Python documentation in DocBook

[Martin v. Loewis]

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

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

In *my* thoughts on internationalization, multi-lingual documents have
no place. Instead, each document has a single language.

Now, it is the case that LaTeX has its own problems with languages
that use large character sets. While I'm not an expert on that, I
believe these problems have been solved, in an acceptable manner.

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

Maybe you misunderstood. I can certainly create a program that
generates the current HTML documentation - I don't even need any
input. That is not the issue. The issue is to allow modification of
the input, and have the output be the same regardless of what the
processing chain is.

You seem to expect that "chunks are named". This is part of the
challenge: what precisely have to be chunks, and how precisely do I
have to name them to get the same output that I currently get.

I bet that, for the existing tools, *no* input will ever produce the
precise output that we currently get. You will have to modify the
style sheets. It is, by far, not obvious that you can modify the
stylesheets - you may have to rewrite them from scratch.

Until you are done doing so, there is no point in converting the
documentation to XML, since we would not be able to render it as HTML.

Regards,
Martin