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

Georg Brandl g.brandl at gmx.net
Tue May 22 18:13:36 CEST 2007

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

More information about the Python-Dev mailing list