Python documentation in DocBook

Martin v. Loewis martin at v.loewis.de
Wed Nov 13 04:16:59 EST 2002


Gerhard Häring <gerhard.haering at gmx.de> writes:

> At least, the DTD would have to be extended and the tools would likely
> have to be adjusted. I'm quite sure that everything that the current
> customized LaTex suite uses can be done with Docbook/XML (or
> Docbook/SGML, which is a little more mature).

It strictly won't be Docbook anymore once extended.

Docbook *does* have its extension mechanisms: you can use the role
attribute available on many elements. For example, you could write

<chapter role="module">
  <title>Common String Operations</title>
  <titleabbrev role="standard">string</titleabbrev>

with the processing expectation that this has the same effect as

\section{\module{string} ---
         Common string operations}

\declaremodule{standard}{string}
\modulesynopsis{Common string operations.}

I think this is straining DocBook already - no existing processor
would deal with that correctly.

> Those who are working on the Python documentation will certainly not
> do this work for you, as they've better work to do. Namely, writing
> documentation and not fighting the toolchain. Adjusting the tools has
> been done once already, and that should suffice for a few years ;-)

I agree with your analysis. As for this last item: Most documentation
authors (atleast if I extrapolate from a single random sample, myself
:-) won't fight with the Latex tools. Instead, they edit the
documentation so that it looks right in the editor, and then let Fred
Drake fight with the tools. So at any point in time, there is a good
chance that the documentation has markup errors - unless somebody just
went over it and fixed them all.

Regards,
Martin



More information about the Python-list mailing list