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

[Phillip J. Eby]

At 06:42 PM 11/6/04 +0100, Martin v. Löwis wrote:
>Phillip J. Eby wrote:
>>>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.
>
>Ah, so you would make use of extensions; i.e. we would essentially
>clone reST.

If you mean clone the Python extensions to LaTeX, then yes.


>>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.
>
>I did not understand that, in order to use reST in a complex
>application, you have to write your own markup extensions, and
>then support those in all the backends you care about.

Just as was done for LaTeX, yes.  (E.g. the Python latex2html 
postprocessing step, and the Python LaTeX macros.)


>If that is typical, then yes, reST should be able to represent
>everything we have in the documentation right now. It just means
>that we cannot expect reST to work *out-of-the-box*. Instead, we
>first need to implement the missing formatting elements for the
>backends we care for. That sounds like a significant project of
>its own.

Potentially so.  However, there are some significant shortcuts possible for 
many situations.  reST includes an unparameterized macro facility, a 'raw' 
directive that passes markup through to the backend, and a 'role' directive 
to create markup roles for use with interpreted text.  These roles apply 
"class" attributes to the DOM, that then end up as HTML or XML "class" 
attributes, or potentially as LaTeX macros or environments.  For example, 
one might use:

    .. role:: var(emphasis)

to define a text role that could be used to replace \var{foo} with :var:`foo`.

So, I think there are some regularities that can be exploited, such that 
it's not an N*M project, for N features and M backends.  Those features 
that can be implemented in terms of existing reST concepts (other than the 
'raw' passthru) would only need implementation once.  Indeed, if reST 
simply had a suitable directive for defining directives, I think that all 
of the merely typographical aspects of Python documentation markup could be 
defined in reST, as part of the documentation source.

The main main areas of "missing" features in docutils backends that I'm 
aware of would fall under the headings of index generation (all backends), 
and multi-page HTML output with navigation links (HTML backend).