Figure 11: Results of draw z0{curl c}.z1.{curl c}z2 for various values of the curl parameter. order here: If there is a non-empty direction specifier before a path knot but not after it, or vice versa, the specified direction (or curl amount) applies to both the incoming and outgoing path segments. A similar arrangement applies when a controls specification gives only one pair primary. Thus.controls (30,20). is equivalent to.controls (30,20) and (30,20). path expression path subexpression | path subexpressiondirection specifier | path subexpressionpath join cycle path subexpression path knot | path expressionpath joinpath knot path join -| direction specifierbasic path joindirection specifier direction specifier empty | {curl numeric expression} | {pair expression} | {numeric expression,numeric expression} basic path join . |. |.tension. |.controls. tension tensionnumeric primary | tensionnumeric primaryandnumeric primary controls controlspair primary | controlspair primaryandpair primary Figure 12: The syntax for path construction A pair of coordinates like (30,20) or a z variable that represents a coordinate pair is what Figure 12 calls a pair primary. A path knot is similar except that it can take on other forms such as a path expression in parentheses. Primaries and expressions of various types will be discussed in full generality in Section 6.

Linear Equations

An important feature taken from METAFONT is the ability to solve linear equations so that programs can be written in a partially declarative fashion. For example, the MetaPost interpreter can read a+b=3; 2a=b+3; and deduce that = 2 and = 1. The same equations can be written slightly more compactly by stringing them together with multiple equal signs: a+b = 2a-b = 3; Whichever way you give the equations, you can then give the command show a,b; to see the values of a and b. MetaPost responds by typing >> 2 >> 1 Note that = is not an assignment operator; it simply declares that the left-hand side equals the right-hand side. Thus a=a+1 produces an error message complaining about an inconsistent equation. The way to increase the value of a is to use the assignment operator := as follows: a:=a+1; In other words, := is for changing existing values while = is for giving linear equations to solve. There is no restriction against mixing equations and assignment operations as in the following example: a = 2; b = a; a := 3; c = a; After the first two equations set a and b equal to 2, the assignment operation changes a to 3 without affecting b. The final value of c is 3 since it is equated to the new value of a. In general, an assignment operation is interpreted by first computing the new value, then eliminating the old value from all existing equations before actually assigning the new value.

Equations and Coordinate Pairs
MetaPost can also solve linear equations involving coordinate pairs. We have already seen many trivial examples of this in the form of equations like z1=(0,.2in) Each side of the equation must be formed by adding or subtracting coordinate pairs and multiplying or dividing them by known numeric quantities. Other ways of naming pair-valued variables will be discussed later, but the znumber is convenient because it is an abbreviation for (xnumber, ynumber) This makes it possible to give values to z variables by giving equations involving their coordinates. For instance, points z1, z2, z3, and z6 in Figure 13 were initialized via the following equations: z1=-z2=(.2in,0); x3=-x6=.3in; x3+y3=x6+y6=1.1in; 11
Exactly the same points could be obtained by setting their values directly: z1=(.2in,0); z2=(-.2in,0); z3=(.3in,.8in); z6=(-.3in,1.4in); After reading the equations, the MetaPost interpreter knows the values of z1, z2, z3, and z6. The next step in the construction of Figure 13 is to define points z4 and z5 equally spaced along the line from z3 to z6. Since this operation comes up often, MetaPost has a special syntax for it. This mediation construction z4=1/3[z3,z6] means that z4 is
of the way from 3 to 6; i.e., 1 z4 = z3 + (z6 z3). 3

Similarly makes z5

z5=2/3[z3,z6] of the way from 3 to 6. beginfig(13); z1=-z2=(.2in,0); x3=-x6=.3in; x3+y3=x6+y6=1.1in; z4=1/3[z3,z6]; z5=2/3[z3,z6]; z20=whatever[z1,z3]=whatever[z2,z4]; z30=whatever[z1,z4]=whatever[z2,z5]; z40=whatever[z1,z5]=whatever[z2,z6]; draw z1--z20--z2--z30--z1--z40--z2; pickup pencircle scaled 1pt; draw z1--z2; draw z3--z6; endfig; 20
Figure 13: MetaPost commands and the resulting figure. Point labels have been added to the figure for clarity. Mediation can also be used to say that some point is at an unknown position along the line between two known points. For instance, we could a introduce new variable aa and write something like z20=aa[z1,z3]; This says that z20 is some unknown fraction aa of the way along the line between z1 and z3. Another such equation involving a different line is sufficient to fix the value of z20. To say that z20 is at the intersection of the z1-z3 line and the z2-z4 line, introduce another variable ab and set z20=ab[z2,z4]; This allows MetaPost to solve for x20, y20, aa, and ab. It is a little painful to keep thinking up new names like aa and ab. This can be avoided by using a special feature called whatever. This macro generates a new anonymous variable each time it appears. Thus the statement z20=whatever[z1,z3]=whatever[z2,z4] 12
sets z20 as before, except it uses whatever to generate two different anonymous variables instead of aa and ab. This is how Figure 13 sets z20, z30, and z40.

Dealing with Unknowns

0 and 1. For example, MetaPost will output the color (1,2,3) as (1,1,1). MetaPost solves linear equations involving colors the same way it does for pairs. The type rgbcolor is an alias of type color. The cmykcolor type is similar to the color type except that it has four components instead of three. This type is used to specify colors by their cyan, magenta, yellow, and black components explicitly. Because CMYK colors deal with pigments instead of light rays, the color white would be expressed as (0,0,0,0) and black as (0,0,0,1). In theory, the colors (,,,1) and (1,1,1,) should result in black for any values of , , and , too. But in practice, this is avoided since it is a waste of colored ink and can lead to unsatisfactory results. A string represents a sequence of characters. String constants are given in double quotes "like this". String constants cannot contain double quotes or newlines, but there is a way to construct a string containing any sequence of eight-bit characters. Conversion from strings to other types, notably numeric, can be accomplished by the scantokens primitive: n := scantokens(str); More generally, scantokens parses a string into a token sequence, as if MetaPost had read it as input. The boolean type has the constants true and false and the operators and, or, not. The relations = and <> test objects of any type for equality and inequality. Comparison relations <, <=, >, and >= are defined lexicographically for strings and in the obvious way for numerics. Ordering relations are also defined for booleans, pairs, colors, and transforms, but the comparison rules are not worth discussing here. The picture data type is just what the name implies. Anything that can be drawn in MetaPost can be stored in a picture variable. In fact, the draw statement actually stores its results in a special picture variable called currentpicture. Pictures can be added to other pictures and operated on by transforms. Finally, there is a data type called a pen. The main function of pens in MetaPost is to determine line thickness, but they can also be used to achieve calligraphic effects. The statement pickup pen expression causes the given pen to be used in subsequent draw or drawdot statements. Normally, the pen expression is of the form pencircle scaled numeric primary. This defines a circular pen that produces lines of constant thickness. If calligraphic effects are desired, the pen expression can be adjusted to give an elliptical pen or a polygonal pen.

a b c d e

and substring (2,4) of "abcde" is "cd". This takes a little getting used to but it tends to avoid annoying off by one errors. Some operators take no arguments at all. An example of what Figure 14 calls a nullary op is nullpicture which returns a completely blank picture. 16
The basic syntax in Figure 14 only covers aspects of the expression syntax that are relatively type-independent. For instance, the complicated path syntax given in Figure 12 gives alternative rules for constructing a path expression. An additional rule path knot pair tertiary | path tertiary explains the meaning of path knot in Figure 12. This means that the path expression z1+(1,1){right}.z2 does not need parentheses around z1+(1,1).
Fractions, Mediation, and Unary Operators
Mediation expressions do not appear in the basic expression syntax of Figure 14. Mediation expressions are parsed at the primary level, so the general rule for constructing them is primary numeric atom[expression,expression] where each expression can be of type numeric, pair, or color. The numeric atom in a mediation expression is an extra simple type of numeric primary as shown in Figure 15. The meaning of all this is that the initial parameter in a mediation expression needs to be parenthesized when it is not just a variable, a positive number, or a positive fraction. For example, -1[a,b] and (-1)[a,b] are very different: the former is since it is equivalent to -(1[a,b]); the latter is ( ) or 2 . numeric primary numeric atom | numeric atom[numeric expression,numeric expression] | of operatorexpressionofprimary | unary opprimary numeric atom numeric variable | number or fraction | (numeric expression) | numeric nullary op number or fraction number/number | number not followed by /number Figure 15: Syntax rules for numeric primaries A noteworthy feature of the syntax rules in Figure 15 is that the / operator binds most tightly when its operands are numbers. Thus 2/3 is a numeric atom while (1+1)/3 is only a numeric secondary. Applying a unary op such as sqrt makes the difference clear: sqrt 2/3 means

while sqrt(1+1)/3

means 2/3. Operators such as sqrt can be written in standard functional notation, but it is often unnecessary to parenthesize the argument. This applies to any function that is parsed as a unary op. For instance abs(x) and abs x both compute the absolute value of x. The same holds for the 17
round, floor, ceiling, sind, and cosd functions. The last two of these compute trigonometric functions of angles in degrees. Not all unary operators take numeric arguments and return numeric results. For instance, the abs operator can be applied to a pair to compute the Euclidean length of a vector. Applying the unitvector operator to a pair produces the same pair rescaled so that its Euclidean length is 1. The decimal operator takes a number and returns the string representation. The angle operator takes a pair and computes the two-argument arctangent; i.e., angle is the inverse of the dir operator that was discussed in Section 4.2. There is also an operator cycle that takes a path primary and returns a boolean result indicating whether the path is a closed curve. There is a whole class of other operators that classify expressions and return boolean results. A type name such as pair can operate on any type of primary and return a boolean result indicating whether the argument is a pair. Similarly, each of the following can be used as a unary operator: numeric, boolean, cmykcolor, color, string, transform, path, pen, picture, and rgbcolor. Besides just testing the type of a primary, you can use the known and unknown operators to test if it has a completely known value. Even a number can behave like an operator in some contexts. This refers to the trick that allows 3x and 3cm as alternatives to 3*x and 3*cm. The rule is that a number or fraction that is not followed by +, -, or another number or fraction can serve as a primary binop. Thus 2/3x is two 2 thirds of x but (2)/3x is 3 and is illegal. There are also operators for extracting numeric subfields from pairs, colors, cmykcolors, and even transforms. If p is a pair primary, xpart p and ypart p extract its components so that (xpart p, ypart p) is equivalent to p even if p is an unknown pair that is being used in a linear equation. Similarly, a color c is equivalent to (redpart c, greenpart c, bluepart c). For a cmykcolor c, the components are (cyanpart c, magentapart c, yellowpart c, blackpart c) and for a greyscale color c, there is only one component greypart c. All color component operators are discussed in more detail in section 9.10. Part specifiers for transforms are discussed in section 9.3.

Integrating Text and Graphics
MetaPost has a number of features for including labels and other text in the figures it generates. The simplest way to do this is to use the label statement labellabel suffix(string or picture expression, pair expression); The string or picture expression gives the label and the pair expression says where to put it. The label suffix can be empty in which case the label is just centered on the given coordinates. If you are labeling some feature of a diagram you probably want to offset the label slightly to avoid overlapping. This is illustrated in Figure 17 where the "a" label is placed above the midpoint of the line it refers to and the "b" label is to the left of the midpoint of its line. This is achieved by using label.top for the "a" label and label.lft for the "b" label as shown in the figure. The label suffix specifies the position of the label relative to the specified coordinates. The complete set of possibilities is label suffix empty | lft | rt | top | bot | ulft | urt | llft | lrt where lft and rt mean left and right and llft, ulft, etc. mean lower left, upper left, etc. The actual amount by which the label is offset in whatever direction is determined by the internal variable labeloffset. beginfig(17); a=.7in; b=.5in; z0=(0,0); z1=-z3=(a,0); z2=-z4=(0,b); draw z1.z2.z3.z4.cycle; draw z1--z0--z2; label.top("a",.5[z0,z1]); label.lft("b",.5[z0,z2]); dotlabel.bot("(0,0)", z0); endfig;

b (0,0)

Figure 17: MetaPost code and the resulting output Figure 17 also illustrates the dotlabel statement. This is effectively like a label statement followed by a statement drawing a dot at the indicated coordinates. For example dotlabel.bot("(0,0)", z0) places a dot at z0 and then puts the label (0,0) just below the dot. The diameter of the dot drawn by the dotlabel statement is determined by the value of the internal variable dotlabeldiam. Default value is 3bp. Another alternative is the macro thelabel. This has the same syntax as the label and dotlabel statements except that it returns the label as a picture primary instead of actually drawing it. Thus label.bot("(0,0)", z0) is equivalent to draw thelabel.bot("(0,0)", z0)

6 Unix

is a registered trademark of Unix Systems Laboratories.
In PostScript output mode, when prologues is 2, the MetaPost output is EPSF and assumes that the text comes from PostScript fonts provided by the environment, such as the document viewer or embedded application using the output. MetaPost will attempt to set up the font encodings correctly, based on fontmapfile and fontmapline commands. A prologues:=2 setting is currently ignored in SVG output mode. The value is reserved for future use (possibly for external font-face definitions). In PostScript output mode, when prologues is 3, the MetaPost output will be EPSF but will contain the PostScript font(s) (or a subset) used based on the fontmapfile and fontmapline commands. This value is useful for generating stand-alone PostScript graphics. In SVG mode, the font glyphs are converted to path definitions that are included at the top of the output file. The correct setting for variable prologues depends on how MetaPost graphics are post-processed. Here are recommendations for some popular use-cases: Previewing: Section 14.2 discusses previewing PostScript output. TEX and dvips: When including PostScript figures into a TEX document that is processed by TEX and a DVI output processer, e.g., dvips, variable prologues should not be set to the value 1, unless the used fonts are known to be resident in the PostScript interpreter. Make sure that variable prologues is set to either 0 (font inclusion handled by dvips, but without re-encoding support), 2 (font inclusion by dvips, with font re-encoding if necessary), or 3 (font inclusion and re-encoding by MetaPost). Value 3 is safest, but may result in slightly larger output. pdfTEX: When generating PDF files with pdfTEX (and the mptopdf bundle), variable prologues is not relevant. PostScript in external applications: Some text processors or graphics applications can directly import EPSF files, while for others MetaPosts PostScript output has to be converted to a different vector or even a bitmap format first. In any case, as soon as PostScript graphics generated by MetaPost are leaving the TEX ecosystem, variable prologues should be set to 3, so that all needed fonts are embedded (as a subset). SVG output: Converting font glyphs to paths by setting variable prologues to 3 is currently the only reliable way to export text objects to SVG. It is worth noting that the value of prologues has no effect on METAFONT fonts in your MetaPost A files, i. e., MetaPost never embeds such fonts. Only output drivers, e. g., dvips or pdfL TEX will handle those. The details on how to include PostScript figures in a paper done in TEX or troff are systemdependent. They can generally be found in manual pages and other on-line documentation, but have a look at section 14.4 of this manual for some brief instructions that in many cases should work. The manual for the widely-used Dvips processor is in a file dvips.texi, included in most distributions, and is available online at http://tug.org/texinfohtml/dvips.html, among many other places and formats.

9 withdots

is only found in MetaPost version 0.50 and higher.
beginfig(28); path p[]; p1 = fullcircle scaled.6in; z1=(.75in,0)=-z3; z2=directionpoint left of p1=-z4; p2 = z1.z2.{curl1}z3.z4.{curl 1}cycle; fill p2 withcolor.4[white,black]; unfill p1; draw p1; transform T; 3 z1 transformed T = z2; z3 transformed T = z4; xxpart T=yypart T; yxpart T=-xypart T; picture pic; pic = currentpicture; for i=1 upto 2: pic:=pic transformed T; draw pic; endfor dotlabels.top(1,2,3); dotlabels.bot(4); endfig;
Figure 28: MetaPost code and the resulting fractal figure
dashed dashed dashed dashed dashed
withdots scaled 2 withdots evenly scaled 4 evenly scaled 2 evenly
Figure 29: Dashed lines each labeled with the dash pattern used to create it.

draw draw draw draw

z6.z7 z4.z5 z2.z3 z0.z1
dashed dashed dashed dashed
e4 shifted (18bp,0) e4 shifted (12bp,0) e4 shifted (6bp,0) e4
Figure 30: Dashed lines and the MetaPost statements for drawing them where e4 refers to the dash pattern evenly scaled 4.
gap, then a 12bp dash, etc. This dash pattern could be specified more directly via the dashpattern function: dashpattern(on 6bp off 12bp on 6bp) This means draw the first 6bp of the line, then skip the next 12bp, then draw another 6bp and repeat. If the line to be dashed is more than 30bp long, the last 6bp of the first copy of the dash pattern will merge with the first 6bp of the next copy to form a dash 12bp long. The general syntax for the dashpattern function is shown in Figure 31. dash pattern dashpattern(on/off list) on/off list on/off liston/off clause | on/off clause on/off clause onnumeric tertiary | offnumeric tertiary Figure 31: The syntax for the dashpattern function Since a dash pattern is really just a special kind of picture, the dashpattern function returns a picture. It is not really necessary to know the structure of such a picture, so the casual reader will probably want to skip on to Section 9.6. For those who want to know, a little experimentation shows that if d is dashpattern(on 6bp off 12bp on 6bp), then llcorner d is (0, 24) and urcorner d is (24, 24). Drawing d directly without using it as a dash pattern produces two thin horizontal line segments like this:
The lines in this example are specified as having width zero, but this does not matter because the line width is ignored when a picture is used as a dash pattern. The general rule for interpreting a picture d as a dash pattern is that the line segments in d are projected onto the -axis and the resulting pattern is replicated to infinity in both directions by placing copies of the pattern end-to-end. The actual dash lengths are obtained by starting at = 0 and scanning in the positive direction. To make the idea of replicating to infinity more precise, let (d) be the projection of d onto the axis, and let shift( (d), ) be the result of shifting d by. The pattern resulting from infinite replication is shift( (), ()),

beginfig(33); for i=0 upto 2: z[i]=(0,40i); z[i+3]-z[i]=(100,30); endfor pickup pencircle scaled 18; draw z0.z3 withcolor.8white; linecap:=butt; draw z1.z4 withcolor.8white; linecap:=squared; draw z2.z5 withcolor.8white; dotlabels.top(0,1,2,3,4,5); endfig; linecap:=rounded;
Figure 33: MetaPost code and the corresponding output beginfig(34); 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; draw z0--z3--z6 withcolor.8white; linejoin:=mitered; draw z1.z4--z7 withcolor.8white; linejoin:=beveled; draw z2.z5--z8 withcolor.8white; dotlabels.bot(0,1,2,3,4,5,6,7,8); endfig; linejoin:=rounded;
Figure 34: MetaPost code and the corresponding output line width
miter length Figure 35: The miter length and line width whose ratio is limited by miterlimit. drawarrow z1.zdrawarrow reverse(z3.z4) 6 drawdblarrow z5.z6 Figure 36: Three ways of drawing arrows. 41
instead of draw path expression. This draws the given path with an arrowhead at the last point on the path. If you want the arrowhead at the beginning of the path, just use the unary operator reverse to take the original path and make a new one with its time sense reversed; i.e., for a path p with length p = , point of reverse p and point of p are synonymous. As shown in Figure 36, a statement beginning drawdblarrow path expression draws a double-headed arrow. The size of the arrowhead is guaranteed to be larger than the line width, but it might need adjusting if the line width is very great. This is done by assigning a new value to the internal variable ahlength that determines arrowhead length as shown in Figure 37. Increasing ahlength from the default value of 4 PostScript points to 1.5 centimeters produces the large arrowhead in Figure 37. There is also an ahangle parameter that controls the angle at the tip of the arrowhead. The default value of this angle is 45 degrees as shown in the figure. ahlength ahangle

ahlength

Figure 37: A large arrowhead with key parameters labeled and paths used to draw it marked with white lines. The arrowhead is created by filling the triangular region that is outlined in white in Figure 37 and then drawing around it with the currently picked up pen. This combination of filling and drawing can be combined into a single filldraw statement: filldraw path expression optional dashed and withcolor and withpen clauses; The path expression should be a closed cycle like the triangular path in Figure 37. This path should not be confused with the path argument to drawarrow which is indicated by a white line in the figure. White lines like the ones in the figure can be created by an undraw statement. This is an erasing version of draw that draws withcolor background just as the unfill statement does. There is also an unfilldraw statement just in case someone finds a use for it. The filldraw, undraw and unfilldraw statements and all the arrow drawing statements are like the fill and draw statements in that they take dashed, withpen, and withcolor options. When you have a lot of drawing statements it is nice to be able to apply an option such as withcolor 0.8white to all of them without having to type this repeatedly as was done in Figures 33 and 34. The statement for this purpose is drawoptions(text) where the text argument gives a sequence of dashed, withcolor, and withpen options to be applied automatically to all drawing statements. If you specify drawoptions(withcolor.5[black,white]) and then want to draw a black line, you can override the drawoptions by specifying draw path expression withcolor black 42

beginfig(38); pickup pencircle scaled.2in yscaled.08 rotated 30; x0=x3=x4; z1-z0 =.45in*dir 30; z2-z3 = whatever*(z1-z0); z6-z5 = whatever*(z1-z0); z1-z6 = 1.2*(z3-z0); rt x3 = lft x2; x5 =.55[x4,x6]; y4 = y6; lft x3 = bot y5 = 0; top y2 =.9in; draw z0--z1--z2--z3--z4--z5--z6 withcolor.7white; dotlabels.top(0,1,2,3,4,5,6); endfig;
Figure 38: MetaPost code and the resulting calligraphic figure. This would be the end of the story on pens, except that for compatibility with METAFONT, MetaPost also allows pen shapes to be polygonal. There is a predefined pen called pensquare that can be transformed to yield pens shaped like parallelograms. In fact, there is even an operator called makepen that takes a convex-polygon-shaped path and makes a pen that shape and size. If the path is not exactly convex or polygonal, the makepen operator will straighten the edges and/or drop some of the vertices. In particular, pensquare is equivalent to makepen((-.5,-.5)--(.5,-.5)--(.5,.5)--(-.5,.5)--cycle) 39. pensquare and makepen should not be used with dash patterns. See the end of Section 9.4, p.
The inverse of makepen is the makepath operator that takes a pen primary and returns the corresponding path. Thus makepath pencircle produces a circular path identical to fullcircle. This also works for a polygonal pen so that makepath makepen path expression will take any cyclic path and turn it into a convex polygon.
Clipping and Low-Level Drawing Commands
Drawing statements such as draw, fill, filldraw, and unfill are part of the Plain macro package and are defined in terms of more primitive statements. The main difference between the drawing statements discussed in previous sections and the more primitive versions is that the primitive drawing statements all require you to specify a picture variable to hold the results. For fill, draw, and related statements, the results always go to a picture variable called currentpicture. The syntax for the primitive drawing statements that allow you to specify a picture variable is shown in Figure 39. The syntax for primitive drawing commands is compatible with METAFONT. Table 3 shows how the primitive drawing statements relate to the familiar draw and fill statements. Each of the statements in the first column of the table could be ended with an option list of its own, which is equivalent to appending the option list to the corresponding entry in the second column of the table. For example, draw withpen pencircle 44
addto command addtopicture variablealsopicture expressionoption list | addtopicture variablecontourpath expressionoption list | addtopicture variabledoublepathpath expressionoption list option list empty | drawing optionoption list drawing option withcolorcolor expression | withrgbcolorrgbcolor expression | withcmykcolorcmykcolor expression | withgreyscalenumeric expression | withoutcolor | withprescriptstring expression | withpostscriptstring expression | withpenpen expression | dashedpicture expression Figure 39: The syntax for primitive drawing statements is equivalent to addto currentpicture doublepath withpen currentpen withpen pencircle where currentpen is a special pen variable that always holds the last pen picked up. The second withpen option silently overrides the withpen currentpen from the expansion of draw. statement draw pic draw fill filldraw undraw pic undraw unfill unfilldraw addto addto addto addto addto addto addto addto equivalent primitives currentpicture also pic currentpicture doublepath withpen currentpicture contour currentpicture contour withpen currentpicture also pic withcolor currentpicture doublepath withpen withcolor currentpicture contour withcolor currentpicture contour withpen withcolor

mpsproof.tex An alternative to mproof.tex is the script mpsproof.tex, which is similar, but more powerful. While the former script only runs with TEX and requires a DVI output driver to generate PostScript files, mpsproof.tex can as well be run through pdfTEX to directly generate PDF files. Additionally, it provides some command-line options. With the \noheaders option, file names, date stamps, and page numbers are omitted from the proof sheet. Use it like tex mpsproof \noheaders MetaPost output files The \bbox option can be used to generate an output file that has exactly the same page size as a figures bounding box (\bbox is actually an alias for the longer \encapsulate). With this option only one figure can be processed at a time, e.g., pdftex mpsproof \bbox fig.1 Alternatives Other alternatives for previewing MetaPost figures, which are not part of the MetaPost distribution, are the mptopdf bundle or the Perl script mpstoeps.pl. There is also an online compiler and viewer for MetaPost code at http://tlhiv.org/mppreview/.

Debugging

MetaPost inherits from METAFONT numerous facilities for interactive debugging, most of which can only be mentioned briefly here. Further information on error messages, debugging, and generating tracing information can be found in The METAFONTbook [5]. Suppose your input file says draw z1--z2; on line 17 without first giving known values to z1 and z2. Figure 51 shows what the MetaPost interpreter prints on your terminal when it finds the error. The actual error message is the line beginning with !; the next six lines give the context that shows exactly what input was being read when the error was found; and the ? on last line is a prompt for your response. Since the error message talks about an undefined coordinate, this value is printed on the first line after the >>. In this case the coordinate of z1 is just the unknown variable x1, so the interpreter prints the variable name x1 just as it would if it were told to show x1 at this point. >> x1 ! Undefined x coordinate has been replaced by 0. <to be read again> { --->{ curl1}.{curl1} l.17 draw z1-z2; ? Figure 51: An example of an error message. The context listing may seem a little confusing at first, but it really just gives a few lines of text showing how much of each line has been read so far. Each line of input is printed on two lines like this: descriptor Text read so far Text yet to be read 69

It is also possible to include MetaPost output in a GNU troff document. The procedure is similar to Figure 54: the grops output processor includes PostScript files when they are requested via troffs \X command. The -mpspic macro package provides a command.PSPIC, which does just that when including an encapsulated PostScript file in the source code. For instance, the troff command.PSPIC fig.1 includes fig.1, using the natural height and width of the image as given in the files bounding box. 14.4.3 Web Applications
An SVG file fig.svg can be easily embedded into HTML documents with the following code snippet: <p> <object data="fig.svg" type="image/svg+xml" width="300" height="200"> </object> </p> SVG files can also be imported by various interactive graphics editing programs, for example GIMP or Inkscape. See Section 8.1 for information on font handling in SVG graphics.

Acknowledgement

I would like to thank Don Knuth for making this work possible by developing METAFONT and placing it in the public domain. I am also indebted to him for helpful suggestions, particularly with regard to the treatment of included TEX material.

Reference Manual

The MetaPost Language
Tables 511 summarize the built-in features of Plain MetaPost. Features from the Plain macro package are marked by symbols. The distinction between primitives and plain macros can be ignored by the casual user. The tables in this appendix give the name of each feature, the page number where it is explained, and a short description. A few features are not explained elsewhere and have no page number listed. These features exist primarily for compatibility with METAFONT and are intended to be self-explanatory. Certain other features from METAFONT are omitted entirely because they are of limited interest to the MetaPost users and/or would require long explanations. All of these are documented in The METAFONTbook [5] as explained in Appendix B.1. Tables 5 and 6 list internal variables that take on numeric and string values. Table 7 lists predefined variables of other types. Table 8 lists predefined constants. Some of these are implemented as variables whose values are intended to be left unchanged. Table 9 summarizes MetaPost operators and lists the possible argument and result types for each one. A entry for the left argument indicates a unary operator; entries for both arguments indicate a nullary operator. Operators that take suffix parameters are not listed in this table because they are treated as function-like macros. The last two tables are Table 10 for commands and Table 11 macros that behave like functions or procedures. Such macros take parenthesized argument lists and/or suffix parameters, returning either a value whose type is listed in the table, or nothing. The latter case is for macros that behave like procedures. Their return values are listed as. The figures in this appendix present the syntax of the MetaPost language starting with expressions in Figures 5557. Although the productions sometimes specify types for expressions, primaries, secondaries, and tertiaries, no attempt is made to give separate syntaxes for numeric expression, pair expression, etc. The simplicity of the productions in Figure 58 is due to this lack of type information. Type information can be found in Tables 511. Figures 59, 60 and 61 give the syntax for MetaPost programs, including statements and commands. They do not mention loops and if tests because these constructions do not behave like statements. The syntax given in Figures 5562 applies to the result of expanding all conditionals and loops. Conditionals and loops do have a syntax, but they deal with almost arbitrary sequences of tokens. Figure 62 specifies conditionals in terms of balanced tokens and loops in terms of loop text, where balanced tokens is any sequence of tokens balanced with respect to if and fi, and loop text is a sequence of tokens balanced with respect to for, forsuffixes, forever, and endfor.

the drawing option withweight. Here is a complete listing of the internal variables whose primitive meanings in METAFONT do not make sense in MetaPost: autorounding fillin chardx granularity chardy hppp proofing tracingpens smoothing turningcheck tracingedges vppp xoffset yoffset
There is also one METAFONT primitive that has a slightly different meaning in MetaPost. Both languages allow statements of the form special string expression; but METAFONT copies the string into its generic font output file, while MetaPost interprets the string as a sequence of PostScript commands that are to be placed at the beginning of the next output file. In this regard, it is worth mentioning that rules in TEX material included via btex.etex in MetaPost are rounded to the correct number of pixels according to PostScript conversion rules [1]. In METAFONT, rules are not generated directly, but simply included in specials and interpreted later by other programs, such as gftodvi, so there is no special conversion. All the other differences between METAFONT and MetaPost are features found only in MetaPost. These are listed in Table 18. The only commands listed in this table that the preceding sections do not discuss are extra_beginfig, extra_endfig, and mpxbreak. The first two are strings that contain extra commands to be processed by beginfig and endfig just as extra_beginchar and extra_endchar are processed by beginchar and endchar. (The file boxes.mp uses these features). The other new feature listed in Table 18 not listed in the index is mpxbreak. This is used to separate blocks of translated TEX or troff commands in mpx files. It should be of no concern to users since mpx files are generated automatically.

File Name Templates

The output file naming template mechanism introduced in MetaPost version 1.000 originally used a primitive called filenametemplate, as opposed to the internal string variable outputtemplate described in section 14.1. This primitive took a string argument with the same syntax as outputtemplate, except that it didnt know about the %{.} escape sequence for evaluating internal variables, e.g.,: filenametemplate "%j-%c.mps"; The filenametemplate primitive has been deprecated since the introduction of outputtemplate (version 1.200), but is still supported. If you happen to need writing future-proof source files, that at the same time are backwards compatible to MetaPost versions between 1.000 and 1.200, this output filename template declaration might help: if scantokens(mpversion) < 1.200: filenametemplate else: outputtemplate := fi "%j-%c.mps";

References

[1] Adobe Systems Inc. PostScript Language Reference Manual. Addison Wesley, Reading, Massachusetts, second edition, 1990. [2] Hans Hagen. Metafun, January 2002. metafun-s.pdf. http://www.pragma-ade.com/general/manuals/ The luamplib package.

llcorner, 27, 67, 81 llft, 21 locality, 20, 51 log file, 4, 24, 70 loggingall, 71 loops, 3, 61, 75 lrcorner, 27, 81 lrt, 21 luamplib, 73 LuaTEX engine, 73 magentapart, 18, 4748, 81 makempx, 24 makepath, 44, 82 makepen, 44, 82 mark_angle, 55 mark_rt_angle, 55 max, 87 mediation, 12, 13, 17 message, 70 METAFONT, 1, 22, 44, 45, 61, 69, 75, 97 metapost/base, 63 mexp, 82 mfplain, 97 middlepoint, 53 midpoint, 53 min, 87 minute, 65, 76 mitered, 40 miterlimit, 40 mlog, 82 mm, 2 mod, 82 month, 65, 76 mp file, 4, 70, 94 mplib, 3, 73, 74 C API, 3 Lua bindings, 3 mplibapi.pdf, 3 mplib, 63 mpost, 94, 96 mpost, 3, 4, 94, 96 mpprocset, 66 mproof.tex, 68 mps file, 5, 65, 73 -mpspic, 74 mpsproof.tex, 69 \bbox, 69 \encapsulate, 69 \noheaders, 69 mpstoeps.pl, 69
MPTEXPRE, 24 mpto, 24 mptopdf, 25, 69, 72 mpversion, 66 mpware tools, 96 mpx file, 24, 96, 100 mpxbreak, 100 MPXCOMMAND, 24 mpxerr.log, 24 mpxerr.tex, 24 multiplication, implicit, 3, 18 newinternal, 20 non-zero fill rule, 28, 49 nonstopmode, 93 normaldeviate, 82 not, 15, 82 nullary op, 16, 88, 89 nullpen, 48 nullpicture, 16, 46 numeric, 18, 82 numeric atom, 17 numeric type, 14 oct, 82 odd, 82 of operator, 60, 88, 89 option list, 45, 92 or, 15, 16, 82 origin, 78 OT1 encoding, 49 outputformat, 66 outputtemplate, 45, 65, 73, 100 pair, 18, 82 pair type, 14 Palatino, 22, 26 parameter expr, 53, 60, 62 suffix, 56, 58, 59, 61, 62 text, 55, 58, 61 parameterization, 7 parsing irregularities, 1618 path, 18, 53, 82 path knot, 17, 88 path type, 14 pathpart, 4748, 82 pausing, 76 pc, 78 PDF, 72, 73 pdfTEX engine, 72, 73 pen, 18, 82 106
pen type, 15 pencircle, 3, 43 penoffset of, 82 penpart, 4748, 82 pens elliptical, 43 polygonal, 44, 71 pensquare, 44 pfb file, 49 pickup, 3, 15 picture, 18, 82 picture type, 15 picture variable, 27, 92 Plain macros, 2, 20, 22, 44, 50, 75, 97 point PostScript, 2, 50, 97 printers, 2 point of, 32, 82 POSIX shell patterns, 68 postcontrol of, 33, 82 PostScript, 1, 28, 45, 72, 97, 100 bounding box, 67 closepath operator, 49 conversion rules, 100 coordinate system, 2 Creator comment, 67 fill rule, 28, 49 fonts, 22, 25, 48, 49, 68 point, 2, 50, 97 structured, 24, 66 precontrol of, 33, 82 preview, 4 PostScript, 67 primary, 15, 88 primary binop, 16, 26, 60, 88, 89 primarydef, 60 prologues, 24, 50, 67, 68 proof sheets, 68 PS, 67.PSPIC, 74 PS_View, 4 pt, 2 quartercircle, 78 readfrom, 63, 82 red, 14 redpart, 18, 4748, 82 Redundant equation, 13 reflectedabout, 36 replacement text, 50, 60, 91