[Doc-SIG] Python Tutorial - urllib2

[Martin Blais]

On 12/22/05, Fred L. Drake, Jr. <fdrake at acm.org> wrote:
> On Thursday 22 December 2005 10:47, Martin Blais wrote:
>  > Well, be disappointed.
>  > It does not currently, and most likely won't.
>
> Yes and no.
>
> Docutils provides support for creating new directives ("dot-dot things") and
> interpreted text roles (":colon: things").  These would go a long way to
> doing what we want, and some experimentation was done toward this
> specifically to support documenting Python modules in a style similar to the
> standard library documentation.  This is somewhere in the docutils sandbox.

It would still not be significantly better than using LaTeX.
if it's not better, why change?


>  > 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!
>
> Whether :function:`os.popen()` is any uglier than \function{os.popen()} is
> largely a matter of what you're used to.  I will note that the LaTeX version
> is one character shorter.  :-)

It's not just that: the LaTeX macro call allows variations (e.g.
optional arguments) that the ReST form does not allow.   It's more
powerful.

Also, the dot-dot directives impose constraints on the layout contents
(has to be indented), which for some uses can make them awkward to
use.  The LaTeX model (delimiting with {}, not caring about
whitespace) is more flexible.


> I think there are appealing qualities to both the TeX macros and the
> availability of the docutils document object model.  Both allow for lots of
> neat things.

Apart from the syntax and a little less markup, I would like to know
are those qualities is that thing that are better with ReST than in
the LaTeX model.  The only thing I can see is the ease of conversion. 
Everything else is less convenient.


>  > 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
>
> Yes, that is the biggest source of pain.
>
>  > 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.
>
> I should get back to that; as someone else noted, the code is really old, and
> doesn't support everything in the current LaTeX markup.

Oh, you did that?  What a wizard :-)