[Doc-SIG] Python Tutorial - urllib2
Martin Blais
blais at furius.ca
Thu Dec 22 17:53:21 CET 2005
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 :-)
More information about the Doc-SIG
mailing list