summaryrefslogtreecommitdiff
path: root/graphics/epix/doc/manual.tex
diff options
context:
space:
mode:
Diffstat (limited to 'graphics/epix/doc/manual.tex')
-rw-r--r--graphics/epix/doc/manual.tex5030
1 files changed, 5030 insertions, 0 deletions
diff --git a/graphics/epix/doc/manual.tex b/graphics/epix/doc/manual.tex
new file mode 100644
index 0000000000..71aa59aa97
--- /dev/null
+++ b/graphics/epix/doc/manual.tex
@@ -0,0 +1,5030 @@
+%% Version 1.2.0
+\documentclass[12pt]{book}
+\usepackage{amsmath,latexsym,epic,eepic,pstricks,xcolor,comment}
+\usepackage[dvips,hyperref]{hyperref}
+
+\usepackage{makeidx}
+\makeindex
+
+\renewcommand{\thefigure}{\arabic{chapter}.\arabic{figure}}
+
+\newcommand{\code}[1]{\texttt{#1}}
+\newcommand{\filename}[1]{\texttt{#1}}
+\newcommand{\Key}[1]{\texttt{#1}}
+\newcommand{\URL}[1]{\texttt{#1}}
+
+%% \setlength{\topmargin}{0.5in}
+\newcommand{\ePiX}{\code{ePiX}}
+\newcommand{\ext}{\code{ePiX\_ext}}
+\newcommand{\epix}{\code{epix}}
+\newcommand{\eepic}{\code{eepic}}
+\newcommand{\C}{\code{C}}
+\newcommand{\CXX}{\code{C++}}
+\newcommand{\pyepix}{\code{Pyepix}}
+
+\DeclareMathOperator{\clip}{clip}
+
+\newcommand{\Header}[1]{\smallskip\noindent\texttt{#1}%
+ \index{Header file!{#1}@\texttt{#1}}\quad}
+
+%% Substitution commands easily removable by sed for texinfo:
+%% Remove recalcitrant chunks,
+\newcommand{\texicomment}{}
+\newcommand{\texicommentend}{}
+
+%% mark simple math,
+\newcommand{\teximath}[1]{$#1$}
+%% make function index entries,
+\newcommand{\findex}[1]{}
+
+%% top-level division (first argument for texinfo node name)
+\newcommand{\texinfochapter}[2]{\chapter{#2}}
+\newcommand{\texinfoappendix}[2]{\chapter{#2}}
+
+%%\renewcommand{\subsection*}[1]{\subsection{#1}}
+
+\title{ \ePiX\ Tutorial and \\ Reference Manual}
+\author{Andrew D. Hwang \\
+ Department\ of Math and CS \\
+ College of the Holy Cross}
+\date{Version 1.2, September, 2007}
+
+\begin{document}
+
+\maketitle
+
+\tableofcontents
+
+\texinfochapter{1}{Introduction}
+
+\ePiX, a collection of batch utilities, creates mathematically
+accurate figures, plots, and animations containing \LaTeX\ typography.
+The input syntax is easy to learn, and the user interface resembles
+that of \LaTeX\ itself: You prepare a scene description in a text
+editor, then ``compile'' the input file into a picture. \LaTeX- and
+web-compatible output types include a \LaTeX\ picture-like environment
+written with \code{PSTricks}, \code{tikz}, or \code{eepic} macros;
+vector images (\code{eps}, \code{ps}, and~\code{pdf}); and bitmapped
+images and movies (\code{png}, \code{mng}, and~\code{gif}).
+
+\ePiX's strengths include:
+
+\begin{itemize}
+\item Quality of output: \ePiX\ creates accurate, publication-quality
+ figures whose appearance matches that of \LaTeX. Typography may be
+ put in a figure as easily as in an ordinary \LaTeX\ document.
+
+\item Ease of use: Figure objects and their attributes are specified
+ by simple, descriptive commands.
+
+\item Flexibility: Objects are described by attributes and Cartesian
+ location; as in \LaTeX, printed appearance is determined when the
+ figure is compiled. A well-designed figure can be altered
+ dramatically, yet precisely, with command-line switches or minor
+ changes to the input file.
+
+\item Power and extendibility: \ePiX\ inherits the power of \CXX\ as a
+ programming language; variables, data structures, loops, and
+ recursion can be used to draw complicated plots and figures with
+ just a few lines of input. External code can be incorporated in a
+ figure with a command line option or by using a Makefile.
+
+\item Economy of storage and transmission: For a document containing
+ many figures, a compressed tar file of the \LaTeX\ sources and
+ \ePiX\ files is typically a few percent the size of the compressed
+ PostScript file.
+
+\item License: \ePiX\ is \emph{free software}.\index{Free software}
+ 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. In
+ short, the license is similar to the terms under which theorems are
+ published.
+
+\end{itemize}
+
+
+\ePiX\ facilitates logical, as opposed to visual, structuring of
+mathematical figures, analogous to the relationship between \LaTeX\
+and a word processor. A few stylistic defaults streamline the creation
+of simple figures, but there are few internal restrictions on the
+contents or appearance of a figure; aesthetic and practical decisions
+are left to you.
+
+If you are a:
+
+\begin{itemize}
+
+\item Potential user, you may wish to skip immediately to ``Software
+ Dependencies'' before investing additional time.
+
+\item New user, proceed from here until you have enough understanding
+ to run the software, then experiment with the samples files while
+ reading Chapter~\ref{chapter:started}, or return to the manual as
+ needed.
+
+\item More advanced user, browse at will, probably starting with
+ Chapter~\ref{chapter:ref-man}.
+
+\end{itemize}
+
+This manual is relatively conversational, and occasionally redundant,
+especially between portions meant for readers at different levels of
+familiarity. Throughout, you are assumed to be familiar with \LaTeX\
+and basic linear algebra: the description of points, vectors, lines,
+and planes in three-dimensional space. Other material, such as \CXX\
+syntax, is introduced as needed.
+
+
+\section{Changes in Version~1.2}
+
+\ePiX~1.2.x has been written almost entirely from scratch. The
+conceptual model is unchanged, but there are a few changes of
+syntax. If you're new to~\ePiX, please skip straight to
+Section~\ref{section:software_deps}.
+
+
+\subsection{Syntax Changes}
+
+Except as noted below, \ePiX~1.0 files will compile under
+Version~1.2. Generally, global variables have been deprecated or
+removed, and should be replaced by function calls in new files. The
+following changes are either required, or else strongly recommended
+(and may become mandatory).
+
+\begin{itemize}
+
+\item (Mandatory) The global variable \verb+tix+ in a \filename{flix}
+ file must be manipulated through the function \verb+tix()+.
+
+\item (Mandatory) The command \code{use\_pstricks()} is obsolete.
+ PSTricks output is obtained systematically as an output format.
+
+\item (Mandatory) Deprecated ``aliases'' no longer exist:
+ \code{triple} (for the \code{P} class), \code{D}~(for \code{Deriv}),
+ and \code{I}~(for \code{Integral}). Lowercase trig function names
+ conflicted with the standard namespace and have been removed.
+
+\item (Mandatory) Geometric object commands (\code{circle},
+ \code{plane}, \code{segment}, and~\code{sphere}), which formerly
+ created class objects, now perform drawing just as \code{ellipse},
+ \code{line}, \code{rect}, etc., do. The classes are available with
+ capitalized names (\code{Circle}, etc.).
+
+\item (Mandatory) Camera orientation is controlled with functions
+ named \code{tilt}, \code{pan}, and~\code{roll}; each rotates
+ the camera about an axis through the viewpoint, not through the
+ target.
+
+\item (Recommended) The global size variables \verb+x_min+,
+ \verb+x_max+, \verb+y_min+, \verb+y_max+, \verb+x_size+, and
+ \verb+y_size+ should be replaced by the function calls
+ \verb+xmin()+, etc. (No underscores.)
+
+\item (Suggested) The camera may be accessed through the function
+ \code{cam()}.
+
+\item (Suggested) The size and bounding box are given in one command,
+ such as \code{picture(P(-1,0), P(1,1), "4x3in")}. The old syntax
+ will be retained indefinitely.
+
+\end{itemize}
+
+
+\subsection{New Features}
+
+\begin{itemize}
+
+\item Output is cleanly separated from the internal representation.
+ Figures may be written with a choice of macros---\code{PSTricks},
+ \code{tikz}, and \code{eepic} at present---and new output types
+ are easily coded so long as the format supports arbitrary line
+ segments, color, and the ability to place a \LaTeX\ box at a
+ specified location.
+
+\item Colors are a manipulable data type, available in RGB, CMY, CMYK,
+ and Gray models. \filename{xcolor}-style operations, such as color
+ model conversion, blending, superposition, and inversion are
+ provided.
+
+ The camera has a filter which affects the colors of all scene
+ elements. Filters performing CMYK separation are provided.
+
+\item Color filling is controlled with declarations, similarly to line
+ colors in \ePiX~1.0. Arrows and markers of type spot, dot, ddot,
+ and~circ are now colored like other markers. Parametric surfaces
+ may be color-shaded.
+
+ If a figure contains many shaded elements, a color-capable output
+ format (e.g.\ \code{PSTricks}~or \code{tikz}) should be used for
+ efficiency. Filled regions are implemented as fine hatching in
+ \filename{eepic}.
+
+\item An \code{axis} class provides coordinate axes with labels in a
+ variety of styles: decimals or scientific notation of specified
+ precision, fractions, trig fractions, logarithmic labels in
+ arbitrary (integer) base, and user-supplied styles.
+
+\item \ePiX~1.2.x performs page layout. Sub-figures may be manipulated
+ flexibly. The sample files give several applications.
+
+\item Non-member intersection operators for circles, planes, spheres,
+ and segments are provided. A ``non-generic'' intersection does not
+ throw an exception, but instead returns an undrawable ``malformed''
+ object.
+
+\end{itemize}
+
+
+\section{Software Dependencies}
+\label{section:software_deps}
+
+\index{Installation|(}
+\index{Mac OS X}
+
+If you run GNU/Linux, a BSD, or Solaris, you probably have (and can
+surely install) all the external software needed to use \ePiX. On
+Mac~OS~X, you will need the Apple developer tools and an X~server
+(XCode and XDarwin on the Tiger disks), and the free~\code{fink}
+package manager to build a GNU environment. For Windows, you'll need
+to install Cygwin and several packages. Detailed instructions are
+given below.
+
+``Under the hood'', an input file is successively converted to a
+\LaTeX\ picture; \code{dvi}; PostScript, \code{pdf}~or \code{eps}; and
+if desired, to a bitmapped image or movie. Four shell
+scripts---\epix, \code{laps}, \code{elaps}, and~\code{flix}---automate
+the various file format conversions.
+
+\ePiX\ consists of a \CXX\ library, header, and shell scripts, and
+requires GNU \code{bash} and a compiler \emph{for normal use}. For
+complete functionality, you need \code{g++} (Version~3.2 or later),
+\code{bash}, a text editor (\ePiX\ works particularly well with
+\code{emacs}), a \LaTeX\ distribution, \code{Ghostscript}, \code{gv}
+(or your favorite PS/PDF previewer), and \code{ImageMagick}. GNU
+\code{grep} and \code{sed} are good to have. You may need additional
+``developer packages'' (\code{binutils}, \code{make}) in order to
+build \ePiX. The more up to date your software is, the better your
+experience is likely to be, but bleeding edge versions are not
+necessary, or even always desirable.
+
+Aside from their reliance on specific programs, \ePiX's shell scripts
+are written using Unix-style pathnames. Thus, the most straightforward
+way to use \ePiX\ is to install a GNU environment.
+
+Jay Belanger's \code{emacs} mode allows you to write, compile, and
+view \ePiX\ figures without leaving \code{emacs}. If you use another
+editor, you'll want to create template source files so you don't have
+to type boilerplate code each time you write a new figure.
+\index{Emacs@\code{emacs}}
+
+
+\subsection{Setting up an Environment Under Windows}
+
+\index{Windows operating system|(}
+\begin{comment}
+Version~1.0.4 of \ePiX\ has been implemented in Python~2.2 by Andrew
+Sterian, making \ePiX\ available on any platform that supports Python,
+and without requiring a \CXX~compiler or~\code{bash}. Python is a
+GPL-ed scripting language, and is available with a Windows installer
+and detailed instructions. The easiest alternative for Windows users
+is probably to install Python~2.2 or later (if necessary) and
+\code{Pyepix}. The \code{pyepix} project home page is:
+\URL{claymore.engineer.gvsu.edu/~steriana/Python/index.html}
+\end{comment}
+
+Cygwin can be used to run \ePiX\ under Windows. Download
+\filename{setup.exe} from \URL{www.cygwin.com}, then install the
+packages you need. The following are recommended, and sufficient for
+the actions described in this manual.
+\begin{verbatim}
+(Archive) bzip2, tar
+(Devel) binutils, coreutils, gcc, gcc-g++, make, sed
+(Editors) emacs, emacs-X11, vim
+(Graphics) ImageMagick, ghostscript-base, ghostscript-x11, gv
+(Publishing) tetex (all)
+(Shells) bash, bash-completion
+(X11) X-start-menu-icons, X-startup-scripts,
+ XFree86-lib-compat, xorg-x11-fscl, xorg-x11-fsrv
+\end{verbatim}
+\index{Windows operating system|)}
+
+
+\section{Installation}
+
+\ePiX\ is distributed over the World-Wide Web as source code. Packages
+may be found at \URL{mathcs.holycross.edu/\~{}ahwang/epix/ePiX.html}
+The latest stable release is also on the CTAN mirrors, in the
+\code{graphics} directory. (Some users of Red Hat have reported file
+permission problems when unpacking the CTAN tarballs. If you encounter
+this difficulty, please try downloading the sources from the project
+main page.) Unpack the compressed tar file with the appropriate
+command:
+\begin{verbatim}
+ tar -zxvf epix-x.y.z.tar.gz
+ tar -jxvf epix-x.y.z.tar.bz2
+\end{verbatim}
+(\code{x.y.z}~is the version number) or, if your \code{tar}
+doesn't do decompression,
+\begin{verbatim}
+ gunzip -c epix-x.y.z.tar.gz | tar -xvf -
+ bzcat epix-x.y.z.tar.bz2 | tar -xvf -
+\end{verbatim}
+\code{cd} to the source directory, \filename{epix-x.y.z}. The
+\filename{INSTALL} file contains detailed installation instructions.
+If you're impatient, the short of it is \code{./configure [--options];
+ make; make install}. Run \code{./configure --help} for a list of
+options.
+
+By default, \ePiX\ installs in subdirectories of
+\filename{/usr/local}; if you want to install elsewhere, supply
+\code{./configure} with the appropriate \code{--prefix}. You may also
+want to consult \filename{POST-INSTALL} for information on setting
+your \code{PATH} variable so your shell can find \ePiX. The manual
+and sample files are in \filename{/usr/local/share/doc/epix}.
+\index{Installation|)}
+
+
+\subsection{Development}
+
+There are two mailing lists, one for user questions, one for
+development discussion. Please visit
+\URL{savannah.nongnu.org/mail/?group=epix} to subscribe.
+
+
+\texinfochapter{2}{Getting Started}
+\label{chapter:started}
+
+This chapter describes the basics of creating figures in \ePiX\ for
+readers familiar with \LaTeX\ but completely new to~\CXX. No detailed
+knowledge of~\CXX\ is needed to use \ePiX, only a bit of grammar that
+is easily absorbed by example.
+
+Section~\ref{section:running} describes the commands (shell scripts)
+comprising \ePiX, and explains how to set up a graphical environment
+using standard *nix programs. Section~\ref{section:overview} briefly
+describes figure creation. Section~\ref{section:tutorial} presents a
+few files side-by-side with their output, and should be read at a
+computer so you can run the exercises.
+
+
+\section{Running \ePiX}
+\label{section:running}
+
+An ``input file'' is a human-written figure specification containing
+\ePiX\ commands. An ``output file'' is machine-created, and is
+included directly into a \LaTeX\ document with the appropriate
+packages.
+
+Conversion (``compiling'' a figure) is accomplished with four shell
+scripts, \code{laps}, \code{epix}, \code{elaps}, and \code{flix}.
+Each script has a preferred extension for its input files, and is
+invoked with a command of the form
+\begin{verbatim}
+ <script> [options] <input file(s)>
+\end{verbatim}
+Often, no options are necessary. \code{<script> --help}
+describes \code{<script>}'s options.
+\texicomment
+Figure~\ref{fig:programs} (page~\pageref{fig:programs}) diagrams the
+shell scripts and the file types they process.
+\texicommentend
+
+By default, output file names are constructed by replacing the input
+extension with the (preferred) output extension. For brevity,
+extensions may be omitted. If the script has doubts about your intent,
+it proceeds with default behavior and prints a warning message.
+
+The author is a great fan of \Key{TAB} completion, under which a
+shell, based on what has been typed so far, automatically fills in a
+command when the \Key{TAB} key is pressed. \ePiX\ comes with code
+snippets that complete intelligently when the first part of a command
+is one of the shell scripts. For example, if command completion is
+active, typing \code{epix} \Key{TAB} prints only names of \code{epix}
+input files. To use this feature, you must install Ian MacDonald's
+\code{bash completion} package. The \filename{INSTALL} and
+\filename{POST\_INSTALL} files contain details.
+
+
+\subsubsection*{\code{laps}}
+
+\code{laps} performs \LaTeX\ to PostScript/PDF conversion, and is
+independent of the rest of \ePiX. By default, \code{laps} invokes
+\LaTeX~and \code{dvips}. The option \code{--pdf} creates a PDF~file by
+post-processing the PostScript with~\code{ps2pdf}. Other \TeX-family
+processors (\code{pslatex}, \code{pdftex}, etc.) may be used instead
+of~\LaTeX\ by invoking \code{laps} with an appropriate option.
+
+
+\subsubsection*{\code{epix}}
+
+\code{epix} compiles an input file into a \LaTeX\ picture. The input
+file should have extension \filename{xp} (for eXtended Picture). Jay
+Belanger's \code{emacs} mode is Highly Recommended; the installation
+procedure can be found in the \filename{POST\_INSTALL} file. When this
+mode is active, \code{emacs} automatically inserts a preamble template
+when a new \filename{xp} file is created. In addition, you can peruse
+\ePiX's info file, or format, compile, and preview files, all from
+within \code{emacs}.
+\index{Emacs@\code{emacs}}
+
+Output files from the script \code{epix} have extension
+\filename{eepic}, after Conrad Kwok's enhancements to the \LaTeX\
+picture environment. In Version~1.2, however, an output file need not
+contain \code{eepic} macros at all.
+
+An output file is \code{input} directly into a \LaTeX\ document whose
+preamble contains appropriate \code{usepackage} lines.
+\texicomment
+\begin{center}
+ \begin{tabular}{cc}
+ Format & Required Package(s) \\
+ \hline
+ \code{eepic} & \code{epic,eepic,xcolor} \\
+ \code{pst} & \code{pstricks} \\
+ \code{tikz} & \code{tikz}
+ \end{tabular}
+\end{center}
+\texicommentend
+Rotated text requires the \code{rotating} package.
+
+
+\subsubsection*{\code{elaps}}
+
+\code{elaps} creates stand-alone vector images (\filename{eps}~or
+\filename{pdf}) from \code{epix} input files or \filename{eepic}
+figures, even those not produced with \code{epix}. \code{elaps}
+automatically loads the \LaTeX\ packages needed for features described
+in this manual. Additional \LaTeX\ packages and \code{dvips} options
+may be specified on the command line.
+
+
+\subsubsection*{\code{flix}}
+
+\code{flix} creates bitmapped images and movies,
+Section~\ref{section:animation}. Input files should have extension
+\filename{flx}, and must contain a valid \code{epix} header as well as
+additional code. Jay Belanger's \code{emacs} mode facilitates creation
+of \code{flix} files.
+
+
+\section{The Drawing Model}
+\label{section:overview}
+
+To draw a figure manually, you select a sheet of paper of appropriate
+size and add paths, markers, and labels. These scene elements have
+attributes (line color, line width, fill color, font size, etc.)
+affecting their appearance.
+
+\index{canvas}
+\ePiX's drawing model behaves similarly. A \code{picture} command
+sets the \emph{canvas} (or logical drawing area, a Cartesian
+rectangle) and the true size of the final figure. A \code{begin}
+command initializes the ``virtual paper'' for drawing. Subsequent
+\emph{drawing commands} add objects to the scene: lines, curves,
+function plots, labels, and the like. The printed appearance of scene
+elements is determined by the current ``attribute state'' and
+controlled by \emph{style declaration} which remain in effect until
+superseded. Finally, an \code{end} command closes the figure and
+prints it to the output file.
+
+In this manual, command descriptions follow a few
+conventions. Optional arguments are enclosed in square brackets. A
+\code{len} argument is either a number (representing a length in
+\code{pt}) or a double-quoted string containing a number and a
+two-letter \LaTeX\ length unit, such as \code{"1.5pt"} or
+\code{"6cm"}. A \code{color} argument is a named primary
+(\code{Red()}, \code{Cyan()}, \code{White()}, etc.), or a \code{Color}
+specified by densities (\code{RGB(r,g,b)}, \code{CMY(c,m,y)}, etc.)
+
+\begin{itemize}
+
+\item Fill color: \code{fill(color)}, \code{nofill()}.
+
+\item Line color and width: \code{plain([color])},
+ \code{bold([color])}.
+
+\item Text size: \code{font\_size([size])}, returns to
+ \code{normalsize} if no argument is given.
+
+\end{itemize}
+
+\noindent A complete list of style commands is found in
+Section~\ref{section:quickref}, starting on
+page~\pageref{section:quickref}.
+
+To handle three-dimensional scenes, a \code{camera} performs point
+projection from a selected spatial location to the canvas. As a user,
+you'll need to control relatively few of the \code{camera}'s
+parameters. Keep in mind, however, that elements are added to a scene
+in the same order their commands appear in the output file, and that
+later elements generally cover earlier ones. Some three-dimensional
+scenes require manual ordering of the input file; such ordering is
+dependent on the \code{camera}'s location.
+
+By default, \ePiX\ draws thin, solid, black lines, performs no filling
+of regions, prints text in a 12~pt Roman font, and looks down the
+\teximath{z}~axis from a large distance, giving orthogonal projection
+on the \teximath{(x,y)}~plane. When the \code{camera} is moved, the
+\teximath{z}~axis points vertically up on the page.
+
+
+\section{Tutorial}
+\label{section:tutorial}
+
+This section presents sample input files side-by-side with their
+output so you can compare what you write with what you'll see on the
+screen or page. \ePiX\ provides standard drawing capabilities, but
+like all software has its own idioms and personality. The basic
+syntax, which comes from \code{C}/\CXX, should be mostly
+self-explanatory. One-line comments begin with the
+string~``\verb+//+''.
+
+
+%%\index{Emacs@\code{emacs}}
+\index{Graphical interface}
+To use the sample files interactively, you'll need working software:
+\filename{bash}, \filename{emacs}, \ePiX, \filename{g++},
+\filename{gv}, and a running X~server. To complete your ``GUI'',
+start~\filename{gv} and select ``Watch file'' from the ``State''
+menu. The loaded file will update automatically when it changes.
+
+Create a ``scratch'' directory, \code{cd} into it, and run the command
+\begin{verbatim}
+ tar -zxf /usr/local/share/doc/epix/sample_src.tar.gz
+\end{verbatim}
+(Change the path as appropriate for your installation.) This unpacks
+copies of the sample files into your scratch directory, including all
+the files mentioned in this manual. The \filename{README} file serves
+as a table of contents.
+
+Open a sample file in \filename{emacs}, compile it from the drop-down
+menu (or with the keyboard command), then open the \filename{EPS} file
+in~\filename{gv}. Now you're ready to follow the tutorial
+interactively. A few suggested exercises are included with each
+file. Naturally, as you study more files, you'll be able to make more
+interesting changes on your own.
+
+
+\subsubsection*{Basic Drawing}
+
+The first sample, \filename{hello.xp}, contains code needed to specify
+the figure's size, followed by the classic greeting. The \code{border}
+command draws a box around the figure in the specified color and
+width, and serves here merely to delimit the output from the
+surrounding page.
+\begin{verbatim}
+/* -*-ePiX-*- */
+#include "epix.h" // These lines are analogous
+using namespace ePiX; // to a usepackage command.
+
+int main()
+{
+ picture(P(-1,-1), P(1,1), "2 x 1in"); // corners, true size
+
+ begin(); // ---- Figure body starts here ----
+
+ border(Black(), "1pt"); // color, line width
+
+ font_size("Huge"); // May be any font size, e.g. "scriptsize"
+ label(P(0,0), "Hello, world!");
+
+ end(); // ---- End figure; write output file ----
+}
+\end{verbatim}
+
+\begin{center}
+ \input{hello.eepic}
+\end{center}
+
+\begin{itemize}
+
+\item Change the color and width of the
+ border. (\code{RGB(r,g,b);} creates an RGB color, CMY colors are
+ analogous. Named primaries are available. The densities should be
+ between \teximath{0}~and \teximath{1} for ``expected'' behavior.)
+
+\item Add \code{backing(Cyan());} after the \code{border} command.
+
+\item Put the command \code{crop\_ellipse();} before the \code{border}
+ command. Permute the \code{crop\_ellipse} command with the
+ \code{border} and \code{backing} lines, and note how the attribute
+ (\code{crop}) affects objects (\code{border}, \code{backing}).
+
+\end{itemize}
+
+
+\subsubsection*{Geometric Objects}
+
+Our next file uses simple objects to draw a 2-D house-and-sun scene.
+
+\begin{verbatim}
+int main()
+{
+ picture(P(0,0), P(5,2), "3.75 x 1.5in");
+
+ begin();
+
+ triangle(P(0.9, 1), P(3.1, 1), P(2, 1.5)); // vertices
+ circle(P(4,1.5), 0.25); // center and radius
+
+ rect(P(1,0), P(3,1)); // opposite corners
+
+ fill(Black(0.1)); // light gray
+ rect(P(2.3,0), P(2.7,0.8)); // the door
+ nofill();
+
+ bold(); // draw thicker lines
+ grid(P(1.4, 0.2), P(2, 0.6), 2, 2); // corners, number of squares
+
+ line(P(xmin(), 0), P(xmax(), 0)); // endpoints
+
+ end();
+}
+\end{verbatim}
+
+\begin{center}
+ \input{objects.eepic}
+\end{center}
+
+\begin{itemize}
+
+\item Add declarations such as \code{bold(RGB(1,0.9,0.5))} or
+ \code{fill(Yellow())} to color the scene. (Color and filling are
+ orthogonal attributes.)
+\end{itemize}
+
+\noindent The sample file \filename{house.flx} uses loops to draw
+gradient fills of the lawn, sky, and sun, and animates a sunset.
+
+
+\subsubsection*{Function Plotting}
+
+Plotted functions must be defined in the ``preamble'', before
+\code{main}. ``High-level'' elements---coordinate axes and grids, axis
+labels, and graphs---are drawn with mnemonically-named commands.
+\begin{verbatim}
+// double = double-precision floating point
+double f(double x) { return 0.75*Sin(x) - 0.25*Sin(2*x); }
+
+int main()
+{
+ picture(P(-2,-1), P(2,1), "5 x 1in"); // [-2,2] x [-1,1]
+
+ begin();
+ revolutions(); // set angle units, [0,1] = one turn
+
+ h_axis(16); // axes w/default endpts
+ v_axis(4);
+ h_axis_labels(4, P(0,-4), b); // shift down 4pt, align below
+
+ plain(Red());
+ plot(f, xmin(), xmax(), 120); // use 120 intervals
+
+ end();
+}
+\end{verbatim}
+
+\begin{center}
+ \input{plotting.eepic}
+\end{center}
+
+\begin{itemize}
+
+\item Define and plot some different functions; adjust the bounding
+ box as necessary. (Use repeated multiplication for polynomials.
+ The \code{polarplot} command graphs \teximath{r=f(\theta)}.)
+
+\item Change the arguments to \code{h\_axis\_labels}. The first
+ specifies the number of intervals to label; the second gives the
+ label offset in~\code{pt}. The last puts each label below~(\code{b})
+ its Cartesian location.
+
+\end{itemize}
+
+
+\subsubsection*{Multivariable Plotting}
+
+Functions of two or three variables are defined just like functions of
+one variable, but for plotting the return type must be a
+point~(\code{P}), not a real number~(\code{double}). The \code{domain}
+class specifies the set of inputs to plot.
+
+\begin{verbatim}
+P f(double r, double th)
+{
+ return P(r*Cos(th), r*Sin(th), pow(r, 3)*Cos(3*th));
+}
+
+int main()
+{
+ picture(P(-1,-1), P(1, 1), "2 x 1in");
+ begin();
+ pst_format(); // use PSTricks macros for output
+
+ // corners ([0,1] x [0,2\pi]) and fineness
+ // (8x40 rectangles, plotted at 16x120 resolution)
+ domain R(P(0,0), P(1, 2*M_PI), mesh(8,40), mesh(16,120));
+
+ camera.at(P(3,1,2)); // set the viewpoint
+ arrow(P(0,0,0), P(1.25,0,0)); // coordinate axes
+ arrow(P(0,0,0), P(0,1.25,0));
+
+ plain(Blue(1.2)); // line color and width
+ fill(Yellow()); // shading color
+ surface(f, R);
+
+ end();
+}
+\end{verbatim}
+
+\begin{center}
+ \input{plotting2.eepic}
+\end{center}
+
+
+\subsubsection*{Loops and Control Structures}
+\label{taylor_poly}
+
+A function can be defined by an arbitrary algorithm, and a
+\code{domain} may be used to plot a family of functions for several
+values of one variable.
+
+\begin{footnotesize}
+\begin{verbatim}
+P sin_n(double x, double n) // Taylor polynomial of sin x
+{
+ const int N((int) floor(n)); // convert n to an index bound
+ const double sqx(-pow(x, 2)); // -x^2
+ double val(x), summand(x);
+
+ for (int i=1; i <= 2*N+1; i += 2)
+ {
+ summand *= (sqx/((i+1)*(i+2))); // (-1)^i x^{2i+1}/(2i+1)!
+ val += summand;
+ }
+
+ return P(x, val); // return (x, y)
+}
+
+int main()
+{
+ picture(P(0, -1), P(6*M_PI, 1), "5 x 1in");
+
+ begin();
+
+ set_crop();
+ bold(Green());
+ plot(Sin, 0, xmax(), 120);
+
+ domain R(P(0,1), P(6*M_PI, 41), mesh(60, 40), mesh(120, 40));
+ for (int i=3; 0 <= i; --i) // print in descending degree
+ {
+ bold(RGB(0.25*i, 0, 1-0.25*i)); // degree-dependent color
+ plot(sin_n, R.slice2(5*i+1)); // plot for n = 5i+1
+ }
+ end();
+}
+\end{verbatim}
+\end{footnotesize}
+
+\begin{center}
+ \input{plotting3.eepic}
+\end{center}
+
+
+\subsubsection*{Page Layout}
+
+Page layout can be composed from sub-pages with \code{screen} objects.
+In the loop body below, objects are added to the ``active''
+\code{screen}, then \code{inset} into the ``canvas'', the screen
+representing the entire figure.
+
+\begin{verbatim}
+P f(double u, double v)
+{
+ return P((u-v)*(u+v), 2*u*v, u);
+}
+
+int main()
+{
+ picture(P(0,0), P(2,3), "5x7.5in"); // overall size
+
+ begin();
+
+ domain R(P(-1,-1), P(1,1), mesh(12,12), mesh(24,24));
+
+ for (int i=0; i<2; ++i)
+ for (int j=0; j<3; ++j)
+ {
+ screen my(P(-3,-3), P(3,3));
+ activate(my);
+ border(Red(0.6), "1pt");
+ // frame-dependent viewpoint
+ camera.at(sph(10, (2*j+i+1)*M_PI/8, M_PI/6));
+
+ plot(f, R);
+ arrow(P(0,0,0), 2*E_1);
+ arrow(P(0,0,0), 2*E_2);
+ // SW corner at (i, 2-j), padded by 0.05 on all sides
+ inset(P(i+0.05,2.05-j), P(i+0.95,2.95-j));
+ }
+
+ end();
+}
+\end{verbatim}
+
+\begin{center}
+ \input{layout.eepic}
+\end{center}
+
+
+\section{\CXX\ Basics}
+
+\index{Cplusplus@\CXX|(}
+An \ePiX\ source file is a \CXX~program. If you've successfully
+modified and compiled the sample files, you know enough~\CXX\ to use
+\ePiX. In the author's experience, \code{C}~grammar suffices for most
+applications. An excellent introduction to definitions of functions
+and variables, control statements, and overall program structure is
+Kernighan~and Ritchie's \emph{The \code{C} Programming Language},
+second edition~\cite{KnR}.
+
+
+\subsection{File Format}
+
+\index{Emacs@\code{emacs}}
+Jay Belanger's \code{emacs} mode for \code{ePiX} inserts a file
+template when an empty buffer is opened with the extension~\code{xp}.
+This section explains the purposes served by the template. A few
+additional remarks may help you avoid basic syntax pitfalls.
+
+A \CXX\ file consists of ``statements'', analogous to ordinary
+sentences. Common types include \emph{declarations} (which
+``register'' a function, variable, or type name with the compiler),
+\emph{definitions} (which assign meaning to declared names), and
+\emph{function calls} (which cause a named function to execute). Most
+statements in an \ePiX\ input file are function calls (``commands'').
+Plain declarations are relatively rare in user files, since a
+definition serves to declare any new names that it contains.
+
+Every statement ends with a semicolon, and conventionally a file
+contains at most one statement per line. The compiler ignores
+nearly all whitespace (spaces, tabs, and newlines), which should be
+used freely to make files easy to read. Other punctuation
+(periods, commas, (semi)colons, parentheses, braces, and quotes)
+dictates file parsing, and must adhere stringently to grammar.
+
+An \ePiX\ file always begins with the lines
+\findex{include}
+\begin{verbatim}
+#include "epix.h" // N.B. pre-processor directive, no semicolon
+using namespace ePiX;
+\end{verbatim}
+The first line is analogous to a \LaTeX\ \code{usepackage} command: It
+loads the contents of the ``header'' file \filename{epix.h}, importing
+the names of commands provided by~\ePiX. To avoid name conflicts,
+\ePiX's commands are enclosed in a ``namespace''. For example, the
+\code{label} command is actually known to the compiler as
+\code{ePiX::label}. The second line above tells the compiler to apply
+the prefix tacitly.
+
+
+\subsection{Variables and Functions}
+%% \index{Variable}\index{Variable!names}
+%% \index{Function}\index{Function!names}
+
+Definitions of variables and functions play the same role in a figure
+that macro definitions play in a \LaTeX\ document: gathering and
+organizing information on which the figure depends. A variable is
+defined by supplying its type, name, and initial value. By far the
+most common data types in~\ePiX\ are \code{double} (double-precision
+floating point number), \code{P}, and \code{int}. The name of a
+variable may consist (only) of letters (including the underscore
+character) and digits, and must begin with a letter:
+\begin{verbatim}
+my_var, var2, MY_var, aLongVariableName; // valid
+my-var, 2var, \v@riable, $x, ${MY_VARIABLE}; // not valid
+\end{verbatim}
+Variable names are case-sensitive, and numerous (non-universal)
+conventions govern the significance of capitalization. Generally, make
+names descriptive but not unwieldy, and avoid language keywords (such
+as \code{const}, \code{true}, \code{double}, \code{class}, or
+\code{public}) and names that begin with an underscore.
+
+A function accepts ``arguments'' and ``returns a value''. To define a
+function in~\CXX, you must specify the return type, the name of the
+function, the types of the arguments, and the algorithm by which the
+value is computed from the inputs. The code block
+\begin{verbatim}
+double f(double x)
+{
+ return sqrt(1-x*x);
+}
+\end{verbatim}
+specifies the \code{double}-valued function~\teximath{f} of one \code{double}
+variable defined by the formula \teximath{f(x)=\sqrt{1-x^2}}.
+
+
+\subsection{Comments}
+
+\CXX\ has two types of comments. \code{C}-style comments, which may
+span several lines, are delimited by the strings \code{/*}~and
+\code{*/}. One-line comments, analogous to the \LaTeX~\code{\%}, are
+begun with \code{//}. A one-line comment may appear within a multi-line
+comment, but a \code{C}-style comment may not; the compiler will
+mistake the first~\code{*/} it encounters as the end of the current
+multi-line comment.
+
+
+\subsection{Program Execution}
+
+All the ``action'' in a \CXX\ program occurs inside the special
+function~\code{main}. Running a compiled \CXX~program is viewed by the
+operating system as calling the program's \code{main} function. The
+return value (an \code{int}) is the program's exit status. The
+contents of the output file start with \code{begin()} and terminate
+with \code{end()}. Intervening statements constitute the \emph{body}
+of the file.
+
+In \CXX, a function may not be defined inside another function. Thus,
+variables may be defined inside \code{main}, but functions cannot be.
+
+
+\subsection{Strings and Raw Output}
+
+In \CXX, a \code{string} is a sequence of characters. Most
+\code{string}s in \ePiX\ input files are \emph{literals},
+double-quoted \code{string}s whose value is read from the input. In a
+string literal, backslash is an escape character; a single backslash
+is produced by a double backslash in the input file. Certain letters
+have special meanings when backslash-escaped, including ``\verb+\n+''
+(newline) and ``\verb+\t+'' (\Key{TAB}). Unlike~\LaTeX, \CXX~does not
+require a space to separate an escape sequence from following text;
+the string ``\verb+\\textwidth+'' literally represents a \LaTeX\
+command, while ``\verb+\textwidth+'' is read ``\code{TABextwidth}'' by
+the compiler.
+
+Though not commonly needed, raw text can be printed to the output
+file. The functions \code{write}, \code{pre\_write}, and
+\code{post\_write} accept \code{string} arguments. \code{write} prints
+its argument where the call appears in the input file. The other
+functions print their arguments before or after the completed picture,
+respectively. These commands must be in the file body. As an
+application, a complete \LaTeX\ \code{figure} environment (with
+caption and label) can be produced by an \ePiX\ file,
+Figure~\ref{fig:captioned}.
+
+\index{pre\_write}
+\index{post\_write}
+\index{write}
+\findex{pre\_write}
+\findex{post\_write}
+\findex{write}
+\begin{figure}
+\begin{footnotesize}
+\begin{verbatim}
+#include "epix.h"
+using namespace ePiX;
+
+int main()
+{
+ picture(P(-1,-1), P(1,1), "10cm x 3in);
+ begin();
+ pre_write("\\begin{figure}[hbt]"); // comes before the picture
+
+ post_write("\\caption{A \\LaTeX\\ figure.}"); // and after
+ post_write("\\end{figure}");
+
+ < ... other ePiX commands ... >
+ write("%% A comment near the end, but inside the picture.");
+ end();
+} // End of main()
+\end{verbatim}
+\end{footnotesize}
+\caption{Generating a self-contained figure in \ePiX.}
+\label{fig:captioned}
+\end{figure}
+
+
+\subsection{Conditionals and Loops}
+
+An algorithm's behavior usually depends on internal state. A
+\emph{conditional statement} causes blocks of code to be executed
+according to criteria. A \emph{loop} repeatedly executes a code
+block, usually changing the values of variables in a predictable way,
+so that the loop exits after finitely many traversals.
+
+\texicomment
+Figure~\ref{fig:gcd} illustrates conditionals and loops with
+Euclid's algorithm for the greatest common divisor. Three pieces of
+notation require explanation: \code{j\%i} means~``\teximath{j\pmod i}'',
+\code{||} is logical~``or'', and \code{==} is ``test for equality''.
+(A single~``\code{=}'' is the assignment operator.)
+
+\index{Function!Euclidean algorithm}
+\begin{figure}[hbt]
+\begin{footnotesize}
+\begin{verbatim}
+int gcd (int i, int j)
+{
+ int temp(i); // initialization syntax
+ if (i==0 || j==0)
+ return i+j; // define gcd(k,0) = k
+
+ else {
+ if (j < i) // swap them
+ {
+ temp = j;
+ j = i;
+ i = temp;
+ }
+ // the work is done here...
+ while (0 != (temp = j%i)) // assign temp, test for zero
+ {
+ j = i;
+ i = temp;
+ }
+ return i;
+ }
+}
+\end{verbatim}
+\end{footnotesize}
+\caption{Euclid's division algorithm in~\CXX.}
+\label{fig:gcd}
+\end{figure}
+\texicommentend
+
+%% \noindent For details on conditionals, or for more advanced techniques
+%% of \CXX\ programming, please consult a textbook or online tutorial.
+\index{Cplusplus@\CXX|)}
+
+%% Force previous two figures onto the same page
+%%\clearpage
+
+\section{Animation}
+\label{section:animation}
+
+\index{Animation|(}
+\ePiX\ is well-suited to the creation of mathematically accurate
+animations: If a figure depends suitably upon a ``time'' parameter,
+then a loop can be used to draw the entire figure for multiple time
+values, yielding successive ``snapshots'' of the figure as time
+progresses. The shell script~\code{flix} automates the process of
+compiling a suitable input file into a collection of \filename{png}s
+and assembling these frames into a \filename{mng}~or \filename{gif}
+animation. ImageMagick is the image-handling engine.
+
+A \code{flix} file is an \code{epix} file with two restrictions:
+\begin{itemize}
+ \item The \code{double} variable \code{tix()} is used as
+ ``clock''.
+
+ \item \code{main} accepts two command line arguments and sets
+ \code{tix()} accordingly.
+\end{itemize}
+\index{Emacs@\code{emacs}}
+Jay Belanger's \code{emacs} mode recognizes the file
+extension~\filename{.flx} and inserts template code if an empty buffer
+is opened. Creation of \code{flix} files is as easy as creation of
+\code{epix} files. The \filename{samples} directory contains a
+handful of \code{flix} files that may be consulted for ideas.
+
+By default, \code{flix} creates movies with 24~frames, in which
+\code{tix()} runs from~0 to~1, and animates at
+\teximath{0.08}~sec/frame. These and other parameters can be changed
+with command-line options.
+
+A ``typical'' \code{.flx} file may take 30~seconds to a few minutes to
+compile, depending on the number of frames and the complexity of each
+frame. To facilitate debugging, \code{elaps} can be run on a
+\code{flix} file. \code{elaps} runs in a fraction of the time, and if
+\code{elaps} can't produce a viewable image, \code{flix} will surely
+fail. While running, \code{flix} prints a progress bar counting the
+number of \filename{eps} files that have been created. There will be
+a delay of a few seconds (or more) after the last frame is produced,
+during which ImageMagick's \code{convert} utility assembles the movie.
+\index{Animation|)}
+
+
+\section{Layout Tricks}
+\label{section:layout}
+\index{Layout}
+
+\subsection{Stereograms}
+\index{Stereograms}
+Stereograms are created by drawing a single scene twice from slightly
+different points of view. To create a stereogram with \ePiX, write a
+``scene'' function containing the necessary drawing commands, then set
+the camera appropriately and call the scene function twice, once for
+each frame.
+
+\subsubsection*{Crossed-Eyes Stereograms}
+
+The sample files \filename{lorenz.xp}~and \filename{twisted\_cubic.xp}
+use page layout to draw crossed-eyes stereograms. For each frame,
+create and activate a \code{screen}, set the camera, and call the
+scene function. The frames are inset side by side in the final
+picture. For a crossed-eyes stereogram, the frame from the
+``rightmost'' camera position is placed on the left.
+
+\subsubsection*{Bi-Color Stereograms}
+
+The sample files \filename{cube.flx}~and \filename{mirrorball.flx}
+contain animated red-cyan stereograms, suitable for viewing with 3-D
+glasses. The technique works best with black-and-white line drawings,
+but the basic approach is the same as for crossed-eyes stereograms:
+Create a scene function and call it twice, setting the camera
+appropriately. Layout is unnecessary since the frames are superposed.
+Pen colors should be close to red and cyan, but ``optimal'' choices
+depend on one's eyes and 3-D glasses.
+
+\subsubsection*{Stereographic Movies}
+
+Either form of stereogram can be animated in a \code{.flx} file, but
+keeping one's eyes properly crossed requires practice while most
+people can instantly see depth with 3-D glasses. As always when using
+\code{flix}, debug the scene with \code{elaps} before compiling a
+movie. If a stereoscopic effect is difficult to see in a still image,
+it will be even harder to perceive in a movie.
+
+
+\subsection{Inset Images}
+
+\ePiX\ can place external images into a figure, similarly to
+Rolf Niepraschk's \code{overpic} package. You provide the Cartesian
+center point, the file name, and optionally the true height and/or
+width of the image:
+\findex{label}
+\begin{verbatim}
+ label(P(a,b), "\\includegraphics[width=w,height=h]{file}");
+\end{verbatim}
+This effect requires the \filename{graphicx} package. When compiling a
+stand-alone graphic containing an external image, you must specify the
+\filename{graphicx} package on the command line: \code{elaps -p
+graphicx <file>}
+
+\texicomment
+\begin{figure}[hbt]
+ \begin{center}
+ \input{ePiX.eepic}
+ \end{center}
+ \caption{Visual guide to \ePiX's shell scripts}
+ \label{fig:programs}
+\end{figure}
+\texicommentend
+
+
+\texinfochapter{3}{Reference Manual}
+\label{chapter:ref-man}
+
+This chapter details \ePiX's capabilities, discussing attributes and
+data types, and listing available commands in the form
+\begin{verbatim}
+ label(P posn, [P offset], string text, [align]);
+ circle(P ctr, double rad=1, normal=P(0,0,1));
+\end{verbatim}
+As in Chapter~\ref{chapter:started}, function arguments are given by
+type (\code{P}, \code{double}, \code{string}, etc.)\ and name, or by
+name alone if the type is clear. Optional arguments are enclosed in
+square brackets. A few argument types, such as \code{[align]} above,
+admit only a small number of values; these cases are explained when
+the corresponding command is first introduced.
+
+A name followed by an equals sign and a value indicates a default
+argument; if omitted in an input file, the compiler substitutes the
+default value. Only trailing arguments may be specified this way. For
+example, if the \code{rad} argument of the \code{circle} command is
+omitted, the \code{normal} argument \emph{must} be omitted as well.
+
+In an input file, only an argument's value is given, not the type:
+\begin{verbatim}
+ label(P(0,0), P(0,-4), "Hello world", b);
+ circle(P(0,-0.25), sqrt(2)); // use default normal
+\end{verbatim}
+
+Generally, \code{len} signifies either a number (representing a length
+in \code{pt}) or a double-quoted string containing a number and a
+two-letter \LaTeX\ length unit, such as \code{"1.5pt"} or
+\code{"6cm"}. \code{color} represents a \code{Color} object
+constructed from a named primary (\code{Blue()}, \code{Magenta(0.7)},
+etc.), a color specification (\code{RGB(r,g,b)}, \code{CMY(c,m,y)},
+etc.), or an operator applied to an existing \code{Color}.
+
+
+\section{File Structure}
+
+An \ePiX\ input file constitutes a short \CXX\ program. When this
+program is compiled and run by one of the shell scripts, it creates a
+figure file suitable for inclusion in \LaTeX.
+
+\index{Preamble}
+Like a \LaTeX\ document, an \ePiX\ file contains a \emph{preamble},
+which sets up a drawing environment, and a \emph{body}, which contains
+actual figure-generating commands. The minimal file has the form
+\findex{picture}
+\findex{begin}
+\findex{end}
+\begin{verbatim}
+#include "epix.h" // N.B. no semicolon
+using namespace ePiX;
+
+int main() {
+ picture(P(a1,b1), P(a2,b2), "n1 [unit1] x n2 unit2");
+ begin(); // end of preamble, start of body
+ end(); // end of body
+}
+\end{verbatim}
+\ePiX\ commands are of four general types: drawing, attribute setting,
+definitions (of data and functions), and operations on existing
+objects. Except as noted below, drawing and attribute commands must
+appear in the body, between \code{begin()}~and \code{end()}. Function
+definitions must come in the preamble, before \code{main()}. Data
+definitions may appear in the preamble or body.
+
+
+\subsubsection*{Output Format}
+\index{Output format}
+
+The \code{end()} command writes the output file to \code{stdout},
+using \code{eepic} macros by default. The shell scripts redirect
+\code{stdout} to an appropriate disk file.
+
+The attribute-setting command \code{pst\_format()} causes the output
+file to be written using \code{PSTricks} macros when \code{end} is
+called. Similarly, \code{tikz\_format()} causes the file to be written
+using \code{tikz} macros, and \code{eepic\_format()} causes the file
+to be written using \code{eepic} macros. These commands may appear
+anywhere in the figure body. There is no reason for a file to contain
+more than one such command.
+
+The output format may be selected on the command line, overriding any
+explicit request in the input file. Supplying \code{epix},
+\code{elaps}, or \code{flix} with one of the options \code{--pst},
+\code{--tikz}, or \code{--eepic} is tantamount to issuing a
+\code{pst\_format()} (etc.)\ command just before the end of the
+file. These options are listed in decreasing precedence. If more than
+one is given, the ``strongest'' applies, regardless of the command
+line order.
+
+A figure may be written directly to a specified disk file, in a format
+unaffected by the command line flags above. The command
+\begin{verbatim}
+ print_eepic("file.tex");
+\end{verbatim}
+writes the figure to the named file using \code{eepic}
+macros. Analogous commands exist for the formats \code{pst}~and
+\code{tikz}. These commands perform an immediate action. Consequently,
+the command's location in the input file is significant, and multiple
+commands may appear in a single file, so long as distinct file name
+arguments are provided. Applications include writing the same figure
+in multiple formats, or creating successive ``snapshots'' of a lengthy
+computation.
+
+
+\section{Picture Size and Aspect Ratio}
+
+\index{Picture!size}
+\index{Picture!offset}
+The \code{picture} command specifies a figure's logical and true
+sizes. In the ``minimal file'' snippet above, the \emph{canvas} is the
+Cartesian rectangle \teximath{[a_1,a_2]\times[b_1,b_2]} whose corners
+are given. Either pair of opposite corners is acceptable, but
+confusion is less likely when the SW~and NE corners are given, in this
+order.
+
+The true (printed) width and height are read from \code{picture}'s
+third argument, a ``size \code{string}'' such as \verb+"4cm x 1in"+,
+containing a number and optional \LaTeX\ length unit, an~\code{x},
+another number, and a mandatory length unit. Spaces may be used for
+legibility. The mandatory length unit becomes the \LaTeX\
+\code{unitlength}. The argument \verb+"4cm x 1in"+ creates a picture
+4~cm wide and 1~in high, but internally converts 4~cm to inches.
+Recognized length units are \code{pt} (points, the default), \code{cm}
+(centimeters), \code{in} (inches), \code{mm} (millimeters), \code{pc}
+(picas), and \code{bp} (big points).
+(\code{1in = 2.54cm = 72bp = 72.27pt}, \code{1pc = 12pt}.)
+
+The logical and true sizes may be defined separately with the commands
+\findex{bounding\_box}
+\findex{picture}
+\findex{unitlength}
+\begin{verbatim}
+ bounding_box(P(a1,b1), P(a2,b2));
+ picture(n1, n2);
+ unitlength(len); // len a length string, not a double
+\end{verbatim}
+One way or another, the logical and true dimensions \emph{must} have
+positive values when the \code{begin()} command is issued.
+
+\LaTeX\ treats the contents of a picture environment as a single box,
+aligned by default on its lower left corner. An \code{offset} command
+accepts two \code{double} arguments or a size \code{string} and shifts
+the page location accordingly. The command
+\code{offset("0.25 x -0.5cm")} shifts the picture right
+\teximath{0.25}~cm and down \teximath{0.5}~cm. If the
+\code{unitlength} is 1~cm, the command \code{offset(0.25, -0.5)} has
+the same effect.
+
+A non-zero \code{offset} causes a picture's contents to appear in a
+location where \LaTeX\ does not expect them. This can be useful in a
+\LaTeX\ document, but should be avoided when compiling a stand-alone
+image, since \code{dvips} may crop according to rules of its own.
+
+
+\index{Picture!aspect ratio}
+\index{Picture!bounding box}
+The canvas's corners are \code{(xmin(),ymin())} and
+\code{(xmax(),ymax())}, while its width and height are
+\code{xsize()}~and \code{ysize()}. The canvas is a virtual, advisory
+data structure; its dimensions are not directly related to the
+figure's printed size, and picture elements may lie outside the
+canvas. Affine scaling maps the canvas to the page when the output
+file is written.
+\begin{center}
+\input{scaling.eepic}
+\end{center}
+\label{page:scaling}
+The figure's aspect ratio is controlled by sizing the canvas. The
+aspect ratio is ``true'' if the canvas and page rectangles are
+geometrically similar, e.g., if both boxes are 1.5~times as wide as
+they are tall.
+
+
+\section{Color}
+\label{section:color}
+
+\index{Color|(}
+\ePiX\ provides a \code{Color} data type. Four models are implemented:
+\code{RGB}, \code{CMY}, \code{CMYK}, and \code{Gray}. A \code{Color}
+holds primary color ``channels'', each carrying an intensity between
+0~(no color) and~1 (full saturation). ``No color'' means black in
+\code{RGB} and \code{Gray}, white in \code{CMY(K)}. \code{RGB},
+\code{CMY}, and~\code{CMYK} colors are written to the output file as
+commands in the corresponding model. \code{Gray} shades are written
+in~\code{RGB}.
+
+Operations on red-green-blue colors are described below. Functionally,
+colors are converted to~\code{RGB}, operated upon, then converted back
+to the original model. Conversions are as described in Uwe Kern's
+\filename{xcolor} manual~\cite{xcolor}.
+
+
+\subsection{Constructors}
+
+Each color model has a ``constructor'' creating a color of specified
+densities. The \code{RGB}~and \code{CMY} models have named ``primary''
+constructors; the density argument is optional and defaults to~1.
+\findex{RGB}
+\findex{Red}
+\findex{Green}
+\findex{Blue}
+\findex{White}
+\findex{Black}
+\begin{verbatim}
+ // red-green-blue colors
+ RGB(double r=0, double g=0, double b=0);
+ Red(d=1); Green(d=1); Blue(d=1);
+ White(d=1); Black(d=1);
+\end{verbatim}
+\findex{CMY}
+\findex{Cyan}
+\findex{Magenta}
+\findex{Yellow}
+\findex{CMY\_White}
+\findex{CMY\_Black}
+\findex{CMYK}
+\findex{Gray}
+\begin{verbatim}
+ // cyan-magenta-yellow colors
+ CMY(double c=0, double m=0, double y=0);
+ Cyan(d=1); Magenta(d=1); Yellow(d=1);
+ CMY_White(d=1); CMY_Black(d=1);
+
+ // gray
+ Gray(double d=0); // equivalent to RGB(d, d, d)
+\end{verbatim}
+Each \code{CMY} constructor has a corresponding \code{CMYK} function,
+e.g.\ \code{CyanK()}~or \code{CMYK\_White()}.
+
+Though color densities lie between 0~and 1, \ePiX's primary color
+constructors take arguments mod~4, viewed as elements
+of~\teximath{[-2,2]}. Consider \code{Red(d)}, ``red with
+density~\teximath{d}''. For integer values of~\teximath{d}, the
+constructor has the following meanings: \code{Red(0)}~is black,
+\code{Red(1)}~is red, \code{Red(2)}=\code{Red(-2)}~is white, and
+\code{Red(-1)}~is anti-red, or cyan. For non-integer~\teximath{d}, the
+constructor interpolates between the bracketing integer values,
+Figure~\ref{fig:densities}. Other primary constructors work
+analogously.
+
+\begin{figure}[hbt]
+ \begin{center}
+ \input{color_density.eepic}
+ \end{center}
+ \caption{The red primary constructor.}
+\label{fig:densities}
+\end{figure}
+
+Let \teximath{\delta:[-2,2]\to[0,1]} be the piecewise-linear function
+that converts real numbers to primary color densities,
+\teximath{\clip:\mathbf{R}\to[0,1]} the clipping function. The
+non-primary constructor \code{RGB(r, g, b)} computes the density of
+the red channel as
+\teximath{\clip\bigl(\delta(r)+\delta(-g)+\delta(-b)\bigr)}; the green
+and blue channel densities are computed similarly. Every color can be
+created with arguments between 0~and 1, but the constructor accepts
+arbitrary real arguments and returns colors varying ``continuously and
+periodically''.
+
+\index{Color!transparency}
+Colors possess an ``alpha-channel'' for transparency. Except as
+supported by the output format, this feature is a stub.
+
+
+\subsection{Color Operations}
+
+Colors can be scaled, inverted, blended, superposed, and filtered. In
+the code below, \code{tint}~is a \code{Color}. The effect of each
+operation is described in the \code{rgb} model; the visual result is
+the same in all models.
+\findex{Color.invert}
+\findex{Color.blend}
+\findex{Color.superpose}
+\findex{Color.alpha}
+\findex{Color.filter}
+\begin{verbatim}
+ tint *= double c; // multiply channels by c, rebuild
+ tint.invert(); // (r, g, b) -> (1-r, 1-g, 1-b)
+ tint.blend(Color col, double t); // (1-t)*tint + t*col
+ tint.superpose(col); // add channels, then clip to [0,1]
+ tint.alpha(double d); // set alpha channel to clip(d)
+
+ tint.filter(col); // return min density in each channel
+\end{verbatim}
+Except for \code{filter}, these operators modify their object.
+\code{filter} simulates the effect of viewing \code{col}
+through a transparent sheet of \code{tint}, and returns a new
+\code{Color} object having the same model as \code{tint} without
+modifying \code{tint} itself.
+
+
+\section{Scene Attributes}
+
+Objects in a scene sit in 3-dimensional space. A \emph{camera}
+maps objects to the \emph{active screen}. The active \code{screen}
+may, in turn crop its contents. Each drawing command creates an
+object, ``photographs'' it, and adds the image to the active
+\code{screen}. This section describes the \code{Camera} and
+\code{screen} classes and a few associated concepts.
+
+
+\subsection{Angular Mode}
+\index{Angle units}
+
+By default, angles are measured in \code{radian}s. Two other angular
+modes are available: \code{degrees}~and \code{revolutions}. The
+angular mode is set with a named command, \code{radians()},
+\code{degrees()}, or \code{revolutions()}. The current angular mode
+affects all trigonometric functions and operations.
+
+
+\subsection{The Camera}
+\index{Camera|(emph}
+\index{Screen|(}
+
+Three-dimensional scenes are drawn on flat paper by applying a
+mathematical transformation. By default, \ePiX\ uses \emph{point
+projection}, the technique used by art students when they trace on a
+window with grease pencil, Figure~\ref{fig:camera}.
+
+\begin{figure}[hbt]
+ \begin{center}
+ \input{camera.eepic}
+ \end{center}
+ \vspace*{-0.25in}
+ \caption{Point projection.}
+ \label{fig:camera}
+\end{figure}
+
+\index{Camera!viewpoint}
+\index{Viewpoint}
+\ePiX\ depicts a Cartesian world by projecting mathematically to a
+screen plane, then affinely scaling to a printed page. The camera,
+which maps the world to the screen, consists of a \emph{body} (data
+that determines the position and orientation of the camera), a
+\emph{lens} (the actual mapping to the screen plane), and a
+\emph{filter} (a color through which the scene is viewed).
+
+
+\subsubsection*{Body}
+
+The camera's spatial orientation is described by a triple of mutually
+perpendicular unit vectors. In memory of happy days at the beach,
+these vectors are called \emph{sea}, \emph{sky}, and~\emph{eye}. The
+screen plane is parallel to the sea-sky plane; the sea vector points
+horizontally to the right, sky points vertically upward. The eye is
+their cross product, which points directly at the viewer.
+
+The sea-sky-eye basis is located at the \emph{viewpoint}, the camera's
+spatial location. The \emph{target}, the origin of the screen plane,
+lies on the line through the viewpoint in the direction opposite the
+eye vector. The distance from the viewpoint to the target is the
+\emph{range}. The \emph{camera sphere} is centered at the viewpoint
+and passes through the target. The orientation, viewpoint, target,
+and range completely (and redundantly) determine the camera's
+geometric situation in the world.
+
+
+\subsubsection*{The Lens}
+\index{Camera!lens}
+
+A \emph{lens} maps the world to the screen. \ePiX\ comes with four
+lenses: \emph{shadow} (the default), \emph{orthogonal},
+\emph{fisheye}, and \emph{bubble}. Each lens simulates the appearance
+of world objects as seen by an observer at the viewpoint. The shadow
+lens is point projection from the viewpoint to the screen plane. The
+orthogonal lens projects from infinite distance. Each of the other
+lenses performs radial projection to the camera sphere, then maps the
+sphere to the screen plane; the fisheye lens does orthogonal
+projection (so the entire image lies inside the disk centered at the
+target whose radius is the range) while the bubble lens does
+stereographic projection from the target's antipode.
+\index{Screen|)}
+
+
+\index{Camera!manipulation|(}
+An input file normally uses a single camera, so a global object named
+\code{camera} is defined automatically. At the start of a figure, the
+\code{camera} looks down on the \teximath{(x_1,x_2)}-plane from a
+distant point on the \teximath{x_3}-axis. The resulting view,
+essentially projection along the axis, is suitable for 2-dimensional
+figures.
+
+The \code{camera} is manipulated similarly to a real camera:
+\findex{Camera.at}
+\findex{Camera.look\_at}
+\findex{Camera.range}
+\findex{Camera.focus}
+\findex{Camera.tilt}
+\findex{Camera.pan}
+\findex{Camera.roll}
+\findex{Camera.clip\_range}
+\begin{verbatim}
+ camera.at(P posn); // set viewpoint to posn
+ camera.look_at(P targ); // set target to targ
+ camera.range(double dist); // fix target, move viewpoint
+ camera.focus(double dist); // fix viewpoint, move target
+ camera.tilt(double angle); // rotate about the sea axis
+ camera.pan(double angle); // rotate about the sky axis
+ camera.roll(double angle); // rotate about the eye axis
+ camera.clip_range(dist); // cull scenery closer than dist
+\end{verbatim}
+Explicitly setting the viewpoint or target makes the sky vector
+parallel to the projection of the \teximath{x_3}~axis when possible;
+otherwise the \teximath{x_2}-axis is used. Setting the range or focus
+moves the \code{camera} parallel along the eye line. Each command
+re-sizes the image; note that increasing the focus \emph{enlarges} the
+image. The three rotation operations fix the viewpoint, but only roll
+fixes the target.
+
+
+\subsubsection*{Filtering and Color Separation}
+\index{Color!separation}
+\index{Camera!color separation}
+
+The \code{camera} has a \emph{filter} through which all scene
+\code{Color}s pass. For uniformity, the filter should only be set at
+the start of the file body, before any visible elements have been
+placed in the scene. The filter has two primary uses---model
+conversion and color separation---but can also be used for special
+effects.
+
+There is a \code{Neutral} color, for which filtering has no effect at
+all. The \code{camera}'s default filter is \code{Neutral}. In
+addition, each color model has a \emph{neutral} representative,
+\code{RGB\_Neutral}, etc. Passing \code{Color}s through a neutral
+filter preserves their appearance but converts them to the neutral
+\code{Color}'s model.
+
+Filtering can be used to ``split'' a \code{Color} into primary
+constituents. For \code{RGB} channels, the primaries themselves are
+suitable filters. For \code{CMYK} channels, there are special
+\emph{process} filters, named \verb+C_Process+, etc.
+\begin{verbatim}
+ camera.filter(CMY_Neutral()); // convert all colors to CMY
+ camera.filter(Gray_Neutral()); // black and white photography
+ camera.filter(Green()); // the green channel
+ camera.filter(M_Process()); // the magenta channel
+ camera.filter(Red(1.4)); // la vie en rose?
+\end{verbatim}
+\index{Camera!manipulation of|)}
+\index{Camera|)}
+
+
+\subsection{Clipping}
+
+\index{Clipping|(}
+
+Two operations handle elements lying far from the target.
+\emph{Cropping} culls elements based on their screen location, and is
+described later. \emph{Clipping} removes objects whose spatial
+location lies outside the ``clip region''.
+
+Initially, the clip region is a very large box centered at the
+origin. Commands are provided to resize this box, keeping the faces
+parallel to coordinate planes.
+\findex{clip\_box}
+\findex{clip\_to}
+\begin{verbatim}
+ clip_box(P pt1, P pt2); // opposite corners
+ clip_box(P pt); // opposite corners pt and -pt
+ clip_to (P pt); // pt and P(0,0,0)
+ clip_box(); // very large box
+\end{verbatim}
+Additional ``clippers'' may be added manually. Individual clipping
+planes are specified by a point and inward-pointing normal vector.
+Parallel planes cutting a ``slice'' or ``slab'' are described by a
+location, direction, and a distance. The location lies halfway between
+the clipping planes, and the planes' normals point toward the location.
+\findex{clip\_face}
+\findex{clip\_slice}
+\findex{clip\_restore}
+\begin{verbatim}
+ clip_face(P loc, P perp); // perp points inward
+ clip_slice(loc, perp); // very close parallel planes
+ clip_slice(loc, perp, dist); // planes separated by dist
+ clip_restore(); // remove manually-added clip planes
+\end{verbatim}
+Like \code{clip\_restore}, the \code{clip\_box} and \code{clip\_to}
+commands remove all user-specified half spaces.
+\index{Clipping|)}
+
+
+\subsection{Screens and Page Layout}
+\index{Screen|(}
+\index{Screen!active}
+\index{Layout}
+
+By default, drawing occurs in the Cartesian coordinate system of the
+\code{canvas}. However, insets and subfigures are most naturally
+composed in ``local'' coordinates, then placed into their final
+location as a unit, a process called \emph{layout}. \ePiX\ implements
+layout with the \code{screen} class.
+
+
+\subsubsection*{Screens}
+\index{Bounding box}
+
+A \code{screen} is a Cartesian plane containing a distinguished
+coordinate rectangle, its \emph{bounding box}. The \code{canvas} of a
+figure is a \code{screen}, as is the internal representation of the
+printed page. At any point of a file body, some \code{screen} is
+\emph{active}, or ``open for drawing''. A new \code{screen} is created
+from a pair of opposite corners, but is not used until explicitly
+activated.
+\findex{activate}
+\findex{deactivate}
+\begin{verbatim}
+ screen subfig(P(a1,b1), P(a2,b2)); // [a1, a2] x [b1, b2]
+ activate(subfig); // open subfig for drawing
+ // commands to draw in subfig
+ deactivate(subfig); // re-activate the previous screen
+\end{verbatim}
+
+The \code{canvas} is automatically drawn at the \code{end} of the
+input file. The contents of other \code{screen}s must be incorporated
+into the \code{canvas} explicitly with an \code{import}~or
+\code{inset} command. \code{import} affinely scales the bounding box
+of the ``child'' \code{screen} to the \code{canvas}. \code{inset}
+specifies corners in the ``parent'' where the child is
+placed.
+\findex{import}
+\findex{inset}
+\begin{verbatim}
+ import(); // active screen to canvas
+ import(subfig); // subfig to canvas
+ inset(P sw, P ne); // active screen to specified rectangle
+ inset(subfig, sw, ne); // subfig to specified rectangle
+ inset(subfig); // inset to subfig's corners
+\end{verbatim}
+
+
+\subsubsection*{Extracting}
+
+The portion of a \code{screen} enclosed by a specified rectangle can
+be \emph{extracted}. Each of the commands
+\findex{extract}
+\findex{canvas}
+\begin{verbatim}
+ subfig.extract(P sw, P ne);
+ canvas().extract(P sw, P ne);
+\end{verbatim}
+returns the \code{screen} having stated corners and containing part of
+\code{subfig} or the \code{canvas}, respectively. Elliptical and
+diamond-shaped portions of a \code{screen} may be extracted. The
+contents occupy the ellipse or diamond inscribed in the given
+rectangle.
+\findex{extract\_diamond}
+\findex{extract\_ellipse}
+\begin{verbatim}
+ subfig.extract_ellipse(sw, ne);
+ canvas().extract_diamond(sw, ne);
+\end{verbatim}
+The \code{screen} returned by \code{extract} (or its variants) may be
+used just like a manually-constructed \code{screen}, for example to
+construct a magnified inset.
+
+
+\subsubsection*{True-Size Drawing}
+\label{truesize}
+
+On occasion, it is necessary to draw at known page size, independently
+of the unit length. For 2-dimensional drawing in the
+\teximath{(x_1,x_2)}-plane with the \code{camera} in its default
+location, the coordinates (horizontal, vertical, or both) of a
+\code{screen} may be interpreted as true~pt offsets relative to a
+specified point rather than as Cartesian coordinates.
+\findex{inlay}
+\findex{inlay\_horizontal}
+\findex{inlay\_vertical}
+\begin{verbatim}
+ inlay(subfig, P loc);
+ inlay_horizontal(subfig, loc);
+ inlay_vertical(subfig, loc);
+\end{verbatim}
+Each command maps the origin of \code{subfig} to the specified
+location in the active \code{screen}. The first performs affine
+scaling so that one Cartesian unit in \code{subfig} maps to one
+true~pt on the page. The second and third commands perform this
+scaling only in the named direction.
+
+\findex{pt\_to\_screen}
+The \code{inlay} functions are suitable only for 2-dimensional
+effects. For 3-dimensional true-size drawing, the function
+\code{pt\_to\_screen} converts a true length of 1~pt into Cartesian
+coordinates in the active \code{screen}. For example, the command
+\code{line(P(0,0), P(pt\_to\_screen(12),0))} draws a line segment
+12~pt long with its left endpoint at the Cartesian origin. True size
+drawing is unusual in an input file, but has definite uses in library
+code; \ePiX's right angle marker is a typical application.
+
+Either type of true-size drawing works as described when drawing in
+the \code{canvas}, and \emph{only} when drawing in a \code{screen}
+imported to the \code{canvas} at ``true Cartesian'' size (one
+\code{screen} unit maps to one Cartesian unit in the \code{canvas}).
+In other situations, the true size coordinate(s) will be scaled by
+additional affine transformation(s).
+
+
+\subsubsection*{Cropping and Decorations}
+
+\index{Cropping}
+A \code{screen} has a \emph{crop mask}: rectangular (default),
+elliptical, or diamond-shaped. If cropping is switched on in the
+active \code{screen}, added elements are cropped to the crop mask.
+For example, cropping by the default crop mask in the \code{canvas}
+ensures the figure lies inside the printed region allocated by
+\LaTeX.
+
+The \code{crop} commands below affect the active \code{screen}
+only. Cropping is not a ``global'' attribute, but must be set or unset
+explicitly for each \code{screen}. By default, cropping is switched
+off.
+\findex{crop}
+\findex{crop\_ellipse}
+\findex{crop\_diamond}
+\findex{set\_crop}
+\begin{verbatim}
+ set_crop(); // activate cropping
+ set_crop(false); // deactivate cropping
+ crop_diamond(); // <>-shaped mask, set crop state
+ crop_ellipse(); // etc...
+ crop(); // crop active screen's contents
+\end{verbatim}
+Normally the crop mask is inscribed in the \code{screen}'s bounding
+box. The commands \code{crop\_diamond} and \code{crop\_ellipse} also
+accept a pair of \code{P}~arguments, which are treated as corners of
+the crop box.
+
+The active \code{screen} may be decorated with a \code{border}
+(outline of specified color and line width) and \code{backing} (solid
+fill color). The crop mask determines the shape of the \code{border}
+and \code{backing}.
+\findex{border}
+\findex{backing}
+\begin{verbatim}
+ border(color, len);
+ backing(color);
+\end{verbatim}
+Identically-named member functions can be applied to an arbitrary
+\code{screen} whether or not it is active:
+\begin{verbatim}
+ scr.crop_rectangle().backing(Blue(1.8));
+ canvas().crop();
+\end{verbatim}
+
+
+\subsubsection*{Affine Maps}
+\index{Affine map}
+
+A \emph{plane affine map} has the form \teximath{T(x) = Ax+b} for some
+invertible \teximath{2\times2} matrix~\teximath{A} and a constant
+vector~\teximath{b}. \ePiX's \code{affine} class allows affine maps to
+be built and applied to \code{screen}s' contents.
+
+An affine map is uniquely determined by the images of three
+non-collinear points. The constructor returns the affine map sending
+the points \teximath{(1,0)}, \teximath{(0,1)}, and~\teximath{(0,0)} to
+\code{pt1}, \code{pt2}, and~\code{pt0}, respectively.
+\findex{affine}
+\begin{verbatim}
+ affine af(P pt1, P pt2, P pt0=P(0,0));
+\end{verbatim}
+To emphasize, the arguments are locations, not displacements, and the
+image of the origin comes last. There is also a \code{void}
+constructor (taking no arguments) which returns the identity map.
+
+To facilitate construction of affine maps, an existing \code{affine}
+may be post-composed with a variety of ``elementary'' affine
+transformations. In the commands below, \code{th} is an angle (in
+current units), \code{sc} is a non-zero \code{double}, and \code{ctr}
+is a point fixed by the composing transformation. In each command,
+\code{ctr} defaults to \teximath{(0,0)}.
+\findex{shift}
+\findex{rotate}
+\findex{reflect}
+\findex{h\_scale}
+\findex{v\_scale}
+\findex{scale}
+\findex{h\_shear}
+\findex{v\_shear}
+\findex{postcomp}
+\begin{verbatim}
+ affine af; // the identity map
+ af.shift(P arg); // translate by arg
+ af.rotate(th, [ctr]); // counterclockwise rotation about ctr
+ af.reflect(th, [ctr]); // reflect across line through ctr
+
+ af.h_scale(sc, [ctr]); // horizontal scaling
+ af.v_scale(sc, [ctr]); // vertical scaling
+ af.scale(sc, [ctr]); // dilatation
+
+ af.h_shear(sc, [ctr]); // shear preserving horizontals
+ af.v_shear(sc, [ctr]); // shear preserving verticals
+
+ af.invert(); // the inverse
+ af.postcomp(affine f); // post-compose with f
+ af(f); // pre-compose, af not modified
+\end{verbatim}
+A non-invertible \code{affine} can be created \emph{only} by shearing
+or scaling with an extremely large or extremely small argument, or by
+supplying three collinear points to the constructor. Calling
+\code{invert} on a non-invertible map merely issues a warning and
+performs no action.
+
+An \code{affine} may be applied to a \code{screen}'s current contents.
+The \code{screen} class has eight member functions (\code{shift}
+through \code{shear}) with syntax identical to the affine map
+functions. In addition, an arbitrary \code{affine} may be applied to a
+\code{screen}:
+\findex{apply}
+\begin{verbatim}
+ scr.shift(arg); // shift scr's contents by arg; etc.
+ scr.apply(f); // apply f to scr's contents
+\end{verbatim}
+To apply a composition of several maps to a \code{screen}, it's best
+to build an \code{affine} map by composition, then \code{apply} the
+map. Composing \code{affine}s is cheap; \code{apply}ing an
+\code{affine} is costly in proportion to the number of elements in the
+\code{screen}.
+
+Applying an \code{affine} to a \code{screen} has no effect on the
+bounding box, \code{border}, or \code{backing}, and may move elements
+outside the bounding box even if cropping is active. To ensure a
+\code{screen}'s contents lie inside the bounding box, \code{crop} the
+\code{screen} \emph{after} \code{apply}ing the \code{affine}(s).
+
+The sample file \filename{inverse.xp} uses \code{affine} maps to
+depict branches of inverse functions in one variable,
+\filename{symmetry.xp} depicts the permutation group~\teximath{S_3}
+by its action on a regular hexagon.
+\index{Screen|)}
+
+
+\section{Drawing Attributes}
+
+\ePiX\ maintains drawing states for filled regions, paths, and text
+objects.
+
+
+\subsection{Filled Regions}
+
+\index{Filling}
+\index{Path|(}
+\index{Path!filled}
+Filling is either on or off. When filling is active, closed paths are
+filled with the current \emph{fill color}.
+\findex{fill}
+\findex{nofill}
+\begin{verbatim}
+ fill(); // turn filling on
+ fill(color); // turn filling on, specify color
+ nofill(); // turn filling off, same as fill(false);
+\end{verbatim}
+
+
+\subsection{Paths}
+
+Paths and borders of filled regions are drawn with two \emph{pen}s,
+each described by color and line width. The \emph{line pen} draws
+all path-like objects. The \emph{base pen} does nothing unless it is
+wider then the line pen, in which case it draws an ``underlayer'' or
+``border'' on the line pen.
+\findex{pen}
+\begin{verbatim}
+ pen(len); // set line pen width
+ pen(color); // set line color, keep width
+ pen(color, len); // set color and width
+\end{verbatim}
+As usual, \code{len} may be either a length string or a \code{double},
+interpreted as a width in~\code{pt}. There are \code{base} functions
+with the same signatures and analogous meanings for the base pen.
+
+The line width can be set with named declarations; the optional
+argument sets the line color:
+\findex{plain}
+\findex{bold}
+\findex{bbold}
+\begin{verbatim}
+ plain([color]); // 0.4pt
+ bold([color]); // 0.8pt
+ bbold([color]); // 1.6pt
+\end{verbatim}
+
+
+\subsubsection*{Path Style}
+
+\index{Path!style}
+By default, path-like objects are drawn with solid lines. Dashed,
+dotted, and free-form path style patterns are also available. (The
+\code{base} underlayer is always solid.) The page length of a pattern
+defaults to 12~pt, but can be set.
+\findex{line\_style}
+\findex{dash\_size}
+\begin{verbatim}
+ line_style(string);
+ dash_size(len=12);
+\end{verbatim}
+The path style is set with a WYSIWYG string of dashes, spaces, and
+periods, representing a pattern of dashes, gaps, and dots. In the
+sample styles below, the repeating units have the same page size,
+12~pt.
+\begin{center}
+ \input{pathstyle.eepic}
+\end{center}
+For brevity and uniformity, named commands are provided.
+\findex{solid}
+\findex{dashed}
+\findex{dotted}
+\begin{verbatim}
+ solid(); "-" dashed(); "- -" dotted(); " . "
+\end{verbatim}
+A sequence of \teximath{n}~dashes, spaces, and dots corresponds to a
+dash/dot pattern in an interval divided into \teximath{n}~subintervals
+of equal length. If the \teximath{i}th character is a dash or space,
+the \teximath{i}th~subinterval is drawn solid or empty,
+respectively. If the \teximath{i}th~character is a period, a dot is
+placed at the midpoint of the \teximath{i}th~subinterval.
+
+This pattern is applied to a path-like object as follows. The page
+length of each edge is divided by the current \code{dash\_size} and
+the ceiling (next largest integer) taken. This many copies of the
+current path style are scaled onto the edge. The first and last
+characters are adjacent in repeated units.
+
+There are three inequivalent ways to adjust the dash length/dot
+spacing in a non-line path: Change the \code{dash\_length}, create a
+path with a different number of points, or use a longer, repetitive
+pattern. For best results, the style string should not be longer than
+about a dozen characters.
+
+If you need several dashed/dotted line styles in multiple figures,
+it's best to define a custom header instead of hard-coding line
+styles. See Section~\ref{section:extensions} for guidance.
+\index{Path|)}
+
+
+\subsection{Text Objects}
+
+\index{Labels|(emph}
+\index{Labels!alignment}
+
+Two types of textual element may appear in a file: \emph{labels} (text
+boxes) and \emph{markers} (\LaTeX\ symbols). A marker occupies a box
+of zero size, and is placed at a specified Cartesian location. A label
+has typographical size, and is usually offset from its Cartesian
+location. For placement, an \emph{alignment point} is attached to each
+label, and Cartesian coordinates position the alignment point.
+
+\subsubsection*{Labels}
+
+A label is printed as a \LaTeX\ box. By default, the alignment point
+is its reference point, the intersection of the left edge and the
+baseline, which is used by \LaTeX\ to position the box on the
+page:\input{basepoint.eepic}
+
+\index{Labels!alignment|(}
+The alignment point may be \emph{offset} manually by a specified
+number of \code{pt}. Additionally, a label's location with respect to
+the alignment point can be chosen with an optional \LaTeX-style
+alignment option. This scheme allows labels to be placed easily where
+they will not overlap other parts of the figure, and ensures labels
+stay properly positioned when the size or aspect ratio of a figure
+changes.
+\findex{label}
+\begin{verbatim}
+ label(P posn, P offset, string msg, [align]);
+ label(posn, msg);
+\end{verbatim}
+The first two components of the \code{offset} argument are numbers
+of~\code{pt} to shift the alignment point right and up. The optional
+\code{align} argument may be one---or an appropriate pair---of
+\code{t}, \code{b}, \code{r}, or~\code{l} (top, bottom, right, left),
+or~\code{c} (center). These alignment options specify the position of
+the label \emph{relative to the Cartesian location}~\code{posn},
+namely they work \emph{opposite} to the way they work in \LaTeX.
+\begin{center}
+ \input{alignment_lr.eepic}\qquad
+ \input{alignment.eepic}
+\end{center}
+\index{Labels!alignment|)}
+
+The \code{msg} argument is usually a snippet of \LaTeX\ code enclosed
+in double quotes. \CXX~treats ``\verb+\+'' as an escape character, so
+a double backslash is needed in the source to get a single backslash
+in the output. For example,
+\begin{verbatim}
+ label(P(0,0), P(2,-1), "$\\rho = \\sin\\theta$", br);
+\end{verbatim}
+positions an alignment point \code{2pt}~right and \code{1pt}~below the
+(Cartesian) origin, and typesets the equation
+\teximath{\rho=\sin\theta} below and to the right.
+
+\index{Labels!rotated}
+\index{Angle units}
+Labels can be rotated; the (counterclockwise) angle is set in current
+angle units with the command \code{label\_angle(theta)}. For example,
+a rotation angle of~90 degrees prints labels along a vertical
+axis. Though label rotation has legitimate uses, it can make labels
+more difficult to read, defeating their purpose. Do not use rotated
+labels merely because they are available. As a practical matter, if an
+output file contains rotated labels, the enclosing document must use
+the \code{rotating} package. \code{elaps} automatically loads this
+package.
+
+\index{Affine map!action on labels}
+An \code{affine} behaves moderately intelligently when acting on a
+marker or label. The mapping is applied to the label's location, and
+the ``linear part'' is used to adjust the offset and label angle. No
+attempt is made to treat alignment. For best results, if a
+\code{screen} will have an \code{affine} applied to it, label
+positions should be fine-tuned only with offsets, not alignment
+arguments. In all situations, the font itself is unchanged; no
+attempt is made to print sheared, scaled, or reflected text. The
+sample file \filename{inverse.xp} illustrates the effect of affine
+maps on labels.
+
+
+\subsubsection*{Fonts and Type Size}
+
+\index{Fonts}
+\index{Labels!fonts in}
+By default, the font in an \ePiX\ figure is that of the enclosing
+document. The font size and face are changed with
+``declaration-style'' commands such as
+\findex{font\_size}
+\findex{font\_face}
+\begin{verbatim}
+font_size("Large");
+font_face("sc");
+\end{verbatim}
+The argument of \verb+font_size+ is a valid \LaTeX\ size. If no
+argument is given, \code{normalsize} is understood. \verb+font_face+
+accepts a two-letter string, appended to the string ``\code{text}'' to
+give a \LaTeX\ font declaration command (``\code{textsc}'' above).
+Finer-grained control is accomplished by placing \LaTeX\ commands
+into the label text.
+
+
+\subsubsection*{Label Attributes and Masked Labels}
+
+Each label command has a corresponding ``mask'' version
+(\code{masklabel}) that draws an opaque rectangle under the label
+text. The mask size exceeds the label's size by an amount of
+\emph{padding}, and the mask is itself surrounded by a rectangular
+\emph{border}, of specified color and width.
+\findex{label\_color}
+\findex{label\_mask}
+\findex{label\_pad}
+\findex{label\_border}
+\findex{no\_label\_border}
+\begin{verbatim}
+ label_color(color); // set label text color
+ label_mask(color=White()); // set mask color
+ label_pad(string len);
+
+ label_border(color, [len]); // set color (and line width)
+ label_border(len); // set line width only
+ no_label_border(); // turn off label borders
+\end{verbatim}
+
+
+\subsubsection*{Markers}
+
+\index{Marker types|(}
+\ePiX's marker types, listed in Table~\ref{table:marker}, are obtained
+with the command \verb+marker(P pt, <MARKER TYPE>);+ Several
+``dot-like'' marker types are available by name: \input{dots.eepic}
+\findex{spot}
+\findex{dot}
+\findex{ddot}
+\findex{box}
+\findex{bbox}
+\findex{ring}
+\findex{circ}
+\begin{verbatim}
+ spot(P pt); dot(P pt); ddot(P pt);
+ --- box(P pt); bbox(P pt);
+ ring(P pt); circ(P pt); ---
+\end{verbatim}
+A \code{circ} is filled with the current \code{mask\_color}, and a
+\code{ring} is ``hollow''. Each dot-like marker can also be called
+with label syntax, generating a labeled marker with one command.
+\begin{verbatim}
+ dot(P posn, offset=P(0,0), msg="", align=none); // etc.
+\end{verbatim}
+
+\findex{dot\_size}
+By default, \code{spot}~and \code{ring} are 4~pt in diameter;
+\code{dot}, \code{box}, and~\code{circ} are 3~pt in diameter;
+\code{ddot}~and \code{bbox} are 2~pt in diameter. At arbitrary
+diameter, a \code{spot} is \teximath{4/3}~the diameter of a~\code{dot}
+and a~\code{ddot} is \teximath{2/3}~the diameter. The command
+\code{dot\_size(diam=3)} sets the diameter of a \code{dot}, and hence
+the size of all dot-like markers.
+
+\begin{table}[tb]
+ \begin{center}
+ \input{marker.eepic}
+ \end{center}
+ \caption{\ePiX's \code{marker} types.}
+ \label{table:marker}
+\end{table}
+\index{Marker types|)}
+
+
+
+\subsubsection*{Reminders}
+
+When constructing and placing a label,
+\begin{itemize}
+\item Offsets are specified in \code{pt} (true length), not Cartesian
+ units: A label's location relative to its alignment point should not
+ depend on the logical or printed size of the figure.
+
+\item The label text is enclosed in double quotes (the single
+ character~\code{"}), and contains the \LaTeX\ code to generate the
+ label. Backslashes are doubled.
+ \index{Labels!backslash in}
+ \index{Labels!in double quotes}
+\end{itemize}
+\index{Labels|)}
+
+
+\subsection{Color Declarations}
+
+Old-style color declarations set the fill color, line color, and
+text color.
+\findex{rgb}
+\findex{cmyk}
+\begin{verbatim}
+ rgb(r, g, b); cmyk(c, m, y, k);
+ rgb(P); cmyk(P); // for function-controlled colors
+ red(d); // similarly for other primaries
+\end{verbatim}
+\index{Color|)}
+
+
+\section{Creating and Drawing Objects}
+
+Scene elements include geometric objects, coordinate grids, axis
+labels, and function plots. A few commands create an object (a point,
+line segment, circle, sphere, or plane) that can be used in subsequent
+computations, but most drawing commands automatically create, draw,
+and discard objects.
+
+
+\subsection{Geometric Data Structures}
+
+\index{Point|(}
+The simplest object in the world, and by far the most common named
+data structure, is~\code{P}, an ordered triple of real numbers
+(double-precision floats). The function~\code{P(x1,x2,x3)} creates the
+point~\teximath{(x_1,x_2,x_3)}. If only two arguments are provided,
+\teximath{x_3=0} by default. This convention allows \ePiX\ to treat
+2-~and 3-dimensional figures uniformly. The standard basis is
+available: \code{E\_1=P(1,0,0)}, etc.
+
+Depending on context, a \code{P} may represent either a
+\emph{location} (point) or a \emph{displacement} (vector). Almost all
+\ePiX\ functions treat a~\code{P} as a point. However, algebraic
+operators and commands that plot vector fields treat \code{P}
+arguments as displacements.
+
+Polar, cylindrical, and spherical coordinate \code{P}~constructors are
+sensitive to the current angular mode.
+\index{Angular mode}
+\findex{P}
+\findex{polar}
+\findex{cis}
+\findex{cyl}
+\findex{sph}
+\begin{verbatim}
+ P pt=polar(r,t); // (r*Cos(t), r*Sin(t), 0)
+ P pt=cis(t); // (Cos(t), Sin(t), 0) = polar(1, t)
+ P pt=cyl(r,t,z); // (r*Cos(t), r*Sin(t), z)
+ P pt=sph(r,t,phi); // polar(r,t)*Cos(phi) + (0,0,r*Sin(phi))
+\end{verbatim}
+
+Algebraic operations---addition/subtraction, scalar multiplication;
+scalar, cross, and componentwise products; orthogonalization---can
+be performed on~\code{P}s. In compound expressions, the binary
+operators below should be enclosed in parentheses, and scalars must be
+collected at left, \code{P}s at right.
+\findex{P.x1}
+\findex{P.x2}
+\findex{P.x3}
+\findex{J}
+\begin{verbatim}
+ double u=pt.x1(); // first coordinate of pt, etc.
+ P(a,b,c)|P(x,y,z); // scalar product, ax+by+cz
+ P(a,b,c)&P(x,y,z); // componentwise product (ax, by, cz)
+ P(a,b,c)*P(x,y,z); // cross product (bz-cy, cx-az, ay-bx)
+ J(p); // quarter turn about the x3-axis
+ p%q; // orthogonalization, p (mod q)
+\end{verbatim}
+Explicitly, \code{p\%q}~is the unique vector \code{p+k*q}
+perpendicular to~\code{q}.
+
+\code{P}~operations express mathematical relationships, and therefore
+imbue a figure with logical structure, making the input file easier to
+read, modify, and maintain. Commonly, a file preamble will define a
+few named points with hard-coded coordinates, then define additional
+points of interest using \code{P}~operators.
+\index{Point|)}
+
+
+\subsubsection*{Other Geometric Classes}
+
+In addition to~\code{P}, objects of type \code{Circle}, \code{Plane},
+\code{Segment}, and \code{Sphere} can be used for Euclidean geometry
+constructions. Simple affine operations are supplied for each type, as
+is a \code{draw()} function, which represents the object as a path in
+the screen.
+\findex{shift}
+\findex{move\_to}
+\findex{scale}
+\findex{draw}
+\begin{verbatim}
+ obj.shift(P arg); // translate by arg
+ obj.move_to(P arg); // move center to arg
+ obj.scale(double c); // scale about center by c
+ obj.draw();
+\end{verbatim}
+A \code{Segment}'s ``center'' is its midpoint. A \code{Plane} has no
+center; \code{move\_to} translates the \code{Plane} to pass through
+\code{arg}, and \code{scale} has no effect.
+
+\index{Circle}
+A \code{Circle} data structure consists of a center, radius, and a
+perpendicular unit vector. Three constructors are provided:
+\findex{Circle}
+\begin{verbatim}
+ Circle(center=P(0,0,0), double rad=1, normal=E_3);
+ Circle(P center, P point);
+ Circle(P p1, P p2, P p3);
+\end{verbatim}
+The second constructor creates the \code{Circle} parallel to the
+\teximath{(x_1,x_2)}~plane, with given center, and radius equal to the distance
+between the arguments. (A warning is printed if the second argument
+does not lie on the circle, namely, if the arguments do not lie in a
+plane parallel to the \teximath{(x_1,x_2)}~plane.) The third returns the
+\code{Circle} passing through the given points; the points must not be
+collinear.
+
+The data defining a \code{Circle} are recovered with member functions
+named \code{center()}, \code{radius()}, and \code{perp()}.
+
+\index{Plane}
+\findex{Plane}
+A \code{Plane} is specified by a point and normal vector, or by three
+non-collinear points. The \code{draw()} function clips the plane and
+draws the resulting polygon. Unless the clip box has been set
+manually, the clipped polygon's vertices will have large coordinates.
+
+\index{Segment}
+\findex{Segment}
+A \code{Segment} is constructed from its endpoints. The member
+function \code{midpoint()} returns the center.
+
+\index{Sphere}
+\findex{Sphere}
+A \code{Sphere} is specified by a point and a radius---by default the
+origin and unity, or by the center and a point on the sphere. Member
+functions \code{center()}~and \code{radius()} return the defining
+data. Capabilities specific to geography and spherical geometry are
+described below, pp.~\pageref{non-eucl}ff.
+
+The \code{draw()} function of a \code{Sphere} draws the horizon
+visible from the current viewpoint. While this horizon is a circle in
+object space, its image in the screen is generally an ellipse.
+Antipodal points are not generally mapped to points symmetrically
+placed with respect to the center of this ellipse. These effects are
+most pronounced when the viewpoint is close to the \code{Sphere} and
+the center is not close to the \code{target}.
+
+
+\subsubsection*{Intersection}
+
+\index{Intersection}
+
+To facilitate geometric computation, \ePiX's \code{Circle},
+\code{Plane}, \code{Segment}, and \code{Sphere} classes can be
+intersected with the \code{*}~operator.
+\texicomment
+Table~\ref{table:intersect}
+lists the return types for each pair of arguments. Intersection is
+commutative, so only the top half of the table is shown. For purposes
+of intersection, a \code{Segment} is extended into a line.
+The sample file \filename{pascal.xp} gives typical applications of
+objects and intersection.
+\findex{intersection}
+\begin{table}[hbt]
+\begin{center}
+ \begin{tabular}{c|cccc}
+ \code{*} &
+ \code{Segment} & \code{Circle} & \code{Plane} & \code{Sphere} \\
+ \hline
+ \code{Segment} & \code{P} & \code{Segment} & \code{P} & \code{Segment} \\
+ \code{Circle} & & \code{Segment} & \code{Segment} & \code{Segment} \\
+ \code{Plane} & & & \code{Segment} & \code{Circle} \\
+ \code{Sphere} & & & & \code{Circle}
+ \end{tabular}
+ \caption{Object intersection types.}
+ \label{table:intersect}
+\end{center}
+\end{table}
+\texicommentend
+
+A \code{Circle} has a center, radius, and unit normal; a \code{Plane}
+has a distinguished point and unit normal; a \code{Segment} has two
+endpoints; a \code{Sphere} has a center and radius. An object is
+\emph{malformed} if these conditions are not met. The constructors
+return well-formed objects with two exceptions: \code{Circle} and
+\code{Plane} create malformed objects if called with three collinear
+points. The operator~\code{*} returns a malformed object if either
+argument is malformed, or if the operands are disjoint, tangent, or
+coincident. Malformedness is benign: Calling \code{draw()} on a
+malformed object does nothing.
+
+
+\subsubsection*{Orthonormal Frames}
+
+A \code{frame} comprises three mutually perpendicular unit
+vectors. The constructor takes three vectors. The \code{frame}'s third
+vector~\teximath{e_3} is positively proportional to~\code{v3}, the
+second vector~\teximath{e_2} is positively proportional to
+\code{v2\%v3}, and the first is the cross product,
+\teximath{e_1=e_2\times e_3}. Thus, a \code{frame} is right-handed,
+and does not depend on~\code{v1}.
+
+The elements of a \code{frame} are named \code{sea}, \code{sky}, and
+\code{eye}, just as for the \code{camera}. A \code{frame} can be
+rotated through an arbitrary angle about any of its elements.
+\findex{frame}
+\begin{verbatim}
+ frame(); // the standard basis {E_1, E_2, E_3}
+ frame fr(v1, v2, v3); // orthonormalize {v1, v2, v3}
+ fr.sea(); // the first element of fr, etc.
+ fr.rot1(theta); // rotate fr through theta about sea, etc.
+\end{verbatim}
+
+
+\subsection{Path-Like Elements}
+
+Basic path-like objects are drawn with named commands. Arguments of
+polygon commands are endpoints/vertices. Except for \code{line}~and
+\code{Line}, the following are subject to filling.
+\findex{line}
+\findex{Line}
+\findex{triangle}
+\findex{rect}
+\findex{quad}
+\findex{circle}
+\begin{verbatim}
+ line(P p1, P p2, [double expand]);
+ Line(p1, p2); // draw line through p1, p2 (crop required)
+ triangle(P p1, P p2, P p3);
+ rect(P p1, P p2);
+ quad(P p1, P p2, P p3, P p4); // quadrilateral
+ circle(ctr=P(0,0,0), rad=1, normal=E_3);
+ circle(ctr, pt);
+ circle(pt1, pt2, pt3);
+\end{verbatim}
+The optional \code{line} argument is an expansion parameter:
+\code{line(p1,p2,t);} draws a segment centered at the midpoint of
+\code{p1}~and \code{p2}, with length scaled
+by~\teximath{2^{t/100}}. (Setting \teximath{t=100} doubles the length,
+while \teximath{t=-100} halves the length.) The arguments of
+\code{rect()} must lie in a plane parallel to a coordinate plane. The
+arguments to \code{circle} commands are the same as for \code{Circle}
+constructors.
+
+Quadratic and cubic splines are described by their control points. A
+list of~\code{P} is drawn as a ``natural'' spline (the \teximath{C^2}
+piecewise cubic curve with vanishing second derivatives at the
+endpoints); the number of points per cubic segment must be specified.
+Circular and elliptical arcs are given by center, a basis, angular
+range, and an optional number of intervals.
+\findex{spline}
+\findex{arc}
+\findex{ellipse}
+\begin{verbatim}
+ spline(P p1, P p2, P p3, [int n]); // quadratic
+ spline(P p1, P p2, P p3, P p4, [int n]); // cubic
+ spline(vector<P>, int n); // natural spline
+
+ arc(P ctr, rad, t_min, t_max); // parallel to (x1,x2)-plane
+ ellipse(P ctr, P v1, P v2); // in plane spanned by v1, v2
+ ellipse(P ctr, P v1, P v2, t_min, t_max, [int n]);
+\end{verbatim}
+\texicomment
+Mathematically, these commands draw parametric paths
+\begin{align*}
+ \text{Spline:}\quad&(1-t)^2 p_1 + 2(1-t)t p_2 + t^2 p_3,
+ && t\in[0,1] \\
+ \text{Spline:}\quad&(1-t)^3 p_1 + 3(1-t)^2t p_2 + 3(1-t)t^2 p_3 + t^3p_4,
+ && t\in[0,1] \\
+ \text{Arc:}\quad&\mathrm{ctr} + (\cos t)(\mathrm{rad},0,0)
+ + (\sin t)(0,\mathrm{rad},0),
+ && t\in[t_\mathrm{min}, t_\mathrm{max}] \\
+ \text{Ellipse:}\quad&\mathrm{ctr} + (\cos t)v_1 + (\sin t)v_2,
+ && t\in[t_\mathrm{min}, t_\mathrm{max}].
+\end{align*}
+\texicommentend
+If parameter bounds are omitted in an \code{ellipse} command, the
+entire ellipse is drawn. When the angular range subtends one or more
+full turns in an \code{arc}~or \code{ellipse} the curve is subject to
+filling.
+
+Commands for planar (half-)ellipses remain from \ePiX's early days:
+\findex{ellipse}
+\findex{ellipse\_left}
+\findex{ellipse\_right}
+\findex{ellipse\_top}
+\findex{ellipse\_bottom}
+\begin{verbatim}
+ ellipse(P ctr, P radius);
+ ellipse_left(P ctr, P radius);
+ ellipse_right(P ctr, P radius);
+ ellipse_top(P ctr, P radius);
+ ellipse_bottom(P ctr, P radius);
+\end{verbatim}
+If \code{radius} is \code{P(a,b)}, these commands draw all or half of
+the ellipse with given center in the \teximath{(x_1,x_2)} plane, axes
+parallel to the coordinate axes, and axis lengths \teximath{2a}~and
+\teximath{2b}.
+
+Two commands are available to mark off right angles or a subtended
+angle. Each accepts a spatial location and two non-zero directions,
+and draws a scene element in the plane spanned by the vectors.
+\findex{right\_angle}
+\findex{arc\_measure}
+\begin{verbatim}
+ right_angle(P loc, P v1, P v2, scale=8);
+ arc_measure(P loc, P v1, P v2, scale=8);
+ arc_measure(P loc, P v1, P v2, offset, text, align, scale=8);
+\end{verbatim}
+The \code{right\_angle} command does not check its arguments for
+perpendicularity. The \code{arc\_measure} commands mark the
+\emph{small} angle subtended by the directions; the label form places
+a label at the midpoint of the arc. The (optional) \code{scale}
+argument is the true size in~\code{pt} of the marker.
+
+
+\subsubsection*{Recursive Fractal Curves}
+
+\index{Path!fractal}
+Consider a path made up of equal-length segments that can point at any
+angle of the form~\teximath{2\pi k/n} radians, for \teximath{0\leq
+k<n}, like spokes on a wheel. A path is specified by a finite sequence
+of integers, taken modulo~\teximath{n}. For example, if
+\teximath{n=6}, then the sequence \teximath{0, 1, -1, 0} corresponds
+to the ASCII path \verb+_/\_+. \ePiX's fractal approximation starts
+with such a ``seed'' then recursively (up to a specified depth)
+replaces each segment with a scaled and rotated copy of the seed,
+Figure~\ref{fig:fractal}. The seed above generates the standard
+von~Koch snowflake fractal. In code:
+\findex{fractal}
+\begin{verbatim}
+ const int seed[] = {6, 4, 0, 1, -1, 0};
+ fractal(P(a,b), P(c,d), depth, seed);
+\end{verbatim}
+The first entry of \code{seed[]} (here~6) is the number of
+``spokes''~\teximath{n}, the second~(4) is the number of terms in the
+seed, and the remaining entries are the seed proper. The final path
+joins \teximath{(a,b)}~to \teximath{(c,d)}. The number of segments in
+the final path grows exponentially in the depth, so depths larger than
+5~or 6 are likely to exceed the capabilities of \LaTeX\ and/or
+PostScript.
+\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}\}}
+ \label{fig:fractal}
+\end{figure}
+
+
+\subsubsection*{Arrows}
+
+\index{Arrow}
+Line segments, splines, and arcs can be drawn with arrowheads at one
+end. In profile, an arrowhead's width is \code{3pt}, and its height
+is 5.5~times the width. The actual printed height depends on the
+head's orientation with respect to the camera. By default, an
+arrowhead is a filled triangle. The shape and size are adjusted with
+declarations:
+\findex{arrow\_width}
+\findex{arrow\_ratio}
+\findex{arrow\_inset}
+\begin{verbatim}
+ arrow_width(w=3); // width in pt
+ arrow_ratio(r=5.5); // height-to-width
+ arrow_inset(c=0); // base indent as frac of ht
+\end{verbatim}
+\input{arrow.eepic} Inset\teximath{=0}\qquad
+\input{arrow25.eepic} Inset\teximath{=0.25}\qquad
+\input{arrow50.eepic} Inset\teximath{=0.5} \\
+The \code{inset} must be between \teximath{-1}~and \teximath{1}. Each
+\code{arrow} command accepts an optional \code{scale} argument, which
+scales the arrowhead.
+\findex{arrow}
+\begin{verbatim}
+ arrow(P tail, P tip, [scale]);
+ arrow(P p1, P p2, P p3, [scale]); // spline arrows
+ arrow(P p1, P p2, P p3, P p4, [scale]);
+ arrow(P ctr, P v1, P v2, t_min, t_max, [scale]); // ellipse
+\end{verbatim}
+A few ``special-purpose'' commands are supplied:
+\findex{dart}
+\findex{aarrow}
+\findex{arc\_arrow}
+\begin{verbatim}
+ dart (P p1, P p2); // same as arrow(p1, p2, 0.5);
+ aarrow(P p1, P p2); // double-headed arrow <--->
+ arc_arrow(ctr, rad, t_min, t_max, [scale]);
+\end{verbatim}
+If an \code{arc\_arrow} is too short, nothing is drawn.
+
+
+\subsection{Coordinate Axes and Labels}
+
+\index{Labels!axis|(}
+\index{Axes!labeling}
+\index{Axes|(}
+\ePiX\ provides an \code{axis} class for coordinate axes. Labels are
+generated automatically in a variety of styles: decimal, scientific
+notation, fraction, and trigonometric fraction. Logarithmic axes and
+labels are available. Axis and labeling commands from Version~1.0 have
+been retained.
+
+
+\subsubsection*{The \code{axis} Class}
+
+An \code{axis} consists of a line segment divided into a specified
+number of equal-length subintervals by ``major'' (long) tick marks.
+Each subinterval may be divided further by ``minor'' (short) tick
+marks. Minor ticks may be equally-spaced (``Cartesian'') or
+logarithmically placed. Finally, a label is written at each major tick
+mark with specified offset and alignment. Labels are generated
+automatically from the endpoints, so the line should be parallel to a
+coordinate axis. Label attributes (masking, borders, font size and
+face, rotation angle) are determined by the current label style, not
+by the \code{axis}.
+
+The command
+\findex{axis}
+\begin{verbatim}
+ axis(P tail, P head, int n, P offset=P(0,0), [align = none]);
+\end{verbatim}
+creates an axis joining \code{tail} to \code{head}, divided into
+\code{n}~segments of equal length, with a major tick mark and label at
+each division point and endpoint. The \code{offset} and \code{align}
+arguments have the same meaning as for ordinary labels.
+
+The number and length of minor ticks, and the alignment of ticks, are
+controlled with member functions:
+\findex{axis.subdivide}
+\findex{axis.tick\_ratio}
+\findex{axis.align}
+\begin{verbatim}
+ axis Ax(P(a,c), P(b,c), n);
+ Ax.subdivide(n); // put n-1 minor ticks in each axis segment
+ Ax.tick_ratio(r); // minor length = r*major length
+ Ax.align(AL=c); // align all ticks; AL = t, b, l, r, or c
+\end{verbatim}
+By default, major ticks are \code{6pt}~long and twice the length of
+minor ticks. The global declaration \code{tick\_size(len)} sets the
+major length, subject to ``reasonable stylistic limits''. For visual
+consistency, tick lengths should not be changed casually.
+
+\index{Axes!labeling}
+Labels on an \code{axis} may be drawn in several styles, selected with
+member functions:
+\findex{axis.dec}
+\findex{axis.frac}
+\findex{axis.trig}
+\findex{axis.sci}
+\findex{axis.unmark}
+\findex{axis.precision}
+\findex{axis.align\_labels}
+\begin{verbatim}
+ Ax.dec(); // decimals (default)
+ Ax.frac(); // fractions, e.g. 0.5 -> \frac{1}{2}
+ Ax.trig(); // fractional multiples of \pi
+ Ax.sci(); // scientific notation, k\times base^N
+
+ Ax.unmark(double); // remove label at selected location
+ Ax.precision(p); // set number of digits for decimal labels
+ Ax.align_labels(AL); // re-align labels
+\end{verbatim}
+Arbitrary textual labels depending on one coordinate are obtained by
+writing a \code{string}-valued function of~\code{double} and
+``registering'' it:
+\findex{axis.label\_rep}
+\begin{verbatim}
+ // f represents x as a string in given precision and base
+ std::string f(double x, unsigned int prec, unsigned int base);
+ Ax.label_rep(f);
+\end{verbatim}
+For example, textual tags can be printed instead of numeric labels.
+
+By default, an \code{axis} is Cartesian. The member function
+\code{log(int b=10)} converts an \code{axis} to ``log mode'' with
+specified base; this affects both tick marks and labeling. If \code{b}
+is at least~3, minor tick marks appropriate for a logarithmic axis
+base~\code{b} are drawn. Second, labels are written in decimal or
+scientific notation appropriately for a logarithmic axis; that is,
+``\teximath{k\times b^N}'' (or its decimal value) is written at
+location \teximath{N+\log_b k}.
+
+Minor ticks of a log \code{axis} may be labeled individually; again,
+this is controlled with member functions:
+\findex{axis.tag}
+\findex{axis.tag235}
+\findex{axis.tags}
+\findex{axis.untag}
+\begin{verbatim}
+ Ax.tag(d); // labels at N+log_b(d)
+ Ax.tag235(); // tag 2, 3, and 5 if b=10
+ Ax.tags(); // tag 1, ..., b-1
+ Ax.untag(); // remove all tags, including 1
+ Ax.untag(double); // remove one tag, e.g. Ax.untag(9);
+\end{verbatim}
+
+For convenience, an \code{axis} object along an edge of the active
+\code{screen} can be created with a named command:
+\findex{top\_axis}
+\findex{bottom\_axis}
+\findex{left\_axis}
+\findex{right\_axis}
+\begin{verbatim}
+ top_axis(n, offset, align);
+ bottom_axis(n, offset, align);
+ left_axis(n, offset, align);
+ right_axis(n, offset, align);
+\end{verbatim}
+The ticks automatically point into the bounding box.
+
+The functions above create objects or set \code{axis} attributes, but
+write no output. Tick marks and labels can be printed separately, or
+at once:
+\findex{axis.draw}
+\findex{axis.draw\_ticks}
+\findex{axis.draw\_labels}
+\begin{verbatim}
+ Ax.draw(); // axis, tick marks, and labels
+ Ax.draw_ticks(); // axis and ticks only
+ Ax.draw_labels();
+\end{verbatim}
+
+
+\subsubsection*{Other Axis-Drawing Commands}
+
+\index{Axes!logarithmic}
+\ePiX\ formerly supplied commands for drawing simple axes and their
+labels. These commands have been kept for compatibility. Horizontal
+axes are generated with
+\findex{h\_axis}
+\findex{h\_log\_axis}
+\findex{v\_axis}
+\findex{v\_log\_axis}
+\begin{verbatim}
+ h_axis(p1, p2, n, align=c); // n subintervals (n+1 ticks)
+ h_log_axis(p1, p2, n, align=c, base=10);
+\end{verbatim}
+For vertical axes, use \code{v\_axis}. The style of tick mark is
+appropriate for an axis of the given type. Horizontal axis tick marks
+may be aligned \code{t}~(above the axis) or~\code{b}
+(below). Similarly, vertical axis ticks may be aligned \code{r}~or
+\code{l}.
+
+The endpoint arguments of a coordinate axis may be omitted, in which
+case they default to \teximath{p_1=(x_\mathrm{min},0)} and
+\teximath{p_2=(x_\mathrm{max},0)} for a horizontal axis, or to
+\teximath{p_1=(0,y_\mathrm{min})} and
+\teximath{p_2=(0,y_\mathrm{max})} for a vertical axis. If the bounding
+box has integer width and/or height, omitting the number of points
+draws tick marks one unit apart.
+
+Labels for a horizontal Cartesian or logarithmic axis are generated
+with the commands
+\findex{h\_axis\_labels}
+\findex{h\_axis\_masklabels}
+\findex{h\_axis\_log\_labels}
+\findex{h\_axis\_log\_masklabels}
+\findex{v\_axis\_labels}
+\findex{v\_axis\_masklabels}
+\findex{v\_axis\_log\_labels}
+\findex{v\_axis\_log\_masklabels}
+\begin{verbatim}
+ h_axis_labels(P p1, P p2, int n, P offset, [align]);
+ h_axis_masklabels(p1, p2, n, offset, [align]);
+ h_axis_log_labels(p1, p2, [n], offset, [align], base=10);
+ h_axis_log_masklabels(p1, p2, [n], offset, [align], base=10);
+\end{verbatim}
+Labels for a vertical axis are generated with \code{v\_axis\_labels},
+etc. The labels are automatically generated to match their horizontal
+location. The first puts \teximath{(n+1)}~evenly-spaced labels on the segment
+joining \code{p1}~and \code{p2}. As with ordinary labels, the
+\code{offset} is in~\code{pt}, and the optional \LaTeX-style alignment
+option positions the labels using their corners. The second command
+draws masked labels according to the current label masking
+attributes. The third writes labels in exponential notation, using the
+Cartesian coordinate as exponent.
+
+As for coordinate axes, the initial and final points may be omitted in
+an \code{axis\_[mask]labels} command, with the same defaults. The
+\code{offset} and number of labels must always be specified.
+
+
+\subsubsection*{Broken Axes}
+\index{Axes!broken}
+
+Broken axes are best drawn using page layout, especially if axis
+labels are to be drawn. To accomplish the task, create a screen for
+each piece of axis, using appropriate Cartesian coordinates for the
+corners, then \code{inset} the screens so the axis pieces are nearly
+end to end. A zig-zag glyph signifies the break:
+\findex{axis\_break}
+\begin{verbatim}
+ axis_break(P, P, scale=12);
+\end{verbatim}
+The \code{P} arguments are the screen coordinates of the ends to be
+joined; the optional third argument is the true height and width
+in~\code{pt} of the glyph. The sample file \filename{coord\_tricks.xp}
+uses layout and axis breaks.
+
+
+\subsubsection*{Coordinate Grids}
+
+Cartesian grids fill a coordinate rectangle, and have a specified
+number of lines in each direction. A polar grid has specified radius,
+and numbers of rings and sectors.
+\findex{grid}
+\findex{polar\_grid}
+\begin{verbatim}
+ grid(n1, n2); // fills the bounding box
+ grid(p1, p2, n1, n2); // fills the box with corners p1, p2
+ polar_grid(r, n1, n2);
+\end{verbatim}
+
+Log and semi-log grids are drawn with analogous syntax:
+\findex{log\_grid}
+\findex{log1\_grid}
+\findex{log2\_grid}
+\begin{verbatim}
+ log_grid (p1, p2, n1, n2, [base1], [base2]); // log-log
+ log1_grid(p1, p2, n1, n2, [base]); // log-lin
+ log2_grid(p1, p2, n1, n2, [base]); // lin-log
+\end{verbatim}
+The~\teximath{n_i} arguments dictate the number of squares, namely the number
+of orders of magnitude spanned in the logarithmic direction(s). The
+(optional) base arguments default to~10, and control the number of
+lines drawn per order of magnitude. As with Cartesian grids, the
+corners are optional; if omitted, the grid fills the bounding box.
+
+\index{Graph paper}
+Graph paper may be created by superimposing grids:
+\texicomment
+\begin{center}
+ \begin{minipage}[b]{2.5in}
+ \begin{footnotesize}
+\texicommentend
+\findex{pen}
+\findex{grid}
+\begin{verbatim}
+ pen(0.25);
+ grid(10*xsize(), 10*ysize());
+ pen(0.5);
+ grid(2*xsize(), 2*ysize());
+ pen(1);
+ grid(xsize(), ysize());
+\end{verbatim}
+\texicomment
+ \end{footnotesize}
+ \end{minipage}
+ \qquad
+ \input{graphpaper.eepic}
+\end{center}
+\index{Axes|)}
+\texicommentend
+
+\subsection{The Path Class}
+
+\index{Path!class}
+A \code{path} data structure is an ordered list of points that can be
+cropped, clipped, mapped, concatenated, and drawn. The first four
+constructors mirror polygon-drawing commands above. Function graphs
+and parametric paths are built from a real- or \code{P}-valued
+function~\code{f} of one variable.
+\findex{path}
+\begin{verbatim}
+ path(p1, p2, expand=0); // line (endpoints)
+ path(p1, p2, p3, [n]); // quadratic spline
+ path(p1, p2, p3, p4, [n]); // cubic spline
+ path(p1, v1, v2, t_min, t_max, [n]); // ellipse
+ path(f, t_min, t_max, [n]);
+\end{verbatim}
+
+The member function \code{pt()} accepts a~\code{P} or three (or two)
+doubles and appends the specified point to a \code{path}. This
+snippet creates a regular \teximath{n}-gon:
+\begin{verbatim}
+ path ngon; // declare new path
+ for (int i=0; i<=n; ++i)
+ ngon.pt(cis(i*full_turn()/n)); // works in all angle modes
+\end{verbatim}
+Compound paths may be built by concatenation. If \code{path1}~and
+\code{path2} share an endpoint, the commands
+\begin{verbatim}
+ path1 += path2;
+ path1 -= path2;
+\end{verbatim}
+replace \code{path1} with the result of traversing \code{path1}
+``forward'', then following \code{path2} in the forward or reverse
+direction (respectively). For expected results, the first
+(or last) point on~\code{path2} should be the last point
+of~\code{path1}. The notation suggests 1-dimensional homology
+chains. The sample file \filename{contour.xp} illustrates path
+creation and manipulation.
+
+A \code{path} is a data structure, and must be drawn explicitly to
+create visible output. By default a \code{path} is not a closed loop
+(even if the first and last points are the same), and is not filled
+when drawn. Member functions perform these tasks. Continuing the
+\teximath{n}-gon snippet above,
+\findex{path.close}
+\findex{path.fill}
+\findex{path.draw}
+\begin{verbatim}
+ ngon.close(); // mark path as closed
+ ngon.fill(); // draw filled region if filling is active
+ ngon.draw(); // print to the screen
+\end{verbatim}
+\code{path::close()} adds a closing edge if necessary. Once a
+\code{path} is closed, no more points can be added. A closed path
+clips and crops differently than an open \code{path} with the same
+data. \code{path::fill()} has no effect on an unclosed \code{path}.
+
+
+\subsection{Function Plotting}
+
+\index{Plotting|(}
+The noun ``map'' refers to a \CXX\ function that accepts one or
+more \code{double} arguments and returns a \code{double}~or
+a~\code{P}. Mathematically, a map can be depicted in two ways: as a
+graph (which retains information about the domain), or as a
+parametrized curve or surface (which discards domain
+information). \ePiX\ assumes that \code{double}-valued maps are
+graphed and \code{P}-valued maps are drawn parametrically. Either sort
+of depiction is called a ``plot''. \ePiX\ plots are either ``wire
+mesh'', produced by a \code{plot} command, or ``shaded'', produced by
+a \code{surface} command.
+
+
+\subsubsection*{Basic Plotting}
+
+For the moment, ``function'' means ``function of one variable''
+(precisely, a \code{double}-valued function of a \code{double}
+variable). A function graph depends on the domain and the number of
+points to use. Each of the commands
+\findex{plot}
+\findex{polarplot}
+\findex{shadeplot}
+\begin{verbatim}
+ plot(f, t_min, t_max, n);
+ polarplot(f, t_min, t_max, n);
+ shadeplot(f, t_min, t_max, n);
+\end{verbatim}
+graphs the function~\code{f} on the interval \code{[t\_min, t\_max]}
+by dividing the interval into \code{n}~subintervals of equal length.
+The first gives a Cartesian plot, the second a polar plot with bounds
+in current angular units, the third shades the region between the
+graph and the horizontal axis. If two functions are given to
+\code{shadeplot}, the region between their graphs is shaded.
+
+
+\subsubsection*{Domains and Wiremesh Plots}
+
+\index{Domain|(}
+An \ePiX\ \code{domain} is a coordinate box of dimension one, two, or
+three, specified by a pair of opposite corners and two \emph{meshes}
+(``coarse'' and ``fine'', respectively) which specify the amount of
+data to be plotted. Plotting is explained in detail below.
+\findex{domain}
+\begin{verbatim}
+ // [a1,a2] x [b1,b2]: n1 x n2 rectangles, m1 x m2 intervals
+ domain R2(P(a1,b1), P(a2,b2), mesh(n1,n2), [mesh(m1,m2)]);
+
+ // [a1,a2] x [b1,b2] x [c1,c2] divided analogously
+ domain R3(P(a1,b1,c1), P(a2,b2,c2),
+ mesh(n1,n2,n3), [mesh(m1,m2,m3)]);
+\end{verbatim}
+If unspecified, the fine mesh is the same as the coarse mesh. For
+expected behavior, the coarse mesh should ``divide'' the fine mesh, in
+that \teximath{m_i}~should be a (usually small) integer multiple
+of~\teximath{n_i} for each~\teximath{i}.
+
+A \code{domain} may be \emph{resized} in any coordinate for which the
+thickness is positive, and can be \emph{sliced} by setting one
+variable to a constant. The result of slicing is a \code{domain} whose
+dimension is one smaller than the original. Finally,
+``\code{slices}'' operators return the list of \code{domain}s obtained
+by setting one variable to evenly-spaced constants. By default, the
+number of slices is specified by the coarse mesh. An optional argument
+specifies the number of slices. This argument need not be related to
+the coarse mesh.
+\findex{domain.resize}
+\findex{domain.slice}
+\findex{domain.slices}
+\begin{verbatim}
+ R2.resize2(a,b); // [a1,b1] x [a,b]
+ R2.slice1(t); // set x1 = t
+ R3.slices3([n]); // (n+1) domains with x3 = const
+\end{verbatim}
+\begin{center}
+ \input{slices.eepic}
+\end{center}
+\smallskip
+When possible, resizing preserves grid square sizes. Generally,
+though, integer truncation occurs: If \code{R=domain(P(0,0), P(1,1),
+mesh(10,6))}, then \code{R.resize1(0,0.25)} is the rectangle
+\teximath{[0,0.25]\times[0,1]} subdivided into \teximath{2\times6}
+subrectangles, since \teximath{10\div4=2} in integer arithmetic. For
+expected behavior, choose mesh sizes to avoid integer truncation.
+
+
+The arguments of a \code{plot} command are a map, followed by either a
+domain or its logical equivalent.
+\findex{plot}
+\begin{verbatim}
+ double f(double t) { return t*t; }
+ P F(double u, double v) { return P(u, v, exp(u)*Sin(v)); }
+ P G(double u, double v, double w) { return P(v*w, u*w, u*v); }
+
+ plot(f, a, b, n); // f:[a,b] -> R, using n intervals
+ plot(F, R2); // graph of exp(u)*Sin(v)
+ plot(G, R3.slice2(0.5); // G: R^3 -> R^3 restricted to y=0.5
+\end{verbatim}
+By (compiler-enforced) convention, \code{plot} commands involving a
+\code{P}-valued map accept a \code{domain} argument, as in the second
+and third commands above. To plot a \code{double}-valued function, by
+contrast, supply the logical equivalent of a \code{domain}, usually
+the endpoints and the number of intervals, as in the first \code{plot}
+command above.
+
+Resizing and slicing allow a map~\code{F} to be plotted selectively
+over parts of its domain. This can be used to emphasize parts of the
+image, layer scene elements, patch surfaces together, and so forth.
+Resize and slice(s) commands may be used directly in a \code{plot}
+command:
+\findex{plot}
+\begin{verbatim}
+ plot(F, R2.resize1(0,0.5));
+ plot(F, R2.slices1());
+\end{verbatim}
+
+
+\subsubsection*{Meshes and Plotting}
+
+The \code{P}~arguments of a \code{domain} are a pair of opposite
+corners. The first \code{mesh} argument, the \emph{coarse} mesh,
+specifies the number of subdivisions in each coordinate direction.
+The second \code{mesh}, the \emph{fine} mesh, determines the number of
+points used in each direction when plotting.
+
+\begin{comment}
+Suppose the \code{domain}~\code{R2} is, as above, the rectangle
+\teximath{[0,3]\times[-1,2]}. The argument \code{mesh(12,6)} divides the
+rectangle a \teximath{12\times6}~array of subrectangles known as the
+\emph{coarse mesh}. A \code{P}-valued map~\code{F} of two variables is
+plotted over the edges of the coarse mesh. Rather than drawing
+quadrilaterals, however, \ePiX\ draws the image curves at the
+resolution specified by the argument \code{mesh(60,60)}, the
+\emph{fine mesh}. In this example, the curves in each direction are
+drawn using 60~line segments.
+\end{comment}
+
+Separating the roles of coarse and fine meshes allows a plot to
+conform closely to a surface without using a fine grid of curves.
+Both parts of Figure~\ref{fig:plot} are drawn with a
+\teximath{6\times20} coarse mesh. In the first picture, the fine mesh
+is also \teximath{6\times20}, while in the second, the fine mesh is
+\teximath{12\times60}.
+
+\begin{figure}[hbt]
+ \begin{center}
+ \input{plot_a.eepic}\hspace*{0.5in}
+ \input{plot_b.eepic}
+ \caption{Coarse and fine meshes.}
+ \label{fig:plot}
+ \end{center}
+\end{figure}
+
+The coarse mesh is significant only for domains of dimension at
+least~2. The coarse mesh's size determines the number of curves or
+surfaces plotted \emph{perpendicularly} to a coordinate direction,
+while the fine mesh's size determines the number of segments used
+\emph{along} that direction. For predictable results, the fine mesh
+should be a small multiple of the coarse mesh.
+
+Plotting works analogously for 3-dimensional \code{domain}s and maps
+depending on three variables: The ``one-dimensional skeleton'' of the
+\code{domain}'s image is drawn. A \code{P}-valued map of
+three variables can be plotted over a 1-~or 2-dimensional
+\code{domain}. (The effect may be unexpected unless the domain arises
+by slicing, however.) A map depending on one or two variables cannot
+be plotted over a 3-dimensional \code{domain}.
+\index{Domain|)}
+
+
+\subsubsection*{Shaded Surfaces}
+
+\index{Plotting!surface|(}
+
+\ePiX's shaded surface plotting implements a degree of hidden surface
+removal. The algorithm breaks a surface into mesh fragments, sorts
+them in decreasing (approximate) distance to the camera, and prints
+them. If filling is active, a mesh fragment is shaded according to
+the angle between the normal vector and the direction to the camera,
+simulating constant ambient lighting; otherwise, the current fill
+color is used. This technique works fairly well for surfaces without
+intersection, and even acceptably handles intersecting surfaces for
+which mesh elements intersect only along boundaries.
+
+The syntax of a \code{surface} command is identical to a \code{plot}
+command when only a single surface is drawn. For example,
+\findex{surface}
+\begin{verbatim}
+ surface(F, R, cull=0);
+\end{verbatim}
+plots the \code{P}-valued function~\code{F} over the domain~\code{R},
+the shaded equivalent of the corresponding \code{plot} command. The
+optional \code{cull} argument removes elements that point toward
+(\code{cull=-1}) or away from (\code{cull=1}) the camera. Naturally,
+orientation of mesh elements depends on the parametrization~\code{F},
+not merely on the surface. Culling reduces the output file size, but
+is useful mostly for closed, convex surfaces.
+
+There are special commands for surfaces of rotation; each accepts a
+final \code{cull} argument.
+\findex{surface\_rev}
+\begin{verbatim}
+ surface_rev(f, t_min, t_max, n_lats, n_longs);
+ surface_rev(f, g, t_min, t_max, n_lats, n_longs=24);
+ surface_rev(f, g, R, frame coords);
+\end{verbatim}
+The first revolves the graph of~\teximath{f} about the
+\teximath{x}-axis, the second uses the parametric curve
+\teximath{t\mapsto\bigl(f(t),g(t)\bigr)} as profile. In each case, the
+parameter interval \verb+[t_min,t_max]+ is divided into \verb+n_lats+
+equal-length subintervals, \verb+n_longs+ copies of the profile curve
+are drawn, and the complete surface (one full turn) is drawn.
+
+The third form uses a \code{domain} to control the range of
+longitudes, and draws a surface of rotation in the Cartesian
+coordinate system defined by the orthonormal basis \code{coords}, by
+default the standard basis. The arguments \code{f}~and \code{g} define
+a parametric curve in the plane spanned by the first two elements
+of~\code{coords}, and the first element is the axis of rotation.
+
+As in wire mesh plotting, the fine mesh is used to draw the boundaries
+of surface patches; this tends to make surfaces look smoother for
+modest-sized coarse meshes. If the coarse mesh is too coarse, however,
+two visually undesirable effects can occur. First, adjacent regions of
+the surface may be shaded very differently, since shading is constant
+over patches defined by the coarse mesh. Second, a patch nearly
+tangent to a line of sight may be drawn badly if the patch bends back
+on itself, since the boundary of the \emph{patch} is drawn, not the
+visible edge of the mathematical surface. See
+\filename{samples/artifacts.xp}.
+
+
+\subsubsection*{Multiple Domains and/or Maps}
+
+A scene containing two or more shaded surfaces cannot generally be
+built up one surface at a time. Instead, multiple surfaces must be
+assembled into a single data structure before they can be drawn.
+Multiple surfaces are built from one or more maps and one or more
+2-dimensional \code{domain}s. In the code snippets below, \code{F}~and
+\code{G} are \code{P}-valued functions of 3~variables, and~\code{R} is
+a 3-dimensional \code{domain}.
+
+To plot the images of several \code{domain}s under a \emph{single
+map}, assemble the \code{domain}s into a list if necessary, then issue
+a \code{surface} command:
+\findex{surface}
+\findex{domain\_list}
+\findex{domain\_list.add}
+\begin{verbatim}
+ surface(F, R.slices3(), cull=0);
+
+ domain_list DL(R.slice1(0)); // build domain list
+ DL.add(R.slice2(0.5)); // add a domain, etc.
+ surface(G, DL, cull=0); // draw
+\end{verbatim}
+For multiple maps, \ePiX\ provides the \code{scenery}
+class. Conceptually, \code{scenery} is an agglomeration of shaded
+surfaces, built one surface at a time from maps and 2-dimensional
+\code{domain}s. The \code{add} function accepts two arguments---a map,
+and either a \code{domain} or a list of \code{domain}s---and
+contributes its data to the \code{scenery} rather than plotting
+immediately. Completed \code{scenery} is drawn manually.
+\findex{scenery}
+\findex{scenery.add}
+\findex{scenery.draw}
+\begin{verbatim}
+ scenery S(F, R.slice3(0.25)); // S contains one surface
+ S.add(F, R.slice2(0)); // S contains two surfaces
+ S.add(G, R.slices1(3)); // S contains six surfaces
+ S.draw(cull=0);
+\end{verbatim}
+Complete examples are included in the \filename{samples} directory:
+\filename{spherical.xp}~and \filename{minkowski.xp}.
+
+In principle, a scene may contain arbitrarily many surfaces. However,
+figures that contain many objects tend to tax \LaTeX's internal
+stacks. Frequent color changes exacerbate the problem. Even if you
+use \filename{hugelatex} (or increase \LaTeX's memory), a figure
+containing more than a few thousand mesh elements is unlikely to
+compile. At moderate resolution, a surface can easily contain
+1000~patches. Each shell script has a command-line option to invoke
+\filename{hugelatex}; your mileage may vary.
+
+
+\subsubsection*{User-Specified Color Shading}
+
+\index{Color!surface plotting}
+By default, a \code{surface} or \code{scenery} is colored according to
+the current fill color. For finer control, each \code{surface},
+\code{surface\_rev}, and \code{scenery} command accepts an optional
+position-dependent \code{color} specification.
+\findex{surface}
+\findex{surface\_rev}
+\findex{scenery}
+\findex{scenery.add}
+\begin{verbatim}
+ surface(F, R, color, cull=0);
+ surface_rev(f, [g], t_min, t_max, n_lats, n_longs, color);
+ surface_rev(f, g, R, color, [coords]);
+
+ scenery S(F, R, color);
+ S.add(F, R, color);
+\end{verbatim}
+The \code{color} argument is a \code{P}-valued function of two or
+three \code{double}s whose output is interpreted as a set of
+\code{RGB}~densities. If \code{color} takes two arguments, they are
+\code{domain} coordinates, and the surface is colored according to
+parameter values. If \code{color} takes three arguments, they are
+Cartesian coordinates, and the surface is colored according to spatial
+location. Please see the sample files
+\filename{surface\_shade.xp}~and \filename{S2\_harmonics.xp}.
+\index{Plotting!surface|)}
+
+
+\subsection{Calculus Plotting}
+\index{Plotting!calculus|(}
+
+\ePiX\ provides high-level commands for plotting derivatives and
+definite integrals, Riemann sums, tangent lines, slope- and vector
+fields, and solutions of planar and spatial systems of differential
+equations.
+
+In this section, \code{f}~and \code{g} are \code{double}-valued
+functions of one variable.
+
+\subsubsection*{Utility Functions}
+
+\findex{sup}
+\findex{inf}
+\findex{newton}
+\begin{verbatim}
+ sup(f, a, b); // max/min of f on [a,b]
+ inf(f, a, b);
+ newton(f, g, x0); // find approximate crossing point
+\end{verbatim}
+Newton's method returns the crossing point of the given functions,
+starting from the specified seed, which should be reasonably close to
+the expected solution. If a critical point is hit or 5~iterations
+pass, a warning is issued and the current result (probably incorrect)
+is returned. The second function~\teximath{g} defaults to the zero function if
+omitted.
+
+\subsubsection*{Derivatives and Integrals}
+
+The classes \code{Deriv}~and \code{Integral} are used to calculate
+values of derivatives and integrals, and to plot these functions.
+\findex{Deriv}
+\findex{Deriv.eval}
+\findex{Deriv.left}
+\findex{Deriv.right}
+\findex{Integral}
+\findex{Integral.eval}
+\begin{verbatim}
+ Deriv df(f); // function object: df(x) = f'(x)
+ df.eval(t); // return f'(t)
+ df.left(t); // deriv from left at t: (f(t)-f(t-dt))/dt
+ df.right(t); // deriv from right at t: (f(t+dt)-f(t))/dt
+
+ Integral prim(f,a); // function object: prim(x) = int_a^x f
+ prim.eval(b); // numerical integral of f over [a,b]
+ double val(Integral(f).eval(1)); // val = \int_0^1 f
+\end{verbatim}
+The lower limit on an integral is~0 by default. \code{Deriv}s and
+\code{Integral}s can be used directly in a \code{plot} command:
+\findex{plot}
+\findex{riemann\_sum}
+\begin{verbatim}
+ plot(Deriv(f), a, b, n); // plot f' over [a,b]
+ plot(Integral(f, x0), a, b, n);
+ riemann_sum(f, a, b, n, TYPE);
+\end{verbatim}
+The second graphs the definite integral \teximath{x\mapsto\int_{x_0}^x
+f(t)\,dt} over~\teximath{[a,b]}. As above, \teximath{x_0}~defaults
+to~0. The third draws rectangles or trapezoids whose area approximates
+the definite integral of~\teximath{f} over~\teximath{[a,b]}. The
+\code{TYPE} may be \code{UPPER}, \code{LOWER}, \code{LEFT},
+\code{RIGHT}, \code{MIDPT}, or~\code{TRAP}.
+
+Tangent lines and envelopes (families of tangent lines) are drawn with
+\findex{tan\_line}
+\findex{envelope}
+\findex{tan\_field}
+\begin{verbatim}
+ tan_line(f, t); // f real- or vector-valued
+ envelope(f, t_min, t_max, n); // family of tangent lines
+ tan_field(f, g, t_min, t_max, n); // field of tangents
+\end{verbatim}
+The sample files \filename{conic.xp}~and \filename{lissajous.xp}
+illustrate these features.
+
+
+\subsubsection*{Systems of Differential Equations}
+
+Let \code{F}~be a \code{P}-valued function of two or three variables.
+\findex{ode\_plot}
+\findex{flow}
+\begin{verbatim}
+ ode_plot(F, p_0, t_min, t_max, n);
+ flow(F, p_0, t_max, n);
+\end{verbatim}
+The first plots the solution curve of the initial-value problem
+\teximath{\dot{x}=F(x)}, \teximath{x(0)=p_0}, over the specified time
+interval. If \teximath{t_\mathrm{min}} is omitted, its value is~0, so
+the curve starts at~\teximath{p_0}. With manual calculation to rotate
+a planar field a quarter turn, \code{ode\_plot} can be used to draw
+level curves (isobars) of a function of two variables; see the sample
+file \filename{dipole.xp}. The \code{flow} function returns the
+result of starting at~\teximath{p_0} and flowing by~\teximath{F} for
+time~\teximath{t_\mathrm{max}}, using Euler's method with~\teximath{n}
+time steps. This is useful for placing markers or arrowheads precisely
+along a flow line.
+
+A planar or spatial vector field itself may be plotted over a
+domain~\code{R} in three styles:
+\findex{vector\_field}
+\findex{dart\_field}
+\findex{slope\_field}
+\begin{verbatim}
+ vector_field(F, R, [scale]); // true length
+ dart_field (F, R, [scale]); // const length
+ slope_field (F, R, [scale]); // const length
+\end{verbatim}
+The field is sampled at the grid points of the coarse mesh. If the
+domain is 2-dimensional, the plot is a planar slice of the field, even
+if the field depends on three variables. If the domain is
+3-dimensional, the field is drawn in successive slices
+\teximath{x_3=\mathrm{const}}, starting at the height of the first
+corner of~\code{R} and ending at the height of the second corner.
+
+The optional final argument, which defaults to~\teximath{1}, scales the
+arrowheads in a vector field, and scales the (constant) length of
+field elements for slope and dart fields. The sample files
+\filename{layout2.xp}, \filename{lorenz.xp}, \filename{slopefield.xp},
+and \filename{vfield.xp} illustrate usage.
+
+In each field-plotting command, the domain argument may be replaced by
+two points, representing corners of a coordinate rectangle, and two
+integers, the number of grid intervals in the selected coordinate
+directions. Only planar slices of a vector field can be plotted using
+the alternative syntax.
+\index{Plotting|)}
+
+
+\subsection{Non-Euclidean Geometry}
+\label{non-eucl}
+
+\ePiX\ provides limited features for spherical and hyperbolic
+geometry: the ability to draw lines in the half-plane and Poincar\'e
+disk models of the hyperbolic plane, and to draw latitudes,
+longitudes, great circle arcs, spherical triangles, regular polyhedra,
+and parametrized curves on a sphere.
+
+Hyperbolic line segments are specified by their endpoints in the upper
+half space or ball (Poincar\'e) models. In each case there is no
+output if either endpoint lies outside the model.
+\findex{hyperbolic\_line}
+\findex{disk\_line}
+\begin{verbatim}
+ hyperbolic_line(p, q);
+ disk_line(p, q);
+\end{verbatim}
+For compatibility with 2-dimensional hyperbolic space, the half-space
+model is the set \teximath{\{(x_1,x_2,x_3)\mid x_2>0\}}.
+
+\index{Plotting!spherical|(}
+A \code{frame} determines geographical coordinates on a \code{Sphere}:
+the first element points toward longitude~0 on the equator, the third
+element points to the north pole. A latitude line depends on a
+\code{Sphere}, a \code{frame}, the numerical latitude, and a range of
+longitudes. A longitude line is described similarly.
+\findex{latitude}
+\findex{longitude}
+\findex{back\_latitude}
+\findex{back\_longitude}
+\begin{verbatim}
+ latitude(lat, long_min, long_max, Sphere S, frame coords);
+ longitude(lngtd, lat_min, lat_max, Sphere S, frame coords);
+\end{verbatim}
+By default, \code{coords} is the standard \code{frame} and \code{S} is
+the unit sphere. These commands draw only the portion of the curve
+that is visible from the current viewpoint. The function
+\code{back\_latitude} draws the invisible portion of a latitude line.
+
+Spherical arcs and triangles are described by their endpoints. Only
+the direction vector from the center of the sphere to an endpoint is
+significant; if a sphere is scaled or moved, the same function call
+will draw the corresponding object on the new sphere.
+
+The following draw the visible (front) portions of great circle arcs:
+\findex{front\_arc}
+\findex{front\_arc2}
+\findex{front\_line}
+\findex{back\_arc}
+\findex{back\_arc2}
+\findex{back\_line}
+\begin{verbatim}
+ front_arc(p1, p2, S); // short arc on S from p1 to p2
+ front_arc2(p1, p2, S); // arc from p1 to -p1 through p2
+ front_line(p1, p2, S); // great circle through p1 and p2
+\end{verbatim}
+Triangles and regular (Platonic) polyhedra are provided. The sample
+file \filename{sample/polyhedra.xp} illustrates usage.
+\findex{front\_triangle}
+\findex{front\_tetra}
+\findex{front\_cube}
+\findex{front\_octa}
+\findex{front\_dodeca}
+\findex{front\_icosa}
+\findex{back\_triangle}
+\findex{back\_tetra}
+\findex{back\_cube}
+\findex{back\_octa}
+\findex{back\_dodeca}
+\findex{back\_icosa}
+\begin{verbatim}
+ front_triangle(p1, p2, p3, S); // spherical triangle
+ front_tetra(S, coords); // regular tetrahedron
+ front_cube(S, coords); // hexahedron
+ front_octa(S, coords); // octahedron
+ front_dodeca(S, coords); // dodecahedron
+ front_icosa(S, coords); // icosahedron
+\end{verbatim}
+Each function has a \code{back} version, which draws the hidden
+portion. The tetrahedron, cube, and octahedron are (up to scale)
+inscribed in the cube of side length~\teximath{2} centered at the origin whose
+sides are parallel to~\code{frame}. The point \teximath{(1,1,1)} is a vertex of
+the tetrahedron.
+
+Up to scale, the icosahedron's vertices lie on the golden rectangle
+with vertices \teximath{(\pm\gamma,0,\pm1)} and its images under cyclic
+permutation of coordinates. The dodecahedron is dual to the
+icosahedron.
+
+\subsubsection*{Spherical Plotting}
+
+Parametrized paths on a \code{Sphere~S} (by default the unit sphere)
+can be specified either by radial projection of a \code{P}-valued
+curve, or by stereographic projection of a plane curve given as a pair
+of \code{double}-valued functions:
+\findex{frontplot\_R}
+\findex{frontplot\_N}
+\findex{frontplot\_S}
+\findex{backplot\_R}
+\findex{backplot\_N}
+\findex{backplot\_S}
+\begin{verbatim}
+ frontplot_R(phi, t_min, t_max, n, [S]); // radial
+ frontplot_N(f1, f2, t_min, t_max, n, [S]); // from north pole
+ frontplot_S(f1, f2, t_min, t_max, n, [S]); // from south pole
+\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 \teximath{\{x_3=0\}} to the unit sphere by
+projection from the corresponding pole: \teximath{N=(0,0,1)},
+\teximath{S=(0,0,-1)}.
+
+Each spherical plot command has a \code{back} version that prints only
+the portion of the path invisible from the current 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.
+
+
+\subsection{Data Plotting}
+\index{Plotting!data|(}
+\index{Data plotting|(}
+
+Files of numerical data can be created, manipulated, analyzed,
+plotted (paths, scatter plots, and histograms), read, and written.
+The format for a data file is one or more floating-point
+numbers per line, with the same number of entries per line. Anything
+that appears on a line after the \LaTeX\ comment character~\code{\%}
+is a comment.
+
+\ePiX\ provides two \code{plot} commands for file data. The first
+facilitates plotting selected columns; the second simplifies plotting
+the first two columns with one or both scales logarithmic. Either form
+can be used to plot selected columns logarithmically.
+
+The general commands read numbers from two or three columns of a
+specified file, pass them as arguments to a \code{P}-valued
+function~\code{F}, and plot the resulting points:
+\findex{plot}
+\begin{verbatim}
+ plot("filename", STYLE, [i_1], [i_2], [i_3], [F]);
+ plot("filename", STYLE, F, [i_1], [i_2], [i_3]);
+\end{verbatim}
+The first argument is the name of the data file. The \code{STYLE} may
+be \code{PATH}, which joins the points in the order they appear, or
+any of the marker types in Table~\ref{table:marker}. The
+integers~\teximath{i_k} specify columns from which to extract data; these
+default, respectively, to the first column, second column, and null (a
+column of zeroes). If the ``coordinate system''~\code{F} is omitted in
+the first command, it defaults to the Cartesian point constructor. The
+function~\code{F} is mandatory in the second form; useful choices
+include \code{log\_log}, \code{log\_lin}, and~\code{lin\_log}, which
+plot the corresponding coordinate logarithmically.
+
+
+\subsubsection*{Data Files}
+
+For more elaborate analysis, the \code{data\_file} class presents an
+interface to a file as an ordered list of columns. There are two
+general ways to create a \code{data\_file}: read in an external file,
+or generate data (up to three columns) using specified
+\code{double}-valued functions. In the constructors below, each
+function~\code{fi} is a \code{double}-valued function of one variable.
+\findex{data\_file}
+\findex{data\_file.read}
+\begin{verbatim}
+ data_file DF("my_data"); // read data from disk file
+ data_file DF(f1, t_min, t_max, num_pts); // values of f1
+ data_file DF(f1, f2, t_min, t_max, num_pts);
+ data_file DF(f1, f2, f3, t_min, t_max, num_pts);
+ data_file DF(3); // create empty data_file with 3 columns
+ DF.read("file1"); // read a disk file
+\end{verbatim}
+
+Columns of a \code{data\_file} can be transformed by a user-specified
+function, averaged, correlated, extracted (for use by other code),
+scatter plotted, and written to a disk file at specified
+precision. Below, the function~\code{f} is a \code{double}-valued
+function of one variable and~\code{F} is a \code{P}-valued function of
+two or three variables, whose components are written back to the
+selected columns.
+\findex{data\_file.transform}
+\begin{verbatim}
+ DF.transform(f, i); // apply f to selected column(s)
+ DF.transform(F, i=1, j=2);
+ DF.transform(F, i, j, k);
+\end{verbatim}
+Basic statistical operations on columns are provided.
+\findex{data\_file.dot}
+\findex{data\_file.avg}
+\findex{data\_file.var}
+\findex{data\_file.covar}
+\findex{data\_file.regression}
+\begin{verbatim}
+ DF.dot(i,j); // dot product of columns i, j
+ DF.avg(i); // mean of column i
+ DF.var(i); // population variance
+ DF.covar(i,j); // covariance
+ DF.regression(i,j); // plot regression line
+\end{verbatim}
+A \code{data\_file} is scatter plotted using syntax as described above.
+% The output is cropped automatically to the bounding box.
+\findex{data\_file.plot}
+\begin{verbatim}
+ DF.plot(STYLE, [i1], [i2], [i3], [F]);
+ DF.plot(STYLE, F, [i1], [i2], [i3]);
+\end{verbatim}
+Histograms and bar charts are described below.
+
+A \code{data\_file} can be written to a disk file as raw data, or in
+specified format. Below, \code{fmt} denotes a \code{string}-valued
+formatting function of two variables and \filename{myfile} is the
+name of the disk file to be written.
+\findex{data\_file.precision}
+\findex{data\_file.write}
+\begin{verbatim}
+ DF.precision(4); // set to 4 significant figures
+ DF.write("myfile"); // write as tab-separated columns
+ DF.write("myfile", fmt, [i1], [i2]); // apply fmt to cols
+\end{verbatim}
+A column can be extracted as a \code{C++}~\code{vector} for use by
+another function.
+\findex{data\_file.column}
+\begin{verbatim}
+ DF.column(i); // i-th column
+ DF.column(f, i); // i-th column, transformed by f
+\end{verbatim}
+
+
+\subsubsection*{Data Containers}
+
+\ePiX\ provides a \code{data\_mask} class for culling data from a file
+according to the values in a specified column, and a \code{data\_bins}
+class for sorting data by value.
+
+A \code{data\_mask} consists of an interval of numbers and a
+``filter'' function. The (closed, open, or half-open) interval is
+given as a string in standard mathematical notation, or by its
+endpoints (for a closed interval). The filter is a
+\code{double}-valued function of \code{double}, by default the
+identity, \teximath{f(x)=x}.
+\findex{data\_mask}
+\begin{verbatim}
+ data_mask dm("[a, b]", [f]);
+ data_mask dm(a, b, [f]);
+\end{verbatim}
+A \code{data\_mask} ``passes'' inputs~\teximath{x} if~\teximath{f(x)}
+lies in the interval. The member function \code{reverse()} inverts
+this logical test.
+
+The \code{data\_file} class has \code{prune} functions to cull
+rows for which a specified column's entry satisfies a
+\code{data\_mask}'s criterion.
+\findex{data\_mask.prune}
+\begin{verbatim}
+ DF.prune(dm, i); // remove row if i-th column entry fails
+ DF.prune(a, b, i); // remove row if i-th column outside [a,b]
+\end{verbatim}
+
+A \code{data\_bins} object models an interval divided at specified
+locations into ``bins'', not necessarily of equal length. Numerical
+data is read in and the number of points in each bin counted. The
+lifetime of a \code{data\_bins} object has two stages. First, ``cuts''
+(endpoints of subintervals) are added. Then, once data is read, the
+cuts are ``locked'' and cannot subsequently be changed.
+\findex{data\_bins}
+\findex{data\_bins.cut}
+\findex{data\_bins.read}
+\begin{verbatim}
+ // [xmin, xmax] divided into n equal intervals, 1 by default
+ data_bins db(xmin, xmax, [n]);
+ db.cut(x); // add a cut at x (if x is in bounds)
+ db.read(vector<double>); // read data, lock bins
+\end{verbatim}
+
+\index{Histograms}
+\index{Bar Charts}
+A \code{data\_bins} object can be plotted as a histogram (rectangles'
+\emph{area} is proportional to the bin population), bar chart
+(rectangles' \emph{height} is proportional to the bin population), or
+spline interpolation of a bar chart.
+\findex{data\_bins.histogram}
+\findex{data\_bins.bar\_chart}
+\findex{data\_bins.plot}
+\begin{verbatim}
+ db.histogram(c=1); // c = vertical scale factor
+ db.bar_chart(c=1);
+ db.plot(c=1);
+\end{verbatim}
+By default (\code{c=1}), the height of a bar chart rectangle is the
+fraction of the total population contained in the bin; thus, the
+height is always between 0~and 1. For a histogram, the height of a
+rectangle is the fraction of the population per horizontal unit in the
+bin; thus, the total area over an interval~\teximath{[a,b]} does not
+depend on how~\teximath{[a,b]} has been subdivided. The sample files
+\filename{dataplot.xp}~and \filename{histogram.xp} illustrate use.
+
+Statistical convention dictates cuts be chosen distinctly from data
+values; that is, values should all fall strictly within a bin, not at
+a boundary point. With large, unknown data sets, this convention may
+be difficult to uphold. \ePiX\ attempts to handle anomalous data
+intelligently, by keeping counts of values ``out-of-range'' or
+``on-cut''.
+
+In detail, if \teximath{x<a} or \teximath{x>b} is a data value, it is
+counted as out-of-range and does not contribute to the histogram
+population. If \teximath{x=a} or \teximath{x=b}, the value counts as
+both out-of-range and on-cut but is added to the population of the
+lowest or highest bin, respectively. Any other cut appearing as a data
+input is flagged as on-cut, and increments the population of each
+adjacent bin by one-half. When a histogram or bar chart is written,
+\ePiX\ prints a warning message summarizing the number of anomalous
+data seen.
+
+
+\subsubsection*{Error Bars}
+\index{Error bars}
+
+Simple horizontal and vertical error bars are provided. The final
+(optional) argument is the true height or width (respectively) in pt.
+\findex{h\_error\_bar}
+\findex{v\_error\_bar}
+\begin{verbatim}
+ h_error_bar(P location, double error, <mark type>, ht=6);
+ v_error_bar(P location, double error, <mark type>, wd=6);
+\end{verbatim}
+
+To create more complex elements, such as asymmetric bars, whisker
+plots, labeled error bars, and the like, write a custom function using
+true-size drawing, see page~\pageref{truesize}. For example, a
+fillable, labeled, asymmetric, vertical rectangular error bar can be
+implemented (entirely in \ePiX) like this:
+\begin{verbatim}
+ void error_bar(P loc, double lo, double hi, P offset,
+ std::string text, align, double wd=6)
+ {
+ const double width(pt_to_screen(0.5*wd)); // converts to 3pt
+ rect(loc - P(width, lo), loc + P(width, hi));
+ line(loc - P(width, 0), loc + P(width, 0));
+ label(loc + P(width, 0), offset, text, align);
+ }
+\end{verbatim}
+For stylistic uniformity, functions such as this should be put into a
+library and used systematically. Section~\ref{section:extensions}
+outlines the process of writing, compiling, and using a custom
+library.
+\index{Plotting!data|)}
+\index{Data plotting|)}
+
+
+\subsection{Legends}
+\index{Legends}
+
+A \code{legend} systematically labels different parts of a plot by
+associating visual ``keys'' with explanatory text. This tends to be
+most useful for plots containing several distinct but conceptually
+related graphs requiring contrast.
+
+Visually, a \code{legend} is represented as an aligned list of rows,
+each containing a box (the key), a gap (the label skip), and some
+text. These rows are printed in a (usually large) masked label. By
+default, keys are \code{12pt}~squares bordered in black, the label
+skip is~\code{6pt}, the background is white, and the border is plain
+black. These attributes are controlled (simultaneously for all items)
+with member functions. Parameters of type \code{double} represent
+lengths in~\code{pt}.
+\findex{legend}
+\findex{legend.backing}
+\findex{legend.border}
+\findex{legend.item\_border}
+\findex{legend.label\_skip}
+\findex{legend.key\_size}
+\begin{verbatim}
+ legend L;
+ L.backing(color); // set background
+ L.border(color, [double]); // set border color [and width]
+ L.border(double); // border width
+
+ L.item_border(color, [double]);
+ L.item_border(double); // same, for item borders
+
+ L.label_skip(double);
+ L.key_size(double);
+\end{verbatim}
+
+
+\subsubsection*{Legend Keys}
+
+There are three types of legend key, representing filled regions,
+paths, and markers. Fill and path keys get their visual attributes
+from the current drawing state. A mark key must be told the marker
+type. Each is created by specifying the item text.
+\findex{legend.fill\_item}
+\findex{legend.path\_item}
+\findex{legend.mark\_item}
+\begin{verbatim}
+ L.fill_item(text);
+ L.path_item(text);
+ L.mark_item(<mark type>, text);
+\end{verbatim}
+Keys in the printed legend appear in the same order they are created
+in the input file.
+
+
+\subsubsection*{Creating a Legend}
+
+Normally, a \code{legend} is defined near the start of a file, and an
+item is added at the point in the file where the corresponding object
+or plot is drawn, so that the item receives the correct attributes. A
+\code{legend} is placed into the figure with the \code{draw}
+function. The arguments have the same meaning as for ordinary
+\code{label}s.
+\findex{legend.draw}
+\begin{verbatim}
+ L.draw(P location, P offset, align);
+\end{verbatim}
+All three arguments are mandatory. ``Global'' \code{legend} settings
+(border, backing, etc.) may be changed anywhere between the
+\code{legend}'s creation and \code{draw} function. The sample file
+\filename{legend.xp} revisits the example on
+page~\pageref{taylor_poly}, including a trig-labeled axis and a
+legend. The file \filename{shadeplot.xp} contains filled keys, and
+\filename{dataplot.xp} contains a \code{legend} with items of mixed
+type.
+
+
+\section{More About \CXX}
+\index{Cplusplus@\CXX|(emph}
+
+A textbook or similarly detailed reference is essential for serious
+study of~\code{C} or~\CXX. \emph{The \code{C} Programming Language},
+second edition, by Kernighan~and Ritchie~\cite{KnR}, is an excellent,
+manageable resource for the basics of procedural
+programming. \emph{C++ Primer Plus}, by Stephen Prata~\cite{Prata},
+clearly lays out the extensive details of~\CXX. Marshall Cline's
+\emph{\CXX\ FAQ Lite}~\cite{Cline} engagingly discusses common points
+of confusion and furnishes tips on good design and programming.
+
+\CXX\ is a powerful, complex language whose syntax is similar to that
+of~\C, or to the scripting languages of Maple~and Mathematica. An
+\ePiX\ input file is source code for a \CXX~program that writes a
+\LaTeX\ picture as output. \ePiX\ may be viewed as an extension
+to~\CXX; in the same way that \LaTeX\ furnishes a high-level interface
+to~\TeX, \ePiX\ provides a high-level bridge between the computational
+power of~\CXX\ and the \LaTeX\ \code{picture} environment.
+
+\index{Function}
+\index{Conditional statement}
+Like all high-level programming languages, \CXX\ provides variables,
+functions, and control structures. Variables hold pieces of data such
+as numerical values and geometric locations, while functions operate
+on data. A control structure, such as a loop or conditional statement,
+affects the program's course according to the program's current state.
+A source file is composed primarily of ``statements'', which perform
+actions ranging from defining variables and functions to setting
+figure attributes, performing calculations, and writing objects to the
+output file.
+
+\subsection{Names and Types}
+
+\index{Variable!names|(}
+Names of variables and functions may consist (only) of letters,
+digits, and the underscore character. The first character of a name
+must not be a digit, and the language standard reserves names starting
+with underscore for library authors. Names are case-sensitive, but
+it's usually a bad idea to use a single name capitalized and
+uncapitalized in a single file. Numerous capitalization conventions
+are used informally; this document uses uncapitalized words separated
+by underscores for variables and functions, and occasionally uses all
+capitals for constants. As with names of \LaTeX\ macros, primary
+considerations are clarity (of meaning), readability, and consistency.
+\index{Variable!names|)}
+
+\index{Variable!type of}
+Every variable in \CXX\ has a ``type'',
+such as integer (\code{int}), double-precision floating point
+(\code{double}), or Boolean (\code{bool}, true~or false). \ePiX\
+provides additional types, the most common of which is~\code{P}, for
+point. The construct \code{P(x,y,z)} creates~\teximath{(x,y,z)}, while
+\code{P(x,y)} gives~\teximath{(x,y,0)}, which is effectively the
+pair~\teximath{(x,y)}. A variable is defined by giving its type, its
+name, and an initializing expression.
+
+\index{Variable!pointer}
+\index{Pointer}
+In~\code{C} and~\CXX, a \emph{pointer} variable holds the memory
+address of another variable. Pointers are useful for manipulating
+(possibly large) data structures through ``handles'' of fixed small
+size. \CXX\ also provides \emph{references}, which bind an additional
+name to an existing object and allow the object to be manipulated
+through this alias. The statements
+\begin{verbatim}
+ double x=1; // ordinary variable definition
+ double& rx=x; // bind a reference, signified by &
+\end{verbatim}
+define a variable~\code{x} having the value~1, and bind a reference
+variable~\code{rx} to it. As long as~\code{rx} exists, it refers
+to~\code{x}. If the value of~\code{x} changes, the value of~\code{rx}
+does as well. Conversely, the value of~\code{x} can be altered by
+assigning to~\code{rx}. However,~\code{rx} is the size of a pointer,
+regardless of the size of~\code{x}, so~\code{rx} can be passed
+efficiently in a function call.
+\texicomment
+Some applications are discussed on page~\pageref{references}.
+\texicommentend
+
+
+\subsection{Functions}
+
+\index{Function|(}
+In a programming language, the term ``function'' refers to a block of
+code that is executable by name. A \CXX\ function takes a list of
+``arguments'', and has a ``return value''. This information, together
+with the function's name, must be provided when a function is defined.
+A function may not be defined inside another function. However, a
+function may call other functions (including itself) as part of its
+execution:
+\begin{verbatim}
+ int factorial(unsigned int n)
+ {
+ if (n == 0) return 1;
+ else return n*factorial(n-1);
+ }
+\end{verbatim}
+
+\index{Function!returning \code{void}}
+The special type~\code{void} represents a ``null type''. A function
+that performs an action but does not return a value has return type
+\code{void}. A function that takes no arguments may be viewed as
+taking a single \code{void} argument.
+
+Every \CXX\ program has a special function~\code{main()}, which is
+called by the operating system when the program is run. The arguments
+of~\code{main()} are command-line arguments, and the return type is an
+integer that signals success or failure. User-specified functions must
+be defined before the call to \code{main()} or in a
+separately-compiled file.
+
+Functions in~\CXX\ may be as simple as an algebraic formula or as
+complex as an arbitrary algorithm. Greatest common divisors, finite
+sums, numerical derivatives and integrals, solutions of differential
+equations, recursively generated fractal curves, and curves of best
+fit are a few applications in \ePiX. Several sample files contain
+user-level algorithms, which do not require knowledge of \ePiX's
+internal data structures. The source file \filename{functions.cc}
+contains simple functions defined by algorithms, and
+\filename{functions.h} illustrates the use of \CXX\ templates. Other
+source files, such as \filename{plots.cc}, may be consulted for
+Simpson's rule, Euler's method, and the like.
+
+
+\subsection{Mathematical Functions}
+
+\index{Function!mathematical|(}
+\CXX~knows several familiar mathematical functions by name:
+\begin{verbatim}
+ sqrt exp log log10 ceil floor fabs
+\end{verbatim}
+(\code{fabs} is the absolute value for a floating-point argument.)
+\ePiX\ provides trig and inverse trig functions sensitive to angular
+mode:
+\index{Angular mode}
+\findex{Cos}
+\findex{Sin}
+\findex{Tan}
+\findex{Sec}
+\findex{Csc}
+\findex{Cot}
+\findex{Acos}
+\findex{Asin}
+\findex{Atan}
+\begin{verbatim}
+ Cos Sin Tan
+ Sec Csc Cot
+ Acos Asin Atan
+\end{verbatim}
+The inverse functions are principle branches.
+
+The function \code{pow(x,y)} returns~\teximath{x^y} when
+\teximath{x>0}, and \code{atan2(y,x)} (N.B. argument order) returns
+\teximath{\mathrm{Arg}(x+iy)\in(-\pi,\pi]}, the principle branch of
+arg. \CXX~knows many constants to 20~decimal places, such as
+\code{M\_PI}, \code{M\_PI\_2}, and \code{M\_E} for~\teximath{\pi},
+\teximath{\pi/2}, and~\teximath{e} respectively. \ePiX\ defines a few
+additional functions:
+\findex{sgn}
+\findex{zero}
+\findex{sinx}
+\findex{cb}
+\begin{verbatim}
+ sgn zero sinx cb
+\end{verbatim}
+\texicomment
+\begin{center}
+ \input{sgn.eepic}\qquad
+ \input{sinx.eepic}\qquad
+ \input{cb.eepic}
+\end{center}
+\medskip
+\texicommentend
+\code{sgn} is the signum function; \code{zero} is the constant
+function; \code{sinx} is the function \teximath{x\mapsto \sin(x)/x}
+with the discontinuity removed; \code{cb} (for ``Charlie Brown'') is
+the period-2 extension of the absolute value function
+on~\teximath{[-1,1]}.
+
+The GNU \CXX\ library defines other functions, including inverse
+hyperbolic functions (\code{acosh}, etc.), \code{log}~and \code{exp}
+with base~2, 10, or arbitrary~\teximath{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~\cite{GNUC}
+describes these and other functions in detail.
+
+Functions may be used in subsequent definitions, and 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)*Sin(t); }
+\end{verbatim}
+\index{Function!mathematical|)}
+
+
+\subsection{Basics of Classes}
+
+\index{Classes|(}
+Unlike~\code{C}, \CXX\ supports ``object-oriented programming''. In a
+nutshell, a \emph{class} is an abstraction in computer code of some
+concept, such as a point, a sphere, a mapping that can be plotted, or
+a camera. Classes allow a programmer to separate an object's
+\emph{interface} (the set of meaningful operations) from its
+\emph{implementation} (the data structures and algorithms that realize
+the interface).
+
+\index{Function!class member}
+A class implementation consists of \emph{members} (named data
+elements) and \emph{member functions} (functions that belong to the
+class and have free access to members). \CXX\ classes enforce access
+permissions on their members, protecting data from being manipulated
+except as promised by the interface.
+
+An ideal interface looks like a black box: It hides the implementation
+completely. In order to cooperate, two classes need only know each
+other's interfaces. This separation of form and function modularizes a
+program, and facilitates debugging, code reuse, and overall
+maintainability, particularly in large programs.
+
+In simple programming, classes may be treated like built-in types.
+Each class object has its own member functions, whose call syntax
+differs from standard function calls:
+\begin{verbatim}
+ Circle C1(P(1,0), 1.5); // circle of given center and radius
+ C1.draw(); // member function Circle::draw();
+\end{verbatim}
+Naturally, this call draws the circle~\code{C1}. Generally, a member
+function call consists of a class object's name, a period, and the
+name of the member function. Arguments, if any, go in the parentheses
+after the member function name, just as in a regular function call.
+
+A few short paragraphs cannot do more than scratch the surface of
+classes and object-oriented programming. For more details, please
+consult a book, such as Prata~\cite{Prata} or Stroustrup~\cite{S}, or
+Cline's on-line FAQ~\cite{Cline}.
+\index{Classes|)}
+
+
+\subsection{References and Function Arguments}
+
+\index{Function!call syntax}
+\index{Variable!reference}
+\label{references}
+\code{C}~and \CXX\ are ``call by value'' languages. Variables are not
+passed to a function; instead a copy of the value is made, and the
+function operates only on the copy. Though this feature causes
+occasional inconvenience, it prevents an object from being altered
+unexpectedly by a function call in a different part of the program.
+Calling by value helps localize the logic of a program, and
+circumvents easy-to-write but extremely hard-to-find bugs.
+
+In \CXX, a function may accept reference arguments. Passing an object
+by reference grants the calling function access to the object itself,
+not to a copy. There are two common applications: The object is a
+large data structure for which copying is ``expensive'', or the
+function \emph{needs} to modify its arguments (e.g., a function
+\code{swap(x,y)} that exchanges the values of \code{x}~and
+\code{y}).
+
+For the first situation, \CXX\ provides the \code{const} keyword,
+which ensures the function does not modify its arguments, but accepts
+a reference merely for efficiency. Any attempt to modify a
+\code{const} argument will be caught by the compiler. Most \ePiX\
+commands accept \code{const} reference arguments.
+
+The ability to pass function arguments by reference is sometimes
+touted as a feature in \CXX\ texts. However, the technique circumvents
+the data encapsulation of calling by value, and should be avoided
+unless absolutely necessary. If a function merely ``updates'' the
+value of a variable, probably the variable should be of class type,
+and the update should be performed by a member function.
+
+A function declaration must indicate that its arguments are
+references. The declarations below have the indicated idiomatic
+meanings.
+\begin{verbatim}
+ class matrix;
+ double det(matrix); // call by value, perhaps inefficient
+ matrix& transpose(matrix&); // probably changes its argument
+ double trace(const matrix&); // does not change its argument
+\end{verbatim}
+Unlike pointer arguments, reference arguments impose no syntactic
+burden on the user. If~\code{A} is a~\code{matrix}, then
+\code{transpose(A);} and \code{trace(A);} will compile. You need not
+declare explicit reference variables and pass those to the function.
+
+
+\subsection{Overloading}
+
+\index{Function!overloaded}
+\CXX\ provides ``overloading'': Multiple functions can be given the
+same name, so long as the number and/or type of their arguments
+differ. (It is \emph{not} enough for the return types alone to differ.
+The compiler must be able to select a function from its calling
+syntax.) To the user, the appearance is that a single function
+intelligently handles multiple argument lists. Naturally, overloaded
+names should refer to functions that are conceptually related.
+\index{Function|)}
+
+
+\subsection{Scope}
+
+\index{Variable!local}
+A \CXX\ statement ends with a semicolon. A collection of statements
+enclosed by curly braces is a ``code block'', and may be viewed as a
+single logical statement. Curly braces determine a ``scope'', inside
+which variable names may be re-used without ambiguity. Function
+bodies are code blocks, as are the alternatives associated to control
+statements. A variable defined between curly braces is said to be
+\emph{local} to the scope in which it is defined; its value cannot
+be used out of scope. Variables should be declared in the smallest
+scope possible.
+
+The compiler is not picky about spaces, tabs, and newlines, so an
+input file should be formatted to make local scopes visually
+apparent. \code{emacs} automatically indents code to reflect scope,
+though the default behavior does not please all users. As with
+variable naming, clarity and consistency are paramount.
+
+
+\subsection{Headers and Pre-Processing}
+
+A \CXX\ source file is compiled in multiple stages that occur
+transparently to the user. The first step, pre-processing, involves
+simple text replacement for file inclusion, macro expansion and
+conditional compilation. Next, the source is compiled and assembled:
+Human-readable language instructions are parsed, then represented in
+assembly language. Finally, the object files are linked: Function
+calls are resolved to hard-coded file offsets, possibly involving
+external library files, and the program instructions are packaged into
+an executable binary that the operating system can run.
+
+Pre-processing is used much less in~\CXX\ than in~\code{C}; the
+language itself supports safer and more featureful alternatives to
+macros, such as \code{const} variables and inline functions. File
+inclusion and conditional compilation are the chief uses of the
+pre-processor. Lines of the form
+\begin{verbatim}
+ #include <iostream>
+ #include "epix.h"
+\end{verbatim}
+cause the contents of a \emph{header file} to be read into the source
+file. A header file contains variable and function
+\emph{declarations}, statements that specify types and names but do
+not define actual data. Declarations tell the compiler just enough
+to resolve expressions and function calls without knowing specific
+values or function definitions.
+
+\index{Input file!conditional compilation}
+Conditional compilation is similar to conditional \LaTeX\ code. For
+example, a file might produce either color or monochrome output as
+follows:
+\begin{verbatim}
+#ifdef COLOR
+ ... // code for generating color figure
+#endif /* COLOR */
+#ifndef COLOR
+ ... // monochrome code
+#endif /* undef COLOR */
+\end{verbatim}
+The ``compiler symbol'' \code{COLOR} is an ordinary \CXX\ name. To
+control compilation, either put a \code{\#define COLOR} line in the
+file, or (better) supply the flag on the command line: \\
+\verb+ epix -DCOLOR <file.xp>+ \\
+Every \code{\#ifdef} must have a matching \code{\#endif}. Commenting
+the \code{\#endif} is a good habit; in a realistic file, the start and
+end of a conditional block may be separated by more than one screen.
+
+
+\subsection{Comparison with \LaTeX\ Syntax}
+
+As a programming language, \CXX\ provides certain features common to
+all languages (such as \LaTeX, MetaPost, Perl, Lisp\ldots) and adheres
+to rules of grammar. Salient differences between \LaTeX\ and \CXX\
+include:
+
+\begin{enumerate}
+\item Every \CXX\ statement and function call must end with a
+ semicolon. An omitted semicolon may result in a cryptic error
+ message from the compiler. Pre-processor directives, which start
+ with a~\code{\#}, do not end with a semicolon.
+
+\item Backslash is an escape character in \CXX:
+ \index{Labels}
+\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 Variable and function names may contain letters (including
+ underscore) and digits \emph{only}, are case sensitive, and must
+ begin with a letter.
+
+\item Variables in \CXX\ must have a declared \emph{type}, such as
+ \code{int} (integer) or \code{double} (double-precision floating
+ point). If a variable has global scope and its value does not
+ change, the definition should probably come in the preamble or at
+ the beginning of \code{main}. Local variables should be defined in
+ the smallest possible scope. Unlike~\C, \CXX\ allows variables to be
+ defined where they first appear.
+
+\item \CXX~requires explicit use of~\code{*} to denote multiplication;
+ juxtaposition is not enough. \CXX~does not support the use of
+ \verb+^+ for exponentiation, e.g., \verb+t^2+ is invalid. Instead,
+ use \code{t*t}~or \code{pow(t,2)}.
+
+\item \CXX\ has single- and multi-line comments. Everything between a
+ double slash and the next newline is ignored, while the strings
+ \verb+/*+~and \verb+*/+ delimit multi-line comments. A single-line
+ comment may appear within a multi-line comment, but the compiler
+ does not nest multi-line comments.
+ \index{Input file!comment in}
+
+\end{enumerate}
+
+Between them, \C~and \CXX~have about 100~reserved keywords which
+cannot be used as function or variable names.
+\index{Cplusplus@\CXX|)}
+
+
+\section{Attribute Quick Reference}
+\label{section:quickref}
+
+In the body of an input file, the ``drawing state'' determines the
+figure's appearance. Attributes are declarations, set by commands that
+accept arguments of the stated type.
+
+A \code{len} argument is a double-quoted string containing a number
+and a two-letter \LaTeX\ length unit, such as \code{"1.5pt"} or
+\code{"6cm"}. A \code{color} argument is a named primary
+(\code{Red()}, \code{Cyan()}, \code{White()}, etc.), a \code{Color}
+specified by densities (\code{RGB(...)}, \code{CMYK(...)}, etc.), or a
+\code{Color} object. Using \code{Neutral()} as a \code{Color} argument
+generally turns off the corresponding attribute.
+
+\begin{itemize}
+
+\item Angular mode: \code{radians()}, \code{degrees()}, or
+ \code{revolutions()}.
+
+ The angular mode affects all trigonometric operations, including
+ camera rotations, the drawing of arcs and ellipses, polar plotting,
+ label angle, and the trig functions themselves. Angle-sensitive trig
+ functions are capitalized, e.g., \code{Cos}, \code{Tan}.
+
+\item Fill style: \code{fill(color)}, \code{fill(bool)},
+ \code{nofill()}.
+
+\item Path style:
+
+ \begin{itemize}
+
+ \item Width: \code{plain()}, \code{bold()}, \code{bbold()},
+ \code{pen(len)}.
+
+ \item Line style: \code{line\_style(string)}. The argument is a
+ WYSIWYG sequence of dashes, spaces, and periods.
+ \code{dash\_size(double)} and \code{dot\_sep(double)} set the
+ (approximate) length in~\code{pt} of the pattern. The commands
+ \code{solid()}, \code{dashed()}, \code{dotted()} define
+ ``standard'' defaults for brevity.
+
+ \item Path color:
+ Paths can be drawn using \emph{two} pens, one atop the other. When
+ the ``base'' pen is white (or the background color) and wider than
+ the ``line'' pen, a path masks parts of the figure it crosses. A
+ 3-D effect may be obtained by making the base pen a darker shade
+ than the ``line'' pen.
+
+ \code{pen(color,[len])}, \code{base(color,[len])}
+
+ Standard widths: \code{plain(color)}, \code{bold(color)},
+ \code{bbold(color)}
+
+ \end{itemize}
+
+\item Text attributes:
+
+ \begin{itemize}
+
+ \item Color: \code{label\_color(color)}
+
+ \item Mask: \code{label\_mask(color)}, \code{label\_pad(len)}
+
+ \item Border: \code{label\_border(color, [len])},
+ \code{label\_border(len)}. The command \code{no\_label\_border()}
+ turns off label borders.
+
+ \item Font size: \code{font\_size(LaTeX size)}, no argument means
+ \code{normalsize}.
+
+ \item Font face: \code{font\_face(LaTeX font)}, two-letter font
+ selection string, default is \code{rm}.
+
+ \item Rotation: \code{label\_angle(double)}
+
+ \end{itemize}
+
+\end{itemize}
+
+Do not confuse \code{Color} constructors with the similarly-named
+(deprecated) lowercase attribute-setting commands, \code{rgb(r,g,b)},
+\code{cmyk(c,m,y,k)}, \code{red(d)}, etc. These commands affect text,
+paths, and filled regions. For example, the single command
+\code{red()} has the same effect as the three commands
+\code{pen(Red())}, \code{fill(Red())}, and \code{label\_color(Red())}.
+
+
+\texinfochapter{4}{Advanced Topics}
+\label{chapter:adv}
+
+This chapter covers \emph{ad hoc} tricks and open-ended techniques
+that require relatively more programming sophistication. You will
+almost surely need an external \CXX\ reference if you do not speak the
+language.
+
+
+\section{Hidden Object Removal}
+\label{section:hidden}
+
+\index{Hidden object removal|(}
+\ePiX\ writes the output file in the same order that objects appear in
+the input. The order is significant because PostScript builds a figure
+in layers: Objects are drawn over objects that come earlier in the
+file. Shaded polygons can be used to obtain surprisingly effective
+hidden object removal in surface meshes. This section describes the
+data structures defined in the source files \code{surface.*}.
+
+\index{Camera}
+The basic idea is to create a shaded polygon class that knows its
+approximate distance to the camera. For computational simplicity, a
+mesh ``facet'' is treated as a quadrilateral, located at the
+arithmetic mean of its vertices. A facet's boundary is created from a
+map and a domain by tracing a fine mesh rectangle counterclockwise.
+
+To draw a parametrized surface, facets are stored in a \CXX\ vector,
+sorted in decreasing order of distance to the camera, and printed to
+the output file. If filling is active, the gray density of a facet
+depends on the cosine of the angle between the normal vector and the
+vector from the camera to the element.
+
+This simple algorithm works surprisingly well when mesh elements
+intersect at most along complete edges. To incorporate line-like
+elements (e.g., coordinate axes, wire-mesh plots) with shaded
+surfaces, the best technique is often to order high-level scene
+elements manually, breaking up shaded surfaces (for example, with
+domain resizing or clipping) as necessary. The sample file
+\filename{saddle.xp} illustrates possible techniques.
+
+Shaded surfaces can be decorated with a bit of hackery. For example,
+the \code{facet::draw} function in \filename{facet.cc} can be
+modified easily to draw line elements, tangents, or normal vectors
+along with the facet itself. The sample file
+\filename{decorate.xp} contains a couple of ideas. (The
+decorations are activated by compiler flags; please consult the file
+itself for information on compiling.)
+\index{Hidden object removal|)}
+
+
+\section{Extensions}
+\label{section:extensions}
+
+Thanks to a suggestion of Andrew Sterian, \ePiX\ is extensible. User
+extensions span a spectrum, from header files that require only basic
+knowledge of~\CXX\ to separately compiled libraries that add
+substantial new features. The structure of the source code is
+outlined in Section~\ref{section:programmers}.
+
+
+\subsection{Header Files}
+
+A \CXX~header file conventionally has suffix~\filename{.h}, as in
+\filename{myheader.h}. To use this custom header, put a line
+\code{\#include "myheader.h"} in your source file.
+
+User definitions can be easily and robustly implemented with ``inline
+functions''. Inline functions are superficially similar to macros, but
+are far more safe and featureful (since they are handled by the
+compiler rather than by the pre-processor). Examples are
+\begin{verbatim}
+ inline void Bold() { pen(1.6); }
+ inline void purple() { rgb(0.5, 0, 0.7); }
+ inline void draw_square(double s) { rect(P(-s,-s),P(s,s)); }
+ inline double cube(double x) { return pow(x,3); // x^3 }
+\end{verbatim}
+The keyword \code{void} signifies a function that does not return a
+value, or (when used as an implicit parameter) a function that does
+not accept arguments. Inline function definitions are syntactically
+identical to ordinary function definitions, but \emph{must} occur in a
+header file or in the source file where they are used. The examples
+above might be used in an input file as follows:
+\begin{verbatim}
+ Bold();
+ draw_square(cube(1.25));
+\end{verbatim}
+
+
+\subsection{Compiling}
+
+The next few sections outline the creation of a ``static library'' on
+GNU/Linux, and explain how to incorporate custom features at runtime.
+The extensively-commented sample files \filename{std\_F.cc}~and
+\filename{std\_F.h} illustrate the techniques described below, and may
+be used for guidance and experimentation.
+
+A small library is usually written as a \emph{header} file, which
+contains class and function declarations (also called ``prototypes''),
+and a \emph{source} file, which contains the actual
+code. Conventionally (under *nix), these files have extension
+\filename{.h}~and \filename{.cc} respectively. Header and source files
+may ``include'' other header files, to incorporate additional
+functionality.
+\begin{verbatim}
+/* my_code.h */
+#ifndef MY_CODE
+#define MY_CODE
+#include <cmath> // standard library math header
+#include "epix.h" // ePiX header
+using ePiX::P;
+
+namespace Mine { // to avoid name conflicts
+ // functions for special relativity
+ double lorentz_norm(const P&);
+ bool spacelike(const P&);
+} // end of namespace
+#endif /* MY_CODE */
+\end{verbatim}
+This file exhibits two ``safety features''. The three \code{MY\_CODE}
+lines prevent the file from being included multiple times. In a file
+of this size, inclusion protection is overkill, but as your code base
+grows and the number of header files increases, this protection is
+essential. Second, the header introduces a ``Mine'' namespace. Inside
+this namespace, two functions are declared as prototypes, giving the
+function's return type, name, and argument type(s). A header file
+should be commented fairly liberally, so that a year or two from now
+you'll be able to decipher the file's contents. For a longer file,
+version and contact information, an overall comment describing the
+file's features, and license information are appropriate.
+
+Next, the corresponding source file; definitions are also placed into
+the namespace, and must match their prototypes from the header file
+exactly.
+\begin{verbatim}
+/* my_code.cc */
+#include "my_code.h"
+using namespace ePiX;
+
+namespace Mine {
+ double lorentz_norm(const P& arg)
+ {
+ double x(arg.x1()), y(arg.x2()), z(arg.x3()); // extract coords
+ return (y-x)*(y+x) + z*z; // -x^2 + y^2 + z^2
+ }
+ bool spacelike(const P& arg)
+ {
+ return (lorentz_norm(arg) > 0); // true if inequality is
+ }
+} // end of namespace
+\end{verbatim}
+Copies of these files are included with the source code so you can
+experiment with them. Next, the source file must be ``compiled'',
+``archived'', and ``indexed''. In the commands below, the percent sign
+is the prompt.
+\begin{verbatim}
+% g++ -c my_code.cc
+% ar -ru libcustom.a my_code.o
+% ranlib libcustom.a
+\end{verbatim}
+Please see your system documentation for details on command options
+and what each step does. For linking (below), the name of the library
+file must begin ``lib'' and have the extension~\filename{.a}. Once these
+steps are successfully completed, put the library \filename{libcustom.a}
+and header file \filename{my\_code.h} in your project directory. You're
+ready to use the code in an \ePiX\ figure.
+
+
+\subsection{Runtime Linking}
+
+The script~\epix\ allows input files to be linked with external
+libraries at run time, when the input file is compiled into a
+temporary executable.
+
+\epix\ recognizes command line options and passes them verbatim to the
+compiler. The most commonly used options are those of the form
+\begin{verbatim}
+ -I<include> -L<libdir> -l<lib>
+\end{verbatim}
+For example, to link \filename{figure.xp} against
+\filename{mylibs/libcustom.a}, run the command
+\begin{verbatim}
+ epix -Lmylibs -lcustom figure
+\end{verbatim}
+The options \code{-I. -L.} tell the compiler to look in the current
+directory for header and library files. Compiler options may appear
+in any order, but must come before the name of the input file(s).
+
+Compiler options may be placed in the configuration file
+\filename{\$HOME/.epixrc}, with syntax as above. A line in the config
+file that contains a pound sign~(\code{\#}) is a comment, no matter
+where in the line the~\code{\#} appears. If any non-comment line
+fails to start with a dash, the rest of the file is silently
+discarded. Command-line options are read before the config file.
+
+
+\subsection{Using Multiple Versions}
+
+The script \filename{epix}~links by default against the \code{C}~math
+library \code{libm.a}~and the \ePiX\ library \code{libepix.a}. The
+command option \code{--no-defaults} clears the header and include
+paths and removes \code{libepix.a} from the link list. The script may
+therefore be used with multiple versions of \ePiX, a potentially
+useful feature if you regularly need to compile old source files, or
+simply prefer the syntax of an older version.
+
+To install and use (say) Version~1.0.0, build the package according to
+its \filename{INSTALL} instructions, but \emph{do not use the makefile
+ to install}. Instead, manually install the header and library only,
+using their version number:
+\begin{verbatim}
+# install -m 644 epix.h /usr/local/include/epix-1.0.h
+# install -m 644 libepix.a /usr/local/lib/libepix-1.0.a
+\end{verbatim}
+A non-system directory may be used instead of \filename{/usr/local}.
+To use the old version, a source file must \code{include} the
+appropriate header file (which is identified by its version number).
+To compile, issue a command such as
+\begin{verbatim}
+epix --no-defaults -I/usr/local -L/usr/local -lepix-1.0 file.xp
+\end{verbatim}
+
+
+\section{Programmer's Guide}
+\label{section:programmers}
+
+This section briefly surveys \ePiX's implementation, and is intended
+for (potential) programmers. The source code is divided into modules
+with small, well-defined responsibilities, but the user interface is
+mostly compatible with the syntax of Version~1.0. These constraints
+demanded a degree of implementation hiding. For example, the
+user-visible classes defined in \filename{Color.h}, \filename{path.h},
+and~\filename{screen.h} contain only a pointer to the implementation
+class, and style data is hidden behind global commands.
+
+Functionally, the code consists of the user interface; implementation
+class\-es comprising drawing attributes, spatial objects, screens and
+representations of their elements, and output; and miscellaneous
+utility functions. The headers in each group, and their contents, are
+described in Section~\ref{section:interface}.
+
+The user interface headers are assembled into a single file,
+\filename{epix.h}, and installed in \filename{/usr/local/include} by
+default. In normal use, the shell scripts read only the user interface
+header. The individual headers, including the components of
+\filename{epix.h}, are installed in
+\filename{/usr/local/include/epix}. These are provided for authors of
+external libraries, who may need access to implementation details.
+
+
+\subsection{External Packages}
+
+\ePiX\ harnesses the computational power of~\CXX\ to the typographical
+capabilities of \LaTeX. Consequently, \ePiX\ should be viewed in part
+as a framework for expressing numerical data visually.
+
+In the course of your work, you may develop specialized code filling a
+gap in \ePiX's functionality. If your code seems likely to be of
+interest to other users, please consider bundling it as an external
+package and notifying the \ePiX\ community so your work can be linked
+from the project pages and distributed to interested users.
+
+There are no formal requirements for external packages, but in the
+interest of uniformity contributed code should follow the GNU Coding
+Standards~\cite{GNUCoding}. At a minimum, an external package should
+build with the standard \code{./configure; make; make install}
+commands, and the \code{configure} script should accept an option
+\code{--with-epix} for the user to specify a non-default \ePiX\
+install directory.
+
+If an external package builds a static library, it should provide a
+single header containing all the package's entry points, and enclose
+its interface in a namespace. Entry points should not collide with
+\ePiX\ functions. Naming the package ``\filename{epix-<...>}'' is a
+good idea, but not essential. For example, a package providing textual
+nodes and diagram layout might be named \filename{epix-nodes}. Input
+files would use the package with the lines
+\begin{verbatim}
+ #include "epix-nodes.h"
+ using namespace ePiX-nodes;
+\end{verbatim}
+and be compiled with
+\begin{verbatim}
+ epix -lepix-nodes <file>
+\end{verbatim}
+
+The user and internal interfaces of \ePiX-1.2 are not likely to
+change. Still, it's prudent to rely only on the user interface in
+contributed code whenever possible. Doing so also simplifies your work
+as an author; your library can simply \code{include} the user header
+file, and deal only with high-level objects and drawing attributes.
+
+
+\subsection{User Interface}
+\label{section:interface}
+
+These files (in order) comprise the global header \filename{epix.h}.
+
+\Header{enums.h} Marker, alignment, Riemann integral, and vector field
+types.
+
+\Header{length.h} Physical lengths, conceptually a number and
+two-letter \LaTeX\ length unit.
+
+\Header{interval.h} Closed, open, and half-open interval ranges for
+data culling.
+
+\Header{triples.h} The \code{P} class.
+
+\Header{functions.h} Angle-sensitive trig functions, miscellaneous
+utility functions, the \code{Deriv}~and \code{Integral} classes.
+
+\Header{pairs.h} Screen locations and displacements, with complex
+arithmetic operations.
+
+\Header{Color.h} The Color class interface, named
+primaries and constructors.
+
+\Header{state.h} Angle mode; clipping and cropping; label styles;
+filling; arrow head style; dot and tick sizes, dash length; line
+style; line and base pen attributes; color-setting commands.
+
+\Header{frame.h} Orthonormal bases.
+
+\Header{domain.h} Coordinate boxes for function plotting.
+
+\Header{camera.h} The camera.
+
+\Header{screen.h} The screen class.
+
+\Header{picture.h} Dimension-setting, offset, layout, decoration,
+verbatim text, and output format commands.
+
+\Header{markers.h} Point markers, axis labels, and coordinate axes.
+
+\Header{axis.h} Coordinate axes and labels in various styles.
+
+\Header{legend.h} Plot legends.
+
+\Header{path.h} The path class.
+
+\Header{curves.h} Polygons, arrows, ellipses, arcs, splines,
+coordinate grids, and recursive fractal curves.
+
+\Header{circle.h} The \code{Circle} shape object class.
+
+\Header{plane.h} The \code{Plane} shape object class.
+
+\Header{segment.h} The \code{Segment} shape object class.
+
+\Header{sphere.h} The \code{Sphere} shape object class.
+
+\Header{intersections.h} Shape object intersection operators.
+
+\Header{plots.h} Plotting commands.
+
+\Header{surface.h} Shaded surface plots.
+
+\Header{data\_mask.h} Helper class for data pruning.
+
+\Header{data\_file.h} Class for storing and representing data.
+
+\Header{data\_bins.h} Class for sorting and counting data.
+
+\Header{geometry.h} Latitudes and longitudes; spherical plotting,
+arcs, polygons, and polyhedra; hyperbolic arcs.
+
+
+\subsection{Implementation Classes}
+
+\Header{Color\_Base.h} The Color implementation interface.
+
+\Header{Color\_CMY.h} The CMY color model.
+
+\Header{Color\_CMYK.h} The CMYK color model.
+
+\Header{Color\_Gray.h} The Gray color model.
+
+\Header{Color\_Neutral.h} Each color class has a ``Neutral'' member
+that converts colors to that model by filtering. This file defines the
+unique ``model-less'' Neutral color for which filtering performs no
+action.
+
+\Header{Color\_RGB.h} The RGB color model.
+
+\Header{Color\_Sep.h} Classes for CMYK separation.
+
+\Header{active\_screen.h} Simple manipulator for the active screen.
+
+\Header{picture\_data.h} Picture implementation: two \code{screen}s
+(representing the \code{canvas}~and the output page), true dimensions
+and offsets, pointer to output format, list of colors, and lists of
+verbatim text to write before and after printing the \code{picture}
+environment in the output file. For simplicity, the \code{screen}s and
+dimensions are public; encapsulation from the user results from
+``hiding'' this header.
+
+
+\subsubsection*{Style Attributes}
+
+Declaration-style attributes are maintained with functions returning
+static references: \code{the\_angle\_style()},
+\code{the\_arrowhead\_style()}, \code{the\_label\_style()},
+\code{the\_mark\_size()}, \code{the\_paint\_style()}, and
+\code{the\_path\_style()}. Each function is declared in the
+analogously-named header.
+
+\Header{angle\_units.h} Angular modes: \code{radians},
+\code{revolutions}, and \code{degrees}.
+
+\Header{arrow\_style.h} Arrow head style data: width, ratio, and
+inset.
+
+\Header{label\_style.h} Text object style: Label and mask colors,
+padding, border color and width, alignment, font size, font face, and
+angle.
+
+\Header{marker\_style.h} Dot and tick sizes.
+
+\Header{paint\_style.h} Line and base pens, fill color.
+
+\Header{path\_style.h} Solid, dashed, dotted lines.
+
+\Header{pen\_data.h} The pen class.
+
+
+\subsubsection*{Objects}
+
+\Header{arrow\_data.h} Arrow representation.
+
+\Header{facet.h} Shaded surface elements.
+
+\Header{label\_data.h} Text (label and marker) objects.
+
+\Header{legend\_item.h} Items for \code{legend}s.
+
+\Header{path\_data.h} Path implementation.
+
+\Header{spline.h} The natural spline class.
+
+\Header{spline\_data.h} Templates for quadratic and cubic splines.
+
+
+\subsubsection*{Screen Representation}
+
+Elements in a \code{screen} are represented polymorphically as
+``\code{tile}s'', of which there are six types: \code{glyph} (textual
+elements), \code{pen\_arrow} (arrows), \code{pen\_fill} (filled
+regions), \code{pen\_line} (path-like elements), \code{verbatim}
+(raw text), and \code{legend\_tile} (legends).
+
+Border and background shape are dictated by the \code{screen\_mask}
+class. The cropping algorithm assumes the contour of a screen mask is
+convex.
+
+\Header{affine.h} Affine maps.
+
+\Header{cropping.h} Screen mask cropping.
+
+\Header{glyph.h} Markers and labels.
+
+\Header{legend\_tile.h} Screen representation of a \code{legend}.
+
+\Header{mask\_diamond.h} Screen diamond mask.
+
+\Header{mask\_ellipse.h} Screen elliptical mask.
+
+\Header{mask\_rectangle.h} Screen rectangular mask.
+
+\Header{pen\_arrow.h} Arrows.
+
+\Header{pen\_fill.h} Filled regions.
+
+\Header{pen\_line.h} Paths.
+
+\Header{screen\_data.h} Screen implementation class.
+
+\Header{screen\_mask.h} Screen mask interface.
+
+\Header{tile.h} Screen element interface.
+
+\Header{verbatim.h} Text in output stream.
+
+
+\subsubsection*{Output}
+
+Output is divided into a couple of high-level operations and several
+``atomic'' low-level operations. To create a new output
+format, one need only implement the \code{format} interface for the
+desired file type. Paths and filled regions may be implemented however
+the output type dictates.
+
+\Header{eepic.h} eepic macros.
+
+\Header{fmt\_template.h} ``skeleton'' header for new output formats.
+
+\Header{format.h} The output interface.
+
+\Header{pst.h} PSTricks macros.
+
+\Header{tikz.h} tikz macros.
+
+
+\subsubsection*{Utilities}
+
+\Header{Color\_Utils.h} Functions for setting color channel densities.
+
+\Header{clipping.h} The clip box.
+
+\Header{constants.h} Global constants: Line widths; dot, tick, and
+dash sizes; arrowhead parameters; miscellaneous numerical constants
+and internal parameters.
+
+\Header{crop\_algorithms.h} Path and loop clipping templates.
+
+\Header{deriv.h} Finite difference template.
+
+\Header{edge\_data.h} Path element representation template.
+
+\Header{errors.h} Warning and error messages.
+
+\Header{frac.h} Rational numbers and operators.
+
+\Header{halfspace.h} Halfspace cutting.
+
+\Header{hatching.h} Filling regions in eepic.
+
+\Header{lens.h} Camera lenses.
+
+\Header{map.h} Wrappers for templated plotting.
+
+\Header{plot\_algorithms.h} Plotting templates.
+
+\Header{screen\_crop.h} Crop paths and loops.
+
+\Header{utils.h} Truncation, date and time, line breaking.
+
+
+\appendix
+\texinfoappendix{A}{Software Freedom}
+\index{Free software|(}
+
+Academics in general, and mathematicians in particular, depend on free
+exchange of information. We prove theorems or establish experimental
+results, write up formal accounts, place preprints on public file
+servers, and submit papers to peer-reviewed journals. If accepted, the
+results---data, techniques, methods of reasoning, citations, and
+conclusions---are published in print and become part of the public
+record, governed by copyright law. Libraries purchase journal
+subscriptions, but researchers and scholars may use ideas from the
+literature merely by giving appropriate citations in their own
+work. ``Theft'' arises from false claims of authorship.
+
+Carried over to software, the academic process would guarantee rights
+similar to those provided by the GNU General Public License (GPL):
+
+\begin{itemize}
+
+\item (GPL~0) To run a program for any purpose.
+
+\item (GPL~1) To study how the program works, and adapt it to your
+ needs.
+
+\item (GPL~2) To redistribute copies of the program.
+
+\item (GPL~3) To improve the program, and release improvements to the
+ public, so that the whole community benefits.
+
+\end{itemize}
+
+In reality, attitudes toward software differ markedly. Most academics
+work on a proprietary platform, use proprietary software for research
+and teaching, and share information with colleagues and students in
+proprietary, even obfuscated, data formats. Contrary to the academic
+ethic, proprietary software licenses restrict access to information:
+preventing users from learning how a program works internally
+(``reverse engineering''), limiting the number of users who may run a
+piece of software, and forbidding users from running (or sometimes
+even installing) a purchased copy on multiple machines.
+
+Restrictions on use aside, if one cannot examine a program's source
+code, one cannot fully trust the output, any more than one can trust
+(for purposes of scientific publication) results of a commercial
+testing lab.
+
+\texicomment
+\noindent$\phantom{.}$\hfil\vbox{\hrule width 4in}\hfil
+\texicommentend
+
+Consider a hypothetical future world in which scholarly results are
+disseminated like software. Instead of subscriptions, journals
+sell licenses granting readership to a specified number of
+individuals. Photocopying an article for a class or research seminar
+constitutes ``piracy'', though if the institution has purchased a
+sufficiently large site license the teacher or speaker may bring the
+physical volume to class and project the pages onto a screen.
+
+Of course, reading an article is scarcely enlightening. Mathematics
+papers contain only the statements of theorems. Merely opening the
+journal binds the reader to a lengthy legal agreement, stating that
+theorems be used only for specific purposes and threatening serious
+legal consequences for attempting to discover the author's proofs.
+
+The actions of a single student, employee, or faculty member can
+expose an institution to a costly ``journal audit'' from the
+Mathematical Society of America (MSA), with the institution
+responsible for legal costs if the audit reveals license violations
+anywhere in the organization.
+
+Mathematicians who long for the Old Days when papers contained
+proofs and were shared freely are dismissed as idealistic cranks
+or labeled anti-business communists. Common knowledge asserts the
+obvious superiority of proprietary journals, and the necessity of
+licenses for keeping mathematicians gainfully employed.
+
+\texicomment
+\noindent$\phantom{.}$\hfil\vbox{\hrule width 4in}\hfil
+\texicommentend
+
+Back in our world, some vendors have attempted to placate opponents of
+closed source with ``shared source'' licenses, under which one may
+sign a non-disclosure agreement and subsequently examine source
+code. In the future world analogy, a shared source agreement would
+allow journal licensees to sign an NDA, then see the proofs of
+theorems. Readers could thereby correct errors in proofs (benefitting
+the publisher by improving the reliability of the journal), but would
+be legally forbidden from using the ideas elsewhere (denying benefit
+to other mathematicians).
+
+Legally and conceptually codifying software as a commodity ignores a
+fundamental reality: Like an idea or recipe, software can be copied
+without loss of the original. The perception of ``theft'' by copying
+arises from an artificial belief that software has an owner who must
+be monetarily compensated each time a person acquires a copy. The
+nature of software does not enforce the ``sale'' model in the way
+services and physical commodities do. It therefore seems
+philosophically inappropriate to treat software as a commodity, and
+perilous to conform the legal system to the enforcement of such a
+model.
+
+At its best, software enhances our productivity and
+creativity. Sharing software, like sharing ideas, benefits a larger
+number of people without detriment to existing users. I hope 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
+\URL{www.fsf.org}, to learn more about free software and how
+you can contribute to its development and adoption.
+\index{Free software|)}
+
+\texinfoappendix{B}{Acknowledgments}
+
+\ePiX\ is built on the work of many people (unfortunately, most of
+whom I am unaware). The following people have contributed, sometimes
+unknowingly but always generously:
+
+\paragraph{Infrastructure} Donald Knuth, Conrad Kwok, Leslie Lamport,
+Tim Morgan, Piet van~Oostrum, Sunil Podar, Richard Stallman, Till
+Tantau, Herbert Voss, Timothy van~Zandt
+
+\paragraph{Enhancements} Jay Belanger, Robin Blume-Kohout, Julian
+Gilbey, Marcus Hanwell, Yvon Henel, Svend Daug{\aa}rd Pedersen, Andrew
+Sterian
+
+\paragraph{Porting and packaging} Julian Gilbey (Debian); Tsuguru Kato
+(FreeBSD); Markus Dittrich, Danny van Dyk, Christian Faulhammer,
+Olivier Fisette, Chris Gianelloni, Michael Hanselmann, Marcus Hanwell,
+David Holm, Peter Johanson, Patrick Kursawe, Tobias Scherbaum, Markus
+Ullmann (Gentoo); Guido Gonzato (RPM); Rene Rebe (T2)
+
+\paragraph{Debugging, advice, and other assistance} Jay Belanger,
+Felipe Paulo Guazzi Bergo, Karl Berry, Robin Blume-Kohout, Patrick
+Cousot, Stephen Gibson, Julian Gilbey, Dov Grobgeld, Bob Grover, Jim
+Hefferon, Jacques L'helgoual, Yvon Henel, Hartmut Henkel, Herng-Jeng
+Jou, Walter Kehowski, Kevin McCormick, Ross Moore, Thorsten Riess,
+Alan Sill, Neel Smith, Michael Somos, Andrew Sterian, Ryszard Tanas,
+Kai Trukenmueller, Torbjorn Vik, Wenguang Wang, Gabe Weaver, Mariusz
+Wodzicki
+
+\texicomment
+\begin{thebibliography}{9}
+%
+\bibitem{Cline} Marshall Cline, \emph{\CXX\ FAQ Lite}, \\
+ \URL{http://www.parashift.com/c++-faq-lite/}
+%
+\bibitem{xcolor} Uwe Kern, \emph{Extending \LaTeX's color facilities:
+ the \code{xcolor} package}, white paper, Jan.~21, 2007
+%
+\bibitem{KnR} Brian Kernighan and Dennis Ritchie, \emph{The \code{C}
+ Programming Language}, Second Ed., Prentice-Hall Software Series,
+ 1988
+%
+\bibitem{GNUC} Sandra Loosemore, Richard M. Stallman, et.\ al.,
+ \emph{The GNU \code{C}~Library Reference Manual}, GNU Press,
+ 2004
+%
+\bibitem{Prata} Stephen Prata, \emph{\CXX\ Primer Plus}, Sams, 2002
+%
+\bibitem{R} Keith Reckdahl, \emph{Using Imported Graphics in
+ \LaTeX2e}, Version~2.0, white paper, Dec.~15, 1997
+%
+\bibitem{GNUCoding} Richard M. Stallman, et.\ al., \emph{The GNU
+ Coding Standards}, \\
+ \URL{http://www.gnu.org/prep/standards/}
+%
+\bibitem{S} Bjarne Stroustrup, \emph{The \CXX\ Programming Language},
+ Special Ed., Addison-Wesley, 1997
+%
+\bibitem{Z} Timothy van~Zandt, \emph{PSTricks: PostScript Macros for
+ Generic \TeX}, Version~0.93a, white paper, Mar.~12, 1993
+%
+\end{thebibliography}
+
+\clearpage
+
+\printindex
+
+\end{document}
+
+\texicommentend