%%% File: mfpicdoc.tex
%%% A part of mfpic 0.6 2002/09/12
%%%
%  Documentation of mfpic macros
\input header

% Uncomment for "12pt":
%\magnification=\magstep1

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

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

% For the index:
\let\nobibtex=t \let\noarrow=t
\let\noauxfile=t
\input indexing


% HEADING:
\centerline {\bf Pictures in \TeX{} with Metafont and MetaPost%
\footnote{}{\prog {mfpic} Version:  \mfpicversion.}%
}
\centerline {by}

\centerline {Dr Thomas E. Leathrum}
\centerline {Geoffrey Tobin\footnote{$^*$}{\mail {G.Tobin@latrobe.edu.au}}}
\centerline {Daniel H. Luecking\footnote{$^{\dag}$}{\mail {luecking@uark.edu}}}
\centerline {\mfpicdate}

\part{Introduction}

\head {Why?}

Tom got the idea for \prog {mfpic}%
%
\footnote{$^{\ddag}$}{If you're wondering how to pronounce
`\prog{mfpic}': I always say `em-eff-{\bf pick}', spelling the first two
letters. This explains expressions like `{\bf an}
\prog{mfpic} file'. ---DHL.}
%
mostly out of a feeling of frustration. Different output mechanisms for
printing or viewing \TeX{} DVI files each have their own ways to include
pictures.  More often than not, there are provisions for including \PS{}
data into a DVI file using \TeX{} \mac{special}'s.  However, this
technique seems far from \TeX's ideal of device-independence, and
besides, different \TeX{} output drivers handle these \mac{special}'s in
different ways. The same problems arise with including \prog {tpic}
\mac{special}'s.

\LaTeX's \env{picture} environment has a hopelessly limited supply of
available objects to draw---if you want to draw a graph of a polynomial
curve, you're out of luck.

There is, of course, \PiCTeX, which is wonderfully flexible and general,
but its most obvious feature is its speed---or rather lack of it.
Processing a single picture in \PiCTeX{} can often take several seconds.

It occurred to Tom that it might be possible to take advantage of the
fact that \MF{} is {\it designed} for drawing things. The result of
pursuing this idea is \prog {mfpic}, a set of macros for \TeX{} and \MF{}
which incorporate \MF-drawn pictures into a \TeX{} file.

With the creation of \MP{} by John Hobby, and availability of
free \PS{} interpreters like \GS, some \prog{mfpic} users wanted to run
their \prog{mfpic} output through \MP, to produce \PS{} pictures.
Moreover, users wanted to be able to use \pdfTeX, which does not get
along well with PK fonts, but is quite happy with \MP{} pictures.
Unfortunately \file{grafbase.mf}, which contained the \MF{} macros
responsible for processing \prog{mfpic}'s output, was far too
pixel-oriented for \MP. A new file, \file{grafbase.mp} was created,
based very heavily on \file{grafbase.mf} but compatible with \MP. Now
when an \prog{mfpic} output file says \mfc{input grafbase}, either \MF{}
or \MP{} may be run on it, and each program will select its own macros,
and produce (nearly) the same picture.

With the extra capabilities of \PS{} (e.g., color) and the corresponding
abilities of \MP, there was a demand for some \prog{mfpic} interface to
access them. Consequently, switches (options) have been added to access
some of them. When these are used, output files may no longer be
compatible with \MF.

\head {Author.}

\prog {mfpic} was written primarily by Tom Leathrum during the late
(northern hemisphere) spring and summer of 1992, while at Dartmouth
College. Different versions were being written and tested for nearly two
years after that, during which time Tom finished his Ph.D. and took a
job at Berry College, in Rome, GA.  Between fall of 1992 and fall of
1993, much of the development was carried out by others.  Those who
helped most in this process are credited in the Acknowledgements.

The addition of \MP{} support was carried out by Dan Luecking around
1997--99.

\head {Manifest.}

Thirty-three files are included in this \prog {mfpic} distribution. See
\file{manifest.txt} for a list and a brief explanation of each. Only
five are actually needed for full access to \prog{mfpic}'s capabilities:
\file{mfpic.tex}, \file{mfpic.sty} (the latter needed only for \LaTeX's
\mac{usepackage}), \file{grafbase.mf} (needed only if \MF{} will be
processing the figures), \file{grafbase.mp} and \file{dvipsnam.mp}
(needed only if \MP{} will be the processor).

\part {Setting Up and Processing.}

Setting up \TeX{} and \MF{} to process these files will, to an extent,
depend on your local installation. The biggest problem you are likely to
have, regardless of your installation, will be convincing \TeX{} and its
output drivers to find \MF's output files. You should do whatever is
necessary to insure that \TeX{} looks in the current directory for
\file{.tfm} files, and that your dvi driver/viewer looks in the current
directory for \file{.pk} files.

\head{The Process}

Here is an example of the process: for the sample file
\file{pictures.tex}, first run \TeX{} on it (or run \LaTeX{} on
\file{lapictures.tex}). You may see a message from \prog{MFpic} that
there is no file \file {pics.tfm}, but \TeX{} will continue processing
the file anyway. When \TeX{} is finished, you will now have a file
called \file {pics.mf}. This is the \MF{} file containing the
descriptions of the pictures for \file {pictures.tex}. You need to run
\MF{} on \file {pics.mf}, with \mac{mode:=localfont} set up.  (Read
your \MF{} manual to see how to do this.%
\footnote{$^*$}{If you are new to running \MF, the document {\it
Metafont for Beginners}, by \hbox{Geoffrey Tobin}, is a good start. Fetch
\file{CTAN/info/metafont-for-beginners.tex}. ``\file{CTAN}'' means the
Comprehensive \TeX{} Archive Network. You can find the mirror nearest
you by pointing your browser at \file{http://www.ctan.org/}.})
This produces a \file{pics.tfm} file and a GF file with a name something
like \file{pics.600gf}. The actual number may be different and the
extension may get truncated on some file systems. Then you run
\prog{gftopk} on the GF file to produce a PK font file. (Read your
\prog{gftopk} manual on how to do this.) Now that you have the font and
font metric files generated by \MF, reprocess the file \file
{pictures.tex} with \TeX. The resulting DVI file should now be complete,
and you should be able to print and view it at your computer (assuming
your viewer and print driver have been set up to be able to find the PK
font generated from \file {pics.mf}).

It is not advisable to rely on automatic font generation to create
the \file{.tfm} and \file{.pk} files. (Different systems do this in
different ways, so here I will try to give a generic explanation.) The
reason: later editing of a figure will require new files to be built,
and most automatic systems will \emph{not} remake the files once they
have been created. This is not so much a problem with the \file{.tfm},
as \prog{mfpic} never tries to load the font if the \file{.tfm} is
absent and therefore no \file{.tfm}-making should ever be triggered.
However, if you forget to run \prog{gftopk}, then try to view your
resulting file, you may have to search your system and delete some
automatically generated \file{.pk} file (they can turn up in \emph{very}
strange places) before you can see any later changes. I suggest you
write a shell script (batch file) that (1)~runs \MF, (2)~runs
\prog{gftopk} if step~1 returns no error, (3)~deletes the \file{.tfm} if
it exists, but the \file{.pk} file does not. That way, if anything goes
wrong, the \file{.dvi} will not contain the font (\prog{mfpic} will draw
a rectangle and the figure number in place of the figure).

These processing steps---processing with \TeX, processing with
\MF/\prog{gftopk}, and reprocessing with \TeX{}---may not always be
necessary. In particular, if you change the \TeX{} document without
making any changes at all to the pictures, then there will be no need to
repeat the \MF{} steps.

If you use \prog{mfpic} with the \opt{metapost} option, then replace the
\MF/\prog{gftopk} steps with the single step of running \MP. (Read your
\MP{} documentation on how to do this.%
\footnote{$^{*}$}{The document {\it Some experiences on running Metafont
and MetaPost}, by Peter Wilson, can be useful for beginners. Fetch
\file{CTAN/info/metafp.pdf}.})

There are also somewhat subtle circumstance under which you can skip the
second \TeX{} step---if you change the picture in such a way as
\emph{not} to affect the font metric file (\MF{} case) or bounding box
(\MP{} case), then you do not have to reprocess with \TeX, because the
original metric used previously will put the pictures in the right
places. However, the post processing (\prog{dvips}, for example) would
still have to be repeated. If \pdfTeX is used, that would also have to
be repeated, since it is effectively also a post-processor. The exact
cirumstances where metrics and bounding box are unchanged is rather
involved, so it is recommended that you always repeat the \TeX{} step if
changes are made to a figure. However, there is one certain case: if you
do not use the option \opt{mplabels}, and if only text labels are added
to a picture, then only one pass through \TeX{} is required, and no
additional runs of \MF{} or \MP{}.

\head {How It Works.}

When you run \TeX{} on the file \file {pictures.tex}, \TeX{} generates a
file \file {pics.mf} (or \file{pics.mp}).  This file is formed by
\mac{write} commands in the \file {mfpic} macros.  The user should never
have to read or change the file \file {pics.mf} directly---the \prog
{mfpic} macros take care of it.

The enterprising user can determine by examining the \prog {mfpic}
drawing macros, that they translate almost directly into similar
\MF/\MP{} commands, defined in \file{grafbase.mf}/\file{.mp}. The \mac
{tlabel}'s and \mac{tcaption}'s, however, are placed on the graph by
\TeX, not \MF{} (except when options \opt{metapost} and \opt{mplabels}
are both in effect, in which case \MP{} arranges the labels).


\part{Options.}

There are now several options to the \prog{mfpic} package. These can be
listed in the standard \LaTeX{} \mac{usepackage} optional argument, or
can be turned on with certain provided commands (the only possibility
for plain \TeX). Some options can be switched off and on throughout the
document. Here we merely list them and provide a general description of
their purpose. More details may be found later in the discussion of the
features affected. The headings below give the option name, the
alternative macro and, if available, the command for turning off the option.

\head{\idx\opt{metapost},
    \idx\mac{usemetapost}}

Selects \MP{} as the figure processor and makes specific features
available. It changes the extension used on the output file to
\file{.mp} to signal that it can no longer be processed with \MF. There
is also a \opt{metafont} option (command \mac{usemetafont}), but it is
redundant, as \MF{} is the default. Either command must come before the
\mac{opengraphsfile} command (see section {\hf Files and Environments}).
They should not be used together in the same document. (Actually, this
hasn't ever been tested, but it definitely wasn't taken into
consideration in writing the macros.) If the command form
\mac{usemetapost} is used in a \LaTeXe{} document, it must come in the
preamble. Because of the timing of actions by the \prog{graphics}
package's \file{pdftex.def} and by \prog{babel},%
\footnote{$^*$}{At least as of this writing.}
when \pdfLaTeX{} is used \prog{mfpic} should be loaded and
\mac{usemetapost} (if used) declared before \prog{babel} is loaded.

\head{\idx\opt{mplabels}, \idx\mac{usemplabels},
    \idx\mac{nomplabels}}

Causes all \mac{tlabel} commands to write their contents to the output
file. It has no effect on \mac{tcaption} commands. In this case labels
are handled by \MP, and can be rotated. It requires \MP, and must come
after \MP{} has been selected or it will produce an error and be ignored
(\MF{} cannot handle labels). Otherwise the commands can come anywhere
and affect subsequent \mac{tlabel} commands, but it is recommended that
you \emph{not} mix the two methods of handling labels in a single
\env{mfpic} environment, and that you \emph{only} use \opt{mplabels} and
\opt{truebbox} (see below) together. When this is in effect, the labels
become part of the figure: they may be clipped if the \opt{clip} option is
in effect, and they contribute to the bounding box if \opt{truebbox} is
in effect.

The user is responsible for adding the appropriate \mfc{verbatimtex}
header to the output file if necessary. For this purpose, there is the
\mac{mfpverbtex} command, see the section {\hf Labels and Captions}.
If the label text contains only valid plain \TeX{} macros, there is
generally no need for a \mfc{verbatimtex} preamble at all. If you add a
\mfc{verbatimtex} preamble of \LaTeX{} code take care to make sure
\MP{} calls \LaTeX{} (for example, by setting the environmental
variable {\tt TEX} to {\tt latex} in the command shell of your operating
system.).

\head{\idx\opt{truebbox}, \idx\mac{usetruebbox},
    \idx\mac{notruebbox}}

Normally \MP{} produces an output file with the exact bounding box of
the figure. By default, \prog{mfpic} overrides this and sets the
bounding box to the dimensions specified by the \mac{mfpic} command.
This is be needed if \TeX{} is to handle \mac{tlabel} commands
correctly. If no \mac{tlabel} commands are present, or if \opt{mplabels}
is used, then it is reasonable to let \MP{} have its way. That is what
this option does. The commands can come anywhere \emph{outside} any
\env{mfpic} environment (because they change certain aspects of the
opening code of the command \mac{mfpic}), and affect all subsequent
figures. This option has no effect with \MF, but should cause no errors.

Again, it is recommended to use either both \opt{truebbox} and
\opt{mplabels} or neither of them. Actually, either one \emph{should}
work without the other but the code depends on internals of the figure
placement packages used, which could possibly change. Such a change
could, in fact, break the current code even if you follow this
recommendation. If you should get a message similar to ``Undefined
control sequence \mac{Gin@llx}'', a possible fix is to redefine the
command \mac{getmfpicoffset} (see section {\hf For Power Users Only})
to be a no-op (\mac{def}\mac{getmfpicoffset}[]).


\head{\idx\opt{clip}, \idx\mac{clipmfpic},
    \idx\mac{noclipmfpic}}

Causes all parts of the figure outside the rectangle specified by the
\mac{mfpic} command to be removed. The commands can come anywhere. If
issued inside an \env{mfpic} environment they affect the current figure
only. Otherwise all subsequent figures are affected. Note: this is a
rather rudimentary option. If \opt{mplabels} is in effect, and the
labels extend beyond the nominal bounds of the figure, they may be
clipped off. It has an often unexpected interaction with truebbox. When
both are in effect, \MP{} will produce a ``true'' bounding box that is
the intersection of two bounding boxes: the true one \emph{without
clipping}, and the box specified in the \mac{mfpic} command. It is
possible that the actual figure will be much smaller (even empty!). This
is a property of the \MP{} \gbc{clip} command and we know of no way to
avoid it.


\head{\idx\opt{centeredcaptions}, \idx\mac{usecenteredcaptions},
\idx\mac{nocenteredcaptions}}

Causes multiline captions created by \mac{tcaption} to have all lines
centered. This has no effect on the normal \LaTeX{} \mac{caption}
command.%
\footnote{$^*$}{This writer [DHL] feels that \mac{tcaption} is too
limited and users ought to apply the caption by other means, such as
\LaTeX's \mac{caption} command, outside the \env{mfpic} environment.}
The commands can be issued anywhere. If inside an \env{mfpic}
environment they should come before the \mac{tcaption} and affect only
it, otherwise they affect all subsequent figures.

\head{\idx\opt{debug}, \idx\mac{mfpicdebugtrue},
    \idx\mac{mfpicdebugfalse}}

Causes \prog{mfpic} to write a rather large amount of information to the
\file{.log} file and sometimes to the terminal. Debug information generated
by \file{mfpic.tex} \emph{while loading} is probably of interest only to
developers, but can be turned on by giving a definition to the command
\mac{mfpicdebug} prior to loading.

\head{\idx\opt{draft}, \idx\opt{final},
    \idx\opt{nowrite}, \idx\mac{mfpicdraft},
    \idx\mac{mfpicfinal}, \idx\mac{mfpicnowrite}}

Under the \opt{metapost} option, the various macros that include the
\EPS{} files emit rather large amounts of confusing error messages when
the files don't exist (especially in \LaTeX). For this reason, before
each picture is placed, \prog{mfpic} checks for the existence of the
graphic before trying to include it. However, on some systems checking
for existence can be very slow, because the entire TeX search path may
need to be checked. Therefore, \prog{mfpic} doesn't even attempt any
inclusion on the first run. The first run is detected by the
non-existence of \file{\<file\>.1}, where \<file\> is the name given in
the \mac{opengraphsfile} command (see section {\hf Files and
Environments}). These options can be used to override this
automatic detection. The command versions must come \emph{before} the
\mac{opengraphsfile} command.

These options might be used if, for example, the first figure has an
error and is not created by \MP, but you would like \prog{mfpic} to go
ahead and include the remaining figures. Then use \opt{final}. It can
also be used to overrule a \LaTeX{} global \opt{draft} option. Or if
\file{\<file\>.1} exists, but other figures still have errors and you
would like several runs to be treated as first runs until \MP{} has
stopped issuing error messages. Then use \opt{draft}.  These commands
also work under the \opt{metafont} option, but time and error messages
are less of an issue then. If all the figures have been created and
debugged, some time might be saved (with either \opt{metafont} or
\opt{metapost}) by not writing the output file again, then \opt{nowrite}
can be used.


\head{Option Scoping Rules}

Some of these options merely change \TeX{} behavior, others write
information to the output file for \MF{} or \MP. Changes in \TeX{}
behavior obey the normal \TeX{} grouping rules, the information written
to the output file obeys \MF{} grouping rules. Since each \env{mfpic}
environment is both a \TeX{} group and (corresponds to) a \MF{} group, the
following always holds: use of one of the command forms inside of an
\env{mfpic} environment makes the change local to that environment.

For options that affect only \TeX{}, the command forms have effects
local to \emph{any} \TeX{} groups. For options that send information to
\MF, the commands' effects are \emph{only} restricted by \mac{mfpic}
environments. The commands influencing only \TeX{} are the following:
\idx\mac{usemplabels}, \idx\mac{nomplabels},%
\footnote{$^{\dag}$}{The macros \mac{usemplabels} and
\mac{nomplabels} obviously affect the output file, but they do not
write anything to the output file that changes any definition or
parameter value, and so no scoping issues are involved.}
\idx\mac{usecenteredcaptions}, \idx\mac{nocenteredcaptions},
\idx\mac{mfpicdebugtrue}, and \idx\mac{mfpigdebugfalse}.  The commands
affecting only the output file are \idx\mac{clipmfpic} and
\idx\mac{noclipmfpic}.

The following commands are special: \idx\mac{usemetapost},
\idx\mac{usemetafont}, \idx\mac{usetruebbox}, \idx\mac{notruebbox},
\idx\mac{mfpicdraft}, \idx\mac{mfpicfinal}, and \idx\mac{mfpicnowrite}.
Their effects are always global, partly because they should not be issued
inside any \env{mfpic} environment (the start-up code of \mac{mfpic}
needs to know their settings).


\part {The Macros.}


\head {Files and Environments.}

\bcd
\idx\mac{opengraphsfile}[\<file\>]\\
  \ $\ldots$\\
\idx\mac{closegraphsfile}
\ecd

These macros open and close the \MF{} or \MP{} file which will contain
the pictures to be included in this document.  The name of the file will
be \file {\<file\>.mf} (or \file{\<file\>.mp}). If the \<file\>
parameter is changed, you will have to reprocess the \TeX{} file after
processing the output file. Do \emph{not} specify the extension, which
is added automatically.

\emph{Note}: This command will cause \file{\<file\>.mf} or
\file{\<file\>.mp} to be overwritten if it already exists, so be sure to
consider that when selecting the name. Repeating the running of \TeX{}
will overwrite the file created on previous runs, but that should be
harmless. For if no changes are made to \env{mfpic} environments, the
identical file will be recreated, and if changes have been made, then you
want the file to be replaced with the new version.

\bcd
\idx\mac{mfpic}[?\<xscale\>][?\<yscale\>]%
  [\<xmin\>][\<xmax\>][\<ymin\>][\<ymax\>]\\
  \ $\ldots$\\
\idx\mac{endmfpic}
\ecd

These macros open and close the \env{mfpic} environment in which the
rest of the macros below make sense. The \mac{mfpic} macro also sets up
the local coordinate system for the picture. The \<xscale\> and
\<yscale\> parameters establish the length of a coordinate system unit,
as a multiple of the \TeX{} dimension \mac{mfpicunit}. If neither is
specified, both are taken to be 1 (i.e., each coordinate system unit is
1 \mac{mfpicunit}). If only one is specified, then they are assumed to
be equal. The \<xmin\> and \<xmax\> parameters establish the lower and
upper bounds for the $x$-axis coordinates; similarly, \<ymin\> and
\<ymax\> establish the bounds for the $y$-axis. These bounds are expressed
in local units---in other words, the actual width of the picture will be
$(\<xmax\>-\<xmin\>)\cdot\<xscale\>$ times \mac{mfpicunit}, its height
$(\<ymax\>-\<ymin\>)\cdot\<yscale\>$ times \mac{mfpicunit}, and its
depth zero. One can scale all pictures uniformly by changing
\mac{mfpicunit}, and scale an individual picture by changing \<xscale\>
and \<yscale\>. After loading \prog{mfpic}, \mac{mfpicunit} has the
value \dim{1pt}.

\emph{Note}: Changing \mac{mfpicunit} or the optional parameters will
scale the coordinate system, but not the values of certain parameters
that are defined in absolute units. Examples of these are the default
width of the drawing pen, the default lengths of arrowheads, the default
sizes of dashes and dots, etc. If you wish, you can set these to
multiples of \mac{mfpicunit}, but it is difficult (and probably unwise)
to get them to scale along with the scale parameters.

In addition to establishing the coordinate system, these scales and
bounds are used to establish the metric for the \MF{} character or
bounding box for the \MP{} figure described within the environment. If
any of these parameters are changed, the \file {.tfm} file (\MF) or the
bounding box (\MP) will be affected, so you will have to reprocess the
\TeX{} file after processing the \file {.mf} or \file{.mp} file.

\bcd
\idx\mac{mfpicnumber}[\<num\>]
\ecd

Normally, \mac{mfpic} assigns the number 1 to the first \env{mfpic}
environment, after which the number is increased by one for each new
\env{mfpic} environment. This number is used internally to include the
picture. It is also transmitted to the output file where it is used as
the argument to a \gbc{beginmfpic} command. In \MF{} this number becomes
the position of the character in the font file, while in \MP{} it is the
extension on the graphic file that is output. The above command tells
\prog{mfpic} to ignore this sequence and number the next \env{mfpic}
figure with \<num\> (and the one after that $\<num\>+1$, etc.). It is up
to the user to make sure no number is repeated, as no checking is done.
Numbers greater than 255 may cause errors, as \TeX{} assumes that
characters are represented by 8-bit numbers. If the first figure is to
be numbered something other than $1$, then, under the \opt{metapost}
option, this command should come before \mac{opengraphsfile}, as that
command checks for the existence of the first numbered figure to
determine if there are figures to be included.

\bcd
\mac{begin}[mfpic]{\tt ...}\mac{end}[mfpic]
\ecd

In \LaTeX, instead of using the \mac{mfpic} and \mac{endmfpic}
macros, you may prefer to use \mac{begin}[mfpic] and
\mac{end}[mfpic]. This is by no means required:
\LaTeX{} has been designed so that \mac{begin}[command]
effectively means \mac{command}, and \mac{end}[command]
effectively means \mac{endcommand}, for any \TeX{} command.

The sample file \file{lapictures.tex} provided with \prog{mfpic}
illustrates this use of an \env{mfpic} environment in \LaTeX.

Note that the \mac{opengraphsfile} and \mac{closegraphsfile}
macros should be used under those names in \LaTeX{} too, as they do not
possess a \mac{command}$\ldots$\mac{endcommand} structure.

\vskip \myskip
The rest of the \prog {mfpic} macros do not affect the font metric
file (\file {\<file\>.tfm}), and so if these commands are changed or
added in your document, you will not have to repeat the third step of
processing (reprocessing with \TeX) to complete your \TeX{} document.
The same is true when option \opt{metapost} is selected, except under
\pdfTeX{} or \pdfLaTeX, and except when the \opt{truebbox} option is
used.

\vskip\myskip
For the remainder of the macros, the numerical parameters are expressed
in the units of the local coordinate system specified by \mac{mfpic},
unless otherwise indicated.


\head {Figures.}

\subhead{\MF{} Pairs.}

Since many of the arguments of the \prog {mfpic} drawing commands are
sent to \MF{} to be interpreted, it's useful to know something about
\MF{} concepts.

In particular, \MF{} has \mfc{pair} objects, which may be constants
or variables.  Pair constants have the form \mfc{($x$,$y$)}.  Pairs
are two-dimensional rectangular (cartesian) quantities, and are
clearly useful for representing both points and vectors on the plane.

Moreover, we herein often represent each pair by a brief name, such as
$p$, $v$ or $c$, the meanings of which are usually obvious in the
context of the macro. The succinctness of this notation also helps us to
think geometrically rather than only of coordinates.

\MP{} has these same concepts, but also has color objects, which may also
be constants or variables. Color constants have the form
\mfc{($r$,$g$,$b$)} where $r$, $g$, and $b$ are numbers between $0$ and
$1$ determining the relative proportions of red, green and blue in the
color (rgb model). A color variable is a name, like \mfc{magenta} or
\mfc{RoyalBlue} (predefined), or a color function like
\mfc{cmyk($x$,$y$,$z$,$w$)} which is defined to convert cmyk values into
\MP's native rgb model.

Some commands depend on the value of separately defined parameters. All
these parameters are initialized when \prog{mfpic} is loaded. In the
following descriptions we give the initial value of all the relevant
parameters. To save having to repeat this for each command: when \MP{}
output is selected, all the commands that draw curves draw them in
\idx\gbc{drawcolor}; those that fill shapes fill them in \idx\gbc{fillcolor};
those that create hatch lines draw them in \idx\gbc{hatchcolor}; those that
create arrowheads draw them in \idx\gbc{headcolor}; commands that use \MP{}
to place text color it in \idx\gbc{tlabelcolor}, and the \mac{gclear}
command fills a contour with the special color \idx\mfc{background}. All
these colors are predefined and initialized to \mfc{black}, except
\mfc{background} is initially \mfc{white}, but all can be changed by the
user (see the {\hf Colors\/} section below).


\subhead{Points, Lines, and Rectangles.}

\bcd
\idx\mac{pointdef}[\<name\>]{\tt($x$,$y$)}
\ecd

Defines a symbolic name for points and their coordinates. \<name\> is
any legal \TeX{} command name \emph{without} the backslash; $x$ and $y$
are any numbers. For example, after the command
\mac{pointdef}[A]{\tt(1,3)}, \mac{A} expands to {\tt(1,3)}, while
\mac{Ax} and \mac{Ay} expand to {\tt 1} and {\tt 3}, respectively.
Because of the way \mac{tlabel} is defined (see section {\hf Labels and
Captions\/} below), one cannot use \mac{A} to specify where to place a
label (unless \opt{mplabels} is in effect), but must use {\tt
(\mac{Ax},\mac{Ay})}. In most other commands, one can use \mac{A} where
a pair or point is required.

\bcd
\idx\mac{point}[?\<ptsize\>][\<$p_0$\>,\<$p_1$\>,$\ldots$]
\ecd

Draws small disks centered at the points \<$p_0$\>, \<$p_1$\>, and so
on. If the optional argument \<ptsize\> is present, it determines the
diameter of the disks, which otherwise equals the \TeX{} dimension \mac
{pointsize}, initially \dim{2pt}. The disks have a filled interior if
the command \mac{pointfilltrue} has been issued (the initial value),
\mac{pointfillfalse} causes the interior to be erased and an outline
drawn. The color of the filled circles is the predefined
\idx\gbc{fillcolor}, and the inside of the open circles is the predefined
\mfc{background}.

\bcd
\idx\mac{plotsymbol}[?\<size\>][\<symbol\>][\<$p_0$\>,\<$p_1$\>,$\ldots$]
\ecd

Draws small symbols centered at the points \<$p_0$\>, \<$p_1$\>, and so
on. The symbols must be given by name, and the available symbols are
\idx\gbc{Asterisk}, \idx\gbc{Circle},
\idx\gbc{Diamond}, \idx\gbc{Square},
\idx\gbc{Triangle}, \idx\gbc{Star},
\idx\gbc{SolidCircle}, \idx\gbc{SolidDiamond},
\idx\gbc{SolidSquare}, \idx\gbc{SolidTriangle},
\idx\gbc{SolidStar}, \idx\gbc{Cross} and
\idx\gbc{Plus}. The names should be self-explanatory. The
``Solid$\ldots$'' symbols are drawn in \idx\gbc{fillcolor}, the
open ones in \idx\gbc{drawcolor}. The \<size\> defaults to
\mac{pointsize} as in \mac{point} above. The difference between {\tt
Star} and {\tt SolidStar} is not very evident unless different colors
are used or the \<size\> is rather large (around \dim{3pt} at printer
resolutions, more for screen viewing). \gbc{Asterisk} consists of five
line segments while \gbc{Star} is the standard closed, ten-sided
polygon.

The difference between \mac{pointfillfalse}\mac{point}$\ldots$ and
\mac{plotsymbol}[Circle]$\ldots$ is that the center of the circle will
not be erased in the second version.

\bcd
\idx\mac{polyline}[\<$p_0$\>,\<$p_1$\>,$\ldots$]\\
\idx\mac{lines}[\<$p_0$\>,\<$p_1$\>,$\ldots$]
\ecd

Draws the line segment with endpoints at \<$p_0$\> and \<$p_1$\>, then
the line segment with endpoints at \<$p_1$\> and \<$p_2$\>, etc. The
result is an open polygonal path through the specified points, in the
specified order. \mac{polyline} and \mac{lines} mean the same thing.

\bcd
\idx\mac{polygon}[\<$p_0$\>,\<$p_1$\>,$\ldots$]
\ecd

Draws a closed polygon with vertices at the specified points.

\bcd
\idx\mac{rect}[\<$p_0$\>,\<$p_1$\>]
\ecd

Draws the rectangle specified by the points
\<$p_0$\> and \<$p_1$\>,
these being any two opposite corners of the rectangle.


\subhead{Axes, Axis Marks, and Grids.}

[{\it As of version 0.5, axis handling was revamped. The three commands
below were retained for backward compatibility, but alternatives were
added with somewhat different behavior.}]

\bcd
\idx\mac{axes}[?\<hlen\>]\\
\idx\mac{xaxis}[?\<hlen\>]\\
\idx\mac{yaxis}[?\<hlen\>]
\ecd

Draw $x$- and  $y$-axes for the coordinate system. The command
\mac{axes} is equivalent to \mac{xaxis} followed by \mac{yaxis}
which produce the obvious. The $x$- and $y$-axes extend the full width
and height of the \env{mfpic} environment. The optional \<hlen\> sets
the length of the arrowhead on each axis. The default is the value of
the \TeX{} dimension \mac{axisheadlen}, initially \dim{5pt}. The shape
of the arrowhead is determined as in the {\tt\string\arrow} macro below.
The color of the head is \idx\gbc{headcolor}.

Unlike other commands that produce lines or curves, these do not respond
to the prefix macros of the section {\hf Shape-Modifier Macros}. They
always draw a solid line (with an arrowhead unless \mac{axisheadlen}
is \dim{0pt}). They \emph{do} respond to changes in the pen thickness (see
\mac{penwd} in section {\hf Parameters\/}).

\bcd
\idx\mac{axis}[?\<hlen\>][\<one-axis\>]\\
\idx\mac{doaxes}[?\<hlen\>][\<axis-list\>]
\ecd

These produce any of 6 different axes. The parameter \<one-axis\> can be
{\tt x} or {\tt y}, to produce (almost) the equivalent of
\mac{xaxis} and \mac{yaxis}; or it can be {\tt l}, {\tt b}, {\tt r},
or {\tt t} to produce an axis on the border of the picture (left,
bottom, right or top, respectively). \mac{doaxes} takes a list of any
or all of the six letters (with either spaces or nothing in between) and
produces the appropriate axes. Example: \mac{doaxes}[lbrt]. The
optional argument sets the length of the arrowhead. In the case of axes
on the edges, the default is the value of \mac{sideheadlen}, which
\file{mfpic.tex} initializes to \dim{0pt}. For the $x$- and $y$-axis the
default is \mac{axisheadlen} as in \mac{xaxis} and \mac{yaxis}
above.

The commands \mac{axis}[x], \mac{axis}[y], and \mac{doaxes}[xy]
differ from the old \mac{xaxis}, \mac{yaxis} and \mac{axes} in
that these new versions respond to changes made by \mac{setrender}
(see subsection {\shf Changing the Default Rendering\/} of section {\hf
Shape-Modifier Macros\/}). Moreover, prefix macros may be applied to
\mac{axis} without error (see section {\hf Shape-Modifier Macros\/}):
\mac{dotted}\mac{axis}[x] draws a dotted $x$-axis, but
\mac{dotted}\mac{xaxis} produces an error (from \MF). (A prefix macro
applied to \mac{doaxes} generates no error, but only the first axis in
the list will be affected.)

The side axes are drawn by default with a pen stroke along the very edge
of the picture (as determined by the parameters to \mac{mfpic}). This
can be changed with the commands \mac{axismargin},
\mac{setaxismargins} and \mac{setallaxismargins}, described below.

Axes on the edges are drawn so that they don't cross each other. For
example, \mac{doaxes}[lbrt] produces a perfect rectangle. If the $x$-
and $y$-axis are drawn with \mac{axis} or \mac{doaxis}, then they
will not cross the side axes. For this to work properly, all the
following margin settings have to be done before the axes are drawn.

\bcd
\idx\mac{axismargin}[\<axis\>][\<num\>]\\
\idx\mac{setaxismargins}[\<num\>][\<num\>][\<num\>][\<num\>]\\
\idx\mac{setallaxismargins}[\<num\>]
\ecd

The \<axis\> is one of the letters {\tt l}, {\tt b}, {\tt r}, or {\tt
t}. \mac{axismargin} causes the given axis to be shifted \emph{inward}
by the \<num\> specified (in \emph{graph} coordinates). The second command
\mac{setaxismargins} takes 4 arguments, using them to set the margins
starting with the left and proceeding anticlockwise. The last command
sets all the axis margins to the same value.

A change to an axis margin affects not only the axis at that edge but
also the three axes perpendicular to it. For example, if the margins are
$M_{\rm lft}$, $M_{\rm bot}$, $M_{\rm rt}$ and $M_{\rm top}$, then
\mac{axis b} draws a line starting $M_{\rm lft}$ graph units from the
left edge and ending $M_{\rm rt}$ units from the right edge. Of course,
the entire line is $M_{\rm bot}$  units above the bottom edge. The
margins are also respected by the $x$- and $y$-axis, but only when drawn
with \mac{axis}. The old \mac{xaxis}, \mac{yaxis} and \mac{axes} ignore
them.

Special effects can be achieved by lying to one axis about the other
margins. For example, the left and right axis can be made to cross the
bottom and top axis with

\bex
\myverbatim;
\setaxismargins{1}{0}{1}{0}
\doaxes{rl}
\setaxismargins{0}{1}{0}{1}
\doaxes{bt}
@endmyverbatim
\eex
\vskip\myskip
\bcd
\idx\mac{xmarks}[?\<len\>][\<numberlist\>]\\
\idx\mac{tmarks}[?\<len\>][\<numberlist\>]\\
\idx\mac{bmarks}[?\<len\>][\<numberlist\>]\\
\idx\mac{ymarks}[?\<len\>][\<numberlist\>]\\
\idx\mac{lmarks}[?\<len\>][\<numberlist\>]\\
\idx\mac{rmarks}[?\<len\>][\<numberlist\>]\\
\idx\mac{axismarks}[\<axis\>][?\<len\>][\<numberlist\>]
\ecd

These macros place hash marks on the appropriate axes at the
places indicated by the values in the list. The optional \<len\> gives
the length of the hash marks. If \<len\> is not specified, the \TeX{}
dimension \mac{hashlen}, initially \dim{4pt}, is used. The marks on
the $x$- and $y$-axes are centered on the respective axis; the marks on the
border axes are drawn to the inside.  Both these behaviors can be
changed (see below). The commands may be repeated as often as desired.
(The timing of drawing commands can make a difference as outlined in
\file{mppicdoc.tex}.) The command \mac{axismarks}[x] is equivalent to
\mac{xmarks} and so on for each of the six axes. (I would have used
\mac{marks}, but e\kern-.16em\TeX{} makes that a primitive.)

The \<numberlist\> is normally a comma-separated list of numbers. In
place of this, one can give a starting number, an increment and an ending
number as in the following example:

\bex
\mac{xmarks}[-2 step 1 until 2]
\eex

is the equivalent of

\bex
\mac{xmarks}[-2,-1,0,1,2]
\eex

One must use exactly the words \mfc{step} and \mfc{until}.
There must be spaces between, but the number of spaces is not
significant.%
\footnote{$^*$}%
    {Experienced \MF{} programmers may recognize that anything can be
    used that is permitted in \MF's \<forloop\> syntax. Thus the given
    example can also be reworded \mac{xmarks}[-2 upto 2], or even
    \mac{xmarks}[2 downto -2]}
Users should be aware that if any of the numbers are non-integral then
due to natural round-off effects, the last value might be overshot and
a mark not printed there.

\bcd
\idx\mac{setaxismarks}[\<axis\>][\<pos\>]\\
\idx\mac{setbordermarks}[\<lpos\>][\<bpos\>][\<rpos\>][\<tpos\>]\\
\idx\mac{setallbordermarks}[\<pos\>]\\
\idx\mac{setxmarks}[\<pos\>]\\
\idx\mac{setymarks}[\<pos\>]
\ecd

These set the placement of the hash marks relative to the axis. The
parameter \<axis\> is one of the letters {\tt x}, {\tt y}, {\tt l}, {\tt
b}, {\tt r}, or {\tt t}, and \<pos\> must be one of the literal words
\gbc{inside}, \gbc{outside}, \gbc{centered}, \gbc{onleft},
\gbc{onright}, \gbc{ontop} or \gbc{onbottom}. The second command takes
four arguments and sets the position of the marks on each border. The
third command sets the position on all four border axis to the same
value. The last two commands are abbreviations for
\mac{setaxismarks}[x][\<pos\>] and \mac{setaxismarks}[y][\<pos\>],
respectively.

Not all combinations make sense (for example,
\mac{setaxismarks}[r][ontop]). In these cases, no error message is
produced: \gbc{ontop} and \gbc{onleft} are considered to be equivalent,
as are \gbc{onbottom} and \gbc{onright}. The parameters \gbc{inside} and
\gbc{outside} make no sense for the $x$- and $y$-axes, but if used \gbc{inside}
means \gbc{ontop} for the $x$-axis and \gbc{onright} for the $y$-axis. These
words are actually \MF{} numeric variables defined in the file
\file{grafbase.mf}, and the variables \gbc{ontop} and \gbc{onleft}, for
example, are given the same value.

\bcd
\idx\mac{grid}[?\<ptsize\>][\<xsep\>,\<ysep\>]\\
\idx\mac{gridpoints}[?\<ptsize\>][\<xsep\>,\<ysep\>]\\
\idx\mac{lattice}[?\<ptsize\>][\<xsep\>,\<ysep\>]\\
\idx\mac{gridlines}[\<xsep\>,\<ysep\>]\\
\idx\mac{plrgrid}[\<rsep\>,\<anglesep\>]\\
\idx\mac{plrpatch}[\<rmin\>,\<rmax\>,\<rsep\>,\<tmin\>,\<tmax\>,\<tsep\>]
\ecd

\mac{grid} draws a dot at every point for which the first coordinate is
an integer multiple of the \<xsep\> and the second coordinate is an
integer multiple of \<ysep\>. This behavior of \mac{grid} started with
version 0.4.05. Before that, the points were drawn on the left border
(and bottom border) and every \<xsep\> right of (\<ysep\> above) those.
The diameter of the dot is determined by \<ptsize\>, the default is
\dim{.5pt}. The commands \mac{gridpoints and \mac{lattice}} are synonyms
for \mac{grid}. \mac{gridlines} draws the horizontal and vertical lines
through these same points.

\mac{plrgrid} fills the graph with circular arcs and radial lines. The
arcs are centered at $(0,0)$ and the lines emanate from $(0,0)$ (even if
$(0,0)$ is not in the graph space). The corresponding \MF{} commands
actually draw enough to cover the graph area and then clip them to the
graph boundaries. If you don't want them clipped, use \mac{plrpatch}
which draws arcs with radii starting at \<rmin\>, stepping by \<rsep\>
and ending with \<rmax\>. Each arc goes from angle \<tmin\> to \<tmax\>.
It also draws radial lines with angles starting at \<tmin\>, stepping by
\<tsep\> and ending with \<tmax\>. Each line goes from radius \<rmin\>
to \<rmax\>. If $\<rmax\>-\<rmin\>$ doesn't happen to be a multiple of
\<rsep\>, the arc with radius \<rmax\> is drawn anyway. The same is true
of the line at angle \<tmax\>, so that the entire boundary is always drawn.

\subhead{Circles and Ellipses.}

\bcd
\idx\mac{circle}[\<$c$\>,\<$r$\>]
\ecd

Draws a circle centered at the point \<$c$\>
and with radius \<$r$\>.

\bcd
\idx\mac{ellipse}[?\<$\theta$\>][\<$c$\>,\<$r_x$\>,\<$r_y$\>]
\ecd

Draws an ellipse with the $x$ radius \<$r_x$\> and $y$
radius \<$r_y$\>, centered at the point \<$c$\>.
The optional parameter \<$\theta$\> provides a way of rotating the
ellipse by \<$\theta$\> degrees counterclockwise around its center.


\subhead{Curves.}

\bcd
\idx\mac{curve}[?\<tension\>][\<$p_0$\>,\<$p_1$\>,$\ldots$]
\ecd

Draws a \MF{} B\'ezier path through the specified points, in the
specified order. The optional \<tension\> defaults to $1$ and influences
\emph{how} smooth the curve is. The special value \mfc{infinity} (in
fact, usually anything greater than about $10$), makes the curve
indistinguishable from \mac{polyline}. The higher the value of
tension, the sharper the corners on the curve and the flatter the
portions in between. \MF{} requires the tension to be larger than 0.75.

\bcd
\idx\mac{cyclic}[?\<tension\>][\<$p_0$\>,\<$p_1$\>,$\ldots$]
\ecd

Draws a cyclic (i.e., closed) \MF{} B\'ezier curve through the specified
points, in the specified order. The \<tension\> is as in the
\mac{curve} command.

\vskip\myskip
Occasionally it is necessary to specify a sequence of points with
\emph{increasing} $x$ coordinates and draw a curve through them. One
would then like the resulting curve both to be smooth {\it and} to
represent a function (that is, the curve always has increasing $x$
coordinate, never turning leftward). This cannot be guaranteed with the
\mac{curve} command unless the tension is {\tt infinity}.

\bcd
\idx\mac{fcncurve}[?\<tension\>][($x_0$,$y_0$),($x_1$,$y_1$),$\ldots$]
\ecd

Draws a curve through the points specified. If the points are listed
with increasing (or decreasing) $x$ coordinates, the curve will also
have increasing (resp., decreasing) $x$ coordinates. The \<tension\> is
a number equal to or greater than $1.0$ which controls how tightly the
curve is drawn. Generally, the larger it is, the closer the curve is to
the polyline through the points. The default tension is $1.2$. (For
those who know something about \MF{}, this ``tension'' is not the same
as the \MF{} notion of tension, nor the same as the tension in the
\mac{curve} command, but it functions in a similar fashion.)


\subhead{Circular Arcs.}

\bcd
\idx\mac{arc}[?\<format\>][$\ldots$]
\ecd

Draws a circular arc specified as determined by the
\<format\> optional parameter---this macro is unusual in that the
optional \<format\> parameter determines the format of the other
parameter, as indicated below. The user is responsible for ensuring that
the parameter values make geometric sense.

\bcd
\mac{arc}[?s][\<$p_0$\>,\<$p_1$\>,\<sweep\>]
\ecd

({\it Point-Sweep Form ---this is the default format.}) Draws a circular
arc starting from the point \<$p_0$\>, ending at the point \<$p_1$\>,
and covering an arc angle of \<sweep\> degrees, measured
counterclockwise around the center of the circle. If, for example, the
points \<$p_0$\> and \<$p_1$\> lie on a horizontal line with \<$p_0$\>
to the \emph{left}, and \<sweep\> is between 0~and 360 (degrees), then
the arc will sweep \emph{below} the horizontal line (in order for the
arc to be counterclockwise). A negative value of \<sweep\> gives a
clockwise arc from \<$p_0$\> to \<$p_1$\>.

\bcd
\mac{arc}[?t][\<$p_0$\>,\<$p_1$\>,\<$p_2$\>]
\ecd

({\it Three-Point Form.})
Draws the circular arc which passes through all three
points given, in the order given.

\bcd
\mac{arc}[?p][\<$c$\>,\<$\theta_1$\>,\<$\theta_2$\>,\<$r$\>]
\ecd

({\it Polar Form.})
Draws the arc of a circle with center \<$c$\> starting at the angle
\<$\theta_1$\> and ending at the angle \<$\theta_2$\>, with radius
\<$r$\>. Both angles are measured counterclockwise from the positive $x$
axis.

\bcd
\mac{arc}[?c][\<$c$\>,\<$p_1$\>,\<$\theta$\>]
\ecd

({\it Center-Point Form.})
Draws the circular arc with center \<$c$\>,
starting at the point \<$p_1$\>, and sweeping an angle
of \<$\theta$\> around the center from that point.
(This is actually \prog {mfpic}'s internal way of handling arcs---all
other formats are translated to this format before drawing.)


\subhead{Other Figures.}

\bcd
\idx\mac{turtle}[\<$p_0$\>,\<$v_1$\>,\<$v_2$\>,$\ldots$]
\ecd

Draws a line segment, starting from the point \<$p_0$\>, and extending
along the (2-dimen\-sional vector) displacement \<$v_1$\>. It then draws
a line segment from the previous segment's endpoint, along displacement
\<$v_2$\>. This continues for all listed displacements, a process
similar to ``turtle graphics''.

\bcd
\idx\mac{sector}[\<$c$\>,\<$r$\>,\<$\theta_1$\>,\<$\theta_2$\>]
\ecd

Draws the sector, from the angle \<$\theta_1$\> to the angle
\<$\theta_2$\> inside the circle with center at the point \<$c$\>
and radius \<$r$\>, where both angles are measured in degrees
counterclockwise from the direction parallel to the $x$ axis.
The sector forms a closed path. \emph{Note}: \mac{sector} and
\mac{arc}[?p] have the same parameters, but \emph{in a different
order}.%
\footnote{$^*$}{This apparently was a mistake which we now have to
live with so as not to break existing \file{.tex} files.}

\subhead{Bar Charts and Pie Charts.}

\bcd
\idx\mac{barchart}[?\<start\>,\<sep\>,\<r\>][\<h-or-v\>][\<list\>]\\
\idx\mac{chartbar}[\<num\>]
\ecd

The macro \mac{barchart} does not actually draw anything, but computes
the \mac{chartbar} rectangles. \<h-or-v\> should be {\tt v} if you want
the bars to extend vertically from the $x$-axis, or {\tt h} if they
should extend horizontally from the $y$-axis. \<list\> should be a
comma-separated list of numbers giving the coordinates of the end of
each bar (the end that is not on the axis). The rest of this description
refers to the {\tt v} case; the {\tt h} case is analogous.

By default the bars are 1 graph unit wide, and the base of the $n$th bar
is the interval $[n-1,n]$. The optional parameter consists of three
numeric parameters separated by commas. \<start\> is the $x$-coordinate of
the left edge of the first bar, \<sep\> is the distance between the left
edges of adjacent bars, and \<r\> is the fraction of \<sep\> occupied by
each bar. The default behavior corresponds to {\tt[0,1,1]}.

The fraction \<r\> should be between -1 and 1, a negative value
indicating that the left edge referred to above is actually the right
edge. For example, if one bar chart is created with
\mac{barchart}[?1,1,-.4][v][..] and another with
\mac{barchart}[?1,1,.4][v][..] having the same number of bars, then
first will have its $n$th bar from $n-.4$ to $n$, while the second will
have its $n$th bar adjacent to that one, from $n$ to $n+.4$. This makes
it easy to draw bars side-by-side for comparison.

After a \mac{barchart} command has been issued, the individual bars may
be drawn with \mac{chartbar}[1], \mac{chartbar}[2], etc.  These are
closed rectangles and can be filled, shaded, hatched, etc., using
appropriate prefix macros (see section {\hf Shape-Modifier Macros},
below).

\bcd
\idx\mac{piechart}[?\<dir\>\<angle\>][\<$c$\>,\<$r$\>][\<list\>]\\
\idx\mac{piewedge}[?\<spec\>\<trans\>][\<num\>]
\ecd

The macro \mac{piechart} also does not draw anything, but computes the
\mac{piewedge} regions described below. The first part of the optional
parameter, \<dir\>, is a single letter which may be either {\tt c} or
{\tt a} which stand for \emph{clockwise} or \emph{anticlockwise},
respectively. It is common to draw piecharts with the largest wedge
starting at 12 o'clock (angle 90 degrees) and successive wedges
clockwise from there. This is the default. You can change the starting
angle from 90 with the \<angle\> parameter, and the change the direction
to counter-clockwise by specifying {\tt a} for \<dir\>. It is also
traditional to arrange the wedges from largest to smallest, except there
is often a miscellaneous category which is usually last and may be
larger than some others. Therefore \mac{piechart} makes no attempt to
sort the data. The data is entered as a comma separated \<list\> of
positive numbers in the second required parameter. These are only used
to determine the relative sizes of the wedges and are not printed
anywhere. The first required parameter should contain a pair \<c\> for
the center and a positive number \<r\> for the radius, separated by a
comma.

After a \mac{piechart} command has been issued, the individual wedges
may be drawn, filled, etc., using \mac{piewedge}[1], \mac{piewedge}[2],
etc. Without the optional argument, the wedges are located according to
the arguments of the last \mac{piechart} command. The optional argument
to \mac{piewedge} can override this. The parameter \<spec\> is a single
letter, which can be {\tt x}, {\tt s} or {\tt m}. The {\tt x} stands for
\emph{exploded} and it means the wedge is moved directly out from the
center of the pie a distance \<trans\>. \<trans\> should then be a pure
number and is interpreted as a distance in graph units. The {\tt s}
stands for \emph{shifted} and in this case \<trans\> should be a pair of
the form {\tt (\<dx\>,\<dy\>)} indicating the wedge should be shifted
\<dx\> horizontally and \<dy\> vertically (in graph units). The {\tt m}
stands for \emph{move to}, and \<trans\> is then the absolute
coordinates {\tt (\<x\>,\<y\>)} in the graph where the point of the
wedge should be placed.

\subhead{Polar Coordinates to Rectangular.}

\bcd
\idx\mac{plr}[(\<$r_0$\>,\<$\theta_0$\>), (\<$r_1$\>,\<$\theta_1$\>), $\ldots$]
\ecd

Replaces the specified list of polar coordinate pairs by
the equivalent list of rectangular (cartesian) coordinate pairs.
Through \mac{plr}, commands designed for rectangular coordinates
can be applied to data represented in polar coordinates---and to data
containing both rectangular and polar coordinate pairs.


\head{Colors}

\subhead{Setting the Default Colors.}

\bcd
\idx\mac{drawcolor}[?\<model\>][\<colorspec\>]\\
\idx\mac{fillcolor}$\ldots$\\
\idx\mac{hatchcolor}$\ldots$\\
\idx\mac{headcolor}$\ldots$\\
\idx\mac{tlabelcolor}$\ldots$\\
\idx\mac{backgroundcolor}$\ldots$
\ecd

These macros set the default color (\MP{} only) for various drawing
elements. Any curve (with one exception, those drawn by
\mac{plotdata}), whether solid, dashed, dotted, or plotted in symbols,
will be in the color set by \mac{drawcolor}. Set the color used by
\mac{gfill} with \mac{fillcolor}. For all the hatching commands use
\mac{hatchcolor}, and for arrowheads, \mac{headcolor}. When
\opt{mplabels} is in effect, the color of labels can be set with
\mac{tlabelcolor}, and one can set the color used by \mac{gclear}
with \mac{backgroundcolor} (the same color is used in the interior of
unfilled points drawn with \mac{point}). The optional \<model\> may be one of
\opt{rgb}, \opt{RGB}, \opt{cmyk}, \opt{gray}, and \opt{named}. The
\<colorspec\> depends on the model, as outlined below. Each of these
commands sets a corresponding \MP{} color variable with the same name
(except \mac{backgroundcolor} sets the color \mfc{background}). Thus
one can set the filling color to the drawing color with
\mac{fillcolor}[drawcolor].

\subhead{\MP{} Colors.}

If the optional \<model\> specification is omitted, the color specification
may be any expression recognized as a color by \MP. In \MP, a color is a
triple of numbers like \mfc{(1,.5,.5)}, with the coordinates between 0
and 1, representing red, green and blue levels, respectively. White is
given by \mfc{(1,1,1)} and black by \mfc{(0,0,0)}. \MP{} also has color
variables and several have been predefined: \mfc{red}, \mfc{green},
\mfc{blue}, \mfc{yellow}, \mfc{cyan}, \mfc{magenta}, \mfc{white}, and
\mfc{black}. All the names in the \LaTeX{} \prog{color} package's
\file{dvipsnam.def} are predefined color variable names. Since \MP{}
allows color expressions, colors may be added and multiplied by
numerics. Moreover, several color functions have been defined:

\bcd
\idx\mfc{cmyk($c$,$m$,$y$,$k$)}
\ecd

Converts a \opt{cmyk} color specification to \MP's native \opt{rgb}. For
example, the command \mfc{cmyk(1,0,0,0)} yields \mfc{(0,1,1)}, which is
the definition of \mfc{cyan}.

\bcd
\idx\mfc{RGB($R$,$G$,$B$)}
\ecd

Converts an \opt{RGB} color specification to \opt{rgb}. It essentially
just divides each component by 255.

\bcd
\idx\mfc{gray($g$)}
\ecd

Converts a \opt{gray} level to a multiple of \mfc{(1,1,1)}.

\bcd
\idx\mfc{named(\<name\>)}, \mfc{rgb($r$,$g$,$b$)}
\ecd

These are essentially no-ops. However; \mfc{rgb} will truncate the
arguments to the 0--1 range,  an unknown \<name\> is converted to
\mfc{black}, and an unknown numeric argument is set to 0.

\vskip\myskip
As an example of the use of these functions, one could conceivable write:

\bex
\mac{drawcolor}[0.5*RGB(255,0,0)+0.5*cmyk(1,0,0,0)]
\eex

to have all curves drawn in a color halfway between red and cyan (which
turns out to be a dark gray).

\subhead{Color Models.}

When the optional \<model\> is specified in the color setting commands,
it determines the format of the color specification:

\vskip\myskip
\halign{\quad#\hfil\quad&#\hfil\cr
{\sl Model:}& {\sl Specification:}\cr
\opt{rgb}&  Three numbers in the range 0 to 1 separated by commas.\cr
\opt{RGB}&  Three numbers in the range 0 to 255 separated by commas.\cr
\opt{cmyk}& Four numbers in the range 0 to 1 separated by commas.\cr
\opt{gray}& One number in the range 0 to 1, with 1 indicating
                  white, 0 black.\cr
\opt{named}& A \MP{} color variable name either predefined by
                   \prog{mfpic} or by the user.\cr}

\vskip\myskip
Example: \mac{fillcolor}[?cmyk][1,.3,0,.2] and
\mac{fillcolor}[cmyk(1,.3,0,.2)] are essentially equivalent. Note that
when the optional model is specified, the color specification must
not be enclosed in parentheses. Note also that each model name is
the name of a color function described in the previous subsection. That
is how the models are implemented internally.


\subhead{Defining a Color Name.}

\bcd
\idx\mac{mfpdefinecolor}[\<name\>][\<model\>][\<colorspec\>]
\ecd

This defines a color variable \<name\> for later use, either in the
commands \mac{drawcolor}, etc., or in the optional parameters to
\mac{draw}, etc. The name can be used alone or in the \opt{named}
model. The mandatory \<model\> and \<colorspec\> are as above.

\vskip\myskip
A final caution, the colors of an \prog{mfpic} figure are stored in the
\file{.mp} output file, and are not related to colors used or defined by
the \LaTeX{} \prog{color} package. In particular a color defined only by
\LaTeX's \mac{definecolor} command will remain unknown to \prog{mfpic}.
Conversely, LaTeX{} commands will not recognize any color defined only
by \mac{mfpdefinecolor}.

\head {Shape-Modifier Macros.}

Some \prog {mfpic} macros operate as \emph{shape-modifier} macros---for
example, if you want to put an arrowhead on a line segment, you could
write: \mac{arrow}\mac{lines}[(0,0),(1,0)]. These are always
prefixed to some figure drawing command, and apply only to the next
following figure macro (which can be rather far removed) provided that
only other prefix commands intervene. This is a rather long section, but
even more modification prefixes are documented in subsection
{\shf Transformation of Paths\/} of section {\hf Affine Transforms}.

In the \PS{} context (i.e., \MP) it is important to note that each prefix
modifies the result of the entire following sequence. In essence
prefixes can be viewed as being applied in the opposite order to their
occurrence. Example:

\bex
\mac{dashed}\mac{gfill}\mac{rect}[(0,0),(1,1)]
\eex

This adds the dashed outline to the filled rectangle. That is, first the
rectangle is defined, then it is filled, then the outline is drawn in
dashed lines. This makes a difference when colors other than black are
used. Drawing is done with the center of the virtual pen stroked down
the middle of the boundary, so half of its width falls inside the
rectangle. On the other hand, filling is done right up to the boundary.
In this example, the dashed lines are drawn on top of part of the fill.
In the reverse order, the fill would cover part of the outline.

For the purposes of these macros, a distinction must be made in the
figure macros between ``open'' and ``closed'' paths. A path that merely
returns to its starting point is \emph{not} automatically closed; such a
path is open, and must be explicitly closed, for example by
\mac{lclosed} (see below). (On the \MF{} level, path closure is achieved
by some variant of \mfc{ ..cycle}). The (already) closed paths are:
\mac{rect}, \mac{circle}, \mac{ellipse}, \mac{sector}, \mac{cyclic},
\mac{polygon}, \mac{plrregion}, \mac{chartbar}, \mac{piewedge},
\mac{tlabelrect}, \mac{tlabeloval}, \mac{tlabelellipse},
\mac{tlabelcircle} and \mac{btwnfcn} (below).


\subhead{Closure of Paths.}

\bcd
\idx\mac{lclosed}$\ldots$
\ecd

Makes each open path into a closed path by adding a line
segment between the endpoints of the path.

\bcd
\idx\mac{bclosed}$\ldots$\\
\idx\mac{cbclosed}$\ldots$
\ecd

These macros are similar to \mac{lclosed}, except that they close
each open path by drawing a B\'ezier, or a cubic B-spline,
respectively, between the path's endpoints.

\bcd
\idx\mac{sclosed}$\ldots$\\
\idx\mac{uclosed}$\ldots$
\ecd

These allow \MF{} to choose its notion of the best smooth curve.
The former allows the entire new curve to be redrawn.
\mac{sclosed}\mac{curve} is more or less equivalent to
\mac{cyclic} and closing a curve can cause \MF{} to rethink how the
original was drawn. The command \mac{uclosed} allows \MF{} to select
the closure (subject to smoothness), but prevents it from changing the
original curve.

\subhead{Reversal and Connection of Paths.}

\bcd
\idx\mac{reverse}$\ldots$
\ecd

Turns a path around, reversing its orientation.
This will affect both the direction of arrows
(e.g. bi-directional arrows can be coded with
\mac{arrow}\mac{reverse}\mac{arrow}$\ldots$ ---here the first
\mac{arrow} modifier applies to the \emph{reversed} path),
and the order of endpoints for a
\mac{connect}$\ldots$\mac{endconnect} environment (below).


\bcd
\idx\mac{connect} $\ldots$ \idx\mac{endconnect}
\ecd

This pair of macros, acting as an environment, add line segments from
the trailing endpoint of one open path to the leading endpoint of the
next path, in the given order. The result is a connected, \emph{open}
path.

\emph{Note}: In \LaTeX, this pair of macros can be used in the form of
a \LaTeX-style environment called \env{connect} ---as in
\mac{begin}[connect]$\ldots$\mac{end}[connect].


\subhead{Drawing.}

When \prog{mfpic} is loaded, the initial way in which figures are drawn
is with a solid outline. That is, \mac{lines}[(1,0),(1,1),(0,0)] will
draw two solid lines connecting the points. When the macros in this
section are used, any previously established default (see {\shf Changing
the Default Rendering\/} of section {\hf Shape-Modifier Macros\/}) is
overridden.

\bcd
\idx\mac{draw}[?\<color\>]$\ldots$
\ecd

Draws the subsequent path using a solid outline.
For an example: to both draw a curve and hatch its
interior, \mac{draw}\mac{hatch} must be used. Default for \<color\> is
\idx\gbc{drawcolor}.

\bcd
\idx\mac{dashed}[?\<length\>,\<space\>]$\ldots$
\ecd

Draws dashed segments along the path specified in the next command. The
default length of the dashes is the value of the \TeX{} dimension \mac
{dashlen}, initially \dim{4pt}. The default space between the dashes is
the value of the \TeX{} dimension \mac{dashspace}, initially
\dim{4pt}. The dashes and the spaces between may be increased or
decreased by as much as ${1\over n}$ of their value, where $n$ is the number
of spaces appearing in the curve, in order to have the proper dashes at
the ends. The dashes at the ends are half of \mac{dashlen} long.

\bcd
\idx\mac{dotted}[?\<size\>,\<space\>]$\ldots$
\ecd

Draws dots along the specified path. The default size of the dots is the
value of the \TeX{} dimension \mac{dotsize}, initially \dim{0.5pt}.
The default space between the dots is the value of the \TeX{} dimension
\mac{dotspace}, initially \dim{3pt}. The size of the spaces may be
adjusted as in \mac{dashed}.

\bcd
\idx\mac{plot}[?\<size\>,\<space\>][\<symbol\>]$\ldots$
\ecd

Similar to \mac{dotted} except copies of  \<symbol\> are drawn along the
path. Possible symbols are those listed under \mac{plotsymbol} above.
The default \<size\> is \mac{pointsize} and the default \<space\> is
\mac{symbolspace}, initially \dim{5pt}.

\bcd
\idx\mac{plotnodes}[?\<size\>][\<symbol\>]
\ecd

This places a symbol (same possibilities as in \mac{plotsymbol}) at
each node of the path that follows. A node is one of the points through
which \MF{} draws its curve.  If one of the macros
\mac{polyline}[$\ldots$] or \mac{curve}[$\ldots$] follows, each of
the points listed is a node. In the \mac{datafile} command (below),
each of the data points in the file is. In the function macros (below)
the points corresponding to \<min\>, \<max\> and each step in between
are nodes. The optional \<size\> defaults to \mac{pointsize}.


\bcd
\idx\mac{dashpattern}[\<name\>][\<len1\>,\<len2\>,$\ldots$,\<len2k\>]
\ecd

For more general dash patterns than \mac{dashed} and \mac{dotted}
provide, there is a generalized dashing command. One must first
establish a named dashing pattern with this command. \<name\> should be
a legal \MF{} variable name. (Any sequence of letters and underscores
will work.) Try to make it distinctive to avoid undoing some internal
variable. \<len1\> through \<len2k\> are an even number of lengths. The
odd ones determine the lengths of dashes, the even ones the lengths of
spaces. A dash of length {\tt 0pt} means a dot. An alternating dot-dash
pattern can be specified with
\bex
\mac{dashpattern}[dotdash][0pt,4pt,3pt,4pt].
\eex

\emph{Note}: Since pens have some thickness, dashes look a little
longer, and spaces a little shorter, than the numbers suggest. It seems
to my eyes better if one increases the specified spaces (and decreases
the specified dashes) by the thickness of the drawing pen (normally
\dim{0.5pt}).

\bcd
\idx\mac{gendashed}[\<name\>]$\ldots$
\ecd
Once a dashing pattern name has been defined, it can be used in this
command to draw the curve that follows it. Using a name not previously
assigned will generate a \MF{} error, but \TeX{} will not complain. If
all the dimensions in a dashpattern are 0, \mac{gendashed} responds by
drawing a solid curve. The same is true if the pattern has only one
entry. If the pattern has an odd number of entries, the last one is
ignored.

\subhead{Arrows.}

\bcd
\idx\mac{arrow}[?l\<headlen\>][?r\<rotate\>][?b\<backset\>][?c\<color\>]$\ldots$
\ecd

Draws an arrowhead at the endpoint of the open path (or at the last key
point of the closed path) that follows. The optional parameter
\<headlen\> determines the length of the arrowhead.  The default is the
value of the \TeX{} dimension \mac{headlen}, initially \dim{3pt}. The
optional parameter \<rotate\> allows the arrowhead to be rotated
counterclockwise around its point an angle of \<rotate\> degrees. The
default is 0. The optional parameter \<backset\> allows the
arrowhead to be ``set back'' from its original point, thus allowing
e.g. double arrowheads. This parameter is in the form of a \TeX{}
dimension---its default value is \dim{0pt}. If an arrowhead is both
rotated and set back, the rotation affects the direction in which the
arrowhead is set back. The optional \<color\> defaults to
\idx\gbc{headcolor}. The optional parameters may appear in any order,
but the indicated key character for each parameter must always appear.


\subhead{Shading, Filling, Erasing, Clipping, Hatching.}

These macros can all be used to fill (or unfill) the interior of closed
paths, even if the paths cross themselves. Filling an open curve is
technically an error, but the code in \file {grafbase} responds by
drawing the path and not doing any filling. These macros replace the
default rendering, that is, when they are used the outline will not be
drawn unless an explicit prefix to do so is present.

\bcd
\idx\mac{gfill}[?\<color\>]$\ldots$
\ecd

Fills in the subsequent closed path. Under \MP{} it fills with \<color\>,
which defaults to \idx\gbc{fillcolor}.

\bcd
\idx\mac{gclear}$\ldots$
\ecd

Erases everything \emph{inside} the subsequent closed path. Under \MP{} it
actually fills with the predefined color \mfc{background}. Since
\mfc{background} is normally white and so are most actual backgrounds,
this is usually indistinguishable from clearing.

\bcd
\idx\mac{gclip}$\ldots$
\ecd

Erases everything \emph{outside} the subsequent closed path from the
picture. Both \mac{gclear} and \mac{gclip} will affect previously placed
tlabels if \opt{mplabels} is in effect.

\bcd
\idx\mac{shade}[?\<shadesp\>]$\ldots$
\ecd

Shades the interior of the subsequent closed path with dots. The
diameter of the dots is the \MF{} variable \mfc{shadewd}, set by the
macro \mac{shadewd}[\<size\>]. Normally this is \dim{0.5pt}. The
optional argument specifies the spacing between (the centers of) the
dots, which defaults to the \TeX{} dimension \mac{shadespace}, initially
\dim{1pt}. If \mac{shadespace} is less than \mfc{shadewd}, the closed
path is filled with black, as if with \mac{gfill}. Under \MP{} this
macro actually fills the path's interior with a shade of gray. The
shade to use is computed based on \mac{shadespace} and
\mfc{shadewd}. The default values of these parameters correspond to a
gray level of 75\% of white.%
\footnote{$^*$}{If \mac{shadewd} is $w$ and \mac{shadespace} is $s$, then
the level of gray is $1 - (w/s)^2$, where $0$ denotes black and $1$
white.}
The \MF{} version attempts to optimize the dots to the pixel grid
corresponding to the printers resolution (to avoid generating ``dither
lines''). Because this involves rounding, it will happen that values
of \mac{shadespace} that are relatively close and at the same time close to
\mfc{shadewd} produce exactly the same shade. By bad luck, when
\mfc{shadewd} is the default \dim{0.5pt}, and the printer resolution is
300dpi, values of \mac{shadespace} between \dim{.69pt} and \dim{1pt}
create the same shading pattern. Most of the time, however, values which
differ by at least 20\% will produce different patterns.

\bcd
\idx\mac{polkadot}[?\<space\>]$\ldots$
\ecd

Fills the interior of a closed path with large dots. This is almost what
\mac{shade} does, but there are several differences. \mac{shade} is
intended solely to simulate a gray fill in \MF{} where the only color is
black. So it is optimized for small dots aligned to the pixel grid (in
\MF). In \MP{} all it does is fill with gray and is intended merely for
compatibility. The macro \mac{polkadot} is intended for large dots in
any color, and so it optimizes spacing (a nice hexagonal array) and
makes no attempt to align at the pixel level. The \<space\> defaults to
the \TeX{} dimension \mac{polkadotspace}, initially \dim{10pt}. The
diameter of the dots is the value of the \MF{} variable \mfc{polkadotwd},
which can be set with \mac{polkadotwd}[\<size\>], and is initially
\dim{5pt}. The dots are colored with \idx\gbc{fillcolor}.

\bcd
\idx\mac{thatch}[?\<hatchsp\>,\<angle\>][?\<color\>]$\ldots$
\ecd

Fills a closed path with equally spaced parallel lines at the specified
angle. The thickness of the lines is set by the macro \mac{hatchwd}.
In the optional argument, \<hatchsp\> specifies the space between lines,
which defaults to the \TeX{} dimension \mac{hatchspace}, initially
\dim{3pt}. The \<angle\> defaults to 0. The \<color\> defaults to
\idx\gbc{hatchcolor}. If \mac{hatchspace} is \dim{0pt} (or less), the
closed path is filled with \<color\>, as if with \mac{gfill}. Of the
first optional arguments, either both must be present, or both must be
absent. For the color argument to be present, the other optional
arguments must also be present.

\bcd
\idx\mac{lhatch}[?\<hatchsp\>][?\<color\>]$\ldots$
\ecd

Draws lines shading in the subsequent closed path in a ``left-oblique
hatched'' (upper left to lower right) pattern. It is exactly the same as
\mac{thatch}[?\<hatchsp\>,-45][?\<color\>]$\ldots$

\bcd
\idx\mac{rhatch}[?\<hatchsp\>][?\<color\>]$\ldots$
\ecd

Draws lines shading in the subsequent closed path in a ``right-oblique
hatched'' (lower left to upper right) pattern. It is exactly the same as
\mac{thatch}[?\<hatchsp\>,45][?\<color\>]$\ldots$

\bcd
\idx\mac{hatch}[?\<hatchsp\>][?\<color\>]$\ldots$\\
\idx\mac{xhatch}[?\<hatchsp\>][?\<color\>]$\ldots$
\ecd

Draws lines shading in the subsequent closed path in a ``cross-hatched''
pattern. It is exactly the same as \mac{rhatch} followed by
\mac{lhatch} using the same \<hatchsp\> and \<color\>.


\subhead{Changing the Default Rendering.}

\emph{Rendering} is the process of converting a geometric description
into a drawing.  In \MF{}, this means producing a bitmap (\MF{} calls
this a \mfc{picture}), either by stroking (drawing) a path using a
particular pen), or by filling a closed path. In \MP{} it means producing
a \PS{} description of strokes with pens, and fills

\bcd
\idx\mac{setrender}[\<\TeX{} commands\>]
\ecd

Initially, \prog {mfpic} uses the \mac{draw} command (stroking) as the
default operation when a figure is to be rendered.  However, this can be
changed to any combination of \prog{mfpic} rendering commands and/or
other \TeX{} commands, by using the \mac{setrender} command.  This is a
local redefinition, so it can be enclosed in braces to restrict its
range.

For example, after \mac{setrender}[\bsl dashed\bsl shade] the command
\mac{circle}[(0,0),1] produces a shaded circle with a dashed
outline. Any explicit drawing or filling prefix replaces this default.
Other kinds of prefixes (e.g., \mac{lclosed}, \mac{arrow},
\mac{rotatepath}) do not.

\subhead{Examples.}

It may be instructive, for the purpose of seeing how the syntax of
\emph{shape-modifier switches} works, to consider two examples:

\bex
\mac{draw}\mac{shade}\mac{lclosed}\mac{lines}[...]
\eex

which shades inside a polygon and draws its outline; and

\bex
\mac{shade}\mac{lclosed}\mac{draw}\mac{lines}[...]
\eex

which draws all of the outline \emph{except} the line segment supplied
by \mac{lclosed}, then shades the interior. And in \MP{} this is just
a gray fill which covers the inner half of the stroke made by
\mac{draw}.



\head {Functions and Plotting.}

In the following macros, expressions like $f({\tt x})$, $g({\tt t})$
stand for any legal \MF{} expression, in which the only unknown
variables are those indicated ({\tt x} in the first case, and
{\tt t} in the second).

\subhead{Defining Functions}

\bcd
\idx\mac{fdef}[\<fcn\>][\<param1\>,\<param2\>,$\ldots$][\<mf-expr\>]
\ecd

Defines a \MF{} function \<fcn\> of the parameters
\<param1\>, \<param2\>, $\ldots$, by the \MF{} expression \<mf-expr\>
in which the only free parameters are those named.  The return type of
the function is the same as the type of the expression. The function
name \<fcn\> is subject to \MF's rule for variable names. Try to make
the names distinctive to avoid redefining internal \MF{} commands.

The expression \<mf-expr\> is passed directly into the corresponding
\MF{} macro and interpreted there, so \MF's rules for algebraic
expressions apply.

As an example, after \mac{fdef}[myfcn][s,t][s*t-t], any place below
where a \MF{} expression is required, you can use \mfc{myfcn(2,3)} to mean
\mfc{2*3-3} and \mfc{myfcn(x,x)} to mean \mfc{x*x-x}.

Operations available include \mfc{+}, \mfc{-}, \mfc{*}, \mfc{/}, and
\mfc{**} (\mfc{x**y}$=x^y$), with \mfc{(} and \mfc{)} for grouping.
Functions already available include the standard \MF{} functions
\mfc{round}, \mfc{floor}, \mfc{ceiling}, \mfc{abs}, \mfc{sqrt},
\mfc{sind}, \mfc{cosd}, \mfc{mlog}, and \mfc{mexp}. Note that in \MF{}
the operations \mfc{*} and \mfc{**} have the same level of precedence,
so \mfc{x*y**z} means $(xy)^z$. Use parentheses liberally!

({\it Notes:} The \MF{} trigonometric functions \mfc{sind} and
\mfc{cosd} take arguments in degrees; \mfc{mlog(x)}$=256\ln x$, and
\mfc{mexp} is its inverse.) You can also define the function \<fcn\> by
cases, using the \MF{} conditional expression

\bex
\mfc{if~\<boolean\>:~\<expr\>~elseif \<boolean\>:~$\ldots$~else:~\<expr\>~fi}.
\eex

Relations available for the \<boolean\> part of the expression include
\mfc{=}, \mfc{<}, \mfc{>}, \mfc{<=}, \mfc{<>} and \mfc{>=}.

Complicated functions can be defined by a compound expression, which is
a series of \MF{} statements, followed by an expression, all enclosed in
the \MF{} commands \mfc{begingroup} and \mfc{endgroup}. \MF{} functions
can call \MF{} functions, recursively.

Many common functions have been predefined in \file{grafbase}. These
include all the usual trig functions \mfc{tand}, \mfc{cotd}, \mfc{secd},
\mfc{cscd}, which take angles in degrees, plus variants \mfc{sin},
\mfc{cos}, \mfc{tan}, \mfc{cot}, \mfc{sec}, and \mfc{csc}, which take
angles in radians. Some inverse trig functions are also available, the
following produce angles in degrees: \mfc{asin}, \mfc{acos}, and
\mfc{atan}, and the following in radians: \mfc{invsin}, \mfc{invcos},
\mfc{invtan}. The exponential and hyperbolic functions: \mfc{exp},
\mfc{sinh}, \mfc{cosh}, \mfc{tanh}, and their inverses \mfc{ln} (or
\mfc{log}), \mfc{asinh}, \mfc{acosh}, and \mfc{atanh} are also defined.

\subhead{Plotting Functions}

The plotting macros take two or more arguments. They have an optional
first argument, \<spec\>, which determines whether a function is drawn
smooth (as a \MF{} B\'ezier curve), or polygonal (as line segments)---if
\<spec\> is {\tt p}, the function will be polygonal. Otherwise the
\<spec\> should be {\tt s}, followed by an optional positive number no
smaller than 0.75. In this case the function will be smooth with a
tension equal to the number. See the \mac{curve} command for an
explanation of tension. The default \<spec\> depends on the purpose of
the macro.

One compulsory argument contains three values \<min\>, \<max\> and
\<step\> separated by commas.  The independent variable of a function
starts at the value \<min\> and steps by \<step\> until reaching
\<max\>. If \<max\>${}-{}$\<min\> is not a whole number of steps, then
round$((\<max\>-\<min\>)/\<step\>)$ equal steps are used. One may have
to experiment with the size of \<step\>, since \MF{} merely connects the
points corresponding to these steps with what \emph{it} considers to be
a smooth curve. Smaller \<step\> gives better accuracy, but too small
may cause the curve to exceed \MF's capacity or slow down its
processing. Increasing the tension may help keep the curve in line, but
at the expense of reduced smoothness.

There are one or more subsequent arguments, each of which is a \MF{}
function or expression as described above.

\bcd
\idx\mac{function}[?\<spec\>][\<xmin\>,\<xmax\>,\<step\>][$f({\tt x})$]
\ecd

Plots $f({\tt x})$, a \MF{} numeric function or expression of one numeric
argument, which must be denoted by a literal {\tt x}. The default
\<spec\> is {\tt s}.

\bcd
\idx\mac{parafcn}[?\<spec\>][\<tmin\>,\<tmax\>,\<step\>][\<pfcn\>]
\ecd

Plots the parametric path determined by $(x(t),y(t)) =
${\tt \<pfcn\>$({\tt t})$}, where \<pfcn\> is a \MF{} function or
expression of one numeric argument {\tt t}, returning a \MF{} \emph{pair}
(such as $(x,y)$). Or a pair of numeric expressions enclosed in
parentheses and separated by a comma. The default \<spec\> is {\tt s}.
Example: \mac{parafcn}[ 0,1,.1][2*(t,t*t)] plots a smooth parabola
from $(0,0)$ to $(2,2)$.

\bcd
\idx\mac{plrfcn}[?\<spec\>][\<\TH{min}\>,\<\TH{max}\>,\<\TH{step}\>][$f({\tt t})$]
\ecd

Plots the polar function determined by $r=f(\theta)$, where $f$ is a
\MF{} numeric function or expression of one numeric argument, and
$\theta$ varies from \<\TH{min}\> to \<\TH{max}\> in steps of
\<\TH{step}\>. Each $\theta$ value is interpreted as an angle measured
in \emph{degrees}. In the expression $f({\tt t})$, the unknown {\tt t}
stands for $\theta$. The default \<spec\> is {\tt s}.

\bcd
\idx\mac{btwnfcn}[?\<spec\>][\<xmin\>,\<xmax\>,\<step\>]%
    [$f({\tt x})$][$g({\tt x})$]
\ecd

Draws the region between the two functions $f(x)$ and $g(x)$, these
being numeric functions of one numeric argument {\tt x}. The region is
bounded also by the vertical lines at \<xmin\> and \<xmax\>. Unlike the
previous function macros, the default \<spec\> is {\tt p} ---this macro
is intended to be used for shading between drawn functions, a task for
which smoothness is usually unnecessary.

\bcd
\idx\mac{plrregion}[?\<spec\>]%
    [\<\TH{min}\>,\<\TH{max}\>,\<\TH{step}\>][$f({\tt t})$]
\ecd

Plots the polar region determined by $r=f(\theta)$, where $f$ is a \MF{}
numeric function of one numeric argument {\tt t}.  The $\theta$ values
are angles (measured in \emph{degrees}), varying from \<\TH{min}\> to
\<\TH{max}\> in steps of \<\TH{step}\>. In the expression $f({\tt t})$,
the {\tt t} stands for $\theta$. The region is also bounded by the
angles \<\TH{min}\> and \<\TH{max}\>, i.e. by the line segments joining
the origin to the endpoints of the function. The default \<spec\> is
{\tt p} ---this macro is intended to be used for shading a region with
the boundary drawn, a task for which smoothness is usually unnecessary.


\subhead{Plotting external data files}

\bcd
\idx\mac{datafile}[?\<spec\>][\<file\>]\\
\idx\mac{smoothdata}[?\<tension\>]\\
\idx\mac{unsmoothdata}
\ecd

\mac{datafile} defines a curve connecting the points listed in the file
\<file\>. The \<spec\> may be either {\tt p} or {\tt s} followed by a
tension value (as in \mac{curve}). If no \<spec\> is given, the default
is initially {\tt p}, but \mac{smoothdata} may be used to change this.
That is, after \mac{smoothdata}[?\<tension\>] the default \<spec\> is
changed to {\tt s\<tension\>}. If the tension parameter is not supplied
it defaults to \mfc{1.0}. The command \mac{unsmoothdata} restores the
default \<spec\> to {\tt p}.

By default, each non-blank line in the file is assumed to contain at
least two numbers, separated by whitespace (blanks or tabs). The first
two numbers on each line are assumed to represent the $x$- and
$y$-coordinates of a point. Initial blank lines in the file are ignored,
as are comments. The comment character in the data file is assumed to be
{\tt \%}, but it can be reset using \mac{mfpdatacomment} (below). Any
blank line other than at the start of the file causes the curve to
terminate. The \mac{datafile} command may be preceded by any of the
prefix commands, so that, for example, a closed curve could be formed
with \mac{lclosed}\mac{datafile}[data.dat].

The \mac{datafile} command has a second, independent use. Any
\prog{mfpic} command (other than one that prints text labels) that takes
as its last argument a list of points (or numerical values), separated
by commas, can now have that list replaced by values in an external data
file. For example, if a file \file{numlist.dat} contains one or more
numerical value per line separated by blanks, then

\bex
\mac{using}[\#1 \#2][\#1]\\
\mac{xmarks}\mac{datafile}[numlist.dat]
\eex

can be used to put hash marks on the $x$-axis at each of the points
corresponding to the first number on each line. This \mac{using} command
tells \mac{mfpic} to discard all but the first number on each line and
include that number in the list. The \prog{mfpic} macros that allow this
usage of \mac{datafile} are, for numeric data: \mac{piechart},
\mac{barchart} , and all the axis marks commands; for
point or vector data: \mac{point}, \mac{plotsymbol}, \mac{polyline},
\mac{polygon}, \mac{fcncurve}, \mac{curve}, \mac{cyclic}, \mac{turtle},
\mac{qspline}, \mac{closedqspline}, \mac{cspline}, and
\mac{closedcspline}.


The \mac{datafile} drawing command described above produces the
equivalent of using \mac{polyline}\mac{datafile} or of
\mac{curve}[?\<tension\>]\mac{datafile} if
\mac{smoothdata}[?\<tension\>] has been used.

\bcd
\idx\mac{mfpdatacomment}{\tt\bsl\<char\>}
\ecd

Changes \<char\> to a comment character and changes the usual \TeX{}
comment character {\tt\%} to an ordinary character {\it while reading a
datafile for drawing}.

\bcd
\idx\mac{using}[\<in-pattern\>][\<out-pattern\>]
\ecd

Used to change the assumptions about the format of the data file. For
example, if there are four numbers on each line separated by commas, to
plot the third against the second (in that order) you can say
\mac{using}[\#1,\#2,\#3,\#4][(\#3,\#2)]. This means the following:
Everything on a line up to the first comma is assigned to parameter {\tt
\#1}, everything from there up to the second comma is assigned to
parameter {\tt\#2}, etc. Everything from the third comma to the end of
line is assigned to {\tt\#4}. When the line is processed by \TeX{} a
\MF{} pair is produced representing a point on the curve. \MF{} pair
expressions can be used in the output portion of \mac{using}. For
example \mac{using}[\#1,\#2,\#3][(\#2,\#1)/10] or even
\mac{using}[\#1,\#2,\#3][polar(\#2,\#1)] if the data are polar
coordinates. As a special case, you can plot any number against its
sequence position, with something like \mac{using}[\#1,\#2,\#3][(\bsl
sequence,\#1)]. Here, the macro \mac{sequence} will take on the values
{\tt 1}, {\tt 2}, etc. as lines are read from the file.  The default
setting is \mac{using}[\#1 \#2 \#3][(\#1,\#2)]. \prog{mfpic} provides
the command \mac{usingpairdefault} to reset this default. It also
provides the command \mac{usingnumericdefault} as the equivalent of
\mac{using}[\#1 \#2][\#1] (seen above in the \mac{xmarks}\mac{datafile}
example). The \mac{using} command cannot normally be used in the
replacement text of another command.

Note that the default value of \mac{using} appears to reference three
arguments. If there are only two numbers on a line separated by
whitespace, this will still work because of \TeX's argument matching
rules. \TeX's file reading mechanism normally converts the EOL to a
space, but there are exceptions so \prog{mfpic} always adds a space at
the end of each line read in to be on the safe side. Then the default
definition of \mac{using} reads everything up to the first space as
{\tt\#1} (whitespace is normally compressed to a single space by \TeX's
reading mechanism), then everything to the second space (the one added
at the end of the line, perhaps) is {\tt\#2}, then everything to the EOL
is {\tt\#3}. This might assign an empty argument to {\tt\#3}, but it is
discarded anyway.

If the numerical data contain percentages with explicit {\tt\%} signs,
then choose another comment character with \mac{mfpdatacomment}. This
will change {\tt\%} to an ordinary character {\it in the data file}.
However, in your \mac{using} command it would still be read as a
comment. The following example shows how to overcome this:

\bex
\myverbatim;
\makepercentother
\using{#1% #2 #3}{(#1/100,#2)}
\makepercentcomment
@endmyverbatim
\eex

Here is an analysis of the meaning of this example: everything in a
line, up to the first percent followed by a space is assigned to
parameter {\tt \#1}, everything from there to the next space is assigned
to {\tt \#2} and the rest of the line (which may be empty) is {\tt\#3}.
On the output side in the above example, the percentage is divided by
100 to convert it to a fraction, and plotted against the second
parameter. Note: normal comments should not be used between
\mac{makepercentother} and \mac{makepercentcomment}, for obvious
reasons.

\bcd
\idx\mac{plotdata}[?\<spec\>][\<file\>]
\ecd

This plots several curves from a single file. The \<spec\> and the
command \mac{smoothdata} have the same effect on each curve as in the
\mac{datafile} command. The data for each curve is a succession of
nonblank lines separated from the data for the next curve by a single
blank line. A \emph{pair} of successive blank lines is treated as the
end of the data. No prefix macros are permitted in front of
\mac{plotdata}.

Each successive curve in the data file is drawn differently. By default,
the first is drawn as a solid line the next dashed, the third dotted,
etc., through a total of six different line types. A \mac{gendashed}
command is used with predefined dashpatterns named \mfc{dashtype0}
through \mfc{dashtype5}. This behavior can be changed with:

\bcd
\idx\mac{coloredlines}\\
\idx\mac{pointedlines}\\
\idx\mac{datapointsonly}\\
\idx\mac{dashedlines}
\ecd

The command \mac{coloredlines} changes to cycling through eight
different colors (starting with black). This has an effect only for \MP.
The command \mac{pointedlines} causes \mac{plotdata} to use
\mac{plot}[\<symbol\>] commands, cycling through nine different symbols.
The command \mac{datapointsonly} causes \mac{plotdata} to use
\mac{plotnodes}[\<symbol\>] commands to plot the data points only. (See
the {\bf Appendix} for more details.) The command \mac{dashedlines}
restores the default. If, for some reason, you do not like the default
starting line style (say you want to start with a color other than
black), you can use one of the following commands.

\bcd
\idx\mac{mfplinetype}[\<num\>], or\\
\idx\mac{mfplinestyle}[\<num\>]
\ecd

Here \<num\> is a non-negative number, less than the number of different
drawing types available. The four previous commands reset the number to
0, so if you use one of them, issue \mac{mfplinetype} \emph{after} it.
The different line styles are numbered starting from $0$. If two or more
\mac{plotdata} commands are used in the same \env{mfpic} environment,
the numbering in each continues where the one before left off (unless
you issue one of the commands above in between). \mac{mfplinestyle}
means the same as \mac{mfplinetype}, and is included for compatibility.
See the {\bf Appendix} to find out what dashpattern, color or symbol
corresponds to each number.

The sole exception to the general rule that all curves are drawn in
\idx\gbc{drawcolor} is the \mac{plotdata} command after
\mac{coloredlines} has been issued.

The commands \mac{using}, \mac{mfpdatacomment} and \mac{sequence} have
the same meaning for \mac{plotdata} as they do for \mac{datafile}
(above). The sequence numbering for \mac{sequence} starts over with each
new curve.

\head {Labels and Captions.}

\subhead{Setting Text.}

The macros \mac{tlabel}, \mac{tlabels}, \mac{axislabels} and
\mac{tcaption} do not affect the \MF{} file (\file {\<file\>.mf}) at
all, but are added to the picture by \TeX. If \opt{metapost} is in
effect but \opt{mplabels} is not, they do not affect the \MP{} file. In
these cases, if these macros are the only changes or additions to your
document, there is no need to repeat the processing with \MF{} or \MP{}
nor the reprocessing with \TeX{} in order to complete your \TeX{}
document.

\bcd
\idx\mac{tlabel}[?\<just\>]{\tt(\<x\>,\<y\>)\{\<label text\>\}}\\
\idx\mac{tlabels}[\<params$_1$\> \<params$_2$\> $\ldots$]
\ecd

Places \TeX{} labels on the graph. (Not to be confused with \LaTeX's
\mac{label} command.) The special form \mac{tlabels} (note the plural)
essentially just applies \mac{tlabel} to each set of parameters listed
in its argument. That is, each \<params$_k$\> is a valid set of parameters
for a \mac{tlabel} command. These can be separated by spaces, newlines,
or nothing at all.

The last required parameter is ordinary \TeX{} text. The pair
{\tt(\<x\>,\<y\>)} gives the coordinates of a point in the graph where
the text will be placed. It may optionally be enclosed in braces. In
fact, if \opt{mplabels} is in effect the syntax

\bcd
\idx\mac{tlabel}[?\<just\>][\<pair-list\>][\<label text\>]\\
\ecd

may be used, where \<pair-list\> is any expression recognized as a pair
by \MP, or a comma-separated list of such pairs.

The optional parameter {\tt [\<just\>]} specifies the
\emph{justification}, the relative placement of the label with respect
to the point {\tt (\<x\>,\<y\>)}. It is a two-character sequence where
the first character is one of {\tt t} (top), {\tt c} (center), {\tt b}
(bottom), or {\tt B} (Baseline), to specify vertical placement, and the
second character is one of {\tt l} (left), {\tt c} (center), or {\tt r}
(right), to specify horizontal placement. These letters specify what
part of the \emph{text} is to be placed at the given point, so {\tt r}
puts the right end of the text there---which means the text will be left
of the point.

When \opt{mplabels} is in effect, the two characters may optionally
be followed by a number, specifying an angle in degrees to rotate the
text about the point {\tt(\<x\>,\<y\>)}. If the angle is supplied
without \opt{mplabels} it is ignored after a warning. If the angle is
absent, there is no rotation. Note that the rotation takes place after
the placement. For example, {\tt [cr]} will place the text left of the
point, while {\tt [cr180]} will place the text right of the point (and
upsidedown, of course).

There should be no spaces before or between the first two characters.
However the number, if present, is only required to be a valid \MP{}
numerical expression containing no bracket characters; as such, it may
contain some spaces (e.g., around operations as in {\tt 45 + 30}).

A multiline \mac{tlabel} may be specified by explicit line breaks, which
are indicated by the {\bsl\bsl} command. This is a very rudimentary
feature. By default it left justifies the lines and causes \mac{tlabel}
to redefine \bsl\bsl{}. One can center a line by putting \mac{hfil} as
the first thing in the label text, and right justify by putting
\mac{hfill} there (these are \TeX{} primitives). Redefining
{\tt\bsl\bsl} can interfere with \LaTeX's definition. For better control
in \LaTeX{} use \mac{shortstack} inside the label (or a \env{tabular}
environment or some other environment which always initializes
\bsl\bsl{} with its own definition).

If the label goes beyond the bounds of the graph in any direction, the
box containing the graph is expanded to make room for it. (Note: in this
behavior it differs from the \LaTeX{} \env{picture} environment.)

If the \opt{mplabels} option is in effect, \mac{tlabel} will write a
\mfc{btex $\ldots$ etex} group to the output file, allowing \MP{} to
arrange for typesetting the label. In this case, the label is part of
the picture, rather than being laid on top of it. It may therefore be
covered up by \prog{mfpic} later filling macros, or clipped off by
\mac{gclear} or\mac{gclip}.

\bcd
\idx\mac{everytlabel}[\<\TeX-code\>]
\ecd

One problem with multi-line \mac{tlabel}s is that each line of their
contents constitutes a separate group. This makes it difficult to change
the \mac{baselineskip} (for example) inside a label. The command
\mac{everytlabel} saves it's contents in a token register and the code
is issued in each \mac{tlabel}, as the last thing before the actual
line(s) of text. Any switch you want to apply to every line can be
supplied. For example

\bex
\mac{everytlabel}[\bsl bf\bsl baselineskip 10pt]
\eex

will make every line of every \mac{tlabel}'s text come out bold with 10
point baselines. The effect of \mac{everytlabel} is local to the
\env{mfpic} environment, if it is issued inside one. Note that the lines
of a tlabel are wrapped in a box, but the commands of \mac{everytlabel}
are outside all of them, so no actual text should be produced by these
commands.

Using \mac{tlabel} without an optional argument is equivalent to
specifying {\tt [Bl]}. Use the following command to change this
behavior.

\bcd
\idx\mac{tlabeljustify}[\<just\>]
\ecd

After this command the placement of all subsequent labels without
optional argument will be as specified in this command. For example,
\mac{tlabeljustify}[cr45] would cause all subsequent \mac{tlabel}
commands lacking an optional argument to be placed as if the argument
{\tt[cr45]} were used in each.

\bcd
\idx\mac{tlabeloffset}[\<hlen\>][\<vlen\>]\\
\idx\mac{tlabelsep}[\<len\>]
\ecd

The first command causes all subsequent \mac{tlabel} commands to shift
the label right by \<hlen\> and up by \<vlen\> (negative lengths cause
it to be shifted left and down, respectively).

The \mac{tlabelsep} command causes labels to be shifted by the given
amount in a direction that depends on the optional positioning
parameter. For example, if the first letter is {\tt t} the label is
shifted down by the amount \<len\> and if the second letter is {\tt l}
it is also shifted right. In all cases it is shifted \emph{away} from
the point of placement (unless the dimension is negative). If {\tt c} or
{\tt B} is the first parameter, no vertical shift takes place, and if
{\tt c} is the second, there is no horizontal shift. This is intended to
be used in cases where something has been drawn at that particular
point, in order to separate the text from the drawing, but the value is
also written to the output file for use by \mac{tlabelrect} and related
commands.

\bcd
\idx\mac{axislabels}[\<axis\>][?\<just\>]%
    [\{\<txt$_1$\>\}\<$n_1$\>, \{\<txt$_2$\>\}\<$n_2$\>,$\ldots$>]
\ecd

This command places the given \TeX{} text (\<txt$_k$\>) at the given
positions (\<$n_k$\>) on the given axis, \<axis\>, which must be a
single letter and one of {\tt l}, {\tt b}, {\tt r}, {\tt t}, {\tt x}, or
{\tt y}. The text is placed as in \mac{tlabels} (including the taking
into account of \mac{tlabelsep} and \mac{tlableoffset}), except that the
default justification depends on the axis (the settings of
\mac{tlabeljustify} are ignored). In the case of the border axes, the
default is to place the label outside the axis and centered. So, for
example, for the bottom axis it is {\tt[tc]}. The defaults for the $x$-
and $y$-axis are below and left, respectively. The optional \<just\> can
be used to change this. For example, to place the labels \emph{inside}
the left border axis, use {\tt[cl]}. If \opt{mplabels} is in effect,
rotations can be included in the justification parameter. For example,
to place the text strings ``first'', ``second'' and ``third'' just below
the positions 1, 2 and 3 on the $x$-axis, rotated so they read upwards
at a 90 degree angle, one can use \mac{axislabels}[x][?cr90][\{first\}1,
\{second\}2, \{third\}3]

\bcd
\idx\mac{plottext}[?\<just\>][\<text\>][($x_0$,$y_0$),
 ($x_1$,$y_1$), $\ldots$]
\ecd

Similar in effect to \mac{point} and \mac{plotsymbol} (but without
requiring \MF), \mac{plottext} places a copy of \<text\> at each of the
listed points. It simply issues multiple \mac{tlabel} commands with the
same text and optional parameter, but at the different points listed.
This is intended to plot a set of points with a single letter or font
symbol (instead of a \MF{} generated shape).
Like \mac{axislabels}, this does not respond to the setting of
\mac{tlabeljustify}. It has a default setting of {\tt [cc]} if the
optional argument is omitted. The points may be MetaPost pair
expressions enclosed in braces under \opt{mplabels}. This command is
actually unnecessary under \opt{mplabels} as the plain \mac{tlabel}
command can then be given a list of points. The \mac{tlabel} command is
more efficient.

\bcd
\idx\mac{mfpverbtex}[\<\TeX-cmds\>]
\ecd

This writes a \mfc{verbatimtex} block to the \file{.mp} file. It makes
sense only if the \opt{mplabels} option is used and so only for \MP. The
\<\TeX-cmds\> in the argument are written to the \file{.mp} file,
preceded by the \MP{} command \mfc{verbatimtex} and followed by
\mfc{etex}. Line breaks within the \<\TeX-cmd\> are preserved. The
\mac{mfpverbtex} command must come before any \mac{tlabel} that is to be
affected by it. Any settings common to all \env{mfpic} environments
should be in a \mac{mfpverbtex} command preceding all such environments.
It may be issued at any point after \prog{mfpic} is loaded, and any
number of times. Because of the way \MP{} handles \mfc{verbatimtex}
material, the effects are not constrained by any grouping unless one
places grouping commands within \mfc{verbatimtex material}.

\bcd
\idx\mac{tcaption}[?\<maxwd\>,\<linewd\>][\<caption text\>]
\ecd

Places a \TeX{} caption at the bottom of the graph. (Not to be confused
with \LaTeX's similar \mac{caption} command.) The macro will
automatically break lines which are too much wider than the graph---if
the \mac{tcaption} line exceeds \<maxwd\> times the width of the graph, then
lines will be broken to form lines at most \<linewd\> times the width of
the graph. The default settings for \<maxwd\> and \<linewd\> are 1.2 and
1.0, respectively. \mac{tcaption} typesets its argument
twice (as does \LaTeX's \mac{caption}), the first time to test
its width, the second time for real. Therefore, the user is advised
\emph{not} to include any global assignments in the caption text.

If the \mac{tcaption} and graph have different widths, the two are centered
relative to each other. If the tcaption takes multiple lines, then the
lines are both left- and right-justified (except for the last line), but
the first line is not indented. If the option \opt{centeredcaptions} is
in effect, each line of the caption will be centered.

In a \mac{tcaption}, Explicit line breaks may be specified by using the
{\bsl\bsl} command.

Many \prog{mfpic} users find the \mac{tcaption} command too limiting
(one cannot, for example, place the caption to the side of the figure).
It is common to use some other method (such as \LaTeX's \mac{caption}
command in a \env{figure} environment). The dimensions
\mac{mfpicheight} and \mac{mfpicwidth} (see section {\hf Parameters\/}
below) might be a convenience for plain \TeX{} users who want to roll
their own caption macros.

\subhead{Curves Surrounding \mac{tlabel}s}

\bcd
\idx\mac{tlabelrect}[?\<rad\>]{\tt(\<x\>,\<y\>)\{\<text\>\}}\\
\mac{tlabelrect}[?\<rad\>][\<pair\>][\<text\>]
\ecd

Produces a closed rectangle containing the \emph{text-box} of \<text\>.
The text-box is here defined to be the bounding box of the text,
increased on all four sides by the value set with \mac{tlabelsep} (see
the section {\hf Labels and Captions}, above). This command places the
text centered at (\<x\>,\<y\>). Under \opt{mplabels}, a pair expression
in braces may be used to specify the point. This command may be preceded
by prefix macros (see the section {\hf Shape-Modifier Macros}, above).
The optional argument \<rad\> is a dimension, defaulting to \dim{0pt},
that produces rounded corners made from quarter-circles of the given
radius. If the corners are rounded, the sides are expanded slightly so
the resulting shape still encompasses the complete text-box. There are
no provisions for rotating the text, even if \opt{mplabels} is in
effect, nor will it do any justification except centering. There is a
``star form'' \mac{tlabelrect*} which produces the rectangle but omits
placing the text.

\bcd
\idx\mac{tlabeloval}[?\<mult\>]{\tt(\<x\>,\<y\>)\{\<text\>\}}\\
\mac{tlabeloval}[?\<mult\>][\<pair\>][\<text\>]
\ecd

Similar to \mac{tlabelrect}, except it draws an ellipse. The ellipse
is calculated to have the same ratio of width to height as the
\emph{text-box} (defined above), the optional \<mult\> is a multiplier
that increases or decreases this ratio. Values of \<mult\> larger than 1
increase the width and decrease the height. The ellipse is always sized
so that it passes through the four corners of the text box. There are no
provisions for rotating the text, even if \opt{mplabels} is in effect,
nor will it do any justification except centering. As with
\mac{tlabelrect}, there is a ``star form'' that omits the text.

\bcd
\idx\mac{tlabelellipse}[?\<ratio\>]{\tt(\<x\>,\<y\>)\{\<text\>\}}\\
\mac{tlabelellipse}[?\<ratio\>][\<pair\>][\<text\>]\\
\idx\mac{tlabelcircle}{\tt(\<x\>,\<y\>)}\{\<text\>\}\\
\mac{tlabelcircle}[\<pair\>][\<text\>]
\ecd

Draws the smallest ellipse centered at the point that encompasses the
\emph{text-box} (defined as above) and that has a ratio of width to
height equal to \<ratio\>; then places the given text centered at the
point. The default ratio is $1$, which produces a circle.
\mac{tlabelcircle} is the same as \mac{tlabelellipse}, and is
intended for use when no optional argument is given in order to describe
the shape being drawn. As with \mac{tlabelrect}, there is a ``star
form'' that omits the text.

In the above \mac{tlabel...} curves, the optional parameter should be
positive. If it is zero, all the curves silently revert to
\mac{tlabelrect}. If it is negative, it is silently accepted. In the
case of \mac{tlabelrect} this causes the corners to be concave and
reversed, a rather bizarre effect. In the other cases, there is no visible
effect, except the sense of the curve is reversed.

One can surround rotated text with one of these curves by the simple
expedient of using the transformation prefix \mac{rotatepath} (see the
section {\hf Transformation of Paths}, below) with the star form, and
then add the same text with a \mac{tlabel} command at the same point
with the same rotation.

\head {Saving and Reusing an \prog {mfpic} Picture.}

These commands have been changed from versions prior to 0.3.14 in order
to behave more like the \LaTeX's \mac{savebox}, and also to allow the
reuse of an allocated box. Past files that use \mac{savepic} will have
to be edited to add \mac{newsavepic} commands that allocate the \TeX{}
boxes.

\bcd
\idx\mac{newsavepic}[\<picname\>]\\
\idx\mac{savepic}[\<picname\>]\\
\idx\mac{usepic}[\<picname\>]
\ecd

\mac{newsavepic} allocates a box (like \LaTeX's \mac{newsavebox}) in
which to save a picture. As in \mac{newsavebox}, \<picname\> is a
control sequence. Example: \mac{newsavepic}[\mac{foo}].

\mac{savepic} saves the \emph{next} \mac{mfpic} picture in the named
box, which should have been previously allocated with \mac{newsavepic}.
(This command should not be used \emph{inside} an \env{mfpic}
environment.) The next picture will not be placed, but saved in the box
for later use. This is primarily intended as a convenience. One
\emph{could} use \mac{savebox}[\<picname\>][\<entire \env{mfpic}
environment\>], but \mac{savepic} avoids having to place the \env{mfpic}
environment in braces, and avoids one extra level of \TeX{} grouping. It
also avoids reading the entire \env{mfpic} environment as a parameter,
which would nullify \prog{mfpic}'s efforts to preserve line breaks in
parameters written to the \MF{} output file. If you repeat \mac{savepic}
with the same \<picname\>, the old contents are replaced with the next
picture.

\mac{usepic} copies the picture that had been saved in the named box.
This may be repeated as often as liked to create multiple copies of one
picture.


\head {Picture frames.}

When \TeX{} is run but before \MF{} or \MP{} has been run on the output
file, \prog{mfpic} detects that the \file{.tfm} file is missing or that
the first \MP{} figure file \file{\<file\>.1} is missing. In these
cases, the \env{mfpic} environment draws only a rectangular frame with
dimensions equal to the nominal size of the picture, containing the
figure name and number (and any \TeX{} labels). The command(s) used
internally to do this are made available to the user.

\bcd
\idx\mac{mfpframe}[?\<fsep\>]\< material-to-be-framed \>\idx\mac{endmfpframe}\\
\idx\mac{mfpframed}[?\<fsep\>][\<material-to-be-framed\>]
\ecd

These surround their contents with a rectangular frame consisting of lines
with thickness \mac{mfpframethickness} separated from the contents by
the \<fsep\> if specified, otherwise by \mac{mfpframesep}. The
default value of the \TeX{} dimensions \mac{mfpframesep} and
\mac{mfpframethickness} are \dim{2pt} and \dim{0.4pt}, respectively.
The \mac{mfpframe} $\ldots$ \mac{endmfpframe} version is preferred
around \env{mfpic} environments or verbatim material since it avoids
reading the enclosed material before appropriate \mac{catcode} changes
go into effect. In \LaTeX, one can also use the \mac{begin}[mfpframe]
$\ldots$ \mac{end}[mfpframe] syntax.

An alternative way to frame \env{mfpic} pictures is to save them with
\mac{savepic} (see previous section) and issue a corresponding
\mac{usepic} command inside any framing environment/command of the
user's choice or devising.


\head {Affine Transforms.}

Coordinate transformations that keep parallel lines in parallel are
called {\bf affine transforms}.  These include translation, rotation,
reflection, scaling and skewing (slanting). For the \MF{} coordinate
system only---that is, for paths, but not for \mac{tlabel}'s (let
alone \mac{tcaption}'s)---\prog {mfpic} provides the ability to apply
\MF{} affine transforms.


\subhead{Affine Transforms of the \MF{} Coordinate System.}

\bcd
\idx\mac{coords} $\ldots$ \idx\mac{endcoords}
\ecd

All affine transforms are restricted to the innermost enclosing \mac
{coords}$\ldots$\mac{endcoords} pair.  If there is \emph{no} such
enclosure, then the transforms will apply to the rest of the \env{mfpic}
environment

\emph{Note}:  In \LaTeX, a \env{coords} environment may be used.

\bcd
\idx\mac{applyT}[\<transformer\>]
\ecd

Apply the \MF{} \<transformer\> to the current coordinate system.
For example, the \prog {mfpic} \TeX{} macro \mac{zslant\#1} is
implemented as \mac{applyT}[zslanted \#1] where the argument
\mfc{\#1} is a \MF{} pair, such as $(x,y)$.

\vskip\myskip
Transforms provided by \prog {mfpic}.

%\bcd
\vskip\myskip
\halign
{\noindent#\hfil&\quad#\hfil\cr
  \idx\mac{rotate}[$\theta$]  &
    Rotates around origin by $\theta$ degrees  \cr
  \idx\mac{rotatearound}[$p$][$\theta$]  &
    Rotates around point $p$ by $\theta$ degrees  \cr
  \idx\mac{turn}[?$p$][$\theta$]  &
    Rotates around point $p$ (origin is default) by $\theta$ degrees  \cr
  \idx\mac{mirror}[$p_1$][$p_2$]  \cr
  \idx\mac{reflectabout}[$p_1$][$p_2$]  &
    Reflects about the line $p_1${\tt--}$p_2$  \cr
  \idx\mac{shift}[$p$]  &
    Shifts origin by the vector $p$  \cr
  \idx\mac{scale}[$s$]  &
    Scales uniformly by a factor of $s$  \cr
  \idx\mac{xscale}[$s$]  &
    Scales only the X coordinates by a factor of $s$  \cr
  \idx\mac{yscale}[$s$]  &
    Scales only the Y coordinates by a factor of $s$  \cr
  \idx\mac{zscale}[$p$]  &
    Scales uniformly by magnitude of $p$,
    and rotates by angle of $p$  \cr
  \idx\mac{xslant}[$s$]  &
    Skew in $X$ direction by the multiple $s$ of $Y$  \cr
  \idx\mac{yslant}[$s$]  &
    Skew in $Y$ direction by the multiple $s$ of $X$  \cr
  \idx\mac{zslant}[$s$]  &
    See \mfc{zslanted} in \file {grafdoc.tex}  \cr
  \idx\mac{boost}[$\chi$]  &
    Special relativity boost by $\chi$  \cr
  \idx\mac{xyswap}  &
    Reflects in the line $Y=X$  \cr
}
%\ecd

\vskip\myskip
When any of these commands is issued, the effect is to transform all
subsequent figures (within the enclosing \env{coords} or \env{mfpic}
environment). In particular, attention may need to be paid to whether
these transformations move (part of) the figure outside the space
allotted by the \mac{mfpic} command parameters.

A not-so-obvious point (even to the creators of \prog{mfpic}) is that if
several of these transformations are applied in succession, then figures
are transformed as if the transformations were applied in the reverse
order, similar to the application of prefix macros (as well as
application of transformations in mathematics: $T_1 T_2 z$ means apply
$T_1$ to the result, after applying $T_2$ to $z$).

\subhead{Transformation of Paths.}

In the previous section we discussed transformations of the \MF{}
coordinate system. Those macros affect the \emph{drawing} of paths and
other figures, but do not change the actual paths. We will explain the
distinction after introducing the following two macros

\bcd
\idx\mac{store}[\<path variable\>][\<path\>]
\ecd

This stores the following \<path\> in the specified \MF{} \<path
variable\>. Any valid \MF{} variable name will do, in particular, any
sequence of letters and underscores will do. The stored path may later
be used as a figure macro using \mac{mfobj} (below).

\bcd
\idx\mac{mfobj}[\<path expression\>]
\ecd

The \<path expression\> is a previously stored path variable, or
a valid \MF{} expression combining such variables and/or constant paths.
This allows the use of path vatiables or expressions as figure macros,
permitting all prefix operations, etc..
Here's some oversimplified uses of \mac{store} and \mac{mfobj}:

\nobreak
\vskip\myskip
\myverbatim;
\store{f}{\circle{...}}            % store a circle
\dotted\mfobj{f}                   % now draw it dotted
\hatch\mfobj{f}                    % and hatch its interior
% Store two curves:
\store{f}{\curve{...}}
\store{g}{\curve{...}}
% Store two combinations of them:
\store{h}{\mfobj{f..g..cycle}}     % a MF path expression
\store{k}{%
  \lclosed\connect
  \mfobj{f}\mfobj{g}
  \endconnect}
\dotted\mfobj{f}                   % draw the first dotted
\dotted\mfobj{g}                   % then the second
\shade\mfobj{h}                    % now shade one combination
\hatch\mfobj{k}                    % and hatch the other
@endmyverbatim

\vskip\myskip
Getting back to coordinate transforms. If one changes the coordinate
system and then stores and draws a curve, say by
\bex
\myverbatim;
\coords
  \rotate{45 deg}
  \store{xx}{\rect{(0,0),(1,1)}}
  \dashed\mfobj{xx}
\endcoords
@endmyverbatim
\eex

one will get a transformed picture, but the object \mac{mfobj}[xx] will
contain the simple, unrotated rectangular path and drawing it later
(outside the \env{coords} environment) will prove that. This is because
the {\tt coords} environment works at the drawing level, not at the
definition level. In oversimplified terms, \mac{dashed} invokes the
transformation, not \mac{store}. The following transformation prefixes
provide a means of actually creating and storing a transformed path.

\bcd
\idx\mac{rotatepath}[(\<x\>,\<y\>),\<$\theta$\>]$\ldots$\\
\idx\mac{shiftpath}[(\<dx\>,\<dy\>)]$\ldots$\\
\idx\mac{scalepath}[(\<x\>,\<y\>),\<s\>]$\ldots$\\
\idx\mac{xscalepath}[\<x\>,\<s\>]$\ldots$\\
\idx\mac{yscalepath}[\<y\>,\<s\>]$\ldots$\\
\idx\mac{slantpath}[\<y\>,\<s\>]$\ldots$\\
\idx\mac{xslantpath}[\<y\>,\<s\>]$\ldots$\\
\idx\mac{yslantpath}[\<x\>,\<s\>]$\ldots$\\
\idx\mac{reflectpath}[\<$p_1$\>,\<$p_2$\>]$\ldots$\\
\idx\mac{xyswappath}$\ldots$
\ecd

\mac{rotatepath} rotates the following path by \<$\theta$\> degrees
about point \mfc{(\<x\>,\<y\>)}. After the commands:

\bex
\mac{store}[xx][\bsl rotatepath\{(0,0), 45\}\bsl rect\{(0,0),(1,1)\}]
\eex

the object \mac{mfobj}[xx] contains an actual rotated rectangle, as
drawing it will prove. The above macro, and the five that follow are
extremely useful (and better than \env{coords} environments) if one
needs to draw a figure, together with many slightly different versions of
it.

\mac{shiftpath} shifts the following path by the horizontal amount
\<dx\> and the vertical amount \<dy\>.

\mac{scalepath} scales (magnifies or shrinks) the following path by the
factor \<s\>, in such a way that the point {\tt (\<x\>,\<y\>)} is kept
fixed. That is

\bex
\mac{scalepath}[(0,0),2]\mac{rect}[(0,0),(1,1)]
\eex

is essentially the same as \mac{rect}[(0,0),(2,2)], while

\bex
\mac{scalepath}[(1,1),2]\mac{rect}[(0,0),(1,1)]
\eex

is the same as \mac{rect}[(-1,-1),(1,1)]. In both cases the rectangle is
doubled in size. In the first case the lower left corner stays the same,
while in the second case the the upper right corner stays the same.

\mac{xscalepath} is similar to \mac{scalepath}, but only the $x$-direction
is scaled, and all points with first coordinate equal to \<x\> remain
fixed. \mac{yscalepath} is similar, except the $y$-direction is affected.

\mac{slantpath} applies a slant transformation to the following path,
keeping points with second coordinate equal to \<y\> fixed. That is, a
point $p$ on the path is moved right by an amount proportional to the
height of $p$ above the line $y=\<y\>$, with $s$ being the
proportionality factor. Vertical lines in the path will acquire a slope
of $1/s$, while horizontal lines stay horizontal.

\mac{xslantpath} is an alias for \mac{slantpath}

\mac{yslantpath} is similar to \mac{xslantpath}, but exchanges the
roles of $x$ and $y$ coordinates.

\mac{reflectpath} returns the mirror image of the following path, where
the line determined by the points \<$p_1$\> and \<$p_2$\> is the mirror.

\mac{xyswappath} returns the path with the roles of $x$ and $y$ exchanged.
This is almost like \mac{reflectpath}[(0,0),(1,1)], and produces the
same result if the $x$ and $y$ scales of the picture are the same. However,
\mac{reflectpath} compensates for such different scales (so the path
shape remains the same), while \mac{xyswappath} does not (so that after
a swap, verticals become horizontal and horizontals become vertical).
One cannot have both.

\head {Parameters.}

There are many parameters in \prog {mfpic} which the user can modify to
obtain different effects, such as different arrowhead size or shape.
Most of these parameters have been described already in the context of
macros they modify, but they are all described together here.

Many of the parameters are stored by \TeX{} as dimensions, and so are
available even if there is no \MF{} file open; changes to them are not
subject to the usual \TeX{} rules of scope however: they are only
limited by the \env{mfpic} environment, if they are set inside one. This
is for consistency: other parameters are stored by \MF{} (so the macros
to change them will have no effect unless a \MF{} file is open) and the
changes are subject to \MF's rules of scope---to the \prog {mfpic} user,
this means that changes inside the \mac{mfpic} $\ldots$ \mac {endmfpic}
environment are local to that environment, but other \TeX{} groupings
have no effect on scope. Some commands (notably those that set the
axismargins and \mac{tlabel} parameters) change both \TeX{} parameters
and \MF{} parameters, and it is important to keep then consistent.

\bcd
\idx\mac{mfpicunit}
\ecd

This \TeX{} dimension stores the basic unit length for \prog {mfpic}
pictures---the $x$ and $y$ scales in the \mac{mfpic} macro are
multiples of this unit. The default value is \dim{1pt}.

\bcd
\idx\mac{pointsize}
\ecd

This \TeX{} dimension stores the diameter of the circle drawn by the
\mac{point} macro and the diameter of the symbols drawn by
\mac{plotsymbol} and by \mac{plot}. The default value is \dim{2pt}.

\bcd
\idx\mac{pointfilltrue} and \mac{pointfillfalse}
\ecd

This \TeX{} boolean switch determines whether the circle drawn by
\mac{point} will be filled ({\tt true}) or open (outline drawn,
background erased). The default is {\tt true}. This value is local to
any \TeX{} group.

\bcd
\idx\mac{pen}[\<drawpensize\>]\\
\idx\mac{drawpen}[\<drawpensize\>]\\
\idx\mac{penwd}[\<drawpensize\>]
\ecd

Establishes the width of the normal drawing pen. The default is
\dim{0.5pt}. This width is stored by \MF. The shading dots and hatching
pen are unaffected by this. There exist three aliases for this command,
the first two to maintain backward compatibility, the last one for
consistency with other dimension changing commands.

\bcd
\idx\mac{shadewd}[\<dotdiam\>]
\ecd

Sets the diameter of the dots used in the shading macro. The drawing and
hatching pens are unaffected by this. The default is \dim{0.5pt}

\bcd
\idx\mac{hatchwd}[\<hatchpensize\>]
\ecd

Sets the line thickness used in the hatching macros. The drawing pen and
shading dots are unaffected by this. The default is \dim{0.5pt}.

\bcd
\idx\mac{polkadotwd}[\<polkadotdiam\>]
\ecd

Sets the diameter of the dots used in the \mac{polkadot} macro. The
default is \dim{5pt}.

\bcd
\idx\mac{headlen}
\ecd

This \TeX{} dimension stores the length of the arrowhead drawn by the
\mac{arrow} macro. The default value is \dim{3pt}.

\bcd
\idx\mac{axisheadlen}
\ecd

This \TeX{} dimension stores the length of the arrowhead drawn by the
\mac{axes}, \mac{xaxis} and \mac{yaxis} macros, and by the macros
\mac{axis} and \mac{doaxes} when applied to the parameters {\tt x} and
{\tt y}. The first name is for compatability; both reference the same
\TeX{} dimension. The default value is \dim{5pt}.

\bcd
\idx\mac{sideheadlen}
\ecd

This \TeX{} dimension stores the length of the arrowhead drawn by the
\mac{axis} and \mac{doaxes} macros when applied to {\tt l}, {\tt b},
{\tt r} or {\tt t}. The default value is \dim{0pt}.

\bcd
\idx\mac{headshape}[\<hdwdr\>][\<hdten\>][\<hfilled\>]
\ecd

Establishes the shape of the arrowhead drawn by the \mac{arrow} and
\mac{axes} macros. The value of \<hdwdr\> is the ratio of the width
of the arrowhead to its length; \<hdten\> is the tension of the B\'ezier
curves; and \<hfilled\> is a \MF{} boolean value indicating whether the
arrowheads are to be filled (if \mfc{true}) or open. The default values
are $1$, $1$, \mfc{false}, respectively. The \<hdwdr\>, \<hdten\> and
\<hfilled\> values are stored by \MF{}. Setting \<hdten\> to
``\mfc{infinity}'' will make the sides of the arrowheads straight lines.

\bcd
\idx\mac{dashlen}, \mac{dashspace}
\ecd

These \TeX{} dimensions store, respectively, the length of dashes and the
length of spaces between dashes, for lines drawn by the \mac{dashed}
macro. The \mac{dashed} macro may adjust the dashes and the spaces
between by as much as $1\over{n}$ of their value, where $n$ is the
number of spaces appearing in the curve, in order not to have
partial dashes at the ends. The default values are both \dim{4pt}. The
dashes will actually be longer (and the spaces shorter) by the thickness
of the pen used when they are drawn.

\bcd
\idx\mac{dashlineset}, \idx\mac{dotlineset}
\ecd

These macros provide convenient standard settings for the \mac
{dashlen} and \mac{dashspace} dimensions. The macro \mac
{dashlineset} sets both values to \dim{4pt}; the macro \mac
{dotlineset} sets \mac{dashlen} to \dim{1pt} and \mac{dashspace}
to \dim{2pt}.

\bcd
\idx\mac{hashlen}
\ecd

This \TeX{} dimension stores the length of the axis hash marks drawn by
the \mac{xmarks} and \mac{ymarks} macros. The default value is
\dim{4pt}.

\bcd
\idx\mac{shadespace}
\ecd

This \TeX{} dimension establishes the spacing between dots drawn by the
\mac{shade} macro. The default value is \dim{1pt}.

\bcd
\idx\mac{darkershade}, \idx\mac{lightershade}
\ecd

These macros both multiply the \mac{shadespace} dimension by constant
factors, $5/6$ and $6/5$ respectively, to provide convenient standard
settings for several levels of shading.

\bcd
\idx\mac{polkadotspace}
\ecd

This \TeX{} dimension establishes the spacing between the centers of the
dots used in the \mac{polkadot} macro. The default is \dim{10pt}.

\bcd
\idx\mac{dotsize}, \idx\mac{dotspace}
\ecd

These \TeX{} dimensions establishes the size and spacing between the
centers of the dots used in the \mac{dotted} macro. The defaults are
\dim{0.5pt} and \dim{3pt}.

\bcd
\idx\mac{symbolspace}
\ecd

Similar to \mac{dotspace}, this \TeX{} dimension established the space
between symbols placed by the macro \mac{plot}[\<symbol\>]$\ldots\,$.
Its default is \dim{5pt}.

\bcd
\idx\mac{hatchspace}
\ecd

This \TeX{} dimension establishes the spacing between lines drawn by the
\mac{hatch} macro. The default value is \dim{3pt}.

\bcd
\idx\mac{tlabelsep}[\<separation\>]
\ecd

This macro establishes the separation between a label and its nominal
position. It affects text written with any of the commands
\mac{tlabel}, \mac{tlabels}, \mac{axislabels} or \mac{plottext}. It also
sets the separation between the text and the curve defined by the
commands \mac{tlabelrect}, \mac{tlabeloval} or \mac{tlabelellipse}. The
default is \dim{0pt}.

\bcd
\idx\mac{mfpdataperline}
\ecd

When \prog{mfpic} is reading data from files and writing it to the
output file, this macro stores the maximum number of points that will be
written on a single line. Its default is defined by
\mac{def}\mac{mfpdataperline}[5 ].

\bcd
\idx\mac{mfpicheight}, \idx\mac{mfpicwidth}
\ecd

These \TeX{} dimensions store the height and width of the figure created
by the most recently completed \env{mfpic} environment. This might
perhaps be of interest to hackers or to aid in precise positioning of the
graphics. They are meant to be read-only: the \mac{endmfpic} command
globally sets them equal to the height and width of the picture.
But \prog{mfpic} does not otherwise make any use of them.


\head {For Power Users Only.}

\bcd
\idx\mac{mfsrc}[\<metafont code\>]
\ecd

Writes the \<metafont code\> directly to the \MF{} file, using a \TeX{}
\mac{write} command. Line breaks within \<metafont code\> are preserved.
Almost all the \prog{mfpic} drawing macros invoke \mac{mfsrc}. Because
of the way \TeX{} reads and processes macro arguments, not all drawing
macros preserve line breaks (nor do they all need to). However, the ones
that operate on long lists of pair or numeric data (for example,
\mac{point}, \mac{curve}, etc.), do preserve line breaks in that data.

Using \mac{mfsrc} can have some rather bizarre consequences, though, so
using it is not recommended to the unwary. It is, however, currently the
only way to make use of \MF's equation solving ability. Here's an
oversimplified example:

\bex
\myverbatim\#
\mfpic[20]{-0.5}{1.5}{0}{1.5}
\mfsrc{z1=(0,0); z2-z3=(1,2); z2+2z3=(1,-1);} % z2=(1,1), z3=(0,-1)
\arc[t]{z1,z2,z3}
\endmfpic
@endmyverbatim
\eex

Check out the sample \file{forfun.tex} for more realistic examples.


\bcd
\idx\mac{noship}
\ecd

This modifier macro turns off character shipping (by \MF{} to the TFM and
GF files, or by \MP{} to appropriate \EPS{} output file) for the duration
of the innermost enclosing group (e.g., for the \env{mfpic}
environment). This is useful if all one wishes to do in the current
\env{mfpic} environment is to make \emph{tiles} (see below).



\smallskip

\bcd
\idx\mac{patharr}[\<pv\>]$\ldots$\idx\mac{endpatharr}
\ecd

This pair of macros, acting as an environment, accumulate all
enclosing paths, in order, into a path array named \<pv\>. Any path in
the array can be accessed by means of \mac{mfobj}. For example, after

\bex
\myverbatim;
\patharr{pa}
  \rect{(0,0),(1,1)}
  \circle{(.5,.5), .5}
\endpatharr
@endmyverbatim
\eex

Then \mac{mfobj}[pa1] refers to the rectangle and
\mac{mfobj}[pa2] refers to the circle.

\emph{Note}: In \LaTeX, this pair of macros can be used in the form of
a \LaTeX-style environment called \env {patharr} ---as in
\mac{begin}[patharr]$\ldots$\mac{end}[patharr].


\bcd
\idx\mac{tile}[\<tilename\>,\<unit\>,\<wd\>,\<ht\>,\<clip\>]\\
  \ $\ldots$\\
\idx\mac{endtile}
\ecd

In this environment, all drawing commands contribute to a \emph{tile}. A
\emph{tile} is a rectangular picture which may be used to fill the
interior of closed paths.  The units of drawing are given by \<unit\>,
which should be a dimension (like \dim{1pt} or \dim{2in}). The tile's
horizontal dimensions are $0$ to $\<wd\>\cdot\<unit\>$ and its vertical
dimensions $0$ to $\<ht\>\cdot\<unit\>$, so \<wd\> and \<ht\> should be
pure numbers. If \<clip\> is \mfc{true} then all drawing is clipped to
be within the tile's boundary.

By using this macro, you can design your own fill patterns (to use them,
see the \mac{tess} macro below), but please take some care with the
\ae sthetics!

\bcd
\idx\mac{tess}[\<tilename\>]$\ldots$
\ecd

Tile the interior of each closed path with a tessellation comprised of
\emph{tiles} of the type specified by \<tilename\>.  There is no default
\<tilename\>; you must make all your own tiles. Tiling an open curve is
technically an error, but the \MF{} code responds by drawing the path
and not doing any tiling.

Tiling large regions with complicated tiles can exceed the capacity of
some versions of \MP. There is less of a problem with \MF. This is not
because \MF{} has greater capacity, but because of the natural difference
between bitmaps and vector graphics (i.e., \PS).

In \MP, the tiles are copied with whatever color they are given when they
are defined. They can be multicolored.

\bcd
\idx\mac{mftitle}[\<title\>]
\ecd

Write the string \<title\> to the \MF{} file, and use it as a \MF{}
message. (See {\it The \MF{}book}, chapter 22: {\it Strings}, page 187,
for two uses of this.)

\bcd
\idx\mac{tmtitle}[\<title\>]
\ecd

Write the text \<title\> to the \TeX{} document, and to the log file,
and use it implicitly in \mac{mftitle}.

\bcd
\idx\mac{newfdim}[\<fdim\>]
\ecd

Create a new global font dimension, named \<fdim\>, which can be used
almost like an ordinary \TeX{} dimension.  One exception is that the
\TeX{} commands \mac{advance}, \mac{multiply} and \mac{divide}
cannot be applied directly to font dimensions (nor \LaTeX's
\mac{addtolength}); however, the font dimension can be copied to a
temporary \TeX{} dimension register, which can then be manipulated and
copied back (using \mac{setlength} in \LaTeX, if desired). Another
exception is that changes to a font dimension are global in scope. Also
beware that \mac{newfdim} uses font dimensions from a single font,
the \file {dummy} font, which most \TeX{} systems ought to have. (You'll
know if yours doesn't, because \prog {mfpic} will fail upon loading!)
Also, implementations of \TeX{} differ in the number of font dimensions
allowed per font.  Hopefully, \prog {mfpic} won't exceed your local
\TeX{}'s limit. All of \prog{mfpic}'s basic
dimension parameters are font dimensions. We have lied slightly when we
called them ``\TeX{} dimensions''.

\bcd
\idx\mac{setmfpicgraphic}[\<filename\>]
\ecd

This is the command that is invoked to place the graphic created. See
\file{mppicdoc.tex} for a discussion of its use and its default
definition. It is a user-level macro so that it can be redefined in
unusual cases. It operates on the output of the following macro:

\bcd
\idx\mac{setfilename}[\<file\>][\<num\>]
\ecd

\prog{mfpic}'s figure inclusion code ultimately executes
\mac{setmfpicgraphic} on the result of applying \mac{setfilename} to two
arguments: the file name specified in the \mac{opengraphsfile} command
and the number of the current picture. Normally \mac{setfilename} just
puts them together with the ``{\tt .}'' separator (because that is the
way \MP{} names its output), but this can be redefined if the \MP{}
output undergoes further processing or conversion to another format in
which the name is changed. Any redefinition of \mac{setfilename} must
come before \mac{opengraphsfile} because that command tests for the
existence of the first figure. After any redefinition, \mac{setfilename}
must be a macro with two arguments that creates the actual
filename from the above two parts. It should also be completely
expandable, which can be tested by issuing the command
\mac{message}{\tt \{***\mac{setfilename}[filename][1]***\}}. What you
should see on the terminal between the triple asterisks is only the
filename, and no unexpanded \TeX{} commands. See \file{mppicdoc.tex} for
a possibly instructive example.

\bcd
\idx\mac{getmfpicoffset}[\<filename\>]
\ecd

This command is automatically invoked after \mac{setmfpicgraphic} to
store the offset of the lower left corner of the figure in the macros
\mac{mfpicllx} and \mac{mfpiclly}. If \mac{setmfpicgraphic} is redefined
then this may also have to be redefined. Typically, defining it to be
empty (i.e., \mac{def}\mac{getmfpicoffset}[]) will work if either both
or neither of the options \opt{mplabels} and \opt{truebbox} are in
effect.


\subhead {For Hackers Only.}

\prog{mfpic} employs a modified version of \LaTeX's \mac{@ifnextchar}
that not only skips over spaces when seeking the next character, but also
skips over \mac{relax} or tokens that have been \mac{let} equal to it.
This is because, in contexts where we try to preserve lines, we make the
end-of-line character active and set it equal to \mac{relax}. Since it
is hard to predict in what context a macro will be used, this gives code
like

\bex
\mac{function}\\
{\tt[s1.2]\{0,2,.1\}\{ x**2 \}}
\eex

the same behavior in both. One consequence is that putting \mac{relax}
to stop a command from seeing a ``{\tt [}'' as the start of an optional
argument will not work for \prog{mfpic} commands. The same holds for the
``{\tt *}'' in those few commands that have a star-form, and also for
other commands that look ahead (\mac{tlabel} looks for a ``{\tt (}''
starting off the location, and macros that operate on lists of data look
ahead for ``\mac{datafile}''). This may all be moot, because I can't
think of an \prog{mfpic} command that doesn't have mandatory argument(s)
following the look-ahead location. If a ``\mac{relax}'' appeared in such
a place, and it was not skipped, an error would result from reading it
as the next argument.


\part {Acknowledgements.}

Tom would like to thank all of the people at Dartmouth as well as out in
the network world for testing \prog {mfpic} and sending him back
comments. He would particularly like to thank:

\vskip\myskip
Geoffrey Tobin %(G.Tobin@latrobe.edu.au)
for his many suggestions,
especially about cleaning up the \MF{} code, enforcing dimensions, fixing
the dotted line computations, and speeding up the shading routines
(through this process, Geoffrey and Tom managed to teach each other many
of the subtleties of \MF), and for keeping track of \prog {mfpic} for
nearly a year while Tom finished his thesis;

\vskip\myskip
Bryan Green %(bgreen@sanjuan.uvic.ca)
for his many suggestions, some of
which (including his rewriting the \mac{tcaption} macro) ultimately
led to the current version's ability to put graphs in-line or
side-by-side; and

\vskip\myskip
Uwe Bonnes %(bon@lte.e-technik.uni-erlangen.de)
and Jaromir Kuben% (vabo@muni.cz)
, who worked out rewrites of \prog {mfpic} during Tom's
working hiatus and who each contributed several valuable ideas.

\vskip\myskip
Some credit also belongs to Anthony Stark% (ajs@merck.com)
, whose work on a FIG to \MF{} converter has had a serious impact on the
development of many of \prog {mfpic}'s capabilities.

\vskip\myskip
Finally, Tom would like to thank Alan Vlach, the other \TeX{}nician at
Berry College, for helping him decide on the format of many of the
macros, and for helping with testing.

Dan Luecking would like to echo Tom's thanks to all of the above,
especially Geoffrey Tobin and Jaromir Kuben. And to add the names Taco
Hoekwater, for comments, advice and suggestions, and Zaimi Sami~Alex for
suggestions and interest shown.

But mostly, he'd like to thank Tom Leathrum for starting it all.

\part {Changes History.}

See the file \file{changes.tex} for a somewhat sporadic and rambling
history of changes to \prog {mfpic}. See the file \file{whats.new} for a
list of any known problems.

\part{Appendices}

\head{Summary of Options}

Unless otherwise stated, any of the command forms will be local to the
current \env{mfpic} environment if used inside. Otherwise it will affect
all later environments.

\def\stack#1{\everycr{}\let\\\cr\halign{\strut##\hfil\cr#1\crcr}}
\vskip\myskip
{\everycr{\noalign{\medskip}}
\halign to \hsize{\opt{#}\hfil\quad\tabskip0pt plus 1fil&
        \vtop{\stack{#}}\hfil\quad&
        \vtop{\parindent0pt \hsize.45\hsize \rightskip0pt plus1fil\relax
            \strut\ignorespaces#\strut}\tabskip0pt\cr
\sc Option:& \sc Command form(s):& \omit\sc Restrictions: \hfil\cr
\noalign{\smallskip\hrule\smallskip}
metapost&\mac{usemetapost}& Command must come before
    \mac{opengraphsfile}. Incompatible with \opt{metafont} option.\cr
metafont&\mac{usemetafont}& The default. Command must come before
    \mac{opengraphsfile}. Incompatible with \opt{metapost} option.\cr
mplabels&\mac{usemplabels},\\ \mac{nomplabels}& Requires
    \opt{metapost}, should be used with \opt{truebbox}. If command is
    used inside an \env{mfpic} environment, it should come before any
    \mac{tlabel} commands.\cr
truebbox& \mac{usetruebbox},\\ \mac{notruebbox}& Has no effect
    without \opt{metapost}; should be used with \opt{mplabels}. Command should
    not be used inside any \env{mfpic} environment because it is needed
    by the start-up code of \mac{mfpic}.\cr
clip& \mac{clipmfpic},\\ \mac{noclipmfpic}& No restrictions.\cr
centeredcaptions& \mac{usecenteredcaptions},\\ \mac{nocenteredcaptions}&
    If command is used inside an \env{mfpic} environment, it should come
    before \mac{tcaption}.\cr
debug&\mac{mfpicdebugtrue},\\\mac{mfpicdebugfalse}& To turn on
    debugging while \file{mfpic.tex} is loading, issue
    \mac{def}\mac{mfpicdebug}[].\cr
\vtop{\hbox{draft\strut}
      \hbox{final\strut}
      \hbox{nowrite\strut}}&\mac{mfpicdraft}\\
                            \mac{mfpicfinal}\\
                            \mac{mfpicnowrite}&Should not be used
                            together. Command forms should come before
                            \mac{opengraphsfile}\cr
}}

\vskip\myskip
\head{Plotting styles for \mac{plotdata}}

When \mac{plotdata} passes from one curve to the next, it increments a
counter and uses that counter to select a dashpattern, color, or
symbol. It uses predefined dashpattern names \mfc{dashtype0} through
\mfc{dashtype5}, or predefined color names \mfc{colortype0} through
\mfc{colortype7}, or predefined symbols \mfc{pointtype0} through
\mfc{pointtype8}. Here follows a description of each of these variables.

\vskip\myskip
 Under \mac{dashedlines}, we have the following dashpatterns:

\vskip\myskip
\indent\vbox{%
\halign{#\hfil\qquad&#\hfil\quad&#\hfil\strut\cr
\sc Name&\sc Pattern&\sc Meaning\cr
\noalign{\smallskip\hrule\smallskip}
\mfc{dashtype0}&\tt 0pt & solid line\cr
\mfc{dashtype1}&\tt 3pt,4pt & dashes\cr
\mfc{dashtype2}&\tt 0pt,4pt & dots\cr
\mfc{dashtype3}&\tt 0pt,4pt,3pt,4pt& dot-dash\cr
\mfc{dashtype4}&\tt 0pt,4pt,3pt,4pt,0pt,4pt& dot-dash-dot\cr
\mfc{dashtype5}&\tt 0pt,4pt,3pt,4pt,3pt,4pt& dot-dash-dash\cr
}}

\filbreak
\vskip\myskip
Under \mac{coloredlines}, we have the following colors. Except for
\mfc{black} and \mfc{red}, each color is altered as indicated. This is
an attempt to make the colors more equal in visibility against a white
background. (The success of this attempt varies greatly with the output
or display device.)

\vskip\myskip
\indent\vbox{%
\halign{#\hfil\qquad&#\hfil\quad&#\hfil\strut\cr
\sc Name&\sc Color &\sc (r,g,b)\cr
\noalign{\smallskip\hrule\smallskip}
\mfc{colortype0}&black& $(0,0,0)$    \cr
\mfc{colortype1}&red& $(1,0,0)$        \cr
\mfc{colortype2}&blue& $(.2,.2,1)$     \cr
\mfc{colortype3}&orange& $(1,.66,0)$   \cr
\mfc{colortype4}&green& $(0,.8,0)$     \cr
\mfc{colortype5}&magenta& $(.85,0,.85)$\cr
\mfc{colortype6}&cyan& $(0,.85,.85)$   \cr
\mfc{colortype7}&yellow& $(.85,.85,0)$ \cr
}}

\filbreak
\vskip\myskip

Under \mac{pointedlines} and \mac{datapointsonly}, the
following symbols are used. Internally each is referred to by the
numeric name, but they are identical to the more descriptive name.
Syntactically, all are \MF{} path variables.

\vskip\myskip
\indent\vbox{%
\halign{#\hfil\qquad&#\hfil\strut\cr
\sc Name&\sc Description\cr
\noalign{\smallskip\hrule\smallskip}
\mfc{pointtype0}&\mfc{Star}\cr
\mfc{pointtype1}&\mfc{Triangle}\cr
\mfc{pointtype2}&\mfc{SolidCircle}\cr
\mfc{pointtype3}&\mfc{Plus}\cr
\mfc{pointtype4}&\mfc{Square}\cr
\mfc{pointtype5}&\mfc{SolidDiamond}\cr
\mfc{pointtype6}&\mfc{Cross}\cr
\mfc{pointtype7}&\mfc{Circle}\cr
\mfc{pointtype8}&\mfc{SolidTriangle}\cr
}}

\vfil
\break

\let\oldopt=\opt
\def\opt{\leavevmode\hphantom{\tt\char`\\}\oldopt}
\let\oldmfc=\mfc
\def\mfc{\leavevmode\hphantom{\tt\char`\\}\oldmfc}
\let\gbc=\mfc
\aboveindexitemskipamount = 0pt
\aboveindexitempenalty = 0
\def\indexspace{\penalty-100\vskip12pt plus 12pt minus 4pt}

\head{Index of commands, options and parameters}

\readindexfile{i}

\end
