maint: update copyrights for 2013 and as per current GNU standards

[chaz/tar] / doc / tar.texi

diff --git a/doc/tar.texi b/doc/tar.texi
index 48e8c3cc002a57f0f5a5e9893f7b578088febc75..4a49282c60e7f609eb3f475a302cacabab9c6e08 100644 (file)
--- a/doc/tar.texi
+++ b/doc/tar.texi
@@ -13,9 +13,9 @@
 @c Maintenance notes:
 @c  1. Pay attention to @FIXME{}s and @UNREVISED{}s
 @c  2. Before creating final variant:
 @c Maintenance notes:
 @c  1. Pay attention to @FIXME{}s and @UNREVISED{}s
 @c  2. Before creating final variant:

-@c    2.1. Run `make check-options' to make sure all options are properly
+@c    2.1. Run 'make check-options' to make sure all options are properly

 @c         documented;
 @c         documented;

-@c    2.2. Run `make master-menu' (see comment before the master menu).
+@c    2.2. Run 'make master-menu' (see comment before the master menu).

 
 @include rendition.texi
 @include value.texi
 
 @include rendition.texi
 @include value.texi


@@ -36,21 +36,20 @@ This manual is for @acronym{GNU} @command{tar} (version
 @value{VERSION}, @value{UPDATED}), which creates and extracts files
 from archives.
 
 @value{VERSION}, @value{UPDATED}), which creates and extracts files
 from archives.
 

-Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001,
-2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
+Copyright @copyright{} 1992, 1994--1997, 1999--2001, 2003--2013 Free
+Software Foundation, Inc.

 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or

-any later version published by the Free Software Foundation; with no
-Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'',
-and with the Back-Cover Texts as in (a) below.  A copy of the license
-is included in the section entitled ``GNU Free Documentation
-License''.
+any later version published by the Free Software Foundation; with the
+Invariant Sections being ``GNU General Public License'', with the
+Front-Cover Texts being ``A GNU Manual'', and with the Back-Cover Texts
+as in (a) below.  A copy of the license is included in the section
+entitled ``GNU Free Documentation License''.

 
 (a) The FSF's Back-Cover Text is: ``You have the freedom to
 
 (a) The FSF's Back-Cover Text is: ``You have the freedom to

-copy and modify this GNU manual.  Buying copies from the FSF
-supports it in developing GNU and promoting software freedom.''
+copy and modify this GNU manual.''

 @end quotation
 @end copying
 
 @end quotation
 @end copying
 


@@ -1438,7 +1437,7 @@ example:
 @smallexample
 @group
 $ @kbd{tar --create --verbose --file archive /etc/mail}
 @smallexample
 @group
 $ @kbd{tar --create --verbose --file archive /etc/mail}

-tar: Removing leading `/' from member names
+tar: Removing leading '/' from member names

 /etc/mail/
 /etc/mail/sendmail.cf
 /etc/mail/aliases
 /etc/mail/
 /etc/mail/sendmail.cf
 /etc/mail/aliases


@@ -1881,6 +1880,7 @@ The other operations of @command{tar} (@option{--list},
 @option{--extract}, @option{--compare}, and @option{--update})
 will act on the entire contents of the archive.
 
 @option{--extract}, @option{--compare}, and @option{--update})
 will act on the entire contents of the archive.
 

+@anchor{exit status}

 @cindex exit status
 @cindex return status
 Besides successful exits, @GNUTAR{} may fail for
 @cindex exit status
 @cindex return status
 Besides successful exits, @GNUTAR{} may fail for


@@ -2362,8 +2362,9 @@ exist in the archive. @xref{update}.
 @itemx -P
 
 Normally when creating an archive, @command{tar} strips an initial
 @itemx -P
 
 Normally when creating an archive, @command{tar} strips an initial

-@samp{/} from member names.  This option disables that behavior.
-@xref{absolute}.
+@samp{/} from member names, and when extracting from an archive @command{tar}
+treats names specially if they have initial @samp{/} or internal
+@samp{..}.  This option disables that behavior.  @xref{absolute}.

 
 @opsummary{after-date}
 @item --after-date
 
 @opsummary{after-date}
 @item --after-date


@@ -2758,7 +2759,7 @@ Ignore exit codes of subprocesses. @xref{Writing to an External Program}.
 @item --ignore-failed-read
 
 Do not exit unsuccessfully merely because an unreadable file was encountered.
 @item --ignore-failed-read
 
 Do not exit unsuccessfully merely because an unreadable file was encountered.

-@xref{Reading}.
+@xref{Ignore Failed Read}.

 
 @opsummary{ignore-zeros}
 @item --ignore-zeros
 
 @opsummary{ignore-zeros}
 @item --ignore-zeros


@@ -2811,7 +2812,10 @@ when extracting files from an archive.
 @item --keep-old-files
 @itemx -k
 
 @item --keep-old-files
 @itemx -k
 

-Do not overwrite existing files when extracting files from an archive.
+Do not overwrite existing files when extracting files from an
+archive.  Return error if such files exist.  See also
+@ref{--skip-old-files}.
+

 @xref{Keep Old Files}.
 
 @opsummary{label}
 @xref{Keep Old Files}.
 
 @opsummary{label}


@@ -3264,6 +3268,20 @@ the archive creation operations it instructs @command{tar} to list the
 member names stored in the archive, as opposed to the actual file
 names.  @xref{listing member and file names}.
 
 member names stored in the archive, as opposed to the actual file
 names.  @xref{listing member and file names}.
 

+@opsummary{skip-old-files}
+@item --skip-old-files
+
+Do not overwrite existing files when extracting files from an
+archive.  @xref{Keep Old Files}.
+
+This option differs from @option{--keep-old-files} in that it does not
+treat such files as an error, instead it just silently avoids
+overwriting them.
+
+The @option{--warning=existing-file} option can be used together with
+this option to produce warning messages about existing old files
+(@pxref{warnings}).
+

 @opsummary{sparse}
 @item --sparse
 @itemx -S
 @opsummary{sparse}
 @item --sparse
 @itemx -S


@@ -3572,8 +3590,7 @@ successfully.  For example, @w{@samp{tar --version}} might print:
 
 @smallexample
 tar (GNU tar) @value{VERSION}
 
 @smallexample
 tar (GNU tar) @value{VERSION}

-Copyright (C) 2010 Free Software Foundation, Inc.
-Copyright (C) 2010 Free Software Foundation, Inc.
+Copyright (C) 2013 Free Software Foundation, Inc.

 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
 This is free software: you are free to change and redistribute it.
 There is NO WARRANTY, to the extent permitted by law.
 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
 This is free software: you are free to change and redistribute it.
 There is NO WARRANTY, to the extent permitted by law.


@@ -4150,17 +4167,17 @@ Disable all warning messages.
 @item symlink-cast
 @samp{Attempting extraction of symbolic links as hard links}
 @kwindex unknown-cast
 @item symlink-cast
 @samp{Attempting extraction of symbolic links as hard links}
 @kwindex unknown-cast

-@cindex @samp{Unknown file type `%c', extracted as normal file}, warning message
+@cindex @samp{Unknown file type '%c', extracted as normal file}, warning message

 @item unknown-cast
 @item unknown-cast

-@samp{%s: Unknown file type `%c', extracted as normal file}
+@samp{%s: Unknown file type '%c', extracted as normal file}

 @kwindex ignore-newer
 @cindex @samp{Current %s is newer or same age}, warning message
 @item ignore-newer
 @samp{Current %s is newer or same age}
 @kwindex unknown-keyword
 @kwindex ignore-newer
 @cindex @samp{Current %s is newer or same age}, warning message
 @item ignore-newer
 @samp{Current %s is newer or same age}
 @kwindex unknown-keyword

-@cindex @samp{Ignoring unknown extended header keyword `%s'}, warning message
+@cindex @samp{Ignoring unknown extended header keyword '%s'}, warning message

 @item unknown-keyword
 @item unknown-keyword

-@samp{Ignoring unknown extended header keyword `%s'}
+@samp{Ignoring unknown extended header keyword '%s'}

 @kwindex decompress-program
 @item decompress-program
 Controls verbose description of failures occurring when trying to run
 @kwindex decompress-program
 @item decompress-program
 Controls verbose description of failures occurring when trying to run


@@ -4439,11 +4456,11 @@ in the archive; the most recently archived members will be extracted
 last.  Additionally, an extracted member will @emph{replace} a file of
 the same name which existed in the directory already, and @command{tar}
 will not prompt you about this@footnote{Unless you give it
 last.  Additionally, an extracted member will @emph{replace} a file of
 the same name which existed in the directory already, and @command{tar}
 will not prompt you about this@footnote{Unless you give it

-@option{--keep-old-files} option, or the disk copy is newer than
-the one in the archive and you invoke @command{tar} with
-@option{--keep-newer-files} option.}.  Thus, only the most recently archived
-member will end up being extracted, as it will replace the one
-extracted before it, and so on.
+@option{--keep-old-files} (or @option{--skip-old-files}) option, or
+the disk copy is newer than the one in the archive and you invoke
+@command{tar} with @option{--keep-newer-files} option.}.  Thus, only
+the most recently archived member will end up being extracted, as it
+will replace the one extracted before it, and so on.

 
 @cindex extracting @var{n}th copy of the file
 @xopindex{occurrence, described}
 
 @cindex extracting @var{n}th copy of the file
 @xopindex{occurrence, described}


@@ -4937,7 +4954,7 @@ For example:
 
 @smallexample
 $ @kbd{tar -c -f archive.tar -v --mtime=yesterday .}
 
 @smallexample
 $ @kbd{tar -c -f archive.tar -v --mtime=yesterday .}

-tar: Option --mtime: Treating date `yesterday' as 2006-06-20
+tar: Option --mtime: Treating date 'yesterday' as 2006-06-20

 13:06:29.152478
 @dots{}
 @end smallexample
 13:06:29.152478
 @dots{}
 @end smallexample


@@ -5134,10 +5151,25 @@ such a directory, use the @option{--no-overwrite-dir} option.
 @cindex Overwriting old files, prevention
 @xopindex{keep-old-files, introduced}
 To be even more cautious and prevent existing files from being replaced, use
 @cindex Overwriting old files, prevention
 @xopindex{keep-old-files, introduced}
 To be even more cautious and prevent existing files from being replaced, use

-the @option{--keep-old-files} (@option{-k}) option.  It causes @command{tar} to refuse
-to replace or update a file that already exists, i.e., a file with the
-same name as an archive member prevents extraction of that archive
-member.  Instead, it reports an error.
+the @option{--keep-old-files} (@option{-k}) option.  It causes
+@command{tar} to refuse to replace or update a file that already
+exists, i.e., a file with the same name as an archive member prevents
+extraction of that archive member.  Instead, it reports an error.  For
+example:
+
+@example
+$ @kbd{ls}
+blues
+$ @kbd{tar -x -k -f archive.tar}
+tar: blues: Cannot open: File exists
+tar: Exiting with failure status due to previous errors
+@end example
+
+@xopindex{skip-old-files, introduced}
+If you wish to preserve old files untouched, but don't want
+@command{tar} to treat them as errors, use the
+@option{--skip-old-files} option.  This option causes @command{tar} to
+silently skip extracting over existing files.

 
 @xopindex{overwrite, introduced}
 To be more aggressive about altering existing files, use the
 
 @xopindex{overwrite, introduced}
 To be more aggressive about altering existing files, use the


@@ -5203,16 +5235,24 @@ archive, but remove other files before extracting.
 @node Keep Old Files
 @unnumberedsubsubsec Keep Old Files
 
 @node Keep Old Files
 @unnumberedsubsubsec Keep Old Files
 

+@GNUTAR{} provides two options to control its actions in a situation
+when it is about to extract a file which already exists on disk.
+

 @table @option
 @opindex keep-old-files
 @item --keep-old-files
 @itemx -k
 @table @option
 @opindex keep-old-files
 @item --keep-old-files
 @itemx -k

-Do not replace existing files from archive.  The
-@option{--keep-old-files} (@option{-k}) option prevents @command{tar}
-from replacing existing files with files with the same name from the
-archive. The @option{--keep-old-files} option is meaningless with
-@option{--list} (@option{-t}).  Prevents @command{tar} from replacing
-files in the file system during extraction.
+Do not replace existing files from archive.  When such a file is
+encountered, @command{tar} issues an error message.  Upon end of
+extraction, @command{tar} exits with code 2 (@pxref{exit status}).
+
+@item --skip-old-files
+Do not replace existing files from archive, but do not treat that
+as error.  Such files are silently skipped and do not affect
+@command{tar} exit status.
+
+Additional verbosity can be obtained using @option{--warning=existing-file}
+together with that option (@pxref{warnings}).

 @end table
 
 @node Keep Newer Files
 @end table
 
 @node Keep Newer Files


@@ -6907,7 +6947,7 @@ When @command{tar} is invoked with @option{--create} (@option{-c}),
 @group
 $ @kbd{tar cf a.tar}
 tar: Cowardly refusing to create an empty archive
 @group
 $ @kbd{tar cf a.tar}
 tar: Cowardly refusing to create an empty archive

-Try `tar --help' or `tar --usage' for more information.
+Try 'tar --help' or 'tar --usage' for more information.

 @end group
 @end smallexample
 
 @end group
 @end smallexample
 


@@ -7798,7 +7838,7 @@ $ @kbd{tar tf arch.tar --quoting-style=escape}
 Control characters, single quote and backslash are printed using
 backslash notation.  All names are quoted using left and right
 quotation marks, appropriate to the current locale.  If it does not
 Control characters, single quote and backslash are printed using
 backslash notation.  All names are quoted using left and right
 quotation marks, appropriate to the current locale.  If it does not

-define quotation marks, use @samp{`} as left and @samp{'} as right
+define quotation marks, use @samp{'} as left and as right

 quotation marks.  Any occurrences of the right quotation mark in a
 name are escaped with @samp{\}, for example:
 
 quotation marks.  Any occurrences of the right quotation mark in a
 name are escaped with @samp{\}, for example:
 


@@ -7807,13 +7847,13 @@ For example:
 @smallexample
 @group
 $ @kbd{tar tf arch.tar --quoting-style=locale}
 @smallexample
 @group
 $ @kbd{tar tf arch.tar --quoting-style=locale}

-`./'
-`./a space'
-`./a\'single\'quote'
-`./a"double"quote'
-`./a\\backslash'
-`./a\ttab'
-`./a\nnewline'
+'./'
+'./a space'
+'./a\'single\'quote'
+'./a"double"quote'
+'./a\\backslash'
+'./a\ttab'
+'./a\nnewline'

 @end group
 @end smallexample
 
 @end group
 @end smallexample
 


@@ -8260,7 +8300,7 @@ ensure he is using the right date.  For example:
 @smallexample
 @group
 $ @kbd{tar -c -f archive.tar --after-date='10 days ago' .}
 @smallexample
 @group
 $ @kbd{tar -c -f archive.tar --after-date='10 days ago' .}

-tar: Option --after-date: Treating date `10 days ago' as 2006-06-11
+tar: Option --after-date: Treating date '10 days ago' as 2006-06-11

 13:19:37.232434
 @end group
 @end smallexample
 13:19:37.232434
 @end group
 @end smallexample


@@ -8535,6 +8575,10 @@ is not, generally speaking, the same as the one you'd get running
 scripts for comparing both outputs.  @xref{listing member and file names},
 for the information on how to handle this case.}.
 
 scripts for comparing both outputs.  @xref{listing member and file names},
 for the information on how to handle this case.}.
 

+Symbolic links containing @file{..} or leading @samp{/} can also cause
+problems when extracting, so @command{tar} normally extracts them last;
+it may create empty files as placeholders during extraction.
+

 If you use the @option{--absolute-names} (@option{-P}) option,
 @command{tar} will do none of these transformations.
 
 If you use the @option{--absolute-names} (@option{-P}) option,
 @command{tar} will do none of these transformations.
 


@@ -8558,7 +8602,7 @@ to transfer files between systems.}
 @table @option
 @item --absolute-names
 Preserves full file names (including superior directory names) when
 @table @option
 @item --absolute-names
 Preserves full file names (including superior directory names) when

-archiving files.  Preserves leading slash when extracting files.
+archiving and extracting files.

 
 @end table
 
 
 @end table
 


@@ -8881,39 +8925,30 @@ etc.) and remote files as well as on normal files; data to or from
 such devices or remote files is reblocked by another copy of the
 @command{tar} program to enforce the specified (or default) record
 size.  The default compression parameters are used.  Most compression
 such devices or remote files is reblocked by another copy of the
 @command{tar} program to enforce the specified (or default) record
 size.  The default compression parameters are used.  Most compression

-programs allow to override these by setting a program-specific
-environment variable.  For example, when using @command{gzip} you can
-use @env{GZIP} as in the example below:
+programs let you override these by setting a program-specific
+environment variable.  For example, with @command{gzip} you can set
+@env{GZIP}:

 
 @smallexample
 
 @smallexample

-$ @kbd{GZIP=--best tar czf archive.tar.gz subdir}
+$ @kbd{GZIP='-9 -n' tar czf archive.tar.gz subdir}

 @end smallexample
 
 @noindent
 @end smallexample
 
 @noindent

-Another way would be to use the @option{-I} option instead (see
-below), e.g.:
+The traditional way to do this is to use a pipe:

 
 @smallexample
 
 @smallexample

-$ @kbd{tar -cf archive.tar.gz -I 'gzip --best' subdir}
-@end smallexample
-
-@noindent
-Finally, the third, traditional, way to achieve the same result is to
-use pipe:
-
-@smallexample
-$ @kbd{tar cf - subdir | gzip --best -c - > archive.tar.gz}
+$ @kbd{tar cf - subdir | gzip -9 -n > archive.tar.gz}

 @end smallexample
 
 @cindex corrupted archives
 @end smallexample
 
 @cindex corrupted archives

-About corrupted compressed archives: compressed files have no
-redundancy, for maximum compression.  The adaptive nature of the
+Compressed archives are easily corrupted, because compressed files
+have little redundancy.  The adaptive nature of the

 compression scheme means that the compression tables are implicitly
 spread all over the archive.  If you lose a few blocks, the dynamic
 construction of the compression tables becomes unsynchronized, and there
 is little chance that you could recover later in the archive.
 
 compression scheme means that the compression tables are implicitly
 spread all over the archive.  If you lose a few blocks, the dynamic
 construction of the compression tables becomes unsynchronized, and there
 is little chance that you could recover later in the archive.
 

-Another compression options provide a better control over creating
+Other compression options provide better control over creating

 compressed archives.  These are:
 
 @table @option
 compressed archives.  These are:
 
 @table @option


@@ -8948,13 +8983,12 @@ suffix.  The following suffixes are recognized:
 Use external compression program @var{prog}.  Use this option if you
 are not happy with the compression program associated with the suffix
 at compile time or if you have a compression program that @GNUTAR{}
 Use external compression program @var{prog}.  Use this option if you
 are not happy with the compression program associated with the suffix
 at compile time or if you have a compression program that @GNUTAR{}

-does not support.  There are two requirements to which @var{prog}
-should comply:
+does not support.  The program should follow two conventions:

 
 

-First, when called without options, it should read data from standard
+First, when invoked without options, it should read data from standard

 input, compress it and output it on standard output.
 
 input, compress it and output it on standard output.
 

-Secondly, if called with @option{-d} argument, it should do exactly
+Secondly, if invoked with the @option{-d} option, it should do exactly

 the opposite, i.e., read the compressed data from the standard input
 and produce uncompressed data on the standard output.
 @end table
 the opposite, i.e., read the compressed data from the standard input
 and produce uncompressed data on the standard output.
 @end table


@@ -9436,7 +9470,7 @@ produces the following diagnostics:
 
 @smallexample
 $ tar -c -f ../archive.tar -l jeden
 
 @smallexample
 $ tar -c -f ../archive.tar -l jeden

-tar: Missing links to `jeden'.
+tar: Missing links to 'jeden'.

 @end smallexample
 
 Although creating special records for hard links helps keep a faithful
 @end smallexample
 
 Although creating special records for hard links helps keep a faithful


@@ -9448,7 +9482,7 @@ archive created in previous examples produces, in the absense of file
 
 @smallexample
 $ tar xf archive.tar ./one
 
 @smallexample
 $ tar xf archive.tar ./one

-tar: ./one: Cannot hard link to `./jeden': No such file or directory
+tar: ./one: Cannot hard link to './jeden': No such file or directory

 tar: Error exit delayed from previous errors
 @end smallexample
 
 tar: Error exit delayed from previous errors
 @end smallexample
 


@@ -9988,8 +10022,8 @@ run mode is enabled by @option{-n} command line argument:
 @group
 $ @kbd{xsparse -n /home/gray/GNUSparseFile.6058/sparsefile}
 Reading v.1.0 sparse map
 @group
 $ @kbd{xsparse -n /home/gray/GNUSparseFile.6058/sparsefile}
 Reading v.1.0 sparse map

-Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to
-`/home/gray/sparsefile'
+Expanding file '/home/gray/GNUSparseFile.6058/sparsefile' to
+'/home/gray/sparsefile'

 Finished dry run
 @end group
 @end smallexample
 Finished dry run
 @end group
 @end smallexample


@@ -10010,8 +10044,8 @@ similar to that from the dry run mode, use @option{-v} option:
 @group
 $ @kbd{xsparse -v /home/gray/GNUSparseFile.6058/sparsefile}
 Reading v.1.0 sparse map
 @group
 $ @kbd{xsparse -v /home/gray/GNUSparseFile.6058/sparsefile}
 Reading v.1.0 sparse map

-Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to
-`/home/gray/sparsefile'
+Expanding file '/home/gray/GNUSparseFile.6058/sparsefile' to
+'/home/gray/sparsefile'

 Done
 @end group
 @end smallexample
 Done
 @end group
 @end smallexample


@@ -10032,8 +10066,8 @@ Found variable GNU.sparse.minor = 0
 Found variable GNU.sparse.name = sparsefile
 Found variable GNU.sparse.realsize = 217481216
 Reading v.1.0 sparse map
 Found variable GNU.sparse.name = sparsefile
 Found variable GNU.sparse.realsize = 217481216
 Reading v.1.0 sparse map

-Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to
-`/home/gray/sparsefile'
+Expanding file '/home/gray/GNUSparseFile.6058/sparsefile' to
+'/home/gray/sparsefile'

 Done
 @end group
 @end smallexample
 Done
 @end group
 @end smallexample


@@ -10135,7 +10169,7 @@ Found variable GNU.sparse.size = 217481216
 Found variable GNU.sparse.numblocks = 208
 Found variable GNU.sparse.name = sparsefile
 Found variable GNU.sparse.map = 0,2048,1050624,2048,@dots{}
 Found variable GNU.sparse.numblocks = 208
 Found variable GNU.sparse.name = sparsefile
 Found variable GNU.sparse.map = 0,2048,1050624,2048,@dots{}

-Expanding file `GNUSparseFile.28124/sparsefile' to `sparsefile'
+Expanding file 'GNUSparseFile.28124/sparsefile' to 'sparsefile'

 Done
 @end group
 @end smallexample
 Done
 @end group
 @end smallexample


@@ -10449,9 +10483,8 @@ want to use.  @command{tar} calls @command{rmt} by running an
 @command{rsh} or @command{remsh} to the remote machine, optionally
 using a different login name if one is supplied.
 
 @command{rsh} or @command{remsh} to the remote machine, optionally
 using a different login name if one is supplied.
 

-A copy of the source for the remote tape server is provided.  It is
-Copyright @copyright{} 1983 by the Regents of the University of
-California, but can be freely distributed.  It is compiled and
+A copy of the source for the remote tape server is provided.  Its
+source code can be freely distributed.  It is compiled and

 installed by default.
 
 @cindex absolute file names
 installed by default.
 
 @cindex absolute file names


@@ -11257,7 +11290,7 @@ is@footnote{If you run @GNUTAR{} under a different locale, the
 translation to the locale's language will be used.}:
 
 @smallexample
 translation to the locale's language will be used.}:
 
 @smallexample

-Prepare volume #@var{n} for `@var{archive}' and hit return:
+Prepare volume #@var{n} for '@var{archive}' and hit return:

 @end smallexample
 
 @noindent
 @end smallexample
 
 @noindent


@@ -11393,7 +11426,10 @@ archive being created (as given by @option{--file} option) and
 
 @smallexample
 @group
 
 @smallexample
 @group

-#! /bin/sh
+#! /bin/bash
+# For this script it's advisable to use a shell, such as Bash,
+# that supports a TAR_FD value greater than 9.
+

 echo Preparing volume $TAR_VOLUME of $TAR_ARCHIVE.
 
 name=`expr $TAR_ARCHIVE : '\(.*\)-.*'`
 echo Preparing volume $TAR_VOLUME of $TAR_ARCHIVE.
 
 name=`expr $TAR_ARCHIVE : '\(.*\)-.*'`


@@ -11626,7 +11662,7 @@ you will get:
 @smallexample
 @group
 $ @kbd{tar -rf archive --label 'My volume' .}
 @smallexample
 @group
 $ @kbd{tar -rf archive --label 'My volume' .}

-tar: Archive not labeled to match `My volume'
+tar: Archive not labeled to match 'My volume'

 @end group
 @end smallexample
 
 @end group
 @end smallexample
 


@@ -11936,11 +11972,16 @@ lets the archive overwrite any file in your system that you can write,
 the @option{--absolute-names} (@option{-P}) option should be used only
 for trusted archives.
 
 the @option{--absolute-names} (@option{-P}) option should be used only
 for trusted archives.
 

-Conversely, with the @option{--keep-old-files} (@option{-k}) option,
-@command{tar} refuses to replace existing files when extracting; and
-with the @option{--no-overwrite-dir} option, @command{tar} refuses to
-replace the permissions or ownership of already-existing directories.
-These options may help when extracting from untrusted archives.
+Conversely, with the @option{--keep-old-files} (@option{-k}) and
+@option{--skip-old-files} options, @command{tar} refuses to replace
+existing files when extracting.  The difference between the two
+options is that the former treats existing files as errors whereas the
+latter just silently ignores them.
+
+Finally, with the @option{--no-overwrite-dir} option, @command{tar}
+refuses to replace the permissions or ownership of already-existing
+directories.  These options may help when extracting from untrusted
+archives.

 
 @node Live untrusted data
 @subsection Dealing with Live Untrusted Data
 
 @node Live untrusted data
 @subsection Dealing with Live Untrusted Data