[Doc-SIG] Python docs in reST
Fred L. Drake, Jr.
fdrake at acm.org
Fri May 27 01:04:28 CEST 2005
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>
More information about the Doc-SIG
mailing list