[Python-Dev] The docs, reloaded

[Georg Brandl]

Martin Blais schrieb:
> On 5/22/07, Nick Coghlan <ncoghlan at gmail.com> wrote:
>>
>> So in Armin's example, I found the reST version *much* easier to read.
>> Whether that difference in perception is due simply to my relative lack
>> of experience in using LaTeX, or to something else, I have no idea.
> 
> - If you make a mistake in LaTeX, you will get a cryptic error which
> is usually a little difficult to figure out (if you're not used to
> it).  You can an error though.
> 
> - If you make a mistake in ReST, you will often get no warning nor
> error, and not the desired output.  If you were to use the amount of
> markup in that example, you would have to check your text with rst2xml
> frequently to make sure it groks what you're trying to say.  (And I've
> been there: I wrote an entire project who relies specifically on this,
> on precise structures generated by docutils (http://furius.ca/nabu/).
> It's *very* easy to make subtle errors that generate something else
> than what you want.)

That is correct, but can be helped with nice preview features.

> ReST works well only when there is little markup.  Writing code
> documentation generally requires a lot of markup, you want to make
> variables, classes, functions, parameters, constants, etc..  (A better
> avenue IMHO would be to augment docutils with some code to
> automatically figure out the syntax of functions, parameters, classes,
> etc., i.e., less markup, and if we do this in Python we may be able to
> use introspection.  This is a challenge, however, I don't know if it
> can be done at all.)

While writing the converter, I stumbled about a few locations where the
LaTeX markup cannot be completely converted into reST, and a few locations
where invalid reST was generated and not warned about.

However, both of those problems occurred far less often than I'd anticipated.

Georg