Merging upstream version 1.0~rc6.

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

1 files changed, 86 insertions, 28 deletions

diff --git a/doc/zutils.texinfo b/doc/zutils.texinfo
index b847830..af1fd90 100644
--- a/doc/zutils.texinfo
+++ b/doc/zutils.texinfo
@@ -1,12 +1,13 @@
 \input texinfo @c -*-texinfo-*-
 @c %**start of header
 @setfilename zutils.info
+@documentencoding ISO-8859-15
 @settitle Zutils Manual
 @finalout
 @c %**end of header
 
-@set UPDATED 11 January 2011
-@set VERSION 0.9
+@set UPDATED 15 March 2013
+@set VERSION 1.0-rc6
 
 @dircategory Data Compression
 @direntry
@@ -45,7 +46,8 @@ This manual is for Zutils (version @value{VERSION}, @value{UPDATED}).
 @end menu
 
 @sp 1
-Copyright @copyright{} 2008, 2009, 2010, 2011 Antonio Diaz Diaz.
+Copyright @copyright{} 2008, 2009, 2010, 2011, 2012, 2013
+Antonio Diaz Diaz.
 
 This manual is free documentation: you have unlimited permission
 to copy, distribute and modify it.
@@ -59,13 +61,18 @@ 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
 used. Compressed files are decompressed on the fly; no temporary files
-are created. These utilities are not wrapper scripts but safer and more
-efficient C++ programs. In particular the @samp{--recursive} option is
-very efficient in those utilities supporting it.
+are created.
+
+These utilities are not wrapper scripts but safer and more efficient C++
+programs. In particular the @samp{--recursive} option is very efficient
+in those utilities supporting it.
 
 @noindent
 The provided utilities are zcat, zcmp, zdiff, zgrep and ztest.@*
-The supported compressors are bzip2, gzip, lzip and xz.
+The supported formats are bzip2, gzip, lzip and xz.
+
+Zcat, zcmp, zdiff, and zgrep are improved replacements for the shell
+scripts provided with GNU gzip. Ztest is unique to zutils.
 
 @sp 1
 Numbers given as arguments to options (positions, sizes) may be followed
@@ -94,10 +101,12 @@ Zcat copies each given file (@samp{-} means standard input), to standard
 output. If any given file is compressed, its uncompressed 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 compressors. If no files are specified,
-data is read from standard input, decompressed if needed, and sent to
-standard output. Data read from standard input must be of the same type;
-all uncompressed or all compressed with the same compressor.
+corresponding to the supported formats.
+
+If no files are specified, data is read from standard input,
+decompressed if needed, and sent to standard output. Data read from
+standard input must be of the same type; all uncompressed or all in the
+same compression format.
 
 The format for running zcat is:
 
@@ -135,6 +144,11 @@ Equivalent to @samp{-vE}.
 @itemx --show-ends
 Print a @samp{$} after the end of each line.
 
+@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,
+the exact file name must be given. Other names won't be tried.
+
 @item -n
 @itemx --number
 Number all output lines, starting with 1. The line count is unlimited.
@@ -187,16 +201,22 @@ zcmp [@var{options}] @var{file1} [@var{file2}]
 @end example
 
 @noindent
-Compares @var{file1} to @var{file2}. If @var{file2} is omitted zcmp
-tries the following:@*
+This compares @var{file1} to @var{file2}. If @var{file2} is omitted zcmp
+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}).@*
+@var{file1}).
+@item
 If @var{file1} is not compressed, compares @var{file1} to the
 uncompressed contents of @var{file1}.[bz2|gz|lz|xz] (the first one that
-is found).@*
+is found).
+@item
 If no suitable file is found, compares @var{file1} to data read from
 standard input.
+@end enumerate
 
 @noindent
 An exit status of 0 means no differences were found, 1 means some
@@ -219,6 +239,14 @@ Print the differing bytes. Print control bytes as a @samp{^} followed by
 a letter, and precede bytes larger than 127 with @samp{M-} (which stands
 for "meta").
 
+@item --format=[@var{fmt1}][,@var{fmt2}]
+Force the given compression formats. Any of @var{fmt1} or @var{fmt2} may
+be omitted and the corresponding format will be automatically detected.
+Valid values for @var{fmt} are @samp{bz2}, @samp{gz}, @samp{lz} and
+@samp{xz}. If at least one format is specified with this option, the
+exact file names of both @var{file1} and @var{file2} must be given.
+Other names won't be tried.
+
 @item -i @var{size}
 @itemx --ignore-initial=@var{size}
 Ignore any differences in the first @var{size} bytes of the input files.
@@ -265,16 +293,22 @@ zdiff [@var{options}] @var{file1} [@var{file2}]
 @end example
 
 @noindent
-Compares @var{file1} to @var{file2}. If @var{file2} is omitted zdiff
-tries the following:@*
+This compares @var{file1} to @var{file2}. If @var{file2} is omitted
+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}).@*
+@var{file1}).
+@item
 If @var{file1} is not compressed, compares @var{file1} to the
 uncompressed contents of @var{file1}.[bz2|gz|lz|xz] (the first one that
-is found).@*
+is found).
+@item
 If no suitable file is found, compares @var{file1} to data read from
 standard input.
+@end enumerate
 
 @noindent
 An exit status of 0 means no differences were found, 1 means some
@@ -318,6 +352,14 @@ Try hard to find a smaller set of changes.
 @itemx --ignore-tab-expansion
 Ignore changes due to tab expansion.
 
+@item --format=[@var{fmt1}][,@var{fmt2}]
+Force the given compression formats. Any of @var{fmt1} or @var{fmt2} may
+be omitted and the corresponding format will be automatically detected.
+Valid values for @var{fmt} are @samp{bz2}, @samp{gz}, @samp{lz} and
+@samp{xz}. If at least one format is specified with this option, the
+exact file names of both @var{file1} and @var{file2} must be given.
+Other names won't be tried.
+
 @item -i
 @itemx --ignore-case
 Ignore case differences in file contents.
@@ -365,10 +407,12 @@ on any combination of compressed and non-compressed files. If any given
 file is compressed, its uncompressed 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 compressors. If no files are specified, data is read from
-standard input, decompressed if needed, and fed to grep. Data read from
-standard input must be of the same type; all uncompressed or all
-compressed with the same compressor.
+supported formats.
+
+If no files are specified, data is read from standard input,
+decompressed if needed, and fed to grep. Data read from standard input
+must be of the same type; all uncompressed or all in the same
+compression format.
 
 The format for running zgrep is:
 
@@ -430,9 +474,15 @@ Obtain patterns from @var{file}, one per line.
 @itemx --fixed-strings
 Treat @var{pattern} as a set of newline-separated strings.
 
+@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,
+the exact file name must be given. Other names won't be tried.
+
 @item -h
 @itemx --no-filename
-Suppress the prefixing filename on output.
+Suppress the prefixing of filenames on output when multiple files are
+searched.
 
 @item -H
 @itemx --with-filename
@@ -502,7 +552,10 @@ Match only whole lines.
 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 compressed with the same compressor.
+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.
 
 The format for running ztest is:
 
@@ -511,9 +564,9 @@ ztest [@var{options}] [@var{files}]
 @end example
 
 @noindent
-The exit status is 0 if all files verify OK, 1 for environmental
-problems (file not found, invalid flags, I/O errors, etc), 2 to indicate
-a corrupt or invalid input file.
+The exit status is 0 if all compressed files verify OK, 1 if
+environmental problems (file not found, invalid flags, I/O errors, etc),
+2 if any compressed file is corrupt or invalid.
 
 Ztest supports the following options:
 
@@ -526,6 +579,11 @@ Print an informative help message describing the options and exit.
 @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,
+all files not in the given format will fail.
+
 @item -q
 @itemx --quiet
 Quiet operation. Suppress all messages.