[Python-Dev] Re: interlocking dependencies on the
path to a release
Phillip J. Eby
pje at telecommunity.com
Sat Nov 6 17:51:20 CET 2004
At 11:18 AM 11/6/04 +0100, Martin v. Löwis wrote:
>Phillip J. Eby wrote:
>>More control of what? I thought that reST was specifically designed to
>>accommodate all of the Python-specific markup we're using in the latex docs.
>How do you create a module index and a "global" index in reST?
By adding directives, or using interpreted text, as long as the feature is
supported by a given output writer.
>How do you express document inclusion (in the spirit of \input)?
There's an "include" directive. I don't know what you mean by the "spirit
>>As a matter of language expressiveness, as far as I can tell, reST
>>accomodates marking up both short strings and long blocks, with
>>application-specific markup, so I don't really understand why there
>>shouldn't be a largely 1:1 mapping between the markup systems.
>It's not about source code display. It is about the other 200
>typographic features that we use in the Python documentation.
I don't get what source code display has to do with it. I'm pointing out
that the languages (Latex and reST) have comparable expressiveness in their
markup facilities, e.g.:
reST: .. foo::
The difference is merely that the meaning of reST's equivalents to macros
and environments (i.e. "interpreted text roles" and "directives") are
defined using Python code rather than Latex. Of course, a latex writer
could still be used to generate latex output, if that is the preferred
format for printing.
By the way, please don't confuse my answering your questions here with me
advocating an actual migration or conversion at this point: from the
dicussion so far and my rechecking the status of the various available
docutils writers, it's clear to me that the writers aren't yet mature
enough to handle generating the Python documentation. But I don't
currently see any issues on the *reader* end. That is, I have not yet seen
any issues raised that rule out reST syntax as a documentation source
format. (I'm not saying there aren't any, either, just that I haven't seen
such an issue raised yet.)
More information about the Python-Dev