     [file version.texi not included]

This file documents version VERSION of the GNU plotting utilities package.  Last updated UPDATED.

Copyright © 1989--1998 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation.

This is the documentation for version VERSION of the GNU plotting utilities package.  The package consists of programs and functions for data plotting and vector graphics.

The GNU Plotting Utilities
**************************

The GNU plotting utilities currently consist of six user-level programs: graph, plot, tek2plot, spline, ode, and double.  Distributed along with them is GNU libplot, a function library for device-independent two-dimensional vector graphics.  This section gives an overview of the plotting utilities and libplot.

graph is a program for plotting two-dimensional scientific data. It reads one or more data files containing datasets, and outputs a plot. The plot may be directed to a display device or to a file.  Six different display devices are supported.  The corresponding commands are graph -T X, graph -T ps, graph -T fig, graph -T hpgl, graph -T tek, and graph.

graph -T X pops up a window on an X Window System display, and draws the plot in it.  graph -T ps produces a plot in encapsulated Postscript format that may be included in another document, edited with the idraw drawing editor, or sent directly to a printer.  graph -T fig produces output that may be displayed and edited with the xfig drawing editor.  graph -T hpgl produces a Hewlett--Packard Graphics Language (HP-GL or HP-GL/2) plot that may be sent to a Hewlett--Packard LaserJet printer or plotter, or included in another document.  graph -T tek produces output that may be displayed on a Tektronix 4014 terminal or emulator.  graph without a -T option (referred to as `raw graph') produces output in a device-independent format, a so-called GNU graphics metafile.  This metafile may be translated into other formats.

graph can read datasets in both ASCII and binary format, and datasets in the `table' format produced by the plotting program gnuplot.  It produces a plot with or without axes and labels. You may specify labels and ranges for the axes, and you may set the size and position of the plot on the display device.  The labels may contain subscripts and subscripts, Greek letters, and other special symbols; there is also support for Cyrillic script (i.e., Russian) and Japanese. You may specify the type of plotting symbol used for each dataset, and such parameters as the style and thickness of the line (if any) used to connect points in a dataset.  The plotting of filled regions is supported, as is the drawing of error bars.  graph provides full support for multiplotting.  With a single invocation of graph, you may produce a plot consisting of many sub-plots, either side by side or inset.  Each sub-plot will have its own axes and data.

graph -T X, graph -T tek, and raw graph have a feature which most plotting programs do not have.  They can accept input from a pipe, and plot data points in real time.  For this to occur, the user must specify ranges for both axes, so that graph does not need to wait until the end of the input before determining them.

The plot program is a so-called plot filter.  It can translate GNU graphics metafiles (produced for example by raw graph) into the six supported output formats.  The corresponding commands are plot -T X, plot -T ps, plot -T fig, plot -T hpgl, plot -T tek, and plot.  The plot program is useful if you wish to produce output in several different formats while invoking graph only once.  It is also useful if you wish to translate files in the traditional `plot(5)' format produced by, e.g., the non-GNU versions of graph provided with some operating systems.  GNU metafile format is compatible with the traditional `plot(5)' format.

The tek2plot program can translate from Tektronix format to any of the abovementioned output formats.  The corresponding commands are tek2plot -T X, tek2plot -T ps, tek2plot -T fig, tek2plot -T hpgl, and tek2plot.  tek2plot is useful if you have a legacy application that produces drawings in Tektronix format.

Among the other GNU plotting utilities, spline does spline interpolation of data.  It normally uses either cubic spline interpolation or exponential splines in tension, but like graph it can function as a real-time filter under some circumstances. ode provides the ability to integrate an ordinary differential equation or a system of ordinary differential equations, when provided with an explicit expression for each equation.  It supplements the plotting program gnuplot, which can plot functions but not integrate ordinary differential equations.  The final plotting utility, double, is a filter for converting, scaling and cutting binary or ASCII data streams.  It is still under development and is not yet documented.

Distributed along with the plotting utilities is GNU libplot, the function library for device-independent two-dimensional vector graphics on which graph, plot, and tek2plot are based. libplot can draw graphics on X Window System displays, and can generate graphical output in any of five additional formats.  This includes (1) output in encapsulated Postscript format that may be included in another document, edited with the idraw drawing editor, or sent directly to a printer, (2) output that may be displayed and edited with the xfig drawing editor, (3) output in HP-GL or HP-GL/2 format that may be sent to a Hewlett--Packard LaserJet printer or plotter, (4) output that may be displayed on a Tektronix 4014 terminal or emulator, and (5) output in the device-independent GNU graphics metafile format.

libplot provides the ability to draw such objects as lines, open and closed polylines, arcs (both circular and elliptic), circles and ellipses, points, markers, and text strings.  The filling of objects other than points, markers, and text strings is supported (fill color, as well as pen color, may be set arbitrarily).  A wide variety of line types and marker symbols is supported.  The support for drawing text strings is extensive.  The X Window System, Postscript, and xfig drivers support the 35 standard Postscript fonts, and the HP-GL/2 driver supports the 45 standard PCL 5 fonts.  All drivers, including the Tektronix and metafile drivers, support a set of 16 Hershey vector fonts, including HersheyCyrillic.  Text strings may include subscripts and superscripts, and may include characters chosen from more than one font in a typeface.  They may include many non-alphanumeric characters.  The entire collection of 1641 `Hershey glyphs' digitized c. 1967 by Allen V. Hershey at the U.S. Naval Surface Weapons Center, which includes many curious symbols, is built into libplot.  Japanese text strings in the so-called EUC (Extended Unix Code) format may be also be drawn.  Such strings may include both syllabic characters (Hiragana and Katakana) and ideographic characters (Kanji).  A library of 603 Japanese Kanji digitized by Dr. Hershey is built into libplot.

The drawing editors idraw and xfig are not distributed along with the GNU plotting utilities.  However, they are free software, and you may readily obtain them elsewhere (see Auxiliary Software).

The graph Utility
*****************

Each invocation of graph reads one or more datasets from files named on the command line or from standard input, and prepares a plot. There are many command-line options for adjusting the visual appearance of the plot. The following sections explain how to use the most frequently used options, by giving examples.

Simple examples using graph
===========================

By default, graph reads ASCII data from the files specified on the command line, or from standard input if no files are specified.  The data are pairs of numbers, interpreted as the x and y coordinates of data points:

     0.0  0.0
     1.0  0.2
     2.0  0.0
     3.0  0.4
     4.0  0.2
     5.0  0.6

Data points do not need to be on different lines, nor do the x and y coordinates of a data point need to be on the same line. However, there should be no blank lines in the input if it is to be viewed as forming a single dataset.

To plot such a dataset with graph, you could do

     graph -T ps ascii_data_file > plot.ps

or equivalently

     graph -T ps < ascii_data_file > plot.ps

This will produce an encapsulated Postscript file plot.ps, which you may include in another document, display on a screen, or send directly to a printer.  (The --page-size option, or the PAGESIZE environment variable, specifies the size of the printed page.  The default is "letter", i.e., 8.5in by 11in, but "a4" or other ISO or ANSI page sizes may be specified instead.)

You may also do

     graph -T fig < ascii_data_file > plot.fig

to produce a file plot.fig that you may edit with the the xfig drawing editor, or

     graph -T hpgl < ascii_data_file > plot.hpgl

to produce a file plot.hpgl in the Hewlett--Packard Graphics Language (HP-GL or HP-GL/2) that you may send to a Hewlett--Packard LaserJet printer or plotter.

You may use graph -T X to pop up a window on an X Window System display, and display the plot in it.  For that, you would do

     graph -T X < ascii_data_file

If you use graph -T X, no output file will be produced; only a window.  The window will vanish if you type q or click your mouse in it.

You may also use graph -T tek, to display a plot on a device that can emulate a Tektronix 4014 graphics terminal.  xterm, the X Window System terminal emulator, can do this.  Within an xterm window, you would do

     graph -T tek < ascii_data_file

xterm normally emulates a VT100 terminal, but when this command is issued from within it, it will pop up a second window (a `Tektronix window') and draw the plot in it.  The Japanese terminal emulator kterm should be able to do the same, provided that it is correctly installed.  Another piece of software that can emulate a Tektronix 4014 terminal is the DOS version of kermit.

graph may behave differently depending on the environment in which it is invoked.  We have already mentioned the PAGESIZE environment variable, which affects the operation of graph -T ps, graph -T fig, and graph -T hpgl.  The DISPLAY and TERM environment variables affect the operation of graph -T X and graph -T tek, respectively.  There are also several environment variables that affect the operation of graph -T hpgl. For a complete discussion of the effects of the environment on graph, see graph Environment.  The following remarks apply irrespective of which display device is specified.

By default, successive points in the dataset are joined by solid line segments, which form a polygonal line or polyline that we call simply a `line'.  You may choose the style of line (the `linemode') with the -m option:

     graph -T ps -m 2 < ascii_data_file > plot.ps

Here -m 2 indicates that linemode #2 should be used.  If the dataset is rendered in monochrome, which is the default, the line may be drawn in one of five distinct styles.  Linemodes #1 through #5 signify solid, dotted, dotdashed, shortdashed, and longdashed; thereafter the sequence repeats.  If the -C option is used, the dataset will be rendered in color.  For colored datasets, the line may be drawn in one of 25 distinct styles.  Linemodes #1 through #5 signify red, green, blue, magenta, and cyan; all are solid.  Linemodes #6 through #10 signify the same five colors, but dotted rather than solid.  Linemodes #11 through #16 signify the same five colors, but dotdashed, and so forth.  After linemode #25, the sequence repeats.  Linemode #0, irrespective of whether the rendering is in monochrome or color, means that the line is not drawn.

If you wish to fill the polygon bounded by the line (i.e., shade it, or fill it with a solid color), you may use the -q option. For example,

     echo .1 .1 .1 .9 .9 .9 .9 .1 .1 .1 | graph -T ps -C -m 1 -q 0.3 > plot.ps

will plot a square region with vertices (0.1,0.1), (0.1,0.9), (0.9,0.9), and (0.9,0.1).  The repetition of the first vertex (0.1,0.1) at the end of the sequence of vertices ensures that the square will be closed: all four segments of its boundary will be drawn.  The square will be drawn in red (since the colored version of linemode #1 is requested).  The interior of the square will be filled with red to an intensity of 30%, as the -q 0.3 option indicates.  If the intensity were zero, the region would be filled with white, and if it were 1.0, the region would be filled with solid color.  If the intensity were negative, the region would be unfilled, or transparent (the default).

You may choose the width of the line, whether it is filled or not, by using the -W option.  For example, -W 0.01 means that the line should have a width equal to 0.01 times the width of the display. Also, you may put symbols at each data point along the line by doing, for example,

     graph -T ps -S 3 0.1 < ascii_data_file > plot.ps

where the first argument 3 indicates which symbol to plot.  The optional second argument 0.1 specifies the symbol size as a fraction of the size of the `plotting box': the square within which the plot is drawn. Symbol #1 is a dot, symbol #2 is a plus sign, symbol #3 is an asterisk, symbol #4 is a circle, symbol #5 is a cross, and so forth. (see Marker Symbols.)  Symbols 1 through 31 are the same for all display devices, and the color of a symbol will be the same as the color of the line it is plotted along.

Actually, you would probably not want to plot symbols at each point in the dataset unless you turn off the line joining the points.  For this purpose, the `negative linemode' concept is useful.  A line whose linemode is negative is not visible; however, any symbols plotted along it will have the color associated with the corresponding positive linemode.  So, for example,

     graph -T ps -C -m -3 -S 4 < ascii_data_file > plot.ps

will plot a blue circle at each data point.  The circles will not be joined by line segments.  By adding the optional second argument to the -S option, you may adjust the size of the circles.

graph will automatically generate abscissa (i.e., x) values for you if you use the -a option.  If this option is used, no abscissa values should be given in the data file.  The data points will be taken to be regularly spaced along the abscissa.  The two arguments following -a on the command line will be taken as the sampling interval and the abscissa value of the first data point.  If they are absent, they default to 1.0 and 0.0 respectively.  For example, the command

     echo 0 1 0 | graph -T ps -a > plot.ps

produces exactly the same plot  as

     echo 0 0 1 1 2 0 | graph -T ps > plot.ps

graph will plot data with error bars, if the -I e option is specified.  If it is, the dataset should consist of triples (x,y,error) rather than pairs (x,y).  A vertical error bar of the appropriate length will be plotted at each data point.  You may plot a symbol at each data point, along with the error bar, by using the -S option in the usual way.  The symbol will be the same for each point in the dataset.  You may use the -a option in conjunction with -I e, if you wish.  If you do, the dataset should contain no abscissa (i.e., x) values.

By default the limits on the x and y axes, and the spacing between the labeled ticks on each axis, are computed automatically. You may wish to set them manually.  You may accomplish this with the -x and -y options.

     echo 0 0 1 1 2 0 | graph -T ps -x -1 3 -y -1 2 > plot.ps

will produce a plot in which the x axis extends from -1 to 3, and the y axis from -1 to 2.  By default, graph tries to place about six numbered ticks on each axis.  By including an optional third argument to either -x or -y, you may manually set the spacing of these ticks, also.  For example, using -y -1 2 1 rather than -y -1 2 will produce a y axis with labeled ticks at -1, 0, 1, and 2, rather than at the locations that graph would choose by default. In general, if a third argument is present then labeled ticks will be placed at each of its integer multiples.

To make an axis logarithmic, you may use the -l option.  For example,

     echo 1 1 2 3 3 1 | graph -T ps -l x > plot.ps

will produce a plot in which the x axis is logarithmic, but the y axis is linear.  To make both axes logarithmic, you would use -l x -l y.  By default, the upper and lower limits on a logarithmic axis are powers of ten, and the tick marks at these powers of ten, and no other tick marks, are labeled.  If you need more labeled ticks on a logarithmic axis, you should specify a tick spacing manually. For example, -l x -x 1 9 2 will produce a plot in which the x axis is logarithmic and extends from 1 to 9.  Labeled ticks will be located at each integer multiple of 2, i.e., at 2, 4, 6, and 8.

You may label the x and y axes with the -X and -Y options, respectively.  For example,

     echo 1 1 2 3 3 1 | graph -T ps -l x -X "A Logarithmic Axis" > plot.ps

will label the log axis in the preceding example.  By default the label for the y axis (if any) will be rotated 90 degrees, unless you use the --toggle-rotate-y-label option.  You may specify a `top label', or title for the plot, by using the -L option. Doing, for example,

     echo 1 1 2 3 3 1 | graph -T ps -l x -L "A Simple Example" > plot.ps

will produce a plot with a title on top.

The size of the x axis and y axis labels is specified with the -f option, and the size of the title is specified with the --title-font-size option.  For example,

     echo 1 1 2 3 3 1 | graph -T ps -X "Abscissa" -f 0.1 > plot.ps

will produce a plot in which the font size of the x axis label, and each of the numerical tick labels, is very large (0.1 times the size of the plotting box, i.e., the square within which the plot is drawn).

The font in which the labels specified with the -X, -Y, and -L options are drawn may be specified with the -F option.  For example, -F Times-Roman will make the labels appear in Times-Roman instead of the default font (which is Helvetica, unless -T hpgl or -T tek is specified).  Font names are case-insensitive, so -F times-roman will work equally well.  The available fonts include 35 Postscript fonts (for all variants of graph other than graph -T hpgl and graph -T tek), 45 PCL 5 fonts (for graph -T hpgl), and 16 Hershey fonts. The Hershey fonts include HersheyCyrillic, for Russian, and HersheyEUC, for Japanese.  For a discussion of the available fonts, see Text Fonts.

The format of the labels drawn with the -X, -Y, and -L options may be quite intricate.  Subscripts, superscripts, square roots, and switching fonts within a typeface are all allowed. The above examples do not illustrate this, but for details, see Text String Format.

Each of the preceding examples produced a plot containing the default sort of grid (a square box, with ticks and labels drawn along its lower edge and its left edge).  There are actually several sorts of grid you may request.  The -g 0, -g 1, -g 2, and -g 3 options yield successively fancier grids.  What they yield, respectively, is no grid at all, a pair of axes with ticks and labels, a square box with ticks and labels, and a square box with ticks, labels, and grid lines.  As you can see, -g 2 is the default.  There is also a -g 4 option, which yields a slightly different sort of grid: a pair of axes that cross at the origin.  This last sort of grid is useful if the x or y coordinates of the data points you are plotting are both positive and negative.

Non-square and displaced plots
==============================

To alter the linear dimensions of a plot, and also to position it in a different part of your display, you could do something like

     graph -T ps -h .3 -w .6 -r .1 -u .1 < ascii_data_file > plot.ps

Here the -h and -w options specify the height and width of the plotting box, and the -r and -u options indicate how far up and to the right the lower left corner of the plotting box should be positioned.  All dimensions are expressed as fractions of the size of the graphics display, which by convention is a square.  By default, the height and width of the plotting box equal 0.6, and the `upward shift' and the `rightward shift' equal 0.2.  So the above example will produce a plot that is half as tall as usual.  Compared to its usual position, the plot will be shifted slightly downward and to the left.

The `graphics display', within which the plotting box is located, is an abstraction.  For graph -T X, it is a square window on an X display.  For graph -T tek, it is a square region occupying the central part of a Tektronix display.  (Tektronix displays are 4/3 times as wide as they are high.)  For graph -T ps, by default it is a square region centered on an 8.5in by 11in page (US letter size), occupying the full width of the page with allowance being made for margins.  For graph -T fig, by default it is a square region of the same size, positioned in the upper left corner of an xfig display.  For graph -T hpgl, by default it is a square region of the same size, position and orientation on the page are controlled by environment variables.  The page size used by graph -T ps, graph -T fig, and graph -T hpgl may be altered by setting the environment variable PAGESIZE.  For example, setting it to "a4" would position the graphics display appropriately on an A4-size page (21cm by 29.7cm).

Changing the width of the plotting box may have unforeseen consequences. A number of command-line options specify sizes or dimensions as fractions of the width of the plotting box.  For example, -S 3 .01 specifies that the plotting symbols for the following dataset should be of type #3, and should have a fractional size equal to 0.01.  If the -w option is employed to widen or narrow the plot, such dimensions or sizes will scale in tandem.  That is presumably the right thing to do, but may be slightly disconcerting.

Preparing a plot from more than one dataset
===========================================

It is frequently the case that several datasets need to be displayed on the same plot.  If so, you may wish to distinguish the points in different datasets by joining them by lines of different types, or by using plotting symbols of different types.

A more complicated example would be the following.  You may have a file containing a dataset that is the result of experimental observations, and a file containing closely spaced points that trace out a theoretical curve.  The second file is a dataset in its own right.  You would presumably plot it with line segments joining successive points, so as to trace out the theoretical curve.  But the first dataset, resulting from experiment, would be plotted without such line segments.  In fact, a plotting symbol would be plotted at each of its points.

These examples, and others like them, led us to define a set of seven attributes which define the way in which a dataset should be plotted.  These attributes, which may be set by command-line options, are the following.

 1. color/monochrome

 2. linemode

 3. linewidth

 4. symbol type

 5. symbol size

 6. symbol font name

 7. fill fraction

Color/monochrome (a choice of one or the other) is the simplest.  This choice is toggled with the -C option.  The `linemode' (i.e., line style) specifies how the line segments joining successive points should be drawn; it is specified with the -m option.  Linemode #0 means no linemode at all, for example.  `Linewidth' is self-explanatory; it is specified with the -W option. `Symbol type' and `symbol size', which are specified with the -S option, specify the symbol plotted at each point of the dataset.  `Symbol font name' refers to the font from which plotting symbols #32 and above, which are taken to be characters rather than geometric symbols, are selected.  It is set with the --symbol-font-name option, and is relevant only if -S is used to request such special plotting symbols. Finally, the polygonal line joining the points in a dataset may be filled, to create a filled or shaded polygon.  The `fill fraction' is set with the -q option.  A negative fill fraction means no fill, or transparent; zero means white, and 1.0 means solid, or fully colored.

The preceding seven attributes refer to the way in which datasets are plotted.  Datasets may also differ from one another in the way in which they are read from files.  The dataset(s) in a file may or may not contain error bars, for example.  If a file contains data with error bars, the -I e option should occur on the command line before the file name.  (The -I option specifies the input format for the following files.)

The following illustrates how datasets in three different input files could be plotted simultaneously.

     graph -T ps -m 0 -S 3 file_1 -C -m 3 file_2 -C -W 0.02 file_3 > output.ps

The dataset in file_1 will be plotted in linemode #0, so successive points will not be joined by lines.  But symbol #3 (an asterisk) will be plotted at each point.  The dataset in file_2 will be plotted in color, and linemode #3 will be used.  In color plotting, linemode #3 is interpreted as a solid blue line.  The second -C on the command line turns off color for file_3.  The points in the third dataset will be joined by a black line of width 0.02, as a fraction of the width of the graphics display.

The above command line could be made even more complicated by specifying additional options (e.g., -q or -I) before each file. In fact the command line could also include such standard options as -x or -y, which specify the range of each axis.  Such options, which refer to the plot as a whole rather than to individual datasets, should appear before the first file name.  For example, you could do

     graph -T ps -x 0 1 0.5 -m 0 -S 3 file_1 -C -m 3 file_2 > output.ps

Note that it is possible to include the special file name -, which refers to standard input, on the command line.  So you may produce a plot in part from files, and in part from input that is piped to graph from another program.

Each input file may include more than one dataset.  If so, the command line options preceding a file on the command line will take effect for all datasets in that file.  There are two exceptions to this.  By default, the linemode is incremented (`bumped') from one dataset to the next.  This feature is usually quite convenient.  For example, if you do

     graph -T ps -m 3 file_1 > output.ps

the first dataset in file_1 will appear in linemode #3, the second in linemode #4, etc.  In fact if you do

     graph -T ps file_1 file_2 ... > output.ps

without specifying linemode explicitly, the successive datasets read from the files on the command line will appear in linemode #1, linemode #2, ....  If you do not like this feature, you may turn it off, or in general toggle it, by using the -B option.

You may also control manually the linemode and symbol type used for the datasets within any file.  You would do this by including directives in the file itself, rather than on the command line.  For example, if the line

     #m=-5,S=10

appeared in an ASCII-format input file, it would be interpreted as a directive to switch to linemode #-5 and symbol type #10 for the following dataset.  Future releases of graph may provide the ability to set each of the seven dataset attributes in this way.

Multiplotting: placing multiple plots on a single page
======================================================

It is occasionally useful to display several plots at once on a single page, or on a single graphics display.  We call such a composite plot a multiplot.  One common sort of multiplot is a small plot inset into a larger one.  Another sort is two or more plots side by side.

graph can draw multiplots consisting of an arbitrarily large number of sub-plots.  When multiplotting, graph draws each sub-plot in its own `virtual display'.  When a conventional plot is drawn, the virtual display is the same as the physical display.  But when a multiplot is drawn, the virtual display may be any smaller square region.

The following example illustrates the idea.  For the present purposes, the physical display is a square with lower left corner (0.0,0.0) and upper right corner (1.0,1.0).

     graph -T ps data_file_1 --reposition 0.35 0.35 0.3 data_file_2

Here data_file_1 is plotted in the usual way.  The virtual display is then shrunk to a square of size 0.3, with lower left corner (0.35,0.35).  A plot is then prepared from data_file_2, and drawn.  This plot, as you can see, will be a much smaller plot that is inset into the first plot.

By convention, before each sub-plot of a multiplot other than the first is drawn, a `blankout region' surrounding its plotting box is erased. (That is, it is filled with white.)  This erasure prevents the sub-plots from overlapping and producing a messy result.  By default, the blankout region is a rectangular region 30% larger in each dimension than the plotting box for the sub-plot.  This is appropriate if the sub-plot is a small one that is inset into the first sub-plot.  It may not be appropriate, however, if you are preparing a multiplot in which several sub-plots appear side by side.  You may use the --blankout option to adjust this parameter.  For example, specifying --blankout 1.0 will make the blankout region for a sub-plot coincide with its plotting box.  Specifying --blankout 0.0 will prevent any blanking out from occurring.  The blankout parameter may differ from sub-plot to sub-plot.

It should be emphasized that every sub-plot in a multiplot is a plot in its own right.  All the usual options (-m, -S, -x, -y, etc.) may be applied to each sub-plot separately.  The options for a sub-plot should occur on the graph command line immediately after the --reposition option that applies to it. Each sub-plot may be prepared from more than a single dataset, also. The names of the data files for each subplot should occur on the command line before the following --reposition option, if any.

Reading binary and other data formats
=====================================

By default, graph reads datasets in ASCII format.  But it can also read datasets in any of three binary formats (single precision floating point, double precision floating point, and integer). These three input formats are specified by the -I d, -I f, and -I i options, respectively.

There are two advantages to using binary data: 1) graph runs significantly faster because the computational overhead for converting data from ASCII to binary is eliminated, and 2) the input files may be significantly smaller.  If you have very large datasets, using binary format may reduce storage and runtime costs.

For example, you may create a single precision binary dataset as output from a C language program:

     #include <stdio.h>
     void write_point (float x, float y)
     {
       fwrite(&x, sizeof (float), 1, stdout);
       fwrite(&y, sizeof (float), 1, stdout);
     }

You may plot data written this way by doing:

     graph -T ps -I f < binary_data_file > plot.ps

The inclusion of multiple datasets within a single binary file is supported.  If a binary file contains more than a single dataset, successive datasets should be separated by a single occurrence of the the largest possible number.  For single precision datasets this is the quantity MAXFLOAT, for single precision datasets it is the quantity MAXDOUBLE, and for integer datasets it is the quantity MAXINT.  On most machines MAXFLOAT is approximately 3.4x10^38, MAXDOUBLE is approximately 1.8x10^308, and MAXINT is 2^32-1.

If you are reading datasets from more than one file, it is not required that the files be in the same format.  For example,

     graph -T ps -I f binary_data_file -I a ascii_data_file > plot.ps

will read binary_data_file in f (binary single precision) format, and ascii_data_file in a (normal ASCII) format.

There is currently no support for reading and plotting binary data with error bars.  If you have data with error bars, you should supply the data to graph in ASCII, and use the -I e option.

graph can also read data files in the ASCII `table' format produced by the gnuplot plotting program.  For this, you should use the -I g option.  Such a data file may consist of more than one dataset.

To sum up: there are six supported data formats, a (normal ASCII), e (ASCII with error bars), g (the ASCII `table' format produced by gnuplot), f (binary single precision), d (binary double precision), and i (binary integer). Input files may be in any of these six formats.

graph command-line options
==========================

The command-line options to graph are listed in the following sections.  Each option that takes an argument is followed, in parentheses, by the type and default value of the argument.  There are five sorts of option.

The behavior of graph is also affected by a number of environment variables, so there is a section discussing them as well.

Plot options
------------

The following options affect an entire plot.  They should normally occur at most once, and should appear on the command line before the first filename.  If a multiplot is being drawn, they may (with the exception of the -T option) occur more than once.  If so, the second and later occurrences should be placed on the command line immediately after each --reposition X Y option.

-T TYPE
--display-type TYPE
     (String, default "meta".)  Emit output for a display of type TYPE, which may be one of the strings "X", "ps", "fig", "hpgl", "tek", and "meta".  These refer respectively to the X Window System, idraw-editable Postscript, the format used by the xfig drawing editor, the Hewlett--Packard Graphics Language, Tektronix format, and device-independent GNU metafile format.

-f FONT_SIZE
--font-size FONT_SIZE
     (Float, default 0.0525.)  Set the size of the font used for the axis and tick labels, as a fraction of the size of the `plotting box' (the box that frames the plot), to be FONT_SIZE.

-F FONT_NAME
--font-name FONT_NAME
     (String, default "Helvetica" except for graph -T hpgl and graph -T tek, for which "HersheySerif" is the default.)  Set the font used for the axis and tick labels, and for the plot title (if any), to be FONT_NAME.  The choice of font for the plot title may be overridden with the --title-font-name option (see below). Font names are case-insensitive.  For a list of available fonts, see Text Fonts.  If the specified font is not available, the default font will be used.

-g GRID_STYLE
--grid-style GRID_STYLE
     (Integer, default 2.)  Set the grid style for the plot to be GRID_STYLE.  Grid styles 0 through 3 are progressively more fancy, but style 4 is a somewhat different style.

      0. no axes, tick marks or labels.

      1. a pair of axes, with tick marks and labels.

      2. box around plot, with tick marks and labels.

      3. box around plot, with tick marks and labels; also grid lines.

      4. axes intersect at the origin, with tick marks and labels.

-h HEIGHT
--height-of-plot HEIGHT
     (Float, default 0.6.)  Set the fractional height of the plot with respect to the height of the display (or virtual display, in the case of a multiplot) to be HEIGHT.  A value of 1.0 will produce a plotting box that fills the available area.  Note that tick marks and labels are outside the plotting box, so that values less than 1.0 are generally used.

-K CLIP_MODE
--clip-mode CLIP_MODE
     (Integer, default 1.) Set the clip mode for the plot to CLIP_MODE. The clip mode is relevant only if data points are being joined by a line, and the line is not being filled to create a filled region (since filled regions are clipped in a fixed way).  There are three clip modes: 0, 1, and 2.  Clip mode 0 means that a line segment joining two data points will be plotted only if neither point is outside the plotting box.  Clip mode 1 means that it will be plotted if no more than one of the two points is outside, and clip mode 2 means that it will be plotted even if both are outside.  In all cases the line segment will be clipped to the plotting box.

-L TOP_LABEL
--top-label TOP_LABEL
     (String, default empty.)  Place the text string TOP_LABEL above the plot, as a plot title.  The string may include escape sequences (see Text String Format).  The --title-font-size option may be used to specify the size of the font.  The font is normally the same as the font used for labelling axes and tick labels, as selected by the -F option.  But this may be overridden with the --title-font-name option.

-l X|Y
--toggle-log-axis X|Y
     Set the specified axis to be a log axis rather than a linear axis, or vice versa.  By default, both axes are linear axes.

-N X|Y
--toggle-no-ticks X|Y
     Toggle the presence of ticks and tick labels on the specified axis. This applies to the grid styles that normally include ticks and tick labels, i.e., grid styles 1, 2, 3, and 4.

-R X|Y
--toggle-round-to-next-tick X|Y
     Toggle the rounding of the limits of the specified axis, so that they are integer multiples of the spacing between labeled tick marks.  By default this does not take place if the user uses the -x or -y options to set axis limits explicitly.

-r RIGHT
--right-shift RIGHT
     (Float, default 0.2.)  Move the plot to the right by a fractional amount RIGHT with respect to the width of the display (or virtual display, in the case of a multiplot).  This produces a margin on the left side of the plotting box.  A value of 0.5 will produce a margin half the width of the available area.  Note that the tick marks and labels are drawn in the margin.

-s
--save-screen
     Save the screen.  This option requests that graph not erase the display device before it begins to plot.  This is relevant only to graph -T tek and raw graph.  It may be employed to perform a crude sort of multiplotting.

-T TICK_SIZE
--tick-size TICK_SIZE
     (Float, default .02.) Set the fractional size of the tick marks on each axis to be TICK_SIZE.  A value of 1.0 produces tick marks on the x axis whose length is equal to the width of the plotting box.  A negative TICK_SIZE will yield tick marks that extend outside the box, rather than inside.

-t
--toggle-transpose-axes
     Transpose the abscissa and ordinate.  This causes the axes to be interchanged, and the options that apply to each axis to be applied to the opposite axis.  That is, data points are read in as (y, x) pairs, and such options as -x and -X apply to the y axis rather than the x axis.  If the -I e option is in force, so that the data points are read with error bars, the orientation of the error bars will be switched between vertical and horizontal.

-u UP
--upward-shift UP
     (Float, default 0.2.)  Move the plot up by a fractional amount UP with respect to the height of the display (or virtual display, in the case of a multiplot).  This produces a margin below the plotting box. A value of 0.5 will produce a margin half the height of the available area.  Note that the tick marks and labels are drawn in the margin.

-w WIDTH
--width-of-plot WIDTH
     (Float, default 0.6.) Set the fractional width of the plot with respect to the width of the display (or virtual display, in the case of a multiplot) to be WIDTH.  A value of 1.0 will produce a plotting box that fills the available area.  Note that the tick marks and labels are outside the plotting box, so values less than 1.0 are generally used.

-x [LOWER_LIMIT [UPPER_LIMIT [SPACING]]]
--x-limits [LOWER_LIMIT [UPPER_LIMIT [SPACING]]]
     (Floats.) The arguments LOWER_LIMIT and UPPER_LIMIT specify the limits of the x axis, and the optional argument SPACING specifies the spacing of labeled ticks along the axis.  If any of the three arguments is missing, it is computed from the data. The arguments LOWER_LIMIT and UPPER_LIMIT must be present if graph is to act as a real-time filter.

-y [LOWER_LIMIT [UPPER_LIMIT [SPACING]]]
--y-limits [LOWER_LIMIT [UPPER_LIMIT [SPACING]]]
     (Floats.)  The arguments specify the limits of the y axis, and the spacing of labeled ticks along it, as for the x axis (see above).  The arguments LOWER_LIMIT and UPPER_LIMIT must be present if graph is to act as a real-time filter.

-X X_LABEL
--x-title X_LABEL
     (String, default empty.)  Set the label for the x axis to be the text string X_LABEL.  The string may include escape sequences (see Text String Format).  The -F and -f options may be used to specify the name of the font and the size of the font.

-Y Y_LABEL
--y-title Y_LABEL
     (String, default empty.) Set the label for the y axis to be the text string Y_LABEL.  The string may include escape sequences (see Text String Format).  The label will be rotated by 90 degrees so that it is parallel to the axis, unless the --toggle-rotate-y-label option is used.  Some old X Window System displays do not support rotated labels, and require the --toggle-rotate-y-label option.  The -F and -f options may be used to specify the name of the font and the size of the font.

--frame-color NAME
     (String, default "black".)  Set the color used for drawing the plot frame, and for drawing monochrome datasets (if any) to be NAME.  An unrecognized name sets the color to the default. For information on what names are recognized, see Color Names.

--frame-line-width FRAME_LINE_WIDTH
     (Float, default -1.0.)  Set the width of lines in the plot frame, as a fraction of the width of the display, to FRAME_LINE_WIDTH. A negative value means that the default value for the line width provided by the libplot graphics library should be used.  This value is device-dependent.  The interpretation of zero line width is also device-dependent (on some devices, a zero-width line is the thinnest line that can be drawn; on others, a zero-width line is invisible).

     graph -T tek does not support drawing lines with other than a default width, and graph -T hpgl does not support doing so if the environment variable HPGL_VERSION is set to a value less than "2" (the default). idraw.

--max-line-length MAX_LINE_LENGTH
     (Integer, default 500.) Set the maximum number of points that a polygonal line drawn through any dataset may contain, before it is flushed to the display device, to equal MAX_LINE_LENGTH.  If this flushing occurs, the polygonal line will be split into two or more sub-lines, though the splitting should not be noticeable.  Splitting will not take place if the -q option, which requests filling, is used.

     The reason for splitting long polygonal lines is that some display devices (e.g., old Postscript printers and HP-GL plotters) have limited buffer sizes.  The environment variable MAX_LINE_LENGTH may also be used to specify the maximum line length.  This option has no effect in graph -T tek or raw graph, since they draw polylines in real time.

--page-size PAGESIZE
     (String, default "letter".)  Set the size of the page on which the plot will be positioned.  This is relevant only to graph -T ps, graph -T fig, and graph -T hpgl.  "letter" means an 8.5in by 11in page.  Any ISO page size in the range "a0"..."a4" or ANSI page size in the range "a"..."e" may be specified ("letter" is an alias for "a" and "tabloid" is an alias for "b").  "legal" and "ledger" are recognized page sizes also.  The environment variable PAGESIZE may equally well be used to specify the page size.

     For graph -T ps, the graphics display within which the plot is drawn will be a square region centered on the specified page and occupying its full width.  For graph -T fig, the graphics display will be a square region located in the upper left corner of an xfig display, with width equal to the width of the specified page.  graph -T hpgl, fine control over the positioning of the graphics display on the page may be accomplished by setting certain environment variables (see graph Environment).

--rotate ANGLE
     (Integer, default 0.)  Set the rotation angle of the plot on the page, relative to the default orientation.  This is currently relevant only to graph -T hpgl.  It facilitates switching between portrait and landscape orientations.  Recognized values for ANGLE are 0, 90, 180, and 270.  "no" and "yes" are equivalent to 0 and 90, respectively.  The environment variable ROTATE may equally well be used to specify the rotation angle.

--title-font-name TITLE_FONT_NAME
     (String, default "Helvetica" except for graph -T hpgl and graph -T tek, for which "HersheySerif" is the default.)  Set the font used for the plot title (`top label') to be FONT_NAME. Normally the font used for the plot title is the same as that used for labelling the axes and the ticks along the axes, as specified by the -F option.  But the --title-font-name option may be used to override this.  Font names are case-insensitive; for a list of available fonts, see Text Fonts.  If the font is not available, the default font will be used.

--title-font-size TITLE_FONT_SIZE
     (Float, default 0.07.)  Set the size of the font for the top label (`title'), as specified by the -L option, to TITLE_FONT_SIZE.  The size is expressed as a fraction of the size of the plotting box.

--toggle-rotate-y-label
     Position the label on the y axis (which is set with the -Y option) horizontally instead of vertically, or vice versa.  By default the label is rotated, so that it is positioned parallel to the y axis.  But some display devices (e.g., old X Window System displays) cannot handle rotated text.

--toggle-switch-axis-end X|Y
     Set the end of the indicated axis through which the other axis passes to be the opposite of what is currently the case.  E.g., --toggle-switch-axis-end x will cause the y axis to appear on the right of the plot rather than the left.  (The left end is the default.)  Similarly, --toggle-switch-axis-end y will cause the x axis to appear at the top of the plot rather than the bottom.  Note that if the x axis appears at the top, no plot title will be drawn (since there will be no room).

Dataset options
---------------

The following options affect the way in which individual datasets are read from files, and drawn as part of a plot.  They should appear on the command line before the file containing the datasets whose reading or rendering they will affect.  They may appear more than once on a command line, if more than one file is to be read.

The following three options affect the way in which datasets are read from files.

-I DATA-FORMAT
--input-format DATA-FORMAT
     This specifies which format the subsequent input file(s) are in.

     a
          ASCII format.  Each input file consists of pairs of floating point numbers, interpreted as the x and y coordinates of the data points in a dataset.  The x and y coordinates of a point need not appear on the same line, and points need not appear on different lines.  But if a blank line occurs (i.e., two newlines in succession are seen), it is interpreted as the end of a dataset, and the beginning of the next.

     e
          ASCII format, including error bars.  Similar to a format, except that triples (x,y,error) appear instead of pairs (x,y).

     g
          The ASCII `table' format produced by the gnuplot plotting program.

     f
          Single precision binary format.  Each input file is a sequence of single precision floating point numbers, interpreted as forming pairs (x,y).  Successive datasets are separated by a single occurrence of the quantity MAXFLOAT, which is the largest possible single precision floating point number.  On most machines this is approximately 3.4x10^38.

     d
          Double precision binary format.  Each input file is a sequence of double precision floating point numbers, interpreted as forming pairs (x,y).  Successive datasets are separated by a single occurrence of the quantity MAXDOUBLE, which is the largest possible double precision floating point number.  On most machines this is approximately 1.8x10^308.

     i
          Integer binary format.  Each input file is a sequence of integers, interpreted as forming pairs (x,y).  Successive datasets are separated by a single occurrence of the quantity MAXINT, which is the largest possible integer.  On most machines this is 2^31-1.

-a [STEP_SIZE [LOWER_LIMIT]]
--auto-abscissa [STEP_SIZE [LOWER_LIMIT]]
     (Floats, defaults 1.0 and 0.0.) Automatically generate abscissa (x) values.  Irrespective of data format (a, e, f, d, or i), this option specifies that the abscissa (x) values are missing: the dataset(s) to be read contain only ordinate (y) values.  The difference between successive x values will be STEP_SIZE, and the first x value will be LOWER_LIMIT.  To return to reading abscissa values from the input you may specify -a 0, which disables automatic generation of the abscissa and returns STEP_SIZE and LOWER_LIMIT to their default values.

-B
--toggle-auto-bump
     By default the linemode (set with -m, see below) is `bumped' (incremented by unity) at the beginning of each new dataset.  This option toggles auto-bumping: it turns it off if it was on, and on if it was off.

The following options affect the way in which individual datasets are drawn as part of a plot.  These options set the six `attributes' (symbol type, symbol font, linemode, line width, fill fraction, and color/monochrome) that each dataset has.

-m LINE_MODE
--line-mode LINE_MODE
     (Integer, default 1.) LINE_MODE specifies the mode (i.e., style) of the lines drawn between successive points in a dataset.  If the dataset is being rendered in monochrome, the interpretation of LINE_MODE is as follows.

      0. no line at all (points are disconnected)

      1. solid

      2. dotted

      3. dotdashed

      4. shortdashed

      5. longdashed

     Thereafter (i.e., for LINE_MODE greater than 5) the sequence of five linemodes repeats.  So besides linemode #0, there are a total of five distinct monochrome linemodes.  If the dataset is being rendered in color (as may be requested with the -C option), the interpretation of linemodes #0 through #5 is instead

      0. no line at all (points are disconnected)

      1. red, solid

      2. green, solid

      3. blue, solid

      4. magenta, solid

      5. cyan, solid

     Linemodes #6 through #10 use the same five colors, but are dotted; linemodes #11 through #15 are dotdashed; linemodes #16 through #20 are shortdashed; and linemodes #21 through #25 are longdashed.  So besides linemode #0, there are a total of 25 distinct colored linemodes.  A negative linemode indicates that no line should be drawn, but that the plotting symbol, if any (see below), should be in the color of the corresponding positive linemode.

-S [SYMBOL_NUMBER [SYMBOL_SIZE]]
--symbol [SYMBOL_NUMBER [SYMBOL_SIZE]]
     (Integer and float, defaults 0 and 0.03.) Draw a marker symbol at each data point.  SYMBOL_NUMBER specifies the symbol type, and SYMBOL_SIZE specifies the fractional size of the symbol with respect to the width of the plotting box.  If the dataset is being rendered in color, the symbol will have the color of the line that is being drawn to connect the data points.  You may request that symbols be drawn without any line connecting them by using the -m option to specify a negative linemode (see above).  The following table lists the first few marker symbols.

      0. no symbol at all

      1. dot

      2. plus (+)

      3. asterisk (*)

      4. circle

      5. cross

     Marker symbols 0 through 31 are furnished by the libplot graphics library.  See Marker Symbols.  Symbol numbers greater than or equal to 32 are interpreted as characters to be selected from a symbol font, which may be set with the --symbol-font-name option (see below).

-W LINE_WIDTH
--line-width LINE_WIDTH
     (Float, default -1.0.)  Set the width of the lines used to join successive points in a dataset, as a fraction of the width of the display, to LINE_WIDTH.  A negative value means that the default value for the line width provided by the libplot graphics library should be used.  This value is device-dependent.  The interpretation of zero line width is also device-dependent (on some devices, a zero-width line is the thinnest line that can be drawn; on others, a zero-width line is invisible).

     graph -T tek does not support drawing lines with other than a default width, and graph -T hpgl does not support doing so if the environment variable HPGL_VERSION is set to a value less than "2" (the default).

-q FILL_FRACTION
--fill-fraction FILL_FRACTION
     (Float, default -1.0.)  If successive points in a dataset are joined by line segments, set the shading intensity for the polygon formed by the line segments to be FILL_FRACTION.  A solid polygon (i.e., one filled with the `pen color' used for drawing the line segments) is obtained by choosing FILL_FRACTION=1.0.  The interior of the polygon will be white if FILL_FRACTION=0.0.  The polygon will be unfilled (transparent) if FILL_FRACTION is negative. If the polygon intersects itself, the `even-odd rule' will be used to determine which points are inside and outside, i.e., to determine which portions of the polygon should be shaded.  The even-odd rule is explained in the Postscript Language Reference Manual.  The -q option has no effect in graph -T tek, and it has no effect in graph -T hpgl if the environment variable HPGL_VERSION is set to "1".

-C
--toggle-use-color
     Toggle between color and monochrome rendering of datasets.  The interpretation of linemode depends on whether the rendering is being performed in color or monochrome; see the -m option above.

--symbol-font-name SYMBOL_FONT_NAME
     (String, default "ZapfDingbats" unless -T hpgl or -T tek is specified, in which case it is "HersheySerif".)  Set the symbol font, from which plotting symbols numbered 32 and higher are selected, to be SYMBOL_FONT_NAME.  Font names are case-insensitive.  For a list of available fonts, see Text Fonts.

Multiplot options
-----------------

The following options are used for multiplotting (placing several plots on a display, or a page, at once).

--reposition X Y SIZE
     (Floats, defaults 0.0, 0.0, 1.0.)  Set the `virtual display' within which the next plot will be drawn to be a square of size SIZE, with lower left corner (X,Y).  This is in the coordinate frame in which the physical display is a unit square with lower left corner (0,0).

--blankout BLANKOUT_FRACTION
     (Float, default 1.3.)  When drawing each additional plot of a multiplot, it is desirable to clear the region of the display on which the plot will be drawn.  If BLANKOUT_FRACTION=1.0, the region covered by the plot's plotting box will be cleared.  If BLANKOUT_FRACTION=1.3, a region 30% larger in each dimension will be cleared.  This is appropriate for inset plots; 1.0 would be appropriate for side by side plots.  Note that graph -T tek cannot clear regions, and graph -T hpgl cannot clear them unless the environment variable HPGL_VERSION is set to "2" (the default) and the environment variable HPGL_OPAQUE_MODE is set to "yes".

Raw graph options
-----------------

The following options are relevant only to raw graph, i.e., are relevant only if no display device is specified with the -T option.  In this case graph outputs a graphics metafile.  They should appear on the command line before any filenames, since they affect the output of the plot (or multiplot) as a whole.

-O
--portable-output
     Output the portable (human-readable) version of GNU metafile format, rather than a binary version (the default).

Informational options
---------------------

The following options request information.

--help
     Print a list of command-line options, and then exit.

--help-fonts
     Print a list of available fonts, and then exit.  The list will depend on which display device is specified with the -T option. graph -T X, graph -T ps, and graph -T fig each support the 35 standard Postscript fonts.  graph -T hpgl supports the 45 standard PCL 5 fonts.  All four, together with graph -T tek, support a set of 16 Hershey vector fonts.  Raw graph in principle supports any font, since its output must be translated to other formats with plot.

--version
     Print the version number of graph and the plotting utilities package, and exit.

Environment variables and X Window System resources
===================================================

The behavior of graph is affected by several environment variables and X Window System resources.  We have already mentioned the environment variables PAGESIZE, ROTATE, and MAX_LINE_LENGTH.  They simply serve as backups for the options --page-size, --rotate, and --max-line-length.  The remaining environment variables are specific to individual display devices.  They control device driver parameters.

graph -T X, which pops up a window on an X Window System display and draws graphics in it, checks the DISPLAY environment variable.  The value of this variable determines the display on which the window will be popped up.  graph -T X also looks at the X resource Xplot.geometry.  It will use the value of this resource, which may be set by the user, as the size of the window in terms of pixels.  The default value is "570x570".

graph -T hpgl, which produces Hewlett--Packard Graphics Language output, is affected by several environment variables.  The most important is HPGL_VERSION, which may be set to "1", "1.5", or "2" (the default).  "1" means that the output should be generic HP-GL, "1.5" means that the output should be suitable for the HP7550A pen plotter (HP-GL with some HP-GL/2 extensions), and "2" means that the output should be modern HP-GL/2.  By default, graph -T hpgl will draw with a fixed set of pens.  Which pens are present may be specified by setting the HPGL_PENS environment variable.  If HPGL_VERSION is "1" or "1.5", the default value of HPGL_PENS is "1=black"; if HPGL_VERSION is "2", the default value of HPGL_PENS is "1=black:2=red:3=green:4=yellow:5=blue:6=magenta:7=cyan".  The format should be self-explanatory.  HPGL_PENS may specify a color for any pen in the range #1...#31.  For information on what color names are recognized, see Color Names.  Pen #1 must always be present, though it need not be black. Any other pen in the range #1...#31 may be omitted.

If HPGL_VERSION is "2" then graph -T hpgl will be affected by two other environment variables.  If the value of HPGL_ASSIGN_COLORS is "yes", then graph -T hpgl will not be restricted to the palette specified in HPGL_PENS: it will assign colors to ``logical pens'' in the range #1...#31, as needed.  Also, if HPGL_OPAQUE_MODE is set equal to "yes" then pen #0 will be used as an opaque white pen, permitting the drawing of white lines and the filling of objects with opaque white.  Not all HP-GL/2 devices allow the assignment of colors to logical pens, or the use of pen #0 as an opaque white pen.  In particular, HP-GL/2 pen plotters do not.  So these two environment variables should be used with caution.

The position of the graph -T hpgl graphics display on the page may be adjusted by setting the HPGL_XOFFSET and HPGL_YOFFSET environment variables, which may be specified in centimeters, millimeters, or inches.  For example, an offset could be specified as "2cm" or "1.2in".  Also, the display may be rotated 90 degrees on the page by using the --rotate 90 option, or setting the ROTATE environment variable to "yes".

graph -T tek, which produces output for a Tektronix terminal or emulator, checks the TERM environment variable.  If the value of TERM is xterm, xterms, or kterm, it is taken as a sign that the current application is running in an X Window System VT100 terminal emulator: an xterm.  Before drawing graphics, graph -T tek will emit an escape sequence that causes the terminal emulator's auxiliary Tektronix window, which is normally hidden, to pop up.  After the graphics are drawn, an escape sequence that returns control to the original VT100 window will be emitted.  The Tektronix window will remain on the screen.

If the value of TERM is kermit, ansi.sys, ansissys, ansi.sysk, or ansisysk, it is taken as a sign that the current application is running in the VT100 terminal emulator provided by the DOS version of kermit.  Before drawing graphics, graph -T tek will emit an escape sequence that switches the terminal emulator to Tektronix mode.  Also, some of the Tektronix control codes output by graph -T tek will be kermit-specific.  There will be a limited amount of color support, which is not normally the case (the 16 ansi.sys colors will be supported).  After drawing graphics, graph -T tek will emit an escape sequence that returns the emulator to VT100 mode.  The key sequence `ALT minus' may be employed manually within kermit to switch between the two modes.

The plot Utility
****************

How to use plot
===============

The GNU plot filter plot translates GNU graphics metafiles to other formats.  The -T option is used to specify the type of display device.

Graphics metafiles are produced by the graph utility if no -T option is specified on its command line, and may also be produced by the libplot library.  The metafile format is a device-independent format for storage of graphic data.  By default, it is a binary rather than an human-readable format (see Metafiles).

plot, like the metafile format itself, is useful if you wish to preserve a plot that is to be displayed or edited on more than one type of display device.  The following illustrate how this is done.

To produce a plot of data arranged as alternating x and y coordinates in an ASCII file, you may use raw graph as follows:

     graph < ascii_data_file > test.plot

The file test.plot will be a GNU graphics metafile.  Similarly, to create a plot consisting of a simple figure, you may do:

     echo 0 0 1 1 2 0 | spline | graph > test.plot

To display any such plot on an X Window System display, you would do

     plot -T X < test.plot

To print the plot on a Postscript printer, you would do something like

     plot -T ps < test.plot | lpr

To edit it with the idraw drawing editor, you would do

     plot -T ps < test.plot > test.ps
     idraw test.ps

And to produce a plot that may be edited with the xfig drawing editor, you would do

     plot -T fig < test.plot > test.fig
     xfig test.fig

plot may behave differently depending on the environment in which it is invoked.  In particular, plot -T ps, plot -T fig, and plot -T hpgl are affected by the environment variable PAGESIZE.  plot -T X and plot -T tek are affected by the environment variables DISPLAY and TERM, respectively.  There are also several environment variables that affect the operation of plot -T hpgl.  For a complete discussion of the effects of the environment on plot, see plot Environment.

plot command-line options
=========================

The command-line options to GNU plot are listed below.  There are four sorts of option:

 1. Options setting the values of drawing parameters.

 2. Options relevant only to raw plot, i.e., relevant only if no display device is specified with the -T option.

 3. Options specifying the type of metafile format the input is in (for backward compatibility only).

 4. Options requesting information (e.g., --help).

Each option that takes an argument is followed, in parentheses, by the type and default value of the argument.

Note that input file names may be specified anywhere on the command line.  Only the options that precede a file name will take effect for that file.  If no file names are specified, or the name - is specified, the standard input is read.

The following options set the values of drawing parameters.

-T TYPE
--display-type TYPE
     (String, default "meta".)  Emit output for a display of type TYPE, which may be one of the strings "X", "ps", "fig", "hpgl", "tek", and "meta".  These refer respectively to the X Window System, idraw-editable Postscript, the format used by the xfig drawing editor, the Hewlett--Packard Graphics Language, Tektronix format, and device-independent GNU metafile format.

--max-line-length MAX_LINE_LENGTH
     (Integer, default 500.) Set the maximum number of points that a polygonal line may contain, before it is flushed to the display device, to equal MAX_LINE_LENGTH.  If this flushing occurs, the polygonal line will be split into two or more sub-lines, though the splitting should not be noticeable.  Splitting will not take place if the line is the boundary of a filled polygon.

     The reason for splitting long polygonal lines is that some display devices (e.g., old Postscript printers and HP-GL plotters) have limited buffer sizes.  The environment variable MAX_LINE_LENGTH may also be used to specify the maximum line length.  This option has no effect in plot -T tek or raw plot, since they draw polylines in real time.

--page-size PAGESIZE
     (String, default "letter".) Set the size of the page on which the plot will be positioned.  This is relevant only to plot -T ps, plot -T fig, and plot -T hpgl.  "letter" means an 8.5in by 11in page.  Any ISO page size in the range "a0"..."a4" or ANSI page size in the range "a"..."e" may be specified ("letter" is an alias for "a" and "tabloid" is an alias for "b").  "legal" and "ledger" are recognized page sizes also.  The environment variable PAGESIZE may equally well be used to specify the page size.

     For plot -T ps, the graphics display within which the plot is drawn will be a square region centered on the specified page and occupying its full width.  For plot -T fig, the graphics display will be a square region located in the upper left corner of an xfig display, with width equal to the width of the specified page.  For plot -T hpgl, fine control over the positioning of the graphics display on the page may be accomplished by setting certain environment variables (see plot Environment).

--rotate ANGLE
     (Integer, default 0.)  Set the rotation angle of the plot on the page, relative to the default orientation.  This is currently relevant only to plot -T hpgl.  It facilitates switching between portrait and landscape orientations.  Recognized values for ANGLE are 0, 90, 180, and 270.  "no" and "yes" are equivalent to 0 and 90, respectively.  The environment variable ROTATE may equally well be used to specify the rotation angle.

The following options set the initial values of additional drawing parameters.  All of these may be overridden by directives in the metafile itself.  In fact, these options are useful mostly for plotting old metafiles in the pre-GNU `plot(5)' format, which did not include such directives.

-f FONT_SIZE
--font-size FONT_SIZE
     (Float, default 0.0525.)  Set the initial size of the font used for rendering text, as a fraction of the width of the display device, to FONT_SIZE.

-F FONT_NAME
--font-name FONT_NAME
     (String, default "Helvetica" except for plot -T hpgl and plot -T tek, for which "HersheySerif" is the default.)  Set the font initially used for text (i.e., for `labels') to FONT_NAME.  Font names are case-insensitive.  For a list of available fonts, see Text Fonts.  If the specified font is not available, the default font will be used.

-W LINE_WIDTH
--line-width LINE_WIDTH
     (Float, default -1.0.)  Set the width of lines, as a fraction of the width of the display, to LINE_WIDTH.  A negative value means that the default value provided by the libplot graphics library should be used.  This value is device-dependent.  The interpretation of zero line width is also device-dependent (on some devices, a zero-width line is the thinnest line that can be drawn; on others, a zero-width line is invisible).

     plot -T tek does not support drawing lines with other than a default width, and plot -T hpgl does not support doing so if the environment variable HPGL_VERSION is set to a value less than "2" (the default).

--pen-color NAME
     (String, default "black".)  Set the pen color to be NAME.  An unrecognized name sets the pen color to the default.  For information on what color names are recognized, see Color Names.

The following option is relevant only to raw plot, i.e., relevant only if no display device is specified with the -T option.  In this case plot outputs a graphics metafile.

-O
--portable-output
     Output the portable (human-readable) version of GNU metafile format, rather than a binary version (the default).

plot will automatically determine which type of GNU metafile format the input is in.  There are two types: binary (the default) and portable (human-readable).  The binary format is machine-dependent. See Metafiles.

For compatibility with older software, the reading of input files in the pre-GNU `plot(5)' metafile format is also supported.  This is a binary format, with each integer argument represented as exactly two bytes. The order of the two bytes is machine dependent.  You may specify that the input is in plot(5) format rather than the ordinary GNU metafile format by using either the -h option (``high byte first'') or the -l option (``low byte first'').

-h
--high-byte-first-input
     Input is assumed to be in the traditional `plot(5)' metafile format, with the high-order byte of each integer occurring first.

-l
--low-byte-first-input
     Input is assumed to be in the traditional `plot(5)' metafile format, with the low-order byte of each integer occurring first.

The following options request information.

--help
     Print a list of command-line options, and then exit.

--help-fonts
     Print a list of available fonts, and then exit.  The list will depend on which display device is specified with the -T option.  plot -T X, plot -T ps, and plot -T fig each support the 35 standard Postscript fonts.  plot -T hpgl supports the 45 standard PCL 5 fonts.  All four, together with plot -T hpgl and plot -T tek, support a set of 16 Hershey vector fonts.  Raw plot in principle supports any font, since its output must be translated to other formats by a later invocation of plot.

--version
     Print the version number of plot and the plotting utilities package, and exit.

Environment variables and X Window System resources
===================================================

The behavior of plot is affected by several environment variables and X Window System resources.  We have already mentioned the environment variables PAGESIZE, ROTATE, and MAX_LINE_LENGTH.  They simply serve as backups for the options --page-size, --rotate, and --max-line-length.  The remaining environment variables are specific to individual display devices.  They control device driver parameters.

plot -T X, which pops up a window on an X Window System display and draws graphics in it, checks the DISPLAY environment variable.  The value of this variable determines the display on which the window will be popped up.  plot -T X also looks at the X resource Xplot.geometry.  It will use the value of this resource, which may be set by the user, as the size of the window in terms of pixels.  The default value is "570x570".

plot -T hpgl, which produces Hewlett--Packard Graphics Language output, is affected by several environment variables.  The most important is HPGL_VERSION, which may be set to "1", "1.5", or "2" (the default).  "1" means that the output should be generic HP-GL, "1.5" means that the output should be suitable for the HP7550A pen plotter (HP-GL with some HP-GL/2 extensions), and "2" means that the output should be modern HP-GL/2.  By default, plot -T hpgl will draw with a fixed set of pens.  Which pens are present may be specified by setting the HPGL_PENS environment variable.  If HPGL_VERSION is "1" or "1.5", the default value of HPGL_PENS is "1=black"; if HPGL_VERSION is "2", the default value of HPGL_PENS is "1=black:2=red:3=green:4=yellow:5=blue:6=magenta:7=cyan".  The format should be self-explanatory.  HPGL_PENS may specify a color for any pen in the range #1...#31.  For information on what color names are recognized, see Color Names.  Pen #1 must always be present, though it need not be black.  Any other pen in the range #1...#31 may be omitted.

If HPGL_VERSION is "2" then plot -T hpgl will be affected by two other environment variables.  If the value of HPGL_ASSIGN_COLORS is "yes", then plot -T hpgl will not be restricted to the palette specified in HPGL_PENS: it will assign colors to ``logical pens'' in the range #1...#31, as needed.  Also, if HPGL_OPAQUE_MODE is set equal to "yes" then pen #0 will be used as an opaque white pen, permitting the drawing of white lines and the filling of objects with opaque white.  Not all HP-GL/2 devices allow the assignment of colors to logical pens, or the use of pen #0 as an opaque white pen.  In particular, HP-GL/2 pen plotters do not.  So these two environment variables should be used with caution.

The position of the plot -T hpgl graphics display on the page may be adjusted by setting the HPGL_XOFFSET and HPGL_YOFFSET environment variables, which may be specified in centimeters, millimeters, or inches.  For example, an offset could be specified as "2cm" or "1.2in".  Also, the display may be rotated 90 degrees on the page by using the --rotate 90 option, or setting the ROTATE environment variable to "yes".

plot -T tek, which produces output for a Tektronix terminal or emulator, checks the TERM environment variable.  If the value of TERM is xterm, xterms, or kterm, it is taken as a sign that the current application is running in an X Window System VT100 terminal emulator: an xterm.  Before drawing graphics, plot -T tek will emit an escape sequence that causes the terminal emulator's auxiliary Tektronix window, which is normally hidden, to pop up.  After the graphics are drawn, an escape sequence that returns control to the original VT100 window will be emitted.  The Tektronix window will remain on the screen.

If the value of TERM is kermit, ansi.sys, ansissys, ansi.sysk, or ansisysk, it is taken as a sign that the current application is running in the VT100 terminal emulator provided by the DOS version of kermit.  Before drawing graphics, plot -T tek will emit an escape sequence that switches the terminal emulator to Tektronix mode.  Also, some of the Tektronix control codes output by plot -T tek will be kermit-specific.  There will be a limited amount of color support, which is not normally the case (the 16 ansi.sys colors will be supported).  After drawing graphics, plot -T tek will emit an escape sequence that returns the emulator to VT100 mode.  The key sequence `ALT minus' may be employed manually within kermit to switch between the two modes.

The tek2plot Utility
********************

How to use tek2plot
===================

The GNU Tektronix translator tek2plot translates Tektronix graphics format, which is produced by many legacy applications, to other formats.  The supported output formats are the same six formats that are supported by the GNU graph and plot utilities.

tek2plot will take input from a file specified on the command line or from standard input, just as the plot filter plot does. The invocation of tek2plot is similar to the invocation of plot.  See plot.

Tektronix graphics format is defined as a noninteractive version of the graphics format understood by Tektronix 4010/4014 terminals, as documented in the 4014 Service Manual, Tektronix Inc., 1974 (Tektronix Part #070-1648-00).  tek2plot does not support interactive features such as GIN mode and status enquiry.  However, it does support a few features of popular Tektronix emulators, such as the color extensions supported by the Tektronix emulator contained in the MS-DOS version of kermit.

tek2plot command-line options
=============================

The command-line options to the Tektronix translator tek2plot are listed below.  There are three sorts of option:

 1. General options.

 2. Options relevant only to raw tek2plot, i.e., relevant only if no display is specified with the -T option.

 3. Options requesting information (e.g., --help).

Each option that takes an argument is followed, in parentheses, by the type and default value of the argument.

Note that input file names may be specified anywhere on the command line.  Only the options that precede a file name will take effect for that file.  If no file names are specified, or the name - is specified, the standard input is read.

The following are general options.

-T TYPE
--display-type TYPE
     (String, default "meta".)  Emit output for a display of type TYPE, which may be one of the strings "X", "ps", "fig", "hpgl", "tek", and "meta".  These refer respectively to the X Window System, idraw-editable Postscript, the format used by the xfig drawing editor, the Hewlett--Packard Graphics Language, Tektronix format, and device-independent GNU metafile format.

-p N
--page-number N
     (Nonnegative integer.) Display only page number N, within the Tektronix file or sequence of Tektronix files that is being translated. Tektronix files may consist of one or more pages, numbered beginning with zero.  By default, tek2plot -T X, tek2plot -T tek, and tek2plot -T meta display these pages in succession, finally displaying the last page.  By default, the other variants of tek2plot display only the last page.  This option may be used to override the default behavior and select a particular page for display.

     Most Tektronix files consist of either one page (page #0) or two pages (an empty page #0, and page #1).  Tektronix files produced by the GNU plotting utilities (e.g., by graph -T tek) are normally of the latter sort.

-F FONT_NAME
--font-name FONT_NAME
     (String, default "Courier" except for tek2plot -T hpgl, for which "HersheySerif" is the default.)  Set the font initially used for text to FONT_NAME.  Font names are case-insensitive.  For a list of available fonts, see Text Fonts.  If a font outside the Courier family is chosen, the --position-chars option (see below) should probably be used.  For a list of available fonts, see Text Fonts.  If the specified font is not available, the default font will be used.

-W LINE_WIDTH
--line-width LINE_WIDTH
     (Float, default -1.0.)  Set the width of lines, as a fraction of the width of the display, to LINE_WIDTH.  A negative value means that the default value provided by the libplot graphics library should be used.  This value is device-dependent.  The interpretation of zero line width is also device-dependent (on some devices, a zero-width line is the thinnest line that can be drawn; on others, a zero-width line is invisible).

     tek2plot -T hpgl does not support drawing lines with other than a default width if the environment variable HPGL_VERSION is set to a value less than "2" (the default).

--max-line-length MAX_LINE_LENGTH
     (Integer, default 500.) Set the maximum number of points that a polygonal line may contain, before it is flushed to the display device, to equal MAX_LINE_LENGTH.  If this flushing occurs, the polygonal line will be split into two or more sub-lines, though the splitting should not be noticeable.

     The reason for splitting long polygonal lines is that some display devices (e.g., old Postscript printers and HP-GL plotters) have limited buffer sizes.  The environment variable MAX_LINE_LENGTH may also be used to specify the maximum line length.  This option has no effect in raw tek2plot, which has no buffer limitations.

--page-size PAGESIZE
     (String, default "letter".) Set the size of the page on which the plot will be positioned.  This is relevant only to tek2plot -T ps, tek2plot -T fig, and tek2plot -T hpgl.  "letter" means an 8.5in by 11in page.  Any ISO page size in the range "a0"..."a4" or ANSI page size in the range "a"..."e" may be specified ("letter" is an alias for "a" and "tabloid" is an alias for "b").  "legal" and "ledger" are recognized page sizes also.  The environment variable PAGESIZE may equally well be used to specify the page size.

     For tek2plot -T ps, the graphics display within which the plot is drawn will be a square region centered on the specified page and occupying its full width.  For tek2plot -T fig, the graphics display will be a square region located in the upper left corner of an xfig display, with width equal to the width of the specified page.  For tek2plot -T hpgl, fine control over the positioning of the graphics display on the page may be accomplished by setting certain environment variables (see tek2plot Environment).

--pen-color NAME
     (String, default "black".)  Set the pen color to be NAME.  An unrecognized name sets the pen color to the default.  For information on what color names are recognized, see Color Names.

--position-chars
     Position the characters in each text string individually on the display. If the text font is not a member of the Courier family, and especially if it is not a fixed-width font, this option is recommended. It will improve the appearance of text strings, at the price of making it difficult to edit the output file with xfig or idraw.

--rotate ANGLE
     (Integer, default 0.)  Set the rotation angle of the plot on the page, relative to the default orientation.  This is currently relevant only to tek2plot -T hpgl.  It facilitates switching between portrait and landscape orientations.  Recognized values for ANGLE are 0, 90, 180, and 270.  "no" and "yes" are equivalent to 0 and 90, respectively.  The environment variable ROTATE may equally well be used to specify the rotation angle.

--use-tek-fonts
     Use the bitmap fonts that were used on the original Tektronix 4010/4014 terminal.  This option is relevant only to tek2plot -T X.  The four relevant bitmap fonts are distributed as part of the plotting utilities package under the names tekfont0...tekfont3. They may readily be installed on any modern X Windows server.  For this option to work properly, you must also select a window size of "1024x1024" pixels, by setting the Xplot.geometry resource. See tek2plot Environment.  The reason for this restriction is that bitmap fonts, unlike the scalable fonts that the plotting utilities normally use, may not be rescaled.

The following option is relevant only to raw tek2plot, i.e., relevant only if no display device is specified with the -T option.  In this case tek2plot outputs a graphics metafile.

-O
--portable-output
     Output the portable (human-readable) version of GNU metafile format, rather than a binary version (the default).

The following options request information.

--help
     Print a list of command-line options, and then exit.

--help-fonts
     Print a list of available fonts, and then exit.  The list will depend on which display device is specified with the -T option. tek2plot -T X, tek2plot -T ps, and tek2plot -T fig each support the 35 standard Postscript fonts.  tek2plot -T hpgl supports the 45 standard PCL 5 fonts.  All four, together with tek2plot -T hpgl, support a set of 16 Hershey vector fonts.  Raw tek2plot in principle supports any font, since its output must be translated to other formats with plot.

--version
     Print the version number of tek2plot and the plotting utilities package, and exit.

Environment variables and X Window System resources
===================================================

The behavior of tek2plot is affected by several environment variables and X Window System resources, which are the same as those that affect graph and plot.  For convenience, we list them here.

We have already mentioned the environment variables PAGESIZE, ROTATE, and MAX_LINE_LENGTH.  They simply serve as backups for the options --page-size, --rotate, and --max-line-length.  The remaining environment variables are specific to individual display devices.  They control device driver parameters.

tek2plot -T X, which pops up a window on an X Window System display and draws graphics in it, checks the DISPLAY environment variable.  The value of this variable determines the display on which the window will be popped up.  tek2plot -T X also looks at the X resource Xplot.geometry.  It will use the value of this resource, which may be set by the user, as the size of the window in terms of pixels.  The default value is "570x570".

tek2plot -T hpgl, which produces Hewlett--Packard Graphics Language output, is affected by several environment variables.  The most important is HPGL_VERSION, which may be set to "1", "1.5", or "2" (the default).  "1" means that the output should be generic HP-GL, "1.5" means that the output should be suitable for the HP7550A pen plotter (HP-GL with some HP-GL/2 extensions), and "2" means that the output should be modern HP-GL/2.  By default, tek2plot -T hpgl will draw with a fixed set of pens.  Which pens are present may be specified by setting the HPGL_PENS environment variable.  If HPGL_VERSION is "1" or "1.5", the default value of HPGL_PENS is "1=black"; if HPGL_VERSION is "2", the default value of HPGL_PENS is "1=black:2=red:3=green:4=yellow:5=blue:6=magenta:7=cyan".  The format should be self-explanatory.  HPGL_PENS may specify a color for any pen in the range #1...#31.  For information on what color names are recognized, see Color Names.  Pen #1 must always be present, though it need not be black.  Any other pen in the range #1...#31 may be omitted.

If HPGL_VERSION is "2" then tek2plot -T hpgl will be affected by two other environment variables.  If the value of HPGL_ASSIGN_COLORS is "yes", then tek2plot -T hpgl will not be restricted to the palette specified in HPGL_PENS: it will assign colors to ``logical pens'' in the range #1...#31, as needed.  Also, if HPGL_OPAQUE_MODE is set equal to "yes" then pen #0 will be used as an opaque white pen, permitting the drawing of white lines and the filling of objects with opaque white.  Not all HP-GL/2 devices allow the assignment of colors to logical pens, or the use of pen #0 as an opaque white pen.  In particular, HP-GL/2 pen plotters do not.  So these two environment variables should be used with caution.

The position of the tek2plot -T hpgl graphics display on the page may be adjusted by setting the HPGL_XOFFSET and HPGL_YOFFSET environment variables, which may be specified in centimeters, millimeters, or inches.  For example, an offset could be specified as "2cm" or "1.2in".  Also, the display may be rotated 90 degrees on the page by using the --rotate 90 option, or setting the ROTATE environment variable to "yes".

The spline Utility
******************

How to use spline
=================

GNU spline is a program for interpolating between the data points in one or more datasets.  Each dataset would consist of values for an independent variable and a single dependent variable.  When discussing interpolation, we call these variables `t' and `x', respectively.  The simplest case is when there is only a single dataset, in ASCII format.  For example, the input file could contain the lines

     0.0  0.0
     1.0  1.0
     2.0  0.0

which are the coordinates (t,x) of the data points (0,0), (1,1), and (2,0).  Data points do not need to be on different lines, nor do the t and x coordinates of a data point need to be on the same line.  However, there should be no blank lines in the input if it is to be viewed as forming a single dataset.  Also, the t coordinates should be monotonically increasing: the dataset must have an interpretation as a function.

You would construct a curve (an `interpolating spline') passing through the points in such a dataset by doing

     spline input_file > output_file

To produce a Postscript plot of the spline with the graph utility, you would do

     spline input_file | graph -T ps > output.ps

To display a spline on an X Window System display, you could do

     echo 0 0 1 1 2 0 | spline | graph -T X

Notice that the last example avoids the use of the input file altogether.  spline will read from standard input if no files are specified on the command line, or if the special name name - is specified.

What exactly does spline do?  First, it fits a curve through the points in the dataset.  Then it splits the interval over which the independent variable t ranges into 100 sub-intervals, and computes the x values at each of the 101 subdivision points. It then outputs each of the pairs (t, x).  These are the coordinates of 101 points that lie along a curve that interpolates between the points in the dataset.  If there is more than one dataset in the input (separated by blank lines), each dataset is interpolated separately.

You may use the -n option to replace `100' by any other integer. You may also use the -t option to specify an interpolation interval that differs from the default (the interval over which the independent variable ranges).  For example, the command

     echo 0 0 1 1 2 0 | spline -n 20 -t 1.0 1.5 > output_file

will produce a dataset consisting of 21 (rather than 101) data points, with t values spaced regularly between 1.0 and 1.5 (rather than between 0.0 and 2.0).  The data points will lie along a curve passing through (0,0), (1,1), and (2,0).  This curve will be a parabola.

In general, the interpolating curve will be a piecewise cubic spline. That is, between each pair of adjacent `nodes' (points in the input dataset), x will be a cubic function of t.  This function will differ, depending on which pair of nodes t lies between.  At each node, both the slope and curvature of the cubic pieces to either side will match.  In mathematical terms, the interpolating curve will be twice continuously differentiable.

spline supports `adding tension' to the interpolating curve.  A nonzero value for the tension may be specified with the -T option.  For example, a spline under considerable tension may be computed and displayed by doing

     echo 0 0 1 0 2 0 | spline -T 10 | graph -T X

As the tension parameter is increased to positive infinity, the spline will converge to a polygonal line.  You are supposed to think of the spline as being drawn taut.  Actually, tension may be negative as well as positive.  A spline with negative tension will tend to bow outward, in fact to oscillate sinusoidally.  But as the tension decreases to negative infinity, the spline, though oscillatory, will again converge to a polygonal line.

If the tension is positive, its reciprocal will be the maximum range of the independent variable t over which the spline will `like to curve'.  Increasing the tension far above zero will accordingly force the spline to consist of short curved sections, centered on the data points, and sections that are almost straight.  It follows that tension is a `dimensionful' quantity.  If the tension is nonzero, then when the values of the independent variable are multiplied by some common positive factor, the tension should be divided by the same factor to obtain a scaled version of the original spline.  If the tension is zero (the default, or cubic spline case), then the computation of the spline will be unaffected by linear scaling of the data.

In mathematical terms, a spline under tension will satisfy the differential equation x''''=sgn(tension)*(tension^2)x'' between each successive pair of nodes.  If the tension equals zero, which is the default, the fourth derivative of x with respect to t will equal zero at every point.  In this case, x as a function of t will reduce to a cubic polynomial between each successive pair of nodes.  But if the tension is nonzero, x will not be a polynomial function of t.  It may be expressed in terms of exponential functions, however.

Irrespective of whether or not the spline is under tension, you may specify the -p option if you wish the spline to be a periodic function of t.  This will only work if the x values for the first and last points in the dataset are equal.  Otherwise, it would make no sense to compute a periodic interpolation.

It is sometimes useful to interpolate between data points at the same time as they are generated by an auxiliary program.  That is, it is useful for spline to function as a real-time filter. spline does not normally act as a filter, since computing an interpolating curve that is as smooth as possible is a global task.  But if the -f option is specified, spline will indeed function as a filter.  A different interpolation algorithm (cubic Bessel interpolation, which is local rather than global) will be used.  If -f is specified, -p may not be specified.  Also, if -f is specified then an interpolation interval must be requested explicitly with the -t option.

Cubic Bessel interpolation is inherently less smooth than the construction of a global cubic spline.  If the -f option is specified, the slope of the spline at each node will be chosen by fitting a parabola through that node, and the two adjacent nodes.  The slopes of the two interpolating segments to either side of each interior node will match at that node, but typically their curvatures will not. In mathematical terms, the interpolating curve will be continuously differentiable, but in general not twice continuously differentiable. This loss of differentiability is the price that is paid for functioning as a real-time filter.

The algorithms used by spline are similar to those discussed in D. Kincaid and W. Cheney, Numerical Analysis (2nd ed., Brooks/Cole, 1996), section 6.4, and C. de Boor, A Practical Guide to Splines (Springer-Verlag, 1978), Chapter 4.

spline command-line options
===========================

The options to spline are listed below.  There are three sorts of option:

 1. Options specifying the type of interpolation to be performed.

 2. Options specifying the input or output format.

 3. Options requesting information (e.g., --help).

Options that take an argument are followed, in parentheses, by the type and default value of the argument.

Besides options, the command line may include the names of one or more input files. If no files are listed, the standard input is read.  Unless the -a option is used (see below), the input is expected to be a sequence of data points, given as alternating t and x coordinates.  There may be more than one dataset per input file.  If the files are in ASCII format (the default), datasets are separated by blank lines.

The following options specify the type of interpolation to be performed on each dataset.

-f
--filter
     Use a local interpolation algorithm (the cubic Bessel algorithm), so that spline may be used as a real-time filter.  The slope of the interpolating curve at each point in a dataset will be chosen by fitting a parabola through that point and the two adjacent points in the dataset.  If -f is specified then the -t option, otherwise optional, must be used as well.  Also, if -f is specified then the -k, -p, and -T options may not be used.

     If -f is not specified, then a different (global) interpolation algorithm will be used.

-k K
--boundary-condition K
     (Float, default 1.0.) Set the boundary condition parameter for each constructed spline to be K.  The spline will satisfy the two boundary conditions x''[0]=kx''[1] and x''[n]=kx''[n-1]. Here x[0] and x[1] signify the ordinate values at the first two points of a dataset, and x[n-1] and x[n] the ordinate values at the last two points.  Setting K to zero will yield a `natural' spline, i.e., one that has zero curvature at the two ends of the dataset.  The -k option may not be used if -f or -p is specified.

-n N
--number-of-intervals N
     (Integer, default 100.)  Subdivide the interval over which interpolation occurs into N subintervals.  The number of data points computed, and written to the output, will be n+1.

-p
--periodic
     Construct a periodic spline.  If this option is specified, the x values for the first and last points in each dataset must be equal.  The -f and -k options may not be used if -p is specified.

-T TENSION
--tension TENSION
     (Float, default 0.0.) Set the tension in each interpolating spline to be TENSION.  Between each pair of successive points in a dataset, the constructed spline will satisfy the differential equation x''''=sgn(tension)*(tension^2)x''. If TENSION equals zero, the spline will be piecewise cubic.  As TENSION increases to positive infinity, the spline will converge to a polygonal line.  The -T option may not be used if -f is specified.

-t TMIN TMAX [TSPACING]
--t-limits TMIN TMAX [TSPACING]
     For each dataset, set the interval over which interpolation occurs to be the interval between TMIN and TMAX.  If TSPACING is not specified, the interval will be divided into the number of subintervals specified by the -n option.  If the -t option is not used, the interval over which interpolation occurs will be the entire range of the independent variable in the dataset.  The -t option must always be used if the -f option is used to request filter-like behavior (see above).

The following options specify the format of the input file(s) and the output file.

-I DATA-FORMAT
--input-format DATA-FORMAT
     (Character, default a.)  Set the data format for the input file(s) to be DATA-FORMAT.  The possible data formats are as follows.

     a
          ASCII format.  Each file consists of pairs of floating point numbers, interpreted as the t and x coordinates of the data points in a dataset.  The t and x coordinates of a point need not appear on the same line, and points need not appear on different lines.  But if a blank line occurs (i.e., two newlines in succession are seen), it is interpreted as the end of a dataset, and the beginning of the next.

     f
          Single precision binary format.  Each file is a sequence of single precision floating point numbers, interpreted as forming pairs (t,x).  Successive datasets are separated by a single occurrence of the quantity MAXFLOAT, which is the largest possible single precision floating point number.  On most machines this is approximately 3.4x10^38.

     d
          Double precision binary format.  Each file is a sequence of double precision floating point numbers, interpreted as forming pairs (t,x).  Successive datasets are separated by a single occurrence of the quantity MAXDOUBLE, which is the largest possible double precision floating point number.  On most machines this is approximately 1.8x10^308.

     i
          Integer binary format.  Each file is a sequence of integers, interpreted as forming pairs (t,x).  Successive datasets are separated by a single occurrence of the quantity MAXINT, which is the largest possible integer.  On most machines this is 2^31-1.

-a [STEP_SIZE [LOWER_LIMIT]]
--auto-abscissa [STEP_SIZE [LOWER_LIMIT]]
     (Floats, defaults 1.0 and 0.0.)  Automatically generate values for the independent variable (t).  Irrespective of data format (a, e, f, d, or i), this option specifies that the values of the independent variable (t) are missing: the dataset(s) to be read contain only values of the dependent variable (x).  The difference between successive t values will be STEP_SIZE, and the first t value will be LOWER_LIMIT.  To return to reading the values of t from the input you may specify -a 0, which disables automatic generation of t and returns STEP_SIZE and LOWER_LIMIT to their default values.

-O DATA-FORMAT
--output-format DATA-FORMAT
     (Character, default a.)  Set the data format for the output file to be DATA-FORMAT.  The interpretation of the DATA-FORMAT argument is the same as for the -I option.

-P SIGNIFICANT-DIGITS
--precision SIGNIFICANT-DIGITS
     (Integer, default 6.)  Set the numerical precision for the t and x coordinates in the output file to be SIGNIFICANT-DIGITS. This takes effect only if the output file is written in a format, i.e., in ASCII.

The following options request information.

--help
     Print a list of command-line options, and then exit.

--version
     Print the version number of spline and the plotting utilities package, and exit.

The ode Utility
***************

The GNU ode utility can produce a numerical solution to the initial value problem for many systems of first-order ordinary differential equations (ODE's).  ode may also be used to solve systems of higher-order ODE's, since a simple procedure converts an n'th-order equation into n first-order equations.  The output of ode may easily be piped to graph, so that one or more solution curves may be plotted as they are generated.

Three distinct schemes for numerical solution are implemented: Runge--Kutta--Fehlberg (the default), Adams--Moulton, and Euler.  The Runge--Kutta--Fehlberg and Adams--Moulton schemes are available with adaptive stepsize.

Mathematical basics
===================

We begin with some standard definitions.  A differential equation is an equation involving an unknown function and its derivatives.  A differential equation is ordinary if the unknown function depends on only one independent variable, often denoted t. The order of the differential equation is the order of the highest-order derivative in the equation.  One speaks of a family, or system of equations when more than one equation is involved.  If the equations are dependent on one another, they are said to be coupled.  A solution is any function satisfying the equations.  An initial value problem is present when there exist subsidiary conditions on the unknown function and its derivatives, all of which are given at the same value of the independent variable.  In principle, such an `initial condition' specifies a unique solution. Questions about the existence and uniqueness of a solution, along with further terminology, are discussed in any introductory text.  (See Chapter 1 of Birkhoff and Rota's Ordinary Differential Equations.  For this and other references relevant to ode, see ODE Bibliography.)

In practical problems, the solution of a differential equation is usually not expressible in terms of elementary functions.  Hence the need for a numerical solution.

A numerical scheme for solving an initial value problem produces an approximate solution, using only functional evaluations and the operations of arithmetic.  ode solves first-order initial value problems of the form:

     x' = f(t,x,y,...,z)
     y' = g(t,x,y,...,z)
        .
        .
        .
     z' = h(t,x,y,...,z)

given the initial values for each dependent variable at the initial value of the independent variable t, i.e.,

     x(a) = b
     y(a) = c
          .
          .
          .
     z(a) = d
     t = a

where a,b,c,...,d are constants.

For ode to be able to solve such a problem numerically, the functions f,g,...,g must be expressed, using the usual operators (+,-,*,/,^), in terms of certain basic functions that ode recognizes.  These are the same functions that the plotting program gnuplot recognizes.  Moreover, each of f,g,...,g must be given explicitly.  ode cannot deal with a system in which one or more of the first derivatives is defined implicitly rather than explicitly.

All schemes for numerical solution involve the calculation of an approximate solution at discrete values of the independent variable t, where the `stepsize' (the difference between any two successive values of t, usually denoted h) may be constant or chosen adaptively.  In general, as the stepsize decreases the solution becomes more accurate.  In ode, the stepsize may be adjusted by the user.

Simple examples using ode
=========================

The following examples should illustrate the procedure of stating an initial value problem and solving it with ode.  If these examples are too elementary, see Input Language, for a formal specification of the ode input language.  There is also a directory containing examples of ode input, called ode-examples, which is distributed along with the GNU plotting utilities.

Our first example is a simple one, namely

     y'(t) = y(t)

with the initial condition

     y(0) = 1

The solution to this differential equation is

     y(t) = e^t.

In particular

     y(1) = e^1 = 2.718282

to seven digits of accuracy.

You may obtain this result with the aid of ode by typing on the command line the sequence of commands

     ode
     y' = y
     y = 1
     print t, y
     step 0, 1

Two columns of numbers will appear.  Each line will show the value of the independent variable t, and the value of the variable y, as t is `stepped' from 0 to 1.  The last line will be

     1 2.718282

as expected.  You may use the -p option to change the precision. If, for example, you type ode -p 10 rather than ode, you will get ten digits of accuracy in the output, rather than seven (the default).

After the above output, ode will wait for further instructions. Entering for example the line

     step 1, 0

should yield two more columns of numbers, containing the values of t and y that are computed when t is stepped back from 1 to 0.  You could type instead

     step 1, 2

to increase rather than decrease t.  To exit ode, you would type a line containing only ., i.e. a single period, and tap `return'.  ode will also exit if it sees an end-of-file indicator in its input stream, which you can send from your terminal by typing control-D.

Each line of the preceding example should be self-explanatory.  A step statement sets the beginning and the end of an interval over which the independent variable (here, t) will range, and causes ode to set the numerical scheme in motion.  The initial value appearing in the first step statement (i.e., 0) and the assignment statement

     y = 1

are equivalent to the initial condition y(0) = 1.  The statements y' = y and y = 1 are very different: y' = y defines a way of computing the derivative of y, while y = 1 sets the initial value of y.  Whenever a step statement is encountered, ode tries to step the independent variable through the interval it specifies.  Which values are to be printed at each step is specified by the most recent print statement.  For example,

     print t, y, y'

would cause the current value of the independent variable t, the variable y, and its derivative to be printed at each step.

To illustrate ode's ability to take its input or the initial part of its input from a file, you could prepare a file containing the following lines:

     # an ode to Euler
     y  = 1
     y' = y
     print t, y, y'

Call this file euler.  (The # line is a comment line, which may appear at any point.  Everything from the # to the end of the line on which it appears will be ignored.)  To process this file with ode, you could type on your terminal

     ode -f euler
     step 0, 1

These two lines cause ode to read the file euler, and the stepping to take place.  You will now get three quantities (t, y, and y') printed at each of the values of t between 0 and 1.  At the conclusion of the stepping, ode will wait for any further commands to be input from the terminal.  This example illustrates that

     ode -f euler

is not equivalent to

     ode < euler

The latter would cause ode to take all its input from the file euler, while the former allows subsequent input from the terminal.  For the latter to produce output, you would need to include a step line at the end of the file.  You would not need to include a . line, however.  . is used to terminate input only when input is being read from a terminal.

A second simple example involves the numerical solution of a second-order differential equation.  Consider the initial value problem

     y''(t) = -y(t)
     y(0) = 0
     y'(0) = 1

Its solution would be

     y(t) = sin(t)

To solve this problem using ode, you must express this second-order equation as two first-order equations.  Toward this end you would introduce a new function, called yp say, of the independent variable t.  The pair of equations

     y' = yp
     yp' = -y

would be equivalent to the single equation above.  This sort of reduction of an n'th order problem to n first order problems is a standard technique.

To plot the variable y as a function of the variable t, you could create a file containing the lines

     # sine : y''(t) = -y(t), y(0) = 0, y'(0) = 1
     sine' = cosine
     cosine' = -sine
     sine = 0
     cosine = 1
     print t, sine

(y and yp have been renamed sine and cosine, since that is what they will be.)  Call this file sine.  To display the generated data points on an X Window System display as they are generated, you would type

     ode -f sine | graph -T X -x 0 10 -y -1 1
     step 0, 2*PI
     .

After you type the ode line, graph -T X will pop up a window, and after you type the step line, the generated dataset will be drawn in it.  The -x 0 10 and -y -1 1 options, which set the bounds for the two axes, are necessary if you wish to display points in real time: as they are generated.  If the axis bounds were not specified on the command line, graph -T X would wait until all points are read from the input before determining the bounds, and drawing the plot.

A slight modification of this example, showing how ode can generate several datasets in succession and plot them on the same graph, would be the following.  Suppose that you type on your terminal the following lines.

     ode -f sine | graph -T X -C -x 0 10 -y -1 1
     step 0, PI
     step PI, 2*PI
     step 2*PI, 3*PI
     .

Then the sine curve will be traced out in three stages.  Since the output from each step statement ends with a blank line, graph -T X will treat each section of the sine curve as a different dataset.  If you are using a color display, each of the three sections will be plotted in a different color.  This is a feature provided by graph -T X, which normally changes its linemode after each dataset it reads.  If you do not like this feature, you may turn it off by using graph -T X -B instead of graph -T X.

In the above examples, you could use any of the other variants of graph instead of graph -T X.  For example, you could use graph -T ps to obtain a plot in encapsulated Postscript format, by typing

     ode -f sine | graph -T ps > plot.ps
     step 0, 2*PI
     .

You should note that of the six variants of graph, graph -T ps, graph -T fig, and graph -T hpgl do not produce output in real time, even when the axis bounds are specified with the -x and -y options.  So if graph -T ps, graph -T fig, or graph -T hpgl is used, the plot will be produced only when input from ode is terminated, which will occur when you type ..

In the preceding examples, the derivatives of the dependent variables were specified by comparatively simple expressions.  They are allowed to be arbitrarily complicated functions of the dependent variables and the independent variable.  They also may involve any of the functions that are built into ode.  ode has a fair number of functions built in, including abs, sqrt, exp, log, log10, sin, cos, tan, asin, acos, atan, sinh, cosh, tanh, asinh, acosh, and atanh.  Less familiar functions which are built into it are besj0, besj1, besy0, besy1, erf, erfc, inverf, lgamma, gamma, norm, invnorm, ibeta, and igamma.  These have the same definitions as in the plotting program gnuplot.  (All functions take a single argument, except for ibeta, which takes three, and igamma, which takes two).  ode also knows the meaning of the constant PI, as the above examples show.  The names of the preceding functions are reserved, so, e.g., cos and sin may not be used as names for variables.

Other than the restriction of avoiding reserved names and keywords, the names of variables may be chosen arbitrarily.  Any sequence of alphanumeric characters starting with an alphabetic character may be used; the first 32 characters are significant.  It is worth noting that ode identifies the independent variable by the fact that it is (or should be) the only variable that has not appeared on the left side of a differential equation or an initial value assignment.  If there is more than than one such variable then no stepping takes place; instead, an error message is printed.  If there is no such variable, a dummy independent variable is invented and given the name (indep), internally.

Additional examples using ode
=============================

We explain here how to use some additional features of ode. However, the discussion below does not cover all of its capabilities. For a complete list of command-line options, see ode Invocation.

It is easy to use ode to create plots of great beauty.  An example would be a plot of a strange attractor, namely the Lorenz attractor.  Suppose that a file named lorenz contains the following lines.

     # The Lorenz model, a system of three coupled ODE's with parameter r.
     x' = -3*(x-y)
     y' = -x*z+r*x-y
     z' = x*y-z

     r = 26
     x = 0; y = 1; z = 0

     print x, y
     step 0, 200

Then executing the command

     <lorenz ode | graph -T X -C -x -10 10 -y -10 10

would produce a plot of the Lorenz attractor (strictly speaking, a plot of one of its two-dimensional projections).  You may produce a Postscript plot of the Lorenz attractor, and print it, by doing something like

     <lorenz ode | graph -T ps -x -10 10 -y -10 10 -W 0 | lpr

The -W 0 (``zero width'') option requests that graph -T ps use the thinnest line possible, to improve the visual appearance of the plot on a printer or other Postscript device.

Besides plotting a visually striking object in real time, the Lorenz attractor example shows how statements may be separated by semicolons, rather than appearing on different lines.  It also shows how to use symbolic constants.  In the description read by ode the parameter r is a variable like x, y, and z.  But unlike them it is not updated during stepping, since no formula for its derivative r' is given.

Our second example deals with the interactive construction of a `phase portrait': a set of solution curves with different initial conditions.  Phase portraits are of paramount interest in the qualitative theory of differential equations, and also possess æsthetic appeal.

Since a description read by ode may contain any number of step statements, multiple solution curves may be plotted in a single run.  The most recent print statement will be used with each step statement.  In practice, a phase portrait would be drawn from a few well-chosen solution curves.  Choosing a good set of solution curves may require experimentation, which makes interactivity and real-time plotting all-important.

As an example, consider a so-called Lotka--Volterra predator--prey model.  Suppose that in a lake there are two species of fish: A (the prey) who live by eating a plentiful supply of plants, and B (the predator) who eat A.  Let x(t) be the population of A and y(t) the population of B at time t.  A crude model for the interaction of A and B is given by the equations

     x' = x(a-by)
     y' = y(cx-d)

where a, b, c, d are positive constants.  To draw a phase portrait for this system interactively, you could type

     ode | graph -T X -C -x 0 5 -y 0 5
     x' = (a - b*y) * x
     y' = (c*x - d) * y
     a = 1; b = 1; c = 1; d = 1;
     print x, y

     x = 1; y = 2
     step 0, 10
     x = 1; y = 3
     step 0, 10
     x = 1; y = 4
     step 0, 10
     x = 1; y = 5
     step 0, 10
     .

Four curves will be drawn in succession, one per step line.  They will be periodic; this periodicity is similar to the fluctuations between predator and prey populations that occur in real-world ecosystems.  On a color display the curves will appear in different colors, since by default, graph -T X changes the line mode between datasets.  That feature may be turned off by using graph -T X -B rather than graph -T X.

It is sometimes useful to use ode and graph to plot discrete points, which are not joined by line segments to form a curve. Our third example illustrates this.  Suppose the file atwoods contains the lines

     m = 1
     M = 1.0625
     a = 0.5; adot = 0
     l = 10; ldot = 0

     ldot' = ( m * l * adot * adot - M * 9.8 + m * 9.8 * cos(a) ) / (m + M)
     l'    = ldot
     adot' = (-1/l) * (9.8 * sin(a) +  2 * adot * ldot)
     a'    = adot

     print l, ldot
     step 0, 400

The first few lines describe the functioning of a so-called swinging Atwood's machine.  An ordinary Atwood's machine consists of a taut cord draped over a pulley, with a mass attached to the cord at each end. Normally, the heavier mass (M) would win against the lighter mass (m), and draw it upward.  A swinging Atwood's machine allows the lighter mass to swing back and forth as well as move vertically.

The print l, ldot statement requests that the vertical position and vertical velocity of the lighter mass be printed out at each step. If you run the command

     <atwoods ode | graph -T X -x 9 11 -y -1 1 -m 0 -S 1 -X l -Y ldot

you will obtain a real-time plot.  The -m 0 option requests that successive data points not be joined by line segments, and the -S 1 option requests that plotting symbol #1 (a dot) be plotted at the location of each point.  As you will see if you run this command, the heavy mass does not win against the lighter mass.  Instead the machine oscillates non-periodically.  Since the motion is non-periodic, the plot benefits from being drawn as a sequence of unconnected points.

We conclude by mentioning a few features of ode that may be useful when things are not going quite right.  One of them is the examine statement.  It may be used to discover pertinent information about any variable in a system.  For details, see Input Language.

Another useful feature is that the print statement may be used to print out more than just the value of a variable.  As we have seen, if the name of the variable is followed by ', the derivative of the variable will be printed instead.  In a similar way, following the variable name with ?, !, or ~ prints respectively the relative single-step error, the absolute single-step error, or the accumulated error (not currently implemented).  These quantities are discussed in Numerical Error.

The print statement may be more complicated than was shown in the preceding examples.  Its general structure is

     print <pr-list> [every <const>] [from <const>]

The bracket notation [...] means that the enclosed statements are optional.  Until now we have not mentioned the every clause or the from clause.  The <pr-list> is familiar, however; it is simply a comma-separated list of variables.  For example, in the statement

     print t, y, y' every 5 from 1

the <pr-list> is <t, y, y'>.  The clauses every 5 and from 1 specify that printing should take place after every fifth step, and that the printing should begin when the independent variable t reaches 1.  An every clause is useful if you wish to `thin out' the output generated by a step statement, and a from clause is useful if you wish to view only the final portion of a solution curve.

ode command-line options
========================

The command-line options to ode are listed below.  There are several sorts of option:

 1. Options affecting the way in which input is read.

 2. Options affecting the format of the output.

 3. Options affecting the choice of numerical solution scheme, and the error bounds that will be imposed on it.

 4. Options that request information.

The following option affects the way input is read.

-f FILENAME
--input-file FILENAME
     Read input from FILENAME before reading from standard input.

The following options affect the output format.

-p PRECISION
--precision PRECISION
     When printing numerical results, use PRECISION significant figures.  If this option is given, all output will be in scientific notation.

-t
--title
     Print a title line at the head of the output, naming the columns.  If this option is given, the default print format will be scientific notation.

The following options specify the numerical integration scheme.  Only one of the three basic option -R, -A, and -E may be specified.  The default is -R (Runge--Kutta--Fehlberg).

-R [STEPSIZE]
--runge-kutta [STEPSIZE]
     Use a fifth-order Runge--Kutta--Fehlberg algorithm, with an adaptive stepsize unless a constant stepsize is specified.  When a constant stepsize is specified and no error analysis is requested, then a classical fourth-order Runge--Kutta scheme is used.

-A [STEPSIZE]
--adams-moulton [STEPSIZE]
     Use a fourth-order Adams--Moulton predictor--corrector scheme, with an adaptive stepsize unless a constant stepsize, STEPSIZE, is specified.  The Runge--Kutta--Fehlberg algorithm is used to get past `bad' points (if any).

-E [STEPSIZE]
--euler [STEPSIZE]
     Use a `quick and dirty' Euler scheme, with a constant stepsize.  The default value of STEPSIZE is 0.1.  Not recommended for serious applications.

-h HMIN [HMAX]
--step-size-bound HMIN [HMAX]
     Use a lower bound HMIN on the stepsize.  The numerical scheme will not let the stepsize go below HMIN.  The default is to allow the stepsize to shrink to the machine limit, i.e., the minimum nonzero double-precision floating point number.  The optional argument HMAX, if included, specifies a maximum value for the stepsize. It is useful in preventing the numerical routine from skipping quickly over an interesting region.

The following options set the error bounds on the numerical solution scheme.

-r RMAX [RMIN]
--relative-error-bound RMAX [RMIN]

-e EMAX [EMIN]
--absolute-error-bound EMAX [EMIN]
     The -r option sets an upper bound on the relative single-step error.  If the -r option is used, the relative single-step error in any dependent variable will never exceed RMAX (the default for which is 10^(-9)).  If this should occur, the solution will be abandoned and an error message will be printed.  If the stepsize is not constant, the stepsize will be decreased `adaptively', so that the upper bound on the single-step error is not violated.  Thus, choosing a smaller upper bound on the single-step error will cause smaller stepsizes to be chosen.  A lower bound RMIN may optionally be specified, to suggest when the stepsize should be increased (the default for RMIN is RMAX/1000).  The -e option is similar to -r, but bounds the absolute rather than the relative single-step error.

-s
--suppress-error-bound
     Suppress the ceiling on single-step error, allowing ode to continue even if this ceiling is exceeded.  This may result in large numerical errors.

Finally, the following options request information.

--help
     Print a list of command-line options, and then exit.

--version
     Print the version number of ode and the plotting utilities package, and exit.

Diagnostic messages
===================

ode is always in one of two states:

  * Reading input.  The input includes a specification of a system of ordinary differential equations, together with instructions for solving it numerically: a print line and a step line.

  * Numerically solving a system, and printing the resulting output.

ode moves from the first to the second state after it sees and processes a step line.  It returns to the first state after the generated output has been printed.  Errors may occur in either the `reading' state or the `solving' state, and may terminate computations or even cause ode to exit.  We now explain the possible sorts of error.

While reading input, ode may encounter a syntax error: an ungrammatical line that it is unable to parse.  (For a summary of its input grammar, see Input Language.)  If so, it emits the error message

     ode::nnn: syntax error

where nnn is the number of the line containing the error.  When the -f filename option is used to specify an input file, the error message will read

     ode:filename:nnn: syntax error

for errors encountered inside the input file.  Subsequently, when ode begins reading the standard input, line numbers will start over again from 1.

No effort is made to recover from syntax errors in the input.  However, there is a meager effort to resynchronize, so that more than one syntax error in a file may be found at the same time.

It is also possible that a fatal arithmetic exception (such as a division by zero, or a floating point overflow) may occur while ode is reading input.  If such an exception occurs, ode will print an ``Floating point exception'' error message and exit. Arithmetic exceptions are machine-dependent.  On some machines, the line

     y = 1/0

would induce an arithmetic exception.  Also on some machines (not necessarily the same ones), the lines

     y = 1e100
     z = y^4

would induce an arithmetic exception.  That is because on most machines, the double precision quantities that ode uses internally are limited to a maximum size of approximately 1.8x10^308.

When ode is in the `solving' state, i.e., computing a numerical solution, similar arithmetic exceptions may occur.  If so, the solution will be interrupted and a message resembling

     ode: arithmetic exception while calculating y'

will be printed.  However, ode will not exit; the exception will be `caught'.  ode itself recognizes the following exceptional conditions: square root of a negative number, logarithm of a non-positive number, and negative number raised to a non-integer power. ode will catch any of these operations before it is performed, and print an error message specifying which illegal operation it has encountered.

     ode: square root of a negative number while calculating y'

would be a typical error message.

If the machine on which ode is running supports the matherr facility for reporting errors in the computation of standard mathematical functions, it will be used.  This facility reports domain errors and range errors (overflows, underflows, and losses of significance) that could occur when evaluating such functions as log, gamma, etc.; again, before they are performed.  If the matherr facility is present, the error message will be fairly informative.  For example, the error message

     ode: range error (overflow) in lgamma while calculating y'

could be generated if the logarithmic gamma function lgamma is evaluated at a value of its argument that is too large.  The generation of any such message, except a message warning of an underflow, will cause the numerical solution to be interrupted.

There is another sort of error that may occur during numerical solution: the condition that an error ceiling, which may be set by the user with the -r option or the -e option, is exceeded.  This too will cause the numerical solution to be abandoned, and ode to switch back to reading input.

Numerical error and how to avoid it
===================================

This discussion is necessarily incomplete.  Entire books exist on any subject mentioned below (e.g., floating point error).  Our goals are modest: first, to introduce the basic notions of error analysis as they apply to ode; second, to steer you around the more obvious pitfalls.  You should look through a numerical analysis text (e.g., Atkinson's Introduction to Numerical Analysis) before beginning this discussion.

We begin with some key definitions.  The error of greatest concern is the difference between the actual solution and the numerical approximation to the solution; this is termed the accumulated error, since the error is built up during each numerical step. Unfortunately, an estimate of this error is usually not available without knowledge of the actual solution.  There are, however, several more usable notions of error.  The single-step error, in particular, is the difference between the actual solution and the numerical approximation to the solution after any single step, assuming the value at the beginning of the step is correct.

The relative single-step error is the single-step error, divided by the current value of the numerical approximation to the solution. Why not divided by the current value of the solution itself?  The reason is that the solution is not exactly known.  When free to choose a stepsize, ode will do so on the basis of the relative single-step error.  By default, it will choose the stepsize so as to maintain an accuracy of eight significant digits in each step.  That is, it will choose the stepsize so as not to violate an upper bound of 10^(-9) on the relative single-step error.  This ceiling may be adjusted with the -r option.

Where does numerical error come from?  There are two sources.  The first is the finite precision of machine computation.  All computers work with floating point numbers, which are not real numbers, but only an approximation to real numbers.  However, all computations performed by ode are done to double precision, so floating point error tends to be relatively small.  You may nonetheless detect the difference between real numbers and floating point numbers by experimenting with the -p 17 option, which will print seventeen significant digits. On most machines, that is the precision of a double precision floating point number.

The second source of numerical error is often called the theoretical truncation error.  It is the difference between the actual solution and the approximate solution due solely to the numerical scheme.  At the root of many numerical schemes is an infinite series; for ordinary differential equations, it is a Taylor expansion. Since the computer cannot compute all the terms in an infinite series, a numerical scheme necessarily uses a truncated series; hence the term.  The single-step error is the sum of the theoretical truncation error and the floating point error, though in practice the floating point error is seldom included.  The single-step error estimated by ode consists only of the theoretical truncation error.

We say that a numerical scheme is stable, when applied to a particular initial value problem, if the error accumulated during the solution of the problem over a fixed interval decreases as the stepsize decreases; at least, over a wide range of step sizes.  With this definition both the Runge--Kutta--Fehlberg (-R) scheme and the Adams--Moulton (-A) scheme are stable (a statement based more on experience than on theoretical results) for a wide class of problems.

After these introductory remarks, we list some common sources of accumulated error and instability in any numerical scheme.  Usually, problems with large accumulated error and instability are due to the single-step error in the vicinity of a `bad' point being large.

 1. Singularities.

     ode should not be used to generate a numerical solution on any interval containing a singularity.  That is, ode should not be asked to step over points at which the system of differential equations is singular or undefined.

     You will find the definitions of singular point, regular singular point, and irregular singular point in any good differential equations text. If you have no favorite, try Birkhoff and Rota's Ordinary Differential Equations, Chapter 9.  Always locate and classify the singularities of a system, if any, before applying ode.

 2. Ill-posed problems.

     For ode to yield an accurate numerical solution on an interval, the true solution must be defined and well-behaved on that interval. The solution must also be real.  Whenever any of these conditions is violated, the problem is said to be ill-posed.  Ill-posedness may occur even if the system of differential equations is well-behaved on the interval.  Strange results, e.g., the stepsize suddenly shrinking to the machine limit or the solution suddenly blowing up, may indicate ill-posedness.

     As an example of ill-posedness (in fact, an undefined solution) consider the innocent-looking problem:

          y' = y^2
          y(1) = -1

     The solution on the domain t > 0 is

          y(t) = -1/t.

     With this problem you must not compute a numerical solution on any interval that includes t=0.  To convince yourself of this, try to use the step statement

          step 1, -1

     on this system.  How does ode react?

     As another example of ill-posedness, consider the system

          y'=1/y

     which is undefined at y=0.  The general solution is

          y = +/- (2(t-C))^(1/2),

     so that if the condition y(2)=2 is imposed, the solution will be (2t)^(1/2).  Clearly, if the domain specified in a step statement includes negative values of t, the generated solution will be bogus.

     In general, when using a constant stepsize you should be careful not to `step over' bad points or bad regions.  When allowed to choose a stepsize adaptively, ode will often spot bad points, but not always.

 3. Critical points.

     An autonomous system is one that does not include the independent variable explicitly on the right-hand side of any differential equation. A critical point for such a system is a point at which all right-hand sides equal zero.  For example, the system

          y' = 2x
          x' = 2y

     has only one critical point, at (x,y) = (0,0).

     A critical point is sometimes referred to as a stagnation point. That is because a system at a critical point will remain there forever, though a system near a critical point may undergo more violent motion. Under some circumstances, passing near a critical point may give rise to a large accumulated error.

     As an exercise, solve the system above using ode, with the initial condition x(0) = y(0) = 0.  The solution should be constant in time.  Now do the same with points near the critical point. What happens?

     You should always locate the critical points of a system before attempting a solution with ode.  Critical points may be classified (as equilibrium, vortex, unstable, stable, etc.) and this classification may be of use.  To find out more about this, consult any book dealing with the qualitative theory of differential equations (e.g., Birkhoff and Rota's Ordinary Differential Equations, Chapter 6).

 4. Unsuitable numerical schemes

     If the results produced by ode are bad in the sense that instability appears to be present, or an unusually small stepsize needs to be chosen needed in order to reduce the single-step error to manageable levels, it may simply be that the numerical scheme being used is not suited to the problem.  For example, ode currently has no numerical scheme which handles so-called `stiff' problems very well.

     As an example, you may wish to examine the stiff problem:

          y' = -100 + 100t + 1
          y(0)=1

     on the domain [0,1].  The exact solution is

          y(t) = e^(-100t) + t.

     It is a useful exercise to solve this problem with ode using various numerical schemes, stepsizes, and relative single-step error bounds, and compare the generated solution curves with the actual solution.

There are several rough and ready heuristic checks you can perform on the accuracy of any numerical solution produced by ode.  We discuss them in turn.

 1. Examine the stability of  solution curves: do they converge?

     That is, check how changing the stepsize affects a solution curve.  As the stepsize decreases, the curve should converge.  If it does not, then either the stepsize is not small enough or the numerical scheme is not suited to the problem.  In practice, you would proceed as follows.

       * If using an adaptive stepsize, superimpose the solution curves for successively smaller bounds on the relative single-step error (obtained with, e.g., -r 1e-9, -r 1e-11, -r 1e-13, ...). If the curves converge then the solution is to all appearances stable, and your accuracy is sufficient.

       * If employing a constant stepsize, perform a similar analysis by successively halving the stepsize.

     The following example is one that you may wish to experiment with.  Make a file named qcd containing:

          # an equation arising in QCD (quantum chromodynamics)
          f'   = fp
          fp'  = -f*g^2
          g'   = gp
          gp'  = g*f^2
          f = 0; fp = -1; g = 1; gp = -1

          print t, f
          step 0, 5

     Next make a file named stability, containing the lines:

          : sserr is the bound on the relative single-step error
          for sserr
          do
          ode -r $sserr < qcd
          done | spline -n 500 | graph -T X -C

     This is a `shell script', which when run will superimpose numerical solutions with specified bounds on the relative single-step error.  To run it, type:

          sh stability 1 .1 .01 .001

     and a plot of the solutions with the specified error bounds will be drawn.  The convergence, showing stability, should be quite illuminating.

 2. Check invariants of the system: are they constant?

     Many systems have invariant quantities.  For example, if the system is a mathematical model of a `conservative' physical system then the `energy' (a particular function of the dependent variables of the system) should be constant in time.  In general, knowledge about the qualitative behavior of any dependent variable may be used to check the quality of the solution.

 3. Check a family of solution curves: do they diverge?

     A rough idea of how error is propagated is obtained by viewing a family of solution curves about the numerical solution in question, obtained by varying the initial conditions.  If they diverge sharply---that is, if two solutions which start out very close nonetheless end up far apart---then the quality of the numerical solution is dubious.  On the other hand, if the curves do not diverge sharply then any error that is present will in all likelihood not increase by more than an order of magnitude or so over the interval.  Problems exhibiting no sharp divergence of neighboring solution curves are sometimes called well-conditioned.

Running time
============

The time required for ode to solve numerically a system of ordinary differential equations depends on a great many factors.  A few of them are: number of equations, complexity of equations (number of operators and nature of the operators), and number of steps taken (a very complicated function of the difficulty of solution, unless constant stepsizes are used).  The most effective way to gauge the time required for solution of a system is to clock a short or imprecise run of the problem, and reason as follows: the time required to take two steps is roughly twice that required for one; and there is a relationship between the number of steps required and the relative error ceiling chosen.  That relationship depends on the numerical scheme being used, the difficulty of solution, and perhaps on the magnitude of the error ceiling itself.  A few carefully planned short runs may be used to determine this relationship, enabling a long but imprecise run to be used as an aid in projecting the cost of a more precise run over the same region.  Lastly, if a great deal of data is printed, it is likely that more time is spent in printing the results than in computing the numerical solution.

The ode input language formally specified
=========================================

The following is a formal specification of the grammar for ode's input language, in Backus--Naur form.  Nonterminal symbols in the grammar are enclosed in angle brackets.  Terminal tokens are in all capitals.  Bare words and symbols stand for themselves.

     <program>    ::=        ... empty ...
                    |  <program> <statement>

     <statement>  ::=  SEP
                    |  IDENTIFIER = <const> SEP
                    |  IDENTIFIER ' = <expression> SEP
                    |  print <printlist> <optevery> <optfrom> SEP
                    |  step <const> , <const> , <const> SEP
                    |  step <const> , <const> SEP
                    |  examine IDENTIFIER SEP

     <printlist>  ::=  <printitem>
                    |  <printlist> , <printitem>

     <printitem>  ::=  IDENTIFIER
                    |  IDENTIFIER '
                    |  IDENTIFIER ?
                    |  IDENTIFIER !
                    |  IDENTIFIER ~

     <optevery>   ::=        ... empty ...
                    |  every <const>

     <optfrom>    ::=        ... empty ...
                    |  from <const>

     <const>      ::=  <expression>

     <expression> ::=  ( <expression> )
                    |  <expression> + <expression>
                    |  <expression> - <expression>
                    |  <expression> * <expression>
                    |  <expression> / <expression>
                    |  <expression> ^ <expression>
                    |  FUNCTION ( <expression> )
                    |  - <expression>
                    |  NUMBER
                    |  IDENTIFIER

Since this grammar is ambiguous, the following table summarizes the precedences and associativities of operators within expressions. Precedences decrease from top to bottom.

     Class           Operators    Associativity

     Exponential         ^            right
     Multiplicative      * /          left
     Additive            + -          left

As noted in the grammar, there are six types of nontrivial statement. We now explain the effects (the `semantics') of each type, in turn.

 1. IDENTIFIER ' = <expression>

     This defines a first-order differential equation. The derivative of IDENTIFIER is specified by <expression>.  If a dynamic variable does not appear on the left side of a statement of this form, its derivative is assumed to be zero.  That is, it is a symbolic constant.

 2. IDENTIFIER = <const>

     This sets the value of IDENTIFIER to the current value of <expression>.  Dynamic variables that have not been initialized in this way are set to zero.

 3. step <const> , <const>

 4. step <const> , <const> , <const>

     A step statement causes the numerical scheme to be executed.  The first <const> is the initial value of the independent variable.  The second is its final value.  The third is a stepsize; if given, it overrides any stepsize that may be specified on the command line. Usually the stepsize is not specified, and it varies adaptively as the computation proceeds.

 5. print <printlist> [ every <const> ] [ from <const> ]

     A print statement controls the content and frequency of the numerical output.  <printlist> is a comma-separated list of IDENTIFIERs, where each IDENTIFIER may be followed by ', denoting the derivative, or ?, denoting the relative single-step error, or !, denoting the absolute single-step error, or ~, denoting the accumulated error (not currently implemented). The specified values are printed in the order they are found.  Both the every clause and the from clause are optional.  If the every clause is present, a printing occurs every <const> iterations of the numerical algorithm.  The default is to print on every iteration (i.e. every 1).  The first and last values are always printed.  If the from clause is present, it means to begin printing when the independent variable reaches or exceeds <const>. The default is to begin printing immediately.

     If no print statement has been supplied, then the independent variable and all dependent variables which have differential equations associated with them are printed.  The independent variable is printed first; the dependent variables follow in the order their equations were given.

 6. examine IDENTIFIER

     An examine statement, when executed, causes a table of interesting information about the named variable to be printed on the standard output.  For example, if the statement examine y were encountered after execution of the `ode to Euler' example discussed elsewhere, the output would be:

          "y" is a dynamic variable
          value:2.718282
          prime:2.718282
          sserr:1.121662e-09
          aberr:3.245638e-09
          acerr:0
           code:	push "y"

     The phrase `dynamic variable' means that there is a differential equation describing the behavior of y.  The numeric fields in the table are:

     value
          Current value of the variable.

     prime
          Current derivative of the variable.

     sserr
          Relative single-step error for the last step taken.

     aberr
          Absolute single-step error for the last step taken.

     acerr
          Total error accumulated during the most recent step statement. Not currently implemented.

     The code section of the table lists the stack operations required to compute the derivative of y (somewhat reminiscent of a reverse Polish calculator).  This information may be useful in discovering whether the precedences in the differential equation statement were interpreted correctly, or in determining the time or space expense of a particular calculation.  push "y" means to load y's value on the stack, which is all that is required to compute its derivative in this case.

The grammar for the ode input language contains four types of terminal token: FUNCTION, IDENTIFIER, NUMBER, and SEP.  They have the following meanings.

 1. FUNCTION

     One of the words: abs, sqrt, exp, log, ln, log10, sin, cos, tan, asin, acos, atan, sinh, cosh, tanh, asinh, acosh, atanh, floor, ceil, besj0, besj1, besy0, besy1, erf, erfc, inverf, lgamma, gamma, norm, invnorm, ibeta, igamma.  These are defined to have the same meaning as in the plotting program gnuplot.  All functions take a single argument, except for ibeta, which takes three, and igamma, which takes two.  For trigonometric functions, all arguments are expressed in radians.  The atan function is defined to give a value between -PI/2 and PI/2 (inclusive).

 2. IDENTIFIER

     A sequence of alphanumeric characters starting with an alphabetic character.  The first 32 characters are significant.  Upper and lower-case letters are distinct.  In identifiers, the underscore character is considered alphabetic.  Function names and keywords may not be used as identifiers, nor may PI.

 3. NUMBER

     A non-empty sequence of digits possibly containing a decimal point and possibly followed by an exponent.  An exponent is e or E, followed by an (optionally signed) one, two, or three-digit number.  All numbers and all parts of numbers are radix 10.  A number may not contain any white space.  The special word PI is a number.

 4. SEP

     A separator: a semicolon or a (non-escaped) newline.

In the ode input language, upper and lower-case letters are distinct.  Comments begin with the character # and continue to the end of the line.  Long lines may be continued onto a second line by ending the first line with a backslash (\).  That is because the combination backslash-newline is equivalent to a space.

Spaces or tabs are required in the input whenever they are needed to separate identifiers, numbers, and keywords from one another.  Except as separators, they are ignored.

Bibliography on ode and solving differential equations
======================================================

  K. E. Atkinson, An Introduction to Numerical Analysis, Wiley, 1978.  Chapter 6 contains a discussion of the literature on the numerical solution of ordinary differential equations.

  G. Birkhoff and G. Rota, Ordinary Differential Equations, 4th ed., Wiley, 1989.

  N. B. Tufillaro, T. Abbott, and J. Reilly, An Experimental Approach to Nonlinear Dynamics and Chaos, Addison--Wesley, 1992. Appendix C discusses an earlier version of ode.

  N. B. Tufillaro, E. F. Redish, and J. S. Risley, ``ode: A numerical simulation of ordinary differential equations,'' pp. 480--481 in Proceedings of the Conference on Computers in Physics Instruction, Addison--Wesley, 1990.

libplot, a Function Library
***************************

libplot is a library of functions for device-independent two-dimensional vector graphics.  The graphical objects which it can draw include paths, circles and ellipses, points, markers, and `adjusted labels' (justified text strings).  A path is a sequence of line segments, circular arcs, and/or elliptic arcs, which may be open or closed.  User-specified filling of paths, circles, and ellipses is supported (fill color, as well as pen color, may be specified). There is support for maintaining a Postscript-style stack of graphics contexts, i.e., a stack of drawing attribute sets.  User-specifiable attributes other than pen color and fill color include path-related attributes such as line type and line width, and text-related attributes such as font name, font size, and text angle.

The fundamental abstraction provided by libplot is that of a Plotter.  A Plotter is an object with an interface for the drawing of vector graphics which is similar to the interface provided by a traditional pen plotter.  There are several types of Plotter, which differ in the display device they produce output for.  Any number of Plotters, of the same or different types, may exist simultaneously in an application.

The drawing operations supported by Plotters of different types are identical, in agreement with the principle of device independence.  So a graphics application that is linked with libplot may easily be written so as to produce output for any or all of the supported display devices.

The following are the currently supported types of Plotter.

  * X Plotters.  An X Plotter, when opened, pops up a window on an X Window System display and draws graphics in it.  The window will be `spun off' when the Plotter is closed; if it is subsequently reopened, a new window will be popped up.  A spun-off window will remain on the screen but will vanish if you type q or click your mouse in it.  Future releases may permit X Plotters, when reopened, to reuse an existing window.

  * X Drawable Plotters.  An X Drawable Plotter draws graphics in one or two specified drawables associated with an X Window System display. A `drawable' is either a window or a pixmap.  The drawables must be passed to the Plotter as parameters.  (see Driver Parameters.)

  * Postscript Plotters.  A Postscript Plotter produces Postscript output and directs it to a file or other specified output stream.  The output is actually in EPS (encapsulated Postscript) format, so it may be included in another document.  It may also be edited with the idraw drawing editor.

  * Fig Plotters.  A Fig Plotter produces output in Fig format and directs it to a file or other specified output stream.  The output may be edited with the xfig drawing editor.  The xfig editor will export drawings in various other formats for inclusion in documents.

  * HP-GL Plotters.  An HP-GL Plotter produces output in the Hewlett--Packard Graphics Language (HP-GL or HP-GL/2), and directs it to a file or other specified output stream.  The output may be sent to a Hewlett--Packard LaserJet printer or plotter, or included in another document.

  * Tektronix Plotters.  A Tektronix Plotter produces output in Tektronix 4014 format and directs it to a file or other specified output stream. The output may be displayed on any Tektronix 4014 emulator.  Such an emulator is built into xterm, the X Window System terminal emulation program.  The DOS version of kermit also includes such an emulator.

  * Metafile Plotters.  A Metafile Plotter produces output in GNU metafile format and directs it to a file or other specified output stream.  This format is an extended version of the `plot(5)' format found on some other operating systems.  (see Metafiles.)  It may be translated to other formats by an invocation of GNU plot.  (see plot.)

A distinction among these types of Plotter is that all except X and X Drawable Plotters write graphics to a file or other output stream.  An X Plotter pops up its own windows, and an X Drawable Plotter manipulates one or two X drawables.

Another distinction is that X, X Drawable, Tektronix and Metafile Plotters are real-time.  This means that they draw graphics or write to an output stream as the drawing operations are invoked on them. Postscript, Fig and HP-GL Plotters are not real-time, since their output streams can only be emitted after all functions have been called.  For a Postscript Plotter this is because a `bounding box' line must be placed at the head of the output file.  For a Fig Plotter it is because color definitions must be placed at the head of the output file.

The most important operations supported by any Plotter are openpl and closepl, which open and close it.  Graphics may be drawn, and drawing attributes set, only within an openpl...closepl pair.  In principle, any Plotter may be opened and closed arbitrarily many times.  The graphics produced by each openpl...closepl pair constitute a `page'.  An X Plotter displays each page in a separate X window, and an HP-GL Plotter renders each page as a separate physical page.  X Drawable Plotters and Tektronix Plotters manipulate a single drawable or display, on which pages are displayed in succession.

There is a minor problem with extending these semantics to Postscript and Fig Plotters.  The closepl operation ensures that all graphical objects that have been drawn are written to the output.  But output files in Postscript and Fig format may not be concatenated.  For this reason, all Plotters support an additional operation: outfile.  The output stream for a Plotter, if it has one, may be altered by invoking outfile on it.  outfile may only be invoked outside an openpl...closepl pair.  By using outfile, a programmer may produce multipage graphics output from Postscript and Fig Plotters.  Its use in other contexts is deprecated.

There are several other basic operations which any Plotter supports. The `graphics display' drawn in by a Plotter is a square or rectangular region on a display device.  But when using any Plotter to draw graphics, an application must specify the coordinates of graphical objects in a device-independent `user frame', rather than in device coordinates.  A Plotter relates the user frame to the device frame by performing a user-specified affine coordinate transformation.

Immediately after invoking openpl to open a Plotter, an application should invoke the space operation to initialize this affine transformation from the user frame to the device frame.  This invocation determines the rectangular region (in user coordinates) that will be mapped by the Plotter to the graphics display.  The affine transformation may be updated at any later time, if desired, by invoking fconcat.  The fconcat operation will `concatenate' (i.e., compose) the current affine transformation transformation with any specified affine map.  This sort of concatenation is a capability familiar from, e.g., Postscript.

Any Plotter maintains a Postscript-style stack of graphics contexts. A graphics context includes such modal drawing attributes as graphics cursor position, line mode, line width, pen and fill colors, and the font used for drawing text.  It also includes the current affine map from the user frame to the device frame.  The state of any uncompleted path (if any) is included as well, since paths may be drawn incrementally, one segment (line segment or arc) at a time. The current graphics context may be pushed onto the stack of graphics contexts by calling savestate, and popped off by calling restorestate.

C Programming with libplot
==========================

If you are writing an application in C that will use libplot to draw graphics, you need to know how to create and select Plotters.

The newpl function will create a Plotter of specified type.  Its first argument may be "X", "Xdrawable", "ps", "fig", "hpgl", "tek", or "meta".  It returns an integer (a ``handle'') that may be used to refer to the Plotter.  Before using a Plotter that you have created (i.e., before invoking any of the libplot operations on it), you must select the Plotter by calling selectpl.  Only one Plotter may be selected at a time, but by calling selectpl you may switch from Plotter to Plotter at any time, even when the selected Plotter is open.  A Plotter that is not currently selected may be deleted, and its storage freed, by calling deletepl.

Strictly speaking, you do not need to call newpl, selectpl, or deletepl in order to draw graphics.  That is because at startup, a single Metafile Plotter that writes to standard output (with handle `0') is automatically created and selected.  The presence of this default Plotter is for compatibility with pre-GNU versions of libplot.  Of course, you may not wish to obtain output in metafile format, and you may not wish to write to standard output.

The source code for a graphics application written in C, if it is to use libplot, should contain the lines

     #include <stdio.h>
     #include <plot.h>

The header file plot.h is distributed with libplot, and should have been installed on your system where your C compiler will find it.  It contains prototypes for each of the functions in libplot and some miscellaneous definitions.  It may be used with C++ programs as well as C programs.

To link your application with libplot, you would use the appropriate -l option(s) on the command line when compiling it. You would use

     -lplot -lXaw -lXmu -lXt -lXext -lX11 -lm

(or perhaps -lplot -lXm -lXt -lXext -lX11 -lm, -lplot -lXm -lXt -lXext -lX11 -lm -lc -lgen, or -lplot -lXm -lXt -lXext -lX11 -lm -lc -lPW, on systems that provide Motif widgets instead of Athena widgets).  Note that on most systems libplot is installed as a DLL (dynamically linked library, or `shared' library).  This means that the linking with your application will take place at run time rather than compile time.  The environment variable LD_LIBRARY_PATH lists the directories which will be searched for DLL's at run time.  For your application to be executable, this environment variable should include the directory in which libplot is stored.

The following is a sample application that uses libplot.  It draws an intricate and beautiful path (Bill Gosper's ``C'' curve, discussed as Item #135 in HAKMEM, MIT Artificial Intelligence Laboratory Memo #239, 1972).  As the numeric constant MAXORDER (here equal to 10) is increased, the path will take on the shape of a curly letter ``C'', which is the envelope of a myriad of epicyclic octagons.

     #include <stdio.h>
     #include <plot.h>

     #define MAXORDER 10
     void draw_c_curve (double dx, double dy, int order)
     {
       if (order >= MAXORDER)
         fcontrel (dx, dy);        /* continue path along (dx, dy) */

       else
         {
           draw_c_curve (0.5 * (dx - dy), 0.5 * (dx + dy), order + 1);
           draw_c_curve (0.5 * (dx + dy), 0.5 * (dy - dx), order + 1);
         }
     }

     int main ()
     {
       int handle;

       {
       /* create a Postscript Plotter that writes to standard output */
       handle = newpl ("ps", stdin, stdout, stderr);
       selectpl (handle);             /* select the Plotter */
       }

       if (openpl () < 0)           /* open Plotter */
         {
           fprintf (stderr, "Couldn't open Plotter\n");
           return 1;
         }
       fspace (0.0, 0.0, 1000.0, 1000.0);  /* choose coors for user frame */
       flinewidth (0.25);          /* width of lines in user frame */
       pencolorname ("red");       /* path will be drawn in red */

       erase ();                   /* erase Plotter's graphics display */
       fmove (600.0, 300.0);       /* position the graphics cursor */
       draw_c_curve (0.0, 400.0, 0);

       /* close plotter, i.e., write output */
       if (closepl () < 0)
         {
           fprintf (stderr, "Couldn't close Plotter\n");
           return 1;
         }
       selectpl (0);               /* select default Plotter */
       deletepl (handle);          /* clean up by deleting Plotter we used */
       return 0;
     }

As you can see, this application begins by calling the newpl function to create a Postscript Plotter.  The three arguments stdin, stdout, stderr require a bit of explanation. Currently, Plotters are write-only: they are not interactive, so they do not read from an input stream.  So the second argument to newpl is a dummy.  If non-NULL, the third and fourth arguments must be an output stream and an error stream, both of which are opened for writing. This is the case for Plotters other than X Plotters, at least. The graphical objects that are drawn between any openpl...closepl pair will be written to the output stream, and error messages (if any) will be written to the error stream, provided that it is non-NULL.  All plotters other than X Plotters and X Drawable Plotters use an output stream to draw graphics.

The application draws the ``C'' curve recursively, and (since a Postscript Plotter is selected) writes a Postscript file to standard output when closepl is called.  The drawing of the curve is accomplished by invoking fmove on the Plotter to position the graphics cursor, and then repeatedly invoking fcontrel.  The fcontrel operation continues a path by adding a line segment to it.  The endpoint of each line segment is specified in relative coordinates, as an offset in the user frame.

Specifying "fig", "hpgl", "tek", or "meta" as the first argument in the call to newpl, instead of "ps", will cause output to be written to the output stream in the specified format, instead of Postscript. If "X" is specified as the first argument of newpl, the curve will be drawn in a popped-up X window, and the output stream argument will be ignored.  Which X Window System display the window pops up on is determined by the DISPLAY driver parameter (Driver Parameters), or if that parameter has not been set, by the DISPLAY environment variable.

Specifying "meta" as the Plotter type may be useful if you wish to avoid recompilation for different output devices.  Metafile output may be piped to the plot utility and converted to any other supported output format, or displayed in an X window.  See plot.

If you specify "Xdrawable" as the Plotter type, you will need to create at least one X drawable (i.e., window or a pixmap), and by invoking the parampl function before newpl is called, pass it to libplot as a driver parameter.  For a list of supported driver parameters, Driver Parameters.

The functions in libplot: A detailed listing
============================================

The functions in GNU libplot include the three Plotter manipulation functions discussed in the previous section (newpl, selectpl, and deletepl), which are specific to the C binding.  The also include 80 basic functions: parampl, a function that sets low-level options for subsequently created Plotters (Driver Parameters), and 79 functions that operate on the currently selected Plotter.

These 80 functions are divided into the four sets tabulated below.

Many functions come in two versions: integer and double precision floating point.  Internally, libplot uses double precision floating point.  The integer versions are provided for backward compatibility.  If there are two versions of a function, the name of the floating point version begins with the letter f.

Many functions come in both absolute and relative versions, also.  The latter use relative coordinates (i.e., coordinates relative to the current position of the graphics cursor), and their names end in rel.

Currently, only a few functions have meaningful return values.

Setup functions
---------------

The following are libplot's ``setup functions,'' which initialize, open, or close a Plotter.  They are listed in the approximate order in which they would be called.

int parampl (const char *PARAMETER, void *VALUE);
     parampl sets the value of the libplot parameter PARAMETER to VALUE.  Parameters are used for setting low-level device driver options.  The parameter values in effect at the time any Plotter is created are copied into it.  The most important parameters are DISPLAY, which specifies the X Window System display that an X Plotter will use, and PAGESIZE, which affects Postscript, Fig, and HP-GL Plotters.

     For most parameters, the value should be a char *, i.e., a string.  See Driver Parameters.

int openpl ();
     openpl opens a Plotter.  Depending on the type of the Plotter, it may write initialization commands to an output stream.  A negative return value indicates the Plotter could not be opened.

     An X Plotter, which has no output stream, pops up a window on its X Window System display instead.  Currently, a new window is popped up with each invocation of openpl.  Future releases may support window re-use.

int erase ();
     erase clears all previously plotted objects from the graphics display.  This is useful for Plotters that are persistent, in the sense that objects drawn within an openpl...closepl pair are still visible and are liable to be overwritten when openpl is next invoked.  For such Plotters, you may wish to invoke erase immediately after openpl.  Currently, only X Drawable Plotters and Tektronix Plotters are persistent.  Future releases may support persistence for X Plotters also.

int space (int X0, int Y0, int X1, int Y1);
int fspace (double X0, double Y0, double X1, double Y1);
     space and fspace take two pairs of arguments, specifying the positions of the lower left corner and upper right corner of the graphics display, in user coordinates.  In other words, calling space or fspace sets the affine transformation from user coordinates to device coordinates.

int space2 (int X0, int Y0, int X1, int Y1, int X2, int Y2);
int fspace2 (double X0, double Y0, double X1, double Y1, double X2, double Y2);
     space2 and fspace2 are extended versions of space and fspace.  Their arguments are the three defining vertices of an `affine window' (a drawing parallelogram), in user coordinates.  The specified vertices are the lower left, the lower right, and the upper left.  This window will be mapped affinely onto the graphics display.

int havecap (const char *S);
     havecap tests whether or not a Plotter has a specified capability. The return value is 0, 1, or 2, signifying no/yes/maybe.  For unrecognized capabilities the return value is zero.  Capabilities include "SOLID_FILL" and "WIDE_LINES" (i.e., lines with a non-default width).  They also include "HERSHEY_FONTS", "PS_FONTS", and "PCL_FONTS", which indicate whether or not fonts of a particular class are supported. See Text Fonts.

int flushpl ();
     flushpl flushes (i.e., pushes onward) all plotting commands to the display device.  This is useful only if the currently selected Plotter does real-time plotting, since it may be used to ensure that all previously plotted objects have been sent to the display and are visible to the user.  It has no effect on Plotters that do not do real-time plotting.

int closepl ();
     closepl closes a Plotter.  If the currently selected Plotter does not do real-time plotting (i.e., if it is a Postscript, Fig, or HP-GL Plotter), it writes the plotted objects to the output stream.  A negative return value indicates the Plotter could not be closed.

FILE *outfile (FILE *FP);
     outfile, which must be called outside a openpl...closepl pair, redirects all graphics output from a Plotter to the stream FP.  The previous output stream is returned.

     This operation is useful on Plotters that may not meaningfully be opened more than once, i.e., Postscript and Fig Plotters.  On other Plotters, its use is deprecated.  On Plotters that do not have an output stream in the conventional sense, i.e., X Plotters and X Drawable Plotters, it has no effect.

Object-drawing functions
------------------------

The following are the libplot functions which, when invoked on a Plotter, cause it to draw objects (paths, circles, ellipses, points, markers, and text strings) on the associated graphics display.  A path is a sequence of line segments and arcs (either circular or elliptic).

int alabel (int HORIZ_JUSTIFY, int VERT_JUSTIFY, const char *S);
     alabel takes three arguments HORIZ_JUSTIFY, VERT_JUSTIFY, and S, which specify an `adjusted label,' i.e., a justified text string.  The path under construction (if any) is ended, and the string S is drawn according to the specified justifications.  If HORIZ_JUSTIFY is equal to l, c, or r, then the string will be drawn with left, center or right justification, relative to the current graphics cursor position.  If VERT_JUSTIFY is equal to b, x, c, or t, then the bottom, baseline, center or top of the string will be placed even with the current graphics cursor position.  The graphics cursor is moved to the right end of the string if left justification is specified, and to the left end if right justification is specified.

     The string may contain escape sequences of various sorts (see Text String Format), though it should not contain line feeds or carriage returns.  In fact it should include only printable characters, from the byte ranges 0x20...0x7e and 0xa0...0xff. The string may be plotted at a nonzero angle, if textangle has been called.

int arc (int XC, int YC, int X0, int Y0, int X1, int Y1);
int farc (double XC, double YC, double X0, double Y0, double X1, double Y1);
int arcrel (int XC, int YC, int X0, int Y0, int X1, int Y1);
int farcrel (double XC, double YC, double X0, double Y0, double X1, double Y1);
     arc and farc take six arguments specifying the beginning (X0, Y0), end (X1, Y1), and center (XC, YC) of a circular arc.  If the graphics cursor is at (X0, Y0) and a path is under construction, then the arc is added to the path.  Otherwise the current path (if any) is ended, and the arc begins a new path.  In all cases the graphics cursor is moved to (X1, Y1).

     The direction of the arc (clockwise or counterclockwise) is determined by the convention that the arc, centered at (XC, YC), sweep through an angle of at most 180 degrees.  If the three points appear to be collinear, the direction is taken to be counterclockwise.  If (XC, YC) is not equidistant from (X0, Y0) and (X1, Y1) as it should be, it is corrected by being moved to the closest point on the perpendicular bisector of the line segment joining (X0, Y0) and (X1, Y1).  arcrel and farcrel are similar to arc and farc, but use cursor-relative coordinates.

int box (int X1, int y1, int X2, int Y2);
int fbox (double X1, double Y1, double X2, double Y2);
int boxrel (int X1, int y1, int X2, int Y2);
int fboxrel (double X1, double y1, double X2, double Y2);
     box and fbox take four arguments specifying the lower left corner (X1, Y1) and upper right corner (X2, Y2) of a `box', or rectangle.  The path under construction (if any) is ended, and the box is drawn as a new path.  This path is also ended, and the graphics cursor is moved to the midpoint of the box.  boxrel and fboxrel are similar to box and fbox, but use cursor-relative coordinates.

int circle (int XC, int YC, int R);
int fcircle (double XC, double YC, double R);
int circlerel (int XC, int YC, int R);
int fcirclerel (double XC, double YC, double R);
     circle and fcircle take three arguments specifying the center (XC, YC) and radius (R) of a circle.  The path under construction (if any) is ended, and the circle is drawn.  The graphics cursor is moved to (XC, YC).  circlerel and fcirclerel are similar to circle and fcircle, but use cursor-relative coordinates for XC and YC.

int cont (int X, int Y);
int fcont (double X, double Y);
int contrel (int X, int Y);
int fcontrel (double X, double Y);
     cont and fcont take two arguments specifying the coordinates (X, Y) of a point.  If a path is under construction, the line segment from the current graphics cursor position to the point (X, Y) is added to it.  Otherwise the line segment begins a new path.  In all cases the graphics cursor is moved to (X, Y).  contrel and fcontrel are similar to cont and fcont, but use cursor-relative coordinates.

int ellarc (int XC, int YC, int X0, int Y0, int X1, int Y1);
int fellarc (double XC, double YC, double X0, double Y0, double X1, double Y1);
int ellarcrel (int XC, int YC, int X0, int Y0, int X1, int Y1);
int fellarcrel (double XC, double YC, double X0, double Y0, double X1, double Y1);
     ellarc and fellarc take six arguments specifying the three points pc=(XC,YC), p0=(X0,Y0), and p1=(X1,Y1) that define a so-called quarter ellipse. This is an elliptic arc from p0 to p1 with center pc.  If the graphics cursor is at point p0 and a path is under construction, the quarter-ellipse is added to it.  Otherwise the path under construction (if any) is ended, and the quarter-ellipse begins a new path.  In all cases the graphics cursor is moved to p1.

     The quarter-ellipse is an affinely transformed version of a quarter circle.  It is drawn so as to have control points p0, p1, and p0+p1-pc.  This means that it is tangent at p0 to the line segment joining p0 to p0+p1-pc, and is tangent at p1 to the line segment joining p1 to p0+p1-pc. So it fits snugly into a triangle with these three control points as vertices.  Notice that the third control point is the reflection of pc through the line joining p0 and p1. ellarcrel and fellarcrel are similar to ellarc and fellarc, but use cursor-relative coordinates.

int ellipse (int XC, int YC, int RX, int RY, int ANGLE);
int fellipse (double XC, double YC, double RX, double RY, double ANGLE);
int ellipserel (int XC, int YC, int RX, int RY, int ANGLE);
int fellipserel (double XC, double YC, double RX, double RY, double ANGLE);
     ellipse and fellipse take five arguments specifying the center (XC, YC) of an ellipse, the lengths of its semiaxes (RX and RY), and the inclination of the first semiaxis in the counterclockwise direction from the x axis in the user frame.  The path under construction (if any) is ended, and the ellipse is drawn.  The graphics cursor is moved to (XC, YC). ellipserel and fellipserel are similar to ellipse and fellipse, but use cursor-relative coordinates.

int endpath ();
     endpath terminates the path under construction, if any.  Paths, which are formed by repeated calls to cont or fcont, arc or farc, ellarc or fellarc, and line or fline, are also terminated if any other object is drawn or any path-related drawing attribute is set.  So endpath is almost redundant.  However, if a Plotter plots objects in real time, calling endpath will ensure that a constructed path is drawn on the graphics display without delay.

int label (const char *S);
     label takes a single string argument S and draws the text contained in S at the current graphics cursor position.  The text is left justified, and the graphics cursor is moved to the right end of the string.  This function is provided for backward compatibility; the function call label(S) is equivalent to alabel(`l',`x',S).

int labelwidth (const char *S);
double flabelwidth (const char *S);
     labelwidth and flabelwidth compute and return the width of a string in the current font, in the user frame.  The string is not plotted.

int line (int X1, int Y1, int X2, int Y2);
int fline (double X1, double y1, double X2, double Y2);
int linerel (int X1, int y1, int X2, int Y2);
int flinerel (double X1, double y1, double X2, double Y2);
     line and fline take four arguments specifying the start point (X1, Y1) and end point (X2, Y2) of a line segment.  If the graphics cursor is at (X1, Y1) and a path is under construction, the line segment is added to it.  Otherwise the path under construction (if any) is ended, and the line segment begins a new path.  In all cases the graphics cursor is moved to (X2, Y2).  linerel and flinerel are similar to line and fline, but use cursor-relative coordinates.

int marker (int X, int Y, int TYPE, int SIZE);
int fmarker (double X, double Y, int TYPE, double SIZE);
int markerrel (int X, int Y, int TYPE, int SIZE);
int fmarkerrel (double X, double Y, int TYPE, double SIZE);
     marker and fmarker take four arguments specifying the location (X,Y) of a marker symbol, its type, and its size in user coordinates.  The path under construction (if any) is ended, and the marker symbol is plotted.  The graphics cursor is moved to (X,Y).  markerrel and fmarkerrel are similar to marker and fmarker, but use cursor-relative coordinates for the position (X,Y).

     Marker symbol types 0 through 31 are taken from a standard set, and marker symbol types 32 and above are interpreted as the index of a character in the current text font.  See Marker Symbols.

int move (int X, int Y);
int fmove (double X, double Y);
int moverel (int X, int Y);
int fmoverel (double X, double Y);
     move and fmove take two arguments specifying the coordinates (X, Y) of a point to which the graphics cursor should be moved.  The path under construction (if any) is ended, and the graphics cursor is moved to (X, Y).  This is equivalent to lifting the pen on a plotter and moving it to a new position, without drawing any line.  moverel and fmoverel are similar to move and fmove, but use cursor-relative coordinates.

int point (int X, int Y);
int fpoint (double X, double Y);
int pointrel (int X, int Y);
int fpointrel (double X, double Y);
     point and fpoint take two arguments specifying the coordinates (X, Y) of a point.  The path under construction (if any) is ended, and the point is plotted.  (A `point' is usually a small solid circle, perhaps the smallest that can be plotted.)  The graphics cursor is moved to (X, Y).  pointrel and fpointrel are similar to point and fpoint, but use cursor-relative coordinates.

Attribute-setting functions
---------------------------

The following are the libplot functions which, when invoked on a Plotter, set its drawing attributes, or save them or restore them.

Note that setting any path-related drawing attribute automatically terminates the path under construction (if any), as if the endpath operation had been invoked.

int capmod (const char *S);
     capmod sets the cap mode (i.e., cap style) for all paths subsequently drawn on the graphics display.  Recognized styles are "butt" (the default), "round", and "projecting".  This function has no effect on Tektronix Plotters.  Also, it has no effect on HP-GL Plotters if the parameter HPGL_VERSION is set to a value less than "2" (the default).  See Driver Parameters.

int color (int RED, int GREEN, int BLUE);
     color is a convenience function.  Calling color is equivalent to calling both pencolor and fillcolor, to set both the the pen color and fill color of all objects subsequently drawn on the graphics display.  Note that the physical fill color depends also on the fill fraction, which is specified by calling filltype.

int colorname (const char *NAME);
     colorname is a convenience function.  Calling colorname is equivalent to calling both pencolorname and fillcolorname, to set both the the pen color and fill color of all objects subsequently drawn on the graphics display.  Note that the physical fill color depends also on the fill fraction, which is specified by calling filltype.

int filltype (int LEVEL);
     filltype sets the fill fraction for all subsequently drawn objects. A value of 0 for LEVEL indicates that objects should be unfilled, or transparent.  This is the default.  A value in the range 0x0001...0xffff, i.e., 1...65535, indicates that objects should be filled.  A value of 1 signifies 100% filling (the fill color will simply be the color specified by calling fillcolor or fillcolorname).  If LEVEL=0xffff, the fill color will be white.  Values between 0x0001 and 0xffff are interpreted as specifying a desaturation, or gray level.  For example, 0x8000 specifies 50% filling (the fill color will be intermediate between the color specified by calling fillcolor or fillcolorname, and white).

     If the object to be filled is a self-intersecting path, the `even-odd rule' will be applied to determine which points are inside, i.e., which of the regions bounded by the path should be filled.  The even-odd rule is explained in the Postscript Language Reference Manual.

     Tektronix Plotters do not support filling, and HP-GL Plotters support filling only if the parameter HPGL_VERSION is equal to "1.5" or "2" (the default).  Also, white filling is fully supported only if the value of the parameter HPGL_VERSION is "2" and the value of the parameter HPGL_OPAQUE_MODE is "yes".  See Driver Parameters.

int fillcolor (int RED, int GREEN, int BLUE);
     fillcolor sets the fill color of all objects subsequently drawn on the graphics display, using a 48-bit RGB color model.  The arguments RED, GREEN and BLUE specify the red, green and blue intensities of the fill color.  Each is an integer in the range 0x0000...0xffff, i.e., 0...65535.  The choice (0, 0, 0) signifies black, and the choice (65535, 65535, 65535) signifies white. Note that the physical fill color depends also on the fill fraction, which is specified by calling filltype.

int fillcolorname (const char *NAME);
     fillcolorname sets the fill color of all objects subsequently drawn on the graphics display to be NAME.  For information on what color names are recognized, see Color Names.  Unrecognized colors are interpreted as "black".  Note that the physical fill color depends also on the fill fraction, which is specified by calling filltype.

int fontname (const char *FONT_NAME);
double ffontname (const char *FONT_NAME);
     fontname and ffontname take a single case-insensitive string argument, FONT_NAME, specifying the name of the font to be used for all text strings subsequently drawn on the graphics display.  (The font for plotting strings is fully specified by calling fontname, fontsize, and textangle.)  The default font name depends on the type of Plotter.  It is "Helvetica" for all Plotters except Tektronix and HP-GL Plotters, for which it is "HersheySerif".  If the argument FONT_NAME is NULL or the font is not available, the default font name will be used.  Which fonts are available also depends on the type of Plotter; for a list of available fonts, see Text Fonts.  The size of the font in user coordinates is returned.

int fontsize (int SIZE);
double ffontsize (double SIZE);
     fontsize and ffontsize take a single argument, interpreted as the size, in the user frame, of the font to be used for all text strings subsequently drawn on the graphics display.  (The font for plotting strings is fully specified by calling fontname, fontsize, and textangle.)  The size of the font in user coordinates is returned. A negative value for SIZE sets the size to a default value, which depends on the type of Plotter.

int joinmod (const char *S);
     joinmod sets the join mode (i.e., join style) for all paths subsequently drawn on the graphics display.  Recognized styles are "miter" (the default), "round", and "bevel".  This function has no effect on Tektronix Plotters.  Also, it has no effect on HP-GL Plotters if the parameter HPGL_VERSION is set to a value less than "2" (the default). See Driver Parameters.

int linemod (const char *S);
     linemod sets the line mode (i.e., line style) for all paths, circles, and ellipses subsequently drawn on the graphics display.  The names supported are "disconnected", "solid", "dotted", "dotdashed", "shortdashed", and "longdashed".  A `disconnected' path joining a sequence of points is invisible, though the points themselves are visible.  Disconnected polylines are never filled. The other five linemodes correspond more or less to the following bit patterns:

          "solid"             --------------------------------
          "dotted"            - - - - - - - - - - - - - - - -
          "dotdashed"         -----------  -  -----------  -
          "shortdashed"       --              --
          "longdashed"        -------         -------

int linewidth (int SIZE);
int flinewidth (double SIZE);
     linewidth and flinewidth set the width, in the user frame, of all paths, circles, and ellipses subsequently drawn on the graphics display.  A negative value means that a default width should be used.  This default width depends on the type of Plotter.  The interpretation of zero line width is does also (for some types of Plotter, a zero-width line is the thinnest line that can be drawn; for others, a zero-width line is invisible).

     Tektronix Plotters do not support drawing with other than a default width, and HP-GL Plotters do not support doing so if the parameter HPGL_VERSION is set to a value less than "2" (the default; see Driver Parameters).

int pencolor (int RED, int GREEN, int BLUE);
     pencolor sets the pen color of all objects subsequently drawn on the graphics display, using a 48-bit RGB color model.  The arguments RED, GREEN and BLUE specify the red, green and blue intensities of the pen color.  Each is an integer in the range 0x0000...0xffff, i.e., 0...65535.  The choice (0, 0, 0) signifies black, and the choice (65535, 65535, 65535) signifies white.

     HP-GL Plotters support drawing with a white pen only if the value of the parameter HPGL_VERSION is "2" (the default), and the value of the parameter HPGL_OPAQUE_MODE is "yes".  See Driver Parameters.

int pencolorname (const char *NAME);
     pencolorname sets the pen color of all objects subsequently drawn on the graphics display to be NAME.  For information on what color names are recognized, see Color Names.  Unrecognized colors are interpreted as "black".

     HP-GL Plotters support drawing with a white pen only if the value of the parameter HPGL_VERSION is "2" (the default), and the value of the parameter HPGL_OPAQUE_MODE is "yes".  See Driver Parameters.

int restorestate ();
     restorestate pops the current graphics context off the stack of drawing states.  The graphics context consists largely of libplot's drawing parameters, which are set by the attribute functions documented in this section.  So popping off the graphics context restores the drawing parameters to values they previously had. A path under construction is regarded as part of the graphics context.  For this reason, calling restorestate automatically calls endpath to terminate the path under construction, if any.  All graphics contexts on the stack are popped off when closepl is called, as if restorestate had been called repeatedly.

int savestate ();
     savestate pushes the current graphics context onto the stack of drawing states.  The graphics context consists largely of libplot's drawing parameters, which are set by the attribute functions documented in this section.  A path under construction, if any, is regarded as part of the drawing state.  That is because paths may be drawn incrementally, one segment (line segment, circular arc segment, or elliptic arc segment) at a time.  When a graphics context is returned to, the path under construction may be continued.

int textangle (int ANGLE);
double ftextangle (double ANGLE);
     textangle and ftextangle take one argument, which specifies the angle in degrees counterclockwise from the x (horizontal) axis in the user frame, for text strings subsequently drawn on the graphics display.  The default angle is zero.  (The font for plotting strings is fully specified by calling fontname, fontsize, and textangle.)  The size of the font for plotting strings, in user coordinates, is returned.

Mapping functions
-----------------

The following four libplot functions, when invoked on a Plotter, affect the affine transformation it employs for mapping from the user frame to the device frame.  They may be viewed as performing transformations of the user frame.  Their names resemble those of the corresponding functions in the Postscript language.  For information on how to use them to draw graphics efficiently, consult any good book on Postscript programming, or the Postscript Language Reference Manual.

int fconcat (double M0, double M1, double M2, double M3, double TX, double TY);
     Apply a Postscript-style transformation matrix, i.e., affine map, to the user coordinate system.  That is, apply the linear transformation defined by the two-by-two matrix [M0 M1 M2 M3] to the user coordinate system, and also translate by TX units in the x direction and TY units in the y direction, relative to the former user coordinate system.  The following three functions (frotate, fscale, ftranslate) are convenience functions that are special cases of fconcat.

int frotate (double THETA);
     Rotate the user coordinate system axes about their origin by THETA degrees, with respect to their former orientation.  The position of the user coordinate origin and the size of the x and y units remain unchanged.

int fscale (double SX, double SY);
     Make the x and y units in the user coordinate system be the size of SX and SY units in the former user coordinate system.  The position of the user coordinate origin and the orientation of the coordinate axes are unchanged.

int ftranslate (double TX, double TY);
     Move the origin of the user coordinate system by TX units in the x direction and TY units in the y direction, relative to the former user coordinate system.  The size of the x and y units and the orientation of the coordinate axes are unchanged.

Device driver parameters
========================

In designing the libplot library, every effort has been made to make the Plotter interface independent of the type of Plotter, i.e., independent of the type of display device that the Plotter drives. Device-dependence has been kept to a minimum, and is captured by a small number of device driver parameters.

Each driver parameter has a value that is allowed to be a generic pointer (a void *).  For most parameters, this value should be a string (a char *).  A value for any parameter may be specified by calling the parampl function.  This function may be called any number of times.  Calling parampl on a parameter is said to `set' the parameter.  A parameter may be unset by calling parampl with a value argument of NULL.

The parampl function does not operate on any particular Plotter: it belongs to libplot as a whole.  The parameter values used by any Plotter are constant over the lifetime of the Plotter, and are essentially those that were in effect when the Plotter was created.  The following rule applies.  If at Plotter creation time a parameter is set, the value specified by the most recent call to parampl will be the value used by the Plotter.  If at Plotter creation time a parameter is not set, its default value will be used, unless there is an environment variable of the same name, in which case the value of that environment variable will be used.  This rule increases run-time flexibility: an application programmer may allow non-critical driver parameters to be specified by the user, via environment variables.

The following are the currently recognized parameters.  The most important parameters are DISPLAY, which affects X Plotters, and PAGESIZE, which affects Postscript, Fig, and HP-GL Plotters. These two parameters are listed first and the others alphabetically. Many of the parameters, such as the several whose names begin with "HPGL", affect only a single type of Plotter.

DISPLAY
     (Default NULL.)  The X Window System display on which the graphics display will be popped up, as an X window.  This is relevant only to X Plotters.  The size of the window in terms of pixels is currently specified only by the X resource Xplot.geometry (see below).  In future releases it will be possible to specify the size of the window by setting a driver parameter.

PAGESIZE
     (Default "letter".)  The size of the page on which the graphics display will be positioned.  This is relevant only to Postscript, Fig, and HP-GL Plotters.  "letter" means an 8.5in by 11in page.  Any ISO page size in the range "a0"..."a4" or ANSI page size in the range "a"..."e" may be specified ("letter" is an alias for "a" and "tabloid" is an alias for "b").  "legal" and "ledger" are recognized page sizes also.

     For Postscript Plotters, the graphics display will be a square region centered on the specified page and occupying its full width.  For Fig Plotters, the graphics display will be a square region located in the upper left corner of an xfig display, with width equal to the width of the specified page.  For HP-GL Plotters, fine control over the positioning of the graphics display on the page may be accomplished by setting the HPGL_XOFFSET and HPGL_YOFFSET parameters.

HPGL_ASSIGN_COLORS
     (Default "no".)  Relevant only to HP-GL Plotters, and only if the value of HPGL_VERSION is "2".  "no" means to draw with a fixed set of pens, specified by setting the HPGL_PENS parameter.  "yes" means that pen colors will not restricted to the palette specified in HPGL_PENS: colors will be assigned to ``logical pens'' in the range #1...#31, as needed.  Not all HP-GL/2 devices allow the assignment of colors to logical pens.  In particular, HP-GL/2 pen plotters do not.  So this parameter should be used with caution.

HPGL_OPAQUE_MODE
     (Default "no".)  Relevant only to HP-GL Plotters, and only if the value of HPGL_VERSION is "2".  "yes" means that pen #0 should be used as an opaque white pen, permitting the drawing of white lines and the filling of objects with opaque white.  Not all HP-GL/2 devices allow the use of pen #0 as an opaque white pen.  In particular, HP-GL/2 pen plotters do not.  So this parameter should be used with caution.

HPGL_PENS
     (Default "1=black:2=red:3=green:4=yellow:5=blue:6=magenta:7=cyan" if the value of HPGL_VERSION is "2" and "1=black" if the value of HPGL_VERSION is "1" or "1.5".)  Relevant only to HP-GL Plotters.  The set of available pens; the format should be self-explanatory.  The color for any pen in the range #1...#31 may be specified.  For information on what color names are recognized, see Color Names.  Pen #1 must always be present, though it need not be black.  Any other pen in the range #1...#31 may be omitted.

HPGL_VERSION
     (Default "2".)  Relevant only to HP-GL Plotters.  "1" means that the output should be generic HP-GL, "1.5" means that the output should be suitable for the HP7550A pen plotter (HP-GL with some HP-GL/2 extensions), and "2" means that the output should be modern HP-GL/2.

HPGL_XOFFSET
     (Default "0.0cm".)  Relevant only to HP-GL Plotters.  An adjustment, in the x direction, of the position of the graphics display on the page.  It may be specified in centimeters, millimeters, or inches.  For example, an offset could be specified as "2cm" or "1.2in".

HPGL_YOFFSET
     (Default "0.0cm".)  Relevant only to HP-GL Plotters.  An adjustment, in the y direction, of the position of the graphics display on the page.

MAX_LINE_LENGTH
     (Default "500".)  The maximum number of points that a path may contain, before it is flushed to the display device.  If this flushing occurs, the path will be split into two or more sub-paths, though the splitting should not be noticeable.  Splitting will not be performed if the path is filled.

     This parameter is relevant to X, X Drawable, Postscript, Fig, and HP-GL Plotters.  It is not relevant to Tektronix or Metafile Plotters, since they draw paths in real time.  The reason for splitting long paths is that some display devices (e.g., old Postscript printers and HP-GL plotters) have limited buffer sizes.

META_PORTABLE
     (Default "no".)  Relevant only to Metafile Plotters.  "yes" means that the output should be in a portable (human-readable) version of the metafile format, rather than the default (binary) version. See Metafiles.

ROTATE
     (Default "0".)  Currently relevant only to HP-GL Plotters.  The angle, in degrees, by which the graphics display should be rotated on the page relative to the default orientation.  Recognized values are "0", "90", "180", and "270"; "no" and "yes" are equivalent to "0" and "90" respectively.  This parameter is provided to facilitate switching between portrait and landscape orientations.  For HP-GL output devices this is frequently a concern, since some HP-GL devices (``plotters'') draw with a default landscape orientation, and others (``printers'') draw with a default portrait orientation.

TERM
     (Default NULL.)  Relevant only to Tektronix Plotters.  If the value is xterm, xterms, or kterm, it is taken as a sign that the current application is running in an X Window System VT100 terminal emulator: an xterm.  Before drawing graphics, a Tektronix Plotter will emit an escape sequence that causes the terminal emulator's auxiliary Tektronix window, which is normally hidden, to pop up.  After the graphics are drawn, an escape sequence that returns control to the original VT100 window will be emitted.  The Tektronix window will remain on the screen.

     If the value of is kermit, ansi.sys, ansissys, ansi.sysk, or ansisysk, it is taken as a sign that the current application is running in the VT100 terminal emulator provided by the DOS version of kermit.  Before drawing graphics, a Tektronix Plotter will emit an escape sequence that switches the terminal emulator to Tektronix mode.  Also, some of the Tektronix control codes output by the Plotter will be kermit-specific. There will be a limited amount of color support, which is not normally the case (the 16 ansi.sys colors will be supported).  After drawing graphics, the Plotter will emit an escape sequence that returns the emulator to VT100 mode.  The key sequence `ALT minus' may be employed manually within kermit to switch between the two modes.

VANISH_ON_DELETE
     (Default "no".)  Relevant only to X Plotters.  If the value is "yes", when a Plotter is deleted, the window or windows that it has popped up will vanish.  Otherwise, each such window will remain on the screen until it is removed by the user (by typing q in it, or by clicking with a mouse).

XDRAWABLE_DISPLAY
     (Default NULL.)  Relevant only to X Drawable Plotters.  The value should be a Display *, a pointer to the X display with which the drawable(s) to be drawn in are associated.

XDRAWABLE_DRAWABLE1
XDRAWABLE_DRAWABLE2
     (Default NULL.)  Relevant only to X Drawable Plotters.  If set, the value of each of these parameters should be a Drawable *, a pointer to a drawable to be drawn in.  A `drawable' is either a window or a pixmap.  At the time an X Drawable Plotter is created, at least one of the two parameters must be set.

     X Drawable Plotters support simultaneous drawing in two drawables because it is often useful to be able to draw graphics simultaneously in both an X window and its background pixmap.  If two drawables are specified, they must have the same dimensions and depth, and be associated with the same X display.

There is is one other low-level parameter worth mentioning.  An X Plotter always checks the value of the X resource Xplot.geometry.  It uses this value, which is a string that may be set by the user, as the size of its graphics display in terms of pixels.  The default value is "570x570".  In future releases it will be possible to set the size of an X Plotter graphics display by setting a driver parameter.

The following appendices contain miscellaneous information on the plotting utilities.

Fonts, Strings, and Symbols
***************************

The libplot library and applications linked with it, such as graph and plot, can draw text strings in a wide variety of fonts.  Text strings may include characters from more than one font in a typeface, and may include superscripts, subscripts, and square roots. A wide variety of plotting symbols can also be drawn.  The following sections explain how to use these features.

Available text fonts
====================

The libplot library and applications linked with it, such as graph and plot, can use many fonts.  These include 16 Hershey fonts, 35 Postscript fonts, and 45 PCL 5 fonts.  We call these 96 fonts the `built-in' fonts.  The Hershey fonts are so-called vector fonts, constructed from stroked characters digitized c. 1967 by Dr. Allen V. Hershey at the U.S. Naval Surface Weapons Center in Dahlgren, VA.  The 35 Postscript fonts are the fonts resident in all modern Postscript printers, and the 45 PCL 5 fonts are the fonts resident in modern Hewlett--Packard LaserJet printers and plotters.  (The old LaserJet III, which was Hewlett--Packard's first PCL 5 printer, supported only 8 of the 45.)

The Hershey fonts may be used by all types of Plotter supported by libplot, and the Postscript fonts may be used by all types of Plotter except HP-GL and Tektronix.  So all variants of graph may use the Hershey fonts, and all variants of graph except graph -T hpgl and graph -T tek may use the Postscript fonts.  The PCL 5 fonts may be used only by HP-GL Plotters and graph -T hpgl.

For the purpose of plotting text strings (see Text String Format), the built-in fonts are divided into typefaces.  The 16 Hershey fonts are divided into typefaces as follows.

  * HersheySerif

      1. HersheySerif

      2. HersheySerif-Italic

      3. HersheySerif-Bold

      4. HersheySerif-BoldItalic

      5. HersheyCyrillic

      6. HersheyEUC

  * HersheySans

      1. HersheySans

      2. HersheySans-Oblique

      3. HersheySans-Bold

      4. HersheySans-BoldOblique

  * HersheyScript

      1. HersheyScript

      2. HersheyScript

      3. HersheyScript-Bold

      4. HersheyScript-Bold

  * HersheyGothic-English

  * HersheyGothic-German

  * HersheyGothic-Italian

  * HersheySerif-Symbol

  * HersheySans-Symbol

The three HersheyGothic fonts are singletons: each is font #1 of its own typeface.  The two symbol fonts play a special role.  By convention, each Hershey typeface contains a symbol font (HersheySerif-Symbol or HersheySans-Symbol, as appropriate) as font #0.

The 35 Postscript fonts are divided into typefaces as follows.

  * Helvetica

      1. Helvetica

      2. Helvetica-Oblique

      3. Helvetica-Bold

      4. Helvetica-BoldOblique

  * Helvetica-Narrow

      1. Helvetica-Narrow

      2. Helvetica-Narrow-Oblique

      3. Helvetica-Narrow-Bold

      4. Helvetica-Narrow-BoldOblique

  * Times

      1. Times-Roman

      2. Times-Italic

      3. Times-Bold

      4. Times-BoldItalic

  * AvantGarde

      1. AvantGarde-Book

      2. AvantGarde-BookOblique

      3. AvantGarde-Demi

      4. AvantGarde-DemiOblique

  * Bookman

      1. Bookman-Light

      2. Bookman-LightItalic

      3. Bookman-Demi

      4. Bookman-DemiItalic

  * Courier

      1. Courier

      2. Courier-Oblique

      3. Courier-Bold

      4. Courier-BoldOblique

  * NewCenturySchlbk

      1. NewCenturySchlbk-Roman

      2. NewCenturySchlbk-Italic

      3. NewCenturySchlbk-Bold

      4. NewCenturySchlbk-BoldItalic

  * Palatino

      1. Palatino-Roman

      2. Palatino-Italic

      3. Palatino-Bold

      4. Palatino-BoldItalic

  * ZapfChancery-MediumItalic

  * ZapfDingbats

  * Symbol

The two Zapf fonts are singletons: each is font #1 of its own typeface. The Symbol font plays a special role.  By convention, each Postscript typeface contains the Symbol font as font #0.

The 45 PCL 5 fonts are divided into typefaces as follows.

  * Univers

      1. Univers

      2. Univers-Oblique

      3. Univers-Bold

      4. Univers-BoldOblique

  * UniversCondensed

      1. UniversCondensed

      2. UniversCondensed-Oblique

      3. UniversCondensed-Bold

      4. UniversCondensed-BoldOblique

  * CGTimes

      1. CGTimes-Roman

      2. CGTimes-Italic

      3. CGTimes-Bold

      4. CGTimes-BoldItalic

  * Albertus

      1. AlbertusMedium

      2. AlbertusMedium

      3. AlbertusExtraBold

      4. AlbertusExtraBold

  * AntiqueOlive

      1. AntiqueOlive

      2. AntiqueOlive-Italic

      3. AntiqueOlive-Bold

  * Arial

      1. Arial-Roman

      2. Arial-Italic

      3. Arial-Bold

      4. Arial-BoldItalic

  * ClarendonCondensed

  * Coronet

  * Courier

      1. Courier

      2. Courier-Italic

      3. Courier-Bold

      4. Courier-BoldItalic

  * Garamond

      1. Garamond

      2. Garamond-Italic

      3. Garamond-Bold

      4. Garamond-BoldItalic

  * LetterGothic

      1. LetterGothic-Roman

      2. LetterGothic-Italic

      3. LetterGothic-Bold

      4. LetterGothic-BoldItalic

  * Marigold

  * CGOmega

      1. CGOmega-Roman

      2. CGOmega-Italic

      3. CGOmega-Bold

      4. CGOmega-BoldItalic

  * TimesNewRoman

      1. TimesNewRoman

      2. TimesNewRoman-Italic

      3. TimesNewRoman-Bold

      4. TimesNewRoman-BoldItalic

  * Wingdings

  * Symbol

The ClarendonCondensed, Coronet, Marigold, and Wingdings fonts are singletons: each is font #1 of its own typeface.  The Symbol font plays a special role.  By convention, each PCL 5 typeface contains the Symbol font as font #0.

As you can see from the three preceding tables, our convention is that in any typeface with more than a single font, font #1 is the normal font, font #2 is italic or oblique, font #3 is bold, and font #4 is bold italic or bold oblique.  Additional variants (if any) are numbered #5 and higher.

Of the above built-in fonts, all except for the four Symbol fonts, HersheyCyrillic, HersheyEUC, ZapfDingbats, and Wingdings are ISO-8859-1 fonts.  This means that they use the ISO-Latin-1 encoding, which is a superset of ASCII.  The four Symbol fonts use a special encoding, since they consist of Greek characters and mathematical symbols.  The Symbol encoding and the encoding used by the ZapfDingbats font are documented in the Postscript Language Reference Manual.

The HersheyCyrillic font uses an encoding known as KOI8-R, a superset of ASCII which has become the de facto standard for Unix and networking applications in the former Soviet Union.  Insofar as printable ASCII characters go, it is the same as the HersheySerif font.  But its `8-bit' characters are different.  The byte range 0xc0...0xdf contains lower-case Cyrillic characters and the byte range 0xe0...0xff contains upper case Cyrillic characters. Additional Cyrillic characters are located at 0xa3 and 0xb3. For more on this encoding, see http://www.nagual.pp.ru/~ache/koi8.html and the document known as Internet RFC 1489.

The HersheyEUC font is used for displaying Japanese.  EUC stands for `extended Unix code', which is a scheme for encoding Japanese, and also other character sets (e.g., Greek and Cyrillic) as multibyte character strings.  The format of EUC strings is discussed in Ken Lunde's Understanding Japanese Information Processing (O'Reilly, 1993), which contains much additional information on Japanese text processing. See also his on-line supplement (http://www.ora.com/people/authors/lunde/cjk_inf.html).

In the HersheyEUC font, characters in the printable ASCII range, 0x20...0x7e, are similar to US ASCII (they are `JIS Roman', an ASCII variant standardized by the Japanese Industrial Standards Committee).  Each successive pair of bytes in the 0xa1...0xfe range defines a single character in the JIS X0208 standard.  The characters in the JIS X0208 standard include Japanese syllabic characters (Hiragana and Katakana), ideographic characters (Kanji), Roman, Greek, and Cyrillic alphabets, punctuation marks, and miscellaneous symbols.  For example, the JIS X0208 standard indexes the 83 Hiragana as 0x2421...0x2453.  To obtain the EUC code for any JIS X0208 character, one adds 0x80 to each byte (i.e., `sets the high bit' on each byte).  So the first of the 83 Hiragana (0x2421) would be encoded as the successive pair of bytes 0xa4 and 0xa1.

The implementation of the JIS X0208 standard in the HersheyEUC font is based on Dr. Hershey's digitizations, and is complete enough to be useful.  All Hiragana and Katakana are available, though the little-used `half-width Katakana' are not supported.  Also, 603 frequently used Kanji are available.  The Hiragana, the Katakana, and the available Kanji all have the same width.  The file kanji.doc, which is distributed along with the GNU plotting utilities, lists the 603 available Kanji.  Each JIS X0208 character that is unavailable will be drawn as an `undefined character' glyph (several horizontal lines).

To what extent do the fonts supported by libplot contain ligatures?  The 35 Postscript fonts and 45 PCL 5 fonts, as implemented in libplot, do not contain ligatures.  However, four of the 16 Hershey fonts contain ligatures.  The character combinations "fi", "ff", "fl", "ffi", and "ffl" are automatically drawn as ligatures in HersheySerif and HersheySerif-Italic.  (Also in HersheyCyrillic and HersheyEUC, since insofar as printable ASCII characters are concerned, they are identical [or almost identical] to HersheySerif.)  In addition, "tz" and "ch" are ligatures in HersheyGothic-German.  The German double-s character `ß', which is called an `eszet', is not regarded as a ligature in any font.  To obtain an eszet, you must either request one with the control sequence "\ss" (see Text String Format), or, if you have an 8-bit keyboard, type an eszet explicitly.

The preceding discussions dealt with the built-in fonts: the 16 Hershey fonts, the 35 Postscript fonts, and the 45 PCL 5 fonts.  In fact, the X Plotters supported by libplot, and graph -T X (which is built on top of libplot) are not restricted to the built-in fonts.  They can display text strings using certain X Window System fonts as well.  Any scalable font which is available on the current X Window System display, and which has a so-called XLFD (X Logical Font Description) name, may be used.  For example, the font "-monotype-gill sans-ultrabold-r-condensed--0-0-0-0-p-0-iso8859-1" is available on some X displays.  It would be referred to as "gill sans-ultrabold-r-condensed".  The command

     echo 0 0 1 1 2 0 | graph -T X -F "gill sans-ultrabold-r-condensed"

would draw a plot on an X display, in which all axis ticks are labeled in this font.

You may determine which fonts are available on an X display by using the xlsfonts command.  Fonts whose names end in "-0-0-0-0-p-0-iso8859-1" or "-0-0-0-0-m-0-iso8859-1" are scalable ISO-Latin-1 fonts that may be used by libplot's X Plotters and by graph -T X.  The two sorts of font are variable-width and fixed-width fonts, respectively.  Fonts whose names end in "adobe-fontspecific" may also be used.  They are fonts that do not employ the ISO-Latin-1 encoding.

The escape sequences which allow access to mathematical symbols and Greek characters (see Text String Format) may be employed when using any X Window System font.  Also, the escape sequences which allow access to the special non-ASCII characters in any of the built-in ISO-Latin-1 fonts may be employed when using any ISO-Latin-1 X Window System font.

Text string format and escape sequences
=======================================

Text strings that are drawn by libplot, and by such applications as graph that are built on libplot, must consist of printable characters.  No embedded control characters, such as newlines or carriage returns, are allowed.  Technically, a character is `printable' if it comes from either of the two byte ranges 0x20...0x7e and 0xa0...0xff.  The former is the printable ASCII range.

Text strings may, however, include embedded `escape sequences' that shift the font, append subscripts or superscripts, or include special mathematical symbols.  As a consequence, the axis labels on a plot prepared with graph may include such features.

The format of the escape sequences should look familiar to anyone who is familiar with the TeX or groff document formatters.  Each escape sequence consists of three characters: a backslash and two characters that specify the control code.  The most frequently used escape sequences are as follows.

"\sp"
     start superscript mode

"\ep"
     end superscript mode

"\sb"
     start subscript mode

"\eb"
     end subscript mode

"\mk"
     mark location

"\rt"
     return to marked location

For example, the string "x\sp2\ep" would be interpreted as `x squared'. Subscripts on subscripts, etc., are allowed.  Subscripts and superscripts may be vertically aligned by judicious use of the "\mk" and "\rt" escape sequences.  For example, "a\mk\sbi\eb\rt\sp2\ep" produces "a sub i squared", with the exponent `2' placed immediately above the subscript.

There are also escape sequences that switch from font to font within a typeface.  For an enumeration of the fonts within each typeface, see Text Fonts.  Suppose for example that the current font is `Times-Roman', which is font #1 in the `Times' typeface.  The string "A \f2very\f1 well labeled axis" would be a string in which the word `very' appears in Times-Italic rather than Times-Roman.  That is because Times-Italic is the #2 font in the typeface.  Font-switching escape sequences are of the form "\fN", where N is the number of the font to be switched to, in the current font.  There is currently no support for switching between fonts in different typefaces.

There are also a few escape sequences for horizontal shifts, which are useful for improving horizontal alignment, such as when shifting between fonts.  "\r1", "\r2", "\r4", "\r6", "\r8" are escape sequences that shift right by 1 em, 1/2 em, 1/4 em, 1/6 em, and 1/8 em, respectively. "\l1", "\l2", "\l4", "\l6", "\l8" are similar, but shift left instead of right.  "A \f2very\r8\f1 well labeled axis" would look better than "A \f2very\f1 well labeled axis".

Square roots are handled with the aid of a special pair of escape sequences, together with the "\mk" and "\rt" sequences discussed above. A square root symbol is begun with "\sr", and continued arbitrarily far to the right with the overbar (`run') escape sequence, "\rn".  For example, the string "\sr\mkab\rt\rn\rn" would be plotted as `the square root of ab'.  To adjust the length of the overbar, you may need to experiment with the number of times "\rn" appears.

To underline a string, you would use "\ul", the underline escape sequence, one or more times.  The "\mk"..."\rt" trick would be employed in the same way.  So, for example, "\mkabc\rt\ul\ul\ul" would yield an underlined "ABC".  To adjust the length of the underline, you may need to experiment with the number of times "\ul" appears.  You may also need to use one or more of the abovementioned horizontal shifts. For example, if the "HersheySerif" font were used, "\mkabc\rt\ul\ul\l8\ul" would yield a better underline than "\mkabc\rt\ul\ul\ul".

Besides the preceding escape sequences, there are also escape sequences for the printable non-ASCII characters in each of the built-in ISO-Latin-1 fonts (which means in every built-in font, except for the symbol fonts, HersheyCyrillic, HersheyEUC, and ZapfDingbats).  Such `8-bit' characters, in the 0xa0...0xff byte range, may be included directly in a text string.  But if your editor does not permit this, you may use the escape sequences for them instead.  The useful non-ASCII characters include accented characters, among others.

There are escape sequences for the mathematical symbols and Greek characters in the symbol fonts, as well.  Which font the mathematical symbols and Greek characters are taken from depends on whether your current font is a Hershey font or a Postscript font.  The symbols are taken from the HersheySerif-Symbol font or the HersheySans-Symbol font in the former case, and from the Symbol font in the latter.

The following are the escape sequences that provide access to the non-ASCII characters of the current font, provided that it is an ISO-Latin-1 font.  Each escape sequence is followed by the position of the corresponding character in the ISO-Latin-1 encoding (in decimal), and the official Postscript name of the character.  Most names should be self-explanatory.  For example, `eacute' is a lower-case `e', equipped with an acute accent.

"\r!"
     [161] exclamdown

"\ct"
     [162] cent

"\Po"
     [163] sterling

"\Cs"
     [164] currency

"\Ye"
     [165] yen

"\bb"
     [166] brokenbar

"\sc"
     [167] section

"\ad"
     [168] dieresis

"\co"
     [169] copyright

"\Of"
     [170] ordfeminine

"\Fo"
     [171] guillemotleft

"\no"
     [172] logicalnot

"\hy"
     [173] hyphen

"\rg"
     [174] registered

"\a-"
     [175] macron

"\de"
     [176] degree

"\+-"
     [177] plusminus

"\S2"
     [178] twosuperior

"\S3"
     [179] threesuperior

"\aa"
     [180] acute

"\*m"
     [181] mu

"\ps"
     [182] paragraph

"\md"
     [183] periodcentered

"\ac"
     [184] cedilla

"\S1"
     [185] onesuperior

"\Om"
     [186] ordmasculine

"\Fc"
     [187] guillemotright

"\14"
     [188] onequarter

"\12"
     [189] onehalf

"\34"
     [190] threequarters

"\r?"
     [191] questiondown

"\`A"
     [192] Agrave

"\'A"
     [193] Aacute

"\^A"
     [194] Acircumflex

"\~A"
     [195] Atilde

"\:A"
     [196] Adieresis

"\oA"
     [197] Aring

"\AE"
     [198] AE

"\,C"
     [199] Ccedilla

"\`E"
     [200] Egrave

"\'E"
     [201] Eacute

"\^E"
     [202] Ecircumflex

"\:E"
     [203] Edieresis

"\`I"
     [204] Igrave

"\'I"
     [205] Iacute

"\^I"
     [206] Icircumflex

"\:I"
     [207] Idieresis

"\-D"
     [208] Eth

"\~N"
     [209] Ntilde

"\'O"
     [210] Ograve

"\'O"
     [211] Oacute

"\^O"
     [212] Ocircumflex

"\~O"
     [213] Otilde

"\:O"
     [214] Odieresis

"\mu"
     [215] multiply

"\/O"
     [216] Oslash

"\`U"
     [217] Ugrave

"\'U"
     [218] Uacute

"\^U"
     [219] Ucircumflex

"\:U"
     [220] Udieresis

"\'Y"
     [221] Yacute

"\TP"
     [222] Thorn

"\ss"
     [223] germandbls

"\`a"
     [224] agrave

"\'a"
     [225] aacute

"\^a"
     [226] acircumflex

"\~a"
     [227] atilde

"\:a"
     [228] adieresis

"\oa"
     [229] aring

"\ae"
     [230] ae

"\,c"
     [231] ccedilla

"\`e"
     [232] egrave

"\'e"
     [233] eacute

"\^e"
     [234] ecircumflex

"\:e"
     [235] edieresis

"\`i"
     [236] igrave

"\'i"
     [237] iacute

"\^i"
     [238] icircumflex

"\:i"
     [239] idieresis

"\Sd"
     [240] eth

"\~n"
     [241] ntilde

"\`o"
     [242] ograve

"\'o"
     [243] oacute

"\^o"
     [244] ocircumflex

"\~o"
     [245] otilde

"\:o"
     [246] odieresis

"\di"
     [247] divide

"\/o"
     [248] oslash

"\`u"
     [249] ugrave

"\'u"
     [250] uacute

"\^u"
     [251] ucircumflex

"\:u"
     [252] udieresis

"\'y"
     [253] yacute

"\Tp"
     [254] thorn

"\:y"
     [255] ydieresis

The following are the escape sequences that provide access to mathematical symbols and Greek characters in the current symbol font, whether HersheySerif-Symbol or HersheySans-Symbol (for Hershey fonts) or Symbol (for Postscript fonts).  Each escape sequence is followed by the position (in octal) of the corresponding character in the symbol encoding, and the official Postscript name of the character.  Many escape sequences and names should be self-explanatory.  "\*a" represents a lower-case Greek alpha, for example.  For a table displaying each of the characters below, see the Postscript Language Reference Manual.

"\fa"
     [0042] universal

"\te"
     [0044] existential

"\st"
     [0047] suchthat

"\**"
     [0052] asteriskmath

"\=~"
     [0100] congruent

"\*A"
     [0101] Alpha

"\*B"
     [0102] Beta

"\*X"
     [0103] Chi

"\*D"
     [0104] Delta

"\*E"
     [0105] Epsilon

"\*F"
     [0106] Phi

"\*G"
     [0107] Gamma

"\*Y"
     [0110] Eta

"\*I"
     [0111] Iota

"\+h"
     [0112] theta1

"\*K"
     [0113] Kappa

"\*L"
     [0114] Lambda

"\*M"
     [0115] Mu

"\*N"
     [0116] Nu

"\*O"
     [0117] Omicron

"\*P"
     [0120] Pi

"\*H"
     [0121] Theta

"\*R"
     [0122] Rho

"\*S"
     [0123] Sigma

"\*T"
     [0124] Tau

"\*U"
     [0125] Upsilon

"\ts"
     [0126] sigma1

"\*W"
     [0127] Omega

"\*C"
     [0130] Xi

"\*Q"
     [0131] Psi

"\*Z"
     [0132] Zeta

"\tf"
     [0134] therefore

"\pp"
     [0136] perpendicular

"\ul"
     [0137] underline

"\rx"
     [0140] radicalex

"\*a"
     [0141] alpha

"\*b"
     [0142] beta

"\*x"
     [0143] chi

"\*d"
     [0144] delta

"\*e"
     [0145] epsilon

"\*f"
     [0146] phi

"\*g"
     [0147] gamma

"\*y"
     [0150] eta

"\*i"
     [0151] iota

"\+f"
     [0152] phi1

"\*k"
     [0153] kappa

"\*l"
     [0154] lambda

"\*m"
     [0155] mu

"\*n"
     [0156] nu

"\*o"
     [0157] omicron

"\*p"
     [0160] pi

"\*h"
     [0161] theta

"\*r"
     [0162] rho

"\*s"
     [0163] sigma

"\*t"
     [0164] tau

"\*u"
     [0165] upsilon

"\+p"
     [0166] omega1

"\*w"
     [0167] omega

"\*c"
     [0170] xi

"\*q"
     [0171] psi

"\*z"
     [0172] zeta

"\ap"
     [0176] similar

"\+U"
     [0241] Upsilon1

"\fm"
     [0242] minute

"\<="
     [0243] lessequal

"\f/"
     [0244] fraction

"\if"
     [0245] infinity

"\Fn"
     [0246] florin

"\CL"
     [0247] club

"\DI"
     [0250] diamond

"\HE"
     [0251] heart

"\SP"
     [0252] spade

"\<>"
     [0253] arrowboth

"\<-"
     [0254] arrowleft

"\ua"
     [0255] arrowup

"\->"
     [0256] arrowright

"\da"
     [0257] arrowdown

"\de"
     [0260] degree

"\+-"
     [0261] plusminus

"\sd"
     [0262] second

"\>="
     [0263] greaterequal

"\mu"
     [0264] multiply

"\pt"
     [0265] proportional

"\pd"
     [0266] partialdiff

"\bu"
     [0267] bullet

"\di"
     [0270] divide

"\!="
     [0271] notequal

"\=="
     [0272] equivalence

"\~~"
     [0273] approxequal

"\.."
     [0274] ellipsis

NONE
     [0275] arrowvertex

"\an"
     [0276] arrowhorizex

"\CR"
     [0277] carriagereturn

"\Ah"
     [0300] aleph

"\Im"
     [0301] Ifraktur

"\Re"
     [0302] Rfraktur

"\wp"
     [0303] weierstrass

"\c*"
     [0304] circlemultiply

"\c+"
     [0305] circleplus

"\es"
     [0306] emptyset

"\ca"
     [0307] cap

"\cu"
     [0310] cup

"\SS"
     [0311] superset

"\ip"
     [0312] reflexsuperset

"\n<"
     [0313] notsubset

"\SB"
     [0314] subset

"\ib"
     [0315] reflexsubset

"\mo"
     [0316] element

"\nm"
     [0317] notelement

"\/_"
     [0320] angle

"\gr"
     [0321] nabla

"\rg"
     [0322] registerserif

"\co"
     [0323] copyrightserif

"\tm"
     [0324] trademarkserif

"\PR"
     [0325] product

"\sr"
     [0326] radical

"\md"
     [0327] dotmath

"\no"
     [0330] logicalnot

"\AN"
     [0331] logicaland

"\OR"
     [0332] logicalor

"\hA"
     [0333] arrowdblboth

"\lA"
     [0334] arrowdblleft

"\uA"
     [0335] arrowdblup

"\rA"
     [0336] arrowdblright

"\dA"
     [0337] arrowdbldown

"\lz"
     [0340] lozenge

"\la"
     [0341] angleleft

"\RG"
     [0342] registersans

"\CO"
     [0343] copyrightsans

"\TM"
     [0344] trademarksans

"\SU"
     [0345] summation

NONE
     [0346] parenlefttp

NONE
     [0347] parenleftex

NONE
     [0350] parenleftbt

"\lc"
     [0351] bracketlefttp

NONE
     [0352] bracketleftex

"\lf"
     [0353] bracketleftbt

"\lt"
     [0354] bracelefttp

"\lk"
     [0355] braceleftmid

"\lb"
     [0356] braceleftbt

"\bv"
     [0357] braceex

NONE
     [0360] applelogo

"\ra"
     [0361] angleright

"\is"
     [0362] integral

NONE
     [0363] integraltp

NONE
     [0364] integralex

NONE
     [0365] integralbt

NONE
     [0366] parenrighttp

NONE
     [0367] parenrightex

NONE
     [0370] parenrightbt

"\rc"
     [0371] bracketrighttp

NONE
     [0372] bracketrightex

"\rf"
     [0373] bracketrightbt

"\RT"
     [0374] bracerighttp

"\rk"
     [0375] bracerightmid

"\rb"
     [0376] bracerightbt

Finally, there are escape sequences that apply only if the current font is a Hershey font.  Most of these escape sequences provide access to special symbols that belong to no font, and are accessible by no other means.  These symbols are of two sorts: miscellaneous and astronomical. The escape sequences for the miscellaneous symbols are as follows.

"\dd"
     daggerdbl

"\dg"
     dagger

"\hb"
     hbar

"\li"
     lineintegral

"\IB"
     interbang

"\Lb"
     lambdabar

"\~-"
     modifiedcongruent

"\-+"
     minusplus

"\||"
     parallel

"\s-"
     [variant form of s]

The final escape sequence in the table above, "\s-", yields a letter rather than a symbol.  It is provided because in some Hershey fonts, the shape of the lower-case letter `s' differs if it is the last letter in a word.  This is the case for HersheyGothic-German.  The German word "besonders", for example, should be written as "besonder\s-" if it is to be rendered correctly in this font.  The same is true for the two Hershey symbol fonts, with their Greek alphabets (in Greek text, lower-case final `s' is different from lower-case non-final `s').  In Hershey fonts where there is no distinction between final and non-final `s', "s" and "\s-" are equivalent.

The escape sequences for the astronomical symbols are listed in the following table.  We stress that that like the preceding miscellaneous escape sequences, they apply only if the current font is a Hershey font.

"\SO"
     sun

"\ME"
     mercury

"\VE"
     venus

"\EA"
     earth

"\MA"
     mars

"\JU"
     jupiter

"\SA"
     saturn

"\UR"
     uranus

"\NE"
     neptune

"\PL"
     pluto

"\LU"
     moon

"\CT"
     comet

"\ST"
     star

"\AS"
     ascendingnode

"\DE"
     descendingnode

The preceding miscellaneous and astronomical symbols are not the only special non-font symbols that may be used if the current font is a Hershey font.  The entire library of glyphs digitized by Allen V. Hershey is built into GNU libplot.  So text strings may include any Hershey glyph.  Each of the 1641 available Hershey glyphs is identified by a four-digit number.  Standard Hershey glyph #1 would be specified as "\#H0001".  The standard Hershey glyphs range from "\#H0001" to "\#H3999", with a number of gaps.  Some additional glyphs designed by others appear in the "\#H4000"..."\#H4194" range. Syllabic Japanese characters (Kana) are located in the "\#H4195"..."\#H4399" range.

You may order a table of nearly all the Hershey glyphs in the "\#H0001"..."\#H3999" range from the U.S. National Technical Information Service, at +1 703 487 4650.  Ask for item number PB251845; the current price is about US$40.  By way of example, the string

     "\#H0744\#H0745\#H0001\#H0002\#H0003\#H0869\#H0907\#H2330\#H2331"

when drawn will display a shamrock, a fleur-de-lys, cartographic (small) letters A, B, C, a bell, a large circle, a treble clef, and a bass clef.  Again, this assumes that the current font is a Hershey font.

You may also use Japanese syllabic characters (Hiragana and Katakana) and ideographic characters (Kanji) when drawing strings in any Hershey font.  In all, 603 Kanji are available; these are the same Kanji that are available in the HersheyEUC font.  The Japanese characters are indexed according to the JIS X0208 standard for Japanese typography, which represents each character by a two-byte sequence.  Each JIS X0208 character would be specified by an escape sequence which expresses this two-byte sequence as four hexadecimal digits, such as "\#J357e".  Both bytes must be in the 0x21...0x7e range in order to define a JIS X0208 character.  Kanji are located at "\#J3021" and above. The file kanji.doc, which is distributed along with the GNU plotting utilities, lists the available Kanji.

Characters appearing elsewhere in the JIS X0208 encoding may be accessed similarly.  For example, Hiragana and Katakana are located in the "\#J2421"..."\#J257e" range, and Roman characters are located in the "\#J2300"..."\#J237e" range.  The file kana.doc lists the encodings of the Hiragana and Katakana.  For more on the JIS X0208 standard, see Ken Lunde's Understanding Japanese Information Processing (O'Reilly, 1993), and his on-line supplement (http://www.ora.com/people/authors/lunde/cjk_inf.html).

The Kanji numbering used in A. N. Nelson's Modern Reader's Japanese-English Character Dictionary, a longtime standard, is also supported.  (This dictionary is published by C. E. Tuttle and Co., with ISBN 0-8048-0408-7.  A revised edition [ISBN 0-8048-2036-8] appeared in 1997, but uses a different numbering.)  `Nelson' escape sequences for Kanji are similar to JIS X0208 escape sequences, but use four decimal instead of four hexadecimal digits.  The file kanji.doc gives the correspondence between the JIS numbering scheme and the Nelson numbering scheme.  For example, "\#N0001" is equivalent to "\#J306c".  It also gives the positions of the available Kanji in the Unicode encoding.

All available Kanji have the same width, which is the same as that of the syllabic Japanese characters (Hiragana and Katakana).  Each Kanji that is not available will print as an `undefined character' glyph (a set of horizontal lines).  The same is true for non-Kanji JIS X0208 characters which are not available.

Available marker symbols
========================

The GNU libplot library supports a standard set of marker symbols, numbered 0 through 31.  These are the symbols that the graph program will plot at each point of a dataset, if the -S option is used.  The list is as follows (by convention, marker symbol #0 means no symbol at all).

 0. no symbol at all

 1. dot

 2. plus (+)

 3. asterisk (*)

 4. circle

 5. cross

 6. square

 7. triangle

 8. diamond

 9. star

 10. inverted triangle

 11. starburst

 12. fancy plus

 13. fancy cross

 14. fancy square

 15. fancy diamond

 16. filled circle

 17. filled square

 18. filled triangle

 19. filled diamond

 20. filled inverted triangle

 21. filled fancy square

 22. filled fancy diamond

 23. half filled circle

 24. half filled square

 25. half filled triangle

 26. half filled diamond

 27. half filled inverted triangle

 28. half filled fancy square

 29. half filled fancy diamond

 30. octagon

 31. filled octagon

The interpretation of marker symbols 1 through 5 is the same as in the GKS (Graphics Kernel System).

Symbols 32 and up are interpreted as characters in a certain text font. For libplot, it is the current font.  For graph, it is the font selected with the --symbol-font-name option.  By default, this is the ZapfDingbats font except in graph -T hpgl and graph -T tek.  graph -T hpgl and graph -T tek currently have no access to Postscript fonts, so they use the HersheySerif font instead.

Many of the characters in the ZapfDingbats font are suitable for use as marker symbols.  For example, character #74 is the Texas star.  Doing

     echo 0 0 1 2 2 1 3 2 4 0 | graph -T ps -m 0 -S 74 0.1 > plot.ps

will produce a Postscript plot consisting of five data points, not joined by line segments.  Each data point will be marked by a Texas star, of a large font size (0.1 times the width of the plotting box).

Specifying Colors by Name
*************************

Many of the plotting utilities allow colors to be specified by name. For example, graph supports the --frame-color option. graph -T hpgl and plot -T hpgl check the value of the HPGL_PENS environment variable, as do the HP-GL Plotters available in the libplot library (on which they are based). Also, the libplot library includes the pencolorname and fillcolorname functions.

In any of these contexts, 665 distinct color names are recognized, including obscure ones like "dark magenta", "forest green", and "olive drab".  Color names are case-insensitive, and spaces are ignored.  So, for example, "RosyBrown" is equivalent to "rosy brown", and "DarkGoldenrod3" to "dark goldenrod 3".

The file colors.txt, which is distributed along with the GNU plotting utilities, lists the available color names.  They are essentially the color names recognized by recent releases of the X Window System, which on most machines are listed in the file /usr/lib/X11/rgb.txt.  However, for every color name containing the string "gray", a version containing "grey" has been included. For example, both "dark slate gray 4" and "dark slate grey 4" are recognized color names.

The Graphics Metafile Format
****************************

A GNU graphics metafile is produced by raw graph or by any other graphics application that uses the Metafile Plotter support contained in libplot.  It is a sort of audit trail: it contains a record of which libplot functions have been called, together with their arguments.  That is, it is a sequence of plotting commands, each of which may be followed by data.  Each plotting command is an `op code': a single ASCII character, indicating which libplot function was called.  The data following the command are the arguments of the function.

There are two sorts of GNU metafile: binary (the default) and portable (human-readable).  If you wish to transfer GNU metafiles between machines of different types, you should use portable rather than binary format.  Portable metafiles are produced by raw graph when the -O option is specified, and by the metafile driver of libplot when the META_PORTABLE parameter is set to "yes". Both binary and portable may be translated to other formats by GNU plot.  Binary metafiles begin with the magic string #PLOT 1, and portable metafiles with the magic string #PLOT 2.

In the portable format, the arguments (integers, floating point numbers, or strings) are printed in a human-readable form, separated by spaces, and each argument list ends with a newline.  In the binary format, the arguments are represented as integers, single precision floating point numbers, or newline-terminated ASCII strings.  The role played by the newline character as a terminator is acceptable because each libplot function includes a maximum of one string among its arguments, and the string may not include a newline.  Moreover, the string must come last among the arguments.

In the traditional plot(5) format produced by pre-GNU versions of graph, command arguments were either two-byte integers or newline-terminated strings.  At the time plot(5) format was designed, `two-byte integer' was synonymous with `short integer', but that is no longer the case.  GNU plot can convert metafiles in the traditional format to GNU metafiles in either binary or portable format.  The absence of a magic string makes it possible to distinguish files in plot(5) format from GNU metafiles.

The following table lists some of the op codes that appear in either version of GNU metafile format, i.e., the possible single-character commands, followed by the name of the libplot function they stand for.  All 79 basic libplot functions have a corresponding op code, with the exception of (1) the setup functions flushpl and outfile, (2) the functions havecap, labelwidth, and flabelwidth, which return information, and (3) the pencolorname and fillcolorname functions, which are mapped to pencolor and fillcolor internally.

Op Code
     Function

a
     arc

c
     circle

e
     erase

f
     linemod

l
     line

m
     move

n
     cont

p
     point

s
     space

t
     label

The op codes above are actually the op codes of the traditional plot(5) format.  Since the GNU metafile format is compatible with it, they are also used in GNU metafiles.  The other op codes of metafile format are too numerous to list.  They are defined in the header file plot.h, which is distributed along with the plotting utilities.

Obtaining Auxiliary Software
****************************

How to get idraw
================

The idraw utility mentioned several times in this documentation is a freely distributable interactive drawing editor for the X Window System.  It may be used to edit the output of graph -T ps, or, in general, the output of any application that uses the Postscript Plotter support contained in libplot.

The current version of idraw is maintained by Vectaport, Inc., and is available at their Web site (http://www.vectaport.com). It is part of the ivtools package, which is a framework for building custom drawing editors.  idraw was originally part of the InterViews package, developed by Stanford University and Silicon Graphics.  The InterViews package is available at a distribution site (ftp://interviews.stanford.edu) but is no longer supported.  Retrieving the ivtools package instead is recommended.

Also available at Vectaport's Web site (http://www.vectaport.com) is an enhanced version of idraw called drawtool.  Unlike idraw, drawtool can import bitmapped graphics in PBM/PGM/PPM, TIFF, and X11 bitmap formats.

How to get xfig
===============

The xfig utility mentioned several times in this documentation is a freely distributable interactive drawing editor for the X Window System.  It may be used to edit the output of graph -T fig, or in general the output of any application that uses the Fig Plotter support contained in libplot.

The current version is available at ftp://ftp.x.org/contrib/applications/drawing_tools/.  It can import graphics in GIF, X11 bitmap, and Postscript formats. Accompanying the editor is a package called transfig, which allows xfig graphics to be exported in many formats.  GIF, X11 bitmap, LaTeX, and Postscript formats are supported.

Acknowledgements
****************

Several of the GNU plotting utilities were inspired by Unix plotting utilities.  A graph utility and various plot filters were present in the first releases of Unix from Bell Laboratories, going at least as far back as the Version 4 distribution (1973).  Most of the work on tying them together and breaking out device-dependent versions of libplot was performed by Lorinda Cherry.  By the time of Version 7 Unix (1979) and the subsequent Berkeley releases, the package consisting of graph, plot, spline, and several device-dependent versions of libplot was a standard Unix feature.  The first display device supported by the package was a Versatec storage scope.  By the early 1980's, supported devices included Tektronix storage scopes, 200dpi electrostatic printer/plotters from Versatec and Varian, pen plotters from Hewlett--Packard, and early graphics terminals.

In 1989, Rich Murphey wrote the first GNU versions of graph, plot, and spline, and the earliest documentation.  Richard Stallman further directed development of the programs and provided editorial support for the documentation. John Interrante, of the InterViews team at Stanford, generously provided the idraw Postscript prologue now included in libplot, and helpful comments.  The package as it stood in 1991 was distributed under the name `GNU graphics'.

In 1995 Robert Maier took over development of the package, and designed and wrote the current, maximally device-independent, standalone version of libplot.  He also rewrote graph from scratch, turning it into a real-time filter that would use the new library.  He fleshed out spline too, by adding support for splines in tension, periodicity, and cubic Bessel interpolation.

Most development work on ode was performed by Nick Tufillaro in 1978--1994, on a sequence of platforms that extended back to a PDP-11 running Version 4 Unix.  In 1997 Robert modified Nick's 1994 version to agree with GNU conventions on coding and command-line parsing, extended it to support the full set of special functions supported by gnuplot, and extended the exception handling.

Many other people aided the development of the plotting utilities package along the way.  The Hershey vector fonts now in libplot are of course based on the characters digitized in the mid to late 1960's by Allen V. Hershey.  Additional characters and/or marker symbols were taken from the SLAC Unified Graphics System developed by Robert C. Beach in the mid-1970's, and from the fonts designed by Thomas Wolff for Ghostscript.  The table-driven parser used in tek2plot was written at Berkeley in the mid-1980's by Edward Moy.  Arthur Smith, formerly of LASSP at Cornell, provided code for his xplot utility.  Ray Toy helped with the tick mark spacing code in graph and was the first to incorporate GNU getopt.  Peter Karnow of URW and Ken Turkowski of Apple developed the `sagitta' algorithm used in an extended form in libplot for drawing circular and elliptic arcs. Nelson Beebe exhaustively tested the package installation process.

Robert Maier wrote the documentation, which now incorporates Nick Tufillaro's ode manual.  Julie Sussmann checked over the documentation for style and clarity.