Python documentation in DocBook

[Martin v. Loewis]

DaveP <DaveP at NEARLYdpawson.freeserve.co.uk> writes:

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

Certainly - but then we need entirely new tools (or must modify
existing tools). Have you ever tried to modify Norman Walsh's DocBook
XSLT stylesheets? That may be an excellent piece of software, but it
has a complexity that is not easy to grasp (to put it mildly).

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

We are not talking about the big picture here; I happily leave views
and architectures to others. What we are talking about is the Python
documentation, which has small but precise needs. Being able to
represent arbitrary characters is not a requirement at the moment.

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

To proof that it can be done, and to smoothen the transition. Many
URLs in the world point to specific pages of the documentation at
python.org. It is desirable that as few as possible of these URLs
break just because the formatting engine changes.

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

Three or four, I think. Conversion to DocBook has been studied for
three years, atleast, and everytime this comes up, the conclusion is
that it is not worth the effort.

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

You don't need to be a Tex aficionado to contribute to the Python
documentation. I don't like Tex myself, and I don't use it for
anything but the Python documentation. However, when writing Python
documentation, I don't think of it as writing Tex. It is a special
language that is much easier to learn than Tex, since the processor is
much more forgiving (it is processed by Fred Drake, after all).

> Change is inevitable.

That may be the case. Change to Docbook can be avoided if necessary.

Regards,
Martin