
        G N U P L O T +
        Version 0.3.2
        14/04/2006

        Copyright (C) 2006
        Dominic Ford


        This is GnuPlot+ version 0.3.2, 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

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).
* Setting plot aspect ratios with 'set size ratio' / 'set size square'

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".

* set key --- as well as the top, bottom, left, right, below and outside options
              which Gnuplot permits, GnuPlot+ also allows xcentre and ycentre,
              which are self-explanatory. In addition, a positional offset may
              be specified -- the first value is assumed to be an xoffset, and
              the second a yoffset, in units approximately equal to the size of
              the plot. For example:

              set key bottom left 0.0 -0.5

              would display a key below the bottom left corner of the graph.

* plot colours --- in the with clause of the plot command, the command "colour"
                   (abbrev. 'c'), followed by an integer, sets the colour of the
                   dataset to be plotted. For example:

                   plot sin(x) with c 5

                   The colour command can also be used when defining linestyles.

* X11 terminal --- by default, the X11 terminal will remove the window containing
                   any previous plots each time the plot command is called; only
                   one plot will display at a time. To keep old plots visible when
                   plotting further graphs, use the X11_multiwindow terminal:

                   set terminal X11_singlewindow
                   plot sin(x)
                   plot cos(x)     <-- first plot window disappears

                   c.f.

                   set terminal X11_multiwindow
                   plot sin(x)
                   plot cos(x)     <-- first plot window remains
