%%%  File: mfpicdoc.tex
%%%

\magnification=\magstep1

% heading macros
\newskip\myskip\myskip=5pt plus 1pt
\def\head#1{\vskip\myskip \noindent $\bullet$ {\it #1} 
\par\nobreak}
\def\subhead#1{\vskip\myskip {\sl #1} \par\nobreak}

% abbreviations
\def\LaTeX{%
{\rm L\raise.42ex\hbox{\kern-.3em a}\kern-.15em\TeX}}
\def\PiCTeX{%
{\rm
P\kern-.12em\lower.5ex\hbox{I}\kern-.075emC%
\kern-.11em\TeX}}
\font\manual=logo10 % may want to use manfnt here instead
\def\MF{{\manual META}\-{\manual FONT}}
\def\PS{{\rm Post}\-{\rm Script}}

% metacode macros
\def\<{$\langle$\bgroup\it}\def\>{\egroup$\rangle$}
% macro to typeset macros
% e.g. \macro{name}[?arg1][arg2] gives
% \name[arg1]{arg2}
\def\gobble#1{}
\def\dooptparam[#1]{{\tt[#1]}\futurelet\nchr\domacro}
\def\dofixparam[#1]{{\tt\string{#1\string}}%
\futurelet\nchr\domacro}
\def\doparamswap{\if?\nchr%
\dooptparam[\expandafter\gobble\else\dofixparam[\fi}
\def\doparam{\futurelet\nchr\doparamswap}
\def\ddoparam{\expandafter\doparam\gobble}
\def\domacro{\if[\nchr\expandafter\ddoparam\fi}
\def\macro#1{{\tt\char\escapechar#1}%
\futurelet\nchr\domacro}

\centerline{\bf Pictures in \TeX\ with Metafont}

\head{Why?} 

I got the idea for {\tt mfpic} mostly out of a feeling of
frustration.  Different output mechanisms for printing or
viewing \TeX\ DVI files each have their own ways to
include pictures.  More often than not, there are
provisions for including \PS\ data into a DVI file using
\TeX\ \macro{special}'s.  However, this technique seems
far from \TeX's ideal of device-independence, and
besides, different \TeX\ output drivers handle these
\macro{special}'s in different ways.  The same problems
arise with including {\tt tpic} \macro{special}'s. 
\LaTeX's {\tt picture} environment has a hopelessly
limited supply of available objects to draw -- if you
want to draw a graph of a polynomial curve, you're out of
luck.  There is, of course, \PiCTeX, which is wonderfully
flexible and general, but its most obvious feature is its
speed -- or rather lack of it.  Processing a single
picture in \PiCTeX\ can often take several minutes.  It
occured to me that it might be possible to take advantage
of the fact that \MF\ is {\it designed} for drawing
things.  The result of pursuing this idea is {\tt mfpic},
a set of macros for \TeX\ and \MF\ which incorporate
Metafont-drawn pictures into a \TeX\ file.  The nature of
the macros, from the user's point of view, is very much
like \PiCTeX.  I do not pretend that {\tt mfpic} has
anything like the scope of \PiCTeX, but it should suit
most purposes for drawing small graphs and including them
in your \TeX\ documents.

\head{Author.}

{\tt mfpic} was written primarily by Tom Leathrum
(moth@dartmouth.edu) during the late spring and summer of
1992.  Those who helped most in this process are credited
in the Acknowledgements.

\head{Manifest.}

There are seven files included in the {\tt mfpic}
distribution:  {\tt mfpicdoc.tex} (this document, which
can be processed in plain \TeX), {\tt mfpic.tex} (the
\TeX\ macros), {\tt graphbase.mf} (the \MF\ macros), 
{\tt objects.tex} (a sample file containing at least one
picture of each object), {\tt pictures.tex} (a short
sample file with a few more complicated pictures), 
{\tt lamfpic.tex} (a short header file that sets up a 
\LaTeX\ environment for pictures), and 
{\tt lapictures.tex} (the \LaTeX\ version of 
{\tt pictures.tex}).  Information on how to set up a few
specific configurations of computers is also available,
separately.

\head{Setting Up and Processing.}

Setting up \TeX\ and \MF\ to process these files will, to
an extent, depend on your local installation.  The
biggest problem you are likely to have, regardless of
your installation, will be convincing \TeX\ and its
output drivers to find \MF's output files.

To process the sample file, first run \TeX\ on the file
{\tt pictures.tex}.  \TeX\ will complain that it can't
find the file {\tt pics.tfm}, but will continue
processing the file anyway.  When the file is finished
processing, you will now have a file called 
{\tt pics.mf}.  This is the \MF\ file containing the
descriptions of the pictures for {\tt pictures.tex}.  You
need to run \MF\ on {\tt pics.mf}, with
\macro{mode=localfont} set up.  (Read your \MF\ manual to
see how to do this.) Now that you have the font and font
metric files generated by \MF, reprocess the file 
{\tt 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 font
generated by {\tt pics.mf}).

These three steps of processing -- processing with \TeX,
processing with \MF, 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 either of
the last two steps.  There is also a somewhat subtle
circumstance under which you can skip the third step --
if you change the picture in such a way as {\it not} to
affect the font metric file, then you do not have to
reprocess with \TeX, because the original metric used for
the first step will put the pictures in the right places.
The only {\tt mfpic} macros that affect the font metric
file are the macros listed in the {\sl Files and
Environments} section below.

\head{How It Works.}

When you run \TeX\ on the file {\tt pictures.tex}, \TeX\
generates a file {\tt pics.mf}.  This file is formed by
\macro{write} commands in the {\tt mfpic} macros.  The
user should never have to read or change the file {\tt
pics.mf} directly -- the {\tt mfpic} macros take care of
it.  The user familiar with \MF\ will notice, by looking
at the {\tt mfpic} macros, that the {\tt mfpic} drawing
macros translate almost directly into simple \MF\ {\tt
draw} commands.  The \macro{label}'s and
\macro{caption}'s, however, are placed on the graph by
\TeX, not \MF.

\head{The Macros.}

\subhead{Files and Environments.}

\vskip\myskip
\noindent\macro{opengraphsfile}[\<font\>]$\dots$
\macro{closegraphsfile}

\nobreak 
These macros open and close the Metafont file
which will contain the pictures to be included in this
document.  The name of the file will be {\tt\<font\>.mf}.
If the \<font\> parameter is changed, you will have to
reprocess the \TeX\ file after processing
{\tt\<font\>.mf}.


\vskip\myskip
\noindent\macro{picture}[?\<xscale\>][?\<yscale\>]%
[\<xneg\>][\<xpos\>][\<yneg\>][\<ypos\>]
$\dots$\macro{endpicture}

\nobreak 
These macros open and close the environment in
which the rest of the macros below make sense.  The
\macro{picture} macro also sets up the local coordinate
system for the picture.  The \<xscale\> and \<yscale\>
parameter establishes the length of a coordinate system
unit, in points.  At least one scale parameter must be
specified, but if only one is specified, then they are
assumed to be equal.  The \<xneg\> and \<xpos\>
parameters establish the lower and upper (resp.) bounds
for the $x$-axis coordinates; similarly, \<yneg\> and
\<ypos\> 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
\<xscale\>$\cdot$(\<xpos\>$-$\<xneg\>) points.  These
scales and bounds are used primarily to establish the
metric for the character containing the picture described
within the environment.  If any of these parameters are
changed, the {\tt\<font\>.tfm} file will be affected, so
you will have to reprocess the \TeX\ file after
processing {\tt\<font\>.mf}.

\vskip\myskip 
The rest of the {\tt mfpic}  macros do not
affect the font metric file ({\tt\<font\>.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.

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

\subhead{Points, Lines, Arrows, and Dotted Lines.}

\vskip\myskip
\noindent\macro{point}[(\<xval\>,\<yval\>)]

\nobreak 
This macro draws a small filled circle centered
at the point {\tt (\<xval\>,\<yval\>)}.  The diameter of
the circle is determined by the dimension
\macro{pointsize}.  The default value of
\macro{pointsize} is 2 points.

\vskip\myskip
\noindent\macro{line}[(\<xval0\>,\<yval0\>),%
(\<xval1\>,\<yval1\>)]

\nobreak
This macro draws the line segment  
with endpoints at the points
{\tt (\<xval0\>,\<yval0\>)} and 
{\tt (\<xval1\>,\<yval1\>)}.

\vskip\myskip
\noindent\macro{arrow}[(\<xval0\>,\<yval0\>),%
(\<xval1\>,\<yval1\>)]

\nobreak
This macro draws an arrow starting from the point 
{\tt (\<xval0\>,\<yval0\>)}
and pointing to the point {\tt (\<xval1\>,\<yval1\>)}.
The length of the arrowhead is determined by the
dimension \macro{headlen}.  The default value of 
\macro{headlen} is 3 points.
Each side of the arrowhead is a  \MF\ Bezier curve
starting from the tip of the arrowhead and heading
initially parallel to the arrow line, then bending out to
the endpoint.

\vskip\myskip
\noindent\macro{dottedline}[(\<xval0\>,\<yval0\>),%
(\<xval1\>,\<yval1\>)]

\nobreak
This macro draws the dotted (or, more properly, dashed) 
line segment  specified as in the \macro{line} macro.
The length of the dashes is determined 
by the dimension \macro{dashlen}.  The default value of 
\macro{dashlen} is 4 points.   The space between the
dashes is determined by the dimension \macro{dashspace}. 
The default value of \macro{dashspace} is  4 points.  The
space between the dashes may be adjusted by as much as
${dashspace}\over{n}$, where $n$ is the number of spaces
appearing in the line segment, in order not to have
partial dashes at the ends.

\vskip\myskip
\noindent\macro{dottedarrow}[(\<xval0\>,\<yval0\>),%
(\<xval1\>,\<yval1\>)]

\nobreak
This macro draws a dotted arrow specified as in the
\macro{arrow} macro, with the 
arrowhead the same
shape and size as in the \macro{arrow} command and the 
dash length and spacing
determined as in the \macro{dottedline} macro.

\subhead{Axes and Axis Marks.}

\vskip\myskip
\noindent\macro{axes}

\nobreak
This macro draws the $x$ and $y$ axes for the coordinate 
system.  The length of the 
arrowhead is determined by the
dimension \macro{axisheadlen}.  The default value of 
\macro{axisheadlen} is 5 points.
The shape of the arrowhead is determined as in the 
{\tt\string\arrow} macro.

\vskip\myskip
\noindent\macro{xmarks}[\<value0\>,\<value1\>,$\dots$] 
and 
\macro{ymarks}[\<value0\>,\<value1\>,$\dots$]

\nobreak
These macros place hash marks on the $x$ and $y$ axes 
(resp.) at the places indicated
by the values in the list.  The
length of the hash marks is determined by the
dimension \macro{hashlen}.  The default value of 
\macro{hashlen} is 
4 points.

\subhead{Polygons.}

\vskip\myskip
\noindent\macro{rect}[(\<xval0\>,\<yval0\>),%
(\<xval1\>,\<yval1\>)]

\nobreak
This macro draws  the rectangle  specified by the 
given points {\tt (\<xval0\>,\<yval0\>)} and  
{\tt (\<xval1\>,\<yval1\>)} being any two
opposite corners of the rectangle.  

\vskip\myskip
\noindent\macro{dottedrect}[(\<xval0\>,\<yval0\>),%
(\<xval1\>,\<yval1\>)]

\nobreak
This macro draws  the dotted line rectangle   
specified as in the \macro{rect} macro.  
The dash length and spacing are
determined as in the \macro{dottedline} macro.

\vskip\myskip
\noindent\macro{block}[(\<xval0\>,\<yval0\>),%
(\<xval1\>,\<yval1\>)]

\nobreak
This macro draws  the filled rectangle   
specified as in the \macro{rect} macro.  

\vskip\myskip
\noindent\macro{rectshade}[(\<xval0\>,\<yval0\>),%
(\<xval1\>,\<yval1\>)]

\nobreak
This macro draws dots shading in the rectangle 
specified as in the \macro{rect} macro.  
This macro does {\it not} draw the
outline rectangle.  The spacing between the dots is 
determined by the
dimension \macro{shadespace}.  The default value of 
\macro{shadespace} is  1 point.

\vskip\myskip
\noindent\macro{polygon}[(\<xval0\>,\<yval0\>),%
(\<xval1\>,\<yval1\>),$\dots$]

\nobreak
This macro draws a polygon with the specified points 
at the vertices.  The resulting
polygon can {\it not} be allowed to cross itself.

\vskip\myskip
\noindent\macro{polyshade}[(\<xval0\>,\<yval0\>),%
(\<xval1\>,\<yval1\>),$\dots$]

\nobreak
This macro shades the region enclosed by the polygon specified as in the
\macro{polygon} macro.  The spacing between dots is determined as in the
\macro{shaderect} macro.

\vskip\myskip
\noindent\macro{polyfill}[(\<xval0\>,\<yval0\>),%
(\<xval1\>,\<yval1\>),$\dots$]

\nobreak
This macro fills the region enclosed by the polygon 
specified as in the \macro{polygon} macro.

\subhead{Parameters.}

There are many parameters to {\tt mfpic} which the user
can modify to obtain different effects, such as different
arrowhead size or shape.  Most of these parameters have
been described already in the context of macros they
modify, but they are all described together here.  Most
of the parameters are stored by \TeX\ as dimensions, and
so are available globally, even if there is no \MF\ file
open; changes to them are subject to the usual \TeX\
rules of scope.  Some parameters, however, 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 {\tt mfpic} user, this
means that changes inside the \macro{picture} $\dots$
\macro{endpicture} environment are local to that
environment, but other \TeX\ groupings have no effect on
scope.

\vskip\myskip
\noindent\macro{pointsize}

\nobreak
This dimension stores the diameter of the filled circle 
drawn by the \macro{point}
macro.  The default value is 2 points.

\vskip\myskip
\noindent\macro{pen}[\<pensize\>]

\nobreak
This macro establishes the width of the drawing pen.  
The default is 0.5 points.
This quantity is stored by \MF.

\vskip\myskip
\noindent\macro{headlen}

\nobreak
This dimension stores the length of the arrowhead 
drawn by the \macro{arrow} macro.
The default value is 3 points.

\vskip\myskip
\noindent\macro{headshape}[\<hdwdr\>][\<hdten\>]

\nobreak
This macro establishes the shape of the arrowhead drawn
by the \macro{arrow} and \macro{axes} macros.  The value
of \<hdwdr\> is the ratio of the width of the arrowhead
to its length, and \<hdten\> is the tension of the Bezier
curves.  The default values are both 1.  These values are
stored by \MF.  Setting  \macro{headshape}[1][infinity]
will make the sides of the arrowheads straight lines.

\vskip\myskip
\noindent\macro{dashlen}, \macro{dashspace}

\nobreak
These dimensions store, respectively, the length of
dashes and the length of spaces between dashes for lines
drawn by the \macro{dottedline} macro.  The space between
the dashes may be adjusted by as much as
${dashspace}\over{n}$, where $n$ is the number of spaces
appearing in the line segment, in order not to have
partial dashes at the ends.  The default values are both
4 points.

\vskip\myskip
\noindent\macro{dashlineset}, \macro{dotlineset}

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

\vskip\myskip
\noindent\macro{axisheadlen}

\nobreak
This dimension stores the length of the arrowhead 
drawn by the \macro{axes} macro. 
The default value is 5 points.

\vskip\myskip
\noindent\macro{hashlen}

\nobreak
This dimension stores the length of the axis 
hash marks drawn by the \macro{xmarks}
and \macro{ymarks} macros.  The default value is 4 points.

\vskip\myskip
\noindent\macro{shadespace}

\nobreak
This dimension establishes the spacing between dots 
drawn by the \macro{rectshade}
macro.  The default value is 1 point.

\vskip\myskip
\noindent\macro{darkershade}, \macro{lightershade}

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

\subhead{Circles, Ellipses, and Disks.}

\vskip\myskip
\noindent\macro{circle}[(\<xval\>,\<yval\>),\<rad\>]

\nobreak
This macro draws a circle centered at the 
point {\tt (\<xval\>,\<yval\>)} and with radius \<rad\>.

\vskip\myskip
\noindent\macro{circshade}[(\<xval\>,\<yval\>),\<rad\>]

\nobreak

This macro draws a shaded circle, determined as in the
\macro{circle} macro.  The spacing between dots is
determined as in the \macro{shaderect} macro.

\vskip\myskip
\noindent\macro{cdisk}[(\<xval\>,\<yval\>),\<rad\>]

\nobreak
This macro draws a filled circle, determined as in the 
\macro{circle} macro. 

\vskip\myskip
\noindent\macro{ellipse}[(\<xval\>,\<yval\>),%
\<xrad\>,\<yrad\>]

\nobreak
This macro draws an ellipse with the $x$ radius \<xrad\>
and $y$ radius \<yrad\>, centered at  the point {\tt
(\<xval\>,\<yval\>)}.

\vskip\myskip
\noindent\macro{ellshade}[(\<xval\>,\<yval\>),%
\<xrad\>,\<yrad\>]

\nobreak
This macro draws a shaded ellipse, determined as in the
\macro{ellipse} macro.  The spacing between dots is
determined as in the \macro{shaderect} macro.

\vskip\myskip
\noindent\macro{edisk}[(\<xval\>,\<yval\>),%
\<xrad\>,\<yrad\>]

\nobreak
This macro draws a filled ellipse, determined as in the 
\macro{ellipse} macro.

\vskip\myskip
\noindent\macro{rotatedellipse}[(\<xval\>,\<yval\>),%
\<xrad\>,\<yrad\>,\<theta\>]

\nobreak
This macro draws an ellipse with the $x$ radius \<xrad\>
and $y$ radius \<yrad\> (before rotation), centered at 
the point {\tt (\<xval\>,\<yval\>)}, and rotated around
its center by the angle \<theta\> (expressed in degrees).

\vskip\myskip
\noindent\macro{rotatedellshade}[(\<xval\>,\<yval\>),%
\<xrad\>,\<yrad\>,\<theta\>]

\nobreak
This macro draws a shaded ellipse, determined as in the
\macro{rotatedellipse} macro.  The spacing between dots
is determined as in the \macro{shaderect} macro.

\vskip\myskip
\noindent\macro{rotatededisk}[(\<xval\>,\<yval\>),%
\<xrad\>,\<yrad\>,\<theta\>]

\nobreak
This macro draws a filled ellipse, determined as in the
\macro{rotatedellipse} macro.

\subhead{Circular Arcs.}

\vskip\myskip
\noindent\macro{arc}[(\<xval0\>,\<yval0\>),%
(\<xval1\>,\<yval1\>),\<sweep\>]

\nobreak 
This macro draws a circular arc starting from the point
{\tt (\<xval0\>,\<yval0\>)}, ending at the point 
{\tt (\<xval1\>,\<yval1\>)}, and covering an arc angle of
\<sweep\> degrees, measured counterclockwise around the
center of the circle.  If, for example, the points {\tt
(\<xval0\>,\<yval0\>)} and {\tt (\<xval1\>,\<yval1\>)}
lie on a horizontal line with {\tt (\<xval0\>,\<yval0\>)}
to the left, and \<sweep\> is between 0 and 180
(degrees), then the center of the circle will be above
the horizontal line (in order for the angle to be
counterclockwise).  Negative values of \<sweep\> give
arcs curving in the other direction.

\vskip\myskip
\noindent\macro{arcarrow}[(\<xval0\>,\<yval0\>),%
(\<xval1\>,\<yval1\>),\<sweep\>]

\nobreak 

This marco draws an arc, specified as in the \macro{arc}
macro, with an arrowhead placed at the 
{\tt (\<xval1\>,\<yval1\>)} end.  
The shape and size of the
arrowhead are the same as in the \macro{arrow} macro.

\vskip\myskip
\noindent\macro{arcshade}[(\<xval0\>,\<yval0\>),%
(\<xval1\>,\<yval1\>),\<sweep\>]

\nobreak

This macro shades the region enclosed by the arc,
specified as in the \macro{arc} macro, and the line
segment between {\tt (\<xval0\>,\<yval0\>)} and 
{\tt (\<xval1\>,\<yval1\>)}.  The spacing between dots is
determined as in the \macro{shaderect} macro.

\vskip\myskip
\noindent\macro{arcfill}[(\<xval0\>,\<yval0\>),%
(\<xval1\>,\<yval1\>),\<sweep\>]

\nobreak
This macro fills the region specified as in the 
\macro{arcshade} macro.

\subhead{Polar Coordinates.}

\vskip\myskip
\noindent\macro{linedir}[(\<xval\>,\<yval\>),%
\<theta\>,\<length\>]

\nobreak
This macro draws a line segment starting from the point
{\tt (\<xval\>,\<yval\>)} and going in the direction
specified by \<theta\>, where \<theta\> is an angle
measured in degrees counterclockwise from the direction
parallel to the positive $x$ axis, and with length
\<length\>.

\vskip\myskip
\noindent\macro{arrowdir}[(\<xval\>,\<yval\>),%
\<theta\>,\<length\>]

\nobreak
This macro draws an arrow starting from the point 
{\tt (\<xval\>,\<yval\>)} and going in the 
direction specified
by \<theta\>, where \<theta\> is an angle measured in
degrees counterclockwise from the direction parallel to
the positive $x$ axis, with length \<length\>, and with
an arrowhead at the end opposite the point {\tt
(\<xval\>,\<yval\>)}.  The size and shape of the
arrowhead are determined as in the \macro{arrow} macro.

\vskip\myskip
\noindent\macro{arcth}[(\<xval\>,\<yval\>),%
\<theta1\>,\<theta2\>,\<rad\>]

\nobreak
This macro draws the arc with center at the point 
{\tt (\<xval\>,\<yval\>)}, of radius \<rad\>, 
from the angle
\<theta1\> to the angle \<theta2\>, where both angles are
measured in degrees counterclockwise from the direction
parallel to the $x$ axis.

\vskip\myskip
\noindent\macro{arctharrow}[(\<xval\>,\<yval\>),%
\<theta1\>,\<theta2\>,\<rad\>]

\nobreak
This macro draws an arc arrow, with the arc specified as
in the \macro{arcth} macro.

\vskip\myskip
\noindent\macro{wedgeshade}[(\<xval\>,\<yval\>),%
\<theta1\>,\<theta2\>,\<rad\>]

\nobreak 
This macro shades the wedge-shaped region, from
the angle \<theta1\> to the angle \<theta2\> inside the
circle with center at the point {\tt (\<xval\>,\<yval\>)}
and radius \<rad\>, where both angles are measured in
degrees counterclockwise from the direction parallel to
the $x$ axis.  The spacing between dots is determined as
in the \macro{shaderect} macro.

\vskip\myskip
\noindent\macro{wedgefill}[(\<xval\>,\<yval\>),%
\<theta1\>,\<theta2\>,\<rad\>]

\nobreak
This macro fills the wedge-shaped region specified 
as in the \macro{wedgeshade} macro.

\subhead{Curves.}

\vskip\myskip
\noindent\macro{curve}[(\<xval0\>,\<yval0\>),%
(\<xval1\>,\<yval1\>),$\dots$]

\nobreak
This macro draws a \MF\ Bezier path through the points 
specified, in the order specified.

\vskip\myskip
\noindent\macro{polycurve}[(\<xval0\>,\<yval0\>),%
(\<xval1\>,\<yval1\>),$\dots$]

\nobreak
This macro draws a polygonal path through the points 
specified, in the order specified.

\vskip\myskip
\noindent\macro{curvedarrow}[(\<xval0\>,\<yval0\>),%
(\<xval1\>,\<yval1\>),$\dots$]

\nobreak 
This macro draws a \MF\ Bezier curve, specified as in the
\macro{curve} macro, then puts an arrowhead at the end. 
The arrowhead is the same size and shape as the arrowhead
in the \macro{arrow} macro.

\vskip\myskip
\noindent\macro{polyarrow}[(\<xval0\>,\<yval0\>),%
(\<xval1\>,\<yval1\>),$\dots$]

\nobreak 
This macro draws a polygonal path, specified as in the
\macro{polycurve} macro, then puts an arrowhead at the
end.  The arrowhead is the same size and shape as the
arrowhead in the \macro{arrow} macro.

\subhead{Cyclic Curves.}

\vskip\myskip
\noindent\macro{cyclic}[(\<xval0\>,\<yval0\>),%
(\<xval1\>,\<yval1\>),$\dots$]

\nobreak
This macro draws a cyclic \MF\ Bezier curve through the
points specified.  The curve can {\it not} be allowed to
cross itself.

\vskip\myskip
\noindent\macro{cycleshade}[(\<xval0\>,\<yval0\>),%
(\<xval1\>,\<yval1\>),$\dots$]

\nobreak
This macro shades the region enclosed by the cyclic curve
specified as in the \macro{cyclic} macro.  The spacing
between dots is determined as in the \macro{shaderect}
macro.

\vskip\myskip
\noindent\macro{cyclefill}[(\<xval0\>,\<yval0\>),%
(\<xval1\>,\<yval1\>),$\dots$]

\nobreak
This macro fills the region enclosed by the cyclic curve
specified as in the \macro{cyclic} macro.

\subhead{Functions.}

\vskip\myskip
\noindent\macro{function}[\<xmin\>,\<xmax\>,%
\<step\>,\<expr\>]

\nobreak

This macro plots the function determined by
$f(x)=$\<expr\>, where \<expr\> is written with the only
unknown being {\tt x}, using as $x$ values the points
starting with \<xmin\> and stepping by \<step\> until
reaching \<xmax\>.  The function is interpolated with a
\MF\ Bezier path.  The expression {\it expr} is passed
directly into the corresponding \MF\ macro and
interpreted there, so \MF's rules for algebraic
expressions apply.  Operations available include {\tt +},
{\tt -}, {\tt *}, {\tt /}, and {\tt **} 
({\tt x**y}$=x^y$), with {\tt(} and {\tt )} for grouping. 
Functions available include {\tt round}, {\tt floor},
{\tt ceiling}, {\tt abs}, {\tt sqrt}, {\tt sind}, 
{\tt cosd}, {\tt mlog}, and {\tt mexp}.  ({\it Notes:}  
the trigonometric functions {\tt sind} and {\tt cosd}
take arguments in degrees; {\tt mlog(x)}$=256\ln x$, and
{\tt mexp} is its inverse.  There are other operations
and functions available, but these are the most useful
for plotting purposes.) You can also define the function
$f(x)$ by cases using the Metafont conditional expression
{\tt if \<boolean\>: \<expr\> else: \<expr\> fi}. 
Relations available for the \<boolean\> part of the
expression include {\tt =}, {\tt <}, {\tt >}, {\tt <=},
and {\tt >=}.

\vskip\myskip
\noindent\macro{polyfunction}[\<xmin\>,\<xmax\>,%
\<step\>,\<expr\>]

\nobreak
This macro plots the function determined by
$f(x)=$\<expr\>, as in the \noindent\macro{function}
macro, but using a polygonal path instead.

\vskip\myskip
\noindent\macro{parafcn}[\<tmin\>,\<tmax\>,\<step\>,%
(\<expr0\>,\<expr1\>)]

\nobreak

This macro plots the parametric path determined by
$(x(t),y(t))=${\tt (\<expr0\>,\<expr1\>)}, where
\<expr0\> and \<expr1\> are written with the only unknown
being {\tt t}, using as $t$ values the points starting
with \<tmin\> and stepping by \<step\> until reaching
\<tmax\>.  The function is interpolated with a \MF\
Bezier path.  The expressions  \<expr0\> and \<expr1\>
are passed directly into the corresponding \MF\ macro, as
in the \macro{function} macro, so the same operations are
available.

\vskip\myskip
\noindent\macro{polyparafcn}[\<tmin\>,\<tmax\>,%
\<step\>,(\<expr0\>,\<expr1\>)]

\nobreak
This macro plots the parametric path specified as in the 
\macro{parafcn} macro, but using a polygonal path instead.

\vskip\myskip
\noindent\macro{shadefcn}[\<xmin\>,\<xmax\>]%
[\<expr0\>][\<expr1\>]

\nobreak
This macro draws the shaded region between the two
functions $f(x)=$\<expr0\> and $g(x)=$\<expr1\>, where
\<expr0\> and \<expr1\> are written with the only unknown
being {\tt x}, bounded also by the vertical lines at
\<xmin\> and \<xmax\>.  The functions $f$ and $g$ can
{\it not} be allowed to cross between \<xmin\> and
\<xmax\>.  The expressions  \<expr0\> and \<expr1\> are
passed directly into the corresponding \MF\ macro, as in
the \macro{function} macro, so the same operations are
available.  The spacing between dots is determined as in
the \macro{shaderect} macro.

\subhead{Labels and Captions.}

\vskip\myskip
The next two macros do not affect the \MF\ file
({\tt\<font\>.mf}) at all, but are added to the picture
by \TeX.  Therefore, if these macros are changed or added
in your document, there is no need to repeat either of
the last two steps (processing with \MF\ or reprocessing
with \TeX) in order to complete your \TeX\ document.

\vskip\myskip
\noindent\macro{label}[?\<orient\>][\<x\>][\<y\>]%
[\<label text\>]

\nobreak 
This macro places a \TeX\ label on the graph.  Without
the {\tt [\<orient\>]} parameter, the label is placed
with the lower left-hand corner of the label at the point
{\tt (\<x\>,\<y\>)}.  Note the different format of the
point specification from the other {\tt mfpic} macros --
this is because \macro{label} does not use \MF\ to place
the label, but instead uses \TeX\ \macro{kern} commands. 
The optional parameter {\tt [\<orient\>]} specifies the
relative placement of the label with respect to the point
{\tt (\<x\>,\<y\>)} -- \<orient\> is a two-character
sequence where the first character is one of {\tt t}
(top), {\tt c} (center), or {\tt b} (bottom), to specify
vertical placement, and the second character is one of
{tt l} (left), {\tt c} (center), or {\tt r} (right), to
specify horizontal placement.  The default orientation is
equivalent to specifying {\tt [bl]}.

\vskip\myskip
\noindent\macro{caption}[\<x\>][\<y\>][\<caption text\>]

\nobreak
This macro places a caption at the bottom of the graph. 
The caption text can also include the macro
{\tt\string\\}, which forces a line break in the caption.

\subhead{For Power Users Only.}

\vskip\myskip
\noindent\macro{mfcmd}[\<command text\>]

\nobreak
This macro writes the \<command text\> directly to the
Metafont file, using a \TeX\ \macro{write} command.  This
can have some rather bizarre consequences, though, so
using it is not recommended.

\head{Using {\tt mfpic} with \LaTeX.}

For \LaTeX\ users, a short header file, 
{\tt lamfpic.tex}, has been provided, which inputs 
{\tt mfpic.tex} and uses the commands defined there to
set up a new \LaTeX\ environment called {\tt mfpic},
making sure in the process that the new environment does
not clash with the \LaTeX\ {\tt picture} environment.  So
instead of using the {\tt\string\picture} and
\macro{endpicture} macros, you would use
\macro{begin}[mfpic] and \macro{end}[mfpic] A La\TeX\
version of the sample file, {\tt lapictures.tex}, has
also been provided.  Note that the \macro{opengraphsfile}
and \macro{closegraphsfile} macros have {\it not} been
converted into a \LaTeX\ environment.

\head{Acknowledgements.}

I would like to thank all of the people here at Dartmouth
as well as out in the network world for testing {\tt
mfpic} and sending me back comments.  I would
particularly like to thank Geoffrey Tobin
(ecsgrt@luxor.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 I managed to teach each other many of the
subtleties of \MF); and Bryan Green
(bgreen@sanjuan.uvic.ca) for his many suggestions, some
of which (including his rewriting the \macro{caption}
macro) ultimately led to the current version's ability to
put graphs in-line or side-by-side.

\head{Changes History.}

\noindent{\it Version 0.0.x:}  Development versions.  
Never released.
\par\noindent{\it Version 0.1:}  First version released 
to network, 6/30/1992.
\par\noindent{\it Version 0.1.x:}  Test versions for new 
features, fixes, etc.
None of them were released for general distribution.  
Many new features added, bugs
worked out, code cleaned up.
\par\noindent{\it Version 0.2:}  Second version released 
to network, 9/7/1992.

\end



