(isotime): Report ??? if localtime returns null.

[chaz/tar] / doc / tar.texi

diff --git a/doc/tar.texi b/doc/tar.texi
index e3ad08f0bd33d78c7fd7b92fcbc517e96994868d..511c4aa6a03f9ee9efcfad3367b5d3fa7f976874 100644 (file)
--- a/doc/tar.texi
+++ b/doc/tar.texi
@@ -131,6 +131,11 @@
 @set xref-blocking-factor @xref{Blocking Factor}
 @set pxref-blocking-factor @pxref{Blocking Factor}
 
+@set op-bzip2 @kbd{--bzip2} (@kbd{-y})
+@set ref-bzip2 @ref{gzip}
+@set xref-bzip2 @xref{gzip}
+@set pxref-bzip2 @pxref{gzip}
+
 @set op-checkpoint @kbd{--checkpoint}
 @set ref-checkpoint @ref{verbose}
 @set xref-checkpoint @xref{verbose}
@@ -459,7 +464,7 @@ END-INFO-DIR-ENTRY
 This file documents GNU @code{tar}, a utility used to store, backup, and
 transport files.
 
-Copyright (C) 1992, 1994, 1995, 1996, 1997, 1999 Free Software Foundation, Inc.
+Copyright 1992, 1994, 1995, 1996, 1997, 1999 Free Software Foundation, Inc.
 
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice
@@ -1630,13 +1635,13 @@ $ @kbd{tar --create --file=foo.tar .}
 @end example
 
 @noindent
-@code{tar} will report @samp{tar: foo.tar is the archive; not dumped}.
+@code{tar} will report @samp{tar: ./foo.tar is the archive; not dumped}.
 This happens because @code{tar} creates the archive @file{foo.tar} in
 the current directory before putting any files into it.  Then, when
 @code{tar} attempts to add all the files in the directory @file{.} to
-the archive, it notices that the file @file{foo.tar} is the same as the
-archive, and skips it.  (It makes no sense to put an archive into
-itself.)  GNU @code{tar} will continue in this case, and create the
+the archive, it notices that the file @file{./foo.tar} is the same as the
+archive @file{foo.tar}, and skips it.  (It makes no sense to put an archive
+into itself.)  GNU @code{tar} will continue in this case, and create the
 archive normally, except for the exclusion of that one file.
 (@emph{Please note:} Other versions of @code{tar} are not so clever;
 they will enter an infinite loop when this happens, so you should not
@@ -2513,6 +2518,12 @@ with the block number in the archive file.  @FIXME-xref{}.
 Sets the blocking factor @code{tar} uses to @var{blocking} x 512 bytes per
 record.  @FIXME-xref{}.
 
+@item --bzip2
+@itemx -y
+
+This option tells @code{tar} to read or write archives through @code{bzip2}.
+@FIXME-xref{}.
+
 @item --checkpoint
 
 This option directs @code{tar} to print periodic checkpoint messages as it
@@ -3069,6 +3080,10 @@ them with the equivalent long option.
 
 @samp{--extract}
 
+@item -y
+
+@samp{--bzip2}
+
 @item -z
 
 @samp{--gzip}
@@ -5333,13 +5348,27 @@ Causes @code{tar} to ignore files that match the @var{pattern}.
 @end table
 
 @findex exclude
-The @value{op-exclude} option will prevent any file or member which
-matches the shell wildcards (@var{pattern}) from being operated on
-(@var{pattern} can be a single file name or a more complex expression).
-For example, if you want to create an archive with all the contents of
-@file{/tmp} except the file @file{/tmp/foo}, you can use the command
-@samp{tar --create --file=arch.tar --exclude=foo}.  A path name is
-excluded if any of its file name components matches @var{pattern}.
+The @value{op-exclude} option prevents any file or member whose name
+matches the shell wildcard (@var{pattern}) from being operated on.
+For example, to create an archive with all the contents of the directory
+@file{src} except for files whose names end in @file{.o}, use the
+command @samp{tar -cf src.tar --exclude='*.o' src}.
+
+A @var{pattern} containing @samp{/} excludes a name if an initial
+subsequence of the name's components matches @var{pattern}; a
+@var{pattern} without @samp{/} excludes a name if it matches any of its
+name components.  For example, the pattern @samp{*b/RCS} contains
+@samp{/}, so it excludes @file{blob/RCS} and @file{.blob/RCS/f} but not
+@file{blob/RCSit/RCS} or @file{/blob/RCS}, whereas the pattern
+@samp{RCS} excludes all these names.  Conversely, the pattern @samp{*.o}
+lacks @samp{/}, so it excludes @file{.f.o}, @file{d/f.o}, and
+@file{d.o/f}.
+
+Other than optionally stripping leading @samp{/} from names
+(@pxref{absolute}), patterns and candidate names are used as-is.  For
+example, trailing @samp{/} is not trimmed from a user-specified name
+before deciding whether to exclude it.
+
 You may give multiple @samp{--exclude} options.
 
 @table @kbd
@@ -5405,14 +5434,14 @@ illegal.  This might not correspond to what you want.
 For example, write:
 
 @example
-$ @kbd{tar -c -f @var{archive.tar} -X '*/tmp/*' @var{directory}}
+$ @kbd{tar -c -f @var{archive.tar} --exclude '*.o' @var{directory}}
 @end example
 
 @noindent
 rather than:
 
 @example
-$ @kbd{tar -c -f @var{archive.tar} -X */tmp/* @var{directory}}
+$ @kbd{tar -c -f @var{archive.tar} --exclude *.o @var{directory}}
 @end example
 
 @item
@@ -5759,7 +5788,8 @@ Do not strip leading slashes from file names.
 @end table
 
 By default, GNU @code{tar} drops a leading @samp{/} on input or output.
-This option turns off this behavior; it is equivalent to changing to the
+This option turns off this behavior.
+Tt is roughly equivalent to changing to the
 root directory before running @code{tar} (except it also turns off the
 usual warning message).
 
@@ -6748,6 +6778,10 @@ loose some compressibility.  But this would have make recovering easier.
 So, there are pros and cons.  We'll see!
 
 @table @kbd
+@item -y
+@itemx --bzip2
+Filter the archive through @code{bzip2}.  Otherwise like @value{op-gzip}.
+
 @item -Z
 @itemx --compress
 @itemx --uncompress
@@ -6780,6 +6814,9 @@ If there is no compress utility available, @code{tar} will report an error.
 @strong{Please note} that the @code{compress} program may be covered by
 a patent, and therefore we recommend you stop using it.
 
+@value{op-bzip2} acts like @value{op-compress}, except that it uses
+the @code{bzip2} utility.
+
 @table @kbd
 @item --compress
 @itemx --uncompress