\input texinfo   @c -*-texinfo-*-
@setfilename plotutils.info
@settitle The Plotutils Package
@set VERSION 1.3

@tex
\hyphenation {Zapf-Ding-bats}
@end tex

@ifinfo
This file documents version @value{VERSION} of the GNU plotutils package.

Copyright @copyright{} 1989--1997 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.
@end ifinfo

@titlepage
@title The GNU Plotting Utilities
@subtitle Programs and functions for drawing and data plotting
@subtitle Version @value{VERSION}
@author {}
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1989--1997 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.
@end titlepage
@page

@node Top, Introduction, (dir), (dir)
@ifinfo
This is the documentation for version @value{VERSION} of the GNU
plotutils (plotting utilities) package.  The package consists of programs
and functions for data plotting and vector graphics.
@end ifinfo

@menu
* Introduction::        About the GNU plotutils package
* graph Examples::	Using GNU graph to plot datasets
* graph Invocation::	GNU graph command-line options
* Plot Filters::	Converting the output of graph to other formats
* libplot::             A library for device-independent 2-d vector graphics
* spline Examples::     Using GNU spline to perform interpolation
* spline Invocation::   GNU spline command-line options
* ode::			ode, a differential equation integrator
* Appendices::          Additional Information
@end menu

@node Introduction, graph Examples, Top, Top
@chapter The GNU Plotting Utilities

The GNU plotting utilities include programs for plotting two-dimensional
scientific data.  They are built on top of GNU @code{libplot}, @w{a
library} for device-independent two-dimensional vector graphics.  The
most important plotting programs are the programs collectively known as
@code{graph} (@code{graph-X}, @code{graph-ps}, @code{graph-fig},
@code{graph-tek}, and raw @code{graph}).  Each of the versions of
@code{graph} 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.  The versions of @code{graph} differ only in the display device
they produce output for.

@code{graph-X} pops up a window on an @w{X Window} System display, and
draws the plot @w{in it}.  @code{graph-ps} produces a plot in
encapsulated Postscript format that may be included in another document,
sent to a printer, or edited with the @code{idraw} drawing editor.
@code{graph-fig} produces output that may be displayed and edited with
the @code{xfig} drawing editor.  @code{graph-tek} produces output that
may be displayed on a Tektronix 4014 terminal or emulator.  Raw
@code{graph} produces output in a device-independent format, referred to
below as a GNU graphics metafile; it may be translated into other
formats.  When discussing the common features of these five programs, we
refer to them simply as @samp{graph}.

@code{graph} can read datasets in both ASCII and binary format, and
datasets in the `table' format produced by the plotting program
@code{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, @w{if any}, used
to connect points in a dataset.  The plotting of filled regions is
supported, as is the drawing of error bars.  @code{graph} provides full
support for multiplotting.  With a single invocation of @code{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.

The versions @code{graph-X}, @code{graph-tek}, and raw @code{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 @code{graph}
does not have to wait until the end of input to determine them.

Accompanying @code{graph} are five `plot filters' collectively called
@code{plot}.  They translate device-independent GNU graphics metafiles
(produced for example by raw @code{graph}) into the five just-mentioned
output formats.  Versions of @code{plot} include @code{plot2X},
@code{plot2ps}, @code{plot2fig}, @code{plot2tek}, and @code{plot2plot}.
These programs are useful if you wish to produce output in several
different formats while invoking @code{graph} only once.  They are also
useful if you wish to translate files in the traditional `plot(5)'
format produced by, for example, the non-GNU versions of @code{graph}
provided with some operating systems.  GNU metafile format is compatible
with the traditional `plot(5)' format.

Among the other GNU plotting utilities, @code{spline} does spline
interpolation of data.  It normally uses either cubic spline
interpolation or exponential splines in tension, but like @code{graph}
it can function as a real-time filter under some circumstances.
@code{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 @code{gnuplot}, which can plot functions but
not integrate ordinary differential equations.

Distributed as a part of this package is GNU @code{libplot}, the
function library mentioned above.  @w{It is} the function library for
device-independent two-dimensional vector graphics on which @code{graph}
and @code{plot} are based.  There are five versions of this library:
@code{libplotX}, @code{libplotps}, @code{libplotfig}, @code{libplottek},
and raw @code{libplot}.  The first four of these produce, respectively,
output for @w{X Window} System displays, output in encapsulated
Postscript format that may be included in another document, sent to a
printer, or edited with the @code{idraw} drawing editor, output that may
be displayed and edited with the @code{xfig} drawing editor, and output
that may be displayed on a Tektronix 4014 terminal or emulator.  Raw
@code{libplot} produces output in the device-independent GNU graphics
metafile format.

All versions of @code{libplot} provide the ability to draw such objects
as lines, open and closed polylines, arcs (both circular and elliptic),
circles and ellipses, markers, and text strings.  The filling of objects
other than text strings is supported (fill color, @w{as well} as pen
color, may be set arbitrarily).  @w{A wide} variety of line types and
marker symbols is supported.  The support for drawing text strings is
extensive.  @code{libplotX}, @code{libplotps}, and @code{libplotfig}
support the 35 standard Postscript fonts, and all three, together with
@code{libplottek}, 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 @w{c.@: 1967} by @w{Dr.@:
Allen V.} Hershey at the U.S. Naval Surface Weapons Center, which
includes many curious symbols, is built into @code{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).  @w{A
library} of 603 Japanese Kanji digitized by @w{Dr.@: Hershey} is built
into @code{libplot}.

The drawing editors @code{idraw} and @code{xfig} are not distributed along
with the GNU plotting utilities.  They are freely distributable, and you
may obtain them elsewhere (@pxref{Auxiliary Software}).

@node graph Examples, graph Invocation, Introduction, Top
@chapter The @code{graph} Utility

Each invocation of @code{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.  
@iftex
@xref{graph Invocation}, for documentation on all options.
@end iftex
The following sections explain how to use the most frequently used
options, by giving examples.

@menu
* Simple Examples::	Simple examples using graph
* Multiple Datasets::	Preparing a plot from more than one dataset
* Non-Square Plots::	Changing the aspect ratio of a plot
* Multiplotting::	Multiple plots on a single page
* Data Formats::	Reading binary and other data formats
@end menu

@node Simple Examples, Non-Square Plots, graph Examples, graph Examples
@section Simple examples using @code{graph}

By default, @code{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 @math{x} @w{and @math{y}}
coordinates of data points:

@example
0.0  0.0
1.0  0.2
2.0  0.0
3.0  0.4
4.0  0.2
5.0  0.6
@end example

@noindent
Data points do not need to be on different lines, nor do the @math{x}
and @math{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 one of the versions of @code{graph}, you
could do

@example
graph-ps ascii_data_file > plot.ps
@end example

@noindent
or equivalently

@example
graph-ps < ascii_data_file > plot.ps
@end example

@noindent
This will produce an encapsulated Postscript file @code{plot.ps}, which
you may include in another document, print, view, or edit with the
@code{idraw} drawing editor.  You may also do

@example
graph-fig < ascii_data_file > plot.fig
@end example

@noindent
if you wish to produce a file @code{plot.fig} that you may edit with the
the @code{xfig} drawing editor.

You may use @code{graph-X} instead of @code{graph-ps} or
@code{graph-fig} if you wish to @w{pop up} a window on an @w{X Window}
System display, and display the plot @w{in it}.  For that, you would do

@example
graph-X < ascii_data_file
@end example

@noindent
If you use @code{graph-X}, no output file will be produced; only a
window.  The window will close if you type @samp{q} or click your mouse
@w{in it}.

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

@example
graph-tek < ascii_data_file
@end example

@noindent
@code{xterm} normally emulates a VT100 terminal, but when this command
is issued from @w{within it}, @w{it will} @w{pop up} a second window
(@w{a `Tektronix} window') and draw the plot @w{in it}.  The Japanese
terminal emulator @code{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 @code{kermit}.

Of the five versions of @code{graph}, @code{graph-tek} and
@code{graph-X} may behave differently depending on the environment in
which they are invoked.  This refers to the values taken by the
@code{TERM} and @code{DISPLAY} environment variables, @w{in particular}.
For a discussion of the effects of the environment on @code{graph-tek}
and @code{graph-X}, @pxref{Environment}.  The following remarks apply to
plots drawn with any of the versions of @code{graph}.

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

@example
graph-ps -m 2 < ascii_data_file > plot.ps
@end example

@noindent
Here @samp{-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 @samp{-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 @emph{fill} the polygon bounded by the line (i.e., shade
it, or fill it with a solid color), you may use the @samp{-q} option.
For example,

@example
echo .1 .1 .1 .9 .9 .9 .9 .1 .1 .1 | graph-ps -C -m 1 -q 0.3 > plot.ps
@end example

@noindent
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 @samp{-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 @samp{-W} option.  For example, @samp{-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,

@example
graph-ps -S 3 0.1 < ascii_data_file > plot.ps
@end example

@noindent
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.
(@xref{Marker Symbols}.)  Symbols 1 through 31 are the same for all
versions of @code{graph}, 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.  @w{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,

@example
graph-ps -C -m -3 -S 4 < ascii_data_file > plot.ps
@end example

@noindent
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
@samp{-S} option, you may adjust the size of the circles.

@code{graph} will automatically generate abscissa (@w{i.e., @math{x}})
values for you if you use the @samp{-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 @samp{-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

@example
echo 0 1 0 | graph-ps -a > plot.ps
@end example

@noindent
produces exactly the same plot  as

@example
echo 0 0 1 1 2 0 | graph-ps > plot.ps
@end example

@code{graph} will plot data with error bars, if the @samp{-I e} option
is specified.  If it is, the dataset should consist of triples
(@math{x},@math{y},@i{error}) rather than pairs @math{(x,y)}.  @w{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 @samp{-S} option in the usual way.  The symbol
will be the same for each point in the dataset.  You may use the
@samp{-a} option in conjunction with @samp{-I e}, if you wish.  If you
do, the dataset should contain no abscissa (@w{i.e., @math{x}}) values.

By default the limits on the @math{x} and @math{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
@samp{-x} and @samp{-y} options.

@example
echo 0 0 1 1 2 0 | graph-ps -x -1 3 -y -1 2 > plot.ps
@end example

@noindent
will produce a plot in which the @math{x} axis extends from @minus{}1
@w{to 3}, and the @math{y} axis from @minus{}1 @w{to 2}.  By default,
@code{graph} tries to place about six numbered ticks on each axis.  By
including an optional third argument to either @samp{-x} or @samp{-y},
you may manually set the spacing of these ticks, also.  For example,
using @samp{-y -1 2 1} rather than @samp{-y -1 2} will produce a
@math{y} axis with labeled ticks at @minus{}1, 0, 1, and 2, rather than
at the locations that @code{graph} would choose by default.  @w{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 @samp{-l} option.  For
example, 

@example
echo 1 1 2 3 3 1 | graph-ps -l x > plot.ps
@end example

@noindent
will produce a plot in which the @math{x} axis is logarithmic, but the
@math{y} axis is linear.  To make both axes logarithmic, you would use
@samp{-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, @samp{-l x -x 1 9 2} will produce a plot in which the
@w{@math{x} axis} is logarithmic and extends from 1 @w{to 9}.  Labeled
ticks will be located at each integer multiple @w{of 2}, i.e., at 2, 4,
6, @w{and 8}.

You may label the @math{x} and @math{y} axes with the @samp{-X} and
@samp{-Y} options, respectively.  For example,

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

@noindent
will label the log axis in the preceding example.  By default the label
for the @math{y} axis, @w{if any}, will be rotated ninety degrees,
unless you use the @samp{--toggle-rotate-y-label} option.  You may
specify a `top label', or title for the plot, by using the @samp{-L}
option.  Doing, for example,

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

@noindent
will produce a plot with a title on top.  

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

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

@noindent
will produce a plot in which the font size of the @math{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 @samp{-X}, @samp{-Y},
and @samp{-L} options are drawn may be specified with the @samp{-F}
option.  For example, @samp{-F Times-Roman} will make the labels appear
in Times-Roman instead of the default font (which is Helvetica, for
versions of @code{graph} other than @code{graph-tek}).  Font names are
case-insensitive, so @samp{-F times-roman} will work equally well.
There are 51 fonts available @w{in all}.  This includes 35 Postscript
fonts (for all versions of @code{graph} other than @code{graph-tek}) and
16 Hershey fonts.  The Hershey fonts include HersheyCyrillic, for
Russian, and HersheyEUC, for Japanese.  For a discussion of the
available fonts, @pxref{Text Fonts}.

The format of the labels drawn with the @samp{-X}, @samp{-Y}, and
@samp{-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, @pxref{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 @samp{-g 0}, @samp{-g 1}, @samp{-g 2}, and @samp{-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, @samp{-g 2} is the default.  There is
also a @samp{-g 4} option, which yields a slightly different sort of
grid: @w{a pair} of axes that cross at the origin.  This last sort of grid
is useful if the @math{x} @w{or @math{y}} coordinates of the data points
you are plotting are both positive and negative.

@node Non-Square Plots, Multiple Datasets, Simple Examples, graph Examples
@section 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

@example
graph-ps -h .3 -w .6 -r .1 -u .1 < ascii_data_file > plot.ps
@end example

@noindent
Here the @samp{-h} and @samp{-w} options specify the height and width of
the plotting box, and the @samp{-r} and @samp{-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 is nominally square.  By default, the height
and width 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 @code{graph-X}, the graphics display is a square
window on an @w{X display}.  For @code{graph-ps}, it is a square region
centered on an 8.5@dmn{in} by 11@dmn{in} page, occupying the full width
of the page.  For @code{graph-fig}, it is a square region with edge
length 8.5@dmn{in}, in the upper left corner of an @code{xfig} display.
And for @code{graph-tek}, it is the square region occupying the left two
thirds of a Tektronix display.  (Tektronix displays are 1.5 times as
wide as they are high.)

In any of the versions of @code{graph}, changing the width of the
plotting box may have unforeseen consequences.  @w{A number} of command-line
options specify sizes or dimensions as fractions of the width of the
plotting box.  For example, @samp{-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 @samp{-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.

@node Multiple Datasets, Multiplotting, Non-Square Plots, graph Examples
@section 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.  @w{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
@emph{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.

@enumerate
@item color/monochrome
@item linemode 
@item linewidth
@item symbol type
@item symbol size
@item symbol font name
@item fill fraction
@end enumerate

@noindent
Color/monochrome (a choice of one or the other) is the simplest.  This
choice is toggled with the @samp{-C} option.  The `linemode' (i.e., line
style) specifies how the line segments joining successive points should
be drawn; it is specified with the @samp{-m} option.  Linemode #0 means
no linemode at all, for example.  `Linewidth' is self-explanatory; it is
specified with the @samp{-W} option. `Symbol type' and `symbol size',
which are specified with the @samp{-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.  @w{It is} set with
the @samp{--symbol-font-name} option, and is relevant only if @samp{-S}
is used to request such special plotting symbols. Finally, the polygonal
line joining the points in a dataset may be @emph{filled}, to create a
filled or shaded polygon.  The `fill fraction' is set with the @samp{-q}
option.  @w{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 @samp{-I e} option should occur on the command line before the file
name.  (The @samp{-I} option specifies the input format for the
following files.)

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

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

@noindent
The dataset in @code{file_1} will be plotted in line style #0, so
successive points will not be joined by lines.  But symbol #3 (an
asterisk) will be plotted at each point.  The dataset in @code{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
@samp{-C} on the command line turns off color for @code{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., @samp{-q} or @samp{-I}) before each file.
@w{In fact} the command line could also include such standard options as
@samp{-x} or @samp{-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

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

@noindent
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
@code{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

@example
graph-ps -m 3 file_1 > output.ps
@end example

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

@example
graph-ps file_1 file_2 @dots{} > output.ps
@end example

@noindent
without specifying linemode explicitly, the successive datasets read
from the files on the command line will appear in linemode #1, linemode
#2, @dots{}.  If you do not like this feature, you may turn it off, or
in general toggle it, by using the @samp{-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

@example
#m=-5,S=10
@end example

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

@node Multiplotting, Data Formats, Multiple Datasets, graph Examples
@section 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
@emph{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.

@code{graph} can draw multiplots consisting of an arbitrarily large
number of sub-plots.  When multiplotting, @code{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).

@example
graph-ps data_file_1 --reposition 0.35 0.35 0.3 data_file_2
@end example

@noindent
Here @code{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).  @w{A plot} is then prepared from @code{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.
(@w{That is}, @w{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.  @w{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
@samp{--blankout} option to adjust this parameter.  For example,
specifying @samp{--blankout 1.0} will make the blankout region for a
sub-plot coincide with its plotting box.  Specifying @samp{--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 (@samp{-m}, @samp{-S}, @samp{-x},
@samp{-y}, etc.) may be applied to each sub-plot separately.  The
options for a sub-plot should occur on the @code{graph} command line
immediately after the @samp{--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 @samp{--reposition} option, @w{if any}.

@node Data Formats, , Multiplotting, graph Examples
@section Reading binary and other data formats

By default, @code{graph} reads datasets in ASCII format.  But it can
also read datasets in binary (double precision floating point) format.
For this, the @samp{-I d} option must be specified.  There are two
advantages to using binary data: @w{1) @code{graph}} runs significantly
faster because the computational overhead for converting data from ASCII
to binary is eliminated, and @w{2) the} input files may be significantly
smaller than the ASCII format would be.  If you have very large
datasets, using binary format may reduce storage and runtime costs.

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

@example
@group
#include <stdio.h>
void write_point (double x, double y)
@{
  fwrite(&x, sizeof (double), 1, stdout);
  fwrite(&y, sizeof (double), 1, stdout);
@}
@end group
@end example

@noindent
You may plot data written this way by doing:

@example
graph-ps -I d < binary_data_file > plot.ps
@end example

@ifinfo
@noindent
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
quantity @code{MAXDOUBLE}, which is the largest possible double
precision floating point number.  On most machines this is approximately
1.8x10^308.
@end ifinfo
@tex
@noindent
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
quantity @code{MAXDOUBLE}, which is the largest possible double
precision floating point number.  On most machines this is
approximately $1.8\times10^{308}$.
@end tex

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

@example
graph-ps -I d binary_data_file -I a ascii_data_file > plot.ps
@end example

@noindent
will read @code{binary_data_file} in @samp{d} (binary double precision)
format, and @code{ascii_data_file} in @samp{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 @code{graph} in ASCII, and use the @samp{-I e} option.

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

To sum up: there are four data formats, @samp{a} (normal ASCII),
@samp{e} (ASCII with error bars), @samp{d} (binary double precision),
and @samp{g} (the `table' format produced by @code{gnuplot}).  Input
files may be in any of these four formats.

@node graph Invocation, Plot Filters, graph Examples, Top
@section @code{graph} command-line options

The command-line options to @code{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 sections, because there are five sorts of option.  They are:

@iftex
@enumerate
@item
Options affecting an entire plot.  (@ref{Plot Options}.)
@item
Options affecting the reading and drawing of individual datasets within a plot.
(@ref{Dataset Options}.)
@item
Options for multiplotting (drawing several sub-plots within a plot).
(@ref{Multiplot Options}.)
@item
Options meaningful only for raw @code{graph}.
(@ref{Raw graph Options}.)
@item
Options requesting information (e.g., @samp{--help}).
(@ref{Info Options}.)
@end enumerate
@end iftex

@menu
* Plot Options::	Options affecting an entire plot
* Dataset Options::	Options affecting the reading and plotting of datasets
* Multiplot Options::	Options for drawing several plots at once
* Raw graph Options::	Options meaningful only for raw graph
* Info Options::	Options requesting information (e.g., ---help)
@end menu

@node Plot Options, Dataset Options, graph Invocation, graph Invocation
@subsection Plot options

The following options affect an entire plot.  They should appear on the
command line before the first filename.  They should appear at most once
on the command line, unless a multiplot is being drawn, in which case
they may appear after each @samp{--reposition}.

@table @samp
@item -f @var{font_size}
@itemx --font-size @var{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 box framing the
plot, to be @var{font_size}.
@item -F @var{font_name}
@itemx --font-name @var{font_name}
(String, default "Helvetica" except for @code{graph-tek}, for which
"HersheySerif" is the default.)  Set the font used for the axis and tick
labels, and for the plot title @w{(if any)}, to be @var{font_name}.  The
choice of font for the plot title may be overridden with the
@samp{--title-font-name} option (see below).  Font names are
case-insensitive.  For a list of available fonts, @pxref{Text Fonts}.
If the font is not available, the default font will be used.
@item -g @var{grid_style}
@itemx --grid-style @var{grid_style}
(Integer, default 2.)  Set the grid style for the plot to be
@var{grid_style}.  Grid styles 0 through 3 are progressively more fancy,
but style 4 is a somewhat different style.

@enumerate 0
@item no axes, tick marks or labels.
@item a pair of axes, with tick marks and labels.
@item box around plot, with tick marks and labels.
@item box around plot, with tick marks and labels; also grid lines.
@item axes intersect at the origin, with tick marks and labels.
@end enumerate

@item -h @var{height}
@itemx --height-of-plot @var{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 @var{height}.  @w{A value} of 1.0 will produce a plotting
box which fills the available area.  Note that the tick marks and labels
are outside the plotting box, so that values less than 1.0 are generally
used.
@item -K @var{clip_mode}
@itemx --clip-mode @var{clip_mode}
(Integer, default 1.) Set the clip mode for the plot to @var{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, @w{and 2}.  Clip @w{mode 0} means that a line segment joining two data
points will be plotted only if neither point is outside the plotting
box.  Clip @w{mode 1} means that it will be plotted if no more than one of
the two points is outside, and clip @w{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.
@item -L @var{top_label}
@itemx --top-label @var{top_label}
(String, default empty.)  Place the text string @var{top_label} above
the plot, as a plot title.  The string may include escape sequences
(@pxref{Text String Format}).  The @samp{--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
@samp{-F} option.  But this may be overridden with the
@samp{--title-font-name} option.
@item -l @var{x|y}
@itemx --toggle-log-axis @var{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.
@item -N @var{x|y}
@itemx --toggle-no-ticks @var{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, @w{and 4}.
@item -R @var{x|y}
@itemx --toggle-round-to-next-tick @var{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 @samp{-x} or
@samp{-y} options to set axis limits explicitly.
@item -r @var{right}
@itemx --right-shift @var{right}
(Float, default 0.2.)  Move the plot to the right by a fractional amount
@var{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.  @w{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.
@item -s
@itemx --save-screen
Save the screen. This option prevents @code{graph} from erasing the
previous contents of the display device.  This is meaningful only for
@code{graph-tek} and raw @code{graph}.  It may be employed to perform a
crude sort of multiplotting.
@item -T @var{tick_size}
@itemx --tick-size @var{tick_size}
(Float, default .02.) Set the fractional size of the tick marks on each
axis to be @var{tick_size}.  @w{A value} of 1.0 produces tick marks on the x
axis whose length is equal to the width of the plotting box.  @w{A negative}
@var{tick_size} will yield tick marks that extend outside the box,
rather than inside.  
@item -t
@itemx --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 @math{(y, x)}
pairs, and such options as @samp{-x} and @samp{-X} apply to the @math{y}
axis rather than the @w{@math{x} axis}.  If the @samp{-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.
@item -u @var{up}
@itemx --upward-shift @var{up}
(Float, default 0.2.)  Move the plot up by a fractional amount @var{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.
@w{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.
@item -w @var{width}
@itemx --width-of-plot @var{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 @var{width}.  @w{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.
@item -x [@var{lower_limit} [@var{upper_limit} [@var{spacing}]]]
@itemx --x-limits [@var{lower_limit} [@var{upper_limit} [@var{spacing}]]]
(Floats.) The arguments @var{lower_limit} and @var{upper_limit} specify
the limits of the @w{@math{x} axis}, and the optional argument
@var{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 @var{lower_limit} and @var{upper_limit} must be present if
@code{graph} is to act as a real-time filter.
@item -y [@var{lower_limit} [@var{upper_limit} [@var{spacing}]]]
@itemx --y-limits [@var{lower_limit} [@var{upper_limit} [@var{spacing}]]]
(Floats.)  The arguments specify the limits of the @math{y} axis, and
the spacing of labeled ticks along it, as for the @w{@math{x} axis} (see
above).  The arguments @var{lower_limit} and @var{upper_limit} must be
present if @code{graph} is to act as a real-time filter.
@item -X @var{x_label}
@itemx --x-title @var{x_label}
(String, default empty.)  Set the label for the @math{x} axis to be the text
string @var{x_label}.  The string may include escape sequences
(@pxref{Text String Format}).  The @samp{-F} and @samp{-f} options may
be used to specify the name of the font and the size of the font.
@item -Y @var{y_label}
@itemx --y-title @var{y_label}
(String, default empty.) Set the label for the @math{y} axis to be the
text string @var{y_label}.  The string may include escape sequences
(@pxref{Text String Format}).  The label will be rotated by ninety
degrees so that it is parallel to the axis, unless the
@samp{--toggle-rotate-y-label} option is used.  Some old @w{X Window} System
displays do not support rotated labels, and require the
@samp{--toggle-rotate-y-label} option.  The @samp{-F} and @samp{-f}
options may be used to specify the name of the font and the size of the
font.
@item --frame-color @var{name}
(String, default "black".)  Set the color used for drawing the plot
frame, and for drawing monochrome datasets @w{if any}, to be @var{name}.
@w{An unrecognized} name sets the color to the default.  For information
on what names are recognized, @pxref{Color Names}.
@item --frame-line-width @var{frame_line_width}
(Float, default @minus{}1.0.)  Set the width of lines in the plot frame,
as a fraction of the width of the display, to @var{frame_line_width}.
@w{A negative} value means that the default value for the line width
provided by the @code{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; @w{on others}, a zero-width line is
invisible).  @code{graph-tek} does not support drawing lines with other
than a default width.
@item --max-line-length @var{max_line_length}
(Integer, default 150.) Set the maximum length that the polygonal lines
joining datasets are allowed to grow to, before they are flushed to the
output device, to @var{max_line_length}.  Some display devices (e.g.,
old Postscript printers) cannot handle long polygonal lines, so that
this option must be employed.
@item --title-font-name @var{title_font_name}
(String, default "Helvetica" except for @code{graph-tek}, for which
"HersheySerif" is the default.)  Set the font used for the plot title
(`top label') to be @var{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 @samp{-F} option.  But the
@samp{--title-font-name} option may be used to override this.  Font
names are case-insensitive; for a list of available fonts, @pxref{Text
Fonts}.  If the font is not available, the default font will be
used. 
@item --title-font-size @var{title_font_size}
(Float, default 0.07.)  Set the size of the font for the top
label (`title'), as specified by the @samp{-L} option, to
@var{title_font_size}.  The size is expressed as a fraction of the size
of the plotting box.
@item --toggle-rotate-y-label
Position the label on the @math{y} axis (which is set with the @samp{-Y}
option) horizontally instead of vertically, or vice versa.  By default
the label is rotated, so that it is positioned parallel to the @math{y}
axis.  But some display devices (e.g., old @w{X Window} System displays)
cannot handle rotated text.
@item --toggle-switch-axis-end @var{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.,
@samp{--toggle-switch-axis-end x} will cause the @math{y} axis to appear
on the right of the plot rather than the left.  (The left end is the
default.)  Similarly, @samp{--toggle-switch-axis-end y} will cause the
@w{@math{x} axis} to appear at the top of the plot rather than the
bottom.  Note that if the @w{@math{x} axis} appears at the top, no plot
title will be drawn (since there will be no room).
@end table

@node Dataset Options, Multiplot Options, Plot Options, graph Invocation
@subsection 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.

@table @samp
@item -I @var{data-format}
@itemx --input-format @var{data-format}
This specifies which format the subsequent input file(s) are in.

@table @samp
@item a  
ASCII format.  Each input file consists of pairs of floating point
numbers, interpreted as the @math{x} @w{and @math{y}} coordinates of the
data points in a dataset.  The @math{x} @w{and @math{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), @w{it is} interpreted as the end of a dataset, and
the beginning of the next.
@ifinfo
@item d
Double precision binary format.  Each input file is a sequence of double
precision floating point numbers, interpreted as forming pairs
(@math{x},@math{y}).  Successive datasets are separated by a single
occurrence of the quantity @code{MAXDOUBLE}, which is the largest
possible double precision floating point number.  On most machines this
is approximately 1.8x10^308.
@end ifinfo
@tex
@item d
Double precision binary format.  Each input file is a sequence of double
precision floating point numbers, interpreted as forming pairs
(@math{x},@math{y}).  Successive datasets are separated by a single
occurrence of the quantity @code{MAXDOUBLE}, which is the largest
possible double precision floating point number.  On most machines this
is approximately $1.8\times10^{308}$.
@end tex
@item e
ASCII format, including error bars.  Similar to @samp{a} format, except
that triples (@math{x},@math{y},@i{error}) appear instead of pairs
@math{(x,y)}.
@item g
The `table' format produced by the @code{gnuplot} plotting program.
@end table

@item -a [@var{step_size} [@var{lower_limit}]]
@itemx --auto-abscissa [@var{step_size} [@var{lower_limit}]]
(Floats, defaults 1.0 and 0.0.) Automatically generate abscissa
(@math{x}) values.  Irrespective of data format (`a', `d', or `e'), this
option specifies that the abscissa (@math{x}) values are missing: the
dataset(s) to be read contain only ordinate (@math{y}) values.  The
difference between successive @w{@math{x} values} will be
@var{step_size}, and the first @w{@math{x} value} will be
@var{lower_limit}.  To return to reading abscissa values from the input
you may specify @samp{-a 0}, which disables automatic generation of the
abscissa and returns @var{step_size} and @var{lower_limit} to their
default values.
@item -B
@itemx --toggle-auto-bump
By default the linemode (set with @samp{-m}, see below) is `bumped'
(incremented by unity) at the beginning of each new dataset.  This
option toggles auto-bumping: @w{it turns} it off if it was on, and on if
it was off.
@end table

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.

@table @samp
@item -m @var{line_mode}
@itemx --line-mode @var{line_mode}
(Integer, default 1.) @var{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
@var{line_mode} is as follows.

@enumerate 0
@item no line at all (points are disconnected)
@item solid
@item dotted
@item dotdashed
@item shortdashed
@item longdashed
@end enumerate

Thereafter (i.e., for @var{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 @samp{-C} option), the
interpretation of linemodes 0 through 5 is instead

@enumerate 0
@item no line at all (points are disconnected)
@item red, solid
@item green, solid
@item blue, solid
@item magenta, solid
@item cyan, solid
@end enumerate

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.  @w{A
negative} linemode indicates that no line should be drawn, but that the
plotting symbol, @w{if any} (see below), should be in the color of the
corresponding positive linemode.
@item -S [@var{symbol_number} [@var{symbol_size}]]
@itemx --symbol [@var{symbol_number} [@var{symbol_size}]]
(Integer and float, defaults 0 and 0.03.) Draw a marker symbol at each
data point.  @var{symbol_number} specifies the symbol type, and
@var{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 @samp{-m} option to
specify a negative linemode (see above).  The following table lists the
first few marker symbols.

@enumerate 0
@item no symbol at all
@item dot
@tex
($\thinspace\cdot\thinspace$)
@end tex
@item plus (@math{+})
@item asterisk (@math{*})
@item circle
@tex
($\circ$)
@end tex
@item cross
@tex
($\times$)
@end tex
@end enumerate

Marker symbols 0 through 31 are furnished by the @code{libplot} graphics
library.  @xref{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 @samp{--symbol-font-name} option (see below).
@item -W @var{line_width}
@itemx --line-width @var{line_width}
(Float, default @minus{}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 @var{line_width}.  @w{A negative} value means that the
default value for the line width provided by the @code{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;
@w{on others}, a zero-width line is invisible).  @code{graph-tek} does
not support drawing lines with other than a default width.
@item -q @var{fill_fraction}
@itemx --fill-fraction @var{fill_fraction}
(Float, default @minus{}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 @var{fill_fraction}.  @w{A solid}
polygon (i.e., one filled with the `pen color' used for drawing the line
segments) is obtained by choosing @var{fill_fraction}=1.0.  The interior
of the polygon will be white if @var{fill_fraction}=0.0.  The polygon
will be unfilled (transparent) if @var{fill_fraction} is negative.
@w{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 @cite{Postscript Language Reference Manual}.  @w{In
@code{graph-tek}}, the @samp{-q} option has no effect.
@item -C
@itemx --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 @samp{-m} option above.
@item --symbol-font-name @var{symbol_font_name}
(String, default "ZapfDingbats" for all versions of @code{graph} except
for @code{graph-tek}, for which it is "HersheySerif".)  Set the symbol
font, from which plotting symbols numbered 32 and higher are selected,
to be @var{symbol_font_name}.  Font names are case-insensitive.
For a list of available fonts, @pxref{Text Fonts}.

@end table

@node Multiplot Options, Raw graph Options, Dataset Options, graph Invocation
@subsection Multiplot options

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

@table @samp
@item --reposition @var{x} @var{y} @var{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 @var{size},
with lower left corner (@var{x},@var{y}).  This is in the coordinate
frame in which the physical display is a unit square with lower left
corner (0,0).
@item --blankout @var{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 @var{blankout_fraction}=1.0, the region covered by
the plot's plotting box will be cleared.  If
@var{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 @code{graph-tek} does not
know how to clear regions.
@end table

@node Raw graph Options, Info Options, Multiplot Options, graph Invocation
@subsection Raw @code{graph} options

The following options are meaningful for raw @code{graph} only.  They
should appear on the command line before any filenames, since they
affect the output of the plot (or multiplot) as a whole.

@table @samp
@item -O
@itemx --ascii-output
Output the portable (ASCII) version of GNU metafile format, rather than a
binary version (the default).
@item -h
@itemx --high-byte-first
@itemx -l
@itemx --low-byte-first
These options force @code{graph} to use the specified byte order when
writing out a file in the binary version of GNU metafile format.  By default
the byte order is host-dependent.
@end table

@node Info Options, , Raw graph Options, graph Invocation
@subsection Informational options

The following options request information.

@table @samp
@item --help
Print a list of command-line options, and then exit.
@item --help-fonts
Print a list of available fonts, and then exit.  The list will depend on
which version of @code{graph} is being used.  @code{graph-X},
@code{graph-ps}, and @code{graph-fig} each support the 35 standard
Postscript fonts.  All three, and @code{graph-tek}, support a set of 16
Hershey vector fonts.  Raw @code{graph} in principle supports any font,
since its output must be translated to other formats with @code{plot}.
@item --version
Print the version of @code{graph} and the plotting utilities package,
and exit.
@end table

@node Plot Filters, libplot, graph Invocation, Top
@chapter The Plot Filters

@menu
* Plot Filter Invocation::	How to use a plot filter
* Plot Filter Options::		Command-line options
@end menu

@node Plot Filter Invocation, Plot Filter Options, Plot Filters, Plot Filters
@section Examples of the use of a plot filter

The GNU plot filters (@code{plot2X}, @code{plot2ps}, @code{plot2fig},
@code{plot2tek}, and @code{plot2plot}, collectively called @code{plot}),
translate GNU graphics metafiles to other formats.  Graphics metafiles
are produced by raw @code{graph} and by raw @code{libplot}.  The
metafile format is a device-independent format for storage of graphic
data.  By default, it is a binary rather than an ASCII format
(@pxref{Metafiles}).

The plot filters, like raw @code{graph} and the metafile format itself,
are 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 @math{x} and @math{y}
coordinates in an ASCII file, you may use raw @code{graph} as follows:

@example
graph < ascii_data_file > test.plot
@end example

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

@example
echo 0 0 1 1 2 0 | spline | graph > test.plot
@end example

@noindent
To display any such plot on an @w{X Window} System display, you
would do

@example
plot2X < test.plot
@end example

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

@example
plot2ps < test.plot | lpr
@end example

@noindent
To edit the plot with the @code{idraw} drawing editor, you would do

@example
@group
plot2ps < test.plot > test.ps
idraw test.ps
@end group
@end example

@noindent
And to edit it with the @code{xfig} drawing editor, you would do

@example
@group
plot2fig < test.plot > test.fig
xfig test.fig
@end group
@end example

Of the five versions of @code{plot}, @code{plot2tek} and @code{plot2X}
may behave differently depending on the environment in which they are
invoked.  This refers to the values taken by the @code{TERM} and
@code{DISPLAY} environment variables, @w{in particular}.  For a
discussion of the effects of the environment on @code{plot2tek} and
@code{plot2X}, @pxref{Environment}.

@node Plot Filter Options, , Plot Filter Invocation, Plot Filters
@section Plot filter command-line options

The command-line options to the plot filters (@code{plot2X},
@code{plot2ps}, @code{plot2fig}, @code{plot2tek}, and @code{plot2plot},
collectively called @code{plot}) are listed below.  There are four sorts
of option:

@enumerate
@item
Options specifying the type of GNU metafile format the input is in.
@item
Options meaningful only for @code{plot2plot}, which outputs GNU metafile
format.
@item
Options setting initial values of drawing parameters.
@item
Options requesting information (e.g., @samp{--help}).
@end enumerate

@noindent
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 @w{name @samp{-}} is
specified, the standard input is read.

The following options specify the type of GNU metafile format the input
is in.  There are actually two types of GNU metafile format: portable
(ASCII) and binary (the default).  The binary format is
machine-dependent; it depends on the byte order of the unformatted,
signed, two-byte integer coordinates contained in plot commands.  The
@samp{-h} and @samp{-l} options specify this order explicitly.  If the
order is not specified, the plot filters attempt to determine the byte
order from commands early in the metafile, but the method is heuristic
and not foolproof.

@table @samp
@item -I
@itemx --ascii-input
Specifies that the input is in the portable (ASCII) version of GNU
metafile format, rather than a binary version (the default).  The
portable version is produced by raw @code{graph} when the @samp{-O}
option is used.
@item -h
@itemx --high-byte-first
This option specifies that the high-order byte of each signed, two-byte
integer occurs first in the metafile.  It disables determination of byte
order from the metafile itself.
@item -l
@itemx --low-byte-first
This option specifies that the low-order byte of each signed, two-byte
integer occurs first in the metafile.  It disables determination of byte
order from the metafile itself.
@end table

The following option is meaningful only for @code{plot2plot}, which
outputs a graphics metafile.

@table @samp
@item -O
@itemx --ascii-output
Output the portable (ASCII) version of GNU metafile format, rather than
a binary version (the default).
@end table

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

@table @samp
@item -f @var{font_size}
@itemx --font-size @var{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
@var{font_size}.
@item -F @var{font_name}
@itemx --font-name @var{font_name}
(String, default "Helvetica" except for @code{graph-tek}, for which
"HersheySerif" is the default.)  Set the font initially used for text
(i.e., for `labels') to @var{font_name}.  Font names are case-insensitive.
For a list of available fonts, @pxref{Text Fonts}.
@item -W @var{line_width}
@itemx --line-width @var{line_width}
(Float, default @minus{}1.0.)  Set the width of lines, as a fraction of
the width of the display, to @var{line_width}.  @w{A negative} value
means that the default value provided by the @code{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).  @code{plot2tek} does not
support drawing lines with other than a default width.
@item --pen-color @var{name}
(String, default "black".)  Set the pen color to be @var{name}.  An
unrecognized name sets the pen color to the default.  For information on
what color names are recognized, @pxref{Color Names}.
@end table

The following options request information.

@table @samp
@item --help
Print a list of command-line options, and then exit.
@item --help-fonts
Print a list of available fonts, and then exit.  The list will depend on
which version of @code{plot} is being used.  @code{plot2X},
@code{plot2ps}, and @code{plot2fig} each support the 35 standard
Postscript fonts.  All three, and @code{plot2tek}, support a set of 16
Hershey vector fonts.  @code{plot2plot} in principle supports any font,
since its output must be translated to other formats by a later
invocation of @code{plot}.
@item --version
Print the version of @code{plot} and the plotting utilities package, and
exit.
@end table

@node libplot, spline Examples, Plot Filters, Top
@chapter @code{libplot}, a Function Library

GNU @code{libplot} is a library of functions for device-independent
two-dimensional vector graphics.  There are functions for drawing lines,
open and closed polylines, arcs (both circular and elliptic), circles
and ellipses, markers, and text strings.  The filling of objects other
than text strings is supported (fill color, @w{as well} as pen color,
may be set arbitrarily).

There are five versions of @code{libplot}, which differ in the display
device they produce output for.

@itemize @bullet
@item 
@code{libplotX}.  This version pops up a window on an @w{X Window}
System display, and draws the graphics in it.  (The
window will close if you type @samp{q} or click your mouse @w{in it}.)
@item 
@code{libplotps}. This version produces Postscript output.  @w{It is} in EPS
(encapsulated Postscript) format, so it may be included in another
document.  The output may be edited with the @code{idraw}
drawing editor.
@item 
@code{libplotfig}.  This version produces output in Fig format, which
may be edited with the @code{xfig} drawing editor.  The @code{xfig}
editor will export drawings in various other formats for inclusion in
documents.
@item
@code{libplottek}.  This version produces output in Tektronix 4014
format, which may be displayed on any Tektronix 4014 emulator.  Such an
emulator is built into @code{xterm}, the @w{X Window} System terminal
emulation program.  The DOS version of @code{kermit} also includes such
an emulator.
@item
Raw @code{libplot}.  This version produces output in GNU metafile format,
which is an extended version of the `plot(5)' format found on some
other operating systems.  It may be translated to other formats with the
GNU plot filters.  (@xref{Plot Filters}.)
@end itemize

The functions in these libraries behave identically, so far as the
caller knows.  So a given graphics application may be linked with any of
them, and will still function.  There are a handful of external
variables that distinguish among the libraries, but the casual
programmer does not need to know about them.

Of the libraries, @code{libplotX}, @code{libplottek}, and raw
@code{libplot} are real-time.  This means that graphics are drawn, or
written to a file, as the graphics functions are called.
@code{libplotps} and @code{libplotfig} are not real-time, since their
output files can only be constructed after all functions have been
called.  For @code{libplotps} this is because the output file must
contain a `bounding box' line.  For @code{libplotfig} it is because
definitions of nonstandard colors, @w{if any}, must be placed at the
head of the output file.

By convention the physical `graphics display' drawn in by each of the
libraries is square.  For example, @code{libplotX} @w{pops up} a square
window and draws graphics in it.  Actually, the programmer specifies the
coordinates of graphical objects in a `user frame', which is not the
same as the device frame.  The two frames are related by an arbitrary,
user-specifiable, affine coordinate transformation.

@menu
* Programming::		Programming with libplot: An overview
* Functions::		A list of functions contained in libplot
* Environment::		Environment variables and X resources
@end menu

@node Programming, Functions, libplot, libplot
@section Programming with @code{libplot}

The source code for any graphics application that calls @code{libplot}
functions, if written in C, should contain the lines

@example
@group
#include <stdio.h>
#include <plot.h>
@end group
@end example

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

To link your application with any of the versions of @code{libplot}, you
would use the appropriate @samp{-l} option(s) on the command line when
compiling it.  For example, you would use @samp{-lplotps -lm} to link
with @code{libplotps}, @samp{-lplotfig -lm} to link with
@code{libplotfig}, and @samp{-lplottek -lm} to link with
@code{libplottek}.  To link with @code{libplotX}, you would use

@example
-lplotX -lXaw -lXmu -lXt -lX11 -lm
@end example

@noindent
(or perhaps @samp{-lplotX -lXm -lXt -lX11 -lm}, @samp{-lplotX -lXm -lXt
-lX11 -lm -lc -lgen}, or @samp{-lplotX -lXm -lXt -lX11 -lm -lc -lPW}, on
systems that provide Motif widgets instead of Athena widgets).  @w{To
link} with raw @code{libplot}, you would simply use @samp{-lplot}.

Before drawing any objects or calling any of the other @code{libplot}
functions, your application should call the @code{libplot} function
@code{openpl}.  Before exiting, and after all other @code{libplot}
calls, it should call @code{closepl}.  @w{A given} application may
contain any number of @code{openpl}@dots{}@code{closepl} pairs.  

By default, applications linked with versions of @code{libplot} other
than @code{libplotX} write graphics to standard output. The output
stream to which plotting commands are directed, in versions other than
@code{libplotX}, may be set by calling @code{outfile}.  The
@code{outfile} function may only be called outside an
@code{openpl}@dots{}@code{closepl} pair.

In non-GNU versions of @code{libplot}, an application is expected to
call the @code{space} function immediately after calling @code{openpl},
to set the rectangular region (in user coordinates) that will be mapped
to the graphics display (@w{by convention}, square).  GNU @code{libplot}
includes @code{space}, and also an extended version (@code{space2}),
which allows the user to specify a parallelogram-shaped region rather
than a rectangular region.  So an arbitrary affine transformation from
the user frame to the device frame may be specified, immediately after
calling @code{openpl}.  This affine transformation may be updated, if
desired, by calling @code{fconcat}.  The @code{fconcat} function will
`concatenate' (i.e., compose) this transformation with any specified
affine map.  This sort of concatenation is a capability familiar from,
for example, Postscript.

GNU @code{libplot} also provides an application with the ability to
maintain a Postscript-style stack of drawing states, i.e., graphics
contexts.  @w{A drawing} state 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 user to device coordinates.  The state of any uncompleted
polyline object @w{(if any)} is included @w{as well}, since polylines may be
drawn incrementally, one line segment at a time.  The current drawing
state may be pushed onto the stack of drawing states by calling
@code{savestate}, and popped off by calling @code{restorestate}.

@node Functions, Environment, Programming, libplot
@section The functions in @code{libplot}: A detailed listing

The functions in GNU @code{libplot} are subdivided into the four sets
tabulated below.

@iftex
@enumerate
@item
Setup functions, e.g., @code{openpl}.
@item
Functions that set or affect drawing attributes.
@item
Functions that draw objects.
@item
Functions affecting the map from user to device coordinates.
@end enumerate
@end iftex

Note that many functions come in two versions: integer and double
precision floating point.  Internally, @code{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 @w{letter @samp{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
@samp{rel}.

Currently, only a few functions have meaningful return values.

@menu
* Setup Functions::	Functions that initialize and close the display device
* Attribute Functions::	Functions that affect drawing attributes
* Drawing Functions::	Functions that draw objects
* Mapping Functions::	Functions affecting the user -> device coordinate map
@end menu

@node Setup Functions, Attribute Functions, Functions, Functions
@subsection Setup functions

@table @asis
@item FILE *@t{outfile} (FILE *@var{fp});
@t{outfile}, which must be called outside a @t{openpl}@dots{}@t{closepl}
pair, directs all graphics output to the stream (i.e., open file)
@var{fp}.  The previous output stream is returned.  The default output
stream is stdout.  @t{outfile} has no effect in @code{libplotX}, which
draws graphics directly on an @w{X Window} System display.
@item int @t{openpl} ();
@t{openpl} opens the display device.  Depending on the version of
@code{libplot}, it may write initialization commands to the output
stream.
@item int @t{erase} ();
@t{erase} is called to erase all objects from the graphics display,
e.g., before a new plot is drawn.  This is important only for
@code{libplottek} and raw @code{libplot}.
@item int @t{space} (int @var{x0}, int @var{y0}, int @var{x1}, int @var{y1});
@itemx int @t{fspace} (double @var{x0}, double @var{y0}, double @var{x1}, double @var{y1});
@t{space} and @t{fspace} take two pairs of arguments, specifying
the positions of the lower left corner and upper right corner of the
display device, in user coordinates.  In other words, calling
@t{space} or @t{fspace} sets the affine transformation from user
coordinates to device coordinates.
@item int @t{space2} (int @var{x0}, int @var{y0}, int @var{x1}, int @var{y1}, int @var{x2}, int @var{y2});
@itemx int @t{fspace2} (double @var{x0}, double @var{y0}, double @var{x1}, double @var{y1}, double @var{x2}, double @var{y2});
@t{space2} and @t{fspace2} are extended versions of @t{space}
and @t{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 display device.
@item int @t{closepl} ();
@t{closepl} closes the display device.  In versions of @code{libplot}
that do not do real-time plotting (i.e., @code{libplotps} and
@code{libplotfig}), it writes the plotted objects to the output stream.
@end table

@node Attribute Functions, Drawing Functions, Setup Functions, Functions
@subsection Attribute-setting functions

The following are the @code{libplot} functions that set drawing
attributes, or save and restore them.

@table @asis
@item int @t{capmod} (char *@var{s});
@t{capmod} sets the cap mode for all polylines subsequently drawn on the
graphics display (by repeated calls to @t{cont} or @t{fcont}).
Recognized modes are "butt" (the default), "round", and "projecting".
This function has no effect in @code{libplottek} or (currently) in
@code{libplotps}.
@item int @t{color} (int @var{red}, int @var{green}, int @var{blue});   
@t{color} is a convenience function.  Calling @t{color} is equivalent to
calling both @t{pencolor} and @t{fillcolor}, to set both the the pen
color and fill color of all objects subsequently drawn on the graphics
display.
@item int @t{colorname} (char *@var{name});
@t{colorname} is a convenience function.  Calling @t{colorname} is
equivalent to calling both @t{pencolorname} and @t{fillcolorname}, to
set both the the pen color and fill color of all objects subsequently
drawn on the graphics display.
@item int @t{fill} (int @var{level});
@t{fill} sets the fill fraction for all subsequently drawn objects.
@w{A value} @w{of 0} for @var{level} indicates that objects should be
unfilled, or transparent.  This is the default.  @w{A value} in the
range @t{0x0001}@dots{}@t{0xffff}, i.e., 1@dots{}65535, indicates that
objects should be filled.  @w{A value} @w{of 1} signifies 100% filling
(the fill color will simply be the color specified by calling
@t{fillcolor} or @t{fillcolorname}).  If @var{level}=@t{0xffff}, the
fill color will be white.  Values between @t{0x0001} and @t{0xffff} are
interpreted as specifying a desaturation, or gray level.  @t{0x8000}
specifies 50% filling (the fill color will be intermediate between the
color specified by calling @t{fillcolor} or @t{fillcolorname}, and
white).  @code{libplottek} does not support filling.

If the object to be filled is a self-intersecting polyline, the
`even-odd rule' will be applied to determine which points are inside,
i.e., which of the regions bounded by the polyline should be filled.
The even-odd rule is explained in the @cite{Postscript Language
Reference Manual}.
@item int @t{fillcolor} (int @var{red}, int @var{green}, int @var{blue});   
@t{fillcolor} sets the fill color of all objects subsequently drawn on
the graphics display, using a 48-bit RGB color model.  The arguments
@var{red}, @var{green} and @var{blue} specify the red, green and blue
intensities of the fill color.  Each is an integer in the range
@t{0x0000}@dots{}@t{0xffff}, i.e., 0@dots{}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 @t{fill}.  @code{libplottek} does not
support filling.
@item int @t{fillcolorname} (char *@var{name});
@t{fillcolorname} sets the fill color of all objects subsequently drawn
on the graphics display to be @var{name}.  For information on what color
names are recognized, @pxref{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 @t{fill}.
@code{libplottek} does not support filling.
@item int @t{fontname} (char *@var{font_name});
@itemx double @t{ffontname} (char *@var{font_name});
@t{fontname} and @t{ffontname} take a single case-insensitive string
argument, @var{font_name}, specifying the name of the font to be used
for all text strings subsequently drawn on the display device.  (The
font for plotting strings is fully specified by calling @t{fontname},
@t{fontsize}, and @t{textangle}.)  The default font name depends on the
version of @code{libplot}.  @w{It is} "Helvetica" for all versions except
@code{libplottek}, for which it is "HersheySerif".  If the argument
@var{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
version of @code{libplot}; for a list of available fonts, @pxref{Text
Fonts}.  The size of the font in user coordinates is returned, except in
raw @code{libplot}, in which the return value is currently zero.
@item int @t{fontsize} (int @var{size});
@itemx double @t{ffontsize} (double @var{size});
@t{fontsize} and @t{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 display device.  (The font for plotting
strings is fully specified by calling @t{fontname}, @t{fontsize}, and
@t{textangle}.)  The size of the font in user coordinates is returned,
except in raw @code{libplot}, in which the return value is currently
zero.  @w{A negative} value for @var{size} sets the size to a default
value, which is device-dependent.
@item int @t{joinmod} (char *@var{s});
@t{joinmod} sets the join mode for all polylines subsequently drawn on
the graphics display (by repeated calls to @t{cont} or @t{fcont}).
Recognized modes are "miter" (the default), "round", and "bevel".  This
function has no effect in @code{libplottek} or (currently) in
@code{libplotps}.
@item int @t{linemod} (char *@var{s});
@t{linemod} takes a single string argument @var{s} containing the name
of the linemode (i.e., line style) desired.  The names supported are
"disconnected", "solid", "dotted", "dotdashed", "shortdashed", and
"longdashed".  @w{A `disconnected'} polyline 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:

@example
@group
"solid"             --------------------------------
"dotted"            - - - - - - - - - - - - - - - - 
"dotdashed"         -----------  -  -----------  -  
"shortdashed"       --              --              
"longdashed"        -------         -------         
@end group
@end example

@item int @t{linewidth} (int size);
@itemx int @t{flinewidth} (double size);
@t{linewidth} and @t{flinewidth} set the width, in the user frame, of
all lines, polylines, arcs, circles, and ellipses subsequently drawn on
the graphics display.  @w{A negative} value means that a default width
should be used.  This default width 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;
@w{on others}, a zero-width line is invisible).  @code{libplottek} does
not support drawing with other than a default width.
@item int @t{pencolor} (int @var{red}, int @var{green}, int @var{blue});   
@t{pencolor} sets the pen color of all objects subsequently drawn on the
graphics display, using a 48-bit RGB color model.  The arguments
@var{red}, @var{green} and @var{blue} specify the red, green and blue
intensities of the pen color.  Each is an integer in the range
@t{0x0000}@dots{}@t{0xffff}, i.e., 0@dots{}65535.  The choice (0, 0, 0)
signifies black, and the choice (65535, 65535, 65535) signifies white.
@item int @t{pencolorname} (char *@var{name});
@t{pencolorname} sets the pen color of all objects subsequently drawn on
the graphics display to be @var{name}.  For information on what color
names are recognized, @pxref{Color Names}.  Unrecognized colors are
interpreted as "black".
@item int @t{restorestate} ();
@t{restorestate} pops the current drawing state off the stack of drawing
states.  The drawing state consists largely of @code{libplot}'s drawing
parameters, which are set by the `attribute functions'.  So @w{popping
off} the drawing state restores the drawing parameters to values they
previously had.  The state of an uncompleted polyline object, @w{if
any}, is regarded as part of the drawing state.  For this reason,
calling @t{restorestate} automatically calls @t{endpoly} to terminate
the polyline under construction.
@item int @t{savestate} ();
@t{savestate} pushes the current drawing state onto the stack of drawing
states.  The drawing state consists largely of @code{libplot}'s drawing
parameters, which are set by the `attribute functions'.  The state
of an uncompleted polyline object, @w{if any}, is regarded as part of
the drawing state.  That is because polylines may be drawn
incrementally, one line segment at a time.  When a drawing state is
returned to, the polyline in progress may be continued.
@item int @t{textangle} (int @var{angle});  
@itemx double @t{ftextangle} (double @var{angle});  
@t{textangle} and @t{ftextangle} take one argument, which specifies the
angle in degrees counterclockwise from the @math{x} (horizontal) axis in
the user frame, for the text strings subsequently drawn on the display
device.  The default angle is zero.  (The font for plotting strings is
fully specified by calling @t{fontname}, @t{fontsize}, and
@t{textangle}.)  The size of the font for plotting strings, in user
coordinates, is returned, except in raw @code{libplot}, in which the
return value is currently zero.

@end table

@node Drawing Functions, Mapping Functions, Attribute Functions, Functions
@subsection Object-drawing functions

The following are the @code{libplot} functions that draw objects (lines,
open and closed polylines, points, arcs, circles, ellipses, marker
symbols, and text) on a graphics display.

@table @asis
@item int @t{alabel} (int @var{horiz_justify}, int @var{vert_justify}, char *@var{s});
@itemx double @t{falabel} (int @var{horiz_justify}, int @var{vert_justify}, char *@var{s});
@t{alabel} and @t{falabel} take three arguments @var{horiz_justify},
@var{vert_justify}, and @var{s}, and plot the text string @var{s} as an
`adjusted label', i.e., according to the adjustments specified in
@var{horiz_justify} and @var{vert_justify}.  @var{horiz_justify} is
equal to @samp{l}, @samp{c}, or @samp{r} for left, center or right
justification, relative to the current graphics cursor position.
@var{vert_justify} is equal to @samp{b}, @samp{x}, @samp{c}, or @samp{t}
for placing the bottom, baseline, center or top of the string even with
the graphics cursor position.  The cursor position 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 be plotted at a
nonzero angle, if @code{textangle} has been called.  The string may
contain escape sequences of various sorts (@pxref{Text String Format}),
though it should not contain line feeds or carriage returns.  @w{In
fact} it should include only printable characters, from the byte ranges
@t{0x20}@dots{}@t{0x7e} and @t{0xa0}@dots{}@t{0xff}.  The width of the
string in user coordinates is returned, except in raw @code{libplot}, in
which the return value is currently zero.
@item int @t{arc} (int @var{x}, int @var{y}, int @var{x0}, int @var{y0}, int @var{x1}, int @var{y1});
@itemx int @t{farc} (double @var{x}, double @var{y}, double @var{x0}, double @var{y0}, double @var{x1}, double @var{y1});
@itemx int @t{arcrel} (int @var{x}, int @var{y}, int @var{x0}, int @var{y0}, int @var{x1}, int @var{y1});
@itemx int @t{farcrel} (double @var{x}, double @var{y}, double @var{x0}, double @var{y0}, double @var{x1}, double @var{y1});
@t{arc} and @t{farc} take six arguments specifying the coordinates of
the center (@var{x}, @var{y}), beginning (@var{x0}, @var{y0}), and end
(@var{x1}, @var{y1}) of a circular arc.  The graphics cursor location
becomes (@var{x}, @var{y}).  @t{arcrel} and @t{farcrel} are similar to
@code{arc} and @code{farc}, but use cursor-relative coordinates.
@item int @t{box} (int @var{x1}, int y@var{1}, int @var{x2}, int @var{y2});
@itemx int @t{fbox} (double @var{x1}, double @var{y1}, double @var{x2}, double @var{y2});
@itemx int @t{boxrel} (int @var{x1}, int y@var{1}, int @var{x2}, int @var{y2});
@itemx int @t{fboxrel} (double @var{x1}, double y@var{1}, double @var{x2}, double @var{y2});
@t{box} and @t{fbox} take four arguments specifying the lower left
corner (@var{x1}, @var{y1}) and upper right corner (@var{x2}, @var{y2})
points of a `box', or rectangle.  The graphics cursor is moved to
(@var{x2}, @var{y2}).  @t{boxrel} and @t{fboxrel} are similar to @t{box}
and @t{fbox}, but use cursor-relative coordinates.
@item int @t{circle} (int @var{x}, int @var{y}, int @var{r});
@itemx int @t{fcircle} (double @var{x}, double @var{y}, double @var{r});
@itemx int @t{circlerel} (int @var{x}, int @var{y}, int @var{r});
@itemx int @t{fcirclerel} (double @var{x}, double @var{y}, double @var{r});
@t{circle} and @t{fcircle} take three arguments specifying the
center (@var{x}, @var{y}) of an circle and its radius (@var{r}).  The
graphics cursor is moved to (@var{x}, @var{y}).  @t{circlerel} and
@t{fcirclerel} are similar to @t{circle} and @t{fcircle}, but
use cursor-relative coordinates for @var{x} and @var{y}.
@item int @t{cont} (int @var{x}, int @var{y});
@itemx int @t{fcont} (double @var{x}, double @var{y});
@itemx int @t{contrel} (int @var{x}, int @var{y});
@itemx int @t{fcontrel} (double @var{x}, double @var{y});
@t{cont} and @t{fcont} take two arguments specifying the coordinate
(@var{x}, @var{y}) for the continuation of a line.  This draws a line
segment from the current graphics cursor position to the point (@var{x},
@var{y}).  The graphics cursor is moved to (@var{x}, @var{y}).  @w{A
polyline} comprising an arbitrary number of line segments may be drawn
by repeated calls to @t{cont} or @t{fcont}.  The polyline may be
terminated by calling @t{endpoly}.  Polylines are also terminated if any
other object is drawn or any drawing attribute is set.  To produce a
closed polyline rather than an open one, the final point should be the
same as the first point.  @t{contrel} and @t{fcontrel} are similar to
@t{cont} and @t{fcont}, but use cursor-relative coordinates.
@item int @t{ellarc} (int xc, int yc, int x0, int y0, int x1, int y1);
@itemx int @t{fellarc} (double xc, double yc, double x0, double y0, double x1, double y1);
@itemx int @t{ellarcrel} (int xc, int yc, int x0, int y0, int x1, int y1);
@itemx int @t{fellarcrel} (double xc, double yc, double x0, double y0, double x1, double y1);
@t{ellarc} and @t{fellarc} take six arguments specifying the three
points @code{pc}=(@var{xc},@var{yc}), @code{p0}=(@var{x0},@var{y0}), and
@code{p1}=(@var{x1},@var{y1}) that define a so-called quarter ellipse.
This is an elliptic arc with center @code{pc}, extending from @code{p0}
to @code{p1}, which is an affinely transformed version of a quarter
circle.  @w{It is} constructed as follows.  If the cross product
@ifinfo
(@code{p0}-@code{pc})x(@code{p1}-@code{pc})
@end ifinfo
@tex
$$({\tt p0 - pc})\times({\tt p1 - pc})$$
@end tex
is positive, the elliptic arc is chosen to have control points
@code{p0}, @code{p1}, and @math{@code{p0}+@code{p1}-@code{pc}}.  This
means that it is tangent at @code{p0} to the line segment joining
@code{p0} to @math{@code{p0}+@code{p1}-@code{pc}}, and is tangent at
@code{p1} to the line segment joining @code{p1} to
@math{@code{p0}+@code{p1}-@code{pc}}.  @w{So it} fits snugly into a
triangle with these three control points as vertices.  If on the other
hand the cross product is negative, a so-called three-quarter ellipse is
drawn instead.  @t{ellarcrel} and @t{fellarcrel} are similar to
@t{ellarc} and @t{fellarc}, but use cursor-relative coordinates.
@item int @t{ellipse} (int x, int y, int rx, int ry, int angle);
@itemx int @t{fellipse} (double x, double y, double rx, double ry, double angle);
@itemx int @t{ellipserel} (int x, int y, int rx, int ry, int angle);
@itemx int @t{fellipserel} (double x, double y, double rx, double ry, double angle);
@t{ellipse} and @t{fellipse} take five arguments specifying the center
(@var{x}, @var{y}) of an an ellipse, the lengths of its semiaxes
(@var{rx} and @var{ry}), and the inclination of the first semiaxis in
the counterclockwise direction from the @w{@math{x} axis} in the user
frame.  @t{ellipserel} and @t{fellipserel} are similar to @t{ellipse}
and @t{fellipse}, but use cursor-relative coordinates.
@item int @t{endpoly} ();
@t{endpoly} terminates the polyline under construction, @w{if any}.
Polylines, which are formed by repeated calls to @t{cont} or @t{fcont},
are also terminated if any other object is drawn or any drawing
attribute is set.  So @t{endpoly} is almost redundant.  However, in
versions of @code{libplot} that plot objects in real time, calling
@t{endpoly} will ensure that the polyline is drawn on the graphics
display without delay.
@item int @t{label} (char @var{*s});
@t{label} takes a single string argument @var{s} and draws the text
contained in @var{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 @t{label}(@var{s}) is equivalent to
@t{alabel}(`l',`x',@var{s}).
@item int @t{labelwidth} (char *@var{s});
@itemx double @t{flabelwidth} (char *@var{s});
@t{labelwidth} and @t{flabelwidth} compute and return the width of
a string in the current font, in the user frame.  The return value is
the same as what is returned by @t{alabel} or @t{falabel}, but the
string is not actually plotted.  In raw @code{libplot}, this function
currently returns zero.
@item int @t{line} (int @var{x1}, int @var{y1}, int @var{x2}, int @var{y2});
@itemx int @t{fline} (double @var{x1}, double y@var{1}, double @var{x2}, double @var{y2});
@itemx int @t{linerel} (int @var{x1}, int y@var{1}, int @var{x2}, int @var{y2});
@itemx int @t{flinerel} (double @var{x1}, double y@var{1}, double @var{x2}, double @var{y2});
@t{line} and @t{fline} take four arguments specifying the start point
(@var{x1}, @var{y1}) and end point (@var{x2}, @var{y2}) of a line.  The
graphics cursor is moved to (@var{x2}, @var{y2}).  These are convenience
functions, since @t{line} (@var{x1}, @var{y1}, @var{x2}, @var{y2}) is
equivalent to @t{move} (@var{x1}, @var{y1}) followed by @t{cont}
(@var{x2}, @var{y2}).  The line may be extended to a polyline by further
calls to @t{cont} or @t{fcont}.  @t{linerel} and @t{flinerel} are
similar to @t{line} and @t{fline}, but use cursor-relative coordinates.
@item  int @t{marker} (int x, int y, int type, int size);
@itemx int @t{fmarker} (double x, double y, int type, double size);
@itemx int @t{markerrel} (int x, int y, int type, int size);
@itemx int @t{fmarkerrel} (double x, double y, int type, double size);
@t{marker} and @t{fmarker} take four arguments specifying the location
@math{(x,y)} where a marker symbol is to be plotted, its type, and its
size in user coordinates.  The graphics cursor moves to @math{(x,y)}.
Marker symbol types 0 through 31 are the same for all versions of
@code{libplot}, and marker symbol types 32 and above are interpreted as
the index of a character in the current text font.  @xref{Marker
Symbols}.  @t{markerrel} and @t{fmarkerrel} are similar to @t{marker}
and @t{fmarker}, but use cursor-relative coordinates for the position
@math{(x,y)}.
@item int @t{move} (int @var{x}, int @var{y});
@itemx int @t{fmove} (double @var{x}, double @var{y});
@itemx int @t{moverel} (int @var{x}, int @var{y});
@itemx int @t{fmoverel} (double @var{x}, double @var{y});
@t{move} and @t{fmove} take two arguments specifying the
coordinates (@var{x}, @var{y}) of the new graphics cursor position.
This is equivalent to lifting the pen on a plotter and moving it to a
new position, without drawing any line.  @t{moverel} and
@t{fmoverel} are similar to @t{move} and @t{fmove}, but use
cursor-relative coordinates.
@item int @t{point} (int @var{x}, int @var{y});
@itemx int @t{fpoint} (double @var{x}, double @var{y});
@itemx int @t{pointrel} (int @var{x}, int @var{y});
@itemx int @t{fpointrel} (double @var{x}, double @var{y});
@t{point} and @t{fpoint} take two arguments specifying the coordinate
(@var{x}, @var{y}) for a single point.  The graphics cursor is moved to
(@var{x}, @var{y}), and a point is plotted.  @t{pointrel} and
@t{fpointrel} are similar to @t{point} and @t{fpoint}, but use
cursor-relative coordinates.
@end table

@node Mapping Functions, , Drawing Functions, Functions
@subsection Mapping functions

The following four @code{libplot} functions affect the affine map 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 @cite{Postscript Language Reference
Manual}.

@table @asis
@item int @t{fconcat} (double @var{m0}, double @var{m1}, double @var{m2}, double @var{m3}, double @var{tx}, double @var{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 [@var{m0} @var{m1} @var{m2} @var{m3}]
to the user coordinate system, and also translate by @var{tx} units in
the @w{@math{x} direction} and @w{@var{ty} units} in the @math{y}
direction, relative to the former user coordinate system.  The following
three functions (@t{frotate}, @t{fscale}, @t{ftranslate}) are
convenience functions that are special cases of @t{fconcat}.
@item int @t{frotate} (double @var{theta});
Rotate the user coordinate system axes about their origin by @var{theta}
degrees, with respect to their former orientation.  The position of the
user coordinate origin and the size of the @math{x} @w{and @math{y}}
units remain unchanged.
@item int @t{fscale} (double @var{sx}, double @var{sy});
Make the @math{x} and @math{y} units in the user coordinate system be
the size of @var{sx} and @var{sy} units in the former user coordinate
system.  The position of the user coordinate origin and the orientation
of the coordinate axes are unchanged.
@item int @t{ftranslate} (double @var{tx}, double @var{ty});
Move the origin of the user coordinate system by @var{tx} units in the
@w{@math{x} direction} and @w{@var{ty} units} in the @w{@math{y}
direction}, relative to the former user coordinate system.  The size of
the @math{x} and @w{@math{y} units} and the orientation of the
coordinate axes are unchanged.
@end table

@node Environment, , Functions, libplot
@section Environment variables and X Window System resources

The way in which @code{libplot} draws graphics is affected by several
environment variables.  In consequence, the behavior of @code{graph},
@code{plot}, and other applications based on @code{libplot} are
affected.  @w{In particular}, this is the case with @code{graph-tek} and
@code{graph-X}, and @code{plot2tek} and @code{plot2X}.

@code{libplottek}, which produces output for a Tektronix terminal or
emulator, checks the @code{TERM} environment variable when the
@code{openpl} function is called to initialize the output device.  @w{If
the} value of this variable is @code{xterm}, @code{xterms}, or
@code{kterm}, @w{it is} taken as a sign that the current application is
running in an @w{X Window} System VT100 terminal emulator: @w{an
@code{xterm}}.  Before producing output in Tektronix format,
@code{libplottek} will issue an escape sequence which causes the
terminal emulator's auxiliary Tektronix window, which is normally
hidden, to @w{pop up}.  When the @code{closepl} function is called to
end the drawing, it will issue an escape sequence which returns control
to the original VT100 window.  The Tektronix window will remain on the
screen.

If the value of @code{TERM} is @code{kermit}, @code{ansi.sys},
@code{ansissys}, @code{ansi.sysk}, or @code{ansisysk}, @w{it is} taken
as a sign that the current application is running in the Tektronix
emulator provided by a DOS version of @code{kermit}.  @w{If so}, some of
the Tektronix control codes output by @code{libplottek} will be
@code{kermit}-specific.  There will be a limited amount of color support
(the 16 @code{ansi.sys} colors will be supported).  Unless it believes
it is running in a @code{kermit} Tektronix emulator, @code{libplottek}
will not use color.

@code{libplotX}, which pops up a window on an @w{X Window} System
display and draws graphics @w{in it}, is similarly affected by the
environment in which it runs.  The environment variable @code{DISPLAY}
determines the display on which it will @w{pop up} the window.
@code{libplotX} also looks at the @w{X resource} @code{Xplot.geometry}.
@w{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".

The functioning of the other versions of @code{libplot}, namely
@code{libplotfig}, @code{libplotps}, and raw @code{libplot}, is not
affected by the environment.

@node spline Examples, spline Invocation, libplot, Top
@chapter The @code{spline} Utility
@section An introduction to @code{spline}

GNU @code{spline} is a program for interpolating between the data points
in one or more datasets.  The simplest case is when there is only a
single dataset, in ASCII format.  The dataset would consist of
alternating @math{x} @w{and @math{y}} coordinates.  For example, the
input file could contain the lines

@example
@group
0.0  0.0
1.0  1.0
2.0  0.0
@end group
@end example

@noindent
which are the coordinates of the data points (0,0), (1,1), and (2,0).
Data points do not need to be on different lines, nor do the @math{x}
@w{and @math{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.  Also, the @math{x} 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

@example
spline input_file > output_file
@end example

@noindent
To produce a Postscript plot of the spline with the @code{graph}
utility, you would do

@example
spline input_file | graph-ps > output.ps
@end example

@noindent
To display a spline on an @w{X Window} System display, you could do

@example
echo 0 0 1 1 2 0 | spline | graph-X
@end example

@noindent
Notice that the last example avoids the use of the input file
altogether.  @code{spline} will read from standard input if no files are
specified on the command line.

What exactly does @code{spline} do?  First, it fits a curve through the
points in the dataset.  Then it splits the input abscissa interval
(i.e., the range of @w{@math{x} values}) into 100 sub-intervals, and
computes the @w{@math{y} values} at each of the 101 subdivision points.
@w{It then} outputs each of the pairs @math{(x,y)}.  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 @samp{-n} option to replace `100' by any other integer.
You may also use the @samp{-x} option to specify an interpolation
interval that differs from the default (the dataset abscissa range).
For example, the command

@example
echo 0 0 1 0 2 0 | spline -n 20 -x 1.0 1.5 > output_file
@end example

@noindent
will produce a dataset consisting of 21 (rather than 101) data points,
with @w{@math{x} 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,0), 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), @math{y} will be a cubic function @w{of @math{x}}.  This
function will differ, depending on which pair of nodes @w{@math{x} 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.

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

@example
echo 0 0 1 0 2 0 | spline -t 10 | graph-X
@end example

@noindent
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 @w{as
well} as positive.  @w{A spline} with negative tension will tend to bow
outward, @w{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 abscissa
range 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 abscissa values 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 
@ifinfo
@math{y''''=sgn(tension)*(tension^2)y''} 
@end ifinfo
@tex
$$y''''={\rm sgn}({\sl tension}){\sl tension}^2\thinspace y''$$
@end tex
between each successive pair of nodes.  If the tension equals zero,
which is the default, the fourth derivative of @math{y} with respect
@w{to @math{x}} will equal zero at every point.  In this case, @math{y}
as a function @w{of @math{x}} will reduce to a cubic polynomial between
each successive pair of nodes.  But if the tension is nonzero, @math{y}
will not be a polynomial function @w{of @math{x}}.  It may be expressed
in terms of exponential functions, however.

Irrespective of whether or not the spline is under tension, you may
specify the @samp{-p} option if you wish the spline to be a periodic
function @w{of @var{x}}.  This will only work if the @var{y} 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 @code{spline} to function as a real-time filter.
@code{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 @samp{-f} option is specified, @code{spline} will indeed function
as a filter.  @w{A different} interpolation algorithm (cubic Bessel
interpolation, which is local rather than global) will be used.  If
@samp{-f} is specified, @samp{-p} may not be specified.  Also, if
@samp{-f} is specified then an interpolation interval must be requested
explicitly with the @samp{-x} option.

Cubic Bessel interpolation is inherently less smooth than the
construction of a global cubic spline.  If the @samp{-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 @code{spline} are similar to those discussed in
@w{D. Kincaid} and @w{W. Cheney}, @cite{Numerical Analysis} (2nd ed.,
Brooks/Cole, 1996), section 6.4, and @w{C. de Boor}, @cite{A Practical
Guide to Splines} (Springer-Verlag, 1978), @w{Chapter 4}.

@node spline Invocation, ode, spline Examples, Top
@section @code{spline} command-line options

The options to @code{spline} are listed below.  There are three sorts of
option:

@enumerate
@item
Options specifying the type of interpolation to be performed.
@item
Options specifying the input or output format.
@item
Options requesting information (e.g., @samp{--help}).
@end enumerate

@noindent
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 @samp{-a} option is used (see below), the input is expected to be a
sequence of data points, given as alternating @math{x} @w{and @math{y}}
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.

@table @samp
@item -f
@itemx --filter
Use a local interpolation algorithm (the cubic Bessel algorithm), so
that @code{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 @samp{-f} is specified then the @samp{-x} option, otherwise
optional, must be used @w{as well}.  Also, if @samp{-f} is specified then
the @samp{-k}, @samp{-p}, and @samp{-t} options may not be used.  If
@samp{-f} is @emph{not} specified, then a different (global)
interpolation algorithm will be used.
@item -k @var{k}
@itemx --boundary-condition @var{k}
(Float, default 1.0.) Set the boundary condition parameter for each
constructed spline to @w{be @var{k}}.  The spline will satisfy the two
boundary conditions @math{y''[0]=ky''[1]} and @math{y''[n]=ky''[n-1]}.
Here @math{y[0]} and @math{y[1]} signify the ordinate values at the
first two points of a dataset, and @math{y[n-1]} and @math{y[n]} the
ordinate values at the last two points.  Setting @var{k} to zero will
yield a `natural' spline, i.e., one that has zero curvature at the two
ends of the dataset.  The @samp{-k} option may not be used if @samp{-f}
or @samp{-p} is specified.
@item -n @var{n}
@itemx --number-of-intervals @var{n}
(Integer, default 100.)  Subdivide the abscissa range over which
interpolation occurs into @var{n} subintervals.  The number of data
points computed, and written to the output, will be @math{n+1}.
@item -p
@itemx --periodic
Construct a periodic spline.  If this option is specified, the @math{y}
values for the first and last points in each dataset must be equal.  The
@samp{-f} and @samp{-k} options may not be used if @samp{-p} is
specified.
@item -t @var{tension}
@itemx --tension @var{tension}
(Float, default 0.0.) Set the tension in each interpolating spline to be
@var{tension}.  Between each pair of successive points in a dataset, the
constructed spline will satisfy the differential equation
@ifinfo
@math{y''''=sgn(tension)*(tension^2)y''}.  
@end ifinfo
@tex
$y''''={\rm sgn}({\sl tension}){\sl tension}^2\thinspace y''$.
@end tex
If @var{tension} equals zero, the spline will be piecewise cubic.  As
@var{tension} increases to positive infinity, the spline will converge
to a polygonal line.  The @samp{-t} option may not be used if @samp{-f}
is specified.
@item -x @var{xmin} @var{xmax} [@var{xspacing}]
@itemx --x-limits @var{xmin} @var{xmax} [@var{xspacing}]
For each dataset, set the abscissa interval over which interpolation
occurs to be the interval between @var{xmin} and @var{xmax}.  If
@var{xspacing} is not specified, the interval will be divided into the
number of subintervals specified by the @samp{-n} option.  If the
@samp{-x} option is not used, the abscissa interval over which
interpolation occurs will be the entire range of the dataset.  Note that
the @samp{-x} option may not be used if the @samp{-f} option is used to
request filter-like behavior (see above).
@end table

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

@table @samp
@item -a [@var{step_size} [@var{lower_limit}]]
@itemx --auto-abscissa [@var{step_size} [@var{lower_limit}]]
(Floats, defaults 1.0 and 0.0.) Automatically generate abscissa values
when reading the input file(s).  Irrespective of data format, this
option indicates that the abscissa (@math{x}) values are missing: the
dataset(s) to be read contain only ordinate (@math{y}) values.  The
difference between successive @w{@math{x} values} will be
@var{step_size}, and the first @w{@math{x} value} will be
@var{lower_limit}.
@item -I @var{data-format}
@itemx --input-format @var{data-format}
(Character, default @samp{a}.)  Set the data format for the input file(s)
to be @var{data-format}.  The possible data formats are as follows.

@table @samp
@item a  
ASCII format.  Each file consists of pairs of floating point numbers,
interpreted as the @math{x} @w{and @math{y}} coordinates of the points
in a dataset.  The @math{x} and @math{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),
@w{it is} interpreted as the end of a dataset, and the beginning of the
next.
@ifinfo
@item d
Double precision binary format.  Each file is a sequence of double
precision floating point numbers, interpreted as forming pairs
(@math{x},@math{y}).  If there is more than one dataset in a file,
successive datasets are separated by a single occurrence of the quantity
@code{MAXDOUBLE}, which is the largest possible double precision
floating point number.  On most machines this is approximately
1.8x10^308.
@end ifinfo
@tex
@item d
Double precision binary format.  Each file is a sequence of double
precision floating point numbers, interpreted as forming pairs
(@math{x},@math{y}).  If there is more than one dataset in a file,
successive datasets are separated by a single occurrence of the quantity
@code{MAXDOUBLE}, which is the largest possible double precision
floating point number.  On most machines this is approximately
$1.8\times10^{308}$.
@end tex
@end table

@item -O @var{data-format}
@itemx --output-format @var{data-format}
(Character, default @samp{a}.)  Set the data format for the output file
to be @var{data-format}.  The interpretation of the @var{data-format}
argument is the same as for the @samp{-I} option.
@item -P @var{significant-digits}
@itemx --precision @var{significant-digits}
(Integer, default 6.)  Set the numerical precision for the @math{x} and
@math{y} coordinates in the output file to be @var{significant-digits}.
This takes effect only if the output file is written in @samp{a} format,
i.e., in ASCII@.
@end table

@noindent
The following options request information.
@table @samp
@item --help
Print a list of command-line options, and then exit.
@item --version
Print the version of @code{spline} and the plotting utilities package,
and exit.
@end table

@node ode, Appendices, spline Invocation, Top
@chapter The @code{ode} Utility

The GNU @code{ode} utility can produce a numerical solution to the
initial value problem for many systems of first-order ordinary
differential equations (ODE's).  @code{ode} may also be used to solve
systems of higher-order ODE's, since a simple procedure converts an
@math{n}'th-order equation into @w{@math{n} first-order} equations.  The
output of @code{ode} may easily be piped to any of the versions of
@code{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.

@menu
* Basic Math::			Ordinary differential equations
* Simple ode Examples::		Simple examples using ode
* Additional ode Examples::	Additional examples using ode
* ode Invocation::		ode command-line options
* Diagnostics::			Diagnostic messages
* Numerical Error::		Numerical error and how to avoid it
* Running Time::		Time spent running ode
* Input Language::		The ode input language formally specified
* ODE Bibliography::		Bibliography on ode and ODE's

@end menu

@node Basic Math, Simple ode Examples, ode, ode
@section Mathematical basics

We begin with some standard definitions.  A @emph{differential equation}
is an equation involving an unknown function and its derivatives.  @w{A
differential} equation is @emph{ordinary} if the unknown function
depends on only one independent variable, often @w{denoted @math{t}}.
The @emph{order} of the differential equation is the order of the
highest-order derivative in the equation.  One speaks of a family, or
@emph{system} of equations when more than one equation is involved.  If
the equations are dependent on one another, they are said to be
@emph{coupled}.  @w{A @emph{solution}} is any function satisfying the
equations.  An @emph{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
@w{Chapter 1} of Birkhoff and Rota's @cite{Ordinary Differential
Equations}.  For this and other references relevant to @code{ode}, see
@ref{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.  @code{ode} solves first-order initial value
problems of the form:

@ifinfo
@example
@group
@math{x' = f(t,x,y,@dots{},z)}
@math{y' = g(t,x,y,@dots{},z)}
   .
   .
   .
@math{z' = h(t,x,y,@dots{},z)}
@end group
@end example
@end ifinfo
@tex
@example
@group
$x' = f(t,x,y,@ldots{},z)$
$y' = g(t,x,y,@ldots{},z)$
   .
   .
   .
$z' = h(t,x,y,@ldots{},z)$
@end group
@end example
@end tex

@noindent
given the initial values for each dependent variable at the initial
value of the independent @w{variable @math{t}}, i.e.,

@example
@group
@math{x(a) = b}
@math{y(a) = c}
     .
     .
     .
@math{z(a) = d}
@math{t = a}
@end group
@end example

@tex
@noindent
where $a,b,c,\ldots,d$ are constants.
@end tex
@ifinfo
@noindent
where @math{a,b,c,...,d} are constants.
@end ifinfo

@tex
For @code{ode} to be able to solve such a problem
numerically, the functions $f,g,\ldots,h$ must be expressed, using the
usual operators (plus, minus, multiplication, division, and
exponentiation), in terms of certain basic functions that @code{ode}
recognizes.  These are the same functions that the plotting
program @code{gnuplot} recognizes.  Moreover, each of $f,g,\ldots,h$
must be given explicitly.  @code{ode} cannot deal with a system in which
one or more of the first derivatives is defined implicitly rather than
explicitly.
@end tex
@ifinfo
For @code{ode} to be able to solve such a problem
numerically, the functions f,g,@dots{},g must be expressed, using the
usual operators (@math{+},@math{-},@math{*},@math{/},^), in terms of
certain basic functions that @code{ode} recognizes.  These are the same
functions that the plotting program @code{gnuplot} recognizes.
Moreover, each of f,g,@dots{},g must be given explicitly.  @code{ode}
cannot deal with a system in which one or more of the first derivatives
is defined implicitly rather than explicitly.
@end ifinfo

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

@node Simple ode Examples, Additional ode Examples, Basic Math, ode
@section Simple examples using @code{ode}

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

Our first example is a simple one, namely

@example
@math{y'(t) = y(t)}
@end example

@noindent
with the initial condition

@example
@math{y(0) = 1}
@end example

@noindent
The solution to this differential equation is 

@ifinfo
@example
@math{y(t) = e^t}.
@end example
@end ifinfo
@tex
@example
@math{y(t) = e^t}.
@end example
@end tex

@noindent
In particular

@ifinfo
@example
@math{y(1) = e^1 = 2.718282}
@end example
@end ifinfo
@tex
@example
@math{y(1) = e^1 = 2.718282}
@end example
@end tex

@noindent
to seven digits of accuracy.

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

@example
@group
ode
y' = y
y = 1
print t, y
step 0, 1
@end group
@end example

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

@example
1 2.718282
@end example

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

After the above output, @code{ode} will wait for further instructions.
Entering for example the line

@example
step 1, 0
@end example

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

@example
step 1, 2
@end example

@noindent
to increase rather than @w{decrease @math{t}}.  @w{To exit} @code{ode},
you would type a line containing only @samp{.}, i.e.@: @w{a single} period,
and tap `return'.  @code{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.  @w{A
@samp{step}} statement sets the beginning and the end of an interval
over which the independent variable (@w{here, @math{t}}) will range, and
causes @code{ode} to set the numerical scheme in motion.  The initial
value appearing in the first @samp{step} statement (@w{i.e., 0}) and the
assignment statement

@example
y = 1
@end example

@noindent
are equivalent to the initial condition @math{y(0) = 1}.  The statements
@w{@samp{y' = y}} and @samp{y = 1} are very different: @samp{y' = y}
defines a way of computing the derivative @w{of @math{y}}, while @samp{y
= 1} sets the initial value @w{of @math{y}}.  Whenever a @samp{step}
statement is encountered, @code{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 @samp{print}
statement.  For example,

@example
print t, y, y'
@end example

@noindent
would cause the current value of the independent @w{variable @math{t}},
the @w{variable @math{y}}, and its derivative to be printed at each
step.

To illustrate @code{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:

@example
@group
# an ode to Euler
y  = 1
y' = y
print t, y, y'
@end group
@end example

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

@example
@group
ode -f euler
step 0, 1
@end group
@end example

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

@example
ode -f euler
@end example

@noindent
is not equivalent to

@example
ode < euler
@end example

@noindent
The latter would cause @code{ode} to take all its input from the file
@file{euler}, while the former allows subsequent input from the
terminal.  For the latter to produce output, you would need to include a
@samp{step} line at the end of the file.  You would not need to include
a @samp{.} line, however.  @w{@samp{.} 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

@example
@group
@math{y''(t) = -y(t)}
@math{y(0) = 0}
@math{y'(0) = 1}
@end group
@end example

@noindent
Its solution would be

@ifinfo
@example
@math{y(t) = sin(t)}
@end example
@end ifinfo
@tex
@example
@math{y(t) = \sin(t)}
@end example
@end tex

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

@example
@group
@math{y' = yp}
@math{yp' = -y}
@end group
@end example

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

To plot the variable @math{y} as a function of the @w{variable
@math{t}}, you could create a file containing the lines

@example
@group
# sine : y''(t) = -y(t), y(0) = 0, y'(0) = 1
sine' = cosine
cosine' = -sine
sine = 0
cosine = 1
print t, sine
@end group
@end example

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

@example
@group
ode -f sine | graph-X -x 0 10 -y -1 1
step 0, 2*PI
.
@end group
@end example

@noindent
After you type the @code{ode} line, @code{graph-X} will @w{pop up} a
window, and after you type the @samp{step} line, the generated dataset
will be drawn @w{in it}.  The @samp{-x 0 10} and @samp{-y -1 1} options,
which set the bounds for the two axes, are necessary if you wish to
display points in @w{real time}: as they are generated.  @w{If the} axis
bounds were not specified on the command line, @code{graph-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 @code{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.

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

@noindent
Then the sine curve will be traced out in three stages.  Since the
output from each @samp{step} statement ends with a blank line,
@code{graph-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
@code{graph-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
@samp{graph-X -B} instead of @samp{graph-X}.

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

@example
@group
ode -f sine | graph-ps > plot.ps
step 0, 2*PI
.
@end group
@end example

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

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 @code{ode}.  @code{ode} has a fair number of functions
@w{built in}, including @t{abs}, @t{sqrt}, @t{exp}, @t{log}, @t{log10},
@t{sin}, @t{cos}, @t{tan}, @t{asin}, @t{acos}, @t{atan}, @t{sinh},
@t{cosh}, @t{tanh}, @t{asinh}, @t{acosh}, and @t{atanh}.  Less familiar
functions which are built @w{into it} are @t{besj0}, @t{besj1},
@t{besy0}, @t{besy1}, @t{erf}, @t{erfc}, @t{inverf}, @t{lgamma},
@t{gamma}, @t{norm}, @t{invnorm}, @t{ibeta}, and @t{igamma}.  These have
the same definitions as in the plotting program @code{gnuplot}.
(All functions take a single argument, except for @t{ibeta}, which takes
three, and @t{igamma}, which takes two).  @code{ode} also knows the
meaning of the constant @samp{PI}, as the above examples show.  The
names of the preceding functions are reserved, so, for example,
@samp{cos} and @samp{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.  @w{It is} worth noting
that @code{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,
@w{a dummy} independent variable is invented and given the name
@samp{(indep)}, internally.

@node Additional ode Examples, ode Invocation, Simple ode Examples, ode
@section Additional examples using @code{ode}

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

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

@example
@group
# 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
@end group

@group
r = 26
x = 0; y = 1; z = 0
@end group

@group
print x, y
step 0, 200
@end group
@end example

@noindent
Then executing the command

@example
<lorenz ode | graph-X -C -x -10 10 -y -10 10
@end example

@noindent
would produce a plot of the Lorenz attractor (strictly speaking, @w{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

@example
<lorenz ode | graph-ps -x -10 10 -y -10 10 -W 0 | lpr
@end example

@noindent
The @samp{-W 0} (``zero width'') option requests that @code{graph-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.  @w{It also} shows how to use
symbolic constants.  @w{In the} description read by @code{ode} the
@w{parameter @math{r}} is a variable like @math{x}, @math{y}, @w{and
@math{z}}.  But unlike them it is not updated during stepping, since no
formula for its @w{derivative @math{r'}} is given.

Our second example deals with the interactive construction of a `phase
portrait': @w{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 aesthetic
appeal.

Since a description read by @code{ode} may contain any number of
@samp{step} statements, multiple solution curves may be plotted in a
single run.  The most recent @samp{print} statement will be used with
each @samp{step} statement.  @w{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: @w{A (the
prey)} who live by eating a plentiful supply of plants, and B (the
predator) who @w{eat A}.  Let @math{x(t)} be the population @w{of A} and
@math{y(t)} the population @w{of B} at @w{time @math{t}}.  @w{A crude}
model for the interaction of A @w{and B} is given by the equations

@example
@group
@math{x' = x(a-by)}
@math{y' = y(cx-d)}
@end group
@end example

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

@example
@group
ode | graph-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
@end group
@group
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
.
@end group
@end example

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

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

@example
@group
m = 1
M = 1.0625
a = 0.5; adot = 0
l = 10; ldot = 0
@end group

@group
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
@end group

@group
print l, ldot
step 0, 400
@end group
@end example

@noindent
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 @w{mass (@math{M})} would win against the lighter
@w{mass (@math{m})}, and draw it upward.  @w{A swinging} Atwood's
machine allows the lighter mass to swing back and forth @w{as well} as
move vertically.

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

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

@noindent
you will obtain a real-time plot.  The @samp{-m 0} option requests that
successive data points not be joined by line segments, and the @samp{-S
1} option requests that plotting @w{symbol #1} (@w{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 @code{ode} that may be
useful when things are not going quite right.  One of them is the
@samp{examine} statement.  @w{It may} be used to discover pertinent
information about any variable in a system.  For details, see @ref{Input
Language}.

Another useful feature is that the @samp{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 @samp{'}, the derivative of the
variable will be printed instead.  @w{In a} similar way, following the
variable name with @samp{?}, @samp{!}, or @samp{~} prints respectively
the relative single-step error, the absolute single-step error, or the
accumulated error (not currently implemented).  These quantities are
discussed in @ref{Numerical Error}.

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

@example
print <pr-list> [every <const>] [from <const>]
@end example

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

@example
print t, y, y' every 5 from 1
@end example

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

@node ode Invocation, Diagnostics, Additional ode Examples, ode
@section @code{ode} command-line options

@noindent
The command-line options to @code{ode} are listed below.  There are
several sorts of option:

@enumerate
@item
Options affecting the way in which input is read.
@item 
Options affecting the format of the output.
@item
Options affecting the choice of numerical solution scheme, and the
error bounds that will be imposed @w{on it}.
@item
Options that request information.
@end enumerate

@noindent
The following option affects the way input is read.

@table @samp
@item -f @var{filename}
@itemx --input-file @var{filename}
Read input from @var{filename} before reading from standard input.
@end table

@noindent
The following options affect the output format.

@table @samp
@item -p @var{precision}
@itemx --precision @var{precision}
When printing numerical results, use @var{precision} significant
figures.  If this option is given, all output will be in scientific
notation.
@item -t
@itemx --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.
@end table

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

@table @samp
@item -R [@var{stepsize}]
@itemx --runge-kutta [@var{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.
@item -A [@var{stepsize}]
@itemx --adams-moulton [@var{stepsize}]
Use a fourth-order Adams--Moulton predictor--corrector scheme, with an
adaptive stepsize unless a constant stepsize, @var{stepsize}, is
specified.  The Runge--Kutta--Fehlberg algorithm is used to get past
`bad' points (@w{if any}).
@item -E [@var{stepsize}]
@itemx --euler [@var{stepsize}]
Use a `quick and dirty' Euler scheme, with a constant stepsize.  The
default value of @var{stepsize} is 0.1.  Not recommended for serious
applications.
@item -h @var{hmin} [@var{hmax}]
@itemx --step-size-bound @var{hmin} [@var{hmax}]
Use a lower bound @var{hmin} on the stepsize.  The numerical scheme will
not let the stepsize go below @var{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
@var{hmax}, if included, specifies a maximum value for the stepsize.
@w{It is} useful in preventing the numerical routine from skipping
quickly over an interesting region.
@end table

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

@table @samp
@item -r @var{rmax} [@var{rmin}]
@itemx --relative-error-bound @var{rmax} [@var{rmin}]
@item -e @var{emax} [@var{emin}]
@itemx --absolute-error-bound @var{emax} [@var{emin}]
@ifinfo
The @samp{-r} option sets an upper bound on the relative single-step
error.  If the @samp{-r} option is used, the relative single-step error
in any dependent variable will never exceed @var{rmax} (the default for
which is @math{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.  @w{A lower} bound @var{rmin} may optionally be
specified, to suggest when the stepsize should be increased (the default
for @var{rmin} is @var{rmax}/1000).  The @samp{-e} option is similar to
@samp{-r}, but bounds the absolute rather than the relative single-step
error.
@end ifinfo
@tex
The @samp{-r} option sets an upper bound on the relative single-step
error.  If the @samp{-r} option is used, the relative single-step error
in any dependent variable will never exceed @var{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.  @w{A lower} bound @var{rmin} may optionally be
specified, to suggest when the stepsize should be increased (the default
for @var{rmin} is @var{rmax}/1000).  The @samp{-e} option is similar to
@samp{-r}, but bounds the absolute rather than the relative single-step
error.
@end tex
@item -s
@itemx --suppress-error-bound
Suppress the ceiling on single-step error, allowing @code{ode} to
continue even if this ceiling is exceeded.  This may result in large
numerical errors.
@end table

@noindent
Finally, the following options request information.

@table @samp
@item --help
Print a list of command-line options, and then exit.
@item --version
Print the version of @code{ode} and the plotting utilities package, and
exit.
@end table

@node Diagnostics, Numerical Error, ode Invocation, ode
@section Diagnostic messages

@code{ode} is always in one of two states:

@itemize @bullet
@item
Reading input.  The input includes a specification of a system of
ordinary differential equations, together with instructions for
@w{solving it} numerically: @w{a @samp{print}} line and a @samp{step}
line.
@item
Numerically solving a system, and printing the resulting output.
@end itemize

@noindent
@code{ode} moves from the first to the second state after it sees and
processes a @samp{step} line.  @w{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 @code{ode} to exit.  We now explain the possible sorts of
error.

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

@example
ode::nnn: syntax error
@end example

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

@example
ode:filename:nnn: syntax error
@end example

@noindent
for errors encountered inside the input file.  Subsequently, when
@code{ode} begins reading the standard input, line numbers will start
over again @w{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
@code{ode} is reading input.  If such an exception occurs, @code{ode}
will print an ``Floating point exception'' error message and exit.
Arithmetic exceptions are machine-dependent.  @w{On some} machines, the
line

@example
y = 1/0
@end example

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

@example
@group
y = 1e100
z = y^4
@end group
@end example

@ifinfo
@noindent
would induce an arithmetic exception.  That is because on most
machines, the double precision quantities that @code{ode} uses
internally are limited to a maximum size of approximately 1.8x10^308.
@end ifinfo
@tex
@noindent
would induce an arithmetic exception.  That is because on most machines,
the double precision quantities that @code{ode} uses internally are
limited to a maximum size of approximately $1.8\times10^{308}$.
@end tex

When @code{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

@example
ode: arithmetic exception while calculating y'
@end example

@noindent
will be printed.  However, @code{ode} will not exit; the exception will
be `caught'.  @code{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.
@code{ode} will catch any of these operations before it is performed,
and print an error message specifying which illegal operation it has
encountered.

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

@noindent
would be a typical error message.

If the machine on which @code{ode} is running supports the
@samp{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 loss of
significance) that could occur when evaluating such functions as
@samp{log}, @samp{gamma}, etc.; again, before they are performed.  If
the @code{matherr} facility is present, the error message will be fairly
informative.  For example, the error message

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

@noindent
could be generated if the logarithmic gamma function @samp{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 @samp{-r} option or the @samp{-e} option, is exceeded.  This too
will cause the numerical solution to be abandoned, and @code{ode} to
switch back to reading input.

@node Numerical Error, Running Time, Diagnostics, ode
@section Numerical error and how to avoid it

This discussion is necessarily incomplete.  Entire books exist on any
subject mentioned below (for example, floating point error).  Our goals
are modest: first, to introduce the basic notions of error analysis as
they apply to @code{ode}; second, @w{to steer} you around the more
obvious pitfalls.  You should look through a numerical analysis text
(e.g., Atkinson's @cite{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 @emph{accumulated
error}, since the error is @w{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 @emph{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.

@ifinfo
The @emph{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, @code{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
@math{10^(-9)} on the relative single-step error.  This ceiling may be
adjusted with the @samp{-r} option.
@end ifinfo
@tex
The @emph{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, @code{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
@samp{-r} option.
@end tex

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
@code{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 @samp{-p 17} option, which will print seventeen significant digits.
@w{On most} machines, that is the precision of a double precision
floating point number.

The second source of numerical error is often called the
@emph{theoretical truncation error}.  @w{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,
@w{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
@code{ode} consists only of the theoretical truncation error.

We say that a numerical scheme is @emph{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; @w{at least}, over a wide range of step sizes.  With this
definition both the Runge--Kutta--Fehlberg (@samp{-R}) scheme and the
Adams--Moulton (@samp{-A}) scheme are stable (@w{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.

@enumerate
@item Singularities

@code{ode} should not be used to generate a numerical solution on any
interval containing a singularity.  That is, @code{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 @cite{Ordinary
Differential Equations}, @w{Chapter 9}.  Always locate and classify the
singularities of a system, @w{if any}, before applying @code{ode}.

@item 
Ill-posed  problems

For @code{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 @emph{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 @w{blowing up}, may indicate
ill-posedness.

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

@ifinfo
@example
@group
@math{y' = y^2}
@math{y(1) = -1}
@end group
@end example
@end ifinfo
@tex
@example
@group
$y' = y^2$
$y(1) = -1$
@end group
@end example
@end tex

@noindent
The solution on the domain @math{t > 0} is

@example
@math{y(t) = -1/t}.
@end example

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

@example
step 1, -1
@end example

@noindent
on this system.  How does @code{ode} react?

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

@item 
Critical points

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

@example
@group
@math{y' = 2x}
@math{x' = 2y}
@end group
@end example

has only one critical point, at @math{(x,y) = (0,0)}.

A critical point is sometimes referred to as a @emph{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 @code{ode}, with the
initial condition @math{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 @code{ode}.  Critical points may be
classified (as equilibrium, vortex, unstable, stable, etc.) and this
classification may be @w{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 @cite{Ordinary Differential Equations},
@w{Chapter 6}).

@item 
Unsuitable numerical schemes

If the results produced by @code{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, @code{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:

@noindent
XXX

@noindent
for @math{0 < t < 10}.  The exact solution is

@noindent
XXX

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

@end enumerate

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

@enumerate
@item 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.

@itemize @bullet

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

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

@end itemize

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

@example
@group
# 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
@end group

@group
print t, f
step 0, 5
@end group
@end example

@noindent
Next make a file named @file{stability}, containing the lines:

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

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:

@example
sh stability 1 .1 .01 .001
@end example

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

@item 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'
(@w{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.

@item 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---@w{that is},
if two solutions which start out very close nonetheless @w{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 @w{or so} over the interval.  Problems exhibiting no sharp
divergence of neighboring solution curves are sometimes called
@emph{well-conditioned}.
@end enumerate

@node Running Time, Input Language, Numerical Error, ode
@section Running time

The time required for @code{ode} to solve numerically a system of
ordinary differential equations depends on a great many factors.  @w{A
few} of them are: number of equations, complexity of equations (number
of operators and nature of the operators), and number of steps taken
(@w{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.  @w{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.

@node Input Language, ODE Bibliography, Running Time, ode
@section The @code{ode} input language formally specified

The following is a formal description of the grammar for @code{ode}'s
input language.  The notation is BNF, which stands for `Backus--Naur
form' (see Wirth).  Nonterminal symbols in the grammar are enclosed in
angle brackets.  Terminal tokens are in all capitals.  Bare words and
symbols stand for themselves.

@example
@group
<program>    ::=        ... empty ...
               |  <program> <statement>
@end group


@group
<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
@end group


@group
<printlist>  ::=  <printitem>
               |  <printlist> , <printitem>
@end group


@group
<printitem>  ::=  IDENTIFIER
               |  IDENTIFIER '
               |  IDENTIFIER ?
               |  IDENTIFIER !
               |  IDENTIFIER ~
@end group


@group
<optevery>   ::=        ... empty ...
               |  every <const>
@end group


@group
<optfrom>    ::=        ... empty ...
               |  from <const>
@end group


@group
<const>      ::=  <expression>
@end group


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

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

@example
@group
Class           Operators    Associativity

Exponential         ^            right
Multiplicative      * /          left
Additive            + -          left
@end group
@end example

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

@enumerate
@item 
@t{IDENTIFIER ' = <expression>}

@noindent This defines a first-order differential equation.  
The derivative of @t{IDENTIFIER} is specified by @t{<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.

@item 
@t{IDENTIFIER = <const>}

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

@item 
@t{step <const> , <const>}
@item 
@t{step <const> , <const> , <const>}

@noindent
A @samp{step} statement causes the numerical scheme to be executed.  The
first @t{<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.

@item 
@t{print <printlist> [ every <const> ] [ from <const> ]}

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

If no @samp{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.

@item 
@t{examine IDENTIFIER}

@noindent
An @samp{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 @samp{examine y} were
encountered after execution of the `ode to Euler' example discussed
elsewhere, the output would be:

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

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

@table @t
@item value
Current value of the variable.
@item prime   
Current derivative of the variable.
@item sserr   
Relative single-step error for the last step taken.
@item aberr   
Absolute single-step error for the last step taken.
@item acerr   
Total error accumulated during the most recent @samp{step} statement.
Not currently implemented.
@end table

The @samp{code} section of the table lists the stack operations required
to compute the derivative @w{of @t{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.  @samp{@t{push "y"}} means to
load @t{y}'s value on the stack, which is all that is required to
compute its derivative in this case.

@end enumerate

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

@enumerate
@item
@t{FUNCTION}

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

@item
@t{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 @samp{PI}.

@item
@t{NUMBER}

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

@item
@t{SEP}

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

@end enumerate

In the @code{ode} input language, upper and lower-case letters are
distinct.  Comments begin with the character @samp{#} and continue to
the end of the line.  Long lines may be continued onto a second line by
ending the first line with a @w{backslash (@samp{\})}.  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.

@node ODE Bibliography, , Input Language, ode
@section Bibliography on @code{ode} and solving differential equations

@itemize @asis
@item
K. E. Atkinson, @cite{An Introduction to Numerical Analysis}, Wiley, 1978.
Pages 380--384 contain a nice review of the literature on the numerical
solution of ordinary differential equations.

@item
G. Birkhoff and G. Rota, @cite{Ordinary Differential Equations}, Ginn
and Co., 1962.

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

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

@item
N. Wirth, @cite{Algorithms + Data Structures = Programs},
Prentice--Hall, 1976.
@end itemize

@node Appendices, , ode, Top
@ifinfo
The following appendices contain miscellaneous information on the
plotting utilities.
@end ifinfo

@menu
* Text and Markers::	Text fonts, text strings, and marker symbols
* Color Names::		Specifying colors by name
* Metafiles::           The device-independent GNU metafile format
* Auxiliary Software::  How to obtain auxiliary software
* Acknowledgements::    The Contributors
@end menu

@node Text and Markers, Color Names, Appendices, Appendices
@appendix Fonts, Strings, and Symbols 

The @code{libplot} function library and applications linked with it,
such as @code{graph}, 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.
@w{A wide} variety of plotting symbols can also be drawn.  The following
sections explain how to use these features.

@menu
* Text Fonts::		Available text fonts
* Text String Format::	Text string formatting (with escape sequences)
* Marker Symbols::	Available marker symbols
@end menu

@node Text Fonts, Text String Format, Text and Markers, Text and Markers
@appendixsection Available text fonts

The @code{libplot} function library and applications linked with it,
such as @code{graph}, can use many fonts.  These include 16 Hershey
fonts and 35 Postscript fonts.  We call these 51 fonts the `built-in'
fonts.  The Hershey fonts are so-called vector fonts, constructed from
stroked characters digitized @w{c.@: 1967} by Dr.@: @w{Allen V.} Hershey
at the U.S. Naval Surface Weapons Center in @w{Dahlgren, VA}.  The 35
Postscript fonts are the fonts built into most modern Postscript
printers.  The Hershey fonts may be used by all versions of
@code{libplot}, and the Postscript fonts may be used by all versions of
@code{libplot} except @code{libplottek}.  So all versions of
@code{graph} may use the Hershey fonts, and all versions of @code{graph}
except @code{graph-tek} may use the Postscript fonts.

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

@itemize @bullet
@item HersheySerif
@enumerate
@item HersheySerif
@item HersheySerif-Italic
@item HersheySerif-Bold
@item HersheySerif-BoldItalic
@item HersheyCyrillic
@item HersheyEUC
@end enumerate
@item HersheySans
@enumerate
@item HersheySans
@item HersheySans-Oblique
@item HersheySans-Bold
@item HersheySans-BoldOblique
@end enumerate
@item HersheyScript
@enumerate
@item HersheyScript
@item HersheyScript
@item HersheyScript-Bold
@item HersheyScript-Bold
@end enumerate
@item HersheyGothic-English
@item HersheyGothic-German
@item HersheyGothic-Italian
@item HersheySerif-Symbol
@item HersheySans-Symbol
@end itemize

@noindent
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 @w{font #0}.

The 35 Postscript fonts are divided into typefaces as follows.

@itemize @bullet
@item Helvetica
@enumerate
@item	Helvetica
@item	Helvetica-Oblique
@item	Helvetica-Bold
@item	Helvetica-BoldOblique
@end enumerate
@item	Helvetica-Narrow
@enumerate
@item	Helvetica-Narrow
@item	Helvetica-Narrow-Oblique
@item	Helvetica-Narrow-Bold
@item	Helvetica-Narrow-BoldOblique
@end enumerate
@item   Times
@enumerate
@item	Times-Roman
@item	Times-Italic
@item	Times-Bold
@item	Times-BoldItalic
@end enumerate
@item AvantGarde
@enumerate
@item	AvantGarde-Book
@item	AvantGarde-BookOblique
@item	AvantGarde-Demi
@item	AvantGarde-DemiOblique
@end enumerate
@item Bookman
@enumerate
@item	Bookman-Light
@item	Bookman-LightItalic
@item	Bookman-Demi
@item	Bookman-DemiItalic
@end enumerate
@item Courier
@enumerate
@item	Courier
@item	Courier-Oblique
@item	Courier-Bold
@item	Courier-BoldOblique
@end enumerate
@item NewCenturySchlbk
@enumerate
@item	NewCenturySchlbk-Roman
@item	NewCenturySchlbk-Italic
@item	NewCenturySchlbk-Bold
@item	NewCenturySchlbk-BoldItalic
@end enumerate
@item Palatino
@enumerate
@item	Palatino-Roman
@item	Palatino-Italic
@item	Palatino-Bold
@item	Palatino-BoldItalic
@end enumerate
@item	ZapfChancery-MediumItalic
@item	ZapfDingbats
@item	Symbol
@end itemize

@noindent
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 @w{font #0}.

As you can see from the above 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 @w{(if any)} are numbered #5 and
higher.

Of the 51 built-in fonts, all except for the three symbol fonts,
HersheyCyrillic, HersheyEUC, and ZapfDingbats are ISO-8859-1 fonts.
This means that they use the ISO-Latin-1 encoding, which is a superset
of ASCII@.  The three symbol fonts use a special encoding, since they
consist of Greek characters and mathematical symbols.  The ZapfDingbats
font, which consists largely of marker symbols, uses a special encoding
also.  These two encodings are documented in the @cite{Postscript
Language Reference Manual}.

The HersheyCyrillic font uses an encoding known as KOI8-R, a superset of
ASCII which has become the @w{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 @t{0xc0}@dots{}@t{0xdf}
contains lower-case Cyrillic characters and the byte range
@t{0xe0}@dots{}@t{0xff} contains upper case Cyrillic characters.
Additional Cyrillic characters are located at @t{0xa3} @w{and @t{0xb3}}.
For more on this encoding, see
@code{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
@cite{Understanding Japanese Information Processing} (O'Reilly, 1993),
which contains much additional information on Japanese text processing.
See also his on-line supplement,
@code{http://www.ora.com/people/authors/lunde/cjk_inf.html}.

In the HersheyEUC font, characters in the printable ASCII range,
@t{0x20}@dots{}@t{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
@code{0xa1}@dots{}@code{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 @code{0x2421}@dots{}@code{0x2453}.  @w{To
obtain} the EUC code for any JIS X0208 character, one adds @code{0x80}
to each byte (i.e., `sets the high bit' on each byte).  So the first of
the 83 Hiragana (@code{0x2421}) would be encoded as the successive pair
of bytes @code{0xa4} @w{and @code{0xa1}}.

The implementation of the JIS X0208 standard in the HersheyEUC font is
based on @w{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 @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 Hershey and Postscript fonts contain ligatures?
The 35 Postscript fonts, as implemented in @code{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.)  @w{In addition}, "tz" and "ch"
are ligatures in HersheyGothic-German.  The German `eszet' double-s
character is not regarded as a ligature in any font.  To obtain it, you
must either request it with the control @w{sequence "\ss"} (@pxref{Text
String Format}), or, if you have an 8-bit keyboard, type it explicitly.

The preceding discussions dealt with the built-in fonts: the 16 Hershey
and 35 Postscript fonts.  @w{In fact} @code{libplotX} and @code{graph-X}
(which is built on top of @code{libplotX}) are not restricted to the
built-in fonts.  They can display text strings using certain @w{X
Window} System fonts @w{as well}.  Any scalable font which is available
on the current @w{X Window} System display, and which has a so-called
XLFD (@w{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
@w{X displays}.  It would be referred to by @code{libplotX} as "gill
sans-ultrabold-r-condensed".  The command

@example
echo 0 0 1 1 2 0 | graph-X -F "gill sans-ultrabold-r-condensed"
@end example

@noindent
would draw a plot on an @w{X display}, in which all axis ticks are labeled
in this font.  

You may determine which fonts are available on an @w{X display} by using
the @code{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 @code{libplotX} and
@code{graph-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 (@pxref{Text String Format}) may be employed when using
any @w{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 @w{X
Window} System font.

@node Text String Format, Marker Symbols, Text Fonts, Text and Markers
@appendixsection Text string format and escape sequences

Text strings that are drawn by @code{libplot}, and by such applications
as @code{graph} that are built on @code{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
@t{0x20}@dots{}@t{0x7e} and @t{0xa0}@dots{}@t{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 @code{graph} may include such features.

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

@table @asis
@item "\sp"
start superscript mode
@item "\ep"
end superscript mode
@item "\sb"
start subscript mode
@item "\eb"
end subscript mode
@item "\mk"
mark location 
@item "\rt"
return to marked location
@end table

@noindent
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
@ref{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 "\f@var{n}", where @var{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"@dots{}"\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 @t{0xa0}@dots{}@t{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, @w{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.

@table @asis
@item "\r!" 
[161] exclamdown
@item "\ct" 
[162] cent
@item "\Po" 
[163] sterling
@item "\Cs" 
[164] currency
@item "\Ye" 
[165] yen
@item "\bb" 
[166] brokenbar
@item "\sc" 
[167] section
@item "\ad" 
[168] dieresis
@item "\co" 
[169] copyright
@item "\Of" 
[170] ordfeminine
@item "\Fo" 
[171] guillemotleft
@item "\no" 
[172] logicalnot
@item "\hy" 
[173] hyphen
@item "\rg" 
[174] registered
@item "\a-" 
[175] macron
@item "\de" 
[176] degree
@item "\+-" 
[177] plusminus
@item "\S2" 
[178] twosuperior
@item "\S3" 
[179] threesuperior
@item "\aa" 
[180] acute
@item "\*m" 
[181] mu
@item "\ps" 
[182] paragraph
@item "\md" 
[183] periodcentered
@item "\ac" 
[184] cedilla
@item "\S1" 
[185] onesuperior
@item "\Om" 
[186] ordmasculine
@item "\Fc" 
[187] guillemotright
@item "\14" 
[188] onequarter
@item "\12" 
[189] onehalf
@item "\34" 
[190] threequarters
@item "\r?" 
[191] questiondown
@item "\`A" 
[192] Agrave
@item "\'A" 
[193] Aacute
@item "\^A" 
[194] Acircumflex
@item "\~A" 
[195] Atilde
@item "\:A" 
[196] Adieresis
@item "\oA" 
[197] Aring
@item "\AE" 
[198] AE
@item "\,C" 
[199] Ccedilla
@item "\`E" 
[200] Egrave
@item "\'E" 
[201] Eacute
@item "\^E" 
[202] Ecircumflex
@item "\:E" 
[203] Edieresis
@item "\`I" 
[204] Igrave
@item "\'I" 
[205] Iacute
@item "\^I" 
[206] Icircumflex
@item "\:I" 
[207] Idieresis
@item "\-D" 
[208] Eth
@item "\~N" 
[209] Ntilde
@item "\'O" 
[210] Ograve
@item "\'O" 
[211] Oacute
@item "\^O" 
[212] Ocircumflex
@item "\~O" 
[213] Otilde
@item "\:O" 
[214] Odieresis
@item "\mu" 
[215] multiply
@item "\/O" 
[216] Oslash
@item "\`U" 
[217] Ugrave
@item "\'U" 
[218] Uacute
@item "\^U" 
[219] Ucircumflex
@item "\:U" 
[220] Udieresis
@item "\'Y" 
[221] Yacute
@item "\TP" 
[222] Thorn
@item "\ss" 
[223] germandbls
@item "\`a" 
[224] agrave
@item "\'a" 
[225] aacute
@item "\^a" 
[226] acircumflex
@item "\~a" 
[227] atilde
@item "\:a" 
[228] adieresis
@item "\oa" 
[229] aring
@item "\ae" 
[230] ae
@item "\,c" 
[231] ccedilla
@item "\`e" 
[232] egrave
@item "\'e" 
[233] eacute
@item "\^e" 
[234] ecircumflex
@item "\:e" 
[235] edieresis
@item "\`i" 
[236] igrave
@item "\'i" 
[237] iacute
@item "\^i" 
[238] icircumflex
@item "\:i" 
[239] idieresis
@item "\Sd" 
[240] eth
@item "\~n" 
[241] ntilde
@item "\`o" 
[242] ograve
@item "\'o" 
[243] oacute
@item "\^o" 
[244] ocircumflex
@item "\~o" 
[245] otilde
@item "\:o" 
[246] odieresis
@item "\di" 
[247] divide
@item "\/o" 
[248] oslash
@item "\`u" 
[249] ugrave
@item "\'u" 
[250] uacute
@item "\^u" 
[251] ucircumflex
@item "\:u" 
[252] udieresis
@item "\'y" 
[253] yacute
@item "\Tp" 
[254] thorn
@item "\:y" 
[255] ydieresis
@end table

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 @cite{Postscript Language Reference
Manual}.

@table @asis
@item "\fa" 
[0042] universal
@item "\te" 
[0044] existential
@item "\st" 
[0047] suchthat
@item "\**" 
[0052] asteriskmath
@item "\=~" 
[0100] congruent
@item "\*A" 
[0101] Alpha
@item "\*B" 
[0102] Beta
@item "\*X" 
[0103] Chi
@item "\*D" 
[0104] Delta
@item "\*E" 
[0105] Epsilon
@item "\*F" 
[0106] Phi
@item "\*G" 
[0107] Gamma
@item "\*Y" 
[0110] Eta
@item "\*I" 
[0111] Iota
@item "\+h" 
[0112] theta1
@item "\*K" 
[0113] Kappa
@item "\*L" 
[0114] Lambda
@item "\*M" 
[0115] Mu
@item "\*N" 
[0116] Nu
@item "\*O" 
[0117] Omicron
@item "\*P" 
[0120] Pi
@item "\*H" 
[0121] Theta
@item "\*R" 
[0122] Rho
@item "\*S" 
[0123] Sigma
@item "\*T" 
[0124] Tau
@item "\*U" 
[0125] Upsilon
@item "\ts" 
[0126] sigma1
@item "\*W" 
[0127] Omega
@item "\*C" 
[0130] Xi
@item "\*Q" 
[0131] Psi
@item "\*Z" 
[0132] Zeta
@item "\tf" 
[0134] therefore
@item "\pp" 
[0136] perpendicular
@item "\ul" 
[0137] underline
@item "\rx" 
[0140] radicalex
@item "\*a" 
[0141] alpha
@item "\*b" 
[0142] beta
@item "\*x" 
[0143] chi
@item "\*d" 
[0144] delta
@item "\*e" 
[0145] epsilon
@item "\*f" 
[0146] phi
@item "\*g" 
[0147] gamma
@item "\*y" 
[0150] eta
@item "\*i" 
[0151] iota
@item "\+f" 
[0152] phi1
@item "\*k" 
[0153] kappa
@item "\*l" 
[0154] lambda
@item "\*m" 
[0155] mu
@item "\*n" 
[0156] nu
@item "\*o" 
[0157] omicron
@item "\*p" 
[0160] pi
@item "\*h" 
[0161] theta
@item "\*r" 
[0162] rho
@item "\*s" 
[0163] sigma
@item "\*t" 
[0164] tau
@item "\*u" 
[0165] upsilon
@item "\+p" 
[0166] omega1
@item "\*w" 
[0167] omega
@item "\*c" 
[0170] xi
@item "\*q" 
[0171] psi
@item "\*z" 
[0172] zeta
@item "\ap" 
[0176] similar
@item "\+U" 
[0241] Upsilon1
@item "\fm" 
[0242] minute
@item "\<=" 
[0243] lessequal
@item "\f/" 
[0244] fraction
@item "\if" 
[0245] infinity
@item "\Fn" 
[0246] florin
@item "\CL" 
[0247] club
@item "\DI" 
[0250] diamond
@item "\HE" 
[0251] heart
@item "\SP" 
[0252] spade
@item "\<>" 
[0253] arrowboth
@item "\<-" 
[0254] arrowleft
@item "\ua" 
[0255] arrowup
@item "\->" 
[0256] arrowright
@item "\da" 
[0257] arrowdown
@item "\de" 
[0260] degree
@item "\+-" 
[0261] plusminus
@item "\sd" 
[0262] second
@item "\>=" 
[0263] greaterequal
@item "\mu" 
[0264] multiply
@item "\pt" 
[0265] proportional
@item "\pd" 
[0266] partialdiff
@item "\bu" 
[0267] bullet
@item "\di" 
[0270] divide
@item "\!=" 
[0271] notequal
@item "\==" 
[0272] equivalence
@item "\~~" 
[0273] approxequal
@item "\.." 
[0274] ellipsis
@item NONE 
[0275] arrowvertex
@item "\an" 
[0276] arrowhorizex
@item "\CR" 
[0277] carriagereturn
@item "\Ah" 
[0300] aleph
@item "\Im" 
[0301] Ifraktur
@item "\Re" 
[0302] Rfraktur
@item "\wp" 
[0303] weierstrass
@item "\c*" 
[0304] circlemultiply
@item "\c+" 
[0305] circleplus
@item "\es" 
[0306] emptyset
@item "\ca" 
[0307] cap
@item "\cu" 
[0310] cup
@item "\SS" 
[0311] superset
@item "\ip" 
[0312] reflexsuperset
@item "\n<" 
[0313] notsubset
@item "\SB" 
[0314] subset
@item "\ib" 
[0315] reflexsubset
@item "\mo" 
[0316] element
@item "\nm" 
[0317] notelement
@item "\/_" 
[0320] angle
@item "\gr" 
[0321] nabla
@item "\rg" 
[0322] registerserif
@item "\co" 
[0323] copyrightserif
@item "\tm" 
[0324] trademarkserif
@item "\PR" 
[0325] product
@item "\sr" 
[0326] radical
@item "\md" 
[0327] dotmath
@item "\no" 
[0330] logicalnot
@item "\AN" 
[0331] logicaland
@item "\OR" 
[0332] logicalor
@item "\hA" 
[0333] arrowdblboth
@item "\lA" 
[0334] arrowdblleft
@item "\uA" 
[0335] arrowdblup
@item "\rA" 
[0336] arrowdblright
@item "\dA" 
[0337] arrowdbldown
@item "\lz" 
[0340] lozenge
@item "\la" 
[0341] angleleft
@item "\RG" 
[0342] registersans
@item "\CO" 
[0343] copyrightsans
@item "\TM" 
[0344] trademarksans
@item "\SU" 
[0345] summation
@item NONE 
[0346] parenlefttp
@item NONE 
[0347] parenleftex
@item NONE 
[0350] parenleftbt
@item "\lc" 
[0351] bracketlefttp
@item NONE 
[0352] bracketleftex
@item "\lf" 
[0353] bracketleftbt
@item "\lt" 
[0354] bracelefttp
@item "\lk" 
[0355] braceleftmid
@item "\lb" 
[0356] braceleftbt
@item "\bv" 
[0357] braceex
@item NONE 
[0360] applelogo
@item "\ra" 
[0361] angleright
@item "\is" 
[0362] integral
@item NONE 
[0363] integraltp
@item NONE 
[0364] integralex
@item NONE 
[0365] integralbt
@item NONE 
[0366] parenrighttp
@item NONE 
[0367] parenrightex
@item NONE 
[0370] parenrightbt
@item "\rc" 
[0371] bracketrighttp
@item NONE 
[0372] bracketrightex
@item "\rf" 
[0373] bracketrightbt
@item "\RT" 
[0374] bracerighttp
@item "\rk" 
[0375] bracerightmid
@item "\rb" 
[0376] bracerightbt
@end table

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.

@table @asis
@item "\dd"
daggerdbl
@item "\dg"
dagger
@item "\hb"
hbar
@item "\li"
lineintegral
@item "\IB"
interbang
@item "\Lb"
lambdabar
@item "\~-"
modifiedcongruent
@item "\-+"
minusplus
@item "\||"
parallel
@item "\s-"
[variant form of s]
@end table

@noindent
The final escape sequence in the table above, "\s-", yields a letter
rather than a symbol.  @w{It is} provided because in some Hershey fonts, the
shape of the lower-case @w{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 @w{final `s'} is different from lower-case @w{non-final
`s'}).  @w{In Hershey} fonts where there is no distinction between final
and @w{non-final `s'}, @w{"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.

@table @asis
@item "\SO"
sun
@item "\ME"
mercury
@item "\VE"
venus
@item "\EA"
earth
@item "\MA"
mars
@item "\JU"
jupiter
@item "\SA"
saturn
@item "\UR"
uranus
@item "\NE"
neptune
@item "\PL"
pluto
@item "\LU"
moon
@item "\CT"
comet
@item "\ST"
star
@item "\AS"
ascendingnode
@item "\DE"
descendingnode
@end table

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 Dr.@: @w{Allen
V.} Hershey is built into GNU @code{libplot}.  @w{So text} strings may
include any Hershey glyph.  Each of the 1641 available Hershey glyphs is
identified by a four-digit number.  Standard Hershey @w{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"@dots{}"\#H4194" range.
Syllabic Japanese characters (Kana) are located in the
"\#H4195"@dots{}"\#H4399" range.

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

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

@noindent
when drawn will display a shamrock, a fleur-de-lis, cartographic (small)
letters @w{A, B, C}, @w{a bell,} @w{a large} circle, @w{a treble}
clef, and @w{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.  @w{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 @code{0x21}@dots{}@code{0x7e} range in order to
define a JIS X0208 character.  Kanji are located at "\#J3021" and above.
The file @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"@dots{}"\#J257e" range, and Roman characters are located in the
"\#J2300"@dots{}"\#J237e" range.  The file @file{kana.doc} lists the
encodings of the Hiragana and Katakana.  For more on the JIS X0208
standard, see Ken Lunde's @cite{Understanding Japanese Information
Processing} (O'Reilly, 1993), and his on-line supplement,
@code{http://www.ora.com/people/authors/lunde/cjk_inf.html}.

The Kanji numbering used in @w{A. N.} Nelson's @cite{Modern Reader's
Japanese-English Character Dictionary}, @w{a longtime} standard, is also
supported.  (This dictionary is published by @w{C. E.} Tuttle and Co.,
with ISBN 0-8048-0408-7.  @w{A revised} edition [ISBN 0-8048-2036-8] is
due 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 @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.

@node Marker Symbols, , Text String Format, Text and Markers
@appendixsection Available marker symbols

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

@enumerate 0
@item no symbol at all
@item dot
@tex
($\thinspace\cdot\thinspace$)
@end tex
@item plus (@math{+})
@item asterisk (@math{*})
@item circle
@tex
($\circ$)
@end tex
@item cross
@tex
($\times$)
@end tex
@item square
@item triangle
@item diamond
@item star
@item inverted triangle
@item starburst
@item fancy plus
@item fancy cross
@item fancy square
@item fancy diamond
@item filled circle
@item filled square
@item filled triangle
@item filled diamond
@item filled inverted triangle
@item filled fancy square
@item filled fancy diamond
@item half filled circle
@item half filled square
@item half filled triangle
@item half filled diamond
@item half filled inverted triangle
@item half filled fancy square
@item half filled fancy diamond
@item octagon
@item filled octagon
@end enumerate

@noindent
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 @code{libplot}, it is the current font.  For @code{graph}, it is the
font selected with the @samp{--symbol-font-name} option.  By default,
this is the ZapfDingbats font except in @code{graph-tek}.
@code{graph-tek} currently has no access to Postscript fonts, so it uses
the @code{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

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

@noindent
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).

@node Color Names, Metafiles, Text and Markers, Appendices
@appendix Specifying Colors by Name

Many of the plotting utilities allow colors to be specified by name.
For example, @code{graph} supports the @samp{--frame-color} option.  The
@code{libplot} function library includes the @t{pencolorname} and
@t{fillcolorname} functions.  All of these take a single string as an
argument.  @w{It is} interpreted as the name of a color.

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 @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 versions of the @w{X
Window} System, which on most machines are listed in the file
@file{/usr/lib/X11/rgb.txt}.  However, for every color name containing
the string "gray", @w{a version} containing "grey" has been included.
For example, both "dark slate gray 4" and "dark slate grey 4" are
recognized color names.

@node Metafiles, Auxiliary Software, Color Names, Appendices
@appendix The Graphics Metafile Format

A GNU graphics metafile, which is produced by raw @code{graph} or by any
other graphics application linked with raw @code{libplot}, is a sort of
audit trail.  It contains a record of which @code{libplot} functions
have been called, together with their arguments.  @w{That is}, @w{it is}
a sequence of plotting commands, each of which may be followed by data.
Each command is an @w{`op code'}: @w{a single} ASCII character,
indicating which @code{libplot} function was called.  The data following
the command are the arguments of the function.  Arguments may be
null-terminated ASCII strings, or double precision floating point
numbers in binary format, or signed, two byte integers in binary format.
The last are used as a means of storing integer arguments.

For example, the @code{libplot} function call @code{move}(3,5), which
moves the graphics cursor to the position (3,5), could appear in a
graphics metafile as @code{m\000\003\000\005}.  The byte order of the
binary representation of the signed, two-byte integers is machine
dependent, so that on some machines, this command would appear as
@code{m\003\000\005\000}.  This machine dependence affects the
representation of all @code{libplot} functions that take integer
arguments.

The confusion over the proper representation for integers goes back to
the `plot(5)' format produced by non-GNU versions of @code{graph}.  GNU
graphics metafiles, which use an enhanced version of this format, may
include double precision floating point numbers @w{as well} as integers,
but the confusion over integer representations remains.  @w{In fact} it
has become slightly worse.  The two-byte representation described above
is no longer the default representation produced by GNU @code{libplot}.
By default, integer arguments to @code{libplot} functions are now
represented in GNU metafiles as short integers.  On some machines a
short integer may occupy more than two bytes.

There is also a portable (ASCII) version of GNU metafile format, which
is less confusing.  @w{It is} produced by raw @code{graph} when the
@samp{-O} option is specified, and read by the GNU plot filters when the
@samp{-I} option is specified.  In the portable version, the arguments
to each single-letter command are supplied in human readable form,
separated by spaces, and each argument list ends with a newline.  This
representation is acceptable because @code{libplot} functions include a
maximum of one string among their arguments, and this string may not
include a newline.  Moreover, the string must come last among the
arguments.

The following table lists some of the @w{op codes}, i.e.,
single-character commands, followed by the name of the @code{libplot}
function they stand for.  All @code{libplot} functions have a
corresponding single-character command, with the exception of @w{(1)
the} setup functions @code{openpl} and @code{closepl}, @w{(2) the}
functions @code{labelwidth} and @code{flabelwidth}, which simply return
the width of a text string, and @w{(3) the} @code{pencolorname} and
@code{fillcolorname} functions, which are mapped to @code{pencolor} and
@code{fillcolor} internally.

@table @asis
@item Op Code
Function
@item @samp{a}
@code{arc}
@item @samp{c}
@code{circle}
@item @samp{e}
@code{erase}
@item @samp{f}
@code{linemod}
@item @samp{l}
@code{line}
@item @samp{m}
@code{move}
@item @samp{n}
@code{cont}
@item @samp{p}
@code{point}
@item @samp{s}
@code{space}
@item @samp{t}
@code{label}
@end table

@noindent
The above are actually the op codes of the traditional `plot(5)' format.
They are also used in GNU metafiles, since the GNU metafile format is
compatible @w{with it}.  The @w{op codes} standing for the other
functions in @code{libplot} are too numerous to list.  They are defined
in the file @code{plot.h}, which is distributed along with the GNU
plotting utilities.


@node Auxiliary Software, Acknowledgements, Metafiles, Appendices
@appendix Obtaining Auxiliary Software

@menu
* idraw::	Obtaining the idraw drawing editor
* xfig::       	Obtaining the xfig drawing editor
@end menu

@node idraw, xfig, Auxiliary Software, Auxiliary Software
@section How to get @code{idraw}

The @code{idraw} utility mentioned several times in this documentation
is a freely distributable interactive drawing editor for the @w{X
Window} System.  It may be used to edit the output of @code{graph-ps},
or, in general, the output of any application linked with the
@code{libplotps} version of @code{libplot}.

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

Also available from @code{http://www.vectaport.com} is an enhanced
version of @code{idraw} called @code{drawtool}.  Unlike @code{idraw},
@code{drawtool} can import bitmapped graphics in PBM/PGM/PPM, TIFF, and
X11 bitmap formats.

@node xfig, , idraw, Auxiliary Software
@section How to get @code{xfig}

The @code{xfig} utility mentioned several times in this documentation is
a freely distributable interactive drawing editor for the @w{X Window}
System.  It may be used to edit the output of @code{graph-fig}, or, in
general, the output of any application linked with the @code{libplotfig}
version of @code{libplot}.

The current version is available in
@code{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 @code{transfig}, which
allows @code{xfig} graphics to be exported in many formats.  GIF, X11
bitmap, La@TeX{}, and Postscript formats are supported.

@node Acknowledgements, , Auxiliary Software, Appendices
@unnumbered Acknowledgements

Versions of @code{graph} and @code{plot} appeared in many early releases
of Unix, going at least as far back as the @w{Version 7} distribution
from Bell Laboratories.  Supported devices in those days (@w{c.@: 1980})
included 200@dmn{dpi} electrostatic printer/plotters from Versatec and
Varian, pen plotters from Hewlett--Packard, Tektronix storage scopes,
and early graphics terminals.

Rich Murphey @t{<rich@@lamprey.utmb.edu>} wrote the first GNU versions
of @code{graph}, @code{plot}, and @code{spline}, and the earliest
documentation.  Richard Stallman @t{<rms@@gnu.ai.mit.edu>} further
directed development of the programs and provided editorial support for
the documentation.  John Interrante @t{<interran@@uluru.stanford.edu>}
generously provided the @code{idraw} Postscript prologue now included in
@code{libplotps}, and helpful comments.  The distribution, as it stood
in 1991, was distributed under the name `GNU graphics'.

In 1995 Robert Maier @t{<rsm@@math.arizona.edu>} took over development
of the package, and wrote the current, maximally device-independent,
standalone versions of @code{libplot}.  He also rewrote @code{graph}
from scratch, turning it into a real-time filter that would use the new
libraries.  He fleshed out @code{spline} too, by adding support for
splines in tension, periodicity, and cubic Bessel interpolation.

Most development work on @code{ode} was performed by Nick Tufillaro
@t{<nbt@@reed.edu>} in 1978--1994, on a sequence of platforms that
extended back to a PDP-11 running @w{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 @code{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 @code{libplot}
are @w{of course} based on the characters digitized in the mid to late
1960's by @w{Allen V.} Hershey.  Additional characters and/or marker
symbols were taken from the SLAC Unified Graphics System developed by
@w{Robert C.}  Beach in the mid-1970's, and from the fonts designed by
Thomas Wolff @t{<wolff@@inf.fu-berlin.de>} for Ghostscript.  Arthur
Smith, formerly of LASSP at Cornell, provided code for his @code{xplot}
utility.  @w{Ray Toy} @t{<toy@@rtp.ericsson.se>} helped with the tick
mark spacing code in @code{graph} and was the first to incorporate GNU
@code{getopt}.  Peter Karnow of URW and Ken Turkowski of Apple
@t{<turk@@apple.com>} developed the `sagitta' algorithm used in an
extended form in @code{libplot} for drawing circular and elliptic arcs.
Nelson Beebe exhaustively tested the package installation process, and
discovered many bugs.

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

@contents
@bye
