tar: improve quality of diagnostics with incrementals

[chaz/tar] / doc / tar.texi

diff --git a/doc/tar.texi b/doc/tar.texi
index f140b70b523727f98e4ebea00ead0de87ea4ff15..4a49282c60e7f609eb3f475a302cacabab9c6e08 100644 (file)
--- a/doc/tar.texi
+++ b/doc/tar.texi
@@ -36,17 +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, 2011 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, no Front-Cover Texts, and no Back-Cover Texts.
-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
+copy and modify this GNU manual.''

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


@@ -3587,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) 2011 Free Software Foundation, Inc.
-Copyright (C) 2011 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.


@@ -8923,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


@@ -8990,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


@@ -10491,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