[Python-Dev] The docs, reloaded (original) (raw)

Georg Brandl 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.

Georg

More information about the Python-Dev mailing list