Debian Codegraph @

texmf-dist/doc/luatex/minim-mp/minim-mp.doc

raw
1
2 \input minim-doc.sty
3
4 \manual{minim-mp}
5
6 \ifchapter \chapter Metapost
7
8 \else \startmetadata
9 author {Esger Renkema}
10 title {minim-mp}
11 date {2025-02-12}
12 version {2025/1.7}
13 keywords {LuaTeX; Plain TeX; MetaPost; mplib}
14 stopmetadata
15 \maketitle \fi
16
17 This package provides low-level mplib integration for plain lua(la)tex. In
18 order to use it, simply say ⟦\input minim-mp.tex⟧ (from plain tex) or
19 ⟦\requirepackage {minim-mp}⟧ from latex.
20 After this, ⟦*\directmetapost [ options ] { mp code }⟧ will result in a series
21 of images corresponding to the ⟦beginfig() ... endfig;⟧ statements in your
22 ⟦mp code⟧. Every image will be in a box of its own.
23
24 This package can also be used as a stand-alone metapost compiler. Saying
25 \stopformulatagging$$\hbox{⟦luatex --fmt=minim-mp your_file.mp⟧}$$\startformulatagging
26 will create a pdf file of all images in ⟦your_file.mp⟧, in order, with page
27 sizes adjusted to image dimensions. You might need generate the format first,
28 this is done with
29 \stopformulatagging$$\hbox{⟦luatex --ini minim-mp.ini⟧}$$\startformulatagging
30 Use minim-lamp instead of minim-mp for a latex-based version of the minim-mp
31 format.
32 With minim-lamp, for specifying the contents of the preamble, you can use
33 ⟦verbatimtex ... etex;⟧ statements at the top of your file.
34 Concluding the preamble with ⟦\begin{document}⟧ is optional, as both ⟦\begin⟧
35 and ⟦\end{document}⟧ will be inserted automatically if omitted.
36
37 \subsection TeX-MetaPost compatibility notes % 1
38
39 All metapost code to-be-run will be read under a special catcode regime in
40 which most ‘special’ characters (including {\tt\#} and {\tt\%}) are inert.
41 Any control sequences will be expanded fully, however, as inside an ⟦\edef⟧.
42 Keep this in mind and define any macros you want to use in a ⟦btex ... etex;⟧
43 environment as ⟦\protected⟧. With the latex package, latex’s ‘protected’ macros
44 are safe-to-use, too.
45
46 Every call to ⟦\directmetapost⟧ opens and closes a separate metapost instance.
47 If you want your second call to remember the first, you will have to define
48 a persistent metapost instance. This will also give you more control over image
49 extraction. See below under „Metapost instances”. The ⟦options⟧ will also be
50 explained there (for simple cases, you will not need them).
51
52 \subsection LaTeX compatibility notes % 1
53
54 The latex package minim-mp.sty contains the full plain interface, but also
55 provides a proper ⟦*metapost⟧ environment as an alternative to
56 ⟦\directmetapost⟧.
57 The ⟦metapost⟧ environment has no persistent backing instance,
58 but you can create a similar environment ⟦envname⟧ that does with
59 ⟦*\newmetapostenvironment [options] {envname}⟧.
60
61 Inside the above environments, you can use ⟦*\mpcolor {name}⟧ to insert the
62 proper colour values. Unlike in luamplib, this will work in any context where
63 metapost expects a colour.
64 An ⟦\mpdim⟧ macro is present too, but quite superfluous since the contents of
65 the metapost environments are fully expanded before metapost sees them: this
66 means you can use ⟦\the⟧ and ⟦\the\dimexpr⟧ like everywhere else. Tex’s
67 registers can also be accessed from within metapost itself (see below).
68
69 When the package is loaded with the option ⟦*luamplib⟧, minim-mp will try and
70 act as a drop-in replacement for luamplib. The effort made is not very great,
71 but it will define an ⟦mplibcode⟧ environment, as well as the
72 ⟦\mplibcodeinherit⟧, ⟦\mplibshowlog⟧, ⟦\mplibsetformat⟧ and
73 ⟦\mplibnumbersystem⟧ switches;
74 also the macros ⟦\everymplib⟧ and ⟦\everyendmplib⟧.
75
76 \subsection MetaFun compatibility notes % 1
77
78 The metafun format is supported to the extent that it should not immediately crash.
79 Otherwise, useing metafun is neither supported nor recommended.
80
81 %
82
83 \section Metapost extensions % 1
84
85 You can set the baseline of an image with ⟦*baseline(p)⟧. There, ⟦p⟧ must
86 either be a point through which the baseline should pass, or a number (where an
87 x~coordinate of zero will be added). Transformations will be taken into
88 account, hence the specification of two coordinates. The last given baseline
89 will be used.
90
91 You can write to tex’s log directly with ⟦*texmessage "hello";⟧. You can feed
92 it a comma-separated list of strings and numbers, which will be passed through
93 ⟦string.format()⟧ first.
94
95 You can write direct pdf statements with ⟦*special "pdf: statements"⟧ and you
96 can add comments to the pdf file with ⟦*special "pdfcomment: comments"⟧.
97 Say ⟦*special "latelua: lua code"⟧ to insert a ⟦late_lua⟧ whatsit.
98 All three specials can also be given as pre- or postscripts to another object.
99 In that case, they will be added before or after the object they are attached to.
100 Do note that all ⟦special⟧ statements will appear at the beginning of the
101 image; use pre- and postscripts to drawing statements if the order matters.
102
103 \subsection Partial paths and the even-odd rule % 2
104
105 While metapost fills paths according to the winding number, the pdf format also
106 supports filling according to the even-odd rule. You can use this method with
107 the ⟦*eofill⟧ and ⟦*eofilldraw⟧ drawing statements. Multiple contours can be
108 filled at once if all but the last are drawn with ⟦*nofill⟧. The latter is
109 especially useful for cutting something out of a shape, as it saves you the
110 hassle of stitching the paths together.
111
112 The macros ⟦*multi(draw|fill|filldraw|eofill|eofilldraw)⟧ take a list of paths
113 between parentheses and can be followed by the usual drawing options.
114 For example,
115 ⟦multidraw (contours "example" of "tenbf") withpen currentpen scaled 1/10;⟧
116 will give the word%
117 \markelement{Span}{\setactualtext{example }\startsinglecontentitem\space
118 \directmetapost [jobname='outline']
119 {beginfig(1) multidraw (contours "example" of "tenbf")
120 withpen currentpen scaled 1/10; baseline 0; endfig;}\stopsinglecontentitem}
121 in a thin outline.
122
123 The clipping shorthands ⟦*clipout⟧ and ⟦*clipto⟧ take a list of paths as
124 a ‘text’ parameter and either clip their ensemble out of the current picture,
125 or the current picture to the ensemble.
126 You will have to ensure yourself that the path has the right orientation for
127 clipping (i.e. you may have to insert the proper ⟦reverse⟧ operator yourself).
128
129 \subsection Tiling patterns % 2
130
131 The specification ⟦*withpattern(<name>)⟧ added to a ⟦fill⟧ statement will fill
132 the path with a pattern instead of a solid colour. If the pattern itself does
133 not contain any colour statements, it will have the colour given by ⟦withcolor⟧.
134 Stroking operations (the ⟦draw⟧ part) will not be affected.
135 Patterns will always look the same, irrespective of any transformations you
136 apply to the picture.
137
138 To define a pattern, sketch it between
139 ⟦*beginpattern(<name>) ... endpattern(xstep, ystep);⟧
140 where ⟦<name>⟧ is a suffix and ⟦(xstep, ystep)⟧ are the horizontal and vertical
141 distances between applications of the pattern.
142 Inside the definition, you can draw the pattern using whatever coordinates you
143 like; assign a value to the ⟦*matrix⟧ transformation to specify how the pattern
144 should be projected onto the page. This ⟦matrix⟧ will also be applied to
145 ⟦xstep⟧ and ⟦ystep⟧.
146
147 You can also change the internal variable ⟦*tilingtype⟧ and the normal variable
148 ⟦*painttype⟧, although the latter will be set to~1 automatically if you use any
149 colour inside the pattern definition. Consult the pdf specification for more
150 information on these parameters.
151
152 You can use text inside patterns, as in this example:
153 \hfill \vbox to 0pt{
154 \startelement alt{A circle filled with red As in a rectangular pattern.}{Figure}
155 \startsinglecontentitem \directmetapost [jobname='pattern']
156 {% define the pattern
157 picture letter; letter = maketext("a");
158 beginpattern(a)
159 draw letter rotated 45;
160 matrix = identity rotated 45;
161 endpattern(12pt,12pt);
162 % use the pattern
163 beginfig(1)
164 fill fullcircle scaled 3cm withpattern(a) withcolor 3/4red;
165 draw fullcircle scaled 3cm withpen pencircle scaled 1;
166 endfig;}\stopsinglecontentitem
167 \stopelement{Figure}\vss}\hskip10pt\strut
168 \par\nobreak
169 ⟦% define the pattern
170 picture letter; letter = maketext("a");
171 beginpattern(a)
172 draw letter rotated 45;
173 matrix = identity rotated 45;
174 endpattern(12pt,12pt);
175 % use the pattern
176 beginfig(1)
177 fill fullcircle scaled 3cm withpattern(a) withcolor 3/4red;
178 draw fullcircle scaled 3cm withpen pencircle scaled 1;
179 endfig;⟧
180
181 A small pattern library is available in the ⟦*minim-hatching.mp⟧ file; see the
182 accompanying documentation sheet for an overview of patterns.
183
184
185 \subsection Box resources % 2
186
187 Box resources (XForms) saved by tex can be included with ⟦*boxresource nr⟧.
188 (Note that ⟦nr⟧ is not a box number, but the index returned by
189 ⟦\lastsavedboxresourceindex⟧.)
190 The result will be an image object with the proper dimensions. This image can
191 be transformed in any way you like, but you cannot inspect the contents of the
192 resource within metapost.
193
194 Box resources can also be created from within metapost: ⟦<id> =⟧
195 ⟦*saveboxresource (<attributes>) <picture>⟧ returns a number identifying the
196 resource. The ⟦<attributes>⟧ can be given in the same way as the arguments to
197 ⟦setgstate⟧ (see below). XForms defined through metapost are available to other
198 metapost instances but not to tex; they are drawn with the same command
199 (⟦boxresource nr⟧).
200 There remains a subtle difference, however: metapost-defined box resources are
201 placed at their original origin, tex-defined resources at their lower left
202 corner.
203
204
205 \subsection Advanced PDF graphics % 2
206
207 You can use ⟦*savegstate⟧ and ⟦*restoregstate⟧ for inserting the ⟦q⟧ and ⟦Q⟧
208 operators; these must always be paired, or horrible errors will occur. You may
209 need them if you use ⟦*setgstate(<params>)⟧ for modifying the extended
210 graphical state (ExtGState). The ⟦params⟧ must be a comma-separated
211 ⟦Key=value⟧ list, with all ⟦value⟧s being suffixes. The latter restriction may
212 require the use of additional variables, but as this is a very low-level
213 command, it is best to wrap it in a more specialised macro anyway.
214 The ⟦*withgstate (<params>)⟧ can be added to a drawing statement and includes
215 saving/restoring the graphical state.
216
217 Note that while you could try and use ⟦setgstate⟧ for modifying variables like
218 the line cap or dash pattern, the result of doing so will be unpredictable,
219 since such changes will be invisible to metapost. Its intended use is
220 restricted to graphics parameters outside metapost’s scope.
221
222
223 \subsection Transparency
224
225 For applying transparency, ⟦*setalpha(a)⟧ updates the ⟦CA⟧ and ⟦ca⟧ parameters
226 as a stand-alone command and ⟦*withalpha(a)⟧ can be used in a drawing statement
227 where it will save/restore the graphical state around it. For applying
228 transparency to an ensemble of drawing statements, ⟦*transparent (a) <picture>⟧
229 instead of ⟦draw <picture>⟧ will create and insert the proper transparency group.
230 The transparency group attributes can be set with the string internal
231 ⟦*transparency_group_attrs⟧, while for all three macros the blend mode can be
232 set with the string internal ⟦*blend_mode⟧ (it will be added whenever set).
233
234
235 \subsection Additions to plain.mp % 2
236
237 Minim-mp provides a few elementary macros and constants that are conspicuously
238 absent from plain.mp; I hope their addition is uncontroversial. All are
239 provided in the file minim.mp. This file is safe for use with other metapost
240 processors.
241
242 The constants are ⟦*pi⟧ (355/113), ⟦*fullsquare⟧, ⟦*unitcircle⟧ and the
243 cmyk-colours ⟦*cyan⟧, ⟦*magenta⟧, ⟦*yellow⟧ and ⟦*key⟧. The macros are
244 ⟦*clockwise⟧, ⟦*xshifted⟧, ⟦*yshifted⟧, ⟦*hflip⟧ and ⟦*vflip⟧, where the flips
245 are defined in such a way that ⟦p & hflip p⟧ gives the expected result.
246
247 Version 1.2 brought the following additions: ⟦*save_pair⟧, ⟦*save_path⟧ etc.
248 etc. that save and declare in one go; the missing trigonometric functions
249 ⟦*tand⟧, ⟦*arcsind⟧, ⟦*arccosd⟧ and ⟦*arctand⟧, and the unit circle segment
250 drawing function ⟦*arc(⟧$θ_0$⟦*,⟧$θ_ℓ$⟦*)⟧ (taking a starting angle and arc
251 length, both in degrees).
252
253 Version 1.6 brought ⟦*empty⟧ for testing empty suffixes, ⟦*typeof(v)⟧
254 expanding to the type (⟦numeric⟧, ⟦pair⟧ etc.) of variable ⟦v⟧,
255 ⟦*getbounds⟧ as complement to ⟦setbounds⟧, the (twodimensional) exterior product
256 ⟦*p extprod q⟧ and the test ⟦*collinear(p,q,r)⟧.
257
258 %
259
260 \section Running tex code % 1
261
262 You can include tex snippets with either ⟦*maketext "tex text"⟧ or
263 ⟦*btex ... etex⟧ statements. The tex code will be executed in the current
264 environment without an extra grouping level. The result of either statement at
265 the place where it is invoked is an image object of the proper dimensions that
266 can be moved, scaled, rotated and mirrored. You can even specify a colour. Its
267 contents, however, will only be added afterwards and are invisible to metapost.
268
269 Arbitrary tex statements may be included in ⟦*verbatimtex ... etex⟧, which may
270 occur anywhere. These ⟦btex⟧ and ⟦verbatimtex⟧ statements are executed in the
271 order they are given.
272
273 When including tex code in metapost, do keep in mind that every metapost
274 snippet read by ⟦\directmetapost⟧ or ⟦\begin{metapost}⟧ will be expanded fully
275 (as inside an ⟦\edef⟧) before execution. This may expand your macros too early!
276 The best solution is to define your own macros as ⟦\protected⟧ or using latex’s
277 more convoluted protection equivalent, although a well-placed ⟦\noexpand⟧ or,
278 as a last resort, wrapping the entire tex fragment in ⟦\unexpanded{...}⟧ will
279 work as well.
280
281 You can also use metapost’s ⟦*infont⟧ operator, which restricts the text
282 to-be-typeset to a single font, but returns an ⟦picture⟧ containing a ⟦picture⟧
283 for each character. The right-hand argument of ⟦infont⟧ should either be
284 a (numerical) font~id or the (cs)name of a font (without backslash).
285 A traditional font name (e.g. ‘cmtt10’) is also accepted; this will silently
286 load the font.
287
288 One possible use of the ⟦infont⟧ operator is setting text along curves: % 2
289
290 \goodbreak
291 ⟦beginfig(1)
292 save t, w, r, a; picture t;
293 t = "Running TeX from within MetaPost" infont "tenrm";
294 w = xpart lrcorner t = 3.141593 r;
295 for c within t :
296 x := xpart (llcorner c + lrcorner c)/2;
297 a := 90 - 180 x/w;
298 draw c rotatedaround((x,0), a)
299 shifted (-r*sind(a)-x, r*cosd(a));
300 endfor
301 endfig;⟧
302 \vskip-2\parskip plus 2\parskip
303 \quitvmode\hfil
304 \startelement alt {The text „Running TeX from within MetaPost” set along a half-circle.} {Figure}%
305 \startsinglecontentitem\directmetapost [jobname='tex-in-mp'] {%
306 beginfig(1)
307 save t, w, r, a; picture t;
308 t = "Running TeX from within MetaPost" infont "tenrm";
309 w = xpart lrcorner t = 3.141593 r;
310 for c within t :
311 x := xpart (llcorner c + lrcorner c)/2;
312 a := 90 - 180 x/w;
313 draw c rotatedaround((x,0), a)
314 shifted (-r*sind(a)-x, r*cosd(a));
315 endfor
316 endfig;}\stopsinglecontentitem \stopelement{Figure}
317
318 By default, the ⟦maketext⟧ operator is used for typesetting labels. You can,
319 however, order de ⟦label⟧ macro to use ⟦infont⟧ instead by setting
320 ⟦*maketextlabels⟧ to ⟦false⟧.
321
322 \subsection Access to font contours % 2
323
324 Both the ⟦maketext⟧ and ⟦infont⟧ operators return pictures that are opaque to
325 metapost. For accessing the contours that make up the characters in a string,
326 you will need the ⟦*glyph g of f⟧ operator.
327 It is a bit more versatile than its traditional metapost
328 counterpart: ⟦g⟧ may also be the name of the glyph instead of its index, while
329 ⟦f⟧ can either be a font~id or font name (as with ⟦infont⟧).
330
331 A variant of ⟦glyph of⟧ is the ⟦*contours s of f⟧ macro, which first typesets
332 the string ⟦s⟧ in the same way as ⟦infont⟧ does (so that kerning and font
333 shaping are applied), but returns a (comma-separated) list of contours. This
334 list is fit for use in a for loop. Note that due to rounding errors, the glyph
335 contours will not match the output of ⟦infont⟧ exactly.
336
337 Be also aware that the contours returned by these operators may be disjoint:
338 a letter ⟦o⟧, for example, will consists of two paths. This means you cannot
339 recreate the characters by just filling each contour, as that would turn the
340 ⟦o⟧ into a filled-in circle. Instead, you must use ⟦multifill⟧ on the entire
341 output of ⟦glyph of⟧ or ⟦contours of⟧ (see above under „Partial paths”).
342
343 %
344
345 \section Running lua code % 1
346
347 You can call out to lua with ⟦*runscript "lua code"⟧. For this purpose, each
348 metapost instance carries around its own lua environment so that assignments
349 you make are local to the instance. (The global environment can still be
350 accessed behind the ⟦_G⟧ variable.)
351
352 Every runscript environment is augmented with a small set of useful functions;
353 this set can be found in the ⟦*M.mp_functions⟧ table (with
354 ⟦M = require 'minim-mp'⟧; see below under „Lua interface”).
355
356 When using ⟦runscript⟧, you must ensure its argument is a correct lua program.
357 As an escape hatch, raw strings can be passed to lua with
358 ⟦runscript ("[[function_name]]" & raw_string)⟧.
359 This will return the result of the function ⟦function_name⟧ applied to
360 ⟦raw_string⟧ as a lua string.
361
362 \subsection Returning values from lua % 2
363
364 If your lua snippet returns nothing, the ⟦runscript⟧ call will be invisible to
365 metapost. If on the other hand it does return a value, that value will have to
366 be translated to something metapost can understand.
367 You can return a point, colour or transform by returning an array of two to six
368 elements (excluding five).
369 Numbers and strings will be returned as they are.
370 For other return values, ⟦tostring()⟧ will be called.
371
372 Note that lua strings will be returned as metapost code, not as metapost string
373 literals! If you want to return the latter, you must quote the string yourself;
374 the runscript environment contains a ⟦*quote(s)⟧ function for this purpose,
375 which also escapes all double quotes in the string~⟦s⟧.
376 When returning dimensions, you must be wary of arithmetic overflows: every
377 useful dimension expressed in scaled points will be too large for metapost. Use
378 ⟦*sp_to_pt(nr)⟧ instead, which converts dimensions to points.
379
380 \subsection Passing values to lua % 2
381
382 Do keep in mind that metapost and lua represent numbers in different ways and
383 that rounding errors may occur. For instance, metapost’s ⟦decimal epsilon⟧
384 returns ⟦0.00002⟧, which metapost understands as ⟦1/65536⟧, but lua as
385 ⟦1/50000⟧. Use the metapost macro ⟦*hexadecimal⟧ instead of ⟦decimal⟧ for
386 passing unambiguous numbers to lua.
387
388 Additionally, you should be aware that metapost uses slightly bigger points
389 than tex, so that ⟦epsilon⟧ when taken as a dimension is not quite equal to
390 ⟦1sp⟧. Use the metapost macro ⟦*scaledpoints⟧ for passing to lua a metapost
391 dimension as an integral number of scaled points.
392
393 Strings can be passed to lua with the ⟦*lua_string⟧ macro, which escapes the
394 necessary characters and then surrounds its argument with quotes.
395 A generic macro for passing values to lua, finally, is ⟦*quote_for_lua⟧, which
396 automatically converts strings, numbers, points and colours to (metapost)
397 strings that lua can understand.
398
399 \subsection Querying tex and lua variables % 2
400
401 Stitching together lua snippets by hand is not very convenient. Therefore,
402 minim-mp provides three helper macros that should cover most lua interaction.
403 For running a single lua function, ⟦*luafunction⟧ ⟦<suffix> (<arguments>)⟧
404 returns the result of the function ⟦str <suffix>⟧ applied to any number of
405 arguments, which are quoted automatically.
406 Variables can be queried with ⟦*luavariable⟧ ⟦<suffix>⟧
407 and set with ⟦*setluavariable⟧ ⟦<suffix> = <value>;⟧.
408
409 The details of metapost tokenisation make these macros rather powerful: you can
410 not only say e.g. ⟦luavariable tex.jobname⟧ to get the current jobname, but
411 even define a ⟦texvariable⟧ macro with
412 \stopformulatagging$$\hbox{⟦vardef texvariable @# = luavariable tex @# enddef;⟧}$$\startformulatagging
413 and have ⟦texvariable jobname⟧ work as expected.
414
415 For accessing count, dimen, attribute or toks registers, the macros are
416 ⟦*tex.count⟧ ⟦[number]⟧ or ⟦*tex.count⟧⟦.name⟧ [etc. etc.] for getting and
417 ⟦*set tex.count⟧ ⟦[number] = value⟧ or ⟦*set tex.count⟧⟦.name = value⟧ etc. for
418 setting values.
419
420 %
421
422 \section Metapost instances % 1
423
424 You can define a new persistent metapost instance with
425 ⟦*\newmetapostinstance [ options ] \id⟧.
426 An instance can be closed with ⟦*\closemetapostinstance \id⟧.
427 The ⟦options⟧ are directly passed to lua, as a table, and can contain the
428 following keys:
429
430 \smallskip\smallskip\automarktable
431 \halign{#\quad\hfil&#\quad\hfil&#\hfil\cr
432 Option&Default&Description\cr
433 ⟦jobname⟧&⟦':metapost:'⟧&Used in error messages.\cr
434 ⟦format⟧&⟦'plain.mp'⟧&Format to initialise the instance with.\cr
435 ⟦mathmode⟧&⟦'scaled'⟧&One of ⟦scaled⟧, ⟦decimal⟧ or ⟦double⟧.\cr
436 ⟦seed⟧&⟦nil⟧&Random seed for this instance.\cr
437 ⟦catcodes⟧&(internal value)&Catcode table for ⟦btex ... etex⟧.\cr
438 ⟦env⟧&copy of ⟦_G⟧&Lua environment for ⟦runscript⟧.\cr
439 }\smallskip
440
441 See below under „Lua interface” for greater control over these parameters.
442
443 \subsection Retrieving images from instances % 2
444
445 Now that you have your own instance, you can run chunks of metapost code in it
446 with ⟦*\runmetapost \id { code }⟧. Any images that your code may have contained
447 will have to be extracted explicitly. This is possible in a number of ways,
448 although each image can be retrieved only once.
449
450 All metapost images have an ⟦\hbox⟧ as outermost container. Do not unpack this
451 box: doing so will cause its dimensions to be lost.
452
453 ⟦*\getnextmpimage \id⟧
454 – Writes the first unretrieved image to the current node list.
455 There, the image will be contained in a single box node.
456
457 ⟦*\getnamedmpimage \id {name}⟧
458 – Retrieves an image by name
459 and writes it to the current node list.
460
461 ⟦*\boxnextmpimage \id box-nr⟧
462 – Puts the next unretrieved image in box ⟦box-nr⟧. The number may be anything
463 tex can parse as a number.
464
465 ⟦*\boxnamedmpimage \id box-nr {name}⟧
466 – Puts the image named ⟦name⟧ in box ⟦box-nr⟧.
467
468 Say ⟦*\remainingmpimages \id⟧ for the number of images not yet retrieved
469 and ⟦*\getallmpimages \id⟧ to insert all remaining images.
470
471 Finally, as a shorthand, ⟦*\runmetapostimage \id { code }⟧ will add
472 ⟦beginfig ... endfig;⟧ to your ⟦code⟧ and write the resulting image immediately
473 to the current list.
474
475 \subsection Associated token lists % 2
476
477 Associated to every instance are four token registers containing tex and/or
478 metapost code to be inserted before or after each executed chunk.
479 You can access them with ⟦*\everymp \id {pre|post} {tex|mp}⟧
480 (e.g. ⟦\everymp1{pre}{mp}⟧).
481 The token lists where ${\tt id}=0$ do not correspond to any instance and will
482 apply to every instance instead.
483 All four token lists are empty by default if you use minim-mp with plain tex.
484 The latex package, on the other hand, uses them for its own purposes, so take
485 care in that case to use ⟦\tokspre⟧ and ⟦\toksapp⟧ instead of overwriting their
486 contents. As a bonus, when using the latex package, you can use the environment
487 name instead of the numerical ⟦\id⟧.
488
489 \subsection Lua interface % 2
490
491 In what follows, you should assume ⟦M⟧ to be the result of
492 \stopformulatagging$$\hbox{⟦M = require('minim-mp')⟧}$$\startformulatagging
493 as this package does not claim a table in the global environment for itself.
494
495 You can open a new instance with ⟦*nr = M.open {options}⟧.
496 This returns an index in the ⟦*M.instances⟧ table.
497 Run code with ⟦*M.run (nr, code)⟧ and close the instance with ⟦*M.close (nr)⟧.
498 Images can be retrieved only with ⟦*box_node = M.get_image(nr, [name])⟧; omit
499 the ⟦name⟧ to select the first image.
500 Say ⟦*nr_remaining = M.left(nr)⟧ for the number of remaining images.
501
502 Each metapost instance is a table containing the following entries:
503
504 \smallskip\smallskip
505 \marktableaslist
506 \tagattribute List ListNumbering /Description
507 \halign{\qquad#\quad\hfil&#\hfil\cr
508 ⟦jobname⟧&The jobname.\cr
509 ⟦instance⟧&The primitive metapost instance.\cr
510 ⟦results⟧&A linked list of unretrieved images.\cr
511 ⟦status⟧&The last exit status (will never decrease).\cr
512 ⟦catcodes⟧&Number of the catcode table used with ⟦btex ... etex⟧.\cr
513 ⟦env⟧&The lua environment for ⟦runscript⟧.\cr}
514
515 Default values for the format and number system are available in the
516 ⟦*M.default_format⟧ and ⟦*M.default_mathmode⟧ variables.
517 The full initialisation sequence for new instances (i.e. the first metapost
518 chunk, that is executed automatically) is contained in the ⟦*M.init_code⟧
519 table.
520
521 The table passed to ⟦env⟧ defaults to a copy of the global table ⟦_G⟧, and will
522 be augmented with the contents of ⟦*M.mp_functions⟧. You can add your own
523 functions to this table, if you wish.
524
525 \subsection Adding new metapost specials % 2
526
527 You can extend this package by adding new metapost specials. Specials should
528 have the form ⟦"identifier: instructions"⟧ and can be added as pre- or
529 postscript to metapost objects. A single object can carry multiple specials and a
530 ⟦*special "..."⟧ statement is equivalent to an empty object with a single
531 prefix.
532
533 Handling of specials is specified in three lua tables: ⟦*M.specials⟧,
534 ⟦*M.prescripts⟧ and ⟦*M.postscripts⟧.
535 The ⟦identifier⟧ above should equal the key of an entry in the relevant table,
536 while the value of an entry in one of these tables should be a function with
537 three parameters: the internal image processor state, the ⟦instructions⟧ from
538 above and the metapost object itself.
539
540 If the ⟦identifier⟧ of a prescript is present in the first table, the
541 corresponding function will replace normal object processing.
542 Only one prescript may match with this table.
543 Functions in the the other two tables will run before or after normal
544 processing.
545
546 Specials can store information in the ⟦user⟧ table of the picture that is being
547 processed; this information is still available inside the ⟦*finish_mpfigure⟧
548 callback that is executed just before the processed image is surrounded by
549 properly-dimensioned boxes. If a ⟦user.save_fn⟧ function is defined, it will
550 replace the normal saving of the image to the image list and the image node
551 list will be flushed.
552
553 \subsection Logs and debugging % 2
554
555 Metapost log output of every processed chunk of metapost code will be printed
556 to the main log file in a quoted form.
557 The logs will be duplicated to the terminal if an error occurs or if the
558 variable ⟦*M.on_line⟧ is ⟦true⟧ (the default is ⟦false⟧, but set to ⟦true⟧ in
559 the stand-alone format files).
560 Because a single error message might trigger many others, log output to the
561 terminal (but not the log file) will be cut after a certain number of errors:
562 this behaviour is governed by the ⟦*M.max_errprint⟧ variable (default ⟦1⟧; set
563 to ⟦0⟧ to disable).
564
565 You can enable (global) debugging by saying ⟦*debug_pdf⟧ to metapost,
566 ⟦*\debugmetapost⟧ to tex or ⟦*M.enable_debugging()⟧ to lua. This will write
567 out a summary of metapost object information to the pdf file, just above the
568 pdf instructions that object was translated into. For this purpose, the pdf
569 will be generated uncompressed. Additionally, the metapost code itself will be
570 echoed to the log, as well as ⟦runscript⟧ and ⟦maketext⟧ invocations, and
571 a small summary of every generated image will be written to log and terminal.
572
573 For debugging the results of ⟦maketext⟧ and the like, you can set the
574 ⟦*debug_tex_bboxes⟧ variable to ⟦true⟧ and have their resulting bounding boxes
575 drawn on the pdf.
576
577
578 %
579
580 \endmanual
581