Updated

[chaz/tar] / doc / tar.texi

diff --git a/doc/tar.texi b/doc/tar.texi
index 7e052981db8a05ef94e4fa7d4fa8835e4acbbb51..c9c7d81b690972cf461098f074f381bdf5738516 100644 (file)
--- a/doc/tar.texi
+++ b/doc/tar.texi
@@ -201,6 +201,11 @@
 @set xref-exclude-from @xref{exclude}
 @set pxref-exclude-from @pxref{exclude}
 
+@set op-exclude-caches @kbd{--exclude-caches}
+@set ref-exclude-from @ref{exclude-caches}
+@set xref-exclude-from @xref{exclude-caches}
+@set pxref-exclude-from @pxref{exclude-caches}
+
 @set op-extract @kbd{--extract} (@kbd{--get}, @kbd{-x})
 @set ref-extract @ref{extract}
 @set xref-extract @xref{extract}
@@ -493,6 +498,11 @@
 @set xref-volno-file @xref{Using Multiple Tapes}
 @set pxref-volno-file @pxref{Using Multiple Tapes}
 
+@set op-seek @kbd{--seek}
+@set ref-seek @ref{seek}
+@set xref-seek @xref{seek}
+@set pxref-seek @pxref{seek}
+
 @c Put everything in one index (arbitrarily chosen to be the concept index).
 @syncodeindex fn cp
 @syncodeindex ky cp
@@ -2743,6 +2753,11 @@ When performing operations, @command{tar} will skip files that match
 Similar to @samp{--exclude}, except @command{tar} will use the list of
 patterns in the file @var{file}.  @FIXME-xref{}
 
+@item --exclude-caches
+
+Automatically excludes all directories
+containing a cache directory tag.  @FIXME-xref{}
+
 @item --file=@var{archive}
 @itemx -f @var{archive}
 
@@ -2911,6 +2926,14 @@ multi-volume @command{tar} archive.  @FIXME-xref{}
 
 (see --info-script)
 
+@item -n
+@itemx --seek
+
+Assume that the archive media supports seeks to arbitrary
+locations. Usually @command{tar} determines automatically whether
+the archive can be seeked or not. This option is intended for use
+in cases when such recognition fails.
+
 @item --newer=@var{date}
 @itemx --after-date=@var{date}
 @itemx -N
@@ -5289,7 +5312,7 @@ to comparing directories; this is fairly gross, but there does not seem
 to be a better way to go.
 
 @command{tar} doesn't access @var{snapshot-file} when
-@value{op-create} or @value{op-list} are specified, but the
+@value{op-extract} or @value{op-list} are specified, but the
 @value{op-listed-incremental} option must still be given.  A
 placeholder @var{snapshot-file} can be specified, e.g.,
 @file{/dev/null}.
@@ -5764,7 +5787,7 @@ Display program version and exit.
 
 To restore files that were archived using a scripted backup, use the
 @code{restore} script. Its usage is quite straightforward. In the
-simplest form, invoke @command{restore} without options, it will
+simplest form, invoke @code{restore --all}, it will
 then restore all the filesystems and files specified in
 @file{backup-specs} (@pxref{General-Purpose Variables,BACKUP_DIRS}).
 
@@ -5802,6 +5825,10 @@ restore --level=1
 The full list of options accepted by @code{restore} follows:
 
 @table @option
+@item -a
+@itemx --all
+Restore all filesystems and files specified in @file{backup-specs}
+
 @item -l @var{level}
 @itemx --level=@var{level}
 Start restoring from the given backup level, instead of the default 0.
@@ -6140,6 +6167,24 @@ added to the archive.
 @FIXME{do the exclude options files need to have stuff separated by
 newlines the same as the files-from option does?}
 
+@table @kbd
+@item --exclude-caches
+Causes @command{tar} to ignore directories containing a cache directory tag.
+@end table
+
+@findex exclude-caches
+When creating an archive,
+the @samp{--exclude-caches} option
+causes @command{tar} to exclude all directories
+that contain a @dfn{cache directory tag}.
+A cache directory tag is a short file
+with the well-known name @file{CACHEDIR.TAG}
+and having a standard header
+specified in @url{http://www.brynosaurus.com/cachedir/spec.html}.
+Various applications write cache directory tags
+into directories they use to hold regenerable, non-precious data,
+so that such data can be more easily excluded from backups.
+
 @menu
 * controlling pattern-patching with exclude::
 * problems with exclude::
@@ -6576,14 +6621,35 @@ relative to the then current directory, which might not be the same as
 the original current working directory of @command{tar}, due to a previous
 @samp{--directory} option.
 
-@FIXME{dan: does this mean that you *can* use the short option form, but
-you can *not* use the long option form with --files-from?  or is this
-totally screwed?}
-
 When using @samp{--files-from} (@pxref{files}), you can put @samp{-C}
-options in the file list.  Unfortunately, you cannot put
-@samp{--directory} options in the file list.  (This interpretation can
-be disabled by using the @value{op-null} option.)
+options in the file list. Notice, however, that in this case the
+option and its argument must occupy two consecutive lines. For 
+instance, the file list for the above example will be:
+
+@smallexample
+@group
+-C
+/etc
+passwd
+hosts
+-C
+/lib
+libc.a
+@end group
+@end smallexample
+
+@noindent
+To use it, you would invoke @command{tar} as follows:
+
+@smallexample
+$ @kbd{tar -c -f foo.tar --files-from list}
+@end smallexample
+
+Notice also that you can only use the short option variant in the file
+list, i.e. always use @option{-C}, not @option{--directory}.
+
+The interpretation of @value{op-directory} is disabled by
+@value{op-null} option.
 
 @node absolute
 @subsection Absolute File Names
@@ -8647,8 +8713,7 @@ head is on.  Before writing an archive, you should make sure that no
 data on the tape will be overwritten (unless it is no longer needed).
 Before reading an archive, you should make sure the tape head is at
 the beginning of the archive you want to read.  (The @code{restore}
-script will find the archive automatically.  @FIXME{There is no such
-restore script!}@FIXME-xref{Scripted Restoration}@xref{mt}, for
+script will find the archive automatically. @FIXME-xref{Scripted Restoration}@xref{mt}, for
 an explanation of the tape moving utility.
 
 If you want to add new archive file entries to a tape, you should