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>
_______________________________________________
Doc-SIG maillist - Doc-SIG@python.org
http://mail.python.org/mailman/listinfo/doc-sig
