Debian Codegraph @

texmf-dist/doc/metapost/base/source-manual/mpman-app-refman.tex

raw
1 \svnInfo $Id$
2 \section{Reference Manual}
3 \label{refman}
4
5 \begingroup
6 \renewcommand\topfraction{1.0}% Allow *lots* of figures and tables.
7 \renewcommand\textfraction{0.0}
8 \setcounter{topnumber}{10}
9 \setcounter{totalnumber}{10}
10
11 \subsection{The MetaPost Language}
12 \label{refman:lang}
13
14 Tables \ref{ivartab}--\ref{pseudotab} summarize the built-in features of
15 Plain MetaPost. Features from the Plain\index{Plain macros} macro
16 package are marked by \pl\ symbols. The distinction between primitives
17 and plain macros can be ignored by the casual user.
18
19 The tables in this appendix give the name of each feature, the page
20 number where it is explained, and a short description. A few features
21 are not explained elsewhere and have no page number listed. These
22 features exist primarily for compatibility with \MF\index{metafont?\MF}
23 and are intended to be self-explanatory. Certain other features from
24 \MF\ are omitted entirely because they are of limited interest to the
25 MetaPost users and/or would require long explanations. All of these are
26 documented in {\sl The \MF book} \cite{kn:c} as explained in
27 Appendix~\ref{MPvsMF}.
28
29 Tables~\ref{ivartab} and~\ref{isvartab} list internal variables that
30 take on numeric and string values. Table~\ref{pvartab} lists predefined
31 variables of other types. Table~\ref{consttab} lists predefined
32 constants. Some of these are implemented as variables whose values are
33 intended to be left unchanged.
34
35 Table~\ref{optab} summarizes MetaPost operators and lists
36 the possible argument and result types for each one. A ``--'' entry for
37 the left argument indicates a unary operator; ``--'' entries for both
38 arguments indicate a nullary operator. Operators that take suffix
39 parameters are not listed in this table because they are treated as
40 ``function-like macros''.
41
42 The last two tables are Table~\ref{cmdtab} for commands and
43 Table~\ref{pseudotab} macros that behave like functions or procedures.
44 Such macros take parenthesized argument lists and/or suffix parameters,
45 returning either a value whose type is listed in the table, or nothing.
46 The latter case is for macros that behave like procedures. Their return
47 values are listed as ``--''.
48
49 The figures in this appendix present the syntax of the MetaPost language
50 starting with expressions in Figures \ref{syexpr1}--\ref{sypseudo}.
51 Although the productions sometimes specify types for expressions, primaries,
52 secondaries, and tertiaries, no attempt is made to give separate syntaxes
53 for \tdescr{numeric expression}, \tdescr{pair expression}, etc.
54 The simplicity of the productions in Figure~\ref{sytypexpr} is due to this
55 lack of type information. Type information
56 can be found in Tables \ref{ivartab}--\ref{pseudotab}.
57
58 Figures \ref{syprog}, \ref{sycmds1} and~\ref{sycmds2} give the syntax
59 for MetaPost programs, including statements and commands. They do not
60 mention loops\index{loops} and {\tt if}\index{if?\texttt{if}} tests
61 because these constructions do not behave like statements. The syntax
62 given in Figures \ref{syexpr1}--\ref{sycondloop} applies to the result
63 of expanding all conditionals and loops. Conditionals and loops do have
64 a syntax, but they deal with almost arbitrary sequences of tokens.
65 Figure~\ref{sycondloop} specifies conditionals in terms of
66 \tdescr{balanced tokens} and loops in terms of \tdescr{loop text}, where
67 \tdescr{balanced tokens} is any sequence of tokens balanced with respect
68 to {\tt if} and {\tt fi}, and \tdescr{loop text} is a sequence of tokens
69 balanced with respect to {\tt for}, {\tt forsuffixes}, {\tt forever},
70 and {\tt endfor}.
71
72 \begin{table}[htp]
73 \caption{Internal variables with numeric values}
74 $$\begin{tabular}{|l|r|l|}
75 \hline
76 \multicolumn1{|c}{Name}& \multicolumn1{|c}{Page}& \multicolumn1{|c|}{Explanation}\\
77 \hline
78 \hline
79 \pl\tt ahangle& \pageref{Dahangle}&
80 Angle for arrowheads in degrees (default: 45)\\\hline
81 \pl\tt ahlength& \pageref{Dahlength}&
82 Size of arrowheads (default: 4{\tt bp})\\\hline
83 \pl\tt bboxmargin& \pageref{Dbbmargin}&
84 Extra space allowed by {\tt bbox} (default 2{\tt bp})\\\hline
85 \tt charcode& \pageref{Dcharcode}&
86 The number of the current figure\\\hline
87 \tt day& \pageref{Dday}&
88 The current day of the month\\\hline
89 \tt defaultcolormodel& \pageref{Ddefaultcolormodel}&
90 The initial color model (default: 5, rgb)\\\hline
91 \pl\tt defaultpen& \pageref{Ddefaultpen}&
92 Numeric index used by {\tt pickup} to select default pen\\\hline
93 \pl\tt defaultscale& \pageref{Ddfscale}&
94 Font scale factor for label strings (default 1)\\\hline
95 \pl\tt dotlabeldiam& \pageref{Ddotlabdiam}&
96 Diameter of the dot drawn by \verb|dotlabel| (default 3{\tt bp})\\\hline
97 \tt hour& \pageref{Dhour}&
98 The hour of the day this job started\\\hline
99 \tt hppp& \pageref{Dhppp}&
100 The number of horizontal points per pixel for bitmap output\\\hline
101 \pl\tt labeloffset& \pageref{Dlaboff}&
102 Offset distance for labels (default 3{\tt bp})\\\hline
103 \tt linecap& \pageref{Dlinecap}&
104 0 for butt, 1 for round, 2 for square\\\hline
105 \tt linejoin& \pageref{Dlinejoin}&
106 0 for mitered, 1 for round, 2 for beveled\\\hline
107 \tt minute& \pageref{Dminute}&
108 The minute of the hour this job started\\\hline
109 \tt miterlimit& \pageref{Dmiterlim}&
110 Controls miter length as in PostScript\\\hline
111 \tt month& \pageref{Dmonth}&
112 The current month (e.g, 3 $\equiv$ March)\\\hline
113 \tt mpprocset& \pageref{Dmpprocset}&
114 Create a PostScript dictionary of command abbreviations\\\hline
115 \tt numberprecision&\pageref{Dnumberprecision}&
116 Arithmetic precision in \texttt{binary} and \texttt{decimal} mode\\\hline
117 \tt pausing& --&
118 ${}>0$ to display lines on the terminal before they are read\\\hline
119 \tt prologues& \pageref{Dprologues}&
120 ${}>0$ to output conforming PostScript using built-in fonts\\\hline
121 \tt restoreclipcolor& --&
122 Restore the graphics state after clip operations (default: 1)\\\hline
123 \tt showstopping& --&
124 ${}>0$ to stop after each {\tt show} command\\\hline
125 \tt time& \pageref{Dtime}&
126 The number of minutes past midnight when this job started\\\hline
127 \tt tracingcapsules& \pageref{Dtcapsules}&
128 ${}>0$ to show capsules too\\\hline
129 \tt tracingchoices& \pageref{Dtchoices}&
130 ${}>0$ to show the control points chosen for paths\\\hline
131 \tt tracingcommands& \pageref{Dtcommands}&
132 ${}>0$ to show commands and operations as they are performed\\\hline
133 \tt tracingequations& \pageref{Dtequations}&
134 ${}>0$ to show each variable when it becomes known\\\hline
135 \tt tracinglostchars& \pageref{Dtlostchars}&
136 ${}>0$ to show characters that aren't {\tt infont}\\\hline
137 \tt tracingmacros& \pageref{Dtmacros}&
138 ${}>0$ to show macros before they are expanded\\\hline
139 \tt tracingonline& \pageref{Dtonline}&
140 ${}>0$ to show long diagnostics on the terminal\\\hline
141 \tt tracingoutput& \pageref{Dtoutput}&
142 ${}>0$ to show digitized edges as they are output\\\hline
143 \tt tracingrestores& \pageref{Dtrestores}&
144 ${}>0$ to show when a variable or internal is restored\\\hline
145 \tt tracingspecs& \pageref{Dtspecs}&
146 ${}>0$ to show path subdivision when using a polygonal a pen\\\hline
147 \tt tracingstats& \pageref{Dtstats}&
148 ${}>0$ to show memory usage at end of job\\\hline
149 \tt tracingtitles& --&
150 ${}>0$ to show titles online when they appear\\\hline
151 \tt troffmode& \pageref{Dtroffmode}&
152 Set to~1 if a {\tt -troff} or {\tt -T} option was given\\\hline
153 \tt truecorners& \pageref{Dtruecorn}&
154 ${}>0$ to make {\tt llcorner} etc. ignore {\tt setbounds}\\\hline
155 \tt vppp& \pageref{Dvppp}&
156 The number of vertical points per pixel for bitmap output\\\hline
157 \tt warningcheck& \pageref{Dwarncheck}&
158 Controls error message when variable value is large\\\hline
159 \tt year& \pageref{Dyear}&
160 The current year (e.g., 1992)\\\hline
161 \end{tabular}
162 $$
163 \label{ivartab}%
164 \index{pausing?\texttt{pausing}}\index{showstopping?\texttt{showstopping}}%
165 \index{tracingtitles?\texttt{tracingtitles}}
166 \end{table}
167
168
169 \begin{table}[htp]
170 \caption{Internal string variables}
171 $$\begin{tabular}{|l|r|l|}
172 \hline
173 \multicolumn1{|c}{Name}& \multicolumn1{|c}{Page}& \multicolumn1{|c|}{Explanation}\\
174 \hline
175 \hline
176 \tt jobname& --&
177 The name of this job\\\hline
178 \tt numbersystem& \pageref{Dnumbersystem}&
179 Arithmetic mode as given on the command-line\\\hline
180 \tt outputfilename& \pageref{Doutputfilename}&
181 Name of the output file last written\\\hline
182 \tt outputformat& \pageref{Doutputformat}&
183 Output backend to be used (default: ``eps'')\\\hline
184 \tt outputformatoptions& \pageref{Doutputformatoptions}&
185 Configure PNG output backend (default: ``'')\\\hline
186 \tt outputtemplate& \pageref{Doutputtemplate}&
187 Output filename template (default: ``\%j.\%c'')\\\hline
188 \end{tabular}
189 $$
190 \label{isvartab}
191 \index{jobname?\texttt{jobname}}
192 \end{table}
193
194
195 \begin{table}[htp]
196 \caption{Other Predefined Variables}
197 $$\begin{tabular}{|l|l|r|l|}
198 \hline
199 \multicolumn1{|c}{Name}& \multicolumn1{|c}{Type}& \multicolumn1{|c}{Page}&
200 \multicolumn1{|c|}{Explanation}\\
201 \hline
202 \hline
203 \pl\tt background& color& \pageref{Dbground}&
204 Color for {\tt unfill} and {\tt undraw} (usually white)\\\hline
205 \pl\tt currentpen& pen& \pageref{Dcurpen}&
206 Last pen picked up (for use by the {\tt draw} command)\\\hline
207 \pl\tt currentpicture& picture& \pageref{Dcurpic}&
208 Accumulate results of {\tt draw} and {\tt fill} commands\\\hline
209 \pl\tt cuttings& path& \pageref{Dcuttings}&
210 Subpath cut off by last {\tt cutbefore} or {\tt cutafter}\\\hline
211 \pl\tt defaultfont& string& \pageref{Ddffont}&
212 Font used by label commands for typesetting strings\\\hline
213 \pl\tt extra\_beginfig& string& \pageref{Dxbfig}&
214 Commands for {\tt beginfig} to scan\\\hline
215 \pl\tt extra\_endfig& string& \pageref{Dxefig}&
216 Commands for {\tt endfig} to scan\\\hline
217 \end{tabular}
218 $$
219 \label{pvartab}
220 \end{table}
221
222
223 \begin{table}[htp]
224 \caption{Predefined Constants}
225 $$\begin{tabular}{|l|l|r|l|}
226 \hline
227 \multicolumn1{|c}{Name}& \multicolumn1{|c}{Type}& \multicolumn1{|c}{Page}&
228 \multicolumn1{|c|}{Explanation}\\
229 \hline
230 \hline
231 \pl\tt beveled& numeric& \pageref{Dbvled}&
232 {\tt linejoin} value for beveled joins [2]\\\hline
233 \pl\tt black& color& \pageref{Dblack}&
234 Equivalent to {\tt (0,0,0)}\\\hline
235 \pl\tt blue& color& \pageref{Dblue}&
236 Equivalent to {\tt (0,0,1)}\\\hline
237 \pl\tt bp& numeric& \pageref{Dbp}&
238 One PostScript point in {\tt bp} units [1]\\\hline
239 \pl\tt butt& numeric& \pageref{Dbutt}&
240 {\tt linecap} value for butt end caps [0]\\\hline
241 \pl\tt cc& numeric& \pageref{Dcc}&
242 One cicero in {\tt bp} units [12.79213]\\\hline
243 \pl\tt cm& numeric& \pageref{Dcm}&
244 One centimeter in {\tt bp} units [28.34645]\\\hline
245 \pl\tt dd& numeric& \pageref{Ddd}&
246 One didot point in {\tt bp} units [1.06601]\\\hline
247 \pl\tt ditto& string& --&
248 The {\tt "} character as a string of length 1\\\hline
249 \pl\tt down& pair& \pageref{Ddown}&
250 Downward direction vector $(0,-1)$\\\hline
251 \pl\tt epsilon& numeric& \pageref{Depsilon}&
252 Smallest positive MetaPost number [$1\over65536$]\\\hline
253 \pl\tt evenly& picture& \pageref{Devenly}&
254 Dash pattern for equal length dashes\\\hline
255 \pl\tt EOF& string& \pageref{Deof}&
256 Single null character\\\hline
257 \tt false& boolean& \pageref{Dfalse}&
258 The boolean value {\it false\/}\\\hline
259 \pl\tt fullcircle& path& \pageref{Dfcirc}&
260 Circle of diameter 1 centered on $(0,0)$\\\hline
261 \pl\tt green& color& \pageref{Dgreen}&
262 Equivalent to {\tt (0,1,0)}\\\hline
263 \pl\tt halfcircle& path& \pageref{Dhcirc}&
264 Upper half of a circle of diameter 1\\\hline
265 \pl\tt identity& transform& \pageref{Dident}&
266 Identity transformation\\\hline
267 \pl\tt in& numeric& \pageref{Din}&
268 One inch in {\tt bp} units [72]\\\hline
269 \pl\tt infinity& numeric& \pageref{Dinf}&
270 Large positive value [4095.99998]\\\hline
271 \pl\tt left& pair& \pageref{Dleft}&
272 Leftward direction $(-1,0)$\\\hline
273 \pl\tt mitered& numeric& \pageref{Dmitred}&
274 {\tt linejoin} value for mitered joins [0]\\\hline
275 \pl\tt mm& numeric& \pageref{Dmm}&
276 One millimeter in {\tt bp} units [2.83464]\\\hline
277 \tt mpversion& string& \pageref{Dmpversion}&
278 MetaPost version number\\\hline
279 \tt nullpen& pen& \pageref{Dnlpen}&
280 Empty pen\\\hline
281 \tt nullpicture& picture& \pageref{Dnlpic}&
282 Empty picture\\\hline
283 \pl\tt origin& pair& \pageref{Dorigin}&
284 The pair $(0,0)$\\\hline
285 \pl\tt pc& numeric& \pageref{Dpc}&
286 One pica in {\tt bp} units [11.95517]\\\hline
287 \tt pencircle& pen& \pageref{Dpncirc}&
288 Circular pen of diameter 1\\\hline
289 \pl\tt pensquare& pen& \pageref{Dpnsqr}&
290 Square pen of height 1 and width 1\\\hline
291 \pl\tt pt& numeric& \pageref{Dpt}&
292 One printer's point in {\tt bp} units [0.99626]\\\hline
293 \pl\tt quartercircle& path& \pageref{Dqcirc}&
294 First quadrant of a circle of diameter 1\\\hline
295 \pl\tt red& color& \pageref{Dred}&
296 Equivalent to {\tt (1,0,0)}\\\hline
297 \pl\tt right& pair& \pageref{Dright}&
298 Rightward direction $(1,0)$\\\hline
299 \pl\tt rounded& numeric& \pageref{Drnded}&
300 {\tt linecap} and {\tt linejoin} value for round joins\\
301 \tt & & &
302 and end caps [1]\\\hline
303 \pl\tt squared& numeric& \pageref{Dsqred}&
304 {\tt linecap} value for square end caps [2]\\\hline
305 \tt true& boolean& \pageref{Dtrue}&
306 The boolean value {\tt true}\\\hline
307 \pl\tt unitsquare& path& \pageref{Dunitsqr}&
308 The path \verb|(0,0)--(1,0)--(1,1)--(0,1)--cycle|\\\hline
309 \pl\tt up& pair& \pageref{Dup}&
310 Upward direction $(0,1)$\\\hline
311 \pl\tt white& color& \pageref{Dwhite}&
312 Equivalent to {\tt (1,1,1)}\\\hline
313 \pl\tt withdots& picture& \pageref{Dwdots}&
314 Dash pattern that produces dotted lines\\\hline
315 \end{tabular}
316 $$
317 \label{consttab}%
318 \index{ditto?\texttt{ditto}}%
319 \end{table}
320
321
322 \clearpage
323 \LTXtable{\textwidth}{mpman-app-optab}
324
325 \begin{table}[htp]
326 \caption{Commands}
327 $$\begin{tabular}{|l|r|l|}
328 \hline
329 \multicolumn1{|c}{Name}& \multicolumn1{|c}{Page}& \multicolumn1{|c|}{Explanation}\\
330 \hline
331 \hline
332 \tt \verb|addto|& \pageref{sydraw}&
333 Low-level command for drawing and filling\\\hline
334 \tt \verb|clip|& \pageref{Dclip}&
335 Applies a clipping path to a picture\\\hline
336 \tt \verb|closefrom|& \pageref{Dclosefrom}&
337 Close a file opened by {\tt readfrom}\\\hline
338 \pl\tt \verb|cutdraw|& \pageref{Dctdraw}&
339 Draw with butt end caps\\\hline
340 \tt \verb|dashed|& \pageref{Ddashed}&
341 Apply dash pattern to drawing command\\\hline
342 \pl\tt \verb|draw|& \pageref{curves}&
343 Draw a line or a picture\\\hline
344 \pl\tt \verb|drawarrow|& \pageref{Ddrwarr}&
345 Draw a line with an arrowhead at the end\\\hline
346 \pl\tt \verb|drawdblarrow|& \pageref{Ddrwdar}&
347 Draw a line with arrowheads at both ends\\\hline
348 \tt \verb|errhelp|& \pageref{Derrhelp}&
349 Declare help message for interactive mode\\\hline
350 \tt \verb|errmessage|& \pageref{Derrmessage}&
351 Show error message on the terminal and enter interactive
352 mode\\\hline
353 \tt \verb|filenametemplate|& \pageref{Dfilenametemplate}&
354 Set output file name pattern (deprecated, see
355 \verb|outputtemplate|)\\\hline
356 \pl\tt \verb|fill|& \pageref{Dfill}&
357 Fill inside a cyclic path\\\hline
358 \pl\tt \verb|filldraw|& \pageref{Dfildrw}&
359 Draw a cyclic path and fill inside it\\\hline
360 \tt \verb|fontmapfile|& \pageref{Dfontmapfile}&
361 Read font map entries from file\\\hline
362 \tt \verb|fontmapline|& \pageref{Dfontmapline}&
363 Declare a font map entry\\\hline
364 \tt \verb|interim|& \pageref{Dinterm}&
365 Make a local change to an internal variable\\\hline
366 \tt \verb|let|& --&
367 Assign one symbolic token the meaning of another\\\hline
368 \pl\tt \verb|loggingall|& \pageref{Dlogall}&
369 Turn on all tracing (log file only)\\\hline
370 \tt \verb|message|& \pageref{Dmessage}&
371 Show message string on the terminal\\\hline
372 \tt \verb|newinternal|& \pageref{Dnewint}&
373 Declare new internal variables\\\hline
374 \pl\tt \verb|pickup|& \pageref{Dpickup}&
375 Specify new pen for line drawing\\\hline
376 \tt \verb|save|& \pageref{Dsave}&
377 Make variables local\\\hline
378 \tt \verb|setbounds|& \pageref{Dsetbnd}&
379 Make a picture lie about its bounding box\\\hline
380 \tt \verb|shipout|& \pageref{Dship}&
381 Low-level command to output a figure\\\hline
382 \tt \verb|show|& \pageref{Dshow}&
383 Print out expressions symbolically\\\hline
384 \tt \verb|showdependencies|& \pageref{Dshdep}&
385 Print out all unsolved equations\\\hline
386 \tt \verb|showtoken|& \pageref{Dshtok}&
387 Print an explanation of what a token is\\\hline
388 \tt \verb|showvariable|& \pageref{Dshvar}&
389 Print variables symbolically\\\hline
390 \tt \verb|special|& \pageref{Dspecl}&
391 Print a string directly in the PostScript output file\\\hline
392 \pl\tt \verb|tracingall|& \pageref{Dtall}&
393 Turn on all tracing\\\hline
394 \pl\tt \verb|tracingnone|& \pageref{Dtnone}&
395 Turn off all tracing\\\hline
396 \pl\tt \verb|undraw|& \pageref{Dundraw}&
397 Erase a line or a picture\\\hline
398 \pl\tt \verb|unfill|& \pageref{Dunfill}&
399 Erase inside a cyclic path\\\hline
400 \pl\tt \verb|unfilldraw|& \pageref{Dunfdrw}&
401 Erase a cyclic path and its inside\\\hline
402 \tt \verb|withcmykcolor|& \pageref{Dwithcmykcolor}&
403 Apply CMYK color to drawing command\\\hline
404 \tt \verb|withcolor|& \pageref{Dwithcolor}&
405 Apply generic color specification to drawing command\\\hline
406 \tt \verb|withgreyscale|& \pageref{Dwithgreyscale}&
407 Apply greyscale color to drawing command\\\hline
408 \tt \verb|withoutcolor|& \pageref{Dwithoutcolor}&
409 Don't apply any color specification to drawing command\\\hline
410 \tt \verb|withpen|& \pageref{sec.pens}&
411 Apply pen to drawing operation\\\hline
412 \tt \verb|withpostscript|& \pageref{Dwithpost}&
413 End raw PostScript code\\\hline
414 \tt \verb|withprescript|& \pageref{Dwithpre}&
415 Begin raw PostScript code\\\hline
416 \tt \verb|withrgbcolor|& \pageref{Dwithrgbcolor}&
417 Apply RGB color to drawing command\\\hline
418 \tt \verb|write to|& \pageref{Dwrite}&
419 Write string to file\\\hline
420 \end{tabular}
421 $$
422 \index{let?\texttt{let}}%
423 \label{cmdtab}
424 \end{table}
425
426
427 \begin{table}[htp]
428 \caption{Function-Like Macros}
429 $$\begin{tabular}{|l|l|l|r|l|}
430 \hline
431 \multicolumn1{|c}{Name}& \multicolumn1{|c}{Arguments}&
432 \multicolumn1{|c}{Result}& \multicolumn1{|c}{Page}&
433 \multicolumn1{|c|}{Explanation}\\
434 \hline
435 \hline
436 \pl\tt \verb|buildcycle|& list of paths& path& \pageref{buildcy}&
437 Build a cyclic path\\\hline
438 \pl\tt \verb|dashpattern|& on/off distances& picture& \pageref{Ddshpat}&
439 Create a pattern for dashed lines\\\hline
440 \pl\tt \verb|decr|& numeric variable& numeric& \pageref{Dincr}&
441 Decrement and return new value\\\hline
442 \pl\tt \verb|dotlabel|& suffix, picture, pair& --& \pageref{Ddotlab}&
443 Mark point and draw picture nearby\\\hline
444 \pl\tt \verb|dotlabel|& suffix, string, pair& --& \pageref{Ddotlab}&
445 Mark point and place text nearby\\\hline
446 \pl\tt \verb|dotlabels|& suffix, point numbers& --& \pageref{Ddotlbs}&
447 Mark {\tt z} points with their numbers\\\hline
448 \pl\tt \verb|drawdot|& pair& --& \pageref{Ddrawdot}&
449 Draw a dot at the given point\\\hline
450 \pl\tt \verb|drawoptions|& drawing options& --& \pageref{Ddropts}&
451 Set options for drawing commands\\\hline
452 \pl\tt \verb|image|& string& picture& \pageref{Dimage}&
453 Return picture from text\\\hline
454 \pl\tt \verb|incr|& numeric variable& numeric& \pageref{Dincr}&
455 Increment and return new value\\\hline
456 \pl\tt \verb|label|& suffix, picture, pair& --& \pageref{Dlabel}&
457 Draw picture near given point\\\hline
458 \pl\tt \verb|label|& suffix, string, pair& --& \pageref{Dlabel}&
459 Place text near given point\\\hline
460 \pl\tt \verb|labels|& suffix, point numbers& --& \pageref{Dlabels}&
461 Draw {\tt z} point numbers; no dots\\\hline
462 \pl\tt \verb|max|& list of numerics& numeric& --&
463 Find the maximum\\\hline
464 \pl\tt \verb|max|& list of strings& string& --&
465 Find the lexicographically last string\\\hline
466 \pl\tt \verb|min|& list of numerics& numeric& --&
467 Find the minimum\\\hline
468 \pl\tt \verb|min|& list of strings& string& --&
469 Find the lexicographically first string\\\hline
470 \pl\tt \verb|thelabel|& suffix, picture, pair& picture& \pageref{Dthelab}&
471 Picture shifted as if to label a point\\\hline
472 \pl\tt \verb|thelabel|& suffix, string, pair& picture& \pageref{Dthelab}&
473 Text positioned as if to label a point\\\hline
474 \pl\tt \verb|z|& suffix& pair& \pageref{Dzconv}&
475 The pair $({\tt x}\descr{suffix},{\tt y}\descr{suffix})$\\\hline
476 \end{tabular}
477 $$
478 \index{min?\texttt{min}}\index{max?\texttt{max}}%
479 \label{pseudotab}
480 \end{table}
481
482 \clearpage
483
484 \begin{figure}[htp]
485 \begin{ctabbing}
486 $\tt \descr{atom} \rightarrow \descr{variable} \;|\; \descr{argument}$\\
487 $\tt \qquad \;|\; \descr{number or fraction}$\\
488 $\tt \qquad \;|\; \descr{internal variable}$\\
489 $\tt \qquad \;|\; \hbox{\tt (}\descr{expression}\hbox{\tt )}$\\
490 $\tt \qquad \;|\; begingroup \descr{statement list} \descr{expression} endgroup$\\
491 $\tt \qquad \;|\; \descr{nullary op}$\\
492 $\tt \qquad \;|\; btex \descr{typesetting commands} etex$\\
493 $\tt \qquad \;|\; \descr{pseudo function}$\\
494 $\tt \descr{primary} \rightarrow \descr{atom}$\\
495 $\tt \qquad \;|\; \hbox{\tt (}\descr{numeric expression}\hbox{\tt ,} \descr{numeric expression}\hbox{\tt )}$\\
496 $\tt \qquad \;|\; \hbox{\tt (}\descr{numeric expression}\hbox{\tt ,} \descr{numeric expression}\hbox{\tt ,} \descr{numeric expression}\hbox{\tt )}$\\
497 $\tt \qquad \;|\; \descr{of operator} \descr{expression} of \descr{primary}$\\
498 $\tt \qquad \;|\; \descr{unary op} \descr{primary}$\\
499 $\tt \qquad \;|\; str \descr{suffix}$\\
500 $\tt \qquad \;|\; z \descr{suffix}$\\
501 $\tt \qquad \;|\; \descr{numeric atom}\hbox{\tt [}\descr{expression}\hbox{\tt ,}\descr{expression}\hbox{\tt ]}$\\
502 $\tt \qquad \;|\; \descr{scalar multiplication op} \descr{primary}$\\
503 $\tt \descr{secondary} \rightarrow \descr{primary}$\\
504 $\tt \qquad \;|\; \descr{secondary} \descr{primary binop} \descr{primary}$\\
505 $\tt \qquad \;|\; \descr{secondary} \descr{transformer}$\\
506 $\tt \descr{tertiary} \rightarrow \descr{secondary}$\\
507 $\tt \qquad \;|\; \descr{tertiary} \descr{secondary binop} \descr{secondary}$\\
508 $\tt \descr{subexpression} \rightarrow \descr{tertiary}$\\
509 $\tt \qquad \;|\; \descr{path expression} \descr{path join} \descr{path knot}$\\
510 $\tt \descr{expression} \rightarrow \descr{subexpression}$\\
511 $\tt \qquad \;|\; \descr{expression} \descr{tertiary binop} \descr{tertiary}$\\
512 $\tt \qquad \;|\; \descr{path subexpression} \descr{direction specifier}$\\
513 $\tt \qquad \;|\; \descr{path subexpression} \descr{path join} cycle$\\
514 $\tt $\\
515 $\tt \descr{path knot} \rightarrow \descr{tertiary}$\\
516 $\tt \descr{path join} \rightarrow \verb|--|$\\
517 $\tt \qquad \;|\; \descr{direction specifier} \descr{basic path join} \descr{direction specifier}$\\
518 $\tt \descr{direction specifier} \rightarrow \descr{empty}$\\
519 $\tt \qquad \;|\; \verb|{|curl \descr{numeric expression}\verb|}|$\\
520 $\tt \qquad \;|\; \verb|{|\descr{pair expression}\verb|}|$\\
521 $\tt \qquad \;|\; \verb|{|\descr{numeric expression}\hbox{\tt ,}\descr{numeric expression}\verb|}|$\\
522 $\tt \descr{basic path join} \rightarrow \hbox{\tt ..} \;|\; \hbox{\tt ...} \;|\; \hbox{\tt ..}\descr{tension}\hbox{\tt ..} \;|\; \hbox{\tt ..}\descr{controls}\hbox{\tt ..}$\\
523 $\tt \descr{tension} \rightarrow tension \descr{numeric primary}$\\
524 $\tt \qquad \;|\; tension \descr{numeric primary} and \descr{numeric primary}$\\
525 $\tt \descr{controls} \rightarrow controls \descr{pair primary}$\\
526 $\tt \qquad \;|\; controls \descr{pair primary} and \descr{pair primary}$\\
527 $\tt $\\
528 $\tt \descr{argument} \rightarrow \descr{symbolic token}$\\
529 $\tt \descr{number or fraction} \rightarrow \descr{number}\hbox{\tt /}\descr{number}$\\
530 $\tt \qquad \;|\; \descr{number not followed by `\hbox{\tt /}\tdescr{number}'}$\\
531 $\tt \descr{scalar multiplication op} \rightarrow + \;|\; -$\\
532 $\tt \qquad \;|\; \descr{`\tdescr{number or fraction}' not followed by `\tdescr{add op}\tdescr{number}'}$
533 \end{ctabbing}
534 \caption{Part 1 of the syntax for expressions}
535 \index{expression?\tdescr{expression}}\index{nullary op?\tdescr{nullary op}}\index{of operator?\tdescr{of operator}}%
536 \index{path knot?\tdescr{path knot}}\index{primary?\tdescr{primary}}\index{primary binop?\tdescr{primary binop}}%
537 \index{secondary?\tdescr{secondary}}\index{secondary binop?\tdescr{secondary binop}}\index{suffix?\tdescr{suffix}}%
538 \index{tertiary?\tdescr{tertiary}}\index{tertiary binop?\tdescr{tertiary binop}}\index{unary op?\tdescr{unary op}}%
539 \label{syexpr1}
540 \end{figure}
541
542 \begin{figure}[htp]
543 \begin{ctabbing}
544 $\tt \descr{transformer} \rightarrow rotated \descr{numeric primary}$\\
545 $\tt \qquad \;|\; scaled \descr{numeric primary}$\\
546 $\tt \qquad \;|\; shifted \descr{pair primary}$\\
547 $\tt \qquad \;|\; slanted \descr{numeric primary}$\\
548 $\tt \qquad \;|\; transformed \descr{transform primary}$\\
549 $\tt \qquad \;|\; xscaled \descr{numeric primary}$\\
550 $\tt \qquad \;|\; yscaled \descr{numeric primary}$\\
551 $\tt \qquad \;|\; zscaled \descr{pair primary}$\\
552 $\tt \qquad \;|\; reflectedabout\hbox{\tt (}\descr{pair expression}\hbox{\tt ,} \descr{pair expression}\hbox{\tt )}$\\
553 $\tt \qquad \;|\; rotatedaround\hbox{\tt (}\descr{pair expression}\hbox{\tt ,} \descr{numeric expression}\hbox{\tt )}$\\
554 $\tt $\\
555 $\tt \descr{nullary op} \rightarrow false \;|\; normaldeviate \;|\; nullpen \;|\; nullpicture \;|\; pencircle$\\
556 $\tt \qquad \;|\; true \;|\; whatever$\\
557 $\tt \descr{unary op} \rightarrow \descr{type}$\\
558 $\tt \qquad \;|\; abs \;|\; angle \;|\; arclength \;|\; ASCII \;|\; bbox \;|\; blackpart \;|\; bluepart \;|\; bot \;|\; bounded$\\
559 $\tt \qquad \;|\; ceiling \;|\; center \;|\; char \;|\; clipped \;|\; colormodel \;|\; cosd \;|\; cyanpart \;|\; cycle$\\
560 $\tt \qquad \;|\; dashpart \;|\; decimal \;|\; dir \;|\; floor \;|\; filled \;|\; fontpart \;|\; fontsize$\\
561 $\tt \qquad \;|\; greenpart \;|\; greypart \;|\; hex \;|\; interval\_get\_left\_endpoint \;|\; interval\_get\_right\_endpoint$\\
562 $\tt \qquad \;|\; interval\_set \;|\; inverse \;|\; known \;|\; length \;|\; lft \;|\; llcorner$\\
563 $\tt \qquad \;|\; lrcorner\;|\; magentapart \;|\; makepath \;|\; makepen \;|\; mexp \;|\; mlog \;|\; not \;|\; oct \;|\; odd$\\
564 $\tt \qquad \;|\; pathpart \;|\; penpart \;|\; readfrom \;|\; redpart \;|\; reverse \;|\; round \;|\; rt \;|\; sind \;|\; sqrt$\\
565 $\tt \qquad \;|\; stroked \;|\; textpart \;|\; textual \;|\; top \;|\; ulcorner$\\
566 $\tt \qquad \;|\; uniformdeviate \;|\; unitvector \;|\; unknown \;|\; urcorner \;|\; xpart \;|\; xxpart$\\
567 $\tt \qquad \;|\; xypart \;|\; yellowpart \;|\; ypart \;|\; yxpart \;|\; yypart$\\
568 $\tt \descr{type} \rightarrow boolean \;|\; cmykcolor \;|\; color \;|\; numeric \;|\; pair$\\
569 $\tt \qquad \;|\; path \;|\; pen \;|\; picture \;|\; rgbcolor \;|\; string \;|\; transform$\\
570 $\tt \descr{internal type} \rightarrow numeric \;|\; string$\\
571 $\tt \descr{primary binop} \rightarrow \hbox{\tt *} \;|\; \hbox{\tt /} \;|\; \hbox{\tt **} \;|\; and$\\
572 $\tt \qquad \;|\; dotprod \;|\; div \;|\; infont \;|\; mod$\\
573 $\tt \descr{secondary binop} \rightarrow + \;|\; - \;|\; ++ \;|\; +-+ \;|\; or$\\
574 $\tt \qquad \;|\; intersectionpoint \;|\; intersectiontimes$\\
575 $\tt \descr{tertiary binop} \rightarrow \hbox{\tt \&} \;|\; \hbox{\verb|<|} \;|\; \hbox{\verb|<=|} \;|\; \hbox{\verb|<>|} \;|\; \hbox{\tt =} \;|\; \hbox{\verb|>|} \;|\; \hbox{\verb|>=|}$\\
576 $\tt \qquad \;|\; cutafter \;|\; cutbefore$\\
577 $\tt \descr{of operator} \rightarrow arctime \;|\; direction \;|\; directiontime \;|\; directionpoint$\\
578 $\tt \qquad \;|\; glyph \;|\; penoffset \;|\; point \;|\; postcontrol \;|\; precontrol$\\
579 $\tt \qquad \;|\; subpath \;|\; substring$\\
580 $\tt $\\
581 $\tt \descr{variable} \rightarrow \descr{tag}\descr{suffix}$\\
582 $\tt \descr{suffix} \rightarrow \descr{empty} \;|\; \descr{suffix}\descr{subscript} \;|\; \descr{suffix}\descr{tag}$\\
583 $\tt \qquad \;|\; \descr{suffix parameter}$\\
584 $\tt \descr{subscript} \rightarrow \descr{number} \;|\; \hbox{\tt [}\descr{numeric expression}\hbox{\tt ]}$\\
585 $\tt $\\
586 $\tt \descr{internal variable} \rightarrow ahangle \;|\; ahlength \;|\; bboxmargin$\\
587 $\tt \qquad \;|\; charcode \;|\; day \;|\; defaultcolormodel \;|\; defaultpen \;|\; defaultscale$\\
588 $\tt \qquad \;|\; hour \;|\; hppp \;|\; jobname \;|\; labeloffset \;|\; linecap \;|\; linejoin
589 \;|\; minute \;|\; miterlimit \;|\; month$\\
590 $\tt \qquad \;|\; numberprecision \;|\; numbersystem$\\
591 $\tt \qquad \;|\; outputfilename \;|\; outputformat \;|\; outputformatoptions \;|\; outputtemplate$\\
592 $\tt \qquad \;|\; pausing \;|\; prologues \;|\; showstopping$\\
593 $\tt \qquad \;|\; time \;|\; tracingoutput \;|\; tracingcapsules \;|\; tracingchoices \;|\; tracingcommands$\\
594 $\tt \qquad \;|\; tracingequations \;|\; tracinglostchars \;|\; tracingmacros$\\
595 $\tt \qquad \;|\; tracingonline \;|\; tracingrestores \;|\; tracingspecs$\\
596 $\tt \qquad \;|\; tracingstats \;|\; tracingtitles \;|\; truecorners$\\
597 $\tt \qquad \;|\; warningcheck \;|\; vppp \;|\; year$\\
598 $\tt \qquad \;|\; \descr{symbolic token defined by {\tt newinternal}}$
599 \end{ctabbing}
600 \caption{Part 2 of the syntax for expressions}
601 \index{nullary op?\tdescr{nullary op}}\index{of operator?\tdescr{of operator}}\index{primary binop?\tdescr{primary binop}}%
602 \index{secondary binop?\tdescr{secondary binop}}\index{subscript?\tdescr{subscript}}\index{suffix?\tdescr{suffix}}%
603 \index{tertiary binop?\tdescr{tertiary binop}}\index{unary op?\tdescr{unary op}}%
604 \label{syexpr2}
605 \end{figure}
606
607 \begin{figure}[htp]
608 \begin{ctabbing}
609 $\tt \descr{pseudo function} \rightarrow min\hbox{\tt (}\descr{expression list}\hbox{\tt )}$\\
610 $\tt \qquad \;|\; max\hbox{\tt (}\descr{expression list}\hbox{\tt )}$\\
611 $\tt \qquad \;|\; incr\hbox{\tt (}\descr{numeric variable}\hbox{\tt )}$\\
612 $\tt \qquad \;|\; decr\hbox{\tt (}\descr{numeric variable}\hbox{\tt )}$\\
613 $\tt \qquad \;|\; dashpattern\hbox{\tt (}\descr{on\hbox{\tt /}off list}\hbox{\tt )}$\\
614 $\tt \qquad \;|\; interpath\hbox{\tt (}\descr{numeric expression}\hbox{\tt ,} \descr{path expression}\hbox{\tt ,} \descr{path expression}\hbox{\tt )}$\\
615 $\tt \qquad \;|\; buildcycle\hbox{\tt (}\descr{path expression list}\hbox{\tt )}$\\
616 $\tt \qquad \;|\; thelabel\descr{label suffix}\hbox{\tt (}\descr{expression}\hbox{\tt ,} \descr{pair expression}\hbox{\tt )}$\\
617 $\tt \descr{path expression list} \rightarrow \descr{path expression}$\\
618 $\tt \qquad \;|\; \descr{path expression list}\hbox{\tt ,} \descr{path expression}$\\
619 $\tt \descr{on\hbox{\tt /}off list} \rightarrow \descr{on\hbox{\tt /}off list}\descr{on\hbox{\tt /}off clause} \;|\; \descr{on\hbox{\tt /}off clause}$\\
620 $\tt \descr{on\hbox{\tt /}off clause} \rightarrow on \descr{numeric tertiary} \;|\; off \descr{numeric tertiary}$
621 \end{ctabbing}
622 \caption{The syntax for function-like macros}
623 \index{label suffix?\tdescr{label suffix}}%
624 \label{sypseudo}
625 \end{figure}
626
627 \begin{figure}[htp]
628 \begin{ctabbing}
629 $\tt \descr{boolean expression} \rightarrow \descr{expression}$\\
630 $\tt \descr{cmykcolor expression} \rightarrow \descr{expression}$\\
631 $\tt \descr{color expression} \rightarrow \descr{expression}$\\
632 $\tt \descr{numeric atom} \rightarrow \descr{atom}$\\
633 $\tt \descr{numeric expression} \rightarrow \descr{expression}$\\
634 $\tt \descr{numeric primary} \rightarrow \descr{primary}$\\
635 $\tt \descr{numeric tertiary} \rightarrow \descr{tertiary}$\\
636 $\tt \descr{numeric variable} \rightarrow \descr{variable} \;|\; \descr{internal variable}$\\
637 $\tt \descr{pair expression} \rightarrow \descr{expression}$\\
638 $\tt \descr{pair primary} \rightarrow \descr{primary}$\\
639 $\tt \descr{path expression} \rightarrow \descr{expression}$\\
640 $\tt \descr{path subexpression} \rightarrow \descr{subexpression}$\\
641 $\tt \descr{pen expression} \rightarrow \descr{expression}$\\
642 $\tt \descr{picture expression} \rightarrow \descr{expression}$\\
643 $\tt \descr{picture variable} \rightarrow \descr{variable}$\\
644 $\tt \descr{rgbcolor expression} \rightarrow \descr{expression}$\\
645 $\tt \descr{string expression} \rightarrow \descr{expression}$\\
646 $\tt \descr{suffix parameter} \rightarrow \descr{parameter}$\\
647 $\tt \descr{transform primary} \rightarrow \descr{primary}$
648 \end{ctabbing}
649 \caption{Miscellaneous productions needed to complete the BNF}
650 \label{sytypexpr}
651 \end{figure}
652
653 \begin{figure}[htp]
654 \begin{ctabbing}
655 $\tt \descr{program} \rightarrow \descr{statement list} end$\\
656 $\tt \descr{statement list} \rightarrow \descr{empty} \;|\; \descr{statement list} \hbox{\tt ;} \descr{statement}$\\
657 $\tt \descr{statement} \rightarrow \descr{empty}$\\
658 $\tt \qquad \;|\; \descr{equation} \;|\; \descr{assignment}$\\
659 $\tt \qquad \;|\; \descr{declaration} \;|\; \descr{macro definition}$\\
660 $\tt \qquad \;|\; \descr{compound} \;|\; \descr{pseudo procedure}$\\
661 $\tt \qquad \;|\; \descr{command}$\\
662 $\tt \descr{compound} \rightarrow begingroup \descr{statement list} endgroup$\\
663 $\tt \qquad \;|\; beginfig\hbox{\tt (}\descr{numeric expression}\hbox{\tt );} \descr{statement list}\hbox{\tt ;} endfig$\\
664 $\tt $\\
665 $\tt \descr{equation} \rightarrow \descr{expression} \hbox{\tt =} \descr{right-hand side}$\\
666 $\tt \descr{assignment} \rightarrow \descr{variable} \hbox{\tt :=} \descr{right-hand side}$\\
667 $\tt \qquad \;|\; \descr{internal variable} \hbox{\tt :=} \descr{right-hand side}$\\
668 $\tt \descr{right-hand side} \rightarrow \descr{expression} \;|\; \descr{equation} \;|\; \descr{assignment}$\\
669 $\tt $\\
670 $\tt \descr{declaration} \rightarrow \descr{type} \descr{declaration list}$\\
671 $\tt \descr{declaration list} \rightarrow \descr{generic variable}$\\
672 $\tt \qquad \;|\; \descr{declaration list}\hbox{\tt ,} \descr{generic variable}$\\
673 $\tt \descr{generic variable} \rightarrow \descr{symbolic token} \descr{generic suffix}$\\
674 $\tt \descr{generic suffix} \rightarrow \descr{empty} \;|\; \descr{generic suffix} \descr{tag}$\\
675 $\tt \qquad \;|\; \descr{generic suffix} \hbox{\tt []}$\\
676 $\tt $\\
677 $\tt \descr{macro definition} \rightarrow \descr{macro heading} \hbox{\tt =} \descr{replacement text} enddef$\\
678 $\tt \descr{macro heading} \rightarrow def \descr{symbolic token} \descr{delimited part} \descr{undelimited part}$\\
679 $\tt \qquad \;|\; vardef \descr{generic variable} \descr{delimited part} \descr{undelimited part}$\\
680 $\tt \qquad \;|\; vardef \descr{generic variable} \hbox{\verb|@#|} \descr{delimited part} \descr{undelimited part}$\\
681 $\tt \qquad \;|\; \descr{binary def} \descr{parameter} \descr{symbolic token} \descr{parameter}$\\
682 $\tt \descr{delimited part} \rightarrow \descr{empty}$\\
683 $\tt \qquad \;|\; \descr{delimited part}\hbox{\tt (}\descr{parameter type} \descr{parameter tokens}\hbox{\tt )}$\\
684 $\tt \descr{parameter type} \rightarrow expr \;|\; suffix \;|\; text$\\
685 $\tt \descr{parameter tokens} \rightarrow \descr{parameter} \;|\; \descr{parameter tokens}\hbox{\tt ,} \descr{parameter}$\\
686 $\tt \descr{parameter} \rightarrow \descr{symbolic token}$\\
687 $\tt \descr{undelimited part} \rightarrow \descr{empty}$\\
688 $\tt \qquad \;|\; \descr{parameter type} \descr{parameter}$\\
689 $\tt \qquad \;|\; \descr{precedence level} \descr{parameter}$\\
690 $\tt \qquad \;|\; expr \descr{parameter} of \descr{parameter}$\\
691 $\tt \descr{precedence level} \rightarrow primary \;|\; secondary \;|\; tertiary$\\
692 $\tt \descr{binary def} \rightarrow primarydef \;|\; secondarydef \;|\; tertiarydef$\\
693 $\tt $\\
694 $\tt \descr{pseudo procedure} \rightarrow drawoptions\hbox{\tt (}\descr{option list}\hbox{\tt )}$\\
695 $\tt \qquad \;|\; label\descr{label suffix}\hbox{\tt (}\descr{expression}\hbox{\tt ,} \descr{pair expression}\hbox{\tt )}$\\
696 $\tt \qquad \;|\; dotlabel\descr{label suffix}\hbox{\tt (}\descr{expression}\hbox{\tt ,} \descr{pair expression}\hbox{\tt )}$\\
697 $\tt \qquad \;|\; labels\descr{label suffix}\hbox{\tt (}\descr{point number list}\hbox{\tt )}$\\
698 $\tt \qquad \;|\; dotlabels\descr{label suffix}\hbox{\tt (}\descr{point number list}\hbox{\tt )}$\\
699 $\tt \descr{point number list} \rightarrow \descr{suffix} \;|\; \descr{point number list}\hbox{\tt ,} \descr{suffix}$\\
700 $\tt \descr{label suffix} \rightarrow \descr{empty} \;|\; lft \;|\; rt \;|\; top \;|\; bot \;|\; ulft \;|\; urt \;|\; llft \;|\; lrt$
701 \end{ctabbing}
702 \caption{Overall syntax for MetaPost programs}
703 \index{generic variable?\tdescr{generic variable}}\index{label suffix?\tdescr{label suffix}}\index{replacement text?\tdescr{replacement text}}%
704 \index{suffix?\tdescr{suffix}}%
705 \label{syprog}
706 \end{figure}
707
708 \begin{figure}[htp]
709 \begin{ctabbing}
710 $\tt \descr{command} \rightarrow clip \descr{picture variable} to \descr{path expression}$\\
711 $\tt \qquad \;|\; interim \descr{internal variable} \hbox{\tt :=} \descr{right-hand side}$\\
712 $\tt \qquad \;|\; let \descr{symbolic token} \hbox{\tt =} \descr{symbolic token}$\\
713 $\tt \qquad \;|\; pickup \descr{expression}$\\
714 $\tt \qquad \;|\; randomseed \hbox{\tt :=} \descr{numeric expression}$\\
715 $\tt \qquad \;|\; save \descr{symbolic token list}$\\
716 $\tt \qquad \;|\; setbounds \descr{picture variable} to \descr{path expression}$\\
717 $\tt \qquad \;|\; shipout \descr{picture expression}$\\
718 $\tt \qquad \;|\; write \descr{string expression} to \descr{string expression}$\\
719 $\tt \qquad \;|\; \descr{addto command}$\\
720 $\tt \qquad \;|\; \descr{drawing command}$\\
721 $\tt \qquad \;|\; \descr{font metric command}$\\
722 $\tt \qquad \;|\; \descr{newinternal command}$\\
723 $\tt \qquad \;|\; \descr{message command}$\\
724 $\tt \qquad \;|\; \descr{mode command}$\\
725 $\tt \qquad \;|\; \descr{show command}$\\
726 $\tt \qquad \;|\; \descr{special command}$\\
727 $\tt \qquad \;|\; \descr{tracing command}$\\
728 $\tt $\\
729 $\tt \descr{show command} \rightarrow show \descr{expression list}$\\
730 $\tt \qquad \;|\; showvariable \descr{symbolic token list}$\\
731 $\tt \qquad \;|\; showtoken \descr{symbolic token list}$\\
732 $\tt \qquad \;|\; showdependencies$\\
733 $\tt $\\
734 $\tt \descr{symbolic token list} \rightarrow \descr{symbolic token}$\\
735 $\tt \qquad \;|\; \descr{symbolic token}\hbox{\tt ,} \descr{symbolic token list}$\\
736 $\tt \descr{expression list} \rightarrow \descr{expression} \;|\; \descr{expression list}\hbox{\tt ,} \descr{expression}$\\
737 $\tt $\\
738 $\tt \descr{addto command} \rightarrow$\\
739 $\tt \qquad addto \descr{picture variable} also \descr{picture expression} \descr{option list}$\\
740 $\tt \qquad \;|\; addto \descr{picture variable} contour \descr{path expression} \descr{option list}$\\
741 $\tt \qquad \;|\; addto \descr{picture variable} doublepath \descr{path expression} \descr{option list}$\\
742 $\tt \descr{option list} \rightarrow \descr{empty} \;|\; \descr{drawing option} \descr{option list}$\\
743 $\tt \descr{drawing option} \rightarrow withcolor \descr{color expression}$\\
744 $\tt \qquad \;|\; withrgbcolor \descr{rgbcolor expression} \;|\; withcmykcolor \descr{cmykcolor expression}$\\
745 $\tt \qquad \;|\; withgreyscale \descr{numeric expression} \;|\; withoutcolor$\\
746 $\tt \qquad \;|\; withprescript \descr{string expression} \;|\; withpostscript \descr{string expression}$\\
747 $\tt \qquad \;|\; withpen \descr{pen expression} \;|\; dashed \descr{picture expression}$\\
748 $\tt $\\
749 $\tt \descr{drawing command} \rightarrow draw \descr{picture expression} \descr{option list}$\\
750 $\tt \qquad \;|\; \descr{fill type} \descr{path expression} \descr{option list}$\\
751 $\tt \descr{fill type} \rightarrow fill \;|\; draw \;|\; filldraw \;|\; unfill \;|\; undraw \;|\; unfilldraw$\\
752 $\tt \qquad \;|\; drawarrow \;|\; drawdblarrow \;|\; cutdraw$\\
753 $\tt $\\
754 $\tt \descr{newinternal command} \rightarrow newinternal \descr{internal type} \descr{symbolic token list}$\\
755 $\tt \qquad \;|\; newinternal \descr{symbolic token list}$\\
756 $\tt $\\
757 $\tt \descr{message command} \rightarrow errhelp \descr{string expression}$\\
758 $\tt \qquad \;|\; errmessage \descr{string expression}$\\
759 $\tt \qquad \;|\; filenametemplate \descr{string expression}$\\
760 $\tt \qquad \;|\; message \descr{string expression}$
761 \end{ctabbing}
762 \caption{Part 1 of the syntax for commands}
763 \index{option list?\tdescr{option list}}\index{picture variable?\tdescr{picture variable}}%
764 \label{sycmds1}
765
766 % is this really true? in practice, in real implementations?
767 %\bigskip
768 %By the way, the default for \ttindex{randomseed} is, in effect,
769 %$\textsl{day} + \textsl{time}*\epsilon$. Unfortunately, \textsl{time}
770 %is in minutes.
771 \end{figure}
772
773 \begin{figure}[htp]
774 \begin{ctabbing}
775 $\tt \descr{mode command} \rightarrow batchmode \;|\; nonstopmode$\\
776 $\tt \qquad \;|\; scrollmode \;|\; errorstopmode$\\
777 $\tt $\\
778 $\tt \descr{special command} \rightarrow fontmapfile \descr{string expression}$\\
779 $\tt \qquad \;|\; fontmapline \descr{string expression}$\\
780 $\tt \qquad \;|\; special \descr{string expression}$\\
781 $\tt $\\
782 $\tt \descr{tracing command} \rightarrow tracingall \;|\; loggingall \;|\; tracingnone$
783 \end{ctabbing}
784 \caption{Part 2 of the syntax for commands}
785 \index{batchmode?\texttt{batchmode}}\index{nonstopmode?\texttt{nonstopmode}}\index{scrollmode?\texttt{scrollmode}}\index{errorstopmode?\texttt{errorstopmode}}%
786 \label{sycmds2}
787 \end{figure}
788
789 \begin{figure}[htp]
790 \begin{ctabbing}
791 $\tt \descr{if test} \rightarrow if \descr{boolean expression} \hbox{\tt :} \descr{balanced tokens} \descr{alternatives} fi$\\
792 $\tt \descr{alternatives} \rightarrow \descr{empty}$\\
793 $\tt \qquad \;|\; else\hbox{\tt :} \descr{balanced tokens}$\\
794 $\tt \qquad \;|\; elseif \descr{boolean expression} \hbox{\tt :} \descr{balanced tokens} \descr{alternatives}$\\
795 $\tt $\\
796 $\tt \descr{loop} \rightarrow \descr{loop header}\hbox{\tt :} \descr{loop text} endfor$\\
797 $\tt \descr{loop header} \rightarrow for \descr{symbolic token} \hbox{\tt =} \descr{progression}$\\
798 $\tt \qquad \;|\; for \descr{symbolic token} \hbox{\tt =} \descr{for list}$\\
799 $\tt \qquad \;|\; for \descr{symbolic token} \hbox{\tt within} \descr{picture expression}$\\
800 $\tt \qquad \;|\; forsuffixes \descr{symbolic token} \hbox{\tt =} \descr{suffix list}$\\
801 $\tt \qquad \;|\; forever$\\
802 $\tt \descr{progression} \rightarrow \descr{numeric expression} upto \descr{numeric expression}$\\
803 $\tt \qquad \;|\; \descr{numeric expression} downto \descr{numeric expression}$\\
804 $\tt \qquad \;|\; \descr{numeric expression} step \descr{numeric expression} until \descr{numeric expression} $\\
805 $\tt \descr{for list} \rightarrow \descr{expression} \;|\; \descr{for list}\hbox{\tt ,} \descr{expression}$\\
806 $\tt \descr{suffix list} \rightarrow \descr{suffix} \;|\; \descr{suffix list}\hbox{\tt ,} \descr{suffix}$
807 \end{ctabbing}
808 \caption{The syntax for conditionals and loops}
809 \index{balanced tokens?\tdescr{balanced tokens}}\index{suffix?\tdescr{suffix}}%
810 \label{sycondloop}
811 \end{figure}
812
813 \endgroup
814
815
816 \subsection{Command-Line Syntax}
817 \label{refman:commandline}
818
819 \begingroup
820 \renewcommand*{\arraystretch}{1.25}% Give command-line switch tables air.
821
822 \subsubsection{The MetaPost Program}
823 \label{refman:mpost}
824
825 \newcommand*{\opt}[1]{\ensuremath{\big[}#1\ensuremath{\big]}}
826 \newcommand*{\cmdsw}{\tdescr{switches}}
827 \newcommand*{\cmdmem}{\tdescr{preloadfile}}
828 \newcommand*{\cmdin}{\tdescr{infile}}
829 \newcommand*{\cmdcode}{\tdescr{commands}}
830 \newcommand*{\cmdindex}[1]{\index{command-line!mpost?\texttt{mpost}!#1?\texttt{#1}}\texttt{#1}}
831
832 The MetaPost program processes commands in the MetaPost language, either
833 read from a file or typed-in interactively, and compiles them into
834 PostScript or SVG graphics. The run-time behavior of the executable can
835 be controlled by command-line parameters, environment variables, and
836 configuration files. The MetaPost executable is named
837 mpost\label{Dmpost}\index{mpost} (or occasionally just mp). The
838 command-line syntax of the executable is
839 $$
840 \begin{verbatim}[commandchars=\\\{\}]
841 mpost \opt{\cmdsw} \opt{\&\cmdmem} \opt{\cmdin} \opt{\cmdcode}
842 \end{verbatim}
843 \index{mpost?\texttt{mpost}}\index{command-line!mpost?\texttt{mpost}}
844 $$
845 Any of the parameters is optional. If no argument is given to the
846 \verb|mpost| command, MetaPost enters interactive mode\index{interactive
847 mode}, indicated by a \verb|**| prompt\index{**?\texttt{**}!prompt},
848 waiting for a file name to be typed-in by keyboard. The file is then
849 read-in and processed as if it were given as parameter \cmdin\ on the
850 command-line.
851
852 \begin{description}
853 \item[\cmdin] A MetaPost input file is a text file containing statements
854 in the MetaPost language. Typically, input files have file extension
855 \texttt{mp}\index{mp file?{\tt mp} file}\index{files!mp?{\tt mp}},
856 e.g., \texttt{fig.mp}. Here is how MetaPost searches for input files.
857 If \cmdin\ doesn't end with \texttt{.mp}\index{mp file?{\tt mp}
858 file}\index{files!mp?{\tt mp}}, MetaPost first looks for a file
859 \texttt{\cmdin.mp}. Only if that file doesn't exist, it looks for
860 file \cmdin\ literally. That way, the \texttt{mp}\index{mp file?{\tt
861 mp} file}\index{files!mp?{\tt mp}} file extension can be omitted
862 when calling MetaPost. If \cmdin\ already ends with
863 \texttt{.mp}\index{mp file?{\tt mp} file}\index{files!mp?{\tt mp}}, no
864 special file name handling takes place and MetaPost looks for that
865 file only.
866
867 As an example, if there are two files \texttt{fig} and \texttt{fig.mp}
868 in the current directory and MetaPost is invoked with
869 \verb|'mpost fig'|, the file that gets processed is \texttt{fig.mp}.
870 To process file \texttt{fig} in this situation, MetaPost can be called
871 as \verb|'mpost fig.'|. Note, the trailing dot is only needed as long
872 as there exists a file \texttt{fig.mp} alongside file \texttt{fig}.
873
874 If MetaPost cannot find any input file by the rules specified above,
875 it complaints with an error message and interactively asks for a new
876 input file name.
877
878 \item[\cmdcode] All text on the command-line after \cmdin\ is
879 interpreted as MetaPost code and is processed after \cmdin\ is read.
880 If \cmdin\ already contains an \verb|end| statement, \cmdcode\ gets
881 effectively ignored. If MetaPost doesn't encounter an \verb|end|
882 statement neither in \cmdin\ nor in \cmdcode, it enters interactive
883 mode after processing all input.
884
885 \item[\texttt{\&\cmdmem}] The MetaPost program code in the \cmdmem\
886 MetaPost source file (and any other files that it inputs) is executed
887 before all other processing starts. The \cmdmem\ file should end with
888 an \texttt{end}\index{end?\texttt{end}} or
889 \texttt{dump}\index{dump?\texttt{dump}} command.
890
891 If neither \texttt{\&\cmdmem} nor \cmdindex{-mem} is specified on the
892 command line, MetaPost will default to loading the macro file
893 \texttt{mpost.mp}\index{mpost.mp?\texttt{mpost.mp}}, or to whatever
894 the actual name of the MetaPost executable is. The \cmdindex{-ini}
895 switch can be used to suppress this behavior.
896
897 \item[\cmdsw] MetaPost provides a number of command-line switches that
898 control the run-time behavior. Switches can be prefixed by one or two
899 dashes. Both forms have the same meaning. An exemplary call to
900 MetaPost that compiles a file \texttt{fig.mp}, using \LaTeX\ to
901 typeset \verb|btex|\slash\verb|etex| labels, would look like:
902 $$
903 \begin{verbatim}
904 mpost -tex=latex fig
905 \end{verbatim}
906 \index{mpost?\texttt{mpost}}
907 $$
908
909 Here's a summary of the command-line switches provided by mpost:
910
911 \setlength{\LTleft}{\leftmargin}
912 \begin{longtable}{>{\ttfamily}p{.35\linewidth}>{\raggedright\arraybackslash}p{.6\linewidth}}
913 \cmdindex{-debug}
914 & Don't delete intermediate files.\\
915 \cmdindex{-dvitomp}
916 & Act as the \texttt{dvitomp} executable (see below).\\
917 \cmdindex{-file-line-error}
918 & Start error messages with \verb|`filename:lineno:'| instead of
919 \verb|`!'|.\\
920 \cmdindex{-halt-on-error}
921 & Immediately exit after the first error occurred.\\
922 \cmdindex{-help}
923 & Show help on command-line switches.\\
924 \cmdindex{-ini}
925 & Do not load any preload file.\\
926 \cmdindex{-interaction}=\tdescr{string}
927 & Set interaction mode to one of \texttt{batchmode},
928 \texttt{nonstopmode}, \texttt{scrollmode}, \texttt{errorstopmode}.\\
929 \cmdindex{-jobname}=\tdescr{jobname}
930 & Set the name of the job (affects output file names).\\
931 \cmdindex{-kpathsea-debug}=\tdescr{number}
932 & Set debugging flags for path searching.\\
933 \cmdindex{-mem}=\tdescr{string}
934 & Use \tdescr{string} for the name of the file that contains macros to be preloaded
935 (same as \texttt{\&\cmdmem})\\
936 \cmdindex{-no-file-line-error}
937 & Enable normal MetaPost and \TeX\ style error messages.\\
938 \cmdindex{-no-kpathsea}
939 & Do not use the kpathsea program to find files. All files have to be
940 in the current directory or specified via a full path.\\
941 \cmdindex{-numbersystem}=\tdescr{string}
942 & Set arithmetic mode to one of \texttt{scaled}, \texttt{double},
943 \texttt{binary}, \texttt{decimal}, \texttt{interval}\\
944 \cmdindex{-progname}=\tdescr{string}
945 & Pretend to be the \tdescr{string} executable.\\
946 \cmdindex{-recorder}
947 & Write a list of all opened disk files to
948 \texttt{\tdescr{jobname}.fls}\index{fls file?{\tt fls}
949 file}\index{files!fls?{\tt fls}}. (This functionality is provided
950 by kpathsea.)\\
951 \cmdindex{-s} \tdescr{key}=\tdescr{value}
952 & Set internal variable \tdescr{key} to \tdescr{value}. This switch
953 can be given multiple times on the command-line. The assignments are
954 applied just before the input file is read-in. \tdescr{value} can be
955 an integer between -16383 and 16383 or a string in double quotes. For
956 strings, double quotes are stripped, but no other processing takes
957 place. To avoid double quotes being already stripped by the shell,
958 the whole assignment can be enclosed in another pair of single quotes.
959 Example: \verb|-s 'outputformat="svg"' -s prologues=3|\newline
960 Use SVG backend converting font shapes to paths.\\
961 \cmdindex{-tex}=\tdescr{texprogram}
962 & Load format \tdescr{texprogram} for rendering \TeX\ material.\\
963 \cmdindex{-troff}, \cmdindex{-T}
964 & Output troff compatible PostScript files.\\
965 \cmdindex{-version}
966 & Print version information and exit.\\
967 \end{longtable}
968
969 The following command-line switches are silently ignored in
970 \emph{mplib}-based MetaPost (v1.100 or later), because they are always
971 `on':
972
973 \begin{longtable}{>{\ttfamily}p{.35\linewidth}>{\raggedright\arraybackslash}p{.6\linewidth}}
974 \cmdindex{-8bit}
975 & \\
976 \cmdindex{-parse-first-line}
977 & \\
978 \end{longtable}
979
980 The following command-line switches are ignored, but trigger a warning:
981
982 \begin{longtable}{>{\ttfamily}p{.35\linewidth}>{\raggedright\arraybackslash}p{.6\linewidth}}
983 \cmdindex{-no-parse-first-line}
984 & \\
985 \cmdindex{-output-directory}=\tdescr{string}
986 & \\
987 \cmdindex{-translate-file}=\tdescr{string}
988 & \\
989 \end{longtable}
990
991 \end{description}
992
993 \subsubsection{The dvitomp Program}
994 \label{refman:dvitomp}
995
996 \renewcommand*{\cmdindex}[1]{\index{command-line!dvitomp?\texttt{dvitomp}!#1?\texttt{#1}}\texttt{#1}}
997 \renewcommand*{\cmdin}{\tdescr{infile}}
998 \newcommand*{\cmdout}{\tdescr{outfile}}
999
1000 The dvitomp\label{Ddvitomp}\index{dvitomp} program converts
1001 DVI\index{dvi file?{\tt dvi} file}\index{files!dvi?{\tt dvi}} files into
1002 low-level MetaPost code. MetaPost uses the dvitomp program when
1003 typesetting \verb|btex|\slash\verb|etex| labels by \TeX\ for the final
1004 conversion back into MetaPost code. The command-line syntax of the
1005 executable is
1006 $$
1007 \begin{verbatim}[commandchars=\\\{\}]
1008 dvitomp \opt{\cmdsw} \cmdin \opt{\cmdout}
1009 \end{verbatim}
1010 \index{dvitomp?\texttt{dvitomp}}\index{command-line!dvitomp?\texttt{dvitomp}}
1011 $$
1012 Parameters \cmdsw\ and \cmdout\ are optional.
1013
1014 \begin{description}
1015 \item[\cmdin] This is the name of the DVI file to convert. If the name
1016 doesn't end with \texttt{.dvi}\index{dvi file?{\tt dvi}
1017 file}\index{files!dvi?{\tt dvi}}, that extension is appended. Note,
1018 dvitomp never opens files not ending \texttt{.dvi}. This file is in
1019 general automatically generated by \TeX\ or troff, driven by MetaPost.
1020
1021 \item[\cmdout] This is the name of the output file containing the
1022 MetaPost code equivalent to \cmdin. If \cmdout\ is not given,
1023 \cmdout\ is \cmdin\ with the extension \texttt{.dvi} replaced by
1024 \texttt{.mpx}\index{mpx file?{\tt mpx} file}\index{files!mpx?{\tt
1025 mpx}}. If \cmdout\ is given and doesn't end with
1026 \texttt{.mpx}\index{mpx file?{\tt mpx} file}\index{files!mpx?{\tt
1027 mpx}}, that extension is appended.
1028
1029 \item[\cmdsw] Command-line switches can be prefixed by one or two
1030 dashes. Both forms have the same meaning. The following command-line
1031 switches are provided by dvitomp:
1032
1033 \setlength{\LTleft}{\leftmargin}
1034 \begin{longtable}{>{\ttfamily}p{.35\linewidth}>{\raggedright\arraybackslash}p{.6\linewidth}}
1035 \cmdindex{-help}
1036 & Show help on command-line switches.\\
1037 \cmdindex{-kpathsea-debug}=\tdescr{number}
1038 & Set debugging flags for path searching.\\
1039 \cmdindex{-progname}=\tdescr{string}
1040 & Pretend to be the \tdescr{string} executable.\\
1041 \cmdindex{-version}
1042 & Print version information and exit.\\
1043 \end{longtable}
1044
1045 \end{description}
1046
1047 The dvitomp program used to be part of a set of external tools, called
1048 \emph{mpware}\index{mpware tools}\footnote{makempx, mpto, dvitomp, and
1049 dmp.}, which were used by MetaPost for processing
1050 \verb|btex|\slash\verb|etex| labels. Since MetaPost version~1.100, the
1051 label conversion is handled internally by the mpost\index{mpost}
1052 program. The \emph{mpware} tools are therefore obsolete and no longer
1053 part of the MetaPost distribution. Nowadays, dvitomp is either a copy
1054 of the mpost executable with the name dvitomp or a wrapper, calling
1055 mpost\index{mpost} as
1056 $$
1057 \begin{verbatim}[commandchars=\\\{\}]
1058 mpost -dvitomp \cmdin \cmdout
1059 \end{verbatim}
1060 \index{mpost?\texttt{mpost}}
1061 $$
1062
1063 \endgroup
1064
1065 %%% Local Variables:
1066 %%% mode: latex
1067 %%% TeX-PDF-mode: t
1068 %%% TeX-master: "mpman"
1069 %%% End: