[Doc-SIG] Python Tutorial - urllib2

[Martin Blais]

> >>By the way my vote is -1 on moving to html as the standard markup format
> >>and +1 on working on docutils to turn that into an usable input format.
> >>Additionally - having a wiki version, or a version that accepts user
> >>commentary would be a very useful way of gathering additional
> >>information. Of course someone has to maintain this... I think AMK did a
> >>simple implementation of this a while ago - although it had usability
> >>issues and the resulting data didn't seem to be used. I guess this is
> >>all part of the ongoing discussion.
> >
> >
> > There was a long and detailed discussion about using ReST as an input
> > format for documentation a while ago.  The consensus was that ReST
> > does not allow sufficient markup for technical documentation, which is
> > necessary for this kind of document.
> >
>
> Doesn't currently - or can't ? I thought it was just the current state
> that was a problem. I'd be disappointed if it was never likely to be
> possible to create the python docs with reST.

Well, be disappointed.
It does not currently, and most likely won't.

As much as we all would like some kind of magic silver bullet text
format that just "knows" what we mean and want to express, it is
rather unlikely that ReST develops to become that for every kind of
domain.  ReST does a fair amount of *generic* structure inference, and
that is its scope.  The amount of ugly directives and markup being
regularly proposed on the docutils mailing-list indicates that ReST
may have already reached its potential in terms of automatically
guessing structure from simple text files.  Even if this is not the
case, extending ReST to include keywords for functions, variables,
classes, lists of arguments, etc.  would render it into just an
equally ugly form of input equivalent to the current LaTeX sources,
... and without the power of expression of TeX macros!

You see, for the technical docs we NEED to indicate the nature of the
identifiers, not just to render them consistently, but for generating
indexes, and cross-references, and for plenty of fother reasons.  You
can't do that in ReST (well, the interpreted roles do take you part of
the way, but not enough).  At some point you have to tell the computer
all the information that is in your head, and the ReST format simply
does not stretch that far, and LaTeX is a great tool for this at the
moment.

What sucks now is the inflexibliity of the produced document: the
tools to convert from the LaTeX sources to other formats are nothing
short of wizardry (i.e. LaTeX2html).  What would be great IMO is if we
could obtain some kind of meaningful intermediate representation from
the source, from which we could then generate various output formats
(a bit like how docutils is structured).  I saw some project like that
a while ago, generating XML from LaTeX sources, never had time to
check it out more seriously.

cheers,