Martin Blais schrieb: > On 5/22/07, Nick Coghlan <[EMAIL PROTECTED]> 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 _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
