[Pipet Devel] Docbook online

[hinsen at dirac.cnrs-orleans.fr]

> Loci's white pages will be written using docbook:  the 'industry
> standard' for creating professional documentation. It is especially
> well-suited to writing books and documentation for computer software and
> hardware. Organizations including GNOME have adopted docbook as the

I decided to use DocBook for the ScientificPython and MMTK manuals,
and my enthusiasm about DocBook gradually disappeared over the time.
First of all, DocBook is extremely complicated, and deciding which
markup to use for what use is not easy. And it doesn't help that the
various existing documentations sometimes contradict each other.
On the other hand, in spite of the enormous number of markup tags,
some very basic things were forgotten; there is no straightforward
markup for citing journal articles, and the markup for library
and code documentation covers only C.

Another problem is translating DocBook to something readable for
normal people. Jade with the DSSSL stylesheets does a good job at HTML
translation (but be prepared to have a fast machine with lots of
memory if you plan to use Jade), but hardcopy output produced via Jade
and JadeTeX looks terrible; it doesn't even respect basic typesetting
rules such as not breaking a page after the first line of a paragraph.

Since I had already started with DocBook and didn't want to start
again from scratch with something else, I ended up using the XML
version of DocBook with modifications (added in the internal DTD
subset) for documenting Python code, and I wrote my own translators to
HTML and LaTeX in Python using DOM. But if I had to do it again, I'd
design my own specialized DTD.

Konrad.
-- 
-------------------------------------------------------------------------------
Konrad Hinsen                            | E-Mail: hinsen at cnrs-orleans.fr
Centre de Biophysique Moleculaire (CNRS) | Tel.: +33-2.38.25.55.69
Rue Charles Sadron                       | Fax:  +33-2.38.63.15.17
45071 Orleans Cedex 2                    | Deutsch/Esperanto/English/
France                                   | Nederlands/Francais
-------------------------------------------------------------------------------