Merging upstream version 1.14~rc1.

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

1 files changed, 116 insertions, 43 deletions

diff --git a/doc/zutils.texi b/doc/zutils.texi
index 1646e7d..3f523d2 100644
--- a/doc/zutils.texi
+++ b/doc/zutils.texi
@@ -6,8 +6,8 @@
 @finalout
 @c %**end of header
 
-@set UPDATED 23 January 2024
-@set VERSION 1.13
+@set UPDATED 29 November 2024
+@set VERSION 1.14-rc1
 
 @dircategory Compression
 @direntry
@@ -45,6 +45,7 @@ This manual is for Zutils (version @value{VERSION}, @value{UPDATED}).
 * 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
 @end menu
@@ -70,8 +71,8 @@ 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 @option{--recursive} is very efficient in
-those utilities supporting it.
+programs. In particular the option @option{--recursive} is efficient in those
+utilities supporting it.
 
 @noindent
 The utilities provided are @command{zcat}, @command{zcmp}, @command{zdiff},
@@ -116,14 +117,10 @@ the process of decompression.
 @chapter Common options
 @cindex common options
 
-The following
-@uref{http://www.nongnu.org/arg-parser/manual/arg_parser_manual.html#Argument-syntax,,options}:
-are available in all the utilities. Rather than writing identical
-descriptions for each of the programs, they are described here. Remember to
-prepend @file{./} to any file name beginning with a hyphen, or use @samp{--}.
-@ifnothtml
-@xref{Argument syntax,,,arg_parser}.
-@end ifnothtml
+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 @file{./} to any file name beginning with a
+hyphen, or use @samp{--}. @xref{Argument syntax}.
 
 @table @code
 @item -h
@@ -146,8 +143,8 @@ compressors used must support the option @option{-V} for this to work).
 @itemx --format=@var{format_list}
 Process only the formats listed in the comma-separated @var{format_list}.
 Valid formats are @samp{bz2}, @samp{gz}, @samp{lz}, @samp{xz}, @samp{zst},
-and @samp{un} for @samp{uncompressed}, meaning "any file name without a
-known extension". This option excludes files based on extension, instead of
+and @samp{un} for @samp{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 name
 or when operating recursively on directories). Files given in the command
@@ -192,7 +189,7 @@ standard output.
 If the option @option{-q} 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.
+It must return 0 if no errors occurred, and a nonzero value otherwise.
 @end enumerate
 
 @end table
@@ -204,7 +201,7 @@ and may be followed by a multiplier and an optional @samp{B} for "byte".
 Table of SI and binary prefixes (unit multipliers):
 
 @multitable {Prefix} {kilobyte   (10^3 = 1000)} {|} {Prefix} {kibibyte  (2^10 = 1024)}
-@item Prefix @tab Value               @tab | @tab Prefix @tab Value
+@headitem Prefix @tab Value           @tab | @tab Prefix @tab Value
 @item k @tab kilobyte   (10^3 = 1000) @tab | @tab Ki @tab kibibyte  (2^10 = 1024)
 @item M @tab megabyte   (10^6)        @tab | @tab Mi @tab mebibyte  (2^20)
 @item G @tab gigabyte   (10^9)        @tab | @tab Gi @tab gibibyte  (2^30)
@@ -278,6 +275,7 @@ zcat [@var{options}] [@var{files}]
 @noindent
 Exit status is 0 if no errors occurred, 1 otherwise.
 
+@noindent
 @command{zcat} supports the following options:
 
 @table @code
@@ -290,6 +288,12 @@ Equivalent to @option{-vET}.
 Number all nonblank output lines, starting with 1. The line count is
 unlimited.
 
+@item -c
+@itemx --stdout
+@itemx -d
+@itemx --decompress
+Ignored, for gzip compatibility.
+
 @item -e
 Equivalent to @option{-vE}.
 
@@ -339,8 +343,8 @@ Print TAB characters as @samp{^I}.
 @item -v
 @itemx --show-nonprinting
 Print control characters except for LF (newline) and TAB using @samp{^}
-notation and precede characters larger than 127 with @samp{M-} (which
-stands for "meta").
+notation and precede characters larger than 127 with @samp{M-} (which stands
+for "meta").
 
 @item --verbose
 Verbose mode. Show error messages. Repeating it increases the verbosity
@@ -378,6 +382,7 @@ corresponding compressed files of the remaining formats until one is found.
 An exit status of 0 means no differences were found, 1 means some
 differences were found, and 2 means trouble.
 
+@noindent
 @command{zcmp} supports the following options:
 
 @table @code
@@ -414,11 +419,11 @@ Compare at most @var{count} input bytes.
 Force the compressed formats given. If @var{format1} or @var{format2} is
 omitted, the corresponding format is automatically detected. Valid values
 for @var{format} are @samp{bz2}, @samp{gz}, @samp{lz}, @samp{xz},
-@samp{zst}, and @samp{un} for @samp{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 @var{file1} and @var{file2} must be given.
-Other names are not tried.
+@samp{zst}, and @samp{un} for @samp{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 @var{file1} and @var{file2} must be given. Other names are not
+tried.
 
 @item -q
 @itemx --quiet
@@ -473,6 +478,7 @@ corresponding compressed files of the remaining formats until one is found.
 An exit status of 0 means no differences were found, 1 means some
 differences were found, and 2 means trouble.
 
+@noindent
 @command{zdiff} supports the following options (some options only work if
 the diff program used supports them):
 
@@ -513,11 +519,11 @@ Ignore case differences. Consider uppercase and lowercase letters equivalent.
 Force the compressed formats given. If @var{format1} or @var{format2} is
 omitted, the corresponding format is automatically detected. Valid values
 for @var{format} are @samp{bz2}, @samp{gz}, @samp{lz}, @samp{xz},
-@samp{zst}, and @samp{un} for @samp{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 @var{file1} and @var{file2} must be given.
-Other names are not tried.
+@samp{zst}, and @samp{un} for @samp{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 @var{file1} and @var{file2} must be given. Other names are not
+tried.
 
 @item -p
 @itemx --show-c-function
@@ -603,6 +609,7 @@ zgrep [@var{options}] @var{pattern} [@var{files}]
 An exit status of 0 means at least one match was found, 1 means no
 matches were found, and 2 means trouble.
 
+@noindent
 @command{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 @command{zgrep} and not passed to grep):
@@ -750,7 +757,7 @@ stop, so that the alignment of tabs looks normal.
 
 @item -U
 @itemx --binary
-Use binary I/O on platforms affected by the bug known as "text mode I/O".
+Use binary I/O on platforms affected by the bug known as 'text mode I/O'.
 (MS-DOS, MS-Windows, OS/2).
 
 @item -v
@@ -825,6 +832,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.
 
+@noindent
 @command{ztest} supports the following options:
 
 @table @code
@@ -887,11 +895,11 @@ Combining the options @option{--force} and @option{--keep}, as in
 each pair of files in a multiformat set of files.
 
 The names of the original files must have one of the following extensions:@*
-@samp{.bz2}, @samp{.gz}, @samp{.xz}, @samp{.zst}, or @samp{.Z}, which are
-recompressed to @samp{.lz};@*
-@samp{.tbz}, @samp{.tbz2}, @samp{.tgz}, @samp{.txz}, or @samp{.tzst}, which
-are recompressed to @samp{.tlz}.@*
-Keeping the combined extensions @w{(@samp{.tgz} ---> @samp{.tlz})} may be
+@file{.bz2}, @file{.gz}, @file{.xz}, @file{.zst}, or @file{.Z}, which are
+recompressed to @file{.lz};@*
+@file{.tbz}, @file{.tbz2}, @file{.tgz}, @file{.txz}, or @file{.tzst}, which
+are recompressed to @file{.tlz}.@*
+Keeping the combined extensions @w{(@file{.tgz} ---> @file{.tlz})} may be
 useful when recompressing Slackware packages, for example.
 
 Bzip2, gzip, and lzip are the primary formats. Xz and zstd are optional. If
@@ -917,6 +925,7 @@ 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).
 
+@noindent
 @command{zupdate} supports the following options:
 
 @table @code
@@ -924,13 +933,25 @@ compressor can't be run, or comparison fails).
 @itemx --destdir=@var{dir}
 Write recompressed files to another directory, using @var{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 @var{dir} to produce the recompressed file names.
-For example, @w{@samp{zupdate -r -d @var{dir} ../a}} recompresses a file
-named @file{../a/b/c.gz} to @file{@var{dir}/b/c.lz}. Regular files specified
-in the command line are recompressed directly into @var{dir}. For example,
-@w{@samp{zupdate -d @var{dir} ../a/b/c.gz}} writes the recompressed file to
-@file{@var{dir}/c.lz}.
+files. This is done by removing the (possibly empty) prefix preceding the
+last slash (if any) of each @var{file} specified in the command line, and
+then prepending @var{dir} to produce the recompressed file names.
+
+In recursive mode, if @var{file} ends with a slash and names a directory, it
+is completely replaced with @var{dir}. Therefore, if @var{file} ends with a
+slash, all the files in @var{file} are recompressed directly into @var{dir},
+but if @var{file} does not end with a slash, the files in @var{file} are
+recompressed into the subdirectory @w{@var{dir}/`basename( @var{file} )`}.
+@samp{@var{file/}} is thus equivalent to @samp{@var{file/*}}, but without
+the danger of exceeding the length limit of the command line.
+
+For example, @w{@samp{zupdate -r -d @var{dir} ../a}} recompresses the file
+@file{../a/b.gz} to @file{@var{dir}/a/b.lz}, while
+@w{@samp{zupdate -r -d @var{dir} ../a/}} recompresses the same file to
+@file{@var{dir}/b.lz}. Regular files specified in the command line are
+recompressed directly into @var{dir}. For example,
+@w{@samp{zupdate -d @var{dir} ../a/b.gz}} writes the recompressed file to
+@file{@var{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
@@ -939,8 +960,8 @@ read-only files to avoid warnings about files that can't be deleted).
 
 @item -e
 @itemx --expand-extensions
-Expand combined file name extensions; recompress @samp{.tbz}, @samp{.tbz2},
-@samp{.tgz}, @samp{.txz}, and @samp{.tzst} to @samp{tar.lz}.
+Expand combined file name extensions; recompress @file{.tbz}, @file{.tbz2},
+@file{.tgz}, @file{.txz}, and @file{.tzst} to @file{tar.lz}.
 
 @item -f
 @itemx --force
@@ -1011,6 +1032,58 @@ archives by using a command like
 @end table
 
 
+@node Argument syntax
+@chapter Syntax of command-line arguments
+@cindex argument syntax
+
+POSIX recommends these conventions for command-line arguments.
+
+@itemize @bullet
+@item A command-line argument is an option if it begins with a hyphen
+(@samp{-}).
+
+@item Option names are single alphanumeric characters.
+
+@item Certain options require an argument.
+
+@item An option and its argument may or may not appear as separate tokens.
+(In other words, the whitespace separating them is optional).
+Thus, @w{@option{-o foo}} and @option{-ofoo} are equivalent.
+
+@item 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, @option{-abc} is equivalent to @w{@option{-a -b -c}}.
+
+@item Options typically precede other non-option arguments.
+
+@item The argument @samp{--} terminates all options; any following arguments
+are treated as non-option arguments, even if they begin with a hyphen.
+
+@item 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 @samp{-}.
+@end itemize
+
+@noindent
+GNU adds @dfn{long options} to these conventions:
+
+@itemize @bullet
+@item A long option consists of two hyphens (@samp{--}) 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.
+
+@item 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 @samp{=}.
+Thus, @w{@option{--foo bar}} and @option{--foo=bar} are equivalent.
+@end itemize
+
+@noindent
+The syntax of options with an optional argument is
+@option{-<short_option><argument>} (without whitespace), or
+@option{--<long_option>=<argument>}.
+
+
 @node Problems
 @chapter Reporting bugs
 @cindex bugs