                       History of the luamplib package

2026/01/14 2.38.2
   Documentation changes only:
   * update examples using recently introduced macros
   * include figures generated from some example code
   * rearrange the order of subsections on metapost macros

2025/12/30 2.38.1
   * Now \mpcolor (or mplibcolor) returns a metapost color expression
   when the color specified is not a spot or named color.
   With spot or named colors, withprescript command will be inserted as before.
   * fix color routine for named color in DVI mode with no \DocumentMetadata
   (assumes xcolor package is loaded)

2025/12/26 2.38.0
   * a new macro to specify fill color and stroke color differently:
        withmplibcolors
   * new macros to draw the picture returned by mplibglyph:
        mplibfillglyph, mplibstrokeglyph, mplibfillandstrokeglyph
   * fix the macro mplibdrawglyph
   * documentation: add explanations about withpostscript "both"/"eoboth"
   * documentation: add a caution about \mpcolor command

2025/12/19 2.37.8
   * support Chinese/Japanese vertical writing in mpliboutlinetext
   * doc: add an example of accessing an MP variable from TeX side

2025/12/05 2.37.7
   * avoid error inside trivlist environment, related to \partokencontext=2

2025/11/10 2.37.6
   * documentation readability: bigger fontsize, wider textwidth, tableofcontents
   * adapt to luatexko's harf-mode vertical writing

2025/05/26 2.37.5
   * 'utf8_mode = true' as a field of mplib.new
     See https://tug.org/pipermail/lualatex-dev/2025-May/001723.html

2025/05/21 2.37.4
   * real horizontal mode upon tagging keys 'actualtext' and 'text'
   * improved tagging of mplibgraphictext by copying node attributes

2025/05/15 2.37.3
   * Tagging option 'debug' is removed.
     Declare '\DocumentMetadata{debug=BBox}' instead.

   * Tagging option 'correct-BBox' is renamed to 'adjust-BBox'.

   * Tagging option 'off' is newly introduced.
     Given this key, nothing will be tagged by luamplib.

   * Tagging option 'tagging-setup' is newly introduced.
     The value of this key is a key-value list of other tagging options.

   * Tagging options 'actualtext' and 'text' do not force horizontal mode.

   * When the text of a tex-text box starts with '[taggingoff]', it will not
     be tagged at all even in the text mode.

   * more robust 'mplibgraphictext' macro

2025/03/20 2.37.2
   * Formerly, it was not possible to give shading effect to a textual picture
   inside a tiling pattern. This limitation is now lifted.
   As a side effect, a tiling pattern inside a tiling pattern is also allowed.

   * 'withmppattern <string>' is a newly introduced command virtually the same
   as 'withpattern <string>', but the former does not force the result of MP
   picture. So users can use any drawing command suitable, such as 'fill' or
   'filldraw' as well as 'draw'.

   * 'textext', 'TEX', 'mplibcolor', 'mplibdimen', or 'VerbatimTeX' can accept
   a string argument without parentheses. For instance, 'textext "\TeX"' is now
   allowed as well as 'textext("\TeX")'.

2025/02/18 2.37.1
   * A new operator 'mplibuclength <string>' returns the number of unicode
   grapheme clusters in the string.

   * A new operator 'mplibucsubstring <pair> of <string>' returns the part of
   the string indexed by unicode grapheme clusters.

   * These two operators require lua-uni-algos package.

2025/02/06 2.37.0
   * introduce a new operator 'mpliblength <string>', a unicode-aware version of
   the 'length' primitive

   * introduce a new operator 'mplibsubstring <pair> of <string>', a unicode-aware
   version of the 'substring ... of ...' primitive

2024/12/16 2.36.3
   * change '//' to 'math.floor' for compatibility with luajittex (#158)

   * fix documentation on mplibgraphictext considering the introduction of
   'withshadingmethod'

2024/12/11 2.36.2
   * fix a bug regarding expansion of options
   (https://tug.org/pipermail/metapost/2024-December/003574.html)

2024/12/09 2.36.1
   * fix a bug of previous release: missing 'local' in front of 'os'

2024/12/08 2.36.0
   * <path>|<textual picture> withshadingmethod <string>,
   where <string> shall be "linear" or "circular", gives shading effect to
   the <path> or <textual picture> with plain format as well as metafun.
   See the documentation.

   * withtransparency (<number>|<string>, <number>)
   gives transparency effect with plain format as well. See the documentation.

   * added 'dir TLT' to usemplibgroup boxes

   * removed 'tag=artifact' option. Use 'artifact' instead.

2024/11/28 2.35.2
   * fix height/depth of boxes made by \mplibgroup command
   * enhanced tagging of \usemplibgroup

2024/11/25 2.35.1
   * cope with 'TEX(char13)': remove everything from char13 to the end of
   input string (https://tug.org/pipermail/metapost/2024-November/003572.html)

   * (WIP) avoid internal command names of tagpdf/kernel code (#151)

2024/11/12 2.35.0
   * even under \mplibtextextlabel{true}, the original 'infont' operator will
   be used when the character slot of the text argument is less than 32, or is
   equal to 35, 36, 37, 38, 92, 94, 95, 123, 125, 126 or 127.

   * \mplibforcehmode will have effects on \usemplibgroup as well as ordinary
   metapost figures.

   * support tagged PDF when tagpdf package is activated. The related code is
   currently in experimental stage. See the documentation for details.

2024/08/03 2.34.5
   * provide 'withgroupbbox' macro for transparency group to enable users to
   control the bounding box

   * write down the width/height/depth values of mplibgroup to the log file

2024/07/31 2.34.4
   * 'withpattern' operator accepts a <textual picture> as well as a <path>
   for its operand. Thus users can give pattern effect to the result of btex
   command or infont operator.

   * fix regarding line width in mplibgraphictext

2024/07/27 2.34.3
   * in DVI mode, use LaTeX's shipout hooks to generate new XObjects
   or to put resources to pageresources. (in plain, load atbegshi.sty)

   * fix shading to allow the even-odd rule

2024/07/24 2.34.2
   * With the newly introduced macros, \mplibgroup ... \endmplibgroup, users
   can define a transparency group or a normal form XObject from TeX side.
   The LaTeX environment 'mplibgroup' is identical to this pair of macros.
   See the document for details.

   * document: be more precise about the color effect of a transparency group

   * remove trailing zeros from numeric objects to get smaller PDF

2024/07/19 2.34.1
   * transparency group is available with plain format as well.
   * transparency group once used is reusable in the TeX code or
   in other MetaPost code chunks. see the document for details.

2024/07/17 2.34.0
   * support transparency group with metafun format
   * fix regarding default value in circular fading mode
   * fix regarging the scope of graphics state

2024/07/14 2.33.1
   * refactor the manual, including some minor items undocumented so far
   * improve fading routine to get possibly smaller pdf file

2024/07/08 2.33.0
   * provide a new metapost operator 'withfademethod' and related macros,
   which make the color of an object gradiently transparent. see luamplib
   document for details.

   * fix spot-color shading routine to support user-defined colorspace

2024/07/03 2.32.4
   * make the variable 'patterns' local
   * 'math.randomseed' on plain TeX
   * remove redundant code 'fullcircle scaled 0'

2024/06/21 2.32.3
   * 'coloured' is a synonym of the option 'colored' in pattern definition.

   * fix a bug related to pdf page resources in dvi mode

   * users can access the lua table containing mplib instances 'luamplib.instances',
   through which metapost variables are also easily accessible as documented in
   LuaTeX manual 11.2.8.4.

2024/06/14 2.32.2
   * fix matrix conversion between MP and PDF

2024/06/13 2.32.1
   * for the sake of convenience, width and height values of tiling patterns
   will be written down into the log file.

   * table type is allowed as well as string type for 'matrix' and 'bbox'
   options in pattern definition.

   * metapost code such as 'rotated 30 slanted .2' is allowed as well as the
   string or table of numbers for the 'matrix' option in pattern definition.

   * as for the 'resources' option in pattern definition, luamplib
   automatically includes the resources of the current page.

   * luamplib does not log info even if there's no beginfig ... endfig.

2024/06/10 2.32.0
   * \mppattern{<name>} ... \endmppattern defines a tiling pattern which can be
   used with 'withpattern' operator to fill a closed path by replicating the tile
   horizontally and vertically.  \begin{mppattern} ... \end{mppattern} is exactly
   the same as \mppattern ... \endmppattern.  See luamplib manual for details.

2024/05/30 2.31.2
   * support vertical writing mode in mpliboutlinetext (presently luatexko
   package only, and except horizontal mode inside vertical mode)

   * after the process of mpliboutlinetext, mpliboutlinepic[1] ...
   mpliboutlinepic[mpliboutlinenum] will be preserved as an array of images
   each of which containing a glyph or a rule.  N.B. Unicode grapheme cluster
   is not considered here.

2024/05/24 2.31.1
   * fix bugs in outlinetext routine
   * improve rule treatment in graphictext

2024/05/21 2.31.0
   * provide a new metapost operator 'mpliboutlinetext', which mimicks
   metafun's 'outlinetext'. The syntax is the same as metafun's. (#133)

2024/05/10 2.30.0
   * 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.  In the syntax as follows, subfont number is zero based.

       mplibglyph 50   of \fontid\font            % slot 50 of current font
       mplibglyph 50   of "cmr10"                          % type1 font
       mplibglyph "Q"  of "TU/TeXGyrePagella(0)/m/n/10"    % font csname
       mplibglyph "똠" of "NotoSansCJKkr-Regular.otf"      % raw filename
       mplibglyph "Q"  of "Times.ttc(2)"                   % subfont number
       mplibglyph "똠" of "SourceHanSansK-VF.otf[Regular]" % instance name

   * provide a new metapost command 'mplibdrawglyph'. In contrast to metapost's
   'draw' command, this one fills paths of a picture according to the Nonzero
   Winding Number Rule.

   * in 'mplibgraphictext', option 'scale' is deprecated and now a synonym of
   'scaled'.  In DVI mode, unicode-math package is needed for math formula
   graphictext.

2024/05/01 2.29.0

   * provide new TeX macros to reduce typing toil.

     \mpfig ... \endmpfig is roughly the abbreviation of
         \begin{mplibcode}[@mpfig]
         beginfig(0)
         token list declared by \everymplib[@mpfig]
         ...
         token list declared by \everyendmplib[@mpfig]
         endfig;
         \end{mplibcode}

     \mpfig* ... \endmpfig is roughly the abbreviation of
         \begin{mplibcode}[@mpfig]
         ...
         \end{mplibcode}

     These macros are protected and unexpandable.
     In these macros \mpliblegacybehavior{false} is forcibly declared.
     As both share the same instance name, MetaPost codes are inherited among them.
     The instance name (default: @mpfig) can be changed by redefining `\mpfiginstancename'.

   * instance names are allowed in plain TeX as well. The syntax is:

         \mplibcode[name] ... \endmplibcode
         \everymplib[name]{ ... }
         \everyendmplib[name]{ ... }

     These macros are now protected and unexpandable.

   * provide new MetaPost operators `mplibtexcolor' and `mplibrgbtexcolor'
     which convert TeX color expressions to MetaPost color expressions.
     The latter one forces rgb model results (#112). For instance,

         mplibtexcolor "olive"     % => (0, 0, 1, 0.5)
         mplibrgbtexcolor "olive"  % => (0.5, 0.5, 0)

     As spot colors are always forced to cmyk or rgb model, it is not
     recommended to use these operators for them.

   * write down MetaPost messages into the log file

2024/04/25 2.28.2
   * direction of figure box is explicitly declared as TLT (#129)
   * figure box materials are emitted in one go at the end of the figure
   (to enable tex.runtoks in spot color shading routine)

2024/04/19 2.28.1
   * fix spot color shading routine

2024/04/12 2.28.0
   * provide a new metapost operator 'mplibgraphictext', which is similar
   to ConTeXt's 'graphictext'. But the syntax is not the same:

       mplibgraphictext "Text" fakebold 2 scale 3
                               fillcolor red drawcolor blue

   where 'fakebold' and 'scale' are fontspec's font options.
   'fakebold', 'scale', 'drawcolor' and 'fillcolor' are optional and
   default values are '2', '1', "black" and "white" respectively.
   When color expressions are given as string, they are regarded as
   xcolor's or l3color's expressions. The operator generates a metapost
   picture, which can be drawn or assigned to a variable. For compatibilty
   with 'graphictext', 'withdrawcolor' and 'withfillcolor' are synonyms of
   'drawcolor' and 'fillcolor'. Because the implementation is quite
   different from the \ConTeXt's, there are some limitations such that
   we can't apply shading (gradient colors) to the text.

   * support metafun's new shading method. Color expressions given as string
   are regarded as xcolor's or l3color's expressions. Spot colors defined
   by the color commands of l3color package are also acceptable
   (currently '\DocumentMetadata{ }' is needed for spot colors).

   * fix the y-position of text figures, which means the result of 'infont'
   operator, not of the 'textext' operator.

2024/04/04 2.27.2
   * for warning/info/error messages we now use our own lua function,
   instead of ltluatex's. As a result, mplib's multi-line messages are
   printed as they are with no module name prepended to each line.
   * terminal messages are now much conciser than before, printing only
   the most relevant part.
   * mplibcode which has no figure output does not print a warning, but
   just an info to the log.

2024/03/29 2.27.1
   * fix a bug regarding local textext boxes

2024/03/23 2.27.0
   * when `mplibcodeinherit' is enabled, `mplibglobaltextext' is implicitly
   enabled as well.
   * when instance name is used to mplibcode environments, btex ... etex
   boxes are also shared among the environments of the same intance name.
   * transparency functionality does not conflict with transparent package.

2024/03/10 2.26.4
    * not just color names but also color expressions of l3color module
    are now supported even if xcolor package is loaded

2024/03/07 2.26.3
    * color expressions of l3color are supported as well.
    But they are regarded as xcolor's expressions if xcolor package is loaded.
    * support pdfmanagement's opacity and shading management.

2024/03/04 2.26.2
    * color expressions ('red!50') are supported with xcolor package only

2024/03/04 2.26.1
    * attempt to support l3color: \mpcolor{color expression}
    * cope with mp.report warning produced by 'message' under metafun

2024/03/01 2.26.0
    * when \mplibcachedir{<dir>} is not set, default cache directory will
    be in the following order:
        $TEXMFVAR/luamplib_cache
        $TEXMF_OUTPUT_DIRECTORY/luamplib_cache
        ./luamplib_cache
        $TEXMFOUTPUT/luamplib_cache
        .

2024/01/25 2.25.3
    * protect "..." even if textextlabel is disabled (revert part of v2.25.0)

2023/12/08 2.25.2
    * info instead of warning when compiling with dviluatex

2023/08/21 2.25.1
    * explicit \par in \mplibstoptoPDF to support LaTeX's paragraph hooks

2023/08/07 2.25.0
    * propagate tex's jobname varible into mplib process as well.
    * protect "..." if and only if textextlabel is enabled.

2023/04/04 2.24.0
    respect '-recorder' command-line option

2022/01/12 2.23.0
    In parellel with the functionality introduced at previous version,
    \everymplib (\everyendmplib as well, of course) supports
    optional argument of named MetaPost instance, affecting only those
    mplibcode environments of the same name.

2022/01/09 2.22.0
    * Sergey Slyusarev (@jemmybutton) has suggested and contributed
    a new feature for LaTeX mplibcode environment, which now supports
    separately named MetaPost instances.  Using this feature,
    all the variables and functions are shared only among
    all the environments belonging to the same instance.
    (#99 and #100)

2021/11/23 2.21.1
    * address #97 (typesetting fails with "--lua" option)

2021/09/16 2.21.0
    * allow empty string in textext()

2021/08/03 2.20.9
    * initialize every mplib instance with random integer seed values

2021/08/02 2.20.8
    * when \mplibshowlog{enable} is declared, log (not term) messages
      returned by mplib instance will be printed into the .log file.

2021/03/11 2.20.7
    * emegency patch for context metafun 2021-03-06

2020/12/30 2.20.6
    * fix a bug regarding no figure output when luamplib.showlog is
      true. (#91)
    * now metapost `show' command triggers a warning message, so that
      it could be shown on the console. (#91)

2020/02/24 2.20.5
    * Extra check for \pdfliteral (PR #89)
    * allow expansion of \mpdim and \mpcolor when they are used in
      another macro
    * step copyright year

2019/12/11 2.20.4
    * remove unnecessary setting of endlinechar
    * \prependtomplibbox instead of \mplibhmodeornot

2019/11/14 2.20.3
    * fix issue #86 (LaTeX command inside metapost label)

2019/10/11 2.20.2
    * fix issue #84 (pgf package hinders \mpcolor process)

2019/03/26 2.20.1
    * '\mpdim' and '\mpcolor' are allowed, even if '\mplibverbatim' is enabled.

2019/03/20 2.20.0
    * huge changes, but mostly internal, so apparently not much difference
      from previous version.
    * '\mplibforcehmode' makes mplibcode typeset in horizontal mode.
      '\mplibnoforcehmode' reverts the setting. The latter is default.
    * '\mpliblegacybehavior{disable}' triggers a new mode of processing
      verbatimtex .. etex: along with btex .. etex, they will be processed
      sequentially one by one. Old behavior, being default, can be restored
      by declaring '\mpliblegacybehavior{enable}'.
      Incidentally, verbatimtex .. etex in MP input files is honored
      from this version, save those that contain '\documentclass'
      or '\begin{document}' etc, which is totally ignored.

2018/09/27 2.12.5
    * change dash.offset pattern from "%i" to "%f" (PR #77)
    * remove unnecessary variables that go back to context (issue #76)

2018/04/16 2.12.4
    * workaround issue #74 relating to PATH limitation
    * substitute InconsolataN font for Liberation Mono in the manual

2018/04/06 2.12.3
    * step copyright year
    * remove a line relating graphictext hindrance

2018/01/04 2.12.2
    * workaround issue #70 "Labels outside beginfig...endfig are not inherited"
    * address issue #71 "metafun problem: arrow tips are not filled"
    by importing luatex-mplib.lua from context beta.

2017/06/02 2.12.1
    * when \mplibglobaltextext{enable} is declared, metapost variables
    containing btex ... etex labels can be inherited across code chunks.
    Of course, \mplibcodeinherit should also be switched on.

2016/03/31 2.11.3
    * fix a bug regarding nested mplibcode environments (issue #63)

2016/01/02 2.11.2
    * updates for luatex 0.87

2015/10/02 2.11.1
    * adapts to latex 2015/10/01 and luatexbase v1.0
    * allows `btex ... etex' and `verbatimtex ... etex' even when
      `\mplibverbatim{enable}' is declared.

2015/08/01 2.11.0
    * after `\mplibverbatim{enable}', contents of mplibcode environment
      will be read verbatim. So `btex ... etex', `verbatimtex ... etex',
      `\mpdim', `\mpcolor' are not allowed and all TeX commands will be
      fed literally into mplib library.
    * allow access to type1 fonts, which means we can use glyph
      operator now (luatex rev 5266)
    * color transparency is now compatible with pgf package and
      beamer class as well. (luatex 0.80+ is recommended)

2015/03/26 2.10.1
    * fix bug #55 regarding hash token

2015/03/20 2.10.0
    * TeX code in `VerbatimTeX()' between `beginfig();' and `endfig;'
      will be inserted after flushing out the mplib figure.
    * `\mpcolor' command accepts optional argument: for instance,
      `\mpcolor[HTML]{FF0000}'.

2015/01/26 2.9.1
    * fix a bug reported by Herbert Schulz via luatex mailing list
      (http://tug.org/pipermail/luatex/2015-January/005054.html)

2015/01/05 2.9.0
    * after declaring `\mplibcodeinherit{enable}', each mplib code chunks
      will inherit variables/constants/macros defined by previous chunks.
      On the contrary, the default value `\mplibcodeinherit{disable}' will
      treat each code chunks as an independent instance, never being affected
      by other code chunks.

2014/07/04 2.8.1
    * support color package on plain tex.
    * fix a failure at `btex \% etex'.

2014/06/17 2.8.0
    * support color/xcolor/spotcolor packages.
      On LaTeX, color names or expressions of color/xcolor packages
      can be used inside mplibcode environment with the command
      \mpcolor{<color expression>}.

2014/04/25 2.7.0
    * support DVIPDFMx
    * default directory for cache is now '$TEXMFVAR/luamplib_cache'
    * internal changes following LuaTeX engine v0.79 and luatexbase
      package v0.7
    * [fix] avoid luatex crash under math_mode 'decimal'

2014/03/26 2.6.1
    * now luamplib does not disregard 'show' command, even if
      'luamplib.showlog' is false. Incidentally, it does not raise
      error, but just prints a warning, even if output contains
      no figure.
    * fix a bug wrt color, which might come to the fore under
      math mode 'double' or 'decimal'.

2014/03/08 2.6.0
    * new macro \mplibtextextlabel{enable} enables string labels typeset
      with textext() instead of infont operator. Every string label
      thereafter will be typeset with current TeX font.
    * fixed a bug wrt btex ... etex parsing (issue #39)
    * [doc] added a mention about \MPllx, \MPlly, \MPurx, and \MPury.

2014/03/01 2.5.3
    * using \mplibcachedir{<directory path>}, users can change the
      directory for storing cache files. By default, it is the directory
      where pdf output file is saved.
    * at the end of package loading, luamplib searches 'luamplib.cfg',
      and, when found, reads the file in automatically.

2014/02/24 2.5.2
    * new macros \mplibmakenocache{...} and \mplibcancelnocache{...} to
      register/unregister those .mp files that do not need caches.
      These macros affect the compilation speed only.
    * added a hack to support graph.mp (in fact, format.mp)
    * [fix] luamplib now respects percent sign if it is enclosed by quotes.

2014/02/19 2.5
    * btex ... etex input from external *.mp files will also be processed
      by luamplib. However, verbatimtex ... etex will be entirely ignored
      in this case.

2014/02/02 2.4
    * implemented "numbersystem" option. Default value "scaled" can be
      changed by declaring \mplibnumbersystem{double}. For details, see
      http://github.com/lualatex/luamplib/issues/21

2014/01/20 2.3
    * \everymplib, \everyendmplib: macros that redefine token lists
      \everymplibtoks and \everyendmplibtoks. These will be
      automatically inserted at the beginning and ending (respectively)
      of each and every mplib code.
    * naked TeX codes, includig \mpdim{...}, are allowed inside
      mplibcode environment. Refer the manual of gmp package for
      details.

2013/12/30 2.2
    * start to support transparency/shading under metafun format.
    * verbatimtex ... etex just before beginfig() is not ignored.
      Using this macro, each mplib box can be moved horizontally and/or
      vertically.

2013/12/23 2.1.1
    * fix a bug wrt "withoutcolor" option
    * fix a bug wrt "char <number> infont <font>" picture
    * bypass some ConTeXt commands which raise errors under metafun format
    * ignore "fontmapfile <filename>" which isn't needed in mplib

2013/12/19 2.1
    * Do not ignore "withcolor" option for textext and normal text object
    * verbatimtex ... etex is now just ignored, not raising error

2013/12/11 2.03
    * implemented textext() macro which is identical to TEX() from TEX.mp.
      TEX() is a synonym of textext().
    * fix a bug regarding tex-text box inside for...endfor loop,
      reported at http://www.ktug.org/xe/index.php?document_srl=178050

2013/09/24 2.01
    * fix bug reported by Stephan Hennig: wrong baseline of tex-text box

2013/05/07 2.0
    * Update with current ConTeXt code
    * Adding the possibility of btex...etex commands (Kim)

2011/12/09 1.09
    * Fix bug reported by Paul Vojta: spurious spaces.

2011/06/23 1.08
    * Fix bug reported by Rolf Dieterich: <, >, TAB anywhere in a luacode
      environment caused errors. The character ` was affected too.

2010/12/28 1.07
    * fix two bugs reported by Arno Trautmann that made the package crash with
      luatex 0.65 (mp 1.5+).
    * remove support for using .mem files (to fix the second bug)

2010/10/17 v1.06
    * bugfix from Hans (bad function name)

2010/10/10 v1.05
    * adapt to luatexbase v0.3

2010/08/02 v1.04
    * fixing a bug in LaTeX's detection (made Tikz fail)
    * setting luamplib-luatex as the default name for the format, it's the case
      in TeXLive 2010
    * adding two test files in the git repository

2010/05/10 v1.03
    * adaptation to the new luatexbase package

