[Python-Dev] status of development documentation (original) (raw)

Fred L. Drake, Jr. fdrake at acm.org
Wed Dec 21 19:35:09 CET 2005

[Copied to the Doc-SIG list.]

On Wednesday 21 December 2005 13:02, Josiah Carlson wrote:

+1 for using ReST. +0 for sticking with latex.

I'll try and spend a little time on this issue this week, but time is hard to come by these days.

ReST (as implemented in docutils) at this point does not support nested markup constructs, unless something has changed in the last few months. I think this is a significant limitation.

LaTeX, for all the tool requirements, is a fairly light-weight markup language. Yes, it has too many special characters. But someone else invented it, and I'm not keen on inventing any more than we have to.

There is the matter of all the semantic markup we're doing in the LaTeX sources; some people think it's fine, and others think using a specialized semantic markup is either a bad idea or at the least a barrier to contributions (though I've pointed out that contributing just plain text is fine many, many times). Alternatives to the semantic markup that I expect to see suggested include:

nothing special, just using presentation markup directly: This prevents even simple information re-use. Conventions can help, but require a careful eye on the part of editors (possibly with tools to help).

something like HTML, but with "microformat" style annotations: More reasonable, especially if we rely on conventions and stylesheets for presentation. I expect the markup will actually be much heavier than the current markup, though it will be somewhat more familiar to someone when they first look at it. Adding in the annotations changes that a bit.

docbook, because others use that: This is really heavy, but tools exist. The last I looked at the OOP extensions, they were fairly simple, but not well matched to Python.

ReST, possibly with additional interpreted text roles: This has been explored in the past, and would likely not be a bad approach. As noted above, I expect non-support for nested markup in docutils to be a problem that will become evident fairly quickly.

All that said, I think this discussion belongs on the Doc-SIG; I've CC'd that list.

-Fred

-- Fred L. Drake, Jr.

More information about the Python-Dev mailing list