PGPLOT Version 5.2.0 for the Archimedes
                         June 1997

  Distributed by 'Fortran Friends' P.O. Box 64, Didcot, Oxon OX11 0TH, UK.

  Email:  BCA@ISISE.RL.AC.UK

 PGPLOT is a portable Fortran subroutine package for drawing simple scientific
graphs. It runs on most mainframes on various graphics display devices and
printers including inkjet and PostScript ones. It was originally developed for
use with astronomical data reduction programs in the Caltech Astronomy
department. It is freely available but copyright.

 This is an upgrade from the previous 'Fortran Friends' version 5.1.1

 Archimedes version upgrade to the graphics driver: this now allows making
the ouput directly into a sprite with driver type \ARCF, as opposed to
direct to the screen with driver type \ARCV. It also works with RISC-OS up
to version 3.6 although it can only make 16 or 256 colour sprites directly.

 More information, copies of the Fortran of the most recent version, and
implementations for other computer systems may be obtained from:
*     Dr. T. J. Pearson
*     105-24 California Institute of Technology,
*     Pasadena, California 91125, USA
*
*     tjp@astro.caltech.edu
*     WWW:  http://astro.caltech.edu/~tjp/pgplot/
*     anonymous ftp: astro.caltech.edu

If you do not have access to electronic mail, and want a copy of the 
complete portable Fortran source of version 5.2.0 of PGPlot, and the text of
the current manual (dated 1989) written in TeX input format, send  a blank,
E format, 800K 3.5" floppy disk with a reply paid envelope to 'Fortran
Friends' (address above) The data on that disc are compressed with !Squash,
so you will need RISC-OS 3 to decompress them. Tim Pearson is in the process
of rewriting the manual; pieces are currently available through WWW.

A contribution of 1.00 (or U.S.$2.00) towards administration costs would be
appreciated, or if your address is outside Europe 2.00 (or U.S.$5.00).
Double these prices if you want us to supply the disc and packaging. 

 The PGPlot library supplied on this disc has been compiled with Fortran
Release 2 for the Archimedes. It must be installed on your Archimedes before
you can compile the example programs supplied and run this package.

 Fortran Release 2 for Acorn computers is available for 99 (ex VAT) from:

* Intelligent Interfaces Ltd,     Tel.  (01703) 261514 
* P.O.Box 80,                     Fax.  (01703) 267904
* Eastleigh, 
* Hants SO5 5YX, UK.
             
Distribution disc contents:

1) The application !PGPlot:
   contains the !Boot, !Run and !Sprites needed to set up the environment
   for running PGPlot, together with the font file 'GRFont' and colour
   information in 'RGBTxt'. The HelpPGPlot text file has helpful information
   on the PGPlot functions in a format useable by !SrcEdit for on-line help.

2) The Copyright notice for PGPlot. 

3) 'Examples' directory with the Fortran of the 14 demo programs and an
   explanation in the ReadMe.

4) 'lib' directory with the PGPlot library, and three auxiliary libraries
   which are PD utilities for primitive graphics and communication with the
   operating system and making 'hardcopy' output (sprites). 

5) 'SYS_ARC' directory contains all the Archimedes specific code and
   instructions on how to create a library for new versions of PGPlot
   transferred electronically from the address above.

Installing this version:

1) Copy the !PGPlot application to your working disc.

2) Copy the library files in the 'lib' directory to the directory where you
   keep Fortran libraries. Everyone should copy 'PGPlot'. If you have the
   !Fortran77 front-end from Intelligent Interfaces, or the Shareware 44 PD
   disc from Norwich Computer Services you will already have the other
   files 'Graphics', 'SpriteOp' and 'Utils', so may not need to copy them. 

   In the Shareware !Fortran77 front-end you must include the name of this
   library in the 'LibList' file BEFORE the Graphics and Utils entries.

3) Copy the Examples directory to your working disc. 

4) If you have !SrcEdit and want to use the on-line help, append the lines:

        PGplot
        none
        <PGPLOT_DIR>.HelpPGPlot

   to the file 'choices.languages' within the !SrcEdit application.

   Then install !SrcEdit on the icon bar, click menu over its icon, and 
   change the options, language, to tick PGPlot.

   If you have !DeskEdit you can replace one of the 3 help files in the
   !DeskEdit.data directory with 'HelpPGPlot'.

5) Edit the !Run file if you want to change any of the global variables
   which set the default device type, screen colours etc.

Testing the installation:

1) Before running any PGPLOT program, click on !PGPlot to set up the 
   environment variables so that PGPLOT can find the fonts and colours.

2) Select the screen mode for your plots by setting the MODE from the
   RISC OS Desktop. This implementation of PGPlot is RISC OS compatible.
   It finds the Desktop screen mode before exiting the Desktop, runs your
   PGPlot program and returns to the Desktop on exit from your program.

3) Now try to compile, link and run the test demo programs. 
   Remember the 'PGPlot' library should be linked before the 'Graphics',
  'SptiteOp' and 'Utils' because it references routines in them.

   Warning: Most of the demos run quickly, but PGDemo3 takes some time, 
   over 20 minutes on an A4000 with an ARM250 chip, and longer on an A3000.


Invitation:

 If you feel inspired to improve this Archimedes version, look in the
'AAReadme' in the SYS_ARC directory for advice, and please send any
enhancements to 'Fortran Friends' for distribution to others to enjoy. 

************************ ReadMe for building the system *******************

          PGPLOT on an Acorn Archimedes using Fortran release 2.

       D.J. & K.M. Crennell ('Fortran Friends')         April 1996
                P.O. Box 64, Didcot, Oxon OX11 0TH, UK.

 --------------------------------------------------------------------------
OBTAINING THE SOURCE

 The source code of PGPLOT is best obtained through anonymous ftp from
astro.caltech.edu. If you do not have access to a relevant network, the
source of version 5.2.0 may be obtained by sending 2.00 to cover costs
(3.00 from outside the UK) to K.M. Crennell at the above address.

 --------------------------------------------------------------------------
TESTED DRIVERS

Currently only the following drivers have been tested under RISC-OS3:

/NULL to plot onto the null device.

/ARCV to use the Fortran Friends graphics library routines to plot to the
      screen. The driver uses the screen mode in use at the time the program
      is invoked; this must be have at least 16 colours.
      The first 16 colours are set to the defaults described in the PGPlot
      manual, the rest (up to 255) are pre-set to black.

/ARCF as /ARCV but makes an Archimedes sprite with the name 'sprite/01' in
      the current directory. Subsequent screens are 'sprite/02' etc. The
      sprite is made in mode 27 for 16 colour representation and mode 28
      (256 colours) for > 16 colour modes. The dimension of the sprite is
      that of the screen by default but may be changed with the variables:
      ARC_WIDTH and ARC_HEIGHT (pixels) as shown in the !Run file.


/PS   to produce a file that can be printed on a Postscript printer.

/VPS  to produce a 'vertical' or portrait mode Postscript file.

/CPS  to produce a colour Postscript file.

/VCPS to produce a 'vertical' or portrait mode colour Postscript file.

Please feel free to adapt drivers for other plotting devices and make them
available to other users. A desktop compliant driver would be very welcome.

 --------------------------------------------------------------------------
INSTALLING PGPLOT

It is assumed that you have transferred the following directories from
California:

0) PGPLOT with text files AAAREADME, COPYRIGHT and the
   associated subdirectories:

1) SRC with the portable PGPlot source. This directory contains ~200 files,
   so concatenate the Fortran into 1 file, keeping the two include files
   separate.

2) SYS_ARC which contains all the Archimedes specific code, HicBoot and
   HicRun and the source of the device drivers

3) FONTS

4) EXAMPLES 

It is also assumed that you have the PD Fortran libraries 'Graphics',
   'SpriteOp' and 'Utils' which are obtainable on the Shareware 44 Disk for 2
   from: Norwich Computer Services, 96a Vauxhall Street, Norwich NR2 2SD, UK.

These libraries are also supplied with the !Fortran77 utility at 25 from
   Intelligent Interfaces Ltd, P.O.Box 80, Eastleigh, Hants SO5 5YX, UK.

Installation  procedure

Set up this directory structure on the Archimedes:

  !PGPlot -
          Examples -
                     f77 (for the demo source code)
          f77 (for the PGPlot system code)
          SYS_ARC -
                     f77 (for the Archimedes specific code)

Copy:
1) the Examples ReadMe and Fortran source into the Examples and Examples.f77
   directories. 
2) the portable source file (call it PGPlot) and 2 include files (PGPLOT/IN
   and GRPCKG1/IN) from SRC into the f77 directory.
3) the contents of the SYS_ARC with its Fortran files into SYS_ARC
   and SYS_ARC.f77
4) the files GRFONT/TXT and RGB/TXT into !PGPlot
   rename the file RGB/TXT as RGBTxt.

Then:
1) Edit the Fortran file in the !PGPlot.f77:
   a) change the all instances of the INCLUDE file names 'pgplot.inc' to
      'f77.PGPLOT/IN' and 'grpckg1.inc' to 'f77.GRPCKG1/IN'
   b) Find the subroutine GRSYXD in the Fortran source, it has an INTEGER*2
      declaration which is not supported by Archimedes Fortran. There is a
      non-standard version in your SYS_ARC.f77 which simulates the INTEGER*2
      code. It was derived from the standard version dated:
      "15-Dec-1988 - standardize". Provided this is the version you have
      just imported then it is OK to remove it from the big source; part c)
      below will insert the new code. Otherwise you will have to improvise
      changes to the GRSYXD in SYS_ARC.f77 to reflect those in the newer
      version.
   c) similarly remove the function GRTRIM which falls into a Fortran system
      library bug. There is a replacement with a work-around in SYS_ARC.f77
      which will be compiled automatically.
   d) add a card:
             INCLUDE 'SYS_ARC.f77.ArcInclude'
      at the end to include the Archimedes specific code.
2) Ensure that the two 'include' files are called PGPLOT/IN and GRPCKG1/IN.
3) make the Current Selected Directory your !PGPlot (*DIR ...!PGPlot). This
   is not necessary if you are using the !Fortran77 front-end from
   Intelligent Interfaces, or the one from Shareware 44 because they do this
   for you.
4) compile the code, creating the object file which can then be used as the
   PGPlot library. For convenience, move it into your Fortran libraries
   directory.

Now make !PGPlot into an application:

1) copy to it the HicBoot as !Boot and HicRun as !Run from SYS_ARC and
   delete the originals.
2) make them into 'Obey' files (e.g. *SETTYPE !Boot FEB)
3) you will also need a !Sprites, so copy one from another application and
   correct it using the !Paint utility. The sprites should be renamed
   '!pgplot' and 'sm!pgplot' so that they will be displayed correctly in the
   filer window.
4) look at the !Run. It contains several statements setting up the PGPLOT_
   variables required by PGPlot. You may want to alter these or set up some
   of your own.

Click on the !PGPlot icon to initialise the global variables and sprites.

 --------------------------------------------------------------------------
SET UP THE FONTS

1) Compile, link and run the program SYS_ARC.f77.PGPack; this will create an 
   UNFORMATTED file 'GRFont' in your !PGPlot application.
2) You may now delete the GRFONT/TXT.

 --------------------------------------------------------------------------
TRY THE EXAMPLES

Now compile a demo, and link it with a command like:

*Link -o demo1 aof.PGDemo1 lib.PGPlot lib.Utils lib.Graphics lib.f77

then:

*Run demo1

This will first ask you for the device and should say that the default is
/ARCV. Just press return to see the demo on the screen.

 --------------------------------------------------------------------------
SETTING UP THE HELP FILE

1) Compile, link and run the file:
         SYS_ARC.f77.ConvertHlp
   This will extract the help information from the PGPlot source (expected to
   be in f77.pgplot in your !PGPlot application) and create a new file
   'HelpPGPlot' within your !PGPlot application.

2) If you have !SrcEdit and want to use the on-line help, 
   append the lines:

        PGplot
        none
        <PGPLOT_DIR>.HelpPGPlot

   to the file 'choices.languages' within the !SrcEdit application.

3) if you have !DeskEdit you will have to replace one of the 3 help files in
   !DeskEdit.data (say Help_T) with the HelpPGPlot file you have just made.

 --------------------------------------------------------------------------
OTHER USEFUL PGPLOT ROUTINES

Other directories you may find useful on the distribution from California
are the APPLICATIONS, which contains some auxiliary programs but not all in
portable code, and DRIVERS which has all the known device drivers. These are
not usually portable, but you may find some of them a good start if you
want to write a new driver of your own.

We welcome any generally useful new utilities and device drivers for PGPlot.
Please send them to 'Fortran Friends' at the above address so that we may
include them in future issues.