[Python-Dev] The docs, reloaded
g.brandl at gmx.net
Tue May 22 17:11:18 CEST 2007
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.
More information about the Python-Dev