[Doc-SIG] Python docs in reST

[Torsten Bronger]

Hallöchen!

Skip Montanaro <skip at pobox.com> writes:

> [...]
>
> I'm not convinced we actually need to change markup systems either.  My
> suggestion that perhaps migrating to reST was motivated by:
>
>     * my dread (real or imagined) that trying to coax different
>       output from latex2html would be a big PITA

It is possible to tweak tex4ht for this purpose.  It would generate
some sort of XML which you could use as the starting point, for
example.  tex4ht+XSLT is very slow, but reST isn't a sprinter
either.  Unfortunately, tex4ht is not easy to setup.

By the way, is there an agreement on a clearly defined subset of the
LaTeX language or Python documentation?  If you allow everything
that TeX/LaTeX can process (even if you recommend certain ways more
than others) you end up with LaTeX files that only TeX/LaTeX can
process.

>     * a perhaps invalid assumption that reST-as-input would
>       generate more documentation contributions based upon the
>       occasional comment I've seen over the years that
>       (paraphrasing), "I can't contribute - I don't know how to
>       use LaTeX."

I think that this will happen for reST, too.  Besides, many people
know LaTeX already, but nobody will know reST.  However, I don't
think that this is a fatal point: Complex structure (and computer
documentation is amongst the most complex documents at all) always
requires complex markup, in one way or the other.  (Too much
implicit magic must be learned, too.)

> I'm personally comfortable with LaTeX.  Fred has yet to complain
> about my markup errors, so if we can find other ways to address
> the above problems/perceptions, I'd actually be happy to keep
> LaTeX.

I know LaTeX very well, and I can say that I like it very much.
However, it's difficult to guarantee translations to other formats.
Concerning "there's more than one way to do it", LaTeX is much worse
than Perl.  Even if you keep the core documentation consistent, it
would be better to have a rock-solid standard doc system in Python.
Let alone the problems when trying to add a feature to your
documentation system.

I have thorough experiences with XML (http://tbook.sf.net), and I
think that it's the best way to archive and to process
documentation.  Since you can't (well, don't want to) input it
directly, something like reST with an XML backend -- among others --
is the way to go, in my opinion.

Even if for really complex projects the reST source becomes somewhat
cluttered, too, it can be an efficient replacement for LaTeX docs.
It contains so many clever tricks to keep the "plain text"
appearance that I'm optimistic that the rest can be added rather
nicely, too.

Tschö,
Torsten.

-- 
Torsten Bronger, aquisgrana, europa vetus