[Python-Dev] The docs, reloaded
Raymond Hettinger
python at rcn.com
Tue May 22 17:23:26 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