summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/mfpic/mfpic-doc.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/mfpic/mfpic-doc.tex')
-rw-r--r--Master/texmf-dist/doc/generic/mfpic/mfpic-doc.tex7123
1 files changed, 7123 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/mfpic/mfpic-doc.tex b/Master/texmf-dist/doc/generic/mfpic/mfpic-doc.tex
new file mode 100644
index 00000000000..bee22641385
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/mfpic/mfpic-doc.tex
@@ -0,0 +1,7123 @@
+%%% File: mfpic-doc.tex
+%%% A part of mfpic 1.00 2009/09/22
+%%%
+% 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}
+\newcommand\sgn{\mathop{\mathrm{sgn}}\nolimits}
+% 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 still 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(x)} 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$", but try \verb$mpost$ first).
+
+This produces files \file{pics.1}, \file{pics.2}, etc., the number of
+files depending on the version of \file{pictures.tex}. You then
+reprocess \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(x)} 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 that of your printer and of your DVI
+viewer. 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
+you have made changes that affect 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}, \opt{metafont}, \cs{usemetapost}, \cs{usemetafont}.}%
+\label{metapost}\index{metapost@\opt{metapost}}\index{usemetapost@\cs{usemetapost}}%
+\index{metafont@\opt{metafont}}\index{usemetafont@\cs{usemetafont}}
+
+The option \opt{metapost} or the command \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 (for backward compatibility of files written
+before \MP{} existed). 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 command forms can be placed anywhere.
+If used outside an mfpic environment, they affect all subsequent
+\cs{tlabel} commands; inside an mfpic environment they affect all
+\cs{tlabel} commands in that figure.
+
+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}.
+
+The commands may be used anywhere. Outside a figure they affect all
+subsequent figures, inside a figure they affect all subsequent text in
+that figure. The commands and option are ignored under the metafont
+option.
+
+\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.
+
+This option is almost mandatory if you wish to use \prog{dvipdfm(x)} to
+convert \TeX{}'s DVI output to PDF. Both \prog{dvipdfm} and
+\prog{dvipdfmx} have a tendency to clip \MP{} figures to the stated
+bounding box. Thus, anything running outside those bounds is lost.
+
+
+\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{} and \CMP{} 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: \kw{numeric}, \kw{pair}, \kw{color} (\MP{}
+only), \kw{path}, \kw{picture} and \kw{boolean}.%
+ \footnote{For the curious, there are a total of eight types (nine or
+ ten for \MP{}). The other three are \kw{string}, \kw{transform} and
+ \kw{pen}. \MF{} also permits expressions that produce nothing, which
+ is sometimes called the vacuous type, but doesn't allow (or need)
+ variables of this type.}
+In \MP{} version 1.000, a tenth data type was added, \kw{cmykcolor}, and
+the \kw{color} data type can be referred to as `\kw{rgbcolor}' when a
+distinction is necessary.
+
+A \emph{variable} is a symbolic name, which can be a single letter such
+as \mfc{A}, or a descriptive name like \mfc{origin}. 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 \kw{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{Numerics and pairs.}\label{pairs}
+
+\CMF{} has \kw{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. These \kw{numeric} quantities can be constants (explicit
+numbers) or variables (symbolic names). In fact, \mfc{in} and \mfc{pt}
+are symbolic names for \kw{numeric} quantities.
+
+\CMF{} also has \kw{pair} objects, which may be constants or variables.
+Constants of type \kw{pair} 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{Colors.}\label{MPcolors}
+
+\CMP{} has the same concepts as \MF, but also has \kw{color} objects,
+which may also be constants or variables. In recent MP{}, colors come in
+two flavors: \kw{rgbcolor} and \kw{cmykcolor}. Constants of type
+\kw{rgbcolor} 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). Constants of type
+\kw{cmykcolor} have the form \mfc{($c$,$m$,$y$,$k$)} where $c$, $m$, $y$
+and $k$ are numbers between $0$ and $1$ determining the relative
+proportions of cyan, magenta, yellow and black in the color (the `cmyk'
+model).
+
+A color variable is a name, like \mfc{red}, \mfc{blue} (both predefined
+rgb colors in \MP) or \gbc{magenta} (predefined by \mfp{} to be an rgb
+color if \MP{} has version ${}<1.000$, a cmyk color if the version is at
+least 1.000).
+
+
+\section{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,
+objects of type \kw{picture} 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 \kw{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 \kw{boolean} data type is one of the values \mfc{true} or
+\mfc{false}. Variables of type \kw{boolean} 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 \kw{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 this will cause no
+harm, but it would be better to avoid doing it altogether, because there
+are cases where it will cause wrong results or error messages.
+
+
+\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.
+
+There may be limitations on what can be used as a filename. As of \mfp{}
+version \mfpversion, we have tried to permit \cs{jobname} as part of
+\meta{file}. Thus we permit \TeX{} macros, but they should expand to
+non-special characters. Permitting macros makes it essentially
+impossible for the filename to contain the backslash and brace
+characters. Also spaces are problematic. However other special \TeX{}
+characters (for example: tilde, underscore and percent) can be used,
+though that is really not recommended.
+
+\begin{cd}\pagelabel{mfpic}
+\cs{mfpic}\oarg{\meta{xfactor}}\oarg{\meta{yfactor}}%
+ \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{xfactor} and
+\meta{yfactor} 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{xfactor}$ times
+\cs{mfpicunit}, its height $(\meta{ymax}-\meta{ymin})\cdot\meta{yfactor}$
+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 designated 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{xfactor} and \meta{yfactor}.
+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.
+
+The value of these 6 parameters to \cs{mfpic} are available within the
+environment as macros: \cs{xfactor}, \cs{yfactor}, \cs{xmin}, \cs{xmax},
+\cs{ymin} and \cs{ymax}.
+
+\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.
+\Mfp{} provides commands to change any of these parameters. When \MP{}
+output is selected, figures can be drawn in any color and several of the
+above mentioned parameters are colors. For example, \gbc{drawcolor} is
+the name of the default color used to draw curves, \gbc{headcolor} is
+used when drawing arrowheads, etc. To save repetition: all special
+colors for figures are initialized to \mfc{black} except
+\mfc{background}, which is \mfc{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 macro \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 point 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 \eTeX{}.)
+
+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
+outside the borders 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. A negative radius is a mathematical error, but
+it is accepted. It produces the same circle, with the same sense, but
+the starting point (normally \meta{$r$} units to the right of the
+center) is \meta{$r$} units \emph{left} of the center.
+
+\item[\oarg{c}] The \textit{center-point form}. In this case the data
+should be the center and one point on the circumference. The circle
+starts at the point and has an anticlockwise sense.
+
+\item[\oarg{t}] The \textit{three-point form}. The data are three points
+that do not lie in a straight line. The circle starts at the first point
+and has the sense determined by the order of the points.
+
+\item[\oarg{s}] The \textit{point-sweep form}. The data are two points on the
+circle, followed by the angle of arc between them. This circle starts at
+the first point and has a sense determined by the angle: anticlockwise
+for positive angles, clockwise for negative.
+
+\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. The sense of the circle is
+normally anticlockwise starting at the first point. Using a negative
+radius is a mathematical error, but this command just produces the other
+circle with the opposite sense.
+
+\item[\oarg{q}] The \textit{alternative point-radius form}. The data are
+the same as for the \oarg{r} case, except the other circle is produced.
+That is, a circle starting at the first point, proceeding anticlockwise
+through an angle greater than $180$ degrees to the second point, then
+along the shorter arc to the first point. Again, a negative radius
+produces the other circle with clockwise sense.
+\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.
+
+\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. If the first angle is
+less than the second, the arc has an anticlockwise sense, otherwise
+clockwise. A negative radius is a mathematical error, but the result is
+the arc on the opposite side of the circle, as if both angles were
+increased by $180$ degrees
+
+\item[\oarg{a}] The alternative polar form differs from the polar form
+above only in the order of the arguments. This seems (to me) a more
+reasonable order, and matches the order \cs{sector} requires (see below).
+The 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 is the fundamental method for drawing arcs. All other methods are
+converted to this or the point-sweep method. Even the point sweep form
+is converted to this one for angles greater than 90 degrees.
+
+\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 an arc on the
+circle that \cs{circle}\oarg{r} would produce. The arc starts at the
+point \meta{$p_0$} and ends at \meta{$p_1$}. Of the two possible arcs on
+that circle, it produces the shorter one that covers an angle $\theta$
+from $0$ to $180$ degrees measured anticlockwise around the center
+of the circle. A negative radius is a mathematical error, but the result
+is the short arc on the other circle with a clockwise sense.
+
+\item[\oarg{q}] The \textit{alternative point-radius form} is the same as
+\oarg{r} except it produces the longer arc, that covers an angle
+$\theta$ between $180$ and $360$ degrees measured anticlockwise around
+the center of the circle. A negative radius is a mathematical error, but
+the result is the longer arc on the other circle with a clockwise sense.
+\end{description}
+
+For both options \oarg{r} and \oarg{q} the angle is computed and then
+the point-sweep method is used. If the absolute value of the radius is
+less than half the distance between the points, then no such arc exists.
+In this case, the angle is just set equal to $\pm180$ degrees (as if the
+radius were changed to half the distance).
+
+\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 single \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}
+
+This last circle-producing macro I wrote for my own use. It produces a
+circle associated with the hyperbolic geometry of a disk or a
+half-plane.
+
+\begin{cd}\pagelabel{pshcircle}
+\cs{pshcircle}\marg{\meta{center},\meta{radius}}\\
+\cs{pshcircle}*\marg{\meta{center},\meta{radius}}%
+\index{pshcircle@\cs{pshcircle}}%
+\end{cd}
+
+This produces the circle whose hyperbolic center is at \meta{center} and
+whose pseudohyperbolic radius is \meta{radius}. This all takes place
+inside the circle with center $(0,0)$ and radius $1$ (the \emph{unit
+circle}). The \meta{center} is required to be inside the unit circle and
+the \meta{radius} is required to be less than $1$.
+
+The star-form is for the \emph{upper half-plane}, which is the set of
+points with positive $y$-coordinate In this case, the \meta{center} must
+be in the upper half-plane and the \meta{radius} must still be less than
+$1$. If you are not versed in hyperbolic geometry, be warned that the
+actual diameter of the resulting circle is on the order of $2y/(1-R)$,
+where $R$ is the \meta{radius}. This can be quite large even for modest
+values of $R$ and $y$.
+
+
+\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 heave 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 in \mfp{}.}\label{colors}
+
+\subsection{\CMP{} color functions}\label{mpcolors}
+
+Because of changes to color handling with \MP{} 1.000, we will have to
+give two descriptions of some operations. For brevity, we will refer to
+\MP{} versions before the addition of the \kw{cmykcolor} data type as
+`early' \MP{} and the versions afterward as `recent' \MP{}. Early \MP{}
+actually ended with version 0.642. When development resumed, beta test
+versions began with 0.900. Any version 0.900 or later qualifies as
+`recent'.
+
+In early \MP{}, the only \kw{color} data type is a triple of numbers
+like \mfc{(1,.5,.5)}, with the components 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)}. Recent \MP{} has the
+\kw{color} data type (refered to as either \kw{color} or \kw{rgbcolor})
+as well as the \kw{cmykcolor} type. A \kw{cmykcolor} is a quadruple of
+numbers like \mfc{(1,.2,0,.3)}, with components between 0 and 1
+representing levels of cyan, magenta, yellow and black. White is
+represented by \mfc{(0,0,0,0)}. While black can be obtained in several
+ways,\mfc{(0,0,0,1)} is the simplest.
+
+\CMP{} also has \kw{color} variables (and \kw{cmykcolor} variables) and
+several have been predefined. The colors \mfc{red}, \mfc{green},
+\mfc{blue}, \mfc{white} and \mfc{black} are built in to \MP{} and are of
+type \kw{rgbcolor}. Colors \gbc{cyan}, \gbc{magenta} and \gbc{yellow}
+are defined by \mfp{}'s \MP{} support macros to be \kw{cmykcolor}. In
+addition, \mfp{} defines \gbc{cmykblack}, \gbc{cmykwhite},
+\gbc{rgbblack}, \gbc{rgbwhite}, \gbc{grayscaleblack} and
+\gbc{grayscalewhite}. These give black and white in the indicated data
+type (grayscale being a numeric: $0$ for black, $1$ for white).
+
+All the names in the \LaTeX{} \prog{color} package's \file{dvipsnam.def}
+have also been predefined by \mfp{} as color variable names. Since \MP{}
+allows color expressions, colors may be added (as long as they are the
+same type) and multiplied by numerics. Multiplication by a number
+between $0$ and $1$ darkens a \kw{rgbcolor}, but lightens a
+\kw{cmykcolor}.
+
+Moreover, several \MP{} color functions have been defined in
+\file{grafbase.mp}. These have the same names as the color models.
+Strictly speaking, it is never necessary to use these in recent \MP{}.
+However, since \MF{} and early \MP{} don't have a data type consisting
+of quadruples, and \MF{} doesn't have one for triples, these functions
+allow the same \mfp{} code to be used for all three figure processors.
+These functions are defined to convert to a usable data type, (which may
+be ignored in \MF{}).
+
+\begin{cd}
+\mfc{cmyk($c$,$m$,$y$,$k$)}%
+\index{cmyk@\mfc{cmyk($c$,$m$,$y$,$k$)}}
+\end{cd}
+
+In early \MP{}, this converts a cmyk color specification to \MP{}'s
+native rgb. For example, the command \mfc{cmyk(1,0,0,0)} yields
+\mfc{(0,1,1)}, which is the rgb equivalent of cyan. In recent \MP{} this
+produces the \kw{cmykcolor} with the given components. That is,
+\gbc{cmyk(1,0,0,0)} simply produces $(1,0,0,0)$, the cmyk coding for
+cyan.
+
+\begin{cd}
+\mfc{gray($g$)}%
+\index{gray@\mfc{gray($g$)}}
+\end{cd}
+
+In early \MP{}, this converts a numeric $g$ (designating a level of
+gray) to the corresponding multiple of white: \mfc{($g$,$g$,$g$)}. In
+recent \MP{}, commands to draw paths or pictures in a particular color
+will accept a \kw{numeric} parameter instead of \kw{color} or
+\kw{cmykcolor}, so in recent \MP{} this command simply returns the given
+numeric $g$.
+
+\begin{cd}
+\mfc{named(\meta{name})},
+\mfc{rgb($r$,$g$,$b$)}%
+\index{named@\mfc{named(\meta{name})}}%
+\index{rgb@\mfc{rgb($r$,$g$,$b$)}}
+\end{cd}
+
+These are essentially no-ops. However; \mfc{rgb()} will truncate the
+arguments to the 0--1 range, and set an unknown argument to 0. An
+unknown \meta{name} is converted to \mfc{black} (in the appropriate
+color model if \meta{name} is an unknown color variable, otherwise rgb
+black).
+
+\begin{cd}
+\mfc{RGB($R$,$G$,$B$)}%
+\index{RGB@\mfc{RGB($R$,$G$,$B$)}}
+\end{cd}
+
+Converts an RGB color specification to rgb. It divides each component by
+255, and performs the same truncations as \gbc{rgb()}. The RGB model
+consists of a triple of numbers between 0 and 255. Originally, the model
+required they be integers. However, since they are converted to
+fractions anyway, it doesn't matter in this command.
+
+\medskip
+As an example of the use of these functions, in early \MP{} one could
+conceivable write:
+%
+\begin{verbatim}
+\draw[0.5*RGB(255,0,0)+0.5*cmyk(1,0,0,0)]\circle{(0,0),1}
+\end{verbatim}
+%
+to have a circle drawn in a color halfway between red and cyan (which
+turns out to be the same as \gbc{gray(0.5)}). In recent \MP{}, however,
+this would be an error, as one cannot add two different data types
+(\kw{rgbcolor} and \kw{cmykcolor}). So \mfp{} supplies conversion functions.
+
+\begin{cd}
+\mfc{makecmyk \meta{clr}}\\
+\mfc{makergb \meta{clr}}\\
+\mfc{makegray \meta{clr}}%
+\index{makecmyk@\mfc{makecmyk}}%
+\index{makergb@\mfc{makergb}}%
+\index{makegray@\mfc{makegray}}
+\end{cd}
+
+In recent \MP{}, the \meta{clr} can be a known color name, a constant
+of type \kw{numeric}, \kw{rgbcolor}, or \kw{cmykcolor}, or the result of
+a color function. Then \mfc{makecmyk} returns the \kw{cmykcolor}
+equivalent, and \mfc{makergb} returns the \kw{rgbcolor} equivalent (a
+\kw{numeric} \meta{clr} is interpreted as a grayscale color). Unknown
+colors produce a black in the appropriate model. Then one can use
+%
+\begin{verbatim}
+\draw{.5*RGB(255,0,0) + .5*makergb cmyk(1,0,0,0)}\circle{(0,0),1}
+\end{verbatim}
+%
+And if one didn't know that \mfc{RGB} returned an \kw{rgbcolor}, one
+could also write \verb$makergb RGB(255,0,0)$ to be sure to get an
+\kw{rgbcolor}.
+
+The first two commands are never necessary in early \MP{}, but they are
+still defined: they simply return the given color if it is a known
+argument of type \kw{color}, or apply the function \gbc{gray()} is it is
+\kw{numeric}, and return black for an unknown name.
+
+The last one \gbc{makegray} converts any color to a numeric, and then
+returns either that number (recent \MP) or that multiple of \mfc{white}
+(early \MP). In \MF{}, all three pass the (presumably numeric) argument
+\meta{clr} unchanged.
+
+All three functions return some kind of black if \meta{clr} is not some
+kind of color, or has an unknown value.
+
+
+\subsection{Establishing \mfp{} default colors}\label{defaultcolors}
+
+\begin{cd}\pagelabel{drawcolor}
+\cs{drawcolor}\oarg{\meta{model}}\marg{\meta{colorspec}}\\
+\cs{fillcolor}\oarg{\meta{model}}\marg{\meta{colorspec}}\\
+\cs{hatchcolor}\oarg{\meta{model}}\marg{\meta{colorspec}}\\
+\cs{pointcolor}\oarg{\meta{model}}\marg{\meta{colorspec}}\\
+\cs{headcolor}\oarg{\meta{model}}\marg{\meta{colorspec}}\\
+\cs{tlabelcolor}\oarg{\meta{model}}\marg{\meta{colorspec}}\\
+\cs{backgroundcolor}\oarg{\meta{model}}\marg{\meta{colorspec}}%
+\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 \texttt{rgb}, \texttt{RGB},
+\texttt{cmyk}, \texttt{gray}, and \texttt{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 named \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}.
+
+If the optional \meta{model} argument is omitted, the color
+specification may be any expression recognized as a color by \MP{}. It
+is highly recommended (for portability) that one use either a predefined
+name or one of the color functions of the previous section.
+
+When the optional \meta{model} is specified in the color setting
+commands, it determines the format of the color specification as in
+figure~\ref{fig:colorspecs}.
+
+\begin{figure}[hbt]
+\halign{\quad\texttt{#}\hfil\quad&#\hfil\cr
+\omit\quad{\slshape Model:}\hfil& {\slshape Specification:}\cr
+rgb & Three numbers in the range 0 to 1 separated by commas.\cr
+RGB & Three numbers in the range 0 to 255 separated by commas.\cr
+cmyk & Four numbers in the range 0 to 1 separated by commas.\cr
+gray & One number in the range 0 to 1, with 0 indicating
+ black, 1 white.\cr
+named & A \MP{} color variable name either predefined by
+ \mfp{} or by the user.\cr}
+\caption{Color specifications}
+\label{fig:colorspecs}
+\end{figure}
+
+\pagebreak[3]
+\Mfp{} translates the command:
+\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. One sees
+from this that the optional argument is never necessary. It's there only
+to make the \LaTeX{} user comfortable.
+
+
+\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 \texttt{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{\CMF{} colors}\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 not 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 macro: 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} path, an
+\emph{output} path, and a \emph{side effect}. 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} take no input path; 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[Apending macros] These\index{prefix macro} pass their input
+ unchanged as their output. Their side effect is the appending of
+ some object such as an arrow head or tail. Currently only the
+ various prefix macros whose names begin with \texttt{arrow} are
+ appending macros (see subsection~\ref{arrows}). But \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[Rendering macros] 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[Modifying macros] 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} and \cs{bclosed} will close it without adding any path 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 its
+name makes sense (and its action is predictable) 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 where the center of the arc is (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 leftmost \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\\
+\cs{trimpath}\marg{\meta{dim$_1$},\meta{dim$_2$}}\dots\\
+\cs{trimpath}\marg{\meta{dim}}\dots%
+\index{partpath@\cs{partpath}}%
+\index{subpath@\cs{subpath}}%
+\index{trimpath@\cs{trimpath}}%
+\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.
+
+The \cs{trimpath} macro takes two dimensions separated by commas and
+trims those lengths off the initial and terminal ends of the following path.
+Alternatively, it takes one dimension and and trims that length off of
+both ends. If any of \meta{dim$_1$}, \meta{dim$_2$} or \meta{dim} is
+missing, it is taken to be \dim{0pt}. This works by finding the points of
+intersection between the path and circles around the endpoints with the given
+dimensions as radii. If the path is shorter than either dimension, it
+will not intersect either circle and nothing will be trimmed. Similar
+problems can occur, at one end or the other, if the path is shorter than
+the sum of the dimensions.
+
+\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 (for example)
+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. The optional \meta{color} defaults to \gbc{headcolor},
+initially black. 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'.
+
+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{background} (usually the same as
+\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 a node. 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}, \cs{levelcurve}, \cs{makesector},
+ \cs{piewedge}, \cs{plrregion},\\
+ \cs{polygon}, \cs{pshcircle}. \cs{rect}, \cs{regpolygon},
+ \cs{sector}, \cs{tlabelcircle},\\
+ \cs{tlabelellipse}, \cs{tlabeloval}, and \cs{tlabelrect}.
+\end{display}
+
+The macros of this section can all be used to fill (or unfill) the
+interior of closed paths, even if the paths cross themselves. Filling an
+open curve is technically an error, but the \MF{} code responds by
+drawing the path and not doing any filling. Note that these macros
+override the default rendering, so if you want some sort of fill pattern
+\emph{and} an outline drawn, you need an explicit prefix for both.
+
+\begin{cd}\pagelabel{gfill}
+\cs{gfill}\oarg{\meta{color}}$\ldots$%
+\index{gfill@\cs{gfill}}
+\end{cd}
+
+This rendering macro fills in the subsequent closed path. Under \MP{} it
+fills with \meta{color}, which defaults to
+\index{fillcolor@\gbc{fillcolor}}\gbc{fillcolor}. Under \MF{} it
+approximates the color with a shade of gray, clears the interior, and
+then fills with a pattern of black and white pixels simulating gray.
+
+\begin{cd}\pagelabel{gclear}
+\cs{gclear}$\ldots$%
+\index{gclear@\cs{gclear}}
+\end{cd}
+
+This rendering macro erases everything \emph{inside} the subsequent
+closed path (except text labels under some circumstances, see
+section~\ref{mplabels} and \ref{overlaylabels}). Under \MP{} it actually
+fills with the predefined color named \mfc{background}. Since
+\mfc{background} is normally \mfc{white}, and so are most actual
+backgrounds, this is usually indistinguishable from clearing. However,
+if an \env{mfpic} environment utilzes \emph{background text} (see
+subsection~\ref{text}), part of the background text may appear to be
+`erased'. Unfortunately, there is little that can be done about this.
+
+\begin{cd}\pagelabel{gclip}
+\cs{gclip}$\ldots$%
+\index{gclip@\cs{gclip}}
+\end{cd}
+
+This rendering macro erases everything \emph{outside} the subsequent
+closed path from the picture (except text labels under some
+circumstances, see section~\ref{mplabels} and \ref{overlaylabels}). Note
+that this is a true erasing, even in \MP{}.
+
+\begin{cd}\pagelabel{shade}
+\cs{shade}\oarg{\meta{shadesp}}$\ldots$%
+\index{shade@\cs{shade}}
+\end{cd}
+
+This rendering macro shades the interior of the subsequent closed path
+with dots. The diameter of the dots is the \MF{} variable \mfc{shadewd},
+set by the macro \cs{shadewd}\marg{\meta{size}}. Normally this is
+\dim{0.5bp}. The optional argument specifies the spacing between (the
+centers of) the dots, which defaults to the \TeX{} dimension
+\cs{shadespace}, initially \dim{1pt}. If \cs{shadespace} is less than
+\mfc{shadewd}, the closed path is filled with black, as if with
+\cs{gfill}. Under \MP{} this macro actually fills the path's interior
+with a shade of gray. The shade to use is computed based on
+\cs{shadespace} and \mfc{shadewd}. The default values of these
+parameters correspond to a gray level of about 78\% of white.%
+ \footnote{If \cs{shadewd} is $w$ and \cs{shadespace} is $s$, then
+ the level of gray is $1 - (.88w/s)^2$, where $0$ denotes black and
+ $1$ white.} %
+The \MF{} version attempts to optimize the dots to the pixel grid
+corresponding to the printers resolution (to avoid generating dither
+lines). Because this involves rounding, it will happen that values of
+\cs{shadespace} that are relatively close and at the same time close to
+\mfc{shadewd} produce exactly the same shade. Most of the time, however,
+values of \cs{shadespace} that differ by at least 20\% will produce
+different patterns. The actual behavior for particular values of the
+parameters and particular printer resolutions cannot be predicted, and
+we even make no guarantee it will not change from one version of \mfp{}
+to another.
+
+\begin{cd}\pagelabel{polkadot}
+\cs{polkadot}\oarg{\meta{space}}$\ldots$%
+\index{polkadot@\cs{polkadot}}
+\end{cd}
+
+This rendering macro fills the interior of a closed path with large
+dots. This is almost what \cs{shade} does, but there are several
+differences. \cs{shade} is intended solely to simulate a gray fill in
+\MF{} where the only color is black. So it is optimized for small dots
+aligned to the pixel grid (in \MF{}). In \MP{} \cs{shade} only fills with
+gray and is intended merely for compatibility. The macro \cs{polkadot}
+is intended for large dots in any color, and so it optimizes spacing (a
+nice hexagonal array) and makes no attempt to align at the pixel level.
+The \meta{space} defaults to the \TeX{} dimension \cs{polkadotspace},
+initially \dim{10pt}. The diameter of the dots is the value of the \MF{}
+variable \mfc{polkadotwd}, which can be set with
+\cs{polkadotwd}\marg{\meta{size}}, and is initially \dim{5bp}. The dots
+are colored with \index{fillcolor@\gbc{fillcolor}}\gbc{fillcolor}. In
+\MF{}, nonblack values of \gbc{fillcolor} will produce shaded dots.
+
+\begin{cd}\pagelabel{thatch}
+\cs{thatch}\oarg{\meta{hatchsp},\meta{angle}}\oarg{\meta{color}}$\ldots$%
+\index{thatch@\cs{thatch}}
+\end{cd}
+
+This rendering macro fills a closed path with equally spaced parallel
+lines at the specified angle. The thickness of the lines is set by the
+macro \cs{hatchwd}. In the optional argument, \meta{hatchsp} specifies
+the space between lines, which defaults to the \TeX{} dimension
+\cs{hatchspace}, initially \dim{3pt}. The \meta{angle} defaults to 0.
+The \meta{color} defaults to \gbc{hatchcolor}. If \cs{hatchspace} is
+less than the line thickness, the closed path is filled with
+\meta{color}, as if with \cs{gfill}. If the first optional argument
+appears, both parts must be present, separated by a comma. For the color
+argument to be present, the other optional argument must also be
+present. However, if one wishes only to override the default color one
+can use an empty first optional argument (completely empty, no spaces or
+comma).
+
+\begin{cd}\pagelabel{hatch}
+\cs{lhatch}\oarg{\meta{hatchsp}}\oarg{\meta{color}}$\ldots$\\
+\cs{rhatch}\oarg{\meta{hatchsp}}\oarg{\meta{color}}$\ldots$\\
+\cs{hatch}\oarg{\meta{hatchsp}}\oarg{\meta{color}}$\ldots$\\
+\cs{xhatch}\oarg{\meta{hatchsp}}\oarg{\meta{color}}$\ldots$%
+\index{lhatch@\cs{lhatch}}%
+\index{rhatch@\cs{rhatch}}%
+\index{hatch@\cs{hatch}}%
+\index{xhatch@\cs{xhatch}}%
+\end{cd}
+
+These rendering macros are just \cs{thatch} with predefined values of
+the angle. \cs{lhatch} fills the region with left slanted lines (from
+upper left to lower right). It is exactly the same as
+\begin{display}
+\cs{thatch}\oarg{\meta{hatchsp},-45}\oarg{\meta{color}}$\ldots$
+\end{display}
+
+\cs{rhatch} draws right slanted lines (lower left to upper right). It is
+exactly the same as
+\begin{display}
+\cs{thatch}\oarg{\meta{hatchsp},45}\oarg{\meta{color}}$\ldots$
+\end{display}
+
+\cs{hatch} (\cs{xhatch} is a synonym) draws lines in a cross-hatched
+pattern. It is exactly the same as \cs{rhatch} followed by \cs{lhatch}
+using the same \meta{hatchsp} and \meta{color}.
+
+Hatching should normally be used very sparingly, or never if
+alternatives are available (color, shading). However, hatching or
+polkadotting on top of another filling macro is almost the only way to
+fill in two regions that \emph{automatically} shows the overlap area.
+Hatching is at least less garish than polkadots.
+
+
+\subsection{Changing the default rendering}\label{default}
+
+\emph{Rendering} is the process of converting a geometric description
+into a drawing. In \MF{}, this means producing a bitmap (\MF{} stores
+these in \mfc{picture} variables), either by stroking (drawing) a path
+using a particular pen), or by filling a closed path. In \MP{} it means
+producing a \PS{} description of penstrokes and fills (with possible
+clipping).
+
+\begin{cd}\pagelabel{setrender}
+\cs{setrender}\marg{\meta{\TeX{} commands}}%
+\index{setrender@\cs{setrender}}
+\end{cd}
+
+Initially, \mfp{} uses the \cs{draw} command (stroking) as the default
+operation when a figure is to be rendered. However, this can be changed
+to any combination of \mfp{} rendering commands or indeed any \TeX{}
+commands, by using the \cs{setrender} command. This redefinition is
+local inside an \env{mfpic} environment, so it can be enclosed in braces
+to restrict its range. Outside an \env{mfpic} environment it is a global
+redefinition.
+
+For example, after \cs{setrender}\marg{\cs{dashed}\cs{shade}} the
+command \cs{circle}\marg{(0,0),1} produces a shaded circle with a dashed
+outline. Any explicit rendering prefix overrides this default.
+
+\subsection{Examples}\label{examples}
+
+It may be instructive, for the purpose of understanding the syntax of
+\emph{shape-modifier and rendering prefixes}, to consider two examples:
+\begin{ex}
+ \cs{draw}\cs{gfill}\oarg{red}\cs{lclosed}\cs{polyline}\marg{$\ldots$}
+\end{ex}
+which fills inside a polygon and draws its outline; and
+\begin{ex}
+ \cs{gfill}[red]\cs{lclosed}\cs{draw}\cs{polyline}\marg{$\ldots$}
+\end{ex}
+which draws all of the outline \emph{except} the line segment supplied
+by \cs{lclosed}, then fills the interior. Thus, in the first case the
+path is first defined (by \cs{polyline}), then closed, then the resulting closed
+path is filled, and finally drawn. In the second case the order is:
+defined, drawn, closed, filled. In particular, what is drawn in the
+second case is the path not yet closed. It should also be pointed out
+that in the last case, the fill is placed last and will cover half
+the thickness of the previously drawn outline.
+
+
+\section{Functions and Plotting.}\label{functions}
+
+In the following macros, expressions like $f(\mathtt{x})$ or $g(\mathtt{t})$
+stand for any legal \MF{} expression, in which the only unknown
+variables are those indicated (\texttt{x} in the first case, and \texttt{t} in
+the second).
+
+\subsection{Defining functions}\label{defining}
+
+\begin{cd}\pagelabel{fdef}
+\cs{fdef}\marg{\meta{fcn}}\marg{\meta{param1},\meta{param2},$\ldots$}%
+ \marg{\meta{mf-expr}}%
+\index{fdef@\cs{fdef}}
+\end{cd}
+
+Defines a \MF{} function \meta{fcn} of the parameters \meta{param1},
+\meta{param2}, $\ldots$, by the \MF{} expression \meta{mf-expr} in which
+the only free parameters are those named. The return type of the
+function is the same as the type of the expression. What is allowed for
+the function name \meta{fcn} is more restrictive than \MF{}'s rule for
+variable names. Roughly speaking, it should consist of letters and
+underscore characters only. (In particular, for those that know what
+this means, the name should have no suffixes.) Try to make the name
+distinctive to avoid redefining internal \MF{} commands.
+
+The expression \meta{mf-expr} is passed directly into the corresponding
+\MF{} macro and interpreted there, so \MF{}'s rules for algebraic
+expressions apply. If \cs{fdef} occurs inside an \env{mfpic}
+environment, it is local to that environment, otherwise it is available
+to all subsequent \env{mfpic} environments.
+
+As an example, after \cs{fdef}\marg{myfcn}\marg{s,t}\marg{s*t-t}, any
+place below where a \MF{} expression is required, you can use
+\mfc{myfcn(2,3)} to mean \mfc{2*3-3} and \mfc{myfcn(x,x)} to mean
+\mfc{x*x-x}.
+
+Operations available include \mfc{+}, \mfc{-}, \mfc{*}, \mfc{/}, and
+\mfc{**} (\mfc{x**y}$=x^y$), with `\mfc{(}' and `\mfc{)}' for grouping.
+Functions already available include the standard \MF{} functions
+\mfc{round}, \mfc{floor}, \mfc{ceiling}, \mfc{abs}, \mfc{sqrt},
+\mfc{sind}, \mfc{cosd}, \mfc{mlog}, and \mfc{mexp}. Note that in \MF{}
+the operations \mfc{*} and \mfc{**} have the same level of precedence,
+so \mfc{x*y**z} means $(xy)^z$. Use parentheses liberally!
+
+(\textit{Notes:} The \MF{} trigonometric functions \mfc{sind} and
+\mfc{cosd} take arguments in degrees; \mfc{mlog(x)}$=256\ln x$, and
+\mfc{mexp} is its inverse.) You can also define the function \meta{fcn}
+by cases, using the \MF{} conditional expression
+\begin{ex}
+ \mfc{if~\meta{boolean}:~\meta{expr}~elseif
+ \meta{boolean}:~$\ldots$~else:~\meta{expr}~fi}.
+\end{ex}
+Relations available for the \meta{boolean} part of the expression
+include \mfc{=}, \mfc{<}, \mfc{>}, \mfc{<=}, \mfc{<>} and \mfc{>=}.
+
+Complicated functions can be defined by a compound expression, which is
+a series of \MF{} statements, followed by an expression, all enclosed
+between \mfc{begingroup} and \mfc{endgroup}. The \cs{fdef} command
+automatically supplies these grouping commands around the definition so
+if the entire \meta{mf-expr} is one such compound expression the user
+need not type them. \CMF{} functions can call \MF{} functions, even
+recursively.
+
+Many common functions have been predefined in \file{grafbase}, which is
+a package of \MF{} macros that implement \prog{mfpic}'s drawing. These
+include the rest of the trig functions \mfc{tand}, \mfc{cotd}, \mfc{secd},
+\mfc{cscd}, which take angles in degrees, plus variants \mfc{sin},
+\mfc{cos}, \mfc{tan}, \mfc{cot}, \mfc{sec}, and \mfc{csc}, which take
+angles in radians. Some inverse trig functions are also available, the
+following produce angles in degrees: \mfc{asin}, \mfc{acos}, and
+\mfc{atan}, and the following in radians: \mfc{invsin}, \mfc{invcos},
+\mfc{invtan}. The exponential and hyperbolic functions: \mfc{exp},
+\mfc{sinh}, \mfc{cosh}, \mfc{tanh}, \mfc{coth}, \mfc{sech}, and
+\mfc{csch}; and some of their inverses: \mfc{ln} (or \mfc{log}),
+\mfc{asinh}, \mfc{acosh}, and \mfc{atanh} are also defined.
+
+There are also two conversion functions: \gbc{radians(t)} produces the
+number of radians in \mfc{t} degrees and \gbc{degrees(t)} produces the
+number of degrees in \mfc{t} radians. In these expressions the special
+variable \gbc{pi} produces $\pi$, accurate to roughly 5 decimals.
+(\CMF{} and \MP{} provide accuracy only to $\pm2^{-17} = \pm
+.76\times10^{-5}$.)
+
+The integer functions \gbc{gcd(m,n)} and \gbc{lcm(m,n)} produce the
+greatest common divisor and least common multiple of two integers
+\gbc{m} and \gbc{n}.
+
+
+\subsection{Plotting functions}\label{plotting}
+
+The plotting macros take two or more arguments. They have an optional
+first argument, \meta{spec}, which determines whether a function is
+drawn smooth (as a \MF{} B\'ezier curve), or polygonal (as line
+segments)---if \meta{spec} is \texttt{p}, the function will be
+polygonal. Otherwise the \meta{spec} should be \texttt{s}, followed by
+an optional positive number no smaller than 0.75. In this case the
+function will be smooth with a tension equal to the number. See the
+\cs{curve} command (subsection~\ref{curves}) for an explanation of
+tension. The default \meta{spec} depends on the purpose of the macro.
+
+One compulsory argument contains three values \meta{min}, \meta{max} and
+\meta{step} separated by commas. The independent variable of a function
+starts at the value \meta{min} and steps by \meta{step} until reaching
+\meta{max}. If \meta{max}${}-{}$\meta{min} is not a whole number of
+steps, then round$((\meta{max}-\meta{min})/\meta{step})$ equal steps are
+used. One may have to experiment with the size of \meta{step}, since
+\MF{} merely connects the points corresponding to these steps with what
+\emph{it} considers to be a smooth curve. Smaller \meta{step} gives
+better accuracy, but too small may cause the curve to exceed \MF{}'s
+capacity or slow down its processing. Increasing the tension may help
+keep the curve in line, but at the expense of reduced smoothness.
+
+There are one or more subsequent arguments, each of which is a \MF{}
+function or expression as described above. All the macros are figure
+macros, defining a path to which prefixes may be applied.
+
+\begin{cd}\pagelabel{function}
+\cs{function}\oarg{\meta{spec}}\marg{\meta{$x_{\mathrm{min}}$},%
+ \meta{$x_{\mathrm{max}}$},\meta{$\Delta x$}}%
+ \marg{$f(\mathtt{x})$}%
+\index{function@\cs{function}}
+\end{cd}
+
+This figure macro produces the graph of $y = f(x)$, where $f$ is a \MF{} numeric
+function or expression of one numeric argument, which must be denoted by
+a literal \texttt{x}. The default \meta{spec} is \texttt{s}. For example
+\begin{verbatim}
+\function{0,pi,pi/10}{sin x}
+\end{verbatim}
+draws the graph of $\sin x$ between 0 and $\pi$.
+
+\begin{cd}\pagelabel{parafcn}
+\cs{parafcn}\oarg{\meta{spec}}\marg{\meta{$t_{\mathrm{min}}$},%
+ \meta{$t_{\mathrm{max}}$},\meta{$\Delta t$}}%
+ \marg{($x(\mathtt{t}), y(\mathtt{t})$)}\\
+\cs{parafcn}\oarg{\meta{spec}}\marg{\meta{$t_{\mathrm{min}}$},%
+ \meta{$t_{\mathrm{max}}$},\meta{$\Delta t$}}%
+ \marg{\meta{pair-fcn}}%
+\index{parafcn@\cs{parafcn}}
+\end{cd}
+
+This figure macro produces the parametric path determined by the last
+argument. This can be a pair of expressions $x(\mathtt{t})$ and
+$y(\mathtt{t})$ enclosed in parentheses and separated by a comma, with
+the literal variable \texttt{t}. Alternatively, the last argument can be
+a \MF{} function or expression in \texttt{t} that returns a pair.%
+ \footnote{There are very few of these. \CMF{} provides \mfc{dir t},
+ which is essentially \mfc{(cosd t, sind t)}. \Mfp{} adds \gbc{cis t}
+ which is \gbc{(cos t, sin t)}.}
+The default \meta{spec} is \texttt{s}. For example
+\begin{verbatim}
+\parafcn{0,1,.1}{(2t, t+t*t)}
+\end{verbatim}
+plots a smooth parabola from $(0,0)$ to $(2,2)$.
+
+\begin{cd}\pagelabel{plrfcn}
+\cs{plrfcn}\oarg{\meta{spec}}\marg{\meta{$\theta_{\mathrm{min}}$},%
+ \meta{$\theta_{\mathrm{max}}$},\meta{$\Delta\theta$}}%
+ \marg{$f(\mathtt{t})$}%
+\index{plrfcn@\cs{plrfcn}}
+\end{cd}
+
+This figure macro produces the graph of the polar coordinate equation
+$r=f(\theta)$, where $f$ is a \MF{} numeric function or expression of
+one numeric argument, and $\theta$ varies from
+\meta{$\theta_{\mathrm{min}}$} to \meta{$\theta_{\mathrm{max}}$} in
+steps of \meta{$\Delta\theta$}. Each $\theta$ value is interpreted as an
+angle measured in \emph{degrees}. In the expression $f(\mathtt{t})$, the
+unknown \texttt{t} stands for $\theta$. The default \meta{spec} is
+\texttt{s}. For example
+\begin{verbatim}
+\plrfcn{0,90,5}{sind (2t)}
+\end{verbatim}
+draws one loop of a 4-petal rosette. Note that this function demands the
+variable \mfc{t} be in degrees. The range and step size must be in
+degrees and the function must operate on the numeric variable \gbc{t} in
+degrees. If one needs to measure angles in radians, use the conversion
+functions \gbc{degrees()} and \gbc{radians()}, as follows:
+\begin{verbatim}
+\plrfcn{0,degrees(pi/2),degrees(pi/36)}{sin (radians(2t))}
+\end{verbatim}
+
+
+\begin{cd}\pagelabel{btwnfcn}
+\cs{btwnfcn}\oarg{\meta{spec}}\marg{\meta{$x_{\mathrm{min}}$},%
+ \meta{$x_{\mathrm{max}}$},\meta{$\Delta x$}}%
+ \marg{$f(\mathtt{x})$}\marg{$g(\mathtt{x})$}\\
+\cs{btwnplrfcn}\oarg{\meta{spec}}\marg{\meta{$\theta_{\mathrm{min}}$},%
+ \meta{$\theta_{\mathrm{max}}$},\meta{$\Delta \theta$}}%
+ \marg{$f(\mathtt{t})$}\marg{$g(\mathtt{t})$}%
+\index{btwnfcn@\cs{btwnfcn}}%
+\index{btwnplrfcn@\cs{btwnplrfcn}}
+\end{cd}
+
+These are figure macros. The first one produces a closed path
+surrounding the region between the graphs of the two functions. The
+second one does the same for two polar functions. That is (in both
+cases), the path follows the first function (in order or increasing $x$
+or $\theta$), thence along the straight line to the \emph{end} of the
+second one, thence backwards along the second function (decreasing $x$
+or $\theta$) and finally along the straight line to the start. The last
+two mandatory arguments, the functions, are specified exactly as in
+\cs{function} and \cs{plrfcn}, being numeric functions of one numeric
+argument \texttt{x} or \texttt{t}. Unlike the previous function macros,
+the default \meta{spec} is \texttt{p}---these macros are intended to be
+used for shading between drawn functions, a task for which smoothness is
+usually unnecessary. For example, the first line below
+\begin{verbatim}
+\shade\btwnfcn{0,1,.1}{0}{x - x**2}
+\btwnplrfcn[s]{-30,30,5}{1}{2*cosd 2t}
+\end{verbatim}
+shades the area between the $x$-axis and the given parabola. The second
+draws the boundary of the region between the circle $r = 1$ and one loop
+of the rosette $r = 2\cos 2\theta$.
+
+Note: the effect of \cs{btwnfcn} could also be accomplished with
+\begin{ex}
+ \cs{lclosed}\cs{connect}\\
+ \cs{function}\marg{\meta{$x_{\mathrm{min}}$},%
+ \meta{$x_{\mathrm{max}}$},\meta{$\Delta x$}}\marg{$f(\mathtt{x})$}\\
+ \cs{reverse}\cs{function}\marg{\meta{$x_{\mathrm{min}}$},%
+ \meta{$x_{\mathrm{max}}$},\meta{$\Delta x$}}\marg{$g(\mathtt{x})$}\\
+ \cs{endconnect}
+\end{ex}
+\cs{lclosed} was described in subsection~\ref{closure} and the
+\cs{connect}\dots\cs{endconnect} pair was described in
+subsection~\ref{reversal}.
+
+\begin{cd}\pagelabel{belowfcn}
+\cs{belowfcn}\oarg{\meta{spec}}%
+ \marg{\meta{$x_{\mathrm{min}}$},\meta{$x_{\mathrm{max}}$},%
+ \meta{$\Delta x$}}\marg{$f(\mathtt{x})$}\\
+\cs{plrregion}\oarg{\meta{spec}}%
+ \marg{\meta{$\theta_{\mathrm{min}}$},\meta{$\theta_{\mathrm{max}}$},%
+ \meta{$\Delta\theta$}}\marg{$f(\mathtt{t})$}%
+\index{belowfcn@\cs{belowfcn}}%
+\index{plrregion@\cs{plrregion}}
+\end{cd}
+
+These figure macros produce identical results to \cs{btwnfcn} and
+\cs{btwnplrfcn} when the first function is just $0$. They are, however,
+much more efficient. The first of these, \cs{belowfcn}, produces the
+path surrounding the region bounded by the $x$-axis, the graph of
+$y=f(x)$ and the two vertical lines $x=x_{\mathrm{min}}$ and $x =
+x_{\mathrm{max}}$. (The region is not actually \emph{below} $y = f(x)$
+unless $f(x) \ge 0$ throughout the interval.) The second produces the
+path surrounding the region bounded by the polar function $r =
+f(\theta)$ and the two rays $\theta=\theta_{\mathrm{min}}$ and
+$\theta=\theta_{\mathrm{max}}$.
+
+The arguments of these command are the same as the nonclosed versions,
+\cs{function} and \cs{plrfcn}, except the default for the optional
+agument is \texttt{[p]}. Again, this is because it is mainly for
+shading. However, drawing the boundary is often needed:
+\begin{verbatim}
+\shade\plrregion{0,90,5}{sind (2t)}
+\plrregion[s]{0,90,5}{sind (2t)}
+\end{verbatim}
+shades one loop of the 4-petal rosette, and then draws it.
+
+\begin{cd}\pagelabel{levelcurve}
+\cs{levelcurve}\oarg{\meta{spec}}\marg{\meta{seed},\meta{step}}
+ \marg{\meta{inequality}}%
+\index{levelcurve@\cs{levelcurve}}
+\end{cd}
+
+This figure macro produces a level curve of some function $F(x,y)$.
+There are three requirements on the parameters for this to work
+correctly. First, in order to obtain the curve satisfying $F(x,y) = C$,
+the \marg{\meta{inequality}} must be either \verb${F(x,y) > C}$ or
+\verb${F(x,y) < C}$.%
+ \footnote{A non-strict inequality such as \mfc{>=} can be
+ used, but the result will not be significantly different.}
+Second, the level curve must surround the point given by the \meta{seed}
+paramter, and third, the inequality must be true at this seed point.
+
+The command works by searching rightward from \meta{seed} until it
+encounters the first point on the level curve. It then tries to find a
+nearby point on the level curve and joins it to the first one, and
+continues similarly until it finds it has returned near the starting
+point. The meaning of ``nearby point on the level curve'' is the
+intersection of the level curve with a circle of radius \meta{step}
+centered at the previously found point. If the region defined by the
+inequality extends beyond the bounds of the picture (as set by the
+\cs{mfpic} command), the region is truncated and the resulting curve
+will follow along the picture's border.
+
+Since the algorithm only approximates the level set, a tolerance (how
+close the points are to actually being \emph{on} the level curve) is
+chosen which gives two decimal places more accuracy than \meta{step}.
+The value of \meta{step} is interpreted in \emph{graph} units and
+so should be a pure number. The \oarg{\meta{spec}} is either \oarg{p},
+in which case the calculated points are joined with straight lines, or
+\oarg{s\meta{tension}} as in \cs{function}. The default is
+\oarg{s}: a smooth curve with the current default tension.
+
+In general, choosing a \meta{step} that corresponds to a few millimeters
+works reasonably well. For example, if the graph unit is 1cm (for
+example, \cs{mfpicunit=1cm} and no scaling is used), then
+\meta{step}${}= 0.5$ might be a reasonable first choice. If the level
+set is reasonably smooth and \oarg{s} is used, then the result will
+match the actual curve to within .005cm, which is approximately .14pt,
+which is less than half the thickness of the standard pen used to draw
+it.
+
+Be warned that there is a limit: there should not be more than 2000
+steps in the completed curve. In a figure which is 10-by-10 graph units,
+a level curve without too much oscillation would probably be less than
+80 units in length and a step size of .04 would probably produce under
+2000 steps. This should be accurate enough for most purposes. If you
+\emph{really} need more, the value of the \MF{} variable
+\verb$max_points$ must be changed. This can be done with
+\cs{setmfvariable} (see section~\ref{variables}).
+
+As a special case, if \meta{step} is 0, the maximum of width and height
+of the figure (as given by the arguments to the \env{mfpic} environment)
+is divided by 100. For example, in a 5-by-10 graph, giving a step size
+of $0$ will actually select \meta{step}${}= 10/100 = 0.1$.
+
+The algorithm used will produce incorrect results if there are two
+points on the curve closer that \meta{step} in straight-line distance,
+but much further apart when measured along the curve.
+
+The algorithm used will produce incorrect results if two points of the
+curve that are distant (as measured along the curve) are closer than
+\meta{step} in straight-line distance.
+
+\subsection{Plotting external data files}\label{external}
+
+\begin{cd}\pagelabel{datafile}
+\cs{datafile}\oarg{\meta{spec}}\marg{\meta{file}}\\
+\cs{smoothdata}\oarg{\meta{tension}}\\
+\cs{unsmoothdata}%
+\index{datafile@\cs{datafile}}%
+\index{smoothdata@\cs{smoothdata}}%
+\index{unsmoothdata@\cs{unsmoothdata}}
+\end{cd}
+
+The figure macro \cs{datafile} produces a curve connecting the points
+listed in the file \meta{file}. (The context makes it clear whether this
+meaning of \cs{datafile} or that of subsection~\ref{list} is meant.) The
+\meta{spec} may be \texttt{p} to produce a polygonal path, or \texttt{s}
+followed by a tension value (as in \cs{curve}) to produce a smooth path.
+If no \meta{spec} is given, the default is initially \texttt{p}, but
+\cs{smoothdata} may be used to change this. Thus, after the command
+\cs{smoothdata}\oarg{\meta{tension}} the default \oarg{\meta{spec}} is
+changed to \oarg{s\meta{tension}}. If the tension parameter is not
+supplied it defaults to \mfc{1.0} (or the value set by the
+\cs{settension} command if one has been used).
+
+The command \cs{unsmoothdata} restores the default \oarg{\meta{spec}} to
+\oarg{p}.
+
+By default, each non-blank line in the file is assumed to contain at
+least two numbers, separated by whitespace (blanks or tabs). The first
+two numbers on each line are assumed to represent the $x$- and
+$y$-coordinates of a point. Initial blank lines in the file are ignored,
+as are comments. The comment character in the data file is assumed to be
+\texttt{\%}, but it can be reset using \cs{mfpdatacomment} (below). Any
+blank line other than at the start of the file causes the curve to
+terminate. The \cs{datafile} command may be preceded by any of the
+prefix commands, so that, for example, a closed curve could be formed
+with \cs{lclosed}\cs{datafile}\marg{data.dat}.
+
+The \index{datafile@\cs{datafile}}\cs{datafile} command has another use,
+independent of the above description. We saw in subsection~\ref{list}
+that any \mfp{} command (other than one that prints text labels) that
+takes as its last argument a list of points (or numerical values)
+separated by commas, can have that list replaced with a reference to an
+external data file. For example, if a file \file{ptlist.dat} contains
+two or more numerical values per line separated by whitespace, then one
+can draw a dot at each of the points corresponding to the first pair of
+numbers on each line with the following.
+\begin{verbatim}
+\point\datafile{ptlist.dat}
+\end{verbatim}
+In fact there is no essential difference between `\cs{datafile}\oarg{p}'
+and `\cs{polyline}\cs{datafile}', and no difference between
+`\cs{datafile}\oarg{s}' and `\cs{curve}\cs{datafile}'.
+Here is the full list (omitting aliases) of \mfp{} macros that allow
+this usage of \cs{datafile}\index{datafile@\cs{datafile}}:
+
+\begin{itemize}
+\raggedright
+\item Numeric data:
+ \cs{barchart}, \cs{dashpattern}, \cs{numericarray},
+ \cs{piechart}, and all the axis marks commands.
+\item Point or vector data:
+ \cs{cbeziers}, \cs{closedcbeziers}, \cs{closedcomputedspline},
+ \cs{closedcspline}, \cs{closedmfbezier}, \cs{closedqbeziers},
+ \cs{closedqspline}, \cs{computedspline}, \cs{convexcurve},
+ \cs{convexcyclic}, \cs{cspline}, \cs{curve}, \cs{cyclic},
+ \cs{fcncurve}, \cs{fcnspline}, \cs{mfbezier},
+ \cs{periodicfcnspline}, \cs{plotsymbol}, \cs{point}, \cs{polygon},
+ \cs{polyline}, \cs{putmfpimage}, \cs{qbeziers}, \cs{qspline},
+ \cs{turtle}, and \cs{pairarray}.
+\end{itemize}
+In addition \cs{setarray} and \cs{globalsetarray} (with the numeric or
+pair data type) allow this usage.
+
+\begin{cd}\pagelabel{mfpdatacomment}
+\cs{mfpdatacomment}\cs{}\meta{char}%
+\index{mfpdatacomment@\cs{mfpdatacomment}}
+\end{cd}
+
+Changes \meta{char} to a comment character and changes the usual \TeX{}
+comment character \texttt{\%} to an ordinary character \emph{while reading a
+datafile for drawing}.
+
+\begin{cd}\pagelabel{using}
+\cs{using}\marg{\meta{in-pattern}}\marg{\meta{out-pattern}}%
+\index{using@\cs{using}}
+\end{cd}
+
+Used to change the assumptions about the format of the data file. For
+example, if there are four numbers on each line separated by commas, to
+plot the third against the second (in that order) you can say
+\cs{using}\marg{\#1,\#2,\#3,\#4}\marg{(\#3,\#2)}. This means the
+following: Everything on a line up to the first comma is assigned to
+parameter \texttt{\#1}, everything from there up to the second comma is
+assigned to parameter \texttt{\#2}, etc. Everything from the third comma
+to the end of line is assigned to \texttt{\#4}. When the line is
+processed by \TeX{} a \MF{} pair is produced representing a point on the
+curve. \CMF{} pair expressions can be used in the output portion of
+\cs{using}. For example \cs{using}\marg{\#1,\#2,\#3}\marg{(\#2,\#1)/10}
+or even \cs{using}\marg{\#1 \#2 \#3}\marg{polar(\#1,\#2)} if the data
+are polar coordinates. The default assumptions of the \cs{datafile}
+command (numbers separated by spaces, with the first two determining the
+$(x,y)$ pair) corresponds to the following setting.
+\begin{verbatim}
+\using{#1 #2 #3}{(#1,#2)}
+\end{verbatim}
+The \cs{using} command cannot normally be used in the replacement text
+of another command. Or rather, it can be so used, but then each
+\texttt{\#} has to be doubled. If a \cs{using} declaration occurs in an
+\env{mfpic} environment it is local to that environment. Otherwise it
+affects all subsequent ones.
+
+\begin{cd}\pagelabel{sequence}
+\cs{sequence}%
+\index{sequence@\cs{sequence}}
+\end{cd}
+
+As a special case, you can plot any number against its sequence
+position, with something like
+\cs{using}\marg{\#1 \#2}\marg{(\cs{sequence},\#1)}. Here, the macro
+\cs{sequence} will take on the values \texttt{1}, \texttt{2}, etc. as
+lines are read from the file.
+
+\begin{cd}\pagelabel{usingpairdefault}
+\cs{usingpairdefault}\\
+\cs{usingnumericdefault}%
+\index{usingpairdefault@\cs{usingpairdefault}}%
+\index{usingnumericdefault@\cs{usingnumericdefault}}
+\end{cd}
+
+The command \cs{usingpairdefault} restores the above described default
+for pair data. The command \cs{usingnumericdefault} is the equivalent of
+\cs{using}\marg{\#1 \#2}\marg{\#1}, a useful default for numeric data.
+
+Note that the default value of \cs{using} appears to reference three
+arguments. If there are only two numbers on a line separated by
+whitespace, this will still work because of \TeX{}'s argument matching
+rules. \TeX{}'s file reading mechanism normally converts the EOL to a
+space, but there are exceptions so \mfp{} internally adds a space at
+the end of each line read in to be on the safe side. Then the default
+definition of \cs{using} reads everything up to the first space as
+\texttt{\#1} (whitespace is normally compressed to a single space by
+\TeX{}'s reading mechanism), then everything to the second space (the one
+added at the end of the line, perhaps) is \texttt{\#2}, then everything
+to the EOL is \texttt{\#3}. This might assign an empty argument to
+\texttt{\#3}, but it is discarded anyway.
+
+If the numerical data contain percentages with explicit \texttt{\%} signs,
+then choose another comment character with \cs{mfpdatacomment}. This
+will change \texttt{\%} to an ordinary character \emph{in the data file}.
+However, in your \cs{using} command it would still be read as a comment.
+The following allows one to overcome this.
+
+\begin{cd}\pagelabel{makepercentother}
+\cs{makepercentother}\\
+\cs{makepercentcomment}%
+\index{makepercentother@\cs{makepercentother}}%
+\index{makepercentcomment@\cs{makepercentcomment}}
+\end{cd}
+
+Here is an example or their use:
+\begin{verbatim}
+\makepercentother
+\using{#1% #2 #3}{(#1/100,#2)}
+\makepercentcomment
+\end{verbatim}
+
+Here is an analysis of the meaning of this example: everything in a
+line, up to the first percent followed by a space is assigned to
+parameter \texttt{\#1}, everything from there to the next space is
+assigned to \texttt{\#2} and the rest of the line (which may be empty)
+is \texttt{\#3}. On the output side in the above example, the percentage
+is divided by 100 to convert it to a fraction, and plotted against the
+second parameter. Note: normal comments should not be used between
+\cs{makepercentother} and \cs{makepercentcomment}, for obvious reasons.
+Moreover, the above construction will fail inside the argument of
+another command.
+
+\begin{cd}\pagelabel{plotdata}
+\cs{plotdata}\oarg{\meta{spec}}\marg{\meta{file}}%
+\index{plotdata@\cs{plotdata}}
+\end{cd}
+
+This plots several curves from a single file. The \meta{spec} and the
+command \cs{smoothdata} have the same effect on each curve as in the
+\cs{datafile} command. The data for each curve is a succession of
+nonblank lines separated from the data for the next curve by a single
+blank line. A \emph{pair} of successive blank lines is treated as the
+end of the data. No prefix macros are permitted in front of
+\cs{plotdata}.
+
+Each successive curve in the data file is drawn differently. By default,
+the first is drawn as a solid line the next dashed, the third dotted,
+etc., through a total of six different line types. A \cs{gendashed}
+command is used with predefined dash patterns named \mfc{dashtype0}
+through \mfc{dashtype5}. This behavior can be changed with:
+
+\begin{cd}\pagelabel{coloredlines}
+\cs{coloredlines}\\
+\cs{pointedlines}\\
+\cs{datapointsonly}\\
+\cs{dashedlines}%
+\index{coloredlines@\cs{coloredlines}}%
+\index{pointedlines@\cs{pointedlines}}%
+\index{datapointsonly@\cs{datapointsonly}}%
+\index{dashedlines@\cs{dashedlines}}
+\end{cd}
+
+The command \cs{coloredlines} causes \cs{plotdata} to use the rendering
+command \cs{draw} with a color option that cycles through eight
+different colors starting with black (hey! black is a color too). The
+command \cs{pointedlines} causes \cs{plotdata} to use the rendering
+command \cs{plot}, cycling through nine symbols. The command
+\cs{datapointsonly} causes \cs{plotdata} to use the rendering command
+\cs{plotnodes}, cycling through the same nine symbols. The data points
+become the nodes of the paths created and so only the data points are
+plotted. The command \cs{dashedlines} restores the default. See
+appendix~\ref{styles} for the details on the actual dash patterns,
+colors and symbols used.
+
+The command \cs{coloredlines} will produce a warning under the
+\opt{metafont} option and substitute \cs{dashedlines}. Under the
+\opt{metapost} option, this is the sole exception to the general rule
+that all curves are drawn in \gbc{drawcolor} by default: the
+\cs{plotdata} command after \cs{coloredlines} has been issued.
+
+If, for some reason, you do not like the default starting line style
+(say you want to start with a color other than black), you can use one
+of the following commands.
+
+\begin{cd}\pagelabel{mfplinetype}
+\cs{mfplinetype}\marg{\meta{num}}, or\\
+\cs{mfplinestyle}\marg{\meta{num}}%
+\index{mfplinetype@\cs{mfplinetype}}%
+\index{mfplinestyle@\cs{mfplinestyle}}
+\end{cd}
+
+Here \meta{num} is a non-negative number, less than the number of
+different drawing types available. The four previous commands reset the
+number to 0, so if you use one of them, issue \cs{mfplinetype}
+\emph{after} it. The different line styles are numbered starting from
+$0$. If two or more \cs{plotdata} commands are used in the same
+\env{mfpic} environment, the numbering in each continues where the one
+before left off (unless you issue one of the commands above in between).
+\cs{mfplinestyle} means the same as \cs{mfplinetype}, and is included
+for compatibility. See appendix~\ref{styles} to find out what dash pattern,
+color or symbol corresponds to each number by default. The commands
+below can be used to change the default dashes, colors, or symbols.
+
+\begin{cd}\pagelabel{reconfigureplot}
+\cs{reconfigureplot}\marg{dashes}\marg{\meta{pat$_1$},\dots,\meta{pat$_n$}}\\
+\cs{reconfigureplot}\marg{colors}\marg{\meta{clr$_1$},\dots,\meta{clr$_n$}}\\
+\cs{reconfigureplot}\marg{symbols}\marg{\meta{symb$_1$},\dots,\meta{symb$_n$}}%
+\index{reconfigureplot@\cs{reconfigureplot}}
+\end{cd}
+
+The first argument of \cs{reconfigureplot} is the rendering method to be
+changed: \texttt{dashes}, \texttt{colors}, or \texttt{symbols}. The
+second argument is a list of dash patterns, colors, or symbols. The dash
+patterns should be names of patterns defined through the use of
+\cs{dashpattern}. The colors can be any color names already known to
+\MP{}, or defined through \cs{mfpdefinecolor}. The symbols can be any of
+those listed with the \cs{plotsymbol} command (see
+subsection~\ref{points}), or any known \MF{} path variable. The colors
+can also be \MP{} color constants or expressions, and the symbols can be
+expressions of type path. In recent \MP{} these `colors' can be
+\kw{numeric} (selecting gray), \kw{rgbcolor} or \kw{cmykcolor}. Within a
+\env{mfpic} environment, the changes made are local to that environment.
+Outside, they affect all subsequent environments.
+
+Using \cs{reconfigureplot}\marg{colors} under the \opt{metafont} option
+will have no effect, but may produce an error from \MF{} unless the
+colors used conform to the guidelines in subsection~\ref{MFcolor}.
+This also holds for \cs{defaultplot}\marg{colors} (below).
+
+\begin{cd}\pagelabel{defaultplot}
+\cs{defaultplot}\marg{dashes}\\
+\cs{defaultplot}\marg{colors}\\
+\cs{defaultplot}\marg{symbols}
+\index{defaultplot@\cs{defaultplot}}
+\end{cd}
+
+The command \cs{defaultplot} restores the built-in defaults for the
+indicated method of rendering in \cs{plotdata}.
+
+The commands \cs{using}, \cs{mfpdatacomment} and \cs{sequence} have the
+same meaning here (for \cs{plotdata}) as they do for \cs{datafile}
+(above). The sequence numbering for \cs{sequence} starts over with each
+new curve.
+
+\section{Labels and Captions.}\label{labels}
+
+\subsection{Setting text}\label{text}
+
+If option \opt{metafont} is in effect macros \cs{tlabel}, \cs{tlabels},
+\cs{axislabels} and \cs{tcaption} do not affect the \MF{} file
+(\file{\meta{file}.mf}) at all, but are added to the picture by \TeX{}. If
+\opt{metapost} is in effect but \opt{mplabels} is not, they do not
+affect the \MP{} file. In these cases, if these macros are the only
+changes or additions to your document, there is no need to repeat the
+processing with \MF{} or \MP{} nor the reprocessing with \TeX{} in order
+to complete your \TeX{} document.
+
+\begin{cd}\pagelabel{tlabel}
+\cs{tlabel}\oarg{\meta{just}}\parg{\meta{x},\meta{y}}\marg{\meta{labeltext}}\\
+\cs{tlabel}\oarg{\meta{just}}\marg{\meta{pair-list}}\marg{\meta{label text}}\\
+\cs{tlabels}\marg{\meta{params$_1$} \meta{params$_2$} $\ldots$}%
+\index{tlabel@\cs{tlabel}}%
+\index{tlabels@\cs{tlabels}}
+\end{cd}
+
+These place \TeX{} text or math on the graph. The special form
+\cs{tlabels} (note the plural) essentially just applies \cs{tlabel} to
+each set of parameters listed in its argument. That is, each
+\meta{params$_k$} is a valid set of parameters for a \cs{tlabel}
+command. These can be separated by spaces, newlines, or nothing at all.
+They should \emph{not} be separated by blank lines.
+
+The last required parameter is ordinary \TeX{} text. The pair
+\parg{\meta{x},\meta{y}} gives the coordinates of a point in the graph
+where the text will be placed. It may optionally be enclosed in braces,
+\verb${$ and \verb$}$. If braces are used, any number of coordinate
+pairs may be listed, separated by commas. This is what is meant by
+\meta{pair-list} in the above syntax. If \opt{mplabels} is in effect,
+the \meta{pair-list} can be any list of expressions recognized as a pair
+by \MP{}.
+
+The optional parameter \oarg{\meta{just}} specifies the
+\emph{justification}, the relative placement of the label with respect
+to the point with coordinates \parg{\meta{x},\meta{y}}. It is a
+two-character sequence in which the first character is one of \texttt{t}
+(top), \texttt{c} (center), \texttt{b} (bottom), or \texttt{B}
+(Baseline), to specify vertical placement, and the second character is
+one of \texttt{l} (left), \texttt{c} (center), or \texttt{r} (right), to
+specify horizontal placement. These letters specify what part of the
+\emph{text} is to be placed at the given point, so \texttt{r} puts the
+right end of the text there---which means the text will be left of the
+point. The default justification is \oarg{Bl}: the left end of the
+baseline of the text is placed at the coordinates.
+
+When \opt{mplabels} is in effect, the two characters may optionally be
+followed by a number, specifying an angle in degrees to rotate the text
+about the point \parg{\meta{x},\meta{y}}. If the angle is supplied
+without \opt{mplabels} it is ignored after a warning. If the angle is
+absent, there is no rotation. Note that the rotation takes place after
+the placement and uses the given point as the center of rotation. For
+example, \oarg{cr} will place the text left of the point, while
+\oarg{cr180} will rotate it around to the right side of the point (and
+upsidedown, of course).
+
+There should be no spaces before, between, or after the first two
+characters. However the number, if present, is only required to be a
+valid \MP{} numerical expression containing no bracket characters; as
+such, it may contain some spaces (e.g., around operations as in
+\texttt{45 + 30}).
+
+A multiline \cs{tlabel} may be specified by explicit line breaks, which
+are indicated by the \bbsl{} command or the \cs{cr} command. This is a
+very rudimentary feature. By default it left justifies the lines and
+causes \cs{tlabel} to redefine \bbsl. One can center a line by putting
+\cs{hfil} as the first thing in the line, and right justify by putting
+\cs{hfill} there (these are \TeX{} primitives). Redefining \bbsl{} can
+interfere with \LaTeX{}'s definition. For better control in \LaTeX{} use
+\cs{shortstack} inside the label (or a \env{tabular} environment or some
+other environment which always initializes \bbsl{} with its own
+definition).
+
+If the label goes beyond the bounds of the graph in any direction, the
+space reserved for the graph is expanded to make room for it. (Note:
+this behavior is very much different from that of the \LaTeX{}
+\env{picture} environment.)
+
+If the \opt{mplabels} option is in effect, \cs{tlabel} will write a
+\mfc{btex $\ldots$ etex} group to the output file, allowing \MP{} to
+arrange for typesetting the label. Normally, the label becomes part of
+the picture, rather than being laid on top of it, and can be covered up
+by any filling macros that follow, or clipped off by \cs{gclip}.
+However, under the \opt{overlaylabels} option (or after the command
+\cs{overlaylabels}), labels are saved and added to the picture at the
+very end. This may prevent some special effects, but it makes the
+behavior of labels much more consistent through all the 12 permissable
+settings of the options \opt{metapost}, \opt{mplabels}, \opt{clip}, and
+\opt{truebbox}.
+
+There is another command, \cs{startbacktext}, which also save the labels
+and adds them later, but \emph{under} the rest of the picture as
+background text. Thus, they will not be clipped, but may be covered up.
+Since erasing regions with \cs{gclear} actually covers up those regions
+with white, labels saved as background text may appear to have portions
+erased.
+
+\begin{cd}\pagelabel{everytlabel}
+\cs{everytlabel}\marg{\meta{\TeX{}-code}}%
+\index{everytlabel@\cs{everytlabel}}
+\end{cd}
+
+One problem with multiline \cs{tlabel}s is that each line of their
+contents constitutes a separate group. This makes it difficult to change
+the \cs{baselineskip} (for example) inside a label. The command
+\cs{everytlabel} saves it's contents in a token register and the code is
+issued in each \cs{tlabel}, as the last thing before the actual line(s)
+of text. Any switch you want to apply to every line can be supplied. For
+example
+\begin{verbatim}
+\everytlabel{\bf\baselineskip 10pt}
+\end{verbatim}
+will make every line of every \cs{tlabel}'s text come out bold with 10
+point baselines. The effect of \cs{everytlabel} is local to the
+\env{mfpic} environment, if it is issued inside one. Note that each line
+of a tlabel is wrapped in a box, but the commands of \cs{everytlabel}
+are outside all of them, so no actual text should be produced by the
+contents of \cs{everytlabel}.
+
+Using \cs{tlabel} without an optional argument is equivalent to
+specifying \oarg{Bl}. Use the following command to change this
+behavior.
+
+\begin{cd}\pagelabel{tlabeljustify}
+\cs{tlabeljustify}\marg{\meta{just}}%
+\index{tlabeljustify@\cs{tlabeljustify}}
+\end{cd}
+
+After this command the placement of all subsequent labels without
+optional argument will be as specified in this command. For example,
+\cs{tlabeljustify}\marg{cr45} would cause all subsequent \cs{tlabel}
+commands lacking an optional argument to be placed as if the argument
+\oarg{cr45} were used in each. If \opt{mplabels} is not in effect at the
+time of this command, the rotation part will be saved in case that
+option is turned on later, but a warning message will be issued. If
+\opt{mplabels} is not turned on later, that rotation will be ignored by
+\cs{tlabel}.
+
+\begin{cd}\pagelabel{tlabeloffset}
+\cs{tlabeloffset}\marg{\meta{hlen}}\marg{\meta{vlen}}\\
+\cs{tlpointsep}\marg{\meta{len}}\\
+\cs{tlpathsep}\marg{\meta{len}}\\
+\cs{tlabelsep}\marg{\meta{len}}%
+\index{tlabeloffset@\cs{tlabeloffset}}%
+\index{tlabelsep@\cs{tlabelsep}}%
+\index{tlpathsep@\cs{tlpathsep}}%
+\index{tlpointsep@\cs{tlpointsep}}
+\end{cd}
+
+The first command causes all subsequent \cs{tlabel} commands to shift
+the label right by \meta{hlen} and up by \meta{vlen} (negative lengths
+cause it to be shifted left and down, respectively).
+
+The \cs{tlpointsep} command causes labels to be shifted by the given
+amount in a direction that depends on the optional positioning
+parameter. For example, if the first letter is \texttt{t} the label is
+shifted down by the amount \meta{len} and if the second letter is
+\texttt{l} it is also shifted right. In all cases it is shifted
+\emph{away} from the point of placement (unless the dimension is
+negative). If \texttt{c} or \texttt{B} is the first parameter, no
+vertical shift takes place, and if \texttt{c} is the second, there is no
+horizontal shift. This is intended to be used in cases where something
+has been drawn at that particular point, in order to separate the text
+from the drawing.
+
+Prior to version 0.8, this separation also defined the separation
+between the label and those curves designed to frame the label
+such as \cs{tlabelrect} (subsection~\ref{surrounding}). Now the two
+separations are independent and \cs{tlpathsep} is used to set the
+separation between the label and such paths.
+
+For backward compatability, the command \cs{tlabelsep} is still
+available and sets both separations to the same value.
+
+\begin{cd}\pagelabel{axislabels}
+\cs{axislabels}\marg{\meta{axis}}\oarg{\meta{just}}%
+ \marg{\marg{\meta{text$_1$}}\meta{$n_1$},%
+ \marg{\meta{text$_2$}}\meta{$n_2$},$\ldots$}%
+\index{axislabels@\cs{axislabels}}
+\end{cd}
+
+This command places the given \TeX{} text (\meta{text$_k$}) at the given
+positions (\meta{$n_k$}) on the given axis, \meta{axis}, which must be a
+single letter and one of \texttt{l}, \texttt{b}, \texttt{r}, \texttt{t},
+\texttt{x}, or \texttt{y}. The text is placed as in \cs{tlabels}
+(including the taking into account of \cs{tlpointsep} and
+\cs{tlableoffset}), except that the default justification depends on the
+axis (the settings of \cs{tlabeljustify} are ignored). In the case of
+the border axes, the default is to place the label outside the axis and
+centered. So, for example, for the bottom axis it is \oarg{tc}. The
+defaults for the $x$- and $y$-axis are below and left, respectively. The
+optional \meta{just} can be used to change this. For example, to place
+the labels \emph{inside} the left border axis, use \oarg{cl}. If
+\opt{mplabels} is in effect, rotations can be included in the
+justification parameter. For example, to place the text strings
+`first', `second' and `third' just below the positions 1, 2 and 3
+on the $x$-axis, rotated so they read upwards at a 90 degree angle, one
+can use \cs{axislabels}\marg{x}\oarg{cr90}\marg{\marg{first}1,
+\marg{second}2, \marg{third}3}.
+
+\begin{cd}\pagelabel{plottext}
+\cs{plottext}\oarg{\meta{just}}\marg{\meta{text}}\marg{($x_0$,$y_0$),
+ ($x_1$,$y_1$), $\ldots$}%
+\index{plottext@\cs{plottext}}
+\end{cd}
+
+Similar in effect to \cs{point} and \cs{plotsymbol} (but without
+requiring \MF{}), \cs{plottext} places a copy of \meta{text} at each of
+the listed points. Since version 0.9, when \cs{tlabel} was enhanced to
+allow lists of points, it is implemented by an equivalent \cs{tlabel}
+command and is only kept for backward compatibility. It differs from
+\cs{tlabel} when the optional argument is absent: the default
+justification is \oarg{cc} regardless of the setting of
+\cs{tlabeljustify}.
+
+\begin{cd}\pagelabel{mfpverbtex}
+\cs{mfpverbtex}\marg{\meta{\TeX{}-cmds}}%
+\index{mfpverbtex@\cs{mfpverbtex}}
+\end{cd}
+
+This writes a \mfc{verbatimtex} block to the \file{.mp} file. It makes
+sense only if the \opt{mplabels} option is used and so only for \MP{}.
+The \meta{\TeX{}-cmds} in the argument are written to the \file{.mp}
+file, preceded by the \MP{} command \mfc{verbatimtex} and followed by
+\mfc{etex}. Line breaks within the \meta{\TeX{}-cmd} are preserved. The
+\cs{mfpverbtex} command must come before any \cs{tlabel} that is to be
+affected by it. Any settings common to all \env{mfpic} environments
+should be in a \cs{mfpverbtex} command preceding all such environments.
+
+It may be issued at any point after \mfp{} is loaded, and any number of
+times. If it is issued after \cs{opengraphsfile}, its contents are
+immediately written to the \file{.mp} file. If it is issued before
+\cs{opengraphsfile}, its contents are saved and written when the file is
+opened (successive uses being cummulative). In this case its contents
+will precede the boilerplate \TeX{} code that \mfp{} writes. If you wish
+to redefine some of that code, you need to use \cs{mfpverbtex} after
+\cs{opengraphsfile}.
+
+Because of the way \MP{} handles \mfc{verbatimtex} material, the effects
+cannot be constrained by any grouping unless one places \TeX{} grouping
+commands within \meta{\TeX{}-cmds}. However, \mfp{} itself places
+grouping commands into the output file at the beginning and end of each
+picture, so definitions written by a \cs{mfpverbtex} are local to any
+picture in which it occurs. Prior to version 0.8, \mfp{} did not write
+comments that occured within the \meta{\TeX{}-cmds}. Now they will be
+preserved, and can be used to place the `\verb$%&latex$' line that some
+\TeX{} distributions permit as a signal that latex should be run to
+produce the labels.
+
+This command attempts a near-verbatim writing of the \meta{\TeX{}-cmds}
+and, as with all verbatim-like commands, it should not be used in the
+argument of another command.
+
+\begin{cd}\pagelabel{backtext}
+\cs{startbacktext} \dots \cs{stopbacktext}%
+\index{startbacktext@\cs{startbacktext}}%
+\index{stopbacktext@\cs{stopbacktext}}
+\end{cd}
+
+When \TeX{} adds labels (\cs{nomplabels}) they have to be positioned
+either on top of a complete figure, or placed under a complete figure.
+The most reasonable choice (and happily the easiest to implement) is to
+put them on top. When \MP{} is placing labels (option \opt{mplabel}) the
+same can be forced with the option \opt{overlaylabels}, but otherwise
+they are placed as they occur, with later drawing commands perhaps
+putting their results on top of the labels or clipping parts of them off.
+
+Sometimes it is useful to place some label as a background (not on top),
+and yet not have it clipped by later commands. The effect of the command
+\cs{startbacktext} is that \cs{tlabel} commands are saved in a special
+place until the command \cs{stopbacktext}. Then, at \cs{endmfpic} the
+rest of the figure is simply place on top of them. Since labels in \MP{}
+files can only consist of characters from some font, if one wants to
+include a graphic in the background (for example, via
+\cs{includegraphics}), one needs to switch off \opt{mplabels}:
+\begin{verbatim}
+\nomplabels
+\startbacktext
+ \tlabel[cc](0,0){\includegraphics{mygraph}}
+\stopbacktext
+\usemplabels
+\end{verbatim}
+As with other labels, it is permitted to switch \opt{mplabels} off and
+on while creating background text. If there are both kinds of labels
+within the background text area the ones handled by \TeX{} will be
+further back than the ones handled by \MP{}. Within a given type,
+earlier ones are further back than later ones.
+
+\Mfp{} normally uses a naming scheme like \cs{cmd} \dots \cs{endcmd} and
+tries to arrange that \env{cmd} can be used as an environment. As
+currently written, the extra grouping added by \cs{begin}\marg{cmd} and
+\cs{end}\marg{cmd} would break the code that implements background text,
+so we have named these in a different way to avoid suggesting this
+possiblity. There should be at most one of these pairs in any
+\env{mfpic} environment. It can occur anywhere in the environment, but
+the two commands must not be inside any grouping.
+
+Under the \opt{metapost} option, the \cs{gclear} command doesn't really
+clear a space, but rather paints the space over with white. Any
+background text will not be visible through such `holes'. This is a
+limitation of \MP{}.
+
+\begin{cd}\pagelabel{tcaption}
+\cs{tcaption}\oarg{\meta{maxwd},\meta{linewd}}\marg{\meta{caption text}}%
+\index{tcaption@\cs{tcaption}}
+\end{cd}
+
+Places a \TeX{} caption at the bottom of the graph. (Not to be confused
+with \LaTeX{}'s similar \cs{caption} command.) The macro will
+automatically break lines which are too much wider than the graph---if
+the \cs{tcaption} line exceeds \meta{maxwd} times the width of the
+graph, then lines will be broken to form lines at most \meta{linewd}
+times the width of the graph. The default settings for \meta{maxwd} and
+\meta{linewd} are 1.2 and 1.0, respectively. \cs{tcaption} may typeset
+its argument twice (as might \LaTeX{}'s \cs{caption}), the first time as
+a single line to test its width, then again if that was too wide.
+Therefore, the user is advised \emph{not} to include any global
+assignments in the caption text.
+
+If the \cs{tcaption} and graph have different widths, the two are
+centered relative to each other. If the \cs{tcaption} takes multiple
+lines, then the default is to set lines both left- and right-justified
+(except for the last line) with no indentation on the first line. If the
+option \opt{raggedcaptions} is in effect, the lines are only
+left-justified and ragged on the right. Finally, if the option
+\opt{centeredcaptions} is in effect, each line of the caption will be
+centered (under \opt{raggedcaptions} they will be ragged on both sides).
+
+In a \cs{tcaption}, explicit line breaks may be specified by using the
+\bbsl{} command. The separation between the bottom of the picture and
+the caption can be changed by increasing or decreasing the skip
+\cs{mfpiccaptionskip}\index{mfpiccaptionskip@\cs{mfpiccaptionskip}}
+(a `rubber' length in Lamport's terminology).
+
+Many \mfp{} users find the \cs{tcaption} command too limiting (one
+cannot, for example, place the caption to the side of the figure). It is
+common to use some other method (such as \LaTeX{}'s \cs{caption} command
+in a \env{figure} environment). The dimensions \cs{mfpicheight} and
+\cs{mfpicwidth} (see section~\ref{parameters}) might be a convenience
+for plain \TeX{} users who want to roll their own caption macros.
+
+
+\subsection{Curves surrounding text}\label{surrounding}
+
+\begin{cd}\pagelabel{tlabelrect}
+\cs{tlabelrect}\oarg{\meta{rad}}\oarg{\meta{just}}%
+ \meta{pair}\marg{\meta{text}}\\
+\cs{tlabelrect*...}%
+\index{tlabelrect@\cs{tlabelrect}}
+\end{cd}
+
+This figure macro and the following two methods of surounding a bit of
+text with a curve share some common characteristics which will be
+described here. The commands all take an optional argument that can
+modify the shape of the curve. After that come arguments exactly as for
+the \cs{tlabel} command except that only a single point is permitted,
+not a list. (So \meta{pair} is either of the form
+\parg{\meta{x},\meta{y}} or the same enclosed in braces, or for
+\opt{mplabels} a pair expression in braces.) After processing the
+surrounding curve, a \cs{tlabel} is applied to those arguments unless a
+\texttt{*} is present. In order for the second optional argument (the
+optional justification argument for the \cs{tlabel} command) to be
+recognized as the second, the first optional argument must also be
+present. An empty first optional argument is permitted, causing the
+default value to be used. The default for the justification argument is
+\texttt{cc}, for compatibility with past \mfp{} versions, in which these
+commands all centered the figure around the point and no justification
+parameter existed. This default can be changed with the
+\cs{tlpathjustify} command below.
+
+The plain rectangle version produces a frame separated from the text on
+all sides by the amount defined with \cs{tlpathsep}. All other versions
+produce the smallest described curve that contains this rectangle.
+
+These commands may be preceded by prefix macros (see the sections
+\ref{modifier}~and \ref{rendering}, above). They all have a
+`star-form' which produces the curve but omits placing the text.
+All have the effect of rendering the path \emph{before} placing any
+text. For example, \cs{gclear}\cs{tlabelrect}\dots\ will clear the
+rectangle and then place the following text in the cleared space.
+
+The optional argument of \cs{tlabelrect}, \meta{rad}, is a dimension,
+defaulting to \dim{0pt}, that produces rounded corners made from
+quarter-circles of the given radius. If the corners are rounded, the
+sides are expanded slightly so the resulting shape still encompasses the
+rectangle mentioned above. There is one special case for the optional
+argument \meta{rad}: if the keyword `\texttt{roundends}' is used instead
+of a dimension, the radius will be chosen to make the nearest quarter
+circles just meet, so the narrow side of the rectangle is a half circle.
+
+\begin{cd}\pagelabel{tlabeloval}
+\cs{tlabeloval}\oarg{\meta{mult}}\oarg{\meta{just}}%
+ \meta{pair}\marg{\meta{text}}\\
+\cs{tlabeloval*...}%
+\index{tlabeloval@\cs{tlabeloval}}
+\end{cd}
+
+This figure macro is similar to \cs{tlabelrect}, except it produces an
+ellipse. The ellipse is calculated to have the same ratio of width to
+height as the rectangle mentioned above. The optional \meta{mult} is a
+multiplier that increases or decreases this ratio. Values of \meta{mult}
+larger than 1 increase the width and decrease the height.
+
+\begin{cd}\pagelabel{tlabelellipse}
+\cs{tlabelellipse}\oarg{\meta{ratio}}\oarg{\meta{just}}%
+ \meta{pair}\marg{\meta{text}}\\
+\cs{tlabelellipse*...}\\
+\cs{tlabelcircle}\oarg{\meta{just}}\meta{pair}\marg{\meta{text}}\\
+\cs{tlabelcircle*...}%
+\index{tlabelellipse@\cs{tlabelellipse}}%
+\index{tlabelcircle@\cs{tlabelcircle}}
+\end{cd}
+
+This figure macro produces the smallest ellipse centered at the point
+that encompasses the rectangle defined above, and that has a ratio of
+width to height equal to \meta{ratio}, then places the text. The default
+ratio is $1$, which produces a circle. We also provide the command
+\cs{tlabelcircle}, which takes only the \oarg{\meta{just}} optional
+argument. Internally, it just processes any \texttt{*} and calls
+\cs{tlabelellipse} with parameter 1.
+
+In the above \cs{tlabel...} curves, the optional parameter should be
+positive. If it is zero, all the curves silently revert to
+\cs{tlabelrect}. If it is negative, it is silently accepted. In the case
+of \cs{tlabelrect} this causes the quarter-circles at the corners to be
+indented rather than convex. In the other cases, there is no visible
+effect, but in all cases the sense of the curve is reversed.
+
+\begin{cd}\pagelabel{tlpathjustify}
+\cs{tlpathjustify}\marg{\meta{just}}%
+\index{tlpathjustify@\cs{tlpathjustify}}
+\end{cd}
+
+This can be used to change the default justification for \cs{tlabelrect}
+and friends. The \meta{just} parameter is exactly as in
+\cs{tlabeljustify} in subsection~\ref{text}.
+
+
+\section{Saving and Reusing an \mfp{} Picture.}\label{saving}
+
+These commands have been changed from versions prior to 0.3.14 in order
+to behave more like the \LaTeX{}'s \cs{savebox}, and also to allow the
+reuse of an allocated box. Past files that use \cs{savepic} will have to
+be edited to add \cs{newsavepic} commands that allocate the \TeX{}
+boxes.
+
+\begin{cd}\pagelabel{newsavepic}
+\cs{newsavepic}\marg{\meta{picname}}\\
+\cs{savepic}\marg{\meta{picname}}\\
+\cs{usepic}\marg{\meta{picname}}%
+\index{newsavepic@\cs{newsavepic}}%
+\index{savepic@\cs{savepic}}%
+\index{usepic@\cs{usepic}}
+\end{cd}
+
+\cs{newsavepic} allocates a box (like \LaTeX{}'s \cs{newsavebox}) in which
+to save a picture. As in \cs{newsavebox}, \meta{picname} is a control
+sequence. Example: \cs{newsavepic}\marg{\cs{foo}}. In a \LaTeX{}
+document, \cs{newsavepic} is actually defined to be \cs{newsavebox}.
+
+\cs{savepic} saves the \emph{next} \cs{mfpic} picture in the named box,
+which should have been previously allocated with \cs{newsavepic}. (This
+command should not be used \emph{inside} an \env{mfpic} environment.)
+The next picture will not be placed, but saved in the box for later use.
+This is primarily intended as a convenience. One \emph{could} use
+\begin{ex}
+ \cs{savebox}\marg{\meta{picname}}\marg{\meta{entire
+ \env{mfpic} environment}},
+\end{ex}
+but \cs{savepic} avoids having to place the \env{mfpic} environment in
+braces, and avoids one extra level of \TeX{} grouping. It also avoids
+reading the entire \env{mfpic} environment as a parameter, which would
+nullify \mfp{}'s efforts to preserve line breaks in parameters
+written to the \MF{} output file. If you repeat \cs{savepic} with the
+same \meta{picname}, the old contents are replaced with the next
+picture.
+
+\cs{usepic} copies the picture that had been saved in the named box.
+This may be repeated as often as liked to create multiple copies of one
+picture. The \cs{usepic} command is essentially a clone of the \LaTeX{}
+\cs{usebox} command. Since the contents of the saved picture are only
+defined during the \TeX{} run, \cs{usebox} cannot be used in the
+\TeX-commands argument of the \cs{tlabel} command while \opt{mplabels}
+is in effect.
+
+
+\section{Picture Frames.}\label{frames}
+
+When \TeX{} is run but before \MF{} or \MP{} has been run on the output
+file, \mfp{} detects that the \file{.tfm} file is missing or that
+the first \MP{} figure file \file{\meta{file}.1} is missing. In these
+cases, the \env{mfpic} environment draws only a rectangular frame with
+dimensions equal to the nominal size of the picture, containing the
+figure number (and any text placed by \cs{tlabel} and its relatives
+without \opt{mplabels} in effect). The command(s) used internally to do
+this are made available to the user.
+
+\begin{cd}\pagelabel{mfpframe}
+\cs{mfpframe}\oarg{\meta{fsep}}%
+ \meta{ material-to-be-framed }%
+\cs{endmfpframe}\\
+\cs{mfpframed}\oarg{\meta{fsep}}\marg{\meta{material-to-be-framed}}%
+\index{mfpframed@\cs{mfpframed}}%
+\index{endmfpframe@\cs{endmfpframe}}%
+\index{mfpframe@\cs{mfpframe}}
+\end{cd}
+
+These commands surround their contents with a rectangular frame
+consisting of lines with thickness \cs{mfpframethickness} separated from
+the contents by the \meta{fsep} if specified, otherwise by the value of
+the dimension \cs{mfpframesep}. The default value of the \TeX{}
+dimensions \cs{mfpframesep} and \cs{mfpframethickness} are \dim{2pt} and
+\dim{0.4pt}, respectively. The \cs{mfpframe} $\ldots$ \cs{endmfpframe}
+version is preferred around \env{mfpic} environments or verbatim
+material since it avoids reading the enclosed material before
+appropriate \cs{catcode} changes go into effect. In \LaTeX{}, one can
+also use environment syntax: \cs{begin}\marg{mfpframe} $\ldots$
+\cs{end}\marg{mfpframe}.
+
+An alternative way to frame \env{mfpic} pictures is to save them with
+\cs{savepic} (see previous section) and issue a corresponding
+\cs{usepic} command inside any framing environment or command of the user's
+choice or devising.
+
+
+\section{Affine Transforms.}\label{transforms}
+
+Coordinate transformations that keep parallel lines in parallel are
+called \emph{affine transforms}. These include translation, rotation,
+reflection, scaling and skewing (slanting). For the \MF{} coordinate
+system only---that is, for paths, but not for \cs{tlabel}'s (let alone
+\cs{tcaption}'s)---\mfp{} provides the ability to apply \MF{}
+affine transforms.
+
+
+\subsection{Transforming the \MF{} coordinate system}\label{affine}
+
+\begin{cd}\pagelabel{coords}
+\cs{coords} \dots \cs{endcoords}%
+\index{coords@\cs{coords}}%
+\index{endcoords@\cs{endcoords}}
+\end{cd}
+
+All affine transforms are restricted to the innermost enclosing
+\cs{coords}$\ldots$\cs{endcoords} pair. If there is \emph{no} such
+enclosure, then the transforms will apply to the rest of the \env{mfpic}
+environment. In \LaTeX{}, one can use the environment named
+\env{coords}.
+
+\medskip
+\noindent Transforms provided by \mfp{}:
+
+\nobreak
+\begin{cd}\pagelabel{applyT}%
+\begin{tabular}[b]{@{}ll@{}}
+ \cs{rotate}\marg{\meta{$\theta$}}%
+ \index{rotate@\cs{rotate}}%
+ & Rotate around origin by \meta{$\theta$} degrees.\\
+ \cs{rotatearound}\marg{\meta{$p$}}\marg{\meta{$\theta$}}%
+ \index{rotatearound@\cs{rotatearound}}%
+ & Rotate around point \meta{$p$} by \meta{$\theta$} degrees.\\
+ \cs{turn}\oarg{\meta{p}}\marg{\meta{$\theta$}}%
+ \index{turn@\cs{turn}}%
+ & Rotate around point \meta{p} (origin is default) by
+ \meta{$\theta$}.\\
+ \cs{reflectabout}\marg{\meta{$p_1$}}\marg{\meta{$p_1$}}%
+ \index{reflectabout@\cs{reflectabout}}%
+ & Reflect in the line through points \meta{$p_1$} and \meta{$p_2$}.\\
+ \cs{mirror}\marg{\meta{$p_1$}}\marg{\meta{$p_2$}}%
+ \index{mirror@\cs{mirror}}%
+ & Same as \cs{reflectabout}.\\
+ \cs{shift}\marg{\meta{v}}%
+ \index{shift@\cs{shift}}%
+ & Shift origin by the vector \meta{v}.\\
+ \cs{scale}\marg{\meta{s}}%
+ \index{scale@\cs{scale}}%
+ & Scale uniformly by a factor of \meta{s}.\\
+ \cs{xscale}\marg{\meta{s}}%
+ \index{xscale@\cs{xscale}}%
+ & Scale only the $x$ coordinates by a factor of \meta{s}.\\
+ \cs{yscale}\marg{\meta{s}}%
+ \index{yscale@\cs{yscale}}%
+ & Scale only the $y$ coordinates by a factor of \meta{s}.\\
+ \cs{zscale}\marg{\meta{pair}}%
+ \index{zscale@\cs{zscale}}%
+ & Scale by the magnitude of vector \meta{v}, and rotate by its
+ angle.\\
+ \cs{xslant}\marg{\meta{s}}%
+ \index{xslant@\cs{xslant}}%
+ & Skew in $x$ direction by the multiple \meta{s} of $y$.\\
+ \cs{yslant}\marg{\meta{s}}%
+ \index{yslant@\cs{yslant}}%
+ & Skew in $y$ direction by the multiple \meta{s} of $x$.\\
+ \cs{zslant}\marg{\meta{pair}}%
+ \index{zslant@\cs{zslant}}%
+ & See \mfc{zslanted} in \file{grafbase.dtx}.\\
+ \cs{boost}\marg{\meta{$\chi$}}%
+ \index{boost@\cs{boost}}%
+ & Special relativity boost by $\chi$, see \mfc{boost} in
+ \file{grafbase.dtx}.\\
+ \cs{xyswap}%
+ \index{xyswap@\cs{xyswap}}%
+ & Exchange the values of $x$ and $y$.\\
+ \cs{applyT}\marg{\meta{transformer}}%
+ \index{applyT@\cs{applyT}}%
+ & Apply the \meta{transformer}.
+\end{tabular}
+\end{cd}
+
+\cs{applyT} is for \MF{} hackers. Any code is permitted that satisfies
+\MF{}'s syntax for a \meta{transformer} (see D.~E.~Knuth, ``The
+\MF{}book'', page~73), although no effort is made to correctly write
+\TeX{} special characters nor to preserve linebreaks in the code.
+
+When any of these commands is issued, the effect is to transform all
+subsequent figures (within the enclosing \env{coords} or \env{mfpic}
+environment). In particular, attention may need to be paid to whether
+these transformations move (part of) the figure outside the space
+allotted by the \cs{mfpic} command parameters.
+
+A not-so-obvious point is that if several of these transformations are
+applied in succession, then the most recent is applied first, so that
+figures are transformed as if the transformations were applied in the
+reverse order of their occurrence. This is similar to the application of
+prefix macros (as well as application of transformations in mathematics:
+$S T z$ usually means to apply $S$ to the result of $T z$).
+
+Finally, some of these may not produce what the unwary user might expect
+if the \env{mfpic} environment was started with unequal scaling. For
+example, in such a case a rotated rectangle will not have right angles
+unless the rotation is by a multiple of 90 degrees. The reason for this:
+the scaling given by the \cs{mfpic} command is applied last and
+slanted lines subjected to unequal horizontal and verical scaling will
+change have their angles changed.
+
+
+\subsection{Transforming paths}\label{transformation}
+
+In the previous section we discussed transformations of the \MF{}
+coordinate system. Those macros affect the \emph{drawing} of paths and
+other figures, but do not change the actual paths. We will explain the
+distinction after introducing two macros for storing and reusing
+figures.
+
+\begin{cd}\pagelabel{store}
+\cs{store}\marg{\meta{path variable}}\marg{\meta{path}}\\
+\cs{store}\marg{\meta{path variable}}\meta{path}%
+\index{store@\cs{store}}
+\end{cd}
+
+This stores the following \meta{path} in the specified \MF{} \meta{path
+variable}. Any valid \MF{} symbolic token will do, in particular, any
+sequence of letters and underscores. You should be careful to make the
+name distinctive to avoid overwriting the definition of some internal
+variable. The stored path may later be used as a figure macro
+using \cs{mfobj} (below). The \meta{path} may be any of the figure
+macros (such as \cs{curve}\marg{(0,0),(1,0),(1,1)}) or the result of
+modifying it. For example:
+\begin{verbatim}
+\store{pth}\lclosed\reverse\curve{(0,0),(1,0),(1,1)}
+\end{verbatim}
+
+In fact, \cs{store} is a prefix macro that does nothing to the following
+curve except store it. It acts as a rendering macro with a null
+rendering, so the curve is not made visible unless other rendering
+macros appear before or after it. It allows the following path to be an
+argument, that is, enclosed in braces. This is solely to support files
+written for past \mfp{} versions in which \cs{store} was \emph{not}
+defined as a prefix macro.
+
+One use of \cs{store} is to create a shorthand for a path that is
+otherwise long and tedious to type. Another is to create `symbols' or
+`arrowheads' for use in \cs{plotsymbol}, \cs{arrowhead} and related
+commands.
+
+\begin{cd}\pagelabel{mfobj}
+\cs{mfobj}\marg{\meta{path expression}}\\
+\cs{mpobj}\marg{\meta{path expression}}%
+\index{mfobj@\cs{mfobj}}%
+\index{mpobj@\cs{mpobj}}
+\end{cd}
+
+This figure macro produces the path represented by \meta{path
+expression}, which is either a path variable in which a path was
+previously stored, or a valid \MF{} expression combining such variables
+and constant paths. This allows the use of path variables or
+expressions as figure macros, permitting all prefix operations, etc..
+Here are some examples of the use of \cs{store} and \cs{mfobj}.
+
+\nobreak
+\begin{verbatim}
+\store{my_f}{\cyclic{...}} % Store a closed curve.
+\dotted\mfobj{my_f} % Now draw it dotted,
+\hatch\mfobj{my_f} % and hatch its interior
+% Create two symbols
+% one outline:
+\store{MyTriang}{\polyline{(-.5,-.5),(.5,-.5),(0,.5),(-.5,-.5)}
+% one solid:
+\store{MySolidTriang}{\polygon{(-.5,-.5),(.5,-.5),(0,.5)}
+% Use them as symbols:
+\plotsymbols{MyTriang}{(0,0),(2,2)}
+\arrowmid{MySolidTriang}\polyline{(1,1),(0,2)}
+\end{verbatim}
+
+\emph{Note}: If a stored path has the same starting point as ending
+point, but is \emph{not} closed then it will behave like \texttt{Circle}
+(for example) when used in \cs{plotsymbol}: only its outline is drawn,
+and its interior is erased when \opt{clearsymbols} is in effect. If a
+closed path is stored, it behaves like \texttt{SolidCircle}: it is not
+drawn, but rather filled. If a path is stored that satisfies neither, it
+behaves like \texttt{Asterisk}, being simply drawn in all circumstances.
+
+The two forms \cs{mfobj} and \cs{mpobj} are absolutely equivalent; they
+differ only in spelling.
+
+It should be noted that every \mfp{} figure is implicitly stored in the
+object \gbc{curpath}. So you can use \cs{mfobj}\marg{curpath} and get
+the path defined by the most recently completed figure macro (possibly
+modified by prefixes).
+
+Getting back to coordinate transforms, if one changes the coordinate
+system and then stores and draws a curve, say by
+\begin{verbatim}
+\coords
+ \rotate{45 deg}
+ \store{xx}{\rect{(0,0),(1,1)}}
+ \dashed\mfobj{xx}
+\endcoords
+\end{verbatim}
+one will get a transformed picture, but the object \cs{mfobj}\marg{xx}
+will contain the simple, unrotated rectangular path and drawing it later
+(outside the \env{coords} environment) will prove that. This is because
+the \texttt{coords} environment works at the drawing level, not at the
+definition level.
+
+In oversimplified terms, \cs{dashed} invokes the transformation, but not
+\cs{store}. More precisely, the rendering macros have the side effect of
+adding ink to the page (or subtracting it). To know where to place this
+ink, a calculation is performed that translates graph coordinates to
+actual positions. The above transforms work by modify the parameters
+used in that calculation. On the other hand, \cs{store} merely stores
+the output of the immediately following prefix or figure macro. See the
+beginning of section~\ref{modifier} for a discussion of input, output
+and side effects of \mfp{} prefix and figure macros.
+
+The following transformation prefixes provide a means of actually
+creating and storing a transformed path. In the terms just discussed,
+their input is a path, their output is the transformed path, and they
+have no side effects.
+
+\begin{cd}\pagelabel{shiftpath}
+\cs{rotatepath}\marg{\meta{$p$},\meta{$\theta$}}$\ldots$\\
+\cs{shiftpath}\marg{\meta{v}}$\ldots$\\
+\cs{scalepath}\marg{\meta{$p$},\meta{s}}$\ldots$\\
+\cs{xscalepath}\marg{\meta{x},\meta{s}}$\ldots$\\
+\cs{yscalepath}\marg{\meta{y},\meta{s}}$\ldots$\\
+\cs{slantpath}\marg{\meta{y},\meta{s}}$\ldots$\\
+\cs{xslantpath}\marg{\meta{y},\meta{s}}$\ldots$\\
+\cs{yslantpath}\marg{\meta{x},\meta{s}}$\ldots$\\
+\cs{reflectpath}\marg{\meta{$p_1$},\meta{$p_2$}}$\ldots$\\
+\cs{xyswappath}$\ldots$\\
+\cs{transformpath}\marg{\meta{transformer}}$\ldots$%
+\index{rotatepath@\cs{rotatepath}}%
+\index{shiftpath@\cs{shiftpath}}%
+\index{scalepath@\cs{scalepath}}%
+\index{xscalepath@\cs{xscalepath}}%
+\index{yscalepath@\cs{yscalepath}}%
+\index{slantpath@\cs{slantpath}}%
+\index{xslantpath@\cs{xslantpath}}%
+\index{yslantpath@\cs{yslantpath}}%
+\index{reflectpath@\cs{reflectpath}}%
+\index{xyswappath@\cs{xyswappath}}%
+\index{transformpath@\cs{transformpath}}
+\end{cd}
+
+These are modifying macros that all return the result of applying an
+affine transformation to the following path. They differ in the
+transformation applied and the data needed in the mandatory argument. I
+have found them extremely useful, and better than \env{coords}
+environments when I need to draw a figure, together with several
+slightly different versions of it. If \cs{store} is used just before one
+of these prefixes, it stores the transformed path rather than the
+original.
+
+\cs{rotatepath} rotates the following path by \meta{$\theta$} degrees
+about point \meta{$p$}.
+
+\cs{shiftpath} shifts the following path by the vector \meta{v}.
+
+\cs{scalepath} scales (magnifies or shrinks) the following path by the
+factor \meta{s}, in such a way that the point \meta{$p$} is kept fixed.
+That is
+\begin{verbatim}
+\scalepath{(0,0),2}\rect{(0,0),(1,1)}
+\end{verbatim}
+is essentially the same as \cs{rect}\marg{(0,0),(2,2)}, while
+\begin{verbatim}
+\scalepath{(1,1),2}\rect{(0,0),(1,1)}
+\end{verbatim}
+is the same as \cs{rect}\marg{(-1,-1),(1,1)}. In both cases the
+rectangle is doubled in size. In the first case the lower left corner
+stays the same, while in the second case the the upper right corner
+stays the same.
+
+\cs{xscalepath} is similar to \cs{scalepath}, but only the $x$-direction
+is scaled, and all points with first coordinate equal to \meta{x} remain
+fixed. \cs{yscalepath} is similar, except the $y$-direction is affected.
+
+\cs{slantpath} applies a slant transformation to the following path,
+keeping points with second coordinate equal to \meta{y} fixed. That is,
+a point $p$ on the path is moved right by an amount proportional to the
+height of $p$ above the line $y={}$\meta{y}, with $s$ being the
+proportionality factor. Points below that line move left. Vertical lines
+in the path will acquire a slope of $1/s$, while horizontal lines stay
+horizontal.
+
+\cs{xslantpath} is an alias for \cs{slantpath}
+
+\cs{yslantpath} is similar to \cs{xslantpath}, but exchanges the roles
+of $x$ and $y$ coordinates.
+
+\cs{reflectpath} returns the mirror image of the following path, where
+the line determined by the points \meta{$p_1$} and \meta{$p_2$} is the
+mirror.
+
+\cs{xyswappath} returns the path with the roles of $x$ and $y$
+exchanged. This is similar in some respects to
+\cs{reflectpath}\marg{(0,0),(1,1)}, and produces the same result if the
+$x$ and $y$ scales of the picture are the same. However,
+\cs{reflectpath} compensates for such different scales (so the path
+shape remains the same), while \cs{xyswappath} does not. However, after
+a swap, verticals become horizontal and horizontals become vertical.
+(It is impossible, when the scales are different, for an affine transform
+to both preserve shape and exchange horizontal and vertical lines.)
+
+This compensation for different scales is also done for \cs{rotatepath},
+so the resulting path always has the same shape after the rotation as
+before. None of the other path transformation prefixes compensate for
+different scales, and none of the coordinate system transformations of
+the previous subsection do it.
+
+For \MF{} or \MP{} power users, \cs{transformpath} can take any
+`transformer' and transform the following path with it. Here, a
+\emph{transformer} is the same as in the previous section. Examples are
+\mfc{scaled}, \mfc{shifted(1,1)}, and \mfc{rotatedabout(0,1)}. Note that
+using this last transformer with \cs{transformpath} is almost like
+\cs{rotatepath}\marg{(0,1)}, but it does not compensate for different
+scales.
+
+All these prefixes change only the path that follows, not any rendering
+of it that follows. For example:
+\begin{verbatim}
+\gfill\rotatepath{(0,0),90}\dashed\rect{(0,0),(1,1)}
+\end{verbatim}
+will not produce a rotated dashed rectangle. Rather the original
+rectangle will be dashed, and the rotated rectangle will be filled.
+
+One complication is the handling of the default rendering. One expects
+\verb$\rect{(0,0),(1,1)}$ to draw a rectangle, and
+\verb$\rotatepath{(0,0),45}\rect{(0,0),(1,1)}$ to draw a rotated
+rectangle (but not the original). That is, a transformation + figure is
+treated as if it were a single figure. But what would one expect in the
+following?
+\begin{verbatim}
+\rotatepath{(0,0),45}\dashed\rect{(0,0),(1,1)}
+\end{verbatim}
+What one will get is the original dashed and the rotated one with the
+default rendering (typically drawn with solid lines). That is, these
+prefixes cannot see the renderings that occur later in the sequence.
+They add the default rendering as if those didn't exist. If something
+other than this is desired, one can either rearrange the prefixes or add
+a \phantomsection\label{norenderexample}\cs{norender} in appropriate
+places. For example, to add a shifted arrowhead without drawing the
+shifted path:
+\begin{verbatim}
+\arrow\norender\shiftpath{(0,1)}\arrow\draw\lines{(0,0),(8,8)}
+\end{verbatim}
+
+\section{Parameters.}\label{parameters}
+
+There are many parameters in \mfp{} which the user can modify to
+obtain different effects, such as different arrowhead size or shape.
+Most of these parameters have been described already in the context of
+macros they modify, but they are all described together here.
+
+Many of the parameters are stored by \TeX{} as dimensions, and so are
+available even if there is no \MF{} file open; changes to them are not
+subject to the usual \TeX{} rules of scope however: they are local
+only to \env{mfpic} environments if set inside one, otherwise
+they are global. This is for consistency: other parameters are stored by
+\MF{} (so the macros to change them will have no effect unless a \MF{}
+file is open) and the changes are subject to \MF{}'s rules of scope---to
+the \mfp{} user, this means that changes inside the \cs{mfpic} $\ldots$
+\cs{endmfpic} environment are local to that environment, but other
+\TeX{} groupings have no effect on scope. Some commands (notably those
+that set the axismargins and \cs{tlabel} parameters) change both \TeX{}
+parameters and \MF{} parameters, and it is important to keep them
+consistent.
+
+There are a few parameters that do obey \TeX{} grouping, but only inside
+\env{mfpic} environments. These are noted where the parameter is
+described.
+
+All parameters are initialized when \prog{mfpic} is loaded. We give the
+initial value or state in each of these descriptions.
+
+\begin{cd}\pagelabel{mfpicunit}
+\cs{mfpicunit}%
+\index{mfpicunit@\cs{mfpicunit}}
+\end{cd}
+
+This dimension stores the basic unit length for \mfp{} pictures. The $x$
+and $y$ scales in the \cs{mfpic} macro are multiples of this unit. The
+initial value is \dim{1pt}. It is global outside an \env{mfpic}
+environment. Changes made to it inside an \env{mfpic} environment have
+no effect and are lost at the end of the environment.
+
+\begin{cd}\pagelabel{pointsize}
+\cs{pointsize}%
+\index{pointsize@\cs{pointsize}}
+\end{cd}
+
+This dimension stores the diameter of the circle drawn by the
+\cs{point} macro and the diameter of the symbols drawn by \cs{plot},
+\cs{plotsymbol} and \cs{plotnodes}. The initial value is \dim{2pt}.
+
+\begin{cd}\pagelabel{pointfilltrue}
+\cs{pointfilltrue}, \cs{pointfillfalse}%
+\index{pointfilltrue@\cs{pointfilltrue}}%
+\index{pointfillfalse@\cs{pointfillfalse}}
+\end{cd}
+
+This \TeX{} boolean switch determines whether the circle drawn by
+\cs{point} will be filled or open (outline drawn, inside erased).
+The initial state is \texttt{true}: filled. This value is local to any \TeX{}
+group inside an \env{mfpic} environment. Outside such it is global.
+
+\begin{cd}\pagelabel{drawpen}
+\cs{pen}\marg{\meta{size}}\\
+\cs{drawpen}\marg{\meta{size}}\\
+\cs{penwd}\marg{\meta{size}}%
+\index{pen@\cs{pen}}%
+\index{drawpen@\cs{drawpen}}%
+\index{penwd@\cs{penwd}}
+\end{cd}
+
+These commands establishes the width of the normal drawing pen (that is,
+the thickness of lines, whether solid or dashed). The initial value is
+\dim{0.5bp}. This width is stored by \MF{}. This has no effect on the
+size of dots for \cs{dotted}, \cs{shade}, \cs{grid}, etc. It also has no
+effect on the lines drawn for hatching. There exist three aliases for
+this command, the first two to maintain backward compatibility, the last
+one for consistency with other dimension changing commands. Publishers
+generally recommended authors to use at least a width of one-half point
+for drawings submitted for publication.
+
+\begin{cd}\pagelabel{shadewd}
+\cs{shadewd}\marg{\meta{diam}}%
+\index{shadewd@\cs{shadewd}}
+\end{cd}
+
+This command sets the diameter of the dots used in the shading macro.
+The drawing and hatching pens are unaffected by this. The initial value
+is \dim{0.5bp}, and the value is stored by \MF{}.
+
+\begin{cd}\pagelabel{hatchwd}
+\cs{hatchwd}\marg{\meta{size}}%
+\index{hatchwd@\cs{hatchwd}}
+\end{cd}
+
+This sets the line thickness used in the hatching macros. The drawing
+pen and shading dots are unaffected by this. The initial value is
+\dim{0.5bp}, and the value is stored by \MF{}.
+
+\begin{cd}\pagelabel{polkadotwd}
+\cs{polkadotwd}\marg{\meta{diam}}%
+\index{polkadotwd@\cs{polkadotwd}}
+\end{cd}
+
+This sets the diameter of the dots used in the \cs{polkadot} macro. The
+initial value is \dim{5bp}, and the value is stored by \MF{}.
+
+\begin{cd}\pagelabel{headlen}
+\cs{headlen}%
+\index{headlen@\cs{headlen}}
+\end{cd}
+
+This dimension stores the length of the arrowhead drawn by the
+\cs{arrow} macro. The initial value is \dim{3pt}.
+
+\begin{cd}\pagelabel{axisheadlen}
+\cs{axisheadlen}%
+\index{axisheadlen@\cs{axisheadlen}}
+\end{cd}
+
+This dimension stores the length of the arrowhead drawn by the
+\cs{axes}, \cs{xaxis} and \cs{yaxis} macros, and by the macros \cs{axis}
+and \cs{doaxes} when applied to the parameters \texttt{x} and
+\texttt{y}. The initial value is \dim{5pt}.
+
+\begin{cd}\pagelabel{sideheadlen}
+\cs{sideheadlen}%
+\index{sideheadlen@\cs{sideheadlen}}
+\end{cd}
+
+This dimension stores the length of the arrowhead drawn by the \cs{axis}
+and \cs{doaxes} macros when applied to \texttt{l}, \texttt{b},
+\texttt{r} or \texttt{t}. The initial value is \dim{0pt} (that is, the
+default is not to put arrowheads on border axes).
+
+\begin{cd}\pagelabel{headshape}
+\cs{headshape}\marg{\meta{ratio}}\marg{\meta{tension}}\marg{\meta{filled}}%
+\index{headshape@\cs{headshape}}
+\end{cd}
+
+This establishes the shape of the \gbc{Arrowhead} drawn by the
+\cs{arrow...} and \cs{axes} macros. It also establishes the shape of
+\gbc{Leftharpoon} and \gbc{Rightharpoon}. The value of \meta{ratio} is
+the ratio of the width of the arrowhead to its length; \meta{tension} is
+the tension of the B\'ezier curves; and \meta{filled} is a \MF{} boolean
+value indicating whether the arrowheads are to be filled (if \mfc{true})
+or open. The initial values are $1$, $1$, and \mfc{false}, respectively.
+Setting \meta{tension} to the literal keyword `\mfc{infinity}' will make
+the sides of the arrowheads straight lines. The harpoon heads are
+arranged to be exactly half of the full arrowhead. The \meta{ratio},
+\meta{tension} and \meta{filled} values are stored by \MF{}.
+
+After \cs{headshape} is used, the symbols \gbc{Arrowhead},
+\gbc{Leftharpoon}, and \gbc{Rightharpoon} take on the new shape if used
+in one of the \cs{plot...} commands.
+
+\begin{cd}\pagelabel{dashlen}
+\cs{dashlen}, \cs{dashspace}%
+\index{dashlen@\cs{dashlen}}
+\end{cd}
+
+These dimensions store, respectively, the length of dashes and the
+length of spaces between dashes, for lines drawn by the \cs{dashed}
+macro. The \cs{dashed} macro may adjust the dashes and the spaces
+between by as much as $1/n$ of their value, where $n$ is the number of
+spaces appearing in the curve, in order not to have partial dashes at
+the ends. The initial values are both \dim{4pt}. The dashes will
+actually be longer (and the spaces shorter) by the thickness of the pen
+used when they are drawn.
+
+\begin{cd}\pagelabel{dashlineset}
+\cs{dashlineset}, \cs{dotlineset}%
+\index{dashlineset@\cs{dashlineset}}%
+\index{dotlineset@\cs{dotlineset}}
+\end{cd}
+
+These macros provide shorthands for certain settings of the \cs{dashlen}
+and \cs{dashspace} dimensions. The macro \cs{dashlineset} sets both
+values to \dim{4pt}, while \cs{dotlineset} sets \cs{dashlen} to
+\dim{1pt} and \cs{dashspace} to \dim{2pt}. They are kept mainly for
+backward compatibility.
+
+\begin{cd}\pagelabel{hashlen}
+\cs{hashlen}%
+\index{hashlen@\cs{hashlen}}
+\end{cd}
+
+This dimension stores the length of the axis hash marks drawn by the
+\cs{xmarks} and \cs{ymarks} macros. The initial value is \dim{4pt}.
+
+\begin{cd}\pagelabel{shadespace}
+\cs{shadespace}%
+\index{shadespace@\cs{shadespace}}
+\end{cd}
+
+This dimension establishes the spacing between dots drawn by the
+\cs{shade} macro. The initial value is \dim{1pt}.
+
+\begin{cd}\pagelabel{darkershade}
+\cs{darkershade}, \cs{lightershade}%
+\index{darkershade@\cs{darkershade}}%
+\index{lightershade@\cs{lightershade}}
+\end{cd}
+
+These macros both multiply the \cs{shadespace} dimension by constant
+factors, $5/6=.833333$ and $6/5=1.2$ respectively, to provide convenient
+standard settings for several levels of shading. Under \MF{} it is
+possible that using one of these macros can have no visible effect. See
+the discussion of the \cs{shade} macro in subsection~\ref{filling}.
+
+\begin{cd}\pagelabel{polkadotspace}
+\cs{polkadotspace}%
+\index{polkadotspace@\cs{polkadotspace}}
+\end{cd}
+
+This dimension establishes the spacing between the centers of the dots
+used for the macro \cs{polkadot}. The initial value is \dim{10pt}.
+
+\begin{cd}\pagelabel{dotsize}
+\cs{dotsize}, \cs{dotspace}%
+\index{dotsize@\cs{dotsize}}\index{dotspace@\cs{dotspace}}%
+\end{cd}
+
+These \TeX{} dimensions establishes the size and spacing between the
+centers of the dots used in the \cs{dotted} macro. The initial values
+are \dim{0.5pt} and \dim{3pt}.
+
+\begin{cd}\pagelabel{griddotsize}
+\cs{griddotsize}%
+\index{griddotsize@\cs{griddotsize}}%
+\end{cd}
+
+This dimension is used as the default for the sizes of dots in the
+\cs{grid} and \cs{plrgridpoints} commands. The initial value is
+\dim{0.5pt}
+
+\begin{cd}\pagelabel{symbolspace}
+\cs{symbolspace}%
+\index{symbolspace@\cs{symbolspace}}
+\end{cd}
+
+Similar to \cs{dotspace}, this \TeX{} dimension establishes the space
+between the centers of symbols placed by the macro
+\cs{plot}\marg{\meta{symbol}}$\ldots\,$. Its initial value is \dim{5pt}.
+
+\begin{cd}\pagelabel{hatchspace}
+\cs{hatchspace}%
+\index{hatchspace@\cs{hatchspace}}
+\end{cd}
+
+This dimension establishes the spacing between lines drawn by the
+\cs{hatch} macro. The initial value is \dim{3pt}.
+
+\begin{cd}
+\cs{tlpointsep}\marg{\meta{separation}}\\
+\cs{tlpathsep}\marg{\meta{separation}}\\
+\cs{tlabelsep}\marg{\meta{separation}}%
+\index{tlpointsep@\cs{tlpointsep}}%
+\index{tlpathsep@\cs{tlpathsep}}%
+\index{tlabelsep@\cs{tlabelsep}}
+\end{cd}
+
+The first macro establishes the separation between a label and its
+nominal position. It affects text written with any of the commands
+\cs{tlabel}, \cs{tlabels}, \cs{axislabels} or \cs{plottext}. The second
+sets the separation between the text and the curve defined by the
+commands \cs{tlabelrect}, \cs{tlabeloval} or \cs{tlabelellipse}. The
+third sets both of these separations to the same value. It is for
+backward compatibility: in the past there was only one dimension used
+for both purposes. The initial value of each is \dim{0pt}. The values
+are stored by both \TeX{} and \MF{}.
+
+\begin{cd}
+\cs{tlabeloffset}\marg{\meta{hlen}}\marg{\meta{vlen}}%
+\index{tlabeloffset@\cs{tlabeloffset}}
+\end{cd}
+
+This macro establishes a uniform offset that applies to all labels. It
+affects text written with any of the commands \cs{tlabel}, \cs{tlabels},
+\cs{axislabels} or \cs{plottext}. The initial state is to have both
+horizontal and vertical offsets of \dim{0pt}. The values are stored by
+both \TeX{} and \MF{}.
+
+\begin{cd}\pagelabel{mfpdataperline}
+\cs{mfpdataperline}%
+\index{mfpdataperline@\cs{mfpdataperline}}
+\end{cd}
+
+When \mfp{} is reading from data files and writing to the output file,
+this macro stores the maximum number of data points that will be written
+on a single line in the output file. Its initial definition is
+\cs{def}\cs{mfpdataperline}\marg{5}. Any such definition (or
+redefinition) obeys \emph{all} \TeX{} groupings.
+
+\begin{cd}\pagelabel{mfpicheight}
+\cs{mfpicheight}, \cs{mfpicwidth}%
+\index{mfpicheight@\cs{mfpicheight}}%
+\index{mfpicwidth@\cs{mfpicwidth}}
+\end{cd}
+
+These dimensions store the height and width of the figure created by the
+most recently completed \env{mfpic} environment. This might perhaps be
+of interest to hackers or to aid in precise positioning of the graphics.
+They are meant to be read-only: the \cs{endmfpic} command globally sets
+them equal to the height and width of the picture, but \mfp{} does not
+otherwise make any use of them. As they are not to be changed, grouping
+is irrelevent, but when \mfp{} sets them, it does so globally. These are
+set even if the picture is saved with \cs{savepic}. If they are needed
+for the corresponding \cs{usepic}, and that occurs after another
+\env{mfpic} environment, they should be copied to other length commands
+right after the \env{mfpic} environment that set them.
+
+\begin{cd}\pagelabel{mfpiccaptionskip}
+\cs{mfpiccaptionskip}%
+\index{mfpiccaptionskip@\cs{mfpiccaptionskip}}
+\end{cd}
+
+This skip register (`rubber length' in \LaTeX) stores the space between
+a picture and the caption produced with \cs{tcaption}. It is local to
+all \TeX{} groups. If changed inside an \env{mfpic} environment it will
+affect only the \cs{tcaption} command in that picture. It's initial
+setting is \cs{medskipamount}, producing the same space as a
+\cs{medskip}.
+
+
+\section{For Advanced Users.}\label{advanced}
+
+\subsection{Splines}\label{splines}
+
+\begin{cd}\pagelabel{qspline}
+\cs{qspline}\marg{\meta{list}}\\
+\cs{closedqspline}\marg{\meta{list}}\\
+\cs{cspline}\marg{\meta{list}}\\
+\cs{closedcspline}\marg{\meta{list}}%
+\index{qspline@\cs{qspline}}%
+\index{closedqspline@\cs{closedqspline}}%
+\index{cspline@\cs{cspline}}%
+\index{closedcspline@\cs{closedcspline}}%
+\end{cd}
+
+These figure macros use alternative ways of defining curves. In each case,
+\meta{list} is a comma separated list of ordered pairs. These represent
+not the points the curve passes through, but the \emph{control points}.
+The first two produce quadratic B-splines and the last two produce cubic
+B-splines. If you don't know what B-splines are, or don't know what
+control points are, it is recommended you not use these commands.
+
+For \cs{qspline}, the curve will pass through the midpoints of the line
+segments joining the points in the list, tangent to that line segment.
+
+For the \cs{cspline}, the list also defines line segments. Divide these
+into equal thirds at two points on each segment. Connect these
+\emph{division points only} to obtain line segments. Each \emph{odd
+numbered} segment is the middle third of one of the original line
+segments. The \cs{cspline} curve passes through the midpoint of each
+\emph{even numbered} line segment, tangent to it.
+
+\begin{cd}\pagelabel{computedspline}
+\cs{computedspline}\marg{\meta{list}}\\
+\cs{closedcomputedspline}\marg{\meta{list}}%
+\index{computedspline@\cs{computedspline}}%
+\index{closedcomputedspline@\cs{closedcomputedspline}}%
+\end{cd}
+
+These figure macros both produce cubic splines. For these you \emph{do}
+provide the list of points the curves are to pass through. They become
+the nodes, and then the control points are computed from them. The nodes
+do not uniquely determine the control points so extra equations are
+required. For the first version, the extra equations give the path zero
+curvature at the endpoints (a \emph{relaxed} spline). For the closed
+version, the extra equations are those that close the curve smoothly.
+The portions of the spline that connect one node to the next are
+parametrized cubic B/'eziers, they are computed so that the first and
+second derivatives (with respect to the parameter) of adjacent curves
+match at the common node.
+
+\begin{cd}\pagelabel{fcnspline}
+\cs{fcnspline}\marg{\meta{list}}\\
+\cs{periodicfcnspline}\marg{\meta{list}}%
+\index{fcnspline@\cs{fcnspline}}%
+\index{periodicfcnspline@\cs{periodicfcnspline}}%
+\end{cd}
+
+These figure macros use cubic spline equations (as in
+\cs{computedspline} above) to produce a smooth graph of a function based
+on a list of points with increasing $x$-values. See \cs{fcncurve} in
+section~\ref{curves} for another way to do this. As in the computed
+splines, above, the spline equations at the nodes do not provide
+sufficient information to compute all control points. In the basic
+version, \cs{fcnspline}, extra equations produce a graph with zero
+curvature at the endpoints (a relaxed spline), while the periodic
+version uses equations that make the first and second derivatives at the
+last point match those at the first point.
+
+\begin{cd}\pagelabel{cbclosed}
+\cs{cbclosed}$\ldots$\\
+\cs{qbclosed}$\ldots$%
+\index{cbclosed@\cs{cbclosed}}%
+\index{qbclosed@\cs{qbclosed}}
+\end{cd}
+
+These are modifying macros that close the following path. The first
+closes with a cubic B-spline, the second with a quadratic B-spline. They
+will close any given curve, but the command \cs{cbclosed} is meant to
+close a cubic B-spline (see above). That is, \cs{cbclosed}\cs{cspline}
+should produce the same result as \cs{closedcspline} with the same
+argument. The corresponding statements are true of \cs{qbclosed}: it is
+meant to close a quadratic B-spline and \cs{qbclosed}\cs{qspline} should
+produce the same result as \cs{closedqspline} with the same argument.
+
+\subsection{B\'eziers}
+
+The power user, having noticed that \cs{curve} and \cs{cyclic} insert
+some direction modifiers into the path created, may have decided that
+there is no \mfp{} command to create a simple \MF{} default style path,
+for example \mfc{(1,1)..(0,1)..(0,0)..cycle}. If so, he or she has forgotten
+about \cs{mfobj}: the command
+\begin{verbatim}
+\mfobj{(1,1)..(0,1)..(0,0)..cycle}
+\end{verbatim}
+will produce, in the \file{.mf} file, exactly this path, but surround it
+with the \TeX{} wrapping needed to make \mfp{}'s prefix macro system work.
+However, the syntax of more complicated paths can be extremely lengthy,
+so we offer this interface:
+
+\begin{cd}\pagelabel{mfbezier}
+ \cs{mfbezier}\oarg{\meta{tens}}\marg{\meta{list}}\\
+ \cs{closedmfbezier}\oarg{\meta{tens}}\marg{\meta{list}}%
+\index{mfbezier@\cs{mfbezier}}%
+\index{closedmfbezier@\cs{closedmfbezier}}
+\end{cd}
+
+These figure macros uses the \MF{} path join operator `\mfc{..tension
+\meta{tens}..}' to connect the points in the list. If the tension option
+\oarg{\meta{tens}} is omitted, the value set by \cs{settension}
+(initially 1) is used. One can get a cyclic path by prepending
+\cs{bclosed} (with matching tension option), but it will not produce the
+same result as \cs{closedmfbezier}. These are cubic B\'ezier's (but you
+know that if you are a power user). Quadratic B\'eziers (as in
+\LaTeX{}'s picture environment) can be obtained with the following:
+
+\begin{cd}\pagelabel{qbeziers}
+ \cs{qbeziers}\marg{\meta{list}}\\
+ \cs{closedqbeziers}\marg{\meta{list}}%
+\index{qbeziers@\cs{qbeziers}}%
+\index{closedqbeziers@\cs{closedqbeziers}}
+\end{cd}
+
+These figure macros produce \emph{quadratic} B\'ezier curves, the
+equivalent of a sequence of \LaTeX{} \cs{qbezier} commands. Note the
+plural forms, to distinguish the first from the \LaTeX{} command, and to
+indicate that they can draw a \emph{series} of quadratic B\'eziers.
+
+In the \meta{list}, the first, third, fifth, etc., are the points to
+connect, while the second, fourth, etc., are the control points. The
+open version requires an ending point, and so needs an odd number of
+points in the list. The closed version assumes the first point is the
+ending, and so requires an even number in the list. If the number of
+ponts is wrong, no error is produced: the last point is simply repeated
+to get the required number.
+
+The curve will not automatically be smooth; that depends on the choice
+of the control points.
+
+\begin{cd}\pagelabel{cbeziers}
+ \cs{cbeziers}\marg{\meta{list}}\\
+ \cs{closedcbeziers}\marg{\meta{list}}%
+\index{cbeziers@\cs{cbeziers}}%
+\index{closedcbeziers@\cs{closedcbeziers}}
+\end{cd}
+
+These figure macros produce a series of \emph{cubic} B\'ezier curves. In
+the \meta{list}, the first, fourth, seventh, etc., are the points to
+connect, while the second and third, fifth and sixth, etc., are pairs of
+control points. The closed version uses the starting point as the ending
+point, and so needs a number of points divisible by $3$ ($n=3k$). The
+open version requires an explicitly given ending node (so $n=3k+1$).
+If the number of ponts is wrong, no error is produced: the last point
+or last two points are simply repeated to get the required number.
+
+The curves will not automatically be smooth; that depends on the choice
+of the control points. Cubic B\'eziers are how curves are represented in
+PostScript files, and how a number of vector drawing programs represent
+curves.
+
+\subsection{Raw \MF{} code}\label{mfcode}
+
+\begin{cd}\pagelabel{mfsrc}
+\cs{mfsrc}\marg{\meta{metafont code}}\\
+\cs{mfcmd}\marg{\meta{metafont code}}\\
+\cs{mflist}\marg{\meta{metafont code}}%
+\index{mfsrc@\cs{mfsrc}}%
+\index{mfcmd@\cs{mfcmd}}%
+\index{mflist@\cs{mflist}}%
+\end{cd}
+
+These all write the \meta{metafont code} directly to the \MF{} file,
+using a \TeX{} \cs{write} command. Line breaks within \meta{metafont
+code} are preserved.%
+ \footnote{Under most circumstances, but not if the command (plus its
+ argument) is part of the argument of another macro.} %
+Almost all the \mfp{} drawing macros invoke one of these. Because of the
+way \TeX{} reads and processes macro arguments, not all drawing macros
+preserve line breaks (nor do they all need to). However, the ones that
+operate on long lists of pair or numeric data (for example, \cs{point},
+\cs{curve}, etc.), do preserve line breaks in that data. The difference
+in these is minor: \cs{mfsrc} writes its argument without change,
+\cs{mfcmd} appends a semicolon (`\mfc{;}') to the code, while
+\cs{mflist} surrounds its argument with parentheses and then appends a
+semicolon.
+
+Using these can have some rather bizarre consequences, though, so it is
+not recommended to the unwary. It is, however, currently the only way to
+make use of \MF{}'s equation solving ability. Here's an oversimplified
+example:
+\begin{verbatim}
+\mfpic[20]{-0.5}{1.5}{0}{1.5}
+\mfsrc{z1=(0,0);
+ z2-z3=(1,2);
+ z2+2z3=(1,-1);} % z2=(1,1), z3=(0,-1)
+\arc[t]{z1,z2,z3}
+\endmfpic
+\end{verbatim}
+
+Check out the sample \file{forfun.tex} for a more extensive example. It
+should produce the word `\textsf{mfpic}' in blue, outlined in green in a
+box with yellow background.
+
+\subsection{Creating \MF{} variables}\label{variables}
+
+\begin{cd}\pagelabel{setmfvariable}
+\cs{setmfvariable}\marg{\meta{type}}\marg{\meta{name}}\marg{\meta{value}}\\
+\cs{setmpvariable}\marg{\meta{type}}\marg{\meta{name}}\marg{\meta{value}}\\
+\cs{globalsetmfvariable}\marg{\meta{type}}\marg{\meta{name}}\marg{\meta{value}}\\
+\cs{globalsetmpvariable}\marg{\meta{type}}\marg{\meta{name}}\marg{\meta{value}}\\
+\cs{setmfnumeric}\marg{\meta{name}}\marg{\meta{value}}\\
+\cs{setmfpair} \marg{\meta{name}}\marg{\meta{value}}\\
+\cs{setmfboolean}\marg{\meta{name}}\marg{\meta{value}}\\
+\cs{setmfcolor} \marg{\meta{name}}\marg{\meta{value}}%
+\index{setmfvariable@\cs{setmfvariable}}%
+\index{setmpvariable@\cs{setmpvariable}}%
+\index{globalsetmfvariable@\cs{globalsetmfvariable}}%
+\index{globalsetmpvariable@\cs{globalsetmpvariable}}%
+\index{setmfnumeric@\cs{setmfnumeric}}%
+\index{setmfpair@\cs{setmfpair}}%
+\index{setmfboolean@\cs{setmfboolean}}%
+\index{setmfcolor@\cs{setmfcolor}}%
+\end{cd}
+
+These formerly internal \mfp{} macros can be use to define symbolic
+names for any \MF{} or \MP{} variable type. The last four are
+abbreviations for the first used with an appropriate value for
+\meta{type}. For example,
+\cs{setmfvariable}\marg{pair}\marg{X}\marg{(2,0)} can be abbreviated
+\cs{setmfpair}\marg{X}\marg{(2,0)}. Note that these overwrite any
+variable with the specified \meta{name}. For certain internal names,
+\MF{} will issue an error, but usually the variable is silently
+redefined.
+
+The commands \cs{setmpvariable} and \cs{globalsetmpvariable} (note the
+\texttt{mp} instead of \texttt{mf}) are just alternative spellings . You
+can use either spelling with either the \opt{metafont} or \opt{metapost}
+option.
+
+The \meta{value} must be a constant of the appropriate type or a \MF{}
+expression returning the appropriate type. It can also be (or include)
+other variables previously defined. The \cs{setmfcolor} command has been
+enhanced so that in recent \MP{} the \meta{value} can be any of the
+three types of colors \MP{} allows: \kw{numeric} (for grayscale color),
+\kw{rgbcolor} or \kw{cmykcolor}. The data type of \meta{value} will be
+examined, and the variable \meta{name} will be declared to be a variable
+of the appropriate type. The same is true of
+\cs{setmfvariable}\marg{color}.
+
+As an example of their use, since dimensions are numeric data types in
+\MF{}, the command
+\begin{verbatim}
+\setmfnumeric{my_spc}{5pt}
+\setmfnumeric{my_dia}{.8pt}
+\end{verbatim}
+would set the \MF{} variables \verb$my_spc$ and \verb$my_dia$ to the
+values \texttt{5pt} and \texttt{.8pt}, respectively. After that, these
+variables can be used in any \emph{drawing} command where a dimension is
+required:
+\begin{verbatim}
+\plot[my_dia,my_spc]{Triangle}\rect{(0,0),(1,1)}
+\end{verbatim}
+will plot the rectangle with small triangles of diameter \dim{.8pt},
+spaced \dim{5pt} apart.
+
+The knowledgeable user may realize that \mfc{path} and \gbc{picture} are
+\MF{} data types, and may want use them in \cs{setmfvariable}. It is
+also true that at some level, \mfp{} figure macros produce a path and
+\cs{mfpimage} produces a picture. However, \mfp{} commands cannot be
+used in the value portion of \cs{setmfvariable}. The \TeX{} code that
+most \mfp{} commands produce would be meaningless to \MF{}. You can
+store the path produced by figure macros with \cs{store}, and store
+pictures in variables with \cs{mfpimage} or even \cs{tile}.
+
+With the obvious exception of the \cs{globalsetmfvariable} command, these
+commands define the variable locally. That is, the variable will revert
+to any previous definition (or become undefined) at the end of the
+\env{mfpic} environment it is defined in. It is in fact local to any
+\MF{} group. In \mfp{}, only \cs{connect} {\dots} \cs{endconnect},
+\cs{mfpimage} {\dots} \cs{endmfpimage}, and \cs{mfpic} {\dots}
+\cs{endmfpic} create \MF{} groups in the graph file.
+
+A warning about variable names. \CMF{} and \MP{} allow multi-part
+variable names like `\mfc{arrowhead length}' or `\mfc{X.r}' The part
+after the first space or `.' is called a \mfc{suffix}. In \MF{},
+variable settings are global unless explicitly made local. The code of
+the \cs{set...} commands does make the variable setting local. However,
+\MF{} syntax forbids this localization when a variable name has a
+suffix. Moreover, if you localize a variable, \MF{} will localize all
+variables with that name plus any suffix. Even more, localizing a
+variable renders all variables with the same name plus suffix locally
+undefined. The command \cs{globalsetmfvariable} simply omits the
+localization part, so suffixes are permitted, but it cannot `globalize'
+something that has previously been localized within the same group.
+
+For example, suppose you use the example code in subsection~\ref{arrows}
+and define a custom arrowhead path \gbc{myAH} and the corresponding
+clearing path \gbc{myAH.clear}. Suppose now you try to make this head
+the default for the \cs{arrow} command by doing the following.
+\begin{verbatim}
+\setmfvariable{path}{Arrowhead}{myAH}
+\end{verbatim}
+Then this assignments is local and makes \gbc{Arrowhead.clear} undefined
+(locally). You cannot use \cs{setmfvariable} to define
+\gbc{Arrowhead.clear}; that will produce an error from \MF{}. You need
+to do
+\begin{verbatim}
+\setmfvariable{path}{Arrowhead}{myAH}
+\globalsetmfvariable{path}{Arrowhead.clear}{myAH.clear}
+\end{verbatim}
+and \emph{both} assignments will be local. To make both assignments
+global, use the global version in both.
+
+
+\begin{cd}\pagelabel{patharr}
+\cs{patharr}\marg{\meta{name}}$\ldots$\cs{endpatharr}%
+\index{patharr@\cs{patharr}}%
+\index{endpatharr@\cs{endpatharr}}
+\end{cd}
+
+This pair of macros, acting as an environment, accumulate all enclosing
+paths, in order, into a path array named \meta{name}. A path array is a
+collection of paths with a common base name indexed by integers from 1
+to the number of paths. Any path in the array can be accessed by means
+of \cs{mfobj}. For example, after
+\begin{verbatim}
+\patharr{pa}
+ \rect{(0,0),(1,1)} \circle{(.5,.5), .5}
+\endpatharr
+\end{verbatim}
+then \cs{mfobj}\marg{pa[1]} refers to the rectangle and
+\cs{mfobj}\marg{pa[2]} refers to the circle. In case explicit numbers
+are used, \MF{} allows \gbc{pa1} as an abbreviation for \gbc{pa[1]}.
+However, if a numeric variable or some expression is used (e.g.,
+\gbc{pa[n+1]}) the square brackets are required.
+
+This command can only be used in an \env{mfpic} environment. For this
+reason, the definitions it makes are global.
+
+\emph{Note}: In \LaTeX{}, this pair of macros can be used in the form of a
+\LaTeX{}-style environment called \env{patharr}---as in
+\cs{begin}\marg{patharr}$\ldots$\cs{end}\marg{patharr}.
+
+\begin{cd}\pagelabel{setarray}
+\cs{setarray}\marg{\meta{type}}\marg{\meta{var}}\marg{\meta{list}}\\
+\cs{globalsetarray}\marg{\meta{type}}\marg{\meta{var}}\marg{\meta{list}}\\
+\cs{pairarray}\marg{\meta{var}}\marg{\meta{list-of-points}}\\
+\cs{numericarray}\marg{\meta{var}}\marg{\meta{list-of-numbers}}\\
+\cs{colorarray}\marg{\meta{var}}\marg{\meta{list-of-colors}}\\
+\cs{rgbcolorarray}\marg{\meta{var}}\marg{\meta{list-of-rgbcolors}}\\
+\cs{cmykcolorarray}\marg{\meta{var}}\marg{\meta{list-of-cmykcolors}}%
+\index{setarray@\cs{setarray}}%
+\index{globalsetarray@\cs{globalsetarray}}%
+\index{pairarray@\cs{pairarray}}%
+\index{numericarray@\cs{numericarray}}%
+\index{colorarray@\cs{colorarray}}%
+\index{rgbcolorarray@\cs{rgbcolorarray}}%
+\index{cmykcolorarray@\cs{cmykcolorarray}}
+\end{cd}
+
+These enable the simultaneous definition of variables.
+For example, after
+\begin{verbatim}
+\pairarray{X}{(0,1),(1,1),(0,0),(1,0)}
+\end{verbatim}
+the variables \mfc{X1}, \mfc{X2}, \mfc{X3}, and \mfc{X4} are equal to
+the given points in that order. And then
+\begin{verbatim}
+\polyline{X1,X2,X3,X4}
+\end{verbatim}
+will draw the lines connecting these four points. The index may
+optionally be put in square brackets and may be separated from the name
+by any number of spaces. That is, \verb$\polyline{X[1],X[2]}$
+and \verb$\polyline{X 1,X 2}$ are the same as \verb$\polyline{X1,X2}$
+to \MF{}. If a numeric \emph{expression} is used instead of an explicit
+number, square brackets \emph{must} surround it: \gbc{X[1+1]},
+\gbc{X[2]}, \gbc{X2} and \gbc{X 2} are all the same. For all these array
+commands, the variable \gbc{X} by itself (not followed by any digit or
+brackets) becomes a numeric variable equal to the number of elements in
+the array. Except for \cs{globalsetarray}, the arrays are defined
+locally if these commands occur in an \env{mfpic} environment, global
+otherwise.
+
+Array variables may be used only where the values are processed only by
+\MF{} or \MP{}, they are unknown to \TeX{}. In particular, they cannot be
+used in commands that position text unless \opt{mplabels} is in effect.
+Variables may be used in the \meta{list} parameters of commands,
+but they must have been previously defined or otherwise known to \MF{}.
+
+Since arrays must all be variables of the same type, one cannot mix rgb
+and cmyk colors. The \verb$\colorarray$ command requires rgb colors (for
+compatibility with early \MP{}).
+
+Several commands in \mfp{} define arrays of objects that can be used in
+other commands. The main ones are \cs{regpolygon}, \cs{piechart} and
+\cs{barchart}. These arrays are always global (either because their
+use is restricted to an \env{mfpic} environment or for backward
+compatibility with the time when they were so restricted).
+
+Using \cs{regpolygon}{\meta{num}}\marg{X}\marg{...}\marg{...} causes a
+pair array named \gbc{X} to be defined having \meta{num} elements (and
+the additional pair \gbc{X0} for the center). This is in addition to
+creating the actual figure. The variable \gbc{X} alone becomes a numeric
+equated to \meta{num}.
+
+Using \cs{piechart} (or \cs{mfppiechart}) causes the following arrays to
+become defined (or redefined):
+\begin{itemize}
+ \item \gbc{piewedge}, a path array describing the wedges of the chart.
+ To access \gbc{piewedge[1]}, for example, one could use
+ \cs{mfobj}\marg{piewedge[1]}. This is almost exactly the
+ same as the \mfp{} command \cs{piewdge}\marg{1} without
+ optional arguments.
+ \item \gbc{pieangle}, a numeric array, gives the starting angles of
+ the wedges.
+ \item \gbc{piedirection}, a pair array, gives the unit vectors
+ pointing from the center of the piechart through middles of the
+ wedges. For example, if \cs{pieangle1} is 0 and \gbc{pieangle2}
+ is 90 degrees, then \gbc{piedirection1} is $(\cos 45,\sin 45)$,
+ the unit vector whose angle is $45$ degrees.
+\end{itemize}
+
+Using \cs{barchart} (or \cs{mfpbarchart} or any of its aliases) causes
+the following arrays to become defined (or redefined). The exact meaning
+depends on whether bars are horizontal or vertical. The following
+describes horizontal bars; exchange the roles of $x$ and $y$ if they are
+vertical (also change `right' to `top', etc.):
+\begin{itemize}
+ \item \gbc{barstart}, a numeric array, gives the position on the
+ $y$-axis of the leading edge of the bars.
+ \item \gbc{barbegin}, numeric, gives the $x$-coordinate of the
+ leftmost end of the bars.
+ \item \gbc{barend}, numeric, gives the $x$-coordinate of the rightmost
+ end of the bars.
+ \item \gbc{chartbar}, a path array, gives the actual bars. For
+ example, \gbc{chartbar2} is the rectangle with opposite corners
+ \gbc{(barbegin2,barstart2)} and \gbc{(barend2,barstart2+barwd)},
+ where the numeric variable \gbc{barwd} is the thickness of the
+ bar (which is a height for horizontal bars).
+ \item \gbc{barlength}, the same as \gbc{barend}. This is for backward
+ compatibility; the name was chosen at a time when all the bars
+ had one side on an axis.
+\end{itemize}
+
+\subsection{Miscelaneous pair expressions}\label{pairexpressions}
+
+A useful \MF{} operator that produces points is the intermediation
+operator, whose syntax is
+\begin{cd}
+\texttt{(\meta{num})[\meta{$p_1$},\meta{$p_2$}]}
+\end{cd}
+That is, a number or numeric expression in parentheses followed by
+literal brackets (this is \emph{not} an optional argument) containing two points
+or pair expressions separated by a comma. It returns an intermediate point on
+the line through \meta{$p_1$} and \meta{$p_2$}. The formula for the
+returned value is $p_1 + \mbox{\meta{num}}(p_2 - p_1)$. The midpoint is
+obtained with $\mbox{\meta{num}} = .5$. If the \meta{num} is a pure
+number, the parentheses can be omitted, but they are required if it is
+any other numeric expression. Values of \meta{num} larger than 1 or
+less than zero produce points on the line that lie outside the segment
+from $p_1$ to $p_2$. This operator can also be applied to numbers or (in
+\MP{}) to colors (of the same type). So that \mfc{(2/3)[3,6] = 5} and
+\mfc{.7[green,blue] = (0,.3,.7)}. See section~\ref{colors} for a
+description of colors in \MP{} and \MF{}.
+
+\begin{cd}
+ \gbc{pathpoint(\meta{frac},\meta{name})}
+\end{cd}
+This is another useful \MF{} command. It requires a number, \meta{frac},
+and the \emph{name} of a previously defined \MF{} path variable.
+(Defined, for example, using \cs{store}; see
+subsection~\ref{transformation}). It returns the point on the path that
+is approximately that fraction of the path's length from the start of
+the path. For example to draw a line from $(0,0)$ to the midpoint of an
+arc, do the following:
+\begin{verbatim}
+\store{myarc}\draw\arc{(1,0),(0,2),90}
+\polyline{(0,0), pathpoint(.5,myarc)}
+\end{verbatim}
+\CMF{} has no general command for calculating the lengths of paths;
+\CMP{} does, but it is quite slow. Thus neither program has an efficient
+method for finding the described point, so \mfp{} uses \MF\slash\MP{} macros
+that are faster, but less accurate than they could be. Still, the
+results should (except in pathological cases) be accurate to within a
+couple of percent of the length of the path. If they are not, adjust the
+value of the fraction. These remarks about accuracy also hold for any
+other command (such as \cs{partpath} in subsection~\ref{reversal}) that
+take the fraction of a path length as a parameter.
+
+The \gbc{pathpoint} command is not a basic \MF{} command, but is defined
+by the \prog{grafbase} macros that accompany \mfp{}.
+
+\MF{} pairs can conveniently be viewed as complex numbers. So
+\file{grafbase} also contains some functions useful in complex analysis
+(my research field). In what follows \gbc{a}, \gbc{z} and \gbc{w} denote
+pair variables or constants, and each function interprets them as
+complex numbers. Also \gbc{t} denotes an angle in radians. There are
+both numeric and pair valued functions, the type of each is noted after
+the description:
+
+\noindent
+\begin{tabular}{@{}ll}
+\gbc{Arg z} & The principle argument of $z$ in radians (numeric).\\
+\gbc{Log z} & The principle logarithm of $z$ (pair).\\
+\gbc{cis t} & $(\cos t, \sin t)$, same as \gbc{dir degrees(t)} (pair).\\
+\gbc{zexp w} & The complex exponential, $e^w$ (pair).\\
+\gbc{sgn z} & The signum, $\sgn (0,0) = (0,0)$ otherwise $\sgn z = z/|z|$ (pair).\\
+\gbc{conj z} & The complex conjugate, $\bar z$ (pair).\\
+\gbc{Moebius(a) z} & The M\"obius transformation $(z+a)/(1+\bar{a}z)$ (pair)\\
+\gbc{pshdist(z,w)} & The pseudohyperbolic distance between $z$ and
+ $w$: $|z-w| / |1-\bar{w}z|$ (numeric).
+\end{tabular}
+
+
+\subsection{Manipulating \MF{} picture variables}
+
+\begin{cd}\pagelabel{tile}
+\cs{tile}\marg{\meta{tilename},\meta{unit},\meta{wd},\meta{ht},\meta{clip}}\\
+ \ \meta{\mfp{} drawing commands}\\
+\cs{endtile}%
+\index{tile@\cs{tile}}%
+\index{endtile@\cs{endtile}}
+\end{cd}
+
+In this environment, all drawing commands contribute to a \emph{tile}. A
+\emph{tile} is a rectangular picture which may be used to fill the
+interior of closed paths. Actually, a tile is a composite object. After
+\cs{tile}\marg{Nick, ... } $\ldots$ \cs{endtile} a picture variable
+\gbc{Nick.pic} is created as well as numeric variable \gbc{Nick.wd} and
+\gbc{Nick.ht}. These are needed by the \cs{tess} command, below.
+
+The units of drawing are given by \meta{unit}, which should be an
+explicit dimension (like \dim{1pt} or \dim{.2in}). The tile's horizontal
+dimensions are $0$ to $\meta{wd}\cdot\meta{unit}$ and its vertical
+dimensions $0$ to $\meta{ht}\cdot\meta{unit}$, so \meta{wd} and
+\meta{ht} should be pure numbers. If \meta{clip} is \mfc{true} then the
+drawing is clipped to be within the tile's boundary.
+
+By using this macro, you can design your own fill patterns (to use them,
+see the \cs{tess} macro below), but see the warning about memory use by
+the \cs{tess} command. The \meta{tilename} is globally defined by this
+command.
+
+\begin{cd}\pagelabel{tess}
+\cs{tess}\marg{\meta{tilename}}$\ldots$%
+\index{tess@\cs{tess}}
+\end{cd}
+
+This rendering macro tiles the interior of a closed path with a
+tessellation comprised of copies of the \emph{tile} specified by
+\meta{tilename}. The tile must have been previously created by
+\cs{tile}\marg{\meta{tilename}, ... }. Tiling an open curve is
+technically an error, but the \MF{} code responds by drawing the path
+and not doing any tiling. The \MF{} code places shifted copies of the
+tile picture in a rectangular grid sufficient to cover the region, then
+clips it to the closed path before drawing it.
+
+Tiling large regions with complicated tiles can exceed the capacity of
+some versions of \MP{}. There is less of a problem with \MF{}. This is not
+because \MF{} has greater capacity, but because of the natural
+difference between bitmaps and vector graphics.
+
+In \MP{}, the tiles are copied with whatever color they are given when
+they are defined. They can be multicolored.
+
+Before version 0.8, \cs{tile} was the only way to create a picture
+variable, and the only way to draw this picture was with the \cs{tess}
+command. Now we have the following command to place multiple copies of
+a picture:
+
+\begin{cd}\pagelabel{putmfpimage}
+ \cs{putmfpimage}\marg{\meta{name}}{\meta{list}}%
+\index{putmfpimage@\cs{putmfpimage}}
+\end{cd}
+
+This take the name of a picture variable and copies the picture at each
+location in the \meta{list}, which should be a comma-separated list of
+coordinate pairs in graph coordinates. The picture is copied so that its
+\emph{reference point} is placed at each of the locations. The reference
+point of a picture created with \cs{tile} is its lower left corner.
+
+\begin{cd}\pagelabel{mfpimage}
+ \cs{mfpimage}\oarg{\meta{refpt}}\marg{\meta{picname}}\\
+ \ \meta{\mfp{} drawing commands}\\
+ \cs{endmfpimage}%
+\index{mfpimage@\cs{mfpimage}}%
+\index{endmfpimage@\cs{endmfpimage}}
+\end{cd}
+
+This is another way to create a picture variable. The drawing commands
+within the \env{mfpimage} environment contribute not to the current
+\mfp{} picture, but rather to the picture variable named in \meta{picname}.
+Otherwise, they operate exactly as they would outside this environment,
+using the same coordinate system and the same default values of all
+parameters, etc. (unlike the \env{tile} environment, which defines its
+own coordinate system). The picture is created with its reference point
+at the point \meta{refpt} given in the optional argument. The default is
+\texttt{(0,0)}. For example:
+\begin{verbatim}
+\mfpimage[(1,1)]{Jan}
+ \fill\rect{(0,0),(1,1)}
+ \fill\rect{(1,1),(2,2)}
+ \rect{(0,0),(2,2)}
+\endmfpimage
+\end{verbatim}
+produces a simple 2-by-2 chessboard with its reference point at the
+center point $(1,1)$. One can then write something like
+\begin{verbatim}
+\putmfpimage{Jan}{(1,1),(3,1),(1,3),(3,3)}
+\end{verbatim}
+to get a 4-by-4 chessboard: the picture \mfc{Jan} copied with its
+center at each of the listed points.
+
+The behavior of \cs{tlabel} in an \env{mfpimage} environment depends on
+the setting. If \opt{mplabels} is turned off, then labels are added by
+\TeX{} and are \emph{not} included as part of the named \MF{} or \MP{}
+picture variable. They are placed on the current picture as if the
+\env{mfpimage} environment were not there at all. If \opt{mplabels} is
+turned on and \opt{overlaylabels} is also turned on, or if the
+\env{mfpimage} environment is between \cs{startbacktext} and
+\cs{stopbacktext}, then the labels will be saved and placed when the
+\env{mfpic} environment ends and \emph{not} added to the named picture
+variable. Thus, to include text labels in the named picture variable,
+you must have \opt{mplabels} on, \opt{overlaylabels} off, and
+\env{mfpimage} outside any \cs{startbacktext}\slash\cs{stopbacktext}.
+
+The picture created by \cs{mfpimage} is locally defined. That is, it
+becomes undefined at the end of the current \env{mfpic} environment. If
+one needs it to be global, one can use \cs{globalsetmfvariable} (see
+subsection~\ref{variables}) to copy it to another variable. For example.
+the command
+\begin{verbatim}
+ \globalsetmfvariable{picture}{Dan}{Jan}
+\end{verbatim}
+would make \gbc{Dan} globally defined to be equal to the current value
+of the picture \gbc{Jan}. Note that picture variables can consume a lot
+of \MF{}'s memory. Copying one variable to another doubles the amount of
+memory, at least until the end of the \env{mfpic} environment.
+
+You can use \cs{putmfpimage} inside a \env{mfpimage} environment,
+provided the picture being placed has been previously defined. Nesting a
+\env{mfpimage} inside another has not been tested at all and so is not
+recommended. But if it works, the inner image would be local to the
+environment created by the outer one, and so would be of limited use.
+One can use the \LaTeX{} environment construct \cs{begin}\marg{mfpimage}
+$\ldots$ \cs{end}\marg{mfpimage} in a LaTeX document instead of
+\cs{mfpimage} $\ldots$ \cs{endmfpimage}.
+
+\subsection{\CMF{} loops}\label{loops}
+
+All the \mfp{} loop commands create a loop (in the \MF{} language) in
+the output file. The \MF{} commands in that loop are executed repeatedly
+by \MF{} or \MP{}. From the point of view of \TeX{}, however each
+command occurs only once. Starting with version 0.9, these loops can be
+created inside or outside the \env{mfpic} drawing environment. If
+outside, they must not contain any drawing commands, but can contain
+commands that set variables, perform computations, etc.
+
+\begin{cd}\pagelabel{mfpfor}
+\cs{mfpfor}\marg{\meta{for-loop header}}\\
+ \ \meta{\mfp{} commands}\\
+\cs{endmfpfor}%
+\index{mfpfor@\cs{mfpfor}}%
+\index{endmfpfor@\cs{endmfpfor}}
+\end{cd}
+
+This creates a for-loop in the \MF{} output file. The \cs{mfpfor} writes
+the start of the loop and \cs{endmfpfor} writes the end. Any code
+written in the output file between them is executed repeatedly by
+\MF{}, according to the information in \meta{for-loop header}. There are
+two types of headers possible, illustrated by the following examples.
+\begin{verbatim}
+\mfpfor{center = (0,0), (1,0), (0,1)}
+ \gfill\circle{center,1}
+\endmfpfor
+\end{verbatim}
+This example will fill three circles of radius 1 with centers at the
+three given points. This type of header has the format
+\begin{display}
+ \mfc{\meta{variable} = \meta{list}}
+\end{display}
+where \meta{variable} should be a simple variable name and \meta{list}
+is a comma separated list of items of the appropriate data type. In the
+above, \gbc{center} is equated to pairs, but in the following
+\begin{verbatim}
+\mfpfor{radius = 1,3,4}
+ \dotted\circle{(0,0),radius}
+\endmfpfor
+\end{verbatim}
+\gbc{radius} gets numeric data.
+
+The other type of header uses a stepped variable:
+\begin{verbatim}
+\mfpfor{level = 3 step 2 until 9}
+ \circle{(0,0),sqrt(level)}
+\endmfpfor
+\end{verbatim}
+This will cause the \MF{} variable \gbc{level} to step through the
+values 3, 5, 7 and 9 and the circles with radius $\sqrt{3}$, $\sqrt{5}$,
+etc. will be drawn. This type of header has the format
+\begin{display}
+ \mfc{\meta{variable} = \meta{start} step \meta{delta} until \meta{stop}}
+\end{display}
+where \meta{variable} is as before, while \meta{start}, \meta{delta} and
+\meta{stop} are numeric values. If \meta{delta} is positive the loop is
+skipped entirely if \meta{stop} is less than \meta{start}. Otherwise the
+loop is executed successively with the variable equal to \meta{start},
+then $\meta{start} + \meta{delta}$ then $\meta{start} + 2\meta{delta}$,
+etc., as long as the variable is not greater than \meta{stop}. The
+behavior is similar if \meta{delta} is negative, except the loop is
+repeated only as long as the variable is not less than \meta{stop}. If
+\meta{delta} is \mfc{0}, then the \MF{} run will generate an error.
+
+Note that the index variable (\gbc{center} and \gbc{radius} in the above
+two examples) is a temporary \MF{} variable. If \opt{mplabels} is turned
+on, this variable will work as expected in the \emph{location} parameter
+of a \cs{tlabel} command, but if it is used in the \emph{label} part, it
+will be interpreted as \TeX{} code and printed as is. The index variable
+reverts to its previous state outside the loop. That is, if it existed
+before the loop, it regains its previous value after the loop, and if it
+was undefined before the loop, it is again undefined after.
+
+The single word ``\mfc{upto}'' can be used as an abbreviation for
+``\mfc{step 1 until}'' and ``\mfc{downto}'' for ``\mfc{step -1 until}''
+in for-loop headers. Spaces are not significant in for-loop headers,
+except to distinguish the keywords (e.g. \mfc{step}) from variable names
+that might be use (e.g., for \meta{start}).
+
+\begin{cd}\pagelabel{mfpwhile}
+ \cs{mfpwhile}\marg{\meta{condition}}\\
+ \ \meta{\mfp{} commands}\\
+ \cs{endmfpwhile}%
+\index{mfpwhile@\cs{mfpwhile}}%
+\index{endmfpwhile@\cs{endmfpwhile}}
+\end{cd}
+
+The \meta{condition} should be an expression that can be either true or
+false about a \MF{} variable that changes at some time during the loop
+body. The loop body is executed (by \MF) as long as the condition is
+true. Example:
+\begin{verbatim}
+\setmfvariable{numeric}{R}{20}
+\mfpwhile{R > 1}
+ \rect{(0,0), (R,3R)}
+ \mfcmd{R:=R/2}
+\endmfpwhile
+\end{verbatim}
+There are no \mfp{} command to \emph{systematically} change a variable,
+so in this example we have resorted to directly writing a \MF{} assignment
+command via \cs{mfcmd} (see subsection~\ref{mfcode} above) that reduces
+\mfc{R} by half. The loop will be executed with \mfc{R} having the
+successive values $20$, $10$, $5$, $2.5$, and $1.25$. The resulting
+picture could have been achieved with \cs{mfpfor} using this list of
+values.
+
+\begin{cd}\pagelabel{mfploop}
+\cs{mfploop}\\
+ \ \meta{\mfp{} commands}\\
+\cs{mfpuntil}\marg{\meta{condition}}\\
+ \ \meta{\mfp{} commands}\\
+\cs{endmfploop}%
+\index{mfploop@\cs{mfploop}}%
+\index{mfpuntil@\cs{mfpuntil}}%
+\index{endmfploop@\cs{endmfploop}}%
+\end{cd}
+
+The body of this loop will be repeated until the \meta{condition}
+becomes true. The condition should be some expression that can be either
+true or false about a variable that changes during the loop execution.
+It should eventually become true. If an \env{mfploop} environment does
+not contain an \cs{mfpuntil} command, then the \cs{endmfploop} command
+will generate a warning message. If the warning is ignored, and the user
+has not otherwise arranged for loop termination,%
+ \footnote{Perhaps by means of \cs{mfsrc} commands. It is because of
+ this possibility that only a warning is produced and not an error.}
+the \file{.mf} file will contain an infinite loop. The \cs{mfpuntil}
+command will break the loop at whatever point it occurs. Example:
+\begin{verbatim}
+\setmfvariable{numeric}{R}{20}
+\mfploop
+ \mfcmd{R:=R/2}
+ \mfpuntil{R <= 1}
+ \rect{(0,0), (R,3R)}
+\endmfploop
+\end{verbatim}
+This will draw rectangles with $R$ equal to $10$, $5$, $2.5$, and
+$1.25$. On the next execution of the loop the condition \mfc{R<=1} is
+true, and the break occurs before the next rectangle is drawn. Note that
+any \cs{mfpwhile} could be encoded with \cs{mfploop}. In fact, the code
+written to the output file by
+\begin{display}
+\cs{mfpwhile}\marg{\meta{condition}}
+\end{display}
+is identical to that written by
+\begin{display}
+\cs{mfploop}\cs{mfpuntil}\marg{not \meta{condition}}
+\end{display}
+
+The command \cs{mfpuntil} can also be used in \env{mfpfor} and
+\env{mfpwhile} environments to break the loop prematurely when the given
+condition becomes true.
+
+All three of these loop structures bracket the inner code in a \TeX{}
+group. In a \LaTeX{} document, the usual \cs{begin}\slash\cs{end} style can
+be used. For example,
+\begin{verbatim}
+\begin{mfpfor}{radius = 1,3,4}
+ \circle{(0,0),radius}
+\end{mfpfor}
+\end{verbatim}
+
+Just to be clear: in all the examples, what is written to the figure
+file is a \emph{single} circle or rectangle drawing command, bracketed
+by code that causes \MF{} to execute it several times with different
+values for the variable. From \TeX{}'s point of view, there is only one
+drawing command command.
+
+\subsection{Miscellaneous}\label{misc}
+
+\begin{cd}\pagelabel{mfmode}
+\cs{mfmode}\marg{\meta{mode-name}}\\
+\cs{mfresolution}\marg{\meta{DPI}}%
+\end{cd}
+
+When working with \MF{}, the code in \file{grafbase.mf} needs to know
+the resolution at which to make the font with all the figures. If the
+wrong resolution is assumed, the figure may end up appearing wrongly
+scaled or have other problems (especially with shading). If your DVI
+viewing/printing program and the file \file{modes.mf} are correctly
+configured, nothing may need to be done. If not, as a last resort, you
+can set the \MF{} mode or the \MF{} resolution in your \file{.tex} file
+with these commands. If you don't know what that means, ask a guru, but
+then you probably shouldn't be using \MF{} at all.
+
+\begin{cd}\pagelabel{noship}
+\cs{noship}\\%
+\cs{stopshipping}\\%
+\cs{resumeshipping}%
+\index{noship@\cs{noship}}%
+\index{stopshipping@\cs{stopshipping}}%
+\index{resumeshipping@\cs{resumeshipping}}
+\end{cd}
+
+\cs{stopshipping} turns off character shipping (by \MF{} to the TFM and
+GF files, or by \MP{} to appropriate \EPS{} output file) until
+\cs{resumeshipping} occurs. If you want just one character not shipped,
+just use \cs{noship} inside that \env{mfpic} environment. This is useful
+if all one wishes to do in the current \env{mfpic} environment is to
+make tiles (see above) or define picture variables with \cs{mfpimage} or
+path arrays with \cs{patharr}. While \cs{mfpimage} defines the picture
+locally, one can globally copy it to another variable with
+\cs{globalsetmfvariable} (see subsection~\ref{variables}).
+
+\begin{cd}\pagelabel{assignmfvalue}
+\cs{assignmfvalue}\marg{\meta{\TeX{}-macro}}\marg{\meta{MF-expr}}\\
+\cs{assignmpvalue}\marg{\meta{\TeX{}-macro}}\marg{\meta{MF-expr}}\\
+\cs{globalassignmfvalue}\marg{\meta{\TeX{}-macro}}\marg{\meta{MF-expr}}\\
+\cs{globalassignmpvalue}\marg{\meta{\TeX{}-macro}}\marg{\meta{MF-expr}}%
+\index{assignmfvalue@\cs{assignmfvalue}}%
+\index{assignmpvalue@\cs{assignmpvalue}}%
+\index{globalassignmfvalue@\cs{globalassignmfvalue}}%
+\index{globalassignmpvalue@\cs{globalassignmpvalue}}%
+\end{cd}
+
+The commands \cs{assignmpvalue} and \cs{globalassignmpvalue} are just
+alternative spellings. You can use either spelling with either the
+\opt{metafont} or \opt{metapost} option.
+
+These commands causes the \meta{MF-expr} to be written to the output
+file for \MF{} to evaluate. The resulting value is then written to the
+\file{.log} file of that \MF{} run. On the next \TeX{} run, if
+\opt{mfpreadlog} (see section~\ref{readlog}) is in effect, the macro
+\meta{\TeX{}-macro} will be defined to produce the resulting value. For
+example:
+\begin{verbatim}
+\setmfnumeric{s}{2}
+\assignmfvalue{\val}{exp s}
+\tlabel(1,2){$e^s = \val$}
+\end{verbatim}
+After \MF{} is run and then \TeX{} run a second time, \cs{val} will
+acquire the definition `7.38905', the value of \gbc{exp s} when
+\gbc{s=2} (i.e., $e^2$, correct to at least the fourth decimal place).
+If \opt{mplabels} is in effect, the correct label is written to the
+figure file only during this second run, and a second \MP{} run will be
+required. In many cases (when using \pdfTeX{}, for example, or when the
+label changes the figure dimensions), a third \TeX{} run will be
+required to make the figure correct when it is included in the document.
+
+Before \MF{} is run to evaluate the expression, the macro produces
+`???'. Thus, it cannot be used in places where a number is needed (as in
+the position arguments of a \cs{tlabel} command). Note also that if a
+command defined by \cs{assignmfvalue} is used in a tlabel with
+\opt{mplabels} in effect, then \opt{mplabels} must be in effect during
+the \cs{assignmfvalue} command as well.
+
+The `\texttt{global}' version makes the definition of the
+\meta{\TeX{}-macro} global, surviving the current group. In particular,
+it can be used in other pictures. The plain versions create commands
+that are only locally defined. Past versions of this manual stated that
+you can say
+\begin{display}
+ \cs{global}\cs{assignmfvalue}
+\end{display}
+to define the macro globally. This turns out not to be true in all
+cases. If a global definition is needed, use the global versions above.
+
+Because of the asynchronous nature of the definition process, using
+\cs{assignmfvalue} with the same macro name more than once in the same
+\env{mfpic} environment will not work. The macro acquires its definition
+upon reading the logfile during the execution of \cs{opengraphsfile},
+and it will end up with the last definition encountered. (The same is
+true for uses outside \env{mfpic} environments: the macro acquires the
+last such definition.) Moreover, the definition is associated to a
+picture by number. Which means that reordering the environments or
+changing the numbering by any means will require the \TeX{}-\MF{}-\TeX{}
+sequence (or more) to be repeated.
+
+If the \meta{\TeX{}-macro} is already defined, no warning will be issued
+and the command will be redefined, so be careful in the name chosen.
+If \opt{mplabels} is turned off when \cs{assignmfvalue} is used, but
+turned on before the \meta{\TeX{}-macro} is used in a \cs{tlabel}
+command, the macro definition will not be written to the \file{.mp}
+file, and either an error message, or incorrect label will result
+when \MP{} tries to make the tlabel.
+
+The concept and much of the code for \cs{assignmfvalue} came from Werner
+Lemberg. However, I have rewritten it substantially to conform to \mfp{}
+conventions and so any errors are my responsibility.
+
+\begin{cd}\pagelabel{cutoffafter}
+\cs{cutoffafter}\marg{\meta{obj}}\dots\\
+\cs{cutoffbefore}\marg{\meta{obj}}\dots\\
+\index{cutoffafter@\cs{cutoffafter}}%
+\index{cutoffbefore@\cs{cutoffbefore}}%
+\end{cd}
+
+These prefix macros modify the following path by cutting part of it off.
+They take an `object' (a variable in which a path was
+previously stored using \cs{store}) and uses it to trim off one end of the
+following path. \cs{cutoffbefore} cuts off the part of the path
+\emph{before} its first intersection with the object, while
+\cs{cutoffafter} cuts off the part \emph{after} the last intersection.
+If the path does not intersect the object, nothing is cut off. If the
+object and the path intersect in more than one point, as little as
+possible (usually%
+ \footnote{\MF{}'s methods for finding the `first' point of
+ intersection do not always find the actual first one.}) %
+is cut off. This is reliable only when there is only one point of
+intersection.
+
+These macros can be used to create a curve that starts or ends
+right at another figure without having to know the point where the two
+curves intersect.
+
+\begin{cd}\pagelabel{random}
+\cs{randomlines}\marg{\meta{maxshift}}\dots\\
+\cs{randomizepath}\marg{\meta{maxshift}, \meta{weirdness}}\dots
+\index{randomizepath@\cs{randomizepath}}%
+\index{randomlines@\cs{randomlines}}
+\end{cd}
+
+These modify the following path by applying random shifts to the nodes
+of a path. The first one, \cs{randomlines} then simply connects those
+new points by straight lines, while the second one also applies
+randomization to the control vectors. The \meta{maxshift} argument is
+either a positive number (in graph units) that limits the distance a
+node can be moved, or it is an ordered pair of positive numbers, in
+which case the first limits the horizontal distance and the second
+limits the vertical. If \meta{maxshift} is larger than the distance
+between nodes, cusps or loops are likely in the result.
+
+For \cs{randomizepath} the \meta{weirdness} parameter controls how the
+control vectors are modified. Roughly speaking the control vectors are
+randomly rotated up to $30\langle\mathit{weirdness}\rangle$ degrees and
+randomly scaled up or down by a factor of
+$2^{\langle\mathit{weirdness}\rangle}$. (A `control vector' is a vector
+pointing from a node to one of its control points.) However, this is
+done in a way that preserves smoothness at each node where the path is
+smooth. Values of \meta{weirdness} greater than 1 are probably too
+weird.
+
+\begin{cd}\pagelabel{brownianmotion}
+\cs{brownianmotion}\marg{\meta{start},\meta{num},\meta{scale}}%
+\index{brownianmotion@\cs{brownianmotion}}
+\end{cd}
+
+This figure macro uses another kind of randomness. The path starts at
+the point \meta{start}, then proceeds in a straight line in a random
+direction a random distance. The random process used is a normaldeviate
+in each coordinate, scaled by \meta{scale}. This is repeated \meta{num}
+times. Thus, \meta{start} is a coordinate pair in graph coordinates,
+\meta{num} is a positive whole number and \meta{scale} is a positive
+real number. In rare cases, the random distance can be quite large, but
+on average it will be about $0.56\times{}$\meta{scale}. The size
+(bounding box) of the resultant path can also be, in rare cases,
+quite large, but it is usually on the order of $\sqrt{\meta{num}}$ times
+\meta{scale}.
+
+The path produced is technically not Brownian motion, but rather a
+`random walk'. However, for small \meta{scale} and large \meta{num} it
+approximates Brownian motion.
+
+\begin{cd}\pagelabel{mftitle}
+\cs{mftitle}\marg{\meta{title}}%
+\index{mftitle@\cs{mftitle}}
+\end{cd}
+
+Write the string \meta{title} to the \MF{} file, and use it as a \MF{}
+message. (See \textit{The \MF{}book}, chapter 22, page 187, for two uses of
+this.)
+
+\begin{cd}\pagelabel{tmtitle}
+\cs{tmtitle}\marg{\meta{title}}%
+\index{tmtitle@\cs{tmtitle}}
+\end{cd}
+
+Write the text \meta{title} to the \TeX{} document, and to the log file,
+and use it implicitly in \cs{mftitle}. This macro forms a local group
+around its argument.
+
+\medskip
+
+Since \TeX{} is limited to 256 dimension registers, and since dimensions
+are so important to typesetting and drawing, it is common to use up all
+256 when drawing packages are loaded. Therefore \mfp{} uses font
+dimensions to store dimension values. The following is the command that
+handles the allocation of these dimensions.
+
+\begin{cd}\pagelabel{newfdim}
+\cs{newfdim}\marg{\meta{fdim}}%
+\index{newfdim@\cs{newfdim}}
+\end{cd}
+
+This create a new global font dimension named \meta{fdim}, which is a
+\TeX{} control sequence (with backslash). It can be used almost like
+an ordinary \TeX{} dimension. One exception is that the \TeX{} commands
+\cs{advance}, \cs{multiply} and \cs{divide} cannot be applied directly
+to font dimensions (nor \LaTeX{}'s \cs{addtolength}); however, the font
+dimension can be copied to a temporary \TeX{} dimension register, which
+can then be manipulated and copied back (using \cs{setlength} in \LaTeX{},
+if desired). Another exception is that all changes to a font dimension
+are global in scope. Also beware that \cs{newfdim} uses font dimensions
+from a single font, the \file{dummy} font, which most \TeX{} systems
+ought to have. (You'll know if yours doesn't, because \mfp{} will fail
+upon loading!) Also, implementations of \TeX{} differ in the number of
+font dimensions allowed per font. \Mfp{} currently uses font dimensions
+23 through 52, which should be OK.
+
+Almost all of \mfp{}'s basic dimension parameters are font dimensions.
+We arrange for them to be local to \env{mfpic} environments by saving
+their values at the start and restoring them at the end.
+
+\begin{cd}\pagelabel{setmfpicgraphic}
+\cs{setmfpicgraphic}\marg{\meta{filename}}%
+\index{setmfpicgraphic@\cs{setmfpicgraphic}}
+\end{cd}
+
+This is the command that is invoked to place the graphic created. See
+appendix~\ref{graphics} for a discussion of its use and its default
+definition. It is a user-level macro so that it can be redefined in
+unusual cases. It operates on the output of the following macro:
+
+\begin{cd}\pagelabel{setfilename}
+\cs{setfilename}\marg{\meta{file}}\marg{\meta{num}}%
+\index{setfilename@\cs{setfilename}}
+\end{cd}
+
+\Mfp's figure inclusion code ultimately executes
+\cs{setmfpicgraphic} on the result of applying \cs{setfilename} to two
+arguments: the file name specified in the \cs{opengraphsfile} command
+and the number of the current picture. Normally \cs{setfilename} just
+puts them together with the `\texttt{.}' separator (because that is
+usually the way \MP{} names its output), but this can be redefined if
+the \MP{} output undergoes further processing or conversion to another
+format in which the name is changed. Any redefinition of
+\cs{setfilename} must come before \cs{opengraphsfile} because that
+command tests for the existence of the first figure. After any
+redefinition, \cs{setfilename} must be a macro with two arguments that
+creates the actual filename from the above two parts. It should also be
+completely expandable. See the appendices, subsection~\ref{graphics} for
+further dicussion.
+
+\begin{cd}\pagelabel{setfilenametemplate}
+\cs{setfilenametemplate}\marg{\meta{template}}%
+\index{setfilenametemplate@\cs{setfilenametemplate}}
+\end{cd}
+
+With the \opt{metapost} option, when you write
+\cs{opengraphsfile{figs}}, a file \file{figs.mp} is created. By default,
+running \MP{} on it results in files named \file{figs.1}, \file{figs.2},
+etc. Recent \MP{} allows the output filenames to be modified. As of
+\mfp{} version \mfpversion, you can do this to some extent from your
+\file{.tex} file. One needs to define a template that tells \MP{} how to
+construct the output file name from the `jobname' and the figure number.
+This is done with the above command. In \meta{template} you can put any
+plain characters, plus the two special tokens: \verb$\_$ and \verb$\#$.
+Each figure's filename is constructed by replacing these tokens with the
+\MP{} jobname and the figure number, respectively. For example, with the
+jobname \file{figs},
+\begin{verbatim}
+\setfilenametemplate{my\_-\#.mps}
+\end{verbatim}
+will cause the figure files to have names \file{myfigs-1.mps},
+\file{myfigs-2.mps}, etc., instead of the defaults. \Mfp{} adjusts the
+definition of \cs{setfilename} accordingly, so that the correct
+filenames are used.
+
+Do not use this command unless you know your version of \MP{} is recent
+enough to have this capability. Under the \opt{metafont} option, this
+command is simply ignored, but \mfp{} has no way of checking the \MP{}
+version on its own.
+
+
+\begin{cd}\pagelabel{preparemfpicgraphic}
+\cs{preparemfpicgraphic}\marg{\meta{filename}}%
+\index{preparemfpicgraphic@\cs{preparemfpicgraphic}}
+\end{cd}
+
+This command is automatically invoked before \cs{setmfpicgraphic} to
+make any preparations needed. The default definition is to do nothing
+except when the \prog{graphics} package is used. That package provides
+no clean way to determine the bounding box of the graphic after it is
+included. Since \mfp{} needs this information, this command redefines an
+internal command of the \prog{graphics} package to make the data
+available. If \cs{setmfpicgraphic} is redefined then this may also have
+to be redefined.
+
+\begin{cd}\pagelabel{getmfpicoffset}
+\cs{getmfpicoffset}\marg{\meta{filename}}%
+\index{getmfpicoffset@\cs{getmfpicoffset}}
+\end{cd}
+
+This command is automatically invoked after \cs{setmfpicgraphic} to
+store the offset of the lower left corner of the figure in the macros
+\cs{mfpicllx} and \cs{mfpiclly}. If \cs{setmfpicgraphic} is redefined
+then this may also have to be redefined.
+
+\begin{cd}\pagelabel{ifmfpmpost}
+\cs{ifmfpmpost}%
+\index{ifmfpmpost@\cs{ifmfpmpost}}
+\end{cd}
+
+Users wishing to write code that adjusts its behavior to the graph file
+processor can use this to test which option is in effect. The macro
+\cs{usemetapost} sets it true and \cs{usemetafont} sets it false. There
+are no commands \cs{mfpmposttrue} nor \cs{mfpmpostfalse}, since the user
+should not be changing the setting once it is set: a great deal of
+\mfp{} internal code depends on them, and on keeping them consistent
+with the \cs{opengraphsfile} commands reading of these booleans.
+
+\begin{cd}\pagelabel{mfpicversion}
+\cs{mfpicversion}%
+\index{mfpicversion@\cs{mfpicversion}}
+\end{cd}
+
+This expands to the current \mfp{} version multiplied by 100. At this
+writing, it produces `\texttt{100}' because the version is 1.0. It can
+be used to test the version:
+\begin{verbatim}
+\ifx\mfpicversion\undefined \def\mfpicversion{0}\fi
+\ifnum\mfpicversion>70 ... \else ... \fi
+\end{verbatim}
+\cs{mfpicversion} was added in version 0.7.
+
+
+Most of \mfp{}'s commands have arguments with parts delimited by commas
+and parentheses. In most cases this is no problem because they are
+written unchanged to the \file{.mf} and there they are parsed just fine.
+Some commands' arguments, however, have to be parsed by both \TeX{} and
+\MF{}. Examples are \cs{tlabel} (sometimes, under \opt{mplabels}), and
+\cs{pointdef}. One might be tempted to use \MP{} expressions there and
+that works fine as long as they do not contain commas or parentheses. In
+such cases, they can sometimes be enclosed in braces to prevent \TeX{}
+seeing these elements as delimiters, but sometimes these braces might
+get written to the \file{.mf} (or \file{.mp}) output and cause a \MF{}
+(\MP{}) error. In such cases the following work-around might be possible:
+\begin{verbatim}
+\def\identity#1{#1}
+\pointdef{A}(\identity{angle (1,2)},3)
+\rect{(0,0),\A}
+\end{verbatim}
+
+The braces prevent \TeX{}'s argument parsing from seeing the first comma
+as a delimiter, but upon writing to the \file{.mf}, the \cs{identity}
+commands are expanded and only the contents appear in the output. (\TeX{}
+parses the argument to assign meanings to \cs{Ax} and \cs{Ay}.)
+
+If the \prog{babel} package is loaded with certain options, the comma
+may become a special character. In that case, one may need to deactivate
+babel shorthands before some \mfp{} code. One might use \cs{everymfpic}
+to do this in every \env{mfpic} environment. In some cases, one may need
+to reactivate babel shorthands insided \cs{tlabel}, and one might use
+\cs{everytlabel} for this purpose. See your \prog{babel} documentation
+for the commands to do these things.
+
+\clearpage
+
+\def\sectionmark#1{\markright {\thesection\quad#1}}%
+\def\subsectionmark#1{}
+\def\subsubsectionmark#1{}
+\thispagestyle{plain}
+\chapter{Appendices}\label{appendices}
+
+\section{Acknowledgements.}\label{acknowledgements}
+
+Tom would like to thank all of the people at Dartmouth as well as out in
+the network world for testing \mfp{} and sending him back
+comments. He would particularly like to thank:
+
+Geoffrey Tobin
+for his many suggestions, especially about cleaning up the \MF{} code,
+enforcing dimensions, fixing the dotted line computations, and speeding
+up the shading routines (through this process, Geoffrey and Tom managed
+to teach each other many of the subtleties of \MF{}), and for keeping
+track of \mfp{} for nearly a year while Tom finished his thesis;
+
+Bryan Green
+for his many suggestions, some of which (including his rewriting the
+\cs{tcaption} macro) ultimately led to the current version's ability to
+put graphs in-line or side-by-side; and
+
+Uwe Bonnes and
+Jarom\'\i r Kuben,
+who worked out rewrites of \mfp{} during Tom's working hiatus and who
+each contributed several valuable ideas.
+
+Some credit also belongs to
+Anthony Stark,
+whose work on a FIG to \MF{} converter has had a serious impact on the
+development of many of \mfp{}'s capabilities.
+
+Finally, Tom would like to thank
+Alan Vlach,
+the other \TeX{}nician at Berry College, for helping him decide on the
+format of many of the macros, and for helping with testing.
+
+\medskip
+Dan Luecking would like to echo Tom's thanks to all of the above,
+especially Geoffrey Tobin and Jarom\'\i r Kuben. And to add the names
+Taco Hoekwater, for comments, advice and suggestions, Werner Lemberg,
+for the \cs{assignmfvalue} command, and Zaimi Sami~Alex for suggestions.
+
+But mostly, he'd like to thank Tom Leathrum for starting it all.
+
+\section{Changes History.}\label{changes}
+
+See the file \file{changes.txt} for a somewhat sporadic history of
+changes to \mfp{}. See the file \file{README} for changes added since
+the previous version, and for any known problems.
+
+%\clearpage
+\section{Summary of Options.}\label{summary}
+
+Unless otherwise stated, any of the command forms will be local to the
+current \env{mfpic} environment if used inside. Otherwise it will affect
+all later environments.
+
+\medskip
+% \shortstack doesn't allow [t] aligment:
+\def\stack#1{{\tabular[t]{@{}l@{}}#1\endtabular}}
+
+% Use halign so it will break over 2 pages
+{\openup\jot
+\halign to \textwidth
+ {#\hfil\quad\tabskip0ptplus 1fil&
+ #\hfil\quad&
+ \vtop{\parindent0pt\rightskip0pt plus 1fil\relax
+ \hsize.5\hsize\normalbaselines
+ \strut#\strut}\tabskip0pt \cr
+\textsc{Option}:& \textsc{Command form(s)}:& \textsc{Restrictions}:\cr
+\noalign{\smallskip\hrule\smallskip}
+\opt{metapost}&
+ \cs{usemetapost}&
+ Command must come before \cs{opengraphsfile}.
+ Incompatible with \opt{metafont} option.\cr
+\opt{metafont}&
+ \cs{usemetafont}&
+ The default. Command must come before
+ \cs{opengraphsfile}. Incompatible with \opt{metapost}
+ option. \cr
+\opt{mplabels}&
+ \stack{\cs{usemplabels},\\ \cs{nomplabels}}&
+ Requires \opt{metapost}. If command is used inside an
+ \env{mfpic} environment, it should come before
+ \cs{tlabel} commands to be affected. \cr
+\opt{overlaylabels}&
+ \stack{\cs{overlaylabels},\\ \cs{nooverlaylabels}}&
+ Has no effect without \opt{metapost}. \cr
+\opt{truebbox}&
+ \stack{\cs{usetruebbox},\\ \cs{notruebbox}}&
+ Has no effect without \opt{metapost}. \cr
+\opt{clip}&
+ \stack{\cs{clipmfpic},\\ \cs{noclipmfpic}}&
+ No restrictions. \cr
+\opt{clearsymbols}&
+ \stack{\cs{clearsymbols},\\ \cs{noclearsymbols}}&
+ No restrictions. \cr
+\stack{\opt{centeredcaptions}\\ \opt{raggedcaptions}}&
+ \stack{\cs{usecenteredcaptions},\\ \cs{nocenteredcaptions}\\
+ \cs{useraggedcaptions},\\ \cs{noraggedcaptions}}&
+ If command is used inside an \env{mfpic} environment, it
+ should come before the \cs{tcaption} command.\cr
+\opt{debug}&
+ \stack{\cs{mfpicdebugtrue},\\\cs{mfpicdebugfalse}}&
+ To turn on debugging while \file{mfpic.tex} is loading,
+ issue \cs{def}\cs{mfpicdebug}\marg{true}.\cr
+\stack{\opt{draft}\\ \opt{final}\\ \opt{nowrite}}&
+ \stack{\cs{mfpicdraft}\\ \cs{mfpicfinal}\\ \cs{mfpicnowrite}}&
+ Should not be used together. Command forms should come
+ before \cs{opengraphsfile} \cr
+\opt{mfpreadlog}&
+ \cs{mfpreadlog}&
+ Needed for \cs{assignmfvalue}. Must occur before
+ \cs{opengraphsfile}. \cr
+}}
+
+%\clearpage
+\section{Plotting Styles for \cs{plotdata}.}\label{styles}
+
+When \cs{plotdata} passes from one curve to the next, it increments a
+counter and uses that counter to select a dash pattern, color, or
+symbol. It uses predefined dash \mfc{dashtype0} through \mfc{dashtype5},
+or predefined colors \mfc{colortype0} through \mfc{colortype7}, or
+predefined symbols \mfc{pointtype0} through \mfc{pointtype8}. Here
+follows a description of each of these variables. These variables must
+not be used in the second argument of \cs{reconfigureplot}, whose
+purpose is to redefine these variables.
+
+\medskip
+Under \cs{dashedlines}, we have the following dash patterns:
+
+\medskip
+\begin{tabular}{@{}lll}
+\textsc{Name}&\textsc{Pattern}&\textsc{Meaning}\cr
+\hline
+\vbox to 10pt{}%
+\mfc{dashtype0}& \dim{0bp} & solid line \\
+\mfc{dashtype1}& \dim{3bp,4bp} & dashes \\
+\mfc{dashtype2}& \dim{0bp,4bp} & dots \\
+\mfc{dashtype3}& \dim{0bp,4bp,3bp,4bp} & dot-dash \\
+\mfc{dashtype4}& \dim{0bp,4bp,3bp,4bp,0bp,4bp}& dot-dash-dot \\
+\mfc{dashtype5}& \dim{0bp,4bp,3bp,4bp,3bp,4bp}& dot-dash-dash
+\end{tabular}
+
+\medskip
+Under \cs{coloredlines}, we have the following colors. Except for
+\mfc{black} and \mfc{red}, each color is altered as indicated. This is
+an attempt to make the colors more equal in visibility against a white
+background. (The success of this attempt varies greatly with the output
+or display device.) Four of the eight colors use the cmyk model
+when the \MP{} version is at least $1.000$.
+
+\medskip
+\begin{tabular}{@{}llll}
+\textsc{Name}&\textsc{Color}&\textsc{(r,g,b)}&\textsc{(c,m,y,k)}\\
+\hline
+\vbox to 10pt{}%
+\mfc{colortype0}& black & $( 0, 0, 0)$&(0,0,0,1)\\
+\mfc{colortype1}& red & $( 1, 0, 0)$&\\
+\mfc{colortype2}& blue & $( .2, .2, 1)$&\\
+\mfc{colortype3}& orange & $(.66,.34, 0)$&\\
+\mfc{colortype4}& green & $( 0, .8, 0)$&\\
+\mfc{colortype5}& magenta& $(.85, 0,.85)$&(0,.85,0,.15)\\
+\mfc{colortype6}& cyan & $( 0,.85,.85)$&(.85,0,0,.15)\\
+\mfc{colortype7}& yellow & $(.85,.85, 0)$&(0,0,.85,.15)\\
+\end{tabular}
+
+\medskip
+
+Under \cs{pointedlines} and \cs{datapointsonly}, the following symbols
+are used. Internally each is referred to by the numeric name, but they
+are identical to the more descriptive name. Syntactically, all are \MF{}
+path variables. (The order changed between versions 0.6 and 0.7.)
+
+\medskip
+\begin{tabular}{@{}ll}
+\textsc{Name}&\textsc{Description}\\
+\hline
+\vbox to 10pt{}%
+\mfc{pointtype0}& \mfc{Circle} \\
+\mfc{pointtype1}& \mfc{Cross} \\
+\mfc{pointtype2}& \mfc{SolidDiamond} \\
+\mfc{pointtype3}& \mfc{Square} \\
+\mfc{pointtype4}& \mfc{Plus} \\
+\mfc{pointtype5}& \mfc{Triangle} \\
+\mfc{pointtype6}& \mfc{SolidCircle} \\
+\mfc{pointtype7}& \mfc{Star} \\
+\mfc{pointtype8}& \mfc{SolidTriangle}
+\end{tabular}
+
+\section{Special Considerations When Using \CMF{}.}\label{mfconsiderations}
+
+The most important restriction in \MF{} is on the size of a picture.
+Coordinates in \MF{} ultimately refer to pixel units in the font that is
+output. These are required to be less than 4096, so an absolute limit on
+the size of a picture is whatever length a row of 4095 pixels is. In
+fonts prepared for a LaserJet4 (600 DPI), this means 6.825 inches
+(17.3355cm). For a 1200 DPI pronter, the limit is 3.4125 inches.
+
+A similar limit holds for numbers input, and the values of variables:
+\MF{} will return an error for \mfc{sin 4096}. Intermediate values can
+be greater (\mfc{sin (2*2048)} will cause no error), but final, stored
+results are subject to the limit. An \mfp{} example that generated an
+error recently was:
+\begin{verbatim}
+\mfpicunit 1mm
+\mfpic[10]{-3}{7}{-3.5}{5}
+ \function{-4.5,4,.1}{x*x}
+\endmfpic
+\end{verbatim}
+The problem was the value of $4.5*4.5 = 20.25$: after multiplying by the
+\cs{mfpic} scaling factor, the \cs{mfpicunit} in inches, and the DPI
+value, this produces $20.25\times10\times0.03937\times600 > 4783$ pixel
+units. The error did not occur at the point of creating the font, but
+merely at the point of storing the path in an internal variable for
+manipulation and drawing. Thus, the fact that this particular picture
+was clipped to a much smaller size for printing did not help.
+
+In \MP{}, the limit on numeric values is only 8 times as high: $32768$.
+However, that is independent of printer resolution and is interpreted as
+\PS{} points (\TeX{}'s `big points'). At $72$ points to the inch, this
+allows figures to be about 12.64 yards (11.56$\,$m).
+
+
+\section{Special Considerations When Using \CMP{}.}\label{mpconsiderations}
+
+\subsection{Required support}
+
+To use \mfp{} with \MP{}, the following support is needed (besides a
+working \MP{} installation):
+
+\medskip\noindent
+\begin{tabular}{@{}lp{4.2in}}
+plain \TeX{} &The file \file{epsf.tex} or \file{epsf.sty}\\
+\LaTeX{}209 &(No longer supported, but plain \TeX{} methods
+ might work)\\
+\LaTeX{} &The package \prog{graphics} or \prog{graphicx}\\
+\pdfLaTeX{} &The package \prog{graphics} or
+ \prog{graphicx} with option \opt{pdftex}\\
+plain \pdfTeX{} &The files \file{supp-pdf.mkii} or \file{supp-pdf.tex}
+ and (possibly) \file{supp-mis.tex}\\
+In all cases &\raggedright The files \file{grafbase.mp} and
+ \file{dvipsnam.mp} plus, of course,
+ \file{mfpic.tex} (and \file{mfpic.sty} for
+ \LaTeX{})
+\end{tabular}
+
+\medskip
+The files \file{grafbase.mp} and \file{dvipsnam.mp} should be in a
+directory searched by \MP{}. The remaining files should be in directories
+searched by the appropriate \TeX{} variant. If \MP{} cannot find the
+file \file{grafbase.mp}, then by default it will try to input
+\file{grafbase.mf}, which is generally futile (or fatal).
+
+In case \pdfLaTeX{} is used, the \prog{graphics} package is given the
+\opt{pdftex} option. This option requires the file \file{pdftex.def}
+which currently inputs one of the \file{supp-pdf} files. Early versions
+of \file{supp-pdf.tex} will input \file{supp-mis.tex}. These three files
+should be supplied with most \TeX{} installations.%
+ \footnote{At this writing, these files, plus a few others,
+ can found at \file{CTAN/macros/pdftex/graphics/}.} %
+Older versions had some bugs in connection with the \prog{babel}
+package. One workaround was to load the \prog{graphics} package and
+\mfp{} before \prog{babel}.
+
+If the user loads one of the above required files or packages before the
+\mfp{} macros are loaded then \mfp{} will not reload them. \Mfp{} will
+load whichever one it decides is required. In the \LaTeXe{} case, \mfp{}
+will load the \prog{graphics} package. If the user wishes
+\prog{graphicx}, then that package must be loaded before \mfp{}.
+
+\subsection{\CMP{} is not \MF{}}
+
+\PS{} is not a pixel oriented language and so neither is \MP{}. The model
+for drawing objects is completely different between \MF{} and \MP{}, and
+so one cannot always expect the same results. \CMP{} support in
+\mfp{} was carefully written so that files successfully printed
+with \mfp{} using \MF{} would be just as successfully printed
+using \MP{}. Nevertheless, it frequently chokes on files that make use of
+the \cs{mfsrc} command for writing code directly to the \file{.mf} file.
+While \file{grafbase.mp} is closely based on \file{grafbase.mf}, some of
+the code had to be completely rewritten.
+
+Pictures in \MP{} are stored as (possibly nested) sequences of objects,
+where objects are things like points, paths, contours, sub-pictures,
+etc. In \MF{}, pictures are stored as a grid of pixels. Pictures that are
+relatively simple in one program might be very complex in the other and
+even exceed memory allocated for their storage. Two examples are the
+\cs{polkadot} and \cs{hatch} commands. When the polkadot space and size
+are both too small, a \cs{polkadot}-ed region has been known to exceed
+\MP{} capacity, while being well within \MF{} capacity. In \MP{} the
+memory consumed by \cs{hatch} goes up in direct proportion to the linear
+dimensions of the figure being hatched, while in \MF{} it goes up in
+proportion to the area (except in horizontal hatching), and then the
+reverse can happen, with \MF{}'s capacity exeeded far sooner that \MP{}'s.
+
+In \MP{} it is important to note that each
+prefix modifies the result of the entire following sequence. In essence
+prefixes can be viewed as being applied in the opposite order to their
+occurrence. Example:
+\begin{verbatim}
+\dashed\gfill\rect{(0,0),(1,1)}
+\end{verbatim}
+This adds the dashed outline to the filled rectangle. That is, first the
+rectangle is defined, then it is filled, then the outline is drawn in
+dashed lines. This makes a difference when colors other than black are
+used. Drawing is done with the center of the virtual pen stroked down
+the middle of the boundary, so half of its width falls inside the
+rectangle. On the other hand, filling is done right up to the boundary.
+In this example, the dashed lines are drawn on top of part of the fill.
+In the reverse order, the fill would cover part of the dashed outline.
+
+\subsection{Graphic inclusion}\label{graphics}
+
+It may be impossible to completely cater to all possible methods of
+graphic inclusions with automatic tests. The macro that is invoked
+to include the \PS{} graphic is \cs{setmfpicgraphic} and the user
+may (carefully!) redefine this to suit special circumstances. Actually,
+\mfp{} runs the following sequence:
+
+\begin{ex}
+ \cs{preparemfpicgraphic}\marg{\meta{filename}}\\
+ \cs{setmfpicgraphic}\marg{\meta{filename}}\\
+ \cs{getmfpicoffset}\marg{\meta{filename}}%
+\index{preparemfpicgraphic@\cs{preparemfpicgraphic}}%
+\index{setmfpicgraphic@\cs{setmfpicgraphic}}%
+\index{getmfpicoffset@\cs{getmfpicoffset}}
+\end{ex}
+
+The following are the default definitions for \cs{setmfpicgraphic}:
+
+\medskip\noindent
+\begin{tabular}{@{}ll}
+plain \TeX{}&
+ \cs{def}\cs{setmfpicgraphic}\texttt{\#1}\marg{\cs{epsfbox}%
+ \marg{\#1}}\\
+\LaTeX{}209& (No longer supported, but likely the plain \TeX{}
+definition will be selected.)\\
+\LaTeX{}&
+ \cs{def}\cs{setmfpicgraphic}\texttt{\#1}\marg{\cs{includegraphics}%
+ \marg{\#1}}\\
+\pdfLaTeX{}&
+ \cs{def}\cs{setmfpicgraphic}\texttt{\#1}\marg{\cs{includegraphics}%
+ \marg{\#1}}\\
+\pdfTeX{}&
+ \cs{def}\cs{setmfpicgraphic}\texttt{\#1}\marg{\cs{convertMPtoPDF}%
+ \marg{\#1}\marg{1}\marg{1}}
+\end{tabular}
+
+\medskip
+Moreover, since \MP{} by default writes files with numeric extensions,
+we add code to each figure, so that these graphics are correctly
+recognized as \EPS{} or \prog{MPS}. For example, to the figure with
+extension \file{.1}, we add the equivalent of one of the following
+\begin{itemize}
+\item[] \cs{DeclareGraphicsRule}\marg{.1}\marg{eps}\marg{.1}\marg{} in \LaTeXe{}.
+\item[] \cs{DeclareGraphicsRule}\marg{.1}\marg{mps}\marg{.1}\marg{} in
+\pdfLaTeX{}.
+\end{itemize}
+
+After running the command \cs{setmfpicgraphic}, \mfp{} runs
+\cs{getmfpicoffset} to store the lower left corner of the bounding box
+of the figure in two macros \cs{mfpicllx} and \cs{mfpiclly}. All the
+above versions of \cs{setmfpicgraphic} (except \cs{includegraphics})
+make this information available; the definition of \cs{getmfpicoffset}
+merely copies it into these two macros. What \mfp{} does in the
+case of \cs{includegraphics} is to modify (locally) the definition of an
+internal command of the \prog{graphics} package so that it copies the
+information to those macros, and then \cs{getmfpicoffset} does nothing.
+This internal modification is accomplished by the macro
+\cs{preparemfpicgraphic}. Changes to \cs{setmfpicgraphic} might require
+changing either or both of \cs{preparemfpicgraphic} and
+\cs{getmfpicoffset}. All three of these commands are fed the graphic's
+file name as the only argument, although only \cs{setmfpicgraphic}
+currently does anything with it.
+
+One possible reason for wanting to redefine \cs{setmfpicgraphic} might
+be to rescale all pictures. This is \emph{definitely not} a good idea. A
+good deal of \mfp{}'s figure placemant code assumes that the size of the
+figure is consistent with the coordinate system set up by the \cs{mfpic}
+command. With \opt{mplabels} plus \opt{truebbox} it might work, but
+(i)~it has \emph{not} been considered in writing the \mfp{} code,
+(ii)~it will then scale all the text as well as the figure, and (iii)~it
+will scale all line thickness, which should normally be a design choice
+independent of the size of a picture. To rescale all pictures, one need
+only change \cs{mfpicunit} and rerun \TeX{} and \MP{}.
+
+A better reason might be to allow the conversion of your \MP{} figures
+to some other format. Then redefining \cs{setmfpicgraphic}
+could enable including the appropriate file in the appropriate format.
+
+The filename argument mentioned above is actually the result obtained by
+running the macro \cs{setfilename}\index{setfilename@\cs{setfilename}}.
+The command \cs{setfilename} gets two arguments: the name of the \MP{}
+output file (set in the \cs{opengraphsfile} command) without extension,
+and the number of the picture. The default definition of
+\cs{setfilename} merely inserts a dot between the two arguments. That is
+\cs{setfilename}\marg{fig}\marg{1} produces \file{fig.1}. You can
+redefine this behavior also. Any changes to \cs{setfilename} must come
+after the \mfp{} macros are input and before the
+\cs{opengraphsfile} command. Any changes to \cs{setmfpicgraphic} must
+come after the \mfp{} macros are input and before any \cs{mfpic}
+commands, but it is best to place it before the \cs{opengraphsfile}
+command.
+
+As \mfp{} is currently written, \cs{setfilename} must be
+\emph{completely expandable}, which means it should contain no
+definitions, no assignments such as \cs{setcounter}, and no
+calculations.%
+ \footnote{But appropriate use of \cs{numexpr} (in \eTeX) for
+ calculations is probably OK.}
+To test whether a proposed definition is completely
+expandable, put
+\begin{verbatim}
+\message{***\setfilename{file}{1}***}
+\end{verbatim}
+after the definition in a \file{.tex} file and view the result on the
+terminal or in the \file{.log} file. You should see only your expected
+filename between the asterisks.
+
+
+\section{\prog{Mfpic} and the Rest of the World.}
+
+\subsection{The literature}
+
+This author has personal knowledge of only one mathematical article
+which definitely uses \mfp{} to create diagrams, and that is this
+author's joint paper with J.~Duncan and C.~M.~McGregor: \textit{On the
+value of pi for norms in $\mathbf{R}^2$} in the College Mathematics
+Journal, vol.~35, pages 84--92. Oddly enough, it was McGregor and not me
+who chose to use \mfp{} for the illustrations.
+
+There are at least two major publications where \mfp{} has garnered more
+than a cursory mention. The most up-to-date is a section in \textit{The
+\LaTeX{} Graphics Companion} by Michel Goossens, Sebastian Rahtz and
+Frank Mittelbach. It describes a version prior to the introduction of
+\MP{} support, but it correctly describes a subset of its current
+commands and abilities. \textit{The \LaTeX{} Companion} (Second Edition)
+mentions \mfp{}, but only in its annotation of the bibliography entry
+for \textit{\TeX{} Unbound} (see below).
+
+The other is \textit{\TeX{} Unbound} by Alan Hoenig, which contains a
+chapter on \mfp{}. Unfortunately, it describes a version that was
+replaced in 1996 with version 0.2.10.9. The following summarizes the
+differences between the description%
+ \footnote{While I'm at it: \textit{\TeX{} Unbound} occasionally
+ refers to \mfp{} using a logo-like formatting in which the `MF' is
+ in a special font and the `I' is lowered. This `logo' may suggest
+ a relationship between \mfp{} and \PiCTeX{}. There is no such
+ relationship, and there is no official logo-like designation for
+ \mfp{}.} %
+found in Chapter 15 and \mfp{} versions 0.2.10.9 through the
+current one:
+
+\cs{wedge} is now renamed \cs{sector} to avoid conflict with the \TeX{}
+command of the same name. The syntax is slightly different from that
+given for \cs{wedge}:
+\begin{ex}
+ \cs{sector}\marg{(\meta{x},\meta{y}), \meta{radius}, \meta{angle1},
+ \meta{angle2}}
+\end{ex}
+
+The macro \cs{plr}\marg{(\meta{$r_0$},\meta{$\theta_0$}),%
+(\meta{$r_1$},\meta{$\theta_1$}),$\ldots$} is used to convert polar
+coordinate pairs to rectangular coordinates, so the commands
+\cs{plrcurve}, \cs{plrcyclic}, \cs{plrlines} and \cs{plrpoint} were
+dropped from \mfp{}. Now use
+\begin{ex}
+ \cs{curve}\marg{\cs{plr}\marg{(\meta{$r_0$},\meta{$\theta_0$}),%
+ (\meta{$r_1$},\meta{$\theta_1$}),$\ldots$}}
+\end{ex}
+instead of
+\begin{ex}
+ \cs{plrcurve}\marg{(\meta{$r_0$},\meta{$\theta_0$}),%
+ (\meta{$r_1$},\meta{$\theta_1$}),$\ldots$}
+\end{ex}
+and similarly for \cs{plrcyclic}, \cs{plrlines} and \cs{plrpoint}.
+
+\cs{fill} is now renamed \cs{gfill} to avoid conflict with the \LaTeX{}
+command of the same name.
+
+\cs{rotate}, which rotates a following figure about a point, is now
+renamed \cs{rotatepath} to avoid confusion with a similar name for a
+transformation (see below).
+
+\cs{white} is now renamed \cs{gclear} because \cs{white} is too likely
+to be chosen for, or confused with, a color command.
+
+\smallskip
+The following affine transform commands were changed from a third person
+indicative form (which could be confused with a plural noun) to an
+imperative form:
+
+\begin{ex}
+\begin{tabular}{@{}ll}
+ Old name: & New name:\\
+ \cs{boosts} & \cs{boost}\\
+ \cs{reflectsabout} & \cs{reflectabout}\\
+ \cs{rotatesaround} & \cs{rotatearound}\\
+ \cs{rotates} & \cs{rotate}\\
+ \cs{scales} & \cs{scale}\\
+ \cs{shifts} & \cs{shift}\\
+ \cs{xscales} & \cs{xscale}\\
+ \cs{xslants} & \cs{xslant}\\
+ \cs{xyswaps} & \cs{xyswap}\\
+ \cs{yscales} & \cs{yscale}\\
+ \cs{yslants} & \cs{yslant}\\
+ \cs{zscales} & \cs{zscale}\\
+ \cs{zslants} & \cs{zslant}
+\end{tabular}
+\end{ex}
+
+\cs{caption} and \cs{label} are now renamed \cs{tcaption} and
+\cs{tlabel} to avoid conflict with the \LaTeX{} commands.
+
+\cs{mfcmd} was renamed \cs{mfsrc} for clarity, and (in version 0.7) a
+new \cs{mfcmd} was defined, which is pretty much the same except it appends
+a semicolon to its argument.
+
+\smallskip
+There is a misprint: \cs{axisheadlin} should be \cs{axisheadlen}.
+
+Finally, in the \LaTeX{} template on page 496: recent \mfp{} may be
+loaded with \cs{usepackage}.
+
+\subsection{Other programs}
+
+There exists a program, \prog{fig2mfpic} that produces \mfp{} code as
+output. The code produced (as of this writing) is somewhat old and
+mostly incompatible with the description in this manual. Fortunately, it
+is accompanied by the appropriate versions of files \file{mfpic.tex} and
+\file{grafbase.mf}. Unfortunately, the names conflict with the current
+filenames and so they should only be used in circumstances where no
+substitution will occur, say in a local directory with the other sources
+for the document being produced. Moreover, the documentation in this
+manual may not apply to the code produced. However the information in
+\textit{\TeX{} Unbound} may apply.
+
+There exist a package, \prog{circuit\_macros}, that can produce a
+variety of output formats, one of which is \mfp{} code. One writes a
+file (don't ask me what it consists of) and apparently processes it with
+\prog{m4} and then \prog{dpic} to produce the output. The \mfp{} code
+produced appears to be compatible with the current \mfp{}.
+
+\renewcommand\mfpindexheading{%
+ \section{Index of commands, options and parameters.}}
+\let\oldcs\cs
+\renewcommand{\cs}[1]{\leavevmode\mytt{\llap{\char`\\}#1}}
+
+\InputIfFileExists{mfpic-doc.ind}{}{\mfpindexheading}
+
+\let\cs\oldcs
+
+\columnseprule 0pt
+\columnsep 35pt
+\twocolumn[\section{List of commands by type.}]
+\parindent0pt
+\parskip0pt plus .3pt\relax
+\makeatletter
+\renewcommand\@idxitem{\par\hangindent 10\p@}
+\let\item\@idxitem
+\makeatother
+
+\subsection{Figure macros}
+
+ \item \cs{arc}, \pageref{arc}
+ \item \cs{axis}, \pageref{axis}
+ \item \cs{axisline}, \pageref{axisline}
+ \item \cs{belowfcn}, \pageref{belowfcn}
+ \item \cs{border}, \pageref{axisline}
+ \item \cs{brownianmotion}, \pageref{brownianmotion}
+ \item \cs{btwnfcn}, \pageref{btwnfcn}
+ \item \cs{btwnplrfcn}, \pageref{btwnfcn}
+ \item \cs{cbeziers}, \cs{closedcbeziers}, \pageref{cbeziers}
+ \item \cs{chartbar}, \pageref{chartbar}
+ \item \cs{circle}, \pageref{circle}
+ \item \cs{computedspline},\\
+ \cs{closedcomputedspline}, \pageref{computedspline}
+ \item \cs{convexcurve}, \cs{closedconvexcurve}, \pageref{convexcurve}
+ \item \cs{convexcyclic}, \pageref{convexcurve}
+ \item \cs{cspline}, \cs{closedcspline}, \pageref{qspline}
+ \item \cs{curve}, \cs{closedcurve}, \pageref{curve}
+ \item \cs{cyclic}, \pageref{curve}
+ \item \cs{datafile}, \pageref{datafile}
+ \item \cs{ellipse}, \pageref{ellipse}
+ \item \cs{fcncurve}, \pageref{fcncurve}
+ \item \cs{fcnspline}, \pageref{fcnspline}
+ \item \cs{function}, \pageref{function}
+ \item \cs{ganttbar}, \pageref{chartbar}
+ \item \cs{graphbar}, \pageref{chartbar}
+ \item \cs{histobar}, \pageref{chartbar}
+ \item \cs{levelcurve}, \pageref{levelcurve}
+ \item \cs{lines}, \pageref{polyline}
+ \item \cs{mfbezier}, \cs{closedmfbezier}, \pageref{mfbezier}
+ \item \cs{mfobj}, \cs{mpobj}, \pageref{mfobj}
+ \item \cs{parafcn}, \pageref{parafcn}
+ \item \cs{periodicfcnspline}, \pageref{fcnspline}
+ \item \cs{piewedge}, \pageref{piewedge}
+ \item \cs{plrfcn}, \pageref{plrfcn}
+ \item \cs{plrregion}, \pageref{belowfcn}
+ \item \cs{polygon}, \pageref{polygon}
+ \item \cs{polyline}, \pageref{polyline}
+ \item \cs{pshcircle}, \pageref{pshcircle}
+ \item \cs{qbeziers}, \cs{closedqbeziers}, \pageref{qbeziers}
+ \item \cs{qspline}, \cs{closedqspline}, \pageref{qspline}
+ \item \cs{rect}, \pageref{rect}
+ \item \cs{regpolygon}, \pageref{regpolygon}
+ \item \cs{sector}, \pageref{sector}
+ \item \cs{tlabelcircle}, \pageref{tlabelellipse}
+ \item \cs{tlabelellipse}, \pageref{tlabelellipse}
+ \item \cs{tlabeloval}, \pageref{tlabeloval}
+ \item \cs{tlabelrect}, \pageref{tlabelrect}
+ \item \cs{turtle}, \pageref{turtle}
+
+\subsection{Macros that render}
+
+ \item \cs{corkscrew}, \pageref{corkscrew}
+ \item \cs{dashed}, \pageref{dashed}
+ \item \cs{dotted}, \pageref{dotted}
+ \item \cs{doubledraw}, \pageref{doubledraw}
+ \item \cs{draw}, \pageref{draw}
+ \item \cs{gclear}, \pageref{gclear}
+ \item \cs{gclip}, \pageref{gclip}
+ \item \cs{gendashed}, \pageref{gendashed}
+ \item \cs{gfill}, \pageref{gfill}
+ \item \cs{hatch}, \pageref{hatch}
+ \item \cs{lhatch}, \pageref{hatch}
+ \item \cs{plot}, \pageref{plot}
+ \item \cs{plotdata}, \pageref{plotdata}
+ \item \cs{plotnodes}, \pageref{plotnodes}
+ \item \cs{polkadot}, \pageref{polkadot}
+ \item \cs{rhatch}, \pageref{hatch}
+ \item \cs{sinewave}, \pageref{zigzag}
+ \item \cs{shade}, \pageref{shade}
+ \item \cs{tess}, \pageref{tess}
+ \item \cs{thatch}, \pageref{thatch}
+ \item \cs{xhatch}, \pageref{hatch}
+ \item \cs{zigzag}, \pageref{zigzag}
+
+\subsection{Macros that append (arrows)}
+
+ \item \cs{arrow}, \pageref{arrow}
+ \item \cs{arrowhead}, \pageref{arrowhead}
+ \item \cs{arrowmid}, \pageref{arrowhead}
+ \item \cs{arrowtail}, \pageref{arrowhead}
+
+\subsection{Macros that modify}
+
+ \item \cs{bclosed}, \pageref{lclosed}
+ \item \cs{cbclosed}, \pageref{cbclosed}
+ \item \cs{connect}, \cs{endconnect}, \pageref{connect}
+ \item \cs{cutoffafter}, \pageref{cutoffafter}
+ \item \cs{cutoffbefore}, \pageref{cutoffafter}
+ \item \cs{lclosed}, \pageref{lclosed}
+ \item \cs{makesector}, \pageref{makesector}
+ \item \cs{parallelpath}, \pageref{parallelpath}
+ \item \cs{partpath}, \pageref{partpath}
+ \item \cs{qbclosed}, \pageref{cbclosed}
+ \item \cs{randomizepath}, \pageref{random}
+ \item \cs{randomlines}, \pageref{random}
+ \item \cs{reflectpath}, \pageref{shiftpath}
+ \item \cs{reverse}, \pageref{reverse}
+ \item \cs{rotatepath}, \pageref{shiftpath}
+ \item \cs{scalepath}, \pageref{shiftpath}
+ \item \cs{sclosed}, \pageref{lclosed}
+ \item \cs{shiftpath}, \pageref{shiftpath}
+ \item \cs{slantpath}, \pageref{shiftpath}
+ \item \cs{subpath}, \pageref{partpath}
+ \item \cs{transformpath}, \pageref{shiftpath}
+ \item \cs{trimpath}, \pageref{partpath}
+ \item \cs{xscalepath}, \pageref{shiftpath}
+ \item \cs{xslantpath}, \pageref{shiftpath}
+ \item \cs{xyswappath}, \pageref{shiftpath}
+ \item \cs{yscalepath}, \pageref{shiftpath}
+ \item \cs{yslantpath}, \pageref{shiftpath}
+
+\subsection{Lengths}
+
+ \item \cs{axisheadlen}, \pageref{axisheadlen}
+ \item \cs{dashlen}, \pageref{dashlen}
+ \item \cs{dotsize}, \pageref{dotsize}
+ \item \cs{dotspace}, \pageref{dotsize}
+ \item \cs{griddotsize}, \pageref{griddotsize}
+ \item \cs{hashlen}, \pageref{hashlen}
+ \item \cs{hatchspace}, \pageref{hatchspace}
+ \item \cs{headlen}, \pageref{headlen}
+ \item \cs{mfpiccaptionskip}, \pageref{mfpiccaptionskip}
+ \item \cs{mfpicheight}, \pageref{mfpicheight}
+ \item \cs{mfpicunit}, \pageref{mfpicunit}
+ \item \cs{mfpicwidth}, \pageref{mfpicheight}
+ \item \cs{pointsize}, \pageref{pointsize}
+ \item \cs{polkadotspace}, \pageref{polkadotspace}
+ \item \cs{shadespace}, \pageref{shadespace}
+ \item \cs{sideheadlen}, \pageref{sideheadlen}
+ \item \cs{symbolspace}, \pageref{symbolspace}
+
+\subsection{Coordinate transformation}
+
+ \item \cs{applyT}, \pageref{applyT}
+ \item \cs{boost}, \pageref{applyT}
+ \item \cs{coords}, \cs{endcoords}, \pageref{coords}
+ \item \cs{mirror}, \pageref{applyT}
+ \item \cs{reflectabout}, \pageref{applyT}
+ \item \cs{rotate}, \pageref{applyT}
+ \item \cs{rotatearound}, \pageref{applyT}
+ \item \cs{scale}, \pageref{applyT}
+ \item \cs{shift}, \pageref{applyT}
+ \item \cs{turn}, \pageref{applyT}
+ \item \cs{xscale}, \pageref{applyT}
+ \item \cs{xslant}, \pageref{applyT}
+ \item \cs{xyswap}, \pageref{applyT}
+ \item \cs{yscale}, \pageref{applyT}
+ \item \cs{yslant}, \pageref{applyT}
+ \item \cs{zscale}, \pageref{applyT}
+ \item \cs{zslant}, \pageref{applyT}
+
+\subsection{Symbols, axes, grids, marks}
+
+ \item \cs{axes}, \pageref{axes}
+ \item \cs{axis}, \pageref{axis}
+ \item \cs{axismarks}, \pageref{axismarks}
+ \item \cs{bmarks}, \pageref{axismarks}
+ \item \cs{doaxes}, \pageref{axis}
+ \item \cs{grid}, \pageref{grid}
+ \item \cs{gridarcs}, \pageref{plrgrid}
+ \item \cs{gridlines}, \pageref{grid}
+ \item \cs{gridpoints}, \pageref{grid}
+ \item \cs{gridrays}, \pageref{plrgrid}
+ \item \cs{hgridlines}, \pageref{grid}
+ \item \cs{lattice}, \pageref{grid}
+ \item \cs{lmarks}, \pageref{axismarks}
+ \item \cs{plotsymbol}, \pageref{plotsymbol}
+ \item \cs{plrgridpoints}, \pageref{plrgrid}
+ \item \cs{plrgrid}, \pageref{plrgrid}
+ \item \cs{plrpatch}, \pageref{plrgrid}
+ \item \cs{plrvectorfield}, \pageref{vectorfield}
+ \item \cs{point}, \pageref{point}
+ \item \cs{putmfpimage}, \pageref{putmfpimage}
+ \item \cs{rmarks}, \pageref{axismarks}
+ \item \cs{tmarks}, \pageref{axismarks}
+ \item \cs{vectorfield}, \pageref{vectorfield}
+ \item \cs{vgridlines}, \pageref{grid}
+ \item \cs{xaxis}, \pageref{axes}
+ \item \cs{xmarks}, \pageref{axismarks}
+ \item \cs{yaxis}, \pageref{axes}
+ \item \cs{ymarks}, \pageref{axismarks}
+
+\subsection{Symbol names}
+
+ \item \gbc{Arrowhead}, \pageref{arrowhead}
+ \item \gbc{Asterisk}, \pageref{plotsymbol}
+ \item \gbc{Circle}, \pageref{plotsymbol}
+ \item \gbc{Crossbar}, \pageref{arrowhead}
+ \item \gbc{Cross}, \pageref{plotsymbol}
+ \item \gbc{Diamond}, \pageref{plotsymbol}
+ \item \gbc{Leftbar}, \pageref{arrowhead}
+ \item \gbc{Leftharpoon}, \pageref{arrowhead}
+ \item \gbc{Lefthook}, \pageref{arrowhead}
+ \item \gbc{Plus}, \pageref{plotsymbol}
+ \item \gbc{Rightbar}, \pageref{arrowhead}
+ \item \gbc{Rightharpoon}, \pageref{arrowhead}
+ \item \gbc{Righthook}, \pageref{arrowhead}
+ \item \gbc{SolidCircle}, \pageref{plotsymbol}
+ \item \gbc{SolidDiamond}, \pageref{plotsymbol}
+ \item \gbc{SolidSquare}, \pageref{plotsymbol}
+ \item \gbc{SolidStar}, \pageref{plotsymbol}
+ \item \gbc{SolidTriangle}, \pageref{plotsymbol}
+ \item \gbc{Square}, \pageref{plotsymbol}
+ \item \gbc{Star}, \pageref{plotsymbol}
+ \item \gbc{Triangle}, \pageref{plotsymbol}
+
+\subsection{Setting options}
+
+ \item \cs{clearsymbols}, \pageref{clearsymbols}
+ \item \cs{clipmfpic}, \pageref{clip}
+ \item \cs{mfpicdebugfalse}, \pageref{debug}
+ \item \cs{mfpicdebugtrue}, \pageref{debug}
+ \item \cs{mfpicdraft}, \pageref{draft}
+ \item \cs{mfpicfinal}, \pageref{draft}
+ \item \cs{mfpicnowrite}, \pageref{draft}
+ \item \cs{mfpreadlog}, \pageref{readlog}
+ \item \cs{nocenteredcaptions}, \pageref{centeredcaptions}
+ \item \cs{noclearsymbols}, \pageref{clearsymbols}
+ \item \cs{noclipmfpic}, \pageref{clip}
+ \item \cs{nomplabels}, \pageref{mplabels}
+ \item \cs{nooverlaylabels}, \pageref{overlaylabels}
+ \item \cs{noraggedcaptions}, \pageref{raggedcaptions}
+ \item \cs{notruebbox}, \pageref{truebbox}
+ \item \cs{overlaylabels}, \pageref{overlaylabels}
+ \item \cs{usecenteredcaptions}, \pageref{centeredcaptions}
+ \item \cs{usemetafont}, \pageref{metapost}
+ \item \cs{usemetapost}, \pageref{metapost}
+ \item \cs{usemplabels}, \pageref{mplabels}
+ \item \cs{useraggedcaptions}, \pageref{raggedcaptions}
+ \item \cs{usetruebbox}, \pageref{truebbox}
+
+\subsection{Setting values}
+
+ \item \cs{axismargin}, \pageref{axismargin}
+ \item \cs{darkershade}, \pageref{darkershade}
+ \item \cs{dashlineset}, \pageref{dashlineset}
+ \item \cs{dashpattern}, \pageref{dashpattern}
+ \item \cs{dotlineset}, \pageref{dashlineset}
+ \item \cs{drawpen}, \pageref{drawpen}
+ \item \cs{globalsetmfvariable}, \pageref{setmfvariable}
+ \item \cs{hatchwd}, \pageref{hatchwd}
+ \item \cs{headshape}, \pageref{headshape}
+ \item \cs{lightershade}, \pageref{darkershade}
+ \item \cs{mfpicnumber}, \pageref{mfpicnumber}
+ \item \cs{mfplinestyle}, \pageref{mfplinetype}
+ \item \cs{mfplinetype}, \pageref{mfplinetype}
+ \item \cs{pen}, \pageref{drawpen}
+ \item \cs{penwd}, \pageref{drawpen}
+ \item \cs{polkadotwd}, \pageref{polkadotwd}
+ \item \cs{setallaxismargins}, \pageref{axismargin}
+ \item \cs{setallbordermarks}, \pageref{setaxismarks}
+ \item \cs{setaxismargins}, \pageref{axismargin}
+ \item \cs{setaxismarks}, \pageref{setaxismarks}
+ \item \cs{setbordermarks}, \pageref{setaxismarks}
+ \item \cs{setmfboolean}, \pageref{setmfvariable}
+ \item \cs{setmfcolor}, \pageref{setmfvariable}
+ \item \cs{setmfnumeric}, \pageref{setmfvariable}
+ \item \cs{setmfpair}, \pageref{setmfvariable}
+ \item \cs{setmfvariable}, \pageref{setmfvariable}
+ \item \cs{settension}, \pageref{settension}
+ \item \cs{setxmarks}, \pageref{setaxismarks}
+ \item \cs{setymarks}, \pageref{setaxismarks}
+ \item \cs{shadewd}, \pageref{shadewd}
+
+\subsection{Changing colors}
+
+ \item \cs{backgroundcolor}, \pageref{drawcolor}
+ \item \cs{drawcolor}, \pageref{drawcolor}
+ \item \cs{fillcolor}, \pageref{drawcolor}
+ \item \cs{hatchcolor}, \pageref{drawcolor}
+ \item \cs{headcolor}, \pageref{drawcolor}
+ \item \cs{mfpdefinecolor}, \pageref{mfpdefinecolor}
+ \item \cs{pointcolor}, \pageref{drawcolor}
+ \item \cs{tlabelcolor}, \pageref{drawcolor}
+
+\subsection{Defining arrays}
+
+ \item \cs{barchart}, \pageref{barchart}
+ \item \cs{bargraph}, \pageref{barchart}
+ \item \cs{colorarray}, \pageref{setarray}
+ \item \cs{gantt}, \pageref{barchart}
+ \item \cs{globalsetarray}, \pageref{setarray}
+ \item \cs{histogram}, \pageref{barchart}
+ \item \cs{mfpbarchart}, \pageref{barchart}
+ \item \cs{mfpbargraph}, \pageref{barchart}
+ \item \cs{mfpgantt}, \pageref{barchart}
+ \item \cs{mfphistogram}, \pageref{barchart}
+ \item \cs{mfppiechart}, \pageref{piechart}
+ \item \cs{numericarray}, \pageref{setarray}
+ \item \cs{pairarray}, \pageref{setarray}
+ \item \cs{patharr}, \cs{endpatharr}, \pageref{patharr}
+ \item \cs{piechart}, \pageref{piechart}
+ \item \cs{setarray}, \pageref{setarray}
+
+\subsection{Changing behavior}
+
+ \item \cs{coloredlines}, \pageref{coloredlines}
+ \item \cs{dashedlines}, \pageref{coloredlines}
+ \item \cs{datapointsonly}, \pageref{coloredlines}
+ \item \cs{defaultplot}, \pageref{defaultplot}
+ \item \cs{everytlabel}, \pageref{everytlabel}
+ \item \cs{everymfpic}, \cs{everyendmfpic}, \pageref{everymfpic}
+ \item \cs{makepercentcomment}, \pageref{makepercentother}
+ \item \cs{makepercentother}, \pageref{makepercentother}
+ \item \cs{mfpdatacomment}, \pageref{mfpdatacomment}
+ \item \cs{mfpdataperline}, \pageref{mfpdataperline}
+ \item \cs{mfpverbtex}, \pageref{mfpverbtex}
+ \item \cs{noship}, \pageref{noship}
+ \item \cs{pointedlines}, \pageref{coloredlines}
+ \item \cs{pointfillfalse}, \cs{pointfilltrue}, \pageref{pointfilltrue}
+ \item \cs{reconfigureplot}, \pageref{reconfigureplot}
+ \item \cs{resumeshipping}, \pageref{noship}
+ \item \cs{setrender}, \pageref{setrender}
+ \item \cs{smoothdata}, \pageref{datafile}
+ \item \cs{stopshipping}, \pageref{noship}
+ \item \cs{tlabeljustify}, \pageref{tlabeljustify}
+ \item \cs{tlabeloffset}, \pageref{tlabeloffset}
+ \item \cs{tlabelsep}, \pageref{tlabeloffset}
+ \item \cs{tlpathjustify}, \pageref{tlpathjustify}
+ \item \cs{tlpathsep}, \pageref{tlabeloffset}
+ \item \cs{tlpointsep}, \pageref{tlabeloffset}
+ \item \cs{unsmoothdata}, \pageref{datafile}
+ \item \cs{using}, \pageref{using}
+ \item \cs{usingnumericdefault}, \pageref{usingpairdefault}
+ \item \cs{usingpairdefault}, \pageref{usingpairdefault}
+
+\subsection{Files and environments}
+
+ \item \cs{closegraphsfile}, \pageref{opengraphsfile}
+ \item \cs{mfpframe}, \cs{endmfpframe}, \pageref{mfpframe}
+ \item \cs{mfpic}, \cs{endmfpic}, \pageref{mfpic}
+ \item \cs{opengraphsfile}, \pageref{opengraphsfile}
+ \item \cs{setfilename}, \pageref{setfilename}
+ \item \cs{setfilenametemplate}, \pageref{setfilenametemplate}
+
+\subsection{Text}
+
+ \item \cs{axislabels}, \pageref{axislabels}
+ \item \cs{plottext}, \pageref{plottext}
+ \item \cs{startbacktext}, \pageref{backtext}
+ \item \cs{stopbacktext}, \pageref{backtext}
+ \item \cs{tcaption}, \pageref{tcaption}
+ \item \cs{tlabel}, \pageref{tlabel}
+ \item \cs{tlabels}, \pageref{tlabel}
+
+\subsection{Misc}
+
+ \item \cs{assignmfvalue}, \cs{assignmpvalue}, \pageref{assignmfvalue}
+ \item \cs{fdef}, \pageref{fdef}
+ \item \cs{getmfpicoffset}, \pageref{getmfpicoffset}
+ \item \cs{globalassignmfvalue},\\
+ \cs{globalassignmpvalue}, \pageref{assignmfvalue}
+ \item \cs{ifmfpmpost}, \pageref{ifmfpmpost}
+ \item \cs{mfcmd}, \pageref{mfsrc}
+ \item \cs{mflist}, \pageref{mfsrc}
+ \item \cs{mfmode}, \pageref{mfmode}
+ \item \cs{mfpfor}, \cs{endmfpfor}, \pageref{mfpfor}
+ \item \cs{mfpframed}, \pageref{mfpframe}
+ \item \cs{mfpicversion}, \pageref{mfpicversion}
+ \item \cs{mfpimage}, \cs{endmfpimage}, \pageref{mfpimage}
+ \item \cs{mfploop}, \cs{endmfploop}, \pageref{mfploop}
+ \item \cs{mfpuntil}, \pageref{mfploop}
+ \item \cs{mfpwhile}, \cs{endmfpwhile}, \pageref{mfpwhile}
+ \item \cs{mfresolution}, \pageref{mfmode}
+ \item \cs{mfsrc}, \pageref{mfsrc}
+ \item \cs{mftitle}, \pageref{mftitle}
+ \item \cs{newfdim}, \pageref{newfdim}
+ \item \cs{newsavepic}, \pageref{newsavepic}
+ \item \cs{plr}, \pageref{plr}
+ \item \cs{pointdef}, \pageref{pointdef}
+ \item \cs{preparemfpicgraphic}, \pageref{preparemfpicgraphic}
+ \item \cs{savepic}, \pageref{newsavepic}
+ \item \cs{sequence}, \pageref{sequence}
+ \item \cs{setmfpicgraphic}, \pageref{setmfpicgraphic}
+ \item \cs{store}, \pageref{store}
+ \item \cs{tile}, \cs{endtile}, \pageref{tile}
+ \item \cs{tmtitle}, \pageref{tmtitle}
+ \item \cs{usepic}, \pageref{newsavepic}
+
+
+\end{document}
+