Adding upstream version 1.1~rc2.upstream/1.1_rc2

Signed-off-by: Daniel Baumann <mail@daniel-baumann.ch>

1 files changed, 109 insertions, 70 deletions

diff --git a/doc/zutils.texinfo b/doc/zutils.texinfo
index ed65997..61a8762 100644
--- a/doc/zutils.texinfo
+++ b/doc/zutils.texinfo
@@ -6,8 +6,8 @@
 @finalout
 @c %**end of header
 
-@set UPDATED 31 May 2013
-@set VERSION 1.0
+@set UPDATED 7 July 2013
+@set VERSION 1.1-rc2
 
 @dircategory Data Compression
 @direntry
@@ -36,13 +36,15 @@ This manual is for Zutils (version @value{VERSION}, @value{UPDATED}).
 
 @menu
 * Introduction::        Purpose and features of zutils
+* Common options::      Common options
+* The zutilsrc file::   The zutils configuration file
 * Zcat::                Concatenating compressed files
 * Zcmp::                Comparing compressed files byte by byte
 * Zdiff::               Comparing compressed files line by line
 * Zgrep::               Searching inside compressed files
 * Ztest::               Testing integrity of compressed files
 * Problems::            Reporting bugs
-* Concept Index::       Index of concepts
+* Concept index::       Index of concepts
 @end menu
 
 @sp 1
@@ -58,8 +60,8 @@ to copy, distribute and modify it.
 @cindex introduction
 
 Zutils is a collection of utilities able to deal with any combination of
-compressed and non-compressed files transparently. If any given file,
-including standard input, is compressed, its uncompressed content is
+compressed and uncompressed files transparently. If any given file,
+including standard input, is compressed, its decompressed content is
 used. Compressed files are decompressed on the fly; no temporary files
 are created.
 
@@ -69,7 +71,8 @@ in those utilities supporting it.
 
 @noindent
 The provided utilities are zcat, zcmp, zdiff, zgrep and ztest.@*
-The supported formats are bzip2, gzip, lzip and xz.
+The supported formats are bzip2, gzip, lzip and xz.@*
+The compressor to be used for each format is configurable at runtime.
 
 Zcat, zcmp, zdiff, and zgrep are improved replacements for the shell
 scripts provided with GNU gzip. Ztest is unique to zutils.
@@ -78,6 +81,10 @@ NOTE: Bzip2 and lzip provide well-defined values of exit status, which
 makes them safe to use with zutils. Gzip and xz may return ambiguous
 warning values, making them less reliable backends for zutils.
 
+LANGUAGE NOTE: Uncompressed = not compressed = plain data; it may never
+have been compressed. Decompressed is used to refer to data which has
+undergone the process of decompression.
+
 @sp 1
 Numbers given as arguments to options (positions, sizes) may be followed
 by a multiplier and an optional @samp{B} for "byte".
@@ -97,12 +104,85 @@ Table of SI and binary prefixes (unit multipliers):
 @end multitable
 
 
+@node Common options
+@chapter Common options
+@cindex common options
+
+The following options are available in all the utilities. Rather than
+writing identical descriptions for each of the programs, they are
+described here.
+
+@table @samp
+@item -h
+@itemx --help
+Print an informative help message describing the options and exit. Zgrep
+only supports the @samp{--help} form of this option.
+
+@item -V
+@itemx --version
+Print the version number on the standard output and exit.
+
+@item -N
+@itemx --no-rcfile
+Don't read the runtime configuration file @samp{zutilsrc}.
+
+@item --bz2=@var{command}
+@itemx --gz=@var{command}
+@itemx --lz=@var{command}
+@itemx --xz=@var{command}
+Set program (may include arguments) to be used as (de)compressor for the
+given format. These options override the values set in @file{zutilsrc}.
+The compression program used must meet three requirements:
+
+@enumerate
+@item
+When called with the @samp{-d} option, it must read compressed data from
+the standard input and produce decompressed data on the standard output.
+@item
+If the @samp{-q} option is passed to zutils, the compression program
+must also accept it.
+@item
+It must return 0 if no errors occurred, and a non-zero value otherwise.
+@end enumerate
+
+@end table
+
+
+@node The zutilsrc file
+@chapter The zutilsrc file
+@cindex the zutilsrc file
+
+@file{zutilsrc} is the runtime configuration file for zutils. In it you
+may define the compressor name and options to be used for each format.
+The @file{zutilsrc} file is optional; you do not need to install it in
+order to run zutils.
+
+The compressors specified in the command line override those specified
+in the @file{zutilsrc} file.
+
+You may copy the system @file{zutilsrc} file
+@file{$@{sysconfdir@}/zutilsrc} to @file{$HOME/.zutilsrc} and customize
+these options as you like. The file syntax is fairly obvious (and there
+are further instructions in it):
+
+@enumerate
+@item
+Any line beginning with @samp{#} is a comment line.
+@item
+Each non-comment line defines the command to be used for the given
+format, with the syntax:
+@example
+<format> = <compressor> [options]
+@end example
+where <format> is one of @samp{bz2}, @samp{gz}, @samp{lz} or @samp{xz}.
+@end enumerate
+
 @node Zcat
 @chapter Zcat
 @cindex zcat
 
 Zcat copies each given file (@samp{-} means standard input), to standard
-output. If any given file is compressed, its uncompressed content is
+output. If any given file is compressed, its decompressed content is
 used. If a given file does not exist, and its name does not end with one
 of the known extensions, zcat tries the compressed file names
 corresponding to the supported formats.
@@ -119,19 +199,11 @@ zcat [@var{options}] [@var{files}]
 @end example
 
 @noindent
-Exit status is 0 if no errors occurred, 1 otherwise.
+Exit status is 0 if no errors occurred, non-zero otherwise.
 
 Zcat supports the following options:
 
 @table @samp
-@item -h
-@itemx --help
-Print an informative help message describing the options and exit.
-
-@item -V
-@itemx --version
-Print the version number of zcat on the standard output and exit.
-
 @item -A
 @itemx --show-all
 Equivalent to @samp{-vET}.
@@ -195,7 +267,7 @@ Verbose mode. Show error messages.
 Zcmp compares two files (@samp{-} means standard input), and if they
 differ, tells the first byte and line number where they differ. Bytes
 and lines are numbered starting with 1. If any given file is compressed,
-its uncompressed content is used. Compressed files are decompressed on
+its decompressed content is used. Compressed files are decompressed on
 the fly; no temporary files are created.
 
 The format for running zcmp is:
@@ -210,15 +282,14 @@ tries the following:
 
 @enumerate
 @item
-If @var{file1} is compressed, compares @var{file1} to the file with the
-corresponding decompressed file name (removes the extension from
-@var{file1}).
+If @var{file1} is compressed, compares its decompressed contents with
+the corresponding uncompressed file (the name of @var{file1} with the
+extension removed).
 @item
-If @var{file1} is not compressed, compares @var{file1} to the
-uncompressed contents of @var{file1}.[lz|bz2|gz|xz] (the first one that
-is found).
+If @var{file1} is uncompressed, compares it with the decompressed
+contents of @var{file1}.[lz|bz2|gz|xz] (the first one that is found).
 @item
-If no suitable file is found, compares @var{file1} to data read from
+If no suitable file is found, compares @var{file1} with data read from
 standard input.
 @end enumerate
 
@@ -229,14 +300,6 @@ differences were found, and 2 means trouble.
 Zcmp supports the following options:
 
 @table @samp
-@item -h
-@itemx --help
-Print an informative help message describing the options and exit.
-
-@item -V
-@itemx --version
-Print the version number of zcmp on the standard output and exit.
-
 @item -b
 @itemx --print-bytes
 Print the differing bytes. Print control bytes as a @samp{^} followed by
@@ -286,7 +349,7 @@ files differ.
 
 Zdiff compares two files (@samp{-} means standard input), and if they
 differ, shows the differences line by line. If any given file is
-compressed, its uncompressed content is used. Zdiff is a front end to
+compressed, its decompressed content is used. Zdiff is a front end to
 the diff program and has the limitation that messages from diff refer to
 temporary filenames instead of those specified.
 
@@ -302,15 +365,14 @@ zdiff tries the following:
 
 @enumerate
 @item
-If @var{file1} is compressed, compares @var{file1} to the file with the
-corresponding decompressed file name (removes the extension from
-@var{file1}).
+If @var{file1} is compressed, compares its decompressed contents with
+the corresponding uncompressed file (the name of @var{file1} with the
+extension removed).
 @item
-If @var{file1} is not compressed, compares @var{file1} to the
-uncompressed contents of @var{file1}.[lz|bz2|gz|xz] (the first one that
-is found).
+If @var{file1} is uncompressed, compares it with the decompressed
+contents of @var{file1}.[lz|bz2|gz|xz] (the first one that is found).
 @item
-If no suitable file is found, compares @var{file1} to data read from
+If no suitable file is found, compares @var{file1} with data read from
 standard input.
 @end enumerate
 
@@ -321,14 +383,6 @@ differences were found, and 2 means trouble.
 Zdiff supports the following options:
 
 @table @samp
-@item -h
-@itemx --help
-Print an informative help message describing the options and exit.
-
-@item -V
-@itemx --version
-Print the version number of zdiff on the standard output and exit.
-
 @item -a
 @itemx --text
 Treat all files as text.
@@ -407,8 +461,8 @@ Ignore all white space.
 @cindex zgrep
 
 Zgrep is a front end to the grep program that allows transparent search
-on any combination of compressed and non-compressed files. If any given
-file is compressed, its uncompressed content is used. If a given file
+on any combination of compressed and uncompressed files. If any given
+file is compressed, its decompressed content is used. If a given file
 does not exist, and its name does not end with one of the known
 extensions, zgrep tries the compressed file names corresponding to the
 supported formats.
@@ -431,13 +485,6 @@ matches were found, and 2 means trouble.
 Zgrep supports the following options:
 
 @table @samp
-@item --help
-Print an informative help message describing the options and exit.
-
-@item -V
-@itemx --version
-Print the version number of zgrep on the standard output and exit.
-
 @item -a
 @itemx --text
 Treat all files as text.
@@ -554,9 +601,9 @@ Match only whole lines.
 @cindex ztest
 
 Ztest verifies the integrity of the specified compressed files.
-Non-compressed files are ignored. If no files are specified, the
-integrity of compressed data read from standard input is verified. Data
-read from standard input must be all in the same compression format.
+Uncompressed files are ignored. If no files are specified, the integrity
+of compressed data read from standard input is verified. Data read from
+standard input must be all in the same compression format.
 
 Note that some xz files lack integrity information, and therefore can't
 be verified as reliably as the other formats can.
@@ -575,14 +622,6 @@ environmental problems (file not found, invalid flags, I/O errors, etc),
 Ztest supports the following options:
 
 @table @samp
-@item -h
-@itemx --help
-Print an informative help message describing the options and exit.
-
-@item -V
-@itemx --version
-Print the version number of ztest on the standard output and exit.
-
 @item --format=@var{fmt}
 Force the given compression format. Valid values for @var{fmt} are
 @samp{bz2}, @samp{gz}, @samp{lz} and @samp{xz}. If this option is used,
@@ -619,8 +658,8 @@ If you find a bug in zutils, please send electronic mail to
 find by running @w{@samp{zutils --version}}.
 
 
-@node Concept Index
-@unnumbered Concept Index
+@node Concept index
+@unnumbered Concept index
 
 @printindex cp