[Doc-SIG] Python docs in reST

[Fred L. Drake, Jr.]

On Thursday 26 May 2005 18:09, Torsten Bronger wrote:
 > It is possible to tweak tex4ht for this purpose.  It would generate
 > some sort of XML which you could use as the starting point, for
 > example.  tex4ht+XSLT is very slow, but reST isn't a sprinter
 > either.  Unfortunately, tex4ht is not easy to setup.

The current software is generally quite easy to set up on modern linux 
distributions, where everything is provided in standard packages except the 
Python-specific portions.  We use different tools for different output 
formats.

 > By the way, is there an agreement on a clearly defined subset of the
 > LaTeX language or Python documentation?  If you allow everything
 > that TeX/LaTeX can process (even if you recommend certain ways more
 > than others) you end up with LaTeX files that only TeX/LaTeX can
 > process.

There aren't really any restrictions; what recommendations there are can be 
found in "Documenting Python":

    http://docs.python.org/doc/doc.html

If there are any particular constructs you consider a problem, we should 
discuss the issue and determine what the right thing to do is.  Since we 
haven't had a lot of specific complaints, there aren't any constructs we've 
declared unsupported.  For things in the standard documentation, I've tried 
to ensure consistency, but that can be done by fiat simply by changing the 
sources in CVS.

 > I know LaTeX very well, and I can say that I like it very much.
 > However, it's difficult to guarantee translations to other formats.
 > Concerning "there's more than one way to do it", LaTeX is much worse
 > than Perl.

Agreed.  As described above, we very much take Python's consenting-adult 
approach to markup.  As (whatever-we-use) gets more widely accepted, it makes 
sense to define the constraints more carefully.

 > I have thorough experiences with XML (http://tbook.sf.net), and I

That site appears to be down at the moment.

 > think that it's the best way to archive and to process
 > documentation.  Since you can't (well, don't want to) input it
 > directly, something like reST with an XML backend -- among others --
 > is the way to go, in my opinion.

It's not clear to me that you really want an extra front-end to hide what's 
happening.  Writing in ReST only makes sense if ReST sufficiently reflects 
the data model.  If it does, there's no need for an XML step (though software 
can use one if convenient as an implementation detail); if it doesn't (and 
that seems to be the case, if we don't want to introduce the extra markup in 
ReST), then it's not clear that we gain from it.

 > Even if for really complex projects the reST source becomes somewhat
 > cluttered, too, it can be an efficient replacement for LaTeX docs.
 > It contains so many clever tricks to keep the "plain text"
 > appearance that I'm optimistic that the rest can be added rather
 > nicely, too.

I'm skeptical.  If the actual data model is hidden, what I suspect will happen 
is that more documentation will be written with the presentational layer in 
mind and the logical markup skipped ("it's supposed to be italic, right?"); 
this reduces the value of the documentation and the potential for re-use is 
reduced.  Going back to add logical markup after the fact is very tedious and 
likely to miss things that would not otherwise be missed.


  -Fred

-- 
Fred L. Drake, Jr.   <fdrake at acm.org>