[Python-Dev] status of development documentation

[Fredrik Lundh]

Fred L. Drake, Jr. wrote:

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

"someone else invented it" is of course why I'm advocating an HTML-
based format.  There's a huge infrastructure, both on the tool side and
on the spec side, that deals with (X)HTML.  And *everyone* knows
how to write HTML.

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

Light annotations plus simple conventions (with corresponding simple tools)
should be more than good enough to match the current level.

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

The doc-sig didn't look too active when I checked the archives, but maybe
it's time to change that.

</F>