[Doc-SIG] Poll-schmoll, READ THIS!

[Fred L. Drake, Jr.]

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