[Doc-SIG] Python Tutorial - urllib2

[Fred L. Drake, Jr.]

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.

 > 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.  :-)

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.

 > 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.


  -Fred

-- 
Fred L. Drake, Jr.   <fdrake at acm.org>