Re: DAVENPORT: DocBook for documenting Python code

[Konrad Hinsen <hinsen@cnrs-orleans.fr>]

> You may want to take a look into sgmlspl which is a perl script from 
> David Megginson which converts an older docbook DTD to latex/html. Its
> very easily to modify(being perl).

Thanks for the pointer, that might help to avoid Jade frustration.
Although my experience with modifiability of Perl code is quite
different from yours...

> There seems to be a misconception that Docbook has poor documentation.
> There are resources by Nik Clayton at the Freebsd site, Mark Galassi (who
> has nicely packaged and out of the box RPMS) and in the distribution itself.

What I need as a document author is documentation which tells me what
markup to use in what situation. The introduction by Mark Galassi does
this for a tiny subset of DocBook, and the reference manual solves the
inverse problem (and in a formal rather than simple way).

> Writing up in docbook may be tedious, but the real win is in
> searching. I mean, if you tag <command>ifconfig</command> you can
> ask a question like: what are all the commands that have to do with

I agree, of course, that's why I ever got interested in DocBook.
But I must also be able to produce good-quality human-readable output,
and with Jade+JadeTeX I cannot do this at the moment.

> One way to implement api markup maybe to use xml namespaces instead of 
> adding more stuff to docbook, and thus increasing its complexity. 
> But you'd be on your own in translating the markup.

Indeed. Although I wonder whether such a "modular" approach could be
used for future versions of DocBook. It would certainly reduce
the intimidation level of the DocBook reference!
-- 
-------------------------------------------------------------------------------
Konrad Hinsen                            | E-Mail: hinsen@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
-------------------------------------------------------------------------------