[Groff] DocBook to man [was: Simplifying groff documentation]

[Michael(tm) Smith]

M Bianchi <address@hidden>, 2006-12-22 20:00 -0500:

> I believe that if the effort was done properly, then the content could be
> mechanically translated into any of the formats, including long, flat text
> files.  man -> docBook  would imply  docBook -> man

As mentioned in recent discussion here, there are a few existing
docBook -> man converters. I maintain one of them: The manpages
stylesheet that is part of the DocBook Project XSLT stylsheets
distribution:

  http://sourceforge.net/projects/docbook
  http://docbook.sourceforge.net/

That stylesheet has some limitation but is more robust and
feature-complete than any of the alternatives. My goal in working
on it has been to make it generate reasonable output for any valid
DocBook refentry instance that's thrown at it -- and not to expect
that authors should need to hobble their source to work around
deficiencies in the stylesheet. That means it needs to handle
things like tables, footnotes, hyperlinks, and special characters
without no-opping on them or just discarding them. So it tries to
do the right thing and give some reasonable rendering of them
(within the limitations of plain-text console display).

In the case of tables, it does a great job of converting them to
tbl(1) markup (including tables with vertical and horizontal
spans). In the case of footnotes and links, it renders markers for
them inline and lists their contents at the end of the page in
Notes section. In the case of special characters, it has a
mechanism for converting them to equivalent *roff escapes (it uses
a map that contains something that 800 mappings of characters to
their equivalent *roff escapes).

It will not be orphaned as long as I'm around. Though I would be
happy to hand off maintainence of it to somebody else (hopefully
somebody with better XSLT chops and better *roff knowledge than
me). It has not really been a great joy to work on it. It's
written in XSLT 1.0 -- because the most widely used open-source
XSLT engine, libxslt/xsltproc, does not support XSLT 2.0. And
libxslt's principal maintainer says that it never will. So it will
remain in XSLT 1.0 unless/until an open-source XSLT 2.0 engine
appears and gains used in the free-software community (which the
one open-source XSLT engine, Saxon 8 -- java-based -- has not)

So, anyway, we will going forward have a good DocBook to man
mechanism -- with a minimal dependency on just one thing: an XSLT
1.0 engine. libxslt/xsltproc is packaged for every modern distro,
so that means that DocBook manpage stylesheet will is usable on
very modern distro (and will continue to be going forward).

  --Mike

-- 
Michael(tm) Smith
http://www.w3.org/People/Smith/