Bug 123010

Summary:	Misleading Documentation in gzip(1)
Product:	Documentation	Reporter:	Andrew Wright <andrewhw>
Component:	Books & Articles	Assignee:	Xin LI <delphij>
Status:	Closed FIXED
Severity:	Affects Only Me
Priority:	Normal
Version:	Latest
Hardware:	Any
OS:	Any

Description Andrew Wright 2008-04-23 13:20:01 UTC

The gzip(1) man page could do with a little clarification when it comes
to gzcat.

In particular, I expected the following two constructions to do the same thing:
   gzcat *.gz | command
   cat *.gz | gzcat | command

They don't -- it seems that gzcat expects each argument to be a separate
compressed archive whose contents are then concatenated together; the
second of course expects the concatenation of the set of provided files
to be a single archive (which in this case was my expectation of both).

While this is fine functionality, a note to this effect on the man page
certainly couldn't hurt.  Right now there is no discussion whatsoever
about how gzcat (or in fact "zcat" as it is referred to there) handles
multiple files.

Fix: 

Doc issue only.
How-To-Repeat: n/a -- documentation issue

Comment 1 Andrew Hamilton-Wright 2008-04-28 00:17:27 UTC

Suggested modification to source of /usr/share/man/man1/gzip.1.gz
below:


--- gzip.1.old	2008-04-27 20:08:23.000000000 -0300
+++ gzip.1.new	2008-04-27 20:13:54.000000000 -0300
@@ -72,10 +72,17 @@
  will be replaced with another file with the suffix, set by the
  .Fl S Ar suffix
  option, added, if possible.
+.Pp
  In decompression mode, each
  .Ar file
  will be checked for existence, as will the file with the suffix
  added.
+Each file argument must contain a separate complete archive;
+when multiple files are indicated, each is decompressed in turn.
+In the case of
+.Nm gzcat
+the resulting data is then concatenated in the manner of
+.Xr cat 1 .
  .Pp
  If invoked as
  .Nm gunzip

Comment 2 Andrew Hamilton-Wright 2008-04-28 00:28:26 UTC

On Sun, 27 Apr 2008, A. Hamilton-Wright wrote:

> Suggested modification to source of /usr/share/man/man1/gzip.1.gz
> below:

I just noticed that I hadn't flagged "file" as per the argument
notation.  Updated patch:


--- gzip.1.old	2008-04-27 20:08:23.000000000 -0300
+++ gzip.1.new	2008-04-27 20:26:30.000000000 -0300
@@ -72,10 +72,21 @@
  will be replaced with another file with the suffix, set by the
  .Fl S Ar suffix
  option, added, if possible.
+.Pp
  In decompression mode, each
  .Ar file
  will be checked for existence, as will the file with the suffix
  added.
+Each
+.Ar file
+argument must contain a separate complete archive;
+when multiple
+.Ar files
+are indicated, each is decompressed in turn.
+In the case of
+.Nm gzcat
+the resulting data is then concatenated in the manner of
+.Xr cat 1 .
  .Pp
  If invoked as
  .Nm gunzip

Comment 3 dfilter service freebsd_committer

2008-06-30 18:46:02 UTC

delphij     2008-06-30 17:45:47 UTC

  FreeBSD src repository

  Modified files:
    usr.bin/gzip         gzip.1 
  Log:
  SVN rev 180126 on 2008-06-30 17:45:47Z by delphij
  
  Make it clear that gzcat expects each argument to be separate files.
  
  PR:             docs/123010
  Submitted by:   Andrew Wright <andrewhw ieee org>
  MFC after:      2 weeks
  
  Revision  Changes    Path
  1.5       +13 -1     src/usr.bin/gzip/gzip.1
_______________________________________________
cvs-all@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/cvs-all
To unsubscribe, send any mail to "cvs-all-unsubscribe@freebsd.org"

Comment 4 Xin LI freebsd_committer

2008-06-30 18:50:50 UTC

State Changed
From-To: open->patched

-HEAD patched, awaiting MFC.

Comment 5 Xin LI freebsd_committer

2008-06-30 18:50:50 UTC

Responsible Changed
From-To: freebsd-doc->delphij

Take

Comment 6 Xin LI freebsd_committer

2008-11-03 11:29:36 UTC

State Changed
From-To: patched->closed

Patch MFC'ed months ago.  Thanks for your submission!