Athena User's Guide source package
		  ==================================


This is the source package for the Athena User's Guide.  This is NOT
the document in a form intended for human consumption -- that is, it
is not in the form of an html or pdf document.  It can, however, be
converted into human consumable formats.

I use The Template Toolkit for this document.  The point of a
templating system is to provide a clean separation between form and
content.  Another common solution to the problem of providing
documentation in disparate forms involves conversion from one form to
another.  The draw back of the conversion approach is that different
forms have different needs.  For example, a figure can be placed in
close proximity to the referring text in html, but a page-based pdf
document requires the use of floats to position figures in the text.
Any conversion scheme will necessarily prefer the layout needs of the
original format and make compromises during the conversion process.

A templating scheme, on the other hand, is better able to address the
needs of different presentation media by tailoring the process of
conversion of the templates into the source for the medium.  In this
case, I use one set of templates to generate html and different set --
with different characteristics -- to generate latex, which is then
compiled into a pdf file.  A third set of templates is used to
generate pod.

The templates are peculiar and slightly difficult to read.  The
template tags are all surrounded by special mark-up that looks
something like this:
  [% INCLUDE imageref text="the figure above" label="dxas" %]
This example is a tag used to provide a sensible reference to a figure
in the text of the document.  Despite the proliferation of those odd
tags, the templates used to format actual document pages are not
really that difficult to read.


Using The Template Toolkit
==========================

To convert the source into html, pdf, or pod, you will need to install
a few things on your computer:

  1. The perl interpreter
  2. The Template Toolkit
  3. These perl modules:
       a. Image::Size
       c. Syntax::Highlight::Perl

To convert the latex document into pdf, you will need:

  1. A complete tex installation, such as teTeX or TeXlive
  2. Various latex styles, including amsmath, amsfonts, floatflt,
     fancybox, fancyhdr, keystroke, varioref, and hyperref.  Some of
     these may already be included in your tex installation


Making the document
===================

Initialization:
   Run the configure script in the top directory of this package:

      ./configure

   This will configure the various files in the bin/ and etc/
   directories so that the document can be correctly built on your
   computer.


HTML:
   To generate the html files issue the following command:

      ./bin/build

   You can force every template to be processed using the -a flag:

      ./bin/build -a

   You can process individual pages by specifying them on the command
   line:

       ./bin/build bkg/norm.tt hephaestus.tt


PDF:
   To generate the latex files issue the following command:

      ./bin/tex

   This script takes all the same command line flags and arguments.

   To compile the latex files to pdf, do the following:

      cd tex/
      pdflatex athena.ltx
      pdflatex athena.ltx

   You need to run pdflatex twice to get all the cross references
   right.

   If TeXlive issues two spurious warnings at startup that have
   something to do with not being able to find font metric files, you
   can safely ignore them by hitting return each time.  Similarly,
   most errors from varioref can safely be ignored.


POD:
   To generate the pod files issue issue the following command:

      ./bin/pod

   This script takes all the same command line flags and arguments.


Using the document
==================

On a web server:
   The html/, images/, and data/ directories can simply be dropped
   onto a web server.  All internal linking is relative, so all links
   will be resolved as long as html/, images/, and data/ are placed at
   the same level of the directory tree.

   You will want to copy the tex/athena.pdf file into the html/
   directory on your server so that the link to the PDF file in the
   navigation bars will resolve correctly.

   The "package" script that comes with the document package will
   bundle everything up into a zip file for easy transport.  Just
   unzip it in the correct location on your web server.

For use with Athena:
   A little script is provided for moving the document into a location
   where it can be used by Athena.  Simply run the command:

      ./install

   and the contents of the pod/, html/, images/, and data/ directories
   will be copied into the location that Athena expects.  Note that
   this script uses one of Athena's modules to determine that
   location, so Athena needs to already be installed on your machine
   for the installation script to work.

   You will probably need root (or sudo or administrator) privilege
   for the installation script to run.