README file for diane (diane is a notation enhancer)

Created by Douglas M. Auclair, dauclair@hotmail.com
Copyright (c) 2000, Douglas M. Auclair under the GPL 
(www.fsf.org/copyleft/gpl.html)

DESCRIPTION
===========
I needed to share-out notation (UML, OMT, or Booch) diagrams of a
software system I'm developing in a collaborative environment.  The
modelling tools I have (Rational Rose and ObjectDomain) did not create
usable web documents.  I created diane to answer this need.

diane reads information from configuration files describing the
Logical View packages of a model, and from those files associates a
diagram with each package.  To see diane in action, review the tutorial.

One calls diane through a web-server, such as apache.  To call the
package hierarchy of the model of the tutorial, one would enter (e.g.)
http://127.0.0.1/cgi-bin/diane?diane+Overview (given that one is using
loopback for the server URL) in a web browser.  The GET values (the
two entries after '?') are the model name (no spaces, please) and
package name (again, no spaces.  Overview is a special keyword that
shows all packages of the model in summary and in detail).

REQUIREMENTS
============
* I wrote diane entirely in Dylan.  A Dylan compiler must be
  installed.  You can get the source or the binaries for d2c (a
  multi-platform Dylan compiler) from www.gwydiondylan.org  
* For Windows systems, you must have Cygnus installed
  (http://sources.redhat.com/cygwin/)
* Apache server installed and working (www.apache.org) (I refer to
  where apache operates as apache/ from now on)
* Have the html library (available from the same download source) installed.

INSTALLATION
============
* Make sure you've installed the html library first.
* Unzipping diane.tgz creates a hierarchy of directories (diane/, diane/meta/, 
  diane/imgs/ and diane/uml-viewer/), a tarred tutorial file, the README files 
  and a top-level makefile.  Type 'make', which will eventually create the
  diane executable in diane/ 
* Move the diane executable to (or below) apache/cgi-bin/ (DIANEDIR).  
* Move imgs/ to (or below) apache/htdocs/
* Move meta/ to DIANEDIR.  Modify each file in meta/ so that they
  contain your server information 

USING diane
===========
* Read the tutorial.README to have diane serve the UML diagrams
  describing herself.
* Create a subdirectory of meta/ of your model's name (MODEL) and copy
  all the files from meta/diane/ to MODEL.  Modify these files to
  describe your model (instead of diane's) 
* Direct your modelling tool to output all the diagrams as
  web-readable image files (.png|.jpeg|whatever).  Put these files in
  or under apache/htdocs/ (DIAGRAMS) and modify MODEL/img-src.dat's
  diagrams: property to point to DIAGRAMS
* diane will now parse and serve your model's information when given
  the GET values diane?<your model's name>+Overview

TODO
====
diane isn't even a dream of a complete notation enhancer:  it's good
enough for the job at hand.  The following things can be added along
the way to approach completeness:

* diane can parse neither class attributes nor class operations in
  packages.uml.  Add that ability.
* packages.uml is, of course, not uml by any stretch, and it doesn't
  look anything at all like the output files of modelling tools such as
  Rational Rose.  Changing the format to be exactly compliant to Rose's
  .mdl files (and, subsequently, changing diane's parser to handle that
  format) will save time for diane's users.
* As the output files have location and dimensions of the UML
  elements, have diane generate image files from the descriptions, and
  save the users another step

ISSUES?
=======
It seems that Apache takes the GET arguments and convert them into the
argument string array to main().  diane takes advantage of this:  she
does not get the arguments from the environmental variable
QUERY_STRING.  This allows easy debugging while on the command-line.
However, if you use another web-server that does not do this
conversion, diane will not work.

CHANGES
=======
I've broken off standard CGI functionality:  file-parsing and http serving
to the html library.  Both diane and the xml-server use this library for
CGI chores.