Subject: bin/32368: cosmetic patch for NetBSD's gzip(1)
To: None <gnats-admin@netbsd.org, netbsd-bugs@netbsd.org>
From: None <igor@string1.ciencias.uniovi.es>
List: netbsd-bugs
Date: 12/23/2005 15:10:00
>Number:         32368
>Category:       bin
>Synopsis:       NetBSD's gzip(1) usage message should be more accurate
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    bin-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Fri Dec 23 15:10:00 +0000 2005
>Originator:     Igor Sobrado
>Release:        NetBSD 2.0.2
>Organization:
	University of Oviedo
>Environment:
	<The following information is extracted from your kernel. Please>
	<append output of "ldd", "ident" where relevant (multiple lines).>
System: NetBSD ws-05 2.0.2 NetBSD 2.0.2 (GENERIC_LAPTOP) #0: Wed Mar 23 08:59:09 UTC 2005 jmc@faith.netbsd.org:/home/builds/ab/netbsd-2-0-2-RELEASE/i386/200503220140Z-obj/home/builds/ab/netbsd-2-0-2-RELEASE/src/sys/arch/i386/compile/GENERIC_LAPTOP i386
Architecture: i386
Machine: i386
>Description:
	Attached to this report is the cosmetic patch for NetBSD's gzip(1) that
	I propose.  Please, do not apply it verbatim.  Changed lines are only
	suggestions and perhaps do not match the taste of NetBSD.

	I have asked Dave Uhring for fixes to NetBSD's gzip(1) usage.  He,
	not me, should be acknowledged for this patch.  In my humble opinion,
	he did a fine work.

	In short, options has been changed in this way:

	  current: -c --stdout   write to stdout, keep original files
	 proposed: -c --stdout   write to stdout, preserve original files
	    NOTES: None.

	  current: -l --list     list compressed file contents
	 proposed: -l --list     list information for the compressed files
	    NOTES: From Dave: OpenBSD's gzip(1) has "List information for the
	           specified compressed files".  I think that is more
	           descriptive than using "contents".

	           When asked about how a user will understand the description
	           of -l Dave answered: Using "details" is just about the same
	           as using "information".  Actually using the -h argument is
	           really just a reminder to the operator of which arguments
	           are available.  He really should have already read and
	           understood the man page.

	  current: -N --name  save or restore original file name and time stamp
	 proposed: -N --name  save or restore original filenames and timestamps
	    NOTES: I removed the blank between "file" and "name", and the
	           blank between "time" and "stamp", to allow the usage section
	           in the gzip(1)'s source code to fit in a 80 columns listing.

	  current: -n --no-name  don't save original file name or time stamp
	 proposed: -n --no-name  don't save original filenames or timestamps
	    NOTES: Same here.

	  current: -t --test     test compressed file
	 proposed: -t --test     test compressed files againsts its checksums
	    NOTES: In private email, Dave asked how many checksums exist.
	           He thinks that the description of the -t argument needs
	           to be changed to show "checksum" and "file" instead.
	           I certainly do not agree as I understand this example:

	           $ gzip -l *.gz
	             compressed uncompressed  ratio uncompressed_name
	                 664416      1597440  58.4% curso2004.tar
	                3720077     23091200  83.8% curso2005.tar
	                  20731        92160  77.5% ejercicio.tar
	                  50986       112640  54.7% ejercicios.tar
	                  24081        81920  70.6% examen.tar
	                1813038      4003840  54.7% globecom-2005-6.tar
	                 142087       768000  81.4% src.040.tar
	                 668120      1320960  49.4% src.050.tar
	                3068333      8796160  65.1% tesis.21.tar
	                3594889     11048960  67.4% tesis.22.tar
	                3585325     11018240  67.4% tesis.23.tar
	                4951168     14602240  66.0% tesis.24.tar
	               22303251     76533760  70.8% (totals)

	           Dave's answer to this problem is: Ordinarily just one file
	           will be checked.  While the "file" argument to gzip may be
	           globbed, the argument is still singular.

	  current: -f --force    force overwriting & compress links
	 proposed: None yet.
	    NOTES: From Dave: "OpenBSD's description makes better sense than
	           either one."  ["either one", NetBSD's gzip(1) and GNU's
	           gzip(1)]

	           In fact, I agree.  This description is a good source not
	           only to fix the description for -f but also to fix the
	           NetBSD's gzip(1) manual page.  I think that Dave was looking
	           at this item:

	           -f  Force compression of file, even if it is not actually
	               reduced in size.  Additionally, files are overwritten
	               without prompting for confirmation.  If the input data
	               is not in a format recognized by compress and if the
	               option -c is also given, copy the input data without
	               change to the standard output: let zcat or gzcat behave
	               as cat(1).

	           I personally prefer not suggesting a fix for this.  It is
	           certainly difficult.  But, perhaps, the ampersand (&) should
	           be changed to "and".  How does it fit in NetBSD's style?

	           In any case, a fix for -f description would be nice.  It is
	           certainly hard to understand even for people that reads the
	           manual page (that probably should be fixed too).  A fix for
	           the NetBSD's gzip(1) manual page would be advisable too.
>How-To-Repeat:
	This is the output of gzip(1) in NetBSD 2.0.2:

	$ gzip -h
	NetBSD gzip 20040711
	usage: gzip [-cdfhHlnNqrS:tvV123456789] [<file> [<file> ...]]
	 -c --stdout          write to stdout, keep original files
	    --to-stdout
	 -d --decompress      uncompress files
	    --uncompress
	 -f --force           force overwriting & compress links
	 -h --help            display this help
	 -n --no-name         don't save original file name or time stamp
	 -N --name            save or restore original file name and time stamp
	 -q --quiet           output no warnings
	 -r --recursive       recursively compress files in directories
	 -S .suf              use suffix .suf instead of .gz
	    --suffix .suf
	 -t --test            test compressed file
	 -v --verbose         print extra statistics
	 -V --version         display program version
	 -1 --fast            fastest (worst) compression
	 -2 .. -8             set compression level
	 -9 --best            best (slowest) compression
>Fix:

--- gzip.c.orig	2005-12-22 11:19:37.000000000 +0100
+++ gzip.c	2005-12-22 12:26:14.000000000 +0100
@@ -1930,20 +1930,20 @@
     " -1 --fast            fastest (worst) compression\n"
     " -2 .. -8             set compression level\n"
     " -9 --best            best (slowest) compression\n"
-    " -c --stdout          write to stdout, keep original files\n"
+    " -c --stdout          write to stdout, preserve original files\n"
     "    --to-stdout\n"
     " -d --decompress      uncompress files\n"
     "    --uncompress\n"
     " -f --force           force overwriting & compress links\n"
     " -h --help            display this help\n"
-    " -l --list            list compressed file contents\n"
-    " -N --name            save or restore original file name and time stamp\n"
-    " -n --no-name         don't save original file name or time stamp\n"
+    " -l --list            list information for the compressed files\n"
+    " -N --name            save or restore original filenames and timestamps\n"
+    " -n --no-name         don't save original filenames or timestamps\n"
     " -q --quiet           output no warnings\n"
     " -r --recursive       recursively compress files in directories\n"
     " -S .suf              use suffix .suf instead of .gz\n"
     "    --suffix .suf\n"
-    " -t --test            test compressed file\n"
+    " -t --test            test compressed files againsts its checksums\n"
     " -V --version         display program version\n"
     " -v --verbose         print extra statistics\n",
 #else

>Unformatted:
 	<Please check that the above is correct for the bug being reported,>
 	<and append source date of snapshot, if applicable (one line).>