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

Raymond Hettinger python at rcn.com
Tue May 22 17:23:07 CEST 2007

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

FWIW, the pure Python program in Tools/scripts/texchecker.py does a pretty good job of catching typical LaTeX mistakes and giving high-quality error reporting. With that tool, I've been making doc contributions for years and not needed my own LaTeX build.

Also, I did not need to learn LaTeX itself. It was sufficient to read a little of Documenting Python and then model the markup from existing docs.

In contrast, whenever I've tried to build a complex ReST document, it was always a struggle. Copying from existing docs doesn't help much there because the cues are more subtle. As Martin pointed out, most errors slide-by because the mis-markup is typically read as valid, unmarked-up text. I find myself having to continously build and view and html file as I write. I like ResT for light-weight work but think it is not ready for prime-time with respect to more complex requirements.

Fred is also correct in that we don't seem to have people rushing to contribute docs (more than a line or two). For a long-time, we've always said that it is okay to submit plain text doc contributions and that another person downstream would do the mark-up. We've had few takers.

Raymond

More information about the Python-Dev mailing list