% $Id: mpintro.tex 822 2009-01-07 10:17:10Z stephanhennig $ % MetaPost doc, by John Hobby. \documentclass{article} \usepackage{graphicx} \usepackage{ifpdf} \ifpdf \else \DeclareGraphicsExtensions{.mps} \DeclareGraphicsRule{mps}{eps}{*}{} \fi \author{John D. Hobby} \title{The MetaPost System} \font\textt=cmtex10 \makeatletter \def\logo{\global\font\logo=logo10 at1\@ptsize\p@ \logo} \def\logosl{\global\font\logosl=logosl10 at1\@ptsize\p@ \logosl} \def\MF{{\ifdim \fontdimen\@ne\font >\z@ \def\logo{\logosl}\fi {\logo META}\-{\logo FONT}}} \makeatother \def\descr#1{{\langle\hbox{#1}\rangle}} \def\lit#1{{\hbox{\textt#1}}} \def\okbreak{\vfil\penalty2000 \vfilneg} {\obeylines\obeyspaces\gdef\startverbatim{% \vcenter\bgroup\textt\catcode`\$=12\catcode`\}=12\catcode`\{=12\catcode`\_=12% \catcode`\\=12\catcode`\#=12\catcode`\^=12\catcode`\%=0% \obeyspaces\let =\ \obeylines\let^^M=\cr\halign\bgroup##\hfil}} \def\stopverbatim{\egroup\egroup} \begin{document} \maketitle \begin{abstract} The MetaPost system implements a picture-drawing language very much like Knuth's \MF\ except that it outputs PostScript commands instead of run-length-encoded bitmaps. MetaPost is a powerful language for producing figures for documents to be printed on PostScript printers. It provides easy access to all the features of PostScript and it includes facilities for integrating text and graphics. This document describes the system and its implementation. It also includes basic user documentation to be used in conjunction with {\it The \MF book}. Much of the source code was copied from the \MF\ sources by permission from the author. \end{abstract} \section{Overview} The MetaPost system is based on Knuth's \MF\footnote{\MF\ is a trademark of Addison Wesley Publishing company.}~\cite{kn:c} and much of the source code is copied with permission from the \MF\ sources. MetaPost is a graphics language like \MF, but with new primitives for integrating text and graphics and for accessing special features of PostScript\footnote{PostScript is a trademark of Adobe Systems Inc.} such as clipping, shading, and dashed lines. The language has the main features of \MF\ including first-class objects for curves, pictures, affine transformations, and pen shapes. Another feature borrowed from \MF\ is the ability to solve linear equations that are given implicitly, thus allowing many programs to be written in a largely declarative style. While MetaPost could be used as a tool for generating PostScript fonts, the intended application is to generate figures for \TeX\footnote{\TeX\ is a trademark of the American Mathematical Society.} and {\it troff\/} documents. The figures can be integrated into a \TeX\ document via a freely available program called {\tt dvips} as shown in Figure~1.\footnote{The C source for {\tt dvips} comes with the web2c \TeX\ distribution. Similar programs are available from other sources.} A similar procedure works with troff: the {\tt grops} output processor includes PostScript figures when they are requested via troff's {\tt \char`\\X} command. \begin{figure}[htp] \centering \includegraphics{mpman-0} \caption{A diagram of the processing for a \TeX\ document with figures done in Meta\-Post} \end{figure} Other than the new commands for integrating text and accessing features of PostScript, the main difference between the \MF\ and MetaPost languages is that the latter deals with continuous pictures rather than discrete ones. This affects the coordinate system and some of the subtler aspects of the language as outlined in the next two sections. Sections \ref{basic} and \ref{advanced} give a short summary of the language with numerous examples. Then Section~\ref{impsec} describes the implementation. A preliminary description of the language has already appeared~\cite{ho:mp1}. \section{Introduction to MetaPost} \label{basic} MetaPost is a lot like Knuth's \MF\ except that it outputs PostScript programs instead of bitmaps. Knuth describes the \MF\ language in {\sl The \MF book\/}.~\cite{kn:d} This document introduces MetaPost via examples and references to key parts of {\sl The \MF book}. It is a good idea to start by reading chapters 2~and 3 in {\sl The \MF book}. The introductory material in these chapters applies to MetaPost except that coordinates are in units of PostScript points by default (72 units per inch). To see MetaPost in action, consider a file \lit{fig.mp} containing the following text:\vadjust{\okbreak} $$ \startverbatim beginfig(1); a=.7in; b=0.5in; z0=(0,0); z1=(a,0); z2=(0,b); z0=.5[z1,z3]=.5[z2,z4]; draw z1..z2..z3..z4..cycle; drawarrow z0..z1; drawarrow z0..z2; label.top(btex $a$ etex, .5[z0,z1]); label.lft(btex $b$ etex, .5[z0,z2]); endfig; end %stopverbatim$$ Then the command \lit{mp} \lit{fig} produces an output file \lit{fig.1} that can be included in a \TeX\ document.\footnote{For importing MetaPost graphics into \LaTeX\ documents please refer to section \emph{Using MetaPost graphics in \TeX, \LaTeX, pdf\LaTeX, pdf\TeX, Con\TeX{}t and troff} in the MetaPost manual.} After \lit{\string\input} \lit{epsf} the \TeX\ commands \lit{\$\$\string\epsfbox\char`\{fig.1\char`\}\$\$} produce $$ \includegraphics{mpintro-1} $$ The \lit{beginfig(1)} line means that everything up to the next \lit{endfig} is to be used to create \lit{fig.1}. If there were more than one figure in \lit{fig.mp}, there would be additional \lit{beginfig} $\ldots$ \lit{endfig} blocks. The \lit{drawarrow} macro has been specially developed for MetaPost. There is also a command called \lit{drawdblarrow} that draws the following path with arrowheads on both ends. The line beginning with \lit{label.top} is a call to a standard macro for positioning text just above a given point. In this case, the point \lit{.5[z0,z1]} is the midpoint of the segment from \lit{z0} to \lit{z1} and the text is generated by the \TeX\ commands \lit{\$a\$}. In addition to \lit{label.top} and \lit{label.lft}, there is also \lit{label.bot}, \lit{label.rt}, and four other versions \lit{label.ulft} for upper-left etc. Just plain \lit{label} without any suffix centers the label on the given point. The discussion of pens in Chapter~4 of {\sl The \MF book\/} applies to MetaPost as well, but simple figures often do not need to refer to pens explicitly because they can just use the default pen which is a circle $0.5{\it bp}$ in diameter.\footnote{The letters ``{\it bp}'' stand for ``big point'' ($1\over72$ inch). This is one of the standard units of measure in \TeX\ and \MF\ and it is the default unit for MetaPost. A complete listing of predefined units is given on page~92 of {\sl The \MF book}.} This produces lines of uniform thickness $0.5{\it bp}$ regardless of the direction of the line. Chapter 5 of {\sl The \MF book\/} does not apply to MetaPost. In particular, there is no \lit{mode\_setup} macro or ``sharped units'' and \lit{mp} does not output \lit{gf} files. MetaPost does have a set of preloaded macros but they are not the same as \MF's plain base. If there were an analogous chapter about running MetaPost, it would probably mention that \lit{mp} skips over \lit{btex} $\ldots$ \lit{etex} blocks and depends on a preprocessor to translate them into low level MetaPost commands. If the main file is \lit{fig.mp}, the translated \TeX\ material is placed in a file named \lit{fig.mpx}. This is normally done silently without any user intervention but it could fail if one of the \lit{btex} $\ldots$ \lit{etex} blocks contains an erroneous \TeX\ command. If this happens, the erroneous \TeX\ input is saved in the file \lit{mpxerr.tex} and the error messages appear in \lit{mpxerr.log}. If there is a need for \TeX\ macro definitions or any other auxiliary \TeX\ commands, they can be enclosed in a \lit{verbatimtex} $\ldots$ \lit{etex} block. The difference between \lit{btex} and \lit{verbatimtex} is that the former generates a picture expression while the latter does not. On Unix systems, an environment variable can be used to specify that \lit{btex} $\ldots$ \lit{etex} and \lit{verbatimtex} $\ldots$ \lit{etex} blocks are in {\it troff\/} instead of \TeX. When using this option, it is a good idea to give the MetaPost command \lit{prologues:=1}. This tells \lit{mp} to output structured PostScript and assume that text comes from built-in PostScript fonts. Chapters 6--10 of {\sl The \MF book\/} cover important aspects of \MF\ that are almost identical in MetaPost. The only change to the tokenization process described in Chapter~6 is that \TeX\ material can contain percent signs and unmatched double quote characters so these are treated like spaces when skipping \TeX\ material. The preprocessor gives \TeX\ everything between \lit{btex} and \lit{etex} except for leading and trailing spaces. Chapters 7--10 discuss the types of variables and expressions that \MF\ understands. MetaPost has an additional type ``\lit{color}'' that is a lot like \lit{pair} except that it has three components instead of two. The operations allowed on colors are addition, subtraction, scalar multiplication, and scalar division. MetaPost also understands mediation expressions involving colors since \lit{.3[w,b]} is equivalent to \lit{w+.3(b-w)} which is allowed even when \lit{w} and \lit{b} are colors. Colors can be specified in terms of the predefined constants \lit{black}, \lit{white}, \lit{red}, \lit{green}, \lit{blue}, or the red, green, and blue components can be given explicitly. Black is \lit{(0,0,0)} and white is \lit{(1,1,1)}. There is no restriction against colors ``blacker than black'' or ``whiter than white'' except all components are snapped back to the $[0,1]$ range when a color is given in an output file. MetaPost solves linear equations involving colors the same way it does so for pairs. (This is explained in Chapter~9). Let's consider another example that uses some of the ideas discussed above. The MetaPost program\vadjust{\okbreak} $$ \startverbatim beginfig(2); h=2in; w=2.7in; path p[], q[], pp; for i=1.5,2,4: ii:=i**2; p[i] = (w/ii,h){1/ii,-1}...(w/i,h/i)...(w,h/ii){1,-1/ii}; endfor for i=.5,1.5: q[i] = origin..(w,i*h) cutafter p1.5; endfor pp = buildcycle(q0.5, p2, q1.5, p4); fill pp withcolor .8white; z0=center pp; picture lab; lab=thelabel(btex $f>0$ etex, z0); unfill bbox lab; draw lab; draw q0.5; draw p2; draw q1.5; draw p4; makelabel.top(btex $P$ etex, p2 intersectionpoint q0.5); makelabel.rt(btex $Q$ etex, p2 intersectionpoint q1.5); endfig; %stopverbatim$$ produces the following figure:\vadjust{\okbreak} $$ \includegraphics{mpintro-2} $$ The third line declares arrays of paths \lit{p} and \lit{q} as explained in Chapter~7. Note that \lit{q1.5} is the same as \lit{q[i]} when $\lit{i}=1.5$. The \lit{for} loops make each \lit{p[i]} an approximation to an arc of the hyperbola $$xy={wh\over i^2} $$ and each \lit{q[i]} a segment of slope $ih/w$. (Loops are discussed in Chapter~19 of {\sl The \MF book\/}). The \lit{cutafter} operator is used to cut off the part of \lit{q[i]} after the intersection with \lit{p1.5}. (There is no ``\lit{draw} \lit{p1.5}'' in the input for the above figure so this hyperbola is invisible). There is also a \lit{cutbefore} operator defined to make $$ a \lit{ cutbefore } b $$ what's left of path~$a$ when everything before its intersection with~$b$ is removed. In case of multiple intersections \lit{cutbefore} and \lit{cutafter} try to cut off as little as possible. The shaded region in the above figure is due to the line $$ \lit{fill pp withcolor .8white} $$ The boundary of this region is the path \lit{pp} that the \lit{buildcycle} macro creates by piecing together the four paths given as arguments. In other words, \lit{pp} is constructed by going along \lit{q0.5} until it intersects \lit{p2}, then going along \lit{p2} until hitting \lit{q1.5}, etc. It turns out that this requires going backwards along \lit{p2} and \lit{q1.5}. The \lit{buildcycle} macro tries to avoid going backwards if it has a choice as to which intersection points to choose, but in this example each pair of consecutive path arguments has a unique intersection point. It is generally a good idea to avoid multiple intersections because they can lead to unpleasant surprises. The \lit{fill} and \lit{unfill} macros in plain MetaPost are similar to the corresponding macros discussed in Chapter~13 of {\sl The \MF book\/} but MetaPost assigns colors to regions rather than assigning weights to pixels. There is no \lit{cull} command or \lit{withweight} option in MetaPost. The \lit{unfill} macro used to erase the rectangle containing the label ``$f>0$'' in the above figure works by specifying ``\lit{withcolor} \lit{background}'' where \lit{background}'' is usually equal to \lit{white}. The complete syntax for primitive drawing commands in MetaPost is as follows: $$\tabskip=0.0pt plus 1000.0pt minus 1000.0pt \halign to\hsize{$#$\hfil\cr \descr{picture command} \rightarrow \descr{addto command} \mid \descr{clip command} \cr \descr{addto command} \rightarrow {} \cr \qquad \lit{addto }\descr{picture variable} \lit{ also } \descr{picture expression} \descr{with list} \cr \qquad {}\mid \lit{addto } \descr{picture variable} \lit{ contour } \descr{path expression} \descr{with list} \cr \qquad {}\mid \lit{addto } \descr{picture variable} \lit{ doublepath } \descr{path expression} \descr{with list} \cr \descr{with list} \rightarrow \descr{empty} \mid \descr{with clause} \descr{with list} \cr \descr{with clause} \rightarrow \lit{withcolor } \descr{color expression}\cr \qquad {} \mid \lit{withpen } \descr{pen expression} \mid \lit{dashed } \descr{picture expression}\cr \descr{clip command} \rightarrow \lit{clip } \descr{picture variable} \lit{ to } \descr{path expression} \cr} $$ If $P$ stands for \lit{currentpicture}, $q$ stands for \lit{currentpen}, and $b$ stands for \lit{background}, the standard drawing macros have roughly the following meanings: $$ \tabskip=0.0pt plus 1000.0pt minus 1000.0pt \halign to\hsize{$#$\hfil&\quad means\quad $#$\hfil\cr \lit{draw }p& \lit{addto }P\lit{ doublepath }p\lit{ withpen }q\cr \lit{fill }c& \lit{addto }P\lit{ contour }c\cr \lit{filldraw }c& \lit{addto }P\lit{ contour }c\lit{ withpen }q\cr \lit{undraw }p& \lit{addto }P\lit{ doublepath }p\lit{ withpen }q \lit{ withcolor }b\cr \lit{unfill }c& \lit{addto }P\lit{ contour }c\lit{ withcolor }b\cr \lit{unfilldraw }c& \lit{addto }P\lit{ contour }c\lit{ withpen }q \lit{ withcolor }b\cr} $$ The expressions denoted by $c$ in the table must be cyclic paths, while path expressions $p$ need not be cyclic. It is also possible to use \lit{draw} and \lit{undraw} when the argument is a picture~$r$: $$ \tabskip=0.0pt plus 1000.0pt minus 1000.0pt \halign to\hsize{$#$\hfil&\quad means\quad $#$\hfil\cr \lit{draw }r& \lit{addto }P\lit{ also }r\cr \lit{undraw }r& \lit{addto }P\lit{ also }r\lit{ withcolor }b\cr} $$ The argument to \lit{unfill} in the last example is \lit{bbox lab}. This is a call to a standard macro that gives the bounding box of a picture as a rectangular path. The \lit{center} macro used two lines previously makes \lit{z0} the center of the bounding box for path \lit{pp}. (This works for paths and pictures). The expression $$ \lit{thelabel(btex \$f>0\$ etex, z0)} $$ computes a picture containing the text ``$f>0$'' centered on the point \lit{z0}. Here is the complete syntax for labeling commands: $$\tabskip=0.0pt plus 1000.0pt minus 1000.0pt \halign to\hsize{$#$\hfil\cr \descr{label command} \rightarrow \descr{command name} \descr{position suffix} (\descr{label text},\ \descr{label loc}) \cr \qquad {}\mid \lit{labels} \descr{position suffix} (\descr{suffix list}) \cr \descr{command name} \rightarrow \lit{label} \mid \lit{thelabel} \mid \lit{makelabel} \cr \descr{position suffix} \rightarrow \descr{empty} \mid \lit{.lft} \mid \lit{.rt} \mid \lit{.top} \mid \lit{.bot} \cr \qquad {}\mid \lit{.ulft} \mid \lit{.urt} \mid \lit{.llft} \mid \lit{.lrt}\cr \descr{label text} \rightarrow \descr{picture expression} \mid \descr{string expression} \cr \descr{label loc} \rightarrow \descr{pair expression} \cr \descr{suffix list} \rightarrow \descr{suffix} \mid \descr{suffix}, \descr{suffix list} \cr} $$ The \lit{label} command adds text to \lit{currentpicture} near the position $\descr{label loc}$ as determined by the $\descr{position suffix}$. An empty suffix centers the label and the other options offset it slightly so that it does not overlap the $\descr{label loc}$. Using \lit{thelabel} just creates a picture expression rather than actually adding it to \lit{currentpicture}. Using \lit{makelabel} instead of \lit{label} adds a dot at the location being labeled. Finally, the \lit{labels} command does $$ \lit{makelabel} \descr{position suffix} (\lit{str}\,\descr{suffix},\,\lit{z}\descr{suffix}) $$ for each $\descr{suffix}$ in the $\descr{suffix list}$, using the \lit{str} operator to convert the suffix to a string. Thus \lit{labels.top(1,2a)} places labels ``\lit{1}'' and ``\lit{2a}'' just above \lit{z1} and \lit{z2a}. The examples given so far have all used $\descr{label text}$ of the form $$ \lit{btex}\ \descr{\TeX\ commands}\ \lit{etex}. $$ This gets converted into a picture expression. If the label is simple enough, it can be given directly as a string expression in which case it is typeset in \lit{defaultfont} at \lit{defaultscale} times its design size. Normally, $$ \lit{defaultfont="cmr10"} \quad{\rm and}\quad \lit{defaultscale=1}, $$ but these can be reset if desired. Using \lit{cmtex10} instead of \lit{cmr10} would allow the label to contain spaces and special characters. If there is any doubt about what the design size is, use the \lit{fontsize} operator to find it as follows: $$ \lit{defaultfont:="Times";} \qquad \lit{defaultscale:=10/fontsize "Times"} $$ Notice that a $\descr{with clause}$ can be ``\lit{dashed} $\descr{picture expression}$.'' The picture gives a template that tells how the line being drawn is to be dashed. There is a standard template called \lit{evenly} that makes dashes $3bp$ long separated by gaps of length $3bp$. It is possible to scale the template in order to get a finer or coarser pattern. Thus $$ \lit{draw z1..z2 dashed evenly scaled 2} $$ draws a line with dashes $6bp$ long with gaps of $6bp$. The following MetaPost input illustrates the use of dashed lines:\vadjust{\okbreak} $$ \startverbatim beginfig(3); 3.2scf = 2.4in; path fun; # = .1; fun = ((0,-1#)..(1,.5#){right}..(1.9,.2#){right} ..{curl .1}(3.2,2#)) scaled scf yscaled(1/#); vardef vertline primary x = (x,-infinity)..(x,infinity) enddef; primarydef f atx x = (f intersectionpoint vertline x) enddef; primarydef f whenx x = xpart(f intersectiontimes vertline x) enddef; z1a = (2.5scf,0); z1 = fun atx x1a; y2a=0; z1-z2a=whatever*direction fun whenx x1 of fun; z2 = fun atx x2a; y3a=0; z2-z3a=whatever*direction fun whenx x2 of fun; draw fun withpen pencircle scaled 1pt; drawarrow (0,0)..(3.2scf,0); label.bot(btex $x_1$ etex, z1a); draw z1a..z1 dashed evenly; makelabel(nullpicture, z1); draw z1..z2a withpen pencircle scaled .3; label.bot(btex $x_2$ etex, z2a); draw z2a..z2 dashed evenly; makelabel(nullpicture, z2); draw z2..z3a withpen pencircle scaled .3; label.bot(btex $x_3$ etex, z3a); endfig; %stopverbatim$$ This produces the following figure:\vadjust{\okbreak} $$ \includegraphics{mpintro-3} $$ The above figure uses some of the more advanced properties of paths discussed in Chapter~14 of {\sl The \MF book}. All of this material applies to MetaPost as well as \MF\ except for the explanation of ``strange paths'' which fortunately cannot occur in MetaPost. The parts most relevant to this figure are the explanation of ``curl'' specifications and the \lit{direction}, \lit{intersectiontimes}, and \lit{intersectionpoint} operators. In order to ensure that the path \lit{fun} makes $y$ a unique function of~$x$, the path is first constructed with the $y$-coordinates compressed by a factor of ten. The final ``\lit{yscaled(1/\char`\#)}'' restores the original aspect ratio after MetaPost has chosen a cubic spline that interpolates the given points. The \lit{yscaled} operator is an example of a very important class of operators that apply affine transformations to pairs, paths, pens, pictures, and other transforms. The discussion in Chapter~15 is relevant and important. The only differences are that MetaPost has no {\it currenttransform} and there is no restriction on the type of transformations that can be applied to pictures. \section{More Advanced Topics} \label{advanced} MetaPost does have pens like those in \MF\ but they aren't very important to the casual user except occasionally to specify changes in line widths as in the preceding figure. Anyone reading the description in Chapter~16 of {\sl The \MF book} should beware that there is no such thing as a ``future pen'' in MetaPost and elliptical pens are never converted into polygons. Furthermore, there is no need for \lit{cutoff} and \lit{cutdraw} because the same effect can be achieved by setting the internal parameter \lit{linecap:=butt}.\vadjust{\okbreak} $$\startverbatim beginfig(4); for i=0 upto 2: z[i]=(0,40i); z[i+3]-z[i]=(100,30); endfor pickup pencircle scaled 18; def gray = withcolor .8white enddef; draw z0..z3 gray; linecap:=butt; draw z1..z4 gray; linecap:=squared; draw z2..z5 gray; dotlabels.top(0,1,2,3,4,5); endfig; linecap:=rounded; %stopverbatim \qquad \vcenter{\includegraphics{mpintro-4}} $$ There is also a \lit{linejoin} parameter as illustrated below. The default values of \lit{linecap} and \lit{linejoin} are both \lit{rounded}.\vadjust{\okbreak} $$ \startverbatim beginfig(5); for i=0 upto 2: z[i]=(0,50i); z[i+3]-z[i]=(60,40); z[i+6]-z[i]=(120,0); endfor pickup pencircle scaled 24; def gray = withcolor .8white enddef; draw z0--z3--z6 gray; linejoin:=mitered; draw z1..z4--z7 gray; linejoin:=beveled; draw z2..z5--z8 gray; dotlabels.bot(0,1,2,3,4,5,6,7,8); endfig; linejoin:=rounded; %stopverbatim \qquad \vcenter{\includegraphics{mpintro-5}} \mskip-54mu % allow it to hang into the margin $$ Another way to adjust the behavior of drawing commands is by giving the declaration $$ \lit{drawoptions}(\descr{with list}) $$ For instance, $$ \lit{drawoptions(withcolor blue)} $$ gives subsequent drawing commands the default color blue. This can still be overridden by giving another \lit{withcolor} clause as in $$ \lit{draw p withcolor red} $$ The options apply only to relevant drawing commands: $$ \lit{drawoptions(dashed dd)} $$ will affect \lit{draw} commands but not fill commands. Chapters 17--20 of {\sl The \MF book} describe the programming constructs necessary to customize the language to a particular problem. These features work the same way in MetaPost but a few additional comments are needed. These chapters mention certain macros from plain \MF\ that are not in the plain macro package for MetaPost. Generally if it sounds as though it's for making fonts, MetaPost doesn't have it. Remember that \lit{beginfig} and \lit{endfig} play the role of \MF's \lit{beginchar} and \lit{endchar}. Look in the file \lit{plain.mp} in the standard macro area if there is any doubt about what macros are predefined. This file is also a good source of examples. Chapter 17 explains how the \lit{interim} statement makes temporary changes to internal quantities. This works the same way in MetaPost except that the example involving {\it autorounding} is inappropriate because MetaPost doesn't have that particular quantity. Here is a complete list of the internal quantities found in \MF\ but not MetaPost: $$\vcenter{\hsize=.8\hsize \raggedright \multiply\rightskip by3 \textt\noindent \lit{autorounding}, \lit{fillin}, \lit{granularity}, \lit{hppp}, \lit{proofing}, \lit{smoothing}, \lit{tracingedges}, \lit{tracingpens}, \lit{turningcheck}, \lit{vppp}, \lit{xoffset}, \lit{yoffset}} $$ The following additional quantities are defined in plain \MF\ but not in plain MetaPost: $$\vcenter{\hsize=.8\hsize \raggedright \multiply\rightskip by3 \textt\noindent \lit{pixels\_per\_inch}, \lit{blacker}, \lit{o\_correction}, \lit{displaying}, \lit{screen\_rows}, \lit{screen\_cols}, \lit{currentwindow}} $$ There are also some internal quantities that are unique to MetaPost. The \lit{linecap} and \lit{linejoin} parameters have already been mentioned. There is also a \lit{miterlimit} parameter that behaves like the similarly named parameter in PostScript. Another parameter, \lit{tracing\_lost\_chars} suppresses error messages about attempts to typeset missing characters. This is probably only relevant when using string parameters in the labeling macros since expressions generated by \lit{btex} $\ldots$ \lit{etex} blocks are not likely to use missing characters. The \lit{prologues} parameter was referred to earlier when we recommended setting it to one when including MetaPost output in a {\it troff\/} document. Any positivie value causes the output files to be ``conforming PostScript'' that assumes only standard Adobe fonts are used. This makes the output more portable but on most implementations, it precludes the use of the use of \TeX\ fonts such as \lit{cmr10}. Software for sending \TeX\ output to PostScript printers generally downloads such fonts one character at a time and does not make them available in included PostScript figures. Plain MetaPost also has internals \lit{bboxmargin}, \lit{labeloffset} and \lit{ahangle} as well as \lit{defaultscale} which controls the size of the default label font as explained above. The \lit{bboxmargin} parameter is the amount of extra space that the \lit{bbox} operator leaves; \lit{labeloffset} gives the distance by which labels are offset from the point being labeled; \lit{ahangle} is the angle of the pointed ends of arrowheads ($45^\circ$ by default). There is also a path \lit{ahcirc} that controls the size of the arrowheads. The statement $$ \lit{ahcirc := fullcircle scaled d} $$ changes the arrowhead length to $\lit{d}/2$. The only relevant new material in {\sl The \MF book\/} not mentioned so far is in Chapters 21--22 and Appendix~D. Chapters 23 and~24 do not apply to MetaPost at all. The grammar given in Chapters 25 and~26 isn't exactly a grammar of MetaPost, but most of the differences have been mentioned above. There are \lit{redpart}, \lit{bluepart}, and \lit{greenpart} operators for colors and there is no \lit{totalweight} operator. The new primitive for label text in pictures is $$ \descr{picture secondary} \rightarrow \descr{picture secondary} \lit{ infont } \descr{string primary} $$ Bounding box information can be obtained via the operators \begin{eqnarray*} \descr{pair primary} &\rightarrow& \descr{corner selector} \descr{picture primary}\\ \descr{corner selector} &\rightarrow& \lit{llcorner} \mid \lit{urcorner} \mid \lit{lrcorner} \mid \lit{urcorner} \end{eqnarray*} The main reason for having these in the MetaPost language is for measuring text but they work for pictures containing any mixture of text and graphics. The command $$ \lit{special }\descr{string expression} $$ adds a line of text at the beginning of the next output file. For instance, the following commands add PostScript definitions that allow MetaPost output to use the built-in font \lit{Times-Roman}. $$ \startverbatim special "/Times-Roman /Times-Roman def"; special "/fshow {exch findfont exch scalefont setfont show}"; special " bind def"; %stopverbatim $$ A similar definition is generated automatically when you set \lit{prologues:=1}. With \lit{prologues=0}, it is assumed that the program that translates \TeX\ output and includes PostScript figures will add the necessary definition.% \footnote{A full description of how to avoid including your output in a \TeX\ document is beyond the scope of this documentation. MetaPost output generated with \lit{prologues:=1} can be sent directly to a PostScript printer if it uses only built-in fonts like \lit{Helvetica}.} Another new feature of MetaPost that needs further explanation is the idea of a dash pattern. It is easiest if you can just get by with the dash pattern called \lit{evenly} that is defined in plain MetaPost, but it seems necessary to give the exact rules just in case they are needed. A dash pattern is a picture containing one or more horizontal line segments. It doesn't matter what pen is used to draw the line segments. MetaPost behaves as though the dash pattern is replicated to form an infinitely long horizontal dashed line to be used as a template for dashed lines. For example, the following commands create a dash pattern~\lit{dd}: $$\startverbatim draw (1,0)..(3.0); draw (5,0)..(6,0); picture dd; dd=currentpicture; clearit; %stopverbatim $$ Lining up an infinite number of copies of \lit{dd} produces a set of line segments $$ \{\,(5i,0)\ldots(5i+3,0) \mid \hbox{for all integer $i$}\,\}. $$ This template is used by starting from the $y$-axis and going to the right, producing dashes $3bp$ long separated by gaps of length $2bp$. In this example, successive copies of \lit{dd} are offset by $5bp$ because the range of $x$ coordinates covered by the line segments in \lit{dd} is $6-1$ or $5bp$. The offset can be increased by shifting the dash pattern vertically so that it lies at a $y$-coordinate greater that $5bp$ in absolute value. The rule is that the horizontal offset between copies of the dash pattern is the maximum of $|y|$ and the range of $x$-coordinates. \bigbreak \centerline{\bf Making Boxes} \nobreak\medskip There are auxiliary macros not included in plain MetaPost that make it convenient to do things that {\it pic} is good at. What follows is a description of how to use the macros contained in the file \lit{boxes.mp}. This may be of some interest to users who don't need these macros but want to see additional examples of what can be done in MetaPost. The main idea is that one should say $$ \lit{boxit} \descr{suffix}(\descr{picture expression}) $$ in order to create pair variables $\descr{suffix}\lit{.c}$, $\descr{suffix}\lit{.n}$, $\descr{suffix}\lit{.e}$, etc. These can then be used for positioning the picture before drawing it with a separate command such as $$ \lit{drawboxed}(\descr{suffix}) $$ The command \lit{boxit.bb(pic)} makes \lit{bb.c} the position where the center of picture \lit{pic} is to be placed and defines \lit{bb.sw}, \lit{bb.se}, \lit{bb.ne}, and \lit{bb.nw} to be the corners of a rectangular path that will surround the resulting picture. Variables \lit{bb.dx} and \lit{bb.dy} give the spacing between the shifted version of \lit{pic} and the surrounding rectangle and \lit{bb.off} is the amount by which \lit{pic} has to be shifted to achieve all this. The \lit{boxit} macro gives linear equations that force \lit{bb.sw}, \lit{bb.se}, $\ldots$ to be the corners of a rectangle aligned on the $x$ and $y$ axes with the picture \lit{pic} centered inside. The values of \lit{bb.dx}, \lit{bb.dy}, and \lit{bb.c} are left unspecified so that the user can give equations for positioning the boxes. If no such equations are given, macros such as \lit{drawbox} can detect this and give default values.\vadjust{\okbreak} $$ \includegraphics{mpintro-6} $$ \okbreak The following example shows how this works in practice. $$ \startverbatim input boxes beginfig(7); boxjoin(a.se=b.sw; a.ne=b.nw); boxit.a(btex $\cdots$ etex); boxit.ni(btex $n_i$ etex); boxit.di(btex $d_i$ etex); boxit.nii(btex $n_{i+1}$ etex); boxit.dii(btex $d_{i+1}$ etex); boxit.aa(pic_.a); boxit.nk(btex $n_k$ etex); boxit.dk(btex $d_k$ etex); di.dy = 2; drawboxed(a,ni,di,nii,dii,aa,nk,dk); label.lft("ndtable:", a.w); boxjoin(a.sw=b.nw; a.se=b.ne); interim defaultdy:=7; boxit.ba(); boxit.bb(); boxit.bc(); boxit.bd(btex $\vdots$ etex); boxit.be(); boxit.bf(); bd.dx=8; ba.ne=a.sw-(15,10); drawboxed(ba,bb,bc,bd,be,bf); label.lft("hashtab:",ba.w); def ndblock suffix $ = boxjoin(a.sw=b.nw; a.se=b.ne); forsuffixes $$=$a,$b,$c: boxit$$(); ($$dx,$$dy)=(5.5,4); endfor; enddef; ndblock nda; ndblock ndb; ndblock ndc; nda.a.c-bb.c = ndb.a.c-nda.c.c = (whatever,0); xpart ndb.c.se = xpart ndc.a.ne = xpart di.c; ndc.a.c - be.c = (whatever,0); drawboxes(nda.a,nda.b,nda.c,ndb.a,ndb.b,ndb.c,ndc.a,ndc.b,ndc.c); drawarrow bb.c .. nda.a.w; drawarrow be.c .. ndc.a.w; drawarrow nda.c.c .. ndb.a.w; drawarrow nda.a.c{right}..{curl0}ni.c cutafter bpath ni; drawarrow nda.b.c{right}..{curl0}di.c cutafter bpath di; drawarrow ndc.a.c{right}..{curl0}nii.c cutafter bpath nii; drawarrow ndc.b.c{right}..{curl0}dii.c cutafter bpath dii; drawarrow ndb.a.c{right}..nk.c cutafter bpath nk; drawarrow ndb.b.c{right}..dk.c cutafter bpath dk; x.ptr=xpart aa.c; y.ptr=ypart ndc.a.ne; drawarrow subpath (0,.7) of (z.ptr..{left}ndc.c.c); label.rt(btex ndblock etex, z.ptr); endfig; %stopverbatim $$ It is instructive to compare the MetaPost output below with the similar figure in the {\it pic} manual \cite{ke:pic}.\vadjust{\okbreak} $$ \includegraphics{mpintro-7} $$ The second line of input for the above figure contains $$ \lit{boxjoin(a.se=b.sw; a.ne=b.nw)} $$ This causes boxes to line up horizontally by giving additional equations that are invoked each time some box \lit{a} is followed by some other box~\lit{b}. These equations are first invoked on the next line when box~\lit{a} is followed by box~\lit{ni}. This yields $$ \lit{a.se=ni.sw; a.ne=ni.nw} $$ The next pair of boxes is box~\lit{ni} and box~\lit{di}. This time the implicitly generated equations are $$ \lit{ni.se=di.sw; ni.ne=di.nw} $$ This process continues until a new \lit{boxjoin} is given. In this case the new declaration is $$ \lit{boxjoin(a.sw=b.nw; a.se=b.ne)} $$ which causes boxes to be stacked below each other. After calling \lit{boxit} for the first eight boxes \lit{a} through \lit{dk}, the example gives the single equation $\lit{di.dy}=2$ followed by a call to \lit{drawboxed} that draws the eight boxes with the given text inside of them. The equation forces there to be $2bp$ of space above and below the contents of box~\lit{di} (the label ``$d_i$''). Since this doesn't fully specify the sizes and positions of the boxes, the \lit{drawboxed} macro starts by selecting default values, setting \lit{a.dx} through \lit{dk.dx} equal to the default value of $3bp$. The argument to boxit can be omitted as in \lit{boxit.ba()} or \lit{boxit.bb()}. This is like calling \lit{boxit} with an empty picture. Alternatively the argument can be a string expression instead of a picture expression in which case the string is typeset in the default font. In addition to the corner points \lit{a.sw}, \lit{a.se}, $\ldots$, a command like \lit{boxit.a} defines points \lit{a.w}, \lit{a.s}, \lit{a.e} and \lit{a.n} at the midpoints of the outer rectangle. If this bounding rectangle is needed for something other than just being drawn by the \lit{drawboxed} macro, it can be referred to as \lit{bpath.a} or in general $$ \lit{bpath} \descr{box name} $$ The \lit{bpath} macro is used in the arguments to \lit{drawarrow} in the previous example. For instance $$ \lit{nda.a.c\char`\{right\char`\}..\char`\{curl0\char`\}ni.c} $$ is a path from the center of box \lit{nda.a} to the center of box \lit{ni}. Following this with ``\lit{cutafter} \lit{bpath.ni}'' makes the arrow go towards the center of the box but stop when it hits the outer rectangle. The next example also uses this technique of cutting connecting arrows when they hit a bounding path, but in this case the bounding paths are circles and ovals instead of rectangles. The circles and ovals are created by using \lit{circleit} in place of \lit{boxit}. Saying \lit{circleit.a(pic)} defines points \lit{a.c}, \lit{a.s}, \lit{a.e}, \lit{a.n}, \lit{a.w} and distances \lit{a.dx} and \lit{a.dy}. These variables describe how the picture is centered in an oval as can be seen from the following diagram:\vadjust{\okbreak} $$ \includegraphics{mpintro-8} $$ \okbreak Here is the input for the figure that uses \lit{circleit}: $$\startverbatim beginfig(9); vardef cuta(suffix a,b) expr p = drawarrow p cutbefore bpath.a cutafter bpath.b; point .5*length p of p enddef; vardef self@# expr p = cuta(@#,@#) @#.c{curl0}..@#.c+p..{curl0}@#.c enddef; verbatimtex \def\stk#1#2{$\displaystyle{\matrix{#1\cr#2\cr}}$} etex circleit.aa("Start"); aa.dx=aa.dy; circleit.bb(btex \stk B{(a|b)^*a} etex); circleit.cc(btex \stk C{b^*} etex); circleit.dd(btex \stk D{(a|b)^*ab} etex); circleit.ee("Stop"); ee.dx=ee.dy; numeric hsep; bb.c-aa.c = dd.c-bb.c = ee.c-dd.c = (hsep,0); cc.c-bb.c = (0,.8hsep); xpart(ee.e - aa.w) = 3.8in; drawboxed(aa,bb,cc,dd,ee); label.ulft(btex$b$etex, cuta(aa,cc) aa.c{dir50}..cc.c); label.top(btex$b$etex, self.cc(0,30pt)); label.rt(btex$a$etex, cuta(cc,bb) cc.c..bb.c); label.top(btex$a$etex, cuta(aa,bb) aa.c..bb.c); label.llft(btex$a$etex, self.bb(-20pt,-35pt)); label.top(btex$b$etex, cuta(bb,dd) bb.c..dd.c); label.top(btex$b$etex, cuta(dd,ee) dd.c..ee.c); label.lrt(btex$a$etex, cuta(dd,bb) dd.c..{dir140}bb.c); label.bot(btex$a$etex, cuta(ee,bb) ee.c..tension1.3 ..{dir115}bb.c); label.urt(btex$b$etex, cuta(ee,cc) ee.c{(cc.c-ee.c)rotated-15}..cc.c); endfig; %stopverbatim $$ The ``boxes'' produced when using \lit{circleit} come out circular unless something forces a different aspect ratio.\vadjust{\okbreak} $$ \includegraphics{mpintro-9} $$ In the above figure, the equations \lit{aa.dx=aa.dy} and \lit{ee.dx=ee.dy} after $$ \lit{circleit.aa("Start")} \quad{\rm and}\quad \lit{circleit.ee("Stop")} $$ make the start and stop nodes non-circular. The general rule is that $\lit{bpath.}c$ comes out circular if $c\lit{.dx}$, $c\lit{.dy}$, and $c\lit{.dx}-c\lit{.dy}$ are all unspecified. Otherwise the macros select an oval just big enough to contain the given picture. (The margin of safety is given by the internal parameter \lit{circmargin}). There is also a \lit{pic} macro that makes $\lit{pic.}c$ the picture that goes inside $\lit{bpath.}c$ In addition to the \lit{drawboxed} macro that draws the picture and the surrounding rectangle or oval, there are \lit{drawunboxed} and \lit{drawboxes} macros that draw the pictures and the surrounding paths separately. \section{Implementation} \label{impsec} The MetaPost interpreter is written in Knuth's {\tt WEB} language which can be thought of as PASCAL with macros. This choice allows the sharing of code with the \MF\ interpreter.~\cite{kn:d} Indeed, about three fourths of the code in the main source file {\tt mp.web} is copied from this source by permission from the author. In accordance with the standard methodology for {\tt WEB} programs, parts of the program that are specific to the UNIX\footnote{UNIX is a registered trademark of UNIX System Laboratories.} system are given in a separate file {\tt mp.ch} that the {\tt tangle} processor merges with {\tt mp.web} to form a PASCAL program. (It is then automatically translated into C using a special-purpose translator that is included with the UNIX version of \TeX.) The only other code required by the MetaPost interpreter is a short external C program {\tt mpext.c} and a small include file {\tt mp.h} to tie it all together. In addition to the main interpreter, there are some programs that control the translation of typesetting commands in \lit{btex} $\ldots$ \lit{etex} blocks. When the interpreter encounters \lit{btex} in some input file \lit{foo.mp}, it needs to start reading from an auxiliary file \lit{foo.mpx}. This file should contain translations of the \lit{btex} $\ldots$ \lit{etex} blocks in \lit{foo.mp} into low-level MetaPost commands. If \lit{foo.mpx} is out of date or does not exist, the MetaPost interpreter invokes a shell script that generates the file. The generation of an auxiliary file \lit{foo.mpx} from an input file \lit{foo.mp} is a three step process: a C~program called \lit{mptotex} strips out the \TeX\ commands; then \TeX\ produces a binary file that gives low-level typesetting instructions; and finally, a {\tt WEB} program \lit{dvitomp} writes equivalent MetaPost commands in the \lit{foo.mpx} file. When using troff, C~programs \lit{mptotr} and \lit{dmp} replace \lit{mptotex} and \lit{dvitomp}. \bibliographystyle{plain} \bibliography{mpintro} \end{document}