Document dumpdir format

[chaz/tar] / doc / tar.texi

diff --git a/doc/tar.texi b/doc/tar.texi
index 221d128c923b194e77445cdccc32653129f9be40..a3a5d2329ed06058daf7928fa6348e962321c13f 100644 (file)
--- a/doc/tar.texi
+++ b/doc/tar.texi
@@ -99,6 +99,7 @@ Appendices
 * Configuring Help Summary::
 * Genfile::
 * Snapshot Files::
+* Dumpdir::
 * Free Software Needs Free Documentation::
 * Copying This Manual::
 * Index of Command Line Options::
@@ -347,6 +348,7 @@ GNU tar internals and development
 
 * Genfile::
 * Snapshot Files::
+* Dumpdir::
 
 Copying This Manual
 
@@ -1013,7 +1015,7 @@ is the operation which creates the new archive
 you give it the name you chose.  The files, @file{blues}, @file{folk},
 and @file{jazz}, are now members of the archive, @file{collection.tar}
 (they are @dfn{file name arguments} to the @option{--create} operation).
-@FIXME{xref here to the discussion of file name args?}Now that they are
+@FIXME-xref{to the discussion of file name args?}Now that they are
 in the archive, they are called @emph{archive members}, not files.
 (@pxref{Definitions,members}).
 
@@ -2990,7 +2992,7 @@ operating on a @command{tar} archive.  @xref{show-omitted-dirs}.
 @itemx --show-stored-names
 
 Display file or member names after applying any transformations
-(@FIXME-pxref{}).  In particular, when used in conjunction with one of
+(@pxref{transform}).  In particular, when used in conjunction with one of
 archive creation operations it instructs tar to list the member names
 stored in the archive, as opposed to the actual file
 names.  @xref{listing member and file names}.
@@ -5303,7 +5305,8 @@ unambiguous for a program: each file name is printed as
 where @var{x} is a letter describing the status of the file: @samp{Y}
 if the file  is present in the archive, @samp{N} if the file is not
 included in the archive, or a @samp{D} if the file is a directory (and
-is included in the archive).@FIXME-xref{dumpdir format}.  Each such
+is included in the archive).  @xref{Dumpdir}, for the detailed
+description of dumpdirs and status codes.  Each such
 line is terminated by a newline character.  The last line is followed
 by an additional newline to indicate the end of the data.
 
@@ -6990,26 +6993,26 @@ Here are several examples of @option{--transform} usage:
 @item Extract @file{usr/} hierarchy into @file{usr/local/}:
 
 @smallexample
-$ @kbd{tar --transform='s,usr/,usr/local/,' -x arch.tar}
+$ @kbd{tar --transform='s,usr/,usr/local/,' -x -f arch.tar}
 @end smallexample
 
 @item Strip two leading directory components (equivalent to
 @option{--strip-components=2}):
 
 @smallexample
-$ @kbd{tar --transform='s,/*[^/]*/[^/]*/,,' -x arch.tar}
+$ @kbd{tar --transform='s,/*[^/]*/[^/]*/,,' -x -f arch.tar}
 @end smallexample
 
 @item Prepend @file{/prefix/}  to each file name:
 
 @smallexample
-$ @kbd{tar --transform 's,^,/prefix/,' -x arch.tar}
+$ @kbd{tar --transform 's,^,/prefix/,' -x -f arch.tar}
 @end smallexample
 
 @item Convert each file name to lower case:
 
 @smallexample
-$ @kbd{tar --transform 's/.*/\L&/' -x arch.tar}
+$ @kbd{tar --transform 's/.*/\L&/' -x -f arch.tar}
 @end smallexample
 
 @end enumerate
@@ -7030,6 +7033,10 @@ To test @option{--transform} effect we suggest to use
 $ @kbd{tar -cf arch.tar --transform='s,^usr/,var/,' \
        --verbose --show-transformed-names /}
 @end smallexample
+
+If both @option{--strip-components} and @option{--transform} are used
+together, then @option{--transform} is applied first, and the required
+number of components is then stripped from its result.
     
 @node after
 @section Operating Only on New Files
@@ -10406,6 +10413,10 @@ Right margin of the text output. Used for wrapping.
 @appendix Format of the Incremental Snapshot Files
 @include snapshot.texi
 
+@node Dumpdir
+@appendix Dumpdir
+@include dumpdir.texi
+
 @node Free Software Needs Free Documentation
 @appendix Free Software Needs Free Documentation
 @include freemanuals.texi