Subject: Re: bug#43107: Errors in man pages
From: Paul Eggert <[email-masked]>
To: Helge Kreutzmann <[email-masked]>
Cc: [email-masked]
Date: Mon, 31 Aug 2020 16:14:17 -0700
List-Id: <debbugs-submit.debbugs.gnu.org>

On 8/31/20 12:13 PM, Helge Kreutzmann wrote:
> But, actually, personally I would not change it, I think the previous
> order looks better.

OK, let's leave that alone then.

The remaining proposed changes are to use bold rather than italics for command 
names so I installed the attached to do that. Closing the bug report.
From fb36f55604205660a3517302999c7336d8f7da5e Mon Sep 17 00:00:00 2001
From: Paul Eggert <[email-masked]>
Date: Mon, 31 Aug 2020 16:11:02 -0700
Subject: [PATCH] doc: prefer bold to italics for command names

---
 gzexe.1  |  28 ++++++-----
 gzip.1   | 146 +++++++++++++++++++++++++++++--------------------------
 zdiff.1  |  30 ++++++------
 zforce.1 |  12 +++--
 zgrep.1  |  17 ++++---
 zless.1  |  12 +++--
 zmore.1  |  38 +++++++++------
 znew.1   |  10 ++--
 8 files changed, 164 insertions(+), 129 deletions(-)

diff --git a/gzexe.1 b/gzexe.1
index 01ad9ad..75213d0 100644
--- a/gzexe.1
+++ b/gzexe.1
@@ -6,7 +6,7 @@ gzexe \- compress executable files in place
 .I "name .\|.\|."
 .SH DESCRIPTION
 The
-.I  gzexe
+.B gzexe
 utility allows you to compress executables in place and have them
 automatically uncompress and execute when you run them (at a penalty
 in performance).  For example if you execute ``gzexe /usr/bin/gdb'' it
@@ -31,21 +31,23 @@ gzip(1), znew(1), zmore(1), zcmp(1), zforce(1)
 The compressed executable is a shell script.  This may create some
 security holes.  In particular, the compressed executable relies
 on the PATH environment variable to find
-.I gzip
+.B gzip
 and some standard utilities
-.RI ( basename ,
-.IR chmod ,
-.IR ln ,
-.IR mkdir ,
-.IR mktemp ,
-.IR rm ,
-.IR sleep ,
+.RB ( basename ,
+.BR chmod ,
+.BR ln ,
+.BR mkdir ,
+.BR mktemp ,
+.BR rm ,
+.BR sleep ,
 and
-.IR tail ).
+.BR tail ).
 .SH "BUGS"
-.I gzexe
+The
+.B gzexe
+command
 attempts to retain the original file attributes on the compressed executable,
 but you may have to fix them manually in some cases, using
-.I chmod
+.B chmod
 or
-.IR chown .
+.BR chown .
diff --git a/gzip.1 b/gzip.1
index 19e0fe3..0029934 100644
--- a/gzip.1
+++ b/gzip.1
@@ -24,7 +24,9 @@ gzip, gunzip, zcat \- compress or expand files
 .I "name \&..."
 ]
 .SH DESCRIPTION
-.I Gzip
+The
+.B gzip
+command
 reduces the size of the named files using Lempel-Ziv coding (LZ77).
 Whenever possible,
 each file is replaced by one with the extension
@@ -35,14 +37,18 @@ while keeping the same ownership modes, access and modification times.
 for MSDOS, OS/2 FAT, Windows NT FAT and Atari.)
 If no files are specified, or if a file name is "-", the standard input is
 compressed to the standard output.
-.I Gzip
+The
+.B gzip
+command
 will only attempt to compress regular files.
 In particular, it will ignore symbolic links.
 .PP
 If the compressed file name is too long for its file system,
-.I gzip
+.B gzip
 truncates it.
-.I Gzip
+The
+.B gzip
+command
 attempts to truncate only the parts of the file name longer than 3 characters.
 (A part is delimited by dots.) If the name consists of small parts only,
 the longest parts are truncated. For example, if file names are limited
@@ -51,7 +57,7 @@ Names are not truncated on systems which do not have a limit on file name
 length.
 .PP
 By default,
-.I gzip
+.B gzip
 keeps the original file name and timestamp in the compressed file. These
 are used when decompressing the file with the
 .B \-N
@@ -59,21 +65,21 @@ option. This is useful when the compressed file name was truncated or
 when the timestamp was not preserved after a file transfer.
 .PP
 Compressed files can be restored to their original form using
-.I gzip -d
+.B "gzip -d"
 or
-.I gunzip
+.B gunzip
 or
-.IR zcat .
+.BR zcat .
 If the original name saved in the compressed file is not suitable for its
 file system, a new name is constructed from the original one to make it
 legal.
 .PP
-.I gunzip
+.B gunzip
 takes a list of files on its command line and replaces each
 file whose name ends with .gz, -gz, .z, -z, or _z (ignoring case)
 and which begins with the correct magic number with an uncompressed
 file without the original extension.
-.I gunzip
+.B gunzip
 also recognizes the special extensions
 .B "\&.tgz"
 and
@@ -84,80 +90,84 @@ and
 .B "\&.tar.Z"
 respectively.
 When compressing,
-.I gzip
+.B gzip
 uses the
 .B "\&.tgz"
 extension if necessary instead of truncating a file with a
 .B "\&.tar"
 extension.
 .PP
-.I gunzip
+.B gunzip
 can currently decompress files created by
-.IR gzip ,
-.IR zip ,
-.IR compress ,
-.I "compress -H"
+.BR gzip ,
+.BR zip ,
+.BR compress ,
+.B "compress -H"
 or
-.IR pack .
+.BR pack .
 The detection of the input format is automatic.  When using
 the first two formats,
-.I gunzip
+.B gunzip
 checks a 32 bit CRC. For
-.I pack
+.B pack
 and
-.I gunzip
+.B gunzip
 checks the uncompressed length. The standard
-.I compress
+.B compress
 format was not designed to allow consistency checks. However
-.I gunzip
+.B gunzip
 is sometimes able to detect a bad .Z file. If you get an error
 when uncompressing a .Z file, do not assume that the .Z file is
 correct simply because the standard
-.I uncompress
+.B uncompress
 does not complain. This generally means that the standard
-.I uncompress
+.B uncompress
 does not check its input, and happily generates garbage output.
 The SCO compress -H format (lzh compression method) does not include a CRC
 but also allows some consistency checks.
 .PP
 Files created by
-.I zip
+.B zip
 can be uncompressed by gzip only if they have a single member compressed
 with the 'deflation' method. This feature is only intended to help
 conversion of tar.zip files to the tar.gz format.  To extract a
-.I zip
+.B zip
 file with a single member, use a command like
-.I "gunzip <foo.zip"
+.B "gunzip <foo.zip"
 or
-.IR "gunzip -S .zip foo.zip" .
+.BR "gunzip -S .zip foo.zip" .
 To extract zip files
 with several members, use
-.I unzip
+.B unzip
 instead of
-.IR gunzip .
+.BR gunzip .
 .PP
-.I zcat
+The
+.B zcat
+command
 is identical to
-.I gunzip
+.B gunzip
 .BR \-c .
 (On some systems,
-.I zcat
+.B zcat
 may be installed as
-.I gzcat
+.B gzcat
 to preserve the original link to
-.IR compress .)
-.I zcat
+.BR compress .)
+.B zcat
 uncompresses either a list of files on the command line or its
 standard input and writes the uncompressed data on standard output.
-.I zcat
+.B zcat
 will uncompress files that have the correct magic number whether
 they have a
 .B "\&.gz"
 suffix or not.
 .PP
-.I Gzip
+The
+.B gzip
+command
 uses the Lempel-Ziv algorithm used in
-.I zip
+.B zip
 and PKZIP.
 The amount of compression obtained depends on the size of the
 input and the distribution of common substrings.
@@ -165,18 +175,18 @@ Typically, text such as source code or English
 is reduced by 60\-70%.
 Compression is generally much better than that achieved by
 LZW (as used in
-.IR compress ),
+.BR compress ),
 Huffman coding (as used in
-.IR pack ),
+.BR pack ),
 or adaptive Huffman coding
-.RI ( compact ).
+.RB ( compact ).
 .PP
 Compression is always performed, even if the compressed file is
 slightly larger than the original. The worst case expansion is
 a few bytes for the gzip file header, plus 5 bytes every 32K block,
 or an expansion ratio of 0.015% for large files. Note that the actual
 number of used disk blocks almost never increases.
-.I gzip
+.B gzip
 preserves the mode, ownership and timestamps of files when compressing
 or decompressing.
 .SH OPTIONS
@@ -200,17 +210,17 @@ Force compression or decompression even if the file has multiple links
 or the corresponding file already exists, or if the compressed data
 is read from or written to a terminal. If the input data is not in
 a format recognized by
-.IR gzip ,
+.BR gzip ,
 and if the option --stdout is also given, copy the input data without change
 to the standard output: let
-.I zcat
+.B zcat
 behave as
-.IR cat .
+.BR cat .
 If
 .B \-f
 is not given,
 and when not running in the background,
-.I gzip
+.B gzip
 prompts to verify whether an existing file should be overwritten.
 .TP
 .B \-h --help
@@ -253,7 +263,7 @@ the title and totals lines are not displayed.
 .TP
 .B \-L --license
 Display the
-.I gzip
+.B gzip
 license and quit.
 .TP
 .B \-n --no-name
@@ -261,7 +271,7 @@ When compressing, do not save the original file name and timestamp by
 default. (The original name is always saved if the name had to be
 truncated.) When decompressing, do not restore the original file name
 if present (remove only the
-.I gzip
+.B gzip
 suffix from the compressed file name) and do not restore the original
 timestamp if present (copy it from the compressed file). This option
 is the default when decompressing.
@@ -279,10 +289,10 @@ Suppress all warnings.
 .B \-r --recursive
 Travel the directory structure recursively. If any of the file names
 specified on the command line are directories,
-.I gzip
+.B gzip
 will descend into the directory and compress all the files it finds there
 (or decompress them in the case of
-.I gunzip
+.B gunzip
 ).
 .TP
 .B \-S .suf   --suffix .suf
@@ -296,7 +306,7 @@ suffixes to try, when deriving an output file name from an input file name.
 .TP
 .B --synchronous
 Use synchronous output.  With this option,
-.I gzip
+.B gzip
 is less likely to lose data during a system crash, but it can be
 considerably slower.
 .TP
@@ -312,7 +322,7 @@ Version. Display the version number and compilation options then quit.
 .TP
 .B \-# --fast --best
 Regulate the speed of compression using the specified digit
-.IR # ,
+.BR # ,
 where
 .B \-1
 or
@@ -333,7 +343,7 @@ Normally, after a change is made to any file in the archive, the compression alg
 With this option, rsync can transfer only the changed files as well as a small amount of metadata that is required to update the archive structure in the area that was changed.
 .SH "ADVANCED USAGE"
 Multiple compressed files can be concatenated. In this case,
-.I gunzip
+.B gunzip
 will extract all members at once. For example:
 
       gzip -c file1  > foo.gz
@@ -376,18 +386,18 @@ replacement.
 The obsolescent environment variable
 .B GZIP
 can hold a set of default options for
-.IR gzip .
+.BR gzip .
 These options are interpreted first and can be overwritten by explicit
 command line parameters.  As this can cause problems when using
 scripts, this feature is supported only for options that are
 reasonably likely to not cause too much harm, and
-.I gzip
+.B gzip
 warns if it is used.
 This feature will be removed in a future release of
-.IR gzip .
+.BR gzip .
 .PP
 You can use an alias or script instead.  For example, if
-.I gzip
+.B gzip
 is in the directory
 .B /usr/bin
 you can prepend
@@ -405,13 +415,13 @@ containing the following:
 znew(1), zcmp(1), zmore(1), zforce(1), gzexe(1), zip(1), unzip(1), compress(1)
 .PP
 The
-.I gzip
+.B gzip
 file format is specified in P. Deutsch, \s-1GZIP\s0 file format
 specification version 4.3,
 .BR <https://www.ietf.org/rfc/rfc1952.txt> ,
 Internet RFC 1952 (May 1996).
 The
-.I zip
+.B zip
 deflation format is specified in P. Deutsch, \s-1DEFLATE\s0 Compressed
 Data Format Specification version 1.3,
 .BR <https://www.ietf.org/rfc/rfc1951.txt> ,
@@ -425,7 +435,7 @@ Invalid options were specified on the command line.
 .TP
 \fIfile\fP\^: not in gzip format
 The file specified to
-.I gunzip
+.B gunzip
 has not been compressed.
 .TP
 \fIfile\fP\^: Corrupt input. Use zcat to recover some data.
@@ -435,10 +445,10 @@ can be recovered using
       zcat \fIfile\fP > recover
 .TP
 \fIfile\fP\^: compressed with \fIxx\fP bits, can only handle \fIyy\fP bits
-.I File
+.B File
 was compressed (using LZW) by a program that could deal with
 more
-.I bits
+bits
 than the decompress code on this machine.
 Recompress the file with gzip, which compresses better and uses
 less memory.
@@ -467,7 +477,7 @@ left unaltered.
 .TP
 -- has \fIxx\fP other links: unchanged
 The input file has links; it is left unchanged.  See
-.IR ln "(1)"
+.BR ln "(1)"
 for more information. Use the
 .B \-f
 flag to force compression of multiply-linked files.
@@ -475,9 +485,9 @@ flag to force compression of multiply-linked files.
 When writing compressed data to a tape, it is generally necessary to
 pad the output with zeroes up to a block boundary. When the data is
 read and the whole block is passed to
-.I gunzip
+.B gunzip
 for decompression,
-.I gunzip
+.B gunzip
 detects that there is extra trailing garbage after the compressed data
 and emits a warning by default.  You can use the --quiet option to
 suppress the warning.
@@ -495,9 +505,9 @@ compressed file is on a non seekable media.
 
 In some rare cases, the --best option gives worse compression than
 the default compression level (-6). On some highly redundant files,
-.I compress
+.B compress
 compresses better than
-.IR gzip .
+.BR gzip .
 .SH "REPORTING BUGS"
 Report bugs to: bug\[email-masked]
 .br
diff --git a/zdiff.1 b/zdiff.1
index 0c826c3..037b582 100644
--- a/zdiff.1
+++ b/zdiff.1
@@ -10,39 +10,41 @@ zcmp, zdiff \- compare compressed files
 [ diff_options ] file1
 [ file2 ]
 .SH DESCRIPTION
-.I  Zcmp
+The
+.B zcmp
 and
-.I zdiff
+.B zdiff
+commands
 are used to invoke the
-.I cmp
+.B cmp
 or the
-.I diff
+.B diff
 program on files compressed via
-.IR gzip "."
+.BR gzip "."
 All options specified are passed directly to
-.I cmp
+.B cmp
 or
-.IR diff "."
+.BR diff "."
 If only
 .I file1
 is specified, it is compared to the uncompressed contents of
-.IR file1 ".gz."
+.IB file1 ".gz" .
 If two files are specified, their contents (uncompressed if necessary) are fed to
-.I cmp
+.B cmp
 or
-.IR diff "."
+.BR diff "."
 The input files are not modified.
 The exit status from
-.I cmp
+.B cmp
 or
-.I diff
+.B diff
 is preserved.
 .SH "SEE ALSO"
 cmp(1), diff(1), zmore(1), zgrep(1), znew(1), zforce(1), gzip(1), gzexe(1)
 .SH BUGS
 Messages from the
-.I cmp
+.B cmp
 or
-.I diff
+.B diff
 programs may refer to file names such as "\-" instead of to the file
 names specified.
diff --git a/zforce.1 b/zforce.1
index 37c6aba..508686f 100644
--- a/zforce.1
+++ b/zforce.1
@@ -5,11 +5,15 @@ zforce \- force a '.gz' extension on all gzip files
 .B zforce
 [ name ...  ]
 .SH DESCRIPTION
-.I  zforce
-forces a .gz extension on all
-.I gzip
+The
+.B zforce
+command
+forces a
+.B .gz
+extension on all
+.B gzip
 files so that
-.I gzip
+.B gzip
 will not compress them twice.
 This can be useful for files with names truncated after a file transfer.
 On systems with a 14 char limitation on file names, the original name
diff --git a/zgrep.1 b/zgrep.1
index dfcf21e..6ca2457 100644
--- a/zgrep.1
+++ b/zgrep.1
@@ -7,28 +7,29 @@ zgrep \- search possibly compressed files for a regular expression
 .BI  [\ -e\ ] " pattern"
 .IR filename ".\|.\|."
 .SH DESCRIPTION
-.I Zgrep
-invokes
-.I grep
+The
+.B zgrep
+command invokes
+.B grep
 on compressed or gzipped files.
 All options specified are passed directly to
-.IR grep .
+.BR grep .
 If no file is specified, then the standard input is decompressed
 if necessary and fed to grep.
 Otherwise the given files are uncompressed if necessary and fed to
-.IR grep .
+.BR grep .
 .PP
 If the GREP environment variable is set,
-.I zgrep
+.B zgrep
 uses it as the
-.I grep
+.B grep
 program to be invoked.
 .SH "EXIT STATUS"
 Exit status is 0 for a match, 1 for no matches, and 2 if trouble.
 .SH BUGS
 .PP
 The following
-.I grep
+.B grep
 options are not supported:
 .B --dereference-recursive
 .RB ( \-R ),
diff --git a/zless.1 b/zless.1
index cedbc4d..d41c0c3 100644
--- a/zless.1
+++ b/zless.1
@@ -5,22 +5,26 @@ zless \- file perusal filter for crt viewing of compressed text
 .B zless
 [ name ...  ]
 .SH DESCRIPTION
-.I  Zless
+The
+.B zless
+command
 is a filter which allows examination of compressed or plain text files
 one screenful at a time on a soft-copy terminal.  It is the equivalent of
 setting the environment variable LESSOPEN to '|gzip -cdfq -- %s',
 and the environment variable LESSMETACHARS to
 \&'<space><tab><newline>;*?"()<>[|&^`#\e$%=~',
 and then running
-.IR less .
+.BR less .
 However, enough people seem to think that having the
 command
-.I zless
+.B zless
 available is important to be worth providing it.
 .SH "SEE ALSO"
 zmore(1), less(1)
 .SH "BUGS"
-.I Zless
+The
+.B zless
+command
 does not work with compressed data that is piped to it via standard
 input; it requires that input files be specified as arguments.
 To read compressed data from a pipe, you can use
diff --git a/zmore.1 b/zmore.1
index e2ff835..a5559e0 100644
--- a/zmore.1
+++ b/zmore.1
@@ -5,28 +5,36 @@ zmore \- file perusal filter for crt viewing of compressed text
 .B zmore
 [ name ...  ]
 .SH DESCRIPTION
-.I  Zmore
+The
+.I zmore
+command
 is a filter which allows examination of compressed or plain text files
 one screenful at a time on a soft-copy terminal.
-.I zmore
+The
+.B zmore
+command
 works on files compressed with
-.IR compress ,
-.I pack
+.BR compress ,
+.B pack
 or
-.IR gzip ,
+.BR gzip ,
 and also on uncompressed files.
 If a file does not exist,
-.I zmore
+.B zmore
 looks for a file of the same name with the addition of a .gz, .z or .Z suffix.
 .PP
-.I Zmore
+The
+.B zmore
+command
 normally pauses after each screenful, printing --More--
 at the bottom of the screen.
 If the user then types a carriage return, one more line is displayed.
 If the user hits a space,
 another screenful is displayed.  Other possibilities are enumerated later.
 .PP
-.I Zmore
+The
+.B zmore
+command
 looks in the file
 .I /etc/termcap
 to determine terminal characteristics,
@@ -34,12 +42,12 @@ and to determine the default window size.
 On a terminal capable of displaying 24 lines,
 the default window size is 22 lines.
 To use a pager other than the default
-.IR more ,
+.BR more ,
 set environment variable PAGER to the name of the desired program, such as
-.IR less .
+.BR less .
 .PP
 Other sequences which may be typed when
-.I zmore
+.B zmore
 pauses, and their effects, are as follows (\fIi\fP is an optional integer
 argument, defaulting to 1) :
 .PP
@@ -104,7 +112,9 @@ In addition, the user may hit the erase character to redisplay the
 .PP
 At any time when output is being sent to the terminal, the user can
 hit the quit key (normally control\-\\).
-.I Zmore
+The
+.I zmore
+command
 will stop sending output, and will display the usual --More--
 prompt.
 The user may then enter one of the above commands in the normal manner.
@@ -119,9 +129,9 @@ What you type will thus not show on your terminal, except for the / and !
 commands.
 .PP
 If the standard output is not a teletype, then
-.I zmore
+.B zmore
 acts just like
-.IR zcat ,
+.BR zcat ,
 except that a header is printed before each file
 if there is more than one file.
 .SH FILES
diff --git a/znew.1 b/znew.1
index ffd3c91..6451ff3 100644
--- a/znew.1
+++ b/znew.1
@@ -5,7 +5,9 @@ znew \-   recompress .Z files to .gz files
 .B znew
 [ -ftv9PK] [ name.Z ...  ]
 .SH DESCRIPTION
-.I  Znew
+The
+.B Znew
+command
 recompresses files from .Z (compress) format to .gz (gzip) format.
 If you want to recompress a file already in gzip format, rename the file
 to force a .Z extension then apply znew.
@@ -35,13 +37,13 @@ gzip(1), zmore(1), zdiff(1), zgrep(1), zforce(1), gzexe(1), compress(1)
 If the
 .B \-P
 option is used,
-.I znew
+.B znew
 does not maintain the timestamp if
-.IR touch (1)
+.BR touch (1)
 does not support the
 .B \-r
 option, and does not maintain permissions if
-.IR chmod (1)
+.BR chmod (1)
 does not support the
 .B \-\-reference
 option.
-- 
2.17.1