summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/mfpic/mfpman.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/mfpic/mfpman.tex')
-rw-r--r--Master/texmf-dist/doc/generic/mfpic/mfpman.tex4991
1 files changed, 4991 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/mfpic/mfpman.tex b/Master/texmf-dist/doc/generic/mfpic/mfpman.tex
new file mode 100644
index 00000000000..7f93ed20e27
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/mfpic/mfpman.tex
@@ -0,0 +1,4991 @@
+%%% File: mfpman.tex
+%%% A part of mfpic 0.7a beta 2004/04/16
+%%%
+% Documentation of mfpic macros
+\documentclass[letterpaper]{article}
+
+\usepackage{pslatex}
+
+\usepackage{mfpdoc}
+\pagestyle{mfpdoc}
+\usepackage{verbatim}
+\usepackage{makeidx}
+\makeindex
+
+\ifpdf
+\usepackage[pdftex,colorlinks,pdfpagemode=none,pdfstartview=FitH,%
+plainpages=false,hypertexnames=true]{hyperref}
+\pdfstringdefDisableCommands{\def\cs#1{\otherbackslash#1}%
+ \def\opt#1{#1}\def\prog#1{#1}}
+\fi
+
+\title{\Mfp: Pictures in \TeX\\ with Metafont and MetaPost}
+\author{Dr Thomas E. Leathrum
+\and Geoffrey Tobin\thanks{\email{G.Tobin@latrobe.edu.au}}
+\and Daniel H. Luecking\thanks{\email {luecking@uark.edu}}}
+\date{\mfpdate}
+
+\begin{document}
+
+\pagenumbering{roman}
+\maketitle
+\tableofcontents
+
+\clearpage
+\pagenumbering{arabic}
+
+\section{Introduction}\label{introduction}
+
+\subsection{Why?}\label{why}
+
+Tom got the idea for \mfp%
+ \footnote{If you're wondering how to pronounce `\mfp': I always say
+ `em-eff-\textbf{pick}', speaking the first two letters. ---DHL.} %
+mostly out of a feeling of frustration. Different output mechanisms for
+printing or viewing \TeX{} DVI files each have their own ways to include
+pictures. More often than not, there are provisions for including
+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 is wonderfully flexible and general,
+but its most obvious feature was its speed---or rather lack of it.
+Processing a single picture in \PiCTeX{} 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 is \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 does
+not get along well with PK fonts, but is quite happy with \MP{}
+pictures. Unfortunately \file{grafbase.mf}, which contained the \MF{}
+macros responsible for processing \mfp's output, was far too
+pixel-oriented for \MP. A new file, \file{grafbase.mp} was created,
+based very heavily on \file{grafbase.mf} but compatible with \MP. Now
+when an \mfp{} output file says \mfc{input grafbase}, either \MF{} or
+\MP{} may be run on it, and each program will select its own macros, and
+produce (nearly) the same picture. This gets us away from device
+independence, but many users were not so much concerned with that as
+with having a convenient way to have text and pictures described in the
+same document.
+
+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.
+
+\subsection{Who?}\label{author}
+
+\Mfp{} 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.
+
+\subsection{What?}\label{manifest}
+
+See \file{README.txt} for a list and a brief explanation of each of
+the files. Only five are actually needed for full access to
+\mfp's capabilities: \file{mfpic.tex}, \file{mfpic.sty} (the
+latter needed only for \LaTeX's \cs{usepackage}), \file{grafbase.mf}
+(needed only if \MF{} will be processing the figures),
+\file{grafbase.mp} and \file{dvipsnam.mp} (needed only if \MP{} will be
+the processor).
+
+The readme file that accompanies \mfp{} gives some guidence on the
+proper location for the installation of these files.
+
+\subsection{How?}\label{process}
+
+Setting up \TeX{} and \MF{} to process these files will, to an extent,
+depend on your local installation. The biggest problem you are likely to
+have, regardless of your installation, will be convincing \TeX{} and its
+output drivers to find \MF's output files. You should do whatever is
+necessary (perhaps nothing!) to insure that \TeX{} looks in the current
+directory for \file{.tfm} files, and that your dvi driver/viewer looks
+in the current directory for \file{.pk} files. If you process your
+pictures with \MP{} there is nothing to do in this regard.
+
+Here is an example of the process: for the sample file
+\file{pictures.tex}%
+ \footnote{Read \file{mfpguide.pdf} for examples of minimal \mfp{}
+ input files.}, %
+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.tfm}, but
+\TeX{} will continue processing the file anyway. When \TeX{} is
+finished, you will now have a file called \file{pics.mf}. This is the
+\MF{} file containing the descriptions of the pictures for
+\file{pictures.tex}. You need to run \MF{} on \file{pics.mf}, with
+\cs{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 \hbox{Geoffrey Tobin}, is a good
+ start. Fetch \file{CTAN/info/metafont-for-beginners.tex}.
+ `\file{CTAN}' means the Comprehensive \TeX{} Archive Network. You
+ can find the mirror nearest you by pointing your browser at
+ \file{http://www.ctan.org/}.}) %
+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 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}). You can delete \file{pics.600gf} and
+\file{pics.log}.
+
+If you use \mfp{} with the \opt{metapost} option (this would require you
+to edit \file{pictures.tex} or \file{lapictures.tex}. See
+chapter~\ref{options} for how to do this), then \file{pics.mp} is
+produced, and you need to replace the \MF/\prog{gftopk} steps with the
+single step of running \MP. (Read your \MP{} documentation on how to do
+this.%
+ \footnote{The document \textit{Some experiences on running Metafont
+ and MetaPost}, by Peter Wilson, can be useful for beginners. Fetch
+ \file{CTAN/info/metafp.pdf}.}) %
+Typically just
+\begin{verbatim}
+ mpost pics.mp
+\end{verbatim}
+or possibly \ \verb$mp pics.mp$ .
+
+After reprocessing \file{pictures.tex} with \TeX{} you should then be
+able to run dvips on the resulting DVI file and print or view its \PS{}
+output. It \pdfTeX{} is used instead of \TeX{} on the second run, you
+should be able to view the resulting PDF file with the pictures
+included.
+
+It is not advisable to rely on automatic font generation to create the
+\file{.tfm} and \file{.pk} files. (Different systems do this in
+different ways, so here I will try to give a generic explanation.) The
+reason: later editing of a figure will require new files to be built,
+and most automatic systems will \emph{not} remake the files once they
+have been created. This is not so much a problem with the \file{.tfm},
+as \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
+unpredictable places) before you can see any later changes. It might
+be wise to write a shell script (batch file) that (1)~runs \MF, (2)~runs
+\prog{gftopk} if step~1 returns no error, (3)~deletes the \file{.tfm} if
+the \file{.pk} file does not exist. 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/\prog{gftopk}, and reprocessing with \TeX---may not always be
+necessary. In particular, if you change the \TeX{} document without
+making any changes at all to the pictures, then there will be no need to
+repeat the \MF{} or \MP{} steps.
+
+There are also somewhat subtle circumstance under which you can skip the
+second \TeX{} step after editing a file that has gone through the above
+process. Listing the exact cirumstances is rather involved, so it is
+recommended that you always repeat the \TeX{} step if changes have been
+made.
+
+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 \MF{} file, that \mfp{} drawing macros translate almost
+directly into similar \MF/\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 \MP{} places the labels).
+
+
+\clearpage
+\section{Options.}\label{options}
+
+There are now several options to the \mfp{} package. These can be listed
+in the standard \LaTeX{} \cs{usepackage} optional argument, or can be
+turned on with certain provided commands (the only possibility for plain
+\TeX). Some options can be switched off and on throughout the document.
+Here we merely list them and provide a general description of their
+purpose. More details may be found later in the discussion of the
+features affected. The headings below give the option name, the
+alternative macro and, if available, the command for turning off the
+option. Any option 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 the file \file{mfpic.usr} exists, 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.
+
+\subsection{\opt{metapost}, \cs{usemetapost}}\label{metapost}
+\index{metapost@\opt{metapost}}\index{usemetapost@\cs{usemetapost}}
+
+Selects \MP{} as the figure processor and makes specific features
+available. It changes the extension used on the output file to
+\file{.mp} to signal that it can no longer be processed with \MF. There
+is also a \opt{metafont} option (command \cs{usemetafont}), but it is
+redundant, as \MF{} is the default. Either command must come before the
+\cs{opengraphsfile} command (see section~\ref{files}). They should not
+be used together in the same document. (Actually, they can but one needs
+to close one output file and open another. Moreover, it hasn't ever been
+seriously tested, and it wasn't taken into consideration in writing most
+of the macros.) If the command form \cs{usemetapost} is used in a
+\LaTeXe{} document, it must come in the preamble. Because of the timing
+of actions by the \prog{babel} package and by older versions of
+\file{supp-pdf.tex} (input by \file{pdftex.def} in the \prog{graphics}
+package), when \pdfLaTeX{} is used \mfp{} should be loaded and
+\cs{usemetapost} (if used) declared before \prog{babel} is loaded.
+
+
+\subsection{\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 has no effect on the \cs{tcaption} command. 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). It may also produce an
+error either from \TeX{} or \MF. Otherwise the commands can come
+anywhere and affect subsequent \cs{tlabel} commands. When this is in
+effect, the labels become part of the figure and, in the default
+handling, they may be clipped off or covered up by later drawing
+elements. But see the next section on the \opt{overlaylabels} option.
+Labels added to a picture contribute to the bounding box even if
+\opt{truebbox} is not in effect.
+
+The user is responsible for adding the appropriate \mfc{verbatimtex}
+header to the output file if necessary. For this purpose, there is the
+\cs{mfpverbtex} command, see section~\ref{labels}. If
+the label text contains only valid plain \TeX{} macros, there is
+generally no need for a \mfc{verbatimtex} preamble at all. If you add a
+\mfc{verbatimtex} preamble of \LaTeX{} code take care to make sure \MP{}
+calls \LaTeX{} (for example, by setting the environmental variable
+\texttt{TEX} to \texttt{latex} in the command shell of your operating
+system.).
+
+
+\subsection{\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 this version 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}.
+
+
+\subsection{\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.
+
+
+\subsection{\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 box specified in the \cs{mfpic} command. It is
+possible that the actual figure will be much smaller (even empty!). This
+is a property of the \MP{} \gbc{clip} command and we know of no way to
+avoid it.
+
+
+\subsection{\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.
+
+\subsection{\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.
+
+\subsection{\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 until now was always simply to 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.
+
+
+\subsection{\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 should come \emph{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.
+
+
+\subsection{Option 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. However, as of this writing I don't
+claim to have caught every one.
+
+The following are special:
+\cs{usemetapost}\index{usemetapost@\cs{usemetapost}},
+\cs{usemetafont}\index{usemetafont@\cs{usemetafont}},
+\cs{mfpicdraft}\index{mfpicdraft@\cs{mfpicdraft}},
+\cs{mfpicfinal}\index{mfpicfinal@\cs{mfpicfinal}},
+and
+\cs{mfpicnowrite}\index{mfpicnowrite@\cs{mfpicnowrite}}.
+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
+\section{The Macros.}\label{macros}
+
+In these descriptions 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 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: \LaTeX, \pdfTeX, \pdfLaTeX, etc.
+
+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{ex}
+ \cs{circle}\marg{(0,0),1}
+\end{ex}
+having only the mandatory argument, or
+\begin{ex}
+ \cs{circle}\oarg{p}\marg{(0,0),1}
+\end{ex}
+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 that \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 request 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}}.
+
+Optional arguments for \mfp{} commands may consist of empty brackets
+(completely empty, no spaces) and the default will be used. This is
+useful only for commands that have two optional arguments and one only
+wants to change from the defaults in the second one. 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 many cases (perhaps most) this will cause no harm, but it
+would be better to avoid doing it altogether.
+
+
+\subsection{Files and Environments.}\label{files}
+
+\begin{cd}
+\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 will cause \file{\meta{file}.mf} or
+\file{\meta{file}.mp} to be overwritten if it already exists, so be sure
+to consider that when selecting the name. Repeating the running of
+\TeX{} will overwrite the file created on previous runs, but that should
+be harmless. For if no changes are made to \env{mfpic} environments, the
+identical file will be recreated, and if changes have been made, then
+you want the file to be replaced with the new version.
+
+It is possible (but \emph{has not} been seriously tested) to close one
+file and open another, and even to change between \opt{metapost} and
+\opt{metafont} in between. If anything goes wrong with this, contact the
+maintainer and it might be fixed in some later version.
+
+\begin{cd}
+\cs{mfpic}\oarg{\meta{xscale}}\oarg{\meta{yscale}}%
+ \marg{\meta{xmin}}\marg{\meta{xmax}}\marg{\meta{ymin}}\marg{\meta{ymax}}\\
+ \ $\ldots$\\
+\cs{endmfpic}%
+\index{mfpic@\cs{mfpic}}\index{endmfpic@\cs{endmfpic}}
+\end{cd}
+
+These macros open and close the \env{mfpic} environment in which most of
+the rest of the macros make sense. The \cs{mfpic} macro also sets up the
+local coordinate system for the picture. The \meta{xscale} and
+\meta{yscale} parameters establish the length of a coordinate system
+unit, as a multiple of the \TeX{} dimension \cs{mfpicunit}. If neither
+is specified, both are taken to be 1 (i.e., each coordinate system unit
+is 1 \cs{mfpicunit}). If only one is specified, then they are assumed to
+be equal. The \meta{xmin} and \meta{xmax} parameters establish the lower
+and upper bounds for the $x$-axis coordinates; similarly, \meta{ymin}
+and \meta{ymax} establish the bounds for the $y$-axis. These bounds are
+expressed in local units---in other words, the actual width of the
+picture will be $(\meta{xmax}-\meta{xmin})\cdot\meta{xscale}$ times
+\cs{mfpicunit}, its height $(\meta{ymax}-\meta{ymin})\cdot\meta{yscale}$
+times \cs{mfpicunit}, and its depth zero. One can scale all pictures
+uniformly by changing \cs{mfpicunit}, and scale an individual picture by
+changing \meta{xscale} and \meta{yscale}. After loading \mfp,
+\cs{mfpicunit} has the value \dim{1pt}. One \texttt{pt} is a
+\emph{printer's point}, which equals 1/72.27 inches or 0.35146
+millimeters.
+
+\emph{Note}: Changing \cs{mfpicunit} or the optional parameters will
+scale the coordinate system, but not the values of certain parameters
+that are defined in absolute units. Examples of these are the default
+width of the drawing pen, the default lengths of arrowheads, the default
+sizes of dashes and dots, etc. If you wish, you can set these to
+multiples of \cs{mfpicunit}, but it is difficult (and probably unwise)
+to get them to scale along with the scale parameters.
+
+In addition to establishing the coordinate system, these scales and
+bounds are used to establish the metric for the \MF{} character or
+bounding box for the \MP{} figure described within the environment. If
+any of these parameters are changed, the \file{.tfm} file (\MF) or the
+bounding box (\MP) will be affected, so you will have to be sure to
+reprocess the \TeX{} file after processing the \file{.mf} or \file{.mp}
+file, even if no other changes are made in the figure.
+
+\begin{cd}
+\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}
+\cs{begin}\marg{mfpic}\texttt{...}\cs{end}\marg{mfpic}%
+\index{begin@\cs{begin}\marg{mfpic}}
+\end{cd}
+
+In \LaTeX, instead of \cs{mfpic} and \cs{endmfpic}, you may prefer to
+use \cs{begin}\marg{mfpic} and \cs{end}\marg{mfpic}. This is by no means
+required: in \LaTeX{} \cs{begin}\marg{command} invokes \cs{command}, and
+\cs{end}\marg{command} invokes \cs{endcommand}, for any environment
+\env{command}.
+
+The sample file \file{lapictures.tex} provided with \mfp{}
+illustrates this use of an \env{mfpic} environment in \LaTeX.
+
+\medskip
+The rest of the \mfp{} macros do not affect the font metric file
+(\file{\meta{file}.tfm}), and so if these commands are changed or added
+in your document, you will not have to repeat the third step of
+processing (reprocessing with \TeX) to complete your \TeX{} document.
+The same is true when option \opt{metapost} is selected without the
+\opt{truebbox} option, except under \pdfTeX{} or \pdfLaTeX. Those \TeX{}
+programs will embed the figures right in the \file{.pdf} output. For
+normal \LaTeX{} + \prog{dvips}, the figures are embedded by
+\prog{dvips}, which must always be repeated.
+
+\medskip
+For the remainder of the macros, the numerical parameters are expressed
+in the units of the local coordinate system specified by \cs{mfpic},
+unless otherwise indicated.
+
+
+\subsection{Figures.}\label{figures}
+
+\subsubsection{\CMF{} Pairs.}\label{pairs}
+
+Since many of the arguments of the \mfp{} drawing commands are
+sent to \MF{} to be interpreted, it's useful to know something about
+\MF{} concepts.
+
+In particular, \MF{} has \mfc{pair} objects, which may be constants or
+variables. Pair constants have the form \mfc{($x$,$y$)}. Pairs are
+two-dimensional rectangular (cartesian) quantities, and are clearly
+useful for representing both points and vectors on the plane.
+
+Moreover, we herein often represent each pair by a brief name, such as
+$p$, $v$ or $c$, the meanings of which are usually obvious in the
+context of the macro. The succinctness of this notation also helps us to
+think geometrically rather than only of coordinates.
+
+\CMP{} has these same concepts, but also has color objects, which may
+also be constants or variables. Color constants have the form
+\mfc{($r$,$g$,$b$)} where $r$, $g$, and $b$ are numbers between $0$ and
+$1$ determining the relative proportions of red, green and blue in the
+color (rgb model). A color variable is a name, like \mfc{magenta} or
+\mfc{RoyalBlue} (predefined). There are also color functions like
+\mfc{cmyk($x$,$y$,$z$,$w$)} which is defined to convert cmyk values into
+\MP's native rgb model.
+
+Some commands depend on the value of separately defined parameters. All
+these parameters are initialized when \mfp{} is loaded. In the following
+descriptions we give the initial value of all the relevant parameters.
+When \MP{} output is selected, figures can be drawn in any color.
+Several of the above mentioned parameters are colors. \Mfp{} provides
+commands to change any of these parameters.
+
+
+\subsubsection{Points, Lines, and Rectangles.}\label{points}
+
+\begin{cd}
+\cs{pointdef}\marg{\meta{name}}\texttt{($x$,$y$)}%
+\index{pointdef@\cs{pointdef}}
+\end{cd}
+
+Defines a symbolic name for points and their coordinates. \meta{name} is
+any legal \TeX{} command name \emph{without} the backslash; $x$ and $y$
+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. Because
+of the way \cs{tlabel} is defined (see section~\ref{labels} below), one
+cannot use \cs{A} to specify where to place a label (unless
+\opt{mplabels} is in effect), but must use \texttt{ (\cs{Ax},\cs{Ay})}. In
+most other commands, one can use \cs{A} where a pair or point is
+required.
+
+\begin{cd}
+\cs{point}\oarg{\meta{ptsize}}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}%
+\index{point@\cs{point}}
+\end{cd}
+
+Draws small disks centered at the points \meta{$p_0$}, \meta{$p_1$}, and
+so on. If the optional argument \meta{ptsize} is present, it determines
+the diameter of the disks, which otherwise equals the \TeX{} dimension
+\cs{pointsize}, initially \dim{2pt}. The disks have a filled interior if
+the command \cs{pointfilltrue} has been issued (the initial value),
+\cs{pointfillfalse} causes the interior to be erased and an outline
+drawn. The color of the circles is the value of the predefined variable
+\gbc{pointcolor}, and the inside of the open circles is the value of
+\mfc{background}.
+
+\begin{cd}
+\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
+\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}}.
+The names should be self-explanatory. 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 closed, ten-sided
+polygon. The name `\cs{plotsymbol}' comes from the fact that the \cs{plot}
+command, which was written first, utilizes these same symbols. The command
+\cs{symbol} was already taken (standard \LaTeX).
+
+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 (i.e., 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}
+\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.
+
+\begin{cd}
+\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}
+
+Draws the line segment with endpoints at \meta{$p_0$} and \meta{$p_1$},
+then the line segment with endpoints at \meta{$p_1$} and \meta{$p_2$},
+etc. The result is an open polygonal path through the specified points,
+in the specified order. \cs{polyline} and \cs{lines} mean the same
+thing.
+
+\begin{cd}
+\cs{polygon}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}%
+\index{polygon@\cs{polygon}}
+\end{cd}
+
+Draws a closed polygon with vertices at the specified points in the
+specified order.
+
+\begin{cd}
+\cs{rect}\marg{\meta{$p_0$},\meta{$p_1$}}%
+\index{rect@\cs{rect}}
+\end{cd}
+
+Draws the rectangle specified by the points \meta{$p_0$} and
+\meta{$p_1$}, these being either pair of opposite corners of the
+rectangle in any order.
+
+It is occasionally helpful to know that connected paths like those
+produced by \cs{polyline} or \cs{rect} have a \emph{sense} (a
+direction). The sense of \cs{polyline} is 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 begins at the first of
+the two points and goes horizontally from there.
+
+\begin{cd}
+\cs{regpolygon}\marg{\meta{num}}\marg{\meta{name}}%
+\marg{\meta{eqn$_1$}}\marg{\meta{eqn$_2$}}%
+\index{regpolygon@\cs{regpolygon}}
+\end{cd}
+
+This produces a 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 refered
+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) will be a \MF{} variable assigned
+the value of \meta{num}. For example,
+\begin{ex}
+\cs{regpolygon}\marg{5}\marg{Meg}\marg{Meg0=(0,1)}\marg{Meg1=(2,0)}
+\end{ex}
+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{ex}
+\cs{polygon}\marg{Meg1,Meg3,Meg5,Meg2,Meg4}
+\end{ex}
+Moreover, \gbc{Meg} 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.
+
+\subsubsection{A Word on List Arguments}\label{list}
+
+We have seen already four \mfp{} macros that take a mandatory argument
+consisting of a list of coordinate pairs. There are many more, and some
+that take a comma-separated lists of other types of items. 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{lines}\marg{\meta{list}}, one can write\index{datafile@\cs{datafile}}
+\begin{ex}
+\cs{lines}\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 as its last argument,
+\emph{with the exception of those commands that adds text to the
+picture}. Examples of the latter are \cs{plottext} and \cs{axislabels}
+(subsection~\ref{text}).
+
+\subsubsection{Axes, Axis Marks, and Grids.}\label{axes}
+
+\begin{cd}
+\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 the prefix macros of sections \ref{modifier}~and \ref{rendering}.
+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}
+\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 changes made by
+\cs{setrender} (see subsection~\ref{default}). Moreover, prefix macros
+may be applied to \cs{axis} without error (see sections
+\ref{modifier}~and \ref{rendering}): \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.
+
+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{doaxis}, then they
+will not cross the side axes. For this to work properly, all the
+following margin settings have to be done before the axes are drawn.
+
+\begin{cd}
+\cs{axismargin}\marg{\meta{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 \meta{axis} is one of the letters \texttt{l}, \texttt{b}, \texttt{r}, or \texttt{
+t}. \cs{axismargin} causes the given axis to be shifted \emph{inward} by
+the \meta{num} specified (in \emph{graph} coordinates). 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 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.
+
+\begin{cd}
+\cs{xmarks}\oarg{\meta{len}}\marg{\meta{numberlist}}\\
+\cs{tmarks}\oarg{\meta{len}}\marg{\meta{numberlist}}\\
+\cs{bmarks}\oarg{\meta{len}}\marg{\meta{numberlist}}\\
+\cs{ymarks}\oarg{\meta{len}}\marg{\meta{numberlist}}\\
+\cs{lmarks}\oarg{\meta{len}}\marg{\meta{numberlist}}\\
+\cs{rmarks}\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 \cs{marks}, but e\kern-.16em\TeX{} makes that a primitive.)
+
+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{ex}
+ \cs{xmarks}\marg{-2 step 1 until 2}
+\end{ex}
+is the equivalent of
+\begin{ex}
+ \cs{xmarks}\marg{-2,-1,0,1,2}
+\end{ex}
+
+One must use exactly the words \mfc{step} and \mfc{until}. There must be
+spaces between, but the number of spaces is not
+significant.%
+ \footnote{Experienced \MF{} programmers may recognize that anything
+ can be used that is permitted in \MF's \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}} %
+Users should be aware that if any of the numbers are non-integral then
+due to natural round-off effects, the last value might be overshot and a
+mark not printed there.
+
+\begin{cd}
+\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} are considered to be
+equivalent, as are \gbc{onbottom} and \gbc{onright}. The parameters
+\gbc{inside} and \gbc{outside} make no sense for the $x$- and $y$-axes,
+but if 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 defined in the file \file{grafbase.mf}, and the
+variables \gbc{ontop} and \gbc{onleft}, for example, are given the same
+value.
+
+\begin{cd}
+\cs{grid}\oarg{\meta{ptsize}}\marg{\meta{xsep},\meta{ysep}}\\
+\cs{gridpoints}\oarg{\meta{ptsize}}\marg{\meta{xsep},\meta{ysep}}\\
+\cs{lattice}\oarg{\meta{ptsize}}\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{ptsize}. The default is \dim{.5bp} and is hard coded in the
+\MF{} macros that ultimately do the drawing. 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 grids. Or omit them entirely: well-designed graphs
+usually don't need them and almost never should both horizontals and
+verticals be used.
+
+\begin{cd}
+\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}\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 at all the places the rays and arcs
+would intersect.
+
+The arcs are centered at $(0,0)$ and the lines emanate from $(0,0)$
+(even if $(0,0)$ is not in the graph space). The corresponding \MF{}
+commands actually draw enough to cover the graph area and then clip them
+to the graph boundaries. If you don't want them clipped, use
+\cs{plrpatch}.
+
+\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 \cs{gridlines} holds for \cs{plrgrid}
+as well.
+
+
+\subsubsection{Circles and Ellipses.}\label{circles}
+
+\begin{cd}
+\cs{circle}\oarg{\meta{format}}\marg{\meta{specification}}%
+\index{circle@\cs{circle}}%
+\end{cd}
+
+Draws a circle. Starting with \mfp{} version 0.7, there are 4
+different ways to specify a circle, so \cs{circle} can be given an
+optional argument that determines what data is 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$}}%
+\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 $c$ and radius $r$ of the
+circle.
+
+\item[\oarg{c}] The \textit{Center-point form}. In this case the data
+should be the center and one point on the circumference.
+
+\item[\oarg{t}] The \textit{Three-point form}. The data are three points
+that do not lie in a straight line.
+
+\item[\oarg{s}] The \textit{point-sweep}. The data are two points on the
+circle, followed by the angle of arc between them.
+\end{description}
+These optional arguments are also used in the \cs{arc} command (see
+subsection~\ref{arcs}). The \cs{circle} command draws the whole circle
+which the equivalent \cs{arc} command draws only part of. The sense of
+the circle produced is anticlockwise except in the case \texttt{[t]},
+where it is the direction determined by the order of the three points,
+and the case \texttt{[s]}, where it is determined by \meta{$\theta$}:
+clockwise if negative, anticlockwise if positive.
+
+
+\begin{cd}
+\cs{ellipse}\oarg{\meta{$\theta$}}\marg{\meta{$c$},\meta{$r_x$},\meta{$r_y$}}%
+\index{ellipse@\cs{ellipse}}%
+\end{cd}
+
+Draws 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.
+
+
+\subsubsection{Curves.}\label{curves}
+
+\begin{cd}
+\cs{curve}\oarg{\meta{tension}}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}%
+\index{curve@\cs{curve}}%
+\end{cd}
+
+Draws 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 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}
+\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.
+
+\begin{cd}
+\cs{cyclic}\oarg{\meta{tension}}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}%
+\index{cyclic@\cs{cyclic}}%
+\end{cd}
+
+Draws a cyclic (i.e., closed) \MF{} B\'ezier curve through the specified
+points, in the specified order. It uses the same procedure as
+\cs{curve}, but treats the first listed point as having the last as its
+predecessor and the last point has the first as its successor. The
+\meta{tension} is as in the \cs{curve} command.
+
+\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}
+\cs{fcncurve}\oarg{\meta{tension}}\marg{($x_0$,$y_0$),($x_1$,$y_1$),$\ldots$}%
+\index{fcncurve@\cs{fcncurve}}%
+\end{cd}
+
+Draws a curve through the points specified. If the points are listed
+with increasing (or decreasing) $x$ coordinates, the curve will also
+have increasing (resp., decreasing) $x$ coordinates. The \meta{tension}
+is a number equal to or greater than $1.0$ which controls how tightly
+the curve is drawn. Generally, the larger it is, the closer the curve is
+to the polyline through the points. The default tension is typically $1.2$
+(actually $1.2$ times the value set with \cs{settension}). 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 be any positive
+number, but only values greater than or equal to $1$ guarantee the
+property of never doubling back.
+
+
+\subsubsection{Circular Arcs.}\label{arcs}
+
+\begin{cd}
+\cs{arc}\oarg{\meta{format}}\marg{\meta{specification}}%
+\index{arc@\cs{arc}}%
+\end{cd}
+
+Draws a circular arc specified as determined by the \meta{format}
+optional parameter. This macro and \cs{circle} are unusual in that 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.
+
+\begin{cd}
+\cs{arc}\oarg{s}\marg{\meta{$p_0$},\meta{$p_1$},\meta{sweep}}\\
+\cs{arc}\oarg{t}\marg{\meta{$p_0$},\meta{$p_1$},\meta{$p_2$}}\\
+\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$}}%
+\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{sweep}
+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{sweep}
+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{sweep} gives a clockwise arc from \meta{$p_0$}
+to \meta{$p_1$}.
+
+\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{p}] The \textit{Polar form} draws the arc of a circle with
+center \meta{$c$} starting at the angle \meta{$\theta_1$} and ending at
+the angle \meta{$\theta_2$}, with radius \meta{$r$}. Both angles are
+measured anticlockwise from the positive $x$ axis.
+
+\item[\oarg{a}] The \textit{Alternate polar form} draws the arc of a
+circle with center \meta{$c$} and radius \meta{$r$}, starting at the
+angle \meta{$\theta_1$} and ending at the angle \meta{$\theta_2$}. Both
+angles are measured anticlockwise from the positive $x$ axis. This is
+provided because it seems a more reasonable order of arguments, and
+matches the order \cs{sector} requires (see subsection~\ref{other}
+below). The \texttt{p} option is retained for backward compatibility.
+
+\item[\oarg{c}] The \textit{Center-point form} draws the circular arc with
+center \meta{$c$}, starting at the point \meta{$p_1$}, and sweeping an
+angle of \meta{$\theta$} around the center from that point. (This and
+the point sweep form are the basic methods of handling arcs---the
+previous three formats are translated to one of these two before drawing.)
+\end{description}
+
+
+\subsubsection{Other Figures.}\label{other}
+
+\begin{cd}
+\cs{turtle}\marg{\meta{$p_0$},\meta{$v_1$},\meta{$v_2$},$\ldots$}%
+\index{turtle@\cs{turtle}}%
+\end{cd}
+
+Draws a line segment, starting from the point \meta{$p_0$}, and
+extending along the (2-dimen\-sional vector) displacement \meta{$v_1$}.
+It then draws a line segment from the previous segment's endpoint, along
+displacement \meta{$v_2$}. This continues for all listed displacements,
+a process similar to `turtle graphics'.
+
+\begin{cd}
+\cs{sector}\marg{\meta{$c$},\meta{$r$},\meta{$\theta_1$},\meta{$\theta_2$}}%
+\index{sector@\cs{sector}}%
+\end{cd}
+
+Draws the sector, from the angle \meta{$\theta_1$} to the angle
+\meta{$\theta_2$} inside the circle with center at the point \meta{$c$}
+and radius \meta{$r$}, where 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}
+\cs{makesector}
+\index{makesector@\cs{makesector}}
+\end{cd}
+The \cs{sector} command requires the center of the arc as one of its
+arguments. But if one doesn't know that center (say one only knows three
+points the arc connects) then even though the arc can be drawn,
+\cs{sector} cannot. The \cs{makesector} command, when followed by any
+\cs{arc} command, will find the center and connect it to the two ends of
+the arc. It will actually attempt to do the same with any path that
+follows, but the `center' it finds (if it finds one) will usually be
+meaningless.
+
+
+\subsubsection{Bar Charts and Pie Charts.}\label{charts}
+
+\begin{cd}
+\cs{barchart}\oarg{\meta{start},\meta{sep},\meta{r}}\marg{\meta{h-or-v}}\marg{\meta{list}}\\
+\cs{bargraph}$\ldots$\\
+\cs{gantt}$\ldots$\\
+\cs{histogram}$\ldots$\\
+\cs{chartbar}\marg{\meta{num}}\\
+\cs{graphbar}\marg{\meta{num}}\\
+\cs{histobar}\marg{\meta{num}}%
+\index{barchart@\cs{barchart}}%
+\index{bargraph@\cs{bargraph}}%
+\index{histogram@\cs{histogram}}%
+\index{chartbar@\cs{chartbar}}%
+\index{graphbar@\cs{graphbar}}%
+\index{histobar@\cs{histobar}}%
+\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.
+
+\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/or pairs giving the coordinates of
+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{..}
+\end{ex}
+and another with
+\begin{ex}
+ \cs{barchart}\oarg{1,1,.4}\marg{h}\marg{..}
+\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 adjacent to 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.
+
+The macro \cs{chartbar} (synonyms \cs{graphbar}, \cs{ganttbar}, and
+\cs{histobar}) takes a number from $1$ to the number of elements in the
+\meta{list} and draws the rectangular path. 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}
+\cs{piechart}\oarg{\meta{dir}\meta{angle}}\marg{\meta{$c$},\meta{$r$}}%
+ \marg{\meta{list}}\\
+\cs{piewedge}\oarg{\meta{spec}\meta{trans}}\marg{\meta{num}}%
+\index{piechart@\cs{piechart}}%
+\index{piewedge@\cs{piewedge}}%
+\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 which may be either \texttt{c} or
+\texttt{a} which stand for \emph{clockwise} or \emph{anticlockwise},
+respectively. It is common to draw piecharts with the largest wedge
+starting at 12 o'clock (angle 90 degrees) and successive wedges
+clockwise from there. This is the default. You can change the starting
+angle from 90 with the \meta{angle} parameter, and the change the
+direction to counter-clockwise by specifying \texttt{a} for \meta{dir}. It
+is also traditional to arrange the wedges from largest to smallest,
+except there is often a miscellaneous category which is usually last and
+may be larger than some others. Therefore \cs{piechart} makes no attempt
+to sort the data. The data is entered as a comma separated \meta{list}
+of positive numbers in the second required parameter. These are only
+used to determine the relative sizes of the wedges and are not printed
+anywhere. The first required parameter should contain a pair \meta{c}
+for the center and a positive number \meta{r} for the radius, separated
+by a comma.
+
+After a \cs{piechart} command has been issued, the individual wedges may
+be drawn, filled, etc., using \cs{piewedge}\marg{1},
+\cs{piewedge}\marg{2}, etc. Without the optional argument, the wedges
+are located according to the arguments of the last \cs{piechart}
+command. 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.
+
+\subsubsection{Polar Coordinates to Rectangular.}\label{polar}
+
+\begin{cd}
+\cs{plr}\marg{(\meta{$r_0$},\meta{$\theta_0$}),
+(\meta{$r_1$},\meta{$\theta_1$}), $\ldots$}%
+\index{plr@\cs{plr}}%
+\end{cd}
+
+Replaces 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---and to data containing both
+rectangular and polar coordinate pairs.
+
+
+\subsection{Colors}\label{colors}
+
+\subsubsection{Setting the Default Colors.}\label{defaultcolors}
+
+\begin{cd}
+\cs{drawcolor}\oarg{\meta{model}}\marg{\meta{colorspec}}\\
+\cs{fillcolor}$\ldots$\\
+\cs{hatchcolor}$\ldots$\\
+\cs{pointcolor}$\ldots$\\
+\cs{headcolor}$\ldots$\\
+\cs{tlabelcolor}$\ldots$\\
+\cs{backgroundcolor}$\ldots$%
+\index{drawcolor@\cs{drawcolor}}%
+\index{fillcolor@\cs{fillcolor}}%
+\index{hatchcolor@\cs{hatchcolor}}%
+\index{pointcolor@\cs{pointcolor}}%
+\index{headcolor@\cs{headcolor}}%
+\index{tlabelcolor@\cs{tlabelcolor}}%
+\index{backgroundcolor@\cs{backgroundcolor}}%
+\end{cd}
+
+These macros set the default color for various drawing
+elements. Any curve (with one exception, those drawn by \cs{plotdata}),
+whether solid, dashed, dotted, or plotted in symbols, will be in the
+color set by \cs{drawcolor}. Set the color used by \cs{gfill} with
+\cs{fillcolor}. For all the hatching commands use \cs{hatchcolor}. For
+the \cs{point}, \cs{plotsymbol} and \cs{grid} commands use
+\cs{pointcolor}, and for arrowheads, \cs{headcolor}. When \opt{mplabels}
+is in effect, the color of labels can be set with \cs{tlabelcolor}, and
+one can set the color used by \cs{gclear} with \cs{backgroundcolor} (the
+same color is used in the interior of unfilled points drawn with
+\cs{point}). The optional \meta{model} may be one of \opt{rgb},
+\opt{RGB}, \opt{cmyk}, \opt{gray}, and \opt{named}. The \meta{colorspec}
+depends on the model, as outlined below. Each of these commands sets a
+corresponding \MP{} color variable with the same name (except
+\cs{backgroundcolor} sets the color \mfc{background}). Thus one can set
+the filling color to the drawing color with
+\cs{fillcolor}\marg{drawcolor}.
+
+\subsubsection{\CMP{} Colors.}\label{mpcolors}
+
+If the optional \meta{model} specification is omitted, the color
+specification may be any expression recognized as a color by \MP. In
+\MP, a color is a triple of numbers like \mfc{(1,.5,.5)}, with the
+coordinates between 0 and 1, representing red, green and blue levels,
+respectively. White is given by \mfc{(1,1,1)} and black by
+\mfc{(0,0,0)}. \CMP{} also has color variables and several have been
+predefined: \mfc{red}, \mfc{green}, \mfc{blue}, \mfc{yellow},
+\mfc{cyan}, \mfc{magenta}, \mfc{white}, and \mfc{black}. All the names
+in the \LaTeX{} \prog{color} package's \file{dvipsnam.def} are
+predefined color variable names. Since \MP{} allows color expressions,
+colors may be added and multiplied by numerics. Moreover, several \MP{}
+color functions have been defined in \file{grafbase.mp}:
+
+\begin{cd}
+\mfc{cmyk($c$,$m$,$y$,$k$)}%
+\index{cmyk@\mfc{cmyk($c$,$m$,$y$,$k$)}}
+\end{cd}
+
+Converts a \opt{cmyk} color specification to \MP's native \opt{rgb}. For
+example, the command \mfc{cmyk(1,0,0,0)} yields \mfc{(0,1,1)}, which is
+the definition of \mfc{cyan}.
+
+\begin{cd}
+\mfc{RGB($R$,$G$,$B$)}%
+\index{RGB@\mfc{RGB($R$,$G$,$B$)}}
+\end{cd}
+
+Converts an \opt{RGB} color specification to \opt{rgb}. It essentially
+just divides each component by 255.
+
+\begin{cd}
+\mfc{gray($g$)}%
+\index{gray@\mfc{gray($g$)}}
+\end{cd}
+
+Converts a numeric $g$ (a gray level) to the corresponding multiple of
+\mfc{(1,1,1)}.
+
+\begin{cd}
+\mfc{named(\meta{name})},
+\mfc{rgb($r$,$g$,$b$)}%
+\index{named@\mfc{named(\meta{name})}}%
+\index{rgb@rgb($r$,$g$,$b$)}
+\end{cd}
+
+These are essentially no-ops. However; \mfc{rgb} will truncate the
+arguments to the 0--1 range, an unknown \meta{name} is converted to
+\mfc{black}, and an unknown numeric argument is set to 0.
+
+\medskip
+As an example of the use of these functions, one could conceivable
+write:
+\begin{ex}
+ \cs{drawcolor}\marg{0.5*RGB(255,0,0)+0.5*cmyk(1,0,0,0)}
+\end{ex}
+to have all curves drawn in a color halfway between red and cyan (which
+turns out to be the same as \gbc{gray(0.5)}).
+
+\subsubsection{Color Models.}\label{colormodels}
+
+When the optional \meta{model} is specified in the color setting
+commands, it determines the format of the color specification:
+
+\medskip
+\halign{\quad#\hfil\quad&#\hfil\cr
+{\sl Model:}& {\sl Specification:}\cr
+\opt{rgb}& Three numbers in the range 0 to 1 separated by commas.\cr
+\opt{RGB}& Three numbers in the range 0 to 255 separated by commas.\cr
+\opt{cmyk}& Four numbers in the range 0 to 1 separated by commas.\cr
+\opt{gray}& One number in the range 0 to 1, with 1 indicating
+ white, 0 black.\cr
+\opt{named}& A \MP{} color variable name either predefined by
+ \mfp{} or by the user.\cr}
+
+\medskip
+\Mfp{} translates
+\begin{ex}
+ \cs{fillcolor}\oarg{cmyk}\marg{1,.3,0,.2}
+\end{ex}
+into the equivalent of
+\begin{ex}
+ \cs{fillcolor}\marg{cmyk(1,.3,0,.2)}.
+\end{ex}
+Note that when the optional model is specified, the color
+specification must not be enclosed in parentheses. Note also that each
+model name is the name of a color function described in the previous
+subsection. That is how the models are implemented internally.
+
+
+\subsubsection{Defining a Color Name.}\label{colorname}
+
+\begin{cd}
+\cs{mfpdefinecolor}\marg{\meta{name}}\marg{\meta{model}}\marg{\meta{colorspec}}%
+\index{mfpdefinecolor@\cs{mfpdefinecolor}}
+\end{cd}
+
+This defines a color variable \meta{name} for later use, either in the
+commands \cs{drawcolor}, etc., or in the optional parameters to
+\cs{draw}, etc. The name can be used alone or in the \opt{named} model.
+The mandatory \meta{model} and \meta{colorspec} are as above.
+
+\medskip
+A final caution, the colors of an \mfp{} figure are stored in the
+\file{.mp} output file, and are not related to colors used or defined by
+the \LaTeX{} \prog{color} package. In particular a color defined only by
+\LaTeX's \cs{definecolor} command will remain unknown to \mfp.
+Conversely, \LaTeX{} commands will not recognize any color defined only
+by \cs{mfpdefinecolor}.
+
+\subsubsection{Color in \MF}
+
+\CMF{} was never meant to understand colors, but it certainly can be
+taught the difference between black and white and, to a limited extent,
+various grays. Starting with version 0.7, \mfp{} will no longer generate
+an error when a color-changing command is used under the \opt{metafont}
+option. Instead, when possible, the variables that represent colors in
+\MP{} will be converted to a numeric value between 0 and 1 in \MF. When
+possible (for example, when a region is filled) the numeric will be
+interpreted as a gray level and shading (see subsection~\ref{filling})
+will be used to approximate the gray. In other cases (drawing or dashing
+of curves, placing of points or symbols, filling with a pattern of hatch
+lines) the number will be interpreted as black or white: a value less
+than 1 will cause the figure to be rendered (in black), while a value
+equal to 1 (white) will cause pixels corresponding to the figure to be
+erased.
+
+This is still somewhat experimental and 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 zeros all affected pixels before adding the dots to
+simulate gray. In particular, \cs{gfill}\oarg{white} should have the
+same effect as \cs{gclear}.
+
+
+\subsection{Shape-Modifier Macros.}\label{modifier}
+
+Some \mfp{} macros operate as \emph{shape-modifier} macros---for
+example, if you want to put an arrowhead on a line segment, you could
+write: \cs{arrow}\cs{lines}\marg{(0,0),(1,0)}. These are always prefixed
+to some figure drawing command, and apply only to the next following
+figure macro (which can be rather far removed) provided that only other
+prefix commands intervene. This is a rather long section, but even more
+modification prefixes are documented in subsection~\ref{transformation}.
+
+For the purposes of these macros, a distinction must be made in the
+figure macros between `open' and `closed' paths. A path that merely
+returns to its starting point is \emph{not} automatically closed; such a
+path is open, and must be explicitly closed, for example by \cs{lclosed}
+(see below). The (already) closed paths are those that have
+`\texttt{closed}' in their name plus: \cs{rect}, \cs{circle},
+\cs{ellipse}, \cs{sector}, \cs{cyclic}, \cs{polygon}, \cs{plrregion},
+\cs{chartbar}, \cs{piewedge}, \cs{tlabelrect}, \cs{tlabeloval},
+\cs{tlabelellipse}, \cs{tlabelcircle} and \cs{btwnfcn} (below).
+
+\subsubsection{Closure of Paths.}\label{closure}
+
+\begin{cd}
+\cs{lclosed}$\ldots$%
+\index{lclosed@\cs{lclosed}}
+\end{cd}
+
+Makes each open path into a closed path by adding a line segment between
+the endpoints of the path.
+
+\begin{cd}
+\cs{bclosed}\oarg{\meta{tens}}$\ldots$
+\index{bclosed@\cs{bclosed}}%
+\end{cd}
+
+This 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.
+
+\begin{cd}
+\cs{sclosed}\oarg{\meta{tens}}$\ldots$%
+\index{sclosed@\cs{sclosed}}
+\end{cd}
+
+This 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 the same result
+as \cs{cyclic} given the same points and tension valuse. The optional
+tension argument is as in the \cs{bclosed} command.
+
+
+\subsubsection{Reversal, Connection and Subpaths.}\label{reversal}
+
+\begin{cd}
+\cs{reverse}$\ldots$%
+\index{reverse@\cs{reverse}}
+\end{cd}
+
+Turns a path around, reversing its sense. This will affect both
+the direction of arrows (e.g. bi-directional arrows can be coded with
+\cs{arrow}\cs{reverse}\cs{arrow}$\ldots$, where the first \cs{arrow}
+modifier applies to the \emph{reversed} path), and the order of
+endpoints for a \cs{connect}$\ldots$\cs{endconnect} environment (below).
+
+
+\begin{cd}
+\cs{connect} $\ldots$
+\cs{endconnect}%
+\index{connect@\cs{connect}}
+\index{endconnect@\cs{endconnect}}
+\end{cd}
+
+This pair of macros, acting as an environment, adds line segments from
+the trailing endpoint of one path to the leading endpoint of the
+next path, in the given order. The result is a connected, \emph{open}
+path.
+
+\emph{Note}: In \LaTeX, this pair of macros can be used in the form of a
+\LaTeX-style environment called \env{connect} ---as in
+\cs{begin}\marg{connect}$\ldots$\cs{end}\marg{connect}.
+
+\begin{cd}
+\cs{partpath}\marg{\meta{frac1},\meta{frac2}}\dots\\
+\cs{subpath}\marg{\meta{num1},\meta{num2}}\dots%
+\index{partpath@\cs{partpath}}%
+\index{subpath@\cs{subpath}}
+\end{cd}
+
+Both produce a part of the following path. 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 \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.
+
+As an example of \cs{partpath}, one can put an arrowhead (see next
+subsection) in the middle of a path with something like the following.
+
+\begin{ex}
+\cs{arrow}\cs{partpath}\marg{0,.5}\cs{draw}\dots
+\end{ex}
+
+
+\subsubsection{Arrows.}\label{arrows}
+
+\begin{cd}
+\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}
+
+Draws an arrowhead at the endpoint of the open path (or at the last key
+point of the closed path) that follows. The optional parameter
+\meta{headlen} determines the length of the arrowhead. The default is
+the value of the \TeX{} dimension \cs{headlen}, initially \dim{3pt}. The
+optional parameter \meta{rotate} allows the arrowhead to be rotated
+anticlockwise around its point an angle of \meta{rotate} degrees. The
+default is 0. The optional parameter \meta{backset} allows the arrowhead
+to be `set back' from its original point, thus allowing e.g. double
+arrowheads. This parameter is in the form of a \TeX{} dimension---its
+default value is \dim{0pt}. If an arrowhead is both rotated and set
+back, the rotation affects the direction in which the arrowhead is set
+back. The optional \meta{color} defaults to \gbc{headcolor}. The
+optional parameters may appear in any order, but the indicated key
+character for each parameter must always appear.
+
+
+\subsection{Rendering macros}\label{rendering}
+
+\subsubsection{Drawing.}\label{drawing}
+
+When \mfp{} is loaded, the initial way in which figures are drawn
+is with a solid outline. That is, \cs{lines}\marg{(1,0),(1,1),(0,0)}
+will draw two solid lines connecting the points. When the macros in this
+section are used, any previously established default (see
+subsection~\ref{default} below) is overridden.
+
+\begin{cd}
+\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{plot}, \cs{plotnodes},
+and \cs{gendashed},
+
+\begin{cd}
+\cs{dashed}\oarg{\meta{length},\meta{space}}$\ldots$%
+\index{dashed@\cs{dashed}}
+\end{cd}
+
+Draws dashed segments along the path specified in the next command. 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\over n}$ of their value, where $n$ is the
+number of spaces appearing in the curve, in order to have the proper
+dashes at the ends. The dashes at the ends are half of \cs{dashlen}
+long.
+
+\begin{cd}
+\cs{dotted}\oarg{\meta{size},\meta{space}}$\ldots$%
+\index{dotted@\cs{dotted}}
+\end{cd}
+
+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}
+\cs{plot}\oarg{\meta{size},\meta{space}}\marg{\meta{symbol}}$\ldots$%
+\index{plot@\cs{plot}}
+\end{cd}
+
+Similar to \cs{dotted} except copies of \meta{symbol} are drawn along
+the path. Possible symbols are those listed under \cs{plotsymbol} in
+subsection~\ref{points}. The default \meta{size} is \cs{pointsize} and
+the default \meta{space} is \cs{symbolspace}, initially \dim{5pt}.
+
+\begin{cd}
+\cs{plotnodes}\oarg{\meta{size}}\marg{\meta{symbol}}$\ldots$%
+\index{plotnodes@\cs{plotnodes}}
+\end{cd}
+
+This places a symbol (same possibilities as in \cs{plotsymbol}, see
+subsection~\ref{points}) at each node of the path that follows. A node
+is one of the points through which \MF{} draws its curve. If one of the
+macros \cs{polyline}\marg{$\ldots$} or \cs{curve}\marg{$\ldots$}
+follows, each of the points listed is a node. In the \cs{datafile}
+command (below), each of the data points in the file is. In the function
+macros (below) 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}
+\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,
+there is a generalized dashing command. One must first establish a named
+dashing pattern with this command. \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{ex}
+ \cs{dashpattern}\marg{dotdash}\marg{0pt,4pt,3pt,4pt}.
+\end{ex}
+\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 space 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.
+
+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}
+\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
+command 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.
+
+
+\subsubsection{Shading, Filling, Erasing, Clipping,
+Hatching.}\label{filling}
+
+These macros can all be used to fill (or unfill) the interior of closed
+paths, even if the paths cross themselves. Filling an open curve is
+technically an error, but the \MF{} code responds by drawing the path
+and not doing any filling. These macros replace the default rendering:
+when they are used the outline will not be drawn unless an explicit
+prefix to do so is present.
+
+\begin{cd}
+\cs{gfill}\oarg{\meta{color}}$\ldots$%
+\index{gfill@\cs{gfill}}
+\end{cd}
+
+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}
+\cs{gclear}$\ldots$%
+\index{gclear@\cs{gclear}}
+\end{cd}
+
+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
+white, and so are most actual backgrounds, this is usually
+indistinguishable from clearing.
+
+\begin{cd}
+\cs{gclip}$\ldots$%
+\index{gclip@\cs{gclip}}
+\end{cd}
+
+Erases everything \emph{outside} the subsequent closed path from the
+picture (except text labels under some circumstances, see
+section~\ref{mplabels} and \ref{overlaylabels}).
+
+\begin{cd}
+\cs{shade}\oarg{\meta{shadesp}}$\ldots$%
+\index{shade@\cs{shade}}
+\end{cd}
+
+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.5pt}. 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 75\% of white.%
+ \footnote{If \cs{shadewd} is $w$ and \cs{shadespace} is $s$, then
+ the level of gray is $1 - (w/s)^2$, where $0$ denotes black and $1$
+ white.} %
+The \MF{} version attempts to optimize the dots to the pixel grid
+corresponding to the printers resolution (to avoid generating dither
+lines). Because this involves rounding, it will happen that values of
+\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}
+\cs{polkadot}\oarg{\meta{space}}$\ldots$%
+\index{polkadot@\cs{polkadot}}
+\end{cd}
+
+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{} all it does is fill 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{5pt}. The dots are colored with
+\index{fillcolor@\gbc{fillcolor}}\gbc{fillcolor}. In \MF, nonblack
+values of \gbc{fillcolor} will produce shaded dots.
+
+\begin{cd}
+\cs{thatch}\oarg{\meta{hatchsp},\meta{angle}}\oarg{\meta{color}}$\ldots$%
+\index{thatch@\cs{thatch}}
+\end{cd}
+
+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).
+
+\begin{cd}
+\cs{lhatch}\oarg{\meta{hatchsp}}\oarg{\meta{color}}$\ldots$%
+\index{lhatch@\cs{lhatch}}
+\end{cd}
+
+Draws lines shading in the subsequent closed path in a left-oblique
+hatched (upper left to lower right) pattern. It is exactly the same as
+\cs{thatch}\oarg{\meta{hatchsp},-45}\oarg{\meta{color}}$\ldots$
+
+\begin{cd}
+\cs{rhatch}\oarg{\meta{hatchsp}}\oarg{\meta{color}}$\ldots$%
+\index{rhatch@\cs{rhatch}}
+\end{cd}
+
+Draws lines shading in the subsequent closed path in a right-oblique
+hatched (lower left to upper right) pattern. It is exactly the same as
+\cs{thatch}\oarg{\meta{hatchsp},45}\oarg{\meta{color}}$\ldots$
+
+\begin{cd}
+\cs{hatch}\oarg{\meta{hatchsp}}\oarg{\meta{color}}$\ldots$\\
+\cs{xhatch}\oarg{\meta{hatchsp}}\oarg{\meta{color}}$\ldots$%
+\index{hatch@\cs{hatch}}%
+\index{xhatch@\cs{xhatch}}
+\end{cd}
+
+Draws lines shading in the subsequent closed path 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). Hatching at two different
+angles is, however, almost the only way to fill in two regions that
+\emph{automatically} shows the overlapping region.
+
+
+\subsubsection{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 strokes with pens, and fills
+
+\begin{cd}
+\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 and/or other \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.
+
+\subsubsection{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{shade}\cs{lclosed}\cs{lines}\marg{...}
+\end{ex}
+which shades inside a polygon and draws its outline; and
+\begin{ex}
+ \cs{shade}\cs{lclosed}\cs{draw}\cs{lines}\marg{...}
+\end{ex}
+which draws all of the outline \emph{except} the line segment supplied
+by \cs{lclosed}, then shades the interior. Thus, in the first case the
+path is defined (by \cs{lines}) then closed, then the resulting closed
+path is shaded, then drawn; while in the second case the order is:
+defined, drawn, closed, shaded. In particular, what is drawn is the path
+not yet closed.
+
+
+\subsection{Functions and Plotting.}\label{functions}
+
+In the following macros, expressions like $f(\mathtt{x})$, $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).
+
+\subsubsection{Defining Functions}\label{defining}
+
+\begin{cd}
+\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 names
+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 in
+the commands \mfc{begingroup} and \mfc{endgroup}. The \cs{fdef}
+command automatically supplies the grouping around the definition so
+the user need not type them if the entire \meta{mf-expr} is one such
+compound expression. \CMF{} functions can call \MF{} functions,
+even recursively.
+
+Many common functions have been predefined in \file{grafbase}. These
+include all the usual trig functions \mfc{tand}, \mfc{cotd}, \mfc{secd},
+\mfc{cscd}, which take angles in degrees, plus variants \mfc{sin},
+\mfc{cos}, \mfc{tan}, \mfc{cot}, \mfc{sec}, and \mfc{csc}, which take
+angles in radians. Some inverse trig functions are also available, the
+following produce angles in degrees: \mfc{asin}, \mfc{acos}, and
+\mfc{atan}, and the following in radians: \mfc{invsin}, \mfc{invcos},
+\mfc{invtan}. The exponential and hyperbolic functions: \mfc{exp},
+\mfc{sinh}, \mfc{cosh}, \mfc{tanh}, and their inverses \mfc{ln} (or
+\mfc{log}), \mfc{asinh}, \mfc{acosh}, and \mfc{atanh} are also defined.
+
+\subsubsection{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.
+
+\begin{cd}
+\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}
+
+Plots $f(\mathtt{x})$, 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{ex}
+\cs{function}\marg{0,pi,pi/10}\marg{sin x}
+\end{ex}
+draws the graph of $\sin x$ between 0 and $\pi$.
+
+\begin{cd}
+\cs{parafcn}\oarg{\meta{spec}}\marg{\meta{$t_{\mathrm{min}}$},%
+ \meta{$t_{\mathrm{max}}$},\meta{$\Delta t$}}%
+ \marg{\meta{pfcn}}%
+\index{parafcn@\cs{parafcn}}
+\end{cd}
+
+Plots the parametric path determined by \meta{pfcn}, where \meta{pfcn}
+is a \MF{} function or expression of one numeric argument \texttt{t},
+returning a \MF{} \emph{pair}. Or a pair of numeric expressions
+$(x(\mathtt{t}),y(\mathtt{t}))$ enclosed in parentheses and separated by
+a comma. The default \meta{spec} is \texttt{s}. For example
+\begin{ex}
+\cs{parafcn}\marg{0,1,.1}\marg{(2t, t + t*t)}
+\end{ex}
+plots a smooth parabola from $(0,0)$ to $(2,2)$.
+
+\begin{cd}
+\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}
+
+Plots the polar function determined by $r=f(\theta)$, where $f$ is a
+\MF{} numeric function or expression of one numeric argument, and
+$\theta$ varies from \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{ex}
+\cs{plrfcn}\marg{0,90,5}\marg{sind (2t)}
+\end{ex}
+draws one loop of a 4-petal rosette. If one needs radian measures, use
+something like the following.
+\begin{ex}
+\cs{plrfcn}\marg{0,pi*radian,pi*radian/18}\marg{sin (2t/radian)}
+\end{ex}
+
+
+\begin{cd}
+\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})$}%
+\index{btwnfcn@\cs{btwnfcn}}
+\end{cd}
+
+Draws the region between the two functions $f(x)$ and $g(x)$, these
+being numeric functions of one numeric argument \texttt{x}. The region is
+bounded also by the vertical lines at \meta{$x_{\mathrm{min}}$} and \meta{$x_{\mathrm{max}}$}.
+Unlike the previous function macros, the default \meta{spec} is
+\texttt{p}---this macro is intended to be used for shading between drawn
+functions, a task for which smoothness is usually unnecessary.
+For example
+\begin{ex}
+\cs{shade}\cs{btwnfcn}\marg{0,180,5}\marg{0}\marg{sind x}
+\end{ex}
+shades the area between first crest of a sine wave and the x-axis.
+
+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}
+
+\begin{cd}
+\cs{plrregion}\oarg{\meta{spec}}%
+ \marg{\meta{$\theta_{\mathrm{min}}$},\meta{$\theta_{\mathrm{max}}$},%
+ \meta{$\Delta\theta$}}\marg{$f(\mathtt{t})$}%
+\index{plrregion@\cs{plrregion}}
+\end{cd}
+
+Plots the polar region determined by $r=f(\theta)$, where $f$ is a \MF{}
+numeric function of one numeric argument \texttt{t}. The $\theta$
+values are angles (measured in \emph{degrees}), varying from
+\meta{$\theta_{\mathrm{min}}$} to \meta{$\theta_{\mathrm{max}}$} in
+steps of \meta{$\Delta\theta$}. In the expression $f(\mathtt{t})$, the
+\texttt{t} stands for $\theta$. The region is also bounded by the angles
+\meta{$\theta_{\mathrm{min}}$} and \meta{$\theta_{\mathrm{max}}$}, i.e.
+by the line segments joining the origin to the endpoints of the
+function. The default \meta{spec} is \texttt{p} ---this macro is
+intended to be used for shading a region with the boundary drawn, a task
+for which smoothness is usually unnecessary. For example
+\begin{ex}
+\cs{shade}\cs{plrregion}\marg{0,90,5}\marg{sind (2t)}
+\end{ex}
+shades one loop of the 4-petal rosette.
+
+
+\subsubsection{Plotting external data files}\label{external}
+
+\begin{cd}
+\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}
+
+\cs{datafile} defines 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 \meta{spec} is changed
+to \texttt{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 \meta{spec} to
+\texttt{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{ex}
+ \cs{point}\cs{datafile}\marg{ptlist.dat}
+\end{ex}
+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 of \mfp{} macros that allow this usage of
+\cs{datafile}\index{datafile@\cs{datafile}}:
+
+ \begin{raggedright}
+\begin{itemize}
+\item Numeric data: \cs{piechart}, \cs{barchart}, \cs{numericarray}, and
+ all the axis marks commands.
+\item Point or vector data: \cs{point}, \cs{plotsymbol}, \cs{polyline},
+ \cs{polygon}, \cs{fcncurve}, \cs{curve}, \cs{cyclic}, \cs{turtle},
+ \cs{qspline}, \cs{closedqspline}, \cs{cspline}, \cs{closedcspline},
+ \cs{mfbezier}, \cs{closedmfbezier}, \cs{qbeziers},
+ \cs{closedqbeziers}, and \cs{pairarray}.
+\end{itemize}
+
+ \end{raggedright}
+
+\begin{cd}
+\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}
+\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 (i.e., space separated numbers, the first two determining each
+point) correspond to the setting
+\begin{ex}
+\cs{using}\marg{\#1 \#2 \#3}\marg{(\#1,\#2)}
+\end{ex}
+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}
+\cs{sequence}\index{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}
+\cs{usingpairdefault}\\
+\cs{usingnumericdefault}%
+\index{usingpairdefault@\cs{usingpairdefault}}%
+\index{usingnumericdefault@\cs{usingnumericdefault}}
+\end{cd}
+
+The command \cs{usingpairdefault} restores the above default for pair
+data. The command \cs{usingnumericdefault} is the equivalent of
+\cs{using}\marg{\#1 \#2}\marg{\#1}.
+
+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 example shows how to overcome this:
+\begin{verbatim}
+ \makepercentother
+ \using{#1% #2 #3}{(#1/100,#2)}
+ \makepercentcomment
+\end{verbatim}
+
+
+Here\index{makepercentother@\cs{makepercentother}}%
+\index{makepercentcomment@\cs{makepercentcomment}}
+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.
+
+\begin{cd}
+ \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}
+\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} changes to cycling through eight different
+colors starting with black (hey, black is a color too). This has an
+effect only for \MP. The sole exception to the general rule that all
+curves are drawn in \gbc{drawcolor} is the \cs{plotdata} command after
+\cs{coloredlines} has been issued. The command \cs{pointedlines} causes
+\cs{plotdata} to use \cs{plot} commands, cycling through nine symbols.
+The command \cs{datapointsonly} causes \cs{plotdata} to use
+\cs{plotnodes}\marg{\meta{symbol}} commands to plot the data points
+only. (See the Appendix for more details.) The command \cs{dashedlines}
+restores the default. If, for some reason, you do not like the default
+starting line style (say you want to start with a color other than
+black), you can use one of the following commands.
+
+\begin{cd}
+\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 the Appendix 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 dashess, colors, or symbols.
+
+\begin{cd}
+\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
+change: \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{} expressions of type color, and the symbols can be
+expressions of type path. Within a \env{mfpic} environment, the changes
+made are local to that environment. Outside, they affect all subsequent
+environments.
+
+\begin{cd}
+\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.
+
+\subsection{Labels and Captions.}\label{labels}
+
+\subsubsection{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}
+\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}
+
+Places \TeX{} labels on the graph. (Not to be confused with \LaTeX's
+\cs{label} command.) 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.
+In fact, the second syntax may be used if \opt{mplabels} is in effect,
+where \meta{pair-list} is any expression recognized as a pair by \MP, or
+a comma-separated list of such pairs.
+
+The optional parameter \oarg{\meta{just}} specifies the
+\emph{justification}, the relative placement of the label with respect
+to the point \parg{\meta{x},\meta{y}}. It is a two-character sequence
+where 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}.
+
+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{gclear} or
+\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}.
+
+\begin{cd}
+\cs{everytlabel}\marg{\meta{\TeX-code}}%
+\index{everytlabel@\cs{everytlabel}}
+\end{cd}
+
+One problem with multi-line \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{ex}
+ \cs{everytlabel}\marg{\cs{bf}\cs{baselineskip} 10pt}
+\end{ex}
+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 the lines
+of a tlabel are wrapped in a box, but the commands of \cs{everytlabel}
+are outside all of them, so no actual text should be produced by these
+commands.
+
+Using \cs{tlabel} without an optional argument is equivalent to
+specifying \oarg{Bl}. Use the following command to change this
+behavior.
+
+\begin{cd}
+\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. Without
+\opt{mplabels}, the rotation is ignored by \cs{tlabel} .
+
+\begin{cd}
+\cs{tlabeloffset}\marg{\meta{hlen}}\marg{\meta{vlen}}\\
+\cs{tlabelsep}\marg{\meta{len}}%
+\index{tlabeloffset@\cs{tlabeloffset}}%
+\index{tlabelsep@\cs{tlabelsep}}
+\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{tlabelsep} command causes labels to be shifted by the given
+amount in a direction that depends on the optional positioning
+parameter. For example, if the first letter is \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, but the value is
+also written to the output file for use by \cs{tlabelrect}
+(subsection~\ref{surrounding}) and related
+commands.
+
+\begin{cd}
+\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{tlabelsep} 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}
+\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. It simply issues multiple \cs{tlabel} commands with
+the same text and optional parameter, but at the different points
+listed. This is intended to plot a set of points with a single letter or
+font symbol (instead of a \MF{} generated shape). Like \cs{axislabels},
+this does not respond to the setting of \cs{tlabeljustify}. It has a
+default setting of \oarg{cc} if the optional argument is omitted. The
+points may be MetaPost pair expressions under \opt{mplabels}, but they
+must \emph{not} be individually enclosed in braces. (This requirement is
+new with version 0.7; prior to that pairs in braces didn't work reliably
+anyway.) This command is actually unnecessary under \opt{mplabels} as
+the plain \cs{tlabel} command can then be given a list of points. The
+\cs{tlabel} command is more efficient, and \cs{plottext} is converted to
+it internally.
+
+\begin{cd}
+\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 issued before \cs{opengraphsfile}, its contents are saved
+and written by that command. 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}.
+
+\begin{cd}
+\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} typesets its
+argument twice (as does \LaTeX's \cs{caption}), the first time to test
+its width, the second time for real. Therefore, the user is advised
+\emph{not} to include any global assignments in the caption text.
+
+If the \cs{tcaption} and graph have different widths, the two are
+centered relative to each other. If the \cs{tcaption} takes multiple
+lines, then the lines are both left- and right-justified (except for the
+last line), but the first line is not indented. If the option
+\opt{centeredcaptions} is in effect, each line of the caption will be
+centered.
+
+In a \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.
+
+\subsubsection{Curves surrounding text}\label{surrounding}
+
+
+\begin{cd}
+\cs{tlabelrect}\oarg{\meta{rad}}\oarg{\meta{just}}%
+ \meta{pair}\marg{\meta{text}}\\
+\cs{tlabelrect*...}%
+\index{tlabelrect@\cs{tlabelrect}}
+\end{cd}
+
+This 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 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 parameter 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{tlabelsep}. 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
+`\texttt{*}-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}
+\cs{tlabeloval}\oarg{\meta{mult}}\oarg{\meta{just}}%
+ \meta{pair}\marg{\meta{text}}\\
+\cs{tlabeloval*...}%
+\index{tlabeloval@\cs{tlabeloval}}
+\end{cd}
+
+This is similar to \cs{tlabelrect}, except it draws 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}
+\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}
+
+Draws 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
+take 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}
+\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}.
+
+
+\subsection{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}
+\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}}.
+
+\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.
+
+
+\subsection{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 name and number (and any \TeX{} labels). The command(s) used
+internally to do this are made available to the user.
+
+\begin{cd}
+\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 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 the \cs{begin}\marg{mfpframe} $\ldots$ \cs{end}\marg{mfpframe}
+syntax.
+
+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/command of the user's
+choice or devising.
+
+
+\subsection{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.
+
+
+\subsubsection{Affine Transforms of the \MF{} Coordinate
+System.}\label{affine}
+
+\begin{cd}
+\cs{coords} $\ldots$
+\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
+
+\emph{Note}: In \LaTeX, a \env{coords} environment may be used.
+
+\medskip
+Transforms provided by \mfp.
+
+\medskip
+\halign
+{#\hfil&\quad#\hfil\cr
+ \cs{rotate}\marg{\meta{$\theta$}}%
+ \index{rotate@\cs{rotate}}%
+ & Rotates around origin by \meta{$\theta$} degrees \cr
+ \cs{rotatearound}\marg{\meta{point}}\marg{\meta{$\theta$}}%
+ \index{rotatearound@\cs{rotatearound}}%
+ & Rotates around point \meta{point} by \meta{$\theta$} degrees \cr
+ \cs{turn}\oarg{\meta{point}}\marg{\meta{$\theta$}}%
+ \index{turn@\cs{turn}}%
+ & Rotates around point \meta{point} (origin is default) by
+ \meta{$\theta$} \cr
+ \cs{mirror}\marg{\meta{$p_1$}}\marg{\meta{$p_2$}}%
+ \index{mirror@\cs{mirror}}%
+ & Same as \cs{reflectabout}\cr
+ \cs{reflectabout}\marg{\meta{$p_1$}}\marg{\meta{$p_1$}}%
+ \index{reflectabout@\cs{reflectabout}}%
+ & Reflect about the line \meta{$p_1$}\texttt{--}\meta{$p_2$} \cr
+ \cs{shift}\marg{\meta{pair}}%
+ \index{shift@\cs{shift}}%
+ & Shifts origin by the vector \meta{pair} \cr
+ \cs{scale}\marg{\meta{s}}%
+ \index{scale@\cs{scale}}%
+ & Scales uniformly by a factor of \meta{s} \cr
+ \cs{xscale}\marg{\meta{s}}%
+ \index{xscale@\cs{xscale}}%
+ & Scales only the X coordinates by a factor of \meta{s} \cr
+ \cs{yscale}\marg{\meta{s}}%
+ \index{yscale@\cs{yscale}}%
+ & Scales only the Y coordinates by a factor of \meta{s} \cr
+ \cs{zscale}\marg{\meta{pair}}%
+ \index{zscale@\cs{zscale}}%
+ & Scales uniformly by magnitude of \meta{pair}, and rotates by angle
+ of \meta{pair} \cr
+ \cs{xslant}\marg{\meta{s}}%
+ \index{xslant@\cs{xslant}}%
+ & Skew in $X$ direction by the multiple \meta{s} of $Y$ \cr
+ \cs{yslant}\marg{\meta{s}}%
+ \index{yslant@\cs{yslant}}%
+ & Skew in $Y$ direction by the multiple \meta{s} of $X$ \cr
+ \cs{zslant}\marg{\meta{pair}}%
+ \index{zslant@\cs{zslant}}%
+ & See \mfc{zslanted} in \file{grafdoc.tex} \cr
+ \cs{boost}\marg{\meta{$\chi$}}%
+ \index{boost@\cs{boost}}%
+ & Special relativity boost by $\chi$, see \mfc{boost} in
+ \file{grafdoc.tex} \cr
+ \cs{xyswap}%
+ \index{xyswap@\cs{xyswap}}%
+ & Exchanges the values of $x$ and $y$. \cr}%
+
+An arbitrary \MF{} transformation can be implemented with
+
+\begin{cd}
+\cs{applyT}\marg{\meta{transformer}}%
+\index{applyT@\cs{applyT}}
+\end{cd}
+
+This is mainly for \MF{} hackers. This applies the \MF{}
+\meta{transformer} to the current coordinate system. For example, the
+\mfp{} \TeX{} macro \cs{zslant\#1} is implemented as
+\cs{applyT}\marg{zslanted \#1} where the argument \mfc{\#1} is a \MF{}
+pair, such as $(x,y)$. Any code that satisfies \MF's syntax for a
+\meta{transformer} (see D.~E.~Knuth, ``The \MF book'') is permitted,
+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:
+$T_1 T_2 z$ usually means to apply $T_1$ to the result of $T_2 z$).
+
+
+\subsubsection{Transformation of 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}
+\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 or 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{ex}
+\cs{store}\marg{pth}\cs{lclosed}\cs{reverse}%
+ \cs{curve}\marg{(0,0),(1,0),(1,1)})
+\end{ex}
+
+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 is special in that it is the only
+prefix macro that allows the following path to be an argument, that is,
+enclosed in braces. This is solely to support past \mfp{} versions in
+which \cs{store} was \emph{not} defined as a prefix macro.
+
+\begin{cd}
+\cs{mfobj}\marg{\meta{path expression}}\\
+\cs{mpobj}\marg{\meta{path expression}}%
+\index{mfobj@\cs{mfobj}}\index{mpobj@\cs{mpobj}}
+\end{cd}
+
+The \meta{path expression} is a previously stored path variable, or a
+valid \MF{} (or \MP) expression combining such variables and/or constant
+paths. This allows the use of path variables or expressions as figure
+macros, permitting all prefix operations, etc.. Here's some
+oversimplified uses of \cs{store} and \cs{mfobj}:
+
+\nobreak
+\begin{verbatim}
+\store{my_f}{\circle{...}} % Store a circle.
+\dotted\mfobj{my_f} % Now draw it dotted,
+\hatch\mfobj{my_f} % and hatch its interior
+% Store two curves:
+\store{my_f}{\curve{...}}
+\store{my_g}{\curve{...}}
+% Store two combinations of them:
+\store{my_h}{\mfobj{my_f--my_g--cycle}} % a MF path expression
+\store{my_k}{%
+ \lclosed\connect % a combination path created from
+ \mfobj{my_f}\mfobj{my_g} % mfpic commands.
+ \endconnect}
+\dotted\mfobj{my_f} % Draw the first dotted,
+\dotted\mfobj{my_g} % then the second.
+\shade\mfobj{my_h} % Now shade one combination.
+\hatch\mfobj{my_k} % and hatch the other
+\end{verbatim}
+The two forms \cs{mfobj} and \cs{mpobj} are absolutely equivalent.
+
+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 recent sequence of prefix macros and
+figure.
+
+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, \mfp{} prefix macros
+have an input and an output and a side effect. The input is the output
+of whatever follows it, the output can be the same as the input (the
+case for rendering prefixes) or modified version of that (the closure
+prefixes). The side effect is the drawing (dashing, filling) of the path,
+appending of an arrowhead, etc.. These side effects have to know where
+to place their marks, so a computation is invoked that converts the
+user's graph coordinates into \MF's drawing coordinates. The previous
+transformation macros work by modifying the parameters used in this
+computation.
+
+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 (other than invoking the default rendering if no
+rendering prefix was previously provided).
+
+\begin{cd}
+\cs{rotatepath}\marg{(\meta{x},\meta{y}),\meta{$\theta$}}$\ldots$\\
+\cs{shiftpath}\marg{(\meta{dx},\meta{dy})}$\ldots$\\
+\cs{scalepath}\marg{(\meta{x},\meta{y}),\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}
+
+\cs{rotatepath} rotates the following path by \meta{$\theta$} degrees
+about point \mfc{(\meta{x},\meta{y})}. After the commands:
+\begin{ex}
+ \cs{store}\marg{xx}\marg{\cs{rotatepath}\marg{(0,0), 45}%
+ \cs{rect}\marg{(0,0),(1,1)}}
+\end{ex}
+the object \cs{mfobj}\marg{xx} contains an actual rotated rectangle, as
+drawing it will prove. The above macro, and the five that follow are
+extremely useful (and better than \env{coords} environments) if one
+needs to draw a figure, together with many slightly different versions
+of it.
+
+\cs{shiftpath} shifts the following path by the horizontal amount
+\meta{dx} and the vertical amount \meta{dy}.
+
+\cs{scalepath} scales (magnifies or shrinks) the following path by the
+factor \meta{s}, in such a way that the point \parg{\meta{x},\meta{y}}
+is kept fixed. That is
+\begin{ex}
+ \cs{scalepath}\marg{(0,0),2}\cs{rect}\marg{(0,0),(1,1)}
+\end{ex}
+is essentially the same as \cs{rect}\marg{(0,0),(2,2)}, while
+\begin{ex}
+ \cs{scalepath}\marg{(1,1),2}\cs{rect}\marg{(0,0),(1,1)}
+\end{ex}
+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. 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 (so that after a
+swap, verticals become horizontal and horizontals become vertical). One
+cannot have both when the scales are different.
+
+For \MF{} or \MP{} power users, \cs{transformpath} can take any
+`transformer' and transform the following path with it. Here, a
+\emph{transformer} is anything that can follow a path and create a new
+path. Examples are \mfc{scaled}, \mfc{shifted (1,1)}, and \mfc{rotatedabout
+(0,1)}.
+
+All these prefixes change only the path that follows, not any rendering
+of it that follows. For example:
+\begin{ex}
+ \cs{gfill}\cs{rotatepath}\marg{(0,0),90}\cs{dashed}%
+ \cs{rect}\marg{(0,0),(1,1)}
+\end{ex}
+will not produce a rotated dashed rectangle. Rather the original
+rectangle will be dashed, and the rotated rectangle will be filled.
+
+
+\subsection{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 to
+\TeX{} groups only if set inside an \env{mfpic} environment 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 then
+consistent.
+
+\begin{cd}
+\cs{mfpicunit}%
+\index{mfpicunit@\cs{mfpicunit}}
+\end{cd}
+
+This \TeX{} 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 default value is \dim{1pt}.
+
+\begin{cd}
+\cs{pointsize}%
+\index{pointsize@\cs{pointsize}}
+\end{cd}
+
+This \TeX{} dimension stores the diameter of the circle drawn by the
+\cs{point} macro and the diameter of the symbols drawn by
+\cs{plotsymbol} and by \cs{plot}. The default value is \dim{2pt}.
+
+\begin{cd}
+\cs{pointfilltrue} and \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 default is \texttt{true}: filled. This value is local to any \TeX{}
+group inside an \env{mfpic} environment. Outside such it is global.
+
+\begin{cd}
+\cs{pen}\marg{\meta{drawpensize}}\\
+\cs{drawpen}\marg{\meta{drawpensize}}\\
+\cs{penwd}\marg{\meta{drawpensize}}%
+\index{pen@\cs{pen}}%
+\index{drawpen@\cs{drawpen}}%
+\index{penwd@\cs{penwd}}
+\end{cd}
+
+Establishes the width of the normal drawing pen. The default is
+\dim{0.5pt}. This width is stored by \MF. The shading dots and hatching
+pen are unaffected by this. There exist three aliases for this command,
+the first two to maintain backward compatibility, the last one for
+consistency with other dimension changing commands. Publishers generally
+recommended authors to use at least a width of one-half point for
+drawings submitted for publication.
+
+\begin{cd}
+\cs{shadewd}\marg{\meta{dotdiam}}%
+\index{shadewd@\cs{shadewd}}
+\end{cd}
+
+Sets the diameter of the dots used in the shading macro. The drawing and
+hatching pens are unaffected by this. The default is \dim{0.5pt}, and
+the value is stored by \MF.
+
+\begin{cd}
+\cs{hatchwd}\marg{\meta{hatchpensize}}%
+\index{hatchwd@\cs{hatchwd}}
+\end{cd}
+
+Sets the line thickness used in the hatching macros. The drawing pen and
+shading dots are unaffected by this. The default is \dim{0.5pt}, and the
+value is stored by \MF.
+
+\begin{cd}
+\cs{polkadotwd}\marg{\meta{polkadotdiam}}%
+\index{polkadotwd@\cs{polkadotwd}}
+\end{cd}
+
+Sets the diameter of the dots used in the \cs{polkadot} macro. The
+default is \dim{5pt}, and the value is stored by \MF.
+
+\begin{cd}
+\cs{headlen}%
+\index{headlen@\cs{headlen}}
+\end{cd}
+
+This \TeX{} dimension stores the length of the arrowhead drawn by
+the \cs{arrow} macro. The default value is \dim{3pt}.
+
+\begin{cd}
+\cs{axisheadlen}%
+\index{axisheadlen@\cs{axisheadlen}}
+\end{cd}
+
+This \TeX{} 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}.
+
+\begin{cd}
+\cs{sideheadlen}%
+\index{sideheadlen@\cs{sideheadlen}}
+\end{cd}
+
+This \TeX{} 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 default value is \dim{0pt}.
+
+\begin{cd}
+\cs{headshape}\marg{\meta{hdwdr}}\marg{\meta{hdten}}\marg{\meta{hfilled}}%
+\index{headshape@\cs{headshape}}
+\end{cd}
+
+Establishes the shape of the arrowhead drawn by the \cs{arrow} and
+\cs{axes} macros. The value of \meta{hdwdr} is the ratio of the width of
+the arrowhead to its length; \meta{hdten} is the tension of the B\'ezier
+curves; and \meta{hfilled} is a \MF{} boolean value indicating whether
+the arrowheads are to be filled (if \mfc{true}) or open. The default
+values are $1$, $1$, \mfc{false}, respectively. The \meta{hdwdr},
+\meta{hdten} and \meta{hfilled} values are stored by \MF. Setting
+\meta{hdten} to `\mfc{infinity}' will make the sides of the arrowheads
+straight lines. These values are all stored by \MF.
+
+\begin{cd}
+\cs{dashlen}, \cs{dashspace}%
+\index{dashlen@\cs{dashlen}}
+\end{cd}
+
+These \TeX{} 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\over{n}$ of their value, where $n$ is the
+number of spaces appearing in the curve, in order not to have partial
+dashes at the ends. The default values are both \dim{4pt}. The dashes
+will actually be longer (and the spaces shorter) by the thickness of the
+pen used when they are drawn.
+
+\begin{cd}
+\cs{dashlineset},
+\cs{dotlineset}%
+\index{dashlineset@\cs{dashlineset}}%
+\index{dotlineset@\cs{dotlineset}}
+\end{cd}
+
+These macros provide convenient standard settings for the \cs{dashlen}
+and \cs{dashspace} dimensions. The macro \cs{dashlineset} sets both
+values to \dim{4pt}; the macro \cs{dotlineset} sets \cs{dashlen} to
+\dim{1pt} and \cs{dashspace} to \dim{2pt}.
+
+\begin{cd}
+\cs{hashlen}%
+\index{hashlen@\cs{hashlen}}
+\end{cd}
+
+This \TeX{} dimension stores the length of the axis hash marks drawn by
+the \cs{xmarks} and \cs{ymarks} macros. The default value is \dim{4pt}.
+
+\begin{cd}
+\cs{shadespace}%
+\index{shadespace@\cs{shadespace}}
+\end{cd}
+
+This \TeX{} dimension establishes the spacing between dots drawn by the
+\cs{shade} macro. The default value is \dim{1pt}.
+
+\begin{cd}
+\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.
+
+\begin{cd}
+\cs{polkadotspace}%
+\index{polkadotspace@\cs{polkadotspace}}
+\end{cd}
+
+This \TeX{} dimension establishes the spacing between the centers of the
+dots used in the macro \cs{polkadot}. The default is \dim{10pt}.
+
+\begin{cd}
+\cs{dotsize}, \index{dotspace@\cs{dotspace}}\cs{dotspace}%
+\index{dotsize@\cs{dotsize}}
+\end{cd}
+
+These \TeX{} dimensions establishes the size and spacing between the
+centers of the dots used in the \cs{dotted} macro. The defaults are
+\dim{0.5pt} and \dim{3pt}.
+
+\begin{cd}
+\cs{symbolspace}%
+\index{symbolspace@\cs{symbolspace}}
+\end{cd}
+
+Similar to \cs{dotspace}, this \TeX{} dimension establishes the space
+between symbols placed by the macro
+\cs{plot}\marg{\meta{symbol}}$\ldots\,$. Its default is \dim{5pt}.
+
+\begin{cd}
+\cs{hatchspace}%
+\index{hatchspace@\cs{hatchspace}}
+\end{cd}
+
+This \TeX{} dimension establishes the spacing between lines drawn by the
+\cs{hatch} macro. The default value is \dim{3pt}.
+
+\begin{cd}
+\cs{tlabelsep}\marg{\meta{separation}}%
+\index{tlabelsep@\cs{tlabelsep}}
+\end{cd}
+
+This 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}. It also sets the
+separation between the text and the curve defined by the commands
+\cs{tlabelrect}, \cs{tlabeloval} or \cs{tlabelellipse}. The default is
+\dim{0pt}. The value is 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 default is to have both horizontal
+and vertical offsets of \dim{0pt}. The values are stored by both \TeX{}
+and \MF.
+
+\begin{cd}
+\cs{mfpdataperline}%
+\index{mfpdataperline@\cs{mfpdataperline}}
+\end{cd}
+
+When \mfp{} is reading data from files and writing it to the
+output file, this macro stores the maximum number of points that will be
+written on a single line in the output file. Its default is defined by
+\cs{def}\cs{mfpdataperline}\marg{5}.
+
+\begin{cd}
+\cs{mfpicheight},
+\cs{mfpicwidth}%
+\index{mfpicheight@\cs{mfpicheight}}%
+\index{mfpicwidth@\cs{mfpicwidth}}
+\end{cd}
+
+These \TeX{} dimensions store the height and width of the figure created
+by the most recently completed \env{mfpic} environment. This might
+perhaps be of interest to hackers or to aid in precise positioning of
+the graphics. They are meant to be read-only: the \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.
+
+
+\subsection{For Advanced Users.}\label{advanced}
+
+\subsubsection{Power Users.}\label{power}
+
+
+\begin{cd}
+\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 are alternate ways of defining curves. In each case, \meta{list}
+is a comma separated list of points. 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.
+
+\begin{cd}
+\cs{cbclosed}$\ldots$\\
+\cs{qbclosed}$\ldots$%
+\index{cbclosed@\cs{cbclosed}}%
+\index{qbclosed@\cs{qbclosed}}
+\end{cd}
+
+These are prefix macros for closing curves. 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.
+
+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}
+ \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}
+
+This connects the points in the list with the path join operator
+\mfc{..tension \meta{tens}..}. 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}
+ \cs{qbeziers}\oarg{\meta{tens}}\marg{\meta{list}}\\
+ \cs{closedqbeziers}\oarg{\meta{tens}}\marg{\meta{list}}%
+\index{qbeziers@\cs{qbeziers}}
+\index{closedqbeziers@\cs{closedqbeziers}}
+\end{cd}
+
+Note the plural, to indicate that they will draw a 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. The curve
+will not automatically be smooth. That depends on the choice of the
+control points.
+
+
+\begin{cd}
+\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 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 realistic example.
+
+\begin{cd}
+\cs{setmfvariable}\marg{\meta{type}}\marg{\meta{name}}\marg{\meta{value}}\\
+\cs{setmpvariable}\marg{\meta{type}}\marg{\meta{name}}\marg{\meta{value}}%
+\index{setmfvariable@\cs{setmfvariable}}
+\index{setmpvariable@\cs{setmpvariable}}
+\end{cd}
+
+These formerly internal \mfp{} macros can be use to define symbolic
+names for any \MF{} or \MP{} variable type. They are interchangeable;
+you can use either one with or without the \opt{metapost} option.
+As an example of their use, since dimensions are numeric data types in
+\MF, the command
+\begin{ex}
+ \cs{setmfvariable}\marg{numeric}\verb${my_dim}$\marg{7pt}
+\end{ex}
+would set the \MF{} variable \verb$my_dim$ to the value \texttt{7pt}.
+After that, \verb$my_dim$ can be used in any \emph{drawing} command
+where a dimension is required:
+\begin{ex}
+ \cs{plotsymbol}\verb$[my_dim]$\marg{Triangle}\cs{rect}\marg{(0,0),(1,1)}
+\end{ex}
+will plot the rectangle with small triangles spaced \dim{7pt} apart.
+
+You can define paths this way
+(\cs{setmfvariable}\marg{path}\marg{X}\marg{(0,0)..(1,1)..(0,1)}), but
+the \meta{value} has to be valid \MF{} path construction syntax,
+\emph{not} something like \cs{rect}\marg{$\ldots$}. You need \cs{store}
+if you want to set a variable to an \mfp{} path. However, defined either
+way, they can be used in \cs{mfobj}.
+
+A variable defined this way is local to the \env{mfpic} environment it
+is contained in. It is in fact local to any \MF{} group. In \mfp, only
+\cs{connect} {\dots} \cs{endconnect} and \cs{mfpic} {\dots}
+\cs{endmfpic} create \MF{} groups in the graph file.
+
+\begin{cd}
+\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 the mfpic environment. This is useful if all
+one wishes to do in the current \env{mfpic} environment is to make
+\emph{tiles} (see below).
+
+\begin{cd}
+\cs{patharr}\marg{\meta{pv}}$\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{pv}. 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. The
+definitions it makes are, however, 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}
+\cs{pairarray}\marg{\meta{var}}{\meta{list-of-points}}\\
+\cs{numericarray}\marg{\meta{var}}{\meta{list-of-numbers}}%
+\index{pairarray@\cs{pairarray}}%
+\index{numericarray@\cs{numericarray}}
+\end{cd}
+
+These enable the simultaneous definition of pair and numeric 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. If a numeric 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. The arrays are
+defined locally if these commands occur in an \env{mfpic} environment,
+global otherwise. In all arrays, the variable \gbc{X} itself (not
+followed by any digit or brackets) is a number equal to the number of
+elements in the array.
+
+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.
+
+Several commands in \mfp{} define arrays of objects that can be used in
+other commands. The main ones are \cs{piechart} and \cs{barchart}. These
+arrays are always global. Using \cs{piechart} causes the following
+arrays to become defined:
+\begin{itemize}
+ \item \gbc{piewedge}, a path array describing the wedges of the chart.
+ The command \cs{piewdge}\marg{\meta{num}} (without optional
+ argument) is almost exactly the same as
+ \cs{mfobj}\marg{piewedge[\meta{num}]}.
+ \item \gbc{pieangle}, a numeric array, the starting angle of each wedge.
+ \item \gbc{piedirection}, a pair array, the unit vectors pointing in
+ the directions of the centers of the wedges. If \cs{pieangle1}
+ is 0 and \gbc{pieangle2} is 90 degrees, then \gbc{piedirection1}
+ is $(\cos 45,\sin 45)$.
+\end{itemize}
+
+Using \cs{barchart} causes the following arrays to become defined. The
+exact meaning depends on whether bars are horizontal or vertical. The
+following describes horizontal bars; interchange the roles of $x$ and
+$y$ if they are vertical:
+\begin{itemize}
+ \item \gbc{barstart}, the position on the $y$-axis of the leading edge
+ of the bars.
+ \item \gbc{barbegin}, the $x$-coordinate of the leftmost end of the
+ bars.
+ \item \gbc{barend}, the $x$-coordinate of the rightmost end of the
+ bars.
+ \item \gbc{chartbar}, the rectangular path of the bar; \gbc{chartbar1}
+ is the rectangle with corners at \gbc{(barbegin1,barstart1)} and
+ \gbc{(barend1,barstart+barwd)}, where \gbc{barwd} is the
+ width (thickness) of the bar.
+ \item \gbc{barlength}, the same as \gbc{barend}. This is for backward
+ compatibility; the was name chosen at a time when all the bars
+ had one side on an axis (i.e., \gbc{barbegin[n] = 0}).
+\end{itemize}
+
+\begin{cd}
+\cs{tile}\marg{\meta{tilename},\meta{unit},\meta{wd},\meta{ht},\meta{clip}}\\
+ \ $\ldots$\\
+\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. The units of drawing are given by
+\meta{unit}, which should be a 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 all drawing is clipped to be within the tile's boundary.
+
+By using this macro, you can design your own fill patterns (to use them,
+see the \cs{tess} macro below), but please take some care with the
+\ae sthetics! The \meta{tilename} is globally defined by this command.
+
+\begin{cd}
+\cs{tess}\marg{\meta{tilename}}$\ldots$%
+\index{tess@\cs{tess}}
+\end{cd}
+
+Tile the interior of a closed path with a tessellation comprised of
+copies of the \emph{tile} specified by \meta{tilename}. There is no
+default \meta{tilename}; you must make all your own tiles. Tiling an
+open curve is technically an error, but the \MF{} code responds by
+drawing the path and not doing any tiling.
+
+Tiling large regions with complicated tiles can exceed the capacity of
+some versions of \MP. There is less of a problem with \MF. This is not
+because \MF{} has greater capacity, but because of the natural
+difference between bitmaps and vector graphics.
+
+In \MP, the tiles are copied with whatever color they are given when
+they are defined. They can be multicolored.
+
+\begin{cd}
+\cs{cutoffafter}\marg{\meta{obj}}\dots\\
+\cs{cutoffbefore}\marg{\meta{obj}}\dots\\
+\cs{trimpath}\marg{\meta{dim$_1$},\meta{dim$_2$}}\dots\\
+\cs{trimpath}\marg{\meta{dim$_1$}}\dots\\
+\index{cutoffafter@\cs{cutoffafter}}%
+\index{cutoffbefore@\cs{cutoffbefore}}%
+\index{trimpath@\cs{trimpath}}%
+\end{cd}
+
+These are prefix macros. The first two take an `object' (a variable in
+which a path was previously stored using \cs{store}) and uses it to trim
+one end off the following path. \cs{cutoffbefore} cuts off the part of
+the path before its first intersection with the object, while
+\cs{cutoffafter} cuts off the part 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 completely reliably only when there is only one
+point of intersection.
+
+The \cs{trimpath} macro takes two dimensions separated by commas and
+trims those lengths off the initial and terminal ends of the path. If
+only one dimension is given, that is used at both ends. This macro is
+essentially equivalent to applying \cs{cutoffafter} and then
+\cs{cutoffbefore} where the objects are circles which have radii equal
+to the given dimensions and which are centered at the endpoints of the
+path. Consequently, if the path is shorter than either dimension, it
+will not intersect either circle and nothing will be trimmed. Similarly,
+if the result of \cs{cutoffafter} is shorter than the first dimension,
+then \cs{cutoffbefore} will not trim any more off. The first two macros
+can be used to create a curve that starts or ends right at another
+figure without having to find the point where the two curves intersect.
+The third one can be used on the result to produce a curve that stops
+just short of the point of intersection.
+
+\begin{cd}
+\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}
+\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}
+\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. Hopefully, \mfp{} won't exceed your
+local \TeX's limit.
+
+All of \mfp's basic dimension parameters are font dimensions. We have
+lied slightly when we called them `\TeX{} 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}
+\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}
+\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}
+\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 graphics package to make the data
+available. If \cs{setmfpicgraphic} is redefined then this may also have
+to be redefined.
+
+\begin{cd}
+\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}
+\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}
+\cs{mfpicversion}
+\index{mfpicversion@\cs{mfpicversion}}
+\end{cd}
+
+This expands to the current \mfp{} version multiplied by 100. At this
+writing, it produces `\texttt{70}' because the version is 0.7. It
+can be used to test for the current 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.
+
+\subsubsection{Hackers.}\label{hackers}
+
+\Mfp{} employs a modified version of \LaTeX's \cs{@ifnextchar}
+that not only skips over spaces when seeking the next character, but
+also skips over \cs{relax} or tokens that have been \cs{let} equal to
+it. This is because, in contexts where we try to preserve lines, we make
+the end-of-line character active and set it equal to \cs{relax}. Since
+it is hard to predict in what context a macro will be used, this gives
+code like
+\begin{ex}
+ \cs{function}\\
+ \oarg{s1.2}\marg{0,2,.1}\marg{ x**2 }
+\end{ex}
+the same behavior in both.%
+ \footnote{Actually, because of a bug in previous versions, this was
+ not true, but it is now. I hope.}
+One consequence is that putting \cs{relax} to stop a command from seeing
+a `\texttt{[}' as the start of an optional argument will not work for
+\mfp{} commands. The same holds for the `\texttt{*}' in those few
+commands that have a star-form, and also for other commands that look
+ahead (\cs{tlabel} looks for a `\texttt{(}' starting off the location,
+and macros that operate on lists of data look ahead for
+`\cs{datafile}'). This is not a serious problem, because there is only
+one command (\cs{smoothdata}) that takes an optional arguments but
+doesn't have mandatory arguments after that. If a `\cs{relax}' appeared
+after any other \mfp{} command, it would be taken as an argument and an
+error would result. In any case, \cs{empty} will stop the looking ahead
+if it should ever be necessary.
+
+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}.)
+
+
+\clearpage
+
+\def\sectionmark#1{\markright {\thesection\quad#1}}%
+\def\subsectionmark#1{}
+\def\subsubsectionmark#1{}
+\thispagestyle{plain}
+\section{Appendices}\label{appendices}
+
+\subsection{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:
+
+\medskip
+Geoffrey Tobin %(G.Tobin@latrobe.edu.au)
+for his many suggestions, especially about cleaning up the \MF{} code,
+enforcing dimensions, fixing the dotted line computations, and speeding
+up the shading routines (through this process, Geoffrey and Tom managed
+to teach each other many of the subtleties of \MF), and for keeping
+track of \mfp{} for nearly a year while Tom finished his thesis;
+
+\medskip
+Bryan Green %(bgreen@sanjuan.uvic.ca)
+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
+
+\medskip
+Uwe Bonnes %(bon@lte.e-technik.uni-erlangen.de)
+and Jarom\'\i r Kuben, % (vabo@muni.cz)
+who worked out rewrites of \mfp{} during Tom's
+working hiatus and who each contributed several valuable ideas.
+
+\medskip
+Some credit also belongs to Anthony Stark, % (ajs@merck.com)
+whose work on a FIG to \MF{} converter has had a serious impact on the
+development of many of \mfp's capabilities.
+
+\medskip
+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, and Zaimi
+Sami~Alex for suggestions.
+
+But mostly, he'd like to thank Tom Leathrum for starting it all.
+
+\subsection{Changes History.}\label{changes}
+
+See the file \file{changes.txt} for a somewhat sporadic and rambling
+history of changes to \mfp. See the file \file{readme.txt} for a
+list of any known problems.
+
+%\clearpage
+\subsection{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
+\def\stack#1{\everycr{}\def\\{\cr}\halign{\strut##\hfil\cr#1\crcr}}
+{\everycr{\noalign{\medskip}}
+\halign to \hsize{\opt{#}\hfil\quad\tabskip0pt plus 1fil&
+ \vtop{\stack{#}}\hfil\quad&
+ \vtop{\parindent0pt \hsize.45\hsize \rightskip0pt plus1fil\relax
+ \strut\ignorespaces#\strut}\tabskip0pt\cr
+{\rmfamily\scshape Option}:& \textsc{Command form(s)}:& \omit\textsc{Restrictions}: \hfil\cr
+\noalign{\smallskip\hrule\smallskip}
+metapost&\cs{usemetapost}& Command must come before
+ \cs{opengraphsfile}. Incompatible with \opt{metafont} option. \cr
+metafont&\cs{usemetafont}& The default. Command must come before
+ \cs{opengraphsfile}. Incompatible with \opt{metapost} option. \cr
+mplabels&\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
+overlaylabels&\cs{overlaylabels},\\ \cs{nooverlaylabels}& Has no effect
+ without \opt{metapost}. \cr
+truebbox& \cs{usetruebbox},\\ \cs{notruebbox}& Has no effect
+ without \opt{metapost}. \cr
+clip& \cs{clipmfpic},\\ \cs{noclipmfpic}& No restrictions. \cr
+clearsymbols& \cs{clearsymbols},\\ \cs{noclearsymbols}& No restrictions. \cr
+centeredcaptions& \cs{usecenteredcaptions},\\ \cs{nocenteredcaptions}&
+ No restrictions. \cr
+debug&\cs{mfpicdebugtrue},\\\cs{mfpicdebugfalse}& To turn on
+ debugging while \file{mfpic.tex} is loading, issue
+ \cs{def}\cs{mfpicdebug}\marg{true}. \cr
+\vtop{\hbox{draft\strut}
+ \hbox{final\strut}
+ \hbox{nowrite\strut}}&\cs{mfpicdraft}\\
+ \cs{mfpicfinal}\\
+ \cs{mfpicnowrite}& Should not be used
+ together. Command forms should come before
+ \cs{opengraphsfile}\cr
+}}
+
+%\clearpage
+\subsection{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 pattern names \mfc{dashtype0} through
+\mfc{dashtype5}, or predefined color names \mfc{colortype0} through
+\mfc{colortype7}, or predefined symbols \mfc{pointtype0} through
+\mfc{pointtype8}. Here follows a description of each of these variables.
+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
+\indent\vbox{%
+\halign{#\hfil\qquad&#\hfil\quad&#\hfil\strut\cr
+\textsc{Name}&\textsc{Pattern}&\textsc{Meaning}\cr
+\noalign{\smallskip\hrule\smallskip}
+\mfc{dashtype0}& \dim{0bp} & solid line \cr
+\mfc{dashtype1}& \dim{3bp,4bp} & dashes \cr
+\mfc{dashtype2}& \dim{0bp,4bp} & dots \cr
+\mfc{dashtype3}& \dim{0bp,4bp,3bp,4bp} & dot-dash \cr
+\mfc{dashtype4}& \dim{0bp,4bp,3bp,4bp,0bp,4bp} & dot-dash-dot \cr
+\mfc{dashtype5}& \dim{0bp,4bp,3bp,4bp,3bp,4bp} & dot-dash-dash\cr
+}}
+
+\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.)
+
+\medskip
+\indent\vbox{%
+\halign{#\hfil\qquad&#\hfil\quad&#\hfil\strut\cr
+\textsc{Name}&\textsc{Color}&\textsc{(r,g,b)}\cr
+\noalign{\smallskip\hrule\smallskip}
+\mfc{colortype0}& black & $( 0, 0, 0)$\cr
+\mfc{colortype1}& red & $( 1, 0, 0)$\cr
+\mfc{colortype2}& blue & $( .2, .2, 1)$\cr
+\mfc{colortype3}& orange & $(.66,.34, 0)$\cr
+\mfc{colortype4}& green & $( 0, .8, 0)$\cr
+\mfc{colortype5}& magenta& $(.85, 0,.85)$\cr
+\mfc{colortype6}& cyan & $( 0,.85,.85)$\cr
+\mfc{colortype7}& yellow & $(.85,.85, 0)$\cr
+}}
+
+\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
+\indent\vbox{%
+\halign{#\hfil\qquad&#\hfil\strut\cr
+\textsc{Name}&\textsc{Description}\cr
+\noalign{\smallskip\hrule\smallskip}
+\mfc{pointtype0}& \mfc{Circle} \cr
+\mfc{pointtype1}& \mfc{Cross} \cr
+\mfc{pointtype2}& \mfc{SolidDiamond} \cr
+\mfc{pointtype3}& \mfc{Square} \cr
+\mfc{pointtype4}& \mfc{Plus} \cr
+\mfc{pointtype5}& \mfc{Triangle} \cr
+\mfc{pointtype6}& \mfc{SolidCircle} \cr
+\mfc{pointtype7}& \mfc{Star} \cr
+\mfc{pointtype8}& \mfc{SolidTriangle}\cr
+}}
+
+\subsection{Special considerations when using \MF}\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 4096 pixels is. In
+fonts prepared for a LaserJet4 (600 DPI), this means about 6.8 inches.
+For a 1200 DPI pronter, the limit is about 3.4 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)^2=20.25$ in pixel units (after
+multiplying by the \cs{mfpic} scaling factor the \cs{mfpicunit} in
+inches and the DPI value): $20.25\times10\times0.03937\times600 > 4783$.
+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.
+
+
+\subsection{Special considerations when using \MP}\label{mpconsiderations}
+
+\subsubsection{Required support}
+
+To use \mfp{} with \MP, the following support is needed (besides a
+working \MP{} installation):
+
+\medskip
+\halign{#\hfil\quad&\vtop{\hsize 4.4 truein \raggedright \noindent
+ \strut#\strut}\hfil\cr
+Under plain\TeX &The file \file{epsf.tex}\cr
+Under \LaTeX209 &The file \file{epsf.tex} or \file{epsf.sty}\cr
+Under \LaTeXe &The package \prog{graphics} or \prog{graphicx}\cr
+Under \pdfLaTeX{} &The package \prog{graphics} or
+ \prog{graphicx} with option \opt{pdftex}\cr
+Under plain \pdfTeX{} &The files \file{supp-pdf.tex} and
+ \file{supp-mis.tex}\cr
+In all cases &The files \file{grafbase.mp} and
+ \file{dvipsnam.mp} plus, of course,
+ \file{mfpic.tex} (and \file{mfpic.sty} for
+ \LaTeX)\cr
+}
+
+\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 graphics package is given the
+\opt{pdftex} option. This option requires the file \file{pdftex.def}
+which currently inputs the files \file{supp-pdf.tex} and
+\file{supp-mis.tex}. The file \file{pdftex.def} is supplied with the
+\prog{graphics} package. The other two are usually supplied with a
+\pdfTeX{} distribution, and are definitely part of the \ConTeXt{}
+distribution. 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.
+If they have not been input, \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.
+
+\subsubsection{\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 choke 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}, much 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, other 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, 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{ex}
+ \cs{dashed}\cs{gfill}\cs{rect}\marg{(0,0),(1,1)}
+\end{ex}
+This adds the dashed outline to the filled rectangle. That is, first the
+rectangle is defined, then it is filled, then the outline is drawn in
+dashed lines. This makes a difference when colors other than black are
+used. Drawing is done with the center of the virtual pen stroked down
+the middle of the boundary, so half of its width falls inside the
+rectangle. On the other hand, filling is done right up to the boundary.
+In this example, the dashed lines are drawn on top of part of the fill.
+In the reverse order, the fill would cover part of the outline.
+
+\subsubsection{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{cd}
+\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{cd}
+
+The following are the default definitions for \cs{setmfpicgraphic}:
+
+\medskip
+\halign{#:\hfil&\quad#\hfil\cr
+In plain \TeX&
+\cs{def}\cs{setmfpicgraphic}\texttt{\#1}\marg{\cs{epsfbox}\marg{\#1}}\cr
+In \LaTeX209&
+\cs{def}\cs{setmfpicgraphic}\texttt{\#1}\marg{\cs{epsfbox}\marg{\#1}}\cr
+In \LaTeXe&
+\cs{def}\cs{setmfpicgraphic}\texttt{\#1}\marg{\cs{includegraphics}\marg{\#1}}\cr
+In \pdfLaTeX&
+\cs{def}\cs{setmfpicgraphic}\texttt{\#1}\marg{\cs{includegraphics}\marg{\#1}}\cr
+In \pdfTeX&
+\cs{def}\cs{setmfpicgraphic}\texttt{\#1}\marg{\cs{convertMPtoPDF}\marg{\#1}%
+ \marg{1}\marg{1}}\cr
+}
+\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 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
+without the option \opt{mplabels} since the \mfp{} code for
+placing labels and captions and reserving space for the picture relies
+on the picture having the dimensions given by the arguments to the
+\cs{mfpic} command. With \opt{mplabels} plus \opt{truebbox} it will
+probably 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. To test whether a proposed definition is completely
+expandable, put
+\begin{ex}
+\cs{message}\marg{\texttt{***}%
+\cs{setfilename}\marg{file}\marg{1}\texttt{***}}
+\end{ex}
+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.
+
+
+\subsection{\prog{Mfpic} and the rest of the world}
+
+\subsubsection{The literature}
+
+There are at least two places 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.
+
+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{cyclic}, \cs{lines} and \cs{point} with respect to
+\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:
+
+\medskip
+\moveright\parindent
+\vbox{%
+ \halign{#\qquad\hfil&#\hfil\cr
+ Old name: & New name:\cr
+ \cs{boosts} & \cs{boost}\cr
+ \cs{reflectsabout} & \cs{reflectabout}\cr
+ \cs{rotatesaround} & \cs{rotatearound}\cr
+ \cs{rotates} & \cs{rotate}\cr
+ \cs{scales} & \cs{scale}\cr
+ \cs{shifts} & \cs{shift}\cr
+ \cs{xscales} & \cs{xscale}\cr
+ \cs{xslants} & \cs{xslant}\cr
+ \cs{xyswaps} & \cs{xyswap}\cr
+ \cs{yscales} & \cs{yscale}\cr
+ \cs{yslants} & \cs{yslant}\cr
+ \cs{zscales} & \cs{zscale}\cr
+ \cs{zslants} & \cs{zslant}\cr
+ }%
+}
+
+\medskip
+\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: \mfp{} now supports
+the \cs{usepackage} method of loading.
+
+\subsubsection{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{%
+ \subsection{Index of commands, options and parameters by page}}
+\let\oldcs\cs
+\renewcommand{\cs}[1]{\leavevmode\mytt{\llap{\char`\\}#1}}
+
+\InputIfFileExists{mfpman.ind}{}{\mfpindexheading}
+
+\let\cs\oldcs
+
+\columnseprule 0pt
+\columnsep 35pt
+\twocolumn[\subsection{List of commands by type}]
+\parindent0pt
+\parskip0pt plus .3pt\relax
+\makeatletter
+\let\item\@idxitem
+\makeatother
+
+\subsubsection{Figures}
+
+ \item \cs{arc}
+ \item \cs{axis}
+ \item \cs{btwnfcn}
+ \item \cs{chartbar}
+ \item \cs{circle}
+ \item \cs{closedcspline}
+ \item \cs{closedmfbezier}
+ \item \cs{closedqbeziers}
+ \item \cs{closedqspline}
+ \item \cs{cspline}
+ \item \cs{curve}
+ \item \cs{cyclic}
+ \item \cs{datafile}
+ \item \cs{ellipse}
+ \item \cs{fcncurve}
+ \item \cs{function}
+ \item \cs{graphbar}
+ \item \cs{histobar}
+ \item \cs{lines}
+ \item \cs{mfbezier}
+ \item \cs{mfobj}
+ \item \cs{parafcn}
+ \item \cs{piewedge}
+ \item \cs{plrfcn}
+ \item \cs{plrregion}
+ \item \cs{polygon}
+ \item \cs{polyline}
+ \item \cs{qbeziers}
+ \item \cs{qspline}
+ \item \cs{rect}
+ \item \cs{regpolygon}
+ \item \cs{sector}
+ \item \cs{tlabelcircle}
+ \item \cs{tlabelellipse}
+ \item \cs{tlabeloval}
+ \item \cs{tlabelrect}
+ \item \cs{turtle}
+
+
+\subsubsection{Figure modifiers}
+
+ \item \cs{arrow}
+ \item \cs{bclosed}
+ \item \cs{cbclosed}
+ \item \cs{connect}, \cs{endconnect}
+ \item \cs{cutoffafter}
+ \item \cs{cutoffbefore}
+ \item \cs{lclosed}
+ \item \cs{makesector}
+ \item \cs{partpath}
+ \item \cs{qbclosed}
+ \item \cs{reflectpath}
+ \item \cs{reverse}
+ \item \cs{rotatepath}
+ \item \cs{scalepath}
+ \item \cs{sclosed}
+ \item \cs{shiftpath}
+ \item \cs{slantpath}
+ \item \cs{subpath}
+ \item \cs{transformpath}
+ \item \cs{trimpath}
+ \item \cs{xscalepath}
+ \item \cs{xslantpath}
+ \item \cs{xyswappath}
+ \item \cs{yscalepath}
+ \item \cs{yslantpath}
+
+
+\subsubsection{Figure renderers}
+
+ \item \cs{dashed}
+ \item \cs{dotted}
+ \item \cs{draw}
+ \item \cs{gclear}
+ \item \cs{gclip}
+ \item \cs{gendashed}
+ \item \cs{gfill}
+ \item \cs{hatch}
+ \item \cs{lhatch}
+ \item \cs{plot}
+ \item \cs{plotdata} (sort of)
+ \item \cs{plotnodes}
+ \item \cs{polkadot}
+ \item \cs{rhatch}
+ \item \cs{shade}
+ \item \cs{tess}
+ \item \cs{thatch}
+ \item \cs{xhatch}
+
+\subsubsection{Lengths}
+
+
+ \item \cs{axisheadlen}
+ \item \cs{dashlen}
+ \item \cs{dotsize}
+ \item \cs{dotspace}
+ \item \cs{hashlen}
+ \item \cs{hatchspace}
+ \item \cs{headlen}
+ \item \cs{mfpiccaptionskip}
+ \item \cs{mfpicheight}
+ \item \cs{mfpicunit}
+ \item \cs{mfpicwidth}
+ \item \cs{pointsize}
+ \item \cs{polkadotspace}
+ \item \cs{shadespace}
+ \item \cs{sideheadlen}
+ \item \cs{symbolspace}
+
+\subsubsection{Coordinate transformation}
+
+ \item \cs{applyT}
+ \item \cs{boost}
+ \item \cs{coords}, \cs{endcoords}
+ \item \cs{mirror}
+ \item \cs{reflectabout}
+ \item \cs{rotate}
+ \item \cs{rotatearound}
+ \item \cs{scale}
+ \item \cs{shift}
+ \item \cs{turn}
+ \item \cs{xscale}
+ \item \cs{xslant}
+ \item \cs{xyswap}
+ \item \cs{yscale}
+ \item \cs{yslant}
+ \item \cs{zscale}
+ \item \cs{zslant}
+
+\subsubsection{Axes, grids, and marks}
+
+ \item \cs{axes}
+ \item \cs{axis}
+ \item \cs{axismarks}
+ \item \cs{bmarks}
+ \item \cs{doaxes}
+ \item \cs{grid}
+ \item \cs{gridarcs}
+ \item \cs{gridlines}
+ \item \cs{gridpoints}
+ \item \cs{gridrays}
+ \item \cs{hgridlines}
+ \item \cs{lattice}
+ \item \cs{lmarks}
+ \item \cs{plotsymbol}
+ \item \cs{plrgrid}
+ \item \cs{plrgridpoints}
+ \item \cs{plrpatch}
+ \item \cs{point}
+ \item \cs{rmarks}
+ \item \cs{tmarks}
+ \item \cs{vgridlines}
+ \item \cs{xaxis}
+ \item \cs{xmarks}
+ \item \cs{yaxis}
+ \item \cs{ymarks}
+
+\subsubsection{Setting options}
+
+ \item \cs{clearsymbols}
+ \item \cs{clipmfpic}
+ \item \cs{mfpicdebugfalse}
+ \item \cs{mfpicdebugtrue}
+ \item \cs{mfpicdraft}
+ \item \cs{mfpicfinal}
+ \item \cs{mfpicnowrite}
+ \item \cs{nocenteredcaptions}
+ \item \cs{noclearsymbols}
+ \item \cs{noclipmfpic}
+ \item \cs{nomplabels}
+ \item \cs{nooverlaylabels}
+ \item \cs{noship}
+ \item \cs{notruebbox}
+ \item \cs{overlaylabels}
+ \item \cs{resumeshipping}
+ \item \cs{stopshipping}
+ \item \cs{usecenteredcaptions}
+ \item \cs{usemetafont}
+ \item \cs{usemetapost}
+ \item \cs{usemplabels}
+ \item \cs{usetruebbox}
+
+\subsubsection{Changing values}
+
+ \item \cs{axismargin}
+ \item \cs{darkershade}
+ \item \cs{dashlineset}
+ \item \cs{dashpattern}
+ \item \cs{dotlineset}
+ \item \cs{drawpen}
+ \item \cs{hatchwd}
+ \item \cs{headshape}
+ \item \cs{lightershade}
+ \item \cs{mfpicnumber}
+ \item \cs{mfplinestyle}
+ \item \cs{mfplinetype}
+ \item \cs{pen}
+ \item \cs{penwd}
+ \item \cs{polkadotwd}
+ \item \cs{setallaxismargins}
+ \item \cs{setallbordermarks}
+ \item \cs{setaxismargins}
+ \item \cs{setaxismarks}
+ \item \cs{setbordermarks}
+ \item \cs{setmfvariable}
+ \item \cs{setmpvariable}
+ \item \cs{settension}
+ \item \cs{setxmarks}
+ \item \cs{setymarks}
+ \item \cs{shadewd}
+
+\subsubsection{Changing colors}
+
+ \item \cs{backgroundcolor}
+ \item \cs{drawcolor}
+ \item \cs{fillcolor}
+ \item \cs{hatchcolor}
+ \item \cs{headcolor}
+ \item \cs{mfpdefinecolor}
+ \item \cs{pointcolor}
+ \item \cs{tlabelcolor}
+
+\subsubsection{Defining arrays}
+
+ \item \cs{barchart}
+ \item \cs{bargraph}
+ \item \cs{histogram}
+ \item \cs{numericarray}
+ \item \cs{pairarray}
+ \item \cs{patharr}, \cs{endpatharr}
+ \item \cs{piechart}
+
+\subsubsection{Changing behavior}
+
+ \item \cs{clearsymbols}
+ \item \cs{coloredlines}
+ \item \cs{dashedlines}
+ \item \cs{datapointsonly}
+ \item \cs{defaultplot}
+ \item \cs{everytlabel}
+ \item \cs{makepercentcomment}
+ \item \cs{makepercentother}
+ \item \cs{mfpdatacomment}
+ \item \cs{mfpdataperline}
+ \item \cs{mfpverbtex}
+ \item \cs{noclearsymbols}
+ \item \cs{pointedlines}
+ \item \cs{pointfillfalse}
+ \item \cs{pointfilltrue}
+ \item \cs{reconfigureplot}
+ \item \cs{setrender}
+ \item \cs{smoothdata}
+ \item \cs{tlabeljustify}
+ \item \cs{tlabeloffset}
+ \item \cs{tlabelsep}
+ \item \cs{tlpathjustify}
+ \item \cs{unsmoothdata}
+ \item \cs{using}
+ \item \cs{usingnumericdefault}
+ \item \cs{usingpairdefault}
+
+\subsubsection{Files and environments}
+
+ \item \cs{closegraphsfile}
+ \item \cs{mfpframe}, \cs{endmfpframe}
+ \item \cs{mfpic}, \cs{endmfpic}
+ \item \cs{opengraphsfile}
+
+\subsubsection{Text}
+
+ \item \cs{axislabels}
+ \item \cs{plottext}
+ \item \cs{tcaption}
+ \item \cs{tlabels}
+ \item \cs{tlabel}
+
+\subsubsection{Misc} \widowpenalty10000
+
+ \item \cs{fdef}
+ \item \cs{getmfpicoffset}
+ \item \cs{ifmfpmpost}
+ \item \cs{mfcmd}
+ \item \cs{mflist}
+ \item \cs{mfpframed}
+ \item \cs{mfpicversion}
+ \item \cs{mfpverbtex}
+ \item \cs{mfsrc}
+ \item \cs{mftitle}
+ \item \cs{newfdim}
+ \item \cs{newsavepic}
+ \item \cs{plr}
+ \item \cs{pointdef}
+ \item \cs{preparemfpicgraphic}
+ \item \cs{savepic}
+ \item \cs{setmfpicgraphic}
+ \item \cs{setfilename}
+ \item \cs{sequence}
+ \item \cs{store}
+ \item \cs{tile}, \cs{endtile}
+ \item \cs{tmtitle}
+ \item \cs{usepic}
+
+
+\end{document}
+