Python documentation in DocBook

[Gerhard Häring]

Martin v. Loewis wrote in comp.lang.python:
> DaveP <DaveP at NEARLYdpawson.freeserve.co.uk> writes:
>> I'm curious what the problem being solved is, and whether docbook
>> and its xml toolset could resolve it?
> 
> As a DocBook user, I can tell you that DocBook and its xml toolset
> could not resolve that.

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).

>> [\seerfc]
>> <ulink href="url"> .... </ulink> appears to provide the same
>> functionality if that is the case.
> 
> Yes, but the documentation author has to fill in the URL. In Python
> documentation, the RFC URL provided at formatting time; currently, it
> points to www.faqs.org.
> 
> So yes, this could be converted, but only with a loss of information.

That's true for ulink, but you could invent your own element and have
appropriate transformation to do the same as the current solution.

Here's my personal summary of the pros/cons:

- Everything that the current Python/LaTex toolchain can do could in
  theory be done using a XML/SGML toolchain, using various
  transformation tools (AFAIK these exist for
  man/pdf/ps/html/txt/windows help from either Docbook XML or SGML)

- It's some effort to extend the Docbook DTD to fit the need of the
  Python documentation.

- It's considerable effort to adjust the various transformation tools
  to cope with the new DTD.

- It's also considerable effort to tweak the transformation tools
  (via XSLT, XML:FO or whatever) so that the resulting documentation
  does look as well as Python's current one. The defaults of these
  tools mostly look quite crappy.

- There's no clear benefit from switching to Docbook right now. All
  the difficult work has already been done for LaTex and switching to
  Docbook provides no clear advantage. Plus, the difficult work would
  have to be done *again*.

Personally, I happen to like Docbook and hardly ever used LaTex, but
have difficulty making the (HTML) Docbook output look good.

I'd suggest to anybody who wants to make the Docbook transition happen
to provide XSLT/CSS stylesheets that make the HTML output of Docbook
look *exactly* like the current one. Same for the PDF output. Unless
you can prove that this is at least possible, at least *I* find the
suggestion to switch to Docbook unconvincing.

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 ;-)

-- Gerhard