%%% File: grafdoc.tex
%%% A part of mfpic 0.6 2002/09/12
%%%
%  Documentation of grafbase code
\input header

% For "12pt":
%\magnification=\magstep1

% Paper size: {width}{height}
\setpapersize{8.5truein}{11 truein}

% Text size: {width}{height}
\setpagegeometry{5.4167 in}{7.4166 in}

\def\_{{\tt\char`\_}} % For \tt only
% metacode macro
\let\texmacro=\mac

\centerline{\bf MFPIC's METAFONT AND METAPOST MACROS%
\footnote{}{\prog {mfpic} Version:  \mfpicversion.}%
}
\centerline{\file{grafbase.mf} and \file{grafbase.mp}}
\centerline{Version:  \mfpicversion, Date:  \mfpicdate}
\centerline{Document Author:  Geoffrey Tobin (\mail{G.Tobin@latrobe.edu.au})}
\centerline{Updates by:  Daniel H. Luecking (\mail{luecking@uark.edu})}


\head{Background}

\MF{} or \MP{} should be moderately familiar to anyone who is serious
about understanding \file{grafbase.mf} or \file{grafbase.mp}.

The best reference for \MF{} programming is undoubtedly Professor Donald
E.~Knuth's \MFbook{}, first published by Addison-Wesley and copyrighted
by the American Mathematical Society in 1986, ISBN 0-201-13445-4.

However, the file \file{mf-revu.tex} contains reminders of some facets
of \MF{}.

For \MP{} specific information (as well as some basic \MF{} information),
the \MP{} documentation by John Hobby is invaluable. It is contained in
the file \file{mpman.ps}, available with most distributions of \MP.

\head{Assumed Variables}

\bcd
{\it w\_, h\_;\\
xneg, xpos, yneg, ypos;\\
unitlen, xscale, yscale.}
\ecd

The file \file{grafbase.mf} assumes that the \MF{} variables \gbc{w\_},
\gbc{h\_}, \gbc{xneg}, \gbc{xpos}, \gbc{yneg}, \gbc{ypos},
\gbc{unitlen}, \gbc{xscale} and \gbc{yscale} are all numeric and
known. The values of \mfc{w\_} and \mfc{h\_} are set by the
\prog{grafbase} macro \mfc{beginmfpic}. By contrast, the four graph
extents variables, \gbc{xneg}, \gbc{xpos}, \gbc{yneg} and \gbc{ypos},
and the three scaling variables \gbc{unitlen}, \gbc{xscale} and
\gbc{yscale}, must be set externally. \mfc{beginmfpic} also sets the
numeric variables \mfc{w} and \mfc{h} to \gbc{w\_} and \gbc{h\_},
respectively. The user may use \mfc{w} and \mfc{h} (indeed, is
encouraged to) but internally \prog{grafbase} uses the underscored
variants to guard against a user accidentally redefining the simpler
ones (as one of the authors once did from \prog{mfpic} using
\mac{mfobj}[h]).

The four variables \gbc{xneg}, \gbc{xpos}, \gbc{yneg} and \gbc{ypos}
determine the nominal drawing boundary. The nominal drawing boundary is
the region that \TeX{} will perceive as the (rectangular) boundary of
the character, according to the \file{TFM} file for the font that \MF{}
will produce (or the bounding box in the EPS files that \MP{} will
produce). \gbc{xneg, xpos, yneg, ypos} are the coordinates in
\emph{graph} units of the left, right, bottom, and top edges of that
boundary. Normally, the origin of the drawing \emph{differs} from the
reference point of the \file{TFM} file or the bounding box of the EPS
file.

The three variables \gbc{unitlen}, \gbc{xscale} and \gbc{yscale} are
used (by \gbc{beginmfpic}) to translate from graph coordinates (pairs
with xpart between \gbc{xneg} and \gbc{xpos}, and ypart between
\gbc{yneg} and \gbc{ypos}) into device coordinates. Changing some or all
of the three will change the size and/or aspect ratio of the final
output. \gbc{unitlen} is provided in order to set the most convenient
physical unit, since that may possibly not be one of the units provided
by plain \MF{} (\mfc{bp\#, cc\#, cm\#, dd\#, in\#, mm\#, pc\#, pt\#}).
Note that \gbc{unitlen} must, like all \emph{mode-independent} units, be
expressed in \emph{sharped} units.

The initial values of these seven dimensioning variables are:
\gbc{unitlen := 1pt\#}, one \TeX{} point in absolute (\emph{sharped})
units; \gbc{xscale := yscale := 7.227}, so as to make the X and Y scale
drawing units $ 1/10 $ inch each; while \gbc{xneg, xpos, yneg, ypos} are
initialised to $ 0, 10, 0, 10 $, so that both axes extend from $ 0 $ to
$ 10 $ \emph{graph} units.

However, the initial dimensions are not intended to be retained, and
should be altered according to the needs of the drawing.  When
generating the \MF{} or \MP{} file by using \TeX{} or \LaTeX{} with the
\file{mfpic.tex} macros, this is what the arguments of the \mac{mfpic}
environment in \file{mfpic.tex} are for. To set \gbc{unitlen}, one uses
the \mac{mfpicunit} macro of \file{mfpic.tex}.


\head{Preliminaries}

\bcd
{\it METAPOST, METAFONT.}
\ecd

\prog{grafbase} uses the boolean variables \gbc{METAPOST} and
\gbc{METAFONT} to record whether it thinks it's being used with \MP{} or
\MF{}.  Since \MF{} has no colors, it seems reasonable that the presence
of \mfc{blue} is a reliable sign of \MP{}, so \prog{grafbase} tests
whether \mfc{blue} is known.

At present, no \prog{grafbase} code involves these booleans, relying on
the different files to contain program specific code: if \mfc{input
grafbase} occurs in a file, then \MF{} will input \file{grafbase.mf} and
\MP{} will take \file{grafbase.mp}. However, if \MP{} cannot find
\file{grafbase.mp} and tries to input the other, the results will be
disastrous. Perhaps in the future the two files can be merged, with
differences controlled by these booleans.

The files \file{grafbase.mf/p} need the \file{plain.mf/p} macros.
Usually, these will be available automatically, but if by any ill chance
they are not, then \prog{grafbase} will attempt to load the appropriate
file.

In \file{grafbase.mf}, before calling \mfc{mode\_setup}, it seems
reasonable, given the purpose of \prog{mfpic} and \file{grafbase.mf}, to
require an explicit mode when calling \MF{}, instead of the frequently
vexing, silent, default of using \mfc{proof} mode, which \file{plain}
\MF{} falls back on when no mode is specified.  So in that case,
\file{grafbase.mf} preempts the default with an error message.

The \mfc{font\_identifier} is set to \gbc{"MFpic graphics"}, to make
the origin of the PK file obvious. We set \mfc{font\_coding\_scheme} to
\gbc{"Arbitrary"} since there can be no generally useful coding scheme
for graphics.

It would be agreeable if \mfc{designsize} could be the same as that used
for the \TeX{} text labels in \prog{mfpic}, say \mfc{10pt\#} or
thereabouts.  Unfortunately, the limited wisdom of \MF{} limits
dimensions to a small multiple of \mfc{designsize}, so
\file{grafbase.mf} has to set \mfc{designsize} to be much larger. The
value chosen (\mfc{128pt\#}) is a power-of-two number of TeX points, and
is large enough to avoid this limitation.

Such font related items are not available (or needed) in \MP, so
\file{grafbase.mp} ignores modes, font identifiers and coding schemes.


\head{Common Global Variables}

\bcd
{\it fileversion, filedate;\\
debug, grafbase;\\
mftitle (macro);\\
deg, radian, pi;\\
penwd, drawpen, hatchwd, hatchpen, shadewd, polkadotwd;\\
store (macro);\\
ClipOn, ClipPath, clipall, truebbox (\MP);\\
Triangle, Square, Diamond, Circle, Star, Plus, Cross, Asterisk\\
SolidTriangle, SolidSquare, SolidDiamond, SolidCircle, SolidStar.}
\ecd

The strings \gbc{fileversion} and \gbc{filedate} are set equal to the
current version and revision date of \prog{mfpic}. For example, at this
writing \gbc{fileversion="\mfpicversion"} and \gbc{filedate="\mfpicdate"}.

The boolean variable \gbc{debug} is present mainly for
experimentation with \prog{grafbase}, so that any diagnostics can be
turned on or off a little more conveniently.

If the boolean variable \gbc{grafbase} is known, then
\prog{grafbase} has been loaded more than once, which is an error.

The \gbc{mftitle} macro is frequently used by \prog{mfpic}, but not in
\prog{grafbase} itself.  Its purpose is to create a title (see \MFbook{}
chapter 22: Strings, page 187, paragraph 3), and to display that title
as a message.

So that users can refer to angular quantities in a self-evident way, the
numeric variable \gbc{deg} is set to \mfc{1}.  Thus, instead of
\mfc{45}, one may write \mfc{45 deg} or \mfc{45deg}, to make the meaning
obvious. Of course \gbc{pi} is set to \gbc{3.1415926} and \gbc{radian}
is set with \gbc{pi*radian = 180 deg;}.

When drawing, the \mfc{pen} variable \gbc{drawpen} is used, which is a
circular \mfc{pen}.  Its diameter, in \emph{device} coordinates, is
determined by the \mfc{internal} variable \gbc{penwd}, which
\prog{grafbase} initialises to \mfc{0.5pt}. (See the Coordinate
Conversion section below for a description of `device coordinates'.)

For hatching, the \mfc{pen} variable \gbc{hatchpen} is used, which is a
circular \mfc{pen}.  Its diameter, in \emph{device} coordinates, is
determined by the \mfc{internal} variable \gbc{hatchwd}, which
\prog{grafbase} initialises to \dim{0.5pt}.

\gbc{shadewd} is the diameter of dots used to shade the interior of
regions (initially \dim{0.5pt}) and \gbc{polkadotwd} is the diameter of
polkadots that the macro \gbc{polkadot} uses to fill regions (initially
\dim{5pt}).

The \gbc{store($f_s$)}~$f$ \ macro is for the purpose of storing a
path expression $f$, which may be quite complex, into a path
variable $f_s$. This is remarkably useful to \prog{mfpic}.

Clipping of the current \gbc{active\_plane} is enabled when the boolean
variable \gbc{ClipOn} is true. It is disabled when \gbc{ClipOn} is
false.


The current clipping region is specified by the path array
\gbc{ClipPath}.  The numeric value of \gbc{ClipPath} equals the number
of paths in the array, which are numbered from one upwards:
\gbc{ClipPath[1]$\ldots$ClipPath[ClipPath]} (\emph{sic}).

The boolean \gbc{clipall} is similar, except it is only checked by
\gbc{endmfpic}. If it is \mfc{true}, the picture created since the
previous \gbc{beginmfpic} is clipped to the nominal boundaries
determined by \gbc{xneg}, \gbc{xpos}, etc., before being shipped out.
In \MP, \gbc{endmfpic} also checks the boolean \gbc{truebbox} to
determine whether it should use the actual bounds of the picture or
artificially set them to the nominal boundaries.

\gbc{Triangle}, $\ldots$, \gbc{SolidCircle} are paths in the obvious
shapes. They have approximately the diameter 1 in device coordinates so
they would normally be drawn \mfc{scaled} to appropriate dimensions.
Despite the names, only the last four (\gbc{Solid...}) are closed paths.
(For example, \gbc{SolidTriangle} is just \gbc{Triangle \& cycle}.) They
are used by \gbc{doplot} and \gbc{plotsymbol} (in which the open ones are
simply drawn while the solid ones are filled), but are available for
other uses.

\subhead{\MP{} Color Variables}

(Colors are only valid in the \MP{} version of \prog{grafbase}.)

\bcd
{\it drawcolor, fillcolor, hatchcolor, headcolor, tlabelcolor;\\
cyan, magenta, yellow;\\
\file{dvipsnam.mp} (file).}
\ecd

In \MP, \mfc{red}, \mfc{green}, \mfc{blue}, \mfc{white} and \mfc{black}
are predefined colors which are normally never changed. Plain \MP{}
defines a color \gbc{background}, whch is normally white.
\file{grafbase.mp} adds definitions for the constant colors \gbc{cyan},
\gbc{magenta} and \gbc{yellow}.

In addition to these \file{grafbase.mp} defines the color variables
\gbc{drawcolor}, \gbc{fillcolor}, \gbc{hatchcolor}, \gbc{headcolor} and
\gbc{tlabelcolor}. \gbc{drawcolor} is used by \gbc{shpath} and
\gbc{safedraw}, the basic curve drawing routines called by almost every
function that draws a curve. Similarly, \gbc{fillcolor} is used for
filling, \gbc{hatchcolor} for hatching, \gbc{headcolor} for drawing
arrowheads, and \gbc{tlabelcolor} for text labels (used by the macro
\gbc{gblabel}). These were chosen because these are the basic drawing
operations of \prog{mfpic} macros: drawing curves, filling interiors of
curves, hatching interiors, adding arrowheads to curves, and placing
text labels. All five are initialized to \mfc{black}.

Finally, the auxilliary file \file{dvipsnam.mp} contains definitions of
all the color names defined in \LaTeX's \file{dvipsnam.def}. It is
normally input by files created by \prog{mfpic} when the \opt{metapost}
option is selected, so all these colors are available to \prog{mfpic}
users.

\head{Utility Macros}

\bcd
{\it map, maparr;\\
textpairs;\\
floorpair, ceilingpair, hroundpair;\\
minpair, maxpair.}
\ecd

As noted in the source, \mfc{text} arguments, which are used in many of
the macros in \prog{grafbase}, are perilous in a high degree, because
they can easily cause naming conflicts with local variables in macros
that use them.  This typically produces obscure error messages.

However, \mfc{text} arguments are very useful, and \MF{} has no useful
alternative, as it lacks a sense of lists as a fully fledged data
structure.  Few language designers seem to learn from this excellent
core feature of Lisp, so we can only muse on what might have been.

\gbc{map($m$)($t$)} generates a new list from a text list $t$ of one or
more items, by applying the macro $m$ to each item in turn. Lists are
generally used in \mfc{for} preambles, so for each item $i$ in $t$,
$m(i)$ should normally be a single object. If $m(i)$ expands to some
arbitrary \MF{} code, some symbols can cause problems (e.g., `\mfc{:}'
can terminate a \mfc{for} preamble prematurely).

\gbc{maparr(proc)($p$)} applies \gbc{proc}, which should be a
\emph{procedure} (a sequence of statements that does not return any
value) with one argument, to each member of the array $p[]$.  The items
in the array may be of any types that \gbc{proc} can process.

\gbc{textpairs($p$)($t$)} converts a text list $t$ of pairs into
an array~$p$ of~pairs.

\gbc{chpair(proc)($p$)} applies \mfc{proc} to each \emph{part} of
the pair $p$, then it returns the pair consisting of each of
these two results:  \mfc{(proc(xpart $p$), proc(ypart $p$))}. Here
\mfc{proc} must be a macro with one numeric argument and which
returns one numeric value.  We describe such a macro by this
mathematical notation: \mfc{proc}${}:{}$numeric${} \mapsto {}$numeric.

\gbc{floorpair($p$)} returns a pair comprising the floors
(rounded-down integer parts) of the X and Y \emph{parts} of the
pair~$p$.

\gbc{ceilingpair($p$)} returns a pair comprising the ceilings
(rounded-up integer parts) of the X and Y \emph{parts} of the
pair~$p$.

\gbc{hroundpair($p$)} returns a pair comprising the hrounds of
(ie, the nearest integers to) the X and Y \emph{parts} of the
pair~$p$.

\gbc{minpair($t$)} returns a pair comprising the minimum X and Y
\emph{parts} of all the pairs in the text list~$t$.

\gbc{maxpair($t$)} returns a pair comprising the maximum X and Y
\emph{parts} of all the pairs in the text list~$t$.


\head{Coordinate Conversion}

\bcd
{\it ztr, vtr, setztr;\\
zconv, invzconv
vconv, invvconv.}
\ecd

\file{grafbase.mf} employs three main (classes of) coordinate systems.
The first describes \emph{graph} coordinates; this is the user's
coordinate system, in which graphs, function plots, the orientation of
axis tic marks, and many other features are described.  The graph
coordinate system can be shifted, rotated, magnified, slanted, and
flipped.  Graph coordinates are device \emph{independent}.

The second is determined by the \emph{sharp} units of \MFbook{}; these
represent an upright Cartesian system in which one millimetre means one
millimetre --- in any direction.  Sharp coordinates are device
\emph{independent}.  Device independent lengths are specified in sharp
units: for example, \gbc{unitlen}.

The third describes the \emph{device}  coordinates. In \MF{} these are
\emph{pixel} coordinates, refering to units of the pixel grid in the
bitmaps formed by picture variables and written into the GF font
file that \MF{} writes; pixels are upright, but they may not be square,
as \MF{}'s modes cater for output devices (for example, various screens
and printers) with differing aspect ratios --- among other properties
that affect how an image is rendered.  Naturally, pixel coordinates are
device \emph{dependent}. The grafbase macros refer to pixel coordinates
through plain \MF{}'s \mfc{.t\_} construct, through the \mfc{w\_} and
\mfc{h\_} quantities calculated by \mfc{beginmfpic}, and in its
manipulations of \MF{} picture variables.

As an example of the various coordinate systems: Under the assignments

\bex
\gbc{unitlen:=1in\#; xscale:=5; yscale:=3; xneg=yneg:=0;}
\eex

the point with graph coordinates \mfc{(1,1)} will have sharp coordinates
\mfc{(5in\#,3in\#)}. If the device mode in use has 360 pixels per inch
horizontally and 240 vertically, then the device coordinates of the same
point will be \mfc{(1800,720)}.

Below, we will use the term `device coordinates' somewhat loosely,
meaning units such as \mfc{pt} and \mfc{cm} (not \mfc{pt\#} or
\mfc{cm\#}). These have already been set equal to some number of
\emph{horizontal} pixels by \mfc{mode\_setup}. The user \emph{could}
calculate a number of pixels and use that also. However, the user should
\emph{not} adjust for nonsquare pixels using \mfc{aspect\_ratio}. That
would compound the adjustment already made by the \prog{grafbase}
drawing commands.

The user can normally ignore the sharp coordinates, except for
\gbc{unitlen}. As for graph or device coordinates: when a
\prog{grafbase} function requires parameters in \emph{graph} coordinates
simply use pure numerics, and when \emph{device} coordinates are
required, use pure numeric multiples of \mfc{pt} or \mfc{cm} or (inside
a \gbc{beginmfpic} group) of \gbc{w} or \gbc{h}, which have already been
established as a certain number of pixels. Or use \gbc{zconv} and
\gbc{vconv} to convert from graph to device coordinates.

In \MP, device coordinates are the same as sharp coordinates. \PS{}
devices should perform the conversion from absolute lengths to pixels
internally.

In \MF{} and \MP, the transform data type represents \emph{affine
transforms}, which are the familiar Euclidean transforms formed by
translation (shifting), rotation (turning), mirror reflection
(flipping), scaling (magnifying), and skewing (slanting). In the absence
of translation, the operations performed are called \emph{linear
transforms}.

There is a significant difference between affine transformations, which
are used to transform coordinates, and vector (displacement)
transformations, because in general the former depend on the absolute
position, whereas the latter act independently of it. Therefore we need
a separate set of transforms for when pairs are interpreted
as vectors.

\gbc{vtr} is a transform variable describing the conversion from
\emph{graph} vectors to \emph{device} vectors. It is a \emph{linear}
transformation (no shift components).

\gbc{ztr} is a transform variable describing the conversion from
\emph{graph} vectors to \emph{device} vectors. It shifts \gbc{(xneg,
yneg)} to the origin, then applies \gbc{vtr}.

\gbc{setztr} sets \gbc{vtr} and \gbc{ztr}.

\gbc{zconv($a$)} returns the \emph{device} coordinate pair
corresponding to the \emph{graph} coordinate pair~$a$.

\gbc{invzconv($v$)} is the inverse of \gbc{zconv}.

\gbc{vconv($a$)} returns the \emph{device} vector corresponding to
the \emph{graph} vector~$a$.

\gbc{invvconv($v$)} is the inverse of \gbc{vconv}.


\head{Initial Setup}

\bcd
{\it active\_plane; initpic.}
\ecd

\gbc{active\_plane} is the active drawing plane, initially defined as
the plain \MF{} picture variable \mfc{currentpicture} which is
\emph{not known} until the call to \mfc{clearit} in \mfc{beginchar}.

\gbc{initpic} calls \gbc{setztr}, initialises \gbc{active\_plane},
and picks up a circular \mfc{pen} of diameter \gbc{penwd}.


\head{Compatibility with Older \file{graphbase.mf}}

\bcd
{\it mfpicenv, endmfpicenv, bounds.}
\ecd

For compatibility with files produced for older versions of the graph
base, usually named \file{graphbase.mf}, three definitions are
provided.

\gbc{mfpicenv} and \gbc{endmfpicenv} are defined as empty definitions.

\gbc{bounds(a, b, c, d)} assigns \gbc{xneg, xpos, yneg, ypos} to \gbc{a,
b, c, d} respectively.

The behavior of \file{grafbase.mp} with such old file has never been
examined, so no compatibility is actually claimed.

\head{Character Wrapper}

\bcd
{\it beginmfpic, endmfpic.}
\ecd

In \file{grafbase.mf}, \gbc{beginmfpic(ch)} is mostly a convenient
abbreviation for the typical use of \mfc{beginchar} with
\file{grafbase.mf}. However, to shield internal commands from users who
might inadvertantly set variables \mfc{d}, \mfc{h} or \mfc{w}, it also
sets \mfc{d\_}, \mfc{h\_} or \mfc{w\_} to the same values for internal
use. (These values are in device units)

In \file{grafbase.mp}, \gbc{beginmfpic} is similar to \mfc{beginfig}.
The variables \mfc{d}, \mfc{h}, \mfc{w}, \mfc{d\_}, \mfc{h\_}, \mfc{w\_}
are set just as in the \MF{} version.

\gbc{endmfpic} functions like \mfc{endchar} or \mfc{endfig}, but is
meant to match \gbc{beginmfpic}. Moreover, when boolean \mfc{clipall}
is set, \mfc{endmfpic} clips the picture to be shipped out to the
nominal dimensions. The \MP{} version also responds to the \mfc{truebbox}
boolean: If this is \mfc{true}, the bounding box in the output \EPS{}
file will reflect the actual extent of the figure, if it is \mfc{false},
the bounding box will be forced to the nominal dimensions.


\head{Extra Trigonometric and Hyperbolic Functions}

\bcd
{\it tand, cotd, secd, cscd, acos, asin, atan;\\
sin, cos, tan, cot, sec, csc, invcos, invsin, invtan;\\
exp, ln, cosh, sinh, tanh, acosh, asinh, atanh;\\
Arg, zexp, cis.}
\ecd

\gbc{tand($x$)}, \gbc{cotd($x$)}, \gbc{secd($x$)} and \gbc{cscd($x$)}
are the tangent, cotangent, secant and cosecant of $x$, where $x$ is in
degrees.

\gbc{sin($x$)}, \gbc{cos($x$)}, \gbc{tan($x$)}, \gbc{cot($x$)},
\gbc{sec($x$)}, and \gbc{csc($x$)} are the the various trig
functions, where $x$ is in radians. That is, \mfc{cos(x)} is the same
as \mfc{cosd(x*radian)}.

\gbc{acos($x$)} and \gbc{asin($x$)} are the arccosine and arcsine, in
degrees, of $x$. Evidently, $x$ must be between $-1$ and $+1$.
\gbc{atan($x$)} is the arctangent, and $x$ is unrestricted.

\gbc{invsin}, \gbc{invsin} and \gbc{invtan} return angles in radians:
\gbc{invsin(x)} is the same as \gbc{(asin(x))/radian}.

\gbc{exp($x$)} is the value of $e^x$.

\gbc{ln($x$)} is the natural logarithm of $x$.

\gbc{cosh($x$)}, \gbc{sinh($x$)} and \gbc{tanh($x$)} are the
hyperbolic cosine, the hyperbolic sine and the hyperbolic tangent of~$x$.

\gbc{acosh($y$)}, \gbc{asinh($y$)} and \gbc{atanh($y$)} are their
inverses.

For complex variables we have:
\gbc{Arg($z$)} returns the angle in radians of the pair $z = (x,y$).
\gbc{zexp($z$)} returns the pair $e^x(\cos y, \sin y$) where $z =
(x,y$). This corresponding to complex exponentiation. Finally
\gbc{cis($\theta$)} returns ($cos\theta, sin\theta$).

\head{Coordinate Systems and Transformations}

\subhead{Coordinate Nesting}

\bcd
{\it T\_stack, T\_push, T\_pop;\\
bcoords, ecoords.}
\ecd

In order to allow local coordinate systems to be nested without
destructively interfering with each other, we define a stack of (affine)
transforms.

\gbc{T\_stack[]} is an array of transforms, which \prog{grafbase}
uses to implement its stack of local coordinate systems. Users should
avoid using \gbc{T\_stack} by name, as its security depends on its being
used only by the \gbc{bccords} and \gbc{ecoords} macros.  The same
avoidance rule applies to all macros that have an underscore \gbc{\_} in
their name.  This rule is a naming convention laid down by Knuth.

\gbc{T\_push($T$)} pushes transform $T$ \ onto the stack \gbc{T\_stack}.

\gbc{T\_pop($T$)} pops the stack \gbc{T\_stack}, and assigns its
erstwhile top element to the transform~$T$.

The purpose of \gbc{bcoords} and \gbc{ecoords} is to enclose a local
coordinate system.  Thus compound objects can be built and manipulated.

\gbc{bcoords} preserves the values of \mfc{ztr} and \mfc{vtr}.

\gbc{ecoords} restores the values of \mfc{ztr} and \mfc{vtr} that was
preserved by the most recent \gbc{bccords}.


\subhead{Coordinate Changes}

\bcd
{\it apply\_t.
xslant, yslant, zslant, xyswap, boost.}
\ecd

\gbc{apply\_t($T$)} changes the coordinate system: it replaces \gbc{ztr}
by transform $T$ followed by~\gbc{ztr} (and \gbc{vtr} is appropriately
modified). Note that transforms applied by successive \gbc{apply\_t}s
ultimately act in reverse order (just as the mathematical notation
$A\circ B z$ applies $B$ to $z$ and then $A$ to the result.)

\gbc{xslant}~$s$ \ is the same as the \MF{} primitive \gbc{slanted~$s$}
: a point $(x,y)$ maps onto $(x,y) + s(y,0)$.

\gbc{yslant}~$s$ \ nicely complements \gbc{xslant} by mapping a point
$(x,y)$ onto $(x,y) + s(0,x)$.

\gbc{zslant}~$p\,$, where $p = (u,v)$, maps $(x,y)$ onto $(xu+yv,
xv+yu)$. (This complements the \MF{} primitive \gbc{zscaled$p$} \ which
maps $(x,y)$ onto $(xu-yv,xv+yu)$.)

\gbc{xyswap} swaps the X and Y coordinates:  $(x,y) \mapsto (y,x)$.

\gbc{boost~$\chi$} \ is the same as \gbc{zslant($\cosh\chi,
\sinh\chi$)}, which is the formula for a boost (the hyperbolic
equivalent of a rotation) in special relativity.

\subhead{Path Transformation}

These operators applied to a path return a transformed path.

\bcd
{\it rotatedpath, shiftedpath, scaledpath, \\
     xscaledpath, yscaledpath, slantedpath, \\
     xslantedpath, yslantedpath,\\
     reflectedpath, xyswappedpath.}
\ecd

\gbc{rotatedpath($p,\theta$)}~$f$ \ returns the \emph{graph} coordinate
path formed by rotating the \emph{graph} coordinate path $f$ by $\theta$
degrees around the point described by the \emph{graph} cooordinate
pair~$p$. This command compensates for differences in scales by doing
the rotation in device coordinates and converting back to graph
coordinates. This ensures that the resulting path is congruent to the
original when both are drawn.

\gbc{shiftedpath($v$)}~$f$ \ returns the \emph{graph} coordinate path
formed by shifting the \emph{graph} coordinate path $f$ by the graph
coordinate vector $v$.

\gbc{scaledpath($p,s$)}~$f$ \ returns the \emph{graph} coordinate path
formed by scaling the \emph{graph} coordinate path $f$ by $s$, doing so
in such a way that graph coordinate point $p$ remains fixed. I.e., it
returns \mfc{$f$ shifted $-p$ scaled $s$ shifted $p$}.

\gbc{xscaledpath($x_0,s$)}~$f$ \ returns the \emph{graph} coordinate
path formed by xscaling the \emph{graph} coordinate path $f$ by $s$,
doing so in such a way that points with x-coordinate equal to $x_0$
remain fixed.

\gbc{yscaledpath($y_0,s$)}~$f$ \ returns the \emph{graph} coordinate
path formed by yscaling the \emph{graph} coordinate path $f$ by $s$,
doing so in such a way that points with y-coordinate equal to $y_0$
remain fixed.

\gbc{slantedpath($y_0,s$)}~$f$ \ returns the \emph{graph} coordinate
path formed by slanting the \emph{graph} coordinate path $f$ by $s$,
doing so in such a way that points with y-coordinate equal to $y_0$
remain fixed. I.e., all points $(x,y)$ are shifted right by $s(y-y_0)$

\gbc{xslantedpath} is an alias for \gbc{slantedpath}.

\gbc{yslantedpath} is similar to \gbc{xslantedpath} except the roles of
x and y are exchanged.

\gbc{reflectedpath($p$, $q$)}~$f$ \ returns the \emph{graph} coordinate
path obtained by reflecting $f$ through the line from $p$ to $q$. This
command compensates for differences in scales by reflecting in device
coordinates and converting back to graph coordinates. This ensures that
the resulting path is congruent to the original when both are drawn.

\gbc{xyswappedpath} is similar to \gbc{reflectedpath((0,0),(1,1))},
except it is done entirely in graph coordinates, simply changing a point
with coordinates $(x,y)$ to the point with coordinates $(y,x)$. If x and
y scales are different, the resulting path may not be congruent to the
original if both are drawn.

\head{Bitmaps, Clipping and Rendering}

\subhead{Picture to Picture --- Bitwise Operations}

\bcd
{\it mono.
andto, picand;
orto, picor;
xorto, picxor;
subto, picsub.}
\ecd

(None of these pixel oriented operations is available in \MP.)

\MF{}'s picture variables are not pure bitmaps; each pixel is a
negative, zero or positive weight.  When the \mfc{shipout} primitive is
called, as in \mfc{shipout $v$;} where $v$ is a picture variable,
the pixels of positive weight in $v$ are interpreted as value one ($1$),
and those of zero or negative weight are interpreted as zero ($0$).  The
\file{GF} font file uses run-length encoding to efficiently record the
positions of the pixels of value one~($1$).

When \MF{} draws pixels in a picture variable, it does so via one
of the forms of the \mfc{addto} primitive.  The result of this
\emph{rendering} are pixels of various weights, as mentioned above.

In order to perform certain picture manipulation tasks, such as
clipping to a given boundary curve, it is highly beneficial that pixels
be either one or zero --- in other words, pictures should be pure
bitmaps.

The operation \gbc{mono($v$)} changes picture $v$ so that all
positive pixels are replaced by one ($1$) and all negative or zero
pixels by zero~($0$).

\gbc{andto($v, w$)} replaces picture $v$ by the bitwise \emph{and}
of~$v$ and~$w$.

$v$ \gbc{picand}~$w$ \ returns the picture formed by the bitwise
\emph{and} of~$v$ and~$w$.

\gbc{orto($v, w$)}  replaces picture $v$ by the bitwise \emph{or} of~$v$
and~$w$.

$v$ \gbc{picor}~$w$ \ returns the picture formed by the bitwise
inclusive \emph{or} of~$v$ and~$w$.

\gbc{xorto($v, w$)}  replaces picture $v$ by the bitwise \emph{exclusive
or} of~$v$ and~$w$.

$v$ \gbc{picxor} $w$ \ returns the picture formed by the bitwise
\emph{exclusive or} of~$v$ and~$w$.

\gbc{subto}($v, w$)  replaces picture $v$ by the bitwise
\emph{subtraction} of~$w$ from~$v$.

$v$ \gbc{picsub} $w$ \ returns the picture formed by the \emph{bitwise
subtraction} of $w$ from $v$. \emph{Note:}  $0-1=0$ here, as in Boolean
algebra.

\subhead{Color Operations}

(None of these color operations is available in \MF.)

\bcd
{\it rgb, RGB, cmyk, gray, named.}
\ecd

\gbc{rgb($r, g, b$)} is essentially a no-op. It takes three
parameters $r$, $g$ and $b$, converts non-numerics to 0, truncates
numerics to the range $0$ to $1$. All the following do similar
conversions and truncations.

\gbc{RGB($R,G,B$)} essentially divides $(R,G,B)$ by 255 to return a
color~triple.

\gbc{cmyk($c,m,y,k$)} returns the \MP{} color triple equivalent of a cmyk
color quadruple.

\gbc{gray($g$)} returns the color triple $(g,g,g)$, i.e., gray.
\gbc{gray(0)} is \mfc{black} and \gbc{gray(1)} is \mfc{white}.

\gbc{named($n$)} returns $n$ if $n$ is a known \MP{} color expression,
otherwise \mfc{black}. Normally $n$ would be a color variable, i.e., a
\emph{named} color.

These operations are named after the names of corresponding color models
in the \LaTeX{} \prog{color} package.

Many of the \prog{grafbase} drawing commands are implemented in
\file{grafbase.mp} as in the following example: The command
\gbc{safedraw} expands to \gbc{colorsafedraw(drawcolor)}, where
\gbc{colorsafedraw} has a definition almost identical to that of the
command \gbc{safedraw} in \file{grafbase.mf}, except for the addition of
a color parameter, used with the drawing option \gbc{withcolor ...}$\,$.
Such differences account for the ability to set the drawing color with
\gbc{drawcolor}, the fill color with \gbc{fillcolor}, etc. These extra
\gbc{color...} commands will not be mentioned in the exposition of the
basic \prog{grafbase} commands later. Search the file \file{grafbase.mp}
for commands beginning with ``\mfc{color}'' to get the whole story.


\subhead{Contour to Picture --- Clipping and Filling}

\bcd
{\it interior, interiors.\\
clipto, clipsto, clip (clipped in \MP).\\
picfill, picunfill, picneg.}
\ecd

\gbc{interior}~$c$ \ returns the picture comprising the \emph{filled}
interior of the closed curve (aka \emph{contour}) $c$, where $c$ is
described in \emph{graph} coordinates. \emph{Note:}  \gbc{interior} is
adapted from \MFbook{}'s \mfc{safefill} macro.

\gbc{interiors}~$cc$ \ returns the picture comprising the \emph{filled}
interiors of the \emph{contours} in the path array $cc$, which are
described in \emph{graph} coordinates.

The remaining picture operations are derived from the preceding ones.
The \emph{contours} are described in \emph{device} coordinates.

\gbc{clipto($v$)}~$c$ \ clips picture $v$ to the interior of
the contour~$c$.

\gbc{clipsto($v$)}~$cc$ \ clips picture $v$ to the interiors of
the \emph{contours} in the path array~$cc$.

\gbc{clip($v$)}~$c$ \ returns the picture formed by \emph{clipping}
picture $v$ to the interior of \mfc{contour} $c$.  In \MP, \mfc{clip} is
a primative command, so this operation is named \gbc {clipped}. Note: in
\file{grafbase.mf}, a side effect of \gbc{clip} is that \mfc{v} is
operated on by \gbc{mono}.

\gbc{picfill($v$)}~$c$ \ \emph{fills} the interior of \emph{contour} $c$
and adds that to $v$. In \MP, the default color used is \gbc{fillcolor}.

\gbc{picunfill($v$)}~$c$ \ changes picture $v$ by \emph{unfilling}
(making all pixels zero in) the interior of \emph{contour} $c$.  In \MP,
this fill $c$ with the color \mfc{background}, which is set equal to
\mfc{white} in \file{plain.mp}, and adds the result to $v$.

\gbc{picneg($v$)}~$c$ \ returns the picture of the reverse video
of picture $v$ as constrained within the interior of \emph{contour} $c$.
\emph{Note:}  An unrestricted reverse video is not possible because that
would require replacing all white pixels, out to infinity, by black
pixels. In \MP, this is a little different. What it does is fill the
contour $c$ with \gbc{fillcolor} and then draw $v$ on top of that in
white. What makes this different is that \PS{} makes a distinction
between something that is drawn in white and regions that were white
because nothing was drawn there. For example, if $v$ is created by
filling a large square and unfilling a smaller square inside it, then
the entire square is still filled, but part of it is filled with
\gbc{white}. If you \gbc{picneg($v$)~$c\,$}, you just get a large white
square inside $c$. In \MP{} this works best in black and white where no
unfilling has been previously done.


\subhead{Rendering Paths --- Drawing and Filling}

\bcd
{\it shpath, minpenwd, picpath;\\
picdraw, safedraw, safefill, safeunfill, safeclip;\\
drawn, filled, unfilled, CLIP.}
\ecd

All paths in this section are in \emph{device} coordinates.

In \MP, several of these have variants that can specify a color.

\gbc{shpath($v, q, f$)} \emph{draws} path $f$ in picture
$v$ using \mfc{pen} $q$. (The `sh' in its name refers to the initials of
`shade' and `hatch', where \gbc{shpath} is used.)

\gbc{minpenwd} is an \mfc{internal} variable storing the smallest
allowed diameter for a \mfc{pen} that's to be used in \gbc{picdraw}
(see below). \gbc{minpenwd} is initially \mfc{0.01{}p{}t}.

The following series of commands take a path argument that is
given in \emph{device} coordinates.

\gbc{picpath}~$d$ \ returns a picture containing a (robust)
\emph{drawing} of path~$d$.

\gbc{picdraw($v$)}~$d$ \ \emph{draws} a path $d$ in picture
$v$.  It is designed to be more robust than plain \MF{}'s \mfc{draw}
macro.

\gbc{safedraw}~$d$ \ \emph{draws} path $d$ in the picture
\gbc{active\_plane}.

\gbc{safefill}~$c$ \ \emph{fills} the interior of \emph{contour} $c$ in
\gbc{active\_plane}. \emph{Note:}  This is different from the
\mfc{safefill} in \MFbook{}.

\gbc{safeunfill}~$c$ \ \emph{unfills} the interior of \emph{contour}
$c$ in \gbc{active\_plane}.

\gbc{safeclip}~$c$ \ \emph{clips} \gbc{active\_plane} to the interior of
\emph{contour} $c$.

The next group of commands take a path argument that is given in
\emph{graph} coordinates.

\gbc{drawn}~$f$ \ \emph{draws} the path $f$ (in \gbc{active\_plane}), and
returns~$f$.

\gbc{filled}~$c$ \ \emph{fills} the \emph{contour} $c$, and returns~$c$.

\gbc{unfilled}~$c$ \ \emph{unfills} the \emph{contour} $c$, and returns
$c$.  In \MP{} this means filling with the color \mfc{background}.

\gbc{CLIP}~$c$ \ \emph{clips} the \gbc{active\_plane} to the interior of
the \emph{contour} $c$, and returns $c$.

\vskip\myskip
{\it Note}
\nobreak
\vskip\myskip
In subsequent sections of this document, \emph{drawing} and
\emph{filling} write to \gbc{active\_plane}.


\head{Shading and Hatching}

\bcd
{\it setdot;\\
onedot, picdot, thepolkadot.\\
showbox, bbox, tightbbox, tbbox;\\
shade; thatchf, thatch,\\
hhatch, vhatch, lhatch, rhatch, xhatch.}
\ecd

\emph{Note:}  Shading and hatching macros \emph{fill} closed
paths, but \emph{draw} open paths.

\gbc{setdot($f, s$)} returns a picture consisting of the
\gbc{interior} of the path $f$ scaled $s$ if $f$ is a closed
path, otherwise it returns a drawing of~$f$.

\prog{grafbase} sets \gbc{onedot} to \gbc{setdot(dotpath, 0.5pt)},
\gbc{shadedot} to \gbc{setdot(dotpath, shadewd)}, and \gbc{thepolkadot}
to \gbc{setdot(dotpath, polkadotwd)}.

\gbc{picdot($v$, $w$, $p$)} superimposes the picture $w$ at the
position given by pair $p$ in \emph{device} coordinates on the
picture~$v$.

For debugging purposes, \prog{grafbase} defines a boolean
variable \gbc{showbox} which determines whether bounding boxes are
shown.  Normally, \gbc{showbox} is set to \mfc{false}.

\gbc{tightbbox($g$, ll, ur)} sets the pair variables \gbc{ll}
and \gbc{ur} to the lower left and upper right corners, respectively,
of the \emph{tight} bounding box of the path $g$.  All three
arguments are described in \emph{device} coordinates.

\gbc{tbbox($g$, ll, ur)} sets the pair variables \gbc{ll} and
\gbc{ur} to the lower left and upper right corners, respectively, of
the \emph{tight} bounding box containing the array $g[]$ of the paths.
All three arguments are described in \emph{device} coordinates.

In \file{grafbase.mf},
\gbc{bbox($g$, ll, ur)} sets the pair variables \gbc{ll} and
\gbc{ur} to the lower left and upper right corners, respectively, of
the \emph{loose} bounding box defined by the control points of the
path $g$. This is faster than \gbc{tightbbox} and is used when all
one needs is an enclosing rectangle (for example, the hatching commands
hatch this loose rectangle and then clip to~$g$).

\MP{} already has a \mfc{bbox} command in \file{plain.mp} which is
incompatible with the above command. Moreover, \gbc{tightbbox} simply
calls the \MP{} primatives \mfc{llcorner} and \mfc{urcorner}. If using
\file{grafbase.mp}, simply use \gbc{tightbbox} where one might use
\gbc{bbox} in \file{grafbase.mf}.

\gbc{shade(sp)}~$f$ \ shades the interior of path $f$ (described
in \emph{graph} coordinates) using dots of a shape and size detrmined
by the \gbc{setdot} macro, spaced \gbc{sp} \emph{pixel} units apart.
Successive rows are offset by half of \gbc{sp}. The dots are first
drawn on a rectangle determined by \gbc{ll} and \gbc{ur} calculated from
\gbc{bbox($f$, ll, ur)}. They are positioned on a pixel grid in this
rectangle, and then clipped to $f$. \gbc{shade(sp)}~$f$ \ returns $f$.

In \MP, \gbc{shade} merely computes a level of gray from \gbc{sp} and
\gbc{shadewd} and then calls \gbc{colorsafefill} with that level of gray.

\gbc{thatchf($v_c$, CT, sp, xa, xb, ya, yb)} hatches the interior of
the upright box defined by the X and Y boundaries \gbc{xa, xb, ya, yb},
using lines that are horizontal and spaced \gbc{sp} units apart, where
all five dimensions are measured in the coordinate system determined by
the affine transform \gbc{CT}. The hatched drawing is added to the
picture $v_c$. The line thickness is determined by \gbc{hatchpen}.

In \MP, an additional color parameter comes between $v_c$ and~\gbc{CT}.

\gbc{thatch(sp, $\theta$)}~$f$ \ hatches the interior of path $f$
(described in \emph{graph} coordinates) with lines at angle $\theta$,
spaced sp apart in \emph{device} coordinates, and adds the drawing to
\gbc{active\_plane}.

The macros
\gbc{hhatch(sp)}~$f$ \ (horizontal hatching),
\gbc{vhatch(sp)}~$f$ \ (vertical hatching),
\gbc{lhatch(sp)}~$f$ \ (left hatching),
and \gbc{rhatch(sp)}~$f$ \ (right hatching)
call \gbc{thatch} with angles $\theta$ of $0$, $90$, $-45$ and $45$
degrees, respectively. In \MP, these hatch in \gbc{hatchcolor}.

\gbc{xhatch(sp)}~$f$ \ is a cross-hatch that combines left and right
hatching.

\head{Tiles}

\bcd
{\it tile, endtile;
is\_tile; tess.}
\ecd

\gbc{tile(atile, unit, width, height, clipon)}~$\ldots$
\gbc{endtile}
provides an environment in which the tile \gbc{atile} can be defined.
Within this environment, \gbc{active\_plane} means the tile, and the
unit of length is \gbc{unit}. The nominal boundary of the tile is
specified by the given \gbc{width} and \gbc{height}, with the other
two sides being at $X=0$ and $Y=0$. The tile is clipped to the boundary
if the boolean expression \gbc{clip} is true. The \gbc{tile}
environment can be thought of a miniature mfpic environment with
\gbc{xneg=0}, \gbc{yneg=0}, \gbc{xpos=width}, \gbc{ypos=height},
\gbc{unitlen=unit} and \gbc{xscale=yscale=1}.

\gbc{is\_tile(atile)} returns \mfc{true} if \gbc{atile} is of the
correct data type to be a tile, otherwise it returns \mfc{false}.

\gbc{tess(atile)}~$c$ \ tiles (tesselates) the interior of the closed
path $c$ with an array of copies of the tile \gbc{atile}, then
returns $c$. The path $c$ is described in \emph{graph}
coordinates.

\head{Dots and Dashes}

\bcd
{\it dashed, dotted;
doplot, gendashed;
dashpat.}
\ecd

\gbc{dashed($d, s$)}~$f$ \ \emph{draws} a series of dashes along
the path $f$, with dash length $d$ and dash space $s$, and returns
$f$. Here $d$ and $s$ are in \emph{device} coordinates, and $f$ is in
\emph{graph} coordinates. In plain \MP, \mfc{dashed} is a primative; in
\prog{grafbase} this primative meaning is available as \gbc{dashed\_}.
\gbc{dashed} does nothing but call \gbc{dashpat} and then
\gbc{gendashed}.

\gbc{dotted($d, s$)}~$f$ \ \emph{draws} a series of dots along the
path $f$, with dot size $d$ and dot space $s$, and returns $f$.
Here $d$ and $s$ are in \emph{device} coordinates, and $f$ is in
\emph{graph} coordinates. \gbc{dotted} merely calls the more general
\gbc{doplot} macro.

\gbc{doplot(sym, sc, dgap)}~$f$ \ plots the curve $f$ (in graph
coordinates) using symbol \gbc{sym}, scaled by \gbc{sc}, spaced apart by
\gbc{dgap}. Both \gbc{sc} and \gbc{dgap} should be in device
coordinates. If \gbc{sym} is a path, \gbc{doplot} creates a picture from
it (by drawing if it is open, or filling if it is a cycle) scaled by
\mfc{sc}. Then it calls \gbc{dashpat(dots)(0,dgap)} and then
\gbc{gendashed(dots)}~$f$ \ with \gbc{plot\_pic} equal to this picture.
If \gbc{sym} is a picture, it is not scaled, but otherwise the
proceedure is the same. In \MP{}, \mfc{sym} is permitted to be a string;
it is converted to a picture with the \MP's \mfc{infont} operator
(but not rescaled).

\gbc{dashpat(pat)($t$)} takes a text list of dimensions $t$ and a
suffix \gbc{pat} and creates three numeric arrays: \gbc{pat.start[]},
\gbc{pat.rep[]}, and \gbc{pat.finish[]}. The main one is \gbc{pat.rep}
which is used by \gbc{gendashed} to draw the repeating pattern of dashes
along a curve. It is just the text $t$ copied to a numeric array. The
other two are an initial and final part of this pattern. These are used
by \gbc{gendashed} to draw the start and end of a curve.

\gbc{gendashed(pat)}~$f$ \ uses the arrays \gbc{pat.start[]},
\gbc{pat.rep[]}, and \gbc{pat.finish[]}. The odd positions of each array
give the length of a dash (in device coordinates), while the even
positions give the length of a space (there must be an even number of
positions except in \gbc{pat.finish}, which ends with a dash). A dash of
length 0 is drawn as a dot. The dot used is the picture variable
\gbc{plot\_pic}, if known. If it is not known, it is set equal to
\gbc{setdot(dotpath, penwd)}.  If \gbc{pat} is created by \gbc{dashpat},
the curve will start with half of the first dash in \gbc{pat.rep} and
end with half of the same dash, with a whole number of repeated patterns
in between. For special effects at the start and end, \gbc{pat.start}
and \gbc{pat.finish} can be defined independently.


\head{Points}

\bcd
{\it bpoint,
pointd,
plotsymbol.}
\ecd

\gbc{bpoint($w$, $a$)} returns a path that represents a point
with diameter $w$ in \emph{device} coordinates and location $a$ in
\emph{devive} coordinates.

\gbc{pointd($d, b, t$)} \emph{draws} a point at each of the \emph{graph}
coordinate pairs given by the text list $t$. Each disc has diameter $d$
in \emph{device} coordinates. If the boolean value $b$ is \mfc{true},
then the disc is filled, otherwise it is white with a boundary. In \MP,
when the disc is filled, \gbc{fillcolor} is used, and when not filled,
the boundary is drawn in \gbc{drawcolor}.

\gbc{plotsymbol($s, d, t$)} draws the symbol $s$ with ``diameter'' $d$
in \emph{device} units at the points given by \emph{graph} coordinate
pairs in the text list $t$. As the symbols are not all round, $d$ is a
sort of average diameter. A ``symbol'' is either one of the predefined
paths \gbc{Triangle}, etc., listed in {\it Common Global Variables}, or a user
defined path which should have roughly diameter 1 and be roughly
centered at the origin. If the symbol is a closed path, the symbol is
filled (in \gbc{fillcolor} in \MP), otherwise it is simply drawn (in
\gbc{drawcolor}). The symbol can also be a picture or (in \MP) a string.
In these case, it has the same behavior as \gbc{doplot}, see section
{\it Dots and Dashes}

\head{Arrows}

\bcd
{\it hdwdr, hdten, hfilled.
headshape, head, headpath.
arrowdraw.}
\ecd

\gbc{hdwdr} is an internal variable giving the ratio of the width of
the arrowhead divided by its length.

\gbc{hdten} is an internal variable giving the tension on the curved
sides, or \emph{barbs}, of the arrowhead.  This controls the curvature
of the \emph{barbs}.

\gbc{hfilled} is a boolean variable.  If it's \mfc{true}, then
arrowheads will be \emph{filled} otherwise
they'll be simply drawn. If unfilled, an arrowhead
is simply two barbs; the ends of the barbs are not connected. In \MP{}
arrowheads are colored \gbc{headcolor}.

\prog{grafbase} initialises \gbc{hdwdr} to 1, \gbc{hdten} to 1, and
\gbc{hfilled} to false.

\gbc{headshape(wr, tens, fil)} sets the global parameters \gbc{hdwdr,
hdten, hfilled} to \gbc{wr, tens, fil} respectively. The initial
arrowhead shape is set by \gbc{headshape(1, 1, false)}.

\gbc{head(front, back, width, tens, filled)} \emph{draws} the
arrowhead. The argument \gbc{front} is a pair giving the position
(in \emph{graph} coordinates) of the tip of the arrowhead, \gbc{back}
is a pair giving the position of the base of the arrowhead, \gbc{width}
is a numeric value giving the ratio of the width to the length of the
arrowhead, \gbc{tens} is a numeric value giving the tension of the
\emph{barbs}, and \gbc{filled} is a boolean value which if \mfc{true}
means that the arrowhead is \emph{filled} but if \mfc{false} causes the
arrowhead to be simply drawn.

\gbc{headpath($l, \theta, b$)}~$f$ \ \emph{draws} an arrowhead on the
path $f$. The arrowhead has length equal to $l$ \emph{graph} units, it
is rotated by $\theta$ degrees, and is set back from the last point of
$f$ by $b$ \emph{graph} units. The \gbc{width}, \gbc{tens} and
\gbc{filled} values of the arrowhead are set by the global variables
\gbc {hdwdr}, \gbc{hdten}, and \gbc{hfilled}. \gbc{headpath} returns the
path $f$.

\gbc{arrowdraw($l, f$)} \emph{draws} $f$ and then adds the arrowhead,
provided $l > 0$. (Essentially the same as \gbc{headpath($l, 0,
0$)~$f\,$}, but without returning~$f$).


\head{Axes, Axis Tic Marks, and Grid}

\bcd
{\it axes, xaxis, yaxis;\\
axis.x, axis.y, axis.l, axis.b, axis.r, axis.t;\\
xmarks, ymarks, lmarks, bmarks, rmarks, tmarks, axismarks;\\
grid, gridlines, polarpatch, polargrid.}
\ecd

\gbc{axes($l$)} \emph{draws} the X axis from \emph{graph} coordinate
\gbc{xneg} to \gbc{xpos}, and the Y axis from \emph{graph} coordinate
\gbc{yneg} to \gbc{ypos}, both with arrowheads of length $l$
\emph{device} units. Obviously \gbc{xaxis} and \gbc{yaxis} draw only the
corresponding axis.

\gbc{axis.x($l$)} and \gbc{axis.y($l$)} return the (straight line) path
after drawing the head, so one can say \gbc{dotted axis.x(5pt)}.
\gbc{drawn axis.x} and \gbc{drawn axis.y} differ slightly from
\gbc{xaxis} and \gbc{yaxis} in that the axes need not extend from border
to border, as explained below.

The remaining four \gbc{axis.\$($l$)} commands return the axis along the
corresponding border of the picture. The axis at the left boundary is
shifted inward by the amount \gbc{laxis} in graph coordinates. It starts
\gbc{baxis} graph units above the bottom edge of the picture and ends
\gbc{taxis} units below the top edge. Similar descriptions hold for the
other three boundary axes. This is designed to make adjacent side axes
come together without crossing. The \gbc{axis.x} and \gbc{axis.y} also
will not cross the side axes.

\gbc{xmarks($l, t$)} \emph{draws} tic marks along the X axis, at the
X values (in \emph{graph} coordinates) given by the text list $t$. The
Each tic is $l$ \emph{device} units long and it is normally centered on
the axis, but its position can be controled by the numeric \gbc{xtick},
which can take the values \gbc{ontop}, \gbc{onbottom} or \gbc{centered}.

\gbc{ymarks} is similar, except \gbc{ytick} can take values
\gbc{onleft}, \gbc{onright} or \gbc{centered}.

The border axes marks (\gbc{lmarks}, etc.) are similar, except that the
corresponding numeric to control the position (\gbc{ltick}, etc.) can
also take the values \gbc{inside} and \gbc{outside}, in addition to the
obvious appropriate choices of the values already meantioned.

The absolute positions, \gbc{ontop}, \gbc{centered}, etc., are positive
and the relative positions \gbc{inside} and \gbc{outside} are negative.
One may set \gbc{xtick}, etc. to reasonable linear combinations of these
numerics to get expected effects. So \gbc{ltick := .75inside +
.25outside;} would result in the \gbc{lmarks} being 75\% inside and 25\%
outside. Mixing absolute and relative positions in this way has
generally unexpected results.

All the above marks commands are implemented by calling \gbc{axismarks}
with appropriate parameters.

\gbc{axismarks($\theta_{\rm in}, {\it tp}, {\it loc}, {\it
dir}$)($l$)($t$)} draws tic marks with length $l$ at coordinates
specified by the list $t$, in a manner determined by the first four
parameters. The parameter {\it dir} is the positive direction of the
axis, normally \mfc{up} or \mfc{right}. $\theta_{\rm in}$ is either $90$
or $-90$ and specifies the angle {\it dir} must be rotated to point
``inward''. {\it tp} is the tick position, such as \gbc{centered},
\gbc{inside}, etc. Finally, {\it loc} is the location of the origin of
the axis, (\mfc{origin} for the x- and y-axis, \gbc{(xneg + laxis, 0)}
for the left border axis, etc.).

\gbc{grid($x_s, y_s$)} draws dots at each point whose graph
coordinates are both integer multiples of $x_s$ and $y_s$. \gbc{gridlines}
draws horizontal and vertical lines that intersect at all these points.
This is a change from versions earlier than 0.4.5, when it used to
simply start at the bottom and left of the figure and move left and up
in steps of $x_s$ and $y_s$, placing dots as it went.

\gbc{polarpatch($r_1,r_2,\Delta r,\theta_1,\theta_2,\Delta\theta$)}
draws the boundary of the region $r_1<r<r_2$,~$\theta_1<\theta<
\theta_2$ as well as all the arcs $r = r_1+n\Delta r$ and lines $\theta
= \theta_1+\Delta\theta$ in between. Most of the work is (all but the
boundaries) done by the utility \gbc{plrpatch}. \gbc{polargrid($\Delta
r,\Delta\theta$)} measures the graph boundaries, creates the smallest
\gbc{plrpatch} that covers it, clips the result to the graph boundaries
and draws the result. The differences between \gbc{polargrid} and
\gbc{plrpatch} are: the former determines the other four parameters to
\gbc{plrpatch} automatically, the former clips the result, and the
former arranges for $r_1$ and $\theta_1$ to be a multiple of $\Delta r$
and $\Delta\theta$.

\vskip\myskip
{\it Note}
\nobreak
\vskip\myskip
Unless or until otherwise indicated, subsequent graphics commands are
coordinate-independent.


\head{Upright Rectangles}

\bcd
{\it rect.}
\ecd

\gbc{rect($ll, ur$)} returns the rectangular path that has the
pair $ll$ as its lower left corner, and the pair
$ur$ as its upper right corner.


\head{Path Construction}

\bcd
{\it mkpath.}
\ecd

\gbc{mkpath($s, c, p$)} returns the smooth path \gbc{mksmooth
($c, p$)} if the boolean value $s$ is \mfc{true}, otherwise it
returns the polyline \gbc{mkpoly($c, p$)}.


\head{Polylines, including Polygons}

\bcd
{\it mkpoly, polyline.}
\ecd

\gbc{mkpoly($c, p$)} returns a polyline path with vertices given
by the array of pairs $p$.  The numeric variable $p$
contains the number of elements in $p$\mfc{[]}, numbered from $1$ to $p$. If
the boolean value $c$ is \mfc{true}, then the path is a
closed polygon, otherwise it is an open polyline.

\gbc{polyline($c, t$)} returns the polyline path that has the
vertices specified in the list $t$. If the boolean value $c$ is
\mfc{true}, then the path is a closed polygon, otherwise it is an
open polyline.


\head{Smooth Curves}

\bcd
{\it mksmooth, curve
mkcontrolledfcn, functioncurve;\\
openqbs, closedqbs;\\
mkopencbs, opencbs, mkclosedcbs, closedcbs.}
\ecd

\gbc{mksmooth($c, p$)} returns a smooth curve passing through the
points given by the array of pairs $p$.  If the boolean
value $c$ is \mfc{true}, then the curve is smoothly closed, otherwise it
is open. The curve is defined to have tension (in the \MF{} sense of
tension) between each pair of points equal to the \gbc{cur\_tension}, a
global numeric parameter.

\gbc{tcurve($T, c, t$)} returns a smooth, curved path that passes
through the pairs given in the text list $t$. If $c$ is
\mfc{true}, then the path is closed, otherwise it is open. The
curve is defined to have tension~$T$. The command \gbc{curve($c,t$)}
calls \gbc{tcurve} with $T={}$\gbc{cur\_tension}.

\gbc{mkcontrolledfcn($p$)} returns a smooth curve through the points
given by the array of pairs $p$. The curve is ``controlled'' by a
numeric parameter \gbc{fcn\_tension}. If \gbc{fcn\_tension} is
greater than or equal to 1, \emph{and\/} the x coordinates of the points
in $p$ are increasing, then the x coordinates of the curve are
guaranteed to increase. Therefore, the curve will be the graph of a
function. The parameter \gbc{fcn\_tension} is not strictly a tension
in the \MF{} sense, but functions similarly to influence the location of
control points.

\gbc{functioncurve($T, t$)} sets \gbc{fcn\_tension} to $T$, converts
the text list of pairs $t$ to an array $p$, and then calls
\gbc{mkcontrolledfcn($p$)}.

\gbc{openqbs($t$)} returns an open quadratic B-spline path
governed by the pair list in the text~$t$.

\gbc{closedqbs($t$)} returns a closed quadratic B-spline path
governed by the pair list in the text~$t$.

\gbc{mkopencbs($b$)} returns an open cubic B-spline path
governed by the pair array~$b$.

\gbc{opencbs($t$)} returns an open cubic B-spline path governed
by the pair list in the text~$t$.

\gbc{mkclosedcbs($b$)} returns a closed cubic B-spline path
governed by the pair array~$b$.

\gbc{closedcbs($t$)} returns a closed cubic B-spline path
governed by the pair list in the text~$t$.


\head{Path Closure}

\bcd
{\it lclosed;
sclosed;
bclosed;
uclosed;
ztob, cbclosed.}
\ecd

If $f$ is a closed path, then \gbc{lclosed}~$f$ \ returns $f$;
otherwise it returns the closure of $f$ by a straight line.

\gbc{sclosed}~$f$ \ returns the result of closing path $f$ in the
manner of \gbc{mksmooth}. The curve returned by \gbc{sclosed}~$f$ \ may
differ in shape from $f$, due to \MF{} optimization of control points
over the whole of a curve.

\gbc{bclosed}~$f$ \ is like \gbc{lclosed~$f\,$}, except that it closes
using a \MF{} B\'ezier curve. \emph{Note:}  The curve returned by
\gbc{bclosed}~$f$ \ may differ in shape from $f$, due to the \mfc{tension}
exerted by the B\'ezier.

\gbc{uclosed}~$f$ \ closes $f$ in a smooth manner, but unlike the previous
two operations, does not change the shape of~$f$.

\gbc{ztob($z, b$)} converts the four B\'ezier segment key points in
the pair array $z$ into four cubic B-spline control points in the
pair array~$b$.

\gbc{cbclosed}~$f$ \ returns the path formed by closing the given
path $f$ by a cubic B-spline.  (This macro uses \gbc{ztob}.)


\head{Circles and Ellipses}

\bcd
{\it ellipse, circle.}
\ecd

\gbc{ellipse($c, r_x, r_y, \theta$)} returns an ellipse with center at
the \emph{graph} coordinate pair $c$, `X' radius $r_x$, `Y'
radius $r_y$, and with its `X' radius angled at $\theta$ degrees from
the \emph{graph} coordinate system's X axis.

\gbc{circle($c, r$)} returns a circle with center at the \emph{graph}
coordinate pair $c$ and radius~$r$.


\head{Circular Arcs}

\bcd
{\it arc;
arccenter;
arcpps, arcplr, arccps, arcppp.}
\ecd

\gbc{arc($c, p_1, \theta$)} returns a path describing a circular
arc for a circle with center at the point $c$, starting point at $p_1$,
and sweep angle $\theta$ in degrees.

\gbc{arccenter($p_1, p_2, \theta$)} returns the pair defining
the center of the circle that has the points $p_1$ and $p_2$ on its
circumference separated by an angle of $\theta$ degrees.

\gbc{arcpps($p_1, p_2, \theta$)} returns a path describing the
arc that has starting point $p_1$, finishing point $p_2$, and sweep
angle $\theta$ degrees.

\gbc{arcplr($c, \theta_1, \theta_2, r$)} returns a path
describing the arc that has center point $c$, starting direction
$\theta_1$, finishing direction $\theta_2$, and radius~$r$.

\gbc{arccps($c, p_1, \theta$)} returns a path describing the arc
that has center point $c$, starting point $p_1$, and sweep angle
$\theta$ degrees.

\gbc{arcppp($p_1, p_2, p_3$)} returns a path describing the arc
that has the given starting point $p_1$, finishing point $p_3$, and that
passes through the point~$p_2$.


\head{Polar Coordinates}

\bcd
{\it polar.}
\ecd

\gbc{polar($p$)} returns the rectangular (cartesian) coordinate
pair $(x,y)$ equivalent to the polar coordinate pair $p=(r,\theta)$.


\head{Turtle}

\bcd
{\it turtle.}
\ecd

\gbc{turtle($p_0, v_1, v_2, \ldots$)} returns a path that starts
at the point $p_0$, then moves by $v_1$, then by $v_2$, and so on. (How
old do you have to be to remember ``turtle graphics''?)


\head{Sectors}

\bcd
{\it sector.}
\ecd

\gbc{sector($c, r, \theta_1, \theta_2$)} returns a path
describing a circular sector boundary with center point $c$, radius $r$,
starting angle $\theta_1$, and finishing angle~$\theta_2$.


\head{Bar and Pie Charts}

\bcd
{\it piechart, piewedge[k], pieangle[k], piedirection[k], piecenter;\\
barchart, chartbar[k], barstart[k], barlength[k], barwd.}
\ecd

\gbc{piechart(\<cw\>,$\theta$,$c$,$r$)(\<data\>)} defines a pie chart,
without actually drawing anything. \<cw\> is a boolean which, if true,
causes the wedges to be defined clockwise starting with angle $\theta$.
$c$ and $r$ are the center and radius of the pie, \<data\> is a text
parameter listing numerical values (which should be positive) separated
by commas. As a result of this command, the paths \gbc{piewedge[$k$]}
are defined with $k$ running from 1 to the number of text parameters
(which value is stored in the numeric \gbc{piewedge}). The center $c$ is
stored in the pair variable \gbc{piecenter}. The starting angle of each
wedge is stored in the array \gbc{pieangle[]} and the direction
from the point of each wedge to the center of its curved edge is
\gbc{piedirection[]}. These can be used to manipulate and draw the
wedges.

\gbc{barchart(\<start\>,\<sep\>,$r$,\<vert\>)(\<data\>)} defines a bar
chart, without actually drawing anything. \<vert\> is a boolean which,
if true, causes the bars to be defined as growing vertically, up or down
from the x-axis. If false, they grow horizontally from the y-axis. (For
the rest of this description assume \<vert\> is true.) \<start\> is the
x-coordinate of the starting edge of the first bar and \<sep\> is the
separation between the starting edge of adjacent bars. $r$ is the
proportion of this separation occupied by the bar (i.e., $r*{}$\<sep\>
is the width of each bar). \<data\> is a text parameter listing
numerical values separated by commas, which determine the height of each
bar. As a result of this command, the paths \gbc{chartbar[$k$]} are
defined with $k$ running from 1 to the number of text parameters (which
value is stored in the numeric \gbc{chartbar}). The coordinate of the
starting edge of each bar is stored in the numeric array
\gbc{barstart[]}. The length of each bar is in \gbc{barlength[]} and the
width of them all is in \gbc{barwd}. The ratio $r$ may be negative, in
which case the starting edge of each bar is actually the right edge
instead of the left.


\head{Utility Functions}

\bcd
{\it id.}
\ecd

\gbc{id($x$)} returns $x$.  This is the identity function for the next
topic.


\head{Functions and Paths}

\bcd
{\it mkfcn, tfcn;\\
parafcn, xfcn, function;\\
rfcn, plrfcn.}
\ecd

\emph{Note:}  Functions may be user-defined.

\gbc{mkfcn($s, t$)($a, b, d, pf$)} returns a path passing through the X
and Y coordinate pairs traced out by $pf(v)$ for each value $v$ from $a$
to $b$ stepping by $d$. Here $pf$ may be any \MF{} pair function of one
numeric argument. If the boolean $s$ is \mfc{true}, then the path is a
smooth curve with tension equal to $t$, otherwise it is a polyline. The
step $d$ will be adjusted if necessary so that a whole number of steps
takes place, and the curve ends with $v$ precisely equal to $b$.

\gbc{tfcn} is a synonym for \gbc{mkfcn}.

\gbc{tparafcn($s, t$)($a, b, d, pf_t$)} returns a path passing through
the X and Y coordinate pairs traced out by the text $pf_t$, which
is a \emph{literal expression} in $t$, for each value $t$ from $a$ to
$b$ stepping by $d$. If the boolean $s$ is \mfc{true},
then the path is a smooth curve with tension $t$, otherwise it is a polyline.
\gbc{parafcn} uses the text $pf_t$ to define a function $pf$ and then
calls \gbc{mkfcn}. The command \gbc{parafcn($s, a, b, d, pf_t$)} calls
\gbc{tparafcn} with $t={}$\gbc{cur\_tension}.

\gbc{xfcn($s, a, b, d, f$)} returns a path which passes through the X
and Y coordinate pairs $(x, f(x))$ for each value $x$ from $a$ to
$b$ stepping by $d$. Here $f$ may be any \MF{} numeric function of
one numeric argument. If the boolean $s$ is \mfc{true},
then the path is a smooth curve, otherwise it is a polyline. This
\gbc{xfcn} merely calls \gbc{mkfcn} with $pf$ defined by
$pf(x)=(x,f(x))$.

\gbc{tfunction($s, t$)($a, b, d, f_x$)} returns a path passing through
the X and Y coordinate pairs $(x, f_x)$, where the text $f_x$ is a
\emph{literal expression} in $x$, for each value $x$ from $a$ to $b$
stepping by $d$. If the boolean $s$ is \mfc{true}, then
the path is a smooth curve with tension $t$, otherwise it is a polyline.
\gbc{function} uses the text $f_x$ to define $pf$ and then calls
\gbc{mkfcn}. The command \gbc{function($s, a, b, d, f_x$)} calls
\gbc{tfunction} with $t={}$\gbc{cur\_tension}

\gbc{rfcn($s, a, b, d, f$)} returns a path passing through the X
and Y coordinate pairs $f(t) * (\mfc{dir}\;t)$
for each value $t$ from $a$ to $b$ stepping by $d$.
(\emph{Note:}  \mfc{dir}$\;t = {}$\mfc{(cosd($t$), sind($t$))}.) Here $f$
may be any \MF{} numeric function in one numeric argument.
If the boolean $s$ is \mfc{true}, then the path is a smooth
curve, otherwise it is a polyline.  \gbc{rfcn} constructs a pair-valued
function as described and then calls \gbc{mkfcn}.

\gbc{tplrfcn($s, t$)($a, b, d, f_t$)} returns a path passing through the
X and Y coordinate pairs $f_t * (\mfc{dir}\;t)$, where the text $f_t$ is
a \emph{literal expression} in $t$, for each value $t$ from $a$ to $b$
stepping by $d$. (\emph{Note:}  \mfc{dir}$\;t = {}$\mfc{(cosd($t$),
sind($t$))}.) If the boolean $s$ is \mfc{true}, then the path is a
smooth curve with tension $t$, otherwise it is a polyline. \gbc{plrfcn}
constructs a pair-valued function as described and then calls
\gbc{mkfcn}. The command \gbc{plrfcn($s, a, b, d, f_t$)} calls
\gbc{tplrfcn} with $t={}$\gbc{cur\_tension}

\head{Text Labels\/ {\rm(}\MP{} only\/{\rm)}}

\bcd
{\it gblabel;\\
label\_adjust, label\_sep.}
\ecd

\gbc{gblabel($l,r,b,t, a$)($s$)($p_1, p_2,\ldots$)} places the label $s$
at the points $p_j$, positioned according to the information in
$(l,r,b,t,a)$. If $L$, $R$, are the x-coordinates of the left and right
end of the bounding box of $s$, and $B$, and $T$ are the y-coordinates
of the bottom and top, then the text is shifted so the point $(lL + rR,
bB + tT)$ is at the origin (normally the leftmost point of the baseline
is at the origin), then rotated by angle $a$, then shifted to the points
$p_j$. For example, to place the lower left corner of $s$ at $p_j$, use
$(1,0,1,0,a)$. To place the center point of the baseline of $s$ at $p$,
use $(1/2,1/2,0,0,a)$. Note: One can think of $l,r,b,t$ as selecting a
new reference point, after which the text is rotated about it and then
moved so the reference point is at $p_j$. The points $p_j$ are in graph
coordinates.

The text $s$ should be either of type string or picture. The most common
example would be a \mfc{btex$\ldots$etex} expression (which is
syntactically a picture expression). If $s$ is a string, it is converted
to a picture with \gbc{infont defaultfont scaled defaultscale}.

After the label is placed it is shifted by \gbc{(a-b,c-d)*label\_sep}.
This is intended to shift the label away from the point $p$ by the
amount \gbc{label\_sep}, both horizontally and vertically,
\emph{provided} the point $p$ is on an edge of the label (one of $a$ or
$b$ is 1, the other 0 and/or one of $c$ or $d$ is 1 and the other 0).
Finally, the whole label is shifted by the pair \gbc{label\_adjust}.
Both \gbc{label\_sep} and \gbc{label\_adjust} are in device coordinates.
\gbc{label\_sep} is initialized to $0$, and \gbc{label\_adjust} to
$(0,0)$.

\head{Paths Surrounding Text\/ {\rm(}both\/ \MF{} and\/ \MP{\rm)}}

These commands more-or-less \emph{require} interaction with \TeX{} via
\prog{mfpic}:

\bcd
{\it textrect, textellipse, textoval.}
\ecd

They all are passed a pair $p=(w,h)$ giving the width and height of a
block of text (in device units like \mfc{10pt}, since this is typically
determined by \TeX) and a point in graph coordinates, and return a
closed path in graph coordinates just sufficient to enclose the
rectangle which has width $ww = w + 2$\gbc{label\_sep} and height $hh=h
+ 2$\gbc{label\_sep} and is centered at $z$ and shifted by
\gbc{label\_adjust}. The values of the numeric \gbc{label\_sep} and pair
\gbc{label\_adjust} are normally set by \prog{mfpic} commands and are in
device units. In \MP, the $p$ parameter may also be a string or picture.
In that case, \MP{} measures the text or picture and determines the pair
of dimensions itself.

\gbc{textrect~($p,r,z$)} produces a rectangle with rounded corners
with $r$ equal to the radius of the quartercircles making up the corners.
Negative values of $r$ cause weird effects (but no errors); $r = 0$
behaves as expected.

\gbc{textellipse($p,r,z$)} produces an ellipse which has x-radius $a$
and y-radius $b$ satisfying $a/b = r$. If $r = 0$, then
\gbc{textrect} is substituted. Naturally one doesn't normally want
$r$ to be very large or very small. A negative value of $r$ produce the
same shape as $|r|$, but has the effect of reversing the direction of the
path.

\gbc{textoval($p,m,z$)} produces an ellipse which has x-radius $a$
and y-radius $b$ satisfying $a/b = m(ww/hh)$, $ww$ and $hh$ defined
above. If $m = 0$, then \gbc{textrect} is substituted. Naturally one
doesn't normally want $m$ to be very large or very small. A negative
value of $m$ produces the same shape as $|m|$ but has the effect of
reversing the path.


\head{Overlays}

\bcd
Global Parameters:  {\it totalpicture, totalnull, currentnull.} \\
Macros: {\it clearit, keepit, addto\_currentpicture, mergeit, shipit,
showit\_, show\_.}
\ecd

Essentially these redefine the middle-level plain \MF{} macros for the
formation of the current font character (picture), so that typing
\gbc{keepit;} will preserve work-to-date from being destroyed by
subsequent erasures on subsequent parts of the same character.

The parameters are for bookkeeping and should not be touched by users.
Those macros intended for public use are \gbc{clearit, keepit, mergeit,
and shipit}.  Of these, only \gbc{keepit} is new; the others behave in
a similar way to their descriptions in \MFbook{}.

For a more detailed description of these overlay macros (devised by
Bruce Leban), see \MFbook{} page 295.

\end

