\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename epix
@settitle
@c $Id: epix.texi,v 1.1 2002/12/13 06:02:22 hwang Exp $
@c %**end of header

\documentclass[12pt]{article}
\usepackage{amsmath,latexsym,epic,eepic,pstcol}

\usepackage{makeidx}
\makeindex

@c \setlength{\topmargin}{0.5in}
\def\ePiX{\texttt{ePiX}}
\def\eepic{\texttt{eepic}}
\def\C{\texttt{C}}
\def\CXX{\texttt{C++}}
@c\renewcommand{\LaTeX}{{\rm LaTeX}} %% For latex2html

\def\bi{\begin{itemize}}
\def\ei{\end{itemize}}

\begin{document}

\begin{center}
{\Large \ePiX\ Tutorial} \\
Andrew D. Hwang \\
\texttt{ahwang@mathcs.holycross.edu} \\
Version 0.8.6, July 27, 2002
\end{center}

\tableofcontents

\section{Introduction}

\ePiX\ is a \LaTeX\ pre-processor that creates mathematically accurate
plots and line figures using easy-to-learn syntax. The user interface
is superficially that of \LaTeX\ itself: You prepare a short input
file and ``run \ePiX'' on this file, which produces a text file that
is included into a \LaTeX\ document.  Because the output is plain
text, the output can be edited manually if necessary. However, for
most visual tweaking it is easier and safer to change the source and
re-run \ePiX.

There are several reasons to use \ePiX. 
\begin{itemize}
\item Ease of use: \ePiX\ was written by a mathematician for
mathematicians. Figure objects are specified by simple, mnemonic
commands, as in \LaTeX. The learning curve is gentle: Using only
built-in primitives, you can duplicate almost everything @code{xfig}
can do, and do many things @code{xfig} cannot.

\item Quality of output: \ePiX\ creates publication-quality,
mathematically accurate figures whose appearance matches that of
\LaTeX. Paragraph-mode \LaTeX\ typography may be put in an \ePiX\
figure as easily as in an ordinary \LaTeX\ document; this is one of
the strongest advantages of \ePiX\ over plain Postscript, and indeed
one of \ePiX's distinguishing features.

\item Economy of storage and transmission: A compressed Postscript
file of this document is roughly 154~kb; a compressed tar file
containing the \eepic\ files is about 100~kb, and the \LaTeX\ and
\ePiX\ files alone compress to a little more than 74~kb.

Typical \emph{source}\/ files are roughly 20--50\% the size of the
\eepic\ file they generate, and the latter are smaller than the
Postscript they generate. However, some source files (vector fields
and fractals, for example) are considerably less than~1\% the size of
the generated \eepic\ file.  \ePiX\ is therefore a potentially
non-trivial form of compression for documents containing many
complicated figures.  The reason is, of course, that mathematical
figures tend to be structured, and the rules that specify them are
fairly short.

\item Flexibility: In \ePiX, you refer almost exclusively to Cartesian
coordinates, letting the software handle conversion to \LaTeX\ picture
coordinates. Resizing a printed figure or its Cartesian bounding box
is a matter of changing a couple of numbers and re-running \ePiX; you
needn't re-calculate or re-type the \LaTeX\ coordinates of all your
picture objects. ePiX's mechanism for placement of text in a figure is
easy, accurate, and robust under changes of scale.

\item Power: \ePiX\ retains the power of \CXX\ as a programming
language; variables, loops, and recursion can be used to draw
complicated plots and figures with just a few lines of input.
Objects' locations can be specified in terms of variables, allowing
you to rearrange or otherwise modify a figure by changing a few
numbers. Some applications are: plotting finite sums of functions
(e.g., Taylor and Fourier polynomials), generation of successive
``snapshots'' of a figure as parameters vary, or creation of
stereoscopic pairs.

\item It is \emph{Free Software},\index{Free software} in the senses
laid out by the Free Software Foundation: You are granted the right to
use the program for whatever purpose, and to inspect, modify, and
re-distribute the source code, so long as you do not restrict the
rights of others to do the same.\footnote{If you do not distribute
compiled versions of your changes, you are under no obligation to
publish their source code. Your intellectual property rights are
thereby preserved.} In short, the license is similar to the terms
under which theorems are published, rather than the way commercial
software is distributed. \ePiX\ also happens to be free (no-cost)
software.

\item Extensibility: The natural conclusion of these points is that
you can add new features to \ePiX\ to provide functionality suited to
your own needs. The author attempts to make the source code easy to
read and modify, and the program easy to extend.

\end{itemize}

A graphical interface is not planned, because it is impossible to
achieve the same accuracy as with an input file, and because graphical
menus do not encourage logical structuring of a figure. Output files
may be previewed with any dvi-capable previewer.

\subsection*{System Requirements}

In contrast to the previous section, which might be titled, ``Why to
use \ePiX'', this section might be called, ``Why not to use \ePiX'',
depending on your operating system and available 
software.\index{Installation!requirements}

Running \ePiX\ requires, in decreasing order of importance, a
\CXX~compiler,\index{Cplusplus@\CXX!compiler} GNU @code{bash} or a
similarly functional shell (``command line'') or scripting language,
and an operating system that supports output redirection. For creating
\ePiX\ input files, a text editor (such as @code{emacs} or
@code{vim}) that facilitates formatting \C~code is extremely
useful. To incorporate \ePiX\ figures in a document and preview the
result, you will of course need \LaTeX\ itself---particularly the
@code{epic}~and \eepic\ packages, but also the
@code{pstcol} or @code{color} packages for color output---and a
@code{dvi} or Postscript previewer. These components are standard
GNU\footnote{``GNU's Not Unix'', an operating system usually
distributed with the Linux kernel.} software, and should also be
available on most Unix mainframes. If not, speak to your sysadmin.

\subsection*{Typographical Conventions}

Shell commands, file names, and other text literals are in
@code{typewriter} font.  Inside an \ePiX\ source file, lines must be
typed exactly as shown, including (or omitting!) final semicolons and
{\tt"}double quotes{\tt"}.

\subsection*{Installing \ePiX}

\index{Installation|(}
\ePiX\ is distributed as source code. The latest version of \ePiX\ can
be found at
\begin{verbatim}
http://mathcs.holycross.edu/~ahwang/current/ePiX.html
\end{verbatim}
Unpack the gzip-ed tar file
\begin{verbatim}
tar -zxvf epix_src.tar.gz
\end{verbatim}
or, if your @code{tar} doesn't know about decompression,
\begin{verbatim}
gunzip epix_src.tar.gz
tar -xvf epix_src.tar
\end{verbatim}
@code{cd} to the source directory, which is named
@code{epix-0.8.x} for some small integer~@code{x}. The
@code{INSTALL} file contains detailed installation instructions. If
you're impatient, the short of it is
\begin{verbatim}
make clean
make test
make install
\end{verbatim}
Respectively, these steps remove any existing components (object
files, and the installed files @code{libepix.a}, @code{epix.h},
and @code{epix}); build the program and run a test compile on the
included sample files; and install the library, header file, and three
shell scripts.\index{ePiX@\ePiX!sample files}

\index{ePiX@\ePiX!contrib@\texttt{contrib}} There is an optional
package, kindly contributed by Svend Daug{\aa}rd Pedersen, that
supplies extensions for enhanced Cartesian coordinate systems, and for
hatching polygons and planar regions. His package is documented
separately, in the @code{contrib/} subdirectory of the source
package. To build this package, do
\begin{verbatim}
make contrib test
\end{verbatim}
instead of @code{make test}.

There is also a @code{legacy} subpackage that supports old-style
naming conventions. If you are upgrading, please see
page~\pageref{page:legacy} for information about
backward-compatibility. New documents should not use @code{legacy}
features.

By default, \ePiX\ installs in subdirectories of @code{/usr/local};
if you want to install elsewhere, see the @code{INSTALL} file for
detailed instructions. You may also want to consult
@code{POST-INSTALL} for information on setting your @code{PATH}
variable so your shell can find \ePiX.  \index{Installation|)}

An RPM @code{spec} file was kindly provided by Guido Gonzato. If you
run a GNU/Linux distribution that uses RPM~4.x to manage installed
packages (e.g., a recent version of Red Hat or Mandrake), you can
build and install \ePiX\ with the command (as @code{root})
\begin{verbatim}
rpm -ta epix_complete.tar.gz
\end{verbatim}
The author does not have access to a machine running RPM~4.x, so this
method of installation is not directly supported.

\ePiX\ is not a stand-alone program, but consists of a \C/@code{C++}
library, header, and a shell script, and therefore requires a
compiler\index{Cplusplus@\CXX!compiler} \emph{for normal use}. The GNU
compiler (@code{g++}) and \CXX\ library are strongly preferred, both
because they are used to develop \ePiX, and because they implement
many mathematical features not specified by @code{ANSI~C}.

Your life with \ePiX\ will be difficult unless the GNU shell
@code{bash} is available on your system.  If you have no idea what
this means, don't worry; most Unices (and all major GNU/Linux
distributions) have @code{bash} installed. The @code{INSTALL} file
has detailed instructions on coping with @code{bash} that is not in
@code{/bin/bash}. If you port \ePiX\ to another operating
environment, please send the author copies of your scripts for future
inclusion.~$\ddot\smile$

\index{Uninstalling}Should it come to this, the command @code{make
uninstall} will remove installed components of \ePiX\ from your
system. You must be in the source directory, and may need to log in as
@code{root}. 

\section{Getting Started}

\index{ePiX@\ePiX!implementation} An \ePiX\ source file is a short
\C/\CXX~program. Even if you speak~\CXX, you may want to skim this
section quickly, as it explains the basic format of an input
file. This section assumes you know nothing of~\C/\CXX, but that you
\emph{do}\/ know \LaTeX.

\subsection*{Coordinates and Dimensions}

\index{Scaling!aspect ratio|(} In creating a mathematical figure, you
generally want to depict a specific portion of the Cartesian plane,
and may want to control the aspect ratio of the figure, for reasons
including aesthetics and mathematical accuracy. In the \LaTeX\ picture
environment, locations are specified in terms of the current \LaTeX\
@code{unitlength}, measured from the lower left corner of the
\LaTeX\ picture box. There are at least three unfortunate consequences
of this design. First, the position of each object must be computed by
hand in a coordinate system that usually has little to do with the
figure.  Second, while a figure can be scaled easily by changing the
@code{unitlength}, it is impossible to change the aspect ratio of a
figure without manually changing the positions of each object. Third,
raw scaling can easily break a figure, because text does not
scale. Thus even changing the size of a \LaTeX\ figure can be
non-trivial.  \ePiX\ circumvents these problems; this is discussed at
more length in Section~\ref{section:reference}.

\index{ePiX@\ePiX!bounding box|(}
In order to draw a figure in \ePiX, you must provide the following
pieces of information: the @code{unitlength} in the figure, the size
of the printed figure in picture coordinates, and the Cartesian
coordinates of the figure's bounding box. \ePiX\ performs the
following affine scaling automatically:
\begin{center}
\input{scaling.eepic}
\end{center}

\noindent Changing the size, aspect ratio, or bounding box of a figure
is therefore trivial, and if the figure is well-designed\footnote{This
phrase applies mostly to positioning of typography in the figure.} it
will scale attractively. Objects may extend outside the bounding box,
but you generally have better control over figures that exactly fill
their bounding box. The entire figure may be offset,\index{Offset} as
in the \LaTeX\ picture environment; if unspecified the offset is
zero. In contrast to \LaTeX, positive offsets\index{Offset!positive}
in \ePiX\ shift the figure up and right.  
\index{ePiX@\ePiX!bounding box|)}

\subsection{A Simple Figure and \C/\CXX\ Tutorial}
\label{section:started}

Suppose we want to depict a rectangle inscribed in the upper unit
half-disk, say for an area maximization problem. The figure will
contain coordinate axes, the semi-circle, the inscribed rectangle, and
labels.  The first step is to decide on the bounding box. In this
example, $[-1,1]\times[0,1]$ is a reasonable choice.  If the figure is
to have true aspect ratio, the width will be twice the height. Next we
decide the true size of the figure (as mentioned already, it is easy
to change this later). A width of 2.5~in is reasonable, and the aspect
ratio forces the height to be 1.25~in.  \index{Scaling!aspect ratio|)}

The input file is shown in Figure~\ref{fig:example-basic-src}. The
format should be partially self-explanatory, but a line-by-line
explanation is given below.  A few things may not be self-explanatory:
\index{Cplusplus@\CXX!syntax!comment} The first line of input,
delimited by ``\verb+/*+''~and ``\verb+*/+'', is a comment. (A comment
begun with~\verb+/*+ may span several lines, but ends at the
\emph{next}\/ occurrance of~\verb+*/+. You should take care when
commenting a large portion of an existing file, lest the new comment
be terminated prematurely by an existing comment.) A single-line
comment, analogous to a \LaTeX\ line beginning with~\verb+%+, begins
with ``\verb+//+''.  \ePiX\ manipulates points and vectors using an
ordered pair data structure;\index{Pairs} the construct
@code{P(a,b)} creates the ordered pair~$(a,b)$. Finally, variables
in \CXX\ must have a declared
type,\index{Cplusplus@\CXX!variables!type} such as @code{int}
(integer), @code{double} (double-precision float), or @code{char}
(character).

\begin{figure}[hbt]
\begin{footnotesize}
\begin{verbatim}
/* semicirc.c -- A rectangle inscribed in a semi-circle */
#include "epix.h"

double width = 0.6;

main()
{
  unitlength("1in");
  bounding_box(P(-1, 0), P(1, 1));
  picture(P(2.5, 1.25));
  offset(P(0,0.125));

  begin();

  line(P(x_min, 0), P(x_max, 0));
  line(P(0, y_min), P(0, y_max));

  ellipse_top(P(0,0), P(1,1));

  bold;
  rect(P(-width,0), P(width, sqrt(1-width*width)));

  label(P(0.5, sqrt(0.75)), P(2,4), "$y=\\sqrt{1-x^2}$");
  h_axis_labels(P(x_min,0), P(x_max,0), x_size, P(-12, -12));

  end();
}
\end{verbatim}
\end{footnotesize}
\caption{The source file for \protect{Figure~\ref{fig:example-basic}}.}
\label{fig:example-basic-src}
\end{figure}

When \ePiX\ is run on this source file and the output is included in a
\LaTeX\ document, the result is as depicted in
Figure~\ref{fig:example-basic}.
\begin{figure}[hbt]
\begin{center}
\input{semicirc.eepic}
\caption{A rectangle inscribed in the upper half disk.}
\label{fig:example-basic}
\end{center}
\end{figure}
The @code{include}
line\index{Cplusplus@\CXX!syntax!include@\texttt{\#include}} ensures
that standard commands will be available to \ePiX\ when the file is
compiled. Every \ePiX\ file must contain this line. The double quotes
are \emph{single characters}, not pairs of single quotes. For the most
part, \CXX~is not picky about spaces and blank lines in a file, but it
is \emph{very}\/ sensitive to punctuation, which the
compiler\index{Cplusplus@\CXX!compiler} uses for parsing. Most lines
in a \CXX~program end with a semicolon. The @code{include} line is a
rare exception.\footnote{Lines beginning with @code{\#include} or
@code{\#define} are \emph{pre-processor directives}, and are not
seen by the compiler.}

\index{Cplusplus@\CXX!variables!assignment}The next non-blank line is an
\emph{assignment statement}. In this example, @code{width}~denotes the
half-width of the inscribed rectangle. The final appearance of the
figure can be adjusted by changing~@code{width}. Using variables
highlights the logical structure\index{Logical structure} of the
figure, which is especially valuable when the figure contains many
objects whose positions are mathematically related. Generally,
variables are similar to \LaTeX\ macros; if a constant appears
repeatedly in a single figure, it should probably be a
variable. Multiple variable assignments may be placed on a single
line, separated by commas, or may be put on separate lines. It is a
good idea to group together logically related assignment statements,
and to use blank lines and spaces as needed to make the file easy to
read.

\index{ePiX@\ePiX!preamble}The @code{include} line, variable
assignments, and function definitions (none in this example)
constitute the \emph{preamble}. The action begins with the
\emph{function call}\/ to @code{main}. The rest of the input file,
the \emph{body}, consists of \ePiX\ commands.

The first four lines of the body assign values to several variables
that determine the size and positioning of the figure. You are
discouraged from accessing these variables directly, but their names
are:\index{Reserved names!ePiX@\ePiX}
\begin{verbatim}
  x_min        x_max        y_min        y_max
  h_size       v_size       h_offset     v_offset
  pic_size     pic_unit
\end{verbatim}
@c The \LaTeX-style alignment options @code{r}, @code{rt},
@c @code{tr}, @code{t}, @code{lt}, @code{tl}, @code{l},
@c @code{lb}, @code{bl}, @code{b}, @code{rb}, @code{br},
@c and~@code{c} may not be used for \emph{global}\/ variables, but
@c are allowed for local variables. 

The @code{begin();} line prints some commentary and a \LaTeX\
picture head in the output file; everything between @code{begin();}
and @code{end();} generates a picture object.

Picture object commands are mnemonic. The @code{line} commands draw
the horizontal and vertical axes. The endpoints of the axes are
specified in terms of the Cartesian bounding box of the figure; if the
bounding box is changed, the axes will adjust automatically.  The
\verb+ellipse_top+ command draws the top half of an ellipse, centered
at~$(0,0)$, with radius~$(1,1)$. Remember that the construct
@code{P(a,b)} creates the ordered
pair~$(a,b)$.\index{Pairs!construction} The @code{bold} command
causes lines to be drawn using \verb+\thicklines+, and @code{rect}
draws a rectangle with opposite corners given in terms of the
variable~@code{w}.

Finally, there are two commands that print labels in the figure. The
first causes output of a \LaTeX\ command to be placed at the Cartesian
location~$(\frac{1}{2},\frac{\sqrt{3}}{\ 2})$,
offset\index{Offset!label} right by @code{2pt} and up by
@code{4pt}.  In the final figure, the label reads
``$y=\sqrt{1-x^2}$'', and is placed using the \LaTeX\ basepoint of the
entire formula. The label command \\
\verb+    h_axis_labels(P(x_min,0), P(x_max,0), x_size, P(-12, -12));+\\
generates horizontal-axis labels. The first label is at~$(-1,0)$, the
last is at~$(1,0)$, and there are $2+1$ labels, namely one at each
integer point. The final pair is the label offset; the labels will be
shifted left by @code{12pt} (which roughly centers them) and down
@code{12pt} (which prints them below the horizontal axis). \ePiX\
generates axis label values automatically. Note that line width
declarations such as @code{bold} have no effect on text fonts.

\index{Text!positioning|(}\LaTeX\ treats label text as a single
box.\footnote{\ePiX\ imposes this condition to facilitate accurate
label placement.} In the above example, labels are aligned at their
basepoint. Sometimes it is more convenient to center a label, or to
align the label elsewhere than its basepoint. The @code{label}
command has three major forms that allow centering and reverse
\LaTeX-style alignment, see Section~\ref{section:manual}. For now, the
important point (no pun) is that the position of a label should be
specified by a ``coarse'' location in Cartesian coordinates, then fine
tuned (probably visually) with an offset. Label offsets are always
specified in true points, because font sizes are given in points and
do not change with scaling. Using a Cartesian location and an offset
ensures that label positions will behave robustly under changes of
\verb+unitlength+, @code{picture} size, and \verb+bounding_box+.
\index{Text!positioning|)}

To summarize the features of~\CXX\ and \ePiX\ illustrated by this
input file:
\begin{itemize}
\item Label commands (and no others) have an offset option; all other
objects are placed using Cartesian coordinates. The use of offsets
when placing text in a figure is crucial to the figure's ability to
rescale attractively.

\item In a label command, the label itself is generated by a string
enclosed by double quotes. Aside from backslashes, the material
between the quotes is printed verbatim to the output file; to get a
backslash in the output,\index{Text!backslash in} you must
put a \emph{double}\/ backslash in the input.

\index{Cplusplus@\CXX!variables!declaration|(}
\item Global variables should be declared either in the preamble, or
in @code{main} \emph{before}\/ anything else.\footnote{This
stylistic point is for the benefit of human readers of the file.}
Variables that are constant should be defined in the preamble;
variables that depend on function values (such as @code{sqrt(3)/2})
or on other variables (e.g., \verb+4*x_size+) must be defined inside
@code{main}.\footnote{To \emph{declare}\/ a variable is to tell the
compiler the variable's name and type, but not to assign a value; the
latter is to \emph{define}\/ the variable. A variable must be declared
exactly once, but can be defined several times.} These rules are
sufficient, but no longer necessary (because \ePiX\ relies on the
\CXX~compiler, whose requirements are less stringent than those of the
\C~compiler).\index{Cplusplus@\CXX!variables!declaration|)}

\item \index{Cplusplus@\CXX!syntax!mathematics|(} \CXX~knows several
mathematical functions (@code{sqrt}, @code{log}, @code{sin}, and
so forth) by the same names as \LaTeX. However, \CXX~requires
a~\verb+*+ to denote multiplication, and does \emph{not}\/ recognize
the caret as notation for exponentiation. To get powers of a variable,
you must either specify explicit multiplication, as
in~\verb+width*width+, or must use \CXX's exponentiation function, as
in~\verb+pow(width,2)+. The latter sensibly handles arbitrary
floating-point bases and exponents.
\index{Cplusplus@\CXX!syntax!mathematics|)}

\item \index{Line styles} Almost all \ePiX\ path-type objects can be
drawn in @code{solid}, @code{dashed}, or @code{dotted} styles,
and in @code{plain} or @code{bold} line widths. Path styles and
line widths are declarations,\footnote{This is a change from earlier
versions, see page~\pageref{page:legacy}.} and remain in force until
overridden, or until the input file ends.  Combinations may be used to
get (e.g.) bold dashed paths.
\end{itemize}

\ePiX\ provides about two dozen graphics primitives, including lines,
arrows, triangles and rectangles, whole and half ellipses, circular
arcs and arrows, quadratic and cubic splines, Cartesian and polar
coordinate grids, axes with tick marks, and various types of point
marker. These are descriptively named, and are invoked as in the
example above. A detailed list and description is given in
Section~\ref{section:manual}. 

\index{Color} With the @code{pstcol} or @code{color} packages for
\LaTeX, you can create basic color figures with declarations such as
\verb+red;+ and \verb+black;+ The primary colors are available in this
way: red, blue, green, magenta, cyan, yellow, black, and white. \ePiX\
also allows generation of essentially arbitrary colors. Detailed
instructions on creating and previewing color files are given in
Section~\ref{section:manual}.

\subsubsection*{Plotting Functions}

\index{Plotting|(}
\ePiX\ has several commands for creating plots of user-specified
functions. Suppose we wish to graph the sin function on the interval
$[-3,3]$, emphasizing that while not invertible, it \emph{is}\/
invertible on the interval $[-\pi/2,\pi/2]$. Because the sin function
is provided in~\CXX, we need not define it. Our input file might look
like Figure~\ref{fig:example-plot-src}. The resulting \LaTeX\ output
is Figure~\ref{fig:example-plot}.
\begin{figure}
@c\begin{footnotesize}
\begin{verbatim}
/* sine.c -- The graph y = sin x on [-3,3] */
#include "epix.h"
double x0 = M_PI_2; // \pi/2 to 20 decimals

main()
{
  unitlength("1pt");
  picture(P(300, 100));
  bounding_box(P(-3, -1), P(3,1));

  begin();

  h_axis(P(x_min, 0), P(x_max, 0), x_size);
  v_axis(P(0, y_min), P(0, y_max), y_size);

  plot(sin, x_min, -x0, 30);
  plot(sin, x0, x_max, 30);

  dashed;
  line(P(x0,0), P(x0, sin(x0)));

  label(P(x0, 0), P(-3, -12), "$\\frac{\\pi}{2}$");
  h_axis_masklabels(P(x_min,0),P(x_max,0), x_size, P(-14,-12));

  bold;
  solid;
  plot(sin, -x0, x0, 60);

  end();
}
\end{verbatim}
@c\end{footnotesize}
\caption{The source file for \protect{Figure~\ref{fig:example-plot}}.}
\label{fig:example-plot-src}
\end{figure}

The figure is {\tt300pt} wide and {\tt100pt} high, and uses the
constant \verb+M_PI_2+. The axis-generating commands are new, but the
syntax is easily divined; note that their positions (and the number of
tick marks) are specified completely in terms of the bounding
box. This works well as long as the bounding box has integer
coordinates. The @code{plot} commands are of primary interest:
\begin{verbatim}
  plot(sin, x_min, -x0, 30);
\end{verbatim}
draws a plot of the sin function between \verb+x_min+ and~$-\pi/2$,
using 30 intervals of equal length (31~data points). The other
@code{plot} lines are similar.
\begin{figure}[hbt]
\begin{center}
\input{sine.eepic}
\caption{Plotting the sin function with \ePiX.}
\label{fig:example-plot}
\end{center}
\end{figure}

\index{ePiX@\ePiX!masking|(}An \ePiX\ figure is built in layers, with
later parts of the file set atop earlier parts. Generally you needn't
pay much attention to the order in which objects appear in a source
file, but in the sin graph example there are two opaque layers whose
occlusion of lower layers is deliberate. First, the axis labels are
``masked'', meaning they are set atop opaque white rectangles; this is
done to prevent the graph from colliding with the label
at~$-3$. Second, the bold portion of the graph passes over the mask at
the origin. Consequently, the plain sin graph, then the axis labels,
then the bold sin graph must appear in order in the source
file. Layering tends to be more of an issue with color figures, since
it is more apparent which of two curves passes over the other when
their colors are different. Generally, masked axis labels should come
last in a file, since the purpose of masking is to make the labels
legible.\index{ePiX@\ePiX!masking|)}

The number of points in a function plot should be as small as possible
without compromising quality, an aesthetic decision. \LaTeX\ reads in
all the points in a path before typesetting anything, and is likely to
run out of memory if the path contains more than a few hundred
points. There may be other limits on the total number of points a
previewer is able to display, but it should be no problem to preview a
figure containing several thousand points.

\ePiX\ provides plotting commands that do clipped, polar, or
parametric plotting, draw slope or vector fields, or plot solutions to
systems of ODEs, but they all operate similarly to @code{plot}: You
provide the function(s) to be plotted, a range of values over which to
plot, and the number of sample points. 

Eventually, you will want to define your own functions for
plotting. This is described in Section~\ref{section:reference}, and
some of the sample files contain examples.  Function (and variable)
names may consist of letters, numerals, and underscores, and may not
begin with a numeral. Names are case sensitive; the convention is to
use lower-case names, but you need not do so. It's a good idea to use
descriptive, relatively short names that are logically related to what
they stand for. If the compiler complains that a function (or
variable) is ``multiply defined'', it means the name has been
previously declared.  \index{Plotting|)}

\subsection{Running \ePiX}
\label{section:running}

\index{ePiX@\ePiX!running|(} The zeroth step in using \ePiX\ is to
have a \LaTeX\ document, say @code{sample.tex}, that requires a
mathematically accurate figure. If you use \LaTeX2e, your file should
begin
\begin{verbatim}
\documentclass[12pt]{article}
\usepackage{amsmath,latexsym,epic,eepic}
\end{verbatim}
The @code{epic} and \eepic\ packages are the relevant ones here. If
you plan to create color figures, you will also need @code{pstcol}
or @code{color}. Somewhere in @code{sample.tex} is the figure
itself:
\begin{verbatim}
\begin{figure}[hbt]
\begin{center}
\input{tutorial-plot.eepic}
\caption{Plotting the sin function with \ePiX.}
\label{fig:example-plot}
\end{center}
\end{figure}
\end{verbatim}
Before you run \LaTeX, you need a file named
@code{tutorial-plot.eepic} in the current directory. This is where
\ePiX\ comes in. If you have created an input file called
@code{sine.c}, as directed in Section~\ref{section:started}, and if
\ePiX\ is correctly installed, then you type
\begin{verbatim}
epix sine.c tutorial-plot.eepic
\end{verbatim}
After a short interval, during which some reassuring messages will be
printed on the screen, you will get the prompt back and the \eepic\
file will be there. That's all there is to it. You may leave off the
file extensions, and may even omit the name of the output file if you
want it to be the same as the name of the input (@code{sine.eepic}
in this example).\index{ePiX@\ePiX!running|)}

\index{Postscript conversion|(}To process the \LaTeX\ file,
either run \LaTeX\ as usual, or do
\begin{verbatim}
laps sample
\end{verbatim}
which runs \LaTeX\ on @code{sample.tex}, then uses @code{dvips} to
convert the @code{dvi} to the Postscript file
@code{sample.ps}. This is a convenient option if your document
includes color figures.  @code{laps} (for ``\LaTeX\ to Postscript'')
is a shell script included with \ePiX. There is also a rudimentary
script, @code{elaps}, that converts an \ePiX\ file into encapsulated
Postscript (@code{eps}) which can be included into a document via
the @code{graphics} package. An @code{eps} file is generally about
50--100~times larger than an \ePiX\ source file, but is useful if you
use @code{xdvi} to preview (color is available in included files),
or if you are tweaking the figures in a large document, and do not
want to recompile the entire document to change just one
figure. @code{elaps} is not capable of converting all \ePiX\ files;
your mileage may vary.\index{Postscript conversion|)}

\ePiX\ comes with a sample document containing side-by-side comparison
of over a dozen source files and their
output. Section~\ref{section:manual} is a complete description of
\ePiX's features, and Section~\ref{section:problems} describes
troubleshooting.  Good luck, and happy drawing!

\section{Advanced Features}
\label{section:reference}

The introduction of Section~\ref{section:started} does not describe
all of \ePiX's features, even ones that you may use frequently. You
may also find that you need to know more of~\CXX, either to understand
why a source file isn't compiling, or to achieve effects using more of
the power of~\CXX. Further, if the installation does not go smoothly,
you will need to know how \ePiX\ is implemented in order to get it
working. Finally, you may be curious, or a better programmer than the
author, and may have improvements to make. This section describes all
of \ePiX's features, some of the design rationale, and the
implementation. Several points about~\CXX\ that are mentioned in
Section~\ref{section:started} are repeated below for completeness.

\subsection{\ePiX, and the @code{epic} and \eepic\ Styles}

\index{ePiX@\ePiX!implementation|(emph}
The \LaTeX\ @code{epic} and \eepic\ styles define commands
\verb+\path+, \verb+\dashline+, and \verb+\dottedline+, that take a
list of ordered pairs as argument and print the corresponding
connect-the-dots path (or dashed/dotted path). These commands are used
in a \LaTeX\ picture environment just like any \LaTeX\ object.
Computers are good at generating lists of numbers. In \ePiX, you write
some lines such as
\begin{verbatim}
  /* Comment: The squaring function */
  double f(double t) { 
    return t*t; 
  }

  /* Graph f for t in [-1,1] using 20 steps */ 
  plot(f, -1, 1, 20);  
\end{verbatim}
When \ePiX\ is run, the @code{plot} command writes the following
\ePiX\ \emph{stanza}\/ to the output file:
\begin{verbatim}
@c plot:
\path(0,50)(5,40.5)(10,32)(15,24.5)(20,18)(25,12.5)(30,8)
  (35,4.5)(40,2)(45,0.5)(50,0)(55,0.5)(60,2)(65,4.5)(70,8)
  (75,12.5)(80,18)(85,24.5)(90,32)(95,40.5)(100,50)
@c
@c---------------------------------------------------------%%
\end{verbatim}
The actual numbers depend on the Cartesian bounding box, and on
\verb+h_size+ and \verb+v_size+, the \LaTeX\ dimensions of the figure;
in this example, \ePiX\ has generated a parabola that fits into a
\LaTeX\ picture 100~units wide and 50~high.

The \eepic\ file written by \ePiX\ is human-readable (even
formatted and commented), and it may be instructive to look at the
output of a short figure. You may edit the output file by hand if
necessary, though it is safer (and usually easier) to change the
source file and re-run \ePiX. Note that \ePiX\ will overwrite an
existing \eepic\ file if so directed. In summary, \ePiX\ is a
\LaTeX\ pre-processor; it turns a human-friendly picture description
into a marked-up list of numbers for \LaTeX.

An \ePiX\ figure is layered:\index{ePiX@\ePiX!masking} Objects are
drawn over objects that come earlier in the file. Most \ePiX\ objects
are transparent, but when using color it is noticeable whether a blue
curve goes over or under a magenta one (say). There are only a few
\ePiX\ commands that explicitly cover objects under them, but in a
complicated figure even the implicit ``masking'' effect bears
consideration. Among the commands that \emph{do}\/ cover previous
layers are the @code{masklabel} commands, which draw an opaque white
rectangle under labels, and @code{circ}, which draws a white-filled
circle 4~true pt in diameter.

\subsection{Coordinates and Dimensions}

\index{Scaling|(emph}
\LaTeX\ requires you to specify a @code{unitlength}, the picture
size, and an offset, which determines the picture coordinates of the
lower-left corner. Picture objects' locations are specified to \LaTeX\
in picture coordinates.  When composing a mathematical figure,
however, it is generally easier to use Cartesian coordinates. Letting
software handle this conversion not only frees you from worrying about
(non-portable) picture coordinates, but also makes it easy to change
the size of the figure, and to place the figure exactly where \LaTeX\
has left space for it. If you've ever had to change the unit length of
a figure (for example, because you are American and your coauthor is
not), only to have the picture become horribly ugly, overlap the
surrounding text, or otherwise break the document, you'll understand
why automatic coordinate conversion is a useful feature.

\index{Text!positioning|(}
There is one situation where Cartesian coordinates are not adequate,
namely when you are doing visual editing to place a text label in a
figure. A label's size is independent of both picture coordinates and
Cartesian coordinates, so if you use either to position a label,
changing the scale or the Cartesian bounding box will probably break
the positioning. However, \emph{true coordinates}\/ (measured on the
page) are no good, either, because the size and/or scale of the
picture may change with further editing. \ePiX\ circumvents this
difficulty by allowing labels to be placed in Cartesian coordinates,
but to be offset in true coordinates and/or aligned on points other
than the \LaTeX\ basepoint. For instance, the labels on a
coordinate axis need to be positioned at the proper location in the
Cartesian plane, but because \LaTeX\ uses the basepoint to position a
box, the raw Cartesian coordinates are likely to mis-position the
labels. If you fine-tune the labels' positions in Cartesian
coordinates, however, the picture will break if the scale is
changed. Using both Cartesian and true coordinates allows you to
position labels easily so that they are placed correctly if the
\verb+unitlength+ is changed, or even if the Cartesian bounding box
is changed.
\index{Text!positioning|)}

Aside from labels, all positions in an \ePiX\ file are specified in
Cartesian coordinates.  \ePiX\ asks \LaTeX\ to set aside a box of size
\verb+h_size+$\times$\verb+v_size+, then does affine scaling on the
rectangle \verb+[x_min, x_max]+$\times$\verb+[y_min, y_max]+ to get an
exact fit. You can still force objects to go outside the bounding box,
by giving them Cartesian coordinates outside the box.
\index{Offset!positive}Positive offsets in \ePiX\ shift the picture
{\bf up} and {\bf right} (the opposite of \LaTeX\ picture offsets).
\ePiX's output is accurate to $10^{-4}${\tt*unitlength}.
\index{Scaling|)}

\subsection{More about \CXX}

\index{Cplusplus@\CXX!syntax|(}
An \ePiX\ input file is really source code for a \CXX~program that
writes an \eepic\ file as output. If you do not speak \CXX, the
main things to remember (principally differences between \LaTeX\
and \CXX\ syntaxes) are:

\begin{enumerate}
\item \index{Cplusplus@\CXX!syntax!comment|emph} Comments, which may
span several lines, are delimited by the strings \verb+/*+~and
\verb+*/+. One-line comments, similar to \LaTeX\ comments, are begun
with \verb+//+ (analogous to the \LaTeX\ \verb+%+) and end with the
next newline. A \verb+//+-style comment may appear within a multiline
comment, but a \verb+/*+~\verb+*/+ comment may not; the \CXX~compiler
will mistake the first~\verb+*/+ it encounters as the end of the
current multiline comment.

\item Every statement and function call must end with a semicolon.  If
you omit a semicolon, the compiler will give you a cryptic error
message (such as `parse error at line~N' if the semicolon is missing
on the last non-blank line before line~N).

Lines that begin with
\verb+#include+\index{Cplusplus@\CXX!syntax!include@\texttt{\#include}} or
\verb+#define+ are \CXX\ \emph{pre-processor}\/ directives, and {\bf
do not} end with a semicolon.

\item \index{Text!backslash in} As in \LaTeX, the
backslash~\verb+\+ is an escape character in \CXX. To print a~\verb+\+
from \CXX, you must use \verb+\\+, as in
\begin{verbatim}
  /* Put label $y=\sin x$ at (2,1) */
  /* Note single  ^ backslash in output */
  label(P(2,1), P(0,0), "$y=\\sin x$"); 
  /*       Double backslash ^^ in source */
\end{verbatim}

\item \index{Cplusplus@\CXX!variables!declaration} Variables in \CXX\
must have a declared \emph{type}, such as @code{int} (integer),
@code{double} (double-precision floating point), or @code{char}
(string of characters), and should be defined in the preamble or at
the beginning of @code{main}. Unlike~\C, \CXX\ allows local
variables (loop or summation indices, for example) to be defined where
they first appear.  Variable and function names may contain letters
(including underscore) and digits, are case sensitive, and must begin
with a letter.

\item \index{Cplusplus@\CXX!syntax!mathematics} \CXX~requires explicit
use of~\verb+*+ to denote multiplication; simple juxtaposition is not
enough. \CXX~does not support the use of \verb+^+ for exponentiation,
e.g., \verb+t^2+ is invalid. Instead, you must use \verb+t*t+ or
\verb+pow(t,2)+.

\item \index{Reserved names!C@\C} The following words are reserved in
\CXX, and may not be used as function or variable names:

\begin{tabular}{p{1.0in}p{1.0in}p{1.0in}p{1.0in}}
\tt auto	& \tt double	& \tt int	& \tt struct 	\\
\tt break	& \tt else	& \tt long	& \tt switch 	\\
\tt case	& \tt enum	& \tt register	& \tt typedef 	\\
\tt char	& \tt extern	& \tt return	& \tt union 	\\
\tt const	& \tt float	& \tt short	& \tt unsigned 	\\
\tt continue	& \tt for	& \tt signed	& \tt void 	\\
\tt default	& \tt goto	& \tt sizeof	& \tt volatile 	\\
\tt do		& \tt if	& \tt static	& \tt while
\end{tabular}

In addition, \ePiX\ reserves the following 
variables:\index{Reserved names!ePiX@\ePiX}

\begin{tabular}{p{1.0in}p{1.0in}p{1.0in}p{1.0in}}
\verb+x_min+  & \verb+x_max+  & \verb+y_min+    & \verb+y_max+   \\
\verb+h_size+ & \verb+v_size+ & \verb+h_offset+ & \verb+v_offset+\\
\verb+x_size+ & \verb+y_size+ & \verb+pic_size+ & \verb+pic_unit+
\end{tabular}

The names \verb+r, rt, tr, t, lt, tl, l, lb, bl, b, rb, br, c+ are
label alignment options, and may not be used as names for
\emph{global}\/ variables. Local variables are not subject to this
restriction.\index{Text!positioning}

\CXX~is case-sensitive, so capitalized variants are valid (but
discouraged).
\end{enumerate}

\index{Scaling!aspect ratio}The aspect ratio of the figure is
controlled by adjusting the \LaTeX\ size of the figure and its
Cartesian bounding box.  The following length units may be used:
@code{cm}, @code{in}, @code{mm}, @code{pc}, and
@code{pt}. (One pica equals 12~pt.) Font-dependent units @code{em}
and @code{ex}, and ``exotic'' units (Didot points, Ciceros, etc.)
are not recognized. See @code{lengths.cc} to add support for other
length units.

\index{ePiX@\ePiX!preamble}Aside from \verb+#include+ and
\verb+#define+ statements, and variable declarations, the preamble
consists of function definitions, for plotting functions you have
specified. Functions may not be defined inside other functions; in
particular, all definitions of user-specified functions \emph{must}\/
come in the preamble, before the call to @code{main}.

\index{Functions|(}
\index{Functions!Cplusplus@\CXX}
\CXX~knows the following functions of one variable by name:
\begin{center}
\begin{tabular}{p{0.75in}p{0.75in}p{0.75in}p{1.5in}}
\tt sqrt	& \tt sin	& \tt sinh	& \tt asin \\
\tt ceil	& \tt cos	& \tt cosh	& \tt acos \\
\tt floor	& \tt tan	& \tt tanh	& \tt atan \\
\tt exp		& \tt log	& \tt log10	& \tt fabs {\rm(abs val)}
\end{tabular}
\end{center}
The inverse trig functions are principle branches. In addition,
\verb+pow(x,y)+ returns~$x^y$ when real, and \verb+atan2(y,x)+ returns
${\rm Arg}(x+iy)$, the principle branch of arg. \CXX~knows many
constants to 20~decimal places (such as \verb+M_PI+, \verb+M_PI_2+,
and \verb+M_E+ for~$\pi$, $\pi/2$, and~$e$ respectively; there are
over a dozen in all). \index{Functions!ePiX@\ePiX}\ePiX\ defines a few
additional functions, such as @code{recip} (the reciprocal, defined
to be~$0$ at~$0$) and @code{cb} (for ``Charlie Brown''), the
period-2 extension of the absolute value function on~$[-1,1]$. If you
use certain functions frequently, add them to @code{functions.cc}
and recompile \ePiX.

\index{Functions!GNU}The GNU \CXX\ library defines many other
functions, including inverse hyperbolic functions (@code{acosh},
etc.), log and exp with base 2, 10, or arbitrary~$b$ (@code{log2},
etc.), the error and gamma functions (@code{erf} and @code{tgamma}
[sic], respectively), and Bessel functions of first and second
kind. (@code{j0}, @code{j1}, @code{y0}, etc. Use, e.g.,
@code{jn(5, )} to get higher indices.)  The GNU \C~library reference
manual describes these and other functions in detail.
\index{Cplusplus@\CXX!syntax|)} \index{ePiX@\ePiX!implementation|)}

You may use known functions in subsequent definitions. Functions of
two (or more) variables are defined in direct analogy to functions of
one variable:
\begin{verbatim}
double f(double t)
{
  return t*t*log(t*t); // t^2 \ln(t^2)
}

double g(double s, double t)
{
  return exp(2*s)*cosh(sin(M_PI*t));
}
\end{verbatim}
\index{Functions|)}

\subsection{More Advanced Uses of \CXX}
\index{ePiX@\ePiX!sample files|(}

Because \CXX~is a programming language, \ePiX\ figures can be
specified using variables, loops, and recursion, to produce
interesting effects. This section presents a few ideas by example. The
@code{sample} files contain other examples.

\subsubsection*{Piecewise-Defined Functions}

\index{Functions!complicated|(}
The syntax for defining a function such as $f=\max(\sin,\cos)$ is:
\begin{verbatim}
double f(double t)
{
  if (cos(t) <= sin(t))
    return sin(t);
  else 
    return cos(t);
}
\end{verbatim}
If there are more than two formulas in the definition, use an 
@code{else if} construction, as in
\begin{verbatim}
double max_10_f(double x)
{
  if ( fabs(f(x)) < 10 ) // |f(x)| < 10
    return f(x);
  else if ( f(x)>0 )
    return 10;
  else
    return -10;
}
\end{verbatim}
This truncates~$f$ at the lines $y=\pm10$. (The function~$f$ must be
defined separately.)

\subsubsection*{Finite Sums and Other Algorithms}

Function definitions in~\CXX\ may be as simple as an algebraic formula,
or as complicated as an arbitrary finite ``rule''. Sums of finite
series are achieved with the following sort of definition, which
defines $\mathrm{fourier9}(t)=\sum\limits_{k=1}^9\frac{1}{k}\sin kt$:
\begin{verbatim}
double fourier9(double t)
{
  double y=0; // running total of the sum

  /* Run from k=1 to 9; increment k at each step */
  for (int k=1; k < 10; ++k)
    {
      // Add (1/k)sin(kt) to the running total
      y += (1.0/k)*sin(k*t); 
    }
  return y;
}
\end{verbatim}
The Weierstrass non-differentiable function @code{sample} file is an
example.

Generally, a function definition may be specified by an arbitrary
algorithm; see the definitions of gcd, sup, and inf in
@code{functions.cc} for more examples. Of course, numerical
error---or even excessive run time---can become an issue if the
algorithm is complicated.
\index{Functions!complicated|)}

\subsubsection*{Parametrized Figures and Animation Frames}
\index{Logical structure}

As already mentioned, variables may be used to clarify the logical
structure of a figure. The way the inscribed rectangle figure was
implemented makes it easy to change the width of the rectangle. When a
figure is complicated, judicious use of variables makes the figure
flexible. The @code{sample} file depicting upper rectangles for the
sin function is an example; to change the number of rectangles, one
need change only a single number in the preamble. To change the
integrand to a different function also requires just one change in the
preamble. (Labels' text must still be changed individually.)

If a figure depends suitably upon a collection of parameters, then a
loop can be used to draw the entire figure for multiple values of the
parameters, yielding successive ``snapshots'' of the figure as time
progresses.\footnote{\LaTeX\ provides no direct way to animate frames,
but the author has used a toy zeotrope together with \ePiX-generated
figures to depict animated mechanical configurations.}  In the
@code{sample} files is a simple example, the cycloids traced by a
rolling wheel. Other possibilities are to solve a planar ODE for
varying lengths of time (illustrating the flow), or to plot solutions
of a $(1+1)$-dimensional PDE (for example, to depict heat flow or wave
motion).
\index{ePiX@\ePiX!sample files|)}

\subsection{Summary of \ePiX\ Objects}
\label{section:objects}

\index{ePiX@\ePiX!objects|(}
After the @code{begin} line, an \ePiX\ file consists of a sequence of
style declarations (for color and boldface plots) and commands that
draw the following kinds of objects:

\begin{itemize}
\item Polygons
\bi
  \item Lines, triangles, coordinate rectangles, and arrows
\ei

\item Coordinate axes and decorations
\bi
  \item Axes and labels
  \item Cartesian and polar coordinate grids
  \item Point markers (see Table~\ref{table:markers})
  \item Arbitrary text, with multiple alignment options
\ei

\item Curve primitives
\bi
  \item Ellipses and half ellipses
  \item Circular arcs and arrows, hyperbolic lines
  \item Quadratic and cubic splines
  \item Simple knot diagram primitives
\ei

\item Plots of user-defined functions
\bi
  \item Graphs, polar plots, parametric plane and space curves
  \item ``Adaptive'' plots (points equally spaced by arc length)
  \item Clipped plots (graphs truncated to the \verb+bounding_box+)
  \item Plots of functions in a family, planar and spatial mesh plots
  \item Plots of numerical data from files
\ei

\item Calculus operations on user-defined functions
\bi
  \item Derivatives and tangent lines; tangent fields and envelopes
  \item Definite integrals and solution curves to planar ODEs
  \item Slope and vector fields (fixed and true length)
\ei
\end{itemize}
\index{ePiX@\ePiX!objects|)}

\section{Reference Manual}
\label{section:manual}

This section presents an essentially complete list of \ePiX's
capabilities. To get a \emph{truly}\/ up-to-date list, peruse the
header file @code{epix.h}, then consult the source if you find an
undocumented routine.

\paragraph{Size Commands and the Preamble} (@code{output.cc})

\index{Scaling}
\bi
  \item Assignment of variables %% \smallskip

   \verb+     bounding_box(P(x_min, y_min), P(x_max, y_max));+\\
   \verb+     picture(P(h_size, v_size));+\\
   \verb+     offset(P(h_offset, v_offset));+\\
   \verb+     unitlength("1pt");+\\
   \verb+     begin();+

  In an actual file, numbers are used, but the variables listed above
  are assigned values when these functions are called. @code{offset}
  is zero by default, hence optional. In @code{unitlength} the
  quoted argument is a floating point number followed by a two-letter
  \LaTeX\ length. @code{begin} sets the variables \verb+x_size+ and
  \verb+y_size+, the width and height of the bounding box. In the body
  of a figure, all input coordinates are Cartesian, and are of type
  double.

\ei

\paragraph{Line Styles and Color} (@code{output.cc})

\index{Line styles|(emph} The material in this subsection applies only
to path-type objects (polygons, curves, and plots). The method of
specifying line styles (solid, dashed, dotted) and line widths (plain,
bold) changed between Versions 0.8.4~and 0.8.6. 
Section~\ref{section:changes} has detailed information on processing
files that use pre-0.8.5 syntax, should this be absolutely necessary.

Line style (including dash lengths and dot separation), line width,
and colors are declarations, not environments: A setting remains in
effect until overridden by a later setting (or until the file ends).
These three families of attribute are now completely separate. (That
is, @code{bold} is no longer a line style.)  Conceptually, \ePiX\
keeps track of the current line style, width, and color via
``environment variables''.\footnote{Literally this is not quite true;
the full story is outlined below.} At each point in an input file, the
appearance of path-type objects is dictated by the current values of
these variables.

\bi
  \item Line width:

  The most common line widths are @code{plain} (\LaTeX\
  \verb+\thinlines+, $0.4$~pt) and @code{bold} (\verb+\thicklines+,
  $0.8$~pt). The default (i.e., at the start of a figure) is
  @code{plain}.  \ePiX\ does not maintain the current line width
  internally; instead, line width declarations are written immediately
  to the output file.  An @code{arrow} after a @code{bold}
  declaration is not the same as a @code{boldarrow}; the latter has
  a filled head.

  The function @code{pen()} accesses @code{eepic.sty}'s
  @code{allinethickness} to permit drawing in essentially arbitrary
  line width. @code{pen()} may be called with a @code{double}
  argument (interpreted as a width in points), or with a string
  argument, similarly to @code{unitlength()}. The following are
  (essentially) equivalent:
\begin{verbatim}
  pen(1);   pen("1pt");   pen("0.35mm");  pen("0.0138in");
\end{verbatim}
  The @code{pen()} function should be used sparingly, to preserve
  uniformity in the appearance of output files. If you \emph{really}\/
  need several different line widths, it is best to use macros, see
  Section~\ref{section:custom}. If \ePiX\ ever standardizes on a
  larger collection of line widths, personal macros can be redefined
  easily.

  \item Line style: %% \smallskip

  All path-type objects can be drawn with solid, dashed, or dotted
  curves.  The declarations @code{solid}, @code{dashed}, and
  @code{dotted} remain in effect until overridden, or until the end
  of the input file. Initially, lines are solid.

  New users should \textbf{skip} this paragraph.  The old-style
  ``prefix'' naming convention is \emph{disabled}\/ by default, and
  should not be used for new figures. If you need to process input
  files containing prefixed line styles, you must install the
  @code{legacy} subpackage, see page~\pageref{page:legacy}. When
  @code{legacy} is installed, most curve primitives and plots can be
  drawn in dashed, dotted, or bold styles by prepending \verb+dash+,
  \verb+dot+, or \verb+bold+ to the object's name.\footnote{New 
  routines do not support this convention, further discouraging the
  use of @code{legacy} features in new source files.} For backward
  compatibility, if (say) @code{dashline} is called while the path
  style is @code{dotted}, the existing path style is superseded, and
  reverts to @code{solid} after the call. By contrast, an
  ``unprefixed'' routine such as @code{line} will be drawn in the
  \emph{current}\/ path style, and the path style \emph{does not}\/
  revert to @code{solid} after the call.

  Line widths and path styles are independent. Combinations of
  @code{bold} or @code{pen} and path style declarations may appear
  in any order; except as noted above, an object will be drawn using
  the current line width and style.

  Dash lengths and dot separation can be changed by calling the
  function \verb+stretch(double);+ The default stretch factor of~1
  should be acceptable for most purposes. The argument is not a
  literal scale factor, but is close. That is, @code{stretch(2);}
  roughly doubles the lengths of dashes and the separation between
  dots in dotted objects.  There are potentially unpredictable
  interactions between line width, dash length/dot separation, and
  Postscript drivers.\footnote{In particular, dashed and dotted
  objects may print differently than they preview.} These issues are
  beyond te control of \ePiX, and there seems to be no simple, robust
  way to enforce consistent behavior. \index{Line styles|)}
  
  \item \index{Color|(emph}Color: %% \smallskip

  \ePiX\ provides color output via the @code{pstcol} or
  @code{color} packages, and can generate essentially arbitrary
  colors, using either the red-green-blue model (@code{rgb}, more
  natural for CRT displays) or the cyan-magenta-yellow-black model
  (@code{cmyk}, often better for printing). An @code{rgb}~color is
  determined by three floating-point densities between~0 (no color)
  and~1 (full saturation). Red, green, and blue are, respectively:

  \verb+     rgb(1,0,0);    rgb(0,1,0);    rgb(0,0,1);+

  A @code{cmyk} color is similarly specified by four
  floats. Densities outside the range~$[0,1]$ are ``clipped''. \ePiX\
  truncates color densities to 2~decimal places (about 20~bits). If
  you need finer control, you'll probably want to look at your
  Postscript driver rather than \ePiX.~$\ddot\smile$

  These color specifiers are declarations, and remain in force until
  superseded.  The seven primary colors (@code{rgb} and
  @code{cmyk}) and white\footnote{Drawing in @code{white} can be
  used like correction fluid to remove pieces of a figure accurately.}
  can be called by name, e.g., @code{red;} The scope of a color
  declaration is ended by a subsequent declaration (e.g.\
  @code{black;}) or the end of the file. If the @code{legacy}
  subpackage is installed, a primary color declaration may be ended by
  name, e.g.\ \verb+end_magenta;+ This construct should not be used
  for new \ePiX\ files.

  Colors will not appear if the @code{dvi} file is previewed in
  @code{xdvi}, but will appear if you use @code{laps} to process
  your \LaTeX\ files, then view the Postscript with (say) @code{gv},
  or if you use @code{elaps} to create @code{eps} files then
  preview with @code{xdvi}.

\ei
\index{Color|)}

\paragraph{Pair manipulation} (@code{pairs.cc})

\index{Pairs|emph}
The \ePiX\ function @code{P} turns a pair of @code{doubles} into a
\verb+<pair>+ (an ordered pair data structure). \ePiX\ treats pairs as
complex numbers for arithmetic purposes; standard \CXX-like
constructions may be used with pairs.

\bi
  \item Pair creation, angles in radians: %% \smallskip

  \verb+     polar(r, theta);     cis(t);+

  @code{polar(1.0, t)}, @code{cis(t)}, and
  @code{P(cos(t),sin(t))} are equivalent. \ePiX\ recognizes the
  standard basis \verb+e_1+~and \verb+e_2+, but these should be
  avoided, since they are likely to be deprecated as \ePiX\ becomes
  more capable of 3-dimensional drawing.

  \item Arithmetic and incrementation (p and q are pairs, k is 
    double): %% \smallskip

\begin{verbatim}
    p + q, p - q, k*p, p*q, p/q;
    p += q, p -= q, p *= k, p *= q; p /= q;
\end{verbatim}
  When forming symbolic expressions involving pairs, scalars (doubles)
  must be collected together at left, vectors (pairs) at right. If
  results of an arithmetic expression are unexpected, use parentheses
  to force a particular association.  

  \ePiX\ provides the Euclidean dot product (think of Dirac's bra-ket
  notation), the componentwise product, and a 1/4-turn
  counterclockwise:
\begin{verbatim}
    (a,b)|(x,y) = ax+by
    (a,b)&(x,y) = (ax,by)
    J(a,b) = (-b,a)
\end{verbatim}
  For example, \verb@P(a,b)&e_2 = P(0,b)@.
\ei

\paragraph{Triple manipulation} (@code{triples.cc})

Ordered triples are handled similarly to ordered pairs.  @code{P}
turns a triple of @code{doubles} into a \verb+<triple>+. The product
of triples is the cross (``vector'') product, and the quotient of
triples is undefined.

\bi
  \item Triple creation, angles in radians: %% \smallskip

   \verb+     sph(r, theta, phi);+ \\
  \ePiX\ recognizes the standard basis \verb+E_1+, \verb+E_2+,
  and~\verb+E_3+. 

  \item Perspective figures: %% \smallskip

   \verb+     viewpoint(viewpt1, viewpt2, viewpt3);+ \\
   \verb+     V(x1, x2, x3);+

  \index{Plotting!3-dimensional} \ePiX\ does orthogonal perspective
  drawing. The @code{viewpoint} of a figure is a vector onto whose
  orthogonal complement certain @code{plot} objects are projected.
  The overall scale of @code{viewpoint} is immaterial, e.g.,
  $(1,2,-1)$~and $(2,4,-2)$ are identical, while $(-1,-2,1)$ reverses
  the orientation of the figure. If @code{viewpoint} is not parallel
  to the $z$~axis, then the $z$~axis is drawn vertically; otherwise
  the figure is drawn in ``standard'' Cartesian form. By default,
  @code{viewpoint} is the zero vector, hence optional. The
  @code{viewpoint} may be changed anywhere in a source file. Using
  red and cyan together with slightly different viewpoints can be used
  to give a 3D-glasses effect.

  The function~@code{V} produces a @code{pair} from an ordered
  triple by orthogonal projection from the @code{viewpoint} to the
  origin. In polygons, arrows, splines, and ellipses, and in
  positioning labels, objects' location may be specified in terms of
  triples. There is a separate function for 3-d curve plotting, see
  below.

\ei

\paragraph{Polygons} (@code{objects.cc})

\bi
  \item The line joining $(a,b)$~to $(c,d)$: %% \smallskip

   \verb+     line(P(a,b), P(c,d));+
   \verb+     line(P(a,b), P(c,d), t);+ \\
   \verb+     Line(P(a,b), P(c,d));+
   \verb+     Line(P(a,b), m);+

   The first form draws the segment with indicated endpoints. The
   second accepts an ``expansion parameter''~$t$ and draws a segment
   with the same midpoint, but having length scaled by~$2^{t/100}$. An
   expansion parameter of~100 doubles the length, while~$-100$ halves
   the length. The third and fourth forms\label{Line} draw the portion
   of the line that lies inside the \verb+bounding_box+. The line is
   specified by either the given points or a point and slope.

  \item The triangle with vertices $(a,b)$, $(c,d)$, and~$(e,f)$:
  %% \smallskip 

   \verb+     triangle(P(a,b), P(c,d), P(e,f));+

  \item Coordinate rectangle with opposite corners $(a,b)$~and
  $(c,d)$: %% \smallskip

  \verb+     rect(P(a,b), P(c,d));+

  Either pair of opposite vertices specifies the rectangle.

  \item Gray-filled rectangle (unaffected by color declarations)

   \verb+     swatch(P(a,b), P(c,d));+
\ei

\paragraph{Coordinate axes and decorations} (@code{objects.cc}) 

\bi
  \item Axes with tick marks %% \smallskip

   \verb+     h_axis(P(a,b), P(c,d), n);+

    Draws an axis between $(a,b)$ and $(c,d)$ with $n+1$~evenly-spaced
    tick marks appropriate for a horizontal axis. If the bounding box
    has integer sides, then the command

   \verb+     h_axis(P(x_min, 0), P(x_max, 0), x_size);+

    draws a horizontal axis the width of the figure with tick marks
    spaced one Cartesian unit apart.

   \verb+     v_axis(P(a,b), P(c,d), n);+

    Same, but with tick marks appropriate for a vertical axis.

  \item Cartesian grid %% \smallskip

   \verb+     grid(n1, n2);+
   \verb+     grid(P(a,b), P(c,d), n1, n2);+

    Draws an @code{n1}~by @code{n2} grid that fills, respectively,
    the \verb+bounding_box+ or the coordinate rectangle with opposite
    vertices $(a,b)$~and $(c,d)$. Graph paper can be created by
    superimposing grids of varying mesh size and line width:
    \begin{center}
    \input{graphpaper.eepic}
    \end{center}
  
  \item Polar grid %% \smallskip

   \verb+     polar_grid(r, n1, n2);+

    Draws a polar grid of radius r with n1 rings and n2 sectors.
  
  \item \index{ePiX@\ePiX!contrib@\texttt{contrib}} S. D. Pedersen's
    @code{contrib/} package contains a number of routines for
    enhanced Cartesian graphs. See @code{contrib/doc} in the source
    for documentation.

  \item \index{ePiX@\ePiX!marker types} Point markers
  \input{dots.eepic} %% \smallskip

   \verb+     spot(P(a,b));  dot(P(a,b));  ddot(P(a,b));+ \\
   \verb+     circ(P(a,b));  ring(P(a,b), r);+

  @code{spot}, @code{dot}, and @code{ddot} are black;
  @code{circ} is white filled, cannot be colored, and masks what is
  underneath. A @code{ring} has diameter @code{r} true pt, can be
  colored, and is transparent. @code{circ} is useful for denoting
  the end of an open interval.  \ePiX\ also provides a @code{marker}
  function, whose syntax is \verb+    marker(P(a,b), <MARKER TYPE>);+

  \begin{table}[htb]
  \begin{center}
  \input{marker.eepic}
  \end{center}
  \caption{\ePiX's marker types.}
  \label{table:markers}
  \end{table}

  These marker types are also available when plotting data from a
  file, see @code{dataplot} below.  Markers of type @code{CIRC},
  @code{DOT}, and @code{DDOT} cannot be colored; this is a \LaTeX\
  issue.

  \item Arrows and darts %% \smallskip

   \verb+     arrow(P(a,b), P(c,d));    dart(P(a,b), P(c,d));+ \\
   \verb+     boldarrow(P(a,b), P(c,d));+ \\
   \verb+     bolddart (P(a,b), P(c,d));+

    Draws an arrow from $(a,b)$ to $(c,d)$ whose head is 3~true pt
    wide and 8.25~true pt long. If the true distance from $(a,b)$~to
    $(c,d)$ is less than 8.25~pt, only the arrowhead is drawn, with
    its base at $(a,b)$. A @code{dart} is similar, but the head has
    half the linear dimensions. Dart and arrow dimensions are
    \verb+#define+d in @code{globals.h}, and may only be changed at
    compile time.
  
  \item \index{Text!positioning|(emph} Axis labels %% \smallskip

   \verb+     h_axis_labels(P(a,b), P(c,d), n, P(u,v));+ \\
   \verb+     v_axis_labels(P(a,b), P(c,d), n, P(u,v));+ \\
   \verb+     h_axis_masklabels(P(a,b), P(c,d), n, P(u,v));+ \\
   \verb+     v_axis_masklabels(P(a,b), P(c,d), n, P(u,v));+

    \verb+h_axis_labels+ puts $(n+1)$~evenly-spaced labels on the
    segment joining $(a,b)$ and $(c,d)$. (Usually $b=d$, but this is
    not necessary.) The ``mask'' version draws an opaque white
    rectangle under the label text, and requires the @code{pstcol}
    or @code{color} package.  The labels are automatically generated
    to match their horizontal location. The pair \verb+P(u,v)+ gives
    the offset in true~pt. For example,

    \verb+     h_axis_labels(P(x_min,0), P(x_max,0), 8, P(-4,-12));+

    divides the $x$~axis into 8~subintervals, generates labels
    accordingly, and places them in Cartesian coordinates, but shifted
    left by 4~pt and down by 12~pt. The ``v''~versions are analogous,
    but for a vertical axis.

    Each axis-labelling routine takes an optional \LaTeX-style
    alignment argument, as in

    \verb+     h_axis_labels(P(a,b), P(c,d), n, P(u,v), label_posn);+

    \verb+label_posn+ may be~@code{c} (center), or one or an
    appropriate pair of @code{t}, @code{b}, @code{r},
    or~@code{l} (top, bottom, right, left). As is the case for
    @code{offset}s, these alignment options specify the position of
    the label \emph{relative to the basepoint}, namely they work
    \emph{opposite}\/ to the way they work in \LaTeX. For example, the
    alignment option~@code{br} puts the label below and to the right
    of~$(a,b)$:
    \begin{center}
    \input{alignment.eepic}
    \end{center}

  \item General text labels
  %% \smallskip

   \verb+     label(P(a,b), P(u,v), "<text string>");+ \\
   \verb+     label(P(a,b), "<text string>");+ \\
   \verb+     label(P(a,b), P(u,v), "<text string>", label_posn);+
@c   \verb+     masklabel(P(a,b), P(u,v), "<text string>");+ \\
@c   \verb+     masklabel(P(a,b), "<text string>");+ \\
@c   \verb+     masklabel(P(a,b),P(u,v),"<text string>, label_posn");+

    The first form prints \verb+<text string>+ with its \LaTeX\
    reference point at the Cartesian location $(a,b)$, offset in true
    points by $(u,v)$. The second form is similar, but centers the
    label at~$(a,b)$ via \verb+\makebox(0,0)+. (Vertical alignment may
    be off, depending on the label text.) The third form provides
    label box alignment as described above for axis labels.

    Each label command has a corresponding ``mask'' version
    (@code{masklabel}) that works analogously to masked axis
    labels. Masked labels require the @code{pstcol} or
    @code{color} package.  \index{Text!positioning|)}

    \index{Text!backslash in|emph} 
    To get a~\verb+\+ in output, there must be a \verb+\\+ in the
    input string. For example, the call

   \verb+  label(P(4,2), P(0,0), "$\\sigma=\\phi(\\tau)$");+

    prints the line

   \verb+  \put(360,180){$\sigma=\phi(\tau)$}+

    in the output file. (The @code{put} location depends on
    user-supplied dimensions.)

\ei

\paragraph{Curve primitives} (@code{curves.cc})

\bi
  \item Ellipses and half ellipses %% \smallskip

   \verb+     ellipse(P(a,b), P(u,v));+ \\
   \verb+     native_ellipse(P(a,b), P(u,v));+ \\
   \verb+     ellipse_top/bottom/left/right(P(a,b), P(u,v));+

    Plots the (half) ellipse centered at $(a,b)$ with radius $(u,v)$,
    and with axes parallel to the coordinate axes. The ``native''
    version uses an \eepic\ macro, resulting in a shorter output file,
    and is available in plain only.

    Right half ellipse, rotated counterclockwise by $\theta$~\emph{degrees}. 

   \verb+     ellipse_half(P(a,b), P(u,v), theta);+

  \item Circular arcs %% \smallskip

   Circular arc of center $(a,b)$ and radius~$r$, subtending the angle
   (counterclockwise, in radians) from $\theta_1$~to $\theta_2$. 

   \verb+     arc(P(a,b), r, theta1, theta2);+ \\
   \verb+     arc_arrow(P(a,b), r, theta1, theta2);+

   If $\theta_2$ is smaller, the arc goes clockwise. The arrowhead
   goes at~$\theta_2$. If an \verb+arc_arrow+ is too short, nothing is
   drawn.

  \item Quadratic and cubic splines with specified control points
  %% \smallskip 

   \verb+ spline(P(x1,y1), P(x2,y2), P(x3,y3));+ \\
   \verb+ spline(P(x1,y1), P(x2,y2), P(x3,y3), P(x4,y4));+

  \item Simple knot diagram primitives (shown with bounding boxes
  below) %% \smallskip

   \verb+    p_twist(P(a,b), P(c,d));+
   \verb+    n_twist(P(a,b), P(c,d));+ \\
   \verb+    twists(P(a,b), P(c,d), n);+ 

\medskip

\begin{center}
\input{p-twist.eepic} \medskip

\input{p-twists.eepic}
\end{center}
\ei

\paragraph{Non-standard functions} (@code{functions.cc})

\index{Functions!ePiX@\ePiX}
\bi
  \item Common functions with isolated discontinuities: @code{sgn}
    (signum), @code{recip} (reciprocal, defined to be~0 at~0), 
    @code{sinx} ($\sin x/x$ with discontinuity removed)
  \item The ``Charlie Brown'' function, @code{cb}, namely the
    period-2 extension of absolute value on the interval~$[-1,1]$.
  \item Integer-valued functions @code{abs} and @code{gcd}.
  \item Non-printing utility functions:
    \verb+  sup(f, a, b);    inf(f, a, b);+

    Numerical approximation of max/min value of~$f$ on $[a,b]$.
\ei

\paragraph{Plotting} (@code{plots.cc})

\index{Plotting|(emph}
  All plot routines accept @code{pair}- or @code{triple}-valued
  arguments as appropriate; lists of functions may be used as well. In
  the code snippets below, functions are of type @code{double}
  (i.e., are \emph{real-valued}) unless specified otherwise.
  Functions must be defined in the preamble, before @code{main}, or
  in a separately compiled file, as in @code{functions.cc}. See the
  samples files for practical advice on usage.

\bi 
  \item Ordinary graph plots  %% \smallskip

   \verb+     plot(f, t_min, t_max, n);+

    Plots the graph of~$f$ for input values between the limits,
    using $n+1$ points equally spaced in the domain. (\verb+t_min+ and
    \verb+t_max+ are doubles, @code{n} is an int) 

  \item Adaptive plotting %% \smallskip

   \verb+     adplot(f, t_min, t_max, n);+

    Same as @code{plot}, but attempts to space data points
    equidistantly along the graph. Good for dashed and dotted potting
    of differentiable functions whose derivative has large absolute
    value on small intervals, but is much slower than @code{plot}, and
    the output is not always more attractive.  

  \item Parametric plane curves %% \smallskip

   \verb+     plot(pair f, t_min, t_max, n);+ \\
   \verb+   adplot(pair f, t_min, t_max, n);+ \\
   \verb+     plot(f1, f2, t_min, t_max, n);+


    Parametric plot of $\bigl(f_1(t), f_2(t)\bigr)$, with $n+1$
    points. 

  \item Polar graphs %% \smallskip

   \verb+     polarplot(f, t_min, t_max, n);+

    Polar plot of $r = f(t)$ for $t\in$\verb+[t_min,t_max]+, with
    $n+1$ points. Angles are measured in {\bf revolutions}; $[0,1]$ is
    a full turn.

  \item Truncated plots %% \smallskip

   \verb+     clipplot(f, t_min, t_max, n);+ \\
   \verb+     clipplot(pair f, t_min, t_max, n);+ \\
   \verb+     clipplot(f1, f2, t_min, t_max, n);+

    Same as @code{plot}, but clips the plot to lie inside the bounding
    box 

    \verb+    [x_min,x_max]+$\times$\verb+[y_min,y_max]+.  

    Clipping is not currently supported in polar plots.

  \item Plotting curves in a family %% \smallskip

   \verb+ multiplot1(pair f, P(a,b), P(c,d), Net(n1, n2), num_pts);+ \\
   \verb+ multiplot1(f1, f2, P(a,b), P(c,d), Net(n1, n2), num_pts);+

    If $f_1$~and $f_2$ are functions of two variables, then
    $(f_1,f_2)$ determines a mapping of the rectangle
    $[a,c]\times[b,d]$ to the plane. @code{multiplot1} divides this
    rectangle into an $n_1\times n_2$~grid, then plots the images of
    the \emph{vertical}\/ segments (first variable held constant)
    using \verb+num_pts+~points per curve. @code{multiplot2} does
    the analogous plot when the second variable is held constant. In
    other words, these routines plot several functions in a family;
    think of the variable held constant as an indexing parameter. 

  \item \index{Plotting!3-dimensional|(} Perspective plots %% \smallskip

   \verb+        plot(triple f,   t_min, t_max, n);+ \\
   \verb+    clipplot(triple f,   t_min, t_max, n);+ \\
   \verb+        plot(f1, f2, f3, t_min, t_max, n);+ \\
   \verb+    clipplot(f1, f2, f3, t_min, t_max, n);+

    Draws an orthogonal perspective plot of $\bigl(f_1(t), f_2(t),
    f_3(t)\bigr)$, with $n+1$ points. If @code{viewpoint} is not
    set, @code{plot} simply drops the third coordinate. For brevity,
    the function may be declared to be @code{triple}-valued, as with
    plane parametric curves. See other notes on perspective drawing
    above.

  \item Wire mesh plots %% \smallskip

   \verb+ wiremesh(triple Phi,P(a,b),P(c,d), Net(n1,n2),Net(N1,N2);+ \\
   \verb+ wiremesh(f1,f2,f3,  P(a,b),P(c,d), Net(n1,n2),Net(N1,N2);+ \\
   \verb+ wiremesh(   f1,     P(a,b),P(c,d), Net(n1,n2),Net(N1,N2);+

    Each component function is a function of two variables. These
    routines plot the wire mesh surface (without hidden line removal
    at present) given parametrically over the rectangle
    $[a,c]\times[b,d]$. The domain is divided into an $n_1\times n_2$
    grid, and the image curves are drawn at resolution $N_1\times
    N_2$. It is not necessary that $N_i$~be an integer multiple
    of~$n_i$, but the results will be strange if $N_i<n_i$, or if
    $N_i$ is small and not a multiple of~$n_i$.
  \index{Plotting!3-dimensional|)}

  \item Data plotting from a file

  The format for a data file is two floating-point numbers per line;
  comment lines begin with a {\tt\%}, and improperly formatted lines
  are ignored.

  \verb+     data_plot("filename", STYLE);+

  Reads data in the named file and plots the corresponding points. In
  addition to the @code{marker} styles listed in
  Table~\ref{table:markers} above, @code{STYLE} may be
  @code{PATH}, which connects the dots in the named file in the
  order they appear.

  \item Derivatives %% \smallskip

   \verb+     plot_deriv(f, a, b, n);+

    Plots the derivative~$f'$ for $t\in[a,b]$, computed as a symmetric
    Newton quotient 
	$$ 
	\frac{f(t+dt)-f(t-dt)}{2\,dt}\qquad \qquad 
	dt=\frac{b-a}{2*n*@code{EPIX}\_@code{ITERATIONS}},
	$$
    with \verb+EPIX_ITERATIONS+ equal to~1000 by default.

  \item Tangent lines and vectors %% \smallskip

   \verb+     tan_line(pair f, t);+ \\
   \verb+     tan_line(f1, f2, t);+
   \verb+     tan_line(f, t);+

   \verb+     envelope(pair f, t_min, t_max, n);+ \\
   \verb+     envelope(f1, f2, t_min, t_max, n);+ \\
   \verb+     envelope(f, t_min, t_max, n);+

   \verb+     tan_field(pair f, t_min, t_max, n);+ \\
   \verb+     tan_field(f1, f2, t_min, t_max, n);+

    \verb+tan_line+ draws the @code{Line} (see page~\pageref{Line})
    tangent to the parametric curve or graph at the indicated
    time~$t$.  @code{envelope} draws the family of $n+1$ tangent
    @code{Line}s over the indicated interval, spaced equally with
    respect to ``time''.  Finally, \verb+tan_field+ plots tangent
    vectors. Because tangent vectors are rendered at true length, in
    total they form a rough piecewise-linear approximation of the
    curve, especially if~$n$ is large. The curve itself is not
    plotted.

  \item Integrals %% \smallskip

   \verb+     plot_int(f, x0, a, b, n);+ \\
   \verb+     plot_int(f, a, b, n);+

  Plots the definite integral $\int_{x_0}^x f(t)\,dt$ for
  $x\in[a,b]$. In the second form, $x_0=a$. Simpson's rule is used to
  compute the running sum; the step size is determined by the constant
  \verb+EPIX_ITERATIONS+.

  \item Vector fields %% \smallskip

   \verb+      slope_field(pair F, P(a,b), P(c,d), n1, n2);+ \\
   \verb+       dart_field(pair F, P(a,b), P(c,d), n1, n2);+ \\
   \verb+     vector_field(pair F, P(a,b), P(c,d), n1, n2);+

   \verb+      slope_field(f1, f2, P(a,b), P(c,d), n1, n2);+ \\
   \verb+       dart_field(f1, f2, P(a,b), P(c,d), n1, n2);+ \\
   \verb+     vector_field(f1, f2, P(a,b), P(c,d), n1, n2);+

  Graphs the slope field (fixed length, no arrows), dart field (fixed
  length, small arrowheads) or vector field (true length, arrows)
  $F=(f_1, f_2)$ on the specified rectangle, with
  $(n_1+1)\times(n_2+1)$ sample mesh. Slope lines and darts are
  guaranteed not to overlap, while vectors are drawn at true length.

  \item Solutions of planar ODEs %% \smallskip

   \verb+     ode_plot(pair F, P(a,b), t_max, n);+ \\
   \verb+     ode_plot(f1, f2, P(a,b), t_max, n);+

   Uses Euler's method to solve a system of ODEs starting at~$(a,b)$,
   attempting to follow the solution for time~$t_{\rm max}$ in
   $(n+1)$~steps. The plot terminates if it leaves the bounding box.

   \verb+flow_plot+ depicts flows of planar vector fields by tracking
   the behavior of an entire curve of points under the flow. The
   initial curve is traced by the @code{pair}-valued function~$f$ on
   the unit interval~$[0,1]$, and the plane evolves under the flow of
   the vector field $F=(f_1, f_2)$. Time runs from~0 to~\verb+t_max+,
   and @code{steps+1} snapshots are drawn, each with
   \verb+num_pts+~points.
\begin{verbatim}
  flow_plot(pair F, f, color, t_max, steps, num_pts);
  flow_plot(pair F, f, t_max, steps, num_pts);
  flow_plot(f1, f2, f, color, t_max, steps, num_pts);
  flow_plot(f1, f2, f, t_max, steps, num_pts);
\end{verbatim}
   The first form allows snapshots to be colored according to the
   amount of time elapsed; @code{color} is a @code{triple}-valued
   function, defined on the unit interval, whose value is interpreted
   as an~@code{rgb} color declaration. The second form draws all
   curves black. There is a @code{sample} file illustrating the use
   of this routine.

\ei

\paragraph{Non-Eucldean geometry} (@code{geometry.cc})

\bi
  \item Hyperbolic geometry

   Hyperbolic line segments are specified by their endpoints in the
   upper half plane or disk (Poincar\'e) models:

   \verb+     hyperbolic_line(P(a,b), P(c,d));+\\
   \verb+     disk_line(P(a,b), P(c,d));+

   In each case there is no output if either endpoint lies outside the
   model.

  \item Spherical geometry
   \index{Plotting!3-dimensional|(} 

   Curves on the unit sphere can be specified either by radial
   projection of a space curve, or by stereographic projection of a
   plane curve:
\begin{verbatim}
    plot_R(triple phi, t_min, t_max, n);
    plot_R(f1, f2, f3, t_min, t_max, n);
    plot_N(f1, f2, t_min, t_max, n);
    plot_S(f1, f2, t_min, t_max, n);
\end{verbatim}
   Attempts to perform radial projection on a path through the origin
   will generate division-by-zero errors. Stereographic projection
   maps the equatorial plane $\{x_3=0\}$ to the unit sphere by
   projection from the corresponding pole: $N=(0,0,1)$, $S=(0,0,-1)$.

   Each spherical plot routine accepts a prefix @code{front} or
   @code{back} that prints only the portion of the path visible or
   invisible (respectively) from the current @code{viewpoint}. 

   Because of the way \ePiX\ layers output, it is generally best to
   put hidden portions of the input before visible portions, with line
   width and/or style that suggests hidden lines.
  \index{Plotting!3-dimensional|)}
\index{Plotting|)}

\ei

\paragraph{Arcane features} (@code{arcana.cc})

\bi
   \item Planar linear transformations

   \verb+std_F(P(a1,b1), P(a2,b2));+ draws the image of the unit
   square under the linear transformation corresponding to the matrix
   whose columns are $(a_1,b_1)$ and $(a_2,b_2)$. The parallelogram
   contains the image of the ``standard~F'':

    \begin{center}
    \input{lin_transf.eepic}
    \end{center}

   \item Profiles of surfaces of revolution

   \verb+     plot_profile(f, a, b, n);+

    Not intended for general use, but documented anyway. Suffice it to
    say that a ``profile'' plot solves a certain differential equation
    and plots the solution. If~$f$ is a quadratic polynomial, the
    resulting curve will be the profile of a surface of revolution of
    constant Gaussian curvature.

   \item \index{Fractal curves|(} Recursively-generated
    piecewise-linear fractal curves

    Consider a path made up of equal-length segments that can point at
    any angle of the form~$2\pi k/n$, for $0\leq k<n$, like spokes on
    a wheel. The path is specified by a finite sequence of integers,
    taken modulo~$n$. For example, if $n=6$, then the sequence $0, 1,
    -1, 0$ corresponds to the ASCII path \verb+_/\_+. \ePiX's fractal
    generation routine starts with such a ``seed'' then recursively
    (up to a specified depth~$D$) replaces each segment with a scaled
    and rotated copy of the seed. The seed above generates the Koch
    fractal, for instance.

   \verb+    fractal(P(a,b), P(c,d), D, seed);+ \\
    @code{seed} is declared in the preamble as (e.g.)

    \verb+    const int seed[] = {6, 4, 0, 1, -1, 0};+

    The first entry (here~6) is the number of ``spokes''~$n$, the
    second~(4) is the number of terms in the seed, and the remaining
    entries are the seed proper. The final path joins $(a,b)$~to
    $(c,d)$. The number of segments in the final path grows
    exponentially in the depth, so depths larger than 5~or 6 are not
    likely to work: \LaTeX\ may crash, or the machine may even run out
    of memory, depending on the length of the seed. At large depth,
    the output will probably suffer from round-off error even if the
    figure renders.

\begin{figure}[hbt]
  \begin{center}
  \input{koch.eepic}
  \end{center}
  \caption{Successive iterations of \{@code{4,8,0,1,0,3,3,0,1,0}\}}
\end{figure}
\index{Fractal curves|)}
\ei

\section{Customizing}
\label{section:custom}

As mentioned in the introduction, \ePiX\ is extensible. There are two
general methods: modify the source code before compiling, or create a
custom header file for use at run time. The latter is analogous to
creating a \LaTeX\ macro file, requires less knowledge of~\CXX, and is
the only method available to users of a multi-user system. The former
is more powerful, since you have access to the features of the
compiler, not just the \CXX\ pre-processor.

\subsection*{Macro Files}

A \CXX~macro file conventionally has suffix~@code{.h}, as in
@code{myheader.h}. To use this custom header, put a line
\verb+#include "myheader.h"+ in your source file.

Macros are not directly seen by the compiler, and their syntax is
slightly different from \CXX~syntax. The most salient differences are
that lines do not end with a semicolon, and that complicated
replacements must fit on a single line. A line that ends with a
backslash ``continues'' on the next line. (Think of the combination
backslash-newline as an escape sequence that causes the newline to be
ignored.)

A @code{\#define} directive causes (more-or-less) literal
substitution to be performed. Here are some representative examples
that could go in a custom header file:
\begin{verbatim}
  #define Bold pen(1.5)
  #define purple rgb(0.5, 0, 0.7)
  #define square(s) rect(P(-(s), -(s)), P((s), (s)))
\end{verbatim}
The third example is a \emph{parametrized}\/ macro; when used, the
expression~@code{s} is placed into the replacement text literally:
\begin{verbatim}
  square(5); --> rect(P(-(5), -(5)), P((5), (5)));
  square(1+sqrt(2)); --> rect(P(-(1+sqrt(2)), ... );
\end{verbatim}
The pre-processor is not as smart as the compiler, and can be confused
by extra or missing space. Similarly, the pre-processor knows almost
nothing of grammar, so excessive parentheses are needed in the macro
definition to prevent unintended grouping when literal substitution is
performed. The classic example is \verb+#define sq(x) x*x+, which
causes \verb@sq(1+1)@ to expand to~3 (\verb@1+1*1+1@).

Some of \ePiX's routines are macros; @code{grep}-ing for
@code{\#define} directives in the source code (particularly
@code{legacy.h}) should suggest other possibilities for macro use.

\subsection*{Changing the Source}

Certain minor changes to the source code are easy. Some of the
parameters in @code{globals.h} (such as \verb+EPIX_ARROWHEAD_WIDTH+)
can be tweaked before compiling. To add substantially new features,
please consult the file @code{README-authors} in the source package
for information on naming conventions, existing header file
dependencies, and structuring new source files (including compiler
symbols that must be defined in order for new modules to compile
properly).

\subsubsection*{Design Goals}
\index{Naming conventions|(} 

The primary considerations in designing and writing a module are
functionality, ease of use, consistency, and compatibility, both
backward and forward. Functionality is in the eye of the user, and is
therefore beyond the scope of a manual. Ease of use is also
subjective; a rough definition is: ``The functionality can be used
without consulting the manual each time.'' Consistency is related to
ease of use, and means that analogous features should be called by
analogously named routines. An example is the use of \LaTeX\ names for
@code{marker} types. Another is the general grouping, in a
@code{plot} command, of functions, bounds on the input variable(s),
and number of points to plot, in that order.  Existing routines that
violate these principles raise to the thorny issue of compatibility,
see also Section~\ref{section:changes}.

Users have a right to expect that files they write today will be fully
functional tomorrow.\footnote{Expectations fostered by certain
software companies notwithstanding.} Unfortunately, one cannot know in
advance which features will be useful, and which will fall into
obscurity with time. A prudent author will, when introducing a new
family of routines, give it a descriptive, uniquely identifying
name. The GNU-style \verb+legible_function_name+ convention, lowercase
names with words separated by underscores, works well but should not
be considered mandatory if you have a strong preference for another
style. Naturally, there is a balance between making a name
descriptive, and making it too cumbersome for frequent use. However,
the importance of choosing a \emph{unique}\/ name is this: If the
routine eventually justifies a shorter name (because it is used so
commonly), it can be re-named in \CXX~code, and the original name
retained as a pre-processor macro with almost no run time
overhead. This process of ``namespace natural selection'' helps ensure
backward and forward compatibility, at the relatively minor cost of
forcing the use of descriptive but overly-long names for an initial
period.

While these conventions are less important for individuals' macro
files, they do bear consideration, since a short, sweet macro name
might later conflict with a routine in the source package. A
one-letter macro is almost surely a bad idea.
\index{Naming conventions|)} 

\section{Syntax Changes}
\label{section:changes}

As mentioned above, one of the principle design goals of \ePiX\ is
backward compatibility: Old input files should work with new versions
of \ePiX. However, on rare occasions changes to \ePiX\ will
necessitate new syntax in input files. This section details such
changes.

\subsection*{Changes from Version 0.8.5}
\index{Updating!from Version 0.8.5|(} 

\label{page:legacy} 
Three classes of names have been removed from the core library:
prefixed path style names (e.g., @code{dashrect} for a dashed
rectangle), Version~0.6.x plot names (@code{paramplot},
@code{plot3d}, \verb+quad_spline+, etc.), and primary color scope
endings (\verb+end_blue+, etc.). The @code{legacy} subpackage is
provided \emph{solely}\/ to facilitate processing old input files
(should this be necessary for some reason). To install the
@code{legacy} capabilities, build \ePiX\ with the command
\begin{verbatim}
make contrib legacy test
\end{verbatim}
then install normally.

Legacy features will eventually be removed from the distribution
package, and should not be used in new source files.  The removal of
prefixed path styles is the last major input syntax change for the
foreseeable future. Though necessitated by the increasing difficulty
of maintaining and extending \ePiX's plotting capabilities, the change
should simplify life for users, as well. Line width, path styles, and
colors are now handled uniformly, objects' names are shorter, and the
installed components (as well as the source code itself) will be
considerably smaller if @code{legacy} is not installed.
\index{Updating!from Version 0.8.5|)}

\subsection*{Changes from Version 0.8.4}
\index{Updating!from Version 0.8.4|(} 

The declarations of primary colors no longer require (or permit) the
``empty parentheses'' typified by @code{red()} but instead are
accomplished by the simpler @code{red}. The same is true of
@code{bold} and \verb+end_bold+.

As a related stylistic note, color declarations should be ended by a
new declaration, often @code{black}, and not with a deprecated call
such as \verb+end_red+. This change is not (yet) mandatory, however.
\index{Updating!from Version 0.8.4|)}

\subsubsection*{The Update Script}
\index{Updating!source files|(} 

Input files for versions up to and including~0.8.4 can be brought into
compliance with~0.8.5 by means of a shell script,
\verb+update_figs.sh+ included with the source code. This script
should be used only if existing files must be re-processed, but are
broken by a new version of \ePiX, not if input files compile with the
current version. The script must be run in each directory containing
source files that require updating.

\verb+update_figs.sh+ acts on files in the current directory that seem
to be \ePiX\ source files, namely that contain the string
@code{epix.h} and have an extension @code{.c}, @code{.cc},
or~@code{.C}. There are failsafe measures (for example, a
@code{quit} option that makes no file modifications), but the update
script should not be run heedlessly.  Running once is non-destructive:
Original versions of modified files are either preserved with the
extension @code{.old}, or are archived. However, the name of the
archive file is hard-wired (\verb+update_figs.tar.gz+), and files with
extension @code{.old} will be overwritten, so running the script
twice in the same directory will destroy the original versions of
files meeting the criteria above.\index{Updating!source files|)}

\section{Troubleshooting}
\label{section:problems}

\subsection{Installation}

\index{Installation|(emph}
Three files comprise \ePiX: a shell script (@code{epix}), a header
file (@code{epix.h}), and a compiled library
(@code{libepix.a}). All of these files are generated at compile
time, using variables found in the @code{Makefile}.  The utility
scripts @code{laps}~and @code{elaps} are part of the distribution,
but independent from \ePiX\ proper. These components are placed into
standard locations where they can find each other. There is also a
short @code{man} page, though this document is the primary
documentation.

\subsubsection*{Installation Problems}
\index{Troubleshooting!installation|(}

Public installation (in @code{/usr/local}) is the default. Unpack the
tar file, then @code{cd} to the source directory
(\verb+epix-0.8.x+). If you are installing in @code{/usr/local},
your \CXX~compiler is~@code{g++}, and @code{bash} is in
@code{/bin/bash}, then do 
\begin{verbatim}
make test
make contrib (optional)
make install
\end{verbatim}
(the last as
@code{root}).\index{ePiX@\ePiX!contrib@\texttt{contrib}} If
@code{bash} is not in @code{/bin/bash}, edit the script
@code{newbash.sh} and run it in the source directory.  If the
install directory or compiler are not as above, edit the
@code{Makefile} accordingly, then build. If a failed partial compile
creates the header file @code{epix.h}, you \emph{must}\/ do
@code{make clean} before re-compiling.

If you have installed in {\tt\$HOME}, please see the
@code{POST-INSTALL} file for additional instructions. 

The directory in which you install \ePiX\ is denoted
{\tt\$INSTALL}. After a successful @code{make install}, you will
have the following files:
\begin{verbatim}
    $INSTALL/bin/epix    $INSTALL/include/epix.h
    $INSTALL/bin/laps    $INSTALL/lib/libepix.a
    $INSTALL/bin/elaps   $INSTALL/man/man1/epix.1  
\end{verbatim}
and sample documents in @code{\$INSTALL/share/epix}.  There is a
@code{tar} file that contains all the samples, so users can copy
them to a convenient place and experiment without modifying the
originals.\index{ePiX@\ePiX!sample files}

\paragraph{Command not found} In order to use \ePiX, the directory
{\tt\$INSTALL/bin} must be in your @code{PATH} (see 
@code{POST-INSTALL}); type\\
@code{echo \$PATH}\\
\noindent to see your @code{PATH}. If the directory
@code{\$INSTALL/bin/} is not in your @code{PATH}, please read
@code{POST-INSTALL} or ask someone knowledgeable at your site for
help; the procedure varies depending on what shell you use. In any
case, you will need to modify your shell's configuration file.

\paragraph{Permission denied} This is  unlikely, but
conceivable. For each component of the program, do a long listing,
e.g. \\
@code{ls -l \$INSTALL/bin/epix} \\
and so forth. The header and library must be readable, and the shell
scripts and directories must be readable and executable. From the
install directory, do
\begin{verbatim}
chmod 0755  bin  include  lib  bin/epix  bin/laps  bin/elaps
chmod 0644  include/epix.h  lib/libepix.a  man/man1/epix.1
\end{verbatim}
\index{Installation|)}

If you still cannot get \ePiX\ to run, please send email to the
author, briefly describing the errors you are getting, the type of
system you are on, and so forth.
\index{Troubleshooting!installation|)}

\subsection{\LaTeX\ Errors}
\index{Troubleshooting!LaTeX problems@\LaTeX\ problems|(}

There are a few things that can cause \LaTeX\ to stop with an error
message when reading an \eepic\ file written by \ePiX. The most common
is the appearance of @code{nan} (not a number) where \LaTeX\ expects
a number. This generally indicates division by zero or bad
exponentiation.

When a number is very small, \ePiX\ may write it in exponential
notation. If this happens, \LaTeX\ will pause with an error message
when it tries to read, e.g., {\tt1.4142135e-14}. This bug in \ePiX\
has been addressed; please send the author a bug report if you
encounter this behavior. You can manually edit the \eepic\ file,
replacing underflows with~$0$. In this eventuality, it's wise to
rename the edited file, lest \ePiX\ overwrite your changes the next
time you run it.

Overflow errors are possible if a point has coordinates larger
than~$2^{16}$; make sure you're not trying to plot the graph of a
pole or something similar.

Occasionally \ePiX\ will not generate any data points after it starts
a path; this may signify a variable whose value is not what you expect
(particularly in a loop), a badly defined function, or a bug in
\ePiX. If you cannot resolve the problem, and have narrowed down the
issue to a small input file, please send the author a copy of the file
and an explanation of the problem.

\LaTeX\ has limited memory, and cannot plot arbitrarily many
points. Make sure you did not accidentally append a digit to the
number of points to be plotted; 500~data points should be fine, but
5000~will almost surely cause problems. If necessary, a long list of
data points in a @code{path} can be broken into groups of a few
hundred (see @code{fractal}, in @code{arcana.cc}), but even so
\LaTeX\ will eventually overflow. Don't expect to render a bitmap as
an array of colored boxes in \LaTeX.~$\ddot\smile$

One of the benefits of \eepic\ files is that they're plain
text. \ePiX\ comments its output, which should assist you in
debugging. Each object or plot command in the input file generates a
stanza in the output file that has a label saying which function wrote
the stanza.

If a run of \ePiX\ is taking unusually long (more than a few seconds
on a 400~MHz machine), it's a good idea to kill the process by typing
@code{ctrl-C} and to inspect the output for signs of a problem, such
as an infinite loop. On a fast PC, \ePiX\ can write a couple of
megabytes per second,\footnote{The 15~MB/sec figure quoted in earlier
versions was true when \ePiX\ was written in~\C.}  which will quickly
fill up your disk and possibly damage other files. Do not run \ePiX\
as @code{root} for normal usage!  
\index{Troubleshooting!LaTeX problems@\LaTeX\ problems|)}

\section{Feedback and Political Blurb}
\index{Free software|(emph} 

Feedback about this program (bug reports, requests for features, etc.)
is welcome. Suggestions for index entries are particularly sought!  If
you find \ePiX\ useful, please tell your colleagues about it.

Academics in general, and mathematicians in particular, depend on Free
software in their work. A good case can be made that proprietary
software is contrary to the academic ethic. Issues of access aside, if
one does not know what exactly went into a program, then one cannot
fully trust the results that come out, any more than one can trust
(for purposes of scientific publication) results of a commercial
testing lab.  Access to the source code is not all that is required,
though. To promote the dissemination of information, access to
software should be free in the four senses laid out in the GNU General
Public License authored by the Free Software Foundation: \\
$\bullet$ To run a program for any purpose \\ %(freedom 0). 
$\bullet$ To study how the program works, and adapt it to your needs \\
%(freedom 1).
$\bullet$ To redistribute copies of the program \\ %(freedom 2). 
$\bullet$ To improve the program, and release your improvements to the
public, so that the whole community benefits %(freedom 3).

Just as theorems are not licensed, I believe that software we use in
our academic work should not be licensed. Releasing software under a
standard commercial license agreement is (to me) the equivalent of
publishing the statement of a theorem, while keeping the proof secret,
and charging people for each citation of the theorem. Releasing source
code alone, without giving users the freedom to modify it for their
own needs, is analogous to publishing a proof, but forbidding readers
from using the ideas of the proof in their own work.

The ultimate purpose of software is to allow us to be productive and
creative. I hope that this modest program is, in conjunction with the
much larger efforts of others (especially Donald Knuth, Richard
Stallman, and the many people who have contributed to the authorship
of \LaTeX\ and its packages), useful to you in your mathematical work.

Please visit the Free Software Foundation, at
\verb+http://www.fsf.org+, to learn more about Free Software and how
you can contribute to its development and adoption.
\index{Free software|)}

\clearpage

\printindex

\end{document}

@bye
