\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename plotutils.info
@settitle The Plotutils Package
@c For double-sided printing, uncomment:
@c @setchapternewpage odd
@c %**end of header

@dircategory GNU Plotting Utilities
@direntry
* Plotting utilities: (plotutils).      GNU plotting utilities
* graph: (plotutils)graph Invocation.   Plot datasets, possibly in real time
* plot: (plotutils)plot Invocation.     Convert and display plot files
* pic2plot: (plotutils)pic2plot Invocation.   Convert files in the pic language
* tek2plot: (plotutils)tek2plot Invocation.   Translate legacy Tektronix data
* plotfont: (plotutils)plotfont Invocation.   Plot character maps of fonts
* spline: (plotutils)spline Invocation. Interpolate between points in datasets
* ode: (plotutils)ode Invocation.       Integrate differential equations
* libplot: (plotutils)libplot.          A library for 2-D vector graphics
* Appendices: (plotutils)Appendices.    More info on the plotting utilities
@end direntry

@iftex
@hyphenation{Zapf-Ding-bats Hershey-Serif-Symbol Hershey-Sans-Symbol}
@end iftex

@ifinfo
This file documents version 2.2 of the GNU plotting
utilities package, including GNU libplot 2.0

Copyright @copyright{} 1989--1999 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 2.2
@author Robert S. Maier and Nicholas B. Tufillaro
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1989--1999 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, Plotutils Intro, (dir), (dir)
@ifnottex
This is the documentation for version 2.2 of the GNU plotting
utilities package, including GNU libplot 2.0.  The package consists of
programs and functions for data plotting and vector graphics.
@end ifnottex

@menu
* Plotutils Intro::     GNU plotting utilities
* graph::               graph, a program for plotting datasets
* plot::                plot, a plot format conversion program
* pic2plot::            pic2plot, a translator for files in the pic language
* tek2plot::            tek2plot, a translator for legacy Tektronix files
* plotfont::            plotfont, a program for plotting font character maps
* spline::              spline, an interpolation program
* ode::                 ode, a differential equation integrator
* libplot::             A library for device-independent 2-D vector graphics
* Appendices::          Additional Information
@end menu

@node Plotutils Intro, graph, Top, Top
@chapter The GNU Plotting Utilities

The GNU plotting utilities consist of eight command-line programs: the
graphics programs @code{graph}, @code{plot}, @code{pic2plot},
@code{tek2plot}, and @code{plotfont}, and the mathematical programs
@code{spline}, @code{ode}, and @code{double}.  Distributed with these
programs is GNU @code{libplot}, the library on which the graphics
programs are based.  @code{libplot} is a function library for
device-independent two-dimensional vector graphics, including vector
graphics animations under the @w{X Window} System.  There are versions
for both C @w{and C++}.

The graphics programs and @code{libplot} can export vector graphics in
the following ten formats.

@table @asis
@item X
If this output option is selected, there is no output file.  Output is
directed to a popped-up window on an @w{X Window} System display.
@item PNM
This is ``portable anymap'' format.  There are three types of portable
anymap: PBM (portable bitmap, for monochrome images), PGM (portable
graymap), and PPM (portable pixmap, for colored images).  The output
file will be in whichever of these three formats is most appropriate.
Portable anymaps may be viewed or edited with many applications, such as
the free image display @w{application @code{xv}}.
@item GIF
This is pseudo-GIF format rather than true GIF format.  Unlike GIF
format it does not use LZW compression, so it does not transgress the
Unisys LZW patent.  However, files in pseudo-GIF format may be viewed or
edited with any application that understands GIF format, such @w{as
@code{xv}}.
@item AI
This is the format used by Adobe Illustrator.  Files in this format may
be edited with Adobe Illustrator (@w{version 5}, and more recent
versions), or other applications.
@item PS
This is @code{idraw}-editable Postscript format.  Files in this format
may be sent to a Postscript printer, imported into another document, or
edited with the free @code{idraw} drawing editor.  See @ref{idraw}.
@item Fig
This is a graphics format that may be displayed or edited with the free
@code{xfig} drawing editor.  See @ref{xfig}.
@item PCL 5
This is a powerful version of Hewlett--Packard's Printer Control
Language.  Files in this format may be sent to a LaserJet printer or
compatible device (note that most inkjets do not support @w{PCL 5}).
@item HP-GL
This is Hewlett--Packard's Graphics Language.  By default, the modern
variant HP-GL/2 is produced.  Files in HP-GL or HP-GL/2 format may be
imported into a document or sent to a plotter.
@item Tek
This is the graphics format understood by Tektronix 4014 terminals and
emulators, including the emulators built into the @code{xterm} terminal
emulator program and the MS-DOS version of @code{kermit}.
@item Metafile
This is device-independent GNU graphics metafile format.  The
@code{plot} program can translate it to any of the preceding formats.
@end table

Of the command-line graphics programs, the best known is @code{graph},
which is an application for plotting two-dimensional scientific data.
It reads one or more data files containing datasets, and outputs a plot.
The above output formats are supported.  The corresponding commands are
@code{graph @w{-T X}}, @code{graph -T pnm}, @code{graph -T gif},
@code{graph -T ai}, @code{graph -T ps}, @code{graph -T fig}, @code{graph
-T pcl}, @code{graph -T hpgl}, @code{graph -T tek}, and @code{graph}.
@code{graph} without a @samp{-T} option (referred to as `raw
@code{graph}') produces output in GNU metafile format.

@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 the size and
position of the plot on the display.  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.

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

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

The @code{pic2plot} program can translate from the pic language to any
supported output format.  The pic language, which was invented at Bell
Laboratories, is used for creating box-and-arrow diagrams of the kind
frequently found in technical papers and textbooks.  The corresponding
commands are @code{pic2plot @w{-T X}}, @code{pic2plot -T pnm},
@code{pic2plot -T gif}, @code{pic2plot -T ai}, @code{pic2plot -T ps},
@code{pic2plot -T fig}, @code{pic2plot -T pcl}, @code{pic2plot -T hpgl},
@code{pic2plot -T tek}, and @code{pic2plot}.

The @code{tek2plot} program can translate from Tektronix format to any
supported output format.  The corresponding commands are @code{tek2plot
@w{-T X}}, @code{tek2plot -T pnm}, @code{tek2plot -T gif},
@code{tek2plot -T ai}, @code{tek2plot -T ps}, @code{tek2plot -T fig},
@code{tek2plot -T pcl}, @code{tek2plot -T hpgl}, and @code{tek2plot}.
@code{tek2plot} is useful if you have an older application that produces
drawings in Tektronix format.

The @code{plotfont} program is a simple utility that displays a
character map for any font that is available to @code{graph},
@code{plot}, @code{pic2plot}, or @code{tek2plot}.  The 35 standard
Postscript fonts are available if the @samp{-T X}, @samp{-T ai},
@samp{-T ps}, or @samp{-T fig} options are used.  The 45 standard @w{PCL
5} fonts (i.e., ``LaserJet'' fonts) are available if the @samp{-T ai},
@samp{-T pcl} or @samp{-T hpgl} options are used.  In the latter two
cases (@samp{-T pcl} and @samp{-T hpgl}), @w{a number} of
Hewlett--Packard vector fonts are available @w{as well}.  @w{A set} of
22 Hershey vector fonts, including Cyrillic fonts and a Japanese font,
is always available.  When producing output for an @w{X Window System}
display, any of the graphics programs can use scalable @w{X fonts}.

Of the command-line mathematical programs, @code{spline} does spline
interpolation of scalar or vector-valued data.  It normally uses either
cubic spline interpolation or exponential splines in tension, but like
@code{graph} @w{it can} function as a real-time filter under some
circumstances.  Besides splining datasets, @w{it can} construct curves,
either open or closed, through arbitrarily chosen points in
@math{d}-dimensional space.  @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.  The final command-line mathematical program, @code{double},
is a filter for converting, scaling and cutting binary or ASCII data
streams.  @w{It is} still under development and is not yet documented.

The @code{libplot} function library is discussed at length elsewhere in
this documentation.  @w{It gives} C @w{and C++} programs the ability to
draw such objects as lines, open and closed polylines, arcs (both
circular and elliptic), quadratic and cubic Bezier curves, circles and
ellipses, points, marker symbols, and text strings.  The filling of
objects other than points, marker symbols, and text strings is supported
(fill color, @w{as well} as pen color, can be set arbitrarily).  Text
strings can be drawn in any of a large number of fonts.  The 35 standard
Postscript fonts are supported by the @w{X Window} System, Illustrator,
Postscript, and @code{xfig} drivers, and the 45 standard @w{PCL 5} fonts
are supported by the Illustrator, @w{PCL 5} and HP-GL/2 drivers.  The
latter two also support a number of Hewlett--Packard vector fonts.  All
drivers, including the PNM, GIF, Tektronix and metafile drivers, support
a set of 22 Hershey vector fonts.

The support for drawing text strings is extensive.  Text strings may
include subscripts and superscripts, and may include characters chosen
from more than one font in a typeface.  Many non-alphanumeric characters
may be included.  The entire collection of over 1700 `Hershey glyphs'
digitized by @w{Allen V.} Hershey at the U.S. Naval Surface Weapons
Center, which includes many curious symbols, is built into
@code{libplot}.  Text strings in the so-called EUC-JP encoding (i.e.,
the Extended Unix Code for Japanese) can be also be drawn.  Such strings
may include both syllabic Japanese characters (Hiragana and Katakana)
and ideographic Japanese characters (Kanji).  @w{A library} of 603
Kanji, including 596 of the 2965 frequently used @w{Level 1} Kanji, is
built into @code{libplot}.

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

@node graph, plot, Plotutils Intro, Top
@chapter The @code{graph} Application

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
* Non-Square Plots::    Rotating and changing the aspect ratio of a plot
* Multiple Datasets::   Preparing a plot from more than one dataset
* Multiplotting::       Multiple plots on a single page
* Data Formats::        Reading binary and other data formats
* graph Invocation::    Command-line options
@end menu

@node Simple Examples, Non-Square Plots, graph, graph
@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 @code{graph}, you could do

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

@noindent
or equivalently

@example
graph -T 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, display on a screen, or send
directly to a printer.  (The @samp{--page-size} option, or the
@code{PAGESIZE} environment variable, specifies the size of the printed
page.  The default is "letter", i.e., 8.5@dmn{in} by 11@dmn{in}, but
"a4" or other ISO or ANSI page sizes can be specified instead.)

You may also do

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

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

@example
graph -T ai < ascii_data_file > plot.ai
@end example

@noindent
to produce a file @code{plot.ai} that you may edit with Adobe
Illustrator.  If you do

@example
graph -T hpgl < ascii_data_file > plot.plt
@end example

@noindent
you will produce a file @code{plot.plt} in the Hewlett--Packard Graphics
Language (HP-GL/2) that you may send to a Hewlett--Packard plotter.
Similarly, you may use @code{graph -T pcl} to produce a file in @w{PCL
5} format that may be printed on a LaserJet or other laser printer.

You may use @code{graph @w{-T X}} 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 -T X < ascii_data_file
@end example

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

You may also use @code{graph -T pnm} to produce a PNM file (a ``portable
anymap''), and @code{graph -T gif} to produce a pseudo-GIF file.  If the
free image display application @code{xv} is available on your system,
you would use either of the two commands

@example
graph -T pnm < ascii_data_file | xv -
graph -T gif < ascii_data_file | xv -
@end example

@noindent
to display the output file.

Another thing you can do is use @code{graph -T 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 -T 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 MS-DOS version of @code{kermit}.

@code{graph} may behave differently depending on the environment in
which it is invoked.  We have already mentioned the @code{PAGESIZE}
environment variable, which affects the operation of @code{graph -T ai},
@code{graph -T ps}, @code{graph -T fig}, @code{graph -T pcl}, and
@code{graph -T hpgl}.  Similarly, the @code{BITMAPSIZE} environment
variable affects the operation of @code{graph @w{-T X}}, @code{graph -T
pnm}, and @code{graph -T gif}.  The @code{DISPLAY} environment variable
affects the operation of @code{graph @w{-T X}}, and the @code{TERM}
environment variable affects the operation of @code{graph -T tek}.
There are also several environment variables that affect the operation
of @code{graph -T pcl} and @code{graph -T hpgl}.  For a complete
discussion of the effects of the environment on @code{graph}, see
@ref{graph Environment}.  The following remarks apply irrespective of
which output format is specified.

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

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

@noindent
Here @samp{-m 2} indicates that linemode #2 should be used.  @w{If the}
dataset is rendered in monochrome, which is the default, the line can be
drawn in one of five distinct styles.  Linemodes #1 through #5 signify
solid, dotted, dotdashed, shortdashed, and longdashed; thereafter the
sequence repeats.  @w{If the} @samp{-C} option is used, the dataset will
be rendered in color.  For colored datasets, the line can 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.,
@w{shade it}, or fill it with a solid color), you may use the @samp{-q}
option.  @w{For example},

@example
echo .1 .1 .1 .9 .9 .9 .9 .1 .1 .1 | graph -T 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 specifies.  @w{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.  @w{If the} intensity were negative,
the region would be unfilled, or transparent (the default).

You may choose the thickness (`width') of the line, whether it is filled
or not, by using the @samp{-W} option.  @w{For example}, @samp{-W 0.01}
specifies that the line should have a thickness equal to 0.01 times the
size of the display.  Also, you may put symbols at each data point along
the line by doing, @w{for example},

@example
graph -T 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
display types, 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, @w{for example},

@example
graph -T 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.  @w{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.  @w{If
they} are absent, they default to 1.0 and 0.0 respectively.  For
example, the command

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

@noindent
produces exactly the same plot  as

@example
echo 0 0 1 1 2 0 | graph -T 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 -T 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.  @w{For example},
using @samp{-y -1 2 1} rather than @samp{-y -1 2} will produce a
@w{@math{y} axis} with labeled ticks at @minus{}1, 0, 1, @w{and 2},
rather than at the locations that @code{graph} would choose by default,
which would be @minus{}1, @minus{}0.5, 0, 0.5, 1, 1.5, @w{and 2}.  @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 -T 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 there are tick marks at each
power of ten and at its integer multiples.  The tick marks at the powers
of ten are labeled.  If the axis spans more than five orders of
magnitude, the tick marks at the integer multiples are omitted.

If you have an unusually short logarithmic axis, you may need to
increase the number of labeled ticks.  To do this, you should specify a
tick spacing manually.  @w{For example}, @samp{-l x -x 1 9 2} would
produce a plot in which the @w{@math{x} axis} is logarithmic and extends
from 1 @w{to 9}.  Labeled ticks would 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 -T 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 90 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, @w{for example},

@example
echo 1 1 2 3 3 1 | graph -T 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 -T 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 can 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, unless
@samp{-T pnm}, @samp{-T gif}, @samp{-T pcl}, @samp{-T hpgl} or @samp{-T
tek} is specified).  Font names are case-insensitive, so @samp{-F
times-roman} will work equally well.  The available fonts include 35
Postscript fonts (for all variants of @code{graph} other than
@code{graph -T pnm}, @code{graph -T gif}, @code{graph -T pcl},
@code{graph -T hpgl} and @code{graph -T tek}), 45 @w{PCL 5} fonts (for
@code{graph -T ai}, @code{graph -T pcl} and @code{graph -T hpgl}), a
number of Hewlett--Packard vector fonts (for @code{graph -T pcl} and
@code{graph -T hpgl}), and 22 Hershey vector fonts.  The Hershey fonts
include HersheyCyrillic, for Russian, and HersheyEUC, for Japanese.  For
a discussion of the available fonts, see @ref{Text Fonts}.  The
@code{plotfont} utility will produce a character map of any available
font.  @xref{plotfont}.

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, see
@ref{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 @w{no grid} @w{at all}, @w{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
@section Rotated, non-square and displaced plots

To rotate the plotting box by 90 degrees counterclockwise on your
graphics display, you would add @samp{--rotation 90} to the @code{graph}
command line.  You may also specify @samp{--rotation 180}, to produce an
upside-down plot, or @samp{--rotation 270}.

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

@example
graph -T 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 by convention is a square.  @w{By default},
the height and width of the plotting box equal 0.6, and the `upward
shift' and the `rightward shift' @w{equal 0.2}.  @w{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.

Several command-line options specify sizes or dimensions as fractions of
the size of the plotting box, rather than as fractions of the size of
the display.  For example, @samp{-S 3 .01} specifies that the plotting
symbols for the following dataset should be of @w{type #3}, and should
have a font size equal @w{to 0.01}, i.e. 0.01 times the minimum
dimension (height or width) of the plotting box.  If the @samp{-h} or
@samp{-w} options are employed to expand or contract the plot, such
sizes or dimensions will scale in tandem.  That is presumably the right
thing @w{to do}.

The @samp{-h}, @samp{-w}, @samp{-r}, and @code{-u} options may be
combined with the @samp{--rotation} option.  If they appear together,
the plotting box is first positioned, and then rotated.  @w{In fact},
@samp{--rotation} specifies how the plot should be mapped to the
graphics display, rather than how the plot is designed.

The `graphics display' is an abstraction.  For @code{graph @w{-T X}}, it
is a window on an @w{X display}.  For @code{graph -T pnm} and
@code{graph -T gif}, it is a square or rectangular bitmap.  In these
three cases, the size of the graphics display can be set by using the
@code{--bitmap-size} option, or by setting the @code{BITMAPSIZE}
environment variable.  For @code{graph -T tek}, the graphics display is
a square region occupying the central part of a Tektronix display.
(Tektronix displays are 4/3 times as wide as they are high.)  For
@code{graph -T ai} and @code{graph -T ps}, @w{by default} it is a square
region centered on an 8.5@dmn{in} by 11@dmn{in} page (@w{US letter}
size), occupying its full width with allowance being made for margins.
For @code{graph -T fig}, @w{by default} it is a square region of the
same size, positioned in the upper left corner of an @code{xfig}
display.  For @code{graph -T pcl} and @code{graph -T hpgl}, @w{by
default} it is a square region of the same size, with position and
orientation on the page being controlled by environment variables.  The
page size used by @code{graph -T ai}, @code{graph -T ps}, @code{graph -T
fig}, @code{graph -T pcl}, and @code{graph -T hpgl} can be set by using
the @code{--page-size} option, or by setting the environment variable
@code{PAGESIZE}.  @w{For example}, setting @code{PAGESIZE} to "a4" would
position the graphics display appropriately on an A4-size page
(21@dmn{cm} by 29.7@dmn{cm}).

@node Multiple Datasets, Multiplotting, Non-Square Plots, graph
@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.  @w{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 can 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 @w{at all}, @w{for example}.  `Linewidth' means line
thickness; @w{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, @w{for example}.  @w{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 -T 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 linemode #0, so
successive points will not be joined by lines.  But symbol #3 (an
asterisk) will be plotted at each point.  The dataset in @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 with
thickness 0.02, as a fraction of the size (i.e., minimum dimension) 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.  @w{For example},
you could do

@example
graph -T 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 @w{name @samp{-}},
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.  @w{By
default}, the linemode is incremented (`bumped') from one dataset to the
next.  This feature is usually quite convenient.  @w{For example}, if
you do

@example
graph -T 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.  @w{In fact} if you do

@example
graph -T 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{}.  @w{If you} do not like this feature, you may turn it
off, or in general @w{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
@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 an ordinary 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.

@example
graph -T ps data_file_1 --reposition .35 .35 .3 data_file_2
@end example

@noindent
Here @code{data_file_1} is plotted in the usual way.  The
@samp{--reposition} option specifies that when @code{data_file_2} is
plotted, it will be drawn within a virtual display.  For the purposes of
the @samp{--reposition} option, the physical display is a square with
lower left corner (0.0,0.0) and upper right corner (1.0,1.0).  In those
coordinates, the virtual display will be a square of size 0.3 with lower
left corner (0.35,0.35).  @w{So the} second sub-plot will be inset into
the first.

Just as the @samp{-w}, @samp{-h}, @samp{-r}, and @samp{-u} options may
be used to set the size and position of a plotting box within the
physical display, so they may be used to set the size and position of a
plotting box within a virtual display.  For example,

@example
graph -T ps data_file_1 --reposition .35 .35 .3 -w .4 -r .3 data_file_2
@end example

@noindent
will yield a multiplot in which the second sub-plot is significantly
different.  Its plotting box will have a width only 0.4 times the width
of the virtual display.  However, the plotting box will be centered
within the virtual display, since the distance between the left edge of
the plotting box and the left edge of the virtual display will be 0.3
times the width of the virtual display.

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.  @w{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.  @w{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.) can 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, graph Invocation, Multiplotting, graph
@section Reading binary and other data formats

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

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.  @w{If you} have very large datasets, using
binary format may reduce storage and runtime costs.

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

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

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

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

@ifnottex
@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
the largest possible number.  For single precision datasets this is the
quantity @code{FLT_MAX}, for double precision datasets it is the
quantity @code{DBL_MAX}, and for integer datasets it is the quantity
@code{INT_MAX}.  @w{On most} machines @code{FLT_MAX} is approximately
3.4x10^38, @code{DBL_MAX} is approximately 1.8x10^308, and
@code{INT_MAX} is 2^32-1.
@end ifnottex
@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
the largest possible number.  For single precision datasets this is the
quantity @code{FLT_MAX}, for double precision datasets it is the
quantity @code{DBL_MAX}, and for integer datasets it is the quantity
@code{INT_MAX}.  @w{On most} machines @code{FLT_MAX} is approximately
$3.4\times10^{38}$, @code{DBL_MAX} is approximately $1.8\times10^{308}$,
and @code{INT_MAX} is $2^{31}-1$.
@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 -T ps -I f binary_data_file -I a ascii_data_file > plot.ps
@end example

@noindent
will read @code{binary_data_file} in @samp{f} (binary single 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 ASCII `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 six supported data formats, @samp{a} (normal
ASCII), @samp{e} (ASCII with error bars), @samp{g} (the ASCII `table'
format produced by @code{gnuplot}), @samp{f} (binary single precision),
@samp{d} (binary double precision), and @samp{i} (binary integer).
Input files may be in any of these six formats.

@node graph Invocation, , Data Formats, graph
@section @code{graph} command-line options

The @code{graph} program reads one or more datasets from files named on
the command line or from standard input, and prepares a plot.  The
output format or display type is specified with the @samp{-T} option.

By default, @code{graph} reads ASCII data from the files specified on
the command line.  The data are pairs of numbers, interpreted as the
@math{x} @w{and @math{y}} coordinates of data points.  If no file names
are specified, or the file @w{name @samp{-}} is specified, the standard
input is read.  The output file is written to standard output, unless
the @samp{-T X} option is specified.  @w{In that} case the graph is
displayed in a window on an @w{X Window} System display, and there is no
output file.

There are many command-line options for adjusting the visual appearance
of the plot.  The relative order of file names and command-line options
is important.  Only the options that precede a file name on the command
line take effect for that file.

The following sections list the possible options.  Each option that
takes an argument is followed, in parentheses, by the type and default
value of the argument.  There are five sorts of option.

@iftex
@enumerate
@item
Options affecting an entire plot.  (@xref{Plot Options}.)

@item
Options affecting the reading and drawing of individual datasets within a plot.
(@xref{Dataset Options}.)

@item
Options for multiplotting (drawing several sub-plots within a plot).
(@xref{Multiplot Options}.)

@item
Options relevant only to raw @code{graph}, i.e., relevant only if no
display type or output format is specified with the @samp{-T} option.
(@xref{Raw graph Options}.)

@item
Options requesting information (e.g., @samp{--help}).
(@xref{Info Options}.)
@end enumerate
@end iftex

@ifnottex
The behavior of @code{graph} is also affected by a number of environment
variables, so there is a section discussing them as well.
@end ifnottex

@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 relevant only to raw graph
* Info Options::        Options requesting information (e.g., ---help)
* graph Environment::   Environment variables
@end menu

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

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

@table @samp
@item -T @var{type}
@itemx --display-type @var{type}
(String, default "meta".)  Select a display type or output format of
type @var{type}, which may be one of the strings "X", "pnm", "gif",
"ai", "ps", "fig", "pcl", "hpgl", "tek", and "meta".  These refer
respectively to the @w{X Window System}, portable anymap (PBM/PGM/PPM)
format, pseudo-GIF format, the format used by Adobe Illustrator,
@code{idraw}-editable Postscript, the format used by the @code{xfig}
drawing editor, the Hewlett--Packard @w{PCL 5} printer language, the
Hewlett--Packard Graphics Language (@w{by default}, HP-GL/2), Tektronix
format, and device-independent GNU graphics metafile format.

@item -E @var{x|y}
@itemx --toggle-axis-end @var{x|y}
Set the position of the indicated axis to be on the other end of the
plotting box from what is currently the case.  E.g., @samp{-E y} will
cause the @math{y} axis to appear on the right of the plot rather than
the left, which is the default.  Similarly, @samp{-E x} 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).

@item -f @var{size}
@itemx --font-size @var{size}
(Float, default 0.0525.)  Set the size of the font used for the axis and
tick labels to be @var{size}.  The size is specified as a fraction of
the minimum dimension (width or height) of the plotting box.

@item -F @var{font_name}
@itemx --font-name @var{font_name}
(String, default "Helvetica" except for @code{graph -T pnm}, @code{graph
-T gif}, @code{graph -T pcl}, @code{graph -T hpgl}, @code{graph -T tek},
and raw @code{graph}, for all of 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.  @w{If the} specified font is
not available, the default font will be used.  Which fonts are available
depends on which @samp{-T} option is used.  For a list of all fonts, see
@ref{Text Fonts}.  The @code{plotfont} utility will produce a character
map of any available font.  @xref{plotfont}.

@item -g @var{grid_style}
@itemx --grid-style @var{grid_style}
(Integer in the range 0@dots{}4, default 2.)  Set the grid style for the
plot to be @var{grid_style}.  Grid styles 0 through 3 are progressively
more fancy, but @w{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 that fills the available area.  Note that tick marks and
labels are outside the plotting box, so that values less than 1.0 are
generally used.

@item -k @var{length}
@itemx --tick-size @var{length}
(Float, default .02.)  Set the length of the tick marks on each axis to
be @var{length}.  @w{A value} of 1.0 produces tick marks whose length is
equal to the minimum dimension (width or height) of the plotting box.
@w{A negative} @var{length} yields tick marks that extend outside the
box, rather than inside.

@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{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 -L @var{top_label}
@itemx --top-label @var{top_label}
(String, default empty.)  Place the text string @var{top_label} above
the plot, as its `top label', i.e., 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 labeling axes
and ticks, as selected by the @samp{-F} option.  But this can be
overridden with the @samp{--title-font-name} option.

@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{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 -R @var{x|y}
@itemx --toggle-round-to-next-tick @var{x|y}
Toggle whether or not the upper and lower limits of the specified axis
should be expanded, so that they both become integer multiples of the
spacing between labeled tick marks.

This option is meaningful whenever the user specifies either or both of
the limits, by using the @samp{-x} or @samp{-y} option.  @w{If the} user
leaves both limits unspecified, they will always be chosen to satisfy
the `integer multiple' constraint.

@item -s
@itemx --save-screen
Save the screen.  This option requests that @code{graph} not erase the
display device before it begins to plot.  

This option is relevant only to @code{graph -T tek} and raw
@code{graph}.  Tektronix displays and emulators are persistent, in the
sense that previously drawn graphics remain visible.  So by repeatedly
using @code{graph -T tek -s}, you can @w{build up} a multiplot.

@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
@w{@math{y} axis} rather than the @w{@math{x} axis}.  @w{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.
@w{If any} of the three arguments is missing or is supplied @w{as
@samp{-}} (i.e., as a single hyphen), @w{it is} computed from the data.
Both arguments @var{lower_limit} and @var{upper_limit} must be present
if @code{graph} is to act as a real-time filter.

By default, the supplied limit(s) are strictly respected.  However, the
@samp{-R x} option may be used to request that they be rounded to the
nearest integer multiple of the spacing between labeled ticks.  The
lower limit will be rounded downward, and the upper limit upward.

@item -X @var{x_label}
@itemx --x-label @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{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).  Both arguments @var{lower_limit} and @var{upper_limit} must be
present if @code{graph} is to act as a real-time filter.

By default, the supplied limit(s) are strictly respected.  However, the
@samp{-R y} option may be used to request that they be rounded to the
nearest multiple of the tick spacing.  The lower limit will be rounded
downward, and the upper limit upward.

@item -Y @var{y_label}
@itemx --y-label @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 90 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 can be used to specify the name of the font and the size of the
font.

@item --bg-color @var{name}
(String, default "white".)  Set the color used for the plot background
to be @var{name}.  This is relevant only to @code{graph @w{-T X}},
@code{graph -T pnm}, and @code{graph -T gif}.  @w{An unrecognized} name
sets the color to the default.  For information on what names are
recognized, see @ref{Color Names}.  The environment variable
@code{BG_COLOR} can equally well be used to specify the background
color.

If the @samp{-T gif} option is used, a transparent pseudo-GIF may be
produced by setting the @code{TRANSPARENT_COLOR} environment variable to
the name of the background color.  @xref{graph Environment}.

@item --bitmap-size @var{bitmap_size}
(String, default "570x570".)  Set the size of the graphics display in
which the plot will be drawn, in terms of pixels, to be
@var{bitmap_size}.  This is relevant only to @code{graph @w{-T X}},
@code{graph -T pnm}, and @code{graph -T gif}, for which the graphics
display size can be expressed in terms of pixels.  The environment
variable @code{BITMAPSIZE} can equally well be used to specify the size.

The graphics display used by @code{graph -T X} is an @w{X window}.  If
you choose a rectangular (non-square) window size, the fonts in the plot
will be scaled anisotropically, i.e., by different factors in the
horizontal and vertical direction.  This requires an X11R6 display.  Any
font that cannot be scaled in this way will be replaced by a default
scalable font, such as the Hershey vector font "HersheySerif".

For backward compatibility, the @w{X resource} @code{Xplot.geometry},
which can be set by the user, may be used to set the window size,
instead of @samp{--bitmap-size} or @code{BITMAPSIZE}@.

@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, see @ref{Color Names}.

@item --frame-line-width @var{frame_line_width}
(Float, default @minus{}1.0.)  Set the thickness of lines in the plot
frame, as a fraction of the size (i.e., minimum dimension) of the
graphics display, to @var{frame_line_width}.  @w{A negative} value means
that the default value for the line thickness provided by the
@code{libplot} graphics library should be used.  This is usually 1/850
times the size of the display, although if @samp{-T X}, @samp{-T pnm},
or @code{-T gif} is specified, it is zero.  By convention, a
zero-thickness line is the thinnest line that can be drawn.  This is the
case in all output formats.  Note, however, that the drawing editors
@code{idraw} and @code{xfig} treat zero-thickness lines as invisible.

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

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

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

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

For @code{graph -T ai} and @code{graph -T ps}, the graphics display
within which the plot is drawn will be a square region centered on the
specified page, occupying its full width (with allowance being made for
margins).  For @code{graph -T fig}, it will be a square region of the
same size, located in the upper left corner of an @code{xfig} display.
For @code{graph -T pcl} and @code{graph -T hpgl}, the graphics display
will be a square region of the same size, but may be positioned
differently.  Fine control over its positioning on the page can be
accomplished by setting certain environment variables (@pxref{graph
Environment}).

@item --pen-colors @var{colors}
(String, default "1=red:2=green:3=blue:4=magenta:5=cyan".)  Set the
colors of the pens used for drawing plots, as numbered, to be
@var{colors}.  The format should be self-explanatory.  @w{An
unrecognized} name sets the corresponding color to the default.  For
information on what names are recognized, see @ref{Color Names}.

@item --rotation @var{angle}
(Integer, default 0.)  Set the rotation angle of the plot within the
graphics display to be @var{angle} degrees.  Recognized values are 0,
90, 180, and 270.  The rotation is counterclockwise.

This option is used for switching between portrait mode and landscape
mode.  Postmodernists may also find it useful.

@item --title-font-name @var{font_name}
(String, default "Helvetica" except for @code{graph -T pnm}, @code{graph
-T gif}, @code{graph -T pcl}, @code{graph -T hpgl} and @code{graph -T
tek}, for which "HersheySerif" is the default.)  Set the font used for
the plot title to be @var{font_name}.  Normally the font used for the
plot title is the same as that used for labeling the axes and the ticks
along the axes, as specified by the @samp{-F} option.  But the
@samp{--title-font-name} option can be used to override this.  Font
names are case-insensitive.  If the specified font is not available, the
default font will be used.  Which fonts are available depends on which
@samp{-T} option is used.  For a list of all fonts, see @ref{Text
Fonts}.  The @code{plotfont} utility will produce a character map of any
available font.  @xref{plotfont}.

@item --title-font-size @var{size}
(Float, default 0.07.)  Set the size of the font used for the top label
(`title'), as specified by the @samp{-L} option, to be @var{size}.  The
size is specified as a fraction of the minimum dimension (width or
height) 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 parallel to the @w{@math{y} axis}.
But some display devices (e.g., old @w{X Window} System displays) cannot
handle rotated fonts.
@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 is a sequence of floating point numbers,
interpreted as the @math{x} @w{and @math{y}} coordinates of the
successive 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.

@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 ASCII `table' format produced by the @code{gnuplot} plotting program.

@item f
@ifnottex
Single precision binary format.  Each input file is a sequence of single
precision floating point numbers, interpreted as forming pairs
(@math{x},@math{y}).  Successive datasets are separated by a single
occurrence of the quantity @code{FLT_MAX}, which is the largest possible
single precision floating point number.  @w{On most} machines this is
approximately 3.4x10^38.
@end ifnottex
@tex
Single precision binary format.  Each input file is a sequence of single
precision floating point numbers, interpreted as forming pairs
(@math{x},@math{y}).  Successive datasets are separated by a single
occurrence of the quantity @code{FLT_MAX}, which is the largest possible
single precision floating point number.  @w{On most} machines this is
approximately $3.4\times10^{38}$.
@end tex

@item d
@ifnottex
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{DBL_MAX}, which is the largest possible
double precision floating point number.  @w{On most} machines this is
approximately 1.8x10^308.
@end ifnottex
@tex
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{DBL_MAX}, which is the largest possible
double precision floating point number.  @w{On most} machines this is
approximately $1.8\times10^{308}$.
@end tex

@item i
@ifnottex
Integer binary format.  Each input file is a sequence of integers,
interpreted as forming pairs (@math{x},@math{y}).  Successive datasets
are separated by a single occurrence of the quantity @code{INT_MAX},
which is the largest possible integer.  @w{On most} machines this is
2^31-1.
@end ifnottex
@tex
Integer binary format.  Each input file is a sequence of integers,
interpreted as forming pairs (@math{x},@math{y}).  Successive datasets
are separated by a single occurrence of the quantity @code{INT_MAX},
which is the largest possible integer.  @w{On most} machines this is
$2^{31}-1$.
@end tex
@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 (@samp{a}, @samp{e},
@samp{f}, @samp{d}, @w{or @samp{i}}), this option specifies that the
abscissa (@math{x}) values are missing from the input file: the
dataset(s) to be read contain only ordinate (@math{y}) values.  The
increment from each @w{@math{x} value} to the next will be
@var{step_size}, and the first @w{@math{x} value} will be
@var{lower_limit}.  @w{To return} to reading abscissa values from the
input, i.e., for subsequent input files, you would use @samp{-a 0},
which disables automatic generation of the abscissa values 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 thickness, 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.  By
convention, linemode #0 means no line @w{at all} (points are
disconnected).  @w{If the} dataset is being rendered in monochrome, the
interpretation of @var{line_mode} is as follows.

@enumerate
@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.  @w{If the} dataset is being
rendered in color (as may be requested with the @samp{-C} option), the
interpretation of linemodes #1 through #5 is instead

@enumerate
@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 font size of the symbol, as a fraction
of the minimum dimension (width or height) of the plotting box.  @w{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 (by convention,
@w{symbol #0} means no symbol @w{at all}).

@enumerate
@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 can 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 thickness of the lines used to
join successive points in a dataset, as a fraction of the size (i.e.,
minimum dimension) of the graphics display, to @var{line_width}.  @w{A
negative} value means that the default value for the line thickness
provided by the @code{libplot} graphics library should be used.  This is
usually 1/850 times the size of the display, although if @samp{-T X},
@samp{-T pnm}, or @code{-T gif} is specified, it is zero.  By
convention, a zero-thickness line is the thinnest line that can be
drawn.  This is the case in all output formats.  Note, however, that the
drawing editors @code{idraw} and @code{xfig} treat zero-thickness lines
as invisible.

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

@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 fill rule' will
normally be used to determine which points are inside rather than
outside, i.e., to determine which portions of the polygon should be
shaded.  The even-odd fill rule is explained in the @cite{Postscript
Language Reference Manual}.

The @samp{-q} option has no effect in @code{graph -T tek}, and it is
only partly effective in @code{graph -T hpgl} if the environment
variable @code{HPGL_VERSION} is set @w{to "1"}.

@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" unless @samp{-T pnm}, @samp{-T gif},
@samp{-T pcl}, @samp{-T hpgl}, or @code{@w{-T tek}} is specified, in
which case it is "HersheySerif".)  Set the symbol font, from which
plotting symbols numbered 32 and higher are selected, to be
@var{symbol_font_name}.  Font names are case-insensitive.  @w{If the}
specified font is not available, the default font will be used.  Which
fonts are available depends on which @samp{-T} option is used.  For
example, if the @samp{-T pcl} or @samp{-T hpgl} option is used then
normally the Wingdings font, which is an alternative source of symbols,
becomes available.  For a list of all fonts, see @ref{Text Fonts}.  The
@code{plotfont} utility will produce a character map of any available
font.  @xref{plotfont}.

@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}).  Normalized coordinates are used
here: (0,0) means the lower left corner of the physical display and
(1,1) means the upper right corner of the physical display.  The size of
the plot within the virtual display may be adjusted with the @samp{-h}
and @samp{-w} options, and its position within the virtual display with
the @samp{-u} and @samp{-w} options.  After a @samp{--reposition}
command, the arguments of those four options will be interpreted in
terms of the virtual display, not the physical display.

@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 -T tek}
cannot clear regions, and @code{graph -T hpgl} cannot clear them if the
environment variables @code{HPGL_VERSION} and @code{HPGL_OPAQUE_MODE}
are set to non-default values (i.e., values other than @w{"2" and
"yes"}, respectively).
@end table

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

The following option is relevant only to raw @code{graph}, i.e., is
relevant only if no display type or output format is specified with the
@samp{-T} option.  In this case @code{graph} outputs a graphics
metafile, which may be translated to other formats by invoking
@code{plot}.  This option should appear on the command line before any
file names, since it affects the output of the plot (or multiplot) as a
whole.

@table @samp
@item -O
@itemx --portable-output
Output the portable (human-readable) version of GNU metafile format,
rather than a binary version (the default).  This can also be requested
by setting the environment variable @code{META_PORTABLE} to "yes".
@end table

@node Info Options, graph Environment, 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 table of available fonts, and then exit.  The table will depend
on which display type or output format is specified with the @samp{-T}
option.  @code{graph @w{-T X}}, @code{graph -T ai}, @code{graph -T ps},
and @code{graph -T fig} each support the 35 standard Postscript fonts.
@code{graph -T ai}, @code{graph -T pcl}, and @code{graph -T hpgl}
support the 45 standard @w{PCL 5} fonts, and @code{graph -T pcl} and
@code{graph -T hpgl} support a number of Hewlett--Packard vector fonts.
All of the preceding, together with @code{graph -T pnm}, @code{graph -T
gif}, and @code{graph -T tek}, support a set of 22 Hershey vector fonts.
Raw @code{graph} @w{in principle} supports any of these fonts, since its
output must be translated to other formats with @code{plot}.  The
@code{plotfont} utility will produce a character map of any available
font.  @xref{plotfont}.

@item --list-fonts
Like @samp{--help-fonts}, but lists the fonts in a single column to
facilitate piping to other programs.  @w{If no} display type or output
format is specified with the @samp{-T} option, the full set of supported
fonts is listed.

@item --version
Print the version number of @code{graph} and the plotting utilities
package, and exit.
@end table

@node graph Environment, , Info Options, graph Invocation
@section Environment variables

The behavior of @code{graph} is affected by several environment
variables.  We have already mentioned the environment variables
@code{BITMAPSIZE}, @code{PAGESIZE}, @code{BG_COLOR}, and
@code{MAX_LINE_LENGTH}.  They serve as backups for the options
@samp{--bitmap-size}, @samp{--page-size}, @samp{--bg-color}, and
@samp{--max-line-length}.  The remaining environment variables are
specific to individual output formats.

@code{graph @w{-T X}}, which pops up a window on an @w{X Window} System
display and draws graphics @w{in it}, checks the @code{DISPLAY}
environment variable.  The value of this variable determines the display
on which the window will be @w{popped up}.

@code{graph -T pnm}, which produces output in Portable Anymap
(PBM/PGM/PPM) format, is affected by the @code{PNM_PORTABLE} environment
variable.  If its value is "yes", the output file will be in the
portable (human readable) version of PBM, PGM, or PPM format, rather
than the default (binary) version.

@code{graph -T gif}, which produces output in pseudo-GIF format, is
affected by two environment variables.  If the value of the
@code{INTERLACE} variable is "yes", the pseudo-GIF output file will be
in interlaced format.  Also, if the value of the
@code{TRANSPARENT_COLOR} environment variable is the name of a color
that appears in the output file, that color will be treated as
transparent by most applications that read GIF files.  For information
on what color names are recognized, see @ref{Color Names}.

@code{graph -T pcl}, which produces @w{PCL 5} output for
Hewlett--Packard printers and plotters, is affected by several
environment variables.  The position of the graphics display on the page
can be adjusted by setting the @code{PCL_XOFFSET} and @code{PCL_YOFFSET}
environment variables, which may be specified in centimeters,
millimeters, or inches.  @w{For example}, an offset could be specified
as "2cm" or "1.2in".  Also, the display can be rotated @w{90 degrees}
counterclockwise on the page by setting the @code{PCL_ROTATE}
environment variable to "yes".  This is not the same as the rotation
obtained with the @code{--rotation} option, which sets the rotation
angle of the plot within the display.  Besides "no" and "yes",
recognized values for the @code{PCL_ROTATE} variable are "0", "90",
"180", @w{and "270"}.  @w{"no" and} "yes" are equivalent to @w{"0" and
"90"}, respectively.

The variable @code{PCL_ASSIGN_COLORS} is also recognized.  It should be
set to "yes" when producing @w{PCL 5} output for a color printer or
other color device.  This will ensure accurate color reproduction by
giving the output device complete freedom in assigning colors,
internally, to its ``logical pens''.  If it is "no" then the device will
use a fixed set of colored pens, and will emulate other colors by
shading.  The default is "no" because monochrome @w{PCL 5} devices,
which are much more common than colored ones, must use shading to
emulate color.

@code{graph -T hpgl}, which produces Hewlett--Packard Graphics Language
output, is also affected by several environment variables.  The most
important is @code{HPGL_VERSION}, which may be set to "1", "1.5", @w{or
"2"} (the default).  @w{"1" means} that the output should be generic
HP-GL, @w{"1.5" means} that the output should be suitable for the
HP7550A graphics plotter and the HP758x, HP7595A and HP7596A drafting
plotters (HP-GL with some HP-GL/2 extensions), and @w{"2" means} that
the output should be modern HP-GL/2.  @w{If the} version is "1" @w{or
"1.5"} then the only available fonts will be vector fonts, and all lines
will be drawn with a default thickness (the @samp{-W} option will not
work).  Additionally, if the version @w{is "1"} then the filling of
arbitrary curves with solid color will not be supported (the @samp{-q}
option may be used to fill circles and rectangles aligned with the
coordinate axes, though).

The position of the @code{graph -T hpgl} graphics display on the page
can be adjusted by setting the @code{HPGL_XOFFSET} and
@code{HPGL_YOFFSET} environment variables, which may be specified in
centimeters, millimeters, or inches.  For example, an offset could be
specified as "2cm" or "1.2in".  Also, the display can be rotated @w{90
degrees} counterclockwise on the page by setting the @code{HPGL_ROTATE}
environment variable to "yes".  This is not the same as the rotation
obtained with the @code{--rotation} option, which sets the rotation
angle of the plot within the display.  Besides "no" and "yes",
recognized values for the @code{HPGL_ROTATE} variable are "0", "90",
"180", @w{and "270"}.  @w{"no" and} "yes" are equivalent to @w{"0" and
"90"}, respectively.  "180" and "270" are supported only if
@code{HPGL_VERSION} @w{is "2"} (the default).

@emph{Opaque} filling and the drawing of visible white lines are
supported only if @code{HPGL_VERSION} is "2" (the default) and the
environment variable @code{HPGL_OPAQUE_MODE} is "yes" (the default).
@w{If the} value is "no" then opaque filling will not be used, and white
lines (@w{if any}), which are normally drawn with @w{pen #0}, will not
be drawn.  This feature is to accommodate older HP-GL/2 devices.
HP-GL/2 pen plotters, @w{for example}, do not support opacity or the use
of @w{pen #0} to draw visible white lines.  Some older HP-GL/2 devices
reportedly malfunction if asked to draw opaque objects.

@w{By default}, @code{graph -T hpgl} will draw with a fixed set of pens.
Which pens are present may be specified by setting the @code{HPGL_PENS}
environment variable.  If @code{HPGL_VERSION} @w{is "1"}, the default
value of @code{HPGL_PENS} is "1=black"; if @code{HPGL_VERSION} is "1.5"
@w{or "2"}, the default value of @code{HPGL_PENS} is
"1=black:2=red:3=green:4=yellow:5=blue:6=magenta:7=cyan".  The format
should be self-explanatory.  By setting @code{HPGL_PENS}, you may
specify a color for any pen in the range #1@dots{}#31.  For information
on what color names are recognized, see @ref{Color Names}.  @w{Pen #1}
must always be present, though it need not be black. Any other pen in
the range #1@dots{}#31 may be omitted.

If @code{HPGL_VERSION} is "2" then @code{graph -T hpgl} will also be
affected by the environment variable @code{HPGL_ASSIGN_COLORS}.  @w{If
the} value of this variable is "yes", then @code{graph -T hpgl} will not
be restricted to the palette specified in @code{HPGL_PENS}: @w{it will}
assign colors to ``logical pens'' in the range #1@dots{}#31, @w{as
needed}.  The default value is "no" because other than color LaserJet
printers and DesignJet plotters, not many HP-GL/2 devices allow the
assignment of colors to logical pens.

@code{graph -T tek}, which produces output for a Tektronix terminal or
emulator, checks the @code{TERM} environment variable.  @w{If the} value
of @code{TERM} is "xterm", "xterms", or "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 drawing graphics,
@code{graph -T tek} will emit an escape sequence that causes the
terminal emulator's auxiliary Tektronix window, which is normally
hidden, to @w{pop up}.  After the graphics are drawn, an escape sequence
that returns control to the original VT100 window will be emitted.  The
Tektronix window will remain on the screen.

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

@node plot, pic2plot, graph, Top
@chapter The @code{plot} Program

@menu
* plot Examples::       How to use a plot filter
* plot Invocation::     Command-line options
* plot Environment::    Environment variables
@end menu

@node plot Examples, plot Invocation, plot, plot
@section How to use @code{plot}

The GNU plot filter @code{plot} displays GNU graphics metafiles or
translates them to other formats.  @w{It will} take input from files
specified on the command line or from standard input.  The @samp{-T}
option is used to specify the desired output format.  Supported output
formats include "X", "pnm", "gif", "ai", "ps", "fig", "pcl", "hpgl",
"tek", and "meta" (the default).

The metafile format is a device-independent format for storage of vector
graphics.  By default, it is a binary rather than a human-readable
format (@pxref{Metafiles}).  Each of the @code{graph}, @code{pic2plot},
@code{tek2plot}, and @code{plotfont} utilities will write a graphics
metafile to standard output if no @samp{-T} option is specified on its
command line.  The @code{libplot} graphics library may also be used to
produce metafiles.  Metafiles may contain arbitrarily many pages of
graphics, but each metafile produced by @code{graph} contains only a
single page.

@code{plot}, like the metafile format itself, is useful if you wish to
preserve a vector graphics file, and display or edit it with more than
one drawing editor.  The following example shows how you may do this.

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

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

@noindent
The file @file{test.meta} will be a single-page graphics metafile.
Similarly, to create in metafile format a plot consisting of a simple
figure, you may do:

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

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

@example
plot -T X test.meta
@end example

@noindent 
or

@example
plot -T X < test.meta
@end example

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

@example
plot -T ps < test.meta | lpr
@end example

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

@example
@group
plot -T ps < test.meta > test.ps
idraw test.ps
@end group
@end example

@noindent
To produce a ``portable anymap'' (a file in PBM, PGM, or PPM format,
whichever is most appropriate) you would do
@example
plot -T pnm < test.meta > test.pnm
@end example

@noindent
and to produce a pseudo-GIF file, you would do
@example
plot -T gif < test.meta > test.gif
@end example

@noindent
Similarly, to produce a version of the plot that can be edited with
Adobe Illustrator, you would do

@example
plot -T ai < test.meta > test.ai
@end example

@noindent
and to produce a version that can be edited with the free @code{xfig}
drawing editor, you would do

@example
@group
plot -T fig < test.meta > test.fig
xfig test.fig
@end group
@end example

@noindent
Other formats may be obtained by using @code{plot -T pcl}, @code{plot -T
hpgl}, and @code{plot -T tek}.

@code{plot} may behave differently depending on the environment in which
it is invoked.  In particular, @code{plot -T ai}, @code{plot -T ps},
@code{plot -T fig}, @code{plot -T pcl}, and @code{plot -T hpgl} are
affected by the environment variable @code{PAGESIZE}.  @code{plot @w{-T
X}}, @code{plot -T pnm}, and @code{plot -T gif} are affected by the
environment variable @code{BITMAPSIZE}@.  The @code{DISPLAY} environment
variable affects the operation of @code{plot @w{-T X}}, and the
@code{TERM} environment variable affects the operation of @code{plot -T
tek}.  There are also several environment variables that affect the
operation of @code{plot -T pcl} and @code{plot -T hpgl}.  For a complete
discussion of the effects of the environment on @code{plot}, see
@ref{plot Environment}.

@node plot Invocation, plot Environment, plot Examples, plot
@section @code{plot} command-line options

The plot filter @code{plot} translates GNU graphics metafiles to other
formats.  The @samp{-T} option is used to specify the output format or
display type.  Files in metafile format are produced by GNU
@code{graph}, @code{pic2plot}, @code{tek2plot}, @code{plotfont}, and
other applications that use the GNU @code{libplot} graphics library.
For technical details on the metafile format, see @ref{Metafiles}.

Input file names may be specified anywhere on the command line.  That
is, the relative order of file names and command-line options does not
matter.  If no file names are specified, or the file @w{name @samp{-}}
is specified, the standard input is read.  The output file is written to
standard output, unless the @samp{-T X} option is specified.  @w{In
that} case the output is displayed in a window or windows on an @w{X
Window} System display, and there is no output file.

The full set of command-line options is listed below.  There are four
sorts of option:

@enumerate
@item
Options setting the values of drawing parameters.
@item
Options relevant only to raw @code{plot}, i.e., relevant only if no
display type or output format is specified with the @samp{-T} option.
@item
Options specifying the type of metafile format the input is in (for
backward compatibility only).
@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.

The following options set the values of drawing parameters.

@table @samp
@item -T @var{type}
@itemx --display-type @var{type}
(String, default "meta".)  Select a display type or output format of
type @var{type}, which may be one of the strings "X", "pnm", "gif",
"ai", "ps", "fig", "pcl", "hpgl", "tek", and "meta".  These refer
respectively to the @w{X Window System}, portable anymap (PBM/PGM/PPM)
format, pseudo-GIF format, the format used by Adobe Illustrator,
@code{idraw}-editable Postscript, the format used by the @code{xfig}
drawing editor, the Hewlett--Packard @w{PCL 5} printer language, the
Hewlett--Packard Graphics Language (@w{by default}, HP-GL/2), Tektronix
format, and device-independent GNU graphics metafile format.

@item -p @var{n}
@itemx --page-number @var{n}
(Positive integer.) Display only page number @var{n}, within the
metafile or sequence of metafiles that is being translated.  

Metafiles may consist of one or more pages, numbered beginning @w{with
1}.  Also, each page may contain multiple `frames'.  @code{plot @w{-T
X}} or @code{plot -T tek}, which plot in real time, will separate
successive frames by screen erasures.  @code{plot -T pnm}, @code{plot -T
gif}, @code{plot -T ai}, @code{plot -T ps}, @code{plot -T fig},
@code{plot -T pcl}, and @code{plot -T hpgl}, which do not plot in real
time, will display only the last frame of any multi-frame page.

The default behavior, if @samp{-p} is not used, is to display all pages.
For example, @code{plot @w{-T X}} displays each page in its own @w{X
window}.  @w{If the} @samp{-T pnm} option, the @samp{-T gif} option, the
@samp{-T ai} option, or the @samp{-T fig} option is used, the default
behavior is to display only the first page, since files in PNM,
pseudo-GIF, AI, or Fig format may contain only a single page of
graphics.

Most metafiles produced by the GNU plotting utilities (e.g., by raw
@code{graph}) contain only a single page, consisting of two frames: an
empty one to clear the display, and a second one containing graphics.

@item -s
@itemx --merge-pages
Merge all displayed pages into a single page, and also merge all
`frames' within each displayed page.

This option is useful when merging together single-page plots from
different sources.  For example, it can be used to merge together plots
obtained from separate invocations of @code{graph}.  This is an
alternative form of multiplotting (@pxref{Multiplotting}).

@item --bitmap-size @var{bitmap_size}
(String, default "570x570".)  Set the size of the graphics display in
which the plot will be drawn, in terms of pixels, to be
@var{bitmap_size}.  This is relevant only to @code{plot @w{-T X}},
@code{plot -T pnm}, and @code{plot -T gif}, for which the graphics
display size can be expressed in terms of pixels.  The environment
variable @code{BITMAPSIZE} can equally well be used to specify the size.

For backward compatibility, the @w{X resource} @code{Xplot.geometry},
which can be set by the user, may be used to set the window size,
instead of @samp{--bitmap-size} or @code{BITMAPSIZE}@.

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

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

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

For @code{plot -T ai} and @code{plot -T ps}, the graphics display within
which the plot is drawn will be a square region centered on the
specified page, occupying its full width (with allowance being made for
margins).  For @code{plot -T fig}, it will be a square region located of
the same size, located in the upper left corner of an @code{xfig}
display.  For @code{plot -T pcl} and @code{plot -T hpgl}, the graphics
display will be a square region of the same size, but may be positioned
differently.  Fine control over its positioning on the page may be
accomplished by setting certain environment variables (@pxref{plot
Environment}).
@end table

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

@table @samp
@item --bg-color @var{name}
(String, default "white".)  Set the color used for the plot background
to be @var{name}.  This is relevant only to @code{plot @w{-T X}},
@code{plot -T pnm}, and @code{plot -T gif}.  @w{An unrecognized} name
sets the color to the default.  For information on what names are
recognized, see @ref{Color Names}.  The environment variable
@code{BG_COLOR} can equally well be used to specify the background
color.

If the @samp{-T gif} option is used, a transparent pseudo-GIF may be
produced by setting the @code{TRANSPARENT_COLOR} environment variable to
the name of the background color.  @xref{plot Environment}.

@item -f @var{font_size}
@itemx --font-size @var{font_size}
(Float, initial value device-dependent.)  Set the initial size of the
font used for rendering text, as a fraction of the width of the graphics
display, to @var{font_size}.

@item -F @var{font_name}
@itemx --font-name @var{font_name}
(String, default "Helvetica" except for @code{plot -T pnm}, @code{plot
-T gif}, @code{plot -T pcl}, @code{plot -T hpgl}, @code{plot -T tek},
and raw @code{plot}, for all of 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.  @w{If the} specified
font is not available, the default font will be used.  Which fonts are
available depends on which @samp{-T} option is used.  For a list of all
fonts, see @ref{Text Fonts}.  The @code{plotfont} utility will produce a
character map of any available font.  @xref{plotfont}.

@item -W @var{line_width}
@itemx --line-width @var{line_width}
(Float, default @minus{}1.0.)  Set the thickness of lines, as a fraction
of the size (i.e., minimum dimension) of the graphics 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 is
usually 1/850 times the size of the display, although if @samp{-T X},
@samp{-T pnm}, or @code{-T gif} is specified, it is zero.  By
convention, a zero-thickness line is the thinnest line that can be
drawn.  This is the case in all output formats.  Note, however, that the
drawing editors @code{idraw} and @code{xfig} treat zero-thickness lines
as invisible.

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

@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, see @ref{Color Names}.
@end table

The following option is relevant only to raw @code{plot}, i.e., relevant
only if no output type is specified with the @samp{-T} option.  In this
case @code{plot} outputs a graphics metafile, which may be translated to
other formats by a second invocation of @code{plot}.

@table @samp
@item -O
@itemx --portable-output
Output the portable (human-readable) version of GNU metafile format,
rather than a binary version (the default).  This can also be requested
by setting the environment variable @code{META_PORTABLE} to "yes".
@end table

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

For compatibility with older plotting software, the reading of input
files in the pre-GNU `plot(5)' format is also supported.  This is
normally a binary format, with each integer in the metafile represented
as a pair of bytes.  The order of the two bytes is machine dependent.
You may specify that input file(s) are in plot(5) format rather than
ordinary GNU metafile format by using either the @samp{-h} option
(``high byte first'') or the @samp{-l} option (``low byte first''),
whichever is appropriate.  Some non-GNU systems support an ASCII
(human-readable) variant of plot(5) format.  You may specify that the
input is in this format by using the @samp{-A} option.  Irrespective of
the variant, a file in plot(5) format includes only one page of
graphics.

@table @samp
@item -h
@itemx --high-byte-first-input
Input file(s) are assumed to be in traditional `plot(5)' metafile
format, with the high-order byte of each integer occurring first.

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

@item -A
@itemx --ascii-input
Input file(s) are assumed to be in the ASCII variant of traditional
`plot(5)' metafile format.
@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 table of available fonts, and then exit.  The table will depend
on which display type or output format is specified with the @samp{-T}
option.  @code{plot @w{-T X}}, @code{plot -T ai}, @code{plot -T ps},
and @code{plot -T fig} each support the 35 standard Postscript fonts.
@code{plot -T ai}, @code{plot -T pcl}, and @code{plot -T hpgl}
support the 45 standard @w{PCL 5} fonts, and @code{plot -T pcl} and
@code{plot -T hpgl} support a number of Hewlett--Packard vector fonts.
All of the preceding, together with @code{plot -T pnm}, @code{plot -T
gif}, and @code{plot -T tek}, support a set of 22 Hershey vector fonts.
Raw @code{plot} @w{in principle} supports any of these fonts, since its
output must be translated to other formats with @code{plot}.  The
@code{plotfont} utility will produce a character map of any available
font.  @xref{plotfont}.

@item --list-fonts
Like @samp{--help-fonts}, but lists the fonts in a single column to
facilitate piping to other programs.  @w{If no} display type or output
format is specified with the @samp{-T} option, the full set of supported
fonts is listed.

@item --version
Print the version number of @code{plot} and the plotting utilities
package, and exit.
@end table

@node plot Environment, , plot Invocation, plot
@section Environment variables

The behavior of @code{plot} is affected by several environment
variables.  We have already mentioned the environment variables
@code{BITMAPSIZE}, @code{PAGESIZE}, @code{BG_COLOR}, and
@code{MAX_LINE_LENGTH}.  They serve as backups for the options
@samp{--bitmap-size}, @samp{--page-size}, @samp{--bg-color}, and
@samp{--max-line-length}.  The remaining environment variables are
specific to individual output formats.

@code{plot @w{-T X}}, which pops up a window on an @w{X Window} System
display and draws graphics @w{in it}, checks the @code{DISPLAY}
environment variable.  The value of this variable determines the display
on which the window will be @w{popped up}.

@code{plot -T pnm}, which produces output in Portable Anymap
(PBM/PGM/PPM) format, is affected by the @code{PNM_PORTABLE} environment
variable.  If its value is "yes", the output file will be in the
portable (human readable) version of PBM, PGM, or PPM format, rather
than the default (binary) version.

@code{plot -T gif}, which produces output in pseudo-GIF format, is
affected by two environment variables.  If the value of the
@code{INTERLACE} variable is "yes", the pseudo-GIF output file will be
in interlaced format.  Also, if the value of the
@code{TRANSPARENT_COLOR} environment variable is the name of a color
that appears in the output file, that color will be treated as
transparent by most applications that read GIF files.  For information
on what color names are recognized, see @ref{Color Names}.

@code{plot -T pcl}, which produces @w{PCL 5} output for Hewlett--Packard
printers and plotters, is affected by several environment variables.
The position of the graphics display on the page can be adjusted by
setting the @code{PCL_XOFFSET} and @code{PCL_YOFFSET} environment
variables, which may be specified in centimeters, millimeters, or
inches.  For example, an offset could be specified as "2cm" or "1.2in".
Also, the display can be rotated @w{90 degrees} counterclockwise on the
page by setting the @code{PCL_ROTATE} environment variable to "yes".
Besides "no" and "yes", recognized values for this variable are "0",
"90", "180", @w{and "270"}.  @w{"no" and} "yes" are equivalent to @w{"0"
and "90"}, respectively.

The variable @code{PCL_ASSIGN_COLORS} is also recognized.  It should be
set to "yes" when producing @w{PCL 5} output for a color printer or
other color device.  This will ensure accurate color reproduction by
giving the output device complete freedom in assigning colors,
internally, to its ``logical pens''.  If it is "no" then the device will
use a fixed set of colored pens, and will emulate other colors by
shading.  The default is "no" because monochrome @w{PCL 5} devices,
which are much more common than colored ones, must use shading to
emulate color.

@code{plot -T hpgl}, which produces Hewlett--Packard Graphics Language
output, is also affected by several environment variables.  The most
important is @code{HPGL_VERSION}, which may be set to "1", "1.5", @w{or
"2"} (the default).  @w{"1" means} that the output should be generic
HP-GL, @w{"1.5" means} that the output should be suitable for the
HP7550A graphics plotter and the HP758x, HP7595A and HP7596A drafting
plotters (HP-GL with some HP-GL/2 extensions), and @w{"2" means} that
the output should be modern HP-GL/2.  @w{If the} version is "1" @w{or
"1.5"} then the only available fonts will be vector fonts, and all lines
will be drawn with a default thickness (the @samp{-W} option will not
work).  Additionally, if the version @w{is "1"} then the filling of
arbitrary curves with solid color will not be supported (circles and
rectangles aligned with the coordinate axes may be filled, though).

The position of the @code{plot -T hpgl} graphics display on the page can
be adjusted by setting the @code{HPGL_XOFFSET} and @code{HPGL_YOFFSET}
environment variables, which may be specified in centimeters,
millimeters, or inches.  For example, an offset could be specified as
"2cm" or "1.2in".  Also, the display can be rotated @w{90 degrees}
counterclockwise on the page by setting the @code{HPGL_ROTATE}
environment variable to "yes".  Besides "no" and "yes", recognized
values for this variable are "0", "90", "180", @w{and "270"}.  @w{"no"
and} "yes" are equivalent to @w{"0" and "90"}, respectively.  "180" and
"270" are supported only if @code{HPGL_VERSION} @w{is "2"} (the
default).

@emph{Opaque} filling and the drawing of visible white lines are
supported only if @code{HPGL_VERSION} is "2" (the default) and the
environment variable @code{HPGL_OPAQUE_MODE} is "yes" (the default).
@w{If the} value is "no" then opaque filling will not be used, and white
lines (@w{if any}), which are normally drawn with @w{pen #0}, will not
be drawn.  This feature is to accommodate older HP-GL/2 devices.
HP-GL/2 pen plotters, @w{for example}, do not support opacity or the use
of @w{pen #0} to draw visible white lines.  Some older HP-GL/2 devices
reportedly malfunction if asked to draw opaque objects.

@w{By default}, @code{plot -T hpgl} will draw with a fixed set of pens.
Which pens are present may be specified by setting the @code{HPGL_PENS}
environment variable.  If @code{HPGL_VERSION} @w{is "1"}, the default
value of @code{HPGL_PENS} is "1=black"; if @code{HPGL_VERSION} is "1.5"
@w{or "2"}, the default value of @code{HPGL_PENS} is
"1=black:2=red:3=green:4=yellow:5=blue:6=magenta:7=cyan".  The format
should be self-explanatory.  By setting @code{HPGL_PENS}, you may
specify a color for any pen in the range #1@dots{}#31.  For information
on what color names are recognized, see @ref{Color Names}.  @w{Pen #1}
must always be present, though it need not be black. Any other pen in
the range #1@dots{}#31 may be omitted.

If @code{HPGL_VERSION} is "2" then @code{plot -T hpgl} will also be
affected by the environment variable @code{HPGL_ASSIGN_COLORS}.  @w{If
the} value of this variable is "yes", then @code{plot -T hpgl} will not
be restricted to the palette specified in @code{HPGL_PENS}: @w{it will}
assign colors to ``logical pens'' in the range #1@dots{}#31, @w{as
needed}.  The default value is "no" because other than color LaserJet
printers and DesignJet plotters, not many HP-GL/2 devices allow the
assignment of colors to logical pens.

@code{plot -T tek}, which produces output for a Tektronix terminal or
emulator, checks the @code{TERM} environment variable.  @w{If the} value
of @code{TERM} is "xterm", "xterms", or "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 drawing graphics,
@code{plot -T tek} will emit an escape sequence that causes the terminal
emulator's auxiliary Tektronix window, which is normally hidden, to
@w{pop up}.  After the graphics are drawn, an escape sequence that
returns control to the original VT100 window will be emitted.  The
Tektronix window will remain on the screen.

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

@node pic2plot, tek2plot, plot, Top
@chapter The @code{pic2plot} Program

@menu
* pic2plot Introduction::     What pic2plot is used for
* pic2plot Invocation::       Command-line options
* pic2plot Environment::      Environment variables
@end menu

@node pic2plot Introduction, pic2plot Invocation, pic2plot, pic2plot
@section What @code{pic2plot} is used for

The @code{pic2plot} program takes one or more files in the pic language,
and either displays the figures that they contain on an @w{X Window}
System display, or produces an output file containing the figures.  Many
graphics file formats are supported.

The pic language is a `little language' that was developed at Bell
Laboratories for creating box-and-arrow diagrams of the kind frequently
found in technical papers and textbooks.  @w{A directory} containing
documentation on the pic language is distributed along with the plotting
utilities.  @w{On most} systems it is installed as
@file{/usr/share/pic2plot} or @file{/usr/local/share/pic2plot}.  The
directory includes Brian Kernighan's original technical report on the
language, Eric Raymond's tutorial on the GNU implementation, and some
sample pic macros contributed by @w{W. Richard} Stevens.

The pic language was originally designed to work with the @code{troff}
document formatter.  In that context it is read by a translator called
@code{pic}, or its GNU counterpart @code{gpic}.  Since extensive
documentation on @code{pic} and @code{gpic} is available, this section
simply gives an example of an input file, and mentions some extra
features supported by @code{pic2plot}.

A pic file contains one or more figures, each of the box-and-arrow type.
Each figure is begun by a line reading @t{.PS}, and ended by a line
reading @t{.PE}.  Lines that are not contained in a
@t{.PS}@dots{}@t{.PE} pair are ignored.  @w{Each figure} is built from
geometrical objects, such as rectangular boxes, circles, ellipses,
quarter circles (``arcs''), polygonal lines, and splines.  Arcs,
polygonal lines, and spline may be equipped with arrowheads.  Any object
may be labeled with text.

Objects are usually positioned not by specifying their positions in
absolute coordinates, but rather by specifying their positions relative
to other, previously drawn objects.  The following figure is an example.

@example
.PS
box "START"; arrow; circle dashed filled; arrow
circle diam 2 thickness 3 "This is a" "big, thick" "circle" dashed; up
arrow from top of last circle; ellipse "loopback" dashed
arrow dotted from left of last ellipse to top of last box
arc cw radius 1/2 from top of last ellipse; arrow
box "END"
.PE
@end example

@noindent
If you put this example in a file and run @samp{pic2plot -T X} on the
file, a window containing the figure will be @w{popped up} on your @w{X
display}.  Similarly, if you run @samp{pic2plot -T ps} on the file, a
Postscript file containing the figure will be written to standard
output.  The Postscript file may be edited with the @code{idraw} drawing
editor.  Other graphics formats such as PNM format, pseudo-GIF format,
or Fig format (which is editable with the @code{xfig} drawing editor)
may be obtained similarly.  You would use the options @samp{-T pnm},
@samp{-T gif}, and @samp{-T fig}, respectively.

The above example illustrates some of the features of the pic language.
By default, successive objects are drawn so as to touch each other.  The
drawing proceeds in a certain direction, which by default is
left-to-right.  The @samp{up} command changes this direction to
bottom-to-top, so that the next object (the arrow extending from the top
of the big circle) will point upward rather than to the right.

Objects have sizes and other attributes, which may be set globally, or
specified on a per-object basis.  For example, the diameter of a circle
may be specified, or the radius of an arc.  An arc may be oriented
clockwise rather than counterclockwise by specifying the @samp{cw}
attribute.  The line style of most objects may be altered by specifying
the @samp{dashed} or @samp{dotted} attribute.  Also, any object may be
labeled, by specifying one or more text strings as attributes.  @w{A
text} string may contain escape sequences that shift the font, append
subscripts or superscripts, or include non-ASCII characters and
mathematical symbols.  @xref{Text String Format}.

Most sizes and positions are expressed in terms of `virtual inches'.
The use of virtual inches is peculiar to @code{pic2plot}.  The graphics
display used by @code{pic2plot}, i.e., its drawing region, is defined to
be a square, @w{8 virtual} inches wide and @w{8 virtual} inches high.
If the page size for the output file is the "letter" size, which is the
default for Postscript output, virtual inches will the same as real
inches.  But a different page size may be specified; for example, by
using the @samp{--page-size a4} option.  @w{If so}, a virtual inch will
simply equal one-eighth of the width of the graphics display.

By default, each figure is centered in the graphics display.  You may
turn off centering, so that you can use absolute coordinates, by using
the @samp{-n} option.  For example, a figure consisting only of the
object @samp{arrow from (8,8) to (4,4)} will be positioned in the
absence of centering so that the tip of the arrow is at the center of
the display.  Its tail will be at the upper right corner.

The thickness of lines is not specified in terms of virtual inches.  For
compatibility with @code{gpic}, it is measured in terms of virtual
points.  The example above, which specifies the @samp{thickness}
attribute of one of the objects, illustrates this.  There are @w{72
virtual} points per virtual inch.

If there is more than one figure to be displayed, they will appear in
different @w{X windows}, or on successive pages of the output file.
Some output formats (such as PNM, pseudo-GIF, Illustrator, and Fig)
support only a single page of graphics.  @w{If any} of those output
formats is chosen, only the first figure will appear in the output file.
Currently, @code{pic2plot} cannot produce animated pseudo-GIFs.

The preceding survey does not do justice to the pic language, which is
actually a full-featured programming language, with support for
variables, looping constructs, etc.  Its advanced features make the
drawing of large, repetitive diagrams quite easy.

@node pic2plot Invocation, pic2plot Environment, pic2plot Introduction, pic2plot
@section @code{pic2plot} command-line options

The @code{pic2plot} program translates files in the pic language, which
is used for creating box-and-arrow diagrams of the kind frequently found
in technical papers and textbooks, to other graphics formats.  The
output format or display type is specified with the @samp{-T} option.
The possible output formats are the same ten formats that are supported
by the GNU @code{graph} and @code{plot} programs.

Input file names may be specified anywhere on the command line.  That
is, the relative order of file names and command-line options does not
matter.  If no file names are specified, or the file @w{name @samp{-}}
is specified, the standard input is read.  The output file is written to
standard output, unless the @samp{-T X} option is specified.  @w{In
that} case the output is displayed in one or more windows on an @w{X
Window} System display, and there is no output file.

The full set of command-line options is listed below.  There are three
sorts of option:

@enumerate
@item
General options.
@item
Options relevant only to raw @code{pic2plot}, i.e., relevant only if no
display type or output format is specified with the @samp{-T} option.
@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.

The following are general options.

@table @samp
@item -T @var{type}
@itemx --display-type @var{type}
(String, default "meta".)  Select a display type or output format of
type @var{type}, which may be one of the strings "X", "pnm", "gif",
"ai", "ps", "fig", "pcl", "hpgl", "tek", and "meta".  These refer
respectively to the @w{X Window System}, portable anymap (PBM/PGM/PPM)
format, pseudo-GIF format, the format used by Adobe Illustrator,
@code{idraw}-editable Postscript, the format used by the @code{xfig}
drawing editor, the Hewlett--Packard @w{PCL 5} printer language, the
Hewlett--Packard Graphics Language (@w{by default}, HP-GL/2), Tektronix
format, and device-independent GNU graphics metafile format.

@item -d
@itemx --precision-dashing
Draw dashed and dotted lines carefully, i.e., draw each dash and dot as
a separate object, so that they may be positioned individually.  The
default is to use the support for dashed and dotted lines provided by
the underlying graphics library, @code{libplot}.

This option may produce slightly better-looking dashed and dotted lines.
However, it will come at a price: if an editable output file is produced
(@w{i.e., an} output file in Illustrator, Postscript or Fig format),
@w{it will} be difficulty to modify its dashed and dotted lines with a
drawing editor.

@item -f @var{font_size}
@itemx --font-size @var{font_size}
(Float, default 0.0175.)  Set the size of the font used for rendering
text, as a fraction of the width of the graphics display, to
@var{font_size}.

@item -F @var{font_name}
@itemx --font-name @var{font_name}
(String, default "Helvetica" except for @code{pic2plot -T pnm},
@code{pic2plot -T gif}, @code{pic2plot -T pcl}, @code{pic2plot -T hpgl},
@code{pic2plot -T tek}, and raw @code{pic2plot}, for all of which
"HersheySerif" is the default.)  Set the font used for text to
@var{font_name}.  Font names are case-insensitive.  @w{If the} specified
font is not available, the default font will be used.  Which fonts are
available depends on which @samp{-T} option is used.  For a list of all
fonts, see @ref{Text Fonts}.  The @code{plotfont} utility will produce a
character map of any available font.  @xref{plotfont}.

@item -n
@itemx --no-centering
Turn off the automatic centering of each figure.  If this option is
specified, the position of the objects in each figure may be specified
in terms of absolute coordinates.  E.g., "line from (0,0) to (4,4)" will
draw a line segment from the lower left corner to the center of the
graphics display, since the display width and display height are defined
to equal @w{8 virtual} inches.

@item -W @var{line_width}
@itemx --line-width @var{line_width}
(Float, default @minus{}1.0.)  Set the default thickness of lines, as a
fraction of the size (i.e., minimum dimension) of the graphics 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 is
usually 1/850 times the size of the display, although if @samp{-T X},
@samp{-T pnm}, or @code{-T gif} is specified, it is zero.  By
convention, a zero-thickness line is the thinnest line that can be
drawn.  This is the case in all output formats.  Note, however, that the
drawing editors @code{idraw} and @code{xfig} treat zero-thickness lines
as invisible.

@code{pic2plot -T hpgl} does not support drawing lines with other than a
default thickness if the environment variable @code{HPGL_VERSION} is set
to a value less @w{than "2"} (the default).

@item --bg-color @var{name}
(String, default "white".)  Set the color used for the background to be
@var{name}.  This is relevant only to @code{pic2plot @w{-T X}},
@code{pic2plot -T pnm}, and @code{pic2plot -T gif}.  @w{An unrecognized}
name sets the color to the default.  For information on what names are
recognized, see @ref{Color Names}.  The environment variable
@code{BG_COLOR} can equally well be used to specify the background
color.

If the @samp{-T gif} option is used, a transparent pseudo-GIF may be
produced by setting the @code{TRANSPARENT_COLOR} environment variable to
the name of the background color.  @xref{pic2plot Environment}.

@item --bitmap-size @var{bitmap_size}
(String, default "570x570".)  Set the size of the graphics display in
which the plot will be drawn, in terms of pixels, to be
@var{bitmap_size}.  This is relevant only to @code{pic2plot @w{-T X}},
@code{pic2plot -T pnm}, and @code{pic2plot -T gif}, for which the
graphics display size can be expressed in terms of pixels.  The
environment variable @code{BITMAPSIZE} can equally well be used to
specify the size.

The graphics display used by @code{pic2plot -T X} is an @w{X window};
i.e., one window for each figure.  If you choose a rectangular
(non-square) window size, the fonts in each figure will be scaled
anisotropically, i.e., by different factors in the horizontal and
vertical direction.  This requires an X11R6 display.  Any font that
cannot be scaled in this way will be replaced by a default scalable
font, such as the Hershey vector font "HersheySerif".

For backward compatibility, the @w{X resource} @code{Xplot.geometry},
which can be set by the user, may be used to set the window size,
instead of @samp{--bitmap-size} or @code{BITMAPSIZE}@.

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

The reason for splitting long polygonal lines is that some display
devices (e.g., old Postscript printers and HP-GL pen plotters) have
limited buffer sizes.  The environment variable @code{MAX_LINE_LENGTH}
can also be used to specify the maximum line length.  This option has no
effect on raw @code{pic2plot}, since it draws polylines in real time and
has no buffer limitations.

@item --page-size @var{pagesize}
(String, default "letter".)  Set the size of the page on which each
figure will be positioned.  This is relevant only to @code{pic2plot -T
ai}, @code{pic2plot -T ps}, @code{pic2plot -T fig}, @code{pic2plot -T
pcl}, and @code{pic2plot -T hpgl}.  "letter" means an 8.5@dmn{in} by
11@dmn{in} page.  Any ISO page size in the range "a0"@dots{}"a4" or ANSI
page size in the range "a"@dots{}"e" may be specified ("letter" is an
alias @w{for "a"} and "tabloid" is an alias @w{for "b"}).  "legal",
"ledger", @w{and "b5"} are recognized page sizes also.  The environment
variable @code{PAGESIZE} can equally well be used to specify the page
size.

For @code{pic2plot -T ai} and @code{pic2plot -T ps}, the graphics
display within which each figure is drawn will be a square region
centered on the specified page, occupying its full width (with allowance
being made for margins).  For @code{pic2plot -T fig}, it will be a
square region of the same size, located in the upper left corner of an
@code{xfig} display.  For @code{pic2plot -T pcl} and @code{pic2plot -T
hpgl}, the graphics display will be a square region of the same size,
but may be positioned differently.  Fine control its positioning on the
page can be accomplished by setting certain environment variables
(@pxref{pic2plot Environment}).

@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, see @ref{Color Names}.

@item --rotation @var{angle}
(Integer, default 0.)  Set the rotation angle of each figure within the
graphics display to be @var{angle} degrees.  Recognized values are 0,
90, 180, and 270.  The rotation is counterclockwise.

This option is used for switching between portrait mode and landscape
mode.  Postmodernists may also find it useful.
@end table

The following option is relevant only to raw @code{pic2plot}, i.e.,
relevant only if no display type or output format is specified with the
@samp{-T} option.  In this case @code{pic2plot} outputs a graphics
metafile, which may be translated to other formats by invoking
@code{plot}.

@table @samp
@item -O
@itemx --portable-output
Output the portable (human-readable) version of GNU metafile format,
rather than a binary version (the default).  This can also be requested
by setting the environment variable @code{META_PORTABLE} to "yes".
@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 table of available fonts, and then exit.  The table will depend
on which display type or output format is specified with the @samp{-T}
option.  @code{pic2plot @w{-T X}}, @code{pic2plot -T ai}, @code{pic2plot
-T ps}, and @code{pic2plot -T fig} each support the 35 standard
Postscript fonts.  @code{pic2plot -T ai}, @code{pic2plot -T pcl}, and
@code{pic2plot -T hpgl} support the 45 standard @w{PCL 5} fonts, and
@code{pic2plot -T pcl} and @code{pic2plot -T hpgl} support a number of
Hewlett--Packard vector fonts.  All of the preceding, together with
@code{pic2plot -T pnm}, @code{pic2plot -T gif}, and @code{pic2plot
-T tek}, support a set of 22 Hershey vector fonts.  Raw @code{pic2plot}
@w{in principle} supports any of these fonts, since its output must be
translated to other formats with @code{plot}.  The @code{plotfont}
utility will produce a character map of any available font.
@xref{plotfont}.

@item --list-fonts
Like @samp{--help-fonts}, but lists the fonts in a single column to
facilitate piping to other programs.  @w{If no} display type or output
format is specified with the @samp{-T} option, the full set of supported
fonts is listed.

@item --version
Print the version number of @code{pic2plot} and the plotting utilities
package, and exit.
@end table

@node pic2plot Environment, , pic2plot Invocation, pic2plot
@section Environment variables

The behavior of @code{pic2plot} is affected by several environment
variables.  We have already mentioned the environment variables
@code{BITMAPSIZE}, @code{PAGESIZE}, @code{BG_COLOR}, and
@code{MAX_LINE_LENGTH}.  They serve as backups for the options
@samp{--bitmap-size}, @samp{--page-size}, @samp{--bg-color}, and
@samp{--max-line-length}.  The remaining environment variables are
specific to individual output formats.

@code{pic2plot @w{-T X}}, which pops up a window on an @w{X Window}
System display for each figure, checks the @code{DISPLAY} environment
variable.  The value of this variable determines the display on which
the windows will be @w{popped up}.

@code{pic2plot -T pnm}, which produces output in Portable Anymap
(PBM/PGM/PPM) format, is affected by the @code{PNM_PORTABLE} environment
variable.  If its value is "yes", the output file will be in the
portable (human readable) version of PBM, PGM, or PPM format, rather
than the default (binary) version.

@code{pic2plot -T gif}, which produces output in pseudo-GIF format, is
affected by two environment variables.  If the value of the
@code{INTERLACE} variable is "yes", the pseudo-GIF output file will be
in interlaced format.  Also, if the value of the
@code{TRANSPARENT_COLOR} environment variable is the name of a color
that appears in the output file, that color will be treated as
transparent by most applications that read GIF files.  For information
on what color names are recognized, see @ref{Color Names}.

@code{pic2plot -T pcl}, which produces @w{PCL 5} output for
Hewlett--Packard printers and plotters, is affected by several
environment variables.  The position of the graphics display on the page
can be adjusted by setting the @code{PCL_XOFFSET} and @code{PCL_YOFFSET}
environment variables, which may be specified in centimeters,
millimeters, or inches.  For example, an offset could be specified as
"2cm" or "1.2in".  Also, the display can be rotated @w{90 degrees}
counterclockwise on the page by setting the @code{PCL_ROTATE}
environment variable to "yes".  Besides "no" and "yes", recognized
values for this variable are "0", "90", "180", @w{and "270"}.  @w{"no"
and} "yes" are equivalent to @w{"0" and "90"}, respectively.

The variable @code{PCL_ASSIGN_COLORS} is also recognized.  It should be
set to "yes" when producing @w{PCL 5} output for a color printer or
other color device.  This will ensure accurate color reproduction by
giving the output device complete freedom in assigning colors,
internally, to its ``logical pens''.  If it is "no" then the device will
use a fixed set of colored pens, and will emulate other colors by
shading.  The default is "no" because monochrome @w{PCL 5} devices,
which are much more common than colored ones, must use shading to
emulate color.

@code{pic2plot -T hpgl}, which produces Hewlett--Packard Graphics
Language output, is also affected by several environment variables.  The
most important is @code{HPGL_VERSION}, which may be set to "1", "1.5",
@w{or "2"} (the default).  @w{"1" means} that the output should be
generic HP-GL, @w{"1.5" means} that the output should be suitable for
the HP7550A graphics plotter and the HP758x, HP7595A and HP7596A
drafting plotters (HP-GL with some HP-GL/2 extensions), and @w{"2"
means} that the output should be modern HP-GL/2.  @w{If the} version is
"1" @w{or "1.5"} then the only available fonts will be vector fonts, and
all lines will be drawn with a default thickness (the @samp{-W} option
will not work).  Additionally, if the version @w{is "1"} then the
filling of arbitrary curves with solid color will not be supported
(circles and rectangles aligned with the coordinate axes may be filled,
though).

The position of the @code{pic2plot -T hpgl} graphics display on the page
can be adjusted by setting the @code{HPGL_XOFFSET} and
@code{HPGL_YOFFSET} environment variables, which may be specified in
centimeters, millimeters, or inches.  For example, an offset could be
specified as "2cm" or "1.2in".  Also, the display can be rotated @w{90
degrees} counterclockwise on the page by setting the @code{HPGL_ROTATE}
environment variable to "yes".  Besides "no" and "yes", recognized
values for this variable are "0", "90", "180", @w{and "270"}.  @w{"no"
and} "yes" are equivalent to @w{"0" and "90"}, respectively.  "180" and
"270" are supported only if @code{HPGL_VERSION} @w{is "2"} (the
default).

@emph{Opaque} filling and the drawing of visible white lines are
supported only if @code{HPGL_VERSION} is "2" (the default) and the
environment variable @code{HPGL_OPAQUE_MODE} is "yes" (the default).
@w{If the} value is "no" then opaque filling will not be used, and white
lines (@w{if any}), which are normally drawn with @w{pen #0}, will not
be drawn.  This feature is to accommodate older HP-GL/2 devices.
HP-GL/2 pen plotters, @w{for example}, do not support opacity or the use
of @w{pen #0} to draw visible white lines.  Some older HP-GL/2 devices
reportedly malfunction if asked to draw opaque objects.

@w{By default}, @code{pic2plot -T hpgl} will draw with a fixed set of
pens.  Which pens are present may be specified by setting the
@code{HPGL_PENS} environment variable.  If @code{HPGL_VERSION} @w{is
"1"}, the default value of @code{HPGL_PENS} is "1=black"; if
@code{HPGL_VERSION} is "1.5" @w{or "2"}, the default value of
@code{HPGL_PENS} is
"1=black:2=red:3=green:4=yellow:5=blue:6=magenta:7=cyan".  The format
should be self-explanatory.  By setting @code{HPGL_PENS}, you may
specify a color for any pen in the range #1@dots{}#31.  For information
on what color names are recognized, see @ref{Color Names}.  @w{Pen #1}
must always be present, though it need not be black. Any other pen in
the range #1@dots{}#31 may be omitted.

If @code{HPGL_VERSION} is "2" then @code{pic2plot -T hpgl} will also be
affected by the environment variable @code{HPGL_ASSIGN_COLORS}.  @w{If
the} value of this variable is "yes", then @code{plot -T hpgl} will not
be restricted to the palette specified in @code{HPGL_PENS}: @w{it will}
assign colors to ``logical pens'' in the range #1@dots{}#31, @w{as
needed}.  The default value is "no" because other than color LaserJet
printers and DesignJet plotters, not many HP-GL/2 devices allow the
assignment of colors to logical pens.

@code{pic2plot -T tek}, which produces output for a Tektronix terminal
or emulator, checks the @code{TERM} environment variable.  @w{If the}
value of @code{TERM} is "xterm", "xterms", or "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 drawing
graphics, @code{pic2plot -T tek} will emit an escape sequence that
causes the terminal emulator's auxiliary Tektronix window, which is
normally hidden, to @w{pop up}.  After the graphics are drawn, an escape
sequence that returns control to the original VT100 window will be
emitted.  The Tektronix window will remain on the screen.

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

@node tek2plot, plotfont, pic2plot, Top
@chapter The @code{tek2plot} Program

@menu
* tek2plot Introduction::     What tek2plot is used for
* tek2plot Invocation::       Command-line options
* tek2plot Environment::      Environment variables
@end menu

@node tek2plot Introduction, tek2plot Invocation, tek2plot, tek2plot
@section What @code{tek2plot} is used for

GNU @code{tek2plot} is a command-line Tektronix translator.  It displays
Tektronix graphics files, or translates them to other formats.  The
@samp{-T} option is used to specify the output format or display type.
Supported output formats include "X", "pnm", "gif", "ai", "ps", "fig",
"pcl", "hpgl", "tek", and "meta" (the default).  These are the same
formats that are supported by the GNU @code{graph}, @code{plot}, and
@code{pic2plot} programs.  @code{tek2plot} will take input from a file
specified on the command line or from standard input, just as the plot
filter @code{plot} does.

Tektronix graphics files are produced by many older applications, such
as @uref{http://tdc-www.harvard.edu/software/skymap, SKYMAP}, a powerful
astronomical display program.  @w{A directory} containing sample
Tektronix graphics files, which you may experiment with, is distributed
along with the GNU plotting utilities.  @w{On most} systems it is
installed as @file{/usr/share/tek2plot} or
@file{/usr/local/share/tek2plot}.

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

@node tek2plot Invocation, tek2plot Environment, tek2plot Introduction, tek2plot
@section @code{tek2plot} command-line options

The @code{tek2plot} program translates the Tektronix graphics files
produced by many older applications to other formats.  The output format
or display type is specified with the @samp{-T} option.  The possible
output formats are the same ten formats that are supported by the GNU
@code{graph}, @code{plot}, and @code{pic2plot} programs.

Input file names may be specified anywhere on the command line.  That
is, the relative order of file names and command-line options does not
matter.  If no file names are specified, or the file @w{name @samp{-}}
is specified, the standard input is read.  The output file is written to
standard output, unless the @samp{-T X} option is specified.  @w{In
that} case the output is displayed in one or more windows on an @w{X
Window} System display, and there is no output file.  

The full set of command-line options is listed below.  There are three
sorts of option:

@enumerate
@item
General options.
@item
Options relevant only to raw @code{tek2plot}, i.e., relevant only if no
display type or output format is specified with the @samp{-T} option.
@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.

The following are general options.

@table @samp
@item -T @var{type}
@itemx --display-type @var{type}
(String, default "meta".)  Select a display type or output format of
type @var{type}, which may be one of the strings "X", "pnm", "gif",
"ai", "ps", "fig", "pcl", "hpgl", "tek", and "meta".  These refer
respectively to the @w{X Window System}, portable anymap (PBM/PGM/PPM)
format, pseudo-GIF format, the format used by Adobe Illustrator,
@code{idraw}-editable Postscript, the format used by the @code{xfig}
drawing editor, the Hewlett--Packard @w{PCL 5} printer language, the
Hewlett--Packard Graphics Language (@w{by default}, HP-GL/2), Tektronix
format, and device-independent GNU graphics metafile format.

@item -p @var{n}
@itemx --page-number @var{n}
(Nonnegative integer.) Display only page number @var{n}, within the
Tektronix file or sequence of Tektronix files that is being translated.
Tektronix files may consist of one or more pages, numbered beginning
with zero.

The default behavior, if the @samp{-p} option is not used, is to display
all nonempty pages in succession.  For example, @code{tek2plot @w{-T X}}
displays each page in its own @w{X window}.  @w{If the} @samp{-T pnm}
option, the @samp{-T gif} option, the @samp{-T ai} option, or the
@samp{-T fig} option is used, the default behavior is to display only
the first page, since files in PNM, pseudo-GIF, AI, or Fig format may
contain only a single page of graphics.

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

@item -F @var{font_name}
@itemx --font-name @var{font_name}
(String, default "Courier" except for @code{tek2plot -T pnm},
@code{tek2plot -T gif}, @code{tek2plot -T pcl}, @code{tek2plot -T hpgl},
and raw @code{tek2plot}, for all of which "HersheySerif" is the
default.)  Set the font used for text to @var{font_name}.  Font names
are case-insensitive.  @w{If a} font outside the Courier family is
chosen, the @samp{--position-chars} option (see below) should probably
be used.  For a list of all fonts, see @ref{Text Fonts}.  @w{If the}
specified font is not available, the default font will be used.

@item -W @var{line_width}
@itemx --line-width @var{line_width}
(Float, default @minus{}1.0.)  Set the thickness of lines, as a fraction
of the size (i.e., minimum dimension) of the graphics 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 is
usually 1/850 times the size of the display, although if @samp{-T X},
@samp{-T pnm}, or @code{-T gif} is specified, it is zero.  By
convention, a zero-thickness line is the thinnest line that can be
drawn.  This is the case in all output formats.  Note, however, that the
drawing editors @code{idraw} and @code{xfig} treat zero-thickness lines
as invisible.

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

@item --bg-color @var{name}
(String, default "white".)  Set the color used for the background to be
@var{name}.  This is relevant only to @code{tek2plot @w{-T X}},
@code{tek2plot -T pnm}, and @code{tek2plot -T gif}.  @w{An unrecognized}
name sets the color to the default.  For information on what names are
recognized, see @ref{Color Names}.  The environment variable
@code{BG_COLOR} can equally well be used to specify the background
color.

If the @samp{-T gif} option is used, a transparent pseudo-GIF may be
produced by setting the @code{TRANSPARENT_COLOR} environment variable to
the name of the background color.  @xref{tek2plot Environment}.

@item --bitmap-size @var{bitmap_size}
(String, default "570x570".)  Set the size of the graphics display in
which the plot will be drawn, in terms of pixels, to be
@var{bitmap_size}.  This is relevant only to @code{tek2plot @w{-T X}},
@code{tek2plot -T pnm}, and @code{tek2plot -T gif}, for which the
graphics display size can be expressed in terms of pixels.  The
environment variable @code{BITMAPSIZE} can equally well be used to
specify the size.

The graphics display used by @code{tek2plot -T X} is an @w{X window}.
If you choose a rectangular (non-square) window size, the fonts in the
plot will be scaled anisotropically, i.e., by different factors in the
horizontal and vertical direction.  This requires an X11R6 display.  Any
font that cannot be scaled in this way will be replaced by a default
scalable font, such as the Hershey vector font "HersheySerif".

For backward compatibility, the @w{X resource} @code{Xplot.geometry},
which can be set by the user, may be used to set the window size,
instead of @samp{--bitmap-size} or @code{BITMAPSIZE}@.

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

The reason for splitting long polygonal lines is that some display
devices (e.g., old Postscript printers and HP-GL pen plotters) have
limited buffer sizes.  The environment variable @code{MAX_LINE_LENGTH}
can also be used to specify the maximum line length.  This option has no
effect on raw @code{tek2plot}, since it draws polylines in real time and
has no buffer limitations.

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

For @code{tek2plot -T ai} and @code{tek2plot -T ps}, the graphics
display within which the plot is drawn will be a square region centered
on the specified page, occupying its full width (with allowance being
made for margins).  For @code{tek2plot -T fig}, it will be a square
region of the same size, located in the upper left corner of an
@code{xfig} display.  For @code{tek2plot -T pcl} and @code{tek2plot -T
hpgl}, the graphics display will be a square region of the same size,
but may be positioned differently.  Fine control its positioning on the
page can be accomplished by setting certain environment variables
(@pxref{tek2plot Environment}).

@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, see @ref{Color Names}.

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

@item --rotation @var{angle}
(Integer, default 0.)  Set the rotation angle of the plot within the
graphics display to be @var{angle} degrees.  Recognized values are 0,
90, 180, and 270.  The rotation is counterclockwise.

This option is used for switching between portrait mode and landscape
mode.  Postmodernists may also find it useful.

@item --use-tek-fonts
Use the bitmap fonts that were used on the original Tektronix 4010/4014
terminal.  This option is relevant only to @code{tek2plot @w{-T X}}.
The four relevant bitmap fonts are distributed with most versions of the
plotting utilities package, under the names
@code{tekfont0}@dots{}@code{tekfont3}.  They may easily be installed on
any modern @w{X Window} System display.  For this option to work
properly, you must also select a window size of 1024x1024 pixels, either
by using the @code{--bitmap-size 1024x1024} option or by setting the
value of the @code{Xplot.geometry} resource.  The reason for this
restriction is that bitmap fonts, unlike the scalable fonts that the
plotting utilities normally use, cannot be rescaled.

This option is useful only if you have a file in Tektronix format that
draws text using native Tektronix fonts.  Tektronix files produced by
the GNU plotting utilities (e.g., by @code{graph -T tek}) @w{do not} use
native Tektronix fonts to draw text.
@end table

The following option is relevant only to raw @code{tek2plot}, i.e.,
relevant only if no display type or output format is specified with the
@samp{-T} option.  In this case @code{tek2plot} outputs a graphics
metafile, which may be translated to other formats by invoking
@code{plot}.

@table @samp
@item -O
@itemx --portable-output
Output the portable (human-readable) version of GNU metafile format,
rather than a binary version (the default).  This can also be requested
by setting the environment variable @code{META_PORTABLE} to "yes".
@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 table of available fonts, and then exit.  The table will depend
on which display type or output format is specified with the @samp{-T}
option.  @code{tek2plot @w{-T X}}, @code{tek2plot -T ai}, @code{tek2plot
-T ps}, and @code{tek2plot -T fig} each support the 35 standard
Postscript fonts.  @code{tek2plot -T ai}, @code{tek2plot -T pcl}, and
@code{tek2plot -T hpgl} support the 45 standard @w{PCL 5} fonts, and
@code{tek2plot -T pcl} and @code{tek2plot -T hpgl} support a number of
Hewlett--Packard vector fonts.  All of the preceding, together with
@code{tek2plot -T pnm}, @code{tek2plot -T gif}, and @code{tek2plot
-T tek}, support a set of 22 Hershey vector fonts.  Raw @code{tek2plot}
@w{in principle} supports any of these fonts, since its output must be
translated to other formats with @code{plot}.  The @code{plotfont}
utility will produce a character map of any available font.
@xref{plotfont}.

@item --list-fonts
Like @samp{--help-fonts}, but lists the fonts in a single column to
facilitate piping to other programs.  @w{If no} display type or output
format is specified with the @samp{-T} option, the full set of supported
fonts is listed.

@item --version
Print the version number of @code{tek2plot} and the plotting utilities
package, and exit.
@end table

@node tek2plot Environment, , tek2plot Invocation, tek2plot
@section Environment variables

The behavior of @code{tek2plot} is affected by several environment
variables, which are the same as those that affect @code{graph} and
@code{plot}.  For convenience, we list them here.

We have already mentioned the environment variables @code{BITMAPSIZE},
@code{PAGESIZE}, @code{BG_COLOR}, and @code{MAX_LINE_LENGTH}.  They
serve as backups for the options @samp{--bitmap-size},
@samp{--page-size}, @samp{--bg-color}, and @samp{--max-line-length}.
The remaining environment variables are specific to individual output
formats.

@code{tek2plot @w{-T X}}, which pops up a window on an @w{X Window}
System display and draws graphics @w{in it}, checks the @code{DISPLAY}
environment variable.  The value of this variable determines the display
on which the window will be @w{popped up}.

@code{tek2plot -T pnm}, which produces output in Portable Anymap
(PBM/PGM/PPM) format, is affected by the @code{PNM_PORTABLE} environment
variable.  If its value is "yes", the output file will be in the
portable (human readable) version of PBM, PGM, or PPM format, rather
than the default (binary) version.

@code{tek2plot -T gif}, which produces output in pseudo-GIF format, is
affected by two environment variables.  If the value of the
@code{INTERLACE} variable is "yes", the pseudo-GIF output file will be
in interlaced format.  Also, if the value of the
@code{TRANSPARENT_COLOR} environment variable is the name of a color
that appears in the output file, that color will be treated as
transparent by most applications that read GIF files.  For information
on what color names are recognized, see @ref{Color Names}.

@code{tek2plot -T pcl}, which produces @w{PCL 5} output for
Hewlett--Packard printers and plotters, is affected by several
environment variables.  The position of the graphics display on the page
can be adjusted by setting the @code{PCL_XOFFSET} and @code{PCL_YOFFSET}
environment variables, which may be specified in centimeters,
millimeters, or inches.  For example, an offset could be specified as
"2cm" or "1.2in".  Also, the display can be rotated @w{90 degrees}
counterclockwise on the page by setting the @code{PCL_ROTATE}
environment variable to "yes".  This is not the same as the rotation
obtained with the @code{--rotation} option, which sets the rotation
angle of the plot within the display.  Besides "no" and "yes",
recognized values for the @code{PCL_ROTATE} variable are "0", "90",
"180", @w{and "270"}.  @w{"no" and} "yes" are equivalent to @w{"0" and
"90"}, respectively.

The variable @code{PCL_ASSIGN_COLORS} is also recognized.  It should be
set to "yes" when producing @w{PCL 5} output for a color printer or
other color device.  This will ensure accurate color reproduction by
giving the output device complete freedom in assigning colors,
internally, to its ``logical pens''.  If it is "no" then the device will
use a fixed set of colored pens, and will emulate other colors by
shading.  The default is "no" because monochrome @w{PCL 5} devices,
which are much more common than colored ones, must use shading to
emulate color.

@code{tek2plot -T hpgl}, which produces Hewlett--Packard Graphics
Language output, is also affected by several environment variables.  The
most important is @code{HPGL_VERSION}, which may be set to "1", "1.5",
@w{or "2"} (the default).  @w{"1" means} that the output should be
generic HP-GL, @w{"1.5" means} that the output should be suitable for
the HP7550A graphics plotter and the HP758x, HP7595A and HP7596A
drafting plotters (HP-GL with some HP-GL/2 extensions), and @w{"2"
means} that the output should be modern HP-GL/2.  @w{If the} version is
"1" @w{or "1.5"} then the only available fonts will be vector fonts, and
all lines will be drawn with a default thickness (the @samp{-W} option
will not work).

The position of the @code{tek2plot -T hpgl} graphics display on the page
can be adjusted by setting the @code{HPGL_XOFFSET} and
@code{HPGL_YOFFSET} environment variables, which may be specified in
centimeters, millimeters, or inches.  For example, an offset could be
specified as "2cm" or "1.2in".  Also, the display can be rotated @w{90
degrees} counterclockwise on the page by setting the @code{HPGL_ROTATE}
environment variable to "yes".  This is not the same as the rotation
obtained with the @code{--rotation} option, which sets the rotation
angle of the plot within the display.  Besides "no" and "yes",
recognized values for the @code{HPGL_ROTATE} variable are "0", "90",
"180", @w{and "270"}.  @w{"no" and} "yes" are equivalent to @w{"0" and
"90"}, respectively.  "180" and "270" are supported only if
@code{HPGL_VERSION} @w{is "2"} (the default).

The drawing of visible white lines is supported only if
@code{HPGL_VERSION} is "2" and the environment variable
@code{HPGL_OPAQUE_MODE} is "yes" (the default).  @w{If the} value is
"no" then white lines (@w{if any}), which are normally drawn with @w{pen
#0}, will not be drawn.  This feature is to accommodate older HP-GL/2
devices.  HP-GL/2 pen plotters, @w{for example}, do not support the use
of @w{pen #0} to draw visible white lines.  Some older HP-GL/2 devices
may, @w{in fact}, malfunction if asked to draw opaque objects.

@w{By default}, @code{tek2plot -T hpgl} will draw with a fixed set of
pens.  Which pens are present may be specified by setting the
@code{HPGL_PENS} environment variable.  If @code{HPGL_VERSION} @w{is
"1"}, the default value of @code{HPGL_PENS} is "1=black"; if
@code{HPGL_VERSION} is "1.5" @w{or "2"}, the default value of
@code{HPGL_PENS} is
"1=black:2=red:3=green:4=yellow:5=blue:6=magenta:7=cyan".  The format
should be self-explanatory.  By setting @code{HPGL_PENS}, you may
specify a color for any pen in the range #1@dots{}#31.  For information
on what color names are recognized, see @ref{Color Names}.  @w{Pen #1}
must always be present, though it need not be black. Any other pen in
the range #1@dots{}#31 may be omitted.

If @code{HPGL_VERSION} is "2" then @code{tek2plot -T hpgl} will also be
affected by the environment variable @code{HPGL_ASSIGN_COLORS}.  @w{If
the} value of this variable is "yes", then @code{tek2plot -T hpgl} will
not be restricted to the palette specified in @code{HPGL_PENS}: @w{it
will} assign colors to ``logical pens'' in the range #1@dots{}#31, @w{as
needed}.  The default value is "no" because other than color LaserJet
printers and DesignJet plotters, not many HP-GL/2 devices allow the
assignment of colors to logical pens.

@node plotfont, spline, tek2plot, Top
@chapter The @code{plotfont} Utility

@menu
* plotfont Examples::         How to use plotfont
* plotfont Invocation::       Command-line options
* plotfont Environment::      Environment variables
@end menu

@node plotfont Examples, plotfont Invocation, plotfont, plotfont
@section How to use @code{plotfont}

GNU @code{plotfont} is a simple utility that will produce a character
map for any font available to the GNU plotting utilities @code{graph},
@code{plot}, @code{pic2plot}, and @code{tek2plot}, and the GNU
@code{libplot} graphics library on which they are based.  The map may be
displayed on an @w{X Window} System display, or produced in any of
several output formats.  The @samp{-T} option is used to specify the
desired output format.  Supported output formats include "X", "pnm",
"gif", "ai", "ps", "fig", "pcl", "hpgl", "tek", and "meta" (the
default).

Which fonts are available depends on the choice of display or output
format.  @w{To get} a list of the available fonts, use the
@samp{--help-fonts} option.  For example,

@example
plotfont -T ps --help-fonts
@end example

@noindent
will list the fonts that are available when producing Postscript output.
One of these fonts is "Times-Roman".  Doing

@example
plotfont -T ps Times-Roman > map.ps
@end example

@noindent
will produce a character map of the lower half of this font, which
consists of printable ASCII characters.  The map will be a 12x8 grid,
with a character centered in each grid cell.  If you include the
@samp{-2} option, you will get a map of the upper half of the font.

Most built-in fonts are ISO-Latin-1 fonts, which means that the upper
half is arranged according to the ISO-Latin-1 encoding.  The
"HersheyCyrillic" font is one that is not.  If you do

@example
plotfont -T ps -2 HersheyCyrillic > map.ps
@end example

@noindent
you will get a map that illustrates its arrangment, which is called
@w{KOI8-R}@.  The @w{KOI8-R} arrangement is the standard for Unix and
networking applications in the former Soviet Union.  So-called dingbats
fonts, such as "ZapfDingbats" and "Wingdings", also have an
individualistic layout.  In most installations of the plotting
utilities, the Wingdings font is not available when producing Postscript
output.  However, @w{it is} available when producing output in @w{PCL 5}
or HP-GL/2 format.  If you do

@example
plotfont -T hpgl Wingdings > map.plt
@end example

@noindent
you will get a Wingdings character map, in HP-GL/2 format, that may be
imported into any application that understands HP-GL/2.  Similarly,
@code{plot -T pcl Wingdings} will produce a Wingdings character map in
@w{PCL 5} format, which may be printed on a LaserJet or other @w{PCL 5}
device.  

In all, more than a hundred fonts are built into the plotting utilities.
@xref{Text Fonts}.  Actually, if you are using the plotting utilities to
display output on an @w{X display}, you are not restricted to the
built-in fonts.  Doing

@example
plotfont -T X --help-fonts
@end example

@noindent
produces a list of the built-in fonts that are available, including both
Hershey and Postscript fonts.  But fonts available on your @w{X display}
may also be used.  The @code{xlsfonts} command will list the fonts
available on your @w{X display}, most font names being given in what is
called XLFD format.  The plotting utilities refer to @w{X fonts} by
shortened versions of their XLFD names.  For example, the font
"Utopia-Regular" is available on many @w{X displays}.  Its XLFD name is
"-adobe-utopia-medium-r-normal--0-0-0-0-p-0-iso8859-1", and its
shortened XLFD name is "utopia-medium-r-normal".  If you do

@example
plotfont -T X utopia-medium-r-normal
@end example

@noindent
then a character map for this font will be displayed in a popped-up
@w{X window}.

When using the @samp{-T X} option, you may also use the
@samp{--bitmap-size} option to choose the size of the popped-up window.
Modern @w{X displays} can scale fonts by different amounts in the
horizontal and vertical directions.  If, for example, you add
@samp{--bitmap-size 600x300} to the above command line, both the
character map and the Utopia-Regular font @w{within it} will be scaled
in this way.  @w{If your} @w{X display} does not support font scaling,
@w{a scalable} font will be substituted.

@node plotfont Invocation, plotfont Environment, plotfont Examples, plotfont
@section @code{plotfont} command-line options

The @code{plotfont} font display utility will produce a character map
for any of the fonts available to the GNU plotting utilities
@code{graph}, @code{plot}, @code{pic2plot}, and @code{tek2plot}, and the
GNU @code{libplot} graphics library on which they are based.  The map
may be produced in any supported output format, or displayed on an @w{X
Window} System display.  The output format or display type is specified
with the @samp{-T} option.

The names of the fonts for which a character map will be produced may
appear anywhere on the @code{plotfont} command line.  That is, the
relative order of font names and command-line options does not matter.
The character map is written to standard output, unless the @samp{-T X}
option is specified.  @w{In that} case the character map is displayed in
a window on an @w{X Window} System display, and there is no output file.

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

@enumerate
@item
General options.
@item
Options relevant only to raw @code{plotfont}, i.e., relevant only if no
display type or output format is specified with the @samp{-T} option.
@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.  

The following are general options.

@table @samp
@item -1
@itemx --lower-half
Generate a character map for the lower half of each specified font.
This is the default.

@item -2
@itemx --upper-half
Generate a character map for the upper half of each specified font.

@item -o
@itemx --octal
Number the characters in octal rather than in decimal (the default).

@item -x
@itemx --hexadecimal
Number the characters in hexadecimal rather than in decimal (the default).

@item --box
Surround each character with a box, showing its extent to left and
right.  The default is not to do this.

@item -j @var{row}
@itemx --jis-row @var{row}
Generate a character map for row @var{row} of a Japanese font arranged
according to JIS [Japanese Industrial Standard] X0208.  The only such
font currently available is the HersheyEUC [Extended Unix Code] font.
@w{If used}, this option overrides the @samp{-1} and @samp{-2} options.

The valid rows are 1@dots{}94.  In the JIS X0208 standard, Roman
characters are located in @w{row 3}, and Japanese syllabic characters
(Hiragana and Katakana) are located in rows 4 @w{and 5}.  Greek and
Cyrillic characters are located in rows 6 @w{and 7}.  Japanese
ideographic characters (Kanji) are located in rows 16@dots{}84.  Rows
16@dots{}47 contain the JIS @w{Level 1} Kanji, which are the most
frequently used.  They are arranged according @w{to On} (old Chinese)
reading.  Rows 48@dots{}84 contain the less frequently used JIS @w{Level
2} Kanji.

The HersheyEUC font contains 596 of the 2965 @w{Level 1} Kanji, and
seven of the @w{Level 2} Kanji.  @w{It uses} the 8-bit EUC-JP encoding.
This encoding is a multibyte encoding that includes the ASCII character
set @w{as well} as the JIS X0208 characters.  It represents each ASCII
character in the usual way, i.e., as a single byte that does not have
its high bit set.  Each JIS X0208 character is represented as two bytes,
each with the high bit set.  The first byte contains the row number
@w{(plus 32)}, and the second byte contains the character number.

@item -T @var{type}
@itemx --display-type @var{type}
(String, default "meta".)  Select a display type or output format of
type @var{type}, which may be one of the strings "X", "pnm", "gif",
"ai", "ps", "fig", "pcl", "hpgl", "tek", and "meta".  These refer
respectively to the @w{X Window System}, portable anymap (PBM/PGM/PPM)
format, pseudo-GIF format, the format used by Adobe Illustrator,
@code{idraw}-editable Postscript, the format used by the @code{xfig}
drawing editor, the Hewlett--Packard @w{PCL 5} printer language, the
Hewlett--Packard Graphics Language (@w{by default}, HP-GL/2), Tektronix
format, and device-independent GNU graphics metafile format.

Files in PNM, pseudo-GIF, AI, or Fig format may contain only a single
page of graphics.  So if the @samp{-T pnm} option, the @samp{-T gif}
option, the @samp{-T ai} option, or the @samp{-T fig} option is used,
a character map will be produced for only the first-specified font.

@item --bg-color @var{name}
(String, default "white".)  Set the color used for the background to be
@var{name}.  This is relevant only to @code{plotfont @w{-T X}},
@code{plotfont -T pnm}, and @code{plotfont -T gif}.  @w{An unrecognized}
name sets the color to the default.  For information on what names are
recognized, see @ref{Color Names}.  The environment variable
@code{BG_COLOR} can equally well be used to specify the background
color.

If the @samp{-T gif} option is used, a transparent pseudo-GIF may be
produced by setting the @code{TRANSPARENT_COLOR} environment variable to
the name of the background color.  @xref{plotfont Environment}.

@item --bitmap-size @var{bitmap_size}
(String, default "570x570".)  Set the size of the graphics display in
which the plot will be drawn, in terms of pixels, to be
@var{bitmap_size}.  This is relevant only to @code{plotfont @w{-T X}},
@code{plotfont -T pnm}, and @code{plotfont -T gif}, for which the
graphics display size can be expressed in terms of pixels.  The
environment variable @code{BITMAPSIZE} can equally well be used to
specify the size.

The graphics display used by @code{plotfont -T X} is an @w{X window}.
If you choose a rectangular (non-square) window size, the fonts in the
plot will be scaled anisotropically, i.e., by different factors in the
horizontal and vertical direction.  This requires an X11R6 display.  Any
font that cannot be scaled in this way will be replaced by a default
scalable font, such as the Hershey vector font "HersheySerif".

For backward compatibility, the @w{X resource} @code{Xplot.geometry},
which can be set by the user, may be used to set the window size,
instead of @samp{--bitmap-size} or @code{BITMAPSIZE}@.

@item --numbering-font-name @var{font_name}
(String, default "Helvetica" except for @code{plotfont -T pnm},
@code{plotfont -T gif}, @code{plotfont -T pcl}, @code{plotfont -T hpgl}
and @code{plotfont -T tek}, for which "HersheySerif" is the default.)
Set the font used for the numbering of the characters in the character
map(s) to be @var{font_name}.

@item --page-size @var{pagesize}
(String, default "letter".)  Set the size of the page for which the
character map(s) will be produced.  This is relevant only to
@code{plotfont -T ai}, @code{plotfont -T ps}, @code{plotfont -T fig},
@code{plotfont -T pcl} and @code{plotfont -T hpgl}.  "letter" means an
8.5@dmn{in} by 11@dmn{in} page.  Any ISO page size in the range
"a0"@dots{}"a4" or ANSI page size in the range "a"@dots{}"e" may be
specified ("letter" is an alias @w{for "a"} and "tabloid" is an alias
@w{for "b"}).  "legal", "ledger", @w{and "b5"} are recognized page sizes
also.  The environment variable @code{PAGESIZE} can equally well be used
to specify the page size.

For @code{plotfont -T ai} and @code{plotfont -T ps}, the graphics
display within which each character map is drawn will be a square region
centered on the specified page, occupying its full width (with allowance
being made for margins).  For @code{plotfont -T fig}, it will be a
square region of the same size, located in the upper left corner of an
@code{xfig} display.  For @code{plotfont -T pcl} and @code{plotfont -T
hpgl}, the graphics display will be a square region of the same size,
but may be positioned differently.  Fine control over its positioning on
the page can be accomplished by setting certain environment variables
(@pxref{plotfont Environment}).

@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, see @ref{Color Names}.

@item --rotation @var{angle}
(Integer, default 0.)  Set the rotation angle of the character map(s)
within the graphics display to be @var{angle} degrees.  Recognized
values are 0, 90, 180, and 270.  The rotation is counterclockwise.

This option is used for switching between portrait mode and landscape
mode.  Postmodernists may also find it useful.

@item --title-font-name @var{font_name}
(String) Set the font used for the title of each character map to be
@var{font_name}.  Normally the font used for the title is the same as
the font whose character set is being displayed.  This option is useful
when producing character maps for unusual fonts such as "ZapfDingbats"
and "Wingdings".
@end table

The following option is relevant only to raw @code{plotfont}, i.e.,
relevant only if no display type or output format is specified with the
@samp{-T} option.  In this case @code{plotfont} outputs a graphics
metafile, which may be translated to other formats by invoking
@code{plot}.

@table @samp
@item -O
@itemx --portable-output
Output the portable (human-readable) version of GNU metafile format,
rather than a binary version (the default).  This can also be requested
by setting the environment variable @code{META_PORTABLE} to "yes".
@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 table of available fonts, and then exit.  The table will depend
on which display type or output format is specified with the @samp{-T}
option.  @code{plotfont @w{-T X}}, @code{plotfont -T ai}, @code{plotfont
-T ps}, and @code{plotfont -T fig} each support the 35 standard
Postscript fonts.  @code{plotfont -T ai}, @code{plotfont -T pcl}, and
@code{plotfont -T hpgl} support the 45 standard @w{PCL 5} fonts, and
@code{plotfont -T pcl} and @code{plotfont -T hpgl} support a number of
Hewlett--Packard vector fonts.  All of the preceding, together with
@code{plotfont -T pnm}, @code{plotfont -T gif}, and @code{plotfont -T
tek}, support a set of 22 Hershey vector fonts.  Raw @code{plotfont}
@w{in principle} supports any of these fonts, since its output must be
translated to other formats with @code{plot}.

@item --list-fonts
Like @samp{--help-fonts}, but lists the fonts in a single column to
facilitate piping to other programs.  @w{If no} display type or output
format is specified with the @samp{-T} option, the full set of supported
fonts is listed.

@item --version
Print the version number of @code{plotfont} and the plotting utilities
package, and exit.
@end table

@node plotfont Environment, , plotfont Invocation, plotfont
@section Environment variables

The behavior of @code{plotfont} is affected by several environment
variables, which are the same as those that affect @code{graph},
@code{plot}, and @code{tek2plot}.  For convenience, we list them here.

We have already mentioned the environment variables @code{BITMAPSIZE},
@code{PAGESIZE}, and @code{BG_COLOR}.  They serve as backups for the
options @samp{--bitmap-size}, @samp{--page-size}, and @samp{--bg-color}.
The remaining environment variables are specific to individual output
formats.

@code{plotfont @w{-T X}}, which pops up a window on an @w{X Window}
System display and draws a character map @w{in it}, checks the
@code{DISPLAY} environment variable.  The value of this variable
determines the display on which the window will be @w{popped up}.

@code{plotfont -T pnm}, which produces output in Portable Anymap
(PBM/PGM/PPM) format, is affected by the @code{PNM_PORTABLE} environment
variable.  If its value is "yes", the output file will be in the
portable (human readable) version of PBM, PGM, or PPM format, rather
than the default (binary) version.

@code{plotfont -T gif}, which produces output in pseudo-GIF format, is
affected by two environment variables.  If the value of the
@code{INTERLACE} variable is "yes", the pseudo-GIF output file will be
in interlaced format.  Also, if the value of the
@code{TRANSPARENT_COLOR} environment variable is the name of a color
that appears in the output file, that color will be treated as
transparent by most applications that read GIF files.  For information
on what color names are recognized, see @ref{Color Names}.

@code{plotfont -T pcl}, which produces @w{PCL 5} output for
Hewlett--Packard printers and plotters, is affected by several
environment variables.  The position of the graphics display on the page
can be adjusted by setting the @code{PCL_XOFFSET} and @code{PCL_YOFFSET}
environment variables, which may be specified in centimeters,
millimeters, or inches.  For example, an offset could be specified as
"2cm" or "1.2in".  Also, the display can be rotated @w{90 degrees}
counterclockwise on the page by setting the @code{PCL_ROTATE}
environment variable to "yes".  This is not the same as the rotation
obtained with the @code{--rotation} option, which sets the rotation
angle of the character map within the display.  Besides "no" and "yes",
recognized values for the @code{PCL_ROTATE} variable are "0", "90",
"180", @w{and "270"}.  @w{"no" and} "yes" are equivalent to @w{"0" and
"90"}, respectively.

The variable @code{PCL_ASSIGN_COLORS} is also recognized.  It should be
set to "yes" when producing @w{PCL 5} output for a color printer or
other color device.  This will ensure accurate color reproduction by
giving the output device complete freedom in assigning colors,
internally, to its ``logical pens''.  If it is "no" then the device will
use a fixed set of colored pens, and will emulate other colors by
shading.  The default is "no" because monochrome @w{PCL 5} devices,
which are much more common than colored ones, must use shading to
emulate color.

@code{plotfont -T hpgl}, which produces Hewlett--Packard Graphics
Language output, is also affected by several environment variables.  The
most important is @code{HPGL_VERSION}, which may be set to "1", "1.5",
@w{or "2"} (the default).  @w{"1" means} that the output should be
generic HP-GL, @w{"1.5" means} that the output should be suitable for
the HP7550A graphics plotter and the HP758x, HP7595A and HP7596A
drafting plotters (HP-GL with some HP-GL/2 extensions), and @w{"2"
means} that the output should be modern HP-GL/2.  @w{If the} version is
"1" @w{or "1.5"} then the only available fonts will be vector fonts.

The position of the @code{plotfont -T hpgl} graphics display on the page
can be adjusted by setting the @code{HPGL_XOFFSET} and
@code{HPGL_YOFFSET} environment variables, which may be specified in
centimeters, millimeters, or inches.  For example, an offset could be
specified as "2cm" or "1.2in".  Also, the display can be rotated @w{90
degrees} counterclockwise on the page by setting the @code{HPGL_ROTATE}
environment variable to "yes".  This is not the same as the rotation
obtained with the @code{--rotation} option, which sets the rotation
angle of the character map within the display.  Besides "no" and "yes",
recognized values for the @code{HPGL_ROTATE} variable are "0", "90",
"180", @w{and "270"}.  @w{"no" and} "yes" are equivalent to @w{"0" and
"90"}, respectively.  "180" and "270" are supported only if
@code{HPGL_VERSION} @w{is "2"} (the default).

@w{By default}, @code{plotfont -T hpgl} will draw with a fixed set of
pens.  Which pens are present may be specified by setting the
@code{HPGL_PENS} environment variable.  If @code{HPGL_VERSION} @w{is
"1"}, the default value of @code{HPGL_PENS} is "1=black"; if
@code{HPGL_VERSION} is "1.5" @w{or "2"}, the default value of
@code{HPGL_PENS} is
"1=black:2=red:3=green:4=yellow:5=blue:6=magenta:7=cyan".  The format
should be self-explanatory.  By setting @code{HPGL_PENS}, you may
specify a color for any pen in the range #1@dots{}#31.  For information
on what color names are recognized, see @ref{Color Names}.  @w{Pen #1}
must always be present, though it need not be black. Any other pen in
the range #1@dots{}#31 may be omitted.

If @code{HPGL_VERSION} is "2" then @code{plotfont -T hpgl} will also be
affected by the environment variable @code{HPGL_ASSIGN_COLORS}.  @w{If
the} value of this variable is "yes", then @code{plotfont -T hpgl} will
not be restricted to the palette specified in @code{HPGL_PENS}: @w{it
will} assign colors to ``logical pens'' in the range #1@dots{}#31, @w{as
needed}.  The default value is "no" because other than color LaserJet
printers and DesignJet plotters, not many HP-GL/2 devices allow the
assignment of colors to logical pens.

@code{plotfont -T tek}, which produces output for a Tektronix terminal
or emulator, checks the @code{TERM} environment variable.  @w{If the}
value of @code{TERM} is "xterm", "xterms", or "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 drawing
graphics, @code{plotfont -T tek} will emit an escape sequence that
causes the terminal emulator's auxiliary Tektronix window, which is
normally hidden, to @w{pop up}.  After the graphics are drawn, an escape
sequence that returns control to the original VT100 window will be
emitted.  The Tektronix window will remain on the screen.

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

@node spline, ode, plotfont, Top
@chapter The @code{spline} Program

@menu
* spline Examples::         How to use spline
* Advanced Use of spline::  More sophisticated uses
* spline Invocation::       Command-line options
@end menu

@node spline Examples, Advanced Use of spline, spline, spline
@section How to use @code{spline}

GNU @code{spline} is a program for interpolating between the data points
in one or more datasets.  Each dataset would consist of values for an
independent variable and a dependent variable, which may be a vector of
specified fixed length.  When discussing interpolation, we call these
variables `@math{t}' and `@math{y}', respectively.  @w{To emphasize:}
@w{@math{t} is a scalar}, but @w{in general} the dependent variable
@w{@math{y} may} be a vector.

The simplest case is when there is a single input file, which is in
ASCII format, and the @w{vector @math{y}} is one-dimensional.  This is
the default.  For example, the input file could contain the dataset

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

@noindent
which are the coordinates @math{(t,y)} 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{t} @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, @w{by default} the
@math{t} coordinate should be monotonically increasing, so that
@w{@math{y} may} be viewed as a function @w{of @math{t}}.

You would construct a spline (the graph of an `interpolating function')
passing through the points in this 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 -T 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 -T 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, or if the special file @w{name @samp{-}}
is specified.

What exactly does @code{spline} do?  First, it fits a curve (the graph
of an interpolating function) through the points in the dataset.  Then
it splits the interval over which the independent @w{variable @math{t}}
ranges 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{(t, 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 positive
integer.  You may also use the @samp{-t} option to specify an
interpolation interval that differs from the default (the interval over
which the independent variable ranges).  For example, the command

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

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

In general, the interpolating function will be a piecewise cubic spline.
That is, between each pair of adjacent `knots' (points in the input
dataset), @w{@math{y} will} be a cubic function @w{of @math{t}}.  This
function will differ, depending on which pair of knots @w{@math{y} lies}
between.  At each knot, 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 can be specified with the @samp{-T}
option.  For example, a spline under considerable tension can be
computed and displayed by doing

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

@noindent
As the tension parameter is increased to positive infinity, the spline
will converge to a polygonal line.  You are meant 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 range of
the independent @w{variable @math{t}} over which the spline will `like
to curve'.  Increasing the tension far above zero will accordingly force
the spline to consist of short curved sections, centered on the data
points, and sections that are almost straight.  It follows that tension
is a `dimensionful' quantity.  @w{If the} tension is nonzero, then when
the values of the independent variable are multiplied by some common
positive factor, the tension should be divided by the same factor to
obtain a scaled version of the original spline.  @w{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 
@ifnottex
@math{y''''=sgn(tension)*(tension^2)y''} 
@end ifnottex
@tex
$$y''''={\rm sgn}({\sl tension}){\sl tension}^2\thinspace y''$$
@end tex
between each successive pair of knots.  If the tension equals zero,
which is the default, the fourth derivative of @math{y} with respect
@w{to @math{t}} will equal zero at every point.  In this case, @math{y}
as a function @w{of @math{t}} will reduce to a cubic polynomial between
each successive pair of knots.  But if the tension is nonzero, @math{y}
will not be a polynomial function @w{of @math{t}}.  @w{It may} be expressed
@w{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 @math{t}}.  This will only work if the @math{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.  @w{That is}, @w{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.  @w{If
@samp{-f}} is specified, @samp{-p} may not be specified.  Also, if
@samp{-f} is specified then an interpolation interval (@w{a range} of
@w{@math{t} values}) must be requested explicitly with the @samp{-t}
option.

Cubic Bessel interpolation is inherently less smooth than the
construction of a global cubic spline.  @w{If the} @samp{-f} option is
specified, the slope of the spline at each knot will be chosen by
fitting a parabola through that knot, and the two adjacent knots.  The
slopes of the two interpolating segments to either side of each interior
knot will match at that knot, 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.

@node Advanced Use of spline, spline Invocation, spline Examples, spline
@section Advanced use of @code{spline}

The preceding section explains how @code{spline} can be employed to
interpolate a function @math{y} of a scalar variable @math{t}, in the
case when @math{y} is a scalar.  In this section we explain how to
perform more sophisticated interpolations.  This includes
multidimensional interpolations, and interpolations that are splinings
of curves, rather than of functions.

@code{spline} can handle the case when @w{@math{y} is} a vector of
arbitrary specified dimensionality.  The dimension can be specified with
the @samp{-d} option.  For example, an input file could contain the
multidimensional dataset

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

@noindent
which are the coordinates @math{(t,y)} of the data points (0,0,1),
(1,1,0), and (2,0,1).  You would construct a spline (the graph of an
interpolating function) passing through the points in this dataset by
doing

@example
spline -d 2 input_file > output_file
@end example

@noindent
The option @samp{-d 2} is used because in this example, the dependent
variable @math{y} is a two-dimensional vector.  Each of the components
of @math{y} will be interpolated independently, and the output file will
contain points that lie along the graph of the resulting interpolating
function.

When doing multidimensional splining, you may use any of the options
that apply in the default one-dimensional case.  For example, the
@samp{-f} option will yield real-time cubic Bessel interpolation.  @w{As
in} the one-dimensional case, if the @samp{-f} option is used then the
@samp{-t} option must be used @w{as well}, to specify an interpolation
interval (@w{a range} of @w{@math{t} values}).  The @code{-p} option
will yield a periodic spline, i.e., the graph of a periodic
vector-valued function.  For this, the first and last dataset
@w{@math{y} values} must be the same.

@code{spline} can also be used to draw a curve through arbitrarily
chosen points in the plane, or @w{in general} through arbitrarily chosen
points in @math{d}-dimensional space.  This is not the same as splining,
@w{at least} as the term is conventionally defined.  The reason is that
`splining' refers to construction of a function, rather than the
construction of a curve that may or may not be the graph of a function.
Not every curve is the graph of a function.

The following example shows how you may `spline a curve'.  The command

@example
echo 0 0 1 0 1 1 0 1 | spline -d 2 -a -s | graph -T X
@end example

@noindent
will construct a curve in the plane through the four points (0,0),
(1,0), (1,1), and (0,1), and graph it on an @w{X Window} System display.
The @samp{-d 2} option specifies that the dependent variable @math{y} is
two-dimensional.  The @samp{-a} option specifies that @w{@math{t}
values} are missing from the input, and should be automatically
generated.  @w{By default}, the first @w{@math{t} value} @w{is 0}, the
second @w{is 1}, etc.  The @samp{-s} option specifies that the
@w{@math{t} values} should be stripped from the output.

The same technique may be used to spline a closed curve.  For example,
doing

@example
echo 0 0 1 0 0 1 0 0 | spline -d 2 -a -s -p | graph -T X
@end example

@noindent
will construct and graph a closed, lozenge-shaped curve through the
three points (0,0), (1,0), and (0,1).  The construction of a closed
curve is guaranteed by the @samp{-p} (i.e., @samp{--periodic}) option,
and by the repetition of the initial point (0,0) at the end of the
sequence.

When splining a curve, whether open or closed, you may wish to
substitute the @samp{-A} option for the @samp{-a} option.  Like the
@samp{-a} option, the @samp{-A} option specifies that @w{@math{t}
values} are missing from the input and should be automatically
generated.  However, the increment from one @w{@math{t} value} to the
next will be the distance between the corresponding values @w{of
@math{y}}.  This scheme for generating @w{@math{t} values}, when
constructing a curve through a sequence of points, is the scheme that is
used in the @w{well known} FITPACK subroutine library.  @w{It is}
probably the best approach when the distances between successive points
fluctuate considerably.

A curve through a sequence of points in the plane, whether open or
closed, may cross itself.  Some interesting visual effects can be
obtained by adding negative tension to such a curve.  For example, doing

@example
echo 0 0 1 0 1 1 0 0 | spline -d 2 -a -s -p -T -14 -n 500 | graph -T X
@end example

@noindent
will construct a closed curve through the three points (0,0), (1,0), 
and (0,1), which is wound into curlicues.  The @samp{-n 500} option is
included because there are so many windings.  @w{It specifies} that 501
points should be generated, which is enough to draw a smooth curve.

@noindent
@node spline Invocation, , Advanced Use of spline, spline
@section @code{spline} command-line options

The @code{spline} program will interpolate vector-valued functions of a
scalar @w{variable @math{t}}, and curves in @math{d}-dimensional space.
The algorithms used by @code{spline} are similar to those discussed in
@w{D. Kincaid} and @w{[E.] 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}.

Input file names may be specified anywhere on the command line.  That
is, the relative order of font names and command-line options does not
matter.  If no file names are specified, or the file @w{name @samp{-}}
is specified, the standard input is read.

An input file may contain more than a single dataset.  Unless the
@samp{-a} or @samp{-A} options are used (see below), each dataset is
expected to consist of a sequence of data points, given as alternating
@math{t} @w{and @math{y}} values.  @w{@math{t} is} the scalar
independent variable, and @w{@math{y} is} the vector-valued dependent
variable.  The dimensionality @w{of @math{y}} is specified with the
@samp{-d} option (the default @w{is @math{1}}).

If the input file is in ASCII format (the default), its datasets are
separated by blank lines.  An input file may also contain any number of
comment lines, which must begin with the comment @w{character `#'}.
Comment lines are ignored.  They are not treated as blank, i.e., they do
not interrupt a dataset in progress.

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 on each dataset.
@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.

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} can 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 quadratic function through that point and the two adjacent points in
the dataset.  If @samp{-f} is specified then the @samp{-t} 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}}.  In each of its components, 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 values of a specified component of the vector-valued dependent
variable @math{y} at the first two points of a dataset, and
@math{y[n-1]} and @math{y[n]} the 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}
(Positive integer, default 100.)  Subdivide the interval 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
@ifnottex
@math{y''''=sgn(tension)*(tension^2)y''}
@end ifnottex
@tex
$y''''={\rm sgn}({\sl tension}){\sl tension}^2\thinspace y''$
@end tex
in each of its components.  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 -t @var{tmin} @var{tmax} [@var{tspacing}]
@itemx --t-limits @var{tmin} @var{tmax} [@var{tspacing}]
For each dataset, set the interval over which interpolation occurs to be
the interval between @var{tmin} @w{and @var{tmax}}.  If @var{tspacing}
is not specified, the interval will be divided into the number of
subintervals specified by the @samp{-n} option.  @w{If the} @samp{-t}
option is not used, the interval over which interpolation occurs will be
the entire range of the independent variable in the dataset.  The
@samp{-t} option must always 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 -d @var{dimension}
@itemx --y-dimension @var{dimension}
(Integer, default 1.)  Set the dimensionality of the dependent variable
@math{y} in the input and output files to be @var{dimension}. 

@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 is a sequence of floating point numbers,
interpreted as the @math{t} @w{and @math{y}} coordinates of the
successive data points in a dataset.  If @math{y} is
@math{d}-dimensional, there will be @math{d+1} numbers for each point.
The @math{t} @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.

@item f
@ifnottex
Single precision binary format.  Each file is a sequence of floating
point numbers, interpreted as the @math{t} @w{and @math{y}} coordinates
of the successive data points in a dataset.  If @math{y} is
@math{d}-dimensional, there will be @math{d+1} numbers for each point.
Successive datasets are separated by a single occurrence of the quantity
@code{FLT_MAX}, which is the largest possible single precision floating
point number.  @w{On most} machines this is approximately 3.4x10^38.
@end ifnottex
@tex
Single precision binary format.  Each file is a sequence of floating
point numbers, interpreted as the @math{t} @w{and @math{y}} coordinates
of the successive data points in a dataset.  If @math{y} is
@math{d}-dimensional, there will be @math{d+1} numbers for each point.
Successive datasets are separated by a single occurrence of the quantity
@code{FLT_MAX}, which is the largest possible single precision floating
point number.  @w{On most} machines this is approximately
$3.4\times10^{38}$.
@end tex

@item d
@ifnottex
Double precision binary format.  Each file is a sequence of double
precision floating point numbers, interpreted as the @math{t} @w{and
@math{y}} coordinates of the successive data points in a dataset.  If
@math{y} is @math{d}-dimensional, there will be @math{d+1} numbers for
each point.  Successive datasets are separated by a single occurrence of
the quantity @code{DBL_MAX}, which is the largest possible double
precision floating point number.  @w{On most} machines this is
approximately 1.8x10^308.
@end ifnottex
@tex
Double precision binary format.  Each file is a sequence of double
precision floating point numbers, interpreted as the @math{t} @w{and
@math{y}} coordinates of the successive data points in a dataset.  If
@math{y} is @math{d}-dimensional, there will be @math{d+1} numbers for
each point.  Successive datasets are separated by a single occurrence of
the quantity @code{DBL_MAX}, which is the largest possible double
precision floating point number.  @w{On most} machines this is
approximately $1.8\times10^{308}$.
@end tex

@item i
@ifnottex
Integer binary format.  Each file is a sequence of integers, interpreted
as the @math{t} @w{and @math{y}} coordinates of the successive data
points in a dataset.  If @math{y} is @math{d}-dimensional, there will be
@math{d+1} numbers for each point.  Successive datasets are separated by
a single occurrence of the quantity @code{INT_MAX}, which is the largest
possible integer.  @w{On most} machines this is 2^31-1.
@end ifnottex
@tex
Integer binary format.  Each file is a sequence of integers, interpreted
as the @math{t} @w{and @math{y}} coordinates of the successive data
points in a dataset.  If @math{y} is @math{d}-dimensional, there will be
@math{d+1} numbers for each point.  Successive datasets are separated by
a single occurrence of the quantity @code{INT_MAX}, which is the largest
possible integer.  @w{On most} machines this is $2^{31}-1$.
@end tex
@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 values for the
independent @w{variable (@math{t})}.  Irrespective of data format
(@samp{a}, @samp{f}, @samp{d}, @w{or @samp{i}}), this option specifies
that the values of the independent variable (@math{t}) are missing from
the input file: the dataset(s) to be read contain only values of the
dependent @w{variable (@math{y})}, @w{so that} if @math{y} is
@math{d}-dimensional, there will be only @w{@math{d} numbers} for each
point.  The increment from each @w{@math{t} value} to the next will be
@var{step_size}, and the first @w{@math{t} value} will be
@var{lower_limit}.

@item -A 
@itemx --auto-dist-abscissa
Automatically generate values for the independent @w{variable
(@math{t})}.  This is a variant form of the @samp{-a} option.  The
increment from each @w{@math{t} value} to the next will be the distance
between the corresponding @w{@math{y}} values, and the first @w{@math{t}
value} will be 0.0.  This option is useful when interpolating curves
rather than functions (@pxref{Advanced Use of spline}).

@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}
(Positive integer, default 6.)  Set the numerical precision for the
@math{t} and @math{y} values 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@.

@item -s
@itemx --suppress-abscissa
Omit the independent variable @math{t} from the output file; for each
point, supply only the dependent @w{variable @math{y}}.  If @math{y} is
@math{d}-dimensional, there will be only @w{@math{d} numbers} for each
point, @w{not @math{d+1}}.  This option is useful when interpolating
curves rather than functions (@pxref{Advanced Use of spline}).
@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 number of @code{spline} and the plotting utilities
package, and exit.
@end table

@node ode, libplot, spline, Top
@chapter The @code{ode} Program

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} can 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} can easily be piped to @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 @w{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:

@ifnottex
@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 ifnottex
@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
@ifnottex
@noindent
where @math{a,b,c,...,d} are constants.
@end ifnottex

@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), @w{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
@ifnottex
For @code{ode} to be able to solve such a problem numerically, the
functions f,g,@dots{},h must be expressed, using the usual operators
(@w{@math{+}, @math{-}}, @math{*}, @math{/}, @w{and ^}), @w{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{},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 ifnottex

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 can 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, which is distributed
along with the GNU plotting utilities.  @w{On most} systems it is
installed as @file{/usr/share/ode} or @file{/usr/local/share/ode}.

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 

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

@noindent
In particular

@ifnottex
@example
@math{y(1) = e^1 = 2.718282}
@end example
@end ifnottex
@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 may 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.  @w{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

@ifnottex
@example
@math{y(t) = sin(t)}
@end example
@end ifnottex
@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 -T 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 @w{-T 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 @w{-T X}} would wait until all points are read from the 
input before determining the bounds, and drawing the plot.

A slight modification of this example, showing how @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 -T 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 @w{-T X}} will treat each section of the sine curve as a
different dataset.  If you are using a color display, each of the three
sections will be plotted in a different color.  This is a feature
provided by @code{graph}, which normally changes its linemode after each
dataset it reads.  If you do not like this feature, you may turn it off
by using @code{graph -T X -B} instead of @code{graph @w{-T X}}.

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

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

@noindent
You should note that of the variants of @code{graph}, the seven variants
@code{graph -T pnm}, @code{graph -T gif}, @code{graph -T ai},
@code{graph -T ps}, @code{graph -T fig}, @code{graph -T pcl} and
@code{graph -T hpgl} do not produce output in real time, even when the
axis bounds are specified with the @samp{-x} @w{and @samp{-y}} options.
@w{So if} any of these seven variants 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 may also 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, e.g., @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.  @w{If
there} is more than than one such variable then no stepping takes place;
instead, an error message is printed.  @w{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
ode < lorenz | graph -T 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
ode < lorenz | graph -T ps -x -10 10 -y -10 10 -W 0 | lpr
@end example

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

Besides plotting a visually striking object in real time, the Lorenz
attractor example shows how statements may be separated by semicolons,
rather than appearing on different lines.  @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
@ae{}sthetic 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 -T X -C -x 0 5 -y 0 5
x' = (a - b*y) * x
y' = (c*x - d) * y
a = 1; b = 1; c = 1; d = 1;
print x, y
@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} changes the linemode between
datasets.  That feature may be @w{turned off} by using @code{graph -T X
-B} rather than @code{graph @w{-T 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
ode < atwoods | graph -T 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{significant-digits}
@itemx --precision @var{significant-digits}
(Positive integer, default 6.)  When printing numerical results, use a
precision specified by @var{significant-digits}.  @w{If this} option is
given, the print format will be scientific notation.

@item -t
@itemx --title
Print a title line at the head of the output, naming the columns.  @w{If
this} option is given, the 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} @w{is 0.1}.  Not recommended for serious
applications.

The error bound options @samp{-r} and @samp{-e} (see below) may not
be used if @samp{-E} is specified.

@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}]
@ifnottex
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.  @w{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 ifnottex
@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.  @w{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 number 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

@ifnottex
@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 ifnottex
@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 losses 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.  @w{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 the user may set 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 (e.g., 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.

@ifnottex
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.  @w{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 ifnottex
@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.  @w{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, @w{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:

@ifnottex
@example
@group
@math{y' = y^2}
@math{y(1) = -1}
@end group
@end example
@end ifnottex
@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?

As another example of ill-posedness, consider the system

@example
@math{y'=1/y}
@end example

which is undefined at @math{y=0}.  The general solution is

@ifnottex
@example
@math{y = +/- (2(t-C))^(1/2)},
@end example
@end ifnottex
@tex
@example
$y = \pm (2(t-C))^{1/2}$,
@end example
@end tex

@ifnottex
so that if the condition @math{y(2)=2} is imposed, the solution will be
@math{(2t)^(1/2)}.  Clearly, if the domain specified in a @samp{step}
statement includes negative values @w{of @math{t}}, the generated
solution will be bogus.
@end ifnottex
@tex
so that if the condition @math{y(2)=2} is imposed, the solution will be
$(2t)^{1/2}$.  Clearly, if the domain specified in a @samp{step}
statement includes negative values @w{of @math{t}}, the generated
solution will be bogus.
@end tex

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.  @w{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:

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

@noindent
on the domain @math{[0,1]}.  The exact solution is

@ifnottex
@example 
@math{y(t) = e^(-100t) + t}.
@end example
@end ifnottex
@tex
@example 
$y(t) = e^{-100t} + t$.
@end example
@end tex

@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 may 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 -T 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.  @w{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.
@w{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, @w{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 specification of the grammar for @code{ode}'s
input language, in Backus--Naur form.  Nonterminal symbols in the
grammar are enclosed in angle brackets.  Terminal tokens are in all
capitals.  Bare words and symbols stand for themselves.

@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, @w{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.  @w{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.  @w{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 items 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.  @w{Chapter 6} contains a discussion of the literature on the
numerical solution of ordinary differential equations.

@item
G. Birkhoff and G. Rota, @cite{Ordinary Differential Equations}, 4th
ed., Wiley, 1989.

@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.
@end itemize

@node libplot, Appendices, ode, Top
@chapter @code{libplot}, a Function Library

@menu
* libplot Overview::    Programming with libplot: An overview
* C Programming::       C programming with libplot
* C++ Programming::     C++ programming with libplotter
* Functions::           A list of functions contained in libplot
* Driver Parameters::   Device driver parameters
@end menu

@node libplot Overview, C Programming, libplot, libplot
@section Programming with @code{libplot}: An overview

GNU @code{libplot} is a free function library for drawing
two-dimensional vector graphics.  It can produce smooth, double-buffered
animations for the @w{X Window} System, and can export files in many
graphics file formats.  @w{It is} `device-independent' in the sense that
its API (application programming interface) is to a large extent
independent of the display type or output format.

There are bindings for C, C++, and other languages.  The @w{C binding},
which is the most frequently used, is also called @code{libplot}, and
the C++ binding, when it needs to be distinguished, is called
@code{libplotter}.  @w{In this} section we use @code{libplot} to refer
to the library itself, irrespective of binding.

The graphical objects that @code{libplot} can draw include paths,
circles and ellipses, points, markers, and `adjusted labels' (justified
text strings).  @w{A @emph{path}} is a sequence of line segments,
circular arcs, elliptic arcs, quadratic Bezier curves, and/or cubic
Bezier curves.  Paths may be open or closed.  User-specified filling of
paths, circles, and ellipses is supported (fill rule and fill color,
@w{as well} as pen color, may be specified).  There is support for
maintaining a Postscript-style stack of graphics contexts, i.e., @w{a
stack} of drawing attribute sets.  Path-related attributes include line
thickness, line type, cap type, and join type, and text-related
attributes include font name, font size, and text angle.

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

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

The following are the currently supported types of Plotter.

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

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

@item
PNM Plotters.  A PNM Plotter produces a single page of output in
``portable anymap'' format, and directs it to a file or other specified
output stream.  There are three types of portable anymap: PBM (portable
bitmap, for monochrome graphics), PGM (portable graymap), and PPM
(portable pixmap, for colored graphics).  The output file will be in
whichever of these three formats is most appropriate.  The file may be
viewed or edited with many applications, such as the free image display
application @code{xv}.

@item
GIF Plotters.  A GIF Plotter produces a single page of output in a
pseudo-GIF format.  Unlike true GIF format, the pseudo-GIF format does
not use LZW compression: @w{it uses} run-length encoding instead.  @w{So
it} does not transgress the Unisys patent that restricts the use of LZW
compression.  However, the output file may be viewed or edited with any
application that understands GIF format, such as @code{xv}.  The
creation of animated pseudo-GIFs is supported.

@item
Illustrator Plotters.  An Illustrator Plotter produces a single page of
output in the format used by Adobe Illustrator, and directs it to a file
or other specified output stream.  The file may be edited with Adobe
Illustrator (@w{version 5}, and more recent versions), or other
applications.

@item 
Postscript Plotters.  A Postscript Plotter produces Postscript output
and directs it to a file or other specified output stream.  If only a
single page of graphics is drawn on the Plotter then its output is in
EPS (encapsulated Postscript) format, so it may be included in another
document.  It may also be edited with the @code{idraw} drawing editor.

@item 
Fig Plotters.  A Fig Plotter produces a single page of output in Fig
format and directs it to a file or other specified output stream.  The
output 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 
PCL Plotters.  A PCL Plotter produces output in @w{PCL 5} format and
directs it to a file or other specified output stream.  @w{PCL 5} is a
powerful version of Hewlett--Packard's Printer Control Language, which
supports vector graphics.  The output may be sent to a @w{PCL 5} device
such as a LaserJet printer or high-end inkjet.

@item
HP-GL Plotters.  An HP-GL Plotter produces output in the
Hewlett--Packard Graphics Language (@w{by default}, in HP-GL/2), and
directs it to a file or other specified output stream.  The output may
be imported into another application, or sent to a plotter.

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

@item
Metafile Plotters.  A Metafile Plotter produces output in GNU graphics
metafile format and directs it to a file or other specified output
stream.  This format is an extended version of the `plot(5)' format
found on some other operating systems.  (@xref{Metafiles}.)  @w{It may}
be translated to other formats by an invocation of GNU @code{plot}.
(@xref{plot}.)
@end itemize

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

Another distinction is that the first four types of Plotter (X, @w{X
Drawable}, PNM, and GIF) produce bitmap output, while the remaining
types produce output in a vector graphics format.  In bitmap output the
structure of the graphical objects is lost, but in a vector format it is
retained.

An additional distinction is that X, X Drawable, Tektronix and Metafile
Plotters are real-time.  This means that they draw graphics or write to
an output stream as the drawing operations are invoked on them.  The
remaining types of Plotter are not real-time, since their output streams
can only be emitted after all functions have been called.  For PNM and
GIF Plotters, this is because the bitmap must be constructed before it
is written out.  For Illustrator and Postscript Plotters, @w{it is}
because a `bounding box' line must be placed at the head of the output
file.  For a Fig Plotter, @w{it is} because color definitions must be
placed at the head of the output file.

The most important operations supported by any Plotter are @code{openpl}
and @code{closepl}, which open and @w{close it}.  Graphics may be drawn,
and drawing attributes set, only within an
@code{openpl}@dots{}@code{closepl} pair.  The graphics produced within
each @code{openpl}@dots{}@code{closepl} pair constitute a `page'.  In
principle, any Plotter may be opened and closed arbitrarily many times.
An @w{X Plotter} displays each page in a separate @w{X window}, and
Postscript, PCL, and HP-GL Plotters render each page as a separate
physical page.  @w{X Drawable} Plotters and Tektronix Plotters
manipulate a single drawable or display, on which pages are displayed in
succession.  Plotters that do not draw in real time (PNM, GIF,
Illustrator, Postscript, Fig, PCL, and HP-GL Plotters) may wait until
their existence comes to an end (i.e., until they are deleted) before
outputting their pages of graphics.

In the current release of @code{libplot}, Postscript Plotters delay
outputting graphics in this way, but PCL and HP-GL Plotters output each
page of graphics individually, i.e., when @code{closepl} is invoked.
PNM, GIF, Illustrator and Fig Plotters are similar, but output only the
first page.  That is because PNM, GIF, Illustrator and Fig formats
support only a single page of graphics.

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

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

Each Plotter maintains a Postscript-style stack of graphics contexts.
This makes possible the rapid, efficient drawing of complicated pages of
graphics.  @w{A graphics} context includes the current affine
transformation from the user coordinate system to the device coordinate
system.  @w{It also} includes such modal drawing attributes as graphics
cursor position, linemode, line thickness, pen and fill colors, and the
font used for drawing text.  The state of any uncompleted path @w{(if
any)} is included @w{as well}, since paths may be drawn incrementally,
one portion (line segment or arc) at a time.  The current graphics
context is pushed onto the stack by calling @code{savestate}, and popped
off by calling @code{restorestate}.

To permit vector graphics animation, any page of graphics may be split
into `frames'.  @w{A frame} is ended, and a new frame is begun, by
invoking the @code{erase} operation.  @w{On a} Plotter that does
real-time plotting (i.e., @w{an X}, @w{X Drawable}, Tektronix, or
Metafile Plotter), this erases all plotted objects from the graphics
display, allowing a new frame to be drawn.  Displaying a sequence of
frames in succession creates the illusion of smooth animation.

@w{On most} Plotters that do not do real-time plotting (i.e., PNM,
Illustrator, Postscript, Fig, PCL, or HP-GL Plotters), invoking
@code{erase} deletes all plotted objects from an internal buffer.  For
this reason, most Plotters that do not do real-time plotting will
display only the final frame of any multiframe page.

GIF Plotters are in a class by themselves.  Even though they do not do
real time plotting, @w{a GIF} Plotter can produce multi-image output,
i.e., an animated pseudo-GIF file, from a multiframe page.  @w{As noted}
above, the pseudo-GIF file produced by a GIF Plotter will contain only
the first page of graphics.  But if this page consists of multiple
frames, then each invocation of @code{erase}, after the first, will be
treated @w{by default} as a separator between successive images.

@node C Programming, C++ Programming, libplot Overview, libplot
@section C Programming with @code{libplot}

@menu
* The C API::                   The C application programming interface
* C Compiling and Linking::     C compiling and linking
* Sample C Drawings::           Sample drawings in C
* Animated GIFs::               Animated GIFs in C
* X Animations::                X Window System animations in C
* X Programming::		Advanced X Window System programming
@end menu

@node The C API, C Compiling and Linking, C Programming, C Programming
@subsection The C application programming interface

@code{libplot} has bindings for several programming languages.
Regardless of which language binding is used, the concepts behind
@code{libplot} (Plotters, and a fixed set of operations that can be
applied to any Plotter) remain the same.  However, the ways in which
Plotters are manipulated (created, selected @w{for use}, and deleted)
may differ between bindings.  This section discusses the @w{C binding}.

If you are writing an application in C that will use @code{libplot} to
draw vector graphics, the first thing you need to know is how, in the
@w{C binding}, Plotters are manipulated.  There are four special
functions for this, which you can invoke: @code{newpl}, @code{selectpl},
@code{deletepl}, and the parameter-setting function @code{parampl}.
Actually, you would usually invoke them under the names @code{pl_newpl},
@code{pl_selectpl}, @code{pl_deletepl}, and @code{pl_parampl}.  That is
because in the C binding, the names of all functions begin with "pl_"
unless the header file @code{plotcompat.h} is included.  @xref{C
Compiling and Linking}.

The @code{pl_newpl} function will create a Plotter of specified type.
Its first argument may be "X", "Xdrawable", "pnm", "gif", "ai", "ps",
"fig", "pcl", "hpgl", "tek", or "meta".  It returns a nonnegative
integer (@w{a ``handle''}) that may be used to refer to the Plotter.
Before using a Plotter that you have created (i.e., before invoking any
of the @code{libplot} operations @w{on it}), you must select the Plotter
@w{for use} by calling @code{pl_selectpl}.  Only one Plotter may be
selected at a time, but by calling @code{pl_selectpl} you may switch
from Plotter to Plotter at any time, even when the selected Plotter is
open.  @w{A Plotter} that is not currently selected can be deleted, and
its storage freed, by calling @code{pl_deletepl}.

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

You should get into the habit of calling @code{pl_deletepl} whenever you
are finished using a Plotter.  In general, Plotters that do not plot
graphics in real time (Postscript Plotters in particular) @w{write out}
graphics only when the plot is finished, and @code{pl_deletepl} is
called.

The following table summarizes the action of the four functions in the
@w{C binding} that are used for Plotter manipulation.

@table @asis
@item int @t{pl_newpl} (const char *@var{type}, FILE *@var{infile}, FILE *@var{outfile}, FILE *@var{errfile});
@t{pl_newpl} creates a Plotter of type @var{type}, where @var{type} may be
"X", "Xdrawable", "pnm", "gif", "ai", "ps", "fig", "pcl", "hpgl", "tek",
or "meta".  The Plotter will have input stream @var{infile}, output
stream @var{outfile}, and error stream @var{errfile}.  Any or all of
these three may be NULL@.  Currently, all Plotters are write-only, so
@var{infile} is ignored.  @w{X Plotters} and @w{X Drawable} Plotters
write graphics to an @w{X Window} System display rather than to an
output stream, so if @var{type} is "X" or "Xdrawable" then @var{outfile}
is ignored @w{as well}.  Error messages (@w{if any}) are written to the
stream @var{errfile}, unless @var{errfile} is NULL@.  The return value
from @t{newpl} is a `handle': @w{a nonnegative} integer by which the
newly created Plotter is @w{referred to}.  @w{A negative} return value
indicates the Plotter could not be created.

@item int @t{pl_selectpl} (int @var{handle});
@t{pl_selectpl} selects a Plotter, referred to by its handle, for use.
If any of the basic @code{libplot} operations is subsequently invoked,
it will be applied to the selected Plotter.  Only one Plotter may be
selected at a time.  At startup, a single Metafile Plotter that writes
to standard output (with @w{handle `0'}) is automatically created and
selected.

The handle of the previously selected Plotter is returned.  A negative
return value indicates the specified Plotter does not exist or could not
be selected.

@item int @t{pl_deletepl} (int @var{handle});
@t{pl_deletepl} deletes a Plotter, referred to by its handle.  The
Plotter must not be selected at the time it is deleted.  @w{A negative}
return value indicates the Plotter could not be deleted.

@item int @t{pl_parampl} (const char *@var{parameter}, void *@var{value});
@t{pl_parampl} sets the value of the device driver parameter
@var{parameter} to @var{value}.  Device driver parameters specify
Plotter options.  The parameter values in effect at the time any Plotter
is created are copied @w{into it}.  For most parameters, @var{value}
should be a @code{char *}, i.e., a string.  Unrecognized parameters are
ignored.  For a list of the recognized parameters and their meaning, see
@ref{Driver Parameters}.
@end table

Up to now we have not discussed the fourth function, @code{pl_parampl}.
Even though the Plotter interface is largely Plotter-independent, @w{it
is} useful to be able to specify certain aspects of a Plotter's behavior
at the time it is created.  Plotter behavior is captured by a manageable
number of parameters, which we call @emph{device driver parameters}.
@w{A value} for any parameter can be specified by calling
@code{pl_parampl}.  This function does not operate on any particular
Plotter: @w{it belongs} to the @w{C binding} as a whole.  The parameter
values used by any Plotter are constant over the lifetime of the
Plotter, and are those that were in effect when the Plotter was created.

Actually, a slightly more sophisticated rule applies.  If at Plotter
creation time a parameter is set, the value specified by the most recent
call to @code{pl_parampl} will be the value used by the Plotter.  If at
Plotter creation time a parameter is @emph{not} set, its default value
will be used, unless the parameter is string-valued and there is an
environment variable of the same name, in which case the value of that
environment variable will be used.  This rule increases run-time
flexibility: @w{an application} programmer may allow non-critical driver
parameters to be specified by the user via environment variables.  Once
set, @w{a parameter} may be unset by the programmer by calling
@code{pl_parampl} with a value argument of NULL@.  This further increases
flexibility.

@node C Compiling and Linking, Sample C Drawings, The C API, C Programming
@subsection C compiling and linking

The source code for a graphics application written in C, if it is to use
@code{libplot}, must 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.

In current releases of @code{libplot}, the names of all functions begin
with the prefix "pl_".  For example, the @code{openpl} operation is
invoked on a Plotter by calling the function @code{pl_openpl}.  If you
wish, you may maintain backward compatibility by also including the
header file @code{plotcompat.h}.  This header file redefines
@code{openpl} as @code{pl_openpl}, and similarly for the other
@code{libplot} functions.

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

@example
-lplot -lXaw -lXmu -lXt -lXext -lX11 -lm
@end example

@noindent
or, in recent releases of the @w{X Window} System,

@example
-lplot -lXaw -lXmu -lXt -lSM -lICE -lXext -lX11 -lm
@end example

@noindent
(Alternatively, you may need to use @samp{-lplot -lXm -lXt -lXext -lX11
-lm}, @samp{-lplot -lXm -lXt -lXext -lX11 -lm -lc -lgen}, or
@samp{-lplot -lXm -lXt -lXext -lX11 -lm -lc -lPW}, on systems that
provide Motif widgets instead of Athena widgets.  In recent releases of
the @w{X Window} System, you would insert @samp{-lSM -lICE}@.  Recent
releases of Motif require @samp{-lXp} @w{as well}.)

On some platforms, the directories in which @code{libplot} or the other
libraries are stored must be specified on the command line.  @w{For
example}, the options @samp{-lXaw -lXmu -lXt -lSM -lICE -lXext -lX11},
which specify @w{X Window} System libraries, may need to be preceded by
an option like @samp{-L/usr/X11/lib}.

On most systems @code{libplot} is installed as a DLL (dynamically linked
library, or `shared' library).  This means that the linking with your
application will take place at run time rather than compile time.  The
environment variable @code{LD_LIBRARY_PATH} lists the directories which
will be searched for DLL's at run time.  For your application to be
executable, this environment variable should include the directory in
which @code{libplot} is stored.

@node Sample C Drawings, Animated GIFs, C Compiling and Linking, C Programming
@subsection Sample drawings in C

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

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

@group
void draw_c_curve (double dx, double dy, int order)
@{
  if (order >= MAXORDER)
    pl_fcontrel (dx, dy);     /* continue path along (dx, dy) */
@end group
@group
  else
    @{
      draw_c_curve (0.5 * (dx - dy), 0.5 * (dx + dy), order + 1);
      draw_c_curve (0.5 * (dx + dy), 0.5 * (dy - dx), order + 1);      
    @}
@}
@end group

@group
int main ()
@{
  int handle;        

  /* set a Plotter parameter */
  pl_parampl ("PAGESIZE", "letter");  
@end group

@group
  /* create a Postscript Plotter that writes to standard output */
  if ((handle = pl_newpl ("ps", stdin, stdout, stderr)) < 0)
    @{
      fprintf (stderr, "Couldn't create Plotter\n");
      return 1;
    @}
  pl_selectpl (handle);       /* select the Plotter for use */
@end group

@group
  if (pl_openpl () < 0)       /* open Plotter */
    @{
      fprintf (stderr, "Couldn't open Plotter\n");
      return 1;
    @}
@end group
@group
  pl_fspace (0.0, 0.0, 1000.0, 1000.0); /* specify user coor system */
  pl_flinewidth (0.25);       /* line thickness in user coordinates */
  pl_pencolorname ("red");    /* path will be drawn in red */
@end group
@group
  pl_erase ();                /* erase Plotter's graphics display */
  pl_fmove (600.0, 300.0);    /* position the graphics cursor */
  draw_c_curve (0.0, 400.0, 0);
@end group
@group
  if (pl_closepl () < 0)      /* close Plotter */
    @{
      fprintf (stderr, "Couldn't close Plotter\n");
      return 1;
    @}
@end group

@group
  pl_selectpl (0);            /* select default Plotter */
  if (pl_deletepl (handle) < 0) /* delete Plotter we used */
    @{
      fprintf (stderr, "Couldn't delete Plotter\n");
      return 1;
    @}
  return 0;
@}
@end group
@end example

As you can see, this application begins by calling the @code{pl_newpl}
function to create a Postscript Plotter.  The Postscript Plotter will
produce output for a US letter-sized page, though any other standard
page size, e.g., "a4", could be substituted.  This would be arranged by
altering the call to @code{pl_parampl}.  The @code{PAGESIZE} parameter
is one of several Plotter parameters that an application programmer may
set by calling @code{pl_parampl}.  For a complete list, see @ref{Driver
Parameters}.

After the Plotter is created, the application selects it for use,
@w{opens it}, and draws the @w{``C'' curve} recursively.  The drawing of
the curve is accomplished by calling the @code{pl_fmove} function to
position the Plotter's graphics cursor, and then calling
@code{draw_c_curve}.  This subroutine repeatedly calls
@code{pl_fcontrel}.  The @code{pl_fcontrel} function continues a path by
adding a line segment @w{to it}.  The endpoint of each line segment is
specified in relative coordinates, i.e., as an offset from the previous
cursor position.  After the @w{``C'' curve} is drawn, the Plotter is
closed.  @w{A Postscript} file is written to standard output when
@code{pl_deletepl} is called to delete the Plotter.

Specifying "pnm", "gif", "ai", "fig", "pcl", "hpgl", "tek", or "meta" as
the first argument in the call to @code{pl_newpl}, instead of "ps",
would yield a Plotter that would write graphics to standard output in
the specified format, instead of Postscript.  The @code{PAGESIZE}
parameter is relevant to the "ai", "fig", "pcl", and "hpgl" output
formats, but is ignored for the others.  Specifying "meta" as the
Plotter type may be useful if you wish to avoid recompilation for
different output devices.  Graphics metafile output may be piped to the
@code{plot} utility and converted to any other supported output format,
or displayed in an @w{X window}.  @xref{plot}.

@w{If "X"} were specified as the first argument of @code{pl_newpl}, the
curve would be drawn in a popped-up @w{X window}, and the output stream
argument would be ignored.  Which @w{X Window} System display the window
would @w{pop up} on would be determined by the @code{DISPLAY} parameter,
or if that parameter were not set, by the @code{DISPLAY} environment
variable.  The size of the @w{X window} would be determined by the
@code{BITMAPSIZE} parameter, or if that parameter were not set, by the
@code{BITMAPSIZE} environment variable.  The default value is "570x570".
For the "pnm" and "gif" Plotter types, the interpretation of
@code{BITMAPSIZE} is similar.

You could also specify "Xdrawable" as the Plotter type.  For you to make
this work, you would need to know a bit about @w{X Window} System
programming.  You would need to create @w{at least} one @w{X drawable}
(i.e., window or a pixmap), and by invoking the @code{pl_parampl}
function before @code{newpl} is called, set it as the value of the
parameter @code{XDRAWABLE_DRAWABLE1} or @code{XDRAWABLE_DRAWABLE2}.  For
the parameters that affect @w{X Drawable} Plotters, see @ref{Driver
Parameters}.

The following is another sample application, written in C, that invokes
@code{libplot} operations to draw vector graphics.  @w{It draws} a
spiral consisting of elliptically boxed text strings, each of which
reads "GNU libplot!".  This figure will be sent to standard output in
Postscript format.

@example
@group
#include <stdio.h>
#include <plot.h>
#include <math.h>
#define SIZE 100.0   /* nominal size of user coordinate frame */
#define EXPAND 2.2   /* expansion factor for elliptical box */
@end group

@group
void draw_boxed_string (char *s, double size, double angle)
@{
  double true_size, width;

  pl_ftextangle (angle);         /* text inclination angle (degrees) */
  true_size = pl_ffontsize (size);  /* choose font size */
  width = pl_flabelwidth (s);    /* compute width of text string */
  pl_fellipserel (0.0, 0.0,      /* draw surrounding ellipse */
               EXPAND * 0.5 * width, EXPAND * 0.5 * true_size, angle);
  pl_alabel ('c', 'c', s);       /* draw centered text string */
@}
@end group

@group
int main()
@{
  int handle, i;

  /* set a Plotter parameter */
  pl_parampl ("PAGESIZE", "letter");
@end group

@group
  /* create a Postscript Plotter that writes to standard output */
  if ((handle = pl_newpl ("ps", stdin, stdout, stderr)) < 0)
    @{
      fprintf (stderr, "Couldn't create Plotter\n");
      return 1;
    @}
  pl_selectpl (handle);         /* select the Plotter for use */
@end group

@group
  if (pl_openpl () < 0)         /* open Plotter */
    @{
      fprintf (stderr, "Couldn't open Plotter\n");
      return 1;
    @}
@end group
@group
  pl_fspace (-(SIZE), -(SIZE), SIZE, SIZE); /* spec. user coor system */
  pl_pencolorname ("blue");     /* pen color will be blue */
  pl_fillcolorname ("white");
  pl_filltype (1);              /* ellipses will be filled with white */
  pl_fontname ("NewCenturySchlbk-Roman"); /* choose a Postscript font */
@end group
  
@group
  for (i = 80; i > 1; i--)      /* loop through angles */
    @{
      double theta, radius;
@end group
      
@group
      theta = 0.5 * (double)i;  /* theta is in radians */
      radius = SIZE / pow (theta, 0.35);  /* this yields a spiral */
      pl_fmove (radius * cos (theta), radius * sin (theta));
      draw_boxed_string ("GNU libplot!", 0.04 * radius,
                          (180.0 * theta / M_PI) - 90.0);
    @}
@end group

@group
  if (pl_closepl () < 0)        /* close Plotter */
    @{
      fprintf (stderr, "Couldn't close Plotter\n");
      return 1;
    @}
@end group
@group
  pl_selectpl (0);
  if (pl_deletepl (handle) < 0) /* delete Plotter we used */
    @{
      fprintf (stderr, "Couldn't delete Plotter\n");
      return 1;
    @}
  return 0;
@}
@end group
@end example

This example shows what is involved in plotting a text string or text
strings.  First, the desired font must be retrieved.  @w{A font} is
fully specified by calling @code{pl_fontname}, @code{pl_fontsize}, and
@code{pl_textangle}, or their floating point counterparts
@code{pl_ffontname}, @code{pl_ffontsize}, and @code{pl_ftextangle}.
Since these three functions may be called in any order, each of them
returns the size of the font that it selects, as a convenience to the
programmer.  This may differ slightly from the size specified in the
most recent call to @code{pl_fontsize} or @code{pl_ffontsize}, since
many Plotters have only a limited repertory of fonts.  The above example
plots each text string in the "NewCenturySchlbk-Roman" font, which is
available on Postscript Plotters.  @xref{Text Fonts}.

If you replace "ps" by "X" in the call to @code{pl_newpl}, an @w{X
Plotter} rather than a Postscript Plotter will be used, and the spiral
will be drawn in a popped-up @w{X window}.  If your @w{X display} does
not support the "NewCenturySchlbk-Roman" font, you may substitute any
other scalable font, such as the widely available
"utopia-medium-r-normal".  For the format of font names, see @ref{Text
Fonts in X}.  @w{If the} @w{X Plotter} is unable to retrieve the font
you specify, it will first attempt to use a default scalable font
("Helvetica"), and if that fails, use a default Hershey vector font
("HersheySerif") instead.  Hershey fonts are constructed from line
segments, so each built-in Hershey font is available on all types of
Plotter.

If you are using an older (pre-X11R6) @w{X Window} System display, you
will find that retrieving a scalable font is a time-consuming operation.
The above example may run slowly on some older @w{X displays}, since a
new font must be retrieved before each text string is drawn.  That is
because each text string has a different angle of inclination.  @w{It
is} possible to retrieve individual characters from an X11R6 display,
rather than retrieving an entire rasterized font.  @w{If this} feature
is available, the @w{X Plotter} will automatically take advantage @w{of
it} to save time.

@node Animated GIFs, X Animations, Sample C Drawings, C Programming
@subsection Animated GIFs in C

Using @code{libplot} to create pseudo-GIF files, including animated
pseudo-GIFs, is straightforward.  @w{A GIF} Plotter is a Plotter like
any other, and it supports the same drawing operations.  However, it has
two special properties.  @w{(1) It} can draw only a single page of
graphics, i.e., only the graphics contained in the first
@code{openpl}@dots{}@code{closepl} appear in the output file.  @w{In
this}, it resembles other Plotters that do not plot in real time.
@w{(2) Within} this page, each invocation of @code{erase} is normally
treated as the beginning of a new image in the output file.  There is an
exception to this: the first invocation of @code{erase} begins a new
image only if something has already been drawn.

The reason for the exception is that many programmers who use
@code{libplot} are in the habit of invoking @code{erase} immediately
after a Plotter is opened.  This is not a bad habit, since a few types
of Plotter (e.g., @w{X Drawable} and Tektronix Plotters) are
`persistent' in the sense that previously drawn graphics remain visible.

The following program creates a simple animated pseudo-GIF, 150 pixels
wide and 100 pixels high.

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

@group
int main()
@{
  int i, handle;
@end group

  /* set Plotter parameters */
  pl_parampl ("BITMAPSIZE", "150x100");
  pl_parampl ("BG_COLOR", "orange");
  pl_parampl ("TRANSPARENT_COLOR", "orange");
  pl_parampl ("GIF_ITERATIONS", "100");
  pl_parampl ("GIF_DELAY", "5");

  /* create a GIF Plotter with the specified parameters */
  handle = pl_newpl ("gif", stdin, stdout, stderr);
  pl_selectpl (handle);         /* select the Plotter for use */
     
  pl_openpl();			/* begin page of graphics */
  pl_space (0, 0, 149, 99);	/* specify user coordinate system */
  
  pl_pencolorname ("red");      /* objects will be drawn in red */
  pl_linewidth (5);             /* set the line thickness */
  pl_filltype (1);              /* objects will be filled */
  pl_fillcolorname ("black");   /* set the fill color */

@group
  for (i = 0; i < 180 ; i += 15)
    @{
      pl_erase ();              /* begin new GIF image */
      pl_ellipse (75, 50, 40, 20, i); /* draw an ellipse */
    @}
@end group

@group
  pl_closepl ();                /* end page of graphics */
  pl_selectpl (0);              /* select default Plotter */
  pl_deletepl (handle);         /* delete Plotter we used */
  return 0;
@}
@end group
@end example

The animated pseudo-GIF will be written to standard output.  @w{It will}
consist of twelve images, showing the counterclockwise rotation of a
black-filled red ellipse through 180 degrees.  The pseudo-GIF will be
`looped' (see below), so the ellipse will rotate repeatedly.

The parameters of the ellipse are expressed in terms of user
coordinates, not pixel coordinates.  But the call to @code{pl_space}
defines user and pixel coordinates to be effectively the same.  User
coordinates are chosen so that the lower left corner is (0,0) and the
upper right corner is (149,99).  Since this agrees with the image size,
individual pixels may be addressed in terms of integer user coordinates.
@w{For example}, @code{pl_point(149,99)} would set the pixel in the
upper right hand corner of the image to the current pen color.

Besides @code{BITMAPSIZE} and @code{BG_COLOR}, there are several
important GIF Plotter parameters that may be set with the
@code{pl_parampl} function.  The @code{TRANSPARENT_COLOR} parameter may
be set to the name of a color.  Pixels in a pseudo-GIF that have that
color will be treated as transparent by most software.  This is usually
used to create a transparent background.  @w{In the} example above, the
background color is specified as orange, but the transparent color is
also specified as orange.  @w{So the} background will not actually be
displayed.

The @code{GIF_ITERATIONS} parameter, @w{if set}, specifies the number of
times that a multi-frame pseudo-GIF should be looped.  The
@code{GIF_DELAY} parameter specifies the number of hundredths of a
seconds that should elapse between successive images.

The @code{INTERLACE} parameter is sometimes useful.  If it is set to
"yes", the pseudo-GIF will be interlaced.  This is of greatest value for
single-frame GIFs.  For full details on Plotter parameters, see
@ref{Driver Parameters}.

@node X Animations, X Programming, Animated GIFs, C Programming
@subsection X Window System animations in C

You may use @code{libplot} to produce vector graphics animations on any
Plotter that does real-time plotting (i.e., @w{an X}, @w{X Drawable},
Tektronix, or Metafile Plotter).  By definition, the `frames' in any
page of graphics are separated by invocations of @code{erase}.  @w{So
the} graphics display will be cleared after each frame.  If successive
frames differ only slightly, @w{a smooth} animation will result.

The following is a sample application, written @w{in C}, that produces
an animation for the @w{X Window} System.  @w{It displays} a `drifting
eye'.  @w{As the} eye drifts across a popped-up window from left to
right, it slowly rotates.  After the eye has drifted across twice, the
window will vanish.

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

@group
int main ()
@{
  int handle, i = 0, j;

  /* set Plotter parameters */        
  pl_parampl ("BITMAPSIZE", "300x150");
  pl_parampl ("VANISH_ON_DELETE", "yes");
  pl_parampl ("USE_DOUBLE_BUFFERING", "yes");
@end group

@group
  /* create an X Plotter with the specified parameters */
  if ((handle = pl_newpl ("X", stdin, stdout, stderr)) < 0)
    @{
      fprintf (stderr, "Couldn't create Plotter\n");
      return 1;
    @}
  pl_selectpl (handle);       /* select the Plotter for use */
@end group

@group
  if (pl_openpl () < 0)       /* open Plotter */
    @{
      fprintf (stderr, "Couldn't open Plotter\n");
      return 1;
    @}
@end group
@group
  pl_space (0, 0, 299, 149);  /* specify user coordinate system */
  pl_linewidth (8);           /* line thickness in user coordinates */
  pl_filltype (1);            /* objects will be filled */
  pl_bgcolorname ("saddle brown"); /* background color for the window*/
@end group
@group
  for (j = 0; j < 300; j++)
    @{
      pl_erase ();            /* erase window */
      pl_pencolorname ("red"); /* choose red pen, with cyan filling */
      pl_fillcolorname ("cyan");
      pl_ellipse (i, 75, 35, 50, i);  /* draw an ellipse */
      pl_colorname ("black"); /* choose black pen, with black filling */
      pl_circle (i, 75, 12);  /* draw a circle [the pupil] */
      i = (i + 2) % 300;      /* shift rightwards */
    @}
@end group
@group
  if (pl_closepl () < 0)         /* close Plotter */
    @{
      fprintf (stderr, "Couldn't close Plotter\n");
      return 1;
    @}
@end group

@group
  pl_selectpl (0);            /* select default Plotter */
  if (pl_deletepl (handle) < 0) /* delete Plotter we used */
    @{
      fprintf (stderr, "Couldn't delete Plotter\n");
      return 1;
    @}
  return 0;
@}
@end group
@end example

As you can see, this application begins by calling @code{pl_parampl}
several times to set device driver parameters, and then calls
@code{pl_newpl} to create an @w{X Plotter}.  The @w{X Plotter} window
will have size 300x150 pixels.  This window will vanish when the Plotter
is deleted.  @w{If the} @code{VANISH_ON_DELETE} parameter were not set
to "yes", the window would remain on the screen until removed by the
user (@w{by typing} @samp{q} @w{in it}, or by clicking with a mouse).

Setting the parameter @code{USE_DOUBLE_BUFFERING} to "yes" requests that
double buffering be used.  This is very important if you wish to produce
a smooth animation, with no jerkiness.  Normally, an @w{X Plotter} draws
graphics into a window in real time, and erases the window when
@code{pl_erase} is called.  But if double buffering is used, each frame
of graphics is written into an off-screen buffer, and is copied into the
window, pixel by pixel, when @code{pl_erase} is called or the Plotter is
closed.  This is a bit counterintuitive, but is exactly what is needed
for smooth animation.

After the Plotter is created, it is selected for use and opened.  When
@code{pl_openpl} is called, the window @w{pops up}, and the animation
begins.  In the body of the @t{for} loop there is a call to
@code{pl_erase}, and also a sequence of @code{libplot} operations that
draws the eye.  The pen color and fill color are changed twice with each
passage through the loop.  You may wish to experiment with the animation
parameters to produce the best effects on your video hardware.

The locations of the objects that are plotted in the animation are
expressed in terms of user coordinates, not pixel coordinates.  But the
call to @code{pl_space} defines user and pixel coordinates to be
effectively the same.  User coordinates are chosen so that the lower
left corner is (0,0) and the upper right corner is (299,149).  Since
this agrees with the window size, individual pixels may be addressed in
terms of integer user coordinates.  @w{For example},
@code{pl_point(299,149)} would set the pixel in the upper right hand
corner of the window to the current pen color.

The following is another sample animation, this time of a rotating
@w{letter `A'}.

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

@group
int main()
@{
  int handle, angle = 0;

  /* set Plotter parameters */        
  pl_parampl ("BITMAPSIZE", "300x300"); 
  pl_parampl ("BG_COLOR", "blue"); /* background color for window */
  pl_parampl ("USE_DOUBLE_BUFFERING", "yes");
@end group

@group
  /* create an X Plotter with the specified parameters */
  handle = pl_newpl ("X", stdin, stdout, stderr);
  pl_selectpl (handle);

  /* open X Plotter, initialize coordinates, pen, and font */
  pl_openpl ();
  pl_fspace (0.0, 0.0, 1.0, 1.0);  /* use normalized coordinates */
  pl_pencolorname ("white");
  pl_ffontsize (1.0);
  pl_fontname ("NewCenturySchlbk-Roman");
@end group

@group
  pl_fmove (.50,.50);           /* move to center */
  while (1)                     /* loop endlessly */
    @{
      pl_erase ();
      pl_textangle (angle++);      /* set new rotation angle */
      pl_alabel ('c', 'c', "A");   /* draw a centered `A' */
    @}
  pl_closepl();                 /* close Plotter */
@end group

@group
  pl_selectpl (0);              /* select default Plotter */
  pl_deletepl (handle);         /* delete Plotter we used */
  return 0;
@}
@end group
@end example

This animation serves as a good test of the capabilities of an @w{X
Window} System display.  @w{On a} modern X11R6 display, animation will
be smooth and fast.  That is because X11R6 displays can rasterize
individual characters from a font without rasterizing the entire font.
@w{If your} @w{X display} does not support the "NewCenturySchlbk-Roman"
font, you may substitute any other scalable font, such as the widely
available "utopia-medium-r-normal".  For the format of font names, see
@ref{Text Fonts in X}.  @w{If the} @w{X Plotter} is unable to retrieve
the font you specify, it will first attempt to use a default scalable
font ("Helvetica").  @w{If that} too fails, it will use a default
Hershey vector font ("HersheySerif") instead.

Animations that use Hershey fonts are normally faster than ones that use
Postscript fonts or other @w{X Window} System fonts, since the Hershey
fonts are constructed from line segments.  Rasterizing line segments can
be done rapidly.  But if you use a scalable font such as
"NewCenturySchlbk-Roman" or "utopia-medium-r-normal", you will notice
that the rotation @w{speeds up} after the letter `A' has rotated through
360 degrees.  That is because the `A' at angles past 360 degrees has
already been rasterized.

@node X Programming, , X Animations, C Programming
@subsection Advanced X Window System programming

Applications that run under the X Window System are normally built using
Xt, the @w{X Toolkit}.  @w{In Xt}, an application is constructed from
`widgets' such as text entry fields, buttons, sliders, drawing areas,
etc.  When the application @w{starts up}, each widget is configured to
respond appropriately to `events', which include key presses and mouse
clicks.  After the widgets are configured, control is transferred to the
@w{Xt event} loop.

GNU @code{libplot} can be used within the Xt event loop to draw vector
graphics.  For this, it would use one or more @w{X Drawable} Plotters.
An @w{X Drawable} Plotter is a Plotter that can plot into an off-screen
pixmap or an on-screen window, such as a window associated with a
widget.

The following sample application shows how an @w{X Drawable} Plotter
would be used.  The application draws a @w{`C' curve}, as defined in a
previous section, in a popped-up window.  The usual Xt command-line
options may be used: the window background color is specified with the
@samp{-bg} option, the window geometry with @samp{-geometry}, etc.  The
curve is initially drawn in red, but clicking once with the mouse will
redraw it in green.  @w{A second} mouse click will redraw it in red, and
@w{so forth}.  The application will terminate when @samp{q} is typed.

@example
@group
#include <stdio.h>
#include <plot.h>
@end group
@group
#include <X11/Xlib.h>
#include <X11/Intrinsic.h>
#include <X11/Shell.h>
#include <X11/StringDefs.h>
#include <X11/Core.h>
@end group

int green = 0;                  /* draw in green, not red? */

@group
#define MAXORDER 12
void draw_c_curve (double dx, double dy, int order)
@{
  if (order >= MAXORDER)
    pl_fcontrel (dx, dy);       /* continue path along (dx, dy) */
@end group
@group
  else
    @{
      draw_c_curve (0.5 * (dx - dy), 0.5 * (dx + dy), order + 1);
      draw_c_curve (0.5 * (dx + dy), 0.5 * (dy - dx), order + 1);
    @}
@}
@end group

void Redraw (Widget w, XEvent *ev, String *params, Cardinal *n_params)
@{
  /* draw C curve */
  pl_erase ();
  pl_pencolorname (green ? "green" : "red");
  pl_fmove (600.0, 300.0);  
  draw_c_curve (0.0, 400.0, 0);
  pl_endpath ();
@}

@group
void Toggle (Widget w, XEvent *ev, String *params, Cardinal *n_params)
@{
  green = (green ? 0 : 1);
  Redraw (w, ev, params, n_params);
@}
@end group

@group
void Quit (Widget w, XEvent *ev, String *params, Cardinal *n_params)
@{
  exit (0);
@}
@end group

@group
/* mapping of events to actions */
static const String translations =
"<Expose>:      redraw()\n\
<Btn1Down>:     toggle()\n\
<Key>q:         quit()";
@end group

@group
/* mapping of actions to subroutines */
static XtActionsRec actions[] = 
@{
  @{"redraw",            Redraw@},
  @{"toggle",            Toggle@},
  @{"quit",              Quit@},
@};
@end group

@group
/* default parameters for widgets */
static String default_resources[] = 
@{
  "Example*geometry:      250x250",
  (String)NULL
@};
@end group

@group
int main (int argc, char *argv[])
@{
  Arg wargs[10];                /* storage of widget args */
  Display *display;             /* X display */
  Widget shell, canvas;         /* toplevel widget; child */
  Window window;                /* child widget's window */
@end group
@group
  XtAppContext app_con;         /* application context */
  int handle, i;
  char *bg_colorname = "white";
@end group
  
@group
  /* take background color from command line */
  for (i = 0; i < argc - 1; i++)
    if (strcmp (argv[i], "-bg") == 0)
      bg_colorname = argv[i + 1];
@end group

  /* create toplevel shell widget */
  shell = XtAppInitialize (&app_con, 
                           (String)"Example", /* app class */
                           NULL,              /* options */
                           (Cardinal)0,       /* num of options */
                           &argc,             /* command line */
                           argv,              /* command line */
                           default_resources,
                           NULL,              /* ArgList */
                           (Cardinal)0        /* num of Args */
                           );

@group
  /* set default widget parameters (including window size) */
  XtAppSetFallbackResources (app_con, default_resources);
@end group

@group
  /* map actions to subroutines */
  XtAppAddActions (app_con, actions, XtNumber (actions));
@end group

@group
  /* create canvas widget as child of shell widget; realize both */
  XtSetArg(wargs[0], XtNargc, argc);
  XtSetArg(wargs[1], XtNargv, argv);
  canvas = XtCreateManagedWidget ((String)"", coreWidgetClass,
                                  shell, wargs, (Cardinal)2);
  XtRealizeWidget (shell);
@end group

@group
  /* for the canvas widget, map events to actions */
  XtSetArg (wargs[0], XtNtranslations, 
            XtParseTranslationTable (translations));
  XtSetValues (canvas, wargs, (Cardinal)1);
@end group

@group
  /* initialize GNU libplot */
  display = XtDisplay (canvas);
  pl_parampl ("XDRAWABLE_DISPLAY", display);
  window = XtWindow (canvas);
  pl_parampl ("XDRAWABLE_DRAWABLE1", &window); 
  pl_parampl ("BG_COLOR", bg_colorname);
@end group
@group
  handle = pl_newpl ("Xdrawable", NULL, NULL, stderr);
  pl_selectpl (handle);
  pl_openpl ();
  pl_fspace (0.0, 0.0, 1000.0, 1000.0);
  pl_flinewidth (0.25);     
@end group

@group
  /* transfer control to X Toolkit event loop (doesn't return) */
  XtAppMainLoop (app_con);
@end group

  return 1;
@}
@end example

Even if you are not familiar with @w{X Window} System programming, the
structure of this application should be clear.  @w{It defines} three
callbacks: @code{Redraw}, @code{Toggle}, and @code{Quit}.  They are
invoked respectively in response to @w{(1) a} window expose event or
mouse click, @w{(2) a} mouse click, and @w{(3) a} @w{typed @samp{q}}.
The first drawing of the @w{`C' curve} (@w{in red}) takes place because
the window receives an initial expose event.

This example could be extended to take window resizing into account.
Actually, @w{X Drawable} Plotters are usually used to draw vector
graphics in off-screen pixmaps rather than on-screen windows.  Pixmaps,
unlike windows, are never resized.

@node C++ Programming, Functions, C Programming, libplot
@section C++ Programming with @code{libplotter}

@menu
* The Plotter Class::           The Plotter class
* C++ Compiling and Linking::   C++ compiling and linking
* Sample C++ Drawings::         Sample drawings in C++
@end menu

@node The Plotter Class, C++ Compiling and Linking, C++ Programming, C++ Programming
@subsection The @code{Plotter} class

The C++ binding for @code{libplot} is provided by a class library, named
@code{libplotter}.  This library implements a @code{Plotter} class,
@w{of which} all Plotters are instances.  Actually, a Plotter would
normally be an instance of an appropriate derived class, determined by
the Plotter's output format.  Derived classes currently include
@code{XPlotter}, @code{XDrawablePlotter}, @code{PNMPlotter},
@code{GIFPlotter}, @code{AIPlotter}, @code{PSPlotter},
@code{FigPlotter}, @code{PCLPlotter}, @code{HPGLPlotter},
@code{TekPlotter}, and @code{MetaPlotter}.  The names should be
self-explanatory.  The operations that may be applied to any Plotter
(e.g., the @code{openpl} operation, which begins a page of graphics) are
implemented as public function members of the @code{Plotter} class.

At the time a Plotter is created, its input, output, and error streams
must be specified.  (The first is ignored, since @w{at present}, all
Plotters are write-only.)  The streams may be specified either as
iostreams or as @code{FILE} pointers.  That is, the two constructors

@example
  Plotter(istream& instream, ostream& outstream, ostream& errstream);
  Plotter(FILE *infile, FILE *outfile, FILE *errfile);
@end example

@noindent
are provided for the base Plotter class, and similarly for each of its
derived classes.  So, for example, both

@example
PSPlotter plotter(cin, cout, cerr);
@end example

@noindent
and

@example
PSPlotter plotter(stdin, stdout, stderr);
@end example

@noindent
are possible declarations of a Postscript Plotter that writes to
standard output.  In the iostream case, an ostream with a null stream
buffer may be specified as the output stream and/or the error stream, to
request that no output take place.  @w{In the} @code{FILE} pointer case,
specifying a null @code{FILE} pointer would accomplish the same thing.
Instances of the @code{XPlotter} and @code{XDrawablePlotter} classes
always ignore the output stream argument, since they write graphics to
an @w{X Display} rather than to a stream.

The parameter-setting function @code{parampl}, which plays an important
role in all bindings of @code{libplot}, is implemented in
@code{libplotter} as a static function member of the @code{Plotter}
class.  The following is a formal description.

@table @asis
@item int @t{Plotter::parampl} (const char *@var{parameter}, void *@var{value});
@t{Plotter::parampl} sets the value of the device driver parameter
@var{parameter} to @var{value}.  Device driver parameters specify
Plotter options.  The parameter values in effect at the time any Plotter
is created are copied @w{into it}.  For most parameters, @var{value}
should be a @code{char *}, i.e., a string.  Unrecognized parameters are
ignored.  For a list of the recognized parameters and their meaning, see
@ref{Driver Parameters}.
@end table

Just as in the C binding, @code{Plotter::parampl} gives the programmer
fine control over the parameters of subsequently created Plotters.  The
parameter values used by any Plotter are constant over the lifetime of
the Plotter, and are those that were set when the Plotter was created.
@w{If at} Plotter creation time a parameter is @emph{not} set, its
default value will be used, unless the parameter is string-valued and
there is an environment variable of the same name, in which case the
value of that environment variable will be used.

Once set, @w{a parameter} may be unset by the programmer by calling
@code{Plotter::parampl} with a value argument of NULL@.  This further
increases flexibility.

@node C++ Compiling and Linking, Sample C++ Drawings, The Plotter Class, C++ Programming
@subsection C++ compiling and linking

The source code for a graphics application written in C++, if it is to
use @code{libplotter}, must contain the line

@example
#include <plotter.h>
@end example

@noindent
The header file @code{plotter.h} is distributed with @code{libplotter},
and should have been installed on your system where your @w{C++
compiler} will find it.  @w{It declares} the @code{Plotter} class and
its derived class, and also contains some miscellaneous definitions.
@w{It includes} the header files @code{<iostream.h>} and
@code{<stdio.h>}, so you do not need to include them separately.

To link your application with @code{libplotter}, you would use the
appropriate @samp{-l} option(s) on the command line when compiling it.
You would use

@example
-lplotter -lXaw -lXmu -lXt -lXext -lX11 -lm
@end example

@noindent
or, in recent releases of the @w{X Window} System,

@example
-lplotter -lXaw -lXmu -lXt -lSM -lICE -lXext -lX11 -lm
@end example

@noindent
(Alternatively, you may need to use @samp{-lplotter -lXm -lXt -lXext
-lX11 -lm}, @samp{-lplotter -lXm -lXt -lXext -lX11 -lm -lc -lgen}, or
@samp{-lplotter -lXm -lXt -lXext -lX11 -lm -lc -lPW}, on systems that
provide Motif widgets instead of Athena widgets.  In recent releases of
the @w{X Window} System, you would insert @samp{-lSM -lICE}@.  Recent
releases of Motif require @samp{-lXp} @w{as well}.)

On some platforms, the directories in which @code{libplotter} or the
other libraries are stored must be specified on the command line.
@w{For example}, the options @samp{-lXaw -lXmu -lXt -lSM -lICE -lXext
-lX11}, which specify @w{X Window} System libraries, may need to be
preceded by an option like @samp{-L/usr/X11/lib}.

On most systems @code{libplotter} is installed as a DLL (dynamically
linked library, or `shared' library).  This means that the linking with
your application will take place at run time rather than compile time.
The environment variable @code{LD_LIBRARY_PATH} lists the directories
which will be searched for DLL's at run time.  For your application to
be executable, this environment variable should include the directory in
which @code{libplotter} is stored.

@node Sample C++ Drawings, , C++ Compiling and Linking, C++ Programming
@subsection Sample drawings in C++

In a previous section, there are several sample @w{C programs} that show
how to draw vector graphics using @code{libplot}'s @w{C binding}.
@xref{Sample C Drawings}.  @w{In this} section, we give a modified
version of one of the C programs, showing how @code{libplot}'s C++
binding, i.e., @code{libplotter}, can be used similarly.

The following C++ program draws an intricate and beautiful path (Bill
Gosper's @w{``C'' curve}).

@example
@group
#include <plotter.h>
#define MAXORDER 12
@end group
     
@group
void draw_c_curve (Plotter& plotter, double dx, double dy, int order)
@{
  if (order >= MAXORDER)
    plotter.fcontrel (dx, dy);	// continue path along (dx, dy)
@end group
@group
  else
    @{
      draw_c_curve (plotter, 
                    0.5 * (dx - dy), 0.5 * (dx + dy), order + 1);
      draw_c_curve (plotter,
                    0.5 * (dx + dy), 0.5 * (dy - dx), order + 1);
    @}
@}
@end group
     
@group
int main ()
@{
  // set a Plotter parameter
  Plotter::parampl ("PAGESIZE", "letter");
@end group
     
@group
  PSPlotter plotter(cin, cout, cerr); // declare Plotter
  if (plotter.openpl () < 0)          // open Plotter
    @{
      cerr << "Couldn't open Plotter\n";
      return 1;
    @}
@end group

  plotter.fspace (0.0, 0.0, 1000.0, 1000.0); // specify user coor system
  plotter.flinewidth (0.25);       // line thickness in user coordinates
  plotter.pencolorname ("red");    // path will be drawn in red
  plotter.erase ();                // erase Plotter's graphics display
  plotter.fmove (600.0, 300.0);    // position the graphics cursor
  draw_c_curve (plotter, 0.0, 400.0, 0);
@group
  if (plotter.closepl () < 0)      // close Plotter
    @{
      cerr << "Couldn't close Plotter\n";
      return 1;
    @}
  return 0;
@}
@end group
@end example

The above is a straightforward translation of the corresponding @w{C
program}.  Here, @code{plotter} is declared as an instance of the
@code{PSPlotter} class, which will write Postscript graphics to the
output stream @code{cout}.  The graphics are drawn by invoking member
functions.

This object-oriented approach to drawing graphics is probably more
natural than the approach used by the @w{C binding}.  With
@code{libplotter}, the use of multiple Plotters in an application
becomes very easy.  @w{No switching} between Plotters is required: the
graphics operations can be immediately invoked on any existing Plotter.

@node Functions, Driver Parameters, C++ Programming, libplot
@section The functions in @code{libplot}: A detailed listing

In the current release of GNU @code{libplot}, any Plotter supports 92
distinct operations.  @w{A language} binding for @code{libplot}
necessarily includes 92 functions that correspond to these operations.
@w{In the} C binding, these 92 functions belong to the @w{C API}
(application programming interface).  @w{In the} C++ binding, they are
implemented as public member functions of the @code{Plotter} class.

@w{A language} binding may also include functions for creating,
selecting, and deleting Plotters.  For example, the @w{C binding}
includes the additional functions @code{pl_newpl}, @code{pl_selectpl},
and @code{pl_deletepl}.  @xref{The C API}.  In the C binding, the names
of all functions should be preceded by "pl_" unless the header file
@code{plotcompat.h} is included.  @xref{C Compiling and Linking}.

The 92 functions that operate on a specified Plotter are divided into
the four sets tabulated below.

@iftex
@enumerate
@item
Setup functions: functions that open, initialize, or close the Plotter.
@item
Functions that cause the Plotter to draw objects.
@item
Functions that set or affect the Plotter's drawing attributes.
@item
Functions affecting the affine map used by the Plotter to transform
user coordinates to device coordinates.
@end enumerate
@end iftex

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.  @w{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 of the 92 functions have meaningful return values.

@menu
* Setup Functions::     Functions that open, initialize or close a Plotter
* Drawing Functions::   Functions that draw objects
* Attribute Functions:: Functions that affect drawing attributes
* Mapping Functions::   Functions affecting the user -> device coordinate map
@end menu

@node Setup Functions, Drawing Functions, Functions, Functions
@subsection Setup functions

The following are the ``setup functions'' in @code{libplot}.  They are
the basic functions that open, initialize, or close an already-created
Plotter.  They are listed in the approximate order in which they would
be called.

In the C binding, the names of all functions should be preceded by
"pl_", unless the header file @code{plotcompat.h} is included.  @xref{C
Compiling and Linking}.  @w{In the} C++ binding, these are member
functions of the @code{Plotter} class and its subclasses.

@table @asis
@item int @t{openpl} ();
@t{openpl} opens a Plotter, i.e., begins a page of graphics.  This
resets the Plotter's drawing attributes to their default values.  @w{A
negative} return value indicates the Plotter could not be opened.

Currently, an X Plotter @w{pops up} a new window on an @w{X Window}
System display for each page of graphics, i.e., with each invocation of
@code{openpl}.  Future releases may support window re-use.

@item int @t{bgcolor} (int @var{red}, int @var{green}, int @var{blue});   
@t{bgcolor} sets the background color for the Plotter's 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 background 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.

@t{bgcolor} affects only Plotters that produce bitmaps, i.e., @w{X
Plotters}, X Drawable Plotters, PNM Plotters, and GIF Plotters.  Its
effect is simple: the next time the @t{erase} operation is invoked on
such a Plotter, its display will be filled with the specified color.

@item int @t{bgcolorname} (const char *@var{name});
@t{bgcolorname} sets the background color for the the graphics display
to be @var{name}.  For information on what color names are recognized,
see @ref{Color Names}.  Unrecognized colors are interpreted as "white".

@t{bgcolorname} affects only Plotters that produce bitmaps, i.e., X
Plotters, X Drawable Plotters, PNM Plotters, and GIF Plotters.  Its
effect is simple: the next time the @t{erase} operation is invoked on
such a Plotter, its display will be filled with the specified color.

@item int @t{erase} ();
@t{erase} begins the next frame of a multiframe page, by clearing all
previously plotted objects from the graphics display, and filling it
with the background color @w{(if any)}.

It is frequently useful to invoke @t{erase} at the beginning of each
page, i.e., immediately after invoking @t{openpl}.  That is because some
Plotters are persistent, in the sense that objects drawn within an
@code{openpl}@dots{}@code{closepl} pair remain on the graphics display
even after a new page is begun by a subsequent invocation of
@code{openpl}.  Currently, only @w{X Drawable} Plotters and Tektronix
Plotters are persistent.  Future releases may support optional
persistence for @w{X Plotters} also.

On X Plotters and X Drawable Plotters the effects of invoking @t{erase}
will be altogether different if the device driver parameter
@code{USE_DOUBLE_BUFFERING} is set to "yes".  @w{In this} case, objects
will be written to an off-screen buffer rather than to the graphics
display, and invoking @t{erase} will @w{(1) copy} the contents of this
buffer to the display, and @w{(2) erase} the buffer by filling it with
the background color.  This `double buffering' feature facilitates
smooth animation.  @xref{Driver Parameters}.

@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
graphics display, in user coordinates.  In other words, calling
@t{space} or @t{fspace} sets the affine transformation from user
coordinates to device coordinates.  One of these operations must be
performed at the beginning of each page of graphics, i.e., immediately
after @t{openpl} is invoked.

@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}, and may be used instead.  Their arguments are the three
defining vertices of an `affine window' (a drawing parallelogram), in
user coordinates.  The specified vertices are the lower left, the lower
right, and the upper left.  This window will be mapped affinely onto the
graphics display.

@item int @t{havecap} (const char *@var{s});
@t{havecap} tests whether or not a Plotter, which need not be open, has
a specified capability.  The return value is @w{0, 1}, @w{or 2},
signifying no/yes/maybe.  For unrecognized capabilities the return value
is zero.  Recognized capabilities include "WIDE_LINES" (i.e., the
ability to draw lines with a non-default thickness), "DASH_ARRAY" (the
ability to draw in arbitrary dashing styles, as requested by the
@t{linedash} function), "SETTABLE_BACKGROUND" (the ability to set the
color of the background), and "SOLID_FILL".  The "HERSHEY_FONTS",
"PS_FONTS", "PCL_FONTS", and "STICK_FONTS" capabilities indicate whether
or not fonts of a particular class are supported.  @xref{Text Fonts}.

All Plotters except Tektronix Plotters have the "SOLID_FILL" capability,
meaning they can fill paths with solid color.  Each such Plotter has at
least one of the "EVEN_ODD_FILL" and "NONZERO_WINDING_NUMBER_FILL"
capabilities.  These indicate the supported rules for determining the
`inside' of a path.

The `maybe' value is returned for most capabilities by Metafile
Plotters, which do no drawing themselves.  The output of a Metafile
Plotter must be translated to another format, or displayed, by invoking
@code{plot}.

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

@item int @t{closepl} ();
@t{closepl} closes a Plotter, i.e., ends a page of graphics.  @w{A
negative} return value indicates the Plotter could not be closed.

In the present release of @code{libplot}, some Plotters output pages in
real time, i.e., with each invocation of @t{closepl}.  This is true of
PCL and HP-GL Plotters, for example.  Similarly, Plotters that normally
output only a single page (PNM, GIF, Illustrator, and Fig Plotters) do
so immediately after that page is ended.  However, Postscript Plotters
do not output their page(s) of graphics until they are deleted.
@end table

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

The following are the ``drawing functions'' in @code{libplot}.  When
invoked on a Plotter, these functions cause it to draw objects (paths,
circles, ellipses, points, markers, and text strings) on the associated
graphics display.  @w{A @emph{path}} is a sequence of line segments, arc
segments (either circular or elliptic), and/or Bezier curve segments
(either quadratic or cubic).  Paths are drawn incrementally, one segment
at a time.

In the C binding, the names of all functions should be preceded by
"pl_", unless the header file @code{plotcompat.h} is included.  @xref{C
Compiling and Linking}.  @w{In the} C++ binding, these are member
functions of the @code{Plotter} class and its subclasses.

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

The string may contain escape sequences of various sorts (see @ref{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 string may be plotted at a nonzero angle, if @code{textangle} has
been called.

@item int @t{arc} (int @var{xc}, int @var{yc}, int @var{x0}, int @var{y0}, int @var{x1}, int @var{y1});
@itemx int @t{farc} (double @var{xc}, double @var{yc}, double @var{x0}, double @var{y0}, double @var{x1}, double @var{y1});
@itemx int @t{arcrel} (int @var{xc}, int @var{yc}, int @var{x0}, int @var{y0}, int @var{x1}, int @var{y1});
@itemx int @t{farcrel} (double @var{xc}, double @var{yc}, double @var{x0}, double @var{y0}, double @var{x1}, double @var{y1});
@t{arc} and @t{farc} take six arguments specifying the beginning
(@var{x0}, @var{y0}), end (@var{x1}, @var{y1}), and center (@var{xc},
@var{yc}) of a circular arc.  @w{If the} graphics cursor is at
(@var{x0}, @var{y0}) and a path is under construction, then the arc is
added to the path.  Otherwise the current path (@w{if any}) is ended,
and the arc begins a new path.  In all cases the graphics cursor is
moved to (@var{x1}, @var{y1}).

The direction of the arc (clockwise or counterclockwise) is determined
by the convention that the arc, centered at (@var{xc}, @var{yc}), sweep
through an angle of at most 180 degrees.  @w{If the} three points appear
to be collinear, the direction is taken to be counterclockwise.  If
(@var{xc}, @var{yc}) is not equidistant from (@var{x0}, @var{y0}) and
(@var{x1}, @var{y1}) as it @w{should be}, @w{it is} corrected by being
moved to the closest point on the perpendicular bisector of the line
segment joining (@var{x0}, @var{y0}) and (@var{x1}, @var{y1}).
@t{arcrel} and @t{farcrel} are similar to @code{arc} and @code{farc},
but use cursor-relative coordinates.

@item int @t{bezier2} (int @var{x0}, int @var{y0}, int @var{x1}, int @var{y1}, int @var{x2}, int @var{y2});
@itemx int @t{fbezier2} (double @var{x0}, double @var{y0}, double @var{x1}, double @var{y1}, double @var{x2}, double @var{y2});
@itemx int @t{bezier2rel} (int @var{x0}, int @var{y0}, int @var{x1}, int @var{y1}, int @var{x2}, int @var{y2});
@itemx int @t{fbezier2rel} (double @var{x0}, double @var{y0}, double @var{x1}, double @var{y1}, double @var{x2}, double @var{y2});
@t{bezier2} and @t{fbezier2} take six arguments specifying the beginning
@code{p0}=(@var{x0}, @var{y0}) and end @code{p2}=(@var{x2}, @var{y2}) of
a quadratic Bezier curve, and its intermediate control point
@code{p1}=(@var{x1}, @var{y1}).  @w{If the} graphics cursor is @w{at
@code{p0}} and a path is under construction, then the curve is added to
the path.  Otherwise the current path (@w{if any}) is ended, and the
curve begins a new path.  @w{In all} cases the graphics cursor is moved
@w{to @code{p2}}.  @t{bezier2rel} and @t{fbezier2rel} are similar to
@code{bezier2} and @code{fbezier2}, but use cursor-relative coordinates.

The quadratic Bezier curve is tangent at @code{p0} to the line segment
joining @code{p0} @w{to @code{p1}}, and is tangent @w{at @code{p2}} to
the line segment joining @code{p1} @w{to @code{p2}}.  @w{So it} fits
snugly into a triangle with vertices @code{p0}, @code{p1}, @w{and
@code{p2}}.

When using a PCL Plotter to draw Bezier curves on a LaserJet III, you
should set the parameter @code{PCL_BEZIERS} to "no".  That is because
the LaserJet III, which was Hewlett--Packard's first @w{PCL 5} printer,
does not recognize the Bezier instructions supported by later @w{PCL 5}
printers.  See @ref{Driver Parameters}.

@item int @t{bezier3} (int @var{x0}, int @var{y0}, int @var{x1}, int @var{y1}, int @var{x2}, int @var{y2}, int @var{x3}, int @var{y3});
@itemx int @t{fbezier3} (double @var{x0}, double @var{y0}, double @var{x1}, double @var{y1}, double @var{x2}, double @var{y2}, double @var{x3}, double @var{y3});
@itemx int @t{bezier3rel} (int @var{x0}, int @var{y0}, int @var{x1}, int @var{y1}, int @var{x2}, int @var{y2}, int @var{x3}, int @var{y3});
@itemx int @t{fbezier3rel} (double @var{x0}, double @var{y0}, double @var{x1}, double @var{y1}, double @var{x2}, double @var{y2}, double @var{x3}, double @var{y3});
@t{bezier3} and @t{fbezier3} take eight arguments specifying the
beginning @code{p0}=(@var{x0}, @var{y0}) and end @code{p3}=(@var{x3},
@var{y3}) of a cubic Bezier curve, and its intermediate control points
@code{p1}=(@var{x1}, @var{y1}) and @code{p2}=(@var{x2}, @var{y2}).
@w{If the} graphics cursor is @w{at @code{p0}} and a path is under
construction, then the curve is added to the path.  Otherwise the
current path (@w{if any}) is ended, and the curve begins a new path.
@w{In all} cases the graphics cursor is moved @w{to @code{p3}}.
@t{bezier3rel} and @t{fbezier3rel} are similar to @code{bezier3} and
@code{fbezier3}, but use cursor-relative coordinates.

The cubic Bezier curve is tangent at @code{p0} to the line segment
joining @code{p0} @w{to @code{p1}}, and is tangent @w{at @code{p3}} to
the line segment joining @code{p2} @w{to @code{p3}}.  @w{So it} fits
snugly into a quadrangle with vertices @code{p0}, @code{p1}, @code{p2},
@w{and @code{p3}}.

When using a PCL Plotter to draw Bezier curves on a LaserJet III, you
should set the parameter @code{PCL_BEZIERS} to "no".  That is because
the LaserJet III, which was Hewlett--Packard's first @w{PCL 5} printer,
does not recognize the Bezier instructions supported by later @w{PCL 5}
printers.  See @ref{Driver Parameters}.

@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})
of a `box', or rectangle.  The path under construction (@w{if any}) is
ended, and the box is drawn as a new path.  This path is also ended, and
the graphics cursor is moved to the midpoint of the box.  @t{boxrel} and
@t{fboxrel} are similar to @t{box} and @t{fbox}, but use cursor-relative
coordinates.

@item int @t{circle} (int @var{xc}, int @var{yc}, int @var{r});
@itemx int @t{fcircle} (double @var{xc}, double @var{yc}, double @var{r});
@itemx int @t{circlerel} (int @var{xc}, int @var{yc}, int @var{r});
@itemx int @t{fcirclerel} (double @var{xc}, double @var{yc}, double @var{r});
@t{circle} and @t{fcircle} take three arguments specifying the center
(@var{xc}, @var{yc}) and radius (@var{r}) of a circle.  The path under
construction (@w{if any}) is ended, and the circle is drawn.  The
graphics cursor is moved to (@var{xc}, @var{yc}).  @t{circlerel} and
@t{fcirclerel} are similar to @t{circle} and @t{fcircle}, but use
cursor-relative coordinates for @var{xc} and @var{yc}.

@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 coordinates
(@var{x}, @var{y}) of a point.  If a path is under construction, the
line segment from the current graphics cursor position to the point
(@var{x}, @var{y}) is added to it.  Otherwise the line segment begins a
new path.  In all cases the graphics cursor is moved to (@var{x},
@var{y}).  @t{contrel} and @t{fcontrel} are similar to @t{cont} and
@t{fcont}, but use cursor-relative coordinates.

@item int @t{ellarc} (int @var{xc}, int @var{yc}, int @var{x0}, int @var{y0}, int @var{x1}, int @var{y1});
@itemx int @t{fellarc} (double @var{xc}, double @var{yc}, double @var{x0}, double @var{y0}, double @var{x1}, double @var{y1});
@itemx int @t{ellarcrel} (int @var{xc}, int @var{yc}, int @var{x0}, int @var{y0}, int @var{x1}, int @var{y1});
@itemx int @t{fellarcrel} (double @var{xc}, double @var{yc}, double @var{x0}, double @var{y0}, double @var{x1}, double @var{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 from @code{p0} to @code{p1} with @w{center
@code{pc}}.  @w{If the} graphics cursor is at point @code{p0} and a path
is under construction, the quarter-ellipse is added to it.  Otherwise
the path under construction (@w{if any}) is ended, and the
quarter-ellipse begins a new path.  @w{In all} cases the graphics cursor
is moved to @code{p1}.

The quarter-ellipse is an affinely transformed version of a quarter
circle.  @w{It is} drawn so as 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.  Notice that the third control point is the reflection of
@code{pc} through the line joining @code{p0} @w{and @code{p1}}.
@t{ellarcrel} and @t{fellarcrel} are similar to @t{ellarc} and
@t{fellarc}, but use cursor-relative coordinates.

@item int @t{ellipse} (int @var{xc}, int @var{yc}, int @var{rx}, int @var{ry}, int @var{angle});
@itemx int @t{fellipse} (double @var{xc}, double @var{yc}, double @var{rx}, double @var{ry}, double @var{angle});
@itemx int @t{ellipserel} (int @var{xc}, int @var{yc}, int @var{rx}, int @var{ry}, int @var{angle});
@itemx int @t{fellipserel} (double @var{xc}, double @var{yc}, double @var{rx}, double @var{ry}, double @var{angle});
@t{ellipse} and @t{fellipse} take five arguments specifying the center
(@var{xc}, @var{yc}) of 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
coordinate system.  The path under construction (@w{if any}) is ended,
and the ellipse is drawn.  The graphics cursor is moved to (@var{xc},
@var{yc}).  @t{ellipserel} and @t{fellipserel} are similar to
@t{ellipse} and @t{fellipse}, but use cursor-relative coordinates.

@item int @t{endpath} ();
@t{endpath} terminates the path under construction, @w{if any}.  @w{A
path} is constructed by one or more successive calls to @t{cont},
@t{line}, @t{arc}, @t{ellarc}, @t{bezier2}, @t{bezier3}, and/or their
floating-point counterparts.  The path will also be terminated if any
non-path object is drawn, if any path-related drawing attribute is set,
or if @t{move} or @t{fmove} is invoked to set the cursor position.  So
@t{endpath} is almost redundant.  However, if a Plotter plots objects in
real time, calling @t{endpath} will ensure that a constructed path is
drawn on the graphics display without delay.

@item int @t{label} (const 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} (const char *@var{s});
@itemx double @t{flabelwidth} (const char *@var{s});
@t{labelwidth} and @t{flabelwidth} compute and return the width of a
string in the current font, in the user coordinate system.  The string
is not plotted.

@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
segment.  @w{If the} graphics cursor is at (@var{x1}, @var{y1}) and a
path is under construction, the line segment is added to it.  Otherwise
the path under construction (@w{if any}) is ended, and the line segment
begins a new path.  @w{In all} cases the graphics cursor is moved to
(@var{x2}, @var{y2}).  @t{linerel} and @t{flinerel} are similar to
@t{line} and @t{fline}, but use cursor-relative coordinates.

@item  int @t{marker} (int @var{x}, int @var{y}, int @var{type}, int @var{size});
@itemx int @t{fmarker} (double @var{x}, double @var{y}, int @var{type}, double @var{size});
@itemx int @t{markerrel} (int @var{x}, int @var{y}, int @var{type}, int @var{size});
@itemx int @t{fmarkerrel} (double @var{x}, double @var{y}, int @var{type}, double @var{size});
@t{marker} and @t{fmarker} take four arguments specifying the location
(@var{x},@var{y}) of a marker symbol, its type, and its size in user
coordinates.  The path under construction (@w{if any}) is ended, and the
marker symbol is plotted.  The graphics cursor is moved to
(@var{x},@var{y}).  @t{markerrel} and @t{fmarkerrel} are similar to
@t{marker} and @t{fmarker}, but use cursor-relative coordinates for the
position (@var{x},@var{y}).

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

@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 coordinates
(@var{x}, @var{y}) of a point.  The path under construction @w{(if any)}
is ended, and the point is plotted.  (Plotters that produce bitmaps draw
points as single pixels.  Other Plotters draw them as small solid
circles, usually the smallest that can be plotted.)  The graphics cursor
is moved to (@var{x}, @var{y}).  @t{pointrel} and @t{fpointrel} are
similar to @t{point} and @t{fpoint}, but use cursor-relative
coordinates.
@end table

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

The following are the ``attribute functions'' in @code{libplot}.  When
invoked on a Plotter, these functions set its drawing attributes, or
save them or restore them.  Path-related attributes include graphics
cursor position, pen color, fill color, fill rule, line thickness, line
style, cap style, join style, and miter limit.  Text-related attributes
include pen color, font name, font size, and text angle.

Setting any path-related drawing attribute automatically terminates the
path under construction (@w{if any}), @w{as if} the @code{endpath}
operation had been invoked.

In the C binding, the names of all functions should be preceded by
"pl_", unless the header file @code{plotcompat.h} is included.  @xref{C
Compiling and Linking}.  @w{In the} C++ binding, these are member
functions of the @code{Plotter} class and its subclasses.

@table @asis
@item int @t{capmod} (const char *@var{s});
@t{capmod} sets the cap mode (i.e., cap style) for all paths
subsequently drawn on the graphics display.  Recognized styles are
"butt" (the default), "round", and "projecting".  The three styles are
visibly distinct only if the line thickness is fairly large.  Butt caps
@w{do not} extend beyond the end of the path.  The other two kinds do,
however.  Round caps are filled semicircles, and projecting caps are
filled rectangular regions that extend a distance equal to half the line
width beyond the end of the path.

PCL and HP-GL Plotters support a fourth cap mode, "triangular".
Plotters other than PCL and HP-GL Plotters treat "triangular" as
equivalent to "round".

This function has no effect on Tektronix Plotters.  Also, it has no
effect on HP-GL Plotters if the parameter @code{HPGL_VERSION} is set to
a value less @w{than "2"} (the default).  @xref{Driver Parameters}.

@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.  Note that the physical fill color depends also on the fill
fraction, which is specified by calling @t{filltype}.

@item int @t{colorname} (const 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.  Note that the physical fill color
depends also on the fill fraction, which is specified by calling
@t{filltype}.

@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{filltype}.  

@item int @t{fillcolorname} (const 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, see @ref{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{filltype}.

@item int @t{fillmod} (const char *@var{s});
@t{fillmod} sets the fill mode, i.e., fill rule, for all objects
subsequently drawn on the graphics display.  The fill rule affects only
filled, self-intersecting paths: it determines which points are
`inside'.  Two rules are supported: "even-odd" (the default for all
Plotters), and "nonzero-winding".  For the distinction, see the
@cite{Postscript Language Reference Manual}.  "alternate" is an alias
for "even-odd" and "winding" is an alias for "nonzero-winding".

Fig Plotters do not support the "nonzero-winding" fill rule, because
@code{xfig} itself does not support it.  Also, HPGL Plotters do not
support it if @code{HPGL_VERSION} is set to a value less than "2" (the
default).  @xref{Driver Parameters}.

The LaserJet III, which was Hewlett--Packard's first @w{PCL 5} printer,
did not support the nonzero-winding fill rule.  However, all later
@w{PCL 5} printers from Hewlett--Packard @w{support it}.

@item int @t{filltype} (int @var{level});
@t{filltype} 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.  @w{For
example}, @t{0x8000} specifies 50% filling (the fill color will be
intermediate between the color specified by calling @t{fillcolor} or
@t{fillcolorname}, and white).

Tektronix Plotters do not support filling, and HP-GL Plotters support
filling of arbitrary paths only if the parameter @code{HPGL_VERSION} is
equal to "1.5" @w{or "2"} (the default).  (If the version @w{is "1"}
then only circles and rectangles aligned with the coordinate axes may be
filled.)  @emph{Opaque} filling, including white filling, is supported
only if the parameter @code{HPGL_VERSION} @w{is "2"} and the parameter
@code{HPGL_OPAQUE_MODE} is "yes" (the default).  @xref{Driver
Parameters}.

@item int @t{fmiterlimit} (double @var{limit});
@t{fmiterlimit} sets the miter limit for all paths subsequently drawn on
the graphics display.  The miter limit controls the treatment of
corners, if the join mode is set to "miter" (the default).  @w{At a}
join point of a path, the `miter length' is defined to be the distance
between the inner corner and the outer corner.  The miter limit is the
maximum value that will be tolerated for the miter length divided by the
line thickness.  If this value is exceeded, the miter will be @w{cut
off}: the "bevel" join mode will be used instead.

Examples of typical values for @var{limit} are 10.43 (the default, which
cuts off miters if the join angle is less than 11 degrees), 2.0 (the
same, for 60 degrees), and 1.414 (the same, for 90 degrees).  @w{In
general}, the miter limit is the cosecant of one-half the minimum angle
for mitered joins.  The minimum meaningful value for @var{limit} @w{is
1.0}, which converts all mitered joins to beveled joins, irrespective of
join angle.  Specifying a value less than 1.0 resets the limit to the
default.

This function has no effect on @w{X Drawable} Plotters or @w{X
Plotters}, since the @w{X Window} System miter limit, which is also
10.43, cannot be altered.  It also has no effect on Tektronix Plotters
or Fig Plotters, or on HP-GL Plotters if the parameter
@code{HPGL_VERSION} is set to a value less @w{than "2"} (the default).
@xref{Driver Parameters}.

@item int @t{fontname} (const char *@var{font_name});
@itemx double @t{ffontname} (const 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 graphics display.  (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.

The default font name depends on the type of Plotter.  @w{It is}
"Helvetica" for all Plotters except PNM, GIF, HP-GL, Tektronix and
Metafile Plotters, for which it is "HersheySerif".  @w{If the} argument
@var{font_name} is NULL or the empty string, or the font is not
available, the default font name will be used.  Which fonts are
available also depends on the type of Plotter; for a list of all
available fonts, see @ref{Text Fonts}.

@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 coordinate system, of the font to be used for all
text strings subsequently drawn on the graphics display.  (The font for
plotting strings is fully specified by calling @t{fontname},
@t{fontsize}, and @t{textangle}.)  The size of the font in user
coordinates is returned.  @w{A negative} value for @var{size} sets the
size to the default, which depends on the type of Plotter.  Typically,
the default font size is 1/50 times the size (i.e., minimum dimension)
of the display.

@item int @t{joinmod} (const char *@var{s});
@t{joinmod} sets the join mode (i.e., join style) for all paths
subsequently drawn on the graphics display.  Recognized styles are
"miter" (the default), "round", and "bevel".  The three styles are
visibly distinct only if the line thickness is fairly large.  Mitered
joins are sharp, rounded joins are round, and beveled joins are
@w{squared off}.  However, unusually sharp joins are never mitered:
instead, they are beveled.  The angle at which beveling replaces
mitering may be specified by calling @t{fmiterlimit}.

PCL and HP-GL Plotters support a fourth join mode, "triangular".
Plotters other than PCL and HP-GL Plotters treat "triangular" as
equivalent to "round".

This function has no effect on Tektronix Plotters.  Also, it has no
effect on HP-GL Plotters if the parameter @code{HPGL_VERSION} is set to
a value less @w{than "2"} (the default).  @xref{Driver Parameters}.

@item int @t{linedash} (int @var{n}, const int *@var{dashes}, int @var{offset});
@itemx int @t{flinedash} (int @var{n}, const double *@var{dashes}, double @var{offset});
@t{linedash} and @t{flinedash} set the line style for all paths,
circles, and ellipses subsequently drawn on the graphics display.  They
provide much finer control of dash patterns than the @t{linemod}
function (see below) provides.  @var{dashes} should be an array of
@w{length @var{n}}.  Its elements, which should be positive, are
interpreted as distances in the user coordinate system.  Along any path,
circle, or ellipse, the elements
@var{dashes}[0]@dots{}@var{dashes}[@var{n}-1] alternately specify the
length of a dash and the length of a gap between dashes.  When the end
of the array is reached, the reading of the array wraps around to the
beginning.  If the array is empty, i.e., @var{n} equals zero, there is
no dashing: the drawn line is solid.

The @var{offset} argument specifies the `phase' of the dash pattern
relative to the start of the path.  It is interpreted as the distance
into the dash pattern at which the dashing should begin.  For example,
if @var{offset} equals zero then the path will begin with a dash, of
length @var{dashes}[0] in user space.  @w{If @var{offset}} equals
@var{dashes}[0] then the path will begin with a gap of length
@var{dashes}[1], and @w{so forth}.  @var{offset} is allowed to be
negative.

Not all Plotters fully support @t{linedash} and @t{flinedash}.  HP-GL
and PCL Plotters cannot dash with a nonzero offset, and in the dash
patterns used by @w{X and} @w{X Drawable} Plotters, each dash and each
gap has a maximum length of 255 pixels.  @t{linedash} and @t{flinedash}
have no effect on Tektronix and Fig Plotters, and they have no effect on
HP-GL Plotters for which the parameter @code{HPGL_VERSION} is less
@w{than "2"} (the default; see @ref{Driver Parameters}).

@strong{Warning}: If the map from the user coordinate system to the
device coordinate system is not uniform, each dash in a dashed path
should ideally be drawn on the graphics display with a length that
depends on its direction.  But currently, only Postscript Plotters @w{do
this}.  Other Plotters always draw any specified dash with the same
length, irrespective of its direction.  The length that is used is the
minimum length, in the device coordinate system, that can correspond to
the specified dash length in the user coordinate system.

@item int @t{linemod} (const char *@var{s});
@t{linemod} sets the line style for all paths, circles, and ellipses
subsequently drawn on the graphics display.  The supported line styles
are "solid", "dotted", "dotdashed", "shortdashed", "longdashed",
"dotdotdashed", "dotdotdotdashed", and "disconnected".  The first seven
correspond to the following dash patterns:

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

@noindent
@w{In the} preceding patterns, each hyphen stands for one line
thickness.  This is the case for sufficiently thick lines, @w{at least}.
@w{So for} sufficiently thick lines, the distance over which a dash
pattern repeats is scaled proportionately to the line thickness.

The "disconnected" line style is special.  A "disconnected" path is
rendered as a set of filled circles, each of which has diameter equal to
the nominal line thickness.  One of these circles is centered on each of
the juncture points of the path (i.e., the endpoints of the line
segments or arcs from which it is constructed).  Circles and ellipses
with "disconnected" line style are invisible.  Disconnected paths,
circles, and ellipses are not filled.

All line styles are supported by all Plotters, with the following
exceptions.  HP-GL Plotters do not support the "dotdotdotdashed" style
unless the parameter @code{HPGL_VERSION} is set to "2" (the default).
Tektronix Plotters do not support the "dotdotdotdashed" style, and do
not support the "dotdotdashed" style unless the parameter @code{TERM} is
set to "kermit".  @xref{Driver Parameters}.

@item int @t{linewidth} (int @var{size});
@itemx int @t{flinewidth} (double @var{size});
@t{linewidth} and @t{flinewidth} set the thickness, in the user
coordinate system, of all paths, circles, and ellipses subsequently
drawn on the graphics display.  @w{A negative} value resets the
thickness to the default.  The default thickness depends on the type of
Plotter.  For most Plotters, it is 1/850 times the size (i.e., minimum
dimension) of the display.  But for Plotters that produce bitmaps, i.e.,
@w{X Plotters}, @w{X Drawable} Plotters, PNM Plotters, and GIF Plotters,
@w{it is} zero.

By convention, a zero-thickness line is the thinnest line that can be
drawn.  However, the drawing editors @code{idraw} and @code{xfig} treat
zero-thickness lines as invisible.  @w{So when} producing editable
graphics with a Postscript or Fig Plotter, using a zero line thickness
may not be desirable.

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

@strong{Warning}: If the map from the user coordinate system to the
device coordinate system is not uniform, each line segment in a
polygonal path should ideally be drawn on the graphics display with a
thickness that depends on its direction.  But currently, only Postscript
Plotters @w{do this}.  Other Plotters draw all line segments in a path
with the same thickness.  The thickness that is used is the minimum
thickness, in the device coordinate system, that can correspond to the
thickness of the path in the user coordinate system.

@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 a point to which the graphics cursor should be
moved.  The path under construction @w{(if any)} is ended, and the
graphics cursor is moved to (@var{x}, @var{y}).  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{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.

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

@item int @t{pencolorname} (const 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, see @ref{Color Names}.  Unrecognized colors are
interpreted as "black".

HP-GL Plotters support drawing with a white pen only if the value of the
parameter @code{HPGL_VERSION} @w{is "2"} (the default) and the value of
the parameter @code{HPGL_OPAQUE_MODE} is "yes" (the default).
@xref{Driver Parameters}.

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

@item int @t{savestate} ();
@t{savestate} pushes the current graphics context onto the stack of
drawing states.  The graphics context consists largely of
@code{libplot}'s drawing attributes, which are set by the attribute
functions documented in this section.  @w{A path} under construction,
@w{if any}, is regarded as part of the graphics context.  That is
because paths may be drawn incrementally, one line segment or arc at a
time.  When a graphics context is returned to, the path under
construction 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 coordinate system, for text strings subsequently drawn on the
graphics display.  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.
@end table

@node Mapping Functions, , Attribute Functions, Functions
@subsection Mapping functions

The following are the ``mapping functions'' in @code{libplot}.  When
invoked on a Plotter, these functions affect the affine transformation
it employs for mapping from the user coordinate system to the device
coordinate system.  They may be viewed as performing transformations of
the user coordinate system.  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}.

In the C binding, the names of all functions should be preceded by
"pl_", unless the header file @code{plotcompat.h} is included.  @xref{C
Compiling and Linking}.  @w{In the} C++ binding, these are member
functions of the @code{Plotter} class and its subclasses.

@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 @w{@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 Driver Parameters, , Functions, libplot
@section Device driver parameters

In designing the @code{libplot} library, every effort was made to make
the Plotter interface independent of the type of Plotter.  @w{To the}
extent that device dependence exists, @w{it is} captured by a manageable
number of @emph{device driver parameters}.

In the @w{C binding}, @w{a value} for any parameter may be specified by
calling the @code{pl_parampl} function.  The @code{pl_parampl} function
does not operate on any particular Plotter: @w{it belongs} to the @w{C
binding} as a whole.  The parameter values used by any Plotter are
constant over the lifetime of the Plotter, and are those that were in
effect when the Plotter was created.  Each driver parameter has a value
that is allowed to be a generic pointer (@w{a @code{void *}}).  For most
parameters, this value should be a string (@w{a @code{char *}}).
@code{pl_parampl} may be called any number of times.  @w{A parameter}
may be unset by calling @code{pl_parampl} with a value argument of
NULL@.

If at Plotter creation time a parameter is @emph{not} set, its default
value will be used, unless the parameter is string-valued and there is
an environment variable of the same name, in which case the value of
that environment variable will be used.  This rule increases run-time
flexibility: @w{an application} programmer may allow non-critical driver
parameters to be specified by the user via environment variables.

In the C++ binding, the function @code{Plotter::parampl} is the analogue
of @code{pl_parampl}.  @w{It is} a static member of the @code{Plotter}
class and its subclasses.  Like @code{pl_parampl}, @w{it does} not act
on any particular Plotter: rather, it sets the parameters of
subsequently created Plotters.

The following are the currently recognized parameters (unrecognized ones
are ignored).  The most important ones are @code{DISPLAY}, which affects
@w{X Plotters}, @code{BITMAPSIZE}, which affects @w{X Plotters}, PNM
Plotters, and GIF Plotters, and @code{PAGESIZE}, which affects
Illustrator, Postscript, Fig, and HP-GL Plotters.  These three
parameters are listed first and the others alphabetically.  Many of the
parameters, such as the several whose names begin with "HPGL", affect
only a single type of Plotter.

@table @code
@item @t{DISPLAY}
(Default NULL@.)  The @w{X Window} System display on which the graphics
display will be @w{popped up}, as an @w{X window}.  This is relevant
only to @w{X Plotters}.

@item BITMAPSIZE
(Default "570x570".)  The size of the graphics display in terms of
pixels.  This is relevant only to @w{X Plotters}, PNM Plotters, and GIF
Plotters.  For @w{X Plotters}, the value of this parameter will
automatically, if it is not set, be taken from the @w{X resource}
@code{Xplot.geometry}.  This is for backward compatibility.

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

For Illustrator and Postscript Plotters, the graphics display will be a
square region centered on the specified page and occupying its full
width, with allowance being made for margins.  For Fig Plotters, the
graphics display will be a square region of the same size, positioned in
the upper left corner of an @code{xfig} display.  For PCL and HP-GL
Plotters, the graphics display will be a square region of the same size,
but may be positioned differently.  For PCL Plotters, fine control over
its positioning on the page may be accomplished by setting the
@code{PCL_XOFFSET} and @code{PCL_YOFFSET} parameters.  For HP-GL
Plotters, @code{HPGL_XOFFSET} and @code{HPGL_YOFFSET} are used
similarly.

@item BG_COLOR
(Default "white".)  The initial background color of the graphics
display, when drawing each page of graphics.  This is relevant to @w{X
Plotters}, PNM Plotters, GIF Plotters, and @w{X Drawable Plotters} (for
the last, the background color @w{shows up} only if @code{erase} is
invoked).  The background color may be changed at any later time by
invoking the @t{bgcolor} (or @t{bgcolorname}) and @t{erase} operations.
An unrecognized color name sets the background color to the default.
For information on what names are recognized, see @ref{Color Names}.

@item GIF_ANIMATION
(Default "yes".)  Relevant only to GIF Plotters.  "yes" means that the
@code{erase} operation will have special semantics: with the exception
of its first invocation, it will act as a separator between successive
images in the written-out pseudo-GIF file.  @w{"no" means} that
@code{erase} should act as it does on other Plotters that do not write
graphics in real time, i.e., @w{it should} erase the image under
construction by filling it with the background color.  @w{If "no"} is
specified, the pseudo-GIF file will contain only a single image.

@item GIF_DELAY
(Default "0".)  Relevant only to GIF Plotters.  The delay, in hundredths
of a second, after each image in a written-out animated pseudo-GIF file.
The value should be an integer in the range "0"@dots{}"65535".

@item GIF_ITERATIONS
(Default "0".)  Relevant only to GIF Plotters.  The number of times that
an animated pseudo-GIF file should be `looped'.  The value should be an
integer in the range "0"@dots{}"65535".

@item HPGL_ASSIGN_COLORS
(Default "no".)  Relevant only to HP-GL Plotters, and only if the value
of @code{HPGL_VERSION} @w{is "2"}.  @w{"no" means} to draw with a fixed
set of pens, specified by setting the @code{HPGL_PENS} parameter.  "yes"
means that pen colors will not restricted to the palette specified in
@code{HPGL_PENS}: colors will be assigned to ``logical pens'' in the
range #1@dots{}#31, @w{as needed}.  Other than color LaserJet printers
and DesignJet plotters, not many HP-GL/2 devices allow the assignment of
colors to logical pens.  @w{So this} parameter should be used with
caution.

@item HPGL_OPAQUE_MODE
(Default "yes".)  Relevant only to HP-GL Plotters, and only if the value
of @code{HPGL_VERSION} @w{is "2"}.  "yes" means that the HP-GL/2 output
device should be switched into opaque mode, rather than transparent
mode.  This allows objects to be filled with opaque white and other
opaque colors.  @w{It also} allows the drawing of visible white lines,
which by convention are drawn with @w{pen #0}.  Not all HP-GL/2 devices
support opaque mode or the use of @w{pen #0} to draw visible white
lines.  In particular, HP-GL/2 pen plotters @w{do not}.  Some older
HP-GL/2 devices reportedly malfunction if asked to switch into opaque
mode.  @w{If the} output of an HP-GL Plotter is to be sent to such a
device, @w{a "no"} value is recommended.

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

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

@item HPGL_VERSION
(Default "2".)  Relevant only to HP-GL Plotters.  @w{"1" means} that the
output should be generic HP-GL, @w{"1.5" means} that the output should
be suitable for the HP7550A graphics plotter and the HP758x, HP7595A and
HP7596A drafting plotters (HP-GL with some HP-GL/2 extensions), and
@w{"2" means} that the output should be modern HP-GL/2.  @w{If the}
version is less than "2" then the only available fonts will be vector
fonts, and all paths will be drawn with a default thickness, so that
invoking @t{capmod}, @t{joinmod}, and @t{fmiterlimit} will have no
effect.  Also, the `nonzero winding number rule' will not be supported
when filling paths, so invoking @t{fillmod} will have no effect.
Additionally, if the version @w{is "1"} then the filling of arbitrary
paths will not be supported (circles and rectangles aligned with the
coordinate axes may be filled, however).

@item HPGL_XOFFSET, HPGL_YOFFSET
(Defaults "0.0cm" and "0.0cm".)  Relevant only to HP-GL Plotters.
Adjustments, in the @w{@math{x} and @math{y}} directions, of the
position of the graphics display on the page.  They may be specified in
centimeters, millimeters, or inches.  For example, an offset could be
specified as "2cm" @w{or "1.2in"}.

@item INTERLACE
(Default "no".)  Relevant only to GIF Plotters.  If the value is "yes",
the pseudo-GIF output file will be interlaced.  That means that it will
be displayed in an interlaced (nonlinear) way by many applications.

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

This parameter is relevant to all Plotters except Tektronix and Metafile
Plotters.  The reason for splitting long paths is that some display
devices (e.g., old Postscript printers and HP-GL pen plotters) have
limited buffer sizes.  @w{It is} not relevant to Tektronix or Metafile
Plotters, since they draw paths in real time and have no buffer
limitations.

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

@item PCL_ASSIGN_COLORS
(Default "no".)  Relevant only to PCL Plotters.  @w{"no" means} to draw
with a fixed set of pens.  "yes" means that pen colors will not
restricted to this palette: colors will be assigned to ``logical pens'',
@w{as needed}.  Other than color LaserJet printers, not many @w{PCL 5}
devices allow the assignment of colors to logical pens.  @w{So this}
parameter should be used with caution.

@item PCL_BEZIERS
(Default "yes".)  Relevant only to PCL Plotters.  @w{"yes" means} that
when drawing Bezier curves, the special `Bezier instructions' will be
used.  @w{"no" means} that these instructions will not be used.
Instead, each Bezier curve will be approximated and drawn as a polygonal
line.  Other than the LaserJet III, which was Hewlett--Packard's first
@w{PCL 5} printer, all Hewlett--Packard's @w{PCL 5} printers support the
Bezier instructions.

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

@item PCL_XOFFSET, PCL_YOFFSET
(Defaults "0.0cm" and "0.0cm".)  Relevant only to PCL Plotters.
Adjustments, in the @w{@math{x} and @math{y}} directions, of the
position of the graphics display on the page.  They may be specified in
centimeters, millimeters, or inches.  For example, an offset could be
specified as "2cm" @w{or "1.2in"}.

@item PNM_PORTABLE
(Default "no".)  Relevant only to PNM Plotters.  "yes" means that the
output should be in a portable (human-readable) version of PBM/PGM/PPM
format, rather than the default (binary) version.  `Portable' is
something of a misnomer, since binary PBM/PGM/PPM files are also
portable, in the sense that they are machine-independent.

@item TERM
(Default NULL@.)  Relevant only to Tektronix Plotters.  If the value is
"xterm", "xterms", or "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 drawing graphics, a Tektronix
Plotter will emit an escape sequence that causes the terminal emulator's
auxiliary Tektronix window, which is normally hidden, to @w{pop up}.
After the graphics are drawn, an escape sequence that returns control to
the original VT100 window will be emitted.  The Tektronix window will
remain on the screen.

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

@item TRANSPARENT_COLOR
(Default "none".)  Relevant only to GIF Plotters.  If the value is a
recognized color name, that color, if it appears in the pseudo-GIF
output file, will be treated as transparent by most applications that
display GIF files.  For information on what names are recognized, see
@ref{Color Names}.

If @code{TRANSPARENT_COLOR} is set and an animated pseudo-GIF file is
produced, the `restore to background' disposal method will be used for
each image in the file.  Otherwise, the `unspecified' disposal method
will be used.

@item USE_DOUBLE_BUFFERING
(Default "no".)  Relevant only to X Plotters and X Drawable Plotters.
@w{If the} value is "yes", a double buffering scheme will be used when
drawing graphics.  Each frame of graphics, within a
@t{openpl}@dots{}@t{closepl} pair, will be written to an off-screen
buffer rather than to the Plotter's display.  When @t{erase} is invoked
to end a frame, or when @t{closepl} is invoked, the contents of the
off-screen buffer will be copied to the Plotter's display, pixel by
pixel.  If successive frames differ only slightly, this will create the
illusion of smooth animation.

Some X displays provide special hardware support for double buffering.
@w{If this} support is available, the @w{X Plotter} will detect its
presence, and will draw graphics using the appropriate extension to the
X11 protocol (either DBE or MBX).  In this case the animation will be
significantly faster; on high-end graphics hardware, @w{at least}.

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

@item XDRAWABLE_COLORMAP
(Default NULL@.)  Relevant only to @w{X Drawable Plotters}.  If the
value is non-NULL, it should be a @code{Colormap *}, @w{a pointer} to a
colormap from which colors should be allocated.  NULL indicates that the
colormap to be used should be the default colormap of the default screen
of the @w{X display}.

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

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

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

@node Appendices, , libplot, Top
@ifnottex
The following appendices contain miscellaneous information on the
GNU plotting utilities.
@end ifnottex

@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} vector graphics library and applications built @w{on
it}, such as @code{graph} and @code{plot}, can draw text strings in a
wide variety of fonts.  Text strings may include characters from more
than one font in a typeface, and may include superscripts, subscripts,
and square roots.  @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
* Cyrillic and Japanese::  The Cyrillic and Japanese fonts
* Text Fonts in X::     Available text fonts in the X Window System
* Text String Format::  Text string formatting (with escape sequences)
* Marker Symbols::      Available marker symbols
@end menu

@node Text Fonts, Cyrillic and Japanese, Text and Markers, Text and Markers
@appendixsection Available text fonts

The @code{libplot} library and applications built on it, such as
@code{graph}, @code{plot}, @code{tek2plot}, and @code{pic2plot}, can use
many fonts.  These include 22 Hershey vector fonts, 35 Postscript fonts,
45 @w{PCL 5} fonts, and 18 Hewlett--Packard vector fonts.  @w{We call}
these 120 supported fonts the `built-in' fonts.  The Hershey fonts are
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 outline fonts
resident in all modern Postscript printers, and the 45 @w{PCL 5} fonts
are the outline fonts resident in modern Hewlett--Packard LaserJet
printers and plotters.  (The old LaserJet III, which was
Hewlett--Packard's first @w{PCL 5} printer, supported only 8 of @w{the
45}.)  The 18 Hewlett--Packard vector fonts are fonts that are resident
in Hewlett--Packard printers and plotters (mostly the latter).

The Hershey fonts can be used by all types of Plotter supported by
@code{libplot}, and the Postscript fonts can be used by X, Illustrator,
Postscript, and Fig Plotters.  So, for example, all variants of
@code{graph} can use the Hershey fonts, and @code{graph -T X},
@code{graph -T ai}, @code{graph -T ps} and @code{graph -T fig} can use
the Postscript fonts.  The @w{PCL 5} fonts can be used by by
Illustrator, PCL, and HP-GL Plotters, and by @code{graph -T ai},
@code{graph -T pcl}, and @code{graph -T hpgl}.  The Hewlett--Packard
vector fonts can be used by by PCL and HP-GL Plotters, and by
@code{graph -T pcl} and @code{graph -T hpgl}.  @w{X Plotters} and
@code{graph @w{-T X}} are not restricted to the built-in Hershey and
Postscript fonts.  They can use any @w{X Window} System font.

The @code{plotfont} utility, which accepts the @samp{-T} option, will
print a character map of any font that is available in the specified
output format.  @xref{plotfont}.

For the purpose of plotting text strings (see @ref{Text String Format}),
the 120 built-in fonts are divided into typefaces.  As you can see from
the following 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.

The 22 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 HersheyCyrillic-Oblique
@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 HersheyGothicEnglish
@item HersheyGothicGerman
@item HersheyGothicItalian

@item HersheySerifSymbol
@enumerate
@item HersheySerifSymbol
@item HersheySerifSymbol-Oblique
@item HersheySerifSymbol-Bold
@item HersheySerifSymbol-BoldOblique
@end enumerate

@item HersheySansSymbol
@enumerate
@item HersheySansSymbol
@item HersheySansSymbol-Oblique
@end enumerate
@end itemize

@noindent
Nearly all Hershey fonts except the Symbol fonts use the ISO-Latin-1
encoding, which is a superset of ASCII@.  The Symbol fonts consist of
Greek characters and mathematical symbols, and use the symbol font
encoding documented in the @cite{Postscript Language Reference Manual}.
By convention, each Hershey typeface contains a symbol font
(HersheySerifSymbol or HersheySansSymbol, as appropriate) as @w{font
#0}.

HersheyCyrillic, HersheyCyrillic-Oblique, and HersheyEUC (which is a
Japanese font) are the only non-Symbol Hershey fonts that do not use the
ISO-Latin-1 encoding.  For their encodings, see @ref{Cyrillic and
Japanese}.

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
All Postscript fonts except the ZapfDingbats and Symbol fonts use the
ISO-Latin-1 encoding.  The encodings used by the ZapfDingbats and Symbol
fonts are documented in the @cite{Postscript Language Reference Manual}.
By convention, each Postscript typeface contains the Symbol font as
@w{font #0}.

The 45 @w{PCL 5} fonts are divided into typefaces as follows.

@itemize @bullet
@item Univers

@enumerate
@item   Univers
@item   Univers-Oblique
@item   Univers-Bold
@item   Univers-BoldOblique
@end enumerate

@item UniversCondensed

@enumerate
@item   UniversCondensed
@item   UniversCondensed-Oblique
@item   UniversCondensed-Bold
@item   UniversCondensed-BoldOblique
@end enumerate

@item   CGTimes

@enumerate
@item   CGTimes-Roman
@item   CGTimes-Italic
@item   CGTimes-Bold
@item   CGTimes-BoldItalic
@end enumerate

@item Albertus

@enumerate
@item   AlbertusMedium
@item   AlbertusMedium
@item   AlbertusExtraBold
@item   AlbertusExtraBold
@end enumerate

@item AntiqueOlive

@enumerate
@item AntiqueOlive
@item AntiqueOlive-Italic
@item AntiqueOlive-Bold
@end enumerate

@item   Arial

@enumerate
@item   Arial-Roman
@item   Arial-Italic
@item   Arial-Bold
@item   Arial-BoldItalic
@end enumerate

@item   ClarendonCondensed
@item   Coronet
@item Courier

@enumerate
@item   Courier
@item   Courier-Italic
@item   Courier-Bold
@item   Courier-BoldItalic
@end enumerate

@item Garamond

@enumerate
@item   Garamond
@item   Garamond-Italic
@item   Garamond-Bold
@item   Garamond-BoldItalic
@end enumerate

@item LetterGothic

@enumerate
@item   LetterGothic-Roman
@item   LetterGothic-Italic
@item   LetterGothic-Bold
@item   LetterGothic-BoldItalic
@end enumerate

@item   Marigold
@item CGOmega

@enumerate
@item   CGOmega-Roman
@item   CGOmega-Italic
@item   CGOmega-Bold
@item   CGOmega-BoldItalic
@end enumerate

@item TimesNewRoman

@enumerate
@item   TimesNewRoman
@item   TimesNewRoman-Italic
@item   TimesNewRoman-Bold
@item   TimesNewRoman-BoldItalic
@end enumerate

@item   Wingdings
@item   Symbol
@end itemize

@noindent
All PCL 5 fonts except the Wingdings and Symbol fonts use the
ISO-Latin-1 encoding.  The encoding used by the Symbol font is the
symbol font encoding documented in the @cite{Postscript Language
Reference Manual}.  By convention, each PCL typeface contains the Symbol
font as @w{font #0}.

The 18 Hewlett--Packard vector fonts are divided into typefaces as
follows.

@itemize @bullet
@item Arc

@enumerate
@item   Arc
@item   Arc-Oblique
@item   Arc-Bold
@item   Arc-BoldOblique
@end enumerate

@item Stick

@enumerate
@item   Stick
@item   Stick-Oblique
@item   Stick-Bold
@item   Stick-BoldOblique
@end enumerate

@item ArcANK

@enumerate
@item   ArcANK*
@item   ArcANK-Oblique*
@item   ArcANK-Bold*
@item   ArcANK-BoldOblique*
@end enumerate

@item StickANK

@enumerate
@item   StickANK*
@item   StickANK-Oblique*
@item   StickANK-Bold*
@item   StickANK-BoldOblique*
@end enumerate

@item ArcSymbol*

@item StickSymbol*

@end itemize

@noindent 
The Hewlett--Packard vector fonts with an asterisk (the ANK and Symbol
fonts) are only available when producing HP-GL output for the HP7550A
graphics plotter and the HP758x, HP7595A and HP7596A drafting plotters.
The ANK fonts are Japanese fonts (@pxref{Cyrillic and Japanese}), and
the Symbol fonts contain a few miscellaneous mathematical symbols.
@w{To ensure} that these fonts are available, you must set the
environment variable or driver parameter @code{HPGL_VERSION} @w{to "1.5"}.

All Hewlett--Packard vector fonts except the ANK and Symbol fonts use
the ISO-Latin-1 encoding.  The Arc fonts are proportional
(variable-width) fonts, and the Stick fonts are fixed-width fonts.  If
@code{HPGL_VERSION} is "1.5" then the Arc fonts will be kerned.  But if
@code{HPGL_VERSION} is "2" (the default), there will be no kerning.
Apparently Hewlett--Packard dropped support for device-resident kerning
tables when moving from HP-GL to modern HP-GL/2 and @w{PCL 5}.  For
information about Hewlett--Packard vector fonts and the way in which
they are kerned (@w{in pen} plotters, @w{at least}), see the article by
@w{L@. W@.} Hennessee @w{et al@.} in the Nov.@: 1981 issue of the
@cite{Hewlett--Packard Journal}.

To what extent do the fonts supported by @code{libplot} contain
ligatures?  The Postscript fonts, the @w{PCL 5} fonts, and the
Hewlett--Packard vector fonts, @w{at least} as implemented in
@code{libplot}, @w{do not} contain ligatures.  However, six of the 22
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 the two HersheyCyrillic
fonts 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 HersheyGothicGerman.
The German double-s @w{character `@ss{}'}, which is called an `eszet',
is not treated as a ligature in any font.  @w{To obtain} an eszet, you
must either request one with the escape @w{sequence "\ss"} (@pxref{Text
String Format}), or, if you have an 8-bit keyboard, type an eszet
explicitly.

@node Cyrillic and Japanese, Text Fonts in X, Text Fonts, Text and Markers
@appendixsection Cyrillic and Japanese fonts

The built-in fonts discussed in the previous section include Cyrillic
and Japanese vector fonts.  This section explains how these fonts are
encoded, i.e., how their character maps are @w{laid out}.  You may use
the @code{plotfont} utility to display the character map for any font,
including the Cyrillic and Japanese vector fonts.  @xref{plotfont}.

The HersheyCyrillic and HersheyCyrillic-Oblique fonts use an encoding
called @w{KOI8-R}, a superset of ASCII that has become the @w{de facto}
standard for Unix and networking applications in the former Soviet
Union.  Insofar as printable ASCII characters go, they resemble the
HersheySerif vector font.  But their upper halves 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 the encoding scheme, see
@uref{http://www.nagual.pp.ru/~ache/koi8.html, the official KOI8-R Web
page} and Internet RFC 1489, which is available from the
@uref{http://www.isi.edu, Information Sciences Institute}.

The HersheyEUC font is a vector font that is is used for displaying
Japanese text.  It uses the 8-bit EUC-JP encoding.  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 explained in Ken Lunde's
@cite{Understanding Japanese Information Processing} (O'Reilly, 1993),
which contains much additional information on Japanese text processing.
See also @uref{http://www.ora.com/people/authors/lunde/cjk_inf.html, his
on-line supplement}.

In the HersheyEUC font, characters in the printable ASCII range,
@t{0x20}@dots{}@t{0x7e}, are similar to HersheySerif (their encoding is
`JIS Roman', an ASCII variant standardized by the Japanese Industrial
Standards Committee).  Also, 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{0x2473}.  @w{To
obtain} the EUC code for any JIS X0208 character, you would add
@code{0x80} to each byte (i.e., `set the high bit' on each byte).  @w{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 83 Hiragana and 86 Katakana are available, though the
little-used `half-width Katakana' are not supported.  Also, 603 Kanji
are available, including 596 of the 2965 JIS @w{Level 1} (i.e.,
frequently used) Kanji.  The Hiragana, the Katakana, and the available
Kanji all have the same width.  The file @file{kanji.doc}, which on most
systems is installed in @file{/usr/share/libplot} or
@file{/usr/local/share/libplot}, lists the 603 available Kanji.  Each
JIS X0208 character that is unavailable will be drawn as an `undefined
character' glyph (@w{a bundle} of horizontal lines).

The eight Hewlett--Packard vector fonts in the ArcANK and StickANK
typefaces are also used for displaying Japanese text.  They are
available when producing HP-GL output for the HP7550A graphics plotter
and the HP758x, HP7595A and HP7596A drafting plotters.  @w{To ensure}
that they are available, you must set the environment variable or driver
parameter @code{HPGL_VERSION} @w{to "1.5"}.

ANK stands for Alphabet, Numerals, and Katakana.  The ANK fonts use the
`Kana-8' encoding.  The lower half of each font uses the JIS Roman
encoding, and the upper half contains half-width Katakana.  Half-width
Katakana are simplified Katakana that may need to be equipped with
diacritical marks.  The diacritical marks are included in the encoding,
as separate characters.

@node Text Fonts in X, Text String Format, Cyrillic and Japanese, Text and Markers
@appendixsection Available text fonts for the X Window System

The plotting utilities @code{graph @w{-T X}}, @code{plot @w{-T X}},
@code{tek2plot @w{-T X}}, @code{pic2plot @w{-T X}}, and @code{plotfont
@w{-T X}}, and the @code{libplot} library that they are @w{built on},
can draw text on an @w{X Window} System display in a wide variety of
fonts.  This includes the 22 built-in Hershey vector fonts.  They can
use the 35 built-in Postscript fonts too, if those fonts are available
on the @w{X display}.  Most releases of the plotting utilities include
freely distributable versions of the 35 Postscript fonts, in @w{Type 1}
format, that are easily installed on any @w{X display}.

In fact, the plotting utilities can use most fonts that are available on
the current @w{X display}.  This includes all scalable fonts that have a
so-called XLFD (@w{X Logical} Font Description) name.  For example, the
"CharterBT-Roman" font is available on many @w{X displays}.  It has a
formal XLFD name, namely
"-bitstream-charter-medium-r-normal--0-0-0-0-p-0-iso8859-1".  The
plotting utilities would refer to it as "charter-medium-r-normal".  The
command

@example
echo 0 0 1 1 2 0 | graph -T X -F charter-medium-r-normal
@end example

@noindent
would draw a plot in a popped-up @w{X window}, 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 can be used by @code{libplot}'s @w{X Plotters}
and by the plotting utilities that are built on @code{libplot}.  The two
sorts of font are variable-width and fixed-width fonts, respectively.
Fonts whose names end in "iso8859-2", etc., and "adobe-fontspecific",
may also be used, even though they do not employ the standard
ISO-Latin-1 encoding.

The escape sequences that provide access to the non-ASCII `8-bit'
characters in the built-in ISO-Latin-1 fonts may be employed when using
any ISO-Latin-1 @w{X Window} System font.  For more on escape sequences,
see @ref{Text String Format}.  As an example, "\Po" will yield the
British pounds sterling @w{symbol `@pounds{}'}.  The command

@example
echo 0 0 1 1 | graph -T X -F charter-medium-r-normal -L "A \Po1 Plot"
@end example

@noindent
shows how this symbol could be used in a graph label.  In the same way,
the escape sequences that provide access to mathematical symbols and
Greek characters may be employed when using any @w{X Window} System
font, whether or not it is an ISO-Latin-1 font.

The plotting utilities, including @code{graph}, support a
@code{--bitmap-size} option.  @w{It is} meaningful only if the
@samp{@w{-T X}} option is used, since it sets the size of the popped-up
@w{X Window}.  You may use it to obtain some interesting visual effects.
Each of the plotting utilities assumes that it is drawing in a square
region, so if you use the @samp{--bitmap-size 800x400} option, your plot
will be scaled anisotropically, by a larger factor in the horizontal
direction than in the vertical direction.  The fonts in the plot will be
scaled in the same way.  Actually, this requires a modern (X11R6)
display.  @w{If your} @w{X display} cannot scale a font, @w{a default}
scalable font (@w{such as} "HersheySerif") will be substituted.

@node Text String Format, Marker Symbols, Text Fonts in X, 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}, @code{plot}, @code{tek2plot}, @code{pic2plot}, and
@code{plotfont}, which 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 and the latter is the printable `8-bit' range.

Text strings may, however, include embedded `escape sequences' that
shift the font, append subscripts or superscripts, or include non-ASCII
characters and mathematical symbols.  As a consequence, the axis labels
on a plot prepared with @code{graph} may include such features.  So may
the text strings that @code{pic2plot} uses to label objects.

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
additional characters.  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 @w{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 @w{switched to}.  For compatibility with @code{groff},
"\fR", "\fI", "\fB" are equivalent to "\f1", "\f2", "\f3", respectively.
"\fP" will switch the font to the previously used font (only one font is
remembered).  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
italic and non-italic fonts.  "\r1", "\r2", "\r4", "\r6", "\r8", and
"\r^" are escape sequences that shift right by 1 em, 1/2 em, 1/4 em, 1/6
em, 1/8 em, and 1/12 em, respectively.  "\l1", "\l2", "\l4", "\l6",
"\l8", and "\l^" are similar, but shift left instead of right.  
"A \fIvery\r^\fP well labeled axis" would look slightly better than 
"A \fIvery\fP 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\mk\rn\rn\rtab" would be plotted as `the square
root of ab'.  @w{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, "\mk\ul\ul\ul\rtabc" 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.
@w{For example}, if the "HersheySerif" font were used,
"\mk\ul\ul\l8\ul\rtabc" would yield a better underline than
"\mk\ul\ul\ul\rtabc".

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, the HersheyCyrillic fonts, HersheyEUC, and ZapfDingbats).
The useful non-ASCII characters include accented characters among
others.  Such `8-bit' characters, in the @t{0xa0}@dots{}@t{0xff} byte
range, may be included directly in a text string.  But if your terminal
does not permit this, you may use the escape sequences for them instead.

There are escape sequences for the mathematical symbols and Greek
characters in the symbol fonts, @w{as well}.  This is how the symbol
fonts are usually accessed.  Which symbol font the mathematical symbols
and Greek characters are taken from depends on whether your current font
is a Hershey font or a non-Hershey font.  They are taken from the
HersheySerifSymbol font or the HersheySansSymbol 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.  @w{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 HersheySerifSymbol or HersheySansSymbol (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, @w{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 "\eu"
[0360] euro
@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
or zodiacal.  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 HersheyGothicGerman.  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, including the signs
for the twelve constellations of the zodiac, 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
@item "\AR"
aries
@item "\TA"
taurus
@item "\GE"
gemini
@item "\CA"
cancer
@item "\LE"
leo
@item "\VI"
virgo
@item "\LI"
libra
@item "\SC"
scorpio
@item "\SG"
sagittarius
@item "\CP"
capricornus
@item "\AQ"
aquarius
@item "\PI"
pisces
@end table

The preceding miscellaneous and astronomical symbols are not the only
special non-font symbols that can be used if the current font is a
Hershey font.  The entire library of glyphs digitized by Allen Hershey
is built into GNU @code{libplot}.  @w{So text} strings may include any
Hershey glyph.  Each of the 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-lys, 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.  The file
@file{kanji.doc}, which is distributed along with the GNU plotting
utilities, lists the available Kanji.  @w{On most} systems it is
installed in @file{/usr/share/libplot} or
@file{/usr/local/share/libplot}.

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.  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
in the "\#J2321"@dots{}"\#J237e" range.  The file @file{kana.doc}, which
is installed in the same directory as @file{kanji.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
@uref{http://www.ora.com/people/authors/lunde/cjk_inf.html, his on-line
supplement}.

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]
appeared in 1997, but uses a different numbering.)  `Nelson' escape
sequences for Kanji are similar to JIS X0208 escape sequences, but use
four decimal instead of four hexadecimal digits.  The file
@file{kanji.doc} gives the correspondence between the JIS numbering
scheme and the Nelson numbering scheme.  @w{For example}, "\#N0001" is
equivalent to "\#J306c".  @w{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 (@w{a
bundle} of horizontal lines).  The same is true for non-Kanji JIS X0208
characters that are not available.

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

The GNU @code{libplot} library supports a standard 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
@w{symbol #0} means no symbol @w{at all}).

@enumerate
@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
@w{well known} GKS (Graphical Kernel System).

Symbols 32 and up are interpreted as characters in a certain text font.
For @code{libplot}, @w{it is} the current font.  For @code{graph}, @w{it
is} the font selected with the @samp{--symbol-font-name} option.  @w{By
default}, this is the ZapfDingbats font except in @code{graph -T pnm},
@code{graph -T gif}, @code{graph -T pcl}, @code{graph -T hpgl} and
@code{graph -T tek}.  These variants of @code{graph} normally have no
access to Postscript fonts, so they use the HersheySerif font instead.

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

@example
echo 0 0 1 2 2 1 3 2 4 0 | graph -T 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).

If you are using @code{graph -T pcl} or @code{graph -T hpgl} and wish to
use font characters as marker symbols, you should consider using the
Wingdings font, which is available when producing @w{PCL 5} or HP-GL/2
output.  Doing

@example
echo 0 0 1 2 2 1 3 2 4 0 | 
    graph -T pcl -m 0 --symbol-font Wingdings -S 181 0.1 > plot.pcl
@end example

@noindent
will produce a @w{PCL 5} plot that is similar to the preceding
Postscript plot.  The Wingdings font has the Texas star in location
#181.

@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
other graphics programs support the @samp{--pen-color} option, and they
all, including @code{graph} support the @samp{--bg-color} option.  The
@code{libplot} library, @w{on which} the graphics programs are based,
includes the @code{pencolorname}, @code{fillcolorname}, and
@code{bgcolorname} functions.

In any of these contexts, 665 distinct color names are recognized,
including obscure ones like "dark magenta", "forest green", and "olive
drab".  Color names are case-insensitive, and spaces are ignored.  So,
@w{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.  @w{On most}
systems it is installed in @file{/usr/share/libplot} or
@file{/usr/local/share/libplot}.  The color names are essentially those
recognized by recent releases 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.  @w{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

GNU graphics metafiles are produced by the raw variants of @code{graph},
@code{plot}, @code{pic2plot}, @code{tek2plot}, and @code{plotfont}, and
by any other graphics application that uses the Metafile Plotter support
contained in GNU @code{libplot}.  @w{A file} in this format is a sort of
audit trail: @w{a sequence} of plotting commands, each of which may be
followed by data.  Each plotting command is an @w{`op code'}: @w{a
single} ASCII character, indicating a Plotter operation.  The data
following the command are the arguments passed to the operation, @w{if
any}.

There are two sorts of GNU graphics metafile: binary (the default) and
portable (human-readable).  Binary metafiles begin with the magic string
@w{"#PLOT 1\n"}, and portable metafiles with the magic string 
@w{"#PLOT 2\n"}.  @w{If you} wish to transfer metafiles between machines
of different types, you should use portable rather than binary format.
Portable metafiles are produced by GNU @code{graph} and the other
plotting utilities if the @samp{-O} option is specified, and by Metafile
Plotters if the @code{META_PORTABLE} parameter is set to "yes".  Both
binary and portable metafiles can be translated to other formats by GNU
@code{plot}.

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

The @code{openpl} and @code{closepl} operations open and close a
Plotter, i.e., begin and end a page of graphics.  They are represented
by the @w{op codes} @w{@samp{o} and @samp{x}}, respectively.  The
@code{erase} operation, if present, separates frames within a page.  On
real-time display devices, @w{it is} interpreted as a screen erasure.
@w{It is} represented by the @w{op code @samp{e}}.

Each of the 89 other Plotter operations has a corresponding @w{op code},
with 12 exceptions.  These 12 exceptions are @w{(1) the} setup operation
@code{flushpl}, @w{(2) the} operations @code{havecap},
@code{labelwidth}, and @code{flabelwidth}, which merely return
information, @w{(3) the} @code{colorname}, @code{pencolorname},
@code{fillcolorname}, and @code{bgcolorname} operations, which are
internally mapped to @code{pencolor}, @code{fillcolor}, and
@code{bgcolor}, @w{(4) the} @code{frotate}, @code{fscale}, and
@code{ftranslate} operations, which are internally mapped to
@code{fconcat}, and @w{(5) the} @code{ffontname} operation, which in a
metafile would be indistinguishable from @code{fontname}.  @w{So
besides} @w{@samp{o} and @samp{x}}, there are 78 possible @w{op codes},
for a total @w{of 80}.  The following table lists 10 of the @w{op codes}
other than @w{@samp{o} and @samp{x}}, followed by the name of the
@code{libplot} operation they @w{stand for}.

@table @asis
@item Op Code
Operation
@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 full set of 80 @w{op codes} is listed in the header file
@file{plot.h}, which is distributed along with the plotting utilities.
@w{On most} systems it is installed in @file{/usr/include} or
@file{/usr/local/include}.

@w{It is} worth noting that of the 80 @w{op codes}, only 50 are used in
portable metafiles.  That is because in ASCII format, there is no point
in distinguishing the floating point @code{libplot} operations from
their integer counterparts.

The 10 op codes in the table above are actually the @w{op codes} of the
traditional `plot(5)' format produced by pre-GNU versions of
@code{graph} and @code{libplot}.  The use of these @w{op codes} make GNU
metafile format compatible with plot(5) format.  The absence of a magic
string, and of the @w{@samp{o} and @samp{x}} @w{op codes}, makes it
possible to distinguish files in plot(5) format from GNU metafiles.  GNU
@code{plot} can convert files in plot(5) format to GNU metafiles in
either binary or portable format.

@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.  @w{It may} be used to edit the output of @code{graph -T
ps}, or, in general, the output of any application that uses the
Postscript Plotter support contained in @code{libplot}.  

The current version of @code{idraw} is maintained by Vectaport, Inc.,
and is available at @uref{http://www.vectaport.com, their Web site}.
@w{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
@uref{ftp://interviews.stanford.edu, a distribution site} but is @w{no
longer} supported.  Retrieving the @code{ivtools} package instead is
recommended.

Also available at @uref{http://www.vectaport.com, Vectaport's Web site}
is an enhanced version of @code{idraw} called @code{drawtool}.
@code{drawtool} can import bitmapped graphics in TIFF and PBM/PGM/PPM
formats, @w{as well} as in the X11 bitmap format that @code{idraw} can
import.

@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.  @w{It may} be used to edit the output of @code{graph -T fig},
or, @w{in general} the output of any application that uses the 
Fig Plotter support contained in @code{libplot}.

The current version is available at
@uref{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.

There is @uref{http://duke.usask.ca/~macphed/soft/fig, a Web page on Fig
format}, which discusses application software packages that can
interoperate with @code{xfig}.

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

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

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

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

@code{libplot} now incorporates the @w{X Window} System code for filling
polygons and drawing wide polygonal lines and arcs.  This code is used
when producing output in bitmap formats (PNM and pseudo-GIF)@.  It was
written by Brian Kelleher, Joel McCormack, Todd Newman, Keith Packard,
Robert Scheifler and Ken Whaley, who worked for Digital Equipment Corp.,
MIT, and/or the @w{X Consortium}, and is copyright @copyright{} 1985--89
by the @w{X Consortium}.

The pseudo-GIF support now in @code{libplot} uses the `miGIF' run-length
encoding routines developed by 
@email{mouse@@rodents.montreal.qc.ca, der Maus} and 
@email{ivo@@hasc.com, ivo}, which are copyright @copyright{} 1998 
by @uref{http://www.hasc.com, Hutchison Avenue Software Corporation}.
The copyright notice and permission notice for the miGIF routines 
are distributed with the source code distribution of the plotting utilities.

Most development work on @code{ode} was performed by
@email{nbt@@reed.edu, Nick Tufillaro}
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, who deserves a vote of thanks.
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
@email{wolff@@inf.fu-berlin.de, Thomas Wolff} for Ghostscript.  The
interpolation algorithms used in @code{spline} are based on the
algorithms of @email{cline@@cs.utexas.edu, @w{Alan K.} Cline}, as
described in his papers in the Apr.@: 1974 issue of @cite{Communications
of the ACM}@.  The table-driven parser used in @code{tek2plot} was
written at Berkeley in the mid-1980's by @email{moy@@parc.xerox.com,
Edward Moy}.  The `sagitta' algorithm used in an extended form in
@code{libplot} for drawing circular and elliptic arcs was developed by
Peter Karnow of URW and @email{turk@@apple.com, Ken Turkowski} of Apple.
@email{toy@@rtp.ericsson.se, Raymond Toy}
helped with the tick mark
spacing code in @code{graph} and was the first to incorporate GNU
@code{getopt}.  Arthur Smith, formerly of LASSP at Cornell, provided
code for his @code{xplot} utility.  
@email{beebe@@math.utah.edu, Nelson Beebe}
exhaustively tested the package installation process.

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
