gradu - graphics dump
by Chris X Edwards
Fri May 10 03:34:20 PDT 2002

INSTALL
-------
This program is pretty simple. The make file should take care of
compiling with a simple:
[~]$ make
To install it into a location that I consider sensible, use:
[~]$ make install

This program is really a way to show off the abilities of the GNU
Plot Utilities. This means that you need to have libplot installed and
ready to link to. To get this library, have a look here:
http://www.gnu.org/software/plotutils/plotutils.html

CONCEPT
-------
The idea for gradu came from the frustration of not being able to
plot simple datasets of 2d vectors. I was doing some experiments with
vector geometry which produced quite a lot of data and I couldn't find
a simple way to have a look at it graphically. I found the GNU
plotutils package which seemed very promising, but its included
program, graph, was rather heavily oriented to X vs. Y style "graphs".
My requirements were much less structured and certainly not oriented
towards traditional mathbook graphs.
  The libplot library contained exactly the functionality I was
looking for, but I couldn't find a program that put it to use in a
general way. I'm sure opinions vary, but I believe that a program like
"graph" should be two parts. One part to calculate where all the lines
of a particular graph are and another part to actually plot it. gradu
is an attempt to be this second stage.
  With gradu, a user has all of the functionality of the libplot
library without either having to write their own C program, or
circumventing the intent of a program like "graph" to get unorthodox
results.
  A program could be written that generated graphs and then fed the
geometry data to gradu. I'll leave that for someone else. Another
example is the follow up program I wrote, vmaster, which takes 3d
data sets and evaluates them to 2d data sets. By piping vmaster's
output to gradu, one can input a stream of 3d vector geometry and see
an image as a result. All of this is inspired by the very modular Unix
way of doing business.

STRATEGY
--------
The idea for functionality was to have a system that was as flexible
as possible for a wide variety of sensible input styles. I was
particularly attentive to the case where a list of coordinates streams
in unattended by anything else. This creates the functionality of a
dot-to-dot experience. From this simplist case, the input stream can
optionally be embellished to provide things like relocating the pen,
relative coordinates, true arcs, properties, text, and more.
  One of the keys to the flexibility is the parsing routine. The
general strategy is that characters that aren't relevant get replaced
with spaces and spaces are the delimiters. This means that whatever
crazy syntax your input may have, there probably isn't a lot that
needs to be done with it to make it work out. Certainly a quick visit
to the sed command should be able to cure any problems.
  The libplot library is pretty elaborate. There are a lot of fancy
features. This required that the data be able to specify commands for
various fancy operations. These single letter commands can be placed
anywhere in the input line. The numeric values supplied, if any, will
of course need to be in the correct order, but this really provides a
huge degree of flexibility.
  Data can be specified as files on the command line or piped in using
the finest Unix traditions. Default output produces an X window with
the data plotted. When making output files such as postscript or gifs,
simply redirect output to the desired file name using the Unix ">". 

CAVEATS
-------
I wrote this program with a fairly simple problem at hand. I did try
to do it right and lay the foundation for a very good system. The fact
remains that once I got it doing what I needed it to do, I didn't get
too crazy about testing all the other functionality. This includes
things like text handling, widths, and styles. I also have noticed a
problem when animating in X. It can cause some kind of infinite loop.
I was content with gif animations and they work fine, so no serious
debugging was done with the X ones.

LEGAL NONSENSE
--------------
This program is released under the GNU Public License (GPL). It is so
flawed that it should be considered dangerous to whatever you're
doing, your data, your physical computer, your health, and sanity. Do
not use it under any circumstances. I am not responsible for any silly
thing either you or I do with regard to this program.
