Installing PGPLOT for IFEFFIT
-----------------------------

This file provides hints and tips for installing and using the PGPLOT
graphics library with Ifeffit.  PGPLOT must be installed __BEFORE__ Ifeffit
is installed, or Ifeffit will not have graphics capabilities.  To date, the
installation of PGPLOT has proven to be 'the hard part' of the Ifeffit
installation.  Because of this, all the wisdom I can muster has been put
into the installation script PGPLOT_install.  This file tries to give as
many hints as possible.

Installation (Semi-Automated with PGPLOT_install):
-------------------------------------------------

The shell script 'PGPLOT_install' will attempt to download, build and 
install PGPLOT for you.  Running PGPLOT_install can be as simple as 
  ./PGPLOT_install --system=linux

which will download the PGPLOT kit, configure, build, and install
PGPLOT for you.  The script has the following requirements:

  1. If the file pgplot5.2.tar.gz isn't already here, it will try 
     to download it for you.  This may fail, in which case you'll
     have to download it yourself from
         http://www.astro.caltech.edu/~tjp/pgplot/
     Only after the file pgplot5.2.tar.gz is in the same directory
     as PGPLOT_install can the installation proceed.

  2. By default, PGPLOT_install will install the pgplot files in 
       /usr/local/pgplot
     and install the pgplot library (libpgplot.a) in
       /usr/local/lib
     To do this successfully, you probably need to run PGPLOT_install
     with root access.  If you don't have root access, or want to use
     some other location for the PGPLOT libraries, specify the
     directory prefix with the --prefix switch:
       ./PGPLOT_install --prefix=/home/matt/libs

     which will install to /home/matt/libs/pgplot.  You will want to
     set the PGPLOT_DIR variable accordingly.

  3. PGPLOT_install assumes it's building on a linux system with
     g77 and gcc.  It will probably work on an IRIX or other Unix 
     system, by using commands like:
       ./PGPLOT_install --system=irix   --prefix=/home/matt/libs/
       ./PGPLOT_install --system=sun4  
     the argument is passed on to PGPLOT to help compilation),
     but this is not tested.

If the script fails, consult the PGPLOT instructions, or contact me when
you've run out of ideas.  The goal of the PGPLOT build is to create a
library file 'libpgplot.a' against which Ifeffit will be linked.  If
this gets built and the demos run, PGPLOT should work with Ifeffit.

Configuring Ifeffit:
--------------------

Unless told otherwise (ie, with an explicit --with-pgpplot,
--without-pgplot, or --with-pgplot-link), the configuration script will
try to determine how to build Ifeffit using the iconf_pgplot script.  You 
can run this yourself:
  ~>./iconf_pgplot

which should write out a set of link options for how to successfully link
with the PGPLOT library.  Something like
    -L/usr/local/pgplot -lpgplot -lpng -lz -L/usr/X11R6/lib -lX11

should get written out.  If you get something like
    ...ifeffit_1.0b/src/pgstub/libnopgplot.a

then Ifeffit will be built without plotting capabilities.


PGPLOT Environmental Variables:
-------------------------------

After installation, you should set some environmental variables 
associated with PGPLOT.  You'll definitely want to set PGPLOT_DIR 
to /usr/local/pgplot (or wherever you installed PGPLOT):
 csh:     setenv PGPLOT_DIR /usr/local/pgplot
 bash:    export PGPLOT_DIR=/usr/local/pgplot


You'll also want to set up a default PGPLOT device. Assuming you are
using X windows, you'll want to set PGPLOT_DEV to either /xwindow
or /xserve.  These two devices are essentially identical, except
that the /xserve plot area will remain after IFEFFIT is ended, and
the same plot area will be used if IFEFFIT is restarted.
 csh:     setenv PGPLOT_DEV /xserve
 bash:    export PGPLOT_DEV=/xserve


For Postscript and / or GIF output from IFEFFIT, you may want to
set the height and widths of the resulting output plots.  For the
Postscript devices, the size is specified in units of 0.001" (25
microns).  An appropriate size might be:
 csh:    setenv PGPLOT_PS_HEIGHT 9000
         setenv PGPLOT_PS_WIDTH  6000

For GIFs, the units are pixels, so appropriate sizes might be:
 bash:   export PGPLOT_GIF_HEIGHT=400
         export PGPLOT_GIF_WIDTH=500

Finally, for the X windows devices, you may want to put a few
setting into your .Xdefaults or .Xresources file. Typical setting
might be these:

 pgxwin.server.visible:	false
 pgxwin.Win.geometry:	610x377

The first of these will hide the annoying little extra PGPLOT
window.  The second configures the starting size of the PGPLOT
plot window.  You can always resize it, but why not have it be
close to the right size to begin with?

If you have an older video card and get 'color flashing' from the
PGPLOT window, PGPLOT (or something else) is probably taking too
much of the X windows 'color map'.  Setting the maximum number of
colors that PGPLOT can use might help. Start with

 pgxwin.Win.maxColors:	512

and work your way down until it works OK.  Setting this number
_too_ small will not give you enough colors.

After changing your .Xdefaults file you'll have to restart your X
session or issue a 'xrdb --merge .Xdefaults' command.


Adding More PGPLOT Devices
--------------------------

If you're interested in using other PGPLOT devices (say PNG, or a
printer-specific driver), I recommend starting with the drivers
listed in drivers.list and add each new driver one at a time.  You
may have to tweak the Makefiles and test extensively.  At this
point, you're sort of on your own -- the PGPLOT documentation is
pretty good.