Python documentation in DocBook

[DaveP]

martin at v.loewis.de (Martin v. Loewis) 
>> 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).

Yes, I do it regularly. Bob Stayton has recently 'published' a book on
just that subject. Its not a black art, honest. The principles are
very straight forward. 

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

It will be if your thoughts on internationalisation are realised.

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

That's determined by the stylesheets, what the chunks are named.
Re your challenge, if you output is valid HTML or XHTML, it is
re-producable using XSLT and XPATH. Flat statement. The proof 
would be rather hollow, since there is no starting XML?

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

With the comments made on this thread I guess it will remain a no go.
If you have the bandwidth, lurk on the docbook-apps list, hosted at 
oasis.   


>  Change to Docbook can be avoided if necessary.

Very true. Pre-determined necessity?


by the way,

http://www.sagehill.net/xml/docbookxsl/index.html is the docbook 
stylesheet homepage for Bob's material.

regards DaveP