%%%
%%%  File: mfpicdoc.tex
%%%  Version:  0.25
%%%  Date:  Tue 26 Oct 1993
%%%
%%%  Principal Author - Thomas E. Leathrum
%%%  Assistant        - Geoffrey Tobin
%%%

\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 mfpic --- Pictures in \TeX\ with Metafont --- version 0.25}

\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
(formerly 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.}

Seven files are included in the {\tt mfpic} distribution:\hfil\break
\hbox{}\kern 1cm   {\tt mfpicdoc.tex} (this document, which can be processed
in plain \TeX),\hfil\break
\hbox{}\kern 1cm    {\tt mfpic.tex} (the \TeX\ macros),\hfil\break
\hbox{}\kern 1cm    {\tt graphbase.mf} (the \MF\ macros),\hfil\break
\hbox{}\kern 1cm    {\tt objects.tex} (a sample file containing at least one
picture of each object),\hfil\break
\hbox{}\kern 1cm    {\tt pictures.tex} (a short sample file with a few more
complicated pictures),\hfil\break
\hbox{}\kern 1cm    {\tt lamfpic.tex} (an outmoded short header file
for LaTeX, which now merely inputs mfpic.tex, and remains solely for
backward compatibility), and\hfil\break
\hbox{}\kern 1cm    {\tt lapictures.tex} (the \LaTeX\ version of
{\tt pictures.tex}).\hfil\break
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 two 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{mflabel}'s and
\macro{mfcaption}'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{mfpicture}[?\<xscale\>][?\<yscale\>]%
[\<xneg\>][\<xpos\>][\<yneg\>][\<ypos\>]
$\dots$\macro{endmfpicture}

\nobreak
These macros open and close the environment in which the rest of the
macros below make sense.
The \macro{mfpicture} macro also sets up the local coordinate system
for the picture.
The \<xscale\> and \<yscale\> parameters establish the length of the
coordinate system units, as multiples of the user-settable dimension
\macro{mfpicunit} which is initially one \TeX\ point ({\tt 1pt}).
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 backward compatibility with version {\tt 0.2} of {\tt mfpic}, if
\macro{picture} is {\it not} already defined, then it is let equal to
\macro{mfpicture}, and \macro{endpicture} is let equal to
\macro{endmfpicture}.
Also, the macros \macro{mfpic} and \macro{endmfpic} are provided as
abbreviations for \macro{mfpicture} and \macro{endmfpicture},
respectively.

\vskip\myskip
For the remainder of the macros, the numerical parameters
are expressed in the units of the local coordinate system
specified by \macro{mfpicture}, 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 (tic) 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{mfpicture} $\dots$
\macro{endmfpicture} 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 (tic) 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} and other shading
macros.  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{polyline}[(\<xval0\>,\<yval0\>),%
(\<xval1\>,\<yval1\>),$\dots$]

\nobreak
This macro draws a piecewise linear path through the points
specified, in the order specified.
For backward compatibility with version {\tt 0.2},
\macro{polycurve} is let equal to \macro{polyline},
but {\tt polyline} is recommended as a more descriptive name.

\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; the function step size is
the same distance.

\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{mflabel}[?\<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{mflabel} 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]}.
The macro \macro{label} has been let equal to \macro{mflabel} for
backward compatibility with version {\tt 0.2}.

\vskip\myskip
\noindent\macro{mfcaption}[\<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.
The macro \macro{caption} has been let equal to \macro{mfcaption}
for backward compatibility.

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

{\tt mfpic.tex} is now \LaTeX\ compatible.  Since \LaTeX{} uses
{\tt picture} for {\it its} {\tt picture} environment, the name
{\tt mfpicture} is now preferred for an mfpic picture:\hfil\break
\hbox{}\kern 1cm
    \macro{begin}[mfpicture]$\dots$\macro{end}[mfpicture]\hfil\break
An abbreviation `{\tt mfpic}' is provided for `{\tt mfpicture}'.
The file {\tt lamfpic.tex} remains solely for backward compatibility,
and it now consists merely of the command {\tt\string\input{} mfpic}.
A \LaTeX\ 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{In the \LaTeX{} {\tt center} environment.}

To center an {\tt mfpic} picture within a \LaTeX\ {\tt center}
environment, go into horizontal mode after the {\tt center}.
For example, using \macro{noindent}:\hfil\break
\hbox{}\kern 1cm	\macro{begin}[center]\hfil\break
\hbox{}\kern 1cm	\macro{noindent}\hfil\break
\hbox{}\kern 1cm	\macro{begin}[mfpic]\dots\hfil\break
\hbox{}\kern 1cm	\dots\hfil\break
\hbox{}\kern 1cm	\macro{end}[mfpic]\hfil\break
\hbox{}\kern 1cm	\macro{end}[center]\hfil\break
Instead of the \TeX\ primitive \macro{noindent}, the plain \TeX\ macro
\macro{leavevmode} may be used.  The drawing is positioned in the
same place in both cases.
Unfortunately, experiments showed that the following device:\hfil\break
\hbox{}\kern 1cm	\macro{ifvmode}\hfil\break
\hbox{}\kern 2cm	\macro{leavevmode}\hfil\break
\hbox{}\kern 1cm	\macro{fi}\hfil\break
within {\tt mfpic.tex} to accommodate a possible enclosing \LaTeX{}
{\tt center} environment, creates an hbox of excessive width, and that
foils the use of {\tt mfpic} in such valuable situations as placing
two pictures side-by-side.  So mfpic users must deal with the \LaTeX{}
{\tt center} environment by inserting \macro{noindent} or
\macro{leavevmode} themselves.

\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{mfcaption}
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, Tue 30 June 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, Mon 7 September 1992.
\par\noindent{\it Version 0.25:}  Bug fixes:  Picture TFM detection,
LaTeX picture environment respected, fractional scales, @ catcode
restored, sharp character for MF file, bad mflabel options detected,
MF char codes out of range (0 to 255) detected.

Tue 12 October 1993.

\end

