Re: Generating documentation from source code

[Marcus G. Daniels]

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

PJ> You are just begging for a giant hassle if you
PJ> try to make swarmdocs from the source and you are not already an
PJ> expert.

Ouch Paul, you're really bringing me down.  ;-)

All this stuff is setup to build right off the Swarm 1.4.1 CD-ROM
under NT.  (It ought to work on Windows 98 too, but of course anything
you do with '98 must be done with kid gloves, with please and thank
you at every turn.  Since it isn't a trivial procedure to run a build
of Swarmdocs to completion, '98 users can expect to reboot about seven
times before the thing finishes -- at least that has been my
experience.)

See, it's just that I *can't help* but respond since it took me more
than a week of Really Intense Suffering to get it all ported to
Windows and work just right off of read-only media.  ;-)

To build Swarmdocs off the CD-ROM, bring up Terminal (bash) and run:

ROOT=//D/ ${ROOT}common/scripts/build/build-swarmdocs

..where $ROOT is the UNC syntax for whatever drive the CD-ROM is
mounted as.  [Otherwise, the script can be copied and tweaked to look
for Swarm or other resources as desired.]

The sources to the SGML tools, etc. are in
ftp://ftp.santafe.edu/pub/swarm/docs-software.

If you're wondering: the reason I bothered to set all this up on the
CD-ROM is that we don't want potential documentation/tutorial
contributors to be scared off by the internal complexity of the
documentation system.  

Here's a review of the stuff that's needed to build Swarmdocs from source:

  1) Swarm
  2) Emacs
  3) Jade (the DSSSL system)
  4) DocBook DTD (describes DocBook SGML format)
  5) DocBook Stylesheets (the DSSSL/Scheme code)
  6) GhostScript (for conversion of EPS to bitmaps)
  7) Netpbm utilities (bitmap operations, e.g. cropping GhostScript output)
  8) cjpeg/djpeg (conversion of bitmaps to jpeg for HTML)
  9) png utilities (reference bitmaps are stored as lossless PNG)
 10) TeX (generation of PostScript)
 11) Gridturtle (sucked in for example text)

Perhaps for the next CD-ROM, we can figure out a reliable set of
RPMs for all this stuff, and distribute a Unix script for starting
the build?

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