summaryrefslogtreecommitdiff
path: root/macros/luatex/generic/minim-mp/minim-mp.doc
diff options
context:
space:
mode:
Diffstat (limited to 'macros/luatex/generic/minim-mp/minim-mp.doc')
-rw-r--r--macros/luatex/generic/minim-mp/minim-mp.doc72
1 files changed, 57 insertions, 15 deletions
diff --git a/macros/luatex/generic/minim-mp/minim-mp.doc b/macros/luatex/generic/minim-mp/minim-mp.doc
index 2f7541ba75..9429544d8e 100644
--- a/macros/luatex/generic/minim-mp/minim-mp.doc
+++ b/macros/luatex/generic/minim-mp/minim-mp.doc
@@ -8,8 +8,8 @@
\else \startmetadata
author {Esger Renkema}
title {minim-mp}
- date {2023-10-20}
- version {2023/1.3}
+ date {2024-01-05}
+ version {2024/1.4}
keywords {LuaTeX; Plain TeX; MetaPost; mplib}
stopmetadata
\maketitle \fi
@@ -147,7 +147,7 @@ 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{%
+\startsinglecontentitem\directmetapost{%
beginfig(1)
save t, w, r, a; picture t;
t = "Running TeX from within MetaPost" infont "tenrm";
@@ -158,7 +158,7 @@ beginfig(1)
draw c rotatedaround((x,0), a)
shifted (-r*sind(a)-x, r*cosd(a));
endfor
-endfig;}\starttagging \stopelement{Figure}
+endfig;}\stopsinglecontentitem \stopelement{Figure}
By default, the ⟦maketext⟧ operator is used for typesetting labels. You can,
however, order de ⟦label⟧ macro to use ⟦infont⟧ instead by setting
@@ -199,9 +199,9 @@ 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 }
+\markelement{Span}{\setactualtext{example }\startsinglecontentitem\space
\directmetapost{beginfig(1) multidraw (contours "example" of "tenbf")
-withpen currentpen scaled 1/10; baseline 0; endfig;}}
+withpen currentpen scaled 1/10; baseline 0; endfig;}\stopsinglecontentitem}
in a thin outline.
Finally, two handy clipping macros have been added:
@@ -233,9 +233,9 @@ If your lua snippet returns nothing, the ⟦runscript⟧ call will be invisible
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.
-
+a metapost string). You can return a point, colour or transform by returning an
+array of two to six elements (excluding five). For other return values,
+⟦tostring()⟧ will be called.
\section Passing values to lua
@@ -275,7 +275,7 @@ and have ⟦texvariable jobname⟧ work as expected.
For accessing count, dimen, attribute or toks registers, the macros are
⟦*tex.count⟧ ⟦[number]⟧ or ⟦*tex.count⟧⟦.name⟧ [etc. etc.] for getting and
-⟦*set tex.count⟧ ⟦[number] = value⟧ or ⟦*tex.count⟧⟦.name = value⟧ etc. for
+⟦*set tex.count⟧ ⟦[number] = value⟧ or ⟦*set tex.count⟧⟦.name = value⟧ etc. for
setting values.
@@ -305,7 +305,7 @@ 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{
+\startsinglecontentitem \directmetapost{
% define the pattern
picture letter; letter = maketext("a");
beginpattern(a)
@@ -316,7 +316,8 @@ endpattern(12pt,12pt);
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
+endfig;}\stopsinglecontentitem
+\stopelement{Figure}\vss}\hskip10pt\strut
\par\nobreak
⟦% define the pattern
picture letter; letter = maketext("a");
@@ -333,6 +334,41 @@ endfig;⟧
A small pattern library is available in the ⟦*minim-hatching.mp⟧ file; see the
accompanying documentation sheet for an overview of patterns.
+\section Advanced PDF graphics % 1
+
+You can use ⟦*savegstate⟧ and ⟦*restoregstate⟧ for inserting the ⟦q⟧ and ⟦Q⟧
+operators; these must always be paired, or horrible errors will occur. You may
+need them if you use ⟦*setgstate(<params>)⟧ for modifying the extended
+graphical state (ExtGState). The ⟦params⟧ must be a comma-separated
+⟦Key=value⟧ list, with all ⟦value⟧s being suffixes. The latter restriction may
+require the use of additional variables, but as this is a very low-level
+command, it is best to wrap it in a more specialised macro anyway.
+The ⟦*withgstate (<params>)⟧ can be added to a drawing statement and includes
+saving/restoring the graphical state.
+
+Note that while you could try and use ⟦setgstate⟧ for modifying variables like
+the line cap or dash pattern, the result of doing so will be unpredictable,
+since such changes will be invisible to metapost. Its intended use is
+restricted to graphics parameters outside the scope of metapost.
+
+For applying transparency, ⟦*setalpha(a)⟧ updates the ⟦CA⟧ and ⟦ca⟧ parameters
+as a stand-alone command and ⟦*withalpha(a)⟧ can be used in a drawing statement
+where it will save/restore the graphical state around it. For applying
+transparency to an ensemble of drawing statements, ⟦*transparent (a) <picture>⟧
+will create and insert the proper transparency group. The transparency group
+attributes can be set with the string internal ⟦transparency_group_attrs⟧,
+while for all three macros the blend mode can be set with the string internal
+⟦blend_mode⟧ (it will be added whenever set).
+
+A transparency group is a special kind of XForm, and these can be created from
+withing metapost: ⟦<id> =⟧ ⟦*saveboxresource (<attributes>) <picture>⟧ returns
+a number identifying the resource and can be fed attributes in the same way as
+⟦setgstate⟧. XForms defined through metapost are available to other metapost
+instances, but not to tex, though the macro painting them, ⟦*boxresource <id>⟧,
+also accepts identifiers of tex-defined box resources. There remains a subtle
+difference, however: metapost-defined box resources are placed at their
+original origin.
+
\section Other metapost extensions % 1
@@ -342,7 +378,9 @@ 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 to tex’s log directly with ⟦*texmessage "hello";⟧. You can feed
+it a comma-separated list of strings and numbers, which will be passed through
+⟦string.format()⟧ first.
You can write direct pdf statements with ⟦*special "pdf: statements"⟧ and you
can add comments to the pdf file with ⟦*special "pdfcomment: comments"⟧.
@@ -381,7 +419,9 @@ 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
+\marktableaslist
+\tagattribute List ListNumbering /Description
+\halign{\qquad#\quad\hfil&#\hfil\cr
⟦jobname⟧&The jobname.\cr
⟦instance⟧&The primitive metapost instance.\cr
⟦results⟧&A linked list of unretrieved images.\cr
@@ -424,7 +464,9 @@ 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.
+properly-dimensioned boxes. If a ⟦user.save_fn⟧ function is defined, it will
+replace the normal saving of the image to the image list and the image node
+list will be flushed.
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