8. Migration tools
The second biggest problem with DocBook is the effort needed to
convert old-style presentation markup to DocBook markup. Human beings
can usually parse the presentation of a document into logical
structure automatically, because (for example) they can tell from
context when an italic font means `emphasis' and when it means
something else such as `this is a foreign phrase'.
Somehow, in converting documents to DocBook, those
sorts of distinctions need to be made explicit. Sometimes
they're present in the old markup; often they are not, and the
missing structural information has to be either deduced by
clever heuristics or added by a human.
Here is a summary of the state of conversion tools from
various other formats:
- GNU Texinfo
The Free Software Foundation has made a policy decision to
support DocBook as an interchange format. Texinfo has enough
structure to make reasonably good automatic conversion possible, and
the 4.x versions of makeinfo feature a
--docbook switch that generates DocBook.
More at the makeinfo project
page.
- POD
There is a POD::DocBook
module that translates Plain Old Documentation markup to DocBook. It
claims to translate every POD tag except the L<> italic tag.
The man page also says "Nested =over/=back lists are not supported
within DocBook." but notes that the module has been heavily
tested.
- LaTeX
LaTeX is a (mostly) structural markup macro language built on
top of the TeX formatter. There is a project called
TeX4ht that (according to the author of PassiveTeX) can
generate DocBook from LaTeX.
- man pages and other troff-based markups
This is generally considered the biggest and nastiest conversion
problem. And indeed, the basic
troff(1) markup is at too low a presentation
level for automatic conversion tools to do much of any good. However,
the gloom in the picture lightens significantly if we consider
translation from sources of documents written in macro packages like
man(7). These have enough structural
features for automatic translation to get some traction.
I wrote a tool to do this myself, because I couldn't find
anything else that did a half-decent job of it (and the problem is
interesting). It's called doclifter. It will
translate to either SGML or XML DocBook from
man(7),
mdoc(7),
ms(7), or
me(7) macros. See the documentation
for details.