[Doc-SIG] Jython documentation

Robert W. Bill rbill@digisprings.com
Mon, 11 Jun 2001 11:30:01 -0500 (CDT)


On Mon, 11 Jun 2001, Fred L. Drake, Jr. wrote:
> 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?

The first-draft outline is at:

    http://www.jython.org/cgi-bin/moin.cgi/JythonDevelDocs

> Are there problems with using the standard documentation?

Do you mean referencing Python docs, or using the standard
doc (LaTeX) tools?

Standard docs are already referenced and are valuable, but do not
address the union with Java and what that means.

> Would the addition of compatibility notes help, or is
> there something more significant lacking?

There are quite a few notes concerning differences between Jython
and Python. However, the scope of the documentation glut includes
working with Java objects, embedding in Java, the role of
reflection, compiling to Java bytecode, inheritance restrictions,
work-arounds for java static, protected members, Jython registry
keys, Java class loading and other such topics unique to Jython.

There seems to be a sizable niche between Java and Python. We're
anxious hear recommendations on how to best fill this, but the
outline mentioned above is our starting point. 

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

It sounds best for us to stick to the Wiki until there's time to
make a DTD. Thanks for the reply.

Cheers,
Robert