Swarm User Guide:
================

This directory tree holds the current Swarm User Guide documentation
in raw SGML format.  The html, dvi, PostScript and RTF formats may be
generated with this package.

The file INSTALL in this directory gives detailed instructions on the
building and installation of the documentation.

------------
Requirements:

Building this documentation requires a number of packages:

* jade - a DSSSL parser, takes the SGML source included in this
  package, and the specified SGML DTD and DSSSL stylesheets (see below) 
  to generate the desired back-end: html, tex and rtf.
* GNU emacs - used to parse the in-code documentation
* jadetex - version of tex equipped with macros generated by jade
* gs - Aladdin Ghostscript version 4.00 or later
* dvips - converts dvi documents to Postscript
* pngtopnm, pngtops - converts png files to pnm and ps files, respectively.
* cjpeg - compresses an image file to a JPEG file 

Two further packages are also required: 

* The DocBook DTD (V3.1)

The SGML documentation is marked up using the DocBook V3.1 DTD
(formerly maintained by the Davenport Group - now maintained by
OASIS), aimed at computer documentation.  The current version can be
found at:

  http://www.oasis-open.org/docbook/docbook/index.html

The Official Docbook documentation, in both HTML and Docbook form, is
web server.  Copies of the Overview, User's Guide, Reference, and
Maintainer's Guide are available here as well. Note that only the
Reference has been updated for only DocBook 3.0 (not 3.1 as yet).
  
* The modular DocBook stylesheets 

The DocBook stylesheets are used to parse the Swarm SGML in
conjunction with the DocBook DTD and generate the html, tex and rtf
output.  The current version required is listed in the Release Notes
section in NEWS and can be found at:

  http://nwalsh.com/docbook/dsssl/


The file `configure' is a shell script to acclimate the creation of
the documentation to the oddities of your processor and operating
system.  It creates the file `Makefile' (a script for the `make'
program), which automates the process of building and installing the
documentation.  See INSTALL for more detailed information.

About the guide itself:
=======================

NB: This is Beta version of the content.

This document began with the Swarm Tutorials presented at the
SwarmFests 1998 and 1999 by Benedikt Stefansson of CASA Inc. (formerly
of the UCLA Department of Economics.  Swarm is discussed in three
stages of increasing detail.  The first part provides an introductory
treatment and description of Swarm. The second part provides a deeper
survey of the anatomy of a swarm program. The third part goes into
significantly greater detail on some elements of programming in Swarm
that users are likely to enounter as they build programs with
Swarm. Users are encouraged to explore the Swarm sample programs and
to visit the Swarm homepage:

  http://www.swarm.org

where they can find out the latest news and join the Swarm e-mail
community.

