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

[Phillip J. Eby]

At 11:42 AM 11/5/04 -0800, Brett C. wrote:
>Phillip J. Eby wrote:
>>At 11:50 AM 11/5/04 +0000, Michael Hudson wrote:
>>>Err, do you mean latex2html?  If so, I'm not at all sure that's
>>>realistic.
>>
>>I've dabbled in the guts of latex2html before; it's certainly not pretty.
>>IMO a better long term option might be to use the Python docutils and 
>>migrate to reStructuredText, since there are a bevy of backends available 
>>for latex, PDF, HTML, etc.  They would probably need more work before 
>>they'll be suitable to handle the entire doc generation process, though.
>
>This has been proposed before but has been shot down.  If I remember 
>correctly the reasoning was that LaTeX gave us more control and thus 
>served the purpose better for the official docs.

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.

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.

To be fair, however, here are the downsides I'm aware of:

  * There are more tools that support editing LaTeX than reST

  * Python code would have to be written to replace the current 
Python-specific LaTeX macros with reST "interpreted text modes" and "block 
directives"

  * Conversion could be very time consuming, for the parts that can't be 
automated

  * There is a risk that the needed back-ends may not be sufficiently 
mature or feature-rich.  For example, I don't think there's an HTML 
back-end that can generate pages for different nodes, with navigation 
links.  I don't know if there's a GNU 'info' backend, either.

Anyway, I thought the whole point behind the docutils initiative was to 
create a doc format that could be used anywhere Python needs docs, ala 
Perl's POD.  If there are problems with reST, maybe we should let the 
docutils folks know what additional requirements exist, so that it can 
(eventually) be used for this purpose.