$Id: README,v 1.11 90/05/09 22:10:48 pturner Exp Locker: pturner $

Release 1.04 Beta test

About grtool:

Grtool is Public Domain software written by Paul J. Turner.
I'm using some code from Touchup (the file completion code)
so observe the Copyright stated there (in io.c).
Use grtool at your own risk.

History:

Grtool is a port of a curses based program called gr I wrote a couple of
years ago.

-----------------------------
Known problems:

Because of the number of windows used by grtool, there
   may not be enough left to run grtool. Close a few windows
   and try again, repeat as needed. Doug Roberts (roberts%studguppy@LANL.GOV)
   pointed out that 'MAKEDEV win2' adds win64 -> win95
   allowing grtool to run without having to kill windows.
   Thank you, Doug.

Floating point errors are trapped by a handler defined in pars.y
   and generates longjmps to nowhere on some floating point errors
   outside the routines in pars.y. This generates segmentation
   faults. You'd think this would be fixed by now.

Log scaling is something of a mess, but there is light at
   the end of the tunnel. The data is still transformed
   but work is in progress to make this unnecessary.

The HP Laserjet drivers seem to leave empty files in /tmp (or
   wherever the temporary files are written) - I'm
   not sure why, I occasionally have to clean them out.

----------------------------------------------------

Recent additions and future directions:

(some of these have been around in 1.03 but, as I never
announced 1.03, they are included here)

New driver for the HP laserjet series II - support for 75, 150, 300 dpi.

Modifications to the SunView driver and the HPLJ driver - 
  dotted and dashed lines are working (almost) properly.
  There will still be problems with large data sets.

Modifications to the PS driver, addition of the Bounding Box
  specifier, and fixes so that dotted/dashed lines look better.
  courtesy of Jeff Treece, treece@sabbagh.com. As I have limited
  access to a PS printer for testing, I've included the old driver 
  in the distribution just in case there are problems - in the file
  ps.org. If you have problems, copy ps.c to ps.new and copy ps.org
  to ps.c and rebuild. Please send me a note on any problems you
  encounter with the new driver.

The Edit String button in Strings & Things works, there is a roundoff
  problem that leads to the image of the old string and the new
  to not correspond exactly in some cases.

The running average item has been modified to do running:
  averages
  medians
  minimums
  maximums
  standard deviations (had a bug in 1.03 fixed in 1.04)

There is a new item in transformations 'Sample' that allows points
to be sampled from a set by a start and step or a logical expression.

There was a bug in the 'Load and eval' function in transformations that
led to an incorrect step size.

There IS a hollow circle symbol, hidden by the dot symbol, I'll try
to resurrect it without breaking parameter files.

Changing the printer definition string had no effect in the printer menu.

The man page is in much better shape, although I've gotten
nowhere with a LaTex version of the documentation (I'm
only shipping the man page these days).

The locator is now capable of delivering the angle from the
fixed point (or 0.0 by default), this angle is based on the
world coordinate system (really just rad_deg*atan2(dy, dx) +
180.0) so there can be distortion wrt to the screen.

Added an item in the Files popup similar to the Write sets button
in Setops, but allows the parameter information that is usually
written to a parameter file to be imbedded into the data file
(optionally, of course). This could prove to be a real convenience.

I'm experimenting with scrollbars on all the popups, it didn't cost
anything in terms of winfds, so what the heck. Does it help cut
down the clutter?

The installation is now done in the Makefile (thanks to the timely 
arrival of calctool). Problems?

Printer spooling strings may now be set using environment variables:
GR_HP_PRSTR1 - HP 7550
GR_HP_PRSTR2 - HPGL cartridge in a Laser Jet II
GR_PS_PRSTR  - Postscript printer
GR_HPLJ_PRSTR  - HP laserjet series II
Just 
      unix% setenv GR_PS_PSTR "lpr -Premote_lp -h"
or whatever. These can also be set in the Makefile.

Hardcopy device can be set in the environment using 
GR_HDEV
Just 
      unix% setenv GR_HDEV 5
or whatever. This can also be set in the Makefile.

Select size of symbols - not really very useful as I'm using the
Hershey symbol set and the solid symbols don't look too hot.

The copy set item in setops has a new option that allows the
from set to be copied to the next available set.

There is a move set option in setops. This moves the
contents of the set, AND the legend string, symbol/line type.

Made modifications to the ticks popup. The toggles are displayed
in menu form only - cutting down the real estate needed to display
this popup. Log scaling has been changed and is hopefully easier
to work with. Data is still transformed. Doing log plots the old
way is still there, you should use one or the other but not both.

Added an entry that allows the number of tick marks to be changed
when autoscaling the plot.

Added a new choice to 'Evaluate formula' - allows for a new
set to be generated for the result rather than overwriting.
Also a new item for parametric functions.

Lines, strings, boxes, and legends can now be located in viewport
coordinates. This makes these items stay put when you change the scaling
of the plot or modify the viewport. This is the default from now on.
I don't anticipate any incompatibilities with old parameter files,
although for legends you should re-write those old parameter files as 
you`ll generally want the legend location in viewport coordinates.

------------------------
There is a way of plotting files outside the set structure imposed
by grtool - this is an experimental but potentially useful item.
To use this section (which is not presently complete) you'll need to
uncomment the make variable EX in the Makefile. The interface is in the
Files popup, put the filename or the name of the command (if a pipe),
at the space for file, select the source (default is disk), select the
file type (default is x y) and set the ON/OFF switch. There are presently
only 2 types of files that can be handled:

X  Y

and 

X Y string

A blank line is indicates to the scanning routine that the pen will be
moved to the next point read. In the string type, Sscanf is used to get the string, 
so anything after the first blank (in the string) will be skipped.
As in

2 3 golly golly

only the first 'golly' will be printed at (2,3).

Linestyles and colors (or pen width) can be selected by 
%l <linestyle number>
and 
%c <color>
The type of file can be set within the file by
%t
for text and 
%d
for x,y type. The '%' MUST be in column 1. A '#' in column 1 indicates
a comment.

Here is an example data file for use with the 'plotfile' feature, this
is in ./examples as extest.d:

#begin data
#sample plot file for grtool - for use outside the set structure
# x y data
1.000000 1
2.000000 2
3.000000 3
#the following blank line forces a move to the next point

4.000000 4
4.500000 4.5
# select linestyle 3
%l 3
5.000000 5
6.000000 6
7.000000 7
8.000000 8
9.000000 9
10.000000 10
#select linestyle 1 (a solid line)
%l 1
#data is text
%t
11.000000 10 abcdefghijklmnopqrstuvwxyz
12.000000 1 gollllllllly
13.000000 5 golly golly
#switch back to x y format
%d
18 18
19 19

38 38
39 39
#end data
-----------------------------------------------------------

The future: 

I probably won't be doing an XView version, due to time
constraints and doubts as to the usefulness of XView.

-----------------------------------------------------------

Credits (the short list):

Antonio M. Baptista for supplying the environment in which grtool
was written.

Ole H. Nielsen for many suggestions and comments on the interface
and improvements to the PostScript driver.

Douglas N. Arnold for suggesting the 'Load and eval' item in
transformations.

Phil Moore for helping out with the man page.

Aritomo Shinozaki for help with log scaling - hopefully I will
have log plots fixed in the X version (if I ever get to it).

Jim Hudgens for the PostScript driver and initial encouragement.

-----------------------------------------------------------

There are 6 demos in the examples subdirectory, run with

grtool test.dat -p test.par /* also try grtool -p test.par test.dat
grtool test2.dat -p test2.par
grtool test3.dat -p test3.par
grtool test4.dat -p test4.par
grtool del.triang vor.diag vor.dat -p vor.par
grtool errbar.dat -p errbar.par
grtool -p testc.par

or, (assuming the grtool binary is in the current path) just run the script
Demo located in ./examples.

The first two are just regular line/scatter graphs.
the third is a linear-log plot, the fourth is a plot
of the locations of part of the nonzero elements of a 
band matrix someone around here had. The fifth is a test
of error bars, the sixth is a Voronoi diagram and Delauney
triangulation and the last is a demo of
the special characters (ignore the warning messages).

Comments to:

Paul J. Turner		     
Department of Environmental Science and Engineering
Oregon Graduate Institute of Science and Technology
19600 NW von Neumann Dr.
Beaverton, OR  97006-1999
pturner@cse.ogi.edu
tektronix!ogicse!pturner     
