      PLOT: A GRAPHPLOTTING UTILITY for the ATARI-ST (version 5.0)

          The current graphplotting utility,  PLOT.PRG,  is an improvement 
 in many ways over previous versions.  It is now much more  "user-friendly" 
 and all options are KEY-SELECTABLE.  Keying a NON-OPTION keycode instantly
 reminds  the  user  of the full set of CORRECT option codes - in fact the
 screen display would then look like:
 ____________________________________________________________________________
           You Keyed a NON-OPTION CODE!   CODES are:

  a: Add Curve                           n: New Axes
  m: Click (mouse)Position               g: Click(s) for Gradient
  p: Toggle PointsDraw                   P: Toggle Show All Points
  l: Toggle LineDraw                     L: Toggle Show All Lines
  x: Toggle ScaleMark Axes               X: Toggle Size of Axes Scales
  r: Toggle Grid                         S: Toggle Show Labels
  t: Write Title to Plot                 w: Write X,Y Axes Labels
  d: Delete Current Curve                s: Swap Current with Previous Curve
  f: Polynomial Fit                      c: CubicSpline Data
  I: Save in PI3 or PIC Format           C: Print HardCopy (24-Pin A4-size)
  R: Rescale Axes to Current Data        A: Alter Current Curve Line Style
  y: Select PointMarker Symbol           M: Select PointMarker Size
  ALT HELP: Screen Dump                  T: Transform/Sort Data
  D: Delete File                         z: Click-Alter Data
  1-9: Select Axes Thickness             V: Show Version/Current Limits
  h: Hide Mouse                          E: Execute External Program
  B: Draw Bar Graph                      G: Click-input Data from Scanned Graph
  b: Begin Again                         e: EXIT

    TO CONTINUE HIT ANY KEY AND THEN OPTION-CODE
______________________________________________________________________________

       Also, DATAFILE names do not any longer have to be typed in - they are
 selected by the standard GEM file selector. Finally PLOT can now be called
 with COMMAND LINE arguments from a shell - for those PLOT-options for which
 this makes sense!. Further PLOT is compatible with ALL TOS-versions (I have
 had NO troubles with TOS versions 1.0, 1.2 or 1.6(STE)).

       PLOT  was developed over past couple of years in Prospero Fortran-77
 with extensive use of its inbuilt  facilities for calling GEM functions from
 the inbuilt GEM ROM on the ATARI ST/STE. Assembler bindings were also made
 to invoke the GEMDOS, BIOS and XBIOS. I believe PLOT now to be quite well-
 proven, eminently "useable", and fairly sophisticated in some features, with
 some UNIQUE features (to my knowledge anyway). PLOT has the capability to:

i/     plot up to NCU curves, each with up to NPTS points each simultaneously
       on screen. For the current version, NCU=5 and NPTS=256 (see below)
ii/    automatically chooses and scales the axes (with manual override).
iii/   toggle on-off whether points are marked.
iv/    toggle  on-off whether points are joined  by  continuous  straight 
       lines.
v/     toggle on-off scale-marking the axes.
vi/    toggle on-off measuring grid over graph area.
vii/   least-squares fit and display a polynomial to (equally weighted) data.
viii/  enable the use of the mouse to determine the position  co-ordinates 
       of any displayed point.
ix/    enable the mouse to evaluate the gradient of any line  joining  two 
       "clicked-on" points.
x/     allows choice of different line styles for each displayed curve.
xi/    allows the display of bargraphs - for this the mid-points between data
       define the edges of the bars.
xii/   Allows a TITLE to be written on top, and each axis to be LABELLED.
xiii/  enable a hardcopy of screen display to be made on both 9-pin and 24-
       pin dot matrix printers with ALT-HELP. For 24-Pin printers I use the
       public domain accessory, HCCL.ACC (Hard Copy & CLock) [- included] to
       configure the output for such printers. The Atari SDUMP.PRG would do
       a similar job for Laser Printers such as the SLM-804 or SLM-605 (and
       probably others). SDUMP.PRG is supplied with such ATARI Lasers.
xiv/   Fit and display a "cubic spline" to current curve data.
xv/    allows various DATA TRANSFORMS e.g. log10,10**(),shift,invert,mult,
       and can reorder data in increasing x-ordinates.
xvi/   The BOX and AXES thickness can be selected.
xvii/  Data Points can be ADDED or DELETED as desired by clicking with mouse.
xviii/ PLOT Displays can be saved in .PI3 format or .PIC format. (.PIC is
       convenient for importing into SIGNUM-2, for example).
xix/   Data can be obtained from "scanned" DEGAS(.PI3) or .PIC images of graphs
       from scientific articles. The mousecursor is used to click on the axes
       scalemarks to determine scales and on the displayed curve to get data.
       The algorithm used is rotationally invariant - so, in scanning images
       of graphs, no inaccuracy will result should the scan direction be skew
       to the axes. If you do not have a scanner you can still test this
       feature using option [I] first to give you a .PI3 or .PIC screen image
       of some test data (which you can make yourself [option 'z']). Note
       also that option [T](and ommitting any of the offered transformations)
       then allows you to save inputted data to a file for more ambitious
       purposes than PLOT itself can manage - e.g. nonlinear fitting.
xx/    Plot can be invoked with command line arguments from GULAM or other
       shells by the following syntax {note the "gem" before the program name
       is the "GULAM" method of executing progs. in GEM ENVIRONMENT}:

           gem  plot    <datafilename>   [(most!) PLOT OPTION CODES]

 where <datafilename> is the ONLY MANDATORY ARGUMENT for COMMAND LINE use -
 Note if no argument is given a GEM fileselector is presented. Thus
           gem  plot  dat
 would plot a curve in the default mode i.e. the data obtained from cols 1 & 2
 of the columnar datafile "dat", with polylines joining adjacent points
 displayed; whereas
           gem  plot  dat 3 4 a dat l p
 would plot 2 graphs, the first from the cols 3 & 4 of the file "dat" with
 only interpoint polylines displayed, and the second from the default cols
 1 & 2 of "dat" with only points displayed.

       PLUS OTHER FEATURES (see TUTORIAL HANDBOOK)
 ____________________________________________________________________________
 Dr.W.A.B.Evans, (EMAIL:  wabe@ukc.ac.uk)                    January 26 1991
 Physics Lab,
 University of Kent,
 Canterbury, Kent, CT2 7NR, UK.
 (Tel. 0227-764000 ext.3293      FAX: +44(0)227 762616)

       In this release two practice files, SW.PL and BAR.DAT are included.
 SW.PL contains 6 columns of theoretical large amplitude Solitary Water Wave
 profiles - but I guess this is only of interest to Fluid Dynamicists. Cols
 1,2 define the first curve, cols 3,4 and 5,6 define the other two curves.
 To plot the lot from a shell type

   plot  sw.pl a sw.pl 3 4 a sw.pl 5 6 r

 {nb. prefix the above with "gem" if you use the (marvellously compact and
 powerful GULAM shell - $aliases are wonderful and much more economic than
 shell scripts) - thanks due to Mateti & Bammi}. And to display a bar graph
 from a shell with a title and axes labelling you could type

     plot bar.dat l w '"MARK DISTRIBUTION"' % t '"PART I EXAM ANALYSIS"' B

 Note here the periods (') tell the shell to regard what is within them as a 
 single argument and the apostrophes (") convey the same information to PLOT.

     Student experience has proved that PLOT's other features quickly become
 transparent with a little experimentation.

******************************************************************************

 **IMPORTANT**  This version of PLOT is issued shareware and must not be
 distributed without this accompanying documentation. The author cannot 
 accept any responsibilty whatsoever for ANY misdemeanours that MIGHT occur
 through the use of PLOT.

      The current version is compiled to handle up to 5 curves each with a
 maximum of 256 points each. This will be adequate for most needs. If you end
 up using PLOT regularly - as most UKC Physics students do! - but desire a
 version that can handle more curves or a greater number of data points, I
 would be happy to compile and mail anyone a "tailored" version of the latest
 PLOT for a contribution of 15 English Pounds (or $25) to cover the cost of
 my time + postage etc. I will also include a Printed copy of a PLOT TUTORIAL
 HANDBOOK (as issued to students here at UKC) which details all the features
 of PLOT and gives some "hints & tips" on some of its less obvious features.

      Don't bother to tell me - I know that if PLOT had been compiled in C
 the program could MALLOCate dataspace as it needs it - so there would not
 be any compiler limits on No. of Datapoints, No. of Curves etc. On the other
 hand FORTRAN seems to produce FASTER code than the "C" compilers I have for
 the ST - and its doubles are real*8 rather than real*4 ( anyone know of an
 ST C-compiler with real*8 doubles?) - which often avoids "ill-conditioning"
 problems in curve-fitting etc. - and possesses a more comprehensive library
 of intrinsic functions (for real (double) or "float" variables). However I
 intend to develop a C-version of PLOT.

      The sourcecode for PLOT is very non-standard ANSI - involving as it must
 so many calls to the SYSTEM. Also my assembler bindings for GEMDOS, BIOS etc.
 would make it difficult for anyone else to compile it. However, I would
 consider sending an enhanced PROSPERO FORTRAN diskette with the required
 bindings & sourcecode to PROSPERO FORTRAN License Holders ONLY ( so quote
 your License Number and I'll see if I can get the "OK" from PROSPERO). Again
 I would need reimbursement (see above) to cover my time/disk/postage etc.

                                                       wabe@ukc.ac.uk 26/01/91
******************************************************************************

 	The program PLOT.PRG has been PACKed with the excellent PFXPAK packer
 utility that recently hit the public domain(otherwise it would occupy 82kb
 of disk space). So, if you have PFXPAK, do not try to pack PLOT.PRG further!
 Is PFXPAK not the most useful 4 kbytes that ever came down the Public Domain
 line?? - not forgetting, of course, that it was probably motivated by the 
 success of the original PACK program of ESCAPE 88. PFXPAK is (of course)
 PFXPAKed itself!. "PACK-ICE" will shrink executables a little more but so
 agonisingly S-L-O-W-L-Y. Further PACK-ICE's packed files behave "peculiarly"
 - for example, "some" of them resist all efforts to delete them from Mark
 Williams "RDY" ramdisks (anyone know why this is?) and their "loading 
 unpacking" time is considerably longer than that of PACK or PFXPAK. Further,
 once "PACK-ICED", the original executable appears not to  be recoverable
 (for HEX-editing for example).

 With PFXPAK:

	UNITERM.PRG(v2.0e) shrinks to ~88k!
	SIGNUM2.PRG shrinks to ~87k!
	PROSPERO FORTRAN's many .PRG,.OVL etc. files shrink to about 55%!
	MARK WILLIAMS C's and Sozobon "C" executables shrink to about 50%!
	MWC's "RDY" executable RAMDISKS can also be PFXPAKed so that they
        occupy less floppy space (and load quicker as the unpacking time is
        less than the extra floppy read time of the "unpacked" ramdisk).
	etc.  etc.

 PS.  I have NO connection whatsoever with the Developers of PFXPAK (or PACK)
      except as a satisfied user!!
