Markup bugs in the gzip man pages

[Eric S. Raymond]

I'm working on a program that automatically translates manual page sources
to DocBook markup.  You can find out more about this program at 

        http://www.tuxedo.org/~esr/doclifter/

If you are not already considering it, please think about moving your
documentation masters to DocBook (or some format from which you can
generate DocBook).  Tools to generate man pages (docbook2man) HTML
(docbook2html) and PostScript (docbook2ps) from DocBook files are
open source and generally available.  My program, doclifter, should
make moving your masters to DocBook a pretty painless process.

Many major open source projects (including the Linux Documentation
Project, GNOME, KDE, and FreeBSD) have moved to DocBook or are in the
process of doing so.  The format has many advantages over man, info,
texinfo, or HTML; by moving everybody to it, we should be able to
support unified browsing of all system documentation with Web-like 
hypertext capabilities, automatic indexing, and rich search facilities.

In the process of debugging doclifter, I have discovered many bugs in 
man page layout.  These are significant because they make automated
translation to DocBook more difficult, and often confuse other document-
mining tools (such as indexers).

I have found some markup bugs on a manual page you maintain.
Please fix these in your next release.

The problems in gzip are one use of an unknown, illegal man macro and
several number of uses of low-level troff macros that can't be
translated structurally.  The following patch fixes these problems.
The visual appearance of the result should not be significantly changed.

Diffs between last version checked in and current workfile(s):

--- gzip.1      2001/10/18 15:24:46     1.1
+++ gzip.1      2001/10/18 15:30:27
@@ -372,81 +372,58 @@
 .SH "DIAGNOSTICS"
 Exit status is normally 0;
 if an error occurs, exit status is 1. If a warning occurs, exit status is 2.
-.PP
+.TP
 Usage: gzip [-cdfhlLnNrtvV19] [-S suffix] [file ...]
-.in +8
 Invalid options were specified on the command line.
-.in -8
-.IR file :
-not in gzip format
-.in +8
-The file specified to
-.I gunzip
-has not been compressed.
-.in -8
-.IR file:
-Corrupt input. Use zcat to recover some data.
-.in +8
+.TP
+\fIfile\fR: not in gzip format
+The file specified to \fIgunzip\fP has not been compressed.
+.TP
+\fIfile\fR: 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
-.in +8
-zcat file > recover
-.in -16
-.IR file :
-compressed with 
-.I xx
-bits, can only handle 
-.I yy
-bits
-.in +8
-.I File
-was compressed (using LZW) by a program that could deal with
+.nf
+                   zcat file > recover
+.fi
+.TP
+\fIfile\fR: compressed with \fIxx\fR bits, can only handle \fIyy\fR bits
+\fIFile\fR was compressed (using LZW) by a program that could deal
+with
 more 
 .I bits
 than the decompress code on this machine.
 Recompress the file with gzip, which compresses better and uses
 less memory.
-.in -8
-.IR file :
-already has .gz suffix -- no change
-.in +8
+.TP
+\fIfile\fR: already has .gz suffix -- no change
 The file is assumed to be already compressed.
 Rename the file and try again.
-.in -8
-.I file
-already exists; do you wish to overwrite (y or n)?
-.in +8
+.TP
+\fIfile\fR already exists; do you wish to overwrite (y or n)?
 Respond "y" if you want the output file to be replaced; "n" if not.
-.in -8
+.TP
 gunzip: corrupt input
-.in +8
 A SIGSEGV violation was detected which usually means that the input file has
 been corrupted.
-.in -8
-.I "xx.x%"
-.in +8
-Percentage of the input saved by compression.
+.TP
+\fI"xx.x%"\fP Percentage of the input saved by compression.
 (Relevant only for
 .BR \-v
 and
 .BR \-l \.)
-.in -8
+.TP
 -- not a regular file or directory: ignored
-.in +8
 When the input file is not a regular file or directory,
 (e.g. a symbolic link, socket, FIFO, device file), it is
 left unaltered.
-.in -8
--- has 
-.I xx 
-other links: unchanged
-.in +8
+.TP
+-- has \fIxx\fR other links: unchanged
 The input file has links; it is left unchanged.  See
 .IR ln "(1)"
 for more information. Use the
 .B \-f
 flag to force compression of multiply-linked files.
-.in -8
+.PP
 .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
--- zmore.1     2001/10/18 15:20:24     1.1
+++ zmore.1     2001/10/18 15:22:32
@@ -139,7 +139,8 @@
 .I zcat,
 except that a header is printed before each file.
 .SH FILES
-.DT
-/etc/termcap           Terminal data base
+.TP
+/etc/termcap
+Terminal data base
 .SH "SEE ALSO"
 more(1), gzip(1), zdiff(1), zgrep(1), znew(1), zforce(1), gzexe(1)

End of diffs.
-- 
                <a href="http://www.tuxedo.org/~esr/";>Eric S. Raymond</a>

"Guard with jealous attention the public liberty.  Suspect every one
who approaches that jewel.  Unfortunately, nothing will preserve it
but downright force.  Whenever you give up that force, you are
inevitably ruined."     -- Patrick Henry, speech of June 5 1788