[Doc-SIG] Python docs in reST
bronger at physik.rwth-aachen.de
Fri May 27 08:03:36 CEST 2005
"Fred L. Drake, Jr." <fdrake at acm.org> writes:
> On Thursday 26 May 2005 18:09, Torsten Bronger wrote:
>> I have thorough experiences with XML (http://tbook.sf.net), and I
> That site appears to be down at the moment.
Well, I misspelt it: tbookdtd.sf.net. At the moment it's only XML,
so I'm looking for a human-friendly input format. I've evaluated
many Wiki formats, but reST is the most promising so far.
>> 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.
In the current situation I don't see a reliable way to get to XML.
Even if you don't use XML in the typical workflow, its possibility
alone assures flexibility and reusability.
It's just so drop-dead simple to do all this with XML. One month
ago I completed a texi2latex converter in XSLT, which covers more
spec features than the original processor(!) with only 120kB of
source code (and XSLT is verbouse).
For our students newspaper, I use wiki --> XHTML --> LaTeX with
great ease. Our authors come from all faculties and are mostly Word
users, but with this system they submit ready-to-use articles.
(Wiki --> XHTML is done with Python, of course. ;)
Theoretically, you *can* achieve this also with an appropriately
constrained LaTeX, therefore my question about a well-defined
subset. LaTeX becomes really nasty not until you use more than
ASCII, which is rare in computer documentation. However, for this
way there must be a real "Python doc" LaTeX with an explicit
>> 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 definitely is a problem with the current reST, however, I think
it's solvable. There is a finite number of typical text patterns in
computer docs, and the reST standard must give you the canonical way
to write them. At the moment, the format is a little bit
wishy-washy, and the specification even more so.
For some things there doesn't seem to be a data model yet. Maybe
reST should be designed not so much as something with an XML
backend, but as a frontend to an XML format one has agreed upon in
the first place. You're right agree that a documentation format is
only useful if it delivers logical markup, and this would be a step
I admit that a certain amount of implicit behaviour will always be
necessary (aka magic). However, I find this desirable, because
often you have to make things clear to LaTeX that the doc processor
could and should figure out itself. This may be a matter of taste,
Torsten Bronger, aquisgrana, europa vetus
More information about the Doc-SIG