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 problems in the nmh pages. These are not
errors per se, but they interfere with automatic translation. Please
consider merging these patches into your next release.
.ta/.in combinations are presentation-level and can't be semantically
translated. I've changed them to table markup, which can be.
--------------------------------------------------------------------------
--- mhbuild.1 2002/07/23 16:00:27 1.1
+++ mhbuild.1 2002/07/23 16:02:59
@@ -117,20 +117,14 @@
that are used to create contents in this way.
.ne 13
The composition string may contain the following escapes:
-.sp
-.nf
-.in +.5i
-.ta \w'%P 'u
+.TS
+l l.
%a Insert parameters from directive
%f Insert filename containing content
%F %f, and stdout is not re-directed
%s Insert content subtype
%% Insert character %
-.re
-.in -.5i
-.fi
-.sp
-
+.TE
First,
\fImhbuild\fR will look for an entry of the form:
.sp
@@ -190,9 +184,8 @@
.ne 19
These parameters are of the form:
.sp
-.nf
-.in +.5i
-.ta \w'access-type= 'u
+.TS
+l l.
access-type= usually \fIanon-ftp\fR or \fImail-server\fR
name= filename
permission= read-only or read-write
@@ -203,11 +196,7 @@
server= mailbox
subject= subject to send
body= command to send for retrieval
-.re
-.in -.5i
-.fi
-.sp
-
+.TE
The \*(lqmessage\*(rq directive (#forw) is used to specify a message or
group of messages to include. You may optionally specify the name of
the folder and which messages are to be forwarded. If a folder is not
--------------------------------------------------------------------------
My synopsis parser can't handle [] groups that span a .br line
I'd fix that, but I think this construction misleads human eyeballs, too.
--------------------------------------------------------------------------
--- foobar.man 2002/07/23 16:21:54 1.1
+++ foobar.man 2002/07/23 16:22:04
@@ -16,7 +16,6 @@
addrs\ ...
\%[\-body\ text]
\%[\-cc\ addrs\ ...]
-.br
\%[\-from\ addr]
\%[\-subject subject]]
.br
--------------------------------------------------------------------------
--
<a href="http://www.tuxedo.org/~esr/">Eric S. Raymond</a>
Courage is resistance of fear, mastery of fear, not absence of fear.