-
Notifications
You must be signed in to change notification settings - Fork 11
/
Copy pathluamplib.dtx
6057 lines (5985 loc) · 213 KB
/
luamplib.dtx
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
% \iffalse meta-comment -- by the way, this file contains UTF-8
%
% Copyright (C) 2008-2025 by Hans Hagen, Taco Hoekwater, Elie Roux,
% Manuel Pégourié-Gonnard, Philipp Gesang and Kim Dohyun.
% Currently maintained by Kim Dohyun.
% Support: <https://github.com/lualatex/luamplib>
%
% This work is under the GPL v2.0 license.
%
% This work consists of the main source file luamplib.dtx
% and the derived files
% luamplib.sty, luamplib.lua and luamplib.pdf.
%
% Unpacking:
% tex luamplib.dtx
%
% Documentation:
% lualatex luamplib.dtx
%
%<*ignore>
\begingroup
\def\x{LaTeX2e}%
\expandafter\endgroup
\ifcase 0\ifx\install y1\fi\expandafter
\ifx\csname processbatchFile\endcsname\relax\else1\fi
\ifx\fmtname\x\else 1\fi\relax
\else\csname fi\endcsname
%</ignore>
%<*install>
\input docstrip.tex
\Msg{************************************************************************}
\Msg{* Installation}
\Msg{* Package: luamplib - metapost package for LuaTeX.}
\Msg{************************************************************************}
\keepsilent
\askforoverwritefalse
\let\MetaPrefix\relax
\preamble
See source file '\inFileName' for licencing and contact information.
\endpreamble
\let\MetaPrefix\DoubleperCent
\generate{%
\usedir{tex/luatex/luamplib}%
\file{luamplib.sty}{\from{luamplib.dtx}{package}}%
}
\def\MetaPrefix{-- }
\def\luapostamble{%
\MetaPrefix^^J%
\MetaPrefix\space End of File `\outFileName'.%
}
\def\currentpostamble{\luapostamble}%
\generate{%
\usedir{tex/luatex/luamplib}%
\file{luamplib.lua}{\from{luamplib.dtx}{lua}}%
}
\obeyspaces
\Msg{************************************************************************}
\Msg{*}
\Msg{* To finish the installation you have to move the following}
\Msg{* files into a directory searched by TeX:}
\Msg{*}
\Msg{* luamplib.sty luamplib.lua}
\Msg{*}
\Msg{* Happy TeXing!}
\Msg{*}
\Msg{************************************************************************}
\endbatchfile
%</install>
%<*ignore>
\fi
%</ignore>
%<*driver>
\NeedsTeXFormat{LaTeX2e}
\ProvidesFile{luamplib.drv}%
[2025/02/18 v2.37.1 Interface for using the mplib library]%
\documentclass{ltxdoc}
\usepackage{metalogo,multicol,xspace}
\usepackage[x11names]{xcolor}
%
\def\primarycolor{DodgerBlue4} %%-> rgb 16 78 139 | #104e8b
\def\secondarycolor{Goldenrod4} %%-> rgb 139 105 200 | #8b6914
%
\usepackage[
bookmarks=true,
colorlinks=true,
linkcolor=\primarycolor,
urlcolor=\secondarycolor,
citecolor=\primarycolor,
pdftitle={The luamplib package},
pdfsubject={Interface for using the mplib library},
pdfauthor={Hans Hagen, Taco Hoekwater, Elie Roux, Philipp Gesang \& Kim Dohyun},
pdfkeywords={luatex, lualatex, mplib, metapost}
]{hyperref}
\usepackage{fontspec}
\setmainfont[
Numbers = OldStyle,
Ligatures = TeX,
BoldFont = {Linux Libertine O Bold},
ItalicFont = {Linux Libertine O Italic},
SlantedFont = {Linux Libertine O Italic},
]{Linux Libertine O}
\setmonofont[Scale=MatchLowercase]{InconsolataN}
%setsansfont[Ligatures=TeX]{Linux Biolinum O}
\setsansfont[UprightFont=*Medium,BoldFont=*Heavy,Ligatures=TeX,Scale=MatchLowercase]{Iwona}
%setmathfont{XITS Math}
\usepackage{hologo}
\newcommand\ConTeXt {Con\TeX t\xspace}
\newcommand*\email [1] {<\href{mailto:#1}{#1}>}
\newcommand \file {\nolinkurl}
\newcommand*\metapost {\textsc{metapost}\xspace}
\newcommand*\mplib {\pkg{mplib}\xspace}
\begin{document}
\DocInput{luamplib.dtx}%
\end{document}
%</driver>
% \fi
%
% \CheckSum{0}
%
% \CharacterTable
% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
% Digits \0\1\2\3\4\5\6\7\8\9
% Exclamation \! Double quote \" Hash (number) \#
% Dollar \$ Percent \% Ampersand \&
% Acute accent \' Left paren \( Right paren \)
% Asterisk \* Plus \+ Comma \,
% Minus \- Point \. Solidus \/
% Colon \: Semicolon \; Less than \<
% Equals \= Greater than \> Question mark \?
% Commercial at \@ Left bracket \[ Backslash \\
% Right bracket \] Circumflex \^ Underscore \_
% Grave accent \` Left brace \{ Vertical bar \|
% Right brace \} Tilde \~}
%
% \title{The \pkg{luamplib} package}
% \author{Hans Hagen, Taco Hoekwater, Elie Roux, Philipp Gesang and Kim Dohyun\\
% Current Maintainer: Kim Dohyun\\
% Support: \url{https://github.com/lualatex/luamplib}}
% \date{2025/02/18 v2.37.1}
%
% \maketitle
%
% \begin{abstract}
% Package to have \metapost code typeset directly in a document with \LuaTeX.
% \end{abstract}
%
% \section{Documentation}
%
% This package aims at providing a simple way to typeset directly \metapost
% code in a document with \LuaTeX. \LuaTeX\ is built with the Lua
% \mplib library, that runs \metapost code. This package is basically a
% wrapper for the Lua \mplib functions and some \TeX\
% functions to have the output of the \mplib functions in the pdf.
%
% Using this package is easy: in Plain, type your \metapost code between the
% macros \cs{mplibcode} and \cs{endmplibcode}, and in \LaTeX\ in the
% |mplibcode| environment.
%
% The resulting \metapost figures are put in a \TeX\ |hbox| with dimensions
% adjusted to the \metapost code.
%
% The code of luamplib is basically from the |luatex-mplib.lua| and |luatex-mplib.tex| files
% from \ConTeXt. They have been adapted to \LaTeX\ and Plain by Elie Roux and
% Philipp Gesang and new functionalities have been added by Kim Dohyun.
% The most notable changes are:
%
% \begin{itemize}
% \item possibility to use |btex ... etex| to typeset \TeX\ code.
% |textext()| is a more versatile macro equivalent to |TEX()| from \pkg{TEX.mp}.
% |TEX()| is also allowed and is a synonym of |textext()|.
% The argument of
% \mplib's primitive |maketext| will also be processed by the same routine.
%
% \item possibility to use |verbatimtex ... etex|, though it's behavior cannot
% be the same as the stand-alone \pkg{mpost}.
% Of course you cannot include \cs{documentclass}, \cs{usepackage} etc.
% When these \TeX\ commands are found in |verbatimtex ... etex|, the entire code will be
% ignored.
% The treatment of |verbatimtex| command has changed a lot since v2.20:
% see \hyperlink{mpliblegacybehavior}{below \S\,1.1}.
%
% \item in the past,
% the package required PDF mode in order to have some output.
% Starting with version 2.7 it works in DVI mode as well, though
% DVIPDFMx is the only DVI tool currently supported.
% \end{itemize}
%
% It seems to be convenient to divide the explanations of some more changes and cautions
% into three parts: \TeX, \textsc{MetaPost}, and Lua interfaces.
%
% \subsection{\TeX}
%
% \subsubsection{\cs{mplibforcehmode}}
% When this macro is declared, every \metapost figure box will be
% typeset in horizontal mode, so \cs{centering}, \cs{raggedleft} etc
% will have effects. \cs{mplibnoforcehmode}, being default, reverts this
% setting. (Actually these commands redefine \cs{prependtomplibbox}; you
% can redefine this command with anything suitable before a box.)
%
% \subsubsection{\cs{everymplib\{...\}}, \cs{everyendmplib\{...\}}}
% \cs{everymplib} and \cs{everyendmplib} redefine
% the lua table containing \metapost code
% which will
% be automatically inserted at the beginning and ending of each \metapost code chunk.
%\begin{verbatim}
% \everymplib{ beginfig(0); }
% \everyendmplib{ endfig; }
% \begin{mplibcode}
% % beginfig/endfig not needed
% draw fullcircle scaled 1cm;
% \end{mplibcode}
%\end{verbatim}
%
% \subsubsection{\cs{mplibsetformat\{plain\textbar metafun\}}}
% There are (basically) two formats for \metapost: \emph{plain} and
% \emph{metafun}. By default, the \emph{plain} format is used, but you can set
% the format to be used by future figures at any time using
% \cs{mplibsetformat}\marg{format name}.
%
% \textsc{n.b.} As \emph{metafun} is such a complicated format,
% we cannot support all the functionalities producing special effects provided by \emph{metafun}.
% At least, however, transparency (actually opacity), shading (gradient colors) and transparency group
% are fully supported,
% and outlinetext is supported by our own alternative |mpliboutlinetext|
% (see \hyperlink{mpliboutlinetext}{below \S\,1.2}).
% You can try other effects as well, though we did not fully tested their proper functioning.
%
% \begin{description}
% \item[transparency]
% (|texdoc metafun| \S\,8.2) Transparency is so simple that you can apply it to an object,
% with \emph{plain} format as well as \emph{metafun},
% just by appending |withprescript| |"tr_transparency=|\meta{number}|"| to the sentence.
% ($0 \le \meta{number} \le 1$)
%
% From v2.36, |withtransparency| is available with \emph{plain} as well.
% See \hyperlink{luamplibtransparency}{below} \S\,1.2.
%
% \item[shading]
% (|texdoc metafun| \S\,8.3) One thing worth mentioning about shading is:
% when a color expression is given in string type,
% it is regarded by luamplib as
% a color expression of \TeX\ side.
% For instance, when |withshadecolors("orange", 2/3red)| is given, the first color |"orange"| will be
% interpreted as a \pkg{color}, \pkg{xcolor} or \pkg{l3color}'s expression.
%
% From v2.36, shading is available with \emph{plain} format as well with extended functionality.
% See \hyperlink{luamplibshading}{below} \S\,1.2.
%
% \item[transparency group]
% \hypertarget{metafunformat}{}\relax
% (|texdoc metafun| \S\,8.8)
% As for transparency group, the current \emph{metafun} document is not correct.
% The true syntax is:
%\begin{verbatim}
% draw <picture>|<path> asgroup <string>
%\end{verbatim}
% where \meta{string} should be |""| (empty), |"isolated"|, |"knockout"|, or |"isolated,knockout"|.
% Beware that currently many of the PDF rendering applications, except Adobe Acrobat Reader,
% cannot properly render the isolated or knockout effect.
%
% Transparency group is available with \emph{plain} format as well, with extended functionality.
% See \hyperlink{transparencygroup}{below} \S\,1.2.
% \end{description}
%
% \subsubsection{\cs{mplibnumbersystem\{scaled\textbar double\textbar decimal\}}}
% Users can choose |numbersystem| option.
% The default value is |scaled|, which can be changed
% by declaring \cs{mplibnumbersystem\{double\}} or
% \cs{mplibnumbersystem\{decimal\}}.
%
% \subsubsection{\cs{mplibshowlog\{enable\textbar disable\}}}
% Default: |disable|.
% When \cs{mplibshowlog\{enable\}}\footnote{As for user's setting,
% |enable|, |true| and |yes| are identical;
% |disable|, |false| and |no| are identical.} is declared, log messages returned by
% the \metapost process will be printed to the |.log| file.
% This is the \TeX{} side interface for |luamplib.showlog|.
%
% \subsubsection{\cs{mpliblegacybehavior\{enable\textbar disable\}}}
% \hypertarget{mpliblegacybehavior}{}\relax
% By default, \cs{mpliblegacybehavior\{enable\}}
% is already declared for backward compatibility,
% in which case \TeX\ code in
% |verbatimtex| |...| |etex| that comes just before |beginfig()|
% will be inserted before the
% following \metapost figure box. In this way,
% each figure box can be freely moved horizontally or vertically.
% Also, a box number can be assigned to a figure box, allowing it to be
% reused later.
%\begin{verbatim}
% \mplibcode
% verbatimtex \moveright 3cm etex; beginfig(0); ... endfig;
% verbatimtex \leavevmode etex; beginfig(1); ... endfig;
% verbatimtex \leavevmode\lower 1ex etex; beginfig(2); ... endfig;
% verbatimtex \endgraf\moveright 1cm etex; beginfig(3); ... endfig;
% \endmplibcode
%\end{verbatim}
% \textsc{n.b.} \cs{endgraf} should be used instead of \cs{par} inside
% |verbatimtex ... etex|.
%
% On the other hand, \TeX\ code in |verbatimtex ... etex|
% between |beginfig()| and |endfig| will be inserted
% after flushing out the \metapost figure.
% As shown in the example below, |VerbatimTeX()| is a synonym of |verbatimtex| |...| |etex|.
%\begin{verbatim}
% \mplibcode
% D := sqrt(2)**7;
% beginfig(0);
% draw fullcircle scaled D;
% VerbatimTeX("\gdef\Dia{" & decimal D & "}");
% endfig;
% \endmplibcode
% diameter: \Dia bp.
%\end{verbatim}
%
% By contrast,
% when \cs{mpliblegacybehavior\{disable\}} is declared, any
% |verbatimtex| |...| |etex| will be executed, along with |btex| |...| |etex|,
% sequentially one by one.
% So, some \TeX\ code in |verbatimtex ... etex| will have effects on
% following |btex| |...| |etex| codes.
%\begin{verbatim}
% \begin{mplibcode}
% beginfig(0);
% draw btex ABC etex;
% verbatimtex \bfseries etex;
% draw btex DEF etex shifted (1cm,0); % bold face
% draw btex GHI etex shifted (2cm,0); % bold face
% endfig;
% \end{mplibcode}
%\end{verbatim}
%
% \subsubsection{\cs{mplibtextextlabel\{enable\textbar disable\}}}
% Default: |disable|.
% \cs{mplibtextextlabel\{enable\}} enables
% the labels typeset via |textext| instead of |infont| operator.
% So, |label("my text",origin)| thereafter is exactly the same as
% |label(textext("my text"),origin)|.
%
% \textsc{n.b.} In the background,
% luamplib redefines |infont| operator so that the right side
% argument (the font part) is totally ignored. Therefore the left side arguemnt (the text part)
% will be typeset with the current \TeX\ font.
%
% From v2.35, however, the redefinition of |infont| operator has been revised:
% when the character code of the text argument is less than $32$~(control characters),
% or is equal to $35$~(|#|), $36$~(|$|), \iffalse |$|\fi
% $37$~(|%|), $38$~(|&|), $92$~(|\|), $94$~(|^|),
% $95$~(|_|), $123$~(|{|), $125$~(|}|), $126$~(|~|) or $127$~(DEL),
% the original |infont| operator will be used instead of |textext| operator
% so that the font part will be honored.
% Despite the revision, please take care of |char| operator in the text argument,
% as this might bring unpermitted characters into \TeX.
%
% \subsubsection{\cs{mplibcodeinherit\{enable\textbar disable\}}}
% Default: |disable|.
% \cs{mplibcodeinherit\{enable\}} enables the inheritance
% of variables, constants, and macros defined by previous \metapost code chunks.
% On the contrary, \cs{mplibcodeinherit\{disable\}} will make
% each code chunk being treated as an independent instance, never
% affected by previous code chunks.
%
% \subsubsection{Separate \metapost instances}
% luamplib v2.22 has added the support for several named \metapost instances
% in \LaTeX{} |mplibcode| environment.
% Plain \TeX\ users also can use this functionality.
% The syntax for \LaTeX\ is:
%\begin{verbatim}
% \begin{mplibcode}[instanceName]
% % some mp code
% \end{mplibcode}
%\end{verbatim}
% The behavior is as follows.
% \begin{itemize}
% \item All the variables and functions are shared
% only among all the environments belonging to the same instance.
% \item \cs{mplibcodeinherit} only affects environments
% with no instance name set (since if a name is set,
% the code is intended to be reused at some point).
% \item |btex ... etex| boxes are also shared and do not
% require \cs{mplibglobaltextext}.
% \item When an instance names is set,
% respective \cs{currentmpinstancename} is set as well.
% \end{itemize}
% In parellel with this functionality, we support
% optional argument of instance name for \cs{everymplib} and
% \cs{everyendmplib}, affecting only those |mplibcode| environments
% of the same name.
% Unnamed \cs{everymplib} affects not only those instances with no name,
% but also those with name but with no corresponding \cs{everymplib}.
% The syntax is:
%\begin{verbatim}
% \everymplib[instanceName]{...}
% \everyendmplib[instanceName]{...}
%\end{verbatim}
%
% \subsubsection{\cs{mplibglobaltextext\{enable\textbar disable\}}}
% Default: |disable|.
% Formerly, to inherit |btex| |...| |etex| boxes as well as other \metapost macros, variables and constants,
% it was necessary to declare \cs{mplibglobaltextext\{enable\}} in advance.
% But from v2.27, this is implicitly enabled when \cs{mplibcodeinherit}
% is enabled.
% This optional command still remains mostly for backward compatibility.
%\begin{verbatim}
% \mplibcodeinherit{enable}
% %\mplibglobaltextext{enable}
% \everymplib{ beginfig(0);} \everyendmplib{ endfig;}
% \mplibcode
% label(btex $\sqrt{2}$ etex, origin);
% draw fullcircle scaled 20;
% picture pic; pic := currentpicture;
% \endmplibcode
% \mplibcode
% currentpicture := pic scaled 2;
% \endmplibcode
%\end{verbatim}
%
% \subsubsection{\cs{mplibverbatim\{enable\textbar disable\}}}
% Default: |disable|.
% Users can issue \cs{mplibverbatim\{enable\}}, after which
% the contents of mplibcode environment will be read verbatim. As a result,
% except for \cs{mpdim} and \cs{mpcolor} (see \hyperlink{mpdim}{below}),
% all other \TeX\ commands outside of the
% |btex| or |verbatimtex| |...| |etex| are not expanded and will be fed
% literally to the \mplib library.
%
% \subsubsection{\cs{mpdim\{...\}}}
% \hypertarget{mpdim}{}\relax
% Besides other \TeX\ commands, \cs{mpdim} is specially allowed
% in the mplibcode environment. This feature is inpired by \pkg{gmp} package authored by
% Enrico Gregorio. Please refer to the manual of \pkg{gmp} package for details.
%\begin{verbatim}
% \begin{mplibcode}
% beginfig(1)
% draw origin--(.6\mpdim{\linewidth},0) withpen pencircle scaled 4
% dashed evenly scaled 4 withcolor \mpcolor{orange};
% endfig;
% \end{mplibcode}
%\end{verbatim}
%
% \subsubsection{\cs{mpcolor[...]\{...\}}}
% With \cs{mpcolor} command, color names or expressions of
% \pkg{color}, \pkg{xcolor} and \pkg{l3color} module/packages can be used in the mplibcode
% environment (after |withcolor| operator).
% See the example \hyperlink{mpdim}{above}.
% The optional |[...]| denotes the option of \pkg{xcolor}'s \cs{color} command.
% For spot colors, \pkg{l3color} (in PDF/DVI mode),
% \pkg{colorspace}, \pkg{spotcolor}
% (in PDF mode) and \pkg{xespotcolor} (in DVI mode) packages are supported
% as well.
%
% \subsubsection{\cs{mpfig} \ldots\ \cs{endmpfig}}
% Besides the |mplibcode| environment (for \LaTeX) and
% \cs{mplibcode ...} \cs{endmplibcode} (for Plain),
% we also provide unexpandable \TeX\ macros \cs{mpfig} |...| \cs{endmpfig} and its starred version
% \cs{mpfig*} |...| \cs{endmpfig} to save typing toil.
% The former is roughly the same as follows:
%\begin{verbatim}
% \begin{mplibcode}[@mpfig]
% beginfig(0)
% token list declared by \everymplib[@mpfig]
% ...
% token list declared by \everyendmplib[@mpfig]
% endfig;
% \end{mplibcode}
%\end{verbatim}
% and the starred version is roughly the same as follows:
%\begin{verbatim}
% \begin{mplibcode}[@mpfig]
% ...
% \end{mplibcode}
%\end{verbatim}
% In these macros \cs{mpliblegacybehavior\{disable\}}
% is forcibly declared.
% Again, as both share the same instance name, \metapost codes are inherited among them.
% A simple example:
%\begin{verbatim}
% \everymplib[@mpfig]{ drawoptions(withcolor .5[red,white]); }
% \mpfig* input boxes \endmpfig
% \mpfig
% circleit.a(btex Box 1 etex); drawboxed(a);
% \endmpfig
%\end{verbatim}
% The instance name (default: |@mpfig|) can be changed by redefining
% \cs{mpfiginstancename}, after which a new \mplib instance will start and
% code inheritance too will begin anew. \cs{let}\cs{mpfiginstancename}\cs{empty} will
% prevent code inheritance if \cs{mplibcodeinherit\{true\}} is not declared.
%
% \subsubsection{About cache files}
% To support |btex ... etex| in external |.mp| files, luamplib
% inspects the content of each and every |.mp| file and makes caches
% if nececcsary, before returning their paths to \LuaTeX's \mplib library.
% This could waste the compilation time, as most |.mp| files
% do not contain |btex ... etex| commands. So luamplib provides
% macros as follows, so that users can give instructions about files
% that do not require this functionality.
% \begin{itemize}
% \item \cs{mplibmakenocache}|{|\meta{filename}|[,|\meta{filename}|,...]}|
% \item \cs{mplibcancelnocache}|{|\meta{filename}|[,|\meta{filename}|,...]}|
% \end{itemize}
% where \meta{filename} is a filename excluding |.mp| extension.
% Note that |.mp| files under |$TEXMFMAIN/metapost/base| and
% |$TEXMFMAIN/metapost/context/base| are already registered by default.
%
% By default, cache files will be stored in |$TEXMFVAR/luamplib_cache| or,
% if it's not available (mostly not writable),
% in the directory where output files are saved:
% to be specific, |$TEXMF_OUTPUT_DIRECTORY/luamplib_cache|,
% |./luamplib_cache|, |$TEXMFOUTPUT/luamplib_cache|, and |.|, in this order.
% |$TEXMF_OUTPUT_DIRECTORY| is normally the value of |--output-directory|
% command-line option.
%
% Users can change this behavior by the command
% \cs{mplibcachedir}\marg{directory path}, where tilde (|~|) is interpreted
% as the user's home directory (on a windows machine as well).
% As backslashes (\cs{}) should be escaped by users, it would be easier to use
% slashes (|/|) instead.
%
% \subsubsection{About figure box metric}
% Notice that, after each figure is processed, the macro \cs{MPwidth} stores
% the width value of the latest figure; \cs{MPheight}, the height value.
% Incidentally, also note that \cs{MPllx}, \cs{MPlly}, \cs{MPurx}, and
% \cs{MPury} store the bounding box information of the latest figure
% without the unit |bp|.
%
% \subsubsection{luamplib.cfg}
% At the end of package loading, luamplib searches
% |luamplib.cfg| and, if found, reads the file in automatically.
% Frequently used settings such as \cs{everymplib}, \cs{mplibforcehmode}
% or \cs{mplibcodeinherit} are suitable for going into this file.
%
% \subsubsection{Tagged PDF}
% When \pkg{tagpdf} package is loaded and activated, |mplibcode| environment accepts additional options for tagged PDF\@.
% The code related to this functionality is currently in experimental stage, not guaranteeing backward compatibility.
% Like the \LaTeX's |picture| environment,
% available optional keys are |tag|, |alt|, |actualtext|, |artifact|, |debug| and |correct-BBox|
% (|texdoc| |latex-lab-graphic|).
% Additionally, luamplib provides its own |text| key.
% \begin{description}
% \item[|tag=...|] You can choose a tag name, default value being |Figure|.
% BBox info will be added automatically to the PDF
% unless the value is |text| or |false|.
% When the value is |false|, tagging is deactivated.
% \item[|debug|] draws bounding box of the figure for checking, which you can correct
% by |correct-BBox| key with space-separated four dimen values.
% \item[|alt=...|] sets an alternative text of the figure as given.
% This key is needed for ordinary \metapost figures.
% You can give alternative text within \metapost code as well:
% |VerbatimTeX| |("\mplibalttext{...}");|
% \item[|actualtext=...|] starts a |Span| tag implicitly and sets an actual text as given.
% Horizontal mode is forced by \cs{noindent} command. BBox info will not be added.
% This key is intended for figures which can be represented by a character or
% a small sequence of characters.
% You can give actual text within \metapost code as well:
% |VerbatimTeX| |("\mplibactualtext{...}");|
% \item[|artifact|] starts an |artifact| MC (marked content).
% BBox info will not be added.
% This key is intended for decorative figures which have no semantic quality.
% \item[|text|] starts an |artifact| MC and enables tagging on textext
% (the same as |btex| |...| |etex|) boxes.
% Horizontal mode is forced by \cs{noindent} command. BBox info will not be added.
% This key is intended for figures made mostly of textext boxes.
% Inside text-keyed figures, reusing textext boxes is strongly discouraged.
% \end{description}
% These keys are provided also for \cs{mpfig} and \cs{usemplibgroup} (see \hyperlink{usemplibgroup}{below}) commands.
%\begin{verbatim}
% \begin{mplibcode}[myInstanceName, alt=figure drawing a circle]
% ...
% \end{mplibcode}
%
% \mpfig[alt=figure drawing a square box]
% ...
% \endmpfig
%
% \usemplibgroup[alt=figure drawing a triangle]{...}
%
% \mppattern{...} % see below
% \mpfig[tag=false] % do not tag this figure
% ...
% \endmpfig
% \endmppattern
%\end{verbatim}
% As for the instance name of |mplibcode| environment,
% |instance=...| or |instancename=...| is also allowed
% in addition to the raw instance name as shown above.
%
%
% \subsection{\textsc{MetaPost}}
%
% \subsubsection{\texttt{mplibdimen(...)}, \texttt{mplibcolor(...)}}
% These are \metapost interfaces for the \TeX\ commands
% \cs{mpdim} and \cs{mpcolor} (see \hyperlink{mpdim}{above}). For example,
% |mplibdimen("\linewidth")| is basically the same as \cs{mpdim\{\cs{linewidth}\}}, and
% |mplibcolor("red!50")| is basically the same as \cs{mpcolor\{red!50\}}.
% The difference is that these \metapost operators can also be used in external |.mp| files,
% which cannot have \TeX\ commands outside of the |btex| or |verbatimtex| |...| |etex|.
%
% \subsubsection{\texttt{mplibtexcolor ...}, \texttt{mplibrgbtexcolor ...}}
% |mplibtexcolor|, which accepts a string argument, is a \metapost operator that converts a \TeX\ color expression
% to a \metapost color expression, that can be used anywhere color expression is expected
% as well as after the |withcolor| operator.
% For instance:
%\begin{verbatim}
% color col;
% col := mplibtexcolor "olive!50";
%\end{verbatim}
% But the result may vary in its color model (gray/rgb/cmyk)
% according to the given \TeX\ color. (Spot colors are forced to
% cmyk model, so this operator is not recommended for spot colors.)
% Therefore the example shown above would raise a \metapost error:
% |cmykcolor col;| should have been declared.
% By contrast, |mplibrgbtexcolor| \meta{string} always returns rgb model expressions.
%
% \subsubsection{\texttt{mplibgraphictext ...}}
% |mplibgraphictext| is a \metapost operator, the effect of which is similar to that of
% \ConTeXt's |graphictext| or our own |mpliboutlinetext|
% (see \hyperlink{mpliboutlinetext}{below}).
% However the syntax is somewhat different.
%\begin{verbatim}
% mplibgraphictext "Funny"
% fakebold 2.3 % fontspec option
% drawcolor .7blue fillcolor "red!50" % color expressions
%\end{verbatim}
% |fakebold|, |drawcolor| and |fillcolor| are optional;
% default values are |2|, |"black"| and |"white"| respectively.
% When the color expressions are given in string type, they are regarded as
% \pkg{color}, \pkg{xcolor} or \pkg{l3color}'s expressions.
% All from |mplibgraphictext| to the end of sentence will compose an
% anonymous |picture|, which can be drawn or assigned to a variable.
% Incidentally, |withdrawcolor| and |withfillcolor| are synonyms of
% |drawcolor| and |fillcolor|, hopefully to be compatible with |graphictext|.
%
% \textsc{n.b.}
% In some cases, |mplibgraphictext| will produce better results than \ConTeXt\
% or even than our own |mpliboutlinetext|,
% especially when processing complicated \TeX\ code
% such as the vertical writing in Chinese or Japanese.
% However, because the implementation is quite different from others,
% there are some limitations such that you can't
% apply shading (gradient colors) to the text with |withshademethod| from \emph{metafun}.
% (But this limitation is now lifted by the introduction of |withshadingmethod|.
% See \hyperlink{luamplibshading}{below}.)
% Again,
% in DVI mode, \pkg{unicode-math} package is needed for math formula,
% as we cannot embolden type1 fonts in DVI mode.
%
% \subsubsection{\texttt{mplibglyph ... of ...}}
% From v2.30, we provide a new \metapost operator |mplibglyph|, which returns a \metapost picture
% containing outline paths of a glyph in opentype, truetype or type1 fonts.
% When a type1 font is specified, \metapost primitive |glyph| will be called.
%\begin{verbatim}
% mplibglyph 50 of \fontid\font % slot 50 of current font
% mplibglyph "Q" of "TU/TeXGyrePagella(0)/m/n/10" % font csname
% mplibglyph "Q" of "texgyrepagella-regular.otf" % raw filename
% mplibglyph "Q" of "Times.ttc(2)" % subfont number
% mplibglyph "Q" of "SourceHanSansK-VF.otf[Regular]" % instance name
%\end{verbatim}
% Both arguments before and after of ``|of|'' can be either a number or a string.
% Number arguments are regarded as a glyph slot (GID) and a font id number, repectively.
% String argument at the left side is regarded as a glyph name in the font or a unicode character.
% String argument at the right side is regarded as a \TeX\ font csname (without backslash) or
% the raw filename of a font. When it is a font filename, a number within parentheses
% after the filename denotes a
% subfont number (starting from zero) of a TTC font; a string within brackets denotes
% an instance name of a variable font.
%
% \subsubsection{\texttt{mplibdrawglyph ...}}
% The picture returned by |mplibglyph| will be quite similar to the result of |glyph| primitive in its structure.
% So, \metapost's |draw| command will fill the inner path of the picture with the background color.
% In contrast, |mplibdrawglyph| \meta{picture} command fills the paths according to the nonzero winding
% number rule. As a result, for instance, the area surrounded by inner path of ``O''
% will remain transparent.
%
% \leavevmode\llap{\textcolor{red}{☞}\kern1.2\parindent}\relax
% To apply the nonzero winding number rule to a picture containing paths,
% luamplib appends |withpostscript| |"collect"|
% to the paths except the last one in the picture.
% If you want the even-odd rule instead, you can, with \emph{plain} format as well,
% additionally declare |withpostscript| |"evenodd"| to the last path in the picture.
%
% \subsubsection{\texttt{mpliboutlinetext (...)}}
% \hypertarget{mpliboutlinetext}{}\relax
% From v2.31, a new \metapost operator |mpliboutlinetext| is available, which mimicks
% \emph{metafun}'s |outlinetext|. So the syntax is the same: see the \emph{metafun}
% manual \S\,8.7 (|texdoc metafun|). A simple example:
%\begin{verbatim}
% draw mpliboutlinetext.b ("$\sqrt{2+\alpha}$")
% (withcolor \mpcolor{red!50})
% (withpen pencircle scaled .2 withcolor red)
% scaled 2 ;
%\end{verbatim}
% After the process, |mpliboutlinepic[]|
% and |mpliboutlinenum| will be preserved as global variables;
% |mpliboutlinepic[1]| |...| |mpliboutlinepic[mpliboutlinenum]|
% will be an array of images each of which containing a glyph or a rule.
%
% \textsc{n.b.} As Unicode grapheme cluster is not considered in the array, a unit that must be
% a single cluster might be separated apart.
%
% \subsubsection{\cs{mppattern\{...\} ...} \cs{endmppattern}, \texttt{... withpattern ...}}
% \hypertarget{mppattern}{}\relax
% \TeX\ macros
% \cs{mppattern}\marg{name} |...| \cs{endmppattern} define a tiling pattern
% associated with the \meta{name}.
% \metapost operator |withpattern|, the syntax being
% \meta{path}\,\textbar\,\meta{textual picture} |withpattern| \meta{string},
% will return a \metapost picture which fills
% the given path or text with a tiling pattern of the \meta{name}
% by replicating it horizontally and vertically.
% The \emph{textual picture} here means any text typeset by \TeX, mostly the result
% of the |btex| command (though technically this is not a true textual picture)
% or the |infont| operator.
%
% An example:
%\begin{verbatim}
% \mppattern{mypatt} % or \begin{mppattern}{mypatt}
% [ % options: see below
% xstep = 10,
% ystep = 12,
% matrix = {0, 1, -1, 0}, % or "0 1 -1 0"
% ]
% \mpfig % or any other TeX code,
% draw (origin--(1,1))
% scaled 10
% withcolor 1/3[blue,white]
% ;
% draw (up--right)
% scaled 10
% withcolor 1/3[red,white]
% ;
% \endmpfig
% \endmppattern % or \end{mppattern}
%
% \mpfig
% draw fullcircle scaled 90
% withpostscript "collect"
% ;
% draw fullcircle scaled 200
% withpattern "mypatt"
% withpen pencircle scaled 1
% withcolor \mpcolor{red!50!blue!50}
% withpostscript "evenodd"
% ;
% \endmpfig
%\end{verbatim}
%
% The available options are listed in Table~\ref{tab:mppatternoptions}.
% \begin{table}
% \centering
% \caption{options for \cs{mppattern}}\label{tab:mppatternoptions}
% \begin{tabular}{lll}\hline
% Key & Value Type & Explanation\\\hline
% |xstep| &\emph{number} & horizontal spacing between pattern cells\\
% |ystep| &\emph{number} & vertical spacing between pattern cells\\
% |xshift| &\emph{number} & horizontal shifting of pattern cells\\
% |yshift| &\emph{number} & vertical shifting of pattern cells\\
% |bbox| &\emph{table} or \emph{string} & |llx|, |lly|, |urx|, |ury| values\kern1pt*\\
% |matrix| &\emph{table} or \emph{string} & |xx|, |yx|, |xy|, |yy| values\kern1pt* or MP transform code\\
% |resources|&\emph{string} & PDF resources if needed\\
% |colored| or |coloured| &\emph{boolean}& |false| for uncolored pattern. default: |true|\\\hline
% & & \small *\,in string type, numbers are separated by spaces\\
% \end{tabular}
% \end{table}
%
% For the sake of convenience, the width and height values of tiling patterns will be written down
% into the log file. (depth is always zero.) Users can refer to them for option setting.
%
% As for |matrix| option, \metapost code such as `|rotated 30 slanted .2|' is allowed as well
% as string or table of four numbers. You can also set |xshift| and |yshift|
% values by using `|shifted|' operator. But when |xshift| or |yshift| option is explicitly
% given, they have precedence over the effect of `|shifted|' operator.
%
% When you use special effects such as transparency in a pattern,
% |resources| option is needed: for instance, |resources="/ExtGState 1 0 R"|.
% However, as luamplib automatically includes the resources of the current page, this option
% is not needed in most cases.
%
% Option |colored=false| (|coloured| is a synonym of |colored|) will generate an uncolored pattern which shall have no color at all.
% Uncolored pattern will be painted later by the color of a \metapost object.
% An example:
%\begin{verbatim}
% \begin{mppattern}{pattnocolor}
% [
% colored = false,
% matrix = "slanted .3 rotated 30",
% ]
% \tiny\TeX
% \end{mppattern}
%
% \begin{mplibcode}
% beginfig(1)
% picture tex;
% tex = mpliboutlinetext.p ("\bfseries \TeX");
% for i=1 upto mpliboutlinenum:
% j:=0;
% for item within mpliboutlinepic[i]:
% j:=j+1;
% draw pathpart item scaled 10
% if j < length mpliboutlinepic[i]:
% withpostscript "collect"
% else:
% withpattern "pattnocolor"
% withpen pencircle scaled 1/2
% withcolor (i/4)[red,blue] % paints the pattern
% fi;
% endfor
% endfor
% endfig;
% \end{mplibcode}
%\end{verbatim}
% A much simpler and efficient way to obtain a similar result
% (without colorful characters in this example)
% is to give a \emph{textual picture} as the operand of |withpattern|:
%\begin{verbatim}
% \begin{mplibcode}
% beginfig(2)
% picture pic;
% pic = mplibgraphictext "\bfseries\TeX"
% fakebold 1/2
% fillcolor 1/3[red,blue] % paints the pattern
% drawcolor 2/3[red,blue]
% scaled 10 ;
% draw pic withpattern "pattnocolor" ;
% endfig;
% \end{mplibcode}
%\end{verbatim}
%
% \subsubsection{\texttt{... withfademethod ...}}
% This is a \metapost operator which makes the color of an object gradiently transparent.
% The syntax is \meta{path}\,\textbar\,\meta{picture} |withfademethod| \meta{string},
% the latter being either |"linear"| or |"circular"|.
% Though it is similar to the |withshademethod| from \emph{metafun},
% the differences are: (1) the operand of |withfademethod| can be a picture as well as a path;
% (2) you cannot make gradient colors, but can only make gradient opacity.
%
% Related macros to control optional values are:
% \begin{description}
% \let\bfseries\relax
% \item [|withfadeopacity (|\emph{number, number}|)|]
% sets the starting opacity and the ending opacity, default value being |(1,0)|.
% `|1|' denotes full color; `|0|' full transparency.
% \item [|withfadevector (|\emph{pair, pair}|)|]
% sets the starting and ending points. Default value in the linear mode is
% |(llcorner p, lrcorner p)|, where |p| is the operand,
% meaning that fading starts from the left edge and ends at the right edge.
% Default value in the circular mode is |(center p, center p)|, which means
% centers of both starting and ending circles are the center of the bounding box.
% \item [|withfadecenter|] is a synonym of |withfadevector|.
% \item [|withfaderadius (|\emph{number, number}|)|]
% sets the radii of starting and ending circles. This is no-op in the linear mode.
% Default value is |(0, abs(center p - urcorner p))|, meaning that fading starts from the
% center and ends at the four corners of the bounding box.
% \item [|withfadebbox (|\emph{pair, pair}|)|]
% sets the bounding box of the fading area, default value being |(llcorner p, urcorner p)|.
% Though this option is not needed in most cases, there could be cases when users want to
% explicitly control the bounding box.
% Particularly, see the description \hyperlink{withgroupbbox}{below}
% on the analogous macro |withgroupbbox|.
% \end{description}
% An example:
%\begin{verbatim}
% \mpfig
% picture mill;
% mill = btex \includegraphics[width=100bp]{mill} etex;
% draw mill
% withfademethod "circular"
% withfadecenter (center mill, center mill)
% withfaderadius (20, 50)
% withfadeopacity (1, 0)
% ;
% \endmpfig
%\end{verbatim}
%
% \subsubsection{\texttt{... asgroup ...}}
% \hypertarget{transparencygroup}{}\relax
% As said \hyperlink{metafunformat}{before},
% transparency group is available with \emph{plain} as well as \emph{metafun} format.
% The syntax is exactly the same:
% \meta{picture}\,\textbar\,\meta{path} |asgroup|
% |""|\,\textbar\,|"isolated"|\,\textbar\,|"knockout"|\,\textbar\ |"isolated,knockout"|,
% which will return a \metapost picture.
% It is called \emph{Transparency Group} because the objects contained in the group are composited
% to produce a single object, so that outer transparency effect, if any,
% will be applied to the group as a whole, not to the individual objects cumulatively.
%
% The additional feature provided by luamplib is that
% you can reuse the group as many times as you want
% in the \TeX{} code or in other \metapost code chunks,
% with infinitesimal increase in the size of PDF file.
% For this functionality we provide \TeX{} and \metapost macros as follows:
% \begin{description}
% \let\bfseries\relax
% \item[|withgroupname| \meta{string}] associates a transparency group with the given name.
% When this is not appended to the sentence with |asgroup| operator,
% the default group name `|lastmplibgroup|' will be used.
%
% \item[\cs{usemplibgroup}\marg{name}]
% \hypertarget{usemplibgroup}{}\relax
% is a \TeX\ command to reuse a transparency group of the name
% once used.
% Note that the position of the group will be origin-based:
% in other words, lower-left corner of the group will be shifted to the origin.
%
% \item[|usemplibgroup| \meta{string}] is a \metapost command which will add
% a transparency group of the name to the |currentpicture|.
% Contrary to the \TeX\ command just mentioned,
% the position of the group is the same as the original transparency group.
%
% \item[|withgroupbbox (|\emph{pair}|,|\emph{pair}|)|]
% \hypertarget{withgroupbbox}{}\relax
% sets the bounding box of the transparency group,
% default value being |(llcorner p, urcorner p)|.
% This option might be needed especially when you draw with a thick pen
% a path that touches the boundary;
% you would probably want to append to the sentence
% `|withgroupbbox| |(bot| |lft| |llcorner| |p,| |top| |rt| |urcorner| |p)|',
% supposing that the pen was selected by the |pickup| command.
%
% \end{description}
% An example showing the difference between the \TeX\ and \metapost commands:
%\begin{verbatim}
% \mpfig
% draw image(
% fill fullcircle scaled 100 shifted 25right withcolor blue;
% fill fullcircle scaled 100 withcolor red ;
% ) asgroup ""
% withgroupname "mygroup";
% draw (left--right) scaled 10;
% draw (up--down) scaled 10;
% \endmpfig
%
% \noindent
% \clap{\vrule width 20pt height .25pt depth .25pt}%
% \clap{\vrule width .5pt height 10pt depth 10pt}%
% \usemplibgroup{mygroup}
%
% \mpfig
% usemplibgroup "mygroup" rotated 15
% withtransparency (1, 0.5) ;
% draw (left--right) scaled 10;
% draw (up--down) scaled 10;
% \endmpfig
%\end{verbatim}
%
% Also note that normally the reused transparency groups are not affected by outer color commands.
% However, if you have made the original transparency group using |withoutcolor| command,
% colors will have effects on the uncolored objects in the group.
%
% \subsubsection{\cs{mplibgroup\{...\} ...} \cs{endmplibgroup}}
% These \TeX\ macros are described here in this subsection, as they are
% deeply related to the |asgroup| operator.
% Users can define a transparency group or a normal \emph{form XObject}
% with these macros from \TeX\ side.
% The syntax is similar to the \cs{mppattern} command (see \hyperlink{mppattern}{above}).
% An example:
%\begin{verbatim}
% \mplibgroup{mygrx} % or \begin{mplibgroup}{mygrx}
% [ % options: see below
% asgroup="",
% ]
% \mpfig % or any other TeX code
% pickup pencircle scaled 10;
% draw (left--right) scaled 30 rotated 45 ;
% draw (left--right) scaled 30 rotated -45 ;
% \endmpfig
% \endmplibgroup % or \end{mplibgroup}
%
% \usemplibgroup{mygrx}
%
% \mpfig
% usemplibgroup "mygrx" scaled 1.5
% withtransparency (1, 0.5) ;
% \endmpfig
%\end{verbatim}
%
% Availabe options, much fewer than those for \cs{mppattern},
% are listed in Table~\ref{tab:mplibgroupoptions}.
% Again, the width/height/depth values of the mplibgroup will be written down into the log file.
% \begin{table}
% \centering
% \caption{options for \cs{mplibgroup}}\label{tab:mplibgroupoptions}