nmh-workers
[Top] [All Lists]

Markup problems on the MH man pages.

2002-09-03 06:46:50
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.


<Prev in Thread] Current Thread [Next in Thread>