
        G N U P L O T +
        Version 0.2.0
        30/03/2006

        Copyright (C) 2006
        Dominic Ford


        This is GnuPlot+ version 0.2.0, a plotting package based
        upon the GnuPlot API, but with superior plotting quality
        provided courtesy of PyX.

        This is an beta-testing version, and presently only
        supports a minimal subset of the GnuPlot API.

        Don't type 'help' to access the on-line reference manual.

        Send comments, bug reports, feature requests and coffee
        supplies to:
            <dcf21@mrao.cam.ac.uk>

0. INTRODUCTION

GnuPlot+ is a rewrite of GnuPlot, intended to provide publication-quality plots
using the same interface as GnuPlot, or at least one which is very similar. It
has been written as a response to (a) the comparatively unattractive output of
GnuPlot and (b) the absence of any other quick and simple commandline plotting
packages. Simple scripts written for GnuPlot should also work with GnuPlot+;
the command syntax is essentially the same. Presently GnuPlot+ is very much
work in progress, and only supports a very minimal subset of the functionality
and configurability of GnuPlot. A rough outline of the features supported by
GnuPlot+ is given in section 3. A few features which have been added are listed
in section 4.

By default, GnuPlot+ prints all textual labels on plots using LaTeX. This does
introduce some incompatibility with GnuPlot, since some strings which were
valid before are no longer valid. For example, "set xlabel 'x^2'" would have
been valid in GnuPlot, but now it needs to be written as "set xlabel '$x^2$'".
I think the nuisance of this incompatibility is far outweighed by the power
that LaTeX brings.

Error trapping is presently minimal, and it is assumed that users are sensible.
Crashing GnuPlot+ is pretty easy.

1. SYSTEM REQUIREMENTS

The following software packages need to be installed prior to GnuPlot+:

* bash
* python  (Version 2.3 or later)
* scipy   (Python Scientific Library)
* PyX     (Python Graphics Library)
* gv      (Ghostview; used for X11 terminal)
* fortune (needed for 'help'!!)

Debian users can find this software in the packages python2.3, python2.3-scipy
and python-pyx. I *believe* that Debian do not yet have a packaged version of
PyX for python2.4.

2. INSTALLATION

* Unpack the distributed .tar.gz:

  tar xvfz gnuplot+_0.2.0.tar.gz
  cd gnuplot+

* Run the installation script:

  ./install

* Start GnuPlot+

  bin/gnuplot

Notes:

(1) The installation process hard-links to the path where the source code is
placed at that time. GnuPlot+ must not be moved after installation.

3. USING GNUPLOT+

As with normal GnuPlot, GnuPlot+ can be used interactively, or via a command
script, e.g.:

gnuplot        -- Starts GnuPlot+ in interactive mode
gnuplot foo    -- Starts GnuPlot+, taking commands from file 'foo'
gnuplot foo -  -- Starts GnuPlot+, taking commands from file 'foo', and then
                  starts operating interactively

Presently, the API supported by GnuPlot+ is a very limited subset of the
GnuPlot API. Things which are supported by this version include:

* Allocation of user-defined variables.
* Allocation of user-defined functions.
* The print command, simple function evaluation.
* The help, exit and quit commands.
* Set plot titles, axis labels, axis ranges, pointsize, linestyles,
  output filename.
* Fitting of functions to data via the "fit" command.
* Basic 2d plotting and replotting of functions and datafiles, with lines,
  points, linespoints, and errorbars of all flavours.
* Use of dual axes. Note: Operation here differs slightly from original
  GnuPlot; dual axes are displayed whenever they are defined, there is no need
  to set xtics nomirror. See API Extension section below.
* Placing arrows and text labels on plots (though arrow linestyles cannot be
  set).
* Automatic and manual selection of linestyles, linetypes, linewidths,
  pointtypes and pointsizes.
* Putting grids on plots (though linestyle cannot be set).

Things which the GnuPlot+ API does not presently include:

* The unset command.
* Parametric function plotting.
* Three-dimensional plotting.
* Multiplot.
* Setting text size and line styles for arrows/gridlines.
* Setting major/minor tics (but GnuPlot+ always gets this right without being
  told anyway).

4. EXTENSIONS TO GNUPLOT'S ORIGINAL API

Some functions are available in GnuPlot+ which were not originally present in
GnuPlot:

* set width x --- Sets the width of postscript output to x centimetres
* set arrow .... (nohead|head|twoway) --- Make arrows with no arrowheads,
                                          normal arrowheads, or two arrowheads
* Multiple axes: GnuPlot only allowed you to have at most two of each kind of
  axes -- one of one side of the plot, and the other on the other. GnuPlot+
  allows an unlimited number of axes to be used. Declare them using statements
  such as "set x3label 'foo'" and "plot sin(x) axes x3y1".
