docbook to man page converter

[Mark Galassi <rosalia cygnus com>]

For those GNOMErs who like man pages (yuck), I just saw this on the
main DocBook list (look down a bit, where he talks about man pages).
I will look in to it and see about including it in the free tool
suite.

---

• From: Fred Dalrymple <fld veloce com>
• To: davenport berkshire net
• Cc: fld veloce com (Fred Dalrymple)
• Subject: Re: DAVENPORT: Re: formatting
• Date: Fri, 20 Mar 1998 11:00:59 -0500 (EST)

> > Then you need something that formats the raw SGML. 

Not necessarily -- there may be transformations of the SGML that you'd
need to have done before doing the formatting.

Looking to the converters (Omnimark et al) to do formatting is, I think,
stretching those technologies..  You wouldn't look to TeX or nroff/troff
to process SGML, and you probably wouldn't look to Omnimark to do right
adjustment algorithms or table column spanning (let alone generating
PostScript)...  Some things are good at processing SGML, some at laying
out text -- they're different tasks.

> Thinking about this some more, DocBook to *roff might be nice, and I
> know James C wants a *roff backend for Jade.

I haven't seen anyone mention the public domain package for taking
<RefEntry>s to nroff/troff manpage macros.  The work was done for the
X Consortium, and is freely available:

    ftp://ftp.x.org/contrib/utilities/docbook-to-man.tar.gz

That package depends on nsgmls for the SGML parsing, then uses "instant"
to translate the ESIS into manpage macros (instant is included in the
package).  From there, the formatting is handled by tbl/nroff/troff.

Though that package doesn't address all of DocBook (and was built for
DocBook 2.4.1 so it needs some updating), it does include pretty
thorough table support (via tbl), which alone has got to be a leg up on
starting this task from scratch.

In other words, if one were to take on the task of handling all of
DocBook, this isn't a bad beginning.  Probably, one would target another
nroff/troff macro set (eg, -mm or -ms) for <Book>-type content.  But
note that, somewhat ironically, the <RefEntry>-specific portion of
a <Book> wouldn't work -- you can't embed manpage macros within another
set of macros like -mm.  A lot *would* work (eg, tables), but you'd have
to create a set of macros to simulate manpage layout style within the
context of a book...

> > But all of these you pay for, ranging from around $350 to the upper
> > tens of thousands. Emacs, psgml, nsgmls, Jade, TeX, and OMLE cost 
> > you no cash: for these you pay in sweat or by returning the fruits 
> > of your own labors to the public domain.

This path, including nroff/troff (in the guise of groff), is also in
the $ 0 category.

Fred

ps.  the docbook-to-man work was done to "kill off" that perennial
     problem voiced in UNIX shops who were considering moving their
     manpage documentation to SGML:  "but how do we make the man
     command work?"

---