Re: documentation and such

[Marcus G. Daniels]

>>>>> "PJ" == Paul E Johnson <address@hidden> writes:

PJ> I need to start doing some better documentation, and I want to
PJ> make notes inside source code and have them pop out in some nice
PJ> way. 

Do you mean to mark up source code for presentation of the source code
or to mark it up for separate documentation?

javadoc is the canonical way to do the latter for Java.  javadoc does a
good job, in my opinion.  For Objective C, we have a custom Emacs Lisp
program extract data, but it isn't really configured for processing
models.  Hardly worth the effort to improve, when a person can just
go write examples in Java, eh?

In principle, DocBook provides nice features for marking up source
code, but right now (AFAIK) the XSL conversion doesn't do things like
callouts as nicely as the DSSSL conversion (such as used by the
userguide).  E.g.

http://www.santafe.edu/projects/swarm/swarmdocs/userbook/swarm.user.user1.03-objc.sect1.html#SWARM.USER.USER1.03.OBJC-CLASS.EXAMPLE

PJ> I know there are various schemes for this, but I want to
PJ> collect advice about which is easiest and which is best to use.  I
PJ> don't want to sink a lot of time into some specialized format that
PJ> will require lots of reconfiguration every few months, but I'm
PJ> willing to try to learn some system.

DocBook is popular in the free software community.  We use it for
everything, basically.  The `proper' use of DocBook has the spirit
"a place for everything and everything in its place".  The fact that
it is XML-based makes it possible to do lots of automatic
preprocessing (e.g.  converting source code comments into XML).

However, DocBook can be frustrating because of the high complexity and
fragility of the support tools.  My hope was that by providing all the
binaries and support files on the CD-ROM for Windows (runnable off the
CD-ROM), that the fragility aspect would be eliminated.  There are
Debian and Redhat binary packages for the Linux world.

I'm hoping over time that Mozilla (Netscape 6) will be able to take
over the job of many of the XML tools we now rely on for creating and
presenting documents.  In principle, Mozilla's HTML editor is based on
a generic DOM/XML engine, so it may come to pass soonish that
Mozilla's editor can edit DocBook XML.  Then there are commercial products
from companies like Arbortext that can edit DocBook in a graphical way.

PJ> In a related note, I could use a pointer about how Marcus Daniels
PJ> is producing those swell pdf documents, such as his Java tutorial.

That's an extended DocBook DTD/stylesheet for slides that uses an XSL
layout engine (a Java program).  It's one of these things that works
great once you know all the ways that it can break (and it can break a
lot of ways).

The Java source code markup was done with a program called java2html;
it is a clumsy solution.  (I would have tried to improve the XSL
DocBook conversion code to work like the URL above, but I didn't have
time.)


                  ==================================
   Swarm-Support is for discussion of the technical details of the day
   to day usage of Swarm.  For list administration needs (esp.
   [un]subscribing), please send a message to <address@hidden>
   with "help" in the body of the message.