[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Markup bug in the gawk.1 man page

From: Eric S. Raymond
Subject: Markup bug in the gawk.1 man page
Date: Thu, 1 Nov 2001 21:52:33 -0500

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


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.

Line 1408, at the end of the list of control statements, reads:

\fB{ \fIstatements \fB}

This is wrong, and should read

\fB{ \fIstatements \fR}
                <a href="http://www.tuxedo.org/~esr/";>Eric S. Raymond</a>

The same applies for other kinds of long-lasting low-level pain. [...]
The body's response to being jabbed, pierced, and cut is to produce
endorphins. [...]  So here's my programme for breaking that cycle of
dependency on Windows: get left arm tattooed with dragon motif, buy a
crate of Jamaican Hot! Pepper Sauce, get nipples pierced.  With any
luck that will produce enough endorphins to make Windows completely
redundant, and I can then upgrade to Linux and get on with things.
        -- Pieter Hintjens

reply via email to

[Prev in Thread] Current Thread [Next in Thread]