[Python-Dev] status of development documentation

[Martin Blais]

On 12/21/05, Barry Warsaw <barry at python.org> wrote:
> On Wed, 2005-12-21 at 20:36 +0100, Fredrik Lundh wrote:
>
> > I'm not really interested in optimizing for you, I'm interested in optimizing
> > for everyone else.  They already know HTML.  They don't know ReST, and
> > I doubt they care about it (how many blogs accept ReST for comments?)
>
> Sorry, but HTML and (even more so) XML are not human-writable. :)  Yeah,
> we can all do the simple stuff, but I absolutely hate authoring in HTML,
> and it would be a nightmare if the documentation production system
> didn't handle lots and lots of magic for you (like weaving in the right
> footers, css, etc. -- oh wait, that's ht2html!).
>
> reST is a fine language but it seems more suitable to simpler linear
> documents like wiki pages and PEPs, rather than those with complicated
> nested structure.
>
> Maybe it's just because I came in late on this thread, but what exactly
> is broken about the current LaTeX documentation?
>
> -Barry

Good point.

Nothing is really "broken", but it's just not flexible because there
is no way to get a solid document model from LaTeX to do some
conversion and processing on.  i.e. you convert from LaTeX direct to
the output.  Having the intermediate representation would allow
generating nicer output, and in more formats, without necessarily
having to reparse the input everytime either.

What we need is not necessarily a change of syntax: the problem is not
the input, it's the conversion.  The input is fine--if someone can't
learn the super simple LaTeX macros for the Python docs, I don't want
to imagine what kind of prose they would come up with.  LaTeX is NOT
hard, at least if you limit yourself to the stuff you need to document
Python code.

About ReST:

Somehow there is a recurrent stream of people--include me at some
point-- who think that ReST could express any document structure for
any task, and that if we use that we will be happy ever after.  ReST
does an amazing job of inferring generic document structures from
text, but for documenting source code, you really want to be able to
say "This is a function", "this is an optional argument", etc.  ReST
does not provide this kind of functionality, and if you try to stretch
the interpreted roles to do this you get an equally ugly syntax as
LaTeX input (I would even argue that I prefer the LaTeX source).

Also, ReST has many gotchas: if you will infer structures from
invisible markup, it's very easy to make mistakes, and there are many
cases where it's not clear what the parsed document will be like, you
have to "learn" a lot of how it parses the documents, and the corner
cases, by checking with rst2pseudoxml.py.  I'm facing this problem
with some of my Nabu extractors, which attempts to extract
semantically meaningful chunks out of the docutils tree, for example,
contact information.

If there is a problem it is not the input, it's the toolchain and conversion.