[Python-Dev] The docs, reloaded (original) (raw)
Martin Blais blais at furius.ca
Tue May 22 16:46:41 CEST 2007
- Previous message: [Python-Dev] The docs, reloaded
- Next message: [Python-Dev] The docs, reloaded
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
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.)
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.)
- Previous message: [Python-Dev] The docs, reloaded
- Next message: [Python-Dev] The docs, reloaded
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]