[Doc-SIG] [Python-Dev] status of development documentation

[Fred L. Drake, Jr.]

[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.   <fdrake at acm.org>