[Fwd: Errors on the dia.1 man page]

[Alexander Larsson <alla lysator liu se>]

--- Begin Message ---

• From: "Eric S. Raymond" <esr snark thyrsus com>
• To: hallon lysator liu se, alla lysator liu se
• Subject: Errors on the dia.1 man page
• Date: Sun, 14 Oct 2001 11:31:53 -0400

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.  Tools to generate man pages (docbook2man)
HTML (docbook2html) and PostScript (docbook2ps) from DocBook masters are
open source and generally available.  My program, doclifter, should make moving
your masters to dicbook 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 thdey 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.

There is a superfluous period on line 8 that messses up my
command-synopsis parser.

On line 22 there is an invalid ".l" command.

Please fix these in your next release.
-- 
                <a href="http://www.tuxedo.org/~esr/";>Eric S. Raymond</a>

Fantastic doctrines (like Christianity or Islam or Marxism) require unanimity
of belief. One dissenter casts doubt on the creed of millions. Thus the fear
and the hate; thus the torture chamber, the iron stake, the gallows, the labor
camp, the psychiatric ward.     -- Edward Abbey

--- End Message ---