
        G N U P L O T +
        Version 0.4.0
        27/04/2006

        Copyright (C) 2006
        Dominic Ford


        This is GnuPlot+ version 0.4.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

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, dots, 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'
* Multiplot

Things which the GnuPlot+ API does not presently include:

* The unset command.
* Parametric function plotting.
* Three-dimensional plotting.
* 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.

* plot linewidths --- For an unknown reason, GnuPlot doesn't allow "set
                      linewidth 2". This syntax is allowed in GnuPlot+.

                      Furthermore, "set pointlinewidth 2" will set the
                      linewidth used when drawing data *points*. A similar effect
                      can be achieved via:

                      plot sin(x) with points pointlinewidth 2

                      In both cases, the abbreviation "plw" is valid.

* plot dots --- when using the dot style, for example:

                plot sin(x) with dots

                the size of the plotted dots can be varied with the pointsize
                modifier, unlike in GnuPlot, where the dots where of a fixed
                size. For example, to display big dots, use:

                plot sin(x) with dots pointsize 10

* multiplot --- in the original GnuPlot, there didn't used to be any way to remove
                plots from a multiplot once they were placed. In gnuplot+, the
                delete and undelete commands answer this problem. When each plot
                is added to a multiplot, it is given a reference number, which is
                output to the terminal. To subsequently remove this plot, type:

                delete <number>

                To restore it, type:

                undelete <number>

                As in the original GnuPlot, the "clear" command wipes all plots
                from a multiplot.

* multiplot axes --- suppose you have two plots in a multiplot, one directly
                     above another. You might not want the top plot to have its
                     own labelled x-axis, rather to share the x-axis of the lower
                     plot. To duplicate it would just be a waste of space. In
                     GnuPlot+, this can be achieved with a "linked axis".

                     Set the x-axis label of the upper plot (i.e. the one which
                     you want not to have an x-axis of its own) to "linkaxis 0".
                     This magic label will cause this plot to borrow its x-axis
                     from plot zero. Both axes will scale together.

* 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
