[Doc-SIG] Jython documentation

[Fred L. Drake, Jr.]

Robert W. Bill writes:
 > Collecting information and examples in a Wiki seemed a good
 > first step, but the formal documentation wasn't so
 > clear. Note that the type of documentation we are pursuing
 > is not that gleaned directly from Java or Python code (not

  I guess my biggest question is:  What kind of content are you
thinking about?  Are there problems with using the standard
documentation?  Would the addition of compatibility notes help, or is
there something more significant lacking?

 > The Latex documentation espoused by Fred Drake's "Documenting
 > Python" wasn't a big hit as few are drawn to Latex; however,
 > staying close to CPython's documentation seemed a good idea.

  LaTeX isn't that big a hit anywhere!  ;-)

 > The section on the documentation future (sgml, xml) seems more
 > interesting. And finally, the questions...

  I need to work on that some more; the target will definately be
XML.

 > What sgml, xml tools are used by the documentation group? The
 > current doc projects seemed more aimed at using inline
 > documenation- are there tools for executive level (not inline)
 > docs? Are there Python doc specific DTD's that should be
 > considered, or is DocBook the most reasonable, despite weighty,
 > path? Is there other advice we can benefit from?

  I've considered DocBook at the object-oriented extensions that have
been proposed, and it just isn't a good match.  I have on my plate
working up the DTD(s?) and related data/content model documentation,
but have not had the time yet.  ;(
  Tool-wise, its too early to be very specific.  I intend to stick
with standards-based tools and Python (though I won't restrict myself
to tools written in Python).  I expect to see a bunch of Python and
some XSLT, and no Perl, but once I've got the DTD(s?) and models
documented, it should be (relatively) easy to apply any general XML
tools.
  I have no specific timeframe because it just isn't that high a
priority with my employer.


  -Fred

-- 
Fred L. Drake, Jr.  <fdrake at acm.org>
PythonLabs at Digital Creations