Doc-SIG readers, This is a long message, but please read it. Moshe Zadka writes:

Authority. Because arbitrary decisions (and it *is* arbitrary) should be made by someone, and then followed. Same reason standards aren't done by poles.

At some point, I will make a recommendation to Guido substantially based on what comes out of this SIG. He will say "yes" or "fix ....", and that will be that. [What follows refers specifically to embedded documentation.] What *I'm* looking for is something to hand to Guido, with an implementation on hand. I want tools that don't require the import of a module's source code. I want it to produce a data structure that can be stored persistently, and I want to be able to produce really nice HTML. I want it written in 100% Python and work with both the CPython and JPython interpreters. Once this is available, I can start dealing with support for multiple formats and that sort of thing. [Back to your regularly scheduled SIG!] I think this SIG has made progress in fits and starts for a variety of reasons, including insufficient availability of my time to implement suggestions or keep up with the discussions. On the other hand, we have seen a number of things start to coalesce recently (never mind that they seem about to fall apart some days). While David seems to think we got very little out of the Doc-SIG session at the conference, I don't agree. David's current stance on StructuredText is good; it leverages existing work more than previous proposals and keeps the markup for embedded documentation quite minimal. It appears that sufficient support for rich hyperlinking can be built without costing too much. Let's support David and the StructuredText people so this can be a fruitful effort. What I got out of the conference was that the most important thing was to quite bickering about syntax and decide on one format for embedded documents and one for out-of-line documents. The attendees at the session seemed to be largely unconcerned about the specific syntax used. For inline, we've agreed here that the syntax should be minimal and that "just-text" docstrings should work. I stated that they would work *well*, so that's a specific requirement for tool builders on this one. I also got the message that nobody really cares about the SGML vs XML debate (it *is* a minor detail), and nobody really cares about the specific DTD. I will write one based on the existing conversion project; we can hash out details here a bit, but it will be frozen relatively quickly. I'll need someone to write stylesheets for typesetting; DSSSL or XSLT/XSL would be fine. We may be able to do the HTML conversion using DSSSL or XSLT as well; if so, I'd like to use the same stylesheet language for that if possible in order to keep the required tool set small, but whether we use multiple stylesheets or one parameterized stylesheet (a la Norm Walsh's modular stylesheets for DocBook) isn't terribly important. We will support at least HTML and one typeset format before we can "cut over" documentation maintenance to the new system. -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> Corporation for National Research Initiatives