%%% 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}[\]$\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\.mf}. If the \ parameter is changed, you will have to reprocess the \TeX\ file after processing {\tt\.mf}. \vskip\myskip \noindent\macro{picture}[?\][?\]% [\][\][\][\] $\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 \ and \ 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 \ and \ parameters establish the lower and upper (resp.) bounds for the $x$-axis coordinates; similarly, \ and \ 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 \$\cdot$(\$-$\) 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\.tfm} file will be affected, so you will have to reprocess the \TeX\ file after processing {\tt\.mf}. \vskip\myskip The rest of the {\tt mfpic} macros do not affect the font metric file ({\tt\.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}[(\,\)] \nobreak This macro draws a small filled circle centered at the point {\tt (\,\)}. 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}[(\,\),% (\,\)] \nobreak This macro draws the line segment with endpoints at the points {\tt (\,\)} and {\tt (\,\)}. \vskip\myskip \noindent\macro{arrow}[(\,\),% (\,\)] \nobreak This macro draws an arrow starting from the point {\tt (\,\)} and pointing to the point {\tt (\,\)}. 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}[(\,\),% (\,\)] \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}[(\,\),% (\,\)] \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}[\,\,$\dots$] and \macro{ymarks}[\,\,$\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}[(\,\),% (\,\)] \nobreak This macro draws the rectangle specified by the given points {\tt (\,\)} and {\tt (\,\)} being any two opposite corners of the rectangle. \vskip\myskip \noindent\macro{dottedrect}[(\,\),% (\,\)] \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}[(\,\),% (\,\)] \nobreak This macro draws the filled rectangle specified as in the \macro{rect} macro. \vskip\myskip \noindent\macro{rectshade}[(\,\),% (\,\)] \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}[(\,\),% (\,\),$\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}[(\,\),% (\,\),$\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}[(\,\),% (\,\),$\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}[\] \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}[\][\] \nobreak This macro establishes the shape of the arrowhead drawn by the \macro{arrow} and \macro{axes} macros. The value of \ is the ratio of the width of the arrowhead to its length, and \ 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}[(\,\),\] \nobreak This macro draws a circle centered at the point {\tt (\,\)} and with radius \. \vskip\myskip \noindent\macro{circshade}[(\,\),\] \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}[(\,\),\] \nobreak This macro draws a filled circle, determined as in the \macro{circle} macro. \vskip\myskip \noindent\macro{ellipse}[(\,\),% \,\] \nobreak This macro draws an ellipse with the $x$ radius \ and $y$ radius \, centered at the point {\tt (\,\)}. \vskip\myskip \noindent\macro{ellshade}[(\,\),% \,\] \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}[(\,\),% \,\] \nobreak This macro draws a filled ellipse, determined as in the \macro{ellipse} macro. \vskip\myskip \noindent\macro{rotatedellipse}[(\,\),% \,\,\] \nobreak This macro draws an ellipse with the $x$ radius \ and $y$ radius \ (before rotation), centered at the point {\tt (\,\)}, and rotated around its center by the angle \ (expressed in degrees). \vskip\myskip \noindent\macro{rotatedellshade}[(\,\),% \,\,\] \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}[(\,\),% \,\,\] \nobreak This macro draws a filled ellipse, determined as in the \macro{rotatedellipse} macro. \subhead{Circular Arcs.} \vskip\myskip \noindent\macro{arc}[(\,\),% (\,\),\] \nobreak This macro draws a circular arc starting from the point {\tt (\,\)}, ending at the point {\tt (\,\)}, and covering an arc angle of \ degrees, measured counterclockwise around the center of the circle. If, for example, the points {\tt (\,\)} and {\tt (\,\)} lie on a horizontal line with {\tt (\,\)} to the left, and \ 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 \ give arcs curving in the other direction. \vskip\myskip \noindent\macro{arcarrow}[(\,\),% (\,\),\] \nobreak This marco draws an arc, specified as in the \macro{arc} macro, with an arrowhead placed at the {\tt (\,\)} end. The shape and size of the arrowhead are the same as in the \macro{arrow} macro. \vskip\myskip \noindent\macro{arcshade}[(\,\),% (\,\),\] \nobreak This macro shades the region enclosed by the arc, specified as in the \macro{arc} macro, and the line segment between {\tt (\,\)} and {\tt (\,\)}. The spacing between dots is determined as in the \macro{shaderect} macro. \vskip\myskip \noindent\macro{arcfill}[(\,\),% (\,\),\] \nobreak This macro fills the region specified as in the \macro{arcshade} macro. \subhead{Polar Coordinates.} \vskip\myskip \noindent\macro{linedir}[(\,\),% \,\] \nobreak This macro draws a line segment starting from the point {\tt (\,\)} and going in the direction specified by \, where \ is an angle measured in degrees counterclockwise from the direction parallel to the positive $x$ axis, and with length \. \vskip\myskip \noindent\macro{arrowdir}[(\,\),% \,\] \nobreak This macro draws an arrow starting from the point {\tt (\,\)} and going in the direction specified by \, where \ is an angle measured in degrees counterclockwise from the direction parallel to the positive $x$ axis, with length \, and with an arrowhead at the end opposite the point {\tt (\,\)}. The size and shape of the arrowhead are determined as in the \macro{arrow} macro. \vskip\myskip \noindent\macro{arcth}[(\,\),% \,\,\] \nobreak This macro draws the arc with center at the point {\tt (\,\)}, of radius \, from the angle \ to the angle \, where both angles are measured in degrees counterclockwise from the direction parallel to the $x$ axis. \vskip\myskip \noindent\macro{arctharrow}[(\,\),% \,\,\] \nobreak This macro draws an arc arrow, with the arc specified as in the \macro{arcth} macro. \vskip\myskip \noindent\macro{wedgeshade}[(\,\),% \,\,\] \nobreak This macro shades the wedge-shaped region, from the angle \ to the angle \ inside the circle with center at the point {\tt (\,\)} and radius \, 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}[(\,\),% \,\,\] \nobreak This macro fills the wedge-shaped region specified as in the \macro{wedgeshade} macro. \subhead{Curves.} \vskip\myskip \noindent\macro{curve}[(\,\),% (\,\),$\dots$] \nobreak This macro draws a \MF\ Bezier path through the points specified, in the order specified. \vskip\myskip \noindent\macro{polycurve}[(\,\),% (\,\),$\dots$] \nobreak This macro draws a polygonal path through the points specified, in the order specified. \vskip\myskip \noindent\macro{curvedarrow}[(\,\),% (\,\),$\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}[(\,\),% (\,\),$\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}[(\,\),% (\,\),$\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}[(\,\),% (\,\),$\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}[(\,\),% (\,\),$\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}[\,\,% \,\] \nobreak This macro plots the function determined by $f(x)=$\, where \ is written with the only unknown being {\tt x}, using as $x$ values the points starting with \ and stepping by \ until reaching \. 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 \: \ else: \ fi}. Relations available for the \ part of the expression include {\tt =}, {\tt <}, {\tt >}, {\tt <=}, and {\tt >=}. \vskip\myskip \noindent\macro{polyfunction}[\,\,% \,\] \nobreak This macro plots the function determined by $f(x)=$\, as in the \noindent\macro{function} macro, but using a polygonal path instead. \vskip\myskip \noindent\macro{parafcn}[\,\,\,% (\,\)] \nobreak This macro plots the parametric path determined by $(x(t),y(t))=${\tt (\,\)}, where \ and \ are written with the only unknown being {\tt t}, using as $t$ values the points starting with \ and stepping by \ until reaching \. The function is interpolated with a \MF\ Bezier path. The expressions \ and \ 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}[\,\,% \,(\,\)] \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}[\,\]% [\][\] \nobreak This macro draws the shaded region between the two functions $f(x)=$\ and $g(x)=$\, where \ and \ are written with the only unknown being {\tt x}, bounded also by the vertical lines at \ and \. The functions $f$ and $g$ can {\it not} be allowed to cross between \ and \. The expressions \ and \ 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\.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}[?\][\][\]% [\