[Python-Dev] The docs, reloaded

[Raymond Hettinger]

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