please report them to @file{bug-tar@@gnu.org}.
When reporting a bug, please be sure to include as much detail as
-possible, in order to reproduce it. @FIXME{Be more specific, I'd
-like to make this node as detailed as 'Bug reporting' node in Emacs
-manual.}
+possible, in order to reproduce it.
+@FIXME{Be more specific, I'd like to make this node as detailed as
+'Bug reporting' node in Emacs manual.}
@node Tutorial
@chapter Tutorial Introduction to @command{tar}
structure and how files are named according to which directory they are
in. You should understand concepts such as standard output and standard
input, what various definitions of the term @samp{argument} mean, and the
-differences between relative and absolute file names. @FIXME{and what
-else?}
+differences between relative and absolute file names.
+@FIXME{and what else?}
@item
This manual assumes that you are working from your own home directory
@var{name} argument having the value @samp{archive.tar}. The last
example contains only old style option letters (repeating option
@samp{c} twice), not all of which are meaningful (eg., @samp{.},
-@samp{h}, or @samp{i}), with no argument value. @FIXME{not sure i liked
+@samp{h}, or @samp{i}), with no argument value.
+@FIXME{not sure i liked
the first sentence of this paragraph..}
@node All Options
When @command{tar} is performing multi-tape backups, @var{command} is run
at the end of each tape. If it exits with nonzero status,
-@command{tar} fails immediately. @xref{info-script}, for a detailed
+@command{tar} fails immediately. @xref{info-script}, for a detailed
discussion of this feature.
@opsummary{interactive}
performing potentially destructive options, such as overwriting files.
@xref{interactive}.
+@opsummary{--keep-directory-symlink}
+@item --keep-directory-symlink
+
+This option changes the behavior of tar when it encounters a symlink
+with the same name as the directory that it is about to extract. By
+default, in this case tar would first remove the symlink and then
+proceed extracting the directory.
+
+The @option{--keep-directory-symlink} option disables this behavior
+and instructs tar to follow symlinks to directories when extracting
+from the archive.
+
+It is mainly intended to provide compatibility with the Slackware
+installation scripts.
+
@opsummary{keep-newer-files}
@item --keep-newer-files
@noindent
Notice, that this option outputs only one line. The example output
-above has been split to fit page boundaries.
+above has been split to fit page boundaries. @xref{defaults}.
@opsummary{show-omitted-dirs}
@item --show-omitted-dirs
Instructs @command{tar} to mention the directories it is skipping when
operating on a @command{tar} archive. @xref{show-omitted-dirs}.
+@opsummary{show-snapshot-field-ranges}
+@item --show-snapshot-field-ranges
+
+Displays the range of values allowed by this version of @command{tar}
+for each field in the snapshot file, then exits successfully.
+@xref{Snapshot Files}.
+
@opsummary{show-transformed-names}
@opsummary{show-stored-names}
@item --show-transformed-names
This means that @command{tar} first tried to decompress
@file{archive.Z} using @command{compress}, and, when that
failed, switched to @command{gzip}.
+@kwindex record-size
+@cindex @samp{Record size = %lu blocks}, warning message
+@item record-size
+@samp{Record size = %lu blocks}
@end table
@subheading Keywords controlling incremental extraction:
in environment variables, specific to each particular operation. For
example, the @option{--checkpoint-action=exec} option, defines the
@env{TAR_ARCHIVE} variable to the name of the archive being worked
-upon. You can, should the need be, use these variables in the
+upon. You can, should the need be, use these variables in the
command line of the external command. For example:
@smallexample
These variables are defined prior to executing the command, so you can
pass them as arguments, if you prefer. For example, if the command
@var{proc} takes the member name and size as its arguments, then you
-could do:
+could do:
@smallexample
$ @kbd{tar -x -f archive.tar \
@end group
@end smallexample
-@noindent
-@xopindex{directory, using in @option{--files-from} argument}
-Notice that the option parsing algorithm used with @option{-T} is
-stricter than the one used by shell. Namely, when specifying option
-arguments, you should observe the following rules:
-
-@itemize @bullet
-@item
-When using short (single-letter) option form, its argument must
-immediately follow the option letter, without any intervening
-whitespace. For example: @code{-Cdir}.
-
-@item
-When using long option form, the option argument must be separated
-from the option by a single equal sign. No whitespace is allowed on
-any side of the equal sign. For example: @code{--directory=dir}.
-
-@item
-For both short and long option forms, the option argument can be given
-on the next line after the option name, e.g.:
-
-@smallexample
-@group
---directory
-dir
-@end group
-@end smallexample
-
-@noindent
-and
-
-@smallexample
-@group
--C
-dir
-@end group
-@end smallexample
-@end itemize
-
@opindex add-file
If you happen to have a file whose name starts with @samp{-},
precede it with @option{--add-file} option to prevent it from
This example uses short options for typographic reasons, to avoid
very long lines.
-@GNUTAR is able to automatically detect @code{NUL}-terminated file lists, so
-it is safe to use them even without the @option{--null} option. In
-this case @command{tar} will print a warning and continue reading such
-a file as if @option{--null} were actually given:
+@GNUTAR is tries to automatically detect @code{NUL}-terminated file
+lists, so in many cases it is safe to use them even without the
+@option{--null} option. In this case @command{tar} will print a
+warning and continue reading such a file as if @option{--null} were
+actually given:
@smallexample
@group
record size on itself. When this is the case, and a non-standard
record size was used when the archive was created, @command{tar} will
print a message about a non-standard blocking factor, and then operate
-normally. On some tape devices, however, @command{tar} cannot figure
-out the record size itself. On most of those, you can specify a
-blocking factor (with @option{--blocking-factor}) larger than the
-actual blocking factor, and then use the @option{--read-full-records}
-(@option{-B}) option. (If you specify a blocking factor with
-@option{--blocking-factor} and don't use the
-@option{--read-full-records} option, then @command{tar} will not
-attempt to figure out the recording size itself.) On some devices,
-you must always specify the record size exactly with
+normally@footnote{If this message is not needed, you can turn it off
+using the @option{--warning=no-record-size} option.}. On some tape
+devices, however, @command{tar} cannot figure out the record size
+itself. On most of those, you can specify a blocking factor (with
+@option{--blocking-factor}) larger than the actual blocking factor,
+and then use the @option{--read-full-records} (@option{-B}) option.
+(If you specify a blocking factor with @option{--blocking-factor} and
+don't use the @option{--read-full-records} option, then @command{tar}
+will not attempt to figure out the recording size itself.) On some
+devices, you must always specify the record size exactly with
@option{--blocking-factor} when reading, because @command{tar} cannot
figure it out. In any case, use @option{--list} (@option{-t}) before
doing any extractions to see whether @command{tar} is reading the archive