path: root/macros/luatex/generic/minim-mp/minim-mp.doc

\input minim-doc.sty

\manual{minim-mp}

\ifchapter \chapter Metapost

\else \startmetadata
    author   {Esger Renkema}
    title    {minim-mp}
    date     {2022-03-03}
    version  {2022/1.1}
    keywords {LuaTeX; Plain TeX; MetaPost; mplib}
    stopmetadata
\maketitle \fi

This package offers low-level mplib integration for plain luatex.
The use of multiple simultaneous metapost instances is supported, as well as 
running tex or lua code from within metapost.
In order to use it, simply say ⟦\input minim-mp.tex⟧.

After this, ⟦*\directmetapost [ options ] { mp code }⟧ will result in a series 
of images corresponding to the ⟦beginfig ... endfig⟧ statements in your
⟦mp code⟧. Every image will be in a box of its own.

Every call to ⟦\directmetapost⟧ opens and closes a separate metapost instance. 
If you want your second call to remember the first, you will have to define 
a persistent metapost instance. This will also give you more control over image 
extraction. See below under „Metapost instances”. The ⟦options⟧ will also be 
explained there (for simple cases, you will not need them).

The logging of the metapost run will be included in the regular log file. If an 
error occurs, the logging will also be shown on the terminal.

This package can also be used as a stand-alone metapost compiler. Saying
\stopformulatagging$$\hbox{⟦luatex  --fmt=minim-mp  your_file.mp⟧}$$\startformulatagging
will create a pdf file of all images in ⟦your_file.mp⟧, in order, with page 
sizes adjusted to image dimensions. You might need generate the format first, 
this is done with
\stopformulatagging$$\hbox{⟦luatex  --ini  minim-mp.ini⟧}$$\startformulatagging
Use minim-lamp instead of minim-mp for an experimental latex-based version 
of the minim-mp format.

\section Metapost instances %1

For more complicated uses, you can define your own instances by saying
⟦*\newmetapostinstance [ options ] \id⟧.
An instance can be closed with ⟦*\closemetapostinstance \id⟧.
These are the options you can use:

\smallskip\smallskip\automarktable
\halign{#\quad\hfil&#\quad\hfil&#\hfil\cr
Option&Default&Description\cr
⟦jobname⟧&⟦':metapost:'⟧&Used in error messages.\cr
⟦format⟧&⟦'plain.mp'⟧&Format to initialise the instance with.\cr
⟦math⟧&⟦'scaled'⟧&One of ⟦scaled⟧, ⟦decimal⟧ or ⟦double⟧.\cr
⟦seed⟧&⟦nil⟧&Random seed for this instance.\cr
⟦catcodes⟧&⟦0⟧&Catcode table for ⟦btex ... etex⟧.\cr
⟦env⟧&copy of ⟦_G⟧&Lua environment; see below.\cr
}\smallskip

Now that you have your own instance, you can run chunks of metapost code in it 
with ⟦*\runmetapost \id { code }⟧. Any images that your code may have contained 
will have to be extracted explicitly. This is possible in a number of ways, 
although each image can be retrieved only once.

⟦*\getnextmpimage  \id⟧
– Writes the first unretrieved image to the current node list.
There, the image will be contained in a single box node.

⟦*\getnamedmpimage \id {name}⟧
– Retrieves an image by name
regardless of its position,
and writes it to the current node list.

⟦*\boxnextmpimage  \id box-nr⟧
– Puts the next unretrieved image in box ⟦box-nr⟧. The number may be anything 
tex can parse as a number.

⟦*\boxnamedmpimage \id box-nr {name}⟧
– Puts the image named ⟦name⟧ in box ⟦box-nr⟧.

Say ⟦*\remainingmpimages \id⟧ for the number of images not yet retrieved.
Finally, as a shorthand, ⟦*\runmetapostimage \id { code }⟧ will add
⟦beginfig ... endfig⟧ to your ⟦code⟧ and write the resulting image immediately 
to the current list.


\section Running tex from within metapost %1

You can include tex snippets with either ⟦*maketext "tex text"⟧ or
⟦*btex ... etex⟧ statements. The tex code will be executed in the current 
environment without an extra grouping level. The result of either statement at 
the place where it is invoked is an image object of the proper dimensions that 
can be moved, scaled, rotated and mirrored. You can even specify a colour. Its 
contents, however, will only be added afterwards and are invisible to metapost.

Arbitrary tex statements may be included in ⟦*verbatimtex ... etex⟧, which may 
occur anywhere. These ⟦btex⟧ and ⟦verbatimtex⟧ statements are executed in the 
order they are given.

Previously-defined box resources can be included with ⟦*boxresource(nr)⟧. The 
result will be an image object with the proper dimensions. This image can be 
transformed in any way you like, but you cannot inspect the contents of the 
resource within metapost.

You can also use metapost’s ⟦*infont⟧ operator, which restricts the text 
to-be-typeset to a single font, but returns an ⟦picture⟧ containing a ⟦picture⟧ 
for each character. The right-hand argument of ⟦infont⟧ should either be 
a (numerical) font~id or the (cs)name of a font (without backslash).

One possible use of the ⟦infont⟧ operator is setting text along curves:

⟦beginfig(1)
    save t, w, r, a; picture t;
    t = "Running TeX from within MetaPost" infont "tenrm";
    w = xpart lrcorner t = 3.141593 r;
    for c within t :
        x := xpart (llcorner c + lrcorner c)/2;
        a := 90 - 180 x/w;
        draw c rotatedaround((x,0), a)
               shifted (-r*sind(a)-x, r*cosd(a));
    endfor
endfig;⟧
\vskip-2\parskip plus 2\parskip
\quitvmode\hfil
\startelement alt {The text ‘Running TeX from within MetaPost’ set along a half-circle.} {Figure}%
\stoptagging\directmetapost{%
beginfig(1)
    save t, w, r, a; picture t;
    t = "Running TeX from within MetaPost" infont "tenrm";
    w = xpart lrcorner t = 3.141593 r;
    for c within t :
        x := xpart (llcorner c + lrcorner c)/2;
        a := 90 - 180 x/w;
        draw c rotatedaround((x,0), a)
               shifted (-r*sind(a)-x, r*cosd(a));
    endfor
endfig;}\starttagging \stopelement{Figure}

For the greatest amount of control, however, you will need the ⟦*glyph g of f⟧ 
operator, which returns the contours that make up a glyph. It is a bit more 
versatile than its traditional metapost counterpart: ⟦g⟧ may also be the name 
of the glyph instead of its index, while ⟦f⟧ can be a font~id or font name (as 
with ⟦infont⟧).

A variant of ⟦glyph of⟧ is the ⟦*contours t of f⟧ macro: it first typesets the 
string ⟦t⟧ in the same way as ⟦infont⟧ does (so that kerning and font shaping 
are applied), but returns a (comma-separated) list of contours, such as may be 
used in a ⟦for⟧ loop. Due to rounding errors, the glyphs will not match exactly.

Be aware that the contours returned by these operators may be disjoint: 
a letter ⟦o⟧, for example, will consists of two. This means you cannot recreate 
the characters by just filling each contour: this would turn the ⟦o⟧ into 
a filled-in circle. Instead, you must use ⟦multifill⟧ on the entire output of 
⟦glyph of⟧ or ⟦contours of⟧ (see the next section).


\section Partial paths and the even-odd rule %1

You can fill or draw two or more disjoint paths in one go by using ⟦*nofill⟧ as 
drawing operator for all paths but the last. This may make it easier to cut 
something out of a shape, since you do not have to worry about stitching the 
paths together.

While metapost fills paths according to the winding number, the pdf format also 
supports filling according to the even-odd rule. This has been made possible 
with the ⟦*eofill⟧ and ⟦*eofilldraw⟧ drawing statements, which can of course 
also be used as the final statement after a series of nofills.

The macros ⟦*multi(draw|fill|filldraw|eofill|eofilldraw)⟧ take a list of paths 
between parentheses and can be followed by the usual drawing options.
For example,
⟦multidraw (contours "example" of "tenbf") withpen currentpen scaled 1/10;⟧
will give the word%
\markelement{Span}{\setactualtext{example }
\directmetapost{beginfig(1) multidraw (contours "example" of "tenbf")
withpen currentpen scaled 1/10; baseline 0; endfig;}}
in a thin outline.

Finally, two handy clipping macros have been added:
⟦*clipout⟧ and ⟦*clipto⟧, which both receive a list of paths as a ‘text’ 
parameter and either clip their ensemble out of the picture, or the picture to 
the ensemble.


\section Running lua from within metapost %1

You can call out to lua with ⟦*runscript "lua code"⟧. For this purpose, each 
metapost instance carries around its own lua environment so that assignments 
you make are local to the instance. (You can of course order the global 
environment to be used by giving ⟦env = _G⟧ as option to 
⟦\newmetapostinstance⟧.)

If your lua snippet returns nothing, the ⟦runscript⟧ call will be invisible to 
metapost. If on the other hand it does return a value, that value will have to 
be translated to metapost. Numbers and strings will be returned as they are
(so make sure the string is surrounded by quotes if you want to return 
a metapost string). You can return a point or colour by returning an array of 
two to four elements. For other return values, ⟦tostring()⟧ will be called.

Do keep in mind that metapost and lua represent numbers in different ways and 
that rounding errors may occur. For instance, metapost’s ⟦decimal epsilon⟧ 
returns ⟦0.00002⟧, which metapost understands as ⟦1/65536⟧, but lua as 
⟦1/50000⟧. Use the metapost macro ⟦*hexadecimal⟧ instead of ⟦decimal⟧ for 
passing unambiguous numbers to lua.

Additionally, you should be aware that metapost uses slightly bigger points 
than tex, so that ⟦epsilon⟧ when taken as a dimension is not quite equal to 
⟦1sp⟧. Use the metapost macro ⟦*scaledpoints⟧ for passing to lua a metapost 
dimension as an integral number of scaled points.


\section Tiling patterns %1

The ⟦*withpattern(<name>)⟧ added to a ⟦fill⟧ statement will fill the path with 
a pattern instead of a solid colour. If the patterns contains no colour 
information of itself, it will have the colour given by ⟦withcolor⟧.
Stroking operations (the ⟦draw⟧ part) will not be affected.
Patterns will always look the same, irrespective of any transformations you 
apply to the picture.

To define a pattern, sketch it between
⟦*beginpattern(<name>) ... endpattern(xstep, ystep);⟧
where ⟦<name>⟧ is a suffix and ⟦(xstep, ystep)⟧ are the horizontal and vertical 
distances between applications of the pattern.
Inside the definition, you can draw the pattern using whatever coordinates you 
like; assign a value to the ⟦*matrix⟧ transformation to specify how the pattern 
should be projected onto the page. This ⟦matrix⟧ will also be applied to 
⟦xstep⟧ and ⟦ystep⟧.

You can also change the internal variable ⟦*tilingtype⟧ and the normal variable 
⟦*painttype⟧, although the latter will be set to~1 automatically if you use any 
colour inside the pattern definition. Consult the pdf specification for more 
information on these parameters.

You can use text inside patterns, as in this example:
\hfill \vbox to 0pt{
\startelement alt{A circle filled with red As in a rectangular pattern.}{Figure}
\directmetapost{
% define the pattern
picture letter; letter = maketext("a");
beginpattern(a)
    draw letter rotated 45;
    matrix = identity rotated 45;
endpattern(12pt,12pt);
% use the pattern
beginfig(1)
    fill fullcircle scaled 3cm withpattern(a) withcolor 3/4red;
    draw fullcircle scaled 3cm withpen pencircle scaled 1;
endfig;}\stopelement{Figure}\vss}\hskip10pt\strut
\par\nobreak
⟦% define the pattern
picture letter; letter = maketext("a");
beginpattern(a)
    draw letter rotated 45;
    matrix = identity rotated 45;
endpattern(12pt,12pt);
% use the pattern
beginfig(1)
    fill fullcircle scaled 3cm withpattern(a) withcolor 3/4red;
    draw fullcircle scaled 3cm withpen pencircle scaled 1;
endfig;⟧

A small pattern library is available in the ⟦*minim-hatching.mp⟧ file; see the 
accompanying documentation sheet for an overview of patterns.


\section Other metapost extensions %1

You can set the baseline of an image with ⟦*baseline(p)⟧. There, ⟦p⟧ must 
either be a point through which the baseline should pass, or a number (where an 
x~coordinate of zero will be added). Transformations will be taken into 
account, hence the specification of two coordinates. The last given baseline 
will be used.

You can write to tex’s log directly with ⟦*texmessage "hello"⟧.

You can write direct pdf statements with ⟦*special "pdf: statements"⟧ and you 
can add comments to the pdf file with ⟦*special "pdfcomment: comments"⟧.
Say ⟦*special "latelua: lua code"⟧ to insert a ⟦late_lua⟧ whatsit.
All three specials can also be given as pre- or postscripts to another object.
In that case, they will be added before or after the object they are attached to.
Do note that all ⟦special⟧ statements will appear at the beginning of the 
image; use pre- and postscripts to drawing statements if the order matters.

Minim-mp also provides a few elementary macros and constants that are 
conspicuously absent from plain.mp; I hope their addition is uncontroversial.
The constants are ⟦*pi⟧ (355/113), ⟦*fullsquare⟧, ⟦*unitcircle⟧ and the 
cmyk-colours ⟦*cyan⟧, ⟦*magenta⟧, ⟦*yellow⟧ and ⟦*key⟧. The macros are 
⟦*clockwise⟧, ⟦*xshifted⟧, ⟦*yshifted⟧, ⟦*hflip⟧ and ⟦*vflip⟧, where the flips 
are defined in such a way that ⟦p & hflip p⟧ gives the expected result.


\section Lua interface %1

In what follows, you should assume ⟦M⟧ to be the result of
\stopformulatagging$$\hbox{⟦M = require('minim-mp')⟧}$$\startformulatagging
as this package does not claim a table in the global environment for itself.

You can open a new instance with ⟦*nr = M.open {options}⟧.
This returns an index in the ⟦*M.instances⟧ table.
Run code with ⟦*M.run (nr, code)⟧ and close the instance with ⟦*M.close (nr)⟧.
Images can be retrieved only with ⟦*box_node = M.get_image(nr, [name])⟧; omit 
the ⟦name⟧ to select the first image.
Say ⟦*nr_remaining = M.left(nr)⟧ for the number of remaining images.

Each metapost instance is a table containing the following entries:

\smallskip\smallskip
\marktableaslist \halign{\qquad#\quad\hfil&#\hfil\cr
⟦jobname⟧&The jobname.\cr
⟦instance⟧&The primitive metapost instance.\cr
⟦results⟧&A linked list of unretrieved images.\cr
⟦status⟧&The last exit status (will never decrease).\cr
⟦catcodes⟧&Number of the catcode table used with ⟦btex ... etex⟧.\cr
⟦env⟧&The lua environment for ⟦runscript⟧.\cr}


\section Debugging %1

You can enable (global) debugging by saying ⟦*debug_pdf⟧ to metapost or 
⟦*M.enable_debugging()⟧ to lua. This will write out a summary of metapost 
object information to the pdf file, just above the pdf instructions that object 
was translated into. For this purpose, the pdf will be generated uncompressed. 
Additionally, a small summary of every generated image will be written to log 
and terminal.


\section Extending metapost %1

You can extend this package by adding new metapost specials. Specials should 
have the form ⟦"identifier: instructions"⟧ and can be added as pre- or 
postscript to metapost objects. A single object can carry multiple specials and a
⟦*special "..."⟧ statement is equivalent to an empty object with a single 
prefix.

Handling of specials is specified in three lua tables: ⟦*M.specials⟧, 
⟦*M.prescripts⟧ and ⟦*M.postscripts⟧.
The ⟦identifier⟧ above should equal the key of an entry in the relevant table,
while the value of an entry in one of these tables should be a function with 
three parameters: the internal image processor state, the ⟦instructions⟧ from 
above and the metapost object itself.

If the ⟦identifier⟧ of a prescript is present in the first table, the 
corresponding function will replace normal object processing.
Only one prescript may match with this table.
Functions in the the other two tables will run before or after normal 
processing.

Specials can store information in the ⟦user⟧ table of the picture that is being 
processed; this information is still available inside the ⟦*finish_mpfigure⟧ 
callback that is executed just before the processed image is surrounded by 
properly-dimensioned boxes.

The ⟦*M.init_code⟧ table contains the code used for initialing new instances. 
In it, the string ⟦INIT⟧ will be replaced with the value of the ⟦format⟧ option 
(normally ⟦plain.mp⟧).

\endmanual %