Re: documentation and such

[Alex Lancaster]

>>>>> "MD" == Marcus G Daniels <address@hidden> writes:

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

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

As an aside on javadoc, I've found a Doclet which will convert javadoc
comments to Texinfo format, so soon Java users will be able to view
the Swarmdocs (or model docs for that matter) in `info' format as can
the Objective C users via docbook2texi, currently.

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

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

True, but Norm Walsh is certainly putting more effort into the XSL
stylesheets now and in the long term, than the DSSSL, so I don't think
that DSSSL-equivalent quality renderings are too far off...

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

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

One thing that also recommends the XSL approach for all the Swarmdocs
in the long term, is that the XSL route generally implies fewer
packages to work than DSSSL: 1) just about any Java VM; 2) some jar
files to provide the processor functionality; and 3) the XSL
stylesheets themselves.  Because XSL is intended to work only with
XML, and not SGML, and XML is lighter than SGML, it obviates some of
heavier parts of the toolchain that are required by DSSSL (which was
originally designed to support the full SGML spec).

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

Yep, integration with Mozilla (or other browsers) is certainly the way
of the future, however it's always nice that with XML one can produce
(say) texinfo docs for those times when firing up bells 'n whistles
browser is just overkill...

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.

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

The one part of XSL that is a little lagging right now, is support for
printed docs.  Currently the DocBook XSL stylesheets take the XML and
generate an intermediate XML format, called XSL-FO (FO for "flow
objects", which is an XML spec for printed documents, think of it as
something like TeX for XML) and then you use a FO -> PDF converter to
generate the final output.  Unfortunately the W3C spec for XSL-FO
itself, is not fully stable, and so both the DocBook -> FO as well as
the FO -> PDF engines (PassiveTeX and RenderX are a free and
commercial engine, respectively) are often a little out of sync.

However, I expect that this situation will stabilize pretty quickly
over the next 6 months or so, since there is a huge userbase tooling
up on XML and much major vendor support for XML in general (Microsoft,
for example, although we'd be aiming for a 100% free toolchain, of
course).

Alex
-- 
Alex Lancaster * address@hidden * www.santafe.edu/~alex * 505 984-8800 x242
Santa Fe Institute (www.santafe.edu) & Swarm Development Group (www.swarm.org)







































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