%%% File: mfpman.tex
%%% A part of mfpic 0.9 2006/05/26
%%%
%  Documentation of mfpic macros
\documentclass[letterpaper]{article}

% Fonts: TimesRoman, CM Sans serif, and LuxiMono for TeX commands.
\usepackage[T1]{fontenc}
\usepackage{mathptmx}
\usepackage[scaled=.85]{luximono}
\renewcommand\sfdefault{cmss}

% Fake chapters (really sections):
\usepackage[chapters]{mfpdoc}
\pagestyle{mfpdoc}

\usepackage{makeidx}
\makeindex

\usepackage{graphics}

\ifpdf
\expandafter\usepackage\expandafter
  [\mfpHyOpts,pdfpagelabels=true,hyperindex]{hyperref}
\expandafter\pdfstringdefDisableCommands\expandafter
  {\mfpHyDisable}
\fi

\stepcounter{secnumdepth}

\title{\Mfp{}: Pictures in \TeX{}\\ with Metafont and
MetaPost\thanks{Copywrite 2002--2006, Daniel H. Luecking}}


\author{%
Daniel H. Luecking%
    \thanks{\email {luecking@uark.edu}: Communications regarding \mfp{}
    should be sent to this author. Any first-person references in this
    manual refer to Dr.~Luecking.}
\and Dr Thomas E. Leathrum
\and Geoffrey Tobin}

\date{\mfpdate}

\begin{document}

\pagenumbering{roman}
\maketitle
\tableofcontents

\clearpage
\pagenumbering{arabic}

\chapter{Introduction}\label{introduction}
\thispagestyle{plain}

\section{Why?}\label{why}

Tom got the idea for \mfp{}%
    \footnote{`\Mfp{}' is pronounced by spelling the first two letters:
    `em-eff-pick'.}
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
graphic objects into a \prog{DVI} file using \TeX{} \cs{special}'s.
However, this technique seemed far from \TeX{}'s ideal of device
independence because different \TeX{} output drivers recognize different
\cs{special's}, and handle them in different ways.

\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 was, of course, \PiCTeX{}, which was wonderfully flexible and
general, but its most obvious feature was its speed---or rather lack of
it. Processing a single picture in \PiCTeX{} (in those days) could often
take several seconds.

It occurred to Tom that it might be possible to take advantage of the
fact that \MF{} is \emph{designed} for drawing things. The result of
pursuing this idea was \mfp{}, 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 the almost universal
availability of free \PS{} interpreters like \GS, some \mfp{} users
wanted to run their \mfp{} output through \MP{}, to produce \PS{}
pictures. Moreover, users wanted to be able to use \pdfTeX{}, which did
not get along well with PK fonts, but was quite happy with \MP{}
pictures. So \MP{} support was added to \mfp{}. This got us a little bit
away from device independence, but many users were not much concerned
with that: they just wanted a convenient way to have text and pictures
described in the same document file.

With the extra capabilities of \PS{} (e.g., color) and the corresponding
abilities of \MP{}, there was a demand for some \mfp{} 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{}.

\section{Who?}\label{author}

The original \Mfp{} (and the core of the current version) 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.

Somewhere in the mid 1990's the development passed to Geoffrey Tobin who
kept things going for several years.

The addition of \MP{} support was carried out by Dan Luecking around
1997--99. He is also responsible for all other additions and changes
since then, with help from Geoffrey and a few others mentioned in the
Acknowledgements.

\section{What?}\label{manifest}

See the \file{README} file for a list of files in the distribution and a
brief explanation of each. Only four are actually needed for full access
to \mfp{}'s capabilities: \file{mfpic.dtx}, \file{mfpic.ins},
\file{grafbase.dtx} and \file{mfppatch.tex}. Running \LaTeX{} on
\file{mfpic.ins} creates the only required files:
\begin{display}
    \file{mfpic.tex} and \file{mfpic.sty}, the latter required only for
        \LaTeX{}.\\
    \file{grafbase.mf}, required only if \MF{} will be processing
        figures.\\
    \file{grafbase.mp} and \file{dvipsnam.mp}, needed only if \MP{} will
        be the processor.\\
    \file{mfppatch.tex} is used to distribute simple bug fixes. It does
        nothing after a major update, but if it is not installed and a
        previous one is, a warning will be issued.
\end{display}
The README file also gives some guidence on the proper location for the
installation of these files.

\section{How?}\label{process}

Some guidance on writing files that contain \mfp{} figures can be found
in the accompanying file \file{mfpguide.pdf}. If you use \mfp{} to
produce \MP{} figures the process is straightforward: run \TeX{} (or
\LaTeX), then \MP{}, then \TeX{} again. If there are no errors, then
\prog{dvips} or other DVI-to-PS converter can be run to produce
viewable\slash printable output. You can also run \prog{dvipdfm} to obtain PDF
output, or even use \pdfTeX{} instead of \TeX{} (or \pdfLaTeX{} instead
of \LaTeX{}) to get PDF output directly.

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 \mfp{} that there is
no file \file{pics.1}, but \TeX{} will continue processing the file
anyway. When \TeX{} is finished, you will now have a file called
\file{pics.mp}. This is the \MP{} file containing the descriptions of
the pictures for \file{pictures.tex}. You need to run \MP{} on
\file{pics.mp} (Read your \MF{} manual to see how to do
this.%
    \footnote{The document \textit{Some experiences on running Metafont
    and MetaPost}, by Peter Wilson, can be useful for beginners. Fetch
    \file{CTAN/info/metafp.pdf}. `\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/}.}) %
Typically, you just type
\begin{verbatim}
mpost pics.mp
\end{verbatim}
(or possibly "\verb$mp pics.mp$").

This produces files \file{pics.1}, \file{pics.2}, etc., the number of
files depending on the version of \file{pictures.tex}. You then
reprocessing \file{pictures.tex} with \TeX{} to produce a DVI file. This
file can then be processed with \prog{dvips} (for example) to produce
\PS{} output which can be printed or viewed. One can also process the
DVI with \prog{dvipdfm} to produce a PDF file.

If \pdfTeX{} is used instead of \TeX{} on the second run, you should be
able to view the resulting PDF file immediately, without any further
processing.

If instead you use \mfp{} to produce \MF{} figures, things are a little
less straightforward. The process is \TeX{}, then \MF{}, then
\prog{gftopk}, then \TeX{} again. After this, \TeX{}'s DVI output ought
to be viewable and printable by most DVI viewers or printer drivers. For
a few \TeX{} systems there may be some prior setup needed. One needs to
convince \TeX{} and its output drivers to find \MF{}'s output files. You
should do whatever is necessary (perhaps nothing!) to insure that \TeX{}
looks in the current directory for \file{.tfm} files, and that your DVI
drivers look in the current directory for \file{.pk} files. There may
also be some setup needed to ensure that the \file{.pk} files are
created at a resolution that matches your printer's. See the discussion
in \file{mfpguide.pdf}.

If you want to test this process on the supplied sample files, edit
\file{pictures.tex} removing the \cs{usemetapost} command (or edit
\file{lapictures.tex}, removing the \opt{metapost} option). After that,
run \TeX{} on \file{pictures.tex} (or run \LaTeX{} on
\file{lapictures.tex}). You may see a message from \mfp{} that there is
no file \file{pics.tfm}, but \TeX{} will continue processing the file.
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
\texttt{mode:=localfont} set up.
(Read your \MF{} manual to see how to do this.%
    \footnote{If you are new to running \MF{}, the document
    \textit{Metafont for Beginners}, by Geoffrey~Tobin, is a good
    start. Fetch \file{CTAN/info/metafont-for-beginners.tex}.}) %
Typically, you just type
\begin{verbatim}
mf pics.mf
\end{verbatim}
or, to use a particular printer mode such as \texttt{ljfour}, possibly
something like
\begin{verbatim}
mf '\mode:=ljfour; input pics.mf'
\end{verbatim}
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.) Typically, you just run
\begin{verbatim}
gftopk pics.600gf
\end{verbatim}
(or possibly ``\verb$gftopk pics.600gf pics.600pk$'' or
``\verb$gftopk pics.600gf pics.pk$'').

Now that you have the font (the \file{.pk} file) and font metric file (the
\file{.tfm}) 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},
because \mfp{} never tries to load the font if the \file{.tfm} is absent
and therefore no automatic \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 far-away
places) before you can see any later changes. It might be wise to write
a shell script (batch file) that runs both \MF{} and \prog{gftopk}. It
should also do some error checking and delete the \file{.tfm} if the
\file{.pk} file is not produced. That way, if anything goes wrong, the
\file{.dvi} will not contain the font (\mfp{} will draw a rectangle and
the figure number in place of the figure).

These processing steps---processing with \TeX{}, processing with
\MF{}\slash\prog{gftopk} or \MP{}, 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{} or \MP{} steps.

There are also somewhat subtle circumstance under which you can skip the
second \TeX{} step after editing a figure if the file  has already gone
through the above process. Delineating the exact cirumstances is rather
involved, so it is recommended that you always repeat the \TeX{} step if
changes have been made to any figure.

What makes \mfp{} work? When you run \TeX{} on the file
\file{pictures.tex}, the \mfp{} macros issue \TeX{} \cs{write} commands,
writing \MF{} (or \MP{}) commands to a file \file{pics.mf} (or
\file{pics.mp}).  The user should never have to read or change the file
\file{pics.mf} directly---the \mfp{} macros take care of it.

The enterprising user can determine by examining the \mfp{} source and
the resulting \file{.mf} or \file{.mp} file, that \mfp{} drawing macros
translate almost directly into similar \MF{}\slash\MP{} commands,
defined in one of the files \file{grafbase.mf} or \file{grafbase.mp}.
The labels and captions, however, are placed on the graph by \TeX{}
using box placement techniques similar to those used in \LaTeX{}'s
\env{picture} environment (except when option \opt{mplabels} is in
effect, in which case the labels are written to the \file{.mp} file and
handled by \MP{}).

\smallskip
\emph{Note}: In this manual, when describing \mfp{} operations, we will
often refer to ``\MF{}'' when we really mean ``\MF{} or \MP{}''. This
will especially be the case whenever we need to refer to commands in the
two languages which are substantially the same, but occasionally we will
even talk about ``running \MF{}'' when we mean running one or the other
program \texttt{mf} or \texttt{mpost} to process the figures. If we need
to discriminate between the two processors, (for example when they have
different behavior) we will make the difference explicit.

A similar shorthand is used when referring to ``\TeX{}''. It should not be
taken to mean ``plain \TeX{}'', but rather whatever version of \TeX{} is used
to process the source file: plain \TeX{}, \LaTeX{}, \pdfTeX{}, or
\pdfLaTeX{}. Also \AmSTeX{}, \prog{eplain} and some other variants. When
last tried, \mfp{} didn't work with \ConTeXt{}.

\clearpage
\chapter{Options.}\label{options}

There are several options to the \mfp{} package. These options can be
turned on with certain provided commands, but under \LaTeX{} they can
also be used in the standard \LaTeX{} \cs{usepackage} optional argument.
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. Any option
in the \cs{usepackage} command not among those given below will be
passed on to the \prog{graphics} package, provided the \opt{metapost}
option has been used.

If the file \file{mfpic.cfg} exists, it will be input just before all
options are processed. You can create such a file containing an
\cs{ExecuteOptions} command to execute any options you would like to
have as default. Actual options to \cs{usepackage} will override these
defaults, of course. And so will any of the commands below.

If a file named \file{mfpic.usr} can be found, it will be input at the
end of the loading of \mfp{}. The user can create such a file containing
any of the commands of this section that he would like to have as
default.

Finally, if the file \file{mfppatch.tex} can be found, it will be input
slightly before the end of loading \mfp{}. It is part of the \mfp{}
distribution, and will be used to implement minor corrections when bugs
are found. The user should \emph{not} modify this file unless
he really knows what he is doing.

\section{\opt{metapost}, \cs{usemetapost}.}\label{metapost}
\index{metapost@\opt{metapost}}%
\index{usemetapost@\cs{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 \cs{usemetafont}), but it is
redundant, as \MF{} is the default. Either command must come before the
\cs{opengraphsfile} command (see section~\ref{files}). They should not
be used together in the same document. (Actually, they can but one needs
to close one output file and open another. Moreover, it hasn't ever been
seriously tested, and it wasn't taken into consideration in writing most
of the macros.) If the command form \cs{usemetapost} is used in a
\LaTeXe{} document, it must come in the preamble. Because of the timing
of actions by the \prog{babel} package and by older versions of
\file{supp-pdf.tex} (input by \file{pdftex.def} in the \prog{graphics}
package), when \pdfLaTeX{} is used \mfp{} should be loaded and
\cs{usemetapost} (if used) declared before \prog{babel} is loaded.


\section{\opt{mplabels}, \cs{usemplabels},
\cs{nomplabels}.}\label{mplabels}
\index{mplabels@\opt{mplabels}}%
\index{usemplabels@\cs{usemplabels}}%
\index{nomplabels@\cs{nomplabels}}

Causes all label creation commands to write their contents to the output
file. It effects only labels on the figure, not a caption added by the
\cs{tcaption} command (see section~\ref{text}).  In this case labels are
handled by \MP{} and can be rotated. It requires \MP{}, and will be be
ignored without it (\MF{} cannot handle labels). Using this option
without the \opt{metapost} option may also produce an error message
either from \TeX{} or \MF{}. The commands forms can be placed anywhere
and they affect subsequent \cs{tlabel} commands. When this is in effect,
the labels become part of the figure and, in the default handling, they
may be clipped off or covered up by later drawing elements. But see the
next section on the \opt{overlaylabels} option. Labels added to a
picture contribute to the bounding box even if \opt{truebbox} is not 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
\cs{mfpverbtex} command, see section~\ref{labels}. 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, the \texttt{mpost} command may take an option for this
purpose, or an environmental variable named \texttt{TEX} may be set
equal to \texttt{latex} in the command shell of your operating system.).


\section{\opt{overlaylabels}, \cs{overlaylabels}, \cs{nooverlaylabels}.}
\label{overlaylabels}
\index{overlaylabels@\opt{overlaylabels}}%
\index{overlaylabels@\cs{overlaylabels}}%
\index{nooverlaylabels@\cs{nooverlaylabels}}

In the past, under \opt{mplabels} all text labels created by \cs{tlabel}
and its relatives were added to the picture by \MP{} \emph{as they
occurred}. This made them subject to later drawing commands: they could
be covered up, erased, or clipped. With this option (or after the
command \cs{overlaylabels}) text labels are saved in a separate place
from the rest of a picture. When a picture is completed, the labels that
were saved are added on top of it. This is the way labels always behave
under the \opt{metafont} option, because then \TeX{} must add the labels
and there is no possibility for special effects involving clipping or
erasing (at the \MF{} level).

With the \opt{metapost} option, but without \opt{mplabels} it has been
decided to keep the same behavior (and the same code) as under the
\opt{metafont} option. However, when \opt{mplabels} is used, there is
the possibility for special effects with text, and it has always been
the behavior before version 0.7 to simply place the labels as they
occurred. It turns out that placing the labels at the end is cleaner and
simpler to code, so I experimented with it and rejected it as a default,
but now offer it as an option. With this option, \mfp{} labels have
almost the same behavior with or without \opt{mplabels}.


\section{\opt{truebbox}, \cs{usetruebbox},
\cs{notruebbox}.}\label{truebbox}
\index{truebbox@\opt{truebbox}}%
\index{usetruebbox@\cs{usetruebbox}}%
\index{notruebbox@\cs{notruebbox}}

Normally \MP{} outputs an EPS file with the actual bounding box of the
figure. By default, \mfp{} \emph{overrides} this and sets the bounding
box to the dimensions specified by the \cs{mfpic} command that produced
it. (This used to be needed for \TeX{} is to handle \cs{tlabel} commands
correctly. Now, it is just for backward compatability, and for
compatability with \MF{}'s behavior.) It is reasonable to let \MP{} have
its way, and that is what this option does. If one of the command forms
is used in an \env{mfpic} environment, it affects only that environment,
otherwise it affects all subsequent figures. This option currently has
no effect with \MF{}, but should cause no errors.


\section{\opt{clip}, \cs{clipmfpic}, \cs{noclipmfpic}.}\label{clip}
\index{clip@\opt{clip}}%
\index{clipmfpic@\cs{clipmfpic}}%
\index{noclipmfpic@\cs{noclipmfpic}}

Causes all parts of the figure outside the rectangle specified by the
\cs{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. It has an often unexpected interaction with
truebbox. When both are in effect, \MP{} will produce a bounding box
that is the intersection of two rectangles: the true one \emph{without
clipping}, and the clipping rectangle (i.e., the one specified in the
\cs{mfpic} command). It is possible for the actual figure to be much
smaller than this bounding box (even empty!). This is a property of the
\MP{} \gbc{clip} command and we know of no way to avoid it.


\section{\opt{centeredcaptions}, \cs{usecenteredcaptions},
\cs{nocenteredcaptions}.}\label{centeredcaptions}
\index{centeredcaptions@\opt{centeredcaptions}}%
\index{usecenteredcaptions@\cs{usecenteredcaptions}}%
\index{nocenteredcaptions@\cs{nocenteredcaptions}}

Causes multiline captions created by \cs{tcaption} to have all lines
centered. This has no effect on the normal \LaTeX{} \cs{caption}
command.%
    \footnote{This writer [DHL] feels that \cs{tcaption} is too limited
    and users ought to apply the caption by other means, such as
    \LaTeX{}'s \cs{caption} command, outside the \env{mfpic}
    environment.}%

The commands can be issued anywhere. If inside an \env{mfpic}
environment they should come before the \cs{tcaption} command and affect
only it, otherwise they affect all subsequent figures. They should not
be used in the argument of a \cs{tcaption} command.

\section{\opt{raggedcaptions}, \cs{useraggedcaptions},
\cs{noraggedcaptions}.}\label{raggedcaptions}
\index{raggedcaptions@\opt{raggedcaptions}}%
\index{useraggedcaptions@\cs{useraggedcaptions}}%
\index{noraggedcaptions@\cs{noraggedcaptions}}

Causes multiline captions created by \cs{tcaption} to have all lines
raggedright. If \opt{centeredcaptions} is on, both sides will be ragged.
The command \cs{noraggedcaptions} restores the default: all lines except
the last justified. The last is either centered or flush left according
to whether \opt{centeredcaptions} is on or off.

The commands can be issued anywhere. If inside an \env{mfpic}
environment they should come before the \cs{tcaption} command and affect
only it, otherwise they affect all subsequent figures. They should not
be used in the argument of a \cs{tcaption} command.

\section{\opt{debug}, \cs{mfpicdebugtrue},
\cs{mfpicdebugfalse}.}\label{debug}
\index{debug@\opt{debug}}%
\index{mfpicdebugtrue@\cs{mfpicdebugtrue}}%
\index{mfpicdebugfalse@\cs{mfpicdebugfalse}}

Causes \mfp{} 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 \cs{mfpicdebug} prior to loading. Any definition will
work because \prog{mfpic} only checks whether it is defined.

\section{\opt{clearsymbols}, \cs{clearsymbols}, \cs{noclearsymbols}.}
\index{clearsymbols@\opt{clearsymbols}}%
\index{clearsymbols@\cs{clearsymbols}}%
\index{noclearsymbols@\cs{noclearsymbols}}

\Mfp{} has two commands, \cs{point} and \cs{plotsymbol} that place a
small symbol at each of a list of points. The first can place either a
small filled disk or an open disk, the choice being dictated by the
setting of the boolean \cs{pointfilltrue} or \cs{pointfillfalse}. The
behavior of \cs{point} in the case of \cs{pointfillfalse} is to erase the
interior of the disk in addition to drawing its circumference.

The second command \cs{plotsymbol} can place a variety of shapes, some
open, some not. Its behavior before version 0.7 was to always draw the
shape without erasing the interior. Two other commands that placed these
symbols, \cs{plotnodes} and \cs{plot}, had the same behavior. With this
option, two of these, \cs{plotsymbol} and \cs{plotnodes}, will erase the
interior of the open symbols before drawing them. Thus
\cs{plotsymbol}\marg{SolidCircle} still works just like
\cs{pointfilltrue}\cs{point}, and now with this option
\cs{plotsymbol}\marg{Circle} behaves the same as
\cs{pointfillfalse}\cs{point}. The \cs{plot} command is unaffected by
this option.


\section{\opt{draft}, \opt{final}, \opt{nowrite}, \cs{mfpicdraft},
    \cs{mfpicfinal}, \cs{mfpicnowrite}.}\label{draft}
\index{draft@\opt{draft}}%
\index{final@\opt{final}}%
\index{nowrite@\opt{nowrite}}%
\index{mfpicdraft@\cs{mfpicdraft}}%
\index{mfpicfinal@\cs{mfpicfinal}}%
\index{mfpicnowrite@\cs{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, \mfp{} checks for the existence of the graphic
before trying to include it. However, on some systems checking for the
existence of a nonexistent file can be very slow because the entire
\TeX{} search path will need to be checked. Therefore, \mfp{} doesn't
even attempt any inclusion on the first run. The first run is detected
by the non-existence of \file{\meta{file}.1}, where \meta{file} is the
name given in the \cs{opengraphsfile} command (but see also
section~\ref{files}). These options can be used to override this
automatic detection. All the command versions \emph{should} come before
the \cs{opengraphsfile} command. The \cs{mfpicnowrite} command
\emph{must} come before it.

These options might be used if, for example, the first figure has an
error and is not created by \MP{}, but you would like \mfp{} to go
ahead and include the remaining figures. Then use \opt{final}. It can
also be used to override a \LaTeX{} global \opt{draft} option. Or if
\file{\meta{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.

\section{\opt{mfpreadlog}, \cs{mfpreadlog}.}\label{readlog}
\index{mfpreadlog@\opt{mfpreadlog}}%
\index{mfpreadlog@\cs{mfpreadlog}}

From version 0.8, there exists a scheme to allow \MF{} or \MP{} to pass
information back to the \file{.tex} file. This is done by writing code
to the figure file requesting \MF{} to place that information in the
\file{.log} file it produces. This option instructs \mfp{} to
read through that log file line-by-line looking for such information.
Since such log files can be potentially quite lengthy, this is made an
option. If the command form \cs{mfpreadlog} is used, it must come before
the \cs{opengraphsfile} command, since that is when the file will be
examined. At the present time, the only \mfp{} facility that requires
this two-way communication is \cs{assignmfvalue} (see
subsection~\ref{misc}). If this is used, the filename given to
\cs{opengraphsfile} should not be the same as the \TeX{} source file in
which this occurs, as then the wrong \file{.log} may be read.


\section{Scoping Rules.}\label{scoping}

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.

An effort has been made (as of version 0.7) to make this universal. That
is, any of the commands listed above for turning options on and off will
be global when issued outside an \env{mfpic} environment. The debug
commands are exceptions; they obey all \TeX{} scoping rules.

We have also tried to make all other \mfp{} commands for changing the
various parameters follow this rule: local inside \env{mfpic}
environment, global outside. If this is ever untrue, and I don't
document that fact, please let me know.

The following are special:
\begin{display}
\cs{usemetapost}\index{usemetapost@\cs{usemetapost}},
\cs{usemetafont}\index{usemetafont@\cs{usemetafont}},
\cs{mfpicdraft}\index{mfpicdraft@\cs{mfpicdraft}},
\cs{mfpicfinal}\index{mfpicfinal@\cs{mfpicfinal}},
\cs{mfpicnowrite}\index{mfpicnowrite@\cs{mfpicnowrite}},\\
and
\cs{mfpreadlog}\index{mfpreadlog@\cs{mfpreadlog}}.
\end{display}
\noindent Their effects are always global, partly because they should
occur prior to the initialization command \cs{opengraphsfile} (described
in section~\ref{files}). Note that \cs{usemetapost} may cause a file of
graphic inclusion macros to be input. If this command is issued inside a
group, some definitions in that file may be lost, breaking the graphic
inclusion code.


\clearpage
\chapter{\CMF{} Data Types.}\label{types}

Since the arguments of most \mfp{} drawing commands are sent to \MF{} to
be interpreted, it's useful to know something about \MF{} concepts. In
this chapter we will discuss some of the data types \MF{} supports.
Even the casual user should know how coordinates and colors are treated
and so should at least skim the next two sections. The last
section can be read when the user wants to manipulate more complex
objects.

\CMF{} permits  several different data types, and we will mainly be
concerned with six of these: numeric, pair, color (\MP{} only), path,
picture and boolean.%
    \footnote{For the curious, there are a total of eight
    types (nine for \MP{}). The other three are string, transform and pen.
    \MF{} also permits expressions that produce nothing, which is sometimes
    called the vacuous type, but doesn't allow for (or need) variables of
    this type.}

A \emph{variable} is a symbolic name such as \mfc{A} or
\mfc{incenter}. Any sequence of letters and underscores is permitted
as a variable name. Numeric indexes are also allowed, provided all
variables that differ only in the index have the same type. Thus
\mfc{A1}, \mfc{A2}, etc., might be variables which are all of type pair.
Quite a lot more is permited for variable names, but the rules are
rather complex and easy to violate. \Mfp{} has commands for creating
both simple variables and indexed variables (called \emph{arrays}) but
the casual user can get quite a lot of use out of \mfp{} without ever
creating or using a \MF{} variable.

\CMF{} also has something akin to functions. For example, \mfc{sin(1.57)}
might represent a function named \mfc{sin} receiving the parameter
$1.57$ as input and returning the appropriate value. Functions
can take any number of parameters and return any of the data types that
\MF{} supports.%
    \footnote{Including the vacuous type.}


\section{\CMF{} numerics and pairs.}\label{pairs}

\CMF{} has numeric quantities. These include lengths, such as the radius
of a circle, as well as dimension units such as \mfc{in} (inches)
and \mfc{pt} (points). In fact it understands all the same units that
\TeX{} does. Numeric quantities can be constants (explicit numbers) or
variables (symbolic names). In fact, \mfc{in} and \mfc{pt} are symbolic
names for numeric quantities.

\CMF{} also has \mfc{pair} objects, which may be constants or variables.
Pair constants have the form \mfc{($x$,$y$)} where $x$ and $y$ are
numbers, for example \mfc{(0,0)}.  Pairs are two-dimensional quantities
used for representing either points or vectors in a rectangular
(Cartesian) coordinate system.

In this manual we often represent each pair by a brief name, such as
\meta{p} or \meta{v}, the meanings of which are usually obvious in the
context of the macro. These are intended to be replaced in actual use by
either a pair constant or variable. The succinctness of this notation
helps us to think geometrically rather than only of coordinates.


\section{\CMP{} colors.}\label{MPcolors}

\CMP{} has the same concepts as \MF, 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 (the ``rgb'' model). A color variable is a name, like
\mfc{red}, \mfc{blue} (both predefined by \MP) or \gbc{magenta}
(predefined by \mfp{}).


\section{\CMF{} paths, pictures and booleans.}\label{paths}

Most of the things that \mfp{} is designed to draw are paths. Examples
of paths are circles, rectangles,  other polygons, graphs of
functions and splines. Because we tend to want to draw these (or fill
them, or render them in other ways) we call the \mfp{} commands that
produce them \emph{figure macros}. Although they are much more complex
than numerics, pairs, or colors, they can still be stored in symbolic
names.

Normally in \mfp{} we want to create a picture, usually by rendering one
or more paths. It is possible in \MF{} to store a picture in a symbolic
name without actually drawing it. However, because of their complexity,
picture objects require somewhat more care than paths or other data
types. Do not expect to use stored pictures in the same way as stored
paths. In fact, one should use picture variables only in those command
that are explicitely designed for them. In \mfp{} to date these are only
\cs{tile...}\cs{endtile} and \cs{mfpimage} to store pictures, and
\cs{putmfpimage} to draw copies of one. There is also \cs{tess}, but it
is used only to fill a region with copies of a picture created by
\cs{tile}.

The boolean data type is one of the values \mfc{true} or \mfc{false}.
Boolean variables are symbolic names that can take either of these two
values. Usually these are used to influence the behavior of some command
by setting a relevant boolean variable to one or the other value.


\clearpage
\chapter{The Macros.}\label{macros}

Many of the commands of \mfp{} have optional arguments. These are
denoted just as in \LaTeX{}, with square brackets. Thus, the command for
drawing a circle can be given
\begin{verbatim}
\circle{(0,0),1}
\end{verbatim}
having only the mandatory argument, or
\begin{verbatim}
\circle[p]{(0,0),1}
\end{verbatim}
Whenever an optional argument is omitted, the behavior is equivalent to
some choice of the optional argument. In this example, the two forms
have exactly the same behavior, drawing a circle centered at $(0,0)$
with radius $1$. In this case we will say ``\oarg{p} is the
\emph{default}''. Another example is \cs{point}\marg{(1,0)} versus
\cs{point}\oarg{3pt}\marg{(1,0)}. They both place a dot at the point
$(1,0)$. The second one explicitly requests that it have diameter
\dim{3pt}; the first will examine the length command \cs{pointsize},
which the user can change, but it is initialized to \dim{2pt}. In this
case we will say ``the default is the value of \cs{pointsize},
\emph{initially} \dim{2pt}''.

If an \mfp{} command that takes an optional argument finds only empty
brackets (completely empty, no spaces), then it will use the default
value. This is useful for commands that have two optional arguments and
one wants the default value in the first one and some nondefault value
in the second. An optional argument should normally not contain any
spaces. Even when the argument contains more than one piece of data,
spaces should not separate the parts. In some cases (perhaps most) this
will cause no harm, but it would be better to avoid doing it altogether,
because it will cause wrong results or error messages in some cases.


\section{Files and Environments.}\label{files}

\begin{cd}\pagelabel{opengraphsfile}
\cs{opengraphsfile}\marg{\meta{file}}\\
  \ $\ldots$\\
\cs{closegraphsfile}%
\index{opengraphsfile@\cs{opengraphsfile}}%
\index{closegraphsfile@\cs{closegraphsfile}}
\end{cd}

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{\meta{file}.mf} (or \file{\meta{file}.mp}). Do \emph{not}
specify the extension, which is added automatically.

\emph{Note}: This command may cause \file{\meta{file}.mf} or
\file{\meta{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.

It is possible (but \emph{has not} been seriously tested) to close one
file and open another, and even to change between \opt{metapost} and
\opt{metafont} in between. If anything goes wrong with this, contact the
maintainer and it might be fixed in some later version.

\begin{cd}\pagelabel{mfpic}
\cs{mfpic}\oarg{\meta{xscale}}\oarg{\meta{yscale}}%
  \marg{\meta{xmin}}\marg{\meta{xmax}}\marg{\meta{ymin}}\marg{\meta{ymax}}\\
  \ $\ldots$\\
\cs{endmfpic}%
\index{mfpic@\cs{mfpic}}%
\index{endmfpic@\cs{endmfpic}}
\end{cd}

These macros open and close the \env{mfpic} environment%
    \footnote{We use the term `environment' loosely. However, in
    \LaTeX{} one may use an actual \env{mfpic} environment. See
    page~\pageref{envusage}.}
in which the drawing macros make sense. While many \mfp{} commands can
be used inside or outside this environment, those that actually produce
visible output are required to be inside. The \cs{mfpic} macro also sets
up the local coordinate system for the picture. The \meta{xscale} and
\meta{yscale} parameters establish the length of a coordinate system
unit, as a multiple of the \TeX{} dimension \cs{mfpicunit}. If neither
is specified, both are taken to be 1 and each coordinate system unit is
1 \cs{mfpicunit}. If only one is specified, then they are assumed to be
equal. Note that some drawing commands require equal scales to work as
expected: if you try to draw a circle with different scales you will get
an ellipse.

The \meta{xmin} and \meta{xmax} parameters establish the lower
and upper bounds for the $x$-axis coordinates; similarly, \meta{ymin}
and \meta{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 $(\meta{xmax}-\meta{xmin})\cdot\meta{xscale}$ times
\cs{mfpicunit}, its height $(\meta{ymax}-\meta{ymin})\cdot\meta{yscale}$
times \cs{mfpicunit}, and its depth zero.

Most of \mfp{}'s drawing macros accept parameters which are
\emph{coordinate pairs}. A coordinate pair is a pair of numbers $(x,y)$
enclosed in parentheses, with $\meta{xmin} \le x \le \meta{xmax}$ and
$\meta{ymin}
\le y \le \meta{ymax}$.%
    \footnote{These inequalities can be violated, usually causing
    something to be drawn outside the desired borders of the figure.}
We will call these \emph{graph coordinates} and refer to the numbers $x$
and $y$ as being \emph{in graph units}. Things like the thickness of
lines and the lengths of arrowheads are required to be expressed in
actual lengths such as \dim{1pt} or \dim{3mm}. These will be referred to as
\emph{absolute} units.

One can scale all pictures uniformly by changing \cs{mfpicunit}, and
scale an individual picture by changing \meta{xscale} and \meta{yscale}.
After loading \mfp{}, \cs{mfpicunit} has the value \dim{1pt}. One
\texttt{pt} is a \emph{printer's point}, which equals 1/72.27 inches or
0.35146 millimeters.

\emph{Note}: Changing \cs{mfpicunit} or the optional parameters will
scale the coordinate system, but not the values of parameters that are
defined in absolute units. If you wish, you can set these to multiples
of \cs{mfpicunit}, but it is difficult (and almost certainly unwise) to
get the thickness of lines (for example) 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 be sure to
reprocess the \TeX{} file after processing the \file{.mf} or \file{.mp}
file, even if no other changes are made in the figure.

\begin{cd}\pagelabel{mfpicnumber}
\cs{mfpicnumber}\marg{\meta{num}}%
\index{mfpicnumber@\cs{mfpicnumber}}
\end{cd}

Normally, \cs{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
\mfp{} to ignore this sequence and number the next \env{mfpic}
figure with \meta{num} (and the one after that $\meta{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 \cs{opengraphsfile}, as that
command checks for the existence of the first numbered figure to
determine if there are figures to be included.

\begin{cd}\pagelabel{everymfpic}
\cs{everymfpic}\marg{\meta{commands}}\\
\cs{everyendmfpic}\marg{\meta{commands}}%
\index{everymfpic@\cs{everymfpic}}%
\index{everyendmfpic@\cs{everyendmfpic}}%
\end{cd}

These commands store the \meta{commands}. The first arranges for these
commands to be issued first thing in every \env{mfpic} environment and
the second arranges for its commands to be issued as the last thing in
every such environment. These could be any commands that make sense
inside that environment. Their purpose is mainly to save typing if there
is identical setup being performed in every picture.

\begin{cd}\pagelabel{envusage}
\cs{begin}\marg{mfpic}\texttt{...}\cs{end}\marg{mfpic}%
\index{begin@\cs{begin}\marg{mfpic}}
\end{cd}

In \LaTeX{} you may prefer to use \cs{begin}\marg{mfpic} and
\cs{end}\marg{mfpic} (instead of \cs{mfpic} and \cs{endmfpic}). This is
by no means required. The sample file \file{lapictures.tex} provided
with \mfp{} illustrates this use of an \env{mfpic} environment in
\LaTeX{}.

\medskip
A word about \TeX{} groups inside \env{mfpic} environments. These can be
useful to limit the scope of declarations or of changes to some
variables. However, they do not limit the scope of changes to the figure
file that is being written, so there is a danger that \TeX{} and \MF{}
will have different values. There are also some \mfp{} command that need
to be at the outermost level. Thus, grouping should generaly be avoided
except for those groups provided by \mfp{} commands.

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

\section{Common objects.}\label{figures}

The \mfp{} macros that draw things can be roughly divided into two
classes.
\begin{enumerate}
  \item Those that simply cause something to be drawn. Examples of these
    are the \cs{point} command, which places a dot at a list of
    coordinates, and \cs{gridlines}, which draw coordinate lines with
    specified separation.
  \item Those that both \emph{define} and draw a \emph{path}. The macros
     \cs{circle}, \cs{rect}, and \cs{polyline} are examples of these.
\end{enumerate}

Macros of type 2 are referred to hereafter as \emph{figure macros}, for
lack of a better term. With them one can use \emph{prefix
macros}\index{prefix macro} to modify various aspects of the path and
how it is drawn. For example,
\begin{verbatim}
\polyline{(1,2),(3,4)}
\end{verbatim}
draws a line from $(1,2)$ to $(3,4)$, but
\begin{verbatim}
\dotted\polyline{(1,2),(3,4)}
\end{verbatim}
produces a dotted version, and
\begin{verbatim}
\arrow\polyline{(1,2),(3,4)}
\end{verbatim}
draws it with an arrowhead at the tip. This is not possible with
\cs{gridlines}, for example. As \mfp{} and the accompanying \MF{}
package \grafbase{} are currently written, prefix macros can only be
applied to single paths, and \cs{gridlines} produces a whole set of
lines. In this manual, as each macro is introduced, if it is a figure
macro, this will be explicitly stated.

Some commands depend on the value of separately defined parameters. all
these parameters are initialized when \mfp{} is loaded. In the following
descriptions we give the initial value of all the relevant parameters.
When \MP{} output is selected, figures can be drawn in any color.
several of the above mentioned parameters are colors. \mfp{} provides
commands to change any of these parameters. To save repetition: all
special colors for figures are initialized to \mfc{black} except
\mfc{background}, which is white.


\subsection{Points, lines, and rectangles}\label{points}

\begin{cd}\pagelabel{point}
\cs{point}\oarg{\meta{size}}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}%
\index{point@\cs{point}}
\end{cd}

Draws small disks centered at the points specified in the list of
ordered pairs. The optional argument \meta{size} is an absolute
dimension that determines the diameter of the disks. The default is the
\TeX{} dimension \cs{pointsize}, initially \dim{2pt}. The disks have a
filled interior if the command \cs{pointfilltrue} has been issued (the
initial behavior). After the command \cs{pointfillfalse}, \cs{point}
commands will produce outlined circles with the interiors erased. The
color of the circles is the value of the predefined variable
\gbc{pointcolor}, and the color inside of the open circles is the value
of the variable \mfc{background}.%
    \footnote{\MP{} cannot actually erase. The illusion of erasing is
    created by painting over with \mfc{background}.}

\begin{cd}\pagelabel{plotsymbol}
\cs{plotsymbol}\oarg{\meta{size}}\marg{\meta{symbol}}%
\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}%
\index{plotsymbol@\cs{plotsymbol}}
\end{cd}

Draws small symbols centered at the points \meta{$p_0$}, \meta{$p_1$},
and so on. The symbols must be given by name, and the available symbols
are:
\begin{display}
\gbc{Asterisk}\index{Asterisk@\gbc{Asterisk}},
\gbc{Circle}\index{Circle@\gbc{Circle}},
\gbc{Diamond}\index{Diamond@\gbc{Diamond}},
\gbc{Square}\index{Square@\gbc{Square}},
\gbc{Triangle}\index{Triangle@\gbc{Triangle}},
\gbc{Star}\index{Star@\gbc{Star}},
\gbc{SolidCircle}\index{SolidCircle@\gbc{SolidCircle}},\\
\gbc{SolidDiamond}\index{SolidDiamond@\gbc{SolidDiamond}},
\gbc{SolidSquare}\index{SolidSquare@\gbc{SolidSquare}},
\gbc{SolidTriangle}\index{SolidTriangle@\gbc{SolidTriangle}},
\gbc{SolidStar}\index{SolidStar@\gbc{SolidStar}},
\gbc{Cross}\index{Cross@\gbc{Cross}} and
\gbc{Plus}\index{Plus@\gbc{Plus}}.
\end{display}
The names should be self-explanatory, the `\gbc{Solid}' ones are filled
in, the others are outlines. Under \opt{metapost}, symbols are drawn in
\gbc{pointcolor}. The \meta{size} defaults to \cs{pointsize} as in
\cs{point} above. \gbc{Asterisk} consists of six line segments while
\gbc{Star} is the standard five-pointed star formed from ten straight
line segments. \gbc{Cross} is a $\times$ shape. The name
`\cs{plotsymbol}' comes from the fact that the \cs{plot} command (see
subsection~\ref{drawing}), which was written first, utilizes these same
symbols. The command \cs{symbol} was already taken (standard \LaTeX{}).

While one would rarely want to use them for this purpose, the following
symbols are also available:
\begin{display}
\gbc{Arrowhead}\index{Arrowhead@\gbc{Arrowhead}},
\gbc{Crossbar}\index{Crossbar@\gbc{Crossbar}},
\gbc{Leftbar}\index{Leftbar@\gbc{Leftbar}},
\gbc{Rightbar}\index{Rightbar@\gbc{Rightbar}},
\gbc{Lefthook}\index{Lefthook@\gbc{Lefthook}},
\gbc{Righthook}\index{Righthook@\gbc{Righthook}},
\gbc{Leftharpoon}\index{Leftharpoon@\gbc{Leftharpoon}},\\
\gbc{Rightharpoon}\index{Rightharpoon@\gbc{Rightharpoon}}.
\end{display}
These are mainly intended for making arrows. See subsection~\ref{arrows}
for a further description.

The difference between \cs{pointfillfalse}\cs{point}$\ldots$ and
\cs{plotsymbol}\marg{Circle}$\ldots$ is that the inside of the circle
will not be erased in the second version, so whatever else has already
been drawn in that area will remain visible. This is the default (for
backward compatibility), but that can be changed with the commands
below.

\begin{cd}\pagelabel{clearsymbols}
\cs{clearsymbols}\\
\cs{noclearsymbols}%
\index{clearsymbols@\cs{clearsymbols}}%
\index{noclearsymbols@\cs{noclearsymbols}}
\end{cd}

After the first of these two commands, subsequent \cs{plotsymbol}
commands will draw the open symbols with their interiors erased. After
the second, the default behavior (described above) will be restored.
These commands have no effect on \cs{point}. \cs{plotnodes} (see
subsection~\ref{drawing}) also responds to the settings made by these
commands. The \cs{plot} command (also in subsection~\ref{drawing}) does
not.

You can design your own `symbols'. See the discussion of arrowheads in
subsection~\ref{arrows}, and of storing paths in
subsection~\ref{transformation}.

\begin{cd}\pagelabel{pointdef}
\cs{pointdef}\marg{\meta{name}}\texttt{(\meta{xcoord},\meta{ycoord})}%
\index{pointdef@\cs{pointdef}}
\end{cd}

Defines a symbolic name for an ordered pair and the coordinates it
contains. \meta{name} is any legal \TeX{} command name \emph{without}
the backslash; \meta{xcoord} and \meta{ycoord} are any numbers. For
example, after the command \cs{pointdef}\marg{A}\texttt{(1,3)}, \cs{A}
expands to \texttt{(1,3)}, while \cs{Ax} and \cs{Ay} expand to
\texttt{1} and \texttt{3}, respectively. If \opt{mplabels} is in effect
one can use \cs{A} to specify where to place a text label, but if \TeX{}
is placing labels one must use \texttt{ (\cs{Ax},\cs{Ay})}. In most
other cases, one can use \cs{A} where a pair or point is required.

\begin{cd}\pagelabel{polyline}
\cs{polyline}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}\\
\cs{lines}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}%
\index{polyline@\cs{polyline}}%
\index{lines@\cs{lines}}
\end{cd}

The figure macro \cs{polyline} produces connected line segments from
\meta{$p_0$} to \meta{$p_1$}, and from there to \meta{$p_2$}, etc. The
result is an open polygonal path through the specified points, in the
specified order. The macro \cs{lines} is an alias for \cs{polyline}.

\begin{cd}\pagelabel{polygon}
\cs{polygon}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}\\
\cs{closedpolyline}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}%
\index{polygon@\cs{polygon}}%
\index{closedpolyline@\cs{closedpolyline}}
\end{cd}

The figure macros \cs{polygon} produces a closed polygon with vertices
at the specified points in the specified order. It works exactly like
\cs{polyline} except the last point in the list is also joined to the
first. The macro \cs{closedpolyline} is an alias for \cs{polygon}.

\begin{cd}\pagelabel{rect}
\cs{rect}\marg{\meta{$p_0$},\meta{$p_1$}}%
\index{rect@\cs{rect}}
\end{cd}

This figure macro produces the closed rectangle with horizontal and
vertical sides, having the points \meta{$p_0$} and \meta{$p_1$} as
diagonally opposite corners. The same rectangle can be specified in four
different ways: either pair of opposite corners in either order.

It is occasionally helpful to know that connected paths like those
produced by \cs{polyline} or \cs{rect} have a \emph{start} and an
\emph{end} as well as \emph{sense} (or direction). The path produced by
\cs{polyline} starts at the first listed pint and ends at last, having
the direction determined by the order of the points. For \cs{rect} the
sense may be clockwise or anticlockwise depending on the corners used:
it starts by moving horizontally from the first listed point.
Several \mfp{} macros (such as those that add arrowheads) treat the
beginning and the end of a path differently, or adjust their behavior
according to the sense of the curve.

\begin{cd}\pagelabel{regpolygon}
\cs{regpolygon}\marg{\meta{num}}\marg{\meta{name}}%
  \marg{\meta{eqn$_1$}}\marg{\meta{eqn$_2$}}%
\index{regpolygon@\cs{regpolygon}}
\end{cd}

This figure macro produces a closed regular polygon with \meta{num}
sides. The second argument, \meta{name} is a symbolic name. It can be
used to refer to the vertices later. The last two arguments should be
equations that position two of the vertices or one vertex and the
center. The center is referred to by \meta{name}\gbc{0} and the vertices
by \meta{name}\gbc{1} \meta{name}\gbc{2}, etc., going anticlockwise
around the polygon. The \meta{name} itself (without a number suffixed)
will be a \MF{} variable assigned the value of \meta{num}. For example,
\begin{verbatim}
\regpolygon{5}{Kay}{Kay0=(0,1)}{Kay1=(2,0)}
\end{verbatim}
will produce a regular pentagon with its center at $(0,1)$ and its first
vertex at $(2,0)$. One could later draw a star inside it with
\begin{verbatim}
\polygon{Kay1,Kay3,Kay5,Kay2,Kay4}
\end{verbatim}
Moreover, \gbc{Kay} will equal $5$. The name given becomes a \MF{}
variable and care should be taken to make the name distinctive so as not
to redefine some internal variable.

\subsection{A word about list arguments}\label{list}

We have seen already four \mfp{} macros that take a mandatory argument
consisting of an arbitrary number of coordinate pairs, separated by
commas. There are many more, and some that take a comma-separated list
of items of other types. If the lists are long, especially if they are
generated by a program, it might be more convenient if one could simply
refer to an external file for the data. This is possible, and one does
it the following way: instead of \cs{polyline}\marg{\meta{list}}, one
can write\index{datafile@\cs{datafile}}
\begin{ex}
  \cs{polyline}\cs{datafile}\marg{\meta{filename}}
\end{ex}
where \meta{filename} is the full name of the file containing the data.
The required format of this file and the details of this usage can be
found in subsection~\ref{external}. This method is available for any
command that takes a comma-separated list of data (of arbitrary length)
as its last argument, \emph{with the exception of those commands that
add text to the picture}. Examples of the latter are \cs{plottext} and
\cs{axislabels} (subsection~\ref{text}).


\subsection{Axes, axis marks, and grids}\label{axesthings}

\begin{cd}\pagelabel{axes}
\cs{axes}\oarg{\meta{hlen}}\\
\cs{xaxis}\oarg{\meta{hlen}}\\
\cs{yaxis}\oarg{\meta{hlen}}%
\index{axes@\cs{axes}}%
\index{xaxis@\cs{xaxis}}%
\index{yaxis@\cs{yaxis}}
\end{cd}

These are retained for backward compatibility, but there are more
flexible alternatives below. They draw $x$- and  $y$-axes for the
coordinate system. The command \cs{axes} is equivalent to \cs{xaxis}
followed by \cs{yaxis} which produce the obvious. The $x$- and $y$-axes
extend the full width and height of the \env{mfpic} environment. The
optional \meta{hlen} sets the length of the arrowhead on each axis. The
default is the value of the \TeX{} dimension \cs{axisheadlen}, initially
\dim{5pt}. The shape of the arrowhead is determined as in the \cs{arrow}
macro (section~\ref{modifier}). The color of the head is the value of
\gbc{headcolor}, the shaft is \gbc{drawcolor}.

Unlike other commands that produce lines or curves, these do not respond
to prefix macros. They always draw a solid line (with an arrowhead
unless \cs{axisheadlen} is \dim{0pt}). They \emph{do} respond to changes
in the pen thickness (see \cs{penwd} in section~\ref{parameters}) but
that is pretty much the only possibility for variation.

\begin{cd}\pagelabel{axis}
\cs{axis}\oarg{\meta{hlen}}\marg{\meta{one-axis}}\\
\cs{doaxes}\oarg{\meta{hlen}}\marg{\meta{axis-list}}%
\index{axis@\cs{axis}}%
\index{doaxes@\cs{doaxes}}%
\end{cd}

These produce any of 6 different axes. The parameter \meta{one-axis} can
be \texttt{x} or \texttt{y}, to produce (almost) the equivalent of
\cs{xaxis} and \cs{yaxis}; or it can be \texttt{l}, \texttt{b},
\texttt{r}, or \texttt{t} to produce an axis on the border of the
picture (left, bottom, right or top, respectively). \cs{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:
\cs{doaxes}\marg{lbrt}. The optional argument sets the length of the
arrowhead. In the case of axes on the edges, the default is the value of
\cs{sideheadlen}, which \mfp{} initializes to \dim{0pt}. For the $x$-
and $y$-axis the default is \cs{axisheadlen} as in \cs{xaxis} and
\cs{yaxis} above.

The commands \cs{axis}\marg{x}, \cs{axis}\marg{y}, and
\cs{doaxes}\marg{xy} differ from the old \cs{xaxis}, \cs{yaxis} and
\cs{axes} in that these new versions respond to prefix macros. The
\cs{arrow} prefix previously mentioned is an exception: these macros add
an arrowhead automatically. For example, the sequence
\cs{dotted}\cs{axis}\marg{x} draws a dotted $x$-axis, but
\cs{dotted}\cs{xaxis} produces a \MF{} error. A prefix macro applied to
\cs{doaxes} generates no error, but only the first axis in the list will
be affected.

\begin{cd}\pagelabel{axisline}
\cs{axisline}\marg{\meta{one-axis}}\\
\cs{border}%
\index{axisline@\cs{axisline}}%
\index{border@\cs{border}}%
\end{cd}

These are figure macros that draw the line or lines that an \cs{axis}
command would draw. An \cs{axis} command is almost the equivalent of
\begin{display}
\cs{arrow}\oarg{l\meta{hlen}}\cs{axisline}\marg{\meta{one-axis}}.
\end{display}
The \cs{axisline} command is provided as a figure macro for maximum
flexibility. For example, one can use the star-form of the \cs{arrow}
command if desired or decorate it with ones own choice of arrowhead (see
subsection~\ref{arrows}).

Also a figure macro, \cs{border} produces the rectangle which, if drawn,
is visibly the same as the four border \cs{axisline}\,s (without heads).
It is a closed path and could easily be drawn with a \cs{rect} command,
but the \cs{border} command automatically adjusts for the margins set by
the commands below.

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

Axes on the edges are drawn so that they don't cross each other.
\cs{doaxes}\marg{lbrt}, for example, produces a perfect rectangle. If the
$x$- and $y$-axis are drawn with \cs{axis} or \cs{doaxes}, 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.

\begin{cd}\pagelabel{axismargin}
\cs{axismargin}\marg{\meta{one-axis}}\marg{\meta{num}}\\
\cs{setaxismargins}%
  \marg{\meta{num}}\marg{\meta{num}}\marg{\meta{num}}\marg{\meta{num}}\\
\cs{setallaxismargins}\marg{\meta{num}}%
\index{axismargin@\cs{axismargin}}%
\index{setaxismargins@\cs{setaxismargins}}%
\index{setallaxismargins@\cs{setallaxismargins}}%
\end{cd}

The parameter \meta{one-axis} is one of the letters \texttt{l},
\texttt{b}, \texttt{r}, or \texttt{ t}, and \cs{axismargin} causes the
given axis to be shifted \emph{inward} by the \meta{num} specified (in
\emph{graph} units). The second command \cs{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_{\mathrm{lft}}$, $M_{\mathrm{bot}}$, $M_{\mathrm{rt}}$ and
$M_{\mathrm{top}}$, then \cs{axis}\marg{b} draws a line starting
$M_{\mathrm{lft}}$ graph units from the left edge and ending
$M_{\mathrm{rt}}$ units from the right edge. Of course, the entire line
is $M_{\mathrm{bot}}$  units above the bottom edge. The margins are also
respected by the $x$- and $y$-axis, but only when drawn with \cs{axis}.
The old \cs{xaxis}, \cs{yaxis} and \cs{axes} ignore them.

Special effects can be achieved by lying to one axis about the other
margins. That is, axes can be draw in separate commands with changes to
the declared margins in between. Be aware that various other commands
are affected by the margin values. Examples are the already mentioned
\cs{border}, as well as \cs{grid} and \cs{gridlines}
(page~\pageref{grid} in this subsection).

\begin{cd}\pagelabel{axismarks}
\cs{xmarks}\oarg{\meta{len}}\marg{\meta{numberlist}}\\
\cs{ymarks}\oarg{\meta{len}}\marg{\meta{numberlist}}\\
\cs{lmarks}\oarg{\meta{len}}\marg{\meta{numberlist}}\\
\cs{bmarks}\oarg{\meta{len}}\marg{\meta{numberlist}}\\
\cs{rmarks}\oarg{\meta{len}}\marg{\meta{numberlist}}\\
\cs{tmarks}\oarg{\meta{len}}\marg{\meta{numberlist}}\\
\cs{axismarks}\marg{\meta{axis}}\oarg{\meta{len}}\marg{\meta{numberlist}}%
\index{xmarks@\cs{xmarks}}%
\index{tmarks@\cs{tmarks}}%
\index{bmarks@\cs{bmarks}}%
\index{ymarks@\cs{ymarks}}%
\index{lmarks@\cs{lmarks}}%
\index{rmarks@\cs{rmarks}}%
\index{axismarks@\cs{axismarks}}
\end{cd}

These macros place hash marks on the appropriate axes at the places
indicated by the values in the list. The optional \meta{len} gives the
length of the hash marks. If \meta{len} is not specified, the \TeX{}
dimension \cs{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
appendix~\ref{mpconsiderations}.) The command \cs{axismarks}\marg{x} is
equivalent to \cs{xmarks} and so on for each of the six axes. (I would
have used the shorter name \cs{marks}, but that name was already taken
by e\kern-.16em\TeX{}.)

The \meta{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:
\begin{verbatim}
\xmarks{-2 step 1 until 2}
\end{verbatim}
is the equivalent of
\begin{verbatim}
\xmarks{-2,-1,0,1,2}
\end{verbatim}

One must use exactly the words \mfc{step} and \mfc{until}. Spaces are
not needed unless a variable name is used in place of one of the
numbers (see subsection~\ref{variables}). The number of spaces is not
significant.%
    \footnote{Experienced \MF{} programmers may recognize that anything
    can be used that is permitted in \MF{}'s \meta{forloop} syntax. Thus
    the given example can also be reworded \cs{xmarks}\marg{-2 upto 2},
    or even \cs{xmarks}\marg{2 downto -2}. See subsection~\ref{loops}
    for more on for-loops in \mfp{}.} %
Users of this syntax should be aware that if any of the numbers is not
an integer then, because of natural round-off effects, the last value
might be overshot and a mark not printed there. For example, to ensure
that a mark is printed at the point $1.0$ on the $x$-axis, the second
line below is better than the first.
\begin{verbatim}
\xmarks{0 step .2 until 1.0}
\xmarks{0 step .2 until 1.1}
\end{verbatim}

\begin{cd}\pagelabel{setaxismarks}
\cs{setaxismarks}\marg{\meta{axis}}\marg{\meta{pos}}\\
\cs{setbordermarks}\marg{\meta{lpos}}\marg{\meta{bpos}}\marg{\meta{rpos}}\marg{\meta{tpos}}\\
\cs{setallbordermarks}\marg{\meta{pos}}\\
\cs{setxmarks}\marg{\meta{pos}}\\
\cs{setymarks}\marg{\meta{pos}}%
\index{setaxismarks@\cs{setaxismarks}}%
\index{setbordermarks@\cs{setbordermarks}}%
\index{setallbordermarks@\cs{setallbordermarks}}%
\index{setxmarks@\cs{setxmarks}}%
\index{setymarks@\cs{setymarks}}%
\end{cd}

These set the placement of the hash marks relative to the axis. The
parameter \meta{axis} is one of the letters \texttt{x}, \texttt{y}, \texttt{l},
\texttt{b}, \texttt{r}, or \texttt{t}, and \meta{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
\cs{setaxismarks}\marg{x}\marg{\meta{pos}} and
\cs{setaxismarks}\marg{y}\marg{\meta{pos}}, respectively.

Not all combinations make sense (for example,
\cs{setaxismarks}\marg{r}\marg{ontop}). In these cases, no error message
is produced: \gbc{ontop} and \gbc{onleft} give the same results, as do
\gbc{onbottom} and \gbc{onright}. The parameters \gbc{inside} and
\gbc{outside} make no sense for the $x$- and $y$-axes, but if they are
used then \gbc{inside} means \gbc{ontop} for the $x$-axis and
\gbc{onright} for the $y$-axis. These words are actually \MF{} numeric
variables and the variables \gbc{ontop} and \gbc{onleft}, for example,
have the same value.

\begin{cd}\pagelabel{grid}
\cs{grid}\oarg{\meta{size}}\marg{\meta{xsep},\meta{ysep}}\\
\cs{gridpoints}\oarg{\meta{size}}\marg{\meta{xsep},\meta{ysep}}\\
\cs{lattice}\oarg{\meta{size}}\marg{\meta{xsep},\meta{ysep}}\\
\cs{hgridlines}\marg{\meta{ysep}}\\
\cs{vgridlines}\marg{\meta{xsep}}\\
\cs{gridlines}\marg{\meta{xsep},\meta{ysep}}%
\index{grid@\cs{grid}}%
\index{gridpoints@\cs{gridpoints}}%
\index{lattice@\cs{lattice}}%
\index{vgridlines@\cs{vgridlines}}%
\index{hgridlines@\cs{hgridlines}}%
\index{gridlines@\cs{gridlines}}%
\end{cd}

\cs{grid} draws a dot at every point for which the first coordinate is
an integer multiple of the \meta{xsep} and the second coordinate is an
integer multiple of \meta{ysep}. The diameter of the dot is determined
by \meta{size}. The default is the value of \cs{griddotsize},
initially \dim{0.5pt}. Under the \opt{metapost} option, the color of the
dot is \gbc{pointcolor}. The commands \cs{gridpoints and \cs{lattice}}
are synonyms for \cs{grid}.

\cs{hgridlines} draws the horizontal and \cs{vgridlines} the vertical
lines through these same points. \cs{gridlines} draws both sets of
lines. The thickness of the lines is set by \cs{penwd}. Authors are
recommended to either reduce the pen width or change \gbc{drawcolor} to
a lighter color for grid lines. Or omit them entirely: well-designed
graphs usually don't need them and almost never should both horizontals
and verticals be used.

The above commands draw their dots and lines within the margins set by the
axis margin commands on page~\pageref{axismargin}.

\begin{cd}\pagelabel{plrgrid}
\cs{plrgrid}\marg{\meta{rsep},\meta{anglesep}}\\
\cs{gridarcs}\marg{\meta{rsep}}\\
\cs{gridrays}\marg{\meta{anglesep}}\\
\cs{plrpatch}\marg{\meta{rmin},\meta{rmax},\meta{rsep},%
    \meta{tmin},\meta{tmax},\meta{tsep}}\\
\cs{plrgridpoints}\oarg{\meta{size}}\marg{\meta{rsep},\meta{anglesep}}%
\index{plrgrid@\cs{plrgrid}}%
\index{plrpatch@\cs{plrpatch}}%
\index{gridarcs@\cs{gridarcs}}%
\index{gridrays@\cs{gridrays}}%
\index{plrgridpoints@\cs{plrgridpoints}}%
\end{cd}

\cs{plrgrid} fills the graph with circular arcs and radial lines.
\cs{gridarcs} draws only the arcs, \cs{gridrays} only the radial lines.
\cs{plrgridpoints} places a dot (diameter \meta{size}) at all the places
the rays and arcs would intersect. It takes an optional argument for the
size of the dots, the default being \cs{griddotsize}, the same as the
\cs{grid} command.

The arcs lie on circles centered at $(0,0)$ and the rays would all meet
at $(0,0)$ if extended. The corresponding \MF{} commands actually draw
just enough to cover the graph area and then clip them to the graph
boundaries. If you don't want them clipped, use \cs{plrpatch}. Unlike
the rectangular coordinate grid commands, these do not respect the axis
margins (rectangular margins don't really belong with polar coordinates).

\cs{plrpatch} draws arcs with radii starting at \meta{rmin}, stepping by
\meta{rsep} and ending with \meta{rmax}. Each arc goes from angle
\meta{tmin} to \meta{tmax}. It also draws radial lines with angles
starting at \meta{tmin}, stepping by \meta{tsep} and ending with
\meta{tmax}. Each line goes from radius \meta{rmin} to \meta{rmax}. If
$\meta{rmax}-\meta{rmin}$ doesn't happen to be a multiple of
\meta{rsep}, the arc with radius \meta{rmax} is drawn anyway. The same
is true of the line at angle \meta{tmax}, so that the entire boundary is
always drawn.

If \meta{tsep} is larger than \meta{tmax}${}-{}$\meta{tmin}, then only
the boundary rays will be drawn. If \meta{rsep} is larger than
\meta{rmax}${}-{}$\meta{rmin}, then only the boundary arcs will be
drawn.

The color used for rays and arcs is \gbc{drawcolor}, and for dots
\gbc{pointcolor}. The advice about color and use of \cs{gridlines} holds
for \cs{plrgrid} and its relatives as well.

\begin{cd}\pagelabel{vectorfield}
\cs{vectorfield}\oarg{\meta{hlen}}\marg{\meta{xsp},\meta{ysp}}%
\marg{\meta{formula}}\marg{\meta{restriction}}\\
\cs{plrvectorfield}\oarg{\meta{hlen}}\marg{\meta{rsp},\meta{tsp}}%
\marg{\meta{formula}}\marg{\meta{restriction}}%
\index{vectorfield@\cs{vectorfield}}%
\index{plrvectorfield@\cs{plrvectorfield}}
\end{cd}

These commande draw a field of vectors (arrows). The optional argument
is the length of the arrowhead, the default being the dimension
\cs{headlen}, initially \dim{3pt}.

For \cs{vectorfield}, an arrow is drawn starting from each point $(x,y)$
where $x$ is an integer multiple of \meta{xsp} and $y$ is an integer
multiple of \meta{ysp}. The vector field is given by \meta{formula},
which should be a pair-valued expression in the literal variables
\mfc{x} and \mfc{y}. Typically that would be a pair of numeric
expressions enclosed in parentheses and separated by a comma. The last
argument is a boolean expression in the literal variables \mfc{x} and
\mfc{y}, used to restrict the domain. That is, if the expression is
false for some $(x,y)$, no arrow is drawn at that point. If you do not
wish to restrict the domain, type \texttt{true} for the restriction.

For \cs{plrvectorfield}, an arrow is drawn starting from each point with
polar coordinates $(r,\theta)$ if $r$ is an integer multiple of
\meta{rsp} and $\theta$ is an integer multiple of \meta{tsp}. In this
case, the \meta{formula} must be a pair-valued expression in the literal
variables \mfc{r} and \mfc{t}. This should be (or produce) a pair of $x$
and $y$ coorinates, not a polar coordinate pair. If you have formulas
$R(r,\theta)$ for the length of each vector and $T(r,\theta)$ for the
angle, then the following will convert to $(x,y)$ pairs:
\begin{verbatim}
{polar (R(r,t),T(r,t))}
\end{verbatim}
The last argument is as in \cs{vectorfield}, except it should depend on
the literal variables \mfc{r} and \mfc{t}.

In either case, the arrow is not drawn if the starting point would lie
within the margins set with \cs{axismargins} and its relatives.

The following draws a rotational field, omitting the inside of the
circle of radius $1$, where the arrows would be excessively long, and
especially avoiding $(0,0)$ where the vector field is undefined.
\begin{verbatim}
\vectorfield[2.5pt]{.25,.25}{.5*(-y,x)/(x**2 + y**2)}{x**2 + y**2 >= 1}
\end{verbatim}
The following is the same field, represented by arrows whose locations
are regularly spaced in polar coordinates.
\begin{verbatim}
\plrvectorfield[2.5pt]{.25,20}{polar(.5/r,t+90)}{r >= 1}
\end{verbatim}


\subsection{Circles, arcs and ellipses}\label{circles}

\begin{cd}\pagelabel{circle}
\cs{circle}\oarg{\meta{format}}\marg{\meta{specification}}%
\index{circle@\cs{circle}}%
\end{cd}

This figure macro produces a circle. Starting with \mfp{} version 0.7,
there are more than one way to specify a circle. In version 0.8 and
later there are six ways, and one selects which one by giving
\cs{circle} an optional argument that signals what data will be
specified in the mandatory argument.

\begin{cd}
\cs{circle}\oarg{p}\marg{\meta{$c$},\meta{$r$}}\\
\cs{circle}\oarg{c}\marg{\meta{$c$},\meta{$p$}}\\
\cs{circle}\oarg{t}\marg{\meta{$p_1$},\meta{$p_2$},\meta{$p_3$}}\\
\cs{circle}\oarg{s}\marg{\meta{$p_1$},\meta{$p_2$},\meta{$\theta$}}\\
\cs{circle}\oarg{r}\marg{\meta{$p_1$},\meta{$p_2$},\meta{$r$}}\\
\cs{circle}\oarg{q}\marg{\meta{$p_1$},\meta{$p_2$},\meta{$r$}}%
\index{circle@\cs{circle}}%
\end{cd}

The optional arguments produce circles according to the following
descriptions.
\begin{description}
\item[\oarg{p}] The \textit{Polar form} is the default. The data in the
mandatory argument should then be the center \meta{c} and radius
\meta{r} of the circle.

\item[\oarg{c}] The \textit{center-point form}. In this case the data
should be the center and one point on the circumference.

\item[\oarg{t}] The \textit{three-point form}. The data are three points
that do not lie in a straight line.

\item[\oarg{s}] The \textit{point-sweep form}. The data are two points on the
circle, followed by the angle of arc between them.

\item[\oarg{r}] The \textit{point-radius form}. The data are two points on the
circle, followed by the radius. There are two circles with this data.
The one that makes the angle from the first to the second point positive
and less than 180 degrees is produced.

\item[\oarg{q}] The \textit{alternate point-radius form}. The data are
the same as for the \oarg{r} case, except the other circle is produced.
\end{description}
These optional arguments are also used in the \cs{arc} command (see
below). The \cs{circle} command draws the whole circle of which the
corresponding \cs{arc} command draws only a part. The sense of the
circle produced is anticlockwise except in the case \texttt{[t]}, where
it is the direction determined by the order of the three points, and the
case \texttt{[s]}, where it is determined by \meta{$\theta$}: clockwise
if negative, anticlockwise if positive.


\begin{cd}\pagelabel{arc}
\cs{arc}\oarg{\meta{format}}\marg{\meta{specification}}\\
\cs{arc*}\oarg{\meta{format}}\marg{\meta{specification}}%
\index{arc@\cs{arc}}%
\end{cd}

This figure macro produces a circular arc specified as determined by the
\meta{format} optional parameter. As with \cs{circle}, the optional
\meta{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. The starting point of each arc is at the
first specified angle or point and the ending point is at the last one.

The star-form produces the complementary arc. That is, instead of the
arc described below, it produces the rest of the circle from the ending
point to the starting point of the arc described.

\begin{cd}
\cs{arc}\oarg{s}\marg{\meta{$p_0$},\meta{$p_1$},\meta{$\theta$}}\\
\cs{arc}\oarg{p}\marg{\meta{$c$},\meta{$\theta_1$},\meta{$\theta_2$},\meta{$r$}}\\
\cs{arc}\oarg{a}\marg{\meta{$c$},\meta{$r$},\meta{$\theta_1$},\meta{$\theta_2$}}\\
\cs{arc}\oarg{c}\marg{\meta{$c$},\meta{$p_1$},\meta{$\theta$}}\\
\cs{arc}\oarg{t}\marg{\meta{$p_0$},\meta{$p_1$},\meta{$p_2$}}\\
\cs{arc}\oarg{r}\marg{\meta{$p_0$},\meta{$p_1$},\meta{$r$}}\\
\cs{arc}\oarg{q}\marg{\meta{$p_0$},\meta{$p_1$},\meta{$r$}}%
\index{arc@\cs{arc}}%
\end{cd}

The optional arguments produce arcs according to the following
descriptions.
\begin{description}
\item[\oarg{s}] The \textit{point-sweep form} is the default format. It
draws the circular arc starting from the point \meta{$p_0$}, ending at
the point \meta{$p_1$}, and covering an arc angle of \meta{$\theta$}
degrees, measured anticlockwise around the center of the circle. If,
for example, the points \meta{$p_0$} and \meta{$p_1$} lie on a
horizontal line with \meta{$p_0$} to the \emph{left}, and \meta{$\theta$}
is between 0~and 360 (degrees), then the arc will sweep \emph{below} the
horizontal line (in order for the arc to be anticlockwise). A
negative value of \meta{$\theta$} gives a clockwise arc from \meta{$p_0$}
to \meta{$p_1$}.

\item[\oarg{p}] The \textit{polar form} draws the arc of a circle with
center \meta{$c$} starting at the angle \meta{$\theta_1$} and ending at
the angle \meta{$\theta_2$}, with radius \meta{$r$}. Both angles are
measured anticlockwise from the positive $x$ axis.

\item[\oarg{a}] The \textit{alternate polar form} draws the arc of a
circle with center \meta{$c$} and radius \meta{$r$}, starting at the
angle \meta{$\theta_1$} and ending at the angle \meta{$\theta_2$}. Both
angles are measured anticlockwise from the positive $x$ axis. This is
provided because it seems a more reasonable order of arguments, and
matches the order \cs{sector} requires (see below). The \texttt{p}
option is retained for backward compatibility.

\item[\oarg{c}] The \textit{center-point-angle form} draws the circular
arc with center \meta{$c$}, starting at the point \meta{$p_1$}, and
sweeping an angle of \meta{$\theta$} around the center from that point.
(This and the point sweep form are the basic methods of handling
arcs---the previous three formats are translated to one of these two
before drawing.)

\item[\oarg{t}] The \textit{three-point form} draws the circular arc
which passes through all three points given, in the order given.
Internally, this is converted to two applications of the point-sweep
form.

\item[\oarg{r}] The \textit{point-radius form} draws the circular arc
starting at the point \meta{$p_0$}, ending at \meta{$p_1$},
with radius \meta{$r$}. Of the four possible arcs on two possible
circles, it produces the one that covers an arc angle $\theta$
no more than $180$ degrees measured anticlockwise around the center
of the circle. To get the similar arc on the other circle, reverse the
order of the points.

\item[\oarg{q}] The \textit{alternate point-radius form} is the same as
\oarg{r} except it produces the arc that covers an angle $\theta$
\emph{no less than} $180$ degrees measured anticlockwise around the
center of the circle. To get the similar arc on the other circle,
reverse the order of the points.

For both options \oarg{r} and \oarg{q}, if the radius is less than half
the distance between the points, then no such arc exists. In this case,
the command uses a radius equal to half the distance. The difference
between negating the radius and reversing the points is the sense of
the resulting path: it always starts at the first point and ends at the
second.
\end{description}

\begin{cd}\pagelabel{sector}
\cs{sector}\marg{\meta{$c$},\meta{$r$},\meta{$\theta_1$},\meta{$\theta_2$}}%
\index{sector@\cs{sector}}%
\end{cd}

This figure macro produces the sector of the circle with center at the
point \meta{$c$} and radius \meta{$r$}, from the angle \meta{$\theta_1$}
to the angle \meta{$\theta_2$}. Both angles are measured in degrees
anticlockwise from the direction parallel to the $x$ axis. The sector
forms a closed path. \emph{Note}: \cs{sector} and \cs{arc}\oarg{p} have
the same parameters, but \emph{in a different order}.%
    \footnote{This apparently was unintended, but we now have to live
    with it so as not to break existing \file{.tex} files.}


\begin{cd}\pagelabel{ellipse}
\cs{ellipse}\oarg{\meta{$\theta$}}\marg{\meta{$c$},\meta{$r_x$},\meta{$r_y$}}%
\index{ellipse@\cs{ellipse}}%
\end{cd}

This figure macro produces an ellipse with the $x$ radius \meta{$r_x$}
and $y$ radius \meta{$r_y$}, centered at the point \meta{$c$}. The
optional parameter \meta{$\theta$} provides a way of rotating the
ellipse by \meta{$\theta$} degrees anticlockwise around its center.
Ellipses may also be created by differentially scaling a circle and
perhaps rotating the result. See subsection~\ref{transformation}.


When dealing with arcs and circles, it is useful to work in polar
coordinates:

\begin{cd}\pagelabel{plr}
\cs{plr}\marg{(\meta{$r_0$},\meta{$\theta_0$}),%
  (\meta{$r_1$},\meta{$\theta_1$}), $\ldots$}%
\index{plr@\cs{plr}}%
\end{cd}

The macro \cs{plr} causes \MF{} to replace the specified list of polar
coordinate pairs by the equivalent list of rectangular (cartesian)
coordinate pairs. Through \cs{plr}, commands designed for rectangular
coordinates can be applied to data represented in polar coordinates. It
must be cautioned that this wholesale conversion of a list applies only
to commands that take a list consisting of an arbitrary number of
points, such as \cs{polyline}.

The effect of \cs{plr} is to apply a \MF{} command, \gbc{polar}, to each
point in the list, producing a new list. This \MF{} command can also be
used separately in any situation where a \MF{} point is required. For
example, to connect the point $(2,3)$ to the point with polar
coordinates $(1, 135)$ write
\begin{verbatim}
\polyline{(2,3),polar(1,135)}
\end{verbatim}


\subsection{Curves}\label{curves}

\begin{cd}\pagelabel{curve}
\cs{curve}\oarg{\meta{tension}}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}\\
\cs{cyclic}\oarg{\meta{tension}}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}\\
\cs{closedcurve}\oarg{\meta{tension}}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}%
\index{curve@\cs{curve}}%
\index{cyclic@\cs{cyclic}}
\index{closedcurve@\cs{closedcurve}}%
\end{cd}

These figure macros produce a smooth path through the specified points,
in the specified order. It is `smooth' in two ways: it never changes
direction abruptly (no `corners' or `cusps' on the curve), and it tries
to make turns that are not too sharp. This latter property is acheived
by specifying (to \MF{}) that the tangent to the curve at each listed
point is to be parallel to the line from that point's predecessor to its
successor. The \cs{cyclic} variant arranges for the last point to be
connected (smoothly) to the first, and produces a closed \MF{} B\'ezier
curve. The command \cs{closedcurve} is an alias for \cs{cyclic}.

The optional \meta{tension} influences \emph{how} smooth the curve is.
The special value \mfc{infinity} (in fact, usually anything greater than
about $10$), makes the curve not visibly different from a polyline. The
higher the value of tension, the sharper the corners on the curve and
the flatter the portions in between. \CMF{} requires the tension to be
larger than 0.75. The default value of the tension is $1$ when \mfp{} is
loaded, but that can be changed with the following command.

\begin{cd}\pagelabel{settension}
\cs{settension}\marg{\meta{num}}%
\index{settension@\cs{settension}}
\end{cd}

This sets the default tension for all commands that take an optional
tension parameter.

Sometimes one would like a convex set of points to produce a convex
curve. This will not always be the case with \cs{curve} or \cs{cyclic}.
You can verify this with the following example, where the list of points
traces a rectangle:
\begin{verbatim}
\cyclic{(0,0),(0,1),(1,1),(2,1),(2,0),(0,0)}
\end{verbatim}
To produce a convex curve, use one of the following:

\begin{cd}\pagelabel{convexcurve}
\cs{convexcurve}\oarg{\meta{tension}}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}\\
\cs{convexcyclic}\oarg{\meta{tension}}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}\\
\cs{closedconvexcurve}\oarg{\meta{tension}}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}%
\index{convexcurve@\cs{convexcurve}}%
\index{convexcyclic@\cs{convexcyclic}}%
\index{closedconvexcurve@\cs{closedconvexcurve}}%
\end{cd}

These figure macros can be used even if the list of points is not
convex, and the result will be convex where possible. The third one is
an alias for for the second one.

\medskip
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 \textit{and} to
represent a function (that is, the curve always has increasing $x$
coordinate, never turning leftward). This cannot be guaranteed with the
\cs{curve} command unless the tension is \texttt{infinity}.

\begin{cd}\pagelabel{fcncurve}
\cs{fcncurve}\oarg{\meta{tension}}\marg{($x_0$,$y_0$),($x_1$,$y_1$),$\ldots$}%
\index{fcncurve@\cs{fcncurve}}%
\end{cd}

This figure macro produces 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
\meta{tension} is a number greater than $1/3$ 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 that set with
\cs{settension}, initially $1$. For those who know something about
\MF{}, this `tension' is not the same as the \MF{} notion of tension,
the tension in the \cs{curve} command, but it functions in a similar
fashion. In this case it can actually be any positive number, but only
values greater than $1/3$ guarantee the property of never doubling back.

\begin{cd}\pagelabel{turtle}
\cs{turtle}\marg{\meta{$p_0$},\meta{$v_1$},\meta{$v_2$},$\ldots$}%
\index{turtle@\cs{turtle}}%
\end{cd}

This figure macro produces a a sequence of line segments starting from
the point \meta{$p_0$}, and extending along the (2-dimen\-sional vector)
displacement \meta{$v_1$}. The next segment is from the previous
segment's endpoint, along displacement \meta{$v_2$}. This continues for
all listed displacements, a process similar to `turtle graphics'.


\subsection{Bar charts and pie charts}\label{charts}

\begin{cd}\pagelabel{barchart}
\cs{barchart}\oarg{\meta{start},\meta{sep},\meta{r}}%
  \marg{\meta{h-or-v}}\marg{\meta{list}}\\
\cs{bargraph}\dots\\
\cs{gantt}\dots\\
\cs{histogram}\dots\\
\cs{mfpbarchart}\dots\\
\cs{mfpbargraph}\dots\\
\cs{mfpgantt}\dots\\
\cs{mfphistogram}\dots
\index{barchart@\cs{barchart}}%
\index{bargraph@\cs{bargraph}}%
\index{histogram@\cs{histogram}}%
\index{gantt@\cs{gantt}}%
\end{cd}

The macro \cs{barchart} computes a bar chart or a Gantt chart. It does
not draw the bars, but only defines their rectangular paths which the
user may then draw or fill or both using the \cs{chartbar} macros (see
below). Since bar charts have many names, \cs{bargraph} and
\cs{histogram} are provided as synonyms. The macro \cs{gantt} is also a
synonym; whether a Gantt chart or bar chart is created depends on the
data.

Since \cs{barchart} never draws anything, there is no particular reason
it needs to be inside an \env{mfpic} environment. Starting with version
0.9 of \mfp{} this is no longer required, but the command name
\cs{mfpbarchart} must be used outside (in case some other package also
defines \cs{barchart}). One can use any of the four synonyms listed that
start with `\cs{mfp}'. The command to draw the bars is still required to
be inside an \env{mfpic} environment.

\meta{h-or-v} should be \texttt{v} if you want the ends of the bars to
be measured vertically from the $x$-axis, or \texttt{h} if they should
be measured horizontally from the $y$-axis. \meta{list} should be a
comma-separated list of numbers and ordered pairs giving the
end(s) of each bar. A number $c$ is interpreted as the pair $(0,c)$; a
pair $(a,b)$ is interpreted as an interval giving the ends of the bar
(for Gantt diagrams). The rest of this description refers to the
\texttt{h} case; the \texttt{v} case is analogous.

By default the bars are 1 graph unit high (thickness), from $y = n-1$ to
$y = n$. Their width and location are determined by the data. The
optional parameter consists of three numeric parameters separated by
commas. \meta{start} is the $y$-coordinate of the bottom edge of the
first bar, \meta{sep} is the distance between the  bottom edges of
successive bars, and \meta{r} is the fraction of \meta{sep} occupied by
each bar. The default behavior corresponds to \texttt{[0,1,1]}. In
general, bar number $n$ will be from $y = \meta{start} +
(n-1)*\meta{sep}$ to $y = \meta{start} + (n-1 + \meta{r})*\meta{sep}$

Notice the bars are numbered in order from bottom to top. You can
reverse them by making \meta{sep} negative, and making \meta{start} the
top edge of the first bar.

The fraction \meta{r}  should be between $-1$ and $1$. A negative value
reverses the direction from the `leading edge' of the bar to the
`trailing edge'. For example, if one bar chart is created with
\begin{ex}
  \cs{barchart}\oarg{1,1,-.4}\marg{h}\marg{$\ldots$}
\end{ex}
and another with
\begin{ex}
  \cs{barchart}\oarg{1,1,.4}\marg{h}\marg{$\ldots$}
\end{ex}
both having the same number of bars, then the first will have its first
bar from $y = 1$ to $y = 1 -.4 = .6$, while the second will have its
first bar on top of that one, from $1$ to $1 + .4$. Similarly the next
bars will be above and below $y=2$, etc. This makes it easy to draw bars
next to one another for comparison.

\begin{cd}\pagelabel{chartbar}
\cs{chartbar}\marg{\meta{num}}\\
\cs{graphbar}\marg{\meta{num}}\\
\cs{histobar}\marg{\meta{num}}\\
\cs{ganttbar}\marg{\meta{num}}%
\index{chartbar@\cs{chartbar}}%
\index{graphbar@\cs{graphbar}}%
\index{histobar@\cs{histobar}}%
\index{ganttbar@\cs{ganttbar}}%
\end{cd}

The figure macro \cs{chartbar} (synonyms \cs{graphbar}, \cs{ganttbar},
and \cs{histobar}) takes a number from $1$ to the number of elements in
the list of data of the most recent \cs{barchart} command and produces
the corresponding rectangular path computed by that command. This
behaves just like any other figure macro, and the prefix macros from
section~\ref{rendering} may be used to give adjacent bars contrasting
colors, fills, etc.


\begin{cd}\pagelabel{piechart}
\cs{piechart}\oarg{\meta{dir}\meta{angle}}\marg{\meta{$c$},\meta{$r$}}%
    \marg{\meta{list}}\\
\cs{mfppiechart}\dots
\index{piechart@\cs{piechart}}%
\end{cd}

The macro \cs{piechart} also does not draw anything, but computes the
\cs{piewedge} regions described below. The first part of the optional
parameter, \meta{dir}, is a single letter to indicate a direction:
`\texttt{c}' for \emph{clockwise} or `\texttt{a}' for \emph{anticlockwise}.
The \meta{angle} is the angle in degrees of the starting edge of the
first wedge. The defaults correspond to \oarg{c90}, which means the
first wedge starts at 12~o'clock and proceeds clockwise.

The first required argument contains the center \meta{$c$} and radius
\meta{$r$} of the chart. The second required argument is the list of
data: positive numbers separated by commas.

Since this command never actually draws anything, only defining the
wedges, it makes sense to have it available outside the drawing
environment. Starting with version 0.9 of \mfp{} that is the case, but
the command name is \cs{mfppiechart} (to avoid a name clash with some
other package's \cs{piechart} command). The command to draw wedges
(\cs{piewedge}, see below) is still required to be inside an \env{mfpic}
environment.

\begin{cd}\pagelabel{piewedge}
\cs{piewedge}\oarg{\meta{spec}\meta{trans}}\marg{\meta{num}}%
\index{piewedge@\cs{piewedge}}%
\end{cd}

This figure macro takes a number from $1$ to the number of elements in
the list of data of the most recent \cs{piechart} command and produces
the corresponding wedge-shaped path computed by that command. By
default, the path is positioned as computed by that \cs{piechart}
command, but The optional argument to \cs{piewedge} can override this.
The parameter \meta{spec} is a single letter, which can be \texttt{x},
\texttt{s} or \texttt{m}. The \texttt{x} stands for \emph{exploded} and
it means the wedge is moved directly out from the center of the pie a
distance \meta{trans}. \meta{trans} should then be a pure number and is
interpreted as a distance in graph units. The \texttt{s} stands for
\emph{shifted} and in this case \meta{trans} should be a pair of the
form \texttt{(\meta{dx},\meta{dy})} indicating the wedge should be
shifted \meta{dx} horizontally and \meta{dy} vertically (in graph
units). The \texttt{m} stands for \emph{move to}, and \meta{trans} is
then the absolute coordinates \texttt{(\meta{x},\meta{y})} in the graph
where the point of the wedge should be placed.

\section{Colors.}\label{colors}

\subsection{Setting the default colors}\label{defaultcolors}

\begin{cd}\pagelabel{drawcolor}
\cs{drawcolor}\oarg{\meta{model}}\marg{\meta{colorspec}}\\
\cs{fillcolor}$\ldots$\\
\cs{hatchcolor}$\ldots$\\
\cs{pointcolor}$\ldots$\\
\cs{headcolor}$\ldots$\\
\cs{tlabelcolor}$\ldots$\\
\cs{backgroundcolor}$\ldots$%
\index{drawcolor@\cs{drawcolor}}%
\index{fillcolor@\cs{fillcolor}}%
\index{hatchcolor@\cs{hatchcolor}}%
\index{pointcolor@\cs{pointcolor}}%
\index{headcolor@\cs{headcolor}}%
\index{tlabelcolor@\cs{tlabelcolor}}%
\index{backgroundcolor@\cs{backgroundcolor}}%
\end{cd}

These macros set the default color for various drawing elements. Any
curve (with one exception, those drawn by \cs{plotdata}), whether solid,
dashed, dotted, or plotted in symbols, will be in the color set by
\cs{drawcolor}. Set the color used by \cs{gfill} with \cs{fillcolor}.
For all the hatching commands use \cs{hatchcolor}. For the \cs{point},
\cs{plotsymbol} and \cs{gridpoints} commands use \cs{pointcolor}, and for
arrowheads, \cs{headcolor}. One can set the color used by \cs{gclear}
with \cs{backgroundcolor} (the same color will also be used in the
interior of unfilled points that are drawn with \cs{point}) and, when
\opt{mplabels} is in effect, the color of labels can be set with
\cs{tlabelcolor}. The optional \meta{model} may be one of \opt{rgb},
\opt{RGB}, \opt{cmyk}, \opt{gray}, and \opt{named}. The \meta{colorspec}
depends on the model, as outlined below. Each of these commands sets a
corresponding \MP{} color variable with the same name (except
\cs{backgroundcolor} sets the color \mfc{background}). Thus, after
\texttt{drawcolor} has been set, one can issue the command
\cs{fillcolor}\marg{drawcolor} to fill with the same color.

As previously discussed, all these colors are initially set to
\mfc{black} except \mfc{background} is set to \mfc{white}.

\subsection{\CMP{} colors}\label{mpcolors}

If the optional \meta{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)}. \CMP{} 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 \MP{}
color functions have been defined in \file{grafbase.mp}:

\begin{cd}
\mfc{cmyk($c$,$m$,$y$,$k$)}%
\index{cmyk@\mfc{cmyk($c$,$m$,$y$,$k$)}}
\end{cd}

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}.

\begin{cd}
\mfc{RGB($R$,$G$,$B$)}%
\index{RGB@\mfc{RGB($R$,$G$,$B$)}}
\end{cd}

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

\begin{cd}
\mfc{gray($g$)}%
\index{gray@\mfc{gray($g$)}}
\end{cd}

Converts a numeric $g$ (a gray level) to the corresponding multiple of
\mfc{(1,1,1)}.

\begin{cd}
\mfc{named(\meta{name})},
\mfc{rgb($r$,$g$,$b$)}%
\index{named@\mfc{named(\meta{name})}}%
\index{rgb@rgb($r$,$g$,$b$)}
\end{cd}

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

\medskip
As an example of the use of these functions, one could conceivable
write:
\begin{verbatim}
\drawcolor{0.5*RGB(255,0,0)+0.5*cmyk(1,0,0,0)}
\end{verbatim}
to have all curves drawn in a color halfway between red and cyan (which
turns out to be the same as \gbc{gray(0.5)}).

\subsection{Color models}\label{colormodels}

When the optional \meta{model} is specified in the color setting
commands, it determines the format of the color specification:

\medskip
\halign{\quad#\hfil\quad&#\hfil\cr
{\slshape Model:}& {\slshape 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
                   \mfp{} or by the user.\cr}

\medskip
\Mfp{} translates
\begin{verbatim}
\fillcolor[cmyk]{1,.3,0,.2}
\end{verbatim}
into the equivalent of
\begin{verbatim}
\fillcolor{cmyk(1,.3,0,.2)}.
\end{verbatim}
Note that when the optional model is specified, the color
specification must \emph{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.


\subsection{Defining a color name}\label{colorname}

\begin{cd}\pagelabel{mfpdefinecolor}
\cs{mfpdefinecolor}\marg{\meta{name}}\marg{\meta{model}}\marg{\meta{colorspec}}%
\index{mfpdefinecolor@\cs{mfpdefinecolor}}
\end{cd}

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

\medskip
A final caution, the colors of an \mfp{} 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 \cs{definecolor} command will remain unknown to \mfp{}.
Conversely, \LaTeX{} commands will not recognize any color defined only
by \cs{mfpdefinecolor}.

\subsection{Color in \MF{}}\label{MFcolor}

\CMF{} was never meant to understand colors, but it certainly can be
taught the difference between black and white and, to a limited extent,
various grays. Starting with version 0.7, \mfp{} will no longer generate
an error when a color-changing command is used under the \opt{metafont}
option. Instead, when possible, the variables that represent colors in
\MP{} will be converted to a numeric value between 0 and 1 in \MF{}. When
possible (for example, when a region is filled) the numeric will be
interpreted as a gray level and shading (see subsection~\ref{filling})
will be used to approximate the gray. In other cases (drawing or dashing
of curves, placing of points or symbols, filling with a pattern of hatch
lines) the number will be interpreted as black or white: a value less
than 1 will cause the figure to be rendered in black, while a value
equal to 1 (white) will cause pixels corresponding to the figure to be
erased.

This depends on adhering to certain restrictions. \CMF{}'s syntax
does not recognize a triple of numbers as any sort of data structure,
but it does allow \emph{commands} to have any number of parameters in
parentheses. So colors must be specified using the color commands such
as \gbc{rgb(1,1,0)} or color names such as \gbc{yellow}, and never as a
bare triple. Also, as currently written, the color names defined in
\file{dvipsnam.mp} are not defined in \MF{}. With these provisions the
same \mfp{} code can often produce either gray scale \MF{} pictures or
\MP{} color pictures depending only on the \opt{metapost} option.

The commands \cs{shade} and \cs{gfill}\oarg{gray(.75)} (see
subsection~\ref{filling} for their meaning) will produce a similar shade
of gray, but there is a difference. The first simply adds small dots on
top of whatever is already drawn. The second, however, tries to simulate
the \MP{} effect, which is to cover up whatever is previously drawn.
Therefore, it first erases all affected pixels before adding the dots to
simulate gray. In particular, \cs{gfill}\oarg{white} should have the
same effect as \cs{gclear}.


\section{Modifying the figures.}\label{modifier}

Some \mfp{} macros operate by \emph{modifying} a figure: if you want to
turn an open arc into a closed figure by adding a straight line, you can
write: \cs{lclosed}\cs{arc}\marg{(0,0),(1,0),45}. These are always
prefixed to some figure drawing command, and apply only to the next
following figure macro provided that only other prefix commands
intervene. This is a rather long section, but even more modification
prefixes are documented in subsection~\ref{transformation}.

The combination of a modifying macro, followed by a figure macro, can
usually be thought of as a new figure macro, to which further prefixes
might be prepended.

More precisely: all prefix macros have an \emph{input}, an
\emph{output}, and a side effect. The input and output are alway paths.
The input is the path that is output by the \emph{following} prefix or
figure macro. The output is either the same as the input or a
modification of it. The side effect might be a drawing or filling of the
path or the addition of an arrowhead.

We list here a classifications of prefix and figure macros that is
useful for understanding the \mfp{} system.

\begin{description}

\item[Figure macros.] These\index{figure macro} have no input; they must
    come last in a sequence. They output the path they were designed to
    produce. Examples are \cs{circle}, \cs{rect} and \cs{polygon}. If
    they have no prefixes, or are preceded only by appending macros (see
    next), they invoke a default rendering of the path (usually a
    drawing as a solid stroke) as the side effect.

\item[Macros that append] These\index{prefix macro} pass their input
    unchanged as their output. Their side effect is the appending of
    some object such as an arrowhead. Currently only the various arrow
    macros are appending macros (see subsection~\ref{arrows}). However,
    \cs{reverse} (which technically modifies a path and has no side
    effect) is coded as an appending macro so that it will work
    correctly with arrows. Think of it as `appending' a new direction.

\item[Macros that render] These\index{prefix macro} pass their
    input unchanged as their output. They have the side effect of adding
    or subtracting ink from a picture in the shape of the input path.
    Examples are \cs{draw}, \cs{dotted}, \cs{gfill} and \cs{gclip}.

\item[Macros that modify] These\index{prefix macro} output the result of
    applying their intended modification to the input path. Examples are
    macros that close the path if it was open, macros that apply a
    transformation such as a rotation, and macros that return only a
    part of a path. If they have no prefixes, or are preceded only by
    appending macros (see above), they also invoke a default rendering
    of the output path (usually a drawing as a solid stroke of the
    modified path) as the side effect.

\end{description}

\subsection{Closure of paths}\label{closure}

It should be pointed out that the closure macros will leave already
closed paths unchanged, so it is always safe to add one when uncertain.
Moreover, if the path is not closed but the endpoints are identical,
\cs{lclosed} will close it without adding the (trivial) line segment.


\begin{cd}\pagelabel{lclosed}
\cs{lclosed}$\ldots$\\
\cs{bclosed}\oarg{\meta{tens}}$\ldots$\\
\cs{sclosed}\oarg{\meta{tens}}$\ldots$%
\index{lclosed@\cs{lclosed}}
\index{bclosed@\cs{bclosed}}%
\index{sclosed@\cs{sclosed}}
\end{cd}

These modifying macros all turn an open path into a closed one. If the
path is already closed, they do nothing.

\cs{lclosed} makes an open path into a closed path by adding a line
segment between the endpoints of the path. In the special case where
the path ends exactly where it begins, all \cs{lclosed} does is change
the type of the path from open to closed.

The \cs{bclosed} macro is similar to \cs{lclosed}, except that it closes
an open path smoothly by drawing a B\'ezier curve. A B\'ezier is \MF{}'s
natural way of connecting points into a curve, and \cs{bclosed} is the
simplest and most efficient closure next to \cs{lclosed}. Moreover it
usually gives a reasonably aesthetic result. Sometimes, however, one
might wish a tighter connection. If that is the case, use the optional
argument with a value of the tension \meta{tens} greater than $1$, the
default. The command \cs{settension} (see subsection~\ref{curves}) can
be used to change the default.

\cs{sclosed} closes the curve by mimicking the definition of the
\cs{curve} command. That command tries to force the curve to pass
through the $n$th point in a direction parallel to the line from point
$(n-1)$ to point $(n+1)$. In order to close a curve in this way, the
direction at the two endpoints often has to be changed, and this changes
the shape of the first and last segments of the curve. Use \cs{bclosed}
if you don't wish this to happen. However, \cs{sclosed}\cs{curve}
produces a result almost identical to \cs{cyclic} given the same points
and tension values. The optional tension argument is as in the
\cs{bclosed} command.

There are two other closure commands but, because they are associated
with particular types of paths (splines), we delay their discussion
until those are discussed (subsection~\ref{splines}).

\begin{cd}\pagelabel{makesector}
\cs{makesector}\cs{arc}[\meta{fmt}]\marg{\meta{spec}}%
\index{makesector@\cs{makesector}}
\end{cd}

The modifying macro \cs{makesector} can be applied to any path, but it
make sense only if that path is an arc. It appends line segments from
the center of the arc's circle to the ends of the arc, producing a
closed path. It is useful if one doesn't know that center of the arc (a
required parameter of \cs{sector}). It works by selecting the first
point, a middle point, and the last point of the following path, then
calculates the center of the circle through those three points.


\subsection{Reversal, connection and other path modifications}%
\label{reversal}

\begin{cd}\pagelabel{reverse}
\cs{reverse}$\ldots$%
\index{reverse@\cs{reverse}}
\end{cd}

This modifies the following path by reversing its sense. This will
affect the direction of arrows: bi-directional arrows can be coded with
\cs{arrow}\cs{reverse}\cs{arrow}$\ldots$, where the first \cs{arrow}
prefix applies to the \emph{reversed} path. The order of endpoints for
the following \env{connect} environment will also be affected.


\begin{cd}\pagelabel{connect}
\cs{connect} $\ldots$ \cs{endconnect}%
\index{connect@\cs{connect}}%
\index{endconnect@\cs{endconnect}}
\end{cd}

The macro \cs{connect} produces a connected path by joining all the
paths following it up to the matching \cs{endconnect} command. Line
segments are added from the end of one path to the start of the next.
The whole group acts as one figure macro, permitting any prefix macros
to come before.

In \LaTeX{}, instead of this pair of macros, an environment named
\env{connect} may be used. For example
\begin{verbatim}
\lclosed
\begin{connect}
  \curve{(2,1),(1,2),(0,1)}
  \polyline{(0,0),(2,0)}
\end{connect}
\end{verbatim}
produces a closed figure consisting of one smooth curve and three line
segments: the segment produced by \cs{polyline}, the segment added by
the \env{connect} environment, and the segment added by \cs{lclosed}.


\begin{cd}\pagelabel{partpath}
\cs{partpath}\marg{\meta{frac1},\meta{frac2}}\dots\\
\cs{subpath}\marg{\meta{num1},\meta{num2}}\dots%
\index{partpath@\cs{partpath}}%
\index{subpath@\cs{subpath}}
\end{cd}

These macros modify the following path by producing only a part of it. In
\cs{partpath} the parameters \meta{frac1} and \meta{frac2} should be
numbers between 0 and 1. The path produced travels the same course as
the path that follows, but starts at the point that is the fraction
\meta{frac1} of the original length along it, and ends at the point
\meta{frac2} of its original length. If \meta{frac1} is greater than
\meta{frac2}, the sense of the path is reversed. In \cs{subpath}, the
two numbers should be between 0 and the number of B\'ezier segments in
the path. This is mainly for experienced \MF{}ers and provides an \mfp{}
interface to \MF{}'s `\mfc{subpath}' operation.

\begin{cd}\pagelabel{parallelpath}
\cs{parallelpath}{\meta{dist}}$\ldots$
\index{parallelpath@\cs{parallelpath}}
\end{cd}

This modifying macro takes the following path and returns a path that
follows beside it, keeping a fixed distance \meta{dist} to the left. If
\meta{dist} is negative, it keeps to the right. Left or right is from
the point of view of a traveller following the given path from start to
finish. The distance is a pure number in \emph{graph} coordinates. Note:
this should be compared to the first optional argument of
\cs{doubledraw} (see subsection~\ref{drawing}), which requires an
absolute dimension like \dim{2pt}, even though it is implemented using
the internal code of \cs{parallelpath}.

The calculation of the parallel path is approximate and rather
inefficient. It is likely to produce inexplicable small loops where it
tries to follow the inside of tight turns (radius less than
\meta{dist}). Actual corners, (which might be thought of as turns of
radius $0$) are usually detected and dealt with in a reasonable manner.
However, if the path is made up of segments of length \meta{dist} or
less, this is unlikely to work correctly at all.

\begin{cd}\pagelabel{arccomplement}
\cs{arccomplement}\dots%
\index{arccomplement@\cs{arccomplement}}
\end{cd}

This macro, to work properly, must be followed by an arc of a circle. It
produces the complementary arc. That is, it produces the circular arc,
which would, if appended to the following arc, complete the circle. The
complementary arc will have the same direction, clockwise or
anticlockwise, as the original. The arc that follows doesn't have to be
produced by \cs{arc}, as in the following example:
\begin{ex}
\cs{draw}\oarg{blue}\cs{arccomplement}\\
\ \cs{draw}\oarg{red}\cs{partpath}\marg{0,.333}\\
\ \cs{circle}\marg{(0,0),1}
\end{ex}
This will draw 1/3 of the circle in red and the rest in blue.

\CMF{} cannot check if a path is really a circular arc. The \MF{} code,
like that of \cs{makesector} (see subsection~\ref{closure}), selects
three key points on the arc, then it produces the rest of the circle
much the same way as the internal code of \cs{arc}\oarg{t} (the three
point option for \cs{arc}). Thus, it will produce \emph{some} arc from
the end of any following path to its beginning (or a straight line if
the three chosen points happen to lie in a straight line). However, the
result needn't bear any significant relation to the original path.


\subsection{Arrows}\label{arrows}

\begin{cd}\pagelabel{arrow}
\cs{arrow}\oarg{l\meta{headlen}}\oarg{r\meta{rotate}}%
    \oarg{b\meta{backset}}\oarg{c\meta{color}}$\ldots$\\
\cs{arrow*}\oarg{l\meta{headlen}}\oarg{r\meta{rotate}}%
    \oarg{b\meta{backset}}\oarg{c\meta{color}}$\ldots$%
\index{arrow@\cs{arrow}}
\end{cd}

This macro adds an arrowhead at the endpoint of the open path (or at the
last key point of the closed path) that follows. The optional parameter
\meta{headlen} determines the length of the arrowhead.  The default is
the value of the \TeX{} dimension \cs{headlen}, initially \dim{3pt}. The
optional parameter \meta{rotate} allows the arrowhead to be rotated
anticlockwise around its point an angle of \meta{rotate} degrees. The
default is 0. The optional parameter \meta{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, it is set back in the direction after the rotation. Actually,
except on a straight line, a better way to set an arrowhead back might
be something like
\begin{ex}
  \cs{arrow}\cs{trimpath}\marg{0,5pt}\cs{draw}\dots
\end{ex}
See subsection~\ref{misc} for the \cs{trimpath} macro. The optional
\meta{color} defaults to \gbc{headcolor}. The optional parameters may
appear in any order, the indicated key character determining the meaning
of a parameter. The key letter \texttt{l} for `length' can be replaced
by \texttt{s} for `size'. And, oddly enough, \texttt{b} for `backset'
can be replaced by \texttt{f} for `forward' so that arrow tails (see
below) can share the same internal code for identifying the meaning of
the parameters.

There is also a star-form: If \cs{arrow} is called as \cs{arrow*}, then
any part of the tip of the following curve that lies outside the
arrowhead shape is clipped off. Imagine a rectangle with one side
connecting the ends of the barbs and the opposite  side passing through
the tip. Everything in that rectangle outside the arrowhead is erased,
so be careful using this (also see comments about \MP{}'s method of
`erasing' in the description of \cs{gclear} in
\cs{}subsection~\ref{filling}). One use of this is adding an arrowhead
to a figure rendered with \cs{doubledraw} (see the next section) or with
a rather large pen diameter (see section~\ref{parameters}).

For the star-form to work, the head has to be added after the path is
drawn. What this means in practice is that the \cs{arrow*} command must
come before any drawing command in the list of prefixes. This is because
prefix macros add their elements to the result of everything that
follows. If you \cs{store} a curve in a path variable (see
subsection~\ref{transformation}), and draw the path and the arrowhead in
separate commands, then the arrow command must come \emph{after} the
drawing command.

\begin{cd}\pagelabel{arrowhead}
\cs{arrowhead}\marg{\meta{symbol}}\oarg{l\meta{length}}\oarg{r\meta{rotate}}%
    \oarg{b\meta{backset}}\oarg{c\meta{color}}$\ldots$\\
\cs{arrowmid}\marg{\meta{symbol}}\oarg{l\meta{length}}\oarg{r\meta{rotate}}%
    \oarg{f\meta{fraction}}\oarg{c\meta{color}}$\ldots$\\
\cs{arrowtail}\marg{\meta{symbol}}\oarg{l\meta{length}}\oarg{r\meta{rotate}}%
    \oarg{f\meta{forward}}\oarg{c\meta{color}}$\ldots$%
\index{arrowhead@\cs{arrowhead}}%
\index{arrowmid@\cs{arrowmid}}%
\index{arrowtail@\cs{arrowtail}}
\end{cd}

These macros add some sort of symbol at different locations along a
path. The first adds an arrowhead, but the head can be any appropriately
designed symbol. It has been arranged that any of the symbols usable in
\cs{plotsymbol} (see subsection~\ref{points}) can be used: you can have
\gbc{Diamond}- or \gbc{Asterisk}-tipped arrows. The special symbol
\gbc{Arrowhead} produces the same shape as the head in the \cs{arrow}
command. In total eight special \meta{symbols} have been made available,
intended for use with \cs{arrowhead}, \cs{arrowmid} and \cs{arrowtail}.
Here is a list and description of all these symbols.
\begin{description}
  \item[\gbc{Arrowhead}] The\index{Arrowhead@\gbc{Arrowhead}} shape that
    would be drawn at the end of a path by \cs{arrow}.
  \item[\gbc{Leftharpoon}] The\index{Leftharpoon@\gbc{Leftharpoon}} left
    half of \gbc{Arrowhead}.
  \item[\gbc{Rightharpoon}] The\index{Rightharpoon@\gbc{Rightharpoon}}
    right half of \gbc{Arrowhead}.
  \item[\gbc{Crossbar}] A\index{Crossbar@\gbc{Crossbar}} short
    line crossing the path perpendicularly unless rotated.
  \item[\gbc{Leftbar}] Essentially\index{Leftbar@\gbc{Leftbar}} the left
    half of \gbc{Crossbar}.
  \item[\gbc{Rightbar}] The\index{Rightbar@\gbc{Rightbar}} right half.
  \item[\gbc{Lefthook}] An\index{Lefthook@\gbc{Lefthook}} open
    semicircle with its open face in the direction of the path, added to
   the left side of the path.
  \item[\gbc{Righthook}] Like\index{Righthook@\gbc{Righthook}}
    \gbc{Lefthook} but on the right side.
\end{description}
Here `left' and `right' are from the point of view of an observer facing
in the direction of the path.

If the symbol is a closed path (see subsection~\ref{closure} for the
difference between a closed path and one that merely looks closed), the
head will be filled, otherwise its outline will be drawn. Thus
\cs{arrowhead}\marg{Diamond} draws an outline, and
\cs{arrowhead}\marg{SolidDiamond} draws a filled shape because
\gbc{Diamond} has been left open, while \gbc{SolidDiamond} has been
defined to be closed.

It is possible, to get an outline drawn with the inside erased:
just place the solid version with color \mfc{white} and then the outline
version. This can produce a pleasing result. But recall that the prefix
macro nearest the figure macro is executed first. For example:
\begin{verbatim}
\arrowmid{Circle}\arrowmid{SolidCircle}[cwhite]\polyline{(0,0),(1,1)}
\end{verbatim}

The symbol is always rotated so that it points in the direction of the
path (for this purpose, all symbols are initially assumed to point
straight upward) before the \oarg{r\meta{rotate}} parameter is applied.

There is a star-form \cs{arrowhead*} that behaves like \cs{arrow*} (when
possible). The optional arguments are exactly as in \cs{arrow}, with the
same defaults for all of them.

The second command, \cs{arrowmid}, places the symbol somewhere between
the start and the end of the path. In this case the optional parameter
\oarg{f\meta{fraction}} gives the location of the symbol as a fraction
of the length of the path. The default is \oarg{f0.5}, which places it
approximately in the middle. The other optional arguments have the same
meaning as for \cs{arrowhead}. As with \cs{arrowhead}, the symbol is
rotated to `point' in the direction of the path before the
\oarg{r\meta{rotate}} is applied.

The third command \cs{arrowtail} places the symbol at the start of the
path. Otherwise it behaves as the other two commands, except the option
\oarg{f\meta{forward}} is an amount to shift the symbol forward from
that first point.

One might be tempted to use \cs{arrowmid} with the \meta{fraction} equal
to $1$ or $0$ to get arrowheads or tails. This will work sometimes.
However, some shapes have a `tip', that is, a particular point
designated as the tip of the arrowhead. The \cs{arrowhead} and
\cs{arrowtail} commands pay attention to this, while \cs{arrowmid} does
not. Also, \cs{arrowmid} has no star-form.

You can design your own \meta{symbol} for these commands: use \cs{store}
to store a path in a path variable (see
subsection~\ref{transformation}). These commands assume that the length
is $1$, that the symbol `points' up and that the `tip' (the `pointy
end') is at $(0,0)$ (unless the pair variable \meta{symbol}\gbc{.tip} is
defined, in which case that is taken to be the tip). So draw your symbol
pointing up with its tip at $(0,0)$ and its length equal to $1$ (graph
unit). For example the following produces a solid head with a common
shape:
\begin{verbatim}
\store{myAH}\polygon{(-.5,-1)(0,0),(0.5,-1),(0,-.7)}
\arrowhead{myAH}\arc{(-10,0),(10,0),90}
\end{verbatim}
If you replace the \cs{polygon} above with \cs{polyline}:
\begin{verbatim}
\store{myAH}\polyline{(-.5,-1)(0,0),(0.5,-1),(0,-.7),(-.5,-1)}
\end{verbatim}
the path will not be closed and so the arrowhead will not be filled in.

To make the star-form work with such self-defined symbols, one must also
define a closed path \gbc{myAH.clear} that gives the region to be
erased. In the above example:
\begin{verbatim}
\store{myAH.clear}\polygon{(-.5,-1),(-.5,0),(.5,0),(.5,-1),(0,-.7)}
\end{verbatim}


\section{Rendering figures.}\label{rendering}

When \mfp{} is loaded, the initial way in which figures are drawn is
with a solid outline. That is, \cs{polyline}\marg{(1,0),(1,1),(0,0)} will
draw two solid lines connecting the points. It is possible to establish
a different default (see \cs{setrender} in subsection~\ref{default}),
however that default is used only when no explicit rendering prefix is
present. That is, when the macros in this section are used, any
previously established default is overridden.

\begin{cd}\pagelabel{norender}
\cs{norender}$\ldots$%
\index{norender@\cs{norender}}%
\end{cd}

This causes the following path not to be rendered at all. This can be
used to override \mfp{}'s automatic rendering rules. See
section~\ref{transformation}, page~\pageref{norenderexample} for an
example where one might need to do this.

\subsection{Drawing}\label{drawing}

\begin{cd}\pagelabel{draw}
\cs{draw}\oarg{\meta{color}}$\ldots$%
\index{draw@\cs{draw}}
\end{cd}

Draws the subsequent path using a solid outline. For an example: to both
draw a curve and hatch its interior, \cs{draw}\cs{hatch} must be used.
The default for \meta{color} is \gbc{drawcolor}.

To save repetition, the color used for the following commands is also
\gbc{drawcolor}: \cs{dashed}, \cs{dotted}, \cs{doubledraw}, \cs{plot},
\cs{plotnodes}, and \cs{gendashed},

\begin{cd}\pagelabel{doubledraw}
\cs{doubledraw}\oarg{\meta{sep}}\oarg{\meta{color}}$\ldots$
\index{doubledraw@\cs{doubledraw}}
\end{cd}

This rendering macro draws the path with a double line. The default
separation (distance between centers of the two penstrokes) is twice the
pen diameter. This normally leaves one line thickness of white space
between. You can change this with the \oarg{\meta{sep}} argument. In
order to make the space between the lines transparent, this command is
implemented by calculating two curves that parallel the given curve and
drawing those. For technical reasons, that calculation is rather lengthy
so this is somewhat inefficient and users of slow machines might want to
avoid it. See also comments at \cs{parallelpath} in
subsection~\ref{reversal}.

\begin{cd}\pagelabel{dashed}
\cs{dashed}\oarg{\meta{length},\meta{space}}$\ldots$%
\index{dashed@\cs{dashed}}
\end{cd}

This rendering macro draws dashed segments along the path specified.
The default length of the dashes is the value of the \TeX{} dimension
\cs{dashlen}, initially \dim{4pt}. The default space between the dashes
is the value of the \TeX{} dimension \cs{dashspace}, initially
\dim{4pt}. The dashes and the spaces between may be increased or
decreased by as much as $1/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 \cs{dashlen} long.

\begin{cd}\pagelabel{dotted}
\cs{dotted}\oarg{\meta{size},\meta{space}}$\ldots$%
\index{dotted@\cs{dotted}}
\end{cd}

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

\begin{cd}\pagelabel{plot}
\cs{plot}\oarg{\meta{size},\meta{space}}\marg{\meta{symbol}}$\ldots$%
\index{plot@\cs{plot}}
\end{cd}

Similar to \cs{dotted}, this rendering macro draws copies of
\meta{symbol} along the path. Possible symbols are those listed under
\cs{plotsymbol} in subsection~\ref{points}. The default \meta{size} is
\cs{pointsize} (initially \dim{2pt}) and the default \meta{space} is
\cs{symbolspace} (initially \dim{5pt}).

\begin{cd}\pagelabel{plotnodes}
\cs{plotnodes}\oarg{\meta{size}}\marg{\meta{symbol}}$\ldots$%
\index{plotnodes@\cs{plotnodes}}
\end{cd}

This rendering macro places a symbol at each \emph{node} of the path
that follows. Possible symbols are those listed under \cs{plotsymbol} in
subsection~\ref{points}. A node is one of the points through which \MF{}
draws its curve.  If one of the macros \cs{polyline}\marg{$\ldots$} or
\cs{curve}\marg{$\ldots$} follows, each of the points listed is a node.
In the \cs{datafile} command (subsection~\ref{external}), each of the
data points in the file is. In the function macros
(subsection~\ref{plotting}) the points corresponding to \meta{min},
\meta{max} and each step in between are nodes. The optional \meta{size}
defaults to \cs{pointsize}. If the command \cs{clearsymbols} has been
issued then the interiors of the open symbols are erased. The effect of
something like the following is rather nice:
\begin{verbatim}
\clearsymbols
\plotnodes{Circle}\draw\polyline{...}
\end{verbatim}
This will first draw the polyline with solid lines, and then the points
listed will be plotted as open circles with the portion of the lines
inside the circles erased. One sees a series of open circles connected
one to the next by line segments


\begin{cd}\pagelabel{dashpattern}
\cs{dashpattern}\marg{\meta{name}}%
    \marg{\meta{len1},\meta{len2},$\ldots$,\meta{len2k}}%
\index{dashpattern@\cs{dashpattern}}
\end{cd}

For more general dash patterns than \cs{dashed} and \cs{dotted} provide,
\mfp{} offers a generalized dashing command. Before using it, one must
first establish a named dashing pattern with the above command. The
\meta{name} can be any sequence of letters and underscores. Try to make
it distinctive to avoid undoing some internal variable. \meta{len1}
through \meta{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 \texttt{0pt} means a dot. An alternating dot-dash pattern
can be specified with
\begin{verbatim}
\dashpattern{dotdash}{0pt,4pt,3pt,4pt}
\end{verbatim}
\emph{Note}: Since pens have some thickness, dashes look a little
longer, and spaces a little shorter, than the numbers suggest. If one
wants dashes and spaces with the same length, one needs to take the size
desired and increase the spaces by the thickness of the drawing pen
(normally) \dim{0.5pt}) and decrease the dashes by the same amount.%
    \footnote{Experienced \MP{} users could also set the \mfc{linecap}
    variable to \mfc{butt}.}

If \cs{dashpattern} is used with an odd number of entries, a space of
length \dim{0pt} is appended. This makes the last dash in one copy of
the pattern abut the first dash in the next copy.

\begin{cd}\pagelabel{gendashed}
\cs{gendashed}\marg{\meta{name}}$\ldots$%
\index{gendashed@\cs{gendashed}}
\end{cd}

Once a dashing pattern name has been defined, it can be used in this
figure macro to draw the curve that follows it. Using a name not
previously defined will cause the curve to be drawn with a solid line,
and generate a \MF{} warning, but \TeX{} will not complain. If all the
dimensions in a dash pattern are 0, \cs{gendashed} responds by drawing a
solid curve. The same is true if the pattern has only one entry.

\begin{cd}\pagelabel{zigzag}
\cs{zigzag}\marg{\meta{start},\meta{end},\meta{wl},\meta{amp}}\dots\\
\cs{sinewave}\oarg{\meta{tens}}%
    \marg{\meta{start},\meta{end},\meta{wl},\meta{amp}}\dots%
\index{zigzag@\cs{zigzag}}%
\index{sinewave@\cs{sinewave}}
\end{cd}

These figure macros both draw a solid line that crosses from one
side of the path to the other. The \cs{zigzag} makes a jagged result
while the \cs{sinewave} makes a smooth one. The optional argument of
\cs{sinewave} is a `tension' and controls how smooth the result is. The
default tension is $1$. Higher values make a less smooth path, and
values of 10 or so produce a result almost indistinguishable from
\cs{zigzag}. Tension is required to be greater than $3/4$.

The mandatory arguments consists of four dimensions separated by a comma.
The rendering produced by these macros actually follow the path a little
way at the start and end of the path. This is controlled by the
dimensions \meta{start} and \meta{end}.

The third dimension, \meta{wl}, is the distance from one `peak' to the
next (the `wavelength'). The second, \meta{amp}, is the maximum distance
to either side of the true path (the `amplitude'). Reasonable values of
\meta{wl} and \meta{amp} are \dim{8pt} and \dim{2pt}, respectively.
These proportions (4 to 1) causes the zigzag and the sinewave to cross
the path at an angle of about 45 degrees, a rather pleasant result.
Those sizes are close to optimal: too much smaller and the rendering
just looks like a fuzzy line, too much larger, and bends in the path
will distort the zigzagging.

The zigzags zig to the left first if \meta{amp} is positive, to the
right if it is negative. For closed curves, the beginning and end are
constructed to meet smoothly. It is always arranged that there are an
equal number of left zigs and right zags, so the \meta{wl} is only
approximate.


\begin{cd}\pagelabel{corkscrew}
\cs{corkscrew}\oarg{\meta{tens}}%
    \marg{\meta{start},\meta{end},\meta{wl},\meta{amp}}\dots\\%
\cs{coil}\oarg{\meta{tens}}%
    \marg{\meta{start},\meta{end},\meta{wl},\meta{amp}}\dots%
\index{corkscrew@\cs{corkscrew}}%
\index{coil@\cs{coil}}
\end{cd}

This rendering macro draws a coil or corkscrew that coils around a
given path, something like this: \includegraphics{coil.mps} (the red
dots show the actual path). The \meta{tens} is a tension option that
controls how `loopy' the result will be (the higher the number the more
jagged). The mandatory argument contains four explicit dimensions. The
first two, \meta{start} and \meta{end} are as in \cs{zigzag}. The
\meta{wl} is the distance from one loop to the next, and \meta{amp} is
the distance from the true path to the tops (or bottoms) of the
loops. If \meta{amp} is positive, the tip of the loop is to the left
of the path, if negative it is to the right. The example at the start of
this paragraph was drawn using the following code:
\begin{verbatim}
\mfpic{0}{33}{0}{6.4}
\dotsize=1pt
\drawcolor{red}
  \dotted\polyline{(0,3.2),(33,3.2)}
\drawcolor{black}
  \coil[1.5]{3pt,3pt,4.8pt,3.2pt}\polyline{(0,3.2),(33,3.2)}
\endmfpic
\end{verbatim}


\subsection{Shading, filling, erasing, clipping, hatching}\label{filling}

For the purposes of this section, 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 might be open and may need to be explicitly closed, for example by
\cs{lclosed}. The (already) closed paths are those that have
`\texttt{closed}' or `\texttt{cyclic}' in their name plus:
\begin{display}
  \cs{belowfcn}, \cs{border}, \cs{btwnfcn}, \cs{btwnplrfcn},
    \cs{chartbar} (and its aliases),\\
  \cs{circle}, \cs{ellipse},