Python documentation in DocBook

[DaveP]

Gerhard Häring <gerhard.haering at gmx.de> wrote 
> 
>>> [\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.

OK, So too could the xml processing chain, probably in the same way.
By holding the url in the stylesheet and indexing off some key.

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

Agreed. Just a case of balancing.

> 
> 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.
Yes, though you would leverage off the work that has gone into docbook?
That would provide a good springboard.
> 
> - It's considerable effort to adjust the various transformation tools
>   to cope with the new DTD.
Big jump either way IMO. 
> 
> - 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.
 One mans meat is another mans .... Unarguable.

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

Yep.... But are you going to march onwards to Omega to pick up Unicode?
   The only given in the future is change.

> 
> Personally, I happen to like Docbook and hardly ever used LaTex, but
> have difficulty making the (HTML) Docbook output look good.
Probably I'm less fussy. 
Equally I see nothing in Fred's help documentation that docbook doesn't 
do already.
> 
> 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.

Justification?


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

Few being?
My wild guess would be that there are today more people familiar with XML
than there are with \tex.  How long will the supply of tex afficianado's 
last?

Change is inevitable. Planning for it and managing it are the hard bit.

Regards DaveP.
Having recognised a brick wall, steps sideways.