[Python-Dev] The docs, reloaded

[Georg Brandl]

Raymond Hettinger schrieb:
>> - 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.

I'm not saying that LaTeX is hard for most of us, I say that it is *perceived*
to be hard by many.

And as soon as you dig into the deep support infrastructure, it gets
very confusing. Just look at this bug fix I made some time ago:
http://mail.python.org/pipermail/python-checkins/2007-April/059637.html

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

ISTM that this is possible with the new markup too. I wrote a great part of the
new "Documenting Python" document, and after reading that one should be prepared
enough to write reST just as well.

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

I can't see many differences. If I can translate a \begin{classdesc}{...}
environment, I can also translate a ".. class::" directive for my new item.

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

Are the docs really that complex? I mean, look at the typical source of
a converted page. The most common things are "information units", i.e.

.. class::

directives, code snippets and plain old text. Cross-references work
flawlessly.

You may also ask Thomas Heller about documenting Python modules in reST.
AFAIR the ctypes docs were written with it and converted to LaTeX
afterwards.

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

Sometimes it's the way you present the ability to change things that
affects how many people actually do it.

Finding the location that tells you how to suggest changes, and opening
a new bug in the infamous SF tracker is not really something people do
happily. A "click here to suggest a change" link that leads to a pseudo-
edit-form, complete with preview facility, might prove more effective.

cheers,
Georg