Date: 05 Jan 2003 10:18:32 -0800 From: "Gary W. Swearingen" <swear@attbi.com> To: FreeBSD-gnats-submit@FreeBSD.org Subject: docs/46787: compress(1) manpage missing BUGS; other cleanup. Message-ID: <hjk7hjmpdz.7hj@localhost.localdomain>
next in thread | raw e-mail | index | archive | help
>Number: 46787 >Category: docs >Synopsis: compress(1) manpage missing BUGS; other cleanup. >Confidential: no >Severity: non-critical >Priority: low >Responsible: freebsd-doc >State: open >Quarter: >Keywords: >Date-Required: >Class: doc-bug >Submitter-Id: current-users >Arrival-Date: Sun Jan 05 10:20:04 PST 2003 >Closed-Date: >Last-Modified: >Originator: Gary W. Swearingen >Release: FreeBSD 5.0-CURRENT i386 >Organization: none >Environment: n/a ================ >Description: The compress(1) manpage has several problems: 1) It doesn't explain that the command will delete a file under certain circumstances (see BUGS in patch). 2) It doesn't mention that ".Z" can be assumed by "uncompress" and prevent compression by "compress". 3) The list of options lists only flags. (One flag is missing its argument). 4) The -b description doesn't give the valid values or default. 5) Misc. other poor organization, missing helpful info, etc. ================ >How-To-Repeat: n/a ================ >Fix: The bug should be fixed in code, but I don't want to do it now. The patch fixes the manpage until the code gets fixed. I'll write a no-patch PR on the code after this PR is closed with the code still unfixed. Patch $FreeBSD: src/usr.bin/compress/compress.1,v 1.17 2002/05/29 18:12:21 ru Exp $ --- /tmp/compress..orig.1 Sun Jan 5 06:33:35 2003 +++ /tmp/compress.1 Sun Jan 5 10:02:14 2003 @@ -54,17 +54,17 @@ .Sh DESCRIPTION The .Nm -utility reduces the size of the named files using adaptive Lempel-Ziv coding. +utility attempts to reduce the size of the +named files using adaptive Lempel-Ziv coding. Each .Ar file is renamed to the same name plus the extension .Dq .Z . -As many of the modification time, access time, file flags, file mode, -user ID, and group ID as allowed by permissions are retained in the -new file. -If compression would not reduce the size of a +If attempted compression would not reduce the size of a .Ar file , -the file is ignored. +or if the filename ends with +.Dq .Z , +the file is not compressed. Exceptions are discussed below. .Pp The .Nm uncompress @@ -72,38 +72,53 @@ files by deleting the .Dq .Z extension. +If a specified filename doesn't end with +.Dq .Z , +one will be assumed unless a file with the extended filename does not +exist, in which case the named file will be removed (because of a bug). .Pp If renaming the files would cause files to be overwritten and the standard input device is a terminal, the user is prompted (on the standard error output) for confirmation. If prompting is not possible or confirmation is not received, the files are not overwritten. +As many of the file attributes (modification time, access time, +file flags, file mode, user ID, and group ID) as allowed by +file permissions are retained in the new file. .Pp If no files are specified or a .Ar file argument is a single dash .Pq Sq Fl , the standard input is compressed or uncompressed to the standard output. -If either the input and output files are not regular files, the checks for +If either the input and output are not regular files, the checks for reduction in size and file overwriting are not performed, the input file is -not removed, and the attributes of the input file are not retained. +not removed, and the attributes of the input file +are not retained in the output. .Pp The options are as follows: -.Bl -tag -width indent -.It Fl b -Specify the -.Ar bits -code limit (see below). +.Bl -tag -width ".Fl b Ar bits" +.It Fl b Ar bits +The code size (see below) is limited to +.Ar bits , +which must be in the range 9..16. +The default is 16. .It Fl c Compressed or uncompressed output is written to the standard output. -No files are modified. +Compression is attempted even if the results will be larger than the +original. +No files are modified. The +.Fl v +flag is ignored. .It Fl f -Force compression of -.Ar file , -even if it is not actually reduced in size. -Additionally, files are overwritten without prompting for confirmation. +Files are overwritten without prompting for confirmation. +For compression, proceed even if the +results will be larger than the original. .It Fl v -Print the percentage reduction of each file. +The size reduction of each file is printed as a percentage to +the standard output. Ignored for uncompressiong or if the +.Fl c +flag is also used. .El .Pp The @@ -112,21 +127,14 @@ Common substrings in the file are first replaced by 9-bit codes 257 and up. When code 512 is reached, the algorithm switches to 10-bit codes and continues to use more bits until the -limit specified by the -.Fl b -flag is reached (the default is 16). -.Ar Bits -must be between 9 and 16. -.Pp -After the -.Ar bits -limit is reached, -.Nm -periodically checks the compression ratio. +code size limit (see +.Fl b ) +is reached. +Then the compression ratio is periodically checked. If it is increasing, .Nm -continues to use the existing code dictionary. -However, if the compression ratio decreases, +continues to use the existing code dictionary; +but if the compression ratio is decreasing, .Nm discards the table of substrings and rebuilds it from scratch. This allows the algorithm to adapt to the next "block" of the file. @@ -187,3 +195,9 @@ .Nm command appeared in .Bx 4.3 . +.Sh BUGS +For uncompression, if a specified filename doesn't end with +.Dq .Z +and a file with the filename extended with +.Dq .Z +does not exist, the named file will be removed. >Release-Note: >Audit-Trail: >Unformatted: To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?hjk7hjmpdz.7hj>