[Python-Dev] status of development documentation

[Josiah Carlson]

"Fredrik Lundh" <fredrik at pythonware.com> wrote:
> 
> Josiah Carlson wrote:
> 
> > -1 for choosing something not ReST or latex.
> 
> yeah, because using something that everyone else uses would of course
> not be the python way.

No, because ReST is significantly easier to learn and use than basically
every other markup language I've gotten my hands on.  Also, considering
that we are talking about documenting Python, perhaps using Perl or Ruby
for the generation of Python documentation would be right out, but
Python is perfectly reasonable - regardless of what 'everyone else uses'
(which is a poor reason to use a tool).

So far our alternatives to latex or ReST have been html, docbook, or our
own XML. Though docbook and XML (thankfully) leave formatting up to the
converter, all suffer from ML-itis (hard to write, hard to read, hard to
maintain, syntax highlighting matters, ...), though has the benefit that
it can at least be partially generated from the latex source - Walter
just mentioned Fred's latex->XML converter.  Depending on the output of
this coverter, it may be very reasonable to convert it to ReST, or
perhaps some other markup that is determined to be the rightful
destination.


 - Josiah