From 97c3d5b3da78b39a715451e52265cd0579dd23ab Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Fri, 16 Jun 2023 15:21:24 -0700 Subject: [PATCH] doc: minor tuneup of man page From suggestions by Bjarni Ingli Gislason (bug#64118). --- gzip.1 | 276 ++++++++++++++++++++++++++++++++------------------------- 1 file changed, 155 insertions(+), 121 deletions(-) diff --git a/gzip.1 b/gzip.1 index 22ab88d..657ad0d 100644 --- a/gzip.1 +++ b/gzip.1 @@ -35,8 +35,8 @@ while keeping the same ownership modes, access and modification times. (The default extension is .B "z" 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. +If no files are specified, or if a file name is "\-", +the standard input is compressed to the standard output. The .B gzip command @@ -51,32 +51,33 @@ The 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 -to 14 characters, gzip.msdos.exe is compressed to gzi.msd.exe.gz. +the longest parts are truncated. +For example, if file names are limited to 14 characters, +gzip.msdos.exe is compressed to gzi.msd.exe.gz. Names are not truncated on systems which do not have a limit on file name length. .PP By default, .B gzip -keeps the original file name and timestamp in the compressed file. These -are used when decompressing the file with the +keeps the original file name and timestamp in the compressed file. +These are used when decompressing the file with the .B \-N -option. This is useful when the compressed file name was truncated or +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 -.B "gzip -d" +.B "gzip \-d" or .B gunzip or .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. +file system, a new name is constructed from the original one to make it valid. .PP .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) +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. .B gunzip @@ -102,40 +103,47 @@ can currently decompress files created by .BR gzip , .BR zip , .BR compress , -.B "compress -H" +.B "compress \-H" or .BR pack . -The detection of the input format is automatic. When using -the first two formats, +The detection of the input format is automatic. +When using the first two formats, .B gunzip -checks a 32 bit CRC. For +checks a 32 bit CRC. +For .B pack and .B gunzip -checks the uncompressed length. The standard +checks the uncompressed length. +The standard .B compress -format was not designed to allow consistency checks. However +format was not designed to allow consistency checks. +However .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 +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 .B uncompress -does not complain. This generally means that the standard +does not complain. +This generally means that the standard .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 +The SCO compress \-H format (lzh compression method) does not include a CRC but also allows some consistency checks. .PP Files created by .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 +with the 'deflation' method. +This feature is only intended to help +conversion of tar.zip files to the tar.gz format. +To extract a .B zip file with a single member, use a command like .RB ' "gunzip foo.gz - gzip -c file2 >> foo.gz + gzip \-c file1 > foo.gz + gzip \-c file2 >> foo.gz Then - gunzip -c foo + gunzip \-c foo is equivalent to cat file1 file2 In case of damage to one member of a .gz file, other members can -still be recovered (if the damaged member is removed). However, -you can get better compression by compressing all members at once: +still be recovered (if the damaged member is removed). +However, you can get better compression by compressing all members at once: cat file1 file2 | gzip > foo.gz compresses better than - gzip -c file1 file2 > foo.gz + gzip \-c file1 file2 > foo.gz If you want to recompress concatenated files to get better compression, do: - gzip -cd old.gz | gzip > new.gz + gzip \-cd old.gz | gzip > new.gz If a compressed file consists of several members, the uncompressed -size and CRC reported by the --list option applies to the last member -only. If you need the uncompressed size for all members, you can use: +size and CRC reported by the \-\-list option applies to the last member only. +If you need the uncompressed size for all members, you can use: - gzip -cd file.gz | wc -c + gzip \-cd file.gz | wc \-c If you wish to create a single archive file with multiple members so that members can later be extracted independently, use an archiver -such as tar or zip. GNU tar supports the -z option to invoke gzip -transparently. gzip is designed as a complement to tar, not as a -replacement. +such as tar or zip. +GNU tar supports the \-z option to invoke gzip transparently. +gzip is designed as a complement to tar, not as a replacement. .SH "ENVIRONMENT" The obsolescent environment variable .B GZIP can hold a set of default options for .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 +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 .B gzip warns if it is used. This feature will be removed in a future release of .BR gzip . .PP -You can use an alias or script instead. For example, if +You can use an alias or script instead. +For example, if .B gzip is in the directory .B /usr/bin @@ -441,9 +470,10 @@ Data Format Specification version 1.3, Internet RFC 1951 (May 1996). .SH "DIAGNOSTICS" Exit status is normally 0; -if an error occurs, exit status is 1. If a warning occurs, exit status is 2. +if an error occurs, exit status is 1. +If a warning occurs, exit status is 2. .TP -Usage: gzip [-cdfhklLnNrtvV19] [-S suffix] [file ...] +Usage: gzip [\-cdfhklLnNrtvV19] [\-S suffix] [file ...] Invalid options were specified on the command line. .TP \fIfile\fP\^: not in gzip format @@ -451,9 +481,10 @@ The file specified to .B gunzip has not been compressed. .TP -\fIfile\fP\^: Corrupt input. Use zcat to recover some data. -The compressed file has been damaged. The data up to the point of failure -can be recovered using +\fIfile\fP\^: Corrupt input. +Use zcat to recover some data. +The compressed file has been damaged. +The data up to the point of failure can be recovered using zcat \fIfile\fP > recover .TP @@ -466,7 +497,7 @@ than the decompress code on this machine. Recompress the file with gzip, which compresses better and uses less memory. .TP -\fIfile\fP\^: already has .gz suffix -- unchanged +\fIfile\fP\^: already has .gz suffix \-\- unchanged The file is assumed to be already compressed. Rename the file and try again. .TP @@ -483,30 +514,33 @@ been corrupted. and .BR \-l \.) .TP --- not a regular file or directory: ignored +\-\- not a regular file or directory: ignored When the input file is not a regular file or directory, -(e.g. a symbolic link, socket, FIFO, device file), it is +(e.g., a symbolic link, socket, FIFO, device file), it is left unaltered. .TP --- has \fIxx\fP other links: unchanged -The input file has links; it is left unchanged. See +\-\- has \fIxx\fP other links: unchanged +The input file has links; it is left unchanged. +See .BR ln "(1)" -for more information. Use the +for more information. +Use the .B \-f flag to force compression of multiply-linked files. .SH CAVEATS 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 +pad the output with zeroes up to a block boundary. +When the data is read and the whole block is passed to .B gunzip for decompression, .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. +and emits a warning by default. +You can use the \-\-quiet option to suppress the warning. .SH BUGS -In some rare cases, the --best option gives worse compression than -the default compression level (-6). On some highly redundant files, +In some rare cases, the \-\-best option gives worse compression than +the default compression level (\-6). +On some highly redundant files, .B compress compresses better than .BR gzip . @@ -517,8 +551,8 @@ GNU gzip home page: .br General help using GNU software: .SH "COPYRIGHT NOTICE" -Copyright \(co 1998-1999, 2001-2002, 2012, 2015-2023 Free Software Foundation, -Inc. +Copyright \(co 1998\(en1999, 2001\(en2002, 2012, 2015\(en2023 +Free Software Foundation, Inc. .br Copyright \(co 1992, 1993 Jean-loup Gailly .PP -- 2.40.1