[Doc-SIG] Python docs in reST

[Torsten Bronger]

Hallöchen!

"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
specification.

> [...]
>
>> 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
towards it.

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,
though.

Tschö,
Torsten.

-- 
Torsten Bronger, aquisgrana, europa vetus