-*- text -*- $Id: README,v 1.1 91/08/22 15:38:36 gnb Exp $

Readme for this release of the AtPlotter widgets, called
"plotter-V5-beta1".

This beta release is going to the bug-at mailinglist and a selected
set of volunteers.  I expect a full release in late September (in time
for inclusion in the X11R5 release tape???  How do I join?)
Submission to comp.sources.x is anticipated at about that time.

This is a complete rewrite of the AthenaTools plotter widget version 4.

It provides easlily used business-style graphics widget set with the
following features:

- Line and Bar graphs for business-style graphics.

- Scatter, X-Y and Contour plots for scientific style graphics. **

- Automatic or manual scaling of axis values, automatic selection of
  tic and subtic points.

- Very flexible text facilities, including math symbols, sub- and
  super-scripts, font changes etc.  This text facility can be used for
  legend names, graph titles, axis labels, tic labels, or attached to
  arbitrary points on the graph in either pixel space or user space.

- Unlimited number of plots on each graph, with each plot
  independently specified.  (Each plot on the graph is a different
  widget).

- Encapsulated PostScript generated that closely matches the screen
  output. (Not a raster dump; real PostScript.) Color postscript will
  be added when I get a color Postscript printer to test it on!

- Log ** or linear axes, or axis labeled at arbitrary points with
  arbitrary strings (which is very useful for labeling axes with
  dates, for example).

- Very flexible axis handling.  There are four axes on the graph, and
  any plot can be associated with either X axis and either Y axis.

- ``Frame'' axes that get their scaling etc. from another axis Object,
  on either the same or another graph.  This makes coordination between
  related graphs very easy.

- Easy access to application data.  The widget set is designed to access
  application data that is stored in an array of structures; it can pull
  data out of structures in either Float, Double or Integer
  format. Other data types are easily added.

- Registration functions for use with the Widget Creation Library

(** This feature is not yet (re-)implemented.)


INSTALLATION
------------

Unpack or unshar the files and make sure they all arrived (look in the
MANIFEST file for hints here).

Either:  
	Hack in Makefile.std according to taste
OR:
	Edit the Imakefile according to the instructions therein.
	Type "xmkmf" to make the Makefile.
	Type "make depend" to get the dependencies.

Type "make" to make the library.

If you have wcl:
	Type "make test" to make the Wcl-based test program.
	Type "XENVIRONMENT=Test.ad ./test" to run the test program.
	(or type "setenv XENVIRONMENT Test.ad; ./test" if you use csh).

Type "make sample_prog" to make the sample program described in the
Using document.

Type "./sample_prog" to run it.  No special libraries etc needed for
this program, and no resource files etc.

Type "make install" to install the library.

Type "make install.man" to install the man pages.

Type "make doc" to make Using.ps, the users guide, if required.

Type "lpr -Pyourprinter Using.ps" to print the manual.

Type "make man-ps" to make PostScript versions of all the man pages.

Type "lpr -Pyourprinter At*.ps" to print the man pages.

RTFM.

Start writing applications.


DOCUMENTATION
-------------

There are two main elements to the documentation.

The manual pages have the suffix .man.  They contain tbl commands (for
formatting the resource lists).  Many man programs require that man
pages be preprocessed by tbl before being installed in /usr/man (or
whatever).  Other man programs (such as SunOs) have a convention that
uses a comment in the first line of the man page source that tells man
to run preprocessors.  The Imakefile has a macro called TBL which is
used to turn .man files into .3X files for installation, depending on
local requirements.  There is another macro called MAN2PS that
converts to PostScript in the current directory for printing.

The most useful document is the Using.tex document.  If you got this
distribution via a tar file, the PostScript output of that is
available in Using.ps.  (This is not included in the shar distribution
as it is nearly 150kbytes.)

The Using document includes three figures drawn using xfig, one
embedded PostScript file (produced by the sample_prog.c test program)
and one tex-ified C program.  As currently set up, the Imakefile
assumes you have the transfig package (in particular, the fig2dev
program) to convert the fig output to PostScript and write a .tex file
to include the generated PostScript in the main document (using a
\special).  The .tex and .ps outputs from the xfig files are included
in the distribution, so you don't need transfig if your latex handles
PostScript (and in particular if your dvi2ps handles
\special{psfile=..} stuff).

If you got the distribution via shar files, the fig files will be in
uuencoded form (as they contain control characters).

It also assumes tgrind (to convert .c files to .tex files); but a
pre-ground version (along with the .sty file) is shipped and you
shouldn't need to rerun tgrind unless you change the sample program.

If you don't have a PostScript printer, you will probably need
transfig to convert the .fig files to (say) a LaTeX picture
environment, and some hacking of the Imakefile will be required.  You
will miss out in the embedded PostScript sample plot, however.

The file CHANGED-V4 documents the main changes since V4 - and glosses
over a whole lot more.  Porting from V4 is NOT trivial, unfortunately.

The file redraw-protocol talks about how the widgets in the set
interact.  It may be useful for widget developers.  It may be out of
date!

The file ToDo is a wishlist/joblist in no particular order.
Volunteers for these tasks gladly accepted.

The file ispell-words is a list of many words used in the
documentation that are not in the standard directory.  This includes
class and resource names.  Makes spell checking a whole lot easier!

NOTES TO BETA TESTERS
---------------------

The main problem is the unimplemented XY and contour plot classes.
Volunteers to do this work should contact me.  I have spent MUCH to
much time on this already to be translating stuff I don't need to use!

All problems, bug reports, tips, hint, spelling corrections etc gladly
received at the address below.  I am also really interested in
comments regarding the design of the widget set as a whole (this is my
first exercise in widget writing).  Hints on improving the
documentation would also be really useful.

Gregory Bond
Burdett, Buckeridge & Young Ltd.,
Melbourne  AUSTRALIA

gnb@bby.oz.au

22 Aug 91
