[Python-Dev] Re: interlocking dependencies on the path to a release

[Phillip J. Eby]

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 
of \input".


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

Latex:   \foo{bar}

reST:    `bar`:foo


Latex:   \begin{foo}
          blah blah
          \end{foo}

reST:    .. foo::
             blah blah

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