Merging upstream version 1.14~rc1.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 120 insertions, 52 deletions

diff --git a/doc/zutils.info b/doc/zutils.info
index d7f9cb4..36a94cb 100644
--- a/doc/zutils.info
+++ b/doc/zutils.info
@@ -11,7 +11,7 @@ File: zutils.info,  Node: Top,  Next: Introduction,  Up: (dir)
 Zutils Manual
 *************
 
-This manual is for Zutils (version 1.13, 23 January 2024).
+This manual is for Zutils (version 1.14-rc1, 29 November 2024).
 
 * Menu:
 
@@ -24,6 +24,7 @@ This manual is for Zutils (version 1.13, 23 January 2024).
 * Zgrep::               Searching inside compressed files
 * Ztest::               Testing the integrity of compressed files
 * Zupdate::             Recompressing files to lzip format
+* Argument syntax::     By convention, options start with a hyphen
 * Problems::            Reporting bugs
 * Concept index::       Index of concepts
 
@@ -47,7 +48,7 @@ created. Data format is detected by its identifier string (magic bytes), not
 by the file name extension. Empty files are considered uncompressed.
 
    These utilities are not wrapper scripts but safer and more efficient C++
-programs. In particular the option '--recursive' is very efficient in those
+programs. In particular the option '--recursive' is efficient in those
 utilities supporting it.
 
 The utilities provided are 'zcat', 'zcmp', 'zdiff', 'zgrep', 'ztest', and
@@ -89,10 +90,10 @@ File: zutils.info,  Node: Common options,  Next: Configuration,  Prev: Introduct
 2 Common options
 ****************
 
-The following options: are available in all the utilities. Rather than
+The following options are available in all the utilities. Rather than
 writing identical descriptions for each of the programs, they are described
 here. Remember to prepend './' to any file name beginning with a hyphen, or
-use '--'. *Note Argument syntax: (arg_parser)Argument syntax.
+use '--'. *Note Argument syntax::.
 
 '-h'
 '--help'
@@ -113,7 +114,7 @@ use '--'. *Note Argument syntax: (arg_parser)Argument syntax.
 '--format=FORMAT_LIST'
      Process only the formats listed in the comma-separated FORMAT_LIST.
      Valid formats are 'bz2', 'gz', 'lz', 'xz', 'zst', and 'un' for
-     'uncompressed', meaning "any file name without a known extension".
+     'uncompressed', meaning 'any file name without a known extension'.
      This option excludes files based on extension, instead of format,
      because it is more efficient. The exclusion only applies to names
      generated automatically (for example when adding extensions to a file
@@ -153,7 +154,7 @@ use '--'. *Note Argument syntax: (arg_parser)Argument syntax.
        2. If the option '-q' is passed to zutils, the compression program
           must also accept it.
 
-       3. It must return 0 if no errors occurred, and a non-zero value
+       3. It must return 0 if no errors occurred, and a nonzero value
           otherwise.
 
 
@@ -164,6 +165,7 @@ and may be followed by a multiplier and an optional 'B' for "byte".
    Table of SI and binary prefixes (unit multipliers):
 
 Prefix   Value                      |   Prefix   Value
+----------------------------------------------------------------------
 k        kilobyte   (10^3 = 1000)   |   Ki       kibibyte  (2^10 = 1024)
 M        megabyte   (10^6)          |   Mi       mebibyte  (2^20)
 G        gigabyte   (10^9)          |   Gi       gibibyte  (2^30)
@@ -228,7 +230,7 @@ directory, and nonrecursive searches read standard input.
 
 Exit status is 0 if no errors occurred, 1 otherwise.
 
-   'zcat' supports the following options:
+'zcat' supports the following options:
 
 '-A'
 '--show-all'
@@ -239,6 +241,12 @@ Exit status is 0 if no errors occurred, 1 otherwise.
      Number all nonblank output lines, starting with 1. The line count is
      unlimited.
 
+'-c'
+'--stdout'
+'-d'
+'--decompress'
+     Ignored, for gzip compatibility.
+
 '-e'
      Equivalent to '-vE'.
 
@@ -287,8 +295,8 @@ Exit status is 0 if no errors occurred, 1 otherwise.
 '-v'
 '--show-nonprinting'
      Print control characters except for LF (newline) and TAB using '^'
-     notation and precede characters larger than 127 with 'M-' (which
-     stands for "meta").
+     notation and precede characters larger than 127 with 'M-' (which stands
+     for "meta").
 
 '--verbose'
      Verbose mode. Show error messages. Repeating it increases the verbosity
@@ -321,7 +329,7 @@ until one is found. *Note search-order::.
 An exit status of 0 means no differences were found, 1 means some
 differences were found, and 2 means trouble.
 
-   'zcmp' supports the following options:
+'zcmp' supports the following options:
 
 '-b'
 '--print-bytes'
@@ -356,10 +364,10 @@ differences were found, and 2 means trouble.
      Force the compressed formats given. If FORMAT1 or FORMAT2 is omitted,
      the corresponding format is automatically detected. Valid values for
      FORMAT are 'bz2', 'gz', 'lz', 'xz', 'zst', and 'un' for
-     'uncompressed'. If at least one format is specified with this option,
-     the file is passed to the corresponding decompressor (or transmitted
-     unmodified) without checking its format, and the exact file names of
-     both FILE1 and FILE2 must be given. Other names are not tried.
+     'uncompressed'. If this option is specified, the corresponding file is
+     passed to the decompressor (or transmitted unmodified) without
+     checking its format, and the exact file names of both FILE1 and FILE2
+     must be given. Other names are not tried.
 
 '-q'
 '--quiet'
@@ -409,8 +417,8 @@ remaining formats until one is found. *Note search-order::.
 An exit status of 0 means no differences were found, 1 means some
 differences were found, and 2 means trouble.
 
-   'zdiff' supports the following options (some options only work if the
-diff program used supports them):
+'zdiff' supports the following options (some options only work if the diff
+program used supports them):
 
 '-a'
 '--text'
@@ -449,10 +457,10 @@ diff program used supports them):
      Force the compressed formats given. If FORMAT1 or FORMAT2 is omitted,
      the corresponding format is automatically detected. Valid values for
      FORMAT are 'bz2', 'gz', 'lz', 'xz', 'zst', and 'un' for
-     'uncompressed'. If at least one format is specified with this option,
-     the file is passed to the corresponding decompressor (or transmitted
-     unmodified) without checking its format, and the exact file names of
-     both FILE1 and FILE2 must be given. Other names are not tried.
+     'uncompressed'. If this option is specified, the corresponding file is
+     passed to the decompressor (or transmitted unmodified) without
+     checking its format, and the exact file names of both FILE1 and FILE2
+     must be given. Other names are not tried.
 
 '-p'
 '--show-c-function'
@@ -536,9 +544,9 @@ with a nonzero status because base64 cannot write to its output pipe after
 An exit status of 0 means at least one match was found, 1 means no matches
 were found, and 2 means trouble.
 
-   'zgrep' supports the following options (Some options only work if the
-grep program used supports them. Options -h, -H, -r, -R, and -Z are managed
-by 'zgrep' and not passed to grep):
+'zgrep' supports the following options (Some options only work if the grep
+program used supports them. Options -h, -H, -r, -R, and -Z are managed by
+'zgrep' and not passed to grep):
 
 '-a'
 '--text'
@@ -680,8 +688,8 @@ by 'zgrep' and not passed to grep):
 
 '-U'
 '--binary'
-     Use binary I/O on platforms affected by the bug known as "text mode
-     I/O". (MS-DOS, MS-Windows, OS/2).
+     Use binary I/O on platforms affected by the bug known as 'text mode
+     I/O'. (MS-DOS, MS-Windows, OS/2).
 
 '-v'
 '--invert-match'
@@ -749,7 +757,7 @@ problems (file not found, invalid command-line options, I/O errors, etc), 2
 if any compressed file is corrupt or invalid, or if any file has an
 incorrect file name extension.
 
-   'ztest' supports the following options:
+'ztest' supports the following options:
 
 '-O FORMAT'
 '--force-format=FORMAT'
@@ -781,7 +789,7 @@ incorrect file name extension.
 
 
 
-File: zutils.info,  Node: Zupdate,  Next: Problems,  Prev: Ztest,  Up: Top
+File: zutils.info,  Node: Zupdate,  Next: Argument syntax,  Prev: Ztest,  Up: Top
 
 9 Zupdate
 *********
@@ -837,19 +845,30 @@ occurred (file not found or not regular, or has invalid format, or can't be
 deleted). 2 if a fatal error occurred (invalid command-line options,
 compressor can't be run, or comparison fails).
 
-   'zupdate' supports the following options:
+'zupdate' supports the following options:
 
 '-d DIR'
 '--destdir=DIR'
      Write recompressed files to another directory, using DIR as base
      directory, instead of writing them in the same directory as the
-     original files. In recursive mode, this is done by replacing each
-     directory specified in the command line with DIR to produce the
-     recompressed file names. For example, 'zupdate -r -d DIR ../a'
-     recompresses a file named '../a/b/c.gz' to 'DIR/b/c.lz'. Regular files
-     specified in the command line are recompressed directly into DIR. For
-     example, 'zupdate -d DIR ../a/b/c.gz' writes the recompressed file to
-     'DIR/c.lz'.
+     original files. This is done by removing the (possibly empty) prefix
+     preceding the last slash (if any) of each FILE specified in the
+     command line, and then prepending DIR to produce the recompressed file
+     names.
+
+     In recursive mode, if FILE ends with a slash and names a directory, it
+     is completely replaced with DIR. Therefore, if FILE ends with a slash,
+     all the files in FILE are recompressed directly into DIR, but if FILE
+     does not end with a slash, the files in FILE are recompressed into the
+     subdirectory DIR/`basename( FILE )`. 'FILE/' is thus equivalent to
+     'FILE/*', but without the danger of exceeding the length limit of the
+     command line.
+
+     For example, 'zupdate -r -d DIR ../a' recompresses the file
+     '../a/b.gz' to 'DIR/a/b.lz', while 'zupdate -r -d DIR ../a/'
+     recompresses the same file to 'DIR/b.lz'. Regular files specified in
+     the command line are recompressed directly into DIR. For example,
+     'zupdate -d DIR ../a/b.gz' writes the recompressed file to 'DIR/b.lz'.
 
      This option allows recompressing files from a read-only file system to
      another place without the need to copy or link them to the destination
@@ -925,9 +944,56 @@ compressor can't be run, or comparison fails).
 
 
 
-File: zutils.info,  Node: Problems,  Next: Concept index,  Prev: Zupdate,  Up: Top
+File: zutils.info,  Node: Argument syntax,  Next: Problems,  Prev: Zupdate,  Up: Top
+
+10 Syntax of command-line arguments
+***********************************
+
+POSIX recommends these conventions for command-line arguments.
+
+   * A command-line argument is an option if it begins with a hyphen ('-').
+
+   * Option names are single alphanumeric characters.
+
+   * Certain options require an argument.
+
+   * An option and its argument may or may not appear as separate tokens.
+     (In other words, the whitespace separating them is optional). Thus,
+     '-o foo' and '-ofoo' are equivalent.
+
+   * One or more options without arguments, followed by at most one option
+     that takes an argument, may follow a hyphen in a single token. Thus,
+     '-abc' is equivalent to '-a -b -c'.
+
+   * Options typically precede other non-option arguments.
+
+   * The argument '--' terminates all options; any following arguments are
+     treated as non-option arguments, even if they begin with a hyphen.
+
+   * A token consisting of a single hyphen character is interpreted as an
+     ordinary non-option argument. By convention, it is used to specify
+     standard input, standard output, or a file named '-'.
+
+GNU adds "long options" to these conventions:
+
+   * A long option consists of two hyphens ('--') followed by a name made
+     of alphanumeric characters and hyphens. Option names are typically one
+     to three words long, with hyphens to separate words. Abbreviations can
+     be used for the long option names as long as the abbreviations are
+     unique.
+
+   * A long option and its argument may or may not appear as separate
+     tokens. In the latter case they must be separated by an equal sign '='.
+     Thus, '--foo bar' and '--foo=bar' are equivalent.
+
+The syntax of options with an optional argument is
+'-<short_option><argument>' (without whitespace), or
+'--<long_option>=<argument>'.
+
+
+File: zutils.info,  Node: Problems,  Next: Concept index,  Prev: Argument syntax,  Up: Top
 
-10 Reporting bugs
+11 Reporting bugs
 *****************
 
 There are probably bugs in zutils. There are certainly errors and omissions
@@ -948,6 +1014,7 @@ Concept index
 
 * Menu:
 
+* argument syntax:                       Argument syntax.           (line 6)
 * bugs:                                  Problems.                  (line 6)
 * common options:                        Common options.            (line 6)
 * getting help:                          Problems.                  (line 6)
@@ -964,21 +1031,22 @@ Concept index
 
 Tag Table:
 Node: Top217
-Node: Introduction1152
-Ref: search-order2304
-Node: Common options3461
-Ref: version4027
-Ref: compressor-requirements5978
-Node: Configuration7367
-Node: Zcat8400
-Node: Zcmp11139
-Node: Zdiff14407
-Node: Zgrep17490
-Node: Ztest23637
-Node: Zupdate26430
-Ref: lz-compressor31838
-Node: Problems32539
-Node: Concept index33073
+Node: Introduction1224
+Ref: search-order2371
+Node: Common options3528
+Ref: version4066
+Ref: compressor-requirements6017
+Node: Configuration7476
+Node: Zcat8509
+Node: Zcmp11320
+Node: Zdiff14560
+Node: Zgrep17615
+Node: Ztest23759
+Node: Zupdate26549
+Ref: lz-compressor32564
+Node: Argument syntax33265
+Node: Problems35157
+Node: Concept index35699
 
 End Tag Table