Home

A User`s Manual for MetaPost

1. Name Page Explanation Tahangle 40 angle for arrowheads in degrees default 45 Tahlength 40 size of arrowheads default 4bp Tbboxmargin 25 extra space allowed by bbox default 2bp charcode 45 the number of the next character to be output circmargin 61 clearance around contents of a circular or oval box day the current day of the month defaultcolormodel the initial color model default 5 rgb defaultdx 58 usual horizontal space around box contents default 3bp defaultdy 58 usual vertical space around box contents default 3bp jdefaultpen 43 numeric index used by pickup to select default pen defaultscale 21 font scale factor for label strings default 1 jlabeloffset 20 offset distance for labels default 3bp linecap 38 0 for butt 1 for round 2 for square linejoin 38 0 for mitered 1 for round 2 for beveled miterlimit 38 controls miter length as in PostScript month the current month e g 3 March mpprocset set this to 1 if you want to include a PostScript dictionary of abbreviations in the output pausing gt 0 to display lines on the terminal before they are read prologues 23 gt 0 to output conforming PostScript using built in fonts restoreclipcolor restore the graphics state after clip operations default 1 showstopping gt 0 to stop after each show command time the number of minutes past midnigh
2. gt amp amp and are all legitimate variable names Such symbolic tokens without special meanings are called tags A variable name can be a sequence of tags like f bot or f top The idea is to provide some of the functionality of Pascal records or C structures It is also possible to simulate arrays by using variable names that contain numbers as well as symbolic tokens For example the variable name x2r consists of the tag x the number 2 and the tag r There can also be variables named x3r and even x3 14r These variables can be treated as an array via constructions like x ilr where i has an appropriate numeric value The overall syntax for variable names is shown in Figure 16 Variables like x2 and y2 take on numeric values by default so we can use the fact that z suffix is an abbreviation for z suffix y suffix 7 INTEGRATING TEXT AND GRAPHICS 19 variable tag suffix suffix empty suffix subscript suffix tag subscript number numeric expression Figure 16 The syntax for variable names to generate pair valued variables when needed It turns out that the beginfig macro wipes out pre existing values variables that begin with the tags x or y so that beginfig endfig blocks do not interfere with each other when this naming scheme is used In other words variables that start with x y z are local to the figure they are used in General mechanisms for making variables local w
3. dashpattern on off list on off list on off list on off clause on off clause on off clause on numeric tertiary off numeric 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 8 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 z 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 x 0 and scanning in the positive x direction To make the idea of replicating to infinity more precise let P d be the projection of d onto the x axis and let shift P d x be the result of shifting d by x The pattern resulting from infinite replication is shift P d
4. where X t i 1 t z 3t 1 t rt 30 1 tag Liza Y t i 1 8 y 3t 1 t y 3C yia Yi for 0 lt t lt 1 The precise rules for choosing the B zier control points are described in 2 and in The METAFONTbook 4 In order for the path to have a continuous slope at z y the incoming and outgoing directions at X i Y i must match Thus the vectors must have the same direction i e r y must be on the line segment between x y and 27 y This situation is illustrated in Figure 5 where the B zier control points selected by Meta Post are connected by dashed lines For those who are familiar with the interesting properties of this construction MetaPost allows the control points to be specified directly in the following format draw 0 0 controls 26 8 1 8 and 51 4 14 6 60 40 controls 67 1 61 0 and 59 8 84 6 40 90 controls 25 4 94 0 and 10 5 84 5 10 70 controls 9 6 58 8 and 18 8 49 6 30 50 Figure 5 The result of draw z0 z1 z2 z3 z4 with the automatically selected B zier control polygon illustrated by dashed lines 3 2 Specifying Direction Tension and Curl MetaPost provides many ways of controlling the behavior of a curved path without actually specifying the control points For instance some points on the path may be selected as vertical or horizontal extrema If z1 is to be a horizontal extreme and z2 is to be a vertical extreme you c
5. 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 5 4 Linear Equations An important feature taken from METRFONT 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 atb 3 2a b 3 4 LINEAR EQUATIONS 10 and deduce that a 2 and b 1 The same equations can be written slightly more compactly by stringing them together with multiple equal signs atb 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 gt gt 2 gt gt 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 l 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
6. draw Hell vilg infont ec 1mr10 endfig Using fontmapline you can specify font mapping information inside the figure prologues 2 fontmapline pplbo8r URWPalladioL Bold amp ditto amp 167 SlantFont amp dittok 8r enc uplb8a pfb beginfig 1 draw Hello world infont pplbo8r endfig This will attempt to reencode the PostScript font URW PalladioL Bold whose tfm file is pplbo8r tfm The encoding is found in the file 8r enc and will be included into the output file If the same example was run with prologues 3 MetaPost would include a subset of the font that resides in uplb8a pfb into the output In this case the subset of the font is reorganized so that it has the correct encoding internally 8r enc will not be embedded also The argument to both commands has an optional flag character at the very beginning This optional flag has the same meaning as in pdfIgX option meaning extend the font list but ignore duplicates extend the font list replacing duplicates remove all matching fonts from the font list 7 INTEGRATING TEXT AND GRAPHICS 25 Without any option the current list will be completely replaced If prologues is set to two or three yet there are no fontmapfile statements MetaPost will attempt to locate a default map file with a preference to read mpost map If that fails it will also attempt either troff map or pdftex map depending on whether or not troff mode is enable
7. etex blocks and depends on a preprocessor to translate them into low level MetaPost commands If the main file is fig mp the translated TEX material is placed in a file named fig mpx This is normally done silently without any user intervention but it could fail if one of the btex etex blocks contains an erroneous TEX command Then the erroneous TEX input is saved in the file mpxerr tex and the error messages appear in mpxerr log The preprocessor for TEX labels does understand virtual fonts so you can use your normal TEX font switching commands inside the label TEX macro definitions or any other auxiliary TEX commands can be enclosed in a verbatimtex etex block The difference between btex and verbatimtex is that the former generates a picture expression while the latter only adds material for TEX to process For instance if you want TEX to typeset labels using macros defined in mymac tex your MetaPost input file would look something like this verbatimtex input mymac etex beginfig 1 label btex TEX material using mymac tex etex some coordinates On Unix and other Web2C based systems the option troff to MetaPost tells the preprocessor that btex etex and verbatimtex etex blocks are in troff instead of TEX When using this option MetaPost sets the internal variable troffmode to 1 Setting prologues can be useful with TEX too not just troff Here is some explanation e When prologues is 0 which is the
8. fill bpath s shifted 1pt 1pt unfill bpath s drawboxed s endfor enddef beginfig 51 circleit a btex Box 1 etex circleit b btex Box 2 etex b n a s 0 20pt drawshadowed a b drawarrow a s b n endfig Figure 51 MetaPost code and the resulting figure Note that the drawshadowed macro used here is not part of the boxes mp macro package 11 MAKING BOXES 63 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 ct p curl0 c enddef beginfig 52 verbatimtex def stk 1 2 displaystyle matrix 1 cr 2 cr etex circleit aa btex strut Start etex aa dx aa dy circleit bb btex stk B alb a etex circleit cc btex stk C b etex circleit dd btex stk D alb ab etex circleit ee btex strut Stop etex 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 diri40 bb c label bot btex a etex cuta
9. similar if they occur on the same row of Table 2 Thus A alpha and are symbolic tokens but is interpreted as two tokens and x34 is a symbolic token followed by a number Since the brackets and are listed on lines by themselves the only symbolic tokens involving them are C etc and J etc Some characters are not listed in Table 2 because they need special treatment The four characters O are loners each comma semicolon or parenthesis is a separate token even when they occur consecutively Thus O is four tokens not one or two The percent sign is very special because it introduces comments The percent sign and everything after it up to the end of the line are ignored Another special character is the period Two or more periods together form a symbolic token but a single period is ignored and a period preceded or followed by digits is part of a number Thus and are symbolic tokens while a b is just two tokens a and b It conventional to use periods to separate tokens in this fashion when naming a variable that is more than one token long 6 2 Variable Declarations A variable name is a symbolic token or a sequence of symbolic tokens Most symbolic tokens are legitimate variable names but anything with a predefined meaning like draw or is disallowed ie variable names cannot be macros or MetaPost primitives This minor restriction allows an amazingly broad class of variable names alpha
10. Figure 3 The result of draw z0 zi z2 z3 z4 There are many other ways to draw a curved path through the same five points To make a smooth closed curve connect z4 back to the beginning by appending cycle to the draw statement as shown in Figure 4a It is also possible in a single draw statement to mix curves and straight lines as shown in Figure 4b Just use where you want straight lines and where you want curves Thus draw z0 z1 z2 z3 z4 cycle produces a curve through points 0 1 2 and 3 then a polygonal line from point 3 to point 4 and back to point 0 The result is essentially the same as having two draw statements draw z0 z1 z2 z3 and draw z3 z4 z0 a b Figure 4 a The result of draw z0 zi z2 z3 z4 cycle b the result of draw z0 z1 z2 z3 z4 cycle 3 1 B zier Cubic Curves When MetaPost is asked to draw a smooth curve through a sequence of points it constructs a piecewise cubic curve with continuous slope and approximately continuous curvature This means 3 CURVES 6 that a path specification such as z0 zi1 z2 z3 z4 zb results in a curve that can be defined parametrically as X t Y t for 0 t 5 where X t and Y t are piecewise cubic functions That is there is a different pair of cubic functions for each integer bounded t interval If zO xo yo 21 x1 y1 Z2 22 y2 MetaPost selects B zier control points xf yg 11 41 xi yt
11. Multiplication numeric numeric pair pair eK numeric numeric numeric 15 Exponentiation cmyk color cmyk color cmyk color 15 Addition numeric numeric numeric pair pair pair numeric numeric numeric 15 Pythagorean addition yl r numeric numeric numeric 15 Pythagorean subtraction yl r cmyk color cmyk color cmyk color 15 Subtraction numeric numeric numeric pair pair pair cmyk color cmyk color 15 Negation numeric numeric pair pair cmyk color numeric cmyk color 15 Division numeric numeric pair pair lt gt string string boolean 14 Comparison operators lt gt numeric numeric lt gt pair pair cmyk color cmyk color transform transform Tabs z numeric numeric 17 Absolute value pair and boolean boolean boolean 14 Logical and angle pair numeric 17 2 argument arctangent in degrees arclength path numeric 32 Arc length of a path arctime numeric path numeric 32 Time on a path where arclength from of the start reaches a given value ASCII string numeric ASCII value of first character in string jbbox picture path 25 A rectangular path for the bounding path box pen blackpart cmykcolor numeric 17 Extract the fourth component bluepart color numeric 17 Extracts the third component boolean E any boolean 17 Is the expression of type boolean bot numeric numeric 42 Bottom of current pen when centered pair pair at the given coordinate
12. 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 zi z3 a 0 z2 z4 0 b draw zi z2 z3 z4 cycle draw zi z0 z2 label top a 5 z0 z1 label 1ft b 5 z0 z2 dotlabel bot 0 0 zO endfig 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 zO and then puts the label 0 0 just below the dot 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 For simple applications of labeled figures you can normally get by with just label and dotlabel In fact you may be able to use a short form of the dotlabel statement that saves a lot of typing when you have many points z0 z1 z a z b etc and you want to use the z suffixes as labels The statement dotlabels rt 0 1 a is equivalent to dotlabel rt 0 z0 dotlabel rt 1 z1 dotlabel rt a z a Thus the argument to dotlabels is a list of suffixes for which z variables are known and the label suffix
13. just a conversion factor and Ocm just multiplies the conversion factor by zero MetaPost understands constructions like 2cm as shorthand for 2 cm It is convenient to introduce your own scale factor say u Then you can define coordinates in terms of u and decide later whether you want to begin with u 1cm or u 0 5cm This gives you control over what gets scaled and what does not so that changing u will not affect features such as line widths There are many ways to affect the appearance of a line besides just changing its width so the width control mechanisms allow a lot of generality that we do not need yet This leads to the strange looking statement pickup pencircle scaled 4pt for setting the line width for subsequent draw statements to 4 points This is about eight times the default line width With such a wide line width even a line of zero length comes out as a big bold dot We can use this to make a grid of bold dots by having one drawdot statement for each grid point Such a repetitive sequence of draw statements is best written as a pair of nested loops for i 0 upto 2 for j 0 upto 2 drawdot i u j u endfor endfor The outer loop runs for i 0 1 2 and the inner loop runs for j 0 1 2 The result is a three by three grid of bold dots as shown in Figure 2 The figure also includes a larger version of the polygonal line diagram that we saw before beginfig 2 u 1cm draw 2u 2u 0 0 0 3u 3u 0 0 0 pickup
14. n d integers n where d measures the length of P d The most restrictive possible definition of this length is dmax Amin Where dmin dmax is the range of x coordinates in P d In fact MetaPost uses max yo d gt dmax dmin 8 ADVANCED GRAPHICS 38 where yo d is the y coordinate of the contents of d The contents of d should lie on a horizontal line but if they do not the MetaPost interpreter just picks a y coordinate that occurs in d A picture used as a dashed pattern must contain no text or filled regions but it can contain lines that are themselves dashed This can give small dashes inside of larger dashes as shown in Figure 32 beginfig 32 draw dashpattern on 15bp off 15bp dashed evenly picture p zu xm p currentpicture currentpicture nullpicture Gre odes draw fullcircle scaled 1cm xscaled 3 dashed p endfig Figure 32 MetaPost code for dashed patterns and the corresponding output Also dashed patterns are intended to be used either with pencircle or no pen at all pensquare and other complex pens should be avoided This is because the output uses the PostScript prim itive setdash which does not interact well with the filled paths created by polygonal pens See Section 8 7 p 42 8 5 Local specials If you want to attach a special bit of PostScript code you can use withprescript string expression and withpostcript string expression the strings will be written to the output file before
15. show expression to ask MetaPost to print a symbolic representation of the value of each expression For known numeric values each is printed on a new line preceded by gt gt Other types of result are printed similarly except that complicated values are sometimes not printed on standard output This produces a reference to the transcript file that looks like this gt gt picture see the transcript file If you want to the full results of show statements to be printed on your terminal assign a positive value to the internal variable tracingonline 5 1 Data Types MetaPost actually has ten basic data types numeric pair path transform rgb color cmykcolor string boolean picture and pen Let us consider these one at a time beginning with the numeric type Numeric quantities in MetaPost are represented in fixed point arithmetic as integer multiples of cag They must normally have absolute values less than 4096 but intermediate results can be eight times larger This should not be a problem for distances or coordinate values since 4096 PostScript points is more than 1 4 meters If you need to work with numbers of magnitude 4096 or more setting the internal variable warningcheck to zero suppresses the warning messages about large numeric quantities The pair type is represented as a pair of numeric quantities We have seen that pairs are used to give coordinates in draw statements Pairs can be added subtracted used in me
16. 26 evenly 36 38 exitif 57 exitunless 57 exponentiation 15 expr 45 47 expression 14 54 78 extra beginfig 86 extra endfig 86 false 14 fi 47 files input 1 mpx 23 86 output 3 t m 21 84 transcript 2 13 66 67 fill 26 45 54 filldraw 40 fixpos 59 fixsize 59 floor 17 fontmapfile 24 fontmapline 24 fontsize 21 for 3 56 forever 57 forsuffixes 57 fractions 16 fullcircle 27 28 43 functions 45 generic variable 53 81 getmid 51 green 13 greenpart 17 halfcircle 27 28 hex 73 hide 48 identity 34 if 47 67 68 image 44 in 3 Inconsistent equation 10 12 incr 51 55 indexing 15 inequality 14 infinity 31 inflections 7 INDEX infont 25 input 58 68 interim 47 56 internal variables 13 19 20 25 26 38 40 45 47 58 61 66 67 84 intersection 29 31 intersectionpoint 29 54 intersections 28 intersectiontimes 20 inverse 34 joinup 51 54 kerning 21 84 known 17 label 19 label suffix 19 80 81 labeloffset 20 labels 21 labels typesetting 21 labels with variable text 64 IATEX typesetting labels with 64 left 7 length 31 let 76 lft 20 42 ligatures 21 84 linecap 38 46 56 linejoin 38 llcorner 25 llft 20 locality 19 45 loggingall 67 loops 3 56 68 lrcorner 25 lrt 20 magentapart 17 makempx 24 makepath 43 makepen 43 mark angle 48 mark rt angle 48 max 77
17. 3 What follows is a description of how to use the macros contained in the file boxes mp This file is included in a special directory reserved for MetaPost macros and 11 MAKING BOXES 58 loop loop header loop text endfor loop header for symbolic token progression for symbolic token for list forsuffixes symbolic token suffix list forever progression numeric expression upto numeric expression numeric expression downto numeric expression numeric expression step numeric expression until numeric expression for list expression for list expression suffix list suffix suffix list suffix Figure 47 The syntax for loops support software and can be accessed by giving the MetaPost command input boxes before any figures that use the box making macros The syntax for the input command is input file name where a final mp can be omitted from the file name The input command looks first in the current directory and then in the special macro directory Users interested in writing macros may want to look at the boxes mp file in this directory 11 1 Rectangular Boxes The main idea of the box making macros is that one should say boxit suffix picture expression where the suffix does not start with a subscript This creates pair variables suffix c suffix n suffix e that can then be used for positioning the picture before draw
18. 3 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 thirds of x but 2 3x is and 3 3 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 parts are cyanpart c magentapart c yellowpart c blackpart c The pa
19. Plain MetaPost has statements for drawing arrows and the arrowheads are slightly rounded when linejoin is rounded The effect depends on the line width and is quite subtle at the default line width of 0 5bp as shown in Figure 36 1 2 drawarrow z1 z2 3 4 4 drawarrow reverse z3 z4 5 4 6 drawdblarrow z5 z6 Figure 36 Three ways of drawing arrows Drawing arrows like the ones in Figure 36 is simply a matter of saying drawarrow path expression 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 n point tof reverse p and point n t 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 a
20. 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 fright z2 does not need parentheses around z1 1 1 5 3 Fractions Mediation and Unary Operators Mediation expressions do not appear in the basic expression syntax of Figure 14 Mediation expres sions 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 b since it is equivalent to 1 a b the latter is a b a or 2a b numeric primary numeric atom numeric atom numeric expression numeric expression of operator expression of primary unary op primary numeric atom numeric variable
21. and after the current object each beginning on their own line You can specify multiple withprescript or withpostscript options if you like 8 6 Other Options You might have noticed that the dashed lines produced by dashed evenly appear to have more black than white This is an effect of the linecap parameter that controls the appearance of the ends of lines as well as the ends of dashes There are also a number of other ways to affect the appearance of things drawn with MetaPost The linecap parameter has three different settings just as in PostScript Plain MetaPost gives this internal variable the default value rounded which causes line segments to be drawn with rounded ends like the segment from z0 to z3 in Figure 33 Setting linecap butt cuts the ends off flush so that dashes produced by dashed evenly have length 3bp not 3bp plus the line width You can also get squared off ends that extend past the specified endpoints by setting linecap squared as was done in the line from z2 to z5 in Figure 33 Another parameter borrowed from PostScript affects the way a draw statement treats sharp corners in the path to be drawn The linejoin parameter can be rounded beveled or mitered as shown in Figure 34 The default value for plain MetaPost is rounded which gives the effect of drawing with a circular brush When linejoin is mitered sharp corners generate long pointed features as shown in Figure 35 Since this might be undesirable there is a
22. as round and unitvector statements such as fill and draw and binary operators such as dotprod and intersectionpoint The main difference between these macros and the ones we already know how to define is their argument syntax The round and unitvector macros are examples of what Figure 14 calls unary op That is they are followed by a primary expression To specify a macro argument of this type the macro definition should look like this vardef round primary u replacement text enddef The u parameter is an expr parameter and it can be used exactly like the expr parameter defined using the ordinary expr u syntax As the round example suggests a macro can be defined to take a secondary tertiary or an expression parameter For example the predefined definition of the fill macro is roughly def fill expr c addto currentpicture contour c enddef 9 MACROS 55 It is even possible to define a macro to play the role of of operator in Figure 14 For example the direction of macro has a definition of this form vardef direction expr t of p replacement text enddef Macros can also be defined to behave like binary operators For instance the definition of the dotprod macro has the form primarydef w dotprod z replacement text enddef This makes dotprod a primary binop Similarly secondarydef and tertiarydef introduce sec ondary binop and tertiary binop definitions These all define ordinary macros
23. either of z1 and z3 are known For instance MetaPost will accept the equations z3 z1 1in 6in z20 whatever z1 z3 but it will not be able to determine any of the components of z1 z3 or z20 These equations do give partial information about zi z3 and z20 A good way to see this is to give another equation such as x20 x1 y20 y1 6 This produces the error message Redundant equation MetaPost assumes that you are trying to tell it something new so it will usually warn you when you give a redundant equation If the new equation had been x20 x1 y20 y1 6 1in the error message would have been Inconsistent equation off by 71 99979 This error message illustrates roundoff error in MetaPost s linear equation solving mechanism Roun doff error is normally not a serious problem but it is likely to cause trouble if you are trying to do something like find the intersection of two lines that are almost parallel 5 EXPRESSIONS 13 5 Expressions It is now time for a more systematic view of the MetaPost language We have seen that there are numeric quantities and coordinate pairs and that these can be combined to specify paths for draw statements We have also seen how variables can be used in linear equations but we have not discussed all the operations and data types that can be used in equations It is possible to experiment with expressions involving any of the data types mentioned below by using the statement
24. is a useful starting point for this process This can be illustrated by paraphrasing the above equation for T into English T should be the transform obtained by doing whatever identity does Then scaling x coordinates by 1 rotating 45 and shifting by 1 1 This works because identity is the identity transformation which does nothing i e transformed identity is a no op The syntax for transform expressions and transformation operators is given in Figure 27 It includes two more options for transformer reflectededabout p q reflects about the line defined by points p and q and rotatedaround p 0 rotates 0 degrees counter clockwise around point p For example the equation for initializing trans form T could have been T identity reflectedabout 2 0 0 2 There is also a unary operator inverse that takes a transform and finds another transform that undoes the effect of the first transform Thus if p q transformed T 8 ADVANCED GRAPHICS 35 pair secondary pair secondary transformer path secondary path secondary transformer picture secondary picture secondary transformer pen secondary pen secondary transformer transform secondary transform secondary transformer transformer rotated numeric primary scaled numeric primary shifted pair primary slanted numeric primary transformed transform primary xscaled numeric primary yscaled numeric prima
25. 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 4 1 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 z number is convenient because it is an abbreviation for x number y number 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 zi z2 2in 0 x3 x6 3in x3 y3 x6 y6 1 1in Exactly the same points could be obtained by setting their values directly zi 2in 0 z2 2in 0 z3 3in 6in z6 3in 1 2in 4 LINEAR EQUATIONS 11 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
26. models The setbounds and truecorners features are only found in MetaPost version 0 30 and higher 8 ADVANCED GRAPHICS 27 beginfig 21 path p p 1cm 0 0 1cm 1cm 0 fill pfup 0 0 1 2 up cycle draw p 0 1cm cycle endfig Figure 21 MetaPost code and the corresponding output Actual input Remapped meaning withcolor rgbcolor c withrgbcolor c withcolor cmykcolor c withemykcolor c withcolor numeric c withgreyscale c withcolor false withoutcolor withcolor true current default color model For the specific color models there are also fill path expression withrgbcolor rgbcolor expression fill path expression withcmykcolor cmykcolor expression fill path expression withgreyscale numeric fill path expression withoutcolor An image object cannot have more then one color model the last withcolor withrgbcolor withcmykcolor withgreyscale or withoutcolor specification sets the color model for any partic ular object The model withoutcolor needs a bit more explanation selecting this model means that Meta Post will not write a color selection statement to the PostScript output file for this object The current default color model can be set up using the internal parameter defaultcolormodel Valid values are no model greyscale rgb default cmyk NIOtT WF Figure 22 illustrates several applications of the fill command to fill areas with shades of gray T
27. not vardef macros e g there is no primaryvardef Thus macro definitions can be introduced by def vardef primarydef secondarydef or tertiarydef A replacement text is any list of tokens that is balanced with respect to def enddef pairs where all five macro definition tokens are treated like def for the purpose of def enddef matching The rest of the syntax for macro definitions is summarized in Figure 46 The syntax contains a few surprises The macro parameters can have a delimited part and an undelimited part Normally one of these is empty but it is possible to have both parts nonempty def foo text a expr b replacement text enddef This defines a macro foo to take a text parameter in parentheses followed by an expression macro definition macro heading replacement text enddef macro heading def symbolic token delimited part undelimited part vardef generic variable delimited part undelimited part vardef generic variable delimited part undelimited part binary def parameter symbolic token parameter delimited part empty delimited part parameter type parameter tokens parameter type expr suffix text parameter tokens parameter parameter tokens parameter parameter symbolic token undelimited part empty parameter type parameter precedence level parameter expr parameter of parameter precedence leve
28. number or fraction numeric expression numeric nullary op number or fraction gt 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 primary binop such as sqrt makes the difference clear sqrt 2 3 means Y while 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 primary sqrt 1 1 3 6 VARIABLES 17 binop For instance abs x and abs x both compute the absolute value of x The same holds for the 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
29. of points and directions whose names are obtained by appending mid off and dir to the path variable The joinup macro takes arrays of points and directions and creates a path of length n that passes through each pt i with direction d i or d i A definition that starts def joinup suffix pt d expr n might suggest that calls to the joinup macro should have two sets of parentheses as in joinup p mid p dir 36 instead of joinup p mid p dir 36 In fact both forms are acceptable Parameters in a macro call can be separated by commas or by pairs The only restriction is that a text parameter must be followed by a right parenthesis For instance a macro foo with one text parameter and one expr parameter can be called foo a b c in which case the text parameter is a b and the expr parameter is c but foo a b c sets the text parameter to parameter a b c and leaves the MetaPost interpreter still looking for the expr 9 MACROS 52 def getmid suffix p pair p mid p off p dir for i 0 upto 36 p dir i dir 5 i p mid i p off i directionpoint p dir i of p p midli p off i directionpoint p dir i of p endfor enddef def joinup suffix pt d expr n begingroup save res g path res res pt 0 d 0 for i 1 upto n g if pt i pt i 1 dotprod d i 0 fi 1 res res g d i 1 g d i pt il endfor res endgroup enddef beginfig 45 path p
30. pencircle scaled 4pt for i 0 upto 2 for j 0 upto 2 drawdot i u j u endfor endfor endfig Figure 2 MetaPost commands and the resulting output Note that the program in Figure 2 starts with beginfig 2 and ends with endfig These are macros that perform various administrative functions and ensure that the results of all the draw statements get packaged up and translated into PostScript A MetaPost input file normally contains a sequence of beginfig endfig pairs with an end statement after the last one If this file is named fig mp the output from draw statements between beginfig 1 and the next endfig is written in a file fig 1 In other words the numeric argument to the beginfig macro determines the name of the corresponding output file 3 CURVES 4 0696 A percent sign j The current jobname 96 0 9 c The charcode value 0 9 y The current year 96 0 9 m The numeric month 96 0 9 d The day of the month 0 9 H The hour 96 0 9 M The minute Table 1 Allowed escape sequences for filenametemplate What does one do with all the PostScript files They can be included as figures in a TEX or troff document if you have an output driver that can handle encapsulated PostScript figures If your standard TEX macro directory contains a file epsf tex you can probably include fig 1 in a TEX document as follows input epsf epstbox fig 1 8 The epsfbox macro figures out how much room to leave for the figure and uses TEX s s
31. 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 To turn off drawoptions all together just give an empty list drawoptions This is done automatically by the beginfig macro Since irrelevant options are ignored there is no harm in giving a statement like drawoptions dashed evenly followed by a sequence of draw and fill commands It does not make sense to use a dash pattern when filling so the dashed evenly gets ignored for fill statements It turns out that drawoptions withpen pen expression does affect fill statements as well as draw statements In fact there is a special pen variable called currentpen such that fill withpen currentpen is equivalent to a filldraw statement Precisely what does it mean to say that drawing options affect those statements where they make sense The dashed dash pattern option only affects draw path expression 8 ADVANCED GRAPHICS 42 statements and text appearing in the picture expression argument to draw picture expression statement is only affected by the withcolor color expression option For all other combinations of drawing statements and options there is some effect An opti
32. q p 5 2 3 4 1 3 2 3 0 5 3 4 5 3 cycle scaled 3cm shifted 0 5cm getmid p draw p draw joinup p mid p dir 36 cycle q joinup p off p dir 36 draw q q rotated 180 cycle drawoptions dashed evenly for i 0 upto 3 draw p mid 9i p off 9i p mid 9i p off 9i draw p off 9i p off 9i endfor endfig Figure 45 MetaPost code and the corresponding figure 9 MACROS 53 9 4 Vardef Macros A macro definition can begin with vardef instead of def Macros defined in this way are called vardef macros They are particularly well suited to applications where macros are being used like functions or subroutines The main idea is that a vardef macro is like a variable of type macro Instead of def symbolic token a vardef macro begins vardef generic variable where a generic variable is a variable name with numeric subscripts replaced by the generic sub script symbol In other words the name following vardef obeys exactly the same syntax as the name given in a variable declaration It is a sequence of tags and generic subscript symbols starting with a tag where a tag is a symbolic token that is not a macro or a primitive operator as explained in Section 6 2 The simplest case is when the name of a vardef macro consists of a single tag Under such circumstances def and vardef provide roughly the same functionality The most obvious difference is that begingrou
33. shifted pair primary slanted numeric primary transformed transform primary xscaled numeric primary yscaled numeric primary zscaled pair primary reflectedabout pair expression pair expression rotatedaround pair expression numeric expression nullary op false normaldeviate nullpicture pencircle true whatever unary op type abs angle arclength ASCII bbox blackpart bluepart bot ceiling center char cosd cyanpart cycle decimal dir floor fontsize greenpart greypart hex inverse known length 1ft 11corner lrcorner magentapart makepath makepen mexp mlog not oct odd redpart reverse round rt sind sqrt top ulcorner uniformdeviate unitvector unknown urcorner xpart xxpart xypart yellowpart ypart yxpart yypart type boolean cmykcolor color numeric pair path pen picture string transform primary binop and dotprod div infont nod secondary binop gt lor intersectionpoint intersectiontimes tertiary binop gt amp lt lt lt gt gt gt cutafter cutbefore of operator gt arctime direction directiontime directionpoint penoffset point postcontrol precontrol subpath substring variable tag suffix suffix empty suffix subscript suffix tag suffix parameter subscript num
34. shifting to the left moves them backward Figure 30 illustrates this effect The dash pattern can be thought of as an infinitely repeating pattern strung out along a horizontal line where the portion of the line to the right of the y axis is laid out along the path to be dashed 9withdots is only found in MetaPost version 0 50 and higher 8 ADVANCED GRAPHICS 37 Ge e7 draw z6 z7 dashed e4 shifted 18bp 0 4e 5 draw z4 z5 dashed e4 shifted 12bp 0 2e e3 draw z2 z3 dashed e4 shifted 6bp 0 Oe el draw z0 z1 dashed e4 Figure 30 Dashed lines and the MetaPost statements for drawing them where e4 refers to the dash pattern evenly scaled 4 When you shift a dash pattern so that the y axis crosses the middle of a dash the first dash gets truncated Thus the line with dash pattern e4 starts with a dash of length 12bp followed by a 12bp gap and another 12bp dash etc while e4 shifted 6bp 0 produces a 6bp dash a 12 bp 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
35. the end of a path Such infinite time values do not work for a cyclic path since time values outside of the normal range can be handled by modular arithmetic in that case i e a cyclic path p through points zo 21 Z2 Zn 1 has the normal parameter range 0 lt t lt n but point t of p can be computed for any t by first reducing t modulo n If the modulus n is not readily available length path primary gives the integer value of the upper limit of the normal time parameter range for the specified path MetaPost uses the same correspondence between time values and points on a path to evaluate the subpath operator The syntax for this operator is subpath pair expression of path primary If the value of the pair expression is t1 t2 and the path primary is p the result is a path that follows p from point t of pto point t2 of p If tg lt t the subpath runs backwards along p An important operation based on the subpath operator is the tertiary binop cutbefore For intersecting paths p and po p cutbefore po is equivalent to subpath xpart p intersectiontimes po length pi of pi 8 ADVANCED GRAPHICS 32 except that it also sets the path variable cuttings to the portion of p that gets cut off In other words cutbefore returns its first argument with the part before the intersection cut off With multiple intersections it tries to cut off as little as possible If the paths do not intersect cutbefore re
36. values and these values can only be changed by using the assignment operator Internal variables are initially zero except that the Plain macro package gives some of them nonzero initial values The Plain macros are normally preloaded automatically as explained in Section 1 7 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 label label suffix string or picture expression pair expression 7 INTEGRATING TEXT AND GRAPHICS 20 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 1ft 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 1ft rt top bot ulft urt 11 t 1rt where 1ft and rt mean left and right and 11ft ulft etc mean lower left upper left
37. w interim defaultdy 7bp boxjoin a sw b nw a se b ne boxit ba boxit bb boxit bc boxit bd btex vdots etex boxit be boxit bf bd dx 8bp ba ne a sw 15bp 10bp drawboxed ba bb bc bd be bf label lft hashtab ba w vardef ndblock suffix boxjoin a sw b nw a se b ne forsuffixes 1 2 3 boxit dx dy 5 5bp 4bp endfor enddef ndblock nda ndblock ndb ndblock ndc ndai c bb c ndbi c nda3 c whatever 0 xpart ndb3 se xpart ndc1 ne xpart di c ndci c be c whatever 0 drawboxed ndai nda2 nda3 ndbi ndb2 ndb3 ndci ndc2 ndc3 drawarrow bb c ndal w drawarrow be c ndci w drawarrow nda3 c ndb1 w drawarrow ndai c right curlO ni c cutafter bpath ni drawarrow nda2 c right curl0 di c cutafter bpath di drawarrow ndci c right curl0 nil c cutafter bpath nil drawarrow ndc2 c right curl0 dil c cutafter bpath dil drawarrow ndbi c right nk c cutafter bpath nk drawarrow ndb2 c right dk c cutafter bpath dk x ptr xpart aa c y ptr ypart ndci ne drawarrow subpath 0 7 of z ptr left ndc3 c dashed evenly label rt btex strut ndblock etex z ptr endfig ndtable n di Ni 1 digi qu dk 4 hashtab ar ndblock Figure 49 MetaPost code and the corresponding figure 11 MAKING BOXES 61 to the box name off variables as needed to fix t
38. withpostscript string expression withpen pen expression dashed picture expression Figure 39 The syntax for primitive drawing statements The syntax for primitive drawing commands is compatible with METRFONT 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 p withpen pencircle 8 ADVANCED GRAPHICS 44 is equivalent to addto currentpicture doublepath p 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 equivalent primitives draw pic addto currentpicture also pic draw p addto currentpicture doublepath p withpen q fillc addto currentpicture contour c filldraw c addto currentpicture contour c withpen q undraw pic addto currentpicture also pic withcolor b undraw p addto currentpicture doublepath p withpen q withcolor b unfillc addto currentpicture contour c withcolor b unfilldraw c addto currentpicture contour c withpen q withcolor b Table 3 Common drawing statements and equivalent primitive versions where q stands for currentpen b stands for background p s
39. z3 z6 means that z4 is i of the way from z3 to z6 i e 1 z4 z34 3 26 z3 Similarly z5 2 3 z3 z6 makes z5 2 of the way from 23 to 26 20 beginfig 13 A zi z2 2in 0 x3 x6 3in x3 y3 x6 y6 1 1in z4 1 3 z3 z6 z5b 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 3 pickup pencircle scaled ipt draw zi z2 draw z3 z6 endfig aD 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 s
40. A User s Manual for MetaPost John D Hobby documented version 0 99 Abstract The MetaPost system implements a picture drawing language very much like Knuth s METR FONT 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 serves as an introductory user s manual It does not require knowledge of METAFONT or access to The METAFONTbook but both are beneficial An appendix explains the differences between MetaPost and METAFONT Contents 1 Introduction 2 Basic Drawing Statements 2 1 Filename templates t 4 p aordi eee ea S Id uA 3 Curves 34d Bezier C bic Qurv s ue vv a A a gd Eidem XE E aser 3 2 Specifying Direction Tension and Curl les 3 3 Summary of Path Syntax 9 46 ox RE Bee aes BOS ehh dos d PP au 4 Linear Equations 4 1 Equations and Coordinate Pairs 2222s 4 2 Dealing with Unknowns 200 0 0002 2 eee eee ee 5 Expressions od Data yp sca oos cede RRR A Sedem ahaa Eee fe te POR a 5 2 Operatotso c AAA a eth ee E eed 5 3 Fractions Mediation and Unary Operators lle 6 Variables 6 15 Token 2 ADR d e de db deu ute LV MULA Vos teas nant 6 2 Variable Declarations o o o a a E a ee 7 In
41. Please report bugs and request enhancements either on the metapostOtug org list or through Sarovar Please do not send reports directly to Dr Hobby any more 2 Basic Drawing Statements The simplest drawing statements are the ones that generate straight lines T hus draw 20 20 0 0 draws a diagonal line and draw 20 20 0 0 0 30 30 0 0 0 Ps MetaPost also has a drawdot command to print a single point as in drawdot 30 0 draws a polygonal line like this What is meant by coordinates like 30 0 MetaPost uses the same default coordinate system that PostScript does This means that 30 0 is 30 units to the right of the origin where a unit 5A prompt is used for interactive input and a prompt indicates that an input file name is expected This can be avoided by invoking MetaPost on a file that ends with an end command 2 BASIC DRAWING STATEMENTS 3 is gt of an inch We shall refer to this default unit as a PostScript point to distinguish it from the standard printer s point which is Tix inches MetaPost uses the same names for units of measure that TEX and METAFONT do Thus bp refers to PostScript points big points and pt refers to printer s points Other units of measure include in for inches cm for centimeters and mm for millimeters For example 2cm 2cm 0 0 0 3cm 3cm 0 0 0 generates a larger version of the above diagram It is OK to say 0 instead Ocm because cm is really
42. X It has the advantage of maximum flexibility different TEX constructs can use different TEX processors But at least two other methods are possible e Set the environment variable TEX to latex or whatever processor you want to invoke To handle Con TEXt fragments texexec could be used This might be convenient when writing a script or working on a project that always requires latex e Invoke MetaPost with the command line option tex latex or whatever processor of course This might be useful from a Makefile or just a one off run 12 2 mproof tex mproof tex is a plain TEX routine not MetaPost at all It writes a proof sheet for MetaPost output Call it like this tex mproof MetaPost output filename Then process the resulting dvi file as usual 13 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 4 Suppose your input file says draw zi z2 on line 17 without first giving known values to z1 and z2 Figure 53 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 Sinc
43. ading a tfm file This is explained in The TEXbook 5 It should be possible to use built in PostScript fonts but the names for them are system dependent Some typical ones are ptmr8r for Times Roman pplr8r for Palatino and phvr for Helvetica The Fontname document available at http tug org fontname has much more information about font names and TeX A TEX font such as cmr10 is a little dangerous because it does not have a space character or certain ASCII symbols MetaPost does not use the ligatures and kerning information that comes with a TEX font Further MetaPost itself does not interpret virtual fonts 7 1 Typesetting Your Labels TEX may be used to format complex labels If you say btex typesetting commands etex in a MetaPost input file the typesetting commands get processed by TEX and translated into a picture expression actually a picture primary that can be used in a label or dotlabel statement Any spaces after btex or before etex are ignored For instance the statement label lrt btex sqrt x etex 3 sqrt 3 u in Figure 18 places the label x at the lower right of the point 3 sqrt 3 u Figure 19 illustrates some of the more complicated things that can be done with labels Since the result of btex etex is a picture it can be operated on like a picture In particular it is possible to apply transformations to pictures We have not discussed the syntax for this yet but a picture secondary can be pictu
44. ame 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 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 5 2 Operators There are many different ways to make expressions of the nine basic types but most of the operations fit into a fairly simple syntax with four levels of precedence as shown in Figure 14 There are primaries secondaries tertiaries and expressions of each of the basic types so the syntax rules could be specialized to deal with items such as numeric primary boolean tertiary etc This allows the result type for an operation to depend on the choice of operator and the types of its operands For example the lt relation is a tertiary binary that can be applied to a numeric expression and a numeric tertiary to give a boole
45. an expression The same operator can accept other operand types such as string expression and string tertiary but an error message results if the operand types do not match 5 EXPRESSIONS 15 primary variable expression nullary op of operator expression of primary unary op primary secondary primary secondary primary binop primary tertiary secondary tertiary secondary binop secondary expression tertiary expression tertiary binop tertiary Figure 14 The overall syntax rules for expressions The multiplication and division operators and are examples of what Figure 14 calls a primary binop Each can accept two numeric operands or one numeric operand and one operand of type pair or color The exponentiation operator is a primary binop that requires two numeric operands Placing this at the same level of precedence as multiplication and division has the unfortunate consequence that 3 a 2 means 3a not 3 a Since unary negation applies at the primary level it also turns out that a 2 means a Fortunately subtraction has lower precedence so that a b 2 does mean a b instead of a b Another primary binop is the dotprod operator that computes the vector dot product of two pairs For example z1 dotprod z2 is equivalent to xi y1 x2 y2 The additive operators and are secondary binops that operate on numerics pairs or colo
46. an specify that X t Y t should go upward at zi and to the left at z2 draw z0O zi up z2 left z3 24 3 CURVES 7 The resulting shown in Figure 6 has the desired vertical and horizontal directions at z1 and z2 but it does not look as smooth as the curve in Figure 3 The reason is the large discontinuity in curvature at z1 If it were not for the specified direction at z1 the MetaPost interpreter would have chosen a direction designed to make the curvature above z1 almost the same as the curvature below that point Figure 6 The result of draw zO zi up z2 left z3 24 How can the choice of directions at given points on a curve determine whether the curvature will be continuous The reason is that curves used in MetaPost come from a family where a path is determined by its endpoints and the directions there Figures 7 and 8 give a good idea of what this family of curves is like beginfig 7 for a 0 upto 9 draw 0 0 fdir 45 dir 10a 6cm 0 endfor endfig Figure 7 A curve family and the MetaPost instructions for generating it beginfig 8 for a 0 upto 7 draw 0 0 fdir 45 dir 10a 6cm 0 endfor endfig Figure 8 Another curve family with the corresponding MetaPost instructions Figures 7 and 8 illustrate a few new MetaPost features The first is the dir operator that takes an angle in degrees and generates a unit vector in that direction Thus dir 0 is equivalent to right and dir 90 is equivalent to up Ther
47. as a PostScript file whose name ends nnn where nnn is the decimal repres entation of the value of the internal variable charcode The name charcode is for compatibility with METAFONT Normally beginfig sets charcode and endfig invokes shipout 9 Macros As alluded to earlier MetaPost has a set of automatically included macros called the Plain macro package and some of the commands discussed in previous sections are defined as macros instead of being built into MetaPost The purpose of this section is to explain how to write such macros Macros with no arguments are very simple A macro definition def symbolic token replacement text enddef makes the symbolic token an abbreviation for the replacement text where the replacement text can be virtually any sequence of tokens For example the Plain macro package could almost define the fill statement like this def fill addto currentpicture contour enddef Macros with arguments are similar except they have formal parameters that tell how to use the arguments in the replacement text For example the rotatedaround macro is defined like this def rotatedaround expr z d shifted z rotated d shifted z enddef The expr in this definition means that formal parameters z and d can be arbitrary expressions They should be pair expressions but the MetaPost interpreter does not immediately check for that Since MetaPost is an interpreted language macros with arguments ar
48. aths intersect more than once The general rule for the buildcycle macro is that buildcycle pi P2 P3 px chooses the intersection between each p and p 1 to be as late as possible on p and as early as possible on p 1 There is no simple rule for resolving conflicts between these two goals so you should avoid cases where one intersection point occurs later on p and another intersection point occurs earlier on pj44 The preference for intersections as late as possible on p and as early as possible on p 1 leads to ambiguity resolution in favor of forward going subpaths For cyclic paths such as path b in Figure 23 early and late are relative to a start finish point which is where you get back to when you say cycle For the path b this turns out to be the rightmost point on the circle A more direct way to deal with path intersections is via the secondary binop intersection point that finds the points P Q R and S in Figure 24 This macro finds a point where two given paths intersect If there is more than one intersection point it just chooses one if there is no intersection the macro generates an error message 8 2 Dealing with Paths Parametrically The intersectionpoint macro is based on a primitive operation called intersectiontimes This secondary binop is one of several operations that deal with paths parametrically It locates an intersection between two paths by giving the time parameter on ea
49. ations before they are performed tracingequations shows each variable when it becomes known tracinglostchars warns about characters omitted from a picture because they are not in the font being used to typeset labels tracingmacros shows macros before they are expanded tracingoutput shows pictures as they are being shipped out as PostScript files tracingrestores shows symbols and internal variables as they are being restored at the end of a group tracingspecs shows the outlines generated when drawing with a polygonal pen tracingstats shows in the transcript file at the end of the job how many of the MetaPost inter preter s limited resources were used 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 A REFERENCE MANUAL 68 A Reference Manual Tables 4 12 summarize the built in features of Plain MetaPost and the features defined in the boxes mp macro file As explained in Section 11 the boxes mp macro file is not automatically preloaded and the macros defined there are not accessible until you ask for them via the command input boxes Features that depend on boxes mp are marked by symbols Features from the Plain macro package are marked by symbols and MetaPost primitives are not marked by or f The distinction b
50. b picture pa pb pa thelabel btex A etex 0 5cm B pb thelabel btex B etex 0 1 5cm fill a withcolor 7white U qe fill b withcolor 7white fill ab withcolor 4white unfill bbox pa draw pa unfill bbox pb draw pb label lft btex U etex 1cm 5cm draw bbox currentpicture endfig Figure 22 MetaPost code and the corresponding output background where background is normally equal to white as is appropriate for printing on white paper If necessary you can assign a new color value to background The labels need to be stored in pictures pa and pb to allow for measuring their bounding box before actually drawing them The macro thelabel creates such pictures and shifts them into position so that they are ready to draw Using the resulting pictures in draw statements of the form draw picture expression adds them to currentpicture so that they overwrite a portion of what has already been drawn In Figure 22 just the white rectangles produced by unfill get overwritten 8 1 Building Cycles The buildcycle command constructs paths for use with the fill or unfill macros When given two or more paths such as aa and b the buildcycle macro tries to piece them together so as to form a cyclic path In this case path aa is a semicircle that starts just to the right of the intersection with path b then passes through b and ends just outside the circle on the left as shown in Figure 23a Figur
51. ber numeric expression internal variable ahangle ahlength bboxmargin charcode day defaultpen defaultscale labeloffset linecap linejoin miterlimit month pausing prologues showstopping time tracingoutput tracingcapsules tracingchoices tracingcommands tracingequations tracinglostchars tracingmacros tracingonline tracingrestores tracingspecs tracingstats tracingtitles truecorners warningcheck year symbolic token defined by newinternal Figure 56 Part 2 of the syntax for expressions A REFERENCE MANUAL 80 pseudo function min expression list path max expression list incr numeric variable decr numeric variable dashpattern on off list interpath numeric expression path expression path expression buildcycle path expression list thelabel label suffix expression pair expression expression list path expression path expression list path expression on off list on off list on off clause on off clause on off clause on numeric tertiary off numeric tertiary Figure 57 The syntax for function like macros boolean expression expression cmykcolor expression expression color expression expression numeric atom atom numeric expression expression numeric primary primary numeric tertiary tertiary numeric variable variable int
52. ble fontdimen headerbyte kern ligtable ligtable operators 1 gt l gt l 1 l 1 gt l 1 gt gt Il internal variables boundarychar chardp charext charht charic charwd designsize fontmaking other operators charexists Table 13 MetaPost primitives for making tfm files Even though MetaPost has the primitives for generating fonts many of the font making primitives and internal variables that are part of Plain METAFONT are not defined in Plain MetaPost Instead there is a separate macro package called mfplain that defines the macros required to allow MetaPost to process Knuth s Computer Modern fonts as shown in Table 14 6 To load these macros put amp mf plain before the name of the input file This can be done at the prompt after invoking the MetaPost interpreter with no arguments or on a command line that looks something like this mpost amp mfplain cmri0 The analog of a METAFONT command line like mf mode lowres mag 1 2 input cmr10 is mpost amp mfplain mode lowres mag 1 2 input cmr10 The result is a set of PostScript files one for each character in the font Some editing would be required in order to merge them into a downloadable Type 3 PostScript font 1 Another limitation of the mfplain package is that certain internal variables from Plain META FONT cannot be given reasonable MetaPost definitions These include displaying c
53. bles of the appropriate types Within the replacement text they can be used in expressions just like variables but they cannot be redeclared or assigned to There is no restriction against unknown or partially known arguments Thus the definition def midpoint expr a b 5 a b enddef works perfectly well when a and b are unknown An equation such as midpoint zi z2 1 1 could be used to help determine z1 and z2 Notice that the above definition for midpoint works for numerics pairs or colors as long as both parameters have the same type If for some reason we want a middlepoint macro that works for a single path or picture it would be necessary to do an if test on the argument type This uses the fact there is a unary operator path primary that returns a boolean result indicating whether its argument is a path Since the basic if test has the syntax if boolean expression balanced tokens else balanced tokens fi where the balanced tokens can be anything that is balanced with respect to if and fi the complete middlepoint macro with type test looks like this def middlepoint expr a if path a point 5 length a of a else 5 llcorner a urcorner a fi enddef The complete syntax for if tests is shown in Figure 41 It allows multiple if tests like if e else if eg else fi fi 9 MACROS 48 to be shortened to if ej elseif eg else fi where e and es represent boolean expres
54. ch path This refers to the parameterization scheme from Section 3 that described paths as piecewise cubic curves X t Y t where t ranges from zero to the number of curve segments In other words when a path is specified as passing through a sequence of points where t 0 at the first point then t 1 at the next and t 2 at the next etc The result of a intersectiontimes b is 1 1 if there is no intersection otherwise you get a pair ta tb where ta is a time on path a when it intersects path b and ty is the corresponding time on path b For example suppose path a is denoted by the thin line in Figure 25 and path b is denoted by the thicker line If the labels indicate time values on the paths the pair of time values computed by a intersectiontimes b 8 ADVANCED GRAPHICS 30 beginfig 24 h 2in w 2 7in path p qll pp for i 2 upto 4 ii i 2 pli w ii h i ii l w i h i w h ii ii 1 endfor q0 5 0 0 w 0 5h qi 5 0 0 w 1 5 h pp buildcycle q0 5 p2 qi 5 p4 fill pp withcolor 7white zO center pp picture lab lab thelabel btex f gt 0 etex zO unfill bbox lab draw lab draw q0 5 draw p2 draw q1 5 draw p4 dotlabel top btex P etex p2 intersectionpoint q0 5 dotlabel rt btex Q etex p2 intersectionpoint q1 5 dotlabel lft btex R etex p4 intersectionpoint q1 5 dotlabel bot btex 8 etex p4 intersectionpoint q0 5 endfig Figure 24 MetaPost c
55. ckup pencircle scaled 1pt draw fun endfig X3 T2 X1 Figure 26 MetaPost code and the resulting figure 8 ADVANCED GRAPHICS 34 Including scaled and yscaled there are seven transformation operators that take a numeric or pair argument x y shifted a b x a y 0 x y rotated9 xcos0 ysin0O zsin0 y cos 0 x y slanteda x ay y x y scaleda az ay x y xscaleda az y x y yscaleda 2 ay x y zscaled a b ax by bx ay Most of these operations are self explanatory except for zscaled which can be thought of as multi plication of complex numbers The effect of zscaled a b is to rotate and scale so as to map 1 0 into a b The effect of rotated 0 is rotate 0 degrees counter clockwise Any combination of shifting rotating slanting etc is an affine transformation the net effect of which is to transform any pair x y into for some sextuple t ty 55 toy 145 tyy This information can be stored in a variable of type transform so that transformed T might be equivalent to xscaled 1 rotated 90 shifted 1 1 if T is an appropriate transform variable The transform T could then be initialized with an expression of type transform as follows transform T T identity xscaled 1 rotated 90 shifted 1 1 As this example indicates transform expressions can be built up by applying transformation operat ors to other transforms The predefined transformation identity
56. curl1 z3 z4 curl 1 cycle fill p2 withcolor 4 white black unfill pl draw pl 2 transform T zi transformed T 22 z3 transformed T 24 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 8 4 Dashed Lines The MetaPost language provides many ways of changing the appearance of a line besides just changing its width One way is to use dashed lines as was done in Figures 5 and 23 The syntax for this is draw path expression dashed dash pattern where a dash pattern is really a special type of picture expression There is a predefined dash pattern called evenly that makes dashes 3 PostScript points long separated by gaps of the same size Another predefined dash pattern withdots produces dotted lines with dots 5 PostScript points apart For dots further apart or longer dashes further apart the dash pattern can be scaled as shown in Figure 29 dashed withdots scaled 2 pat gas dashed withdots dashed evenly scaled 4 dashed evenly scaled 2 dashed evenly Figure 29 Dashed lines each labeled with the dash pattern used to create it Another way to change a dash pattern is to alter its phase by shifting it horizontally Shifting to the right makes the dashes move forward along the path and
57. d If prologues is set to 1 MetaPost attempts to read a file called psfonts map regardless of any fontmapfile statement Again this is for backward compatibility only 7 3 The infont operator Regardless of whether you use TEX or troff all the real work of adding text to pictures is done by a MetaPost primitive operator called infont It is a primary binop that takes a string secondary as its left argument and a string primary as its right argument The left argument is text and the right argument is a font name The result of the operation is a picture secondary that can then be transformed in various ways One possibility is enlargement by a given factor via the syntax picture secondary scaled numeric primary Thus label text z0 is equivalent to label text infont defaultfont scaled defaultscale z0 If it is not convenient to use a string constant for the left argument of infont you can use char numeric primary to select a character based on its numeric position in the font Thus char n 64 infont ptmr8r is a picture containing character n 64 of the font ptmr8r which is a typical TEX way to refer to Times Roman See p 21 for further discussion Bare MetaPost does not do any kind of input reencoding so when you use infont string for labels instead of btex etex the string has to be specified in the font encoding 7 4 Measuring Text MetaPost makes readily available the physical dimensions of pictures gen
58. dashed miterlimit withcolor defaultcolormodel mpprocset withgreyscale etex mpxbreak withoutcolor filenametemplate prologues withpostscript fontmapfile redpart withprescript fontmapline restoreclipcolor withrgbcolor fontsize rgbcolor yellowpart Variables and Macros defined only in Plain MetaPost ahangle cutbefore extra beginfig ahlength cuttings extra endfig background dashpattern green bbox defaultfont image bboxmargin defaultpen label beginfig defaultscale labeloffset beveled dotlabel mitered black dotlabels red blue drawarrow rounded buildcycle drawdblarrow squared butt drawoptions thelabel center endfig white cutafter evenly 87 Index HO 53 amp 15 2 2 15 15 15 SA 8 54 10 19 lt 14 lt 14 lt gt 14 10 gt l4 gt 14 53 Qit 53 19 53 abs 17 addto also 43 addto contour 43 addto doublepath 43 ahangle 40 ahlength 40 and 14 15 angle 17 arc length 32 48 arclength 32 48 arctime 48 arctime of 32 arithmetic 13 17 56 arrays 18 multidimensional 19 arrows 40 double headed 40 ASCII 72 assignment 10 19 57 background 28 41 balanced tokens 47 83 bbox 25 27 bboxmargin 25 beginfig 3 19 41 42 45 46 86 begingroup 45 53 beveled 38 black 13 blackpart 17 blue 13 88 bluepart 17 boolean 17 boolean type 14 bot 20 42 box name 58 boxes mp 57 68 86 boxit 58 boxj
59. default the MetaPost output files do not have embedded fonts Fonts in the resulting output will probably render as Courier or Times Roman e When prologues is 1 the MetaPost output claims to be structured PostScript EPSF but it is not completely conformant This variant is kept for backward compatibility with old troff documents but its use is deprecated For historical reasons MetaPost sets prologues to 1 when the troff option is given on the command line e 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 e When prologues is 3 the MetaPost output wil 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 8Unix is a registered trademark of Unix Systems Laboratories 7 INTEGRATING TEXT AND GRAPHICS 24 It is worth noting that the default value prologues 0 is sufficient for graphics included in TEX based documents Also the prologues variable is irrelevant when processing MetaPost files through the mptopdf utility part of the Con TEXt distribution because PDF files are by nature stand alone The details on how to include PostScrip
60. dered too wild a draw statement of the following form increases the tension between z1 and z2 draw z0 z1 tension 1 3 z2 z3 This produces Figure 10b For an asymmetrical effect like Figure 10c the draw statement becomes draw z0 z1 tension 1 6 and 1 z2 z3 The tension parameter can be less than one but it must be at least 3 Figure 10 Results of draw z0 z1 tension a and 3 z2 z3 for various a and 8 a a 8 1 b a 821 3 c a 1 5 B 1 MetaPost paths also have a parameter called curl that affects the ends of a path In the absence of any direction specifications the first and last segments of a non cyclic path are approximately circular arcs as in the c 1 case of Figure 11 To use a different value for the curl parameter specify curl c for some other value of c Thus draw zO curl c z1 fcurl c z2 sets the curl parameter for z0 and z2 Small values of the curl parameter reduce the curvature at the indicated path endpoints while large values increase the curvature as shown in Figure 11 In particular a curl value of zero makes the curvature approach zero 3 3 Summary of Path Syntax There are a few other features of MetaPost path syntax but they are relatively unimportant Since METRFONT uses the same path syntax interested readers can refer to 4 chapter 14 The summary of path syntax in Figure 12 includes everything discussed so far including the and construc tions which 4 sh
61. diation expressions or multiplied or divided by numerics Paths have already been discussed in the context of draw statements but that discussion did not mention that paths are first class objects that can be stored and manipulated A path represents a straight or curved line that is defined parametrically Another data type represents an arbitrary affine transformation A transform can be any com bination of rotating scaling slanting and shifting If p pz py is a pair and T is a transform p transformed T is a pair of the form tz trzPr tryPy ty Luna F tyyPy where the six numeric quantities tz ty tax tay tyz tyy determine T Transforms can also be applied to paths pictures pens and transforms The color type is like the pair type except that it has three components instead of two and each component is normally between 0 and 1 Like pairs colors can be added subtracted used in mediation expressions or multiplied or divided by numerics Colors can be specified in terms of the predefined constants black white red green blue or the red green and blue components can be given explicitly Black is 0 0 0 and white is 1 1 1 A level of gray such as 4 4 4 5 EXPRESSIONS 14 can also be specified as 0 4white Although color typed variables may be any ordered triplet when adding an object to a picture MetaPost will convert its color by clipping each component between 0 and 1 For example MetaPost wil
62. dotprod pair pair numeric 15 vector dot product floor numeric numeric 17 Greatest integer less than or equal to fontsize string numeric 21 The point size of a font greenpart color numeric 17 Extract the second component greypart m numeric numeric Extract the first only component hex string numeric Interpret as a hexadecimal number infont string string picture 25 Typeset string in given font Tintersec path path pair 29 An intersection point tionpoint intersec path path pair 29 Times t tr on paths and r tiontimes when the paths intersect Tinverse transform transform 34 Invert a transformation known any boolean 17 Does argument have a known value length path numeric 31 Number of arcs in a path ftlft numeric numeric 42 Left side of current pen when its pair pair center is at the given coordinate s llcorner picture pair 25 Lower left corner of bounding box path pen lrcorner picture pair 25 Lower left corner of bounding box path pen magentapart cmykcolor numeric 17 Extract the second component makepath E pen path 43 Cyclic path bounding the pen shape makepen x path pen 43 A polygonal pen made from the convex hull of the path knots mexp E numeric numeric The function exp z 256 mlog E numeric numeric The function 256 In z 1mod numeric numeric The remainder function l r 1 r normal numeric Choose a random number with deviate
63. e 23b shows how buildcycle forms a closed cycle from the pieces of paths aa and b The buildcycle macro detects the two intersections labeled 1 and 2 in Figure 23b Then it constructs the cyclic path shown in bold in the figure by going forward along path aa from intersection 1 to intersection 2 and then forward around the counter clockwise path b back to intersection 1 It turns out that buildcycle a b would have produced the same result but the reasoning behind this is a little confusing It is a easier to use the buildcycle macro in situations like Figure 24 where there are more than two path arguments and each pair of consecutive paths has a unique intersection For instance the line q0 5 and the curve p2 intersect only at point P and the curve p2 and the line q1 5 intersect only at point Q In fact each of the points P Q R S is a unique intersection and the result of buildcycle q0 5 p2 q1 5 p4 8 ADVANCED GRAPHICS 29 aa aa Figure 23 a The semicircular path aa with a dashed line marking path b b paths aa and b with the portions selected by buildcycle shown by heavy lines takes q0 5 from S to P then p2 from P to Q then q1 5 from Q to R and finally p4 from R back to S An examination of the MetaPost code for Figure 24 reveals that you have to go backwards along p2 in order to get from P to Q This works perfectly well as long as the intersection points are uniquely defined but it can cause unexpected results when pairs of p
64. e a lot like subroutines MetaPost macros are often used like subroutines so the language includes programming concepts to support this These concepts include local variables loops and conditional statements 9 1 Grouping Grouping in MetaPost is essential for functions and local variables The basic idea is that a group is a sequence of statements possibly followed by an expression with the provision that certain symbolic tokens can have their old meanings restored at the end of the group If the group ends with an expression the group behaves like a function call that returns that expression Otherwise the group is just a compound statement The syntax for a group is begingroup statement list endgroup or begingroup statement list expression endgroup where a statement list is a sequence of statements each followed by a semicolon A group with an expression after the statement list behaves like a primary in Figure 14 or like a numeric atom in Figure 15 Since the replacement text for the beginfig macro starts with begingroup and the replace ment text for endfig ends with endgroup each figure in a MetaPost input file behaves like a group This is what allows figures can have local variables We have already seen in Section 6 2 that variable names beginning with x or y are local in the sense that they have unknown values at 9 MACROS 46 the beginning of each figure and these values are forgotten at the end of each fi
65. e are also predefined direction vectors left and down for dir 180 and dir 270 The direction vectors given in can be of any length and they can come before a point as well as after one It is even possible for a path specification to have directions given before and after a point For example a path specification containing dir 60 10 0 up produces a curve with a corner at 10 0 Note that some of the curves in Figure 7 have points of inflection This is necessary in order to produce smooth curves in situations like Figure 4a but it is probably not desirable when dealing 3 CURVES 8 with vertical and horizontal extreme points as in Figure 9a If z1 is supposed to be the topmost point on the curve this can be achieved by using instead of in the path specification as shown in Figure 9b The meaning of is choose an inflection free path between these points unless the endpoint directions make this impossible It would be possible to avoid inflections in Figure 7 but not in Figure 8 0 2 0 2 draw zO up zi right z2 down draw zO up zi right z2 down re Figure 9 Two draw statements and the resulting curves Another way to control a misbehaving path is to increase the tension parameter Using in a path specification sets the tension parameter to the default value 1 If this makes some part of a path a little too wild we can selectively increase the tension If Figure 10a is consi
66. e interpreter to proceed as best it can prints a listing of the options available followed by another prompt Error messages and responses to show commands are also written into the transcript file whose name is obtained from the name of the main input file by changing mp to 1og When the internal variable tracingonline is at its default value of zero some show commands print their results in full detail only in the transcript file Only one type of show command has been discussed so far show followed by a comma separated list of expressions prints symbolic representations of the expressions The showtoken command can be used to show the parameters and replacement text of a macro It takes a comma separated list of tokens and identifies each one If the token is a primitive as in showtoken it is just identified as being itself gt Applying showtoken to a variable or a vardef macro yields gt token variable To get more information about a variable use showvariable instead of showtoken The argu ment to showvariable is a comma separated list of symbolic tokens and the result is a description of all the variables whose names begin with one of the listed tokens This even works for vardef macros For example showvariable z yields zOH macro gt begingroup x SUFFIX2 y SUFFIX2 endgroup There is also a showdependencies command that takes no arguments and prints a list of all dependent variables and h
67. e the error message talks about an undefined x coordinate this value is printed on the first line after the gt gt n this case the x 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 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 13 DEBUGGING 66 gt gt x1 Undefined x coordinate has been replaced by 0 lt to be read again gt 1 gt curli curli 1 17 draw z1 z2 Figure 53 An example of an error message The descriptor identifies the input source It is either a line number like 1 17 for line 17 of the current file or it can be a macro name followed by gt or it is a descriptive phrase in angle brackets Thus the meaning of the context listing in Figure 53 is that the interpreter has just read line 17 of the input file up to the expansion of the macro has just started and the initial has been reinserted to allow for user input before scanning this token Among the possible responses to a prompt are the following x terminates the run so that you can fix your input file and start over h prints a help message followed by another prompt return causes th
68. ed at the position given by the argument where will its left right top or bottom edge be In this case the current pen is the ellipse given in the pickup statement and its bounding box is 0 1734 inches wide and 0 1010 inches high so rt x3 is x3 0 0867in and bot y5 is ys 0 0505in The 1ft rt top and bot operators also accept arguments of type pair in which case they compute the z and y coordinates of the leftmost rightmost topmost or bottommost point on the pen shape For example rt x y x y 0 0867in 0 0496in for the pen in Figure 38 Note that beginfig resets the current pen to a default value of pencircle scaled 0 5bp 8 ADVANCED GRAPHICS 43 at the beginning of each figure This value can be reselected at any time by giving the command pickup defaultpen This would be the end of the story on pens except that for compatibility with METRFONT 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 pensquare and makepen should not be used with dash patterns See the e
69. ee bb ee c tension1 3 diriid bb c label urt btex b etex cuta ee cc ee c cc c ee c rotated 15 cc c endfig Figure 52 MetaPost code and the corresponding figure 12 UTILITY ROUTINES 64 12 Utility Routines This section describes some of the utility routines included in the mplib directory of the development source hierarchy Future versions of this documentation may include more meanwhile please read the source files most have explanatory comments at the top They are also included in the MetaPost and larger TEX distributions typically in a texmf metapost base directory 12 1 TEX mp TEX mp provides a way to typeset the text of a MetaPost string expression Suppose for example you need labels of the form no n N19 across the x axis You can do this relatively conveniently with TEX mp as follows input TEX beginfig 100 last 10 for i 0 upto last label TEX n amp decimal i 5mmx i 0 endfor endfig In contrast the basic btex command see p 21 typesets verbatim text That is btex s etex typesets the literal character s TEX s typesets the value of the MetaPost text variable s In version 0 9 TEX mp acquired two additional routines to facilitate using IATEX to typeset labels TEXPRE and TEXPOST Their values are remembered and included before and after respectively each call to TEX Otherwise each TEX call is effectively typeset independently TEX calls also do
70. elate the time on a path to the more familiar concept of arc length The expression arclength path primary gives the arc length of a path If p is a path and a is a number between 0 and arclength p arctime a of p gives the time t such that arclength subpath 0 t of p a 8 3 Affine Transformations Note how path fun in Figure 26 is first constructed as 0 1 1 05 right 1 9 02 right curl 1 3 2 2 and then the yscaled and scaled operators are used to adjust the shape and size of the path As the name suggests an expression involving yscaled 10 multiplies y coordinates by ten so that every point x y on the original path corresponds to a point x 10y on the transformed path 8The arclength and arctime operators are only found in MetaPost version 0 50 and higher 8 ADVANCED GRAPHICS 33 beginfig 26 numeric scf t 3 2scf 2 4in path fun tt 1 Keep the function single valued fun 0 1 1 5 right 1 9 2 right curl 1 3 2 2 yscaled 1 scaled scf x1 2 5scf for i 1 upto 2 t i whatever fun intersectiontimes x i infinity x i infinity z i point t i of fun zlil x i 1 0 whatever direction t i of fun draw x i 0 z i x i 1 0 fill fullcircle scaled 3bp shifted z i endfor label bot btex x 1 etex x1 0 label bot btex x 2 etex x2 0 label bot btex x 3 etex x3 0 draw 0 0 3 2scf 0 pi
71. eneric variable delimited part undelimited part vardef generic variable delimited part undelimited part binary def parameter symbolic token parameter delimited part empty delimited part parameter type parameter tokens parameter type expr suffix text parameter tokens parameter parameter tokens parameter parameter symbolic token undelimited part empty parameter type parameter precedence level parameter expr parameter of parameter precedence level primary secondary tertiary binary def primarydef secondarydef tertiarydef pseudo procedure drawoptions option list label label suffix expression pair expression dotlabel label suffix expression pair expression labels label suffix point number list dotlabels label suffix point number list point number list suffix point number list suffix label suffix empty 1ft rt top bot ulft urt 11ft 1rt Figure 59 Overall syntax for MetaPost programs A REFERENCE MANUAL 82 command clip picture variable to path expression show interim internal variable right hand side let symbolic token symbolic token newinternal symbolic token list pickup expression randomseed numeric expression save symbolic token list setbounds picture variable to path expression shipout picture expressio
72. erated by the infont operator There are unary operators llcorner lrcorner urcorner ulcorner and center that take a picture primary and return the corners of its bounding box as illustrated in Figure 20 The center operator also accepts path primary and pen primary operands In MetaPost Version 0 30 and higher 1lcorner lrcorner etc accept all three argument types as well The argument type restrictions on the corner operators are not very important because their main purpose is to allow label and dotlabel statements to center their text properly The predefined macro bbox picture primary finds a rectangular path that represents the bounding box of a given picture If p is a picture bbox p equivalent to 11corner p lrcorner p urcorner p ulcorner p cycle except that it allows for a small amount of extra space around p as specified by the internal variable bboxmargin 8 ADVANCED GRAPHICS 26 testing Figure 20 A bounding box and its corner points ulcorner urcorner llcorner lrcorner Note that MetaPost computes the bounding box of a btex etex picture just the way TEX does This is quite natural but it has certain implications in view of the fact that TEX has features like Nstrut and rlap that allow TEX users to lie about the dimensions of a box When TEX commands that lie about the dimensions of a box are translated in to low level MetaPost code a setbounds statement does the lying setbounds
73. ernal variable pair expression expression pair primary primary path expression expression path subexpression subexpression pen expression expression picture expression expression picture variable variable rgbcolor expression expression string expression expression suffix parameter parameter transform primary primary Figure 58 Miscellaneous productions needed to complete the BNF A REFERENCE MANUAL 81 program statement list end statement list empty statement list statement statement empty equation assignment declaration macro definition compound pseudo procedure command compound begingroup statement list endgroup beginfig numeric expression statement list endfig equation expression right hand side assignment variable right hand side internal variable right hand side right hand side expression equation assignment declaration type declaration list declaration list generic variable declaration list generic variable generic variable symbolic token generic suffix generic suffix empty generic suffix tag generic suffix macro definition macro heading replacement text enddef macro heading def symbolic token delimited part undelimited part vardef g
74. es so path path that 1 0 is mapped into the pair pair given pair i e do complex pen pen multiplication transform transform A REFERENCE MANUAL Table 11 Commands Name Page Explanation addto 43 Low level command for drawing and filling clip 44 Applies a clipping path to a picture Tcutdraw 56 Draw with butt end caps draw 4 Draw a line or a picture Tdrawarrow 40 Draw a line with an arrowhead at the end Tdrawdblarrow 40 Draw a line with arrowheads at both ends Tfill 26 Fill inside a cyclic path Tfilldraw 40 Draw a cyclic path and fill inside it interim 47 Make a local change to an internal variable let Assign one symbolic token the meaning of another Tloggingall 67 Turn on all tracing log file only newinternal 19 Declare new internal variables pickup 14 Specify new pen for line drawing save 46 Make variables local setbounds 26 Make a picture lie about its bounding box shipout 44 Low level command to output a figure show 13 print out expressions symbolically showdependencies 66 print out all unsolved equations showtoken 66 print an explanation of what a token is showvariable 66 print variables symbolically special 86 print a string directly in the PostScript output file Ttracingall 67 Turn on all tracing Ttracingnone 67 Turn off all tracing Tundraw 4 Erase a line or a picture Tun
75. ets 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 4 LINEAR EQUATIONS 12 4 2 Dealing with Unknowns A system of equations such as those used in Figure 13 can be given in any order as long as all the equations are linear and all the variables can be determined before they are needed This means that the equations zi z2 2in 0 x3 x6 3in x3 y3 x6 y6 1 1in z4 1 3 z3 z6 z5 2 3 z3 z6 suffice to determine z1 through z6 no matter what order the equations are given in On the other hand z20 whatever z1 z3 is legal only when a known value has previously been specified for the difference z3 z1 because the equation is equivalent to z20 zi whatever z3 z1 and the linearity requirement disallows multiplying unknown components of z3 z1 by the an onymous unknown result of whatever The general rule is that you cannot multiply two unknown quantities or divide by an unknown quantity nor can an unknown quantity be used in a draw statement Since only linear equations are allowed the MetaPost interpreter can easily solve the equations and keep track of what values are known The most natural way to ensure that MetaPost can handle an expression like whatever z1 z3 is to ensure that z1 and z3 are both known However this is not actually required since MetaPost may be able to deduce a known value for z3 z1 before
76. etween primitives and plain macros can be ignored by the casual user but it is important to remember that features marked by a can only be used after reading in the boxes mp macro file 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 METRFONT and are intended to be self explanatory Certain other features from METRFONT 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 4 as explained in Appendix B Table 4 lists internal variables that take on numeric values Table 5 lists predefined variables of other types Table 6 lists predefined constants Some of these are implemented as variables whose values are intended to be left unchanged Tables 7 10 summarize MetaPost operators and list 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 these tables because they are treated as function like macros The last two tables are Table 11 for commands and Table 12 macros that behave like functions or procedures Such macros take parenthesized argument list
77. everse 40 rgbcolor 17 right 7 Xrlap 26 rotated 21 34 rotated text 21 rotatedaround 34 45 round 17 54 rounded 38 roundoff error 12 rt 20 42 save 46 scaled 3 25 32 34 36 scantokens 14 secondary 14 54 78 secondary binop 15 29 55 78 79 secondarydef 55 self 63 semicolon 56 setbounds 26 91 shifted 34 shipout 44 show 46 show 10 13 46 65 66 showdependencies 66 showstopping 69 showtoken 66 showvariable 66 sind 17 size 25 slanted 34 special 86 sqrt 16 squared 38 step 56 str 53 57 string 17 string constants 14 18 string expressions as labels 64 string type 14 strut 26 subpath 31 subroutines 45 subscript generic 19 53 subscript 19 51 79 substring of 15 suffix 17 19 51 53 78 79 81 83 suffix 48 55 tags 18 53 54 tension 8 tertiary 14 54 78 tertiary binop 15 31 32 55 78 79 tertiarydef 55 TEX 1 4 21 26 86 errors 23 TEX fonts 21 TEX mp 64 text 48 55 text and graphics 19 tfm file 21 84 thelabel 20 28 time 69 Times Roman 23 tokens 17 symbolic 17 18 45 46 top 20 42 tracingall 67 tracingcapsules 67 tracingchoices 67 tracingcommands 67 INDEX tracingequations 67 tracinglostchars 67 tracingmacros 67 tracingnone 67 tracingonline 13 66 tracingoutput 67 tracingrestores 67 tracingspecs 67 tracingstats 67 tracingtitles 69 transcrip
78. expression loop text endfor It is equally simple to construct a loop that counts downward just replace upto by downto make the second expression smaller than the first This section covers more complicated types of pro gressions loops where the loop counter behaves like a suffix parameter and ways of exiting from a loop The first generalization is suggested by the fact that upto is a predefined macro for step 1 until and downto is a macro for step 1 until A loop begining for i a step b until c scans a sequence of i values a a b a 2b stopping before i passes c i e the loop scans i values where i lt cifb gt 0and i gt cif i lt 0 It is best to use this feature only when the step size is an integer or some number that can be represented exactly in fixed point arithmetic as a multiple of GRE Otherwise error will accumulate and the loop index might not reach the expected termination value For instance for i 0 step 1 until 1 show i endfor shows ten i values the last of which is 0 90005 The standard way of avoid the problems associated with non integer step sizes is to iterate over integer values and then multiply by a scale factor when using the loop index as was done in Figures 2 and 40 Alternatively the values to iterate over can be given explicitly Any sequence of zero or more expressions separated by commas can be used in place of a step b upto c In fact the expressions need not all be the same type a
79. fill 27 Erase inside a cyclic path junfilldraw 41 Erase a cyclic path and its inside 76 A REFERENCE MANUAL 77 Table 12 Function Like Macros Name Arguments Result Page Explanation boxit suffix picture 58 Define a box containing the picture xboxit suffix string 61 Define a box containing text boxit suffix empty 61 Define an empty box boxjoin equations i 59 Give equations for connecting boxes bpath suffix path 58 A box s bounding circle or rectangle jbuildcycle list of paths path 28 Build a cyclic path circleit suffix picture 61 Put picture in a circular box circleit suffix picture E 61 Put a string in a circular box circleit suffix empty m 61 Define an empty circular box dashpattern on off distances picture 37 Create a pattern for dashed lines decr numeric variable numeric 55 Decrement and return new value Tdotlabel suffix picture pair x 20 Mark point and draw picture nearby Tdotlabel suffix string pair 20 Mark point and place text nearby Tdotlabels suffix point numbers 20 Mark z points with their numbers drawboxed list of suffixes i 58 Draw the named boxes and their contents drawboxes list of suffixes 61 Draw the named boxes Tdrawdot pair 2 Draw a dot at the given point jdrawoptions drawing option
80. given with dotlabels is used to position all the labels 7 INTEGRATING TEXT AND GRAPHICS 21 There is also a labels statement that is analogous to dotlabels but its use is discouraged because it presents compatibility problems with METRFONT Some versions of the preloaded Plain macro package define labels to be synonymous with dotlabels For labeling statements such as label and dotlabel that use a string expression for the label text the string gets typeset in a default font as determined by the string variable defaultfont The initial value of defaultfont is likely to be cmr10 but it can be changed to a different font name by giving an assignment such as defaultfont ptmr8r ptmr8r is a typical way to refer to the Times Roman font in TEX The discussion of font names on p 21 explains further There is also a numeric quantity called defaultscale that determines the type size When defaultscale is 1 you get the normal size which is usually 10 point but this can also be changed For instance defaultscale 1 2 makes labels come out twenty percent larger If you do not know the normal size and you want to be sure the text comes out at some specific size say 12 points you can use the fontsize operator to determine the normal size e g defaultscale 12pt fontsize defaultfont When you change defaultfont the new font name should be something that TEX would under stand since MetaPost gets height and width information by re
81. gure The following example illustrates how locality works x23 3 1 beginfig 17 y3a 1 x23 2 endfig show x23 y3a The result of the show command is gt gt 3 1 gt gt y3a indicating that x23 has returned to its former value of 3 1 and y3a is completely unknown as it was at beginfig 17 The locality of x and y variables is achieved by the statement save X y in the replacement text for beginfig In general variables are made local by the statement save symbolic token list where symbolic token list is a comma separated list of tokens symbolic token list symbolic token symbolic token symbolic token list All variables whose names begin with one of the specified symbolic tokens become unknown numerics and their present values are saved for restoration at the end of the current group If the save statement is used outside of a group the original values are simply discarded The main purpose of the save statement is to allow macros to use variables without interfering with existing variables or variables in other calls to the same macro For example the predefined macro whatever has the replacement text begingroup save endgroup This returns an unknown numeric quantity but it is no longer called question mark since that name was local to the group Asking the name via show whatever yields gt gt 4CAPSULEnnnn where nnnn is an identification number that is chosen when save makes t
82. he name question mark disappear In spite of the versatility of save it cannot be used to make local changes to any of MetaPost s internal variables A statement such as save linecap 9 MACROS AT would cause MetaPost to temporarily forget the special meaning of this variable and just make it an unknown numeric If you want to draw one dashed line with linecap butt and then go back to the previous value you can use the interim statement as follows begingroup interim linecap butt draw path expression dashed evenly endgroup This saves the value of the internal variable linecap and temporarily gives it a new value without forgetting that linecap is an internal variable The general syntax is interim internal variable numeric expression 9 2 Parameterized Macros The basic idea behind parameterized macros is to achieve greater flexibility by allowing auxiliary information to be passed to a macro We have already seen that macro definitions can have formal parameters that represent expressions to be given when the macro is called For instance a definition such as def rotatedaround expr z d replacement text enddef allows the MetaPost interpreter to understand macro calls of the form rotatedaround expression expression The keyword expr in the macro definition means that the parameters can be expressions of any type When the definition specifies expr z d the formal parameters z and d behave like varia
83. he paths involved are intersecting circles a and b and a path ab that bounds the region inside both circles Circles a and b are derived from a predefined path fullcircle that approximates a circle of unit diameter centered on the origin There is also a predefined path halfcircle that is the part of fullcircle above the x axis Path ab is then initialized using a predefined macro buildcycle that will be discussed shortly Filling circle a with the light gray color 7white and then doing the same with circle b doubly fills the region where the disks overlap The rule is that each fill statement assigns the given color to all points in the region covered wiping out whatever was there previously including lines and text as well as filled regions Thus it is important to give fill commands in the right order In the above example the overlap region gets the same color twice leaving it light gray after the first two fill statements The third fill statement assigns the darker color 4white to the overlap region At this point the circles and the overlap region have their final colors but there are no cutouts for the labels The cutouts are achieved by the unfill statements that effectively erase the re gions bounded by bbox pa and bbox pb More precisely unfill is shorthand for filling withcolor 8 ADVANCED GRAPHICS 28 beginfig 22 path a b aa ab a fullcircle scaled 2cm b a shifted 0 1cm aa halfcircle scaled 2cm ab buildcycle aa
84. he position of each box By using fixsize to fix the dimensions of each box before assigning default positions to any of them the number of needing default positions can usually be cut to at most one Since the bounding path for a box cannot be computed until the size shape and position of the box is determined the bpath macro applies fixsize and fixpos to its argument Other macros that do this include pic box name where the box name is a suffix possibly in parentheses This returns the contents of the named box as a picture positioned so that draw pic box name draws the box contents without the bounding rectangle This operation can also be accomplished by the drawunboxed macro that takes a comma separated list of box names There is also a drawboxes macro that draws just the bounding rectangles Another way to draw empty rectangles is by just saying boxit box name O with no picture argument as is done several times in Figure 49 This is like calling 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 11 2 Circular and Oval Boxes Circular and oval boxes are a lot like rectangular boxes except for the shape of the bounding path Such boxes are set up by the circleit macro circleit box name box contents where box name is a suffix and box contents is either a picture expression a string expression o
85. ill be discussed in Section 9 1 Type declarations make it possible to use almost any naming scheme while still wiping out any previous value that might cause interference For example the declaration pair pp a b makes pp and a b unknown pairs Such a declaration is not strictly local since pp and a b are not automatically restored to their previous values at the end of the current figure Of course they are restored to unknown pairs if the declaration is repeated Declarations work the same way for any of the other eight types numeric path transform color string boolean picture and pen The only restriction is that you cannot give explicit numeric subscripts in a variable declaration Do not give the illegal declaration numeric qi q2 q3 use the generic subscript symbol instead to declare the whole array numeric q You can also declare multidimensional arrays After the declaration path pl q pal1 1 p2q3 and pq1 4 5 are both paths Internal variables like tracingonline cannot be declared in the normal fashion All the internal variables discussed in this manual are predefined and do not have to be declared at all but there is a way to declare that a variable should behave like a newly created internal variable The declaration is nevinternal followed by a list of symbolic tokens For example newinternal a b c causes a b and c to behave like internal variables Such variables always have known numeric
86. ing it with a separate command such as drawboxed suffix list The argument to drawboxed should be a comma separated list of box names where a box name is a suffix with which boxit has been called For the command boxit bb pic the box name is bb and the contents of the box is the picture pic In this case bb c the position where the center of picture pic is to be placed and bb sw bb se bb ne and bb nw are the corners of a rectangular path that will surround the resulting picture Variables bb dx and bb dy give the spacing between the shifted version of pic and the surrounding rectangle and bb off is the amount by which pic has to be shifted to achieve all this When the boxit macro is called with box name b it gives linear equations that force b sw b se b ne and b nw to be the corners of a rectangle aligned on the x and y axes with the box contents centered inside as indicated by the gray rectangle in Figure 48 The values of b dx b dy and b c are left unspecified so that the user can give equations for positioning the boxes If no such equations are given macros such as drawboxed can detect this and give default values The default values for dx and dy variables are controlled by the internal variables defaultdx and defaultdy If b represents a box name drawboxed b draws the rectangular boundary of box b and then the contents of the box This bounding rectangle can be accessed separately as bpath b or in general bpath box
87. invoked on the next line when box a is followed by box ni This yields a se ni sw a ne ni nw The next pair of boxes is box ni and box di This time the implicitly generated equations are ni se di sw ni ne di nw This process continues until a new boxjoin is given In this case the new declaration is boxjoin a sw b nw a se b ne which causes boxes to be stacked below each other After calling boxit for the first eight boxes a through dk the box heights are constrained to match but the widths are still unknown Thus the drawboxed macro needs to assign default values to the box name dx and box name dy variables First di dx and di dy get default values so that all the boxes are forced to be large enough to contain the contents of box di The macro that actually assigns default values to dx and dy variables is called fixsize It takes a list of box names and considers them one at a time making sure that each box has a fixed size and shape A macro called fixpos then takes this same list of box names and assigns default values 11 MAKING BOXES 60 input boxes beginfig 49 boxjoin a se b sw a ne b nw boxit a btex strut cdots etex boxit ni btexMstrut n i etex boxit di btexMstrut d i etex boxit nil btex strut n_ it 1 etex boxit dil btex strut d_ it 1 etex boxit aa btex strut cdots etex boxit nk btex strut n_k etex boxit dk btex strut d_k etex drawboxed di a ni nii dii aa nk dk label lft ndtable a
88. ion numeric expression of operator expression of primary unary op primary str suffix z suffix numeric atom expression expression scalar multiplication op primary secondary primary secondary primary binop primary secondary transformer tertiary secondary tertiary secondary binop secondary subexpression tertiary path expression path join path knot expression subexpression expression tertiary binop tertiary path subexpression direction specifier path subexpression path join cycle path knot tertiary path join gt direction specifier basic path join direction specifier direction specifier empty curl numeric expression pair expression numeric expression numeric expression basic path join gt tension controls tension gt tension numeric primary tension numeric primary and numeric primary controls controls pair primary controls pair primary and pair primary argument symbolic token number or fraction number number number not followed by number scalar multiplication op number or fraction not followed by add op number Figure 55 Part 1 of the syntax for expressions A REFERENCE MANUAL 79 transformer rotated numeric primary scaled numeric primary
89. ir pair pen pen transform transform jround numeric numeric 17 round each component to the pair pair nearest integer frt numeric numeric 42 Right side of current pen when pair pair centered at given coordinate s scaled picture numeric picture 34 Scale all coordinates by the path path given amount pair pair pen pen transform transform scantokens string token sequence 14 Converts a string to a token or token sequence Provides string to numeric conversion etc shifted picture pair picture 34 Add the given shift amount to path path each pair of coordinates pair pair pen pen transform transform sind numeric numeric 17 Sine of an angle in degrees slanted picture numeric picture 34 Apply the slanting transformation path path that maps a y into x sy y pair pair where s is the numeric argument pen pen transform transform sqrt numeric numeric 16 Square root str suffix string 53 String representation for a suffix A REFERENCE MANUAL 75 Table 10 Operators Part 4 Name Argument result types Page Explanation Left Right Result string any boolean 17 Is the expression of type string subpath pair path path 31 Portion of a path for given range of of time values substring pair string string 15 Substring bounded by given indices of Ttop numeric numeric 42 Top of cur
90. is should make it clear why the parameter to dotlabels has to be a comma separated list of suffixes Most macros that accept variable length comma separated lists use them in for or forsuffixes loops in this fashion as values to iterate over When there are no values to iterate over you can use a forever loop forever loop text endfor To terminate such a loop when a boolean condition becomes true use an exit clause exitif boolean expression When the MetaPost interpreter encounters an exit clause it evaluates the boolean expression and exits the current loop if the expression is true If it is more convenient to exit the loop when an expression becomes false use the predefined macro exitunless Thus MetaPost s version of a while loop is forever exitunless boolean expression loop text endfor The exit clause could equally well come just before endfor or anywhere in the loop text In fact any for forever or forsuffixes loop can contain any number of exit clauses The summary of loop syntax shown in Figure 47 does not mention exit clauses explicitly because a loop text can be virtually any sequence of tokens The only restriction is that a loop text must be balanced with respect to for and endfor Of course this balancing process treats forsuffixes and forever just like for 11 Making Boxes This section describes auxiliary macros not included in Plain MetaPost that make it convenient to do things that pic is good at
91. itered numeric 38 linejoin value for mitered joins 0 1mm numeric 3 One millimeter in bp units 2 83464 mpversion string 2 MetaPost version number nullpicture picture 15 Empty picture Torigin pair The pair 0 0 pe numeric One pica in bp units 11 95517 pencircle pen 42 Circular pen of diameter 1 Tpensquare pen 43 square pen of height 1 and width 1 ipt numeric 3 One printer s point in bp units 0 99626 Tquartercircle path First quadrant of a circle of diameter 1 jred color 13 Equivalent to 1 0 0 fright pair 7 Rightward direction 1 0 jrounded numeric 38 linecap and linejoin value for round joins and end caps 1 Tsquared numeric 38 linecap value for square end caps 2 true boolean 14 The boolean value true junitsquare path The path 0 0 1 0 1 1 0 1 cycle Tup pair 7 Upward direction 0 1 white color 13 Equivalent to 1 1 1 jwithdots picture 36 Dash pattern that produces dotted lines 71 A REFERENCE MANUAL Table 7 Operators Part 1 72 Name Argument result types Page Explanation Left Right Result amp string string string 15 Concatenation works for paths l amp r if path path path r starts exactly where the ends numeric cmyk color cmyk color 15 Multiplication numeric numeric pair pair cmyk color numeric cmyk color 15
92. l primary secondary tertiary binary def primarydef secondarydef tertiatydef Figure 46 The syntax for macro definitions The syntax also allows the undelimited part to specify an argument type of suffix or text An example of a macro with an undelimited suffix parameter is the predefined macro incr that is actually defined like this vardef incr suffix 1 enddef This makes incr a function that takes a variable increments it and returns the new value Un delimited suffix parameters may be parenthesized so incr a and incr a are both legal if a is a numeric variable There is also a similar predefined macro decr that subtracts 1 10 LOOPS 96 Undelimited text parameters run to the end of a statement More precisely an undelimited text parameter is the list of tokens following the macro call up to the first or endgroup or end except that an argument containing begingroup will always include the matching endgroup An example of an undelimited text parameter comes from the predefined macro cutdraw whose definition is roughly def cutdraw text t begingroup interim linecap butt draw t endgroup enddef This makes cutdraw synonymous with draw except for the linecap value This macro is provided mainly for compatibility with METAFONT 10 Loops Numerous examples in previous sections have used simple for loops of the form for symbolic token expression upto
93. l bot c c dotlabel 11ft d d z0 5 a d zi 5 b c z p z0 dotprod d a 0 z p zi dotprod c b 0 draw a d draw b c draw z0 z p z1 draw marked a b 1 draw marked c d 1 draw marked a z p 2 draw marked d z p 2 draw marked b z p 3 draw marked c z p 3 mark angle z p b a 1 mark angle z p c d 1 mark angle z p c b 2 mark angle c b z p 2 mark rt angle z p z0 a mark rt angle z p z1 b endfig Figure 42 MetaPost code and the corresponding figure 9 MACROS 50 marksize 4pt def draw mark expr p a begingroup save t dm pair dm t arctime a of p dm marksize unitvector direction t of p rotated 90 draw 5dm 5dm shifted point t of p endgroup enddef def draw marked expr p n begingroup save amid amid 5 arclength p for i n 1 2 upto n 1 2 draw mark p amid 6marksize i endfor draw p endgroup enddef Figure 43 Macros for drawing a path p with n cross marks angle radius 8pt def mark angle expr a b c n begingroup save S p path p p unitvector a b a b rotated 907 unitvector c b S 9marksize length point 1 of p point O of p if s angle radius s angle radius fi draw marked p scaled s shifted b n endgroup enddef def mark rt angle expr a b c draw 1 0 1 1 0 1 zscaled angle radius unitvector a b shifted b enddef Figure 44 Macros for marki
94. l 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 cmykcolors deal with pigments instead of light rays the color black would be expressed as 1 1 1 1 and white as 0 0 0 0 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 lt gt test objects of any type for equality and inequality Comparison relations lt lt gt and gt 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 n
95. mean 0 and standard deviation 1 A REFERENCE MANUAL Table 9 Operators Part 3 74 Name Argument result types Page Explanation Left Right Result not boolean boolean 14 Logical negation numeric any boolean 17 Is the expression of type numeric oct string numeric Interpret string as octal number odd numeric boolean Is the closest integer odd or even or boolean boolean boolean 14 Logical inclusive or pair any boolean 17 Is the expression of type pair path any boolean 17 Is the expression of type path pen any boolean 17 Is the expression of type pen penoffset pair pen pair Point on the pen furthest to the of right of the given direction picture any boolean 17 Is the expression of type picture point of numeric path pair 31 Point on a path given a time value postcontrol numeric path pair First B zier control point on path of segment starting at the given time precontrol numeric path pair Last B zier control point on path of segment ending at the given time redpart color numeric 17 Extract the first component reverse path path 40 time reversed path beginning swapped with ending rgbcolor any boolean 17 Is the expression of type color rotated picture numeric picture 34 Rotate counterclockwise a given path path number of degrees pa
96. mediation 11 12 16 METAFONT 1 21 43 45 56 65 68 84 metapost base 64 mexp 73 mfplain 84 middlepoint 47 midpoint 47 min 77 90 mitered 38 miterlimit 38 mlog 73 mm 3 mod 73 month 69 mplib 64 mpost 1 mproof tex 65 MPTEXPRE 24 mpto 24 mptopdf 24 mpxbreak 86 mpxerr log 23 mpxerr tex 23 multiplication implicit 3 multiplication implicit 17 newinternal 19 normaldeviate 73 not 14 nullary op 15 78 79 nullpicture 15 numeric 17 numeric atom 16 numeric type 13 oct 74 odd 74 of operator 55 78 79 option list 43 82 or 14 15 origin 71 pair 17 pair type 13 parameter expr 47 54 57 suffix 51 53 55 57 text 48 51 56 parameterization 6 parsing irregularities 15 17 path 17 47 path knot 16 78 path type 13 pausing 69 pc 71 pen 17 pen type 14 pencircle 3 42 penoffset 74 pens INDEX elliptical 42 polygonal 43 67 pensquare 43 pic 61 pickup 3 14 picture 17 picture type 14 picture variable 26 82 Plain macros 2 19 21 43 45 68 84 point PostScript 3 printer s 3 point of 31 postcontrol 74 PostScript 1 26 45 coordinate system 2 point 3 structured 23 precontrol 74 primary 14 78 primary binop 15 25 55 78 79 primarydef 55 prologues 23 pt 3 quartercircle 71 red 13 redpart 17 Redundant equation 12 reflectedabout 34 replacement text 45 55 81 r
97. ming language much like Knuth s METAFONT 4 except that it outputs PostScript programs instead of bitmaps Borrowed from METAFONT are the basic tools for creating and manipulating pictures These include numbers coordinate pairs cubic splines affine trans formations text strings and boolean quantities Additional features facilitate integrating text and graphics and accessing special features of PostScript such as clipping shading and dashed lines Another feature borrowed from METAFONT is the ability to solve linear equations that are given implicitly thus allowing many programs to be written in a largely declarative style By building complex operations from simpler ones MetaPost achieves both power and flexibility MetaPost is particularly well suited to generating figures for technical documents where some aspects of a picture may be controlled by mathematical or geometrical constraints that are best expressed symbolically In other words MetaPost is not meant to take the place of a freehand draw ing tool or even an interactive graphics editor It is really a programming language for generating graphics especially figures for TEX and troff documents The figures can be integrated into a TEX document via a freely available program called dvips as shown in Figure 1 2 A similar procedure works with troff the dpost output processor includes PostScript figures when they are requested via troff s XX command Figure
98. n Special string expression addto command drawing command font metric command show command tracing command command show expression list showvariable symbolic token list showtoken symbolic token list showdependencies symbolic token list symbolic token symbolic token symbolic token list expression list expression expression list expression addto command addto picture variable also picture expression option list addto picture variable contour path expression option list addto picture variable doublepath path expression option list option list empty drawing option option list drawing option withcolor color expression withrgcolor rgbcolor expression withcmykcolor cmykcolor expression withgreyscale numeric expression vithoutcolor withprescript string expression withpostscript string expression withpen pen expression dashed picture expression drawing command draw picture expression option list fill type path expression option list fill type fill draw filldraw unfill undraw unfilldraw drawarrow drawdblarrow cutdraw tracing command tracingall loggingall tracingnone Figure 60 The syntax for commands A REFERENCE MANUAL if test if boolean expression balanced tokens alternatives fi alternatives empty else balanced tokens e1seif boolean e
99. n internal variable called miterlimit that controls how 8 ADVANCED GRAPHICS beginfig 33 for i 0 upto 2 z i 0 40i z i 3 z i 2 100 30 endfor pickup pencircle scaled 18 draw z0 z3 withcolor 8white linecap butt draw zi 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 2 0 50i z i 3 z i l2 60 40 z i 6 z i 2 120 0 endfor pickup pencircle scaled 24 draw z0 z3 z6 withcolor 8white linejoin mitered draw zi 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 ce re Ne ecc er en we he Cie ew on ec ce e oce 39 8 ADVANCED GRAPHICS 40 extreme the situation can get before the mitered join is replaced by a beveled join For Plain MetaPost miterlimit has a default value of 10 0 and line joins revert to beveled when the ratio of miter length to line width reaches this value line m me 4 A Acc NUS miter length Figure 35 The miter length and line width whose ratio is limited by miterlimit The linecap linejoin and miterlimit parameters are especially important because they also affect things that get drawn behind the scenes For instance
100. name 10The name of this directory is likely to be something like usr lib mp lib but this is system dependent 11Some early versions of the box making macros did not allow any subscripts in the boxit suffix 11 MAKING BOXES 59 n nw ne dx C dx WwW e sw se S Figure 48 The relationship between the picture given to boxit and the associated variables The picture is indicated by a gray rectangle It is useful in combination with operators like cutbefore and cutafter in order to control paths that enter the box For example if a and b are box names and p is a path from a c to b c drawarrow p cutbefore bpath a cutafter bpath b draws an arrow from the edge of box a to the edge of box b Figure 49 shows a practical example including some arrows drawn with cutafter bpath box name It is instructive to compare Figure 49 to the similar figure in the pic manual 3 The figure uses a macro boxjoin equation text to control the relationship between consecutive boxes Within the equation text a and b represent the box names given in consecutive calls to boxit and the equation text gives equations to control the relative sizes and positions of the boxes For example the second line of input for the above figure contains 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 a is followed by some other box b These equations are first
101. nd of Section 8 7 p 38 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 8 8 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 addto command addto picture variable also picture expression option list addto picture variable contour path expression option list addto picture variable doublepath path expression option list option list empty drawing option option list drawing option withcolor color expression withrgbcolor rgbcolor expression withcmykcolor cmykcolor expression withgreyscale numeric expression vithoutcolor withprescript string expression
102. nd they need not have known values Thus for t 3 14 2 78 a 2a hello show t endfor shows the four values listed Note that the loop body in the above example is a statement followed by a semicolon It is common for the body of a loop to be one or more statements but this need not be the case A 11 MAKING BOXES 57 loop is like a macro definition followed by calls to the macro The loop body can be virtually any sequence of tokens as long as they make sense together Thus the ridiculous statement draw for p 3 1 6 2 7 5 4 6 1 3 p endfor cycle is equivalent to draw 3 1 6 2 7 5 4 6 1 3 cycle See Figure 18 for a more realistic example of this If a loop is like a macro definition the loop index is like an expr parameter It can represent any value but it is not a variable and it cannot be changed by an assignment statement In order to do that you need a forsuffixes loop A forsuffixes loop is a lot like a for loop except the loop index behaves like a suffix parameter The syntax is forsuffixes symbolic token suffix list loop text endfor where a suffix list is a comma separated list of suffixes If some of the suffixes are empty the loop text gets executed with the loop index parameter set to the empty suffix A good example of a forsuffixes loop is the definition of the dotlabels macro vardef dotlabels text t forsuffixes t dotlabel str z endfor enddef Th
103. ng angles 9 MACROS 51 If the hide macro were not predefined it could be defined like this def ignore expr a enddef def hide text t ignore begingroup t 0 endgroup enddef The statements represented by the text parameter t would be evaluated as part of the group that forms the argument to ignore Since ignore has an empty replacement text expansion of the hide macro ultimately produces nothing Another example of a predefined macro with a text parameter is dashpattern The definition of dashpattern starts def dashpattern text t begingroup save on off then it defines on and off to be macros that create the desired picture when the text parameter t appears in the replacement text Text parameters are very general but their generality sometimes gets in the way If you just want to pass a variable name to a macro it is better to declare it as a suffix parameter For example def incr suffix begingroup 41 endgroup enddef defines a macro that will take any numeric variable add one to it and return the new value Since variable names can be more than one token long incr a3b is perfectly acceptable if a3b is a numeric variable Suffix parameters are slightly more general than variable names because the definition in Figure 16 allows a suffix to start with a subscript Figure 45 shows how suffix and expr parameters can be used together The getmid macro takes a path variable and creates arrays
104. not interfere with uses of verbatimtex p 23 Here s the same example as above using the IXTEX commands NC and V input TEX TEXPRE amp latex amp char 10 documentclass article begin document TEXPOST end document beginfig 100 last 10 for i O upto last label TEX n_ decimal i 5mm i 0 endfor endfig Explanation e The amp latex causes IATEX to be invoked instead of TEX See below also Web2C and MiK TeX based TEX implementations at least understand this amp specification see e g the Web2C documentation for details http tug org web2c Information on how to do the same with other systems would be most welcome e The char 10 puts a newline ASCII character code 10 decimal in the output e The Ndocumentclass is the usual way to start a TEX document 13 DEBUGGING 65 e The TEXPOST end document is not strictly necessary due to the behavior of mpto but it is safer to include it Unfortunately TEX special instructions vanish in this process So it is not possible to use packages such as xcolor and hyperref In case you re curious these routines are implemented very simply they write btex commands to a temporary file and then use scantokens p 14 to process it The makempx mechanism p 24 does all the work of running TEX The amp magic on the first line is not the only way to specify invoking a different program than plain TE
105. ode and the corresponding output 8 ADVANCED GRAPHICS 31 must be one of 0 25 1 77 0 75 1 40 or 2 58 0 24 depending on which of the three intersection points is chosen by the MetaPost interpreter The exact rules for choosing among multiple intersection points are a little complicated but it turns out that you get the time values 0 25 1 77 in this example Smaller time values are preferred over larger ones so that t tp is preferred to t t whenever ta lt t and ty lt tj When no single alternative minimizes both the ta and ty components the ta component tends to get priority but the rules get more complicated when there are no integers between ta and t For more details see The METAFONTbook 4 Chapter 14 Figure 25 Two intersecting paths with time values marked on each path The intersectiontimes operator is more flexible than intersectionpoint because there are a number of things that can be done with time values on a path One of the most important is just to ask where is path p at time t The construction point numeric expression of path primary answers this question If the numeric expression is less than zero or greater than the time value assigned to the last point on the path the point of construction normally yields an endpoint of the path Hence it is common to use the predefined constant infinity equal to 4095 99998 as the numeric expression in a point of construction when dealing with
106. oin 59 bp 3 bpath 58 61 btex 21 23 26 buildcycle 28 butt 38 56 CAPSULE 46 cc 71 ceiling 17 center 25 char 25 charcode 45 circleit 61 circmargin 61 clip 44 cm 3 cmykcolor 17 cmykcolor type 14 color 17 color type 13 comments 18 comparison 14 compound statement 45 concatenation 15 control points 6 67 controls 6 convex polygons 43 corners 38 cosd 17 Courier 23 Creator comment in PostScript output 2 curl 8 currentpen 41 44 currentpicture 14 28 43 44 curvature 5 7 8 cutafter 32 59 cutbefore 31 59 cutdraw 56 cuttings 32 cyanpart 17 cycle 5 17 INDEX dash pattern 36 38 recursive 38 dash pattern 37 dashed 36 41 43 dashpattern 51 day 69 dd 71 decimal 17 declarations 19 decr 55 def 45 defaultcolormodel 27 defaultdx 58 defaultdy 58 defaultfont 21 defaultpen 43 defaultscale 21 dir 7 direction of 32 55 directionpoint of 32 directiontime of 32 ditto 71 div 73 dotlabel 20 dotlabels 20 57 dotprod 15 54 55 dots 3 down 7 downto 56 draw 2 14 28 54 draw_mark 48 draw_marked 48 drawarrow 40 59 drawboxed 58 59 61 drawboxes 61 drawdblarrow 40 drawing option 43 drawoptions 41 44 drawshadowed 62 drawunboxed 61 dvips 1 else 47 elseif 48 end 2 3 56 enddef 45 endfig 3 45 86 endfor 3 56 endgroup 45 53 56 EPSF 23 epsf tex 4 epsilon 71 89 erasing 27 41 etex 21 23
107. on applied to a draw picture expression statement will in general affect some parts of the picture but not others For instance a dashed or withpen option will affect all the lines in the picture but none of the labels 8 7 Pens Previous sections have given numerous examples of pickup pen expression and withpen pen expression but there have not been any examples of pen expressions other than pencircle scaled numeric primary which produces lines of a specified width For calligraphic effects such in Figure 38 you can apply any of the transformation operators discussed in Section 8 3 The starting point for such transformations is pencircle a circle one PostScript point in diameter Thus affine transformations produce a circular or elliptical pen shape The width of lines drawn with the pen depends on how nearly perpendicular the line is to the long axis of the ellipse beginfig 38 pickup pencircle scaled 2in yscaled 08 rotated 30 x0 x3 x4 zi zO 4bin dir 30 z2 z3 whatever zi z0 en z6 z5 whatever zi z0 3 zi z6 1 2 z3 z0 1 rt x3 lft x2 0 x5 55 x4 x6 F M RE B c y4 y6 e 5 e lft x3 bot yb 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 Figure 38 demonstrates operators 1ft rt top and bot that answer the question If the current pen is plac
108. ore or cutafter Tdefaultfont string 21 Font used by label commands for typesetting strings jextra beginfig string 86 Commands for beginfig to scan jextra_endfig string 86 Commands for endfig to scan 70 A REFERENCE MANUAL Table 6 Predefined Constants Name Type Page Explanation jbeveled numeric 38 linejoin value for beveled joins 2 black color 13 Equivalent to 0 0 0 blue color 13 Equivalent to 0 0 1 Tbp numeric 3 One PostScript point in bp units 1 butt numeric 38 linecap value for butt end caps 0 tec numeric One cicero in bp units 12 79213 tom numeric One centimeter in bp units 28 34645 1dd numeric One didot point in bp units 1 06601 ditto string The character as a string of length 1 Tdown pair 7 Downward direction vector 0 1 Tepsilon numeric Smallest positive MetaPost number 5x Tevenly picture 36 Dash pattern for equal length dashes false boolean 14 The boolean value false jfullcircle path 27 Circle of diameter 1 centered on 0 0 jgreen color 13 Equivalent to 0 1 0 jhalfcircle path 27 Upper half of a circle of diameter 1 Tidentity transform 34 Identity transformation Tin numeric 3 One inch in bp units 72 linfinity numeric 31 Large positive value 4095 99998 jleft pair 7 Leftward direction 1 0 jm
109. ow the linear equations given so far make them depend on other variables Thus after z2 z1 5 10 z1 z2 a b 13 DEBUGGING 67 showdependencies prints what is shown in Figure 54 This could be useful in answering a question like What does it mean Undefined x coordinate I thought the equations given so far would determine x1 x2 0 5a 2 5 y2 0 5b 5 x1 0 5a 2 5 y1 0 5b 5 Figure 54 The result of z2 z1 5 10 zi z2 a b showdependencies When all else fails the predefined macro tracingall causes the interpreter to print a detailed listing of everything it is doing Since the tracing information is often quite voluminous it may be better to use the loggingall macro that produces the same information but only writes it in the transcript file There is also a tracingnone macro that turns off all the tracing output Tracing output is controlled by the set of internal variables summarized below When any one of these variables is given a positive value the corresponding form of tracing is turned on Here is the set of tracing variables and what happens when each of them is positive tracingcapsules shows the values of temporary quantities capsules when they become known tracingchoices shows the B zier control points of each new path when they are chosen tracingcommands shows the commands before they are performed A setting gt 1 also shows if tests and loops before they are expanded a setting gt 2 shows algebraic oper
110. ows to be macros rather than primitives A few comments on the semantics are in order here If there is a non empty direction specifier before a path knot but not after it or vice 4 LINEAR EQUATIONS 9 2 2 2 2 1 1 1 1 0 0 0 0 c 0 c 1 c 2 c oo Figure 11 Results of draw zO curl c z1 curl c z2 for various values of the curl parameter c versa the specified direction or curl amount applies to both the incoming and outgoing path seg ments 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 subexpression direction specifier path subexpression path join cycle path subexpression path knot path expression path join path knot path join direction specifier basic path join direction specifier direction specifier empty curl numeric expression pair expression numeric expression numeric expression basic path join gt tension controls tension tension numeric primary tension numeric primary and numeric primary controls controls pair primary controls pair primary and pair 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
111. p and endgroup are automatically inserted at the beginning and end of the re placement text of every vardef macro This makes the replacement text a group so that a vardef macro behaves like a subroutine or a function call Another property of vardef macros is that they allow multi token macro names and macro names involving generic subscripts When a vardef macro name has generic subscripts numeric values have to be given when the macro is called After a macro definition vardef a b expr p replacement text enddef a2b 1 2 and a3b 1 2 3 4 are macro calls But how can the replacement text tell the difference between a2b and a3b Two implicit suffix parameters are automatically provided for this purpose Every vardef macro has suffix parameters and 0 where is the last token in the name from the macro call and is everything preceding the last token Thus is a2 when the name is given as a2b and a3 when the name is given as a3b Suppose for example that the a b macro is to take its argument and shift it by an amount that depends on the macro name The macro could be defined like this vardef a b expr p p shifted 40 b enddef Then a2b 1 2 means 1 2 shifted a2 b and a3b 1 2 3 4 means 1 2 3 4 shifted a3 b If the macro had been a b would always be a b and the parameter would give the numeric subscript Then a would refer to an element of the array al Note that is a suffix
112. parameter not an expr parameter so an expression like 1 would be illegal The only way to get at the numeric values of subscripts in a suffix parameter is by extracting them from the string returned by the str operator This operator takes a suffix and returns a string representation of a suffix Thus str would be 3 in a b3 and 3 14 in a b3 14 or a b 3 14 Since the syntax for a suffix in Figure 16 requires negative subscripts to be in brackets str returns 3 in a b 3 The str operator is generally for emergency use only It is better to use suffix parameters only as variable names or suffixes The best example of a vardef macro involving suffixes is the z macro that defines the z convention The definition involves a special token that refers to the suffix following the macro name vardef z x y enddef 9 MACROS 54 This means that any variable name whose first token is z is equivalent to a pair of variables whose names are obtained by replacing z with x and y For instance z a1 calls the z macro with the suffix parameter set to al In general vardef generic variable Qst is an alternative to vardef generic variable that causes the MetaPost interpreter to look for a suffix following the name given in the macro call and makes this available as the suffix parameter To summarize the special features of vardef macros they allow a broad class of macro names as well as macro names followed by a special
113. pecial command to insert a request for fig 1 It is also possible to include MetaPost output in a troff document The mpictures macro package defines a command BP that includes an encapsulated PostScript file For instance the troff command BP fig 1 3c 3c includes fig 1 and specifies that its height and width are both three centimeters 2 1 Filename templates Metapost has support for output file name templates These templates use printf style escape sequences and are re evaluated before each figure is written to disk The command to use is filenametemplate and it accepts a string as argument The syntax is as simple as filenametemplate 4j 43c mps beginfig 1 draw p endfig If the file is saved as fig mp then this will create the output file fig 001 mps instead of fig 1 A small set of escape sequences are possible see table 1 for details To ensure compatibility with older files the default value of filenametemplate is 4j 4c If you assign an empty string it will revert to that default 3 Curves MetaPost is perfectly happy to draw curved lines as well as straight ones A draw statement with the points separated by draws a smooth curve through the points For example consider the result of draw z0O zi z2 z3 z4 3 CURVES 5 after defining five points as follows zO 0 0 zi 60 40 z2 40 90 z3 10 70 z4 30 50 Figure 3 shows the curve with points zO through z4 labeled 2
114. picture variable to path expression makes the picture variable behave as if its bounding box were the same as the given path To get the true bounding box of such a picture assign a positive value to the internal variable truecorners i e show urcorner btex bullet rlap A etex produces gt gt 4 9813 6 8078 while truecorners 1 show urcorner btex bullet rlap A etex produces gt gt 15 7742 6 8078 8 Advanced Graphics All the examples in the previous sections have been simple line drawings with labels added This section describes shading and tools for generating not so simple line drawings Shading is done with the fill statement In its simplest form the fill statement requires a path expression that gives the boundary of the region to be filled In the syntax fill path expression the argument should be a cyclic path i e a path that describes a closed curve via the cycle or cycle notation For example the fill statement in Figure 21 builds a closed path by extending the roughly semicircular path p This path has a counter clockwise orientation but that does not matter because the fill statement uses PostScript s non zero winding number rule 1 The general fill statement fill path expression withcolor color expression specifies a shade of gray or if you have a color printer some rainbow color The color expression can have five possible values mapping to four possible color
115. r empty The circleit macro defines pair variable just as boxit does except that there are no corner points box name ne box name sw etc A call to circleit a gives relationships among points a c a s a e a n a w and distances a dx and a dy Together with a c and a off these variables describe how the picture is centered in an oval as can be seen from the Figure 50 The drawboxed drawunboxed drawboxes pic and bpath macros work for circleit boxes just as they do for boxit boxes By default the boundary path for a circleit box is a circle large enough to surround the box contents with a small safety margin controlled by the internal variable circmargin Figure 51 gives a basic example of the use of bpath with circleit boxes A full example of circleit boxes appears in Figure 52 The oval boundary paths around Start and Stop are due to the equations aa dx aa dy and ee dx ee dy after circleit ee btex strut Stop etex and circleit ee btex strut Stop etex The general rule is that bpath c comes out circular if c dx c dy and c dx c dy are all unknown Otherwise the macros select an oval big enough to contain the given picture with the safety margin circmargin 11 MAKING BOXES 62 dx dx eo dy S Figure 50 The relationship between the picture given to circleit and the associated variables The picture is indicated by a gray rectangle vardef drawshadowed text t fixsize t forsuffixes s t
116. raw mark with the appropriate arc length values The draw marked macro in Figure 43 uses n equally spaced a values centered on 5 arclength p Since draw marked works for curved lines it can be used to draw the arcs that the mark angle macro generates Given points a b and c that define a counter clockwise angle at b the mark angle needs to generate a small arc from segment ba to segment bc The macro definition in Figure 44 does this by creating an arc p of radius one and then computing a scale factor s that makes it big enough to see clearly The mark rt angle macro is much simpler It takes a generic right angle corner and uses the zscaled operator to rotate it and scale it as necessary 9 3 Suffix and Text Parameters Macro parameters need not always be expressions as in the previous examples Replacing the keyword expr with suffix or text in a macro definition declares the parameters to be variable names or arbitrary sequences of tokens For example there is a predefined macro called hide that takes a text parameter and interprets it as a sequence of statements while ultimately producing an empty replacement text In other words hide executes its argument and then gets the next token as if nothing happened Thus show hide numeric a b a b 3 a b 1 a prints gt gt 2 9 MACROS beginfig 42 pair a b c d b 0 0 c 1 5in 0 a 0 6in d c a b rotated 25 dotlabel lft a a dotlabel lft b b dotlabe
117. re secondary rotated numeric primary This is used in Figure 19 to rotate the label y axis so that it runs vertically 7 INTEGRATING TEXT AND GRAPHICS 22 beginfig 18 numeric u u icm draw 0 2u 0 0 4u 0 ud pickup pencircle scaled 1pt vz draw 0 0 up y for i 1 upto 8 i 2 sqrt i 2 u endfor label lrt btex sqrt x etex 3 sqrt 3 u label bot btex x etex 2u 0 label lft btex y etex 0 u endfig Figure 18 Arbitrary T X as labels beginfig 19 u 2 numeric ux uy l coszx 120ux 1 2in 4uy 2 4in draw 0 4uy 0 0 120ux 0 pickup pencircle scaled 1pt draw 0 uy right for ix 1 upto 8 15ix ux uy 2 1 cosd 15ix 4 endfor 8 label bot btex x axis etex 60ux 0 label lft btex y axis etex rotated 90 0 2uy label 1ft btex displaystyle y 12l0veri Xcos x etex 120ux 4uy endfig x axis Figure 19 TEX labels with display math and rotated by MetaPost 7 INTEGRATING TEXT AND GRAPHICS 23 Another complication in Figure 19 is the use of the displayed equation 2 T l coszx as a label It would be more natural to code this as y 2 over 1 cos x but this would not work because TEX typesets the labels in horizontal mode For a way to typeset variable text as labels see the TEX utility routine described on p 64 Here is how TEX material gets translated into a form MetaPost understands The MetaPost processor skips over btex
118. rent pen when centered pair pair at the given coordinate s transform E any boolean 17 Is the argument of type transform transformed picture transform picture 34 Apply the given transform to all path path coordinates pair pair pen pen transform transform ulcorner picture pair 25 Upper left corner of bounding box path pen uniform numeric numeric Random number between zero and deviate the value of the argument junitvector pair pair 17 Rescale a vector so its length is 1 unknown any boolean 17 Is the value unknown urcorner x picture pair 25 Upper left corner of bounding box path pen whatever numeric 11 Create a new anonymous unknown xpart pair number 17 x or ty component transform xscaled picture numeric picture 34 Scale all z coordinates by the path path given amount pair pair pen pen transform transform xxpart transform number 35 44 entry in transformation matrix xypart transform number 35 ty entry in transformation matrix yellowpart cmykcolor numeric 17 Extract the third component ypart pair number 17 y or ty component transform yscaled picture numeric picture 34 Scale all y coordinates by the path path given amount pair pair pen pen transform transform yxpart transform number 35 tyz entry in transformation matrix yypart transform number 35 tyy entry in transformation matrix zscaled picture pair picture 34 Rotate and scale all coordinat
119. rs and produce results of the same type Other operators that fall in this category are Pythagorean addition and Pythagorean subtraction a b means Va b and a b means ya b There are too many other operators to list here but some of the most important are the boolean operators and and or The and operator is a primary binop and the or operator is a secondary binop The basic operations on strings are concatenation and substring construction The tertiary binop amp implements concatenation e g abc amp de produces the string abcde For substring construction the of operator substring is used like this substring pair expression of string primary The pair expression determines what part of the string to select For this purpose the string is indexed so that integer positions fall between characters Pretend the string is written on a piece of graph paper so that the first character occupies x coordinates between zero and one and the next character covers the range 1 x lt 2 etc Thus the string abcde should be thought of like this alble die 2 0 1 2 3 4 5 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 5 EXPRESSIONS 16
120. rs grayfont hround imagerules lowres fix nodisplays notransforms openit proofoffset Screenchars Screenrule Screenstrokes showit slantfont titlefont unitpixel vround Table 14 Macros and internal variables defined only in the mfplain package 85 REFERENCES 86 the drawing option withweight Here is a complete listing of the internal variables whose primitive meanings in METRFONT do not make sense in MetaPost autorounding fillin proofing tracingpens xoffset chardx granularity smoothing turningcheck yoffset chardy hppp tracingedges vppp 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 METRFONT 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 All the other differences between METRFONT and MetaPost are features found only in MetaPost These are listed in Table 15 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 15 not listed in
121. rt specifiers for transforms will be discussed later 6 Variables MetaPost allows compound variable names such as x a x2r y2r and z2r where z2r means x2r y2r and z a means x a y a In fact there is a broad class of suffixes such that z suf fix means x suffix y suffix Since a suffix is composed of tokens it is best to begin with a few comments about tokens 6 1 Tokens A MetaPost input file is treated as a sequence of numbers string constants and symbolic tokens A number consists of a sequence of digits possibly containing a decimal point Technically the minus sign in front of a negative number is a separate token Since MetaPost uses fixed point arithmetic it does not understand exponential notation such as 6 02E23 MetaPost would interpret this as the number 6 02 followed by the symbolic token E followed by the number 23 6 VARIABLES 18 ABCDEFGHIJKLMNOPQRSTUVWXYZ abcdefghijklmnopqrstuvwxyz lt gt amp 0 I Table 2 Character classes for tokenization Anything between a pair of double quotes is a string constant It is illegal for a string constant to start on one line and end on a later line Nor can a string constant contain double quotes or anything other than printable ASCII characters Everything in a line of input other than numbers and string constants is broken into symbolic tokens A symbolic token is a sequence of one or more similar characters where characters are
122. ry zscaled pair primary reflectedabout pair expression pair expression rotatedaround pair expression numeric expression Figure 27 The syntax for transforms and related operators then q p transformed inverse T It is not legal to take the inverse of an unknown transform but we have already seen that you can say T transform expression when T has not been given a value yet It is also possible to apply an unknown transform to a known pair or transform and use the result in a linear equation Three such equations are sufficient to determine a transform Thus the equations 0 1 transformed T 3 4 1 1 transformed T 7 1 1 0 transformed T 4 3 allow MetaPost to determine that the transform T is a combination of rotation and scaling with tre 4 Lys 3 tyz 3 tyy 4 t 0 ty 0 Equations involving an unknown transform are treated as linear equations in the six parameters that define the transform These six parameters can also be referred to directly as xpart T ypart T xxpart T xypart T yxpart T yypart T where T is a transform For instance Figure 28 uses the equations xxpart T yypart T yxpart T xypart T to specify that T is shape preserving ie it is a combination of rotating shifting and uniform scaling 8 ADVANCED GRAPHICS 36 beginfig 28 path pl pi fullcircle scaled 6in zi 75in 0 z3 z2 directionpoint left of pi z4 p2 z1 22
123. s ceiling numeric numeric 17 Least integer greater than or equal to Tcenter picture pair 25 Center of the bounding box path pen A REFERENCE MANUAL Table 8 Operators Part 2 73 Name Argument result types Page Explanation Left Right Result char numeric string 25 Character with a given ASCII code cmykcolor any boolean 17 Is the expression of type cmykcolor colormodel image object numeric What is the color model of the image object color any boolean 17 Is the expression of type color cosd numeric numeric 17 Cosine of angle in degrees jcutafter path path path 32 Left argument with part after the intersection dropped jcutbefore path path path 31 Left argument with part before the intersection dropped cyanpart cmykcolor numeric 17 Extract the first component cycle path boolean 17 Determines whether a path is cyclic decimal numeric string 17 The decimal representation fdir numeric pair 7 cos sin given 0 in degrees direction numeric path pair 32 The direction of a path at a given of time Tdirection pair path numeric 32 Point where a path has a given point of direction direction pair path numeric 32 Time when a path has a given time of direction div numeric numeric numeric Integer division T T
124. s 41 Set options for drawing commands drawunboxed list of suffixes x 61 Draw contents of named boxes fixpos list of suffixes i 59 Solve for the size and position of the named boxes fixsize list of suffixes 59 Solve for size of named boxes Timage string picture 44 Return picture from text Tincr numeric variable numeric 55 Increment and return new value Tlabel suffix picture pair a 19 Draw picture near given point label suffix string pair 19 Place text near given point labels suffix point numbers 21 Draw z point numbers no dots jmax list of numerics numeric Find the maximum jmax list of strings string Find the lexicographically last string jmin list of numerics numeric Find the minimum jmin list of strings string Find the lexicographically first string pic suffix picture 61 Box contents shifted into position jthelabel suffix picture pair picture 20 Picture shifted as if to label a point jthelabel suffix string pair picture 20 text positioned as if to label a point iz suffix pair 18 The pair x suffix y suffix A REFERENCE MANUAL 78 atom variable argument number or fraction internal variable expression begingroup statement list expression endgroup nullary op btex typesetting commands etex pseudo function primary atom numeric expression numeric expression numeric expression numeric express
125. s 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 expres sions in Figures 55 57 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 4 12 Figures 59 and 60 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 55 61 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 61 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 A REFERENCE MANUAL Table 4 Internal variables with numeric values 69
126. s in MetaPost TEX Document MetaPost TEX Figures in PostScript dvi file dvips PostScript Figure 1 A diagram of the processing for a TEX document with figures in MetaPost To use MetaPost you prepare an input file containing MetaPost code and then invoke MetaPost usually by giving a command of the form mpost filename The syntax and program name itself are system dependent sometimes it is named mp MetaPost input files normally have names ending mp but this part of the name can be omitted when invoking MetaPost For an input file foo mp mpost foo IMETRFONT is a trademark of Addison Wesley Publishing company PostScript is a trademark of Adobe Systems Inc 3T X is a trademark of the American Mathematical Society 1The C source for dvips comes with the web2c TEX distribution Similar programs are available from other sources 2 BASIC DRAWING STATEMENTS 2 invokes MetaPost and produces output files with names like foo 1 and foo 2 Any terminal I O is summarized in a transcript file called foo log This includes error messages and any MetaPost commands entered interactively The transcript file starts with a banner line that identifies the version of MetaPost you are using You can also determine the current version from within a MetaPost program via the mpversion predefined constant string this was introduced in version 0 9 For instance if known mpversion message mp amp mpversion if mp
127. sions Note that if tests are not statements and the balanced tokens in the syntax rules can be any sequence of balanced tokens even if they do not form a complete expression or statement Thus we could have saved two tokens at the expense of clarity by defining midpoint like this def midpoint expr a if path a point 5 length a of else 5 l1corner a urcorner fi a enddef if test if boolean expression balanced tokens alternatives fi alternatives empty else balanced tokens e1seif boolean expression balanced tokens alternatives Figure 41 The syntax for if tests The real purpose of macros and if tests is to automate repetitive tasks and allow important subtasks to be solved separately For example Figure 42 uses macros draw marked mark angle and mark rt angle to mark lines and angles that appear in the figure The task of the draw marked macro is to draw a path with a given number of cross marks near its midpoint A convenient starting place is the subproblem of drawing a single cross mark perpendicular to a path p at some time t The draw mark macro in Figure 43 does this by first finding a vector dm perpendicular to p at t To simplify positioning the cross mark the draw marked macro is defined to take an arc length a along p and use the arctime operator to compute t With the subproblem of drawing a single mark out of the way the draw marked macro only needs to draw the path and call d
128. suffix parameter Furthermore begingroup and endgroup are automatically added to the replacement text of a vardef macro Thus using vardef instead of def to define the joinup macro in Figure 45 would have avoided the need to include begingroup and endgroup explicitly in the macro definition In fact most of the macro definitions given in previous examples could equally well use vardef instead of def It usually does not matter very much which you use but a good general rule is to use vardef if you intend the macro to be used like a function or a subroutine The following comparison should help in deciding when to use vardef e Vardef macros are automatically surrounded by begingroup and endgroup e The name of a vardef macro can be more than one token long and it can contain subscripts e A vardef macro can have access to the suffix that follows the macro name when the macro is called e When a symbolic token is used in the name of a vardef macro it remains a tag and can still be used in other variable names Thus p5dir is a legal variable name even though dir is a vardef macro but an ordinary macro such as cannot be used in a variable name This is fortunate since zb z6 is supposed to be a path expression not an elaborate variable name 9 5 Defining Unary and Binary Macros It has been mentioned several times that some of the operators and commands discussed so far are actually predefined macros These include unary operators such
129. t figures in a paper done in TEX or troff are system dependent They can generally be found in manual pages and other on line documentation 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 On Web2C based systems the preprocessor is named makempx which calls another utility mpto the Web2C documentation describes them in more detail We ll mention one feature here though if the environment variable MPTEXPRE is set to the name of an existing file nakempx will prepend it to the output You can use this to include I3TEX preambles for instance The TEX macro described on p 64 provides another way to handle this 7 2 Font map files If prologues is set to 2 any used fonts in the output file are automatically re encoded and the encoding vector file specified in the fontmap entry will be embedded in the output file If prologues is set to 3 MetaPost will also attempt to include a subset of the used PostScript fonts For this to work it needs to acquire font map information The code is based on the font library used by pdfIEX Following in the footsteps of pdf TEX there are two new associated primitives fontmapfile and fontmapline Here is a simple example specifying the map file for Latin Modern fonts in IATEX T1 encoding prologues 2 fontmapfile ec public lm map beginfig 1
130. t file 2 transform 17 transform type 13 32 transformation unknown 35 transformed 13 34 troff 1 4 23 86 troffmode 23 true 14 truecorners 26 type declarations 19 types 13 ulcorner 25 ulft 20 unary op 15 78 79 undraw 41 unfill 27 unfilldraw 41 uniformdeviate 75 unitsquare 71 unitvector 17 54 Unix 23 unknown 17 until 56 up 7 upto 56 urcorner 25 urt 20 utility routines 64 vardef 53 variables internal 13 19 20 25 26 38 40 45 47 58 61 66 67 84 local 19 45 verbatimtex 64 verbatimtex 23 warningcheck 13 whatever 46 whatever 11 white 13 92 winding number 26 withcolor 26 41 43 withdots 36 withpen 41 43 xpart 17 35 xscaled 34 xxpart 35 xypart 35 year 69 yellowpart 17 ypart 17 ypart 35 yscaled 32 34 yxpart 35 yypart 35 z convention 10 18 53 zscaled 34 48
131. t the tip of the arrowhead The default value of this angle is 45 degrees as shown in the figure 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 8 ADVANCED GRAPHICS 41 ahlength ahangle ahlength Figure 37 A large arrowhead with key parameters labeled and paths used to draw it marked with white lines 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
132. t when this job started tracingcapsules 67 gt 0 to show capsules too tracingchoices 67 gt 0 to show the control points chosen for paths tracingcommands 67 gt 0 to show commands and operations as they are performed tracingequations 67 gt 0 to show each variable when it becomes known tracinglostchars 67 gt 0 to show characters that aren t infont tracingmacros 67 gt 0 to show macros before they are expanded tracingonline 13 gt 0 to show long diagnostics on the terminal tracingoutput 67 gt 0 to show digitized edges as they are output tracingrestores 67 gt 0 to show when a variable or internal is restored tracingspecs 67 gt 0 to show path subdivision when using a polygonal a pen tracingstats 67 gt 0 to show memory usage at end of job tracingtitles gt 0 to show titles online when they appear troffmode set to 1 if a troff or T option was given truecorners 26 gt 0to make 11corner etc ignore setbounds warningcheck 13 controls error message when variable value is large year the current year e g 1992 A REFERENCE MANUAL Table 5 Other Predefined Variables Name Type Page Explanation background color 28 Color for unfill and undraw usually white Tcurrentpen pen 44 Last pen picked up for use by the draw command jcurrentpicture picture 43 Accumulate results of draw and fill commands jcuttings path 32 subpath cut off by last cutbef
133. tands for any path c stands for a cyclic path and pic stands for a picture expression Note that nonempty drawoptions would complicate the entries in the second column The image macro from Plain MetaPost takes any text as its argument executes it and returns the resulting picture The value of currentpicture is not affected There are two more primitive drawing commands that do not accept any drawing options One is the setbounds command that was discussed in Section 7 4 the other is the clip command clip picture variable to path expression Given a cyclic path this statement trims the contents of the picture variable to eliminate everything outside of the cyclic path There is no high level version of this statement so you have to use clip currentpicture to path expression if you want to clip currentpicture Figure 40 illustrates clipping beginfig 40 path p pi 0 0 curl 0 5pt 3pt curl 0 10pt 0 p2 p1 p1 yscaled 1 shifted 10pt 0 pO p2 for i 1 upto 3 p0 p0 p2 shifted i 20pt 0 endfor for j 0 upto 8 draw pO shifted 0 j 10pt endfor p3 fullcircle shifted 5 5 scaled 72pt clip currentpicture to p3 draw p3 endfig Figure 40 MetaPost code and the resulting clipped figure All the primitive drawing operations would be useless without one last operation called shipout The statement shipout picture expression 9 MACROS 45 This writes out a picture
134. tegrating Text and Graphics 1 1 Typesetting Your Labels n s 2 a a tes e o eee e ehe ege deat 2 Bon6mapfl sc aego a y Ea ege e Do eae ta a e dd 1 3 The infont operator oz 4 cod Ahaide ae d Lee ee eee i 4 4 Measuring Text e eet a saaa da AA AR REE a 8 Advanced Graphics SE SBuldimg Cycles z c uuo S eue uod odo Soo eet e Ro Ce e Tbe Rl rede ded e 8 2 Dealing with Paths Parametrically eee 8 3 Affine Transformations 2 2 a ss 8 4 Dashed ines emu A E EO REESE Ee EGER RS 8 5 Wocal specials acne fh a a EU ENSE eur ese dud pud hd a 8 6 Other Options 223394 e ee e444 Pere ee oe ruere Qve idees O MEM 3 dow hw A aca le a a a ataa 8 8 Clipping and Low Level Drawing Commands ss 9 Macros 9 11 GYQUDIBE uuo hee e he RR EN Ge So da aa ee A A e de A a edd 9 2 Parameterized Macros e a a 0 0 eee E a a a li e ER G A 9 3 Suffix and Text Parameters oaea a 9 4 Vardet Mactos Lou eum al Be ELLE Esa 9 5 Defining Unary and Binary Macros eA 10 Loops 11 Making Boxes 1T P Rectangular Boxes 3 uos be S purus qox E ata qo Re s ec e e e Re P adea 11 2 Circular and Oval Boxes s T eoo Roe RR URSUS RU S R 12 Utility Routines 2X STEM apis i Loo DEAS uult Seed du dak dh kk M e Me Me redis die Bo ki rut 12 2 mproof tex nune RN 13 Debugging cana AN e A Reference Manual B MetaPost Versus METRFONT ii 68 84 1 INTRODUCTION 1 1 Introduction MetaPost is a program
135. 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 References 1 Adobe Systems Inc PostScript Language Reference Manual Addison Wesley Reading Mas sachusetts 1986 2 J D Hobby Smooth easy to compute interpolating splines Discrete and Computational Geo metry 1 2 1986 3 Brian W Kernighan Pic a graphics language for typesetting In Unix Research System Papers Tenth Edition pages 53 77 AT amp T Bell Laboratories 1990 4 D E Knuth The METAFONTbook Addison Wesley Reading Massachusetts 1986 Volume C of Computers and Typesetting 5 D E Knuth The TgXbook Addison Wesley Reading Massachusetts 1986 Volume A of Computers and Typesetting 6 D E Knuth Computer Modern Typefaces Addison Wesley Reading Massachusetts 1986 Volume E of Computers and Typesetting 7 D E Knuth The new versions of TEX and METAFONT TUGboat the TgX User s Group Newsletter 10 3 325 328 November 1989 REFERENCES Table 15 Macros and internal variables defined in MetaPost but not METAFONT MetaPost primitives not found in METAFONT blackpart greenpart setbounds bluepart greypart tracinglostchars btex infont troffmode clip linecap truecorners cmykcolor linejoin ulcorner color llcorner urcorner colormodel lrcorner verbatimtex cyanpart magentapart withcmykcolor
136. turns its first argument There is also an analogous tertiary binop called cutafter that works by applying cutbefore with time reversed along its first argument Thus p cutafter p tries to cut off the part of p after its last intersection with po Another operator direction numeric expression of path primary finds a vector in the direction of the path primary This is defined for any time value analogously to the point of construction The resulting direction vector has the correct orientation and a somewhat arbitrary magnitude Combining point of and direction of constructions yields the equation for a tangent line as illustrated in Figure 26 If you know a slope and you want to find a point on a curve where the tangent line has that slope the directiontime operator inverts the direction of operation Given a direction vector and a path directiontime pair expression of path primary returns a numeric value that gives the first time t when the path has the indicated direction If there is no such time the result is 1 For example if a is the path drawn as a thin curve in Figure 25 directiontime 1 1 of a returns 0 2084 There is also an predefined macro directionpoint pair expression of path primary that finds the first point on a path where a given direction is achieved The directionpoint macro produces an error message if the direction does not occur on the path Operators arclength and arctime of r
137. urrentwindow screen_rows and screen_cols which depend on METAFONT s ability to display images on the computer screen In addition pixels_per_inch is irrelevant since MetaPost uses fixed units of PostScript points The reason why some macros and internal variables are not meaningful in MetaPost is that METAFONT primitive commands cull display openwindow numspecial and totalweight are not implemented in MetaPost Also not implemented are a number of internal variables as well as 12Command line syntax is system dependent Quotes are needed on most Unix systems to protect special characters like amp B METAPOST VERSUS METAFONT Defined in the mfplain package beginchar blacker capsule def change width define blacker pixels define corrected pixels define good x pixels define good y pixels define horizontal corrected pixels define pixels define whole blacker pixels define whole pixels define whole vertical blacker pixels define whole vertical pixels endchar extra beginchar extra endchar extra setup font coding scheme font extra space font identifier font normal shrink font normal space font normal stretch font quad font size font slant font x height italcorr labelfont makebox makegrid maketicks mode def mode setup Oo correction proofrule proofrulethickness rulepen smode Defined as no ops in the mfplain package cullit currenttransform gfcorne
138. version gt 1 0 message time has flown by fi fi prints mp 0 9 Incidentally gt does a simple ASCII comparison of strings that works here because of our particular version numbering until and unless MetaPost reaches version 10 The version number is also included in the Creator comment in the PostScript output This document introduces the MetaPost language beginning with the features that are easiest to use and most important for simple applications The first few sections describe the language as it appears to the novice user with key parameters at their default values Some features described in these sections are part of a predefined macro package called Plain Later sections summarize the complete language and distinguish between primitives and preloaded macros from the Plain macro package Since much of the language is identical to Knuth s METAFONT the appendix gives a detailed comparison so that advanced users can learn more about MetaPost by reading The META FONTbook 4 The MetaPost home page is http tug org metapost It has links to much additional in formation including many articles that have been written about MetaPost For general help try the metapost tug org mailing list you can subscribe to this list at http tug org mailman listinfo metapost The development is currently hosted at Sarovar visit http www sarovar org projects metapost for the current development team members sources and much else
139. xpression balanced tokens alternatives loop loop header loop text endf or loop header for symbolic token progression for symbolic token for list forsuffixes symbolic token suffix list forever progression numeric expression upto numeric expression numeric expression downto numeric expression numeric expression step numeric expression until numeric expression for list expression for list expression suffix list suffix suffix list suffix Figure 61 The syntax for conditionals and loops 83 B METAPOST VERSUS METAFONT 84 B MetaPost Versus METAFONT Since the METRFONT and MetaPost languages have so much in common expert users of METRFONT will want to skip most of the explanations in this document and concentrate on concepts that are unique to MetaPost The comparisons in this appendix are intended to help experts that are familiar with The METAFONTbook as well as other users that want to benefit from Knuth s more detailed explanations 4 Since METAFONT is intended for making TEX fonts it has a number of primitives for generating the tfm files that TEX needs for character dimensions spacing information ligatures and kerning MetaPost can also be used for generating fonts and it also has METRFONT s primitives for making tfm files These are listed in Table 13 Explanations can be found in the METAFONT documentation 4 7 commands charlist extensi

A User`s Manual for MetaPost

Contents

Download Pdf Manuals

Related Search

Related Contents