             Instructions for the Plot package for Unix

     This file explains how to compile,link, and use the programs in the
MIIPS Plot package on a Unix machine.  The package consists of high level
programs to create XY plots from one or two text files, a library of plot
subroutines for creating custom applications, and several demonstration
programs for XY, histogram, contour, mesh, Hammer-Aitoff, and animation
plotting.  Some features of the programs are:

1) XY, histogram, mesh, contour, and Hammer-Aitoff plotting
2) Full interactivity with the plots:  adding annotation, changing colors,
replotting subsections, arithmetic operatons on data, resetting axis 
parameters, reading cursor values, drawing vectors, etc.
3) Linear and antilog axes labeling
4) Any number of points, any number of simultaneous plots for XY plotting
5) Additional optional labeling for top and right of XY graph
6) Any size array for contour or mesh plotting
7) Text and annotation can include subscripts and superscripts, and
Greek letters, and symbols, and can be added interactively or hard coded.
8) Output can be directed to more than one plot device at a time and
to a standard plot file
9) Output can later be directed from the standard plot file to any supported
plot device or format, with offsetting, scaling, and rotation
10) Supported output devices and formats are:  graphics terminals, xterm,
xgterm, VersaTerm Pro, Enhanced SAOimage, postscipt, and encapsulated
postscript.  Support for Grinnell, Houston Plotter, Lasergrafix,
Printronix, Ramtek, Tektronix 4662 Plotter, and Trapix is available upon
request.
11) The quality is suitable for publication in scientific and engineering
journals and has been so used for over 25 years.

     To use the compiled versions on a Linux system with Intel processor, or
on a Mac OS X system with Intel processor, download plot_linux_executables.tar.gz 
or plot_macosintel_executables.tar.gz, respectively from the link at
http://www.chara.gsu.edu/~gudehus/plot.html, and then extract the execute
images and other files. For Mac OS X PPC systems, download and extract the file
plot_macosppc_executables.tar.gz.  The compiled versions should work on any 
of the above mentioned systems, but if the system libraries have been changed
from their default versions some programs might crash.  One known vulnerability
is the FORTRAN call to DTIME.

After the executables are on your system, you should define some aliases
which are described further below.

     If you wish or need to recompile, you can download the file
plot_unix_source.tar.gz from the download link at
http://www.chara.gsu.edu/~gudehus/plot.html, and then extract the source
code and other files.
     Once you have plot_unix_source.tar.gz available on your Unix 
machine, just enter
  gzip -d plot_unix_source.tar.gz
  tar -xf plot_unix_source.tar
from a desired directory location.  Set default to the newly created 
plot directory and enter
  make linux
for Linux systems, or
  make macosppc
for Mac OS X PPC systems, or
  make macosintel
for Mac OS X Intel systems, or
  make ultrix
for Ultrix systems, or
  make unix
for other Unix systems.  It is also possible to use the command
  make -f makefile-plot.pgf77
for Linux and Mac OS X Intel systems, for example.  Ignore any 
warning messages.

     The programs will compile and link on a DECstation with the 
default compiler.  For Linux on Intel processors, and for Mac OS X
on Intel processors, you will need to have installed the Portland 
Group f77 compiler (http://www.pgroup.com).  A free 15-day trial 
version of their compiler is available from their website.  Their 
compiler also works for Solaris on Intel processors, but I have not 
tested this.  Presumably, the linux makefile should work for their 
compiler on Solaris as well.  Other brand compilers may possibly
work with this code but I have not investigated them.  For Mac OS X 
PPC, you will need to have installed the Absoft Pro Fortran compiler 
(http://www.absoft.com).  A free 30-day trial version of their 
compiler is available from their website.  The Absoft f77 compiler 
doesn't support variable FORMAT expressions which necessitated 
creating a special set of files just for that compiler.  Also, 
the Absoft compiler has a bug with handling %REF with character data.  
A special usrinp.for, i.e., usrinp_char.for, was created to handle 
this problem.  New subroutines for this and other limitations are 
located in the subdirectories mac_os_ppc.  The compiled PPC version 
will also run on Macintoshes which use the Intel processors and are 
able to run Rosetta.  The Portland Group's compiler for Mac OS X 
with Intel will also work with the Linux make file.
     For other Unix flavors the default f77 compiler may or may not work.
A compatible compiler should support BYTE data type, ENCODE, DECODE, %REF,
%VAL, variable FORMAT expressions, CARRIAGECONTROL keyword, and PARAMETER
statement with or without parentheses.  For the C code files, the
built-in compiler will work.

A brief description of the source code files follows.

In the directory plot, one should have the files:

   Name                                         Description
alogaxis.for                            Lower level plot routine
alogcode.for                            Lower level plot routine
alogdeccode.for                         Lower level plot routine
alogdecode.for                          Lower level plot routine
apple.for                               Lower level routine for postscript
appleplot.for                           Lower level routine for postscript
arrowhead.for                           Lower level plot routine
ascii1.dat				Test file for xyplot_ascii.exe demo
ascii2.dat				Test file for xyplot_ascii.exe demo
ascii3.dat				Test file for xyplot_ascii.exe demo
ascii4.dat				Test file for xyplot_ascii.exe demo
ascii5.dat				Test file for xyplot_ascii.exe demo
axis.for                                Lower level plot routine
bell.for                                Routine to ring the bell
calc.for                                Lower level plot routine
color_24_triplet.for                    Lower level plot routine
color_input.for                         Lower level plot routine
color.for                               Program to interconvert colors
                                        of various bit numbers
colormode.for                           Lower level plot routine
colormode_background.for                Lower level plot routine
contourdem.for                          Demo program for contour plotting
contourplot.for                         High level subroutine for 
                                        contour plotting
cplotc.for                              Lower level plot routine
crosshair.for                           Lower level plot routine
cube.for                                Demo program for rotating cube
cubeplot.for                            Lower level plot routine
datalevel.for                           Lower level plot routine
decode_intervals.for                    Lower level plot routine
delay.for                               Routine to produce a delay
display-plotting_availability.dat       List of available plot devices
errorbar.for                            Lower level plot routine
fillmode.for                            Lower level plot routine
findplot.for                            Lower level plot routine
get_dp_availability.for                 Lower level plot routine
hammer_aitoff.for                       Transforms angles to Hammer-Aitoff
                                        X and Y
hammer_aitoff_dem.for                   Demo program for Hammer-Aitoff plotting
hammer_aitoff_grid.for                  Plots a Hammer-Aitoff grid
histogram.for                           Lower level plot routine
imtoolchecksum.for                      Required lower level routine
issubsup.for                            Lower level plot routine
keyboard.for                            Lower level plot routine
limit.for                               Lower level plot routine
line.for                                Lower level plot routine
line_symbl.for                          Lower level plot routine
makefile                                General makefile to compile and
                                        link all the executables
makefile-plot.macosppc                  Makefile for Mac OS X PPC, w/Absoft
                                        compiler.
makefile-plot.pgf77                     Makefile for Linux/Mac OS X, 
					Intel w/Portland Group compiler
makefile-plot.ultrix                    Makefile for Ultrix
makefile-plot.unix                      Makefile for other Unix
meshdem.for                             Demo program for mesh plots
meshgen.for                             Lower level plot routine
meshplot.for                            High level subroutine for mesh plots
meshplot1.for                           Helper routine for meshplot
nhint.for                               Required lowel level routine
number.for                              Lower level plot routine
penmode.for                             Lower level plot routine
plot.for                                Lower level plot routine
plot_linux_executables.com              Command file to tar and compress
					the executables for Linux
plot_macosintel_executables.com		Like above but for Mac OS X Intel
plot_macosppc_executables.com		Like above but for Mac OS X PPC
plot_ultrix_executables.com             Like above but for Ultrix
plot_unix_executables.com               Like above but for Unix
plotcom.for                             Program to plot from plot file
plotdevices.for                         Lower level plot routine
plotdevices2.for                        Lower level plot routine
plotdevques.for                         Lower level plot routine
ploterrs.for                            Plot package error messages
pltdev.for                              Lower level plot routine
pltread.for                             Lower level plot routine
pltwrite.for                            Lower level plot routine
proj.for                                Lower level plot routine
prtmsg.for                              Required lower level routine
resettek.for                            Lower level plot routine
sao.for                                 Lower level plot routine
sao_curn.for                            Lower level routine for SAOimage
sao_display_vect.for                    Lower level routine for SAOimage
sao_draw.for                            Lower level routine for SAOimage
sao_erase_cursor.for                    User routine to erase cursors
sao_load_vlt.for                        Lower level routine for SAOimage
sao_vect.for                            Lower level routine for SAOimage
saocaption.for                          Lower level routine for SAOimage
saoconvlt.for                           Lower level routine for SAOimage
saoeras.for                             Lower level routine for SAOimage
saofirst.for                            Lower level routine for SAOimage
saoplot.for                             Lower level plot routine
saostart.for                            Lower level routine for SAOimage
scale_axis.for                          Lower level plot routine
scan.for                                Lower level plot routine
scan_simple.for                         Lower level plot routine
scansl.for                              Lower level plot routine
si_subs.c                               Lower level routine for SAOimage
si_subs.h                               Lower level routine for SAOimage
strludef.for                            Required lowel level routine
symbol.for                              Lower level plot routine
symbols.for                             Demo program to plot symbols
symgen.for                              Routine to generate symbols
symgengr.for                            Routine to generate Greek letters
sys_keyin.c                             Lower level plot routine
t.txt                                   Explanation for simple demo programs
t1.for                                  Program to demonstrate vectors
t2.for                                  Program to demonstrate key press
t3.for                                  Program to demonstrate fill
t4.for                                  Program to demonstrate vector styles
t5.for                                  Program to demonstrate axis drawing
t6.for                                  Program to demonstrate axis
                                        drawing with user input
t7.for                                  Program to demonstrate pausing
t8.for                                  Program to demonstrate antilog
                                        axis drawing
t9.for                                  Program to demonstrate the 
                                        symbol subroutine
t10.for                                 Program to demonstrate changing
                                        the data level
t11.for                                 Program to demonstrate pen widths
t12.for                                 Program to demonstrate the line
                                        subroutine
t13.for                                 Program to demonstrate the 
                                        line_symbl subroutine
t14.for                                 Program to demonstrate 
                                        interactive commands
t15.for                                 Program to demonstrate circles
t16.for                                 Program to demonstrate point plot mode
t17.for					Program to write a simple 1-inch square
tek.for                                 Lower level plot routine
tekcon.for                              Lower level plot routine
tekpau.for                              Lower level plot routine
tekplot.for                             Lower level plot routine
textcnch.for                            Lower level plot routine
trace.for                               Lower level plot routine
transform.for                           Lower level plot routine
transparent_mode.for                    Program to go from Tek to terminal
transparent_mode_x.for                  Program to go from Tek to terminal
                                        for xterm
transparent_mode_xn.for                 Program to go from Tek to terminal
                                        for xterm without erasing plot
transparent_to_tek.for                  Lower level plot routine
vectmode.for                            Lower level plot routine
where.for                               Lower level plot routine
xyplohdem.for                           Demo program for histogram plots
xyplot.for                              High level subroutine for XY plots
xyplot_ascii.for                        Program to plot from one or more ASCII
					files
xyplot_f.for                            Lower level plot routine
xyplot_setup.dat                        Setup file for xyplot_ascii.exe
xyplot_setup1.dat                       Setup file for xyplot_ascii.exe in demo
xyplot_setup2.dat			Setup file for xyplot_ascii.exe in demo
xyplot_setup.for                        Lower level plot routine
xyplotdem.for                           Demo program for XY plots
xyplotdem2.for                          Demo program for XY plots

In the directory plot/include one should have the files:

   Name                                         Description
plotpar.for                             Plotting parameters include file
sao_default_vlt.for                     Default lookup table for
saofacts.for				Common block for Enhance SAOimage

In the directory plot/mac_os_ppc one should have the files:

   Name                                         Description
apple.for                               Lower level routine for postscript
color.for                               Program to interconvert colors
                                        of various bit numbers
contourplot.for                         High level subroutine for
                                        contour plotting
crosshair.for                           Lower level plot routine
cube.for                                Demo program for rotating cube
errorbar.for                            Lower level plot routine
hammer_aitoff_dem.for                   Demo program for Hammer-Aitoff plotting
imtoolchecksum.for                      Lower level routine for named pipes
line.for                                Lower level plot routine
line_symbl.for                          Lower level plot routine
meshdem.for                             Demo program for mesh plots
meshplot.for                            High level subroutine for mesh plots
number.for                              Lower level plot routine
plotcom.for                             Program to plot from plot file
plotdevices.for                         Lower level plot routine
pltread.for                             Lower level plot routine
pltwrite.for                            Lower level plot routine
scale_axis.for                          Lower level plot routine
si_subs.c                               Lower level routine for named pipes
si_subs.h                               Include file for the above file
t2.for                                  Program to demonstrate key press
t9.for                                  Program to demonstrate the
                                        symbol subroutine
t14.for                                 Program to demonstrate
                                        interactive commands
xyplohdem.for                           Demo program for histogram plots
xyplot.for                              High level subroutine for XY plots
xyplot_ascii.for                        Program to plot from one or more ASCII files
xyplot_setup.for                        Lower level plot routine

In the directory plot/utilities one should have the files:

   Name                                         Description
alpha.for                               Character processing routine
daxpy.for                               Routine for vector math
dcd.for                                 Routine to help usrinp
dcopy.for                               Routine for vector math
ddot.for                                Routine for vector math
decode_decimal.for                      Lower level routine
dmnmxme.for                             Lower level routine
do.for                                  Routine to help usrinp
dspdi.for                               Routine for matrix math
dspfa.for                               Routine for matrix math
dswap.for                               Routine for vector math
dynamic.for                             Routine to obtain dynamic memory
dynamic_c.c                             Routine to obtain dynamic memory
error.for                               Required lower level routine
get_os_bytes.for			Routine to get OS number of bytes
get_os_bytes_c.c			Routine to get OS number of bytes
idamax.for                              Routine for vector math
inel.for                                Routine to help usrinp
linfit1d.for                            Routine for 1-dimensional linear
                                        least squares fitting
linfit1d1.for                           Helper routine for linfit1d
linfit1d2.for                           Helper routine for linfit1d
makefile                                General makefile for the utility files
makefile-plot_utilities.macosppc        Makefile for Mac OS X PPC
makefile-plot_utilities.pgf77           Makefile for Intel processors
makefile-plot_utilities.ultrix          Makefile for Ultrix
makefile-plot_utilities.unix            Makefile for other Unix
matrixinv.for                           Routine for inverting a matrix
matrixinv1.for                          Helper routine for matrixinv
message.for                             Routine to display messages
nel.for                                 Routine to help usrinp
neld.for                                Routine to help usrinp
opencf.for                              User routine to open a character file
pol.for                                 Routine to evaluate a polynomial
pol1.for                                Helper routine for pol
polinterp1d.for                         Routine for 1-Dimensional
                                        polynomial interpolation
polinterp1d1.for                        Helper routine for polinterp1d
realindex.for                           Lower level routine
release_memory_c.c                      Routine to release dynamic memory
save.for                                Routine to help usrinp
scalpol.for                             Helper routine for linfit1d2
strkey.for                              Routine to help usrinp
syminv.for                              Routine to solve linear equations
usrinp.for                              User input routine

In the directory plot/utilities/mac_os_ppc one should have the files:

   Name                                         Description
dcd.for                                 Mac OS X/Absoft version
linfit1d1.for                           Mac OS X/Absoft version
nel.for                                 Mac OS X/Absoft version
neld.for                                Mac OS X/Absoft version
opencf.for                              Mac OS X/Absoft version
save.for                                Mac OS X/Absoft version
usrinp.for                              Mac OS X/Absoft version

The makefile will also create the object libraries, plot_u.a and
and utilities/utilities_u.a which can be used to link with any user
written programs if desired.

For whichever method you use to install the executable files, create the
aliases:
  alias a 'transparent_mode.exe'
  alias ax 'transparent_mode_x.exe'
  alias axn 'transparent_mode_xn.exe'
  alias plot 'plotcom.exe'
  alias xyplot 'xyplot_ascii.exe'

"a" will change from the Tektronix window to the text window in a graphics
terminal.
"ax" will change from the Tektronix window to the text window in xterm, and
erase the screen.
"axn" will change from the Tektronix window to the text window in xterm, 
without erasing the screen.
"plot" will operate the plot command on the standard plot files (see below)
"xyplot" will produce an XY plot of columnar data from one or more ASCII files.

These definitions can be placed in a login file if desired.

Finally, edit display-plotting_availability.dat to match the display and
plotting devices availabile on your system.

     The plot device xgterm is a color xterm-like graphics terminal emulator
which runs on Unix.  Copies compiled for Linux with Intel processors for 
kernels 2.2 and 2.4, Mac OS X 10.4, Tiger, and Mac OS X 10.7/10.8 can be 
downloaded from the web page for this package.  An early version of xgterm for 
Mac OS X 10.4 from iraf.net did not work correctly.  While a plot could be sent
to it, the Tek window never received focus, so no cursor readback was possible.
The version on the  web page was prepared by Chip Coldwell, and will work correctly.
In the file .Xdefaults in your Unix home directory create the following settings
for xgterm:

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
! xgterm

Xgterm*gterm*color0:      black
Xgterm*gterm*color1:      ivory1
Xgterm*gterm*color2:      red
Xgterm*gterm*color3:      green
Xgterm*gterm*color4:      blue
Xgterm*gterm*color5:      cyan
Xgterm*gterm*color6:      yellow
Xgterm*gterm*color7:      magenta
Xgterm*gterm*color8:      gold1
Xgterm*gterm*color9:      DarkSlateGray3
Xgterm*gterm*height:      601
Xgterm*gterm*width:       801
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

These colors are frequently used in the demonstration programs.


             Running the Demonstration Programs

     First try running the demonstrations programs xyplotdem.exe,
xyplotdem2.exe, xyplohdem.exe, contourplotdem.exe, meshdem.exe, 
hammer_aitoff_dem, and cube.exe.  One is initially prompted for the plot
device.  Depending on the state of the display-plotting_availability.dat, 
one might be presented with:

  Enter the plot devices:
       S   = SAOimage
      -S   = SAOimage, no erasure of screen
       G   = Graphics terminal (VT100/Retrographics and Visual 550)
       G4  = Graphics terminal emulator (Versaterm)
       X   = Xterm (default)
       XG  = Xgterm
       F   = File

Enter one or more letters corresponding to the plot devices you wish the
plot to appear on, e.g. X F.  If you are connected to a Unix system
via telnet or ssh from a Macintosh, then it is possible to use Versaterm.
Note that SAOimage refers to "Enhanced SAOimage", available from 
http://www.chara.gsu.edu/~gudehus/enhanced_saoimage.html.  After the
plot appears, several interactive plot commands are available (except when 
running cube.exe).  Help can be obtained by typing (not entering) H or h.  
All or some of the following will then appear (note that ^ denotes that
the control key is to be pressed as well):

A = Turns on the crosshairs and by pressing the <CR> at chosen X limits,
    the mean Y value will be calculated for each plot.
a = Allows the user to enter annotation at the location of the crosshairs
    with the color most recently selected.
    ^I (^L on Mac OS X) toggles to the Greek alphabet and special symbols
    and back to English
    ^H (^B on Mac Os X) gives a backspace
    ^K toggles to subscript, superscript, and back to normal
^A = Prompts user for the height of the annotation.
B = Defines a box with the crosshairs placed at the lower left and upper right.
    Will replot with this scaling.
b = Allows the user to be prompted for the background color on SAOimage.
C = Turns on the crosshairs and by pressing the <CR>, prints the values at
    that location and puts the values in a common block;  typing - deletes the
    last pair of values from the common block; and typing Q turns off the
    crosshairs.
c = Allows the user to be prompted for the color.
F = Allows the user to alter the scaling factor on the current plot device(s).
f = Allows the user to change the fill style for each plot.
H = Gives help.
h = Gives help.
I = Allows the user to be prompted for several of the plotting parameters
    before a replot is done.  This command is typically used when preparing
    a plot for publication.
    The following operations are available:
    1) Inverting the X axis and/or Y axis
    2) Labeling the X and Y axes in the following ways:  Linear automatic,
       Linear manual, Antilog automatic, Antilog manual (antilog refers to
       the fact that the labeling is the antilog of the plotted values which
       are logs)
       a) In the Linear manual mode one can specify for the X and Y axes, the
       lowest labeled physical value, the physical value/interval, and the
       number of intervals (coded as nn.llrr where nn is the integer part, .ll
       represents the left (or bottom) fractional part, and .rr represents the
       right (or top) fractional part of an interval).
       b) In the Antilog manual mode one can specify for the X and Y axes, the
       lowest displayed tick mark (coded as log.antilog where log is the
       integer part of the plotted value (which is a log), and antilog
       represents the first displayed tick mark of that decade (which
       is an antilog)).  The antilog of the physical value at the first tick
       mark may or may not be printed byu the program.   One can also specify
       the number of displayed decades (coded as n.antilog where n is the
       integer part of the number of decades, and antilog represents the
       rightmost displayed tick mark of an additional decade.  For example, if
       one enters -1.5 for the lowest value and 3.2 for the number of decades,
       then the first tick mark will be at X=0.5 (log = -0.301 = -1 + 0.699)
       and the last tick mark will be at X=200 (log = 2.301).  Note that
       fractional parts of .0 and .1 behave the same way.

       Note:  If the original plot was linear, then the log of the data should
       be taken first (with the L command) for the antilog labeling to make
       sense.
    3) Specifying symbol heights
    4) Specifying labels for the X and Y axes
    5) Specifying a title
    6) Specifying one or more print devices
L = Allows the user to take log(X) and log(Y).
l = Allows the user to take ln(X) and ln(Y).
M = Allows the user to modify the X and Y values by adding increments and
    adjusting by scaling factors.
m = Allows the user to modify the X and Y values by adding increments and
    adjusting by scaling factors for a selected plot.
O = Redoes the original plot with any new axes, colors, and symbols.
o = Redoes the original plot without any new axes or symbols.
P = Allows the user to take powers.
p = Allows the user to specify the color of each plot.
Q = Returns.
q = Returns.
R = Turns on the crosshairs and by pressing the <CR> at chosen X limits,
    replotting with automatic scaling will be done.
S = Allows the user to specify the style of vector.
s = Allows the user to specify the symbol for a set of points.
V = Draws a vector of the color and vector style most recently selected.
v = Allows the user to be prompted for the starting and ending physical
    values of a vector.
X = Allows plotting an additional X axis in different linear units.
x = Allows plotting an additional X axis in different antilog units.
Y = Allows plotting an additional Y axis in different linear units.
y = Allows plotting an additional Y axis in different antilog units.

A subset of these commands are used in contourdem.exe, hammer_aitoff_dem.exe,
and meshdem.exe.

     On SAOimage and xgterm, user prompts appear on the text terminal
whereas on all other devices the prompts will appear on the Tek window.
Note that a plot can be sent to more than one device at a time.
Xgterm, a color xterm, behaves mostly like xterm.  One difference
between the two is that xterm allows one to use the left mouse button to
interact with the plot whereas xgterm requires a <CR> press.  SAOimage
also requires a <CR> press for plot interaction.  SAOimage on Mac OS
also requires that it be given focus by clicking in the frame before
any interaction is attempted.  Following that, the cross cursor should
be positioned within the SAOimage desktop area before and commands are
given.  The version of SAOimage available from most sources will not work 
with plotting;  the version that is required is "Enhanced SAOimage, v. 1.24E",
available at the MIIPS website.  The version of Xgterm for the Macintosh
available from iraf.net does not work properly either.  Use the version in
this package.
     Xgterm needs to have its colors defined in the user's .Xdefaults file.
The following entries will ensure that the correct colors are displayed:

Xgterm*gterm*color0:      black
Xgterm*gterm*color1:      ivory1
Xgterm*gterm*color2:      red
Xgterm*gterm*color3:      green
Xgterm*gterm*color4:      blue
Xgterm*gterm*color5:      cyan
Xgterm*gterm*color6:      yellow
Xgterm*gterm*color7:      magenta
Xgterm*gterm*color8:      gold1
Xgterm*gterm*color9:      DarkSlateGray3
Xgterm*gterm*height:      601
Xgterm*gterm*width:       801

     If a plot file is being created it is possible to add annotation
that will be written to the file.  For example, if one selects

  DEVICES=X F

the plot will appear on an xterm and be written to a file.  Pressing
"a" while the plot is displayed on an xterm will then bring up a cursor.
Position the cursor on the plot and then click the left mouse button
(or press the <CR> for xgterm and SAOimage).  You are then prompted to
enter some annotation.  You can enter either English text, Greek letters,
special symbols, or some combination of them.  Typing ^I (^L on Mac OS X) 
at this time, toggles to the Greek alphabet and special symbols, and back
to English.  In the Greek mode, the numbers 0 to 9 produce the symbols 0
to 9.  One could for example use special symbol 1 (a circle) to denote the
position of the primary in a plot of a relative orbit.  Note however,
that the cursor center currently corresponds to the lower left corner
of the initial character.

                        The Plot Command

     After a plot file has been created, the plot can at any time be
directed to any of the available plot devices by using the plotcom.exe
program.  Since the plot file's default name is plot.plt, be sure to
change this to some other name to avoid having it be overwritten by another
plot file.  To plot a plot file, first be sure that you have set up the
alias 'plot' as described above.  Enter:

  plot device=P xoff=X yoff=Y scale=S rotate=R number=N plot_file

where
1) Each optional keyword, and in the case of "device", its value, can be
   shortened to an unambiguous abbreviation
2) If no device is specified, the default is xterm
3) If no plot_file is specified, the default is plot.plt
4) An optional / delimiter can be used between keywords (but not before the
   first one)
5) The keywords have the following meaning:
     device is the plot device, with values, P, equal to
        TEKTRONIX  = Graphics terminal (VT100/Retrographics and Visual 550)
        GRAPHON    = Graphon graphics terminal
        CODONICS   = Codonocs graphics terminal
        MICROTERM  = Microterm graphics terminal
        VERSATERM  = Versaterm graphics terminal emulator for Macintosh
        XTERM      = Xterm graphics terminal emulator for OpenVMS and Unix
        XGTERM     = Xgterm grpahics terminal emulator for Unix
        SAOIMAGE   = Enhanced SAOimage
        _SAOIMAGE  = Enhanced SAOimage with not erasure of the previous image
        POSTSCRIPT = Postscript output file (default name is plot.ps)
        EPS        = Encapsulated postscript output file (default name
                     is plot.eps)
        (each device can be shortened to an unambiguous abbreviation,
        e.g. pos or POS for POSTSCRIPT)
      xoff is the horizontal offset, X, of the plot in inches
      yoff is the vertical offset, Y, of the plot in inches
      scale is the magnification, S, of the plot in terms of a factor.
      rotate is the counterclockwise rotation, R, of the plot in degrees
      number is the number, N, of the complete plot within the plot file.
         Because the plot file is not closed until the binary program quits,
         all plots are written to the same file, and the "number" keyword
         must be used to select the plot.
6)  The keywords and their values can be upper- or lowercase
7)  When both rotation and offsets are given, the operation can be thought of
    as either 1) rotation about the lower left corner of the plot
    followed by translation in the rotated coordinate system, or 2) translation
    followed by rotation about the old location of the corner.  Thus a plot on
    xterm can be viewed rotated 90 counterclockwise with a command such as:
      plot yof=-6 rot=90 sca=0.75 myplot.plt
8)  Postscript files created by the plot command are by default matched to
    a printed sheet viewed in landscape orientation.  Thus when such a file
    is viewed with ghostview or another postscript viewer, they will appear
    to be rotated by 90 degrees counterclockwise.  To create a postscript
    file without the prerotation, use a command such as:
      plot dev=pos xof=-8.0 rot=-90 myplot.plt
9)  Encapsulated postscript files are by default not prerotated and will
    appear in the correct orientation in ghostview.  In addition, encapsulated
    postscript files are by default created with a bounding box size just
    slightly larger than the default XY plot size (X axis = 6 inches, Y axis
    = 5 inches).  If your plot size is larger or smaller than the default size
    just use an editor such as vi to change the dimensions in the *.eps file.
    The BoundingBox line is 5th from the top.  The encapsulated postscript
    files will not ordinarily produce output on a printer because because they
    do not contain the 'showpage' command.  If you wish to see a printed
    version of your eps file, just add 'showpage' after the last 'stroke'
    command on the third line from the end.
10) The keyword, number, selects the number of the plot within a multi-plot
    file.  If the number keyword is not given, by default the first plot is
    displayed on devices such as graphic terminals, xterm, xgterm, and
    SAOimage.  If a postscript file is created and no number keyword is given,
    all plots are written to the file.  For an eps file, only the first file
    is written.  If the value given for the number keywords is -1, then all
    plots are displayed overlapped on all devices, postscript files, and eps
    files.

               Plotting from an ASCII File

     One or more ASCII files of data can be plotted with the program 
xyplot_ascii.exe, a general purpose interface for the xyplot.for.  Three
cases can be handled.  In the first case, the data for the abscissa and
ordinate are contained in one file having an arbitrary number of header lines,
an arbitrary number of columns, and an arbitrary number of rows of data.  All
columns must have the same number of rows however.  Multiple plots are possible
by selecting more than one column for the abscissa and ordinate.  The number
of columns chosen for the abscissa and ordinate must match.  In the second
case, the data for the abscissa are contained in a first file and the data for
the ordinate are contained in a second file.  The number of rows in both files,
other than header rows, must match.  Multiple plots are again possible.  In
the third case, the abscissa and ordinate data for the first plot are contained
in the first of several files, and the abscissa and ordinate data for
additional plots are contained in additional files up to a maximum of fifteen
plots.  This is the most general case because the numbers of rows do not have
to match between files.  In all three cases the data can be in the form of 
decimal or integer values.
     A setup file needs to be opened which sets up the line dashing, pen
width, line style, symbols, and colors.  By editing this setup file, many
different graphs can be produced.  In the setup file, the name of the
control parameter is followed on successive lines by the values desired
for each plot.  The control parameters may be in any order.  The number of
values can be less than, equal to, or greater than the number of plots
desired.  The program will simply use the values up to the last one
available, and then roll the values over.
    The file xyplot_setup1.dat, shown below, is an example of this format:

LINE VECTOR STYLE
0
0
0
0
0
0
0
1
2
3
4
5
PEN WIDTH
20
LINE TYPE
-1
0
997
997
-1
997
997
SYMBOL
0
1
100
100
327681
100
100
5
6
7
8
9
10
INVERT X
NO
INVERT Y
NO
COLOR
16776960        Yellow
16711935        Magenta
65280           Green
65280           Green
16711680        Red
8388564         Aquamarine
8388564         Aquamarine
255             Blue
16766720        Gold1
65535           Cyan
7982541         DarkSlateGray3
16777200        Ivory1
10824234        Brown
16716947        Deep pink
5597999         Dark olive greem
15631086        Violet
16766720        Gold
16770229        Moccasin
X LABEL
X Axis
Y LABEL
Y Axis
TITLE
Anonymous

1) Each keyword is followed, on successive lines, by the values for a single
plot within the complete plot.  If there are more plots than values, rollover
will occur.  If there are fewer plots than values, the extra ones will not be
used.
2) The keywords may be in any order
3) Comments are allowed to the right of a value, however it is very important
that there be no tabs in the line.
4) The LINE TYPE (as explained in line.for) controls the plot lines and the
   type of plot, where:
   a) The magnitude of the value controls the frequency of plotted symbols,
      e.g. zero gives no symbols, and 4 gives a symbol every 4th data point
   b) Positive values give a straight line connecting every data point
   c) Negative values give no connecting straight lines
   d) If the value is 997 error bars are drawn (two plots are required)
   e) If the value is 998 a histogram is drawn with the bars stacked
      vertically if multiple plots are made
   f) If the valud is 999 a histogram is drawn with the bars placed next
      to each other is multiple plots are made
5) The SYMBOL controls the type of symbol where
   a) values from 0 to 13 in the first byte give the built-in symbols
   b) a character may be plotted if the ASCII code is placed in the second byte
   c) if a histogram is to be drawn, the value in the first byte give the
      filling style
   d) if error bars are to be drawn, the value in the first byte give the
      style of the bar, i.e., 0 give a short tick, 1 gives nothing, 2 gives
      an arrowhead.  If 100 is added to the first byte, the X or Y locations
      contain the central location and the deviation to the low and high
      directions, respectively, for the adjacent array locations.  Because
      errorbars require two plots, the values should be repeated.
   e) the value in the third byte give the symbol height in hundredths of
      an inch.  If the value is not present a default of 0.14 inch is used.

     In the above example setup file, the values under LINE TYPE and SYMBOL
indicate that the first plot will consist of points drawn with symbol number 0
with no connecting lines, and the second plot will have connecting lines
between the points with no symbols drawn.  The third plot will be error bars
drawn with the usual short ticks at the ends.  Because error bars require two
adjacent plot array locations, the values for each keword are repeated.  The
fourth plot will consists of points drawn with symbol number 1, but because
the symbol is to be drawn with a smaller size of 5/100 inches, 5 is added to
the 3rd byte, giving a final value of 1 + 5*256**2 = 327681.  A future version
of xyplot_ascii will attempt to make this operation more user friendly.
The next plot is again error bars, requiring repeated values.

     Five sample ASCII files are included in this package to demonstrate how
xyplot_ascii.exe works.  Launch the program, and you will be presented with
the following menu:

  Enter a choice for the input data:
       1 = Abscissa and ordinate data for one or more plots in one file
           (default)
       2 = Abscissa data in one file and ordinate data in another file for
           one or more plots
       3 = Abscissa and ordinate data for first plot in first file,
           additional data for additional plots in successive files, up
           to a maximum of ten files
  CHOICE=

Enter 1, and the program responds with:

  Open the file containing the abscissa and ordinate data for one or
  more plots.
  Enter the file name:
  FILE=

Enter ascii1.dat, and the program asks:

  How many lines are in the header?  (default = 1)
  LINES_HEADER_1=

Enter 1 or take the default, and the header line will be displayed, along
with the counts of the number of columns of data and the number of lines of
data.  The program then asks:

  Enter the column(s) to be plotted as abscissa values:
  COLUMNS_ABSCISSA=

Here we are going to plot the data in column 2 against time in column 1, plot
the curve in column 6 against time, and plot error bars for the data.  Because
all abscissa values originate from column 1, and because there are 4 plots 
(data, curve, and error bars requiring 2 plots) we enter 1 1 1 1.  The program
then asks:

  Enter the column(s) to be plotted as ordinate values:
  COLUMNS_ORDINATE=

We enter 2 6 2 3 (column 2 for the data, column 6 for the curve, column 2 for
the central location of the error bar, and column 3 for the amplitdue of the 
error bar).  Now the program asks for the name of the setup file:

  Open the setup file:  (default = xyplot_setup.dat)
  SETUP_FILE=

Enter xyplot_setup1.dat (do not take the default) and the program then asks

  Enter the plot devices:
       S   = SAOimage (Enhanced version)
      -S   = SAOimage, no erasure of screen
       G   = Graphics terminal (VT100/Retrographics and Visual 550)
       G4  = Graphics terminal emulator (Versaterm)
       X   = Xterm (default)
       XG  = Xgterm
       F   = File

Enter the appropriate device name, and you will see the plot.

     If you enter 1 1 1 1 1 1 1 for the abscissa columns, and 2 6 2 3 4 4 5
for the ordinate columns, you will see an additional set of data points 
plotted with a different symbol, a different symbol size, a different error
bar length, and different colors (if you are using a color display).

                             *************
     Launch xyplot_ascii.exe again and this time enter 2 for the choice of
input data.  In this case, the abscissa data come from one file and the 
ordinate data from a second file.  The program responds with:

  Open the file containing the abscissa data for one or more plots.
  Enter the file name:
  FILE=

Enter ascii2.dat, and the program asks:

  How many lines are in the header?  (default = 1)
  LINES_HEADER_1=

Enter 1 or take the default, and the header line will be displayed, along
with the counts of the number of columns of data and the number of lines of
data.  The program then asks:

  Enter the column(s) to be plotted as abscissa values:
  COLUMNS_ABSCISSA=

Enter 1 1 1 1.  The program then asks:

  Open the file for the ordinate
  Enter the file name:
  FILE=

Enter ascii1.dat, and the program asks:

  How many lines are in the header?  (default = 1)
  LINES_HEADER_2=

Enter 1 or take the default, and the header line will be displayed, along
with the counts of the number of columns of data and the number of lines of
data.  The program then asks:

  Enter the column(s) to be plotted as ordinate values:
  COLUMNS_ORDINATE=

Enter 2 6 2 3, as before, and the program asks:

  Open the setup file:  (default = xyplot_setup.dat)
  SETUP_FILE=

Enter xyplot_setup1.dat, as before, and the program then asks

  Enter the plot devices:
       S   = SAOimage (Enhanced version)
      -S   = SAOimage, no erasure of screen
       G   = Graphics terminal (VT100/Retrographics and Visual 550)
       G4  = Graphics terminal emulator (Versaterm)
       X   = Xterm (default)
       XG  = Xgterm
       F   = File

Enter the appropriate device name, and you will see a plot which differs from 
the first one in that the abscissa values are larger by a factor of 100.

                             *************
     Launch xyplot_ascii.exe again and this time enter 3 for the choice of
input data.  In this case, the abscissa and ordinate data for the first plot
are contained in the first of several files, and the abscissa and ordinate
data for additional plots are contained in additional files up to a maximum
of fifteen plots.  The program responds with:

  Open the file containing the abscissa and ordinate data for the first plot.
  Enter the file name:
  FILE=

Enter ascii3.dat, and the program asks:

  How many lines are in the header?  (default = 1)
  LINES_HEADER=

Enter 13, and the program will report the number of columns of data and the
number of lines of data, and then ask:

  Enter the column(s) to be plotted as abscissa values:
  COLUMNS_ABSCISSA=

Enter 1 1 1, (the columns for the x data points and their error bars).  Then 
the program asks:

  Enter the column(s) to be plotted as ordinate values:
  COLUMNS_ORDINATE=

Enter 2 2 3, (the columns for the y data points and their error bars), and 
the program responds with:

  Enter the name of the input file for an additional plot;
  enter 0 to continue:
  FILE=

Enter ascii4.dat, and the program asks:

 How many lines are in the header?  (default = 1)
 LINES_HEADER=

Enter 13, and the program will report the number of columns of data and the
number of lines of data, and then ask:

  Enter the column(s) to be plotted as abscissa values:
  COLUMNS_ABSCISSA=

Enter 1, (the column for the x data of a single curve).  Then the program
asks:

  Enter the column(s) to be plotted as ordinate values:
  COLUMNS_ORDINATE=

Enter 2, (the column for the y data of that curve).  The program next asks:

   Enter the name of the input file for an additional plot;
  enter 0 to continue:
  FILE=

Enter ascii5.dat, and the program asks:

 How many lines are in the header?  (default = 1)
 LINES_HEADER=

Enter 13, and the program will report the number of columns of data and the
number of lines of data, and then ask:

  Enter the column(s) to be plotted as abscissa values:
  COLUMNS_ABSCISSA=

Enter 1 1 1, (the columns for the x data points and their error bars for
another set of data).  Then the program
asks:

  Enter the column(s) to be plotted as ordinate values:
  COLUMNS_ORDINATE=

Enter 2 2 3, (the columns for the y data points and their error bars).  The 
program next asks:

  Enter the name of the input file for an additional plot;
  enter 0 to continue:
  FILE=

Enter 0, because we are done entering the ascii files of data.  Now the
will ask:

  Open the setup file:  (default = xyplot_setup.dat)
  SETUP_FILE=

Enter xyplot_setup2.dat (don't take the default).  Then you are asked:

  Enter the plot devices:
        S   = SAOimage (Enhanced version)
       -S   = SAOimage, no erasure of screen
        G   = Graphics terminal (VT100/Retrographics and Visual 550)
        G4  = Graphics terminal emulator (Versaterm)
        X   = Xterm (default)
        XG  = Xgterm
        F   = File

  DEVICES=

Enter your current graphics device and a plot with two sets of data with error
bars, and a curve with a dashed line will be displayed.  You can then use the
built-in interacive commands of xyplot to rescale, arithmetically tranform 
the data, add annotation, and send the plot to the same or a different device,
or a file.


                          Additional Notes

     The MIIPS plot package also allows programmers to create their own
specialized plot applications.  Besides the above demonstrations programs
there are several simple examples, described in t.txt, which demonstrate one 
or more aspects of the package.  Try running the test programs t1.exe, etc 
to get familiar with the subroutines.  Some of these programs will ask for 
the device number.  The numbers can be found in pltdev.for, and have the 
following associations:

       NDEV                    DEVICE
         1                     Graphics Terminal (VT100/Retrographics,
                               Visual 550)
       101                     Graphics Terminal (GraphOn)
       201                     Graphics Terminal (Codonics)
       301                     Graphics Terminal (Micro-term)
       401                     Graphics Terminal emulator (Versaterm)
     10001                     Xterm
     20001                     Xgterm
         2                     File
         4                     1 and 2 (temporarily retained for compatibility)
    999811                     Encapsulated postscript file (no printing)
    999911                     Postscript file (no printing)
        13                     SAOimage
       -13                     SAOimage without erasure


     Any questions should be directed to Donald Gudehus at
gudehus@chara.gsu.edu.

