[Python-Dev] status of development documentation

[Torsten Bronger]

Hallöchen!

"A.M. Kuchling" <amk at amk.ca> writes:

> On Wed, Dec 21, 2005 at 05:10:24PM +0100, Fredrik Lundh wrote:
>
>> (as I hinted, I'd prefer HTML with microformat annotations as the
>> main format; with roundtripping to markdown or rest (etc) for
>> people who prefer to author in that, and tidy->xhtml->python
>> tools for the HTML generation)
>
> I don't see how HTML can be used to support printed versions of the
> docs (e.g. PostScript, PDF).

I've used XSLT heavily for converting XML/XHTML to PDF.  It was
pretty easy, and the result was of very high typographic quality.
The only disadvantage is that XSLT is *slow*.

My standard approach was to convert XML to LaTeX and to substitute
all unicodes with LaTeX commands.  Thus, the depenencies are LaTeX,
an XSLT processor (Saxon), and a tiny program for the substitutions.
(The latter can be avoided by LaTeX's Unicode package; however,
expect problems in some cases.)

> [...]  Are there any HTML-to-print converters that are better?

I don't understand exactly how the HTML is to be used for Python but
I assume that not everything could be done via CSS, so own
converters will be necessary for perfect output.  Alternatively, you
can use XSLT so that the browser can convert the original document
to a printable document (with table of contents, index etc).  For
perfect typography you need LaTeX though.

> reST is a possibility, though I don't think anyone has worked on
> building the required toolchain.

I used reST last spring for a small package project.  Although I
love its goals (reST as well as Wiki languages are a perfect
"front-end" for the XML family), I was disappointed with its rather
small semantic vocabulary.  I felt forced to use visual markup
tricks and things like that.  If nothing significant has changed, I
think that reST is too young for a really big project.

Tschö,
Torsten.

-- 
Torsten Bronger, aquisgrana, europa vetus            ICQ 264-296-646