| 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⟧© 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 |
|