summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/context/sources/general/manuals
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/context/sources/general/manuals')
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi-contents.tex9
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi-fonts.tex99
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi-introduction.tex53
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi-lua.tex38
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi-mixed.tex178
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi-numbering.tex19
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi-style.tex123
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi-titlepage.tex33
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi-vertical.tex18
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi.tex517
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/colors/colors-basics.tex5
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-contents.tex11
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-expansion.tex148
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-fonts.tex732
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-introduction.tex38
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-libraries.tex188
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-normalization.tex239
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-pi.tex134
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-style.tex67
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-threesix.tex739
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-titlepage.tex45
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-whattex.tex155
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore.tex25
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/evenmore/mozilla-svg-001.svg72
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-bitmaps.tex189
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-cleanup.tex332
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-compilation.tex84
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-contents.tex11
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-directions.tex778
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-evolution.tex373
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-feedback.tex306
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-introduction.tex104
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-logging.tex58
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-lua.tex151
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-mp.tex166
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-performance.tex107
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-rejected.tex83
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-retrospect.tex188
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-stripping.tex369
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-stubs.tex262
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-style.tex66
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-tex.tex125
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-titlepage.tex58
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-whatsits.tex78
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup.tex34
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-appendix.tex483
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-demo-rule.lua47
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-environment.tex74
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-extensions.tex2729
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-features.tex2742
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-formats.tex896
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-hooks.tex917
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-introduction.tex95
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-lookups.tex410
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-math.tex1093
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-methods.tex376
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-mkiv.tex76
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-modes.tex817
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-scripts.tex18
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-tricks.tex390
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/libraries/ecmascript-mkiv.tex420
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/libraries/libraries-mkiv.tex152
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/lowlevel/lowlevel-boxes.tex698
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/lowlevel/lowlevel-conditionals.tex1409
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/lowlevel/lowlevel-expansion.tex442
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/lowlevel/lowlevel-registers.tex251
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/lowlevel/lowlevel-style.tex104
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-arrow.tex166
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-axis.tex83
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-chart.tex441
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-contents.tex11
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-contour.tex771
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-followtext.tex124
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-fonts.tex328
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-function.tex296
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-grid.tex11
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-groups.tex52
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-interface.tex155
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-introduction.tex88
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-mesh-examples.tex161
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-mesh.tex78
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-outline.tex188
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-placeholder.tex163
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-shade.tex230
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-style.tex64
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-surface.tex96
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-svg.tex75
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-text.tex137
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-titlepage.tex41
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun.tex34
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametafun/mozilla-svg-001.svg72
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametafun/mozilla-svg-002.svg11
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-callbacks.tex822
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-contents.tex19
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-differences.tex213
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-enhancements.tex1777
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-firstpage.tex36
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-fonts.tex597
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-introduction.tex142
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-languages.tex1095
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-libraries.tex573
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-lua.tex224
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-math.tex1587
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-metapost.tex453
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-modifications.tex440
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-nodes.tex2527
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-pdf.tex565
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-preamble.tex166
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-primitives.tex395
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-registers.tex47
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-statistics.tex17
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-style.tex478
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-tex.tex2481
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-titlepage.tex53
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luatex/luatex-fonts.tex16
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luatex/luatex-modifications.tex14
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luatex/luatex-preamble.tex2
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/luatex/luatex.tex3
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/metafun/metafun-basics.tex2
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/musings/musings-names.tex325
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/musings/musings-plain.tex553
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/musings/musings.tex5
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/onandon/onandon-53.tex262
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/onandon/onandon-execute.tex152
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/publications/122176.pdfbin226229 -> 226353 bytes
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/publications/124484.pdfbin50884 -> 51009 bytes
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/publications/4953942.pdfbin54853 -> 54978 bytes
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/publications/971.pdfbin30653 -> 30796 bytes
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/sql/sql-mkiv.tex4
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/svg/mozilla-tiger.svg1
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/svg/svg-lmtx-microsoft.lua113
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/svg/svg-lmtx-mozilla.lua365
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/svg/svg-lmtx.tex547
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/svg/svglogo.svg261
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/swiglib/swiglib-mkiv-gm-1.pdfbin20433 -> 20555 bytes
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/workflows/workflows-graphics.tex51
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/workflows/workflows-mkiv.tex2
137 files changed, 42794 insertions, 713 deletions
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi-contents.tex b/Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi-contents.tex
new file mode 100644
index 00000000000..21c318dff37
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi-contents.tex
@@ -0,0 +1,9 @@
+% language=us
+
+\startcomponent bidi-contents
+
+ \starttitle[title=Table of contents]
+ \placelist[chapter]
+ \stoptitle
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi-fonts.tex b/Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi-fonts.tex
new file mode 100644
index 00000000000..bfedd8f4745
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi-fonts.tex
@@ -0,0 +1,99 @@
+% language=us
+
+\startcomponent bidi-fonts
+
+\environment bidi-style
+
+\startchapter[title={Setting up fonts}]
+
+So let's see how Arabic and Hebrew come out:
+
+\startbuffer
+The sentence \quotation {I have no clue what this means.} is translated (by
+Google Translate) into \quotation {\ar \righttoleft ليس لدي أي فكرة عما يعنيه هذا.}
+which is then translated back to \quotation {I have no idea what this means.} so
+maybe arabic has no clue what a clue is. The suggested Arabic pronunciation is
+\quotation {lays laday 'ayu fikrat eamaa yaenih hadha}. Hebrew also likes ideas
+more: \quotation {\he \righttoleft אין לי מושג מה זה אומר}.
+\stopbuffer
+
+\typebuffer
+
+\getbuffer
+
+According to Idris Hamid the Arabic should actually be this: \quotation {\ar
+لَيْسَ لَدَيَّ أَيُّ فِكْرَةٍ عَمَّا يَعْنِيهِ هٰذَا} and the transliteration \quotation {Laysa
+ladayya ayyu fikratin ʿammā yaʿnihi hādhā}.
+
+The \CONTEXT\ (or any \TEX) ecosystem deals with languages and fonts. Languages
+(that relate to scripts) have specific characteristics, like running from right
+to left, and fonts provide a repertoire of glyphs and features. There is no real
+(standard) relationship between these. In for instance browsers, there are
+automatic fallback systems for missing characters in a font: another font is
+taken. These fallbacks are often not easy to tweak.
+
+In this document we use Dejavu and although that font has Arabic shapes in its
+monospace variant, the serifs come without them (at least when I write this
+down). Before we actually define the bodyfont we hook in some fallbacks. The
+typescript for Dejavu has lines like this:
+
+\starttyping
+\definefontsynonym
+ [SerifBoldItalic]
+ [name:dejavuserifbolditalic]
+ [features=default,
+ fallbacks=SerifBoldItalic]
+\stoptyping
+
+This permits us to do this:
+
+\typebuffer[preamble-fonts]
+
+In addition we set up the languages:
+
+\typebuffer[preamble-languages]
+
+The following example demonstrates what the effects of these commands are:
+
+\startbuffer
+{لَيْسَ لَدَيَّ أَيُّ فِكْرَةٍ عَمَّا يَعْنِيهِ هٰذَا.}
+{אין לי מושג מה זה אומר.}
+{\righttoleft لَيْسَ لَدَيَّ أَيُّ فِكْرَةٍ عَمَّا يَعْنِيهِ هٰذَا.}
+{\righttoleft אין לי מושג מה זה אומר.}
+{\ar \righttoleft لَيْسَ لَدَيَّ أَيُّ فِكْرَةٍ عَمَّا يَعْنِيهِ هٰذَا.}
+{\he \righttoleft אין לי מושג מה זה אומר.}
+{\ar لَيْسَ لَدَيَّ أَيُّ فِكْرَةٍ عَمَّا يَعْنِيهِ هٰذَا.}
+{\he אין לי מושג מה זה אומר.}
+\stopbuffer
+
+\typebuffer
+
+\startlines
+\getbuffer
+\stoplines
+
+In principle you can also rely on automatic direction changes, for instance
+by using the following command:
+
+\starttyping
+\setupdirections
+ [bidi=global,
+ method=three]
+\stoptyping
+
+But that doesn't do a font switch for you, nor does it do any of the other
+language related settings. It really helps if you properly tag your
+document content, as in:
+
+\starttyping
+{\ar لَيْسَ لَدَيَّ أَيُّ فِكْرَةٍ عَمَّا يَعْنِيهِ هٰذَا.}
+{\he אין לי מושג מה זה אומר.}
+\stoptyping
+
+One reason to set the \type {font} parameter for a language is that it will
+activate the right features in a font. Instead of falling back on some default,
+we can be very specific in what we want to enable.
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi-introduction.tex b/Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi-introduction.tex
new file mode 100644
index 00000000000..5ea0f98798a
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi-introduction.tex
@@ -0,0 +1,53 @@
+% language=us
+
+\startcomponent bidi-introduction
+
+\environment bidi-style
+
+\startchapter[title=Introduction]
+
+With \CONTEXT\ you can typeset in two directions: from left to right and from
+right to left. In fact you can also combine these two directions, like this:
+
+\startbuffer
+There are many {\righttoleft \maincolor \it scripts in use} and some run into the
+other direction. However, there is {\righttoleft \maincolor \it no fixed relation
+{\lefttoright \black \it between the} direction of the script} and cars being
+driven left or right of the road.
+\stopbuffer
+
+\typebuffer
+
+\getbuffer
+
+Even someone not familiar with right to left typesetting can see what happens
+here, or not? In fact Luigi Scarso pointed out that the \type {fixed} reversed
+into {\righttoleft \type {fixed}} but not in the example where {\bf fixed}
+becomes {\righttoleft \bf fixed}. This signals an important property of the way
+the text gets processed: you input something, at some points font features get
+applied (like ligatures) and in the end the resulting glyph stream is reversed.
+By that time the combination of {\bf f}+{\bf i} has become {\bf fi}! So, be
+prepared for surprises.
+
+This manual is written by a left to right user so don't expect a manual on
+semitic typesetting. Also don't expect a (yet) complete manual. I'll add whatever
+comes to mind. This is not a manual about Hebrew or Arabic, if only because I
+can't read any of those scripts (languages). I leave that to others to cover.
+
+This is work in progress and might always be! So expect errors and typos. As with
+anything related to typesetting the truth about how it should be done and what
+looks best is not absolute. So, the most we can offer is flexibility and the way
+\CONTEXT\ is setup permits that.
+
+Of course this is not possible without input. When we moved to \CONTEXT\ \LMTX,
+the bidi thread was picked up by Mohammad Hossein Bateni, Idris Samawi Hamid,
+Wolfgang Schuster and myself. So, expect more!
+
+\startlines
+Hans Hagen
+Hasselt, NL
+\stoplines
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi-lua.tex b/Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi-lua.tex
new file mode 100644
index 00000000000..beb93b6049a
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi-lua.tex
@@ -0,0 +1,38 @@
+% language=us
+
+\startcomponent bidi-lua
+
+\environment bidi-style
+
+\startchapter[title={The \LUA\ interface}]
+
+We assume that you run \CONTEXT\ \MKIV\ in combination with \LUATEX. Direction
+support in this engine has been improved over time. Originally the \OMEGA\
+(\ALEPH) direction model was used but in the meantime it has been stripped to the
+basics, and what used to be so called whatsits (extension nodes) are now first
+class nodes. Of the many directions only four are kept in \LUATEX\ and they are
+indicated by three letters:
+
+\starttabulate[|l|l|l|]
+\NC 0 \NC \type {TLT} \NC left to right \NC \NR
+\NC 1 \NC \type {TRT} \NC right to left \NC \NR
+\NC 2 \NC \type {LTL} \NC not used in context (obsolete) \NC \NR
+\NC 3 \NC \type {RTT} \NC not used in context (obsolete) \NC \NR
+\stoptabulate
+
+In \LUAMETATEX, and therefore \CONTEXT\ \LMTX\ we only have the first two.
+Therefore in \LMTX\ you normally don't have to worry about checking for them at
+the \LUA\ end because they are irrelevant for calculations (the vertical ones
+swapped the horizontal and vertical progression). Also, when really needed, we
+use the \type {direction} keys with numerical indicators, so zero for \type {l2r}
+and one for \type {r2l}. These values are used for local par nodes as well as
+direction nodes. In addition a direction node has a subtype:
+
+\starttabulate[|l|l|l|]
+\NC 0 \NC \type {normal} \NC comparable to \type {+} \NC \NR
+\NC 1 \NC \type {cancel} \NC comparable to \type {-} \NC \NR
+\stoptabulate
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi-mixed.tex b/Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi-mixed.tex
new file mode 100644
index 00000000000..851d6d8b4ef
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi-mixed.tex
@@ -0,0 +1,178 @@
+% language=us
+
+\startcomponent bidi-mixed
+
+\environment bidi-style
+
+\startchapter[title=A mixed layout]
+
+The typesetting engine normally works from left to right and top to bottom. Going
+from right to left actually involved two decisions:
+
+\startitemize[packed]
+\startitem the direction of the display elements, the paragraphs \stopitem
+\startitem the direction of the inline text, the lines \stopitem
+\stopitemize
+
+The first one is kept track of in a state variable. Every paragraph starts with
+a node that carries, among other information, that state. This node is added
+automatically and does not interfere with the typesetting. The inline direction
+is more intrusive as it is marked by nodes that indicate the beginning and end
+of a reversed strip. This mechanism is rather reliable and normally works out
+well. Take this:
+
+\startbuffer
+left {\righttoleft right} left
+left{ \righttoleft right} left
+left {\righttoleft right }left
+left{ \righttoleft right }left
+\stopbuffer
+
+\typebuffer
+
+You can see that we need to be careful with spaces as they can end up inside or
+outside a substream and by swapping next to each other:
+
+\startlines
+\getbuffer
+\stoplines
+
+We can wrap the lines in boxes as in:
+
+\startbuffer
+\hbox{left\space{\bf\righttoleft right}\space left}
+\hbox{left{\bf\space \righttoleft right}\space left}
+\hbox{left\space{\bf\righttoleft right\space}left}
+\hbox{left{\bf\space\righttoleft right\space}left}
+\stopbuffer
+
+\typebuffer
+
+\definecolor[ShineThrough][s=0,a=1,t=.2]
+
+When visualize the spaces we get this:
+
+\startlines\ShineThrough
+\showmakeup[space,hbox]\getbuffer
+\stoplines
+
+The space of a normal and bold font in the same family normally is the same but
+let's mix with a larger size:
+
+\startbuffer
+\hbox{left {\bfa\righttoleft right} left}
+\hbox{left{\bfa\space \righttoleft right} left}
+\hbox{left {\bfa\righttoleft right }left}
+\hbox{left{\bfa\space\righttoleft right }left}
+\stopbuffer
+
+\typebuffer
+
+Now we get the following. As you can see, it really matters where we put the
+braces.
+
+\startlines
+\ShineThrough\showmakeup[space,hbox]\getbuffer
+\stoplines
+
+Once you are accustomed to tagging and \TEX\ you will probably not fall into
+these traps. In \in {figure} [fig:spaces] we show a large version.
+
+\startplacefigure[location=top,title={Watch your spaces!},reference=fig:spaces]
+ \scale
+ [width=\hsize]
+ {\vbox{\ShineThrough\showmakeup[space,hbox]\getbuffer}}
+\stopplacefigure
+
+The \type {\righttoleft} command actually has two meanings. This can best be seen
+from an example.
+
+\startbuffer
+\righttoleft \bf How will this come out?
+\stopbuffer
+
+\typebuffer
+
+\start \getbuffer \par \stop
+
+\startbuffer
+And \righttoleft \bf how will this come out?
+\stopbuffer
+
+\typebuffer
+
+\start \getbuffer \par \stop
+
+When we start a paragraph (or in \TEX\ speak: when we are still in vertical mode)
+the paragraph direction as well as the inline direction is set. Otherwise only
+the inline direction is set. There are low level \TEX\ commands (primitives) to
+set the direction but you can best {\em not} use these because we need to do a
+bit more than that.
+
+There are quite some low level commands related to changing directions. Some deal
+with the layout, some with boxes. We might provide more in the future.
+
+\starttabulate[|l|p|]
+\FL
+\NC \type {\lefttoright} \NC l2r dir node or paragraph property \NC \NR
+\NC \type {\righttoleft} \NC r2l dir node or paragraph property \NC \NR
+\NC \type {\checkedlefttoright} \NC l2r dir node or paragraph property (unless already set) \NC \NR
+\NC \type {\checkedrighttoleft} \NC r2l dir node or paragraph property (unless already set) \NC \NR
+\ML
+\NC \type {\synchronizeinlinedirection} \NC pickup a (possibly) reset state \NC \NR
+\NC \type {\synchronizelayoutdirection} \NC pickup a (possibly) reset state \NC \NR
+\NC \type {\synchronizedisplaydirection} \NC pickup a (possibly) reset state \NC \NR
+\ML
+\NC \type {\righttolefthbox} \NC r2l \type {\hbox} \NC \NR
+\NC \type {\lefttorighthbox} \NC l2r \type {\hbox} \NC \NR
+\NC \type {\righttoleftvbox} \NC r2l \type {\vbox} \NC \NR
+\NC \type {\lefttorightvbox} \NC l2r \type {\vbox} \NC \NR
+\NC \type {\righttoleftvtop} \NC r2l \type {\vtop} \NC \NR
+\NC \type {\lefttorightvtop} \NC l2r \type {\vtop} \NC \NR
+\ML
+\NC \type {\leftorrighthbox} \NC l2r or r2l \type {\hbox} \NC \NR
+\NC \type {\leftorrightvbox} \NC l2r or r2l \type {\vbox} \NC \NR
+\NC \type {\leftorrightvtop} \NC l2r or r2l \type {\vtop} \NC \NR
+\ML
+\NC \type {\autodirhbox} \NC l2r or r2l \type {\hbox} (a bit more clever) \NC \NR
+\NC \type {\autodirvbox} \NC l2r or r2l \type {\vbox} (a bit more clever) \NC \NR
+\NC \type {\autodirvtop} \NC l2r or r2l \type {\vtop} (a bit more clever) \NC \NR
+\ML
+\NC \type {\bidilre} \NC character \type {U+202A}, enforce l2r state \NC \NR
+\NC \type {\bidirle} \NC character \type {U+202B}, enforce r2l state \NC \NR
+\NC \type {\bidipop} \NC character \type {U+202C}, return to last state \NC \NR
+\NC \type {\bidilro} \NC character \type {U+202D}, override l2r state \NC \NR
+\NC \type {\bidirlo} \NC character \type {U+202E}, override r2l state \NC \NR
+\NC \type {\lefttorightmark} \type {\lrm} \NC character \type {U+200E}, l2r indicator \NC \NR
+\NC \type {\righttoleftmark} \type {\rlm} \NC character \type {U+200F}, r2l indicator \NC \NR
+\ML
+\NC \type {\dirlre} \NC switch to l2r mode using \type {\bidilre} or \lefttoright \NC \NR
+\NC \type {\dirrle} \NC switch to r2l mode using \type {\bidirle} or \righttoleft \NC \NR
+\NC \type {\dirlro} \NC enforce l2r mode using \type {\bidilro} or \lefttoright \NC \NR
+\NC \type {\dirrlo} \NC enforce r2l mode using \type {\bidirlo} or \righttoleft \NC \NR
+\ML
+\NC \type {\naturalhbox} \NC a normal l2r \type {hbox} \NC \NR
+\NC \type {\naturalvbox} \NC a normal l2r \type {vbox} \NC \NR
+\NC \type {\naturalvtop} \NC a normal l2r \type {vtop} \NC \NR
+\NC \type {\naturalhpack} \NC a normal l2r \type {hpack} \NC \NR
+\NC \type {\naturalvpack} \NC a normal l2r \type {vpack} \NC \NR
+\LL
+\stoptabulate
+
+When we talk about layout, we mean the overall layout, concerning the document as
+a whole. We can have a dominantly l2r, dominantly r2l or mixed setup. In a next
+chapter we will give more details on the dominant setup. Here we stick to
+mentioning that the document flow direction is set with
+
+\starttyping
+\setupalign[r2l] % or r2l
+\stoptyping
+
+When a command to setup an environment has a \type {align} parameter, the same
+keywords can be uses as part of the specification. \footnote {We haven't tested
+all situations and possible interferences. Just report anomalies to the mailing
+list.}
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi-numbering.tex b/Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi-numbering.tex
new file mode 100644
index 00000000000..c328d6a1a65
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi-numbering.tex
@@ -0,0 +1,19 @@
+% language=us
+
+\startcomponent bidi-numbering
+
+\environment bidi-style
+
+\startchapter[title={Numbering and positioning}]
+
+todo: columns (direction key), numbers (conversionsets), margins (begin/end), etc
+
+% \defineconversionset [\s!default] [] [numbers]
+% \defineconversionset [\v!number] [] [numbers]
+% \defineconversionset [\v!pagenumber] [] [numbers]
+% \defineconversionset [\v!appendix:\s!default] [Romannumerals,Characters] [numbers]
+% \defineconversionset [\v!formula] [numbers,characters] % no \v! ?
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi-style.tex b/Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi-style.tex
new file mode 100644
index 00000000000..1ce4e3b799c
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi-style.tex
@@ -0,0 +1,123 @@
+\startenvironment bidi-style
+
+\usemodule[abr-04]
+
+\dontcomplain
+
+\startbuffer[preamble-fonts]
+\definefontfallback
+ [Serif] [scheherazaderegular*arabic]
+ [arabic] [force=yes,rscale=1.5]
+\definefontfallback
+ [SerifBold] [scheherazadebold*arabic]
+ [arabic] [force=yes,rscale=1.5]
+\definefontfallback
+ [SerifItalic] [scheherazaderegular*arabic]
+ [arabic] [force=yes,rscale=1.5]
+\definefontfallback
+ [SerifBoldItalic] [scheherazadebold*arabic]
+ [arabic] [force=yes,rscale=1.5]
+
+\definefontfallback
+ [Serif] [sileot*hebrew]
+ [hebrew] [force=yes]
+\definefontfallback
+ [SerifBold] [sileot*hebrew]
+ [hebrew] [force=yes]
+\definefontfallback
+ [SerifItalic] [sileot*hebrew]
+ [hebrew] [force=yes]
+\definefontfallback
+ [SerifBoldItalic] [sileot*hebrew]
+ [hebrew] [force=yes]
+
+\definefontfallback
+ [Mono] [almfixed*none]
+ [arabic] [force=yes]
+
+\definefontfallback
+ [Mono] [sileot*none]
+ [hebrew] [force=yes,factor=1] % factor forces a monospace
+
+\setupbodyfont
+ [dejavu,10pt]
+\stopbuffer
+
+\startbuffer[preamble-languages]
+\setuplanguage[ar][font=arabic,bidi=right]
+\setuplanguage[he][font=hebrew,bidi=right]
+\stopbuffer
+
+\getbuffer[preamble-fonts]
+\getbuffer[preamble-languages]
+
+\setuplayout
+ [backspace=15mm,
+ topspace=15mm,
+ footer=0pt,
+ width=middle,
+ height=middle]
+
+% \setuptyping
+% [color=middleblue]
+%
+% \setuptype
+% [color=middleblue]
+
+\usemodule[scite]
+
+\setuptyping
+ [option=TEX]
+
+\setuptype
+ [option=TEX]
+
+\definecolor
+ [maincolor]
+ [middleblue]
+
+\setupwhitespace
+ [big]
+
+\setuphead
+ [color=darkyellow]
+
+\setuphead
+ [chapter]
+ [style=\bfc]
+
+\setuphead
+ [section]
+ [style=\bfb]
+
+\setuphead
+ [subsection]
+ [style=\bfa]
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\startluacode
+ local report = logs.reporter("directions","check")
+ local line = 0
+ function nodes.tracers.checkdirections(head)
+ line = line + 1
+ report("line: %i",line)
+ for n in nodes.traverse_id(nodes.nodecodes.dir,head) do
+ report(" %s (%i,%i)",n.dir,n.subtype,n.direction)
+ end
+ return head, false
+ end
+
+ nodes.tasks.appendaction("contributers","after","nodes.tracers.checkdirections")
+ nodes.tasks.disableaction("contributers","nodes.tracers.checkdirections")
+\stopluacode
+
+\installtextracker
+ {directions.check}
+ {\ctxlua{nodes.tasks.enableaction("contributers","nodes.tracers.checkdirections")}}
+ {\ctxlua{nodes.tasks.disableaction("contributers","nodes.tracers.checkdirections")}}
+
+% \enabletrackers[directions.check]
+% \disabletrackers[directions.check]
+
+\stopenvironment
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi-titlepage.tex b/Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi-titlepage.tex
new file mode 100644
index 00000000000..a80851aea89
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi-titlepage.tex
@@ -0,0 +1,33 @@
+\startcomponent bidi-titlepage
+
+\environment bidi-style
+
+\startMPpage
+
+ picture p, q, r, s ;
+
+ p := textext("l2r") xsized .9PaperWidth ;
+ q := textext("r2l") xsized .9PaperWidth ;
+ r := textext("a few tips") xsized .9PaperWidth ;
+ s := textext("\bf\ss hans\quad\space\quad hagen") xsized .5bbheight(p);
+
+ p := p shifted - llcorner p ;
+ q := q shifted - llcorner q ;
+ r := r shifted - llcorner r ;
+ s := s shifted - llcorner s ;
+
+ fill Page withcolor "darkyellow" ;
+
+ p := p shifted (.05PaperWidth,ypart .5[ulcorner Page, urcorner Page]-1.1bbheight(p)) ;
+ q := q shifted (.05PaperWidth,ypart .5[ulcorner Page, urcorner Page]-1.1bbheight(p)-1.15bbheight(q)) ;
+ r := r shifted (.05PaperWidth,ypart .5[llcorner Page, lrcorner Page]+0.3bbheight(r)) ;
+ s := s shifted (.66PaperWidth,ypart .5[llcorner Page, lrcorner Page]+1.5bbheight(s)) ;
+
+ draw p withcolor "lightgray" ;
+ draw q withcolor "lightgray" ;
+ draw r withcolor "middleblue" ;
+ draw s withcolor "lightgray" ;
+
+\stopMPpage
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi-vertical.tex b/Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi-vertical.tex
new file mode 100644
index 00000000000..824d7a033f8
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi-vertical.tex
@@ -0,0 +1,18 @@
+% language=us
+
+\startcomponent bidi-vertical
+
+\environment bidi-style
+
+\startchapter[title={Going vertical}]
+
+Normally the term bidi is reserved for horizontal direction swapping but there is
+no reason to limit our view to that. So, here I will spend some words on how we
+can deal with vertical directions.
+
+{\em I will move some (not yet public) explanation from elsewhere to here in due
+time.}
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi.tex b/Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi.tex
index abd3f64fa3f..c6fedacdfa4 100644
--- a/Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi.tex
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/bidi/bidi.tex
@@ -1,505 +1,28 @@
-% language=uk
+% Because we cross a threshold in the amount of content the sources
+% have been split into components. This is typical a manual that
+% grows. Feel free to send suggestions and improvements.
-% \showglyphs
+\environment bidi-style
-\usemodule[abr-04]
+\startdocument
-\dontcomplain
+ \component bidi-titlepage
-\startbuffer[preamble-fonts]
-\definefontfallback
- [Serif] [scheherazaderegular*arabic]
- [arabic] [force=yes,rscale=1.5]
-\definefontfallback
- [SerifBold] [scheherazadebold*arabic]
- [arabic] [force=yes,rscale=1.5]
-\definefontfallback
- [SerifItalic] [scheherazaderegular*arabic]
- [arabic] [force=yes,rscale=1.5]
-\definefontfallback
- [SerifBoldItalic] [scheherazadebold*arabic]
- [arabic] [force=yes,rscale=1.5]
+ \startfrontmatter
+ \component bidi-contents
+ \component bidi-introduction
+ \stopfrontmatter
-\definefontfallback
- [Serif] [sileot*hebrew]
- [hebrew] [force=yes]
-\definefontfallback
- [SerifBold] [sileot*hebrew]
- [hebrew] [force=yes]
-\definefontfallback
- [SerifItalic] [sileot*hebrew]
- [hebrew] [force=yes]
-\definefontfallback
- [SerifBoldItalic] [sileot*hebrew]
- [hebrew] [force=yes]
+ \startbodymatter
+ \component bidi-fonts
+ \component bidi-mixed
+ \component bidi-numbering
-\definefontfallback
- [Mono] [almfixed*none]
- [arabic] [force=yes]
+ % work in progress / dev:
+ \component bidi-tables
-\definefontfallback
- [Mono] [sileot*none]
- [hebrew] [force=yes,factor=1] % factor forces a monospace
+ \component bidi-lua
+ \component bidi-vertical
+ \stopbodymatter
-\setupbodyfont
- [dejavu,10pt]
-\stopbuffer
-
-\startbuffer[preamble-languages]
-\setuplanguage[ar][font=arabic,bidi=right]
-\setuplanguage[he][font=hebrew,bidi=right]
-\stopbuffer
-
-\getbuffer[preamble-fonts]
-\getbuffer[preamble-languages]
-
-\setuplayout
- [backspace=15mm,
- topspace=15mm,
- footer=0pt,
- width=middle,
- height=middle]
-
-\setuptyping
- [color=middleblue]
-
-\setuptype
- [color=middleblue]
-
-\definecolor
- [maincolor]
- [middleblue]
-
-\setupwhitespace
- [big]
-
-\setuphead
- [color=darkyellow]
-
-\setuphead
- [chapter]
- [style=\bfc]
-
-\setuphead
- [section]
- [style=\bfb]
-
-\setuphead
- [subsection]
- [style=\bfa]
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\startluacode
- local report = logs.reporter("directions","check")
- local line = 0
- function nodes.tracers.checkdirections(head)
- line = line + 1
- report("line: %i",line)
- for n in nodes.traverse_id(nodes.nodecodes.dir,head) do
- report(" %s (%i,%i)",n.dir,n.subtype,n.direction)
- end
- return head, false
- end
-
- nodes.tasks.appendaction("contributers","after","nodes.tracers.checkdirections")
- nodes.tasks.disableaction("contributers","nodes.tracers.checkdirections")
-\stopluacode
-
-\installtextracker
- {directions.check}
- {\ctxlua{nodes.tasks.enableaction("contributers","nodes.tracers.checkdirections")}}
- {\ctxlua{nodes.tasks.disableaction("contributers","nodes.tracers.checkdirections")}}
-
-% \enabletrackers[directions.check]
-% \disabletrackers[directions.check]
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\starttext
-
-\startMPpage
-
- picture p, q, r, s ;
-
- p := textext("l2r") xsized .9PaperWidth ;
- q := textext("r2l") xsized .9PaperWidth ;
- r := textext("a few tips") xsized .9PaperWidth ;
- s := textext("\bf\ss hans\quad\space\quad hagen") xsized .5bbheight(p);
-
- p := p shifted - llcorner p ;
- q := q shifted - llcorner q ;
- r := r shifted - llcorner r ;
- s := s shifted - llcorner s ;
-
- fill Page withcolor "darkyellow" ;
-
- p := p shifted (.05PaperWidth,ypart .5[ulcorner Page, urcorner Page]-1.1bbheight(p)) ;
- q := q shifted (.05PaperWidth,ypart .5[ulcorner Page, urcorner Page]-1.1bbheight(p)-1.15bbheight(q)) ;
- r := r shifted (.05PaperWidth,ypart .5[llcorner Page, lrcorner Page]+0.3bbheight(r)) ;
- s := s shifted (.66PaperWidth,ypart .5[llcorner Page, lrcorner Page]+1.5bbheight(s)) ;
-
- draw p withcolor "lightgray" ;
- draw q withcolor "lightgray" ;
- draw r withcolor "middleblue" ;
- draw s withcolor "lightgray" ;
-
-\stopMPpage
-
-\startchapter[title=Introduction]
-
-With \CONTEXT\ you can typeset in two directions: from left to right and from
-right to left. In fact you can also combine these two directions, like this:
-
-\startbuffer
-There are many {\righttoleft \maincolor \it scripts in use} and some run into the
-other direction. However, there is {\righttoleft \maincolor \it no fixed relation
-{\lefttoright \black \it between the} direction of the script} and cars being
-driven left or right of the road.
-\stopbuffer
-
-\typebuffer
-
-\getbuffer
-
-Even someone not familiar with right to left typesetting can see what happens
-here, or not? In fact Luigi Scarso pointed out that the \type {fixed} reversed
-into {\righttoleft \type {fixed}} but not in the example where {\bf fixed}
-becomes {\righttoleft \bf fixed}. This signals an important property of the way
-the text gets processed: you input something, at some points font features get
-applied (like ligatures) and in the end the resulting glyph stream is reversed.
-By that time the combination of {\bf f}+{\bf i} has become {\bf fi}! So, be
-prepared for surprises.
-
-This manual is written by a left to right user so don't expect a manual on
-semitic typesetting. Also don't expect a (yet) complete manual. I'll add whatever
-comes to mind. This is not a manual about Hebrew or Arabic, if only because I
-can't read any of those scripts (languages). I leave that to others to cover.
-
-{\em This is work in progress! So expect errors and typos.}
-
-\startlines
-Hans Hagen
-Hasselt, NL
-\stoplines
-
-\stopchapter
-
-\startchapter[title={Setting up fonts}]
-
-So let's see how Arabic and Hebrew come out:
-
-\startbuffer
-The sentence \quotation {I have no clue what this means.} is translated (by
-Google Translate) into \quotation {\ar \righttoleft ليس لدي أي فكرة عما يعنيه هذا.}
-which is then translated back to \quotation {I have no idea what this means.} so
-maybe arabic has no clue what a clue is. The suggested Arabic pronunciation is
-\quotation {lays laday 'ayu fikrat eamaa yaenih hadha}. Hebrew also likes ideas
-more: \quotation {\he \righttoleft אין לי מושג מה זה אומר}.
-\stopbuffer
-
-\typebuffer
-
-\getbuffer
-
-According to Idris Hamid the Arabic should actually be this: \quotation {\ar
-لَيْسَ لَدَيَّ أَيُّ فِكْرَةٍ عَمَّا يَعْنِيهِ هٰذَا} and the transliteration \quotation {Laysa
-ladayya ayyu fikratin ʿammā yaʿnihi hādhā}.
-
-The \CONTEXT\ (or any \TEX) ecosystem deals with languages and fonts. Languages
-(that relate to scripts) have specific characteristics, like running from right
-to left, and fonts provide a repertoire of glyphs and features. There is no real
-(standard) relationship between these. In for instance browsers, there are
-automatic fallback systems for missing characters in a font: another font is
-taken. These fallbacks are often not easy to tweak.
-
-In this document we use Dejavu and although that font has Arabic shapes in its
-monospace variant, the serifs come without them (at least when I write this
-down). Before we actually define the bodyfont we hook in some fallbacks. The
-typescript for Dejavu has lines like this:
-
-\starttyping
-\definefontsynonym
- [SerifBoldItalic]
- [name:dejavuserifbolditalic]
- [features=default,
- fallbacks=SerifBoldItalic]
-\stoptyping
-
-This permits us to do this:
-
-\typebuffer[preamble-fonts]
-
-In addition we set up the languages:
-
-\typebuffer[preamble-languages]
-
-The following example demonstrates what the effects of these commands are:
-
-\startbuffer
-{لَيْسَ لَدَيَّ أَيُّ فِكْرَةٍ عَمَّا يَعْنِيهِ هٰذَا.}
-{אין לי מושג מה זה אומר.}
-{\righttoleft لَيْسَ لَدَيَّ أَيُّ فِكْرَةٍ عَمَّا يَعْنِيهِ هٰذَا.}
-{\righttoleft אין לי מושג מה זה אומר.}
-{\ar \righttoleft لَيْسَ لَدَيَّ أَيُّ فِكْرَةٍ عَمَّا يَعْنِيهِ هٰذَا.}
-{\he \righttoleft אין לי מושג מה זה אומר.}
-{\ar لَيْسَ لَدَيَّ أَيُّ فِكْرَةٍ عَمَّا يَعْنِيهِ هٰذَا.}
-{\he אין לי מושג מה זה אומר.}
-\stopbuffer
-
-\typebuffer
-
-\startlines
-\getbuffer
-\stoplines
-
-In principle you can also rely on automatic direction changes, for instance
-by using the following command:
-
-\starttyping
-\setupdirections
- [bidi=global,
- method=three]
-\stoptyping
-
-But that doesn't do a font switch for you, nor does it do any of the other
-language related settings. It really helps if you properly tag your
-document content, as in:
-
-\starttyping
-{\ar لَيْسَ لَدَيَّ أَيُّ فِكْرَةٍ عَمَّا يَعْنِيهِ هٰذَا.}
-{\he אין לי מושג מה זה אומר.}
-\stoptyping
-
-One reason to set the \type {font} parameter for a language is that it will
-activate the right features in a font. Instead of falling back on some default,
-we can be very specific in what we want to enable.
-
-\stopchapter
-
-\startchapter[title=A mixed layout]
-
-The typesetting engine normally works from left to right and top to bottom. Going
-from right to left actually involved two decisions:
-
-\startitemize[packed]
-\startitem the direction of the display elements, the paragraphs \stopitem
-\startitem the direction of the inline text, the lines \stopitem
-\stopitemize
-
-The first one is kept track of in a state variable. Every paragraph starts with
-a node that carries, among other information, that state. This node is added
-automatically and does not interfere with the typesetting. The inline direction
-is more intrusive as it is marked by nodes that indicate the beginning and end
-of a reversed strip. This mechanism is rather reliable and normally works out
-well. Take this:
-
-\startbuffer
-left {\righttoleft right} left
-left{ \righttoleft right} left
-left {\righttoleft right }left
-left{ \righttoleft right }left
-\stopbuffer
-
-\typebuffer
-
-You can see that we need to be careful with spaces as they can end up inside or
-outside a substream and by swapping next to each other:
-
-\startlines
-\getbuffer
-\stoplines
-
-We can wrap the lines in boxes as in:
-
-\startbuffer
-\hbox{left\space{\bf\righttoleft right}\space left}
-\hbox{left{\bf\space \righttoleft right}\space left}
-\hbox{left\space{\bf\righttoleft right\space}left}
-\hbox{left{\bf\space\righttoleft right\space}left}
-\stopbuffer
-
-\typebuffer
-
-\definecolor[ShineThrough][s=0,a=1,t=.2]
-
-When visualize the spaces we get this:
-
-\startlines\ShineThrough
-\showmakeup[space,hbox]\getbuffer
-\stoplines
-
-The space of a normal and bold font in the same family normally is the same but
-let's mix with a larger size:
-
-\startbuffer
-\hbox{left {\bfa\righttoleft right} left}
-\hbox{left{\bfa\space \righttoleft right} left}
-\hbox{left {\bfa\righttoleft right }left}
-\hbox{left{\bfa\space\righttoleft right }left}
-\stopbuffer
-
-\typebuffer
-
-Now we get the following. As you can see, it really matters where we put the
-braces.
-
-\startlines
-\ShineThrough\showmakeup[space,hbox]\getbuffer
-\stoplines
-
-Once you are accustomed to tagging and \TEX\ you will probably not fall into
-these traps. In \in {figure} [fig:spaces] we show a large version.
-
-\startplacefigure[location=top,title={Watch your spaces!},reference=fig:spaces]
- \scale
- [width=\hsize]
- {\vbox{\ShineThrough\showmakeup[space,hbox]\getbuffer}}
-\stopplacefigure
-
-
-The \type {\righttoleft} command actually has two meanings. This can best be seen
-from an example.
-
-\startbuffer
-\righttoleft \bf How will this come out?
-\stopbuffer
-
-\typebuffer
-
-\start \getbuffer \par \stop
-
-\startbuffer
-And \righttoleft \bf how will this come out?
-\stopbuffer
-
-\typebuffer
-
-\start \getbuffer \par \stop
-
-When we start a paragraph (or in \TEX\ speak: when we are still in vertical mode)
-the paragraph direction as well as the inline direction is set. Otherwise only
-the inline direction is set. There are low level \TEX\ commands (primitives) to
-set the direction but you can best {\em not} use these because we need to do a
-bit more than that.
-
-There are quite some low level commands related to changing directions. Some deal
-with the layout, some with boxes. We might provide more in the future.
-
-\starttabulate[|l|p|]
-\FL
-\NC \type {\lefttoright} \NC l2r dir node or paragraph property \NC \NR
-\NC \type {\righttoleft} \NC r2l dir node or paragraph property \NC \NR
-\NC \type {\checkedlefttoright} \NC l2r dir node or paragraph property (unless already set) \NC \NR
-\NC \type {\checkedrighttoleft} \NC r2l dir node or paragraph property (unless already set) \NC \NR
-\ML
-\NC \type {\synchronizeinlinedirection} \NC pickup a (possibly) reset state \NC \NR
-\NC \type {\synchronizelayoutdirection} \NC pickup a (possibly) reset state \NC \NR
-\NC \type {\synchronizedisplaydirection} \NC pickup a (possibly) reset state \NC \NR
-\ML
-\NC \type {\righttolefthbox} \NC r2l \type {\hbox} \NC \NR
-\NC \type {\lefttorighthbox} \NC l2r \type {\hbox} \NC \NR
-\NC \type {\righttoleftvbox} \NC r2l \type {\vbox} \NC \NR
-\NC \type {\lefttorightvbox} \NC l2r \type {\vbox} \NC \NR
-\NC \type {\righttoleftvtop} \NC r2l \type {\vtop} \NC \NR
-\NC \type {\lefttorightvtop} \NC l2r \type {\vtop} \NC \NR
-\ML
-\NC \type {\leftorrighthbox} \NC l2r or r2l \type {\hbox} \NC \NR
-\NC \type {\leftorrightvbox} \NC l2r or r2l \type {\vbox} \NC \NR
-\NC \type {\leftorrightvtop} \NC l2r or r2l \type {\vtop} \NC \NR
-\ML
-\NC \type {\autodirhbox} \NC l2r or r2l \type {\hbox} (a bit more clever) \NC \NR
-\NC \type {\autodirvbox} \NC l2r or r2l \type {\vbox} (a bit more clever) \NC \NR
-\NC \type {\autodirvtop} \NC l2r or r2l \type {\vtop} (a bit more clever) \NC \NR
-\ML
-\NC \type {\bidilre} \NC character \type {U+202A}, enforce l2r state \NC \NR
-\NC \type {\bidirle} \NC character \type {U+202B}, enforce r2l state \NC \NR
-\NC \type {\bidipop} \NC character \type {U+202C}, return to last state \NC \NR
-\NC \type {\bidilro} \NC character \type {U+202D}, override l2r state \NC \NR
-\NC \type {\bidirlo} \NC character \type {U+202E}, override r2l state \NC \NR
-\NC \type {\lefttorightmark} \type {\lrm} \NC character \type {U+200E}, l2r indicator \NC \NR
-\NC \type {\righttoleftmark} \type {\rlm} \NC character \type {U+200F}, r2l indicator \NC \NR
-\ML
-\NC \type {\dirlre} \NC switch to l2r mode using \type {\bidilre} or \lefttoright \NC \NR
-\NC \type {\dirrle} \NC switch to r2l mode using \type {\bidirle} or \righttoleft \NC \NR
-\NC \type {\dirlro} \NC enforce l2r mode using \type {\bidilro} or \lefttoright \NC \NR
-\NC \type {\dirrlo} \NC enforce r2l mode using \type {\bidirlo} or \righttoleft \NC \NR
-\ML
-\NC \type {\naturalhbox} \NC a normal l2r \type {hbox} \NC \NR
-\NC \type {\naturalvbox} \NC a normal l2r \type {vbox} \NC \NR
-\NC \type {\naturalvtop} \NC a normal l2r \type {vtop} \NC \NR
-\NC \type {\naturalhpack} \NC a normal l2r \type {hpack} \NC \NR
-\NC \type {\naturalvpack} \NC a normal l2r \type {vpack} \NC \NR
-\LL
-\stoptabulate
-
-When we talk about layout, we mean the overall layout, concerning the document as
-a whole. We can have a dominantly l2r, dominantly r2l or mixed setup. In a next
-chapter we will give more details on the dominant setup. Here we stick to
-mentioning that the document flow direction is set with
-
-\starttyping
-\setupalign[r2l] % or r2l
-\stoptyping
-
-When a command to setup an environment has a \type {align} parameter, the same
-keywords can be uses as part of the specification. \footnote {We haven't tested
-all situations and possible interferences. Just report anomalies to the mailing
-list.}
-
-\stopchapter
-
-\startchapter[title={Numbering and positioning}]
-
-todo: columns (direction key), numbers (conversionsets), margins (begin/end), etc
-
-\stopchapter
-
-\startchapter[title={The \LUA\ interface}]
-
-We assume that you run \CONTEXT\ \MKIV\ in combination with \LUATEX. Direction
-support in this engine has been improved over time. Originally the \OMEGA\
-(\ALEPH) direction model was used but in the meantime it has been stripped to the
-basics, and what used to be so called whatsits (extension nodes) are now first
-class nodes. In the \LUA\ interface we still support the:
-
-\startitemize[packed]
-\startitem
- \type {TLT} and \type {TRT} keywords for local par nodes
-\stopitem
-\startitem
- \type {+TLT}, \type {-TLT}, \type {+TRT} and \type {-TRT} keywords for
- direction nodes
-\stopitem
-\stopitemize
-
-However, because we use dedicated nodes, and because nodes actually store numbers
-and not strings we also expose the numeric model:
-
-\starttabulate[|l|l|l|]
-\NC 0 \NC \type {TLT} \NC left to right \NC \NR
-\NC 1 \NC \type {TRT} \NC right to left \NC \NR
-\NC 2 \NC \type {LTL} \NC not used in context \NC \NR
-\NC 3 \NC \type {RTT} \NC not used in context \NC \NR
-\stoptabulate
-
-These values are used for local par nodes as well as direction nodes. In addition
-a direction node has a subtype:
-
-\starttabulate[|l|l|l|]
-\NC 0 \NC \type {normal} \NC comparable to \type {+} \NC \NR
-\NC 1 \NC \type {cancel} \NC comparable to \type {-} \NC \NR
-\stoptabulate
-
-The \type {dir} field uses the strings, the \type {direction} field the number
-(both of course share the same internal node variable).
-
-\stopchapter
-
-\stoptext
-
-% \defineconversionset [\s!default] [] [numbers]
-% \defineconversionset [\v!number] [] [numbers]
-% \defineconversionset [\v!pagenumber] [] [numbers]
-% \defineconversionset [\v!appendix:\s!default] [Romannumerals,Characters] [numbers]
-% \defineconversionset [\v!formula] [numbers,characters] % no \v! ?
+\stopdocument
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/colors/colors-basics.tex b/Master/texmf-dist/doc/context/sources/general/manuals/colors/colors-basics.tex
index 4d7822bd0a1..3832501c5d2 100644
--- a/Master/texmf-dist/doc/context/sources/general/manuals/colors/colors-basics.tex
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/colors/colors-basics.tex
@@ -874,9 +874,8 @@ will keep their color.
This is what we get in \MKIV: \start \inlinebuffer \stop
-When we use fonts switches we don't expect the content of the
-box to change. So, in the following the \quote {default} texts will
-{\em not} become bold.
+When we use fonts switches we don't expect the content of the box to change. So,
+in the following the \quote {default} texts will {\em not} become bold.
\startbuffer
\setbox0\hbox{default {\sl slanted \bi bold italic} default}
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-contents.tex b/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-contents.tex
new file mode 100644
index 00000000000..d20b45eee6c
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-contents.tex
@@ -0,0 +1,11 @@
+\startcomponent evenmore-contents
+
+\environment evenmore-style
+
+\starttitle[title={Table of contents}]
+
+ \placelist[chapter]
+
+\stoptitle
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-expansion.tex b/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-expansion.tex
new file mode 100644
index 00000000000..6c67f07d634
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-expansion.tex
@@ -0,0 +1,148 @@
+% language=us
+
+\environment evenmore-style
+
+\startcomponent evenmore-expansion
+
+\startchapter[title=Expansion]
+
+Character expansion was introduced in \PDFTEX\ a couple of decades ago. It is a
+mechanism that scales glyphs horizontally in order to reduce excessive whitespace
+that is needed to properly justify a paragraph. I must admit that I never use it
+myself but there are users who do. Although this mechanism evolved a bit, and in
+\LUATEX\ is implemented a bit different, the basics remained the same. If you
+have no clue what this is about, you can just quite reading here.
+
+A font can be set up to expand characters by a certain amount: they can shrink or
+stretch. This is driven by three parameters: \type {step}, \type {stretch} and
+\type {shrink}. The values are in thousands because \TEX\ has no float quantity.
+Originally these values were percentages of the width of a glyph, later they
+became related to the em width but in \LUATEX\ we went back to the former
+definition.
+
+In \CONTEXT\ \MKIV\ we have an interface that works as follows:
+
+\startbuffer
+\startluacode
+ local classes = fonts.expansions.classes
+
+ classes.qualitya = {
+ vector = "default",
+ factor = 1,
+ stretch = 4,
+ shrink = 2,
+ step = .5,
+ }
+
+ classes.qualityb = {
+ vector = "default",
+ factor = 1,
+ stretch = 8,
+ shrink = 4,
+ step = .5,
+ }
+
+\stopluacode
+\stopbuffer
+
+\typebuffer[option=TEX] \getbuffer
+
+The default vector looks like this:
+
+\starttyping[option=LUA]
+vectors['default'] = {
+ [0x0041] = 0.5, -- A
+ [0x0042] = 0.7, -- B
+ -- and some more
+}
+\stoptyping
+
+The values that we pass to the engine are stretch 40, shrink 20, and step 5 for
+\type {qualitya} and stretch 80, shrink 40, and step 5 for \type {qualityb}, so
+we multiply by 10. In the engine the step is limited to 100, the stretch to 1000
+and the shrink to 500. But these extremes produce quite bad results.
+
+The expansion class is set with the \type {expansion} feature, as in:
+
+\startbuffer
+\definefontfeature [basea] [default] [expansion=qualitya]
+\definefontfeature [baseb] [default] [expansion=qualityb]
+
+\definefont [FontA] [Serif*basea]
+\definefont [FontB] [Serif*baseb]
+
+\stopbuffer
+
+\typebuffer[option=TEX] \getbuffer
+
+\startbuffer[sample]
+ \setupalign[verytolerant,stretch,hz] % hz triggers expansion
+ \dorecurse {30} {%
+ {\FontB \darkred test me #1,} \FontA \dorecurse{#1}{test ##1, }%
+ }\par
+\stopbuffer
+
+In \in {figure} [hz:1] we see this in action, using the following code:
+
+\typebuffer[sample][option=TEX]
+
+\startplacefigure[reference=hz:1]
+ \getbuffer[sample]
+\stopplacefigure
+
+There is one drawback with this method, although so far I never heard a user
+complain, which can be an indication of how this mechanism is used: you cannot
+mix fonts with different step, stretch and|/|or shrink. As we just did this in
+the example, this statement is not really true in \LUAMETATEX: there we only need
+to keep the step the same. This is compatible in the sense that otherwise we
+would quit the run, so at least we carry on: the smallest stretch and shrink is
+taken. But, we do issue a warning (once) because there can be side effects! This
+is not that pretty a solution anyway because it depends on what font is used
+first.
+
+It is for this reason that we have another option: in \CONTEXT\ \LMTX\ you can
+define a specific expansion:
+
+\startbuffer
+\defineexpansion
+ [myexpansion]
+ [step=1, % default
+ stretch=50,
+ shrink=20]
+\stopbuffer
+
+\typebuffer[option=TEX] \getbuffer
+
+There is no need to have a different step than~1. In \PDFTEX\ instances are
+created per step used, but in \LUATEX\ this is more fluid. There is no gain in
+using different steps. We just keep it for compatibility reasons. This specific
+expansion is enables with:
+
+\starttyping[option=TEX]
+\setexpansion[myexpansion]
+\stoptyping
+
+and the result is shown in \in {figure} [hz:2]. This time the set expansion wins
+over the one set in the font. All fonts that have the expansion feature set are
+treated the same. By using this method you can locally have different values.
+
+\startplacefigure[reference=hz:2]
+ \setexpansion[myexpansion]
+ \getbuffer[sample]
+\stopplacefigure
+
+Deep down we use some new primitives:
+
+\starttyping[option=TEX]
+\adjustspacingstep
+\adjustspacingstretch
+\adjustspacingshrink
+\stoptyping
+
+The step is limited to 100 (10\percent) and the stretch and shrink to 500
+(50\percent) and the stretch to 1000 (100\percent) but these extremes are only
+useful for examples.
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-fonts.tex b/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-fonts.tex
new file mode 100644
index 00000000000..fea3f7ac5ac
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-fonts.tex
@@ -0,0 +1,732 @@
+% language=us
+
+\environment evenmore-style
+
+\disabledirectives[fonts.svg.cached]
+
+% \usemodule[scite]
+% \usemodule[article-basic]
+% \usemodule[abbreviations-logos]
+
+\startcomponent evenmore-fonts
+
+\startchapter[title=Modern Type 3 fonts]
+
+Support for \TYPETHREE\ fonts has been on my agenda for a couple of years now.
+Here I will take a look at them from the perspective of \LUAMETATEX. \footnote
+{This chapter appeared in \TUGBOAT\ 40:3. Thanks to Karl Berry for corrections.}
+The reason is that they might be useful for embedding (for instance) runtime
+graphics (such as symbols) in an efficient way. In \TEX\ systems \TYPETHREE\
+fonts are normally used for bitmap fonts, the \PK\ output that comes via
+\METAFONT. Where for instance \TYPEONE\ fonts are defined using a set of font
+specific rendering operators, a \TYPETHREE\ font can contain arbitrary code, in
+\PDF\ files these are \PDF\ (graphic and text) operators.
+
+A program like \LUATEX\ supports embedding of several font formats natively. A
+quick summary of relevant formats is the following: \footnote {Technically one
+can embed anything in the \PDF\ file.}
+
+\startitemize[headintext][headstyle=bold]
+\starthead {\TYPEONE:}
+ these are outline fonts using \type {cff} descriptions, a compact format for
+ storing outlines. Normally up to 256 characters are accessible but a font can
+ have many more (as Latin Modern and \TEX\ Gyre demonstrate).
+\stophead
+\starthead {\OPENTYPE:}
+ these also use the \type {cff} format. As with \TYPEONE\ the outlines are
+ mostly cubic Bezier curves. Because there is no bounding box data stored in
+ the format the engine has to pseudo|-|render the glyphs to get that
+ information. When embedding a subset the backend code has to flatten the
+ subroutine calls, which is another reason the \type {cff} blob has to be
+ disassembled.
+\stophead
+\starthead {\TRUETYPE:}
+ these use the \type {ttf} format which uses quadratic B|-|splines. The font
+ can have a separate kerning table and stores information about the bounding
+ box (which is then used by \TEX\ to get the right heights and depths of
+ glyphs). Of course those details never make it into the \PDF\ file as such.
+\stophead
+\starthead {\TYPETHREE:}
+ as mentioned this format is (traditionally) used to store bitmap fonts but as
+ we will see it can do more. It is actually the easiest format to deal with.
+\stophead
+\stopitemize
+
+In \LUATEX\ any font can be a \quotation {wide} font, therefore in \CONTEXT\ a
+\TYPEONE\ font is not treated differently than an \OPENTYPE\ font. The \LUATEX\
+backend can even disguise a \TYPEONE\ font as an \OPENTYPE\ font. In the end, as
+not that much information ends up in the \PDF\ file, the differences are not that
+large for the first three types. The content of a \TYPETHREE\ font is less
+predictable but even then it can have for instance a \type {ToUnicode} vector so
+it has no real disadvantages in, say, accessibility. In \CONTEXT\ \LMTX, which
+uses \LUAMETATEX\ without any backend, all is dealt with in \LUA: loading,
+tweaking, applying and embedding.
+
+The difference between \OPENTYPE\ and \TRUETYPE\ is mostly in the kind of curves
+and specific data tables. Both formats are nowadays covered by the \OPENTYPE\
+specification. If you Google for the difference between these formats you can
+easily end up with rather bad (or even nonsense) descriptions. The best
+references are \typ {https://en.wikipedia.org/wiki/Bézier_curve} and the
+ever|-|improving \typ {https://docs.microsoft.com/en-us/typography} website.
+
+Support for so|-|called variable fonts is mostly demanding of the front|-|end
+because in the backend it is just an instance of an \OPENTYPE\ or \TRUETYPE\ font
+being embedded. In this case the instance is generated by the \CONTEXT\ font
+machinery which interprets the \type {cff} and \type {ttf} binary formats in
+doing~so. This feature is not widely used but has been present from the moment
+these fonts showed up.
+
+\TYPETHREE\ fonts don't have a particularly good reputation, which is mainly due
+to the fact that viewers pay less attention in displaying them, at least that was
+the case in the past. If they describe outlines, then all is okay, apart from the
+fact that there is no anti|-|aliasing or hinting but on modern computers that is
+hardly an issue. For bitmaps the quality depends on the resolution and
+traditionally \TEX\ bitmap fonts are generated for a specific device, but if you
+use a decent resolution (say 1200 dpi) then all should be okay. The main drawback
+is that viewers will render such a font and cache the (then available) bitmap
+which in some cases can have a speed penalty.
+
+Using \TYPETHREE\ fonts in a \PDF\ backend is not something new. Already in the
+\PDFTEX\ era we were playing with so|-|called \PDF\ glyph containers. In practice
+that worked okay but not so much for \METAPOST\ output from \METAFONT\ fonts. As
+a side note: it might actually work better now that in \METAFUN\ we have some
+extensions for rendering the kind of paths used in fonts. But glyph containers
+were dropped long ago already and \TYPETHREE\ was limited to traditional \TEX\
+bitmap inclusion. However, in \LUAMETATEX\ it is easier to mess around with fonts
+because we no longer need to worry about side effects of patching font related
+inclusion (embedding) for other macro packages. All is now under \LUA\ control:
+there is no backend included and therefore no awareness of something built|-|in
+as \TYPETHREE.
+
+So, as a prelude to the 2019 \CONTEXT\ meeting, I picked up this thread and
+turned some earlier experiments into production code. Originally I meant to
+provide support for \METAPOST\ graphics but that is still locked in experiments.
+I do have an idea for its interface, now that we have more control over user
+interfaces in \METAFUN.
+
+In addition to \quote {just graphics} there is another candidate for \TYPETHREE\
+fonts \emdash\ extensions to \OPENTYPE\ fonts:
+
+\startitemize[packed,n]
+\startitem Color fonts where stacked glyphs are used (a nice method). \stopitem
+\startitem Fonts where \SVG\ images are used. \stopitem
+\startitem Fonts that come with bitmap representations in \PNG\ format. \stopitem
+\stopitemize
+
+It will be no surprise that we're talking of emoji fonts here although the second
+category is now also used for regular text fonts. When these fonts showed up
+support for them was not that hard to implement and (as often) we could make
+\TEX\ be among the first to support them in print (often such fonts are meant for
+the web).
+
+For category one, the stacked shapes, the approach was to define a virtual font
+where glyphs are flushed while backtracking over the width in order to get the
+overlay. Of course color directives have to be injected too. The whole lot is
+wrapped in a container that tells a \PDF\ handler what character actually is
+represented. Due to the way virtual fonts work, every reference to a character
+results in the same sequence of glyph references, (negative) kern operations and
+color directives plus the wrapper in the page stream. This is not really an issue
+for emoji because these are seldom used and even then in small quantities. But it
+can explode a \PDF\ page stream for a color text font. All happens at runtime and
+because we use virtual fonts, the commands are assembled beforehand for each
+glyph.
+
+For the second category, \SVG\ images, we used a different approach. Each symbol
+was converted to \PDF\ using Inkscape and cached for later use. Instead of
+injecting a glyph reference, a reference to a so|-|called \type {XForm} is
+injected, again with a wrapper to indicate what character we deal with. Here the
+overhead is not that large but still present as we need the so|-|called \quote
+{actual text} wrapper.
+
+The third category is done in a similar way but this time we use GraphicsMagick
+to convert the images beforehand. The drawbacks are the same.
+
+In \CONTEXT\ \LMTX\ a different approach is followed. The \PDF\ stream that
+stacks the glyphs of category one makes a perfect stream for a \TYPETHREE\
+character. Apart from some juggling to relate a \TYPETHREE\ font to an \OPENTYPE\
+font, the page stream just contains references to glyphs (with the proper related
+\UNICODE\ slot). The overhead is minimal.
+
+For the second category \CONTEXT\ \LMTX\ uses its built|-|in \SVG\ converter. The
+\XML\ code of the shape is converted to (surprise): \METAPOST. We could go
+directly to \PDF\ but the \METAPOST\ route is cheap and we can then get support
+for color spaces, transformations, efficient paths and high quality all for free.
+It also opens up the possibility for future manipulations. The \TYPETHREE\ font
+eventually has a sequence of drawing operations, mixed with transformations and
+color switches, but only once. Most of the embedded code is shared with the other
+categories (a plug|-|in model is used).
+
+The third category follows a similar route but this time we use the built|-|in
+\PNG\ inclusion code. Just like the other categories, the page stream only
+contains references to glyphs.
+
+It was interesting to find that most of the time related to the inclusion went
+into figuring out why viewers don't like these fonts. For instance, in Acrobat
+there needs to be a glyph at index zero and all viewers seem to be able to handle
+at most 255 additional characters in a font. But once that, and a few more
+tricks, had become clear, it worked out quite well. It also helps to set the font
+bounding box to all zero values so that no rendering optimizations kick in. Also,
+some dimensions can are best used consistently. With \SVG\ there were some issues
+with reference points and bounding boxes but these could be dealt with. A later
+implementation followed a slightly different route anyway.
+
+The implementation is reasonably efficient because most work is delayed till a
+glyph (shape) is actually injected (and most shapes in these fonts aren't used at
+all). The viewers that I have installed, Acrobat Reader, Acrobat X, and the
+mupdf|-|based Sumatra\PDF\ viewer can all handle the current implementation.
+
+An example of a category one font is \MICROSOFT's \type {seguiemj}. I have no
+clue about the result in the future because some of these emoji fonts change
+every now and then, depending also on social developments. This is a category one
+font which not only has emoji symbols but also normal glyphs:
+
+\startbuffer[1a]
+\definefontfeature[colored][default][colr=yes]
+\definefont[TestA][file:seguiemj.ttf*colored]
+\definesymbol[bug1][\getglyphdirect{file:seguiemj.ttf*colored} {\char"1F41C}]
+\definesymbol[bug2][\getglyphdirect{file:seguiemj.ttf*colored} {\char"1F41B}]
+\stopbuffer
+
+\typebuffer[1a][option=TEX] \getbuffer[1a]
+
+The example below demonstrates this by showing the graphic glyph surrounded by
+the \type {x} from the emoji font, and from a regular text font.
+
+\startbuffer[1b]
+{\TestA x\char"1F41C x\char"1F41B x}%
+\quad
+{x\symbol[bug1]x\symbol[bug2]x}%
+\quad
+{\showglyphs x\symbol[bug1]x\symbol[bug2]x}%
+\stopbuffer
+
+\typebuffer[1b][option=TEX]
+
+\startlinecorrection
+\scale[width=\textwidth]{\getbuffer[1b]}
+\stoplinecorrection
+
+In this mix we don't use a \TYPETHREE\ font for the characters that don't need
+stacked (colorful) glyphs, which is more efficient. So the \type {x} characters
+are references to a regular (embedded) \OPENTYPE\ font.
+
+The next example comes from a manual and demonstrates that we can (still)
+manipulate colors as we wish.
+
+\startbuffer[1c]
+\definecolor[emoji-red] [r=.4]
+\definecolor[emoji-blue] [b=.4]
+\definecolor[emoji-green] [g=.4]
+\definecolor[emoji-yellow][r=.4,g=.5]
+\definecolor[emoji-gray] [s=1,t=.5,a=1]
+
+\definefontcolorpalette
+ [emoji-red]
+ [emoji-red,emoji-gray]
+
+\definefontcolorpalette
+ [emoji-green]
+ [emoji-green,emoji-gray]
+
+\definefontcolorpalette
+ [emoji-blue]
+ [emoji-blue,emoji-gray]
+
+\definefontcolorpalette
+ [emoji-yellow]
+ [emoji-yellow,emoji-gray]
+
+\definefontfeature[seguiemj-r][default][ccmp=yes,dist=yes,colr=emoji-red]
+\definefontfeature[seguiemj-g][default][ccmp=yes,dist=yes,colr=emoji-green]
+\definefontfeature[seguiemj-b][default][ccmp=yes,dist=yes,colr=emoji-blue]
+\definefontfeature[seguiemj-y][default][ccmp=yes,dist=yes,colr=emoji-yellow]
+
+\definefont[MyColoredEmojiR][seguiemj*seguiemj-r]
+\definefont[MyColoredEmojiG][seguiemj*seguiemj-g]
+\definefont[MyColoredEmojiB][seguiemj*seguiemj-b]
+\definefont[MyColoredEmojiY][seguiemj*seguiemj-y]
+\stopbuffer
+
+\typebuffer[1c][option=TEX] \getbuffer[1c]
+
+\startbuffer[1d]
+\MyColoredEmojiR\resolvedemoji{man}\resolvedemoji{woman}%
+\MyColoredEmojiG\resolvedemoji{man}\resolvedemoji{woman}%
+\MyColoredEmojiB\resolvedemoji{man}\resolvedemoji{woman}%
+\MyColoredEmojiY\resolvedemoji{man}\resolvedemoji{woman}%
+\stopbuffer
+
+\startlinecorrection
+ \scale[width=\textwidth]{\getbuffer[1d]}
+\stoplinecorrection
+
+Let's look in more detail at the woman emoji. On the left we see the default
+colors, and on the right we see our own:
+
+\definefontfeature[seguiemj][default][ccmp=yes,dist=yes,colr=yes]
+\definefont[MyColoredEmojiD][seguiemj*seguiemj]
+
+\startlinecorrection
+\scale[height=2cm]
+ {\MyColoredEmojiD\resolvedemoji{woman}%
+ \MyColoredEmojiR\resolvedemoji{woman}}
+\stoplinecorrection
+
+The multi|-|color variant in \CONTEXT\ \MKIV\ ends up as follows in the page
+stream:
+
+\starttyping
+/Span << /ActualText <feffD83DDC69> >> BDC
+q
+0.000 g
+BT
+/F8 11.955168 Tf
+1 0 0 1 0 2.51596 Tm [<045B>]TJ
+0.557 0.337 0.180 rg
+1 0 0 1 0 2.51596 Tm [<045C>]TJ
+1.000 0.784 0.239 rg
+1 0 0 1 0 2.51596 Tm [<045D>]TJ
+0.000 g
+1 0 0 1 0 2.51596 Tm [<045E>]TJ
+0.969 0.537 0.290 rg
+1 0 0 1 0 2.51596 Tm [<045F>]TJ
+0.941 0.227 0.090 rg
+1 0 0 1 0 2.51596 Tm [<0460>]TJ
+ET
+Q
+EMC
+\stoptyping
+
+and the reddish one becomes:
+
+\starttyping[option=PDF]
+/Span << /ActualText <feffD83DDC69> >> BDC
+q
+0.400 0 0 rg 0.400 0 0 RG
+BT
+/F8 11.955168 Tf
+1 0 0 1 0 2.51596 Tm [<045B>]TJ
+1 g 1 G /Tr1 gs
+1 0 0 1 0 2.51596 Tm [<045C>1373<045D>1373<045E>1373<045F>1373<0460>]TJ
+ET
+Q
+EMC
+\stoptyping
+
+Each time this shape is typeset these sequences are injected. In \CONTEXT\ \LMTX\
+we get this in the page stream:
+
+\starttyping[option=PDF]
+BT
+/F2 11.955168 Tf
+1 0 0 1 0 2.515956 Tm [<C8>] TJ
+ET
+\stoptyping
+
+This time the composed shape ends up in the \TYPETHREE\ character procedure. In
+the colorful case (reformatted because it actually is a one|-|liner):
+
+\starttyping[option=PDF]
+2812 0 d0
+0.000 g BT /V8 1 Tf [<045B>] TJ ET
+0.557 0.337 0.180 rg BT /V8 1 Tf [<045C>] TJ ET
+1.000 0.784 0.239 rg BT /V8 1 Tf [<045D>] TJ ET
+0.000 g BT /V8 1 Tf [<045E>] TJ ET
+0.969 0.537 0.290 rg BT /V8 1 Tf [<045F>] TJ ET
+0.941 0.227 0.090 rg BT /V8 1 Tf [<0460>] TJ ET
+\stoptyping
+
+and in the reddish case (where we have a gray transparent color):
+
+\starttyping[option=PDF]
+2812 0 d0
+0.400 0 0 rg 0.400 0 0 RG
+BT /V8 1 Tf [<045B>] TJ ET
+1 g 1 G /Tr1 gs
+BT /V8 1 Tf [<045C>] TJ ET
+BT /V8 1 Tf [<045D>] TJ ET
+BT /V8 1 Tf [<045E>] TJ ET
+BT /V8 1 Tf [<045F>] TJ ET
+BT /V8 1 Tf [<0460>] TJ ET
+\stoptyping
+
+but this time we only get these verbose compositions once in the \PDF\ file. We
+could optimize the last variant by a sequence of indices and negative kerns but
+it hardly pays off. There is no need for \type {ActualText} here because we have
+an entry in the \type {ToUnicode} vector:
+
+\starttyping[option=PDF]
+<C8> <D83DDC69>
+\stoptyping
+
+To be clear, the \type {/V8} is a sort of local reference to a font which can
+have an \type {/F8} counterpart elsewhere. These \TYPETHREE\ fonts have their own
+resource references and I found it more clear to use a different prefix in that
+case. If we only use a few characters of this kind, of course the overhead of
+extra fonts has a penalty but as soon we refer to more characters we gain a lot.
+
+When we have \SVG\ fonts, the gain is a bit less. The \PDF\ resulting from the
+\METAPOST\ run can of course be large but they are included only once. In \MKIV\
+these would be (shared) so|-|called \type {XForm}s. In the page stream we then
+see a simple reference to such an \type {XForm} but again wrapped into an \type
+{ActualText}. In \LMTX\ we get just a reference to a \TYPETHREE\ character plus
+of course an extra font.
+
+The \typ {emojionecolor-svginot} font is somewhat problematic (although maybe in
+the meantime it has become obsolete). As usual with new functionality,
+specifications are not always available or complete (especially when they are
+application specs turned into standards). This is also true with for instance
+\SVG\ fonts. The current documentation on the \MICROSOFT\ website is reasonable
+and explains how to deal with the viewport but when I first implemented support
+for \SVG\ it was more trial and error. The original implementation in \CONTEXT\
+used Inkscape to generate \PDF\ files with a tight bounding box and mix that with
+information from the font (in \MKIV\ and the generic loader we still use this
+method). This results in a reasonable placement for emoji (that often sit on top
+of the baseline) but not for characters. More accurate treatment, using the
+origin and bounding box, fail for graphics with bad viewports and strange
+transform attributes. Now one can of course argue that I read the specs wrong,
+but inconsistencies are hard to deal with. Even worse is that successive versions
+of a font can demand different hacks. (I would not be surprised if some programs
+have built|-|in heuristics for some fonts that apply fixes.) Here is an example:
+
+\starttyping
+<svg transform="translate(0 -1788) scale(2.048)" viewBox="0 0 64 64" ...>
+ <path d="... all within the viewBox ..." ... />
+</svg>
+\stoptyping
+
+It is no problem to scale up the image to normal dimensions, often 1000, or 2048
+but I've also seen 512. The 2.048 suggests a 2048 unit approach, as does the 1788
+shift. Now, we could scale up all dimensions by 1000/64 and then multiply by
+2.048 and eventually shift over 1788, but why not scale the 1788 by 2.048 or
+scale 64 by 2.048? Even if we can read the standard to suit this specification
+it's just a bit too messy for my taste. In fact I tried all reasonable
+combinations and didn't (yet) get the right result. In that case it's easier to
+just discard the font. If a user complains that it (kind of) worked in the past,
+a counter|-|argument can be that other (more recent) fonts don't work otherwise.
+In the end we ended up with an option: when the \type {svg} feature value is
+\type {fixdepth} the vertical position will be fixed.
+
+\startbuffer[2a]
+\definefontfeature[whatever][default][color=yes,svg=fixdepth]
+\definefont[TestB][file:emojionecolor-svginot.ttf*whatever]
+\stopbuffer
+
+\typebuffer[2a][option=TEX] \getbuffer[2a]
+
+\startbuffer[2b]
+x{\TestB \char"1F41C \char"1F41B}x
+\stopbuffer
+
+\startlinecorrection
+ \scale[height=1cm]{\getbuffer[2b]}
+\stoplinecorrection
+
+The newer \type {emojionecolor} font doesn't need this because it has a \type
+{viewBox} of \type {0 54.4 64 64} which fixes the baseline.
+
+\startbuffer[2c]
+\definefontfeature[whatever][default][color=yes,svg=yes]
+\definefont[TestB][file:emojionecolor.otf*whatever]
+\stopbuffer
+
+\typebuffer[2c][option=TEX] \getbuffer[2c]
+
+\startlinecorrection
+ \scale[height=1cm]{\getbuffer[2b]}
+\stoplinecorrection
+
+Another example of a pitfall is running into category one glyphs made from
+several pieces that all have the same color. If that color is black, one starts
+to wonder what is wrong. In the end the \CONTEXT\ code was doing the right thing
+after all, and I would not be surprised if that glyph gets colors in an update of
+the font. For that reason it makes no sense to include them as examples here.
+After all, we can hardly complain about free fonts (and I'm also guilty of
+imposing bugs on users). By the way, for the font referred to here (\type
+{twemojimozilla}), another pitfall was that all shapes in my copy had a zero
+bounding box which means that although a width is specified, rendering in
+documents can give weird side effects. This can be corrected by the \type
+{dimensions} feature that forces the ascender and descender values to be used.
+
+\startbuffer[3a]
+\definefontfeature[colored:x][default][colr=yes]
+\definefontfeature[colored:y][default][colr=yes,dimensions={1,max,max}]
+\definefont[TestC][file:twemojimozilla.ttf*colored:x]
+\definefont[TestD][file:twemojimozilla.ttf*colored:y]
+\stopbuffer
+
+\typebuffer[3a][option=TEX] \getbuffer[3a]
+
+\startbuffer[3b]
+{\TestC\char 128028}\quad{\showglyphs\TestC\char 128028}\quad
+{\TestD\char 128028}\quad{\showglyphs\TestD\char 128028}
+\stopbuffer
+
+\startlinecorrection
+ \scale[height=2cm]{\getbuffer[3b]}
+\stoplinecorrection
+
+An example of a \PNG|-|enhanced font is the \type {applecoloremoji} font. The
+bitmaps are relatively large for the quality they provide and some look like
+scans.
+
+\startbuffer[4a]
+\definefontfeature[sbix][default][sbix=yes]
+\definefont[TestE][file:applecoloremoji.ttc*sbix at 10bp]
+\stopbuffer
+
+\typebuffer[4a][option=TEX] \getbuffer[4a]
+
+\startbuffer[4b]
+\red \TestE \char 35 \char 9203 \char 9202
+\stopbuffer
+
+\startlinecorrection
+ \scale[height=1cm]{\getbuffer[4b]}
+\stoplinecorrection
+
+As mentioned above, there are fonts that color characters other than emoji. We
+give two examples (sometimes fonts are mentioned on the \CONTEXT\ mailing list).
+
+\startbuffer[5a]
+\definefontfeature
+ [whatever]
+ [default,color:svg]
+ [script=latn,
+ language=dflt]
+
+\definefont[TestF][file:Abelone-FREE.otf*whatever @ 13bp]
+\definefont[TestG][file:Gilbert-ColorBoldPreview5*whatever @ 13bp]
+\definefont[TestH][file:ColorTube-Regular*whatever @ 13bp]
+\stopbuffer
+
+\typebuffer[5a][option=TEX] \getbuffer[5a]
+
+Of course one can wonder about the readability of these fonts and unless one used
+random colors (which bloats the file immensely) it might become boring, but
+typically such fonts are only meant for special purposes.
+
+\startbuffer[5b]
+ {\TestF\setupinterlinespace[0.7]\input zapf \par}
+\stopbuffer
+
+\startbuffer[5c]
+ {\TestG\setupinterlinespace \input zapf \par}
+\stopbuffer
+
+\startbuffer[5d]
+ {\TestH\setupinterlinespace[0.7]\input zapf \par}
+\stopbuffer
+
+\start \setupalign[tolerant] \getbuffer[5b] \stop
+
+The previous font is the largest and as a consequence also puts some strain on
+the viewer, especially when zooming in. But, because viewers cache \TYPETHREE\
+shapes it's a one|-|time penalty.
+
+\start \setupalign[tolerant] \getbuffer[5c] \stop
+
+This font is rather lightweight. Contrary to what one might expect, there is no
+transparency used (but of course we do support that when needed).
+
+\start \setupalign[tolerant] \getbuffer[5d] \stop
+
+This third example is again rather lightweight. Such fonts normally have a rather
+limited repertoire although there are some accented characters included. But they
+are not really meant for novels anyway. If you look closely you will also notice
+that some characters are missing and kerning is suboptimal.
+
+I considered testing some more fonts but when trying to download some interesting
+looking ones I got a popup asking me for my email address in order to subscribe
+me to something: a definite no|-|go.
+
+%\section{\SVG\ to MetaPost}
+
+I already mentioned that we have a built|-|in converter that goes from \SVG\ to
+\METAPOST. Although this article deals with fonts, the following code
+demonstrates that we can also access such graphics in \METAFUN\ itself. The nice
+thing is that because we get pictures, they can be manipulated.
+
+\startbuffer
+\startMPcode{doublefun}
+ picture p ; p := lmt_svg [ filename = "mozilla-svg-001.svg" ] ;
+ numeric w ; w := bbwidth(p) ;
+ draw p ;
+ draw p xscaled -1 shifted (2.5*w,0);
+ draw p rotatedaround(center p,45) shifted (3.0*w,0) ;
+ draw image (
+ for i within p : if filled i :
+ draw pathpart i withcolor green ;
+ fi endfor ;
+ ) shifted (4.5*w,0);
+ draw image (
+ for i within p : if filled i :
+ fill pathpart i withcolor red withtransparency (1,.25) ;
+ fi endfor ;
+ ) shifted (6*w,0);
+\stopMPcode
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+This graphic is a copy from a glyph from an emoji font, so we have plenty of such
+images to play with. The above manipulations result in:
+
+\startlinecorrection
+ \getbuffer
+\stoplinecorrection
+
+Now that we're working with \METAPOST\ we may as well see if we can also load a
+specific glyph, and indeed this is possible.
+
+\startbuffer[1]
+\startMPcode{doublefun}
+ picture lb, rb ;
+ lb := lmt_svg [ fontname = "Gilbert-ColorBoldPreview5", unicode = 123 ] ;
+ rb := lmt_svg [ fontname = "Gilbert-ColorBoldPreview5", unicode = 125 ] ;
+ numeric dx ; dx := 1.25 * bbwidth(lb) ;
+ draw lb ;
+ draw rb shifted (dx,0) ;
+ pickup pencircle scaled 2mm ;
+ for i within lb :
+ draw lmt_arrow [
+ path = pathpart i,
+ pen = "auto",
+ alternative = "curved",
+ penscale = 8
+ ]
+ shifted (3dx,0)
+ withcolor "darkblue"
+ withtransparency (1,.5)
+ ;
+ endfor ;
+ for i within rb :
+ draw lmt_arrow [
+ path = pathpart i,
+ pen = "auto",
+ alternative = "curved",
+ penscale = 8
+ ]
+ shifted (4dx,0)
+ withcolor "darkred"
+ withtransparency (1,.5)
+ ;
+ endfor ;
+\stopMPcode
+\stopbuffer
+
+% Ok, I should make a macro ...
+
+\startbuffer[2]
+\startMPcode{doublefun}
+ picture lb, rb ;
+ lb := lmt_svg [ fontname = "Gilbert-ColorBoldPreview5", unicode = 42 ] ;
+ rb := lmt_svg [ fontname = "Gilbert-ColorBoldPreview5", unicode = 64 ] ;
+ numeric dx ; dx := 1.25 * bbwidth(lb) ;
+ draw lb ;
+ draw rb shifted (dx,0) ;
+ pickup pencircle scaled 2mm ;
+ for i within lb :
+ draw lmt_arrow [
+ path = pathpart i,
+ pen = "auto",
+ alternative = "curved",
+ penscale = 6
+ ]
+ shifted (3.5dx,0)
+ withcolor "darkgreen"
+ withtransparency (1,.5)
+ ;
+ endfor ;
+ for i within rb :
+ draw lmt_arrow [
+ path = pathpart i,
+ pen = "auto",
+ alternative = "curved",
+ penscale = 6
+ ]
+ shifted (4.5dx,0)
+ withcolor "darkyellow"
+ withtransparency (1,.5)
+ ;
+ endfor ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[1][option=TEX]
+
+Here we first load two character shapes from a font. The \UNICODE\ slots (which
+here are the same as the \ASCII\ slots) might look familiar: they indicate the
+curly brace characters. We get two pictures and use the \type {within} loop to
+run over the paths within these shapes. Each shape is made from three curves. As
+a bonus a few more characters are shown.
+
+\startlinecorrection
+ \dontleavehmode
+ \scale[height=3cm]{\getbuffer[1]}%
+ \quad\quad\quad\quad
+ \scale[height=3cm]{\getbuffer[2]}
+\stoplinecorrection
+
+It is not hard to imagine that a collection of such graphics could be made into a
+font (at runtime). One only needs to find the motivation. Of course one can
+always use a font editor (or Inkscape) and tweak there, which probably makes more
+sense, but sometimes a bit of \METAPOST\ hackery is a nice distraction. Editing
+the \SVG\ code directly is not that much fun. The overall structure often doesn't
+look that bad (apart from often rather redundant grouping):
+
+\starttyping[option=XML]
+<svg xmlns="http://www.w3.org/2000/svg">
+ <path fill="#d87512" d="..."/>
+ <g fill="#bc600d">
+ <path d="..."/>
+ </g>
+ <g fill="#d87512">
+ <path d="..."/>
+ <path d="..."/>
+ </g>
+ <g fill="#bc600d">
+ <path d="..."/>
+ </g>
+ ...
+</svg>
+\stoptyping
+
+In addition to \type {path}s there can be \type {line}, \type {circle} and
+similar elements but often fonts just use the \type {path} element. This element
+has a \type {d} attribute that holds a sequence of one character commands that
+each can be followed by numbers. Here are the start characters of four such
+attributes:
+
+\starttyping
+M11.585 43.742s.387 1.248.104 3.05c0 0 2.045-.466 1.898-2.27 ...
+M53.33 39.37c0-4.484-35.622-4.484-35.622 0 0 10.16.05 ...
+M42.645 56.04c1.688 2.02 9.275.043 10.504-2.28 5.01-9.482-.006 ...
+M54.2 41.496s-.336 4.246-4.657 9.573c0 0 4.38-1.7 5.808-4.3 ...
+\stoptyping
+
+Indeed, numbers can be pasted together, also with the operators, which doesn't
+help with seeing at a glance what happens. Probably the best reference can be
+found at \typ {https://developer.mozilla.org/en-US/docs/Web/SVG} where it is
+explained that a path can have move, line, curve, arc and other operators, as
+well use absolute and relative coordinates. How that works is for another
+article.
+
+How would the \TEX\ world look like today if Don Knuth had made \METAFONT\
+support colors? Of course one can argue that it is a bitmap font generator, but
+in our case using high resolution bitmaps might even work out better. In the
+example above the first text fragment uses a font that is very inefficient: it
+overlays many circles in different colors with slight displacements. Here a
+bitmap font would not only give similar effects but probably also be more
+efficient in terms of storage as well as rendering. The \METAPOST\ successor does
+support color and with \MPLIB\ in \LUATEX\ we can keep up quite well \unknown\ as
+hopefully has been demonstrated here.
+
+
+% It's no fun messing with these things that survive only for short time before
+% being replaced by the next hyped fashion. Typical work than one needs to be paid
+% for but never is.
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-introduction.tex b/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-introduction.tex
new file mode 100644
index 00000000000..d5bfbdad760
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-introduction.tex
@@ -0,0 +1,38 @@
+% language=us
+
+\startcomponent evenmore-introduction
+
+\environment evenmore-style
+
+\startchapter[title={Introduction}]
+
+After five collections of \quote {articles} about the development of \LUATEX,
+\CONTEXT\ \MKIV, \LUAMETATEX\ and \CONTEXT\ \LMTX, there is even more to tell so
+here is number six. Wrapping up not only serves to inform the users but for me it is
+also a way to get things right: if you cannot write it down it's no good. It forces
+me to (re)consider interfaces and also test new code but of course it comes with
+no guarantees.
+
+When writing this introduction I just finished the first chapter, about some new
+font stuff, as follow up on the (again) nice \CONTEXT\ meeting in 2019. It's
+always inspiring to meet and talk with my \TEX\ friends and see what they're
+doing. It keeps me going.
+
+Some chapters end up in user group journals first so they will be added once they
+have been published and are available. The advantage is that these are then
+copy|-|edited. Many texts, also in previous development updates, got better
+because Karl Berry checked them thoroughly for TUGboat, for which I'm grateful.
+
+Hopefully, this document serves a purpose.
+
+\blank[2*big]
+
+\startlines
+Hans Hagen
+PRAGMA ADE, Hasselt NL
+Started in October 2019
+\stoplines
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-libraries.tex b/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-libraries.tex
new file mode 100644
index 00000000000..5cca165bb35
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-libraries.tex
@@ -0,0 +1,188 @@
+% language=us
+
+\startcomponent evenmore-libraries
+
+\environment evenmore-style
+
+\startchapter[title={Libraries}]
+
+\startsection[title={Introduction}]
+
+The \LUAMETATEX\ binary comes with a couple of libraries built in. These normally
+provide enough functionality to get a \TEX\ job done. But take the case where
+need to manipulate (or convert) an image before we can include it? It would be
+nice if \CONTEXT\ does that for you so having some features in the binary that
+handle it make sense. However, given that such a conversion only happens once it
+makes more sense to just call an external program and let that deal with it. It
+is for that reason that the \CONTEXT\ code base has hardly any library related
+code: most of what one wants to do can be done by calling a program. Some callers
+are built in, others can be dealt with using the Adityas filter module. The most
+significant runtime exception is probably accessing \SQL\ databases where it
+might be more efficient to use a library call instead of calling a client. And
+even then the main reason for that interface being present is the simple fact
+that I (ab)use the engine to serve requests that need some kind of database
+access. Another example of where we need some external program is in generating
+barcodes. Here one can argue that it does make sense to do that runtime, for
+instance because they change or because one doesn't like to have dozens of cached
+barcode images on disk.
+
+In this chapter I will explain how we deal with libraries in \LUAMETATEX. Because
+libraries create a dependency an approach is chosen that tries to avoid bloating
+the source tree with additional header and source files. This is made easy by the
+fact that we don't need full blown interfaces to libraries where all methods are
+exposed. We know what we need and most of these tasks somehow relate to
+typesetting which is a limited application with known demands in terms of input,
+output and performance. We don't need to serve every possible scenario.
+
+\stopsection
+
+\startsection[title={Using \LUA\ libraries}]
+
+One approach is to use a \LUA\ library that sits between the embedded \LUA\ instance
+and the external library. Say that one does this:
+
+\starttyping
+local mylib = require("mylib")
+\stoptyping
+
+This can locate and load the file \type {mylib.lua} which implements a bunch of
+(\LUA) functions. But, it can also load a library, for instance \type
+{mylib.dll}, a binary that provides functions that themselves can call external
+ones. Often such a library is also responsible for some resource management which
+is then done via userdata objects. Such a connector library on the one hand
+refers to \LUA\ library methods (like \type {const char * str = lua_tostring (L,
+1);} for fetching a \LUA\ string variable from the argument list) and on the
+other hand to those in the external library (like passing that string \type {str}
+to a function and passing the result back to \LUA\ with \type {lua_pushstring (L,
+result);}). If we would follow that approach in \LUAMETATEX\ it means that in
+addition to the main binary (on \MSWINDOWS\ that is \type {luametatex.exe}) there
+is also an extra intermediate binary (on \MSWINDOWS\ that is \type {mylib.dll})
+plus the external library (on \MSWINDOWS\ that could be \type {foolib.dll}) which
+itself can depend on other libraries.
+
+In this approach we need to compile the extra intermediate libraries alongside
+the main \LUAMETATEX\ binary. Quite likely we then need access to the header
+files of the external libraries too. We might even decide to put the dependencies
+in our source tree. But, this is not what we like to do: it adds extra work, we
+need to keep an eye on updates and operating specific patches, we complicate the
+compilation, etc. This all contradicts the fact that we want \LUAMETATEX\ to be
+simple. There is no need to complicate the setup just because a very few users
+want to use some library. Add to this the fact that quite likely we need to
+provide a version of \LUAMETATEX\ that exposes its \LUA\ related symbols which
+makes for a larger binary. So, this approach is not really an option because
+at the same time we like to keep the binary (and memory footprint) as small
+as possible (think of running in a container or on a low energy device).
+
+\stopsection
+
+\startsection[title=A variant]
+
+There are a few issues when you use \LUA\ libraries from elsewhere. First of all,
+you need to get hold of one that matches the version of \LUA\ that you use. There
+are not that many and some only can be set up as part of a larger framework.
+Also, you can find plenty of modules that seem not to be maintained (or maybe
+they are just very stable and I'm wrong here). Also, not all platforms are
+supported equally well. Then there is the question to what extend libraries are
+to stay. What is considered to be the standard today might not be tomorrow. Even
+in the rather stable \TEX\ ecosystem we see them come and go. These are all
+reasons to avoid hard coded dependencies. Ideally we like users to be able to
+compile \LUAMETATEX\ in the future without too must hassle.
+
+A couple of years after we started the \LUATEX\ project, a solution for using
+libraries was implemented, called \SWIGLIB, because it uses the swig
+infrastructure. It was an attempt to come up with a more or less standard
+approach, a rather one|-|to|-|one mapping so that basically any library could be
+interfaced. But, probably because no one really needs libraries, it never catched
+on. In \MKIV\ we still support loading libraries made that way but in \LMTX\ that
+code has been removed.
+
+As a side note: the code that deals with this in \MKIV\ also deals with version
+specific loading. When we were playing with for instance \MYSQL\ libs we found
+out that it made sense to be able to support different \API s, but in the end,
+given the rare usage of libraries, that made no sense either. Therefore in \LMTX\
+locating libraries has version support removes and as a consequence is much
+simpler (code|-|wise).
+
+\stopsection
+
+\startsection[title=Foreign function interfaces]
+
+Then there is a \FFI\ interface, first introduced in \LUAJITTEX\ as it is part of
+\LUAJIT, and later a similar library was built|-|in \LUATEX. But \LUAJIT\ doesn't
+conceptually follow \LUA\ upgrades and its future is unsure so in \LUAMETATEX\
+there is no \JIT\ variant (the \JIT\ part was never used anyway as it only slowed
+down a run; we just used the \FFI\ part plus the fact that the restricted virtual
+machine performs better). The \FFI\ library used in \LUATEX\ also comes from
+elsewhere and it doesn't seem to be maintained any longer, so that code is to be
+kept working in the perspective of \LUATEX. Both technologies hook into the
+processor architecture and are somewhat complex so when their maintenance becomes
+unsure we have to reconsider using them. Not all hardware platforms are supported
+\footnote {As I write this only Intel works while ARM doesn't and only on
+\MSWINDOWS, \LINUX\ and \OSX\ I can compile without alignment warnings} and the
+functionality can differ in details per platform. To some extend we can keep
+using \FFI\ in \LUATEX\ because Luigi takes care of it, but who knows when it
+becomes too problematic. Does it make sense to adopt a library that needs tweaks
+depending on architectures? For now we're good for \LUATEX, so for a while we're
+also okay (in \MKIV).
+
+The nice thing about \FFI\ is that one can define the interface at runtime. Of
+course this interface has to fit the current version of the library \API, but
+that is doable. It is up to a user of a library to determine where it comes from.
+It can be put in the \TEX\ tree but also being taken from wherever the operating
+system put it in the path. Of course that can then be a bit of an issue when
+there are different versions because programs can ship their own variants, but
+when you use a library you probably are aware of that and know what you're doing.
+A drawback of \FFI\ is that it opens up the whole machinery pretty low level,
+which can be considered a risk. Some can consider that to be a security threat.
+It for these reasons that \LUAMETATEX\ doesn't provide the \FFI\ feature; users
+who depend on it can of course use \MKIV\ with \LUATEX.
+
+\stopsection
+
+\startsection[title=So how to proceed?]
+
+When a library and its \LUA\ interface are kept external the main binary has to
+be compiled in a way that permits loading libraries (read: symbols need to be
+known). When we use \FFI\ that is not needed. And when a library is internal we
+have the disadvantage that we mentioned at the start of this chapter.
+
+So, how do we combine the advantages of \FFI\ (runtime binding), external
+libraries (no need to have all that code in the code base) and internal libraries
+(no loading issues)? At some point it stroke me that we actually can do that with
+not that much effort. The solution was probably subconsciously implanted by
+noticing the fact that the \LUAMETATEX\ machinery uses function pointers in some
+places and the fact that when a \LUA\ library is loaded by \LUA\ itself, a
+specific initialization function is called to initialize it: by combining these
+concepts we can delay the binding till when a library is needed.
+
+In \LUAMETATEX\ we can therefore have some optional libraries that offer a
+minimal interface because after all we can do a lot at the \LUA\ end. Optional
+libraries register themselves in the global \type {optional} table. We're talking
+of a couple of hundred lines of \CCODE\ for a simple binding. The functions in an
+optional library table can be used (accessed) without loading the library and
+then just do nothing useful. So, before using them you need to load the third
+party library but we can safely assume that the \LUA\ wrapper code calls an
+initializer when it needs some feature. That initializer, which by the way is
+located at the \LUA\ end, loads the external library, and when that is successful
+the needed helpers are bound by resolving function pointers. There is no
+dependency when nothing is used: the main binary stays lean and mean because the
+binding normally only adds a few \KB. Users can compile without dependencies and
+when used performance is quite okay (no \FFI\ overhead).
+
+The \LUAMETATEX\ distribution only ships a few such bindings but these can serve
+as example. What is shipped has a proper \LUA\ companion file and these are then
+the standard one used in the \CONTEXT\ distribution. Think of \MYSQL\ and
+\SQLITE\ (for databases), \ZINT\ (for barcodes), simple \CURL\ (for fetching
+stuff), \GHOSTSCRIPT\ and \GRAPHICSMAGICK\ (for some conversions) bindings . When
+compiled into \LUAMETATEX\ these will add some interfacing code to the main
+binary but that gets compensated by the removal of the \FFI\ library. The \LUA\
+interfaces provide just enough to get us going. At some point we can consider
+providing libraries as optional part of an installation because we can generate
+them using the buildbot infrastructure managed by Mojca, but the core
+distribution (source code) is kept clean.
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-normalization.tex b/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-normalization.tex
new file mode 100644
index 00000000000..36d4390aaff
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-normalization.tex
@@ -0,0 +1,239 @@
+% language=us
+
+% \enabletrackers[nodes.directions]
+
+\environment evenmore-style
+
+\startcomponent evenmore-normalization
+
+\startchapter[title=Normalization]
+
+What I describe here was long due. I delayed it because when enabled it had best
+also be used and I need to (check and) adapt some code to it in order to profit
+from it. So, if used at all, it will take some time to have an effect on the
+\CONTEXT\ code base. But first some background information.
+
+When \TEX\ builds a paragraph it splits the current text stream (that makes up
+the paragraph) into lines where each line becomes an horizontal box. In \LUATEX,
+this process is split into distinctive steps, contrary to regular \TEX\ where the
+splitting is combined with hyphenation, ligature construction and font kerning.
+But what all engines have in common is that after the decision is made about what
+a line is, the result gets packages into the horizontal box.
+
+The decision making is influenced by quite some factors, like:
+
+\startitemize[packed]
+\startitem
+ The indentation of the first line, driven by the presence of a box of
+ with a certain width and no height and depth (its always there, also when
+ the indentation is zero).
+\stopitem
+\startitem
+ Hanging indentation, which can happen at each corner of the paragraph, or
+ alternatively a specific parshape.
+\stopitem
+\startitem
+ Left and|/|or right margins, aka left skip and right skip. A right skip is
+ always present, even when zero.
+\stopitem
+\startitem
+ The way the last line gets aligns, aka parfill skip.
+\stopitem
+\startitem
+ Directional changes that need to be carries over to the next line.
+\stopitem
+\startitem
+ Optional protrusion of characters to the left of right of the line, something
+ that is sensitive for directional changes.
+\stopitem
+\startitem
+ Expansion of characters in order to get better inter|-|word spacing and|/|or
+ to prevent lines being too bad. There can be stretch as well as shrink but
+ on a per line basis. Inter|-|character kerns can also get that treatment.
+\stopitem
+\startitem
+ The penalties associated to hyphenation: the pre|-|last line, the last two
+ lines, a list of penalties (\ETEX), specific penalties bound to hyphenation
+ pints (\LUATEX).
+\stopitem
+\startitem
+ The wish to have more or less lines than optimal, aka looseness. I have to
+ admit that I never use that feature.
+\stopitem
+\stopitemize
+
+In traditional \TEX\ it doesn't really matter how the resulting boxes look like,
+as long as the following steps can handle them, and those steps don't look into
+those boxes. In fact, unless you unpack a box, only the backend deals with the
+content. But in \LUATEX\ we have callbacks that hook into several stages and {\em
+can} look into the constructed boxes. In \LUATEX\ these boxes also have embedded
+directional information (needed by the backend) and (although that is seldom
+used) left or right boxed material, a features inherited from \ALEPH|/|\OMEGA.
+And when messing around with the content of boxes one has to know what can be
+seen there. In principle the code can be reorganized a it but adding additional
+functionality is not that trivial because we want to stay close to the original
+implementation, even if it has been messed up a bit by successive additions.
+Eventually I might give it a try to integrate all these features a bit better,
+but on the other hand: it works.
+
+\starttexdefinition Sample #1#2
+ \startluacode
+ document.normalizestate = nodes.getnormalizeline()
+ nodes.setnormalizeline(#1)
+ \stopluacode
+ \startsubsubject[title={normalization #1, #2}]
+ \typebuffer[#2]
+ \startlinecorrection
+ \forgetall
+ \start
+ \setupalign[verytolerant,stretch]
+ \showmakeup[line,hbox,vbox,glue]
+ \vbox{\getbuffer[#2]\samplefile{sapolsky}}
+ \stop
+ \par
+ \stoplinecorrection
+ \stopsubject
+ \startluacode
+ nodes.setnormalizeline(document.normalizestate)
+ \stopluacode
+\stoptexdefinition
+
+\startbuffer[sample-1]
+ \parindent = 20pt
+ \leftskip = 40pt
+ \rightskip = 50pt
+ \hangindent = 0pt
+ \hangafter = 0
+\stopbuffer
+
+\startbuffer[sample-2]
+ \parindent = 0pt
+ \leftskip = 0pt
+ \rightskip = 0pt
+ \hangindent =-20pt
+ \hangafter = -3
+\stopbuffer
+
+\startbuffer[sample-3]
+ \parindent = 0pt
+ \leftskip = 0pt
+ \rightskip = 0pt
+ \hangindent = 20pt
+ \hangafter = 3
+\stopbuffer
+
+\startbuffer[sample-4]
+ \parindent = 0pt
+ \leftskip = 10pt
+ \rightskip = 30pt
+ \hangindent = 20pt
+ \hangafter = 3
+\stopbuffer
+
+In the next examples we show how the result of typesetting a paragraph looks
+like. We use the Sapolsky quote from the distribution. The cyan glue nodes are
+the left and right skip nodes, and the gray one at the end of the last line
+represents the parfill skip. The magenta ones at the edge are baseline skips. An
+indentation is shown in gray too. As experiment we have four normalization levels
+but in the end only the highest level makes sense, simply because normalization
+makes no sense unless one consistently normalizes all. We just keep the
+granularity because it makes it possible to explain what gets done.
+
+\texdefinition{Sample}{0}{sample-1}
+\texdefinition{Sample}{0}{sample-2}
+\texdefinition{Sample}{0}{sample-3}
+\texdefinition{Sample}{0}{sample-4}
+
+You might have noticed that the right skip is always there but the left skip is
+absent when it is zero. As said, as long as the result is okay, it does not
+really matter. But \unknown\ in \LUATEX\ (and therefore \CONTEXT) it can have
+consequences because there we can kick in a callback that does something with
+lines. Such a callback often has to deal with these specific glues and them being
+optional makes for more testing. The more predictable the order is, the better.
+Although we can easily normalize lines (in a callback) to always have a left skip
+too it is also an option in the engine.
+
+\texdefinition{Sample}{1}{sample-1}
+\texdefinition{Sample}{1}{sample-2}
+\texdefinition{Sample}{1}{sample-3}
+\texdefinition{Sample}{1}{sample-4}
+
+In the previous examples there are always left skips as well as right skips. It
+makes no sense to have an option to omit both zero left and right skips, because
+that again is unpredictable. But we can go further.
+
+\texdefinition{Sample}{2}{sample-1}
+\texdefinition{Sample}{2}{sample-2}
+\texdefinition{Sample}{2}{sample-3}
+\texdefinition{Sample}{2}{sample-4}
+
+In these examples the indentation has been turned into a glue as well (actually
+it is more a kern but using a glue makes more sense). The hanging indentation
+however is not seen here: it is not represented by glue but instead sort of
+hidden in the width of the box and a shift of its content.
+
+\texdefinition{Sample}{3}{sample-1}
+\texdefinition{Sample}{3}{sample-2}
+\texdefinition{Sample}{3}{sample-3}
+\texdefinition{Sample}{3}{sample-4}
+
+In the previous examples the hanging indentation is turned into left and right
+hang skips. These cannot be set at the \TEX\ end, but are injected when we
+instruct the normalizer to do so.
+
+\texdefinition{Sample}{4}{sample-1}
+\texdefinition{Sample}{4}{sample-2}
+\texdefinition{Sample}{4}{sample-3}
+\texdefinition{Sample}{4}{sample-4}
+
+The previous examples differ from the previous set in that they push these hang
+related glue nodes before the left and after the right skip. As I couldn't make
+up my mind yet, I let \LUAMETATEX\ just provide both variants.
+
+The option to keep hang related information explicitly in the line has some
+consequences. First of all, we now have glue and not some shift|/|width
+combination. Second, we have introduced an incompatibility: the lines now always
+have the proper width. You might have noticed that but we can show it more
+explicitly. We use two parameter sets
+
+\startbuffer[sample-5]
+ \hangindent = 20pt
+ \hangafter = 0
+\stopbuffer
+
+\startbuffer[sample-6]
+ \hangindent =-20pt
+ \hangafter = 0
+\stopbuffer
+
+\Sample{0}{sample-5}
+\Sample{4}{sample-5}
+
+\Sample{0}{sample-6}
+\Sample{4}{sample-6}
+
+A not yet mention part of the normalization is that, because they are no longer
+of relevance, the special local par nodes have been removed. The one that starts
+a paragraph is turned into a normal directional node if needed, so that we get
+properly balanced pairs of directional nodes. It must been said that the code
+that does all this is a bit of a mess. We want to stay close to the original
+code, but we also need to deal with all these extensions, like directions,
+protrusion, extra boxes, etc.
+
+Not shown here is that there is a fifth mode of operation. When we enable that
+level an overfull box will get a correction skip so that the right skip etc are
+properly aligned. How useful this is: we'll see.
+
+Now, when I decide to keep this feature, which can be set at the \LUA\ end to do
+the previously mentioned tasks, depending on a feature level ranging from zero to
+four, I also need to check the impact on existing \CONTEXT\ code, which
+(currently) is complicated by the fact that most is shared between \MKIV\ and
+\LMTX, and only \LUAMETATEX\ has this normalization feature. I will probably
+enable it for a while locally in order to see if there are side effects. Then,
+when the code base gets adapted, we have to assume that normalization happens, so
+there is no way back.
+
+\stopchapter
+
+\stopcomponent
+
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-pi.tex b/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-pi.tex
new file mode 100644
index 00000000000..197e8682699
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-pi.tex
@@ -0,0 +1,134 @@
+% language=us
+
+\environment evenmore-style
+
+% This appeared in TB 126, thanks to Karl Berry for fixing the English.
+
+\startcomponent evenmore-pi
+
+\startchapter[title=\TEX\ and Pi]
+
+This is a short status report \footnote {This chapter appeared in \TUGBOAT\ 40:3.
+Thanks to Karl Berry for corrections.} on Pi, not the famous version number of
+\TEX\ (among other things), but the small machine, meant for education but
+nowadays also used for Internet Of Things projects, process control and toy
+projects. While the majority of \TEX\ installations run on an Intel processor,
+the Raspberry Pi has an \ARM\ central processing unit. In fact, its main chip has
+the same foundation as those found in settop boxes all around the world. It's
+made for entertainment, not for number crunching.
+
+At the \CONTEXT\ meetings, it has become tradition to play with electronic
+gadgets. Every year we are curious what Harald K\"onig might bring this time. The
+last couple of meetings we also had talks about using \TEX\ and \METAPOST\ for
+designing (home|-|scale, automated) railroad systems, using \LUATEX\ for running
+domotica applications, using \METAPOST\ for rendering high quality graphics from
+data from appliances, presenting \TEX\ at computer and electronics bootcamps, and
+more. This year Frans Goddijn also brought back memories of low speed modem
+sounds, from the early days of \TEX\ support. It is these things that make the
+meetings fun.
+
+This year the meeting was in Belgium, close to the border of the Netherlands, and
+on the way there Mojca Miklavec traveled via my home, where the contextgarden
+compile farm runs on a server with plenty of cores, lots of memory and big disks.
+But the farm also has an old Mac connected as well as a tiny underpowered
+Raspberry Pi 2 for \ARM\ binaries that we had to fix: the small micro \SSD\ card
+in it had finally given up. This is no surprise if you realize that it does a
+daily compilation of the whole \TEX\ Live setup and also compiles \LUATEX,
+\LUAMETATEX\ and pplib when changes occur. Replacing the card worked out but
+nevertheless we decided to take the small machine with us to the meeting. We also
+took an external (2.5 inch) \SSD\ box with us. The idea was to order a Raspberry
+Pi~4 on location, the much praised successor of the older models, the one with
+4~\GB\ of memory, real \USB~3 ports and proper Ethernet.
+
+At the meeting Harald showed us that he had version~1, 3 and~4 machines with him
+because he was looking into an energy control setup based on Zigbee devices. So
+we had the full range of Pi's there to play with.
+
+This is a long introduction but the message is that we are dealing with a small
+but popular device with up to now four generations, using an architecture
+supported in \TEX\ distributions. So how does that relate to \CONTEXT ? One of
+the reasons for \LUAMETATEX\ going lean and mean is that computers are no longer
+getting much faster and \quote {multiple small} energy|-|wise has more appeal
+than \quote {one large}. So then the question is: how can we make \TEX\ run fast
+on small instead of gambling on big becoming even bigger (which does not seem to
+be happening anyway).
+
+At the meeting Harald gave a talk \quotation {Which Raspberry Pi is the best for
+\CONTEXT ?} and I will use his data to give an overview: see Table~\ref{rpispec}.
+
+\starttabulate[||c|c|c|c|]
+\BC model \BC 1 \BC 2 \BC 3 \BC 4 \NC \NR
+\BC chipset \NC BCM2835 \NC BCM2835 \NC BCM2835 \NC BCM2835 \NC \NR
+\BC CPU core \NC v6l rev 7 \NC v7l rev 5 \NC v7l rev 4 \NC v7l rev 3 \NC \NR
+\BC cores \NC 1 \NC 4 \NC 4 \NC 4 \NC \NR
+\BC free mem \NC 443080 \NC 948308 \NC 948304 \NC 3999784 \NC \NR
+\BC idlemips \NC 997.08 \NC 38.40 \NC 38.40 \NC 108.00 \NC \NR
+\BC bogomips \NC 997.08 \NC 57.60 \NC 76.80 \NC 270.00 \NC \NR
+\BC read SD \NC 23.0 MB/s \NC 23.2 MB/s \NC 23.2 MB/s \NC 45.1 MB/s \NC \NR
+\BC read USB \NC \NC 30.0 MB/s \NC 30.0 MB/s \NC 320.0 MB/s \NC \NR
+\stoptabulate
+
+After some discussion at the presentation we decided to discard the (absurd)
+bogomips value for the tiny Pi~1 computing board and not take the values for the
+others too seriously. But it will be clear that, especially when we consider the
+external drive that things have improved. The table doesn't mention Ethernet
+speed but because the~4 now has real support for it (instead of sharing the \USB\
+bus) we get close to 1~\GB/s there.
+
+The real performance test is of course processing a \TEX\ document and what
+better to test than the \TEX\ book. The processing time in seconds, after initial
+caching of files and fonts is:
+
+\starttabulate[||c|c|c|c|]
+\BC model \BC 1 \BC 2 \BC 3 \BC 4 \NC \NR
+\BC \TEX book \NC 13.649 \NC 7.023 \NC 4.553 \NC 1.694 \NC \NR
+\BC {\tt context --make} \NC \NC 19.949 \NC 11.796 \NC 6.034 \NC \NR
+\BC {\tt context --make} TL \NC 89.454 \NC 46.578 \NC 29.256 \NC 14.146 \NC \NR
+\stoptabulate
+
+The test of making the \CONTEXT\ format using \LUATEX\ gives an indication of how
+well the \IO\ performs: it loads the file database, some 460 \LUA\ modules and
+355 \TEX\ source files. On my laptop with Intel i7-3840QM with 16GB memory and
+decent \SSD\ it takes 3.5 seconds (and 1 second less for \LUAMETATEX\ because
+there we don't compress the format file). Somehow a regular \TEXLIVE\
+installation performs much worse than the one from the contextgarden.
+
+We didn't test real \CONTEXT\ documents at the meeting but when I came home the
+Pi~4 was bound again to the compile farm. Harald and Mojca had prepared the
+machine to boot from the internal micro \SSD\ and use the external disk for the
+rest. So, when we could compile \LUAMETATEX\ again, I made an \ARM\ installer for
+\LMTX, and after that could not resist doing a simple test. First of course came
+generating the format. It took 6.3 seconds to make one, which is a bit more than
+Harald measured. I see a hiccup at the end so I guess that it has to do with the
+(external) disk or maybe there is some throttling going on because the machine
+sits on top of a (warm) server.
+
+More interesting was testing a real document: the upcoming \LUAMETATEX\ manual.
+It has 226 pages, uses 21 font files, processes 225 \METAPOST\ graphics, and in
+order to get it \LUAMETATEX\ does more than 50\% of the work in \LUA, including
+all font and backend|-|related operations. On my laptop it needs 9.5~seconds and
+on the Pi~4 it uses 33~seconds. Of course, if I take a more modern machine than
+this 8|-|year|-|old workhorse, I probably need half the time, but still the
+performance of the Raspberry Pi~4 is quite impressive. It uses hardly any energy
+and can probably compete rather well with a virtual machine on a heavily loaded
+machine. It means that when we ever have to upgrade the server, I can consider
+replacement by an Ethernet switch, with power over Ethernet, connected to a bunch
+of small Raspberries, also because normally one would connect to some shared
+storage medium.
+
+Because I was curious how the dedicated small Fitlet that I use for controlling
+my lights and heating performs I also processed the manual there. After making
+the format, which takes 6~seconds, processing the manual took a little less than
+30~seconds. In that respect it performs the same as a Raspberry Pi~4. But, inside
+that small (way more expensive) computer is an dual core AMD A10 Micro-6700T APU
+(with AMD Radeon R6 Graphics), running a recent 64|-|bit Ubuntu. It does some
+2400 bogomips (compare that to the values of the Pi). I was a bit surprised that
+it didn't outperform the Raspberry because the (fast \SSD) disk is connected to
+the main board and it has more memory and horsepower. It might be that in the end
+an \ARM\ processor is simply better suited for the kind of byte juggling that
+\TEX\ does, where special \CPU\ features and multiple cores don't contribute
+much. It definitely demonstrates that we cannot neglect this platform.
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-style.tex b/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-style.tex
new file mode 100644
index 00000000000..07168e57c6a
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-style.tex
@@ -0,0 +1,67 @@
+% \enablelmtx
+% \nopdfcompression
+
+\startenvironment evenmore-style
+
+\usemodule[abbreviations-smallcaps]
+\usemodule[scite]
+
+\logo [LUAMETATEX] {LuaMeta\TeXsuffix}
+
+\setupbodyfont[plex,10pt] % not that ok for titling
+
+\setuplayout
+ [width=middle,
+ height=middle,
+ header=0pt,
+ footer=1cm,
+ footerdistance=5mm,
+ backspace=2cm,
+ cutspace=15mm,
+ topspace=2cm,
+ bottomspace=1cm,
+ style=bold,
+ color=maincolor]
+
+\setuppagenumbering
+ [alternative=doublesided]
+
+\setupwhitespace
+ [big]
+
+\setupfootertexts
+ [][{\getmarking[chapter]\quad\pagenumber}]
+ [{\pagenumber\quad\getmarking[chapter]}][]
+
+\definecolor
+ [maincolor]
+ [darkgray]
+
+\setuphead
+ [chapter]
+ [style=\bfc,
+ color=maincolor]
+
+\setuphead
+ [section]
+ [style=\bfa,
+ color=maincolor]
+
+\setuphead
+ [subsection]
+ [style=\bf,
+ color=maincolor]
+
+\setupalign
+ [tolerant,stretch]
+
+\setuptyping
+ [color=maincolor]
+
+\setuptype
+ [color=maincolor]
+
+\setupitemize
+ [color=maincolor]
+
+\stopenvironment
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-threesix.tex b/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-threesix.tex
new file mode 100644
index 00000000000..d75f9b68396
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-threesix.tex
@@ -0,0 +1,739 @@
+% language=us
+
+\environment evenmore-style
+
+\useMPlibrary[threesix]
+
+\startcomponent evenmore-threesix
+
+\startchapter[title={ThreeSix, Don Knuths first colorfont?}]
+
+In the process of reaching completion and perfection Don Knuth occasionally posts
+links to upcoming parts of the TAOCP series on his web pages. Now, I admit that
+much is way beyond me but I do understand (and like) the graphics and I know that
+Don uses \METAPOST. The next example code is just a proof of concept but might
+eventually become a decent module (with helpers) for making (runtime) fonts.
+After all, we need to adapt to current developments and \TEX ies always are
+willing to adapt and experiment. This chapter was written at the same time as
+the previous one on \TYPETHREE\ fonts so you might want to read that first.
+
+The font explored here is \type {FONT36}, used in \quotation {A potpourri of
+puzzles} and flagged as \quotation {a special font designed for dissection
+puzzles} (in fascicle 9b for Volume 4). Playing with and visualizing for me often
+works better than formulas, which then distracts me from the original purpose,
+but let's have a closer look anyway.
+
+\startlinecorrection
+ \scale[width=\textwidth]{\DEKFontA 1234567890} \vskip1ex
+ \scale[width=\textwidth]{\DEKFontA ABC{\red DE}FGHIJ{\red K}LM} \vskip1ex
+ \scale[width=\textwidth]{\DEKFontA NOPQRSTUVWXYZ}
+\stoplinecorrection
+
+The font has a fixed maximum height of 8~quantities. There is no depth in the
+characters. Some characters are wider. In this example we use a tight bounding
+box. In \CONTEXT\ speak this font is just a regular font but with a special
+feature enabled.
+
+\starttyping
+\definefontfeature
+ [fontthreesix]
+ [default]
+ [metapost=fontthreesix]
+
+\definefont[DEKFontA][Serif*fontthreesix]
+\stoptyping
+
+After this the \type {\DEKFontA} command will set this font as current font. The
+definition mentions \type {Serif} as font name. In \CONTEXT\ this name will
+resolve in the currently defined Serif, so when your document uses Latin Modern
+that will be the one. The \type {fontthreesix} will make this instance use that
+feature set, and the feature definition has the defaults as parent (so we get
+kerning, ligatures, etc.) but as extra feature also \type {metapost}. This means
+that the new glyphs that are about to be defined will actually be injected in the
+\type {Serif}! We will replace characters in that instance. So, the following:
+
+\startbuffer[taocp]
+This font is used in \quotation {The Art Of Computer Programming} by
+Don Knuth, not in volume~1, 2 or~3, but in number~4!
+\stopbuffer
+
+\typebuffer[taocp]
+
+comes out as:
+
+\startnarrower
+\DEKFontA \getbuffer[taocp]
+\stopnarrower
+
+But that doesn't look too good, so we will tweak the font a bit:
+
+\starttyping
+\definefontfeature
+ [fontthreesix-color]
+ [default]
+ [metapost={category=fontthreesix,spread=.1}]
+
+\definefont[DEKFontD][Serif*fontthreesix]
+\stoptyping
+
+The \type {spread} (multiplied by the font unit, which is 12 basepoints here)
+will add a bit more spacing around the blob:
+
+\startnarrower
+\DEKFontD \getbuffer[taocp]
+\stopnarrower
+
+Now, keep in mind that we're talking of a real font here. You can cut and paste
+these characters. It's just the default uppercase Latin alphabet plus digits.
+
+Before we go and look at some of the code needed to render this, a few more
+examples will be given.
+
+\startlinecorrection
+ \scale[width=\textwidth]{\DEKFontB 1234567890} \vskip4pt
+ \scale[width=\textwidth]{\DEKFontB ABCDEFGHIJKLM} \vskip4pt
+ \scale[width=\textwidth]{\DEKFontB NOPQRSTUVWXYZ}
+\stoplinecorrection
+
+In the above example we not only use color, but also a different shape and random
+colors (that is: random per \TEX\ job). The feature definition for this is:
+
+\starttyping
+\definefontfeature
+ [fontthreesix-color]
+ [default]
+ [metapost={%
+ category=fontthreesix,shape=diamond,%
+ color=random,pen=fancy,spread=.1%
+ }]
+\stoptyping
+
+Possible shapes are \type {circle}, \type {diamond} and \type {square} and
+instead of a random color one can give a known color name. Using transparency
+makes no sense in this font.
+
+A nice usage for this font are initials: % 4 for lm
+
+\startbuffer
+\setupinitial[font=Serif*fontthreesix-initial sa 5]
+{\DEKFontB \placeinitial \input zapf\par}
+\stopbuffer
+
+\typebuffer
+
+The initial feature is defined as:
+
+\starttyping
+\definefontfeature
+ [fontthreesix-initial]
+ [metapost={category=fontthreesix,color=random,shape=circle}]
+\stoptyping
+
+We use this in quoting Hermann Zapf, one that for sure is very applicable in
+a case like this:
+
+\startnarrower
+\getbuffer
+\stopnarrower
+
+Some combinations of sub|-|features are shown in \in {figure} [threesix:dek]. We
+blow up the diamond with fancy pen example in \in {figure} [threesix:tex]. Alas,
+the \TEX\ logo doesn't look that good in such a font. Using it for acronyms is
+not a good idea anyway, but maybe you can figure out \in {figure}
+[threesix:taocp].
+
+% todo penx peny penr
+
+\definefontfeature
+ [fontthreesix-circle]
+ [metapost={category=fontthreesix,shape=circle,color=random}]
+\definefontfeature
+ [fontthreesix-square]
+ [metapost={category=fontthreesix,shape=square,color=random}]
+\definefontfeature
+ [fontthreesix-diamond]
+ [metapost={category=fontthreesix,shape=diamond,color=random}]
+\definefontfeature
+ [fontthreesix-circle-pen]
+ [metapost={category=fontthreesix,shape=circle,color=random,pen=fancy}]
+\definefontfeature
+ [fontthreesix-square-pen]
+ [metapost={category=fontthreesix,shape=square,color=random,pen=fancy}]
+\definefontfeature
+ [fontthreesix-diamond-pen]
+ [metapost={category=fontthreesix,shape=diamond,color=random,pen=fancy}]
+\definefontfeature
+ [fontthreesix-circle-random]
+ [metapost={category=fontthreesix,random=yes,shape=circle,color=random}]
+\definefontfeature
+ [fontthreesix-square-random]
+ [metapost={category=fontthreesix,random=yes,shape=square,color=random}]
+\definefontfeature
+ [fontthreesix-diamond-random]
+ [metapost={category=fontthreesix,random=yes,shape=diamond,color=random}]
+
+\definefontfeature
+ [fontthreesix-circle-random-spread]
+ [metapost={category=fontthreesix,random=yes,shape=circle,color=random,spread=.1}]
+
+\startplacefigure[reference=threesix:dek]
+ \startcombination[3*3]
+ {\scale[width=.3\textwidth]{\definedfont [Serif*fontthreesix-circle]D\kern1pt E\kern 1ptK}} {\type{shape=circle}}
+ {\scale[width=.3\textwidth]{\definedfont [Serif*fontthreesix-square]D\kern1pt E\kern 1ptK}} {\type{shape=square}}
+ {\scale[width=.3\textwidth]{\definedfont [Serif*fontthreesix-diamond]D\kern1pt E\kern 1ptK}} {\type{shape=diamond}}
+ {\scale[width=.3\textwidth]{\definedfont [Serif*fontthreesix-circle-pen]D\kern1pt E\kern 1ptK}} {\type{shape=circle,pen=fancy}}
+ {\scale[width=.3\textwidth]{\definedfont [Serif*fontthreesix-square-pen]D\kern1pt E\kern 1ptK}} {\type{shape=square,pen=fancy}}
+ {\scale[width=.3\textwidth]{\definedfont [Serif*fontthreesix-diamond-pen]D\kern1pt E\kern 1ptK}} {\type{shape=diamond,pen=fancy}}
+ {\scale[width=.3\textwidth]{\definedfont [Serif*fontthreesix-circle-random]D\kern1pt E\kern 1ptK}} {\type{shape=circle,random=yes}}
+ {\scale[width=.3\textwidth]{\definedfont [Serif*fontthreesix-square-random]D\kern1pt E\kern 1ptK}} {\type{shape=square,random=yes}}
+ {\scale[width=.3\textwidth]{\definedfont[Serif*fontthreesix-diamond-random]D\kern1pt E\kern 1ptK}} {\type{shape=diamond,random=yes}}
+ \stopcombination
+\stopplacefigure
+
+\startplacefigure[reference=threesix:tex]
+\scale[width=\textwidth]{\definedfont[Serif*fontthreesix-diamond-pen]T\lower.5ex\hbox spread .1em{\hss E\hss}X}
+\stopplacefigure
+
+\startplacefigure[reference=threesix:taocp]
+\scale[width=\textwidth]{\definedfont[Serif*fontthreesix-circle-random-spread]TAOCP}
+\stopplacefigure
+
+You can quit reading now or expose yourself to how this is coded. We use a
+combination of \LUA\ and \METAPOST, but different solutions are possible. The
+shapes are entered (or course) with zeros and ones.
+
+\starttyping
+\startluacode
+local font36 = {
+ ["0"] = "00111100 01111110 11000011 11000011 11000011 ...",
+ ["1"] = "00011100 11111100 11101100 00001100 00001100 ...",
+ .....
+ ["D"] = "11111100 11100010 01100011 01100011 01100011 ...",
+ ["E"] = "1111111 1110001 0110101 0111100 0110100 0110001 ...",
+ .....
+ ["K"] = "11101110 11100100 01101000 01110000 01111000 ...",
+ .....
+}
+\stopluacode
+\stoptyping
+
+We also use \LUA\ to register this font. The actual code looks slightly different
+because it uses some helpers from the \CONTEXT\ \LUA\ libraries. We remap the
+bits pattern onto \METAPOST\ macro calls.
+
+\starttyping
+\startluacode
+local replace = {
+ ["0"] = "N;",
+ ["1"] = "Y;",
+ [" "] = "L;",
+}
+
+function MP.registerthreesix(name)
+ fonts.dropins.registerglyphs {
+ name = name,
+ units = 12,
+ usecolor = true,
+ }
+ for u, v in table.sortedhash(font36) do
+ local ny = 8
+ local nx = (#v - ny + 1) // ny
+ local height = ny * 1.1 - 0.1
+ local width = nx * 1.1 - 0.1
+ local code = string.gsub(v,".",replace)
+ fonts.dropins.registerglyph {
+ category = name,
+ unicode = utf.byte(u),
+ width = width,
+ height = height,
+ code = string.format("ThreeSix(%s);",code),
+ }
+ end
+end
+
+MP.registerthreesix("fontthreesix")
+\stopluacode
+\stoptyping
+
+So, after this the font \type {fontthreesix} is known to the system but we still
+need to provide \METAPOST\ code to generate it. The glyphs themselves are now
+just sequences of \type {N}, \type {Y} and \type {L} with some wrapper code
+around it. The definitions are put in the \type {MP} namespace simply because a
+first version initialized in \METAPOST, and there could create variants, but in
+the end I settled on the parameter interface at the \TEX\ end.
+
+The next definition looks a bit complex but normally such a macro is
+stepwise constructed. Notice how we can query the sub features. In order to make
+that possible the regular \METAFUN\ parameter handling code is used. We just push
+the sub|-|features into to \type {mpsfont} namespace.
+
+\starttyping
+\startMPcalculation{simplefun}
+
+def InitializeThreeSix =
+ save Y, N, L, S ; save dx, dy, nx, ny ; save currentpen ;
+ save shape, fillcolor, mypen, random, spread, hoffset ;
+ string shape, fillcolor, mypen ; boolean random ;
+ pen currentpen ;
+ dx := 11/10 ;
+ dy := - 11/10 ;
+ nx := - dx ;
+ ny := 0 ;
+ shape := getparameterdefault "mpsfont" "shape" "circle" ;
+ random := hasoption "mpsfont" "random" "true" ;
+ fillcolor := getparameterdefault "mpsfont" "color" "" ;
+ mypen := getparameterdefault "mpsfont" "pen" "" ;
+ spread := getparameterdefault "mpsfont" "spread" 0 ;
+ hoffset := 12 * spread / 2 ;
+ currentpen := pencircle
+ if mypen = "fancy" :
+ xscaled 1/20 yscaled 2/20 rotated 45
+ else :
+ scaled 1/20
+ fi ;
+ if shape == "square" :
+ def S =
+ unitsquare if random : randomized 1/10 fi
+ shifted (nx,ny)
+ enddef ;
+ elseif shape = "diamond" :
+ def S =
+ unitdiamond if random : randomized 1/10 fi
+ shifted (nx,ny)
+ enddef ;
+ else :
+ def S =
+ unitcircle if random : randomizedcontrols 1/20 fi
+ shifted (nx,ny)
+ enddef ;
+ fi ;
+ def N =
+ nx := nx + dx ;
+ draw S ;
+ enddef ;
+ if fillcolor = "random" :
+ def Y =
+ nx := nx + dx ;
+ fillup S withcolor white randomized (2/3,2/3,2/3) ;
+ enddef ;
+ elseif fillcolor = "" :
+ def Y =
+ nx := nx + dx ;
+ fillup S ;
+ enddef ;
+ else :
+ def Y =
+ nx := nx + dx ;
+ fillup S withcolor fillcolor ;
+ enddef ;
+ fi ;
+ def L =
+ nx := - dx ;
+ ny := ny + dy ;
+ enddef ;
+enddef ;
+
+vardef ThreeSix (text code) =
+ InitializeThreeSix ; % todo: once per instance run
+ draw image (code) shifted (hoffset,-ny) ;
+enddef ;
+
+\stopMPcalculation
+\stoptyping
+
+This code is not that efficient in the sense that there's quite some
+\METAPOST|-|\LUA|-|\METAPOST\ traffic going on, for instance each parameter check
+involves this, but in practice performance is quite okay, certainly for such a
+small font. There will be an initializer option some day soon. The \type
+{simplefun} is a reference to an \MPLIB\ instance that does load \METAFUN\ but
+only the modules that make no sense for this kind of usage. It also enforces
+double mode. The calculations wrapper just executes the code and does not place
+some (otherwise empty) graphic.
+
+% After playing with the font I see the beauty of the descriptions in the
+% pre|-|fascicle 9b but I still feel pretty stupid. Lucky for me there are
+% exercises like 999, tagged as \quote {for dummies}, so I'm not alone.
+
+Those who have seen (and|/|or read) \quotation {Concrete Mathematics} will have
+noticed the use of inline images, like dice. Dice are also used in \quotation
+{pre-fascicle 5a} (I need a few more lives to grasp that, so I stick to the
+images for now!). So, to compensate the somewhat complex code above, I will show
+how to accomplish that. This time we do all in \METAPOST:
+
+\startMPcalculation{simplefun}
+
+def DiceFrame =
+ pickup pencircle scaled 1/2 ;
+ draw unitsquare scaled 8 ;
+ pickup pencircle scaled 3/2 ;
+enddef ;
+
+vardef DiceOne =
+ DiceFrame ;
+ draw (4,4) ;
+enddef ;
+vardef DiceTwoA =
+ DiceFrame ;
+ draw (2,6) ; draw (6,2) ;
+enddef ;
+vardef DiceTwoB =
+ DiceFrame ;
+ draw (6,6) ; draw (2,2) ;
+enddef ;
+vardef DiceTwo =
+ if hasoption "mpsfont" "option" "reverse" :
+ DiceTwoB
+ else :
+ DiceTwoA
+ fi ;
+enddef ;
+vardef DiceThreeA =
+ DiceFrame ;
+ draw (2,6) ; draw (4,4) ; draw (6,2) ;
+enddef ;
+vardef DiceThreeB =
+ DiceFrame ;
+ draw (6,6) ; draw (4,4) ; draw (2,2) ;
+enddef ;
+vardef DiceThree =
+ if hasoption "mpsfont" "option" "reverse" :
+ DiceThreeB
+ else :
+ DiceThreeA
+ fi ;
+enddef ;
+vardef DiceFour =
+ DiceFrame ;
+ draw (2,6) ; draw (6,6) ; draw (2,2) ; draw (6,2) ;
+enddef ;
+vardef DiceFive =
+ DiceFrame ;
+ draw (2,6) ; draw (6,6) ; draw (4,4) ; draw (2,2) ; draw (6,2) ;
+enddef ;
+vardef DiceSix =
+ DiceFrame ;
+ draw (2,6) ; draw (6,6) ; draw (2,4) ; draw (6,4) ; draw (2,2) ; draw (6,2) ;
+enddef ;
+
+vardef DiceBad =
+ pickup pencircle scaled 1/2 ;
+ draw unitsquare scaled 8 ;
+ draw (1,7) -- (7,1) ; draw (1,1) -- (7,7) ;
+enddef ;
+
+lmt_registerglyphs [
+ name = "dice",
+ units = 12,
+ width = 8,
+ height = 8,
+ depth = 0,
+ usecolor = true,
+] ;
+
+lmt_registerglyph [ category = "dice", unicode = "0x2680", code = "DiceOne;" ] ;
+lmt_registerglyph [ category = "dice", unicode = "0x2681", code = "DiceTwo;" ] ;
+lmt_registerglyph [ category = "dice", unicode = "0x2682", code = "DiceThree;" ] ;
+lmt_registerglyph [ category = "dice", unicode = "0x2683", code = "DiceFour;" ] ;
+lmt_registerglyph [ category = "dice", unicode = "0x2684", code = "DiceFive;" ] ;
+lmt_registerglyph [ category = "dice", unicode = "0x2685", code = "DiceSix;" ] ;
+
+lmt_registerglyph [ category = "dice", private = "invaliddice", code = "DiceBad;" ] ;
+
+\stopMPcalculation
+
+This is not that hard to follow. We define some shapes first. These could have
+been assigned to the \type {code} parameter directly but this is nicer. Next we
+register the font itself and after that we set glyphs. We also set the official
+\UNICODE\ slots. So, copying a dice can either result in a digit or in a
+\UNICODE\ slot for a dice. In the example below we switch to a color which
+demonstrates that our dice can be colored at the \TEX\ end. It's either that or
+coloring at the \METAPOST\ end as both demand a different kind of \TYPETHREE\
+embedding trickery.
+
+We actually predefine three features. The digits one will map regular digit in
+the input to dice. We accomplish that via a font feature:
+
+\startbuffer
+\startluacode
+fonts.handlers.otf.addfeature("dice:digits", {
+ type = "substitution",
+ order = { "dice:digits" },
+ nocheck = true,
+ data = {
+ [0x30] = "invaliddice",
+ [0x31] = 0x2680,
+ [0x32] = 0x2681,
+ [0x33] = 0x2682,
+ [0x34] = 0x2683,
+ [0x35] = 0x2684,
+ [0x36] = 0x2685,
+ [0x37] = "invaliddice",
+ [0x38] = "invaliddice",
+ [0x39] = "invaliddice",
+ },
+} )
+\stopluacode
+\stopbuffer
+
+\typebuffer \getbuffer
+
+This kind of trickery is part of the font machinery used in \CONTEXT\ and permits
+runtime adaption of fonts, so we just use the same mechanism. The \type {nocheck}
+is needed to avoid this feature not kicking in due to lack of (at the time of
+checking) yet undefined dice.
+
+\startbuffer
+\definefontfeature
+ [dice:normal]
+ [default]
+ [metapost={category=dice}]
+\definefontfeature
+ [dice:reverse]
+ [default]
+ [metapost={category=dice,option=reverse}]
+\definefontfeature
+ [dice:digits]
+ [dice:digits=yes]
+
+\definefont[DiceN] [Serif*dice:normal]
+\definefont[DiceD] [Serif*dice:normal,dice:digits]
+\definefont[DiceR] [Serif*dice:reverse,dice:digits]
+
+{\DiceD Does 1 it 4 work? And {\darkgreen 3} too?} {\DiceR And how about
+{\darkred 3} then? But 8 should sort of fail!}
+\stopbuffer
+
+\typebuffer \getbuffer
+
+The six digits and \UNICODE\ characters come out the same:
+
+\startbuffer
+\red \DiceD \dostepwiserecurse {`1} {`6}{1}{\char#1\quad}%
+\blue \DiceN \dostepwiserecurse{"2680}{"2685}{1}{\char#1\quad}%
+\stopbuffer
+
+\typebuffer
+
+\startlinecorrection
+ \scale[width=\textwidth]{\getbuffer\unskip}
+\stoplinecorrection
+
+It is tempting to implement for instance~7 as two dice (a one to multi mapping in
+\OPENTYPE\ speak) but then one has to decide what combination is taken. One can
+also implement ligatures so that for instance 12 results in two six dice. But I
+think that's over the top and only showing \TEX\ muscles. It is anyway not that
+hard to do as we have an interface for that already.
+
+So why not do the dominos as well? Because there are so many dominos we predefine
+the shapes and then register the lot in a loop. We have horizontal and vertical
+variants. Being lazy I just made two helpers while one could have done but with
+some rotation and shifting of the horizontal one. The loop could be a macro but
+we don't save much code that way.
+
+\startbuffer
+\startMPcalculation{simplefun}
+
+picture Dominos[] ;
+
+Dominos[0] := image() ;
+Dominos[1] := image(draw(4,4);) ;
+Dominos[2] := image(draw(2,6);draw(6,2););
+Dominos[3] := image(draw(2,6);draw(4,4);draw(6,2););
+Dominos[4] := image(draw(2,6);draw(6,6);draw(2,2);draw(6,2););
+Dominos[5] := image(draw(2,6);draw(6,6);draw(4,4);draw(2,2);draw(6,2););
+Dominos[6] := image(draw(2,6);draw(4,6);draw(6,6);draw(2,2);draw(4,2);draw(6,2););
+
+lmt_registerglyphs [
+ name = "dominos",
+ units = 12,
+ width = 16,
+ height = 8,
+ depth = 0,
+ usecolor = true,
+] ;
+
+def DrawDominoH(expr a, b) =
+ draw image (
+ pickup pencircle scaled 1/2 ;
+ if (getparameterdefault "mpsfont" "color" "") = "black" :
+ fillup unitsquare xyscaled (16,8) ;
+ draw (8,.5) -- (8,7.5) withcolor white ;
+ pickup pencircle scaled 3/2 ;
+ draw Dominos[a]
+ withpen currentpen
+ withcolor white ;
+ draw Dominos[b] shifted (8,0)
+ withpen currentpen
+ withcolor white ;
+ else :
+ draw unitsquare xyscaled (16,8) ;
+ draw (8,0) -- (8,8) ;
+ pickup pencircle scaled 3/2 ;
+ draw Dominos[a]
+ withpen currentpen ;
+ draw Dominos[b] shifted (8,0)
+ withpen currentpen ;
+ fi ;
+ ) ;
+enddef ;
+
+def DrawDominoV(expr a, b) = % is H rotated and shifted
+ draw image (
+ pickup pencircle scaled 1/2 ;
+ if (getparameterdefault "mpsfont" "color" "") = "black" :
+ fillup unitsquare xyscaled (8,16) ;
+ draw (.5,8) -- (7.5,8) withcolor white ;
+ pickup pencircle scaled 3/2 ;
+ draw Dominos[a] rotatedaround(center Dominos[a],90)
+ withpen currentpen
+ withcolor white ;
+ draw Dominos[b] rotatedaround(center Dominos[b],90) shifted (0,8)
+ withpen currentpen
+ withcolor white ;
+ else :
+ draw unitsquare xyscaled (8,16) ;
+ draw (0,8) -- (8,8) ;
+ pickup pencircle scaled 3/2 ;
+ draw Dominos[a] rotatedaround(center Dominos[a],90)
+ withpen currentpen ;
+ draw Dominos[b] rotatedaround(center Dominos[b],90) shifted (0,8)
+ withpen currentpen ;
+ fi ;
+ ) ;
+enddef ;
+
+begingroup
+ save unicode ; numeric unicode ; unicode := 127025 ; % 1F031
+
+ for i=0 upto 6 :
+ for j=0 upto 6 :
+ lmt_registerglyph [
+ category = "dominos",
+ unicode = unicode,
+ code = "DrawDominoH(" & decimal i & "," & decimal j & ");",
+ width = 16,
+ height = 8,
+ ] ;
+ unicode := unicode + 1 ;
+ endfor ;
+ endfor ;
+
+ save unicode ; numeric unicode ; unicode := 127075 ;
+
+ for i=0 upto 6 :
+ for j=0 upto 6 :
+ lmt_registerglyph [
+ category = "dominos",
+ unicode = unicode,
+ code = "DrawDominoV(" & decimal i & "," & decimal j & ");",
+ width = 8,
+ height = 16,
+ ] ;
+ unicode := unicode + 1 ;
+ endfor ;
+ endfor ;
+endgroup ;
+
+\stopMPcalculation
+\stopbuffer
+
+\typebuffer \getbuffer
+
+Again we predefine a couple of features:
+
+\startbuffer
+\definefontfeature
+ [dominos:white]
+ [default]
+ [metapost={category=dominos}]
+
+\definefontfeature
+ [dominos:black]
+ [default]
+ [metapost={category=dominos,color=black}]
+
+\definefontfeature
+ [dominos:digits]
+ [dominos:digits=yes]
+\stopbuffer
+
+\typebuffer \getbuffer
+
+This last feature is yet to be defined. We could deal with the invalid dominos
+with some substitution trickery but let's keep it simple.
+
+\startbuffer
+\startluacode
+local ligatures = { }
+local unicode = 127025
+
+for i=0x30,0x36 do
+ for j=0x30,0x36 do
+ ligatures[unicode] = { i, j }
+ unicode = unicode + 1 ;
+ end
+end
+
+fonts.handlers.otf.addfeature("dominos:digits", {
+ type = "ligature",
+ order = { "dominos:digits" },
+ nocheck = true,
+ data = ligatures,
+} )
+\stopluacode
+\stopbuffer
+
+\typebuffer \getbuffer
+
+That leaves showing an example. We define a few fonts and again we just extend
+the Serif:
+
+\startbuffer
+\definefont[DominoW][Serif*dominos:white]
+\definefont[DominoB][Serif*dominos:black]
+\definefont[DominoD][Serif*dominos:white,dominos:digits]
+\stopbuffer
+
+\typebuffer \getbuffer
+
+The example is:
+
+\startbuffer
+\DominoW
+ \char"1F043\quad 🀱\quad
+ \char"1F052\quad 🀲\quad
+ \char"1F038\quad 🀳\quad
+ \darkgreen\char"1F049\quad \char"1F07B\quad
+\DominoB
+ \char"1F087\quad
+ \char"1F088\quad
+ \char"1F089\quad
+\DominoD
+ \darkred 12\quad56\quad64
+\stopbuffer
+
+\typebuffer
+
+Watch the ligatures in action:
+
+\startlinecorrection
+ \scale[width=\textwidth]{\getbuffer\unskip}
+\stoplinecorrection
+
+To what extent the usage of symbols like dice and dominos as characters in the
+mentioned book are responsible for them being in \UNICODE, I don't know. Now with
+all these emoji showing up one can wonder about graphics in such a standard
+anyway. But for sure, even after more than three decades, Don still makes nice
+fonts.
+
+A treasure of tiny graphics can be found in \quotation {pre-fascicle 5c} and many
+are in color! In fact, it has dominos too. It must have been a lot of fun writing
+this! I'm thinking of turning the pentominoes into a font where a \type {GPOS}
+feature can deal with the inter|-|pentomino kerning (which mighty work out okay
+for example~36. The windmill dominos also make a nice example for a font where
+ligatures will boil down to the base form and the (one or more) blades are laid
+over. It's definitely an inspiring read.
+
+\stopchapter
+
+\stoptext
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-titlepage.tex b/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-titlepage.tex
new file mode 100644
index 00000000000..57418800c4a
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-titlepage.tex
@@ -0,0 +1,45 @@
+\startcomponent evenmore-titlepage
+
+\environment evenmore-style
+
+% \usetypescriptfile[latinmodern]
+% \usetypescript[mono][latin-modern]
+% \definefont[MyFontA][LMTypewriter-Dark*none]
+% \definefont[MyFontB][LMTypewriterVarWd-Regular*default]
+
+\definefont[MyFontA][MonoBold*none]
+\definefont[MyFontB][Serif*default]
+
+\startMPpage[pagestate=stop]
+
+StartPage ;
+
+ fill Page withcolor .1 ;
+
+ numeric d ; d := PaperWidth/4 ;
+
+ numeric w ; w := d ;
+ numeric h ; h := 2d ;
+
+ draw textext.rt ("\MyFontA E") xsized d shifted (0w,PaperHeight- 36mm) withcolor "darkred" ;
+ draw textext.rt ("\MyFontA V") xsized d shifted (1w,PaperHeight- 36mm) withcolor "darkgreen" ;
+ draw textext.rt ("\MyFontA E") xsized d shifted (2w,PaperHeight- 36mm) withcolor "darkblue" ;
+ draw textext.rt ("\MyFontA N") xsized d shifted (3w,PaperHeight- 36mm) withcolor "darkorange" ;
+ draw textext.rt ("\MyFontA M") xsized d shifted (0w,PaperHeight-104mm) withcolor "darkcyan" ;
+ draw textext.rt ("\MyFontA O") xsized d shifted (1w,PaperHeight-104mm) withcolor "darkmagenta" ;
+ draw textext.rt ("\MyFontA R") xsized d shifted (2w,PaperHeight-104mm) withcolor "darkyellow" ;
+ draw textext.rt ("\MyFontA E") xsized d shifted (3w,PaperHeight-104mm) withcolor "darkgray" ;
+
+% draw textext.lft ("\MyFontB\setstrut\strut fun with") ysized 30mm shifted lrcorner Page shifted (-1cm,8cm) withcolor "white" ;
+% draw textext.lft ("\MyFontB\setstrut\strut luametatex") ysized 30mm shifted lrcorner Page shifted (-1cm,5cm) withcolor "white" ;
+% draw textext.lft ("\MyFontB\setstrut\strut and context") ysized 30mm shifted lrcorner Page shifted (-1cm,2cm) withcolor "white" ;
+
+ draw textext.lft ("\MyFontB\setstrut\strut fun with") ysized 27mm shifted lrcorner Page shifted (-10mm,70mm) withcolor "white" ;
+ draw textext.lft ("\MyFontB\setstrut\strut luametatex") ysized 27mm shifted lrcorner Page shifted (-10mm,45mm) withcolor "white" ;
+ draw textext.lft ("\MyFontB\setstrut\strut and context") ysized 27mm shifted lrcorner Page shifted (-10mm,20mm) withcolor "white" ;
+
+StopPage ;
+
+\stopMPpage
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-whattex.tex b/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-whattex.tex
new file mode 100644
index 00000000000..10d3e49f2f7
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore-whattex.tex
@@ -0,0 +1,155 @@
+% language=us
+
+\startcomponent evenmore-whattex
+
+\environment evenmore-style
+
+\startchapter[title={Is \LUAMETATEX\ still \TEX ?}]
+
+\startsection[title={Introduction}]
+
+Is \LUAMETATEX\ really a \TEX\ (compatible) engine? The answer to that depends on
+how you define \TEX. If you think of the program with the same name, the answer
+is definitely \quotation {no}, simply because a program that is not exactly
+behaving like \quotation {\TEX\ The Program} cannot be called \TEX. This is why
+derived programs have \type {tex} in their name but also some addition that
+indicates that it isn't the original: \type {e}, \type {pdf}, \type {lua}. Don't
+confuse that with macro package names that have \type {tex} in their name. If you
+find such binaries that they are likely some stub to an engine (binary) that
+preloads a format file (a memory dump) with the same name.
+
+When you mean \quotation {\TEX\ The Macro Language} the answer is a bit more
+nuanced especially when the results are pretty close to identical. In the next
+sections I will discuss this in more detail from the perspective of how \CONTEXT\
+evolved and what engines it has used.
+
+\stopsection
+
+\startsection[title={Multiple engines}]
+
+When we started with \CONTEXT\ there was not that much choice in engines.
+Basically one just used original \TEX, but although we used the version that came
+with the book, pretty soon we switched to em\TEX, a version that gave more
+memory; later a real huge version showed up. The fonts used were bitmaps and the
+viewer was a \DVI\ bitmap viewer. However, when our new printer could not be set
+up properly we decided to move on to \POSTSCRIPT\ fonts. That also meant using a
+different backend driver (\DVIPSONE). And then of course we also started using a
+previewer that could handle outline fonts. Once you start along that route
+graphics come into play, color shows up and hyperlinks become an option. A couple
+of years later the \PDF\ document rendering format was introduced. This paragraph
+already mentions a lot of different programs and adaptations, but we're still
+talking good old \TEX\ here and \CONTEXT\ was set up in such a way that it
+adapted itself to whatever ecosystem made sense. When looking at \TEX\ one has to
+consider the front as well as the backend, and both have related primitives and
+features. Extensions to the frontend have been driven by the demands of macro
+packages (beyond the original ideas) and those of the backend relate to what the
+evolving rendering demands impose.
+
+A couple of decades ago the \ETEX\ project started. It's objective was to extend
+stable \TEX\ with a couple of more primitives and features: it is a superset and
+therefore still \TEX, but as it really is an extension the name was extended too
+(with the bit unusual character $\varepsilon$). At that point the main reason for
+\CONTEXT\ was convenience because the new features were already kind of present
+in the code base (think of emulated behavior). Again the macro package adapted
+itself at runtime.
+
+Then \PDFTEX\ came around which had some impact. It introduced the concept of a
+built|-|in backend that avoided additional programs. The \ETEX\ extensions were
+merged into this program so that basically meant that it replaced its
+predecessors. For a user \PDFTEX\ was just \TEX. For some reason the narrative
+became that \CONTEXT\ depended on \PDFTEX, probably because it was always quick
+in using its features, a side effect of being close to the development.
+
+The \CONTEXT\ package was an early adopter of \METAPOST\ and that graphic
+subsystem, although still external, was integrated in such a way that users could
+think of it being embedded. This was made possible by the fact that right from
+the start \CONTEXT\ came with an infrastructure that handled processing including
+subruns as needed for \METAPOST. This is why, years later, adding a \METAPOST\
+library to \LUATEX\ was a logical step. As \CONTEXT\ came with a lot of scripts
+(for all kind of tasks related to typesetting and managing a \TEX\ ecosystem)
+adding a scripting language (like \LUA) was not that strange either.
+
+In parallel to \PDFTEX\ the experimental \OMEGA\ program was on its way and
+although at some point a stable \ALEPH\ variant was there, it never was robust
+enough for production. Its main contribution (that survived) was the introduction
+if directional typesetting. There were \CONTEXT\ users using it but for very
+specific applications. It's also why the bidirectional model of \OMEGA\ inspired
+\LUATEX\ more than the simpler model that \ETEX\ used.
+
+\stopsection
+
+\startsection[title={The merge}]
+
+We now move forward to \LUATEX\ and more precisely \LUAMETATEX\ because that is
+for \CONTEXT\ the engine of choice now. To what extend is it \TEX\ or not? The
+naive answer is \quotation {no} because some primitives are not present and|/|or
+are implemented using \LUA. However, these primitives fall into categories. Some
+relate to the backend and in \LUAMETATEX\ the backend is not built|-|in and as a
+consequence a macro package has to provide the primitives as part of its
+implementation of a backend. This is no big deal because the backend related
+primitives in \TEX\ The Program are actually examples of extensions and
+implemented as such. Handling them happens in kind of isolated code. Take \type
+{\special}: it is basically a no|-|op when the \DVI\ driver doesn't interpret
+what is passed to the \DVI\ file. \footnote {\CONTEXT\ \MKII\ has a bunch of
+backend drivers, \TEX\ code, that targets specific postprocessors and they hook
+into primitives like \type {\special} or the additional \type {\pdf...} ones in
+\PDFTEX.} \footnote {We need to keep in mind that by the time \PDFTEX\ and later
+\LUATEX\ were developed memory constraints were lifted so these engines didn't
+have to work around the limitations that for instance \ETEX\ and \OMEGA\ had to
+cope with.}
+
+A more drastic change is the lack of font loaders and that no fonts can be stored
+in the format. Again this relates to the simple fact that todays fonts are more
+demanding so we need to extend the machinery and as we do that via \LUA\
+extensions we can as well do all that way. Less drastic, but it could have side
+effects, is that the machinery has to be able to deal with \OPENTYPE\ math. And
+of course all is \UNICODE\ aware so additional primitives cope with that. But in
+principle the old stuff should still work. Hyphenation is also expanded: patterns
+are loaded runtime and the hyphenation, ligature building and kerning stages are
+split, which actually it a good thing.
+
+The \LUAMETATEX\ code base is a follow up on \LUATEX, that combines good old
+\TEX\ (but adapted with respect to fonts, languages and math as mentioned), parts
+of \ETEX\ (so it provides more primitives), bits of \PDFTEX\ (like protrusion and
+expansion, although adapted), and rudiments of \OMEGA\ (\ALEPH). And of course
+there's a lot of new stuff too, primitives as well as ways to plug in \LUA\ code
+plus some helpers at the \LUA\ end.
+
+As an example of progression, by now the \ETEX\ extensions that we kept are
+integrated more naturally in existing subsystems. A nice detail is that there are
+no longer any version numbers that relate to \ETEX; for a while they were kept
+but suddenly I realized that it makes no sense to waste (four) command codes on
+something that is of not much use: there has never been a real \ETEX\ follow up
+after its stable release so testing for a version makes no sense. No backend
+means no \PDFTEX\ version info too and \OMEGA\ version numbers serve no purpose
+either. If a macro package needs to know what functionality is there, testing for
+the \LUATEX\ version number, revision and maybe functionality level makes enough
+sense. By the way, one reason for a clean up related to \ETEX\ was that where
+\ETEX\ uses change files to replace or extend good old \TEX\ code, \LUATEX\ has
+one integrated code base.
+
+\stopsection
+
+\startsection[title={The verdict}]
+
+So in the end the answer is that \LUAMETATEX\ is mostly \TEX\ but that due to
+developments like for instance \UNICODE, \OPENTYPE\ fonts and math, as well as
+the wish to use images, color, runtime graphics, directionality, features beyond
+what the engine has built, etc.\ in the end it hopefully meets the demands to
+today. In its core the same code is still there although extensions and hooks got
+mixed in more naturally. When in documents (or talks) I speak of \TEX\ I
+basically refer to a concept (materialized in the set of core primitives and
+related functionality) but once extensions come into play I try to talk of
+\LUATEX\ or \LUAMETATEX. This happens kind of automatic because I know what got
+added but I can imagine that users who entered the game later don't always see
+what was added (and when).
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
+
+% Written on the day I heard Neal Peart had passed away so mixed with watching
+% Rush dvd's which made me realize that times flies. They day before I was at a
+% Jan Akkerman show ... timeless quality too.
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore.tex b/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore.tex
new file mode 100644
index 00000000000..293753a797c
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/evenmore.tex
@@ -0,0 +1,25 @@
+\environment evenmore-style
+
+\dontcomplain
+
+\startdocument
+
+ \component evenmore-titlepage
+
+ \startfrontmatter
+ \component evenmore-contents
+ \stopfrontmatter
+
+ \startbodymatter
+ \component evenmore-introduction
+ \component evenmore-pi
+ \component evenmore-fonts
+ \component evenmore-threesix
+ \component evenmore-normalization
+ \component evenmore-expansion
+ \component evenmore-macros
+ \component evenmore-libraries
+ \component evenmore-whattex
+ \stopbodymatter
+
+\stopdocument
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/mozilla-svg-001.svg b/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/mozilla-svg-001.svg
new file mode 100644
index 00000000000..5e46d846759
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/evenmore/mozilla-svg-001.svg
@@ -0,0 +1,72 @@
+<svg xmlns="http://www.w3.org/2000/svg">
+ <path fill="#d87512" d="M17.786 44.63c-.606.115-1.23.173-1.854.173-2.444 0-4.644-.864-6.04-2.375-.855-.92-1.394-2.147-1.517-3.47-.126-1.243.067-2.638.58-4.163.325-1.016.83-2.01 1.365-3.064.216-.426.437-.858.65-1.302.702-1.454 1.504-3.164 2.11-5.05.715-2.188.943-4.287.682-6.23-.267-2.102-.994-3.972-1.74-5.685a2.992 2.992 0 0 0-4.15-1.446c-.71.375-1.23 1-1.467 1.77a2.983 2.983 0 0 0 .218 2.292c.632 1.19 1.314 2.596 1.592 3.977.238 1.137.18 2.41-.184 3.897-.37 1.538-.976 3.143-1.522 4.518-.16.406-.33.816-.507 1.234-.507 1.215-1.032 2.47-1.364 3.838-.55 2.14-.666 4.152-.348 5.97.36 2.163 1.41 4.14 2.955 5.567 2.027 1.88 4.808 2.914 7.826 2.914 1.14 0 2.274-.146 3.375-.437l-.66-2.923"/>
+ <g fill="#bc600d">
+ <path d="M11.585 43.742s.387 1.248.104 3.05c0 0 2.045-.466 1.898-2.27 0 0-.815-.29-2-.78M9.19 41.484S8.98 42.94 7.93 44.43c0 0 2.103.42 2.774-1.265 0 0-.696-.66-1.515-1.68M8.398 37.21s-.926 1.432-3.23 2.322c0 0 1.514 2.303 3.53.904 0 0-.237-1.388-.3-3.226M12.964 15.833s-1.685.798-3.783 3.45c0 0 2.1 1.55 4.663 2.228 0 0 .285-3.093-.88-5.677M13.5 23.873s-2.988.544-5.57 2.794c0 0 1.615 1.708 3.583 2.62 0 0 1.678-3.39 1.987-5.414M10.32 31.73s-1.483 0-4.483.812c0 0-.01 2.873 2.94 2.823 0 0 .747-1.75 1.544-3.635"/>
+ </g>
+ <g fill="#d87512">
+ <path d="M53.33 39.37c0-4.484-35.622-4.484-35.622 0 0 10.16.05 10.25 17.81 10.25 17.762 0 17.812-.09 17.812-10.25"/>
+ <path d="M42.645 56.04c1.688 2.02 9.275.043 10.504-2.28 5.01-9.482-.006-13.58-.006-13.58l-10.5 1.313s-2.154 11.977 0 14.547"/>
+ </g>
+ <g fill="#bc600d">
+ <path d="M54.2 41.496s-.336 4.246-4.657 9.573c0 0 4.38-1.7 5.808-4.3 0 0 .448-3.02-1.15-5.274M55.08 48.69s-1.065 1.88-3.563 3.872c0 0 1.78-.03 2.576-.785 0 0 .77-1.41.987-3.086"/>
+ </g>
+ <path fill="#f29a2e" d="M35.484 60.38c1.87 2.23 8.547 2.09 10.574 0 2.904-2.995 2.78-16.656 2.904-23.314l-12.418-1.053s-3.444 21.52-1.06 24.367"/>
+ <g fill="#bc600d">
+ <path d="M48.21 53.53s-3.578-3.443-8.738-.013c0 0 5.754 2.455 7.365 5.672 0 0 1.126-2.245 1.373-5.66M48.775 46.06s-3.852-3.09-7.938 1.43c0 0 4.452-.47 7.632 3.635 0 0 .493-3.05.305-5.065"/>
+ </g>
+ <g fill="#3e4347">
+ <path d="M43.847 61.57l-.397-2.765 1.344 2.445zM40.41 61.996l.502-3.294.498 3.294zM36.713 61.3l1.317-2.26-.372 2.59z"/>
+ </g>
+ <path fill="#d87512" d="M28.388 56.04c-1.688 2.02-9.277.043-10.504-2.28-5.01-9.482.004-13.58.004-13.58l10.5 1.313s2.154 11.977 0 14.547"/>
+ <g fill="#bc600d">
+ <path d="M16.833 41.496s.336 4.246 4.657 9.573c0 0-4.38-1.7-5.807-4.3 0 0-.448-3.02 1.15-5.274M15.957 48.69s1.066 1.88 3.563 3.872c0 0-1.782-.03-2.576-.785 0 0-.772-1.41-.987-3.086"/>
+ </g>
+ <path fill="#f29a2e" d="M35.548 60.38c-1.87 2.23-8.548 2.09-10.575 0-2.904-2.995-2.78-16.656-2.904-23.314l12.417-1.053s3.446 21.52 1.06 24.367"/>
+ <g fill="#bc600d">
+ <path d="M22.822 53.53s3.58-3.443 8.74-.013c0 0-5.754 2.455-7.367 5.672 0 0-1.125-2.245-1.373-5.66M22.255 46.06s3.852-3.09 7.94 1.43c0 0-4.453-.47-7.633 3.635 0 0-.493-3.05-.307-5.065"/>
+ </g>
+ <g fill="#3e4347">
+ <path d="M26.24 61.25l1.345-2.445-.395 2.765zM29.62 61.996l.5-3.294.5 3.294zM33.375 61.63L33 59.04l1.32 2.26zM35.516 60.46c-.395-2.48-.482-4.96-.5-7.438.015-2.48.104-4.96.5-7.44.396 2.48.485 4.96.5 7.44-.018 2.48-.106 4.96-.5 7.438"/>
+ </g>
+ <path fill="#f29a2e" d="M27.777 6.994c0 3.82-2.727 6.987-6.086 6.915C11.83 13.7 15.893 2 15.893 2c3.36 0 11.885 1.176 11.885 4.994"/>
+ <path fill="#af5a31" d="M24.05 7.752c0 2.037-1.454 3.727-3.248 3.688-5.26-.11-3.093-6.353-3.093-6.353 1.792 0 6.34.628 6.34 2.665"/>
+ <path fill="#f29a2e" d="M43.26 6.994c0 3.82 2.726 6.987 6.086 6.915 9.86-.21 5.8-11.91 5.8-11.91C51.782 2 43.26 3.176 43.26 6.994"/>
+ <path fill="#af5a31" d="M46.983 7.752c0 2.037 1.455 3.727 3.247 3.688 5.26-.11 3.094-6.353 3.094-6.353-1.794 0-6.34.628-6.34 2.665"/>
+ <path fill="#f29a2e" d="M55.806 33.378c0 7.155-9.517 8.13-20.288 8.13-10.776 0-20.29-.975-20.29-8.13 0-29.96 11.596-29.14 20.29-29.14 8.69 0 20.288-.82 20.288 29.14"/>
+ <g fill="#3e4347">
+ <path d="M35.54 7.59c3.24 0 6.15 1.084 8.156 2.81-.77-2.945-4.135-5.16-8.173-5.16-4.06 0-7.442 2.238-8.186 5.204 2.01-1.753 4.938-2.855 8.204-2.855"/>
+ <path d="M35.535 11.193c2.217 0 4.21.744 5.584 1.925-.528-2.02-2.835-3.534-5.6-3.534-2.78 0-5.095 1.533-5.605 3.564 1.376-1.198 3.383-1.955 5.62-1.955"/>
+ </g>
+ <path fill="#ffe8bb" d="M29.553 43.727l-18.408-7.01 4.24-9.06s2.704 3.85 13.29 6.82l.878 9.243"/>
+ <path fill="#3e4347" d="M29.37 39.77c-7.462-1.27-16.325-6.673-16.48-6.75l.992-2.168c.184.092 8.806 5.342 15.853 6.544l-.366 2.374"/>
+ <path fill="#ffe8bb" d="M41.48 43.727l18.406-7.01-4.24-9.06s-2.704 3.85-13.29 6.82l-.876 9.243"/>
+ <path fill="#3e4347" d="M41.663 39.77c7.46-1.27 16.325-6.673 16.48-6.75l-.993-2.168c-.184.092-8.808 5.342-15.852 6.544l.365 2.374"/>
+ <g fill="#ffe8bb">
+ <path d="M43.524 45.57C38.752 42.023 41.4 33.86 41.4 33.86c-5.657 5.906-12.662 8.74-12.662 8.74 1.608 5.446 5.77 6.412 5.77 6.412-.34-1.835.663-3.302.663-3.302 1.68 2.22 5.03 2.986 5.03 2.986-1.287-1.508-.948-3.835-.948-3.835 2.326.875 4.27.71 4.27.71"/>
+ <path d="M42.29 42.97c-2.634 2.247-10.917 2.247-13.553 0-2.856-2.435-2.495-7.144.1-9.884 2.397-2.527 10.958-2.527 13.355 0 2.595 2.74 2.956 7.45.098 9.883"/>
+ </g>
+ <g fill="#3e4347">
+ <path d="M36.18 40.48a.69.69 0 0 1-.644-.477c-.227-.67-.77-3.293-.71-5.498.01-.398.325-.71.7-.698.38.01.674.343.663.74-.057 2.01.46 4.466.633 4.974.127.375-.06.786-.414.92a.607.607 0 0 1-.23.04"/>
+ <path d="M30.504 43.25c.21-.202.394-.408.582-.61.188-.204.378-.405.57-.604.385-.396.782-.78 1.2-1.145a14.125 14.125 0 0 1 2.745-1.9c.504-.263 1.032-.49 1.59-.654s1.153-.273 1.772-.253c.31.01.623.055.928.146.307.088.602.23.86.416.263.19.485.422.652.684.17.257.287.54.35.83a4.247 4.247 0 0 0-.677-.448 2.567 2.567 0 0 0-.68-.237c-.447-.088-.887-.04-1.33.06-.89.216-1.786.65-2.69 1.114-.905.466-1.818.983-2.776 1.466-.48.24-.97.473-1.48.682-.256.103-.517.202-.783.285-.27.078-.546.155-.833.167"/>
+ </g>
+ <path fill="#f15a61" d="M41.34 31.743c-1.17-.528-4.757-.57-5.83-.57-1.07 0-4.66.042-5.83.57-.832.376-.187 1.31 2.027 2.116 1.397.506 2.733.666 3.803.666 1.07 0 2.405-.16 3.805-.667 2.213-.808 2.856-1.74 2.025-2.117"/>
+ <g fill="#3e4347">
+ <path d="M29.917 23.48l1.61 5.292L26.954 26z"/>
+ <path d="M22.645 31.828c-.522 0-.932-.056-1.17-.098-2.986-.52-4.632-1.996-6.09-4.067l.185-2.472c1.52 1.446 3.953 3.76 6.28 4.167 1.156.2 2.853-.016 4.15-1.234 1.537-1.44 2.263-4.05 2.1-7.547l1.635.132c.2 4.312-.116 7.244-2.212 9.212-1.692 1.59-3.613 1.908-4.878 1.908M41.12 23.48l-1.613 5.292L44.08 26z"/>
+ <path d="M48.39 31.828c.52 0 .93-.056 1.167-.098 2.99-.52 4.637-1.996 6.09-4.067l-.182-2.472c-1.52 1.446-3.955 3.76-6.28 4.167-1.156.2-2.855-.016-4.154-1.234-1.532-1.44-2.258-4.05-2.095-7.547l-1.636.132c-.202 4.312.114 7.244 2.213 9.212 1.69 1.59 3.61 1.908 4.877 1.908"/>
+ </g>
+ <path fill="#ffe8bb" d="M30.25 22.09c-.852 5.282-3.728 5.87-6.696 5.577-2.986-.294-5.396-2.667-5.396-6.743 0-4.28 0-4.28 6.647-5.752 6.728-1.49 6 3.437 5.445 6.918"/>
+ <path fill="#3e4347" d="M29.16 22.547c-.244 2.534-2.61 4.357-5.287 4.072-2.674-.286-4.645-2.57-4.402-5.102s.28-2.75 5.108-2.237c4.83.514 4.824.737 4.582 3.267"/>
+ <path fill="#fff" d="M27.59 21.884c-.16 1.688-1.74 2.903-3.522 2.714-1.785-.19-3.096-1.712-2.936-3.4.163-1.69.186-1.835 3.406-1.493 3.22.344 3.215.49 3.053 2.18"/>
+ <g fill="#3e4347">
+ <ellipse cx="25.5" cy="21.08" rx="1.45" ry="1.647"/>
+ <path d="M31.27 17.896c.42 0 .807-.284.936-.728.16-.546-.133-1.122-.65-1.29l-5.98-1.924c-.516-.166-1.065.14-1.225.685-.155.543.136 1.12.652 1.287l5.98 1.924a.95.95 0 0 0 .288.046"/>
+ </g>
+ <path fill="#ffe8bb" d="M40.78 22.09c.855 5.282 3.73 5.87 6.7 5.577 2.984-.294 5.395-2.667 5.395-6.743 0-4.28-.002-4.28-6.646-5.752-6.73-1.49-6.01 3.437-5.45 6.918"/>
+ <path fill="#3e4347" d="M41.873 22.547c.243 2.534 2.61 4.357 5.287 4.072 2.674-.286 4.646-2.57 4.402-5.102-.242-2.533-.28-2.75-5.107-2.237-4.83.514-4.824.737-4.582 3.267"/>
+ <path fill="#fff" d="M43.44 21.884c.16 1.688 1.737 2.903 3.522 2.714 1.783-.19 3.098-1.712 2.936-3.4-.16-1.69-.188-1.835-3.404-1.493-3.22.344-3.217.49-3.054 2.18"/>
+ <g fill="#3e4347">
+ <ellipse cx="47.722" cy="20.932" rx="1.45" ry="1.647"/>
+ <path d="M39.76 17.896a.982.982 0 0 1-.935-.728c-.16-.546.132-1.122.65-1.29l5.98-1.924c.517-.166 1.063.14 1.224.685.155.543-.136 1.12-.653 1.287l-5.98 1.924a.96.96 0 0 1-.287.046"/>
+ </g>
+</svg>
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-bitmaps.tex b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-bitmaps.tex
new file mode 100644
index 00000000000..cf74c0cade9
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-bitmaps.tex
@@ -0,0 +1,189 @@
+% language=us
+
+\startcomponent followingup-bitmaps
+
+\environment followingup-style
+
+\startchapter[title={Bitmap images}]
+
+\startsection[title={Introduction}]
+
+In \TEX\ image inclusion is traditionally handled by specials. Think of a signal
+added someplace in the page stream that says:
+
+\starttyping
+\special{image: foo.png 2000 3000}
+\stoptyping
+
+Here the number for instance indicate a scale factor to be divided by 1000.
+Because \TEX\ has no floating point numbers, normally one uses an integer and the
+magic multiplier 1000 representing 1.000. Such a special is called a \quote
+{whatsit} and is one reason why \TEX\ is so flexible and adaptive.
+
+In \PDFTEX\ instead of a \type {\special} the command \type {\pdfximage} and its
+companions are used. In \LUATEX\ this concept has been generalized to \type
+{\useimageresource} which internally is not a so called whatsit (an extension
+node) but a special kind of rule. This makes for nicer code as now we don't need
+to check if a certain whatsit node is actually one with dimensions, while rules
+already are part of calculating box dimensions, so no extra overhead in checking
+for whatsits is added. In retrospect this was one of the more interesting
+conceptual changes in \LUATEX.
+
+In \LUAMETATEX\ we don't have such primitives but we do have these special rule
+nodes; we're talking of subtypes and the frontend doesn't look at those details.
+Depending on what the backend needs one can easily define a scanner that
+implements a primitive. We already did that in \CONTEXT. More important is that
+inclusion is not handled by the engine simply because there is no backend. This
+means that we need to do it ourselves. There are two steps involved in this that
+we will discuss below.
+
+\stopsection
+
+\startsection[title={Identifying}]
+
+There is only a handful of image formats that makes sense in a typesetting
+workflow. Because \PDF\ inclusion is supported (but not discussed here) one can
+actually take any format as long as it converts to \PDF, and tools like graphic
+magic do a decent job on that. \footnote {Although one really need to check a
+converted image. When we moved to pplib, I found out that lots of converted
+images in a project had invalid \PDF\ objects, but apart from a warning nothing
+bad resulted from this because those objects were not used.} The main bitmap
+formats that we care about are \JPEG, \JPEG2000, and \PNG. We could deal with
+\JBIG\ files but I never encountered them so let's forget about them for now.
+
+One of the problems with a built|-|in analyzer (and embedder) is that it can
+crash or just abort the engine. The main reason is that when the used libraries
+run into some issue, the engine is not always able to recover from it: a
+converter just aborts which then cleans up (potentially messed up) memory. In
+\LUATEX\ we also abort, simply because we have no clue to what extend further on
+the libraries are still working as expected. We play safe. For the average user
+this is quite ok as it signals that an image has to be fixed.
+
+In a workflow that runs unattended on a server and where users push images to a
+resource tree, there is a good change that a \TEX\ job fails because of some
+problem with images. A crash is not really an option then. This is one reason why
+converting bitmaps to \PDF\ makes much sense. Another reason is that some color
+profiling might be involved. Runtime manipulations make no sense, unless there is
+only one typesetting run.
+
+Because in \LMTX\ we do the analyzing ourselves \footnote {Actually, in \MKIV\
+this was also possible but not widely advertised, but we now exclusively keep
+this for \LMTX.} we can recover much easier. The main reason is of course that
+because we use \LUA, memory management and garbage collection happens pretty well
+controlled. And crashing \LUA\ code can easily be intercepted by a \type {pcall}.
+
+Most (extensible) file formats are based on tables that gets accessed from an
+index of names and offsets into the file. This means that filtering for instance
+metadata like dimensions and resolutions is no big deal (we always did that). I
+can extend analyzing when needed without a substantial change in the engine that
+can affect other macro packages. And \LUA\ is fast enough (and often faster) for
+such tasks.
+
+\stopsection
+
+\startsection[title={Embeding}]
+
+Once identified the frontend can use that information for scaling and (if needed)
+reuse of the same image. Embedding of the image resource happens when a page is
+shipped out. For \JPEG\ images this is actually quite simple: we only need to
+create a dictionary with the right information and push the bitmap itself into
+the associated stream.
+
+For \PNG\ images it's a bit different. Unfortunately \PDF\ only supports certain
+formats, for instance masks are separated and transparency needs to be resolved.
+This means that there are two routes: either pass the bitmap blob to the stream,
+or convert it to a suitable format supported by \PDF. In \LUATEX\ that is
+normally done by the backend code, which uses a library for this. It is a typical
+example of a dependency of something much larger than actually needed. In
+\LUATEX\ the original poppler library used for filtering objects from a \PDF\
+file as well as the \PNG\ library also have tons of code on board that relates to
+manipulating (writing) data. But we don't need those features. As a side note:
+this is something rather general. You decide to use a small library for a simple
+task only to find out after a decade that it has grown a lot offering features
+and having extra dependencies that you really don't want. Even worse: you end up
+with constant updates due to fixed security (read: bug) fixes.
+
+Passing the \PNG\ blob unchanged in itself to the \PDF\ file is trivial, but
+massaging it into an acceptable form when it doesn't suit the \PDF\ specification
+takes a bit more code. In fact, \PDF\ does not really support \PNG\ as format,
+but it supports \PNG\ compression (aka filters).
+
+Trying to support more complex \PNG\ files is a nice way to test if you can
+transform a public specification into a program as for instance happens with
+\PDF, \OPENTYPE, and font embedding in \CONTEXT. So this again was a nice
+exercise in coding. After a while I was able to process the \PNG\ test suite
+using \LUA. Optimizing the code came with understanding the specification.
+However, for large images, especially interlaced ones, runtime was definitely not
+to be ignored. It all depended on the tasks at hand:
+
+\startitemize
+
+\startitem
+ A \PNG\ blob is compressed with \ZIP\ compression, so first it needs to be
+ decompressed. This takes a bit of time (and in the process we found out that
+ the \type {zlib} library used in \LUATEX\ had a bug that surfaced when a
+ mostly zero byte image was uncompressed and we can then hit a filled up
+ buffer condition.
+\stopitem
+
+\startitem
+ The resulting uncompressed stream is itself compressed with a so called
+ filter. Each row starts with a filter byte that indicates how to convert
+ bytes into other bytes. The most commonly used methods are deltas with
+ preceding pixels and/or pixels on a previous row. When done the filter bytes
+ can go away.
+\stopitem
+
+\startitem
+ Sometimes an image uses 1, 2 or 4 bits per pixel, in which case the rows
+ needs to be expanded. This can involve a multiplication factor per pixel (it
+ can also be an index in a palette).
+\stopitem
+
+\startitem
+ An image can be interlaced which means that there are seven parts of the
+ image that stepwise build up the whole. In professional workflows with high
+ res images interlacing makes no sense as transfer over the internet is not an
+ issue and the overhead due to reassembling the image and the potentially
+ larger file size (due to independent compression of the seven parts) are not
+ what we want either.
+\stopitem
+
+\startitem
+ There can be an image mask that needs to be separated from the main blob. A
+ single byte gray scale image then has two bytes per pixel, and a double byte
+ pixel has four bytes of information. An \RGB\ image has three bytes per pixel
+ plus an alpha byte, and in the case of double byte pixels we get eight bytes
+ per pixel.
+\stopitem
+
+\startitem
+ Finally the resulting blob has to be compressed again. The current amount of
+ time involved in that suggests that there is room for improvement.
+\stopitem
+
+\stopitemize
+
+The process is controlled by number of rows and columns, the number of bytes per
+pixel (one or two) and the color space which effectively means one or three
+bytes. These numbers get fed into the filter, deinterlacer, expander and|/|or
+mask separator. In order to speed up the embedding these basic operations can be
+assisted by a helpers written in \CCODE. Because \LUA\ is quite good with
+strings, we pass strings and get back strings. So, most of the logic stays at the
+\LUA\ end.
+
+\stopsection
+
+\startsection[title=Conclusion]
+
+Going for a library|-|less solution for bitmap inclusion is quite doable and in
+most cases as efficient. Because we have a pure \LUA\ implementation for testing
+and an optimized variant for production, we can experiment as we like. A positive
+side effect is that we can more robustly intercept bad images and inject a
+placeholder instead.
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-cleanup.tex b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-cleanup.tex
new file mode 100644
index 00000000000..7dcb3b3b1fa
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-cleanup.tex
@@ -0,0 +1,332 @@
+% language=us
+
+% Youtube: TheLucs play with Jacob Collier // Don't stop til you get enough
+
+\startcomponent followingup-cleanup
+
+\environment followingup-style
+
+\logo [ALGOL] {Algol}
+\logo [FORTRAN] {FORTRAN}
+\logo [SPSS] {SPSS}
+\logo [DEC] {DEC}
+\logo [VAX] {VAX}
+\logo [AMIGA] {Amiga}
+
+\startchapter[title={Cleanup}]
+
+\startsection[title={Introduction}]
+
+Original \TEX\ is a literate program, which means that code and documentation are
+mixed. This mix, called a \WEB, is split into a source file and a \TEX\ file and
+both parts are processed independently into a program (binary) and a typeset
+document. The evolution of \TEX\ went through stages but in the end a \PASCAL\
+\WEB\ file was the result. This fact has lead to the more or less standard \WEBC\
+compilation infrastructure which is the basis for \TEXLIVE.
+
+% My programming experience started with programming a micro processor kit (using
+% an 1802 processor), but at the university I went from \ALGOL\ to \PASCAL\ (okay,
+% I also remember lots of \SPSS\ kind|-|of|-|\FORTRAN\ programming. The \PASCAL\
+% was the one provided on \DEC\ and \VAX\ machines and it was a bit beyond standard
+% \PASCAL. Later I did quite some programming in \MODULA 2 in (for a while an
+% \AMIGA) but mostly on personal computers. The reason that I mention this it that
+% it still determines the way I look at programs. For instance that code goes
+% through a couple if stepwise improvements (and that it can always be done
+% better). That you need to keep an eye on memory consumption (can be a nice
+% challenge). That a properly formatted source code is important (at least for me).
+%
+% When into \PASCAL, I ran into the \TEX\ series and as it looked familiar it ended
+% up on my bookshelf. However, I could not really get an idea what it was about,
+% simply because I had no access to the \TEX\ program. But the magic stayed with
+% me. The fact that \LUA\ resembles \PASCAL, made it a good candidate for extending
+% \TEX\ (there were other reasons as well). When decades later, after using \TEX\
+% in practice, I ended up looking at the source, it was the \LUATEX\ source.
+
+So, \TEX\ is a woven program and this is also true for the starting point of
+\LUATEX: \PDFTEX. But, because we wanted to open up the internals, and because
+\LUA\ is written in \CCODE, already in an early stage Taco decided to start from
+the \CCODE\ translated from \PASCAL. A permanent conversion was achieved using
+additional scripts and the original documentation stayed in the source. The one
+large file was split into more logical smaller parts and combined with snippets
+from \ALEPH .
+
+After we released version 1.0 I went through the documentation parts of the code
+and normalized that a bit. The at that moment still sort of simple \WEB\ files
+became regular \CCODE\ files, and the idea was (and is) that at some point it
+should be possible to process the documentation (using \CONTEXT).
+
+Over time the \CCODE\ code evolved and functions ended up in places that at that
+made most sense at that moment. After the previously described stripping process,
+I decided to go through the files and see if a bit of reshuffling made sense,
+mostly because that would make documenting easier. (I'm not literate enough to
+turn it into a proper literate program.) It was also a good moment to get rid of
+unused code (not that much) and unused macros (some more than expected). It also
+made sense to change a few names (for instance to avoid potential future clashes
+with \type {lua_} core functions). However, all this takes quite some careful
+checking and compilation runs, so I expect that after this first cleanup, for
+quite some time stepwise improvements can happen (especially in adding comments).
+\footnote {This is and will be an ongoing effort. It probably doesn't show, but
+getting the code base in the state it is in now, took quite some time. It
+probably won't take away complaints and nagging but I've decided no longer to pay
+attention to those on the sideline.} \footnote {In the end not much \PDFTEX\ and
+\ALEPH\ code is present in \LUAMETATEX , but these were useful intermediate
+steps. No matter how lean \LUAMETATEX\ becomes, I have a weak spot for \PDFTEX\
+as it always served us well and without it \TEX\ would be less present today.}
+
+One of the things that I keep in mind when doing this, is that we use \LUA. This
+component compiles on most relevant platforms and as such we can assume that
+\LUAMETATEX\ also should (and can be) made a bit less dependent on old mechanisms
+that are used in stock \LUATEX. For instance, we don't come from \PASCAL\ any
+longer but there are traces of that transition still present. We also don't use
+specific operating system features, and those that we use are also used in \LUA.
+And, as we try to share code we can also delegate some (more) to \LUA. For
+instance file related code is not dependent on other components in the \TEX\
+infrastructure, but maybe at some point the runtime loadable \KPSE\ library can
+kick in. So, basically the idea is to sort of go bare bone first and later see
+how with the help of \LUA\ we can get bring some back. For the record: this is
+not needed for \CONTEXT\ as it already has this interface to \TDS. \footnote
+{This has been removed from my agenda.}
+
+\stopsection
+
+\startsection[title={Motivation}]
+
+The \LUATEX\ project started as an experiment of adding \LUA\ to \PDFTEX, which
+was done by Hartmut and in order to avoid confusion we named it \LUATEX. When we
+figured out that there this had possibilities we decided to go further and Taco
+took the challenge to rework the code base. Part of that work was sponsored by
+Idris' Oriental \TEX\ project. I have fond memory of the intensive and rapid
+development cycles: online discussions, binaries going my directions,
+experimental \CONTEXT\ code going the other way. When we had reached a sort of
+stable state but at some point, read: usage in \CONTEXT\ had become crucial, a
+steady further development started, where Taco redid \METAPOST\ into \MPLIB,
+funded by user groups. At some point Luigi took over from Taco the task of
+integration of components (also into \TEX Live), introduced \LUAJIT\ into the
+binary, conducted the (again partially funded) swiglib project, followed by
+support for \FFI. A while later I myself started messing around in the code base
+directly and continued extending the engine and \LUA\ interfaces.
+
+I could work on this because I have quite some freedom at the place where I work.
+We use (part of) \CONTEXT\ for some projects and especially in dealing with \XML\
+we could benefit from \LUATEX. It must be said that (long running) projects like
+these never pay off (on the contrary, they cost a lot in terms of money and
+energy) so it's quite safe to conclude that \LUATEX\ development is to a large
+extend a (many man years) work of love for the subject. I guess that no sane
+company will do (permit) such a thing. It is also for that reason that I keep
+spending time on it, and as a simplification of the code base was always one of
+my dreams, this is what I spend my time on now. After all, \LUATEX\ is just
+juggling bytes and as it is written in \CCODE, and has no graphical user
+interface or complex dependencies, it should be possible to have a relative
+simple setup in terms of code files and compilation. Of course this is also made
+possible by the fact that I can use \LUA. It's also why I decided to
+\quotation {Just do it}, and then \quotation {Let's see where I end up}. No
+matter how it turns out, it makes a good vehicle for further development and
+years of fun.
+
+\stopsection
+
+\startsection[title={Files}]
+
+After a decade of adding and moving around code it's about time to reorganize the
+code a bit, but we do so without deviating too much from the original setup. For
+instance we started out with a small number of \LUA\ interface macros and these
+were collected in a few files, and defined in one \type {h} file, but it made
+sense to have header files alongside the libraries that implement helpers. This
+is a rather tedious job but with music videos or video casts on a second screen
+it is bearable.
+
+When I reached a state where we only needed the \LUATEX\ files plus the minimal
+set of libraries I tried to get rid of directories in the source tree that were
+placeholders, but with \type {automake} files, like those for \PDFTEX\ and
+\XETEX. After a couple of attempts I gave up on that because the build setup is
+rather hard coded for checking them. Also, there were some (puzzling)
+dependencies in the configuring on \OMEGA\ files as well as some \DVI\ related
+tools. So, that bit is for later to sort out. \footnote {Of course later the
+decision was made to forget about using \type {autotools} and go for an as simple
+as possible \type {cmake} solution.}
+
+\stopsection
+
+\startsection[title={Command line arguments}]
+
+As we need to set up a backend and deal with font loading in \LUA, we can as well
+delegate some of the command line handling to \LUA\ as well. Therefore, only the
+a limited set of options is dealt with: those that determine the startup and \LUA\
+behavior. In principle we can even get rid of all and always use a startup script
+but for now it makes sense to not deviate too much from a regular \TEX\ run.
+
+At the time of this writing some code is still in place that is a candidate for
+removal. For instance, using the \type {&} to define a format file has long be
+replaced by \type {--fmt}. There are sentimental reasons for keeping it but at
+the same time we need to realize that shells use these special characters too. A
+for me unknown (or forgotten) feature of prefixing a jobname with a \type {*}
+will be removed as it makes no sense. There is some \MSWINDOWS\ specific last
+resort code that probably will go too, unless I can figure out why it is needed
+in the first place. \footnote {Intercepting these symbols has been dropped in
+favor of the command line flags.}
+
+Now left with a very simple set of command line options it also makes sense to
+use a simple option analyzer, so that was a next step as it rid us of a
+dependency and produces less code.
+
+So, the option parser has now been replaced by a simple variant that is more in
+tune with what will happen when you deal with options in \LUA: no magic. One
+problem is that \TEX's first input file is moved from the command line to the
+input buffer and a an interactive session is emulated. As mentioned before, there
+is some extra \type {&}, \type {*} and \type {\\} parsing involved. One can
+wonder if this still makes sense in a situation where one has to specify a format
+and \LUA\ file (using \type {--fmt} and \type {--ini}) so that might as well be
+redone a bit some day. \footnote {In the end only these explicit command line
+options were supported.}
+
+\stopsection
+
+\startsection[title={Platforms}]
+
+When going through the code I noticed conditional sections for long obsolete
+platforms: \type {amiga}, \type {dos} and \type {djgpp}, \type {os/2}, \type
+{aix}, \type {solaris}, etc. Also, with 64 bit becoming the standard, it makes
+sense to assume that users will use a modern 64 platform (intel or arm combined
+with \MSWINDOWS\ or some popular \UNIX\ variant). We don't need large and complex
+code management for obscure platforms and architectures simply because we want to
+proof that \LUAMETATEX\ runs everywhere. With respect to \MSWINDOWS\ we use a
+cross compiler (\type {mingw}) as reference but native compilation should be no
+big deal eventually. We can cross that bridge when we have a simplified
+compilation set up. Right now it doesn't make sense to waste time on a native
+\MICROSOFT\ compilation as it would also pollute the code with conditional
+sections. We'll see what happens when I'm bored. \footnote {In the meantime no
+effort is made to let the source compile otherwise than with the cross compiler.
+Best is to keep the code as clean as possible with respect to conditional code
+sections. So don't bother me with patches.}
+
+\stopsection
+
+\startsection[title={Stubs}]
+
+A \CONTEXT\ run is managed by \MTXRUN\ in combination with a specific script
+
+\starttyping
+mtxrun --script context
+\stoptyping
+
+On windows, we use a stub because using a \type {cmd} file create an indirectness
+that is not seen as executable and therefore in other command files needs to
+be called in a special way to guarantee continuation. So, there we have a small
+binary:
+
+\starttyping
+mtxrun.exe ...
+\stoptyping
+
+that will call:
+
+\starttyping
+luatex --luaonly mtxrun.lua ...
+\stoptyping
+
+And when the stub has a different name than \type {mtxrun}, say:
+
+\starttyping
+context.exe ...
+\stoptyping
+
+it effectively becomes:
+
+\starttyping
+luatex --luaonly mtxrun.lua --script context ...
+\stoptyping
+
+Because the stripped down version assumes some kind of initializations anyway a
+small extension made it possible to use \LUAMETATEX\ as stub too. So, when we
+rename \type {luametatex.exe} to \type {mtxrun.exe} (on \UNIX\ we don't use a
+suffix) it will start up as \LUA\ interpreter when it finds a script with the
+name \type {mtxrun.lua} in the same path. When we rename it to \type
+{context.exe} it will search for \type {context.lua} and all that that script has
+to do is this:
+
+\starttyping
+arg[0] = "mtxrun"
+
+table.insert(arg,1,"mtx-context")
+table.insert(arg,1,"--script")
+
+dofile(os.selfpath .. "/" .. "mtxrun.lua")
+\stoptyping
+
+So, it basically becomes a call to \type {mtxrun}, but we stay in \LUAMETATEX.
+Because we want an isolated run this will launch \LUAMETATEX\ again with the
+right command line arguments. This sounds inefficient but because we have a small
+binary this is no real issue, and as that run is isolated, it cannot influence
+the caller. The overhead is really small: on my somewhat older laptop it's .2
+seconds, but we had that management overhead already for decades, so no one
+bothers about it. On all platforms using symbolic links works ok too.
+
+\stopsection
+
+\startsection[title={Global variables}]
+
+There are quite a bit global variables and function in the code base, but in the
+process of opening up I got rid of some. The cleanup turned some more into
+locals which saved executable bytes (keep in mind that we also use the engine as
+\LUA\ interpreter so, the smaller, the more friendly). \footnote {Later the
+global variables were collected in so called \CCODE\ structs.} This is work
+in progress.
+
+\stopsection
+
+\startsection[title={Memory usage}]
+
+By going over all the code a couple of times, I was able to decrease the amount
+of used memory a bit as well as avoid some memory allocations. This has no
+consequences for performance but is nicer when multiple runs at the same time
+(e.g.\ on virtual machines) have to compete for resources. \footnote {I will
+probably have to spend some more time on this in order to reach a state that I'm
+satisfied with.}
+
+\stopsection
+
+\startsection[title={\METAPOST}]
+
+The current code base doesn't have that many files. We can imagine that, when
+\LUA\ can be compiled on a platform, that compiling \LUAMETATEX\ is also no that
+complicated. However, the rather complex build infrastructure demonstrates the
+opposite. One of the complications is that \MPLIB\ is codes in \CWEB\ and that
+needs some juggling to get \CCODE. The process has quite some dependencies. There
+are some upstream patches needed, but for now occasionally checking with the
+upstream sources used for compiling \MPLIB\ in \LUATEX\ works okay. \footnote
+{Later I decided to cleanup the \MPLIB\ code: unused font related code was
+removed, the \POSTSCRIPT\ backend was untangled, the translation from \CWEB\ to
+\CCODE\ got done by a \LUA\ script, aspects like error reporting and \IO\ were
+redone, and in the end some new extensions were added. Some of that might trickle
+back to th original, as long as it doesn't harm compatibility; after all
+\METAPOST\ (the program) is standardized and considered functionally stable.}
+
+As \LUAMETATEX\ is also used for experiments we use a copy of the \LUA\ library
+interface. That way we don't interfere with the stable \LUATEX\ situation. When
+we play with extensions, we can always decide to backport them, once they are
+found useful and in good working order. But, as that interface was just \CCODE\
+this was trivial.
+
+\stopsection
+
+\startsection[title={Files}]
+
+In a relative late stage I decided to cleanup some of the filename handling.
+First I got rid of the \type {area}, \type {name} and \type {ext} decomposition
+and optional recomposition. In the original engine that goes through the string
+pool and although there is some recovery in the end, with many files and fonts
+being used, the pool can get exhausted. For instance when you have hundreds of
+thousands of \typ {\font \foo = bar} kind of definitions, each definition wipes
+out the previous entry in the hash, but its font name is kept in the string pool.
+I got rid of that side effect by reusing strings but in the end decided to avoid
+the pool altogether. It was then a small step to also do that for other
+filenames. In the process I also decided that it made no sense to keep the code
+around that reads a filename from the console: we now just quit. Restarting the
+program with a proper filename is no big deal today. I might do some more cleanup
+there. In the end we can best use a callback for handling input from the console.
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-compilation.tex b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-compilation.tex
new file mode 100644
index 00000000000..a0e67d4bed9
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-compilation.tex
@@ -0,0 +1,84 @@
+% language=us
+
+\startcomponent followingup-compilation
+
+\environment followingup-style
+
+\startchapter[title={Compilation}]
+
+Compiling \LUATEX\ is possible because after all it's what I do on my machine.
+The \LUATEX\ source tree is part of a larger infrastructure: \TEX Live. Managing
+that one is work for specialists and the current build system is the work of
+experts over a quite long period of time. When you only compile \LUATEX\ it goes
+unnoticed that there are many dependencies, some of which are actually unrelated
+to \LUATEX\ itself but are a side effect of the complexity of the build
+structure.
+
+When going from \LUATEX\ to \LUAMETATEX\ many dependencies were removed and I
+eventually ended up with a simpler setup. The source tree went down to less than
+30 MB and zipped to around 4 MB. That makes it possible to consider adding the
+code to the regular \CONTEXT\ distribution.
+
+One reason for doing that is that one keeps the current version of the engine
+packaged with the current version of \CONTEXT. But a more important one is that
+it fulfils a demand. Some time ago we were asked by some teachers participating
+in a (basically free) math method for technical education what guarantees there
+are that the tools used are available forever. Now, even with \LUAMETATEX\ one
+has to set up a compiler but it is much easier than installing the whole \TEX
+Live infrastructure for that. A third reason is that it gives me a comfortable
+feeling that I myself can compile it anywhere as can \CONTEXT\ users who want to
+do that.
+
+The source tree traditionally has libs in a separate directory (lua, luajit, zlib
+and zziplib). However, it is more practical to have them alongside our normal
+source. These are relative small collections of files that never change so there
+is no reason not to do it. \footnote {If I ever decide to add more libraries,
+only the minimal interfaces needed will be provided, but at this moment there are
+no such plans.}
+
+Another assumption we're going to make is that we use 64 bit binaries. There is
+no need to support obsolete platforms either. As a start we make sure it compiles
+on the platforms used by \CONTEXT\ users. Basically we make a kind of utility.
+For now I can compile the \WINDOWS\ 32 bit binaries that my colleague needs in
+half a minute anyway, but in the long run we will settle for 64 bits.
+
+I spent about a week figuring out why the compilation is so complex (by
+selectively removing components). At some point compilation on \OSX\ stopped
+working. When the minimum was reached I decided to abandon the automake tool
+chain and see if \type {cmake} could be used (after all, Mojca challenged that).
+In retrospect I should have done that sooner because in a day I could get all
+relevant platforms working. Flattening the source tree was a next step and so
+there is no way back now. What baffled me (and Alan, who at some point joined in
+testing \OSX) is the speed of compilation. My pretty old laptop needed about half
+a minute to get the job done and even on a raspberry pi with only a flash card
+just a few minutes were needed. At that point, as we could remove more make
+related files, the compressed 11 MB archive (\type {tar.xz}) shrunk to just over
+2~MB. Interesting is that compiling \MPLIB\ takes most time, and when one compiles
+in parallel (on more cores) that one finishes last.
+
+For the record: I do all this on a laptop running \MSWINDOWS\ 10 using the Linux
+subsystem. When that came around, Luigi made me a working setup for cross
+compilation but in the meantime with GCC 8.2 all works out of the box. I edit the
+files at the \MSWINDOWS\ end (using \SCITE), compile at the \LINUX\ end, and test
+everything on \MSWINDOWS. It is a pretty convenient setup.
+
+When compilation got faster it became also more convenient to do some more code
+reshuffling. This time I decided to pack the global variables into structures,
+more or less organized the way the header files were organized. It gives a bit
+more verbosity but also has the side effects that (at least in principle) the
+\CPU\ cache can perform better because neighboring variables are often cached as
+part of the deal. Now it might be imagination, but in the process I did notice
+that mid March processing the manual went down to below 11.7 seconds while before
+it stayed around 12.1 seconds. Of course this is not that relevant currently, but
+I might make a difference on less capable processors (as in a low power setup).
+It anyway didn't hurt.
+
+In the meantime some of the constants used in the program got prefixes or
+suffixes to make them more unique and for instance the use of \type {normal} as
+equivalent for zero was made a bit more distinctive as we now have more subtypes.
+That is: all the subtypes were collected in enumerations instead of \CCODE\
+defines. Back to the basics.
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-contents.tex b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-contents.tex
new file mode 100644
index 00000000000..3fbfc701a5b
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-contents.tex
@@ -0,0 +1,11 @@
+\startcomponent followingup-contents
+
+\environment followingup-style
+
+\starttitle[title={Table of contents}]
+
+ \placelist[chapter]
+
+\stoptitle
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-directions.tex b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-directions.tex
new file mode 100644
index 00000000000..244baff90de
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-directions.tex
@@ -0,0 +1,778 @@
+% language=us
+
+\startcomponent followingup-directions
+
+\environment followingup-style
+
+\startchapter[title={Directions}]
+
+\startsection[title={Introduction}]
+
+In \LUATEX\ the directional model taken from \OMEGA\ has been upgraded a bit. For
+instance in addition to the \type {\*dir} commands we have \type {\*direction}
+commands that take a number instead of a keyword. This is a bit more efficient and
+consistent as using these keywords was kind of un|-|\TEX. Internally direction
+related nodes (text directions) are not whatsits but first class nodes. We also
+use a subtype that indicates the push or pop state.
+
+The \LUATEX\ directional model provides four directions which is a subset of the
+many that \OMEGA\ provided, indicated by three letters, like \type {TRT} and
+\type {LTT}. In the beginning we had them all fixed\footnote {This was doen by
+Hartmut by rigorously checking all possible combinations} and thereby implemented
+but being in doubt about their usefulness we dropped most of them, just four were
+kept. However, in practice only right|-|to|-|left makes sense. Going from top to
+bottom in Japanese or Mongolian can also involve glyph rotation, which actually
+is not implemented in the engine at all. Spacing and inter|-|character breaks
+have to be implemented and in the end one has to combine the results into a
+page body. So, in practice you end up with juggling node list and macro magic in
+the page builder. The \type {LTL} (number~2) and \type {RTT} (number~3)
+directions are not used for serious work. Therefore, in \LUAMETATEX\ the model
+has been adapted. In the end, it was not entirely clear anyway what the three
+letters were indicating in each direction property (page, body, par, text, math)
+as most had no real meaning.
+
+As a side note: if you leave the (not really working well) vertical directions
+out of the picture, directional typesetting is not that hard to deal with and has
+hardly any consequences for the code. This is because horizontal dimensions are
+not affected by direction, only the final ship out is: when a run (wrapped in an
+hbox) goes the other way, the backend effectively has to skip the width and then
+with each component goes back. Not much more is involved. This means that a
+bidirectional engine is rather simple. The complications are more in the way a
+macro package deals with it, in relation to the input as well as the layout. The
+backend has to do the real work. \footnote {Of course when one hooks in \LUA\
+code taking care of direction can be needed!}
+
+\stopsection
+
+\startsection[title=Two directions]
+
+We now have only two directions left: the default left|-|to|-|right (l2r) and
+right|-|to|-|left (r2l). They work the same as before and in the backend we can
+get rid of the fuzzy parallel and rotation (which actually was just stacking
+nodes) heuristics.
+
+Reducing the lot to two directions simplifies some code in the engine. This is
+because when calculating dimensions a change in horizontal direction doesn't
+influence the width, height and depth in an orthogonal way. Because there are no
+longer top|-|down items we don't need to swap the height and or depth with the
+width. This also means that we don't need to keep much track of direction
+changes. Technically an hpack doesn't need to know its own direction and we can
+set it to any value afterwards if we want because the calculation are not
+influenced by it; so that also simplified matters.
+
+The \type {\bodydir} and \type {\pagedir} already didn't make much sense, and in
+\CONTEXT\ we actually intercepted them, so now they are removed. The body
+direction is always left|-|to|-|right and the page direction was only consulted
+in the backend code which we no longer have. Another side effect of going with
+only two directions is that rules no longer need to carry the direction property:
+there is no flipping of width with height and depth needed.
+
+\stopsection
+
+\startsection[title=Four orientations]
+
+Instead of the top|-|bottom variants we now have four orientations plus a bunch
+of anchoring options. Of course one could use the backend save, restore and
+matrix whatsits but a natural feature makes more sense. Let's start with what
+happens normally:
+
+\startbuffer[1]
+This is a \LUAMETATEX\ goodie.
+\stopbuffer
+
+\startbuffer[2]
+\hbox orientation 2{This is a \LUAMETATEX\ goodie.}
+\stopbuffer
+
+\startbuffer[3]
+This is a \hbox orientation 2{\LUAMETATEX} goodie.
+\stopbuffer
+
+\startbuffer[4]
+\hbox orientation 2{This is a \hbox orientation 002{\LUAMETATEX} goodie.}
+\stopbuffer
+
+\blank{\showstruts\strut}\quad\ruledhbox{\inlinebuffer[1]}\quad{\showstruts\strut}\blank
+
+This line has height and depth. We can rotate this sentence by 180 degrees around
+the baseline in which case the depth and height are flipped.
+
+\blank{\showstruts\strut}\quad\ruledhbox{\inlinebuffer[2]}\quad{\showstruts\strut}\blank
+
+or we flip part:
+
+\blank{\showstruts\strut}\quad\ruledhbox{\inlinebuffer[3]}\quad{\showstruts\strut}\blank
+
+or flip nested:
+
+\blank{\showstruts\strut}\quad\ruledhbox{\inlinebuffer[4]}\quad{\showstruts\strut}\blank
+
+but we're talking boxes, so the above examples are defined as:
+
+\typebuffer[1,2,3,4]
+
+The \type {orientation} keyword does the magic here. There are four such
+orientations with zero being the default. We saw that two rotates over 180
+degrees, so one and three are left for up and down.
+
+\startbuffer[5]
+\hbox orientation 0 {\TEX} and
+\hbox orientation 1 {\TEX} and
+\hbox orientation 2 {\TEX} and
+\hbox orientation 3 {\TEX}
+\stopbuffer
+
+\blank{\showstruts\strut}\quad\ruledhbox{\inlinebuffer[5]}\quad{\showstruts\strut}\blank
+
+This is codes as:
+
+\typebuffer[5]
+
+The landscape and seascape variants both sit on top of the baseline while the
+flipped variant has its depth swapped with the height. Although this would be
+enough a bit more control is possible. The number is actually a three byte hex
+number:
+
+\starttyping
+0x<X><Y><O>
+\stoptyping
+
+or in \TEX\ syntax
+
+\starttyping
+"<X><Y><O>
+\stoptyping
+
+We saw that the last byte regulates the orientation. The first and second one
+deal with anchoring horizontally and vertically. The vertical options of the
+horizontal variants anchor on the baseline, lower corner, upper corner or center.
+
+\startbuffer[6]
+\hbox orientation "002 {\TEX} and
+\hbox orientation "012 {\TEX} and
+\hbox orientation "022 {\TEX} and
+\hbox orientation "032 {\TEX}
+\stopbuffer
+
+\typebuffer[6]
+
+\blank{\showstruts\strut}\quad\ruledhbox{\inlinebuffer[6]}\quad{\showstruts\strut}\blank
+
+\startbuffer[7]
+\hbox orientation "002 {\TEX} and
+\hbox orientation "102 {\TEX} and
+\hbox orientation "202 {\TEX} and
+\hbox orientation "302 {\TEX} and
+\hbox orientation "402 {\TEX}
+\stopbuffer
+
+The horizontal options of the horizontal variants anchor in the center, left, right,
+halfway left and halfway right.
+
+\typebuffer[7]
+
+\blank{\showstruts\strut}\quad\ruledhbox{\inlinebuffer[7]}\quad{\showstruts\strut}\blank
+
+All combinations will be shown on the next pages, so we suffice with telling that
+for the vertical variants we can vertically anchor on the baseline, top, bottom
+or center, while horizontally we center, hang left or right, halfway left or
+right, and in addition align on the (rotated) baseline left or right.
+
+The orientation has consequences for the dimensions so they are dealt with in the
+expected way in constructing lines, paragraphs and pages, but the anchoring is
+virtual. As a bonus, we have two extra variants for orientation zero: on top of
+baseline or below, with dimensions taken into account.
+
+\startbuffer[8]
+\hbox orientation "000 {\TEX} and
+\hbox orientation "004 {\TEX} and
+\hbox orientation "005 {\TEX}
+\stopbuffer
+
+\typebuffer[8]
+
+\blank{\showstruts\strut}\quad\ruledhbox{\inlinebuffer[8]}\quad{\showstruts\strut}\blank
+
+\definecolor[brcolorh][r=1,t=.5,a=1]
+\definecolor[brcolord][b=1,t=.5,a=1]
+\definecolor[brcolorm][g=1,t=.5,a=1]
+
+\starttexdefinition ShowAnchor
+ \blackrule[width=2pt,height=1pt,depth=1pt,color=darkgray]
+\stoptexdefinition
+
+\starttexdefinition DemoRule#1#2#3
+ \ShowAnchor
+ \ruledhbox {
+ \hbox orientation "#1#2#3 {
+ \blackrule[height=6mm,depth=0mm,width=8mm,color=brcolorh]\kern-8mm\relax
+ \blackrule[height=0mm,depth=3mm,width=8mm,color=brcolord]\kern-8mm\relax
+ \blackrule[height=2mm,depth=-1mm,width=8mm,color=brcolorm]
+ }
+ }
+ \ShowAnchor
+\stoptexdefinition
+
+\starttexdefinition DemoText#1#2#3
+ \ShowAnchor
+ \ruledhbox{\hbox orientation "#1#2#3 {\red\TEX}}
+ \ShowAnchor
+\stoptexdefinition
+
+\starttexdefinition DemoSet #1#2
+ \startcombination[nx=4,ny=7,width=10cm]
+ {#200#1}{\ttxx 0x00#1} {#201#1}{\ttxx 0x01#1} {#202#1}{\ttxx 0x02#1} {#203#1}{\ttxx 0x03#1}
+ {#210#1}{\ttxx 0x10#1} {#211#1}{\ttxx 0x11#1} {#212#1}{\ttxx 0x12#1} {#213#1}{\ttxx 0x13#1}
+ {#220#1}{\ttxx 0x20#1} {#221#1}{\ttxx 0x21#1} {#222#1}{\ttxx 0x22#1} {#223#1}{\ttxx 0x23#1}
+ {#230#1}{\ttxx 0x30#1} {#231#1}{\ttxx 0x31#1} {#232#1}{\ttxx 0x32#1} {#233#1}{\ttxx 0x33#1}
+ {#240#1}{\ttxx 0x40#1} {#241#1}{\ttxx 0x41#1} {#242#1}{\ttxx 0x42#1} {#243#1}{\ttxx 0x43#1}
+ {#250#1}{\ttxx 0x50#1} {#251#1}{\ttxx 0x51#1} {#252#1}{\ttxx 0x52#1} {#253#1}{\ttxx 0x53#1}
+ {#260#1}{\ttxx 0x60#1} {#261#1}{\ttxx 0x61#1} {#262#1}{\ttxx 0x62#1} {#263#1}{\ttxx 0x63#1}
+ \stopcombination
+\stoptexdefinition
+
+\startplacefigure[title={orientation 0}]\scale[width=\textwidth]{\framed[offset=1cm]{\DemoSet0\DemoRule}}\stopplacefigure
+\startplacefigure[title={orientation 1}]\scale[width=\textwidth]{\framed[offset=1cm]{\DemoSet1\DemoRule}}\stopplacefigure
+\startplacefigure[title={orientation 2}]\scale[width=\textwidth]{\framed[offset=1cm]{\DemoSet2\DemoRule}}\stopplacefigure
+\startplacefigure[title={orientation 3}]\scale[width=\textwidth]{\framed[offset=1cm]{\DemoSet3\DemoRule}}\stopplacefigure
+
+\startplacefigure[title={orientation 0}]\scale[width=\textwidth]{\framed[offset=1cm]{\DemoSet0\DemoText}}\stopplacefigure
+\startplacefigure[title={orientation 1}]\scale[width=\textwidth]{\framed[offset=1cm]{\DemoSet1\DemoText}}\stopplacefigure
+\startplacefigure[title={orientation 2}]\scale[width=\textwidth]{\framed[offset=1cm]{\DemoSet2\DemoText}}\stopplacefigure
+\startplacefigure[title={orientation 3}]\scale[width=\textwidth]{\framed[offset=1cm]{\DemoSet3\DemoText}}\stopplacefigure
+
+% \page
+
+The anchoring can look somewhat confusing but you need to keep in mind that it is
+normally only used in very controlled circumstances and not in running text.
+Wrapped in macros users don't see the details. We're talking boxes here, so or
+instance:
+
+\startbuffer
+test\quad
+\hbox orientation 3 \bgroup
+ \strut test\hbox orientation "002 \bgroup\strut test\egroup test%
+\egroup \quad
+\hbox orientation 3 \bgroup
+ \strut test\hbox orientation "002 \bgroup\strut test\egroup test%
+\egroup \quad
+\hbox orientation 3 \bgroup
+ \strut test\hbox orientation "012 \bgroup\strut test\egroup test%
+\egroup \quad
+\hbox orientation 3 \bgroup
+ \strut test\hbox orientation "022 \bgroup\strut test\egroup test%
+\egroup \quad
+\hbox orientation 3 \bgroup
+ \strut test\hbox orientation "032 \bgroup\strut test\egroup test%
+\egroup \quad
+\hbox orientation 3 \bgroup
+ \strut test\hbox orientation "042 \bgroup\strut test\egroup test%
+\egroup
+\quad test
+\stopbuffer
+
+\typebuffer
+
+gives:
+
+\startlinecorrection[blank]
+\ruledhbox\bgroup \showcolorstruts \showboxes \inlinebuffer \egroup
+\stoplinecorrection
+
+\stopsection
+
+\startsection[title={Right|-|to|-|left typesetting}]
+
+Another aspect to keep in mind when we transform is the already mentioned
+right|-|to|-|left direction. We show some examples where we do things like this:
+
+\starttyping
+\hbox{\hbox
+ orientation #1
+ {\strut abcd}}
+\hbox{\hbox
+ orientation #1
+ to 15mm
+ {\strut abcd}}
+\hbox{\hbox
+ orientation #1
+ direction 1
+ {\righttoleft\strut abcd}}
+\hbox{\hbox
+ orientation #1
+ direction 1
+ to 15mm {\righttoleft\strut abcd}}
+\stoptyping
+
+\starttexdefinition TestH #1
+ \dontcomplain
+ \setbox\scratchbox\hbox{abcd}%
+ x\ruledhbox{\hbox orientation #1 to \wd\scratchbox {\strut abcd}}x\quad
+ x\ruledhbox{\hbox orientation #1 to 15mm {\strut abcd}}x\quad
+ x\ruledhbox{\hbox orientation #1 direction 1 to \wd\scratchbox {\righttoleft\strut abcd}}x\quad
+ x\ruledhbox{\hbox orientation #1 direction 1 to 15mm {\righttoleft\strut abcd}}x%
+\stoptexdefinition
+
+\starttexdefinition TestV #1
+ \dontcomplain
+ \setbox\scratchbox\hbox{abcd}%
+ x\ruledvbox{\vbox orientation #1 {\hsize \wd\scratchbox\strut abcd}}x\quad
+ x\ruledvbox{\vbox orientation #1 {\hsize 15mm\strut abcd}}x\quad
+ x\ruledvbox{\vbox orientation #1 {\righttoleft\hsize \wd\scratchbox\strut abcd}}x\quad
+ x\ruledvbox{\vbox orientation #1 {\righttoleft\hsize 15mm\strut abcd}}x%
+\stoptexdefinition
+
+\startplacefigure[title={Horizontal boxes.}]
+ \startcombination[nx=2,ny=2]
+ {\TestH 0} {orientation 0}
+ {\TestH 2} {orientation 2}
+ {\TestH 1} {orientation 1}
+ {\TestH 3} {orientation 3}
+ \stopcombination
+\stopplacefigure
+
+\startplacefigure[title={Vertical boxes.}]
+ \startcombination[nx=2,ny=2]
+ {\TestV 0} {orientation 0}
+ {\TestV 2} {orientation 2}
+ {\TestV 1} {orientation 1}
+ {\TestV 3} {orientation 3}
+ \stopcombination
+\stopplacefigure
+
+\stopsection
+
+\startsection[title={Vertical typesetting}]
+
+I'm no expert on vertical typesetting and have no application for it either. But
+from what I've seen vertically positioned glyphs are normally used in rather
+straightforward situations. Here I will just give some examples of how
+transformations can be used to achieve certain effects. It is no big deal to make
+macros or use \LUA\ to apply magic to node lists but it is beyond this description
+to discuss that.
+
+Before we fine tune this example we have to discuss another feature. When a \typ
+{orientation} keyword is given optionally \type {xoffset} and \type {yoffset} can
+be specified. These offsets are {\em not} taken into account when calculating
+dimensions. This is different from the offsets (at the \LUA\ end) used in glyphs
+because there the vertical offset is taken into account. Here are some examples
+of offsets in packaged lists:
+
+\startbuffer
+\hbox
+ {test 1}
+\hbox
+ orientation 0
+ yoffset 15pt
+ xoffset 150pt
+ {test}
+\vbox
+ orientation 0
+ {\hbox{test}}
+\vbox
+ orientation 0
+ yoffset -5pt
+ xoffset 130pt
+ {\hbox{test}}
+\vbox
+ orientation 0
+ yoffset 2pt
+ {\hbox{test}}
+\stopbuffer
+
+\typebuffer
+
+\startlinecorrection[blank]
+ \start \showboxes \bfd \getbuffer \stop
+\stoplinecorrection
+
+In order to demonstrate some hacking, we first define a font that supports
+chinese glyphs:
+
+\startbuffer
+\definefont[NotoCJK][NotoSansCJKtc-Regular*default @ 24pt]
+\stopbuffer
+
+\typebuffer \getbuffer
+
+We put some text in a horizontal box; it doesn't show up in verbatim but you
+get the idea nevertheless:
+
+\startbuffer
+\hbox{\NotoCJK 通用规范汉字表}
+\stopbuffer
+
+\typebuffer
+
+\startlinecorrection[blank]
+ \start \showboxes \getbuffer \stop
+\stoplinecorrection
+
+Let's now rotate this line of text:
+
+\startbuffer[1]
+\hbox orientation 1 {\NotoCJK 通用规范汉字表}
+\stopbuffer
+
+\typebuffer[1]
+
+The result is shown in a while. Because we also need to rotate the glyphs we
+deconstruct the box.
+
+\startbuffer[2]
+\hbox orientation 1 \bgroup \NotoCJK %
+ \vbox {\hbox {通}}%
+ \vbox {\hbox {用}}%
+ \vbox {\hbox {规}}%
+ \vbox {\hbox {test}}%
+ \vbox {\hbox {范}}%
+ \vbox {\hbox {汉}}%
+ \vbox {\hbox {字}}%
+ \vbox {\hbox {表}}%
+\egroup
+\stopbuffer
+
+\typebuffer[2]
+
+Next we rotate the glyphs.
+
+\startbuffer[3]
+\hbox orientation 1 \bgroup \NotoCJK %
+ \vbox orientation 3 {\hbox {通}}%
+ \vbox orientation 3 {\hbox {用}}%
+ \vbox orientation 3 {\hbox {规}}%
+ \vbox orientation 0 {\hbox {test}}%
+ \vbox orientation 3 {\hbox {范}}%
+ \vbox orientation 3 {\hbox {汉}}%
+ \vbox orientation 3 {\hbox {字}}%
+ \vbox orientation 3 {\hbox {表}}%
+\egroup
+\stopbuffer
+
+\typebuffer[3]
+
+This still looks bad so we kick in some offsets and glue:
+
+\startbuffer[4]
+\dontleavehmode\hbox orientation 1 \bgroup \NotoCJK
+ \vbox
+ orientation 0 yoffset -.1ex
+ {\hbox orientation 3 {通}}\hskip.2ex
+ \vbox
+ orientation 0 yoffset -.1ex
+ {\hbox orientation 3 {用}}\hskip.2ex
+ \vbox
+ orientation 0 yoffset -.1ex
+ {\hbox orientation 3 {规}}\hskip.6ex
+ \vbox
+ {\hbox {test}}\hskip.2ex
+ \vbox
+ orientation 0 yoffset -.1ex
+ {\hbox orientation 3 {范}}\hskip.2ex
+ \vbox
+ orientation 0 yoffset -.1ex
+ {\hbox orientation 3 {汉}}\hskip.2ex
+ \vbox
+ orientation 0 yoffset -.1ex
+ {\hbox orientation 3 {字}}\hskip.2ex
+ \vbox
+ orientation 0 yoffset -.1ex
+ {\hbox orientation 3 {表}}\hskip.2ex
+\egroup
+\stopbuffer
+
+\typebuffer[4]
+
+Now we're ready to compare the results
+
+\startlinecorrection[blank]
+ \startcombination[9*1]
+ {\showboxes \getbuffer[1]} {1}
+ {\showboxes \getbuffer[2]} {2}
+ {\showboxes \getbuffer[3]} {3}
+ {\showboxes \getbuffer[4]} {4}
+ {\quad}{}
+ {\getbuffer[1]} {1}
+ {\getbuffer[2]} {2}
+ {\getbuffer[3]} {3}
+ {\getbuffer[4]} {4}
+ \stopcombination
+\stoplinecorrection
+
+This could of course also be done with traditional kerns, raising and|/|or
+lowering and messing around with dimensions. It's just that when manipulating
+such rather complex constructs a little help (and efficiency) makes a difference,
+also at the \LUA\ end. Of course one can argue the result but all is
+programmable in the end.
+
+\stopsection
+
+\startsection[title={Considerations}]
+
+Just in case you wonder if using these offsets is better than using normal kerning
+and shifting, in practice offsets are not more efficient. Let's compare the
+alternatives. We go from most to least efficient.
+
+\starttyping
+\setbox\scratchbox\hpack{}
+\boxxoffset\scratchbox\scratchdimen
+\boxyoffset\scratchbox\scratchdimen
+\stoptyping
+
+This sets the offsets and by setting them we also trigger the transform. Scanning
+is fast and so is setting them. One million times expanding this takes (as
+reference) 0.73 seconds on my current machine.
+
+\starttyping
+\setbox\scratchbox\hpack
+ orientation \zerocount
+ xoffset \scratchdimen
+ yoffset \scratchdimen
+ {}
+\stoptyping
+
+This takes a bit more time, 1.11 seconds, because the keywords have to be scanned
+which happens on a token by token base.
+
+\starttyping
+\setbox\scratchbox\hpack{}
+\scratchheight\ht\scratchbox
+\scratchdepth\dp\scratchbox
+\setbox\scratchbox\hpack
+ {\kern\scratchdimen
+ \raise\scratchdimen\box\scratchbox
+ \kern\scratchdimen}
+\ht\scratchbox\scratchheight
+\dp\scratchbox\scratchdepth
+\stoptyping
+
+Now we're up to 1.69 seconds for the million expansions. Not only do we have some
+parsing going on, but we also have assignments and extra packing, which means
+calculations taking place.
+
+\starttyping
+\setbox\scratchbox\hpack{}
+\scratchwidth\wd\scratchbox
+\scratchheight\ht\scratchbox
+\scratchdepth\dp\scratchbox
+\setbox\scratchbox\hpack
+ {\kern\scratchdimen
+ \raise\scratchdimen\box\scratchbox}
+\wd\scratchbox\scratchwidth
+\ht\scratchbox\scratchheight
+\dp\scratchbox\scratchdepth
+\stoptyping
+
+This variant is about as fast, as I measured 1.72 seconds. So, compared to the
+0.73 seconds for the first variant, is this better? Does it help when we look at
+our existing macros and adapt them?
+
+Normally we don't have an empty box and normally we use \type {\hbox} because we
+want the content to be processed. And a million times building a list and
+processing content (which means runs over the list) will make the differences
+in timing become noise. Add to that garbage collection (in \LUA) and memory
+management (in \TEX) and it even becomes unpredictable. Seeing differences of
+a factor two in such timings is no exception.
+
+Another aspect is the parsing. When these commands are wrapped in macros we're
+talking expanding tokens which is pretty fast. When it comes from the input file
+a conversion to tokens has to happen too. And we will never see millions of such
+sequences in a source file.
+
+The backend also plays a role. Handling a kern or shift is more efficient than
+analyzing transforms (and offsets) especially in a \LUA\ variant. But on the
+other hand, we don't have an extra wrapping in a box so that actually saves work.
+
+So, before a \CONTEXT\ user thinks \quotation {Let's update macros and change
+policy.}, just consider staying with proven good old \TEX\ approaches. These
+features are mostly meant for efficient low level manipulations as discussed in
+relation to for instance handling scripts. In the rather large \CONTEXT\ code
+base there are really only a few places where it will make code look nicer, but
+there I don't expect an impact on performance.
+
+\stopsection
+
+\startsection[title={Integration}]
+
+How these mechanisms are used depends on ones needs and the macro package used.
+It makes no sense to cook up generic solutions because integration in a macro
+package is too different. But anyhow we'll give an example of some (definitely
+non optimized) \LUA\ magic.
+
+\startbuffer
+\startluacode
+local glyph_id = node.id("glyph")
+local fontdata = fonts.hashes.identifiers -- assumes generic font loader
+
+local function is_vertical(c)
+ -- more ranges matter but this will do here
+ return c >= 0x04E00 and c <= 0x09FFF
+end
+
+function document.go_vertical(boxnumber)
+ local box = tex.getbox(boxnumber)
+ local n = box.list
+ while n do
+ if n.id == glyph_id and is_vertical(n.char) then
+ local o = .2 * fontdata[n.font].parameters.xheight
+ local prev, next = n.prev, n.next
+ n.next, n.prev = nil, nil
+ local l = nodes.new("hlist")
+ l.list = n
+ local w, h, d = n.width, n.height, n.depth
+ if prev then
+ prev.next, l.prev = l, prev
+ else
+ box.list = l
+ end
+ if next then
+ l.next, next.prev = next, l
+ end
+ l.width, l.height, l.depth = h + d + o, w, 0
+ l.orientation = 0x003
+ l.xoffset, l.yoffset = o/2, -o/2
+ l.hoffset, l.doffset = h, d - o
+ n = next
+ else
+ n = n.next
+ end
+ end
+end
+\stopluacode
+\stopbuffer
+
+\typebuffer \getbuffer
+
+We will use some other magic that we won't discuss here which relates to handling
+scripts. For Hangul one needs to inject breakpoints and if needed also glue
+between characters. The script environment does this. We also need to bump the
+interline spacing. First we define a regular text helper and an auxiliary box.
+
+\startbuffer[1]
+\unexpanded\def\stripe#1%
+ {\hbox orientation 0 yoffset .2\exheight{\strut #1}}
+
+\newbox\MyVerticalBox
+\stopbuffer
+
+\typebuffer[1]
+
+Next we fill that box with some mix of text (I have no clue what, as I just
+copied it from some web page).
+
+\startbuffer[2a]
+\setbox\MyVerticalBox\hbox \bgroup
+ \NotoCJK
+ \startscript[hangul]%
+ \dorecurse{20}{通用规范汉字表 \stripe{test #1} }%
+ \unskip % remove last space
+ \stopscript
+\egroup
+\stopbuffer
+
+\typebuffer[2a]
+
+We then apply the \LUA\ magic to the result:
+
+\startbuffer[3a]
+\ctxlua{document.go_vertical(\number\MyVerticalBox)}
+\stopbuffer
+
+\typebuffer[3a]
+
+and finally assemble the result:
+
+\startbuffer[4a]
+\ruledvbox orientation 1 to \textwidth \bgroup
+ \setupinterlinespace[40pt]
+ \hsize .95\textheight
+ \unhbox\MyVerticalBox
+ \vfill
+\egroup
+\stopbuffer
+
+\typebuffer[4a]
+
+The result is shown in \in {figure} [fig:verticalmagic-1]. Of course this
+approach is not that user friendly but it just serves as example. In \CONTEXT\ we
+can follow a different route. First we define a new font feature. It is probably
+clear that we need some code elsewhere that does something useful with this
+information, but I will nos show this as it is rather \CONTEXT\ dependent.
+
+\startbuffer[2b]
+\definefontfeature
+ [vertical]
+ [vertical={%
+ orientation=3,%
+ down=.1,%
+ right=.1,%
+ ranges={%
+ cjkcompatibility,%
+ cjkcompatibilityforms,%
+ cjkcompatibilityideographs,%
+ cjkcompatibilityideographssupplement,%
+ cjkradicalssupplement,%
+ % cjkstrokes,%
+ cjksymbolsandpunctuation,%
+ cjkunifiedideographs,%
+ cjkunifiedideographsextensiona,%
+ cjkunifiedideographsextensionb,%
+ cjkunifiedideographsextensionc,%
+ cjkunifiedideographsextensiond,%
+ cjkunifiedideographsextensione,%
+ cjkunifiedideographsextensionf,%
+ }%
+ }]
+\stopbuffer
+
+\typebuffer[2b]
+
+We apply this feature to a font:
+
+\startbuffer[3b]
+\definefont
+ [NotoCJKvertical]
+ [NotoSansCJKtc-Regular*default,vertical @ 24pt]
+\stopbuffer
+
+\typebuffer[3b]
+
+\startbuffer[4b]
+\setbox\MyVerticalBox\hbox\bgroup
+ \NotoCJKvertical
+ \startscript[hangul]%
+ \dorecurse{20}{通用规范汉字表 \stripe{test #1} }%
+ \unskip
+ \stopscript
+\egroup
+\stopbuffer
+
+\typebuffer[4b]
+
+\startbuffer[5b]
+\ruledvbox orientation 1 to \textwidth \bgroup
+ \setupinterlinespace[40pt]
+ \hsize .95\textheight
+ \unhbox\MyVerticalBox
+ \vfill
+\egroup
+\stopbuffer
+
+\typebuffer[5b]
+
+The result is shown in \in {figure} [fig:verticalmagic-2]. Again this approach is
+not that user friendly but it already is a bit easier.
+
+\startplacefigure[reference=fig:verticalmagic-1,title={Some vertical magic using manipulations.}]
+ \getbuffer[1,2a,3a,4a]
+\stopplacefigure
+
+\startplacefigure[reference=fig:verticalmagic-2,title={Some vertical magic using fonts.}]
+ \getbuffer[1,2b,3b,4b,5b]
+\stopplacefigure
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-evolution.tex b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-evolution.tex
new file mode 100644
index 00000000000..730f4cc1b84
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-evolution.tex
@@ -0,0 +1,373 @@
+% language=us
+
+\startcomponent followingup-evolution
+
+\environment followingup-style
+
+% Yes, music is still evolving in qualitive ways ...
+%
+% Home Is - Jacob Collier with VOCES8
+%
+% and as long as there's interesting new music to run into I keep
+% doing thse kind of things.
+
+\startchapter[title={Evolution}]
+
+\startsection[title={Introduction}]
+
+The original idea behind \TEX\ is that of a relatively small kernel with (either
+or not system dependent) extensions. One such extension is the \DVI\ backend, and
+later \PDFTEX\ added a \PDF\ backend. Other extensions are \quote {writing to
+files} and \quote {writing to the output medium} using so called specials. This
+extension mechanism permits \TEX\ to support, for instance, color and image
+inclusion.
+
+The \LUATEX\ project started from \PDFTEX, including its extensions like font
+expansion, and combined that with (bi|)|directional typesetting from the, at that
+moment, stable \OMEGA\ variant \ALEPH. During the more than a decade development
+we integrated expansion in a more efficient way and limited directions to the
+four that made sense. The assumption that \UNICODE\ has the future lead to \UTF8
+being used all over the place.
+
+The \LUATEX\ variant opens up the internals using the \LUA\ extension language.
+The idea was (and still is) that instead if adding more and more hard coded
+solutions, one can use \LUA\ to do it on demand. So, for instance \OPENTYPE\
+fonts are supported by providing a font file reader but the implementation of
+features is up to \LUA. From \PDFTEX\ the graphic inclusions were inherited but
+an image and \PDF\ reading library provided a few more possibilities, for
+instance for querying properties. An important integral part of \LUATEX\ is the
+\METAPOST\ library, but apart from that one, the amount of libraries is kept at a
+minimum. That way we're free of dependencies and compilation hassles.
+
+With version 1.0 the functionality became official and with version 1.1 the
+functionality became more of less frozen. The main reason for this is that
+further extensions would violate the principle of using \LUA\ instead of hard
+coding solutions. Another reason is that at some point you have to provide a
+stable machinery for macro packages so that backward as well as forward
+compatibility over a longer period is possible. Also, because one can use \TEX\
+in (unattended) workflows sudden changes become undesirable.
+
+\stopsection
+
+\startsection[title={What next?}]
+
+Does it stop here? We have reached a reasonable stable state with \CONTEXT\
+\MKIV\ and can basically do what we want to do. However, during the more than a
+decade development of this \MKII\ follow up, the idea surfaced that we can go
+more minimal in the engine. Basically we can go back to where \TEX\ started: a
+core plus extension mechanism. What does that mean? First of all, there is the
+very efficient frontend: scanning macros, expanding them and constructing node
+lists, all within a powerful grouping mechanism. There is no reason to reconsider
+that. The core of the interface is also well documented, for instance in the
+\TEX\ book. We added some primitives to \LUATEX, but most of them are of no real
+importance to users; they make more sense to macro package writers.
+
+Original \TEX\ has a \DVI\ backend which is a simple representation of a page:
+characters and rules positioned on some grid. A separate program has to convert
+that into something for a printer. There is a basic extension mechanism that
+permits injection of so called specials that get passed to the external program
+so that for instance an image can be included. Given that \LUATEX\ is mostly used
+to generate \PDF, using so called wide fonts in a \UNICODE\ universe, a \DVI\
+backend is not that useful. In fact, one can then better use the faster \PDFTEX\
+program or just \ETEX\ or \TEX: use the best tool available for the job.
+
+The backend however can be left out and can be implemented in \LUA\ instead. In
+fact, most of the backend related code in \CONTEXT\ doesn't really use the
+\LUATEX\ backend features at all. The backend is only used to convert the page
+stream to a \PDF\ content stream, include images, include fonts and manage low
+level objects. Everything specific to \PDF\ is already done in \LUA. Of course
+this has a performance penalty but given the overhead already present in
+\CONTEXT\ it is bearable.
+
+Alongside the frontend the \METAPOST\ library plays an important role in
+\CONTEXT: integration between \TEX, \METAPOST\ and \LUA\ is pretty tight and a
+unique property of \CONTEXT. But, for instance the font reader library is no
+longer used. Also the interfacing to the \TEX\ Directory Structure was done in
+\LUA, originally for performance reasons as it reduced startup time by more that
+a second. For some of the frontend code (like hyphenation and par building) we
+can kick in \LUA\ variants too but there is not much to gain there. (I know that
+some users use them with success.)
+
+So, traditional \TEX\ can be summarized as:
+
+\starttyping
+tex core + dvi backend + tex extensions
+\stoptyping
+
+where the extension interface provide a few goodies. If we would have to summarize
+\LUATEX\ we could say:
+
+\starttyping
+tex core + dvi & pdf backend + tex extensions + lua callbacks
+\stoptyping
+
+The core interprets the input and does the typesetting. In order to be able to
+typeset \TEX\ only needs the dimensions of characters and information about
+spacing (which in principle are sort of independent) in math mode a few more
+properties are needed, like snippets that make large symbols. In text mode
+ligature and kerning information can be used too. However, in \LUATEX, where
+normally \OPENTYPE\ fonts are used, that information is provided from \LUA. This
+means that one can also think of:
+
+\starttyping
+tex core + basic font data + tex extensions + lua callbacks
+\stoptyping
+
+Compared to regular \TEX\ this is not that different, and it's what \CONTEXT\ can
+do with. So, it will be no surprise that when I wondered what \LUATEX\ 2.0 could
+be that a more minimalistic approach was considered: back to the basics.
+
+\stopsection
+
+\startsection[title={Roadmap}]
+
+Before I continue it is good to mention the following. One of the burdens that
+\CONTEXT\ users (and developers) carry is that the outside world likes putting
+labels on \CONTEXT, like \quotation {A macro package depending on \PDFTEX} in a
+time that we supported \DVI\ at the same level using a more of less generic
+driver model. The same is true for \MKIV, e.g.\ \quotation {\CONTEXT\ uses a lot
+of \LUA\ and moves away from \TEX} while in fact we provide a hybrid tool: you
+can use \TEX\ input (which most users do) but also \LUA\ (which can be handy) or
+\XML\ (which some publishers demand and definitely seems to be used by some
+\CONTEXT\ power users). A special one is \quotation {\CONTEXT\ is kind of plain
+\TEX, so you have to program all yourself.} Reality is that \CONTEXT\ is an
+integrated system, where \TEX\ and \METAPOST\ work together to provide a lot of
+integrated functionality. Because of \LUATEX\ development and the relation
+between an updated engine and the beta version of \CONTEXT, the impression can be
+that we have an unstable system. This strategy of parallel adaptation is the only
+way to really test of things work as expected. Because we have a rather fast
+update cycle normally users don't suffer that much from it.
+
+The core of whatever we follow up with is and remains \TEX, just because I like
+it. So, when I talk about a small core, I actually still talk about \TEX. The
+main reason is that it's way easier (and readable) to code some solutions in this
+hybrid fashion. A pure \LUA\ solution is no fun, maybe even a pain, and I have no
+use for it, but a pure \TEX\ solution can be cumbersome too. And \TEX\ input is
+just very convenient and for that one needs a \TEX\ interpreter. I would already
+have dropped out when \TEX\ was not part of the game: an intriguing, puzzling and
+powerful toy. And \METAPOST\ and \LUA\ add even more fun. So, I settle for a mix
+between three interesting languages. And, because I seldom run into professional
+demand for \LUATEX\ related support (or high end, high performance rendering),
+the fun factor has always been the driving force.
+
+All that said, for practical reasons, when we explore a follow up in the
+perspective of \CONTEXT, we will use the working title \LUAMETATEX\ instead.
+\LUAMETATEX\ has the current \LUATEX\ frontend, some \LUA\ libraries, but no
+backend. Gone are the font reader, image inclusion, \DVI\ and \PDF\ backend
+(including font inclusion) and the interface to the \TDS. Can that work? As
+mentioned, the font reader was already not used in \CONTEXT\ for quite a while. An
+alternative page stream builder was also in good working condition in \CONTEXT\
+when \LUATEX\ 1.08 was released and around \LUATEX\ 1.09 image inclusion was
+replaced (\PDF\ inclusion was already accompanied for a while by a \LUA\
+variant). Currently (fall 2018) \CONTEXT\ is able to completely construct the
+\PDF\ file which also meant font inclusion. However, it didn't make much sense to
+release that code yet because after all, there was minimal gain when using it
+with a full blown \LUATEX. Also, switching to this variant involved some runtime
+adaption of code which might confuse users. But above all, it needed more
+testing, and releasing something before an upcoming \TEX Live code freeze is a
+bad idea.
+
+During \LUATEX\ development a few times we got suggestions for additional
+features but merely looking at them already made clear that what works for
+someone in a particular case, can introduce side effects that make (for instance)
+\CONTEXT\ fail. And, how many folks keep \CONTEXT\ in mind? So, when \LUATEX\
+goes into maintenance mode, specific distributions could accept patches outside
+our control, which has the danger that a binary (suggesting to be \LUATEX)
+doesn't work with \CONTEXT. Of course we cannot change something ourselves either
+without looking around. And I'm not even bringing possible negative side effects
+on performance into the discussion here.
+
+When developing \LUATEX\ some ideas were dropped or delayed and these can now be
+explored without the danger of messing up the stable version. It has always been
+relatively easy to adapt \CONTEXT\ to changes so an (at least for now)
+experimental follow up can be dealt with too, but this time the concept of \quote
+{experimental} is really bound to \CONTEXT. When something is found useful (or
+can be improved) it can always (after testing it for a while) be fed back into
+\LUATEX, as long as it doesn't break something. I'll decide on that later.
+
+In the documentation of \TEX, when discussing the extension mechanism, Donald
+Knuth says:
+
+\startquotation
+The goal of a \TEX\ extender should be to minimize alterations to the standard
+parts of the program, and to avoid them completely if possible. He or she should
+also be quite sure that there's no easy way to accomplish the desired goals with
+the standard features that \TEX\ already has. \quotation {Think thrice before
+extending}, because that may save a lot of work, and it will also keep
+incompatible extensions of \TEX\ from proliferating.
+\stopquotation
+
+With the in the next chapters discussed reduction of backend and some frontend
+code, combined with hooks that can trigger callbacks, we try to come close to
+this objective. Now, the last sentence of this quote relates to stability and
+this is also a reason why we enter this new thread: the smaller the core is, the
+less subjected we are to change. Think of this: I haven't used \CONTEXT\ \MKII\
+in over a decade. A \PDFTEX\ format still gets generated but I have no clue if
+the engine has been changed in ways that make some code behave differently (it
+could also be the ecosystem related to that engine), but I assume it's still
+behaving the same. The same has to become true for stock \LUATEX\ and \MKIV\ and
+for \CONTEXT\ it can even become more true with \LUAMETATEX. We'll see.
+
+\stopsection
+
+\startsection[title={Experiments}]
+
+This (still sort of) prototype of what \LUAMETATEX\ could be boils down to a much
+smaller binary, and not that much more \LUA\ code on top of what we already have.
+There are no longer dependencies on third party code, apart from \LUA\ (\type
+{pplib} is tuned for \LUATEX\ and permanent part of the code base). Performance
+wise the backend of the experimental version makes a run upto 5\% slower than
+when using a native backend (on processing the \LUATEX\ manual) but history has
+learned that we can gain some of that back in due time. Performance also depends
+a bit on the properties of the document. Interesting is that better control over
+the output showed that \PDF\ output of the mentioned manual was a bit smaller
+(but that might change). \footnote {In the meantime the experimental version can
+process the \LUATEX\ manual 5\endash10\% faster and the result is still smaller.}
+
+The experiments actually started already years ago with no longer using the font
+loader. It sort of went this way:
+
+\startitemize
+\startitem
+ Stepwise \CONTEXT\ functionality started using a combination of \TEX\ and
+ \LUA\ code and we got an idea of what was needed. The most demanding part
+ was support for fonts.
+\stopitem
+\startitem
+ Font handling was done in \LUA\ because it's flexible which is what \TEX ies
+ are accustomed to. The \OPENTYPE\ and \PDF\ standards would not be called
+ standards if some implementation was impossible and so far we're ok. (Some
+ more script support will be provided in future versions.)
+\stopitem
+\startitem
+ We stopped using the fontforge font loader but use one written in \LUA\
+ instead. One reason for this was that when variable fonts showed up we wanted
+ to support it in \CONTEXT\ right from the start (not that there has been much
+ demand). The same is true for fonts using color (like emoji). Also, fighting
+ the built|-|in \FONTFORGE\ heuristics was hard.
+\stopitem
+\startitem
+ The (large and dependent on \CPLUSPLUS) poppler library used for \PDF\
+ embedding has been replaced by a small lightweight library in pure \CCODE.
+ This was triggered at a chat during a bacho\TEX\ meeting.
+\stopitem
+\startitem
+ The hard coded \PDF\ inclusion can be swapped with a \LUA\ based one so that
+ we can for instance filter the page stream. We already had a hybrid solution
+ in \CONTEXT\ anyway for other reasons (merging annotations, layers,
+ bookmarks, etc.).
+\stopitem
+\startitem
+ The page stream constructor got a (shipout and xforms) by a \LUA\ variant,
+ but I decided not to make that an independent option in stock \LUATEX\ with
+ \CONTEXT\ \MKIV, although for a while I had the option \type {--lmtx} for
+ activating that experimental code.
+\stopitem
+\startitem
+ Then of course bitmap image inclusion had to be done by \LUA\ code, in order
+ to see if we can get rid of another external dependency as some of these
+ libraries get frequent updates while in practice we only use a very small
+ subset of functionality. Indeed this was possible. \footnote {I have a pure
+ \LUA\ parser for \PDF\ too, so at some point that might get included in the
+ \CONTEXT\ code base.}
+\stopitem
+\startitem
+ With some effort (deciphering specs and such) the font inclusion could also
+ be done by a \LUA. This was made possible by the fact that we already had
+ support for variable fonts. More tricks are possible and will be explored.
+\stopitem
+\startitem
+ Finally the \PDF\ file construction and \PDF\ object management had to be
+ implemented. This was actually the easiest part.
+\stopitem
+\stopitemize
+
+Performance wise the \LUA\ font loader is faster than the built in one. The same
+is true for \PDF\ inclusion but in practice that is unnoticeable. Bitmap
+inclusion is currently slower for interlaced images (seldom used in print) and
+just as efficient for other types. The page stream constructor is definitely
+slower but this is compensated by the faster font inclusion and \PDF\ file
+construction. Of course it all depends on the kind of content, but these are the
+observation as of fall 2018. Anyway, they were enough reason to continue this
+experiment.
+
+One thing to keep in mind is that the smaller the binary and the less code paths
+we have, the better future performance might be. Computers are not becoming much
+faster for single thread processes like \TEX, so the less we jump around code
+space (memory) the better it probably is for \CPU\ caching (as caches are not
+growing much either).
+
+\stopsection
+
+\startsection[title={Conclusion}]
+
+Normally when writing this kind of code I make sure that I can enable such new
+mechanisms on top of others but at some point one has to decide how to really
+integrate them. For instance, we can do font inclusion independent of \PDF\
+generation or page stream construction independent of \PDF\ generation and|/|or
+font inclusion but in the end that doesn't make sense and makes the code base a
+bit of a mess. So, this is how it will go.
+
+Stock \LUATEX\ with \MKIV\ will use the normal backend but probably there might
+be an option to overload the built|-|in image inclusion so that one can avoid the
+abortion of a run in case of problematic images. Complete \PDF\ file
+construction, which then also includes page stream construction, font embedding
+and object management might be available as option for \MKIV\ with \LUATEX\ 1.10
+(for a while) but will be default when using \LUAMETATEX. When we move on \LMTX\
+support might evolve in more sophisticated trickery. \footnote {A few months
+later I decided that this made no sense, and that it was cleaner to just leave
+that approach for \LMTX\ only. So, now both engines use different code
+exclusively.}
+
+Once tested a bit in real documents experimental code will end up in the
+distribution. That code can then be turned into production code (read: cleaned up
+and reshuffled a bit). We can streamline the engine code base: strip the
+components that are not needed any more, remove some obsolete features, optimize
+the code, strip some functions from \LUA\ libraries, rename some helpers, and
+finally add some documentation. There are some plans to extend \METAPOST\ so also
+things can get added. Concerning the \LUA\ interface it means that \type
+{slunicode} is removed, the embedded socket related \LUA\ code goes external (but
+the library stays), the font loader gets removed, the \type {img} library goes
+away, no longer \PNG\ libraries are embedded, synctex is stripped out (but the
+fields in nodes stay or get extended). \footnote {Much later I also decided to
+remove the zip file reader library.} The resulting binary will be much smaller
+and the code base more independent and smaller too. In the process \LUAJIT\
+support might be dropped as well, simply because it no longer is in sync with
+stock \LUA, but that also depends on how complex long term maintenance becomes.
+\footnote {As we will see in following chapters, indeed support for \LUAJIT\ has
+been dropped while \LUA\ got upgraded to 5.4.}
+
+Because such a stripped down binary is no longer what got presented as \LUATEX\
+version~1, it will basically become \LUATEX\ version 2, but then we have the
+problem that its binary name clashes with the original. This is why it will be
+run as \typ {luametatex}. For \CONTEXT\ it's not that relevant as it will run on
+both \LUATEX\ 1.10 and its lean and mean successor. I might also provide a plain
+\TEX\ (read: generic) version but that is to be decided because it probably
+doesn't make much sense to spend time on it. As usual we will test this within
+the \CONTEXT\ beta program. The good thing is that it doesn't interact with
+\LUATEX, so that other macro packages are not affected. Another side effect can
+be that we uncover issues with \LUATEX\ 1.10 and that we can experiment with some
+improvements that we feed back into the parent.
+
+At the \CONTEXT\ end of this there are some plans to extend the export, maybe
+improve already present \PDF\ tagging (if found useful), add some more input
+(xml) manipulations, and maybe extend (virtual) font handling a bit, now that we
+no longer are bound to the currently used packet model. Contrary to what one
+might expect this is not really dependent on the engine.
+
+How do we proceed? As with the transition from \MKII\ to \MKIV, it will all
+happen stepwise. This means that for a while the code base will be a bit hybrid
+but at some point it might be partially split to make things cleaner, not that I
+expect many fundamental differences (certainly not in the front|-|end). This
+dualistic approach means more work but also makes that we keep a working
+\CONTEXT. We also need to keep an eye on for instance generic commands as used in
+tikz: we can't drop them so we emulate them (so far with success). As the time of
+this writing, begin November 2018, the \CONTEXT\ test suite can be processed in
+\LMTX\ mode without problems so I'm confident that it will work out ok. The next
+chapter describes the results of how we did the above in more detail.
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-feedback.tex b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-feedback.tex
new file mode 100644
index 00000000000..d77ef302c9b
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-feedback.tex
@@ -0,0 +1,306 @@
+% language=us
+
+\startcomponent followingup-feedback
+
+\environment followingup-style
+
+\logo [AMD] {AMD}
+\logo [INTEL] {Intel}
+
+\startchapter[title={Feedback}]
+
+\startsection[title={Introduction}]
+
+As \LUATEX\ 1.10 is basically frozen in terms of functionality not much can or
+will be added. But it made sense to some of the (small) improvements that were
+made in \LUAMETATEX\ got feedback to \LUATEX\ (or will be at some point). Because
+we are also experimenting, there can be a delay. \footnote {Later chapters
+mention a few more possible extensions.}
+
+Of course the question is \quotation {Should we feedback (retrofit) at all?}. I'm
+still not sure about it. There should be a good reason to do it because it can
+harm stability of the original. At some point \CONTEXT\ can default to the follow
+up in which case testing the original becomes more difficult for specific
+features. I never ran into (useful) demands for extensions so retrofit can have a
+low priority.
+
+Another factor is that when distributions start adding stuff to stock \LUATEX\ on
+top of what is our default (after all isn't that what happens with open source
+projects), it makes not much sense to look back and retrofit new functionality,
+because there is not much change that we will use such a variant ourselves and we
+could introduce errors in the process. Providing bloatware is not our objective.
+
+Related to this is the question if we should always go into \LMTX\ mode and I'm
+no longer sure if we shouldn't do that. We can use plain \TEX\ with the regular
+\LUATEX\ backend and just forget about some generic framework. The danger of it
+backfiring is just too large. It is a waste of time and will keep us back.
+
+One reason for a dual mode is that it made possible some timings in order to
+determine bottlenecks. I did some rough tests and that is enough to get the
+picture. Take this document:
+
+\starttyping
+\starttext
+ \dorecurse
+ {1000}
+ {\samplefile{sapolsky} {\bf\samplefile{sapolsky}}\par}
+\stoptext
+\stoptyping
+
+Using regular \LUATEX\ this takes on an \INTEL\ i7-3840 mobile processor about
+9.3 seconds while \LUAMETATEX\ needs 11.2 seconds, so we loose time. This is
+because we have only text so the native backend wins on piping out the page
+stream. On my domotica fitlet with an low power \AMD\ A10 processor running
+\LINUX\ the runtime goes from 25.4 seconds to 27.8 seconds, so again a slow down.
+
+But this is not a typical document! Add a bit more spice and the numbers reverse.
+For processing the \LUATEX\ manual stock \LUATEX\ takes 12.6 seconds on the
+\INTEL\ and \LUAMETATEX\ needs 12.4 seconds. On the \AMD\ runtime goes from 35.1
+seconds down to 32.8 seconds. So here we win some.
+
+These are rough timings and a few weeks later we go these timings on the \INTEL:
+\footnote {On the more modern gaming laptop of a nephew we measured half these
+numbers.}
+
+\starttabulate[|l|c|c|c|]
+\BC engine \BC backend \BC runtime \BC \LUAJIT\ vm \BC \NR
+\HL
+\NC \LUATEX\ 1.10 \NC normal \NC 12.4 \NC 9.9 \NC \NR
+\NC \LUATEX\ 1.10 \NC lmtx \NC 12.7 \NC 9.8 \NC \NR
+\NC \LUAMETATEX\ 2.00 \NC lmtx \NC 12.2 \NC 9.3 \NC \NR
+\stoptabulate
+
+Because we have more \LUA\ code active, we pay a price with \LMTX\ but not on
+\LUAMETATEX\ (as of now, later we will see a performance bump). The gain when
+using the \LUAJIT\ virtual machine is more noticeable. And, there is probably
+some more to gain. In case you wonder why this matters: think of the low power
+\AMD\ processor. When we have to replace computers we can consider using low
+power ones, with weaker processors, less memory, and less cache. For the record:
+I use cross compiled \MINGW\ binaries on windows (they are quite a bit faster
+than native windows binaries). And the binaries are less than 3MB (small files
+and less resources are nice when running on remote file systems).
+
+This all indicates that we have no real reason to stick to a mixed approach: if we
+want we can just switch to always \LMTX\ and never look back.
+
+\stopsection
+
+\startsection[title={Expressions}]
+
+When writing an article that involved using a \type {\numexpr} it struck me that
+we should have a proper integer division. Just compare these:
+
+\startbuffer[1]
+\the\numexpr 13/2\relax
+\stopbuffer
+
+\startbuffer[2]
+\scratchcounter13 \divide\scratchcounter 2 \the\scratchcounter
+\stopbuffer
+
+\typebuffer[1]
+
+and
+
+\typebuffer[2]
+
+This gives {\bf \inlinebuffer[1]} and {\bf \inlinebuffer[2]}. We now also have:
+
+\startbuffer[3]
+\the\numexpr 13:2\relax
+\stopbuffer
+
+\typebuffer[3]
+
+which gives {\bf \inlinebuffer[3]}. I considered using a double slash (as in
+\LUA) but using a colon is easier. Of course those who make that an active
+character are probably toast. This is an easy patch but it's hard to predict
+possible side effects outside \CONTEXT.
+
+\stopsection
+
+\startsection[title={Looking ahead}]
+
+Sometimes you want to look ahead and act upon the presence of a specific
+character. Implementing that in pure \TEX\ primitives is no big deal, but
+especially when you want to ignore leading spaces it leads to rather verbose code
+when tracing is enabled. Out of curiosity I played with a primitive that can help
+us out. Although there is also a performance gain, in practice one will not
+notice that unless such a feature is used millions of times, but in that case the
+gain is noise compared to the rest of the run.
+
+\startbuffer
+\def\foo{\futureexpand/\fooyes\foonop}
+\def\fooyes/#1/#2{[#1:#2]}
+\def\foonop #1{(#1)}
+
+\foo/yes/{one}\quad
+\foo {two}
+\stopbuffer
+
+\typebuffer
+
+We either expand \type {\fooyes} or \type {\foonop}, depending on the presence
+of a \type {/} after \type {\foo}. So, the result is:
+
+{\tttf\getbuffer}
+
+The next examples demonstrates two variants. The second one doesn't inject spaces
+back into the stream.
+
+\startbuffer
+\def\f<{\futureexpand/\y\n}
+\def\y/#1/{#1}
+\def\n {}
+
+(\f</yes/>)\quad
+(\f< >)
+\stopbuffer
+
+\typebuffer
+
+Watch the space in the \type {\n} case.
+
+{\tttf\getbuffer}
+
+\startbuffer
+\def\f<{\futureexpandis/\y\n}
+\def\y/#1/{#1}
+\def\n {}
+
+(\f</yes/>)\quad
+(\f< >)
+\stopbuffer
+
+\typebuffer
+
+This time the space is not injected (\type{is} is short for ignore spaces).
+
+{\tttf\getbuffer}
+
+I will probably use this one in \CONTEXT, but as said, not for performance
+reasons but because it reduces code and therefore tracing. \footnote {In the
+\CONTEXT\ code base there are several places where less code takes precedence
+over efficiency. But in all cases extensive tests were done to see if it made a
+dent in practical performance.}
+
+\stopsection
+
+\startsection[title={Checking numbers an dimensions}]
+
+The \CONTEXT\ user interface often uses parameters that take keywords as well as
+a number or dimension. In practice it has never been an issue to check for that but
+there are a few cases where we'd like to be a bit more flexible.
+
+\startbuffer
+\doifelsenumber{123999999999999999}YN
+\doifelsenumber {123}YN
+\doifelsenumber {A}YN
+\doifelsenumber {\char123}YN
+\doifelsenumber {\toks123}YN
+\doifelsenumber{123\scratchcounter}YN
+
+\doifelsedimension{123999999999999999pt}YN
+\doifelsedimension {123pt}YN
+\doifelsedimension {A}YN
+\doifelsedimension {\char123}YN
+\doifelsedimension {\toks123}YN
+\doifelsedimension {123\scratchdimen}YN
+\stopbuffer
+
+\typebuffer
+
+This typesets:
+
+\startpacked
+\getbuffer
+\stoppacked
+
+especially the \type {123\scratch...} checking is tricky. For that reason we now
+have two new built|-|in checkers. Again, performance is not one of the arguments,
+because these checks are not much faster than what we have already, they are just
+a bit more robust for weird cases. A possible use of the primitives is:
+
+\starttyping
+\ifdimen123\or
+ yes
+\else % or \or
+ no
+\fi
+\stoptyping
+
+and:
+
+\starttyping
+\ifnumber123\or
+ yes
+\else % or \or
+ no
+\fi
+\stoptyping
+
+When a valid number or dimension is gobbled, the value pushed in the branches
+is~1, and when an error is encountered the value~2 is pushed. Deep down we have
+just an \type {\ifcase} and by not using the value zero we nicely skip the
+invalid code. It might look a bit weird but we need a sentinel for the number
+(and the \type {\or} serves as such, without introducing strange new constructs.
+We'll see if we keep it (as testing must prove its usefulness).
+
+\stopsection
+
+\stopsection
+
+\startsection[title={Comparing tokens}]
+
+The following code compares (for instance) two strings:
+
+\starttyping
+\def\thisorthat#1#2%
+ {\edef\one{#1}
+ \edef\two{#2}
+ \ifx\one\two
+ this%
+ \else
+ that%
+ \fi}
+
+\thisorthat{foo}{bar}
+\stoptyping
+
+but this looks a bit cleaner (in a trace):
+
+\starttyping
+\def\thisorthat#1#2%
+ {\iftok{#1}{#2}%
+ this%
+ \else
+ that%
+ \fi}
+
+\thisorthat{foo}{bar}
+\stoptyping
+
+It's not that much faster (unless one uses it a real lot) as similar things have
+to happen to get the test to work. But the nice things of this checker is that it
+works with token registers and macros too. But in order use it in relevant places
+in \CONTEXT\ I would have to adapt quite some code. This could actually be a
+reason for a \MKIV\ freeze and \LMTX\ code base (as with \MKII). The question is:
+does it pay off?
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
+
+% \newbox\mybox \setbox\mybox\ruledhbox{\blackrule[width=3cm,height=1cm]}
+
+% \dontleavehmode\copy\mybox\quad \ruledhbox{\copy\mybox} \blank[3*line]
+% \boxxmove\mybox 10pt
+% \dontleavehmode\copy\mybox\quad \ruledhbox{\copy\mybox} \blank[3*line]
+% \wd\mybox\dimexpr\wd\mybox+10pt\relax
+% \dontleavehmode\copy\mybox\quad \ruledhbox{\copy\mybox} \blank[3*line]
+% \boxymove\mybox 10pt
+% \dontleavehmode\copy\mybox\quad \ruledhbox{\copy\mybox} \blank[3*line]
+% \ht\mybox\dimexpr\ht\mybox+10pt\relax
+% \dontleavehmode\copy\mybox\quad \ruledhbox{\copy\mybox} \blank[3*line]
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-introduction.tex b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-introduction.tex
new file mode 100644
index 00000000000..c4a5920bdf4
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-introduction.tex
@@ -0,0 +1,104 @@
+% language=us
+
+\startcomponent followingup-introduction
+
+\environment followingup-style
+
+\startchapter[title={Introduction}]
+
+This document, the fifth in a series, describes the follow up project on
+\CONTEXT\ \MKIV\ & \LUATEX\ which carries the working title \CONTEXT\ \LMTX. This
+four letter acronym represents \LUA, \METAPOST\ and \TEX, and if you want you can
+see the last character representing \XML, as that has been an integral part of
+\CONTEXT\ for a long time. But the \quote {x} can also be found in \quote
+{experimental}, \quote {extreme}, \quote {experience} and \quote {extravagant},
+so take your choice.
+
+Of course \CONTEXT\ is and will be a typesetting system using the \TEX\ language
+and typesetting core, but a rather substantial amount of the functionality is a
+hybrid of \TEX\ macros and \LUA\ code. The built|-|in graphic support is driven
+by \METAPOST, but there we also use \LUA\ as an extension language. The \LUA\
+machinery is used for alternative input and handling data too. The same is true
+for \XML, \SQL, \CSV, \JSON, etc.
+
+The output from \CONTEXT\ is normally \PDF\ and \MKIV\ doesn't even enable \DVI\
+output. Mid 2018 I started experimenting with a backend that no longer used the
+one provided by the engine. After all, we only used page stream building, font
+embedding and bitmap inclusion and all other features were always done in \LUA.
+The experiments also concerned a \METAPOST\ and \LUA\ backend. Those familiar
+with \CONTEXT\ know that there is already an export feature which till now runs
+in parallel with the \CONTEXT\ \PDF\ backend (it started as a kind of joke but in
+the end was seen as relevant and kept and maybe so some point I will rewrite that
+code).
+
+The idea behind \CONTEXT\ \LMTX\ is that we will use a minimalist engine. Being
+minimalist also means that probably only \CONTEXT\ will use it and therefore no
+other package will be affected by further experiments, although at some point a
+sort of general low level layer might be provided. The frontend is mostly the
+same as \LUATEX\ 1.1 but the backend and related code is gone and|/|or different.
+Libraries have (and are) being cleaned up and reorganized too. At least for a
+while, \CONTEXT\ will work on \LUATEX\ 1.1 (stable) as well as its (experimental)
+follow up, where the follow up will evolve over a few years and be tested in the
+usual \CONTEXT\ (garden) beta setting. The next chapters will explain this in
+more detail.
+
+Just to be clear I repeat: \LUATEX\ 1.1 will be supported by \CONTEXT\ and
+maintained as usual, including binaries generated on the \CONTEXT\ garden. We've
+invested many years in it and it serves its purpose well, but our experiments
+will happen in its follow up, so that it doesn't affect stable workflows. Of
+course there have been (and probably are) bugs in \LUATEX\ but the engine could
+be used pretty well right from the start with \CONTEXT. The same will be true for
+the follow up.
+
+One of the ideas of the follow up is to provide a combination of a stable engine
+independent of libraries with a relative simple compilation setup and a macro
+package that has proven to exploit a mix of \TEX, \METAPOST\ and \LUA. As a side
+effect I can explore some postponed ideas. Of course there can be valid reasons
+to move to the successor sooner. In that case we might create a stable snapshot
+of \MKIV\ as was done with \MKII. As to be expected in \CONTEXT, the user
+interfaces won't change nor will the functionality, but there will be two code
+paths, one for \MKIV\ and one for \LMTX. There will also be new functionality in
+\CONTEXT\ that is only available in \LMTX. So, eventually we expect all users to
+migrate.
+
+In the beginning of december 2018 most of the work was done and users involved in
+development could start testing. By the end of the year a reasonable stable state
+was reached. In 2019 the code base was further overhauled and libraries got
+upgraded. The code base became smaller and compilation easier, smoother and much
+faster. Eventually the source code (now some 11MB uncompressed and 3MB
+compressed) will be part of the \CONTEXT\ distribution, so that we have a
+complete package (also in the archival sense).
+
+The next chapters discuss the process and choices that were made. The chapters
+were written in order so later chapters can amend earlier ones. Consider it a
+history, and one cannot cheat by patching history. In some cases footnotes were
+added to earlier chapters when writing later ones. It's not a manual! Reported
+typos (for sure there are many) will be fixed but changes in later versions of
+the follow discussed here will not end up in this document.
+
+This document is dedicated to Wolfgang Schuster, who has been instrumental in the
+transition from \MKII\ to \MKIV, and often baffles me with his knowledge of the
+(even obscure bits) of the \CONTEXT\ internals. Without him checking the code
+base, fundamental changes like those that are and might get introduced in this
+follow up are impossible.
+
+I want to thank Alan Braslau who accompanies me on this journey and patiently
+compiles the lot for some platforms. He, Thomas Schmitz and Aditya Mahajan are
+examples of power users who also are early adopters of something new like this
+and are willing to take the risks. And of course there is Mojca Miklavec without
+whose enthusiasm and optimism developments like this would never take place. In
+the meantime Luigi Scarso made sure that the (frozen) \LUATEX\ code base served
+existing users. It is hard to tell how users experience the transition: there are
+no that many issues reported which can be a good or bad sign. We will see.
+
+\blank[2*big]
+
+\startlines
+Hans Hagen
+PRAGMA ADE, Hasselt NL
+August 2018\enspace\endash\enspace May 2019
+\stoplines
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-logging.tex b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-logging.tex
new file mode 100644
index 00000000000..e82df3c04ef
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-logging.tex
@@ -0,0 +1,58 @@
+% language=us
+
+\startcomponent followingup-logging
+
+\environment followingup-style
+
+\startchapter[title={Logging}]
+
+\startsection[title={Introduction}]
+
+In \CONTEXT\ we have quite some logging enabled by default and even more when
+you enable trackers. Most logging is done with \LUA, which is quite efficient.
+Information from the \TEX\ machinery follows a different path and one reason
+for that is that it often happens on a character (or small strings) basis.
+
+The runtime of a job is, in spite of what one may expect, also dependent on the
+speed of the console: what fonts are used (there can be font features being
+applied), is the output buffered, and with what delays, how large is the history,
+etc. When more complex fonts arrived I found out that on \OSX\ generating a
+format was impacted by seconds. When on \MSWINDOWS\ the normal console was used
+its character|-|by|-|character flushing made it sluggish, and on \LINUX\ it
+depended on the font, kind of console, delays, etc. Lucky me, the \SCITE\ editors
+log pane beats them all. \footnote {I use the \LINUX\ subsystem on \MSWINDOWS\
+for cross compiling \LUATEX, and with the advent of that subsystem the regular
+console was also rewritten so most of the delays are gone now.}
+
+At the \TEX\ end a few decades of coding has made the system also complex.
+\footnote {Interfaces like that are only partly defined by \TEX\ and left to the
+implementation.} Each string goes through a mechanism that checks with line
+ending to apply and where to cut off lines exceeding a preset maximum length,
+where \LUATEX\ also needs to take \UTF\ into account. Some characters can
+(optionally) be escaped with \type {^^} and occasionally the line length gets
+reset by explicit newline commands.
+
+In \CONTEXT\ already for a long time we always used an (at least) 10K line length
+and disabled output escaping. We have consoles that can handle long lines and
+live in an \UTF\ world so escaping makes no sense. And, when \OPENTYPE\ features
+get applied random line breaks can interfere badly. Just in case one wonders what
+happens with so called \type{null} characters: as all goes through \CCODE\
+anyway, such a character just terminates a string. Therefore the line length
+limitations have been removed and the line|-|ending substitution be optimized. In
+principle this gives simpler codes and less overhead.
+
+The log is not always compatible with \LUATEX. For instance we output more details
+about node lists. This is natural because we have more subtypes and these can
+provide additional information (clues) when debugging \TEX\ code.
+
+In \LUATEX\ the error handling is already such that some can be delegated to
+\LUA, and later I will look into more isolation. But, error handling is quite
+interwoven in the code and I don't want to mess up the original concept too much.
+\footnote {Indeed the error handling was redone in such a way that we now have an
+even better isolation.}
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-lua.tex b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-lua.tex
new file mode 100644
index 00000000000..f0f3350a3e0
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-lua.tex
@@ -0,0 +1,151 @@
+% language=us
+
+\startcomponent followingup-lua
+
+\environment followingup-style
+
+\startchapter[title={\LUA}]
+
+\startsection[title={Move to 5.4}]
+
+Another experiment concerned testing \LUA\ 5.4 which looks like a minor update in
+terms of new functionality but has some consequences. By now the old module model
+is even more deprecated and compatibility mode no longer makes much sense. As a
+consequence we now need to adapt the way libraries are loaded (and we use global
+ones) and a few other low level calls had to be adapted. This is no real issue
+and once that was done, I found out that the bit32 module was even more obsolete
+so I decided to get rid of it. We already have a bit32 replacement in \CONTEXT\
+so I had to enable that. As \CONTEXT\ doesn't need compatibility mode it was no
+problem to drop that too.
+
+The biggest changes in 5.4 are under the hood: some optimized byte code and a new
+generational garbage collector. I did a few runs and a 12.4 seconds run on the
+manual now dropped to around 12.1 and given that we spend (probably) more than
+half the time in \LUA\ that means some 5\% gain in performance. This is still
+more than the 9.6 seconds that \LUAJIT\ needs but it looks like every \LUA\
+release gains a bit and I'm pretty sure that there is more to gain. \footnote {In
+the meantime there are experiments in 5.4 with \type {<const>} directives which
+might have advantages.}
+
+An interesting experiment was to disable the automatic string to number
+conversion when a number is expected but a string is needed. So far I only had to
+adapt two lines of code in the in the meantime considerable amount of \LUA\ code
+that comes with \CONTEXT.
+
+\stopsection
+
+\startsection[title={No more \LUAJIT}]
+
+One thing I had to consider was the future of \LUAJIT. This project is sort of
+stalled and will not follow \LUA\ development. Now, to some extend we can deal
+with this but with the faster \LUA\ 5.4 around the corner, the limitations of
+\LUAJIT\ with respect to loading large tables, as well as the fact that we need a
+patched hash function to get an advantage over regular \LUA\ anyway, it makes
+sense to drop it in \LUAMETATEX. After discussing this with Alan, who crunched
+numbers in order to make impressive graphics with \METAPOST, we came to the
+conclusion that we should not overestimate the benefits. There is still a gain
+but removing the need to support both could also makes it possible to improve
+existing code (although one should not expect too much from that; it's more a
+matter of convenience for me). Also, for as long as have \LUAJITTEX\ that is
+still an option when one has to squeeze out every second.
+
+A valid question is if ditching \LUAJIT\ will harm users. The answer to this
+depends on the kind of documents that you process. Given decent programming, you
+can gain quite a bit of runtime, but on the average the difference is not that
+large. There is for instance always the overhead of callbacks and crossing the so
+called \CCODE\ boundary that has an impact.
+
+\stopsection
+
+\startsection[title={Performance}]
+
+At the time of writing this Thomas Schmitz was wondering if there was a
+significant difference in runtime between the table mechanisms and especially
+natural tables and extreme tables. Some test demonstrated that extreme tables
+were best for his case. That case concerned generating about 400 pages of tables
+from \XML\ files, including some juggling of data in \LUA. The bottleneck in that
+document can be roughly simulated with the following test. We assume one pass
+over the table but in practice there are upto four, but only the last one has
+frames. So, the test concerns 80.000 (400 pages with 40 rows of 5 columns) calls
+to \type {\framed}.
+
+% 400 pages : 5 cells * 40 rows = 80000 framed
+
+\starttyping
+1 \hpack{\framed {oeps}}
+2 \hpack{\framed[frame=off] {oeps}}
+3 \setupframed[frame=off] \hpack{\framed {oeps}}
+4 \hpack{\framed[frame=on] {oeps}}
+5 \setupframed[frame=on] \hpack{\framed {oeps}}
+6 \hpack{\framed[frame=closed]{oeps}}
+7 \setupframed[frame=closed] \hpack{\framed {oeps}}
+\stoptyping
+
+\starttabulate[|c|c|c|c|]
+\HL
+\BC sample \BC luatex & mkiv \BC luajittex & mkiv \BC luametatex & lmtx \BC \NR
+\HL
+\NC 1 \NC 17.3 \NC 16.8 \NC 13.5 \NC \NR
+\NC 2 \NC 17.8 \NC 17.2 \NC 14.0 \NC \NR
+\NC 3 \NC 17.3 \NC 16.8 \NC 13.3 \NC \NR
+\NC 4 \NC 17.9 \NC 17.4 \NC 13.7 \NC \NR
+\NC 5 \NC 17.4 \NC 17.1 \NC 13.3 \NC \NR
+\NC 6 \NC 17.4 \NC 16.8 \NC 12.9 \NC \NR
+\NC 7 \NC 16.4 \NC 16.0 \NC 12.6 \NC \NR
+\HL
+\stoptabulate
+
+Even if we add the usual .1 second interval around these values it will be clear
+that we gain enough not to worry about the loss of \LUAJIT, also because the gain
+is not in the \LUA\ part only. A nice consequence of this is that when we replace
+the \CPU's in a server with low power ones that perform 25\% less, we can
+compensate that by using \LMTX. \footnote {There's still room for improvement,
+because mid July 2019 we're at 12.9, 13.2, 12.9, 13.5, 13.0, 12.5 and 12.2
+seconds or less. But don't expect too many miracles.}
+
+When wrapping this up, the \LUATEX\ manual processed with \LMTX\ took slightly
+less than 11.9 seconds, compared to a normal run of 12.6 seconds, so we're
+gaining some there too. And just after I wrote this we went down to 11.7 seconds
+by (as experiment) changing the \LUA\ virtual machine dispatcher, so there is
+still some to gain. In the energy saving fitlet with small amd processor
+processing the manual with stock \LUATEX\ takes about 37 seconds, but 33.5 with
+\LMTX\ so here also we're not off worse.
+
+\stopsection
+
+\startsection[title={Modules}]
+
+Right from the start \LUATEX\ had some extra libraries linked in: \type {md5}
+(for hashing), \type {lfs} (for accessing file properties), \type {slunicode}
+(for basic \UTF\ handling), \type {gzip} and \type {zlib} (for zipping files and
+streams), \type {zip} (for accessing zip files) and \type {socket} (for
+communicating other than with files).
+
+In \LUAMETATEX\ the not so useful \type {slunicode} library was removed pretty
+early but the others stayed around. The more backend specific \type {img} and
+\type {pdf} libraries went away too, as did the (already not used) \type
+{fontloader} library. The \type {kpse} library is also gone, as we do those
+things in \LUA. The \type {epdf} library was kept. A couple of libraries were
+added, like \type {sha2}, \type {basexx}, and \type {flate}, plus a few handy
+helper libraries that are still experimental and therefore not mentioned here.
+
+The \type {flate} library is also an experiment but will replace the \type {gzip}
+and \type {zlib} libraries. Currently these use \type {libz} but \type
+{libdeflate} will be the low level replacement once it support streams and is
+already used for \type {flate}. The \type {md5} library has been redone using
+utility code \type {pplib}, as \type {sha2} does. The type {basexx} library also
+falls back on utility code form \type {pplib} (that code is actually
+independent).
+
+The \type {lfs} code has been replaced by a variant that omits features not
+common to the platforms and with a iterator that permits much faster directory
+scans and has a few more helpers. It is not compatible but we kept the name
+because of legacy usage. I might strip the socket code to what is actually used,
+but on the other hand: don't touch what works well. The original code doesn't
+change that much anyway.
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-mp.tex b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-mp.tex
new file mode 100644
index 00000000000..22e8e8356dc
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-mp.tex
@@ -0,0 +1,166 @@
+% language=us
+
+\registerctxluafile{mlib-scn}{}
+
+\startcomponent followingup-mp
+
+\environment followingup-style
+
+\startchapter[title={\METAPOST}]
+
+\startsection[title={Introduction}]
+
+Relatively late in the followup I started wondering about what to do with \MPLIB.
+Alan Braslau is working on the \type {luapost} module and we discuss handy
+extensions written in \LUA\ and \METAPOST\ code but who knows what more is
+needed. Some ideas were put on delay but it looked like a good moment to pick up
+on them. One problem is that when we play with the \MPLIB\ code itself in
+\LUAMETATEX, the question is how to keep in sync with the official library. In
+this chapter I'll discuss both: keeping up with the official code, and keeping
+ahead with ideas.
+
+\stopsection
+
+\startsection[title={The code base}]
+
+The \MPLIB\ code is written in \CWEB\ and lives in files with the suffix \type
+{w}. These files need to be converted to \type {c} and \type {h} files, something
+that is done with the \type {ctangle} program. To avoid that dependency I just
+took the \CCODE\ files from \LUATEX, but I had to apply a few patches (to get rid
+of dependencies). Now, it is a fact that \METAPOST\ doesn't really develop fast and
+in principle a diff could identify the changes easily. So, why shouldn't I also
+start experimenting with \MPLIB\ itself in the follow up? It's easy to merge
+future changes (in both directions).
+
+The first thing I wrote was a \type {w-to-c} script. This was not that hard given
+that I already had written lexers. After a first prototype worked out well, I
+redid the code a bit (so that in the future I can also implement support for
+change files for instance). A complication was that I found out that the regular
+\CWEB\ converter messes around a bit with the code. So, I had to write another
+script to mimmick that to the level that I could compare the results. For
+example, spaces are removed before and after operators and all leading space gets
+removed too. When I got the same output I could get rid of that code and output
+what I want. For instance I'd like to keep the spacing the same because compilers
+can warn about some issues, like missing \type {;} and misleading indentation in
+simple \type {if} and \type {while} constructs where braces are omitted.
+\footnote {This is no problem in for instance \PASCAL\ where we always have a
+\type {begin} and \type {end}.} One can argue that this is not important, but if
+not, then why enable warnings at all. I had to fix half a dozen places in the
+\type {w} file to make the compiler happy, so the price was small.
+
+Once I had a more or less instantaneous conversion \footnote {Conversion of the
+\type {w} files involved took just over half a second at that time, currently it
+takes just over a quarter of a second, on a relatively old machine that is.} I
+got the same feeling as with the rest of the code: experimenting became
+convenient due to the fast edit|-|compile cycle. So, with al this covered I could
+do what I always had wanted to do: remove traces of the backends (including the
+full \POSTSCRIPT\ one), because they are actually to be plug|-|ins, and also get
+rid of internal font handling, which is bound to \TYPEONE\ (rendering) and small
+size \TFM\ (generating). With respect to that export: I wonder if anyone used
+that these days because even the Gust font project always had their own tool
+chain alongside \METAPOST. I could also void the hacks needed to trick the
+library in not being dependent of \type {png.h} and \type {zlib.h} headers, for
+which I had to use dummies. \footnote {The converter can load a file with patches
+to be applied but by now there are no patches.}
+
+It took a few days scripting the converter (most time went into getting identical
+output in order to check the converter which was later dropped), a few days
+stripping unused code, another day cleaning up the remaining code and then I
+could start playing with some new extensions. The binary has shrunk with 200KB
+and the whole \LUAMETATEX\ code base in compressed \type {tar.xz} format is now
+below 1.8MB while before it was above 2MB. Not that it matters much, but it was
+an nice side effect. \footnote {Size matters as we want to code to end up in the
+\CONTEXT\ distribution. It might grow a bit as side effect of adding some more
+features to \MPLIB.}
+
+What new extensions would show up was still open. Because Alan and I play with
+scanners it made sense to look into that. Error handling and logging has also
+been on my radar for a while. In the process some more code might be dropped, but
+actually the current version is still useable as library for a stand alone
+program, given that one reconstructs the \POSTSCRIPT\ driver from the dropped
+code (not that much work). Some configuration options are missing then but that
+could be provided as extensions (after all we can have change files.) On the
+other hand, wrapping code in \CONTEXT, like:
+
+\starttyping
+\starttext
+\startMPpage
+ ........
+\stopMPpage
+\startMPpage
+ ........
+\stopMPpage
+\stoptext
+\stoptyping
+
+will give a \PDF\ file that can be converted to all kinds of formats, and the
+advantage is that one has full font support. There is already a script in the
+distribution that does this anyway.
+
+\stopsection
+
+\startsection[title={Communication}]
+
+The first experiment concerns a change in the interfacing between the \METAPOST\
+and \LUA\ end. In the original library all file \IO\ is handled by the library
+itself. The filenames can be resolved via a callback. Once an instance is
+initialized, snippets of code are passed to the instance via the \type {execute}
+call. Log, terminal and error information is collected and returned as part of
+the return value (a table). This means that reporting back to the user has a
+delay: it can be shown {\em after} all code in the buffer has been processed. The
+code given as argument to \type {execute} is passed to the engine as (fake)
+terminal input, which nicely fits in the concept of interactive input, which
+already is part of the \METAPOST\ concept.
+
+In our follow up variant all file \IO\ goes via \LUA. This means that we have a
+bit more control over matters. In \CONTEXT\ we now can use the usual file
+handling code. One defines an \type {open_file} callback that returns a table
+with possible methods \type {close}, \type {reader} and \type {writer}, as in
+similar \LUATEX\ callbacks. A special file, with the name \type {terminal} is
+used for terminal communication. Now, when the \type {execute} command is
+handled, the string that gets passed ends up in the terminal, so the file handler
+has to deal with it: the string gets written to the handle, and the handle has to
+return it as lines on request. In \CONTEXT\ we directly feed the to be executed
+code into the terminal cache.
+
+It's all experimental and subject to changes but as we keep \CONTEXT\ \LMTX\ and
+\LUAMETATEX\ in sync, this is no problem. Users will not use these low level
+interfaces directly. It might take a few years to settle on this.
+
+The reports that come from the \METAPOST\ engine are now passed on to the \type
+{run_logger} callback. That one gets a target and a string passed. Where the
+original library can output stuff twice, once for the log and once for the
+console, in the new situation it gets output once, with the target being
+terminal, log file or both. The nice thing about this callback is that there is no
+delay: the messages come as the code is processed.
+
+We combine this logging with the new \type {halt_on_error} flag, which makes the
+engine abort after one error. This mechanism will be improved as we go. The
+interaction option \type {silent} hides some of the less useful messages.
+
+The overall efficiency of the library doesn't suffer from these changes, and in
+some cases it can perform even better. Anyhow, the user experience is much better
+with synchronous reports.
+
+Although not strictly related to \IO, we already has extended the library with
+the option to support \UTF-8, which is handy for special symbols, as for instance
+used in the \type {luapost} library.
+
+\stopsection
+
+\startsection[title={Scanning}]
+
+Another extension is more fundamental in the sense that it can affect the way
+users see \METAFUN: extending the user interface. It is again an example of why
+is having an independent code base has benefits: we can do such experiments for a
+long time, before we decide that (and how) it can end up in the parent (of course
+the same is true for the mentioned \IO\ features). I will not discuss these
+features here. For now it is enough to know that it gets applied in \CONTEXT\ and
+will provide a convenient additional interface. Once it is stable I'll wrap it up
+in writing.
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-performance.tex b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-performance.tex
new file mode 100644
index 00000000000..40eb1971d9c
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-performance.tex
@@ -0,0 +1,107 @@
+% language=us
+
+\startcomponent followingup-performance
+
+\environment followingup-style
+
+\startchapter[title={Performance}]
+
+\startsection[title={Introduction}]
+
+Those who've read the other documents describing the development of \LUATEX, know
+that performance is always on my radar. A decent performance is a must for a
+useable workflow, especially because typesetting is a multi|-|pass process.
+\footnote {I'm often baffled by reports of (non|-|\CONTEXT) \LUATEX\ users about
+the performance of \LUATEX. It seems easier to blame an engine than ones own
+macros or setup and most of those tests make no sense anyway. Believe it or not,
+but if performance of \CONTEXT\ \MKIV\ was much worse than \MKII\ (using \PDFTEX\
+or \XETEX) it would have backfired and the project would never have taken of.
+Just think of this: would Hans really use \LUATEX\ and continue with development
+if it were that slow?} One page reference changing from two digits to three
+digits can influence whatever follows and we're not only talking of a different
+page break, even a change in line breaks can have consequences. The core engine
+cannot be made much faster. When the (single core) run has the whole cpu
+available not much can be gained. But multiple processes are run at the same
+time, the cache has to be shared and misses can become an issue. So, efficiency
+of code is still important. Occasionally a (tiny) improvement can be made, but
+only the accumulation of such improvements can make a dent. The feeling is that
+over time \LUATEX\ has not become slower but we keep an eye on possible other
+improvements. The memory footprint is also something to keep an eye on. \footnote
+{Of course this is all becoming less relevant now that having e.g. a browser open
+in the background will set you back with a constant 5\endash10\% cpu load and
+slowly accumulating gigabyte memory usage. That actually was something I had to
+keep in mind when running \LUAMETATEX\ benchmarks.}
+
+The more we delegate to \LUA, the less we can benefit from for instance \CPU\
+improvements: in that case the \LUA\ virtual machine is the bottleneck. And there
+is not much we can do about that. This also means that when we delegate more to
+\LUA\ we sacrifice performance. Sometimes things can be done more efficient in
+\LUA, but those are often tasks that are not performed frequently. That said, I'm
+convinced most of the \CONTEXT\ code is quite efficient and not much can be
+gained.
+
+The biggest change in \LUAMETATEX\ is the backend. We gain some efficiency in
+terms of speed, performance and output in some cases, while in other cases we
+loose a bit. On the average the small performance hit is bearable. Because
+\CONTEXT\ users don't complain about performance I think that I have some slack
+here.
+
+\stopsection
+
+\startsection[title={An example}]
+
+There are a few places where \LUATEX\ looks ahead to check something and goes back
+when the condition is not met. Take these:
+
+\starttyping
+\hbox {...}
+\hbox to 10cm {...}
+\hrule width 10cm height 10cm \relax
+\dimen0 =10cm
+\dimen0 10cm
+\mydimen 10cm
+\toks0 {...}
+\toks0 \toks2
+\stoptyping
+
+Spaces and sometimes \type {\relax} after the trigger (\type {\hbox}, \type
+{\dimen}, etc.) are skipped and in some case there can be an optional \type {=}
+sign. So, there are quite some cases where there is first a check for an optional
+equal which itself can be preceded by optional spaces. When there is no equal
+sign the last seen token is pushed back into the scanned which effectively means
+that a temporary token is allocated, and a one token list is pushed on the input
+stack. Then scanning goes on. The same can happen with the open brace in case of
+a token list assignment: it gets pushed back and the content scanned checks it
+again. In the case of keywords something similar takes place, because here
+\LUATEX\ checks explicitly for e.g.\ type {width}, and when it is not found again
+it pushes back consumed tokens and checks for the \type {width}. In the case of
+the specifiers of the box we don't need to check at all when we have an opening
+brace. In the follow up, when the \type {orientation} keyword was added, and the
+\type {dir} and \type {bdir} were replaced by \type {direction} a little bit more
+was optimized.
+
+In \LUATEX\ this code comes from \PDFTEX\ which takes if from \TEX, but in both
+cases some code side effects occur from the transition from \PASCAL\ to \CCODE.
+But, in \LUATEX\ we stick to the \CCODE, so we can try to get rid of these
+artifacts. During the last years, especially when additional keywords were
+introduces (for instance for attributes) already some optimization took place. In
+the follow up again some optimizations were applied, for instance quite often we
+can combine the check for an equal sign with skipping the spaces.
+
+The gain is not spectacular but as all small bits add up eventually it is
+measurable in a complex run. What definitely is true, is that we avoid some
+memory access which in turn might pay back when multiple runs happen in parallel.
+
+Of course one can argue that such optimizations are to be avoided but as long as
+they don't obscure the code, it's okay. After all, just as one optimizes for
+instance a compression algorithm or search routine, there is no reason not to
+mildly optimize some of the critical code in \LUATEX. And in \CONTEXT\ we have
+plenty of opportunities to check if that works out well. At some point some might
+be retrofit into \LUATEX\ 1.2 (or later). \footnote {But it makes less sense now
+that there are variants popping up that might depend on the stable base.}
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-rejected.tex b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-rejected.tex
new file mode 100644
index 00000000000..f357c0ae536
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-rejected.tex
@@ -0,0 +1,83 @@
+% language=us
+
+\startcomponent followingup-rejected
+
+\environment followingup-style
+
+\startchapter[title={Rejected}]
+
+\startsection[title={Introduction}]
+
+During the development of \LUATEX\ some extensions were considered but rejected
+after some experiments. I already forgot about some that were tried the last
+decade. I will not discuss what has been added already to \LUATEX.
+
+\stopsection
+
+\startsection[title={Conditionals}]
+
+The \LUATEX\ manual describes a few conditional primitives that were added. One
+thing I played with was a native definer, think of \type {\idef} but in the end
+rejected it, because in practice it was seldom needed. Another useful one would
+be \type {\ifnothing} but the current implementation of \type {\ifx} is already
+pretty efficient so there is nothing to gain here. Another rejected one is \type
+{\ifxcase} which takes a token and compares that with a sequence, like
+
+\starttyping
+\ifxcase\foo\alpha
+\or\beta
+\or\gamma
+\else
+\fi
+\stoptyping
+
+As this was never available, in \CONTEXT\ already different strategies were
+followed so I could only find a few places where this could make code more
+readable. But who knows, I might change my mind when I split the code base and can
+adapt code accordingly although it doesn't make much sense for the more high
+level modules because it would only affect a few lines and maintaining duplicate
+files is no fun. \footnote {But playing with extensions that make for better code
+{\em is} fun.}
+
+\stopsection
+
+\startsection[title={Dimensions}]
+
+A primitive that returns the height plus depth would make sense (\type {hd}) but
+one can easily define one and the gain can be neglected. So, for now this has
+been rejected. Also, one can use the token scanners to implement that kind of
+primitives but of course that then does have a penalty in terms of performance.
+\footnote {Okay, in the end I decided to just add a primitive for this, but only
+as part of a larger set of box related primitives.}
+
+\stopsection
+
+\startsection[title={The something}]
+
+I played a bit with intercepting \type {\the} so that we could define commands
+that also respond to this expander. It didn't work out well because full
+expansion happens, even with protected macros:
+
+\starttyping
+\protected\def\foo{...] \the\foo
+\stoptyping
+
+We just have to accept this and it's no big deal.
+
+\stopsection
+
+\startsection[title={Primitives}]
+
+Occasionally I'm wondering if we should have a way to flag primitives and macros
+as being frozen but in the end it might not pay off. At some point I decided that
+at least the \type {\primitive} and \type {\ifprimitive} could go away as they
+are not really working as expected. It's better to have nothing than something
+bad. Also, we can easily clone the whole set of primitives in a new namespace
+with \LUA\ if we want. \footnote {But \unknown\ in the end we got something else
+back.}
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-retrospect.tex b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-retrospect.tex
new file mode 100644
index 00000000000..b99185b77e1
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-retrospect.tex
@@ -0,0 +1,188 @@
+% language=us
+
+\startcomponent followingup-retrospect
+
+\environment followingup-style
+
+\startchapter[title={Retrospect}]
+
+% \startsection[title={Introduction}]
+% \stopsection
+
+At some point in a new development, and \LUAMETATEX\ feels like that, there comes
+a moment when you need to make a decision. In this case the question is if we
+need to make hybrid \MKIV\ and \LMTX\ files or do the same as with the transition
+from \MKII\ to \MKIV: use two variants. For \TEX\ files a conditional section has
+only overhead in the format generation as skipped code doesn't end up in the
+format. With conditional \LUA\ code it's different: the ignored section is still
+present in byte code. But even for \TEX\ code a conditional section is not
+entirely invisible: encountered control sequences are still creating (bogus) hash
+entries. So the question is: do we go lean and mean and do we omit historic
+non|-|\LMTX\ code?
+
+A comparison with the transition from \MKII\ is actually relevant. For instance
+right from the start \CONTEXT\ had an abstract backend layer, and support for
+engines and output formats was loaded on demand. There was never any specific
+code in the core. With \MKIV\ we changed the model but there is still some
+abstraction.
+
+In \MKII\ we also had to deal with encodings and that has consequences for
+font handling, language support and input encodings. In \MKIV\ all that changed:
+internal all is \UTF, as is normally the input (but we can still use encodings),
+and fonts are always mapped to \UNICODE.
+
+Anyhow, much that made sense for \MKII\ was no longer relevant for \MKIV: code
+could be dropped. But some mechanisms were reimplemented using \LUA: code was
+added. The user interface stayed the same but in \MKIV\ uses a conceptually
+different approach deep down. Therefore the code base was split in \MKII\ and
+\MKIV\ files but this transition was made stepwise.
+
+So should the same happen with \LMTX ? There is not that much that needs to be
+added to \MKIV\ in terms of functionality. In the end, for the \TEX\ code the
+differences are not that substantial, so there we can consider loading different
+files. The files involved are rather stable so there is not much danger of
+functionality between \MKIV\ and \LMTX\ getting out of sync. The same is true for
+the \LUA\ files, although synchronization is probably more an issue there.
+
+Another option is to always assume that \LUAMETATEX\ is used. For testing regular
+\LUATEX\ (patches) we can just use a 2019 stable \CONTEXT. But in order for users
+to benefit from developments we then expect them all to move on to \LMTX. Using a
+frozen 2019 version with upcoming \LUATEX\ is no big deal as we've done the same
+with \MKII\ and that worked out okay.
+
+When we started with \CONTEXT\ development in the previous century we were doing
+pretty weird things. I remember getting comments that what we did made no sense
+because it was not what \TEX\ was meant for and some even suggested that it
+disrupted the picture. Highly structured input, a clear separation (and
+abstraction) of front and backend, inheritance and user defined styling,
+integrated support for \XML, embedded \METAPOST, advanced interactive documents,
+handling of fonts en encodings, the list is long. Occasionally some of the things
+that came with \CONTEXT\ were ridiculed, like the fact that a script was used to
+manage the (multiple) run(s), but in the end, look at how many script are around
+now. Some even wondered why we used \TEX\ at all because \TEX\ was meant for
+typesetting math. And who needs \XML\ let alone \MATHML ? Or interactive \PDF\
+features? Much in \CONTEXT\ and its management got smoother over time and the
+\LUAMETATEX\ engine fits nicely into this evolution. It's hard to keep the
+cutting edge but at least we have the instruments.
+
+During \BACHOTEX\ 2019 (end of April, beginning of May) this project was
+presented the first time outside the \CONTEXT\ community. During that meeting
+Mojca Miklavec, one of the driving forces behind \CONTEXT, upgraded the compile
+farm that already was used to compile (intermediate versions of) \LUATEX\ and
+\TEXLIVE\ to also compile \type {pplib} (handy for development) and \LUAMETATEX.
+This permits us to fine|-|tune the \type {cmake} setup which is still work in
+progress. And, also further improvements take place in the code base itself.
+
+One of the properties of open source is that one can build upon an existing code
+base, so when at \BACHOTEX\ Arthur announced that he was going to make a merge of
+\XETEX\ (which he maintains) and \LUATEX\ no one was surprised. But it could be a
+strong argument for a rather strict code freeze: spin|-|offs need stability. I've
+been told that there are now several projects where more libraries (like
+Harfbuzz) get integrated. Those cases don't influence the parent but here
+stability of the original also is expected, unless of course additional features
+go in these engines, which itself creates instability, but that's another matter.
+One could actually argue that the arrival of variants defeats the argument that
+stability is important: if a macro package uses new features, it needs to adapt,
+and naturally (temporary) issues might show up. Such are the dynamics of todays
+software development. History in general shows that not that much is persistent
+(or even accumulative) and programs are probably the least, so maybe the whole
+stability aspect has lost its relevance. \footnote {In a similar way as that the
+argument \quotation {Publishers want this or that, so we as \TEX\ community need
+to provide it.} is no longer that relevant because publishing is now more a
+business model than vocation.} Of course \LUAMETATEX\ is also a follow up, but
+one of the ideas behind it was that I could use it as platform for (independent)
+experiments that could result in code being put into \LUATEX. Also, the changes
+have a limited impact: only \CONTEXT\ will be affected. \footnote {So maybe, in
+the end, stability boils down to \quotation {The engine behaves the same and the
+\CONTEXT\ that comes with it exploits its features as good as possible}.}
+
+It is not feasible to make \CONTEXT\ work with all kind of engines that in
+practice are not used by its users. For instance, after \XETEX\ showed up it went
+through several iterations or font rendering, so we never really spent time on
+the low level features that it provided (there was no demand anyway). One cannot
+simply claim that one method is better than another that replaces it and expect
+constant adaptation (probably for the sake of a few potential users). There
+simply is no \quote {best} engine and no \quote {perfect} solution. Another
+aspect is that when we would adapt \CONTEXT\ to \LUATEX\ variants the
+dependencies on specific functionality that itself depends on the outside world
+is kind of unavoidable. Especially languages and fonts are fluid and for the
+average user there is not that much difference in that department. Should we
+really complicate matters for a few (potential) users? In \CONTEXT\ support like
+that is added on demand, driven by specific needs of users who use \TEX\ for a
+reason and are willing to test.
+
+There's enough huge and complex software around that demonstrates what happens
+when programs are extended, keep growing, their code base becoming more complex.
+Such a process doesn't really fit in my ideas about for \TEX. We positioned 1.10
+as long term stable, with the option to add a few handy things in the long run.
+For sure there are niches to fill and it is a fact that the \TEX\ community can
+deal with variants of engines: just look at the different \CJK\ engines around,
+with prefixes like \type {p}, \type {up}, \type {ep}, etc. But the question is,
+where does that put further \LUATEX\ development? And, more important, what
+consequences does it have for the \CONTEXT\ code base?
+
+The reason I mention this is that I had in mind to eventually backport features
+that work out well in \LUAMETATEX. I also mentioned that in order to support
+stock \LUATEX\ it made no sense to split the \CONTEXT\ code base. After all, a
+few conditional sections could deal with the difference between \LUATEX\ and
+\LUAMETATEX: some differences could be temporary anyway. But, given recent
+developments it actually made sense to split the code base: why spent time on
+backporting when the engine user base is spread over different spinoffs. I can
+better just assume \CONTEXT\ to exclusively use \LUAMETATEX\ and that other macro
+packages use (one or more) \LUATEX\ variants. I can then keep the generic code up
+to date and maybe occasionally add some proven stable features. It is also no big
+deal to keep the minimum subset needed for (plain) font handling compatible,
+assuming \LUATEX\ compatibility, as in the end that engine is the benchmark,
+especially when I strip it a bit from features not needed outside \CONTEXT.
+
+Thoughts like this show how fragile plans and predictions are: within a year one
+has to adapt ideas and assumptions. But it also proves that \LUAMETATEX\ was a
+good choice for \CONTEXT, especially because it is bound to \CONTEXT\
+development, which keep the users independent and isolated from developments that
+don't mind that much the (side) effects on \CONTEXT.
+
+% \footnote {I mentioned stability a few times, but this aspect is somewhat vague:
+% often I see complaints about \LUATEX, or comparisons with other engines, that
+% have nothing to do with the engine per se, but more with misunderstanding and|/|
+% assumptions, strange usage, maybe or even likely bad user code, comparing apples
+% and pears, etc. The term \type {bug} is very popular and often a preferred
+% qualifications, and it sounds even more impressive when it's qualified as a bug
+% one. I guess that a more tight coupling between specific engines and macro
+% packages at least that aspect becomes cleaner.}
+
+Around the \CONTEXT\ meeting (or maybe a bit later) we hope to have the new
+installation infrastructure stable too (currently it is also experimental). By
+that time it will also be clear how we will proceed with the \LMTX\ project. In
+the meantime I have decided so put \LUAMETATEX\ specific files alongside the
+\MKIV\ files, simply because I always need to be able run stock \LUATEX. In order
+to show the close relationship these files are flagged as \MKXL, so we bump from
+\quote {Mark Four} to \quote {Mark Fourty}. The suffixes \type {mkiv}, \type
+{mkvi} and \type {mpiv} get company from \type {mkxl}, \type {mklx} and \type
+{mpxl}. Depending on backporting features, files can come and go. I'm not yet
+sure about the \LUA\ files but the \type {lmt} suffix is already reserved for
+future use. \footnote {This is because \LUA\ 5.4 introduces some new syntax
+elements and where we can get away with the difference between 5.2 (\LUAJITTEX)
+and 5.3 (\LUATEX) such a syntax change is more drastic.} All this is also driven
+by (user) demand.
+
+Consider this (and these thoughts) a snapshot. There will be the usual reports on
+experiments and developments. And in due time there will also be a manual for
+\LUAMETATEX. \footnote {In fact it already lives on my machine but I'm not in
+ready yet for the usual complaints about manuals, so I'm not in that much of a
+hurry.} And yes, at some point I have to make up my mind with respect to
+backporting features that have proven to be useful.
+
+% \footnote {Actually, it seems to come with the Internet: folks wining on whatever
+% platform about lack of documentation (most of the \CONTEXT\ distribution actually
+% is documentation and quite some articles are, have been, and will be written) or
+% possible bug (always huge, even if no bug at all) without exposing much actual
+% research or knowledge about these matters. Write, post and shout before thinking
+% it through, increase the number hits on your profile. It's for sure a way to make
+% something end up at the bottom of my to do list, if at all. A valid response
+% could be: whatever did you contribute to the community that I myself (or
+% \CONTEXT\ users) can benefit from. Quite likely: nothing (or little)! It looks
+% like even the normally friendly \TEX\ community sometimes gets infected by this.}
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-stripping.tex b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-stripping.tex
new file mode 100644
index 00000000000..69af6376c4e
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-stripping.tex
@@ -0,0 +1,369 @@
+% language=us
+
+% 2,777,600 / 11,561,471 cont-en.fmt
+
+% Hooverphonic - Live at the Ancienne Belgique (Geike Arnaert)
+
+\startcomponent followingup-stripping
+
+\environment followingup-style
+
+\startchapter[title={Stripping}]
+
+\startsection[title={Introduction}]
+
+Normally I need a couple of iterations to reach the implementation that I like
+(an average of three rewrites is rather normal). So, I sat down and started
+stripping the engine and did so a few times in order to get an idea of how to
+proceed. One drawback of going public too soon (and we ran into that with
+\LUATEX) is that as soon as there are more users, one gets stuck into the
+situation that a different approach is not really possible. This is why from now
+on experimental is really experimental, even if that means: it works ok in
+\CONTEXT\ (even for production) but we can change interfaces be better, e.g.\
+more consistent (although we're also stuck with existing \TEX\ terminology).
+Anyway, let's proceed.
+
+\stopsection
+
+\startsection[title={The binary}]
+
+In 2014 the \LUATEX\ binary was some 10.9 MB large. The version 1.09 binary of
+October 2018 was about 6.8MB, and the reduction was due to removing the bitmap
+generation from \MPLIB\ as well as replacing poppler by pplib. As an exercise I
+decided to see how easy it was to make a small version suitable for \CONTEXT\
+\LMTX, and as expected the binary shrunk to below 3MB (plus a \LUA\ and \KPSE\
+dll). This is a reasonable size given what is still present.
+
+There is hardly any file related code left because in practice the backend used
+the most different file types. That also meant that we could remove \KPSE\
+related code and keep all that in the library part. In principle one can load
+that library and hook it into the few callbacks that relate to loading files.
+Once we're stable I'll probably write some code for that. \footnote {In the
+meantime I think it makes not much sense to do that.} Launching the binary with a
+startup script can deal with all matters needed, because the command line
+arguments are available.
+
+We could actually go even smaller by removing the built|-|in \TFM\ and \VF\
+readers. For instance it made not much sense to read and store information that
+is never used anyway, like virtual font data: as long as the backend has access
+to what it needs it's fine. By removing unused code and stripping no longer used
+fields in the internal font tables (which is also good for memory consumption),
+and cleaning up a bit here and there the experimental binary ended up at a bit
+above 2.5MB (plus a \LUA\ dll). \footnote {Mid January we were just below 2.7 MB
+with a static, all inclusive, binary. In March the static ended up at 2.9 MB on
+\MSWINDOWS\ and 2.6 MB in \UNIX.}
+
+\stopsection
+
+\startsection[title={Functionality}]
+
+There is no real reason to change much in the functionality of the frontend but
+as we have no backend now, some primitives are gone. These have to be implemented
+as part of creating a backend.
+
+\starttyping
+\dviextension \dvivariable \dvifeedback
+\pdfextension \pdfvariable \pdffeedback
+\stoptyping
+
+The already obsolete related dimensions are also removed:
+
+\starttyping
+\pageleftoffset \pagerightoffset
+\pagetopoffset \pagebottomoffset
+\stoptyping
+
+And we no longer need the page dimensions because they are just registers that
+are normally used in the backend. So, we got rid of:
+
+\starttyping
+\pageheight
+\pagewidth
+\stoptyping
+
+Some font related inheritances from \PDFTEX\ have also been dropped:
+
+\starttyping
+\letterspacefont
+\copyfont
+\expandglyphsinfont
+\ignoreligaturesinfont
+\tagcode
+\stoptyping
+
+Internally all backend whatsits are gone, but generic \type {literal}, \type
+{save}, \type {restore} and \type {setmatrix} nodes can still be created. Under
+consideration is to let them be so called user nodes but for testing it made
+sense to keep them around for a while. \footnote {Don't take this as a reference:
+later we will see that more was changed.}
+
+The resource relates primitives are backend dependent so the primitives have been
+removed. As with other backend related primitives, their arguments depend on the
+implementation. So, no more:
+
+\starttyping
+\saveboxresource
+\useboxresource
+\lastsavedboxresourceindex
+\stoptyping
+
+and:
+
+\starttyping
+\saveimageresource
+\useimageresource
+\lastsavedimageresourceindex
+\lastsavedimageresourcepages
+\stoptyping
+
+Of course the rule nodes subtypes are still there, so the typesetting machinery
+will handle them fine. It is no big deal to define a pseudo|-|primitive that
+provides the functionality at the \TEX\ level.
+
+The position related primitives are also backend dependent so again they were
+removed. \footnote {There was some sentimental element in this. Long ago, even
+before \PDFTEX\ showed up, \CONTEXT\ already had a positional mechanism. It
+worked by using specials in combination with a program that calculated the
+positions from the \DVI\ file. At some point that functionality was integrated
+into \PDFTEX. For me it always was a nice example of demonstrating that
+complaints like \quotation {\TEX\ is limited because we don't know the position
+of an element in the text.} make no sense: \TEX\ can do more than one thinks,
+given that one thinks the right way.}
+
+\starttyping
+\savepos
+\lastxpos
+\lastypos
+\stoptyping
+
+We could have kept \type {\savepos} but better is to be consistent. We no longer
+need these:
+
+\starttyping
+\outputmode
+\draftmode
+\synctex
+\stoptyping
+
+These could go because we no longer have a backend and if one needs it it's easy
+to define a meaningful variable and listen to that.
+
+The \type {\shipout} primitive does no ship out but just flushes the content of
+the box, if that hasn't happened already.
+
+Because we have \LUA\ on board, and because we can now use the token scanners to
+implement features, we no longer need the hard coded randomizer extensions. In
+fact, also the \METAPOST\ should now use the \LUA\ randomizer, so that we are
+consistent. Anyway, removed are:
+
+\starttyping
+\randomseed
+\setrandomseed
+\normaldeviate
+\uniformdeviate
+\stoptyping
+
+plus the helpers in the \type {tex} library.
+
+\stopsection
+
+\startsection[title={Fonts}]
+
+Fonts are sort of special. We need the data at the \LUA\ end in order to process
+\OPENTYPE\ fonts and the backend code needs the virtual commands. The par builder
+also needs to access font properties, as does the math renderer, but here is no
+real reason to carry virtual font information around (which involves packing and
+unpacking virtual packets). So, in the end it made much sense to also delegate
+the \TFM\ and \VF\ loading to \LUA\ as well. And, as a consequence dumping and
+undumping font information could go away too, which is okay, as we didn't preload
+fonts in \CONTEXT\ anyway. The saving in binary bytes is not impressive but
+keeping unused code around neither. In principle we can get rid of the internal
+representation if we fetch relevant data from the \LUA\ tables but that might be
+unwise from the perspective of performance. By removing the no longer needed
+fields the memory footprint became somewhat smaller and font loading (passing
+from \LUA\ to \TEX) more efficient.
+
+\stopsection
+
+\startsection[title={File IO}]
+
+What came next? A program like \LUATEX\ interacts with its environment and one of
+the nice things about \TEX\ is that it has a standard ecosystem, organized as the
+\quotation {\TEX\ Directory Structure}. There is library that interfaces with
+this structure: \KPSE, but in \CONTEXT\ \MKIV\ we implement its functionality in
+\LUA. The primary reason for this was performance. When we started with \LUATEX\
+the startup on my machine (\MSWINDOWS) and a few servers (\LINUX) of a \TEX\
+engine took seconds and most fo that was due to loading the rather large file
+databases, because a \TEX\ Live installation was a gigabyte adventure. With the
+\LUA\ variant I could bring that down to milliseconds, because I could pre|-|hash
+the database and limit it to files relevant for \CONTEXT\ (still a lot, as fonts
+made up most). Nowadays we have \SSD\ disks and plenty of memory for caching, so
+these things are less urgent, but on network shares it still matters.
+
+So, as we don't use \KPSE, we can remove that library. By doing that we simplify
+compilation a lot as then all dependencies are in the engine's source tree, and
+we're no longer dependent on updates. One can argue that we then sacrifice too
+much, but already for a decade we don't use it and the \LUA\ variant does the job
+well within the \TDS\ ecosystem. Also, in our by now stripped down engine, there
+is not that much lookup going on anyway: we're already in \LUA\ when we do fonts.
+But on the other hand, some generic usage could benefit from the library to be
+present, so we face a choice. The choice is made even more difficult by the fact
+that we can remove all kind of tweaks once we delegate for instance control over
+command execution to \LUA\ completely. But, we might provide \KPSE\ as loadable
+\LUA\ module so that when needed one can use a stub to start the program with a
+\LUA\ script that as first action loads this library that then can take care of
+further file management. As command line arguments are available in \LUA, one can
+also implement the relevant extra switches (and even more if needed).
+
+Now, the interesting thing is that because we have a \LUA\ interface to \KPSE\ we
+can actually drop some hard coded solutions. This means that we can have a binary
+without \KPSE, in which case one has to cook up callbacks that do what this
+library does. But in a version with \KPSE\ embedded one also has to define some
+file related callbacks although they can be rather simple. By keeping a handful
+of file related callbacks the code base could be simplified a lot. In the process
+the recorder option went away (not that we ever used it). It is relatively easy
+to support this in the \quote {find} related callbacks and one has to deal with
+other files (like images and fonts) also, so keeping this feature was a cheat
+anyway.
+
+At this point it is important to notice that while we're dropping some command
+line options, they can still be passed and intercepted at the \LUA\ end. So,
+providing compatible (or alternative solution) is no big deal. For instance,
+execution of (shell) programs is a \LUA\ activity and can be managed from there.
+
+\stopsection
+
+\startsection[title={Callbacks}]
+
+Callbacks can be organized in groups. First there are those related to
+\IO. We only have to deal with a few types: all kind of \TEX\ files (data
+files), format files and \LUA\ modules (but these to are on the list of
+potentially dropped files as this can be programmed in \LUA).
+
+\starttyping
+find_write_file
+find_data_file open_data_file read_data_file
+find_format_file find_lua_file find_clua_file
+\stoptyping
+
+The callbacks related to errors stay: \footnote {Some more error handling was
+added later, as was intercepting user input related to it.}
+
+\starttyping
+show_error_hook show_lua_error_hook,
+show_error_message show_warning_message
+\stoptyping
+
+% We kept the buffer handlers but dropped the output handler later anyway, so we
+% have left:
+%
+% \starttyping
+% process_input_buffer
+% \stoptyping
+
+The management hooks were kept (but the edit one might go): \footnote {And
+indeed, that one went away.}
+
+\starttyping
+process_jobname
+call_edit
+start_run stop_run wrapup_run
+pre_dump
+start_file stop_file
+\stoptyping
+
+Of course the typesetting callbacks remain too as they are the backbone of the
+opening up:
+
+\starttyping
+buildpage_filter hpack_filter vpack_filter
+hyphenate ligaturing kerning
+pre_output_filter contribute_filter build_page_insert
+pre_linebreak_filter linebreak_filter post_linebreak_filter
+insert_local_par append_to_vlist_filter new_graf
+hpack_quality vpack_quality
+mlist_to_hlist make_extensible
+\stoptyping
+
+Finally we mention one of the important callbacks:
+
+\starttyping
+define_font
+\stoptyping
+
+Without that one defined not much will happen with respect to typesetting. I
+could actually remove the \type {\font} primitive but that would be a bit weird
+as other font related commands stay. Also, it's one of the fundamental frontend
+primitives, so removal was never really considered.
+
+\stopsection
+
+\startsection[title={Bits and pieces}]
+
+In the process some helpers and status queries were removed. From the summary
+above you can deduce that this concerns images, backend, and file management.
+Also not used variables (some inherited from the past and predecessors) were
+removed. These and other changes are the reason why there is a separate manual
+for \LUAMETATEX. \footnote {Relatively late in the project I decided to be more
+selective in what got initialized in \LUA\ only mode.}
+
+One of my objectives was to see how lean and mean the code base could be. But
+even if we don't use that many files, the rather complex build system makes that
+we need to have (make and configure) files in the tree that are not really used
+but even then omitting them aborts a build. I played a bit with that but the
+problem is that it needs to be dealt with upstream in order to prevent repetitive
+work. So, this is something to sort out later. Eventually it would be nice to be
+able to compile with a minimal set of source files, also because other programs
+(all kind of \TEX\ variants) that are checked for but not compiled depend on
+libraries that we don't need (and therefore want) to have in the stripped down
+source tree. \footnote {In the end, the source tree was redesigned completely.}
+
+For now we also brought down the number of catcode tables (to 256) \footnote {As
+with math families, and if more tables are needed one should wonder about the
+\TEX\ code used.}, and the number of languages (to 8192) \footnote {This is
+already a lot and because languages are loaded run time, we can go much lower
+than this.} as that saves some initially allocated memory.
+
+\stopsection
+
+\startsection[title={What's next}]
+
+Basically the experiment ends here. A next step is to create a stable code base,
+make compilation easy and consider the way the code is packages. Then some
+cleanup can take place. Also, as it's a window to the outside world, \type {ffi}
+support will move to the code base and be integral to \LUAMETATEX. And of course
+the decision about \LUAJIT\ support has to be made some day soon. The same is
+true for \LUA\ 5.4: in \LUATEX\ for now we stick to 5.3 but experimenting with
+5.4 in \LUAMETATEX\ can't harm us. \footnote {The choice has been made:
+\LUAMETATEX\ will not have a \LUAJIT\ based companion.}
+
+To what extend the \CONTEXT\ code base will have a special files for \LMTX\ is
+yet to be decided, but we have some ideas about new features that might make that
+desirable from the perspective of maintenance. The main question is: do I want to
+have hybrid files or clean files for each variant (stock \MKIV\ and \LMTX).
+
+For the record: at the time of wrapping this up, processing the \LUATEX\ manual
+of 294 pages took 13.5 seconds using stock \LUATEX\ while using the stripped down
+binary, where \LUA\ takes over some tasks, took 13.9 seconds. \footnote {In the
+meantime we're down to around 11.6MB. These are all rough numbers and mostly
+indicate relative speeds at some point.} The \LUAJITTEX\ variant needed 10.9 and
+10.8 seconds. So, there is no real reason to not explore this route, although
+\unknown\ the \PDF\ file size shrinks from 1.48MB to 1.18MB (and optionally we
+can squeeze out more) but one can wonder if I didn't make big mistakes. It is
+good to realize that there is not much performance to gain in the engine simply
+because most code is already pretty well optimized. The same is true for the
+\CONTEXT\ code: there might be a few places where we can squeeze out a few
+milliseconds but probably it will go unnoticed.
+
+On the todo list went removal of \type {\primitive} which we never use (need) and
+the possible introduction of a way to protect primitives and macros against
+redefinition, but on the other hand, it might impact performance and be not worth
+the trouble. In the end it is a macro package issue anyway and we never really
+ran into users redefining primitives. \footnote {Indeed this primitive has been
+removed.}
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-stubs.tex b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-stubs.tex
new file mode 100644
index 00000000000..69d02adc726
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-stubs.tex
@@ -0,0 +1,262 @@
+% language=us
+
+\startcomponent followingup-stubs
+
+\environment followingup-style
+
+\startchapter[title={Stubs}]
+
+\startsection[title={Bare bone}]
+
+The most barebone way to process a \CONTEXT\ file is something like:
+
+\starttyping
+luametatex
+ --fmt="<cache path to>/luametatex/cont-en"
+ --lua="<cache path to>/luametatex/cont-en.lui"
+ --jobname="article"
+ "cont-yes.mkiv"
+\stoptyping
+
+We pas extra options, like:
+
+\starttyping
+ --c:autopdf
+ --c:currentrun=1
+ --c:fulljobname="./article.tex"
+ --c:input="./article.tex"
+ --c:kindofrun=1
+ --c:maxnofruns=9
+ --c:texmfbinpath="c:/data/develop/tex-context/tex/texmf-win64/bin"
+\stoptyping
+
+but for what we are going to discuss here it doesn't really matter. The main point is
+that we use a \LUA\ startup file. That one has a minimal amount of code so that the
+format can be loaded as we like it. For instance we need to start up with initial
+memory settings.
+
+The file \type {cont-yes} sets up the way processing content happens. This can be the
+\type {jobname} file but also something different. It is enough to know that this
+startup is quite controlled.
+
+I will explore a different approach to format loading but for now this is how it
+goes. After al, we need to be compatible with \LUATEX\ and normal \MKIV\ runs, at
+least for now.
+
+\stopsection
+
+\startsection[title={Management (some history)}]
+
+In \CONTEXT\ we always had a script: \type {texexec}, originally a \MODULA2
+program, later a \PERL\ script, then a \RUBY\ script but now we have \type
+{mtxrun}, a \LUA\ script. All take care of making sure that the file is
+processed enough times to get the cross references, tables of contents, indexes,
+multi|-|pass data stable. It also makes it possible to avoid using these special
+binaries (or links) that trick the engine into thinking it is bound to a format:
+we never had \type {pdfcontext} or \type {luacontext}, just one \type {context}.
+Actually, because we have multiple user interfaces, we would have needed many
+stubs instead. Getting this approach accepted was not easy but in the meantime
+I've seen management scripts for other packages being mentioned occasionally.
+
+The same is true for scripts: for a long time \CONTEXT\ came with quite some
+scripts but when an average \TEX\ distribution started growing, including many
+other scripts, we abandoned this approach and stuck to one management script that
+also launched auxiliary scripts. That way we could be sure that there were no
+clashes in names. If you look at a full \TEX\ installation you see many stubs to
+scripts and more keep coming. How that can work out well without unexpected side
+effects (name clashes) is not entirely clear to me, as a modern computer can have
+large bin paths. Just imagine that all large programs (or ecosystems) would
+introduce hundreds of new \quote {binaries}.
+
+Anyway, in the end a \CONTEXT\ installation using \MKIV\ only needs \type {mtxrun}
+and as bonus \type {context}. The above call is triggered by:
+
+\starttyping
+mtxrun --autogenerate --script context --autopdf article.tex
+\stoptyping
+
+from the editor. Here we create formats when none is found, and start or activate
+the \PDF\ viewer afterwards, so more minimal is:
+
+\starttyping
+mtxrun --script context article.tex
+\stoptyping
+
+Normally there is also a \type {context} stub so this also works:
+
+\starttyping
+context article.tex
+\stoptyping
+
+\stopsection
+
+\startsection[title={The launch process (more history)}]
+
+In \MKII, when we use \PDFTEX, the actual launch of these script is somewhat
+complex and a bit different per platform. But, on all platforms \KPSE\ does the
+lookup of the script. Already long ago I found out that this startup overhead
+could amount to seconds on a complete \TEX Live installation (imagine running
+over a network) which is why eventually we came up with the minimals. The reason
+is that the file databases have to be loaded: first for looking up, then for the
+stub that also needs that information and finally by the actual program. There
+were no \SSD's then.
+
+The first hurdle we took was to combine the lookup and the runner. Of course this
+is sort of out of our control because an installer can decide to still use a
+lookup approach but at least on \MSWINDOWS\ this was achieved quite easy. Sort
+of:
+
+\starttyping
+texexex -> [lookup] -->
+ texexec.pl -> [lookup] ->
+ pdftex + formats ->
+ [lookup] -> processing
+\stoptyping
+
+The first lookup can be avoided by some fast relative lookup, but for more
+complex management the second one is always there. Over time this mechanism
+became more sophisticated, for instance we use caching, could work over sockets
+using a \KPSE\ server, etc.
+
+When \LUATEX\ came around, it was already decided early that it also would serve
+as script engine for the \CONTEXT\ runner, this time \type {mtxrun}. The way this
+works differs per platform. On \WINDOWS\ there is a small binary, say \type
+{runner.exe}. It gets two copies: \type {mtxrun.exe} and \type {context.exe}. If
+you find more copies on your system, something might be wrong with your
+installation.
+
+\starttyping
+mtxrun.exe -> loads mtxrun.lua in same path
+context.exe -> idem but runs with --script=context
+\stoptyping
+
+The \type {mtxrun.lua} script will load its file database which is very efficient
+and fast. It will then load the given script and execute it. In the case of \type
+{context.exe} the \type {mtx-context.lua} script is loaded, which lives in the
+normal place in the \TEX\ tree (alongside other scripts).
+
+So, a minimal amount of programs and scripts is then:
+
+\starttyping
+texmf-win64/bin/luatex.exe
+texmf-win64/bin/mtxrun.exe
+texmf-win64/bin/mtxrun.lua
+texmf-win64/bin/context.exe
+\stoptyping
+
+with (we also need to font manager):
+
+\starttyping
+texmf-context/scripts/context/lua/mtx-context.lua
+texmf-context/scripts/context/lua/mtx-fonts.lua
+\stoptyping
+
+But \unknown\ there is a catch here: \LUATEX\ has to be started in script mode in
+order to process \type {mtxrun}. So, in fact we see this in distributions.
+
+\starttyping
+texmf-win64/bin/luatex.exe
+texmf-win64/bin/texlua.exe
+texmf-win64/bin/mtxrun.exe
+texmf-win64/bin/mtxrun.lua
+texmf-win64/bin/context.exe
+\stoptyping
+
+The \type {texlua} program is just a copy of \type {luatex} that by its name
+knows that is is supposed to run scripts and not process \TEX\ files. The setup
+can be different using dynamic libraries (more files but a shared engine part)
+but the principles are the same. Nowadays the stub doesn't need the \type
+{texlua.exe} binary any more, so this is the real setup:
+
+\starttyping
+texmf-win64/bin/luatex.exe large program
+texmf-win64/bin/mtxrun.exe small program
+texmf-win64/bin/mtxrun.lua large lua file
+texmf-win64/bin/context.exe small program
+\stoptyping
+
+Just for the record: we cannot really use batch files here because we need to
+know the original command, and when run from a script that is normally not known.
+It works to some extend but for instance when started indirectly from an editor
+it can fail, depending on how that editor is calling programs. Therefore the stub
+is the most robust method.
+
+On a \UNIX\ system the situation differs:
+
+\starttyping
+texmf-linux-64/bin/luatex large program
+texmf-linux-64/bin/texlua symlink to luatex
+texmf-linux-64/bin/mtxrun large lua file
+texmf-linux-64/bin/context shell script that starts mtxrun
+\stoptyping
+
+Here \type {mtxrun.lua} is renamed to \type {mtxrun} with a shebang line that
+triggers loading by \type {texlua} which is a symlink to \type {luatex} because
+shebang lines don't support the \type {--texlua} argument. As on windows, this
+is not really pretty.
+
+\stopsection
+
+\startsection[title={The \LMTX\ way (the present)}]
+
+Now when we move to \LMTX\ we need to make sure that the method that we choose is
+acceptable for distributions but also nicely consistent over platforms. We only
+have one binary \type {luametatex} with all messy logic removed and no second
+face like \type {metaluatex}. When it is copied to another instance (or linked)
+it will load the script with its own name when it finds one. So on \WINDOWS\ we
+now have:
+
+\starttyping
+texmf-win64/bin/luametatex.exe medium program
+texmf-win64/bin/mtxrun.exe copy (or link) of luametatex
+texmf-win64/bin/mtxrun.lua large lua file
+texmf-win64/bin/context.exe copy (or link) of luametatex
+texmf-win64/bin/context.lua small lua file
+\stoptyping
+
+and in \UNIX:
+
+\starttyping
+texmf-linux-64/bin/luametatex mediumprogram
+texmf-linux-64/bin/mtxrun copy (or link) of luametatex
+texmf-linux-64/bin/mtxrun.lua large lua file
+texmf-linux-64/bin/context copy (or link) of luametatex
+texmf-linux-64/bin/context.lua small lua file
+\stoptyping
+
+So, \type {luametatex[.exe]}, \type {mtxrun[.exe]} and \type {context[.exe]} are
+all the same. On both platforms there is \type {mtxrun.lua} (with suffix) and on
+both we also use the same runner approach. The \type {context.lua} script is
+really small and just sets the script command line argument before loading \type
+{mtxrun.lua} from the same path. In the case of copied binaries: keep in mind
+that the three copies together are not (much) larger than the \type {luatex} and
+\type {texlua} pair (especially when you take additional libraries into account).
+
+The disadvantage of using copies is that one can forget to copy with an update,
+but the fact that one can use them might be easier for installers. It's up to
+those who create the installers.
+
+One complication is that the \type {mtxrun.lua} script has to deal with the old
+and the new setup. But, when we release we will assume that one used either
+\LUATEX\ or \LUAMETATEX, not some mix. As \type {mtxrun} and \type {context} know
+what got it started they will then trigger the right engine, unless one passes
+\typ {--engine=luatex}. In that case the \LUAMETATEX\ launcher will trigger a
+\LUATEX\ run. But a mixed installation is unlikely to happen.
+
+\stopsection
+
+\startsection[title={Why not \unknown}]
+
+Technically we could use one call for both the runner and \TEX\ processor but
+when multiple runs are needed this would demand an internal engine reset as well
+as macro package reset while keeping some (multi|-|pass) data around. A way
+in|-|between could be to spawn the next run. In the end the gain would be minimal
+(we have now .2 seconds overhead per total run, which can trigger multiple
+passes, due to the management script, to basically we can neglect it. (Triggering
+the viewer takes more time.)
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-style.tex b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-style.tex
new file mode 100644
index 00000000000..68b52043c25
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-style.tex
@@ -0,0 +1,66 @@
+% \enablelmtx
+% \nopdfcompression
+
+\startenvironment followingup-style
+
+\usemodule[abbreviations-smallcaps]
+
+\logo [LUAMETATEX] {LuaMeta\TeXsuffix}
+
+\setupbodyfont[plex] % not that ok for titling
+
+\setuplayout
+ [width=middle,
+ height=middle,
+ header=0pt,
+ footer=1cm,
+ footerdistance=5mm,
+ backspace=2cm,
+ cutspace=15mm,
+ topspace=2cm,
+ bottomspace=1cm,
+ style=bold,
+ color=maincolor]
+
+\setuppagenumbering
+ [alternative=doublesided]
+
+\setupwhitespace
+ [big]
+
+\setupfootertexts
+ [][{\getmarking[chapter]\quad\pagenumber}]
+ [{\pagenumber\quad\getmarking[chapter]}][]
+
+\definecolor
+ [maincolor]
+ [darkblue]
+
+\setuphead
+ [chapter]
+ [style=\bfc,
+ color=maincolor]
+
+\setuphead
+ [section]
+ [style=\bfa,
+ color=maincolor]
+
+\setuphead
+ [subsection]
+ [style=\bf,
+ color=maincolor]
+
+\setupalign
+ [tolerant,stretch]
+
+\setuptyping
+ [color=maincolor]
+
+\setuptype
+ [color=maincolor]
+
+\setupitemize
+ [color=maincolor]
+
+\stopenvironment
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-tex.tex b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-tex.tex
new file mode 100644
index 00000000000..5524baf5358
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-tex.tex
@@ -0,0 +1,125 @@
+% language=us
+
+\startcomponent followingup-tex
+
+\environment followingup-style
+
+\startchapter[title={\TEX}]
+
+\startsection[title={Prefixes}]
+
+The fact that we merged \ETEX, a bit of \PDFTEX\ and some of \ALEPH\ into
+\LUATEX, already makes it a non|-|standard \TEX\ engine. In \LUAMETATEX\ we go a
+bit further. Completely outsourcing the backend has the side effect that some
+(extension related) primitives have to be implemented explicitly. The fact that
+\LUA\ is integrated has consequences for, for instance, initialization.
+Defaulting to \UTF-8 input makes it different too. And delegating many font
+matters to \LUA\ also doesn't make it behave like good old \TEX.
+
+Here I discuss another difference. One can argue that this definitely makes it
+less \TEX, but in practice this is not that problematic. We're talking prefixes
+here. Traditional \TEX\ has only prefixes:
+
+\startitemize[n]
+\startitem
+ \type {\global}: when used, it will make the next definition a global one.
+ The \type {\globaldefs} parameter can be used to force global or local
+ definitions.
+\stopitem
+\startitem
+ \type {\long}: when applied, this will make a macro bark on a \type {\par}
+ (or its equivalent) when grabbing an argument. In \LUATEX\ this check can be
+ disabled. \footnote {In a similar fashion barking about a \type {\par} in
+ math mode can be disabled. Such warnings made much sense when a \TEX\ run
+ took much time and was triggered and traced on relative slow output devices.}
+\stopitem
+\startitem
+ \type {\outer}: when applied the macro can only be used at the outer level.
+\stopitem
+\stopitemize
+
+Multiple prefixes can be given and their effects accumulate. The \ETEX\ extension
+adds another one:
+
+\startitemize[continue]
+\startitem
+ \type {\protected}: this will make a macro unexpandable inside an \type
+ {\edef}, an \type {\xdef} or token list serialization.
+\stopitem
+\stopitemize
+
+In \CONTEXT\ we never use(d) \type {\outer} and I can't even think of a useful
+application in a large macro package. in \MKII\ most interface macros are defined
+as \type {\long}, and because in \MKIV\ we block the complaints, we don't need
+this prefix either. On the other hand, many macros are defined \type
+{\protected}. \footnote {Or in \CONTEXT\ speak, they are defined as \typ
+{\unexpanded}, because we already had \typ {\protected} as well as \typ
+{\unexpanded} before these were introduces as primitives.}
+
+When you look at the implementation, \type {\long} and \type {\outer} are
+properties of the so called command code: we have normal, long, outer and long
+outer macros, and each has a unique command code. For some reason \type
+{\protected} is not implemented with command codes, which would have doubled the
+number to eight, but as special token injected in front of the macro preamble.
+Using a command code would have made more sense as there is no real speed penalty
+in that, while the special token indicating is a macro (body) is protected now
+has to be intercepted in some cases.
+
+Anyhow, already for a while I wondered if I should drop \type {\long} and \type
+{\outer} (making them no|-|ops). I also had on my agenda to promote \type
+{\protected} to a normal command code. And, already for a long time I wanted to
+play with a new prefix: \footnote {This is a typical example of a feature that I
+like playing with, before deciding if it will stay (as such).}
+
+\startitemize[continue]
+\startitem
+ \type {\frozen}: this will protect a macro (for now only a macro) against
+ redefinition, which provides a bit of protection for a user.
+\stopitem
+\stopitemize
+
+Promoting \type {\protected} brings the set of call commands from four to eight,
+and a \type {\frozen} property would bump it to sixteen. This is still okay, but
+in some places it would involve mode testing. However, dropping \type {\long} and
+\type {\outer} would not only keep the set small (just four) but also rid it of
+some tests. There is no performance penalty either (even a bit of gain in case of
+many protected macros as we no longer need to skip the special signal token) and
+it even saves some memory (but not that much).
+
+As a bonus there are a few more conditionals: \type {\ifprotected}, \type
+{\iffrozen}, and, very experimental, \type {\ifusercmd}, which can be used to
+check if something is user defined (often not a primitive). These probably only
+make sense for diagnostic purposes.
+
+In the end, the implementation was not that hard. In the process I also removed
+the \type {\suppress...} parameters so \type {\par} no longer plays havoc. If this
+new prefix \type {\frozen} stays of will affect more definitions, we'll see.
+
+\stopsection
+
+\startsection[title={Conditionals}]
+
+Another domain where there have been some extensions is conditions. In a previous
+chapter I mentioned \type {\iftok} already. As this is not a manual I will not go
+into details about other new conditionals. For instance we have a few that can be
+used to check for valid dimensions and numbers. This can lead to a bit cleaner
+code, although for instance in \CONTEXT\ we always used support macros for this.
+We seldom needed more than we had but when interfacing with \METAPOST\ it helps a
+little.
+
+Another, maybe interesting one is \type {\ifcondition} which when \TEX\ is in
+jump over branches mode is seen as a valid \type {\if<cmd>} token but when it
+comes to expansion the following macro determines a true or false state. A second
+nice experiment is \type {\orelse} which is to be followed by a valid \type
+{\if<cmd>} token and makes for less nesting which sometimes looks nicer and also
+has some advantages.
+
+I might wrap up these and other extensions in articles once they are considered
+stable and useful. But first I'll test them in real situation, which in practice
+means that \CONTEXT\ users will test them, probably without noticing.
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-titlepage.tex b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-titlepage.tex
new file mode 100644
index 00000000000..0f46ee9ca27
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-titlepage.tex
@@ -0,0 +1,58 @@
+\startcomponent followingup-titlepage
+
+\environment followingup-style
+
+\startluacode
+ function document.graphic()
+ local min, max, random, round = math.min, math.max, math.random, math.round
+
+ local width = 210
+ local height = 297
+
+ local bitmap = graphics.bitmaps.new(width,height,"rgb",1)
+ local data = bitmap.data
+
+ for i=1,height do
+ local d = data[i]
+ for j=1,width do
+ -- d[j] = { 0, 0, random(100,200) }
+ d[j] = { 0, 0, random(128,255) }
+ end
+ end
+
+ graphics.bitmaps.tocontext(bitmap,"210bp","297bp")
+ end
+\stopluacode
+
+\startuseMPgraphic{graphic}
+ StartPage ;
+ % fill Page
+ % withcolor "maincolor" ;
+ draw textext.urt("\bf \WORD{following up}")
+ rotated 90
+ ysized (PaperHeight-10mm)
+ shifted lrcorner Page
+ shifted (-10mm,5mm)
+ withcolor "middlegray" ;
+ draw textext.lft("\bf\strut\ConTeXt")
+ ysized 4.5cm
+ shifted lrcorner Page
+ shifted (-50mm,70mm)
+ withcolor "white" ;
+ draw textext.lft("\bf\strut lm\kern-.1ex tx")
+ ysized 4cm
+ shifted lrcorner Page
+ shifted (-50mm,37.5mm)
+ withcolor "white" ;
+ StopPage ;
+\stopuseMPgraphic
+
+\startpagemakeup[pagestate=stop] % doubledided=no
+ \startoverlay
+ % {luametatex} % for searching
+ {\scale[width=\paperwidth]{\ctxlua{document.graphic()}}}
+ {\useMPgraphic{graphic}}
+ \stopoverlay
+\stoppagemakeup
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-whatsits.tex b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-whatsits.tex
new file mode 100644
index 00000000000..64c8175734b
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup-whatsits.tex
@@ -0,0 +1,78 @@
+% language=us
+
+\startcomponent followingup-whatsits
+
+\environment followingup-style
+
+\startchapter[title={Whatsits}]
+
+% \startsection[title={...}]
+
+Whatsits provide the natural extension mechanism for \TEX. In \PDFTEX\ there are
+plenty such whatsits, for instance for \PDF\ annotations. In \LUATEX\ this
+mechanism was reorganized so that the code was better isolated. In the first
+versions of \LUAMETATEX\ only a handful was left. Stepwise some were removed and
+in the end we could stick to only one general whatsit because one can implement
+the few needed to be compatible with \TEX.
+
+We started out with this set of whatsits:
+
+\starttabulate[|B|p|]
+\NC open \NC open a file for writing (delayed) \NC \NR
+\NC write \NC write to an open file (or terminal otherwise) \NC \NR
+\NC close \NC close an opened file \NC \NR
+\NC special \NC write some literal \PDF\ code to the output file \NC \NR
+\NC user \NC store and retrieve data in a node \NC \NR
+\NC latelua \NC execute code delayed (in the backend) \NC \NR
+\NC literal \NC write some literal \PDF\ code to the output file, controlled by a mode \NC \NR
+\NC save \NC push the transformation state \NC \NR
+\NC restore \NC pop the transformation state \NC \NR
+\NC matrix \NC apply a transformation (\type {rx sx sy ry}) \NC \NR
+\NC savepos \NC register a position to be queried afterwards (\type {x y}) \NC \NR
+\stoptabulate
+
+The \type {\openout}, \type {\write} and \type {\closeout} primitives relate to
+the first three but they can be prefixed with \type {\immediate} in which case
+they don't end up as whatsits but are applied directly. The \type {special} is
+actually meant for \DVI\ while the \type {\(pdf)literal} is for \PDF\ output. The
+first four are available in regular \TEX.
+
+The last four are dealt with exclusively in the backend and by removing the
+backend they basically became no|-|ops. I kept them for a while but in the end
+decided to kick them out. Instead a generic whatsit was introduced that could be
+used as signal with the same function. That simple whatsit only has a subtype
+(and of course optionally attributes). And, as \CONTEXT\ has its own backend, we
+can intercept them as we like. The saving in code is not spectacular but keeping
+it around (basically doing nothing) neither. The impact on \CONTEXT\ was not that
+large because for instance saving positions is done differently and
+transformations are encapsulated in a few helpers that could easily be adapted.
+
+From there it was a small step to also remove the literal whatsit, so then we had
+five whatsits left, plus the generic one. I then entered sentimental mode: should
+we keep the first four or not. Of course we want to be \TEX\ compatible but we
+can remove the code and provide a compatible replacement using macros and our own
+simple whatsit nodes. That keeps all the housekeeping at the \LUA\ end,
+simplifies the \CCODE, and we're still \TEX.
+
+Of course, once we remove these and only have the delayed \LUA\ whatsit and user
+whatsits left, we can as well replace these too. In \LUATEX\ user nodes are
+actually not dealt with in the backend. One can create them at the \LUA\ end and
+query them in callbacks. The \TEX\ machinery just ignores them, like any whatsit.
+In retrospect they could have been first class nodes, but making them whatsits
+was wise because that way they can be ignored consistently when needed.
+
+So, in the end all we need is a simple whatsit. As I removed the subtypes
+stepwise there was an intermediate mix of code to recognize simple whatsits from
+core whatsits but that distinction went away. Doing this kind of refactoring is
+best done stepwise because that way I can compile some large documents and see if
+things break. As a consequence again some code could be simplified as we
+basically no longer have extensions. Of course at the \CONTEXT\ end the removed
+primitives had to be added but that didn't take much effort. The binary shrunk
+some 30K but (a small amount of) \LUA\ code was added to provide a compatible
+functionality (not that we use it).
+
+% \stopsection
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup.tex b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup.tex
new file mode 100644
index 00000000000..a9aaaf71c55
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/followingup/followingup.tex
@@ -0,0 +1,34 @@
+\environment followingup-style
+
+\dontcomplain
+
+\startdocument
+
+ \component followingup-titlepage
+
+ \startfrontmatter
+ \component followingup-contents
+ \stopfrontmatter
+
+ \startbodymatter
+ \component followingup-introduction
+ \component followingup-evolution
+ \component followingup-stripping
+ \component followingup-bitmaps
+ \component followingup-logging
+ \component followingup-directions
+ \component followingup-performance
+ \component followingup-cleanup
+ \component followingup-rejected
+ \component followingup-whatsits
+ \component followingup-feedback
+ \component followingup-lua
+ \component followingup-compilation
+ \component followingup-stubs
+ \component followingup-mp
+ \component followingup-tex
+ \component followingup-retrospect
+ \stopbodymatter
+
+\stopdocument
+
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-appendix.tex b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-appendix.tex
new file mode 100644
index 00000000000..2eab26a9371
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-appendix.tex
@@ -0,0 +1,483 @@
+% language=uk
+
+\startcomponent fonts-appendix
+
+\environment fonts-environment
+
+\startchapter[title=Appendix][color=darkgray]
+
+\startsection[title=The \type {tfm} file,reference=fontdata:tfm]
+
+The (binary) \type {tfm} file is not human readable but can be turned into a
+verbose property list which is not that hard to understand.
+
+\starttyping
+tftopl texnansi-lmr10.tfm
+\stoptyping
+
+Here is an excerpt from the data file. It starts with some general properties of
+the font. The \type {O} means that the value is in octal while the \type {R} is a
+real. Keep in mind that \TEX\ has no datatype \quote {real} so internally it is
+just integers representing scaled points.
+
+\startnarrowtyping
+(FAMILY LMROMAN10)
+(FACE O 352)
+(CODINGSCHEME LY1 ENCODING /TEX'N'ANSI, Y&Y/)
+(DESIGNSIZE R 10.0)
+(COMMENT DESIGNSIZE IS IN POINTS)
+(COMMENT OTHER SIZES ARE MULTIPLES OF DESIGNSIZE)
+(CHECKSUM O 4720464277)
+\stopnarrowtyping
+
+A text font has the following font dimensions:
+
+\startnarrowtyping
+(FONTDIMEN
+ (SLANT R 0.0)
+ (SPACE R 0.333333)
+ (STRETCH R 0.166667)
+ (SHRINK R 0.111112)
+ (XHEIGHT R 0.43055)
+ (QUAD R 1.0)
+ (EXTRASPACE R 0.111112)
+ ...
+)
+\stopnarrowtyping
+
+Kerns and ligatures are packed into a table that is basically a sequence of
+labelled entries. Here we see the entry for the character \type {f} which has
+three ligatures: \type {ff}, \type {fi} and \type {fl}. Because ligatures can be
+chained, octal slot 13 will have ligature entries for \type {ffl} and \type
+{ffi}.
+
+\startnarrowtyping
+(LIGTABLE
+ ...
+ (LABEL C f)
+ (LIG C f O 13)
+ (LIG C i O 14)
+ (LIG C l O 10)
+ (KRN O 135 R 0.027779)
+ (KRN O 41 R 0.027779)
+ (KRN O 51 R 0.027779)
+ (KRN O 77 R 0.027779)
+ (KRN O 223 R 0.027779)
+ (KRN O 224 R 0.027779)
+ (KRN O 140 R 0.027779)
+ (KRN O 47 R 0.027779)
+ (STOP)
+ ...
+)
+\stopnarrowtyping
+
+Each character gets its own entry. In this case there is no depth involved so it
+is not shown. The comment is just a repetition of the entry in the ligtable.
+
+\startnarrowtyping
+(CHARACTER C f
+ (CHARWD R 0.30555)
+ (CHARHT R 0.688875)
+ (CHARIC R 0.079222)
+ (COMMENT
+ (LIG C f O 13)
+ (LIG C i O 14)
+ (LIG C l O 10)
+ (KRN O 135 R 0.027779)
+ (KRN O 41 R 0.027779)
+ (KRN O 51 R 0.027779)
+ (KRN O 77 R 0.027779)
+ (KRN O 223 R 0.027779)
+ (KRN O 224 R 0.027779)
+ (KRN O 140 R 0.027779)
+ (KRN O 47 R 0.027779)
+ )
+)
+\stopnarrowtyping
+
+\stopsection
+
+\startsection[title=The \type {vf} file,reference=fontdata:vf]
+
+A virtual font specification file can be converted to a more readable format with
+\type {vftovp}, for instance:
+
+\starttyping
+vftovp eurm10.vf
+\stoptyping
+
+The information in a \type {vf} file will be combined with the data in the
+accompanying \type {tfm} file so the output looks similar:
+
+\startnarrowtyping
+(VTITLE )
+(FAMILY UNSPECIFIED)
+(FACE F MRR)
+(CODINGSCHEME TEX MATH ITALIC)
+(DESIGNSIZE R 10.0)
+(COMMENT DESIGNSIZE IS IN POINTS)
+(COMMENT OTHER SIZES ARE MULTIPLES OF DESIGNSIZE)
+(CHECKSUM O 24401046203)
+(SEVENBITSAFEFLAG TRUE)
+\stopnarrowtyping
+
+Because this font is a math font there is no space defined.
+
+\startnarrowtyping
+(FONTDIMEN
+ (SLANT R 0.0)
+ (SPACE R 0.0)
+ (STRETCH R 0.0)
+ (SHRINK R 0.0)
+ (XHEIGHT R 0.459)
+ (QUAD R 1.0)
+ (EXTRASPACE R 0.0)
+)
+\stopnarrowtyping
+
+A virtual font will take glyphs from another font and therefore there are entries
+that refer to these fonts. In the following definition index \type {0} is created
+(the \type {D} specifies a decimal entry).
+
+\startnarrowtyping
+(MAPFONT D 0
+ (FONTNAME eurm10)
+ (FONTCHECKSUM O 4276740471)
+ (FONTAT R 1.0)
+ (FONTDSIZE R 10.0)
+)
+(MAPFONT D 1
+ (FONTNAME cmmi10)
+ (FONTCHECKSUM O 1350061076)
+ (FONTAT R 1.0)
+ (FONTDSIZE R 10.0)
+)
+\stopnarrowtyping
+
+The zero indexed font is the default, so in the following entry this font is
+taken:
+
+\startnarrowtyping
+(CHARACTER C W
+ (CHARWD R 0.986)
+ (CHARHT R 0.691)
+ (CHARIC R 0.056)
+ (COMMENT
+ (KRN O 177 R 0.056)
+ (KRN O 75 R -0.056)
+ (KRN O 73 R -0.083)
+ (KRN O 72 R -0.083)
+ )
+ (MAP
+ (SETCHAR C W)
+ )
+)
+\stopnarrowtyping
+
+The next specification is a combination of two other glyphs becoming a new
+glyph. We see here that the \type {MAP} table is actually a sort of program:
+
+\startnarrowtyping
+(CHARACTER O 200
+ (CHARWD R 0.622)
+ (CHARHT R 0.691)
+ (MAP
+ (PUSH)
+ (MOVEDOWN R -0.18)
+ (MOVERIGHT R 0.015)
+ (SELECTFONT D 2)
+ (SETCHAR O 40)
+ (POP)
+ (SELECTFONT D 0)
+ (SETCHAR C h)
+ )
+)
+\stopnarrowtyping
+
+The character information is also in the \type {tfm} companion and that is what
+\TEX\ uses. The virtual information kicks in when the backend is creating the
+page stream and embedding the fonts.
+
+\stopsection
+
+\startsection[title=The \type {map} file,reference=fontdata:map]
+
+In a map file each line maps a font name onto a file that contains the font
+shapes in bitmap or outline format. For instance in the file \type
+{lm-texnansi.map} we find the line:
+
+\startnarrowtyping
+texnansi-lmr10 LMRoman10-Regular "enclmtexnansi ReEncodeFont" <lm-texnansi.enc <lmr10.pfb
+\stopnarrowtyping
+
+The backend will fetch the glyph data from \type {lmf10.pfb} and use the given
+encoding file to resolve indices to glyph names. A \type {pfb} file can contain
+more than 256 entries so names are used to access the data. The string between
+quotes is used for the encoding vector in the resulting file.
+
+The second entry in the line is the font name that will be used. This name is
+also used to control subset behaviour. Multiple references to this name will be
+collapsed into one inclusion when possible, thereby making the file as small as
+possible. You better make sure that the names are unique for a specific font.
+
+In addition to this, there can be directives for extending the font (horizontal
+stretch) and transforming it into a slanted variant. Both are to be used with
+care.
+
+In \MKIV\ map files are only used for virtual math fonts and just as in \MKII\ we
+load such files selectively. Users don't have to worry about this.
+
+\stopsection
+
+\startsection[title=The \type {enc} file,reference=fontdata:enc]
+
+For historic reasons, an encoding file is a blob of \POSTSCRIPT, probably because
+it can be copied into the final output directly. Given that \TEX\ got extended
+anyway, you can wonder why this information never ended up in an extended \type
+{tfm} or \type {vf} file. It had definitely made the traditional process much
+more robust.
+
+\startnarrowtyping
+/enclmtexnansi[
+/.notdef
+/Euro
+...
+/dotaccent
+/hungarumlaut
+/ogonek
+...
+/ffi
+/ffl
+/dotlessi
+/dotlessj
+/grave
+...
+/thorn
+/ydieresis
+] def
+\stopnarrowtyping
+
+There are excactly 256 entries in such a vector and the names should match those
+in a \type {pfb} file.
+
+\stopsection
+
+\startsection[title=The \type {afm} file,reference=fontdata:afm]
+
+Here we show an excerpt from an \type {afm} file that comes with Latin Modern
+Roman. Just as with a \type {tfm} file we start with some general information.
+However we don't need to convert the file as is it already in human readable
+format.
+
+\startnarrowtyping
+StartFontMetrics 2.0
+Comment Generated by MetaType1 (a MetaPost-based engine)
+Comment Creation Date: 7th October 2009
+Notice Copyright 2003--2009 by B. Jackowski and J.M. Nowacki (on behalf of TeX USERS GROUPS).
+Comment Supported by CSTUG, DANTE eV, GUST, GUTenberg, NTG, and TUG.
+Comment METATYPE1/Type 1 version by B. Jackowski & J. M. Nowacki
+Comment from GUST (http://www.gust.org.pl).
+Comment This work is released under the GUST Font License.
+Comment For the most recent version of this license see
+Comment This work has the LPPL maintenance status `maintained'.
+Comment The Current Maintainer of this work is Bogus\l{}aw Jackowski and Janusz M. Nowacki.
+Comment This work consists of the files listed in the MANIFEST-Latin-Modern.txt file.
+FontName LMRoman10-Regular
+FullName LMRoman10-Regular
+FamilyName LMRoman10
+Weight Normal
+ItalicAngle 0
+IsFixedPitch false
+UnderlinePosition -146
+UnderlineThickness 40
+Version 2.004
+EncodingScheme FontSpecific
+FontBBox -430 -290 1417 1127
+CapHeight 683.33333
+XHeight 430.55556
+Descender -194.44444
+Ascender 694.44444
+Comment PFM parameters: LMRoman10 0 0 0xEE
+Comment TFM designsize: 10 (in points)
+Comment TFM fontdimen 1: 0 (slant)
+Comment TFM fontdimen 2: 3.33333 (space)
+Comment TFM fontdimen 3: 1.66667 (space stretch)
+Comment TFM fontdimen 4: 1.11111 (space shrink)
+Comment TFM fontdimen 5: 4.3055 (xheight)
+Comment TFM fontdimen 6: 10 (quad)
+Comment TFM fontdimen 7: 1.11111 (extra space)
+Comment TFM fontdimen 8: 6.833 (non-standard: uc height)
+Comment TFM fontdimen 9: 6.9445 (non-standard: ascender)
+Comment TFM fontdimen 10: 11.27 (non-standard: accented cap height)
+Comment TFM fontdimen 11: 1.94443 (non-standard: descender depth)
+Comment TFM fontdimen 12: 11.27 (non-standard: max height)
+Comment TFM fontdimen 13: 2.9 (non-standard: max depth)
+Comment TFM fontdimen 14: 5 (non-standard: digit width)
+Comment TFM fontdimen 15: 0.88889 (non-standard: uc stem)
+Comment TFM fontdimen 16: 12 (non-standard: baselineskip)
+Comment TFM fontdimen 17: 0.69444 (non-standard: lc stem)
+Comment TFM fontdimen 18: 0.55556 (non-standard: u, i.e., font unit)
+Comment TFM fontdimen 19: 0.22223 (non-standard: overshoot)
+Comment TFM fontdimen 20: 0.25 (non-standard: thin stem, hair)
+Comment TFM fontdimen 21: 0.30556 (non-standard: cap thin stem, i.e., cap_hair)
+Comment TFM headerbyte 9: FontSpecific
+Comment TFM headerbyte 49: LMRoman10
+Comment TFM headerbyte 72: 234
+\stopnarrowtyping
+
+Watch the comments! Because \TEX\ needs a couple of so called fontdimens to be
+set, the comments list the appropriate values. When a \type {tfm} file is
+generated from an \type {afm} file, these values have to be used.
+
+Each character (or glyph) gets an entry. When we run out of indices i.e.\ pass
+the 255 boundary (we start at 0) the index becomes \type {-1}. Only the width is
+specified. The height and depth have to be derived from the bounding box for
+which the specification starts with key \type {B}.
+
+\startnarrowtyping
+StartCharMetrics 821
+...
+C 32 ; WX 333.33333 ; N space ; B 0 0 0 0 ;
+...
+C 102 ; WX 305.55556 ; N f ; B 33 0 357 705 ; L f ff ; L i fi ; L k f_k ; L l fl ;
+C 105 ; WX 277.77777 ; N i ; B 33 0 247 657 ;
+C 108 ; WX 277.77777 ; N l ; B 33 0 255 694 ;
+...
+C -1 ; WX 500 ; N Acute ; B 181 493 388 656 ;
+C -1 ; WX 500 ; N acute ; B 188 510 374 698 ;
+C -1 ; WX 500 ; N acute.ts1 ; B 208 513 392 699 ;
+...
+EndCharMetrics
+\stopnarrowtyping
+
+Watch how this font defines a space character and keep in mind that these fonts
+date from the time that there was only one kind of space. The \type {L} entry
+specifies a ligature.
+
+The names of glyphs are standardized, and even the \type {f_k} is conforming to
+standards. This standardization makes it possible to go back from glyphs to characters
+when copying text from a typeset document.
+
+The kern table is pretty large here and for a reason. First of all the file
+defines 821 glyphs so the average amount of kerns per glyph is not that large.
+But take a look at the \type {A}. Because the \type {Aacute} has the same shape
+it kerns in a similar way. This means that ideally all combined characters end up
+with the same value as their base glyph. However, in our case a bit more
+selective approach is taken. The \type {Adieresis} has a different set of kerns,
+probably to save space. It is for this reason that \OPENTYPE\ fonts have a model
+of kern classes so that similar shapes can be treated as one when setting kerns.
+You see a similar issue with ligatures, where often the right part of the shape
+kerns the same as the (stand alone) first part of the shape does.
+
+\startnarrowtyping
+StartKernData
+StartKernPairs 9230
+...
+KPX seven.prop hyphen.prop -37
+KPX seven.prop four.prop -74
+KPX seven.prop six.prop -18.5
+KPX hyphen.prop one.prop -37
+KPX hyphen.prop two.prop -18.5
+KPX hyphen.prop seven.prop -55.5
+KPX seven.oldstyle four.oldstyle -74
+KPX A T -83.333
+KPX Aacute T -83.333
+KPX Abreve T -83.333
+KPX Acircumflex T -83.333
+...
+KPX Adieresis C -27.778
+...
+KPX f bracketright 27.778
+KPX f exclam 27.778
+KPX f parenright 27.778
+KPX f question 27.778
+KPX f quotedblleft 27.778
+KPX f quotedblleft.cm 27.778
+KPX f quotedblright 27.778
+KPX f quotedblright.cm 27.778
+KPX f quoteleft 27.778
+KPX f quoteright 27.778
+...
+KPX ff bracketright 27.778
+KPX ff exclam 27.778
+KPX ff parenright 27.778
+KPX ff question 27.778
+KPX ff quotedblleft 27.778
+KPX ff quotedblleft.cm 27.778
+KPX ff quotedblright 27.778
+KPX ff quotedblright.cm 27.778
+KPX ff quoteleft 27.778
+KPX ff quoteright 27.778
+...
+EndKernPairs
+EndKernData
+\stopnarrowtyping
+
+If you look closely at the names, you will notice that some glyphs have a
+variant. In \OPENTYPE\ fonts these variants are grouped in features like \type
+{oldstyle}. The first part of such a name is still part of the standardization,
+but the second part is up to the font designer.
+
+The file ends with:
+
+\startnarrowtyping
+EndFontMetrics
+\stopnarrowtyping
+
+\stopsection
+
+\startsection[title=The \type {otf} file,reference=fontdata:otf]
+
+In the \LUATEX\ manual you can find an overview of the raw \OTF\ format as
+exposed in a \LUA\ table. The first decade of \LUATEX\ we used the built|-|in
+loader but even then in \CONTEXT\ we didn't use that format directly but used it
+to create a more compact and efficient table instead. The current release of
+\CONTEXT\ uses its own loader written in \LUA, but the fundamentals have not
+changed much. The tables are cached and can be read in at high speed. The
+structure of the tables is unlikely to change much although more data might get
+added. Although you can access the data it seldom makes sense to do so. Where
+needed interfaces are provided.
+
+\stopsection
+
+\startsection[title=The \type {lfg} file,reference=fontdata:lua]
+
+We use the goodies file control what gets added, replaced, patched or manipulated
+in a font. A goodie file permits us to go beyond what font provide by default.
+The content of a goodie file differs per font. As we also use this for
+experiments, not all entries that you find in such files are meant for users.
+
+\stopsection
+
+\startsection[title=Used fonts]
+
+The examples in the document depend on the fonts used. Here is a list of fonts used
+to render this version. Because fonts might have changed in the meantime, some examples
+might come out other than intended.
+
+\startluacode
+local list = table.load("fonts-mkiv-usedfonts.lua") or { }
+
+local NC, NR = context.NC, context.NR
+
+for i=1,#list do
+ local l = list[i]
+ context.starttabulate { "|lB|l|" }
+ local basename = string.lower(file.basename(l.filename))
+ local version = string.lower(l.version)
+ local filesize = (l.size or 0) / 1000 .. " Kb"
+ local instances = l.instances or 1
+ NC() context("filename") NC() context.type(basename) NC() NR()
+ NC() context("instances") NC() context.type(instances) NC() NR()
+ NC() context("filesize") NC() context.type(filesize) NC() NR()
+ NC() context("version") NC() context.type(version) NC() NR()
+ context.stoptabulate()
+end
+\stopluacode
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
+
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-demo-rule.lua b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-demo-rule.lua
new file mode 100644
index 00000000000..667d1e43c90
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-demo-rule.lua
@@ -0,0 +1,47 @@
+local startactualtext = backends.codeinjections.startunicodetoactualtext
+local stopactualtext = backends.codeinjections.stopunicodetoactualtext
+
+return function(specification)
+ local features = specification.features.normal
+ local name = features.original or "dejavu-serif"
+ local option = features.option -- we only support "line"
+ local size = specification.size -- always set
+ local detail = specification.detail -- e.g. default
+ if detail then
+ name = name .. "*" .. detail
+ end
+ local f, id = fonts.constructors.readanddefine(name,size)
+ if f then
+ f.properties.name = specification.name
+ f.properties.virtualized = true
+ f.fonts = {
+ { id = id },
+ }
+ for s in string.gmatch("aeuioy",".") do
+ local n = utf.byte(s)
+ local c = f.characters[n]
+ if c then
+ local w = c.width or 0
+ local h = c.height or 0
+ local d = c.depth or 0
+ if option == "line" then
+ f.characters[n].commands = {
+ { "special", "pdf:direct:" .. startactualtext(n) },
+ { "rule", option == "line" and size/10, w },
+ { "special", "pdf:direct:" .. stopactualtext() },
+ }
+ else
+ f.characters[n].commands = {
+ { "special", "pdf:direct:" .. startactualtext(n) },
+ { "down", d },
+ { "rule", h + d, w },
+ { "special", "pdf:direct:" .. stopactualtext() },
+ }
+ end
+ else
+ -- probably a real bad font
+ end
+ end
+ end
+ return f
+end
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-environment.tex b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-environment.tex
new file mode 100644
index 00000000000..c884d97e5d3
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-environment.tex
@@ -0,0 +1,74 @@
+\startenvironment fonts-environment
+
+ % we need to do this beforehand
+
+ \blockligatures[fi,fl,ff]
+
+ \startbuffer[extraminus]
+ \startluacode
+ fonts.helpers.addextraprivate("smallminus", function(tfmdata)
+ local hchar = tfmdata.characters[0x002D]
+ local mchar = tfmdata.characters[0x2212]
+ if hchar and mchar then
+ return {
+ width = hchar.width,
+ height = mchar.height,
+ commands = {
+ { "down", hchar.height - mchar.height },
+ { "char", 0x002D },
+ }
+ }
+ end
+ end)
+ fonts.helpers.addextraprivate("highminus", function(tfmdata)
+ local hchar = tfmdata.characters[0x002D]
+ local mchar = tfmdata.characters[0x2212]
+ local xchar = tfmdata.characters[0x0058]
+ if hchar and mchar and xchar then
+ return {
+ width = hchar.width,
+ height = mchar.height,
+ commands = {
+ { "down", - xchar.height + mchar.height },
+ { "char", 0x002D },
+ }
+ }
+ end
+ end)
+ \stopluacode
+ \stopbuffer
+
+ \getbuffer[extraminus]
+
+ % so far for preloading
+
+ \environment manuals-explaining-environment
+ \environment manuals-explaining-cover
+
+ \enabledirectives[visualizers.fraction=2]
+
+ \usemodule [s] [fonts-tables]
+ \usemodule [s] [fonts-missing]
+ \usemodule [s] [fonts-vectors]
+ \usemodule [s] [fonts-features]
+ \usemodule [s] [math-extensibles]
+
+ \definefontfeature[demo-onum][kern=yes,onum=yes]
+ %definefontfeature[demo-lnum][kern=yes,lnum=yes]
+ \definefontfeature[demo-tnum][kern=yes,tnum=yes]
+ \definefontfeature[demo-pnum][kern=yes,pnum=yes]
+ \definefontfeature[demo-zero][zero=yes]
+ \definefontfeature[demo-none][]
+
+ \definefont[DemoOnumLM][file:lmroman10-regular*demo-onum at 42pt]
+ %definefont[DemoLnumLM][file:lmroman10-regular*demo-lnum at 42pt]
+ \definefont[DemoTnumLM][file:lmroman10-regular*demo-tnum at 42pt]
+ \definefont[DemoPnumLM][file:lmroman10-regular*demo-pnum at 42pt]
+
+ \definefont[DemoZeroLM][file:lmroman10-regular*demo-zero at 42pt]
+ \definefont[DemoNoneLM][file:lmroman10-regular*demo-none at 42pt]
+
+ \definefont[DemoZeroLT][file:lmtypewriter10-regular*demo-zero at 42pt]
+ \definefont[DemoNoneLT][file:lmtypewriter10-regular*demo-none at 42pt]
+
+\stopenvironment
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-extensions.tex b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-extensions.tex
new file mode 100644
index 00000000000..afe6fd82386
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-extensions.tex
@@ -0,0 +1,2729 @@
+% language=uk
+
+\startcomponent fonts-extensions
+
+\environment fonts-environment
+
+\startchapter[title=Extensions][color=darkorange]
+
+\startsection[title=Introduction]
+
+One of the benefits of using \TEX\ is that you can add your own features and try
+to optimize the look and feel. Of course this can also go wrong and output can
+look pretty awful when you don't know what you're doing, but on the average it
+works out well. In many aspects the move to an \UNICODE\ data path and \OPENTYPE\
+fonts is a good one and solves a lot of problems with traditional \TEX\ engines
+and helps us to avoid complex and ugly hacks. But, if you look into the source
+code of \CONTEXT\ you will notice that there's still quite some complex coding
+needed. This is because we want to control mechanisms, even if it's only for
+dealing with some border cases. It's also the reason why \LUATEX\ is what it is:
+an extensible engine, building on tradition.
+
+As always with \TEX, fonts are an area where many tuning happens and this is also
+true in \CONTEXT. In this chapter some of the extensions will be discussed. Some
+extensions run on top of the (rather generic) feature mechanism and some are
+using dedicated code.
+
+\stopsection
+
+\startsection[title=Italics]
+
+Although \OPENTYPE\ fonts are more rich in features than traditional \TEX\ and
+\TYPEONE\ fonts, one important feature is missing: italic correction. This might
+sound strange but you need to keep in mind that in practice it's a feature that
+needs to be applied manually.
+
+\starttyping
+test {\it test\/} test
+\stoptyping
+
+It is possible to automate this mechanism and this is what the \type {\em} command
+does in \MKII:
+
+\starttyping
+test {\em test} test
+\stoptyping
+
+This command knows that it switches to italic (or slanted) and when used nested it
+knows to switch back. It also knows if a bold italic or slanted font is used. Therefore
+it can add italic correction between an italic and upright shape.
+
+An italic correction is bound to a glyph and bound to a font. In \in {figure}
+[latinmodern-italic] we see how an italic shape extends out of the bounding box.
+This is not the case in Dejavu: watch \in {figure} [dejavu-italic].
+
+\startplacefigure[reference=latinmodern-italic,title={Italic overshoot in Latin Modern.}]
+ \startcombination
+ \startcontent
+ \backgroundline[gray]{\color[maincolor]{\definedfont[lmroman10-regular*default sa 8]test}}
+ \stopcontent
+ \startcaption
+ Latin Modern Roman Regular
+ \stopcaption
+ \startcontent
+ \backgroundline[gray]{\color[maincolor]{\definedfont[lmroman10-italic*default sa 8]test}}
+ \stopcontent
+ \startcaption
+ Latin Modern Roman Italic
+ \stopcaption
+ \stopcombination
+\stopplacefigure
+
+\startplacefigure[reference=dejavu-italic,title={Italic overshoot in Dejavu Serif.}]
+ \startcombination
+ \startcontent
+ \backgroundline[gray]{\color[maincolor]{\definedfont[dejavuserif*default sa 8]test}}
+ \stopcontent
+ \startcaption
+ Dejavu Regular
+ \stopcaption
+ \startcontent
+ \backgroundline[gray]{\color[maincolor]{\definedfont[dejavuserifitalic*default sa 8]test}}
+ \stopcontent
+ \startcaption
+ Dejavu Italic
+ \stopcaption
+ \stopcombination
+\stopplacefigure
+
+This means that the application of italic correction should never been applied without
+knowing the font. In \in {figure} [italic-upright] we see an upright word following
+an italic. The space is determined by the upright one.
+
+\startplacefigure[reference=italic-upright,title={Italic followed by upright.}]
+ \startcombination
+ \startcontent
+ \backgroundline
+ [gray]
+ {\color[maincolor]{\definedfont[lmroman10-italic*default sa 4]test}
+ \color[maincolor]{\definedfont[lmroman10-regular*default sa 4]\space test}}
+ \stopcontent
+ \startcaption
+ Latin Modern
+ \stopcaption
+ \startcontent
+ \backgroundline
+ [gray]
+ {\color[maincolor]{\definedfont[dejavuserifitalic*default sa 4]test}%
+ \color[maincolor]{\definedfont[dejavuserif*default sa 4]\space test}}
+ \stopcontent
+ \startcaption
+ Dejavu
+ \stopcaption
+ \stopcombination
+\stopplacefigure
+
+Because it is to be used with care you need to enable this feature per font, You
+also need to explicitly enable the application of this correction. in \in {figure}
+[italic-one] we see italic correction in action.
+
+\startbuffer
+\definefontfeature
+ [italic]
+ [default]
+ [itlc=yes]
+\stopbuffer
+
+\typebuffer
+
+\getbuffer
+
+\startplacefigure[reference=italic-one,title={Italic correction.}]
+ \startcombination
+ \startcontent
+ \backgroundline
+ [maincolor]
+ {\color[white]{\definedfont[lmroman10-italic*default sa 4]test}
+ \color[white]{\definedfont[lmroman10-regular*default sa 4]\space test}}
+ \stopcontent
+ \startcaption
+ \backgroundline
+ [maincolor]
+ {\setupitaliccorrection[text]%
+ \color[white]{\definedfont[lmroman10-italic*italic sa 4]test}
+ \color[white]{\definedfont[lmroman10-regular*default sa 4]\space test}}
+ \stopcaption
+ \startcontent
+ \backgroundline
+ [maincolor]
+ {\color[white]{\definedfont[dejavuserifitalic*default sa 4]test}
+ \color[white]{\definedfont[dejavuserif*default sa 4]\space test}}
+ \stopcontent
+ \startcaption
+ \backgroundline
+ [maincolor]
+ {\setupitaliccorrection[text]%
+ \color[white]{\definedfont[dejavuserifitalic*italic sa 4]test}
+ \color[white]{\definedfont[dejavuserif*default sa 4]\space test}}
+ \stopcaption
+ \stopcombination
+\stopplacefigure
+
+This only signals the font constructor that additional italic information has
+to be added to the font metrics. As we already mentioned, the application of
+correction is driven by the \type {\/} primitive and that one consults the
+font metrics. Because the correction is not part of the original font
+metrics it is calculated automatically by adding a small value to the
+width. This value is calculated as follows:
+
+\starttyping
+factor * (parameters.uwidth or 40) / 2
+\stoptyping
+
+The \type {uwidth} parameter is sometimes part of the specification but if not, we
+take a reasonable default. The factor is under user control:
+
+\startbuffer
+\definefontfeature
+ [moreitalic]
+ [default]
+ [itlc=5]
+\stopbuffer
+
+\typebuffer
+
+\getbuffer
+
+This is demonstrated in \in {figure} [italic-two]. You will notice that for Latin
+Modern (any) correction makes sense, but for Dejavu it probably makes things look
+worse. This is why italic correction is disabled by default. When enabled there
+are several variants:
+
+\starttabulate[|Bl|l|]
+\NC global \NC always apply correction \NC \NR
+\NC text \NC only apply correction to text \NC \NR
+\NC always \NC apply correction between text and boxes \NC \NR
+\NC none \NC forget about correction \NC \NR
+\stoptabulate
+
+We keep track of the state using attributes but that comes at a (small) price in terms
+of extra memory and runtime. The \type {global} option simply assumes that we always
+need to check for correction (of course only for fonts that have this feature enables).
+In the given example we used:
+
+\starttyping
+\setupitaliccorrection
+ [text]
+\stoptyping
+
+You can combine keys:
+
+\starttyping
+\setupitaliccorrection
+ [global,always]
+\stoptyping
+
+\startplacefigure[reference=italic-two,title={Italic correction (factor 5).}]
+ \startcombination
+ \startcontent
+ \backgroundline
+ [maincolor]
+ {\color[white]{\definedfont[lmroman10-italic*default sa 4]test}
+ \color[white]{\definedfont[lmroman10-regular*default sa 4]\space test}}
+ \stopcontent
+ \startcaption
+ \backgroundline
+ [maincolor]
+ {\setupitaliccorrection[text]%
+ \color[white]{\definedfont[lmroman10-italic*italic sa 4]test}
+ \color[white]{\definedfont[lmroman10-regular*default sa 4]\space test}}
+ \stopcaption
+ \startcontent
+ \backgroundline
+ [maincolor]
+ {\color[white]{\definedfont[dejavuserifitalic*default sa 4]test}
+ \color[white]{\definedfont[dejavuserif*default sa 4]\space test}}
+ \stopcontent
+ \startcaption
+ \backgroundline
+ [maincolor]
+ {\setupitaliccorrection[text]%
+ \color[white]{\definedfont[dejavuserifitalic*italic sa 4]test}
+ \color[white]{\definedfont[dejavuserif*default sa 4]\space test}}
+ \stopcaption
+ \stopcombination
+\stopplacefigure
+
+The \type {itlc} feature controls if a font gets italic correction applied. In
+principle this is all that the user needs to do, given that the mechanism is
+enabled. These is an extra feature that controls the implementation:
+
+\starttabulate[|T|T|p|]
+\NC itlc \NC no \NC don't apply italic correction (default) \NC \NR
+\NC \NC yes \NC apply italic correction \NC \NR
+\NC textitalics \NC no \NC precalculate italic corrections (permit engine usage) \NC \NR
+\NC \NC yes \NC precalculate italic corrections (inhibit engine) \NC \NR
+\NC \NC delay \NC delay calculation of corrections \NC \NR
+\stoptabulate
+
+When \type {textitalics} is set to \type {yes} or \type {delay} the mechanism
+built into the engine is completely disabled. When set to \type {no} the engine
+can kick in but normally the alternative method takes precedence so that the
+engine sees no reason for further action. You can trace italic corrections with:
+
+\starttyping
+\enabletrackers[typesetters.italics]
+\stoptyping
+
+\stopsection
+
+\startsection[title=Bounding boxes]
+
+\startbuffer
+\definefontfeature
+ [withbbox]
+ [boundingbox=yes]
+
+\definefont
+ [FontWithBB]
+ [Normal*withbbox]
+\stopbuffer
+
+\start \getbuffer \FontWithBB
+
+There are some features that are rather useless and only make sense when figuring out
+issues. An example of such a feature is the following:
+
+\typebuffer
+
+This feature adds a background to each character in a font. In some fonts a glyph
+has a tight bounding box, while on other fonts some extra space is put on the left
+and right. Keep in mind that this feature blocks colored text.
+
+\par \stop
+
+\stopsection
+
+\startsection[title=Math italics]
+
+In the traditional \TEX\ fonts the width of a glyph was not the real width because
+one had to add the italic correction to it. The engine then juggles a bit with
+these properties. If you run into fonts that are designed this way, you can do this:
+
+\starttyping
+\definefontfeature[mathextra][italicwidths=yes] % fix latin modern
+\stoptyping
+
+This might make \type {$\left|V\right| = \left|W\right|$} look better for such
+fonts. Of course there can be side effects because these fonts assume a
+traditional engine.
+
+\stopsection
+
+\startsection[title=Slanting]
+
+This features (as well as the one described in the next section) are seldom used
+but provided because they were introduced in \PDFTEX.
+
+\startbuffer[define]
+\definefontfeature
+ [abitslanted]
+ [default]
+ [slant=.1]
+
+\definefontfeature
+ [abitmoreslanted]
+ [default]
+ [slant=.2]
+\stopbuffer
+
+\startbuffer[sample]
+\definedfont[Normal*abitslanted]This is a bit slanted.
+\definedfont[Normal*abitmoreslanted]And this is a bit more slanted.
+\stopbuffer
+
+\typebuffer[define,sample]
+
+The result is:
+
+\getbuffer[define]
+
+\startlines
+\getbuffer[sample]
+\stoplines
+
+\stopsection
+
+\startsection[title=Extending]
+
+The second manipulation is extending the shapes horizontally:
+
+\startbuffer[define]
+\definefontfeature
+ [abitbolder]
+ [default]
+ [extend=1.3]
+
+\definefontfeature
+ [abitnarrower]
+ [default]
+ [extend=0.7]
+\stopbuffer
+
+\startbuffer[sample]
+\definedfont[Normal*abitbolder]This looks a bit bolder.
+\definedfont[Normal*abitnarrower]And this is a bit narrower.
+\stopbuffer
+
+\typebuffer[define,sample]
+
+The result is:
+
+\getbuffer[define]
+
+\startlines
+\getbuffer[sample]
+\stoplines
+
+We can also combine slanting and extending:
+
+\startbuffer[define]
+\definefontfeature
+ [abitofboth]
+ [default]
+ [extend=1.3,
+ slant=.1]
+\stopbuffer
+
+\startbuffer[sample]
+\definedfont[Normal*abitofboth]This is a bit bolder but also slanted.
+\stopbuffer
+
+\typebuffer[define,sample]
+
+If you remember those first needle matrix printers you might recognize the
+next rendering:
+
+\getbuffer[define]
+
+\startlines
+\getbuffer[sample]
+\stoplines
+
+\stopsection
+
+\startsection[title=Fixing] % dimensions
+
+This is a rather special one. First we show a couple of definitions:
+
+\startbuffer
+\definefontfeature
+ [dimensions-a]
+ [default]
+ [dimensions={1,1,1}]
+
+\definefontfeature
+ [dimensions-b]
+ [default]
+ [dimensions={1,2,3}]
+
+\definefontfeature
+ [dimensions-c]
+ [default]
+ [dimensions={1,3,2}]
+
+\definefontfeature
+ [dimensions-d]
+ [default]
+ [dimensions={3,3,3}]
+\stopbuffer
+
+\typebuffer \getbuffer
+
+When you don't want a dimension to change you leave an entry empty, so
+valid entries are for instance: \type {,3,} and \type {1,,}.
+
+As usual you apply such a feature as follows:
+
+\starttyping
+\definefont[MyFont][Serif*dimensions-a sa 2]
+\stoptyping
+
+Alternatively you can use such a feature on its own:
+
+\starttyping
+\definefontfeature
+ [dimensions-333]
+ [dimensions={3,3,3}]
+\definefont[MyFont][Serif*default,dimensions-333 sa 2]
+\stoptyping
+
+In \in {figure} [dimensions-side-by-side] you see these four definitions in
+action. The leftmost rendering is the default rendering. The three numbers in the
+definitions represent the width (in em), height and depth (in ex).
+
+\startplacefigure[reference={dimensions-side-by-side},title={Freezing dimensions of glyphs.}]
+ \startcombination[5*1]
+ \startcontent \hbox to 7em {\hss\ruledhbox{\definedfont[Serif*default sa 2]g}\hss}\stopcontent \startcaption default \stopcaption
+ \startcontent \hbox to 7em {\hss\ruledhbox{\definedfont[Serif*dimensions-a sa 2]g}\hss}\stopcontent \startcaption \hbox{1em 1ex 1ex} \stopcaption
+ \startcontent \hbox to 7em {\hss\ruledhbox{\definedfont[Serif*dimensions-b sa 2]g}\hss}\stopcontent \startcaption \hbox{1em 2ex 3ex} \stopcaption
+ \startcontent \hbox to 7em {\hss\ruledhbox{\definedfont[Serif*dimensions-c sa 2]g}\hss}\stopcontent \startcaption \hbox{1em 3ex 2ex} \stopcaption
+ \startcontent \hbox to 7em {\hss\ruledhbox{\definedfont[Serif*dimensions-d sa 2]g}\hss}\stopcontent \startcaption \hbox{3em 3ex 3ex} \stopcaption
+ \stopcombination
+\stopplacefigure
+
+This feature only makes sense for fonts that need a fixed width, like the
+\CJK\ fonts that are used for asian scripts. Normally those fonts already
+have fixed dimensions, but this feature can be used to fix problematic
+fonts or add some more space. However, for such large fonts this also brings a
+larger memory footprint.
+
+A special case is the following:
+
+\startbuffer
+\definefontfeature
+ [dimensions-e]
+ [dimensions=strut]
+\stopbuffer
+
+\typebuffer \getbuffer
+
+This will make the height and depth the same as the {\em current} strut height
+and depth:
+
+\startbuffer
+\ruledhbox{\definedfont[Serif*default,dimensions-e at 8pt]clipped}
+\ruledhbox{\definedfont[Serif*default,dimensions-e at 12pt]clipped}
+\ruledhbox{\definedfont[Serif*default,dimensions-e at 24pt]clipped}
+\stopbuffer
+
+\typebuffer
+
+The dimensions are (in this case) limited:
+
+\startlinecorrection[blank] \dontleavehmode \hpack{\maincolor\inlinebuffer} \stoplinecorrection
+
+Another special case is \type {dimensions=mono} which will make an characters the
+fonts em|-|width. This is handy when you define font fallbacks where glyphs come
+from a non monospaced font.
+
+\stopsection
+
+\startsection[title=Unicoding]
+
+Nowadays we will mostly use fonts that ship with a \UNICODE\ aware encoding. And
+in \CONTEXT, even if we use a \TYPEONE\ font, it gets mapped onto \UNICODE.
+However, there are some exceptions, for instance the Zapf Dingbats in \TYPEONE\
+format. These have a rather obscure private encoding and the glyph names run from
+\type {a1} upto \type {a206} and have no relation to what the glyph represents.
+
+In the case of Dingbats we're somewhat lucky that they ended up in \UNICODE, so
+we can relocate the glyphs to match their rightful place. This is done by means
+of a goodies file. We already discussed this in \in {section} [goodies] so we
+only repeat the usage.
+
+\startbuffer
+\definefontfeature
+ [dingbats]
+ [mode=base,
+ goodies=dingbats,
+ unicoding=yes]
+
+\definefontsynonym
+ [ZapfDingbats]
+ [file:uzdr.afm]
+ [features=dingbats]
+\stopbuffer
+
+\typebuffer \getbuffer
+
+I tend to qualify the Dingbat font in \TEX\ distributions as rather unstable
+because of name changes and them either or not being included. Therefore it's best to
+use the hard coded name because that triggers the most visible error message when
+the font is not found.
+
+A font like this can for instance be used with the glyph placement macros as is
+demonstrated below. In the last line we see that a direct \UTF\ input also works
+out well.
+
+\starttabulate[|||T|]
+\HL
+\NC \type{\getglyphdirect {ZapfDingbats*dingbats}{\number"2701}} \NC \getglyphdirect {ZapfDingbats*dingbats}{\number"2701} \NC \NC \NR
+\NC \type{\getglyphdirect {ZapfDingbats*dingbats}{\char"2701}} \NC \getglyphdirect {ZapfDingbats*dingbats}{\char"2701} \NC \NC \NR
+\NC \type{\getnamedglyphdirect{ZapfDingbats*dingbats}{a1}} \NC \getnamedglyphdirect{ZapfDingbats*dingbats}{a1} \NC \NC \NR
+\NC \type{\getnamedglyphdirect{ZapfDingbats*dingbats}{a11}} \NC \getnamedglyphdirect{ZapfDingbats*dingbats}{a11} \NC \NC \NR
+\HL
+\NC \type{\getglyphdirect {ZapfDingbats}{\number"2701}} \NC \getglyphdirect {ZapfDingbats}{\number"2701} \NC unknown \NC \NR
+\NC \type{\getglyphdirect {ZapfDingbats}{\char"2701}} \NC \getglyphdirect {ZapfDingbats}{\char"2701} \NC unknown \NC \NR
+\NC \type{\getnamedglyphdirect{ZapfDingbats}{a1}} \NC \getnamedglyphdirect{ZapfDingbats}{a1} \NC \NC \NR
+\NC \type{\getnamedglyphdirect{ZapfDingbats}{a11}} \NC \getnamedglyphdirect{ZapfDingbats}{a11} \NC \NC \NR
+\HL
+\NC \type{\definedfont[ZapfDingbats*dingbats]✁} \NC \definedfont[ZapfDingbats*dingbats]✁ \NC \NC \NR
+\HL
+\stoptabulate
+
+Keep in mind that fonts like Dejavu (that we use here as document font) already
+has these characters which is why it shows up in the verbose part of the table.
+
+\stopsection
+
+\startsection[title=Protrusion]
+
+Protrusion is a feature that \LUATEX\ inherits from \PDFTEX. It is sometimes
+referred to as hanging punctuation but in our case any character qualifies. Also,
+hanging is not frozen but can be tuned in detail. Currently the engine defines
+protrusion in terms of the emwidth which is unfortunate and likely to change.
+\footnote {In general the low level implementation can be optimized as there are
+better mechanisms in \LUATEX.}
+
+It is sometimes believed that protrusion improves for instance narrower columns,
+but I'm pretty sure that this is not the case. It is true that it is taken into
+account when breaking a paragraph into lines, and that we then have a little bit
+more width available, but at the same time it is an extra constraint: if we
+protrude we have to do it for each line (and the whole main body of text) so it's
+just a different solution space. The main reason for applying this feature is
+{\em not} that the lines look better or that we get better looking narrow lines
+but that the right and left margins look nicer. Personally I don't like half
+protrusion of punctuation and hyphens. Best is to have small values for regular
+characters to improve the visual appearance and use full protrusion for hyphens
+(and maybe punctuation).
+
+\startsubsubject[title=protrusion classes]
+
+In \CONTEXT\ we've always defined protrusion as a percentage of the width of a
+glyph. From \MKII\ we inherit the level of control as well as the ability to
+define vectors. The shared properties are collected in so called classes and the
+character specific properties in vectors. The following classes are predefined:
+
+\showprotrusionclass
+
+The names are used in the definitions:
+
+\starttyping
+\definefontfeature[default][protrusion=quality]
+\stoptyping
+
+Currently adding a class only has a \LUA\ interface.
+
+\startbuffer
+\startluacode
+fonts.protrusions.classes.myown = {
+ vector = 'myown',
+ factor = 1,
+}
+\stopluacode
+\stopbuffer
+
+\typebuffer \getbuffer
+
+\stopsubsubject
+
+\startsubsubject[title=protrusion vectors]
+
+Vectors are larger but not as large as you might expect. Only a subset of
+characters needs to be defined. This is because in practice only latin scripts
+are candidates and these scripts have glyphs that look a lot like each other. As
+we only operate on the horizontal direction characters like \quote
+{aàáâãäå} look the same from the left and right so we only have to define
+the protrusion for \quote {a}.
+
+As with classes, you can define your own vectors:
+
+\startbuffer
+\startluacode
+fonts.protrusions.vectors.myown = table.merged (
+ fonts.protrusions.vectors.quality,
+ {
+ [0x002C] = { 0, 2 }, -- comma
+ }
+)
+\stopluacode
+\stopbuffer
+
+\typebuffer \getbuffer
+
+\stopsubsubject
+
+\startsubsubject[title=protrusion vector pure]
+ \showprotrusionvector[name=pure]
+\stopsubsubject
+
+\startsubsubject[title=protrusion vector punctuation]
+ \showprotrusionvector[name=punctuation]
+\stopsubsubject
+
+\startsubsubject[title=protrusion vector alpha]
+ \showprotrusionvector[name=alpha]
+\stopsubsubject
+
+\startsubsubject[title=protrusion vector quality]
+ \showprotrusionvector[name=quality]
+\stopsubsubject
+
+\startsubsubject[title=examples of protrusion]
+
+Next we show the quality protrusion. For this we use \type {tufte.tex} as
+this one for sure will result in punctuation and other candidates for
+protrusion.
+
+\startbuffer[define]
+\definefontfeature
+ [whatever]
+ [default]
+ [protrusion=quality]
+
+\definefont[MyTestA][Serif*default at 10pt]
+\definefont[MyTestB][Serif*whatever at 10pt]
+\stopbuffer
+
+\startbuffer[example]
+\startoverlay
+ {\ruledvbox \bgroup
+ \hsize\textwidth
+ \MyTestA
+ \setupalign[normal]
+ \input{tufte}
+ \egroup}
+ {\ruledvbox \bgroup
+ \hsize\textwidth
+ \MyTestB
+ \setupalign[hanging,normal]
+ \maincolor
+ \input{tufte}
+ \egroup}
+\stopoverlay
+\stopbuffer
+
+\typebuffer[define]
+\getbuffer [define]
+
+We use the following example. The results are shown in \in {figure}
+[protrusion:quality]. The colored text is the protruding one.
+
+\typebuffer[example]
+
+\startplacefigure[reference=protrusion:quality,title=The difference between no protrusion and quality protrusion.]
+ \getbuffer [example]
+\stopplacefigure
+
+The previously defined own class and vector is somewhat more extreme:
+
+\startbuffer[define]
+\definefontfeature
+ [whatever]
+ [default]
+ [protrusion=myown]
+
+\definefont[MyTestA][Serif*default at 10pt]
+\definefont[MyTestB][Serif*whatever at 10pt]
+\stopbuffer
+
+\typebuffer[define]
+\getbuffer [define]
+
+In \in {figure} [protrusion:myown] we see that the somewhat extreem definition of
+the comma also pulls the preceding character into the margin.
+
+\startplacefigure[reference=protrusion:myown,title=The influence of extreme protrusion on preceding characters.]
+ \getbuffer [example]
+\stopplacefigure
+
+\stopsubsubject
+
+\stopsection
+
+\startsection[title=Expansion]
+
+Expansion is also an inheritance of \PDFTEX. \footnote {As with protrusion the
+implementation in the engine is somewhat suboptimal and inefficient and will be
+upgraded to a more \LUATEX-ish way.} This mechanism selectively expands
+characters, normally upto 5\%. One reason for applying it is that we have less
+visually incompatible spacing, especially when we have underfull or cramped
+lines. For each (broken) line the badness is reconsidered with either shrink or
+stretch applied to all characters in that line. So, in the worst case a shrunken
+line is followed by a stretched one and that can be visible when the scaling
+factors are chosen wrong.
+
+As with protrusion, the solution space is larger but so are the constraints. But
+contrary to protrusion here the look and feel of the whole line can be made
+better but at the cost of much more runtime and larger (\PDF) files.
+
+\startsubsubject[title=protrusion classes]
+
+The amount of expansion depends in the shape of the character. Vertical strokes
+are more sensitive for expansion then horizontal ones. So an \quote {o} can
+get a different scaling than an \quote {m}. As with protrusion we have collected
+the properties in classes:
+
+\showexpansionclass
+
+The smaller the step, the more instances of a font we get, the better it
+looks, and the larger the files become. it's best not to use too many stretch
+and shrink steps. A stretch of 2 and shrink of 2 and step of .25 results in
+upto 8~instances plus the regular sized one.
+
+\stopsubsubject
+
+\startsubsubject[title=expansion vectors]
+
+We only have one vector: \type {quality}:
+
+\showexpansionvector[name=quality]
+
+\stopsubsubject
+
+\startsubsubject[title=an example of expansion]
+
+We use \type {zapf.tex} as example text, if only because Hermann Zapf introduced
+this optimization. Keep in mind that you can combine expansion and protrusion.
+
+\startbuffer[define]
+\definefontfeature
+ [whatever]
+ [default]
+ [expansion=quality]
+
+\definefont[MyTestA][Serif*default at 10pt]
+\definefont[MyTestB][Serif*whatever at 10pt]
+\stopbuffer
+
+\startbuffer[example]
+\startoverlay
+ {\ruledvbox \bgroup
+ \hsize\textwidth
+ \MyTestA
+ \setupalign[normal]
+ \input{tufte}
+ \egroup}
+ {\ruledvbox \bgroup
+ \hsize\textwidth
+ \MyTestB
+ \setupalign[hz,normal]
+ \maincolor
+ \input{tufte}
+ \egroup}
+\stopoverlay
+\stopbuffer
+
+\typebuffer[define]
+\getbuffer [define]
+
+We use the following example. The results are shown in \in {figure}
+[expansion:quality]. The colored text is the protruding one.
+
+\typebuffer[example]
+
+\startplacefigure[reference=expansion:quality,title=The difference between no expansion and quality expansion.]
+ \getbuffer [example]
+\stopplacefigure
+
+You can see what happens in \in {figure} [expansion:visualized].
+
+\startbuffer[example]
+ \setupalign[hz]
+ \enabletrackers[*expansion*]
+ \definefontfeature[boundingbox][boundingbox={frame,empty}]
+ \definedfont[Serif*default,quality,boundingbox @ 12.1pt]
+ \samplefile{sapolsky}\par
+ \disabletrackers[*expansion*]
+\stopbuffer
+
+\typebuffer[example]
+
+\startplacefigure[reference=expansion:visualized,title=The injected expansion kerns.]
+ \getbuffer [example]
+\stopplacefigure
+
+\stopsubsubject
+
+\startsubsubject[title=Expansion and kerning]
+
+When we expand glyphs we also need to look at the font kerns between them. In the
+original implementation taken from \PDFTEX\ expansion was implemented using pseudo
+fonts (with expanded glyph widths) and expansion of inter|-|character kerns was
+based on font information. In \LUATEX\ we have expansion factors in glyph nodes
+instead which is more efficient and gives a cleaner separation between front- and
+backend as the backend has no need to consult the font.
+
+For the font kerns we set the kern compensation directly and for that we use the
+average expansion factors of the neighbouring fonts so technically we support
+kerns between different fonts). This also has the advantage that kerns injected
+in node mode are treated well, given that they are tagged as font kern.
+
+So what is the effect (and need) of scaling font kerns? Let's look at an example.
+Kerns can be positive but also negative:
+
+\startlinecorrection
+\startcombination
+ {\vbox {
+ \forgetall
+ \hpack to 3cm{\hss\ruledhbox{\maincolor V\kern-1ptA}\hss}
+ \hpack to 3cm{\hss\ruledhbox{\maincolor V\kern 0ptA}\hss}
+ }} {negative}
+ {\vbox {
+ \forgetall
+ \hpack to 3cm{\hss\ruledhbox{\maincolor I\kern.25ptI}\hss}
+ \hpack to 3cm{\hss\ruledhbox{\maincolor I\kern 0ptI}\hss}
+ }} {positive}
+\stopcombination
+\stoplinecorrection
+
+If we use a rediculous amount of stretch we get the following. In the top line we
+scale the kern, in the bottom line we don't.
+
+\startlinecorrection
+\startcombination
+ {\vbox {
+ \definedfont[file:texgyrepagella-regular.otf at 12pt]%
+ \forgetall
+ \hpack to 3cm{\maincolor \hss\strut \scale[xscale=5000]{V}\kern-5pt\scale[xscale=5000]{A}\hss}
+ \hpack to 3cm{\maincolor \hss\strut \scale[xscale=5000]{V}\kern-1pt\scale[xscale=5000]{A}\hss}
+ }} {negative}
+ {\vbox {
+ \definedfont[file:texgyrepagella-regular.otf at 12pt]%
+ \forgetall
+ \hpack to 3cm{\maincolor \hss\strut \scale[xscale=5000]{I}\kern1.25pt\scale[xscale=5000]{I}\hss}
+ \hpack to 3cm{\maincolor \hss\strut \scale[xscale=5000]{I}\kern0.25pt\scale[xscale=5000]{I}\hss}
+ }} {positive}
+\stopcombination
+\stoplinecorrection
+
+The reason that we mention this is that when we apply \OPENTYPE\ features,
+positioning not necessarily result in font kerns. For instance ligatures can be
+the result of careful applied kerns and in some scripts kerns are used to connect
+glyphs. This means that we best cannot expand kerns by default. How bad is
+that? By looking at the examples above one would say \quotation {real bad}.
+
+But say that we have about 1pt of font kerns, then a 5\% expansion (which is
+already a lot) amounts to 0.05pt so to \blackrule [width=1pt, height=max,
+depth=max] we add \blackrule [width=.05pt, height=max, depth=max] which is so
+little that it probably goes unnoticed. Even if we use extreme kerns, as between
+VA, in practice the small amount of stretch or shrink added to a font kern goes
+unnoticed.
+
+In \in {figure} [hz:natural] we have overlayed the different strategies. The
+sample and width is chosen such that we see something. On a display you can
+scale up these examples and inspect if there is really something to see,
+but on paper zooming in helps, as in \in {figure} [hz:zoomed]. Even then the
+effect of expanded kerns is invisible. The used definitions are:
+
+\definecolor[hz:test:tr][r=1,a=1,t=.5]
+\definecolor[hz:test:tg][g=1,a=1,t=.5]
+\definecolor[hz:test:tb][b=1,a=1,t=.5]
+
+\startbuffer
+\setupfontexpansion
+ [extremehz]
+ [stretch=5,shrink=5,step=.5,vector=default,factor=1]
+\setupfontexpansion
+ [regularhz]
+ [stretch=2,shrink=2,step=.5,vector=default,factor=1]
+\setupfontexpansion
+ [minimalhz]
+ [stretch=2,shrink=2,step=.5,vector=default,factor=.5]
+
+\definefontfeature
+ [extremehz] [default]
+ [mode=node,expansion=extremehz]
+\definefontfeature
+ [regularhz] [default]
+ [mode=node,expansion=regularhz]
+\definefontfeature [minimalhz] [default]
+ [mode=node,expansion=minimalhz]
+
+\definefont
+ [ExtremeHzFont]
+ [file:texgyrepagella-regular.otf*extremehz at 10pt]
+\definefont
+ [RegularHzFont]
+ [file:texgyrepagella-regular.otf*regularhz at 10pt]
+\definefont
+ [MinimalHzFont]
+ [file:texgyrepagella-regular.otf*minimalhz at 10pt]
+\stopbuffer
+
+\typebuffer \getbuffer
+
+\edef\HzSampleText{\cldloadfile{ward}}
+
+\def\NoHzSample {\vbox{\hsize 10cm \color[hz:test:tr]{\setupalign [nohz]\HzSampleText\par}}}
+\def\HzSample {\vbox{\hsize 10cm \color[hz:test:tg]{\setupalign [hz]\HzSampleText\par}}}
+\def\FullHzSample{\vbox{\hsize 10cm \color[hz:test:tb]{\setupalign[fullhz]\HzSampleText\par}}}
+
+\startplacefigure[reference=hz:natural,title={The two expansion methods compared.}]
+ \showfontkerns
+ \dontcomplain
+ \startcombination[1*3]
+ {\ExtremeHzFont\ruledhpack{\startoverlay {\NoHzSample} {\HzSample } \stopoverlay}} {no hz \& hz}
+ {\ExtremeHzFont\ruledhpack{\startoverlay {\NoHzSample} {\FullHzSample} \stopoverlay}} {no hz \& full hz}
+ {\ExtremeHzFont\ruledhpack{\startoverlay {\HzSample } {\FullHzSample} \stopoverlay}} {hz \& full hz}
+ \stopcombination
+\stopplacefigure
+
+\startplacefigure[reference=hz:zoomed,title={The two expansion methods compared (zoomed in).}]
+ \showfontkerns
+ \dontcomplain
+ \startcombination[3*3]
+
+ {\ExtremeHzFont
+ \clip[nx=6,ny=5,x=2,y=2,sx=2]{\startoverlay {\NoHzSample} {\HzSample } \stopoverlay}} {extreme: no hz \& hz}
+ {\ExtremeHzFont
+ \clip[nx=6,ny=5,x=2,y=2,sx=2]{\startoverlay {\NoHzSample} {\FullHzSample} \stopoverlay}} {extreme: no hz \& full hz}
+ {\ExtremeHzFont
+ \clip[nx=6,ny=5,x=2,y=2,sx=2]{\startoverlay {\HzSample } {\FullHzSample} \stopoverlay}} {extreme: hz \& full hz}
+
+ {\RegularHzFont
+ \clip[nx=6,ny=5,x=2,y=2,sx=2]{\startoverlay {\NoHzSample} {\HzSample } \stopoverlay}} {regular: no hz \& hz}
+ {\RegularHzFont
+ \clip[nx=6,ny=5,x=2,y=2,sx=2]{\startoverlay {\NoHzSample} {\FullHzSample} \stopoverlay}} {regular: no hz \& full hz}
+ {\RegularHzFont
+ \clip[nx=6,ny=5,x=2,y=2,sx=2]{\startoverlay {\HzSample } {\FullHzSample} \stopoverlay}} {regular: hz \& full hz}
+
+ {\MinimalHzFont
+ \clip[nx=6,ny=5,x=2,y=2,sx=2]{\startoverlay {\NoHzSample} {\HzSample } \stopoverlay}} {minimal: no hz \& hz}
+ {\MinimalHzFont
+ \clip[nx=6,ny=5,x=2,y=2,sx=2]{\startoverlay {\NoHzSample} {\FullHzSample} \stopoverlay}} {minimal: no hz \& full hz}
+ {\MinimalHzFont
+ \clip[nx=6,ny=5,x=2,y=2,sx=2]{\startoverlay {\HzSample } {\FullHzSample} \stopoverlay}} {minimal: hz \& full hz}
+
+ \stopcombination
+\stopplacefigure
+
+In \CONTEXT\ the \type {hz} alignment option only enables expansion of glyphs,
+while \type {fullhz} also applies it to kerns. It will be clear that you can just
+stick to using the \type {hz} directive (if you want expansion at all) because
+this directive is normally disabled and because most fonts are processed in node
+mode.
+
+\stopsubsubject
+
+\stopsection
+
+\startsection[title=Composing]
+
+This feature is seldom needed but can come in handy for old fonts or when
+some special language is to be supported. When writing this section I tested
+this feature with Dejavu and only two additional characters were added:
+
+\definefontfeature
+ [default-plus-compose]
+ [compose=yes]
+
+\definefont
+ [MyComposedSerif]
+ [Serif*default-plus-compose]
+
+% we need to cheat a bit as we don't have the main character in mono
+
+\startlines \MyComposedSerif
+\type{fonts > combining > }\hbox to .5em{\hss Ѷ\hss}\type{ (U+00476) = }\hbox to .5em{\hss Ѵ\hss}\type{ (U+00474) + ̏ (U+0030F)}
+\type{fonts > combining > }\hbox to .5em{\hss ѷ\hss}\type{ (U+00477) = }\hbox to .5em{\hss ѵ\hss}\type{ (U+00475) + ̏ (U+0030F)}
+\stoplines
+
+This trace showed up after giving:
+
+\starttyping
+\enabletrackers
+ [fonts.composing.define]
+
+\definefontfeature
+ [default-plus-compose]
+ [compose=yes]
+
+\definefont
+ [MyFont]
+ [Serif*default-plus-compose]
+\stoptyping
+
+Fonts like Latin Modern have lots of glyphs but still lack some. Although the
+composer can add some of the missing, some of those new virtual glyphs probably
+will never look real good. For instance, putting additional accents on top of
+already accented uppercase characters will fail when that character has a rather
+tight (or even clipped) boundingbox in order not to spoil the lineheight. You can
+get some more insight in the process by turning on tracing:
+
+\starttyping
+\enabletrackers[fonts.composing.visualize]
+\stoptyping
+
+One reason why composing can be suboptimal is that it uses the boundingbox of the
+characters that are combined. If you really depend on a specific font and need
+some of the missing characters it makes sense to spend some time on optimizing
+the rendering. This can be done via the goodies mechanism. As an example we've
+added \type {lm-compose-test.lfg} to the distribution. First we show how it
+looks at the \TEX\ end:
+
+\startbuffer
+\enabletrackers[fonts.composing.visualize]
+
+\definefontfeature
+ [default-plus-compose]
+ [compose=yes]
+
+\loadfontgoodies
+ [lm-compose-test] % playground
+
+\definefont
+ [MyComposedSerif]
+ [file:lmroman10regular*default-plus-compose at 48pt]
+\stopbuffer
+
+\typebuffer \getbuffer
+
+\blank
+\backgroundline
+ [halfcolor]
+ {\MyComposedSerif B\quad\char"1E02\quad\char"1E04}
+\blank
+
+The positions of the dot accents on top and below the capital B is defined
+in a goodie file:
+
+\starttyping
+return {
+ name = "lm-compose-test",
+ version = "1.00",
+ comment = "Goodies that demonstrate composition.",
+ author = "Hans and Mojca",
+ copyright = "ConTeXt development team",
+ compositions = {
+ ["lmroman12-regular"] = compose,
+ }
+}
+\stoptyping
+
+As this is an experimental feature there are several ways to deal with
+this. For instance:
+
+\starttyping
+local defaultfraction = 10.0
+
+local compose = {
+ dy = defaultfraction,
+ [0x1E02] = { -- B dot above
+ dy = 150
+ },
+ [0x1E04] = { -- B dot below
+ dy = 150
+ },
+}
+\stoptyping
+
+Here the fraction is relative to the difference between the height of the
+accentee and the accent. A better solution is the following:
+
+\starttyping
+local compose = {
+ [0x1E02] = { -- B dot above
+ anchored = "top",
+ },
+ [0x1E04] = { -- B dot below
+ anchored = "bottom",
+ },
+ [0x0042] = { -- B
+ anchors = {
+ top = {
+ x = 300, y = 700,
+ },
+ bottom = {
+ x = 300, y = -30,
+ },
+ },
+ },
+ [0x0307] = {
+ anchors = {
+ top = {
+ x = -250, y = 550,
+ },
+ },
+ },
+ [0x0323] = {
+ anchors = {
+ bottom = {
+ x = -250, y = -80,
+ },
+ },
+ },
+}
+\stoptyping
+
+This approach is more or less the same as \OPENTYPE\ anchoring. It takes a bit
+more effort to define these tables but the result is better.
+
+\stopsection
+
+\startsection[title=Kerning]
+
+Inter|-|character kerning is not supported at the font level and with good
+reason. The fact that something is conceptually possible doesn't mean that we
+should use or support it. Normally proper kerning (or the lack of it) is part
+of a font design and for some scripts different kerning is not even an option.
+
+On the average \TEX\ does a proper job on justification but not all programs
+are that capable. As a consequence designers (at least we ran into it) tend to
+stick to flush left rendering because they don't trust their system to do a
+proper job otherwise. On the other hand they seem to have no problem with
+messing up the inter|-|character spacing and even combine that with excessive
+inter|-|word spacing {\em if} they want to achieve justification (without
+hyphenation). And it can become even worse when extreme glyph expansion (like
+hz) is applied.
+
+Anyhow, it will be clear that consider messing with properties like kerning that
+are part of the font design is to be done careful.
+
+\definecharacterkerning [extremekerning] [factor=.125]
+
+\start \setcharacterkerning[extremekerning]
+
+For running text additional kerning makes no sense. It not only looks
+bad, it also spoils the grayness of a text. When it is applied we need
+to deal with special cases. For instance ligatures make no sense so they
+should be disabled. Additional kerning should relate to already present
+kerning and interword spacing should be adapted accordingly. Embedded
+non|-|characters also need to be treated well.
+
+\par \stop
+
+This paragraph was typeset as follows:
+
+\starttyping
+\definecharacterkerning [extremekerning] [factor=.125]
+
+\setcharacterkerning[extremekerning] ... text ...
+\stoptyping
+
+Where additional kerning can make sense, is in titles. The previous
+command can do that job. In addition we have a mechanism that
+fills a given space. This mechanism uses the following definition:
+
+\starttyping
+\setupcharacterkerning
+ [stretched]
+ [factor=max,
+ width=\availablehsize]
+\stoptyping
+
+\startbuffer
+\stretched{\bfd to the limit}
+\stopbuffer
+
+\typebuffer
+
+\blank \start \color[maincolor]{\getbuffer} \stop \blank
+
+The following does not work:
+
+\startbuffer
+\ruledhbox to 5cm{\stretched{\bfd to the limit}}
+\stopbuffer
+
+\typebuffer
+
+\blank \start \color[maincolor]{\getbuffer} \stop \blank
+
+But this works ok:
+
+\startbuffer
+\setupcharacterkerning
+ [stretched]
+ [width=]
+
+\stretched{\bfd to the limit}
+\stopbuffer
+
+\typebuffer
+
+\blank \start \color[maincolor]{\getbuffer} \stop \blank
+
+You can also say this:
+
+\startbuffer
+\stretched[width=]{\bfd to the limit}
+\stopbuffer
+
+\typebuffer
+
+\blank \start \color[maincolor]{\getbuffer} \stop \blank
+
+or:
+
+\startbuffer
+\ruledhbox{\stretched[width=10cm]{\bfd to the limit}}
+\stopbuffer
+
+\typebuffer
+
+\blank \start \color[maincolor]{\getbuffer} \stop \blank
+
+You can get some insight in what kerning does to your font by the following
+command:
+
+\startbuffer
+\usemodule[typesetting-kerning]
+
+\starttext
+ \showcharacterkerningsteps
+ [style=Bold,
+ sample=how to violate a proper font design,
+ text=rubish,
+ first=0,
+ last=45,
+ step=5]
+\stoptext
+\stopbuffer
+
+\typebuffer
+
+\blank \getbuffer \blank
+
+\stopsection
+
+\startsection[title=Extra font kerns]
+
+Fonts are processed independent of each other. Sometimes that is unfortunate for
+kerning, although in practice it won't happen that often. We can enable an
+additional kerning mechanism to deal with these cases. The \type
+{\setextrafontkerns} command takes one argument between square brackets. The
+effect can be seen below:
+
+\startbuffer
+ VA {\smallcaps va} V{\smallcaps a}
+ VA {\bf VA} V{\bf A} {\bf V}A
+ V{\it A}
+\stopbuffer
+
+\starttabulate[|Tl|l|p|]
+\HL
+\BC key \BC result \BC logic \NC \NR
+\HL
+\NC no kerns \NC \showfontkerns\setextrafontkerns[reset]\subff{f:kern}\inlinebuffer \NC no kerns at all \NC \NR
+\NC kerns \NC \showfontkerns\setextrafontkerns[reset]\inlinebuffer \NC kerns within a font (feature) run \NC \NR
+\HL
+\NC none \NC \showfontkerns\setextrafontkerns [none]\inlinebuffer \NC only extra kerns within fonts \NC \NR
+\NC min \NC \showfontkerns\setextrafontkerns [min]\inlinebuffer \NC minimal kerns within and across fonts \NC \NR
+\NC max \NC \showfontkerns\setextrafontkerns [max]\inlinebuffer \NC maximum kerns within and across fonts \NC \NR
+\NC mixed \NC \showfontkerns\setextrafontkerns[mixed]\inlinebuffer \NC averaged kerns within and across fonts \NC \NR
+\HL
+\stoptabulate
+
+The content is defined as:
+
+\typebuffer
+
+This mechanism obeys grouping so you have complete control over where and when
+it gets applied. The \type {\showfontkerns} command can be used to trace the
+injection of (font) kerns.
+
+\stopsection
+
+\startsection[title=Ligatures]
+
+For some Latin fonts ligature building is quite advanced, take Unifraktur. I have no
+problem admitting that I find fraktur hard to read, but this one actually is sort of
+an exception. It's also a good candidate for a screen presentation where you mainly
+made notes for yourself: no one has to read it, but it looks great, especially if
+you consider it to be drawn by a pen.
+
+Anyway, we will use the following code as example (based on some remarks on the
+fonts website).
+
+\startbuffer[sample]
+sitzen / ſitzen / effe fietsen / ch ck ſt tz ſi fi
+\stopbuffer
+
+\typebuffer[sample]
+
+Some ligatures are implemented in the usual way, using the \type {liga} and \type {dlig}
+features, others kick in thanks to \type {ccmp}. This fact alone is an illustration that
+the low level \OPENTYPE\ ligature feature is not related to ligatures at all but a more
+generic mechanism: you can basically combine multiple shapes into one in all features
+exposed to the user.
+
+We define a bunch of specific feature sets:
+
+\startbuffer
+\definefontfeature
+ [unifraktur-a]
+ [default]
+\definefontfeature
+ [unifraktur-b]
+ [default]
+ [goodies=unifraktur,keepligatures=yes]
+\definefontfeature
+ [unifraktur-c]
+ [default]
+ [ccmp=yes]
+\definefontfeature
+ [unifraktur-d]
+ [default]
+ [ccmp=yes,goodies=unifraktur,keepligatures=yes]
+\definefontfeature
+ [unifraktur-e]
+ [default]
+ [liga=no,rlig=no,clig=no,dlig=no,ccmp=yes,keepligatures=auto]
+\stopbuffer
+
+\getbuffer \typebuffer
+
+and also some fonts:
+
+\startbuffer
+\definefont[TestA][UnifrakturCook*unifraktur-a sa 0.9]
+\definefont[TestB][UnifrakturCook*unifraktur-b sa 0.9]
+\definefont[TestC][UnifrakturCook*unifraktur-c sa 0.9]
+\definefont[TestD][UnifrakturCook*unifraktur-d sa 0.9]
+\definefont[TestE][UnifrakturCook*unifraktur-e sa 0.9]
+\stopbuffer
+
+\getbuffer \typebuffer
+
+We show these five alternatives here:
+
+\starttabulate[|T||]
+\NC liga \NC \TestA\getbuffer[sample] \NC \NR
+\NC liga + keepligatures \NC \TestB\getbuffer[sample] \NC \NR
+\NC liga + ccmp \NC \TestC\getbuffer[sample] \NC \NR
+\NC liga + ccmp + keepligatures \NC \TestD\getbuffer[sample] \NC \NR
+\NC ccmp + keepligatures \NC \TestE\getbuffer[sample] \NC \NR
+\stoptabulate
+
+The real fun starts when we want to add extra spacing between characters. Some
+ligatures need to get broken and some kept.
+
+\startbuffer
+\setupcharacterkerning[kerncharacters][factor=0.5]
+\setupcharacterkerning[letterspacing] [factor=0.5]
+\stopbuffer
+
+\getbuffer \typebuffer
+
+\enabletrackers[typesetters.kerns.ligatures]
+
+Next we will see how ligatures behave depending on how the mechanisms are set
+up. The colors indicate what trickery is used:
+
+\starttabulate[|T||]
+\NC \color[darkred] {red} \NC kept by dynamic feature \NC \NR
+\NC \color[darkgreen]{green} \NC kept by static feature \NC \NR
+\NC \color[darkblue] {blue} \NC keep by goodie \NC \NR
+\stoptabulate
+
+First we use \type {\kerncharacters}:
+
+\starttabulate[|T||]
+\NC liga \NC \kerncharacters {\TestA\getbuffer[sample]} \NC \NR
+\NC liga + keepligatures \NC \kerncharacters {\TestB\getbuffer[sample]} \NC \NR
+\NC liga + ccmp \NC \kerncharacters {\TestC\getbuffer[sample]} \NC \NR
+\NC liga + ccmp + keepligatures \NC \kerncharacters {\TestD\getbuffer[sample]} \NC \NR
+\NC ccmp + keepligatures \NC \kerncharacters {\TestE\getbuffer[sample]} \NC \NR
+\stoptabulate
+
+In the next example we use \type {\letterspacing}:
+
+\starttabulate[|T||]
+\NC liga \NC \letterspacing {\TestA\getbuffer[sample]} \NC \NR
+\NC liga + keepligatures \NC \letterspacing {\TestB\getbuffer[sample]} \NC \NR
+\NC liga + ccmp \NC \letterspacing {\TestC\getbuffer[sample]} \NC \NR
+\NC liga + ccmp + keepligatures \NC \letterspacing {\TestD\getbuffer[sample]} \NC \NR
+\NC ccmp + keepligatures \NC \letterspacing {\TestE\getbuffer[sample]} \NC \NR
+\stoptabulate
+
+\disabletrackers[typesetters.kerns.ligatures]
+
+The difference is that the letterspacing variant dynamically adds the predefined
+featureset \type {letterspacing} which is defined in a similar way as \type
+{unifraktur-e}. In the case of this font, this variant is the better one to use.
+In fact, this variant probably works okay with most fonts. However, by not hard
+coding this behaviour we keep control, as one never knows what the demands are.
+When no features are used, information from the (given) goodie file \type
+{unifraktur.lfg} is consulted:
+
+\starttyping
+letterspacing = {
+ -- watch it: zwnj's are used (in the tounicodes too)
+ keptligatures = {
+ ["c_afii301_k.ccmp"] = true, -- ck
+ ["c_afii301_h.ccmp"] = true, -- ch
+ ["t_afii301_z.ccmp"] = true, -- tz
+ ["uniFB05"] = true, -- ſt
+ },
+}
+\stoptyping
+
+These kick in when we don't disable ligatures by setting features (case~e).
+
+There are two pseudo features that can help us out when a font doesn't provide
+the wanted ligatures but has the right glyphs for building them. The \UNICODE\
+database has some information about how characters can be (de)composed and we can
+use that information to create virtual glyphs:
+
+\starttyping
+\definefontfeature
+ [default] [default]
+ [char-ligatures=yes,mode=node]
+\stoptyping
+
+and:
+
+\starttyping
+\definefontfeature
+ [default] [default]
+ [compat-ligatures=yes,mode=node]
+\stoptyping
+
+This feature was added after some discussion on the \CONTEXT\ mailing list about
+the following use case.
+
+\startbuffer
+\definefontfeature
+ [default-l] [default]
+ [char-ligatures=yes,
+ compat-ligatures=yes,
+ mode=node]
+
+\definefont[LigCd][cambria*default]
+\definefont[LigPd][texgyrepagellaregular*default]
+\definefont[LigCl][cambria*default-l]
+\definefont[LigPl][texgyrepagellaregular*default-l]
+\stopbuffer
+
+\typebuffer \getbuffer
+
+These definitions result in:
+
+\starttabulate[|l|l|l|l|l|]
+\NC \NC \type {\LigCd} \NC \type {\LigPd} \NC \type {\LigCl} \NC \type {\LigPl} \NC \NR
+\NC \type{PEL·LÍCULES} \NC \LigCd PEL·LÍCULES \NC \LigPd PEL·LÍCULES \NC \LigCl PEL·LÍCULES \NC \LigPl PEL·LÍCULES \NC \NR
+\NC \type{pel·lícules} \NC \LigCd pel·lícules \NC \LigPd pel·lícules \NC \LigCl pel·lícules \NC \LigPl pel·lícules \NC \NR
+\NC \type{PEĿLÍCULES} \NC \LigCd PEĿLÍCULES \NC \LigPd PEĿLÍCULES \NC \LigCl PEĿLÍCULES \NC \LigPl PEĿLÍCULES \NC \NR
+\NC \type{peŀlícules} \NC \LigCd peŀlícules \NC \LigPd peŀlícules \NC \LigCl peŀlícules \NC \LigPl peŀlícules \NC \NR
+\stoptabulate
+
+Of course one can wonder is this is the right approach and if it's not better to
+use a font that provides the needed characters in the first place.
+
+\stopsection
+
+\startsection[title=New features]
+
+\startsubsection[title=Substitution]
+
+It is possible to add new features via \LUA. Here is an example of a single
+substitution:
+
+\startbuffer
+\startluacode
+ fonts.handlers.otf.addfeature {
+ name = "stest",
+ type = "substitution",
+ data = {
+ a = "X",
+ b = "P",
+ }
+ }
+\stopluacode
+\stopbuffer
+
+\typebuffer \getbuffer
+
+We show an overview at the end of this section, but here is a simple example
+already. You need to define the feature before defining a font because otherwise
+the font will not know about it.
+
+\startbuffer
+\definefontfeature[stest][stest=yes]
+\definedfont[file:dejavu-serifbold.ttf*default]
+abracadabra: \addff{stest}abracadabra
+\stopbuffer
+
+\typebuffer \start \blank \maincolor \getbuffer \blank \stop
+
+Instead of (more readable) glyph names you can also give \UNICODE\ numbers:
+
+\starttyping
+\startluacode
+ fonts.handlers.otf.addfeature {
+ name = "stest",
+ type = "substitution",
+ data = {
+ [0x61] = 0x58
+ [0x62] = 0x50
+ }
+ }
+\stopluacode
+\stoptyping
+
+The definition is quite simple: we just map glyph names (or unicodes) onto
+other ones. An alternate is also possible:
+
+\startbuffer
+\startluacode
+ fonts.handlers.otf.addfeature {
+ name = "atest",
+ type = "alternate",
+ data = {
+ a = { "X", "Y" },
+ b = { "P", "Q" },
+ }
+ }
+\stopluacode
+\stopbuffer
+
+\typebuffer \getbuffer
+
+Less useful is a multiple substitution. Normally this one is part of a chain of
+replacements.
+
+\startbuffer
+\startluacode
+ fonts.handlers.otf.addfeature {
+ name = "mtest",
+ type = "multiple",
+ data = {
+ a = { "X", "Y" },
+ b = { "P", "Q" },
+ }
+ }
+\stopluacode
+\stopbuffer
+
+\typebuffer \getbuffer
+
+A ligature (or multiple to one) is also possible but normally only makes sense when
+there is indeed a ligature. We use a similar definition for mapping the \TEX\ input
+sequence \type {---} onto an \emdash.
+
+\startbuffer
+\startluacode
+ fonts.handlers.otf.addfeature {
+ name = "ltest",
+ type = "ligature",
+ data = {
+ ['1'] = { "a", "b" },
+ ['2'] = { "d", "a" },
+ }
+ }
+\stopluacode
+\stopbuffer
+
+\typebuffer \getbuffer
+
+\stopsubsection
+
+\startsubsection[title=Positioning]
+
+You can define a kern feature too but when doing so you need to use measures in
+font units.
+
+\startbuffer
+\startluacode
+ fonts.handlers.otf.addfeature {
+ name = "ktest",
+ type = "kern",
+ data = {
+ a = { b = -500 },
+ }
+ }
+\stopluacode
+\stopbuffer
+
+\typebuffer \getbuffer
+
+Pairwise positioning is more complex and involves two (optional) arrays
+that specify \type {{dx dy wd ht}} for each of the two glyphs. In the next
+example we only displace the second glyph.
+
+\startbuffer
+\startluacode
+ fonts.handlers.otf.addfeature {
+ name = "ptest",
+ type = "pair",
+ data = {
+ ["a"] = { ["b"] = { false, { -1000, 1200, 0, 0 } } },
+ }
+ }
+\stopluacode
+\stopbuffer
+
+\typebuffer \getbuffer
+
+Of course you need to know a bit about the metrics of the glyphs involved so in
+practice this boils down to trial and error.
+
+A single character (glyph) can also be tweaked, although normally this is done
+better in a manipulator when loading the font. Anyway:
+
+\startbuffer
+\startluacode
+ fonts.handlers.otf.addfeature {
+ name = "stest",
+ type = "single",
+ data = {
+ a = { -30, 0, -50, 0 },
+ }
+ }
+\stopluacode
+\stopbuffer
+
+\typebuffer \getbuffer
+
+This will reduce the left and right edges and make the glyph a pretty tight one. The
+values are for Latin Modern.
+
+\stopsubsection
+
+\startsubsection[title=Examples]
+
+We didn't show usage yet. This is because we need to define a feature before we
+define a font. New features will be added to a font when it gets defined.
+
+\startbuffer
+\definefontfeature[stest][stest=yes]
+\definefontfeature[atest][atest=2]
+\definefontfeature[mtest][mtest=yes]
+\definefontfeature[ltest][ltest=yes]
+\definefontfeature[ktest][ktest=yes]
+\definefontfeature[ptest][ptest=yes]
+\definefontfeature[ctest][ctest=yes]
+
+\definedfont[file:dejavu-serif.ttf*default]
+
+\starttabulate[|l|l|l|]
+\NC operation \NC feature \NC abracadabra \NC \NR
+\HL
+\NC substitution \NC \type {stest} \NC \addff{stest}abracadabra \NC \NR
+\NC alternate \NC \type {atest} \NC \addff{atest}abracadabra \NC \NR
+\NC multiple \NC \type {mtest} \NC \addff{mtest}abracadabra \NC \NR
+\NC ligature \NC \type {ltest} \NC \addff{ltest}abracadabra \NC \NR
+\NC kern \NC \type {ktest} \NC \addff{ktest}abracadabra \NC \NR
+\NC pair \NC \type {ptest} \NC \addff{ptest}abracadabra \NC \NR
+\NC chain sub \NC \type {ctest} \NC \addff{ctest}abracadabra \NC \NR
+\stoptabulate
+\stopbuffer
+
+\typebuffer \getbuffer
+
+\stopsubsection
+
+\startsubsection[title=Contexts]
+
+A more complex substitution is the following:
+
+\startbuffer
+\startluacode
+ fonts.handlers.otf.addfeature {
+ name = "ytest",
+ type = "chainsubstitution",
+ lookups = {
+ {
+ type = "substitution",
+ data = {
+ ["b"] = "B",
+ ["c"] = "C",
+ },
+ },
+ },
+ data = {
+ rules = {
+ {
+ before = { { "a" } },
+ current = { { "b", "c" } },
+ lookups = { 1 },
+ },
+ },
+ },
+ }
+\stopluacode
+\stopbuffer
+
+\typebuffer \getbuffer
+
+Here the dataset is a sequence of rules. There can be a \type {before}, \type
+{current} and \type {after} match. The replacements are specified with the \type
+{lookups} entry and the numbers are indices in the provided \type {lookups}
+table.
+
+Here is another example. This one demonstrates that one can check against spaces
+(some fonts kerns against them) and against boundaries as well. The later is
+something \CONTEXT\ specific. First we define a feature that create ligatures but
+only when we touch a space:
+
+\startbuffer
+\startluacode
+ fonts.handlers.otf.addfeature {
+ name = "test-a",
+ type = "chainsubstitution",
+ lookups = {
+ {
+ type = "ligature",
+ data = {
+ ['1'] = { "a", "b" },
+ ['2'] = { "c", "d" },
+ },
+ },
+ },
+ data = {
+ rules = {
+ {
+ before = { { " " } },
+ current = { { "a" }, { "b" } },
+ lookups = { 1 },
+ },
+ {
+ current = { { "c" }, { "d" } },
+ after = { { " " } },
+ lookups = { 1 },
+ },
+ },
+ },
+ }
+\stopluacode
+\stopbuffer
+
+\typebuffer \getbuffer
+
+The next example also checks against whatever boundary we have.
+
+\startbuffer
+\startluacode
+ fonts.handlers.otf.addfeature {
+ name = "test-b",
+ type = "chainsubstitution",
+ lookups = {
+ {
+ type = "ligature",
+ data = {
+ ['1'] = { "a", "b" },
+ ['2'] = { "c", "d" },
+ },
+ },
+ },
+ data = {
+ rules = {
+ {
+ before = { { " ", 0xFFFC } },
+ current = { { "a" }, { "b" } },
+ lookups = { 1 },
+ },
+ {
+ current = { { "c" }, { "d" } },
+ after = { { 0xFFFC, " " } },
+ lookups = { 1 },
+ },
+ },
+ },
+ }
+\stopluacode
+\stopbuffer
+
+\typebuffer \getbuffer
+
+We can actually simplify this one to:
+
+\startbuffer
+\startluacode
+ fonts.handlers.otf.addfeature {
+ name = "test-c",
+ type = "chainsubstitution",
+ lookups = {
+ {
+ type = "ligature",
+ data = {
+ ['1'] = { "a", "b" },
+ ['2'] = { "c", "d" },
+ },
+ },
+ },
+ data = {
+ rules = {
+ {
+ before = { { 0xFFFC } },
+ current = { { "a" }, { "b" } },
+ lookups = { 1 },
+ },
+ {
+ current = { { "c" }, { "d" } },
+ after = { { 0xFFFC } },
+ lookups = { 1 },
+ },
+ },
+ },
+ }
+\stopluacode
+\stopbuffer
+
+\typebuffer \getbuffer
+
+As a bonus we show how to do more complex things:
+
+\startbuffer
+\startluacode
+ fonts.handlers.otf.addfeature {
+ name = "test-d",
+ type = "chainsubstitution",
+ lookups = {
+ {
+ type = "substitution",
+ data = {
+ ["a"] = "A",
+ ["b"] = "B",
+ ["c"] = "C",
+ ["d"] = "D",
+ },
+ },
+ {
+ type = "ligature",
+ data = {
+ ['1'] = { "a", "b" },
+ ['2'] = { "c", "d" },
+ },
+ },
+ },
+ data = {
+ rules = {
+ {
+ before = { { 0xFFFC } },
+ current = { { "a" }, { "b" } },
+ lookups = { 2 },
+ },
+ {
+ current = { { "c" }, { "d" } },
+ after = { { 0xFFFC } },
+ lookups = { 2 },
+ },
+ {
+ current = { { "a" } },
+ after = { { "b" } },
+ lookups = { 1 },
+ },
+ {
+ current = { { "c" } },
+ after = { { "d" } },
+ lookups = { 1 },
+ },
+ },
+ },
+ }
+\stopluacode
+\stopbuffer
+
+\typebuffer \getbuffer
+
+\definefontfeature[test-a][test-a=yes]
+\definefontfeature[test-b][test-b=yes]
+\definefontfeature[test-c][test-c=yes]
+\definefontfeature[test-d][test-d=yes]
+
+\startbuffer
+abababcdcd abababcdcd abababcdcd
+\stopbuffer
+
+With the test text:
+
+\typebuffer
+
+These four result in:
+
+\blank \start
+
+ \definedfont[file:dejavu-serif.ttf*default]
+
+ \start \addff{test-a} \getbuffer \stop\par
+ \start \addff{test-b} \getbuffer \stop\par
+ \start \addff{test-c} \getbuffer \stop\par
+ \start \addff{test-d} \getbuffer \stop\par
+
+\stop \blank
+
+\stopsubsection
+
+\startsubsection[title={Language dependencies}]
+
+When \OPENTYPE\ was not around we only had to deal with ligatures, smallcaps and
+oldstyle and of course kerns. Their number was so small that the term \quote
+{features} was not even used. In practice one just loaded a font that had
+oldstyle or smallcaps or none of that and was done. There were different fonts and
+sold separately.
+
+In \OPENTYPE\ we have more variation and although these fonts can be much more
+advanced the lack of standardization (for instance what gets initialized, or what
+shapes are in the default slots) can lead to messy setups. Some fonts bind
+features to scripts, some don't, which means that:
+
+\starttyping
+\definefontfeature[smallcaps][smcp=yes,script=dflt]
+\definefontfeature[smallcaps][smcp=yes,script=latn]
+\definefontfeature[smallcaps][smcp=yes,script=cyrl]
+\stoptyping
+
+are in fact different and you don't know in advance if you need to specify \type
+{dflt} or \type {latn}. In practice for a feature like smallcaps there is no
+difference between languages, but for ligatures there can be.
+
+When we extend an existing feature we can think of:
+
+\starttyping
+\definefontfeature[smallcaps][default][smcp=yes,script=auto]
+\definefontfeature[smallcaps][default][smcp=yes,script=*]
+\stoptyping
+
+but that can have side effects too (for instance disabling language specific
+features). The easiest way to explore this language dependency is to make
+a feature of our own.
+
+\startbuffer
+\startluacode
+fonts.handlers.otf.addfeature {
+ name = "simplify",
+ type = "multiple",
+ prepend = true,
+ features = {
+ ["*"] = {
+ ["deu"] = true
+ }
+ },
+ data = {
+ [utf.byte("ä")] = { "a", "e" },
+ [utf.byte("Ä")] = { "A", "E" },
+ [utf.byte("ü")] = { "u", "e" },
+ [utf.byte("Ü")] = { "U", "E" },
+ [utf.byte("ö")] = { "o", "e" },
+ [utf.byte("Ö")] = { "O", "E" },
+ [utf.byte("ß")] = { "s", "z" },
+ [utf.byte("ẞ")] = { "S", "Z" },
+ },
+}
+\stopluacode
+\stopbuffer
+
+\typebuffer \getbuffer
+
+Here we implement a language specific feature that we use at the \TEX\ end:
+
+\startbuffer
+\definefontfeature
+ [simplify-de]
+ [simplify=yes,
+ language=deu]
+\stopbuffer
+
+\typebuffer \getbuffer
+
+that we can use as:
+
+\startbuffer
+\definedfont[Serif*default,simplify-de]%
+äüöß
+{\de äüöß}
+{\nl äüöß}
+\stopbuffer
+
+\typebuffer
+
+and get: \start \maincolor \inlinebuffer \stop, but as you see, both German and
+Dutch get the same treatment, which might not be what you want, because in Dutch
+the diearesis has a different meaning.
+
+\startbuffer
+\definedfont[Serif*default]%
+ äüöß
+{\de\addff{simplify-de}äüöß}
+{\nl äüöß}
+\stopbuffer
+
+\typebuffer
+
+The above is restricts the usage so now we get: \start \maincolor \inlinebuffer
+\stop, which is more language bound. You don't need much imagination for
+extending this:
+
+\startbuffer
+\definefontfeature
+ [simplify]
+ [simplify=yes,
+ language=deu]
+\stopbuffer
+
+\typebuffer \getbuffer
+
+\startbuffer
+\definedfont[Serif*default]%
+ äüöß
+{\de\addff{simplify}äüöß}
+{\nl\addff{simplify}äüöß}
+\stopbuffer
+
+So what do we expect with the next?
+
+\typebuffer
+
+We get: \start \maincolor \inlinebuffer \stop, and we see that the language
+setting is not taken into account! This is because the font already has been set
+up with a script and language combination. The solution is to temporary set the
+font related language explicitly:
+
+\definefontfeature
+ [simplify]
+ [simplify=yes]
+
+\startbuffer
+\definedfont[Serif*default]%
+ äüöß
+{\de\addfflanguage\addff{simplify}äüöß}
+{\nl\addfflanguage\addff{simplify}äüöß}
+\stopbuffer
+
+\typebuffer
+
+So we can automatically switch to language specific features if we want to:
+\start \maincolor \inlinebuffer \stop.
+
+Let's now move to another level of complexity: support for more than one language
+as in fact this example was made for Dutch in the first place, but the German
+outcome is a bit more visible.
+
+\startbuffer
+\startluacode
+fonts.handlers.otf.addfeature {
+ name = "simplify",
+ type = "multiple",
+ prepend = true,
+ -- prepend = "smcp",
+ dataset =
+ {
+ {
+ features = {
+ ["*"] = {
+ ["nld"] = true
+ }
+ },
+ data = {
+ -- [utf.byte("ä")] = { "a" },
+ -- [utf.byte("Ä")] = { "A" },
+ -- [utf.byte("ü")] = { "u" },
+ -- [utf.byte("Ü")] = { "U" },
+ -- [utf.byte("ö")] = { "o" },
+ -- [utf.byte("Ö")] = { "O" },
+ [utf.byte("ij")] = { "i", "j" },
+ [utf.byte("IJ")] = { "I", "J" },
+ [utf.byte("æ")] = { "a", "e" },
+ [utf.byte("Æ")] = { "A", "E" },
+ },
+ },
+ {
+ -- type = "multiple", -- local values possible
+ features = {
+ ["*"] = {
+ ["deu"] = true
+ }
+ },
+ data = {
+ [utf.byte("ä")] = { "a", "e" },
+ [utf.byte("Ä")] = { "A", "E" },
+ [utf.byte("ü")] = { "u", "e" },
+ [utf.byte("Ü")] = { "U", "E" },
+ [utf.byte("ö")] = { "o", "e" },
+ [utf.byte("Ö")] = { "O", "E" },
+ [utf.byte("ß")] = { "s", "z" },
+ [utf.byte("ẞ")] = { "S", "Z" },
+ },
+ }
+ }
+}
+\stopluacode
+\stopbuffer
+
+\typebuffer \getbuffer
+
+For this we use the following example:
+
+\startbuffer
+\definedfont[Serif*default,simplify]%
+ äüöß ijæ
+{\de\addfflanguage äüöß ijæ}
+{\nl\addfflanguage äüöß ijæ}
+\stopbuffer
+
+\typebuffer
+
+Because the Dutch is hard to check we use an \type {æ} replacement too and
+commented the similarities with German: \start \maincolor \inlinebuffer \stop.
+But still we're not done, say that we want smallcaps too:
+
+\startbuffer
+\definefontfeature[alwayssmcp][smcp=always]%
+\definedfont[Serif*default,simplify,alwayssmcp]%
+ äüöß ijæ
+{\de\addfflanguage äüöß ijæ}
+{\nl\addfflanguage äüöß ijæ}
+\stopbuffer
+
+\typebuffer
+
+This comes out as: \start \maincolor \inlinebuffer \stop.
+
+The reason for specifying \type{smcp} as \type {always} is that otherwise we
+get language specific smallcaps while often they are not bound to a language
+but to the defaults. The good news is that we can do this automatically:
+
+\startbuffer
+\setupfonts[language=auto]%
+\definefontfeature[alwayssmcp][smcp=always]%
+\definedfont[Serif*default,simplify,alwayssmcp]%
+ äüöß ijæ
+{\de äüöß ijæ}
+{\nl äüöß ijæ}
+\stopbuffer
+
+\typebuffer
+
+But be aware that this applies to all situations. Here we get: \start \maincolor
+\inlinebuffer \stop.
+
+\stopsubsection
+
+\startsubsection[title=Syntax summary]
+
+In the examples we have seen several ways to define features. One of the
+differences is that you either set a \type {data} field directly, or that you
+specify a dataset. The fields in a dataset entry overload the ones given at the
+top level or when not set the top level value will be taken. There is a bit
+of (downward compatibility) tolerance built in, but best not depend on that.
+
+\starttyping
+fonts.handlers.otf.addfeature {
+ name = "demo",
+ features = {
+ [<script>] = {
+ [<language>] = true
+ }
+ },
+ prepend = true | featurename | position,
+ dataset = {
+ {
+ type = "substitution",
+ data = {
+ [<char|code>] = <char|code>,
+ }
+ },
+ {
+ type = "alternate",
+ data = {
+ [<char|code>] = { <char|code>, <char|code>, ... },
+ }
+ },
+ {
+ type = "multiple",
+ data = {
+ [<char|code>] = { <char|code>, <char|code>, ... },
+ }
+ },
+ {
+ type = "ligature",
+ data = {
+ [<char|code>] = { <char|code>, <char|code>, ... },
+ }
+ },
+ {
+ type = "kern",
+ data = {
+ [<char|code>] = { [<char|code>] = <value> },
+ }
+ },
+ {
+ type = "pair",
+ data = {
+ [<char|code>] = {
+ [<char|code>] = {
+ false | { <value>, <value>, <value>, <value> },
+ false | { <value>, <value>, <value>, <value> }
+ }
+ }
+ }
+ },
+ {
+ type = "chainsubstitution",
+ lookups = {
+ {
+ type = <typename>,
+ data = <mapping>,
+ },
+ },
+ data = {
+ rules = {
+ {
+ before = { { [<char|code>], ... } },
+ current = { { [<char|code>], ... } },
+ after = { { [<char|code>], ... } },
+ lookups = { <index>, ... },
+ },
+ },
+ },
+ },
+ },
+}
+\stoptyping
+
+\stopsubsection
+
+\startsubsection[title=Extra characters]
+
+\startbuffer[hyphenchars]
+\startluacode
+
+ local privateslots = fonts.constructors.privateslots
+
+ local function addspecialhyphen(tfmdata)
+
+ local exheight = tfmdata.parameters.xheight
+ local emwidth = tfmdata.parameters.quad
+ local width = emwidth / 4
+ local height = exheight / 10
+ local depth = exheight / 2
+ local offset = emwidth / 6
+
+ tfmdata.characters[privateslots.righthyphenchar] = {
+ -- no dimensions
+ commands = {
+
+ { "right", offset },
+
+ { "push" },
+ { "right", -width },
+ { "down", depth },
+ { "rule", height, width },
+ { "pop" },
+
+ { "right", -width/5 },
+ { "down", depth + height },
+ { "rule", 3*height, width/5 },
+
+ }
+ }
+
+ tfmdata.characters[privateslots.lefthyphenchar] = {
+ -- no dimensions
+ commands = {
+
+ { "right", -offset },
+
+ { "push" },
+ { "down", depth + height },
+ { "rule", 3*height, width/5 },
+ { "pop" },
+
+ { "down", depth },
+ { "rule", height, width },
+
+ }
+ }
+
+ end
+
+ fonts.constructors.features.otf.register {
+ name = "specialhyphen",
+ description = "special hyphen",
+ manipulators = {
+ base = addspecialhyphen,
+ node = addspecialhyphen,
+ }
+ }
+
+\stopluacode
+\stopbuffer
+
+You can add virtual characters to fonts. Here we give an example that is derived
+from an example posted on the mailing list. By default, when we hyphenated a word,
+we get this:
+
+\definefont[DemoFont] [Serif*default]
+
+\blank \start \DemoFont \maincolor \hsize 1mm averylongword \par \stop \blank
+
+The default character that is appended at the end and beginning of a line
+can be specified as follows:
+
+\startbuffer
+\setuplanguage
+ [en]
+ [righthyphenchar=45,
+ lefthyphenchar=45]
+\stopbuffer
+
+\typebuffer
+
+So now we get:
+
+\blank \start \getbuffer \DemoFont \maincolor \hsize 1mm averylongword \par \stop \blank
+
+Say that we want a different signal, for instance some rule. Here is how that can
+be done:
+
+\typebuffer[hyphenchars]
+
+\getbuffer[hyphenchars]
+
+Watch the way we use private slots. You can best use a unique glyph name as these
+numbers are shared between fonts. With:
+
+\startbuffer
+\definefontfeature
+ [default]
+ [default]
+ [specialhyphen=yes]
+\definefont
+ [DemoFont]
+ [Serif*default at 24pt]
+\setuplanguage
+ [en]
+ [righthyphenchar=\getprivateglyphslot{righthyphenchar},
+ lefthyphenchar=\getprivateglyphslot{lefthyphenchar}]
+\stopbuffer
+
+\typebuffer
+
+We get:
+
+\startlinecorrection[blank]
+\getbuffer
+\framed
+ [foregroundstyle=\DemoFont \setupinterlinespace,
+ offset=none,
+ frame=no,
+ width=1mm,
+ align={flushleft}]
+ {\hsize 1mm \maincolor averylongword\par}
+\stoplinecorrection
+
+You need to keep in mind that some of these settings are global but in practice that is
+not a real problem. Here is how you reset:
+
+\startbuffer
+\definefontfeature
+ [default]
+ [default]
+ [specialhyphen=no]
+\setuplanguage
+ [en]
+ [righthyphenchar=45,
+ lefthyphenchar=0]
+\stopbuffer
+
+\typebuffer \getbuffer
+
+\stopsubsection
+
+\startsubsection[title=Goodies]
+
+The examples above extend a font in the \TEX\ document (normally a style) but you
+can use a goodies file too, for instance \type {cambria.lfg}.
+
+\starttyping
+return {
+ name = "cambria",
+ version = "1.00",
+ comment = "Goodies that complement cambria.",
+ author = "Hans Hagen",
+ copyright = "ConTeXt development team",
+ extensions = {
+ {
+ name = "kern", -- adds to kerns
+ type = "pair",
+ data = {
+ [0x0153] = { -- combining acute
+ [0x0301] = { -- aeligature
+ false,
+ { -500, 0, 0, 0 }
+ }
+ },
+ }
+ }
+ }
+}
+\stoptyping
+
+Here we use the feature name \type {kern} and therefore we don't have to define a
+specific (new) feature for it. Such a goodie is then used as follows:
+
+\starttyping
+\definefontsynonym
+ [Serif]
+ [cambria]
+ [features=default,
+ goodies=cambria]
+\stoptyping
+
+You can find such definitions in the \type {type-imp-*.mkiv} files.
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title=Spacing]
+
+% By default the font loader deduces the spacing from the space character or
+% other font properties. You can influence this by the \type {space} feature.
+%
+% \starttyping
+% \definefontfeature
+% [korean]
+% [default]
+% [script=hang,
+% language=kor,
+% space=local] % or locl
+% \stoptyping
+%
+% Instead of the usual \type {yes} (which means: use character 32), \type {local}
+% or \type {locl} (which means: use a replacement provided by the \type{locl}
+% feature), you can also pass a character, so
+%
+% \starttyping
+% \definefontfeature
+% [spacy]
+% [default]
+% [space=A]
+% \stoptyping
+%
+% is valid.
+
+As you probably know, \TEX\ has no space character. When the input is read,
+characters tagged as space are intercepted and become glue. Compare this:
+
+\startlinecorrection[blank]
+ \startcombination
+ {\framed
+ [width=3cm,height=15mm,align={middle,lohi},foregroundcolor=maincolor]
+ {\dorecurse{5}{test }}}
+ {\type{text test...}}
+ {\framed
+ [width=3cm,height=15mm,align={middle,lohi},foregroundcolor=maincolor]
+ {\dorecurse{5}{test\char32\relax}}}
+ {\type{text\char32test...}}
+ \stopcombination
+\stoplinecorrection
+
+Most fonts have a space character and you can actually use it and indeed a space
+character will be injected but as it is not glue, the line break algorithm will
+not see it as space.
+
+Al the magic done with space characters other than the native space character
+(decimal 32) are at some point translated into glue.
+
+\starttabulate[||T|p|]
+\NC \bf command \NC \UNICODE \NC width \NC \NR
+
+\NC \type{\nobreakspace}
+ \type{\nbsp} \NC U+00A0 \NC space \NC \NR
+\NC \type{\ideographicspace} \NC U+2000 \NC quad/2 \NC \NR
+\NC \type{\ideographichalffillspace} \NC U+2001 \NC quad \NC \NR
+\NC \type{\twoperemspace}
+ \type{\enspace} \NC U+2002 \NC quad/2 \NC \NR
+\NC \type{\emspace}
+ \type{\quad} \NC U+2003 \NC quad \NC \NR
+\NC \type{\threeperemspace} \NC U+2004 \NC quad/3 \NC \NR
+\NC \type{\fourperemspace} \NC U+2005 \NC quad/4 \NC \NR
+\NC \type{\fiveperemspace} \NC \NC quad/5 \NC \NR
+\NC \type{\sixperemspace} \NC U+2006 \NC quad/6 \NC \NR
+\NC \type{\figurespace} \NC U+2007 \NC width of zero \NC \NR
+\NC \type{\punctuationspace} \NC U+2008 \NC width of period \NC \NR
+\NC \type{\breakablethinspace} \NC U+2009 \NC quad/8 \NC \NR
+\NC \type{\hairspace} \NC U+200A \NC quad/8 \NC \NR
+\NC \type{\zerowidthspace} \NC U+200B \NC 0 \NC \NR
+\NC \type{\zerowidthnonjoiner}
+ \type{\zwnj} \NC U+200C \NC 0 \NC \NR
+\NC \type{\zerowidthjoiner}
+ \type{\zwj} \NC U+200D \NC 0 \NC \NR
+\NC \type{\narrownobreakspace} \NC U+202F \NC quad/8 \NC \NR
+\NC \type{\zerowidthnobreakspace} \NC U+FEFF \NC \NC \NR
+\NC \type{\optionalspace} \NC \NC space when not followed by punctuation \NC \NR
+\stoptabulate
+
+% "205F % space/8 (math)
+
+The last one is not un \UNICODE\ and the fifths of an emspace is not in \UNICODE\
+either. This emspace (or quad in \TEX\ speak) is a font property. The width of
+the space used by \CONTEXT\ is dreived form this value. In case of a monospace
+fonts, the following logic is applied:
+
+\startitemize
+ \startitem
+ When there is a space character, the width of that character is used.
+ \stopitem
+ \startitem
+ Otherwise, when there is an emdash present, the width if that character
+ is used.
+ \stopitem
+ \startitem
+ Otherwise, when there is an \type {charwidth} property available (the
+ average width), that valua is used.
+ \stopitem
+\stopitemize
+
+When a proportional font is used, we do as follows:
+
+\startitemize
+ \startitem
+ When there is a space character, the width of that character is used.
+ \stopitem
+ \startitem
+ Otherwise, when there is an emdash present, the width of that character
+ divided by two is used.
+ \stopitem
+ \startitem
+ Otherwise, when there is an \type {charwidth} property available (the
+ average width), that value is used.
+ \stopitem
+\stopitemize
+
+In both cases, when no value is set we use the units of the font (often 1000 or
+2048). In \TEX\ a space glue also has stretch and shrink. Here we follow the
+traditional \TEX\ logic:
+
+\startitemize
+ \startitem
+ The stretch is set to half the width of a space but to zero with a mono
+ spaced font.
+ \stopitem
+ \startitem
+ The shrink is set to one third of the width of a space but to zero with a
+ mono spaced font.
+ \stopitem
+\stopitemize
+
+The xheight is set to the values specified by the font and when this is unset the
+height of the character \type {x} will be used but when this character is not in
+the font, we use two fifths of the font's units (normally the same as the
+emwidth). The italic angle is also taken from the font (and is of course zero for
+a not italic font). Most fonts have these properties set so we seldom have to
+fall back to a guess.
+
+\stopsection
+
+\startsection[title=Ligatures]
+
+Not all fonts provide ligature control (normally related to languages), so here is a
+trick.
+
+\starttyping
+\blockligatures[fi,ff]
+\blockligatures[fl]
+
+\definefontfeature
+ [default]
+ [default]
+ [blockligatures=yes]
+
+\setupbodyfont[pagella]
+
+...
+\stoptyping
+
+This way it works globally. Of course you can also bind it to a font instance:
+
+\startbuffer
+\blockligatures[fi,fl]
+
+\definefontfeature
+ [default:blockligs]
+ [default]
+ [blockligatures=yes]
+
+\definefont[DemoBlockY][Serif*default:blockligs at 20pt]
+\definefont[DemoBlockN][Serif*default at 20pt]
+
+Here we have no ligatures: {\DemoBlockY fi ff fl}, while here we get
+them: {\DemoBlockN fi ff fl}. Of course it also depends on the font.
+\stopbuffer
+
+\typebuffer \start \showfontkerns \getbuffer \par \stop
+
+There is one limitation: you need to specify the blocked ligatures before a font
+gets defined and because we share resources it even has to happen before the
+first font gets loaded. So, the \type {\blockligatures} commands go before
+setting up the body font. This is no real problem because it's a hack anyway.
+
+The next example combines several tricks:
+
+\startbuffer[definitions]
+\startluacode
+ fonts.handlers.otf.addfeature {
+ name = "kernligatures",
+ type = "kern",
+ data = {
+ f = { i = 50, l = 50 },
+ }
+ }
+\stopluacode
+
+\blockligatures[u:fl:a]
+
+\definefontfeature[default:b][default][blockligatures=yes]
+\definefontfeature[default:k][default][blockligatures=yes,kernligatures=yes]
+
+\showfontkerns
+\stopbuffer
+
+\startbuffer[demo]
+{\definedfont[Brill*default @ 11pt]auflage}\par
+{\definedfont[Brill*default:b @ 11pt]auflage}\par
+{\definedfont[Brill*default:k @ 11pt]auflage}\par
+\stopbuffer
+
+\typebuffer[definitions,demo] \getbuffer[definitions]
+
+\startlinecorrection
+ \externalfigure[demo.buffer][width=4cm]
+\stoplinecorrection
+
+Processing fonts is complicated by the fact that a text can be hyphenated. This
+complicates for instance ligature building which can cross the pre, post and|/|or
+replace bounds. The current implementation does a decent job although there will
+always be border cases. And, figuring out what goes wrong is a pain. There are
+several ways to trace what happens and here's one. As mentioned, blocking only
+works when we haven't not yet defined a font instance, so we use a funny size
+here.
+
+\startbuffer
+\blockligatures[u:fl:a]
+
+\definefontfeature
+ [blockligatures]
+ [default]
+ [blockligatures=yes]
+
+\startotfcompositionlist{texgyrepagella-regular*blockligatures @ 14.5pt}{l2r}
+ \HL
+ \showotfcompositionsample{auflage}
+ \showotfcompositionsample{a\discretionary{-}{}{}uflage}
+ \showotfcompositionsample{au\discretionary{-}{}{}flage}
+ \showotfcompositionsample{auf\discretionary{-}{}{}lage}
+ \showotfcompositionsample{aufl\discretionary{-}{}{}age}
+ \showotfcompositionsample{aufla\discretionary{-}{}{}ge}
+ \showotfcompositionsample{auflag\discretionary{-}{}{}e}
+ \HL
+ \showotfcompositionsample{auflegt}
+ \showotfcompositionsample{a\discretionary{-}{}{}uflegt}
+ \showotfcompositionsample{au\discretionary{-}{}{}flegt}
+ \showotfcompositionsample{auf\discretionary{-}{}{}legt}
+ \showotfcompositionsample{aufl\discretionary{-}{}{}egt}
+ \showotfcompositionsample{aufle\discretionary{-}{}{}gt}
+ \showotfcompositionsample{aufleg\discretionary{-}{}{}t}
+ \HL
+\stopotfcompositionlist
+\stopbuffer
+
+\typebuffer \getbuffer
+
+Here is another example. This one demonstrates that ligatures can force
+collapsing of discretionaries.
+
+\startbuffer
+\startotfcompositionlist{Serif*default @ 11pt}{l2r}
+ \HL
+ \showotfcompositionsample{effe}
+ \showotfcompositionsample{efficient}
+ \HL
+\stopotfcompositionlist
+\stopbuffer
+
+\typebuffer \getbuffer
+
+\stopsection
+
+\startsection[title=Collections]
+
+ {\em Todo.}
+
+\stopsection
+
+\stopchapter
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-features.tex b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-features.tex
new file mode 100644
index 00000000000..bf9f39385df
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-features.tex
@@ -0,0 +1,2742 @@
+% language=uk
+
+\startcomponent fonts-features
+
+\environment fonts-environment
+
+% windows: seguiemj.ttf (windows 10)
+% public : emojionecolor-svginot.ttf (https://github.com/eosrei/emojione-color-font)
+
+\startMPextensions
+ vardef MyRectangle(expr n, w, h, x, y, c) =
+ image (
+ fill unitsquare xyscaled (w,h) shifted (x,y) withcolor c ;
+ draw textext("\tttf " & decimal n) xsized (1/2) shifted (w/2,h/2) shifted (x,y) withcolor white ;
+ )
+ enddef ;
+ vardef MyDot(expr x, y) =
+ image (
+ draw (x,y) withpen pencircle scaled (2/3) withcolor white ;
+ draw (x,y) withpen pencircle scaled (1/2) withcolor black ;
+ )
+ enddef ;
+\stopMPextensions
+
+\startchapter[title=Features][color=darkmagenta]
+
+\startsection[title=Introduction]
+
+If you look into fonts, it is hard not to bump into kerns (spacing between
+characters) and ligatures (combining multiple shapes into one) and apart from
+monospaced fonts most \TYPEONE\ fonts have them. In the \OPENTYPE\ universe we
+call these properties features and in such a font there can be many such
+features.
+
+For those who grew up with \TEX\ or still remember the times of eight bit fonts,
+it is no secret that \TEX\ macro packages did some magic to get most out of a
+font: replacing missing glyphs, fixing metrics, using commands to access shapes
+that had a weird code point, to mention a few. As there is absolutely no
+guarantee that an \OPENTYPE\ font does better, there is a good reason to continue
+messing around with fonts. After all, it's what \TEX\ users seem to like:
+control.
+
+So, when we started writing support for \OPENTYPE\ quite soon a mechanism has
+been created that permits adding our own features to the repertoire that comes
+with a font. Because \OPENTYPE\ features demand a configuration and control
+mechanism, it made sense to generalize that and provide a single interface.
+
+This means that when we talk about font features, we don't limit ourselves to
+those provided by the font, but also those provided by \CONTEXT. As with font
+features, they are enabled per font.
+
+Some of the extra features are sort of generic, others are very font specific and
+their properties are somewhat bound to a font. Such features are defined in a
+font goodie files. Consider these goodies a font extension mechanism.
+
+Some features need information that only the engine can provide. This is why we
+have analyzers. Some are generic, others are bound to scripts. They come in
+action before features are applied. Rather special is applying features in
+combination with paragraph building. This is something very specific to \CONTEXT\
+but it depends on properties of the font. It falls into the category \quote
+{optimizing}.
+
+It is clear that when we talk of features many aspects of a font play a role. In
+this chapter we will discuss all the mentioned aspects. There is quite a bit of
+\LUA\ code shown in this chapter, but don't worry, users will seldom need to
+tweak fonts this way. On the other hand it's good to see what is possible.
+
+\stopsection
+
+\startsection[title=Regulars]
+
+\startsubsection[title=Introduction]
+
+The \OPENTYPE\ specification, which can be found on the \MICROSOFT\ website
+is no easy reading. Some of the concepts are easy to understand, like relative
+positioning (that we call kerning in \TEX) or ligature substitution (as we
+have ligatures in \TEX\ too). It makes no sense to discuss the bitwise composition
+of an \OPENTYPE\ or \TRUETYPE\ file here. First of all, all we get to see is
+a \LUA\ table, and in \CONTEXT\ even that one gets sanitized and optimized
+into a more useable table. However, as the data that comes with a font is
+a good indication of what a font is capable of, we will discuss some of it in
+an appendix. In this section we will discuss the basic principles and categories
+of features.
+
+\stopsubsection
+
+\startsubsection[title=Feature sets]
+
+Because in the next examples we will demonstrate features, we need to know how
+we can tell \CONTEXT\ what features to use. Although you can add explicit
+feature definitions to a font specification, I strongly advice you not to do this
+but use the more abstract mechanism of feature sets. These are defined as follows:
+
+\starttyping
+\definefontfeature
+ [MyFeatureSet]
+ [alpha=yes,
+ beta=no,
+ gamma=123]
+\stoptyping
+
+Such a set is bound to a font with the \type {*} specifier, as in:
+
+\starttyping
+\definefont
+ [MyFontInstance]
+ [MyNiceFont*MyFeatureSet at 12pt]
+\stoptyping
+
+In most cases the already defined \type {default} feature set will suffice. It often
+makes sense to use that one as base for new definitions:
+
+\starttyping
+\definefontfeature
+ [MyFeatureSet]
+ [default]
+ [alpha=yes,
+ beta=no,
+ gamma=123]
+\stoptyping
+
+The second argument can be a list, as in:
+
+\starttyping
+\definefontfeature
+ [MyFeatureSet]
+ [MyFirstSet,MySecondSet]
+ [alpha=yes,
+ beta=no,
+ gamma=123]
+\stoptyping
+
+Of course you need to know what features a font support, and one way to find
+out is:
+
+\starttyping
+mtxrun --script font --list --info --pattern=pagella
+\stoptyping
+
+Don't be too surprised if different fonts show different features and even similar
+features can be implemented differently. Sometimes you really need to know the font,
+but fortunately many fonts come with examples.
+
+There are many features and there values are kept with the font when it gets
+defined. This means that when you change a featureset, it will not affect already
+defined fonts. Because fonts are often defined on demand, you need to be aware of
+the fact that a redefinition of a featureset can have consequences for already
+defined fonts. For instance, a bodyfont switch only sets up the fonts and delays
+defining them.
+
+Although features are a sort of abstractions it can be interesting to see what features
+and values are actually used:
+
+\starttyping
+\usemodule[fonts-features] \showusedfeatures
+\stoptyping
+
+You will notice that we have more features than \OPENTYPE\ fonts can offer. This
+is because in \CONTEXT\ features is a more general concept.
+
+\showusedfeatures
+
+\stopsubsection
+
+\startsubsection[title=Main categories]
+
+There are two (but potentially more) main groups of features: those that deal
+with substitution, and those that lead to positioning. It is not really needed
+to know the gory details, but it helps to know at least a bit about them as
+it can help to track down issues with fonts.
+
+There are several substitutions possible:
+
+\startitemize[packed]
+\startitem a single substitution replaces one glyph by another \stopitem
+\startitem a multiple substitution replaces one glyph by one or more \stopitem
+\startitem a ligature substitution replaces multiple glyphs by one glyph \stopitem
+\startitem an alternate substitution replaces one glyph by one out of a set \stopitem
+\stopitemize
+
+Like it or not, but these categories are not always used as intended: they just
+are a way of replacing one or more glyphs by one or more other glyphs. This means
+that when for instance \type {ij} gets replaced by one glyph (given that the font
+supports it) a ligature substitution is used, even when in fact we have to do
+with a diftong that can be represented by one character.
+
+No matter what features you will use, keep in mind that they are nothing more
+than a combination of substitutions and positioning directives. So, the de facto
+standard ligature building feature \type {liga} indeed uses a ligature
+substitution, but other features with names that resemble no ligatures might use
+this substitution as well.
+
+An example of a single substitution is an oldstyle (\type {onum}) although it can
+as well be implemented as a choice out of alternate glyphs. Another example is
+smallcaps (\type {smcp}). Nowdays these are more or less standard features for a
+grown up font, while in the past they came as separate fonts. So, instead of loading
+an extra font, one sticks to one and selects the feature that does the
+substitution.
+
+A second category concerns relative positioning. Again we have several variants:
+
+\startitemize[packed]
+\startitem a single positioning moves a glyph over one of two axis and can change the width and|/|or height \stopitem
+\startitem a pair positioning also moved glyphs but concerns two adjacent glyphs \stopitem
+\startitem a cursive positioning operates on a range of glyphs and is used to visually connect them \stopitem
+\stopitemize
+
+In addition there are three ways to anchor marks onto glyphs:
+
+\startitemize[packed]
+\startitem a mark can be anchored on a base glyph \stopitem
+\startitem a mark can be anchored on a specific (visual) component of a ligature \stopitem
+\startitem a mark can be anchored on another mark \stopitem
+\stopitemize
+
+In base mode the single, alternate and ligature substitutions can rather easily
+be mapped onto the traditional \TEX\ font handling mechanism and this is what
+happens in base mode. A single substitution is just another instance of a glyph
+so there we just replace the original index into the glyph table by another one.
+In the case of an alternate we change the default index into one of several
+possible replacements in the alternate set. Ligatures can be mapped onto \TEX s
+ligature mechanism. The single positioning maps nicely on \TEX s kerning
+mechanism and pairwise positioning is not applicable in base mode. In node mode
+we don't do any remapping at loading time but delegate that to \LUA\ when
+processing the node lists.
+
+Marks are special in the sense that they normally only occur in scripts that also
+use substitution and positioning which in turn means that some more housekeeping
+is involved. After all, we need to keep track to what a mark applies. Of course a
+font can provide regular latin accents as marks but that is ill practice because
+cut and paste might not work out as expected. A proper font will support composed
+characters and provide glyphs that have the accents built in. Marks are not dealt
+with in base mode.
+
+Talking of complex scripts, the above set of operations is far from enough. Take
+for instance Arabic, where a sequence of 5~characters with 3~marks can easily
+become two glyphs glued together with two marks only. In the process we can have
+single substitutions, ligatures being built, marks being anchored and glyphs
+being cursively positioned. But, in order to do this well, some contextual
+analysis has to be done as well. Again we have several variants of this:
+
+\startitemize[packed]
+\startitem with contextual substitution a replacement takes place depending on a matching sequence of glyphs,
+optionally preceded or followed by matches \stopitem
+\startitem with contextual positioning shifting and anchoring happens based on a matching sequence of glyphs,
+optionally preceded or followed by matches \stopitem
+\startitem multiple contextual substitutions or positionings can be chained together \stopitem
+\startitem this can also happen in the reverse order (for right|-|to|-|left scripts) \stopitem
+\stopitemize
+
+In practice there is no fundamental difference between these and we can collapse
+them all in a sequence of lookups resulting in a sequence of whatever other
+manipulation is wanted.
+
+Given this, what is a feature? It's mostly a sequence of actions expressed in the
+above. And although there is a whole repertoire of semi|-|standardized features
+like \type {liga} and \type {onum}, there is no real hard coded support for them
+in \CONTEXT. Instead we have a generic feature processor that deals with all of
+them. A feature, say \type {abcd}, has a definition that boils down to a sequence
+of lookups. A lookup is just a name that is associated to one of the mentioned
+actions. So, \type {abcd} can do a decomposition (multiple substitution), then a
+replacement (single substitution) based on neighbouring glyphs, then do some
+ligature building (ligature substitution) and finally position the resulting
+glyphs relative to each other (like cursive positioning and anchoring marks).
+
+Imagine that we start out with 5 characters in the input. Instead of real glyphs
+we represent them by rectangles. The third one is a mark.
+
+\startlinecorrection
+\startMPcode
+ draw MyRectangle(1,2,6, 0,0,.5red ) ;
+ draw MyRectangle(2,2,4, 3,0,.5green ) ; draw MyDot(4,4.25) ;
+ draw MyRectangle(3,2,1, 6,5,.5blue ) ; draw MyDot(7,4.75) ;
+ draw MyRectangle(4,2,5, 9,0,.5yellow ) ;
+ draw MyRectangle(5,2,5,12,0,.5magenta) ;
+ currentpicture := currentpicture ysized(4cm) ;
+\stopMPcode
+\stoplinecorrection
+
+In the next variant we see that four and five have been replaced by
+number six. This is a ligature replacement.
+
+\startlinecorrection
+\startMPcode
+ draw MyRectangle(1,2,6,0,0,.5red ) ;
+ draw MyRectangle(2,2,4,3,0,.5green) ; draw MyDot(4,4.25) ;
+ draw MyRectangle(3,2,1,6,5,.5blue ) ; draw MyDot(7,4.75) ;
+ draw MyRectangle(6,3,5,9,0,.5cyan ) ;
+ currentpicture := currentpicture ysized(4cm) ;
+\stopMPcode
+\stoplinecorrection
+
+The mark is an independent entity. Sometimes it has a width, sometimes it hasn't.
+In both cases we can position it. Here we move the shape left and down. There are
+two ways to do this: simple pairwise kerning but better is to use anchors. Here
+we have one anchor per shape but there can be many.
+
+\startlinecorrection
+\startMPcode
+ draw MyRectangle(1,2,6,0,0 ,.5red ) ;
+ draw MyRectangle(2,2,4,3,0 ,.5green) ;
+ draw MyRectangle(3,2,1,3,4.5,.5blue ) ; draw MyDot(4,4.25) ;
+ draw MyRectangle(6,3,5,6,0 ,.5cyan ) ;
+ currentpicture := currentpicture ysized(4cm) ;
+\stopMPcode
+\stoplinecorrection
+
+Next we apply some kerning. Of course the anchored marks need to move as well.
+
+\startlinecorrection
+\startMPcode
+ draw MyRectangle(1,2,6,0, 0 ,.5red ) ;
+ draw MyRectangle(2,2,4,2.5,0 ,.5green) ;
+ draw MyRectangle(3,2,1,2.5,4.5,.5blue ) ; draw MyDot(3.5,4.25) ;
+ draw MyRectangle(6,3,5,5, 0 ,.5cyan ) ;
+ currentpicture := currentpicture ysized(4cm) ;
+\stopMPcode
+\stoplinecorrection
+
+Alternatively we can connect the shapes in a cursive way. The name cursive is
+somewhat misleading as it just boils down to shifting. The cursive indicates that
+the shifts accumulate within a word.
+
+\startlinecorrection
+\startMPcode
+ draw MyRectangle(1,2,6,0,0 ,.5red ) ;
+ draw MyRectangle(2,2,4,2,0.5,.5green) ;
+ draw MyRectangle(3,2,1,2,5 ,.5blue ) ; draw MyDot(3,4.75) ;
+ draw MyRectangle(6,3,5,4,1 ,.5cyan ) ;
+ currentpicture := currentpicture ysized(4cm) ;
+\stopMPcode
+\stoplinecorrection
+
+\stopsubsection
+
+\startsubsection[title={Single substitution}]
+
+Single substitutions are probably the most used ones. For instance, when you
+ask for small caps, a lot of glyphs get replaced. When using oldstyle numerals
+only digits get replaced but even then each glyph has to be checked. This can be
+demonstrated with the Latin Modern fonts.
+
+\startlinecorrection
+\scale
+ [height=1cm]
+ {\strut
+ {\definedfont[lmroman10-bold*default]\$123.45}%
+ \quad
+ {\definedfont[lmroman10-bold*oldstyle]\$123.45}}
+\stoplinecorrection
+
+As you can see here, Latin Modern has an oldstyle dollar sign. If you don't like
+that one, you're in troubles as it comes with the rest of the oldstyles. The only
+way out is to apply the oldstyle numerals to digits only which involves more tagging
+than you might be willing to add. So, whenever you choose a substitution, be aware
+that you have not that much control over what gets substituted: it's the font that
+drives it. Here are some examples:
+
+\starttyping
+\definefontfeature[capsandold][smallcaps,oldstyle]
+
+\showotfcomposition{dejavu-serif*capsandold at 24pt}{}{It's 2013!}
+\showotfcomposition{cambria*capsandold at 24pt}{}{It's 2013!}
+\showotfcomposition{lmroman10regular*capsandold at 24pt}{}{It's 2013!}
+\showotfcomposition{texgyrepagellaregular*capsandold at 24pt}{}{It's 2013!}
+\stoptyping
+
+\definefontfeature[capsandold][smallcaps,oldstyle]
+
+\blank \showotfcomposition{dejavu-serif*capsandold at 24pt}{}{\disabletrackers[otf.analyzing]\color[maincolor]{It's 2013!}} \blank
+\blank \showotfcomposition{cambria*capsandold at 24pt}{}{\disabletrackers[otf.analyzing]\color[maincolor]{It's 2013!}} \blank
+\blank \showotfcomposition{lmroman10regular*capsandold at 24pt}{}{\disabletrackers[otf.analyzing]\color[maincolor]{It's 2013!}} \blank
+\blank \showotfcomposition{texgyrepagellaregular*capsandold at 24pt}{}{\disabletrackers[otf.analyzing]\color[maincolor]{It's 2013!}} \blank
+
+\stopsubsection
+
+\startsubsection[title={Multiple substitution}]
+
+In a multiple substitution a sequence of characters (glyphs) gets replaced by
+another sequence. In fact, you might wonder why one||to||one, multiple||to||one
+and multiple||to||multiple are not all generalized into this variant. Efficiency
+is probably the main reason. \footnote {Isn't it strange that complex mechanisms
+are designed to save a few bytes while at the same time we produce ridiculous
+large pictures with cameras.} For instance the many||to||one is often used for
+ligatures (\type {liga}) and as a consequence \type {liga} is often misused also
+for non||ligatures.
+
+One usage of multiple replacements is to avoid and or undo other replacements. In
+the next example we see a language dependent \type {fi} ligature. Take the dutch
+\type {ij} and \type {ie} diftongs. Here we need to prevent the \type {i}
+becoming combined with the \type {f} as it would look weird. Among the solutions
+for this are: context dependent ligatures (which involves a lot of rules), or
+multiple to multiple replacements (looking at the \type {fij} sequence).
+
+\startbuffer[definitions]
+\definefontfeature[default-fijn-en][default][language=eng,script=latn]
+\definefontfeature[default-fijn-nl][default][language=nld,script=latn]
+\stopbuffer
+
+\getbuffer[definitions] \typebuffer[definitions]
+
+\starttyping
+\definedfont[lmroman10-regular*default-fijn-en]\en effe fijn fietsen
+\definedfont[lmroman10-regular*default-fijn-nl]\nl effe fijn fietsen
+\stoptyping
+
+This gives:
+
+\startlinecorrection[blank]
+\scale [width=\textwidth] \bgroup
+ \framed [offset=overlay,frame=off,foregroundcolor=maincolor,align=normal,strut=no] \bgroup
+ \definedfont[lmroman10-regular*default-fijn-en]\en effe fijn fietsen\vskip-1ex
+ \definedfont[lmroman10-regular*default-fijn-nl]\nl effe fijn fietsen\par
+ \egroup
+\egroup
+\stoplinecorrection
+
+Of course from this result one cannot see what (combination of) substitution(s)
+was used, but it's a nice exercise to work out a solution.
+
+Multiple substitutions are mostly used for scripts more complex than latin or
+special fonts like Zapfino where advanced contextual analysis happens.
+
+\stopsubsection
+
+\startsubsection[title={Alternate substitution}]
+
+Alternates are simple one||to||one substitutions. Popular examples are small
+capitials and oldstyle numerals.
+
+A nice application of alternates is the punk font. This font is a Knuth original.
+As part of experimenting with the \METAPOST\ library in the early days of
+\LUATEX\ and \MKIV, runtime randomization was implemented. However, that variant
+used virtual fonts and was somewhat resource hungry. So, in a later stage Khaled
+Hosny made an \OPENTYPE\ version using \METAPOST\ output. Randomization is
+implemented through the \type {rand} feature.
+
+In \MKIV\ the \type {rand} feature is not really special and behaves just like
+any other (stylistic) alternate. The only difference is that for this feature a
+value of \type {yes} equals \type {random}. This also means that any feature that
+uses alternates use them randomly.
+
+\startbuffer
+\definefontfeature[punknova-first] [mode=node,kern=yes,rand=first]
+\definefontfeature[punknova-2] [mode=node,kern=yes,rand=2]
+\definefontfeature[punknova-yes] [mode=node,kern=yes,rand=yes]
+\definefontfeature[punknova-random][mode=node,kern=yes,rand=random]
+\stopbuffer
+
+\typebuffer \getbuffer
+
+We use this is:
+
+\startbuffer[sample]
+The original punk font is designed by Don Knuth: xxxxxxxxxxxx
+\stopbuffer
+
+\startbuffer
+\definedfont[punknova-regular at 15pt] \getbuffer[sample]
+\definedfont[punknova-regular*punknova-first at 15pt] \getbuffer[sample]
+\definedfont[punknova-regular*punknova-2 at 15pt] \getbuffer[sample]
+\definedfont[punknova-regular*punknova-yes at 15pt] \getbuffer[sample]
+\definedfont[punknova-regular*punknova-random at 15pt] \getbuffer[sample]
+\stopbuffer
+
+\typebuffer[sample]
+
+\typebuffer
+
+In order to illustrate the variants we show a sequence of \type {x}'s. There are
+upto ten different variants per characters.
+
+\startlines[color=maincolor] \getbuffer \stoplines
+
+There is one pitfall with random alternates: if each run leads to a different
+outcome, we can end up in oscillation: different shapes give different paragraphs
+and we can get more pages or cross references etc.\ that can end up differently
+so this is why \CONTEXT\ always uses the same random seed (which gets reset when
+you purge the auxiliary files.
+
+\stopsubsection
+
+\startsubsection[title={Ligature substitution}]
+
+A ligature is traditionally a combination of several characters into one. Popular
+ligatures are \quote {fi}, \quote {fl}, \quote {ffi} and , \quote {ffl}.
+Occasionally we see \quote {\ae}, \quote {\oe} and some more. Often ligatures are
+language dependant. For instance in languages like Dutch and German there can be
+compound words where one part ends with an \type {f} and the next part starts with
+an \type {f} and that looks bad or at least not intuitive. To some extent one
+can wonder if this tradition of ligatures is a good one. It definitely made
+sense ages ago, but I wouldn't be surprised if they are often added to fonts
+because the encoding vectors have them. After all, nothing prevents to go ahead
+and come up with way more ligatures.
+
+There can be many ligature features in a font. Although we support arbitrary
+features, that is: those not registered as being official one way or the other,
+the following are known by description:
+
+\startluacode
+context.starttabulate { "|lTCT{maincolor}|l|" }
+for k, v in table.sortedhash(fonts.handlers.otf.tables.features) do
+ if string.find(v,"ligature") then
+ context.NC()
+ context(k)
+ context.NC()
+ context(v)
+ context.NR()
+ end
+end
+context.stoptabulate()
+\stopluacode
+
+The \type {default} feature set has type {liga} as wel as the \TEX\ specific \type {tlig}
+that replaces successive hyphen signs into en- and emdashes. The \type {arabic} feature
+set also has \type {rlig} enabled.
+
+Now, there is one thing you should realize when we discuss specific features and
+the underlaying mechanisms: there is no real relationship between the features's
+name and the mechanisms used: any feature can use any underlying mechanism or
+combination. This is why deep down we see that what is internally called ligature
+gets used for any purpose where multiple||to||one replacements happen, and why the
+\type {liga} feature can use single substitutions or alternates to swap in
+another rendering so that the dot of the \type {i} stays free of the preceding
+\type {f}. And for some fonts relative positioning can be used to achieve a
+ligature effect.
+
+The next examples demonstrate how the \type {liga} feature deals with \type {ffi}.
+Possible solutions are: replace all three at once, replace the first two first and
+in a next step, combine a ligature and following character, replace one or more
+components by variants that have no interference with the dot of the~\quote{i}.
+
+\starttyping
+\showotfcomposition{dejavu-serif*default at 48pt}{}{ffi}
+\showotfcomposition{cambria*default at 48pt}{}{ffi}
+\showotfcomposition{lmroman10regular*default at 48pt}{}{ffi}
+\showotfcomposition{texgyrepagellaregular*default at 48pt}{}{ffi}
+\stoptyping
+
+\blank \showotfcomposition{dejavu-serif*default at 48pt}{}{\disabletrackers[otf.analyzing]\color[maincolor]{ffi}} \blank
+\blank \showotfcomposition{cambria*default at 48pt}{}{\disabletrackers[otf.analyzing]\color[maincolor]{ffi}} \blank
+\blank \showotfcomposition{lmroman10regular*default at 48pt}{}{\disabletrackers[otf.analyzing]\color[maincolor]{ffi}} \blank
+\blank \showotfcomposition{texgyrepagellaregular*default at 48pt}{}{\disabletrackers[otf.analyzing]\color[maincolor]{ffi}} \blank
+
+\stopsubsection
+
+\startsubsection[title={Single positioning}]
+
+Single positioning is also known as kerning, moving characters closer together so
+that we get a more uniformly spaced sequence of glyphs. It is a mistake to think
+that kerning is always needed! There are fonts that have hardly any kerns or no
+kerns at all and still look good.
+
+\start
+ \showfontkerns \blank
+ \definedfont[dejavu-serif*default at 8pt]Dejavu Serif: \input tufte (E.R. Tufte)\blank
+ \definedfont[cambria*default at 9pt]Cambria: \input tufte (E.R. Tufte)\blank
+ \definedfont[lmroman10regular*default at 10pt]Latin Roman Regular: \input tufte (E.R. Tufte)\blank
+ \definedfont[lucidabrightot*default at 8pt]Lucida Bright: \input tufte (E.R. Tufte)\blank
+ \definedfont[texgyrepagellaregular*default at 9pt]Pagella Regular: \input tufte (E.R. Tufte)\blank
+\stop
+
+The next couple of examples show the action for a few words:
+
+\blank \showotfcomposition{dejavu-serif*default at 24pt}{}{\disabletrackers[otf.analyzing]\color[maincolor]{We thrive}} \blank
+\blank \showotfcomposition{cambria*default at 24pt}{}{\disabletrackers[otf.analyzing]\color[maincolor]{We thrive}} \blank
+\blank \showotfcomposition{lmroman10regular*default at 24pt}{}{\disabletrackers[otf.analyzing]\color[maincolor]{We thrive}} \blank
+\blank \showotfcomposition{lucidabrightot*default at 24pt}{}{\disabletrackers[otf.analyzing]\color[maincolor]{We thrive}} \blank
+\blank \showotfcomposition{texgyrepagellaregular*default at 24pt}{}{\disabletrackers[otf.analyzing]\color[maincolor]{We thrive}} \blank
+
+\stopsubsection
+
+\startsubsection[title={Pairwise positioning}]
+
+This variant of positioning involved the first, second or both glyphs of a glyph
+pair. The specification can influence the horizontal and vertical positions we
+well as the widths of the positioned glyphs.
+
+\startnotabene
+ We need an example here.
+\stopnotabene
+
+\stopsubsection
+
+\startsubsection[title={Mark positioning}]
+
+Marks are (often) small symbols that represent accents (in latin) or vowels (in
+arabic) that get attached to base glyphs. In the input stream they come after the
+character that they apply to. Many fonts come with precomposed latin characters
+which means that an \type {à} in the input is mapped directly onto its
+corresponding shape. When the input contains an \type {a} followed by a \type{̀ }
+input normalization will normally turn this into an \type {à}. But, when this
+doesn't happen, the font machinery has to make sure that the mark gets positioned
+right onto the base character. In traditional \TYPEONE\ fonts that more or less
+happened automatically by overlaying the shapes. In \OPENTYPE\ (single)
+positioning is used to place the mark right.
+
+\startnarrowtyping
+\showotfcomposition{dejavu-serif*default at 24pt}{}{à a\utfchar{"0300} à}
+\showotfcomposition{cambria*default at 24pt}{}{à a\utfchar{"0300} à}
+\showotfcomposition{lmroman10regular*default at 24pt}{}{à a\utfchar{"0300} à}
+\showotfcomposition{lucidabrightot*default at 24pt}{}{à a\utfchar{"0300} à}
+\showotfcomposition{texgyrepagellaregular*default at 24pt}{}{à a\utfchar{"0300} à}
+\stopnarrowtyping
+
+Of course a font can contain logic that replaces a sequence of base and mark into
+precomposed characters with the right \UNICODE\ entry.
+
+\blank \showotfcomposition{dejavu-serif*default at 24pt}{}{\disabletrackers[otf.analyzing]\color[maincolor]{à a\utfchar{"0300} à}} \blank
+\blank \showotfcomposition{cambria*default at 24pt}{}{\disabletrackers[otf.analyzing]\color[maincolor]{à a\utfchar{"0300} à}} \blank
+\blank \showotfcomposition{lmroman10regular*default at 24pt}{}{\disabletrackers[otf.analyzing]\color[maincolor]{à a\utfchar{"0300} à}} \blank
+\blank \showotfcomposition{lucidabrightot*default at 24pt}{}{\disabletrackers[otf.analyzing]\color[maincolor]{à a\utfchar{"0300} à}} \blank
+\blank \showotfcomposition{texgyrepagellaregular*default at 24pt}{}{\disabletrackers[otf.analyzing]\color[maincolor]{à a\utfchar{"0300} à}} \blank
+
+You can imagine that when marks are bound to characters that have become
+ligatures the anchoring is more complex as the font machinery has to keep track
+of onto which component the mark goes. For this purpose marks as well as base
+characters and base ligatures have anchors and feature lookups can explicitly
+refer to them.
+
+\stopsubsection
+
+\startsubsection[title={Contextual analysis}]
+
+What actually happens when turning a list of characters into a list of glyphs can
+range from real simple to pretty complex. For instance the \type {smcp} feature
+only has to run over the list and relate characters to a smallcaps shape. A
+slightly more complex feature might also demand some positioning. One step further
+is the use of contextual analysis, i.e. looking at previous, current and following
+characters (or glyphs). Because features can range from simple to complex the actual
+processing is not per feature! A font comes with a sequence of so called lookups that
+relate to a feature, script and language. Also, each feature can use one||to||one,
+multiple||to||one and many||to||many replacements as well as relative positioning.
+
+So, what actually happens is not that a feature is processed, but that all features
+are dealt with at the same time, in the order that the font prescribes. Enabling a
+specific feature means that a step is executed, while a disabled feature skips all
+steps that are tagged as belonging to that feature. And, as each feature can use
+contextual analysis, you can imagine that the effective sequence of actions can be
+a complex mix.
+
+A nice example of a contextual substitution is the centered period character in
+catalan in \type {ebgaramond}:
+
+\startbuffer
+\definefontfeature
+ [example]
+ [default]
+ [locl=yes,script=latn,language=cat]
+
+\definedfont[file:ebgaramond12-regular.otf*default at 40pt]l·l\quad
+\definedfont[file:ebgaramond12-regular.otf*example at 40pt]l·l
+\stopbuffer
+
+\typebuffer
+
+We show the boundingbox of the glyphs. The centered period between two l's is
+is replaced by a raised variant with no width.
+
+\blank \start \showglyphs \maincolor \midaligned{\getbuffer} \stop \blank
+
+It will be clear that in order to use such features you need to know what the font
+provides. For some fonts you need to explicitly enable the latin script (while others
+use default). Such a feature can be part of localized support but that is no rule.
+In that respect \OPENTYPE\ features are a rather unpredictable mess. For instance,
+nothing prevents such a feature to be a ligature, and in case you find that strange,
+especially ligature features are often abused for any purpose.
+
+\stopsubsection
+
+\startsubsection[reference=ligatures:hyphenation,title=Ligatures and hyphenation]
+
+In this section we will say a few words on how hyphenation interferes with
+(especially) ligature building. For this you need to know that:
+
+\starttyping
+effe
+\stoptyping
+
+But when hyphenation is permitted between the two \type{s}'s we actually have
+internally:
+
+\starttyping
+ef{-}{}{}fe
+\stoptyping
+
+The first snippet comes at the end of a line, the second at the beginning of a
+the next line and the last snippet is used when no hyphenation is needed. Such
+triplets need to be taken into account when we do replacements and positioning
+and also when we do contextual lookups.
+
+An \OPENTYPE\ font is just a container that collects the following:
+
+\startitemize[packed]
+\startitem
+ graphic representations of characters and symbols
+\stopitem
+\startitem
+ information about what characters the shapes represent
+\stopitem
+\startitem
+ rules about converting (sequences of) characters into one or more
+ representations
+\stopitem
+\startitem
+ rules about positioning representations relative to each other
+\stopitem
+\stopitemize
+
+Although the way this information is stored is standardized, the rules are not.
+You can imagine that there would be some standard way to turn an \type {f} and
+\type {i} into an \quote{fi} but we already saw that this is not the case. Here
+are some possibilities:
+
+\startitemize[packed]
+\startitem
+ The two characters get their own standard glyph, maybe with some kerning.
+\stopitem
+\startitem
+ The two characters are combined into one shape.
+\stopitem
+\startitem
+ The \type{f} gets a narrow representation and is kept close to the standard
+ \type{i}.
+\stopitem
+\startitem
+ A standard \type {f} is kerned with a dotless \type{i} (not to be confused
+ with the \UNICODE\ character).
+\stopitem
+\startitem
+ A special \type {f} is combined with a special \type {i}.
+\stopitem
+\stopitemize
+
+% maybe mark lig components when separate chars so that we can do spacing
+
+If the two characters are represented by their own shape, some contextual
+analysis takes place. Again there are several approaches to this:
+
+\startitemize[packed]
+\startitem
+ When an \type{f} is seen in the input, the next character is checked and one
+ or both gets replaced.
+\stopitem
+\startitem
+ When an \type{i} is seen in the input, the previous character is checked and
+ the \type {i} gets replaced.
+\stopitem
+\startitem
+ When an \type{f} several following characters are checked, for instance to
+ see if we need to take \type {ij} into account.
+\stopitem
+\stopitemize
+
+Traditionally the \type {f} followed by an \type{f}, \type{l} and \type{i} get a
+treatment, but some fonts also combine the \type {f} with \type {k}, \type {j},
+\type {b}, \type {t} and more.
+
+The \MKIV\ font handler is rather generic in the sense that it support what the
+font requires. However, a complication is that the scripts (languages) that use
+these diverse methods also expect hyphenation within such a ligature. Script like
+Arabic that are more demanding don't hyphenate so there interference with
+hyphenation is not a problem.
+
+Some ligatures are sensitive for languages. In languages that have compound words
+it might be undesirable to have a ligature at a word boundary, or in the Dutch
+word \type {fijn} we like to have a nice glyph (or combinations) for \type {ij}
+but no \type {fi} ligature. In a similar way hyphenation patterns can have
+rules and it will be no surprise that the hyphenation mechanism can compete with
+the ligature building for the best solution. This gets complicated by the fact
+that there is no real way to recognize in the font handler if we really are
+dealing with ligature building. Not only is the \type {liga} feature (and deep
+down the ligature gsub handling) not bound to ligatures (but simply a
+many|-|to|-|one mapper), some of the mentioned pseudo ligature builders use simple
+substitution and kerning and there is no way to recognize that as a ligature.
+
+Although it is possible to come up with a solution that is acceptable for many cases,
+there is no way to predict what kind of tricks font designers will use. A hyphenation
+point can be seen as follows:
+
+\starttabulate[||||]
+\NC \type{effe} \NC \type{ef-fe} \NC \type{e{f-}{f}{ff}e} \NC \NR
+\NC \type{efficient} \NC \type{ef-fi-cient} \NC \type{e{ffi-}{}{ffi}cient} \NC \NR
+\stoptabulate
+
+In the second case the larger ligatures has replaced the previous one. We could
+have kept the first one because there are ways to manage two|-|step bounding
+ligatures but it's not worth the trouble (read: way more complex code and
+increased runtime for the whole mechanism). Here the \type {{ff}} and \type
+{{ffi}} can be individual shapes or just one shape.
+
+The three components of a hyphenation point: the pre, post and replacement text
+need to be looked at independently so that we get the proper kerning with the
+preceding and following characters. Also, in more complex (chained) lookups we
+need to compare each element with its surrounding. A fully expanded solution tree
+is too time consuming so we take some shortcuts and limits the checks to the
+level that it has no big impact on performance. The occasionally needed
+backtracking and inspection of components is currently quite reasonable. We need
+to trade quality with convenience: the result should look okay but processing
+speed should also be as high as possible. There is no need to let other scripts
+or regular fonts suffer too much from excessive script demands of fonts that
+could have be done better.
+
+The complication is that we not only need to check and replace but also need to
+check the kerning with preceding and following characters. We also need to take
+the hyphen into account (here one, but there can also be one after the break.
+
+It is for this reason that in \MKIV\ we have a (we think) acceptable mix of
+heuristics around hyphenation points that deal with single and multiple
+substitution as well as kerning. It will never be 100\% pertect but we consider
+it better to drop an occasional hyphenation in favor of proper font handling. In
+practice \TEX\ is clever enough to break a paragraph in lines within these
+restrictions.
+
+In \CONTEXT\ we have the traditional \TEX\ hyphenator but also provide an
+extensible \LUA\ reimplementation. That one might become the default in future
+versions. In traditional \TEX\ there are several low level hyphenation
+representations: simple hyphen only points, injected by the hyphenator,
+explicitly injected by the user or originating from a hyphen character. Then
+there is the generic (pre, post, replace) discretionary that can be explicitly
+injected by the user (or a macro). In \MKIV\ all hyphenation points get
+normalized to this generic discretionary. There is no need for old|-|time
+optimizations and a consistent (expanded) representation is easier to deal with
+in other extensions. However, because the font handler is supposed to also work
+outside \CONTEXT\ we need to deal with traditional cases too. But \unknown\ the
+results might differ a bit.
+
+\stopsubsection
+
+ \startsubsection[title=Color]
+
+ % TODO: use emojionecolor-svginot-archived.ttf
+
+ A recent new (and evolving) addition to \OPENTYPE\ is colored glyphs. One variant
+ (by \MICROSOFT) uses overlays and this method is quite efficient.
+
+ \startbuffer
+ \definefontfeature[colored][colr=yes]
+ \definefontsynonym[Emoji][file:seguiemj.ttf*default,colored]
+
+ \definesymbol[bug][\getglyphdirect{Emoji}{\char"1F41B}]
+ \definesymbol[ant][\getglyphdirect{Emoji}{\char"1F41C}]
+ \definesymbol[bee][\getglyphdirect{Emoji}{\char"1F41D}]
+ \stopbuffer
+
+ \typebuffer \getbuffer
+
+ Here we see a \symbol[bug], \symbol[ant] and \symbol[bee], and they come in
+ color! Once \UNICODE\ started adding such symbols (and more get added) the
+ distinction between characters and symbols get even fuzzier. Of course one
+ can argue that we communicate in pictograms but even then, given that
+ mankind lasts a while, the \UNICODE\ repertoire will explode.
+
+ \startplacefigure[title={A few emojis from \type {seguiemj.ttf}}]
+ \startcombination [3*1]
+ {\scale[width=.3\textwidth]{\symbol[bug]}} {\type{U+1F41B}: bug}
+ {\scale[width=.3\textwidth]{\symbol[ant]}} {\type{U+1F41C}: ant}
+ {\scale[width=.3\textwidth]{\symbol[bee]}} {\type{U+1F41D}: bee}
+ \stopcombination
+ \stopplacefigure
+
+ Here we use \type {seguiemj.ttf}, a font that comes with \MSWINDOWS. Colors are
+ achieved by combining glyphs rendered in different colors. A variant that uses
+ \SVG\ instead of overlays is \type {emojionecolor-svginot.ttf}:
+
+ \startbuffer
+ \definefontfeature[svg][svg=yes]
+ \definefontsynonym[Emoji][file:emojionecolor-svginot.ttf*default,svg]
+ \stopbuffer
+
+ \typebuffer \getbuffer
+
+ This time we get \symbol[bug], \symbol[ant] and \symbol[bee] and they look
+ quite different. Both fonts also have ligatures and you can wonder what sense
+ that makes. It makes it impossible to swap fonts and as there is no standard
+ one never knows what to expect.
+
+ \startplacefigure[title={A few emojis from \type {emojionecolor-svginot.ttf}}]
+ \startcombination [3*1]
+ {\scale[width=.3\textwidth]{\symbol[bug]}} {\type{U+1F41B}: bug}
+ {\scale[width=.3\textwidth]{\symbol[ant]}} {\type{U+1F41C}: ant}
+ {\scale[width=.3\textwidth]{\symbol[bee]}} {\type{U+1F41D}: bee}
+ \stopcombination
+ \stopplacefigure
+
+ \definefont[emoji][file:emojionecolor-svginot.ttf*default,svg]
+
+ \def\FourFaces{\char128104\zwj\char128105\zwj\char128102\zwj\char128102\relax}
+
+ \def\Man {\char"1F468\relax}
+ \def\Woman{\char"1F469\relax}
+ \def\Boy {\char"1F466\relax}
+ \def\Girl {\char"1F467\relax}
+
+ How do we know what faces add up to the ligature {\emoji\Man \zwj \Woman \zwj
+ \Girl \zwj \Boy} and how are we supposed to know that there should {\darkgray
+ \type {zwj}} in between? When we input four faces separated by zero width
+ joiners, we get a four face symbol instead. The reason for having the joiners in
+ between is probably to avoid unexpected ligatures. The sequence \type {man},
+ \type {woman}, \type {boy}, \type {boy} gives \type {family}:
+ %
+ {\emoji\Man} + {\darkgray \type {zwj}}
+ {\emoji\Woman} + {\darkgray \type {zwj}}
+ {\emoji\Boy} + {\darkgray \type {zwj}}
+ {\emoji\Boy} = {\emoji\Man \zwj \Woman \zwj \Boy \zwj \Boy},
+ %
+ but two girls also work:
+ %
+ {\emoji\Man} + {\darkgray \type {zwj}}
+ {\emoji\Woman} + {\darkgray \type {zwj}}
+ {\emoji\Girl} + {\darkgray \type {zwj}}
+ {\emoji\Girl} = {\emoji\Man \zwj \Woman \zwj \Girl \zwj \Girl},
+ %
+ so does a mixture of kids:
+ %
+ {\emoji\Man} + {\darkgray \type {zwj}}
+ {\emoji\Woman} + {\darkgray \type {zwj}}
+ {\emoji\Girl} + {\darkgray \type {zwj}}
+ {\emoji\Boy} = {\emoji\Man \zwj \Woman \zwj \Girl \zwj \Boy},
+ %
+ although (at least currently):
+ %
+ {\emoji\Man} + {\darkgray \type {zwj}}
+ {\emoji\Woman} + {\darkgray \type {zwj}}
+ {\emoji\Boy} + {\darkgray \type {zwj}}
+ {\emoji\Girl} = {\emoji\Man \zwj \Woman \zwj \Boy \zwj \Girl},
+ %
+ gives twin boys. Of course the real family emoj is {\emoji\char"1F46A}.
+
+ In our times for sure many combinations are possible, so:
+ %
+ {\emoji\Man} + {\darkgray \type {zwj}}
+ {\emoji\Man} + {\darkgray \type {zwj}}
+ {\emoji\Girl} + {\darkgray \type {zwj}}
+ {\emoji\Girl} = {\emoji\Man \zwj \Man \zwj \Girl \zwj \Girl},
+ %
+ indeed gives a family, but I wonder at what point cultural bias will creep into
+ font design. One can even wonder how clothing and haircut will demand frequent
+ font updates: {\emoji\char"1F46B}, {\emoji\char"1F46C}, {\emoji\char"1F46D}.
+
+ In the math alphabets we have a couple of annoying holes because some characters
+ were already present in \UNICODE. The bad thing here is that we now always have
+ to deal with these exceptions. But not so with emojis because here eventually all
+ variants will show up. Where a character \type {A} in red or blue uses the same
+ code point, a white telephone {\emoji\char"1F57E} and black telephone
+ {\emoji\char"1F57F} have their own. And because obsolete scripts are already
+ supported in \UNICODE\ and more get added, we can expect old artifacts also
+ showing up at some time. Soon the joystick {\emoji\char"1F579} will be an unknown
+ item to most of us, while the \MICROSOFT\ hololens migth get its slot.
+
+ \startplacefigure[title={Will all animals come in stages of development?}]
+ \startcombination [3*1]
+ {\scale[width=.3\textwidth]{\emoji\char"1F423}} {\type{U+1F423}: hatching chick}
+ {\scale[width=.3\textwidth]{\emoji\char"1F424}} {\type{U+1F424}: baby chick}
+ {\scale[width=.3\textwidth]{\emoji\char"1F425}} {\type{U+1F425}: front-facing baby chick}
+ \stopcombination
+ \stopplacefigure
+
+ For sure these mechanisms will evolve and to what extent we support them depends
+ on what users want. At least we have the basics implemented.
+
+ \stopsubsection
+
+ \stopsection
+
+\startsection[title=Extras]
+
+\startnotabene
+ Todo.
+\stopnotabene
+
+\stopsection
+
+\startsection[reference=goodies,title=Goodies]
+
+Goodies range from simple to complex. They share that they are defined in files
+and loaded at runtime. There is a good change that when you read this, that there
+are already more goodies than mentioned here. Here we will just mention a couple
+of goodies. More details can be found in the files that ship with \CONTEXT\ and
+have suffix \type {lfg}.
+
+A goodie file is a regular \LUA\ file and is supposed to return a table. This
+table collects data that is used for implementing the goodie or relates to a
+regular feature. It can also provide information that is used for patching a
+font. An example of a simple goodie file is the ones that accompanies the first
+release of the \OPENTYPE\ Lucida fonts.
+
+\starttyping
+return {
+ name = "lucida-opentype-math",
+ version = "1.00",
+ comment = "Goodies that complement lucida opentype.",
+ author = "Hans Hagen",
+ copyright = "ConTeXt development team",
+ mathematics = {
+ alternates = {
+ italic = {
+ feature = 'ss01',
+ value = 1,
+ comment = "Mathematical Alternative Italic"
+ },
+ }
+ }
+}
+\stoptyping
+
+This goodie file is only providing information about the meaning of a stylistic
+alternate. These have abstract tags like \type {ss01} and in this case this
+category collects alternative italic (calligraphic) shapes. Because math does
+not follow the same rules as text, this feature is enabled explicitly.
+
+In the goodie file of Xits math the alternates table has more entries:
+
+\startnarrowtyping
+alternates = {
+ cal = { ... comment = "Mathematical Calligraphic Alphabet" },
+ greekssup = { ... comment = "Mathematical Greek Sans Serif Alphabet" },
+ greekssit = { ... comment = "Mathematical Italic Sans Serif Digits" },
+ monobfnum = { ... comment = "Mathematical Bold Monospace Digits" },
+ mathbbbf = { ... comment = "Mathematical Bold Double-Struck Alphabet" },
+ mathbbit = { ... comment = "Mathematical Italic Double-Struck Alphabet" },
+ mathbbbi = { ... comment = "Mathematical Bold Italic Double-Struck Alphabet" },
+ upint = { ... comment = "Upright Integrals" },
+ vertnot = { ... comment = "Negated Symbols With Vertical Stroke" },
+}
+\stopnarrowtyping
+
+An alternate is triggered at the \TEX\ end with:
+
+\starttyping
+$ABC$ $\cal ABC$ $\mathalternate{cal}\cal ABC$
+\stoptyping
+
+This is an example of a dynamic feature that gets applied when enabled at a
+specific location in the input. The \type {cal} is only recognized when it
+is defined in a goodies file, where the value is defined (in all of the above cases
+the value is~\type {1}).
+
+The Xits math fonts has a goodie files that starts with:
+
+\starttyping
+return {
+ name = "xits-math",
+ version = "1.00",
+ comment = "Goodies that complement xits (by Khaled Hosny).",
+ author = "Hans Hagen",
+ copyright = "ConTeXt development team",
+ mathematics = {
+ italics = {
+ ["xits-math"] = italics,
+ },
+ alternates = {
+\stoptyping
+
+Here the \type {italics} variable is a table defined before the \type {return}
+that looks as follows:
+
+\starttyping
+local italics = {
+ defaultfactor = 0.025,
+ disableengine = true,
+ corrections = {
+ -- [0x1D44E] = 0.99, -- a (fraction of quad)
+ -- [0x1D44F] = 100, -- b (font points)
+ [0x1D453] = -0.0375, -- f
+ }
+}
+\stoptyping
+
+This rather specific table tells \CONTEXT\ that (when enabled) it has to apply
+italic correction. It disables support built into the \TEX\ engine (which in the
+case of \LUATEX\ is close to absent anyway). It will apply a default italic
+correction of \type {0.025} but for some shapes a different value is used. Again
+we have some commands at the \TEX\ end:
+
+\starttyping
+\setupmathematics[italics=1] % apply italics with we have an italic font
+\setupmathematics[italics=2] % apply italics anyway
+\setupmathematics[italics=3] % apply italics only when italic or bolditalic shapes
+\setupmathematics[italics=4] % combination of 1 and 3
+\stoptyping
+
+An alternative is this:
+
+\starttyping
+\definefontfeature[mathextra][mathextra][collapseitalics=yes]
+\stoptyping
+
+This extends the \type {mathextra} feature to move the italic correction into
+the character's width. Often this works out ok.
+
+Because (definitely at the start of the \LUATEX\ project) we had no
+proper \OPENTYPE\ math fonts, but at the same time wanted to move on
+to \OPENTYPE\ and \UNICODE\ math and no longer struggle with all
+those math families and definitions. The way out of this problem
+is to define a virtual math font. The code for doing this is built
+into the \MKIV\ core but is controlled by a goodie definition. Take
+for instance Antykwa Math:
+
+\startnarrowtyping
+return {
+ name = "antykwa-math",
+ version = "1.00",
+ comment = "Goodies that complement antykwa math.",
+ author = "Hans, Mojca, Aditya",
+ copyright = "ConTeXt development team",
+ mathematics = {
+ mapfiles = {
+ "antt-rm.map",
+ "antt-mi.map",
+ "antt-sy.map",
+ "antt-ex.map",
+ "mkiv-base.map",
+ },
+ virtuals = {
+ ["antykwa-math"] = {
+ { name = "file:AntykwaTorunska-Regular", features = "virtualmath", main = true },
+ { name = "mi-anttri.tfm", vector = "tex-mi", skewchar=0x7F },
+ { name = "mi-anttri.tfm", vector = "tex-it", skewchar=0x7F },
+ { name = "sy-anttrz.tfm", vector = "tex-sy", skewchar=0x30, parameters = true } ,
+ { name = "ex-anttr.tfm", vector = "tex-ex", extension = true } ,
+ { name = "msam10.tfm", vector = "tex-ma" },
+ { name = "msbm10.tfm", vector = "tex-mb" },
+ },
+\stopnarrowtyping
+
+Normally users will not define such tables but the keys give an indication of
+what is involved. The same is true for the previously shown tables: they are just
+provided in the \CONTEXT\ distribution.
+
+Text fonts also can have goodies. We start with a rather dumb one and there
+will be not that many of those. This one is needed to turn a \TYPEONE\ font
+with a rather special encoding into a \UNICODE\ font. The next mapping is
+possible because the dingbats are part of \UNICODE.
+
+\starttyping
+return {
+ name = "dingbats",
+ version = "1.00",
+ comment = "Goodies that complement dingbats (funny names).",
+ author = "Hans Hagen",
+ copyright = "ConTeXt development team",
+ remapping = {
+ tounicode = true,
+ unicodes = {
+ a1 = 0x2701,
+ a10 = 0x2721,
+ a100 = 0x275E,
+ a101 = 0x2761,
+ a102 = 0x2762,
+\stoptyping
+
+Applying this encoding happens in two steps. Because goodies like this are just
+features, we need to define a proper font feature set:
+
+\starttyping
+\definefontfeature
+ [dingbats]
+ [mode=base,
+ goodies=dingbats,
+ unicoding=yes]
+\stoptyping
+
+We have a base mode font, so no special processing takes place. The \type {goodies}
+key is used to communicate the goodies file. The \type {unicoding} key is used
+to apply the encoding. Of course this only works because the remapper code is present
+in the core and is hooked in to the font initialization code. The \type {dingbats}
+feature set is predefined, just as the font definition:
+
+\starttyping
+\definefontsynonym [ZapfDingbats] [file:uzdr] [features=dingbats]
+\stoptyping
+
+Here is a goodie file that I made a while ago:
+
+\starttyping
+return {
+ name = "oxoniensis",
+ version = "1.00",
+ comment = "Oxoniensis test file for Thomas Schmitz.",
+ author = "Hans Hagen",
+ copyright = "ConTeXt development team",
+ features = {
+ lunatesigma = {
+ type = "substitution",
+ data = {
+ sigma = 0x03F2,
+ sigma1 = 0x03F2,
+ Sigma = 0x03F9,
+ phi = phi1,
+ },
+ }
+ },
+}
+\stoptyping
+
+There is not that much to say about this, apart from that it's a sort of fake
+feature that gets enabled as regular one:
+
+\starttyping
+\definefontfeature[test]
+ [mode=node,
+ kern=yes,
+ lunatesigma=yes,
+ goodies=oxoniensis]
+
+\definefont[somefont][file:oxoniensis*test]
+\stoptyping
+
+A complete different kind of goodie is the following. At one of the \CONTEXT\ meetings
+Mojca Miklavec discussed the possibility to have an additional mechanism for
+defining combinations of fonts. Often fonts come in a set of four (regular, italic,
+bold and bold italic). In \MKII\ the complexity of typescripts depends on the amount of
+encodings that need to be supported but in \MKIV\ things are easier. For a set of four fonts
+a typescript looks as follows:
+
+\starttyping
+\starttypescript [sans] [somesansfont] [name]
+ \setups[font:fallback:sans]
+ \definefontsynonym [Sans] [file:somesans] [features=default]
+ \definefontsynonym [SansBold] [file:somesansb] [features=default]
+ \definefontsynonym [SansItalic] [file:somesansi] [features=default]
+ \definefontsynonym [SansBoldItalic] [file:somesansz] [features=default]
+\stoptypescript
+\stoptyping
+
+We still have the abstract notion of a \type {Sans} font so that we can refer to
+the regular shape without knowing the real name but the number of lines needed
+is small. Such a definition can then be referred to using:
+
+\starttyping
+\starttypescript[somefontset]
+ \definetypeface [somefontset] [rm] [serif] [someserif] [default]
+ \definetypeface [somefontset] [ss] [sans] [somesans] [default]
+ \definetypeface [somefontset] [tt] [mono] [somemono] [default]
+ \definetypeface [somefontset] [mm] [math] [somemath] [default]
+\stoptypescript
+\stoptyping
+
+So far things look simple. Given that many fonts follow a similar naming scheme
+Wolfgang made a module that avoids such definitions altogether. However, being
+involved in the development of the Antykwa fonts, Mojca ran into the situation
+that not just four fonts were part of the set but many more. There are several
+weight (think of light and heavy variants) as well as condensed variants and of
+course the whole set is not per se a multiple of four.
+
+In the meantime, in addition to the \type {file:} and \type {name:} accessors,
+\CONTEXT\ had an additional one tagged \type {spec:} where a string made out of
+weight, style, width etc.\ is turned into a (best guessed) font name. Therefore
+the most natural way to deal with the many|-|fonts|-|in|-|a|-|set dilemma was to
+provide an additional interface between this specification and the font set and
+the most robust method was to define all in a goodie file.
+
+In this case the goodies are loaded independent of the font, that is: not
+as a feature. For instance:
+
+\starttyping
+\loadfontgoodies[antykwapoltawskiego]
+\stoptyping
+
+This file maps obscure fontnames onto the \type {spec:} interface so that
+we can access them in a robust way.
+
+\starttyping
+\definefont
+ [MyFontA]
+ [file:Iwona-Regular*smallcaps]
+\definefont
+ [MyFontB]
+ [file:AntykwaTorunska-Regular*smallcaps]
+\definefont
+ [MyFontC]
+ [file:antpoltltcond-regular*smallcaps]
+\definefont
+ [MyFontD]
+ [spec:antykwapoltawskiego-bold-italic-condensed-normal*smallcaps]
+\definefont
+ [MyFontE]
+ [spec:antykwapoltawskiego-bold-italic-normal]
+\stoptyping
+
+The goodies file looks as follows:
+
+\starttyping
+return {
+ name = "antykwa-poltawskiego",
+ version = "1.00",
+ comment = "Goodies that complement Antykwa Poltawskiego",
+ author = "Hans & Mojca",
+ copyright = "ConTeXt development team",
+ files = {
+ name = "antykwapoltawskiego", -- shared
+ list = {
+ ["AntPoltLtCond-Regular.otf"] = {
+ weight = "light",
+ style = "regular",
+ width = "condensed",
+ },
+ ...
+ ["AntPoltExpd-BoldItalic.otf"] = {
+ weight = "bold",
+ style = "italic",
+ width = "expanded",
+ },
+ },
+ },
+ typefaces = {
+ ["antykwapoltawskiego-light"] = {
+ shortcut = "rm",
+ shape = "serif",
+ fontname = "antykwapoltawskiego",
+ normalweight = "light",
+ boldweight = "medium",
+ width = "normal",
+ size = "default",
+ features = "default",
+ },
+ ...
+ },
+}
+\stoptyping
+
+In addition to the files|-|to|-|specification mapping, there is
+also a typeface specification table. This permits the definition
+of a typeface in the following way:
+
+\starttyping
+\definetypeface
+ [name=mojcasfavourite,
+ preset=antykwapoltawskiego,
+ normalweight=light,
+ boldweight=bold,
+ width=expanded]
+
+\setupbodyfont
+ [mojcasfavourite]
+\stoptyping
+
+When resolving the definition, the best possible match will be taken from the
+typeface table in the goodie file. Of course this is not something that we expect
+the average user to deliver and deal with.
+
+As the Antykwa font is somewhat atypical and not used in everyday typesetting,
+you might wonder if all this overhead makes sense. However, there are type
+foundries that do ship their fonts in many weights and for those using a \LUA\
+goodie file instead of many typescripts in \TEX\ coding makes sense. Take for
+instance TheMix:
+
+\starttyping
+\loadfontgoodies
+ [themix]
+
+\definetypeface
+ [name=themix,
+ preset=themix-light]
+
+\definetypeface
+ [name=themix,
+ preset=themixmono-light]
+
+\setupbodyfont
+ [themix]
+\stoptyping
+
+In this case the goodie file can serve as a template for more such fonts.
+In order to be efficient this goodie file uses a couple of local
+tables (we could have used metatables instead).
+
+\starttyping
+local themix = {
+ name = "themix",
+ shortcut = "ss",
+ shape = "sans",
+ fontname = "themix",
+ width = "normal",
+ size = "default",
+ features = "default",
+}
+
+local themixmono = {
+ name = "themixmono",
+ shortcut = "tt",
+ shape = "mono",
+ fontname = "themixmono",
+ width = "normal",
+ size = "default",
+ features = "default",
+}
+\stoptyping
+
+The main goodie table defines a lot of weights:
+
+\startnarrowtyping
+return {
+ name = "themix",
+ version = "1.00",
+ comment = "Goodies that complement TheMix (by and for sale at www.lucasfonts.com).",
+ author = "Hans Hagen",
+ copyright = "ConTeXt development team",
+ files = {
+ list = {
+ ["TheMixOsF-ExtraLight"] = {
+ name = "themix",
+ weight = "extralight",
+ style = "regular",
+ width = "normal"
+ },
+ ["TheMixOsF-ExtraLightItalic"] = {
+ ...
+ },
+ ...
+ ["TheMixOsF-Black"] = {
+ ...
+ },
+ ["TheMixOsF-BlackItalic"] = {
+ ...
+ },
+ ...
+ --
+ ["TheMixMono-W2ExtraLight"] = {
+ name = "themixmono",
+ weight = "extralight",
+ style = "regular",
+ width = "normal"
+ },
+ ...
+ ["TheMixMono-W9BlackItalic"] = {
+ ...
+ },
+ },
+ },
+ typefaces = {
+ ["themix-extralight"] = table.merged(themix, {
+ normalweight = "extralight",
+ boldweight = "semilight"
+ }),
+ ["themix-light"] = table.merged(themix, {
+ normalweight = "light",
+ boldweight = "normal"
+ }),
+ ...
+ ["themixmono-bold"] = table.merged(themixmono, {
+ normalweight = "bold",
+ boldweight = "black"
+ }),
+ },
+}
+\stopnarrowtyping
+
+It's now time for some generic goodies. In the \CONTEXT\ distribution there
+is a goodie file that (at the time of this writing) looks as follows:
+
+\starttyping
+local default = {
+ analyze = "yes",
+ mode = "node",
+ language = "dflt",
+ script = "dflt",
+}
+
+local smallcaps = {
+ smcp = "yes",
+}
+
+local function statistics(tfmdata)
+ commands.showfontparameters(tfmdata)
+end
+
+local function squeeze(tfmdata)
+ for k, v in next, tfmdata.characters do
+ v.height = 0.75 * (v.height or 0)
+ v.depth = 0.75 * (v.depth or 0)
+ end
+end
+
+return {
+ name = "demo",
+ version = "1.01",
+ comment = "An example of goodies.",
+ author = "Hans Hagen",
+ featuresets = {
+ default = {
+ default,
+ },
+ smallcaps = {
+ default, smallcaps,
+ },
+ },
+ colorschemes = {
+ default = {
+ [1] = {
+ "one", "three", "five", "seven", "nine",
+ },
+ [2] = {
+ "two", "four", "six", "eight", "ten",
+ },
+ },
+ all = {
+ [1] = {
+ "*",
+ },
+ },
+ some = {
+ [1] = {
+ "0x0030:0x0035",
+ },
+ },
+ },
+ postprocessors = {
+ statistics = statistics,
+ squeeze = squeeze,
+ },
+}
+\stoptyping
+
+This demo file implements several goodies: featuresets, colors and
+postprocessors. Keep in mind that a goodie file can provide whatever information
+it wants but of course only known subtables will be dealt with.
+
+The coloring of glyphs can happen by name, which assumes that glyph names are
+used, or by number. Here we use generic glyph names, but for a specific font one
+might need to provide a special goodie file. For instance, the color section of
+the goodie file for the husayni font has entries like:
+
+\startnarrowtyping
+[3] = {
+ "Ttaa.waqf", "SsLY.waqf", "QLY.waqf", "Miim.waqf", "LA.waqf", "Jiim.waqf",
+ "Threedotsabove.waqf", "Siin.waqf", "Ssaad.waqf", "Qaaf.waqf", "SsL.waqf",
+ "QF.waqf", "SKTH.waqf", "WQFH.waqf", "Kaaf.waqf", "Ayn.ruku", "Miim.nuun_high",
+ "Siin.Ssaad", "Nuunsmall", "emptydot_low", "emptydot_high", "Sifr.fill",
+ "Miim.nuun_low", "Nuun.tanwiin",
+},
+\stopnarrowtyping
+
+Of course such a definition can only be made when the internals of the font are
+known and in this case it concerns a pretty complex font.
+
+\startbuffer
+\definefontfeature
+ [demo-colored]
+ [goodies=demo,
+ colorscheme=default,
+ featureset=default]
+
+\definefontfeature
+ [demo-colored-all]
+ [goodies=demo,
+ colorscheme=all,
+ featureset=default]
+
+\definefontfeature
+ [demo-colored-some]
+ [goodies=demo,
+ colorscheme=some,
+ featureset=default]
+
+\definefont[DemoFontA][MonoBold*demo-colored at 10pt]
+\definefont[DemoFontB][MonoBold*demo-colored-all at 10pt]
+\definefont[DemoFontC][MonoBold*demo-colored-some at 10pt]
+\stopbuffer
+
+\typebuffer \getbuffer
+
+% \definecolor[colorscheme:1:1][s=.75]
+% \definecolor[colorscheme:1:2][r=.75]
+% \definecolor[colorscheme:1:3][g=.75]
+% \definecolor[colorscheme:1:4][b=.75]
+% \definecolor[colorscheme:1:5][c=.75]
+% \definecolor[colorscheme:1:6][m=.75]
+% \definecolor[colorscheme:1:7][y=.75]
+
+% \definecolor[colorscheme:2:7][s=.75]
+% \definecolor[colorscheme:2:6][r=.75]
+% \definecolor[colorscheme:2:5][g=.75]
+% \definecolor[colorscheme:2:4][b=.75]
+% \definecolor[colorscheme:2:3][c=.75]
+% \definecolor[colorscheme:2:2][m=.75]
+% \definecolor[colorscheme:2:1][y=.75]
+
+\startbuffer
+\starttabulate[||||]
+\NC
+ \DemoFontA \resetfontcolorscheme test 1234567890 \NC
+ \DemoFontA \setfontcolorscheme [1]test 1234567890 \NC
+ \DemoFontA \setfontcolorscheme [2]test 1234567890 \NC
+\NR
+\NC
+ \DemoFontB \resetfontcolorscheme test 1234567890 \NC
+ \DemoFontB \setfontcolorscheme [1]test 1234567890 \NC
+ \DemoFontB \setfontcolorscheme [2]test 1234567890 \NC
+\NR
+\NC
+ \DemoFontC \resetfontcolorscheme test 1234567890 \NC
+ \DemoFontC \setfontcolorscheme [1]test 1234567890 \NC
+ \DemoFontC \setfontcolorscheme [2]test 1234567890 \NC
+\NR
+\stoptabulate
+\stopbuffer
+
+\typebuffer \getbuffer
+
+Here is an example that I made at the TUG 2013 conference in Japan,
+after a presentation by Chof. The font (adapted by by Dohyun Kim) can
+be downloaded from: \hyphenatedurl {http://ftp.ktug.org/KTUG/hcr-lvt/1.910_nomac/}.
+
+\startbuffer[korean-demo]
+\definefontfeature
+ [korean-composed]
+ [goodies=hanbatanglvt,
+ colorscheme=default,
+ mode=node,
+ ljmo=yes,
+ tjmo=yes,
+ vjmo=yes,
+ script=hang,
+ language=kor]
+
+\definefont
+ [KoreanJMO]
+ [hanbatanglvt*korean-composed]
+
+\definecolor[colorscheme:100:1][r=.75]
+\definecolor[colorscheme:100:2][g=.75]
+\definecolor[colorscheme:100:3][b=.75]
+
+\definecolor[colorscheme:101:1][g=.75,b=.75]
+\definecolor[colorscheme:101:2][r=.75,b=.75]
+\definecolor[colorscheme:101:3][r=.75,g=.75]
+\stopbuffer
+
+\typebuffer[korean-demo] \getbuffer[korean-demo]
+
+\startbuffer
+ % Hunminjeongeum: http://en.wikipedia.org/wiki/Hunminjeongeum
+ 나랏말ᄊᆞ미中듕國귁에달아문ᄍᆞᆼ와로서르ᄉᆞᄆᆞᆺ디아니ᄒᆞᆯᄊᆡ%
+ 사ᄅᆞᆷ마다ᄒᆡᅇᅧ수ᄫᅵ니겨나...% ᆯ로ᄡᅮ메便뼌安ᅙᅡᆫ킈ᄒᆞ고져ᄒᆞᇙᄯᆞᄅᆞ미니라
+\stopbuffer
+
+\startlinecorrection
+\startcombination[1*3]
+ {\framed{\startscript[hangul]\KoreanJMO \getbuffer\stopscript}} {no colorscheme}
+ {\framed{\startscript[hangul]\KoreanJMO\setfontcolorscheme[100]\getbuffer\stopscript}} {colorscheme 100}
+ {\framed{\startscript[hangul]\KoreanJMO\setfontcolorscheme[101]\getbuffer\stopscript}} {colorscheme 101}
+\stopcombination
+\stoplinecorrection
+
+The goodie definition looks as follows (watch how we use ranges):
+
+\starttyping
+return {
+ name = "hanbatanglvt",
+ version = "1.00",
+ comment = "Goodies that complement the hanbatanglvt fonts.",
+ author = "Hans Hagen",
+ colorschemes = {
+ default = {
+ { "0x01100:0x0115F" }, -- jamo_initial (r/c)
+ { "0x01160:0x011A7" }, -- jamo_medial (g/m)
+ { "0x011A8:0x011FF" }, -- jamo_final (b/y)
+ }
+ }
+}
+\stoptyping
+
+This is much shorter (and efficent) that defining a whole vector, as in:
+
+\starttyping
+local f_uni_base = string.formatters["uni%04X"]
+local f_uni_plus = string.formatters["uni%04X.y%s"]
+
+local function range(first,last)
+ local t = { }
+ for i=first,last do
+ t[#t+1] = f_uni_base(i)
+ for j=0,19 do
+ t[#t+1] = f_uni_plus(i,j)
+ end
+ end
+ return t
+end
+
+return {
+ name = "hanbatanglvt",
+ version = "1.00",
+ comment = "Goodies that complement the hanbatanglvt fonts.",
+ author = "Hans Hagen",
+ colorschemes = {
+ default = {
+ range(0x01100,0x0115F), -- jamo_initial (r/c)
+ range(0x01160,0x011A7), -- jamo_medial (g/m)
+ range(0x011A8,0x011FF), -- jamo_final (b/y)
+ }
+ }
+}
+\stoptyping
+
+By using names we don't depend on \UNICODE\ which sometimes is needed when glyphs
+have ended up in the private space. However, by default, after glyphs have been
+mapped to colors, an extra pass will make sure that characters pushed into
+private space will get the same mapping as their regular \UNICODE\ has gotten
+(given that the number is known). Of course explicitly assigned colors will be
+preserved.
+
+Another generic demo feature is postprocessing. In principle one can
+add additional postprocessors but for that the source code needs to
+be consulted which in turn assumes some knowledge of fonts and \CONTEXT\
+internals.
+
+\startbuffer
+\definefontfeature
+ [justademoa]
+ [default]
+ [goodies=demo,
+ postprocessor=squeeze]
+
+\definefontfeature
+ [justademob]
+ [default]
+ [goodies=demo,
+ postprocessor=statistics]
+
+\definefontfeature
+ [justademoc]
+ [default]
+ [goodies=demo,
+ postprocessor={statistics,squeeze}]
+\stopbuffer
+
+\typebuffer \getbuffer
+
+The statistics just print some font parameters to the log so that one
+is not showing up here. The squeeze looks as follows:
+
+\startbuffer
+\definefont[DemoFontD][Serif*default at 30pt]
+\definefont[DemoFontE][Serif*justademoa at 30pt]
+\stopbuffer
+
+\typebuffer \getbuffer
+
+\startlinecorrection
+\hbox\bgroup
+ \ruledhbox{\color[maincolor]{DemoFontD height \& depth}}\quad
+ \ruledhbox{\color[maincolor]{DemoFontE height \& depth}}
+\egroup
+\stoplinecorrection
+
+The squeezer just makes the height and depth of glyphs a bit smaller and it is
+not that hard to imagine other manipulations. The demo goodie file is good
+place to start playing with such things.
+
+Because there is less standardization with respect to features than one might
+suspect, goodie files provide a mean to define featuresets. We can use such a set
+in another definition:
+
+\starttyping
+\definefontfeature
+ [demo-smallcaps]
+ [goodies=demo,
+ featureset=smallcaps]
+\stoptyping
+
+Of course this only makes sense for more complex combinations. The already mentioned
+husayni font comes with many features and most of these work together.
+
+The basic goodie table looks as follows:
+
+\startnarrowtyping
+return {
+ name = "husayni",
+ version = "1.00",
+ comment = "Goodies that complement the Husayni font by Idris Samawi Hamid.",
+ author = "Idris Samawi Hamid and Hans Hagen",
+ featuresets = { },
+ solutions = { },
+ stylistics = { },
+ colorschemes = { },
+}
+\stopnarrowtyping
+
+We already saw the color schemes and now we will fill in the other tables. First
+we define a couple of sets:
+
+\startnarrowtyping
+local basics = {
+ analyze = "yes",
+ mode = "node",
+ language = "dflt",
+ script = "arab",
+}
+
+local analysis = {
+ ccmp = "yes",
+ init = "yes", medi = "yes", fina = "yes",
+}
+
+local regular = {
+ rlig = "yes", calt = "yes", salt = "yes", anum = "yes",
+ ss01 = "yes", ss03 = "yes", ss07 = "yes", ss10 = "yes", ss12 = "yes",
+ ss15 = "yes", ss16 = "yes", ss19 = "yes", ss24 = "yes", ss25 = "yes",
+ ss26 = "yes", ss27 = "yes", ss31 = "yes", ss34 = "yes", ss35 = "yes",
+ ss36 = "yes", ss37 = "yes", ss38 = "yes", ss41 = "yes", ss42 = "yes",
+ ss43 = "yes", js16 = "yes",
+}
+
+local positioning = {
+ kern = "yes", curs = "yes", mark = "yes", mkmk = "yes",
+}
+
+local minimal_stretching = {
+ js11 = "yes", js03 = "yes",
+}
+
+local medium_stretching = {
+ js12="yes", js05="yes",
+}
+local maximal_stretching= {
+ js13 = "yes", js05 = "yes", js09 = "yes",
+}
+
+local wide_all = {
+ js11 = "yes", js12 = "yes", js13 = "yes", js05 = "yes", js09 = "yes",
+}
+
+local shrink = {
+ flts = "yes", js17 = "yes", ss05 = "yes", ss11 = "yes", ss06 = "yes",
+ ss09 = "yes",
+}
+
+local default = {
+ basics, analysis, regular, positioning, -- xxxx = "yes", yyyy = 2,
+}
+\stopnarrowtyping
+
+Next we define some featuresets and we use the default as starting point:
+
+\startnarrowtyping
+ featuresets = {
+ default = {
+ default,
+ },
+ minimal_stretching = {
+ default, js11 = "yes", js03 = "yes",
+ },
+ medium_stretching = {
+ default, js12="yes", js05="yes",
+ },
+ maximal_stretching= {
+ default, js13 = "yes", js05 = "yes", js09 = "yes",
+ },
+ wide_all = {
+ default, js11 = "yes", js12 = "yes", js13 = "yes", js05 = "yes",
+ js09 = "yes",
+ },
+ shrink = {
+ default, flts = "yes", js17 = "yes", ss05 = "yes", ss11 = "yes",
+ ss06 = "yes", ss09 = "yes",
+ },
+ }
+\stopnarrowtyping
+
+When defining the font at the \TEX\ end we can now refer to for instance \type
+{wide_all} which saves us some typing. However, it does not stop here. In a later
+paragraph we will see how fonts can work in tandem with the parbuilder. For that
+purpose the goodie table has a \type {solutions} subtable:
+
+\startnarrowtyping
+solutions = {
+ experimental = {
+ less = {
+ "shrink"
+ },
+ more = {
+ "minimal_stretching", "medium_stretching", "maximal_stretching", "wide_all"
+ },
+ },
+}
+\stopnarrowtyping
+
+Here we define an experimental solution for optimizing the lines in a paragraph:
+we can narrow words or we can widen them according to a specific featureset. In
+order to reach the optimal solution the text will be retypeset under a different
+feature regime.
+
+{\em TODO: show how to apply.}
+
+%D \starttyping
+%D \setupfontsolutions[method={random,preroll},criterium=1,randomseed=101]
+%D
+%D \definefontsolution % actually only the last run needs to be done this way
+%D [FancyHusayni]
+%D [goodies=husayni,
+%D solution=experimental]
+%D
+%D \definedfont[husayni*husayni-default at 24pt]
+%D \setupinterlinespace[line=36pt]
+%D \righttoleft
+%D \enabletrackers[parbuilders.solutions.splitters.colors]
+%D \setfontsolution[FancyHusayni]
+%D alb alb alb \par
+%D \resetfontsolution
+%D \disabletrackers[parbuilders.solutions.splitters.colors]
+%D \stoptyping
+
+Because there are a some 55 stylistic and 21 justification variants the
+goodie file also provides a \type {stylistics} table and for tracing purposes
+the {colorschemes} table is populated.
+
+Yet another demonstration of manipulation is the following. Not all fonts come
+with all combined glyphs. Although we have an auto|-|compose feature in \CONTEXT\
+it sometimes helps to be specific with respect to some combinations. This is
+where the \type {compositions} goodie kicks in:
+
+\starttyping
+local compose = {
+ [0x1E02] = {
+ anchored = "top",
+ },
+ [0x1E04] = {
+ anchored = "bottom",
+ },
+ [0x0042] = { -- B
+ anchors = {
+ top = {
+ x = 300,
+ y = 700,
+ },
+ bottom = {
+ x = 300,
+ y = -30,
+ },
+ },
+ },
+ [0x0307] = {
+ anchors = {
+ top = {
+ x = -250,
+ y = 550,
+ },
+ },
+ },
+ [0x0323] = {
+ anchors = {
+ bottom = {
+ x = -250,
+ y = -80,
+ },
+ },
+ },
+}
+
+return {
+ name = "lm-compose-test",
+ version = "1.00",
+ comment = "Goodies that demonstrate composition.",
+ author = "Hans and Mojca",
+ copyright = "ConTeXt development team",
+ compositions = {
+ ["lmroman12-regular"] = compose,
+ }
+}
+\stoptyping
+
+Of course this assumes some knowledge of the font metrics (in base points) and
+\UNICODE\ slots, but it might be worth the trouble. After all, one only needs to
+figure it out once. But keep in mind that it will always be a kludge.
+
+A slightly different way to define such compositions is the following:
+
+\starttyping
+local defaultunits = 193 - 30
+
+local compose = {
+ DY = defaultunits,
+ -- [0x010C] = { DY = defaultunits }, -- Ccaron
+ -- [0x02C7] = { DY = defaultunits }, -- textcaron
+}
+
+-- fractions relative to delta(X_height - x_height)
+
+local defaultfraction = 0.85
+
+local compose = {
+ DY = defaultfraction, -- uppercase compensation
+}
+
+return {
+ name = "lucida-one",
+ version = "1.00",
+ comment = "Goodies that complement lucida.",
+ author = "Hans and Mojca",
+ copyright = "ConTeXt development team",
+ compositions = {
+ ["lbr"] = compose,
+ ["lbi"] = compose,
+ ["lbd"] = compose,
+ ["lbdi"] = compose,
+ }
+}
+\stoptyping
+
+Of course no one really needs this because \OPENTYPE\ Lucida fonts
+have replaced the \TYPEONE\ versions.
+
+The next goodie table is dedicated to the de facto standard \TEX\ font Latin
+Modern. There is a bit of history behind this file. When we started writing
+\CONTEXT\ there were not that many fonts available and so we ended up with a font
+system that was rather well suited for the predecessor of Latin Modern, called
+Computer Modern. And because these fonts came in design sizes the font system
+was made such that it could cope efficiently with many files in a font set. Although
+there is no additional overhead compared to small font sets, apart from more files,
+there is some burden in defining them. And, as they are the default fonts, these
+definitions slow down the initialization of \CONTEXT\ (which is due to the fact that
+the large typescript definitions were loaded and parsed). So, at some point
+the decision was made to kick out these definitions and move the burden of figuring
+out the right size to \LUA. When Latin Modern is chosen as font the effect is the
+same when design sizes are enabled. But, instead of many definitions (one for each
+combination of size and style) we now have an option. A non|-|designsize typeface
+is defined as follows:
+
+\startnarrowtyping
+\starttypescript [modern,modern-base]
+ \definetypeface [\typescriptone] [rm] [serif] [modern] [default]
+ \definetypeface [\typescriptone] [ss] [sans] [modern] [default]
+ \definetypeface [\typescriptone] [tt] [mono] [modern] [default]
+ \definetypeface [\typescriptone] [mm] [math] [modern] [default]
+ \quittypescriptscanning
+\stoptypescript
+\stopnarrowtyping
+
+The designsize variant looks like this:
+
+\startnarrowtyping
+\starttypescript [modern-designsize]
+ \definetypeface [\typescriptone]
+ [rm] [serif] [latin-modern-designsize] [default] [designsize=auto]
+ \definetypeface [\typescriptone]
+ [ss] [sans] [latin-modern-designsize] [default] [designsize=auto]
+ \definetypeface [\typescriptone]
+ [tt] [mono] [latin-modern-designsize] [default] [designsize=auto]
+ \definetypeface [\typescriptone]
+ [mm] [math] [latin-modern-designsize] [default] [designsize=auto]
+ \quittypescriptscanning
+\stoptypescript
+\stopnarrowtyping
+
+Of course there are accompanying typescripts that map the sans, serif, mono
+and math styles onto files. The \type {designsize} magic uses the following
+table. We show only part of the file, as it is in the \CONTEXT\ distribution.
+
+\starttyping
+return {
+ name = "latin modern",
+ version = "1.00",
+ comment = "Goodies that complement latin modern.",
+ author = "Hans Hagen",
+ copyright = "ConTeXt development team",
+ mathematics = {
+ tweaks = {
+ aftercopying = {
+ mathematics.tweaks.fixbadprime, -- prime is too low
+ },
+ },
+ },
+ designsizes = {
+ ["LMMathRoman-Regular"] = {
+ ["4pt"] = "LMMath5-Regular@lmroman5-math",
+ ...
+ ["12pt"] = "LMMath12-Regular@lmroman12-math",
+ default = "LMMath10-Regular@lmroman10-math"
+ },
+ ["LMMathRoman-Bold"] = { -- not yet ready
+ ...
+ },
+ ["LMRoman-Regular"] = {
+ ["4pt"] = "file:lmroman5-regular",
+ ...
+ ["12pt"] = "file:lmroman12-regular",
+ default = "file:lmroman10-regular",
+ },
+ ["LMRoman-Bold"] = {
+ ...
+ },
+ ["LMRoman-Demi"] = {
+ default = "file:lmromandemi10-regular",
+ },
+ ["LMRoman-Italic"] = {
+ ...
+ },
+ ...
+ ["LMRoman-Unslanted"] = {
+ default = "file:lmromanunsl10-regular",
+ },
+ ["LMSans-Regular"] = {
+ ...
+ },
+ ["LMTypewriter-Regular"] = {
+ ...
+ },
+ ...
+ ["LMTypewriterVarWd-DarkOblique"] = {
+ default = "file:lmmonoproplt10-boldoblique",
+ },
+ ...
+ ["LMTypewriter-CapsOblique"] = {
+ default = "file:lmmonocaps10-oblique",
+ },
+ }
+}
+\stoptyping
+
+The \type {auto} option will choose a best fit compatible to the
+\MKII\ implementation. When \type {default} is used instead, the
+default filename will be taken. Of course one might wonder if
+there will ever be similar goodie files because design sizes
+are not that popular nowadays.
+
+Not all fonts are perfect and of course the \LUATEX\ engine can have flaws as
+well. For this reason we can implement patches. Here is another example of a
+goodie file that has some more code than just a table:
+
+\starttyping
+local patches = fonts.handlers.otf.enhancers.patches
+
+local function patch(data,filename,threshold)
+ local m = data.metadata.math
+ if m then
+ local d = m.DisplayOperatorMinHeight or 0
+ if d < threshold then
+ patches.report("DisplayOperatorMinHeight(%s -> %s)",d,threshold)
+ m.DisplayOperatorMinHeight = threshold
+ end
+ end
+end
+
+patches.register("after","analyze math","asana",
+ function(data,filename) patch(data,filename,1350) end)
+
+local function less(value,target,original)
+ return 0.25 * value
+end
+
+local function more(value,target,original)
+ local o = original.mathparameters.DisplayOperatorMinHeight
+ if o < 2800 then
+ return 2800 * target.parameters.factor
+ else
+ return value -- already scaled
+ end
+end
+
+return {
+ name = "asana-math",
+ version = "1.00",
+ comment = "Goodies that complement asana.",
+ author = "Hans Hagen",
+ copyright = "ConTeXt development team",
+ mathematics = {
+ parameters = {
+ DisplayOperatorMinHeight = more,
+ StackBottomDisplayStyleShiftDown = less,
+ StackBottomShiftDown = less,
+ StackDisplayStyleGapMin = less,
+ StackGapMin = less,
+ StackTopDisplayStyleShiftUp = less,
+ StackTopShiftUp = less,
+ StretchStackBottomShiftDown = less,
+ StretchStackGapAboveMin = less,
+ StretchStackGapBelowMin = less,
+ StretchStackTopShiftUp = less,
+ }
+ }
+}
+\stoptyping
+
+In fact, in addition to already mentioned \type {mapfiles} and
+\type {virtuals} subtables, we can pass variables and
+overload parameters.
+
+\starttyping
+return {
+ name = "lm-math",
+ ...
+ mathematics = {
+ mapfiles = {
+ ...
+ },
+ virtuals = {
+ ...
+ variables = {
+ joinrelfactor = 3, -- default anyway
+ },
+ parameters = { -- test values
+ -- FactorA = 123.456,
+ -- FactorB = false,
+ -- FactorC = function(value,target,original)
+ -- return 7.89 * target.factor
+ -- end,
+ -- FactorD = "Hi There!",
+ },
+ }
+}
+\stoptyping
+
+This kind of goodie functionality is typical for the development of \LUATEX\ and
+experimental math fonts and no user should ever be bothered with it. However, it
+demonstrates that we're not stuck with only features built in the fonts.
+
+% mathdimensions
+
+It can be that a user is not satisfied by some aspects of a math font design.
+There is not much that we can do about the shapes, but we can manipulate for
+instance dimensions.
+
+For this there are two mechanism available: automatically applied dimensional
+fixes and a \type {mathdimensions} feature. Both work with the same goody
+specification.
+
+\starttyping
+mathematics = {
+ ...
+ dimensions = {
+ },
+ ...
+}
+\stoptyping
+
+The entries in a dimensions table are tables themselves. There can be many
+of them so one can organize dimensional tweaks in groups. The \type {default}
+group is always applied, while others are applied on demand. Say that want
+to tweak all \type {±} and \type {∓}. \footnote {In fact, this mechanism is a
+a response to a mail on the \CONTEXT\ mailing list.}
+
+\starttyping
+mathematics = {
+ dimensions = {
+ default = {
+ [0x00B1] = { -- ±
+ height = 500,
+ depth = 0,
+ },
+ [0x2213] = { -- ∓
+ height = 500,
+ depth = 0,
+ },
+ },
+ },
+}
+\stoptyping
+
+This will give these two characters a different height and depth. However, this
+will not have much effect in rendering (much larger dimensions might have).
+
+\starttyping
+mathematics = {
+ dimensions = {
+ default = {
+ [0x00B1] = { -- ±
+ yoffset = 100,
+ },
+ [0x2213] = { -- ∓
+ yoffset = -100,
+ },
+ },
+ },
+}
+\stoptyping
+
+This will raise and lower the glyphs in their bounding boxes and give them
+an appearance more close to their ancestors. But defined this way, they are
+always applied and that might not be what we want. So, we can do this:
+
+\starttyping
+mathematics = {
+ dimensions = {
+ signs = {
+ [0x00B1] = { -- ±
+ yoffset = 100,
+ },
+ [0x2213] = { -- ∓
+ yoffset = -100,
+ },
+ },
+ },
+}
+\stoptyping
+
+This time the application is feature driven. As with all features, setting them
+up has to happen {\em before} fonts are loaded. This will do the trick:
+
+\starttyping
+\definefontfeature [lm-math] [mathdimensions=signs]
+\stoptyping
+
+The \type {lm-math} feature is not defined by default but can be used for such
+purposes. It {\em is} defined with the fontname:
+
+\starttyping
+\definefontsynonym
+ [LMMathRoman-Regular]
+ [file:latinmodern-math-regular.otf]
+ [features={math\mathsizesuffix,lm-math},
+ goodies=lm]
+\stoptyping
+
+A rather specialized goodie is the one that is used to specify math cut|-|ins. A
+good quality math font has these kerns already defined but even then you might
+want to add or replace some by your own. Here is an example of such a patch.
+Normally there are multiple goodies defined in one file but we only show kerns
+here:
+
+\starttyping
+local kern_200 = { bottomright = { { kern = -200 } } }
+local kern_100 = { bottomright = { { kern = -100 } } }
+
+return {
+ name = "pagella-math",
+ version = "1.00",
+ comment = "Goodies that complement pagella.",
+ author = "Hans Hagen",
+ copyright = "ConTeXt development team",
+ mathematics = {
+ kerns = {
+ [0x1D449] = kern_200, -- math italic V
+ [0x1D44A] = kern_100, -- math italic W
+ },
+ },
+}
+\stoptyping
+
+As with other goodies the file is loaded with:
+
+\starttyping
+\definefontsynonym
+ [MathRoman] % names used in definitions
+ [file:texgyrepagella-math.otf] % the file to be loaded
+ [features=math\mathsizesuffix, % size dependent features
+ goodies=pagella-math] % the goodie file to be applied
+\stoptyping
+
+This is typically a goodie that is always applied and not driven by a feature.
+After all, the values given are passed to the engine (after being scaled).
+
+Most goodies are bound to fonts of collections of fonts. This is different for
+treatments. These ship with the distribution but you can also provide your own.
+As this is still somewhat experimental we just mention a few aspects. The entries
+are filenames that point to tables.
+
+\starttyping
+return {
+ name = "treatments",
+ version = "1.00",
+ comment = "Goodies that deals with some general issues.",
+ author = "Hans Hagen",
+ copyright = "ConTeXt development team",
+ treatments = {
+ ["adobeheitistd-regular.otf"] = {
+ embedded = false, -- not yet used
+ comment = "this font is part of acrobat",
+ },
+ ["crap.ttf"] = {
+ ignored = true,
+ comment = "a text file with suffix ttf",
+ },
+ ["latinmodern-math.otf"] = {
+ comment = "experimental",
+ },
+ ["rubish-regular.ttf"] = {
+ comment = "check output for missing à and á",
+ }
+ },
+}
+\stoptyping
+
+The comment entry in such a table becomes part of the message at the end
+of a run:
+
+\startnarrowtyping
+mkiv lua stats > loaded fonts: 2 files: latinmodern-math.otf (experimental), lmroman12-regular.otf
+\stopnarrowtyping
+
+The ignored flag signals the font name database builder to ignore the file. This
+means that the font can still be known as file, but that its (name based)
+properties are not collected. As you asked explicitly for a file, the file can
+still be loaded. You can use this trick to avoid issues with the database builder
+in case of a problematic file, but a real run will still try to load the file. After
+all, you get what you ask for. If loading and usage is successful you get at least
+the message reported at the end of the run.
+
+\stopsection
+
+\startsection[title=Analyzers]
+
+An \OPENTYPE\ font is kind of special in the sense that it provides some
+information on how to turn sequences of characters into sequences of glyphs. In
+fact, if all fonts had a reasonable repertoire of glyphs most of the information
+that concerns combining, remapping and shuffling the input and|/|or mapping onto
+glyphs could as well happen in the renderer. This means that fonts have many of
+their internal features tables in common, or more precisely could share many gsub
+related issues, if only there had been some predefined sets of substitutional
+features.
+
+So, for most of the time, a feature processor just does what the font demands and
+the font provides the information. There are however a few cases where font only
+provide part of the logic. Take for instance the \type {init}, \type {medi},
+\type {fina} and \type {isol} features that relate to positions in the word: the
+start, the end, in the middle or isolated. For these features to work the engine
+has to provide information about the state of a character (glyph) and this is where
+analysis kicks in. Just watch this:
+
+\startbuffer
+\definefontfeature
+ [default-with-analyze]
+ [default]
+ [script=latn,mode=node,
+ init=yes,medi=yes,fina=yes,isol=yes]
+
+\showotfcomposition
+ {dejavu-serif*default-with-analyze at 24pt}
+ {}
+ {I don't wanna know tha\utfchar{"300}t!}
+\stopbuffer
+
+\typebuffer
+
+In the tracer the different categories are colored. This kind of information is
+especially important for typesetting Arabic. Normally \CONTEXT\ can figure out
+itself when this is needed so you don't have to worry too much about this kind of
+additional actions.
+
+\blank \getbuffer \blank
+
+\stopsection
+
+\startsection[title=Processors]
+
+ \startnotabene
+ Todo.
+ \stopnotabene
+
+\stopsection
+
+\startsection[title=Optimizing]
+
+ \startnotabene
+ Todo.
+ \stopnotabene
+
+\stopsection
+
+\startsection[title=Tracing]
+
+There are a lot of tracing options in \MKIV, but most will never be seen by users. Most
+are enabled using the tracker mechanism. Some have a bit more visibility and have a dedicated
+command to trigger them.
+
+When something is going terribly wrong, you will always get a message but sometimes even an
+end|-|user has to request for more information. An example are missing characters. There are
+several ways to get them reported:
+
+\starttyping
+\enabletrackers[fonts.missing=replace]
+\enabletrackers[fonts.missing=remove]
+\enabletrackers[fonts.missing]
+\stoptyping
+
+For historic reasons we also have:
+
+\starttyping
+\checkcharactersinfont
+\removemissingcharacters
+\replacemissingcharacters
+\stoptyping
+
+which happens automatically when you enable the tracker. There is some extra
+overhead involved so you might want to turn on this feature on only if you really
+expect characters not to be present.
+
+Say that we use Latin Modern fonts and ask for some of the rare fractions:
+
+\startbuffer
+\definedfont[lmroman10-regular*default-with-missing at 10pt]
+a b c ½ ⅓ ¼ ⅕ ⅙ ⅛ Ɣ ɣ ʤ ʭ ʮ α β γ
+\stopbuffer
+
+\typebuffer
+
+\enabletrackers[fonts.missing=replace]
+We get this: \start \getbuffer \stop
+\removeunwantedspaces . \space
+In the log file you will find something like this:
+\par \disabletrackers[fonts.missing]
+
+\starttyping
+fonts > characters > start missing characters: lmroman10-regular.otf
+
+missing > U+00194 Ɣ LATIN CAPITAL LETTER GAMMA
+missing > U+00263 ɣ LATIN SMALL LETTER GAMMA
+missing > U+002A4 ʤ LATIN SMALL LETTER DEZH DIGRAPH
+missing > U+002AD ʭ LATIN LETTER BIDENTAL PERCUSSIVE
+missing > U+002AE ʮ LATIN SMALL LETTER TURNED H WITH FISHHOOK
+missing > U+003B1 α GREEK SMALL LETTER ALPHA
+missing > U+003B2 β GREEK SMALL LETTER BETA
+missing > U+003B3 γ GREEK SMALL LETTER GAMMA
+missing > U+02153 ⅓ VULGAR FRACTION ONE THIRD
+missing > U+02155 ⅕ VULGAR FRACTION ONE FIFTH
+missing > U+02159 ⅙ VULGAR FRACTION ONE SIXTH
+missing > U+0215B ⅛ VULGAR FRACTION ONE EIGHTH
+
+fonts > characters > stop missing characters
+\stoptyping
+
+If you're lucky your editor will use a font that shows the missing characters (dejavu
+monospace is a good candidate).
+
+The replacement characters can help you to locate the spots where something is missing
+so that an alternative can be considered. The replacements resemble the category
+of the missing character.
+
+\showmissingcharacterslegend
+
+You can call up this legend after loading an extra module:
+
+\starttyping
+\usemodule[s][fonts-missing]
+
+\showmissingcharacterslegend
+
+\showmissingcharacters
+\stoptyping
+
+The last command shows a detailed list of missing characters
+
+\showmissingcharacters
+
+Here the characters are shown, because we use a monospaced font that happens to
+have them. Of course this example uses characters that are rarely used and are
+unlikely to show up in future versions of the Latin Modern fonts.
+
+\startnotabene
+ Here a few more relevant trackers will be mentioned.
+\stopnotabene
+
+\stopsection
+
+% \startsection[title=Discretionaries]
+%
+% \startbuffer
+% \definedfont[cambria*default]
+% 12\discretionary
+% {3} {4} {5}%
+% 67\par
+% 12{\oldstyle\discretionary
+% {3} {4} {5}}%
+% 67\par
+% 12\discretionary
+% {3{\oldstyle3}} {{\oldstyle4}4} {5{\oldstyle5}5}%
+% 67\par
+% \stopbuffer
+%
+% The font handler has to do some magick to get features working with and across
+% discretionaries. To some extend you can use font switches inside discretionaries
+% but for sure border cases are not dealt with. This works:
+%
+% \startlinecorrection[blank]
+% \startcombination[nx=4,ny=1,location=top]
+% {\framed[align=normal]{\enabledirectives [otf.alwaysdisc]\setupwhitespace[line]\getbuffer}} {1}
+% {\framed[align=normal]{\enabledirectives [otf.alwaysdisc]\hsize1mm\getbuffer}} {2}
+% {\framed[align=normal]{\disabledirectives[otf.alwaysdisc]\setupwhitespace[line]\getbuffer}} {3}
+% {\framed[align=normal]{\disabledirectives[otf.alwaysdisc]\hsize1mm\getbuffer}} {4}
+% \stopcombination
+% \stoplinecorrection
+%
+% The first two examples have \type {otf.alwaysdisk} enabled, the last two have it
+% disabled.
+%
+% \typebuffer
+%
+% \stopsection
+
+\startsection[title=Some remarks]
+
+If you talk about features and fonts it is not difficult to end up speaking
+\OPENTYPE . However, in \CONTEXT\ we use the term in a more general way, if only
+because we provide more features. In traditional \TEX\ we have a few features:
+ligatures, smallcaps and kerns, and to some extent we can see oldstyle numerals
+also as feature. It is however important to notice that in \OPENTYPE\ ligatures
+are just a synonym for combining multiple characters into on. From the user
+interface point of view these operations are grouped into \type {liga}, \type
+{dlig}, \type {clig} and \type {rlig} and for \TEX ies we have \type {tlig}. The
+distinction is not as clear as one might think: any feature can use the ligature
+builder. And as a consequence we see that happen too, for instance some fonts use
+\type {ccmp} for constructing mandatory ligatures.
+
+Some of these interpretations (or maybe even tricks) are side effects of for
+instance user interfaces. If one can for instance not turn on or off the \type
+{ccmp} feature, but can do that for \type {liga}, then one way to keep some
+ligatures in for instance letter spaced text, is to put them into \type {ccmp},
+assuming that this one will always be enabled. Eventually that then becomes a
+sort of standard. Personally I don't like such pseudo standards but we have to
+live with them.
+
+Another example of such a standard is the used of non breakable spaces to
+influence treatment of some Devanagari characters. Where \UNICODE\ has special
+characters to influence mechanisms that combine and replace characters, the lack
+of some triggers others to be used and eventually that becomes a standard.
+Similar ambiguities arise with math: we have no way to indicate math (while we do
+have ways to indicate a change in writing order).
+
+Talking of math, take \OPENTYPE\ math: at some point there is a draft, that then
+gets implemented in one word processor using one font, but omissions or
+imperfections that surface (maybe because more fonts and engines are developed)
+stay around because the initial implementation is published and frozen, simply
+because there are many users that stick to expectations. Where \TEX ies accept a
+few years of development, this is not true for commercial applications. \footnote
+{Of course \HTML\ is the biggest example of this: we're stuck forever with open
+tags without close tags, mixed uppercase and lowercase tags, attributes without
+value or values without quotes.}
+
+So, although there is without doubt progress, some annoyances stay. The \TEX\
+community has always been able to adapt, and this is one reason why a \LUA\
+implementation is nice: it gives room for experiments, extensions, variants, etc.
+Of course it also makes a bit more independent, although one may wonder if that
+matters any longer in a rapidly changing world. The original idea behind \TEX,
+that it should be useable for ages, will survive, but users might see more
+changes in a lifetime than foreseen when \TEX\ showed up.
+
+\stopsection
+
+\startsection[title=Different spaces]
+
+The width of the space and its stretch and shrink are taken from the font. The so
+called emspace is the reference for much spacing related parameters. It is the
+width of character \type {0x2014}. The regular space width is taken from \type
+{0x0020}, the space character. When there is no space character, in the case of a
+monospaced font we take the emwidth, otherwise we take half the emwidth. As a
+last resort we can take the average width of characters. And of even that fails
+we take half of the font units. When there is no emwidth that one is set to the
+font units.
+
+In the \CONTEXT\ font loader we use a stretch that is 1/2 of the width of a space
+and the shrink is 1/3 the width of a space, so we use values that are quite
+similar to what \TEX\ always used.
+
+You can overload these values when a font is loaded and the overload is
+implemented as a feature. The next example demonstrates how this is done:
+
+\startbuffer
+\definefontfeature[morespace][spacing=0.50 plus 0.50 minus 0.250]
+\definefontfeature[lessspace][spacing=0.25 plus 0.25 minus 0.125]
+
+\definedfont[Serif*default] \samplefile{klein}\blank
+\definedfont[Serif*default,morespace]\samplefile{klein}\blank
+\definedfont[Serif*default,lessspace]\samplefile{klein}\blank
+\definedfont[Serif*default] \samplefile{klein}\blank
+\stopbuffer
+
+\typebuffer \blank \getbuffer \blank
+
+\stopsection
+
+\startsection[title=Dynamic features]
+
+We can enable and disable features any time in the input by using the
+\type {\feature} command. he following example was posted on the list:
+
+\startbuffer
+\definefont
+ [WeirdShapes]
+ [file:libertiner*default]
+
+\definefontfeature
+ [hist]
+ [hlig=yes]
+
+\definefontfeature
+ [rare]
+ [dlig=yes]
+
+\setupquotation
+ [style={\feature[+][hist,rare]}]
+
+\startlines
+\WeirdShapes
+strict {\feature[+][hist]strict}
+wurtzite {\feature[+][rare]wurtzite}
+\quotation{strict wurtzite}
+\stoplines
+\stopbuffer
+
+\typebuffer
+
+Or typeset:
+
+\getbuffer
+
+The \type {\feature} command takes as first argument a directive of what
+do do:
+
+\starttabulate[|T||]
+\NC + more \NC add set to previous set and combine with font set \NC \NR
+\NC - less \NC subtract set to previous set and combine with font set \NC \NR
+\NC = new \NC replace font set \NC \NR
+\NC ! < reset \NC forget sets and revert to font set \NC \NR
+\NC > old default \NC make sure the current set is used on top of the font set \NC \NR
+\stoptabulate
+
+\stopsection
+
+\startsection[title=Spacekerns]
+
+Some fonts kern glyphs with spaces. Although \TEX\ doesn't really have spaces we do
+support this. However, it's implemented as part of kerning so when you define such
+kerns you need to hook it into for instance the \type {kern} feature:
+
+\starttyping
+\startluacode
+ local kern = -50
+ local pair = { [32] = kern }
+
+ fonts.handlers.otf.addfeature {
+ name = "kern", -- spacekerns assume kern
+ type = "kern",
+ data = {
+ A = pair, V = pair, W = pair,
+ [32] = {
+ A = kern,
+ V = kern,
+ W = kern,
+ },
+ }
+ }
+\stopluacode
+\stoptyping
+
+Of course this depends on font properties so one can wonder how useful this is.
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-formats.tex b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-formats.tex
new file mode 100644
index 00000000000..9ad6bc9bda0
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-formats.tex
@@ -0,0 +1,896 @@
+% language=uk
+
+\startcomponent fonts-formats
+
+\environment fonts-environment
+
+\startchapter[title=Font formats][color=darkred]
+
+\startsection[title=Introduction]
+
+In this chapter the font formats as we know them will be introduced. The
+descriptions will be rather general but more details can be found in the
+appendix. Although in \MKIV\ we do support all these types eventually the focus
+will be on \OPENTYPE\ fonts but it does not hurt to see where we are coming from.
+
+\stopsection
+
+\startsection[title=Glyphs]
+
+A typeset text is mostly a sequence of characters turned into glyphs. We talk of
+characters when you input the text, but the visualization involves glyphs. When
+you copy a part of the screen in an open \PDF\ document or \HTML\ page back to
+your editor you end up with characters again. In case you wonder why we make this
+distinction between these two states we give an example.
+
+\startplacefigure [location=here,reference=fig:character-glyph,title=From characters to glyphs.]
+ \startcombination
+ {\color[maincolor]{\definedfont[Serif*default at 30pt]affiliation}} {upright}
+ {\color[maincolor]{\definedfont[SerifItalic*default at 30pt]affiliation}} {italic}
+ \stopcombination
+\stopplacefigure
+
+We see here that the shape of the \type {a} is different for an upright serif and
+an italic. We also see that in \type {ffi} there is no dot on the \type {i}. The
+first case is just a stylistic one but the second one, called a ligature, is
+actually one shape. The 11 characters are converted into 9 glyphs. Hopefully the
+final document format carries some extra information about this transformation so
+that a cut and paste will work out well. In \PDF\ files this is normally the
+case. In this document we will not be too picky about the distinction as in most
+cases the glyph is rather related to the character as one knows it.
+
+So, a font contains glyphs and it also carries some information about
+replacements. In addition to that there needs to be at least some information
+about the dimensions of them. Actually, a typesetting engine does not have to
+know anything about the actual shape at all.
+
+\startplacefigure [location=here,reference=fig:glyph-dimension-normal,title=The boundingbox of some normal glyphs.]
+ \startcombination[9*1]
+ {\ruledhbox{\color[maincolor]{\definedfont[Serif*default at 30pt]a}}} {}
+ {\ruledhbox{\color[maincolor]{\definedfont[Serif*default at 30pt]b}}} {}
+ {\ruledhbox{\color[maincolor]{\definedfont[Serif*default at 30pt]g}}} {}
+ {\ruledhbox{\color[maincolor]{\definedfont[Serif*default at 30pt]l}}} {}
+ {\ruledhbox{\color[maincolor]{\definedfont[Serif*default at 30pt]q}}} {}
+ {\ruledhbox{\color[maincolor]{\definedfont[Serif*default at 30pt].}}} {}
+ {\ruledhbox{\color[maincolor]{\definedfont[Serif*default at 30pt];}}} {}
+ {\ruledhbox{\color[maincolor]{\definedfont[Serif*default at 30pt]?}}} {}
+ {\ruledhbox{\color[maincolor]{\definedfont[Serif*default at 30pt]ffi}}} {}
+ \stopcombination
+\stopplacefigure
+
+\startplacefigure [location=here,reference=fig:glyph-dimension-italic,title=The boundingbox of some italic glyphs.]
+ \startcombination[9*1]
+ {\ruledhbox{\color[maincolor]{\definedfont[SerifItalic*default at 30pt]a}}} {}
+ {\ruledhbox{\color[maincolor]{\definedfont[SerifItalic*default at 30pt]b}}} {}
+ {\ruledhbox{\color[maincolor]{\definedfont[SerifItalic*default at 30pt]g}}} {}
+ {\ruledhbox{\color[maincolor]{\definedfont[SerifItalic*default at 30pt]l}}} {}
+ {\ruledhbox{\color[maincolor]{\definedfont[SerifItalic*default at 30pt]q}}} {}
+ {\ruledhbox{\color[maincolor]{\definedfont[SerifItalic*default at 30pt].}}} {}
+ {\ruledhbox{\color[maincolor]{\definedfont[SerifItalic*default at 30pt];}}} {}
+ {\ruledhbox{\color[maincolor]{\definedfont[SerifItalic*default at 30pt]?}}} {}
+ {\ruledhbox{\color[maincolor]{\definedfont[SerifItalic*default at 30pt]ffi}}} {}
+ \stopcombination
+\stopplacefigure
+
+The rectangles around the shapes \in {figure} [fig:glyph-dimension-normal] and \in
+{figure} [fig:glyph-dimension-italic] are called boundingbox. The dashed line
+reflects the baseline where they eventually are aligned onto next to each other.
+The amount above the baseline is called height, and below is called depth. The
+piece of the shape above the baseline is the ascender and the bit below the
+descender. The width of the bounding box is not by definition the width of the
+glyph. In \TYPEONE\ and \OPENTYPE\ fonts each shape has a so called advance width
+and that is the one that will be used.
+
+\usemodule[fonts-kerns]
+
+\startplacefigure [location=here,reference=fig:glyph-kerns,title={Kerning in Latin Roman, Cambria, Pagella and Dejavu.}]
+ \scale[width=\textwidth]{\startcombination[1*4]
+ {\color[maincolor]{\definedfont[name:lmroman10-regular*default sa 1]\ShowKernedHBox{Very often glyphs get very small spaces inserted horizontally.}}} {}
+ {\color[maincolor]{\definedfont[name:cambria*default sa 1]\ShowKernedHBox{Very often glyphs get very small spaces inserted horizontally.}}} {}
+ {\color[maincolor]{\definedfont[name:texgyrepagellaregular*default sa 1]\ShowKernedHBox{Very often glyphs get very small spaces inserted horizontally.}}} {}
+ {\color[maincolor]{\definedfont[name:dejavuserif*default sa 0.9]\ShowKernedHBox{Very often glyphs get very small spaces inserted horizontally.}}} {}
+ \stopcombination}
+\stopplacefigure
+
+Another traditional property of a font is kerning. In \in {figure}
+[fig:glyph-kerns] you see this in action. These examples
+demonstrate that not all fonts need (or provide) the same kerns
+(in points).
+
+So, as a start, we have now met a couple of properties of a font.
+They can be summarized as follows:
+
+\starttabulate[|l|p|]
+\NC mapping to glyphs \EQ characters are represented by a shapes that have recognizable
+ properties so that readers know what they mean \NC \NR
+\NC ligature building \EQ a sequence of characters gets mapped onto one glyph \NC \NR
+\NC dimensions \EQ each glyph has a width, height and depth \NC \NR
+\NC inter-glyph kerning \EQ optionally a bit of positive or negative space has to be inserted between glyphs \NC \NR
+%NC italic correction \EQ a correction is applied between an oblique shape and what follows \NC \NR
+\stoptabulate
+
+Regular font kerning is hardly noticeable and improves the overall look of the
+page. Typesetting applications sometimes are capable of inserting additional
+spaces between shapes. This more excessive kerning is not that much related to
+the font and is used for special purposes, like making a snippet of text stand
+out. In \CONTEXT\ this kind of kerning is available but it is a font independent
+feature. Keep in mind that when applying that kind of rather visible kerning
+you'd better not have ligatures and fancy replacements enabled as \CONTEXT\
+already tries to deal with that as good as possible.
+
+\stopsection
+
+\startsection[title=The basic process]
+
+In \TEX\ a font is an abstraction: the engine only needs to know about the
+mapping from characters to glyphs, what the width, height and depth is, what
+sequences need to be translated into ligatures and when kerning has to be
+applied. If for the moment we forget about math, these are all the properties
+that matter and this is what the \TEX\ font metric files that we see in the next
+section provide.
+
+Because one of the principles behind \LUATEX\ is that the core engine (the
+binary) stays small and that new functionality is provided in \LUA\ code, the
+font subsystem largely looks like it always has been. As users will normally use
+a macro package most of the loading will be hidden from the user. It is however
+good to give a quick overview of how for instance \PDFTEX\ deals with fonts using
+traditional metric files.
+
+\startFLOWchart[pdftex]
+ \startFLOWcell
+ \name {source}
+ \location {1,1}
+ \shape {action}
+ \text {input}
+ \connection [rl] {parser}
+ \stopFLOWcell
+ \startFLOWcell
+ \name {parser}
+ \location {2,1}
+ \shape {action}
+ \text {characters}
+ \connection [rl] {builder}
+ \stopFLOWcell
+ \startFLOWcell
+ \name {builder}
+ \location {3,1}
+ \shape {action}
+ \text {glyphs}
+ \connection [rl] {backend}
+ \stopFLOWcell
+ \startFLOWcell
+ \name {backend}
+ \location {4,1}
+ \shape {action}
+ \text {subset}
+ \stopFLOWcell
+\stopFLOWchart
+
+\startplacefigure [location=here,reference=fig:tfm-pdftex,title={Several translation steps in a traditonal \TEX\ flow.}]
+ \FLOWchart[pdftex]
+\stopplacefigure
+
+The input (bytes) gets translated into characters by the input parser. Normally
+this is a one|-|to|-|one translation but there are examples of some translation
+taking place. You can for instance make characters active and give them a
+meaning. So, the eight bit represention of an editors code page \type {ë} can
+become something else internally, for instance a regular \type {e} with an \type
+{¨} overlayed. It can also become another character, which in the code page
+would be shown as \type {á} but the user will not know this as by then this byte
+is already tokenized. Another example is multibyte translation, for instance
+\UTF\ sequences can get remapped to something that is known internally as being a
+character of some kind. The \LUATEX\ engine expects \UTF\ so a macro package has
+to make sure that translation to this encoding happens beforehand, for instance
+using a callback that intercepts the input from file. \footnote {In \CONTEXT\ we
+talk of input regimes and these can be mixed, although in practice most users
+will stick to \UTF\ and never use regimes.}
+
+So, the input character (sequence) becomes tokens representing a character. From
+these tokens \TEX\ will start building a (linked) node list where each character
+becomes a node. In this node there is a reference to the current font. If you
+know \TEX\ you will understand that a list can have more than characters: there
+can be skips, kerns, rules, references to images, boxes, etc.
+
+At some point \TEX\ will handle this list over to a routine that will turn them
+into something that resembles a paragraph or otherwise snippet of text. In that
+stage hyphenation kicks in, ligatures get built and kerning is added. Character
+references become glyph indices. This list can finally be broken into lines.
+
+It is no secret that \TEX\ can box and unbox material and that after unboxing
+some new formatting has to happen. The traditional engine has some optimizations
+that demand a partial reconstruction of the original list but in \LUATEX\ we
+removed this kind of optimization so there the process is somewhat simpler. We
+will see more of that later.
+
+When \TEX\ ships out a page, the backend will load the real font data and merge
+that into the final output. It will now take the glyph index and build the right
+data structures and references to the real font. As a font gets subset only the
+used glyphs end up in the final output.
+
+There is one tricky aspect involved here: re|-|encoding. In so called map files
+one can map a specific metric filename onto a real font name. One can also
+specify an encoding vector that tells what a given index really refers to. This
+makes it possible to use fonts that have more than 256 glyphs and refer to any of
+them. This is also the trick that makes it possible to use \TRUETYPE\ fonts in
+\PDFTEX: the backend code filters the right glyphs from the font, remapping
+\TEX's glyph indices onto real entries in the font happens via the encoding
+vector. In \in {figure} [fig:tfm-bytes] we show a possible route for input byte
+68.
+
+\startFLOWchart[bytes]
+ \startFLOWcell
+ \name {source}
+ \location {1,1}
+ \shape {action}
+ \text {bytes (68)}
+ \connection [rl] {parser}
+ \stopFLOWcell
+ \startFLOWcell
+ \name {parser}
+ \location {2,1}
+ \shape {action}
+ \text {bytes (31)}
+ \connection [rl] {builder}
+ \stopFLOWcell
+ \startFLOWcell
+ \name {builder}
+ \location {3,1}
+ \shape {action}
+ \text {index (31)}
+ \connection [rl] {backend}
+ \stopFLOWcell
+ \startFLOWcell
+ \name {backend}
+ \location {4,1}
+ \shape {action}
+ \text {index (88)}
+ \stopFLOWcell
+\stopFLOWchart
+
+\startplacefigure [location=here,reference=fig:tfm-bytes,title={From bytes to indices.}]
+ \FLOWchart[bytes]
+\stopplacefigure
+
+As \LUATEX\ carries much of the bagage of older engines, you can still do it this
+way but in \CONTEXT\ \MKIV\ we have made our live much simpler: we use unicode as
+much as possible. This means that we effectively have removed two steps (see \in
+{figure} [fig:tfm-luatex]).
+
+\startFLOWchart[luatex]
+ \startFLOWcell
+ \name {source}
+ \location {1,1}
+ \shape {action}
+ \text {input}
+ \connection [rl] {builder}
+ \stopFLOWcell
+ \startFLOWcell
+ \name {builder}
+ \location {2,1}
+ \shape {action}
+ \text {glyphs}
+ \stopFLOWcell
+\stopFLOWchart
+
+\startplacefigure [location=here,reference=fig:tfm-luatex,title={Simplified mapping in \LUATEX.}]
+ \FLOWchart[luatex]
+\stopplacefigure
+
+There is of course still some work to do for the backend, like subsetting, but
+the nasty dependency on the input encoding, font encoding (that itself relates to
+hyphenation) and backend re|-|encoding is gone. But keep in mind that the
+internal data structure of the font is still quite traditional.
+
+Before we move on to font formats I like to point out that there is no space in
+\TEX. Spaces in the input are converted into glue, either or not with some
+stretch and|/|or shrink. This also means that accessing character 32 in
+traditional \TEX\ will not end up as space in the output.
+
+\stopsection
+
+\startsection[title=\TEX\ metrics]
+
+\appendixdata{\in[fontdata:tfm]}
+\appendixdata{\in[fontdata:vf]}
+
+Traditional font metrics are packaged in a binary format. Due to the limitations
+of that time a font has at most 256 characters. In books dedicated to \TEX\ you
+will often find tables that show what glyphs are in a font, so we will not repeat
+that here as after all we got rid of that limitation in \LUATEX.
+
+Because 256 is not that much, especially when you mix many scripts and need lots
+of symbols from the same font, there are quite some encodings used in traditional
+\TEX, like \type {texnansi}, \type {ec} and \type {qx}. When you use \LUATEX\
+exclusively you can do with way less font files. This is easier for users,
+especially because most of those files were never used anyway. It's interesting
+to notice that some of the encodings contain symbols that are never used or used
+only once in a document, like the copyright or registered symbols. They are often
+accessed by symbolic names and therefore easily could have been omitted and
+collected in a dedicated symbol font thereby freeing slots for more useful
+characters anyway. The lack of coverage is probably one of the reasons why new
+encodings kept popping up. In the next table you see how many files are involved
+in Latin Modern which comes in a couple of design sizes. \footnote {The original
+Computer Modern fonts have \METAFONT\ source files and (runtime) generated bitmap
+files in whatever resolutions are needed for previewing and printing. The
+\TYPEONE\ follow|-|up came in several sets, organized by language support. The
+Latin Modern fonts have a few more weights and variants than Computer Modern.}
+
+\starttabulate[|l|c|r|r|r|]
+\HL
+\NC \bf font format \NC \bf type \NC \bf \# files \NC \bf size in bytes \NC \bf \CONTEXT \NC \NR
+\HL
+\NC type 1 \NC tfm \NC 380 \NC 3.841.708 \NC \NC \NR
+\NC \NC afm \NC 25 \NC 2.697.583 \NC \NC \NR
+\NC \NC pfb \NC 92 \NC 9.193.082 \NC \NC \NR
+\NC \NC enc \NC 15 \NC 37.605 \NC \NC \NR
+\NC \NC map \NC 9 \NC 42.040 \NC \NC \NR
+\HL[darkgray]
+\NC \NC \NC 521 \NC 15.812.018 \NC mkii \NC \NR
+\HL
+\NC opentype \NC otf \NC 73 \NC 8.224.100 \NC mkiv \NC \NR
+\HL
+\stoptabulate
+
+A \TFM\ file can contain so called italic corrections. This is an additional kern
+that can be added after a character in order to get better spacing between an
+italic shape and an upright one. As this is manual work, it's a not that advanced
+mechanism, but in addition to width, height, depth, kerns and ligatures it is
+nevertheless a useful piece of information. But, it's a rather \TEX\ specific
+quantity.
+
+Since \TEX\ showed up many fonts have been added. In addition support for
+commercial fonts was provided. In fact, for that to happen, one only needs
+accompanying metric files for \TEX\ itself and map files and encoding vectors
+for the backend. Because a metric file also has some general information, like
+spacing (including stretch and shrink), the ex|-|height and em|-|width, this
+means that sometimes guesses must be made when the original font does not come
+with such parameters.
+
+At some point virtual fonts were introduced. In a virtual font a \TFM\ file has
+an accompanying \VF\ file. In that file each glyph has a specification that tells
+where to find the real glyph. It is even possible to construct glyphs from other
+glyphs. In traditional \TEX\ this only concerns the backend, which in \PDFTEX\ is
+built in. In \LUATEX\ this mechanism is integrated into the frontend which means
+that users can construct such virtual fonts themselves. We will see more of that
+later, but for now it's enough to know that when we talk about the representation
+of font (the \TFM\ table) in \LUATEX, this includes virtual functionality.
+
+An important limitation of \TFM\ files cq.\ traditional \TEX\ is that the number
+of depths and heights is limited to 16 each. Although this results in somewhat
+inaccurate dimensions in practice this gets unnoticed, if only because many
+designs have some consistency in this. On the other hand, it is a limitation when
+we start thinking of accents or even multiple accents which lead to many more
+distinctive heights and depths.
+
+Concerning ligatures we can remark that there are quite some substitutions
+possible although in practice only the multiple to one replacement has been used.
+
+Some fonts that are used in \TEX\ started out as bitmaps but rather soon
+\TYPEONE\ outline fonts became the fashion. These are supported using the map
+files that we will discuss later. First we look into \TYPEONE\ fonts.
+
+\stopsection
+
+\startsection[title=\TYPEONE]
+
+\appendixdata{\in[fontdata:afm]}
+\appendixdata{\in[fontdata:enc]}
+\appendixdata{\in[fontdata:map]}
+
+For a long time \TYPEONE\ fonts have dominated the scene. These are \POSTSCRIPT\
+fonts that can have more that 256 glyphs in the file that defines the shapes, but
+only 256 of them can be used at one time. Of course there can be multiple subsets
+active in one document.
+
+In traditional \TEX\ a \TYPEONE\ font is used by making a \TFM\ file from a so
+called Adobe metric file (\AFM) that come with such a font. There are several
+tool chains for doing this and \CONTEXT\ \MKII\ ships with one that can be of
+help when you need to support commercial fonts. Projects like the Latin Modern
+Fonts and \TEX\ Gyre have normalized a whole lot of fonts that came in several
+more or less complete encodings into a consistent package of \TYPEONE\ fonts.
+This already simplified live a lot but still users had to choose a suitable input
+and font encoding for their language and|/|or script. As \TEX\ only cares about
+metrics and not about the rendering, it doesn't consider \TYPEONE\ fonts as
+something special. Also, as \TEX\ and \POSTSCRIPT\ were developed about the same
+time support for \TYPEONE\ fonts is rather present in \TEX\ distributions.
+
+You can still follow this route but for \CONTEXT\ \MKIV\ this is no longer the
+recommended way because there we have changed the whole subsystem to use
+\UNICODE. As a result we no longer use \TFM\ files derived from \AFM\ files, but
+directly interpret the \AFM\ data. This not only removes the 256 limitation, but
+also brings more resolution in height and depth as we no longer have at most 16
+alternatives. There can also be more kerns. Of course we need some heuristics to
+determine for instance the spacing but that is not different from former times.
+
+Because most \TEX\ users don't use commercial fonts, they will not notice that
+\CONTEXT\ \MKIV\ treats \TYPEONE\ fonts this way. One reason is that the free
+fonts also come as wide fonts in \OPENTYPE\ format and whenever possible
+\CONTEXT\ prefers \OPENTYPE\ over \TYPEONE\ over \TFM.
+
+In the beginning \LUATEX\ only could load a \TFM\ file, which is why loading
+\AFM\ files is implemented in \LUA. Later, when the \OPENTYPE\ loaded was added,
+loading \PFB\ and \AFM\ files also became possible but it's slower and we see no
+reason to rewrite the current code in \CONTEXT. We also do a couple of extra
+things when loading such a file. As more \TYPEONE\ fonts move on to \OPENTYPE\ we
+don't expect that much usage anyway.
+
+\stopsection
+
+\startsection[title=\OPENTYPE]
+
+\appendixdata{\in[fontdata:otf]}
+
+When an engine can deal with \UNICODE\ directly it also means that internally it
+uses pretty large numbers for storing characters and glyph indices. The first
+\TEX\ descendent that went wide was \OMEGA, later replaced by \ALEPH. However, this
+engine never took off and still used its own extended \TFM\ format: \OFM. In fact,
+as \LUATEX\ uses some of the \ALEPH\ code, it can also use these extended metric
+files but I don't think that there are any useful fonts around so we can forget
+about this.
+
+We use the term \OPENTYPE\ for a couple of font formats that share the same
+principles: \OPENTYPE\ (\OTF), \TRUETYPE\ (\TTF) and \TRUETYPE\ containers
+(\TTC). The \LUATEX\ font reader presents them in a similar format. In the case
+of a \TRUETYPE\ container, one does not load the whole font but selects an
+instance from it. Internally an \OPENTYPE\ font can have the glyphs organized in
+subfonts.
+
+The first \TEX\ descendent to really go wide from front to back is \XETEX. This
+engine can use \OPENTYPE\ fonts directly and for a whole category of users this
+opened up a new world. Hoever, it is still mostly a traditional engine. The
+transition from characters to glyphs is accomplished by external libraries, while
+in \LUATEX\ we code in \LUA. This has the disadvantage that it is slower
+(although that depends on the job) but the advantage is that we have much more
+control and can extend the font handler as we like.
+
+An \OPENTYPE\ font is much more complex than a \TYPEONE\ one. Unless it is a
+quick and dirty converted existing font, it will have more glyphs to start with.
+Quite likely it will have kerns and ligatures too and of course there are
+dimensions. However, there is no concept of a depth and height. These need to be
+deduced from the bounding box instead. There is an advance width. This means that
+we can start right away using such fonts if we map those properties onto the
+\TFM\ table that \LUATEX\ expects.
+
+But there is more, take ligatures. In a traditional font the sequence \type {ffi}
+always becomes a ligature, given that the font has such a glyph. In \LUATEX\
+there is a way to disable this mechanism, which is sometimes handy when dealing
+with mono|-|spaced fonts in verbatim. It's pretty hard to disable that. For
+instance one option is to insert kerns manually. In an \OPENTYPE\ font ligatures
+are collected in a so called feature. There can be many such features and even
+kerning is a feature. Other examples are old style numerals, fractions,
+superiors, inferiors, historic ligatures and stylistic alternates.
+
+\starttabulate[|lT|l|l|l|l|]
+\NC \type{onum} \NC \ruledhbox{\maincolor\DemoOnumLM\char45 1}
+ \NC \ruledhbox{\maincolor\DemoOnumLM1234567890}
+ \NC \ruledhbox{\maincolor\DemoOnumLM\char"A2}
+ \NC \ruledhbox{\maincolor\DemoOnumLM\char"24} \NC \NR
+%NC \type{lnum} \NC \ruledhbox{\maincolor\DemoLnumLM\char45 1}
+% \NC \ruledhbox{\maincolor\DemoLnumLM1234567890}
+% \NC \ruledhbox{\maincolor\DemoLnumLM\char"A2}
+% \NC \ruledhbox{\maincolor\DemoLnumLM\char"24} \NC \NR
+\NC \type{tnum} \NC \ruledhbox{\maincolor\DemoTnumLM\char45 1}
+ \NC \ruledhbox{\maincolor\DemoTnumLM1234567890}
+ \NC \ruledhbox{\maincolor\DemoTnumLM\char"A2}
+ \NC \ruledhbox{\maincolor\DemoTnumLM\char"24} \NC \NR
+\NC \type{pnum} \NC \ruledhbox{\maincolor\DemoPnumLM\char45 1}
+ \NC \ruledhbox{\maincolor\DemoPnumLM1234567890}
+ \NC \ruledhbox{\maincolor\DemoPnumLM\char"A2}
+ \NC \ruledhbox{\maincolor\DemoPnumLM\char"24} \NC \NR
+\stoptabulate
+
+To this all you need to add that features operate in two dimensions: languages
+and scripts. This means that when ligatures are enabled for Dutch the \type {ij}
+sequence becomes a single glyph but for German it gets mapped onto two glyphs.
+And, to make it even more complex, a substitution can depend on circumstances,
+which means that for Dutch \type {fijn} becomes \type {f ij n} but \type {fiets}
+becomes \type {fi ets}. It will be no surprise that not all \OPENTYPE\ fonts come
+with a complete and rich repertoire of rules. To make things worse, there can be
+rules that turn \type {1/2} into one glyph, or transfer the numbers into superior
+and inferior alternatives, but leaves us with an unacceptable rendered \type
+{1/a}, given that the \type {frac} features is enabled. It looks like features
+like this are to be applied to a manually selected range of characters.
+
+The fact that an \OPENTYPE\ font can contain many features and rules to apply
+them makes it possible to typeset scripts like Arabic. And this is where it gets
+vague. A generic \OPENTYPE\ sub|-|engine can do clever things using these rules,
+but if you read the specification for some scripts additional intelligence has to
+be provided by the typesetting engine.
+
+While users no longer have to care about encodings, map files and back|-|end
+issues, they do have to carry knowledge about the possibilities and limitations
+of features. Even worse, he or she needs to be aware that fonts can have bugs.
+Also, as font vendors have no tradition of providing updates this is something
+that we might need to take care of ourselves by tweaking the engine.
+
+One of the problems with the transition from \TYPEONE\ to \OPENTYPE\ is that font
+designers can take an existing design and start from that basic repertoire of
+shapes. If such a design had oldstyle figures only, there is a good chance that
+this will be the case in the \OPENTYPE\ variant too. However, such a default
+interferes with the fact that the \type {onum} feature is one that we explicitly
+have to enable. This means that writing a generic style where a font is later
+plugged in becomes somewhat messy if it assumes that features need to be turned
+on.
+
+\TEX\ users expect more control, which means that in practice just an \OPENTYPE\
+engine is not enough, but for the average font the \TEX\ model using the
+traditional approach still is quite acceptable. After all, not all users use
+complex scripts or need advanced features. And, in practice most readers don't
+notice the difference anyway.
+
+\stopsection
+
+\startsection[title=\LUA]
+
+\appendixdata{\in[fontdata:lua]}
+
+As mentioned support for virtual fonts is built into \LUATEX\ and loading the so
+called \VF\ files happens when needed. However, that concerns traditional fonts
+that we already covered. In \CONTEXT\ we do use the virtual font mechanism for
+creating missing glyphs out of existing ones or add fallbacks when this is not
+possible. But this is not related to some kind of font format.
+
+In 2010 and 2011 the first public \OPENTYPE\ math fonts showed up that replace
+their \TYPEONE\ originals. In \CONTEXT\ we already went forward and created
+virtual \UNICODE\ fonts out of traditional fonts. Of course eventually the
+defaults will change to the \OPENTYPE\ alternatives. The specification for such a
+virtual font is given in \LUA\ tables and therefore you can consider \LUA\ to be
+a font format as well. In \CONTEXT\ such fonts can be defined in so called
+goodies files. As we use these files for much more tuning, we come back to that
+in a later chapter. In a virtual font you can mix real \TYPEONE\ fonts and real
+\OPENTYPE\ fonts using whatever metrics suit best.
+
+An extreme example is the virtual \UNICODE\ Punk font. This font is defined in
+the \METAPOST\ language (derived from Don Knuths \METAFONT\ sources) where each
+glyph is one graphic. Normally we get \POSTSCRIPT, but in \LUATEX\ we can also
+get output in a comparable \LUA\ table. That output is converted to \PDF\
+literals that become part of the virtual font definitions and these eventually
+end up in the \PDF\ page stream. So, at the \TEX\ end we have regular (virtual)
+characters and all \TEX\ needs is their dimensions, but in the \PDF\ each glyph
+is shown using drawing operations. Of course the now available \OPENTYPE\ variant
+is more efficient, but it demonstrates the possibilities.
+
+\stopsection
+
+\startsection[title=Files]
+
+We summarize these formats in the following table where we explain what the file
+suffixes stand for:
+
+\starttabulate[|Tl|p|]
+\HL
+\NC tfm \NC This is the traditional \TEX\ font metric file format and it reflects
+ the internal quantities that \TEX\ uses. The internal data structures
+ (in \LUATEX) are an extension of the \TFM\ format. \NC \NR
+\NC vf \NC This file contains information about how to construct and where to
+ find virtual glyphs and is meant for the backend. With \LUATEX\ this
+ format gets more known. \NC \NR
+\NC pk \NC This is the bitmap format used for the first generation of \TEX\
+ fonts but the typesetter never deals with them. Bitmap files are more
+ or less obselete. \NC \NR
+\HL
+\NC ofm \NC This is the \OMEGA\ variant of the \type {tfm} files that caters for
+ larger fonts. \NC \NR
+\NC ovf \NC This is the \OMEGA\ variant of the \type {vf}. \NC \NR
+\HL
+\NC pfb \NC In this file we find the glyph data (outlines) and some basic
+ information about the font, like name|-|to|-|index mappings. A
+ differently byte|-|encoded variant of this format is \type {pfa}.\NC
+ \NR
+\NC afm \NC This file accompanies the \type {pfb} file and provides additional
+ metrics, kerns and information about ligatures. A binary variant of
+ this is the \PFA\ format. For \MSWINDOWS\ there is a variant that has the
+ \type {pfm} suffix. \NC \NR
+\NC map \NC The backend will consult this file for mapping metric file names onto
+ real font names. \NC \NR
+\NC enc \NC The backend will include (and use) this encoding vector to map
+ internal indices to font indices using glyph names, if needed. \NC
+ \NR
+\HL
+\NC otf \NC This binary format describes not only the font in terms of metrics,
+ features and properties but also contains the shapes. \NC \NR
+\NC ttf \NC This is the \MICROSOFT\ variant of \OPENTYPE. \NC \NR
+\NC ttc \NC This is the \MICROSOFT\ container format that combines multiple fonts
+ in one. \NC \NR
+\HL
+\NC fea \NC A (\FONTFORGE) feature definition file. Such a file can be loaded and
+ applied to a font. This is no longer supported in \CONTEXT\ as we have
+ other means to achieve the same goals. \NC \NR
+\NC cid \NC A glyph index (name) to \UNICODE\ mapping file that is referenced
+ from an \OPENTYPE\ font and is shared between fonts. \NC \NR
+\HL
+\NC lfg \NC These are \CONTEXT\ specific \LUA\ font goodie files providing
+ additional information. \NC \NR
+\HL
+\stoptabulate
+
+If you look at how files are organized in a \TEX\ distribution, you will notice
+that these files all get their own place. Therefore adding a \TYPEONE\ font to
+the distribution is not that trivial if you want to avoid clashes. Also, files
+are simply not found when they are not in the right spot. Just to mention a few
+paths:
+
+\starttyping
+<root>/fonts/tfm/vendor/typeface
+<root>/fonts/vf/vendor/typeface
+<root>/fonts/type1/vendor/typeface
+<root>/fonts/truetype/vendor/typeface
+<root>/fonts/opentype/vendor/typeface
+<root>/fonts/fea
+<root>/fonts/cid
+<root>/fonts/dvips/enc
+<root>/fonts/dvips/map
+\stoptyping
+
+There can be multiple roots and the right locations are specified in a
+configuration file. Currently all engines can use the \DVIPS\ encoding and map
+files, so luckily we don't need to duplicate this. For some reason \TRUETYPE\ and
+\OPENTYPE\ fonts have different locations and you need to be aware of the fact
+that some fonts come in both formats (just to confuse users) so you might end up
+with conflicts.
+
+In \CONTEXT\ we try to make live somewhat easier by also supporting a simple path
+structure:
+
+\starttyping
+<root>/fonts/data/vendor/typeface
+\stoptyping
+
+This way files are kept together and installing commercial fonts is less complex
+and error prone. Also, in practice we only have one set of files now: one of the
+other \OPENTYPE\ formats.
+
+If you want to see the difference between a traditional (\PDFTEX\ or \XETEX\ plus
+\CONTEXT\ \MKII) setup or a modern one (\LUATEX\ with \CONTEXT\ \MKIV) you can
+install the \CONTEXT\ suite (formerly known as minimals). If you explicitly
+choose for a \LUATEX\ only setup, you will notice that far less files get
+installed.
+
+\stopsection
+
+\startsection[title=Text]
+
+This is not an in|-|depth explanation of how to define and load fonts in
+\CONTEXT. First of all this is covered in other manuals, but more important is
+that we assume that the reader is already familiar with the way \CONTEXT\ deals
+with fonts. Therefore we limit ourselves to some remarks and expand on this a bit
+in later chapters.
+
+The font subsystem has evolved over years and when you look at the low level code
+you will probably find it complex. This is true, although in some aspects it is
+not as complex as in \MKII\ where we also had to deal with encodings due to the
+eight bit limitations. In fact, setting up fonts is easier due the fact that we
+have less files to deal with.
+
+The main properties of a (modern) font subsystem for typesetting text are the
+following:
+
+\startitemize[n]
+ \startitem
+ We need to be able to switch the look and feel efficiently and
+ consistently, for instance going from regular to bold or italic. So,
+ when we load a font family we not only load one file, but often
+ at least four: regular, bold, italic (oblique) and bolditalic
+ (boldoblique).
+ \stopitem
+ \startitem
+ When we change the size we also need to make sure that these related
+ sets are changed accordingly. You really want the bold shapes to scale
+ along with the regular ones.
+ \stopitem
+ \startitem
+ Shapes are organized in serif, sans serif, mono spaced and math and for
+ proper working of a typesetter that has math all over you need always
+ need the math. Again, when you change size, all these shapes need to
+ scale in sync.
+ \stopitem
+ \startitem
+ In one document several families can be combined so the subsystem should
+ make it possible to switch from one to the other without too much
+ overhead.
+ \stopitem
+ \startitem
+ Because section heads and other structural elements have their own sizes
+ there has to be a consistent way to deal with that. It should also be
+ possible to specify exceptions for them.
+ \stopitem
+\stopitemize
+
+In the next chapters we will cover some details, for instance font features. You
+can actually control these when setting up a body font, simply by redefining
+the \type {default} feature set, but not all features are dealt with this way.
+So let's continue the demands put on a font subsystem.
+
+\startitemize[continue]
+ \startitem
+ Sometimes inter|-|character kerning is needed. In \CONTEXT\ this is not a
+ property of a font because glyphs can be mixed with basically anything.
+ This kind of features is applied independent of a font.
+ \stopitem
+ \startitem
+ The same is true for casing (like uppercasing and such) which is not
+ related to a font but applied to a selected (or marked) piece of the
+ input stream.
+ \stopitem
+ \startitem
+ Using so called \quotation {small caps} or \quotation {old style}
+ numerals or \unknown\ can be dealt with by setting the default features
+ but often these are applied selectively. As these are applied using the
+ information in a font they do belong to the font subsystem but in
+ practice they can be seen as independent (assuming that the font supports
+ them at all).
+ \stopitem
+ \startitem
+ Protrusion (into margins) and expansion (to improve whitespace) are
+ applied to the font at load time because the engine needs to know about
+ them. But they two can selectively be turned on and off. They are more
+ related to line break handling than font defining.
+ \stopitem
+ \startitem
+ Slanting (to fake oblique) and expanding (to fake bold) are regular
+ features but are applied to the font because the engine needs to know
+ about them. They permanently influence the shape.
+ \stopitem
+\stopitemize
+
+We will discuss these in this manual too. What we will not discuss in depth is
+spacing, even when it depends on the (main body) font size. These use properties
+of fonts (like the ex|-|height or em|-|width and maybe the width of the space,
+but normally they are controlled by the spacing subsystem. We will however
+mention some rather specific possibilities:
+
+\startitemize[continue]
+ \startitem
+ The \CONTEXT\ font subsystem provides ways to combine multiple fonts
+ into one.
+ \stopitem
+ \startitem
+ You can construct artificial fonts, using existing fonts or \METAPOST\
+ graphics.
+ \stopitem
+ \startitem
+ Fonts can be fixed (dimensions) and completed (for instance accented
+ characters) when loading/
+ \stopitem
+ \startitem
+ There are extensive tracing options, not only for applied features but
+ also for loading, checking etc. There is a set of styles that can be
+ used to study fonts.
+ \stopitem
+\stopitemize
+
+Sometimes users ask for very special trickery and it no surprise then that some
+of that is now widely know (or even discussed in detail). When we get notice of
+that we can mention it in this manual.
+
+So how does this all relate to font formats? We mentioned that when loading we
+basically load some four files per family (and more if we use specific fonts for
+titling). These files just provide the data: metric information, shapes and ways
+to remap characters (or sequences) into glyphs, either of not positioned relative
+to each other. In traditional \TEX\ only dimensions, kerns and ligatures
+mattered, but in nowadays we also deal with specific \OPENTYPE\ features. But
+still, as you can deduce from the above, this is only part of the story. You need
+a complete and properly integrated system. It is no big deal to set up some
+environment that uses font files to achieve some typesetting goal, but to provide
+users with some consistent and extensible system is a bit more work.
+
+There are basically three font formats: good old bitmaps, \TYPEONE\ and
+\OPENTYPE. All need to be supported and expectations are that we also support
+their features. But is should be noticed that whatever font you use, the quality
+of the outcome depends on what information the font can provide. We can improve
+processing but are often stuck with the font. There are many thousands of
+fonts out there and we need to be able to use them all.
+
+\stopsection
+
+\startsection[title=Math]
+
+In the previous section we already mentioned math fonts. The fonts are just one
+aspect of typesetting math and math fonts are special in the sense that they have
+to provide the relevant information. For instance a parenthesis comes in several
+sizes and at some point turns in a symbol made out of pieces (like a top curve,
+middle lines and bottom curve) that overlap. The user never sees such details. In
+fact, there are ot that many math fonts and these are already set up so there is
+not much to mess up here. Nevertheless we mention:
+
+\startitemize [n]
+ \startitem
+ Math fonts are loaded in three sizes: text, script and scriptscript. The
+ optimal relative sizes ar defined in the font.
+ \stopitem
+ \startitem
+ There are direction aware math fonts and we support this in \CONTEXT.
+ \stopitem
+ \startitem
+ Bold math is in fact a bolder version of a regular math font (that can
+ have bold symbols too). Again this is supported.
+ \stopitem
+\stopitemize
+
+The way math is dealt with in \CONTEXT\ is different from the way it is done
+traditionally. Already when we started with \MKIV\ we moved to \UNICODE\ and
+the setup at the font level is kept simple by delegating some of the work to
+the \LUA\ end. We will see some of the mentioned aspects in more detail later.
+
+Because of it's complexity and because in a math text there can be many times
+activation of math fonts (and related settings) quite some effort has been put in
+making it efficient. But you need to keep in mind that when we discuss math
+related topics later on, this is hardly of concern. Math fonts are loaded only
+once so manipulating them a bit has no penalty. And using them later on is hardly
+related to the font subsystem.
+
+Concerning formats we can notice that traditional \TEX\ comes with math fonts
+that have properties that the engine can use. Because there were not many math
+fonts, this was no problem. The \OPENTYPE\ math fonts however are also used in
+other applications and therefore are a bit more generic. \footnote {Their
+internals are now defined in the \OPENTYPE\ specification.} For this we not only
+had to adapt the math engine in \LUATEX\ (although we kept that to the minimum)
+but we also had to think different about loading them. In later chapters we will
+see that in the transition to \UNICODE\ math fonts we implemented a mechanism for
+combining \TYPEONE\ fonts into virtual \UNICODE\ fonts. We did that because it
+made no sense to keep an old and new loader alongside.
+
+There will not be thousands of math fonts flying around. A few dozen is already a
+lot and the developers of macro packages can set them up for the users. So, in
+practice there is not much that a user needs to know about math font formats.
+
+\stopsection
+
+\startsection[title=Caching]
+
+Because fonts can be large and because we use \LUA\ tables to describe them
+a bit of effort has been put into managing them efficiently. Once converted
+to the representation that we need they get cached. You can peek into the cache
+which is someplace on your system (depending on the setup):
+
+\starttabulate[|l|p|]
+\NC \type{fonts/data} \NC font name databases \NC \NR
+\NC \type{fonts/mp} \NC fonts created using \METAPOST \NC \NR
+\NC \type{fonts/one} \NC type one fonts, converted from \type {afm} and \type
+ {pfb} files \NC \NR
+\NC \type{fonts/otl} \NC open type fonts, converted from \type {ttf}, \type {otf},
+ \type {ttc} and \type {ttx} files loaded using the
+ \CONTEXT\ \LUA\ loader \NC \NR
+\NC \type{fonts/pdf} \NC font shapes for color fonts \NC \NR
+\NC \type{fonts/shapes} \NC outlines of fonts (for instance for use in \METAFUN) \NC \NR
+\NC \type{fonts/streams} \NC font programs for variable font instances \NC \NR
+\stoptabulate
+
+There can be three types of files there. The \type{tma} files are just \LUA\
+tables and they can be large. These files can be compiled to bytecode where \type
+{tmc} is for stock \LUATEX\ and \type {tmb} for \LUAJITTEX. The \type {tma} files
+are optimized for space and memory (aka: packed) but you can expand them with
+\type {mtxrun --script font}.
+
+Fonts in the cache are automatically updated when you install new versions of a
+font or when the \CONTEXT\ font loader has been updated.
+
+\stopsection
+
+\startsection[title=Paths]
+
+The search for fonts happens on paths defined in \type {texmf.cnf}. The information
+in there is used to generate a file database for fast access with priorities based
+on file type. The \TDS\ is starting point. The environment variable driven paths
+\type {OSFONTDIR} (set automatically) and \type {EXTRAFONTDIR} are taken into account.
+
+In addition you can set \type {RUNTIMEFONTS} which is, when set, consulted at
+runtime. You can also add a path in your style:
+
+\starttyping
+\usefontpath[c:/data/projects/myproject/fonts]
+\stoptyping
+
+although in general we recommend to put fonts in
+
+\starttyping
+<texroot>/tex/texmf-fonts/fonts/data]
+\stoptyping
+
+which is more efficient.
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-hooks.tex b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-hooks.tex
new file mode 100644
index 00000000000..7ee5dc198b8
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-hooks.tex
@@ -0,0 +1,917 @@
+% language=uk
+
+\startcomponent fonts-hooks
+
+\environment fonts-environment
+
+\startchapter[title=Hooks][color=darkcyan]
+
+\startsection[title=Introduction]
+
+One of the virtues of \TEX\ is its flexibility. Because we cannot predict what
+users want to mess around with, much of the underlying code has hooks. And because
+it's not too hard to add functionality that will break things we will not advocate
+all of it. Of course you can study the code and figure out what can be done and
+there is no problem with that. It's just that you shouldn't expect much support.
+
+In this chapter we collect some of these hooks. If you run into interesting ones
+that are worth mentioning, you can always ask us to add description here.
+
+\stopsection
+
+\startsection[title=Safe hooks]
+
+\startsubsection[title=Trimming fonts]
+
+Because we store font related information in \LUA\ tables there can be situations
+where the resources used outgrow memory. An example of such a font is \type
+{lastresort} that basically defined the whole \UNICODE\ range. The font is
+actually not that large as it uses similar placeholders for glyphs in a range,
+but it has rather verbose (redundant) names. As we normally don't need these, you
+can decide to strip them away.
+
+\starttyping
+\startluacode
+ fonts.handlers.otf.readers.registerextender {
+ name = "remove names from lastresort",
+ action = function(fontdata)
+ if fontdata.metadata.fullname == "LastResort" then
+ for k, v in next, fontdata.descriptions do
+ v.name = nil
+ end
+ end
+ end
+ }
+\stopluacode
+
+\definedfont[LastResort][lastresort*default sa 1]
+\stoptyping
+
+This will result in a much smaller font, one that has less change to crash the
+engine due to lack of memory. Extenders like this are applied once the font has
+been loaded but before it gets saved.
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title=Loading]
+
+\startsubsection[title=Introduction]
+
+We basically have to deal with three font formats that can easily be recognized
+by the suffix of the files involved: \type {tfm} and \type {vf} files that
+describe 8 bit fonts, traditionally bitmap fonts, but as they carry only metric
+information, any 8 bit font can be described. Then there are \type {afm} files
+that contain metrics related to \TYPEONE\ fonts (stored in \type {pfb} files).
+Although such fonts could contain more than 256 shapes, the implementation was
+limited to 8 bits too. By converting \type {afm} files to \type {tfm} files,
+traditional \TEX\ can deal with \TYPEONE\ given that the backend can include them
+in the final result.
+
+In this section we will discuss some aspects of the \OPENTYPE\ font reader. As
+\TEX\ only deals with metrics (in the frontend) we need to parse them, filter
+information from it and pass the metrics to \TEX. In addition, we can use all
+kind of extra information to manipulate the so called node list but in the end
+\TEX\ is only interested in font id's (that point to a font resource) and glyph
+indexes.
+
+To overcome the 256 limitation of \TYPEONE\ fonts, in \CONTEXT\ we moved away
+from \type {tfm} files (we can of course still deal with them) and turn \type
+{afm} files into so called wide fonts. Basically we turn them in a more rich
+format that looks similar to the internal \OPENTYPE\ format we use. We will not
+go into much detail about that because \TYPEONE\ is kind of obsolete and being
+replaced by \OPENTYPE, but we will of course support the old formats simply
+because we have all these fonts around.
+
+Already early in the development of \LUATEX\ a font loader library was created
+that can turn an \OPENTYPE\ (but also a \TYPEONE) font into a \LUA\ table. This
+library is derived from \FONTFORGE\ which makes it possible to look into a font
+using that editor and at the same time get a similar view on the font in \LUA,
+which is quite handy. However, at some point in \CONTEXT\ we wanted to play with
+outlines in \METAPOST\ and for that purpose an \OPENTYPE\ reader was written in
+\LUA\ that could extract the data. Because \TYPEONE\ fonts already were done in
+\LUA\ it was a logical step to also do \OPENTYPE\ in \LUA\ so now we use an
+alternative loader that doesn't depend in the \FONTFORGE\ library. This not only
+gives more flexibility but also makes it possible to avoid some conversions
+needed to provide the \CONTEXT\ font handler with the needed information in an
+efficient way.
+
+\stopsubsection
+
+\startsubsection[title=Loading \OPENTYPE\ fonts]
+
+As with most binary media formats today an \OPENTYPE\ font file is a linked list
+of records. The top level structure is called table. There are two flavours of
+\OPENTYPE\ where the main difference is in the way the shapes are defined: they
+can be \TRUETYPE\ outlines using quadratric bezier curves or cff files using
+cubic bezier curves. The last variant is the same as \POSTSCRIPT\ \TYPEONE\
+fonts. Simplified, a quadratic curve defines the shape in points with a control
+point in between, while a quadratic one also has points but each with two control
+points (as in \METAPOST).
+
+An \OPENTYPE\ font can be large: there can be upto 65536 glyphs and lots of extra
+properties and features. In order to save space the data is rather packed using
+different numeric data types. Of course one can wonder if size really matters now
+that most bandwidth is taken by audio, video and pictures but we have to live
+with it.
+
+The definition of \OPENTYPE\ can be found on the \MICROSOFT\ website:
+\hyphenatedurl {https://www.microsoft.com/typography/otspec}. Most tables then
+could make sense for us are mentioned in the following list:
+
+\starttabulate[|Bl|l|l|]
+\NC required \NC cmap \NC character to glyph mapping \NC \NR
+\NC \NC head \NC font header \NC \NR
+\NC \NC hhea \NC horizontal header \NC \NR
+\NC \NC hmtx \NC horizontal metrics \NC \NR
+\NC \NC maxp \NC maximum profile \NC \NR
+\NC \NC name \NC naming table \NC \NR
+\NC \NC os/2 \NC os/2 and windows specific metrics \NC \NR
+\NC \NC post \NC postScript information \NC \NR
+\NC truetype \NC glyf \NC glyph data \NC \NR
+\NC \NC loca \NC index to location \NC \NR
+\NC postscript \NC cff \NC compact font format \NC \NR
+\NC \NC vorg \NC vertical origin \NC \NR
+\NC typographic \NC base \NC baseline data \NC \NR
+\NC \NC gdef \NC glyph definition data \NC \NR
+\NC \NC gpos \NC glyph positioning data \NC \NR
+\NC \NC gsub \NC glyph substitution data \NC \NR
+\NC \NC jstf \NC justification data \NC \NR
+\NC \NC math \NC math layout data \NC \NR
+\NC extras \NC kern \NC kerning \NC \NR
+\NC \NC ltsh \NC linear threshold data \NC \NR
+\NC \NC vhea \NC vertical metrics header \NC \NR
+\NC \NC vmtx \NC vertical metrics \NC \NR
+\NC \NC colr \NC color table \NC \NR
+\NC \NC cpal \NC color palette table \NC \NR
+\stoptabulate
+
+When we read these tables it depends on what we want to do with the result how
+much we will really read. For instance when we only want to identify a font and
+get some basic information we don't need to read all tables and certainly don't
+need to read them completely. If we want to have the outlines we need to read the
+\type {glyf} or \type {cff} table. If we also want to boundingbox of \POSTSCRIPT\
+shapes we even need to process the shapes so that we know the dimensions of the
+result. There is no need to summarize the format here in detail because you can
+find it on the \MICROSOFT\ site. Here I only cover some aspects that influence
+the way \TEX\ can use the fonts.
+
+One of the main differences between the readers is that the \FONTFORGE\ reader
+has a lot of (recovery) heuristics for bad fonts. Nowadays most fonts are quite
+okay, and in \CONTEXT\ we prefer to just reject bad ones. In the process of
+loading the built|-|in loader gives each glyph a name (it makes them up for
+variants needed for features). It also tries to figure out some font properties,
+like the weight. If does a pretty good job on that but it is also hard to repair
+at the \LUA\ end when it makes a bad guess. The \LUA\ variants stays closer to
+the specification, but delegates more to the final user, which is good because we
+need and want that level of control as controls is what \TEX\ is about. It also
+made it possible to support for instance colored fonts without too much effort.
+
+So what data needs to be collected? If we look at what we get eventually the list
+of glyphs is the bulk. For each glyph we collect some metric information. For
+instance we fetch the (advance) width of the glyph but also the boundingbox,
+which gives us the the height and depth.
+
+In the font file the list of glyphs starts at zero and runs up tot the total
+number of glyphs. The index in this table is used in for instance the tables that
+define the font features, for instance kerning between glyphs, or multiple glyphs
+that are turned into ligatures. Each glyph gets a name. That can be a meaningful
+one but also a rather dumb one, for instance the index number.
+
+Eventually (at least in \CONTEXT) we don't order by glyph index but by \UNICODE.
+The font file contains information about the mapping from index to \UNICODE. In
+principle other encodings are possible but we stick to \UNICODE. But, because
+many glyphs can refer to one \UNICODE\ slot, for instance a regular shape as well
+as a smallcaps or oldstyle variant. These extra glyphs we let end up in the
+private \UNICODE\ areas. This also means that with each glyph in the final table
+there is also a field that has the \UNICODE. Because we order by \UNICODE\ we
+also need to store the index. An example from a Latin Modern font is:
+
+\starttyping
+[97] = {
+ boundingbox = { 34, -10, 474, 446 },
+ index = 28,
+ name = "a",
+ unicode = 97,
+ width = 490,
+}
+\stoptyping
+
+Another example is the following. Here we end up in private space:
+
+\starttyping
+[983059] = {
+ boundingbox = { 30, -10, 734, 446 },
+ index = 19,
+ name = "oe.dup",
+ unicode = 339,
+ width = 762,
+}
+\stoptyping
+
+Yet another entry is:
+
+\starttyping
+[306] = {
+ boundingbox = { 28, -22, 790, 683 },
+ index = 357,
+ name = "I_J",
+ unicode = { 73, 74 },
+ width = 839,
+ },
+\stoptyping
+
+Here you see two \UNICODE\ numbers. That kind of information is deduced from the
+name of the glyph, using knowledge on how such names are supposed to be
+constructed, or, when that is not possible, from ligature information in the
+fonts.
+
+It makes no sense to discuss the whole font table in detail, if only because most users
+will never (need to) see it. But if your curious you can have a look at the fonts
+in the cache tree, in the \CONTEXT\ distribution from the \CONTEXT\ garden this is
+
+\starttyping
+.../tex/texmf-cache/luatex-cache/context/<somehash>/fonts/otl
+\stoptyping
+
+There can be three kind of files there, with suffixes \type {tma}, \type {tmc}
+and \type {tmb}. The first one is the table as converted from the binary font
+file. The second and third variants are just bytecode compilations of this file
+(for \LUATEX\ and|/|or \LUAJITTEX). The bytecode variants are smaller but more
+important, they load a bit faster. On my disk the largest \type{tma} file is just
+below 10 MByte (an extensive \CJK\ font) but normally they are in the few hundred
+KByte range (some are real small), with the bytecode files of course being
+relatively small to their original.
+
+However, there is a bit of cheating here. If we run the command:
+
+\starttyping
+mtxrun --script font --convert lmroman10-regular.otf
+\stoptyping
+
+A \LUA\ file is generated: \type {lmroman10-regular.lua}. This file is much larger
+than the \type {tma} file in the cache:
+
+\starttabulate[|T|T|]
+\NC 643.924 \NC lmroman10-regular.lua \NC 0.029 \NR
+\NC 209.950 \NC lmroman10-regular.tma \NC 0.010 \NR
+\NC 121.541 \NC lmroman10-regular.tmb \NC \NR
+\NC 134.564 \NC lmroman10-regular.tmc \NC 0.003 \NR
+\stoptabulate
+
+The reason for this is the following. Most information is stored in tables.
+Especially tables that describe font features can be the same all over the place.
+This is why we pack the table in a more compact format before saving it in the
+cache, and unpack it after loading. The effects on loading are neglectable but
+and it has the benefit that it saves a lot of memory. By looking at such numbers
+one should be careful with conclusions, but (assuming proper garbage collection)
+we see a memory footprint of the \type {lua} file of 2836 Kbyte, while the
+unpacked variant takes 704 Kbyte. You can imagine what happens with large \CJK\
+fonts. Loading the (larger unpacked) \type {lua} file currently costs me 0.029
+seconds, while loading and unpacking the \type {tma} file takes 0.010 seconds and
+the bytecode variant \type {tmc} 0.003 seconds.
+
+\stopsubsection
+
+\startsubsection[title=Loading \TYPEONE\ fonts]
+
+When we started with \CONTEXT\ \MKIV\ (which is shortly after we started with
+\LUATEX) the only \TFM\ files that were loaded, were those to make virtual
+\UNICODE\ math fonts, awaiting real \OPENTYPE\ math fonts. Math fonts are kind
+of special with respect to metrics and such.
+
+For \TYPEONE\ text fonts we didn't use the \TFM\ files but went for parsing \AFM\
+files. That way we could use all the glyphs provided by fonts and not be limited
+to 256 slots. So, effectively we made them \UNICODE\ and similar to \OPENTYPE. Of
+course the only features were ligatures, kerns and some special ones like \TEX\
+ligatures and replacements. With the old loader code, we always made them base
+mode fonts, which means that processing was delegated to \TEX. In the new loader
+we implement ligatures and kerns as node mode features, which means that we can
+use those fonts in base mode as well as node mode. The last options therefore
+permits to add or adapt features to \TYPEONE\ fonts as well.
+
+In the next sections we will focus on \OPENTYPE\ but as the \TYPEONE\ fonts are
+organized in a similar way, some of it also applies to this older type. The most
+important to keep in mind is that we only have \type {liga}, \type {kern} and a
+few \CONTEXT\ specific features.
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title=The tables]
+
+\startsubsection[title=Structure]
+
+Getting a font read for \TEX\ happens in stages. The original \OPENTYPE\ file is
+read only once. At that moment the shapes are described in the \type
+{descriptions} subtable while by the time that we pass the information to \TEX\
+they are in \type {characters}. The reason is that we go from dimensions in font
+units to dimensions in scaled points. We start with the following table:
+
+\ctxlua{context.tocontext(fonts.tables.data.original,"original_table")}
+
+The table passed \TEX\ is constructed from this one and looks like:
+
+\ctxlua{context.tocontext(fonts.tables.data.scaled,"scaled_table")}
+
+There might be a few more (often obscure) fields for special purposes. The
+characters subtable conforms to what \TEX\ expects, while the descriptions stays
+closer to \OPENTYPE. The \type {kerns} and \type {ligatures} subtables are there
+for base mode and are not present in \type {node} mode. The \type {commands} and
+\type {fonts} subtables relate to virtual fonts.
+
+\startitemize[packed]
+\startitem
+ Start with the (already) loaded \OPENTYPE\ table.
+\stopitem
+\startitem
+ Copy relevant information from \type {descriptions} to \type {characters} etc.
+\stopitem
+\startitem
+ Construct \type {properties} and \type {parameters} tables.
+\stopitem
+\startitem
+ Apply additional manipulators, for instance extend the \type {characters}
+ table, with expansion and protrusion.
+\stopitem
+\startitem
+ Scale the \type {characters}, \type {properties} and \type {parameters}.
+\stopitem
+\startitem
+ Apply additional manipulators.
+\stopitem
+\startitem
+ Pass the table to \TEX, but keep it around for later access.
+\stopitem
+\stopitemize
+
+One of the things you need to be aware of is that all references to glyphs are
+\UNICODE\ slots, either natural ones (representing a character) or a private one
+(representing an alternative representation). In \OPENTYPE\ features are defined
+in terms of glyph indices but we prefer \UNICODE\ because that is easier to deal
+with when we run over the node list. Before font processing the character field
+in a glyph node is a \UNICODE\ slot and afterwards it's still a \UNICODE\ but
+when it's a private one it can always be resolved to a non private slot of
+sequence of slots. Of course that could also be done with indices but it's just
+more natural this way.
+
+Another thing to note is that in the descriptions we're still working with font
+units ranging from $-1000$ to $+1000$, $-2048$ to $+2048$ or similar ranges. At
+the \TEX\ end we need scaled points which are much larger numbers.
+
+The question is: how often do users need to access the raw data in a font? After
+a decade of \MKIV\ and \LUATEX\ hardly any user has requested such access,
+probably because when needed easier interfaces were provided. Also, in the
+\CONTEXT\ distrubution there are some examples of manipulations that can be
+copied and adapted to personal use. There's also a danger is messing with the
+fonts (similar messing with the node lists): you never know how it interferes
+with other (maybe future) features.
+
+If you still want to do it, best is probably to start with saving the
+to|-|be|-|passed|-|to|-|\TEX\ table in a file and have a look at it. The most
+prominent subtable is the \type {characters} table and messing a bit with
+dimensions is rather harmless. You could add characters, for instance virtual
+ones, which again is harmless unless you use invalid commands. You probably want
+to stay away from the resources subtable, if only because some of its subtables
+are shared and therefore adapting them can have side effects. The top level \type
+{shared} and \type {unscaled} subtable are off limits as is the \type
+{specification}.
+
+You can save a font by consulting one of the hashes but for a specific font
+you need to know its id. You can do this by using low level accessors but better
+is to use the helpers made for this, because they prevent saving redundant
+data.
+
+% \starttyping
+% \startluacode
+% local nullfont = fonts.hashes.identifiers[false]
+% local currentfont = fonts.hashes.identifiers[true]
+%
+% local id, tfmdata = fonts.definers.define {
+% name = "dejavusansmono*default",
+% size = tex.sp("6pt")
+% }
+%
+% table.save("temp-nullfont.lua", nullfont)
+% table.save("temp-currentfont.lua",currentfont)
+% table.save("temp-definedfont.lua",tfmdata)
+% table.save("temp-definedfont.lua",fonts.hashes.identifiers[id])
+% \stopluacode
+% \stoptyping
+
+\starttyping
+\startluacode
+fonts.tables.save {
+ filename = "temp-font-scaled.lua",
+ fontname = "dejavusansmono*default",
+ method = "original",
+}
+\stopluacode
+\stoptyping
+
+At the \TEX\ end you can use:
+
+\starttyping
+\savefont
+ [name=dejavusansmono*default,
+ file=temp-o.lua,
+ method=original]
+\savefont
+ [name=dejavusansmono*default,
+ file=temp-s.lua,
+ method=scaled]
+\stoptyping
+
+When no \type {name} is given, the current font is used and when no \type {file}
+is given a filename is made up. The default \type {method} is \type {scaled}. The
+saved name is reported.
+
+\stopsubsection
+
+\startsubsection[title=Plug-ins]
+
+There are several places where you can hook in code: before scaling
+(initalizers), after scaling (manipulators) and while processing (processors).
+Only the first two are meant for tweaks.
+
+\starttyping
+local do_something = {
+ name = "something",
+ description = "doing something",
+ initializers = {
+ -- position = 1,
+ base = function(tfmdata,value,features) ... end,
+ node = function(tfmdata,value,features) ... end,
+ },
+ manipulators = {
+ -- position = 1,
+ base = function(tfmdata,feature,value) ... end,
+ node = function(tfmdata,feature,value) ... end,
+ },
+ processors = {
+ -- position = 1,
+ base = function(tfmdata,font,attr) ... end,
+ node = function(tfmdata,font,attr) ... end,
+ }
+}
+
+fonts.constructors.features.register.otf(so_something)
+fonts.constructors.features.register.afm(so_something)
+\stoptyping
+
+A \type {initializer} is applied just before the font gets scaled. This means
+that the characterm properties and parameters are unscaled! Initializers can for
+instance be used to add extra features to fonts. You can provide an \type
+{position} key with a number to force a place in the list of initializers but of
+course you can never be sure of interference.
+
+A \type {manipulator} is applied when the font is scaled but before it gets
+passed to \TEX. It's a good place to tweak dimensions. Here you can also probide
+a \type {position}.
+
+The processors are applied when the node list gets processed, hence the \type
+{font} and optional \type {attr} arguments. The action is only applied to the
+specified font (id) and when an attribute gets passed, this is tested for a
+value. When an attribute is used, an unset attribute on the node will skip the
+action.
+
+If adapting characters and their properties is your main objetive, then there is a
+better plugin mechanism using sequencers. We illustrate this with a fake example:
+
+\starttyping
+\startluacode
+
+function document.b_copying(tfmdata)
+ logs.report("fonts","before copying: %s",tfmdata.properties.filename)
+end
+function document.a_copying(tfmdata)
+ logs.report("fonts","after copying: %s",tfmdata.properties.filename)
+end
+
+function document.b_math(tfmdata)
+ logs.report("fonts","before math: %s",tfmdata.properties.filename)
+end
+function document.a_math(tfmdata)
+ logs.report("fonts","after math: %s",tfmdata.properties.filename)
+end
+
+utilities.sequencers.appendaction(
+ "beforecopyingcharacters",
+ "before",
+ "document.a_copying"
+)
+
+utilities.sequencers.appendaction(
+ "aftercopyingcharacters",
+ "after",
+ "document.b_copying"
+)
+
+utilities.sequencers.appendaction(
+ "mathparameters",
+ "before",
+ "document.b_math"
+)
+
+utilities.sequencers.appendaction(
+ "mathparameters",
+ "after",
+ "document.a_math"
+)
+\stopluacode
+\stoptyping
+
+When we call the next command:
+
+\starttyping
+\definedfont[MathRoman at 3pt]
+\stoptyping
+
+we get this reported:
+
+\starttyping
+fonts > before math: ...../public/dejavu/texgyredejavu-math.otf
+fonts > after math: ...../public/dejavu/texgyredejavu-math.otf
+fonts > after copying: ...../public/dejavu/texgyredejavu-math.otf
+fonts > before copying: ...../public/dejavu/texgyredejavu-math.otf
+\stoptyping
+
+In between \type {before} and \type {after} we have \type {system} which is
+reserved for \CONTEXT\ actions. These actions are executed in the scaler
+function. The function get two tables passed: the original data as well as the
+target. If you ever need these hooks, you can probably best run an \type
+{inspect} on these arguments to see what you're dealing with.
+
+Fonts get reused when possible and for that a hash is calculated depending on the
+enabled features and size. If for some reason you want to adapt that hash you can
+use postprocessors. When the \type {tfmdata} table has a subtable \type
+{postprocessors}, then the actions in that subtable will be applied. When an
+action returns a string, the string will be combined with the hash. You can set
+(o rextend) the postprocessors table using the previopusly mentioned commands.
+However, in \CONTEXT\ you can best stay away from this as it might interfere. This
+mechanism is mostly provided for generic use.
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title=Goodies]
+
+The font goodies are already discussed as an official mechanism to extend or enhance
+fonts with additional features. There are quite some goodies defined and for sure more will
+show up. Here is the full repertoire:
+
+\ctxlua{context.tocontext(fonts.tables.data.goodies,"goodie_table")}
+
+Of course you will never use all the options at the same time. The best place to
+look for examples are the \type {lfg} files in the \CONTEXT\ distribution.
+\footnote {At some point we might decide to also support goodies in the generic
+version.}
+
+\stopsection
+
+\startsection[title=Extra characters]
+
+When \TEX\ loads a font it gets stored in an internal format. Although \LUATEX\
+can still load \TFM\ files, normally we will load font data using \LUA\ and then
+pass it to \TEX. When that is done the font is basically frozen. After all, once
+you entered text and that text has been processed to a sequence of glyphs, the
+backend has to be sure that it can include the right data in the result. What
+matters there is:
+
+\startitemize[packed]
+\startitem the width of a glyph \stopitem
+\startitem the index of a glyph in the font \stopitem
+\startitem properties of a font, like its name \stopitem
+\startitem all kind manipulations don't with a virtual glyph\stopitem
+\stopitemize
+
+So, changing an already used glyph is not done. But, adding a new one should not
+be a big deal. So, starting with \LUATEX\ 1.0.5 we can add characters (that
+become glyphs) to a font after it got passed to \TEX.
+
+Of course there are some limitations to this. For instance, when \OPENTYPE\
+features are needed, you also need to extend that bit and it's not that trivial.
+But adding independent special characters is no problem. Also, you can decide to
+replace an already processed glyph by another one newly created with the same
+dimensions but a different rendering.
+
+Here I'll give a few (simple) examples. First we define a helper that creates a
+rule. After that we use all kind of \CONTEXT\ data structures and helpers but the
+general setup is not that complicated.
+
+\startbuffer
+\startluacode
+ function document.MakeGlyph(w)
+ local v = 655360
+ local w = w*v
+ local h = v
+ local d = v/3
+ return {
+ width = w,
+ height = h,
+ depth = d,
+ commands = {
+ { "down", d },
+ { "rule", h + d, w }
+ },
+ }
+ end
+\stopluacode
+\stopbuffer
+
+\typebuffer \getbuffer
+
+Of course, when one defines a font to be passed to \TEX\ it needs to conform to
+the standard. The \LUATEX\ manual describes what parameters and other properties
+have to be set. We cheat and copy the so called null font. We also create a fonts
+sub table. In such a table, a reference to id zero will be resolved to the id of
+the font.
+
+After defining the font table, we pass it to \TEX\ with \type {font,define} watch
+how we also pass an already reserved id. Then we add some characters and we also
+replace character 122 which is no problem because, after all, we haven't used it
+yet. We just use numbers so don't think we're doing \UNICODE\ here.
+
+\startbuffer
+\startluacode
+ local fontdata = fonts.hashes.identifiers
+
+ local id = font.nextid(true) -- true reserves the id
+ local nf = table.copy(fontdata[0])
+
+ local make = document.MakeGlyph
+ local add = font.addcharacters
+
+ nf.name = "foo"
+ nf.type = "virtual"
+ nf.fonts = { { id = 0 } }
+ nf.characters = {
+ [122] = make(1),
+ [123] = make(2),
+ }
+
+ font.define(id,nf)
+
+ fontdata[id] = nf
+
+ local t = make(3)
+ nf.characters[124] = t
+ add(id, {
+ fonts = nf.fonts,
+ characters = { [124] = t }
+ })
+
+ local t = make(4)
+ nf.characters[125] = t
+ add(id, {
+ fonts = nf.fonts,
+ characters = { [125] = t }
+ })
+
+ local t = make(8)
+ nf.characters[122] = t
+ add(id, {
+ fonts = nf.fonts,
+ characters = { [122] = t }
+ })
+
+ interfaces.setmacro("MyDemoFontId",id)
+\stopluacode
+\stopbuffer
+
+\typebuffer \getbuffer
+
+\startbuffer
+\def\MyDemoFont{\setfontid\MyDemoFontId}
+\stopbuffer
+
+We also define a command to access this font:
+
+\typebuffer \getbuffer
+
+\startbuffer
+{\MyDemoFont \type{[122=}\char122\type{]}}
+{\MyDemoFont \type{[123=}\char123\type{]}}
+{\MyDemoFont \type{[124=}\char124\type{]}}
+{\MyDemoFont \type{[125=}\char125\type{]}}
+\stopbuffer
+
+and we test this font as follows:
+
+\typebuffer
+
+This gives:
+
+\startlines \getbuffer \stoplines
+
+Next we extend an existing font and demonstrate several methods for extending a
+font. First we define a font that we will patch.
+
+\startbuffer
+\definefontfeature[myextension-one][default][myextension=1]
+
+\definefont[MyDemoOne][Serif*myextension-one]
+\stopbuffer
+
+\typebuffer \getbuffer
+
+\startbuffer
+\startluacode
+ local currentfont = font.current()
+ local fontdata = fonts.hashes.identifiers[currentfont]
+ local characters = fontdata.characters
+ local cfonts = fontdata.fonts
+ local addcharacters = font.addcharacters
+
+ local make = document.MakeGlyph
+
+ local function startextension()
+ statistics.starttiming()
+ end
+
+ local function stopextension(n)
+ context.NC() context.formatted.type("\\char%s",n)
+ context.NC() context.char(n)
+ context.NC() context("%0.3f",statistics.stoptiming())
+ context.NC() context.NR()
+ end
+
+ context.starttabulate { "||||" }
+
+ startextension()
+ for i=1000,1999 do
+ local t = make(3)
+ characters[i] = t
+ addcharacters(currentfont, {
+ fonts = cfonts,
+ characters = { [i] = t }
+ })
+ end
+ stopextension(1500)
+
+ startextension()
+ local t = {
+ fonts = cfonts,
+ characters = characters
+ }
+ for i=2000,2999 do
+ characters[i] = make(5)
+ addcharacters(currentfont, t)
+ end
+ stopextension(2500)
+
+ startextension()
+ for i=3000,3999 do
+ characters[i] = make(7)
+ end
+ addcharacters(currentfont, {
+ fonts = cfonts,
+ characters = characters
+ })
+ stopextension(3500)
+
+ startextension()
+ local t = { }
+ for i=4000,4999 do
+ characters[i] = make(9)
+ t[i] = characters[i]
+ end
+ addcharacters(currentfont, {
+ fonts = cfonts,
+ characters = t
+ })
+ stopextension(4500)
+
+ local addcharacters = fonts.constructors.addcharacters
+
+ startextension()
+ local t = { }
+ for i=5000,5999 do
+ t[i] = make(11)
+ end
+ addcharacters(currentfont, {
+ fonts = cfonts,
+ characters = t
+ })
+ stopextension(5500)
+
+ context.stoptabulate()
+\stopluacode
+\stopbuffer
+
+Watch how we only pass the new characters. We also need to make sure that the
+table at the \LUA\ end gets updated, because we might need the data later. You
+can see that not all methods are equally efficient. The last extension uses a
+helper that also makes sure that the main character table at the \LUA\ end gets
+updated.
+
+\typebuffer \start \MyDemoOne \getbuffer \stop
+
+\startbuffer
+\startluacode
+ local addcharacters = fonts.constructors.addcharacters
+ local currentfont = font.current()
+ local parameters = fonts.hashes.parameters[currentfont]
+
+ local m = metapost.simple
+ local f = string.formatters
+ ["draw fullsquare rotated %i scaled %b randomized 2bp withcolor %s"]
+
+ local push = { "push" }
+ local pop = { "pop" }
+
+ function make()
+ local r = parameters.size
+ local o = r/2
+ local p1 = m("metafun",f( 0, r, "red"))
+ local p2 = m("metafun",f(30, r, "green"))
+ local p3 = m("metafun",f(60, r, "blue"))
+ return {
+ width = o + r,
+ height = 2*o,
+ depth = o,
+ commands = {
+ { "down", -o/2 }, { "right", o/2 + o },
+ push, { "pdf", "origin", p1 }, pop,
+ push, { "pdf", "origin", p2 }, pop,
+ push, { "pdf", "origin", p3 }, pop,
+ },
+ }
+ end
+
+ local t = { }
+ for i=6000,6010 do
+ t[i] = make()
+ end
+ addcharacters(currentfont, {
+ fonts = cfonts,
+ characters = t
+ })
+\stopluacode
+\stopbuffer
+
+In this example we use \METAPOST\ to generate a shape. There is some juggling
+with dimensions and we need to shift the image in order to get a proper baseline.
+
+\typebuffer \start \MyDemoOne \showglyphs \getbuffer \stop
+
+These shapes show up as follows. We show the bounding box too:
+
+\startbuffer
+\scale [width=\textwidth] {%
+ \char6000 \space
+ \char6001 \space
+ \char6002 \space
+ \char6003
+}
+\stopbuffer
+
+\typebuffer \startlinecorrection \MyDemoOne \showglyphs \getbuffer \stoplinecorrection
+
+When defining virtual characters you need to keep in mind that there are limits to
+how large a character can be. If you go too far \LUATEX\ will quit with a scale
+related message.
+
+In \CONTEXT\ there are a couple of mechanism that were implemented when \LUATEX\
+came around that can be updated to use the tricks described here. I'm not sure if
+I'll do that. After all, it works now too. The main benefit of the fact that we
+can extend a font within reasonable bounds is that future mechanism can benefit
+from it.
+
+There is one thing to keep in mind. Say that we define a font like this:
+
+\starttyping
+\definefont[MyDemoOneX][Serif*myextension-one]
+\stoptyping
+
+Because we already defined a font with the same size, we automatically get the characters
+\type {6000} upto \type {6003}. If we don't want this and want a fresh instance, we can do:
+
+\starttyping
+\definefontfeature[myextension-two][default][myextension=2]
+\definefont[MyDemoOneX][Serif*myextension-two]
+\stoptyping
+
+or just:
+
+\starttyping
+\definefont[MyDemoOneX][Serif*default]
+\stoptyping
+
+Normally this kind of hackery is not arbitrary and part of a well designed set up
+so one knows what one gets.
+
+\stopsection
+
+% - features
+% - subfonts
+% - outlines
+% - math
+% - hashes
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-introduction.tex b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-introduction.tex
new file mode 100644
index 00000000000..0ca91ee9fee
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-introduction.tex
@@ -0,0 +1,95 @@
+% language=uk
+
+\startcomponent fonts-introduction
+
+\environment fonts-environment
+
+\startchapter[title=Introduction][color=darkgray]
+
+You sit in a cave and wonder how to keep track of your winter stock. While
+playing with some burned wood you end up with vertical strokes on the wall
+representing how much you have in store.
+
+You walk through the woods and wonder how to find your way back. Suddenly it
+strikes you that you can put markers on trees. Years from that moment the whole
+forest is marked with routes. Different symbols carry different meanings.
+
+The next thing you want to do is to carry around information and pass it onto
+following generations. So, you turn those symbols into shapes that make up the
+scripts that can be used to express your languages in.
+
+For ages scripts have evolved and the rendering of them on stone or wood and
+later paper has resulted in a multitude of coherent collections of so called
+glyphs. Manual labour turned into (semi) automated mass production and once that
+took off, developments went fast. But the quality was still somewhat dubious,
+especially when for instance specialized scripts like math had to be dealt with.
+
+Some 30 years ago Don Knuth wrote a book, and in the process invented the \TEX\
+typesetting system, the graphical language \METAFONT\ and a bunch of fonts. He
+made it open and free of charge. He was well aware that the new ideas were built
+on older ones that had evolved from common sense: how to keep track of things on
+paper.
+
+It is no surprise that an active community formed around these goodies. First of
+all the system has no strings attached: the licence is generous and there are no
+patents involved. There is also a network of user groups that takes care of
+coordinated updates to the whole machinery. Of course it helps that it all
+relates to Don Knuth.
+
+Since \TEX\ showed up several open and closed source typesetting systems have
+surfaced and only some of them survived. Also regular word processing has become
+more clever and still become better. The \TEX\ typesetting system also moved on.
+Some of its ideas have been used in other programs and some of the ideas of other
+programs made their way into \TEX. However, its main property is still there: you
+can tweak and tune it to your needs and are not hampered by too many limitations.
+
+Don Knuth had this chicken or egg problem: once you can typeset a source you need
+fonts but you can only make fonts if you can use them in a typesetting program.
+As a result \TEX\ came with its own fonts and it has special ways to deal with
+them. Given the limitations of that time \TEX\ puts some limitations on fonts and
+also expects them to have certain properties, something that is most noticeable
+in math fonts.
+
+Rather soon from the start it has been possible to use third party fonts in \TEX,
+for instance \TYPEONE. As \TEX\ only needs some information about the shapes, it
+was the backend that integrated the font resources in the final document. One of
+its descendants, \PDFTEX, had this backend built in and could do some more clever
+things with fonts in the typesetting process, like protrusion and expansion. The
+integration of front- and backend made live much easier. Another descendant,
+\XETEX\ made it possible to move on to the often large \OPENTYPE\ fonts. On the
+one hand this made live even more easy but at the other end it introduced users
+to the characteristics of such fonts and making the right choices, i.e.\ not fall
+in the trap of too fancy font usage.
+
+In this manual we will look at fonts from the perspective of yet another
+descendant, \LUATEX. It inherits the font technology from traditional \TEX, but
+also extends it so that we can deal with modern font technologies. Of course it
+offers much more, but in practice much relates to fonts one way or the other.
+
+Of course this exploration will be from the perspective of the \CONTEXT\ macro
+package but this is not a manual about how to use fonts in \CONTEXT\ as we have
+another manual for that. Much of what we say here applies to the generic font
+code as well, although some more advanced control is \CONTEXT\ specific. There is
+nothing real new here, and it all evolved from common sense and dealing with
+\TEX\ for many years. The perspective is mostly that of being a user myself so
+don't complain too loudly if things look complicated and unclear.
+
+There is some overlap between the chapters. This is because each chapter is
+written from another perspective and this document quite certainly will not be
+read as a whole but more by looking at examples.
+
+\startnotabene
+ This document will probably have an \quote {still under construction} state
+ for a long time. The functionality discussed here will stay and more might
+ show up. Of course there are errors, and they're all mine.
+\stopnotabene
+
+\startlines
+Hans Hagen
+PRAGMA ADE, Hasselt NL
+Summer 2011 \endash\ Spring 2016
+\stoplines
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-lookups.tex b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-lookups.tex
new file mode 100644
index 00000000000..e9448b88456
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-lookups.tex
@@ -0,0 +1,410 @@
+% language=uk
+
+\startcomponent fonts-lookups
+
+\environment fonts-environment
+
+\startchapter[title=Lookups][color=darkblue]
+
+\startsection[title=Introduction]
+
+In traditional \TEX\ a font is defined by referring to its filename. A
+definition looks like this:
+
+\starttyping
+\font \MyFontA = lmr10
+\font \MyFontB = lmr10 at 20pt
+\font \MyFontC = lmr10 scaled 1500
+\stoptyping
+
+The first definition defines the command \type {MyFontA} as a reference to the
+font stored in the file \type {lmx10}. No scaling takes place so the natural size
+is taken. This so called designsize is in no way standardized. Just look at these
+three specimen:
+
+\startlines
+{\definedfont[file:dejavuserif*default]Design Size (Dejavu)}
+{\definedfont[file:cambria*default]Design Size (Cambria)}
+{\definedfont[file:lmroman10-regular*default]Design Size (Latin Modern)}
+\stoplines
+
+The designsize is normally 10 point, but as there is no real reference for this a
+designer decides how to translate this into a visual representation. As a
+consequence the \type {20pt} in the second line of the example definitions only
+means that the font is scaled to (normally) twice the designsize. The third line
+scaled by a factor \type {1.5} and the reason for using a value thousand times
+larger is that \TEX's numbers are integers.
+
+The next three lines are typical for Latin Modern (derived from Computer Modern)
+because this family comes in different design sizes.
+
+\starttyping
+\font \MyFontD = lmr12
+\font \MyFontE = lmr12 at 20pt
+\font \MyFontF = lmr12 scaled 1500
+\stoptyping
+
+Because the designsize is part of the font metrics the second line (\type
+{\MyFontE}) is of similar size as \type {\MyFontB} although the 12~point variant
+is visually better suited for scaling up.
+
+These definitions refer to files, but what file? What gets loaded is the file
+with name \type {name.tfm}. Eventually for embedding in the (let's assume \PDF)
+file the outlines are taken from \type {name.pfb}. At that stage, when present, a
+\type {name.vf} is consulted in order to resolve characters that are combinations
+of others (potentially from other \type {pfb} files). The mapping from \type
+{name.tfm} to \type {name.pfb} filename happens in the so called map file. This
+means that one can also refer to another file, for instance \type {name.ttf}.
+
+All this logic is hard coded in the engine and because the virtual font mechanism
+was introduced later without extending the \type {tfm} format, it can be hard at
+times to figure out issues when a (maybe obsolete) virtual file is present (this
+can be the case if you have generated the \type {tfm} file from an \type {afm}
+file that comes with the \type {pfb} file when you buy one.
+
+But, in \LUATEX\ we no longer use traditional fonts and as a consequence we have
+more options open. Before we move on to them, we mention yet another definition:
+
+\starttyping
+\font \MyFontG = lmr12 sa 1.2
+\stoptyping
+
+This method is not part of \TEX\ but is provided by \CONTEXT, \MKII\ as well as
+\MKIV. It means as much as \quotation {scale this font to 1.2 times the
+bodyfontsize}. As this involves parsing the specification, it does not work
+as advertised here, but the next definition works okay:
+
+\starttyping
+\definefont[MyFontG][lmr12 sa 1.2]
+\stoptyping
+
+This indicates that we already had a parser for font specifications on board
+which in turn made it relatively easy to do even more parsing, for instance for
+font features as introduced in \XETEX\ and \LUATEX.
+
+\stopsection
+
+\startsection[title=Specifications]
+
+In \LUATEX\ we intercept the font loader. We do so for several reasons.
+
+\startitemize[packed]
+
+\startitem We want to make decisions on what file to load, this is needed when
+for instance there are files with the same name but different properties. \stopitem
+
+\startitem We want to be able to lookup by file, by name, and by more abstract specification.
+In doing so, we want to be as tolerant as possible. \stopitem
+
+\startitem We want to support several scaling methods, as discussed in the previous section. \stopitem
+
+\startitem We want to implement several strategies for passing features and defining non
+standard approaches. \stopitem
+
+\stopitemize
+
+The formal specification of a font is as follows:
+
+\starttyping
+\definefont[PublicReference][filename]
+\definefont[PublicReference][filename at dimension]
+\definefont[PublicReference][filename scaled number]
+\stoptyping
+
+We already had that extended to:
+
+\starttyping
+\definefont[PublicReference][filename]
+\definefont[PublicReference][filename at dimension]
+\definefont[PublicReference][filename scaled number]
+\definefont[PublicReference][filename sa number]
+\stoptyping
+
+So let's generalize that to:
+
+\starttyping
+\definefont[PublicReference][filename scaling]
+\stoptyping
+
+And in \MKIV\ we now have:
+
+\starttyping
+\definefont[PublicReference][filename*featurenames scaling]
+\definefont[PublicReference][filename:featurespecication scaling]
+\definefont[PublicReference][filename@virtualconstructor scaling]
+\stoptyping
+
+The second variant is seldom used and is only provided because some users
+have fonts defined in the \XETEX\ way. Users are advised not to use this
+method. The last method is special in the sense that it's used to define
+fonts that are constructed using the built in virtual font constructors. This
+method is for instance used for defining virtual math fonts.
+
+The first method is what we use most. It is really important not to forget the
+feature specification. A rather safe bet is \type {*default}. In a next chapter
+we will discuss the difference between these two; here we focus on the name part.
+
+The \type {filename} is in fact a symbolic name. In \CONTEXT\ we have always used
+an indirect reference to fonts. Look at this:
+
+\starttyping
+\definefont[TitleFont][SerifBold*default sa 2]
+\stoptyping
+
+A reference like \type {SerifBold} makes it possible to define styles independent
+of the chosen font family. This reference eventually gets resolved to a real
+name and there can be a chain of references.
+
+Font definitions can be grouped into a larger setup using typescripts. In that
+case, we can set the features for a regular, italic, bold and bolditalic for the
+whole set but when a fontname has a specific feature associated (as in the
+previous examples) that one takes precedence.
+
+so far we talked about fonts being files, but in practice a lookup happens by
+file as well as by name as known to the system. In the next section this will be
+explained in more detail.
+
+\stopsection
+
+\startsection[title=File]
+
+You can force a file lookup with:
+
+\starttyping
+\definefont[TitleFont][file:somefilename*default sa 2]
+\stoptyping
+
+If you use more symbolic names you can use the \type {file:} prefix in the
+mapping:
+
+\starttyping
+\definefontsynonym[SerifBold][file:somefile]
+\definefont[TitleFont][SerifBold*default sa 2]
+\stoptyping
+
+In projects that are supposed to run for a long time I always use the file based
+lookup, because filenames tend to be rather stable. Also, as the lookup happens
+in the \TEX\ directory structure, file lookups will rely on the general file
+search routines. This has the benefit that case is ignored. When no match is found
+the lookup will also use the font name database. Spaces and special characters are
+ignored.
+
+The name alone is not enough as there can be similar filenames with different
+suffixes. Therefore the lookup will happen in the order \ctxcommand {
+concatcommalist { list = fonts.readers.sequence, separator = ", ", last = " and
+", command = "type" } }. You can force a lookup by being more explicit, like:
+
+\starttyping
+\definefont[TitleFont][file:somefilename.ttf*default sa 1]
+\stoptyping
+
+\stopsection
+
+\startsection[title=Name]
+
+Say that we want to use a Dejavu font and that instead of filenames we want to
+use its given name. The best way to find out what is available is to call for a
+list:
+
+\starttyping
+mtxrun --script font --list --all dejavu
+\stoptyping
+
+This produces the following list:
+
+\startnarrowtyping
+dejavusans dejavusans dejavusans.ttf
+dejavusansbold dejavusansbold dejavusans-bold.ttf
+dejavusansboldoblique dejavusansboldoblique dejavusans-boldoblique.ttf
+dejavusanscondensed dejavusanscondensed dejavusanscondensed.ttf
+dejavusanscondensedbold dejavusanscondensedbold dejavusanscondensed-bold.ttf
+dejavusanscondensedboldoblique dejavusanscondensedboldoblique dejavusanscondensed-boldoblique.ttf
+dejavusanscondensednormal dejavusanscondensed dejavusanscondensed.ttf
+dejavusanscondensedoblique dejavusanscondensedoblique dejavusanscondensed-oblique.ttf
+dejavusansextralight dejavusansextralight dejavusans-extralight.ttf
+dejavusanslight dejavusansextralight dejavusans-extralight.ttf
+dejavusansmono dejavusansmono dejavusansmono.ttf
+dejavusansmonobold dejavusansmonobold dejavusansmono-bold.ttf
+dejavusansmonoboldoblique dejavusansmonoboldoblique dejavusansmono-boldoblique.ttf
+dejavusansmononormal dejavusansmonooblique dejavusansmono-oblique.ttf
+dejavusansmonooblique dejavusansmonooblique dejavusansmono-oblique.ttf
+dejavusansnormal dejavusans dejavusans.ttf
+dejavusansoblique dejavusansoblique dejavusans-oblique.ttf
+dejavuserif dejavuserif dejavuserif.ttf
+dejavuserifbold dejavuserifbold dejavuserif-bold.ttf
+dejavuserifbolditalic dejavuserifbolditalic dejavuserif-bolditalic.ttf
+dejavuserifcondensed dejavuserifcondensed dejavuserifcondensed.ttf
+dejavuserifcondensedbold dejavuserifcondensedbold dejavuserifcondensed-bold.ttf
+dejavuserifcondensedbolditalic dejavuserifcondensedbolditalic dejavuserifcondensed-bolditalic.ttf
+dejavuserifcondenseditalic dejavuserifcondenseditalic dejavuserifcondensed-italic.ttf
+dejavuserifcondensednormal dejavuserifcondensed dejavuserifcondensed.ttf
+dejavuserifitalic dejavuserifitalic dejavuserif-italic.ttf
+dejavuserifnormal dejavuserif dejavuserif.ttf
+\stopnarrowtyping
+
+The first two columns mention the names that we can use to access a font. These
+are normalized names in the sense that we only kept letters and numbers. The next three
+definitions are equivalent:
+
+\starttyping
+\definefont[TitleFont][name:dejavuserif*default sa 1]
+\definefont[TitleFont][name:dejavuserifnormal*default sa 1]
+\definefont[TitleFont][name:dejavuserif.ttf*default sa 1]
+\stoptyping
+
+In the list you see two names that all point to \type {dejavusans-extralight.ttf}:
+
+\starttyping
+dejavusansextralight
+dejavusanslight
+\stoptyping
+
+There are some heuristics built into \CONTEXT\ and we do some cleanup as well.
+For instance we interpret \type {ital} as \type {italic}. In a font there is
+sometimes information about the weight and we look at those properties as well.
+Unfortunately font names (even within a collection) are often rather inconsistent
+so you still need to know what you're looking for. The more explicit you are, the
+less change of problems.
+
+\stopsection
+
+\startsection[title=Spec]
+
+There is often some logic in naming fonts but it's not robust and really depends on
+how consistent a font designer or typefoundry has been. In \CONTEXT\ we can
+access names by using a normalized scheme.
+
+\starttyping
+name-weight-style-width-variant
+\stoptyping
+
+The following values are valid:
+
+\starttabulate[|Bl|Tp|]
+\NC weight \NC \ctxcommand { concatcommalist { list = fonts.names.knownweights } } \NC \NR
+\NC style \NC \ctxcommand { concatcommalist { list = fonts.names.knownstyles } } \NC \NR
+\NC width \NC \ctxcommand { concatcommalist { list = fonts.names.knownwidths } } \NC \NR
+\NC variant \NC \ctxcommand { concatcommalist { list = fonts.names.knownvariants } } \NC \NR
+\stoptabulate
+
+The four specifiers are optional but the more you provide, the better the match. Let's
+give an example:
+
+\starttyping
+mtxrun --script fonts --list --spec dejavu
+\stoptyping
+
+This reports:
+
+\startnarrowtyping
+dejavuserifcondensed normal normal normal normal dejavuserifcondensed dejavuserifcondensed.ttf
+dejavuserif normal normal normal normal dejavuserif dejavuserif.ttf
+dejavusansmono normal normal normal normal dejavusansmono dejavusansmono.ttf
+dejavusanscondensed normal normal normal normal dejavusanscondensed dejavusanscondensed.ttf
+dejavusans normal normal normal normal dejavusans dejavusans.ttf
+\stopnarrowtyping
+
+We can be more specific, for instance:
+
+\starttyping
+mtxrun --script fonts --list --spec dejavu-bold
+\stoptyping
+
+\startnarrowtyping
+dejavuserif bold normal normal normal dejavuserifbold dejavuserif-bold.ttf
+dejavusansmono bold normal normal normal dejavusansmonobold dejavusansmono-bold.ttf
+dejavusans bold normal normal normal dejavusansbold dejavusans-bold.ttf
+\stopnarrowtyping
+
+We add another specifier:
+
+\starttyping
+mtxrun --script fonts --list --spec dejavu-bold-italic
+\stoptyping
+
+\startnarrowtyping
+dejavuserif bold italic normal normal dejavuserifbolditalic dejavuserif-bolditalic.ttf
+dejavusansmono bold italic normal normal dejavusansmonoboldoblique dejavusansmono-boldoblique.ttf
+dejavusans bold italic normal normal dejavusansboldoblique dejavusans-boldoblique.ttf
+\stopnarrowtyping
+
+As the first hit is used we need to be more specific with respect to the
+name, so lets do that in an example definition:
+
+\starttyping
+\definefont[TitleFont][spec:dejavuserif-bold-italic*default sa 1]
+\stoptyping
+
+Watch the prefix \type {spec}. Wolfgang Schusters \type {simplefonts} module
+nowadays uses this method to define sets of fonts based on a name only
+specification. Of course that works best if a fontset has well defined
+properties.
+
+\stopsection
+
+\startsection[title=Selectfont]
+
+The selectfont interface by Wolfgang Schuster can be used to define fonts
+by name. For a long term project workflow you probably want to use filenames
+but for average use names do well:
+
+\starttyping
+\definefontfamily [mainface] [serif] [DejaVu Serif]
+\definefontfamily [mainface] [sans] [DejaVu Sans]
+\definefontfamily [mainface] [mono] [DejaVu Sans Mono] [features=none]
+\definefontfamily [mainface] [math] [Dejavu Math]
+\stoptyping
+
+This setup is triggered in the usual way:
+
+\starttyping
+\setupbodyfont[mainface]
+\stoptyping
+
+When you combine different designs you may need to apply a relative scale:
+
+\starttyping
+\definefontfamily [mainface] [math] [XITS Math] [rscale=1.1]
+\stoptyping
+
+Some fonts come in designsizes, like Latin Modern:
+
+\starttyping
+\definefontfamily
+ [mainface]
+ [serif]
+ [Latin Modern Roman]
+ [designsize=auto]
+\stoptyping
+
+You can define fallbacks, for example:
+
+\starttyping
+\definefallbackfamily
+ [mainface]
+ [serif]
+ [DejaVu Serif]
+ [range=cyrillic]
+
+\definefontfamily [mainface] [serif] [TeX Gyre Pagella]
+\stoptyping
+
+Here Pagella is used with missing characters taken from Dejavu. The ranges
+are defined with:
+
+\starttyping
+\definefontfamilypreset
+ [range:cyrillic]
+ [range={cyrillic,
+ cyrillicextendeda,
+ cyrillicextendedb,
+ cyrillicsupplement}]
+\stoptyping
+
+For more details you can consult the wiki and the source file \type {font-sel.mkvi}.
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-math.tex b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-math.tex
new file mode 100644
index 00000000000..76620493755
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-math.tex
@@ -0,0 +1,1093 @@
+% language=uk
+
+% todo:
+
+% \starttext
+% \setupbodyfont[cambria]
+% \setupmathematics[kernpairs=yes]
+% $abcd$ % 𝑎𝑏
+% \stoptext
+%
+% kernpairs = {
+% [0x1D44E] = {
+% [0x1D44F] = 1000, -- 𝑎𝑏 demo
+% }
+% },
+
+\startcomponent fonts-math
+
+\environment fonts-environment
+
+\startchapter[title=Math][color=darkmix-3]
+
+\startsection[title=Introduction]
+
+As one can expect, math support in \CONTEXT\ is to some extend modelled after
+what plain \TEX\ provides, plus what was later decided to be standard. This
+mostly concerns the way fonts behave and what names are used to access glyphs or
+special constructs. It means that when you come from another macro package you
+can stick to coding math the way you did before, at least the basic coding. In
+addition to this, \CONTEXT\ gives control over fonts, structure and rendering and
+most of that was either driven by personal need or user demand. To be honest,
+many of the options are probably of not much interest to the average user.
+
+As we focus on fonts we will only touch this aspect of math here. Right from when
+we started with developing \LUATEX, cleaning op the math part of \CONTEXT\ was
+part of the game. Some primitives were added that would make it possible to avoid
+unnecessary complex macros to get certain glyphs rendered, like radicals, accents
+and extensibles. This was made easy because we also support \OPENTYPE\ math and
+because we knew that eventually the Latin Modern and Gyre fonts would also
+support \OPENTYPE. In order to move forward and get rid of traditional eight bit
+fonts \CONTEXT\ \MKIV\ can construct a virtual \OPENTYPE\ font from traditional
+math fonts. It makes not much sense to discuss that here as by now this method is
+only provided for reasons of compatibility and a reference to the past. As a lot
+of time went into this it will always stay around if only to remind us of what
+we went through to get where we are now.
+
+\stopsection
+
+\startsection[title=\UNICODE\ math]
+
+Due to the limited amount of glyphs in a \TYPEONE\ font a macro package has to
+jump through loops in order to get traditional \TEX\ engines behave well. As a
+practical consequence these fonts are often a mixture of characters, symbols,
+punctuation and snippets that make up larger shapes. The font dimensions in these
+files have often special meanings too.
+
+This has all changed considerably with math being part of \UNICODE. It was however
+\MICROSOFT\ where the real action took place: the development of the first font that
+combined \UNICODE\ with \OPENTYPE\ technology. The Cambria font can be considered
+the benchmark for fonts that surfaced later. The characteristic of a math font are
+the following:
+
+\startitemize[packed]
+ \startitem All math alphabets are present: latin as well as greek, in regular,
+ italic, bold, fraktur and script variants as well as some combinations of these. \stopitem
+ \startitem The symbols that make sense are present (read: the more obscure shapes
+ can be omited). \stopitem
+ \startitem For the characters that make sense, there are two variants that render well
+ at smaller sizes: script and scriptscript. In the font they have the same size but
+ the application will scale them down. This feature is named \type {ssty}. \stopitem
+ \startitem Characters that can extend horizontally (for instance accents and arrows) or vertically
+ (like radicals and fences) have associated larger variants and carries information about
+ how to grow indefinitely. \stopitem
+ \startitem There is a whole lot of special math dimensions. Most of the ones
+ already used in \TEX\ are present. \stopitem
+ \startitem Some glyphs come in variants in order to please special usage. There
+ can also be variants for script or fraktur alphabets. \stopitem
+\stopitemize
+
+This means that in practice an \OPENTYPE\ math font is quite large. We easily
+have thousands of glyphs. It also means that creating such a font involves some
+expertise and this is one of the reasons why \TEX\ usergroups have joined forces
+in developing a suite of fonts. There are also other initiatives in the \TEX\
+community, of which Xits is an example. \footnote {This is a useable
+variant of Stix fonts with proper math features, some extra glyphs and
+experimental right||to||left shapes.} The well known Lucida Bright math font
+package has also been upgraded to a set of \OPENTYPE\ math fonts.
+
+The fact that there are not that many math fonts out there has a positive side as
+well: \CONTEXT\ comes with them pre|-|configured. Because during the development
+of \LUATEX\ we needed to have at least a couple of fonts for testing, and because
+it makes no sense to waste time on traditional fonts, the Latin Modern, Palatino,
+Times and a few more fonts were (and still are) provided as virtual \UNICODE\
+fonts.
+
+In a regular text font, what you key in is what you get out. So, when you've
+chosen a font with an italic shape, you get italic shapes, even if the smallcaps
+feature is enabled. In math, if you use the right unicodes you also get the shape
+you expect. Because in this case italic shapes are situated in one of the
+alphabets you explicitly choose a rendering. You can enter the right codepoints
+directly, so for instance if you enter \UNICODE\ character \type {U+1D434} you
+will get \mathematics {\utfchar {"1D434}}. In practice something like \type {$\bi
+A$} should also give that character if only because that is what we have been
+doing for over three decades. This means that the engine has to map a regular
+\type {A} onto the bold italic alphabet. In a traditional approach you will use
+math families for this, but in \CONTEXT\ \MKIV\ we simply use one font and one
+family and let the \MKIV\ machinery do the rest.
+
+In text mode we switch fonts styles in the following way:
+
+\startbuffer
+regular {\it italic} {\bf bold} {\bi bold italic} and so on
+\stopbuffer
+
+\typebuffer
+
+The three commands shown here are shortcuts for font switches. This input is
+converted into an internal representation and after whatever manipulations
+are applied end up as:
+
+\blank \getbuffer \blank
+
+If we look at what fonts we end up with we get:
+
+\blank \markfonts{\getbuffer} \blank
+
+Now lets do the same in math mode:
+
+\startbuffer
+$regular {\it italic} {\bf bold} {\bi bold italic} and so on$
+\stopbuffer
+
+\typebuffer
+
+This time we get a different result:
+
+\blank \getbuffer \blank
+
+If again we analyze the fonts you see this:
+
+\blank \markfonts{\getbuffer} \blank
+
+All glyphs come from the same font. Instead of regular we get italic simply because
+math characters are italic by nature. The two character style switches are not
+really font switches but just make sure that the given input is mapped onto the
+right alphabet.
+
+A traditional approach using \TYPEONE\ fonts is to use a so called math family for
+each alphabet. In that case each alphabet maps one||to||one onto the font: when
+we switch to a bold family we just take the glyph that sits in that slot. In \MKIV\
+we have all characters in one family so behind the screens a given character is
+remapped.
+
+Now take a look at the following example:
+
+\startbuffer
+$text^{script^{scriptscript}}$
+\stopbuffer
+
+\typebuffer
+
+This renders to this, with the characters marked by font:
+
+\blank \markfonts{\getbuffer} \blank
+
+This time we have three different fonts: one for each of the three math sizes.
+But this representation is not entirely honest, because indeed we have three font
+instances for math, but the glyphs come from the same \OPENTYPE\ math font. We
+just load the same font three times, once for each size. In fact we load the
+font once, but use three copies, scaled accordingly to the relative scale the
+font prescribes.
+
+There is a whole bunch of commands to choose specific characters in math mode
+using a regular input. These are state switching commands.
+
+\def\SampleLine#1#2#3%
+ {\NC \type{#1}\space
+ \ifx#2\empty\else\type{#2}\fi\space
+ \ifx#3\empty\else\type{#3}\fi
+ \NC $#1 a$
+ \NC $#1 A$
+ \NC \NR}
+
+\starttabulate[|||||]
+\HL
+\SampleLine \mr \empty \empty
+\HL
+\SampleLine \mathdefault \empty \empty
+\SampleLine \mathscript \empty \empty
+\SampleLine \mathfraktur \empty \empty
+\SampleLine \mathblackboard\empty \empty
+\HL
+\SampleLine \rm \mathrm \empty
+\SampleLine \ss \mathss \empty
+\SampleLine \tt \mathtt \empty
+\HL
+\SampleLine \tf \mathtf \tfmath
+\SampleLine \sl \mathsl \slmath
+\SampleLine \it \mathit \itmath
+\HL
+\SampleLine \bf \mathbf \bfmath
+\SampleLine \bs \mathbs \bsmath
+\SampleLine \bi \mathbi \bimath
+\HL
+\stoptabulate
+
+As you can see here, some commands have synonyms. The short commands adapt
+themselves to text and mathmode, the longer ones are meant for use in math mode
+only.
+
+In text mode distinctive shapes are either a font property (the whole font looks
+that way) or a stylistic alternate (an extra feature of a font). In math mode we
+can have alternates, but in addition to the previously mentioned alphabet
+switchers we have a few more:
+
+\starttabulate[|||||]
+\HL
+\SampleLine \frak \empty \empty
+\SampleLine \cal \empty \empty
+\SampleLine \bbd \empty \empty
+\SampleLine \blackboard \empty \empty
+\SampleLine \fraktur \empty \empty
+\SampleLine \gothic \empty \empty
+\HL
+\stoptabulate
+
+This chapter is not meant as an introduction to math but it is good to know
+that math font support in \CONTEXT\ is rather flexible. There are several
+mechanisms for remapping and converting characters and sequences into
+others and more is possible. Here is one:
+
+\startbuffer
+\startformula
+\reals {\mathbf R} \utfchar{"0211D} \utfchar{"1D411}
+\stopformula
+\stopbuffer
+
+\typebuffer \blank \getbuffer \blank
+
+Compare this to:
+
+\startbuffer
+\setupmathematics[symbolset=blackboard-to-bold]
+\startformula
+\reals {\mathbf R} \utfchar{"0211D} \utfchar{"1D411}
+\stopformula
+\stopbuffer
+
+\typebuffer \blank \start \getbuffer \stop \blank
+
+Greek is always troublesome because instead of regular text shapes math uses a
+few variants. Because in \UNICODE\ characters are only included once, we have
+gaps in the math alphabets but \MKIV\ will take care of this. \footnote {This is
+a typical example of where exceptions in a standard force all applications that
+deal with it have to implement tweaks.} Depending on the field an author has to
+choose between upright and italic greek:
+
+\startbuffer
+$\nabla \alpha \mathgreekupright \nabla \alpha \mathgreekitalic \nabla \alpha$
+\stopbuffer
+
+\typebuffer \blank \start \getbuffer \stop \blank
+
+By default \CONTEXT\ is set up as follows:
+
+\starttyping
+\setupmathematics
+ [sygreek=normal,
+ lcgreek=italic,
+ ucgreek=normal]
+\stoptyping
+
+Again, these are not features of a font. The font just provides the glyphs and
+the \TEX\ engine, controlled by \CONTEXT\ takes care of mapping characters to
+glyphs and building special constructs. The same is true for spacing. Although
+math fonts do have kerning information, most of the math spacing is controlled
+by properties of characters and not by the font.
+
+\unexpanded\def\SampleLine#1%
+ {\NC
+ \type{$a #1{+} b$}
+ \NC
+ \ruledhbox{$\mathsurround\zeropoint a#1{+}b$}
+ \NC \NR}
+
+\starttabulate[|||]
+\SampleLine \mathord
+\SampleLine \mathpunct
+\SampleLine \mathinner
+\SampleLine \mathop
+\SampleLine \mathalpha
+\SampleLine \mathnothing
+\SampleLine \mathbin
+\SampleLine \mathrel
+\stoptabulate
+
+As a user you don't have to worry about these issues because characters are tagged
+according to their usage. \footnote {There are a few more commands, like \type
+{\mathlimop}, \type {\mathnolop} and \type {mathbox} but these are used
+differently.}
+
+With \TEX\ being the oldest and still dominant math renderer it is no surprise
+that \MICROSOFT\ modelled its math renderer after \TEX\ and Cambria quite well
+suits the concept. In retrospect it is somewhat unfortunate that we're still
+stuck with some left overs (or compromises) from the past with respect to spacing
+built into the font. However, as long as this is consistent over fonts it's not
+that relevant. You can always influence the spacing with the commands mentioned.
+
+If you look at the low level definitions in for instance plain \TEX\ but also in
+\CONTEXT\ \MKII\ that relate to prime symbols it probably takes a while before you
+figure out what happens there. For instance, the prime symbol is triggered by a
+quote and multiple in a row results in primes that are spaced tightly. In
+\UNICODE\ we have slots for single, double and tripple primes. Therefore, in
+\MKIV\ we have a mechanism that accepts different kinds of input that eventually
+all end up in one of these three glyphs.
+
+\unexpanded\def\SampleLine#1%
+ {\NC \type{#1} \NC #1 \NC \NR}
+
+\starttabulate[|||]
+\SampleLine{$f^2$}
+\SampleLine{$f\prime^2$}
+\SampleLine{$f\prime\prime^2$}
+\SampleLine{$f\prime\prime\prime^2$}
+\SampleLine{$f{\prime}^2$}
+\SampleLine{$f{\prime\prime}^2$}
+\SampleLine{$f{\prime\prime\prime}^2$}
+\SampleLine{$f'(x)$}
+\SampleLine{$f''(x)$}
+\SampleLine{$f'''(x)$}
+\SampleLine{$f\utfchar{0x2032}(x)$}
+\SampleLine{$f\utfchar{0x2033}(x)$}
+\SampleLine{$f\utfchar{0x2034}(x)$}
+\SampleLine{$f\utfchar{0x2032}\utfchar{0x2032}(x)$}
+\SampleLine{$f\utfchar{0x2032}\utfchar{0x2032}\utfchar{0x2032}(x)$}
+\SampleLine{$f\utfchar{0x2033}\utfchar{0x2032}(x)$}
+\SampleLine{$f\utfchar{0x2032}\utfchar{0x2033}(x)$}
+\stoptabulate
+
+Again, this is not the same as ligature building features in text fonts, but
+handled in a different way.
+
+The \TEX\ engine understands the concept of italic correction. When an italic
+shape is followed by for instance an upright shape, you can insert a \type {\/}
+and the engine will add a correction as defined in the font. In \OPENTYPE\ we
+don't have such corrections available but we can fake it, which is what the \type
+{itlc} feature in \CONTEXT\ does. However, you need to enable this feature
+explicitly. An example of a setup is:
+
+\starttyping
+\definefontfeature
+ [default]
+ [default]
+ [itlc=yes,textitalics=yes]
+
+\setupitaliccorrection
+ [global,always]
+\stoptyping
+
+This will make sure that the right amount of correction is added between
+italic shapes and non italics or boxes. Using \type {text} instead of
+\type {always} would limit the correction to glyphs only and leaving out
+the \type {global} would permit selective (grouped) usage at the cost
+of more runtime. There is no need for the \type {\/} here.
+
+In math we also can have italic correction but there it is built into the engine
+and in traditional \TEX\ no directives are needed. Italic correction properties
+in math fonts are somewhat troublesome as their application depends on what we're
+dealing with: symbols, super- and subscripts, etc. Because early versions of
+\LUATEX\ didn't handle all of it well, if only because the fonts were not yet okay,
+the \MKIV\ math handler provides a bit of control.
+
+\def\SampleLine#1#2%
+ {\NC #1
+ \NC \setupmathematics[italics=#1]\ruledhbox{$m$ t}
+ \NC \setupmathematics[italics=#1]\ruledhbox{$m$ {\it t}}
+ \NC \setupmathematics[italics=#1]\ruledhbox{t $m$ t $m$ {\it t}}
+ \NC #2
+ \NC \NR}
+
+\starttabulate[||||||]
+\SampleLine0{no correction}
+\SampleLine1{only apply italics when the font carries them}
+\SampleLine2{apply italics provided by the font or automatically calculated}
+\SampleLine3{apply italics based on an emwidth and character properties}
+\SampleLine4{use method 1 but fall back on 3 if needed}
+\stoptabulate
+
+Because we cannot rely on fonts too much, we default to method~3 which in practice
+works out well, so the setup is:
+
+\starttyping
+\setupmathematics
+ [italics=3]
+\stoptyping
+
+There are all kind of commands that can be used to build math constructs in such a
+way that super- and subscripts are consistently rendered. It goes beyond this
+chapter to discuss them and most users will never see or use those commands. The
+main message of the examples above is that text and math use different fonts and
+properties and therefore also different methods in rendering text or a formula.
+Even if the names of mechanisms are the same (like italics) you cannot assume
+that both modes do exactly the same.
+
+\stopsection
+
+\startsection[title=Bold math]
+
+If you look at what \UNICODE\ provides you will notice that there are quite some
+bold characters. First of all there are a bunch of alphabets and because bold is
+not present in the text part of \UNICODE\ these alphabets have no holes. Then
+there are some symbols that have special meaning.
+
+\startluacode
+local find = string.find
+local NC, NR = context.NC, context.NR
+
+context.starttabulate { "|Tl||l|" }
+for unicode, entry in table.sortedhash(characters.data) do
+ local description = entry.description
+ if find(description,"^MATHEMATICAL BOLD") then
+ NC() context("U+04X",unicode)
+ NC() context.mathematics(utf.char(unicode))
+ NC() context(description)
+ NC() NR()
+ end
+end
+context.stoptabulate()
+\stopluacode
+
+The biggest mistake one can make when discussing bold math is the assumption that
+these bold alphabets are meant for section titles and other structural elements
+that need some emphasis. This is not true, in that case we would expect the whole
+formula to be bold and the bold symbols or variables would be even more bold.
+Bold math boils down to {\em all} math being bold. The reason why we show the
+list of bold characters on the previous pages is that it gives a good impression of
+fact that we're mostly given alphabets in an otherwise regular font.
+
+As Latin Modern (being derived from Computer Modern) has some bold extras in
+\MKII\ to some extend we do support a complete bold math switch but mixing bold
+formulas with regular ones has some limitations. Math typesetting consists of two
+phases: first the input is translated into a special list where references to
+fonts are not yet resolved. Instead families are used and each family has three
+sizes: text, script and scriptscript. In a second pass the formula is typeset and
+the families get translated into fonts. So, if we change the definition of a
+family, say math italic into bold math italic, then the definition that is actual
+when the second pass takes place is used.
+
+Although \LUATEX\ provides for many more families and as a consequence we could
+have replaced the \MKII\ mechanism with a more complete one, instead we just
+forgot about it and stuck to one family for regular math and another one for bold
+math. Okay, this is not entirely true as later on we added some more in order to
+deal with bidirectional typesetting.
+
+Only a few math fonts come with a bold variant. One of the objectives of the \TEX
+Gyre math font project is to explore the possibilities of bold math companions,
+but such a font will probably have less coverage, simply because no real complex
+math will end up in for instance section titles.
+
+When I wrote this down there were not that many math fonts that come with a real
+(complete) bold variant. The \CONTEXT\ math font subsystem tries to fill this gap
+as good as possible by using pseudo fonts. When a typeface doesn't define a math
+bold variant a pseudo setup is used. When a real bold font is used, it could be
+that not all alphabets are supported in which case a suitable alternative is
+tried.
+
+The Xits font, assembed from Stix and enhanced by Khaled Hosny, comes with a bold
+variant but the coverage is not complete, at least not when I wrote this
+paragraph. This can go unnoticed because \CONTEXT\ tries to work around this. On
+the other hand, it definitely has bold properties, which can be seen from the
+next example. You switch between regular and bold math with the \type {\mr} and
+\type {\mb} commands.
+
+\startbuffer
+\switchtobodyfont[xitsbidi]
+
+$ \sqrt{x } \quad
+ \mb \sqrt{mb} \quad
+ \mathupright \sqrt{u } \quad
+ \mr \sqrt{mr} \quad
+ \mathupright \sqrt{u } \quad
+ \mathdefault \sqrt{d }
+$
+\stopbuffer
+
+\typebuffer \blank \start \getbuffer \stop \blank
+
+You can track some of what happens with:
+
+\starttyping
+\enabletrackers[math.remapping,math.families]
+\stoptyping
+
+You will get some information about remapping or when it fails if fallback
+remapping is used. But no matter what happens with glyphs, you will notice in
+this example that the radical symbol is bold indeed.
+
+\stopsection
+
+\startsection[title=Bidirectional math]
+
+There is not that much to tell about bidirectional math typesetting, simply
+because the fonts are still in development. However, Khaled Hosny added
+some support to the Xits font. Of course you need to load this font first:
+
+\starttyping
+\switchtobodyfont[xitsbidi]
+\stoptyping
+
+In the previous chapter we mentioned bold math and as Xits also comes with
+a bold variant which means that this command loads the whole lot (which is
+fast enough anyway).
+
+Easiest is to just show a few examples. When in left to right mode we get what we
+are accustomed to:
+
+\startbuffer
+\setupmathematics[align=l2r]
+
+\startformula
+\sqrt{x^2\over 4x} \eqno(1)
+\stopformula
+
+\startformula
+5 < 6 > 4
+\stopformula
+
+\startformula
+5 \leq 6 \geq 7
+\stopformula
+\stopbuffer
+
+\typebuffer \start \switchtobodyfont[xitsbidi] \getbuffer \stop
+
+However, when we go the other way, we automatically get digits converted to
+arabic.
+
+\startbuffer
+\setupmathematics[align=r2l,bidi=yes]
+
+\startformula
+\sqrt{ف^2\over 4ب} \eqno(1)
+\stopformula
+
+\startformula
+5 < 6 > 4
+\stopformula
+
+\startformula
+5 \leq 6 \geq 7
+\stopformula
+\stopbuffer
+
+\typebuffer \start \switchtobodyfont[xitsbidi] \getbuffer \stop
+
+You don't have to worry about how the font is set up, but not that much is needed
+because \CONTEXT\ does it for you and the Xits typescripts carries the right
+definitions. Just to give you an idea, we show a feature definition: The magic is
+in the \type {rtlm} feature combined with \type {locl}.
+
+\starttyping
+\definefontfeature
+ [mathematics-r2l]
+ [mathematics]
+ [language=ara,
+ rtlm=yes,
+ locl=yes]
+\stoptyping
+
+Some symbols are mirrored too:
+
+\startbuffer
+\setupmathematics[align=r2l,bidi=yes]
+
+\startformula
+\sum^\infty_{س=0} س^2 \eqno(2)
+\stopformula
+\stopbuffer
+
+\typebuffer \start \switchtobodyfont[xitsbidi] \getbuffer \stop
+
+And of course the extensible fences are done properly too:
+
+\startbuffer
+\setupmathematics[align=r2l,bidi=yes]
+
+\startformula
+\left(\root{2} \of{155}\right)
+\stopformula
+
+\startformula
+\left[\int^{55}_{123} 666^3\right]
+\qquad\textstyle\left[\int^{55}_{123} 666^3\right]
+\stopformula
+
+\startformula
+\left\{\sum^{55}_{123} 666^3\right\}
+\stopformula
+\stopbuffer
+
+\typebuffer \start \switchtobodyfont[xitsbidi] \getbuffer \stop
+
+The real torture test is the radical sign. A mirrored shape is used
+and it grows upwards as well as leftwards.
+
+\startbuffer
+\setupmathematics[align=r2l,bidi=yes]
+
+\startformula
+\sqrt{\sqrt{\sqrt{\sqrt{\sqrt{\sqrt{\sqrt{\sqrt{\sqrt{\sqrt{55}}}}}}}}}}
+\stopformula
+\stopbuffer
+
+\typebuffer \start \switchtobodyfont[xitsbidi] \getbuffer \stop
+
+\stopsection
+
+\startsection[title=Styles]
+
+In text mode you use font switches like \type {\sl} that switches the current font
+to a slanted one. In math mode it is an alphabet switch in the same font. In
+fact, there isn't much to choose from fonts there, apart from a massive switch
+to bold, in which case \type {\bf} is just a bolder alphabet in that bolder font.
+
+A lot of things in math mode happen automatically. There are for instance always
+three instances of (the same) font active, each different in size: text, script
+and the smallest, scriptscript and when you ask for instance for a superscript
+the next smaller size is used.
+
+\starttabulate[|l|l|l|]
+\NC normal \NC \type {\textstyle} \NC $\textstyle text^{script^{scriptscript}}$ \NC \NR
+\NC smaller \NC \type {\scriptstyle} \NC $\scriptstyle text^{script^{scriptscript}}$ \NC \NR
+\NC smallest \NC \type {\scriptscriptstyle} \NC $\scriptscriptstyle text^{script^{scriptscript}}$ \NC \NR
+\stoptabulate
+
+In text style, superscripts can go twice smaller, but in script style only one
+smaller size is left, and in scriptscript style you're stuck with one size. The
+commands in the second column can be used to force a style.
+
+The math formula builder has an important property: the formula is typeset after
+it has been scanned completely. In a traditional setup that has some
+consequences. Take this:
+
+\starttyping
+one \sl two \bf three \bi four
+\stoptyping
+
+In a traditional setup four so called families are used and each character gets
+tagged with a family number. So we have (for instance):
+
+\blank \start \tttf
+o\low7n\low7e\low7 t\low6w\low6o\low6 t\low5h\low5r\low5e\low5e\low5 f\low9o\low9u\low9r\low9
+\stop \blank
+
+As the number of families was limited there could be at most 16 families. In
+fact, the first four were traditionally reserved for math roman, math italic,
+symbol and extensibles. Then, due to the limit of 256 characters per font,
+another few were used for additional symbol fonts. So, adding a few more variants
+could exhaust the family pool quite fast. You could argue that we could halfway
+redefine a family but this will not work as there is a one to one relationship
+between family numbers and fonts assigned to them when the formula has been
+read in (the last value counts). And grouping won't help you either.
+
+The actual (plain) situation is even more complex. As we have a limited number of
+characters per font, most symbols are accessed by name, and the name relates to a
+mathematical character definition using for instance \type {\mathchardef}. Such a
+definition refers to a slot in a specific family number and therefore font. It
+also puts a character in a so called math class. One of these, the alphanumeric
+class, with number~7, is special. Characters that are input directly on the
+keyboard (like \type {a}||\type {z} can also be tagged this way using \type
+{\mathcode}.
+
+When we switch a family, this will normally not affect a symbol defined as math
+character, simply because we refer to a specific family|/|slot combination, but
+when a character has class~7, then it will be taken from the current family. This
+permits latin letters, digits and greek letters to be typeset in different
+styles. So, in that traditional approach we have fonts that provide a bunch of
+symbols as well as some alphabets. Think for instance of a font with additional
+symbols where the regular alphabet slots contain blackboard shapes. The symbols
+are accessed directly and the characters are accessed via the regular \type
+{a}||\type {z} characters as these will adapt to the family and therefore font.
+In practice users will not notice this complication as macro packages hide the
+implementation details.
+
+In \MKIV\ the situation is different as there we have one family (or a few more
+if we use a full bold switch and|/|or bidirectional math). Although we no longer
+have the limit of 16 fonts we actually don't need that many families, at least
+not in the way we've set up \MKIV \footnote{A technical note: in principle the
+\MKIV\ approach can have a speed penalty compared to a multi||family approach but
+we don't care too much about it. Also, as we load less fonts the extra overhead gets
+compensated nicely.}
+
+\blank \start \tttf
+o\low1n\low1e\low1 t\low1w\low1o\low1 t\low1h\low1r\low1e\low1e\low1 f\low1o\low1u\low1r\low1
+\stop \blank
+
+So how does this relate to styles? Each family has three fonts and we can use the
+switch commands to choose any of these. In text mode we use the term style for a
+font switch, while in math mode it's more than that: indeed we switch a font, but
+only in size, but the spacing is also adapted. If a proper math font is used, the
+smaller sizes are actually alternates in the font, visually adapted to suit their
+use.
+
+In text mode we do this in order to limit the scope of a switch:
+
+\starttyping
+normal {\bf bold {\it italic} bold} normalbracket
+\stoptyping
+
+This is the same as:
+
+\starttyping
+normal \bgroup \bf bold \bgroup \it italic\egroup
+ \ bold\egroup \ normalbracket
+\stoptyping
+
+and:
+
+\starttyping
+normal \begingroup \bf bold \begingroup \it italic\endgroup
+ \ bold\endgroup \ normalbracket
+\stoptyping
+
+The \CONTEXT\ distribution ships with a plain math definition file that also uses
+one family but reassigns some math codes when we switch to another style. As the
+number of characters that this applies to this is efficient enough for a modern
+computer. A peek into \type {luatex-math.tex} gives an impression of what we deal
+with. However, keep in mind that the implementation in \MKIV\ goes it differently
+and is therefore more powerful. We also have hardly any definitions at the \TEX\
+end and use information from \type {char-def.lua} instead.
+
+In math mode there is a subtle difference in the way grouping works with styles:
+
+\starttyping
+text {\scriptstyle script} normal
+\stoptyping
+
+This is the same as:
+
+\starttyping
+text \bgroup\scriptstyle script\egroup\ normal
+\stoptyping
+
+but different from:
+
+\starttyping
+text \begingroup\scriptstyle script\endgroup\ script
+\stoptyping
+
+This has to do with the fact that a style switch is explicitly registered in the
+math list and grouping like this is not limiting the scope. In math mode the
+braced grouping mode actually does create a math group and there the scope of the
+switch is limited to that group. In practice users will not run into this but
+they can use macros that use \type {\begingroup}. Among other reasons, this is
+why we have a special mathstyle mechanism.
+
+\startbuffer
+\ruledhbox{$x\begingroup\scriptstyle x\endgroup x$} \quad
+\ruledhbox{$x\begingroup\setupmathstyle[script]x\endgroup x$} \quad
+\ruledhbox{$x{\setupmathstyle[script]x}x$} \quad
+\ruledhbox{$x\startmathstyle[script]x\stopmathstyle x$}
+\stopbuffer
+
+\typebuffer
+
+This gives:
+
+\startlinecorrection[blank] \dontleavehmode \getbuffer \stoplinecorrection
+
+Mechanisms that support the \type {mathstyle} parameter know how to apply the
+proper grouping so you don't have to worry there. You can best avoid using the
+verbose grouping command and stick to braces or the \type {start}||\type {stop}
+command. An example is the fence mechanism:
+
+\startbuffer
+\definemathfence
+ [fancybracket] [bracket]
+ [color=darkblue]
+\definemathfence
+ [smallbracket] [bracket]
+ [command=yes,color=darkgreen,mathstyle=small]
+\definemathfence
+ [normalbracket] [bracket]
+ [command=yes,color=darkred]
+\stopbuffer
+
+\typebuffer \getbuffer
+
+We apply this to an example:
+
+\startbuffer
+$x \fenced[bar]{\frac{1}{x}} x$ \quad
+$x \fenced[doublebar]{\frac{1}{x}} x$ \quad
+$x \fenced[bracket]{\frac{1}{x}} x$ \quad
+$x \fenced[fancybracket]{\frac{1}{x}} x$ \quad
+$x \frac{1}{n} \normalbracket{\frac{1}{n}} \smallbracket{\frac{1}{s}} x$
+\stopbuffer
+
+\typebuffer
+
+Of course these somewhat weird examples are not real but at least they
+demonstrate the principles.
+
+\startlinecorrection[blank] \dontleavehmode \getbuffer \stoplinecorrection
+
+A math style is a combination of the following keys. Their effect can depend on
+the current state, for instance you can switch cramp or size indepently.
+
+\starttabulate[|T||]
+\NC display \NC display style, like text style but somewhat more spacy \NC \NR
+\NC text \NC text style, normally used inline \NC \NR
+\NC script \NC smaller than text cq. display style \NC \NR
+\NC scriptscript \NC smaller than script style \NC \NR
+\NC cramped packed \NC more tightly positioned superscripts \NC \NR
+\NC uncramped normal \NC normal positioned superscripts \NC \NR
+\NC small \NC switch to the next smaller style but keep cramp state \NC \NR
+\NC big \NC switch to the next larger style but keep cramp state \NC \NR
+\stoptabulate
+
+Future versions of \MKIV\ will provide more features (like parameter sets driven
+by keywords). As you might prefer a more symbolic approach we provide:
+
+\starttyping
+\definemathstyle[default][text,cramped]
+\stoptyping
+
+After this you can use the keyword \type {default} which has the advantage that
+you only need to change one definition in order to get different rendering.
+
+\stopsection
+
+\startsection[title=Supported fonts]
+
+As in \CONTEXT\ MKIV\ I wanted to go ahead with \UNICODE\ math as soon as the
+first version of \LUATEX\ showed up. Because at that time only Cambria was
+available I decided to provide virtual \UNICODE\ math fonts as a prelude to
+proper replacements for the popular \TYPEONE\ math fonts. In the meantime Xits
+came around and in 2012 we had quite useable math companions for the public Latin
+Modern, Pagella and Termes fonts and the \TEX\ user groups started shipping
+\OPENTYPE\ variants of Lucida. The virtual variants will still around so that we
+can compare them with the new implementations. As the official specification of
+\OPENTYPE\ math is not always clear from the beginning the \OPENTYPE\ fonts get
+improved over time. In fact, this is true not only for math fonts. Just think of
+this:
+
+\startitemize
+
+\startitem As \UNICODE\ gets extended, fonts might get more glyphs and possibly
+alternate shapes. \stopitem
+
+\startitem The more languages are supported, the more glyphs are to be available
+and features have to get language dependent instances. \stopitem
+
+\startitem The larger the font, the bigger the chance that mistakes get unnoticed
+especially when contextual subtitutions and positioning are used. \stopitem
+
+\startitem Math fonts can get more script and scriptscript alternates, more size
+variants, more advanced extensibles, bidirectional support, etc. \stopitem
+
+\stopitemize
+
+So, like regular programs, \LUATEX\ and macro packages, we now have fonts as
+component that needs occasional updating. Of course resources like hyphenation
+patterns are also subjected to this, so it's not a new aspect. But still, best
+keep en eye on font updates.
+
+While there are lots of text fonts, there are not that many math fonts, so you
+can safely assume that \CONTEXT\ ships with the proper setup for those fonts. Of
+course you have to choose a specific instance when you set up your own
+combination of fonts, but a peek into the typescripts shows the way.
+
+In the font manual and on the wiki you can find more about typescript and what is
+possible, so here we just take a look at one definition:
+
+\startnarrowtyping
+\starttypescript [serif] [dejavu] [name]
+ \definefontsynonym [Serif] [name:dejavuserif] [features=default]
+ \definefontsynonym [SerifBold] [name:dejavuserifbold] [features=default]
+ \definefontsynonym [SerifItalic] [name:dejavuserifitalic] [features=default]
+ \definefontsynonym [SerifBoldItalic] [name:dejavuserifbolditalic] [features=default]
+\stoptypescript
+
+\starttypescript [sans] [dejavu] [name]
+ \definefontsynonym [Sans] [name:dejavusans] [features=default]
+ \definefontsynonym [SansBold] [name:dejavusansbold] [features=default]
+ \definefontsynonym [SansItalic] [name:dejavusansoblique] [features=default]
+ \definefontsynonym [SansBoldItalic] [name:dejavusansboldoblique] [features=default]
+\stoptypescript
+
+\starttypescript [mono] [dejavu] [name]
+ \definefontsynonym [Mono] [name:dejavusansmono] [features=none]
+ \definefontsynonym [MonoBold] [name:dejavusansmonobold] [features=none]
+ \definefontsynonym [MonoItalic] [name:dejavusansmonooblique] [features=none]
+ \definefontsynonym [MonoBoldItalic] [name:dejavusansmonoboldoblique] [features=none]
+\stoptypescript
+
+\starttypescript[dejavu]
+ \definetypeface [dejavu] [rm] [serif] [dejavu] [default]
+ \definetypeface [dejavu] [ss] [sans] [dejavu] [default]
+ \definetypeface [dejavu] [tt] [mono] [dejavu] [default]
+ \definetypeface [dejavu] [mm] [math] [xits] [default] [scale=1.2]
+\stoptypescript
+\stopnarrowtyping
+
+So, in many cases you can just copy this blob and replace the font names by your
+own.
+
+Loading a font, and Dejavu is a predefined one, is done as follows:
+
+\starttyping
+\setupbodyfont[dejavu]
+\stoptyping
+
+In a similar fashion you can enable \type {cambria}, \type {pagella}, \type
+{termes}, \type {lucidaot}, etc.\ and if you don't use this command at all, you
+get Latin Modern. These fonts are part of \TEX\ distributions, including
+\CONTEXT\ stand||alone that can be downloaded from \CONTEXT\ garden.
+
+If you want to use Lucida, all you have to do when you have bought the fonts, is
+to put the \OPENTYPE\ files in a place where they can be found, for instance:
+
+\starttyping
+tex/texmf-fonts/fonts/data/lucida
+\stoptyping
+
+Of course you need to run \type {mtxrun --generate} afterwards so that the files
+can be found.
+
+\startnotabene
+ Tracing and characters coverage will be discussed here as soon as the styles
+ that are used for them are normalized.
+\stopnotabene
+
+\stopsection
+
+\startsection[title={Stylistic alternates}]
+
+Some fonts provide stylistic alternates. These can be described in goodies files
+and the Lucida setup is a good example. Here we demonstrate the effects. We
+disable the default math rendering (which takes the italic variants).
+
+\startbuffer[sa:1]
+\switchtobodyfont[lucidaot,14.4pt]
+\setupmathrendering[lucidaot][it=]
+$x
+ ^{i \leftarrow 0 = ∅}
+ _{i \leftarrow 0 = ∅}
+$
+\stopbuffer
+
+\typebuffer[sa:1]
+
+The next code enabled three alternatives:
+
+\startbuffer[sa:2]
+\switchtobodyfont[lucidaot,14.4pt]
+\setupmathrendering[lucidaot][it=]
+$x
+ ^{i \leftarrow 0 = ∅}
+ _{\setmathfontalternate{arrow}
+ \setmathfontalternate{dotless}
+ \setmathfontalternate{zero}
+ i \leftarrow 0 = ∅}
+$
+\stopbuffer
+
+\typebuffer[sa:2]
+
+Here we set them in one go:
+
+\startbuffer[sa:3]
+\switchtobodyfont[lucidaot,14.4pt]
+\setupmathrendering[lucidaot][it=]
+$x
+ ^{i \leftarrow 0 = ∅}
+ _{\setmathfontalternate{arrow,dotless,zero}
+ i \leftarrow 0 = ∅}
+$
+\stopbuffer
+\
+\typebuffer[sa:3]
+
+The last example shows how to enable these features globally:
+
+\startbuffer[sa:4]
+\switchtobodyfont[lucidaot,14.4pt]
+\setupmathrendering[lucidaot][it=]
+\setupmathematics[stylealternative={arrow,dotless,zero}]
+$x
+ ^{i \leftarrow 0 = ∅}
+ _{i \leftarrow 0 = ∅}
+$
+\stopbuffer
+
+\typebuffer[sa:4]
+
+The results are collected here:
+
+\startlinecorrection[blank]
+\startcombination[4*1]
+ {\vbox{\hsize.2\hsize\midaligned{\nospacing\getbuffer[sa:1]}}} {\bf nothing}
+ {\vbox{\hsize.2\hsize\midaligned{\nospacing\getbuffer[sa:2]}}} {\bf stepwise}
+ {\vbox{\hsize.2\hsize\midaligned{\nospacing\getbuffer[sa:3]}}} {\bf combined}
+ {\vbox{\hsize.2\hsize\midaligned{\nospacing\getbuffer[sa:4]}}} {\bf global}
+\stopcombination
+\stoplinecorrection
+
+\stopsection
+
+\startsection[title=Italics and limits]
+
+An \OPENTYPE\ font treats italic correction differently from traditional fonts.
+Officially the italic correction is used for placement above and below limits
+where the scripts shift left and right half of the correction from the center of
+the shape. Advanced kerns are then to be used for anchoring the scripts when they
+are placed at the right side (so far no fonts seem to do this). Because we cannot
+foresee if fonts compensate for correction then we can control placement a bit.
+There is a parameter \type {\mathnolimitsmode} that controls the correction.
+
+\definebodyfontenvironment[20pt]
+
+\startlinecorrection
+\startcombination[5*1]
+ {\ruledhbox to .15\hsize{\hss\showglyphs\switchtobodyfont[20pt]\mathnolimitsmode0$\displaystyle\int\nolimits^0_1$\hss}} {\tttf 0}
+ {\ruledhbox to .15\hsize{\hss\showglyphs\switchtobodyfont[20pt]\mathnolimitsmode1$\displaystyle\int\nolimits^0_1$\hss}} {\tttf 1}
+ {\ruledhbox to .15\hsize{\hss\showglyphs\switchtobodyfont[20pt]\mathnolimitsmode2$\displaystyle\int\nolimits^0_1$\hss}} {\tttf 2}
+ {\ruledhbox to .15\hsize{\hss\showglyphs\switchtobodyfont[20pt]\mathnolimitsmode3$\displaystyle\int\nolimits^0_1$\hss}} {\tttf 3}
+ {\ruledhbox to .15\hsize{\hss\showglyphs\switchtobodyfont[20pt]\mathnolimitsmode4$\displaystyle\int\nolimits^0_1$\hss}} {\tttf 4}
+\stopcombination
+\stoplinecorrection
+
+A value larger than 15 is interpreted as a factor (in the usual \TEX\ way 1000
+means 1.0). We have some values left for future use when correction is to be
+combined with kerns.
+
+In \CONTEXT\ we set the value to 1 which means that the factors for super- and
+subscript are set via math parameters (or constants in the font). We use a
+default of \type {{0,800}} so we don't shift the superscript and the subscript we
+shift less than the italic correction. This is driven by a feature but you can
+change the values before loading a font, for instance with:
+
+\starttyping
+\adaptfontfeature[*math*][mathnolimitsmode={100,700}]
+\stoptyping
+
+The defaults come out as:
+
+\startlinecorrection
+\startcombination[5*1]
+ {\ruledhbox to .15\hsize{\hss\showglyphs\switchtobodyfont[modern, 20pt]$\displaystyle\int\nolimits^0_1$\hss}} {\tttf modern}
+ {\ruledhbox to .15\hsize{\hss\showglyphs\switchtobodyfont[xits, 20pt]$\displaystyle\int\nolimits^0_1$\hss}} {\tttf xits}
+ {\ruledhbox to .15\hsize{\hss\showglyphs\switchtobodyfont[lucidaot,20pt]$\displaystyle\int\nolimits^0_1$\hss}} {\tttf lucidaot}
+ {\ruledhbox to .15\hsize{\hss\showglyphs\switchtobodyfont[pagella, 20pt]$\displaystyle\int\nolimits^0_1$\hss}} {\tttf pagella}
+ {\ruledhbox to .15\hsize{\hss\showglyphs\switchtobodyfont[cambria, 20pt]$\displaystyle\int\nolimits^0_1$\hss}} {\tttf cambria}
+\stopcombination
+\stoplinecorrection
+
+\stopsection
+
+\startsection[title=Kerning]
+
+Math kerns in \OPENTYPE\ are quite advanced and use a staircase model left
+and|/|or right of characters. However, hardly any math font implements them
+(extensively). Therefore we provide a way to fine tune your fonts to your
+preferences. You can test this mechanism by patching \type {cambria-math.lfg} by
+adding this to the mathematics subtable:
+
+\starttyping
+kernpairs = {
+ [0x1D44E] = {
+ [0x1D44F] = 1000, -- 𝑎𝑏 demo
+ }
+}
+\stoptyping
+
+After that, the next example should work:
+
+\starttyping
+\starttext
+ \setupbodyfont[cambria]
+ \setupmathematics[kernpairs=yes]
+ $abcd$
+\stoptext
+\stoptyping
+
+There should be a gap between the $𝑎$ and $𝑏$. It is not shown here because I
+don't want to mess up my goodie file.
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-methods.tex b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-methods.tex
new file mode 100644
index 00000000000..eac86d69487
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-methods.tex
@@ -0,0 +1,376 @@
+% language=uk
+
+\startcomponent fonts-methods
+
+\environment fonts-environment
+
+\startchapter[title=Methods][color=darkyellow]
+
+\startsection[title=Introduction]
+
+A font definition looks as follows:
+
+\starttyping
+\definefont
+ [MyFont]
+ [namepart method specification size]
+\stoptyping
+
+For example:
+
+\starttyping
+\definefont
+ [MyFont]
+ [Bold*default at 12.3pt]
+\stoptyping
+
+We have already discussed the namepart and size in a previous chapter and here
+we will focus on the method. The method is represented by a character and although
+we currently only have a few methods there can be many more.
+
+\stopsection
+
+\startsection[title=: (direct features)]
+
+This one is seldom used, but those coming from another macro package to \CONTEXT\
+might use it as first attempt to defining a font.
+
+\starttyping
+\definefont
+ [MyFont]
+ [Bold:+kern;+liga; at 12.3pt]
+\stoptyping
+
+This is the \XETEX\ way of defining fonts. A \type {+} means as much as
+\quotation {turn on this feature} so you can guess what the minus sign does.
+Alternatively you can use a key/value approach with semicolons as separator. If
+no value is given the value \type {yes} is assumed.
+
+\starttyping
+\definefont
+ [MyFont]
+ [Bold:kern=yes;liga=yes; at 12.3pt]
+\stoptyping
+
+When we started supporting \XETEX\ we ran into issues with already present
+features of \CONTEXT\ as the \XETEX\ syntax also has some more obscure properties
+using slashes and brackets for signalling a file or name lookup. As in \CONTEXT\
+we prefer a more symbolic approach anyway, it never was a real issue.
+
+\stopsection
+
+\startsection[title=* (symbolic features)]
+
+The most natural way to associate a set of features with a font instance
+is the following:
+
+\starttyping
+\definefont
+ [MyFont]
+ [Bold*default at 12.3pt]
+\stoptyping
+
+This will use the featureset named \type {default} and this one is defined in
+\type {font-pre.mkiv} which might be worth looking at.
+
+\starttyping
+\definefontfeature
+ [always]
+ [mode=auto,
+ script=auto,
+ kern=yes,
+ mark=yes,
+ mkmk=yes,
+ curs=yes]
+
+\definefontfeature
+ [default]
+ [always]
+ [liga=yes,
+ tlig=yes,
+ trep=yes] % texligatures=yes,texquotes=yes
+
+\definefontfeature
+ [smallcaps]
+ [always]
+ [smcp=yes,
+ tlig=yes,
+ trep=yes] % texligatures=yes,texquotes=yes
+
+\definefontfeature
+ [oldstyle]
+ [always]
+ [onum=yes,
+ liga=yes,
+ tlig=yes,
+ trep=yes] % texligatures=yes,texquotes=yes
+
+\definefontfeature % == default unless redefined
+ [ligatures]
+ [always]
+ [liga=yes,
+ tlig=yes,
+ trep=yes]
+
+\definefontfeature % can be used for type1 fonts
+ [complete]
+ [always]
+ [compose=yes,
+ liga=yes,
+ tlig=yes,
+ trep=yes]
+
+\definefontfeature
+ [none]
+ [mode=none,
+ features=no]
+\stoptyping
+
+These definitions show that you can construct feature sets on top of existing
+ones, but keep in mind that they are defined instantly, so any change in the
+parent is not reflected in its kids.
+
+In a font definition you can specify more than one set:
+
+\starttyping
+\definefont
+ [MyFont]
+ [Bold*always,oldstyle at 12.3pt]
+\stoptyping
+
+\stopsection
+
+\startsection[title=@ (virtual features)]
+
+This method is somewhat special as it demands knowledge of the internals
+of the \CONTEXT\ font code. Much of it is still experimental but it is a
+nice playground. A good example of its usage can be found in the file
+\type {m-punk.mkiv} where we create a font out of \METAPOST\ graphics.
+
+Another example is virtual math. As in the beginning of \LUATEX\ and \MKIV\
+there were only a few \OPENTYPE\ math fonts, and as I wanted to get rid
+of the old mechanisms, it was decided to virtualize the math fonts. For
+instance a Latin Modern Roman 10 point math font can be defined as follows:
+
+\starttyping
+\definefontsynonym
+ [LMMathRoman10-Regular]
+ [LMMath10-Regular@lmroman10-math]
+\stoptyping
+
+The \type {lmroman10-math} refers to a virtual definition and in this case
+it is one using a built|-|in constructor and therefore we use a goodies
+file to specify the font. That file looks as follows:
+
+\starttyping
+return {
+ name = "lm-math",
+ version = "1.00",
+ comment = "Goodies that complement latin modern math.",
+ author = "Hans Hagen",
+ copyright = "ConTeXt development team",
+ mathematics = {
+ ...
+ virtuals = {
+ ...
+ ["lmroman10-math"] = ten,
+ ...
+ },
+ ...
+ }
+}
+\stoptyping
+
+Here \type {ten} is a previously defined table:
+
+\startnarrowtyping
+local ten = {
+ { name = "lmroman10-regular.otf", features = "virtualmath", main = true },
+ { name = "rm-lmr10.tfm", vector = "tex-mr-missing" } ,
+ { name = "lmmi10.tfm", vector = "tex-mi", skewchar = 0x7F },
+ { name = "lmmi10.tfm", vector = "tex-it", skewchar = 0x7F },
+ { name = "lmsy10.tfm", vector = "tex-sy", skewchar = 0x30, parameters = true } ,
+ { name = "lmex10.tfm", vector = "tex-ex", extension = true } ,
+ { name = "msam10.tfm", vector = "tex-ma" },
+ { name = "msbm10.tfm", vector = "tex-mb" },
+ { name = "stmary10.afm", vector = "tex-mc" },
+ { name = "lmroman10-bold.otf", vector = "tex-bf" } ,
+ { name = "lmmib10.tfm", vector = "tex-bi", skewchar = 0x7F } ,
+ { name = "lmsans10-regular.otf", vector = "tex-ss", optional = true },
+ { name = "lmmono10-regular.otf", vector = "tex-tt", optional = true },
+ { name = "eufm10.tfm", vector = "tex-fraktur", optional = true },
+ { name = "eufb10.tfm", vector = "tex-fraktur-bold", optional = true },
+}
+\stopnarrowtyping
+
+This says as much as: take \type {lmroman10-regular.otf} as starting point
+and overload slots with ones found in the following fonts. The vectors are
+predefined as they are shared with other font sets like \type {px} and
+\type {tx}.
+
+In due time more virtual methods might end up in \CONTEXT\ because they are
+a convenient way to extend or manipulate fonts.
+
+\stopsection
+
+\startsection[title=Lua fonts]
+
+You can define a font in \LUA. In the process you can use all kind of helper
+functions that \CONTEXT\ provides. Here is an example:
+
+\typefile{fonts-demo-rule.lua}
+
+This code is stored in \type {fonts-demo-rule.lua} and we can load that font
+in the usual way, by specifying a filename:
+
+\startbuffer
+\definefont
+ [MyRuleFont]
+ [file:fonts-demo-rule.lua*default sa 1]
+\stopbuffer
+
+\typebuffer
+
+\getbuffer
+
+{\MyRuleFont So when we use it we get text typeset where all vowels are replaced
+by rules. The actualtext injection (in theory) makes it possible to cut and paste
+the text from the \PDF\ document but while writing this (mid 2016) a {\maincolor
+\type {mupdf}} based viewer couldn't handle it and {\maincolor \type {acrobat}}
+had problems with spaces.}
+
+\startbuffer
+\definefontfeature
+ [myrulefont]
+ [default]
+ [original=file:texgyrepagella-regular.otf]
+\definefont
+ [MyRuleFont]
+ [file:fonts-demo-rule.lua*myrulefont]
+\stopbuffer
+
+\typebuffer
+
+\getbuffer
+
+{\showfontkerns \MyRuleFont The previous code demonstrates how we can pass a
+fontname to be used as base to the generator. In case you wonder how features
+behave with such fonts: as you can see here, font kerns are indeed injected.
+Compared to {\maincolor \type {Dejavu}}, the {\maincolor \type {Pagella}} font
+has quite some more kerns.}
+
+\startbuffer
+\definefontfeature
+ [myrulefont]
+ [default]
+ [original=file:texgyrepagella-regular.otf,
+ option=line]
+\definefont
+ [MyRuleFont]
+ [file:fonts-demo-rule.lua*myrulefont]
+\stopbuffer
+
+\typebuffer
+
+\getbuffer
+
+{\MyRuleFont Here we show how the passed {\maincolor \type {option}} is handled.
+Because we no longer have a relationship with the height and depth, the real text
+is a bit harder to guess.}
+
+\stopsection
+
+\startsection[title=Old fuzzy fonts]
+
+Most natural is to use \OPENTYPE\ or \TYPEONE\ fonts. In the case of \TYPEONE\ a
+matching pair of \type {afm} and \type {pfb} files is needed. However, there can
+be situations where there is only a \type{tfm} and \type {pfb} file (or not even
+that: just a bitmap file).
+
+I will not show specimen here, simply because I don't have (nor want to have) the
+fonts needed in my development and production environments. The implementation
+was tested with a specific czech computer modern font.
+
+In a traditional (8 bit) setup we have an \type {tfm} file, a \type {pfb} file
+and a \type {enc file}. The order of the characters in the \type {tfm} file
+directly relates to the input encoding. The \type {enc} file relates that order
+to the order in the \type {pfb} file. The mapping from input encoding to font
+shape encoding happens via glyph names. In the \type {map} file we tell what
+\type {pfb} file to use with what \type {enc} file.
+
+However, in the case of the \type {csr.tfm} and \type {csr.pfb} file it looks
+like in practice the \type {enc} file is not used, probably because in the \type
+{pfb} file the standard encoding matches the order in the \type {tfm} file. This
+is of course a rather dangerous assumption, especially if information lacks to
+check it.
+
+The next example definitions demonstrate several paths to go from \UNICODE\ input
+(source file) to rendered shapes. As this is mostly meant for generic usage we
+use the low level definition code (\CONTEXT\ users are not supposed to use that
+method).
+
+\starttyping
+\font\foo=file:csr10.tfm:reencode=auto;mode=node;liga=yes;kern=yes
+\stoptyping
+
+This is the easiest way. We use the \type {tfm} file for dimensions, ligatures
+and kerns. The \type {auto} option will use the \type {pfb} file to identify the
+right mapping. We enable ligatures and kerns and we use node mode. This indicates
+that we're dealing with a pseudo \OPENTYPE\ setup here. You can provide a \type
+{pfb} file with the \type {pfbfile} feature in case the name differes from the
+\type {tfm} file.
+
+\starttyping
+\font\foo=file:csr10.tfm:reencode=csr.enc;mode=node;liga=yes;kern=yes
+\stoptyping
+
+Now we use the \type {enc} file for the encoding vector but we still need the
+\type {pfb} file for mapping that onto the right shape. You probably can best use
+\type {auto} instead.
+
+\starttyping
+\font\foo=file:csr10.tfm:reencode=csr.enc;bitmap=yes;mode=node;liga=yes;kern=yes
+\stoptyping
+
+Here we force bitmap shapes. This is a bit tricky as a different code path is
+followed in the backend. Unless the situation is too confusing, a proper \type
+{ToUnicode} is included in the output, so that cut and paste works all right,
+given that the viewer is able to deal with it (always use \ACROBAT\ as
+reference).
+
+Why do we need modes and|/|or to simulate \OPENTYPE\ behaviour? Indeed it seldom
+makes sense with \type {tfm} files but in this particular case teh font has a
+quote cheat.
+
+\starttyping
+\startluacode
+ fonts.handlers.otf.addfeature {
+ name = "czechdqcheat",
+ type = "substitution",
+ data = {
+ quotedblright = "csquotedblright",
+ },
+ }
+\stopluacode
+\stoptyping
+
+We could make this a language specific feature but as this font is not meant for
+other languages it makes no sense to do so. This feature is enabled with:
+
+\starttyping
+czechdqcheat=yes
+\stoptyping
+
+This will replace one quote by another with different side bearings. Of course a
+properly bounded quote with proper kerning makes much more sense. A test case is:
+
+\starttyping
+\quotedblleft X\quotedblright
+\quotedblright X\quotedblleft
+\stoptyping
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-mkiv.tex b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-mkiv.tex
new file mode 100644
index 00000000000..fa53492f084
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-mkiv.tex
@@ -0,0 +1,76 @@
+% language=uk
+
+% author : Hans Hagen
+% copyright : PRAGMA ADE & ConTeXt Development Team
+% license : Creative Commons Attribution ShareAlike 4.0 International
+% reference : pragma-ade.nl | contextgarden.net | texlive (related) distributions
+% origin : the ConTeXt distribution
+%
+% comment : Because this manual is distributed with TeX distributions it comes with a rather
+% liberal license. We try to adapt these documents to upgrades in the (sub)systems
+% that they describe. Using parts of the content otherwise can therefore conflict
+% with existing functionality and we cannot be held responsible for that. Many of
+% the manuals contain characteristic graphics and personal notes or examples that
+% make no sense when used out-of-context.
+%
+% comment : Some chapters might have been published in TugBoat, the NTG Maps, the ConTeXt
+% Group journal or otherwise. Thanks to the editors for corrections. Also thanks
+% to users for testing, feedback and corrections.
+
+% \definefontfeature[default][default][globalkern=true]
+%
+% \usemodule[speedtest]
+
+\enabletrackers[fonts.usage]
+
+\enablemode[simple] % ,oversized
+
+\startbuffer[abstract]
+
+ This book is about fonts and how they are dealt with in \CONTEXT\ \MKIV\ and
+ \LUATEX. Although we use \CONTEXT\ as starting point, much applies to the
+ generic font handler that ships as part of this macro package. We discuss the
+ way fonts are dealt with in the engine, font formats, standard features and
+ additional goodies. Tracing and the extensibility of code are also discussed.
+ This book is the more technical companion of the regular \CONTEXT\ font
+ manual.
+
+\stopbuffer
+
+\environment fonts-environment
+
+\startdocument
+ [author=Hans Hagen,
+ title=Fonts out of \ConTeXt,
+ subtitle=explaining luatex and mkiv,
+ affiliation=PRAGMA ADE,
+ comment=work in progress,
+ cover:color:1=darkred,
+ cover:color:2=darkgreen,
+ cover:color:3=darkblue,
+ cover:color:4=darkyellow,
+ cover:color:5=darkgray]
+
+ \startfrontmatter
+ \component manuals-explaining-contents
+ \component fonts-introduction
+ \stopfrontmatter
+
+ \startbodymatter
+ \component fonts-formats
+ \component fonts-modes
+ \component fonts-lookups
+ \component fonts-methods
+ \component fonts-features
+ \component fonts-scripts
+ \component fonts-math
+ \component fonts-extensions
+ \component fonts-hooks
+ \component fonts-tricks
+ \stopbodymatter
+
+ \startappendices
+ \component fonts-appendix
+ \stopappendices
+
+\stopdocument
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-modes.tex b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-modes.tex
new file mode 100644
index 00000000000..95cb957328f
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-modes.tex
@@ -0,0 +1,817 @@
+% language=uk
+
+\definefontfeature
+ [otftracker-husayni]
+ [analyze=yes,mode=node,language=dflt,script=arab,
+ ccmp=yes,init=yes,medi=yes,fina=yes,
+ rlig=yes,tlig=yes,anum=yes,calt=yes,salt=yes,
+ ss01=yes,ss03=yes,ss10=yes,ss12=yes,ss15=yes,
+ ss16=yes,ss19=yes,ss24=yes,ss25=yes,ss26=yes,
+ ss27=yes,ss31=yes,ss34=yes,ss35=yes,ss36=yes,
+ ss37=yes,ss38=yes,ss41=yes,ss42=yes,ss43=yes,
+ ss60=yes,js16=yes,
+ kern=yes,curs=yes,mark=yes,mkmk=yes]
+
+\startbuffer[nodechart:1a]
+
+ \switchtobodyfont[6pt]
+
+ \definecolor[nodechart:glyph][maincolor]
+
+ \hboxtoFLOWchart[dummy]{\definedfont[Normal*none]\language0 test BLAtest}
+
+ \FLOWchart[dummy][width=14em,height=3em,dx=.5em,dy=.75em,offset=1em,hcompact=yes]
+
+\stopbuffer
+
+\startbuffer[nodechart:1b]
+
+ \switchtobodyfont[6pt]
+
+ \definecolor[nodechart:glyph][maincolor]
+
+ \hboxtoFLOWchart[dummy]{test BLAtest}
+
+ \FLOWchart[dummy][width=14em,height=3em,dx=.5em,dy=.75em,offset=1em,hcompact=yes]
+
+\stopbuffer
+
+\startbuffer[nodechart:2a]
+
+ \switchtobodyfont[6pt]
+
+ \definecolor[nodechart:glyph][maincolor]
+
+ \hboxtoFLOWchart[dummy]{affiliation}
+
+ \FLOWchart[dummy][width=14em,height=3em,dx=.5em,dy=.75em,offset=1em,hcompact=yes]
+
+\stopbuffer
+
+\startbuffer[nodechart:2b]
+
+ \switchtobodyfont[6pt]
+
+ \definecolor[nodechart:glyph][maincolor]
+
+ \hboxtoFLOWchart[dummy]{abc\discretionary{d}{e}{f}ghi}
+
+ \FLOWchart[dummy][width=14em,height=3em,dx=.5em,dy=.75em,offset=1em,hcompact=yes]
+
+\stopbuffer
+
+\startbuffer[nodechart:2c]
+
+ \switchtobodyfont[6pt]
+
+ \definecolor[nodechart:glyph][maincolor]
+
+ \hboxtoFLOWchart[dummy]{\nl effe fijn fietsen}
+
+ \FLOWchart[dummy][width=12em,height=3em,dx=.5em,dy=.75em,offset=1em,hcompact=yes]
+
+\stopbuffer
+
+\startbuffer[nodechart:3a]
+
+ \switchtobodyfont[6pt]
+
+ \definecolor[nodechart:glyph][maincolor]
+
+ \hboxtoFLOWchart[dummy]{\tttf\righttoleft فَخَا}
+
+ \FLOWchart[dummy][width=12em,height=3em,dx=.5em,dy=.75em,offset=1em,hcompact=yes]
+
+\stopbuffer
+
+\startbuffer[nodechart:3b]
+
+ \switchtobodyfont[6pt]
+
+ \definecolor[nodechart:glyph][maincolor]
+
+ \hboxtoFLOWchart[dummy]{{\definedfont[name:husayni*otftracker-husayni at 6pt]\righttoleft فَخَا}}
+
+ \FLOWchart[dummy][width=12em,height=3em,dx=.5em,dy=.75em,offset=1em,hcompact=yes]
+
+\stopbuffer
+
+\startcomponent fonts-modes
+
+\environment fonts-environment
+
+\startchapter[title=Modes][color=darkgreen]
+
+\startsection[title=Introduction]
+
+We use the term modes for classifying the several ways characters are turned into
+glyphs. When a font is defined, a set of features can be associated and one of
+them is the mode.
+
+\starttabulate[|l|p|]
+\NC none \NC Characters are just mapped onto glyphs and no substitution or
+ positioning takes place. \NC \NR
+\NC base \NC The routines built into the engine are used. For many Latin fonts
+ this is a rather useable and efficient method. \NC \NR
+\NC node \NC Here alternative routines written in \LUA\ are used. This mode is
+ needed for more complex scripts as well as more advanced features
+ that demand some analysis. \NC \NR
+\NC auto \NC This mode will determine the most suitable mode for the given
+ feature set. \NC \NR
+\stoptabulate
+
+When we talk about features, we refer to more than only features provided by
+fonts as \CONTEXT\ adds some of its own. In the following section each of these
+modes is discussed. Before we do so a short introduction to font tables that we
+use is given.
+
+\stopsection
+
+\startsection[title=The font table]
+
+The internal representation of a font in \CONTEXT\ is such that we can
+conveniently access data that is needed in the mentioned modes. When a font is
+used for the first time, or when it has changed, it is read in its most raw form.
+After some cleanup and normalization the font gets cached when it is a \TYPEONE\
+or \OPENTYPE\ font. This is done in a rather efficient way. A next time the
+cached copy is used.
+
+The normalized table is shared among instances of a font. This means that when a
+font is used at a different scale, or when a different feature set is used, the
+font gets loaded only once and its data is shared when possible. In \in {figure}
+[fig:tfm-loading] we have visualized the process. Say that you ask for font \type
+{whatever} at \type {12pt} using featureset \type {smallcaps}. In low level code
+this boils down to:
+
+\starttyping
+\font\MySmallCaps=whatever*smallcaps at 12pt
+\stoptyping
+
+In \CONTEXT\ we have overloaded the font loader so \LUA\ code takes care of the
+loading. Basically there is a function hooked into \LUATEX's font definer (the
+\type {\font} primitive) that returns a table and from that on \LUATEX\ will
+create its internal representation that is identified by a number, the so called
+font id. So, in fact the \type {\Whatever} command is a reference to a font id, a
+positive number. When this font is already loaded, \CONTEXT\ will reuse the id
+and pas that one.
+
+\startFLOWchart[loading]
+ \startFLOWcell \name {tfm 1} \location {2,1} \text {raw tfm} \connection [bt]{tfm 2} \stopFLOWcell
+ \startFLOWcell \name {tfm 2} \location {2,2} \text {normalized tfm} \connection [rl]{tfm 3} \stopFLOWcell
+ \startFLOWcell \name {tfm 3} \location {4,2} \text {featured tfm} \connection[+rl]{tfm 5a}
+ \connection [rl]{tfm 5b}
+ \connection[-rl]{tfm 5c} \stopFLOWcell
+
+ \startFLOWcell \name {tfm 5a} \location {5,1} \text {scaled tfm} \connection[r+t]{tfm} \stopFLOWcell
+ \startFLOWcell \name {tfm 5b} \location {5,2} \text {scaled tfm} \connection [rt]{tfm} \stopFLOWcell
+ \startFLOWcell \name {tfm 5c} \location {5,3} \text {scaled tfm} \connection[r-t]{tfm} \stopFLOWcell
+
+ \startFLOWcell \name {afm 1} \location {2,4} \text {raw afm} \connection [bt]{afm 2} \stopFLOWcell
+ \startFLOWcell \name {afm 2} \location {2,5} \text {normalized afm} \connection [rl]{afm 3} \stopFLOWcell
+ \startFLOWcell \name {afm 3} \location {3,5} \text {cached afm} \connection[+rl]{afm 4a}
+ \connection [rl]{afm 4b} \stopFLOWcell
+ \startFLOWcell \name {afm 4a} \location {4,4} \text {featured afm} \connection [rl]{afm 5a} \stopFLOWcell
+ \startFLOWcell \name {afm 4b} \location {4,5} \text {featured afm} \connection [rl]{afm 5b}
+ \connection[-rl]{afm 5c} \stopFLOWcell
+ \startFLOWcell \name {afm 5a} \location {5,4} \text {scaled afm} \connection[r+l]{tfm} \stopFLOWcell
+ \startFLOWcell \name {afm 5b} \location {5,5} \text {scaled afm} \connection [rl]{tfm} \stopFLOWcell
+ \startFLOWcell \name {afm 5c} \location {5,6} \text {scaled afm} \connection[r-l]{tfm} \stopFLOWcell
+
+ \startFLOWcell \name {otf 1} \location {2,7} \text {raw otf} \connection [bt]{otf 2} \stopFLOWcell
+ \startFLOWcell \name {otf 2} \location {2,8} \text {normalized otf} \connection [rl]{otf 3} \stopFLOWcell
+ \startFLOWcell \name {otf 3} \location {3,8} \text {cached otf} \connection[+rl]{otf 4a}
+ \connection [rl]{otf 4b} \stopFLOWcell
+ \startFLOWcell \name {otf 4a} \location {4,7} \text {featured otf} \connection [rl]{otf 5a} \stopFLOWcell
+ \startFLOWcell \name {otf 4b} \location {4,8} \text {featured otf} \connection [rl]{otf 5b}
+ \connection[-rl]{otf 5c} \stopFLOWcell
+ \startFLOWcell \name {otf 5a} \location {5,7} \text {scaled otf} \connection[r-b]{tfm} \stopFLOWcell
+ \startFLOWcell \name {otf 5b} \location {5,8} \text {scaled otf} \connection [rb]{tfm} \stopFLOWcell
+ \startFLOWcell \name {otf 5c} \location {5,9} \text {scaled otf} \connection[r+b]{tfm} \stopFLOWcell
+
+ \startFLOWcell \name {tfm} \location {6,5} \text {engine tfm} \stopFLOWcell
+\stopFLOWchart
+
+\startplacefigure [location=here,reference=fig:tfm-loading,title={Defining a font.}]
+ \FLOWchart[loading][dx=.75\bodyfontsize,dy=.5\bodyfontsize,width=6\bodyfontsize,offset=0pt,x=2]
+\stopplacefigure
+
+The first step is loading the font (or using the cached copy). From that a copy
+is made that has some additional data concerning the features set and from that a
+scaled copy is constructed. These copies share as much data as possible to keep
+the memory footprint as small as possible. The table that is passed to \LUATEX\
+gets cleaned up afterwards. In practice the \TFM\ loader only kicks in for
+creating virtual math fonts. The \AFM\ reader is used for \TYPEONE\ fonts and as
+there is no free upgrade path from \TYPEONE\ to \OPENTYPE\ for commercial fonts,
+that one will get used for older fonts. Of course most loading is done by the
+\OTF\ reader(s).
+
+\appendixdata{\in[fonts:trackers:tables]}
+
+The data in the final \TFM\ table is organized in subtables. The biggest ones are
+the \type {characters} and \type {descriptions} tables that have information
+about each glyph. Later we will see more of that. There are a few additional
+tables of which we show two: \type {properties} and \type {parameters}. For the
+current font the first one has the following entries:
+
+\showfontproperties
+
+The \type {parameters} table has variables that have been (re)assigned in the
+process. A period in the key indicates that we are dealing with a subtable, for
+instance \type {expansion}.
+
+\showfontparameters
+
+To give you an impression of what we are dealing with, the positional features
+are shown next:
+
+\showfontpositionings
+
+The substitution features of the current font are as follows:
+
+\showfontsubstitutions
+
+This is clearly an \OPENTYPE\ font. Normally there are a default
+script and default language supported. If this is not the case you
+need to provide them as part of the featureset, otherwise there
+will be no features applied.
+
+\stopsection
+
+\startsection[title=Base mode]
+
+We talk of base mode processing when the font machinery is used that is built in
+\LUATEX. So what does this traditional mechanism provide?
+
+Before we discuss this, a somewhat simplified model of how \TEX\ works has to be
+given. Say that we have the following input:
+
+\starttyping
+\def\bla{BLA}
+test \bla test
+\stoptyping
+
+This input gets translated into tokens and those tokens are either processed
+later or they become something else directly. Take the first line. Characters in
+the input have a so called catcode property that determines how the parser
+tokenized them. Effectively we therefore get something like this:
+
+\starttyping
+<command def>
+<command bla>
+<begingroup>
+<character B>
+<character L>
+<character A>
+<endgroup>
+\stoptyping
+
+and finally in the hash table there will be an entry for \type {bla} that has the
+meaning \type {BLA} expressed in three characters.
+
+The second line refers to \type {\bla} and in the process this macro gets
+expanded, so we get:
+
+\starttyping
+<character t>
+<character e>
+<character s>
+<character t>
+<space>
+<character B>
+<character L>
+<character A>
+<character t>
+<character e>
+<character s>
+<character t>
+\stoptyping
+
+Because the parser gobbles spaces after a macro name, there is no space before
+the second \type {test}. In practice there will be no intermediate list like
+this, because as soon as possible \TEX\ will add something to a so called node
+list. When the moment is there, this list will be passed to the typesetting
+routine that constructs a horizontal list. Later this list can be converted into
+a horizontal box or broken into lines when it concerns a paragraph.
+
+In traditional \TEX\ characters are stored into char nodes and the builder turns
+them into glyph nodes. In \LUATEX\ they start out as glyph nodes and the subtype
+number will flag them as glyphs. Any value larger than 255 is a signal that the
+list has been processed. The previous example leads to the list shown in \in
+{figure} [nodechart:1a].
+
+\startplacefigure[title={The text \quote {\typ {test BLAtest}} converted to nodes.},reference=nodechart:1a]
+ \getbuffer[nodechart:1a]
+\stopplacefigure
+
+Here we have turned off inter|-|character kerning and hyphenation. When we turn
+that on, we get a slightly more complex list, as shown in \in {figure}
+[nodechart:1b]. Hyphenation points are represented by discretionary nodes and
+these have pointers to a pre break, post break and replacement text.
+
+\startplacefigure[title={The text \quote {\typ {test BLAtest}} converted to nodes, hyphenated and kerned.},reference=nodechart:1b]
+ \getbuffer[nodechart:1b]
+\stopplacefigure
+
+In addition to hyphenation and kerning we can have ligatures. The list in \in
+{figure} [nodechart:2a] shows that we get a reference to a ligature in the glyph
+node but that the components are still known. This figure also demonstrates that
+the ligature is build in steps.
+
+\startplacefigure[title={The rendering of the word \quote {\typ {affiliation}}.},reference=nodechart:2a]
+ \getbuffer[nodechart:2a]
+\stopplacefigure
+
+% \appendixdata{\in[nodes:discretionaries]}
+
+If we insert an explicit \type {\discretionary} command, we see in
+\in {figure} [nodechart:2b] that we get three variants. In \in
+{figure} [nodechart:2c] we render some Dutch words and these have
+quite some ligatures.
+
+\startplacefigure[title={The rendering of the bogus word \quote {\typ {abcghi}} with an
+ explicit discretionary added.},reference=nodechart:2b]
+ \getbuffer[nodechart:2b]
+\stopplacefigure
+
+\startplacefigure[title={The rendering of the Dutch words \quote { \typ{effe fijn fietsen}}.},reference=nodechart:2c]
+ \getbuffer[nodechart:2c]
+\stopplacefigure
+
+So, we have hyphenation, ligature building and kerning and to some extent these
+mechanisms hook into each other. This process is driven by information stored in
+the font and rules related to the language. The hyphenation happens first, so the
+builder just sees discretionary nodes and needs to act properly on them. Although
+languages play an important role in formatting the text, for the moment we can
+forget about that. This leaves the font.
+
+As we already mentioned in a previous chapter, in \CONTEXT\ we use \UNICODE\
+internally. This also means that fonts are organized this way. By default the
+glyph representation of a \UNICODE\ character sits in the same slot in the glyph
+table. All additional glyphs, like ligatures or alternates are pushed in the
+private unicode space. This is why in the lists shown in the figures the
+ligatures have a private \UNICODE\ number.
+
+The basic mode of operation in the builder in \LUATEX\ is as follows:
+
+\startitemize[packed]
+\startitem hyphenate the node list \stopitem
+\startitem build ligatures \stopitem
+\startitem inject kerns \stopitem
+\startitem optionally break into lines \stopitem
+\stopitemize
+
+In traditional \TEX\ the first step is not that independent. There hyphenation
+takes place when the text is broken into lines, and only in places that are
+candidate for such a break. In \LUATEX\ the whole text is hyphenated. This has
+the advantage that the steps are clearly separated and that no complex
+reconstruction and re|-|hyphenation has to take place. The speed penalty can be
+neglected and the extra memory overhead is small compared to what is needed
+anyway.
+
+In base mode the raw font data is read in and from that only basic information is
+used to construct the \TFM\ table: dimensions, ligatures and kerns. In a node
+list, all glyph ranges that refer to such a font get the standard ligature and
+kern routines applied, but only if the subtype is still less than 256. This check
+on subtype prevents duplicate processing that might happen as a side effect of
+for instance unboxing some material in a yet to be typeset text.
+
+Given that the majority of what \TEX\ has to deal with is relatively simple latin
+script, base mode processing is rather convenient and efficient. It is also the
+reference point of other kinds of processing. The most simple way to force base
+mode is the following:
+
+\starttyping
+\definefontfeature[basemode][mode=base,kern=yes,liga=yes]
+
+\definefont[MyTitleFont][SerifBold*basemode at 12pt]
+\stoptyping
+
+Here \type {\MyTitleFont} will be a bold serif with ligatures and kerns applied.
+However, as an \OPENTYPE\ font can have many features, the following definitions
+are also valid:
+
+\starttyping
+\definefontfeature[basemode-o][mode=base,kern=yes,onum=yes,liga=yes]
+\definefontfeature[basemode-s][mode=base,kern=yes,smcp=yes]
+\stoptyping
+
+The \TFM\ constructor will filter the right information from the font data and
+construct a proper table based on these specifications. But you need to keep in
+mind that when for instance old style numerals or small caps are activated, that
+their rendering (the glyph) will always be used. So, for instance \type {3} and
+\type {A} keep their \UNICODE\ points but as part of their specification they
+will get an index pointing to the oldstyle or small caps variant and the
+dimensions of that shape will be used.
+
+\stopsection
+
+\startsection[title=Node mode]
+
+Node mode is by far the most interesting of the modes. When enabled we only pass
+a few properties of glyphs to the engine: the width, height and depth and
+optionally protrusion, expansion factors as well as some extra \CONTEXT\ specific
+quantities. So there is no kerning and no ligature building done by the engine.
+Instead we do this in \LUA\ by walking over the node list and checking if some
+action is needed.
+
+\appendixdata{\in[fonts:trackers:features]}
+
+The default feature set enables kerning and ligature building for default and/or
+Latin scripts and the default language. Being a relative simple feature,
+ligatures don't take much action. Next we show a trace of a ligature replacement.
+
+\blank
+\showotfcomposition{name:dejavuserif*default at 24pt}{1}{affiliation}
+\blank
+
+Be warned that this \type {f f i} sequence not always becomes a ligature.
+Actually this is one area where tradition is quite visible: for some reason most
+fonts do have these f|-|related ligatures but lack others. These ligatures even
+have code points in \UNICODE\ which is quite debatable. Just as there are fonts
+with hardly any kerns (like Lucida) there are fonts that follow a different route
+to improve the look and feel of neighbouring glyphs, like Cambria:
+
+\blank
+\showotfcomposition{name:cambria*default at 24pt}{1}{affiliation}
+\blank
+
+Instead of representing multiple characters by one glyph the designer has decided
+to replace the \type {f} by a slightly narrower one so that the dot of the \type
+{i} stays loose.
+
+An example where much more is involved is the following. The Husayni font that is
+used for typesetting Arabic is built upon a solid but complex \OPENTYPE\
+foundation and can only be dealt with in node mode. When the \LUATEX\ project
+started we assumed that more power in the engine was needed to accomplish this,
+but so far the results with standard \OPENTYPE\ functionality are quite good.
+\CONTEXT\ has an additional paragraph optimizer that can apply additional
+features to get even better results but discussing this falls beyond this
+chapter. A trace of just one Arabic word is much longer than the previously shown
+traces.
+
+\blank
+\showotfcomposition{name:husayni*otftracker-husayni at 48pt}{-1}{فَخَا}
+\blank
+
+What we see here is a stepwise substitution process, sometimes based on a
+contextual analysis, followed by positioning. The coloring concerns the outcome
+of the analysis which in this case flags initial, final, medial and isolated
+characters.
+
+The starting point of this Arabic word is visualized in \in {figure}
+[nodechart:3a] and as expected we see no discretionary nodes here. The result as
+seen in \in {figure} [nodechart:3b] has (interestingly) no kerns as all
+replacements happen via offsets in the glyph node.
+
+\startplacefigure[title={The Arabic input \quote {\tttf\righttoleft فَخَا} before rendering.},reference=nodechart:3a]
+ \getbuffer[nodechart:3a]
+\stopplacefigure
+
+\startplacefigure[title={The Arabic input \quote {\tttf\righttoleft فَخَا} after rendering.},reference=nodechart:3b]
+ \getbuffer[nodechart:3b]
+\stopplacefigure
+
+\stopsection
+
+\startsection[title=Auto mode]
+
+Base mode is lean and mean and relatively fast while node mode is more powerful
+and slower. So how do you know what to choose? The safest bet is to use node mode
+for everything. In \CONTEXT\ however, we also have the so called auto mode. In that
+case there is some analysis going on that chooses between base mode and node mode
+depending on the boundary conditions of script and language and there are specific
+demands in terms of feature processing. So, auto mode will resolve to base or
+node mode.
+
+\stopsection
+
+\startsection[title=None mode]
+
+Sometimes no features have to be applied at all. A good example is verbatim.
+There you don't want ligatures, kerning or fancy substitutions. Contrary to what
+you might expect, monospaced fonts can have such features. Some might actually
+make sense, like rendering zeros. However, you cannot assume such a feature to be
+present so this is an example of where some more knowledge about a particular
+font is needed. This is what Latin Modern provides.
+
+\starttabulate[|l|l|l|]
+\NC \type{none} \NC typewriter \NC \ruledhbox{\maincolor\DemoNoneLT1234567890} \NC \NR
+\NC \type{zero} \NC typewriter \NC \ruledhbox{\maincolor\DemoZeroLT1234567890} \NC \NR
+\NC \type{none} \NC regular \NC \ruledhbox{\maincolor\DemoNoneLM1234567890} \NC \NR
+\NC \type{zero} \NC regular \NC \ruledhbox{\maincolor\DemoZeroLM1234567890} \NC \NR
+\stoptabulate
+
+Normally using mode none for situations that need to be predictable is quite
+okay.
+
+\stopsection
+
+\startsection[title=Dynamics]
+
+Sometimes you want to enable or disable a specific feature only for a specific
+span of text. Defining a font for only this occasion is overkill, especially when
+for instance features are used to fine|-|tune the typography as happens in the
+Oriental \TEX\ project, which is related to \LUATEX. Instead of defining yet
+another font instance we can therefore enable and disable specific features. For
+this it is not needed to know the current font and its size. \footnote {Dynamics
+are a \CONTEXT\ specific feature and is not available in the generic version of
+the font code. There are several reasons for this: it complicates the code, it
+assumes the \CONTEXT\ feature definition mechanism to be used, and it is somewhat
+slower as some extra analysis has to be done.}
+
+Dynamics are a special case of node mode and you don't need to set it up when
+defining a font. In fact, a font defined in base mode can also be dynamic. We
+show some simple examples of applying dynamic features.
+
+% First we define two feature sets, one for ligatures and one for oldstyle. As in
+% our example we want to start fresh we also define a simple set with only kerning
+% enabled. In a next chapter we will see more of how featuresets are defined.
+%
+% \startbuffer
+% \definefontfeature[l][script=latn,liga=yes]
+% \definefontfeature[o][script=latn,onum=yes]
+% \definefontfeature[k][script=latn,kern=yes]
+%
+% \definefont[LOKfont][file:lmroman10-regular*k]
+% \stopbuffer
+%
+% \typebuffer \getbuffer
+
+% \startbuffer[demo]
+% {\LOKfont fiets 123 fiets 123 fiets 123}\par
+% {\LOKfont fiets 123 \addff{l}fiets 123 \addff{o}fiets 123}\par
+% {\LOKfont fiets 123 \addff{o}fiets 123 \addff{l}fiets 123}\par
+% {\LOKfont fiets 123 \addfs{l}fiets 123 \addfs{o}fiets 123}\par
+% {\LOKfont fiets 123 \addfs{o}fiets 123 \addfs{l}fiets 123}\par
+% {\LOKfont fiets 123 \addfs{l}fiets 123 \subfs{l}fiets 123}\par
+% {\LOKfont fiets 123 \addfs{o}fiets 123 \subfs{o}fiets 123}\par
+% \stopbuffer
+%
+% We use the following test line:
+%
+% \typebuffer
+%
+% In the first line we do nothing but in the following lines we add features to the
+% font (replacing existing ones), we add features to the current set (nothing gets
+% replaced) and finally we remove some from the set. The typeset result is shown in
+% \in {figure} [fig:modes:dynamics].
+%
+% \placefigure
+% [here]
+% [fig:modes:dynamics]
+% {Selectively applying ligatures and oldstyle numerals using dynamic features in
+% Latin Modern Roman.}
+% {\color[maincolor]{\externalfigure[demo.buffer][width=.75\textwidth]}}
+%
+% Although for reasons of symmetry we have a few more commands, in practice only
+% the following make sense, and even the first one is mostly of interest or
+% testing.
+%
+% \starttabulate[|l|l|]
+% \NC \type {\addff} \NC set a feature to be the one applied \NC \NR
+% \NC \type {\addfs} \NC add a feature to current set \NC \NR
+% \NC \type {\subfs} \NC remove a feature from the current set \NC \NR
+% \stoptabulate
+%
+% Keep in mind that the given feature set can set a combination of
+% features. Also be aware of the fact that these commands don't
+% accumulate: the last one is applied.
+
+% A more sophisticated dynamic feature mechanism is the following. This
+% time we do stack up features. We can add, subtract or even replace
+% feature sets.
+
+Let's first define some feature sets:
+
+\startbuffer
+\definefontfeature[f:smallcaps][smcp=yes]
+\definefontfeature[f:nocaps] [smcp=no]
+\definefontfeature[f:oldstyle] [onum=yes]
+\definefontfeature[f:newstyle] [onum=no]
+\stopbuffer
+
+\typebuffer \getbuffer
+
+We can add and subtract these features from the current feature set
+that is bound to the current font.
+
+\startbuffer
+\switchtobodyfont[pagella] 123 normal
+\addfeature {f:oldstyle} 123 oldstyle
+\addfeature {f:smallcaps} 123 olstyle smallcaps
+\subtractfeature{f:oldstyle} 123 smallcaps
+\subtractfeature{f:smallcaps} 123 normal
+\stopbuffer
+
+\typebuffer
+
+Here we choose a font that has oldstyle numerals as well as small caps: pagella.
+
+\blank \start \getbuffer \stop \blank
+
+The following does the same, but only uses addition:
+
+\startbuffer
+\switchtobodyfont[pagella] 123 normal
+\addfeature{f:oldstyle} 123 oldstyle
+\addfeature{f:smallcaps} 123 olstyle smallcaps
+\addfeature{f:newstyle} 123 smallcaps
+\addfeature{f:nocaps} 123 normal
+\stopbuffer
+
+\typebuffer
+
+You can also completely replace a feature set. Of course the set is only
+forgotten inside the current group.
+
+\startbuffer
+\switchtobodyfont[pagella] 123 normal
+\addfeature {f:oldstyle} 123 oldstyle
+\addfeature {f:smallcaps} 123 olstyle smallcaps
+\replacefeature{f:oldstyle} 123 oldstyle
+\replacefeature{f:smallcaps} 123 smallcaps
+\stopbuffer
+
+\typebuffer
+
+and now we get:
+
+\blank \start \getbuffer \stop \blank
+
+You can exercise some control with \type {\resetfeature}:
+
+\startbuffer
+\switchtobodyfont[pagella] 123 normal
+\addfeature [f:oldstyle] 123 oldstyle
+\addfeature [f:smallcaps] 123 olstyle smallcaps
+\resetfeature 123 reset
+\addfeature [f:oldstyle] 123 oldstyle
+\addfeature [f:smallcaps] 123 olstyle smallcaps
+\stopbuffer
+
+\typebuffer
+
+Watch how we use the \type {[]} variant of the commands. The braced and
+bracketed variants behave the same.
+
+\blank \start \getbuffer \stop \blank
+
+There is also a generic command \type {\feature} that takes two arguments. Below
+we show all calls, with long and short variants:
+
+\starttyping
+\addfeature [f:mine] \feature [more][f:mine] \feature[+][f:mine]
+\subtractfeature [f:mine] \feature [less][f:mine] \feature[-][f:mine]
+\replacefeature [f:mine] \feature [new][f:mine] \feature[=][f:mine]
+\resetandaddfeature[f:mine] \feature[local][f:mine] \feature[!][f:mine]
+\revivefeature [f:mine] \feature [old][f:mine] \feature[>][f:mine]
+\resetfeature \feature[reset] \feature[<]
+\stoptyping
+
+Each variant also accepts \type {{}} instead of \type {[]} so that they can
+conveniently be used in square bracket arguments. As a bonus, the following also
+works:
+
+\startbuffer
+\switchtobodyfont[pagella]
+123 normal
+\feature[+][f:smallcaps,f:oldstyle]
+123 SmallCaps and OldStyle
+\stopbuffer
+
+\typebuffer
+
+Here is the proof:
+
+\blank \start \getbuffer \stop \blank
+
+\stopsection
+
+\startsection[title=Discretionaries]
+
+One of the complications in supporting more complex features is that we can have
+discretionary nodes. These are either inserted by the hyphenation engine, or
+explicitly by the user (directly or via macros). In most cases we don't need to
+bother about this. For instance, more demanding scripts like Arabic don't
+hyphenate, languages using the Latin script seldom want ligatures at hyphenation
+points (as they can be compound words) and|/|or avoid confusing hyphenation
+points, so what is left are specific user inserted discretionaries. Add to that,
+that a proper font has not much kerning between lowercase characters and it will
+be clear that we can ignore most of this. Anyway, as we explicitly deal with user
+discretionaries, the next works out okay. Watch how we normally only have
+something special in the replacements text that shows up when no hyphenation is
+needed.
+
+\startbuffer
+\language[nl]
+\definedfont[file:texgyrepagella-regular.otf*default]
+\hsize 1mm vereffenen \par
+\hsize 1mm effe \par
+\hsize 1mm e\discretionary{f-}{f}{ff}e \par
+\hsize 20mm e\discretionary{f-}{f}{ff}e \par
+\smallcaps
+\hsize 1mm vereffenen \par
+\hsize 1mm effe \par
+\hsize 1mm e\discretionary{f-}{f}{ff}e \par
+\hsize 20mm e\discretionary{f-}{f}{ff}e \par
+\stopbuffer
+
+\typebuffer
+
+\blank
+\startcolumns[n=6]
+ \indenting[no]
+ \maincolor
+ \getbuffer
+\stopcolumns
+\blank
+
+In base mode such things are handled by the \TEX\ engine itself and it can deal
+with pretty complex cases. In node mode we use a simplification which in practice
+suffices. We will come back to this in \in {section} [ligatures:hyphenation].
+
+\stopsection
+
+\startsection[title=Efficiency]
+
+The efficiency of the mechanisms described here depends on several factors. It
+will be clear that the larger the font, the more time it will take to load it.
+But what is large? Most \CJK\ fonts are pretty large but also rather simple. A
+font like Zapfino on the other hand covers only latin but comes with many
+alternative shapes and a large set of rules. The Husayni font focusses on Arabic,
+which in itself has not that large an alphabet, but being an advanced script
+font, it has a lot of features and definitely a lot of rules.
+
+In terms of processing it's safe to say that Latin is of average complexity. At
+most you will get some substitutions, like regular numerals being replaced by
+oldstyles, or ligature building, which involves a bit of analysis, and some
+kerning at the end. In base mode the substitutions have no overhead, simply
+because the character table already has references to the substituents and the
+replacement already takes place when defining the font. There ligature building
+and kerning are also fast because of the limited amount of lookups that also are
+already kept with the characters. In node mode however, the lists have to be
+parsed and tables have to be consulted so even Latin processing has some
+overhead: each glyph node is consulted and analyzed (either or not in its
+context), often multiple times. However, the code is rather optimized and we use
+caching of already analyzed data when possible.
+
+A \CJK\ script is somewhat more complex on the one hand, but pretty simple on the
+other. Instead of font based kerning, we need to prevent or encourage breaks
+between certain characters. This information is not in the font and is processed
+otherwise but it does cost some time. The font part however is largely idle as
+there are no features to be applied. Even better, because the glyphs are large
+and the information density is high, the processing time per page is not much
+different from Latin. Base mode is good enough for most \CJK.
+
+The Arabic script is another matter. There we definitely go beyond what base mode
+offers so we always end up in node mode. Also, because there is some analysis
+involved, quite some substitutions and in the end also positioning, these are the
+least efficient fonts in terms of processing time. Of course the fact that we mix
+directions also plays a role. If in the Husayni font you enable 30 features with
+an average of 5 rules per feature, a 300 character paragraph will take 45.000
+actions. \footnote {For a modern machine this amount is no real issue, but as
+each action involves function calls and possibly some garbage collection there
+is some price to pay.} When multiple fonts are combined in a paragraph there will
+be more sweeps over the list and of course the replacements also have to happen.
+
+In a time when the average photo camera produces megabyte pictures it makes no
+sense to whine about the size of a font file. On the other hand as each font
+eventually ends up in memory as a \LUA\ table, it makes sense to optimize that
+bit. This is why fonts are converted into a more efficient intermediate table
+that is cached on disk. This makes loading a font quite fast and due to shared
+tables memory usage rather efficient. Of course a scaled instance has to be
+generated too, but that is acceptable. To some extent loading and defining a font
+also depends on the way the macro package is set up.
+
+When comparing \LUATEX\ with for instance \PDFTEX\ or \XETEX\ you need to take
+into account that in \CONTEXT\ \MKIV\ we tend to use \OPENTYPE\ fonts only so
+there are less fonts loaded than in a more traditional setup. In \CONTEXT\
+startup time of \MKIV\ is less than \MKII\ although overall processing time is
+slower, which is due to \UNICODE\ being used and more functionality being
+provided. On the other hand, immediate \METAPOST\ processing and more clever
+multipass handling wins back time. The impact of fonts on processing time in a
+regular document is therefore not that impressive. In practice a \MKIV\ run can
+be faster than a \MKII\ run, especially when \METAPOST\ is used.
+
+In \CONTEXT\ processing of node lists with respect to fonts is only one of the
+many manipulations of such lists and by now fonts are not really the bottleneck.
+The more not font related features users demand and enable, the less the relative
+impact of font processing becomes.
+
+Also, there are some advanced typographic extras that \LUATEX\ offers, like
+protrusion (think of hanging punctuation) and hz optimization (glyph scaling) and
+these slow down processing quite a lot, and they are not taking place at the
+\LUA\ end at all, but this might change in \MKIV. And, of course, typesetting
+involves more than fonts and other aspects can be way more demanding.
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
+
+% oldstyle not in math (old school tex)
+% funny tex ligatures
+% features=yes
+% analysis
+% mode=none (tt)
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-scripts.tex b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-scripts.tex
new file mode 100644
index 00000000000..aed4f0a5c9d
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-scripts.tex
@@ -0,0 +1,18 @@
+% language=uk
+
+\startcomponent fonts-scripts
+
+\environment fonts-environment
+
+\startchapter[title=Scripts][color=darkmix-6]
+
+\startsection[title=Introduction]
+
+As \OPENTYPE\ fonts can provide specific features to deal with scripts and
+languages it makes sense to spend some word on this.
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-tricks.tex b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-tricks.tex
new file mode 100644
index 00000000000..65b210e2c48
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-tricks.tex
@@ -0,0 +1,390 @@
+% language=uk
+
+\startcomponent fonts-tricks
+
+\environment fonts-environment
+
+\startchapter[title=Tricks][color=middleorange]
+
+\startsection[title=Introduction]
+
+In this chapter topics that don't fit in the previous chapters are
+collected.
+
+\stopsection
+
+\startsection[title=Extra characters]
+
+In one of our projects we need a small (high) minus and here we discuss
+one way of achieving this. An option is to define a new character
+and use a font feature to add it, as in:
+
+\starttyping
+\startluacode
+ local function addextraminus(tfmdata)
+ fonts.helpers.addprivate(tfmdata, "smallminus", ... ) -- see below
+ fonts.helpers.addprivate(tfmdata, "highminus", ... ) -- see below
+ end
+ fonts.constructors.newfeatures.otf.register {
+ name = "extraminus",
+ description = "extra minus symbols",
+ default = true,
+ manipulators = {
+ base = addextraminus,
+ node = addextraminus,
+ }
+ }
+\stopluacode
+\stoptyping
+
+However, why make it an option when we can just add it to any font. So,
+we can end up with just:
+
+\typebuffer[extraminus] % already defined before loading fonts
+
+It is important to do this before fonts get loaded. Next we need to decide how to
+access these characters. A straightforward way is:
+
+\startbuffer
+\def\smallminus{\privatechar{smallminus}}
+\def\highminus {\privatechar{highminus}}
+\stopbuffer
+
+\typebuffer \getbuffer
+
+An alternative is:
+
+\starttyping
+\definemathcommand [smallminus] [ord] {\privatechar{smallminus}}
+\definemathcommand [highminus] [ord] {\privatechar{highminus}}
+\stoptyping
+
+but that fails in text mode. So, we can consider:
+
+\starttyping
+\def\smallminus{\mathortext{\mathord{\privatechar{smallminus}}}{\privatechar{smallminus}}}
+\def\highminus {\mathortext{\mathord{\privatechar {highminus}}}{\privatechar {highminus}}}
+\stoptyping
+
+or more compact
+
+\starttyping
+\def\smallminus{\mathortext\mathord\firstofoneargument{\privatechar{smallminus}}}
+\def\highminus {\mathortext\mathord\firstofoneargument{\privatechar {highminus}}}
+\stoptyping
+
+What method you choose depends on usage. With the first, simple definitions we
+get this:
+
+\startbuffer
+[\getprivateslot{smallminus}] [\getprivatechar{smallminus}] [\smallminus] $[\smallminus]$\par
+[\getprivateslot {highminus}] [\getprivatechar {highminus}] [\highminus ] $[\highminus ]$\par
+\stopbuffer
+
+\typebuffer \getbuffer
+
+Because we are fully expandable we can even use this in:
+
+\startbuffer
+\bTABLE[aligncharacter=yes,alignmentcharacter={text->\smallminus}]
+ \bTR \bTD \mathminus100\smallminus00+ \eTD \eTR
+ \bTR \bTD 100\smallminus00 \eTD \eTR
+ \bTR \bTD \mathminus 99\smallminus00+ \eTD \eTR
+ \bTR \bTD \mathminus 99\smallminus00 \eTD \eTR
+ \bTR \bTD 100\highminus \eTD \eTR
+\eTABLE
+\stopbuffer
+
+\typebuffer
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+With the other definitions the alignment would not work. If you need both then
+you can define different commands for text and math.
+
+\stopsection
+
+\startsection[title=Tabular numbers]
+
+Some font features are meant to be used in controlled situations. An example is
+the \type {tnum} feature that triggers so called \quote {tabular figures} meaning
+numbers that have equal widths. Its opposite feature is \type {lnum} or lining
+figures. We have two predefined \CONTEXT\ font features for this:
+
+\starttyping
+\definefontfeature [inlinenumbers] [lnum=yes,tnum=no]
+\definefontfeature [tabularnumbers] [tnum=yes,lnum=no]
+\stoptyping
+
+Some mechanisms in \CONTEXT\ had better be aware of this and one of them is the
+alignment mechanism in tables.
+
+\startbuffer[demo]
+\startcombination[before=,after=]
+ \startcontent
+ \switchtobodyfont[pagella]\showglyphs%
+ \disabledirectives[typesetters.characteralign.autofont]%
+ \bTABLE[alignmentcharacter=.,aligncharacter=yes]
+ \bTR \bTD 11.111 \eTD \eTR
+ \bTR \bTD 2.2 \eTD \eTR
+ \bTR \bTD 444.444 \eTD \eTR
+ \eTABLE
+ \enabledirectives[typesetters.characteralign.autofont]%
+ \stopcontent
+ \startcaption
+ \small manual \type {tnum}
+ \stopcaption
+ \startcontent
+ \switchtobodyfont[pagella]\showglyphs%
+ \bTABLE[alignmentcharacter=.,aligncharacter=yes]
+ \bTR \bTD 11.111 \eTD \eTR
+ \bTR \bTD 2.2 \eTD \eTR
+ \bTR \bTD 444.444 \eTD \eTR
+ \eTABLE
+ \stopcontent
+ \startcaption
+ \small auto \type {tnum}
+ \stopcaption
+\stopcombination
+\stopbuffer
+
+In the following examples we demonstrate how the automatic font adaption makes
+sure that tabular figures are used. The table is defined as:
+
+\typebuffer[demo]
+
+\startbuffer
+\dontleavehmode\hbox to .3\textwidth \bgroup
+ \hss\getbuffer[demo]\hss
+\egroup
+\stopbuffer
+
+In \in {figure}[fig:tabularnumbers] we see what the features do. We use the \type
+{\feature} or \type {\addfeature} macro for this. For the moment this trickery is
+controlled by a directive (beware: enabling them is global).
+
+\startplacefigure[reference=fig:tabularnumbers,title={Tabular numbers}]
+ \startcombination[nx=3,ny=2]
+ {\getbuffer} {\tt\nohyphens default}
+ {\addfeature [inlinenumbers]\getbuffer} {\tt\nohyphens inlinenumbers}
+ {\addfeature [tabularnumbers]\getbuffer} {\tt\nohyphens tabularnumbers}
+ {\addfeature[oldstylenumbers]\getbuffer} {\tt\nohyphens oldstylenumbers}
+ {\addfeature[oldstylenumbers]%
+ \addfeature [inlinenumbers]\getbuffer} {\tt\nohyphens oldstylenumbers\par inlinenumbers}
+ {\addfeature[oldstylenumbers]%
+ \addfeature [tabularnumbers]\getbuffer} {\tt\nohyphens oldstylenumbers\par tabularnumbers}
+ \stopcombination
+\stopplacefigure
+
+\stopsection
+
+\startsection[title=Symbols]
+
+You can access glyphs by name but you need to know that name, for example:
+
+\startbuffer
+\definefontsynonym [bends] [file:manfnt.afm]
+
+\startsymbolset [Dangerous Bends]
+ \definesymbol [dbend] [\resolvedglyphdirect{bends}{n:char_7e}]
+ \definesymbol [lhdbend] [\resolvedglyphdirect{bends}{n:char_7f}]
+\stopsymbolset
+
+\setupsymbolset [Dangerous Bends]
+
+Two dangerous bends: \symbol{dbend} and \symbol{lhdbend}.
+\stopbuffer
+
+\typebuffer
+
+You can best save the fonts you use that way in a place that doesn't get
+overwritten because names can change.
+
+\getbuffer
+
+\stopsection
+
+\startsection[title=Alternative styles]
+
+\startbuffer[demo]
+ \start
+ \getbuffer[setup]
+ \subject{[ {\myslanted myslanted} ] [ {\it it} ] [ {\slanted slanted} ] [ $x=1$ ]}
+ [ {\myslanted myslanted} ] [ {\it it} ] [ {\slanted slanted} ] [ $x=1$ ]
+ \typebuffer[setup]
+ \blackrule[width=\hsize,height=1pt,depth=0pt]
+ \stop
+\stopbuffer
+
+In section heads we want a nested style (e.g.\ italic) to adapt to the main font.
+The following definitions shows how you can influence that process. We use the
+following \type {demo} buffer as sample:
+
+\typebuffer[demo]
+
+\startbuffer
+\blackrule[width=\hsize,height=1pt,depth=0pt]
+
+\startbuffer[setup]
+\setuphead[subject][style=\tfb,before=,after=]
+\definealternativestyle [myslanted] [\it] []
+\stopbuffer
+
+\getbuffer[demo]
+
+\startbuffer[setup]
+\setuphead[subject][style=\tfb,before=,after=]
+\definealternativestyle [myslanted] [\it] [\bi]
+\stopbuffer
+
+\getbuffer[demo]
+
+\startbuffer[setup]
+\setuphead[subject][style=\tfb,before=,after=]
+\definealternativestyle [myslanted] [\it] [\tf]
+\stopbuffer
+
+\getbuffer[demo]
+
+\startbuffer[setup]
+\definealternativestyle [myslanted] [\normalitalicface]
+\setuphead[subject][style=bold,before=,after=]
+\stopbuffer
+
+\getbuffer[demo]
+
+\startbuffer[setup]
+\definealternativestyle [myslanted] [\normalitalicface]
+\setuphead[subject][style=\bfd,before=,after=]
+\stopbuffer
+
+\getbuffer[demo]
+
+\startbuffer[setup]
+\definealternativestyle [myslanted] [\slantedface]
+\setuphead[subject][style=boldface,before=,after=]
+\stopbuffer
+
+\getbuffer[demo]
+\stopbuffer
+
+You can influence the main method of operation with:
+
+\starttyping
+\setupalternativestyles[method=normal]
+\setupalternativestyles[method=auto]
+\stoptyping
+
+\startplacefigure[title={Alternative style methods.},reference=fig:alternativestyle]
+ \startcombination
+ {\setupalternativestyles[method=normal]\scale[width=.45\textwidth]{\framed[width=.85\textwidth,align=normal,frame=off,offset=overlay]{\getbuffer}}} {\type{method=normal}}
+ {\setupalternativestyles [method=auto]\scale[width=.45\textwidth]{\framed[width=.85\textwidth,align=normal,frame=off,offset=overlay]{\getbuffer}}} {\type{method=auto}}
+ \stopcombination
+\stopplacefigure
+
+The result is shown in \in {figure} [fig:alternativestyle]. Relevant commands are:
+
+\starttyping
+\emphasistypeface
+\emphasisboldface
+
+\normaltypeface \typeface
+\normalboldface \boldface
+\normalslantedface \slantedface
+\normalitalicface \italicface
+\swaptypeface \swapface
+\stoptyping
+
+\stopsection
+
+\startsection[title={A virtual hack}]
+
+Here is some virtual trickery. A virtual font is just a font but instead of a
+character being a reference to a slot in a font (often via an index) it
+constructs a glyph from whatever characters, rules, displacements, inline \PDF\
+code, etc. We use them a lot deep down in \CONTEXT. The next example defines two
+characters represented by rules. This definition is about as minimalistic as
+reasonable and demonstrates how we can apply expansion (aka hz) to such a font.
+\footnote {You need \LUATEX\ 1.08 or later for this.} We store the font id (a
+number) in a macro. Watch how we don't refer to a glyph in a font. Because we
+don't specify its type as \type {virtual} we can leave out the \type {font}
+table. After all, we don't refer to real glyphs.
+
+\startbuffer
+\startluacode
+local d = 400000 -- just over 6pt
+local a = font.define {
+ characters = {
+ [string.byte("A")] =
+ {
+ width = d,
+ depth = d,
+ commands = { { "down", d }, { "rule", d, d } },
+ expansion_factor = 1000,
+ },
+ [string.byte("B")] =
+ {
+ width = d,
+ height = d,
+ commands = { { "rule", d, d } },
+ expansion_factor = 500,
+ },
+
+ },
+ parameters = {
+ space = 2*d,
+ space_stretch = d,
+ space_shrink = d,
+ },
+ stretch = 8,
+ shrink = 8,
+ step = 2,
+ name = "foo"
+}
+
+tex.count.scratchcounter = a
+\stopluacode
+
+\edef\MyFontID{\the\scratchcounter}
+\stopbuffer
+
+\typebuffer \getbuffer
+
+% \enabletrackers[*expans*]
+
+\startbuffer
+\startoverlay
+ {\vbox \bgroup
+ \setuptolerance[verytolerant,stretch]
+ \setfontid\MyFontID
+ \dorecurse{5}{ABABABABABABABABABABABABABABABABA }
+ \egroup}
+ {\vbox \bgroup
+ \normaladjustspacing2
+ \middlegray
+ \setuptolerance[verytolerant,stretch]
+ \setfontid\MyFontID
+ \dorecurse{5}{ABABABABABABABABABABABABABABABABA }
+ \egroup}
+\stopoverlay
+\stopbuffer
+
+We test this with some rather low level code and show the result in \in {figure}
+[fig:virtualhack]. Of course you will never define a font this way if only
+because we don't set important parameters and this version is not generic in the
+sense that it scales well. You can find better examples elsewhere in the manual
+and in the distribution.
+
+\typebuffer
+
+\startplacefigure[title={A virtual hack.},reference=fig:virtualhack]
+ \getbuffer
+\stopplacefigure
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/libraries/ecmascript-mkiv.tex b/Master/texmf-dist/doc/context/sources/general/manuals/libraries/ecmascript-mkiv.tex
new file mode 100644
index 00000000000..70350142c03
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/libraries/ecmascript-mkiv.tex
@@ -0,0 +1,420 @@
+% language=us
+
+% author : Hans Hagen
+% copyright : PRAGMA ADE & ConTeXt Development Team
+% license : Creative Commons Attribution ShareAlike 4.0 International
+% reference : pragma-ade.nl | contextgarden.net | texlive (related) distributions
+% origin : the ConTeXt distribution
+%
+% comment : Because this manual is distributed with TeX distributions it comes with a rather
+% liberal license. We try to adapt these documents to upgrades in the (sub)systems
+% that they describe. Using parts of the content otherwise can therefore conflict
+% with existing functionality and we cannot be held responsible for that. Many of
+% the manuals contain characteristic graphics and personal notes or examples that
+% make no sense when used out-of-context.
+%
+% comment : Some chapters might have been published in TugBoat, the NTG Maps, the ConTeXt
+% Group journal or otherwise. Thanks to the editors for corrections. Also thanks
+% to users for testing, feedback and corrections.
+
+% for now:
+
+\usemodule[article-basic]
+\usemodule[abbreviations-smallcaps]
+\usemodule[scite]
+\usemodule[ecmascript]
+
+\definecolor
+ [maincolor]
+ [r=.4]
+
+\definecolor
+ [extracolor]
+ [g=.4]
+
+\setupbodyfont
+ [11pt]
+
+\setuptype
+ [color=maincolor]
+
+% \setuptyping
+% [color=maincolor]
+
+\definefontsynonym
+ [TitlePageMono]
+ [file:lmmonoproplt10-bold*default]
+
+\setuphead
+ [color=maincolor]
+
+\usesymbols
+ [cc]
+
+\setupinteraction
+ [hidden]
+
+\loadfontgoodies[lm]
+
+\startdocument
+ [metadata:author=Hans Hagen,
+ metadata:title=ecmascript in context lmtx,
+ author=Hans Hagen,
+ affiliation=PRAGMA ADE,
+ location=Hasselt NL,
+ title=\ECNASCRIPT\ in \CONTEXT\ \LMTX,
+ support=www.contextgarden.net,
+ website=www.pragma-ade.nl]
+
+\starttext
+
+\startMPpage
+ StartPage;
+
+ fill Page withcolor "darkgreen";
+
+ draw textext.lrt("\tttf ECMA")
+ xsized .75PaperWidth
+ shifted ulcorner (Page enlarged -15mm )
+ withcolor "white" ;
+
+ draw textext.llft("\tttf SCRIPT")
+ xsized .50PaperWidth
+ shifted urcorner (Page enlarged -15mm topenlarged -70mm)
+ withcolor "white" ;
+
+ draw textext.llft("\tttf in context lmtx")
+ xsized .50PaperWidth
+ shifted urcorner (Page enlarged -15mm topenlarged -110mm)
+ withcolor "white" ;
+
+ draw textext.llft("\tttf using the optional mujs library")
+ xsized .50PaperWidth
+ shifted lrcorner (Page enlarged -15mm bottomenlarged -10mm)
+ withcolor "white" ;
+
+ StopPage;
+\stopMPpage
+
+\dontcomplain
+
+% \startsubject[title=Contents]
+%
+% \placelist[section][alternative=a]
+%
+% \stopsubject
+
+\startsection[title=Introduction]
+
+When you use \CONTEXT\ there is no way around noticing that the \LUA\ scripting
+language is an important component. When we progressed from \LUATEX\ to
+\LUAMETATEX\ did didn't change. I like that language a lot! Among the reasons are
+that it reminds me of \PASCAL, that it's clean, fast and well maintained. There
+is no huge infrastructure involved, nor lots of libraries and therefore
+dependencies.
+
+So why bother about another scripting language? One can argue that because of the
+World Wide Web one should use \JAVASCRIPT\ instead. It might make sense from a
+commercial point of view, or for some promotional reason. But that all makes
+little sense in the perspective of \CONTEXT. But, when I was playing with
+optional libraries in \LUAMETATEX,
+
+On and off I wonder if I should spend some time on adding \LUA\ annotation
+support to the open source mupdf viewer. After all, it has some basic
+\JAVASCRIPT\ support (but currently not enough, for instance it lacks control
+over widgets and layers and such.) However, then I noticed that the related
+\JAVASCRIPT\ code was actually an independent library and looking at the header
+files it looked quite a bit like the \LUA\ interface. So, just for the fun of it I
+gave it a try, and when doing so, I realized that having support for \JAVASCRIPT,
+or actually \ECMASCRIPT, because that is what it is, could make users who are
+afraid of \LUA\ willing to play with simple scripting in \CONTEXT. Of course,
+after a while they will figure out that \LUA\ is the real deal.
+
+Therefore, instead of sticking to an experiment, I decided to make support for
+the \type {mujs} library an option. After all, every now and they we need
+something new to play with. But be warned: it's an optional thing. The
+interpreter is not embedded in the binary and is loaded on demand (when present).
+In spite of that performance is quite okay.
+
+\stopsection
+
+\startsection[title=A few examples]
+
+Because the provided interface is pretty limited, a few simple examples will do.
+There are plenty of tutorials on the Internet. The main thing to keep in mind is
+that an \ECMASCRIPT\ interpreter is normally pretty limited when it comes to
+communicating with its environment. For instance, the main application provides
+way to print something (to a console) or read from files. So, commands that
+relate to this are specific for \LUAMETATEX. Before anything can be done you need
+to load the (\type {mujs}) library, which is done with:
+
+\starttyping
+\usemodule[ecmascript]
+\stoptyping
+
+You can write a message to the log (or an output pane or console) with the \type
+{console} function, one that normally is present in a \JAVASCRIPT\ (\ECMASCRIPT)
+environment:
+
+\starttyping
+\ecmacode {console("Example Three!")}
+\stoptyping
+
+Printing something to the \TEX\ engine is done with this command:
+
+\startbuffer
+\ecmacode {texprint("Just a {\\bf short} sentence.")}
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+This produces:
+
+\getbuffer
+
+and is comparable with the \type {tex.print} (which prints lines) function at the
+\LUA\ end. This means that there is also \type {texsprint} (which accumulates
+parts into lines). In practice one will probably always use that one.
+
+When there are two arguments, the first argument has to be a number and sets the
+so called catcode table to be used.
+
+\startbuffer
+\ecmacode {texprint(catcodes.vrb,"Just a {\\bf short} sentence.")}
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+This results in a verbatim print: {\tttf \inlinebuffer} The backslash is just that,
+a backslash and not a trigger for a \TEX\ command.
+
+You can do pretty much everything with these print commands. Take for instance the
+following example:
+
+\startbuffer
+\startecmacode
+ console("We're doing some MetaPost!");
+ texsprint(
+ "\\startMPcode "
+ + 'fill fullsquare xyscaled (6cm,1cm) withcolor "darkred";'
+ + 'fill fullsquare xyscaled (4cm,1cm) withcolor "darkgreen";'
+ + 'fill fullsquare xyscaled (2cm,1cm) withcolor "darkblue";'
+ + "\\stopMPcode "
+ );
+\stopecmacode
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+This produces:
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+in \LUA\ we can do this:
+
+\startbuffer
+\startluacode
+ context.startMPcode()
+ context('fill fullsquare xyscaled (6cm,1cm) withcolor "middlecyan";')
+ context('fill fullsquare xyscaled (4cm,1cm) withcolor "middlemagenta";')
+ context('fill fullsquare xyscaled (2cm,1cm) withcolor "middleyellow";')
+ context.stopMPcode()
+\stopluacode
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+The result is the same but the code to produce it looks more like \CONTEXT, if
+only because way more built in features are provided. It makes no sense to do
+the same with another scripting language.
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+As mentioned, reading from files is to be provided by the main program and indeed
+we do have some basic interface. Actually we delegate all to the \LUA\ end by
+using a callback mechanism but users won't see these details. It suffices to know
+that file lookups are done the same way as in the main program because we use the
+same resolvers. One can (in the spirit of \ECMASCRIPT) open a file by creating a
+new file object. After that one can read from the file and, when done, close it.
+
+\startbuffer
+\startecmacode
+ var f = File("ecmascript-mkiv.tex","r");
+ var l = f.read("*a");
+ f.close();
+ texprint(
+ "This file has "
+ + l.length // or: l.length.toString()
+ + " bytes!"
+ )
+\stopecmacode
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+Which reports that: \quotation {\inlinebuffer} The arguments to the \type {read}
+method are the same as in \LUA, so for instance \type {*a} reads the whole file,
+\type {*l} a single line, and a number will read that many bytes. There is
+currently no support for writing as I see no need for it (yet).
+
+You can load an external file too.
+
+\startluacode
+io.savedata("ecmascript-demo-001.js",[[
+function filesize(name) {
+ var f = File(name,"r");
+ if (f != undefined) {
+ var l = f.read("*a");
+ f.close();
+ return l.length;
+ } else {
+ return 0;
+ }
+}
+]])
+\stopluacode
+
+\startbuffer
+\ecmafile{ecmascript-demo-001.js}
+\stopbuffer
+
+\typebuffer[option=TEX] \getbuffer
+
+This file defines a function:
+
+\typefile{ecmascript-demo-001.js}
+
+We use this as follows:
+
+\startbuffer
+\startecmacode
+ texsprint(
+ "This file has "
+ + filesize("ecmascript-mkiv.tex")
+ + " bytes!"
+ )
+\stopecmacode
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+The result is the same as before: \quotation {\inlinebuffer} but by using a
+predefined function we save ourselves some typing. Actually, a more efficient
+variant is this:
+
+\starttyping
+function filesize(name) {
+ var f = File(name,"r");
+ if (f != undefined) {
+ var l = f.seek("end");
+ f.close();
+ return l;
+ } else {
+ return 0;
+ }
+}
+\stoptyping
+
+As with the \type {read} method, the \type {seek} method behaves the same as
+its \LUA\ counterpart, which is a good reason to have a look at the \LUA\
+manual.
+
+If you want you want also access the \ECMASCRIPT\ interpreter from the \LUA\ end,
+not that it makes much sense, but maybe you have a lot of complex code that you
+don't want to rewrite. Here is an example:
+
+\startbuffer
+\startluacode
+ optional.loaded.mujs.execute [[
+ var MyMax = 10; // an example of persistence
+ ]]
+
+ optional.loaded.mujs.execute [[
+ texsprint("\\startpacked");
+ for (var i = 1; i <= MyMax; i++) {
+ texprint(
+ "Here is some rather dumb math test: "
+ + Math.sqrt(i/MyMax)
+ + "!\\par"
+ );
+ }
+ texsprint("\\stoppacked");
+ ]]
+\stopluacode
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+This assumes that you have loaded the module \type {ecmascript} which does the
+necessary preparations. Watch the different ways to add comment and also watch
+how we need to escape the \CONTEXT\ commands. Of course the syntax of both
+languages is different too.
+
+\getbuffer
+
+For now there is not much more to tell. I might add a few features (and more
+examples). And the low level optional interface is not yet declared stable but as
+we wrap it in higher level commands no one will notice changes at that end.
+
+\stopsection
+
+\startsection[title=Extensions]
+
+To summarize, for printing to \TEX\ we have:
+
+\starttyping
+texsprint([catcodetableid,]string|number)
+\stoptyping
+
+and
+
+\starttyping
+texprint(catcodetableid,]string|number)
+\stoptyping
+
+and for printing to the console:
+
+\starttyping
+console(string|number)
+\stoptyping
+
+A file is opened with:
+
+\starttyping
+var f = File.new(filename[,mode])
+\stoptyping
+
+and the returned file object has the methods:
+
+\starttyping
+var str = f:read([string|number])
+var pos = f:seek(whence[,offset])
+\stoptyping
+
+There is a predefined table \type {catcodes} with sybolic entries
+for:
+
+\starttabulate
+\NC \type {tex} \NC regular \TEX\ catcode regime \NC \NR
+\NC \type {ctx} \NC standard \CONTEXT\ catcode regime \NC \NR
+\NC \type {vrb} \NC verbatim catcode regime \NC \NR
+\NC \type {prt} \NC protected \CONTEXT\ catcode regime \NC \NR
+\stoptabulate
+
+\stopsection
+
+\startsection[title=Colofon]
+
+\starttabulate[|B|p|]
+\NC author \NC \getvariable{document}{author}, \getvariable{document}{affiliation}, \getvariable{document}{location} \NC \NR
+\NC version \NC \currentdate \NC \NR
+\NC website \NC \getvariable{document}{website} \endash\ \getvariable{document}{support} \NC \NR
+\stoptabulate
+
+\stopsection
+
+\stopdocument
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/libraries/libraries-mkiv.tex b/Master/texmf-dist/doc/context/sources/general/manuals/libraries/libraries-mkiv.tex
index 67ca7596618..f1801efc0a0 100644
--- a/Master/texmf-dist/doc/context/sources/general/manuals/libraries/libraries-mkiv.tex
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/libraries/libraries-mkiv.tex
@@ -61,7 +61,7 @@
support=www.contextgarden.net,
website=www.pragma-ade.nl]
-\startluasetups[swiglib]
+\startluasetups[libraries]
context.nohyphens()
for i=1,640 do
context.definedfont { string.formatters["TitlePageMono at %p"](65536*(10+math.random(5))) }
@@ -76,7 +76,7 @@ StartPage ;
fill Page enlarged 1cm withcolor \MPcolor{extracolor} ;
- draw textext("\framed[loffset=2pt,roffset=2pt,frame=off,width=\paperwidth,align={normal,paragraph,verytolerant,stretch}]{\luasetup{swiglib}}")
+ draw textext("\framed[loffset=2pt,roffset=2pt,frame=off,width=\paperwidth,align={normal,paragraph,verytolerant,stretch}]{\luasetup{libraries}}")
xysized (PaperWidth,PaperHeight)
shifted center Page
withcolor .8white ;
@@ -107,6 +107,39 @@ StopPage ;
\startsection[title=Introduction]
+Since we started developing \LUATEX\ several methods have been explored with
+regards to external libraries. Now, before we go into details, it must be said
+that in practice this feature is hardly needed. If someone really needs it, it is
+likely to be in a setting where one can also write some library interface and
+compile \LUATEX\ to suit it. So, what we're talking of here is probably not of
+interest for all of you.
+
+In the perspective of \CONTEXT\ a dependency on a library is not what we have in
+mind when we advocate long term usage (and stability) of a workflow. If you see
+\TEX\ as an independent component but still depend on its use of libraries you
+might consider having a backup plan in case a library is no longer maintained, of
+when it gets replaced by another favourite, as happens. There are several ways to
+use a library, and we mention a few here.
+
+The first one is to use \LUA\ {\em wrapper} libraries that interface to some {\em
+specific} library. This is what you do when you use \LUA\ as stand alone program.
+In that case you depend on someone cooking up an efficient and reliable
+interface. Then you depend on the author or others to provide the binaries. If
+there is only one target platform you can wonder if you like that additional
+dependency. Another aspect to keep in mind is that such a wrapper library has to
+match both the used library and the version of \LUA\ that you use. When we use
+this method in \LUATEX, one also has also to make sure that the \LUATEX\ binary
+is compiled in a way that permits loading (this has to do with exposing symbols
+that need a runtime binding).
+
+Because this didn't work out well in practice, already before version 1.0 showed
+up we explored a flexible way to create libraries suited for \LUATEX. This
+project was tagged \quotation {\SWIGLIB}. An infrastructure was created and a
+couple of example library interfaces were provided. However, in practice this
+never catched on and we don't expect distributions to provide libraries in
+addition to the main \LUATEX\ binary, but the framework is there for those who
+want to play with it.
+
Not long after we released \LUATEX\ 1.0, we started experimenting a bit more with
so called foreign function interface: \FFI. Originally that interface to external
libraries was only available in \LUAJITTEX, but a good and compatible alternative
@@ -115,39 +148,43 @@ to know how it works, as long as it works. It means that in addition to \SWIGLIB
we have a method that doesn't demand compilation as it uses normal (public)
libraries.
-Of course one needs to make sure that the right version of a library is used.
-And, as there is the danger of the \API\ having been changed in an incompatible
-way one can wonder if such a dependency is really what one wants. On the other
-hand one can expect \CONTEXT\ to keep up.
-
-Do you really need libraries? For instance does it really make sense to use curl,
-ghostscript or graphicmagic libraries while the command line version is
-(normally) just as efficient and avoids a dependency. This is even more true if
-you realizes that for instance a fetch or conversion only needs to happen once
-per run or in fact only when there is some change in the resource.
-
-On the other hand, when accessing databases one can avoid the often slower
-command line calls and save the hassle of intermediate files. Here efficiency
-wins. Also, when \CONTEXT\ is used in a high performance database backend
-application a distribution and the used libraries are not updated on a daily
-basis.
+A last alternative we mention is to just add the libraries to the \LUATEX\
+engine. In fact, this happens: the \METAPOST\ binary has been provided this way
+for quite a while now. In \LUAMETATEX\ for instance some more math related
+libraries were added, simply because the overhead is not that large and because
+it is a way to extend \METAPOST\ beyond what it provided out of the box.
+
+Before we proceed, ask yourself this questions: \quotation {Do I really need more
+libraries?} For instance does it really make sense to use \CURL, \GHOSTSCRIPT\ or
+\GRAPHICSMAGICK\ libraries while the command line version is (normally) just as
+efficient and avoids a dependency. This is even more true if you realizes that
+for instance a fetch or conversion only needs to happen once per run or in fact
+only when there is some change in the resource. On the other hand, when accessing
+databases one can avoid the often slower command line calls and save the hassle
+of intermediate files. Here efficiency wins. Also, when \CONTEXT\ is used in a
+high performance database backend application a distribution and the used
+libraries are not updated on a daily basis. Anyway, if the answer to the
+question, and it can depend on what variant of \CONTEXT\ you use: \MKIV\ or
+\LMTX, is \quotation {Yes!} then read on.
\stopsection
-\startsection[title=Supported]
+\startsection[title=Usage in \MKIV]
-Apart from some experiments we currently can use \FFI\ interfaced libraries in:
+Although there are (still) some examples of \SWIGLIB\ in \MKIV\ we now assume
+that the \FFI\ interface is used. Apart from some experiments we currently can
+use \FFI\ interfaced libraries in:
\starttabulate[|l|l|l|l|l|]
\FL
-\BC module \BC library \BC windows \BC unix \NC \NR
+\BC module \BC library \BC windows \BC unix \NC \NR
\ML
-\NC util-crl \NC curl \NC libcurl \NC libcurl \NC \NR % todo: client and ffi
-\NC util-sql-imp-ffi \NC mysql \NC libmysql \NC libmysqlclient \NC \NR
-\NC util-sql-imp-sqlite \NC sqlite \NC sqlite3 \NC sqlite3 \NC \NR
-%NC font-phb-imp-library \NC harfbuzz \NC libharfbuzz \NC libharfbuzz \NC \NR % for testing uniscribe (idris fonts)
-%NC \NC ghostscript \NC \NC \NC \NR % only a few experiments
-%NC \NC graphicmagick \NC \NC \NC \NR % only a few experiments
+\NC util-crl \NC curl \NC libcurl \NC libcurl \NC \NR % todo: client and ffi
+\NC util-sql-imp-ffi \NC mysql \NC libmysql \NC libmysqlclient \NC \NR
+\NC util-sql-imp-sqlite \NC sqlite \NC sqlite3 \NC sqlite3 \NC \NR
+%NC font-phb-imp-library \NC harfbuzz \NC libharfbuzz \NC libharfbuzz \NC \NR % old, for testing uniscribe (idris fonts)
+%NC \NC ghostscript \NC \NC \NC \NR % only a few experiments
+%NC \NC graphicsmagick \NC \NC \NC \NR % only a few experiments
\LL
\stoptabulate
@@ -161,7 +198,7 @@ different versions. You can try to play safe and put libraries in the \TEX\ tree
instance on my system they are in:
\starttyping
-c:/data/tex-context/tex/texmf-win64/bin/lib/luatex/lua/whatever/libwhatever.dll
+c:/data/tex-context/tex/texmf-win64/bin/lib/luatex/foo/libfoo.dll
\stoptyping
You can trace where libraries are looked for with:
@@ -179,9 +216,60 @@ trackers.enable("resolvers.ffilib")
The library is first located on one of the valid \TDS\ paths (these are sort of
standardized in \TEX\ distributions) and then using the normal \FFI\ loader.
-As this is all still experimental in \LUATEX\ there is not much more to say about
-it now. Of course this kind of specialized support to a large degree depends on
-the need to use it.
+\stopsection
+
+\startsection[title=Usage in \LMTX]
+
+In \CONTEXT\ \LMTX\ we only have so called \quote {optional} libraries. Actually
+they are just simple interfaces that register themselves in the \type {optional}
+namespace and that can load the real library at runtime. The approach is rather
+lightweight in the sense that compilation of the \LUAMETATEX\ binary doesn't
+depend on additional resources (there is no need to have the libraries on the
+system or their source code to be present) and that at runtime there is no need
+to have the libraries present. This sounds similar to delayed loading of \LUA\
+wrapper libraries but the difference is that there is no potential \LUA\ version
+clash and we also still have one single (relatively small) binary.
+
+This approach works ok because in practice only very few users need a library and
+when they do they have to compile the interface anyway. And, as they compile,
+they can as well add a few lines that are needed to integrate their library to
+the optional mechanism. If you depend on such extensions, you quite certainly
+know what you're doing and need to maintain a code base very careful.
+
+There are some optional libraries present, like:
+
+\starttabulate[|l|l|l|l|l|]
+\FL
+\BC module \BC library \BC windows \BC unix \NC \NR
+\ML
+\NC libs-imp-curl \NC curl \NC libcurl \NC libcurl \NC \NR
+\NC libs-imp-mysql \NC mysql \NC libmysql \NC libmysqlclient \NC \NR
+\NC libs-imp-sqlite \NC sqlite \NC sqlite3 \NC sqlite3 \NC \NR
+%NC libs-imp-postgress \NC libpg \NC libpg \NC libpg \NC \NR % untested
+\NC libs-imp-zint \NC libzint \NC libzint \NC libzint \NC \NR
+\NC libs-imp-mujs \NC libmujs \NC libmujs \NC libmujs \NC \NR
+\NC libs-imp-ghostscript \NC ghostscript \NC gswin64 \NC libgs \NC \NR
+\NC libs-imp-graphicsmagick \NC graphicsmagick \NC several \NC unknown \NC \NR
+%NC font-phb-imp-internal \NC hb \NC libharfbuzz \NC libharfbuzz \NC \NR % maybe, for idris, testing uniscribe
+\LL
+\stoptabulate
+
+It is still to be decided how these will be used. An example of a library that
+can be used out of the box is \ZINT\ for using barcodes: see \type {m-zint.mkxl}
+for an example of its usage. The \SQL\ libraries have their own manuals and have
+been around for a while. They have a common encapsulating infrastructure written
+in \LUA.
+
+It is best to keep libraries in a place where you can keep an eye on them being
+updated, like
+
+\starttyping
+c:/data/tex-context/tex/texmf-win64/bin/lib/luametatex/foo/libfoo.dll
+\stoptyping
+
+You could of course use the ones provided by the system or maybe use symbolic
+links so that you still keep en eye on changes. The \CONTEXT\ distribution might
+at some point provide the libraries that we support.
\stopsection
@@ -191,7 +279,7 @@ the need to use it.
\NC author \NC \getvariable{document}{author}, \getvariable{document}{affiliation}, \getvariable{document}{location} \NC \NR
\NC version \NC \currentdate \NC \NR
\NC website \NC \getvariable{document}{website} \endash\ \getvariable{document}{support} \NC \NR
-\NC comment \NC many thanks to Luigi Scarso for taking care of ffi support in the engines \NC \NR
+\NC comment \NC many thanks to Luigi Scarso for taking care of \FFI\ support in the engines \NC \NR
\stoptabulate
\stopsection
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/lowlevel/lowlevel-boxes.tex b/Master/texmf-dist/doc/context/sources/general/manuals/lowlevel/lowlevel-boxes.tex
new file mode 100644
index 00000000000..986d07b1b61
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/lowlevel/lowlevel-boxes.tex
@@ -0,0 +1,698 @@
+% language=us
+
+% \hfil \hss
+% spread
+
+\environment lowlevel-style
+
+\startdocument
+ [title=boxes,
+ color=middlered]
+
+\startsection[title=Preamble]
+
+\startsubsection[title=Introduction]
+
+An average \CONTEXT\ user will not use the low level box primitives but a basic
+understanding of how \TEX\ works doesn't hurt. In fact, occasionally using a box
+command might bring a solution not easily achieved otherwise, simply because a
+more high level interface can also be in the way.
+
+The best reference is of course The \TeX book so if you're really interested in
+the details you should get a copy of that book. Below I will not go into details
+about all kind of glues, kerns and penalties, just boxes it is.
+
+This explanation will be extended when I feel the need (or users have questions
+that can be answered here).
+
+\stopsubsection
+
+\startsubsection[title=Boxes]
+
+This paragraph of text is made from lines that contain words that themselves
+contain symbolic representations of characters. Each line is wrapped in a so
+called horizontal box and eventually those lines themselves get wrapped in what
+we call a vertical box.
+
+\startbuffer
+\vbox \bgroup
+ \hsize 5cm
+ \raggedright
+ This is a rather narrow paragraph blown up a bit. Here we use a flush left,
+ aka ragged right, approach.
+\egroup
+\stopbuffer
+
+When we expose some details of a paragraph it looks like this:
+
+\startlinecorrection
+\startcombination[2*1]
+ {\scale[width=8cm]{\showmakeup[boxes]\getbuffer}} {}
+ {\scale[width=8cm]{\showmakeup\getbuffer}} {}
+\stopcombination
+\stoplinecorrection
+
+The left only shows the boxes, the variant at the right shows (font) kerns and
+glue too. Because we flush left, there is rather strong right skip glue at the
+right boundary of the box. If font kerns show up depends on the font, not all
+fonts have them (or have only a few). The glyphs themselves are also kind of
+boxed, as their dimensions determine the area that they occupy:
+
+\startlinecorrection
+ \scale[width=\textwidth]{\showglyphs\hbox{This is a rather ...}}
+\stoplinecorrection
+
+But, internally they are not really boxed, as they already are a single quantity.
+The same is true for rules: they are just blobs with dimensions. A box on the
+other hand wraps a linked list of so called nodes: glyphs, kerns, glue,
+penalties, rules, boxes, etc. It is a container with properties like width,
+height, depth and shift.
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title={\TEX\ primitives}]
+
+The box model is reflected in \TEX's user interface but not by that many
+commands, most noticeably \type {\hbox}, \type {\vbox} and \type {\vtop}. Here is
+an example of the first one:
+
+\starttyping[option=TEX]
+\hbox width 10cm{text}
+\hbox width 10cm height 1cm depth 5mm{text}
+text \raise5mm\hbox{text} text
+\stoptyping
+
+The \type {\raise} and \type {\lower} commands behave the same but in opposite
+directions. One could as well have been defined in terms of the other.
+
+\startbuffer
+text \raise 5mm \hbox to 2cm {text}
+text \lower -5mm \hbox to 2cm {text}
+text \raise -5mm \hbox to 2cm {text}
+text \lower 5mm \hbox to 2cm {text}
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+{\dontcomplain\showboxes\getbuffer}
+\stoplinecorrection
+
+A box can be moved to the left or right but, believe it or not, in \CONTEXT\ we
+never use that feature, probably because the consequences for the width are such
+that we can as well use kerns. Here are some examples:
+
+\startbuffer
+text \vbox{\moveleft 5mm \hbox {left}}text !
+text \vbox{\moveright 5mm \hbox{right}}text !
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+{\dontcomplain\getbuffer}
+\stoplinecorrection
+
+\startbuffer
+text \vbox{\moveleft 25mm \hbox {left}}text !
+text \vbox{\moveright 25mm \hbox{right}}text !
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+{\dontcomplain\getbuffer}
+\stoplinecorrection
+
+Code like this will produce a complaint about an underfull box but we can easily
+get around that:
+
+\startbuffer
+text \raise 5mm \hbox to 2cm {\hss text}
+text \lower -5mm \hbox to 2cm {text\hss}
+text \raise -5mm \hbox to 2cm {\hss text}
+text \lower 5mm \hbox to 2cm {text\hss}
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+The \type {\hss} primitive injects a glue that when needed will fill up the
+available space. So, here we force the text to the right or left.
+
+\startlinecorrection
+{\dontcomplain\showboxes\getbuffer}
+\stoplinecorrection
+
+We have three kind of boxes: \type {\hbox}, \type {\vbox} and \type {\vtop}:
+
+\startbuffer
+\hbox{\strut height and depth\strut}
+\vbox{\hsize 4cm \strut height and depth\par and width\strut}
+\vtop{\hsize 4cm \strut height and depth\par and width\strut}
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+A \type {\vbox} aligns at the bottom and a \type {\vtop} at the top. I have added
+some so called struts to enforce a consistent height and depth. A strut is an
+invisible quantity (consider it a black box) that enforces consistent line
+dimensions: height and depth.
+
+
+\startlinecorrection
+{\dontcomplain\hbox{\showstruts\showboxes\getbuffer}}
+\stoplinecorrection
+
+You can store a box in a register but you need to be careful not to use a
+predefined one. If you need a lot of boxes you can reserve some for your own:
+
+\starttyping
+\newbox\MySpecialBox
+\stoptyping
+
+but normally you can do with one of the scratch registers, like 0, 2, 4, 6 or 8,
+for local boxes, and 1, 3, 5, 7 and 9 for global ones. Registers are used like:
+
+\starttyping
+ \setbox0\hbox{here}
+\global\setbox1\hbox{there}
+\stoptyping
+
+In \CONTEXT\ you can also use
+
+\starttyping
+\setbox\scratchbox \hbox{here}
+\setbox\scratchboxone\hbox{here}
+\setbox\scratchboxtwo\hbox{here}
+\stoptyping
+
+and some more. In fact, there are quite some predefined scratch registers (boxes,
+dimensions, counters, etc). Feel free to investigate further.
+
+When a box is stored, you can consult its dimensions with \type {\wd}, \type
+{\ht} and \type {\dp}. You can of course store them for later use.
+
+\starttyping
+\scratchwidth \wd\scratchbox
+\scratchheight\ht\scratchbox
+\scratchdepth \dp\scratchbox
+\scratchtotal \dimexpr\ht\scratchbox+\dp\scratchbox\relax
+\scratchtotal \htdp\scratchbox
+\stoptyping
+
+The last line is \CONTEXT\ specific. You can also set the dimensions
+
+\starttyping
+\wd\scratchbox 10cm
+\ht\scratchbox 10mm
+\dp\scratchbox 5mm
+\stoptyping
+
+So you can cheat! A box is placed with \type {\copy}, which keeps the original
+intact or \type {\box} which just inserts the box and then wipes the register. In
+practice you seldom need a copy, which is more expensive in runtime anyway. Here
+we use copy because it serves the examples.
+
+\starttyping
+\copy\scratchbox
+\box \scratchbox
+\stoptyping
+
+\stopsection
+
+\startsection[title={\ETEX\ primitives}]
+
+The \ETEX\ extensions don't add something relevant for boxes, apart from that you
+can use the expressions mechanism to mess around with their dimensions. There is
+a mechanism for typesetting r2l within a paragraph but that has limited
+capabilities and doesn't change much as it's mostly a way to trick the backend
+into outputting a stretch of text in the other direction. This feature is not
+available in \LUATEX\ because it has an alternative direction mechanism.
+
+\stopsection
+
+\startsection[title={\LUATEX\ primitives}]
+
+The concept of boxes is the same in \LUATEX\ as in its predecessors but there are
+some aspects to keep in mind. When a box is typeset this happens in \LUATEX:
+
+\startitemize[n]
+ \startitem
+ A list of nodes is constructed. In \LUATEX\ this is a double linked
+ list (so that it can easily be manipulated in \LUA) but \TEX\ itself
+ only uses the forward links.
+ \stopitem
+ \startitem
+ That list is hyphenated, that is: so called discretionary nodes are
+ injected. This depends on the language properties of the glyph
+ (character) nodes.
+ \stopitem
+ \startitem
+ Then ligatures are constructed, if the font has such combinations. When
+ this built|-|in mechanism is used, in \CONTEXT\ we speak of base mode.
+ \stopitem
+ \startitem
+ After that inter|-|character kerns are applied, if the font provides
+ them. Again this is a base mode action.
+ \stopitem
+ \startitem
+ Finally the box gets packaged:
+ \startitemize
+ \startitem
+ In the case of a horizontal box, the list is packaged in a
+ hlist node, basically one liner, and its dimensions are calculated
+ and set.
+ \stopitem
+ \startitem
+ In the case of a vertical box, the paragraph is broken into one
+ or more lines, without hyphenation, with optimal hyphenation or
+ in the worst case with so called emergency stretch applied, and
+ the result becomes a vlist node with its dimensions set.
+ \stopitem
+ \stopitemize
+ \stopitem
+\stopitemize
+
+In traditional \TEX\ the first four steps are interwoven but in \LUATEX\ we need
+them split because the step~5 can be overloaded by a callback. In that case steps
+3 and 4 (and maybe 2) are probably also overloaded, especially when you bring
+handling of fonts under \LUA\ control.
+
+New in \LUATEX\ are three packers: \type {\hpack}, \type {\vpack} and \type
+{\tpack}, which are companions to \type {\hbox}, \type {\vbox} and \type {\vtop}
+but without the callbacks applied. Using them is a bit tricky as you never know
+if a callback should be applied, which, because users can often add their own
+\LUA\ code, is not something predictable.
+
+Another box related extension is direction. There are four possible directions
+but because in \LUAMETATEX\ there are only two. Because this model has been upgraded,
+it will be discusses in the next section. A \CONTEXT\ user is supposed to use the
+official \CONTEXT\ interfaces in order to be downward compatible.
+
+\stopsection
+
+\startsection[title={\LUAMETATEX\ primitives}]
+
+There are two possible directions: left to right (the default) and right to left
+for Hebrew and Arabic. Here is an example that shows how it'd done with low level
+directives:
+
+\startbuffer
+\hbox direction 0 {from left to right}
+\hbox direction 1 {from right to left}
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+A low level direction switch is done with:
+
+\startbuffer
+\hbox direction 0
+ {from left to right \textdirection 1 from right to left}
+\hbox direction 1
+ {from right to left \textdirection 1 from left to right}
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+but actually this is kind of {\em not done} in \CONTEXT, because there you are
+supposed to use the proper direction switches:
+
+\startbuffer
+\naturalhbox {from left to right}
+\reversehbox {from right to left}
+\naturalhbox {from left to right \righttoleft from right to left}
+\reversehbox {from right to left \lefttoright from left to right}
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+Often more is needed to properly support right to left typesetting so using the
+\CONTEXT\ commands is more robust.
+
+In \LUAMETATEX\ the box model has been extended a bit, this as a consequence of
+dropping the vertical directional typesetting, which never worked well. In
+previous sections we discussed the properties width, height and depth and the
+shift resulting from a \type {\raise}, \type {\lower}, \type {\moveleft} and
+\type {\moveright}. Actually, the shift is also used in for instance positioning
+math elements.
+
+The way shifting influences dimensions can be somewhat puzzling. Internally, when
+\TEX\ packages content in a box there are two cases:
+
+\startitemize
+ \startitem
+ When a horizontal box is made, and \typ {height - shift} is larger than the
+ maximum height so far, that delta is taken. When \typ {depth + shift} is
+ larger than the current depth, then that depth is adapted. So, a shift up
+ influences the height and a shift down influences the depth.
+ \stopitem
+ \startitem
+ In the case of vertical packaging, when \typ {width + shift} is larger
+ than the maximum box (line) width so far, that maximum gets bumped. So, a
+ shift to the right can contribute, but a shift to the left cannot result
+ in a negative width. This is also why vertical typesetting, where height
+ and depth are swapped with width, goes wrong: we somehow need to map two
+ properties onto one and conceptually \TEX\ is really set up for
+ horizontal typesetting. (And it's why I decided to just remove it from the
+ engine.)
+ \stopitem
+\stopitemize
+
+This is one of these cases where \TEX\ behaves as expected but it also means that
+there is some limitation to what can be manipulated. Setting the shift using one
+of the four commands has a direct consequence when a box gets packaged which
+happens immediately because the box is an argument to the foursome.
+
+There is in traditional \TEX, probably for good reason, no way to set the shift
+of a box, if only because the effect would normally be none. But in \LUATEX\ we
+can cheat, and therefore, for educational purposed \CONTEXT\ has implements
+some cheats.
+
+We use this sample box:
+
+\startbuffer[demo]
+\setbox\scratchbox\hbox\bgroup
+ \middlegray\vrule width 20mm depth -.5mm height 10mm
+ \hskip-20mm
+ \darkgray \vrule width 20mm height -.5mm depth 5mm
+\egroup
+\stopbuffer
+
+\typebuffer[demo][option=TEX]
+
+When we mess with the shift using the \CONTEXT\ \type {\shiftbox} helper, we see
+no immediate effect. We only get the shift applied when we use another helper,
+\type {\hpackbox}.
+
+\startbuffer
+\hbox\bgroup
+ \showstruts \strut
+ \quad \copy\scratchbox
+ \quad \shiftbox\scratchbox -20mm \copy\scratchbox
+ \quad \hpackbox\scratchbox \box \scratchbox
+ \quad \strut
+\egroup
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+\getbuffer[demo]\getbuffer
+\stoplinecorrection
+
+When instead we use \type {\vpackbox} we get a different result. This time we
+move left.
+
+\startbuffer
+\hbox\bgroup
+ \showstruts \strut
+ \quad \copy\scratchbox
+ \quad \shiftbox\scratchbox -10mm \copy\scratchbox
+ \quad \vpackbox\scratchbox \copy\scratchbox
+ \quad \strut
+\egroup
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+\getbuffer[demo]\getbuffer
+\stoplinecorrection
+
+The shift is set via \LUA\ and the repackaging is also done in \LUA, using the
+low level \type {hpack} and \type {vpack} helpers and these just happen to look
+at the shift when doing their job. At the \TEX\ end this never happens.
+
+This long exploration of shifting serves a purpose: it demonstrates that there is
+not that much direct control over boxes apart from their three dimensions.
+However this was never a real problem as one can just wrap a box in another one
+and use kerns to move the embedded box around. But nevertheless I decided to see
+if the engine can be a bit more helpful, if only because all that extra wrapping
+gives some overhead and complications when we want to manipulate boxes. And of
+course it is also a nice playground.
+
+We start with changing the direction. Changing this property doesn't require
+repackaging because directions are not really dealt with in the frontend. When
+a box is converted to (for instance \PDF) the reversion happens.
+
+\startbuffer
+\setbox\scratchbox\hbox{whatever}
+\the\boxdirection\scratchbox: \copy\scratchbox \crlf
+\boxdirection\scratchbox 1
+\the\boxdirection\scratchbox: \copy\scratchbox
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+Another property that can be queried and set is an attribute. In order to get
+a private attribute we define one.
+
+\startbuffer
+\newattribute\MyAt
+\setbox\scratchbox\hbox attr \MyAt 123 {whatever}
+[\the\boxattr\scratchbox\MyAt]
+\boxattr\scratchbox\MyAt 456
+[\the\boxattr\scratchbox\MyAt]
+[\ifnum\boxattr\scratchbox\MyAt>400 okay\fi]
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+The sum of the height and depth is available too. Because for practical reasons
+setting that property is also needed then, the choice was made to distribute the
+value equally over height and depth.
+
+\startbuffer
+\setbox\scratchbox\hbox {height and depth}
+[\the\ht\scratchbox]
+[\the\dp\scratchbox]
+[\the\boxtotal\scratchbox]
+\boxtotal\scratchbox=20pt
+[\the\ht\scratchbox]
+[\the\dp\scratchbox]
+[\the\boxtotal\scratchbox]
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+We've now arrived to a set of properties that relate to each other. They are
+a bit complex and given the number of possibilities one might need to revert
+to some trial and error: orientations and offsets. As with the dimensions,
+directions and attributes, they are passed as box specification. We start
+with the orientation.
+
+\startbuffer
+\hbox \bgroup \showboxes
+ \hbox orientation 0 {right}
+ \quad \hbox orientation 1 {up}
+ \quad \hbox orientation 2 {left}
+ \quad \hbox orientation 3 {down}
+\egroup
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+When the orientation is set, you can also set an offset. Where shifting around a box
+can have consequences for the dimensions, an offset is virtual. It gets effective
+in the backend, when the contents is converted to some output format.
+
+\startbuffer
+\hbox \bgroup \showboxes
+ \hbox orientation 0 yoffset 10pt {right}
+ \quad \hbox orientation 1 xoffset 10pt {up}
+ \quad \hbox orientation 2 yoffset -10pt {left}
+ \quad \hbox orientation 3 xoffset -10pt {down}
+\egroup
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+The reason that offsets are related to orientation is that we need to know in
+what direction the offsets have to be applied and this binding forces the user to
+think about it. You can also set the offsets using commands.
+
+\startbuffer
+\setbox\scratchbox\hbox{whatever}%
+1 \copy\scratchbox
+2 \boxorientation\scratchbox 2 \copy\scratchbox
+3 \boxxoffset \scratchbox -15pt \copy\scratchbox
+4 \boxyoffset \scratchbox -15pt \copy\scratchbox
+5
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+\ruledhbox{\getbuffer}
+\stoplinecorrection
+
+\startbuffer
+\setbox\scratchboxone\hbox{whatever}%
+\setbox\scratchboxtwo\hbox{whatever}%
+1 \boxxoffset \scratchboxone -15pt \copy\scratchboxone
+2 \boxyoffset \scratchboxone -15pt \copy\scratchboxone
+3 \boxxoffset \scratchboxone -15pt \copy\scratchboxone
+4 \boxyoffset \scratchboxone -15pt \copy\scratchboxone
+5 \boxxmove \scratchboxtwo -15pt \copy\scratchboxtwo
+6 \boxymove \scratchboxtwo -15pt \copy\scratchboxtwo
+7 \boxxmove \scratchboxtwo -15pt \copy\scratchboxtwo
+8 \boxymove \scratchboxtwo -15pt \copy\scratchboxtwo
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+\ruledhbox{\getbuffer}
+\stoplinecorrection
+
+The move commands are provides as convenience and contrary to the offsets they do
+adapt the dimensions. Internally, with the box, we register the orientation and
+the offsets and when you apply these commands multiple times the current values
+get overwritten. But \unknown\ because an orientation can be more complex you
+might not get the effects you expect when the options we discuss next are used.
+The reason is that we store the original dimensions too and these come into play
+when these other options are used: anchoring. So, normally you will apply an
+orientation and offsets once only.
+
+% the next bit is derived from the followingup document
+
+The orientation specifier is actually a three byte number that best can be seen
+hexadecimal (although we stay within the decimal domain). There are three
+components: x|-|anchoring, y|-|anchoring and orientation:
+
+\starttyping
+0x<X><Y><O>
+\stoptyping
+
+or in \TEX\ speak:
+
+\starttyping
+"<X><Y><O>
+\stoptyping
+
+The landscape and seascape variants both sit on top of the baseline while the
+flipped variant has its depth swapped with the height. Although this would be
+enough a bit more control is possible.
+
+The vertical options of the horizontal variants anchor on the baseline, lower
+corner, upper corner or center.
+
+\startbuffer
+\ruledhbox orientation "002 {\TEX} and
+\ruledhbox orientation "012 {\TEX} and
+\ruledhbox orientation "022 {\TEX} and
+\ruledhbox orientation "032 {\TEX}
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+\ruledhbox{\getbuffer}
+\stoplinecorrection
+
+The horizontal options of the horizontal variants anchor in the center, left,
+right, halfway left and halfway right.
+
+\startbuffer
+\ruledhbox orientation "002 {\TEX} and
+\ruledhbox orientation "102 {\TEX} and
+\ruledhbox orientation "202 {\TEX} and
+\ruledhbox orientation "302 {\TEX} and
+\ruledhbox orientation "402 {\TEX}
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+\ruledhbox{\getbuffer}
+\stoplinecorrection
+
+The orientation has consequences for the dimensions so they are dealt with in the
+expected way in constructing lines, paragraphs and pages, but the anchoring is
+virtual, like the offsets. There are two extra variants for orientation zero: on
+top of baseline or below, with dimensions taken into account.
+
+\startbuffer
+\ruledhbox orientation "000 {\TEX} and
+\ruledhbox orientation "004 {\TEX} and
+\ruledhbox orientation "005 {\TEX}
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+\ruledhbox{\getbuffer}
+\stoplinecorrection
+
+The anchoring can look somewhat confusing but you need to keep in mind that it is
+normally only used in very controlled circumstances and not in running text.
+Wrapped in macros users don't see the details. We're talking boxes here, so for
+instance:
+
+\startbuffer
+test\quad
+\hbox orientation 3 \bgroup
+ \strut test\hbox orientation "002 \bgroup\strut test\egroup test%
+\egroup \quad
+\hbox orientation 3 \bgroup
+ \strut test\hbox orientation "002 \bgroup\strut test\egroup test%
+\egroup \quad
+\hbox orientation 3 \bgroup
+ \strut test\hbox orientation "012 \bgroup\strut test\egroup test%
+\egroup \quad
+\hbox orientation 3 \bgroup
+ \strut test\hbox orientation "022 \bgroup\strut test\egroup test%
+\egroup \quad
+\hbox orientation 3 \bgroup
+ \strut test\hbox orientation "032 \bgroup\strut test\egroup test%
+\egroup \quad
+\hbox orientation 3 \bgroup
+ \strut test\hbox orientation "042 \bgroup\strut test\egroup test%
+\egroup
+\quad test
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+\ruledhbox{\getbuffer}
+\stoplinecorrection
+
+\stopsection
+
+\stopdocument
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/lowlevel/lowlevel-conditionals.tex b/Master/texmf-dist/doc/context/sources/general/manuals/lowlevel/lowlevel-conditionals.tex
new file mode 100644
index 00000000000..ea3c9e1a244
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/lowlevel/lowlevel-conditionals.tex
@@ -0,0 +1,1409 @@
+% language=us
+
+\environment lowlevel-style
+
+\startdocument
+ [title=conditionals,
+ color=middleblue]
+
+\startsection[title=Preamble]
+
+\startsubsection[title=Introduction]
+
+You seldom need the low level conditionals because there are quite some so called
+support macros available in \CONTEXT . For instance, when you want to compare two
+values (or more accurate: sequences of tokens), you can do this:
+
+\starttyping[option=TEX]
+\doifelse {foo} {bar} {
+ the same
+} {
+ different
+}
+\stoptyping
+
+But if you look in the \CONTEXT\ code, you will see that often we use primitives
+that start with \type {\if} in low level macros. There are good reasons for this.
+First of all, it looks familiar when you also code in other languages. Another
+reason is performance but that is only true in cases where the snippet of code is
+expanded very often, because \TEX\ is already pretty fast. Using low level \TEX\
+can also be more verbose, which is not always nice in a document source. But, the
+most important reason (for me) is the layout of the code. I often let the look
+and feel of code determine the kind of coding. This also relates to the syntax
+highlighting that I am using, which is consistent for \TEX, \METAPOST, \LUA,
+etc.\ and evolved over decades. If code looks bad, it probably is bad. Of course
+this doesn't mean all my code looks good; you're warned. In general we can say
+that I often use \type {\if...} when coding core macros, and \type {\doifelse...}
+macros in (document) styles and modules.
+
+In the sections below I will discuss the low level conditions in \TEX. For the
+often more convenient \CONTEXT\ wrappers you can consult the source of the system
+and support modules, the wiki and|/|or manuals.
+
+Some of the primitives shown here are only available in \LUATEX, and some only in
+\LUAMETATEX . We could do without them for decades but they were added to these
+engines because of convenience and, more important, because then made for nicer
+code. Of course there's also the fun aspect. This manual is not an invitation to
+use these very low level primitives in your document source. The ones that
+probably make most sense are \type {\ifnum}, \type {\ifdim} and \type {\ifcase}.
+The others are often wrapped into support macros that are more convenient.
+
+In due time I might add more examples and explanations. Also, maybe some more
+tests will show up as part of the \LUAMETATEX\ project.
+
+\stopsubsection
+
+\startsubsection[title={Number and dimensions}]
+
+Numbers and dimensions are basic data types in \TEX. When you enter one, a number
+is just that but a dimension gets a unit. Compare:
+
+\starttyping[option=TEX]
+1234
+1234pt
+\stoptyping
+
+If you also use \METAPOST, you need to be aware of the fact that in that language
+there are not really dimensions. The \type {post} part of the name implies that
+eventually a number becomes a \POSTSCRIPT\ unit which represents a base point (\type
+{bp}) in \TEX. When in \METAPOST\ you entry \type {1234pt} you actually multiply
+\type {1234} by the variable \type {pt}. In \TEX\ on the other hand, a unit like
+\type {pt} is one of the keywords that gets parsed. Internally dimensions are
+also numbers and the unit (keyword) tells the scanner what multiplier to use.
+When that multiplier is one, we're talking of scaled points, with the unit \type
+{sp}.
+
+\startbuffer
+\the\dimexpr 12.34pt \relax
+\the\dimexpr 12.34sp \relax
+\the\dimexpr 12.99sp \relax
+\the\dimexpr 1234sp \relax
+\the\numexpr 1234 \relax
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlines \getbuffer \stoplines
+
+When we serialize a dimension it always shows the dimension in points, unless we
+serialize it as number.
+
+\startbuffer
+\scratchdimen1234sp
+\number\scratchdimen
+\the\scratchdimen
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlines \getbuffer \stoplines
+
+When a number is scanned, the first thing that is taken care of is the sign. In many
+cases, when \TEX\ scans for something specific it will ignore spaces. It will
+happily accept multiple signs:
+
+\startbuffer
+\number +123
+\number +++123
+\number + + + 123
+\number +-+-+123
+\number --123
+\number ---123
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlines \getbuffer \stoplines
+
+Watch how the negation accumulates. The scanner can handle decimal, hexadecimal
+and octal numbers:
+
+\startbuffer
+\number -123
+\number -"123
+\number -'123
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlines \getbuffer \stoplines
+
+A dimension is scanned like a number but this time the scanner checks for upto
+three parts: an either or not signed number, a period and a fraction. Here no
+number means zero, so the next is valid:
+
+\startbuffer
+\the\dimexpr . pt \relax
+\the\dimexpr 1. pt \relax
+\the\dimexpr .1pt \relax
+\the\dimexpr 1.1pt \relax
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlines \getbuffer \stoplines
+
+Again we can use hexadecimal and octal numbers but when these are entered, there
+can be no fractional part.
+
+\startbuffer
+\the\dimexpr 16 pt \relax
+\the\dimexpr "10 pt \relax
+\the\dimexpr '20 pt \relax
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlines \getbuffer \stoplines
+
+The reason for discussing numbers and dimensions here is that there are cases where
+when \TEX\ expects a number it will also accept a dimension. It is good to know that
+for instance a macro defined with \type {\chardef} or \type {\mathchardef} also is
+treated as a number. Even normal characters can be numbers, when prefixed by a \type
+{`} (backtick).
+
+The maximum number in \TEX\ is 2147483647 so we can do this:
+
+\starttyping[option=TEX]
+\scratchcounter2147483647
+\stoptyping
+
+but not this
+
+\starttyping[option=TEX]
+\scratchcounter2147483648
+\stoptyping
+
+as it will trigger an error. A dimension can be positive and negative so there we
+can do at most:
+
+\starttyping[option=TEX]
+\scratchdimen 1073741823sp
+\stoptyping
+
+\startbuffer
+\scratchdimen1073741823sp
+\number\scratchdimen
+\the\scratchdimen
+\scratchdimen16383.99998pt
+\number\scratchdimen
+\the\scratchdimen
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlines
+\getbuffer
+\stoplines
+
+We can also do this:
+
+\startbuffer
+\scratchdimen16383.99999pt
+\number\scratchdimen
+\the\scratchdimen
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlines
+\getbuffer
+\stoplines
+
+but the next one will fail:
+
+\starttyping[option=TEX]
+\scratchdimen16383.9999999pt
+\stoptyping
+
+Just keep in mind that \TEX\ scans both parts as number so the error comes from
+checking if those numbers combine well.
+
+\startbuffer
+\ifdim 16383.99999 pt = 16383.99998 pt the same \else different \fi
+\ifdim 16383.999979 pt = 16383.999980 pt the same \else different \fi
+\ifdim 16383.999987 pt = 16383.999991 pt the same \else different \fi
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+Watch the difference in dividing, the \type {/} rounds, while the \type {:}
+truncates.
+
+\startlines
+\getbuffer
+\stoplines
+
+You need to be aware of border cases, although in practice they never really
+are a problem:
+
+\startbuffer
+\ifdim \dimexpr16383.99997 pt/2\relax = \dimexpr 16383.99998 pt/2\relax
+ the same \else different
+\fi
+\ifdim \dimexpr16383.99997 pt:2\relax = \dimexpr 16383.99998 pt:2\relax
+ the same \else different
+\fi
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlines
+\getbuffer
+\stoplines
+
+\startbuffer
+\ifdim \dimexpr1.99997 pt/2\relax = \dimexpr 1.99998 pt/2\relax
+ the same \else different
+\fi
+\ifdim \dimexpr1.99997 pt:2\relax = \dimexpr 1.99998 pt:2\relax
+ the same \else different
+\fi
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlines
+\getbuffer
+\stoplines
+
+\startbuffer
+\ifdim \dimexpr1.999999 pt/2\relax = \dimexpr 1.9999995 pt/2\relax
+ the same \else different
+\fi
+\ifdim \dimexpr1.999999 pt:2\relax = \dimexpr 1.9999995 pt:2\relax
+ the same \else different
+\fi
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlines
+\getbuffer
+\stoplines
+
+This last case demonstrates that at some point the digits get dropped (still
+assuming that the fraction is within the maximum permitted) so these numbers then
+are the same. Anyway, this is not different in other programming languages and
+just something you need to be aware of.
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title={\TEX\ primitives}]
+
+\startsubsection[title={\tex{if}}]
+
+I seldom use this one. Internally \TEX\ stores (and thinks) in terms of tokens.
+If you see for instance \type {\def} or \type {\dimen} or \type {\hbox} these all
+become tokens. But characters like \type {A} or {@} also become tokens. In this
+test primitive all non|-|characters are considered to be the same. In the next
+examples this is demonstrated.
+
+\startbuffer
+[\if AB yes\else nop\fi]
+[\if AA yes\else nop\fi]
+[\if CDyes\else nop\fi]
+[\if CCyes\else nop\fi]
+[\if\dimen\font yes\else nop\fi]
+[\if\dimen\font yes\else nop\fi]
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+Watch how spaces after the two characters are kept: \inlinebuffer . This primitive looks
+at the next two tokens but when doing so it expands. Just look at the following:
+
+\startbuffer
+\def\AA{AA}%
+\def\AB{AB}%
+[\if\AA yes\else nop\fi]
+[\if\AB yes\else nop\fi]
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+We get: \inlinebuffer .
+
+% protected macros
+
+\stopsubsection
+
+\startsubsection[title={\tex{ifcat}}]
+
+In \TEX\ characters (in the input) get interpreted according to their so called
+catcodes. The most common are letters (alphabetic) and and other (symbols) but
+for instance the backslash has the property that it starts a command, the dollar
+signs trigger math mode, while the curly braced deal with grouping. If for
+instance either or not the ampersand is special (for instance as column separator
+in tables) depends on the macro package.
+
+\startbuffer
+[\ifcat AB yes\else nop\fi]
+[\ifcat AA yes\else nop\fi]
+[\ifcat CDyes\else nop\fi]
+[\ifcat CCyes\else nop\fi]
+[\ifcat C1yes\else nop\fi]
+[\ifcat\dimen\font yes\else nop\fi]
+[\ifcat\dimen\font yes\else nop\fi]
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+This time we also compare a letter with a number: \inlinebuffer . In that case
+the category codes differ (letter vs other) but in this test comparing the
+letters result in a match. This is a test that is used only once in \CONTEXT\ and
+even that occasion is dubious and will go away.
+
+You can use \type {\noexpand} to prevent expansion:
+
+\startbuffer
+\def\A{A}%
+\let\B B%
+\def\C{D}%
+\let\D D%
+[\ifcat\noexpand\A Ayes\else nop\fi]
+[\ifcat\noexpand\B Byes\else nop\fi]
+[\ifcat\noexpand\C Cyes\else nop\fi]
+[\ifcat\noexpand\C Dyes\else nop\fi]
+[\ifcat\noexpand\D Dyes\else nop\fi]
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+We get: \inlinebuffer, so who still thinks that \TEX\ is easy to understand for a
+novice user?
+
+\stopsubsection
+
+\startsubsection[title={\tex{ifnum}}]
+
+This condition compares its argument with another one, separated by an \type {<},
+\type {=} or \type {>} character.
+
+\starttyping[option=TEX]
+\ifnum\scratchcounter<0
+ less than
+\else\ifnum\scratchcounter>0
+ more than
+\else
+ equal to
+\fi zero
+\stoptyping
+
+This is one of these situations where a dimension can be used instead. In that
+case the dimension is in scaled points.
+
+\starttyping[option=TEX]
+\ifnum\scratchdimen<0
+ less than
+\else\ifnum\scratchdimen>0
+ more than
+\else
+ equal to
+\fi zero
+\stoptyping
+
+Of course this equal treatment of a dimension and number is only true when the
+dimension is a register or box property.
+
+\stopsubsection
+
+\startsection[title={\tex{ifdim}}]
+
+This condition compares one dimension with another one, separated by an \type {<},
+\type {=} or \type {>} sign.
+
+\starttyping[option=TEX]
+\ifdim\scratchdimen<0pt
+ less than
+\else\ifdim\scratchdimen>0pt
+ more than
+\else
+ equal to
+\fi zero
+\stoptyping
+
+While when comparing numbers a dimension is a valid quantity but here you cannot
+mix them: something with a unit is expected.
+
+\stopsubsection
+
+\startsubsection[title={\tex{ifodd}}]
+
+This one can come in handy, although in \CONTEXT\ it is only used in checking for
+an odd of even page number.
+
+\startbuffer
+\scratchdimen 3sp
+\scratchcounter4
+
+\ifodd\scratchdimen very \else not so \fi odd
+\ifodd\scratchcounter very \else not so \fi odd
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+As with the previously discussed \type {\ifnum} you can use a dimension variable
+too, which is then interpreted as representing scaled points. Here we get:
+
+\startlines
+\getbuffer
+\stoplines
+
+\stopsubsection
+
+\startsubsection[title={\tex{ifvmode}}]
+
+This is a rather trivial check. It takes no arguments and just is true when we're
+in vertical mode. Here is an example:
+
+\startbuffer
+\hbox{\ifvmode\else\par\fi\ifvmode v\else h\fi mode}
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+We're always in horizontal mode and issuing a \type {\par} inside a horizontal
+box doesn't change that, so we get: \ruledhbox{\inlinebuffer}.
+
+\stopsubsection
+
+\startsubsection[title={\tex{ifhmode}}]
+
+As with \type {\ifvmode} this one has no argument and just tells if we're in
+vertical mode.
+
+\startbuffer
+\vbox {
+ \noindent \ifhmode h\else v\fi mode
+ \par
+ \ifhmode h\else \noindent v\fi mode
+}
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+You can use it for instance to trigger injection of code, or prevent that some
+content (or command) is done more than once:
+
+\startlinecorrection
+\ruledhbox{\inlinebuffer}
+\stoplinecorrection
+
+\stopsubsection
+
+\startsubsection[title={\tex{ifmmode}}]
+
+Math is something very \TEX\ so naturally you can check if you're in math mode.
+here is an example of using this test:
+
+\starttyping[option=TEX]
+\def\enforcemath#1{\ifmmode#1\else$ #1 $\fi}
+\stoptyping
+
+Of course in reality macros that do such things are more advanced than this one.
+
+\stopsubsection
+
+\startsubsection[title={\tex{ifinner}}]
+
+\startbuffer
+\def\ShowMode
+ {\ifhmode \ifinner inner \fi hmode
+ \else\ifvmode \ifinner inner \fi vmode
+ \else\ifmmode \ifinner inner \fi mmode
+ \else \ifinner inner \fi unset
+ \fi\fi\fi}
+\stopbuffer
+
+\typebuffer[option=TEX] \getbuffer
+
+\startbuffer
+\ShowMode \ShowMode
+
+\vbox{\ShowMode}
+
+\hbox{\ShowMode}
+
+$\ShowMode$
+
+$$\ShowMode$$
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+The first line has two tests, where the first one changes the mode to horizontal
+simply because a text has been typeset. Watch how display math is not inner.
+
+\startpacked
+\startlines
+\getbuffer
+\stoplines
+\stoppacked
+
+By the way, moving the \type {\ifinner} test outside the branches (to the top of
+the macro) won't work because once the word \type {inner} is typeset we're no
+longer in vertical mode, if we were at all.
+
+\stopsubsection
+
+\startsubsection[title={\tex{ifvoid}}]
+
+A box is one of the basic concepts in \TEX. In order to understand this primitive
+we present four cases:
+
+\startbuffer
+\setbox0\hbox{} \ifvoid0 void \else content \fi
+\setbox0\hbox{123} \ifvoid0 void \else content \fi
+\setbox0\hbox{} \box0 \ifvoid0 void \else content \fi
+\setbox0\hbox to 10pt{} \ifvoid0 void \else content \fi
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+In the first case, we have a box which is empty but it's not void. It helps to
+know that internally an hbox is actually an object with a pointer to a linked
+list of nodes. So, the first two can be seen as:
+
+\starttyping
+hlist -> [nothing]
+hlist -> 1 -> 2 -> 3 -> [nothing]
+\stoptyping
+
+but in any case there is a hlist. The third case puts something in a hlist but
+then flushes it. Now we have not even the hlist any more; the box register has
+become void. The last case is a variant on the first. It is an empty box with a
+given width. The outcome of the four lines (with a box flushed in between) is:
+
+\startlines
+\getbuffer
+\stoplines
+
+So, when you want to test if a box is really empty, you need to test also its
+dimensions, which can be up to three tests, depending on your needs.
+
+\startbuffer
+\setbox0\emptybox \ifvoid0 void\else content\fi
+\setbox0\emptybox \wd0=10pt \ifvoid0 void\else content\fi
+\setbox0\hbox to 10pt {} \ifvoid0 void\else content\fi
+\setbox0\hbox {} \wd0=10pt \ifvoid0 void\else content\fi
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+Setting a dimension of a void voix (empty) box doesn't make it less void:
+
+\startlines
+\getbuffer
+\stoplines
+
+\stopsubsection
+
+\startsubsection[title={\tex{ifhbox}}]
+
+This test takes a box number and gives true when it is an hbox.
+
+\stopsubsection
+
+\startsubsection[title={\tex{ifvbox}}]
+
+This test takes a box number and gives true when it is an vbox. Both a \type
+{\vbox} and \type {\vtop} are vboxes, the difference is in the height and depth
+and the baseline. In a \type {\vbox} the last line determines the baseline
+
+\startlinecorrection
+\ruledvbox{vbox or vtop\par vtop or vbox}
+\stoplinecorrection
+
+And in a \type {\vtop} the first line takes control:
+
+\startlinecorrection
+\ruledvtop{vbox or vtop\par vtop or vbox}
+\stoplinecorrection
+
+but, once wrapped, both internally are just vlists.
+
+\stopsubsection
+
+\startsubsection[title={\tex{ifx}}]
+
+This test is actually used a lot in \CONTEXT: it compares two token(list)s:
+
+\startbuffer
+ \ifx a b Y\else N\fi
+ \ifx ab Y\else N\fi
+\def\A {a}\def\B{b}\ifx \A\B Y\else N\fi
+\def\A{aa}\def\B{a}\ifx \A\B Y\else N\fi
+\def\A {a}\def\B{a}\ifx \A\B Y\else N\fi
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+Here the result is: \quotation{\inlinebuffer}. It does not expand the content, if
+you want that you need to use an \type {\edef} to create two (temporary) macros
+that get compared, like in:
+
+\starttyping[option=TEX]
+\edef\TempA{...}\edef\TempB{...}\ifx\TempA\TempB ...\else ...\fi
+\stoptyping
+
+\stopsubsection
+
+\startsubsection[title={\tex{ifeof}}]
+
+This test checks if a the pointer in a given input channel has reached its end.
+It is also true when the file is not present. The argument is a number which
+relates to the \type {\openin} primitive that is used to open files for reading.
+
+\stopsubsection
+
+\startsubsection[title={\tex{iftrue}}]
+
+It does what it says: always true.
+
+\stopsubsection
+
+\startsubsection[title={\tex{iffalse}}]
+
+It does what it says: always false.
+
+\stopsubsection
+
+\startsubsection[title={\tex{ifcase}}]
+
+The general layout of an \type {\ifcase} tests is as follows:
+
+\starttyping[option=TEX]
+\ifcase<number>
+ when zero
+\or
+ when one
+\or
+ when two
+\or
+ ...
+\else
+ when something else
+\fi
+\stoptyping
+
+As in other places a number is a sequence of signs followed by one of more digits
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title={\ETEX\ primitives}]
+
+\startsubsection[title={\tex{ifdefined}}]
+
+This primitive was introduced for checking the existence of a macro (or primitive)
+and with good reason. Say that you want to know if \type {\MyMacro} is defined? One
+way to do that is:
+
+\startbuffer
+\ifx\MyMacro\undefined
+ {\bf undefined indeed}
+\fi
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+This results in: \inlinebuffer , but is this macro really undefined? When \TEX\
+scans your source and sees a the escape character (the forward slash) it will
+grab the next characters and construct a control sequence from it. Then it finds
+out that there is nothing with that name and it will create a hash entry for a
+macro with that name but with no meaning. Because \type {\undefined} is also not
+defined, these two macros have the same meaning and therefore the \type {\ifx} is
+true. Imagine that you do this many times, with different macro names, then your
+hash can fill up. Also, when a user defined \type {\undefined} you're suddenly
+get a different outcome.
+
+In order to catch the last problem there is the option to test directly:
+
+\startbuffer
+\ifdefined\MyOtherMacro \else
+ {\bf also undefined}
+\fi
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+This (or course) results in: \inlinebuffer, but the macro is still sort of
+defined (with no meaning). The next section shows how to get around this.
+
+\stopsubsection
+
+\startsubsection[title={\tex{ifcsname}}]
+
+A macro is often defined using a ready made name, as in:
+
+\starttyping[option=TEX]
+\def\OhYes{yes}
+\stoptyping
+
+The name is made from characters with catcode letter which means that you cannot
+use for instance digits or underscores unless you also give these characters that
+catcode, which is not that handy in a document. You can however use \type
+{\csname} to define a control sequence with any character in the name, like:
+
+\starttyping[option=TEX]
+\expandafter\def\csname Oh Yes : 1\endcsname{yes}
+\stoptyping
+
+Later on you can get this one with \type {\csname}:
+
+\starttyping[option=TEX]
+\csname Oh Yes : 1\endcsname
+\stoptyping
+
+However, if you say:
+
+\starttyping[option=TEX]
+\csname Oh Yes : 2\endcsname
+\stoptyping
+
+you won't get some result, nor a message about an undefined control sequence, but
+the name triggers a define anyway, this time not with no meaning (undefined) but
+as equivalent to \type {\relax}, which is why
+
+\starttyping[option=TEX]
+\expandafter\ifx\csname Oh Yes : 2\endcsname\relax
+ {\bf relaxed indeed}
+\fi
+\stoptyping
+
+is the way to test its existence. As with the test in the previous section,
+this can deplete the hash when you do lots of such tests. The way out of this
+is:
+
+\starttyping[option=TEX]
+\ifcsname Oh Yes : 2\endcsname \else
+ {\bf unknown indeed}
+\fi
+\stoptyping
+
+This time there is no hash entry created and therefore there is not even an
+undefined control sequence.
+
+In \LUATEX\ there is an option to return false in case of a messy expansion
+during this test, and in \LUAMETATEX\ that is default. This means that tests can
+be made quite robust as it is pretty safe to assume that names that make sense
+are constructed from regular characters and not boxes, font switches, etc.
+
+\stopsubsection
+
+\startsubsection[title={\tex{iffontchar}}]
+
+This test was also part of the \ETEX\ extensions and it can be used to see if
+a font has a character.
+
+\startbuffer
+\iffontchar\font`A
+ {\em This font has an A!}
+\fi
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+And, as expected, the outcome is: \quotation {\inlinebuffer}. The test takes two
+arguments, the first being a font identifier and the second a character number,
+so the next checks are all valid:
+
+\starttyping[option=TEX]
+\iffontchar\font `A yes\else nop\fi\par
+\iffontchar\nullfont `A yes\else nop\fi\par
+\iffontchar\textfont0`A yes\else nop\fi\par
+\stoptyping
+
+In the perspective of \LUAMETATEX\ I considered also supporting \type {\fontid}
+but it got a bit messy due to the fact that this primitive expands in a different
+way so this extension was rejected.
+
+\stopsubsection
+
+\startsubsection[title={\tex{unless}}]
+
+You can negate the results of a test by using the \type {\unless} prefix, so for
+instance you can replace:
+
+\starttyping[option=TEX]
+\ifdim\scratchdimen=10pt
+ \dosomething
+\else\ifdim\scratchdimen<10pt
+ \dosomething
+\fi\fi
+\stoptyping
+
+by:
+
+\starttyping[option=TEX]
+\unless\ifdim\scratchdimen>10pt
+ \dosomething
+\fi
+\stoptyping
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title={\LUATEX\ primitives}]
+
+\startsubsection[title={\tex{ifincsname}}]
+
+As it had no real practical usage uit might get dropped in \LUAMETATEX, so it
+will not be discussed here.
+
+\stopsubsection
+
+\startsubsection[title={\tex{ifprimitive}}]
+
+As it had no real practical usage due to limitations, this one is not available
+in \LUAMETATEX\ so it will not be discussed here.
+
+\stopsubsection
+
+\startsubsection[title={\tex{ifabsnum}}]
+
+This test is inherited from \PDFTEX\ and behaves like \type {\ifnum} but first
+turns a negative number into a positive one.
+
+\stopsubsection
+
+\startsubsection[title={\tex{ifabsdim}}]
+
+This test is inherited from \PDFTEX\ and behaves like \type {\ifdim} but first
+turns a negative dimension into a positive one.
+
+\stopsubsection
+
+\startsubsection[title={\tex{ifcondition}}]
+
+This is not really a test but in order to unstand that you need to know how
+\TEX\ internally deals with tests.
+
+\starttyping[option=TEX]
+\ifdimen\scratchdimen>10pt
+ \ifdim\scratchdimen<20pt
+ result a
+ \else
+ result b
+ \fi
+\else
+ result c
+\fi
+\stoptyping
+
+When we end up in the branch of \quotation {result a} we need to skip two \type
+{\else} branches after we're done. The \type {\if..} commands increment a level
+while the \type {\fi} decrements a level. The \type {\else} needs to be skipped
+here. In other cases the true branch needs to be skipped till we end up a the
+right \type {\else}. When doing this skipping, \TEX\ is not interested in what it
+encounters beyond these tokens and this skipping (therefore) goes real fast but
+it does see nested conditions and doesn't interpret grouping related tokens.
+
+A side effect of this is that the next is not working as expected:
+
+\starttyping[option=TEX]
+\def\ifmorethan{\ifdim\scratchdimen>}
+\def\iflessthan{\ifdim\scratchdimen<}
+
+\ifmorethan10pt
+ \iflessthan20pt
+ result a
+ \else
+ result b
+ \fi
+\else
+ result c
+\fi
+\stoptyping
+
+The \type{\iflessthan} macro is not seen as an \type {\if...} so the nesting gets
+messed up. The solution is to fool the scanner in thinking that it is. Say we have:
+
+\startbuffer
+\scratchdimen=25pt
+
+\def\ifmorethan{\ifdim\scratchdimen>}
+\def\iflessthan{\ifdim\scratchdimen<}
+\stopbuffer
+
+\typebuffer[option=TEX] \getbuffer
+
+and:
+
+\startbuffer
+\ifcondition\ifmorethan10pt
+ \ifcondition\iflessthan20pt
+ result a
+ \else
+ result b
+ \fi
+\else
+ result c
+\fi
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+When we expand this snippet we get: \quotation {\inlinebuffer} and no error
+concerning a failure in locating the right \type {\fi's}. So, when scanning the
+\type {\ifcondition} is seen as a valid \type {\if...} but when the condition is
+really expanded it gets ignored and the \type {\ifmorethan} has better come up
+with a match or not.
+
+In this perspective it is also worth mentioning that nesting problems can be
+avoided this way:
+
+\starttyping[option=TEX]
+\def\WhenTrue {something \iftrue ...}
+\def\WhenFalse{something \iffalse ...}
+
+\ifnum\scratchcounter>123
+ \let\next\WhenTrue
+\else
+ \let\next\WhenFalse
+\fi
+\next
+\stoptyping
+
+This trick is mentioned in The \TeX book and can also be found in the plain \TEX\
+format. A variant is this:
+
+\starttyping[option=TEX]
+\ifnum\scratchcounter>123
+ \expandafter\WhenTrue
+\else
+ \expandafter\WhenFalse
+\fi
+\stoptyping
+
+but using \type {\expandafter} can be quite intimidating especially when there
+are multiple in a row. It can also be confusing. Take this: an \type
+{\ifcondition} expects the code that follows to produce a test. So:
+
+\starttyping[option=TEX]
+\def\ifwhatever#1%
+ {\ifdim#1>10pt
+ \expandafter\iftrue
+ \else
+ \expandafter\iffalse
+ \fi}
+
+\ifcondition\ifwhatever{10pt}
+ result a
+\else
+ result b
+\fi
+\stoptyping
+
+This will not work! The reason is in the already mentioned fact that when we end
+up in the greater than \type {10pt} case, the scanner will happily push the \type
+{\iftrue} after the \type {\fi}, which is okay, but when skipping over the \type
+{\else} it sees a nested condition without matching \type {\fi}, which makes ity
+fail. I will spare you a solution with lots of nasty tricks, so here is the clean
+solution using \type {\ifcondition}:
+
+\starttyping[option=TEX]
+\def\truecondition {\iftrue}
+\def\falsecondition{\iffalse}
+
+\def\ifwhatever#1%
+ {\ifdim#1>10pt
+ \expandafter\truecondition
+ \else
+ \expandafter\falsecondition
+ \fi}
+
+\ifcondition\ifwhatever{10pt}
+ result a
+\else
+ result b
+\fi
+\stoptyping
+
+It will be no surprise that the two macros at the top are predefined in \CONTEXT.
+It might be more of a surprise that at the time of this writing the usage in
+\CONTEXT\ of this \type {\ifcondition} primitive is rather minimal. But that
+might change.
+
+As a further teaser I'll show another simple one,
+
+\startbuffer
+\def\HowOdd#1{\unless\ifnum\numexpr ((#1):2)*2\relax=\numexpr#1\relax}
+
+\ifcondition\HowOdd{1}very \else not so \fi odd
+\ifcondition\HowOdd{2}very \else not so \fi odd
+\ifcondition\HowOdd{3}very \else not so \fi odd
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+This renders:
+
+\startlines
+\getbuffer
+\stoplines
+
+The code demonstrates several tricks. First of all we use \type {\numexpr} which
+permits more complex arguments, like:
+
+\starttyping[option=TEX]
+\ifcondition\HowOdd{4+1}very \else not so \fi odd
+\ifcondition\HowOdd{2\scratchcounter+9}very \else not so \fi odd
+\stoptyping
+
+Another trick is that we use an integer division (the \type {:}) which is an
+operator supported by \LUAMETATEX .
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title={\LUAMETATEX\ primitives}]
+
+\startsubsection[title={\tex{ifcmpnum}}]
+
+This one is part of s set of three tests that all are a variant of a \type
+{\ifcase} test. A simple example of the first test is this:
+
+\starttyping[option=TEX]
+\ifcmpnum 123 345 less \or equal \else more \fi
+\stoptyping
+
+The test scans for two numbers, which of course can be registers or expressions,
+and sets the case value to 0, 1 or 2, which means that you then use the normal
+\type {\or} and \type {\else} primitives for follow up on the test.
+
+\stopsubsection
+
+\startsubsection[title={\tex{ifchknum}}]
+
+This test scans a number and when it's okay sets the case value to 1, and otherwise
+to 2. So you can do the next:
+
+\starttyping[option=TEX]
+\ifchknum 123\or good \else bad \fi
+\ifchknum bad\or good \else bad \fi
+\stoptyping
+
+An error message is suppressed and the first \type {\or} can be seen as a sort of
+recovery token, although in fact we just use the fast scanner mode that comes
+with the \type {\ifcase}: because the result is 1 or 2, we never see invalid
+tokens.
+
+\stopsubsection
+
+\startsubsection[title={\tex{ifnumval}}]
+
+A sort of combination of the previous two is \type {\ifnumval} which checks a
+number but also if it's less, equal or more than zero:
+
+\starttyping[option=TEX]
+\ifnumval 123\or less \or equal \or more \else error \fi
+\ifnumval bad\or less \or equal \or more \else error \fi
+\stoptyping
+
+You can decide to ignore the bad number or do something that makes more sense.
+Often the to be checked value will be the content of a macro or an argument like
+\type {#1}.
+
+\stopsubsection
+
+\startsubsection[title={\tex{ifcmpdim}}]
+
+This test is like \type {\ifcmpnum} but for dimensions.
+
+\stopsubsection
+
+\startsubsection[title={\tex{ifchkdim}}]
+
+This test is like \type {\ifchknum} but for dimensions.
+
+\stopsubsection
+
+\startsubsection[title={\tex{ifdimval}}]
+
+This test is like \type {\ifnumval} but for dimensions.
+
+\stopsubsection
+
+\startsubsection[title={\tex{iftok}}]
+
+Although this test is still experimental it can be used. What happens is that
+two to be compared \quote {things} get scanned for. For each we first gobble
+spaces and \type {\relax} tokens. Then we can have several cases:
+
+\startitemize[n,packed]
+ \startitem
+ When we see a left brace, a list of tokens is scanned upto the
+ matching right brace.
+ \stopitem
+ \startitem
+ When a reference to a token register is seen, that register is taken as
+ value.
+ \stopitem
+ \startitem
+ When a reference to an internal token register is seen, that register is
+ taken as value.
+ \stopitem
+ \startitem
+ When a macro is seen, its definition becomes the to be compared value.
+ \stopitem
+ \startitem
+ When a number is seen, the value of the corresponding register is taken
+ \stopitem
+\stopitemize
+
+An example of the first case is:
+
+\starttyping[option=TEX]
+\iftok {abc} {def}%
+ ...
+\else
+ ...
+\fi
+\stoptyping
+
+The second case goes like this:
+
+\starttyping[option=TEX]
+\iftok\scratchtoksone\scratchtokstwo
+ ...
+\else
+ ...
+\fi
+\stoptyping
+
+Case one and four mixed:
+
+\starttyping[option=TEX]
+\iftok{123}\TempX
+ ...
+\else
+ ...
+\fi
+\stoptyping
+
+The last case is more a catch: it will issue an error when no number is given.
+Eventually that might become a bit more clever (depending on our needs.)
+
+\stopsubsection
+
+\startsubsection[title={\tex{ifcstok}}]
+
+There is a subtle difference between this one and \type {iftok}: spaces
+and \type {\relax} tokens are skipped but nothing gets expanded. So, when
+we arrive at the to be compared \quote {things} we look at what is there,
+as|-|is.
+
+\stopsubsection
+
+\startsubsection[title={\tex{iffrozen}}]
+
+{\em This is an experimental test.} Commands can be defined with the \type
+{\frozen} prefix and this test can be used to check if that has been the case.
+
+\stopsubsection
+
+\startsubsection[title={\tex{ifprotected}}]
+
+Commands can be defined with the \type {\protected} prefix (or in \CONTEXT, for
+historic reasons, with \type {\unexpanded}) and this test can be used to check if
+that has been the case.
+
+\stopsubsection
+
+\startsubsection[title={\tex{ifusercmd}}]
+
+{\em This is an experimental test.} It can be used to see if the command is
+defined at the user level or is a build in one. This one might evolve.
+
+\stopsubsection
+
+\startsubsection[title={\tex{orelse}}]
+
+This it not really a test primitive but it does act that way. Say that we have this:
+
+\starttyping[option=TEX]
+\ifdim\scratchdimen>10pt
+ case 1
+\else\ifdim\scratchdimen<20pt
+ case 2
+\else\ifcount\scratchcounter>10
+ case 3
+\else\ifcount\scratchcounter<20
+ case 4
+\fi\fi\fi\fi
+\stoptyping
+
+A bit nicer looks this:
+
+\starttyping[option=TEX]
+\ifdim\scratchdimen>10pt
+ case 1
+\orelse\ifdim\scratchdimen<20pt
+ case 2
+\orelse\ifcount\scratchcounter>10
+ case 3
+\orelse\ifcount\scratchcounter<20
+ case 4
+\fi
+\stoptyping
+
+We stay at the same level and the only test that cannot be used this way is \type
+{\ifcondition} but that is no real problem. Sometimes a more flat test tree had
+advantages but if you think that it gives better performance then you will be
+disappointed. The fact that we stay at the same level is compensated by a bit
+more parsing, so unless you have millions such cases (or expansions) it might
+make a bit of a difference. As mentioned, I'm a bit sensitive for how code looks so
+that was the main motivation for introducing it.
+
+A rather neat trick is the definition of \type {\quitcondition}:
+
+\starttyping[option=TEX]
+\def\quitcondition{\orelse\iffalse}
+\stoptyping
+
+This permits:
+
+\starttyping[option=TEX]
+\ifdim\scratchdimen>10pt
+ case 1a
+ \quitcondition
+ case 4b
+\fi
+\stoptyping
+
+where, of course, the quitting normally is the result of some intermediate extra
+test. But let me play safe here: beware of side effects.
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title={For the brave}]
+
+\startsubsection[title={Full expansion}]
+
+If you don't understand the following code, don't worry. There is seldom much
+reason to go this complex but obscure \TEX\ code attracts some users so \unknown
+
+When you have a macro that has for instance assignments, and when you expand that
+macro inside an \type {\edef}, these assignments are not actually expanded but
+tokenized. In \LUATEX\ there is a way to immediately apply these assignments and
+that feature can be used to write a fully expandable user test. For instance:
+
+\startbuffer
+\def\truecondition {\iftrue}
+\def\falsecondition{\iffalse}
+
+\def\fontwithidhaschar#1#2%
+ {\immediateassignment\scratchcounter\numexpr\fontid\font\relax
+ \immediateassignment\setfontid\numexpr#1\relax
+ \iffontchar\font\numexpr#2\relax
+ \immediateassignment\setfontid\scratchcounter
+ \expandafter\truecondition
+ \else
+ \expandafter\falsecondition
+ \fi}
+\stopbuffer
+
+\typebuffer[option=TEX] \getbuffer
+
+The \type {\iffontchar} test doesn't handle numeric font id, simply because
+at the time it was added to \ETEX, there was no access to these id's. Now we
+can do:
+
+\startbuffer
+\edef\foo{\fontwithidhaschar{1} {75}yes\else nop\fi} \meaning\foo
+\edef\foo{\fontwithidhaschar{1}{999}yes\else nop\fi} \meaning\foo
+
+[\ifcondition\fontwithidhaschar{1} {75}yes\else nop\fi]
+[\ifcondition\fontwithidhaschar{1}{999}yes\else nop\fi]
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+These result in:
+
+\startlines
+\getbuffer
+\stoplines
+
+If you remove the \type {\immediateassignment} in the definition above then the
+typeset results are still the same but the meanings of \type {\foo} look
+different: they contain the assignments and the test for the character is
+actually done when constructing the content of the \type {\edef}, but for the
+current font. So, basically that test is now useless.
+
+\stopsubsection
+
+\startsubsection[title={User defined if's}]
+
+There is a \type {\newif} macro that defines three other macros:
+
+\starttyping[option=TEX]
+\newif\ifOnMyOwnTerms
+\stoptyping
+
+After this, not only \type {\ifOnMyOwnTerms} is defined, but also:
+
+\starttyping[option=TEX]
+\OnMyOwnTermstrue
+\OnMyOwnTermsfalse
+\stoptyping
+
+These two actually are macros that redefine \type {\ifOnMyOwnTerms} to be either
+equivalent to \type {\iftrue} and \type {\iffalse}. The (often derived from plain
+\TEX) definition of \type {\newif} is a bit if a challenge as it has to deal with
+removing the \type {if} in order to create the two extra macros and also make
+sure that it doesn't get mixed up in a catcode jungle.
+
+In \CONTEXT\ we have a variant:
+
+\starttyping[option=TEX]
+\newconditional\MyConditional
+\stoptyping
+
+that can be used with:
+
+\starttyping[option=TEX]
+\settrue\MyConditional
+\setfalse\MyConditional
+\stoptyping
+
+and tested like:
+
+\starttyping[option=TEX]
+\ifconditional\MyConditional
+ ...
+\else
+ ...
+\fi
+\stoptyping
+
+This one is cheaper on the hash and doesn't need the two extra macros per test.
+The price is the use of \type {\ifconditional}, which is {\em not} to confused
+with \type {\ifcondition} (it has bitten me already a few times).
+
+\stopsubsection
+
+\stopsection
+
+\startsubject[title=Colofon]
+
+\starttabulate
+\NC Author \NC Hans Hagen \NC \NR
+\NC \CONTEXT \NC \contextversion \NC \NR
+\NC \LUAMETATEX \NC \texengineversion \NC \NR
+\NC Support \NC www.pragma-ade.com \NC \NR
+\NC \NC contextgarden.net \NC \NR
+\stoptabulate
+
+\stopsubject
+
+\stopdocument
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/lowlevel/lowlevel-expansion.tex b/Master/texmf-dist/doc/context/sources/general/manuals/lowlevel/lowlevel-expansion.tex
new file mode 100644
index 00000000000..1e2e00a35ad
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/lowlevel/lowlevel-expansion.tex
@@ -0,0 +1,442 @@
+% language=us
+
+\environment lowlevel-style
+
+\startdocument
+ [title=expansion,
+ color=middleyellow]
+
+\startsection[title=Preamble]
+
+% \startsubsection[title=Introduction]
+% \stopsubsection
+
+This short manual demonstrates a couple of properties of the macro language. It
+is not the in|-|depth philosophical expose about macro languages, tokens,
+expansion and such that some \TEX ies like. I prefer to stick to the practical
+aspects.
+
+\stopsection
+
+\startsection[title={\TEX\ primitives}]
+
+The \TEX\ language provides quite some commands and those built in are called
+primitives. User defined commands are called macros. A macro is a shortcut to a
+list of primitives or macro calls. All can be mixed with characters that are to
+be typeset somehow.
+
+\starttyping[option=TEX]
+\def\MyMacro{b}
+
+a\MyMacro c
+\stoptyping
+
+When \TEX\ reads this input the \type {a} gets turned into a glyph node with a
+reference to the current font set and the character \type {a}. Then the parser
+sees a macro call, and it will enter another input level where it expands this
+macro. In this case it sees just an \type {b} and it will give this the same
+treatment as the \type {a}. The macro ends, the input level decrements and the
+\type {c} gets its treatment.
+
+A macro can contain references to macros so in practice the input can go several
+levels down.
+
+\starttyping[option=TEX]
+\def\MyMacroA{ and }
+\def\MyMacroB{1\MyMacroA 2}
+
+a\MyMacroA b
+\stoptyping
+
+When \type {\MyMacroB} is defined, its body gets three so called tokens: the
+character token \type {a} with property \quote {other}, a token that is a
+reference to the macro \type {\MyMacroB}, and a character token \type {2}, also
+with property \quote {other} The meaning of \type {\MyMacroA} became five tokens:
+a reference to a space token, then three character tokens with property \quote
+{letter}, and finally again a space token.
+
+\starttyping[option=TEX]
+\def \MyMacroA{ and }
+\edef\MyMacroB{1\MyMacroA 2}
+
+a\MyMacroA b
+\stoptyping
+
+In the previous example an \type {\edef} is used, where the \type {e} indicates
+expansion. This time the meaning gets expanded. So we get effectively the same
+as
+
+\starttyping[option=TEX]
+\def\MyMacroB{1 and 2}
+\stoptyping
+
+Characters are easy: they just expand, but not all primitives expand to their
+meaning or effect.
+
+\startbuffer
+\def\MyMacroA{\scratchcounter = 1 }
+\def\MyMacroB{\advance\scratchcounter by 1}
+\def\MyMacroC{\the\scratchcounter}
+
+\MyMacroA a
+\MyMacroB b
+\MyMacroB c
+\MyMacroB d
+\MyMacroC
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\scratchcounter0 \getbuffer
+
+\startlines \tt
+\meaning\MyMacroA
+\meaning\MyMacroB
+\meaning\MyMacroC
+\stoplines
+
+Let's assume that \type {\scratchcounter} is zero to start with and use \type
+{\edef's}:
+
+\startbuffer
+\edef\MyMacroA{\scratchcounter = 1 }
+\edef\MyMacroB{\advance\scratchcounter by 1}
+\edef\MyMacroC{\the\scratchcounter}
+
+\MyMacroA a
+\MyMacroB b
+\MyMacroB c
+\MyMacroB d
+\MyMacroC
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\scratchcounter0 \getbuffer
+
+\startlines \tt
+\meaning\MyMacroA
+\meaning\MyMacroB
+\meaning\MyMacroC
+\stoplines
+
+So, this time the third macro has basically its meaning frozen, but we can
+prevent this by applying a \type {\noexpand} when we do this:
+
+\startbuffer
+\edef\MyMacroA{\scratchcounter = 1 }
+\edef\MyMacroB{\advance\scratchcounter by 1}
+\edef\MyMacroC{\noexpand\the\scratchcounter}
+
+\MyMacroA a
+\MyMacroB b
+\MyMacroB c
+\MyMacroB d
+\MyMacroC
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\scratchcounter0 \getbuffer
+
+\startlines \tt
+\meaning\MyMacroA
+\meaning\MyMacroB
+\meaning\MyMacroC
+\stoplines
+
+Of course this is a rather useless example but it serves its purpose: you'd better
+be aware what gets expanded immediately in an \type {\edef}. In most cases you
+only need to worry about \type {\the} and embedded macros (and then of course
+their meanings).
+
+\def\MyShow{\quotation {\strut \inlinebuffer \expandafter \typ \expandafter
+{\the\scratchtoks}\strut}}
+
+You can also store tokens in a so called token register. Here we use a predefined
+scratch register:
+
+\startbuffer
+\def\MyMacroA{ and }
+\def\MyMacroB{1\MyMacroA 2}
+\scratchtoks {\MyMacroA}
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+The content of \type {\scratchtoks} is: \MyShow, so no expansion has happened
+here.
+
+\startbuffer
+\def\MyMacroA{ and }
+\def\MyMacroB{1\MyMacroA 2}
+\scratchtoks \expandafter {\MyMacroA}
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+Now the content of \type {\scratchtoks} is: \MyShow, so this time expansion has
+happened.
+
+\startbuffer
+\def\MyMacroA{ and }
+\def\MyMacroB{1\MyMacroA 2}
+\scratchtoks \expandafter {\MyMacroB}
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+Indeed the macro gets expanded but only one level: \MyShow. Compare this with:
+
+\startbuffer
+\def\MyMacroA{ and }
+\edef\MyMacroB{1\MyMacroA 2}
+\scratchtoks \expandafter {\MyMacroB}
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+The trick is to expand in two steps: \MyShow. Later we will see that other
+engines provide some more expansion tricks. The only way to get a grip on
+expansion is to just play with it.
+
+The \type {\expandafter} primitive expands the token (which can be a macro) after
+the next next one and injects its meaning into the stream. So:
+
+\starttyping[option=TEX]
+\expandafter \MyMacroA \MyMacroB
+\stoptyping
+
+works okay. In a normal document you will never need this kind of hackery: it
+only happens in a bit more complex macros. Here is an example:
+
+\startbuffer[a]
+\scratchcounter 1
+\bgroup
+\advance\scratchcounter 1
+\egroup
+\the\scratchcounter
+\stopbuffer
+
+\typebuffer[a][option=TEX]
+
+\startbuffer[b]
+\scratchcounter 1
+\bgroup
+\advance\scratchcounter 1
+\expandafter
+\egroup
+\the\scratchcounter
+\stopbuffer
+
+\typebuffer[b][option=TEX]
+
+The first one gives \inlinebuffer[a], while the second gives \inlinebuffer[b].
+
+% \let
+% \futurelet
+% \afterassignment
+% \aftergroup
+
+\stopsection
+
+\startsection[title={\ETEX\ primitives}]
+
+In this engine a couple of extensions were added and later on \PDFTEX\ added some
+more. We only discuss a few that relate to expansion. There is however a pitfall
+here. Before \ETEX\ showed up, \CONTEXT\ already had a few mechanism that also
+related to expansion and it used some names for macros that clash with those in
+\ETEX. This is why we will use the \type {\normal} prefix here to indicate the
+primitive.
+
+\startbuffer
+\def\MyMacroA{a}
+\def\MyMacroB{b}
+\normalprotected\def\MyMacroC{c}
+\edef\MyMacroABC{\MyMacroA\MyMacroB\MyMacroC}
+\stopbuffer
+
+\typebuffer[option=TEX] \getbuffer
+
+These macros have the following meanings:
+
+\startlines \tt
+\meaning\MyMacroA
+\meaning\MyMacroB
+\meaning\MyMacroC
+\meaning\MyMacroABC
+\stoplines
+
+In \CONTEXT\ you will use the \type {\unexpanded} prefix instead because that one
+did something similar in older versions of \CONTEXT. As we were early adopters of
+\ETEX, this later became a synonym to the \ETEX\ primitive.
+
+\startbuffer
+\def\MyMacroA{a}
+\def\MyMacroB{b}
+\normalprotected\def\MyMacroC{c}
+\normalexpanded{\scratchtoks{\MyMacroA\MyMacroB\MyMacroC}}
+\stopbuffer
+
+\typebuffer[option=TEX] \getbuffer
+
+Here the wrapper around the token register assignment will expand the three
+macros, unless they are protected, so its content becomes \MyShow. This saves
+either a lot of more complex \type {\expandafter} usage or using an intermediate
+\type {\edef}. In \CONTEXT\ the \type {\expanded} macro does something simpler
+but it doesn't expand the first token as it is meant as a wrapper around a command,
+like:
+
+\starttyping[option=TEX]
+\expanded{\chapter{....}} % a ConTeXt command
+\stoptyping
+
+where we do want to expand the title but not the \type {\chapter} command, not
+that this would happen actually because \type {\chapter} is a protected command.
+
+The counterpart of \type {\normalexpanded} is \type {\normalunexpanded}, as in:
+
+\startbuffer
+\def\MyMacroA{a}
+\def\MyMacroB{b}
+\normalprotected\def\MyMacroC{c}
+\normalexpanded {\scratchtoks
+ {\MyMacroA\normalunexpanded {\MyMacroB}\MyMacroC}}
+\stopbuffer
+
+\typebuffer[option=TEX] \getbuffer
+
+The register now holds \MyShow: three tokens, one character token and two
+macro references.
+
+Tokens can represent characters, primitives, macros or be special entities like
+starting math mode, beginning a group, assigning a dimension to a register, etc.
+Although you can never really get back to the original input, you can come pretty
+close, with:
+
+\startbuffer
+\normaldetokenize{this can $ be anything \bgroup}
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+This (when typeset monospaced) is: {\tt \inlinebuffer}. The detokenizer is like
+\type {\string} applied to each token in its argument. Compare this:
+
+\startbuffer
+\normalexpanded {
+ \normaldetokenize{10pt}
+}
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+We get four tokens: {\tt\inlinebuffer}.
+
+\startbuffer
+\normalexpanded {
+ \string 1\string 0\string p\string t
+}
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+So that was the same operation: {\tt\inlinebuffer}, but in both cases there is a
+subtle thing going on: characters have a catcode which distinguishes them. The
+parser needs to know what makes up a command name and normally that's only
+letters. The next snippet shows these catcodes:
+
+\startbuffer
+\normalexpanded {
+ \noexpand\the\catcode`\string 1 \noexpand\enspace
+ \noexpand\the\catcode`\string 0 \noexpand\enspace
+ \noexpand\the\catcode`\string p \noexpand\enspace
+ \noexpand\the\catcode`\string t \noexpand
+}
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+The result is \quotation {\tt\inlinebuffer}: two characters are marked as \quote
+{letter} and two fall in the \quote {other} category.
+
+\stopsection
+
+\startsection[title={\LUATEX\ primitives}]
+
+This engine adds a little in the expansion arena. First of all it offers a way to
+extend token lists registers
+
+\startbuffer
+\def\MyMacroA{a}
+\def\MyMacroB{b}
+\normalprotected\def\MyMacroC{b}
+\scratchtoks{\MyMacroA\MyMacroB}
+\stopbuffer
+
+\typebuffer[option=TEX] \getbuffer
+
+The result is: \MyShow.
+
+\startbuffer
+\toksapp\scratchtoks{\MyMacroA\MyMacroB}
+\stopbuffer
+
+\typebuffer[option=TEX] \getbuffer
+
+We're now at: \MyShow.
+
+\startbuffer
+\etoksapp\scratchtoks{\MyMacroA\space\MyMacroB\space\MyMacroC}
+\stopbuffer
+
+\typebuffer[option=TEX] \getbuffer
+
+The register has this content: \MyShow, so the additional context got expanded in
+the process, except of course the protected macro \type {\MyMacroC}.
+
+There is a bunch of these combiners: \type {\toksapp} and \type {\tokspre} for
+local appending and prepending, with global companions: \type {\gtoksapp} and
+\type {\gtokspre}, as well as expanding variant: \type {\etoksapp}, \type
+{\etokspre}, \type {\xtoksapp} and \type {\xtokspre}.
+
+There are not beforehand more efficient that using intermediate expanded macros
+or token lists, simply because in the process \TEX\ has to create tokens lists
+too, but sometimes they're just more convenient to use.
+
+A second extension is \type {\immediateassignment} which instead in tokenizing
+the assignment directive applies it right now.
+
+\startbuffer
+\edef\MyMacroA
+ {\scratchcounter 123
+ \noexpand\the\scratchcounter}
+
+\edef\MyMacroB
+ {\immediateassignment\scratchcounter 123
+ \noexpand\the\scratchcounter}
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\getbuffer
+
+These two macros now have the meaning:
+
+\startlines \tt
+\meaning\MyMacroA
+\meaning\MyMacroB
+\stoplines
+
+\stopsection
+
+\startsection[title={\LUAMETATEX\ primitives}]
+
+{\em todo}
+
+% \aftergroups
+
+\stopsection
+
+\stopdocument
+
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/lowlevel/lowlevel-registers.tex b/Master/texmf-dist/doc/context/sources/general/manuals/lowlevel/lowlevel-registers.tex
new file mode 100644
index 00000000000..8ccb0cd3ab6
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/lowlevel/lowlevel-registers.tex
@@ -0,0 +1,251 @@
+% language=us
+
+\environment lowlevel-style
+
+\startdocument
+ [title=registers,
+ color=darkmagenta]
+
+\startsection[title=Preamble]
+
+Registers are sets of variables that are accessed by index and a such resemble
+registers in a processing unit. You can store a quantity in a register, retrieve
+it, and also manipulate it.
+
+There is hardly any need to use them in \CONTEXT\ so we keep it simple.
+
+\stopsection
+
+\startsection[title={\TEX\ primitives}]
+
+There are several categories:
+
+\startitemize
+\startitem
+ Integers (int): in order to be portable (at the time it surfaced) there are only
+ integers and no floats. The only place where \TEX\ uses floats internally is
+ when glue gets effective which happens in the backend.
+\stopitem
+\startitem
+ Dimensions (dimen): internally these are just integers but when they are entered they
+ are sliced into two parts so that we have a fractional part. The internal
+ representation is called a scaled point.
+\stopitem
+\startitem
+ Glue (skip): these are dimensions with a few additional properties: stretch and
+ shrink. Being a compound entity they are stored differently and thereby a bit
+ less efficient than numbers and dimensions.
+\stopitem
+\startitem
+ Math glue (muskip): this is the same as glue but with a unit that adapts to
+ the current math style properties. It's best to think about them as being
+ relative measures.
+\stopitem
+\startitem
+ Token lists (toks): these contain a list of tokens coming from the input
+ or coming from a place where they already have been converted.
+\stopitem
+\stopitemize
+
+The original \TEX\ engine had 256 entries per set. The first ten of each set are
+normally reserved for scratch purposes: the even ones for local use, and the odd
+ones for global usage. On top of that macro packages can reserve some for its own
+use. It was quite easy to reach the maximum but there were tricks around that.
+This limitation is no longer present in the variants in use today.
+
+Let's set a few dimension registers:
+
+\startbuffer[1]
+\dimen 0 = 10 pt
+\dimen2=10pt
+\dimen4 10pt
+\scratchdimen 10pt
+\stopbuffer
+
+\typebuffer[1][option=TEX]
+
+We can serialize them with:
+
+\startbuffer[2]
+\the \dimen0
+\number \dimen2
+\meaning\dimen4
+\meaning\scratchdimen
+\stopbuffer
+
+\typebuffer[2][option=TEX]
+
+The results of these operations are:
+
+\startlines\tt
+\getbuffer[1,2]
+\stoplines
+
+The last two is not really useful but it is what you see when tracing options are
+set. Here \type {\scratchdimen} is a shortcut for a register. This is {\em not} a
+macro but a defined register. The low level \type {\dimendef} is used for this
+but in a macro package you should not use that one but the higher level \type
+{\newdimen} macro that uses it.
+
+\startbuffer[1]
+\newdimen\MyDimenA
+\def \MyDimenB{\dimen999}
+\dimendef\MyDimenC998
+\stopbuffer
+
+\typebuffer[1][option=TEX]
+
+\startbuffer[2]
+\meaning\MyDimenA
+\meaning\MyDimenB
+\meaning\MyDimenC
+\stopbuffer
+
+\typebuffer[2][option=TEX]
+
+Watch the difference:
+
+\startlines\tt
+\getbuffer[1,2]
+\stoplines
+
+The first definition uses a yet free register so you won't get a clash. The
+second one is just a shortcut using a macro and the third one too but again
+direct shortcut. Try to imagine how the second line gets interpreted:
+
+\starttyping[option=TEX]
+\MyDimenA10pt \MyDimenA10.5pt
+\MyDimenB10pt \MyDimenB10.5pt
+\MyDimenC10pt \MyDimenC10.5pt
+\stoptyping
+
+Also try to imagine what messing around with \type {\MyDimenC} will do when we
+also have defined a few hundred extra dimensions with \type {\newdimen}.
+
+In the case of dimensions the \type {\number} primitive will make the register
+serialize as scaled points without unit \type {sp}.
+
+Next we see some of the other registers being assigned:
+
+\starttyping[option=TEX]
+\count 0 = 100
+\skip 0 = 10pt plus 3pt minus 2pt
+\skip 0 = 10pt plus 1fill
+\muskip 0 = 10mu plus 3mu minus 2mu
+\muskip 0 = 10mu minus 1 fil
+\toks 0 = {hundred}
+\stoptyping
+
+When a number is expected, you can use for instance this:
+
+\starttyping[option=TEX]
+\scratchcounter\scratchcounterone
+\stoptyping
+
+Here we use a few predefined scratch registers. You can also do this:
+
+\starttyping[option=TEX]
+\scratchcounter\numexpr\scratchcounterone+\scratchcountertwo\relax
+\stoptyping
+
+There are some quantities that also qualify as number:
+
+\starttyping[option=TEX]
+\chardef\MyChar=123 % refers to character 123 (if present)
+\scratchcounter\MyChar
+\stoptyping
+
+In the past using \type {\chardef} was a way to get around the limited number of
+registers, but it still had (in traditional \TEX) a limitation: you could not go
+beyond 255. The \type {\mathchardef} could fo higher as it also encodes a family
+number and class. This limitation has been lifted in \LUATEX.
+
+A character itself can also be interpreted as number, in which case it has to be
+prefixed with a reverse quote: \type {`}, so:
+
+\startbuffer
+\scratchcounter\numexpr`0+5\relax
+\char\scratchcounter
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+produces \quotation {\inlinebuffer} because the \type {`0} expands into the
+(\ASCII\ and \UTF8) slot {\tt \number`0} which represents the character zero. In
+this case the next makes more sense:
+
+\starttyping[option=TEX]
+\char\numexpr`0+5\relax
+\stoptyping
+
+If you want to know more about all these quantities, \quotation {\TEX\ By Topic}
+provides a good summary of what \TEX\ has to offer, and there is no need to repeat
+it here.
+
+\stopsection
+
+\startsection[title={\ETEX\ primitives}]
+
+Apart from the ability to use expressions, the contribution to registers that
+\ETEX\ brought was that suddenly we could use upto 65K of them, which is more
+than enough. The extra registers were not as efficient as the first 256 because
+they were stored in the hash table, but that was not really a problem. In \OMEGA\
+and later \LUATEX\ regular arrays were used, at the cost of more memory which in
+the meantime has become cheap. As \CONTEXT\ moved to \ETEX\ rather early its
+users never had to worry about it.
+
+\stopsection
+
+\startsection[title={\LUATEX\ primitives}]
+
+The \LUATEX\ engine introduced attributes. These are numeric properties that are
+bound to the nodes that are the result of typesetting operations. They are
+basically like integer registers but when set their values get bound and when
+unset they are kind of invisible.
+
+\startitemize
+\startitem
+ Attribute (attribute): a numeric property that when set becomes part of the
+ current attribute list that gets assigned to nodes.
+\stopitem
+\stopitemize
+
+Attributes can be used to communicate properties to \LUA\ callbacks. There are
+several functions available for setting them and querying them.
+
+\starttyping[option=TEX]
+\attribute999 = 123
+\stoptyping
+
+Using attributes this way is dangerous (of course I can only speak for \CONTEXT)
+because an attribute value might trigger some action in a callback that gives
+unwanted side effects. For convenience \CONTEXT\ provides:
+
+\startbuffer
+\newattribute\MyAttribute
+\stopbuffer
+
+\typebuffer[option=TEX] \getbuffer
+
+Which currently defines \type {\MyAttribute} as {\tt \meaning\MyAttribute} and is
+meant to be used as: \footnote {The low level \type {\attributedef} command is
+rather useless in the perspective of \CONTEXT.}
+
+\starttyping[option=TEX]
+\attribute\MyAttribute = 123
+\stoptyping
+
+Just be aware that defining attributes can have an impact on performance. As you
+cannot access them at the \TEX\ end you seldom need them. If you do you can
+better use the proper more high level definers (not discussed here).
+
+\stopsection
+
+\startsection[title={\LUAMETATEX\ primitives}]
+
+{\em todo}
+
+\stopsection
+
+\stopdocument
+
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/lowlevel/lowlevel-style.tex b/Master/texmf-dist/doc/context/sources/general/manuals/lowlevel/lowlevel-style.tex
new file mode 100644
index 00000000000..ddd9df747ba
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/lowlevel/lowlevel-style.tex
@@ -0,0 +1,104 @@
+% language=us
+
+% I started this series in June 2019 and I bet that it will never be complete or
+% extensive enough. But I'll do my best to make it as useful as possible ConTeXt
+% users out there who like to know about such details. Feel free to ask for more
+% explanations.
+
+\startenvironment lowlevel-style
+
+\usemodule[abbreviations-logos]
+\usemodule[scite]
+
+\setvariables
+ [document]
+ [title=No Title,
+ author=No Author,
+ color=NoColor]
+
+\setupbodyfont
+ [dejavu,11pt]
+
+\setuplayout
+ [width=middle,
+ height=middle,
+ backspace=2cm,
+ topspace=15mm]
+
+\setupwhitespace
+ [big]
+
+\setuphead
+ [chapter]
+ [style=\bfc,
+ color=darkgray]
+
+\setuphead
+ [section]
+ [style=\bfb,
+ %page=right,
+ color=darkgray]
+
+\setuphead
+ [subsection]
+ [style=\bfa,
+ color=darkgray]
+
+\setupfootertexts
+ [section] % [\documentvariable{title}]
+
+\setupfooter
+ [style=bold,
+ color=darkgray]
+
+\startuseMPgraphic{titlepage}
+ fill Page
+ withcolor "\documentvariable{color}" ;
+
+ numeric d ; d := 2mm ;
+
+ picture p ; p := textext.llft("\tex{}")
+ xysized (.1PaperWidth-2d,.1PaperHeight-2d)
+ shifted (.1PaperWidth- d,.1PaperHeight -d)
+ ;
+
+ draw image (
+ for i = 0 step .1 PaperWidth until PaperWidth :
+ for j = 0 step .1 PaperHeight until PaperHeight :
+ draw p shifted (i,j) ;
+ endfor ;
+ endfor ;
+ ) withcolor .5resolvedcolor("middlegray") ;
+
+ draw textext.d("\strut low level")
+ xsized (.8PaperWidth)
+ shifted center topboundary Page
+ shifted -(0,.2PaperHeight)
+ withcolor "white" ;
+ draw textext.d("\strut \TeX")
+ xsized (.4PaperWidth)
+ shifted center topboundary Page
+ shifted -(0,.4PaperHeight)
+ withcolor "white" ;
+ draw textext.d("\strut\documentvariable{title}")
+ ysized 3cm
+ shifted center bottomboundary Page
+ shifted (0,.1PaperHeight)
+ withcolor "white" ;
+\stopuseMPgraphic
+
+\startsetups document:start
+
+ \startMPpage
+ \includeMPgraphic{titlepage} ;
+ \stopMPpage
+
+ \page
+
+ \startsubject[title=Contents]
+ \placelist[section][criterium=previous]
+ \stopsubject
+
+\stopsetups
+
+\stopenvironment
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-arrow.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-arrow.tex
new file mode 100644
index 00000000000..72c9528e8b3
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-arrow.tex
@@ -0,0 +1,166 @@
+% language=us
+
+\environment luametafun-style
+
+\startcomponent luametafun-arrow
+
+\startchapter[title={Arrow}]
+
+Arrows are somewhat complicated because they follow the path, are constructed
+using a pen, have a fill and draw, and need to scale. One problem is that the
+size depends on the pen but the pen normally is only known afterwards.
+
+\startbuffer[1a]
+\startMPcode
+draw lmt_arrow [
+ path = (fullcircle scaled 3cm),
+]
+ withpen pencircle scaled 2mm
+ withcolor "darkred" ;
+\stopMPcode
+\stopbuffer
+
+\startbuffer[1b]
+\startMPcode
+draw lmt_arrow [
+ path = (fullcircle scaled 3cm),
+ length = 8,
+]
+ withpen pencircle scaled 2mm
+ withcolor "darkgreen" ;
+\stopMPcode
+\stopbuffer
+
+\startbuffer[1c]
+\startMPcode
+draw lmt_arrow [
+ path = (fullcircle scaled 3cm rotated 45),
+ pen = (pencircle xscaled 2mm yscaled 1mm rotated 45),
+]
+ withpen pencircle xscaled 2mm yscaled 1mm rotated 45
+ withcolor "darkblue" ;
+\stopMPcode
+\stopbuffer
+
+\startbuffer[1d]
+\startMPcode
+pickup pencircle xscaled 2mm yscaled 1mm rotated 45 ;
+draw lmt_arrow [
+ path = (fullcircle scaled 3cm rotated 45),
+ pen = "auto",
+]
+ withcolor "darkyellow" ;
+\stopMPcode
+\stopbuffer
+
+To some extent \METAFUN\ can help you with this issue. In \in {figure} [arrows:1]
+we see some variants. The definitions are given below:
+
+\typebuffer[1a][option=TEX]
+\typebuffer[1b][option=TEX]
+\typebuffer[1c][option=TEX]
+\typebuffer[1d][option=TEX]
+
+\startplacefigure[reference=arrows:1]
+ \startcombination[4*1]
+ {\getbuffer[1a]} {default}
+ {\getbuffer[1b]} {length}
+ {\getbuffer[1c]} {pen}
+ {\getbuffer[1d]} {auto}
+ \stopcombination
+\stopplacefigure
+
+There are some options that influence the shape of the arrowhead and its
+location on the path. You can for instance ask for two arrowheads:
+
+\startbuffer[3]
+\startMPcode
+ pickup pencircle scaled 1mm ;
+ draw lmt_arrow [
+ pen = "auto",
+ location = "both"
+ path = fullcircle scaled 3cm rotated 90,
+ ] withcolor "darkgreen" ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[3][option=TEX]
+
+\startlinecorrection
+\getbuffer[3]
+\stoplinecorrection
+
+The shape can also be influenced although often this is not that visible:
+
+\startbuffer[4]
+\startMPcode
+ pickup pencircle scaled 1mm ;
+ draw lmt_arrow [
+ kind = "draw",
+ pen = "auto",
+ penscale = 4,
+ location = "middle",
+ alternative = "curved",
+ path = fullcircle scaled 3cm,
+ ] withcolor "darkblue" ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[4][option=TEX]
+
+\startlinecorrection
+\getbuffer[4]
+\stoplinecorrection
+
+The location can also be given as percentage, as this example demonstrates. Watch
+how we draw only arrow heads:
+
+\startbuffer[5]
+\startMPcode
+ pickup pencircle scaled 1mm ;
+ for i = 0 step 5 until 100 :
+ draw lmt_arrow [
+ alternative = "dimpled",
+ pen = "auto",
+ location = "percentage",
+ percentage = i,
+ dimple = (1/5 + i/200),
+ headonly = (i = 0),
+ path = fullcircle scaled 3cm,
+ ] withcolor "darkyellow" ;
+ endfor ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[5][option=TEX]
+
+\startlinecorrection
+\getbuffer[5]
+\stoplinecorrection
+
+The supported parameters are:
+
+\starttabulate[|T|T|T|p|]
+\FL
+\BC name \BC type \BC default \BC comment \NC \NR
+\ML
+\NC path \NC path \NC \NC \NC \NR
+\NC pen \NC path \NC \NC \NC \NR
+\NC \NC string \NC auto \NC \NC \NR
+\NC kind \NC string \NC fill \NC \type {fill} or \type {draw} \NC \NR
+\NC dimple \NC numeric \NC 1/5 \NC \NC \NR
+\NC scale \NC numeric \NC 3/4 \NC \NC \NR
+\NC penscale \NC numeric \NC 3 \NC \NC \NR
+\NC length \NC numeric \NC 4 \NC \NC \NR
+\NC angle \NC numeric \NC 45 \NC \NC \NR
+\NC location \NC string \NC end \NC \type {end}, \type {middle} or \type {both} \NC \NR % middle both
+\NC alternative \NC string \NC normal \NC \type {normal}, \type {dimpled} or \type {curved} \NC \NR
+\NC percentage \NC numeric \NC 50 \NC \NC \NR
+\NC headonly \NC boolean \NC false \NC \NC \NR
+\LL
+\stoptabulate
+
+\stopchapter
+
+\stopcomponent
+
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-axis.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-axis.tex
new file mode 100644
index 00000000000..f9483039ca7
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-axis.tex
@@ -0,0 +1,83 @@
+% language=us
+
+\environment luametafun-style
+
+\startcomponent luametafun-axis
+
+\startchapter[title={Axis}]
+
+The axis macro is the result of one of the first experiments with the key|/|value
+interface in \METAFUN. Let's show a lot in one example:
+
+\startbuffer[1]
+\startMPcode
+ draw lmt_axis [
+ sx = 5mm, sy = 5mm,
+ nx = 20, ny = 10,
+ dx = 5, dy = 2,
+ tx = 10, ty = 10,
+
+ list = {
+ [
+ connect = true,
+ color = "darkred",
+ close = true,
+ points = { (1, 1), (15, 8), (2, 10) },
+ texts = { "segment 1", "segment 2", "segment 3" }
+ ],
+ [
+ connect = true,
+ color = "darkgreen",
+ points = { (2, 2), (4, 1), (10, 3), (16, 8), (19, 2) },
+ labels = { "a", "b", "c", "d", "e" }
+ ],
+ [
+ connect = true,
+ color = "darkblue",
+ close = true,
+ points = { (5, 3), (8, 8), (16, 1) },
+ labels = { "1", "2", "3" }
+ ]
+ },
+
+ ] withpen pencircle scaled 1mm ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[1][option=TEX]
+
+\startplacefigure[reference=axis:1]
+ \getbuffer[1]
+\stopplacefigure
+
+This macro will probably be extended at some point.
+
+\starttabulate[|T|T|T|p|]
+\FL
+\BC name \BC type \BC default \BC comment \NC \NR
+\ML
+\NC nx \NC numeric \NC 1 \NC \NC \NR
+\NC dx \NC numeric \NC 1 \NC \NC \NR
+\NC tx \NC numeric \NC 0 \NC \NC \NR
+\NC sx \NC numeric \NC 1 \NC \NC \NR
+\NC startx \NC numeric \NC 0 \NC \NC \NR
+\NC ny \NC numeric \NC 1 \NC \NC \NR
+\NC dy \NC numeric \NC 1 \NC \NC \NR
+\NC ty \NC numeric \NC 0 \NC \NC \NR
+\NC sy \NC numeric \NC 1 \NC \NC \NR
+\NC starty \NC numeric \NC 0 \NC \NC \NR
+\ML \NC \NC \NR
+\NC samples \NC list \NC \NC \NC \NR
+\NC list \NC list \NC \NC \NC \NR
+\NC connect \NC boolean \NC false \NC \NC \NR
+\NC list \NC list \NC \NC \NC \NR
+\NC close \NC boolean \NC false \NC \NC \NR
+\NC samplecolors \NC list \NC \NC \NC \NR
+\NC axiscolor \NC string \NC \NC \NC \NR
+\NC textcolor \NC string \NC \NC \NC \NR
+\LL
+\stoptabulate
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-chart.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-chart.tex
new file mode 100644
index 00000000000..1bd89d3505f
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-chart.tex
@@ -0,0 +1,441 @@
+% language=us
+
+\environment luametafun-style
+
+\startcomponent luametafun-chart
+
+\startchapter[title={Chart}]
+
+This is another example implementation but it might be handy for simple cases of
+presenting results. Of course one can debate the usefulness of certain ways of
+presenting but here we avoid that discussion. Let's start with a simple pie
+chart (\in {figure} [chart:1]).
+
+\startbuffer[1]
+\startMPcode
+ draw lmt_chart_circle [
+ samples = { { 1, 4, 3, 2, 5, 7, 6 } },
+ percentage = true,
+ trace = true,
+ ] ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[1][option=TEX]
+
+\startplacefigure[reference=chart:1]
+ \getbuffer[1]
+\stopplacefigure
+
+As with all these \LMTX\ extensions, you're invited to play with the parameters.
+in \in {figure} [chart:2] we see a variant that adds labels as well as one that
+has a legend.
+
+\startbuffer[2a]
+\startMPcode
+draw lmt_chart_circle [
+ height = 4cm,
+ samples = { { 1, 4, 3, 2, 5, 7, 6 } },
+ percentage = true,
+ trace = true,
+ labelcolor = "white",
+ labelformat = "@0.1f",
+ labelstyle = "ttxx"
+] ;
+\stopMPcode
+\stopbuffer
+
+The styling of labels and legends can be influenced independently.
+
+\typebuffer[2a][option=TEX]
+
+\startbuffer[2b]
+\startMPcode
+draw lmt_chart_circle [
+ height = 4cm,
+ samples = { { 1, 4, 3, 2, 5, 7, 6 } },
+ percentage = false,
+ trace = true,
+ linewidth = .125mm,
+ originsize = 0,
+ labeloffset = 3cm,
+ labelstyle = "bfxx",
+ legendstyle = "tfxx",
+ legend = {
+ "first", "second", "third", "fourth",
+ "fifth", "sixths", "sevenths"
+ }
+] ;
+
+\stopMPcode
+\stopbuffer
+
+\typebuffer[2b][option=TEX]
+
+\startplacefigure[reference=chart:2]
+ \startcombination
+ {\getbuffer[2a]} {}
+ {\getbuffer[2b]} {}
+ \stopcombination
+\stopplacefigure
+
+A second way of rendering are histograms, and the interface is mostly the same.
+In \in {figure} [chart:3] we see two variants
+
+\startbuffer[3a]
+\startMPcode
+ draw lmt_chart_histogram [
+ samples = { { 1, 4, 3, 2, 5, 7, 6 } },
+ percentage = true,
+ cumulative = true,
+ trace = true,
+ ] ;
+\stopMPcode
+\stopbuffer
+
+\startbuffer[3b]
+\startMPcode
+ draw lmt_chart_histogram [
+ samples = {
+ { 1, 4, 3, 2, 5, 7, 6 },
+ { 1, 2, 3, 4, 5, 6, 7 }
+ },
+ background = "lightgray",
+ trace = true,
+ ] ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[3a][option=TEX]
+
+and one with two datasets:
+
+\typebuffer[3b][option=TEX]
+
+\startplacefigure[reference=chart:3]
+ \startcombination
+ {\getbuffer[3a]} {}
+ {\getbuffer[3b]} {}
+ \stopcombination
+\stopplacefigure
+
+\startbuffer[4]
+\startMPpage[offset=5mm]
+ draw lmt_chart_histogram [
+ samples = {
+ { 1, 4, 3, 2, 5, 7, 6 },
+ { 1, 2, 3, 4, 5, 6, 7 }
+ },
+ percentage = true,
+ cumulative = true,
+ showlabels = false,
+ backgroundcolor = "lightgray",
+ ] ;
+\stopMPpage
+\stopbuffer
+
+A cumulative variant is shown in \in {figure} [chart:4] where we also add a
+background (color).
+
+\typebuffer[4][option=TEX]
+
+\startplacefigure[reference=chart:4]
+ \getbuffer[4]
+\stopplacefigure
+
+A different way of using colors is shown in \in {figure} [chart:5] where each
+sample gets its own (same) color.
+
+\startbuffer[5]
+\startMPcode
+ draw lmt_chart_histogram [
+ samples = {
+ { 1, 4, 3, 2, 5, 7, 6 },
+ { 1, 2, 3, 4, 5, 6, 7 }
+ },
+ percentage = true,
+ cumulative = true,
+ showlabels = false,
+ background = "lightgray",
+ colormode = "local",
+ ] ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[5][option=TEX]
+
+\startplacefigure[reference=chart:5]
+ \getbuffer[5]
+\stopplacefigure
+
+As with pie charts you can add labels and a legend:
+
+\startbuffer[6a]
+\startMPcode
+ draw lmt_chart_histogram [
+ height = 6cm,
+ samples = { { 1, 4, 3, 2, 5, 7, 6 } },
+ percentage = true,
+ cumulative = true,
+ trace = true,
+ labelstyle = "ttxx",
+ labelanchor = "top",
+ labelcolor = "white",
+ backgroundcolor = "middlegray",
+ ] ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[6a][option=TEX]
+
+The previous and next examples are shown in \in {figure} [chart:6]. The height
+specified here concerns the graphic and excludes the labels,
+
+\startbuffer[6b]
+\startMPcode
+ draw lmt_chart_histogram [
+ height = 6cm,
+ width = 10mm,
+ samples = { { 1, 4, 3, 2, 5, 7, 6 } },
+ trace = true,
+ maximum = 7.5,
+ linewidth = 1mm,
+ originsize = 0,
+ labelanchor = "bot",
+ labelcolor = "black"
+ labelstyle = "bfxx"
+ legendstyle = "tfxx",
+ labelstrut = "yes",
+ legend = {
+ "first", "second", "third", "fourth",
+ "fifth", "sixths", "sevenths"
+ }
+ ] ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[6b][option=TEX]
+
+\startplacefigure[reference=chart:6]
+ \startcombination
+ {\getbuffer[6a]} {}
+ {\getbuffer[6b]} {}
+ \stopcombination
+\stopplacefigure
+
+The third category concerns bar charts that run horizontal. Again we see similar
+options driving the rendering (\in {figure} [chart:7]).
+
+\startbuffer[7a]
+\startMPcode
+ draw lmt_chart_bar [
+ samples = { { 1, 4, 3, 2, 5, 7, 6 } },
+ percentage = true,
+ cumulative = true,
+ trace = true,
+ ] ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[7a][option=TEX]
+
+\startbuffer[7b]
+\startMPcode
+ draw lmt_chart_bar [
+ samples = { { 1, 4, 3, 2, 5, 7, 6 } },
+ percentage = true,
+ cumulative = true,
+ showlabels = false,
+ backgroundcolor = "lightgray",
+ ] ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[7b][option=TEX]
+
+Determining the offset of labels is manual work:
+
+\startbuffer[7c]
+\startMPcode
+draw lmt_chart_bar [
+ width = 4cm,
+ height = 5mm,
+ samples = { { 1, 4, 3, 2, 5, 7, 6 } },
+ percentage = true,
+ cumulative = true,
+ trace = true,
+ labelcolor = "white",
+ labelstyle = "ttxx",
+ labelanchor = "rt",
+ labeloffset = .25EmWidth,
+ backgroundcolor = "middlegray",
+] ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[7c][option=TEX]
+
+\startplacefigure[reference=chart:7]
+ \startcombination[3*1]
+ {\getbuffer[7a]} {}
+ {\getbuffer[7b]} {}
+ {\getbuffer[7c]} {}
+ \stopcombination
+\stopplacefigure
+
+Here is one with a legend (rendered in \in {figure} [chart:8]):
+
+\startbuffer[8]
+\startMPcode
+draw lmt_chart_bar [
+ width = 8cm,
+ height = 10mm,
+ samples = { { 1, 4, 3, 2, 5, 7, 6 } },
+ trace = true,
+ maximum = 7.5,
+ linewidth = 1mm,
+ originsize = 0,
+ labelanchor = "lft",
+ labelcolor = "black"
+ labelstyle = "bfxx"
+ legendstyle = "tfxx",
+ labelstrut = "yes",
+ legend = {
+ "first", "second", "third", "fourth",
+ "fifth", "sixths", "sevenths"
+ }
+] ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[8][option=TEX]
+
+\startplacefigure[reference=chart:8]
+ \getbuffer[8]
+\stopplacefigure
+
+You can have labels per dataset as well as draw multiple datasets in
+one image, see \in {figure} [chart:9]:
+
+\startbuffer[9]
+\startMPcode
+ draw lmt_chart_bar [
+ samples = {
+ { 1, 4, 3, 2, 5, 7, 6 },
+ { 3, 2, 5, 7, 5, 6, 1 }
+ },
+ labels = {
+ { "a1", "b1", "c1", "d1", "e1", "f1", "g1" },
+ { "a2", "b2", "c2", "d2", "e2", "f2", "g2" }
+ },
+ labeloffset = -EmWidth,
+ labelanchor = "center",
+ labelstyle = "ttxx",
+ trace = true,
+ center = true,
+ ] ;
+
+ draw lmt_chart_bar [
+ samples = {
+ { 1, 4, 3, 2, 5, 7, 6 }
+ },
+ labels = {
+ { "a", "b", "c", "d", "e", "f", "g" }
+ },
+ labeloffset = -EmWidth,
+ labelanchor = "center",
+ trace = true,
+ center = true,
+ ] shifted (10cm,0) ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[9][option=TEX]
+
+\startplacefigure[reference=chart:9]
+ \getbuffer[9]
+\stopplacefigure
+
+\starttabulate[|T|T|T|p|]
+\FL
+\BC name \BC type \BC default \BC comment \NC \NR
+\ML
+\NC originsize \NC numeric \NC 1mm \NC \NC \NR
+\NC trace \NC boolean \NC false \NC \NC \NR
+\NC showlabels \NC boolean \NC true \NC \NC \NR
+\NC center \NC boolean \NC false \NC \NC \NR
+\ML
+\NC samples \NC list \NC \NC \NC \NR
+\NC
+\NC cumulative \NC boolean \NC false \NC \NC \NR
+\NC percentage \NC boolean \NC false \NC \NC \NR
+\NC maximum \NC numeric \NC 0 \NC \NC \NR
+\NC distance \NC numeric \NC 1mm \NC \NC \NR
+\ML
+\NC labels \NC list \NC \NC \NC \NR
+\NC labelstyle \NC string \NC \NC \NC \NR
+\NC labelformat \NC string \NC \NC \NC \NR
+\NC labelstrut \NC string \NC auto \NC \NC \NR
+\NC labelanchor \NC string \NC \NC \NC \NR
+\NC labeloffset \NC numeric \NC 0 \NC \NC \NR
+\NC labelfraction \NC numeric \NC 0.8 \NC \NC \NR
+\NC labelcolor \NC string \NC \NC \NC \NR
+\ML
+\NC backgroundcolor \NC string \NC \NC \NC \NR
+\NC drawcolor \NC string \NC white \NC \NC \NR
+\NC fillcolors \NC list \NC \NC primary (dark) colors \NC \NR
+\NC colormode \NC string \NC global \NC \NC or \type {local} \NC \NR
+\ML
+\NC linewidth \NC numeric \NC .25mm \NC \NC \NR
+\ML
+\NC legendcolor \NC string \NC \NC \NC \NR
+\NC legendstyle \NC string \NC \NC \NC \NR
+\NC legend \NC list \NC \NC \NC \NR
+\LL
+\stoptabulate
+
+Pie charts have:
+
+\starttabulate[|T|T|]
+\FL
+\BC name \BC default \NC \NR
+\ML
+\NC height \NC 5cm \NC \NR
+\NC width \NC 5mm \NC \NR
+\NC labelanchor \NC \NC \NR
+\NC labeloffset \NC 0 \NC \NR
+\NC labelstrut \NC no \NC \NR
+\LL
+\stoptabulate
+
+Histograms come with:
+
+\starttabulate[|T|T|]
+\FL
+\BC name \BC default \NC \NR
+\ML
+\NC height \NC 5cm \NC \NR
+\NC width \NC 5mm \NC \NR
+\NC labelanchor \NC bot \NC \NR
+\NC labeloffset \NC 1mm \NC \NR
+\NC labelstrut \NC auto \NC \NR
+\LL
+\stoptabulate
+
+Bar charts use:
+
+\starttabulate[|T|T|]
+\FL
+\BC name \BC default \NC \NR
+\ML
+\NC height \NC 5cm \NC \NR
+\NC width \NC 5mm \NC \NR
+\NC labelanchor \NC lft \NC \NR
+\NC labeloffset \NC 1mm \NC \NR
+\NC labelstrut \NC no \NC \NR
+\LL
+\stoptabulate
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-contents.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-contents.tex
new file mode 100644
index 00000000000..73800ba8bb4
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-contents.tex
@@ -0,0 +1,11 @@
+% language=us
+
+\environment luametafun-style
+
+\startcomponent luametafun-contents
+
+\starttitle[title={Contents}]
+ \placelist[chapter]
+\stoptitle
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-contour.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-contour.tex
new file mode 100644
index 00000000000..11eca8b7adc
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-contour.tex
@@ -0,0 +1,771 @@
+% language=us
+
+\environment luametafun-style
+
+\startcomponent luametafun-contour
+
+\startchapter[title={Contour}]
+
+This feature started out as experiment triggered by a request on the mailing
+list. In the end it was a nice exploration of what is possible with a bit of
+\LUA. In a sense it is more subsystem than a simple \METAPOST\ macro because
+quite some \LUA\ code is involved and more might be used in the future. It's part
+of the fun.
+
+A contour is a line through equivalent values $z$ that result from applying a
+function to two variables $x$ and $y$. There is quite a bit of analysis needed
+to get these lines. In \METAFUN\ we currently support three methods for generating
+a colorful background and three for putting lines on top:
+
+One solution is to use the the isolines and isobands methods are described on the
+marching squares page of wikipedia:
+
+\starttyping
+https://en.wikipedia.org/wiki/Marching_squares
+\stoptyping
+
+This method is relative efficient as we don't do much optimization, simply
+because it takes time and the gain is not that much relevant. Because we support
+filling of multiple curves in one go, we get efficient paths anyway without side
+effects that normally can occur from many small paths alongside. In these days of
+multi megabyte movies and sound clips a request of making a \PDF\ file small is kind
+of strange anyway. In practice the penalty is not that large.
+
+As background we can use a bitmap. This method is also quite efficient because we
+use indexed colors which results in a very good compression. We use a simple
+mapping on a range of values.
+
+A third method is derived from the one that is distributed as \CCODE\ source
+file at:
+
+\starttyping
+https://physiology.arizona.edu/people/secomb/contours
+https://github.com/secomb/GreensV4
+\stoptyping
+
+We can create a background image, which uses a sequence of closed curves
+\footnote {I have to figure out how to improve it a bit so that multiple path
+don't get connected.}. It can also provide two variants of lines around the
+contours (we tag them shape and shade). It's all a matter of taste. In the
+meantime I managed to optimize the code a bit and I suppose that when I buy a new
+computer (the code was developed on an 8 year old machine) performance is
+probably acceptable.
+
+In order of useability you can think of isoband (band) with isolines (cell),
+bitmap (bitmap) with isolines (cell) and finally shapes (shape) with edges
+(edge). But let's start with a couple of examples.
+
+\startbuffer[1]
+\startMPcode{doublefun}
+ draw lmt_contour [
+ xmin = 0, xmax = 4*pi, xstep = .05,
+ ymin = -6, ymax = 6, ystep = .05,
+
+ levels = 7,
+ height = 5cm,
+ preamble = "local sin, cos = math.sin, math.cos",
+ function = "cos(x) + sin(y)",
+ background = "bitmap",
+ foreground = "edge",
+ linewidth = 1/2,
+ cache = true,
+ ] ;
+\stopMPcode
+\stopbuffer
+
+\startplacefigure[reference=contour:1]
+ \getbuffer[1]
+\stopplacefigure
+
+\typebuffer[1][option=TEX]
+
+In \in {figure} [contour:1] we see the result. There is a in this case black and
+white image generated and on top of that we see lines. The step determines the
+resolution of the image. In practice using a bitmap is quite okay and also rather
+efficient: we use an indexed colorspace and, as already was mentioned, because
+the number of colors is limited such an image compresses well. A different
+rendering is seen in \in {figure} [contour:2] where we use the shape method for
+the background. That method creates outlines but is much slower, and when you use
+a high resolution (small step) it can take quite a while to identify the shapes.
+This is why we set the cache flag.
+
+\startbuffer[2]
+\startMPcode{doublefun}
+ draw lmt_contour [
+ xmin = 0, xmax = 4*pi, xstep = .10,
+ ymin = -6, ymax = 6, ystep = .10,
+
+ levels = 7,
+ preamble = "local sin, cos = math.sin, math.cos",
+ function = "cos(x) - sin(y)",
+ background = "shape",
+ foreground = "shape",
+ linewidth = 1/2,
+ cache = true,
+ ] ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[2][option=TEX]
+
+\startplacefigure[reference=contour:2]
+ \getbuffer[2]
+\stopplacefigure
+
+We mentioned colorspace but haven't seen any color yet, so let's set some in \in
+{figure} [contour:3]. Two variants are shown: a background \type {shape} with
+foreground \type {shape} and a background \type {bitmap} with a foreground \type
+{edge}. The bitmap renders quite fast, definitely when we compare with the shape,
+while the quality is as good at this size.
+
+\startbuffer[3a]
+\startMPcode{doublefun}
+ draw lmt_contour [
+ xmin = -10, xmax = 10, xstep = .1,
+ ymin = -10, ymax = 10, ystep = .1,
+
+ levels = 10,
+ height = 7cm,
+ color = "shade({1/2,1/2,0},{0,0,1/2})",
+ function = "x^2 + y^2",
+ background = "shape",
+ foreground = "shape",
+ linewidth = 1/2,
+ cache = true,
+ ] xsized .45TextWidth ;
+\stopMPcode
+\stopbuffer
+
+\startbuffer[3b]
+\startMPcode{doublefun}
+ draw lmt_contour [
+ xmin = -10, xmax = 10, xstep = .1,
+ ymin = -10, ymax = 10, ystep = .1,
+
+ levels = 10,
+ height = 7cm,
+ color = "shade({1/2,0,0},{0,0,1/2})",
+ function = "x^2 + y^2",
+ background = "bitmap",
+ foreground = "edge",
+ linewidth = 1/2,
+ cache = true,
+ ] xsized .45TextWidth ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[3a][option=TEX]
+
+\startplacefigure[reference=contour:3]
+ \startcombination
+ {\getbuffer[3a]} {\bf shape}
+ {\getbuffer[3b]} {\bf bitmap}
+ \stopcombination
+\stopplacefigure
+
+We use the \type {doublefun} instance because we need to be sure that we don't
+run into issues with scaled numbers, the default model in \METAPOST. The
+function that gets passed is {\em not} using \METAPOST\ but \LUA, so basically
+you can do very complex things. Here we directly pass code, but you can for
+instance also do this:
+
+\starttyping[option=TEX]
+\startluacode
+ function document.MyContourA(x,y)
+ return x^2 + y^2
+ end
+\stopluacode
+\stoptyping
+
+and then \type {function = "document.MyContourA(x,y)"}. As long as the function
+returns a valid number we're okay. When you pass code directly you can use the
+\type {preamble} key to set local shortcuts. In the previous examples we took
+\type {sin} and \type {cos} from the math library but you can also roll out your
+own functions and|/|or use the more elaborate \type {xmath} library. The color
+parameter is also a function, one that returns one or three arguments. In the
+next example we use \type {lin} to calculate a fraction of the current level and
+total number of levels.
+
+\startbuffer[4a]
+\startMPcode{doublefun}
+ draw lmt_contour [
+ xmin = -3, xmax = 3, xstep = .01,
+ ymin = -1, ymax = 1, ystep = .01,
+
+ levels = 10,
+ default = .5,
+ height = 5cm,
+ function = "x^2 + y^2 + x + y/2",
+ color = "lin(l), 0, 1/2",
+ background = "bitmap"
+ foreground = "none",
+ cache = true,
+ ] xsized TextWidth ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[4a][option=TEX]
+
+\startplacefigure[reference=contour:4a]
+ \getbuffer[4a]
+\stopplacefigure
+
+Instead of a bitmap we can use an isoband, which boils down to a set of tiny
+shapes that make up a bigger one. This is shown in \in {figure} [contour:4b].
+
+\startbuffer[4b]
+\startMPcode{doublefun}
+ draw lmt_contour [
+ xmin = -3, xmax = 3, xstep = .01,
+ ymin = -1, ymax = 1, ystep = .01,
+
+ levels = 10,
+ default = .5,
+ height = 5cm,
+ function = "x^2 + y^2 + x + y/2",
+ color = "lin(l), 1/2, 0",
+ background = "band",
+ foreground = "none",
+ cache = true,
+ ] xsized TextWidth ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[4b][option=TEX]
+
+\startplacefigure[reference=contour:4b]
+ \getbuffer[4b]
+\stopplacefigure
+
+You can draw several functions and see where they overlap:
+
+\startbuffer[5]
+\startMPcode{doublefun}
+ draw lmt_contour [
+ xmin = -pi, xmax = 4*pi, xstep = .1,
+ ymin = -3, ymax = 3, ystep = .1,
+
+ range = { -.1, .1 },
+ preamble = "local sin, cos = math.sin, math.cos",
+ functions = {
+ "sin(x) + sin(y)", "sin(x) + cos(y)",
+ "cos(x) + sin(y)", "cos(x) + cos(y)"
+ },
+ background = "bitmap",
+ linecolor = "black",
+ linewidth = 1/10,
+ color = "shade({1,1,0},{0,0,1})"
+ cache = true,
+ ] xsized TextWidth ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[5][option=TEX]
+
+\startplacefigure[reference=contour:5]
+ \getbuffer[5]
+\stopplacefigure
+
+The range determines the $z$ value(s) that we take into account. You can also
+pass a list of colors to be used. In \in {figure} [contour:6] this is
+demonstrated. There we also show a variant foreground \type {cell}, which uses a
+bit different method for calculating the edges. \footnote {This a bit of a
+playground: more variants might show up in due time.}
+
+\startbuffer[6]
+\startMPcode{doublefun}
+ draw lmt_contour [
+ xmin = -2*pi, xmax = 2*pi, xstep = .01,
+ ymin = -3, ymax = 3, ystep = .01,
+
+ range = { -.1, .1 },
+ preamble = "local sin, cos = math.sin, math.cos",
+ functions = { "sin(x) + sin(y)", "sin(x) + cos(y)" },
+ background = "bitmap",
+ foreground = "cell",
+ linecolor = "white",
+ linewidth = 1/10,
+ colors = { (1/2,1/2,1/2), red, green, blue }
+ level = 3,
+ linewidth = 6,
+ cache = true,
+ ] xsized TextWidth ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[6][option=TEX]
+
+Here the number of levels depends on the number of functions as each can overlap
+with another; for instance the outcome of two functions can overlap or not which
+means 3 cases, and with a value not being seen that gives 4 different cases.
+
+\startplacefigure[reference=contour:6]
+ \getbuffer[6]
+\stopplacefigure
+
+\startbuffer[7]
+\startMPcode{doublefun}
+ draw lmt_contour [
+ xmin = -2*pi, xmax = 2*pi, xstep = .01,
+ ymin = -3, ymax = 3, ystep = .01,
+
+ range = { -.1, .1 },
+ preamble = "local sin, cos = math.sin, math.cos",
+ functions = {
+ "sin(x) + sin(y)",
+ "sin(x) + cos(y)",
+ "cos(x) + sin(y)",
+ "cos(x) + cos(y)"
+ },
+ background = "bitmap",
+ foreground = "none",
+ level = 3,
+ color = "shade({2/3,0,0},{2/3,1,2/3})"
+ cache = true,
+ ] xsized TextWidth ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[7][option=TEX]
+
+Of course one can wonder how useful showing many functions but it can give nice
+pictures, as shown in \in {figure} [contour:7].
+
+\startplacefigure[reference=contour:7]
+ \getbuffer[7]
+\stopplacefigure
+
+\startbuffer[8]
+\startMPcode{doublefun}
+ draw lmt_contour [
+ xmin = -2*pi, xmax = 2*pi, xstep = .01,
+ ymin = -3, ymax = 3, ystep = .01,
+
+ range = { -.3, .3 },
+ preamble = "local sin, cos = math.sin, math.cos",
+ functions = {
+ "sin(x) + sin(y)",
+ "sin(x) + cos(y)",
+ "cos(x) + sin(y)",
+ "cos(x) + cos(y)"
+ },
+ background = "bitmap",
+ foreground = "none",
+ level = 3,
+ color = "shade({1,0,0},{0,1,0})"
+ cache = true,
+ ] xsized TextWidth ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[8][option=TEX]
+
+We can enlargen the window, which is demonstrated in \in {figure} [contour:8]. I
+suppose that such images only make sense in educational settings.
+
+\startplacefigure[reference=contour:8]
+ \getbuffer[8]
+\stopplacefigure
+
+% \startbuffer[9a]
+% \startMPcode{doublefun}
+% draw lmt_contour [
+% xmin = -10, xmax = 10, xstep = 1,
+% ymin = -10, ymax = 10, ystep = 1,
+% function = "math.random(1,3)", levels = 3,
+% linecolor = "white", linewidth = 1/10,
+% width = .3TextWidth, legend = "none",
+% color = "shade({1/2,1/2,0},{0,0,1})"
+%
+% background = "bitmap", foreground = "edge",
+% ] ;
+% \stopMPcode
+% \stopbuffer
+%
+% \typebuffer[9a][option=TEX]
+%
+% \startbuffer[9b]
+% \startMPcode{doublefun}
+% draw lmt_contour [
+% xmin = -10, xmax = 10, xstep = 1,
+% ymin = -10, ymax = 10, ystep = 1,
+% function = "math.random(1,3)", levels = 3,
+% linecolor = "white", linewidth = 1/10,
+% width = .3TextWidth, legend = "none",
+% color = "shade({1/2,1/2,0},{0,0,1/2})"
+%
+% background = "bitmap", foreground = "cell",
+% ] ;
+% \stopMPcode
+% \stopbuffer
+%
+% \startbuffer[9c]
+% \startMPcode{doublefun}
+% draw lmt_contour [
+% xmin = -10, xmax = 10, xstep = 1,
+% ymin = -10, ymax = 10, ystep = 1,
+% function = "math.random(1,3)", levels = 3,
+% linecolor = "white", linewidth = 1/10,
+% width = .3TextWidth, legend = "none",
+% color = "shade({1/2,1/2,0},{0,0,1})"
+%
+% background = "bitmap", foreground = "none",
+% ] ;
+% \stopMPcode
+% \stopbuffer
+%
+% \startbuffer[9d]
+% \startMPcode{doublefun}
+% draw lmt_contour [
+% xmin = -10, xmax = 10, xstep = 1,
+% ymin = -10, ymax = 10, ystep = 1,
+% function = "math.random(1,3)", levels = 3,
+% linecolor = "white", linewidth = 1/10,
+% width = .3TextWidth, legend = "none",
+% color = "shade({1/2,1/2,0},{0,0,1})"
+%
+% background = "shape", foreground = "shape",
+% ] ;
+% \stopMPcode
+% \stopbuffer
+%
+% \startbuffer[9e]
+% \startMPcode{doublefun}
+% draw lmt_contour [
+% xmin = -10, xmax = 10, xstep = 1,
+% ymin = -10, ymax = 10, ystep = 1,
+% function = "math.random(1,3)", levels = 3,
+% linecolor = "white", linewidth = 1/10,
+% width = .3TextWidth, legend = "none",
+% color = "shade({1/2,1/2,0},{0,0,1})"
+%
+% background = "shape", foreground = "edge",
+% ] ;
+% \stopMPcode
+% \stopbuffer
+%
+% \startbuffer[9f]
+% \startMPcode{doublefun}
+% draw lmt_contour [
+% xmin = -10, xmax = 10, xstep = 1,
+% ymin = -10, ymax = 10, ystep = 1,
+% function = "math.random(1,3)", levels = 3,
+% linecolor = "white", linewidth = 1/10,
+% width = .3TextWidth, legend = "none",
+% color = "shade({1/2,1/2,0},{0,0,1})"
+%
+% background = "shape", foreground = "none",
+% ] ;
+% \stopMPcode
+% \stopbuffer
+%
+% \startbuffer[9g]
+% \startMPcode{doublefun}
+% draw lmt_contour [
+% xmin = -10, xmax = 10, xstep = 1,
+% ymin = -10, ymax = 10, ystep = 1,
+% function = "math.random(1,3)", levels = 3,
+% linecolor = "white", linewidth = 1/10,
+% width = .3TextWidth, legend = "none",
+% color = "shade({1/2,1/2,0},{0,0,1})"
+%
+% background = "band", foreground = "edge",
+% ] ;
+% \stopMPcode
+% \stopbuffer
+%
+% \startbuffer[9h]
+% \startMPcode{doublefun}
+% draw lmt_contour [
+% xmin = -10, xmax = 10, xstep = 1,
+% ymin = -10, ymax = 10, ystep = 1,
+% function = "math.random(1,3)", levels = 3,
+% linecolor = "white", linewidth = 1/10,
+% width = .3TextWidth, legend = "none",
+% color = "shade({1/2,1/2,0},{0,0,1})"
+%
+% background = "band", foreground = "cell",
+% ] ;
+% \stopMPcode
+% \stopbuffer
+%
+% \startbuffer[9i]
+% \startMPcode{doublefun}
+% draw lmt_contour [
+% xmin = -10, xmax = 10, xstep = 1,
+% ymin = -10, ymax = 10, ystep = 1,
+% function = "math.random(1,3)", levels = 3,
+% linecolor = "white", linewidth = 1/10,
+% width = .3TextWidth, legend = "none",
+% color = "shade({1/2,1/2,0},{0,0,1})"
+%
+% background = "band", foreground = "none",
+% ] ;
+% \stopMPcode
+% \stopbuffer
+%
+% In \in {figure} [contour:9] we see that using the shape option doesn't work out
+% too well here, which again demonstrates that using the bitmap method is not that
+% bad. In that example we use random numbers, just to show the erratic behavior. In
+% \in {figure} [contour:10] a more sane image is used. The band and bitmap examples
+% are generated quite fast so no caching is used there. We only show one definition:
+%
+% \typebuffer[9i][option=TEX]
+%
+% \startplacefigure[reference=contour:9]
+% \startcombination[3*3]
+% {\pushrandomseed\setrandomseed{1}\getbuffer[9a]\poprandomseed} {\bf bitmap edge}
+% {\pushrandomseed\setrandomseed{1}\getbuffer[9b]\poprandomseed} {\bf bitmap cell}
+% {\pushrandomseed\setrandomseed{1}\getbuffer[9c]\poprandomseed} {\bf bitmap none}
+% {\pushrandomseed\setrandomseed{1}\getbuffer[9d]\poprandomseed} {\bf shape shape}
+% {\pushrandomseed\setrandomseed{1}\getbuffer[9e]\poprandomseed} {\bf shape edge}
+% {\pushrandomseed\setrandomseed{1}\getbuffer[9f]\poprandomseed} {\bf shape none}
+% {\pushrandomseed\setrandomseed{1}\getbuffer[9g]\poprandomseed} {\bf band edge}
+% {\pushrandomseed\setrandomseed{1}\getbuffer[9h]\poprandomseed} {\bf band cell}
+% {\pushrandomseed\setrandomseed{1}\getbuffer[9i]\poprandomseed} {\bf band none}
+% \stopcombination
+% \stopplacefigure
+
+In \in {figure} [contour:10] we see different combinations of backgrounds (in color)
+and foregrounds (edges) in action.
+
+\startbuffer[10a]
+\startMPcode{doublefun}
+ draw lmt_contour [
+ xmin = 0, xmax = 4*pi, xstep = 0,
+ ymin = -6, ymax = 6, ystep = 0,
+
+ levels = 5, legend = false, linewidth = 1/2,
+
+ preamble = "local sin, cos = math.sin, math.cos",
+ function = "cos(x) - sin(y)",
+ color = "shade({1/2,0,0},{0,0,1/2})",
+
+ background = "bitmap", foreground = "edge",
+ ] xsized .3TextWidth ;
+\stopMPcode
+\stopbuffer
+
+\startbuffer[10b]
+\startMPcode{doublefun}
+ draw lmt_contour [
+ xmin = 0, xmax = 4*pi, xstep = 0,
+ ymin = -6, ymax = 6, ystep = 0,
+
+ levels = 5, legend = false, linewidth = 1/2,
+
+ preamble = "local sin, cos = math.sin, math.cos",
+ function = "cos(x) - sin(y)",
+ color = "shade({1/2,0,0},{0,0,1/2})",
+
+ background = "bitmap", foreground = "cell",
+ ] xsized .3TextWidth ;
+\stopMPcode
+\stopbuffer
+
+\startbuffer[10c]
+\startMPcode{doublefun}
+ draw lmt_contour [
+ xmin = 0, xmax = 4*pi, xstep = 0,
+ ymin = -6, ymax = 6, ystep = 0,
+
+ levels = 5, legend = false, linewidth = 1/2,
+
+ preamble = "local sin, cos = math.sin, math.cos",
+ function = "cos(x) - sin(y)",
+ color = "shade({1/2,0,0},{0,0,1/2})",
+
+ background = "bitmap", foreground = "none",
+ ] xsized .3TextWidth ;
+\stopMPcode
+\stopbuffer
+
+\startbuffer[10d]
+\startMPcode{doublefun}
+ draw lmt_contour [
+ xmin = 0, xmax = 4*pi, xstep = 0,
+ ymin = -6, ymax = 6, ystep = 0,
+
+ levels = 5, legend = false, linewidth = 1/2,
+
+ preamble = "local sin, cos = math.sin, math.cos",
+ function = "cos(x) - sin(y)",
+ color = "shade({1/2,0,0},{0,0,1/2})",
+
+ background = "shape", foreground = "shape", cache = true,
+ ] xsized .3TextWidth ;
+\stopMPcode
+\stopbuffer
+
+\startbuffer[10e]
+\startMPcode{doublefun}
+ draw lmt_contour [
+ xmin = 0, xmax = 4*pi, xstep = 0,
+ ymin = -6, ymax = 6, ystep = 0,
+
+ levels = 5, legend = false, linewidth = 1/2,
+
+ preamble = "local sin, cos = math.sin, math.cos",
+ function = "cos(x) - sin(y)",
+ color = "shade({1/2,0,0},{0,0,1/2})",
+
+ background = "shape", foreground = "edge", cache = true,
+ ] xsized .3TextWidth ;
+\stopMPcode
+\stopbuffer
+
+\startbuffer[10f]
+\startMPcode{doublefun}
+ draw lmt_contour [
+ xmin = 0, xmax = 4*pi, xstep = 0,
+ ymin = -6, ymax = 6, ystep = 0,
+
+ levels = 5, legend = false, linewidth = 1/2,
+
+ preamble = "local sin, cos = math.sin, math.cos",
+ function = "cos(x) - sin(y)",
+ color = "shade({1/2,0,0},{0,0,1/2})",
+
+ background = "shape", foreground = "none", cache = true,
+ ] xsized .3TextWidth ;
+\stopMPcode
+\stopbuffer
+
+\startbuffer[10g]
+\startMPcode{doublefun}
+ draw lmt_contour [
+ xmin = 0, xmax = 4*pi, xstep = 0,
+ ymin = -6, ymax = 6, ystep = 0,
+
+ levels = 5, legend = false, linewidth = 1/2,
+
+ preamble = "local sin, cos = math.sin, math.cos",
+ function = "cos(x) - sin(y)",
+ color = "shade({1/2,0,0},{0,0,1/2})",
+
+ background = "band", foreground = "edge",
+ ] xsized .3TextWidth ;
+\stopMPcode
+\stopbuffer
+
+\startbuffer[10h]
+\startMPcode{doublefun}
+ draw lmt_contour [
+ xmin = 0, xmax = 4*pi, xstep = 0,
+ ymin = -6, ymax = 6, ystep = 0,
+
+ levels = 5, legend = false, linewidth = 1/2,
+
+ preamble = "local sin, cos = math.sin, math.cos",
+ function = "cos(x) - sin(y)",
+ color = "shade({1/2,0,0},{0,0,1/2})",
+
+ background = "band", foreground = "cell",
+ ] xsized .3TextWidth ;
+\stopMPcode
+\stopbuffer
+
+\startbuffer[10i]
+\startMPcode{doublefun}
+ draw lmt_contour [
+ xmin = 0, xmax = 4*pi, xstep = 0,
+ ymin = -6, ymax = 6, ystep = 0,
+
+ levels = 5, legend = false, linewidth = 1/2,
+
+ preamble = "local sin, cos = math.sin, math.cos",
+ function = "cos(x) - sin(y)",
+ color = "shade({1/2,0,0},{0,0,1/2})",
+
+ background = "band", foreground = "none",
+ ] xsized .3TextWidth ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[10b][option=TEX]
+
+% \page
+
+There are quite some settings. Some deal with the background, some with the
+foreground and quite some deal with the legend.
+
+\starttabulate[|T|T|T|p|]
+\FL
+\BC name \BC type \BC default \BC comment \NC \NR
+\ML
+\NC xmin \NC numeric \NC 0 \NC needs to be set \NC \NR
+\NC xmax \NC numeric \NC 0 \NC needs to be set \NC \NR
+\NC ymin \NC numeric \NC 0 \NC needs to be set \NC \NR
+\NC ymax \NC numeric \NC 0 \NC needs to be set \NC \NR
+\NC xstep \NC numeric \NC 0 \NC auto 1/200 when zero \NC \NR
+\NC ystep \NC numeric \NC 0 \NC auto 1/200 when zero \NC \NR
+\NC checkresult \NC boolean \NC false \NC checks for overflow and NaN \NC \NR
+\NC defaultnan \NC numeric \NC 0 \NC the value to be used when NaN \NC \NR
+\NC defaultinf \NC numeric \NC 0 \NC the value to be used when overflow \NC \NR
+\ML
+\NC levels \NC numeric \NC 10 \NC number of different levels to show \NC \NR
+\NC level \NC numeric \NC \NC only show this level (foreground) \NC \NR
+\ML
+\NC preamble \NC string \NC \NC shortcuts \NC \NR
+\NC function \NC string \NC x + y \NC the result z value \NC \NR
+\NC functions \NC list \NC \NC multiple functions (overlapping levels) \NC \NR
+\NC color \NC string \NC lin(l) \NC the result color value for level l (1 or 3 values) \NC \NR
+\NC colors \NC numeric \NC \NC used when set \NC \NR
+\ML
+\NC background \NC string \NC bitmap \NC band, bitmap, shape \NC \NR
+\NC foreground \NC string \NC auto \NC cell, edge, shape auto \NC \NR
+\ML
+\NC linewidth \NC numeric \NC .25 \NC \NC \NR
+%NC backgroundcolor \NC string \NC black \NC \NC \NR
+\NC linecolor \NC string \NC gray \NC \NC \NR
+\ML
+\NC width \NC numeric \NC 0 \NC automatic when zero \NC \NR
+\NC height \NC numeric \NC 0 \NC automatic when zero \NC \NR
+\ML
+\NC trace \NC boolean \NC false \NC \NC \NR
+\ML
+\NC legend \NC string \NC all \NC x y z function range all \NC \NR
+\NC legendheight \NC numeric \NC LineHeight \NC \NC \NR
+\NC legendwidth \NC numeric \NC LineHeight \NC \NC \NR
+\NC legendgap \NC numeric \NC 0 \NC \NC \NR
+\NC legenddistance \NC numeric \NC EmWidth \NC \NC \NR
+\NC textdistance \NC numeric \NC 2EmWidth/3 \NC \NC \NR
+\NC functiondistance \NC numeric \NC ExHeight \NC \NC \NR
+\NC functionstyle \NC string \NC \NC \CONTEXT\ style name \NC \NR
+\NC xformat \NC string \NC @0.2N \NC number format template \NC \NR
+\NC yformat \NC string \NC @0.2N \NC number format template \NC \NR
+\NC zformat \NC string \NC @0.2N \NC number format template \NC \NR
+\NC xstyle \NC string \NC \NC \CONTEXT\ style name \NC \NR
+\NC ystyle \NC string \NC \NC \CONTEXT\ style name \NC \NR
+\NC zstyle \NC string \NC \NC \CONTEXT\ style name \NC \NR
+\ML
+\NC axisdistance \NC numeric \NC ExHeight \NC \NC \NR
+\NC axislinewidth \NC numeric \NC .25 \NC \NC \NR
+\NC axisoffset \NC numeric \NC ExHeight/4 \NC \NC \NR
+\NC axiscolor \NC string \NC black \NC \NC \NR
+\NC ticklength \NC numeric \NC ExHeight \NC \NC \NR
+\ML
+\NC xtick \NC numeric \NC 5 \NC \NC \NR
+\NC ytick \NC numeric \NC 5 \NC \NC \NR
+\NC xlabel \NC numeric \NC 5 \NC \NC \NR
+\NC ylabel \NC numeric \NC 5 \NC \NC \NR
+\LL
+\stoptabulate
+
+\startplacefigure[reference=contour:10]
+ \startcombination[3*3]
+ {\getbuffer[10a]} {\bf bitmap edge}
+ {\getbuffer[10b]} {\bf bitmap cell}
+ {\getbuffer[10c]} {\bf bitmap none}
+ {\getbuffer[10d]} {\bf shape shape}
+ {\getbuffer[10e]} {\bf shape edge}
+ {\getbuffer[10f]} {\bf shape none}
+ {\getbuffer[10g]} {\bf band edge}
+ {\getbuffer[10h]} {\bf band cell}
+ {\getbuffer[10i]} {\bf band none}
+ \stopcombination
+\stopplacefigure
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-followtext.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-followtext.tex
new file mode 100644
index 00000000000..0791315656a
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-followtext.tex
@@ -0,0 +1,124 @@
+% language=us
+
+\environment luametafun-style
+
+\startcomponent luametafun-followtext
+
+\startchapter[title={Followtext}]
+
+Typesetting text along a path started as a demo if communication between \TEX\ and
+\METAPOST\ in the early days of \METAFUN. In the meantime the implementation has
+been modernized a few times and the current implementation feels okay, especially
+now that we have a better user interface. Here is an example:
+
+\startbuffer[1a]
+\startMPcode{doublefun}
+ draw lmt_followtext [
+ text = "How well does it work {\bf 1}! ",
+ path = fullcircle scaled 4cm,
+ trace = true,
+ spread = true,
+ ] ysized 5cm ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[1a][option=TEX]
+
+Here is the same example but with the text in the reverse order. The results of both examples
+are shown in \in {figure} [followtext:1].
+
+\startbuffer[1b]
+\startMPcode{doublefun}
+ draw lmt_followtext [
+ text = "How well does it work {\bf 2}! ",
+ path = fullcircle scaled 4cm,
+ trace = true,
+ spread = false,
+ reverse = true,
+ ] ysized 5cm ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[1b][option=TEX]
+
+\startplacefigure[reference=followtext:1]
+ \startcombination[2*2]
+ {\getbuffer[1a]} {}
+ {\getbuffer[1b]} {}
+ \stopcombination
+\stopplacefigure
+
+There are not that many options. One is \type {autoscale} which makes the shape
+and text match. \in {Figure} [followtext:2] shows what happens.
+
+\startbuffer[2a]
+\startMPcode{doublefun}
+ draw lmt_followtext [
+ text = "How well does it work {\bf 3}! ",
+ trace = true,
+ autoscaleup = "yes"
+ ] ysized 5cm ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[2a][option=TEX]
+
+\startbuffer[2b]
+\startMPcode{doublefun}
+ draw lmt_followtext [
+ text = "How well does it work {\bf 4}! ",
+ path = fullcircle scaled 2cm,
+ trace = true,
+ autoscaleup = "max"
+ ] ysized 5cm ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[2b][option=TEX]
+
+\startplacefigure[reference=followtext:2]
+ \startcombination[2*2]
+ {\getbuffer[2a]} {}
+ {\getbuffer[2b]} {}
+ \stopcombination
+\stopplacefigure
+
+You can use quite strange paths, like the one show in \in {figure}
+[followtext:3]. Watch the parenthesis around the path. this is really needed in
+order for the scanner to pick up the path (otherwise it sees a pair).
+
+\startbuffer[3]
+\startMPcode{doublefun}
+ draw lmt_followtext [
+ text = "\samplefile {zapf}",
+ path = ((3,0) .. (1,0) .. (5,0) .. (2,0) .. (4,0) .. (3,0)),
+ autoscaleup = "max"
+ ] xsized TextWidth ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[3][option=TEX]
+
+\startplacefigure[reference=followtext:3]
+ \getbuffer[3]
+\stopplacefigure
+
+The small set of options is:
+
+\starttabulate[|T|T|T|p|]
+\FL
+\BC name \BC type \BC default \BC comment \NC \NR
+\ML
+\NC text \NC string \NC \NC \NC \NR
+\NC spread \NC string \NC true \NC \NC \NR
+\NC trace \NC numeric \NC false \NC \NC \NR
+\NC reverse \NC numeric \NC false \NC \NC \NR
+\NC autoscaleup \NC numeric \NC no \NC \NC \NR
+\NC autoscaledown \NC string \NC no \NC \NC \NR
+\NC path \NC string \NC (fullcircle) \NC \NC \NR
+\LL
+\stoptabulate
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-fonts.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-fonts.tex
new file mode 100644
index 00000000000..27ea2fd0014
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-fonts.tex
@@ -0,0 +1,328 @@
+% language=us
+
+\environment luametafun-style
+
+\startcomponent luametafun-fonts
+
+\startchapter[title={Fonts}]
+
+Fonts are interesting phenomena but can also be quite hairy. Shapes can be
+missing or not to your liking. There can be bugs too. Control over fonts has
+always been on the agenda of \TEX\ macro packages, and \CONTEXT\ provides a lot
+of control, especially in \MKIV. In \LMTX\ we add some more to that: we bring
+back \METAFONT's but now in the \METAPOST\ way. A simple example shows how this
+is (maybe I should say: will be) done.
+
+We define three simple shapes and do that (for now) in the \type {simplefun}
+instance because that's what is used when generating the glyphs.
+
+\startbuffer
+\startMPcalculation{simplefun}
+ vardef TestGlyphLB =
+ image (
+ fill (unitsquare xscaled 10 yscaled 16 shifted (0,-3))
+ withcolor "darkred" withtransparency (1,.5)
+ ;
+ )
+ enddef ;
+
+ vardef TestGlyphRB =
+ image (
+ fill (unitcircle xscaled 15 yscaled 12 shifted (0,-2))
+ withcolor "darkblue" withtransparency (1,.5)
+ ;
+ )
+ enddef ;
+
+ vardef TestGlyphFS =
+ image (
+ fill (unittriangle xscaled 15 yscaled 12 shifted (0,-2))
+ withcolor "darkgreen" withtransparency (1,.5)
+ ;
+ )
+ enddef ;
+\stopMPcalculation
+\stopbuffer
+
+\typebuffer[option=TEX] \getbuffer
+
+This is not that spectacular, not is the following:
+
+\startbuffer
+\startMPcalculation{simplefun}
+ lmt_registerglyphs [
+ name = "test",
+ units = 10, % 1000
+ ] ;
+
+ lmt_registerglyph [
+ category = "test",
+ unicode = 123,
+ code = "draw TestGlyphLB ;",
+ width = 10, % 1000
+ height = 13, % 1300
+ depth = 3 % 300
+ ] ;
+
+ lmt_registerglyph [
+ category = "test",
+ unicode = 125,
+ code = "draw TestGlyphRB ;",
+ width = 15,
+ height = 10,
+ depth = 2
+ ] ;
+
+ lmt_registerglyph [
+ category = "test",
+ unicode = "/",
+ code = "draw TestGlyphFS ;",
+ width = 15,
+ height = 10,
+ depth = 2
+ ] ;
+
+\stopMPcalculation
+\stopbuffer
+
+\typebuffer[option=TEX] \getbuffer
+
+We now define a font. We always use a font as starting point which has the
+advantage that we always get something reasonable when we test. Of course you can
+use this \type {mps} font feature with other fonts too.
+
+\startbuffer
+\definefontfeature[metapost][metapost=test] % or: mps={category=test}
+
+\definefont[MyFontA][Serif*metapost @ 10bp]
+\definefont[MyFontB][Serif*metapost @ 12bp]
+\stopbuffer
+
+\typebuffer[option=TEX] \getbuffer
+
+These fonts can now be used:
+
+\startbuffer
+\MyFontA \dorecurse{20}{\{ /#1/ \} }\par
+\MyFontB \dorecurse{20}{\{ /#1/ \} }\par
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+We get some useless text but it demonstrates the idea:
+
+{\getbuffer}
+
+If you know a bit more about \CONTEXT\ you could think: so what, wasn't this
+already possible? Sure, there are various ways to achieve similar effects, but
+the method described here has a few advantages: it's relatively easy and we're
+talking about real fonts here. This means that using the shapes for characters is
+pretty efficient.
+
+A more realistic example is given next. It is a subset of what is available in
+the \CONTEXT\ core.
+
+\startbuffer
+\startMPcalculation{simplefun}
+
+ pen SymbolPen ; SymbolPen := pencircle scaled 1/4 ;
+
+ vardef SymbolBullet =
+ fill unitcircle scaled 3 shifted (1.5,1.5) withpen SymbolPen
+ enddef ;
+ vardef SymbolSquare =
+ draw unitsquare scaled (3-1/16) shifted (1.5,1.5) withpen SymbolPen
+ enddef ;
+ vardef SymbolBlackDiamond =
+ fillup unitdiamond scaled (3-1/16) shifted (1.5,1.5) withpen SymbolPen
+ enddef ;
+ vardef SymbolNotDef =
+ draw center unitcircle
+ scaled 3
+ shifted (1.5,1.5)
+ withpen SymbolPen scaled 4
+ enddef ;
+
+ lmt_registerglyphs [
+ name = "symbols",
+ units = 10,
+ usecolor = true,
+ width = 6,
+ height = 6,
+ depth = 0,
+ code = "SymbolNotDef ;",
+ ] ;
+
+ lmt_registerglyph [ category = "symbols", unicode = "0x2022",
+ code = "SymbolBullet ;"
+ ] ;
+ lmt_registerglyph [ category = "symbols", unicode = "0x25A1",
+ code = "SymbolSquare ;"
+ ] ;
+ lmt_registerglyph [ category = "symbols", unicode = "0x25C6",
+ code = "SymbolBlackDiamond ;"
+ ] ;
+\stopMPcalculation
+\stopbuffer
+
+\typebuffer[option=TEX] \getbuffer
+
+We could use these symbols in for instance itemize symbols. You might notice the
+potential difference in bullets:
+
+\startbuffer
+\definefontfeature[metapost][metapost=symbols]
+
+\definefont[MyFont] [Serif*metapost sa 1]
+
+\startitemize[packed]
+ \startitem {\MyFont • □ ◆}\quad Regular rendering. \stopitem
+ \startitem {\MyFont\red • □ ◆}\quad Rendering with color. \stopitem
+ \startitem {\MyFont\blue\showglyphs • □ ◆}\quad Idem but with boundingboxes shown. \stopitem
+\stopitemize
+\stopbuffer
+
+\typebuffer[option=TEX] \getbuffer
+
+When blown up, these symbols look as follows:
+
+\startlinecorrection
+\scale[width=\textwidth]{%
+ {\MyFont •□◆}%
+ {\MyFont\red •□◆}%
+ {\MyFont\blue\showglyphs •□◆}%
+}
+\stoplinecorrection
+
+You can use these tricks with basically any font, so also with math fonts.
+However, at least for now, you need to define these before the font gets loaded.
+
+\startbuffer
+\startMPcalculation{simplefun}
+
+ pen KindergartenPen ; KindergartenPen := pencircle scaled 1 ;
+
+ % 10 x 10 grid
+
+ vardef KindergartenEqual =
+ draw image
+ (
+ draw (2,6) -- (9,5) ;
+ draw (2,4) -- (8,3) ;
+ )
+ shifted (0,-2)
+ withpen KindergartenPen
+ withcolor "KindergartenEqual"
+ enddef ;
+ vardef KindergartenPlus =
+ draw image
+ (
+ draw (1,4) -- (9,5) ;
+ draw (4,1) -- (5,8) ;
+ )
+ shifted (0,-2)
+ withpen KindergartenPen
+ withcolor "KindergartenPlus"
+ enddef ;
+ vardef KindergartenMinus =
+ draw image
+ (
+ draw (1,5) -- (9,4) ;
+ )
+ shifted (0,-2)
+ withpen KindergartenPen
+ withcolor "KindergartenMinus"
+ enddef ;
+ vardef KindergartenTimes =
+ draw image
+ (
+ draw (2,1) -- (9,8) ;
+ draw (8,1) -- (2,8) ;
+ )
+ shifted (0,-2)
+ withpen KindergartenPen
+ withcolor "KindergartenTimes"
+ enddef ;
+ vardef KindergartenDivided =
+ draw image
+ (
+ draw (2,1) -- (8,9) ;
+ )
+ shifted (0,-2)
+ withpen KindergartenPen
+ withcolor "KindergartenDivided"
+ enddef ;
+
+ lmt_registerglyphs [
+ name = "kindergarten",
+ units = 10,
+ % usecolor = true,
+ width = 10,
+ height = 8,
+ depth = 2,
+ ] ;
+
+ lmt_registerglyph [ category = "kindergarten", unicode = "0x003D",
+ code = "KindergartenEqual"
+ ] ;
+ lmt_registerglyph [ category = "kindergarten", unicode = "0x002B",
+ code = "KindergartenPlus"
+ ] ;
+ lmt_registerglyph [ category = "kindergarten", unicode = "0x2212",
+ code = "KindergartenMinus"
+ ] ;
+ lmt_registerglyph [ category = "kindergarten", unicode = "0x00D7",
+ code = "KindergartenTimes"
+ ] ;
+ lmt_registerglyph [ category = "kindergarten", unicode = "0x002F",
+ code = "KindergartenDivided"
+ ] ;
+
+\stopMPcalculation
+\stopbuffer
+
+\typebuffer[option=TEX] \getbuffer
+
+We also define the colors. If we leave \type {usecolor} to true, the text colors
+will be taken.
+
+\startbuffer[definitions]
+\definecolor[KindergartenEqual] [darkgreen]
+\definecolor[KindergartenPlus] [darkred]
+\definecolor[KindergartenMinus] [darkred]
+\definecolor[KindergartenTimes] [darkblue]
+\definecolor[KindergartenDivided][darkblue]
+
+\definefontfeature[mathextra][metapost=kindergarten]
+\stopbuffer
+
+\typebuffer[definitions][option=TEX] \getbuffer[definitions]
+
+Here is an example:
+
+\starttyping
+\switchtobodyfont[cambria]
+
+$ y = 2 \times x + a - b / 3 $
+\stoptyping
+
+Scaled up:
+
+\startlinecorrection
+ \switchtobodyfont[cambria]
+ \scale[width=\textwidth]{$ y = 2 \times x + a - b / 3 $}
+\stoplinecorrection
+
+Of course this won't work out well (yet) with extensible yet, due to related
+definitions for which we don't have an interface yet. There is one thing that you
+need to keep in mind: the fonts are flushed when the document gets finalized so
+you have to make sure that colors are defined at the level that they are still
+valid at that time. So best put color definitions like the above in the document
+style.
+
+This is an experimental interface anyway so we don't explain the parameters yet
+as there might be more of them.
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-function.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-function.tex
new file mode 100644
index 00000000000..79fa97a21de
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-function.tex
@@ -0,0 +1,296 @@
+% language=us
+
+\environment luametafun-style
+
+\startcomponent luametafun-function
+
+\startchapter[title={Function}]
+
+It is tempting to make helpers that can do a lot. However, that also means that
+we need to explain a lot. Instead it makes more sense to have specific helpers
+and just make another one when needed. Rendering functions falls into this
+category. At some point users will come up with specific cases that other users
+can use. Therefore, the solution presented here is not the ultimate answer. We
+start with a simple example:
+
+\startbuffer[1]
+\startMPcode{doublefun}
+ draw lmt_function [
+ xmin = 0, xmax = 20, xstep = .1,
+ ymin = -2, ymax = 2,
+
+ sx = 1mm, xsmall = 80, xlarge = 20,
+ sy = 4mm, ysmall = 40, ylarge = 4,
+
+ linewidth = .025mm, offset = .1mm,
+
+ code = "1.5 * math.sind (50 * x - 150)",
+ ]
+ xsized 8cm
+ ;
+\stopMPcode
+\stopbuffer
+
+\startplacefigure
+ \getbuffer[1]
+\stopplacefigure
+
+This image is defined as follows:
+
+\typebuffer[1][option=TEX]
+
+\startbuffer[2]
+\startMPcode{doublefun}
+ draw lmt_function [
+ xmin = 0, xmax = 20, xstep = .1,
+ ymin = -2, ymax = 2,
+
+ sx = 1mm, xsmall = 80, xlarge = 20,
+ sy = 4mm, ysmall = 40, ylarge = 4,
+
+ linewidth = .025mm, offset = .1mm,
+
+ xticks = "bottom",
+ yticks = "left",
+ xlabels = "nolimits",
+ ylabels = "yes",
+ code = "1.5 * math.sind (50 * x - 150)",
+ % frame = "ticks",
+ frame = "sticks",
+ ycaption = "\strut \rotate[rotation=90]{something vertical, using $\sin{x}$}",
+ xcaption = "\strut something horizontal",
+ functions = {
+ [ xmin = 1.0, xmax = 7.0, close = true, fillcolor = "darkred" ],
+ [ xmin = 7.0, xmax = 12.0, close = true, fillcolor = "darkgreen" ],
+ [ xmin = 12.0, xmax = 19.0, close = true, fillcolor = "darkblue" ],
+ [
+ drawcolor = "darkyellow",
+ drawsize = 2
+ ]
+ }
+ ]
+ xsized TextWidth
+ ;
+\stopMPcode
+\stopbuffer
+
+We can draw multiple functions in one go. The next sample split the drawing over
+a few ranges and is defined as follows; in \in {figure} [function:2] we see the
+result.
+
+\typebuffer[2][option=TEX]
+
+
+\startplacefigure[reference=function:2]
+ \getbuffer[2]
+\stopplacefigure
+
+Instead of the same function, we can draw different ones and when we use transparency
+we get nice results too.
+
+\startbuffer[3]
+\definecolor[MyColorR][r=.5,t=.5,a=1]
+\definecolor[MyColorG][g=.5,t=.5,a=1]
+\definecolor[MyColorB][b=.5,t=.5,a=1]
+
+\startMPcode{doublefun}
+ draw lmt_function [
+ xmin = 0, xmax = 20, xstep = .1,
+ ymin = -1, ymax = 1,
+
+ sx = 1mm, xsmall = 80, xlarge = 20,
+ sy = 4mm, ysmall = 40, ylarge = 4,
+
+ linewidth = .025mm, offset = .1mm,
+
+ functions = {
+ [
+ code = "math.sind (50 * x - 150)",
+ close = true,
+ fillcolor = "MyColorR"
+ ],
+ [
+ code = "math.cosd (50 * x - 150)",
+ close = true,
+ fillcolor = "MyColorB"
+ ]
+ },
+ ]
+ xsized TextWidth
+ ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[3][option=TEX]
+
+\startplacefigure[reference=function:3]
+ \getbuffer[3]
+\stopplacefigure
+
+It is important to choose a good step. In \in {figure} [function:4] we show 4
+variants and it is clear that in this case using straight line segments is better
+(or at least more efficient with small steps).
+
+\startbuffer[4a]
+\startMPcode{doublefun}
+ draw lmt_function [
+ xmin = 0, xmax = 10, xstep = .1,
+ ymin = -1, ymax = 1,
+
+ sx = 1mm, sy = 4mm,
+
+ linewidth = .025mm, offset = .1mm,
+
+ code = "math.sind (50 * x^2 - 150)",
+ shape = "curve"
+ ]
+ xsized .45TextWidth
+ ;
+\stopMPcode
+\stopbuffer
+
+\startbuffer[4b]
+\startMPcode{doublefun}
+ draw lmt_function [
+ xmin = 0, xmax = 10, xstep = .01,
+ ymin = -1, ymax = 1,
+
+ sx = 1mm, sy = 4mm,
+
+ linewidth = .025mm, offset = .1mm,
+
+ code = "math.sind (50 * x^2 - 150)",
+ shape = "curve"
+ ]
+ xsized .45TextWidth
+ ;
+\stopMPcode
+\stopbuffer
+
+\startbuffer[4c]
+\startMPcode{doublefun}
+ draw lmt_function [
+ xmin = 0, xmax = 10, xstep = .1,
+ ymin = -1, ymax = 1,
+
+ sx = 1mm, sy = 4mm,
+
+ linewidth = .025mm, offset = .1mm,
+
+ code = "math.sind (50 * x^2 - 150)",
+ shape = "line"
+ ]
+ xsized .45TextWidth
+ ;
+\stopMPcode
+\stopbuffer
+
+\startbuffer[4d]
+\startMPcode{doublefun}
+ draw lmt_function [
+ xmin = 0, xmax = 10, xstep = .01,
+ ymin = -1, ymax = 1,
+
+ sx = 1mm, sy = 4mm,
+
+ linewidth = .025mm, offset = .1mm,
+
+ code = "math.sind (50 * x^2 - 150)",
+ shape = "line"
+ ]
+ xsized .45TextWidth
+ ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[4a][option=TEX]
+
+\startplacefigure[reference=function:4]
+ \startcombination[2*2]
+ {\getbuffer[4a]} {\type {xstep=.10} and \type {shape="curve"}}
+ {\getbuffer[4b]} {\type {xstep=.01} and \type {shape="curve"}}
+ {\getbuffer[4c]} {\type {xstep=.10} and \type {shape="line"}}
+ {\getbuffer[4d]} {\type {xstep=.01} and \type {shape="line"}}
+ \stopcombination
+\stopplacefigure
+
+You can manipulate the axis (a bit) by tweaking the first and last ticks. In the
+case of \in {figure} [function:5] we also put the shape on top of the axis.
+
+\startbuffer[5]
+\startMPcode{doublefun}
+ draw lmt_function [
+ xfirst = 9, xlast = 21, ylarge = 2, ysmall = 1/5,
+ yfirst = -1, ylast = 1, xlarge = 2, xsmall = 1/4,
+
+ xmin = 10, xmax = 20, xstep = .25,
+ ymin = -1, ymax = 1,
+
+ drawcolor = "darkmagenta",
+ shape = "steps",
+ code = "0.5 * math.random(-2,2)",
+ linewidth = .025mm,
+ offset = .1mm,
+ reverse = true,
+ ]
+ xsized TextWidth
+ ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[5][option=TEX]
+
+\startplacefigure[reference=function:5]
+ \getbuffer[5]
+\stopplacefigure
+
+The whole repertoire of parameters (in case of doubt just check the source code as this
+kind of code is not that hard to follow) is:
+
+\starttabulate[|T|T|T|p|]
+\FL
+\BC name \BC type \BC default \BC comment \NC \NR
+\ML
+\NC sx \NC numeric \NC 1mm \NC horizontal scale factor \NC \NR
+\NC sy \NC numeric \NC 1mm \NC vertical scale factor \NC \NR
+\NC offset \NC numeric \NC 0 \NC \NC \NR
+\NC xmin \NC numeric \NC 1 \NC \NC \NR
+\NC xmax \NC numeric \NC 1 \NC \NC \NR
+\NC xstep \NC numeric \NC 1 \NC \NC \NR
+\NC xsmall \NC numeric \NC \NC optional step of small ticks \NC \NR
+\NC xlarge \NC numeric \NC \NC optional step of large ticks \NC \NR
+\NC xlabels \NC string \NC no \NC \type {yes}, \type {no} or \type {nolimits} \NC \NR
+\NC xticks \NC string \NC bottom \NC possible locations are \type {top}, \type {middle} and \type {bottom} \NC \NR
+\NC xcaption \NC string \NC \NC \NC \NR
+\NC ymin \NC numeric \NC 1 \NC \NC \NR
+\NC ymax \NC numeric \NC 1 \NC \NC \NR
+\NC ystep \NC numeric \NC 1 \NC \NC \NR
+\NC ysmall \NC numeric \NC \NC optional step of small ticks \NC \NR
+\NC ylarge \NC numeric \NC \NC optional step of large ticks \NC \NR
+\NC xfirst \NC numeric \NC \NC left of \type {xmin} \NC \NR
+\NC xlast \NC numeric \NC \NC right of \type {xmax} \NC \NR
+\NC yfirst \NC numeric \NC \NC below \type {ymin} \NC \NR
+\NC ylast \NC numeric \NC \NC above \type {ymax} \NC \NR
+\NC ylabels \NC string \NC no \NC \type {yes}, \type {no} or \type {nolimits} \NC \NR
+\NC yticks \NC string \NC left \NC possible locations are \type {left}, \type {middle} and \type {right} \NC \NR
+\NC ycaption \NC string \NC \NC \NC \NR
+\NC code \NC string \NC \NC \NC \NR
+\NC close \NC boolean \NC false \NC \NC \NR
+\NC shape \NC string \NC curve \NC or \type {line} \NC \NR
+\NC fillcolor \NC string \NC \NC \NC \NR
+\NC drawsize \NC numeric \NC 1 \NC \NC \NR
+\NC drawcolor \NC string \NC \NC \NC \NR
+\NC frame \NC string \NC \NC options are \type {yes}, \type {ticks} and \type {sticks} \NC \NR
+\NC linewidth \NC numeric \NC .05mm \NC \NC \NR
+\NC pointsymbol \NC string \NC \NC like type {dots} \NC \NR
+\NC pointsize \NC numeric \NC 2 \NC \NC \NR
+\NC pointcolor \NC string \NC \NC \NC \NR
+\NC xarrow \NC string \NC \NC \NC \NR
+\NC yarrow \NC string \NC \NC \NC \NR
+\NC reverse \NC boolean \NC false \NC when \type {true} draw the function between axis and labels \NC \NR
+\LL
+\stoptabulate
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-grid.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-grid.tex
new file mode 100644
index 00000000000..719d8023d28
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-grid.tex
@@ -0,0 +1,11 @@
+% language=us
+
+\environment luametafun-style
+
+\startcomponent luametafun-grid
+
+\startchapter[title={Grid}]
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-groups.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-groups.tex
new file mode 100644
index 00000000000..b29ab3cbf47
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-groups.tex
@@ -0,0 +1,52 @@
+% language=us
+
+\environment luametafun-style
+
+\startcomponent luametafun-groups
+
+\startchapter[title={Groups}]
+
+This is just a quick example of an experimental features.
+
+\startbuffer
+\startMPcode
+ fill fullcircle scaled 2cm shifted ( 5mm,2cm) withcolor "darkblue" ;
+ fill fullcircle scaled 2cm shifted (15mm,2cm) withcolor "darkblue" ;
+
+ fill fullcircle scaled 2cm shifted ( 5mm,-2cm) withcolor "darkgreen" ;
+ fill fullcircle scaled 2cm shifted (15mm,-2cm) withcolor "darkgreen" ;
+
+ draw image (
+ fill fullcircle scaled 4cm withcolor "darkred" ;
+ fill fullcircle scaled 4cm shifted (2cm,0) withcolor "darkred" ;
+
+ setgroup currentpicture to boundingbox currentpicture
+ withtransparency (1,.5) ;
+ ) ;
+
+ draw image (
+ fill fullcircle scaled 3cm withcolor "darkyellow"
+ withtransparency (1,.5) ;
+ fill fullcircle scaled 3cm shifted (2cm,0) withcolor "darkyellow"
+ withtransparency (1,.5) ;
+ ) ;
+
+ addbackground withcolor "darkgray" ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+A group create an object that when transparency is applied is treated as
+a group.
+
+\startlinecorrection
+ \getbuffer
+\stoplinecorrection
+
+(Groups might become more powerful in the future, like reusable components but
+then some more juggling is needed.)
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-interface.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-interface.tex
new file mode 100644
index 00000000000..662ae61a88b
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-interface.tex
@@ -0,0 +1,155 @@
+% language=us
+
+\environment luametafun-style
+
+\startcomponent luametafun-interface
+
+\startchapter[title={Interface}]
+
+Because graphic solutions are always kind of personal or domain driven it makes not
+much sense to cook up very generic solutions. If you have a project where \METAPOST\
+can be of help, it also makes sense to spend some time on implementing the basics that
+you need. In that case you can just copy and tweak what is there. The easiest way to
+do that is to make a test file and use:
+
+\starttyping[option=TEX]
+\startMPpage
+ % your code
+\stopMPpage
+\stoptyping
+
+Often you don't need to write macros, and standard drawing commands will do the
+job, but when you find yourself repeating code, a wapper might make sense. And
+this is why we have this key|/|value interface: it's easier to abstract your
+settings than to pass them as (expression or text) arguments to a macro,
+especially when there are many.
+
+You can find many examples of the key|/|value driven user interface in the source
+files and these are actually not that hard to understand when you know a bit of
+\METAPOST\ and the additional macros that come with \METAFUN. In case you wonder
+about overhead: the performance of this mechanism is pretty good.
+
+Although the parameter handler runs on top of the \LUA\ interface, you don't need
+to use \LUA\ unless you find that \METAPOST\ can't do the job. I won't give
+examples of coding because I think that the source of \METAFUN\ provides enough
+clues, especially the file \type {mp-lmtx.mpxl}. As the name suggests this is
+part of the \CONTEXT\ version \LMTX, which runs on top of \LUAMETATEX. I leave it
+open if I will backport this functionality to \LUATEX\ and therefore \MKIV.
+
+An excellent explanation of this interface can be found at:
+
+\starttyping
+https://adityam.github.io/context-blog/post/new-metafun-interface/
+\stoptyping
+
+So (at least for now) here I can stick to just mentioning the currently stable
+interface macros:
+
+\starttabulate[|T|l|pl|]
+\FL
+\NC presetparameters \NC \type {name [...]} \NC
+ Assign default values to a category of parameters. Sometimes it makes sense
+ not to set a default, because then you can check if a parameter has been set
+ at all.
+ \NC \NR
+\NC applyparameters \NC \type {name macro} \NC
+ This prepares the parameter handler for the given category and calls the
+ given macro when that is done.
+ \NC \NR
+\NC getparameters \NC \type {name [...]} \NC
+ The parameters given after the category name are set.
+ \NC \NR
+\ML
+\NC hasparameter \NC \type {names} \NC
+ Returns \type {true} when a parameter is set, and \type {false} otherwise.
+ \NC \NR
+\NC hasoption \NC \type {names options} \NC
+ Returns \type {true} when there is overlap in given options, and \type
+ {false} otherwise.
+ \NC \NR
+\ML
+\NC getparameter \NC \type {names} \NC
+ Resolves the parameter with the given name. because a parameter itself can
+ have a parameter list you can pass additional names to reach the final
+ destination.
+ \NC \NR
+\NC getparameterdefault \NC \type {names} \NC
+ Resolves the parameter with the given name. because a parameter itself can
+ have a parameter list you can pass additional names to reach the final
+ destination. The last value is used when no parameter is found.
+ \NC \NR
+\ML
+\NC getparametercount \NC \type {names} \NC
+ Returns the size if a list (array).
+ \NC \NR
+\NC getmaxparametercount \NC \type {names} \NC
+ Returns the size if a list (array) but descends into lists to find the largest size
+ of a sublist.
+ \NC \NR
+\ML
+\NC getparameterpath \NC \type {names string boolean} \NC
+ Returns the parameter as path. The optional string is one of \type {--},
+ \type {..} or \type {...} and the also optional boolean will force a closed
+ path.
+ \NC \NR
+\NC getparameterpen \NC \type {names} \NC
+ Returns the parameter as pen (path).
+ \NC \NR
+\NC getparametertext \NC \type {names boolean} \NC
+ Returns the parameter as string. The boolean can be used to force prepending
+ a so called \type {\strut}.
+ \NC \NR
+\ML
+\NC pushparameters \NC \type {category} \NC
+ Pushed the given (sub) category onto the stack so that we don't need to give
+ the category each time.
+ \NC \NR
+\NC popparameters \NC \NC
+ Pops the current (sub) category from the stack.
+ \NC \NR
+\LL
+\stoptabulate
+
+Most commands accept a list of strings separated by one or more spaces, The
+resolved will then stepwise descend into the parameter tree. This means that a
+parameter itself can refer to a list. When a value is an array and the last name
+is a number, the value at the given index will be returned.
+
+\starttyping
+"category" "name" ... "name"
+"category" "name" ... number
+\stoptyping
+
+The \type {category} is not used when we have pushed a (sub) category which can
+save you some typing and also is more efficient. Of course than can mean that you
+need to store values at a higher level when you need them at a deeper level.
+
+There are quite some extra helpers that relate to this mechanism, at the
+\METAPOST\ end as well as at the \LUA\ end. They aim for instance at efficiently
+dealing with paths and can be seen at work in the mentioned module.
+
+There is one thing you should notice. While \METAPOST\ has numeric, string,
+boolean and path variables that can be conveniently be passed to and from \LUA,
+communicating colors is a bit of a hassle. This is because \RGB\ and \CMYK\
+colors and gray scales use different types. For this reason it is strongly
+recommended to use strings that refer to predefined colors instead. This also
+enforces consistency with the \TEX\ end. As convenience you can define colors at
+the \METAFUN\ end.
+
+\startbuffer
+\startMPcode
+ definecolor [ name = "MyColor", r = .5, g = .25, b = .25 ]
+
+ fill fullsquare xyscaled (TextWidth,5mm) withcolor "MyColor" ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-introduction.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-introduction.tex
new file mode 100644
index 00000000000..6892b21ce84
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-introduction.tex
@@ -0,0 +1,88 @@
+% language=us
+
+\environment luametafun-style
+
+\startcomponent luametafun-introduction
+
+\startchapter[title={Introduction}]
+
+For quite a while, around since 1996, the integration of \METAPOST\ into
+\CONTEXT\ became sort of mature but, it took decades of stepwise refinement to
+reach the state that we're in now. In this manual I will discuss some of the
+features that became possible by combining \LUA\ and \METAPOST. We already had
+quite a bit of that for a decade but in 2018, when \LUAMETATEX\ showed up a next
+stage was started.
+
+Before we go into details it is good to summarize the steps that were involved in
+integrating \METAPOST\ and \TEX\ in \CONTEXT. It indicates a bit what we had and
+have to deal with which in turn lead to the interfaces we now have.
+
+Originally, \TEX\ had no graphic capabilities: it just needed to know dimensions
+of the graphics and pass some basic information about what to include to the
+\DVI\ post processor. So, a \METAPOST\ graphic was normally processed outside the
+current run, resulting in \POSTSCRIPT\ graphic, that then had to be included. In
+\PDFTEX\ there were some more built in options, and therefore the \METAPOST\ code
+could be processed runtime using some (generic) \TEX\ macros that I wrote.
+However, that engine still had to launch \METAPOST\ for each graphic, although we
+could accumulate them and do that between runs. Immediate processing means that
+we immediately know the dimensions, while a collective run is faster. In \LUATEX\
+this all changed to very fast runtime processing, made possible because the
+\METAPOST\ library is embedded in the engine, a decision that we made early in
+the project and never regret.
+
+With \PDFTEX\ the process was managed by the \type {texexec} \CONTEXT\ runner but
+with \LUATEX\ it stayed under the control of the current run. In the case of
+\PDFTEX\ the actual embedding was done by \TEX\ macros that interpreted the
+(relatively simple) \POSTSCRIPT\ code and turned it into \PDF\ literals. In
+\LUATEX\ that job was delegated to \LUA.
+
+When using \PDFTEX\ with independent \METAPOST\ runs support for special color
+spaces, transparency, embedded graphics, outline text, shading and more was
+implemented using specials and special colors where the color served as reference
+to some special extension. This works quite well. In \LUATEX\ the pre- and
+postscript features, which are properties of picture objects, are used.
+
+In all cases, some information about the current run, for instance layout related
+information, or color information, has to be passed to the rather isolated
+\METAPOST\ run. In the case if \LUATEX\ (and \MKIV) the advantage is that
+processing optional text happens in the same process so there we don't need to
+pass information about for instance the current font setup.
+
+In \LUATEX\ the \METAPOST\ library has a \type {runscript} feature, which will
+call \LUA\ with the given code. This permitted a better integration: we could now
+ask for specific information (to the \TEX\ end) instead of passing it from the
+\TEX\ end with each run. In \LUAMETATEX\ another feature was added: access to the
+scanners from the \LUA\ end. Although we could already fetch some variables when
+in \LUA\ this made it possible to extend the \METAPOST\ language in ways not
+possible before.
+
+Already for a while Alan Braslau and I were working on some new \METAFUN\ code
+that exploits all these new features. When the scanners came available I sat down
+and started working on new interfaces and in this manual I will discuss some of
+these. Some of them are illustrative, others are probably rather useful. The core
+of what we could call \LUAMETAFUN\ (or \METAFUN\ XL when we use the file
+extension as indicator) is a key|-|value interface as we have at the \TEX\ end.
+This interface relates to \CONTEXT\ \LMTX\ development and therefore related
+files have a different suffix: \type {mpxl}. However, keep in mind that some are
+just wrappers around regular \METAPOST\ code so you have the full power of
+traditional \METAPOST\ at hand.
+
+We can never satisfy all needs, so to some extent this manual also demonstrates
+how to roll out your own code, but for that you also need to peek into the
+\METAFUN\ source code too. It will take a while for this manual to complete. I
+also expect other users to come up with solutions, so maybe in the end we will
+have a collection of modules for specific tasks.
+
+\startlines
+Hans Hagen
+Hasselt NL
+August 2019 (and beyond)
+\stoplines
+
+\stopchapter
+
+\stopcomponent
+
+% I started writing this in 2019, a few days after seeing Wende live in Zeist (
+% (YT: WENDE - # MENS), one of the best shows of that year, a clear reminder of
+% timeless versatility.
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-mesh-examples.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-mesh-examples.tex
new file mode 100644
index 00000000000..87f6d105fbe
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-mesh-examples.tex
@@ -0,0 +1,161 @@
+\startbuffer[1]
+\startuseMPgraphic{MyPath1}
+ fill OverlayBox withcolor "darkyellow" ;
+ save p ; path p[] ;
+ p1 := unitsquare xysized( OverlayWidth/4, OverlayHeight/4) ;
+ p2 := unitsquare xysized(2OverlayWidth/4,3OverlayHeight/5) shifted ( OverlayWidth/4,0) ;
+ p3 := unitsquare xysized( OverlayWidth/4, OverlayHeight ) shifted (3OverlayWidth/4,0) ;
+ fill p1 withcolor "darkred" ;
+ fill p2 withcolor "darkblue" ;
+ fill p3 withcolor "darkgreen" ;
+ draw lmt_mesh [ paths = { p1, p2, p3 } ] ;
+ setbounds currentpicture to OverlayBox ;
+\stopuseMPgraphic
+\stopbuffer
+
+\startbuffer[2]
+\startuseMPgraphic{MyPath2}
+ save q ; path q ; q := unitcircle xysized(OverlayWidth,OverlayHeight) ;
+ save p ; path p ; p := for i=1 upto length(q) :
+ (center q) -- (point (i-1) of q) -- (point i of q) -- (center q) --
+ endfor cycle ;
+ fill q withcolor "darkgray" ;
+ draw lmt_mesh [
+ trace = true,
+ paths = { p }
+ ] withcolor "darkred" ;
+
+ setbounds currentpicture to OverlayBox ;
+\stopuseMPgraphic
+\stopbuffer
+
+\startbuffer[3]
+\startuseMPgraphic{MyPath3}
+ save q ; path q ; q := unitcircle xysized(OverlayWidth,OverlayHeight) randomized 3mm ;
+ fill q withcolor "darkgray" ;
+ draw lmt_mesh [
+ trace = true,
+ paths = { meshed(q,OverlayBox,.05) }
+ ] withcolor "darkgreen" ;
+ % draw OverlayMesh(q,.025) withcolor "darkgreen" ;
+ setbounds currentpicture to OverlayBox ;
+\stopuseMPgraphic
+\stopbuffer
+
+\startbuffer[4]
+\startuseMPgraphic{MyPath4}
+ save q ; path q ; q := unitcircle xysized(OverlayWidth,OverlayHeight) randomized 3mm ;
+ fill q withcolor "darkgray" ;
+ draw lmt_mesh [
+ trace = true,
+ auto = true,
+ step = 0.0125,
+ paths = { q }
+ ] withcolor "darkyellow" ;
+ setbounds currentpicture to OverlayBox ;
+\stopuseMPgraphic
+\stopbuffer
+
+\startbuffer[5]
+\startuseMPgraphic{MyPath5}
+ save q ; path q ; q := unitdiamond xysized(OverlayWidth,OverlayHeight) randomized 2mm ;
+ q := q shifted - center q shifted center OverlayBox ;
+ fill q withcolor "darkgray" ;
+ draw lmt_mesh [
+ trace = true,
+ auto = true,
+ step = 0.0125,
+ paths = { q }
+ ] withcolor "darkmagenta" ;
+ setbounds currentpicture to OverlayBox ;
+\stopuseMPgraphic
+\stopbuffer
+
+\startbuffer[6]
+\startuseMPgraphic{MyPath6}
+ save p ; path p[] ;
+ p1 := p2 := fullcircle xysized(2OverlayWidth/5,2OverlayHeight/3) ;
+ p1 := p1 shifted - center p1 shifted center OverlayBox shifted (-1OverlayWidth/4,0) ;
+ p2 := p2 shifted - center p2 shifted center OverlayBox shifted ( 1OverlayWidth/4,0) ;
+ fill p1 withcolor "middlegray" ;
+ fill p2 withcolor "middlegray" ;
+ draw lmt_mesh [
+ trace = true,
+ auto = true,
+ step = 0.02,
+ paths = { p1, p2 }
+ ] withcolor "darkcyan" ;
+ setbounds currentpicture to OverlayBox ;
+\stopuseMPgraphic
+\stopbuffer
+
+\startbuffer[7]
+\startuseMPgraphic{MyPath7}
+ save p ; path p[] ;
+ p1 := p2 := fullcircle xysized(2OverlayWidth/5,2OverlayHeight/3) rotated 45 ;
+ p1 := p1 shifted - center p1 shifted center OverlayBox shifted (-1OverlayWidth/4,0) ;
+ p2 := p2 shifted - center p2 shifted center OverlayBox shifted ( 1OverlayWidth/4,0) ;
+ fill p1 withcolor "middlegray" ;
+ fill p2 withcolor "middlegray" ;
+ draw lmt_mesh [
+ trace = true,
+ auto = true,
+ step = 0.01,
+ box = OverlayBox enlarged -5mm,
+ paths = { p1, p2 }
+ ] withcolor "darkcyan" ;
+ draw OverlayBox enlarged -5mm withcolor "darkgray" ;
+ setbounds currentpicture to OverlayBox ;
+\stopuseMPgraphic
+\stopbuffer
+
+\continueifinputfile {luametafun-mesh-examples.tex}
+
+\setupbodyfont[dejavu]
+
+\setupinteraction
+ [state=start,
+ color=white,
+ contrastcolor=white]
+
+\starttext
+
+ \getbuffer[1,2,3,4,5,6,7]
+
+ \defineoverlay[MyPath1][\useMPgraphic{MyPath1}]
+ \defineoverlay[MyPath2][\useMPgraphic{MyPath2}]
+ \defineoverlay[MyPath3][\useMPgraphic{MyPath3}]
+ \defineoverlay[MyPath4][\useMPgraphic{MyPath4}]
+ \defineoverlay[MyPath5][\useMPgraphic{MyPath5}]
+ \defineoverlay[MyPath6][\useMPgraphic{MyPath6}]
+ \defineoverlay[MyPath7][\useMPgraphic{MyPath7}]
+
+ \startTEXpage
+ \button[height=3cm,width=4cm,background=MyPath1,frame=off]{Example 1}[realpage(2)]
+ \stopTEXpage
+
+ \startTEXpage
+ \button[height=3cm,width=4cm,background=MyPath2,frame=off]{Example 2}[realpage(3)]
+ \stopTEXpage
+
+ \startTEXpage
+ \button[height=3cm,width=4cm,background=MyPath3,frame=off]{Example 3}[realpage(4)]
+ \stopTEXpage
+
+ \startTEXpage
+ \button[height=3cm,width=4cm,background=MyPath4,frame=off]{Example 4}[realpage(5)]
+ \stopTEXpage
+
+ \startTEXpage
+ \button[height=3cm,width=4cm,background=MyPath5,frame=off]{Example 5}[realpage(6)]
+ \stopTEXpage
+
+ \startTEXpage
+ \button[height=3cm,width=4cm,background=MyPath6,frame=off]{Example 6}[realpage(7)]
+ \stopTEXpage
+
+ \startTEXpage
+ \button[height=3cm,width=4cm,background=MyPath7,frame=off]{Example 7}[realpage(1)]
+ \stopTEXpage
+
+\stoptext
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-mesh.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-mesh.tex
new file mode 100644
index 00000000000..2fdb3125051
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-mesh.tex
@@ -0,0 +1,78 @@
+% language=us
+
+\environment luametafun-style
+\environment luametafun-mesh-examples
+
+\startcomponent luametafun-mesh
+
+\startchapter[title={Mesh}]
+
+This is more a gimmick than of real practical use. A mesh is a set of paths that
+gets transformed into hyperlinks. So, as a start you need to enable these:
+
+\starttyping[option=TEX]
+\setupinteraction
+ [state=start,
+ color=white,
+ contrastcolor=white]
+\stoptyping
+
+We just give a bunch of examples of meshes. A path is divided in smaller paths and
+each of them is part of the same hyperlink. An application is for instance clickable
+maps but (so far) only Acrobat supports such paths.
+
+\typebuffer[1][option=TEX]
+
+Such a definition is used as follows. First we define the mesh as overlay:
+
+\starttyping[option=TEX]
+\defineoverlay[MyPath1][\useMPgraphic{MyPath1}]
+\stoptyping
+
+Then, later on, this overlay can be used as background for a button. Here we just
+jump to another page. The rendering is shown in \in {figure} [mesh:1].
+
+\starttyping[option=TEX]
+\button
+ [height=3cm,
+ width=4cm,
+ background=MyPath1,
+ frame=off]
+ {Example 1}
+ [realpage(2)]
+\stoptyping
+
+\startplacefigure[reference=mesh:1]
+ \externalfigure[luametafun-mesh-examples][page=1,width=.45\textwidth]
+\stopplacefigure
+
+More interesting are non|-|rectangular shapes so we show a bunch of them. You can
+pass multiple paths, influence the accuracy by setting the number of steps and show
+the mesh with the tracing option.
+
+\typebuffer[2][option=TEX]
+\typebuffer[3][option=TEX]
+\typebuffer[4][option=TEX]
+\typebuffer[5][option=TEX]
+\typebuffer[6][option=TEX]
+\typebuffer[7][option=TEX]
+
+This is typical a feature that, if used at all, needs some experimenting but at
+least the traced images look interesting enough. The six examples are shown in
+\in {figure} [mesh:2].
+
+\startplacefigure[reference=mesh:2]
+ \startcombination[2*3]
+ {\externalfigure[luametafun-mesh-examples][page=2,width=.45\textwidth]} {\type {MyPath2}}
+ {\externalfigure[luametafun-mesh-examples][page=3,width=.45\textwidth]} {\type {MyPath3}}
+ {\externalfigure[luametafun-mesh-examples][page=4,width=.45\textwidth]} {\type {MyPath4}}
+ {\externalfigure[luametafun-mesh-examples][page=5,width=.45\textwidth]} {\type {MyPath5}}
+ {\externalfigure[luametafun-mesh-examples][page=6,width=.45\textwidth]} {\type {MyPath6}}
+ {\externalfigure[luametafun-mesh-examples][page=7,width=.45\textwidth]} {\type {MyPath7}}
+ \stopcombination
+\stopplacefigure
+
+\stopchapter
+
+\stopcomponent
+
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-outline.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-outline.tex
new file mode 100644
index 00000000000..e2cdb422667
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-outline.tex
@@ -0,0 +1,188 @@
+% language=us
+
+\environment luametafun-style
+
+\startcomponent luametafun-outline
+
+\startchapter[title={Outline}]
+
+In a regular text you can have outline characters by setting a (pseudo) font
+feature but sometimes you want to play a bit more with this. In \METAFUN\ we
+always had that option. In \MKII\ we call \type {pstoedit} to turn text into
+outlines, in \MKIV\ we do that by manipulating the shapes directly. And, as with
+some other extensions, in \LMTX\ a new interface has been added, but the
+underlying code is the same as in \MKIV.
+
+\startbuffer[1a]
+\startMPcode{doublefun}
+ draw lmt_outline [
+ text = "hello"
+ kind = "draw",
+ drawcolor = "darkblue",
+ ] xsized .45TextWidth ;
+\stopMPcode
+\stopbuffer
+
+\startbuffer[1b]
+\startMPcode{doublefun}
+ draw lmt_outline [
+ text = "hello",
+ kind = "both",
+ fillcolor = "middlegray",
+ drawcolor = "darkgreen",
+ rulethickness = 1/5,
+ ] xsized .45TextWidth ;
+\stopMPcode
+\stopbuffer
+
+In \in {figure} [outline:1] we see two examples:
+
+\typebuffer[1a][option=TEX]
+
+and
+
+\typebuffer[1b][option=TEX]
+
+\startplacefigure[reference=outline:1,title={Drawing and|/|or filling an outline.}]
+ \startcombination
+ {\getbuffer[1a]} {\type {kind=draw}}
+ {\getbuffer[1b]} {\type {kind=both}}
+ \stopcombination
+\stopplacefigure
+
+Normally the fill ends up below the draw but we can reverse the order, as in
+\in {figure} [outline:2], where we coded the leftmost example as:
+
+\startbuffer[2a]
+\startMPcode{doublefun}
+ draw lmt_outline [
+ text = "hello",
+ kind = "reverse",
+ fillcolor = "darkred",
+ drawcolor = "darkblue",
+ rulethickness = 1/2,
+ ] xsized .45TextWidth ;
+\stopMPcode
+\stopbuffer
+
+\startbuffer[2b]
+\startMPcode{doublefun}
+ draw lmt_outline [
+ text = "hello",
+ kind = "both",
+ fillcolor = "darkred",
+ drawcolor = "darkblue",
+ rulethickness = 1/2,
+ ] xsized .45TextWidth ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[2a][option=TEX]
+
+\startplacefigure[reference=outline:2,title={Reversing the order of drawing and filling.}]
+ \startcombination
+ {\getbuffer[2a]} {\type {kind=reverse}}
+ {\getbuffer[2b]} {\type {kind=both}}
+ \stopcombination
+\stopplacefigure
+
+It is possible to fill and draw in one operation, in which case the same color is
+used for both, see \in {figure} [outline:3] for an example fo this. This is a low
+level optimization where the shape is only output once.
+
+\startbuffer[3a]
+\startMPcode{doublefun}
+ draw lmt_outline [
+ text = "hello",
+ kind = "fillup",
+ fillcolor = "darkgreen",
+ rulethickness = 1/5,
+ ] xsized .45TextWidth ;
+\stopMPcode
+\stopbuffer
+
+\startbuffer[3b]
+\startMPcode{doublefun}
+ draw lmt_outline [
+ text = "hello",
+ kind = "fill",
+ fillcolor = "darkgreen",
+ rulethickness = 1/5,
+ ] xsized .45TextWidth ;
+\stopMPcode
+\stopbuffer
+
+\startplacefigure[reference=outline:3,title={Combining a fill with a draw in the same color.}]
+ \startcombination
+ {\getbuffer[3a]} {\type {kind=fillup}}
+ {\getbuffer[3b]} {\type {kind=fill}}
+ \stopcombination
+\stopplacefigure
+
+
+This interface is much nicer than the one where each variant (the parameter \type
+{kind} above) had its own macro due to the need to group properties of the
+outline and fill. Let's show some more:
+
+\startbuffer[4]
+\startMPcode{doublefun}
+ draw lmt_outline [
+ text = "\obeydiscretionaries\samplefile{tufte}",
+ align = "normal",
+ kind = "draw",
+ drawcolor = "darkblue",
+ ] xsized TextWidth ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[4][option=TEX]
+
+In this case we feed the text into the \type {\framed} macro so that we get a
+properly aligned paragraph of text, as demonstrated in \in {figure} [outline:4]
+\in {and} [outline:5]. If you want more trickery you can of course use any
+\CONTEXT\ command (including \type {\framed} with all kind of options) in the
+text.
+
+\startplacefigure[reference=outline:4,title={Outlining a paragraph of text.}]
+ \getbuffer[4]
+\stopplacefigure
+
+\startbuffer[5]
+\startMPcode{doublefun}
+ draw lmt_outline [
+ text = "\obeydiscretionaries\samplefile{ward}",
+ align = "normal,tolerant",
+ style = "bold",
+ width = 10cm,
+ kind = "draw",
+ drawcolor = "darkblue",
+ ] xsized TextWidth ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[5][option=TEX]
+
+\startplacefigure[reference=outline:4,title={Outlining a paragraph of text with a specific width.}]
+ \getbuffer[5]
+\stopplacefigure
+
+We summarize the parameters:
+
+\starttabulate[|T|T|T|p|]
+\FL
+\BC name \BC type \BC default \BC comment \NC \NR
+\ML
+\NC text \NC string \NC \NC \NC \NR
+\NC kind \NC string \NC draw \NC One of \type {draw}, \type {fill}, \type {both}, \type {reverse} and \type {fillup}. \NC \NR
+\NC fillcolor \NC string \NC \NC \NC \NR
+\NC drawcolor \NC string \NC \NC \NC \NR
+\NC rulethickness \NC numeric \NC 1/10 \NC \NC \NR
+\NC align \NC string \NC \NC \NC \NR
+\NC style \NC string \NC \NC \NC \NR
+\NC width \NC numeric \NC \NC \NC \NR
+\LL
+\stoptabulate
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-placeholder.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-placeholder.tex
new file mode 100644
index 00000000000..3627bbfd04f
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-placeholder.tex
@@ -0,0 +1,163 @@
+% language=us
+
+\environment luametafun-style
+
+\startcomponent luametafun-placeholder
+
+\startchapter[title={Placeholder}]
+
+Placeholders are an old \CONTEXT\ features and have been around since we started using
+\METAPOST. They are used as dummy figure, just in case one is not (yet) present. They
+are normally activated by loading a \METAFUN\ library:
+
+\starttyping[option=TEX]
+\useMPLibrary[dum]
+\stoptyping
+
+Just because it could be done conveniently, placeholders are now defined at the
+\METAPOST\ end instead of as useable \METAPOST\ graphic at the \TEX\ end. The
+variants and options are demonstrated using side floats.
+
+\startbuffer[1]
+\startMPcode
+ lmt_placeholder [
+ width = 4cm,
+ height = 3cm,
+ color = "red",
+ alternative = "circle".
+ ] ;
+\stopMPcode
+\stopbuffer
+
+\startplacefigure[location=left]
+ \getbuffer[1]
+\stopplacefigure
+
+\typebuffer[1][option=TEX]
+
+In addition to the traditional random circle we now also provide rectangles
+and triangles. Maybe some day more variants will show up.
+
+\startbuffer[2]
+\startMPcode
+ lmt_placeholder [
+ width = 4cm,
+ height = 3cm,
+ color = "green",
+ alternative = "square".
+ ] ;
+\stopMPcode
+\stopbuffer
+
+\startplacefigure[location=left]
+ \getbuffer[2]
+\stopplacefigure
+
+\typebuffer[2][option=TEX]
+
+Here we set the colors but in the image placeholder mechanism we cycle through
+colors automatically. Here we use primary, rather dark, colors.
+
+\startbuffer[3]
+\startMPcode
+ lmt_placeholder [
+ width = 4cm,
+ height = 3cm,
+ color = "blue",
+ alternative = "triangle".
+ ] ;
+\stopMPcode
+\stopbuffer
+
+\startplacefigure[location=left]
+ \getbuffer[3]
+\stopplacefigure
+
+\typebuffer[3][option=TEX]
+
+\startbuffer[4a]
+\startMPcode
+ lmt_placeholder [
+ width = 4cm,
+ height = 3cm,
+ color = "yellow",
+ alternative = "circle".
+ reduction = 0,
+ ] ;
+\stopMPcode
+\stopbuffer
+
+\startbuffer[4b]
+\startMPcode
+ lmt_placeholder [
+ width = 4cm,
+ height = 3cm,
+ color = "yellow",
+ alternative = "circle".
+ reduction = 0.25,
+ ] ;
+\stopMPcode
+\stopbuffer
+
+\startbuffer[4c]
+\startMPcode
+ lmt_placeholder [
+ width = 4cm,
+ height = 3cm,
+ color = "yellow",
+ alternative = "circle".
+ reduction = 0.50,
+ ] ;
+\stopMPcode
+\stopbuffer
+
+\startbuffer[4d]
+\startMPcode
+ lmt_placeholder [
+ width = 4cm,
+ height = 3cm,
+ color = "yellow",
+ alternative = "circle".
+ reduction = 0.75,
+ ] ;
+\stopMPcode
+\stopbuffer
+
+If you want less dark colors, the \type {reduction} parameter can be used to
+interpolate between the given color and white; its value is therefore a value
+between zero (default) and 1 (rather pointless as it produces white).
+
+\startplacefigure[location=left]
+ \startcombination[2*2]
+ {\getbuffer[4a]} {0}
+ {\getbuffer[4b]} {0.25}
+ {\getbuffer[4c]} {0.50}
+ {\getbuffer[4d]} {0.75}
+ \stopcombination
+\stopplacefigure
+
+We demonstrate this with four variants, all circles. Of course you can also use
+lighter colors, but this option was needed for the image placeholders anyway.
+
+\typebuffer[4b][option=TEX]
+
+\flushsidefloats
+
+There are only a few possible parameters. As you can see, proper dimensions need
+to be given because the defaults are pretty small.
+
+\starttabulate[|T|T|T|p|]
+\FL
+\BC name \BC type \BC default \BC comment \NC \NR
+\ML
+\NC color \NC string \NC red \NC \NC \NR
+\NC width \NC numeric \NC 1 \NC \NC \NR
+\NC height \NC numeric \NC 1 \NC \NC \NR
+\NC reduction \NC numeric \NC 0 \NC \NC \NR
+\NC alternative \NC string \NC circle \NC \NC \NR
+\LL
+\stoptabulate
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-shade.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-shade.tex
new file mode 100644
index 00000000000..a139be95460
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-shade.tex
@@ -0,0 +1,230 @@
+% language=us
+
+\environment luametafun-style
+
+\startcomponent luametafun-shade
+
+\startchapter[title={Shade}]
+
+{\em This interface is still experimental!}
+
+Shading is complex. We go from one color to another on a continuum either linear
+or circular. We have to make sure that we cover the whole shape and that means
+that we have to guess a little, although one can influence this with parameters.
+It can involve a bit of trial and error, which is more complex that using a
+graphical user interface but this is the price we pay. It goes like this:
+
+\startbuffer[1]
+\startMPcode
+definecolor [ name = "MyColor3", r = 0.22, g = 0.44, b = 0.66 ] ;
+definecolor [ name = "MyColor4", r = 0.66, g = 0.44, b = 0.22 ] ;
+
+draw lmt_shade [
+ path = fullcircle scaled 4cm,
+ direction = "right",
+ domain = { 0, 2 },
+ colors = { "MyColor3", "MyColor4" },
+] ;
+
+draw lmt_shade [
+ path = fullcircle scaled 3cm,
+ direction = "left",
+ domain = { 0, 2 },
+ colors = { "MyColor3", "MyColor4" },
+] shifted (45mm,0) ;
+
+draw lmt_shade [
+ path = fullcircle scaled 5cm,
+ direction = "up",
+ domain = { 0, 2 },
+ colors = { "MyColor3", "MyColor4" },
+] shifted (95mm,0) ;
+
+draw lmt_shade [
+ path = fullcircle scaled 1cm,
+ direction = "down",
+ domain = { 0, 2 },
+ colors = { "MyColor3", "MyColor4" },
+] shifted (135mm,0) ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[1][option=TEX]
+
+Normally this is good enough as demonstrated in \in {figure} [shade:1] because
+we use shades as backgrounds. In the case of a circular shade we need to tweak
+the domain because guessing doesn't work well.
+
+\startplacefigure[reference=shade:1,title={Simple circular shades.}]
+ \getbuffer[1]
+\stopplacefigure
+
+\startbuffer[2]
+\startMPcode
+draw lmt_shade [
+ path = fullsquare scaled 4cm,
+ alternative = "linear",
+ direction = "right",
+ colors = { "MyColor3", "MyColor4" },
+] ;
+
+draw lmt_shade [
+ path = fullsquare scaled 3cm,
+ direction = "left",
+ alternative = "linear",
+ colors = { "MyColor3", "MyColor4" },
+] shifted (45mm,0) ;
+
+draw lmt_shade [
+ path = fullsquare scaled 5cm,
+ direction = "up",
+ alternative = "linear",
+ colors = { "MyColor3", "MyColor4" },
+] shifted (95mm,0) ;
+
+draw lmt_shade [
+ path = fullsquare scaled 1cm,
+ direction = "down",
+ alternative = "linear",
+ colors = { "MyColor3", "MyColor4" },
+] shifted (135mm,0) ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[2][option=TEX]
+
+\startplacefigure[reference=shade:2,title={Simple rectangular shades.}]
+ \getbuffer[2]
+\stopplacefigure
+
+The \type {direction} relates to the boundingbox. Instead of a keyword you can
+also give two values, indicating points on the boundingbox. Because a boundingbox
+has four points, the \type {up} direction is equivalent to \type {{0.5,2.5}}.
+
+The parameters \type {center}, \type {factor}, \type {vector} and \type {domain}
+are a bit confusing but at some point the way they were implemented made sense,
+so we keep them as they are. The center moves the center of the path that is used
+as anchor for one color proportionally to the bounding box: the given factor is
+multiplied by half the width and height.
+
+\startbuffer[3]
+\startMPcode
+draw lmt_shade [
+ path = fullcircle scaled 5cm,
+ domain = { .2, 1.6 },
+ center = { 1/10, 1/10 },
+ direction = "right",
+ colors = { "MyColor3", "MyColor4" },
+ trace = true,
+] ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[3][option=TEX]
+
+\startplacefigure[reference=shade:3,title={Moving the centers.}]
+ \getbuffer[3]
+\stopplacefigure
+
+A vector takes the given points on the path as centers for the colors, see \in
+{figure} [shade:4].
+
+\startbuffer[4]
+\startMPcode
+draw lmt_shade [
+ path = fullcircle scaled 5cm,
+ domain = { .2, 1.6 },
+ vector = { 2, 4 },
+ direction = "right",
+ colors = { "MyColor3", "MyColor4" },
+ trace = true,
+] ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[4][option=TEX]
+
+\startplacefigure[reference=shade:4,title={Using a vector (points).}]
+ \getbuffer[4]
+\stopplacefigure
+
+Messing with the radius in combination with the previously mentioned domain
+is really trial and error, as seen in \in {figure} [shade:5].
+
+\startbuffer[5]
+\startMPcode
+draw lmt_shade [
+ path = fullcircle scaled 5cm,
+ domain = { 0.5, 2.5 },
+ radius = { 2cm, 6cm },
+ direction = "right",
+ colors = { "MyColor3", "MyColor4" },
+ trace = true,
+] ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[5][option=TEX]
+
+\startplacefigure[reference=shade:5,title={Tweaking the radius.}]
+ \getbuffer[5]
+\stopplacefigure
+
+But actually the radius used alone works quite well as shown in \in {figure}
+[shade:6].
+
+\startbuffer[6]
+\startMPcode
+draw lmt_shade [
+ path = fullcircle scaled 5cm,
+ colors = { "red", "green" },
+ trace = true,
+] ;
+
+draw lmt_shade [
+ path = fullcircle scaled 5cm,
+ colors = { "red", "green" },
+ radius = 2.5cm,
+ trace = true,
+] shifted (6cm,0) ;
+
+draw lmt_shade [
+ path = fullcircle scaled 5cm,
+ colors = { "red", "green" },
+ radius = 2.0cm,
+ trace = true,
+] shifted (12cm,0) ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[6][option=TEX]
+
+\startplacefigure[reference=shade:6,title={Just using the radius.}]
+ \getbuffer[6]
+\stopplacefigure
+
+\starttabulate[|T|T|T|p|]
+\FL
+\BC name \BC type \BC default \BC comment \NC \NR
+\ML
+\NC alternative \NC string \NC circular \NC or \type {linear} \NC \NR
+\NC path \NC path \NC \NC \NC \NR
+\NC trace \NC boolean \NC false \NC \NC \NR
+\NC domain \NC set of numerics \NC \NC \NC \NR
+\NC radius \NC numeric \NC \NC \NC \NR
+\NC \NC set of numerics \NC \NC \NC \NR
+\NC factor \NC numeric \NC \NC \NC \NR
+\NC origin \NC pair \NC \NC \NC \NR
+\NC \NC set of pairs \NC \NC \NC \NR
+\NC vector \NC set of numerics \NC \NC \NC \NR
+\NC colors \NC set of strings \NC \NC \NC \NR
+\NC center \NC numeric \NC \NC \NC \NR
+\NC \NC set of numerics \NC \NC \NC \NR
+\NC direction \NC string \NC \NC \type{up}, \type {down}, \type {left}, \type {right} \NC \NR
+\NC \NC set of numerics \NC \NC two points on the boundingbox \NC \NR
+\LL
+\stoptabulate
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-style.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-style.tex
new file mode 100644
index 00000000000..63eb7e3755e
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-style.tex
@@ -0,0 +1,64 @@
+\startenvironment luametafun-style
+
+\usemodule[abbreviations-smallcaps]
+
+\usemodule[scite]
+
+\setupbodyfont
+ [ibmplex,rm,10pt]
+
+\setupwhitespace
+ [big]
+
+\setuplayout
+ [topspace=10mm,
+ bottomspace=1cm,
+ backspace=2cm,
+ footerdistance=10mm,
+ footer=1cm,
+ % headerdistance=10mm,
+ % header=1cm,
+ topspace=20mm,
+ headerdistance=0mm,
+ header=0cm,
+ height=middle,
+ width=middle]
+
+\setupalign
+ [verytolerant]
+
+\setupheadertexts
+ []
+
+\setupfootertexts
+ [chapter][pagenumber]
+
+\setuphead
+ [chapter]
+ [color=darkgray,
+ style=\bfd]
+
+\setuphead
+ [section]
+ [color=darkgray,
+ style=\bfc]
+
+\setupfooter
+ [color=darkgray,
+ style=\bf]
+
+\setuplist
+ [chapter]
+ [before=,
+ after=]
+
+% sectionblocks keep things local and we need these colors very late,
+% when we flush fonts
+
+\definecolor[KindergartenEqual] [darkgreen]
+\definecolor[KindergartenPlus] [darkred]
+\definecolor[KindergartenMinus] [darkred]
+\definecolor[KindergartenTimes] [darkblue]
+\definecolor[KindergartenDivided][darkblue]
+
+\stopenvironment
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-surface.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-surface.tex
new file mode 100644
index 00000000000..0014fa7251d
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-surface.tex
@@ -0,0 +1,96 @@
+% language=us
+
+\environment luametafun-style
+
+\startcomponent luametafun-surface
+
+\startchapter[title={Surface}]
+
+This is work in progress so only some examples are shown here. Yet to be decided
+is how we deal with axis and such.
+
+In \in {figure} [surface:1] we see an example of a plot with axis as well as
+lines drawn.
+
+\startbuffer[1]
+\startMPcode{doublefun}
+ draw lmt_surface [
+ preamble = "local sin, cos = math.sin, math.cos",
+ code = "sin(x*x) - cos(y*y)"
+ xmin = -3,
+ xmax = 3,
+ ymin = -3,
+ ymax = 3,
+ xvector = { -0.3, -0.3 },
+ height = 5cm,
+ axis = { 40mm, 40mm, 30mm },
+ clipaxis = true,
+ axiscolor = "gray",
+ ] xsized .8TextWidth ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[1]
+
+\startplacefigure[reference=surface:1]
+ \getbuffer[1]
+\stopplacefigure
+
+In \in {figure} [surface:2] we don't draw the axis and lines. We also use a high
+resolution.
+
+\startbuffer[2]
+\startMPcode{doublefun}
+ draw lmt_surface [
+ preamble = "local sin, cos = math.sin, math.cos",
+ code = "sin(x*x) - cos(y*y)"
+ color = "f, f/2, 1-f"
+ color = "f, f, 0"
+ xstep = .02,
+ ystep = .02,
+ xvector = { -0.4, -0.4 },
+ height = 5cm,
+ lines = false,
+ ] xsized .8TextWidth ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[2]
+
+\startplacefigure[reference=surface:2]
+ \getbuffer[2]
+\stopplacefigure
+
+The preliminary set of parameters is:
+
+\starttabulate[|T|T|T|p|]
+\FL
+\BC name \BC type \BC default \BC comment \NC \NR
+\ML
+\NC code \NC string \NC
+\NC color \NC string \NC \type {"f, 0, 0"} \NC \NC \NR
+\NC linecolor \NC numeric \NC \type {1} \NC gray scale \NC \NR
+\NC xmin \NC numeric \NC \type {-1} \NC \NC \NR
+\NC xmax \NC numeric \NC \type { 1} \NC \NC \NR
+\NC ymin \NC numeric \NC \type {-1} \NC \NC \NR
+\NC ymax \NC numeric \NC \type { 1} \NC \NC \NR
+\NC xstep \NC numeric \NC \type {.1} \NC \NC \NR
+\NC ystep \NC numeric \NC \type {.1} \NC \NC \NR
+\NC snap \NC numeric \NC \type {.01} \NC \NC \NR
+\NC xvector \NC list \NC \type {{ -0.7, -0.7 }} \NC \NC \NR
+\NC yvector \NC list \NC \type {{ 1, 0 }} \NC \NC \NR
+\NC zvector \NC list \NC \type {{ 0, 1 }} \NC \NC \NR
+\NC light \NC list \NC \type {{ 3, 3, 10 }} \NC \NC \NR
+\NC bright \NC numeric \NC \type {100} \NC \NC \NR
+\NC clip \NC boolean \NC \type {false} \NC \NC \NR
+\NC lines \NC boolean \NC \type {true} \NC \NC \NR
+\NC axis \NC list \NC \type {{ }} \NC \NC \NR
+\NC clipaxis \NC boolean \NC \type {false} \NC \NC \NR
+\NC axiscolor \NC string \NC \type {"gray"} \NC \NC \NR
+\NC axislinewidth \NC numeric \NC \type {1/2} \NC \NC \NR
+\LL
+\stoptabulate
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-svg.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-svg.tex
new file mode 100644
index 00000000000..069abc6a68b
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-svg.tex
@@ -0,0 +1,75 @@
+% language=us
+
+\environment luametafun-style
+
+\startcomponent luametafun-svg
+
+\startchapter[title={SVG}]
+
+There is not that much to tell about this command. It translates an \SVG\ image
+to \METAPOST\ operators. We took a few images from a mozilla emoji font:
+
+\startbuffer[2]
+\startMPcode
+ draw lmt_svg [
+ filename = "mozilla-svg-002.svg",
+ height = 2cm,
+ width = 8cm,
+ ] ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[2][option=TEX]
+
+\startlinecorrection
+ \getbuffer[2]
+\stoplinecorrection
+
+Because we get pictures, you can mess around with them:
+
+\startbuffer[1]
+\startMPcode
+ picture p ; p := lmt_svg [ filename = "mozilla-svg-001.svg" ] ;
+ numeric w ; w := bbwidth(p) ;
+ draw p ;
+ draw p xscaled -1 shifted (2.5*w,0);
+ draw p rotatedaround(center p,45) shifted (3.0*w,0) ;
+ draw image (
+ for i within p : if filled i :
+ draw pathpart i withcolor green ;
+ fi endfor ;
+ ) shifted (4.5*w,0);
+ draw image (
+ for i within p : if filled i :
+ fill pathpart i withcolor red withtransparency (1,.25) ;
+ fi endfor ;
+ ) shifted (6*w,0);
+\stopMPcode
+\stopbuffer
+
+\typebuffer[1][option=TEX]
+
+\startlinecorrection
+ \getbuffer[1]
+\stoplinecorrection
+
+Of course. often you won't know in advance what is inside the image and how (well)
+it has been defined so the previous example is more about showing some \METAPOST\
+muscle.
+
+The supported parameters are:
+
+\starttabulate[|T|T|T|p|]
+\FL
+\BC name \BC type \BC default \BC comment \NC \NR
+\ML
+\NC filename \NC path \NC \NC \NC \NR
+\NC width \NC numeric \NC \NC \NC \NR
+\NC height \NC numeric \NC \NC \NC \NR
+\LL
+\stoptabulate
+
+\stopchapter
+
+\stopcomponent
+
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-text.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-text.tex
new file mode 100644
index 00000000000..4f08ee00f8c
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-text.tex
@@ -0,0 +1,137 @@
+% language=us
+
+\environment luametafun-style
+
+\startcomponent luametafun-text
+
+\startchapter[title={Text}]
+
+The \METAFUN\ \type {textext} command normally can do the job of typesetting a
+text snippet quite well.
+
+\startbuffer
+\startMPcode
+ fill fullcircle xyscaled (8cm,1cm) withcolor "darkred" ;
+ draw textext("\bf This is text A") withcolor "white" ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+We get:
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+You can use regular \CONTEXT\ commands, so this is valid:
+
+\startbuffer
+\startMPcode
+ fill fullcircle xyscaled (8cm,1cm) withcolor "darkred" ;
+ draw textext("\framed{\bf This is text A}") withcolor "white" ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+Of course you can as well draw a frame in \METAPOST\ but the \type {\framed}
+command has more options, like alignments.
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+Here is a variant using the \METAFUN\ interface:
+
+\startbuffer
+\startMPcode
+ fill fullcircle xyscaled (8cm,1cm) withcolor "darkred" ;
+ draw lmt_text [
+ text = "This is text A",
+ color = "white",
+ style = "bold"
+ ] ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+The outcome is more or less the same:
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+Here is another example. The \type {format} option is actually why this command
+is provided.
+
+\startbuffer
+\startMPcode
+ fill fullcircle xyscaled (8cm,1cm) withcolor "darkred" ;
+ draw lmt_text [
+ text = decimal 123.45678,
+ color = "white",
+ style = "bold",
+ format = "@0.3F",
+ ] ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+The following parameters can be set:
+
+\starttabulate[|T|T|T|p|]
+\FL
+\BC name \BC type \BC default \BC comment \NC \NR
+\ML
+\NC offset \NC numeric \NC 0 \NC \NC \NR
+\NC strut \NC string \NC auto \NC adapts the dimensions to the font (\type {yes} uses the the default strut) \NC \NR
+\NC style \NC string \NC \NC \NC \NR
+\NC color \NC string \NC \NC \NC \NR
+\NC text \NC string \NC \NC \NC \NR
+\NC anchor \NC string \NC \NC one of these \type {lft}, \type {urt} like anchors \NC \NR
+\NC format \NC string \NC \NC a format specifier using \type {@} instead of a percent sign \NC \NR
+\NC position \NC pair \NC origin \NC \NC \NR
+\NC trace \NC boolean \NC false \NC \NC \NR
+\LL
+\stoptabulate
+
+The next example demonstrates the positioning options:
+
+\startbuffer
+\startMPcode
+ fill fullcircle xyscaled (8cm,1cm) withcolor "darkblue" ;
+ fill fullcircle scaled .5mm withcolor "white" ;
+ draw lmt_text [
+ text = "left",
+ color = "white",
+ style = "bold",
+ anchor = "lft",
+ position = (-1mm,2mm),
+ ] ;
+ draw lmt_text [
+ text = "right",
+ color = "white",
+ style = "bold",
+ anchor = "rt",
+ offset = 3mm,
+ ] ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-titlepage.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-titlepage.tex
new file mode 100644
index 00000000000..4450199e653
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun-titlepage.tex
@@ -0,0 +1,41 @@
+
+\environment luametafun-style
+
+\startcomponent luametafun-titlepage
+
+\startMPpage
+
+ fill Page withcolor "darkblue" ;
+
+ path p ; p := (0,0) -- (0,4) -- (2,2) -- (4,4) -- (4,0) ;
+
+ p := p scaled 20; p := p shifted - center p ;
+
+ draw image (
+ for i=1 upto 1000 :
+ draw p shifted (center Page randomized urcorner Page) ;
+ endfor ;
+ ) withcolor "darkgreen" ;
+
+ setbounds currentpicture to Page ;
+
+ draw
+ % textext.ulft("\ss luametafun")
+ textext.ulft("\ss metafun xl")
+ xsized .55bbwidth(Page)
+ shifted lrcorner Page
+ shifted (-15mm,35mm)
+ withcolor "white"
+ ;
+
+ draw
+ textext.ulft("\ss Hans Hagen")
+ xsized .3bbwidth(Page)
+ shifted lrcorner Page
+ shifted (-15mm,15mm)
+ withcolor "white"
+ ;
+
+\stopMPpage
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun.tex
new file mode 100644
index 00000000000..2dd917cdfcf
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/luametafun.tex
@@ -0,0 +1,34 @@
+\setupfootertexts[{\tttf uncorrected draft}]
+
+\environment luametafun-style
+
+\startcomponent luametafun
+
+ \component luametafun-titlepage
+
+ \startfrontmatter
+ \component luametafun-contents
+ \component luametafun-introduction
+ \stopfrontmatter
+
+ \startbodymatter
+ \component luametafun-text
+ % \component luametafun-grid
+ \component luametafun-axis
+ \component luametafun-outline
+ \component luametafun-followtext
+ \component luametafun-placeholder
+ \component luametafun-arrow
+ \component luametafun-shade
+ \component luametafun-contour
+ \component luametafun-surface
+ \component luametafun-mesh
+ \component luametafun-function
+ \component luametafun-chart
+ \component luametafun-svg
+ \component luametafun-fonts
+ \component luametafun-groups
+ \component luametafun-interface
+ \stopbodymatter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/mozilla-svg-001.svg b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/mozilla-svg-001.svg
new file mode 100644
index 00000000000..5e46d846759
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/mozilla-svg-001.svg
@@ -0,0 +1,72 @@
+<svg xmlns="http://www.w3.org/2000/svg">
+ <path fill="#d87512" d="M17.786 44.63c-.606.115-1.23.173-1.854.173-2.444 0-4.644-.864-6.04-2.375-.855-.92-1.394-2.147-1.517-3.47-.126-1.243.067-2.638.58-4.163.325-1.016.83-2.01 1.365-3.064.216-.426.437-.858.65-1.302.702-1.454 1.504-3.164 2.11-5.05.715-2.188.943-4.287.682-6.23-.267-2.102-.994-3.972-1.74-5.685a2.992 2.992 0 0 0-4.15-1.446c-.71.375-1.23 1-1.467 1.77a2.983 2.983 0 0 0 .218 2.292c.632 1.19 1.314 2.596 1.592 3.977.238 1.137.18 2.41-.184 3.897-.37 1.538-.976 3.143-1.522 4.518-.16.406-.33.816-.507 1.234-.507 1.215-1.032 2.47-1.364 3.838-.55 2.14-.666 4.152-.348 5.97.36 2.163 1.41 4.14 2.955 5.567 2.027 1.88 4.808 2.914 7.826 2.914 1.14 0 2.274-.146 3.375-.437l-.66-2.923"/>
+ <g fill="#bc600d">
+ <path d="M11.585 43.742s.387 1.248.104 3.05c0 0 2.045-.466 1.898-2.27 0 0-.815-.29-2-.78M9.19 41.484S8.98 42.94 7.93 44.43c0 0 2.103.42 2.774-1.265 0 0-.696-.66-1.515-1.68M8.398 37.21s-.926 1.432-3.23 2.322c0 0 1.514 2.303 3.53.904 0 0-.237-1.388-.3-3.226M12.964 15.833s-1.685.798-3.783 3.45c0 0 2.1 1.55 4.663 2.228 0 0 .285-3.093-.88-5.677M13.5 23.873s-2.988.544-5.57 2.794c0 0 1.615 1.708 3.583 2.62 0 0 1.678-3.39 1.987-5.414M10.32 31.73s-1.483 0-4.483.812c0 0-.01 2.873 2.94 2.823 0 0 .747-1.75 1.544-3.635"/>
+ </g>
+ <g fill="#d87512">
+ <path d="M53.33 39.37c0-4.484-35.622-4.484-35.622 0 0 10.16.05 10.25 17.81 10.25 17.762 0 17.812-.09 17.812-10.25"/>
+ <path d="M42.645 56.04c1.688 2.02 9.275.043 10.504-2.28 5.01-9.482-.006-13.58-.006-13.58l-10.5 1.313s-2.154 11.977 0 14.547"/>
+ </g>
+ <g fill="#bc600d">
+ <path d="M54.2 41.496s-.336 4.246-4.657 9.573c0 0 4.38-1.7 5.808-4.3 0 0 .448-3.02-1.15-5.274M55.08 48.69s-1.065 1.88-3.563 3.872c0 0 1.78-.03 2.576-.785 0 0 .77-1.41.987-3.086"/>
+ </g>
+ <path fill="#f29a2e" d="M35.484 60.38c1.87 2.23 8.547 2.09 10.574 0 2.904-2.995 2.78-16.656 2.904-23.314l-12.418-1.053s-3.444 21.52-1.06 24.367"/>
+ <g fill="#bc600d">
+ <path d="M48.21 53.53s-3.578-3.443-8.738-.013c0 0 5.754 2.455 7.365 5.672 0 0 1.126-2.245 1.373-5.66M48.775 46.06s-3.852-3.09-7.938 1.43c0 0 4.452-.47 7.632 3.635 0 0 .493-3.05.305-5.065"/>
+ </g>
+ <g fill="#3e4347">
+ <path d="M43.847 61.57l-.397-2.765 1.344 2.445zM40.41 61.996l.502-3.294.498 3.294zM36.713 61.3l1.317-2.26-.372 2.59z"/>
+ </g>
+ <path fill="#d87512" d="M28.388 56.04c-1.688 2.02-9.277.043-10.504-2.28-5.01-9.482.004-13.58.004-13.58l10.5 1.313s2.154 11.977 0 14.547"/>
+ <g fill="#bc600d">
+ <path d="M16.833 41.496s.336 4.246 4.657 9.573c0 0-4.38-1.7-5.807-4.3 0 0-.448-3.02 1.15-5.274M15.957 48.69s1.066 1.88 3.563 3.872c0 0-1.782-.03-2.576-.785 0 0-.772-1.41-.987-3.086"/>
+ </g>
+ <path fill="#f29a2e" d="M35.548 60.38c-1.87 2.23-8.548 2.09-10.575 0-2.904-2.995-2.78-16.656-2.904-23.314l12.417-1.053s3.446 21.52 1.06 24.367"/>
+ <g fill="#bc600d">
+ <path d="M22.822 53.53s3.58-3.443 8.74-.013c0 0-5.754 2.455-7.367 5.672 0 0-1.125-2.245-1.373-5.66M22.255 46.06s3.852-3.09 7.94 1.43c0 0-4.453-.47-7.633 3.635 0 0-.493-3.05-.307-5.065"/>
+ </g>
+ <g fill="#3e4347">
+ <path d="M26.24 61.25l1.345-2.445-.395 2.765zM29.62 61.996l.5-3.294.5 3.294zM33.375 61.63L33 59.04l1.32 2.26zM35.516 60.46c-.395-2.48-.482-4.96-.5-7.438.015-2.48.104-4.96.5-7.44.396 2.48.485 4.96.5 7.44-.018 2.48-.106 4.96-.5 7.438"/>
+ </g>
+ <path fill="#f29a2e" d="M27.777 6.994c0 3.82-2.727 6.987-6.086 6.915C11.83 13.7 15.893 2 15.893 2c3.36 0 11.885 1.176 11.885 4.994"/>
+ <path fill="#af5a31" d="M24.05 7.752c0 2.037-1.454 3.727-3.248 3.688-5.26-.11-3.093-6.353-3.093-6.353 1.792 0 6.34.628 6.34 2.665"/>
+ <path fill="#f29a2e" d="M43.26 6.994c0 3.82 2.726 6.987 6.086 6.915 9.86-.21 5.8-11.91 5.8-11.91C51.782 2 43.26 3.176 43.26 6.994"/>
+ <path fill="#af5a31" d="M46.983 7.752c0 2.037 1.455 3.727 3.247 3.688 5.26-.11 3.094-6.353 3.094-6.353-1.794 0-6.34.628-6.34 2.665"/>
+ <path fill="#f29a2e" d="M55.806 33.378c0 7.155-9.517 8.13-20.288 8.13-10.776 0-20.29-.975-20.29-8.13 0-29.96 11.596-29.14 20.29-29.14 8.69 0 20.288-.82 20.288 29.14"/>
+ <g fill="#3e4347">
+ <path d="M35.54 7.59c3.24 0 6.15 1.084 8.156 2.81-.77-2.945-4.135-5.16-8.173-5.16-4.06 0-7.442 2.238-8.186 5.204 2.01-1.753 4.938-2.855 8.204-2.855"/>
+ <path d="M35.535 11.193c2.217 0 4.21.744 5.584 1.925-.528-2.02-2.835-3.534-5.6-3.534-2.78 0-5.095 1.533-5.605 3.564 1.376-1.198 3.383-1.955 5.62-1.955"/>
+ </g>
+ <path fill="#ffe8bb" d="M29.553 43.727l-18.408-7.01 4.24-9.06s2.704 3.85 13.29 6.82l.878 9.243"/>
+ <path fill="#3e4347" d="M29.37 39.77c-7.462-1.27-16.325-6.673-16.48-6.75l.992-2.168c.184.092 8.806 5.342 15.853 6.544l-.366 2.374"/>
+ <path fill="#ffe8bb" d="M41.48 43.727l18.406-7.01-4.24-9.06s-2.704 3.85-13.29 6.82l-.876 9.243"/>
+ <path fill="#3e4347" d="M41.663 39.77c7.46-1.27 16.325-6.673 16.48-6.75l-.993-2.168c-.184.092-8.808 5.342-15.852 6.544l.365 2.374"/>
+ <g fill="#ffe8bb">
+ <path d="M43.524 45.57C38.752 42.023 41.4 33.86 41.4 33.86c-5.657 5.906-12.662 8.74-12.662 8.74 1.608 5.446 5.77 6.412 5.77 6.412-.34-1.835.663-3.302.663-3.302 1.68 2.22 5.03 2.986 5.03 2.986-1.287-1.508-.948-3.835-.948-3.835 2.326.875 4.27.71 4.27.71"/>
+ <path d="M42.29 42.97c-2.634 2.247-10.917 2.247-13.553 0-2.856-2.435-2.495-7.144.1-9.884 2.397-2.527 10.958-2.527 13.355 0 2.595 2.74 2.956 7.45.098 9.883"/>
+ </g>
+ <g fill="#3e4347">
+ <path d="M36.18 40.48a.69.69 0 0 1-.644-.477c-.227-.67-.77-3.293-.71-5.498.01-.398.325-.71.7-.698.38.01.674.343.663.74-.057 2.01.46 4.466.633 4.974.127.375-.06.786-.414.92a.607.607 0 0 1-.23.04"/>
+ <path d="M30.504 43.25c.21-.202.394-.408.582-.61.188-.204.378-.405.57-.604.385-.396.782-.78 1.2-1.145a14.125 14.125 0 0 1 2.745-1.9c.504-.263 1.032-.49 1.59-.654s1.153-.273 1.772-.253c.31.01.623.055.928.146.307.088.602.23.86.416.263.19.485.422.652.684.17.257.287.54.35.83a4.247 4.247 0 0 0-.677-.448 2.567 2.567 0 0 0-.68-.237c-.447-.088-.887-.04-1.33.06-.89.216-1.786.65-2.69 1.114-.905.466-1.818.983-2.776 1.466-.48.24-.97.473-1.48.682-.256.103-.517.202-.783.285-.27.078-.546.155-.833.167"/>
+ </g>
+ <path fill="#f15a61" d="M41.34 31.743c-1.17-.528-4.757-.57-5.83-.57-1.07 0-4.66.042-5.83.57-.832.376-.187 1.31 2.027 2.116 1.397.506 2.733.666 3.803.666 1.07 0 2.405-.16 3.805-.667 2.213-.808 2.856-1.74 2.025-2.117"/>
+ <g fill="#3e4347">
+ <path d="M29.917 23.48l1.61 5.292L26.954 26z"/>
+ <path d="M22.645 31.828c-.522 0-.932-.056-1.17-.098-2.986-.52-4.632-1.996-6.09-4.067l.185-2.472c1.52 1.446 3.953 3.76 6.28 4.167 1.156.2 2.853-.016 4.15-1.234 1.537-1.44 2.263-4.05 2.1-7.547l1.635.132c.2 4.312-.116 7.244-2.212 9.212-1.692 1.59-3.613 1.908-4.878 1.908M41.12 23.48l-1.613 5.292L44.08 26z"/>
+ <path d="M48.39 31.828c.52 0 .93-.056 1.167-.098 2.99-.52 4.637-1.996 6.09-4.067l-.182-2.472c-1.52 1.446-3.955 3.76-6.28 4.167-1.156.2-2.855-.016-4.154-1.234-1.532-1.44-2.258-4.05-2.095-7.547l-1.636.132c-.202 4.312.114 7.244 2.213 9.212 1.69 1.59 3.61 1.908 4.877 1.908"/>
+ </g>
+ <path fill="#ffe8bb" d="M30.25 22.09c-.852 5.282-3.728 5.87-6.696 5.577-2.986-.294-5.396-2.667-5.396-6.743 0-4.28 0-4.28 6.647-5.752 6.728-1.49 6 3.437 5.445 6.918"/>
+ <path fill="#3e4347" d="M29.16 22.547c-.244 2.534-2.61 4.357-5.287 4.072-2.674-.286-4.645-2.57-4.402-5.102s.28-2.75 5.108-2.237c4.83.514 4.824.737 4.582 3.267"/>
+ <path fill="#fff" d="M27.59 21.884c-.16 1.688-1.74 2.903-3.522 2.714-1.785-.19-3.096-1.712-2.936-3.4.163-1.69.186-1.835 3.406-1.493 3.22.344 3.215.49 3.053 2.18"/>
+ <g fill="#3e4347">
+ <ellipse cx="25.5" cy="21.08" rx="1.45" ry="1.647"/>
+ <path d="M31.27 17.896c.42 0 .807-.284.936-.728.16-.546-.133-1.122-.65-1.29l-5.98-1.924c-.516-.166-1.065.14-1.225.685-.155.543.136 1.12.652 1.287l5.98 1.924a.95.95 0 0 0 .288.046"/>
+ </g>
+ <path fill="#ffe8bb" d="M40.78 22.09c.855 5.282 3.73 5.87 6.7 5.577 2.984-.294 5.395-2.667 5.395-6.743 0-4.28-.002-4.28-6.646-5.752-6.73-1.49-6.01 3.437-5.45 6.918"/>
+ <path fill="#3e4347" d="M41.873 22.547c.243 2.534 2.61 4.357 5.287 4.072 2.674-.286 4.646-2.57 4.402-5.102-.242-2.533-.28-2.75-5.107-2.237-4.83.514-4.824.737-4.582 3.267"/>
+ <path fill="#fff" d="M43.44 21.884c.16 1.688 1.737 2.903 3.522 2.714 1.783-.19 3.098-1.712 2.936-3.4-.16-1.69-.188-1.835-3.404-1.493-3.22.344-3.217.49-3.054 2.18"/>
+ <g fill="#3e4347">
+ <ellipse cx="47.722" cy="20.932" rx="1.45" ry="1.647"/>
+ <path d="M39.76 17.896a.982.982 0 0 1-.935-.728c-.16-.546.132-1.122.65-1.29l5.98-1.924c.517-.166 1.063.14 1.224.685.155.543-.136 1.12-.653 1.287l-5.98 1.924a.96.96 0 0 1-.287.046"/>
+ </g>
+</svg>
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/mozilla-svg-002.svg b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/mozilla-svg-002.svg
new file mode 100644
index 00000000000..6d3126133e1
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametafun/mozilla-svg-002.svg
@@ -0,0 +1,11 @@
+<svg id="glyph651" xmlns="http://www.w3.org/2000/svg">
+ <g fill="#42cde2">
+ <path d="
+ M18.06 50.947
+ l-4.45 3.732.136-9.223
+ a.623.623 0 0 0-.146-.408
+ L11.63 42.7a.62.62 0 0 0-.873-.077
+ l-8.54 7.165
+ a.62.62 0 0 0-.076.874l1.93 2.3a.62.62 0 0 0 .875.074l3.948-3.313-.058 9.45c-.002.147.05.29.144.403l1.845 2.2a.62.62 0 0 0 .874.075l9.102-7.64a.62.62 0 0 0 .077-.874l-1.946-2.318a.623.623 0 0 0-.874-.075M36.03 33.53l-6.464 3.732 2.23-11.648a.812.812 0 0 0-.095-.548l-1.97-3.412a.8.8 0 0 0-1.09-.293l-12.41 7.166a.798.798 0 0 0-.292 1.09l1.928 3.34a.798.798 0 0 0 1.09.293l5.74-3.314-2.184 11.95a.794.794 0 0 0 .093.544l1.846 3.197a.797.797 0 0 0 1.09.29l13.234-7.637a.796.796 0 0 0 .292-1.09l-1.945-3.37a.8.8 0 0 0-1.09-.29M59.33 16.792l-7.794 2.837 4.686-12.316a.894.894 0 0 0 .003-.618l-1.497-4.114a.885.885 0 0 0-1.135-.53L38.63 7.5a.886.886 0 0 0-.53 1.136l1.466 4.03a.884.884 0 0 0 1.136.53l6.92-2.52-4.695 12.658a.888.888 0 0 0-.003.612l1.402 3.854a.888.888 0 0 0 1.137.53l15.953-5.806a.887.887 0 0 0 .53-1.137l-1.48-4.06a.887.887 0 0 0-1.136-.532"/>
+ </g>
+</svg>
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-callbacks.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-callbacks.tex
new file mode 100644
index 00000000000..e3e2a91e19a
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-callbacks.tex
@@ -0,0 +1,822 @@
+% language=uk
+
+\environment luametatex-style
+
+\startcomponent luametatex-callbacks
+
+\startchapter[reference=callbacks,title={\LUA\ callbacks}]
+
+\startsection[title={Registering callbacks}][library=callback]
+
+\topicindex{callbacks}
+
+\libindex{register}
+\libindex{list}
+\libindex{find}
+\libindex{known}
+
+This library has functions that register, find and list callbacks. Callbacks are
+\LUA\ functions that are called in well defined places. There are two kind of
+callbacks: those that mix with existing functionality, and those that (when
+enabled) replace functionality. In mosty cases the second category is expected to
+behave similar to the built in functionality because in a next step specific
+data is expected. For instance, you can replace the hyphenation routine. The
+function gets a list that can be hyphenated (or not). The final list should be
+valid and is (normally) used for constructing a paragraph. Another function can
+replace the ligature builder and|/|or kerner. Doing something else is possible
+but in the end might not give the user the expected outcome.
+
+The first thing you need to do is registering a callback:
+
+\startfunctioncall
+id = callback.register(<string> callback_name, <function> func)
+id = callback.register(<string> callback_name, nil)
+id = callback.register(<string> callback_name, false)
+\stopfunctioncall
+
+Here the \syntax {callback_name} is a predefined callback name, see below. The
+function returns the internal \type {id} of the callback or \type {nil}, if the
+callback could not be registered.
+
+\LUATEX\ internalizes the callback function in such a way that it does not matter
+if you redefine a function accidentally.
+
+Callback assignments are always global. You can use the special value \type {nil}
+instead of a function for clearing the callback.
+
+For some minor speed gain, you can assign the boolean \type {false} to the
+non|-|file related callbacks, doing so will prevent \LUATEX\ from executing
+whatever it would execute by default (when no callback function is registered at
+all). Be warned: this may cause all sorts of grief unless you know \notabene
+{exactly} what you are doing!
+
+\startfunctioncall
+<table> info =
+ callback.list()
+\stopfunctioncall
+
+The keys in the table are the known callback names, the value is a boolean where
+\type {true} means that the callback is currently set (active).
+
+\startfunctioncall
+<function> f = callback.find(callback_name)
+\stopfunctioncall
+
+If the callback is not set, \type {find} returns \type {nil}. The \type {known}
+function can be used to check if a callback is supported.
+
+\startfunctioncall
+if callback.known("foo") then ... end
+\stopfunctioncall
+
+\stopsection
+
+\startsection[title={File related callbacks}][library=callback]
+
+The behaviour documented in this subsection is considered stable in the sense that
+there will not be backward|-|incompatible changes any more.
+
+\subsection{\cbk {find_read_file}}
+
+Your callback function should have the following conventions:
+
+\startfunctioncall
+<string> actual_name =
+ function (<number> id_number, <string> asked_name)
+\stopfunctioncall
+
+Arguments:
+
+\startitemize
+
+\sym{id_number}
+
+This number is zero for the log or \prm {input} files. For \TEX's \prm {read}
+or \prm {write} the number is incremented by one, so \type {\read0} becomes~1.
+
+\sym{asked_name}
+
+This is the user|-|supplied filename, as found by \prm {input}, \prm {openin}
+or \prm {openout}.
+
+\stopitemize
+
+Return value:
+
+\startitemize
+
+\sym{actual_name}
+
+This is the filename used. For the very first file that is read in by \TEX, you
+have to make sure you return an \type {actual_name} that has an extension and
+that is suitable for use as \type {jobname}. If you don't, you will have to
+manually fix the name of the log file and output file after \LUATEX\ is finished,
+and an eventual format filename will become mangled. That is because these file
+names depend on the jobname.
+
+You have to return \type {nil} if the file cannot be found.
+
+\stopitemize
+
+\subsection{\cbk {find_data_file}}
+
+\topicindex{callbacks+data files}
+
+Your callback function should have the following conventions:
+
+\startfunctioncall
+<string> actual_name =
+ function (<string> asked_name)
+\stopfunctioncall
+
+Return \type {nil} if the file cannot be found.
+
+\subsection{\cbk {find_format_file}}
+
+\topicindex{callbacks+format file}
+
+Your callback function should have the following conventions:
+
+\startfunctioncall
+<string> actual_name =
+ function (<string> asked_name)
+\stopfunctioncall
+
+The \type {asked_name} is a format file for reading (the format file for writing
+is always opened in the current directory).
+
+\subsection{\cbk {open_read_file}}
+
+\topicindex{callbacks+opening files}
+
+Your callback function should have the following conventions:
+
+\startfunctioncall
+<table> env =
+ function (<string> file_name)
+\stopfunctioncall
+
+Argument:
+
+\startitemize
+
+\sym{file_name}
+
+The filename returned by a previous \cbk {find_read_file} or the return value of
+\type {kpse.find_file()} if there was no such callback defined.
+
+\stopitemize
+
+Return value:
+
+\startitemize
+
+\sym{env}
+
+This is a table containing at least one required and one optional callback
+function for this file. The required field is \type {reader} and the associated
+function will be called once for each new line to be read, the optional one is
+\type {close} that will be called once when \LUATEX\ is done with the file.
+
+\LUATEX\ never looks at the rest of the table, so you can use it to store your
+private per|-|file data. Both the callback functions will receive the table as
+their only argument.
+
+\stopitemize
+
+\subsubsection{\type {reader}}
+
+\topicindex{callbacks+reader}
+
+\LUATEX\ will run this function whenever it needs a new input line from the file.
+
+\startfunctioncall
+function(<table> env)
+ return <string> line
+end
+\stopfunctioncall
+
+Your function should return either a string or \type {nil}. The value \type {nil}
+signals that the end of file has occurred, and will make \TEX\ call the optional
+\type {close} function next.
+
+\subsubsection{\type {close}}
+
+\topicindex{callbacks+closing files}
+
+\LUATEX\ will run this optional function when it decides to close the file.
+
+\startfunctioncall
+function(<table> env)
+end
+\stopfunctioncall
+
+Your function should not return any value.
+
+\stopsection
+
+\startsection[title={Data processing callbacks}][library=callback]
+
+\subsection{\cbk {process_jobname}}
+
+\topicindex{callbacks+jobname}
+
+This callback allows you to change the jobname given by \prm {jobname} in \TEX\
+and \type {tex.jobname} in Lua. It does not affect the internal job name or the
+name of the output or log files.
+
+\startfunctioncall
+function(<string> jobname)
+ return <string> adjusted_jobname
+end
+\stopfunctioncall
+
+The only argument is the actual job name; you should not use \type {tex.jobname}
+inside this function or infinite recursion may occur. If you return \type {nil},
+\LUATEX\ will pretend your callback never happened. This callback does not
+replace any internal code.
+
+\stopsection
+
+\startsection[title={Node list processing callbacks}][library=callback]
+
+The description of nodes and node lists is in~\in{chapter}[nodes].
+
+\subsection{\cbk {contribute_filter}}
+
+\topicindex{callbacks+contributions}
+
+This callback is called when \LUATEX\ adds contents to list:
+
+\startfunctioncall
+function(<string> extrainfo)
+end
+\stopfunctioncall
+
+The string reports the group code. From this you can deduce from
+what list you can give a treat.
+
+\starttabulate[|l|p|]
+\DB value \BC explanation \NC \NR
+\TB
+\NC \type{pre_box} \NC interline material is being added \NC \NR
+\NC \type{pre_adjust} \NC \prm {vadjust} material is being added \NC \NR
+\NC \type{box} \NC a typeset box is being added (always called) \NC \NR
+\NC \type{adjust} \NC \prm {vadjust} material is being added \NC \NR
+\LL
+\stoptabulate
+
+\subsection{\cbk {buildpage_filter}}
+
+\topicindex{callbacks+building pages}
+
+This callback is called whenever \LUATEX\ is ready to move stuff to the main
+vertical list. You can use this callback to do specialized manipulation of the
+page building stage like imposition or column balancing.
+
+\startfunctioncall
+function(<string> extrainfo)
+end
+\stopfunctioncall
+
+The string \type {extrainfo} gives some additional information about what \TEX's
+state is with respect to the \quote {current page}. The possible values for the
+\cbk {buildpage_filter} callback are:
+
+\starttabulate[|l|p|]
+\DB value \BC explanation \NC \NR
+\TB
+\NC \type{alignment} \NC a (partial) alignment is being added \NC \NR
+\NC \type{after_output} \NC an output routine has just finished \NC \NR
+\NC \type{new_graf} \NC the beginning of a new paragraph \NC \NR
+\NC \type{vmode_par} \NC \prm {par} was found in vertical mode \NC \NR
+\NC \type{hmode_par} \NC \prm {par} was found in horizontal mode \NC \NR
+\NC \type{insert} \NC an insert is added \NC \NR
+\NC \type{penalty} \NC a penalty (in vertical mode) \NC \NR
+\NC \type{before_display} \NC immediately before a display starts \NC \NR
+\NC \type{after_display} \NC a display is finished \NC \NR
+\NC \type{end} \NC \LUATEX\ is terminating (it's all over) \NC \NR
+\LL
+\stoptabulate
+
+\subsection{\cbk {build_page_insert}}
+
+\topicindex{callbacks+inserts}
+
+This callback is called when the pagebuilder adds an insert. There is not much
+control over this mechanism but this callback permits some last minute
+manipulations of the spacing before an insert, something that might be handy when
+for instance multiple inserts (types) are appended in a row.
+
+\startfunctioncall
+function(<number> n, <number> i)
+ return <number> register
+end
+\stopfunctioncall
+
+with
+
+\starttabulate[|l|p|]
+\DB value \BC explanation \NC \NR
+\TB
+\NC \type{n} \NC the insert class \NC \NR
+\NC \type{i} \NC the order of the insert \NC \NR
+\LL
+\stoptabulate
+
+The return value is a number indicating the skip register to use for the
+prepended spacing. This permits for instance a different top space (when \type
+{i} equals one) and intermediate space (when \type {i} is larger than one). Of
+course you can mess with the insert box but you need to make sure that \LUATEX\
+is happy afterwards.
+
+\subsection{\cbk {pre_linebreak_filter}}
+
+\topicindex{callbacks+linebreaks}
+
+This callback is called just before \LUATEX\ starts converting a list of nodes
+into a stack of \prm {hbox}es, after the addition of \prm {parfillskip}.
+
+\startfunctioncall
+function(<node> head, <string> groupcode)
+ return true | false | <node> newhead
+end
+\stopfunctioncall
+
+The string called \type {groupcode} identifies the nodelist's context within
+\TEX's processing. The range of possibilities is given in the table below, but
+not all of those can actually appear in \cbk {pre_linebreak_filter}, some are
+for the \cbk {hpack_filter} and \cbk {vpack_filter} callbacks that will be
+explained in the next two paragraphs.
+
+\starttabulate[|l|p|]
+\DB value \BC explanation \NC \NR
+\TB
+\NC \type{<empty>} \NC main vertical list \NC \NR
+\NC \type{hbox} \NC \prm {hbox} in horizontal mode \NC \NR
+\NC \type{adjusted_hbox} \NC \prm {hbox} in vertical mode \NC \NR
+\NC \type{vbox} \NC \prm {vbox} \NC \NR
+\NC \type{vtop} \NC \prm {vtop} \NC \NR
+\NC \type{align} \NC \prm {halign} or \prm {valign} \NC \NR
+\NC \type{disc} \NC discretionaries \NC \NR
+\NC \type{insert} \NC packaging an insert \NC \NR
+\NC \type{vcenter} \NC \prm {vcenter} \NC \NR
+\NC \type{local_box} \NC \lpr {localleftbox} or \lpr {localrightbox} \NC \NR
+\NC \type{split_off} \NC top of a \prm {vsplit} \NC \NR
+\NC \type{split_keep} \NC remainder of a \prm {vsplit} \NC \NR
+\NC \type{align_set} \NC alignment cell \NC \NR
+\NC \type{fin_row} \NC alignment row \NC \NR
+\LL
+\stoptabulate
+
+As for all the callbacks that deal with nodes, the return value can be one of
+three things:
+
+\startitemize
+\startitem
+ boolean \type {true} signals successful processing
+\stopitem
+\startitem
+ \type {<node>} signals that the \quote {head} node should be replaced by the
+ returned node
+\stopitem
+\startitem
+ boolean \type {false} signals that the \quote {head} node list should be
+ ignored and flushed from memory
+\stopitem
+\stopitemize
+
+This callback does not replace any internal code.
+
+\subsection{\cbk {linebreak_filter}}
+
+\topicindex{callbacks+linebreaks}
+
+This callback replaces \LUATEX's line breaking algorithm.
+
+\startfunctioncall
+function(<node> head, <boolean> is_display)
+ return <node> newhead
+end
+\stopfunctioncall
+
+The returned node is the head of the list that will be added to the main vertical
+list, the boolean argument is true if this paragraph is interrupted by a
+following math display.
+
+If you return something that is not a \type {<node>}, \LUATEX\ will apply the
+internal linebreak algorithm on the list that starts at \type {<head>}.
+Otherwise, the \type {<node>} you return is supposed to be the head of a list of
+nodes that are all allowed in vertical mode, and at least one of those has to
+represent a hbox. Failure to do so will result in a fatal error.
+
+Setting this callback to \type {false} is possible, but dangerous, because it is
+possible you will end up in an unfixable \quote {deadcycles loop}.
+
+\subsection{\type {append_to_vlist_filter}}
+
+\topicindex{callbacks+contributions}
+
+This callback is called whenever \LUATEX\ adds a box to a vertical list:
+
+\startfunctioncall
+function(<node> box, <string> locationcode, <number prevdepth>,
+ <boolean> mirrored)
+ return list, prevdepth
+end
+\stopfunctioncall
+
+It is ok to return nothing in which case you also need to flush the box or deal
+with it yourself. The prevdepth is also optional. Locations are \type {box},
+\type {alignment}, \type {equation}, \type {equation_number} and \type
+{post_linebreak}.
+
+\subsection{\cbk {post_linebreak_filter}}
+
+\topicindex{callbacks+linebreaks}
+
+This callback is called just after \LUATEX\ has converted a list of nodes into a
+stack of \prm {hbox}es.
+
+\startfunctioncall
+function(<node> head, <string> groupcode)
+ return true | false | <node> newhead
+end
+\stopfunctioncall
+
+This callback does not replace any internal code.
+
+\subsection{\cbk {hpack_filter}}
+
+\topicindex{callbacks+packing}
+
+This callback is called when \TEX\ is ready to start boxing some horizontal mode
+material. Math items and line boxes are ignored at the moment.
+
+\startfunctioncall
+function(<node> head, <string> groupcode, <number> size,
+ <string> packtype [, <string> direction] [, <node> attributelist])
+ return true | false | <node> newhead
+end
+\stopfunctioncall
+
+The \type {packtype} is either \type {additional} or \type {exactly}. If \type
+{additional}, then the \type {size} is a \type {\hbox spread ...} argument. If
+\type {exactly}, then the \type {size} is a \type {\hbox to ...}. In both cases,
+the number is in scaled points.
+
+The \type {direction} is either one of the three-letter direction specifier
+strings, or \type {nil}.
+
+This callback does not replace any internal code.
+
+\subsection{\cbk {vpack_filter}}
+
+\topicindex{callbacks+packing}
+
+This callback is called when \TEX\ is ready to start boxing some vertical mode
+material. Math displays are ignored at the moment.
+
+This function is very similar to the \cbk {hpack_filter}. Besides the fact
+that it is called at different moments, there is an extra variable that matches
+\TEX's \prm {maxdepth} setting.
+
+\startfunctioncall
+function(<node> head, <string> groupcode, <number> size, <string> packtype,
+ <number> maxdepth [, <string> direction] [, <node> attributelist]))
+ return true | false | <node> newhead
+end
+\stopfunctioncall
+
+This callback does not replace any internal code.
+
+\subsection{\type {hpack_quality}}
+
+\topicindex{callbacks+packing}
+
+This callback can be used to intercept the overfull messages that can result from
+packing a horizontal list (as happens in the par builder). The function takes a
+few arguments:
+
+\startfunctioncall
+function(<string> incident, <number> detail, <node> head, <number> first,
+ <number> last)
+ return <node> whatever
+end
+\stopfunctioncall
+
+The incident is one of \type {overfull}, \type {underfull}, \type {loose} or
+\type {tight}. The detail is either the amount of overflow in case of \type
+{overfull}, or the badness otherwise. The head is the list that is constructed
+(when protrusion or expansion is enabled, this is an intermediate list).
+Optionally you can return a node, for instance an overfull rule indicator. That
+node will be appended to the list (just like \TEX's own rule would).
+
+\subsection{\type {vpack_quality}}
+
+\topicindex{callbacks+packing}
+
+This callback can be used to intercept the overfull messages that can result from
+packing a vertical list (as happens in the page builder). The function takes a
+few arguments:
+
+\startfunctioncall
+function(<string> incident, <number> detail, <node> head, <number> first,
+ <number> last)
+end
+\stopfunctioncall
+
+The incident is one of \type {overfull}, \type {underfull}, \type {loose} or
+\type {tight}. The detail is either the amount of overflow in case of \type
+{overfull}, or the badness otherwise. The head is the list that is constructed.
+
+\subsection{\cbk {process_rule}}
+
+\topicindex{callbacks+rules}
+
+This is an experimental callback. It can be used with rules of subtype~4
+(user). The callback gets three arguments: the node, the width and the
+height. The callback can use \type {pdf.print} to write code to the \PDF\
+file but beware of not messing up the final result. No checking is done.
+
+\subsection{\type {pre_output_filter}}
+
+\topicindex{callbacks+output}
+
+This callback is called when \TEX\ is ready to start boxing the box 255 for \prm
+{output}.
+
+\startfunctioncall
+function(<node> head, <string> groupcode, <number> size, <string> packtype,
+ <number> maxdepth [, <string> direction])
+ return true | false | <node> newhead
+end
+\stopfunctioncall
+
+This callback does not replace any internal code.
+
+\subsection{\cbk {hyphenate}}
+
+\topicindex{callbacks+hyphenation}
+
+\startfunctioncall
+function(<node> head, <node> tail)
+end
+\stopfunctioncall
+
+No return values. This callback has to insert discretionary nodes in the node
+list it receives.
+
+Setting this callback to \type {false} will prevent the internal discretionary
+insertion pass.
+
+\subsection{\cbk {ligaturing}}
+
+\topicindex{callbacks+ligature building}
+
+\startfunctioncall
+function(<node> head, <node> tail)
+end
+\stopfunctioncall
+
+No return values. This callback has to apply ligaturing to the node list it
+receives.
+
+You don't have to worry about return values because the \type {head} node that is
+passed on to the callback is guaranteed not to be a glyph_node (if need be, a
+temporary node will be prepended), and therefore it cannot be affected by the
+mutations that take place. After the callback, the internal value of the \quote
+{tail of the list} will be recalculated.
+
+The \type {next} of \type {head} is guaranteed to be non-nil.
+
+The \type {next} of \type {tail} is guaranteed to be nil, and therefore the
+second callback argument can often be ignored. It is provided for orthogonality,
+and because it can sometimes be handy when special processing has to take place.
+
+Setting this callback to \type {false} will prevent the internal ligature
+creation pass.
+
+You must not ruin the node list. For instance, the head normally is a local par node,
+and the tail a glue. Messing too much can push \LUATEX\ into panic mode.
+
+\subsection{\cbk {kerning}}
+
+\topicindex{callbacks+kerning}
+
+\startfunctioncall
+function(<node> head, <node> tail)
+end
+\stopfunctioncall
+
+No return values. This callback has to apply kerning between the nodes in the
+node list it receives. See \cbk {ligaturing} for calling conventions.
+
+Setting this callback to \type {false} will prevent the internal kern insertion
+pass.
+
+You must not ruin the node list. For instance, the head normally is a local par node,
+and the tail a glue. Messing too much can push \LUATEX\ into panic mode.
+
+\subsection{\type {insert_local_par}}
+
+Each paragraph starts with a local par node that keeps track of for instance
+the direction. You can hook a callback into the creator:
+
+\startfunctioncall
+function(<node> local_par, <string> location)
+end
+\stopfunctioncall
+
+There is no return value and you should make sure that the node stays valid
+as otherwise \TEX\ can get confused.
+
+\subsection{\cbk {mlist_to_hlist}}
+
+\topicindex{callbacks+math}
+
+This callback replaces \LUATEX's math list to node list conversion algorithm.
+
+\startfunctioncall
+function(<node> head, <string> display_type, <boolean> need_penalties)
+ return <node> newhead
+end
+\stopfunctioncall
+
+The returned node is the head of the list that will be added to the vertical or
+horizontal list, the string argument is either \quote {text} or \quote {display}
+depending on the current math mode, the boolean argument is \type {true} if
+penalties have to be inserted in this list, \type {false} otherwise.
+
+Setting this callback to \type {false} is bad, it will almost certainly result in
+an endless loop.
+
+\stopsection
+
+\startsection[title={Information reporting callbacks}][library=callback]
+
+\subsection{\cbk {pre_dump}}
+
+\topicindex{callbacks+dump}
+
+\startfunctioncall
+function()
+end
+\stopfunctioncall
+
+This function is called just before dumping to a format file starts. It does not
+replace any code and there are neither arguments nor return values.
+
+\subsection{\cbk {start_run}}
+
+\topicindex{callbacks+job run}
+
+\startfunctioncall
+function()
+end
+\stopfunctioncall
+
+This callback replaces the code that prints \LUATEX's banner. Note that for
+successful use, this callback has to be set in the \LUA\ initialization script,
+otherwise it will be seen only after the run has already started.
+
+\subsection{\cbk {stop_run}}
+
+\topicindex{callbacks+job run}
+
+\startfunctioncall
+function()
+end
+\stopfunctioncall
+
+This callback replaces the code that prints \LUATEX's statistics and \quote
+{output written to} messages. The engine can still do housekeeping and therefore
+you should not rely on this hook for postprocessing the \PDF\ or log file.
+
+\subsection{\cbk {show_error_hook}}
+
+\topicindex{callbacks+errors}
+
+\startfunctioncall
+function()
+end
+\stopfunctioncall
+
+This callback is run from inside the \TEX\ error function, and the idea is to
+allow you to do some extra reporting on top of what \TEX\ already does (none of
+the normal actions are removed). You may find some of the values in the \type
+{status} table useful. This callback does not replace any internal code.
+
+\subsection{\cbk {show_error_message}}
+
+\topicindex{callbacks+errors}
+
+\startfunctioncall
+function()
+end
+\stopfunctioncall
+
+This callback replaces the code that prints the error message. The usual
+interaction after the message is not affected.
+
+\subsection{\cbk {show_lua_error_hook}}
+
+\topicindex{callbacks+errors}
+
+\startfunctioncall
+function()
+end
+\stopfunctioncall
+
+This callback replaces the code that prints the extra \LUA\ error message.
+
+\subsection{\cbk {start_file}}
+
+\topicindex{callbacks+files}
+
+\startfunctioncall
+function(category,filename)
+end
+\stopfunctioncall
+
+This callback replaces the code that prints \LUATEX's when a file is opened like
+\type {(filename} for regular files. The category is a number:
+
+\starttabulate[|c|l|]
+\DB value \BC meaning \NC \NR
+\TB
+\NC 1 \NC a normal data file, like a \TEX\ source \NC \NR
+\NC 2 \NC a font map coupling font names to resources \NC \NR
+\NC 3 \NC an image file (\type {png}, \type {pdf}, etc) \NC \NR
+\NC 4 \NC an embedded font subset \NC \NR
+\NC 5 \NC a fully embedded font \NC \NR
+\LL
+\stoptabulate
+
+\subsection{\cbk {stop_file}}
+
+\topicindex{callbacks+files}
+
+\startfunctioncall
+function(category)
+end
+\stopfunctioncall
+
+This callback replaces the code that prints \LUATEX's when a file is closed like
+the \type {)} for regular files.
+
+\subsection{\cbk {wrapup_run}}
+
+\topicindex{callbacks+wrapping up}
+
+This callback is called after the \PDF\ and log files are closed. Use it at your own
+risk.
+
+\stopsection
+
+\startsection[title={Font-related callbacks}][library=callback]
+
+\subsection{\cbk {define_font}}
+
+\topicindex{callbacks+fonts}
+
+\startfunctioncall
+function(<string> name, <number> size)
+ return <number> id
+end
+\stopfunctioncall
+
+The string \type {name} is the filename part of the font specification, as given
+by the user.
+
+The number \type {size} is a bit special:
+
+\startitemize[packed]
+\startitem
+ If it is positive, it specifies an \quote{at size} in scaled points.
+\stopitem
+\startitem
+ If it is negative, its absolute value represents a \quote {scaled} setting
+ relative to the design size of the font.
+\stopitem
+\stopitemize
+
+The font can be defined with \type {font.define} which returns a font identifier
+that can be returned in the callback. So, contrary to \LUATEX, in \LUAMETATEX\
+we only accept a number.
+
+The internal structure of the \type {font} table that is passed to \type
+{font.define} is explained in \in {chapter} [fonts]. That table is saved
+internally, so you can put extra fields in the table for your later \LUA\ code to
+use. In alternative, \type {retval} can be a previously defined fontid. This is
+useful if a previous definition can be reused instead of creating a whole new
+font structure.
+
+Setting this callback to \type {false} is pointless as it will prevent font
+loading completely but will nevertheless generate errors.
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-contents.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-contents.tex
new file mode 100644
index 00000000000..d55b7f15b15
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-contents.tex
@@ -0,0 +1,19 @@
+\environment luametatex-style
+
+\startcomponent luametatex-contents
+
+\starttitle[title=Contents]
+
+\start
+
+ \definecolor[maincolor][black]
+
+ \placelist
+ [chapter,section,subsection]
+ [criterium=text]
+
+\stop
+
+\stoptitle
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-differences.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-differences.tex
new file mode 100644
index 00000000000..4ec846b3817
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-differences.tex
@@ -0,0 +1,213 @@
+% language=uk
+
+\environment luametatex-style
+
+\startcomponent luametatex-differences
+
+\startchapter[reference=differences,title={Differences with \LUATEX}]
+
+As \LUAMETATEX\ is a leaner and meaner \LUATEX, this chapter will discuss
+what is gone. We start with the primitives that were dropped.
+
+\starttabulate[|l|pl|]
+\NC fonts \NC \type {\letterspacefont}
+ \type {\copyfont}
+ \type {\expandglyphsinfont}
+ \type {\ignoreligaturesinfont}
+ \type {\tagcode}
+ \type {\leftghost}
+ \type {\rightghost}
+ \NC \NR
+\NC backend \NC \type {\dviextension}
+ \type {\dvivariable }
+ \type {\dvifeedback}
+ \type {\pdfextension}
+ \type {\pdfvariable }
+ \type {\pdffeedback}
+ \type {\dviextension}
+ \type {\draftmode}
+ \type {\outputmode}
+ \NC \NR
+\NC dimensions \NC \type {\pageleftoffset}
+ \type {\pagerightoffset}
+ \type {\pagetopoffset}
+ \type {\pagebottomoffset}
+ \type {\pageheight}
+ \type {\pagewidth}
+ \NC \NR
+\NC resources \NC \type {\saveboxresource}
+ \type {\useboxresource}
+ \type {\lastsavedboxresourceindex}
+ \type {\saveimageresource}
+ \type {\useimageresource}
+ \type {\lastsavedimageresourceindex}
+ \type {\lastsavedimageresourcepages}
+ \NC \NR
+\NC positioning \NC \type {\savepos}
+ \type {\lastxpos}
+ \type {\lastypos}
+ \NC \NR
+\NC directions \NC \type {\textdir}
+ \type {\linedir}
+ \type {\mathdir}
+ \type {\pardir}
+ \type {\pagedir}
+ \type {\bodydir}
+ \type {\pagedirection}
+ \type {\bodydirection}
+ \NC \NR
+\NC randomizer \NC \type {\randomseed}
+ \type {\setrandomseed}
+ \type {\normaldeviate}
+ \type {\uniformdeviate}
+ \NC \NR
+\NC utilities \NC \type {\synctex}
+ \NC \NR
+\NC extensions \NC \type {\latelua}
+ \type {\lateluafunction}
+ \type {\immediate}
+ \type {\openout}
+ \type {\write}
+ \type {\closeout}
+ \NC \NR
+\NC control \NC \type {\suppressfontnotfounderror}
+ \type {\suppresslongerror}
+ \type {\suppressprimitiveerror}
+ \type {\suppressmathparerror}
+ \type {\suppressifcsnameerror}
+ \type {\suppressoutererror}
+ \type {\mathoption}
+ \NC \NR
+\NC whatever \NC \type {\primitive}
+ \type {\ifprimitive}
+ \NC \NR
+\NC ignored \NC \type {\long}
+ \type {\outer}
+ \type {\mag}
+ \NC \NR
+\stoptabulate
+
+The resources and positioning primitives are actually useful but can be defined
+as macros that (via \LUA) inject nodes in the input that suit the macro package
+and backend. The three||letter direction primitives are gone and the numeric
+variants are now leading. There is no need for page and body related directions
+and they don't work well in \LUATEX\ anyway. We only have two directions left.
+
+The primitive related extensions were not that useful and reliable so they have
+been removed. There are some new variants that will be discussed later. The \type
+{\outer} and \type {\long} prefixes are gone as they don't make much sense
+nowadays and them becoming dummies opened the way to something new, again to be
+discussed elsewhere. I don't think that (\CONTEXT) users will notice it. The
+\type {\suppress..} features are now default.
+
+The \type {\shipout} primitive does no ship out but just erases the content of
+the box, if that hasn't happened already in another way.
+
+The extension primitives relate to the backend (when not immediate) and can be
+implemented as part of a backend design using generic whatsits. There is only one
+type of whatsit now. In fact we're now closer to original \TEX\ with respect to
+the extensions.
+
+The \type {img} library has been removed as it's rather bound to the backend. The
+\type {slunicode} library is also gone. There are some helpers in the string
+library that can be used instead and one can write additional \LUA\ code if
+needed. There is no longer a \type {pdf} backend library.
+
+In the \type {node}, \type {tex} and \type {status} library we no longer have
+helpers and variables that relate to the backend. The \LUAMETATEX\ engine is in
+principle \DVI\ and \PDF\ unaware. There are only generic whatsit nodes that can
+be used for some management related tasks. For instance you can use them to
+implement user nodes.
+
+The \KPSE\ library is no longer built|-|in. Because there is no backend, quite
+some file related callbacks could go away. The following file related callbacks
+remained (till now):
+
+\starttyping
+find_write_file find_data_file find_format_file
+open_data_file read_data_file
+\stoptyping
+
+Also callbacks related to errors stay:
+
+\starttyping
+show_error_hook show_lua_error_hook,
+show_error_message show_warning_message
+\stoptyping
+
+The (job) management hooks are kept:
+
+\starttyping
+process_jobname
+start_run stop_run wrapup_run
+pre_dump
+start_file stop_file
+\stoptyping
+
+Because we use a more generic whatsit model, there is a new callback:
+
+\starttyping
+show_whatsit
+\stoptyping
+
+Being the core of extensibility, the typesetting callbacks of course stayed. This
+is what we ended up with:
+
+% \ctxlua{inspect(table.sortedkeys(callbacks.list))}
+
+\starttyping
+find_log_file, find_data_file, find_format_file, open_data_file, read_data_file,
+process_jobname, start_run, stop_run, define_font, pre_output_filter,
+buildpage_filter, hpack_filter, vpack_filter, hyphenate, ligaturing, kerning,
+pre_linebreak_filter, linebreak_filter, post_linebreak_filter,
+append_to_vlist_filter, mlist_to_hlist, pre_dump, start_file, stop_file,
+handle_error_hook, show_error_hook, show_lua_error_hook, show_error_message,
+show_warning_message, hpack_quality, vpack_quality, insert_local_par,
+contribute_filter, build_page_insert, wrapup_run, new_graf, make_extensible,
+show_whatsit, terminal_input,
+\stoptyping
+
+As in \LUATEX\ font loading happens with the following callback. This time it
+really needs to be set because there is no built|-|in font loader.
+
+\starttyping
+define_font
+\stoptyping
+
+There are all kinds of subtle differences in the implementation, for instance we
+no longer intercept \type {*} and \type {&} as these were already replaced long
+ago in \TEX\ engines by command line options. Talking of options, only a few are
+left.
+
+We took our time for reaching a stable state in \LUATEX. Among the reasons is the
+fact that most was experimented with in \CONTEXT. It took many man|-|years to
+decide what to keep and how to do things. Of course there are places when things
+can be improved and it might happen in \LUAMETATEX. Contrary to what is sometimes
+suggested, the \LUATEX|-|\CONTEXT\ \MKIV\ combination (assuming matched versions)
+has been quite stable. It made no sense otherwise. Most \CONTEXT\ functionality
+didn't change much at the user level. Of course there have been issues, as is
+natural with everything new and beta, but we have a fast update cycle.
+
+The same is true for \LUAMETATEX\ and \CONTEXT\ \LMTX: it can be used for
+production as usual and in practice \CONTEXT\ users tend to use the beta
+releases, which proves this. Of course, if you use low level features that are
+experimental you're on your own. Also, as with \LUATEX\ it might take many years
+before a long term stable is defined. The good news is that, the source code
+being part of the \CONTEXT\ distribution, there is always a properly working,
+more or less long term stable, snapshot.
+
+The error reporting subsystem has been redone a little but is still fundamentally
+the same. We don't really assume interactive usage but if someone uses it, it
+might be noticed that it is not possible to backtrack or inject something. Of
+course it is no big deal to implement all that in \LUA\ if needed. It removes a
+system dependency and makes for a bit cleaner code.
+
+There are new primitives too as well as some extensions to existing primitive
+functionality. These are described in following chapters but there might be
+hidden treasures in the binary. If you locate them, don't automatically assume
+them to stay, some might be part of experiments!
+
+\stopchapter
+
+\stopcomponent
+
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-enhancements.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-enhancements.tex
new file mode 100644
index 00000000000..d70b8f2c0b4
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-enhancements.tex
@@ -0,0 +1,1777 @@
+% language=uk
+
+\environment luametatex-style
+
+\startcomponent luametatex-enhancements
+
+\startchapter[reference=enhancements,title={Basic \TEX\ enhancements}]
+
+\startsection[title={Introduction}]
+
+\startsubsection[title={Primitive behaviour}]
+
+From day one, \LUATEX\ has offered extra features compared to the superset of
+\PDFTEX, which includes \ETEX, and \ALEPH. This has not been limited to the
+possibility to execute \LUA\ code via \prm {directlua}, but \LUATEX\ also adds
+functionality via new \TEX|-|side primitives or extensions to existing ones. The
+same is true for \LUAMETATEX. Some primitives have \type {luatex} in their name
+and there will be no \type {luametatex} variants. This is because we consider
+\LUAMETATEX\ to be \LUATEX 2\high{+}.
+
+Contrary to the \LUATEX\ engine \LUAMETATEX\ enables all its primitives. You can
+clone (a selection of) primitives with a different prefix, like:
+
+\starttyping
+\directlua { tex.enableprimitives('normal',tex.extraprimitives()) }
+\stoptyping
+
+The \type {extraprimitives} function returns the whole list or a subset,
+specified by one or more keywords \type {core}, \type {tex}, \type {etex} or
+\type {luatex}. \footnote {At some point this function might be changed to return
+the whole list always}.
+
+But be aware that the curly braces may not have the proper \prm {catcode}
+assigned to them at this early time (giving a \quote {Missing number} error), so
+it may be needed to put these assignments before the above line:
+
+\starttyping
+\catcode `\{=1
+\catcode `\}=2
+\stoptyping
+
+More fine|-|grained primitives control is possible and you can look up the
+details in \in {section} [luaprimitives]. There are only three kinds of
+primitives: \type {tex}, \type {etex} and \type {luatex} but a future version
+might drop this and no longer make that distinction as it no longer serves
+a purpose.
+
+\stopsubsection
+
+\startsubsection[title={Experiments}]
+
+There are a few extensions to the engine regarding the macro machinery. Some are
+already well tested but others are (still) experimental. Although they are likely
+to stay, their exact behaviour might evolve. Because \LUAMETATEX\ is also used
+for experiments, this is not a problem. We can always decide to also add some of
+what is discussed here to \LUATEX, but it will happen with a delay.
+
+There are all kinds of small improvements that might find their way into stock
+\LUATEX: a few more helpers, some cleanup of code, etc. We'll see. In any case,
+if you play with these before they are declared stable, unexpected side effects
+are what you have to accept.
+
+\stopsubsection
+
+\startsubsection[title={Version information}]
+
+\startsubsubsection[title={\lpr {luatexbanner}, \lpr {luatexversion} and \lpr {luatexrevision}}]
+
+\topicindex{version}
+\topicindex{banner}
+
+There are three primitives to test the version of \LUATEX\ (and \LUAMETATEX):
+
+\unexpanded\def\VersionHack#1% otherwise different luatex and luajittex runs
+ {\ctxlua{%
+ local banner = "\luatexbanner"
+ local banner = string.match(banner,"(.+)\letterpercent(") or banner
+ context(string.gsub(banner ,"jit",""))%
+ }}
+
+\starttabulate[|l|l|pl|]
+\DB primitive \BC value
+ \BC explanation \NC \NR
+\TB
+\NC \lpr {luatexbanner} \NC \VersionHack{\luatexbanner}
+ \NC the banner reported on the command line \NC \NR
+\NC \lpr {luatexversion} \NC \the\luatexversion
+ \NC a combination of major and minor number \NC \NR
+\NC \lpr {luatexrevision} \NC \luatexrevision
+ \NC the revision number, the current value is \NC \NR
+\LL
+\stoptabulate
+
+A version is defined as follows:
+
+\startitemize
+\startitem
+ The major version is the integer result of \lpr {luatexversion} divided by
+ 100. The primitive is an \quote {internal variable}, so you may need to prefix
+ its use with \prm {the} depending on the context.
+\stopitem
+\startitem
+ The minor version is the two|-|digit result of \lpr {luatexversion} modulo 100.
+\stopitem
+\startitem
+ The revision is reported by \lpr {luatexrevision}. This primitive expands to
+ a positive integer.
+\stopitem
+\startitem
+ The full version number consists of the major version, minor version and
+ revision, separated by dots.
+\stopitem
+\stopitemize
+
+\stopsubsubsection
+
+The \LUAMETATEX\ version number starts at 2 in order to prevent a clash with
+\LUATEX, and the version commands are the same. This is a way to indicate that
+these projects are related.
+
+\startsubsubsection[title={\lpr {formatname}}]
+
+\topicindex{format}
+
+The \lpr {formatname} syntax is identical to \prm {jobname}. In \INITEX, the
+expansion is empty. Otherwise, the expansion is the value that \prm {jobname} had
+during the \INITEX\ run that dumped the currently loaded format. You can use this
+token list to provide your own version info.
+
+\stopsubsubsection
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title={\UNICODE\ text support}]
+
+\startsubsection[title={Extended ranges}]
+
+\topicindex{\UNICODE}
+
+Text input and output is now considered to be \UNICODE\ text, so input characters
+can use the full range of \UNICODE\ ($2^{20}+2^{16}-1 = \hbox{0x10FFFF}$). Later
+chapters will talk of characters and glyphs. Although these are not
+interchangeable, they are closely related. During typesetting, a character is
+always converted to a suitable graphic representation of that character in a
+specific font. However, while processing a list of to|-|be|-|typeset nodes, its
+contents may still be seen as a character. Inside the engine there is no clear
+separation between the two concepts. Because the subtype of a glyph node can be
+changed in \LUA\ it is up to the user. Subtypes larger than 255 indicate that
+font processing has happened.
+
+A few primitives are affected by this, all in a similar fashion: each of them has
+to accommodate for a larger range of acceptable numbers. For instance, \prm
+{char} now accepts values between~0 and $1{,}114{,}111$. This should not be a
+problem for well|-|behaved input files, but it could create incompatibilities for
+input that would have generated an error when processed by older \TEX|-|based
+engines. The affected commands with an altered initial (left of the equal sign)
+or secondary (right of the equal sign) value are: \prm {char}, \prm {lccode},
+\prm {uccode}, \lpr {hjcode}, \prm {catcode}, \prm {sfcode}, \lpr {efcode}, \lpr
+{lpcode}, \lpr {rpcode}, \prm {chardef}.
+
+As far as the core engine is concerned, all input and output to text files is
+\UTF-8 encoded. Input files can be pre|-|processed using the \type {reader}
+callback. This will be explained in \in {section} [iocallback]. Normalization of
+the \UNICODE\ input is on purpose not built|-|in and can be handled by a macro
+package during callback processing. We have made some practical choices and the
+user has to live with those.
+
+Output in byte|-|sized chunks can be achieved by using characters just outside of
+the valid \UNICODE\ range, starting at the value $1{,}114{,}112$ (0x110000). When
+the time comes to print a character $c>=1{,}114{,}112$, \LUATEX\ will actually
+print the single byte corresponding to $c$ minus 1{,}114{,}112.
+
+Contrary to other \TEX\ engines, the output to the terminal is as|-|is so there
+is no escaping with \type {^^}. We operate in a \UTF\ universe.
+
+\stopsubsection
+
+\startsubsection[title={\lpr {Uchar}}]
+
+\topicindex{\UNICODE}
+
+The expandable command \lpr {Uchar} reads a number between~0 and $1{,}114{,}111$
+and expands to the associated \UNICODE\ character.
+
+\stopsubsection
+
+\startsubsection[title={Extended tables}]
+
+All traditional \TEX\ and \ETEX\ registers can be 16-bit numbers. The affected
+commands are:
+
+\startfourcolumns
+\startlines
+\prm {count}
+\prm {dimen}
+\prm {skip}
+\prm {muskip}
+\prm {marks}
+\prm {toks}
+\prm {countdef}
+\prm {dimendef}
+\prm {skipdef}
+\prm {muskipdef}
+\prm {toksdef}
+\prm {insert}
+\prm {box}
+\prm {unhbox}
+\prm {unvbox}
+\prm {copy}
+\prm {unhcopy}
+\prm {unvcopy}
+\prm {wd}
+\prm {ht}
+\prm {dp}
+\prm {setbox}
+\prm {vsplit}
+\stoplines
+\stopfourcolumns
+
+Fonts are loaded via \LUA\ and a minimal amount of information is kept at the
+\TEX\ end. Sharing resources is up to the loaders. The engine doesn't really care
+about what a character (or glyph) number represents (a \UNICODE\ or index) as it
+only is interested in dimensions.
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title={Attributes}]
+
+\startsubsection[title={Nodes}]
+
+\topicindex {nodes}
+
+When \TEX\ reads input it will interpret the stream according to the properties
+of the characters. Some signal a macro name and trigger expansion, others open
+and close groups, trigger math mode, etc. What's left over becomes the typeset
+text. Internally we get a linked list of nodes. Characters become \nod {glyph}
+nodes that have for instance a \type {font} and \type {char} property and \typ
+{\kern 10pt} becomes a \nod {kern} node with a \type {width} property. Spaces are
+alien to \TEX\ as they are turned into \nod {glue} nodes. So, a simple paragraph
+is mostly a mix of sequences of \nod {glyph} nodes (words) and \nod {glue} nodes
+(spaces). A node can have a subtype so that it can be recognized as for instance
+a space related glue.
+
+The sequences of characters at some point are extended with \nod {disc} nodes
+that relate to hyphenation. After that font logic can be applied and we get a
+list where some characters can be replaced, for instance multiple characters can
+become one ligature, and font kerns can be injected. This is driven by the
+font properties.
+
+Boxes (like \prm {hbox} and \prm {vbox}) become \nod {hlist} or \nod {vlist}
+nodes with \type {width}, \type {height}, \type {depth} and \type {shift}
+properties and a pointer \type {list} to its actual content. Boxes can be
+constructed explicitly or can be the result of subprocesses. For instance, when
+lines are broken into paragraphs, the lines are a linked list of \nod {hlist}
+nodes, possibly with glue and penalties in between.
+
+Internally nodes have a number. This number is actually an index in the memory
+used to store nodes.
+
+So, to summarize: all that you enter as content eventually becomes a node, often
+as part of a (nested) list structure. They have a relative small memory footprint
+and carry only the minimal amount of information needed. In traditional \TEX\ a
+character node only held the font and slot number, in \LUATEX\ we also store some
+language related information, the expansion factor, etc. Now that we have access
+to these nodes from \LUA\ it makes sense to be able to carry more information
+with a node and this is where attributes kick in.
+
+\stopsubsection
+
+\startsubsection[title={Attribute registers}]
+
+\topicindex {attributes}
+
+Attributes are a completely new concept in \LUATEX. Syntactically, they behave a
+lot like counters: attributes obey \TEX's nesting stack and can be used after
+\prm {the} etc.\ just like the normal \prm {count} registers.
+
+\startsyntax
+\attribute <16-bit number> <optional equals> <32-bit number>!crlf
+\attributedef <csname> <optional equals> <16-bit number>
+\stopsyntax
+
+Conceptually, an attribute is either \quote {set} or \quote {unset}. Unset
+attributes have a special negative value to indicate that they are unset, that
+value is the lowest legal value: \type {-"7FFFFFFF} in hexadecimal, a.k.a.
+$-2147483647$ in decimal. It follows that the value \type {-"7FFFFFFF} cannot be
+used as a legal attribute value, but you {\it can\/} assign \type {-"7FFFFFFF} to
+\quote {unset} an attribute. All attributes start out in this \quote {unset}
+state in \INITEX.
+
+Attributes can be used as extra counter values, but their usefulness comes mostly
+from the fact that the numbers and values of all \quote {set} attributes are
+attached to all nodes created in their scope. These can then be queried from any
+\LUA\ code that deals with node processing. Further information about how to use
+attributes for node list processing from \LUA\ is given in~\in {chapter}[nodes].
+
+Attributes are stored in a sorted (sparse) linked list that are shared when
+possible. This permits efficient testing and updating. You can define many
+thousands of attributes but normally such a large number makes no sense and is
+also not that efficient because each node carries a (possibly shared) link to a
+list of currently set attributes. But they are a convenient extension and one of
+the first extensions we implemented in \LUATEX.
+
+In \LUAMETATEX\ we try to minimize the memory footprint and creation of these
+attribute lists more aggressive sharing them. This feature is still somewhat
+experimental.
+
+\stopsubsection
+
+\startsubsection[title={Box attributes}]
+
+\topicindex {attributes}
+\topicindex {boxes}
+
+Nodes typically receive the list of attributes that is in effect when they are
+created. This moment can be quite asynchronous. For example: in paragraph
+building, the individual line boxes are created after the \prm {par} command has
+been processed, so they will receive the list of attributes that is in effect
+then, not the attributes that were in effect in, say, the first or third line of
+the paragraph.
+
+Similar situations happen in \LUATEX\ regularly. A few of the more obvious
+problematic cases are dealt with: the attributes for nodes that are created
+during hyphenation, kerning and ligaturing borrow their attributes from their
+surrounding glyphs, and it is possible to influence box attributes directly.
+
+When you assemble a box in a register, the attributes of the nodes contained in
+the box are unchanged when such a box is placed, unboxed, or copied. In this
+respect attributes act the same as characters that have been converted to
+references to glyphs in fonts. For instance, when you use attributes to implement
+color support, each node carries information about its eventual color. In that
+case, unless you implement mechanisms that deal with it, applying a color to
+already boxed material will have no effect. Keep in mind that this
+incompatibility is mostly due to the fact that separate specials and literals are
+a more unnatural approach to colors than attributes.
+
+It is possible to fine-tune the list of attributes that are applied to a \type
+{hbox}, \type {vbox} or \type {vtop} by the use of the keyword \type {attr}. The
+\type {attr} keyword(s) should come before a \type {to} or \type {spread}, if
+that is also specified. An example is:
+
+\startbuffer[tex]
+\attribute997=123
+\attribute998=456
+\setbox0=\hbox {Hello}
+\setbox2=\hbox attr 999 = 789 attr 998 = -"7FFFFFFF{Hello}
+\stopbuffer
+
+\startbuffer[lua]
+ for b=0,2,2 do
+ for a=997, 999 do
+ tex.sprint("box ", b, " : attr ",a," : ",tostring(tex.box[b] [a]))
+ tex.sprint("\\quad\\quad")
+ tex.sprint("list ",b, " : attr ",a," : ",tostring(tex.box[b].list[a]))
+ tex.sprint("\\par")
+ end
+ end
+\stopbuffer
+
+\typebuffer[tex]
+
+Box 0 now has attributes 997 and 998 set while box 2 has attributes 997 and 999
+set while the nodes inside that box will all have attributes 997 and 998 set.
+Assigning the maximum negative value causes an attribute to be ignored.
+
+To give you an idea of what this means at the \LUA\ end, take the following
+code:
+
+\typebuffer[lua]
+
+Later we will see that you can access properties of a node. The boxes here are so
+called \nod {hlist} nodes that have a field \type {list} that points to the
+content. Because the attributes are a list themselves you can access them by
+indexing the node (here we do that with \type {[a]}). Running this snippet gives:
+
+\start
+ \getbuffer[tex]
+ \startpacked \tt
+ \ctxluabuffer[lua]
+ \stoppacked
+\stop
+
+Because some values are not set we need to apply the \type {tostring} function
+here so that we get the word \type {nil}.
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title={\LUA\ related primitives}]
+
+\startsubsection[title={\prm {directlua}}]
+
+In order to merge \LUA\ code with \TEX\ input, a few new primitives are needed.
+The primitive \prm {directlua} is used to execute \LUA\ code immediately. The
+syntax is
+
+\startsyntax
+\directlua <general text>
+\stopsyntax
+
+The \syntax {<general text>} is expanded fully, and then fed into the \LUA\
+interpreter. After reading and expansion has been applied to the \syntax
+{<general text>}, the resulting token list is converted to a string as if it was
+displayed using \type {\the\toks}. On the \LUA\ side, each \prm {directlua} block
+is treated as a separate chunk. In such a chunk you can use the \type {local}
+directive to keep your variables from interfering with those used by the macro
+package.
+
+The conversion to and from a token list means that you normally can not use \LUA\
+line comments (starting with \type {--}) within the argument. As there typically
+will be only one \quote {line} the first line comment will run on until the end
+of the input. You will either need to use \TEX|-|style line comments (starting
+with \%), or change the \TEX\ category codes locally. Another possibility is to
+say:
+
+\starttyping
+\begingroup
+\endlinechar=10
+\directlua ...
+\endgroup
+\stoptyping
+
+Then \LUA\ line comments can be used, since \TEX\ does not replace line endings
+with spaces. Of course such an approach depends on the macro package that you
+use.
+
+The \prm {directlua} command is expandable. Since it passes \LUA\ code to the
+\LUA\ interpreter its expansion from the \TEX\ viewpoint is usually empty.
+However, there are some \LUA\ functions that produce material to be read by \TEX,
+the so called print functions. The most simple use of these is \type
+{tex.print(<string> s)}. The characters of the string \type {s} will be placed on
+the \TEX\ input buffer, that is, \quote {before \TEX's eyes} to be read by \TEX\
+immediately. For example:
+
+\startbuffer
+\count10=20
+a\directlua{tex.print(tex.count[10]+5)}b
+\stopbuffer
+
+\typebuffer
+
+expands to
+
+\getbuffer
+
+Here is another example:
+
+\startbuffer
+$\pi = \directlua{tex.print(math.pi)}$
+\stopbuffer
+
+\typebuffer
+
+will result in
+
+\getbuffer
+
+Note that the expansion of \prm {directlua} is a sequence of characters, not of
+tokens, contrary to all \TEX\ commands. So formally speaking its expansion is
+null, but it places material on a pseudo-file to be immediately read by \TEX, as
+\ETEX's \prm {scantokens}. For a description of print functions look at \in
+{section} [sec:luaprint].
+
+Because the \syntax {<general text>} is a chunk, the normal \LUA\ error handling
+is triggered if there is a problem in the included code. The \LUA\ error messages
+should be clear enough, but the contextual information is still pretty bad.
+Often, you will only see the line number of the right brace at the end of the
+code.
+
+While on the subject of errors: some of the things you can do inside \LUA\ code
+can break up \LUAMETATEX\ pretty bad. If you are not careful while working with
+the node list interface, you may even end up with assertion errors from within
+the \TEX\ portion of the executable.
+
+\stopsubsection
+
+\startsubsection[title={\lpr {luaescapestring}}]
+
+\topicindex {escaping}
+
+This primitive converts a \TEX\ token sequence so that it can be safely used as
+the contents of a \LUA\ string: embedded backslashes, double and single quotes,
+and newlines and carriage returns are escaped. This is done by prepending an
+extra token consisting of a backslash with category code~12, and for the line
+endings, converting them to \type {n} and \type {r} respectively. The token
+sequence is fully expanded.
+
+\startsyntax
+\luaescapestring <general text>
+\stopsyntax
+
+Most often, this command is not actually the best way to deal with the
+differences between \TEX\ and \LUA. In very short bits of \LUA\ code it is often
+not needed, and for longer stretches of \LUA\ code it is easier to keep the code
+in a separate file and load it using \LUA's \type {dofile}:
+
+\starttyping
+\directlua { dofile("mysetups.lua") }
+\stoptyping
+
+\stopsubsection
+
+\startsubsection[title={\lpr {luafunction}, \lpr {luafunctioncall} and \lpr {luadef}}]
+
+The \prm {directlua} commands involves tokenization of its argument (after
+picking up an optional name or number specification). The tokenlist is then
+converted into a string and given to \LUA\ to turn into a function that is
+called. The overhead is rather small but when you have millions of calls it can
+have some impact. For this reason there is a variant call available: \lpr
+{luafunction}. This command is used as follows:
+
+\starttyping
+\directlua {
+ local t = lua.get_functions_table()
+ t[1] = function() tex.print("!") end
+ t[2] = function() tex.print("?") end
+}
+
+\luafunction1
+\luafunction2
+\stoptyping
+
+Of course the functions can also be defined in a separate file. There is no limit
+on the number of functions apart from normal \LUA\ limitations. Of course there
+is the limitation of no arguments but that would involve parsing and thereby give
+no gain. The function, when called in fact gets one argument, being the index, so
+in the following example the number \type {8} gets typeset.
+
+\starttyping
+\directlua {
+ local t = lua.get_functions_table()
+ t[8] = function(slot) tex.print(slot) end
+}
+\stoptyping
+
+The \lpr {luafunctioncall} primitive does the same but is unexpandable, for
+instance in an \prm {edef}. In addition \LUATEX\ provides a definer:
+
+\starttyping
+ \luadef\MyFunctionA 1
+ \global\luadef\MyFunctionB 2
+\protected\global\luadef\MyFunctionC 3
+\stoptyping
+
+You should really use these commands with care. Some references get stored in
+tokens and assume that the function is available when that token expands. On the
+other hand, as we have tested this functionality in relative complex situations
+normal usage should not give problems.
+
+\stopsubsection
+
+\startsubsection[title={\lpr {luabytecode} and \lpr {luabytecodecall}}]
+
+Analogue to the function callers discussed in the previous section we have byte
+code callers. Again the call variant is unexpandable.
+
+\starttyping
+\directlua {
+ lua.bytecode[9998] = function(s)
+ tex.sprint(s*token.scan_int())
+ end
+ lua.bytecode[5555] = function(s)
+ tex.sprint(s*token.scan_dimen())
+ end
+}
+\stoptyping
+
+This works with:
+
+\starttyping
+\luabytecode 9998 5 \luabytecode 5555 5sp
+\luabytecodecall9998 5 \luabytecodecall5555 5sp
+\stoptyping
+
+The variable \type {s} in the code is the number of the byte code register that
+can be used for diagnostic purposes. The advantage of bytecode registers over
+function calls is that they are stored in the format (but without upvalues).
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title={Catcode tables}]
+
+\startsubsection[title={Catcodes}]
+
+\topicindex {catcodes}
+
+Catcode tables are a new feature that allows you to switch to a predefined
+catcode regime in a single statement. You can have lots of different tables, but
+if you need a dozen you might wonder what you're doing. This subsystem is
+backward compatible: if you never use the following commands, your document will
+not notice any difference in behaviour compared to traditional \TEX. The contents
+of each catcode table is independent from any other catcode table, and its
+contents is stored and retrieved from the format file.
+
+\stopsubsection
+
+\startsubsection[title={\lpr {catcodetable}}]
+
+\startsyntax
+\catcodetable <15-bit number>
+\stopsyntax
+
+The primitive \lpr {catcodetable} switches to a different catcode table. Such a
+table has to be previously created using one of the two primitives below, or it
+has to be zero. Table zero is initialized by \INITEX.
+
+\stopsubsection
+
+\startsubsection[title={\lpr {initcatcodetable}}]
+
+\startsyntax
+\initcatcodetable <15-bit number>
+\stopsyntax
+
+The primitive \lpr {initcatcodetable} creates a new table with catcodes
+identical to those defined by \INITEX. The new catcode table is allocated
+globally: it will not go away after the current group has ended. If the supplied
+number is identical to the currently active table, an error is raised. The
+initial values are:
+
+\starttabulate[|c|c|l|l|]
+\DB catcode \BC character \BC equivalent \BC category \NC \NR
+\TB
+\NC 0 \NC \tttf \letterbackslash \NC \NC \type {escape} \NC \NR
+\NC 5 \NC \tttf \letterhat\letterhat M \NC return \NC \type {car_ret} \NC \NR
+\NC 9 \NC \tttf \letterhat\letterhat @ \NC null \NC \type {ignore} \NC \NR
+\NC 10 \NC \tttf <space> \NC space \NC \type {spacer} \NC \NR
+\NC 11 \NC {\tttf a} \endash\ {\tttf z} \NC \NC \type {letter} \NC \NR
+\NC 11 \NC {\tttf A} \endash\ {\tttf Z} \NC \NC \type {letter} \NC \NR
+\NC 12 \NC everything else \NC \NC \type {other} \NC \NR
+\NC 14 \NC \tttf \letterpercent \NC \NC \type {comment} \NC \NR
+\NC 15 \NC \tttf \letterhat\letterhat ? \NC delete \NC \type {invalid_char} \NC \NR
+\LL
+\stoptabulate
+
+\stopsubsection
+
+\startsubsection[title={\lpr {savecatcodetable}}]
+
+\startsyntax
+\savecatcodetable <15-bit number>
+\stopsyntax
+
+\lpr {savecatcodetable} copies the current set of catcodes to a new table with
+the requested number. The definitions in this new table are all treated as if
+they were made in the outermost level.
+
+The new table is allocated globally: it will not go away after the current group
+has ended. If the supplied number is the currently active table, an error is
+raised.
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title={Tokens, commands and strings}]
+
+\startsubsection[title={\lpr {scantextokens}}]
+
+\topicindex {tokens+scanning}
+
+The syntax of \lpr {scantextokens} is identical to \prm {scantokens}. This
+primitive is a slightly adapted version of \ETEX's \prm {scantokens}. The
+differences are:
+
+\startitemize
+\startitem
+ The last (and usually only) line does not have a \prm {endlinechar}
+ appended.
+\stopitem
+\startitem
+ \lpr {scantextokens} never raises an EOF error, and it does not execute
+ \prm {everyeof} tokens.
+\stopitem
+\startitem
+ There are no \quote {\unknown\ while end of file \unknown} error tests
+ executed. This allows the expansion to end on a different grouping level or
+ while a conditional is still incomplete.
+\stopitem
+\stopitemize
+
+\stopsubsection
+
+\startsubsection[title={\lpr {toksapp}, \lpr {tokspre}, \lpr {etoksapp}, \lpr {etokspre},
+\lpr {gtoksapp}, \lpr {gtokspre}, \lpr {xtoksapp}, \lpr {xtokspre}}]
+
+Instead of:
+
+\starttyping
+\toks0\expandafter{\the\toks0 foo}
+\stoptyping
+
+you can use:
+
+\starttyping
+\etoksapp0{foo}
+\stoptyping
+
+The \type {pre} variants prepend instead of append, and the \type {e} variants
+expand the passed general text. The \type {g} and \type {x} variants are global.
+
+\stopsubsection
+
+\startsubsection[title={\prm {csstring}, \lpr {begincsname} and \lpr {lastnamedcs}}]
+
+These are somewhat special. The \prm {csstring} primitive is like
+\prm {string} but it omits the leading escape character. This can be
+somewhat more efficient than stripping it afterwards.
+
+The \lpr {begincsname} primitive is like \prm {csname} but doesn't create
+a relaxed equivalent when there is no such name. It is equivalent to
+
+\starttyping
+\ifcsname foo\endcsname
+ \csname foo\endcsname
+\fi
+\stoptyping
+
+The advantage is that it saves a lookup (don't expect much speedup) but more
+important is that it avoids using the \prm {if} test. The \lpr {lastnamedcs}
+is one that should be used with care. The above example could be written as:
+
+\starttyping
+\ifcsname foo\endcsname
+ \lastnamedcs
+\fi
+\stoptyping
+
+This is slightly more efficient than constructing the string twice (deep down in
+\LUATEX\ this also involves some \UTF8 juggling), but probably more relevant is
+that it saves a few tokens and can make code a bit more readable.
+
+\stopsubsection
+
+\startsubsection[title={\lpr {clearmarks}}]
+
+\topicindex {marks}
+
+This primitive complements the \ETEX\ mark primitives and clears a mark class
+completely, resetting all three connected mark texts to empty. It is an
+immediate command.
+
+\startsyntax
+\clearmarks <16-bit number>
+\stopsyntax
+
+\stopsubsection
+
+\startsubsection[title={\lpr {alignmark} and \lpr {aligntab}}]
+
+The primitive \lpr {alignmark} duplicates the functionality of \type {#} inside
+alignment preambles, while \lpr {aligntab} duplicates the functionality of \type
+{&}.
+
+\stopsubsection
+
+\startsubsection[title={\lpr {letcharcode}}]
+
+This primitive can be used to assign a meaning to an active character, as in:
+
+\starttyping
+\def\foo{bar} \letcharcode123=\foo
+\stoptyping
+
+This can be a bit nicer than using the uppercase tricks (using the property of
+\prm {uppercase} that it treats active characters special).
+
+\stopsubsection
+
+\startsubsection[title={\lpr {glet}}]
+
+This primitive is similar to:
+
+\starttyping
+\protected\def\glet{\global\let}
+\stoptyping
+
+but faster (only measurable with millions of calls) and probably more convenient
+(after all we also have \type {\gdef}).
+
+\stopsubsection
+
+\startsubsection[title={\lpr {expanded}, \lpr {immediateassignment} and \lpr {immediateassigned}}]
+
+\topicindex {expansion}
+
+The \lpr {expanded} primitive takes a token list and expands its content which can
+come in handy: it avoids a tricky mix of \prm {expandafter} and \prm {noexpand}.
+You can compare it with what happens inside the body of an \prm {edef}. But this
+kind of expansion still doesn't expand some primitive operations.
+
+\startbuffer
+\newcount\NumberOfCalls
+
+\def\TestMe{\advance\NumberOfCalls1 }
+
+\edef\Tested{\TestMe foo:\the\NumberOfCalls}
+\edef\Tested{\TestMe foo:\the\NumberOfCalls}
+\edef\Tested{\TestMe foo:\the\NumberOfCalls}
+
+\meaning\Tested
+\stopbuffer
+
+\typebuffer
+
+The result is a macro that has the not expanded code in its body:
+
+\getbuffer
+
+Instead we can define \tex {TestMe} in a way that expands the assignment
+immediately. You need of course to be aware of preventing look ahead interference
+by using a space or \tex {relax} (often an expression works better as it doesn't
+leave an \tex {relax}).
+
+\startbuffer
+\def\TestMe{\immediateassignment\advance\NumberOfCalls1 }
+
+\edef\Tested{\TestMe foo:\the\NumberOfCalls}
+\edef\Tested{\TestMe foo:\the\NumberOfCalls}
+\edef\Tested{\TestMe foo:\the\NumberOfCalls}
+
+\meaning\Tested
+\stopbuffer
+
+\typebuffer
+
+This time the counter gets updates and we don't see interference in the
+resulting \tex {Tested} macro:
+
+\getbuffer
+
+Here is a somewhat silly example of expanded comparison:
+
+\startbuffer
+\def\expandeddoifelse#1#2#3#4%
+ {\immediateassignment\edef\tempa{#1}%
+ \immediateassignment\edef\tempb{#2}%
+ \ifx\tempa\tempb
+ \immediateassignment\def\next{#3}%
+ \else
+ \immediateassignment\def\next{#4}%
+ \fi
+ \next}
+
+\edef\Tested
+ {(\expandeddoifelse{abc}{def}{yes}{nop}/%
+ \expandeddoifelse{abc}{abc}{yes}{nop})}
+
+\meaning\Tested
+\stopbuffer
+
+\typebuffer
+
+It gives:
+
+\getbuffer
+
+A variant is:
+
+\starttyping
+\def\expandeddoifelse#1#2#3#4%
+ {\immediateassigned{
+ \edef\tempa{#1}%
+ \edef\tempb{#2}%
+ }%
+ \ifx\tempa\tempb
+ \immediateassignment\def\next{#3}%
+ \else
+ \immediateassignment\def\next{#4}%
+ \fi
+ \next}
+\stoptyping
+
+The possible error messages are the same as using assignments in preambles of
+alignments and after the \prm {accent} command. The supported assignments are the
+so called prefixed commands (except box assignments).
+
+\stopsubsection
+
+\startsubsection[title={\lpr {ignorepars}}]
+
+This primitive is like \prm {ignorespaces} but also skips paragraph ending
+commands (normally \prm {par} and empty lines).
+
+\stopsubsection
+
+\startsubsection[title={\lpr {futureexpand}, \lpr {futureexpandis}, \lpr {futureexpandisap}}]
+
+These commands are used as:
+
+\starttyping
+\futureexpand\sometoken\whenfound\whennotfound
+\stoptyping
+
+When there is no match and a space was gobbled a space will be put back. The
+\type {is} variant doesn't do that while the \type {isap} even skips \type
+{\pars}, These characters stand for \quote {ignorespaces} and \quote
+{ignorespacesandpars}.
+
+\stopsubsection
+
+\startsubsection[title={\lpr {aftergrouped}}]
+
+There is a new experimental feature that can inject multiple tokens to after the group
+ends. An example demonstrate its use:
+
+\startbuffer
+{
+ \aftergroup A \aftergroup B \aftergroup C
+test 1 : }
+
+{
+ \aftergrouped{What comes next 1}
+ \aftergrouped{What comes next 2}
+ \aftergrouped{What comes next 3}
+test 2 : }
+
+
+{
+ \aftergroup A \aftergrouped{What comes next 1}
+ \aftergroup B \aftergrouped{What comes next 2}
+ \aftergroup C \aftergrouped{What comes next 3}
+test 3 : }
+
+{
+ \aftergrouped{What comes next 1} \aftergroup A
+ \aftergrouped{What comes next 2} \aftergroup B
+ \aftergrouped{What comes next 3} \aftergroup C
+test 4 : }
+\stopbuffer
+
+\typebuffer
+
+This gives:
+
+\startpacked\getbuffer\stoppacked
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title=Conditions]
+
+\startsubsection[title={\lpr{ifabsnum} and \lpr {ifabsdim}}]
+
+There are two tests that we took from \PDFTEX:
+
+\startbuffer
+\ifabsnum -10 = 10
+ the same number
+\fi
+\ifabsdim -10pt = 10pt
+ the same dimension
+\fi
+\stopbuffer
+
+\typebuffer
+
+This gives
+
+\blank {\tt \getbuffer} \blank
+
+\stopsubsection
+
+\startsubsection[title={\lpr{ifcmpnum}, \lpr {ifcmpdim}, \lpr {ifnumval}, \lpr
+{ifdimval}, \lpr {ifchknum} and \lpr {ifchkdim}}]
+
+\topicindex {conditions+numbers}
+\topicindex {conditions+dimensions}
+\topicindex {numbers}
+\topicindex {dimensions}
+
+New are the ones that compare two numbers or dimensions:
+
+\startbuffer
+\ifcmpnum 5 8 less \or equal \else more \fi
+\ifcmpnum 5 5 less \or equal \else more \fi
+\ifcmpnum 8 5 less \or equal \else more \fi
+\stopbuffer
+
+\typebuffer \blank {\tt \getbuffer} \blank
+
+and
+
+\startbuffer
+\ifcmpdim 5pt 8pt less \or equal \else more \fi
+\ifcmpdim 5pt 5pt less \or equal \else more \fi
+\ifcmpdim 8pt 5pt less \or equal \else more \fi
+\stopbuffer
+
+\typebuffer \blank {\tt \getbuffer} \blank
+
+There are also some number and dimension tests. All four expose the \type {\else}
+branch when there is an error, but two also report if the number is less, equal
+or more than zero.
+
+\startbuffer
+\ifnumval -123 \or < \or = \or > \or ! \else ? \fi
+\ifnumval 0 \or < \or = \or > \or ! \else ? \fi
+\ifnumval 123 \or < \or = \or > \or ! \else ? \fi
+\ifnumval abc \or < \or = \or > \or ! \else ? \fi
+
+\ifdimval -123pt \or < \or = \or > \or ! \else ? \fi
+\ifdimval 0pt \or < \or = \or > \or ! \else ? \fi
+\ifdimval 123pt \or < \or = \or > \or ! \else ? \fi
+\ifdimval abcpt \or < \or = \or > \or ! \else ? \fi
+\stopbuffer
+
+\typebuffer \blank {\tt \getbuffer} \blank
+
+\startbuffer
+\ifchknum -123 \or okay \else bad \fi
+\ifchknum 0 \or okay \else bad \fi
+\ifchknum 123 \or okay \else bad \fi
+\ifchknum abc \or okay \else bad \fi
+
+\ifchkdim -123pt \or okay \else bad \fi
+\ifchkdim 0pt \or okay \else bad \fi
+\ifchkdim 123pt \or okay \else bad \fi
+\ifchkdim abcpt \or okay \else bad \fi
+\stopbuffer
+
+\typebuffer \blank {\tt \getbuffer} \blank
+
+\stopsubsection
+
+\startsubsection[title={\lpr {iftok} and \lpr {ifcstok}}]
+
+\topicindex {conditions+tokens}
+\topicindex {tokens}
+
+Comparing tokens and macros can be done with \type {\ifx}. Two extra test are
+provided in \LUAMETATEX:
+
+\startbuffer
+\def\ABC{abc} \def\DEF{def} \def\PQR{abc} \newtoks\XYZ \XYZ {abc}
+
+\iftok{abc}{def}\relax (same) \else [different] \fi
+\iftok{abc}{abc}\relax [same] \else (different) \fi
+\iftok\XYZ {abc}\relax [same] \else (different) \fi
+
+\ifcstok\ABC \DEF\relax (same) \else [different] \fi
+\ifcstok\ABC \PQR\relax [same] \else (different) \fi
+\ifcstok{abc}\ABC\relax [same] \else (different) \fi
+\stopbuffer
+
+\typebuffer \startpacked[blank] {\tt\nospacing\getbuffer} \stoppacked
+
+You can check if a macro is is defined as protected with \type {\ifprotected}
+while frozen macros can be tested with \type {\iffrozen}. A provisional \type
+{\ifusercmd} tests will check if a command is defined at the user level (and this
+one might evolve).
+
+\stopsubsection
+
+\startsubsection[title={\lpr {ifcondition}}]
+
+\topicindex {conditions}
+
+This is a somewhat special one. When you write macros conditions need to be
+properly balanced in order to let \TEX's fast branch skipping work well. This new
+primitive is basically a no||op flagged as a condition so that the scanner can
+recognize it as an if|-|test. However, when a real test takes place the work is
+done by what follows, in the next example \tex {something}.
+
+\starttyping
+\unexpanded\def\something#1#2%
+ {\edef\tempa{#1}%
+ \edef\tempb{#2}
+ \ifx\tempa\tempb}
+
+\ifcondition\something{a}{b}%
+ \ifcondition\something{a}{a}%
+ true 1
+ \else
+ false 1
+ \fi
+\else
+ \ifcondition\something{a}{a}%
+ true 2
+ \else
+ false 2
+ \fi
+\fi
+\stoptyping
+
+If you are familiar with \METAPOST, this is a bit like \type {vardef} where the macro
+has a return value. Here the return value is a test.
+
+Experiments with something \type {\ifdef} actually worked ok but were rejected
+because in the end it gave no advantage so this generic one has to do. The \type
+{\ifcondition} test is basically is a no|-|op except when branches are skipped.
+However, when a test is expected, the scanner gobbles it and the next test result
+is used. Here is an other example:
+
+\startbuffer
+\def\mytest#1%
+ {\ifabsdim#1>0pt\else
+ \expandafter \unless
+ \fi
+ \iftrue}
+
+\ifcondition\mytest{10pt}\relax non-zero \else zero \fi
+\ifcondition\mytest {0pt}\relax non-zero \else zero \fi
+\stopbuffer
+
+\typebuffer \blank {\tt \getbuffer} \blank
+
+The last expansion in a macro like \type {\mytest} has to be a condition and here
+we use \type {\unless} to negate the result.
+
+\stopsubsection
+
+\startsubsection[title={\lpr {orelse}}]
+
+Sometimes you have successive tests that, when laid out in the source lead to
+deep trees. The \type {\ifcase} test is an exception. Experiments with \type
+{\ifcasex} worked out fine but eventually were rejected because we have many
+tests so it would add a lot. As \LUAMETATEX\ permitted more experiments,
+eventually an alternative was cooked up, one that has some restrictions but is
+relative lightweight. It goes like this:
+
+\starttyping
+\ifnum\count0<10
+ less
+\orelse\ifnum\count0=10
+ equal
+\else
+ more
+\fi
+\stoptyping
+
+The \type {\orelse} has to be followed by one of the if test commands, except
+\type {\ifcondition}, and there can be an \type {\unless} in front of such a
+command. These restrictions make it possible to stay in the current condition
+(read: at the same level). If you need something more complex, using \type
+{\orelse} is probably unwise anyway. In case you wonder about performance, there
+is a little more checking needed when skipping branches but that can be
+neglected. There is some gain due to staying at the same level but that is only
+measurable when you runs tens of millions of complex tests and in that case it is
+very likely to drown in the real action. It's a convenience mechanism, in the
+sense that it can make your code look a bit easier to follow.
+
+There is a nice side effect of this mechanism. When you define:
+
+\starttyping
+\def\quitcondition{\orelse\iffalse}
+\stoptyping
+
+you can do this:
+
+\starttyping
+\ifnum\count0<10
+ less
+\orelse\ifnum\count0=10
+ equal
+ \quitcondition
+ indeed
+\else
+ more
+\fi
+\stoptyping
+
+Of course it is only useful at the right level, so you might end up with cases like
+
+\starttyping
+\ifnum\count0<10
+ less
+\orelse\ifnum\count0=10
+ equal
+ \ifnum\count2=30
+ \expandafter\quitcondition
+ \fi
+ indeed
+\else
+ more
+\fi
+\stoptyping
+
+\stopsubsection
+
+\startsubsection[title={\lpr {ifprotected}, \lpr {frozen}, \lpr {iffrozen} and \lpr {ifusercmd}}]
+
+These checkers deal with control sequences. You can check if a command is a
+protected one, that is, defined with the \type {\protected} prefix. A command is
+frozen when it has been defined with the \type {\frozen} prefix. Beware: only
+macros can be frozen. A user command is a command that is not part of the
+predefined set of commands. This is an experimental command.
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title={Boxes, rules and leaders}]
+
+\startsubsection[title={\lpr {outputbox}}]
+
+\topicindex {output}
+
+This integer parameter allows you to alter the number of the box that will be
+used to store the page sent to the output routine. Its default value is 255, and
+the acceptable range is from 0 to 65535.
+
+\startsyntax
+\outputbox = 12345
+\stopsyntax
+
+\stopsubsection
+
+\startsubsection[title={\prm {vpack}, \prm {hpack} and \prm {tpack}}]
+
+These three primitives are like \prm {vbox}, \prm {hbox} and \prm {vtop}
+but don't apply the related callbacks.
+
+\stopsubsection
+
+\startsubsection[title={\prm {vsplit}}]
+
+\topicindex {splitting}
+
+The \prm {vsplit} primitive has to be followed by a specification of the required
+height. As alternative for the \type {to} keyword you can use \type {upto} to get
+a split of the given size but result has the natural dimensions then.
+
+\stopsubsection
+
+\startsubsection[title={Images and reused box objects},reference=sec:imagedandforms]
+
+In original \TEX\ image support is dealt with via specials. It's not a native
+feature of the engine. All that \TEX\ cares about is dimensions, so in practice
+that meant: using a box with known dimensions that wraps a special that instructs
+the backend to include an image. The wrapping is needed because a special itself
+is a whatsit and as such has no dimensions.
+
+In \PDFTEX\ a special whatsit for images was introduced and that one {\em has}
+dimensions. As a consequence, in several places where the engine deals with the
+dimensions of nodes, it now has to check the details of whatsits. By inheriting
+code from \PDFTEX, the \LUATEX\ engine also had that property. However, at some
+point this approach was abandoned and a more natural trick was used: images (and
+box resources) became a special kind of rules, and as rules already have
+dimensions, the code could be simplified.
+
+When direction nodes and localpar nodes also became first class nodes, whatsits
+again became just that: nodes representing whatever you want, but without
+dimensions, and therefore they could again be ignored when dimensions mattered.
+And, because images were disguised as rules, as mentioned, their dimensions
+automatically were taken into account. This seperation between front and backend
+cleaned up the code base already quite a bit.
+
+In \LUAMETATEX\ we still have the image specific subtypes for rules, but the
+engine never looks at subtypes of rules. That was up to the backend. This means
+that image support is not present in \LUAMETATEX. When an image specification was
+parsed the special properties, like the filename, or additional attributes, were
+stored in the backend and all that \LUATEX\ does is registering a reference to an
+image's specification in the rule node. But, having no backend means nothing is
+stored, which in turn would make the image inclusion primitives kind of weird.
+
+Therefore you need to realize that contrary to \LUATEX, {\em in \LUAMETATEX\
+support for images and box reuse is not built in}! However, we can assume that
+an implementation uses rules in a similar fashion as \LUATEX\ does. So, you can
+still consider images and box reuse to be core concepts. Here we just mention the
+primitives that \LUATEX\ provides. They are not available in the engine but can
+of course be implemented in \LUA.
+
+\starttabulate[|l|p|]
+\DB command \BC explanation \NC \NR
+\TB
+\NC \lpr {saveboxresource} \NC save the box as an object to be included later \NC \NR
+\NC \lpr {saveimageresource} \NC save the image as an object to be included later \NC \NR
+\NC \lpr {useboxresource} \NC include the saved box object here (by index) \NC \NR
+\NC \lpr {useimageresource} \NC include the saved image object here (by index) \NC \NR
+\NC \lpr {lastsavedboxresourceindex} \NC the index of the last saved box object \NC \NR
+\NC \lpr {lastsavedimageresourceindex} \NC the index of the last saved image object \NC \NR
+\NC \lpr {lastsavedimageresourcepages} \NC the number of pages in the last saved image object \NC \NR
+\LL
+\stoptabulate
+
+An implementation probably should accept the usual optional dimension parameters
+for \type {\use...resource} in the same format as for rules. With images, these
+dimensions are then used instead of the ones given to \lpr {useimageresource} but
+the original dimensions are not overwritten, so that a \lpr {useimageresource}
+without dimensions still provides the image with dimensions defined by \lpr
+{saveimageresource}. These optional parameters are not implemented for \lpr
+{saveboxresource}.
+
+\starttyping
+\useimageresource width 20mm height 10mm depth 5mm \lastsavedimageresourceindex
+\useboxresource width 20mm height 10mm depth 5mm \lastsavedboxresourceindex
+\stoptyping
+
+Examples or optional entries are \type {attr} and \type {resources} that accept a
+token list, and the \type {type} key. When set to non|-|zero the \type {/Type}
+entry is omitted. A value of 1 or 3 still writes a \type {/BBox}, while 2 or 3
+will write a \type {/Matrix}. But, as said: this is entirely up to the backend.
+Generic macro packages (like \type {tikz}) can use these assumed primitives so
+one can best provide them. It is probably, for historic reasons, the only more or
+less standardized image inclusion interface one can expect to work in all macro
+packages.
+
+\stopsubsection
+
+\startsubsection[title={\lpr {hpack}, \lpr {vpack} and \lpr {tpack}}]
+
+These three primitives are the equivalents of \type {\hbox}, \type {\vbox} and
+\type {\vtop} but they don't trigger the packaging related callbacks. Of course
+one never know if content needs a treatment so using them should be done with
+care.
+
+\stopsubsection
+
+\startsubsection[title={\lpr {nohrule} and \lpr {novrule}}]
+
+\topicindex {rules}
+
+Because introducing a new keyword can cause incompatibilities, two new primitives
+were introduced: \lpr {nohrule} and \lpr {novrule}. These can be used to
+reserve space. This is often more efficient than creating an empty box with fake
+dimensions.
+
+\stopsubsection
+
+\startsubsection[title={\lpr {gleaders}},reference=sec:gleaders]
+
+\topicindex {leaders}
+
+This type of leaders is anchored to the origin of the box to be shipped out. So
+they are like normal \prm {leaders} in that they align nicely, except that the
+alignment is based on the {\it largest\/} enclosing box instead of the {\it
+smallest\/}. The \type {g} stresses this global nature.
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title={Languages}]
+
+\startsubsection[title={\lpr {hyphenationmin}}]
+
+\topicindex {languages}
+\topicindex {hyphenation}
+
+This primitive can be used to set the minimal word length, so setting it to a value
+of~$5$ means that only words of 6 characters and more will be hyphenated, of course
+within the constraints of the \prm {lefthyphenmin} and \prm {righthyphenmin}
+values (as stored in the glyph node). This primitive accepts a number and stores
+the value with the language.
+
+\stopsubsection
+
+\startsubsection[title={\prm {boundary}, \prm {noboundary}, \prm {protrusionboundary} and \prm {wordboundary}}]
+
+The \prm {noboundary} command is used to inject a whatsit node but now injects a normal
+node with type \nod {boundary} and subtype~0. In addition you can say:
+
+\starttyping
+x\boundary 123\relax y
+\stoptyping
+
+This has the same effect but the subtype is now~1 and the value~123 is stored.
+The traditional ligature builder still sees this as a cancel boundary directive
+but at the \LUA\ end you can implement different behaviour. The added benefit of
+passing this value is a side effect of the generalization. The subtypes~2 and~3
+are used to control protrusion and word boundaries in hyphenation and have
+related primitives.
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title={Control and debugging}]
+
+\startsubsection[title={Tracing}]
+
+\topicindex {tracing}
+
+If \prm {tracingonline} is larger than~2, the node list display will also print
+the node number of the nodes.
+
+\stopsubsection
+
+\startsubsection[title={\lpr {lastnodetype}, \lpr {lastnodesubtype}, \lpr
+{currentiftype} and \lpr {internalcodesmode}.}]
+
+The \ETEX\ command \type {\lastnodetype} is limited to some nodes. When the
+parameter \type {\internalcodesmode} is set to a non|-|zero value the normal
+(internally used) numbers are reported. The same is true for \type
+{\currentiftype}, as we have more conditionals and also use a different order.
+The \type {\lastnodesubtype} is a bonus.
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title={Files}]
+
+\startsubsection[title={File syntax}]
+
+\topicindex {files+names}
+
+\LUAMETATEX\ will accept a braced argument as a file name:
+
+\starttyping
+\input {plain}
+\openin 0 {plain}
+\stoptyping
+
+This allows for embedded spaces, without the need for double quotes. Macro
+expansion takes place inside the argument.
+
+The \lpr {tracingfonts} primitive that has been inherited from \PDFTEX\ has
+been adapted to support variants in reporting the font. The reason for this
+extension is that a csname not always makes sense. The zero case is the default.
+
+\starttabulate[|l|l|]
+\DB value \BC reported \NC \NR
+\TB
+\NC \type{0} \NC \type{\foo xyz} \NC \NR
+\NC \type{1} \NC \type{\foo (bar)} \NC \NR
+\NC \type{2} \NC \type{<bar> xyz} \NC \NR
+\NC \type{3} \NC \type{<bar @ ..pt> xyz} \NC \NR
+\NC \type{4} \NC \type{<id>} \NC \NR
+\NC \type{5} \NC \type{<id: bar>} \NC \NR
+\NC \type{6} \NC \type{<id: bar @ ..pt> xyz} \NC \NR
+\LL
+\stoptabulate
+
+\stopsubsection
+
+\startsubsection[title={Writing to file}]
+
+\topicindex {files+writing}
+
+You can now open upto 127 files with \prm {openout}. When no file is open writes
+will go to the console and log. The \type {write} related primitives have to be
+implemented as part of a backend! As a consequence a system command is no longer
+possible but one can use \type {os.execute} to do the same.
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title={Math}]
+
+\topicindex {math}
+
+We will cover math extensions in its own chapter because not only the font
+subsystem and spacing model have been enhanced (thereby introducing many new
+primitives) but also because some more control has been added to existing
+functionality. Much of this relates to the different approaches of traditional
+\TEX\ fonts and \OPENTYPE\ math.
+
+\stopsection
+
+\startsection[title={Fonts}]
+
+\topicindex {fonts}
+
+Like math, we will cover fonts extensions in its own chapter. Here we stick to
+mentioning that loading fonts is different in \LUAMETATEX. As in \LUATEX\ we have
+the extra primitives \type {\fontid} and \type {\setfontid}, \type {\noligs} and
+\type {\nokerns}, and \type {\nospaces}. The other new primitives in \LUATEX\
+have been dropped.
+
+\stopsection
+
+\startsection[title=Directions]
+
+\topicindex {\OMEGA}
+\topicindex {\ALEPH}
+\topicindex {directions}
+
+\startsubsection[title={Two directions}]
+
+The directional model in \LUAMETATEX\ is a simplified version the the model used
+in \LUATEX. In fact, not much is happening at all: we only register a change in
+direction.
+
+\stopsubsection
+
+\startsubsection[title={How it works}]
+
+The approach is that we try to make node lists balanced but also try to avoid
+some side effects. What happens is quite intuitive if we forget about spaces
+(turned into glue) but even there what happens makes sense if you look at it in
+detail. However that logic makes in|-|group switching kind of useless when no
+properly nested grouping is used: switching from right to left several times
+nested, results in spacing ending up after each other due to nested mirroring. Of
+course a sane macro package will manage this for the user but here we are
+discussing the low level injection of directional information.
+
+This is what happens:
+
+\starttyping
+\textdirection 1 nur {\textdirection 0 run \textdirection 1 NUR} nur
+\stoptyping
+
+This becomes stepwise:
+
+\startnarrower
+\starttyping
+injected: [push 1]nur {[push 0]run [push 1]NUR} nur
+balanced: [push 1]nur {[push 0]run [pop 0][push 1]NUR[pop 1]} nur[pop 0]
+result : run {RUNrun } run
+\stoptyping
+\stopnarrower
+
+And this:
+
+\starttyping
+\textdirection 1 nur {nur \textdirection 0 run \textdirection 1 NUR} nur
+\stoptyping
+
+becomes:
+
+\startnarrower
+\starttyping
+injected: [+TRT]nur {nur [+TLT]run [+TRT]NUR} nur
+balanced: [+TRT]nur {nur [+TLT]run [-TLT][+TRT]NUR[-TRT]} nur[-TRT]
+result : run {run RUNrun } run
+\stoptyping
+\stopnarrower
+
+Now, in the following examples watch where we put the braces:
+
+\startbuffer
+\textdirection 1 nur {{\textdirection 0 run} {\textdirection 1 NUR}} nur
+\stopbuffer
+
+\typebuffer
+
+This becomes:
+
+\startnarrower
+\getbuffer
+\stopnarrower
+
+Compare this to:
+
+\startbuffer
+\textdirection 1 nur {{\textdirection 0 run }{\textdirection 1 NUR}} nur
+\stopbuffer
+
+\typebuffer
+
+Which renders as:
+
+\startnarrower
+\getbuffer
+\stopnarrower
+
+So how do we deal with the next?
+
+\startbuffer
+\def\ltr{\textdirection 0\relax}
+\def\rtl{\textdirection 1\relax}
+
+run {\rtl nur {\ltr run \rtl NUR \ltr run \rtl NUR} nur}
+run {\ltr run {\rtl nur \ltr RUN \rtl nur \ltr RUN} run}
+\stopbuffer
+
+\typebuffer
+
+It gets typeset as:
+
+\startnarrower
+\startlines
+\getbuffer
+\stoplines
+\stopnarrower
+
+We could define the two helpers to look back, pick up a skip, remove it and
+inject it after the dir node. But that way we loose the subtype information that
+for some applications can be handy to be kept as|-|is. This is why we now have a
+variant of \lpr {textdirection} which injects the balanced node before the skip.
+Instead of the previous definition we can use:
+
+\startbuffer[def]
+\def\ltr{\linedirection 0\relax}
+\def\rtl{\linedirection 1\relax}
+\stopbuffer
+
+\typebuffer[def]
+
+and this time:
+
+\startbuffer[txt]
+run {\rtl nur {\ltr run \rtl NUR \ltr run \rtl NUR} nur}
+run {\ltr run {\rtl nur \ltr RUN \rtl nur \ltr RUN} run}
+\stopbuffer
+
+\typebuffer[txt]
+
+comes out as a properly spaced:
+
+\startnarrower
+\startlines
+\getbuffer[def,txt]
+\stoplines
+\stopnarrower
+
+Anything more complex that this, like combination of skips and penalties, or
+kerns, should be handled in the input or macro package because there is no way we
+can predict the expected behaviour. In fact, the \lpr {linedir} is just a
+convenience extra which could also have been implemented using node list parsing.
+
+\stopsubsection
+
+\startsubsection[title={Controlling glue with \lpr {breakafterdirmode}}]
+
+Glue after a dir node is ignored in the linebreak decision but you can bypass that
+by setting \lpr {breakafterdirmode} to~\type {1}. The following table shows the
+difference. Watch your spaces.
+
+\def\ShowSome#1{%
+ \BC \type{#1}
+ \NC \breakafterdirmode\zerocount\hsize\zeropoint#1
+ \NC
+ \NC \breakafterdirmode\plusone\hsize\zeropoint#1
+ \NC
+ \NC \NR
+}
+
+\starttabulate[|l|Tp(1pt)|w(5em)|Tp(1pt)|w(5em)|]
+ \DB
+ \BC \type{0}
+ \NC
+ \BC \type{1}
+ \NC
+ \NC \NR
+ \TB
+ \ShowSome{pre {\textdirection 0 xxx} post}
+ \ShowSome{pre {\textdirection 0 xxx }post}
+ \ShowSome{pre{ \textdirection 0 xxx} post}
+ \ShowSome{pre{ \textdirection 0 xxx }post}
+ \ShowSome{pre { \textdirection 0 xxx } post}
+ \ShowSome{pre {\textdirection 0\relax\space xxx} post}
+ \LL
+\stoptabulate
+
+\stopsubsection
+
+\startsubsection[title={Controling parshapes with \lpr {shapemode}}]
+
+Another adaptation to the \ALEPH\ directional model is control over shapes driven
+by \prm {hangindent} and \prm {parshape}. This is controlled by a new parameter
+\lpr {shapemode}:
+
+\starttabulate[|c|l|l|]
+\DB value \BC \prm {hangindent} \BC \prm {parshape} \NC \NR
+\TB
+\BC \type{0} \NC normal \NC normal \NC \NR
+\BC \type{1} \NC mirrored \NC normal \NC \NR
+\BC \type{2} \NC normal \NC mirrored \NC \NR
+\BC \type{3} \NC mirrored \NC mirrored \NC \NR
+\LL
+\stoptabulate
+
+The value is reset to zero (like \prm {hangindent} and \prm {parshape})
+after the paragraph is done with. You can use negative values to prevent
+this. In \in {figure} [fig:shapemode] a few examples are given.
+
+\startplacefigure[reference=fig:shapemode,title={The effect of \type {shapemode}.}]
+ \startcombination[2*3]
+ {\ruledvbox \bgroup \setuptolerance[verytolerant]
+ \hsize .45\textwidth \switchtobodyfont[6pt]
+ \pardirection 0 \textdirection 0
+ \hangindent 40pt \hangafter -3
+ \leftskip10pt \input tufte \par
+ \egroup} {TLT: hangindent}
+ {\ruledvbox \bgroup \setuptolerance[verytolerant]
+ \hsize .45\textwidth \switchtobodyfont[6pt]
+ \pardirection 0 \textdirection 0
+ \parshape 4 0pt .8\hsize 10pt .8\hsize 20pt .8\hsize 0pt \hsize
+ \input tufte \par
+ \egroup} {TLT: parshape}
+ {\ruledvbox \bgroup \setuptolerance[verytolerant]
+ \hsize .45\textwidth \switchtobodyfont[6pt]
+ \pardirection 1 \textdirection 1
+ \hangindent 40pt \hangafter -3
+ \leftskip10pt \input tufte \par
+ \egroup} {TRT: hangindent mode 0}
+ {\ruledvbox \bgroup \setuptolerance[verytolerant]
+ \hsize .45\textwidth \switchtobodyfont[6pt]
+ \pardirection 1 \textdirection 1
+ \parshape 4 0pt .8\hsize 10pt .8\hsize 20pt .8\hsize 0pt \hsize
+ \input tufte \par
+ \egroup} {TRT: parshape mode 0}
+ {\ruledvbox \bgroup \setuptolerance[verytolerant]
+ \hsize .45\textwidth \switchtobodyfont[6pt]
+ \shapemode=3
+ \pardirection 1 \textdirection 1
+ \hangindent 40pt \hangafter -3
+ \leftskip10pt \input tufte \par
+ \egroup} {TRT: hangindent mode 1 & 3}
+ {\ruledvbox \bgroup \setuptolerance[verytolerant]
+ \hsize .45\textwidth \switchtobodyfont[6pt]
+ \shapemode=3
+ \pardirection 1 \textdirection 1
+ \parshape 4 0pt .8\hsize 10pt .8\hsize 20pt .8\hsize 0pt \hsize
+ \input tufte \par
+ \egroup} {TRT: parshape mode 2 & 3}
+ \stopcombination
+\stopplacefigure
+
+We have \type {\pardirection}, \type {\textdirection}, \type {\mathdirection} and
+\type {\linedirection} that is like \type {\textdirection} but with some
+additional (inline) glue checking.
+
+\stopsubsection
+
+\startsubsection[title=Orientations]
+
+As mentioned, the difference with \LUATEX\ is that we only have numeric
+directions and that there are only two: left|-|to|-|right (\type {0}) and
+right|-|to|-|left (\type {1}). The direction of a box is set with \type
+{direction}.
+
+In addition to that boxes can now have an \type {orientation} keyword followed by
+optional \type {xoffset} and|/|or \type {yoffset} keywords. The offsets don't
+have consequences for the dimensions. The alternatives \type {xmove} and \type
+{ymove} on the contrary are reflected in the dimensions. Just play with them. The
+offsets and moves only are accepted when there is also an orientation, so no time
+is wasted on testing for these rarely used keywords. There are related primitives
+\type {\box...} that set these properties.
+
+As these are experimental it will not be explained here (yet). They are covered
+in the descriptions of the development of \LUAMETATEX: articles and|/|or
+documents in the \CONTEXT\ distribution. For now it is enough to know that the
+orientation can be up, down, left or right (rotated) and that it has some
+anchoring variants. Combined with the offsets this permits macro writers to
+provide solutions for top|-|down and bottom|-|up writing directions, something
+that is rather macro package specific and used for scripts that need
+manipulations anyway. The \quote {old} vertical directions were never okay and
+therefore not used.
+
+There are a couple of properties in boxes that you can set and query but that
+only really take effect when the backend supports them. When usage on \CONTEXT\
+shows that is't okay, they will become official, so we just mention them: \type
+{\boxdirection}, \type {\boxattr}, \type {\boxorientation}, \type {\boxxoffset},
+\type {\boxyoffset}, \type {\boxxmove}, \type {\boxymove} and \type {\boxtotal}.
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title=Expressions]
+
+The \type {*expr} parsers now accept \type {:} as operator for integer division
+(the \type {/} operators does rounding. This can be used for division compatible
+with \type {\divide}. I'm still wondering if adding a couple of bit operators
+makes sense (for integers).
+
+\stopsection
+
+\startsection[title=Nodes]
+
+The \ETEX\ primitive \type {\lastnodetype} is not honest in reporting the
+internal numbers as it uses its own values. But you can set \type
+{\internalcodesmode} to a non|-|zero value to get the real id's instead. In
+addition there is \type {\lastnodesubtype}.
+
+Another last one is \type {\lastnamedcs} which holds the last match but this one
+should be used with care because one never knows if in the meantime something
+else \quote {last} has been seen.
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-firstpage.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-firstpage.tex
new file mode 100644
index 00000000000..83fb40df12b
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-firstpage.tex
@@ -0,0 +1,36 @@
+\environment luametatex-style
+
+\startcomponent luametatex-firstpage
+
+\startstandardmakeup
+
+ \start
+ \raggedleft
+ \definedfont[Bold*default at 48pt]
+ \setupinterlinespace
+ \blue \documentvariable{manual} \endgraf Reference \endgraf Manual \endgraf
+ \stop
+
+ \vfill
+
+ \definedfont[Bold*default at 12pt]
+
+ \starttabulate[|l|l|]
+ \NC copyright \EQ Lua\TeX\ development team \NC \NR
+ \NC \EQ \CONTEXT\ development team \NC \NR
+ \NC more info \EQ www.luatex.org \NC \NR
+ \NC \EQ contextgarden.net \NC \NR
+ \NC version \EQ \currentdate \doifsomething{\documentvariable{snapshot}}{(snapshot \documentvariable{snapshot})} \NC \NR
+ \stoptabulate
+
+\stopstandardmakeup
+
+\setupbackgrounds
+ [leftpage]
+ [setups=pagenumber:left]
+
+\setupbackgrounds
+ [rightpage]
+ [setups=pagenumber:right]
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-fonts.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-fonts.tex
new file mode 100644
index 00000000000..917ebfeb86f
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-fonts.tex
@@ -0,0 +1,597 @@
+% language=uk
+
+\environment luametatex-style
+
+\startcomponent luametatex-fonts
+
+\startchapter[reference=fonts,title={Fonts}]
+
+\startsection[title={Introduction}]
+
+Only traditional font support is built in, anything more needs to be implemented
+in \LUA. This conforms to the \LUATEX\ philosophy. When you pass a font to the
+frontend only the dimensions matter, as these are used in typesetting, and
+optionally ligatures and kerns when you rely on the built|-|in font handler. For
+math some extra data is needed, like information about extensibles and next in
+size glyphs. You can of course put more information in your \LUA\ tables because
+when such a table is passed to \TEX\ only that what is needed is filtered from
+it.
+
+Because there is no built|-|in backend, virtual font information is not used. If
+you want to be compatible you'd better make sure that your tables are okay, and
+in that case you can best consult the \LUATEX\ manual. For instance, parameters
+like \type {extend} are backend related and the standard \LUATEX\ backend sets
+the standard here.
+
+\stopsection
+
+\startsection[title={Defining fonts}]
+
+All \TEX\ fonts are represented to \LUA\ code as tables, and internally as
+\CCODE\ structures. All keys in the table below are saved in the internal font
+structure if they are present in the table passed to \type {font.define}. When
+the callback is set, which is needed for \type {\font} to work, its function
+gets the name and size passed, and it has to return a valid font identifier (a
+positive number).
+
+For the engine to work well, the following information has to be present at
+the font level:
+
+\starttabulate[|l|l|pl|]
+\DB key \BC value type \BC description \NC \NR
+\TB
+\NC \type {name} \NC string \NC metric (file) name \NC \NR
+\NC \type {characters} \NC table \NC the defined glyphs of this font \NC \NR
+\NC \type {designsize} \NC number \NC expected size (default: 655360 == 10pt) \NC \NR
+\NC \type {fonts} \NC table \NC locally used fonts \NC \NR
+\NC \type {hyphenchar} \NC number \NC default: \TEX's \prm {hyphenchar} \NC \NR
+\NC \type {parameters} \NC hash \NC default: 7 parameters, all zero \NC \NR
+\NC \type {size} \NC number \NC the required scaling (by default the same as designsize) \NC \NR
+\NC \type {skewchar} \NC number \NC default: \TEX's \prm {skewchar} \NC \NR
+\NC \type {stretch} \NC number \NC the \quote {stretch} \NC \NR
+\NC \type {shrink} \NC number \NC the \quote {shrink} \NC \NR
+\NC \type {step} \NC number \NC the \quote {step} \NC \NR
+\NC \type {nomath} \NC boolean \NC this key allows a minor speedup for text fonts; if it
+ is present and true, then \LUATEX\ will not check the
+ character entries for math|-|specific keys \NC \NR
+\NC \type {oldmath} \NC boolean \NC this key flags a font as representing an old school \TEX\
+ math font and disables the \OPENTYPE\ code path \NC \NR
+\LL
+\stoptabulate
+
+The \type {parameters} is a hash with mixed key types. There are seven possible
+string keys, as well as a number of integer indices (these start from 8 up). The
+seven strings are actually used instead of the bottom seven indices, because that
+gives a nicer user interface.
+
+The names and their internal remapping are:
+
+\starttabulate[|l|c|]
+\DB name \BC remapping \NC \NR
+\TB
+\NC \type {slant} \NC 1 \NC \NR
+\NC \type {space} \NC 2 \NC \NR
+\NC \type {space_stretch} \NC 3 \NC \NR
+\NC \type {space_shrink} \NC 4 \NC \NR
+\NC \type {x_height} \NC 5 \NC \NR
+\NC \type {quad} \NC 6 \NC \NR
+\NC \type {extra_space} \NC 7 \NC \NR
+\LL
+\stoptabulate
+
+The \type {characters} table is a \LUA\ hash table where the keys are integers.
+When a character in the input is turned into a glyph node, it gets a character
+code that normally refers to an entry in that table. For proper paragraph
+building and math rendering the following fields can be present in an entry in
+the \type {characters} table. You can of course add all kind of extra fields. The
+engine only uses those that it needs for typesetting a paragraph or formula. The
+subtables that define ligatures and kerns are also hashes with integer keys, and
+these indices should point to entries in the main characters table.
+
+Providing ligatures and kerns this way permits \TEX\ to construct ligatures and
+add inter|-|character kerning. However, normally you will use an \OPENTYPE\ font
+in combination with \LUA\ code that does this. In \CONTEXT\ we have base mode
+that uses the engine, and node mode that uses \LUA. A monospaced font normally
+has no ligatures and kerns and is normally not processed at all.
+
+\starttabulate[|l|l|pl|]
+\DB key \BC type \BC description \NC\NR
+\TB
+\NC \type {width} \NC number \NC width in sp (default 0) \NC\NR
+\NC \type {height} \NC number \NC height in sp (default 0) \NC\NR
+\NC \type {depth} \NC number \NC depth in sp (default 0) \NC\NR
+\NC \type {italic} \NC number \NC italic correction in sp (default 0) \NC\NR
+\NC \type {top_accent} \NC number \NC top accent alignment place in sp (default zero) \NC\NR
+\NC \type {bot_accent} \NC number \NC bottom accent alignment place, in sp (default zero) \NC\NR
+\NC \type {left_protruding} \NC number \NC left protruding factor (\lpr {lpcode}) \NC\NR
+\NC \type {right_protruding} \NC number \NC right protruding factor (\lpr {rpcode}) \NC\NR
+\NC \type {expansion_factor} \NC number \NC expansion factor (\lpr {efcode}) \NC\NR
+\NC \type {next} \NC number \NC \quote {next larger} character index \NC\NR
+\NC \type {extensible} \NC table \NC constituent parts of an extensible recipe \NC\NR
+\NC \type {vert_variants} \NC table \NC constituent parts of a vertical variant set \NC \NR
+\NC \type {horiz_variants} \NC table \NC constituent parts of a horizontal variant set \NC \NR
+\NC \type {kerns} \NC table \NC kerning information \NC\NR
+\NC \type {ligatures} \NC table \NC ligaturing information \NC\NR
+\NC \type {mathkern} \NC table \NC math cut-in specifications \NC\NR
+\LL
+\stoptabulate
+
+For example, here is the character \quote {f} (decimal 102) in the font \type
+{cmr10 at 10pt}. The numbers that represent dimensions are in scaled points.
+
+\starttyping
+[102] = {
+ ["width"] = 200250,
+ ["height"] = 455111,
+ ["depth"] = 0,
+ ["italic"] = 50973,
+ ["kerns"] = {
+ [63] = 50973,
+ [93] = 50973,
+ [39] = 50973,
+ [33] = 50973,
+ [41] = 50973
+ },
+ ["ligatures"] = {
+ [102] = { ["char"] = 11, ["type"] = 0 },
+ [108] = { ["char"] = 13, ["type"] = 0 },
+ [105] = { ["char"] = 12, ["type"] = 0 }
+ }
+}
+\stoptyping
+
+
+Two very special string indexes can be used also: \type {left_boundary} is a
+virtual character whose ligatures and kerns are used to handle word boundary
+processing. \type {right_boundary} is similar but not actually used for anything
+(yet).
+
+The values of \type {top_accent}, \type {bot_accent} and \type {mathkern} are
+used only for math accent and superscript placement, see \at {page} [math] in
+this manual for details. The values of \type {left_protruding} and \type
+{right_protruding} are used only when \lpr {protrudechars} is non-zero. Whether
+or not \type {expansion_factor} is used depends on the font's global expansion
+settings, as well as on the value of \lpr {adjustspacing}.
+
+A math character can have a \type {next} field that points to a next larger
+shape. However, the presence of \type {extensible} will overrule \type {next}, if
+that is also present. The \type {extensible} field in turn can be overruled by
+\type {vert_variants}, the \OPENTYPE\ version. The \type {extensible} table is
+very simple:
+
+\starttabulate[|l|l|p|]
+\DB key \BC type \BC description \NC\NR
+\TB
+\NC \type{top} \NC number \NC top character index \NC\NR
+\NC \type{mid} \NC number \NC middle character index \NC\NR
+\NC \type{bot} \NC number \NC bottom character index \NC\NR
+\NC \type{rep} \NC number \NC repeatable character index \NC\NR
+\LL
+\stoptabulate
+
+The \type {horiz_variants} and \type {vert_variants} are arrays of components.
+Each of those components is itself a hash of up to five keys:
+
+\starttabulate[|l|l|p|]
+\DB key \BC type \BC explanation \NC \NR
+\TB
+\NC \type{glyph} \NC number \NC The character index. Note that this is an encoding number, not a name. \NC \NR
+\NC \type{extender} \NC number \NC One (1) if this part is repeatable, zero (0) otherwise. \NC \NR
+\NC \type{start} \NC number \NC The maximum overlap at the starting side (in scaled points). \NC \NR
+\NC \type{end} \NC number \NC The maximum overlap at the ending side (in scaled points). \NC \NR
+\NC \type{advance} \NC number \NC The total advance width of this item. It can be zero or missing,
+ then the natural size of the glyph for character \type {component}
+ is used. \NC \NR
+\LL
+\stoptabulate
+
+The \type {kerns} table is a hash indexed by character index (and \quote
+{character index} is defined as either a non|-|negative integer or the string
+value \type {right_boundary}), with the values of the kerning to be applied, in
+scaled points.
+
+The \type {ligatures} table is a hash indexed by character index (and \quote
+{character index} is defined as either a non|-|negative integer or the string
+value \type {right_boundary}), with the values being yet another small hash, with
+two fields:
+
+\starttabulate[|l|l|p|]
+\DB key \BC type \BC description \NC \NR
+\TB
+\NC \type{type} \NC number \NC the type of this ligature command, default 0 \NC \NR
+\NC \type{char} \NC number \NC the character index of the resultant ligature \NC \NR
+\LL
+\stoptabulate
+
+The \type {char} field in a ligature is required. The \type {type} field inside a
+ligature is the numerical or string value of one of the eight possible ligature
+types supported by \TEX. When \TEX\ inserts a new ligature, it puts the new glyph
+in the middle of the left and right glyphs. The original left and right glyphs
+can optionally be retained, and when at least one of them is kept, it is also
+possible to move the new \quote {insertion point} forward one or two places. The
+glyph that ends up to the right of the insertion point will become the next
+\quote {left}.
+
+\starttabulate[|l|c|l|l|]
+\DB textual (Knuth) \BC number \BC string \BC result \NC\NR
+\TB
+\NC \type{l + r =: n} \NC 0 \NC \type{=:} \NC \type{|n} \NC\NR
+\NC \type{l + r =:| n} \NC 1 \NC \type{=:|} \NC \type{|nr} \NC\NR
+\NC \type{l + r |=: n} \NC 2 \NC \type{|=:} \NC \type{|ln} \NC\NR
+\NC \type{l + r |=:| n} \NC 3 \NC \type{|=:|} \NC \type{|lnr} \NC\NR
+\NC \type{l + r =:|> n} \NC 5 \NC \type{=:|>} \NC \type{n|r} \NC\NR
+\NC \type{l + r |=:> n} \NC 6 \NC \type{|=:>} \NC \type{l|n} \NC\NR
+\NC \type{l + r |=:|> n} \NC 7 \NC \type{|=:|>} \NC \type{l|nr} \NC\NR
+\NC \type{l + r |=:|>> n} \NC 11 \NC \type{|=:|>>} \NC \type{ln|r} \NC\NR
+\LL
+\stoptabulate
+
+The default value is~0, and can be left out. That signifies a \quote {normal}
+ligature where the ligature replaces both original glyphs. In this table the~\type {|}
+indicates the final insertion point.
+
+\stopsection
+
+\startsection[reference=virtualfonts,title={Virtual fonts}]
+
+% \topicindex {fonts+virtual}
+
+Virtual fonts have been introduced to overcome limitations of good old \TEX. They
+were mostly used for providing a direct mapping from for instance accented
+characters onto a glyph. The backend was responsible for turning a reference to a
+character slot into a real glyph, possibly constructed from other glyphs. In our
+case there is no backend so there is also no need to pass this information
+through \TEX. But it can of course be part of the font information and because it is
+a kind of standard, we describe it here.
+
+A character is virtual when it has a \type {commands} array as part of the data.
+A virtual character can itself point to virtual characters but be careful with
+nesting as you can create loops and overflow the stack (which often indicates an
+error anyway).
+
+At the font level there can be a an (indexed) \type {fonts} table. The values are
+one- or two|-|key hashes themselves, each entry indicating one of the base fonts
+in a virtual font. In case your font is referring to itself in for instance a
+virtual font, you can use the \type {slot} command with a zero font reference,
+which indicates that the font itself is used. So, a table looks like this:
+
+\starttyping
+fonts = {
+ { name = "ptmr8a", size = 655360 },
+ { name = "psyr", size = 600000 },
+ { id = 38 }
+}
+\stoptyping
+
+The first referenced font (at index~1) in this virtual font is \type {ptrmr8a}
+loaded at 10pt, and the second is \type {psyr} loaded at a little over 9pt. The
+third one is a previously defined font that is known to \LUATEX\ as font id~38.
+The array index numbers are used by the character command definitions that are
+part of each character.
+
+The \type {commands} array is a hash where each item is another small array,
+with the first entry representing a command and the extra items being the
+parameters to that command. The allowed commands and their arguments are:
+
+\starttabulate[|l|l|l|p|]
+\DB command \BC arguments \BC type \BC description \NC \NR
+\TB
+\NC \type{font} \NC 1 \NC number \NC select a new font from the local \type {fonts} table \NC \NR
+\NC \type{char} \NC 1 \NC number \NC typeset this character number from the current font,
+ and move right by the character's width \NC \NR
+\NC \type{node} \NC 1 \NC node \NC output this node (list), and move right
+ by the width of this list\NC \NR
+\NC \type{slot} \NC 2 \NC 2 numbers \NC a shortcut for the combination of a font and char command\NC \NR
+\NC \type{push} \NC 0 \NC \NC save current position\NC \NR
+\NC \type{nop} \NC 0 \NC \NC do nothing \NC \NR
+\NC \type{pop} \NC 0 \NC \NC pop position \NC \NR
+\NC \type{rule} \NC 2 \NC 2 numbers \NC output a rule $ht*wd$, and move right. \NC \NR
+\NC \type{down} \NC 1 \NC number \NC move down on the page \NC \NR
+\NC \type{right} \NC 1 \NC number \NC move right on the page \NC \NR
+\NC \type{special} \NC 1 \NC string \NC output a \prm {special} command \NC \NR
+\NC \type{pdf} \NC 2 \NC 2 strings \NC output a \PDF\ literal, the first string is one of \type {origin},
+ \type {page}, \type {text}, \type {font}, \type {direct} or \type {raw}; if you
+ have one string only \type {origin} is assumed \NC \NR
+\NC \type{lua} \NC 1 \NC string,
+ function \NC execute a \LUA\ script when the glyph is embedded; in case of a
+ function it gets the font id and character code passed \NC \NR
+\NC \type{image} \NC 1 \NC image \NC output an image (the argument can be either an \type {<image>} variable or an \type {image_spec} table) \NC \NR
+\NC \type{comment} \NC any \NC any \NC the arguments of this command are ignored \NC \NR
+\LL
+\stoptabulate
+
+When a font id is set to~0 then it will be replaced by the currently assigned
+font id. This prevents the need for hackery with future id's.
+
+The \type {pdf} option also accepts a \type {mode} keyword in which case the
+third argument sets the mode. That option will change the mode in an efficient
+way (passing an empty string would result in an extra empty lines in the \PDF\
+file. This option only makes sense for virtual fonts. The \type {font} mode only
+makes sense in virtual fonts. Modes are somewhat fuzzy and partially inherited
+from \PDFTEX.
+
+\starttabulate[|l|p|]
+\DB mode \BC description \NC \NR
+\TB
+\NC \type {origin} \NC enter page mode and set the position \NC \NR
+\NC \type {page} \NC enter page mode \NC \NR
+\NC \type {text} \NC enter text mode \NC \NR
+\NC \type {font} \NC enter font mode (kind of text mode, only in virtual fonts) \NC \NR
+\NC \type {always} \NC finish the current string and force a transform if needed \NC \NR
+\NC \type {raw} \NC finish the current string \NC \NR
+\LL
+\stoptabulate
+
+You always need to check what \PDF\ code is generated because there can be all
+kind of interferences with optimization in the backend and fonts are complicated
+anyway. Here is a rather elaborate glyph commands example using such keys:
+
+\starttyping
+...
+commands = {
+ { "push" }, -- remember where we are
+ { "right", 5000 }, -- move right about 0.08pt
+ { "font", 3 }, -- select the fonts[3] entry
+ { "char", 97 }, -- place character 97 (ASCII 'a')
+ -- { "slot", 2, 97 }, -- an alternative for the previous two
+ { "pop" }, -- go all the way back
+ { "down", -200000 }, -- move upwards by about 3pt
+ { "special", "pdf: 1 0 0 rg" } -- switch to red color
+ -- { "pdf", "origin", "1 0 0 rg" } -- switch to red color (alternative)
+ { "rule", 500000, 20000 } -- draw a bar
+ { "special", "pdf: 0 g" } -- back to black
+ -- { "pdf", "origin", "0 g" } -- back to black (alternative)
+}
+...
+\stoptyping
+
+The default value for \type {font} is always~1 at the start of the
+\type {commands} array. Therefore, if the virtual font is essentially only a
+re|-|encoding, then you do usually not have created an explicit \quote {font}
+command in the array.
+
+Rules inside of \type {commands} arrays are built up using only two dimensions:
+they do not have depth. For correct vertical placement, an extra \type {down}
+command may be needed.
+
+Regardless of the amount of movement you create within the \type {commands}, the
+output pointer will always move by exactly the width that was given in the \type
+{width} key of the character hash. Any movements that take place inside the \type
+{commands} array are ignored on the upper level.
+
+The special can have a \type {pdf:}, \type {pdf:origin:}, \type {pdf:page:},
+\type {pdf:direct:} or \type {pdf:raw:} prefix. When you have to concatenate
+strings using the \type {pdf} command might be more efficient.
+
+The fields mentioned above can be found in external fonts. It is good to keep in
+mind that we can extend this model, given that the backend knows what to do with
+it.
+
+\stopsection
+
+\startsection[title={Additional \TEX\ commands}]
+
+\startsubsection[title={Font syntax}]
+
+\topicindex {fonts}
+
+\LUATEX\ will accept a braced argument as a font name:
+
+\starttyping
+\font\myfont = {cmr10}
+\stoptyping
+
+This allows for embedded spaces, without the need for double quotes. Macro
+expansion takes place inside the argument.
+
+\stopsubsection
+
+\startsubsection[title={\lpr {fontid} and \lpr {setfontid}}]
+
+\startsyntax
+\fontid\font
+\stopsyntax
+
+This primitive expands into a number. It is not a register so there is no need to
+prefix with \prm {number} (and using \prm {the} gives an error). The currently
+used font id is \fontid\font. Here are some more:
+
+\starttabulate[|l|c|c|]
+\DB style \BC command \BC font id \NC \NR
+\TB
+\NC normal \NC \type {\tf} \NC \tf \fontid\font \NC \NR
+\NC bold \NC \type {\bf} \NC \bf \fontid\font \NC \NR
+\NC italic \NC \type {\it} \NC \it \fontid\font \NC \NR
+\NC bold italic \NC \type {\bi} \NC \bi \fontid\font \NC \NR
+\LL
+\stoptabulate
+
+These numbers depend on the macro package used because each one has its own way
+of dealing with fonts. They can also differ per run, as they can depend on the
+order of loading fonts. For instance, when in \CONTEXT\ virtual math \UNICODE\
+fonts are used, we can easily get over a hundred ids in use. Not all ids have to
+be bound to a real font, after all it's just a number.
+
+The primitive \lpr {setfontid} can be used to enable a font with the given id,
+which of course needs to be a valid one.
+
+\stopsubsection
+
+\startsubsection[title={\lpr {noligs} and \lpr {nokerns}}]
+
+\topicindex {ligatures+suppress}
+\topicindex {kerns+suppress}
+
+These primitives prohibit ligature and kerning insertion at the time when the
+initial node list is built by \LUATEX's main control loop. You can enable these
+primitives when you want to do node list processing of \quote {characters}, where
+\TEX's normal processing would get in the way.
+
+\startsyntax
+\noligs <integer>!crlf
+\nokerns <integer>
+\stopsyntax
+
+These primitives can also be implemented by overloading the ligature building and
+kerning functions, i.e.\ by assigning dummy functions to their associated
+callbacks. Keep in mind that when you define a font (using \LUA) you can also
+omit the kern and ligature tables, which has the same effect as the above.
+
+\stopsubsection
+
+\startsubsection[title={\type{\nospaces}}]
+
+\topicindex {spaces+suppress}
+
+This new primitive can be used to overrule the usual \prm {spaceskip} related
+heuristics when a space character is seen in a text flow. The value~\type{1}
+triggers no injection while \type{2} results in injection of a zero skip. In \in
+{figure} [fig:nospaces] we see the results for four characters separated by a
+space.
+
+\startplacefigure[reference=fig:nospaces,title={The \lpr {nospaces} options.}]
+\startcombination[3*2]
+ {\ruledhbox to 5cm{\vtop{\hsize 10mm\nospaces=0\relax x x x x \par}\hss}} {\type {0 / hsize 10mm}}
+ {\ruledhbox to 5cm{\vtop{\hsize 10mm\nospaces=1\relax x x x x \par}\hss}} {\type {1 / hsize 10mm}}
+ {\ruledhbox to 5cm{\vtop{\hsize 10mm\nospaces=2\relax x x x x \par}\hss}} {\type {2 / hsize 10mm}}
+ {\ruledhbox to 5cm{\vtop{\hsize 1mm\nospaces=0\relax x x x x \par}\hss}} {\type {0 / hsize 1mm}}
+ {\ruledhbox to 5cm{\vtop{\hsize 1mm\nospaces=1\relax x x x x \par}\hss}} {\type {1 / hsize 1mm}}
+ {\ruledhbox to 5cm{\vtop{\hsize 1mm\nospaces=2\relax x x x x \par}\hss}} {\type {2 / hsize 1mm}}
+\stopcombination
+\stopplacefigure
+
+\stopsubsection
+
+\startsubsection[title={\type{\protrusionboundary}}]
+
+\topicindex {protrusion}
+\topicindex {boundaries}
+
+The protrusion detection mechanism is enhanced a bit to enable a bit more complex
+situations. When protrusion characters are identified some nodes are skipped:
+
+\startitemize[packed,columns,two]
+\startitem zero glue \stopitem
+\startitem penalties \stopitem
+\startitem empty discretionaries \stopitem
+\startitem normal zero kerns \stopitem
+\startitem rules with zero dimensions \stopitem
+\startitem math nodes with a surround of zero \stopitem
+\startitem dir nodes \stopitem
+\startitem empty horizontal lists \stopitem
+\startitem local par nodes \stopitem
+\startitem inserts, marks and adjusts \stopitem
+\startitem boundaries \stopitem
+\startitem whatsits \stopitem
+\stopitemize
+
+Because this can not be enough, you can also use a protrusion boundary node to
+make the next node being ignored. When the value is~1 or~3, the next node will be
+ignored in the test when locating a left boundary condition. When the value is~2
+or~3, the previous node will be ignored when locating a right boundary condition
+(the search goes from right to left). This permits protrusion combined with for
+instance content moved into the margin:
+
+\starttyping
+\protrusionboundary1\llap{!\quad}«Who needs protrusion?»
+\stoptyping
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title={The \LUA\ font library}][library=font]
+
+\startsubsection[title={Introduction}]
+
+The \LUA\ font library is reduced to a few commands. Contrary to \LUATEX\ there
+is no loading of \TFM\ or \VF\ files. The explanation of the following commands
+is in the \LUATEX\ manual.
+
+\starttabulate[|l|pl|]
+\DB function \BC description \NC\NR
+\TB
+\NC \type {current} \NC returns the id of the currently active font \NC \NR
+\NC \type {max} \NC returns the last assigned font identifier \NC \NR
+\NC \type {setfont} \NC enables a font setfont (sets the current font id) \NC \NR
+\NC \type {addcharacters} \NC adds characters to a font \NC \NR
+\NC \type {define} \NC defined a font \NC \NR
+\NC \type {id} \NC returns the id that relates to a command name \NC \NR
+\LL
+\stoptabulate
+
+For practical reasons the management of font identifiers is still done by \TEX\
+but it can become an experiment to delegate that to \LUA\ as well.
+
+\stopsubsection
+
+\startsubsection[title={Defining a font with \type {define}, \type {addcharacters} and \type
+{setfont}}]
+
+\topicindex {fonts+define}
+\topicindex {fonts+extend}
+
+Normally you will use a callback to define a font but there's also a \LUA\
+function that does the job.
+
+\startfunctioncall
+id = font.define(<table> f)
+\stopfunctioncall
+
+Within reasonable bounds you can extend a font after it has been defined. Because
+some properties are best left unchanged this is limited to adding characters.
+
+\startfunctioncall
+font.addcharacters(<number n>, <table> f)
+\stopfunctioncall
+
+The table passed can have the fields \type {characters} which is a (sub)table
+like the one used in define, and for virtual fonts a \type {fonts} table can be
+added. The characters defined in the \type {characters} table are added (when not
+yet present) or replace an existing entry. Keep in mind that replacing can have
+side effects because a character already can have been used. Instead of posing
+restrictions we expect the user to be careful. The \type {setfont} helper is
+a more drastic replacer and only works when a font has not been used yet.
+
+\stopsubsection
+
+\startsubsection[title={Font ids: \type {id}, \type {max} and \type {current}}]
+
+\topicindex {fonts+id}
+\topicindex {fonts+current}
+
+\startfunctioncall
+<number> i = font.id(<string> csname)
+\stopfunctioncall
+
+This returns the font id associated with \type {csname}, or $-1$ if \type
+{csname} is not defined.
+
+\startfunctioncall
+<number> i = font.max()
+\stopfunctioncall
+
+This is the largest used index so far. The currently active font id can be
+queried or set with:
+
+\startfunctioncall
+<number> i = font.current()
+font.current(<number> i)
+\stopfunctioncall
+
+\stopsubsection
+
+% \startsubsection[title={Glyph data: \lpr {glyphdata}]
+%
+% This primitive can be used to set an additional glyph property. Of course it's very
+% macro package dependant what is done with that. Consider it an experiment (we had
+% some room left in the glyphs data structure). It's basically an single attribute.
+%
+% \stopsubsection
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
+
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-introduction.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-introduction.tex
new file mode 100644
index 00000000000..774f3d8d9a1
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-introduction.tex
@@ -0,0 +1,142 @@
+% language=uk
+
+\environment luametatex-style
+
+\startcomponent luametatex-introduction
+
+\startchapter[title=Introduction]
+
+Around 2005 we started the \LUATEX\ projects and it took about a decade to reach
+a state where we could consider the experiments to have reached a stable state.
+Pretty soon \LUATEX\ could be used in production, even if some of the interfaces
+evolved, but \CONTEXT\ was kept in sync so that was not really a problem. In 2018
+the functionality was more or less frozen. Of course we might add some features
+in due time but nothing fundamental will change as we consider version 1.10 to be
+reasonable feature complete. Among the reasons is that this engine is now used
+outside \CONTEXT\ too which means that we cannot simply change much without
+affecting other macro packages.
+
+However, in reaching that state some decisions were delayed because they didn't
+go well with a current stable version. This is why at the 2018 \CONTEXT\ meeting
+those present agreed that we could move on with a follow up tagged \METATEX, a
+name we already had in mind for a while, but as \LUA\ is an important component,
+it got expanded to \LUAMETATEX. This follow up is a lightweight companion to
+\LUATEX\ that will be maintained alongside. More about the reasons for this
+follow up as well as the philosophy behind it can be found in the document(s)
+describing the development. During \LUATEX\ development I kept track of what
+happened in a series of documents, parts of which were published as articles in
+user group journals, but all are in the \CONTEXT\ distribution. I did the same
+with the development of \LUAMETATEX.
+
+The \LUAMETATEX\ engine is, as said, a lightweight version of \LUATEX, that for
+now targets \CONTEXT. We will use it for possibly drastic experiments but without
+affecting \LUATEX. As we can easily adapt \CONTEXT\ to support both, no other
+macro package will be harmed when (for instance) interfaces change as part of an
+experiment. Of course, when we consider something to be useful, it can be ported
+back to \LUATEX, but only when there are good reasons for doing so and when no
+compatibility issues are involved. When considering this follow up one
+consideration was that a lean and mean version with an extension mechanism is a
+bit closer to original \TEX. Of course, because we also have new primitives, this
+is not entirely true. The move to \LUA\ already meant that some aspects,
+especially system dependent ones, no longer made sense and therefore had
+consequences for the interface at the system level.
+
+This manual currently has quite a bit of overlap with the \LUATEX\ manual but
+some chapters are removed, others added and the rest has been (and will be
+further) adapted. It also discusses the (main) differences. Some of the new
+primitives or functions that show up in \LUAMETATEX\ might show up in \LUATEX\ at
+some point, others might not, so don't take this manual as reference for \LUATEX
+! For now it is an experimental engine in which we can change things at will but
+with \CONTEXT\ in tandem so that this macro package will keep working.
+
+For \CONTEXT\ users the \LUAMETATEX\ engine will become the default. The
+\CONTEXT\ variant for this engine is tagged \LMTX. The pair can be used in
+production, just as with \LUATEX\ and \MKIV. In fact, most users will probably
+not really notice the difference. In some cases there will be a drop in
+performance, due to more work being delegated to \LUA, but on the average
+performance will be better, also due to some changes below the hood of the
+engine.
+
+As this follow up is closely related to \CONTEXT\ development, and because we
+expect stock \LUATEX\ to be used outside the \CONTEXT\ proper, there will be no
+special mailing list nor coverage (or pollution) on the \LUATEX\ related mailing
+lists. We have the \CONTEXT\ mailing lists for that. In due time the source code
+will be part of the regular \CONTEXT\ distribution.
+
+% \testpage[8]
+
+This manual sometimes refers to \LUATEX, especially when we talk of features
+common to both engine, as well as to \LUAMETATEX, when it is more specific to the
+follow up. A substantial amount of time went into the transition and more will go
+in, so if you want to complain about \LUAMETATEX, don't bother me. Of course, if
+you really need professional support with these engines (or \TEX\ in general),
+you can always consider contacting the developers.
+
+% And yes, I'm really fed up with receiving mails or seeing comments where there's
+% this 'always need to be present' negative remark (nagging) about the program,
+% documentation, development, support, etc. present, probably to put the writer on
+% a higher stand, or maybe to compensate some other personal shortcoming ... who
+% knows. This 'i need to make my stupid point' behaviour seems to come with the
+% internet and it also seems to increase, but that doesn't mean that I want to deal
+% with those unpleasant people for the sake of the larger "tex good". Therefore, I'm
+% quite happy in the nearly always positive and motivating ConTeXt bubble. It's also
+% why I (start) avoid(ing) certain mailing lists and don't really follow forums.
+
+\blank[big]
+
+Hans Hagen
+
+\blank[2*big]
+
+\starttabulate[|||]
+\NC Version \EQ \currentdate \NC \NR
+\NC \LUAMETATEX \EQ \cldcontext{LUATEXENGINE} %
+ \cldcontext{LUATEXVERSION} / %
+ \cldcontext{LUATEXFUNCTIONALITY}
+ \NC \NR
+\NC \CONTEXT \EQ MkIV \contextversion \NC \NR
+\NC \LUATEX\ Team \EQ Hans Hagen, Hartmut Henkel, Taco Hoekwater, Luigi Scarso \NC \NR
+\stoptabulate
+
+\vfilll
+
+{\bf remark:} \LUAMETATEX\ development is mostly done by Hans Hagen and Alan
+Braslau, who love playing with the three languages involved. And as usual Mojca
+Miklavec make sure all compiles well on the buildbot infrastructure. Testing is
+done by \CONTEXT\ developers and users. Many thanks for their patience!
+
+{\bf remark:} When there are non|-|intrusive features that also make sense in
+\LUATEX, these will be applied in the experimental branch first, so that there is
+no interference with the stable release.
+
+{\bf remark:} Most \CONTEXT\ users seem always willing to keep up with the latest
+versions which means that \LMTX\ is tested well. We can therefore safely claim
+that end of 2019 the code has become quite stable. There are no complaints about
+performance (on my laptop this manual compiles at 22.5 pps with \LMTX\ versus
+20.7 pps for the \LUATEX\ manual with \MKIV). Probably no one notices it, but
+memory consumption stepwise got reduced too. And \unknown\ the binary is still
+below 3~MegaBytes on all platforms.
+
+\stopchapter
+
+\stopcomponent
+
+% I'm not that strict with incrementing numbers, but let's occasionally bump
+% the number. Once we're stable it might happen more systematically. For sure
+% I don't want to end up with these redicoulous 0.99999999 kind of numbers.
+%
+% We started with 2.00.0 and kept that number till November 2019, after Alan
+% Braslau and I did the initial beta release at April 1, 2019. After more than
+% a year working on the code base after the \CONTEXT\ 2019 meeting a state was
+% reached where nothing fundamental got added for a while. When \LUATEX\ needs
+% a patch, I check the \LUAMETATEX\ code base as the same patch might be needed
+% there. On the other hand, we don't need a strict compatibility, so some
+% patched in \LUATEX\ are not applied here.
+%
+% In November 2019 I started wondering if we should bump the number, just for
+% the sake of showing that there's still some progress. So I decided to bump to
+% 2.01.0 then. Just as a reminder for myself: it was the day when I watched
+% Jacob Collier perform Lua (feat. MARO) live on YouTube (of course that is not
+% about the language at all, but still a nice coincidence). Just for the fun of
+% it the number bumped a few more times, just to catch up, so end 2019 we're at
+% 2.03.5.
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-languages.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-languages.tex
new file mode 100644
index 00000000000..b6607a9bb8c
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-languages.tex
@@ -0,0 +1,1095 @@
+% language=uk
+
+\environment luametatex-style
+
+\startcomponent luametatex-languages
+
+\startchapter[reference=languages,title={Languages, characters, fonts and glyphs}]
+
+\startsection[title={Introduction}]
+
+\topicindex {languages}
+
+\LUATEX's internal handling of the characters and glyphs that eventually become
+typeset is quite different from the way \TEX82 handles those same objects. The
+easiest way to explain the difference is to focus on unrestricted horizontal mode
+(i.e.\ paragraphs) and hyphenation first. Later on, it will be easy to deal
+with the differences that occur in horizontal and math modes.
+
+In \TEX82, the characters you type are converted into \type {char} node records
+when they are encountered by the main control loop. \TEX\ attaches and processes
+the font information while creating those records, so that the resulting \quote
+{horizontal list} contains the final forms of ligatures and implicit kerning.
+This packaging is needed because we may want to get the effective width of for
+instance a horizontal box.
+
+When it becomes necessary to hyphenate words in a paragraph, \TEX\ converts (one
+word at time) the \type {char} node records into a string by replacing ligatures
+with their components and ignoring the kerning. Then it runs the hyphenation
+algorithm on this string, and converts the hyphenated result back into a \quote
+{horizontal list} that is consecutively spliced back into the paragraph stream.
+Keep in mind that the paragraph may contain unboxed horizontal material, which
+then already contains ligatures and kerns and the words therein are part of the
+hyphenation process.
+
+Those \type {char} node records are somewhat misnamed, as they are glyph
+positions in specific fonts, and therefore not really \quote {characters} in the
+linguistic sense. There is no language information inside the \type {char} node
+records at all. Instead, language information is passed along using \type
+{language whatsit} nodes inside the horizontal list.
+
+In \LUATEX, the situation is quite different. The characters you type are always
+converted into \nod {glyph} node records with a special subtype to identify them
+as being intended as linguistic characters. \LUATEX\ stores the needed language
+information in those records, but does not do any font|-|related processing at
+the time of node creation. It only stores the index of the current font and a
+reference to a character in that font.
+
+When it becomes necessary to typeset a paragraph, \LUATEX\ first inserts all
+hyphenation points right into the whole node list. Next, it processes all the
+font information in the whole list (creating ligatures and adjusting kerning),
+and finally it adjusts all the subtype identifiers so that the records are \quote
+{glyph nodes} from now on.
+
+\stopsection
+
+\startsection[title={Characters, glyphs and discretionaries},reference=charsandglyphs]
+
+\topicindex {characters}
+\topicindex {glyphs}
+\topicindex {hyphenation}
+
+\TEX82 (including \PDFTEX) differentiates between \type {char} nodes and \type
+{lig} nodes. The former are simple items that contained nothing but a \quote
+{character} and a \quote {font} field, and they lived in the same memory as
+tokens did. The latter also contained a list of components, and a subtype
+indicating whether this ligature was the result of a word boundary, and it was
+stored in the same place as other nodes like boxes and kerns and glues.
+
+In \LUATEX, these two types are merged into one, somewhat larger structure called
+a \nod {glyph} node. Besides having the old character, font, and component
+fields there are a few more, like \quote {attr} that we will see in \in {section}
+[glyphnodes], these nodes also contain a subtype, that codes four main types and
+two additional ghost types. For ligatures, multiple bits can be set at the same
+time (in case of a single|-|glyph word).
+
+\startitemize
+ \startitem
+ \type {character}, for characters to be hyphenated: the lowest bit
+ (bit 0) is set to 1.
+ \stopitem
+ \startitem
+ \nod {glyph}, for specific font glyphs: the lowest bit (bit 0) is
+ not set.
+ \stopitem
+ \startitem
+ \type {ligature}, for constructed ligatures bit 1 is set.
+ \stopitem
+\stopitemize
+
+The \nod {glyph} nodes also contain language data, split into four items that
+were current when the node was created: the \prm {setlanguage} (15~bits), \prm
+{lefthyphenmin} (8~bits), \prm {righthyphenmin} (8~bits), and \prm {uchyph}
+(1~bit).
+
+Incidentally, \LUATEX\ allows 16383 separate languages, and words can be 256
+characters long. The language is stored with each character. You can set
+\prm {firstvalidlanguage} to for instance~1 and make thereby language~0
+an ignored hyphenation language.
+
+The new primitive \lpr {hyphenationmin} can be used to signal the minimal length
+of a word. This value is stored with the (current) language.
+
+Because the \prm {uchyph} value is saved in the actual nodes, its handling is
+subtly different from \TEX82: changes to \prm {uchyph} become effective
+immediately, not at the end of the current partial paragraph.
+
+Typeset boxes now always have their language information embedded in the nodes
+themselves, so there is no longer a possible dependency on the surrounding
+language settings. In \TEX82, a mid|-|paragraph statement like \type {\unhbox0}
+would process the box using the current paragraph language unless there was a
+\prm {setlanguage} issued inside the box. In \LUATEX, all language variables
+are already frozen.
+
+In traditional \TEX\ the process of hyphenation is driven by \type {lccode}s. In
+\LUATEX\ we made this dependency less strong. There are several strategies
+possible. When you do nothing, the currently used \type {lccode}s are used, when
+loading patterns, setting exceptions or hyphenating a list.
+
+When you set \prm {savinghyphcodes} to a value greater than zero the current set
+of \type {lccode}s will be saved with the language. In that case changing a \type
+{lccode} afterwards has no effect. However, you can adapt the set with:
+
+\starttyping
+\hjcode`a=`a
+\stoptyping
+
+This change is global which makes sense if you keep in mind that the moment that
+hyphenation happens is (normally) when the paragraph or a horizontal box is
+constructed. When \prm {savinghyphcodes} was zero when the language got
+initialized you start out with nothing, otherwise you already have a set.
+
+When a \lpr {hjcode} is greater than 0 but less than 32 is indicates the
+to be used length. In the following example we map a character (\type {x}) onto
+another one in the patterns and tell the engine that \type {œ} counts as two
+characters. Because traditionally zero itself is reserved for inhibiting
+hyphenation, a value of 32 counts as zero.
+
+Here are some examples (we assume that French patterns are used):
+
+\starttabulate[||||]
+\NC \NC \type{foobar} \NC \type{foo-bar} \NC \NR
+\NC \type{\hjcode`x=`o} \NC \type{fxxbar} \NC \type{fxx-bar} \NC \NR
+\NC \type{\lefthyphenmin3} \NC \type{œdipus} \NC \type{œdi-pus} \NC \NR
+\NC \type{\lefthyphenmin4} \NC \type{œdipus} \NC \type{œdipus} \NC \NR
+\NC \type{\hjcode`œ=2} \NC \type{œdipus} \NC \type{œdi-pus} \NC \NR
+\NC \type{\hjcode`i=32 \hjcode`d=32} \NC \type{œdipus} \NC \type{œdipus} \NC \NR
+\NC
+\stoptabulate
+
+Carrying all this information with each glyph would give too much overhead and
+also make the process of setting up these codes more complex. A solution with
+\type {hjcode} sets was considered but rejected because in practice the current
+approach is sufficient and it would not be compatible anyway.
+
+Beware: the values are always saved in the format, independent of the setting
+of \prm {savinghyphcodes} at the moment the format is dumped.
+
+A boundary node normally would mark the end of a word which interferes with for
+instance discretionary injection. For this you can use the \prm {wordboundary}
+as a trigger. Here are a few examples of usage:
+
+\startbuffer
+ discrete---discrete
+\stopbuffer
+\typebuffer \startnarrower \dontcomplain \hsize 1pt \getbuffer \par \stopnarrower
+\startbuffer
+ discrete\discretionary{}{}{---}discrete
+\stopbuffer
+\typebuffer \startnarrower \dontcomplain \hsize 1pt \getbuffer \par \stopnarrower
+\startbuffer
+ discrete\wordboundary\discretionary{}{}{---}discrete
+\stopbuffer
+\typebuffer \startnarrower \dontcomplain \hsize 1pt \getbuffer \par \stopnarrower
+\startbuffer
+ discrete\wordboundary\discretionary{}{}{---}\wordboundary discrete
+\stopbuffer
+\typebuffer \startnarrower \dontcomplain \hsize 1pt \getbuffer \par \stopnarrower
+\startbuffer
+ discrete\wordboundary\discretionary{---}{}{}\wordboundary discrete
+\stopbuffer
+\typebuffer \startnarrower \dontcomplain \hsize 1pt \getbuffer \par \stopnarrower
+
+We only accept an explicit hyphen when there is a preceding glyph and we skip a
+sequence of explicit hyphens since that normally indicates a \type {--} or \type
+{---} ligature in which case we can in a worse case usage get bad node lists
+later on due to messed up ligature building as these dashes are ligatures in base
+fonts. This is a side effect of separating the hyphenation, ligaturing and
+kerning steps.
+
+The start and end of a sequence of characters is signalled by a \nod {glue}, \nod
+{penalty}, \nod {kern} or \nod {boundary} node. But by default also a \nod
+{hlist}, \nod {vlist}, \nod {rule}, \nod {dir}, \nod {whatsit}, \nod {ins}, and
+\nod {adjust} node indicate a start or end. You can omit the last set from the
+test by setting \lpr {hyphenationbounds} to a non|-|zero value:
+
+\starttabulate[|c|l|]
+\DB value \BC behaviour \NC \NR
+\TB
+\NC \type{0} \NC not strict \NC \NR
+\NC \type{1} \NC strict start \NC \NR
+\NC \type{2} \NC strict end \NC \NR
+\NC \type{3} \NC strict start and strict end \NC \NR
+\LL
+\stoptabulate
+
+The word start is determined as follows:
+
+\starttabulate[|l|l|]
+\DB node \BC behaviour \NC \NR
+\TB
+\BC boundary \NC yes when wordboundary \NC \NR
+\BC hlist \NC when hyphenationbounds 1 or 3 \NC \NR
+\BC vlist \NC when hyphenationbounds 1 or 3 \NC \NR
+\BC rule \NC when hyphenationbounds 1 or 3 \NC \NR
+\BC dir \NC when hyphenationbounds 1 or 3 \NC \NR
+\BC whatsit \NC when hyphenationbounds 1 or 3 \NC \NR
+\BC glue \NC yes \NC \NR
+\BC math \NC skipped \NC \NR
+\BC glyph \NC exhyphenchar (one only) : yes (so no -- ---) \NC \NR
+\BC otherwise \NC yes \NC \NR
+\LL
+\stoptabulate
+
+The word end is determined as follows:
+
+\starttabulate[|l|l|]
+\DB node \BC behaviour \NC \NR
+\TB
+\BC boundary \NC yes \NC \NR
+\BC glyph \NC yes when different language \NC \NR
+\BC glue \NC yes \NC \NR
+\BC penalty \NC yes \NC \NR
+\BC kern \NC yes when not italic (for some historic reason) \NC \NR
+\BC hlist \NC when hyphenationbounds 2 or 3 \NC \NR
+\BC vlist \NC when hyphenationbounds 2 or 3 \NC \NR
+\BC rule \NC when hyphenationbounds 2 or 3 \NC \NR
+\BC dir \NC when hyphenationbounds 2 or 3 \NC \NR
+\BC whatsit \NC when hyphenationbounds 2 or 3 \NC \NR
+\BC ins \NC when hyphenationbounds 2 or 3 \NC \NR
+\BC adjust \NC when hyphenationbounds 2 or 3 \NC \NR
+\LL
+\stoptabulate
+
+\in {Figures} [hb:1] upto \in [hb:5] show some examples. In all cases we set the
+min values to 1 and make sure that the words hyphenate at each character.
+
+\hyphenation{o-n-e t-w-o}
+
+\def\SomeTest#1#2%
+ {\lefthyphenmin \plusone
+ \righthyphenmin \plusone
+ \parindent \zeropoint
+ \everypar \emptytoks
+ \dontcomplain
+ \hbox to 2cm {%
+ \vtop {%
+ \hsize 1pt
+ \hyphenationbounds#1
+ #2
+ \par}}}
+
+\startplacefigure[reference=hb:1,title={\type{one}}]
+ \startcombination[4*1]
+ {\SomeTest{0}{one}} {\type{0}}
+ {\SomeTest{1}{one}} {\type{1}}
+ {\SomeTest{2}{one}} {\type{2}}
+ {\SomeTest{3}{one}} {\type{3}}
+ \stopcombination
+\stopplacefigure
+
+\startplacefigure[reference=hb:2,title={\type{one\null two}}]
+ \startcombination[4*1]
+ {\SomeTest{0}{one\null two}} {\type{0}}
+ {\SomeTest{1}{one\null two}} {\type{1}}
+ {\SomeTest{2}{one\null two}} {\type{2}}
+ {\SomeTest{3}{one\null two}} {\type{3}}
+ \stopcombination
+\stopplacefigure
+
+\startplacefigure[reference=hb:3,title={\type{\null one\null two}}]
+ \startcombination[4*1]
+ {\SomeTest{0}{\null one\null two}} {\type{0}}
+ {\SomeTest{1}{\null one\null two}} {\type{1}}
+ {\SomeTest{2}{\null one\null two}} {\type{2}}
+ {\SomeTest{3}{\null one\null two}} {\type{3}}
+ \stopcombination
+\stopplacefigure
+
+\startplacefigure[reference=hb:4,title={\type{one\null two\null}}]
+ \startcombination[4*1]
+ {\SomeTest{0}{one\null two\null}} {\type{0}}
+ {\SomeTest{1}{one\null two\null}} {\type{1}}
+ {\SomeTest{2}{one\null two\null}} {\type{2}}
+ {\SomeTest{3}{one\null two\null}} {\type{3}}
+ \stopcombination
+\stopplacefigure
+
+\startplacefigure[reference=hb:5,title={\type{\null one\null two\null}}]
+ \startcombination[4*1]
+ {\SomeTest{0}{\null one\null two\null}} {\type{0}}
+ {\SomeTest{1}{\null one\null two\null}} {\type{1}}
+ {\SomeTest{2}{\null one\null two\null}} {\type{2}}
+ {\SomeTest{3}{\null one\null two\null}} {\type{3}}
+ \stopcombination
+\stopplacefigure
+
+% (Future versions of \LUATEX\ might provide more granularity.)
+
+In traditional \TEX\ ligature building and hyphenation are interwoven with the
+line break mechanism. In \LUATEX\ these phases are isolated. As a consequence we
+deal differently with (a sequence of) explicit hyphens. We already have added
+some control over aspects of the hyphenation and yet another one concerns
+automatic hyphens (e.g.\ \type {-} characters in the input).
+
+When \lpr {automatichyphenmode} has a value of 0, a hyphen will be turned into
+an automatic discretionary. The snippets before and after it will not be
+hyphenated. A side effect is that a leading hyphen can lead to a split but one
+will seldom run into that situation. Setting a pre and post character makes this
+more prominent. A value of 1 will prevent this side effect and a value of 2 will
+not turn the hyphen into a discretionary. Experiments with other options, like
+permitting hyphenation of the words on both sides were discarded.
+
+\startbuffer[a]
+before-after \par
+before--after \par
+before---after \par
+\stopbuffer
+
+\startbuffer[b]
+-before \par
+after- \par
+--before \par
+after-- \par
+---before \par
+after--- \par
+\stopbuffer
+
+\startbuffer[c]
+before-after \par
+before--after \par
+before---after \par
+\stopbuffer
+
+\startbuffer[demo]
+\startcombination[nx=4,ny=3,location=top]
+ {\framed[align=normal,strut=no,top=\vskip.5ex,bottom=\vskip.5ex]{\automatichyphenmode\zerocount \hsize6em \getbuffer[a]}} {A~0~6em}
+ {\framed[align=normal,strut=no,top=\vskip.5ex,bottom=\vskip.5ex]{\automatichyphenmode\zerocount \hsize2pt \getbuffer[a]}} {A~0~2pt}
+ {\framed[align=normal,strut=no,top=\vskip.5ex,bottom=\vskip.5ex]{\automatichyphenmode\plusone \hsize2pt \getbuffer[a]}} {A~1~2pt}
+ {\framed[align=normal,strut=no,top=\vskip.5ex,bottom=\vskip.5ex]{\automatichyphenmode\plustwo \hsize2pt \getbuffer[a]}} {A~2~2pt}
+ {\framed[align=normal,strut=no,top=\vskip.5ex,bottom=\vskip.5ex]{\automatichyphenmode\zerocount \hsize6em \getbuffer[b]}} {B~0~6em}
+ {\framed[align=normal,strut=no,top=\vskip.5ex,bottom=\vskip.5ex]{\automatichyphenmode\zerocount \hsize2pt \getbuffer[b]}} {B~0~2pt}
+ {\framed[align=normal,strut=no,top=\vskip.5ex,bottom=\vskip.5ex]{\automatichyphenmode\plusone \hsize2pt \getbuffer[b]}} {B~1~2pt}
+ {\framed[align=normal,strut=no,top=\vskip.5ex,bottom=\vskip.5ex]{\automatichyphenmode\plustwo \hsize2pt \getbuffer[b]}} {B~2~2pt}
+ {\framed[align=normal,strut=no,top=\vskip.5ex,bottom=\vskip.5ex]{\automatichyphenmode\zerocount \hsize6em \getbuffer[c]}} {C~0~6em}
+ {\framed[align=normal,strut=no,top=\vskip.5ex,bottom=\vskip.5ex]{\automatichyphenmode\zerocount \hsize2pt \getbuffer[c]}} {C~0~2pt}
+ {\framed[align=normal,strut=no,top=\vskip.5ex,bottom=\vskip.5ex]{\automatichyphenmode\plusone \hsize2pt \getbuffer[c]}} {C~1~2pt}
+ {\framed[align=normal,strut=no,top=\vskip.5ex,bottom=\vskip.5ex]{\automatichyphenmode\plustwo \hsize2pt \getbuffer[c]}} {C~2~2pt}
+\stopcombination
+\stopbuffer
+
+\startplacefigure[reference=automatichyphenmode:1,title={The automatic modes \type {0} (default), \type {1} and \type {2}, with a \prm {hsize}
+of 6em and 2pt (which triggers a linebreak).}]
+ \dontcomplain \tt \getbuffer[demo]
+\stopplacefigure
+
+\startplacefigure[reference=automatichyphenmode:2,title={The automatic modes \type {0} (default), \type {1} and \type {2}, with \lpr {preexhyphenchar} and \lpr {postexhyphenchar} set to characters \type {A} and \type {B}.}]
+ \postexhyphenchar`A\relax
+ \preexhyphenchar `B\relax
+ \dontcomplain \tt \getbuffer[demo]
+\stopplacefigure
+
+In \in {figure} [automatichyphenmode:1] \in {and} [automatichyphenmode:2] we show
+what happens with three samples:
+
+Input A: \typebuffer[a]
+Input B: \typebuffer[b]
+Input C: \typebuffer[c]
+
+As with primitive companions of other single character commands, the \prm {-}
+command has a more verbose primitive version in \lpr {explicitdiscretionary}
+and the normally intercepted in the hyphenator character \type {-} (or whatever
+is configured) is available as \lpr {automaticdiscretionary}.
+
+\stopsection
+
+\startsection[title={The main control loop}]
+
+\topicindex {main loop}
+\topicindex {hyphenation}
+
+In \LUATEX's main loop, almost all input characters that are to be typeset are
+converted into \nod {glyph} node records with subtype \quote {character}, but
+there are a few exceptions.
+
+\startitemize[n]
+
+\startitem
+ The \prm {accent} primitive creates nodes with subtype \quote {glyph}
+ instead of \quote {character}: one for the actual accent and one for the
+ accentee. The primary reason for this is that \prm {accent} in \TEX82 is
+ explicitly dependent on the current font encoding, so it would not make much
+ sense to attach a new meaning to the primitive's name, as that would
+ invalidate many old documents and macro packages. A secondary reason is that
+ in \TEX82, \prm {accent} prohibits hyphenation of the current word. Since
+ in \LUATEX\ hyphenation only takes place on \quote {character} nodes, it is
+ possible to achieve the same effect. Of course, modern \UNICODE\ aware macro
+ packages will not use the \prm {accent} primitive at all but try to map
+ directly on composed characters.
+
+ This change of meaning did happen with \prm {char}, that now generates
+ \quote {glyph} nodes with a character subtype. In traditional \TEX\ there was
+ a strong relationship between the 8|-|bit input encoding, hyphenation and
+ glyphs taken from a font. In \LUATEX\ we have \UTF\ input, and in most cases
+ this maps directly to a character in a font, apart from glyph replacement in
+ the font engine. If you want to access arbitrary glyphs in a font directly
+ you can always use \LUA\ to do so, because fonts are available as \LUA\
+ table.
+\stopitem
+
+\startitem
+ All the results of processing in math mode eventually become nodes with
+ \quote {glyph} subtypes. In fact, the result of processing math is just
+ a regular list of glyphs, kerns, glue, penalties, boxes etc.
+\stopitem
+
+\startitem
+ Automatic discretionaries are handled differently. \TEX82 inserts an empty
+ discretionary after sensing an input character that matches the \prm
+ {hyphenchar} in the current font. This test is wrong in our opinion: whether
+ or not hyphenation takes place should not depend on the current font, it is a
+ language property. \footnote {When \TEX\ showed up we didn't have \UNICODE\
+ yet and being limited to eight bits meant that one sometimes had to
+ compromise between supporting character input, glyph rendering, hyphenation.}
+
+ In \LUATEX, it works like this: if \LUATEX\ senses a string of input
+ characters that matches the value of the new integer parameter \prm
+ {exhyphenchar}, it will insert an explicit discretionary after that series of
+ nodes. Initially \TEX\ sets the \type {\exhyphenchar=`\-}. Incidentally, this
+ is a global parameter instead of a language-specific one because it may be
+ useful to change the value depending on the document structure instead of the
+ text language.
+
+ The insertion of discretionaries after a sequence of explicit hyphens happens
+ at the same time as the other hyphenation processing, {\it not\/} inside the
+ main control loop.
+
+ The only use \LUATEX\ has for \prm {hyphenchar} is at the check whether a
+ word should be considered for hyphenation at all. If the \prm {hyphenchar}
+ of the font attached to the first character node in a word is negative, then
+ hyphenation of that word is abandoned immediately. This behaviour is added
+ for backward compatibility only, and the use of \type {\hyphenchar=-1} as a
+ means of preventing hyphenation should not be used in new \LUATEX\ documents.
+\stopitem
+
+\startitem
+ The \prm {setlanguage} command no longer creates whatsits. The meaning of
+ \prm {setlanguage} is changed so that it is now an integer parameter like all
+ others. That integer parameter is used in \type {\glyph_node} creation to add
+ language information to the glyph nodes. In conjunction, the \prm {language}
+ primitive is extended so that it always also updates the value of \prm
+ {setlanguage}.
+\stopitem
+
+\startitem
+ The \prm {noboundary} command (that prohibits word boundary processing
+ where that would normally take place) now does create nodes. These nodes are
+ needed because the exact place of the \prm {noboundary} command in the
+ input stream has to be retained until after the ligature and font processing
+ stages.
+\stopitem
+
+\startitem
+ There is no longer a \type {main_loop} label in the code. Remember that
+ \TEX82 did quite a lot of processing while adding \type {char_nodes} to the
+ horizontal list? For speed reasons, it handled that processing code outside
+ of the \quote {main control} loop, and only the first character of any \quote
+ {word} was handled by that \quote {main control} loop. In \LUATEX, there is
+ no longer a need for that (all hard work is done later), and the (now very
+ small) bits of character|-|handling code have been moved back inline. When
+ \prm {tracingcommands} is on, this is visible because the full word is
+ reported, instead of just the initial character.
+\stopitem
+
+\stopitemize
+
+Because we tend to make hard coded behaviour configurable a few new primitives
+have been added:
+
+\starttyping
+\hyphenpenaltymode
+\automatichyphenpenalty
+\explicithyphenpenalty
+\stoptyping
+
+The first parameter has the following consequences for automatic discs (the ones
+resulting from an \prm {exhyphenchar}):
+
+\starttabulate[|c|l|l|]
+\DB mode \BC automatic disc \type {-} \BC explicit disc \prm{-} \NC \NR
+\TB
+\NC \type{0} \NC \prm {exhyphenpenalty} \NC \prm {exhyphenpenalty} \NC \NR
+\NC \type{1} \NC \prm {hyphenpenalty} \NC \prm {hyphenpenalty} \NC \NR
+\NC \type{2} \NC \prm {exhyphenpenalty} \NC \prm {hyphenpenalty} \NC \NR
+\NC \type{3} \NC \prm {hyphenpenalty} \NC \prm {exhyphenpenalty} \NC \NR
+\NC \type{4} \NC \lpr {automatichyphenpenalty} \NC \lpr {explicithyphenpenalty} \NC \NR
+\NC \type{5} \NC \prm {exhyphenpenalty} \NC \lpr {explicithyphenpenalty} \NC \NR
+\NC \type{6} \NC \prm {hyphenpenalty} \NC \lpr {explicithyphenpenalty} \NC \NR
+\NC \type{7} \NC \lpr {automatichyphenpenalty} \NC \prm {exhyphenpenalty} \NC \NR
+\NC \type{8} \NC \lpr {automatichyphenpenalty} \NC \prm {hyphenpenalty} \NC \NR
+\LL
+\stoptabulate
+
+other values do what we always did in \LUATEX: insert \prm {exhyphenpenalty}.
+
+\stopsection
+
+\startsection[title={Loading patterns and exceptions},reference=patternsexceptions]
+
+\topicindex {hyphenation}
+\topicindex {hyphenation+patterns}
+\topicindex {hyphenation+exceptions}
+\topicindex {patterns}
+\topicindex {exceptions}
+
+Although we keep the traditional approach towards hyphenation (which is still
+superior) the implementation of the hyphenation algorithm in \LUATEX\ is quite
+different from the one in \TEX82.
+
+After expansion, the argument for \prm {patterns} has to be proper \UTF8 with
+individual patterns separated by spaces, no \prm {char} or \prm {chardef}d
+commands are allowed. The current implementation is quite strict and will reject
+all non|-|\UNICODE\ characters. Likewise, the expanded argument for \prm
+{hyphenation} also has to be proper \UTF8, but here a bit of extra syntax is
+provided:
+
+\startitemize[n]
+\startitem
+ Three sets of arguments in curly braces (\type {{}{}{}}) indicate a desired
+ complex discretionary, with arguments as in \prm {discretionary}'s command in
+ normal document input.
+\stopitem
+\startitem
+ A \type {-} indicates a desired simple discretionary, cf.\ \type {\-} and
+ \type {\discretionary{-}{}{}} in normal document input.
+\stopitem
+\startitem
+ Internal command names are ignored. This rule is provided especially for \prm
+ {discretionary}, but it also helps to deal with \prm {relax} commands that
+ may sneak in.
+\stopitem
+\startitem
+ An \type {=} indicates a (non|-|discretionary) hyphen in the document input.
+\stopitem
+\stopitemize
+
+The expanded argument is first converted back to a space|-|separated string while
+dropping the internal command names. This string is then converted into a
+dictionary by a routine that creates key|-|value pairs by converting the other
+listed items. It is important to note that the keys in an exception dictionary
+can always be generated from the values. Here are a few examples:
+
+\starttabulate[|l|l|l|]
+\DB value \BC implied key (input) \BC effect \NC\NR
+\TB
+\NC \type {ta-ble} \NC table \NC \type {ta\-ble} ($=$ \type {ta\discretionary{-}{}{}ble}) \NC\NR
+\NC \type {ba{k-}{}{c}ken} \NC backen \NC \type {ba\discretionary{k-}{}{c}ken} \NC\NR
+\LL
+\stoptabulate
+
+The resultant patterns and exception dictionary will be stored under the language
+code that is the present value of \prm {language}.
+
+In the last line of the table, you see there is no \prm {discretionary} command
+in the value: the command is optional in the \TEX-based input syntax. The
+underlying reason for that is that it is conceivable that a whole dictionary of
+words is stored as a plain text file and loaded into \LUATEX\ using one of the
+functions in the \LUA\ \type {lang} library. This loading method is quite a bit
+faster than going through the \TEX\ language primitives, but some (most?) of that
+speed gain would be lost if it had to interpret command sequences while doing so.
+
+It is possible to specify extra hyphenation points in compound words by using
+\type {{-}{}{-}} for the explicit hyphen character (replace \type {-} by the
+actual explicit hyphen character if needed). For example, this matches the word
+\quote {multi|-|word|-|boundaries} and allows an extra break inbetween \quote
+{boun} and \quote {daries}:
+
+\starttyping
+\hyphenation{multi{-}{}{-}word{-}{}{-}boun-daries}
+\stoptyping
+
+The motivation behind the \ETEX\ extension \prm {savinghyphcodes} was that
+hyphenation heavily depended on font encodings. This is no longer true in
+\LUATEX, and the corresponding primitive is basically ignored. Because we now
+have \lpr {hjcode}, the case related codes can be used exclusively for \prm
+{uppercase} and \prm {lowercase}.
+
+The three curly brace pair pattern in an exception can be somewhat unexpected so
+we will try to explain it by example. The pattern \type {foo{}{}{x}bar} pattern
+creates a lookup \type {fooxbar} and the pattern \type {foo{}{}{}bar} creates
+\type {foobar}. Then, when a hit happens there is a replacement text (\type {x})
+or none. Because we introduced penalties in discretionary nodes, the exception
+syntax now also can take a penalty specification. The value between square brackets
+is a multiplier for \lpr {exceptionpenalty}. Here we have set it to 10000 so
+effectively we get 30000 in the example.
+
+\def\ShowSample#1#2%
+ {\startlinecorrection[blank]
+ \hyphenation{#1}%
+ \exceptionpenalty=10000
+ \bTABLE[foregroundstyle=type]
+ \bTR
+ \bTD[align=middle,nx=4] \type{#1} \eTD
+ \eTR
+ \bTR
+ \bTD[align=middle] \type{10em} \eTD
+ \bTD[align=middle] \type {3em} \eTD
+ \bTD[align=middle] \type {0em} \eTD
+ \bTD[align=middle] \type {6em} \eTD
+ \eTR
+ \bTR
+ \bTD[width=10em]\vtop{\hsize 10em 123 #2 123\par}\eTD
+ \bTD[width=10em]\vtop{\hsize 3em 123 #2 123\par}\eTD
+ \bTD[width=10em]\vtop{\hsize 0em 123 #2 123\par}\eTD
+ \bTD[width=10em]\vtop{\setupalign[verytolerant,stretch]\rmtf\hsize 6em 123 #2 #2 #2 #2 123\par}\eTD
+ \eTR
+ \eTABLE
+ \stoplinecorrection}
+
+\ShowSample{x{a-}{-b}{}x{a-}{-b}{}x{a-}{-b}{}x{a-}{-b}{}xx}{xxxxxx}
+\ShowSample{x{a-}{-b}{}x{a-}{-b}{}[3]x{a-}{-b}{}[1]x{a-}{-b}{}xx}{xxxxxx}
+
+\ShowSample{z{a-}{-b}{z}{a-}{-b}{z}{a-}{-b}{z}{a-}{-b}{z}z}{zzzzzz}
+\ShowSample{z{a-}{-b}{z}{a-}{-b}{z}[3]{a-}{-b}{z}[1]{a-}{-b}{z}z}{zzzzzz}
+
+\stopsection
+
+\startsection[title={Applying hyphenation}]
+
+\topicindex {hyphenation+how it works}
+\topicindex {hyphenation+discretionaries}
+\topicindex {discretionaries}
+
+The internal structures \LUATEX\ uses for the insertion of discretionaries in
+words is very different from the ones in \TEX82, and that means there are some
+noticeable differences in handling as well.
+
+First and foremost, there is no \quote {compressed trie} involved in hyphenation.
+The algorithm still reads pattern files generated by \PATGEN, but \LUATEX\ uses a
+finite state hash to match the patterns against the word to be hyphenated. This
+algorithm is based on the \quote {libhnj} library used by \OPENOFFICE, which in
+turn is inspired by \TEX.
+
+There are a few differences between \LUATEX\ and \TEX82 that are a direct result
+of the implementation:
+
+\startitemize
+\startitem
+ \LUATEX\ happily hyphenates the full \UNICODE\ character range.
+\stopitem
+\startitem
+ Pattern and exception dictionary size is limited by the available memory
+ only, all allocations are done dynamically. The trie|-|related settings in
+ \type {texmf.cnf} are ignored.
+\stopitem
+\startitem
+ Because there is no \quote {trie preparation} stage, language patterns never
+ become frozen. This means that the primitive \prm {patterns} (and its \LUA\
+ counterpart \type {lang.patterns}) can be used at any time, not only in
+ ini\TEX.
+\stopitem
+\startitem
+ Only the string representation of \prm {patterns} and \prm {hyphenation} is
+ stored in the format file. At format load time, they are simply
+ re|-|evaluated. It follows that there is no real reason to preload languages
+ in the format file. In fact, it is usually not a good idea to do so. It is
+ much smarter to load patterns no sooner than the first time they are actually
+ needed.
+\stopitem
+\startitem
+ \LUATEX\ uses the language-specific variables \lpr {prehyphenchar} and \lpr
+ {posthyphenchar} in the creation of implicit discretionaries, instead of
+ \TEX82's \prm {hyphenchar}, and the values of the language|-|specific
+ variables \lpr {preexhyphenchar} and \lpr {postexhyphenchar} for explicit
+ discretionaries (instead of \TEX82's empty discretionary).
+\stopitem
+\startitem
+ The value of the two counters related to hyphenation, \prm {hyphenpenalty}
+ and \prm {exhyphenpenalty}, are now stored in the discretionary nodes. This
+ permits a local overload for explicit \prm {discretionary} commands. The
+ value current when the hyphenation pass is applied is used. When no callbacks
+ are used this is compatible with traditional \TEX. When you apply the \LUA\
+ \type {lang.hyphenate} function the current values are used.
+\stopitem
+\startitem
+ The hyphenation exception dictionary is maintained as key|-|value hash, and
+ that is also dynamic, so the \type {hyph_size} setting is not used either.
+\stopitem
+\stopitemize
+
+Because we store penalties in the disc node the \prm {discretionary} command has
+been extended to accept an optional penalty specification, so you can do the
+following:
+
+\startbuffer
+\hsize1mm
+1:foo{\hyphenpenalty 10000\discretionary{}{}{}}bar\par
+2:foo\discretionary penalty 10000 {}{}{}bar\par
+3:foo\discretionary{}{}{}bar\par
+\stopbuffer
+
+\typebuffer
+
+This results in:
+
+\blank \start \getbuffer \stop \blank
+
+Inserted characters and ligatures inherit their attributes from the nearest glyph
+node item (usually the preceding one, but the following one for the items
+inserted at the left-hand side of a word).
+
+Word boundaries are no longer implied by font switches, but by language switches.
+One word can have two separate fonts and still be hyphenated correctly (but it
+can not have two different languages, the \prm {setlanguage} command forces a
+word boundary).
+
+All languages start out with \type {\prehyphenchar=`\-}, \type {\posthyphenchar=0},
+\type {\preexhyphenchar=0} and \type {\postexhyphenchar=0}. When you assign the
+values of one of these four parameters, you are actually changing the settings
+for the current \prm {language}, this behaviour is compatible with \prm {patterns}
+and \prm {hyphenation}.
+
+\LUATEX\ also hyphenates the first word in a paragraph. Words can be up to 256
+characters long (up from 64 in \TEX82). Longer words are ignored right now, but
+eventually either the limitation will be removed or perhaps it will become
+possible to silently ignore the excess characters (this is what happens in
+\TEX82, but there the behaviour cannot be controlled).
+
+If you are using the \LUA\ function \type {lang.hyphenate}, you should be aware
+that this function expects to receive a list of \quote {character} nodes. It will
+not operate properly in the presence of \quote {glyph}, \quote {ligature}, or
+\quote {ghost} nodes, nor does it know how to deal with kerning.
+
+\stopsection
+
+\startsection[title={Applying ligatures and kerning}]
+
+\topicindex {ligatures}
+\topicindex {kerning}
+
+After all possible hyphenation points have been inserted in the list, \LUATEX\
+will process the list to convert the \quote {character} nodes into \quote {glyph}
+and \quote {ligature} nodes. This is actually done in two stages: first all
+ligatures are processed, then all kerning information is applied to the result
+list. But those two stages are somewhat dependent on each other: If the used font
+makes it possible to do so, the ligaturing stage adds virtual \quote {character}
+nodes to the word boundaries in the list. While doing so, it removes and
+interprets \prm {noboundary} nodes. The kerning stage deletes those word
+boundary items after it is done with them, and it does the same for \quote
+{ghost} nodes. Finally, at the end of the kerning stage, all remaining \quote
+{character} nodes are converted to \quote {glyph} nodes.
+
+This separation is worth mentioning because, if you overrule from \LUA\ only one
+of the two callbacks related to font handling, then you have to make sure you
+perform the tasks normally done by \LUATEX\ itself in order to make sure that the
+other, non|-|overruled, routine continues to function properly.
+
+Although we could improve the situation the reality is that in modern \OPENTYPE\
+fonts ligatures can be constructed in many ways: by replacing a sequence of
+characters by one glyph, or by selectively replacing individual glyphs, or by
+kerning, or any combination of this. Add to that contextual analysis and it will
+be clear that we have to let \LUA\ do that job instead. The generic font handler
+that we provide (which is part of \CONTEXT) distinguishes between base mode
+(which essentially is what we describe here and which delegates the task to \TEX)
+and node mode (which deals with more complex fonts.
+
+Let's look at an example. Take the word \type {office}, hyphenated \type
+{of-fice}, using a \quote {normal} font with all the \type {f}-\type {f} and
+\type {f}-\type {i} type ligatures:
+
+\starttabulate[|l|l|]
+\NC initial \NC \type {{o}{f}{f}{i}{c}{e}} \NC\NR
+\NC after hyphenation \NC \type {{o}{f}{{-},{},{}}{f}{i}{c}{e}} \NC\NR
+\NC first ligature stage \NC \type {{o}{{f-},{f},{<ff>}}{i}{c}{e}} \NC\NR
+\NC final result \NC \type {{o}{{f-},{<fi>},{<ffi>}}{c}{e}} \NC\NR
+\stoptabulate
+
+That's bad enough, but let us assume that there is also a hyphenation point
+between the \type {f} and the \type {i}, to create \type {of-f-ice}. Then the
+final result should be:
+
+\starttyping
+{o}{{f-},
+ {{f-},
+ {i},
+ {<fi>}},
+ {{<ff>-},
+ {i},
+ {<ffi>}}}{c}{e}
+\stoptyping
+
+with discretionaries in the post-break text as well as in the replacement text of
+the top-level discretionary that resulted from the first hyphenation point.
+
+Here is that nested solution again, in a different representation:
+
+\testpage[4]
+
+\starttabulate[|l|c|c|c|c|c|c|]
+\DB \BC pre \BC \BC post \BC \BC replace \BC \NC \NR
+\TB
+\NC topdisc \NC \type {f-} \NC (1) \NC sub 1 \NC \NC sub 2 \NC \NC \NR
+\NC sub 1 \NC \type {f-} \NC (2) \NC \type {i} \NC (3) \NC \type {<fi>} \NC (4) \NC \NR
+\NC sub 2 \NC \type {<ff>-} \NC (5) \NC \type {i} \NC (6) \NC \type {<ffi>} \NC (7) \NC \NR
+\LL
+\stoptabulate
+
+When line breaking is choosing its breakpoints, the following fields will
+eventually be selected:
+
+\starttabulate[|l|c|c|]
+\NC \type {of-f-ice} \NC \type {f-} \NC (1) \NC \NR
+\NC \NC \type {f-} \NC (2) \NC \NR
+\NC \NC \type {i} \NC (3) \NC \NR
+\NC \type {of-fice} \NC \type {f-} \NC (1) \NC \NR
+\NC \NC \type {<fi>} \NC (4) \NC \NR
+\NC \type {off-ice} \NC \type {<ff>-} \NC (5) \NC \NR
+\NC \NC \type {i} \NC (6) \NC \NR
+\NC \type {office} \NC \type {<ffi>} \NC (7) \NC \NR
+\stoptabulate
+
+The current solution in \LUATEX\ is not able to handle nested discretionaries,
+but it is in fact smart enough to handle this fictional \type {of-f-ice} example.
+It does so by combining two sequential discretionary nodes as if they were a
+single object (where the second discretionary node is treated as an extension of
+the first node).
+
+One can observe that the \type {of-f-ice} and \type {off-ice} cases both end with
+the same actual post replacement list (\type {i}), and that this would be the
+case even if \type {i} was the first item of a potential following ligature like
+\type {ic}. This allows \LUATEX\ to do away with one of the fields, and thus make
+the whole stuff fit into just two discretionary nodes.
+
+The mapping of the seven list fields to the six fields in this discretionary node
+pair is as follows:
+
+\starttabulate[|l|c|c|]
+\DB field \BC description \NC \NC \NR
+\TB
+\NC \type {disc1.pre} \NC \type {f-} \NC (1) \NC \NR
+\NC \type {disc1.post} \NC \type {<fi>} \NC (4) \NC \NR
+\NC \type {disc1.replace} \NC \type {<ffi>} \NC (7) \NC \NR
+\NC \type {disc2.pre} \NC \type {f-} \NC (2) \NC \NR
+\NC \type {disc2.post} \NC \type {i} \NC (3,6) \NC \NR
+\NC \type {disc2.replace} \NC \type {<ff>-} \NC (5) \NC \NR
+\LL
+\stoptabulate
+
+What is actually generated after ligaturing has been applied is therefore:
+
+\starttyping
+{o}{{f-},
+ {<fi>},
+ {<ffi>}}
+ {{f-},
+ {i},
+ {<ff>-}}{c}{e}
+\stoptyping
+
+The two discretionaries have different subtypes from a discretionary appearing on
+its own: the first has subtype 4, and the second has subtype 5. The need for
+these special subtypes stems from the fact that not all of the fields appear in
+their \quote {normal} location. The second discretionary especially looks odd,
+with things like the \type {<ff>-} appearing in \type {disc2.replace}. The fact
+that some of the fields have different meanings (and different processing code
+internally) is what makes it necessary to have different subtypes: this enables
+\LUATEX\ to distinguish this sequence of two joined discretionary nodes from the
+case of two standalone discretionaries appearing in a row.
+
+Of course there is still that relationship with fonts: ligatures can be implemented by
+mapping a sequence of glyphs onto one glyph, but also by selective replacement and
+kerning. This means that the above examples are just representing the traditional
+approach.
+
+\stopsection
+
+\startsection[title={Breaking paragraphs into lines}]
+
+\topicindex {linebreaks}
+\topicindex {paragraphs}
+\topicindex {discretionaries}
+
+This code is almost unchanged, but because of the above|-|mentioned changes with
+respect to discretionaries and ligatures, line breaking will potentially be
+different from traditional \TEX. The actual line breaking code is still based on
+the \TEX82 algorithms, and there can be no discretionaries inside of
+discretionaries. But, as patterns evolve and font handling can influence
+discretionaries, you need to be aware of the fact that long term consistency is
+not an engine matter only.
+
+But that situation is now fairly common in \LUATEX, due to the changes to the
+ligaturing mechanism. And also, the \LUATEX\ discretionary nodes are implemented
+slightly different from the \TEX82 nodes: the \type {no_break} text is now
+embedded inside the disc node, where previously these nodes kept their place in
+the horizontal list. In traditional \TEX\ the discretionary node contains a
+counter indicating how many nodes to skip, but in \LUATEX\ we store the pre, post
+and replace text in the discretionary node.
+
+The combined effect of these two differences is that \LUATEX\ does not always use
+all of the potential breakpoints in a paragraph, especially when fonts with many
+ligatures are used. Of course kerning also complicates matters here.
+
+\stopsection
+
+\startsection[title={The \type {lang} library}][library=lang]
+
+\subsection {\type {new} and \type {id}}
+
+\topicindex {languages+library}
+
+\libindex {new}
+\libindex {id}
+
+This library provides the interface to \LUATEX's structure representing a
+language, and the associated functions.
+
+\startfunctioncall
+<language> l = lang.new()
+<language> l = lang.new(<number> id)
+\stopfunctioncall
+
+This function creates a new userdata object. An object of type \type {<language>}
+is the first argument to most of the other functions in the \type {lang} library.
+These functions can also be used as if they were object methods, using the colon
+syntax. Without an argument, the next available internal id number will be
+assigned to this object. With argument, an object will be created that links to
+the internal language with that id number.
+
+\startfunctioncall
+<number> n = lang.id(<language> l)
+\stopfunctioncall
+
+The number returned is the internal \prm {language} id number this object refers to.
+
+\subsection {\type {hyphenation}}
+
+\libindex {hyphenation}
+
+You can hyphenate a string directly with:
+
+\startfunctioncall
+<string> n = lang.hyphenation(<language> l)
+lang.hyphenation(<language> l, <string> n)
+\stopfunctioncall
+
+\subsection {\type {clear_hyphenation} and \type {clean}}
+
+\libindex {clear_hyphenation}
+\libindex {clean}
+
+This either returns the current hyphenation exceptions for this language, or adds
+new ones. The syntax of the string is explained in~\in {section}
+[patternsexceptions].
+
+\startfunctioncall
+lang.clear_hyphenation(<language> l)
+\stopfunctioncall
+
+This call clears the exception dictionary (string) for this language.
+
+\startfunctioncall
+<string> n = lang.clean(<language> l, <string> o)
+<string> n = lang.clean(<string> o)
+\stopfunctioncall
+
+This function creates a hyphenation key from the supplied hyphenation value. The
+syntax of the argument string is explained in \in {section} [patternsexceptions].
+This function is useful if you want to do something else based on the words in a
+dictionary file, like spell|-|checking.
+
+\subsection {\type {patterns} and \type {clear_patterns}}
+
+\libindex {patterns}
+\libindex {clear_patterns}
+
+\startfunctioncall
+<string> n = lang.patterns(<language> l)
+lang.patterns(<language> l, <string> n)
+\stopfunctioncall
+
+This adds additional patterns for this language object, or returns the current
+set. The syntax of this string is explained in \in {section}
+[patternsexceptions].
+
+\startfunctioncall
+lang.clear_patterns(<language> l)
+\stopfunctioncall
+
+This can be used to clear the pattern dictionary for a language.
+
+\subsection {\type {hyphenationmin}}
+
+\libindex {hyphenationmin}
+
+This function sets (or gets) the value of the \TEX\ parameter
+\type {\hyphenationmin}.
+
+\startfunctioncall
+n = lang.hyphenationmin(<language> l)
+lang.hyphenationmin(<language> l, <number> n)
+\stopfunctioncall
+
+\subsection {\type {[pre|post][ex|]hyphenchar}}
+
+\libindex {prehyphenchar}
+\libindex {posthyphenchar}
+\libindex {preexhyphenchar}
+\libindex {postexhyphenchar}
+
+\startfunctioncall
+<number> n = lang.prehyphenchar(<language> l)
+lang.prehyphenchar(<language> l, <number> n)
+
+<number> n = lang.posthyphenchar(<language> l)
+lang.posthyphenchar(<language> l, <number> n)
+\stopfunctioncall
+
+These two are used to get or set the \quote {pre|-|break} and \quote
+{post|-|break} hyphen characters for implicit hyphenation in this language. The
+intial values are decimal 45 (hyphen) and decimal~0 (indicating emptiness).
+
+\startfunctioncall
+<number> n = lang.preexhyphenchar(<language> l)
+lang.preexhyphenchar(<language> l, <number> n)
+
+<number> n = lang.postexhyphenchar(<language> l)
+lang.postexhyphenchar(<language> l, <number> n)
+\stopfunctioncall
+
+These gets or set the \quote {pre|-|break} and \quote {post|-|break} hyphen
+characters for explicit hyphenation in this language. Both are initially
+decimal~0 (indicating emptiness).
+
+\subsection {\type {hyphenate}}
+
+\libindex {hyphenate}
+
+The next call inserts hyphenation points (discretionary nodes) in a node list. If
+\type {tail} is given as argument, processing stops on that node. Currently,
+\type {success} is always true if \type {head} (and \type {tail}, if specified)
+are proper nodes, regardless of possible other errors.
+
+\startfunctioncall
+<boolean> success = lang.hyphenate(<node> head)
+<boolean> success = lang.hyphenate(<node> head, <node> tail)
+\stopfunctioncall
+
+Hyphenation works only on \quote {characters}, a special subtype of all the glyph
+nodes with the node subtype having the value \type {1}. Glyph modes with
+different subtypes are not processed. See \in {section} [charsandglyphs] for
+more details.
+
+\subsection {\type {[set|get]hjcode}}
+
+\libindex {sethjcode}
+\libindex {gethjcode}
+
+The following two commands can be used to set or query hj codes:
+
+\startfunctioncall
+lang.sethjcode(<language> l, <number> char, <number> usedchar)
+<number> usedchar = lang.gethjcode(<language> l, <number> char)
+\stopfunctioncall
+
+When you set a hjcode the current sets get initialized unless the set was already
+initialized due to \prm {savinghyphcodes} being larger than zero.
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
+
+% \parindent0pt \hsize=1.1cm
+% 12-34-56 \par
+% 12-34-\hbox{56} \par
+% 12-34-\vrule width 1em height 1.5ex \par
+% 12-\hbox{34}-56 \par
+% 12-\vrule width 1em height 1.5ex-56 \par
+% \hjcode`\1=`\1 \hjcode`\2=`\2 \hjcode`\3=`\3 \hjcode`\4=`\4 \vskip.5cm
+% 12-34-56 \par
+% 12-34-\hbox{56} \par
+% 12-34-\vrule width 1em height 1.5ex \par
+% 12-\hbox{34}-56 \par
+% 12-\vrule width 1em height 1.5ex-56 \par
+
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-libraries.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-libraries.tex
new file mode 100644
index 00000000000..d8210ac48c7
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-libraries.tex
@@ -0,0 +1,573 @@
+% language=uk
+
+\environment luametatex-style
+
+\startcomponent luametatex-libraries
+
+\startchapter[reference=libraries,title={Extra libraries}]
+
+\startsection[title=Introduction]
+
+The libraries can be grouped in categories like fonts, languages, \TEX,
+\METAPOST, \PDF, etc. There are however also some that are more general puspose
+and these are discussed here.
+
+\stopsection
+
+\startsection[title=File and string readers: \type {fio} and type {sio}]
+
+This library provides a set of functions for reading numbers from a file and
+in addition to the regular \type {io} library functions. The following
+work on normal \LUA\ file handles.
+
+\starttabulate[|Tw(12em)|T|T|]
+\DB name \BC arguments \BC results \NC \NR
+\TB
+\NC readcardinal1 \NC (f) \NC a 1 byte unsigned integer \NC \NR
+\NC readcardinal2 \NC (f) \NC a 2 byte unsigned integer \NC \NR
+\NC readcardinal3 \NC (f) \NC a 3 byte unsigned integer \NC \NR
+\NC readcardinal4 \NC (f) \NC a 4 byte unsigned integer \NC \NR
+\NC readcardinaltable \NC (f,n,b) \NC \type {n} cardinals of \type {b} bytes \NC \NR
+\NC readinteger1 \NC (f) \NC a 1 byte signed integer \NC \NR
+\NC readinteger2 \NC (f) \NC a 2 byte signed integer \NC \NR
+\NC readinteger3 \NC (f) \NC a 3 byte signed integer \NC \NR
+\NC readinteger4 \NC (f) \NC a 4 byte signed integer \NC \NR
+\NC readintegertable \NC (f,n,b) \NC \type {n} integers of \type {b} bytes \NC \NR
+\NC readfixed2 \NC (f) \NC a 2 byte float (used in font files) \NC \NR
+\NC readfixed4 \NC (f) \NC a 4 byte float (used in font files) \NC \NR
+\NC read2dot14 \NC (f) \NC a 2 byte float (used in font files) \NC \NR
+\NC setposition \NC (f,p) \NC goto position \type {p} \NC \NR
+\NC getposition \NC (f) \NC get the current position \NC \NR
+\NC skipposition \NC (f,n) \NC skip \type {n} positions \NC \NR
+\NC readbytes \NC (f,n) \NC \type {n} bytes \NC \NR
+\NC readbytetable \NC (f,n) \NC \type {n} bytes\NC \NR
+\LL
+\stoptabulate
+
+When relevant there are also variants that end with \type {le} that do it the
+little endian way.
+
+A similar set of function as in the \type {fio} library is available in the \type
+{sio} library: \libidx {sio} {readcardinal1}, \libidx {sio} {readcardinal2},
+\libidx {sio} {readcardinal3}, \libidx {sio} {readcardinal4}, \libidx {sio}
+{readcardinaltable}, \libidx {sio} {readinteger1}, \libidx {sio} {readinteger2},
+\libidx {sio} {readinteger3}, \libidx {sio} {readinteger4}, \libidx {sio}
+{readintegertable}, \libidx {sio} {readfixed2}, \libidx {sio} {readfixed4},
+\libidx {sio} {read2dot14}, \libidx {sio} {setposition}, \libidx {sio}
+{getposition}, \libidx {sio} {skipposition}, \libidx {sio} {readbytes} and
+\libidx {sio} {readbytetable}. Here the first argument is a string instead of a
+file handle.
+
+\stopsection
+
+\startsection[title=\type{md5}]
+
+\starttabulate[|Tw(12em)|T|T|]
+\DB name \BC arguments \BC results \NC \NR
+\TB
+\NC sum \NC \NC \NC \NR
+\NC hex \NC \NC \NC \NR
+\NC HEX \NC \NC \NC \NR
+\LL
+\stoptabulate
+
+\stopsection
+
+\startsection[title=\type{sha2}]
+
+\starttabulate[|Tw(12em)|T|T|]
+\DB name \BC arguments \BC results \NC \NR
+\TB
+\NC digest256 \NC \NC \NC \NR
+\NC digest384 \NC \NC \NC \NR
+\NC digest512 \NC \NC \NC \NR
+\LL
+\stoptabulate
+
+\stopsection
+
+% \startsection[title=\type{flate}]
+%
+% \starttabulate[|Tw(12em)|T|T|]
+% \DB name \BC arguments \BC results \NC \NR
+% \TB
+% \NC flate_compress \NC \NC \NC \NR
+% \NC flate_decompress \NC \NC \NC \NR
+% \NC zip_compress \NC \NC \NC \NR
+% \NC zip_decompress \NC \NC \NC \NR
+% \NC gz_compress \NC \NC \NC \NR
+% \NC gz_decompress \NC \NC \NC \NR
+% \NC update_adler32 \NC \NC \NC \NR
+% \NC update_crc32 \NC \NC \NC \NR
+% \LL
+% \stoptabulate
+%
+% \stopsection
+
+\startsection[title=\type{xzip}]
+
+\starttabulate[|Tw(12em)|T|T|]
+\DB name \BC arguments \BC results \NC \NR
+\TB
+\NC compress \NC \NC \NC \NR
+\NC decompress \NC \NC \NC \NR
+\NC adler32 \NC \NC \NC \NR
+\NC crc32 \NC \NC \NC \NR
+\LL
+\stoptabulate
+
+\stopsection
+
+\startsection[title=\type{xmath}]
+
+This library just opens up standard \CCODE\ math library and the main reason for
+it being there is that it permits advanced graphics in \METAPOST\ (via the \LUA\
+interface). There are three constant values:
+
+\starttabulate[|Tw(12em)|T|T|]
+\DB name \BC arguments \BC results \NC \NR
+\TB
+\NC inf \NC \emdash \NC \cldcontext{xmath.inf} \NC \NR
+\NC nan \NC \emdash \NC \cldcontext{xmath.nan} \NC \NR
+\NC pi \NC \emdash \NC \cldcontext{xmath.pi} \NC \NR
+\LL
+\stoptabulate
+
+and a lot of functions:
+
+\starttabulate[|Tw(12em)|T|T|]
+\DB name \BC arguments \BC results \NC \NR
+\TB
+\NC acos \NC (a) \NC \NC \NR
+\NC acosh \NC (a) \NC \NC \NR
+\NC asin \NC (a) \NC \NC \NR
+\NC asinh \NC (a) \NC \NC \NR
+\NC atan \NC (a[,b]) \NC \NC \NR
+\NC atan2 \NC (a[,b]) \NC \NC \NR
+\NC atanh \NC (a) \NC \NC \NR
+\NC cbrt \NC (a) \NC \NC \NR
+\NC ceil \NC (a) \NC \NC \NR
+\NC copysign \NC (a,b) \NC \NC \NR
+\NC cos \NC (a) \NC \NC \NR
+\NC cosh \NC (a) \NC \NC \NR
+\NC deg \NC (a) \NC \NC \NR
+\NC erf \NC (a) \NC \NC \NR
+\NC erfc \NC (a) \NC \NC \NR
+\NC exp \NC (a) \NC \NC \NR
+\NC exp2 \NC (a) \NC \NC \NR
+\NC expm1 \NC (a) \NC \NC \NR
+\NC fabs \NC (a) \NC \NC \NR
+\NC fdim \NC (a,b) \NC \NC \NR
+\NC floor \NC (a) \NC \NC \NR
+\NC fma \NC (a,b,c) \NC \NC \NR
+\NC fmax \NC (...) \NC \NC \NR
+\NC fmin \NC (...) \NC \NC \NR
+\NC fmod \NC (a,b) \NC \NC \NR
+\NC frexp \NC (a,b) \NC \NC \NR
+\NC gamma \NC (a) \NC \NC \NR
+\NC hypot \NC (a,b) \NC \NC \NR
+\NC isfinite \NC (a) \NC \NC \NR
+\NC isinf \NC (a) \NC \NC \NR
+\NC isnan \NC (a) \NC \NC \NR
+\NC isnormal \NC (a) \NC \NC \NR
+\NC j0 \NC (a) \NC \NC \NR
+\NC j1 \NC (a) \NC \NC \NR
+\NC jn \NC (a,b) \NC \NC \NR
+\NC ldexp \NC (a,b) \NC \NC \NR
+\NC lgamma \NC (a) \NC \NC \NR
+\NC l0 \NC (a) \NC \NC \NR
+\NC l1 \NC (a) \NC \NC \NR
+\NC ln \NC (a,b) \NC \NC \NR
+\NC log \NC (a[,b]) \NC \NC \NR
+\NC log10 \NC (a) \NC \NC \NR
+\NC log1p \NC (a) \NC \NC \NR
+\NC log2 \NC (a) \NC \NC \NR
+\NC logb \NC (a) \NC \NC \NR
+\NC modf \NC (a,b) \NC \NC \NR
+\NC nearbyint \NC (a) \NC \NC \NR
+\NC nextafter \NC (a,b) \NC \NC \NR
+\NC pow \NC (a,b) \NC \NC \NR
+\NC rad \NC (a) \NC \NC \NR
+\NC remainder \NC (a,b) \NC \NC \NR
+\NC remquo \NC (a,b) \NC \NC \NR
+\NC round \NC (a) \NC \NC \NR
+\NC scalbn \NC (a,b) \NC \NC \NR
+\NC sin \NC (a) \NC \NC \NR
+\NC sinh \NC (a) \NC \NC \NR
+\NC sqrt \NC (a) \NC \NC \NR
+\NC tan \NC (a) \NC \NC \NR
+\NC tanh \NC (a) \NC \NC \NR
+\NC tgamma \NC (a) \NC \NC \NR
+\NC trunc \NC (a) \NC \NC \NR
+\NC y0 \NC (a) \NC \NC \NR
+\NC y1 \NC (a) \NC \NC \NR
+\NC yn \NC (a) \NC \NC \NR
+\LL
+\stoptabulate
+
+\stopsection
+
+\startsection[title=\type{xcomplex}]
+
+\LUAMETATEX\ also provides a complex library \type {xcomplex}. The complex
+number is a userdatum:
+
+\starttabulate[|Tw(12em)|T|T|]
+\DB name \BC arguments \BC results \NC \NR
+\TB
+\NC new \NC (r,i) \NC a complex userdata type \NC \NR
+\NC tostring \NC (z) \NC a string representation \NC \NR
+\NC topair \NC (z) \NC two numbers \NC \NR
+\LL
+\stoptabulate
+
+There is a bunch of functions that take a complex number:
+
+\starttabulate[|Tw(12em)|T|T|]
+\DB name \BC arguments \BC results \NC \NR
+\TB
+\NC abs \NC (a) \NC \NC \NR
+\NC arg \NC (a) \NC \NC \NR
+\NC imag \NC (a) \NC \NC \NR
+\NC real \NC (a) \NC \NC \NR
+\NC onj \NC (a) \NC \NC \NR
+\NC proj \NC (a) \NC \NC \NR
+\NC exp" \NC (a) \NC \NC \NR
+\NC log \NC (a) \NC \NC \NR
+\NC sqrt \NC (a) \NC \NC \NR
+\NC pow \NC (a,b) \NC \NC \NR
+\NC sin \NC (a) \NC \NC \NR
+\NC cos \NC (a) \NC \NC \NR
+\NC tan \NC (a) \NC \NC \NR
+\NC asin \NC (a) \NC \NC \NR
+\NC acos \NC (a) \NC \NC \NR
+\NC atan \NC (a) \NC \NC \NR
+\NC sinh \NC (a) \NC \NC \NR
+\NC cosh \NC (a) \NC \NC \NR
+\NC tanh \NC (a) \NC \NC \NR
+\NC asinh \NC (a) \NC \NC \NR
+\NC acosh \NC (a) \NC \NC \NR
+\NC atanh \NC (a) \NC \NC \NR
+\LL
+\stoptabulate
+
+These are accompanied by \type {libcerf} functions:
+
+\starttabulate[|Tw(12em)|T|T|]
+\DB name \BC arguments \BC results \NC \NR
+\TB
+\NC erf \NC (a) \NC The complex error function erf(z) \NC \NR
+\NC erfc \NC (a) \NC The complex complementary error function erfc(z) = 1 - erf(z) \NC \NR
+\NC erfcx \NC (a) \NC The underflow-compensating function erfcx(z) = exp(z^2) erfc(z) \NC \NR
+\NC erfi \NC (a) \NC The imaginary error function erfi(z) = -i erf(iz) \NC \NR
+\NC dawson \NC (a) \NC Dawson's integral D(z) = sqrt(pi)/2 * exp(-z^2) * erfi(z) \NC \NR
+\NC voigt \NC (a,b,c) \NC The convolution of a Gaussian and a Lorentzian \NC \NR
+\NC voigt_hwhm \NC (a,b) \NC The half width at half maximum of the Voigt profile \NC \NR
+\LL
+\stoptabulate
+
+\stopsection
+
+\startsection[title=\type{lfs}]
+
+The original \type {lfs} module has been adapted a bit to our needs but for
+practical reasons we kept the namespace. This module will probably evolve a bit
+over time.
+
+\starttabulate[|Tw(12em)|T|Tp|]
+\DB name \BC arguments \BC results \NC \NR
+\TB
+\NC attributes \NC (name) \NC \NC \NR
+\NC chdir \NC (name) \NC \NC \NR
+\NC currentdir \NC () \NC \NC \NR
+\NC dir \NC (name) \NC \type {name}, \type {mode}, \type {size} and \type {mtime} \NC \NR
+\NC mkdir \NC (name) \NC \NC \NR
+\NC rmdir \NC (name) \NC \NC \NR
+\NC touch \NC (name) \NC \NC \NR
+\NC link \NC (name) \NC \NC \NR
+\NC symlinkattributes \NC (name) \NC \NC \NR
+\NC isdir \NC (name) \NC \NC \NR
+\NC isfile \NC (name) \NC \NC \NR
+\NC iswriteabledir \NC (name) \NC \NC \NR
+\NC iswriteablefile \NC (name) \NC \NC \NR
+\NC isreadabledir \NC (name) \NC \NC \NR
+\NC isreadablefile \NC (name) \NC \NC \NR
+\LL
+\stoptabulate
+
+The \type {dir} function is a traverser which in addition to the name returns
+some more properties. Keep in mind that the traverser loops over a directory and
+that it doesn't run well when used nested. This is a side effect of the operating
+system. It is also the reason why we return some properties because querying them
+via \type {attributes} would interfere badly.
+
+The following attributes are returned by \type {attributes}:
+
+\starttabulate[|Tw(12em)|T|]
+\DB name \BC value \NC \NR
+\TB
+\NC mode \NC \NC \NR
+\NC size \NC \NC \NR
+\NC modification \NC \NC \NR
+\NC access \NC \NC \NR
+\NC change \NC \NC \NR
+\NC permissions \NC \NC \NR
+\NC nlink \NC \NC \NR
+\LL
+\stoptabulate
+
+\stopsection
+
+\startsection[title=\type{pngdecode}]
+
+This module is experimental and used in image inclusion. It is not some general
+purpose module and is supposed to be used in a very controlled way. The
+interfaces might evolve.
+
+\starttabulate[|Tw(12em)|T|T|]
+\DB name \BC arguments \BC results \NC \NR
+\TB
+\NC applyfilter \NC (str,nx,ny,slice) \NC string \NC \NR
+\NC splitmask \NC (str,nx,ny,bpp,bytes) \NC string \NC \NR
+\NC interlace \NC (str,nx,ny,slice,pass) \NC string \NC \NR
+\NC expand \NC (str,nx,ny,parts,xline,factor) \NC string \NC \NR
+\LL
+\stoptabulate
+
+\stopsection
+
+\startsection[title=\type{basexx}]
+
+Some more experimental helpers:
+
+\starttabulate[|Tw(12em)|T|T|]
+\DB name \BC arguments \BC results \NC \NR
+\TB
+\NC encode16 \NC (str[,newline]) \NC string \NC \NR
+\NC decode16 \NC (str) \NC string \NC \NR
+\NC encode64 \NC (str[,newline]) \NC string \NC \NR
+\NC decode64 \NC (str) \NC string \NC \NR
+\NC encode85 \NC (str[,newline]) \NC string \NC \NR
+\NC decode85 \NC (str) \NC string \NC \NR
+\NC encodeRL \NC (str) \NC string \NC \NR
+\NC decodeRL \NC (str) \NC string \NC \NR
+\NC encodeLZW \NC (str[,defaults]) \NC string \NC \NR
+\NC decodeLZW \NC (str[,defaults]) \NC string \NC \NR
+\LL
+\stoptabulate
+
+\stopsection
+
+\startsection[title={Multibyte \type {string} functions}]
+
+The \type {string} library has a few extra functions, for example \libidx
+{string} {explode}. This function takes upto two arguments: \type
+{string.explode(s[,m])} and returns an array containing the string argument \type
+{s} split into sub-strings based on the value of the string argument \type {m}.
+The second argument is a string that is either empty (this splits the string into
+characters), a single character (this splits on each occurrence of that
+character, possibly introducing empty strings), or a single character followed by
+the plus sign \type {+} (this special version does not create empty sub-strings).
+The default value for \type {m} is \quote {\type { +}} (multiple spaces). Note:
+\type {m} is not hidden by surrounding braces as it would be if this function was
+written in \TEX\ macros.
+
+The \type {string} library also has six extra iterators that return strings
+piecemeal: \libidx {string} {utfvalues}, \libidx {string} {utfcharacters},
+\libidx {string} {characters}, \libidx {string} {characterpairs}, \libidx
+{string} {bytes} and \libidx {string} {bytepairs}.
+
+\startitemize
+\startitem
+ \type {string.utfvalues(s)}: an integer value in the \UNICODE\ range
+\stopitem
+\startitem
+ \type {string.utfcharacters(s)}: a string with a single \UTF-8 token in it
+\stopitem
+\startitem
+ \type {string.cWharacters(s)}: a string containing one byte
+\stopitem
+\startitem
+ \type {string.characterpairs(s)}: two strings each containing one byte or an
+ empty second string if the string length was odd
+\stopitem
+\startitem
+ \type {string.bytes(s)}: a single byte value
+\stopitem
+\startitem
+ \type {string.bytepairs(s)}: two byte values or nil instead of a number as
+ its second return value if the string length was odd
+\stopitem
+\stopitemize
+
+The \type {string.characterpairs()} and \type {string.bytepairs()} iterators
+are useful especially in the conversion of \UTF16 encoded data into \UTF8.
+
+There is also a two|-|argument form of \type {string.dump()}. The second argument
+is a boolean which, if true, strips the symbols from the dumped data. This
+matches an extension made in \type {luajit}. This is typically a function that
+gets adapted as \LUA\ itself progresses.
+
+The \type {string} library functions \type {len}, \type {lower}, \type {sub}
+etc.\ are not \UNICODE|-|aware. For strings in the \UTF8 encoding, i.e., strings
+containing characters above code point 127, the corresponding functions from the
+\type {slnunicode} library can be used, e.g., \type {unicode.utf8.len}, \type
+{unicode.utf8.lower} etc.\ The exceptions are \type {unicode.utf8.find}, that
+always returns byte positions in a string, and \type {unicode.utf8.match} and
+\type {unicode.utf8.gmatch}. While the latter two functions in general {\it
+are} \UNICODE|-|aware, they fall|-|back to non|-|\UNICODE|-|aware behavior when
+using the empty capture \type {()} but other captures work as expected. For the
+interpretation of character classes in \type {unicode.utf8} functions refer to
+the library sources at \hyphenatedurl {http://luaforge.net/projects/sln}.
+
+Version 5.3 of \LUA\ provides some native \UTF8 support but we have added a few
+similar helpers too: \libidx {string} {utfvalue}, \libidx {string} {utfcharacter}
+and \libidx {string} {utflength}.
+
+\startitemize
+\startitem
+ \type {string.utfvalue(s)}: returns the codepoints of the characters in the
+ given string
+\stopitem
+\startitem
+ \type {string.utfcharacter(c,...)}: returns a string with the characters of
+ the given code points
+\stopitem
+\startitem
+ \type {string.utflength(s)}: returns the length of the given string
+\stopitem
+\stopitemize
+
+These three functions are relative fast and don't do much checking. They can be
+used as building blocks for other helpers.
+
+\stopsection
+
+\startsection[title={Extra \type {os} library functions}]
+
+The \type {os} library has a few extra functions and variables: \libidx {os}
+{selfdir}, \libidx {os} {selfarg}, \libidx {os} {setenv}, \libidx {os} {env}, \libidx {os}
+{gettimeofday}, \libidx {os} {type}, \libidx {os} {name} and \libidx {os}
+{uname}, that we will discuss here. There are also some time related helpers in
+the \type {lua} namespace.
+
+\startitemize
+
+% selfbin
+% selfpath
+% selfdir
+% selfbase
+% selfname
+% selfcore
+
+\startitem
+ \type {os.selfdir} is a variable that holds the directory path of the
+ actual executable. For example: \type {\directlua {tex.sprint(os.selfdir)}}.
+\stopitem
+
+\startitem
+ \type {os.selfarg} is a table with the command line arguments.
+\stopitem
+
+\startitem
+ \type {os.setenv(key,value)} sets a variable in the environment. Passing
+ \type {nil} instead of a value string will remove the variable.
+\stopitem
+
+\startitem
+ \type {os.env} is a hash table containing a dump of the variables and
+ values in the process environment at the start of the run. It is writeable,
+ but the actual environment is \notabene {not} updated automatically.
+\stopitem
+
+\startitem
+ \type {os.gettimeofday} returns the current \quote {\UNIX\ time}, but as a
+ float. Keep in mind that there might be platforms where this function is
+ available.
+\stopitem
+
+\startitem
+ \type {os.type} is a string that gives a global indication of the class of
+ operating system. The possible values are currently \type {windows}, \type
+ {unix}, and \type {msdos} (you are unlikely to find this value \quote {in the
+ wild}).
+\stopitem
+
+\startitem
+ \type {os.name} is a string that gives a more precise indication of the
+ operating system. These possible values are not yet fixed, and for \type
+ {os.type} values \type {windows} and \type {msdos}, the \type {os.name}
+ values are simply \type {windows} and \type {msdos}
+
+ The list for the type \type {unix} is more precise: \type {linux}, \type
+ {freebsd}, \type {kfreebsd}, \type {cygwin}, \type {openbsd}, \type
+ {solaris}, \type {sunos} (pre-solaris), \type {hpux}, \type {irix}, \type
+ {macosx}, \type {gnu} (hurd), \type {bsd} (unknown, but \BSD|-|like), \type
+ {sysv}, \type {generic} (unknown). But \unknown\ we only provide \LUAMETATEX\
+ binaries for the mainstream variants.
+
+ Officially we only support mainstream systems: \MSWINDOWS, \LINUX, \FREEBSD\
+ and \OSX. Of course one can build \LUAMETATEX\ for other systems, in which
+ case on has to check the above.
+\stopitem
+
+\startitem
+ \type {os.uname} returns a table with specific operating system
+ information acquired at runtime. The keys in the returned table are all
+ string values, and their names are: \type {sysname}, \type {machine}, \type
+ {release}, \type {version}, and \type {nodename}.
+\stopitem
+
+\stopitemize
+
+\stopsection
+
+\startsection[title={The \type {lua} library functions}]
+
+The \type {lua} library provide some general helpers.
+
+\startitemize
+
+\startitem
+ The \type {newtable} and \type {newindex} functions can be used to create
+ tables with space reserved beforehand for the given amount of entries.
+\stopitem
+
+\startitem
+ The \type {getstacktop} function returns a number that can be used for
+ diagnostic purposes.
+\stopitem
+
+\startitem
+ The functions \type {getruntime}, \type {getcurrenttime}, \type
+ {getpreciseticks} and \type {getpreciseseconds} return what their name
+ suggests.
+\stopitem
+
+\startitem
+ On \MSWINDOWS\ the \type {getcodepage} function returns two numbers, one
+ for the command handler and one for the graphical user interface.
+\stopitem
+
+\startitem
+ The name of the startup file is reported by \type {getstartupfile}.
+\stopitem
+
+\startitem
+ The \LUA\ version is reported by \type {getversion}.
+\stopitem
+
+\startitem
+ The \type {lua.openfile} function can be used instead of \type {io.open}. On
+ \MSWINDOWS\ it will convert the filename to a so called wide one which means
+ that filenames in \UTF8 encoding will work ok. On the other hand, names given
+ in the codepage won't.
+\stopitem
+
+\stopitemize
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-lua.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-lua.tex
new file mode 100644
index 00000000000..a126a95dcea
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-lua.tex
@@ -0,0 +1,224 @@
+% language=uk
+
+\environment luametatex-style
+
+\startcomponent luametatex-lua
+
+\startchapter[reference=lua,title={Using \LUAMETATEX}]
+
+\startsection[title={Initialization},reference=init]
+
+\startsubsection[title={\LUAMETATEX\ as a \LUA\ interpreter}]
+
+\topicindex {initialization}
+\topicindex {\LUA+interpreter}
+
+Although \LUAMETATEX\ is primarily meant as a \TEX\ engine, it can also serve as
+a stand alone \LUA\ interpreter. There are two ways to make \LUAMETATEX\ behave
+like a standalone \LUA\ interpreter:
+
+\startitemize[packed]
+\startitem
+ if a \type {--luaonly} option is given on the commandline, or
+\stopitem
+\startitem
+ if the only non|-|option argument (file) on the commandline has the extension
+ \type {lua} or \type {luc}.
+\stopitem
+\stopitemize
+
+In this mode, it will set \LUA's \type {arg[0]} to the found script name, pushing
+preceding options in negative values and the rest of the command line in the
+positive values, just like the \LUA\ interpreter does.
+
+\LUAMETATEX\ will exit immediately after executing the specified \LUA\ script and is,
+in effect, a somewhat bulky stand alone \LUA\ interpreter with a bunch of extra
+preloaded libraries.
+
+When no argument is given, \LUAMETATEX\ will look for a \LUA\ file with the same
+name as the binary and run that one when present. This makes it possible to use
+the engine as a stub. For instance, in \CONTEXT\ a symlink from \type {mtxrun} to
+type {luametatex} will run the \type {mtxrun.lua} script when present in the same
+path as the binary itself
+
+\stopsubsection
+
+\startsubsection[title={Other commandline processing}]
+
+\topicindex {command line}
+
+When the \LUAMETATEX\ executable starts, it looks for the \type {--lua} command line
+option. If there is no \type {--lua} option, the command line is interpreted in a
+similar fashion as the other \TEX\ engines. All options are accepted but only some
+are understood by \LUAMETATEX\ itself:
+
+\starttabulate[|l|p|]
+\DB commandline argument \BC explanation \NC \NR
+\TB
+\NC \type{--credits} \NC display credits and exit \NC \NR
+\NC \type{--fmt=FORMAT} \NC load the format file \type {FORMAT} \NC\NR
+\NC \type{--help} \NC display help and exit \NC\NR
+\NC \type{--ini} \NC be \type {iniluatex}, for dumping formats \NC\NR
+\NC \type{--jobname=STRING} \NC set the job name to \type {STRING} \NC \NR
+\NC \type{--lua=FILE} \NC load and execute a \LUA\ initialization script \NC\NR
+\NC \type{--version} \NC display version and exit \NC \NR
+\LL
+\stoptabulate
+
+There are less options than with \LUATEX, because one has to deal with them in
+\LUA\ anyway. There are no options to enter a safer mode or control executing
+programs. This can easily be achieved with a startup \LUA\ script.
+
+The value to use for \prm {jobname} is decided as follows:
+
+\startitemize
+\startitem
+ If \type {--jobname} is given on the command line, its argument will be the
+ value for \prm {jobname}, without any changes. The argument will not be
+ used for actual input so it need not exist. The \type {--jobname} switch only
+ controls the \prm {jobname} setting.
+\stopitem
+\startitem
+ Otherwise, \prm {jobname} will be the name of the first file that is read
+ from the file system, with any path components and the last extension (the
+ part following the last \type {.}) stripped off.
+\stopitem
+\startitem
+ There is an exception to the previous point: if the command line goes into
+ interactive mode (by starting with a command) and there are no files input
+ via \prm {everyjob} either, then the \prm {jobname} is set to \type
+ {texput} as a last resort.
+\stopitem
+\stopitemize
+
+Next the initialization script is loaded and executed. From within the script,
+the entire command line is available in the \LUA\ table \type {arg}, beginning
+with \type {arg[0]}, containing the name of the executable. As consequence
+warnings about unrecognized options are suppressed.
+
+Command line processing happens very early on. So early, in fact, that none of
+\TEX's initializations have taken place yet. The \LUA\ libraries that don't deal
+with \TEX\ are initialized early.
+
+\LUAMETATEX\ allows some of the command line options to be overridden by reading
+values from the \type {texconfig} table at the end of script execution (see the
+description of the \type {texconfig} table later on in this document for more
+details on which ones exactly).
+
+So let's summarize this. The handling of when is called jobname is a bit complex.
+There can be explicit names set on the command line but when not set they can be
+taken from the \type {texconfig} table.
+
+\starttabulate[|l|T|T|T|]
+\NC startup filename \NC --lua \NC a \LUA\ file \NC \NC \NR
+\NC startup jobname \NC --jobname \NC a \TEX\ tex \NC texconfig.jobname \NC \NR
+\NC startup dumpname \NC --fmt \NC a format file \NC texconfig.formatname \NC \NR
+\stoptabulate
+
+These names are initialized according to \type {--luaonly} or the first filename
+seen in the list of options. Special treatment of \type {&} and \type {*} as well
+as interactive startup is gone.
+
+When we are in \TEX\ mode at some point the engine needs a filename, for instance
+for opening a log file. At that moment the set jobname becomes the internal one
+and when it has not been set which internalized to jobname but when not set
+becomes \type {texput}. When you see a \type {texput.log} file someplace on your
+system it normally indicates a bad run.
+
+When running on \MSWINDOWS\ the command line, filenames, environment variable
+access etc.\ internally uses the current code page but to the user is exposed as
+\UTF8. Normally users won't notice this.
+
+% fileio_state .jobname : a tex string (set when a (log) file is opened)
+% engine_state .startup_jobname : handles by option parser
+% environment_state.input_name : temporary interceptor
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title={\LUA\ behaviour}]
+
+\startsubsection[title={The \LUA\ version}]
+
+\topicindex {\LUA+libraries}
+\topicindex {\LUA+extensions}
+
+We currently use \LUA\ 5.4 and will follow developments of the language but
+normally with some delay. Therefore the user needs to keep an eye on (subtle)
+differences in successive versions of the language. Here is an example of one
+aspect.
+
+\LUA s \type {tostring} function (and \type {string.format}) may return values in
+scientific notation, thereby confusing the \TEX\ end of things when it is used as
+the right|-|hand side of an assignment to a \prm {dimen} or \prm {count}. The
+output of these serializers also depend on the \LUA\ version, so in \LUA\ 5.3 you
+can get different output than from 5.2. It is best not to depend the automatic
+cast from string to number and vise versa as this can change in future versions.
+
+\stopsubsection
+
+\startsubsection[title={Locales}]
+
+\index {locales}
+
+In stock \LUA, many things depend on the current locale. In \LUAMETATEX, we can't
+do that, because it makes documents unportable. While \LUAMETATEX\ is running if
+forces the following locale settings:
+
+\starttyping
+LC_CTYPE=C
+LC_COLLATE=C
+LC_NUMERIC=C
+\stoptyping
+
+There is no way to change that as it would interfere badly with the often
+language specific conversions needed at the \TEX\ end.
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title={\LUA\ modules}]
+
+\topicindex {\LUA+libraries}
+\topicindex {\LUA+modules}
+
+Of course the regular \LUA\ modules are present. In addition we provide the \type
+{lpeg} library by Roberto Ierusalimschy, This library is not \UNICODE|-|aware,
+but interprets strings on a byte|-|per|-|byte basis. This mainly means that \type
+{lpeg.S} cannot be used with \UTF8 characters that need more than one byte, and
+thus \type {lpeg.S} will look for one of those two bytes when matching, not the
+combination of the two. The same is true for \type {lpeg.R}, although the latter
+will display an error message if used with multibyte characters. Therefore \type
+{lpeg.R('aä')} results in the message \type {bad argument #1 to 'R' (range must
+have two characters)}, since to \type {lpeg}, \type {ä} is two 'characters'
+(bytes), so \type {aä} totals three. In practice this is no real issue and with
+some care you can deal with \UNICODE\ just fine.
+
+There are some more libraries present. These are discussed on a later chapter.
+For instance we embed \type {luasocket} but contrary to \LUATEX\ don't embed the
+related \LUA\ code. An adapted version of \type {luafilesystem} is also included.
+There is a more extensive math library and there are libraries that deal with
+encryption and compression.
+
+\stopsection
+
+\startsection[title={Testing}]
+
+\topicindex {testing}
+
+For development reasons you can influence the used startup date and time. By
+setting the \type {start_time} variable in the \type {texconfig} table; as with
+other variables we use the internal name there. When Universal Time is needed,
+set the entry \type {use_utc_time} in the \type {texconfig} table.
+
+In \CONTEXT\ we provide the command line argument \type {--nodates} that does
+a bit more than disabling dates; it avoids time dependent information in the
+output file for instance.
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-math.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-math.tex
new file mode 100644
index 00000000000..ce4fe154482
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-math.tex
@@ -0,0 +1,1587 @@
+% language=uk
+
+\environment luametatex-style
+
+\startcomponent luametatex-math
+
+\startchapter[reference=math,title={Math}]
+
+\startsection[title={Traditional alongside \OPENTYPE}]
+
+\topicindex {math}
+
+At this point there is no difference between \LUAMETATEX\ and \LUATEX\ with
+respect to math. The handling of mathematics in \LUATEX\ differs quite a bit from
+how \TEX82 (and therefore \PDFTEX) handles math. First, \LUATEX\ adds primitives
+and extends some others so that \UNICODE\ input can be used easily. Second, all
+of \TEX82's internal special values (for example for operator spacing) have been
+made accessible and changeable via control sequences. Third, there are extensions
+that make it easier to use \OPENTYPE\ math fonts. And finally, there are some
+extensions that have been proposed or considered in the past that are now added
+to the engine.
+
+\stopsection
+
+\startsection[title={Unicode math characters}]
+
+\topicindex {math+\UNICODE}
+\topicindex {\UNICODE+math}
+
+Character handling is now extended up to the full \UNICODE\ range (the \type {\U}
+prefix), which is compatible with \XETEX.
+
+The math primitives from \TEX\ are kept as they are, except for the ones that
+convert from input to math commands: \type {mathcode}, and \type {delcode}. These
+two now allow for a 21-bit character argument on the left hand side of the equals
+sign.
+
+Some of the new \LUATEX\ primitives read more than one separate value. This is
+shown in the tables below by a plus sign.
+
+The input for such primitives would look like this:
+
+\starttyping
+\def\overbrace{\Umathaccent 0 1 "23DE }
+\stoptyping
+
+The altered \TEX82 primitives are:
+
+\starttabulate[|l|l|r|c|l|r|]
+\DB primitive \BC min \BC max \BC \kern 2em \BC min \BC max \NC \NR
+\TB
+\NC \prm {mathcode} \NC 0 \NC 10FFFF \NC = \NC 0 \NC 8000 \NC \NR
+\NC \prm {delcode} \NC 0 \NC 10FFFF \NC = \NC 0 \NC FFFFFF \NC \NR
+\LL
+\stoptabulate
+
+The unaltered ones are:
+
+\starttabulate[|l|l|r|]
+\DB primitive \BC min \BC max \NC \NR
+\TB
+\NC \prm {mathchardef} \NC 0 \NC 8000 \NC \NR
+\NC \prm {mathchar} \NC 0 \NC 7FFF \NC \NR
+\NC \prm {mathaccent} \NC 0 \NC 7FFF \NC \NR
+\NC \prm {delimiter} \NC 0 \NC 7FFFFFF \NC \NR
+\NC \prm {radical} \NC 0 \NC 7FFFFFF \NC \NR
+\LL
+\stoptabulate
+
+For practical reasons \prm {mathchardef} will silently accept values larger
+that \type {0x8000} and interpret it as \lpr {Umathcharnumdef}. This is needed
+to satisfy older macro packages.
+
+The following new primitives are compatible with \XETEX:
+
+% somewhat fuzzy:
+
+\starttabulate[|l|l|r|c|l|r|]
+\DB primitive \BC min \BC max \BC \kern 2em \BC min \BC max \NC \NR
+\TB
+\NC \lpr {Umathchardef} \NC 0+0+0 \NC 7+FF+10FFFF \NC \NC \NC \NC \NR
+\NC \lpr {Umathcharnumdef}\rlap{\high{5}} \NC -80000000 \NC 7FFFFFFF \NC \NC \NC \NC \NR
+\NC \lpr {Umathcode} \NC 0 \NC 10FFFF \NC = \NC 0+0+0 \NC 7+FF+10FFFF \NC \NR
+\NC \lpr {Udelcode} \NC 0 \NC 10FFFF \NC = \NC 0+0 \NC FF+10FFFF \NC \NR
+\NC \lpr {Umathchar} \NC 0+0+0 \NC 7+FF+10FFFF \NC \NC \NC \NC \NR
+\NC \lpr {Umathaccent} \NC 0+0+0 \NC 7+FF+10FFFF \NC \NC \NC \NC \NR
+\NC \lpr {Udelimiter} \NC 0+0+0 \NC 7+FF+10FFFF \NC \NC \NC \NC \NR
+\NC \lpr {Uradical} \NC 0+0 \NC FF+10FFFF \NC \NC \NC \NC \NR
+\NC \lpr {Umathcharnum} \NC -80000000 \NC 7FFFFFFF \NC \NC \NC \NC \NR
+\NC \lpr {Umathcodenum} \NC 0 \NC 10FFFF \NC = \NC -80000000 \NC 7FFFFFFF \NC \NR
+\NC \lpr {Udelcodenum} \NC 0 \NC 10FFFF \NC = \NC -80000000 \NC 7FFFFFFF \NC \NR
+\LL
+\stoptabulate
+
+Specifications typically look like:
+
+\starttyping
+\Umathchardef\xx="1"0"456
+\Umathcode 123="1"0"789
+\stoptyping
+
+The new primitives that deal with delimiter|-|style objects do not set up a
+\quote {large family}. Selecting a suitable size for display purposes is expected
+to be dealt with by the font via the \lpr {Umathoperatorsize} parameter.
+
+For some of these primitives, all information is packed into a single signed
+integer. For the first two (\lpr {Umathcharnum} and \lpr {Umathcodenum}), the
+lowest 21 bits are the character code, the 3 bits above that represent the math
+class, and the family data is kept in the topmost bits. This means that the values
+for math families 128--255 are actually negative. For \lpr {Udelcodenum} there
+is no math class. The math family information is stored in the bits directly on
+top of the character code. Using these three commands is not as natural as using
+the two- and three|-|value commands, so unless you know exactly what you are
+doing and absolutely require the speedup resulting from the faster input
+scanning, it is better to use the verbose commands instead.
+
+The \lpr {Umathaccent} command accepts optional keywords to control various
+details regarding math accents. See \in {section} [mathacc] below for details.
+
+There are more new primitives and all of these will be explained in following
+sections:
+
+\starttabulate[|l|l|]
+\DB primitive \BC value range (in hex) \NC \NR
+\TB
+\NC \lpr {Uroot} \NC 0 + 0--FF + 10FFFF \NC \NR
+\NC \lpr {Uoverdelimiter} \NC 0 + 0--FF + 10FFFF \NC \NR
+\NC \lpr {Uunderdelimiter} \NC 0 + 0--FF + 10FFFF \NC \NR
+\NC \lpr {Udelimiterover} \NC 0 + 0--FF + 10FFFF \NC \NR
+\NC \lpr {Udelimiterunder} \NC 0 + 0--FF + 10FFFF \NC \NR
+\LL
+\stoptabulate
+
+\stopsection
+
+\startsection[title={Math styles}]
+
+\subsection{\lpr {mathstyle}}
+
+\topicindex {math+styles}
+
+It is possible to discover the math style that will be used for a formula in an
+expandable fashion (while the math list is still being read). To make this
+possible, \LUATEX\ adds the new primitive: \lpr {mathstyle}. This is a \quote
+{convert command} like e.g. \prm {romannumeral}: its value can only be read,
+not set.
+
+The returned value is between 0 and 7 (in math mode), or $-1$ (all other modes).
+For easy testing, the eight math style commands have been altered so that they can
+be used as numeric values, so you can write code like this:
+
+\starttyping
+\ifnum\mathstyle=\textstyle
+ \message{normal text style}
+\else \ifnum\mathstyle=\crampedtextstyle
+ \message{cramped text style}
+\fi \fi
+\stoptyping
+
+Sometimes you won't get what you expect so a bit of explanation might help to
+understand what happens. When math is parsed and expanded it gets turned into a
+linked list. In a second pass the formula will be build. This has to do with the
+fact that in order to determine the automatically chosen sizes (in for instance
+fractions) following content can influence preceding sizes. A side effect of this
+is for instance that one cannot change the definition of a font family (and
+thereby reusing numbers) because the number that got used is stored and used in
+the second pass (so changing \type {\fam 12} mid|-|formula spoils over to
+preceding use of that family).
+
+The style switching primitives like \prm {textstyle} are turned into nodes so the
+styles set there are frozen. The \prm {mathchoice} primitive results in four
+lists being constructed of which one is used in the second pass. The fact that
+some automatic styles are not yet known also means that the \lpr {mathstyle}
+primitive expands to the current style which can of course be different from the
+one really used. It's a snapshot of the first pass state. As a consequence in the
+following example you get a style number (first pass) typeset that can actually
+differ from the used style (second pass). In the case of a math choice used
+ungrouped, the chosen style is used after the choice too, unless you group.
+
+\startbuffer[1]
+ [a:\mathstyle]\quad
+ \bgroup
+ \mathchoice
+ {\bf \scriptstyle (x:d :\mathstyle)}
+ {\bf \scriptscriptstyle (x:t :\mathstyle)}
+ {\bf \scriptscriptstyle (x:s :\mathstyle)}
+ {\bf \scriptscriptstyle (x:ss:\mathstyle)}
+ \egroup
+ \quad[b:\mathstyle]\quad
+ \mathchoice
+ {\bf \scriptstyle (y:d :\mathstyle)}
+ {\bf \scriptscriptstyle (y:t :\mathstyle)}
+ {\bf \scriptscriptstyle (y:s :\mathstyle)}
+ {\bf \scriptscriptstyle (y:ss:\mathstyle)}
+ \quad[c:\mathstyle]\quad
+ \bgroup
+ \mathchoice
+ {\bf \scriptstyle (z:d :\mathstyle)}
+ {\bf \scriptscriptstyle (z:t :\mathstyle)}
+ {\bf \scriptscriptstyle (z:s :\mathstyle)}
+ {\bf \scriptscriptstyle (z:ss:\mathstyle)}
+ \egroup
+ \quad[d:\mathstyle]
+\stopbuffer
+
+\startbuffer[2]
+ [a:\mathstyle]\quad
+ \begingroup
+ \mathchoice
+ {\bf \scriptstyle (x:d :\mathstyle)}
+ {\bf \scriptscriptstyle (x:t :\mathstyle)}
+ {\bf \scriptscriptstyle (x:s :\mathstyle)}
+ {\bf \scriptscriptstyle (x:ss:\mathstyle)}
+ \endgroup
+ \quad[b:\mathstyle]\quad
+ \mathchoice
+ {\bf \scriptstyle (y:d :\mathstyle)}
+ {\bf \scriptscriptstyle (y:t :\mathstyle)}
+ {\bf \scriptscriptstyle (y:s :\mathstyle)}
+ {\bf \scriptscriptstyle (y:ss:\mathstyle)}
+ \quad[c:\mathstyle]\quad
+ \begingroup
+ \mathchoice
+ {\bf \scriptstyle (z:d :\mathstyle)}
+ {\bf \scriptscriptstyle (z:t :\mathstyle)}
+ {\bf \scriptscriptstyle (z:s :\mathstyle)}
+ {\bf \scriptscriptstyle (z:ss:\mathstyle)}
+ \endgroup
+ \quad[d:\mathstyle]
+\stopbuffer
+
+\typebuffer[1]
+
+% \typebuffer[2]
+
+This gives:
+
+\blank $\displaystyle \getbuffer[1]$ \blank
+\blank $\textstyle \getbuffer[1]$ \blank
+
+Using \prm {begingroup} \unknown\ \prm {endgroup} instead gives:
+
+\blank $\displaystyle \getbuffer[2]$ \blank
+\blank $\textstyle \getbuffer[2]$ \blank
+
+This might look wrong but it's just a side effect of \lpr {mathstyle} expanding
+to the current (first pass) style and the number being injected in the list that
+gets converted in the second pass. It all makes sense and it illustrates the
+importance of grouping. In fact, the math choice style being effective afterwards
+has advantages. It would be hard to get it otherwise.
+
+\subsection{\lpr {Ustack}}
+
+\topicindex {math+stacks}
+
+There are a few math commands in \TEX\ where the style that will be used is not
+known straight from the start. These commands (\prm {over}, \prm {atop},
+\prm {overwithdelims}, \prm {atopwithdelims}) would therefore normally return
+wrong values for \lpr {mathstyle}. To fix this, \LUATEX\ introduces a special
+prefix command: \lpr {Ustack}:
+
+\starttyping
+$\Ustack {a \over b}$
+\stoptyping
+
+The \lpr {Ustack} command will scan the next brace and start a new math group
+with the correct (numerator) math style.
+
+\subsection{The new \type {\cramped...style} commands}
+
+\topicindex {math+styles}
+\topicindex {math+spacing}
+\topicindex {math+cramped}
+
+\LUATEX\ has four new primitives to set the cramped math styles directly:
+
+\starttyping
+\crampeddisplaystyle
+\crampedtextstyle
+\crampedscriptstyle
+\crampedscriptscriptstyle
+\stoptyping
+
+These additional commands are not all that valuable on their own, but they come
+in handy as arguments to the math parameter settings that will be added shortly.
+
+In Eijkhouts \quotation {\TEX\ by Topic} the rules for handling styles in scripts
+are described as follows:
+
+\startitemize
+\startitem
+ In any style superscripts and subscripts are taken from the next smaller style.
+ Exception: in display style they are in script style.
+\stopitem
+\startitem
+ Subscripts are always in the cramped variant of the style; superscripts are only
+ cramped if the original style was cramped.
+\stopitem
+\startitem
+ In an \type {..\over..} formula in any style the numerator and denominator are
+ taken from the next smaller style.
+\stopitem
+\startitem
+ The denominator is always in cramped style; the numerator is only in cramped
+ style if the original style was cramped.
+\stopitem
+\startitem
+ Formulas under a \type {\sqrt} or \prm {overline} are in cramped style.
+\stopitem
+\stopitemize
+
+In \LUATEX\ one can set the styles in more detail which means that you sometimes
+have to set both normal and cramped styles to get the effect you want. (Even) if
+we force styles in the script using \prm {scriptstyle} and \lpr
+{crampedscriptstyle} we get this:
+
+\startbuffer[demo]
+\starttabulate
+\DB style \BC example \NC \NR
+\TB
+\NC default \NC $b_{x=xx}^{x=xx}$ \NC \NR
+\NC script \NC $b_{\scriptstyle x=xx}^{\scriptstyle x=xx}$ \NC \NR
+\NC crampedscript \NC $b_{\crampedscriptstyle x=xx}^{\crampedscriptstyle x=xx}$ \NC \NR
+\LL
+\stoptabulate
+\stopbuffer
+
+\getbuffer[demo]
+
+Now we set the following parameters
+
+\startbuffer[setup]
+\Umathordrelspacing\scriptstyle=30mu
+\Umathordordspacing\scriptstyle=30mu
+\stopbuffer
+
+\typebuffer[setup]
+
+This gives a different result:
+
+\start\getbuffer[setup,demo]\stop
+
+But, as this is not what is expected (visually) we should say:
+
+\startbuffer[setup]
+\Umathordrelspacing\scriptstyle=30mu
+\Umathordordspacing\scriptstyle=30mu
+\Umathordrelspacing\crampedscriptstyle=30mu
+\Umathordordspacing\crampedscriptstyle=30mu
+\stopbuffer
+
+\typebuffer[setup]
+
+Now we get:
+
+\start\getbuffer[setup,demo]\stop
+
+\stopsection
+
+\startsection[title={Math parameter settings}]
+
+\subsection {Many new \lpr {Umath*} primitives}
+
+\topicindex {math+parameters}
+
+In \LUATEX, the font dimension parameters that \TEX\ used in math typesetting are
+now accessible via primitive commands. In fact, refactoring of the math engine
+has resulted in many more parameters than were not accessible before.
+
+\starttabulate
+\DB primitive name \BC description \NC \NR
+\TB
+\NC \lpr {Umathquad} \NC the width of 18 mu's \NC \NR
+\NC \lpr {Umathaxis} \NC height of the vertical center axis of
+ the math formula above the baseline \NC \NR
+\NC \lpr {Umathoperatorsize} \NC minimum size of large operators in display mode \NC \NR
+\NC \lpr {Umathoverbarkern} \NC vertical clearance above the rule \NC \NR
+\NC \lpr {Umathoverbarrule} \NC the width of the rule \NC \NR
+\NC \lpr {Umathoverbarvgap} \NC vertical clearance below the rule \NC \NR
+\NC \lpr {Umathunderbarkern} \NC vertical clearance below the rule \NC \NR
+\NC \lpr {Umathunderbarrule} \NC the width of the rule \NC \NR
+\NC \lpr {Umathunderbarvgap} \NC vertical clearance above the rule \NC \NR
+\NC \lpr {Umathradicalkern} \NC vertical clearance above the rule \NC \NR
+\NC \lpr {Umathradicalrule} \NC the width of the rule \NC \NR
+\NC \lpr {Umathradicalvgap} \NC vertical clearance below the rule \NC \NR
+\NC \lpr {Umathradicaldegreebefore}\NC the forward kern that takes place before placement of
+ the radical degree \NC \NR
+\NC \lpr {Umathradicaldegreeafter} \NC the backward kern that takes place after placement of
+ the radical degree \NC \NR
+\NC \lpr {Umathradicaldegreeraise} \NC this is the percentage of the total height and depth of
+ the radical sign that the degree is raised by; it is
+ expressed in \type {percents}, so 60\% is expressed as the
+ integer $60$ \NC \NR
+\NC \lpr {Umathstackvgap} \NC vertical clearance between the two
+ elements in a \prm {atop} stack \NC \NR
+\NC \lpr {Umathstacknumup} \NC numerator shift upward in \prm {atop} stack \NC \NR
+\NC \lpr {Umathstackdenomdown} \NC denominator shift downward in \prm {atop} stack \NC \NR
+\NC \lpr {Umathfractionrule} \NC the width of the rule in a \prm {over} \NC \NR
+\NC \lpr {Umathfractionnumvgap} \NC vertical clearance between the numerator and the rule \NC \NR
+\NC \lpr {Umathfractionnumup} \NC numerator shift upward in \prm {over} \NC \NR
+\NC \lpr {Umathfractiondenomvgap} \NC vertical clearance between the denominator and the rule \NC \NR
+\NC \lpr {Umathfractiondenomdown} \NC denominator shift downward in \prm {over} \NC \NR
+\NC \lpr {Umathfractiondelsize} \NC minimum delimiter size for \type {\...withdelims} \NC \NR
+\NC \lpr {Umathlimitabovevgap} \NC vertical clearance for limits above operators \NC \NR
+\NC \lpr {Umathlimitabovebgap} \NC vertical baseline clearance for limits above operators \NC \NR
+\NC \lpr {Umathlimitabovekern} \NC space reserved at the top of the limit \NC \NR
+\NC \lpr {Umathlimitbelowvgap} \NC vertical clearance for limits below operators \NC \NR
+\NC \lpr {Umathlimitbelowbgap} \NC vertical baseline clearance for limits below operators \NC \NR
+\NC \lpr {Umathlimitbelowkern} \NC space reserved at the bottom of the limit \NC \NR
+\NC \lpr {Umathoverdelimitervgap} \NC vertical clearance for limits above delimiters \NC \NR
+\NC \lpr {Umathoverdelimiterbgap} \NC vertical baseline clearance for limits above delimiters \NC \NR
+\NC \lpr {Umathunderdelimitervgap} \NC vertical clearance for limits below delimiters \NC \NR
+\NC \lpr {Umathunderdelimiterbgap} \NC vertical baseline clearance for limits below delimiters \NC \NR
+\NC \lpr {Umathsubshiftdrop} \NC subscript drop for boxes and subformulas \NC \NR
+\NC \lpr {Umathsubshiftdown} \NC subscript drop for characters \NC \NR
+\NC \lpr {Umathsupshiftdrop} \NC superscript drop (raise, actually) for boxes and subformulas \NC \NR
+\NC \lpr {Umathsupshiftup} \NC superscript raise for characters \NC \NR
+\NC \lpr {Umathsubsupshiftdown} \NC subscript drop in the presence of a superscript \NC \NR
+\NC \lpr {Umathsubtopmax} \NC the top of standalone subscripts cannot be higher than this
+ above the baseline \NC \NR
+\NC \lpr {Umathsupbottommin} \NC the bottom of standalone superscripts cannot be less than
+ this above the baseline \NC \NR
+\NC \lpr {Umathsupsubbottommax} \NC the bottom of the superscript of a combined super- and subscript
+ be at least as high as this above the baseline \NC \NR
+\NC \lpr {Umathsubsupvgap} \NC vertical clearance between super- and subscript \NC \NR
+\NC \lpr {Umathspaceafterscript} \NC additional space added after a super- or subscript \NC \NR
+\NC \lpr {Umathconnectoroverlapmin}\NC minimum overlap between parts in an extensible recipe \NC \NR
+\LL
+\stoptabulate
+
+Each of the parameters in this section can be set by a command like this:
+
+\starttyping
+\Umathquad\displaystyle=1em
+\stoptyping
+
+they obey grouping, and you can use \type {\the\Umathquad\displaystyle} if
+needed.
+
+\subsection{Font|-|based math parameters}
+
+\topicindex {math+parameters}
+
+While it is nice to have these math parameters available for tweaking, it would
+be tedious to have to set each of them by hand. For this reason, \LUATEX\
+initializes a bunch of these parameters whenever you assign a font identifier to
+a math family based on either the traditional math font dimensions in the font
+(for assignments to math family~2 and~3 using \TFM|-|based fonts like \type
+{cmsy} and \type {cmex}), or based on the named values in a potential \type
+{MathConstants} table when the font is loaded via Lua. If there is a \type
+{MathConstants} table, this takes precedence over font dimensions, and in that
+case no attention is paid to which family is being assigned to: the \type
+{MathConstants} tables in the last assigned family sets all parameters.
+
+In the table below, the one|-|letter style abbreviations and symbolic tfm font
+dimension names match those used in the \TeX book. Assignments to \prm
+{textfont} set the values for the cramped and uncramped display and text styles,
+\prm {scriptfont} sets the script styles, and \prm {scriptscriptfont} sets the
+scriptscript styles, so we have eight parameters for three font sizes. In the
+\TFM\ case, assignments only happen in family~2 and family~3 (and of course only
+for the parameters for which there are font dimensions).
+
+Besides the parameters below, \LUATEX\ also looks at the \quote {space} font
+dimension parameter. For math fonts, this should be set to zero.
+
+\def\MathLine#1#2#3#4#5%
+ {\TB
+ \NC \llap{\high{\tx #2\enspace}}\ttbf \string #1 \NC \tt #5 \NC \NR
+ \NC \tx #3 \NC \tt #4 \NC \NR}
+
+\starttabulate[|l|l|]
+\DB variable / style \BC tfm / opentype \NC \NR
+\MathLine{\Umathaxis} {} {} {AxisHeight} {axis_height}
+\MathLine{\Umathoperatorsize} {6} {D, D'} {DisplayOperatorMinHeight} {\emdash}
+\MathLine{\Umathfractiondelsize} {9} {D, D'} {FractionDelimiterDisplayStyleSize} {delim1}
+\MathLine{\Umathfractiondelsize} {9} {T, T', S, S', SS, SS'}{FractionDelimiterSize} {delim2}
+\MathLine{\Umathfractiondenomdown} {} {D, D'} {FractionDenominatorDisplayStyleShiftDown}{denom1}
+\MathLine{\Umathfractiondenomdown} {} {T, T', S, S', SS, SS'}{FractionDenominatorShiftDown} {denom2}
+\MathLine{\Umathfractiondenomvgap} {} {D, D'} {FractionDenominatorDisplayStyleGapMin} {3*default_rule_thickness}
+\MathLine{\Umathfractiondenomvgap} {} {T, T', S, S', SS, SS'}{FractionDenominatorGapMin} {default_rule_thickness}
+\MathLine{\Umathfractionnumup} {} {D, D'} {FractionNumeratorDisplayStyleShiftUp} {num1}
+\MathLine{\Umathfractionnumup} {} {T, T', S, S', SS, SS'}{FractionNumeratorShiftUp} {num2}
+\MathLine{\Umathfractionnumvgap} {} {D, D'} {FractionNumeratorDisplayStyleGapMin} {3*default_rule_thickness}
+\MathLine{\Umathfractionnumvgap} {} {T, T', S, S', SS, SS'}{FractionNumeratorGapMin} {default_rule_thickness}
+\MathLine{\Umathfractionrule} {} {} {FractionRuleThickness} {default_rule_thickness}
+\MathLine{\Umathskewedfractionhgap} {} {} {SkewedFractionHorizontalGap} {math_quad/2}
+\MathLine{\Umathskewedfractionvgap} {} {} {SkewedFractionVerticalGap} {math_x_height}
+\MathLine{\Umathlimitabovebgap} {} {} {UpperLimitBaselineRiseMin} {big_op_spacing3}
+\MathLine{\Umathlimitabovekern} {1} {} {0} {big_op_spacing5}
+\MathLine{\Umathlimitabovevgap} {} {} {UpperLimitGapMin} {big_op_spacing1}
+\MathLine{\Umathlimitbelowbgap} {} {} {LowerLimitBaselineDropMin} {big_op_spacing4}
+\MathLine{\Umathlimitbelowkern} {1} {} {0} {big_op_spacing5}
+\MathLine{\Umathlimitbelowvgap} {} {} {LowerLimitGapMin} {big_op_spacing2}
+\MathLine{\Umathoverdelimitervgap} {} {} {StretchStackGapBelowMin} {big_op_spacing1}
+\MathLine{\Umathoverdelimiterbgap} {} {} {StretchStackTopShiftUp} {big_op_spacing3}
+\MathLine{\Umathunderdelimitervgap} {} {} {StretchStackGapAboveMin} {big_op_spacing2}
+\MathLine{\Umathunderdelimiterbgap} {} {} {StretchStackBottomShiftDown} {big_op_spacing4}
+\MathLine{\Umathoverbarkern} {} {} {OverbarExtraAscender} {default_rule_thickness}
+\MathLine{\Umathoverbarrule} {} {} {OverbarRuleThickness} {default_rule_thickness}
+\MathLine{\Umathoverbarvgap} {} {} {OverbarVerticalGap} {3*default_rule_thickness}
+\MathLine{\Umathquad} {1} {} {<font_size(f)>} {math_quad}
+\MathLine{\Umathradicalkern} {} {} {RadicalExtraAscender} {default_rule_thickness}
+\MathLine{\Umathradicalrule} {2} {} {RadicalRuleThickness} {<not set>}
+\MathLine{\Umathradicalvgap} {3} {D, D'} {RadicalDisplayStyleVerticalGap} {default_rule_thickness+abs(math_x_height)/4}
+\MathLine{\Umathradicalvgap} {3} {T, T', S, S', SS, SS'}{RadicalVerticalGap} {default_rule_thickness+abs(default_rule_thickness)/4}
+\MathLine{\Umathradicaldegreebefore}{2} {} {RadicalKernBeforeDegree} {<not set>}
+\MathLine{\Umathradicaldegreeafter} {2} {} {RadicalKernAfterDegree} {<not set>}
+\MathLine{\Umathradicaldegreeraise} {2,7}{} {RadicalDegreeBottomRaisePercent} {<not set>}
+\MathLine{\Umathspaceafterscript} {4} {} {SpaceAfterScript} {script_space}
+\MathLine{\Umathstackdenomdown} {} {D, D'} {StackBottomDisplayStyleShiftDown} {denom1}
+\MathLine{\Umathstackdenomdown} {} {T, T', S, S', SS, SS'}{StackBottomShiftDown} {denom2}
+\MathLine{\Umathstacknumup} {} {D, D'} {StackTopDisplayStyleShiftUp} {num1}
+\MathLine{\Umathstacknumup} {} {T, T', S, S', SS, SS'}{StackTopShiftUp} {num3}
+\MathLine{\Umathstackvgap} {} {D, D'} {StackDisplayStyleGapMin} {7*default_rule_thickness}
+\MathLine{\Umathstackvgap} {} {T, T', S, S', SS, SS'}{StackGapMin} {3*default_rule_thickness}
+\MathLine{\Umathsubshiftdown} {} {} {SubscriptShiftDown} {sub1}
+\MathLine{\Umathsubshiftdrop} {} {} {SubscriptBaselineDropMin} {sub_drop}
+\MathLine{\Umathsubsupshiftdown} {8} {} {SubscriptShiftDownWithSuperscript} {\emdash}
+\MathLine{\Umathsubtopmax} {} {} {SubscriptTopMax} {abs(math_x_height*4)/5}
+\MathLine{\Umathsubsupvgap} {} {} {SubSuperscriptGapMin} {4*default_rule_thickness}
+\MathLine{\Umathsupbottommin} {} {} {SuperscriptBottomMin} {abs(math_x_height/4)}
+\MathLine{\Umathsupshiftdrop} {} {} {SuperscriptBaselineDropMax} {sup_drop}
+\MathLine{\Umathsupshiftup} {} {D} {SuperscriptShiftUp} {sup1}
+\MathLine{\Umathsupshiftup} {} {T, S, SS,} {SuperscriptShiftUp} {sup2}
+\MathLine{\Umathsupshiftup} {} {D', T', S', SS'} {SuperscriptShiftUpCramped} {sup3}
+\MathLine{\Umathsupsubbottommax} {} {} {SuperscriptBottomMaxWithSubscript} {abs(math_x_height*4)/5}
+\MathLine{\Umathunderbarkern} {} {} {UnderbarExtraDescender} {default_rule_thickness}
+\MathLine{\Umathunderbarrule} {} {} {UnderbarRuleThickness} {default_rule_thickness}
+\MathLine{\Umathunderbarvgap} {} {} {UnderbarVerticalGap} {3*default_rule_thickness}
+\MathLine{\Umathconnectoroverlapmin}{5} {} {MinConnectorOverlap} {0}
+\LL
+\stoptabulate
+
+Note 1: \OPENTYPE\ fonts set \lpr {Umathlimitabovekern} and \lpr
+{Umathlimitbelowkern} to zero and set \lpr {Umathquad} to the font size of the
+used font, because these are not supported in the \type {MATH} table,
+
+Note 2: Traditional \TFM\ fonts do not set \lpr {Umathradicalrule} because
+\TEX82\ uses the height of the radical instead. When this parameter is indeed not
+set when \LUATEX\ has to typeset a radical, a backward compatibility mode will
+kick in that assumes that an oldstyle \TEX\ font is used. Also, they do not set
+\lpr {Umathradicaldegreebefore}, \lpr {Umathradicaldegreeafter}, and \lpr
+{Umathradicaldegreeraise}. These are then automatically initialized to
+$5/18$quad, $-10/18$quad, and 60.
+
+Note 3: If \TFM\ fonts are used, then the \lpr {Umathradicalvgap} is not set
+until the first time \LUATEX\ has to typeset a formula because this needs
+parameters from both family~2 and family~3. This provides a partial backward
+compatibility with \TEX82, but that compatibility is only partial: once the \lpr
+{Umathradicalvgap} is set, it will not be recalculated any more.
+
+Note 4: When \TFM\ fonts are used a similar situation arises with respect to \lpr
+{Umathspaceafterscript}: it is not set until the first time \LUATEX\ has to
+typeset a formula. This provides some backward compatibility with \TEX82. But
+once the \lpr {Umathspaceafterscript} is set, \prm {scriptspace} will never be
+looked at again.
+
+Note 5: Traditional \TFM\ fonts set \lpr {Umathconnectoroverlapmin} to zero
+because \TEX82\ always stacks extensibles without any overlap.
+
+Note 6: The \lpr {Umathoperatorsize} is only used in \prm {displaystyle}, and is
+only set in \OPENTYPE\ fonts. In \TFM\ font mode, it is artificially set to one
+scaled point more than the initial attempt's size, so that always the \quote
+{first next} will be tried, just like in \TEX82.
+
+Note 7: The \lpr {Umathradicaldegreeraise} is a special case because it is the
+only parameter that is expressed in a percentage instead of a number of scaled
+points.
+
+Note 8: \type {SubscriptShiftDownWithSuperscript} does not actually exist in the
+\quote {standard} \OPENTYPE\ math font Cambria, but it is useful enough to be
+added.
+
+Note 9: \type {FractionDelimiterDisplayStyleSize} and \type
+{FractionDelimiterSize} do not actually exist in the \quote {standard} \OPENTYPE\
+math font Cambria, but were useful enough to be added.
+
+\stopsection
+
+\startsection[title={Math spacing}]
+
+\subsection{Setting inline surrounding space with \lpr {mathsurround[skip]}}
+
+\topicindex {math+spacing}
+
+Inline math is surrounded by (optional) \prm {mathsurround} spacing but that is a fixed
+dimension. There is now an additional parameter \lpr {mathsurroundskip}. When set to a
+non|-|zero value (or zero with some stretch or shrink) this parameter will replace
+\prm {mathsurround}. By using an additional parameter instead of changing the nature
+of \prm {mathsurround}, we can remain compatible. In the meantime a bit more
+control has been added via \lpr {mathsurroundmode}. This directive can take 6 values
+with zero being the default behaviour.
+
+\start
+
+\def\MathHack#1{\mathsurroundmode#1\relax\inlinebuffer}
+
+\def\OneLiner#1#2%
+ {\NC \type{#1}
+ \NC \dontleavehmode\inframed[align=normal,offset=0pt,frame=off]{\hsize 100pt x$\MathHack{#1}x$x}
+ \NC \dontleavehmode\inframed[align=normal,offset=0pt,frame=off]{\hsize 100pt x $\MathHack{#1}x$ x}
+ \NC #2
+ \NC \NR}
+
+\startbuffer
+\mathsurround 10pt
+\mathsurroundskip20pt
+\stopbuffer
+
+\typebuffer
+
+\starttabulate[|c|c|c|pl|]
+\DB mode \BC x\$x\$x \BC x \$x\$ x \BC effect \NC \NR
+\TB
+\OneLiner{0}{obey \prm {mathsurround} when \lpr {mathsurroundskip} is 0pt}
+\OneLiner{1}{only add skip to the left}
+\OneLiner{2}{only add skip to the right}
+\OneLiner{3}{add skip to the left and right}
+\OneLiner{4}{ignore the skip setting, obey \prm {mathsurround}}
+\OneLiner{5}{disable all spacing around math}
+\OneLiner{6}{only apply \lpr {mathsurroundskip} when also spacing}
+\OneLiner{7}{only apply \lpr {mathsurroundskip} when no spacing}
+\LL
+\stoptabulate
+
+\stop
+
+Method six omits the surround glue when there is (x)spacing glue present while
+method seven does the opposite, the glue is only applied when there is (x)space
+glue present too. Anything more fancy, like checking the begining or end of a
+paragraph (or edges of a box) would not be robust anyway. If you want that you
+can write a callback that runs over a list and analyzes a paragraph. Actually, in
+that case you could also inject glue (or set the properties of a math node)
+explicitly. So, these modes are in practice mostly useful for special purposes
+and experiments (they originate in a tracker item). Keep in mind that this glue
+is part of the math node and not always treated as normal glue: it travels with
+the begin and end math nodes. Also, method 6 and 7 will zero the skip related
+fields in a node when applicable in the first occasion that checks them
+(linebreaking or packaging).
+
+\subsection{Pairwise spacing and \lpr {Umath...spacing} commands}
+
+\topicindex {math+spacing}
+
+Besides the parameters mentioned in the previous sections, there are also 64 new
+primitives to control the math spacing table (as explained in Chapter~18 of the
+\TEX book). The primitive names are a simple matter of combining two math atom
+types, but for completeness' sake, here is the whole list:
+
+\starttwocolumns
+\startlines
+\lpr {Umathordordspacing}
+\lpr {Umathordopspacing}
+\lpr {Umathordbinspacing}
+\lpr {Umathordrelspacing}
+\lpr {Umathordopenspacing}
+\lpr {Umathordclosespacing}
+\lpr {Umathordpunctspacing}
+\lpr {Umathordinnerspacing}
+\lpr {Umathopordspacing}
+\lpr {Umathopopspacing}
+\lpr {Umathopbinspacing}
+\lpr {Umathoprelspacing}
+\lpr {Umathopopenspacing}
+\lpr {Umathopclosespacing}
+\lpr {Umathoppunctspacing}
+\lpr {Umathopinnerspacing}
+\lpr {Umathbinordspacing}
+\lpr {Umathbinopspacing}
+\lpr {Umathbinbinspacing}
+\lpr {Umathbinrelspacing}
+\lpr {Umathbinopenspacing}
+\lpr {Umathbinclosespacing}
+\lpr {Umathbinpunctspacing}
+\lpr {Umathbininnerspacing}
+\lpr {Umathrelordspacing}
+\lpr {Umathrelopspacing}
+\lpr {Umathrelbinspacing}
+\lpr {Umathrelrelspacing}
+\lpr {Umathrelopenspacing}
+\lpr {Umathrelclosespacing}
+\lpr {Umathrelpunctspacing}
+\lpr {Umathrelinnerspacing}
+\lpr {Umathopenordspacing}
+\lpr {Umathopenopspacing}
+\lpr {Umathopenbinspacing}
+\lpr {Umathopenrelspacing}
+\lpr {Umathopenopenspacing}
+\lpr {Umathopenclosespacing}
+\lpr {Umathopenpunctspacing}
+\lpr {Umathopeninnerspacing}
+\lpr {Umathcloseordspacing}
+\lpr {Umathcloseopspacing}
+\lpr {Umathclosebinspacing}
+\lpr {Umathcloserelspacing}
+\lpr {Umathcloseopenspacing}
+\lpr {Umathcloseclosespacing}
+\lpr {Umathclosepunctspacing}
+\lpr {Umathcloseinnerspacing}
+\lpr {Umathpunctordspacing}
+\lpr {Umathpunctopspacing}
+\lpr {Umathpunctbinspacing}
+\lpr {Umathpunctrelspacing}
+\lpr {Umathpunctopenspacing}
+\lpr {Umathpunctclosespacing}
+\lpr {Umathpunctpunctspacing}
+\lpr {Umathpunctinnerspacing}
+\lpr {Umathinnerordspacing}
+\lpr {Umathinneropspacing}
+\lpr {Umathinnerbinspacing}
+\lpr {Umathinnerrelspacing}
+\lpr {Umathinneropenspacing}
+\lpr {Umathinnerclosespacing}
+\lpr {Umathinnerpunctspacing}
+\lpr {Umathinnerinnerspacing}
+\stoplines
+\stoptwocolumns
+
+These parameters are of type \prm {muskip}, so setting a parameter can be done
+like this:
+
+\starttyping
+\Umathopordspacing\displaystyle=4mu plus 2mu
+\stoptyping
+
+They are all initialized by \type {initex} to the values mentioned in the table
+in Chapter~18 of the \TEX book.
+
+Note 1: for ease of use as well as for backward compatibility, \prm {thinmuskip},
+\prm {medmuskip} and \prm {thickmuskip} are treated specially. In their case a
+pointer to the corresponding internal parameter is saved, not the actual \prm
+{muskip} value. This means that any later changes to one of these three
+parameters will be taken into account.
+
+Note 2: Careful readers will realise that there are also primitives for the items
+marked \type {*} in the \TEX book. These will not actually be used as those
+combinations of atoms cannot actually happen, but it seemed better not to break
+orthogonality. They are initialized to zero.
+
+\subsection{Local settings}
+
+Math is processed in two passes. The first pass is needed to intercept for
+instance \type {\over}, one of the few \TEX\ commands that actually has a
+preceding argument. There are often lots of curly braces used in math and these
+can result in a nested run of the math sub engine. However, you need to be aware
+of the fact that some properties are kind of global to a formula and the last
+setting (for instance a family switch) wins. This also means that a change (or
+again, the last one) in math parameters affects the whole formula. In
+\LUAMETATEX\ we have changed this model a bit. One can argue that this introduces
+an incompatibility but it's hard to imagine a reason for setting the parameters
+at the end of a formula run and assume that they also influence what goes in
+front.
+
+\startbuffer
+$
+ x \Usubscript {-}
+ \frozen\Umathsubshiftdown\textstyle 0pt x \Usubscript {0}
+ {\frozen\Umathsubshiftdown\textstyle 5pt x \Usubscript {5}}
+ x \Usubscript {0}
+ {\frozen\Umathsubshiftdown\textstyle 15pt x \Usubscript {15}}
+ x \Usubscript {0}
+ {\frozen\Umathsubshiftdown\textstyle 20pt x \Usubscript {20}}
+ x \Usubscript {0}
+ \frozen\Umathsubshiftdown\textstyle 10pt x \Usubscript {10}
+ x \Usubscript {0}
+$
+\stopbuffer
+
+\typebuffer
+
+The \type {\frozen} prefix does the magic: it injects information in the
+math list about the set parameter.
+
+In \LUATEX\ 1.10 the last setting, the \type {10pt} drop wins, but in
+\LUAMETATEX\ you will see each local setting taking effect. The implementation
+uses a new node type, parameters nodes, so you you might encounter these in an
+unprocessed math list. The result looks as follows:
+
+\blank \getbuffer \blank
+
+
+
+\subsection{Skips around display math and \lpr {mathdisplayskipmode}}
+
+\topicindex {math+spacing}
+
+The injection of \prm {abovedisplayskip} and \prm {belowdisplayskip} is not
+symmetrical. An above one is always inserted, also when zero, but the below is
+only inserted when larger than zero. Especially the latter makes it sometimes hard
+to fully control spacing. Therefore \LUATEX\ comes with a new directive: \lpr
+{mathdisplayskipmode}. The following values apply:
+
+\starttabulate[|c|l|]
+\DB value \BC meaning \NC \NR
+\TB
+\NC 0 \NC normal \TEX\ behaviour \NC \NR
+\NC 1 \NC always (same as 0) \NC \NR
+\NC 2 \NC only when not zero \NC \NR
+\NC 3 \NC never, not even when not zero \NC \NR
+\LL
+\stoptabulate
+
+\subsection {Nolimit correction with \lpr {mathnolimitsmode}}
+
+\topicindex {math+limits}
+
+There are two extra math parameters \lpr {Umathnolimitsupfactor} and \lpr
+{Umathnolimitsubfactor} that were added to provide some control over how limits
+are spaced (for example the position of super and subscripts after integral
+operators). They relate to an extra parameter \lpr {mathnolimitsmode}. The half
+corrections are what happens when scripts are placed above and below. The
+problem with italic corrections is that officially that correction italic is used
+for above|/|below placement while advanced kerns are used for placement at the
+right end. The question is: how often is this implemented, and if so, do the
+kerns assume correction too. Anyway, with this parameter one can control it.
+
+\starttabulate[|l|ck1|ck1|ck1|ck1|ck1|ck1|]
+ \NC
+ \NC \mathnolimitsmode0 $\displaystyle\int\nolimits^0_1$
+ \NC \mathnolimitsmode1 $\displaystyle\int\nolimits^0_1$
+ \NC \mathnolimitsmode2 $\displaystyle\int\nolimits^0_1$
+ \NC \mathnolimitsmode3 $\displaystyle\int\nolimits^0_1$
+ \NC \mathnolimitsmode4 $\displaystyle\int\nolimits^0_1$
+ \NC \mathnolimitsmode8000 $\displaystyle\int\nolimits^0_1$
+ \NC \NR
+ \TB
+ \BC mode
+ \NC \tttf 0
+ \NC \tttf 1
+ \NC \tttf 2
+ \NC \tttf 3
+ \NC \tttf 4
+ \NC \tttf 8000
+ \NC \NR
+ \BC superscript
+ \NC 0
+ \NC font
+ \NC 0
+ \NC 0
+ \NC +ic/2
+ \NC 0
+ \NC \NR
+ \BC subscript
+ \NC -ic
+ \NC font
+ \NC 0
+ \NC -ic/2
+ \NC -ic/2
+ \NC 8000ic/1000
+ \NC \NR
+\stoptabulate
+
+When the mode is set to one, the math parameters are used. This way a macro
+package writer can decide what looks best. Given the current state of fonts in
+\CONTEXT\ we currently use mode 1 with factor 0 for the superscript and 750 for
+the subscripts. Positive values are used for both parameters but the subscript
+shifts to the left. A \lpr {mathnolimitsmode} larger that 15 is considered to
+be a factor for the subscript correction. This feature can be handy when
+experimenting.
+
+\subsection {Controlling math italic mess with \lpr {mathitalicsmode}}
+
+\topicindex {math+italics}
+
+The \lpr {mathitalicsmode} parameter can be set to~1 to force italic correction
+before noads that represent some more complex structure (read: everything
+that is not an ord, bin, rel, open, close, punct or inner). We show a Cambria
+example.
+
+\starttexdefinition Whatever #1
+ \NC \type{\mathitalicsmode = #1}
+ \NC \mathitalicsmode#1\ruledhbox{$\left|T^1\right|$}
+ \NC \mathitalicsmode#1\ruledhbox{$\left|T\right|$}
+ \NC \mathitalicsmode#1\ruledhbox{$T+1$}
+ \NC \mathitalicsmode#1\ruledhbox{$T{1\over2}$}
+ \NC \mathitalicsmode#1\ruledhbox{$T\sqrt{1}$}
+ \NC \NR
+\stoptexdefinition
+
+\start
+ \switchtobodyfont[cambria]
+ \starttabulate[|c|c|c|c|c|c|]
+ \Whatever{0}%
+ \Whatever{1}%
+ \stoptabulate
+\stop
+
+This kind of parameters relate to the fact that italic correction in \OPENTYPE\
+math is bound to fuzzy rules. So, control is the solution.
+
+\subsection {Influencing script kerning with \lpr {mathscriptboxmode}}
+
+\topicindex {math+kerning}
+\topicindex {math+scripts}
+
+If you want to typeset text in math macro packages often provide something \type
+{\text} which obeys the script sizes. As the definition can be anything there is
+a good chance that the kerning doesn't come out well when used in a script. Given
+that the first glyph ends up in a \prm {hbox} we have some control over this.
+And, as a bonus we also added control over the normal sublist kerning. The \lpr
+{mathscriptboxmode} parameter defaults to~1.
+
+\starttabulate[|c|l|]
+\DB value \BC meaning \NC \NR
+\TB
+\NC \type {0} \NC forget about kerning \NC \NR
+\NC \type {1} \NC kern math sub lists with a valid glyph \NC \NR
+\NC \type {2} \NC also kern math sub boxes that have a valid glyph \NC \NR
+\NC \type {2} \NC only kern math sub boxes with a boundary node present\NC \NR
+\LL
+\stoptabulate
+
+Here we show some examples. Of course this doesn't solve all our problems, if
+only because some fonts have characters with bounding boxes that compensate for
+italics, while other fonts can lack kerns.
+
+\startbuffer[1]
+ $T_{\tf fluff}$
+\stopbuffer
+
+\startbuffer[2]
+ $T_{\text{fluff}}$
+\stopbuffer
+
+\startbuffer[3]
+ $T_{\text{\boundary1 fluff}}$
+\stopbuffer
+
+\unexpanded\def\Show#1#2#3%
+ {\doifelsenothing{#3}
+ {\small\tx\typeinlinebuffer[#1]}
+ {\doifelse{#3}{-}
+ {\small\bf\tt mode #2}
+ {\switchtobodyfont[#3]\showfontkerns\showglyphs\mathscriptboxmode#2\relax\inlinebuffer[#1]}}}
+
+\starttabulate[|lBT|c|c|c|c|c|]
+ \NC \NC \Show{1}{0}{} \NC\Show{1}{1}{} \NC \Show{2}{1}{} \NC \Show{2}{2}{} \NC \Show{3}{3}{} \NC \NR
+ \NC \NC \Show{1}{0}{-} \NC\Show{1}{1}{-} \NC \Show{2}{1}{-} \NC \Show{2}{2}{-} \NC \Show{3}{3}{-} \NC \NR
+ \NC modern \NC \Show{1}{0}{modern} \NC\Show{1}{1}{modern} \NC \Show{2}{1}{modern} \NC \Show{2}{2}{modern} \NC \Show{3}{3}{modern} \NC \NR
+ \NC lucidaot \NC \Show{1}{0}{lucidaot} \NC\Show{1}{1}{lucidaot} \NC \Show{2}{1}{lucidaot} \NC \Show{2}{2}{lucidaot} \NC \Show{3}{3}{lucidaot} \NC \NR
+ \NC pagella \NC \Show{1}{0}{pagella} \NC\Show{1}{1}{pagella} \NC \Show{2}{1}{pagella} \NC \Show{2}{2}{pagella} \NC \Show{3}{3}{pagella} \NC \NR
+ \NC cambria \NC \Show{1}{0}{cambria} \NC\Show{1}{1}{cambria} \NC \Show{2}{1}{cambria} \NC \Show{2}{2}{cambria} \NC \Show{3}{3}{cambria} \NC \NR
+ \NC dejavu \NC \Show{1}{0}{dejavu} \NC\Show{1}{1}{dejavu} \NC \Show{2}{1}{dejavu} \NC \Show{2}{2}{dejavu} \NC \Show{3}{3}{dejavu} \NC \NR
+\stoptabulate
+
+Kerning between a character subscript is controlled by \lpr {mathscriptcharmode}
+which also defaults to~1.
+
+Here is another example. Internally we tag kerns as italic kerns or font kerns
+where font kerns result from the staircase kern tables. In 2018 fonts like Latin
+Modern and Pagella rely on cheats with the boundingbox, Cambria uses staircase
+kerns and Lucida a mixture. Depending on how fonts evolve we might add some more
+control over what one can turn on and off.
+
+\def\MathSample#1#2#3%
+ {\NC
+ #1 \NC
+ #2 \NC
+ \showglyphdata \switchtobodyfont[#2,17.3pt]$#3T_{f}$ \NC
+ \showglyphdata \switchtobodyfont[#2,17.3pt]$#3\gamma_{e}$ \NC
+ \showglyphdata \switchtobodyfont[#2,17.3pt]$#3\gamma_{ee}$ \NC
+ \showglyphdata \switchtobodyfont[#2,17.3pt]$#3T_{\tf fluff}$ \NC
+ \NR}
+
+\starttabulate[|Tl|Tl|l|l|l|l|]
+ \FL
+ \MathSample{normal}{modern} {\mr}
+ \MathSample{} {pagella} {\mr}
+ \MathSample{} {cambria} {\mr}
+ \MathSample{} {lucidaot}{\mr}
+ \ML
+ \MathSample{bold} {modern} {\mb}
+ \MathSample{} {pagella} {\mb}
+ \MathSample{} {cambria} {\mb}
+ \MathSample{} {lucidaot}{\mb}
+ \LL
+\stoptabulate
+
+\subsection{Forcing fixed scripts with \lpr {mathscriptsmode}}
+
+We have three parameters that are used for this fixed anchoring:
+
+\starttabulate[|c|l|]
+\DB parameter \BC register \NC \NR
+\NC $d$ \NC \lpr {Umathsubshiftdown} \NC \NR
+\NC $u$ \NC \lpr {Umathsupshiftup} \NC \NR
+\NC $s$ \NC \lpr {Umathsubsupshiftdown} \NC \NR
+\LL
+\stoptabulate
+
+When we set \lpr {mathscriptsmode} to a value other than zero these are used
+for calculating fixed positions. This is something that is needed for instance
+for chemistry. You can manipulate the mentioned variables to achieve different
+effects.
+
+\def\SampleMath#1%
+ {$\mathscriptsmode#1\mathupright CH_2 + CH^+_2 + CH^2_2$}
+
+\starttabulate[|c|c|c|p|]
+\DB mode \BC down \BC up \BC example \NC \NR
+\TB
+\NC 0 \NC dynamic \NC dynamic \NC \SampleMath{0} \NC \NR
+\NC 1 \NC $d$ \NC $u$ \NC \SampleMath{1} \NC \NR
+\NC 2 \NC $s$ \NC $u$ \NC \SampleMath{2} \NC \NR
+\NC 3 \NC $s$ \NC $u + s - d$ \NC \SampleMath{3} \NC \NR
+\NC 4 \NC $d + (s-d)/2$ \NC $u + (s-d)/2$ \NC \SampleMath{4} \NC \NR
+\NC 5 \NC $d$ \NC $u + s - d$ \NC \SampleMath{5} \NC \NR
+\LL
+\stoptabulate
+
+The value of this parameter obeys grouping but applies to the whole current
+formula.
+
+% if needed we can put the value in stylenodes but maybe more should go there
+
+\subsection{Penalties: \lpr {mathpenaltiesmode}}
+
+\topicindex {math+penalties}
+
+Only in inline math penalties will be added in a math list. You can force
+penalties (also in display math) by setting:
+
+\starttyping
+\mathpenaltiesmode = 1
+\stoptyping
+
+This primnitive is not really needed in \LUATEX\ because you can use the callback
+\cbk {mlist_to_hlist} to force penalties by just calling the regular routine
+with forced penalties. However, as part of opening up and control this primitive
+makes sense. As a bonus we also provide two extra penalties:
+
+\starttyping
+\prebinoppenalty = -100 % example value
+\prerelpenalty = 900 % example value
+\stoptyping
+
+They default to inifinite which signals that they don't need to be inserted. When
+set they are injected before a binop or rel noad. This is an experimental feature.
+
+\subsection{Equation spacing: \lpr {matheqnogapstep}}
+
+By default \TEX\ will add one quad between the equation and the number. This is
+hard coded. A new primitive can control this:
+
+\startsyntax
+\matheqnogapstep = 1000
+\stopsyntax
+
+Because a math quad from the math text font is used instead of a dimension, we
+use a step to control the size. A value of zero will suppress the gap. The step
+is divided by 1000 which is the usual way to mimmick floating point factors in
+\TEX.
+
+\stopsection
+
+\startsection[title={Math constructs}]
+
+\subsection {Unscaled fences and \lpr{mathdelimitersmode}}
+
+\topicindex {math+fences}
+
+The \lpr {mathdelimitersmode} primitive is experimental and deals with the
+following (potential) problems. Three bits can be set. The first bit prevents an
+unwanted shift when the fence symbol is not scaled (a cambria side effect). The
+second bit forces italic correction between a preceding character ordinal and the
+fenced subformula, while the third bit turns that subformula into an ordinary so
+that the same spacing applies as with unfenced variants. Here we show Cambria
+(with \lpr {mathitalicsmode} enabled).
+
+\starttexdefinition Whatever #1
+ \NC \type{\mathdelimitersmode = #1}
+ \NC \mathitalicsmode1\mathdelimitersmode#1\ruledhbox{\showglyphs\showfontkerns\showfontitalics$f(x)$}
+ \NC \mathitalicsmode1\mathdelimitersmode#1\ruledhbox{\showglyphs\showfontkerns\showfontitalics$f\left(x\right)$}
+ \NC \NR
+\stoptexdefinition
+
+\start
+ \switchtobodyfont[cambria]
+ \starttabulate[|l|l|l|]
+ \Whatever{0}\Whatever{1}\Whatever{2}\Whatever{3}%
+ \Whatever{4}\Whatever{5}\Whatever{6}\Whatever{7}%
+ \stoptabulate
+\stop
+
+So, when set to 7 fenced subformulas with unscaled delimiters come out the same
+as unfenced ones. This can be handy for cases where one is forced to use \prm
+{left} and \prm {right} always because of unpredictable content. As said, it's an
+experimental feature (which somehow fits in the exceptional way fences are dealt
+with in the engine). The full list of flags is given in the next table:
+
+\starttabulate[|c|l|]
+\DB value \BC meaning \NC \NR
+\TB
+\NC \type{"01} \NC don't apply the usual shift \NC \NR
+\NC \type{"02} \NC apply italic correction when possible \NC \NR
+\NC \type{"04} \NC force an ordinary subformula \NC \NR
+\NC \type{"08} \NC no shift when a base character \NC \NR
+\NC \type{"10} \NC only shift when an extensible \NC \NR
+\LL
+\stoptabulate
+
+The effect can depend on the font (and for Cambria one can use for instance \type {"16}).
+
+\subsection[mathacc]{Accent handling with \lpr {Umathaccent}}
+
+\topicindex {math+accents}
+
+\LUATEX\ supports both top accents and bottom accents in math mode, and math
+accents stretch automatically (if this is supported by the font the accent comes
+from, of course). Bottom and combined accents as well as fixed-width math accents
+are controlled by optional keywords following \lpr {Umathaccent}.
+
+The keyword \type {bottom} after \lpr {Umathaccent} signals that a bottom accent
+is needed, and the keyword \type {both} signals that both a top and a bottom
+accent are needed (in this case two accents need to be specified, of course).
+
+Then the set of three integers defining the accent is read. This set of integers
+can be prefixed by the \type {fixed} keyword to indicate that a non-stretching
+variant is requested (in case of both accents, this step is repeated).
+
+A simple example:
+
+\starttyping
+\Umathaccent both fixed 0 0 "20D7 fixed 0 0 "20D7 {example}
+\stoptyping
+
+If a math top accent has to be placed and the accentee is a character and has a
+non-zero \type {top_accent} value, then this value will be used to place the
+accent instead of the \prm {skewchar} kern used by \TEX82.
+
+The \type {top_accent} value represents a vertical line somewhere in the
+accentee. The accent will be shifted horizontally such that its own \type
+{top_accent} line coincides with the one from the accentee. If the \type
+{top_accent} value of the accent is zero, then half the width of the accent
+followed by its italic correction is used instead.
+
+The vertical placement of a top accent depends on the \type {x_height} of the
+font of the accentee (as explained in the \TEX book), but if a value turns out
+to be zero and the font had a \type {MathConstants} table, then \type
+{AccentBaseHeight} is used instead.
+
+The vertical placement of a bottom accent is straight below the accentee, no
+correction takes place.
+
+Possible locations are \type {top}, \type {bottom}, \type {both} and \type
+{center}. When no location is given \type {top} is assumed. An additional
+parameter \nod {fraction} can be specified followed by a number; a value of for
+instance 1200 means that the criterium is 1.2 times the width of the nucleus. The
+fraction only applies to the stepwise selected shapes and is mostly meant for the
+\type {overlay} location. It also works for the other locations but then it
+concerns the width.
+
+\subsection{Building radicals with \lpr {Uradical} and \lpr {Uroot}}
+
+\topicindex {math+radicals}
+
+The new primitive \lpr {Uroot} allows the construction of a radical noad
+including a degree field. Its syntax is an extension of \lpr {Uradical}:
+
+\starttyping
+\Uradical <fam integer> <char integer> <radicand>
+\Uroot <fam integer> <char integer> <degree> <radicand>
+\stoptyping
+
+The placement of the degree is controlled by the math parameters \lpr
+{Umathradicaldegreebefore}, \lpr {Umathradicaldegreeafter}, and \lpr
+{Umathradicaldegreeraise}. The degree will be typeset in \prm
+{scriptscriptstyle}.
+
+\subsection{Super- and subscripts}
+
+The character fields in a \LUA|-|loaded \OPENTYPE\ math font can have a \quote
+{mathkern} table. The format of this table is the same as the \quote {mathkern}
+table that is returned by the \type {fontloader} library, except that all height
+and kern values have to be specified in actual scaled points.
+
+When a super- or subscript has to be placed next to a math item, \LUATEX\ checks
+whether the super- or subscript and the nucleus are both simple character items.
+If they are, and if the fonts of both character items are \OPENTYPE\ fonts (as
+opposed to legacy \TEX\ fonts), then \LUATEX\ will use the \OPENTYPE\ math
+algorithm for deciding on the horizontal placement of the super- or subscript.
+
+This works as follows:
+
+\startitemize
+ \startitem
+ The vertical position of the script is calculated.
+ \stopitem
+ \startitem
+ The default horizontal position is flat next to the base character.
+ \stopitem
+ \startitem
+ For superscripts, the italic correction of the base character is added.
+ \stopitem
+ \startitem
+ For a superscript, two vertical values are calculated: the bottom of the
+ script (after shifting up), and the top of the base. For a subscript, the two
+ values are the top of the (shifted down) script, and the bottom of the base.
+ \stopitem
+ \startitem
+ For each of these two locations:
+ \startitemize
+ \startitem
+ find the math kern value at this height for the base (for a subscript
+ placement, this is the bottom_right corner, for a superscript
+ placement the top_right corner)
+ \stopitem
+ \startitem
+ find the math kern value at this height for the script (for a
+ subscript placement, this is the top_left corner, for a superscript
+ placement the bottom_left corner)
+ \stopitem
+ \startitem
+ add the found values together to get a preliminary result.
+ \stopitem
+ \stopitemize
+ \stopitem
+ \startitem
+ The horizontal kern to be applied is the smallest of the two results from
+ previous step.
+ \stopitem
+\stopitemize
+
+The math kern value at a specific height is the kern value that is specified by the
+next higher height and kern pair, or the highest one in the character (if there is no
+value high enough in the character), or simply zero (if the character has no math kern
+pairs at all).
+
+\subsection{Scripts on extensibles: \lpr {Uunderdelimiter}, \lpr {Uoverdelimiter},
+\lpr {Udelimiterover}, \lpr {Udelimiterunder} and \lpr {Uhextensible}}
+
+\topicindex {math+scripts}
+\topicindex {math+delimiters}
+\topicindex {math+extensibles}
+
+The primitives \lpr {Uunderdelimiter} and \lpr {Uoverdelimiter} allow the
+placement of a subscript or superscript on an automatically extensible item and
+\lpr {Udelimiterunder} and \lpr {Udelimiterover} allow the placement of an
+automatically extensible item as a subscript or superscript on a nucleus. The
+input:
+
+% these produce radical noads .. in fact the code base has the numbers wrong for
+% quite a while, so no one seems to use this
+
+\startbuffer
+$\Uoverdelimiter 0 "2194 {\hbox{\strut overdelimiter}}$
+$\Uunderdelimiter 0 "2194 {\hbox{\strut underdelimiter}}$
+$\Udelimiterover 0 "2194 {\hbox{\strut delimiterover}}$
+$\Udelimiterunder 0 "2194 {\hbox{\strut delimiterunder}}$
+\stopbuffer
+
+\typebuffer will render this:
+
+\blank \startnarrower \getbuffer \stopnarrower \blank
+
+The vertical placements are controlled by \lpr {Umathunderdelimiterbgap}, \lpr
+{Umathunderdelimitervgap}, \lpr {Umathoverdelimiterbgap}, and \lpr
+{Umathoverdelimitervgap} in a similar way as limit placements on large operators.
+The superscript in \lpr {Uoverdelimiter} is typeset in a suitable scripted style,
+the subscript in \lpr {Uunderdelimiter} is cramped as well.
+
+These primitives accepts an option \type {width} specification. When used the
+also optional keywords \type {left}, \type {middle} and \type {right} will
+determine what happens when a requested size can't be met (which can happen when
+we step to successive larger variants).
+
+An extra primitive \lpr {Uhextensible} is available that can be used like this:
+
+\startbuffer
+$\Uhextensible width 10cm 0 "2194$
+\stopbuffer
+
+\typebuffer This will render this:
+
+\blank \startnarrower \getbuffer \stopnarrower \blank
+
+Here you can also pass options, like:
+
+\startbuffer
+$\Uhextensible width 1pt middle 0 "2194$
+\stopbuffer
+
+\typebuffer This gives:
+
+\blank \startnarrower \getbuffer \stopnarrower \blank
+
+\LUATEX\ internally uses a structure that supports \OPENTYPE\ \quote
+{MathVariants} as well as \TFM\ \quote {extensible recipes}. In most cases where
+font metrics are involved we have a different code path for traditional fonts end
+\OPENTYPE\ fonts.
+
+\subsection{Fractions and the new \lpr {Uskewed} and \lpr {Uskewedwithdelims}}
+
+\topicindex {math+fractions}
+
+The \prm {abovewithdelims} command accepts a keyword \type {exact}. When issued
+the extra space relative to the rule thickness is not added. One can of course
+use the \type {\Umathfraction..gap} commands to influence the spacing. Also the
+rule is still positioned around the math axis.
+
+\starttyping
+$$ { {a} \abovewithdelims() exact 4pt {b} }$$
+\stoptyping
+
+The math parameter table contains some parameters that specify a horizontal and
+vertical gap for skewed fractions. Of course some guessing is needed in order to
+implement something that uses them. And so we now provide a primitive similar to the
+other fraction related ones but with a few options so that one can influence the
+rendering. Of course a user can also mess around a bit with the parameters
+\lpr {Umathskewedfractionhgap} and \lpr {Umathskewedfractionvgap}.
+
+The syntax used here is:
+
+\starttyping
+{ {1} \Uskewed / <options> {2} }
+{ {1} \Uskewedwithdelims / () <options> {2} }
+\stoptyping
+
+where the options can be \type {noaxis} and \type {exact}. By default we add half
+the axis to the shifts and by default we zero the width of the middle character.
+For Latin Modern the result looks as follows:
+
+\def\ShowA#1#2#3{$x + { {#1} \Uskewed / #3 {#2} } + x$}
+\def\ShowB#1#2#3{$x + { {#1} \Uskewedwithdelims / () #3 {#2} } + x$}
+
+\start
+ \switchtobodyfont[modern]
+ \starttabulate[||||||]
+ \NC \NC
+ \ShowA{a}{b}{} \NC
+ \ShowA{1}{2}{} \NC
+ \ShowB{a}{b}{} \NC
+ \ShowB{1}{2}{} \NC
+ \NR
+ \NC \type{exact} \NC
+ \ShowA{a}{b}{exact} \NC
+ \ShowA{1}{2}{exact} \NC
+ \ShowB{a}{b}{exact} \NC
+ \ShowB{1}{2}{exact} \NC
+ \NR
+ \NC \type{noaxis} \NC
+ \ShowA{a}{b}{noaxis} \NC
+ \ShowA{1}{2}{noaxis} \NC
+ \ShowB{a}{b}{noaxis} \NC
+ \ShowB{1}{2}{noaxis} \NC
+ \NR
+ \NC \type{exact noaxis} \NC
+ \ShowA{a}{b}{exact noaxis} \NC
+ \ShowA{1}{2}{exact noaxis} \NC
+ \ShowB{a}{b}{exact noaxis} \NC
+ \ShowB{1}{2}{exact noaxis} \NC
+ \NR
+ \stoptabulate
+\stop
+
+\subsection {Delimiters: \type{\Uleft}, \prm {Umiddle} and \prm {Uright}}
+
+\topicindex {math+delimiters}
+
+Normally you will force delimiters to certain sizes by putting an empty box or
+rule next to it. The resulting delimiter will either be a character from the
+stepwise size range or an extensible. The latter can be quite differently
+positioned than the characters as it depends on the fit as well as the fact if
+the used characters in the font have depth or height. Commands like (plain \TEX
+s) \type {\big} need use this feature. In \LUATEX\ we provide a bit more control
+by three variants that support optional parameters \type {height}, \type {depth}
+and \type {axis}. The following example uses this:
+
+\startbuffer
+\Uleft height 30pt depth 10pt \Udelimiter "0 "0 "000028
+\quad x\quad
+\Umiddle height 40pt depth 15pt \Udelimiter "0 "0 "002016
+\quad x\quad
+\Uright height 30pt depth 10pt \Udelimiter "0 "0 "000029
+\quad \quad \quad
+\Uleft height 30pt depth 10pt axis \Udelimiter "0 "0 "000028
+\quad x\quad
+\Umiddle height 40pt depth 15pt axis \Udelimiter "0 "0 "002016
+\quad x\quad
+\Uright height 30pt depth 10pt axis \Udelimiter "0 "0 "000029
+\stopbuffer
+
+\typebuffer
+
+\startlinecorrection
+\ruledhbox{\mathematics{\getbuffer}}
+\stoplinecorrection
+
+The keyword \type {exact} can be used as directive that the real dimensions
+should be applied when the criteria can't be met which can happen when we're
+still stepping through the successively larger variants. When no dimensions are
+given the \type {noaxis} command can be used to prevent shifting over the axis.
+
+You can influence the final class with the keyword \type {class} which will
+influence the spacing. The numbers are the same as for character classes.
+
+\subsection {Accents: \type{\mathlimitsmode}}
+
+\topicindex {math+accents}
+
+When you use \type {\limits} or \type {\nolimits} without scripts spacing might
+get messed up. This can be prevented by setting \type {\mathlimitsmode} to a
+non|-|zero value.
+
+\stopsection
+
+\startsection[title={Extracting values}]
+
+\subsection{Codes and using \lpr {Umathcode}, \lpr {Umathcharclass}, \lpr
+{Umathcharfam} and \lpr {Umathcharslot}}
+
+\topicindex {math+codes}
+
+You can extract the components of a math character. Say that we have defined:
+
+\starttyping
+\Umathcode 1 2 3 4
+\stoptyping
+
+then
+
+\starttyping
+[\Umathcharclass1] [\Umathcharfam1] [\Umathcharslot1]
+\stoptyping
+
+will return:
+
+\starttyping
+[2] [3] [4]
+\stoptyping
+
+These commands are provides as convenience. Before they come available you could
+do the following:
+
+\starttyping
+\def\Umathcharclass{\directlua{tex.print(tex.getmathcode(token.scan_int())[1])}}
+\def\Umathcharfam {\directlua{tex.print(tex.getmathcode(token.scan_int())[2])}}
+\def\Umathcharslot {\directlua{tex.print(tex.getmathcode(token.scan_int())[3])}}
+\stoptyping
+
+\subsection {Last lines and \lpr{predisplaygapfactor}}
+
+\topicindex {math+last line}
+
+There is a new primitive to control the overshoot in the calculation of the
+previous line in mid|-|paragraph display math. The default value is 2 times
+the em width of the current font:
+
+\starttyping
+\predisplaygapfactor=2000
+\stoptyping
+
+If you want to have the length of the last line independent of math i.e.\ you don't
+want to revert to a hack where you insert a fake display math formula in order to
+get the length of the last line, the following will often work too:
+
+\starttyping
+\def\lastlinelength{\dimexpr
+ \directlua {tex.sprint (
+ (nodes.dimensions(node.tail(tex.lists.page_head).list))
+ )}sp
+\relax}
+\stoptyping
+
+\stopsection
+
+\startsection[title={Math mode}]
+
+\subsection {Verbose versions of single|-|character math commands like \lpr {Usuperscript}
+and \lpr {Usubscript}}
+
+\topicindex {math+styles}
+
+\LUATEX\ defines six new primitives that have the same function as
+\type {^}, \type {_}, \type {$}, and \type {$$}:
+
+\starttabulate[|l|l|]
+\DB primitive \BC explanation \NC \NR
+\TB
+\NC \lpr {Usuperscript} \NC duplicates the functionality of \type {^} \NC \NR
+\NC \lpr {Usubscript} \NC duplicates the functionality of \type {_} \NC \NR
+\NC \lpr {Ustartmath} \NC duplicates the functionality of \type {$}, % $
+ when used in non-math mode. \NC \NR
+\NC \lpr {Ustopmath} \NC duplicates the functionality of \type {$}, % $
+ when used in inline math mode. \NC \NR
+\NC \lpr {Ustartdisplaymath} \NC duplicates the functionality of \type {$$}, % $$
+ when used in non-math mode. \NC \NR
+\NC \lpr {Ustopdisplaymath} \NC duplicates the functionality of \type {$$}, % $$
+ when used in display math mode. \NC \NR
+\LL
+\stoptabulate
+
+The \lpr {Ustopmath} and \lpr {Ustopdisplaymath} primitives check if the current
+math mode is the correct one (inline vs.\ displayed), but you can freely intermix
+the four mathon|/|mathoff commands with explicit dollar sign(s).
+
+\subsection{Script commands \lpr {Unosuperscript} and \lpr {Unosubscript}}
+
+\topicindex {math+styles}
+\topicindex {math+scripts}
+
+These two commands result in super- and subscripts but with the current style (at the
+time of rendering). So,
+
+\startbuffer[script]
+$
+ x\Usuperscript {1}\Usubscript {2} =
+ x\Unosuperscript{1}\Unosubscript{2} =
+ x\Usuperscript {1}\Unosubscript{2} =
+ x\Unosuperscript{1}\Usubscript {2}
+$
+\stopbuffer
+
+\typebuffer
+
+results in \inlinebuffer[script].
+
+\subsection{Allowed math commands in non|-|math modes}
+
+\topicindex {math+text}
+\topicindex {text+math}
+
+The commands \prm {mathchar}, and \lpr {Umathchar} and control sequences that are
+the result of \prm {mathchardef} or \lpr {Umathchardef} are also acceptable in
+the horizontal and vertical modes. In those cases, the \prm {textfont} from the
+requested math family is used.
+
+\stopsection
+
+\startsection[title={Goodies}]
+
+\subsection {Flattening: \lpr {mathflattenmode}}
+
+\topicindex {math+flattening}
+
+The \TEX\ math engine collapses \type {ord} noads without sub- and superscripts
+and a character as nucleus. and which has the side effect that in \OPENTYPE\ mode
+italic corrections are applied (given that they are enabled).
+
+\startbuffer[sample]
+\switchtobodyfont[modern]
+$V \mathbin{\mathbin{v}} V$\par
+$V \mathord{\mathord{v}} V$\par
+\stopbuffer
+
+\typebuffer[sample]
+
+This renders as:
+
+\blank \start \mathflattenmode\plusone \getbuffer[sample] \stop \blank
+
+When we set \lpr {mathflattenmode} to 31 we get:
+
+\blank \start \mathflattenmode\numexpr1+2+4+8+16\relax \getbuffer[sample] \stop \blank
+
+When you see no difference, then the font probably has the proper character
+dimensions and no italic correction is needed. For Latin Modern (at least till
+2018) there was a visual difference. In that respect this parameter is not always
+needed unless of course you want efficient math lists anyway.
+
+You can influence flattening by adding the appropriate number to the value of the
+mode parameter. The default value is~1.
+
+\starttabulate[|Tc|c|]
+\DB mode \BC class \NC \NR
+\TB
+\NC 1 \NC ord \NC \NR
+\NC 2 \NC bin \NC \NR
+\NC 4 \NC rel \NC \NR
+\NC 8 \NC punct \NC \NR
+\NC 16 \NC inner \NC \NR
+\LL
+\stoptabulate
+
+\subsection {Less Tracing}
+
+\topicindex {math+tracing}
+
+Because there are quite some math related parameters and values, it is possible
+to limit tracing. Only when \type {tracingassigns} and|/|or \type
+{tracingrestores} are set to~2 or more they will be traced.
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-metapost.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-metapost.tex
new file mode 100644
index 00000000000..6cee0f4937f
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-metapost.tex
@@ -0,0 +1,453 @@
+% language=uk
+
+% lua.newtable
+
+\environment luametatex-style
+
+\startcomponent luametatex-metapost
+
+\startchapter[reference=metapost,title={The \METAPOST\ library \type {mplib}}]
+
+\startsection[title={Process management}][library=mplib]
+
+\topicindex {\METAPOST}
+\topicindex {\METAPOST+mplib}
+\topicindex {images+mplib}
+\topicindex {images+\METAPOST}
+
+\libindex{version}
+
+The \METAPOST\ library interface registers itself in the table \type {mplib}. It
+is based on \MPLIB\ version \ctxlua {context(mplib.version())}.
+
+\subsection{\type {new}}
+
+\libindex{new}
+
+To create a new \METAPOST\ instance, call
+
+\startfunctioncall
+<mpinstance> mp = mplib.new({...})
+\stopfunctioncall
+
+This creates the \type {mp} instance object. The argument hash can have a number
+of different fields, as follows:
+
+\starttabulate[|l|l|pl|pl|]
+\DB name \BC type \BC description \BC default \NC \NR
+\TB
+\NC \type{error_line} \NC number \NC error line width \NC 79 \NC \NR
+\NC \type{print_line} \NC number \NC line length in ps output \NC 100 \NC \NR
+\NC \type{random_seed} \NC number \NC the initial random seed \NC variable \NC \NR
+\NC \type{math_mode} \NC string \NC the number system to use:
+ \type {scaled},
+ \type {double} or
+ % \type {binary} or
+ \type {decimal} \NC \type {scaled} \NC \NR
+\NC \type{interaction} \NC string \NC the interaction mode:
+ \type {batch},
+ \type {nonstop},
+ \type {scroll} or
+ \type {errorstop} \NC \type {errorstop} \NC \NR
+\NC \type{job_name} \NC string \NC a compatibility value \NC \type {mpout} \NC \NR
+\NC \type{find_file} \NC function \NC a function to find files \NC only local files \NC \NR
+\NC \type{utf8} \NC boolean \NC permit characters in the
+ range 128 upto 255 to be
+ part of names \NC \type {false} \NC \NR
+\LL
+\stoptabulate
+
+The binary mode is no longer available in the \LUATEX\ version of \MPLIB. It
+offers no real advantage and brings a ton of extra libraries with platform
+specific properties that we can now avoid. We might introduce a high resolution
+scaled variant at some point but only when it pays of performance wise.
+
+The \type {find_file} function should be of this form:
+
+\starttyping
+<string> found = finder (<string> name, <string> mode, <string> type)
+\stoptyping
+
+with:
+
+\starttabulate[|l|p|]
+\DB name \BC the requested file \NC \NR
+\TB
+\NC \type{mode} \NC the file mode: \type {r} or \type {w} \NC \NR
+\NC \type{type} \NC the kind of file, one of: \type {mp}, \type {tfm}, \type {map},
+ \type {pfb}, \type {enc} \NC \NR
+\LL
+\stoptabulate
+
+Return either the full path name of the found file, or \type {nil} if the file
+cannot be found.
+
+Note that the new version of \MPLIB\ no longer uses binary mem files, so the way
+to preload a set of macros is simply to start off with an \type {input} command
+in the first \type {execute} call.
+
+When you are processing a snippet of text starting with \type {btex} or \type
+{verbatimtex} and ending with \type {etex}, the \METAPOST\ \type {texscriptmode}
+parameter controls how spaces and newlines get honoured. The default value is~1.
+Possible values are:
+
+\starttabulate[|l|p|]
+\DB name \BC meaning \NC \NR
+\TB
+\NC \type {0} \NC no newlines \NC \NR
+\NC \type {1} \NC newlines in \type {verbatimtex} \NC \NR
+\NC \type {2} \NC newlines in \type {verbatimtex} and \type {etex} \NC \NR
+\NC \type {3} \NC no leading and trailing strip in \type {verbatimtex} \NC \NR
+\NC \type {4} \NC no leading and trailing strip in \type {verbatimtex} and \type {btex} \NC \NR
+\LL
+\stoptabulate
+
+That way the \LUA\ handler (assigned to \type {make_text}) can do what it likes.
+An \type {etex} has to be followed by a space or \type {;} or be at the end of a
+line and preceded by a space or at the beginning of a line.
+
+\subsection{\type {statistics}}
+
+\libindex{statistics}
+
+You can request statistics with:
+
+\startfunctioncall
+<table> stats = mp:statistics()
+\stopfunctioncall
+
+This function returns the vital statistics for an \MPLIB\ instance. There are
+four fields, giving the maximum number of used items in each of four allocated
+object classes:
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{main_memory} \NC number \NC memory size \NC \NR
+\NC \type{hash_size} \NC number \NC hash size\NC \NR
+\NC \type{param_size} \NC number \NC simultaneous macro parameters\NC \NR
+\NC \type{max_in_open} \NC number \NC input file nesting levels\NC \NR
+\LL
+\stoptabulate
+
+Note that in the new version of \MPLIB, this is informational only. The objects
+are all allocated dynamically, so there is no chance of running out of space
+unless the available system memory is exhausted.
+
+\subsection{\type {execute}}
+
+\libindex{execute}
+
+You can ask the \METAPOST\ interpreter to run a chunk of code by calling
+
+\startfunctioncall
+<table> rettable = execute(mp,"metapost code")
+\stopfunctioncall
+
+for various bits of \METAPOST\ language input. Be sure to check the \type
+{rettable.status} (see below) because when a fatal \METAPOST\ error occurs the
+\MPLIB\ instance will become unusable thereafter.
+
+Generally speaking, it is best to keep your chunks small, but beware that all
+chunks have to obey proper syntax, like each of them is a small file. For
+instance, you cannot split a single statement over multiple chunks.
+
+In contrast with the normal stand alone \type {mpost} command, there is
+\notabene {no} implied \quote{input} at the start of the first chunk.
+
+\subsection{\type {finish}}
+
+\libindex{finish}
+
+\startfunctioncall
+<table> rettable = finish(mp)
+\stopfunctioncall
+
+If for some reason you want to stop using an \MPLIB\ instance while processing is
+not yet actually done, you can call \type {finish}. Eventually, used memory
+will be freed and open files will be closed by the \LUA\ garbage collector, but
+an explicit \type {finish} is the only way to capture the final part of the
+output streams.
+
+\stopsection
+
+\startsection[title={The end result}]
+
+\libindex {fields}
+
+The return value of \type {execute} and \type {finish} is a table with a
+few possible keys (only \type {status} is always guaranteed to be present).
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{log} \NC string \NC output to the \quote {log} stream \NC \NR
+\NC \type{term} \NC string \NC output to the \quote {term} stream \NC \NR
+\NC \type{error} \NC string \NC output to the \quote {error} stream
+ (only used for \quote {out of memory}) \NC \NR
+\NC \type{status} \NC number \NC the return value:
+ \type {0} = good,
+ \type {1} = warning,
+ \type {2} = errors,
+ \type {3} = fatal error \NC \NR
+\NC \type{fig} \NC table \NC an array of generated figures (if any) \NC \NR
+\LL
+\stoptabulate
+
+When \type {status} equals~3, you should stop using this \MPLIB\ instance
+immediately, it is no longer capable of processing input.
+
+If it is present, each of the entries in the \type {fig} array is a userdata
+representing a figure object, and each of those has a number of object methods
+you can call:
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{boundingbox} \NC function \NC returns the bounding box, as an array of 4
+ values \NC \NR
+\NC \type{postscript} \NC function \NC returns a string that is the ps output of the
+ \type {fig}. this function accepts two optional
+ integer arguments for specifying the values of
+ \type {prologues} (first argument) and \type
+ {procset} (second argument) \NC \NR
+\NC \type{svg} \NC function \NC returns a string that is the svg output of the
+ \type {fig}. This function accepts an optional
+ integer argument for specifying the value of
+ \type {prologues} \NC \NR
+\NC \type{objects} \NC function \NC returns the actual array of graphic objects in
+ this \type {fig} \NC \NR
+\NC \type{copy_objects} \NC function \NC returns a deep copy of the array of graphic
+ objects in this \type {fig} \NC \NR
+\NC \type{filename} \NC function \NC the filename this \type {fig}'s \POSTSCRIPT\
+ output would have written to in stand alone
+ mode \NC \NR
+\NC \type{width} \NC function \NC the \type {fontcharwd} value \NC \NR
+\NC \type{height} \NC function \NC the \type {fontcharht} value \NC \NR
+\NC \type{depth} \NC function \NC the \type {fontchardp} value \NC \NR
+\NC \type{italcorr} \NC function \NC the \type {fontcharit} value \NC \NR
+\NC \type{charcode} \NC function \NC the (rounded) \type {charcode} value \NC \NR
+\LL
+\stoptabulate
+
+Note: you can call \type {fig:objects()} only once for any one \type {fig}
+object!
+
+When the boundingbox represents a \quote {negated rectangle}, i.e.\ when the
+first set of coordinates is larger than the second set, the picture is empty.
+
+Graphical objects come in various types that each has a different list of
+accessible values. The types are: \type {fill}, \type {outline}, \type {text},
+\type {start_clip}, \type {stop_clip}, \type {start_bounds}, \type {stop_bounds},
+\type {special}.
+
+There is a helper function (\type {mplib.fields(obj)}) to get the list of
+accessible values for a particular object, but you can just as easily use the
+tables given below.
+
+All graphical objects have a field \type {type} that gives the object type as a
+string value; it is not explicit mentioned in the following tables. In the
+following, \type {number}s are \POSTSCRIPT\ points represented as a floating
+point number, unless stated otherwise. Field values that are of type \type
+{table} are explained in the next section.
+
+\subsection{fill}
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{path} \NC table \NC the list of knots \NC \NR
+\NC \type{htap} \NC table \NC the list of knots for the reversed trajectory \NC \NR
+\NC \type{pen} \NC table \NC knots of the pen \NC \NR
+\NC \type{color} \NC table \NC the object's color \NC \NR
+\NC \type{linejoin} \NC number \NC line join style (bare number)\NC \NR
+\NC \type{miterlimit} \NC number \NC miterlimit\NC \NR
+\NC \type{prescript} \NC string \NC the prescript text \NC \NR
+\NC \type{postscript} \NC string \NC the postscript text \NC \NR
+\LL
+\stoptabulate
+
+The entries \type {htap} and \type {pen} are optional.
+
+\subsection{outline}
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{path} \NC table \NC the list of knots \NC \NR
+\NC \type{pen} \NC table \NC knots of the pen \NC \NR
+\NC \type{color} \NC table \NC the object's color \NC \NR
+\NC \type{linejoin} \NC number \NC line join style (bare number) \NC \NR
+\NC \type{miterlimit} \NC number \NC miterlimit \NC \NR
+\NC \type{linecap} \NC number \NC line cap style (bare number) \NC \NR
+\NC \type{dash} \NC table \NC representation of a dash list \NC \NR
+\NC \type{prescript} \NC string \NC the prescript text \NC \NR
+\NC \type{postscript} \NC string \NC the postscript text \NC \NR
+\LL
+\stoptabulate
+
+The entry \type {dash} is optional.
+
+\subsection{text}
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{text} \NC string \NC the text \NC \NR
+\NC \type{font} \NC string \NC font tfm name \NC \NR
+\NC \type{dsize} \NC number \NC font size \NC \NR
+\NC \type{color} \NC table \NC the object's color \NC \NR
+\NC \type{width} \NC number \NC \NC \NR
+\NC \type{height} \NC number \NC \NC \NR
+\NC \type{depth} \NC number \NC \NC \NR
+\NC \type{transform} \NC table \NC a text transformation \NC \NR
+\NC \type{prescript} \NC string \NC the prescript text \NC \NR
+\NC \type{postscript} \NC string \NC the postscript text \NC \NR
+\LL
+\stoptabulate
+
+\subsection{special}
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{prescript} \NC string \NC special text \NC \NR
+\LL
+\stoptabulate
+
+\subsection{start_bounds, start_clip}
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{path} \NC table \NC the list of knots \NC \NR
+\LL
+\stoptabulate
+
+\subsubsection{stop_bounds, stop_clip}
+
+Here are no fields available.
+
+\stopsection
+
+\startsection[title={Subsidiary table formats}]
+
+\subsection{Paths and pens}
+
+Paths and pens (that are really just a special type of paths as far as \MPLIB\ is
+concerned) are represented by an array where each entry is a table that
+represents a knot.
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{left_type} \NC string \NC when present: endpoint, but usually absent \NC \NR
+\NC \type{right_type} \NC string \NC like \type {left_type} \NC \NR
+\NC \type{x_coord} \NC number \NC X coordinate of this knot \NC \NR
+\NC \type{y_coord} \NC number \NC Y coordinate of this knot \NC \NR
+\NC \type{left_x} \NC number \NC X coordinate of the precontrol point of this knot \NC \NR
+\NC \type{left_y} \NC number \NC Y coordinate of the precontrol point of this knot \NC \NR
+\NC \type{right_x} \NC number \NC X coordinate of the postcontrol point of this knot \NC \NR
+\NC \type{right_y} \NC number \NC Y coordinate of the postcontrol point of this knot \NC \NR
+\LL
+\stoptabulate
+
+There is one special case: pens that are (possibly transformed) ellipses have an
+extra key \type {type} with value \type {elliptical} besides the array part
+containing the knot list.
+
+\subsection{Colors}
+
+A color is an integer array with 0, 1, 3 or 4 values:
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{0} \NC marking only \NC no values \NC \NR
+\NC \type{1} \NC greyscale \NC one value in the range $(0,1)$, \quote {black} is $0$ \NC \NR
+\NC \type{3} \NC \RGB \NC three values in the range $(0,1)$, \quote {black} is $0,0,0$ \NC \NR
+\NC \type{4} \NC \CMYK \NC four values in the range $(0,1)$, \quote {black} is $0,0,0,1$ \NC \NR
+\LL
+\stoptabulate
+
+If the color model of the internal object was \type {uninitialized}, then it was
+initialized to the values representing \quote {black} in the colorspace \type
+{defaultcolormodel} that was in effect at the time of the \type {shipout}.
+
+\subsection{Transforms}
+
+Each transform is a six|-|item array.
+
+\starttabulate[|l|l|p|]
+\DB index \BC type \BC explanation \NC \NR
+\TB
+\NC \type{1} \NC number \NC represents x \NC \NR
+\NC \type{2} \NC number \NC represents y \NC \NR
+\NC \type{3} \NC number \NC represents xx \NC \NR
+\NC \type{4} \NC number \NC represents yx \NC \NR
+\NC \type{5} \NC number \NC represents xy \NC \NR
+\NC \type{6} \NC number \NC represents yy \NC \NR
+\LL
+\stoptabulate
+
+Note that the translation (index 1 and 2) comes first. This differs from the
+ordering in \POSTSCRIPT, where the translation comes last.
+
+\subsection{Dashes}
+
+Each \type {dash} is two-item hash, using the same model as \POSTSCRIPT\ for the
+representation of the dashlist. \type {dashes} is an array of \quote {on} and
+\quote {off}, values, and \type {offset} is the phase of the pattern.
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{dashes} \NC hash \NC an array of on-off numbers \NC \NR
+\NC \type{offset} \NC number \NC the starting offset value \NC \NR
+\LL
+\stoptabulate
+
+\subsection{Pens and \type {pen_info}}
+
+\libindex{pen_info}
+
+There is helper function (\type {pen_info(obj)}) that returns a table containing
+a bunch of vital characteristics of the used pen (all values are floats):
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{width} \NC number \NC width of the pen \NC \NR
+\NC \type{sx} \NC number \NC $x$ scale \NC \NR
+\NC \type{rx} \NC number \NC $xy$ multiplier \NC \NR
+\NC \type{ry} \NC number \NC $yx$ multiplier \NC \NR
+\NC \type{sy} \NC number \NC $y$ scale \NC \NR
+\NC \type{tx} \NC number \NC $x$ offset \NC \NR
+\NC \type{ty} \NC number \NC $y$ offset \NC \NR
+\LL
+\stoptabulate
+
+\stopsection
+
+\startsection[title=Acessors]
+
+\subsection[title={Character size information}]
+
+\libindex{char_width}
+\libindex{char_height}
+\libindex{char_depth}
+
+These functions find the size of a glyph in a defined font. The \type {fontname}
+is the same name as the argument to \type {infont}; the \type {char} is a glyph
+id in the range 0 to 255; the returned \type {w} is in AFM units.
+
+
+\startfunctioncall
+<number> w = char_width(mp,<string> fontname, <number> char)
+<number> h = char_height(mp,<string> fontname, <number> char)
+<number> d = char_depth(mp,<string> fontname, <number> char)
+\stopfunctioncall
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-modifications.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-modifications.tex
new file mode 100644
index 00000000000..6448f2b01c1
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-modifications.tex
@@ -0,0 +1,440 @@
+% language=uk
+
+\environment luametatex-style
+
+\startcomponent luametatex-modifications
+
+\startchapter[reference=modifications,title={The original engines}]
+
+\startsection[title=The merged engines]
+
+\startsubsection[title=The rationale]
+
+\topicindex {engines}
+\topicindex {history}
+
+The first version of \LUATEX, made by Hartmut after we discussed the possibility
+of an extension language, only had a few extra primitives and it was largely the
+same as \PDFTEX. It was presented to the public in 2005. As part of the Oriental
+\TEX\ project, Taco merged substantial parts of \ALEPH\ into the code and some
+more primitives were added. Then we started more fundamental experiments. After
+many years, when the engine had become more stable, the decision was made to
+clean up the rather hybrid nature of the program. This means that some primitives
+were promoted to core primitives, often with a different name, and that others
+were removed. This also made it possible to start cleaning up the code base. In
+\in {chapter} [enhancements] we discuss some new primitives, here we will cover
+most of the adapted ones.
+
+During more than a decade stepwise new functionality was added and after 10 years
+the more of less stable version 1.0 was presented. But we continued and after
+some 15 years the \LUAMETATEX\ follow up entered its first testing stage. But
+before details about the engine are discussed in successive chapters, we first
+summarize where we started from. Keep in mind that in \LUAMETATEX\ we have a bit
+less than in \LUATEX, so this section differs from the one in the \LUATEX\
+manual.
+
+Besides the expected changes caused by new functionality, there are a number of
+not|-|so|-|expected changes. These are sometimes a side|-|effect of a new
+(conflicting) feature, or, more often than not, a change necessary to clean up
+the internal interfaces. These will also be mentioned.
+
+\stopsubsection
+
+\startsubsection[title=Changes from \TEX\ 3.1415926]
+
+\topicindex {\TEX}
+
+Of course it all starts with traditional \TEX. Even if we started with \PDFTEX,
+most still comes from original Knuthian \TEX. But we divert a bit.
+
+\startitemize
+
+\startitem
+ The current code base is written in \CCODE, not \PASCAL. The original \CWEB\
+ documentation is kept when possible and not wrapped in tagged comments. As a
+ consequence instead of one large file plus change files, we now have multiple
+ files organized in categories like \type {tex}, \type {luaf}, \type
+ {languages}, \type {fonts}, \type {libraries}, etc. There are some artifacts
+ of the conversion to \CCODE, but these got (and get) removed stepwise. The
+ documentation, which actually comes from the mix of engines (via so called
+ change files), is kept as much as possible. Of course we want to stay as
+ close as possible to the original so that the documentation of the
+ fundamentals behind \TEX\ by Don Knuth still applies. However, because we use
+ \CCODE, some documentation is a bit off. Also, most global variables are now
+ collected in structures, but the original names were kept. There are lots of
+ so called macros too.
+\stopitem
+
+\startitem
+ See \in {chapter} [languages] for many small changes related to paragraph
+ building, language handling and hyphenation. The most important change is
+ that adding a brace group in the middle of a word (like in \type {of{}fice})
+ does not prevent ligature creation. Also, the hyphenation, ligature building
+ and kerning has been split so that we can hook in alternative or extra code
+ wherever we like. There are various options to control discretionary
+ injection and related penalties are now integrated in these nodes. Language
+ information is now bound to glyphs. The number of languages in \LUAMETATEX\
+ is smaller than in \LUATEX.
+\stopitem
+
+\startitem
+ There is no pool file, all strings are embedded during compilation. This also
+ removed some memory constraints. We kept token and node memory management
+ because it is convenient and efficient but parts were reimplemented in order
+ to remove some constraints. Token memory management is largely the same.
+\stopitem
+
+\startitem
+ The specifier \type {plus 1 fillll} does not generate an error. The extra
+ \quote {l} is simply typeset.
+\stopitem
+
+\startitem
+ The upper limit to \prm {endlinechar} and \prm {newlinechar} is 127.
+\stopitem
+
+\startitem
+ Because the backend is not built|-|in, the magnification (\prm {mag})
+ primitive is not doing nothing. A \type {shipout} just discards the content
+ of the given box. The write related primitives have to be implemented in the
+ used macro package using \LUA. None of the \PDFTEX\ derived primitives is
+ present.
+\stopitem
+
+\startitem
+ There is more control over some (formerly hard|-|coded) math properties. In fact,
+ there is a whole extra bit of math related code because we need to deal with
+ \OPENTYPE\ fonts.
+\stopitem
+
+\startitem
+ The \type {\outer} and \type {\long} prefixed are silently ignored. It is
+ permitted to use \type {\par} in math.
+\stopitem
+
+\startitem
+ Because there is no font loader, a \LUA\ variant is free to either support or
+ not the \OMEGA\ \type {ofm} file format. As there are hardly any such fonts
+ it probably makes no sense.
+\stopitem
+
+\startitem
+ The lack of a backend means that some primitives related to it are not
+ implemented. This is no big deal because it is possible to use the scanner
+ library to implement them as needed, which depends on the macro package and
+ backend.
+\stopitem
+
+\startitem
+ When detailed logging is enabled more detail is output with respect to what
+ nodes are involved. This is a side effect of the core nodes having more
+ detailed subtype information. The benefit of more detail wins from any wish
+ to be byte compatible in the logging. One can always write additional logging
+ in \LUA.
+\stopitem
+
+\stopitemize
+
+\stopsubsection
+
+\startsubsection[title=Changes from \ETEX\ 2.2]
+
+\topicindex {\ETEX}
+
+Being the de|-|facto standard extension of course we provide the \ETEX\
+features, but with a few small adaptations.
+
+\startitemize
+
+\startitem
+ The \ETEX\ functionality is always present and enabled so the prepended
+ asterisk or \type {-etex} switch for \INITEX\ is not needed.
+\stopitem
+
+\startitem
+ The \TEXXET\ extension is not present, so the primitives \type
+ {\TeXXeTstate}, \type {\beginR}, \type {\beginL}, \type {\endR} and \type
+ {\endL} are missing. Instead we used the \OMEGA|/|\ALEPH\ approach to
+ directionality as starting point, albeit it has been changed quite a bit,
+ so that we're probably not that far from \TEXXET.
+\stopitem
+
+\startitem
+ Some of the tracing information that is output by \ETEX's \prm
+ {tracingassigns} and \prm {tracingrestores} is not there. Also keep in mind
+ that tracing doesn't involve what \LUA\ does.
+\stopitem
+
+\startitem
+ Register management in \LUAMETATEX\ uses the \OMEGA|/|\ALEPH\ model, so the
+ maximum value is 65535 and the implementation uses a flat array instead of
+ the mixed flat & sparse model from \ETEX.
+\stopitem
+
+\startitem
+ Because we don't use change files on top of original \TEX, the integration of
+ \ETEX\ functionality is bit more natural, code wise.
+\stopitem
+
+\stopitemize
+
+\stopsubsection
+
+\startsubsection[title=Changes from \PDFTEX\ 1.40]
+
+\topicindex {\PDFTEX}
+
+Because we want to produce \PDF\ the most natural starting point was the popular
+\PDFTEX\ program. We inherit the stable features, dropped most of the
+experimental code and promoted some functionality to core \LUATEX\ functionality
+which in turn triggered renaming primitives. However, as the backend was dropped,
+not that much from \PDFTEX\ is present any more. Basically all we now inherit
+from \PDFTEX\ is expansion and protrusion but even that has been adapted. So
+don't expect \LUAMETATEX\ to be compatible.
+
+\startitemize
+
+\startitem
+ The experimental primitives \lpr {ifabsnum} and \lpr {ifabsdim} have been
+ promoted to core primitives.
+\stopitem
+
+\startitem
+ The primitives \lpr {ifincsname}, \lpr {expanded} and \lpr {quitvmode}
+ have become core primitives.
+\stopitem
+
+\startitem
+ As the hz (expansion) and protrusion mechanism are part of the core the
+ related primitives \lpr {lpcode}, \lpr {rpcode}, \lpr {efcode}, \lpr
+ {leftmarginkern}, \lpr {rightmarginkern} are promoted to core primitives. The
+ two commands \lpr {protrudechars} and \lpr {adjustspacing} control these
+ processes.
+\stopitem
+
+\startitem
+ In \LUAMETATEX\ three extra primitives can be used to overload the font
+ specific settings: \lpr {adjustspacingstep} (max: 100), \lpr
+ {adjustspacingstretch} (max: 1000) and \lpr {adjustspacingshrink} (max: 500).
+\stopitem
+
+\startitem
+ The hz optimization code has been partially redone so that we no longer need
+ to create extra font instances. The front- and backend have been decoupled
+ and the glyph and kern nodes carry the used values. In \LUATEX\ that made a
+ more efficient generation of \PDF\ code possible. It also resulted in much
+ cleaner code. The backend code is gone, but of course the information is
+ still carried around.
+\stopitem
+
+\startitem
+ When \lpr {adjustspacing} has value~2, hz optimization will be applied to
+ glyphs and kerns. When the value is~3, only glyphs will be treated. A value
+ smaller than~2 disables this feature. With value of~1, font expansion is
+ applied after \TEX's normal paragraph breaking routines have broken the
+ paragraph into lines. In this case, line breaks are identical to standard
+ \TEX\ behavior (as with \PDFTEX). But \unknown\ this is a left|-|over from
+ the early days of \PDFTEX\ when this feature was part of a research topic. At
+ some point level~1 might be dropped from \LUAMETATEX.
+\stopitem
+
+\startitem
+ When \lpr {protrudechars} has a value larger than zero characters at the edge
+ of a line can be made to hang out. A value of~2 will take the protrusion into
+ account when breaking a paragraph into lines. A value of~3 will try to deal
+ with right|-|to|-|left rendering; this is a still experimental feature.
+\stopitem
+
+\startitem
+ The pixel multiplier dimension \lpr {pxdimen} has be inherited as core
+ primitive.
+\stopitem
+
+\startitem
+ The primitive \lpr {tracingfonts} is now a core primitive but doesn't relate
+ to the backend.
+\stopitem
+
+\stopitemize
+
+\stopsubsection
+
+\startsubsection[title=Changes from \ALEPH\ RC4]
+
+\topicindex {\ALEPH}
+
+In \LUATEX\ we took the 32 bit aspects and much of the directional mechanisms and
+merged it into the \PDFTEX\ code base as starting point for further development.
+Then we simplified directionality, fixed it and opened it up. In \LUAMETATEX\ not
+that much of the later is left. We only have two horizontal directions. Instead
+of vertical directions we introduce an orientation model bound to boxes.
+
+The already reduced|-|to|-|four set of directions now only has two members:
+left|-|to|-|right and right|-|to|-|left. They don't do much as it is the backend
+that has to deal with them. When paragraphs are constructed a change in
+horizontal direction is irrelevant for calculating the dimensions. So, basically
+most that we do is registering state and passing that on till the backend can do
+something with it.
+
+Here is a summary of inherited functionality:
+
+\startitemize
+
+\startitem
+ The \type {^^} notation has been extended: after \type {^^^^} four
+ hexadecimal characters are expected and after \type {^^^^^^} six hexadecimal
+ characters have to be given. The original \TEX\ interpretation is still valid
+ for the \type {^^} case but the four and six variants do no backtracking,
+ i.e.\ when they are not followed by the right number of hexadecimal digits
+ they issue an error message. Because \type {^^^} is a normal \TEX\ case, we
+ don't support the odd number of \type {^^^^^} either.
+\stopitem
+
+\startitem
+ Glues {\it immediately after} direction change commands are not legal
+ breakpoints. There is a bit more sanity testing for the direction state.
+\stopitem
+
+\startitem
+ The placement of math formula numbers is direction aware and adapts
+ accordingly. Boxes carry directional information but rules don't.
+\stopitem
+
+\startitem
+ There are no direction related primitives for page and body directions. The
+ paragraph, text and math directions are specified using primitives that
+ take a number.
+\stopitem
+
+\stopitemize
+
+\stopsubsection
+
+\startsubsection[title=Changes from standard \WEBC]
+
+\topicindex {\WEBC}
+
+The \LUAMETATEX\ codebase is not dependent on the \WEBC\ framework. The
+interaction with the file system and \TDS\ is up to \LUA. There still might be
+traces but eventually the code base should be lean and mean. The \METAPOST\
+library is coded in \CWEB\ and in order to be independent from related tools,
+conversion to \CCODE\ is done with a \LUA\ script ran by, surprise, \LUAMETATEX.
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title=Implementation notes]
+
+\startsubsection[title=Memory allocation]
+
+\topicindex {memory}
+
+The single internal memory heap that traditional \TEX\ used for tokens and nodes
+is split into two separate arrays. Each of these will grow dynamically when
+needed. Internally a token or node is an index into these arrays. This permits
+for an efficient implementation and is also responsible for the performance of
+the core. The original documentation in \TEX\ The Program mostly applies!
+
+\stopsubsection
+
+\startsubsection[title=Sparse arrays]
+
+The \prm {mathcode}, \prm {delcode}, \prm {catcode}, \prm {sfcode}, \prm {lccode}
+and \prm {uccode} (and the new \lpr {hjcode}) tables are now sparse arrays that
+are implemented in~\CCODE. They are no longer part of the \TEX\ \quote
+{equivalence table} and because each had 1.1 million entries with a few memory
+words each, this makes a major difference in memory usage. Performance is not
+really hurt by this.
+
+The \prm {catcode}, \prm {sfcode}, \prm {lccode}, \prm {uccode} and \lpr {hjcode}
+assignments don't show up when using the \ETEX\ tracing routines \prm
+{tracingassigns} and \prm {tracingrestores} but we don't see that as a real
+limitation. It also saves a lot of clutter.
+
+A side|-|effect of the current implementation is that \prm {global} is now more
+expensive in terms of processing than non|-|global assignments but not many users
+will notice that.
+
+The glyph ids within a font are also managed by means of a sparse array as glyph
+ids can go up to index $2^{21}-1$ but these are never accessed directly so again
+users will not notice this.
+
+\stopsubsection
+
+\startsubsection[title=Simple single|-|character csnames]
+
+\topicindex {csnames}
+
+Single|-|character commands are no longer treated specially in the internals,
+they are stored in the hash just like the multiletter csnames.
+
+The code that displays control sequences explicitly checks if the length is one
+when it has to decide whether or not to add a trailing space.
+
+Active characters are internally implemented as a special type of multi|-|letter
+control sequences that uses a prefix that is otherwise impossible to obtain.
+
+\stopsubsection
+
+\startsubsection[title=Binary file reading]
+
+\topicindex {files+binary}
+
+All of the internal code is changed in such a way that if one of the \type
+{read_xxx_file} callbacks is not set, then the file is read by a \CCODE\ function
+using basically the same convention as the callback: a single read into a buffer
+big enough to hold the entire file contents. While this uses more memory than the
+previous code (that mostly used \type {getc} calls), it can be quite a bit faster
+(depending on your \IO\ subsystem). So far we never had issues with this approach.
+
+\stopsubsection
+
+\startsubsection[title=Tabs and spaces]
+
+\topicindex {space}
+\topicindex {newline}
+
+We conform to the way other \TEX\ engines handle trailing tabs and spaces. For
+decades trailing tabs and spaces (before a newline) were removed from the input
+but this behaviour was changed in September 2017 to only handle spaces. We are
+aware that this can introduce compatibility issues in existing workflows but
+because we don't want too many differences with upstream \TEXLIVE\ we just follow
+up on that patch (which is a functional one and not really a fix). It is up to
+macro packages maintainers to deal with possible compatibility issues and in
+\LUAMETATEX\ they can do so via the callbacks that deal with reading from files.
+
+The previous behaviour was a known side effect and (as that kind of input
+normally comes from generated sources) it was normally dealt with by adding a
+comment token to the line in case the spaces and|/|or tabs were intentional and
+to be kept. We are aware of the fact that this contradicts some of our other
+choices but consistency with other engines. We still stick to our view that at
+the log level we can (and might be) more incompatible. We already expose some
+more details anyway.
+
+\stopsubsection
+
+\startsubsection[title=Logging]
+
+The information that goes into the log file can be different from \LUATEX, and
+might even differ a bit more in the future. The main reason is that inside the
+engine we have more granularity, which for instance means that we output subtype
+related information when nodes are printed. Of course we could have offered a
+compatibility mode but it serves no purpose. Over time there have been many
+subtle changes to control logs in the \TEX\ ecosystems so another one is
+bearable.
+
+In a similar fashion, there is a bit different behaviour when \TEX\ expects
+input, which in turn is a side effect of removing the interception of \type {*}
+and \type {&} which made for cleaner code (quite a bit had accumulated as side
+effect of continuous adaptations in the \TEX\ ecosystems). There was already code
+that was never executed, simply as side effect of the way \LUATEX\ initializes
+itself (one needs to enable classes of primitives for instance).
+
+\stopsubsection
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-nodes.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-nodes.tex
new file mode 100644
index 00000000000..16c6e1202ab
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-nodes.tex
@@ -0,0 +1,2527 @@
+% language=uk
+
+\environment luametatex-style
+
+\startcomponent luametatex-nodes
+
+\startchapter[reference=nodes,title={Nodes}]
+
+\startsection[title={\LUA\ node representation}][library=node]
+
+\topicindex {nodes}
+
+\libindex {fields}
+\libindex {subtypes}
+\libindex {values}
+
+\TEX's nodes are represented in \LUA\ as userdata objects with a variable set of
+fields or by a numeric identifier when requested. When you print a node userdata
+object you will see these numbers. In the following syntax tables the type of
+such a userdata object is represented as \syntax {<node>}.
+
+\blank
+\dontleavehmode {\bf The return values of \type {node.types} are:} \showtypes
+\blank
+
+In \ETEX\ the \prm {lastnodetype} primitive has been introduced. With this
+primitive the valid range of numbers is still $[-1,15]$ and glyph nodes (formerly
+known as char nodes) have number~0. That way macro packages can use the same
+symbolic names as in traditional \ETEX. But you need to keep in mind that these
+\ETEX\ node numbers are different from the real internal ones. When you set \prm
+{internalcodesmode} to a non|-|zero value, the internal codes will be used in
+the \ETEX\ introspection commands \prm {lastnodetype} and \prm {currentiftype}.
+
+You can ask for a list of fields with \type {node.fields} and for valid subtypes
+with \type {node.subtypes}. The \type {node.values} function reports some used
+values. Valid arguments are \type {glue}, \type {style} and \type {math}. Keep in
+mind that the setters normally expect a number, but this helper gives you a list
+of what numbers matter. For practical reason the \type {pagestate} values are
+also reported with this helper, but they are backend specific.
+
+\def\ShowValues#1{
+ \blank
+ \dontleavehmode
+ {\bf The return values of \type {node.values("#1")} are:}
+ \showvalues{#1}
+ \blank
+}
+
+\ShowValues{glue} \ShowValues{style} \ShowValues{math} \ShowValues{pagestate}
+
+\stopsection
+
+\startsection[title={Main text nodes}]
+
+\topicindex {nodes+text}
+
+These are the nodes that comprise actual typesetting commands. A few fields are
+present in all nodes regardless of their type, these are:
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{next} \NC node \NC the next node in a list, or nil \NC \NR
+\NC \type{id} \NC number \NC the node's type (\type {id}) number \NC \NR
+\NC \type{subtype} \NC number \NC the node \type {subtype} identifier \NC \NR
+\LL
+\stoptabulate
+
+The \type {subtype} is sometimes just a dummy entry because not all nodes
+actually use the \type {subtype}, but this way you can be sure that all nodes
+accept it as a valid field name, and that is often handy in node list traversal.
+In the following tables \type {next} and \type {id} are not explicitly mentioned.
+
+Besides these three fields, almost all nodes also have an \type {attr} field, and
+there is a also a field called \type {prev}. That last field is always present,
+but only initialized on explicit request: when the function \type {node.slide}
+is called, it will set up the \type {prev} fields to be a backwards pointer in
+the argument node list. By now most of \TEX's node processing makes sure that the
+\type {prev} nodes are valid but there can be exceptions, especially when the
+internal magic uses a leading \nod {temp} nodes to temporarily store a state.
+
+The \LUAMETATEX\ engine provides a lot of freedom and it is up to the user to
+make sure that the node lists remain sane. There are some safeguards but there
+can be cases where the engine just quits out of frustration. And, of course you
+can make the engine crash.
+
+\startsubsection[title={\nod {hlist} and \nod {vlist} nodes}]
+
+\topicindex {nodes+lists}
+\topicindex {lists}
+
+These lists share fields and subtypes although some subtypes can only occur in
+horizontal lists while others are unique for vertical lists. The possible
+fields are \showfields {hlist}.
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{subtype} \NC number \NC \showsubtypes{list} \NC \NR
+\NC \type{attr} \NC node \NC list of attributes \NC \NR
+\NC \type{width} \NC number \NC the width of the box \NC \NR
+\NC \type{height} \NC number \NC the height of the box \NC \NR
+\NC \type{depth} \NC number \NC the depth of the box \NC \NR
+\NC \type{direction} \NC number \NC the direction of this box, see~\in [dirnodes] \NC \NR
+\NC \type{shift} \NC number \NC a displacement perpendicular to the character
+ (hlist) or line (vlist) progression direction \NC \NR
+\NC \type{glue_order} \NC number \NC a number in the range $[0,4]$, indicating the
+ glue order \NC \NR
+\NC \type{glue_set} \NC number \NC the calculated glue ratio \NC \NR
+\NC \type{glue_sign} \NC number \NC 0 = \type {normal}, 1 = \type {stretching}, 2 =
+ \type {shrinking} \NC \NR
+\NC \type{list} \NC node \NC the first node of the body of this list \NC \NR
+\LL
+\stoptabulate
+
+The \type {orientation}, \type {woffset}, \type {hoffset}, \type {doffset},
+\type {xoffset} and \type {yoffset} fields are special. They can be used to make
+the backend rotate and shift boxes which can be handy in for instance vertical
+typesetting. Because they relate to (and depend on the) the backend they are not
+discussed here (yet).
+
+A warning: never assign a node list to the \type {list} field unless you are sure
+its internal link structure is correct, otherwise an error may result.
+
+Note: the field name \type {head} and \type {list} are both valid. Sometimes it
+makes more sense to refer to a list by \type {head}, sometimes \type {list} makes
+more sense.
+
+\stopsubsection
+
+\startsubsection[title={\nod {rule} nodes}]
+
+\topicindex {nodes+rules}
+\topicindex {rules}
+
+Contrary to traditional \TEX, \LUATEX\ has more \prm {rule} subtypes because we
+also use rules to store reuseable objects and images. User nodes are invisible
+and can be intercepted by a callback. The supported fields are \showfields {rule}.
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{subtype} \NC number \NC \showsubtypes {rule} \NC \NR
+\NC \type{attr} \NC node \NC list of attributes \NC \NR
+\NC \type{width} \NC number \NC the width of the rule where the special value
+ $-1073741824$ is used for \quote {running} glue dimensions \NC \NR
+\NC \type{height} \NC number \NC the height of the rule (can be negative) \NC \NR
+\NC \type{depth} \NC number \NC the depth of the rule (can be negative) \NC \NR
+\NC \type{left} \NC number \NC shift at the left end (also subtracted from width) \NC \NR
+\NC \type{right} \NC number \NC (subtracted from width) \NC \NR
+\NC \type{dir} \NC string \NC the direction of this rule, see~\in[dirnodes] \NC \NR
+\NC \type{index} \NC number \NC an optional index that can be referred to \NC \NR
+\NC \type{transform} \NC number \NC an private variable (also used to specify outline width) \NC \NR
+\LL
+\stoptabulate
+
+The \type {left} and type {right} keys are somewhat special (and experimental).
+When rules are auto adapting to the surrounding box width you can enforce a shift
+to the right by setting \type {left}. The value is also subtracted from the width
+which can be a value set by the engine itself and is not entirely under user
+control. The \type {right} is also subtracted from the width. It all happens in
+the backend so these are not affecting the calculations in the frontend (actually
+the auto settings also happen in the backend). For a vertical rule \type {left}
+affects the height and \type {right} affects the depth. There is no matching
+interface at the \TEX\ end (although we can have more keywords for rules it would
+complicate matters and introduce a speed penalty.) However, you can just
+construct a rule node with \LUA\ and write it to the \TEX\ input. The \type
+{outline} subtype is just a convenient variant and the \type {transform} field
+specifies the width of the outline.
+
+The \type {xoffset} and \type {yoffset} fields are special. They can be used to
+shift rules. Because they relate to (and depend on the) the backend they are not
+discussed here (yet).
+
+\stopsubsection
+
+\startsubsection[title={\nod {ins} nodes}]
+
+\topicindex {nodes+insertions}
+\topicindex {insertions}
+
+This node relates to the \prm {insert} primitive and support the fields: \showfields{ins}.
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{subtype} \NC number \NC the insertion class \NC \NR
+\NC \type{attr} \NC node \NC list of attributes \NC \NR
+\NC \type{cost} \NC number \NC the penalty associated with this insert \NC \NR
+\NC \type{height} \NC number \NC height of the insert \NC \NR
+\NC \type{depth} \NC number \NC depth of the insert \NC \NR
+\NC \type{list} \NC node \NC the first node of the body of this insert \NC \NR
+\LL
+\stoptabulate
+
+There is a set of extra fields that concern the associated glue: \type {width},
+\type {stretch}, \type {stretch_order}, \type {shrink} and \type {shrink_order}.
+These are all numbers.
+
+A warning: never assign a node list to the \type {head} field unless you are sure
+its internal link structure is correct, otherwise an error may result. You can use
+\type {list} instead (often in functions you want to use local variable with similar
+names and both names are equally sensible).
+
+\stopsubsection
+
+\startsubsection[title={\nod {mark} nodes}]
+
+\topicindex {nodes+marks}
+\topicindex {marks}
+
+This one relates to the \prm {mark} primitive and only has a few fields:
+\showfields {mark}.
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{subtype} \NC number \NC unused \NC \NR
+\NC \type{attr} \NC node \NC list of attributes \NC \NR
+\NC \type{class} \NC number \NC the mark class \NC \NR
+\NC \type{mark} \NC table \NC a table representing a token list \NC \NR
+\LL
+\stoptabulate
+
+\stopsubsection
+
+\startsubsection[title={\nod {adjust} nodes}]
+
+\topicindex {nodes+adjust}
+\topicindex {adjust}
+
+This node comes from \prm {vadjust} primitive and has fields: \showfields {adjust}.
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{subtype} \NC number \NC \showsubtypes{adjust} \NC \NR
+\NC \type{attr} \NC node \NC list of attributes \NC \NR
+\NC \type{list} \NC node \NC adjusted material \NC \NR
+\LL
+\stoptabulate
+
+A warning: never assign a node list to the \type {head} field unless you are sure
+its internal link structure is correct, otherwise an error may be the result.
+
+\stopsubsection
+
+\startsubsection[title={\nod {disc} nodes}]
+
+\topicindex {nodes+discretionaries}
+\topicindex {discretionaries}
+
+The \prm {discretionary} and \prm {-}, the \type {-} character but also the
+hyphenation mechanism produces these nodes. The available fields are: \showfields
+{disc}.
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{subtype} \NC number \NC \showsubtypes{disc} \NC \NR
+\NC \type{attr} \NC node \NC list of attributes \NC \NR
+\NC \type{pre} \NC node \NC pointer to the pre|-|break text \NC \NR
+\NC \type{post} \NC node \NC pointer to the post|-|break text \NC \NR
+\NC \type{replace} \NC node \NC pointer to the no|-|break text \NC \NR
+\NC \type{penalty} \NC number \NC the penalty associated with the break, normally
+ \prm {hyphenpenalty} or \prm {exhyphenpenalty} \NC \NR
+\LL
+\stoptabulate
+
+The subtype numbers~4 and~5 belong to the \quote {of-f-ice} explanation given
+elsewhere. These disc nodes are kind of special as at some point they also keep
+information about breakpoints and nested ligatures.
+
+The \type {pre}, \type {post} and \type {replace} fields at the \LUA\ end are in
+fact indirectly accessed and have a \type {prev} pointer that is not \type {nil}.
+This means that when you mess around with the head of these (three) lists, you
+also need to reassign them because that will restore the proper \type {prev}
+pointer, so:
+
+\starttyping
+pre = d.pre
+-- change the list starting with pre
+d.pre = pre
+\stoptyping
+
+Otherwise you can end up with an invalid internal perception of reality and
+\LUAMETATEX\ might even decide to crash on you. It also means that running forward
+over for instance \type {pre} is ok but backward you need to stop at \type {pre}.
+And you definitely must not mess with the node that \type {prev} points to, if
+only because it is not really a node but part of the disc data structure (so
+freeing it again might crash \LUAMETATEX).
+
+\stopsubsection
+
+\startsubsection[title={\nod {math} nodes}]
+
+\topicindex {nodes+math}
+\topicindex {math+nodes}
+
+Math nodes represent the boundaries of a math formula, normally wrapped into
+\type {$} signs. The following fields are available: \showfields {math}.
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{subtype} \NC number \NC \showsubtypes{math} \NC \NR
+\NC \type{attr} \NC node \NC list of attributes \NC \NR
+\NC \type{surround} \NC number \NC width of the \prm {mathsurround} kern \NC \NR
+\NC \type{width} \NC number \NC the horizontal or vertical displacement \NC \NR
+\NC \type{stretch} \NC number \NC extra (positive) displacement or stretch amount \NC \NR
+\NC \type{stretch_order} \NC number \NC factor applied to stretch amount \NC \NR
+\NC \type{shrink} \NC number \NC extra (negative) displacement or shrink amount\NC \NR
+\NC \type{shrink_order} \NC number \NC factor applied to shrink amount \NC \NR
+\LL
+\stoptabulate
+
+The glue fields only kick in when the \type {surround} fields is zero.
+
+\stopsubsection
+
+\startsubsection[title={\nod {glue} nodes}]
+
+\topicindex {nodes+glue}
+\topicindex {glue}
+
+Skips are about the only type of data objects in traditional \TEX\ that are not a
+simple value. They are inserted when \TEX\ sees a space in the text flow but also
+by \prm {hskip} and \prm {vskip}. The structure that represents the glue
+components of a skip internally is called a \nod {glue_spec}. In \LUAMETATEX\ we
+don't use the spec itself but just its values. A glue node has the fields:
+\showfields {glue}.
+
+\starttabulate[|l|l|pA{flushleft,tolerant}|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{subtype} \NC number \NC \showsubtypes{glue} \NC \NR
+\NC \type{attr} \NC node \NC list of attributes \NC \NR
+\NC \type{leader} \NC node \NC pointer to a box or rule for leaders \NC \NR
+\NC \type{width} \NC number \NC the horizontal or vertical displacement \NC \NR
+\NC \type{stretch} \NC number \NC extra (positive) displacement or stretch amount \NC \NR
+\NC \type{stretch_order} \NC number \NC factor applied to stretch amount \NC \NR
+\NC \type{shrink} \NC number \NC extra (negative) displacement or shrink amount\NC \NR
+\NC \type{shrink_order} \NC number \NC factor applied to shrink amount \NC \NR
+\LL
+\stoptabulate
+
+Note that we use the key \type {width} in both horizontal and vertical glue. This
+suits the \TEX\ internals well so we decided to stick to that naming.
+
+The effective width of some glue subtypes depends on the stretch or shrink needed
+to make the encapsulating box fit its dimensions. For instance, in a paragraph
+lines normally have glue representing spaces and these stretch or shrink to make
+the content fit in the available space. The \type {effective_glue} function that
+takes a glue node and a parent (hlist or vlist) returns the effective width of
+that glue item. When you pass \type {true} as third argument the value will be
+rounded.
+
+\stopsubsection
+
+\startsubsection[title={\nod {glue_spec} nodes}]
+
+\topicindex {nodes+glue}
+\topicindex {gluespec}
+
+Internally \LUAMETATEX\ (like its ancestors) also uses nodes to store data that
+is not seen in node lists. For instance the state of expression scanning (\type
+{\dimexpr} etc.) and conditionals (\type {\ifcase} etc.) is also kept in lists of
+nodes. A glue, which has five components, is stored in a node as well, so, where
+most registers store just a number, a skip register (of internal quantity) uses a
+pointer to a glue spec node. It has similar fields as glue nodes: \showfields
+{glue_spec}, which is not surprising because in the past (and other engines than
+\LUATEX) a glue node also has its values stored in a glue spec. This has some
+advantages because often the values are the same, so for instance spacing related
+skips were not resolved immediately but pointed to the current value of a space
+related internal register (like \type {\spaceskip}). But, in \LUATEX\ we do
+resolve these quantities immediately and we put the current values in the glue
+nodes.
+
+\starttabulate[|l|l|pA{flushleft,tolerant}|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{width} \NC number \NC the horizontal or vertical displacement \NC \NR
+\NC \type{stretch} \NC number \NC extra (positive) displacement or stretch amount \NC \NR
+\NC \type{stretch_order} \NC number \NC factor applied to stretch amount \NC \NR
+\NC \type{shrink} \NC number \NC extra (negative) displacement or shrink amount\NC \NR
+\NC \type{shrink_order} \NC number \NC factor applied to shrink amount \NC \NR
+\LL
+\stoptabulate
+
+You will only find these nodes in a few places, for instance when you query an
+internal quantity. In principle we could do without them as we have interfaces
+that use the five numbers instead. For compatibility reasons we keep glue spec
+nodes exposed but this might change in the future.
+
+\stopsubsection
+
+\startsubsection[title={\nod {kern} nodes}]
+
+\topicindex {nodes+kerns}
+\topicindex {kerns}
+
+The \prm {kern} command creates such nodes but for instance the font and math
+machinery can also add them. There are not that many fields: \showfields {kern}.
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{subtype} \NC number \NC \showsubtypes{kern} \NC \NR
+\NC \type{attr} \NC node \NC list of attributes \NC \NR
+\NC \type{kern} \NC number \NC fixed horizontal or vertical advance \NC \NR
+\NC \type{expansion_factor} \NC number \NC multiplier related to hz for font kerns \NC \NR
+\LL
+\stoptabulate
+
+\stopsubsection
+
+\startsubsection[title={\nod {penalty} nodes}]
+
+\topicindex {nodes+penalty}
+\topicindex {penalty}
+
+The \prm {penalty} command is one that generates these nodes. It is one of the
+type of nodes often found in vertical lists. It has the fields: \showfields
+{penalty}.
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{subtype} \NC number \NC \showsubtypes{penalty} \NC \NR
+\NC \type{attr} \NC node \NC list of attributes \NC \NR
+\NC \type{penalty} \NC number \NC the penalty value \NC \NR
+\LL
+\stoptabulate
+
+The subtypes are just informative and \TEX\ itself doesn't use them. When you
+run into an \type {linebreakpenalty} you need to keep in mind that it's a
+accumulation of \type {club}, \type{widow} and other relevant penalties.
+
+\stopsubsection
+
+\startsubsection[title={\nod {glyph} nodes},reference=glyphnodes]
+
+\topicindex {nodes+glyph}
+\topicindex {glyphs}
+
+These are probably the mostly used nodes and although you can push them in the
+current list with for instance \prm {char} \TEX\ will normally do it for you when
+it considers some input to be text. Glyph nodes are relatively large and have many
+fields: \showfields {glyph}.
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{subtype} \NC number \NC bit field \NC \NR
+\NC \type{attr} \NC node \NC list of attributes \NC \NR
+\NC \type{char} \NC number \NC the character index in the font \NC \NR
+\NC \type{font} \NC number \NC the font identifier \NC \NR
+\NC \type{lang} \NC number \NC the language identifier \NC \NR
+\NC \type{left} \NC number \NC the frozen \type {\lefthyphenmnin} value \NC \NR
+\NC \type{right} \NC number \NC the frozen \type {\righthyphenmnin} value \NC \NR
+\NC \type{uchyph} \NC boolean \NC the frozen \prm {uchyph} value \NC \NR
+\NC \type{components} \NC node \NC pointer to ligature components \NC \NR
+\NC \type{xoffset} \NC number \NC a virtual displacement in horizontal direction \NC \NR
+\NC \type{yoffset} \NC number \NC a virtual displacement in vertical direction \NC \NR
+\NC \type{width} \NC number \NC the (original) width of the character \NC \NR
+\NC \type{height} \NC number \NC the (original) height of the character\NC \NR
+\NC \type{depth} \NC number \NC the (original) depth of the character\NC \NR
+\NC \type{expansion_factor} \NC number \NC the to be applied expansion_factor \NC \NR
+\NC \type{data} \NC number \NC a general purpose field for users (we had room for it) \NC \NR
+\LL
+\stoptabulate
+
+The \type {width}, \type {height} and \type {depth} values are read|-|only. The
+\type {expansion_factor} is assigned in the par builder and used in the backend.
+
+A warning: never assign a node list to the components field unless you are sure
+its internal link structure is correct, otherwise an error may be result. Valid
+bits for the \type {subtype} field are:
+
+\starttabulate[|c|l|]
+\DB bit \BC meaning \NC \NR
+\TB
+\NC 0 \NC character \NC \NR
+\NC 1 \NC ligature \NC \NR
+\NC 2 \NC ghost \NC \NR
+\NC 3 \NC left \NC \NR
+\NC 4 \NC right \NC \NR
+\LL
+\stoptabulate
+
+The \type {expansion_factor} has been introduced as part of the separation
+between front- and backend. It is the result of extensive experiments with a more
+efficient implementation of expansion. Early versions of \LUATEX\ already
+replaced multiple instances of fonts in the backend by scaling but contrary to
+\PDFTEX\ in \LUATEX\ we now also got rid of font copies in the frontend and
+replaced them by expansion factors that travel with glyph nodes. Apart from a
+cleaner approach this is also a step towards a better separation between front-
+and backend.
+
+The \type {is_char} function checks if a node is a glyph node with a subtype still
+less than 256. This function can be used to determine if applying font logic to a
+glyph node makes sense. The value \type {nil} gets returned when the node is not
+a glyph, a character number is returned if the node is still tagged as character
+and \type {false} gets returned otherwise. When nil is returned, the id is also
+returned. The \type {is_glyph} variant doesn't check for a subtype being less
+than 256, so it returns either the character value or nil plus the id. These
+helpers are not always faster than separate calls but they sometimes permit
+making more readable tests. The \type {uses_font} helpers takes a node
+and font id and returns true when a glyph or disc node references that font.
+
+\stopsubsection
+
+\startsubsection[title={\nod {boundary} nodes}]
+
+\topicindex {nodes+boundary}
+\topicindex {boundary}
+
+This node relates to the \prm {noboundary}, \prm {boundary}, \prm
+{protrusionboundary} and \prm {wordboundary} primitives. These are small
+nodes: \showfields {boundary} are the only fields.
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{subtype} \NC number \NC \showsubtypes{boundary} \NC \NR
+\NC \type{attr} \NC node \NC list of attributes \NC \NR
+\NC \type{value} \NC number \NC values 0--255 are reserved \NC \NR
+\LL
+\stoptabulate
+
+\stopsubsection
+
+\startsubsection[title={\nod {local_par} nodes}]
+
+\topicindex {nodes+paragraphs}
+\topicindex {paragraphs}
+
+This node is inserted at the start of a paragraph. You should not mess
+too much with this one. Valid fields are: \showfields {local_par}.
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{attr} \NC node \NC list of attributes \NC \NR
+\NC \type{pen_inter} \NC number \NC local interline penalty (from \lpr {localinterlinepenalty}) \NC \NR
+\NC \type{pen_broken} \NC number \NC local broken penalty (from \lpr {localbrokenpenalty}) \NC \NR
+\NC \type{dir} \NC string \NC the direction of this par. see~\in [dirnodes] \NC \NR
+\NC \type{box_left} \NC node \NC the \lpr {localleftbox} \NC \NR
+\NC \type{box_left_width} \NC number \NC width of the \lpr {localleftbox} \NC \NR
+\NC \type{box_right} \NC node \NC the \lpr {localrightbox} \NC \NR
+\NC \type{box_right_width} \NC number \NC width of the \lpr {localrightbox} \NC \NR
+\LL
+\stoptabulate
+
+A warning: never assign a node list to the \type {box_left} or \type {box_right}
+field unless you are sure its internal link structure is correct, otherwise an
+error may result.
+
+\stopsubsection
+
+\startsubsection[title={\nod {dir} nodes},reference=dirnodes]
+
+\topicindex {nodes+direction}
+\topicindex {directions}
+
+Direction nodes mark parts of the running text that need a change of direction
+and the \prm {textdir} command generates them. Again this is a small node, we
+just have \showfields {dir}.
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{subtype} \NC number \NC \showsubtypes{dir} \NC \NR
+\NC \type{attr} \NC node \NC list of attributes \NC \NR
+\NC \type{dir} \NC string \NC the direction (\type {0} = l2r, \type {1} = r2l) \NC \NR
+\NC \type{level} \NC number \NC nesting level of this direction \NC \NR
+\LL
+\stoptabulate
+
+There are only two directions: left|-|to|-|right (\type {0}) and
+right|-|to|-|left (\type {1}). This is different from \LUATEX\ that has four
+directions.
+
+\stopsubsection
+
+\startsubsection[title={\nod {marginkern} nodes}]
+
+\topicindex {nodes+paragraphs}
+\topicindex {paragraphs}
+\topicindex {protrusion}
+
+Margin kerns result from protrusion and have: \showfields {margin_kern}.
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{subtype} \NC number \NC \showsubtypes{marginkern} \NC \NR
+\NC \type{attr} \NC node \NC list of attributes \NC \NR
+\NC \type{width} \NC number \NC the advance of the kern \NC \NR
+\NC \type{glyph} \NC node \NC the glyph to be used \NC \NR
+\LL
+\stoptabulate
+
+\stopsubsection
+
+\startsubsection[title={Whatsits}]
+
+A whatsit node is a real simple one and it only has a subtype. It is even less
+than a user node (which it actually could be) and uses hardly any memory. What
+you do with it it entirely up to you: it's is real minimalistic. You can assign a
+subtype and it has attributes. It is all up to the user how they are handled.
+
+\stopsubsection
+
+\startsubsection[title={Math noads}]
+
+\topicindex {nodes+math}
+\topicindex {math+nodes}
+
+\startsubsubsection[title=The concept]
+
+These are the so||called \quote {noad}s and the nodes that are specifically
+associated with math processing. When you enter a formula, \TEX\ creates a node
+list with regular nodes and noads. Then it hands over the list the math
+processing engine. The result of that is a nodelist without noads. Most of the
+noads contain subnodes so that the list of possible fields is actually quite
+small. Math formulas are both a linked list and a tree. For instance in $e =
+mc^2$ there is a linked list \type {e = m c} but the \type {c} has a superscript
+branch that itself can be a list with branches.
+
+First, there are the objects (the \TEX book calls them \quote {atoms}) that are
+associated with the simple math objects: ord, op, bin, rel, open, close, punct,
+inner, over, under, vcenter. These all have the same fields, and they are combined
+into a single node type with separate subtypes for differentiation: \showfields
+{noad}.
+
+Many object fields in math mode are either simple characters in a specific family
+or math lists or node lists: \type {math_char}, \type {math_text_char}, {sub_box}
+and \type {sub_mlist} and \type {delim}. These are endpoints and therefore the
+\type {next} and \type {prev} fields of these these subnodes are unused.
+
+Some of the more elaborate noads have an option field. The values in this bitset
+are common:
+
+\starttabulate[|l|r|]
+\DB meaning \BC bits \NC \NR
+\TB
+\NC set \NC \type{0x08} \NC \NR
+\NC internal \NC \type{0x00} + \type{0x08} \NC \NR
+\NC internal \NC \type{0x01} + \type{0x08} \NC \NR
+\NC axis \NC \type{0x02} + \type{0x08} \NC \NR
+\NC no axis \NC \type{0x04} + \type{0x08} \NC \NR
+\NC exact \NC \type{0x10} + \type{0x08} \NC \NR
+\NC left \NC \type{0x11} + \type{0x08} \NC \NR
+\NC middle \NC \type{0x12} + \type{0x08} \NC \NR
+\NC right \NC \type{0x14} + \type{0x08} \NC \NR
+\NC no subscript \NC \type{0x21} + \type{0x08} \NC \NR
+\NC no superscript \NC \type{0x22} + \type{0x08} \NC \NR
+\NC no script \NC \type{0x23} + \type{0x08} \NC \NR
+\LL
+\stoptabulate
+
+\stopsubsubsection
+
+\startsubsubsection[title={\nod {math_char} and \nod {math_text_char} subnodes}]
+
+These are the most common ones, as they represent characters, and they both have
+the same fields: \showfields {math_char}.
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{attr} \NC node \NC list of attributes \NC \NR
+\NC \type{char} \NC number \NC the character index \NC \NR
+\NC \type{fam} \NC number \NC the family number \NC \NR
+\LL
+\stoptabulate
+
+The \nod {math_char} is the simplest subnode field, it contains the character and
+family for a single glyph object. The family eventually resolves on a reference
+to a font. The \nod {math_text_char} is a special case that you will not normally
+encounter, it arises temporarily during math list conversion (its sole function
+is to suppress a following italic correction).
+
+\stopsubsubsection
+
+\startsubsubsection[title={\nod {sub_box} and \nod {sub_mlist} subnodes}]
+
+These two subnode types are used for subsidiary list items. For \nod {sub_box},
+the \type {list} points to a \quote {normal} vbox or hbox. For \nod {sub_mlist},
+the \type {list} points to a math list that is yet to be converted. Their fields
+are: \showfields {sub_box}.
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{attr} \NC node \NC list of attributes \NC \NR
+\NC \type{list} \NC node \NC list of nodes \NC \NR
+\LL
+\stoptabulate
+
+A warning: never assign a node list to the \type {list} field unless you are sure
+its internal link structure is correct, otherwise an error is triggered.
+
+\stopsubsubsection
+
+\startsubsubsection[title={\nod {delim} subnodes}]
+
+There is a fifth subnode type that is used exclusively for delimiter fields. As
+before, the \type {next} and \type {prev} fields are unused, but we do have:
+\showfields {delim}.
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{attr} \NC node \NC list of attributes \NC \NR
+\NC \type{small_char} \NC number \NC character index of base character \NC \NR
+\NC \type{small_fam} \NC number \NC family number of base character \NC \NR
+\NC \type{large_char} \NC number \NC character index of next larger character \NC \NR
+\NC \type{large_fam} \NC number \NC family number of next larger character \NC \NR
+\LL
+\stoptabulate
+
+The fields \type {large_char} and \type {large_fam} can be zero, in that case the
+font that is set for the \type {small_fam} is expected to provide the large
+version as an extension to the \type {small_char}.
+
+\stopsubsubsection
+
+\startsubsubsection[title={simple \nod {noad} nodes}]
+
+In these noads, the \type {nucleus}, \type {sub} and \type {sup} fields can
+branch of. Its fields are: \showfields {noad}.
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{subtype} \NC number \NC \showsubtypes{noad} \NC \NR
+\NC \type{attr} \NC node \NC list of attributes \NC \NR
+\NC \type{nucleus} \NC kernel node \NC base \NC \NR
+\NC \type{sub} \NC kernel node \NC subscript \NC \NR
+\NC \type{sup} \NC kernel node \NC superscript \NC \NR
+\NC \type{options} \NC number \NC bitset of rendering options \NC \NR
+\LL
+\stoptabulate
+
+\stopsubsubsection
+
+\startsubsubsection[title={\nod {accent} nodes}]
+
+Accent nodes deal with stuff on top or below a math constructs. They support:
+\showfields {accent}.
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{subtype} \NC number \NC \showsubtypes{accent} \NC \NR
+\NC \type{nucleus} \NC kernel node \NC base \NC \NR
+\NC \type{sub} \NC kernel node \NC subscript \NC \NR
+\NC \type{sup} \NC kernel node \NC superscript \NC \NR
+\NC \type{accent} \NC kernel node \NC top accent \NC \NR
+\NC \type{bot_accent} \NC kernel node \NC bottom accent \NC \NR
+\NC \type{fraction} \NC number \NC larger step criterium (divided by 1000) \NC \NR
+\LL
+\stoptabulate
+
+\stopsubsubsection
+
+\startsubsubsection[title={\nod {style} nodes}]
+
+These nodes are signals to switch to another math style. They are quite simple:
+\showfields {style}. Currently the subtype is actually used to store the style
+but don't rely on that for the future. Fields are: \showfields {style}.
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{style} \NC string \NC contains the style \NC \NR
+\LL
+\stoptabulate
+
+Valid styles are: \showvalues{style}.
+
+\stopsubsubsection
+
+\startsubsubsection[title={\nod {parameter} nodes}]
+
+These nodes are used to (locally) set math parameters: \showfields {parameter}.
+Fields are: \showfields {parameter}.
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{style} \NC string \NC contains the style \NC \NR
+\NC \type{name} \NC string \NC defines the parameter \NC \NR
+\NC \type{value} \NC number \NC holds the value, in case of a muglue multiple \NC \NR
+\LL
+\stoptabulate
+
+\stopsubsubsection
+
+\startsubsubsection[title={\nod {choice} nodes}]
+
+Of its fields \showfields {choice} most are lists. Warning: never assign a node
+list unless you are sure its internal link structure is correct, otherwise an
+error can occur.
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{attr} \NC node \NC list of attributes \NC \NR
+\NC \type{display} \NC node \NC list of display size alternatives \NC \NR
+\NC \type{text} \NC node \NC list of text size alternatives \NC \NR
+\NC \type{script} \NC node \NC list of scriptsize alternatives \NC \NR
+\NC \type{scriptscript} \NC node \NC list of scriptscriptsize alternatives \NC \NR
+\LL
+\stoptabulate
+
+\stopsubsubsection
+
+\startsubsubsection[title={\nod {radical} nodes}]
+
+Radical nodes are the most complex as they deal with scripts as well as
+constructed large symbols. Many fields: \showfields {radical}. Warning: never
+assign a node list to the \type {nucleus}, \type {sub}, \type {sup}, \type
+{left}, or \type {degree} field unless you are sure its internal link structure
+is correct, otherwise an error can be triggered.
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{subtype} \NC number \NC \showsubtypes{radical} \NC \NR
+\NC \type{attr} \NC node \NC list of attributes \NC \NR
+\NC \type{nucleus} \NC kernel node \NC base \NC \NR
+\NC \type{sub} \NC kernel node \NC subscript \NC \NR
+\NC \type{sup} \NC kernel node \NC superscript \NC \NR
+\NC \type{left} \NC delimiter node \NC \NC \NR
+\NC \type{degree} \NC kernel node \NC only set by \lpr {Uroot} \NC \NR
+\NC \type{width} \NC number \NC required width \NC \NR
+\NC \type{options} \NC number \NC bitset of rendering options \NC \NR
+\LL
+\stoptabulate
+
+\stopsubsubsection
+
+\startsubsubsection[title={\nod {fraction} nodes}]
+
+Fraction nodes are also used for delimited cases, hence the \type {left} and
+\type {right} fields among: \showfields {fraction}.
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{attr} \NC node \NC list of attributes \NC \NR
+\NC \type{width} \NC number \NC (optional) width of the fraction \NC \NR
+\NC \type{num} \NC kernel node \NC numerator \NC \NR
+\NC \type{denom} \NC kernel node \NC denominator \NC \NR
+\NC \type{left} \NC delimiter node \NC left side symbol \NC \NR
+\NC \type{right} \NC delimiter node \NC right side symbol \NC \NR
+\NC \type{middle} \NC delimiter node \NC middle symbol \NC \NR
+\NC \type{options} \NC number \NC bitset of rendering options \NC \NR
+\LL
+\stoptabulate
+
+Warning: never assign a node list to the \type {num}, or \type {denom} field
+unless you are sure its internal link structure is correct, otherwise an error
+can result.
+
+\stopsubsubsection
+
+\startsubsubsection[title={\nod {fence} nodes}]
+
+Fence nodes come in pairs but either one can be a dummy (this period driven empty
+fence). Fields are: \showfields {fence}. Some of these fields are used by the
+renderer and might get adapted in the process.
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{subtype} \NC number \NC \showsubtypes{fence} \NC \NR
+\NC \type{attr} \NC node \NC list of attributes \NC \NR
+\NC \type{delim} \NC delimiter node \NC delimiter specification \NC \NR
+\NC \type{italic} \NC number \NC italic correction \NC \NR
+\NC \type{height} \NC number \NC required height \NC \NR
+\NC \type{depth} \NC number \NC required depth \NC \NR
+\NC \type{options} \NC number \NC bitset of rendering options \NC \NR
+\NC \type{class} \NC number \NC spacing related class \NC \NR
+\LL
+\stoptabulate
+
+\stopsubsubsection
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title={The \type {node} library}][library=node]
+
+\startsubsection[title={Introduction}]
+
+The \type {node} library provides methods that facilitate dealing with (lists of)
+nodes and their values. They allow you to create, alter, copy, delete, and insert
+node, the core objects within the typesetter. Nodes are represented in \LUA\ as
+userdata. The various parts within a node can be accessed using named fields.
+
+Each node has at least the three fields \type {next}, \type {id}, and \type
+{subtype}. The other available fields depend on the \type {id}.
+
+\startitemize[intro]
+
+\startitem
+ The \type {next} field returns the userdata object for the next node in a
+ linked list of nodes, or \type {nil}, if there is no next node.
+\stopitem
+
+\startitem
+ The \type {id} indicates \TEX's \quote{node type}. The field \type {id} has a
+ numeric value for efficiency reasons, but some of the library functions also
+ accept a string value instead of \type {id}.
+\stopitem
+
+\startitem
+ The \type {subtype} is another number. It often gives further information
+ about a node of a particular \type {id}.
+\stopitem
+
+\stopitemize
+
+% Support for \nod {unset} (alignment) nodes is partial: they can be queried and
+% modified from \LUA\ code, but not created.
+
+Nodes can be compared to each other, but: you are actually comparing indices into
+the node memory. This means that equality tests can only be trusted under very
+limited conditions. It will not work correctly in any situation where one of the
+two nodes has been freed and|/|or reallocated: in that case, there will be false
+positives. The general approach to a node related callback is as follows:
+
+\startitemize
+
+\startitem
+ Assume that the node list that you get is okay and properly double linked.
+ If for some reason the links are not right, you can apply \type {node.slide}
+ to the list.
+\stopitem
+
+\startitem
+ When you insert a node, make sure you use a previously removed one, a new one
+ or a copy. Don't simply inject the same node twice.
+\stopitem
+
+\startitem
+ When you remove a node, make sure that when this is permanent, you also free
+ the node or list. When you free a node its components are checked and when
+ they are nodes themselves they are also freed.
+\stopitem
+
+\startitem
+ Although you can fool the system, normally you will trigger an error when you
+ try to copy a nonexisting node, or free an already freed node. There is some
+ overhead involved in this checking but the current compromise is acceptable.
+\stopitem
+
+\startitem
+ When you're done, pass back (if needed) the result. It's your responsibility
+ to make sure that the list is properly linked (you can play safe and again
+ apply \type {node.slide}. In principle you can put nodes in a list that are
+ not acceptable in the following up actions. Some nodes get ignored, others
+ will trigger an error, and sometimes the engine will just crash.
+\stopitem
+
+\stopitemize
+
+So, from the above it will be clear then memory management of nodes has to be
+done explicitly by the user. Nodes are not \quote {seen} by the \LUA\ garbage
+collector, so you have to call the node freeing functions yourself when you are
+no longer in need of a node (list). Nodes form linked lists without reference
+counting, so you have to be careful that when control returns back to \LUATEX\
+itself, you have not deleted nodes that are still referenced from a \type {next}
+pointer elsewhere, and that you did not create nodes that are referenced more
+than once. Normally the setters and getters handle this for you.
+
+A good example are discretionary nodes that themselves have three sublists.
+Internally they use special pointers, but the user never sees them because when
+you query them or set fields, this property is hidden and taken care of. You just
+see a list. But, when you mess with these sub lists it is your responsibility
+that it only contains nodes that are permitted in a discretionary.
+
+There are statistics available with regards to the allocated node memory, which
+can be handy for tracing. Normally the amount of used nodes is not that large.
+Typesetting a page can involve thousands of them but most are freed when the page
+has been shipped out. Compared to other programs, node memory usage is not that
+excessive. So, if for some reason your application leaks nodes, if at the end of
+your run you lost as few hundred it's not a real problem. In fact, if you created
+boxes and made copies but not flushed them for good reason, your run will for
+sure end with used nodes and the statistics will mention that. The same is true
+for attributes and skips (glue spec nodes): keeping the current state involves
+using nodes.
+
+\stopsubsection
+
+\startsubsection[title={Housekeeping}]
+
+\startsubsubsection[title={\type {types}}]
+
+\libindex {types}
+
+This function returns an array that maps node id numbers to node type strings,
+providing an overview of the possible top|-|level \type {id} types.
+
+\startfunctioncall
+<table> t = node.types()
+\stopfunctioncall
+
+When we issue this command, we get a table. The currently visible types are
+\inlineluavalue { node.types() } where the numbers are the internal identifiers.
+Only those nodes are reported that make sense to users so there can be gaps in
+the range of numbers.
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {id} and \type {type}}]
+
+\libindex{id}
+\libindex{type}
+
+This converts a single type name to its internal numeric representation.
+
+\startfunctioncall
+<number> id = node.id(<string> type)
+\stopfunctioncall
+
+The \type {node.id("glyph")} command returns the number \inlineluavalue { node.id
+("glyph") } and \type {node.id("hlist")} returns \inlineluavalue { node.id
+("hlist") } where the numbers don't relate to importance or some ordering; they
+just appear in the order that is handy for the engine. Commands like this are
+rather optimized so performance should be ok but you can of course always store
+the id in a \LUA\ number.
+
+The reverse operation is: \type {node.type} If the argument is a number, then the
+next function converts an internal numeric representation to an external string
+representation. Otherwise, it will return the string \type {node} if the object
+represents a node, and \type {nil} otherwise.
+
+\startfunctioncall
+<string> type = node.type(<any> n)
+\stopfunctioncall
+
+The \type {node.type(4)} command returns the string \inlineluavalue { node.type
+(4) } and \type {node.id(99)} returns \inlineluavalue { node.id (99) } because
+there is no node with that id.
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {fields} and \type {has_field}}]
+
+\libindex {fields}
+\libindex {has_field}
+
+This function returns an indexed table with valid field names for a particular
+type of node.
+
+\startfunctioncall
+<table> t = node.fields(<number|string> id)
+\stopfunctioncall
+
+The function accepts a string or number, so \typ {node.fields ("glyph")} returns
+\inlineluavalue { node.fields ("glyph") } and \typ {node.fields (12)} gives
+\inlineluavalue { node.fields (12) }.
+
+The \type {has_field} function returns a boolean that is only true if \type {n}
+is actually a node, and it has the field.
+
+\startfunctioncall
+<boolean> t = node.has_field(<node> n, <string> field)
+\stopfunctioncall
+
+This function probably is not that useful but some nodes don't have a \type
+{subtype}, \type {attr} or \type {prev} field and this is a way to test for that.
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {is_node}}]
+
+\topicindex {nodes+functions}
+
+\libindex {is_node}
+
+\startfunctioncall
+<boolean|integer> t = node.is_node(<any> item)
+\stopfunctioncall
+
+This function returns a number (the internal index of the node) if the argument
+is a userdata object of type \type {<node>} and false when no node is passed.
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {new}}]
+
+\libindex{new}
+
+The \type {new} function creates a new node. All its fields are initialized to
+either zero or \type {nil} except for \type {id} and \type {subtype}. Instead of
+numbers you can also use strings (names). If you pass a second argument the
+subtype will be set too.
+
+\startfunctioncall
+<node> n = node.new(<number|string> id)
+<node> n = node.new(<number|string> id, <number|string> subtype)
+\stopfunctioncall
+
+As already has been mentioned, you are responsible for making sure that nodes
+created this way are used only once, and are freed when you don't pass them
+back somehow.
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {free}, \type {flush_node} and \type {flush_list}}]
+
+\libindex{free}
+\libindex{flush_node}
+\libindex{flush_list}
+
+The next one frees node \type {n} from \TEX's memory. Be careful: no checks are
+done on whether this node is still pointed to from a register or some \type
+{next} field: it is up to you to make sure that the internal data structures
+remain correct. Fields that point to nodes or lists are flushed too. So, when
+you used their content for something else you need to set them to nil first.
+
+\startfunctioncall
+<node> next = node.free(<node> n)
+flush_node(<node> n)
+\stopfunctioncall
+
+The \type {free} function returns the next field of the freed node, while the
+\type {flush_node} alternative returns nothing.
+
+A list starting with node \type {n} can be flushed from \TEX's memory too. Be
+careful: no checks are done on whether any of these nodes is still pointed to
+from a register or some \type {next} field: it is up to you to make sure that the
+internal data structures remain correct.
+
+\startfunctioncall
+node.flush_list(<node> n)
+\stopfunctioncall
+
+When you free for instance a discretionary node, \type {flush_list} is applied to
+the \type {pre}, \type {post}, \type {replace} so you don't need to do that
+yourself. Assigning them \type {nil} won't free those lists!
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {copy} and \type {copy_list}}]
+
+\libindex{copy}
+\libindex{copy_list}
+
+This creates a deep copy of node \type {n}, including all nested lists as in the case
+of a hlist or vlist node. Only the \type {next} field is not copied.
+
+\startfunctioncall
+<node> m = node.copy(<node> n)
+\stopfunctioncall
+
+A deep copy of the node list that starts at \type {n} can be created too. If
+\type {m} is also given, the copy stops just before node \type {m}.
+
+\startfunctioncall
+<node> m = node.copy_list(<node> n)
+<node> m = node.copy_list(<node> n, <node> m)
+\stopfunctioncall
+
+Note that you cannot copy attribute lists this way. However, there is normally no
+need to copy attribute lists as when you do assignments to the \type {attr} field
+or make changes to specific attributes, the needed copying and freeing takes
+place automatically. When you change a value of an attribute {\em in} a list, it will
+affect all the nodes that share that list.
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {write}}]
+
+\libindex {write}
+
+\startfunctioncall
+node.write(<node> n)
+\stopfunctioncall
+
+This function will append a node list to \TEX's \quote {current list}. The node
+list is not deep|-|copied! There is no error checking either! You might need to
+enforce horizontal mode in order for this to work as expected.
+
+\stopsubsubsection
+
+\stopsubsection
+
+\startsubsection[title={Manipulating lists}]
+
+\startsubsubsection[title={\type {slide}}]
+
+\libindex {slide}
+
+This helper makes sure that the node list is double linked and returns the found
+tail node.
+
+\startfunctioncall
+<node> tail = node.slide(<node> n)
+\stopfunctioncall
+
+After some callbacks automatic sliding takes place. This feature can be turned
+off with \type {node.fix_node_lists(false)} but you better make sure then that
+you don't mess up lists. In most cases \TEX\ itself only uses \type {next}
+pointers but your other callbacks might expect proper \type {prev} pointers too.
+Future versions of \LUATEX\ can add more checking but this will not influence
+usage.
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {tail}}]
+
+\libindex {tail}
+
+\startfunctioncall
+<node> m = node.tail(<node> n)
+\stopfunctioncall
+
+Returns the last node of the node list that starts at \type {n}.
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {length} and \type {count}}]
+
+\libindex {length}
+\libindex {count}
+
+\startfunctioncall
+<number> i = node.length(<node> n)
+<number> i = node.length(<node> n, <node> m)
+\stopfunctioncall
+
+Returns the number of nodes contained in the node list that starts at \type {n}.
+If \type {m} is also supplied it stops at \type {m} instead of at the end of the
+list. The node \type {m} is not counted.
+
+\startfunctioncall
+<number> i = node.count(<number> id, <node> n)
+<number> i = node.count(<number> id, <node> n, <node> m)
+\stopfunctioncall
+
+Returns the number of nodes contained in the node list that starts at \type {n}
+that have a matching \type {id} field. If \type {m} is also supplied, counting
+stops at \type {m} instead of at the end of the list. The node \type {m} is not
+counted. This function also accept string \type {id}'s.
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {remove}}]
+
+\libindex {remove}
+
+\startfunctioncall
+<node> head, current, removed =
+ node.remove(<node> head, <node> current)
+<node> head, current =
+ node.remove(<node> head, <node> current, <boolean> true)
+\stopfunctioncall
+
+This function removes the node \type {current} from the list following \type
+{head}. It is your responsibility to make sure it is really part of that list.
+The return values are the new \type {head} and \type {current} nodes. The
+returned \type {current} is the node following the \type {current} in the calling
+argument, and is only passed back as a convenience (or \type {nil}, if there is
+no such node). The returned \type {head} is more important, because if the
+function is called with \type {current} equal to \type {head}, it will be
+changed. When the third argument is passed, the node is freed.
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {insert_before}}]
+
+\libindex {insert_before}
+
+\startfunctioncall
+<node> head, new = node.insert_before(<node> head, <node> current, <node> new)
+\stopfunctioncall
+
+This function inserts the node \type {new} before \type {current} into the list
+following \type {head}. It is your responsibility to make sure that \type
+{current} is really part of that list. The return values are the (potentially
+mutated) \type {head} and the node \type {new}, set up to be part of the list
+(with correct \type {next} field). If \type {head} is initially \type {nil}, it
+will become \type {new}.
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {insert_after}}]
+
+\libindex {insert_after}
+
+\startfunctioncall
+<node> head, new = node.insert_after(<node> head, <node> current, <node> new)
+\stopfunctioncall
+
+This function inserts the node \type {new} after \type {current} into the list
+following \type {head}. It is your responsibility to make sure that \type
+{current} is really part of that list. The return values are the \type {head} and
+the node \type {new}, set up to be part of the list (with correct \type {next}
+field). If \type {head} is initially \type {nil}, it will become \type {new}.
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {last_node}}]
+
+\libindex {last_node}
+
+\startfunctioncall
+<node> n = node.last_node()
+\stopfunctioncall
+
+This function pops the last node from \TEX's \quote{current list}. It returns
+that node, or \type {nil} if the current list is empty.
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {traverse}}]
+
+\libindex {traverse}
+
+\startfunctioncall
+<node> t, id, subtype = node.traverse(<node> n)
+\stopfunctioncall
+
+This is a \LUA\ iterator that loops over the node list that starts at \type {n}.
+Typically code looks like this:
+
+\starttyping
+for n in node.traverse(head) do
+ ...
+end
+\stoptyping
+
+is functionally equivalent to:
+
+\starttyping
+do
+ local n
+ local function f (head,var)
+ local t
+ if var == nil then
+ t = head
+ else
+ t = var.next
+ end
+ return t
+ end
+ while true do
+ n = f (head, n)
+ if n == nil then break end
+ ...
+ end
+end
+\stoptyping
+
+It should be clear from the definition of the function \type {f} that even though
+it is possible to add or remove nodes from the node list while traversing, you
+have to take great care to make sure all the \type {next} (and \type {prev})
+pointers remain valid.
+
+If the above is unclear to you, see the section \quote {For Statement} in the
+\LUA\ Reference Manual.
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {traverse_id}}]
+
+\libindex {traverse_id}
+
+\startfunctioncall
+<node> t, subtype = node.traverse_id(<number> id, <node> n)
+\stopfunctioncall
+
+This is an iterator that loops over all the nodes in the list that starts at
+\type {n} that have a matching \type {id} field.
+
+See the previous section for details. The change is in the local function \type
+{f}, which now does an extra while loop checking against the upvalue \type {id}:
+
+\starttyping
+ local function f(head,var)
+ local t
+ if var == nil then
+ t = head
+ else
+ t = var.next
+ end
+ while not t.id == id do
+ t = t.next
+ end
+ return t
+ end
+\stoptyping
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {traverse_char} and \type {traverse_glyph}}]
+
+\libindex {traverse_char}
+\libindex {traverse_glyph}
+
+The \type{traverse_char} iterator loops over the \nod {glyph} nodes in a list.
+Only nodes with a subtype less than 256 are seen.
+
+\startfunctioncall
+<node> n, font, char = node.traverse_char(<node> n)
+\stopfunctioncall
+
+The \type{traverse_glyph} iterator loops over a list and returns the list and
+filters all glyphs:
+
+\startfunctioncall
+<node> n, font, char = node.traverse_glyph(<node> n)
+\stopfunctioncall
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {traverse_list}}]
+
+\libindex {traverse_list}
+
+This iterator loops over the \nod {hlist} and \nod {vlist} nodes in a list.
+
+\startfunctioncall
+<node> n, id, subtype, list = node.traverse_list(<node> n)
+\stopfunctioncall
+
+The four return values can save some time compared to fetching these fields but
+in practice you seldom need them all. So consider it a (side effect of
+experimental) convenience.
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {find_node}}]
+
+\libindex {find_node}
+
+This helper returns the location of the first match at or after node \type {n}:
+
+\startfunctioncall
+<node> n = node.find_node(<node> n, <integer> subtype)
+<node> n, subtype = node.find_node(<node> n)
+\stopfunctioncall
+
+\stopsubsubsection
+
+
+\stopsubsection
+
+\startsubsection[title={Glue handling}][library=node]
+
+\startsubsubsection[title={\type {setglue}}]
+
+\libindex {setglue}
+
+You can set the properties of a glue in one go. If you pass no values, the glue
+will become a zero glue.
+
+\startfunctioncall
+node.setglue(<node> n)
+node.setglue(<node> n,width,stretch,shrink,stretch_order,shrink_order)
+\stopfunctioncall
+
+When you pass values, only arguments that are numbers are assigned so
+
+\starttyping
+node.setglue(n,655360,false,65536)
+\stoptyping
+
+will only adapt the width and shrink.
+
+When a list node is passed, you set the glue, order and sign instead.
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {getglue}}]
+
+\libindex {getglue}
+
+The next call will return 5 values or nothing when no glue is passed.
+
+\startfunctioncall
+<integer> width, <integer> stretch, <integer> shrink, <integer> stretch_order,
+ <integer> shrink_order = node.getglue(<node> n)
+\stopfunctioncall
+
+When the second argument is false, only the width is returned (this is consistent
+with \type {tex.get}).
+
+When a list node is passed, you get back the glue that is set, the order of that
+glue and the sign.
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {is_zero_glue}}]
+
+\libindex {is_zero_glue}
+
+This function returns \type {true} when the width, stretch and shrink properties
+are zero.
+
+\startfunctioncall
+<boolean> isglue = node.is_zero_glue(<node> n)
+\stopfunctioncall
+
+\stopsubsubsection
+
+\stopsubsection
+
+\startsubsection[title={Attribute handling}][library=node]
+
+\startsubsubsection[title={Attributes}]
+
+\topicindex {attributes}
+
+Assignments to attributes registers result in assigning lists with set attributes
+to nodes and the implementation is non|-|trivial because the value that is
+attached to a node is essentially a (sorted) sparse array of key|-|value pairs.
+It is generally easiest to deal with attribute lists and attributes by using the
+dedicated functions in the \type {node} library.
+
+\stopsubsubsection
+
+\startsubsubsection[title={\nod {attribute_list} nodes}]
+
+\topicindex {nodes+attributes}
+
+An \type {attribute_list} item is used as a head pointer for a list of attribute
+items. It has only one user|-|visible field:
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{next} \NC node \NC pointer to the first attribute \NC \NR
+\LL
+\stoptabulate
+
+\stopsubsubsection
+
+\startsubsubsection[title={\nod {attr} nodes}]
+
+A normal node's attribute field will point to an item of type \nod
+{attribute_list}, and the \type {next} field in that item will point to the first
+defined \quote {attribute} item, whose \type {next} will point to the second
+\quote {attribute} item, etc.
+
+\starttabulate[|l|l|p|]
+\DB field \BC type \BC explanation \NC \NR
+\TB
+\NC \type{next} \NC node \NC pointer to the next attribute \NC \NR
+\NC \type{number} \NC number \NC the attribute type id \NC \NR
+\NC \type{value} \NC number \NC the attribute value \NC \NR
+\LL
+\stoptabulate
+
+As mentioned it's better to use the official helpers rather than edit these
+fields directly. For instance the \type {prev} field is used for other purposes
+and there is no double linked list.
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {current_attr}}]
+
+\libindex{current_attr}
+
+This returns the currently active list of attributes, if there is one.
+
+\startfunctioncall
+<node> m = node.current_attr()
+\stopfunctioncall
+
+The intended usage of \type {current_attr} is as follows:
+
+\starttyping
+local x1 = node.new("glyph")
+x1.attr = node.current_attr()
+local x2 = node.new("glyph")
+x2.attr = node.current_attr()
+\stoptyping
+
+or:
+
+\starttyping
+local x1 = node.new("glyph")
+local x2 = node.new("glyph")
+local ca = node.current_attr()
+x1.attr = ca
+x2.attr = ca
+\stoptyping
+
+The attribute lists are ref counted and the assignment takes care of incrementing
+the refcount. You cannot expect the value \type {ca} to be valid any more when
+you assign attributes (using \type {tex.setattribute}) or when control has been
+passed back to \TEX.
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {has_attribute}}]
+
+\libindex {has_attribute}
+
+\startfunctioncall
+<number> v = node.has_attribute(<node> n, <number> id)
+<number> v = node.has_attribute(<node> n, <number> id, <number> val)
+\stopfunctioncall
+
+Tests if a node has the attribute with number \type {id} set. If \type {val} is
+also supplied, also tests if the value matches \type {val}. It returns the value,
+or, if no match is found, \type {nil}.
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {get_attribute}}]
+
+\libindex {get_attribute}
+
+\startfunctioncall
+<number> v = node.get_attribute(<node> n, <number> id)
+\stopfunctioncall
+
+Tests if a node has an attribute with number \type {id} set. It returns the
+value, or, if no match is found, \type {nil}. If no \type {id} is given then the
+zero attributes is assumed.
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {find_attribute}}]
+
+\libindex {find_attribute}
+
+\startfunctioncall
+<number> v, <node> n = node.find_attribute(<node> n, <number> id)
+\stopfunctioncall
+
+Finds the first node that has attribute with number \type {id} set. It returns
+the value and the node if there is a match and otherwise nothing.
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {set_attribute}}]
+
+\libindex {set_attribute}
+
+\startfunctioncall
+node.set_attribute(<node> n, <number> id, <number> val)
+\stopfunctioncall
+
+Sets the attribute with number \type {id} to the value \type {val}. Duplicate
+assignments are ignored.
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {unset_attribute}}]
+
+\libindex {unset_attribute}
+
+\startfunctioncall
+<number> v =
+ node.unset_attribute(<node> n, <number> id)
+<number> v =
+ node.unset_attribute(<node> n, <number> id, <number> val)
+\stopfunctioncall
+
+Unsets the attribute with number \type {id}. If \type {val} is also supplied, it
+will only perform this operation if the value matches \type {val}. Missing
+attributes or attribute|-|value pairs are ignored.
+
+If the attribute was actually deleted, returns its old value. Otherwise, returns
+\type {nil}.
+
+\stopsubsubsection
+
+\stopsubsection
+
+\startsubsection[title={Glyph handling}][library=node]
+
+\startsubsubsection[title={\type {first_glyph}}]
+
+\libindex {first_glyph}
+
+\startfunctioncall
+<node> n = node.first_glyph(<node> n)
+<node> n = node.first_glyph(<node> n, <node> m)
+\stopfunctioncall
+
+Returns the first node in the list starting at \type {n} that is a glyph node
+with a subtype indicating it is a glyph, or \type {nil}. If \type {m} is given,
+processing stops at (but including) that node, otherwise processing stops at the
+end of the list.
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {is_char} and \type {is_glyph}}]
+
+\libindex {is_char}
+\libindex {is_glyph}
+
+The subtype of a glyph node signals if the glyph is already turned into a character reference
+or not.
+
+\startfunctioncall
+<boolean> b = node.is_char(<node> n)
+<boolean> b = node.is_glyph(<node> n)
+\stopfunctioncall
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {has_glyph}}]
+
+\libindex {has_glyph}
+
+This function returns the first glyph or disc node in the given list:
+
+\startfunctioncall
+<node> n = node.has_glyph(<node> n)
+\stopfunctioncall
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {ligaturing}}]
+
+\libindex {ligaturing}
+
+\startfunctioncall
+<node> h, <node> t, <boolean> success = node.ligaturing(<node> n)
+<node> h, <node> t, <boolean> success = node.ligaturing(<node> n, <node> m)
+\stopfunctioncall
+
+Apply \TEX-style ligaturing to the specified nodelist. The tail node \type {m} is
+optional. The two returned nodes \type {h} and \type {t} are the new head and
+tail (both \type {n} and \type {m} can change into a new ligature).
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {kerning}}]
+
+\libindex {kerning}
+
+\startfunctioncall
+<node> h, <node> t, <boolean> success = node.kerning(<node> n)
+<node> h, <node> t, <boolean> success = node.kerning(<node> n, <node> m)
+\stopfunctioncall
+
+Apply \TEX|-|style kerning to the specified node list. The tail node \type {m} is
+optional. The two returned nodes \type {h} and \type {t} are the head and tail
+(either one of these can be an inserted kern node, because special kernings with
+word boundaries are possible).
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {unprotect_glyph[s]}}]
+
+\libindex {unprotect_glyphs}
+\libindex {unprotect_glyph}
+
+\startfunctioncall
+node.unprotect_glyph(<node> n)
+node.unprotect_glyphs(<node> n,[<node> n])
+\stopfunctioncall
+
+Subtracts 256 from all glyph node subtypes. This and the next function are
+helpers to convert from \type {characters} to \type {glyphs} during node
+processing. The second argument is optional and indicates the end of a range.
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {protect_glyph[s]}}]
+
+\libindex {protect_glyphs}
+\libindex {protect_glyph}
+
+\startfunctioncall
+node.protect_glyph(<node> n)
+node.protect_glyphs(<node> n,[<node> n])
+\stopfunctioncall
+
+Adds 256 to all glyph node subtypes in the node list starting at \type {n},
+except that if the value is 1, it adds only 255. The special handling of 1 means
+that \type {characters} will become \type {glyphs} after subtraction of 256. A
+single character can be marked by the singular call. The second argument is
+optional and indicates the end of a range.
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {protrusion_skippable}}]
+
+\libindex {protrusion_skippable}
+
+\startfunctioncall
+<boolean> skippable = node.protrusion_skippable(<node> n)
+\stopfunctioncall
+
+Returns \type {true} if, for the purpose of line boundary discovery when
+character protrusion is active, this node can be skipped.
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {check_discretionary}, \type {check_discretionaries}}]
+
+\libindex{check_discretionary}
+\libindex{check_discretionaries}
+
+When you fool around with disc nodes you need to be aware of the fact that they
+have a special internal data structure. As long as you reassign the fields when
+you have extended the lists it's ok because then the tail pointers get updated,
+but when you add to list without reassigning you might end up in trouble when
+the linebreak routine kicks in. You can call this function to check the list for
+issues with disc nodes.
+
+\startfunctioncall
+node.check_discretionary(<node> n)
+node.check_discretionaries(<node> head)
+\stopfunctioncall
+
+The plural variant runs over all disc nodes in a list, the singular variant
+checks one node only (it also checks if the node is a disc node).
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {flatten_discretionaries}}]
+
+\libindex {flatten_discretionaries}
+
+This function will remove the discretionaries in the list and inject the replace
+field when set.
+
+\startfunctioncall
+<node> head, count = node.flatten_discretionaries(<node> n)
+\stopfunctioncall
+
+\stopsubsubsection
+
+\stopsubsection
+
+\startsubsection[title={Packaging}][library=node]
+
+\startsubsubsection[title={\type {hpack}}]
+
+\libindex {hpack}
+
+This function creates a new hlist by packaging the list that begins at node \type
+{n} into a horizontal box. With only a single argument, this box is created using
+the natural width of its components. In the three argument form, \type {info}
+must be either \type {additional} or \type {exactly}, and \type {w} is the
+additional (\type {\hbox spread}) or exact (\type {\hbox to}) width to be used.
+The second return value is the badness of the generated box.
+
+\startfunctioncall
+<node> h, <number> b =
+ node.hpack(<node> n)
+<node> h, <number> b =
+ node.hpack(<node> n, <number> w, <string> info)
+<node> h, <number> b =
+ node.hpack(<node> n, <number> w, <string> info, <string> dir)
+\stopfunctioncall
+
+Caveat: there can be unexpected side|-|effects to this function, like updating
+some of the \prm {marks} and \type {\inserts}. Also note that the content of
+\type {h} is the original node list \type {n}: if you call \type {node.free(h)}
+you will also free the node list itself, unless you explicitly set the \type
+{list} field to \type {nil} beforehand. And in a similar way, calling \type
+{node.free(n)} will invalidate \type {h} as well!
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {vpack}}]
+
+\libindex {vpack}
+
+This function creates a new vlist by packaging the list that begins at node \type
+{n} into a vertical box. With only a single argument, this box is created using
+the natural height of its components. In the three argument form, \type {info}
+must be either \type {additional} or \type {exactly}, and \type {w} is the
+additional (\type {\vbox spread}) or exact (\type {\vbox to}) height to be used.
+
+\startfunctioncall
+<node> h, <number> b =
+ node.vpack(<node> n)
+<node> h, <number> b =
+ node.vpack(<node> n, <number> w, <string> info)
+<node> h, <number> b =
+ node.vpack(<node> n, <number> w, <string> info, <string> dir)
+\stopfunctioncall
+
+The second return value is the badness of the generated box. See the description
+of \type {hpack} for a few memory allocation caveats.
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {prepend_prevdepth}}]
+
+\libindex {prepend_prevdepth}
+
+This function is somewhat special in the sense that it is an experimental helper
+that adds the interlinespace to a line keeping the baselineskip and lineskip into
+account.
+
+\startfunctioncall
+<node> n, <number> delta =
+ node.prepend_prevdepth(<node> n,<number> prevdepth)
+\stopfunctioncall
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {dimensions}, \type {rangedimensions}, \type {naturalwidth}}]
+
+\libindex{dimensions}
+\libindex{rangedimensions}
+
+\startfunctioncall
+<number> w, <number> h, <number> d =
+ node.dimensions(<node> n)
+<number> w, <number> h, <number> d =
+ node.dimensions(<node> n, <node> t)
+\stopfunctioncall
+
+This function calculates the natural in|-|line dimensions of the node list starting
+at node \type {n} and terminating just before node \type {t} (or the end of the
+list, if there is no second argument). The return values are scaled points. An
+alternative format that starts with glue parameters as the first three arguments
+is also possible:
+
+\startfunctioncall
+<number> w, <number> h, <number> d =
+ node.dimensions(<number> glue_set, <number> glue_sign, <number> glue_order,
+ <node> n)
+<number> w, <number> h, <number> d =
+ node.dimensions(<number> glue_set, <number> glue_sign, <number> glue_order,
+ <node> n, <node> t)
+\stopfunctioncall
+
+This calling method takes glue settings into account and is especially useful for
+finding the actual width of a sublist of nodes that are already boxed, for
+example in code like this, which prints the width of the space in between the
+\type {a} and \type {b} as it would be if \type {\box0} was used as-is:
+
+\starttyping
+\setbox0 = \hbox to 20pt {a b}
+
+\directlua{print (node.dimensions(
+ tex.box[0].glue_set,
+ tex.box[0].glue_sign,
+ tex.box[0].glue_order,
+ tex.box[0].head.next,
+ node.tail(tex.box[0].head)
+)) }
+\stoptyping
+
+You need to keep in mind that this is one of the few places in \TEX\ where floats
+are used, which means that you can get small differences in rounding when you
+compare the width reported by \type {hpack} with \type {dimensions}.
+
+The second alternative saves a few lookups and can be more convenient in some
+cases:
+
+\startfunctioncall
+<number> w, <number> h, <number> d =
+ node.rangedimensions(<node> parent, <node> first)
+<number> w, <number> h, <number> d =
+ node.rangedimensions(<node> parent, <node> first, <node> last)
+\stopfunctioncall
+
+A simple and somewhat more efficient variant is this:
+
+\startfunctioncall
+<number> w =
+ node.naturalwidth(<node> start, <node> stop)
+\stopfunctioncall
+
+\stopsubsubsection
+
+\stopsubsection
+
+\startsubsection[title={Math}][library=node]
+
+\startsubsubsection[title={\type {mlist_to_hlist}}]
+
+\libindex {mlist_to_hlist}
+
+\startfunctioncall
+<node> h =
+ node.mlist_to_hlist(<node> n, <string> display_type, <boolean> penalties)
+\stopfunctioncall
+
+This runs the internal mlist to hlist conversion, converting the math list in
+\type {n} into the horizontal list \type {h}. The interface is exactly the same
+as for the callback \cbk {mlist_to_hlist}.
+
+\stopsubsubsection
+
+\startsubsubsection[title={\type {end_of_math}}]
+
+\libindex {end_of_math}
+
+\startfunctioncall
+<node> t = node.end_of_math(<node> start)
+\stopfunctioncall
+
+Looks for and returns the next \type {math_node} following the \type {start}. If
+the given node is a math end node this helper returns that node, else it follows
+the list and returns the next math endnote. If no such node is found nil is
+returned.
+
+\stopsubsubsection
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title={Two access models}][library=node]
+
+\topicindex{nodes+direct}
+\topicindex{direct nodes}
+
+\libindex {todirect}
+\libindex {tonode}
+\libindex {tostring}
+
+Deep down in \TEX\ a node has a number which is a numeric entry in a memory
+table. In fact, this model, where \TEX\ manages memory is real fast and one of
+the reasons why plugging in callbacks that operate on nodes is quite fast too.
+Each node gets a number that is in fact an index in the memory table and that
+number often is reported when you print node related information. You go from
+userdata nodes and there numeric references and back with:
+
+\startfunctioncall
+<integer> d = node.todirect(<node> n))
+<node> n = node.tonode(<integer> d))
+\stopfunctioncall
+
+The userdata model is rather robust as it is a virtual interface with some
+additional checking while the more direct access which uses the node numbers
+directly. However, even with userdata you can get into troubles when you free
+nodes that are no longer allocated or mess up lists. if you apply \type
+{tostring} to a node you see its internal (direct) number and id.
+
+The first model provides key based access while the second always accesses fields
+via functions:
+
+\starttyping
+nodeobject.char
+getfield(nodenumber,"char")
+\stoptyping
+
+If you use the direct model, even if you know that you deal with numbers, you
+should not depend on that property but treat it as an abstraction just like
+traditional nodes. In fact, the fact that we use a simple basic datatype has the
+penalty that less checking can be done, but less checking is also the reason why
+it's somewhat faster. An important aspect is that one cannot mix both methods,
+but you can cast both models. So, multiplying a node number makes no sense.
+
+So our advice is: use the indexed (table) approach when possible and investigate
+the direct one when speed might be a real issue. For that reason \LUATEX\ also
+provide the \type {get*} and \type {set*} functions in the top level node
+namespace. There is a limited set of getters. When implementing this direct
+approach the regular index by key variant was also optimized, so direct access
+only makes sense when nodes are accessed millions of times (which happens in some
+font processing for instance).
+
+We're talking mostly of getters because setters are less important. Documents
+have not that many content related nodes and setting many thousands of properties
+is hardly a burden contrary to millions of consultations.
+
+Normally you will access nodes like this:
+
+\starttyping
+local next = current.next
+if next then
+ -- do something
+end
+\stoptyping
+
+Here \type {next} is not a real field, but a virtual one. Accessing it results in
+a metatable method being called. In practice it boils down to looking up the node
+type and based on the node type checking for the field name. In a worst case you
+have a node type that sits at the end of the lookup list and a field that is last
+in the lookup chain. However, in successive versions of \LUATEX\ these lookups
+have been optimized and the most frequently accessed nodes and fields have a
+higher priority.
+
+Because in practice the \type {next} accessor results in a function call, there
+is some overhead involved. The next code does the same and performs a tiny bit
+faster (but not that much because it is still a function call but one that knows
+what to look up).
+
+\starttyping
+local next = node.next(current)
+if next then
+ -- do something
+end
+\stoptyping
+
+In the direct namespace there are more helpers and most of them are accompanied
+by setters. The getters and setters are clever enough to see what node is meant.
+We don't deal with whatsit nodes: their fields are always accessed by name. It
+doesn't make sense to add getters for all fields, we just identifier the most
+likely candidates. In complex documents, many node and fields types never get
+seen, or seen only a few times, but for instance glyphs are candidates for such
+optimization. The \type {node.direct} interface has some more helpers. \footnote
+{We can define the helpers in the node namespace with \type {getfield} which is
+about as efficient, so at some point we might provide that as module.}
+
+The \type {setdisc} helper takes three (optional) arguments plus an optional
+fourth indicating the subtype. Its \type {getdisc} takes an optional boolean;
+when its value is \type {true} the tail nodes will also be returned. The \type
+{setfont} helper takes an optional second argument, it being the character. The
+directmode setter \type {setlink} takes a list of nodes and will link them,
+thereby ignoring \type {nil} entries. The first valid node is returned (beware:
+for good reason it assumes single nodes). For rarely used fields no helpers are
+provided and there are a few that probably are used seldom too but were added for
+consistency. You can of course always define additional accessors using \type
+{getfield} and \type {setfield} with little overhead. When the second argument of
+\type {setattributelist} is \type {true} the current attribute list is assumed.
+
+In \CONTEXT\ some of the not performance|-|critical userdata variants are
+emulated in \LUA\ and not in the engine, so we retain downward compatibility.
+
+\def\yes{$+$} \def\nop{$-$}
+
+\def\supported#1#2#3#4%
+ {\NC \type{#1}
+ \NC \ifx#2\yes\lix{node} {#1}\fi #2
+ \NC \ifx#3\yes\lix{node.direct}{#1}\fi #3 \NC
+ \NC #4 \NC
+ \NR}
+
+\starttabulate[|l|c|c|]
+\DB function \BC node \BC direct \NC emulated \NC \NR
+\TB
+\supported {check_discretionaries} \nop \yes \yes
+\supported {check_discretionary} \nop \yes \yes
+\supported {copy} \yes \yes \relax
+\supported {copy_list} \yes \yes \relax
+%supported {copy_only} \nop \yes \relax
+\supported {count} \nop \yes \yes
+\supported {current_attr} \yes \yes \relax
+\supported {dimensions} \nop \yes \yes
+\supported {effective_glue} \nop \yes \yes
+\supported {end_of_math} \nop \yes \yes
+\supported {find_attribute} \nop \yes \yes
+%supported {find_attribute_range} \nop \yes \relax
+%supported {find_node} \nop \yes \relax
+\supported {first_glyph} \nop \yes \yes
+\supported {flatten_discretionaries} \nop \yes \yes
+%supported {flush_components} \nop \yes \relax
+\supported {flush_list} \yes \yes \relax
+\supported {flush_node} \yes \yes \relax
+\supported {free} \yes \yes \relax
+\supported {get_attribute} \yes \yes \relax
+\supported {get_properties_table} \yes \yes \relax
+\supported {get_synctex_fields} \nop \yes \relax
+\supported {getattributelist} \nop \yes \relax
+\supported {getboth} \nop \yes \relax
+\supported {getbox} \nop \yes \relax
+\supported {getchar} \nop \yes \relax
+\supported {getcomponents} \nop \yes \relax
+\supported {getdata} \nop \yes \relax
+\supported {getdepth} \nop \yes \relax
+\supported {getdirection} \nop \yes \relax
+\supported {getdisc} \nop \yes \relax
+\supported {getexpansion} \nop \yes \relax
+\supported {getfam} \nop \yes \relax
+\supported {getfield} \yes \yes \relax
+\supported {getfont} \nop \yes \relax
+\supported {getglue} \nop \yes \yes
+%supported {getglyphdata} \nop \yes \relax % experiment
+\supported {getheight} \nop \yes \relax
+\supported {getid} \nop \yes \relax
+\supported {getkern} \nop \yes \relax
+\supported {getlang} \nop \yes \relax
+\supported {getleader} \nop \yes \relax
+\supported {getlist} \nop \yes \relax
+\supported {getnext} \nop \yes \relax
+\supported {getnormalizedline} \nop \yes \relax
+\supported {getnucleus} \nop \yes \relax
+\supported {getoffsets} \nop \yes \relax
+\supported {getorientation} \nop \yes \relax
+\supported {getpenalty} \nop \yes \relax
+\supported {getpost} \nop \yes \relax
+\supported {getpre} \nop \yes \relax
+\supported {getprev} \nop \yes \relax
+\supported {getproperty} \yes \yes \relax
+\supported {getreplace} \nop \yes \relax
+\supported {getshift} \nop \yes \relax
+\supported {getsub} \nop \yes \relax
+\supported {getsubtype} \nop \yes \relax
+\supported {getsup} \nop \yes \relax
+\supported {getwhd} \nop \yes \relax
+\supported {getwidth} \nop \yes \relax
+\supported {has_attribute} \yes \yes \relax
+\supported {has_dimensions} \nop \yes \relax
+\supported {has_field} \yes \yes \relax
+\supported {has_glyph} \nop \yes \yes
+\supported {hpack} \nop \yes \yes
+%supported {ignore_math_skip} \nop \yes \relax
+\supported {insert_after} \yes \yes \relax
+\supported {insert_before} \yes \yes \relax
+\supported {is_char} \nop \yes \relax
+\supported {is_direct} \nop \yes \relax
+\supported {is_glyph} \nop \yes \relax
+\supported {is_node} \yes \yes \relax
+\supported {is_valid} \nop \yes \relax
+\supported {is_zero_glue} \nop \yes \yes
+\supported {kerning} \nop \yes \yes
+\supported {last_node} \nop \yes \yes
+\supported {length} \nop \yes \yes
+\supported {ligaturing} \nop \yes \yes
+\supported {make_extensible} \nop \yes \yes
+\supported {mlist_to_hlist} \nop \yes \yes
+\supported {naturalwidth} \nop \yes \yes
+\supported {new} \yes \yes \relax
+\supported {prepend_prevdepth} \nop \yes \yes
+\supported {protect_glyphs} \nop \yes \yes
+\supported {protect_glyph} \nop \yes \yes
+\supported {protrusion_skippable} \nop \yes \yes
+\supported {rangedimensions} \nop \yes \yes
+\supported {remove} \yes \yes \relax
+\supported {set_attribute} \yes \yes \relax
+\supported {set_synctex_fields} \nop \yes \relax
+\supported {setattributelist} \nop \yes \relax
+\supported {setboth} \nop \yes \relax
+\supported {setbox} \nop \yes \relax
+\supported {setchar} \nop \yes \relax
+\supported {setcomponents} \nop \yes \relax
+\supported {setdata} \nop \yes \relax
+\supported {setdepth} \nop \yes \relax
+\supported {setdirection} \nop \yes \relax
+\supported {setdisc} \nop \yes \relax
+\supported {setexpansion} \nop \yes \relax
+\supported {setfam} \nop \yes \relax
+\supported {setfield} \yes \yes \relax
+\supported {setfont} \nop \yes \relax
+\supported {setglue} \yes \yes \relax
+%supported {setglyphdata} \nop \yes \relax % experiment
+\supported {setheight} \nop \yes \relax
+\supported {setkern} \nop \yes \relax
+\supported {setlang} \nop \yes \relax
+\supported {setleader} \nop \yes \relax
+\supported {setlink} \nop \yes \relax
+\supported {setlist} \nop \yes \relax
+\supported {setnext} \nop \yes \relax
+\supported {setnucleus} \nop \yes \relax
+\supported {setoffsets} \nop \yes \relax
+\supported {setorientation} \nop \yes \relax
+\supported {setpenalty} \nop \yes \relax
+\supported {setprev} \nop \yes \relax
+\supported {setproperty} \yes \yes \relax
+\supported {setshift} \nop \yes \relax
+\supported {setsplit} \nop \yes \relax
+\supported {setsub} \nop \yes \relax
+\supported {setsubtype} \nop \yes \relax
+\supported {setsup} \nop \yes \relax
+\supported {setwhd} \nop \yes \relax
+\supported {setwidth} \nop \yes \relax
+\supported {slide} \nop \yes \yes
+\supported {start_of_par} \nop \yes \relax
+\supported {subtype} \nop \nop \relax
+\supported {tail} \yes \yes \relax
+\supported {todirect} \nop \yes \relax
+\supported {tonode} \nop \yes \relax
+\supported {tostring} \yes \nop \relax
+\supported {traverse} \yes \yes \relax
+\supported {traverse_char} \yes \yes \relax
+\supported {traverse_glyph} \yes \yes \relax
+\supported {traverse_id} \yes \yes \relax
+\supported {traverse_list} \yes \yes \relax
+\supported {type} \yes \nop \relax
+\supported {unprotect_glyphs} \nop \yes \yes
+\supported {unprotect_glyph} \nop \yes \yes
+\supported {unset_attribute} \yes \yes \relax
+\supported {usedlist} \nop \yes \yes
+\supported {uses_font} \nop \yes \yes
+\supported {vpack} \nop \yes \yes
+\supported {write} \yes \yes \relax
+\LL
+\stoptabulate
+
+The \type {node.next} and \type {node.prev} functions will stay but for
+consistency there are variants called \type {getnext} and \type {getprev}. We had
+to use \type {get} because \type {node.id} and \type {node.subtype} are already
+taken for providing meta information about nodes. Note: The getters do only basic
+checking for valid keys. You should just stick to the keys mentioned in the
+sections that describe node properties.
+
+Some of the getters and setters handle multiple node types, given that the field
+is relevant. In that case, some field names are considered similar (like \type
+{kern} and \type {width}, or \type {data} and \type {value}. In retrospect we
+could have normalized field names better but we decided to stick to the original
+(internal) names as much as possible. After all, at the \LUA\ end one can easily
+create synonyms.
+
+Some nodes have indirect references. For instance a math character refers to a
+family instead of a font. In that case we provide a virtual font field as
+accessor. So, \type {getfont} and \type {.font} can be used on them. The same is
+true for the \type {width}, \type {height} and \type {depth} of glue nodes. These
+actually access the spec node properties, and here we can set as well as get the
+values.
+
+In some places \LUATEX\ can do a bit of extra checking for valid node lists and
+you can enable that with:
+
+\startfunctioncall
+node.fix_node_lists(<boolean> b)
+\stopfunctioncall
+
+You can set and query the \SYNCTEX\ fields, a file number aka tag and a line
+number, for a glue, kern, hlist, vlist, rule and math nodes as well as glyph
+nodes (although this last one is not used in native \SYNCTEX).
+
+\startfunctioncall
+node.set_synctex_fields(<integer> f, <integer> l)
+<integer> f, <integer> l =
+ node.get_synctex_fields(<node> n)
+\stopfunctioncall
+
+Of course you need to know what you're doing as no checking on sane values takes
+place. Also, the synctex interpreter used in editors is rather peculiar and has
+some assumptions (heuristics).
+
+\stopsection
+
+\startsection[title={Normalization}][library=node]
+
+As an experiment the lines resulting from paragraph construction can be normalized.
+There are several modes, that can be set and queried with:
+
+\startfunctioncall
+node.direct.setnormalize(<integer> n)
+<integer> n = node.direct.getnormalize()
+\stopfunctioncall
+
+The state of a line (a hlist) can be queried with:
+
+\startfunctioncall
+<integer> leftskip, <integer> rightskip,
+ <integer> lefthangskip, <integer> righthangskip,
+ <node> head, <node> tail,
+ <integer> parindent, <integer> parfillskip = node.direct.getnormalized()
+\stopfunctioncall
+
+The modes accumulate, so mode \type {4} includes \type {1} upto \type {3}:
+
+\starttabulate[|l|p|]
+\DB value \BC explanation \NC \NR
+\TB
+\NC \type{1} \NC left and right skips and directions \NC \NR
+\NC \type{2} \NC indentation and parfill skip \NC \NR
+\NC \type{3} \NC hanging indentation and par shapes \NC \NR
+\NC \type{4} \NC idem but before left and right skips \NC \NR
+\NC \type{5} \NC inject compensation for overflow \NC \NR
+\LL
+\stoptabulate
+
+This is experimental code and might take a while to become frozen.
+
+\stopsection
+
+\startsection[title={Properties}][library=node]
+
+\topicindex {nodes+properties}
+\topicindex {properties}
+
+\libindex{flush_properties_table}
+\libindex{get_properties_table}
+\libindex{set_properties_mode}
+
+Attributes are a convenient way to relate extra information to a node. You can
+assign them at the \TEX\ end as well as at the \LUA\ end and and consult them at
+the \LUA\ end. One big advantage is that they obey grouping. They are linked
+lists and normally checking for them is pretty efficient, even if you use a lot
+of them. A macro package has to provide some way to manage these attributes at the
+\TEX\ end because otherwise clashes in their usage can occur.
+
+Each node also can have a properties table and you can assign values to this
+table using the \type {setproperty} function and get properties using the \type
+{getproperty} function. Managing properties is way more demanding than managing
+attributes.
+
+Take the following example:
+
+\starttyping
+\directlua {
+ local n = node.new("glyph")
+
+ node.setproperty(n,"foo")
+ print(node.getproperty(n))
+
+ node.setproperty(n,"bar")
+ print(node.getproperty(n))
+
+ node.free(n)
+}
+\stoptyping
+
+This will print \type {foo} and \type {bar} which in itself is not that useful
+when multiple mechanisms want to use this feature. A variant is:
+
+\starttyping
+\directlua {
+ local n = node.new("glyph")
+
+ node.setproperty(n,{ one = "foo", two = "bar" })
+ print(node.getproperty(n).one)
+ print(node.getproperty(n).two)
+
+ node.free(n)
+}
+\stoptyping
+
+This time we store two properties with the node. It really makes sense to have a
+table as property because that way we can store more. But in order for that to
+work well you need to do it this way:
+
+\starttyping
+\directlua {
+ local n = node.new("glyph")
+
+ local t = node.getproperty(n)
+
+ if not t then
+ t = { }
+ node.setproperty(n,t)
+ end
+ t.one = "foo"
+ t.two = "bar"
+
+ print(node.getproperty(n).one)
+ print(node.getproperty(n).two)
+
+ node.free(n)
+}
+\stoptyping
+
+Here our own properties will not overwrite other users properties unless of
+course they use the same keys. So, eventually you will end up with something:
+
+\starttyping
+\directlua {
+ local n = node.new("glyph")
+
+ local t = node.getproperty(n)
+
+ if not t then
+ t = { }
+ node.setproperty(n,t)
+ end
+ t.myself = { one = "foo", two = "bar" }
+
+ print(node.getproperty(n).myself.one)
+ print(node.getproperty(n).myself.two)
+
+ node.free(n)
+}
+\stoptyping
+
+This assumes that only you use \type {myself} as subtable. The possibilities are
+endless but care is needed. For instance, the generic font handler that ships
+with \CONTEXT\ uses the \type {injections} subtable and you should not mess with
+that one!
+
+There are a few helper functions that you normally should not touch as user: \typ
+{flush_properties_table} will wipe the table (normally a bad idea), \typ
+{get_properties_table} and will give the table that stores properties (using
+direct entries) and you can best not mess too much with that one either because
+\LUATEX\ itself will make sure that entries related to nodes will get wiped when
+nodes get freed, so that the \LUA\ garbage collector can do its job. In fact, the
+main reason why we have this mechanism is that it saves the user (or macro
+package) some work. One can easily write a property mechanism in \LUA\ where
+after a shipout properties gets cleaned up but it's not entirely trivial to make
+sure that with each freed node also its properties get freed, due to the fact
+that there can be nodes left over for a next page. And having a callback bound to
+the node deallocator would add way to much overhead.
+
+When we copy a node list that has a table as property, there are several
+possibilities: we do the same as a new node, we copy the entry to the table in
+properties (a reference), we do a deep copy of a table in the properties, we
+create a new table and give it the original one as a metatable. After some
+experiments (that also included timing) with these scenarios we decided that a
+deep copy made no sense, nor did nilling. In the end both the shallow copy and
+the metatable variant were both ok, although the second one is slower. The most
+important aspect to keep in mind is that references to other nodes in properties
+no longer can be valid for that copy. We could use two tables (one unique and one
+shared) or metatables but that only complicates matters.
+
+When defining a new node, we could already allocate a table but it is rather easy
+to do that at the lua end e.g.\ using a metatable \type {__index} method. That
+way it is under macro package control. When deleting a node, we could keep the
+slot (e.g. setting it to false) but it could make memory consumption raise
+unneeded when we have temporary large node lists and after that only small lists.
+Both are not done.
+
+So in the end this is what happens now: when a node is copied, and it has a table
+as property, the new node will share that table. If the second argument of \typ
+{set_properties_mode} is \type {true} then a metatable approach is chosen: the
+copy gets its own table with the original table as metatable. If you use the
+generic font loader the mode is enabled that way.
+
+A few more xperiments were done. For instance: copy attributes to the properties
+so that we have fast access at the \LUA\ end. In the end the overhead is not
+compensated by speed and convenience, in fact, attributes are not that slow when
+it comes to accessing them. So this was rejected.
+
+Another experiment concerned a bitset in the node but again the gain compared to
+attributes was neglectable and given the small amount of available bits it also
+demands a pretty strong agreement over what bit represents what, and this is
+unlikely to succeed in the \TEX\ community. It doesn't pay off.
+
+Just in case one wonders why properties make sense: it is not so much speed that
+we gain, but more convenience: storing all kinds of (temporary) data in attributes
+is no fun and this mechanism makes sure that properties are cleaned up when a
+node is freed. Also, the advantage of a more or less global properties table is
+that we stay at the \LUA\ end. An alternative is to store a reference in the node
+itself but that is complicated by the fact that the register has some limitations
+(no numeric keys) and we also don't want to mess with it too much.
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-pdf.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-pdf.tex
new file mode 100644
index 00000000000..3e215005329
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-pdf.tex
@@ -0,0 +1,565 @@
+% language=uk
+
+% lua.newtable
+
+\environment luametatex-style
+
+\startcomponent luametatex-pdf
+
+\startchapter[reference=pdf,title={The \PDF\ related libraries}]
+
+\startsection[title={The \type {pdfe} library}][library=pdfe]
+
+\startsubsection[title={Introduction}]
+
+\topicindex{\PDF+objects}
+
+\topicindex{\PDF+analyze}
+\topicindex{\PDF+\type{pdfe}}
+
+The \type {pdfe} library replaces the \type {epdf} library and provides an
+interface to \PDF\ files. It uses the same code as is used for \PDF\ image
+inclusion. The \type {pplib} library by Paweł Jackowski replaces the \type
+{poppler} (derived from \type {xpdf}) library.
+
+A \PDF\ file is basically a tree of objects and one descends into the tree via
+dictionaries (key/value) and arrays (index/value). There are a few topmost
+dictionaries that start at root that are accessed more directly.
+
+Although everything in \PDF\ is basically an object we only wrap a few in so
+called userdata \LUA\ objects.
+
+\starttabulate[|l|l|]
+\DB type \BC mapping \NC \NR
+\TB
+\BC \PDF \BC \LUA \NC \NR
+\NC null \NC nil \NC \NR
+\NC boolean \NC boolean \NC \NR
+\NC integer \NC integer \NC \NR
+\NC float \NC number \NC \NR
+\NC name \NC string \NC \NR
+\NC string \NC string \NC \NR
+\NC array \NC array userdatum \NC \NR
+\NC dictionary \NC dictionary userdatum \NC \NR
+\NC stream \NC stream userdatum (with related dictionary) \NC \NR
+\NC reference \NC reference userdatum \NC \NR
+\LL
+\stoptabulate
+
+The regular getters return these \LUA\ data types but one can also get more
+detailed information.
+
+\stopsubsection
+
+\startsubsection[title={\type {open}, \type {openfile}, \type {new}, \type {getstatus}, \type {close}, \type {unencrypt}}]
+
+\libindex {open}
+\libindex {new}
+\libindex {new}
+\libindex {getstatus}
+\libindex {close}
+\libindex {unencrypt}
+
+A document is loaded from a file (by name or handle) or string:
+
+\starttyping
+<pdfe document> = pdfe.open(filename)
+<pdfe document> = pdfe.openfile(filehandle)
+<pdfe document> = pdfe.new(somestring,somelength)
+\stoptyping
+
+Such a document is closed with:
+
+\starttyping
+pdfe.close(<pdfe document>)
+\stoptyping
+
+You can check if a document opened well by:
+
+\starttyping
+pdfe.getstatus(<pdfe document>)
+\stoptyping
+
+The returned codes are:
+
+\starttabulate[|c|l|]
+\DB value \BC explanation \NC \NR
+\TB
+\NC \type {-2} \NC the document failed to open \NC \NR
+\NC \type {-1} \NC the document is (still) protected \NC \NR
+\NC \type {0} \NC the document is not encrypted \NC \NR
+\NC \type {2} \NC the document has been unencrypted \NC \NR
+\LL
+\stoptabulate
+
+An encrypted document can be unencrypted by the next command where instead of
+either password you can give \type {nil}:
+
+\starttyping
+pdfe.unencrypt(<pdfe document>,userpassword,ownerpassword)
+\stoptyping
+
+\stopsubsection
+
+\startsubsection[title={\type {getsize}, \type {getversion}, \type {getnofobjects}, \type {getnofpages}}]
+
+\libindex {getsize}
+\libindex {getversion}
+\libindex {getnofobjects}
+\libindex {getnofpages}
+
+A successfully opened document can provide some information:
+
+\starttyping
+bytes = getsize(<pdfe document>)
+major, minor = getversion(<pdfe document>)
+n = getnofobjects(<pdfe document>)
+n = getnofpages(<pdfe document>)
+bytes, waste = getnofpages(<pdfe document>)
+\stoptyping
+
+\stopsubsection
+
+\startsubsection[title={\type {get[catalog|trailer|info]}}]
+
+\libindex {getcatalog}
+\libindex {gettrailer}
+\libindex {getinfo}
+
+For accessing the document structure you start with the so called catalog, a
+dictionary:
+
+\starttyping
+<pdfe dictionary> = pdfe.getcatalog(<pdfe document>)
+\stoptyping
+
+The other two root dictionaries are accessed with:
+
+\starttyping
+<pdfe dictionary> = pdfe.gettrailer(<pdfe document>)
+<pdfe dictionary> = pdfe.getinfo(<pdfe document>)
+\stoptyping
+
+\stopsubsection
+
+\startsubsection[title={\type {getpage}, \type {getbox}}]
+
+\libindex {getpage}
+\libindex {getbox}
+
+A specific page can conveniently be reached with the next command, which
+returns a dictionary. The first argument is to be a page dictionary.
+
+\starttyping
+<pdfe dictionary> = pdfe.getpage(<pdfe document>,pagenumber)
+\stoptyping
+
+Another convenience command gives you the (bounding) box of a (normally page)
+which can be inherited from the document itself. An example of a valid box name
+is \type {MediaBox}.
+
+\starttyping
+pages = pdfe.getbox(<pdfe dictionary>,boxname)
+\stoptyping
+
+\stopsubsection
+
+\startsubsection[title={\type {get[string|integer|number|boolean|name]}}]
+
+\libindex {getstring}
+\libindex {getinteger}
+\libindex {getnumber}
+\libindex {getboolean}
+\libindex {getname}
+
+Common values in dictionaries and arrays are strings, integers, floats, booleans
+and names (which are also strings) and these are also normal \LUA\ objects:
+
+\starttyping
+s = getstring (<pdfe array|dictionary>,index|key)
+i = getinteger(<pdfe array|dictionary>,index|key)
+n = getnumber (<pdfe array|dictionary>,index|key)
+b = getboolean(<pdfe array|dictionary>,index|key)
+n = getname (<pdfe array|dictionary>,index|key)
+\stoptyping
+
+\stopsubsection
+
+\startsubsection[title={\type {get[from][dictionary|array|stream]}}]
+
+\libindex {getdictionary} \libindex {getfromdictionary}
+\libindex {getarray} \libindex {getfromarray}
+\libindex {getstream} \libindex {getfromstream}
+
+Normally you will use an index in an array and key in a dictionary but dictionaries
+also accept an index. The size of an array or dictionary is available with the
+usual \type {#} operator.
+
+\starttyping
+<pdfe dictionary> = getdictionary(<pdfe array|dictionary>,index|key)
+<pdfe array> = getarray (<pdfe array|dictionary>,index|key)
+<pdfe stream>,
+<pdfe dictionary> = getstream (<pdfe array|dictionary>,index|key)
+\stoptyping
+
+These commands return dictionaries, arrays and streams, which are dictionaries
+with a blob of data attached.
+
+Before we come to an alternative access mode, we mention that the objects provide
+access in a different way too, for instance this is valid:
+
+\starttyping
+print(pdfe.open("foo.pdf").Catalog.Type)
+\stoptyping
+
+At the topmost level there are \type {Catalog}, \type {Info}, \type {Trailer}
+and \type {Pages}, so this is also okay:
+
+\starttyping
+print(pdfe.open("foo.pdf").Pages[1])
+\stoptyping
+
+\stopsubsection
+
+\startsubsection[title={\type {[open|close|readfrom|whole|]stream}}]
+
+\libindex {openstream}
+\libindex {closestream}
+\libindex {readfromstream}
+\libindex {readfromwholestream}
+
+Streams are sort of special. When your index or key hits a stream you get back a
+stream object and dictionary object. The dictionary you can access in the usual
+way and for the stream there are the following methods:
+
+\starttyping
+okay = openstream(<pdfe stream>,[decode])
+ closestream(<pdfe stream>)
+str, n = readfromstream(<pdfe stream>)
+str, n = readwholestream(<pdfe stream>,[decode])
+\stoptyping
+
+You either read in chunks, or you ask for the whole. When reading in chunks, you
+need to open and close the stream yourself. The \type {n} value indicates the
+length read. The \type {decode} parameter controls if the stream data gets
+uncompressed.
+
+As with dictionaries, you can access fields in a stream dictionary in the usual
+\LUA\ way too. You get the content when you \quote {call} the stream. You can
+pass a boolean that indicates if the stream has to be decompressed.
+
+% pdfe.objectcodes = objectcodes
+% pdfe.stringcodes = stringcodes
+% pdfe.encryptioncodes = encryptioncodes
+
+\stopsubsection
+
+\startsubsection[title={\type {getfrom[dictionary|array]}}]
+
+\libindex {getfromdictionary}
+\libindex {getfromarray}
+
+In addition to the interface described before, there is also a bit lower level
+interface available.
+
+\starttyping
+key, type, value, detail = getfromdictionary(<pdfe dictionary>,index)
+type, value, detail = getfromarray(<pdfe array>,index)
+\stoptyping
+
+\starttabulate[|c|l|l|l|]
+\DB type \BC meaning \BC value \BC detail \NC \NR
+\NC \type {0} \NC none \NC nil \NC \NC \NR
+\NC \type {1} \NC null \NC nil \NC \NC \NR
+\NC \type {2} \NC boolean \NC boolean \NC \NC \NR
+\NC \type {3} \NC integer \NC integer \NC \NC \NR
+\NC \type {4} \NC number \NC float \NC \NC \NR
+\NC \type {5} \NC name \NC string \NC \NC \NR
+\NC \type {6} \NC string \NC string \NC hex \NC \NR
+\NC \type {7} \NC array \NC arrayobject \NC size \NC \NR
+\NC \type {8} \NC dictionary \NC dictionaryobject \NC size \NC \NR
+\NC \type {9} \NC stream \NC streamobject \NC dictionary size \NC \NR
+\NC \type {10} \NC reference \NC integer \NC \NC \NR
+\LL
+\stoptabulate
+
+A \type {hex} string is (in the \PDF\ file) surrounded by \type {<>} while plain
+strings are bounded by \type {<>}.
+
+\stopsubsection
+
+\startsubsection[title={\type {[dictionary|array]totable}}]
+
+\libindex {dictionarytotable}
+\libindex {arraytotable}
+
+All entries in a dictionary or table can be fetched with the following commands
+where the return values are a hashed or indexed table.
+
+\starttyping
+hash = dictionarytotable(<pdfe dictionary>)
+list = arraytotable(<pdfe array>)
+\stoptyping
+
+You can get a list of pages with:
+
+\starttyping
+{ { <pdfe dictionary>, size, objnum }, ... } = pagestotable(<pdfe document>)
+\stoptyping
+
+\stopsubsection
+
+\startsubsection[title={\type {getfromreference}}]
+
+\libindex {getfromreference}
+
+Because you can have unresolved references, a reference object can be resolved
+with:
+
+\starttyping
+type, <pdfe dictionary|array|stream>, detail = getfromreference(<pdfe reference>)
+\stoptyping
+
+So, as second value you get back a new \type {pdfe} userdata object that you can
+query.
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title={Memory streams}][library=pdfe]
+
+\topicindex{\PDF+memory streams}
+
+\libindex {new}
+
+The \type {pdfe.new} that takes three arguments:
+
+\starttabulate
+\DB value \BC explanation \NC \NR
+\TB
+\NC \type {stream} \NC this is a (in low level \LUA\ speak) light userdata
+ object, i.e.\ a pointer to a sequence of bytes \NC \NR
+\NC \type {length} \NC this is the length of the stream in bytes (the stream can
+ have embedded zeros) \NC \NR
+\NC \type {name} \NC optional, this is a unique identifier that is used for
+ hashing the stream, so that multiple doesn't use more
+ memory \NC \NR
+\LL
+\stoptabulate
+
+The third argument is optional. When it is not given the function will return an
+\type {pdfe} document object as with a regular file, otherwise it will return a
+filename that can be used elsewhere (e.g.\ in the image library) to reference the
+stream as pseudo file.
+
+Instead of a light userdata stream (which is actually fragile but handy when you
+come from a library) you can also pass a \LUA\ string, in which case the given
+length is (at most) the string length.
+
+The function returns an \type {pdfe} object and a string. The string can be used in
+the \type {img} library instead of a filename. You need to prevent garbage
+collection of the object when you use it as image (for instance by storing it
+somewhere).
+
+Both the memory stream and it's use in the image library is experimental and can
+change. In case you wonder where this can be used: when you use the swiglib
+library for \type {graphicmagick}, it can return such a userdata object. This
+permits conversion in memory and passing the result directly to the backend. This
+might save some runtime in one|-|pass workflows. This feature is currently not
+meant for production and we might come up with a better implementation.
+
+\stopsection
+
+\startsection[title={The \type {pdfscanner} library}][library=pdfscanner]
+
+This library is not available in \LUAMETATEX.
+
+\stopsection
+
+% \startsection[title={The \type {pdfscanner} library}][library=pdfscanner]
+%
+% \topicindex{\PDF+scanner}
+%
+% \libindex {scan}
+%
+% The \type {pdfscanner} library allows interpretation of \PDF\ content streams and
+% \type {/ToUnicode} (cmap) streams. You can get those streams from the \type
+% {pdfe} library, as explained in an earlier section. There is only a single
+% top|-|level function in this library:
+%
+% \startfunctioncall
+% pdfscanner.scan (<pdfe stream>, <table> operatortable, <table> info)
+% pdfscanner.scan (<pdfe array>, <table> operatortable, <table> info)
+% pdfscanner.scan (<string>, <table> operatortable, <table> info)
+% \stopfunctioncall
+%
+% The first argument should be a \LUA\ string or a stream or array onject coming
+% from the \type {pdfe} library. The second argument, \type {operatortable}, should
+% be a \LUA\ table where the keys are \PDF\ operator name strings and the values
+% are \LUA\ functions (defined by you) that are used to process those operators.
+% The functions are called whenever the scanner finds one of these \PDF\ operators
+% in the content stream(s). The functions are called with two arguments: the \type
+% {scanner} object itself, and the \type {info} table that was passed are the third
+% argument to \type {pdfscanner.scan}.
+%
+% Internally, \type {pdfscanner.scan} loops over the \PDF\ operators in the
+% stream(s), collecting operands on an internal stack until it finds a \PDF\
+% operator. If that \PDF\ operator's name exists in \type {operatortable}, then the
+% associated function is executed. After the function has run (or when there is no
+% function to execute) the internal operand stack is cleared in preparation for the
+% next operator, and processing continues.
+%
+% The \type {scanner} argument to the processing functions is needed because it
+% offers various methods to get the actual operands from the internal operand
+% stack.
+%
+% A simple example of processing a \PDF's document stream could look like this:
+%
+% \starttyping
+% local operatortable = { }
+%
+% operatortable.Do = function(scanner,info)
+% local resources = info.resources
+% if resources then
+% local val = scanner:pop()
+% local name = val[2]
+% local xobject = resources.XObject
+% print(info.space .. "Uses XObject " .. name)
+% local resources = xobject.Resources
+% if resources then
+% local newinfo = {
+% space = info.space .. " ",
+% resources = resources,
+% }
+% pdfscanner.scan(entry, operatortable, newinfo)
+% end
+% end
+% end
+%
+% local function Analyze(filename)
+% local doc = pdfe.open(filename)
+% if doc then
+% local pages = doc.Pages
+% for i=1,#pages do
+% local page = pages[i]
+% local info = {
+% space = " " ,
+% resources = page.Resources,
+% }
+% print("Page " .. i)
+% -- pdfscanner.scan(page.Contents,operatortable,info)
+% pdfscanner.scan(page.Contents(),operatortable,info)
+% end
+% end
+% end
+%
+% Analyze("foo.pdf")
+% \stoptyping
+%
+% This example iterates over all the actual content in the \PDF, and prints out the
+% found \type {XObject} names. While the code demonstrates quite some of the \type
+% {pdfe} functions, let's focus on the type \type {pdfscanner} specific code
+% instead.
+%
+% From the bottom up, the following line runs the scanner with the \PDF\ page's
+% top|-|level content given in the first argument.
+%
+% The third argument, \type {info}, contains two entries: \type {space} is used to
+% indent the printed output, and \type {resources} is needed so that embedded \type
+% {XForms} can find their own content.
+%
+% The second argument, \type {operatortable} defines a processing function for a
+% single \PDF\ operator, \type {Do}.
+%
+% The function \type {Do} prints the name of the current \type {XObject}, and then
+% starts a new scanner for that object's content stream, under the condition that
+% the \type {XObject} is in fact a \type {/Form}. That nested scanner is called
+% with new \type {info} argument with an updated \type {space} value so that the
+% indentation of the output nicely nests, and with a new \type {resources} field
+% to help the next iteration down to properly process any other, embedded \type
+% {XObject}s.
+%
+% Of course, this is not a very useful example in practice, but for the purpose of
+% demonstrating \type {pdfscanner}, it is just long enough. It makes use of only
+% one \type {scanner} method: \type {scanner:pop()}. That function pops the top
+% operand of the internal stack, and returns a \LUA\ table where the object at index
+% one is a string representing the type of the operand, and object two is its
+% value.
+%
+% The list of possible operand types and associated \LUA\ value types is:
+%
+% \starttabulate[|l|l|]
+% \DB types \BC type \NC \NR
+% \TB
+% \NC \type{integer} \NC <number> \NC \NR
+% \NC \type{real} \NC <number> \NC \NR
+% \NC \type{boolean} \NC <boolean> \NC \NR
+% \NC \type{name} \NC <string> \NC \NR
+% \NC \type{operator} \NC <string> \NC \NR
+% \NC \type{string} \NC <string> \NC \NR
+% \NC \type{array} \NC <table> \NC \NR
+% \NC \type{dict} \NC <table> \NC \NR
+% \LL
+% \stoptabulate
+%
+% In case of \type {integer} or \type {real}, the value is always a \LUA\ (floating
+% point) number. In case of \type {name}, the leading slash is always stripped.
+%
+% In case of \type {string}, please bear in mind that \PDF\ actually supports
+% different types of strings (with different encodings) in different parts of the
+% \PDF\ document, so you may need to reencode some of the results; \type {pdfscanner}
+% always outputs the byte stream without reencoding anything. \type {pdfscanner}
+% does not differentiate between literal strings and hexadecimal strings (the
+% hexadecimal values are decoded), and it treats the stream data for inline images
+% as a string that is the single operand for \type {EI}.
+%
+% In case of \type {array}, the table content is a list of \type {pop} return
+% values and in case of \type {dict}, the table keys are \PDF\ name strings and the
+% values are \type {pop} return values.
+%
+% \libindex{pop}
+% \libindex{popnumber}
+% \libindex{popname}
+% \libindex{popstring}
+% \libindex{poparray}
+% \libindex{popdictionary}
+% \libindex{popboolean}
+% \libindex{done}
+%
+% There are a few more methods defined that you can ask \type {scanner}:
+%
+% \starttabulate[|l|p|]
+% \DB method \BC explanation \NC \NR
+% \TB
+% \NC \type{pop} \NC see above \NC \NR
+% \NC \type{popnumber} \NC return only the value of a \type {real} or \type {integer} \NC \NR
+% \NC \type{popname} \NC return only the value of a \type {name} \NC \NR
+% \NC \type{popstring} \NC return only the value of a \type {string} \NC \NR
+% \NC \type{poparray} \NC return only the value of a \type {array} \NC \NR
+% \NC \type{popdictionary} \NC return only the value of a \type {dict} \NC \NR
+% \NC \type{popboolean} \NC return only the value of a \type {boolean} \NC \NR
+% \NC \type{done} \NC abort further processing of this \type {scan()} call \NC \NR
+% \LL
+% \stoptabulate
+%
+% The \type {pop*} are convenience functions, and come in handy when you know the
+% type of the operands beforehand (which you usually do, in \PDF). For example, the
+% \type {Do} function could have used \type {local name = scanner:popname()}
+% instead, because the single operand to the \type {Do} operator is always a \PDF\
+% name object.
+%
+% The \type {done} function allows you to abort processing of a stream once you
+% have learned everything you want to learn. This comes in handy while parsing
+% \type {/ToUnicode}, because there usually is trailing garbage that you are not
+% interested in. Without \type {done}, processing only ends at the end of the
+% stream, possibly wasting \CPU\ cycles.
+%
+% {\em We keep the older names \type {popNumber}, \type {popName}, \type
+% {popString}, \type {popArray}, \type {popDict} and \type {popBool} around.}
+%
+% \stopsection
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-preamble.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-preamble.tex
new file mode 100644
index 00000000000..8f1400c9f9c
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-preamble.tex
@@ -0,0 +1,166 @@
+% language=uk
+
+\environment luametatex-style
+
+\startcomponent luametatex-preamble
+
+\startchapter[reference=preamble,title={The internals}]
+
+\topicindex{nodes}
+\topicindex{boxes}
+\topicindex{\LUA}
+
+This is a reference manual, not a tutorial. This means that we discuss changes
+relative to traditional \TEX\ and also present new functionality. As a
+consequence we will refer to concepts that we assume to be known or that might be
+explained later. Because the \LUATEX\ and \LUAMETATEX\ engines open up \TEX\
+there's suddenly quite some more to explain, especially about the way a (to be)
+typeset stream moves through the machinery. However, discussing all that in
+detail makes not much sense, because deep knowledge is only relevant for those
+who write code not possible with regular \TEX\ and who are already familiar with
+these internals (or willing to spend time on figuring it out).
+
+So, the average user doesn't need to know much about what is in this manual. For
+instance fonts and languages are normally dealt with in the macro package that
+you use. Messing around with node lists is also often not really needed at the
+user level. If you do mess around, you'd better know what you're dealing with.
+Reading \quotation {The \TEX\ Book} by Donald Knuth is a good investment of time
+then also because it's good to know where it all started. A more summarizing
+overview is given by \quotation {\TEX\ by Topic} by Victor Eijkhout. You might
+want to peek in \quotation {The \ETEX\ manual} too.
+
+But \unknown\ if you're here because of \LUA, then all you need to know is that
+you can call it from within a run. If you want to learn the language, just read
+the well written \LUA\ book. The macro package that you use probably will provide
+a few wrapper mechanisms but the basic \lpr {directlua} command that does the job
+is:
+
+\starttyping
+\directlua{tex.print("Hi there")}
+\stoptyping
+
+You can put code between curly braces but if it's a lot you can also put it in a
+file and load that file with the usual \LUA\ commands. If you don't know what
+this means, you definitely need to have a look at the \LUA\ book first.
+
+If you still decide to read on, then it's good to know what nodes are, so we do a
+quick introduction here. If you input this text:
+
+\starttyping
+Hi There
+\stoptyping
+
+eventually we will get a linked lists of nodes, which in \ASCII\ art looks like:
+
+\starttyping
+H <=> i <=> [glue] <=> T <=> h <=> e <=> r <=> e
+\stoptyping
+
+When we have a paragraph, we actually get something:
+
+\starttyping
+[localpar] <=> H <=> i <=> [glue] <=> T <=> h <=> e <=> r <=> e <=> [glue]
+\stoptyping
+
+Each character becomes a so called glyph node, a record with properties like the
+current font, the character code and the current language. Spaces become glue
+nodes. There are many node types that we will discuss later. Each node points
+back to a previous node or next node, given that these exist. Sometimes
+multiple characters are represented by one glyphs, so one can also get:
+
+\starttyping
+[localpar] <=> H <=> i <=> [glue] <=> Th <=> e <=> r <=> e <=> [glue]
+\stoptyping
+
+And maybe some characters get positioned relative to each other, so we might
+see:
+
+\starttyping
+[localpar] <=> H <=> [kern] <=> i <=> [glue] <=> Th <=> e <=> r <=> e <=> [glue]
+\stoptyping
+
+It's also good to know beforehand that \TEX\ is basically centered around
+creating paragraphs and pages. The par builder takes a list and breaks it into
+lines. At some point horizontal blobs are wrapped into vertical ones. Lines are
+so called boxes and can be separated by glue, penalties and more. The page
+builder accumulates lines and when feasible triggers an output routine that will
+take the list so far. Constructing the actual page is not part of \TEX\ but done
+using primitives that permit manipulation of boxes. The result is handled back to
+\TEX\ and flushed to a (often \PDF) file.
+
+The \LUATEX\ engine provides hooks for \LUA\ code at nearly every reasonable
+point in the process: collecting content, hyphenating, applying font features,
+breaking into lines, etc. This means that you can overload \TEX's natural
+behaviour, which still is the benchmark. When we refer to \quote {callbacks} we
+means these hooks. The \TEX\ engine itself is pretty well optimized but when you
+kick in much \LUA\ code, you will notices that performance drops. Don't blame and
+bother the authors with performance issues. In \CONTEXT\ over 50\% of the time
+can be spent in \LUA, but so far we didn't get many complaints about efficiency.
+
+Where plain \TEX\ is basically a basic framework for writing a specific style,
+macro packages like \CONTEXT\ and \LATEX\ provide the user a whole lot of
+additional tools to make documents look good. They hide the dirty details of font
+management, language demands, turning structure into typeset results, wrapping
+pages, including images, and so on. You should be aware of the fact that when you
+hook in your own code to manipulate lists, this can interfere with the macro
+package that you use. Each successive step expects a certain result and if you
+mess around to much, the engine eventually might bark and quit. It can even
+crash, because testing everywhere for what users can do wrong is no real option.
+
+When you read about nodes in the following chapters it's good to keep in mind
+their commands that relate to then. Here are a few:
+
+\starttabulate[|l|l|p|]
+\DB command \BC node \BC explanation \NC \NR
+\TB
+\NC \prm {hbox} \NC \nod {hlist} \NC horizontal box \NC \NR
+\NC \prm {vbox} \NC \nod {vlist} \NC vertical box with the baseline at the bottom \NC \NR
+\NC \prm {vtop} \NC \nod {vlist} \NC vertical box with the baseline at the top \NC \NR
+\NC \prm {hskip} \NC \nod {glue} \NC horizontal skip with optional stretch and shrink \NC \NR
+\NC \prm {vskip} \NC \nod {glue} \NC vertical skip with optional stretch and shrink \NC \NR
+\NC \prm {kern} \NC \nod {kern} \NC horizontal or vertical fixed skip \NC \NR
+\NC \prm {discretionary} \NC \nod {disc} \NC hyphenation point (pre, post, replace) \NC \NR
+\NC \prm {char} \NC \nod {glyph} \NC a character \NC \NR
+\NC \prm {hrule} \NC \nod {rule} \NC a horizontal rule \NC \NR
+\NC \prm {vrule} \NC \nod {rule} \NC a vertical rule \NC \NR
+\NC \prm {textdirection} \NC \nod {dir} \NC a change in text direction \NC \NR
+\LL
+\stoptabulate
+
+Text (interspersed with macros) comes from an input medium. This can be a file,
+token list, macro body cq.\ arguments, \ some internal quantity (like a number),
+\LUA, etc. Macros get expanded. In the process \TEX\ can enter a group. Inside
+the group, changes to registers get saved on a stack, and restored after leaving
+the group. When conditionals are encountered, another kind of nesting happens,
+and again there is a stack involved. Tokens, expansion, stacks, input levels are
+all terms used in the next chapters. Don't worry, they loose their magic once you
+use \TEX\ a lot. You have access to most of the internals and when not, at least
+it is possible to query some state we're in or level we're at.
+
+When we talk about packing it can mean two things. When \TEX\ has consumed some
+tokens that represent text the next can happen. When the text is put into a so
+called \type {\hbox} it (normally) first gets hyphenated, next ligatures are
+build, and finally kerns are added. Each of that stages can be overloaded using
+\LUA\ code. When these three stages are finished, the dimension of the content is
+calculated and the box gets its width, height and depth. What happens with the
+box depends on what macros do with it.
+
+The other thing that can happen is that the text starts a new paragraph. In that
+case some (directional) information is put in front, indentation is prepended and
+some skip appended at the end. Again the three stages are applied but this time,
+afterwards, the long line is broken into lines and the result is either added to
+the content of a box or to the main vertical list (the running text so to say).
+This is called par building. At some point \TEX\ decides that enough is enough
+and it will trigger the page builder. So, building is another concept we will
+encounter. Another example of a builder is the one that turns an intermediate
+math list into something typeset.
+
+Wrapping something in a box is called packing. Adding something to a list is
+described in terms of contributing. The more complicated processes are wrapped
+into builders. For now this should be enough to enable you to understand the next
+chapters. The text is not as enlightening and entertaining as Don Knuths books,
+sorry.
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-primitives.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-primitives.tex
new file mode 100644
index 00000000000..9e26c6bc47f
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-primitives.tex
@@ -0,0 +1,395 @@
+% language=uk
+
+\environment luametatex-style
+
+\startcomponent luametatex-primitives
+
+\startchapter[reference=primitives,title={Primitives aka commands}]
+
+\startsection[title=Introduction]
+
+The starting point of \LUATEX\ is \PDFTEX, which itself contains regular \TEX\
+and \ETEX. Because directional support was needed we also took some code from
+\ALEPH\ (\OMEGA). In a later stage the backend specific commands were isolated in
+its own namespace which resulted in a cleaner code base where the backend code no
+longer was interwoven with the normal frontend primitives. We also promoted some
+generic constructs (like box resources and directions) to core functionality.
+
+Some of the \PDFTEX\ support primitives have been around from the start but when
+\LUA\ integration became better and when a token scanner library was added, not
+all of those made sense as primitives. In previous chapters we already mentioned
+what is gone from the core. Deep down some more has changes but not all is
+reflected at the primitive level. Because there is still a considerable amount of
+new primitives, a summary is given below.
+
+\stopsection
+
+\startsection[title=Languages]
+
+\starttabulate[|||p|]
+\NC \type {automatichyphenmode} \NC integer \NC \NC \NR
+\NC \type {automatichyphenpenalty} \NC integer \NC \NC \NR
+\NC \type {hyphenpenaltymode} \NC integer \NC \NC \NR
+\NC \type {compoundhyphenmode} \NC integer \NC \NC \NR
+\NC \type {exceptionpenalty} \NC integer \NC \NC \NR
+\NC \type {explicithyphenpenalty} \NC integer \NC \NC \NR
+\NC \type {hyphenationbounds} \NC integer \NC \NC \NR
+\NC \type {hjcode} \NC charactercode \NC \NC \NR
+\NC \type {hyphenationmin} \NC charactercode \NC \NC \NR
+\NC \type {postexhyphenchar} \NC charactercode \NC \NC \NR
+\NC \type {posthyphenchar} \NC charactercode \NC \NC \NR
+\NC \type {preexhyphenchar} \NC charactercode \NC \NC \NR
+\NC \type {prehyphenchar} \NC charactercode \NC \NC \NR
+\stoptabulate
+
+\stopsection
+
+\startsection[title=Fonts]
+
+\starttabulate[|||p|]
+\NC \type {tracingfonts} \NC integer \NC \NC \NR
+\NC \type {suppressfontnotfounderror} \NC integer \NC \NC \NR
+\NC \type {setfontid} \NC integer \NC \NC \NR
+\NC \type {fontid} \NC font \NC \NC \NR
+\NC \type {efcode} \NC font charactercode \NC \NC \NR
+\NC \type {lpcode} \NC font charactercode \NC \NC \NR
+\NC \type {rpcode} \NC font charactercode \NC \NC \NR
+\stoptabulate
+
+\stopsection
+
+\startsection[title=Math]
+
+\starttabulate[|||p|]
+\NC \type {matholdmode} \NC integer \NC \NC \NR
+\NC \type {mathstyle} \NC integer \NC \NC \NR
+\NC \type {matheqnogapstep} \NC integer \NC \NC \NR
+\NC \type {Uskewed} \NC \NC \NC \NR
+\NC \type {Uskewedwithdelims} \NC \NC \NC \NR
+\NC \type {Ustartdisplaymath} \NC \NC \NC \NR
+\NC \type {Ustartmath} \NC \NC \NC \NR
+\NC \type {Ustopdisplaymath} \NC \NC \NC \NR
+\NC \type {Ustopmath} \NC \NC \NC \NR
+\NC \type {crampeddisplaystyle} \NC \NC \NC \NR
+\NC \type {crampedtextstyle} \NC \NC \NC \NR
+\NC \type {crampedscriptstyle} \NC \NC \NC \NR
+\NC \type {crampedscriptscriptstyle} \NC \NC \NC \NR
+\NC \type {Umathchardef} \NC \NC \NC \NR
+\NC \type {Umathcharnumdef} \NC \NC \NC \NR
+\NC \type {mathdisplayskipmode} \NC integer \NC \NC \NR
+\NC \type {mathscriptsmode} \NC integer \NC \NC \NR
+\NC \type {mathnolimitsmode} \NC integer \NC \NC \NR
+\NC \type {mathitalicsmode} \NC integer \NC \NC \NR
+\NC \type {mathrulesmode} \NC integer \NC \NC \NR
+\NC \type {mathrulesfam} \NC integer \NC \NC \NR
+\NC \type {mathdelimitersmode} \NC integer \NC \NC \NR
+\NC \type {mathflattenmode} \NC integer \NC \NC \NR
+\NC \type {mathpenaltiesmode} \NC integer \NC \NC \NR
+\NC \type {mathrulethicknessmode} \NC integer \NC \NC \NR
+\NC \type {mathscriptboxmode} \NC integer \NC \NC \NR
+\NC \type {mathscriptcharmode} \NC integer \NC \NC \NR
+\NC \type {mathsurroundmode} \NC integer \NC \NC \NR
+\NC \type {nokerns} \NC integer \NC \NC \NR
+\NC \type {noligs} \NC integer \NC \NC \NR
+\NC \type {prebinoppenalty} \NC integer \NC \NC \NR
+\NC \type {predisplaygapfactor} \NC integer \NC \NC \NR
+\NC \type {prerelpenalty} \NC integer \NC \NC \NR
+\NC \type {Usuperscript} \NC command \NC \NC \NR
+\NC \type {Usubscript} \NC command \NC \NC \NR
+\NC \type {Unosuperscript} \NC command \NC \NC \NR
+\NC \type {Unosubscript} \NC command \NC \NC \NR
+\NC \type {Umathcode} \NC \NC \NC \NR
+\NC \type {Umathcodenum} \NC \NC \NC \NR
+\NC \type {Udelcode} \NC \NC \NC \NR
+\NC \type {Udelcodenum} \NC \NC \NC \NR
+\NC \type {Umathaxis} \NC family dimension \NC \NC \NR
+\NC \type {Umathbinbinspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathbinclosespacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathbininnerspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathbinopenspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathbinopspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathbinordspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathbinpunctspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathbinrelspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathclosebinspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathcloseclosespacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathcloseinnerspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathcloseopenspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathcloseopspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathcloseordspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathclosepunctspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathcloserelspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathconnectoroverlapmin} \NC family dimension \NC \NC \NR
+\NC \type {Umathfractiondelsize} \NC family dimension \NC \NC \NR
+\NC \type {Umathfractiondenomdown} \NC family dimension \NC \NC \NR
+\NC \type {Umathfractiondenomvgap} \NC family dimension \NC \NC \NR
+\NC \type {Umathfractionnumup} \NC family dimension \NC \NC \NR
+\NC \type {Umathfractionnumvgap} \NC family dimension \NC \NC \NR
+\NC \type {Umathfractionrule} \NC family dimension \NC \NC \NR
+\NC \type {Umathinnerbinspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathinnerclosespacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathinnerinnerspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathinneropenspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathinneropspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathinnerordspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathinnerpunctspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathinnerrelspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathlimitabovebgap} \NC family dimension \NC \NC \NR
+\NC \type {Umathlimitabovekern} \NC family dimension \NC \NC \NR
+\NC \type {Umathlimitabovevgap} \NC family dimension \NC \NC \NR
+\NC \type {Umathlimitbelowbgap} \NC family dimension \NC \NC \NR
+\NC \type {Umathlimitbelowkern} \NC family dimension \NC \NC \NR
+\NC \type {Umathlimitbelowvgap} \NC family dimension \NC \NC \NR
+\NC \type {Umathnolimitsubfactor} \NC family dimension \NC \NC \NR
+\NC \type {Umathnolimitsupfactor} \NC family dimension \NC \NC \NR
+\NC \type {Umathopbinspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathopclosespacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathopenbinspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathopenclosespacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathopeninnerspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathopenopenspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathopenopspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathopenordspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathopenpunctspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathopenrelspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathoperatorsize} \NC family dimension \NC \NC \NR
+\NC \type {Umathopinnerspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathopopenspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathopopspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathopordspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathoppunctspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathoprelspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathordbinspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathordclosespacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathordinnerspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathordopenspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathordopspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathordordspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathordpunctspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathordrelspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathoverbarkern} \NC family dimension \NC \NC \NR
+\NC \type {Umathoverbarrule} \NC family dimension \NC \NC \NR
+\NC \type {Umathoverbarvgap} \NC family dimension \NC \NC \NR
+\NC \type {Umathoverdelimiterbgap} \NC family dimension \NC \NC \NR
+\NC \type {Umathoverdelimitervgap} \NC family dimension \NC \NC \NR
+\NC \type {Umathpunctbinspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathpunctclosespacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathpunctinnerspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathpunctopenspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathpunctopspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathpunctordspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathpunctpunctspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathpunctrelspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathquad} \NC family dimension \NC \NC \NR
+\NC \type {Umathradicaldegreeafter} \NC family dimension \NC \NC \NR
+\NC \type {Umathradicaldegreebefore} \NC family dimension \NC \NC \NR
+\NC \type {Umathradicaldegreeraise} \NC family dimension \NC \NC \NR
+\NC \type {Umathradicalkern} \NC family dimension \NC \NC \NR
+\NC \type {Umathradicalrule} \NC family dimension \NC \NC \NR
+\NC \type {Umathradicalvgap} \NC family dimension \NC \NC \NR
+\NC \type {Umathrelbinspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathrelclosespacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathrelinnerspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathrelopenspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathrelopspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathrelordspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathrelpunctspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathrelrelspacing} \NC family dimension \NC \NC \NR
+\NC \type {Umathskewedfractionhgap} \NC family dimension \NC \NC \NR
+\NC \type {Umathskewedfractionvgap} \NC family dimension \NC \NC \NR
+\NC \type {Umathspaceafterscript} \NC family dimension \NC \NC \NR
+\NC \type {Umathstackdenomdown} \NC family dimension \NC \NC \NR
+\NC \type {Umathstacknumup} \NC family dimension \NC \NC \NR
+\NC \type {Umathstackvgap} \NC family dimension \NC \NC \NR
+\NC \type {Umathsubshiftdown} \NC family dimension \NC \NC \NR
+\NC \type {Umathsubshiftdrop} \NC family dimension \NC \NC \NR
+\NC \type {Umathsubsupshiftdown} \NC family dimension \NC \NC \NR
+\NC \type {Umathsubsupvgap} \NC family dimension \NC \NC \NR
+\NC \type {Umathsubtopmax} \NC family dimension \NC \NC \NR
+\NC \type {Umathsupbottommin} \NC family dimension \NC \NC \NR
+\NC \type {Umathsupshiftdrop} \NC family dimension \NC \NC \NR
+\NC \type {Umathsupshiftup} \NC family dimension \NC \NC \NR
+\NC \type {Umathsupsubbottommax} \NC family dimension \NC \NC \NR
+\NC \type {Umathunderbarkern} \NC family dimension \NC \NC \NR
+\NC \type {Umathunderbarrule} \NC family dimension \NC \NC \NR
+\NC \type {Umathunderbarvgap} \NC family dimension \NC \NC \NR
+\NC \type {Umathunderdelimiterbgap} \NC family dimension \NC \NC \NR
+\NC \type {Umathunderdelimitervgap} \NC family dimension \NC \NC \NR
+\NC \type {Udelimiter} \NC \NC \NC \NR
+\NC \type {Umathaccent} \NC \NC \NC \NR
+\NC \type {Umathchar} \NC \NC \NC \NR
+\NC \type {Umathcharnum} \NC \NC \NC \NR
+\NC \type {Ustack} \NC \NC \NC \NR
+\NC \type {Uradical} \NC \NC \NC \NR
+\NC \type {Uroot} \NC \NC \NC \NR
+\NC \type {Uunderdelimiter} \NC \NC \NC \NR
+\NC \type {Uoverdelimiter} \NC \NC \NC \NR
+\NC \type {Udelimiterunder} \NC \NC \NC \NR
+\NC \type {Udelimiterover} \NC \NC \NC \NR
+\NC \type {Uhextensible} \NC \NC \NC \NR
+\NC \type {Uchar} \NC \NC \NC \NR
+\NC \type {Umathcharclass} \NC \NC \NC \NR
+\NC \type {Umathcharfam} \NC \NC \NC \NR
+\NC \type {Umathcharslot} \NC \NC \NC \NR
+\NC \type {Uleft} \NC \NC \NC \NR
+\NC \type {Umiddle} \NC \NC \NC \NR
+\NC \type {Uright} \NC \NC \NC \NR
+\NC \type {Uvextensible} \NC \NC \NC \NR
+\stoptabulate
+
+\stopsection
+
+\startsection[title=Boxes and directions]
+
+\starttabulate[|||p|]
+\NC \type {pardirection} \NC direction \NC \NC \NR
+\NC \type {textdirection} \NC direction \NC \NC \NR
+\NC \type {mathdirection} \NC direction \NC \NC \NR
+\NC \type {linedirection} \NC direction \NC \NC \NR
+\NC \type {breakafterdirmode} \NC integer \NC \NC \NR
+\NC \type {shapemode} \NC integer \NC \NC \NR
+\NC \type {fixupboxesmode} \NC integer \NC \NC \NR
+\NC \type {boxdirection} \NC box direction \NC \NC \NR
+\NC \type {boxorientation} \NC box orientation \NC rotation over 90, 180, 270 degrees \NC \NR
+\NC \type {boxxoffset} \NC box xoffset \NC leaves dimensions untounched \NC \NR
+\NC \type {boxyoffset} \NC box yoffset \NC leaves dimensions untounched \NC \NR
+\NC \type {boxxmove} \NC box xmove \NC offsets that reflect on dimensions \NC \NR
+\NC \type {boxymove} \NC box ymove \NC offsets that reflect on dimensions \NC \NR
+\NC \type {boxtotal} \NC box ht+dp \NC height plus depth (and when assigned halfs) \NC \NR
+\NC \type {boxattr} \NC box attr value \NC (sets) a specific attribute to a value \NC \NR
+\stoptabulate
+
+\stopsection
+
+\startsection[title=Scanning]
+
+\starttabulate[|||p|]
+\NC \type {aftergrouped} \NC text \NC like aftergroup but for given list \NC \NR
+\NC \type {alignmark} \NC \NC equivalent to hash token \NC \NR
+\NC \type {aligntab} \NC \NC equivalent to tab token \NC \NR
+\NC \type {begincsname} \NC command \NC variant of \type {\csname} that ignores undefined commands \NC \NR
+\NC \type {catcodetable} \NC integer \NC switch to catcode table \NC \NR
+\NC \type {csstring} \NC command \NC the command without preceding escape character \NC \NR
+\NC \type {endlocalcontrol} \NC command \NC switches back to the main control loop \NC \NR
+\NC \type {etoksapp} \NC tokenregister text \NC append expanded text to given tokenregister \NC \NR
+\NC \type {etokspre} \NC tokenregister text \NC prepend expanded text to given tokenregister \NC \NR
+\NC \type {expanded} \NC text \NC expands the given text \NC \NR
+\NC \type {frozen} \NN prefix \NC \NC \NR
+\NC \type {futureexpand} \NN token command command \NC expands second ot third token depending on first match \NC \NR
+\NC \type {futureexpandis} \NN token command command \NC as \type {futureexpand} but also skips pars \NC \NR
+\NC \type {futureexpandisap} \NN token command command \NC same as idem but doesn't push back skipped spaces \NC \NR
+\NC \type {gtoksapp} \NC tokenregister text \NC globally append text to given tokenregister \NC \NR
+\NC \type {gtokspre} \NC tokenregister text \NC globally prepend text to given tokenregister \NC \NR
+\NC \type {ifabsdim} \NC dimension <=> dimension \NC test the absolute value of the given dimension \NC \NR
+\NC \type {ifabsnum} \NC integer <=> integer \NC test the absolute value of the given integer \NC \NR
+\NC \type {ifcondition} \NC command \NC assume the next token is a test (so skip as if) \NC \NR
+\NC \type {ifdimen} \NC possibly a dimension \NC acts like an \type {\ifcase} with 1 for valid and 2 for invalid \NC \NR
+\NC \type {ifincsname} \NC command \NC check if we're inside a csname expansion \NC \NR
+\NC \type {ifnumval} \NC \NC \NC \NR
+\NC \type {ifdimval} \NC \NC \NC \NR
+\NC \type {ifchknum} \NC \NC \NC \NR
+\NC \type {ifchkdim} \NC \NC \NC \NR
+\NC \type {ifcmpnum} \NC \NC \NC \NR
+\NC \type {ifcmpdim} \NC \NC \NC \NR
+\NC \type {ifusercmd} \NC command \NC \NC \NR
+\NC \type {ifprotected} \NC command \NC \NC \NR
+\NC \type {iffrozen} \NC command \NC \NC \NR
+\NC \type {iftok} \NC \NC \NC \NR
+\NC \type {ifcstok} \NC \NC \NC \NR
+\NC \type {internalcodesmode} \NC integer \NC \NC \NR
+%NC \type {ifprimitive} \NC command \NC check if the given command is a primitive \NC \NR
+\NC \type {immediateassigned} \NC command \NC (todo) expand the following assignment now\NC \NR
+\NC \type {immediateassignment} \NC command \NC (todo) expand the following assignment now\NC \NR
+\NC \type {initcatcodetable} \NC integer \NC initialize catcode table \NC \NR
+\NC \type {lastnamedcs} \NC command \NC last found command of \type {\ifcsname} construction \NC \NR
+\NC \type {nospaces} \NC integer \NC don't inject spaces \NC \NR
+%NC \type {primitive} \NC command \NC expands the next primitive equivalent \NC \NR
+\NC \type {orelse} \NC condition \NC \NC \NR
+\NC \type {pxdimen} \NC dimension \NC multiplier for the \type {px} unit \NC \NR
+\NC \type {savecatcodetable} \NC integer \NC save catcode table \NC \NR
+\NC \type {scantextokens} \NC text \NC \type {\scantokens} without file side effects \NC \NR
+\NC \type {suppressifcsnameerror} \NC integer \NC recover from issues in csname testing \NC \NR
+\NC \type {suppresslongerror} \NC integer \NC make \type {\long} a nop \NC \NR
+\NC \type {suppressmathparerror} \NC integer \NC accepts \type {\par} and empty lines in math \NC \NR
+\NC \type {suppressoutererror} \NC integer \NC make \type {\outer} a nop \NC \NR
+\NC \type {suppressprimitiveerror} \NC integer \NC don't report an invalid \type {\primitive} \NC \NR
+\NC \type {toksapp} \NC tokenregister text \NC append text to given tokenregister \NC \NR
+\NC \type {tokspre} \NC tokenregister text \NC prepend text to given tokenregister \NC \NR
+\NC \type {xtoksapp} \NC tokenregister text \NC globally append expanded text to given tokenregister \NC \NR
+\NC \type {xtokspre} \NC tokenregister text \NC globally prepend expanded text to given tokenregister \NC \NR
+% new (some end-of-the-year experiment)
+\NC \type {letfrozen} \NC macro \NC sets the frozen property of a macro \NC \NR
+\NC \type {letprotected} \NC macro \NC sets the protected property of a macro \NC \NR
+\NC \type {unletfrozen} \NC macro \NC unsets the frozen property of a macro \NC \NR
+\NC \type {unletprotected} \NC macro \NC unsets the protected property of a macro \NC \NR
+\stoptabulate
+
+\stopsection
+
+\startsection[title=Typesetting]
+
+\starttabulate[|||p|]
+\NC \type {protrudechars} \NC integer \NC \NC \NR
+\NC \type {localbrokenpenalty} \NC integer \NC \NC \NR
+\NC \type {localinterlinepenalty} \NC integer \NC \NC \NR
+\NC \type {adjustspacing} \NC integer \NC \NC \NR
+\NC \type {boundary} \NC command \NC \NC \NR
+\NC \type {noboundary} \NC command \NC \NC \NR
+\NC \type {protrusionboundary} \NC command \NC \NC \NR
+\NC \type {wordboundary} \NC command \NC \NC \NR
+\NC \type {nohrule} \NC command \NC \NC \NR
+\NC \type {novrule} \NC command \NC \NC \NR
+\NC \type {insertht} \NC number \NC \NC \NR
+\NC \type {quitvmode} \NC command \NC \NC \NR
+\NC \type {leftmarginkern} \NC dimension \NC \NC \NR
+\NC \type {rightmarginkern} \NC dimension \NC \NC \NR
+\NC \type {localleftbox} \NC box \NC \NC \NR
+\NC \type {localrightbox} \NC box \NC \NC \NR
+\NC \type {gleaders} \NC command \NC \NC \NR
+\stoptabulate
+
+\stopsection
+
+\startsection[title=\LUA]
+
+\starttabulate[|||p|]
+\NC \type {luacopyinputnodes} \NC integer \NC \NC \NR
+\NC \type {luadef} \NC \NC \NC \NR
+\NC \type {luabytecodecall} \NC \NC \NC \NR
+\NC \type {luafunctioncall} \NC \NC \NC \NR
+\NC \type {latelua} \NC \NC \NC \NR
+\NC \type {lateluafunction} \NC \NC \NC \NR
+\NC \type {luabytecode} \NC \NC \NC \NR
+\NC \type {luaescapestring} \NC \NC \NC \NR
+\NC \type {luafunction} \NC \NC \NC \NR
+\stoptabulate
+
+\stopsection
+
+\startsection[title=Management]
+
+\starttabulate[|||p|]
+\NC \type {outputbox} \NC integer \NC \NC \NR
+\NC \type {clearmarks} \NC \NC \NC \NR
+\NC \type {attribute} \NC \NC \NC \NR
+\NC \type {glet} \NC \NC \NC \NR
+\NC \type {letcharcode} \NC \NC \NC \NR
+\NC \type {attributedef} \NC \NC \NC \NR
+\stoptabulate
+
+\stopsection
+
+\startsection[title=Miscellaneous]
+
+\starttabulate[|||p|]
+\NC \type {luatexversion} \NC \NC \NC \NR
+\NC \type {formatname} \NC \NC \NC \NR
+\NC \type {luatexbanner} \NC \NC \NC \NR
+\NC \type {luatexrevision} \NC \NC \NC \NR
+\stoptabulate
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-registers.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-registers.tex
new file mode 100644
index 00000000000..f230a4500ca
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-registers.tex
@@ -0,0 +1,47 @@
+\environment luametatex-style
+
+\startcomponent luametatex-registers
+
+\startchapter[title=Topics]
+
+ \placeregister[topicindex]
+
+\stopchapter
+
+\startchapter[title=Primitives]
+
+ This register contains the primitives that are mentioned in the manual. There
+ are of course many more primitives. The \LUATEX\ primitives are typeset in
+ bold. The primitives from \PDFTEX\ are not supported that way but mentioned
+ anyway.
+
+ \placeregister[primitiveindex][indicator=no]
+
+\stopchapter
+
+\startchapter[title=Callbacks]
+
+ \placeregister[callbackindex]
+
+\stopchapter
+
+\startchapter[title=Nodes]
+
+ This register contains the nodes that are known to \LUATEX. The primary nodes
+ are in bold, whatsits that are determined by their subtype are normal. The
+ names prefixed by \type {pdf_} are backend specific.
+
+ \placeregister[nodeindex]
+
+\stopchapter
+
+\startchapter[title=Libraries]
+
+ This register contains the functions available in libraries. Not all functions
+ are documented, for instance because they can be experimental or obsolete.
+
+ \placeregister[libraryindex]
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-statistics.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-statistics.tex
new file mode 100644
index 00000000000..d779a0899a8
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-statistics.tex
@@ -0,0 +1,17 @@
+% language=uk
+
+\environment luametatex-style
+
+\startcomponent luametatex-statistics
+
+\startchapter[title={Statistics}]
+
+ \topicindex{fonts+used}
+
+ The following fonts are used in this document:
+
+ \showfontusage
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-style.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-style.tex
new file mode 100644
index 00000000000..3f4b0ad2183
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-style.tex
@@ -0,0 +1,478 @@
+\startenvironment luametatex-style
+
+% \environment luatex-style
+
+% \logo[LUAMETATEX] {\Lua Meta\TeX}
+
+% todo: use \useMPlibrary[lua]
+
+\enabletrackers[fonts.usage]
+
+\usemodule[fonts-statistics]
+
+\setuplayout
+ [height=middle,
+ width=middle,
+ backspace=2cm,
+ topspace=10mm,
+ bottomspace=10mm,
+ header=10mm,
+ footer=10mm,
+ footerdistance=10mm,
+ headerdistance=10mm]
+
+\setuppagenumbering
+ [alternative=doublesided]
+
+\setuptolerance
+ [stretch,tolerant]
+
+\setuptype
+ [lines=hyphenated]
+
+\setuptyping
+ [lines=hyphenated]
+
+\setupitemize
+ [each]
+ [packed]
+
+\definesymbol[1][\Uchar"2023]
+\definesymbol[2][\endash]
+\definesymbol[3][\wait] % we want to catch it
+
+\setupitemize
+ [each]
+ [headcolor=maincolor,
+ symbolcolor=maincolor,
+ color=maincolor]
+
+\setupwhitespace
+ [medium]
+
+\setuptabulate
+ [blank={small,samepage},
+ margin=.25em,
+ headstyle=bold,
+ rulecolor=maincolor,
+ rulethickness=1pt,
+ foregroundcolor=white,
+ foregroundstyle=\ss\bfx\WORD,
+ backgroundcolor=maincolor]
+
+\setupcaptions
+ [headcolor=darkblue]
+
+\startluacode
+ local skipped = { 'id', 'subtype', 'next', 'prev' }
+
+ local function showlist(l,skipped)
+ if l then
+ l = table.tohash(l)
+ if skipped then
+ for i=1,#skipped do
+ l[skipped[i]] = nil
+ end
+ end
+ l = table.sortedkeys(l)
+ local n = #l
+ for i=1,n do
+ context("%s{\\tttf %s}", (i == 1 and "") or (i == n and " and ") or ", ", l[i])
+ end
+ end
+ end
+
+ function document.functions.showvalues(l)
+ if l then
+ local n = table.count(l)
+ local i = 0
+ for k, v in table.sortedhash(l) do
+ i = i + 1
+ context("%s{\\tttf %s} (%i)", (i == 1 and "") or (i == n and " and ") or ", ", v,k)
+ end
+ end
+ end
+
+ function document.functions.showfields(s)
+ local t = string.split(s,',')
+ showlist(node.fields(t[1],t[2]),skipped)
+ end
+
+ function document.functions.showid(s)
+ local t = string.split(s,',')
+ local i = t[1] and node.id(t[1])
+ local s = t[2] and node.subtype(t[2])
+ if s then
+ context('{\\tttf %s}, {\\tttf %s}',i,s)
+ else
+ context('{\\tttf %s}',i)
+ end
+ end
+
+ function document.functions.showsubtypes(s)
+ showlist(node.subtypes(s))
+ end
+
+\stopluacode
+
+\unexpanded\def\showfields #1{\ctxlua{document.functions.showfields("#1")}}
+\unexpanded\def\showid #1{\ctxlua{document.functions.showid("#1")}}
+\unexpanded\def\showsubtypes#1{\ctxlua{document.functions.showsubtypes("#1")}}
+\unexpanded\def\showvalues #1{\ctxlua{document.functions.showvalues(node.values("#1"))}}
+\unexpanded\def\showtypes {\ctxlua{document.functions.showvalues(node.types())}}
+
+
+\definecolor[blue] [b=.5]
+\definecolor[red] [r=.5]
+\definecolor[green] [g=.5]
+%definecolor[maincolor] [b=.5]
+%definecolor[keptcolor] [b=.5]
+%definecolor[othercolor][r=.5,g=.5]
+
+\definecolor[maincolor] [b=.5]
+\definecolor[keptcolor] [b=.5]
+\definecolor[othercolor][s=.5]
+
+\writestatus{luametatex manual}{}
+\writestatus{luametatex manual}{defining lucodaot} \usebodyfont [lucidaot]
+\writestatus{luametatex manual}{defining pagella} \usebodyfont [pagella]
+\writestatus{luametatex manual}{defining cambria} \usebodyfont [cambria]
+\writestatus{luametatex manual}{defining modern} \usebodyfont [modern]
+\writestatus{luametatex manual}{defining dejavu} \setupbodyfont[dejavu,10pt]
+\writestatus{luametatex manual}{}
+
+\setuphead [chapter] [align={flushleft,broad},style=\bfd]
+\setuphead [section] [align={flushleft,broad},style=\bfb]
+\setuphead [subsection] [align={flushleft,broad},style=\bfa]
+\setuphead [subsubsection][align={flushleft,broad},style=\bf]
+
+\setuphead [chapter] [color=maincolor]
+\setuphead [section] [color=maincolor]
+\setuphead [subsection] [color=maincolor]
+\setuphead [subsubsection][color=maincolor]
+
+\setupfloats
+ [ntop=4]
+
+\definehead
+ [remark]
+ [subsubsubject]
+
+\setupheadertexts
+ []
+
+% \setuplayout
+% [style=bold,
+% color=maincolor]
+
+\definemixedcolumns
+ [twocolumns]
+ [n=2,
+ balance=yes,
+ before=\blank,
+ after=\blank]
+
+\definemixedcolumns
+ [threecolumns]
+ [twocolumns]
+ [n=3]
+
+\definemixedcolumns
+ [fourcolumns]
+ [threecolumns]
+ [n=4]
+
+% if we do this we also need to do it in table cells
+%
+% \setuptyping
+% [color=maincolor]
+%
+% \setuptype
+% [color=maincolor]
+
+\definetyping
+ [functioncall]
+
+\startMPdefinitions
+
+ color luaplanetcolor ; luaplanetcolor := \MPcolor{maincolor} ;
+ color luaholecolor ; luaholecolor := white ;
+ numeric luaextraangle ; luaextraangle := 0 ;
+ numeric luaorbitfactor ; luaorbitfactor := .25 ;
+
+ vardef lualogo = image (
+
+ % Graphic design by A. Nakonechnyj. Copyright (c) 1998, All rights reserved.
+
+ save d, r, p ; numeric d, r, p ;
+
+ d := sqrt(2)/4 ; r := 1/4 ; p := r/8 ;
+
+ fill fullcircle scaled 1
+ withcolor luaplanetcolor ;
+ draw fullcircle rotated 40.5 scaled (1+r)
+ dashed evenly scaled p
+ withpen pencircle scaled (p/2)
+ withcolor (luaorbitfactor * luaholecolor) ;
+ fill fullcircle scaled r shifted (d+1/8,d+1/8)
+ rotated - luaextraangle
+ withcolor luaplanetcolor ;
+ fill fullcircle scaled r shifted (d-1/8,d-1/8)
+ withcolor luaholecolor ;
+ luaorbitfactor := .25 ;
+ ) enddef ;
+
+\stopMPdefinitions
+
+\startuseMPgraphic{luapage}
+ StartPage ;
+
+ fill Page withcolor \MPcolor{othercolor} ;
+
+ luaorbitfactor := 1 ;
+
+ picture p ; p := lualogo ysized (5*\measure{paperheight}/10) ;
+ draw p
+ shifted - center p
+ shifted (
+ \measure{spreadwidth} - .5*\measure{paperwidth} + \measure{spinewidth},
+ .375*\measure{paperheight}
+ )
+ ;
+
+ StopPage ;
+\stopuseMPgraphic
+
+% \starttexdefinition luaextraangle
+% % we can also just access the last page and so in mp directly
+% \ctxlua {
+% context(\lastpage == 0 and 0 or \realfolio*360/\lastpage)
+% }
+% \stoptexdefinition
+
+\startuseMPgraphic{luanumber}
+ % luaextraangle := \luaextraangle;
+ luaextraangle := if (LastPageNumber < 10) : 10 else : (RealPageNumber / LastPageNumber) * 360 fi;
+ luaorbitfactor := 0.25 ;
+ picture p ; p := lualogo ;
+ setbounds p to boundingbox fullcircle ;
+ draw p ysized 1cm ;
+\stopuseMPgraphic
+
+\definelayer
+ [page]
+ [width=\paperwidth,
+ height=\paperheight]
+
+\setupbackgrounds
+ [leftpage]
+ [background=page]
+
+\setupbackgrounds
+ [rightpage]
+ [background=page]
+
+\definemeasure[banneroffset][\bottomspace-\footerheight-\footerdistance+2cm]
+
+\startsetups pagenumber:right
+ \setlayerframed
+ [page]
+ [preset=rightbottom,x=1.0cm,y=\measure{banneroffset}]
+ [frame=off,height=1cm,offset=overlay]
+ {\strut\useMPgraphic{luanumber}}
+ \setlayerframed
+ [page]
+ [preset=rightbottom,x=2.5cm,y=\measure{banneroffset}]
+ [frame=off,height=1cm,width=1cm,offset=overlay,
+ foregroundstyle=bold,foregroundcolor=maincolor]
+ {\strut\pagenumber}
+ \setlayerframed
+ [page]
+ [preset=rightbottom,x=3.5cm,y=\measure{banneroffset}]
+ [frame=off,height=1cm,offset=overlay,
+ foregroundstyle=bold,foregroundcolor=maincolor]
+ {\strut\getmarking[chapter]}
+\stopsetups
+
+\startsetups pagenumber:left
+ \setlayerframed
+ [page]
+ [preset=leftbottom,x=3.5cm,y=\measure{banneroffset}]
+ [frame=off,height=1cm,offset=overlay,
+ foregroundstyle=bold,foregroundcolor=maincolor]
+ {\strut\getmarking[chapter]}
+ \setlayerframed
+ [page]
+ [preset=leftbottom,x=2.5cm,y=\measure{banneroffset}]
+ [frame=off,height=1cm,width=1cm,offset=overlay,
+ foregroundstyle=bold,foregroundcolor=maincolor]
+ {\strut\pagenumber}
+ \setlayerframed
+ [page]
+ [preset=leftbottom,x=1.0cm,y=\measure{banneroffset}]
+ [frame=off,height=1cm,offset=overlay]
+ {\strut\useMPgraphic{luanumber}}
+\stopsetups
+
+\unexpanded\def\nonterminal#1>{\mathematics{\langle\hbox{\rm #1}\rangle}}
+
+% taco's brainwave -) .. todo: create a typing variant so that we can avoid the !crlf
+
+\newcatcodetable\syntaxcodetable
+
+\unexpanded\def\makesyntaxcodetable
+ {\begingroup
+ \catcode`\<=13 \catcode`\|=12
+ \catcode`\!= 0 \catcode`\\=12
+ \savecatcodetable\syntaxcodetable
+ \endgroup}
+
+\makesyntaxcodetable
+
+\unexpanded\def\startsyntax {\begingroup\catcodetable\syntaxcodetable \dostartsyntax}
+\unexpanded\def\syntax {\begingroup\catcodetable\syntaxcodetable \dosyntax}
+ \let\stopsyntax \relax
+
+\unexpanded\def\syntaxenvbody#1%
+ {\par
+ \tt
+ \startnarrower
+ % \maincolor
+ #1
+ \stopnarrower
+ \par}
+
+\unexpanded\def\syntaxbody#1%
+ {\begingroup
+ % \maincolor
+ \tt #1%
+ \endgroup}
+
+\bgroup \catcodetable\syntaxcodetable
+
+!gdef!dostartsyntax#1\stopsyntax{!let<!nonterminal!syntaxenvbody{#1}!endgroup}
+!gdef!dosyntax #1{!let<!nonterminal!syntaxbody{#1}!endgroup}
+
+!egroup
+
+\definetyping
+ [texsyntax]
+% [color=maincolor]
+
+% end of wave
+
+\setupinteraction
+ [state=start,
+ focus=standard,
+ style=,
+ color=,
+ contrastcolor=]
+
+\placebookmarks
+ [chapter,section,subsection]
+
+\setuplist
+ [chapter,section,subsection,subsubsection]
+ [interaction=all,
+ width=4em]
+
+\setuplist
+ [chapter]
+ [style=bold,
+ before={\testpage[4]\blank},
+ color=keptcolor]
+
+\setuplist
+ [section]
+ [before={\testpage[3]}]
+
+\setuplist
+ [subsection,subsubsection]
+ [margin=4em,
+ width=5em]
+
+\definestartstop
+ [notabene]
+ [style=slanted]
+
+\definestartstop
+ [preamble]
+ [style=normal,
+ before=\blank,
+ after=\blank]
+
+% Hans doesn't like the bookmarks opening by default so we comment this:
+%
+% \setupinteractionscreen
+% [option=bookmark]
+
+\startbuffer[stylecalculations]
+
+ \normalexpanded{\definemeasure[spinewidth] [0pt]}
+ \normalexpanded{\definemeasure[paperwidth] [\the\paperwidth ]}
+ \normalexpanded{\definemeasure[paperheight][\the\paperheight]}
+ \normalexpanded{\definemeasure[spreadwidth][\measure{paperwidth}]}
+
+\stopbuffer
+
+\getbuffer[stylecalculations]
+
+\dontcomplain
+
+\usemodule[abbreviations-mixed]
+
+\defineregister[topicindex]
+\defineregister[primitiveindex]
+\defineregister[callbackindex]
+\defineregister[nodeindex]
+\defineregister[libraryindex]
+
+\unexpanded\def\lpr#1{\doifmode{*bodypart}{\primitiveindex[#1]{\bf\tex {#1}}}\tex {#1}}
+\unexpanded\def\prm#1{\doifmode{*bodypart}{\primitiveindex[#1]{\tex {#1}}}\tex {#1}}
+\unexpanded\def\orm#1{\doifmode{*bodypart}{\primitiveindex[#1]{\tex {#1}}}\tex {#1}}
+\unexpanded\def\cbk#1{\doifmode{*bodypart}{\callbackindex [#1]{\type {#1}}}\type{#1}}
+\unexpanded\def\nod#1{\doifmode{*bodypart}{\nodeindex [#1]{\bf\type{#1}}}\type{#1}}
+\unexpanded\def\whs#1{\doifmode{*bodypart}{\nodeindex [#1]{\type {#1}}}\type{#1}}
+\unexpanded\def\noa#1{\doifmode{*bodypart}{\nodeindex [#1]{\type {#1}}}\type{#1}}
+
+\hyphenation{sub-nodes}
+
+\def\currentlibraryindex{\namedstructureuservariable{section}{library}}
+
+\setupregister
+ [alternative=a,
+ balance=no]
+
+\setupregister
+ [libraryindex]
+ [indicator=no,before=]
+
+\setupregister
+ [libraryindex]
+ [1]
+ [textstyle=\ttbf]
+
+\setupregister
+ [libraryindex]
+ [2]
+ [textstyle=\tttf]
+
+\unexpanded\def\lib #1{\doifmode{*bodypart}{\expanded{\libraryindex{\currentlibraryindex+#1}}}\type{\currentlibraryindex.#1}}
+\unexpanded\def\libindex#1{\doifmode{*bodypart}{\expanded{\libraryindex{\currentlibraryindex+#1}}}}
+\unexpanded\def\libidx#1#2{\doifmode{*bodypart}{\expanded{\libraryindex{#1+#2}}\type{#1.#2}}}
+\unexpanded\def\lix #1#2{\doifmode{*bodypart}{\expanded{\libraryindex{#1+#2}}}}
+
+% \setstructurepageregister[][keys:1=,entries:1=]
+
+\unexpanded\def\inlineluavalue#1%
+ {{\maincolor \ctxlua {
+ local t = #1
+ if type(t) == "table" then
+ t = string.gsub(table.serialize(t,false),"="," = ")
+ else
+ t = tostring(t)
+ end
+ context.typ(t)
+ }}}
+
+\stopenvironment
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-tex.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-tex.tex
new file mode 100644
index 00000000000..25f70dd2f3e
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-tex.tex
@@ -0,0 +1,2481 @@
+% language=uk
+
+\environment luametatex-style
+
+\startcomponent luametatex-tex
+
+\startchapter[reference=tex,title={The \TEX\ related libraries}]
+
+\startsection[title={The \type {lua} library}][library=lua]
+
+\startsubsection[title={Version information}]
+
+\topicindex{libraries+\type{lua}}
+\topicindex{version}
+\topicindex{startupfile}
+
+\libindex{version}
+\libindex{startupfile}
+
+This library contains two read|-|only items:
+
+\starttyping
+<string> v = lua.version
+<string> s = lua.startupfile
+\stoptyping
+
+This returns the \LUA\ version identifier string. The value is currently
+\directlua {tex.print(lua.version)}.
+
+\stopsubsection
+
+\startsubsection[title={Table allocators}]
+
+\topicindex{tables}
+
+\libindex{newtable}
+\libindex{newindex}
+
+Sometimes performance (and memory usage) can benefit a little from
+it preallocating a table with \type {newtable}:
+
+\starttyping
+<table> t = lua.newtable(100,5000)
+\stoptyping
+
+This preallocates 100 hash entries and 5000 index entries. The \type
+{newindex} function create an indexed table with preset values:
+
+\starttyping
+<table> t = lua.newindex(2500,true)
+\stoptyping
+
+\stopsubsection
+
+\startsubsection[title={Bytecode registers}]
+
+\topicindex{bytecodes}
+\topicindex{registers+bytecodes}
+
+\libindex{bytecode}
+\libindex{setbytecode}
+\libindex{getbytecode}
+
+\LUA\ registers can be used to store \LUA\ code chunks. The accepted values for
+assignments are functions and \type {nil}. Likewise, the retrieved value is
+either a function or \type {nil}.
+
+\starttyping
+lua.bytecode[<number> n] = <function> f
+lua.bytecode[<number> n]()
+\stoptyping
+
+The contents of the \type {lua.bytecode} array is stored inside the format file
+as actual \LUA\ bytecode, so it can also be used to preload \LUA\ code. The
+function must not contain any upvalues. The associated function calls are:
+
+\startfunctioncall
+<function> f = lua.getbytecode(<number> n)
+lua.setbytecode(<number> n, <function> f)
+\stopfunctioncall
+
+Note: Since a \LUA\ file loaded using \type {loadfile(filename)} is essentially
+an anonymous function, a complete file can be stored in a bytecode register like
+this:
+
+\startfunctioncall
+lua.bytecode[n] = loadfile(filename)
+\stopfunctioncall
+
+Now all definitions (functions, variables) contained in the file can be
+created by executing this bytecode register:
+
+\startfunctioncall
+lua.bytecode[n]()
+\stopfunctioncall
+
+Note that the path of the file is stored in the \LUA\ bytecode to be used in
+stack backtraces and therefore dumped into the format file if the above code is
+used in \INITEX. If it contains private information, i.e. the user name, this
+information is then contained in the format file as well. This should be kept in
+mind when preloading files into a bytecode register in \INITEX.
+
+\stopsubsection
+
+\startsubsection[title={Chunk name registers}]
+
+\libindex{name}
+\libindex{setluaname}
+\libindex{getluaname}
+
+There is an array of 65536 (0--65535) potential chunk names for use with the
+\prm {directlua} and \lpr {latelua} primitives.
+
+\startfunctioncall
+lua.name[<number> n] = <string> s
+<string> s = lua.name[<number> n]
+\stopfunctioncall
+
+If you want to unset a \LUA\ name, you can assign \type {nil} to it. The function
+accessors are:
+
+\startfunctioncall
+lua.setluaname(<string> s,<number> n])
+<string> s = lua.getluaname(<number> n)
+\stopfunctioncall
+
+\stopsubsection
+
+\startsubsection[title={Introspection}]
+
+\libindex{getstacktop}
+\libindex{getruntime}
+\libindex{getcurrenttime}
+\libindex{getpreciseticks}
+\libindex{getpreciseseconds}
+
+The \type {getstacktop} function return a number indicating how full the \LUA\
+stack is. This function only makes sense as breakpoint when checking some
+mechanism going haywire.
+
+There are four time related helpers. The \type {getruntime} function returns the
+time passed since startup. The \type {getcurrenttime} does what its name says.
+Just play with them to see how it pays off. The \type {getpreciseticks} returns a
+number that can be used later, after a similar call, to get a difference. The
+\type {getpreciseseconds} function gets such a tick (delta) as argument and
+returns the number of seconds. Ticks can differ per operating system, but one
+always creates a reference first and then deltas to this reference.
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title={The \type {status} library}][library=status]
+
+\topicindex{libraries+\type{status}}
+
+\libindex{list}
+\libindex{resetmessages}
+\libindex{setexitcode}
+
+This contains a number of run|-|time configuration items that you may find useful
+in message reporting, as well as an iterator function that gets all of the names
+and values as a table.
+
+\startfunctioncall
+<table> info = status.list()
+\stopfunctioncall
+
+The keys in the table are the known items, the value is the current value. Almost
+all of the values in \type {status} are fetched through a metatable at run|-|time
+whenever they are accessed, so you cannot use \type {pairs} on \type {status},
+but you {\it can\/} use \type {pairs} on \type {info}, of course. If you do not
+need the full list, you can also ask for a single item by using its name as an
+index into \type {status}. The current list is:
+
+\starttabulate[|l|p|]
+\DB key \BC explanation \NC \NR
+\TB
+\NC \type{banner} \NC terminal display banner \NC \NR
+\NC \type{best_page_break} \NC the current best break (a node) \NC \NR
+\NC \type{buf_size} \NC current allocated size of the line buffer \NC \NR
+\NC \type{callbacks} \NC total number of executed callbacks so far \NC \NR
+\NC \type{cs_count} \NC number of control sequences \NC \NR
+\NC \type{dest_names_size} \NC \PDF\ destination table size \NC \NR
+\NC \type{dvi_gone} \NC written \DVI\ bytes \NC \NR
+\NC \type{dvi_ptr} \NC not yet written \DVI\ bytes \NC \NR
+\NC \type{dyn_used} \NC token (multi|-|word) memory in use \NC \NR
+\NC \type{filename} \NC name of the current input file \NC \NR
+\NC \type{fix_mem_end} \NC maximum number of used tokens \NC \NR
+\NC \type{fix_mem_min} \NC minimum number of allocated words for tokens \NC \NR
+\NC \type{fix_mem_max} \NC maximum number of allocated words for tokens \NC \NR
+\NC \type{font_ptr} \NC number of active fonts \NC \NR
+\NC \type{hash_extra} \NC extra allowed hash \NC \NR
+\NC \type{hash_size} \NC size of hash \NC \NR
+\NC \type{indirect_callbacks} \NC number of those that were themselves a result of other callbacks (e.g. file readers) \NC \NR
+\NC \type{ini_version} \NC \type {true} if this is an \INITEX\ run \NC \NR
+\NC \type{init_pool_ptr} \NC \INITEX\ string pool index \NC \NR
+\NC \type{init_str_ptr} \NC number of \INITEX\ strings \NC \NR
+\NC \type{input_ptr} \NC the level of input we're at \NC \NR
+\NC \type{inputid} \NC numeric id of the current input \NC \NR
+\NC \type{largest_used_mark} \NC max referenced marks class \NC \NR
+\NC \type{lasterrorcontext} \NC last error context string (with newlines) \NC \NR
+\NC \type{lasterrorstring} \NC last \TEX\ error string \NC \NR
+\NC \type{lastluaerrorstring} \NC last \LUA\ error string \NC \NR
+\NC \type{lastwarningstring} \NC last warning tag, normally an indication of in what part\NC \NR
+\NC \type{lastwarningtag} \NC last warning string\NC \NR
+\NC \type{linenumber} \NC location in the current input file \NC \NR
+\NC \type{log_name} \NC name of the log file \NC \NR
+\NC \type{luabytecode_bytes} \NC number of bytes in \LUA\ bytecode registers \NC \NR
+\NC \type{luabytecodes} \NC number of active \LUA\ bytecode registers \NC \NR
+\NC \type{luastate_bytes} \NC number of bytes in use by \LUA\ interpreters \NC \NR
+\NC \type{luatex_engine} \NC the \LUATEX\ engine identifier \NC \NR
+\NC \type{luatex_hashchars} \NC length to which \LUA\ hashes strings ($2^n$) \NC \NR
+\NC \type{luatex_hashtype} \NC the hash method used (in \LUAJITTEX) \NC \NR
+\NC \type{luatex_version} \NC the \LUATEX\ version number \NC \NR
+\NC \type{luatex_revision} \NC the \LUATEX\ revision string \NC \NR
+\NC \type{max_buf_stack} \NC max used buffer position \NC \NR
+\NC \type{max_in_stack} \NC max used input stack entries \NC \NR
+\NC \type{max_nest_stack} \NC max used nesting stack entries \NC \NR
+\NC \type{max_param_stack} \NC max used parameter stack entries \NC \NR
+\NC \type{max_save_stack} \NC max used save stack entries \NC \NR
+\NC \type{max_strings} \NC maximum allowed strings \NC \NR
+\NC \type{nest_size} \NC nesting stack size \NC \NR
+\NC \type{node_mem_usage} \NC a string giving insight into currently used nodes \NC \NR
+\NC \type{obj_ptr} \NC max \PDF\ object pointer \NC \NR
+\NC \type{obj_tab_size} \NC \PDF\ object table size \NC \NR
+\NC \type{output_active} \NC \type {true} if the \prm {output} routine is active \NC \NR
+\NC \type{output_file_name} \NC name of the \PDF\ or \DVI\ file \NC \NR
+\NC \type{param_size} \NC parameter stack size \NC \NR
+\NC \type{pdf_dest_names_ptr} \NC max \PDF\ destination pointer \NC \NR
+\NC \type{pdf_gone} \NC written \PDF\ bytes \NC \NR
+\NC \type{pdf_mem_ptr} \NC max \PDF\ memory used \NC \NR
+\NC \type{pdf_mem_size} \NC \PDF\ memory size \NC \NR
+\NC \type{pdf_os_cntr} \NC max \PDF\ object stream pointer \NC \NR
+\NC \type{pdf_os_objidx} \NC \PDF\ object stream index \NC \NR
+\NC \type{pdf_ptr} \NC not yet written \PDF\ bytes \NC \NR
+\NC \type{pool_ptr} \NC string pool index \NC \NR
+\NC \type{pool_size} \NC current size allocated for string characters \NC \NR
+\NC \type{save_size} \NC save stack size \NC \NR
+\NC \type{shell_escape} \NC \type {0} means disabled, \type {1} means anything is permitted, and \type {2} is restricted \NC \NR
+\NC \type{safer_option} \NC \type {1} means safer is enforced \NC \NR
+\NC \type{kpse_used} \NC \type {1} means that kpse is used \NC \NR
+\NC \type{stack_size} \NC input stack size \NC \NR
+\NC \type{str_ptr} \NC number of strings \NC \NR
+\NC \type{total_pages} \NC number of written pages \NC \NR
+\NC \type{var_mem_max} \NC number of allocated words for nodes \NC \NR
+\NC \type{var_used} \NC variable (one|-|word) memory in use \NC \NR
+\NC \type{lc_collate} \NC the value of \type {LC_COLLATE} at startup time (becomes \type {C} at startup) \NC \NR
+\NC \type{lc_ctype} \NC the value of \type {LC_CTYPE} at startup time (becomes \type {C} at startup) \NC \NR
+%NC \type{lc_monetary} \NC the value of \type {LC_MONETARY} at startup time \NC \NR
+\NC \type{lc_numeric} \NC the value of \type {LC_NUMERIC} at startup time \NC \NR
+%NC \type{lc_time} \NC the value of \type {LC_TIME} at startup time (becomes \type {C} at startup) \NC \NR
+\LL
+\stoptabulate
+
+The error and warning messages can be wiped with the \type {resetmessages}
+function. A return value can be set with \type {setexitcode}.
+
+\stopsection
+
+\startsection[title={The \type {tex} library}][library=tex]
+
+\startsubsection[title={Introduction}]
+
+\topicindex{libraries+\type{tex}}
+
+The \type {tex} table contains a large list of virtual internal \TEX\
+parameters that are partially writable.
+
+The designation \quote {virtual} means that these items are not properly defined
+in \LUA, but are only front\-ends that are handled by a metatable that operates
+on the actual \TEX\ values. As a result, most of the \LUA\ table operators (like
+\type {pairs} and \type {#}) do not work on such items.
+
+At the moment, it is possible to access almost every parameter that you can use
+after \prm {the}, is a single token or is sort of special in \TEX. This excludes
+parameters that need extra arguments, like \type {\the\scriptfont}. The subset
+comprising simple integer and dimension registers are writable as well as
+readable (like \prm {tracingcommands} and \prm {parindent}).
+
+\stopsubsection
+
+\startsubsection[title={Internal parameter values, \type {set} and \type {get}}]
+
+\topicindex{parameters+internal}
+
+\libindex{set} \libindex{get}
+
+For all the parameters in this section, it is possible to access them directly
+using their names as index in the \type {tex} table, or by using one of the
+functions \type {tex.get} and \type {tex.set}.
+
+The exact parameters and return values differ depending on the actual parameter,
+and so does whether \type {tex.set} has any effect. For the parameters that {\em
+can} be set, it is possible to use \type {global} as the first argument to \type
+{tex.set}; this makes the assignment global instead of local.
+
+\startfunctioncall
+tex.set (["global",] <string> n, ...)
+... = tex.get (<string> n)
+\stopfunctioncall
+
+Glue is kind of special because there are five values involved. The return value
+is a \nod {glue_spec} node but when you pass \type {false} as last argument to
+\type {tex.get} you get the width of the glue and when you pass \type {true} you
+get all five values. Otherwise you get a node which is a copy of the internal
+value so you are responsible for its freeing at the \LUA\ end. When you set a
+glue quantity you can either pass a \nod {glue_spec} or upto five numbers. If
+you pass \type {true} to \type {get} you get 5 values returned for a glue and
+when you pass \type {false} you only get the width returned.
+
+\subsubsection{Integer parameters}
+
+The integer parameters accept and return \LUA\ numbers. These are read|-|write:
+
+\starttwocolumns
+\starttyping
+tex.adjdemerits
+tex.binoppenalty
+tex.brokenpenalty
+tex.catcodetable
+tex.clubpenalty
+tex.day
+tex.defaulthyphenchar
+tex.defaultskewchar
+tex.delimiterfactor
+tex.displaywidowpenalty
+tex.doublehyphendemerits
+tex.endlinechar
+tex.errorcontextlines
+tex.escapechar
+tex.exhyphenpenalty
+tex.fam
+tex.finalhyphendemerits
+tex.floatingpenalty
+tex.globaldefs
+tex.hangafter
+tex.hbadness
+tex.holdinginserts
+tex.hyphenpenalty
+tex.interlinepenalty
+tex.language
+tex.lastlinefit
+tex.lefthyphenmin
+tex.linepenalty
+tex.localbrokenpenalty
+tex.localinterlinepenalty
+tex.looseness
+tex.mag
+tex.maxdeadcycles
+tex.month
+tex.newlinechar
+tex.outputpenalty
+tex.pausing
+tex.postdisplaypenalty
+tex.predisplaydirection
+tex.predisplaypenalty
+tex.pretolerance
+tex.relpenalty
+tex.righthyphenmin
+tex.savinghyphcodes
+tex.savingvdiscards
+tex.showboxbreadth
+tex.showboxdepth
+tex.time
+tex.tolerance
+tex.tracingassigns
+tex.tracingcommands
+tex.tracinggroups
+tex.tracingifs
+tex.tracinglostchars
+tex.tracingmacros
+tex.tracingnesting
+tex.tracingonline
+tex.tracingoutput
+tex.tracingpages
+tex.tracingparagraphs
+tex.tracingrestores
+tex.tracingscantokens
+tex.tracingstats
+tex.uchyph
+tex.vbadness
+tex.widowpenalty
+tex.year
+\stoptyping
+\stoptwocolumns
+
+These are read|-|only:
+
+\startthreecolumns
+\starttyping
+tex.deadcycles
+tex.insertpenalties
+tex.parshape
+tex.prevgraf
+tex.spacefactor
+\stoptyping
+\stopthreecolumns
+
+\subsubsection{Dimension parameters}
+
+The dimension parameters accept \LUA\ numbers (signifying scaled points) or
+strings (with included dimension). The result is always a number in scaled
+points. These are read|-|write:
+
+\startthreecolumns
+\starttyping
+tex.boxmaxdepth
+tex.delimitershortfall
+tex.displayindent
+tex.displaywidth
+tex.emergencystretch
+tex.hangindent
+tex.hfuzz
+tex.hoffset
+tex.hsize
+tex.lineskiplimit
+tex.mathsurround
+tex.maxdepth
+tex.nulldelimiterspace
+tex.overfullrule
+tex.pagebottomoffset
+tex.pageheight
+tex.pageleftoffset
+tex.pagerightoffset
+tex.pagetopoffset
+tex.pagewidth
+tex.parindent
+tex.predisplaysize
+tex.scriptspace
+tex.splitmaxdepth
+tex.vfuzz
+tex.voffset
+tex.vsize
+tex.prevdepth
+tex.prevgraf
+tex.spacefactor
+\stoptyping
+\stopthreecolumns
+
+These are read|-|only:
+
+\startthreecolumns
+\starttyping
+tex.pagedepth
+tex.pagefilllstretch
+tex.pagefillstretch
+tex.pagefilstretch
+tex.pagegoal
+tex.pageshrink
+tex.pagestretch
+tex.pagetotal
+\stoptyping
+\stopthreecolumns
+
+Beware: as with all \LUA\ tables you can add values to them. So, the following is
+valid:
+
+\starttyping
+tex.foo = 123
+\stoptyping
+
+When you access a \TEX\ parameter a look up takes place. For read||only variables
+that means that you will get something back, but when you set them you create a
+new entry in the table thereby making the original invisible.
+
+There are a few special cases that we make an exception for: \type {prevdepth},
+\type {prevgraf} and \type {spacefactor}. These normally are accessed via the
+\type {tex.nest} table:
+
+\starttyping
+tex.nest[tex.nest.ptr].prevdepth = p
+tex.nest[tex.nest.ptr].spacefactor = s
+\stoptyping
+
+However, the following also works:
+
+\starttyping
+tex.prevdepth = p
+tex.spacefactor = s
+\stoptyping
+
+Keep in mind that when you mess with node lists directly at the \LUA\ end you
+might need to update the top of the nesting stack's \type {prevdepth} explicitly
+as there is no way \LUATEX\ can guess your intentions. By using the accessor in
+the \type {tex} tables, you get and set the values at the top of the nesting
+stack.
+
+\subsubsection{Direction parameters}
+
+The direction states can be queried and set with:
+
+\startthreecolumns
+\starttyping
+tex.gettextdir()
+tex.getlinedir()
+tex.getmathdir()
+tex.getpardir()
+tex.settextdir(<number>)
+tex.setlinedir(<number>)
+tex.setmathdir(<number>)
+tex.setpardir(<number>)
+\stoptyping
+\stopthreecolumns
+
+and also with:
+
+\startthreecolumns
+\starttyping
+tex.textdirection
+tex.linedirection
+tex.mathdirection
+tex.pardirection
+\stoptyping
+\stopthreecolumns
+
+
+\subsubsection{Glue parameters}
+
+The glue parameters accept and return a userdata object that represents a \nod {glue_spec} node.
+
+\startthreecolumns
+\starttyping
+tex.abovedisplayshortskip
+tex.abovedisplayskip
+tex.baselineskip
+tex.belowdisplayshortskip
+tex.belowdisplayskip
+tex.leftskip
+tex.lineskip
+tex.parfillskip
+tex.parskip
+tex.rightskip
+tex.spaceskip
+tex.splittopskip
+tex.tabskip
+tex.topskip
+tex.xspaceskip
+\stoptyping
+\stopthreecolumns
+
+\subsubsection{Muglue parameters}
+
+All muglue parameters are to be used read|-|only and return a \LUA\ string.
+
+\startthreecolumns
+\starttyping
+tex.medmuskip
+tex.thickmuskip
+tex.thinmuskip
+\stoptyping
+\stopthreecolumns
+
+\subsubsection{Tokenlist parameters}
+
+The tokenlist parameters accept and return \LUA\ strings. \LUA\ strings are
+converted to and from token lists using \prm {the} \prm {toks} style expansion:
+all category codes are either space (10) or other (12). It follows that assigning
+to some of these, like \quote {tex.output}, is actually useless, but it feels bad
+to make exceptions in view of a coming extension that will accept full|-|blown
+token strings.
+
+\startthreecolumns
+\starttyping
+tex.errhelp
+tex.everycr
+tex.everydisplay
+tex.everyeof
+tex.everyhbox
+tex.everyjob
+tex.everymath
+tex.everypar
+tex.everyvbox
+tex.output
+\stoptyping
+\stopthreecolumns
+
+\stopsubsection
+
+\startsubsection[title={Convert commands}]
+
+\topicindex{convert commands}
+
+All \quote {convert} commands are read|-|only and return a \LUA\ string. The
+supported commands at this moment are:
+
+\starttwocolumns
+\starttyping
+tex.formatname
+tex.jobname
+tex.luatexbanner
+tex.luatexrevision
+tex.fontname(number)
+tex.uniformdeviate(number)
+tex.number(number)
+tex.romannumeral(number)
+tex.fontidentifier(number)
+\stoptyping
+\stoptwocolumns
+
+If you are wondering why this list looks haphazard; these are all the cases of
+the \quote {convert} internal command that do not require an argument, as well as
+the ones that require only a simple numeric value. The special (\LUA|-|only) case
+of \type {tex.fontidentifier} returns the \type {csname} string that matches a
+font id number (if there is one).
+
+\stopsubsection
+
+\startsubsection[title={Last item commands}]
+
+\topicindex{last items}
+
+All \quote {last item} commands are read|-|only and return a number. The
+supported commands at this moment are:
+
+\startthreecolumns
+\starttyping
+tex.lastpenalty
+tex.lastkern
+tex.lastskip
+tex.lastnodetype
+tex.inputlineno
+tex.lastxpos
+tex.lastypos
+tex.randomseed
+tex.luatexversion
+tex.currentgrouplevel
+tex.currentgrouptype
+tex.currentiflevel
+tex.currentiftype
+tex.currentifbranch
+\stoptyping
+\stopthreecolumns
+
+\stopsubsection
+
+\startsubsection[title={Accessing registers: \type {set*}, \type {get*} and \type {is*}}]
+
+\topicindex{attributes}
+\topicindex{registers}
+
+\libindex{attribute} \libindex{setattribute} \libindex{getattribute} \libindex{isattribute}
+\libindex{count} \libindex{setcount} \libindex{getcount} \libindex{iscount}
+\libindex{dimen} \libindex{setdimen} \libindex{getdimen} \libindex{isdimen}
+\libindex{skip} \libindex{setskip} \libindex{getskip} \libindex{isskip}
+\libindex{muskip} \libindex{setmuskip} \libindex{getmuskip} \libindex{ismuskip}
+\libindex{glue} \libindex{setglue} \libindex{getglue} \libindex{isglue}
+\libindex{muglue} \libindex{setmuglue} \libindex{getmuglue} \libindex{ismuglue}
+\libindex{toks} \libindex{settoks} \libindex{gettoks} \libindex{istoks}
+\libindex{box} \libindex{setbox} \libindex{getbox} \libindex{isbox}
+
+\libindex{scantoks}
+
+\TEX's attributes (\lpr {attribute}), counters (\prm {count}), dimensions (\prm
+{dimen}), skips (\prm {skip}, \prm {muskip}) and token (\prm {toks}) registers
+can be accessed and written to using two times five virtual sub|-|tables of the
+\type {tex} table:
+
+\startthreecolumns
+\starttyping
+tex.attribute
+tex.count
+tex.dimen
+tex.skip
+tex.glue
+tex.muskip
+tex.muglue
+tex.toks
+\stoptyping
+\stopthreecolumns
+
+It is possible to use the names of relevant \lpr {attributedef}, \prm {countdef},
+\prm {dimendef}, \prm {skipdef}, or \prm {toksdef} control sequences as indices
+to these tables:
+
+\starttyping
+tex.count.scratchcounter = 0
+enormous = tex.dimen['maxdimen']
+\stoptyping
+
+In this case, \LUATEX\ looks up the value for you on the fly. You have to use a
+valid \prm {countdef} (or \lpr {attributedef}, or \prm {dimendef}, or \prm
+{skipdef}, or \prm {toksdef}), anything else will generate an error (the intent
+is to eventually also allow \type {<chardef tokens>} and even macros that expand
+into a number).
+
+\startitemize
+
+ \startitem
+ The count registers accept and return \LUA\ numbers.
+ \stopitem
+
+ \startitem
+ The dimension registers accept \LUA\ numbers (in scaled points) or
+ strings (with an included absolute dimension; \type {em} and \type {ex}
+ and \type {px} are forbidden). The result is always a number in scaled
+ points.
+ \stopitem
+
+ \startitem
+ The token registers accept and return \LUA\ strings. \LUA\ strings are
+ converted to and from token lists using \prm {the} \prm {toks} style
+ expansion: all category codes are either space (10) or other (12).
+ \stopitem
+
+ \startitem
+ The skip registers accept and return \nod {glue_spec} userdata node
+ objects (see the description of the node interface elsewhere in this
+ manual).
+ \stopitem
+
+ \startitem
+ The glue registers are just skip registers but instead of userdata
+ are verbose.
+ \stopitem
+
+ \startitem
+ Like the counts, the attribute registers accept and return \LUA\ numbers.
+ \stopitem
+
+\stopitemize
+
+As an alternative to array addressing, there are also accessor functions defined
+for all cases, for example, here is the set of possibilities for \prm {skip}
+registers:
+
+\startfunctioncall
+tex.setskip (["global",] <number> n, <node> s)
+tex.setskip (["global",] <string> s, <node> s)
+<node> s = tex.getskip (<number> n)
+<node> s = tex.getskip (<string> s)
+\stopfunctioncall
+
+We have similar setters for \type {count}, \type {dimen}, \type {muskip}, and
+\type {toks}. Counters and dimen are represented by numbers, skips and muskips by
+nodes, and toks by strings.
+
+Again the glue variants are not using the \nod {glue-spec} userdata nodes. The
+\type {setglue} function accepts upto 5 arguments: width, stretch, shrink,
+stretch order and shrink order and the \type {getglue} function reports them,
+unless the second argument is \type {false} in which care only the width is
+returned.
+
+Here is an example usign a threesome:
+
+\startfunctioncall
+local d = tex.getdimen("foo")
+if tex.isdimen("bar") then
+ tex.setdimen("bar",d)
+end
+\stopfunctioncall
+
+There are six extra skip (glue) related helpers:
+
+\startfunctioncall
+tex.setglue (["global"], <number> n,
+ width, stretch, shrink, stretch_order, shrink_order)
+tex.setglue (["global"], <string> s,
+ width, stretch, shrink, stretch_order, shrink_order)
+width, stretch, shrink, stretch_order, shrink_order =
+ tex.getglue (<number> n)
+width, stretch, shrink, stretch_order, shrink_order =
+ tex.getglue (<string> s)
+\stopfunctioncall
+
+The other two are \type {tex.setmuglue} and \type {tex.getmuglue}.
+
+There are such helpers for \type {dimen}, \type {count}, \type {skip}, \type
+{muskip}, \type {box} and \type {attribute} registers but the glue ones
+are special because they have to deal with more properties.
+
+As with the general \type {get} and \type {set} function discussed before, for
+the skip registers \type {getskip} returns a node and \type {getglue} returns
+numbers, while \type {setskip} accepts a node and \type {setglue} expects upto 5
+numbers. Again, when you pass \type {false} as second argument to \type {getglue}
+you only get the width returned. The same is true for the \type {mu} variants
+\type {getmuskip}, \type {setmuskip}, \type {getmuskip} and\type {setmuskip}.
+
+For tokens registers we have an alternative where a catcode table is specified:
+
+\startfunctioncall
+tex.scantoks(0,3,"$e=mc^2$")
+tex.scantoks("global",0,3,"$\int\limits^1_2$")
+\stopfunctioncall
+
+In the function-based interface, it is possible to define values globally by
+using the string \type {global} as the first function argument.
+
+\stopsubsection
+
+\startsubsection[title={Character code registers: \type {[get|set]*code[s]}}]
+
+\topicindex{characters+codes}
+
+\libindex{lccode} \libindex{setlccode} \libindex{getlccode}
+\libindex{uccode} \libindex{setuccode} \libindex{getuccode}
+\libindex{sfcode} \libindex{setsfcode} \libindex{getsfcode}
+\libindex{catcode} \libindex{setcatcode} \libindex{getcatcode}
+\libindex{mathcode} \libindex{setmathcode} \libindex{getmathcode}
+\libindex{delcode} \libindex{setdelcode} \libindex{getdelcode}
+
+\libindex{setdelcodes} \libindex{getdelcodes}
+\libindex{setmathcodes} \libindex{getmathcodes}
+
+\TEX's character code tables (\prm {lccode}, \prm {uccode}, \prm {sfcode}, \prm
+{catcode}, \prm {mathcode}, \prm {delcode}) can be accessed and written to using
+six virtual subtables of the \type {tex} table
+
+\startthreecolumns
+\starttyping
+tex.lccode
+tex.uccode
+tex.sfcode
+tex.catcode
+tex.mathcode
+tex.delcode
+\stoptyping
+\stopthreecolumns
+
+The function call interfaces are roughly as above, but there are a few twists.
+\type {sfcode}s are the simple ones:
+
+\startfunctioncall
+tex.setsfcode (["global",] <number> n, <number> s)
+<number> s = tex.getsfcode (<number> n)
+\stopfunctioncall
+
+The function call interface for \type {lccode} and \type {uccode} additionally
+allows you to set the associated sibling at the same time:
+
+\startfunctioncall
+tex.setlccode (["global"], <number> n, <number> lc)
+tex.setlccode (["global"], <number> n, <number> lc, <number> uc)
+<number> lc = tex.getlccode (<number> n)
+tex.setuccode (["global"], <number> n, <number> uc)
+tex.setuccode (["global"], <number> n, <number> uc, <number> lc)
+<number> uc = tex.getuccode (<number> n)
+\stopfunctioncall
+
+The function call interface for \type {catcode} also allows you to specify a
+category table to use on assignment or on query (default in both cases is the
+current one):
+
+\startfunctioncall
+tex.setcatcode (["global"], <number> n, <number> c)
+tex.setcatcode (["global"], <number> cattable, <number> n, <number> c)
+<number> lc = tex.getcatcode (<number> n)
+<number> lc = tex.getcatcode (<number> cattable, <number> n)
+\stopfunctioncall
+
+The interfaces for \type {delcode} and \type {mathcode} use small array tables to
+set and retrieve values:
+
+\startfunctioncall
+tex.setmathcode (["global"], <number> n, <table> mval )
+<table> mval = tex.getmathcode (<number> n)
+tex.setdelcode (["global"], <number> n, <table> dval )
+<table> dval = tex.getdelcode (<number> n)
+\stopfunctioncall
+
+Where the table for \type {mathcode} is an array of 3 numbers, like this:
+
+\starttyping
+{
+ <number> class,
+ <number> family,
+ <number> character
+}
+\stoptyping
+
+And the table for \type {delcode} is an array with 4 numbers, like this:
+
+\starttyping
+{
+ <number> small_fam,
+ <number> small_char,
+ <number> large_fam,
+ <number> large_char
+}
+\stoptyping
+
+You can also avoid the table:
+
+\startfunctioncall
+tex.setmathcode (["global"], <number> n, <number> class,
+ <number> family, <number> character)
+class, family, char =
+ tex.getmathcodes (<number> n)
+tex.setdelcode (["global"], <number> n, <number> smallfam,
+ <number> smallchar, <number> largefam, <number> largechar)
+smallfam, smallchar, largefam, largechar =
+ tex.getdelcodes (<number> n)
+\stopfunctioncall
+
+Normally, the third and fourth values in a delimiter code assignment will be zero
+according to \lpr {Udelcode} usage, but the returned table can have values there
+(if the delimiter code was set using \prm {delcode}, for example). Unset \type
+{delcode}'s can be recognized because \type {dval[1]} is $-1$.
+
+\stopsubsection
+
+\startsubsection[title={Box registers: \type {[get|set]box}}]
+
+\topicindex{registers}
+\topicindex{boxes}
+
+\libindex{box}
+\libindex{setbox} \libindex{getbox}
+
+It is possible to set and query actual boxes, coming for instance from \prm
+{hbox}, \prm {vbox} or \prm {vtop}, using the node interface as defined in the
+\type {node} library:
+
+\starttyping
+tex.box
+\stoptyping
+
+for array access, or
+
+\starttyping
+tex.setbox(["global",] <number> n, <node> s)
+tex.setbox(["global",] <string> cs, <node> s)
+<node> n = tex.getbox(<number> n)
+<node> n = tex.getbox(<string> cs)
+\stoptyping
+
+for function|-|based access. In the function-based interface, it is possible to
+define values globally by using the string \type {global} as the first function
+argument.
+
+Be warned that an assignment like
+
+\starttyping
+tex.box[0] = tex.box[2]
+\stoptyping
+
+does not copy the node list, it just duplicates a node pointer. If \type {\box2}
+will be cleared by \TEX\ commands later on, the contents of \type {\box0} becomes
+invalid as well. To prevent this from happening, always use \type
+{node.copy_list} unless you are assigning to a temporary variable:
+
+\starttyping
+tex.box[0] = node.copy_list(tex.box[2])
+\stoptyping
+
+\stopsubsection
+
+\startsubsection[title={\type {triggerbuildpage}}]
+
+\topicindex{pages}
+
+\libindex{triggerbuildpage}
+
+You should not expect to much from the \type {triggerbuildpage} helpers because
+often \TEX\ doesn't do much if it thinks nothing has to be done, but it might be
+useful for some applications. It just does as it says it calls the internal
+function that build a page, given that there is something to build.
+
+\stopsubsection
+
+\startsubsection[title={\type {splitbox}}]
+
+\topicindex{boxes+split}
+
+\libindex{splitbox}
+
+You can split a box:
+
+\starttyping
+local vlist = tex.splitbox(n,height,mode)
+\stoptyping
+
+The remainder is kept in the original box and a packaged vlist is returned. This
+operation is comparable to the \prm {vsplit} operation. The mode can be \type
+{additional} or \type {exactly} and concerns the split off box.
+
+\stopsubsection
+
+\startsubsection[title={Accessing math parameters: \type {[get|set]math}}]
+
+\topicindex{math+parameters}
+\topicindex{parameters+math}
+
+\libindex{setmath}
+\libindex{getmath}
+
+It is possible to set and query the internal math parameters using:
+
+\startfunctioncall
+tex.setmath(["global",] <string> n, <string> t, <number> n)
+<number> n = tex.getmath(<string> n, <string> t)
+\stopfunctioncall
+
+As before an optional first parameter \type {global} indicates a global
+assignment.
+
+The first string is the parameter name minus the leading \quote {Umath}, and the
+second string is the style name minus the trailing \quote {style}. Just to be
+complete, the values for the math parameter name are:
+
+\starttyping
+quad axis operatorsize
+overbarkern overbarrule overbarvgap
+underbarkern underbarrule underbarvgap
+radicalkern radicalrule radicalvgap
+radicaldegreebefore radicaldegreeafter radicaldegreeraise
+stackvgap stacknumup stackdenomdown
+fractionrule fractionnumvgap fractionnumup
+fractiondenomvgap fractiondenomdown fractiondelsize
+limitabovevgap limitabovebgap limitabovekern
+limitbelowvgap limitbelowbgap limitbelowkern
+underdelimitervgap underdelimiterbgap
+overdelimitervgap overdelimiterbgap
+subshiftdrop supshiftdrop subshiftdown
+subsupshiftdown subtopmax supshiftup
+supbottommin supsubbottommax subsupvgap
+spaceafterscript connectoroverlapmin
+ordordspacing ordopspacing ordbinspacing ordrelspacing
+ordopenspacing ordclosespacing ordpunctspacing ordinnerspacing
+opordspacing opopspacing opbinspacing oprelspacing
+opopenspacing opclosespacing oppunctspacing opinnerspacing
+binordspacing binopspacing binbinspacing binrelspacing
+binopenspacing binclosespacing binpunctspacing bininnerspacing
+relordspacing relopspacing relbinspacing relrelspacing
+relopenspacing relclosespacing relpunctspacing relinnerspacing
+openordspacing openopspacing openbinspacing openrelspacing
+openopenspacing openclosespacing openpunctspacing openinnerspacing
+closeordspacing closeopspacing closebinspacing closerelspacing
+closeopenspacing closeclosespacing closepunctspacing closeinnerspacing
+punctordspacing punctopspacing punctbinspacing punctrelspacing
+punctopenspacing punctclosespacing punctpunctspacing punctinnerspacing
+innerordspacing inneropspacing innerbinspacing innerrelspacing
+inneropenspacing innerclosespacing innerpunctspacing innerinnerspacing
+\stoptyping
+
+The values for the style parameter are:
+
+\starttyping
+display crampeddisplay
+text crampedtext
+script crampedscript
+scriptscript crampedscriptscript
+\stoptyping
+
+The value is either a number (representing a dimension or number) or a glue spec
+node representing a muskip for \type {ordordspacing} and similar spacing
+parameters.
+
+\stopsubsection
+
+\startsubsection[title={Special list heads: \type {[get|set]list}}]
+
+\topicindex{lists}
+
+\libindex{lists}
+\libindex{setlist}
+\libindex{getlist}
+
+The virtual table \type {tex.lists} contains the set of internal registers that
+keep track of building page lists.
+
+\starttabulate[|l|p|]
+\DB field \BC explanation \NC \NR
+\TB
+\NC \type{page_ins_head} \NC circular list of pending insertions \NC \NR
+\NC \type{contrib_head} \NC the recent contributions \NC \NR
+\NC \type{page_head} \NC the current page content \NC \NR
+%NC \type{temp_head} \NC \NC \NR
+\NC \type{hold_head} \NC used for held-over items for next page \NC \NR
+\NC \type{adjust_head} \NC head of the current \prm {vadjust} list \NC \NR
+\NC \type{pre_adjust_head} \NC head of the current \type {\vadjust pre} list \NC \NR
+%NC \type{align_head} \NC \NC \NR
+\NC \type{page_discards_head} \NC head of the discarded items of a page break \NC \NR
+\NC \type{split_discards_head} \NC head of the discarded items in a vsplit \NC \NR
+\LL
+\stoptabulate
+
+The getter and setter functions are \type {getlist} and \type {setlist}. You have
+to be careful with what you set as \TEX\ can have expectations with regards to
+how a list is constructed or in what state it is.
+
+\stopsubsection
+
+\startsubsection[title={Semantic nest levels: \type {getnest} and \type {ptr}}]
+
+\topicindex{nesting}
+
+\libindex{nest}
+\libindex{ptr}
+%libindex{setnest} % only a message
+\libindex{getnest}
+
+The virtual table \type {nest} contains the currently active semantic nesting
+state. It has two main parts: a zero-based array of userdata for the semantic
+nest itself, and the numerical value \type {ptr}, which gives the highest
+available index. Neither the array items in \type {nest[]} nor \type {ptr} can be
+assigned to (as this would confuse the typesetting engine beyond repair), but you
+can assign to the individual values inside the array items, e.g.\ \type
+{tex.nest[tex.nest.ptr].prevdepth}.
+
+\type {tex.nest[tex.nest.ptr]} is the current nest state, \type {nest[0]} the
+outermost (main vertical list) level. The getter function is \type {getnest}. You
+can pass a number (which gives you a list), nothing or \type {top}, which returns
+the topmost list, or the string \type {ptr} which gives you the index of the
+topmost list.
+
+The known fields are:
+
+\starttabulate[|l|l|l|p|]
+\DB key \BC type \BC modes \BC explanation \NC \NR
+\TB
+\NC \type{mode} \NC number \NC all \NC the meaning of these numbers depends on the engine
+ and sometimes even the version; you can use \typ
+ {tex.getmodevalues()} to get the mapping: positive
+ values signal vertical, horizontal and math mode,
+ while negative values indicate inner and inline
+ variants \NC \NR
+\NC \type{modeline} \NC number \NC all \NC source input line where this mode was entered in,
+ negative inside the output routine \NC \NR
+\NC \type{head} \NC node \NC all \NC the head of the current list \NC \NR
+\NC \type{tail} \NC node \NC all \NC the tail of the current list \NC \NR
+\NC \type{prevgraf} \NC number \NC vmode \NC number of lines in the previous paragraph \NC \NR
+\NC \type{prevdepth} \NC number \NC vmode \NC depth of the previous paragraph \NC \NR
+\NC \type{spacefactor} \NC number \NC hmode \NC the current space factor \NC \NR
+\NC \type{dirs} \NC node \NC hmode \NC used for temporary storage by the line break algorithm\NC \NR
+\NC \type{noad} \NC node \NC mmode \NC used for temporary storage of a pending fraction numerator,
+ for \prm {over} etc. \NC \NR
+\NC \type{delimptr} \NC node \NC mmode \NC used for temporary storage of the previous math delimiter,
+ for \prm {middle} \NC \NR
+\NC \type{mathdir} \NC boolean \NC mmode \NC true when during math processing the \lpr {mathdir} is not
+ the same as the surrounding \lpr {textdir} \NC \NR
+\NC \type{mathstyle} \NC number \NC mmode \NC the current \lpr {mathstyle} \NC \NR
+\LL
+\stoptabulate
+
+When a second string argument is given to the \type {getnest}, the value with
+that name is returned. Of course the level must be valid. When \type {setnest}
+gets a third argument that value is assigned to the field given as second
+argument.
+
+\stopsubsection
+
+\startsubsection[reference=sec:luaprint,title={Print functions}]
+
+\topicindex{printing}
+
+The \type {tex} table also contains the three print functions that are the major
+interface from \LUA\ scripting to \TEX. The arguments to these three functions
+are all stored in an in|-|memory virtual file that is fed to the \TEX\ scanner as
+the result of the expansion of \prm {directlua}.
+
+The total amount of returnable text from a \prm {directlua} command is only
+limited by available system \RAM. However, each separate printed string has to
+fit completely in \TEX's input buffer. The result of using these functions from
+inside callbacks is undefined at the moment.
+
+\subsubsection{\type {print}}
+
+\libindex{print}
+
+\startfunctioncall
+tex.print(<string> s, ...)
+tex.print(<number> n, <string> s, ...)
+tex.print(<table> t)
+tex.print(<number> n, <table> t)
+\stopfunctioncall
+
+Each string argument is treated by \TEX\ as a separate input line. If there is a
+table argument instead of a list of strings, this has to be a consecutive array
+of strings to print (the first non-string value will stop the printing process).
+
+The optional parameter can be used to print the strings using the catcode regime
+defined by \lpr {catcodetable}~\type {n}. If \type {n} is $-1$, the currently
+active catcode regime is used. If \type {n} is $-2$, the resulting catcodes are
+the result of \prm {the} \prm {toks}: all category codes are 12 (other) except for
+the space character, that has category code 10 (space). Otherwise, if \type {n}
+is not a valid catcode table, then it is ignored, and the currently active
+catcode regime is used instead.
+
+The very last string of the very last \type {tex.print} command in a \prm
+{directlua} will not have the \prm {endlinechar} appended, all others do.
+
+\subsubsection{\type {sprint}}
+
+\libindex{sprint}
+
+\startfunctioncall
+tex.sprint(<string> s, ...)
+tex.sprint(<number> n, <string> s, ...)
+tex.sprint(<table> t)
+tex.sprint(<number> n, <table> t)
+\stopfunctioncall
+
+Each string argument is treated by \TEX\ as a special kind of input line that
+makes it suitable for use as a partial line input mechanism:
+
+\startitemize[packed]
+\startitem
+ \TEX\ does not switch to the \quote {new line} state, so that leading spaces
+ are not ignored.
+\stopitem
+\startitem
+ No \prm {endlinechar} is inserted.
+\stopitem
+\startitem
+ Trailing spaces are not removed. Note that this does not prevent \TEX\ itself
+ from eating spaces as result of interpreting the line. For example, in
+
+ \starttyping
+ before\directlua{tex.sprint("\\relax")tex.sprint(" inbetween")}after
+ \stoptyping
+
+ the space before \type {in between} will be gobbled as a result of the \quote
+ {normal} scanning of \prm {relax}.
+\stopitem
+\stopitemize
+
+If there is a table argument instead of a list of strings, this has to be a
+consecutive array of strings to print (the first non-string value will stop the
+printing process).
+
+The optional argument sets the catcode regime, as with \type {tex.print}. This
+influences the string arguments (or numbers turned into strings).
+
+Although this needs to be used with care, you can also pass token or node
+userdata objects. These get injected into the stream. Tokens had best be valid
+tokens, while nodes need to be around when they get injected. Therefore it is
+important to realize the following:
+
+\startitemize
+\startitem
+ When you inject a token, you need to pass a valid token userdata object. This
+ object will be collected by \LUA\ when it no longer is referenced. When it gets
+ printed to \TEX\ the token itself gets copied so there is no interference with the
+ \LUA\ garbage collection. You manage the object yourself. Because tokens are
+ actually just numbers, there is no real extra overhead at the \TEX\ end.
+\stopitem
+\startitem
+ When you inject a node, you need to pass a valid node userdata object. The
+ node related to the object will not be collected by \LUA\ when it no longer
+ is referenced. It lives on at the \TEX\ end in its own memory space. When it
+ gets printed to \TEX\ the node reference is used assuming that node stays
+ around. There is no \LUA\ garbage collection involved. Again, you manage the
+ object yourself. The node itself is freed when \TEX\ is done with it.
+\stopitem
+\stopitemize
+
+If you consider the last remark you might realize that we have a problem when a
+printed mix of strings, tokens and nodes is reused. Inside \TEX\ the sequence
+becomes a linked list of input buffers. So, \type {"123"} or \type {"\foo{123}"}
+gets read and parsed on the fly, while \typ {<token userdata>} already is
+tokenized and effectively is a token list now. A \typ {<node userdata>} is also
+tokenized into a token list but it has a reference to a real node. Normally this
+goes fine. But now assume that you store the whole lot in a macro: in that case
+the tokenized node can be flushed many times. But, after the first such flush the
+node is used and its memory freed. You can prevent this by using copies which is
+controlled by setting \lpr {luacopyinputnodes} to a non|-|zero value. This is one
+of these fuzzy areas you have to live with if you really mess with these low
+level issues.
+
+\subsubsection{\type {tprint}}
+
+\libindex{tprint}
+
+\startfunctioncall
+tex.tprint({<number> n, <string> s, ...}, {...})
+\stopfunctioncall
+
+This function is basically a shortcut for repeated calls to \type
+{tex.sprint(<number> n, <string> s, ...)}, once for each of the supplied argument
+tables.
+
+\subsubsection{\type {cprint}}
+
+\libindex{cprint}
+
+This function takes a number indicating the to be used catcode, plus either a
+table of strings or an argument list of strings that will be pushed into the
+input stream.
+
+\startfunctioncall
+tex.cprint( 1," 1: $&{\\foo}") tex.print("\\par") -- a lot of \bgroup s
+tex.cprint( 2," 2: $&{\\foo}") tex.print("\\par") -- matching \egroup s
+tex.cprint( 9," 9: $&{\\foo}") tex.print("\\par") -- all get ignored
+tex.cprint(10,"10: $&{\\foo}") tex.print("\\par") -- all become spaces
+tex.cprint(11,"11: $&{\\foo}") tex.print("\\par") -- letters
+tex.cprint(12,"12: $&{\\foo}") tex.print("\\par") -- other characters
+tex.cprint(14,"12: $&{\\foo}") tex.print("\\par") -- comment triggers
+\stopfunctioncall
+
+% \subsubsection{\type {write}, \type {twrite}, \type {nwrite}}
+\subsubsection{\type {write}}
+
+\libindex{write}
+% \libindex{twrite}
+% \libindex{nwrite}
+
+\startfunctioncall
+tex.write(<string> s, ...)
+tex.write(<table> t)
+\stopfunctioncall
+
+Each string argument is treated by \TEX\ as a special kind of input line that
+makes it suitable for use as a quick way to dump information:
+
+\startitemize
+\item All catcodes on that line are either \quote{space} (for '~') or \quote
+ {character} (for all others).
+\item There is no \prm {endlinechar} appended.
+\stopitemize
+
+If there is a table argument instead of a list of strings, this has to be a
+consecutive array of strings to print (the first non-string value will stop the
+printing process).
+
+% The functions \type {twrite} and \type {nwrite} can be used to write a token or
+% node back to \TEX\, possibly intermixed with regular strings that will be
+% tokenized. You have to make sure that you pass the right data because sometimes
+% \TEX\ has expectations that need to be met.
+
+\stopsubsection
+
+\startsubsection[title={Helper functions}]
+
+\subsubsection{\type {round}}
+
+\topicindex {helpers}
+
+\libindex{round}
+
+\startfunctioncall
+<number> n = tex.round(<number> o)
+\stopfunctioncall
+
+Rounds \LUA\ number \type {o}, and returns a number that is in the range of a
+valid \TEX\ register value. If the number starts out of range, it generates a
+\quote {number too big} error as well.
+
+\subsubsection{\type {scale}}
+
+\libindex{scale}
+
+\startfunctioncall
+<number> n = tex.scale(<number> o, <number> delta)
+<table> n = tex.scale(table o, <number> delta)
+\stopfunctioncall
+
+Multiplies the \LUA\ numbers \type {o} and \nod {delta}, and returns a rounded
+number that is in the range of a valid \TEX\ register value. In the table
+version, it creates a copy of the table with all numeric top||level values scaled
+in that manner. If the multiplied number(s) are of range, it generates
+\quote{number too big} error(s) as well.
+
+Note: the precision of the output of this function will depend on your computer's
+architecture and operating system, so use with care! An interface to \LUATEX's
+internal, 100\% portable scale function will be added at a later date.
+
+\subsubsection{\type {number} and \type {romannumeral}}
+
+\libindex{number}
+\libindex{romannumeral}
+
+These are the companions to the primitives \prm {number} and \prm
+{romannumeral}. They can be used like:
+
+\startfunctioncall
+tex.print(tex.romannumeral(123))
+\stopfunctioncall
+
+\subsubsection{\type {fontidentifier} and \type {fontname}}
+
+\libindex{fontidentifier}
+\libindex{fontname}
+
+The first one returns the name only, the second one reports the size too.
+
+\startfunctioncall
+tex.print(tex.fontname(tex.fontname))
+tex.print(tex.fontname(tex.fontidentidier))
+\stopfunctioncall
+
+\subsubsection{\type {sp}}
+
+\libindex{sp}
+
+\startfunctioncall
+<number> n = tex.sp(<number> o)
+<number> n = tex.sp(<string> s)
+\stopfunctioncall
+
+Converts the number \type {o} or a string \type {s} that represents an explicit
+dimension into an integer number of scaled points.
+
+For parsing the string, the same scanning and conversion rules are used that
+\LUATEX\ would use if it was scanning a dimension specifier in its \TEX|-|like
+input language (this includes generating errors for bad values), expect for the
+following:
+
+\startitemize[n]
+\startitem
+ only explicit values are allowed, control sequences are not handled
+\stopitem
+\startitem
+ infinite dimension units (\type {fil...}) are forbidden
+\stopitem
+\startitem
+ \type {mu} units do not generate an error (but may not be useful either)
+\stopitem
+\stopitemize
+
+\subsubsection{\type {tex.getlinenumber} and \type {tex.setlinenumber}}
+
+\libindex{getlinenumber}
+\libindex{setlinenumber}
+
+You can mess with the current line number:
+
+\startfunctioncall
+local n = tex.getlinenumber()
+tex.setlinenumber(n+10)
+\stopfunctioncall
+
+which can be shortcut to:
+
+\startfunctioncall
+tex.setlinenumber(10,true)
+\stopfunctioncall
+
+This might be handy when you have a callback that read numbers from a file and
+combines them in one line (in which case an error message probably has to refer
+to the original line). Interference with \TEX's internal handling of numbers is
+of course possible.
+
+\subsubsection{\type {error}, \type {show_context} and \type {gethelptext}}
+
+\topicindex{errors}
+
+\libindex{error}
+\libindex{show_context}
+\libindex{gethelptext}
+
+\startfunctioncall
+tex.error(<string> s)
+tex.error(<string> s, <table> help)
+<string> s = tex.gethelptext()
+\stopfunctioncall
+
+This creates an error somewhat like the combination of \prm {errhelp} and \prm
+{errmessage} would. During this error, deletions are disabled.
+
+The array part of the \type {help} table has to contain strings, one for each
+line of error help.
+
+In case of an error the \type {show_context} function will show the current
+context where we're at (in the expansion).
+
+\subsubsection{\type {getfamilyoffont}}
+
+\libindex {getfamilyoffont}
+
+When you pass a proper family identifier the next helper will return the font
+currently associated with it.
+
+\startfunctioncall
+<integer> id = font.getfamilyoffont(<integer> fam)
+\stopfunctioncall
+
+\subsubsection{\type {[set|get]interaction}}
+
+\libindex{setinteraction}
+\libindex{getinteraction}
+
+The engine can in one of four modes:
+
+\starttabulate[|lT|l|pl|]
+\DB value \NC mode \BC meaning \NC \NR
+\TB
+\NC 0 \NC batch \NC omits all stops and omits terminal output \NC \NR
+\NC 1 \NC nonstop \NC omits all stops \NC \NR
+\NC 2 \NC scroll \NC omits error stops \NC \NR
+\NC 3 \NC errorstop \NC stops at every opportunity to interact \NC \NR
+\LL
+\stoptabulate
+
+The mode can be queried and set with:
+
+\startfunctioncall
+<integer> i = tex.getinteraction()
+tex.setinteraction(<integer> i)
+\stopfunctioncall
+
+\subsubsection{\type {runtoks} and \type {quittoks}}
+
+Because of the fact that \TEX\ is in a complex dance of expanding, dealing with
+fonts, typesetting paragraphs, messing around with boxes, building pages, and so
+on, you cannot easily run a nested \TEX\ run (read nested main loop). However,
+there is an option to force a local run with \type {runtoks}. The content of the
+given token list register gets expanded locally after which we return to where we
+triggered this expansion, at the \LUA\ end. Instead a function can get passed
+that does some work. You have to make sure that at the end \TEX\ is in a sane
+state and this is not always trivial. A more complex mechanism would complicate
+\TEX\ itself (and probably also harm performance) so this simple local expansion
+loop has to do.
+
+\startfunctioncall
+tex.runtoks(<token register>)
+tex.runtoks(<lua function>)
+tex.runtoks(<macro name>)
+tex.runtoks(<register name>)
+\stopfunctioncall
+
+When the \prm {tracingnesting} parameter is set to a value larger than~2 some
+information is reported about the state of the local loop. The return value indicates
+an error:
+
+\starttabulate[|lT|pl|]
+\DB value \NC meaning \NC \NR
+\TB
+\NC 0 \NC no error \NC \NR
+\NC 1 \NC bad register number \NC \NR
+\NC 2 \NC unknown macro or register name \NC \NR
+\NC 3 \NC macro is unsuitable for runtoks (has arguments) \NC \NR
+\LL
+\stoptabulate
+
+This function has two optional arguments in case a token register is passed:
+
+\startfunctioncall
+tex.runtoks(<token register>,force,grouped)
+\stopfunctioncall
+
+Inside for instance an \type {\edef} the \type {runtoks} function behaves (at
+least tries to) like it were an \type {\the}. This prevents unwanted side
+effects: normally in such an definition tokens remain tokens and (for instance)
+characters don't become nodes. With the second argument you can force the local
+main loop, no matter what. The third argument adds a level of grouping.
+
+You can quit the local loop with \type {\endlocalcontrol} or from the \LUA\ end
+with \type {tex.quittoks}. In that case you end one level up! Of course in the
+end that can mean that you arrive at the main level in which case an extra end
+will trigger a redundancy warning (not an abort!).
+
+\subsubsection{\type {forcehmode}}
+
+\libindex{forcehmode}
+
+An example of a (possible error triggering) complication is that \TEX\ expects to
+be in some state, say horizontal mode, and you have to make sure it is when you
+start feeding back something from \LUA\ into \TEX. Normally a user will not run
+into issues but when you start writing tokens or nodes or have a nested run there
+can be situations that you need to run \type {forcehmode}. There is no recipe for
+this and intercepting possible cases would weaken \LUATEX's flexibility.
+
+\subsubsection{\type {hashtokens}}
+
+\libindex{hashtokens}
+
+\topicindex{hash}
+
+\startfunctioncall
+for i,v in pairs (tex.hashtokens()) do ... end
+\stopfunctioncall
+
+Returns a list of names. This can be useful for debugging, but note that this
+also reports control sequences that may be unreachable at this moment due to
+local redefinitions: it is strictly a dump of the hash table. You can use \type
+{token.create} to inspect properties, for instance when the \type {command} key
+in a created table equals \type {123}, you have the \type {cmdname} value \type
+{undefined_cs}.
+
+\subsubsection{\type {definefont}}
+
+\topicindex{fonts+defining}
+
+\libindex{definefont}
+
+\startfunctioncall
+tex.definefont(<string> csname, <number> fontid)
+tex.definefont(<boolean> global, <string> csname, <number> fontid)
+\stopfunctioncall
+
+Associates \type {csname} with the internal font number \type {fontid}. The
+definition is global if (and only if) \type {global} is specified and true (the
+setting of \type {globaldefs} is not taken into account).
+
+\stopsubsection
+
+\startsubsection[reference=luaprimitives,title={Functions for dealing with primitives}]
+
+\subsubsection{\type {enableprimitives}}
+
+\libindex{enableprimitives}
+
+\topicindex{initialization}
+\topicindex{primitives}
+
+\startfunctioncall
+tex.enableprimitives(<string> prefix, <table> primitive names)
+\stopfunctioncall
+
+This function accepts a prefix string and an array of primitive names. For each
+combination of \quote {prefix} and \quote {name}, the \type
+{tex.enableprimitives} first verifies that \quote {name} is an actual primitive
+(it must be returned by one of the \type {tex.extraprimitives} calls explained
+below, or part of \TEX82, or \prm {directlua}). If it is not, \type
+{tex.enableprimitives} does nothing and skips to the next pair.
+
+But if it is, then it will construct a csname variable by concatenating the
+\quote {prefix} and \quote {name}, unless the \quote {prefix} is already the
+actual prefix of \quote {name}. In the latter case, it will discard the \quote
+{prefix}, and just use \quote {name}.
+
+Then it will check for the existence of the constructed csname. If the csname is
+currently undefined (note: that is not the same as \prm {relax}), it will
+globally define the csname to have the meaning: run code belonging to the
+primitive \quote {name}. If for some reason the csname is already defined, it
+does nothing and tries the next pair.
+
+An example:
+
+\starttyping
+tex.enableprimitives('LuaTeX', {'formatname'})
+\stoptyping
+
+will define \type {\LuaTeXformatname} with the same intrinsic meaning as the
+documented primitive \lpr {formatname}, provided that the control sequences \type
+{\LuaTeXformatname} is currently undefined.
+
+When \LUATEX\ is run with \type {--ini} only the \TEX82 primitives and \prm
+{directlua} are available, so no extra primitives {\bf at all}.
+
+If you want to have all the new functionality available using their default
+names, as it is now, you will have to add
+
+\starttyping
+\ifx\directlua\undefined \else
+ \directlua {tex.enableprimitives('',tex.extraprimitives ())}
+\fi
+\stoptyping
+
+near the beginning of your format generation file. Or you can choose different
+prefixes for different subsets, as you see fit.
+
+Calling some form of \type {tex.enableprimitives} is highly important though,
+because if you do not, you will end up with a \TEX82-lookalike that can run \LUA\
+code but not do much else. The defined csnames are (of course) saved in the
+format and will be available at runtime.
+
+\subsubsection{\type {extraprimitives}}
+
+\libindex{extraprimitives}
+
+\startfunctioncall
+<table> t = tex.extraprimitives(<string> s, ...)
+\stopfunctioncall
+
+This function returns a list of the primitives that originate from the engine(s)
+given by the requested string value(s). The possible values and their (current)
+return values are given in the following table. In addition the somewhat special
+primitives \quote{\tex{ }}, \quote{\tex {/}} and \quote{\type {-}} are defined.
+
+\startluacode
+function document.showprimitives(tag)
+ local t = tex.extraprimitives(tag)
+ table.sort(t)
+ for i=1,#t do
+ local v = t[i]
+ if v ~= ' ' and v ~= "/" and v ~= "-" then
+ context.type(v)
+ context.space()
+ end
+ end
+end
+\stopluacode
+
+\starttabulate[|l|pl|]
+\DB name \BC values \NC \NR
+\TB
+\NC tex \NC \ctxlua{document.showprimitives('tex') } \NC \NR
+\NC core \NC \ctxlua{document.showprimitives('core') } \NC \NR
+\NC etex \NC \ctxlua{document.showprimitives('etex') } \NC \NR
+\NC luatex \NC \ctxlua{document.showprimitives('luatex') } \NC \NR
+\LL
+\stoptabulate
+
+Note that \type {luatex} does not contain \type {directlua}, as that is
+considered to be a core primitive, along with all the \TEX82 primitives, so it is
+part of the list that is returned from \type {'core'}.
+
+Running \type {tex.extraprimitives} will give you the complete list of
+primitives \type {-ini} startup. It is exactly equivalent to \type
+{tex.extraprimitives("etex","luatex")}.
+
+\subsubsection{\type {primitives}}
+
+\libindex{primitives}
+
+\startfunctioncall
+<table> t = tex.primitives()
+\stopfunctioncall
+
+This function returns a list of all primitives that \LUATEX\ knows about.
+
+\stopsubsection
+
+\startsubsection[title={Core functionality interfaces}]
+
+\subsubsection{\type {badness}}
+
+\libindex{badness}
+
+\startfunctioncall
+<number> b = tex.badness(<number> t, <number> s)
+\stopfunctioncall
+
+This helper function is useful during linebreak calculations. \type {t} and \type
+{s} are scaled values; the function returns the badness for when total \type {t}
+is supposed to be made from amounts that sum to \type {s}. The returned number is
+a reasonable approximation of \mathematics {100(t/s)^3};
+
+\subsubsection{\type {tex.resetparagraph}}
+
+\topicindex {paragraphs+reset}
+
+\libindex{resetparagraph}
+
+This function resets the parameters that \TEX\ normally resets when a new paragraph
+is seen.
+
+\subsubsection{\type {linebreak}}
+
+\topicindex {linebreaks}
+
+\libindex{linebreak}
+
+\startfunctioncall
+local <node> nodelist, <table> info =
+ tex.linebreak(<node> listhead, <table> parameters)
+\stopfunctioncall
+
+The understood parameters are as follows:
+
+\starttabulate[|l|l|p|]
+\DB name \BC type \BC explanation \NC \NR
+\TB
+\NC \type{pardir} \NC string \NC \NC \NR
+\NC \type{pretolerance} \NC number \NC \NC \NR
+\NC \type{tracingparagraphs} \NC number \NC \NC \NR
+\NC \type{tolerance} \NC number \NC \NC \NR
+\NC \type{looseness} \NC number \NC \NC \NR
+\NC \type{hyphenpenalty} \NC number \NC \NC \NR
+\NC \type{exhyphenpenalty} \NC number \NC \NC \NR
+\NC \type{pdfadjustspacing} \NC number \NC \NC \NR
+\NC \type{adjdemerits} \NC number \NC \NC \NR
+\NC \type{pdfprotrudechars} \NC number \NC \NC \NR
+\NC \type{linepenalty} \NC number \NC \NC \NR
+\NC \type{lastlinefit} \NC number \NC \NC \NR
+\NC \type{doublehyphendemerits} \NC number \NC \NC \NR
+\NC \type{finalhyphendemerits} \NC number \NC \NC \NR
+\NC \type{hangafter} \NC number \NC \NC \NR
+\NC \type{interlinepenalty} \NC number or table \NC if a table, then it is an array like \prm {interlinepenalties} \NC \NR
+\NC \type{clubpenalty} \NC number or table \NC if a table, then it is an array like \prm {clubpenalties} \NC \NR
+\NC \type{widowpenalty} \NC number or table \NC if a table, then it is an array like \prm {widowpenalties} \NC \NR
+\NC \type{brokenpenalty} \NC number \NC \NC \NR
+\NC \type{emergencystretch} \NC number \NC in scaled points \NC \NR
+\NC \type{hangindent} \NC number \NC in scaled points \NC \NR
+\NC \type{hsize} \NC number \NC in scaled points \NC \NR
+\NC \type{leftskip} \NC glue_spec node \NC \NC \NR
+\NC \type{rightskip} \NC glue_spec node \NC \NC \NR
+\NC \type{parshape} \NC table \NC \NC \NR
+\LL
+\stoptabulate
+
+Note that there is no interface for \prm {displaywidowpenalties}, you have to
+pass the right choice for \type {widowpenalties} yourself.
+
+It is your own job to make sure that \type {listhead} is a proper paragraph list:
+this function does not add any nodes to it. To be exact, if you want to replace
+the core line breaking, you may have to do the following (when you are not
+actually working in the \cbk {pre_linebreak_filter} or \cbk {linebreak_filter}
+callbacks, or when the original list starting at listhead was generated in
+horizontal mode):
+
+\startitemize
+\startitem
+ add an \quote {indent box} and perhaps a \nod {local_par} node at the start
+ (only if you need them)
+\stopitem
+\startitem
+ replace any found final glue by an infinite penalty (or add such a penalty,
+ if the last node is not a glue)
+\stopitem
+\startitem
+ add a glue node for the \prm {parfillskip} after that penalty node
+\stopitem
+\startitem
+ make sure all the \type {prev} pointers are OK
+\stopitem
+\stopitemize
+
+The result is a node list, it still needs to be vpacked if you want to assign it
+to a \prm {vbox}. The returned \type {info} table contains four values that are
+all numbers:
+
+\starttabulate[|l|p|]
+\DB name \BC explanation \NC \NR
+\TB
+\NC prevdepth \NC depth of the last line in the broken paragraph \NC \NR
+\NC prevgraf \NC number of lines in the broken paragraph \NC \NR
+\NC looseness \NC the actual looseness value in the broken paragraph \NC \NR
+\NC demerits \NC the total demerits of the chosen solution \NC \NR
+\LL
+\stoptabulate
+
+Note there are a few things you cannot interface using this function: You cannot
+influence font expansion other than via \type {pdfadjustspacing}, because the
+settings for that take place elsewhere. The same is true for hbadness and hfuzz
+etc. All these are in the \type {hpack} routine, and that fetches its own
+variables via globals.
+
+\subsubsection{\type {shipout}}
+
+\topicindex {shipout}
+
+\libindex{shipout}
+
+\startfunctioncall
+tex.shipout(<number> n)
+\stopfunctioncall
+
+Ships out box number \type {n} to the output file, and clears the box register.
+
+\subsubsection{\type {getpagestate}}
+
+\topicindex {pages}
+
+\libindex{getpagestate}
+
+This helper reports the current page state: \type {empty}, \type {box_there} or
+\type {inserts_only} as integer value.
+
+\subsubsection{\type {getlocallevel}}
+
+\topicindex {nesting}
+
+\libindex{getlocallevel}
+
+This integer reports the current level of the local loop. It's only useful for
+debugging and the (relative state) numbers can change with the implementation.
+
+\stopsubsection
+
+\startsubsection[title={Randomizers}]
+
+\libindex{lua_math_random}
+\libindex{lua_math_randomseed}
+\libindex{init_rand}
+\libindex{normal_rand}
+\libindex{uniform_rand}
+\libindex{uniformdeviate}
+
+For practical reasons \LUATEX\ has its own random number generator. The original
+\LUA\ random function is available as \typ {tex.lua_math_random}. You can
+initialize with a new seed with \type {init_rand} (\typ {lua_math_randomseed} is
+equivalent to this one.
+
+There are three generators: \type {normal_rand} (no argument is used), \type
+{uniform_rand} (takes a number that will get rounded before being used) and \type
+{uniformdeviate} which behaves like the primitive and expects a scaled integer, so
+
+\startfunctioncall
+tex.print(tex.uniformdeviate(65536)/65536)
+\stopfunctioncall
+
+will give a random number between zero and one.
+
+\stopsubsection
+
+\startsubsection[reference=synctex,title={Functions related to synctex}]
+
+\topicindex {synctex}
+
+\libindex{set_synctex_mode} \libindex{get_synctex_mode}
+\libindex{set_synctex_no_files}
+\libindex{set_synctex_tag} \libindex{get_synctex_tag} \libindex{force_synctex_tag}
+\libindex{set_synctex_line} \libindex{get_synctex_line} \libindex{force_synctex_line}
+
+The next helpers only make sense when you implement your own synctex logic. Keep in
+mind that the library used in editors assumes a certain logic and is geared for
+plain and \LATEX, so after a decade users expect a certain behaviour.
+
+\starttabulate[|l|p|]
+\DB name \BC explanation \NC \NR
+\TB
+\NC \type{set_synctex_mode} \NC \type {0} is the default and used normal synctex
+ logic, \type {1} uses the values set by the next
+ helpers while \type {2} also sets these for glyph
+ nodes; \type{3} sets glyphs and glue and \type {4}
+ sets only glyphs \NC \NR
+\NC \type{set_synctex_tag} \NC set the current tag (file) value (obeys save stack) \NC \NR
+\NC \type{set_synctex_line} \NC set the current line value (obeys save stack) \NC \NR
+\NC \type{set_synctex_no_files} \NC disable synctex file logging \NC \NR
+\NC \type{get_synctex_mode} \NC returns the current mode (for values see above) \NC \NR
+\NC \type{get_synctex_tag} \NC get the currently set value of tag (file) \NC \NR
+\NC \type{get_synctex_line} \NC get the currently set value of line \NC \NR
+\NC \type{force_synctex_tag} \NC overload the tag (file) value (\type {0} resets) \NC \NR
+\NC \type{force_synctex_line} \NC overload the line value (\type {0} resets) \NC \NR
+\LL
+\stoptabulate
+
+The last one is somewhat special. Due to the way files are registered in \SYNCTEX\ we need
+to explicitly disable that feature if we provide our own alternative if we want to avoid
+that overhead. Passing a value of 1 disables registering.
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title={The \type {texconfig} table},reference=texconfig][library=texconfig]
+
+\topicindex{libraries+\type{texconfig}}
+
+\topicindex {configuration}
+
+This is a table that is created empty. A startup \LUA\ script could fill this
+table with a number of settings that are read out by the executable after loading
+and executing the startup file.
+
+\starttabulate[|l|l|l|]
+\DB key \BC type \BC default \NC \NR
+\TB
+\NC \type{max_strings} \NC number \NC 100000 \NC \NR
+\NC \type{strings_free} \NC number \NC 100 \NC \NR
+\NC \type{nest_size} \NC number \NC 50 \NC \NR
+\NC \type{max_in_open} \NC number \NC 100 \NC \NR
+\NC \type{param_size} \NC number \NC 60 \NC \NR
+\NC \type{save_size} \NC number \NC 5000 \NC \NR
+\NC \type{stack_size} \NC number \NC 500 \NC \NR
+\NC \type{expand_depth} \NC number \NC 1000 \NC \NR
+\NC \type{function_size} \NC number \NC 0 \NC \NR
+\NC \type{error_line} \NC number \NC 79 \NC \NR
+\NC \type{half_error_line} \NC number \NC 50 \NC \NR
+\NC \type{hash_extra} \NC number \NC 0 \NC \NR
+\NC \type{formatname} \NC string \NC \NC \NR
+\NC \type{jobname} \NC string \NC \NC \NR
+\LL
+\stoptabulate
+
+If no format name or jobname is given on the command line, the related keys will
+be tested first instead of simply quitting.
+
+\stopsection
+
+\startsection[title={The \type {texio} library}][library=texio]
+
+\topicindex{libraries+\type{texio}}
+\topicindex{\IO}
+
+This library takes care of the low|-|level I/O interface: writing to the log file
+and|/|or console.
+
+\startsubsection[title={\type {write}}]
+
+\libindex{write}
+
+\startfunctioncall
+texio.write(<string> target, <string> s, ...)
+texio.write(<string> s, ...)
+\stopfunctioncall
+
+Without the \type {target} argument, writes all given strings to the same
+location(s) \TEX\ writes messages to at this moment. If \prm {batchmode} is in
+effect, it writes only to the log, otherwise it writes to the log and the
+terminal. The optional \type {target} can be one of three possibilities: \type
+{term}, \type {log} or \type {term and log}.
+
+Note: If several strings are given, and if the first of these strings is or might
+be one of the targets above, the \type {target} must be specified explicitly to
+prevent \LUA\ from interpreting the first string as the target.
+
+\stopsubsection
+
+\startsubsection[title={\type {write_nl}}]
+
+\libindex{write_nl}
+
+\startfunctioncall
+texio.write_nl(<string> target, <string> s, ...)
+texio.write_nl(<string> s, ...)
+\stopfunctioncall
+
+This function behaves like \type {texio.write}, but make sure that the given
+strings will appear at the beginning of a new line. You can pass a single empty
+string if you only want to move to the next line.
+
+\stopsubsection
+
+\startsubsection[title={\type {setescape}}]
+
+\libindex{setescape}
+
+You can disable \type {^^} escaping of control characters by passing a value of
+zero.
+
+\stopsubsection
+
+\startsubsection[title={\type {closeinput}}]
+
+\libindex{closeinput}
+
+This function that should be used with care. It acts as \prm {endinput} but at
+the \LUA\ end. You can use it to (sort of) force a jump back to \TEX. Normally a
+\LUA\ will just collect prints and at the end bump an input level and flush these
+prints. This function can help you stay at the current level but you need to know
+what you're doing (or more precise: what \TEX\ is doing with input).
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title={The \type {token} library}][library=token]
+
+\startsubsection[title={The scanner}]
+
+\topicindex{libraries+\type{token}}
+\topicindex{tokens}
+
+\libindex{scan_keyword}
+\libindex{scan_keywordcs}
+\libindex{scan_int}
+\libindex{scan_real}
+\libindex{scan_float}
+\libindex{scan_dimen}
+\libindex{scan_glue}
+\libindex{scan_toks}
+\libindex{scan_code}
+\libindex{scan_string}
+\libindex{scan_argument}
+\libindex{scan_word}
+\libindex{scan_csname}
+\libindex{scan_list}
+
+The token library provides means to intercept the input and deal with it at the
+\LUA\ level. The library provides a basic scanner infrastructure that can be used
+to write macros that accept a wide range of arguments. This interface is on
+purpose kept general and as performance is quite ok. One can build additional
+parsers without too much overhead. It's up to macro package writers to see how
+they can benefit from this as the main principle behind \LUATEX\ is to provide a
+minimal set of tools and no solutions. The scanner functions are probably the
+most intriguing.
+
+\starttabulate[|l|l|p|]
+\DB function \BC argument \BC result \NC \NR
+\TB
+\NC \type{scan_keyword} \NC string \NC returns true if the given keyword is gobbled; as with
+ the regular \TEX\ keyword scanner this is case insensitive
+ (and \ASCII\ based) \NC \NR
+\NC \type{scan_keywordcs} \NC string \NC returns true if the given keyword is gobbled; this variant
+ is case sensitive and also suitable for \UTF8 \NC \NR
+\NC \type{scan_int} \NC \NC returns an integer \NC \NR
+\NC \type{scan_real} \NC \NC returns a number from e.g.\ \type {1}, \type {1.1}, \type {.1} with optional collapsed signs \NC \NR
+\NC \type{scan_float} \NC \NC returns a number from e.g.\ \type {1}, \type {1.1}, \type {.1}, \type {1.1E10}, , \type {.1e-10} with optional collapsed signs \NC \NR
+\NC \type{scan_dimen} \NC infinity, mu-units \NC returns a number representing a dimension and or two numbers being the filler and order \NC \NR
+\NC \type{scan_glue} \NC mu-units \NC returns a glue spec node \NC \NR
+\NC \type{scan_toks} \NC definer, expand \NC returns a table of tokens tokens \NC \NR
+\NC \type{scan_code} \NC bitset \NC returns a character if its category is in the given bitset (representing catcodes) \NC \NR
+\NC \type{scan_string} \NC \NC returns a string given between \type {{}}, as \type {\macro} or as sequence of characters with catcode 11 or 12 \NC \NR
+\NC \type{scan_argument} \NC \NC this one is simular to \type {scanstring} but also accepts a \type {\cs}
+ (which then get expanded) \NC \NR
+\NC \type{scan_word} \NC \NC returns a sequence of characters with catcode 11 or 12 as string \NC \NR
+\NC \type{scan_csname} \NC \NC returns \type {foo} after scanning \type {\foo} \NC \NR
+\NC \type{scan_list} \NC \NC picks up a box specification and returns a \type {[h|v]list} node \NC \NR
+\LL
+\stoptabulate
+
+The scanners can be considered stable apart from the one scanning for a token.
+The \type {scan_code} function takes an optional number, the \type {keyword}
+function a normal \LUA\ string. The \type {infinity} boolean signals that we also
+permit \type {fill} as dimension and the \type {mu-units} flags the scanner that
+we expect math units. When scanning tokens we can indicate that we are defining a
+macro, in which case the result will also provide information about what
+arguments are expected and in the result this is separated from the meaning by a
+separator token. The \type {expand} flag determines if the list will be expanded.
+
+The string scanner scans for something between curly braces and expands on the
+way, or when it sees a control sequence it will return its meaning. Otherwise it
+will scan characters with catcode \type {letter} or \type {other}. So, given the
+following definition:
+
+\startbuffer
+\def\bar{bar}
+\def\foo{foo-\bar}
+\stopbuffer
+
+\typebuffer \getbuffer
+
+we get:
+
+\starttabulate[|l|Tl|l|]
+\DB name \BC result \NC \NR
+\TB
+\NC \type {\directlua{token.scan_string()}{foo}} \NC \directlua{context("{\\red\\type {"..token.scan_string().."}}")} {foo} \NC full expansion \NC \NR
+\NC \type {\directlua{token.scan_string()}foo} \NC \directlua{context("{\\red\\type {"..token.scan_string().."}}")} foo \NC letters and others \NC \NR
+\NC \type {\directlua{token.scan_string()}\foo} \NC \directlua{context("{\\red\\type {"..token.scan_string().."}}")}\foo \NC meaning \NC \NR
+\LL
+\stoptabulate
+
+The \type {\foo} case only gives the meaning, but one can pass an already
+expanded definition (\prm {edef}'d). In the case of the braced variant one can of
+course use the \prm {detokenize} and \prm {unexpanded} primitives since there we
+do expand.
+
+The \type {scan_word} scanner can be used to implement for instance a number scanner:
+
+\starttyping
+function token.scan_number(base)
+ return tonumber(token.scan_word(),base)
+end
+\stoptyping
+
+This scanner accepts any valid \LUA\ number so it is a way to pick up floats
+in the input.
+
+You can use the \LUA\ interface as follows:
+
+\starttyping
+\directlua {
+ function mymacro(n)
+ ...
+ end
+}
+
+\def\mymacro#1{%
+ \directlua {
+ mymacro(\number\dimexpr#1)
+ }%
+}
+
+\mymacro{12pt}
+\mymacro{\dimen0}
+\stoptyping
+
+You can also do this:
+
+\starttyping
+\directlua {
+ function mymacro()
+ local d = token.scan_dimen()
+ ...
+ end
+}
+
+\def\mymacro{%
+ \directlua {
+ mymacro()
+ }%
+}
+
+\mymacro 12pt
+\mymacro \dimen0
+\stoptyping
+
+It is quite clear from looking at the code what the first method needs as
+argument(s). For the second method you need to look at the \LUA\ code to see what
+gets picked up. Instead of passing from \TEX\ to \LUA\ we let \LUA\ fetch from
+the input stream.
+
+In the first case the input is tokenized and then turned into a string, then it
+is passed to \LUA\ where it gets interpreted. In the second case only a function
+call gets interpreted but then the input is picked up by explicitly calling the
+scanner functions. These return proper \LUA\ variables so no further conversion
+has to be done. This is more efficient but in practice (given what \TEX\ has to
+do) this effect should not be overestimated. For numbers and dimensions it saves
+a bit but for passing strings conversion to and from tokens has to be done anyway
+(although we can probably speed up the process in later versions if needed).
+
+\stopsubsection
+
+\startsubsection[title={Picking up one token}]
+
+\libindex {get_next}
+\libindex {scan_token}
+\libindex {expand}
+
+The scanners look for a sequence. When you want to pick up one token from the
+input you use \type {get_next}. This creates a token with the (low level)
+properties as discussed next. This token is just the next one. If you want to
+enforce expansion first you can use \type {scan_token}. Internally tokens are
+characterized by a number that packs a lot of information. In order to access
+the bits of information a token is wrapped in a userdata object.
+
+The \type {expand} function will trigger expansion of the next token in the
+input. This can be quite unpredictable but when you call it you probably know
+enough about \TEX\ not to be too worried about that. It basically is a call to
+the internal expand related function.
+
+\stopsubsection
+
+\startsubsection[title={Creating tokens}]
+
+\libindex{create}
+\libindex{new}
+
+\libindex{is_defined}
+\libindex{is_token}
+\libindex{biggest_char}
+
+\libindex{commands}
+\libindex{command_id}
+
+\libindex{get_command}
+\libindex{get_cmdname}
+\libindex{get_csname}
+\libindex{get_id}
+\libindex{get_active}
+\libindex{get_expandable}
+\libindex{get_protected}
+\libindex{get_mode}
+\libindex{get_index}
+\libindex{get_tok}
+
+\libindex{get_next}
+
+The creator function can be used as follows:
+
+\starttyping
+local t = token.create("relax")
+\stoptyping
+
+This gives back a token object that has the properties of the \prm {relax}
+primitive. The possible properties of tokens are:
+
+\starttabulate[|l|p|]
+\DB name \BC explanation \NC \NR
+\TB
+\NC \type {command} \NC a number representing the internal command number \NC \NR
+\NC \type {cmdname} \NC the type of the command (for instance the catcode in case of a
+ character or the classifier that determines the internal
+ treatment \NC \NR
+\NC \type {csname} \NC the associated control sequence (if applicable) \NC \NR
+\NC \type {id} \NC the unique id of the token \NC \NR
+\NC \type {tok} \NC the full token number as stored in \TEX \NC \NR
+\NC \type {active} \NC a boolean indicating the active state of the token \NC \NR
+\NC \type {expandable} \NC a boolean indicating if the token (macro) is expandable \NC \NR
+\NC \type {protected} \NC a boolean indicating if the token (macro) is protected \NC \NR
+\NC \type {mode} \NC a number either representing a character or another entity \NC \NR
+\NC \type {index} \NC a number running from 0x0000 upto 0xFFFF indicating a \TEX\ register index \NC \NR
+\LL
+\stoptabulate
+
+Alternatively you can use a getter \type {get_<fieldname>} to access a property
+of a token.
+
+The numbers that represent a catcode are the same as in \TEX\ itself, so using
+this information assumes that you know a bit about \TEX's internals. The other
+numbers and names are used consistently but are not frozen. So, when you use them
+for comparing you can best query a known primitive or character first to see the
+values.
+
+You can ask for a list of commands:
+
+\starttyping
+local t = token.commands()
+\stoptyping
+
+The id of a token class can be queried as follows:
+
+\starttyping
+local id = token.command_id("math_shift")
+\stoptyping
+
+If you really know what you're doing you can create character tokens by not
+passing a string but a number:
+
+\starttyping
+local letter_x = token.create(string.byte("x"))
+local other_x = token.create(string.byte("x"),12)
+\stoptyping
+
+Passing weird numbers can give side effects so don't expect too much help with
+that. As said, you need to know what you're doing. The best way to explore the
+way these internals work is to just look at how primitives or macros or \prm
+{chardef}'d commands are tokenized. Just create a known one and inspect its
+fields. A variant that ignores the current catcode table is:
+
+\starttyping
+local whatever = token.new(123,12)
+\stoptyping
+
+You can test if a control sequence is defined with \type {is_defined}, which
+accepts a string and returns a boolean:
+
+\starttyping
+local okay = token.is_defined("foo")
+\stoptyping
+
+The largest character possible is returned by \type {biggest_char}, just in case you
+need to know that boundary condition.
+
+\stopsubsection
+
+\startsubsection[title={Macros}]
+
+\topicindex {macros}
+
+\libindex{set_macro}
+\libindex{get_macro}
+\libindex{get_meaning}
+\libindex{set_char}
+\libindex{set_lua}
+\libindex{get_functions_table}
+
+The \type {set_macro} function can get upto 4 arguments:
+
+\starttyping
+set_macro("csname","content")
+set_macro("csname","content","global")
+set_macro("csname")
+\stoptyping
+
+You can pass a catcodetable identifier as first argument:
+
+\starttyping
+set_macro(catcodetable,"csname","content")
+set_macro(catcodetable,"csname","content","global")
+set_macro(catcodetable,"csname")
+\stoptyping
+
+The results are like:
+
+\starttyping
+ \def\csname{content}
+\gdef\csname{content}
+ \def\csname{}
+\stoptyping
+
+The \type {get_macro} function can be used to get the content of a macro while
+the \type {get_meaning} function gives the meaning including the argument
+specification (as usual in \TEX\ separated by \type {->}).
+
+The \type {set_char} function can be used to do a \prm {chardef} at the
+\LUA\ end, where invalid assignments are silently ignored:
+
+\starttyping
+set_char("csname",number)
+set_char("csname",number,"global")
+\stoptyping
+
+A special one is the following:
+
+\starttyping
+set_lua("mycode",id)
+set_lua("mycode",id,"global","protected")
+\stoptyping
+
+This creates a token that refers to a \LUA\ function with an entry in the table
+that you can access with \type {lua.get_functions_table}. It is the companion
+to \lpr {luadef}. When the first (and only) argument is true the size will preset
+to the value of \type {texconfig.function_size}.
+
+\stopsubsection
+
+\startsubsection[title={Pushing back}]
+
+\libindex{get_next}
+\libindex{put_next}
+
+There is a (for now) experimental putter:
+
+\starttyping
+local t1 = token.get_next()
+local t2 = token.get_next()
+local t3 = token.get_next()
+local t4 = token.get_next()
+-- watch out, we flush in sequence
+token.put_next { t1, t2 }
+-- but this one gets pushed in front
+token.put_next ( t3, t4 )
+\stoptyping
+
+When we scan \type {wxyz!} we get \type {yzwx!} back. The argument is either a table
+with tokens or a list of tokens. The \type {token.expand} function will trigger
+expansion but what happens really depends on what you're doing where.
+
+\stopsubsection
+
+\startsubsection[title={Nota bene}]
+
+When scanning for the next token you need to keep in mind that we're not scanning
+like \TEX\ does: expanding, changing modes and doing things as it goes. When we
+scan with \LUA\ we just pick up tokens. Say that we have:
+
+\starttyping
+\bar
+\stoptyping
+
+but \type {\bar} is undefined. Normally \TEX\ will then issue an error message.
+However, when we have:
+
+\starttyping
+\def\foo{\bar}
+\stoptyping
+
+We get no error, unless we expand \type {\foo} while \type {\bar} is still
+undefined. What happens is that as soon as \TEX\ sees an undefined macro it will
+create a hash entry and when later it gets defined that entry will be reused. So,
+\type {\bar} really exists but can be in an undefined state.
+
+\startbuffer[demo]
+bar : \directlua{tex.print(token.scan_csname())}\bar
+foo : \directlua{tex.print(token.scan_csname())}\foo
+myfirstbar : \directlua{tex.print(token.scan_csname())}\myfirstbar
+\stopbuffer
+
+\startlines
+\getbuffer[demo]
+\stoplines
+
+This was entered as:
+
+\typebuffer[demo]
+
+The reason that you see \type {bar} reported and not \type {myfirstbar} is that
+\type {\bar} was already used in a previous paragraph.
+
+If we now say:
+
+\startbuffer
+\def\foo{}
+\stopbuffer
+
+\typebuffer \getbuffer
+
+we get:
+
+\startlines
+\getbuffer[demo]
+\stoplines
+
+And if we say
+
+\startbuffer
+\def\foo{\bar}
+\stopbuffer
+
+\typebuffer \getbuffer
+
+we get:
+
+\startlines
+\getbuffer[demo]
+\stoplines
+
+When scanning from \LUA\ we are not in a mode that defines (undefined) macros at
+all. There we just get the real primitive undefined macro token.
+
+\startbuffer
+\directlua{local t = token.get_next() tex.print(t.id.." "..t.tok)}\myfirstbar
+\directlua{local t = token.get_next() tex.print(t.id.." "..t.tok)}\mysecondbar
+\directlua{local t = token.get_next() tex.print(t.id.." "..t.tok)}\mythirdbar
+\stopbuffer
+
+\startlines
+\getbuffer
+\stoplines
+
+This was generated with:
+
+\typebuffer
+
+So, we do get a unique token because after all we need some kind of \LUA\ object
+that can be used and garbage collected, but it is basically the same one,
+representing an undefined control sequence.
+
+\stopsubsection
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-titlepage.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-titlepage.tex
new file mode 100644
index 00000000000..6f7a6f9a5a5
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luametatex/luametatex-titlepage.tex
@@ -0,0 +1,53 @@
+\environment luametatex-style
+
+\startcomponent luametatex-titlepage
+
+\startstandardmakeup
+
+ \switchtobodyfont
+ [mainfacemedium]
+
+ \definedfont[Bold*default at \the\dimexpr.06\paperheight\relax] \setupinterlinespace
+
+ \setlayer
+ [page]
+ {\useMPgraphic{luapage}}
+
+ \setlayerframed
+ [page]
+ [preset=righttop,
+ location=middletop,
+ hoffset=.500\measured{paperwidth},
+ voffset=.175\measured{paperheight}]
+ [align=middle,
+ foregroundcolor=white,
+ frame=off]
+ {\documentvariable{manual}\crlf Reference\crlf Manual}
+
+ \definedfont[Bold*default at 14pt] \setupinterlinespace
+
+ \setlayerframed
+ [page]
+ [preset=rightbottom,
+ offset=.025\measured{paperheight}]
+ [align=flushright,
+ foregroundcolor=white,
+ frame=off]
+ {\doifsomething{\documentvariable{status}}{\documentvariable{status}\par}
+ \currentdate[month,space,year]\par
+ Version \documentvariable{version}}
+
+ \setlayerframed
+ [page]
+ [preset=middle,
+ hoffset=-.5\dimexpr\measured{paperwidth}-\measured{spinewidth}\relax]
+ [width=.7\measured{paperwidth},
+ align=normal,
+ foregroundstyle=\bf,
+ foregroundcolor=white,
+ frame=off]
+ {\getbuffer[backpage]}
+
+\stopstandardmakeup
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luatex/luatex-fonts.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luatex/luatex-fonts.tex
index d49c63afecb..400550a96dd 100644
--- a/Master/texmf-dist/doc/context/sources/general/manuals/luatex/luatex-fonts.tex
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luatex/luatex-fonts.tex
@@ -43,6 +43,7 @@ the table are as follows:
complete control to the loader. \NC \NR
\NC \type{fullname} \NC no \NC no \NC yes \NC string \NC output font name, used as a fallback in the \PDF\ output
if the \type {psname} is not set \NC \NR
+\NC \type{subfont} \NC no \NC no \NC yes \NC number \NC default: 0, index in (\type {ttc}) font with multiple fonts \NC \NR
\NC \type{header} \NC yes \NC no \NC no \NC string \NC header comments, if any \NC \NR
\NC \type{hyphenchar} \NC no \NC no \NC yes \NC number \NC default: \TEX's \prm {hyphenchar} \NC \NR
\NC \type{parameters} \NC no \NC yes \NC yes \NC hash \NC default: 7 parameters, all zero \NC \NR
@@ -105,6 +106,11 @@ font in \type {font.fonts}. It is the actual expansion factor (a value between
\type {-shrink} and \type {stretch}, with step \type {step}) of a font that was
automatically generated by the font expansion algorithm.
+The \type {subfont} parameter can be used to specify the subfont in a \type {ttc}
+font. When given, it is used instead of the \type {psname} and \type {fullname}
+combination. The first subfont has number~1. A zero value signals using the names
+as lookup.
+
Because we store the actual state of expansion with each glyph and don't have
special font instances, we can change some font related parameters before lines
are constructed, like:
@@ -722,14 +728,18 @@ font.setfont(<number> n, <table> f)
Note that at the moment, each access to the \type {font.fonts} or call to \type
{font.getfont} creates a \LUA\ table for the whole font unless you cached it.
-This process can be quite slow.
+If you want a copy of the internal data you can use \type {font.copyfont}:
\startfunctioncall
-<table> p = font.getparameters(<number> n)
+<table> f = font.copyfont(<number> n)
\stopfunctioncall
This one will return a table of the parameters as known to \TEX. These can be
-different from the ones in the cached table.
+different from the ones in the cached table:
+
+\startfunctioncall
+<table> p = font.getparameters(<number> n)
+\stopfunctioncall
Also note the following: assignments can only be made to fonts that have already
been defined in \TEX, but have not been accessed {\it at all\/} since that
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luatex/luatex-modifications.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luatex/luatex-modifications.tex
index 50d23fb1b78..747945f55f7 100644
--- a/Master/texmf-dist/doc/context/sources/general/manuals/luatex/luatex-modifications.tex
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luatex/luatex-modifications.tex
@@ -128,6 +128,15 @@ functionality, but with a few small adaptations.
(\LUATEX\ uses the variable \type {OVFFONTS} instead of \type {VFFONTS}).
\stopitem
+\startitem
+ The primitives that report a stretch or shrink order report a value in a
+ convenient range zero upto four. Because some macro packages can break on
+ that we also provide \type {\eTeXgluestretchorder} and \type
+ {\eTeXglueshrinkorder} which report values compatible with \ETEX. The (new)
+ \type {fi} value is reported as \type {-1} (so when used in an \type
+ {\ifcase} test that value makes one end up in the \type {\else}).
+\stopitem
+
\stopitemize
\stopsubsection
@@ -253,7 +262,10 @@ backend are decoupled as much as possible.
\startitem
When \lpr {adjustspacing} has value~2, hz optimization will be applied to
glyphs and kerns. When the value is~3, only glyphs will be treated. A value
- smaller than~2 disables this feature.
+ smaller than~2 disables this feature. With value of 1, font expansion is
+ applied after \TEX's normal paragraph breaking routines have broken the
+ paragraph into lines. In this case, line breaks are identical to standard
+ \TEX\ behavior (as with \PDFTEX).
\stopitem
\startitem
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luatex/luatex-preamble.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luatex/luatex-preamble.tex
index 8293179776d..e6389528414 100644
--- a/Master/texmf-dist/doc/context/sources/general/manuals/luatex/luatex-preamble.tex
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luatex/luatex-preamble.tex
@@ -11,7 +11,7 @@
\topicindex{\LUA}
This is a reference manual, not a tutorial. This means that we discuss changes
-relative to traditonal \TEX\ and also present new functionality. As a consequence
+relative to traditional \TEX\ and also present new functionality. As a consequence
we will refer to concepts that we assume to be known or that might be explained
later.
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/luatex/luatex.tex b/Master/texmf-dist/doc/context/sources/general/manuals/luatex/luatex.tex
index 0230af73840..5a98f224379 100644
--- a/Master/texmf-dist/doc/context/sources/general/manuals/luatex/luatex.tex
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/luatex/luatex.tex
@@ -44,6 +44,9 @@
% after adding primitives: context mult-prm.mkiv
+% \enabledirectives[pdf.stripzeros]
+% \enabledirectives[metapost.stripzeros]
+
\environment luatex-style
\startmode[book]
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/metafun/metafun-basics.tex b/Master/texmf-dist/doc/context/sources/general/manuals/metafun/metafun-basics.tex
index df556e239a8..a52c7a35a63 100644
--- a/Master/texmf-dist/doc/context/sources/general/manuals/metafun/metafun-basics.tex
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/metafun/metafun-basics.tex
@@ -2835,7 +2835,7 @@ eofill fullsquare rotated 45 scaled 2cm
\typebuffer
The \type {eofill} is a \METAFUN\ extension. Hopefully the next explains a bit
-how this works (you can find explanations zon the internet).
+how this works (you can find explanations on the Internet).
\startlinecorrection[blank]
\processMPbuffer
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/musings/musings-names.tex b/Master/texmf-dist/doc/context/sources/general/manuals/musings/musings-names.tex
new file mode 100644
index 00000000000..55641ecd957
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/musings/musings-names.tex
@@ -0,0 +1,325 @@
+% language=uk
+
+\startcomponent musings-names
+
+\environment musings-style
+
+\startchapter[title={What's in a name}]
+
+\startlines \setupalign[flushright]
+Hans Hagen
+Hasselt NL
+May 2019
+\stoplines
+
+\startsection[title=\TEX]
+
+I sometimes wonder how much the fact that English is the language mostly used in
+programming environments influences the way one looks at a program. For instance,
+translating the names of an operating system \quote {windows}, an image
+manipulation program \quote {photoshop} or a text editing program \quote
+{wordperfect} to Dutch makes them sound kind of silly to me. The name can
+influence what you buy or are willing to use. These are examples of commercial
+programs but there are plenty examples of such naming in the open source universe
+too. I write this in my own bad English so that other non|-|English speakers can
+try to do a similar exercise.
+
+So, when I was reading an article about \CPU\ technology called \quote
+{thread|-|ripper} and after a while also saw the usual talk of yet another bunch
+of technologies marked as \quote {stack} and translated that to Dutch it again
+made me feel somewhat puzzled about such names. From there it was a small step to
+wondering about programming languages, and especially the ones I use: \TEX,
+\METAPOST, and \LUA.
+
+One can even wonder to what extent the quality of programming is influenced by
+the names of commands and keywords. A language name \quote {\BASIC} sounds less
+serious than \quote {C}. A meaningless \quote {\LUA} sounds different than \quote
+{\PYTHON}. Does using your native tongue make a difference? In Dutch and German
+words tend to get long. When I look at my French dictionary it is rather thin,
+but we might need accented characters. Words in a language like Polish can differ
+per usage. What if German or Spanish had been chosen as the language for what is
+now the United States? How would we perceive programming and what would look
+natural to us?
+
+\stopsection
+
+\startsection[title=\TEX]
+
+The \TEX\ language comes with a lot of so called primitives built in. Many of
+these relate to concepts in the program. For instance, a movement in horizontal
+or vertical direction that can stretch or shrink depending on what the boundary
+conditions demand, is called \quote {glue}. When discussing this in Dutch the
+word \quote {lijm} can be used and after seeing it a few times it might sound ok.
+We can probably use \quote {elastiek} (\quote {elastic}).
+
+This internal concept is actually represented to the user via the interface name
+\quote {skip}, take: \type {\abovedisplayskip} and \type {\belowdisplayskip}.
+Here the word \quote {display} refers to math that gets vertical space around it
+and is normally typeset in a somewhat larger way compared to \quote {inline}. The
+word \quote {skip} can be translated to \quote {sprong} (translated back we could
+as well get \quote {jump}). But how to translate \quote {display}? An internet
+translation can be \quote {tentoonspreiding} but apart from it being a long word
+it sounds pretty weird for something math. The combined translation of such a
+command will not work well I think so probably complete different words has to be
+made up to describe these quantities. Taco suggested that {\en \typ
+{\bovenuitstallingkortesprong}} might work for \type {\abovedisplayshortskip} but
+luckily no ordinary \TEX\ user will not set such parameters in a document source.
+
+In \CONTEXT\ we use the somewhat typographical term \type {wit} or \type
+{witruimte} for vertical spacing. Some parameters like \type {\baselineskip} can
+be translated directly to the Dutch \type {\regelafstand} which is a proper
+typographical term (\TEX\ has no concept of line height). Okay, it can become
+messy when we translate \type {\lineskip} by \typ {\interlinespace} as that
+could be seen as the baseline skip too (\quote {interlinie} comes to mind). Quite
+a mess. In many cases we probably would not handle the \type {skip} part in
+parameter: \type {leftskip} could become \type {\linkermarge} and \type
+{\parfillskip} can become \typ {\paragraafuitvulling}.
+
+Another concept is that of \quote {penalty}, or in Dutch \type {boete}. It's
+probably harder to get the combinations right, simply because they have no
+typographical meanings, they're more process controllers. I fear that most
+translations would sound pretty weird to me. So, how do they sound to a native
+English speaker? Words like \quote {club} or \quote {widow} can be translated to
+their Dutch gender neutral counterparts \quote {wees} and \quote {weduw} but how
+strange does {\nl \typ {weduwboete}} sound?
+
+The counter variables are easier. When they end on \type {char} that can become
+\type {karakter}. However, translating \type {\escapechar} with \type
+{\ontsnappingskarakter} might look a bit weird, but as that one is used very
+seldom, a weird one doesn't matter much. Operators like \type {\advance} and
+\type {\multiply} can become \type {\verhoog} and \type {\vermenigvuldig} which
+doesn't sound that strange in this context.
+
+There are \quote {rule}s and \quote {box}es. The first one can be translated to
+\quote {lijn} which sounds quite good. But what to do with the second one. We can
+use \quote {blok} (which translates back to \quote {block}) which is good when we
+start stacking things, but also with \quote {doos} which is more literal but
+sounds to me somewhat silly: \typ {\hdoos {whatever}}. I'm not so sure if I would
+have seen that in a book about \TEX, I'd looked further into the language. The
+optional keywords \quote {width} etc. can be translated well into \quote
+{breedte} etc., so no problem there.
+
+There are all kinds of very peculiar aspects that need a translation. For instance
+the (for new users intimidating) primitive \type {\futurelet}. The \quote {future}
+part is no problem as \quote {toekomst} isn't that weird but the \quote {let}
+will for sure become something very long in Dutch, so we end up with {\nl \typ
+{\toekomstigetoekenning}}, but seeing that long one, we can consider {\nl \type
+{kijkvooruit}} as reasonable alternative. It definitely leads to more verbose
+programming.
+
+Expansion is a tricky one. I have no clue what would make nice translations of
+the primitives \type {\noexpand} and \type {\expandafter}. The Dutch \quote
+{uitbreiden} simply is not sounding good here. Taco Hoekwater came up with a good
+alternative \quote {uitvouwen} for \quote {expand} and I like that one because
+we then can let bookmaker (a somewhat dubious term in itself) Willi Egger organize
+a workshop in unfolding (instead of folding).
+
+Talking of \quote {macros} is less a problem because there is no Dutch word for
+it. There are more words with no real translations: \type {\kern} for instance
+probably would need some thinking but there might be a typographical equivalent
+that can be used.
+
+The \ETEX\ and \LUATEX\ extensions introduce new names, like \type {\detokenize},
+\type {\boundary} and \type {\attribute}. The first one is hard to translate
+because again it relates to an internal concept: \type {tokens}. I get the
+feeling that translating each occurrence of \type {token} by \type {teken} kind
+of makes everything look less serious. To strip something from its special
+meaning, which is actually what \type {\detokenize} does can give weird
+translations: {\nl \typ {\onttekenen}} is not really a Dutch word so a complete
+different one has to be found that describes what happens, like \type
+{\ontwaarderen}. On the other hand, \type {\boundary} and \type {\attribute} can
+translate directly into \type {\grens} and \type {\attribuut} where the last one
+sounds mostly okay.
+
+Just to get you thinking: how would you translate \type {\looseness} (\type
+{losheid}, related to linebreaking), \type {\deadcycles} (\type {\zinlozelus}, in
+the perspective of building pages), \type {\pretolerance} (again line break
+related, here we can use something \type {tolerantie}) and \type {\prevgraf}
+(which is actually even in English a weird one but hardly used anyway, so Taco
+likes {\nl \typ {voorloopregels}})? The easy ones are \type {\omit}, \type {\meaning},
+\type {\number}, maybe even \type {\mark}. The for users often difficult to grasp
+\quote {catcode} can be simplified to \quote {code} which is proper Dutch.
+Concepts like \quote {align} translate well to \quote {uitlijnen}. Short ones
+like \type {\wd} could be a problem but any two letter combination can look bad,
+so \type {\br} could do. In the same fashion \type {\def} is ok as it is also the
+start of the Dutch \quote {definitie}. Mathematical terms like \quote {text},
+\quote {script} and \quote {scriptscript} can be confusing: \quote {tekst} will
+do but \quote {schrift} is strange.
+
+Conditionals are not the hardest part: \type {\if} becomes \type {\als}, \type
+{\else} becomes \type {\anders} and \type {\or} is \type {\of}. However, turning
+\type {\ifcase} into \type {\inhetgevaldat} can be over the top. The \type
+{\every...} register variables can also be translated quite well, by using the
+\type {\elk} or \type {\elke} prefix. They are seldom seen at the user level so
+no real problem there.
+
+The \quote {group} related commands are easy as \quote {groep} is a good Dutch
+equivalent. Even \quote {global} operations translate well (\type {globaal}). A
+dubious one is \type {\font} because we can use {\nl \typ {\lettertype}} but it's
+not really a translation. The internet translations tend towards \quote
+{fountain} kind of things.
+
+The concept of \quote {discretionary} again needs a decent typographical
+translation although \type {\hyphenation} can become \type {\afbreking},
+translating \type {\discretionary} needs some imagination. The concept of \quote
+{leaders} is again something that can best be bound to something more
+typographical because \type {\leaders} turned {\nl \typ {\leidinggevende}} is not
+an option nor is \type {\leiders}.
+
+The prefix \type {\un} as used in \type {\unhbox} can become \type {\ont} so that
+we get \type {\ontdoos} but I get the feeling that this one can be source of
+jokes. The more verbose {\nl \typ {\pakdoosuit}} (equivalent to \typ
+{\unpackbox}) would do better. To translate \type {\unvcopy} into the gibberish
+{\nl \typ {\ontdoosdecopie}} is simply ridiculous and {\nl \typ
+{\copieeruitgepaktedoos}} is a bit long. The \type {\lower} and \type {\raise} on
+the other hand translate well to \type {\verlaag} and \type {\verhoog}. Keeping
+\type {\relax} untranslated sounds ok to me, because \type {\ontspan} really
+makes a language silly.
+
+\stopsection
+
+\startsection[title=\METAPOST]
+
+The \TEX\ language is driving a macro system while \LUA\ is a procedural
+language. The \METAPOST\ language sits somewhere in between. It is still
+expanding all along but it looks a bit more like a programming language with its
+loops, assignments, conditionals, expressions and (sort of) functions. As a
+consequence some of what I mentioned in the previous section applies here.
+
+Translation of for instance \type {truecorners} into \type {echtehoeken} can give
+the language a bit less serious image. Words like \type {linejoin}, \type
+{linecap} and \type {miterlimit} relate directly to the \POSTSCRIPT\ language so
+translating them also relates to translated \POSTSCRIPT.
+
+The \type {primary}, \type {secundary} keywords can be nicely translated into
+serious counterparts \type {primaire} and \type {secundaire} which are words that
+are not really of Dutch origin anyway. The \type {precontrol} and \type
+{postcontrol} words relate to concepts but even there the verbose \type
+{controlepuntvoor} and \type {controlepuntachter} could do. However \type {punt}
+as translation for \type {point} can be confusing because we also use that for
+\type {period}. Translating \type {controls} and \type {curl} needs some
+imagination. Words like \type {tension} becoming \type {spanning} is still
+acceptable soundwise. However:
+
+\starttyping
+voor i=1 stap 2 tot 10:
+ .....
+eindvanvoor; % or: eindvoor
+\stoptyping
+
+Kind of interesting is translating \type {if} into \type {als} because \type {fi}
+then becomes \type {sla} which is \quote {lettuce} or, when see as verb, \quote
+{hit}. The \type {true} and \type {false} keywords becoming \type {goed} and
+\type {fout} is no problem.
+
+Turning \type {atleast} into \type {opzijnminst} at first sight looks strange but
+actually I can appreciate that one. And {\nl \typ {tussendoortje}} as translation
+of \type {interim}, I can live with that one too as it sounds funny. Concepts
+like \quote {suffixes} need thinking but {\nl \typ {uitdr(ukking)}} or more
+literal {\nl \typ {expr(essie)}} for {\nl \typ {expr(ession)}} are okay. The {\nl
+\typ {expandafter}}, {\nl \typ {scantokens}} and similar keywords share the
+problem with \TEX\ that they relate to concepts that are hard to translate.
+
+The \type {redpart} and similar keywords could be translated into \type
+{rooddeel} but {\nl \typ {roodkanaal}} (meaning \type {redchannel}) might be
+better or maybe {\nl \typ {rodecomponent}}. As with \TEX\ grouping related
+keywords are no problem.
+
+A \type {pencircle} becomes \type {pencirkel}, \type {odd} becomes \type
+{oneven}, \type {reverse} becomes {\nl \typ {omgekeerd}} (or {\nl \typ
+{andersom}} or {\nl \typ {tegengesteld}}). For \type {length} we use \type
+{lengte}, and so on. All these sound professional enough, just like \quote
+{corner} related keywords becoming \quote {hoek}, although there a clash with
+\quote {angle} is possible. I'm less sure about \type {clipped} becoming {\nl
+\typ {afgeknepen}} or {\nl \typ {begrensd}} but \type {bounded} then needs some
+thinking as these all are more or less the same. The concept of \quote {stroke}
+maps onto \quote {tekenen} or \quote {vegen} but lucky us that one is not really
+used, contrary to \type {draw} that can map onto \type {teken}, while \type
+{fill} and \type {vul} match well too I guess.
+
+The transformations are no problem but I'd use a directive instead: \type
+{rotated} or \type {roteer}, \type {slanted} or \type {schuin}, \type {scaled} or
+\type {schaal}, and \type {transform} or {\nl \typ {transformeer}}. As you can
+see, these have a reasonable word length too.
+
+The concept of a \type {picture} is known in Dutch as \type {plaatje} or \type
+{tekening}: not an easy choice. Using \type {kleur} for \type {color} is no
+problem at all. A coordinate \type {pair} becomes a \type {paar}: close enough
+not to give subjective side effects. The \type {inner} and \type {outer} keywords
+translate well to \type {binnen} and \type {buiten} but in code it might look a
+bit strange.
+
+So, in general, the translated commands are not that weird but still a graphic
+defined in Dutch keywords instead of English to me might look less serious.
+
+\stopsection
+
+\startsection[title=\LUA]
+
+We now arrived at a more traditional programming language. The \LUA\ language
+only has a few keywords. I suppose that it's just a matter of time before one
+gets accustomed to \typ {als ... dan ... anders ... eind} instead of \typ {if ...
+then ... else ... end}. The loops also translate rather well: \typ {zolang ...
+doe}, \typ {herhaal .. totdat}, \typ {voor ... in ... doe ... einde} are all not
+that verbose. Also, with proper syntax highlighting they stand out and become
+abstract words. But because examples for kids are normally in Dutch, using a
+Dutch programming language might give a toy language feeling.
+
+The \type {local} directive is a bit of a problem because it should be \typ
+{lokale variabele} in order to sound ok in a sentence. The \type {goto} should
+become \type {ganaar} which is also two words with no space in between. The \type
+{function} keyword can become \type {functie}. A \type {coroutine} is a challenge
+(also conceptually); we do have \type {routine} but how about the \type {co}
+part?
+
+Because \LUA\ is such a clean language it doesn't really end up bad. In \CCODE\
+there are some more issues due to the abbreviated \type {struct}, \type {int},
+\type {char}, \type {enum} and \type {typedef}. A literal translation of \type
+{void} to \type {leegte} to me sounds a bit strange. What to do with \type
+{unsigned}? Coming up with something (short) Dutch for \type {return} is not easy
+either. Translating \type {switch} into \type {schakelaar} looks like a bad idea
+but after consulting Taco using \type {keuze} came up. The \type {break} then can
+be \type {klaar} which roundtrips to \quote {finished} and \type {default} can be
+\type {anders} which roundtrips to \quote {otherwise} which is indeed what some
+languages provide.. But, there are programming languages out there that have
+plenty keywords and that are more challenging. But as I'm a happy \LUA\ user I
+don't have to worry about them.
+
+\stopsection
+
+\startsection[title=Conclusion]
+
+Looking at a program source in Dutch the general feeling probably will be
+different. A low level bit of \TEX\ is the worst. For \METAPOST\ it's bearable
+and for \LUA\ it is kind of okay. But in all cases, I'm not convinced that it
+would give me the same feeling. The abstraction of the language due to it not
+being my native tongue makes a difference. This problem is not much different
+than what we have with popular music and songs: for non|-|native speakers it's
+basically sounds, but for a native speaker it is more clear when nonsense is
+sung. The same can happen to me with movies, where watching some scandinavian
+series is different from watching a Dutch one. In the last case one picks up
+different nuances, not necessarily for the best. But it can be worse: post
+synchronized (audio) translations can be pretty unbearable and might compare well
+to programs translated to for instance Dutch. So let's not discuss the way
+Germans would deal with this.
+
+\stopsection
+
+\startsection[title=Side notes]
+
+We now see monospaced fonts showing up that provide ligatures for e.g.\ \type
+{<=} and I've seen examples where ligatures kicked in for \type {fi}. One can
+wonder about that but ligatures are definitely something to keep in mind when
+translating.
+
+The \CONTEXT\ macro package is normally used with the English user interface. But
+the design is such that one can provide different ones too; after all it started
+out Dutch. It is beyond the scope of this musing to discuss the problems with
+translating typographical concepts between languages, especially when there are
+no distinctive words. But it can (and has) been done.
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/musings/musings-plain.tex b/Master/texmf-dist/doc/context/sources/general/manuals/musings/musings-plain.tex
new file mode 100644
index 00000000000..757f7300c55
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/musings/musings-plain.tex
@@ -0,0 +1,553 @@
+% language=uk
+
+% \showfontkerns
+
+\startcomponent musings-manuals
+
+\environment musings-style
+
+\definetyping[narrowtyping][style=\ttx]
+
+\startchapter[title={About what \CONTEXT\ isn't}]
+
+\startsection[title={Introduction}]
+
+It really puzzles me why, when someone someplace asks if \CONTEXT\ is suitable
+for her or is his needs, there are answers like: \quotation {You need to think of
+\CONTEXT\ as being kind of plain \TEX: you have to define everything yourself.}
+That answer probably stems from the fact that for \LATEX\ you load some style
+that defines a lot, which you then might need to undefine or redefine, but that's
+not part of the answer.
+
+In the following sections I will go into a bit more detail of what plain \TEX\ is
+and how it influences macro packages, especially \CONTEXT . I'm sure I have
+discussed this before so consider this another go at it.
+
+The \type {plain.tex} file start with the line:
+
+\starttyping
+% This is the plain TeX format that's described in The TeXbook.
+\stoptyping
+
+A few lines later we read:
+
+\starttyping
+% And don't modify the file under any circumstances.
+\stoptyping
+
+So, this format related to the \TEX\ reference. It serves as a template for what
+is called a macro package. Here I will not go into the details of macro programming
+but an occasional snippet of code can be illustrative.
+
+\stopsection
+
+\startsection[title={Getting started}]
+
+The first code we see in the plain file is:
+
+\startnarrowtyping
+\catcode`\{=1 % left brace is begin-group character
+\catcode`\}=2 % right brace is end-group character
+\catcode`\$=3 % dollar sign is math shift
+\catcode`\&=4 % ampersand is alignment tab
+\catcode`\#=6 % hash mark is macro parameter character
+\catcode`\^=7 \catcode`\^^K=7 % circumflex and uparrow are for superscripts
+\catcode`\_=8 \catcode`\^^A=8 % underline and downarrow are for subscripts
+\catcode`\^^I=10 % ascii tab is a blank space
+\chardef\active=13 \catcode`\~=\active % tilde is active
+\catcode`\^^L=\active \outer\def^^L{\par} % ascii form-feed is "\outer\par"
+\stopnarrowtyping
+
+Assigning catcodes to the braces and hash are needed in order to make it possible
+to define macros. The dollar is set to enter math mode and the ampersand becomes
+a separator in tables. The superscript and subscript also relate to math. Nothing
+demands these bindings but they are widely accepted. In this respect \CONTEXT\ is
+indeed like plain.
+
+The tab is made equivalent to a space and a tilde is made active which means that
+later on we need to give it some meaning. It is quite normal to make that an
+unbreakable space, and one with the width of a digit when we're doing tables.
+Now, nothing demands that we have to assume \ASCII\ input but for practical
+reasons the formfeed character is made equivalent to a \type {\par}.
+
+Now what do these \type {^^K} and similar triplets represent? The \type {^^A}
+represents character zero and normally all these control characters below decimal
+32 (space) are special. The \type {^^I} is the \ASCII\ tab character, and \type
+{^^L} the formfeed. But, the ones referred to as uparrow and downarrow in the
+comments have only meaning on certain keyboards. So these are typical definitions
+that only made sense for Don Knuth at that time and are not relevant in other
+macro packages that aim at standardized input media.
+
+\startnarrowtyping
+% We had to define the \catcodes right away, before the message line, since
+% \message uses the { and } characters. When INITEX (the TeX initializer) starts
+% up, it has defined the following \catcode values:
+%
+% \catcode`\^^@=9 % ascii null is ignored
+% \catcode`\^^M=5 % ascii return is end-line
+% \catcode`\\=0 % backslash is TeX escape character
+% \catcode`\%=14 % percent sign is comment character
+% \catcode`\ =10 % ascii space is blank space
+% \catcode`\^^?=15 % ascii delete is invalid
+% \catcode`\A=11 ... \catcode`\Z=11 % uppercase letters
+% \catcode`\a=11 ... \catcode`\z=11 % lowercase letters
+% all others are type 12 (other)
+\stopnarrowtyping
+
+The comments above speak for themselves. Changing catcodes is one way to adapt
+interpretation. For instance, in verbatim mode most catcodes can best be made
+letter or other. In \CONTEXT\ we always had so called catcode regimes: for
+defining macros, for normal text, for \XML, for verbatim, etc. In \MKIV\ this
+mechanism was adapted to the new catcode table mechanism available in that
+engine. It was one of the first things we added to \LUATEX. So, again, although
+we follow some standards (expectations) \CONTEXT\ differs from plain.
+
+\startnarrowtyping
+% We make @ signs act like letters, temporarily, to avoid conflict between user
+% names and internal control sequences of plain format.
+
+\catcode`@=11
+\stopnarrowtyping
+
+In \CONTEXT\ we went a step further and when defining macros also adapted
+the catcode of \type {!} and \type {?} and later in \MKIV\ \type {_}. When
+we're in unprotected mode this applies. In addition to regular text
+input math is dealt with:
+
+\startnarrowtyping
+% INITEX sets up \mathcode x=x, for x=0..255, except that
+%
+% \mathcode x=x+"7100, for x = `A to `Z and `a to `z;
+% \mathcode x=x+"7000, for x = `0 to `9.
+
+% The following changes define internal codes as recommended in Appendix C of
+% The TeXbook:
+
+\mathcode`\^^@="2201 % \cdot
+\mathcode`\^^A="3223 % \downarrow
+\mathcode`\^^B="010B % \alpha
+\mathcode`\^^C="010C % \beta
+....................
+\mathcode`\|="026A
+\mathcode`\}="5267
+\mathcode`\^^?="1273 % \smallint
+\stopnarrowtyping
+
+Here we see another set of definitions but the alphabetic ones are not defined in
+\CONTEXT, they are again bindings to the authors special keyboard.
+
+\startnarrowtyping
+% INITEX sets \sfcode x=1000 for all x, except that \sfcode`X=999 for uppercase
+% letters. The following changes are needed:
+
+\sfcode`\)=0 \sfcode`\'=0 \sfcode`\]=0
+
+% The \nonfrenchspacing macro will make further changes to \sfcode values.
+\stopnarrowtyping
+
+Definitions like this depend on the language. Because original \TEX\ was mostly
+meant for typesetting English, these things are hard coded. In \CONTEXT\ such
+definitions relate to languages.
+
+I show these definitions because they also illustrate what \TEX\ is about:
+typesetting math:
+
+\startnarrowtyping
+% Finally, INITEX sets all \delcode values to -1, except \delcode`.=0
+
+\delcode`\(="028300
+\delcode`\)="029301
+\delcode`\[="05B302
+\delcode`\]="05D303
+\delcode`\<="26830A
+\delcode`\>="26930B
+\delcode`\/="02F30E
+\delcode`\|="26A30C
+\delcode`\\="26E30F
+
+% N.B. { and } should NOT get delcodes; otherwise parameter grouping fails!
+\stopnarrowtyping
+
+Watch the last comment. One of the complications of \TEX\ is that because some
+characters have special meanings, we also need to deal with exceptions. It also
+means that arbitrary input is not possible. For instance, unless the percent
+character is made a letter, everything following it till the end of a line will
+be discarded. This is an areas where macro packages can differ but in \MKII\ we
+followed these rules. In \MKIV\ we made what we called \type {\nonknuthmode}
+default which means that ampersands are just that and scripts are only special in
+math (there was also \type {\donknuthmode}). So, \CONTEXT\ is not like plain
+there.
+
+\stopsection
+
+\startsection[title=Housekeeping]
+
+The next section defines some numeric shortcuts. Here the fact is used that a
+defined symbolic character can act as counter value. When the number is larger
+than 255 a math character is to be used. In \LUATEX, which is a \UNICODE\ engine
+character codes can be much larger.
+
+\startnarrowtyping
+% To make the plain macros more efficient in time and space, several constant
+% values are declared here as control sequences. If they were changed, anything
+% could happen; so they are private symbols.
+
+\chardef\@ne=1
+\chardef\tw@=2
+\chardef\thr@@=3
+\chardef\sixt@@n=16
+\chardef\@cclv=255
+\mathchardef\@cclvi=256
+\mathchardef\@m=1000
+\mathchardef\@M=10000
+\mathchardef\@MM=20000
+\stopnarrowtyping
+
+In \CONTEXT\ we still support these shortcuts but never use them ourselves. We
+have plenty more variables and constants and nowadays always use verbose names.
+(There was indeed a time when each extra characters depleted string memory more
+and more so then using short command names made sense.) The comment is right that
+using such variables is more efficient, for instance once loaded a macro is a
+sequence of tokens, so \type {\@one} takes one memory slot. In the case of the
+first three the saving is zero and even interpreting a single character token
+\type {3} is not less efficient than \type {\thr@@}, but in the case of \type
+{\@cclv} the three tokens \type {255} take more memory and also trigger the number
+scanner which is much slower than simply taking the meaning of the \type
+{\chardef}'d token. However, the \CONTEXT\ variable \type {\plusone} is as
+efficient as the \type {\@ne} and it looks prettier in code too (and I'm very
+sensitive for that). So, here \CONTEXT\ is definitely different!
+
+It makes no sense to show the next section here: it deals with managing
+registers, like counters and dimensions and token lists. Traditional \TEX\ has
+255 registers per category. Associating a control sequence (name) with a specific
+counter is done with \type {\countdef} but I don't think that you will find a
+macro package that expects a user to use that primitive. Instead it will provide
+a \type {\newcount} macro. So yes, here \CONTEXT\ is like plain.
+
+Understanding these macros is a test case for understanding \TEX. Take the
+following snippet:
+
+\startnarrowtyping
+\let\newtoks=\relax % we do this to allow plain.tex to be read in twice
+\outer\def\newhelp#1#2{\newtoks#1#1\expandafter{\csname#2\endcsname}}
+\outer\def\newtoks{\alloc@5\toks\toksdef\@cclvi}
+\stopnarrowtyping
+
+The \type {\outer} prefix flags macros as to be used at the outermost level and
+because the \type {\newtoks} is in the macro body of \type {\newtoks} it has to
+be relaxed first. Don't worry if you don't get it. In \CONTEXT\ we have no outer
+macros so the definitions differ there.
+
+The plain format assumes that the first 10 registers are used for scratch
+purposes, so best also assume this to be the case in other macro packages. There
+is no need for \CONTEXT\ to differ from plain here. The definitions of box
+registers and inserts are special: there is no \type {\boxdef} and inserts use
+multiple registers. Especially the allocation of inserts is macro package
+specific. Anyway, \CONTEXT\ users never see such details because inserts are used
+as building blocks deep down.
+
+Right after defining the allocators some more constants are defined:
+
+\startnarrowtyping
+% Here are some examples of allocation.
+
+\newdimen\maxdimen \maxdimen=16383.99999pt % the largest legal <dimen>
+\stopnarrowtyping
+
+We do have that one, as it's again a standard but we do have more such constants.
+This definition is kind of interesting as it assumes knowledge about what is
+acceptable for \TEX\ as dimension:
+
+\startbuffer
+{\maxdimen=16383.99999pt \the\maxdimen \quad \number\maxdimen}
+{\maxdimen=16383.99998pt \the\maxdimen \quad \number\maxdimen}
+\stopbuffer
+
+\typebuffer
+
+\startlines
+\getbuffer
+\stoplines
+
+Indeed it is the largest legal dimension but the real largest one is slighly
+less. We could also have said the following, which also indicates what the
+maximum cardinal is:
+
+\startnarrowtyping
+\newdimen\maxdimen \maxdimen=1073741823sp
+\stopnarrowtyping
+
+We dropped some of the others defined in plain. So, \CONTEXT\ is a bit like plain
+but differs substantially. In fact, \MKII\ already used a different allocator
+implementation and \MKIV\ is even more different. We also have more \type {\new}
+things.
+
+The \type {\newif} definition also differs. Now that definition is quite special
+in plain \TEX, so if you want a challenge, look it up. It defines three macros as
+the comment says:
+
+\startnarrowtyping
+% For example, \newif\iffoo creates \footrue, \foofalse to go with \iffoo.
+\stopnarrowtyping
+
+The \type {\iffoo} is either equivalent to \type {\iftrue} or \type {\iffalse}
+because that is what \TEX\ needs to see in order to be able to skip nested
+conditional branches. In \CONTEXT\ we have so called conditionals, which are more
+efficient. So, yes, you will find such defined ifs in the \CONTEXT\ source but
+way less than you'd expect in such a large macro package: \CONTEXT\ code doesn't
+look much like plain code I fear.
+
+\stopsection
+
+\startsection[title=Parameters]
+
+A next stage sets the internal parameters:
+
+\startnarrowtyping
+% All of TeX's numeric parameters are listed here, but the code is commented out
+% if no special value needs to be set. INITEX makes all parameters zero except
+% where noted.
+\stopnarrowtyping
+
+We use different values for many of them. The reason is that the plain \TEX\ format
+is set up for a 10 point Computer Modern font system, and for a particular kind
+of layout, so we use different values for:
+
+\startnarrowtyping
+\hsize=6.5in
+\vsize=8.9in
+\maxdepth=4pt
+\stopnarrowtyping
+
+and
+
+\startnarrowtyping
+\abovedisplayskip=12pt plus 3pt minus 9pt
+\abovedisplayshortskip=0pt plus 3pt
+\belowdisplayskip=12pt plus 3pt minus 9pt
+\belowdisplayshortskip=7pt plus 3pt minus 4pt
+\stopnarrowtyping
+
+No, here \CONTEXT\ is not like plain. But, there is one aspect that we do inherit and
+that is the ratio. Here a 10 point relates to 12 point and this 1.2 factor is carried
+over in some defaults in \CONTEXT. So, in the end we're a bit like plain.
+
+After setting up the internal quantities plain does this:
+
+% We also define special registers that function like parameters:
+
+\startnarrowtyping
+\newskip\smallskipamount \smallskipamount=3pt plus 1pt minus 1pt
+\newskip\medskipamount \medskipamount=6pt plus 2pt minus 2pt
+\newskip\bigskipamount \bigskipamount=12pt plus 4pt minus 4pt
+\newskip\normalbaselineskip \normalbaselineskip=12pt
+\newskip\normallineskip \normallineskip=1pt
+\newdimen\normallineskiplimit \normallineskiplimit=0pt
+\newdimen\jot \jot=3pt
+\newcount\interdisplaylinepenalty \interdisplaylinepenalty=100
+\newcount\interfootnotelinepenalty \interfootnotelinepenalty=100
+\stopnarrowtyping
+
+The first three as well as the following three related variables are not internal
+quantities but preallocated registers. These are not used in the engine but in
+macros. In \CONTEXT\ we do provide them but the first three are never used that
+way. The last three are not defined at all. So, \CONTEXT\ provides a bit what
+plain provides, just in case.
+
+\stopsection
+
+\startsection[title=Fonts]
+
+The font section is quite interesting. I assume that one reason why some want to
+warn users against using \CONTEXT\ is because it supports some of the font
+switching commands found in plain. We had no reasons to come up with different ones
+but they do different things anyway, for instance adapting to situations. So, in
+\CONTEXT\ you will not find the plain definitions:
+
+\startnarrowtyping
+\font\tenrm=cmr10 % roman text
+\font\preloaded=cmr9
+\font\preloaded=cmr8
+\font\sevenrm=cmr7
+\font\preloaded=cmr6
+\font\fiverm=cmr5
+\stopnarrowtyping
+
+There is another thing going on here. Some fonts are defined \type {\preloaded}. So,
+\type {cmr9} is defined, and then \type {cmr8} and \type {cmr6}. But they all use the
+same name. Later on we see:
+
+\startnarrowtyping
+\let\preloaded=\undefined % preloaded fonts must be declared anew later.
+\stopnarrowtyping
+
+If you never ran into the relevant part of the \TEX\ book or read the program
+source of \TEX, you won't realize that preloading means that it stays in memory
+which in turn means that when it gets (re)defined later, the font data doesn't
+come from disk. In fact, as the plain format is normally dumped for faster reload
+later on, the font data is also retained. So, preloading is a speed up hack. In
+\CONTEXT\ font loading has always been delayed till the moment a font is really
+used. This permits plenty of definitions and gives less memory usage. Of course
+we do reuse fonts once loaded. All this, plus the fact that we have a a system of
+related sizes, collections of families, support multiple font encodings
+alongside, collect definitions in so called typescript, etc. makes that the
+\CONTEXT\ font subsystem is far from what plain provides. Only some of the
+command stick, like \type {\rm} and \type {\bf}.
+
+The same is true for math fonts, where we can have different math font setups in
+one document. Definitely in \MKII\ times, we also had to work around limitations
+in the number of available math families, which again complicated the code. In
+\MKIV\ things are even more different, one can even consider the implementation
+somewhat alien for a standard macro package, but that's for another article (if
+at all).
+
+\stopsection
+
+\startsection[title=Macros]
+
+Of course \CONTEXT\ comes with macros, but these are organized in setups,
+environments, instances, etc. The whole process and setup is keyword driven. Out
+of the box all things work: nothing needs to be loaded. If you want it different,
+you change some settings, but you don't need to load something. Maybe that last
+aspect is what is meant with \CONTEXT\ being like plain: you don't (normally)
+load extra stuff. You just adapt the system to your needs. So there we proudly
+follow up on plain \TEX.
+
+In the plain macro section we find definitions like:
+
+\startnarrowtyping
+\def\frenchspacing{\sfcode`\.\@m \sfcode`\?\@m \sfcode`\!\@m
+ \sfcode`\:\@m \sfcode`\;\@m \sfcode`\,\@m}
+\def\nonfrenchspacing{\sfcode`\.3000\sfcode`\?3000\sfcode`\!3000%
+ \sfcode`\:2000\sfcode`\;1500\sfcode`\,1250 }
+\stopnarrowtyping
+
+and:
+
+\startnarrowtyping
+\def\space{ }
+\def\empty{}
+\def\null{\hbox{}}
+
+\let\bgroup={
+\let\egroup=}
+\stopnarrowtyping
+
+and:
+
+\startnarrowtyping
+\def\nointerlineskip{\prevdepth-1000\p@}
+\def\offinterlineskip{\baselineskip-1000\p@
+ \lineskip\z@ \lineskiplimit\maxdimen}
+\stopnarrowtyping
+
+Indeed we also provide these, but apart from the two grouping related aliases
+their implementation is different in \CONTEXT. There is no need to reinvent
+names.
+
+For a while we kept (and did in \MKII) some of the plain helper macros, for
+instance those that deal with tabs, but we have several more extensive table
+models that are normally used. We always had our own code for float placement,
+and we also have more options there. Footnotes are supported but again we have
+multiple classes, placements, options, etc. Idem for itemized lists, one of the
+oldest mechanisms in \CONTEXT. We don't have \type {\beginsection} but of course
+we do have sectioning commands, and have no \type {\proclaim} but provide lots of
+descriptive alternatives, so many that I forgot about most of them by now (so
+plain is a winner in terms of knowing a macro package inside out).
+
+The fact that we use tables, floats and footnotes indeed makes \CONTEXT\ to act
+like plain, but that's then also true for other macro packages. A fact is that
+plain sets the standard for how to think about these matters! The same is true
+for naming characters:
+
+\startnarrowtyping
+\chardef\%=`\%
+\chardef\&=`\&
+\chardef\#=`\#
+\chardef\$=`\$
+\chardef\ss="19
+\chardef\ae="1A
+\chardef\oe="1B
+\chardef\o="1C
+\chardef\AE="1D
+\chardef\OE="1E
+\chardef\O="1F
+\chardef\i="10 \chardef\j="11 % dotless letters
+\stopnarrowtyping
+
+But we have many more and understandable the numbers are different in \CONTEXT\
+because we use different font (encodings). Their implementation is more adaptive.
+The same is true for accented characters:
+
+\startnarrowtyping
+\def\`#1{{\accent18 #1}}
+\def\'#1{{\accent19 #1}}
+\stopnarrowtyping
+
+The definitions in \MKII\ are different (in most cases we use native glyphs) and
+in \MKIV\ we use \UNICODE\ anyway. I think that the \type {\accent} command is
+only used in a few exceptional cases (like very limited fonts) in \MKII\ and never
+in \MKIV. The implementation of for instance accents (and other pasted together
+symbols) in math is also quite different.
+
+There are also definitions that seem to be commonly used in macro packages but
+that we never use in \CONTEXT\ because they interfere badly with all kind of
+other mechanisms, so you will find no usage of
+
+\startnarrowtyping
+\def\leavevmode{\unhbox\voidb@x} % begins a paragraph, if necessary
+\stopnarrowtyping
+
+in \CONTEXT. In order to stress that we provide \type {\dontleavehmode}, a wink
+to not using the one above.
+
+The macro section ends with lots of math definitions. Most of the names used are
+kind of standard so again here \CONTEXT\ is like plain, but the implementation
+can differ as does the level of control.
+
+\stopsection
+
+\startsection[title=Output]
+
+Once a page is ready it gets wrapped up and shipped out. Here \CONTEXT\ is very
+different from plain. The amount of code in plain is not that large but the
+possibilities aren't either, which is exactly what the objectives demand: a
+simple (example) format that can be described in the \TEX book. But, as with
+other aspects of plain, it steered the way macro packages started out as it
+showed the way. As did many examples in the \TEX\ book.
+
+\stopsection
+
+\startsection[title=Hyphenation]
+
+As an afterthought, the plain format ends with loading hyphenation patterns, that
+is the English ones. That said it will be clear that \CONTEXT\ is not like plain:
+we support many languages, and the subsystem deals with labels, specific
+typesetting properties, etc.\ too.
+
+\startnarrowtyping
+\lefthyphenmin=2 \righthyphenmin=3 % disallow x- or -xx breaks
+\input hyphen
+\stopnarrowtyping
+
+We don't even use these patterns as we switched to \UTF\ long ago (also in \MKII)
+if only because we had to deal with a mix of font encodings. But we did preload the
+lot there. In \MKIV\ again things are much different.
+
+\stopsection
+
+\startsection[title=Conclusion]
+
+The plain format does (and provides) what it is supposed to do. It is a showcase
+of possibilities and part of the specification. In that respect it's nice that
+\CONTEXT\ is considered to be like plain. But if it wasn't more, there was no
+reason for its existence. Like more assumptions about \CONTEXT\ it demonstrates
+that those coming up with answers and remarks like that probably missed something
+in assessing \CONTEXT. Just let users find out themselves what suits best (and
+for some that actually might be plain \TEX).
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/musings/musings.tex b/Master/texmf-dist/doc/context/sources/general/manuals/musings/musings.tex
index e2787dc9923..687fcdb50f0 100644
--- a/Master/texmf-dist/doc/context/sources/general/manuals/musings/musings.tex
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/musings/musings.tex
@@ -16,6 +16,11 @@
\component musings-staygo
\component musings-stability
\component musings-roadmap
+ \component musings-names
+ \component musings-plain
+ % \component musings-performance
+ % \component musings-history
+ % \component musings-treasures
\stopbodymatter
\stopproduct
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/onandon/onandon-53.tex b/Master/texmf-dist/doc/context/sources/general/manuals/onandon/onandon-53.tex
index 0d5dc1b9cc0..c724bf810d2 100644
--- a/Master/texmf-dist/doc/context/sources/general/manuals/onandon/onandon-53.tex
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/onandon/onandon-53.tex
@@ -2,49 +2,55 @@
\startcomponent onandon-53
+% copy-edited by Alan Braslau
+
\environment onandon-environment
\startchapter[title={From \LUA\ 5.2 to 5.3}]
-When we started with \LUATEX\ we used \LUA\ 5.1 and moved to 5.2 when that became
-available. We didn't run into issues then because there were no fundamental
-changes that could not be dealt with. However, when \LUA\ 5.3 was announced in
-2015 we were not sure if we should make the move. The main reason was that we'd
-chosen \LUA\ because of its clean design which meant that we had only one number
-type: double. In 5.3 on the other hand, deep down a number can be either an
-integer or a floating point quantity.
-
-Internally \TEX\ is mostly (up to) 32-bit integers and when we go from \LUA\ to
-\TEX\ we round numbers. Nonetheless one can expect some benefits in using
-integers. Performance|-|wise we didn't expect much, and memory consumption would
-be the same too. So, the main question then was: can we get the same output and
-not run into trouble due to possible differences in serializing numbers; after
-all \TEX\ is about stability. The serialization aspect is for instance important
-when we compare quantities and|/|or use numbers in hashes.
-
-Apart from this change in number model, which comes with a few extra helpers,
-another extension in 5.3 was that bit|-|wise operations are now part of the
-language. The lpeg library is still not part of stock \LUA. There is some minimal
-\UTF8 support, but less than we provide in \LUATEX\ already. So, looking at these
-changes, we were not in a hurry to update. Also, it made sense to wait till this
-important number|-|related change was stable.
-
-But, a few years later, we still had it on our agenda to test, and after the
-\CONTEXT\ 2017 meeting we decided to give it a try; here are some observations. A
-quick test was just dropping in the new \LUA\ code and seeing if we could make a
-\CONTEXT\ format. Indeed that was no big deal but a test run failed because at
-some point a (for instance) \type {1} became a \type {1.0}. It turned out that
-serializing has some side effects. And with some ad hoc prints for tracing (in
-the \LUATEX\ source) I could figure out what went on. How numbers are seen can
-(to some extent) be deduced from the \type {string.format} function, which is in
-\LUA\ a combination of parsing, splitting and concatenation combined with piping
-to the \CCODE\ \type {sprintf} function. \footnote {Actually, at some point I
-decided to write my own formatter on top of \type {format} and I ended up with
-splitting as well. It's only now that I realize why this is working out so well
-(in terms of performance): simple format (single items) are passed more or less
-directly to \type {sprintf} and as \LUA\ itself is fast, due to some caching, the
-overhead is small compared to the built|-|in splitter method. And the \CONTEXT\
-formatter has many more options and is extensible.}
+When we started with \LUATEX\ we used \LUA\ 5.1 and then moved seamlessly to 5.2
+when that became available. We didn't run into issues with this language version
+change because there were no fundamental differences that could not be easily
+dealt with. However, when \LUA\ 5.3 was announced in 2015 we were not sure if we
+should make the move. The main reason was that we'd chosen \LUA\ because of its
+clean design part of which meant that we had only one number type: double. In 5.3
+on the other hand, deep down a number can be either an integer or a floating
+point quantity.
+
+Internally \TEX\ is mostly (up to) 32-bit integers so when we go from \LUA\ to
+\TEX\ we are forced to round numbers. Nonetheless, or perhaps because of this,
+one can expect some benefits in using integers in \LUA. Performance|-|wise we
+didn't expect much, and memory consumption would be the same too. So the main
+question then was: can we get the same output and not run into trouble due to
+possible differences in serializing numbers? After all \TEX\ is about stability.
+The serialization aspect is for instance important when we compare quantities
+and|/|or use numbers in hashes, so one must be careful.
+
+Apart from this change in the number model (which comes with a few extra
+helpers), another interesting extension in 5.3 was that bit|-|wise operations are
+now part of the language. However, the lpeg library is still not part of stock
+\LUA. There is also added some minimal \UTF8 support, but less than we provide in
+\LUATEX\ already. So, considering these changes, we were not in a big hurry to
+update. Also, it made sense to wait until this important number|-|related change
+became stable.
+
+But, a few years later, we still had it on our agenda to test the new version of
+\LUA, and after the \CONTEXT\ 2017 meeting we decided to give it a try; here are
+some observations. A quick test involved just dropping in the new \LUA\ code and
+seeing if with this we could still compile a \CONTEXT\ format. Indeed that was no
+big deal but the test run failed because at some point a (for instance) \type {1}
+became a \type {1.0}. It turned out that serializing has some side effects, and
+with some ad hoc prints for tracing (in the \LUATEX\ source) I could figure out
+what was going on. How numbers are seen can (to some extent) be deduced from the
+\type {string.format} function, which is in \LUA\ a combination of parsing,
+splitting and concatenation combined with piping to the \CCODE\ \type {sprintf}
+function: \footnote {Actually, at some point I decided to write my own formatter
+on top of \type {format} and I ended up with splitting as well. It's only now
+that I realize why this is working out so well (in terms of performance): simple
+format (single items) are passed more or less directly to \type {sprintf} and as
+\LUA\ itself is fast, due to some caching, the overhead is small compared to the
+built|-|in splitter method. An advantage is that the \CONTEXT\ formatter has many
+more options and is also extensible.}
\starttyping
local a = 2 * (1/2) print(string.format("%s", a),math.type(x))
@@ -76,10 +82,10 @@ This gives the following results:
\BC k \NC -2 \NC .0f \NC 2 \NC integer \NC \NR
\stoptabulate
-This demonstrates that we have to be careful when we need these numbers
-represented as strings. In \CONTEXT\ the number of places where we had to check
-for that was not that large; in fact, only some hashing related to font sizes had
-to be done using explicit rounding.
+This demonstrates that we have to be careful when we need numbers represented as
+strings. In \CONTEXT\ the places where we had to check for this was not that
+many: in fact, only some hashing related to font sizes had to be done using
+explicit rounding.
Another surprising side effect is the following. Instead of:
@@ -103,22 +109,23 @@ because we don't want this to be serialized to \type {64.0} which is due to the
fact that a power results in a float. One can wonder if this makes sense when we
apply it to an integer.
-At any rate, once we could process a file, two documents were chosen for a
-performance test. Some experiments with loops and casts had demonstrated that we
-could expect a small performance hit and indeed, this was the case. Processing
-the \LUATEX\ manual takes 10.7 seconds with 5.2 on my 5-year-old laptop and 11.6
-seconds with 5.3. If we consider that \CONTEXT\ spends 50\% of its time in \LUA,
-then we see a 20\% performance penalty. Processing the \METAFUN\ manual (which
-has lots of \METAPOST\ images) went from less than 20 seconds (\LUAJITTEX\ does
-it in 16 seconds) up to more than 27 seconds. So there we lose more than 50\% on
-the \LUA\ end. When we observed these kinds of differences, Luigi and I
-immediately got into debugging mode, partly out of curiosity, but also because
-consistent performance is important to~us.
-
-Because these numbers made no sense, we traced different sub-mechanisms and
-eventually it became clear that the reason for the speed penalty was that the
+At any rate, once we were able to process a file, two standard documents were
+chosen for a performance test. Some experiments with loops and casts had
+demonstrated that we could expect a small performance hit and indeed, this was
+the case. Processing the \LUATEX\ manual takes 10.7 seconds with 5.2 on my
+5-year-old laptop and 11.6 seconds with 5.3. If we consider that \CONTEXT\ spends
+about 50\% of its time in \LUA, then we find here a 20\% performance penalty
+using the later version of \LUA. Processing the \METAFUN\ manual (which has lots
+of \METAPOST\ images) went from less than 20 seconds (and \LUAJITTEX\ does it in
+16 seconds) to up to more than 27 seconds. So there we lose more than 50\% on the
+\LUA\ end. When we observed these kinds of differences, Luigi and I immediately
+got into debugging mode, partly out of curiosity but also because consistent
+performance is always important to us.
+
+As these results made no sense, we traced different sub-mechanisms and eventually
+it became clear that the reason behind the speed penalty was in fact that the
core \typ {string.format} function was behaving quite badly in the \type {mingw}
-cross-compiled binary, as seen by this test:
+cross|-|compiled binary, as can be seen by this test:
\starttyping
local t = os.clock()
@@ -137,13 +144,13 @@ print(os.clock()-t)
\BC c \NC 0.26 \NC 0.68 \NC 3.67 (0.29) \NC 0.66 \NC \NR
\stoptabulate
-The 5.2 binaries perform the same but the 5.3 Lua binary greatly outperforms
-\LUATEX, and so we had to figure out why. After all, all this integer
-optimization could bring some gain! It took us a while to figure this out. The
-numbers in parentheses are the results after fixing this.
+Both 5.2 binaries perform the same but the 5.3 \LUA\ binary greatly outperforms
+the \LUATEX binary so we had to figure out why. After all, the integer
+optimization should bring some gain! It took us a while to figure out what was
+going wrong, and the numbers in parentheses are the results after fixing \LUATEX.
Because font internals are specified in integers one would expect a gain
-in running:
+in running the command:
\starttyping
mtxrun --script font --reload force
@@ -151,8 +158,10 @@ mtxrun --script font --reload force
and indeed that is the case. On my machine a scan results in 2561 registered
fonts from 4906 read files and with 5.2 that takes 9.1 seconds while 5.3 needs a
-bit less: 8.6 seconds (with the bad format performance) and even less once that
-was fixed. For a test:
+bit less: 8.6 seconds (with the bad cross|-|compiled format performance) and even
+less once that was fixed.
+
+For a test:
\starttyping
\setupbodyfont[modern] \tf \bf \it \bs
@@ -163,21 +172,23 @@ was fixed. For a test:
\starttext \stoptext
\stoptyping
-This code needs 30\% more runtime so the question is: how often do we call \type
-{string.format} there? A first run (when we wipe the font cache) needs some
-715,000 calls while successive runs need 115,000 calls so that slow down
-definitely comes from the bad handling of \type {string.format}. When we drop in
-a \LUA\ update or whatever other dependency we don't want this kind of impact. In
-fact, when one uses external libraries that are or can be compiled under the
-\TEX\ Live infrastructure and the impact would be such, it's bad advertising,
-especially when one considers the occasional complaint about \LUATEX\ being
-slower than other engines.
+This code needs 30\% more runtime using the newer version of \LUA\ so the
+question is: how often do we call \type {string.format} there? A first run (when
+we wipe the font cache) needs some 715\,000 calls while successive runs need
+115\,000 calls so the slow down definitely comes from the bad handling of \type
+{string.format}.
+
+When we drop in a \LUA\ or whatever other dependency update we don't want this
+kind of impact. In fact, when one uses external libraries that are or can be
+compiled under the \TEX\ Live infrastructure and the impact would be so dramatic,
+this would be very bad advertising, especially when one considers the occasional
+complaint about \LUATEX\ being slower than other engines.
The good news is that eventually Luigi was able to nail down this issue and we
got a binary that performed well. It looks like \LUA\ 5.3.4 (cross|)|compiles
-badly with \GCC\ 5.3.0 and 6.3.0.
+badly under both \GCC\ 5.3.0 and 6.3.0.
-So in the end caching the fonts takes:
+So in the end loading the fonts takes:
\starttabulate[||c|c|]
\BC \BC caching \BC running \NC \NR
@@ -186,18 +197,20 @@ So in the end caching the fonts takes:
\BC 5.3 fixed \NC 6.3 \NC 1.0 \NC \NR
\stoptabulate
-So indeed it looks like 5.3 is able to speed up \LUATEX\ a bit, given that one
-integrates it in the right way! Using a recent compiler is needed too, although
-one can wonder when a bad case will show up again. One can also wonder why such a
-slow down can mostly go unnoticed, because for sure \LUATEX\ is not the only
-compiled program.
+So indeed after an initial scare it looks like 5.3 is able to speed up \LUATEX\ a
+bit, given that one integrates it in the right way! The use of a recent compiler
+is needed here, although one can wonder when another bad case will show up again.
+One can also wonder why such a slow down can mostly go unnoticed, because for
+sure \LUATEX\ is not the only compiled program integrating the \LUA\ language.
+\footnote{We can only speculate that others do not pay such close attention to
+performance.}
The next examples are some edge cases that show you need to be aware
that
\startitemize[n,text,nostopper]
\startitem an integer has its limits, \stopitem
- \startitem that hexadecimal numbers are integers and \stopitem
- \startitem that \LUA\ and \LUAJIT\ can be different in details. \stopitem
+ \startitem that hexadecimal numbers are integers, and \stopitem
+ \startitem that \LUA\ 5.2 and \LUAJIT\ can differ in small details: \stopitem
\stopitemize
\starttabulate[||T|T|]
@@ -208,47 +221,53 @@ that
\BC lua 53 \NC -1 \NC 9223372036854775807 \NC \NR
\stoptabulate
-So, to summarize the process. A quick test was relatively easy: move 5.3 into the
-code base, adapt a little bit of internals (there were some \LUATEX\ interfacing
-bits where explicit rounding was needed), run tests and eventually fix some
-issues related to the Makefile (compatibility) and \CCODE\ obscurities (the slow
-\type {sprintf}). Adapting \CONTEXT\ was also not much work, and the test suite
-uncovered some nasty side effects. For instance, the valid 5.2 solution:
+We see here that \LUA\ 5.3 clearly represents some progress.
+
+So, to summarize the migration, a quick test was relatively easy: move 5.3 into
+the code base, make slight adaptations to the internals (there were a few
+\LUATEX\ interfacing bits where explicit rounding was needed), run tests, and
+eventually fix some issues related to the Makefile (compatibility) and \CCODE\
+obscurities (the very slow \type {sprintf}). \footnote{This demonstrates the
+importance of compilers, or rather how one writes code with respect to each
+compiler.}
+
+Adapting \CONTEXT\ was also not much work, but the test suite uncovered some
+nasty side effects. For instance, the valid 5.2 solution:
\starttyping
local s = string.format("02X",u/1024)
local s = string.char (u/1024)
\stoptyping
-now has to become (both 5.2 and 5.3):
+now has to become (works with both 5.2 and 5.3):
\starttyping
local s = string.format("02X",math.floor(u/1024))
local s = string.char (math.floor(u/1024))
\stoptyping
-or (both 5.2 and (emulated or real) 5.3):
+or (with 5.2 and emulated or real 5.3):
\starttyping
local s = string.format("02X",bit32.rshift(u,10))
local s = string.char (bit32.rshift(u,10))
\stoptyping
-or (only 5.3):
+or (5.3 only):
\starttyping
local s = string.format("02X",u >> 10))
local s = string.char (u >> 10)
\stoptyping
-or (only 5.3):
+or (5.3 only):
\starttyping
local s = string.format("02X",u//1024)
local s = string.char (u//1024)
\stoptyping
-A conditional section like:
+Unfortunately, adapting a conditional section like:
\starttyping
if LUAVERSION >= 5.3 then
@@ -260,28 +279,61 @@ else
end
\stoptyping
-will fail because (of course) the 5.2 parser doesn't like that. In \CONTEXT\ we
-have some experimental solutions for that but that is beyond this summary.
+will fail because (of course) the 5.2 parser doesn't like the 5.3 syntax
+elements. In \CONTEXT\ we have some experimental solutions for this but it is
+beyond the scope of this summary.
-In the process a few \UTF\ helpers were added to the string library so that we
-have a common set for \LUAJIT\ and \LUA\ (the \type {utf8} library that was added
-to 5.3 is not that important for \LUATEX). For now we keep the \type {bit32}
-library on board. Of course we'll not mention all the details here.
+In the process of this update a few \UTF\ helpers were added to the string
+library so that we have a common set for both \LUAJIT\ and \LUA\ (the \type
+{utf8} library that was added to 5.3 is not very useful for \LUATEX). For now we
+also keep the \type {bit32} library on board, of course, we'll not mention all
+the details here.
-When we consider a gain in speed of 5-10\% with 5.3 that also means that the gain
-of \LUAJITTEX\ compared to 5.2 becomes less. For instance in font processing both
-engines now perform closer to the same.
+When we consider a gain in speed of 5–10\% with 5.3 that also means that the gain
+obtained using \LUAJITTEX\ compared to \LUA\ 5.2 becomes less important. For
+instance in font processing both engines (\LUA\ 5.3 and \LUAJIT) now perform
+roughly to the same.
As I write this, we've just entered 2018 and after a few months of testing
\LUATEX\ with \LUA\ 5.3 we're confident that we can move the code to the
experimental branch. This means that we will use this version in the \CONTEXT\
-distribution and likely will ship this version as 1.10 in 2019, where it becomes
+distribution and likely will ship this as 1.10 in 2019 where \LUA\ 5.3 becomes
the default. The 2018 version of \TEX~Live will have 1.07 with \LUA\ 5.2 while
intermediate versions of the \LUA\ 5.3 binary will end up on the \CONTEXT\
garden, probably with number 1.08 and 1.09 (who knows what else we will add or
change in the meantime).
-\stopchapter
+\subsubject{Addendum}
+
+Around the 2018 meeting I also started what is to become the next major upgrade
+of \CONTEXT, this time using a new engine \LUAMETATEX. In working on that I
+decided to try \LUA\ 5.4 to see what consequences this new version would have for
+us. There are no real conceptual changes as were found with the number model in
+5.3, so the tests didn't reveal any real issues. But as an additional step
+towards a bit cleaner distinction between strings and numbers, I decided to
+disable the automatic casting so that mixing strings and numbers in expression
+for instance is no longer permitted. If I remember correctly, there was only in
+one place I had to adapt the source (and we're talking about a pretty large \LUA\
+code base).
+
+There is a new mechanism in \LUA\ for freezing constants but I'm not yet sure if
+it makes much sense to use it, although one of the intentions is to produce more
+efficient bytecode. \footnote {Mid July 2019 some quick tests indeed show a
+performance boost with the experimental code base, but if we want to benefit from
+using constants, the \CONTEXT\ codebase has to be adapted, which means that those
+parts no longer will work with stock \LUATEX.} It's use goes along with some
+other restrictions, like the possibility to adapt loop counters inside the loop.
+Inside the body of a loop one could always adapt such a variable, which (I can
+imagine) can come in handy. I haven't checked the source code for that, but
+probably I don't do this anywhere.
+
+Another new feature is an alternative garbage collector which seems to perform
+better when there are many variables with a short life spans. At least for now I
+have decided to default to this variant in future releases.
+
+Overall the performance of \LUA\ 5.4 is better than its predecessors which means
+that the gap between \LUATEX\ and \LUAJITTEX\ is closed or is closing. This is
+good because I have chosen not to support \LUAJIT\ in \LUAMETATEX.
\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/onandon/onandon-execute.tex b/Master/texmf-dist/doc/context/sources/general/manuals/onandon/onandon-execute.tex
index abb3b4d8a15..9d5458fe909 100644
--- a/Master/texmf-dist/doc/context/sources/general/manuals/onandon/onandon-execute.tex
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/onandon/onandon-execute.tex
@@ -6,12 +6,12 @@
\startchapter[title={Executing \TEX}]
-Much of the \LUA\ code in \CONTEXT\ originates from experiments. When it survives
-in the source code it is probably used, waiting to be used or kept for
+Much of the \LUA\ code in \CONTEXT\ originates from experiments. What survives in
+the source code is probably either used, waiting to be used, or kept for
educational purposes. The functionality that we describe here has already been
-present for a while in \CONTEXT, but improved a little starting with \LUATEX\
-1.08 due to an extra helper. The code shown here is generic and not used in
-\CONTEXT\ as such.
+present for a while in \CONTEXT, but has been improved a little starting with
+\LUATEX\ 1.08 due to an extra helper. The code shown here is generic and is not
+used in \CONTEXT\ as such.
Say that we have this code:
@@ -33,8 +33,8 @@ end
% \ctxluabuffer
When we call \type {\directlua} with this snippet we get some 30 pages of \type
-{12345345345}. The printed text is saved till the end of the \LUA\ call, so
-basically we pipe some 170.000 characters to \TEX\ that get interpreted as one
+{12345345345}. The printed text is saved until the end of the \LUA\ call so
+basically we pipe some 170\,000 characters to \TEX\ that get interpreted as one
paragraph.
Now imagine this:
@@ -45,7 +45,8 @@ Now imagine this:
\typebuffer
-which gives \getbuffer. If we check the box in \LUA, with:
+which gives \getbuffer (the width of the \type {box0} register). If we check the
+box in \LUA, with:
\startbuffer
tex.sprint(tex.box[0].width)
@@ -56,10 +57,11 @@ tex.sprint(tex.box[0].width)
\typebuffer
-the result is {\tttf \ctxluabuffer}, which is not what you would expect at first
-sight. However, if you consider that we just pipe to a \TEX\ buffer that gets
-parsed after the \LUA\ call, it will be clear that the reported width is the
-width that we started with. It will work all right if we say:
+the result is {\tttf \ctxluabuffer} i.e. the same number repeated, which is not
+what you would expect at first sight. However, if you consider that we just pipe
+to a \TEX\ buffer that gets parsed \italic {after} the \LUA\ call, it will be
+clear that the reported width is each time the width that we started with. Our
+code will work all right if we use:
\startbuffer
tex.sprint(tex.box[0].width)
@@ -70,9 +72,11 @@ tex.sprint("\\directlua{tex.sprint(tex.box[0].width)}")
\typebuffer
-because now we get: {\tttf\ctxluabuffer}. It's not that complex to write some
-support code that makes this more convenient. This can work out quite well but
-there is a drawback. If we use this code:
+and now we get: {\tttf\ctxluabuffer}, but this use is a bit awkward.
+
+It's not that complex to write some support code that is convenient and this can
+work out quite well but there is a drawback. If we add references to the status
+of the input pointer:
\startbuffer
print(status.input_ptr)
@@ -85,24 +89,24 @@ tex.sprint("\\directlua{print(status.input_ptr)\
\typebuffer
-Here we get \type {6} and \type {7} reported. You can imagine that when a lot of
-nested \type {\directlua} calls happen, we can get an overflow of the input level
-or (depending on what we do) the input stack size. Ideally we want to do a \LUA\
-call, temporarily go to \TEX, return to \LUA, etc.\ without needing to worry
-about nesting and possible crashes due to \LUA\ itself running into problems. One
-charming solution is to use so|-|called coroutines: independent \LUA\ threads
-that one can switch between --- you jump out from the current routine to another
-and from there back to the current one. However, when we use \type {\directlua}
-for that, we still have this nesting issue and what is worse, we keep nesting
-function calls too. This can be compared to:
+we then get \type {6} and \type {7} reported. You can imagine that when a lot of
+nested \type {\directlua} calls happen, this can lead to an overflow of the input
+level or (depending on what we do) the input stack size. Ideally we want to do a
+\LUA\ call, temporarily go to \TEX, return to \LUA, etc.\ without needing to
+worry about nesting and possible crashes due to \LUA\ itself running into
+problems. One charming solution is to use so|-|called coroutines: independent
+\LUA\ threads that one can switch between --- you jump out from the current
+routine to another and from there back to the current one. However, when we use
+\type {\directlua} for that, we still have this nesting issue and what is worse,
+we keep nesting function calls too. This can be compared to:
\starttyping
\def\whatever{\ifdone\whatever\fi}
\stoptyping
-where at some point \type {\ifdone} is false so we quit. But we keep nesting when
-the condition is met, so eventually we can end up with some nesting related
-overflow. The following:
+where at some point \type {\ifdone} would be false so we quit, but we keep
+nesting when the condition is met and eventually we will end up with some nesting
+related overflow. The following:
\starttyping
\def\whatever{\ifdone\expandafter\whatever\fi}
@@ -122,7 +126,7 @@ and call that one with:
\luafunction 1
\stoptyping
-This is a bit faster than calling a function like:
+This is a bit faster than calling a function such as:
\starttyping
\directlua{HiThere()}
@@ -134,14 +138,28 @@ which can also be achieved by
\directlua{print("Hi there!")}
\stoptyping
-which sometimes can be more convenient. Anyway, a function call is what we can
-use for our purpose as it doesn't involve interpretation and effectively behaves
-like a tail call. The following snippet shows what we have in mind:
+and is sometimes more convenient. Don't overestimate the gain in speed because
+\type {directlua} is quite efficient too (and on an average run a user doesn't
+call it that often, millions of times that is). Anyway, a function call is what
+we can use for our purpose as it doesn't involve interpretation and effectively
+behaves like a tail call. The following snippet shows what we have in mind:
+
+\startbuffer[demo]
+tex.routine(function()
+ tex.sprint(tex.box[0].width)
+ tex.sprint("\\enspace")
+ tex.sprint("\\setbox0\\hbox{!}")
+ tex.yield()
+ tex.sprint(tex.box[0].width)
+end)
+\stopbuffer
+
+\typebuffer[demo]
\startbuffer[code]
local stepper = nil
local stack = { }
-local fid = 0xFFFFFF
+local fid = 2 -- make sure to take a free slot
local goback = "\\luafunction" .. fid .. "\\relax"
function tex.resume()
@@ -166,27 +184,24 @@ function tex.routine(f)
stepper = coroutine.create(f)
tex.sprint(goback)
end
-\stopbuffer
-\ctxluabuffer[code]
+-- Because we protect against abuse and overload of functions, in ConTeXt we
+-- need to do the following:
-\startbuffer[demo]
-tex.routine(function()
- tex.sprint(tex.box[0].width)
- tex.sprint("\\enspace")
- tex.sprint("\\setbox0\\hbox{!}")
- tex.yield()
- tex.sprint(tex.box[0].width)
-end)
+if context then
+ fid = context.functions.register(tex.resume)
+ goback = "\\luafunction" .. fid .. "\\relax"
+end
\stopbuffer
-\typebuffer[demo]
We start a routine, jump out to \TEX\ in the middle, come back when we're done
-and continue. This gives us: \ctxluabuffer [demo], which is what we expect.
-
-\setbox0\hbox{xxxxxxxxxxx}
+and continue. This gives us: \ctxluabuffer [code,demo], which is what we expect.
-\ctxluabuffer[demo]
+% What does this accomplish (or is it left over)?
+%
+% \setbox0\hbox{xxxxxxxxxxx}
+%
+% \ctxluabuffer[demo]
This mechanism permits efficient (nested) loops like:
@@ -219,9 +234,10 @@ e.g.\ the space) then the main difference is that instead of a small delay due t
the loop unfolding in a large set of prints and accumulated content, we now get a
steady flushing and processing.
-However, we can still have an overflow of input buffers because we still nest
-them: the limitation at the \TEX\ end has moved to a limitation at the \LUA\ end.
-How come? Here is the code that we use:
+However, even using this scheme we can still have an overflow of input buffers
+because we still nest them: the limitation at the \TEX\ end has moved to a
+limitation at the \LUA\ end. How come? Here is the code that we use defining the
+function \type {tex.yield()}:
\typebuffer[code]
@@ -233,12 +249,12 @@ then you will not easily overflow.
When I picked up this side project and wondered how to get around it, it suddenly
struck me that if we could just quit the current input level then nesting would
not be a problem. Adding a simple helper to the engine made that possible (of
-course figuring it out took a while):
+course figuring this out took a while):
\startbuffer[code]
local stepper = nil
local stack = { }
-local fid = 0xFFFFFF
+local fid = 3 -- make sure to take a frees slot
local goback = "\\luafunction" .. fid .. "\\relax"
function tex.resume()
@@ -270,16 +286,24 @@ function tex.routine(f)
stepper = coroutine.create(f)
tex.sprint(goback)
end
+
+-- Again we need to do it as follows in ConTeXt:
+
+if context then
+ fid = context.functions.register(tex.resume)
+ goback = "\\luafunction" .. fid .. "\\relax"
+end
\stopbuffer
\ctxluabuffer[code]
\typebuffer[code]
-The trick is in \type {texio.closeinput}, a recent helper and one that should be
-used with care. We assume that the user knows what she or he is doing. On an old
-laptop with a i7-3840 processor running \WINDOWS\ 10 the following snippet takes
-less than 0.35 seconds with \LUATEX\ and 0.26 seconds with \LUAJITTEX.
+The trick is in \type {texio.closeinput}, a recent helper to the engine and one
+that should be used with care. We assume that the user knows what she or he is
+doing. On an older laptop with a i7-3840 processor running \WINDOWS\ 10 the
+following snippet takes less than 0.35 seconds with \LUATEX\ and 0.26 seconds
+with \LUAJITTEX.
\startbuffer[code]
tex.routine(function()
@@ -302,7 +326,7 @@ end)
% \testfeatureonce {1} {\setbox0\hpack{\ctxluabuffer[code]}} \elapsedtime
-Say that we run the bad snippet:
+Say that we were to run the bad snippet:
\startbuffer[code]
for i=1,10000 do
@@ -319,7 +343,7 @@ end
% \testfeatureonce {1} {\setbox0\hpack{\ctxluabuffer[code]}} \elapsedtime
-This time we need 0.12 seconds in both engines. So what if we run this:
+This executes in only 0.12 seconds in both engines. So what if we run this:
\startbuffer[code]
\dorecurse{10000}{%
@@ -339,7 +363,7 @@ This time we need 0.12 seconds in both engines. So what if we run this:
Pure \TEX\ needs 0.30 seconds for both engines but there we lose 0.13 seconds on
the loop code. In the \LUA\ example where we yield, the loop code takes hardly
any time. As we need only 0.05 seconds more it demonstrates that when we use the
-power of \LUA\ the performance hit of the switch is quite small: we yield 40.000
+power of \LUA, the performance hit of the switch is quite small: we yield 40.000
times! In general, such differences are far exceeded by the overhead: the time
needed to typeset the content (which \type {\hpack} doesn't do), breaking
paragraphs into lines, constructing pages and other overhead involved in the run.
@@ -385,11 +409,11 @@ Now, in order to stay realistic, this macro can also be defined as:
We get the same result: \quotation {\getbuffer}.
-We have been using a \LUA|-|\TEX\ mix for over a decade now in \CONTEXT, and have
+We have been using a \LUA|-|\TEX\ mix for over a decade now in \CONTEXT\ and have
never really needed this mixed model. There are a few places where we could
-(have) benefitted from it and we might use it in a few places, but so far we have
-done fine without it. In fact, in most cases typesetting can be done fine at the
-\TEX\ end. It's all a matter of imagination.
+(have) benefited from it and now we might use it in a few places, but so far we
+have done fine without it. In fact, in most cases typesetting can be done fine at
+the \TEX\ end. It's all a matter of imagination.
\stopchapter
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/publications/122176.pdf b/Master/texmf-dist/doc/context/sources/general/manuals/publications/122176.pdf
index f8db03c1c25..7bca4089aa6 100644
--- a/Master/texmf-dist/doc/context/sources/general/manuals/publications/122176.pdf
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/publications/122176.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/publications/124484.pdf b/Master/texmf-dist/doc/context/sources/general/manuals/publications/124484.pdf
index 227a35b2938..3af8bbf9ae0 100644
--- a/Master/texmf-dist/doc/context/sources/general/manuals/publications/124484.pdf
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/publications/124484.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/publications/4953942.pdf b/Master/texmf-dist/doc/context/sources/general/manuals/publications/4953942.pdf
index 02c6cc22a28..860bcf80479 100644
--- a/Master/texmf-dist/doc/context/sources/general/manuals/publications/4953942.pdf
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/publications/4953942.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/publications/971.pdf b/Master/texmf-dist/doc/context/sources/general/manuals/publications/971.pdf
index a2fbc32c778..2ffb5704492 100644
--- a/Master/texmf-dist/doc/context/sources/general/manuals/publications/971.pdf
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/publications/971.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/sql/sql-mkiv.tex b/Master/texmf-dist/doc/context/sources/general/manuals/sql/sql-mkiv.tex
index 4d2ecbc6e9b..835065ba041 100644
--- a/Master/texmf-dist/doc/context/sources/general/manuals/sql/sql-mkiv.tex
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/sql/sql-mkiv.tex
@@ -493,8 +493,8 @@ context --extra=sql-tables --help
\startsection[title=Example]
-The distribution has a few examples, for instance a logger. The following code shows
-a bit of this (we assume that the swiglib sqlite module is present):
+The distribution has a few examples, for instance a logger. The following code
+shows a bit of this (we assume that \SQLITE\ is installed):
\startbuffer
require("util-sql")
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/svg/mozilla-tiger.svg b/Master/texmf-dist/doc/context/sources/general/manuals/svg/mozilla-tiger.svg
new file mode 100644
index 00000000000..f74af7dd117
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/svg/mozilla-tiger.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg"><path fill="#d87512" d="M17.786 44.63c-.606.115-1.23.173-1.854.173-2.444 0-4.644-.864-6.04-2.375-.855-.92-1.394-2.147-1.517-3.47-.126-1.243.067-2.638.58-4.163.325-1.016.83-2.01 1.365-3.064.216-.426.437-.858.65-1.302.702-1.454 1.504-3.164 2.11-5.05.715-2.188.943-4.287.682-6.23-.267-2.102-.994-3.972-1.74-5.685a2.992 2.992 0 0 0-4.15-1.446c-.71.375-1.23 1-1.467 1.77a2.983 2.983 0 0 0 .218 2.292c.632 1.19 1.314 2.596 1.592 3.977.238 1.137.18 2.41-.184 3.897-.37 1.538-.976 3.143-1.522 4.518-.16.406-.33.816-.507 1.234-.507 1.215-1.032 2.47-1.364 3.838-.55 2.14-.666 4.152-.348 5.97.36 2.163 1.41 4.14 2.955 5.567 2.027 1.88 4.808 2.914 7.826 2.914 1.14 0 2.274-.146 3.375-.437l-.66-2.923"/><g fill="#bc600d"><path d="M11.585 43.742s.387 1.248.104 3.05c0 0 2.045-.466 1.898-2.27 0 0-.815-.29-2-.78M9.19 41.484S8.98 42.94 7.93 44.43c0 0 2.103.42 2.774-1.265 0 0-.696-.66-1.515-1.68M8.398 37.21s-.926 1.432-3.23 2.322c0 0 1.514 2.303 3.53.904 0 0-.237-1.388-.3-3.226M12.964 15.833s-1.685.798-3.783 3.45c0 0 2.1 1.55 4.663 2.228 0 0 .285-3.093-.88-5.677M13.5 23.873s-2.988.544-5.57 2.794c0 0 1.615 1.708 3.583 2.62 0 0 1.678-3.39 1.987-5.414M10.32 31.73s-1.483 0-4.483.812c0 0-.01 2.873 2.94 2.823 0 0 .747-1.75 1.544-3.635"/></g><g fill="#d87512"><path d="M53.33 39.37c0-4.484-35.622-4.484-35.622 0 0 10.16.05 10.25 17.81 10.25 17.762 0 17.812-.09 17.812-10.25"/><path d="M42.645 56.04c1.688 2.02 9.275.043 10.504-2.28 5.01-9.482-.006-13.58-.006-13.58l-10.5 1.313s-2.154 11.977 0 14.547"/></g><g fill="#bc600d"><path d="M54.2 41.496s-.336 4.246-4.657 9.573c0 0 4.38-1.7 5.808-4.3 0 0 .448-3.02-1.15-5.274M55.08 48.69s-1.065 1.88-3.563 3.872c0 0 1.78-.03 2.576-.785 0 0 .77-1.41.987-3.086"/></g><path fill="#f29a2e" d="M35.484 60.38c1.87 2.23 8.547 2.09 10.574 0 2.904-2.995 2.78-16.656 2.904-23.314l-12.418-1.053s-3.444 21.52-1.06 24.367"/><g fill="#bc600d"><path d="M48.21 53.53s-3.578-3.443-8.738-.013c0 0 5.754 2.455 7.365 5.672 0 0 1.126-2.245 1.373-5.66M48.775 46.06s-3.852-3.09-7.938 1.43c0 0 4.452-.47 7.632 3.635 0 0 .493-3.05.305-5.065"/></g><g fill="#3e4347"><path d="M43.847 61.57l-.397-2.765 1.344 2.445zM40.41 61.996l.502-3.294.498 3.294zM36.713 61.3l1.317-2.26-.372 2.59z"/></g><path fill="#d87512" d="M28.388 56.04c-1.688 2.02-9.277.043-10.504-2.28-5.01-9.482.004-13.58.004-13.58l10.5 1.313s2.154 11.977 0 14.547"/><g fill="#bc600d"><path d="M16.833 41.496s.336 4.246 4.657 9.573c0 0-4.38-1.7-5.807-4.3 0 0-.448-3.02 1.15-5.274M15.957 48.69s1.066 1.88 3.563 3.872c0 0-1.782-.03-2.576-.785 0 0-.772-1.41-.987-3.086"/></g><path fill="#f29a2e" d="M35.548 60.38c-1.87 2.23-8.548 2.09-10.575 0-2.904-2.995-2.78-16.656-2.904-23.314l12.417-1.053s3.446 21.52 1.06 24.367"/><g fill="#bc600d"><path d="M22.822 53.53s3.58-3.443 8.74-.013c0 0-5.754 2.455-7.367 5.672 0 0-1.125-2.245-1.373-5.66M22.255 46.06s3.852-3.09 7.94 1.43c0 0-4.453-.47-7.633 3.635 0 0-.493-3.05-.307-5.065"/></g><g fill="#3e4347"><path d="M26.24 61.25l1.345-2.445-.395 2.765zM29.62 61.996l.5-3.294.5 3.294zM33.375 61.63L33 59.04l1.32 2.26zM35.516 60.46c-.395-2.48-.482-4.96-.5-7.438.015-2.48.104-4.96.5-7.44.396 2.48.485 4.96.5 7.44-.018 2.48-.106 4.96-.5 7.438"/></g><path fill="#f29a2e" d="M27.777 6.994c0 3.82-2.727 6.987-6.086 6.915C11.83 13.7 15.893 2 15.893 2c3.36 0 11.885 1.176 11.885 4.994"/><path fill="#af5a31" d="M24.05 7.752c0 2.037-1.454 3.727-3.248 3.688-5.26-.11-3.093-6.353-3.093-6.353 1.792 0 6.34.628 6.34 2.665"/><path fill="#f29a2e" d="M43.26 6.994c0 3.82 2.726 6.987 6.086 6.915 9.86-.21 5.8-11.91 5.8-11.91C51.782 2 43.26 3.176 43.26 6.994"/><path fill="#af5a31" d="M46.983 7.752c0 2.037 1.455 3.727 3.247 3.688 5.26-.11 3.094-6.353 3.094-6.353-1.794 0-6.34.628-6.34 2.665"/><path fill="#f29a2e" d="M55.806 33.378c0 7.155-9.517 8.13-20.288 8.13-10.776 0-20.29-.975-20.29-8.13 0-29.96 11.596-29.14 20.29-29.14 8.69 0 20.288-.82 20.288 29.14"/><g fill="#3e4347"><path d="M35.54 7.59c3.24 0 6.15 1.084 8.156 2.81-.77-2.945-4.135-5.16-8.173-5.16-4.06 0-7.442 2.238-8.186 5.204 2.01-1.753 4.938-2.855 8.204-2.855"/><path d="M35.535 11.193c2.217 0 4.21.744 5.584 1.925-.528-2.02-2.835-3.534-5.6-3.534-2.78 0-5.095 1.533-5.605 3.564 1.376-1.198 3.383-1.955 5.62-1.955"/></g><path fill="#ffe8bb" d="M29.553 43.727l-18.408-7.01 4.24-9.06s2.704 3.85 13.29 6.82l.878 9.243"/><path fill="#3e4347" d="M29.37 39.77c-7.462-1.27-16.325-6.673-16.48-6.75l.992-2.168c.184.092 8.806 5.342 15.853 6.544l-.366 2.374"/><path fill="#ffe8bb" d="M41.48 43.727l18.406-7.01-4.24-9.06s-2.704 3.85-13.29 6.82l-.876 9.243"/><path fill="#3e4347" d="M41.663 39.77c7.46-1.27 16.325-6.673 16.48-6.75l-.993-2.168c-.184.092-8.808 5.342-15.852 6.544l.365 2.374"/><g fill="#ffe8bb"><path d="M43.524 45.57C38.752 42.023 41.4 33.86 41.4 33.86c-5.657 5.906-12.662 8.74-12.662 8.74 1.608 5.446 5.77 6.412 5.77 6.412-.34-1.835.663-3.302.663-3.302 1.68 2.22 5.03 2.986 5.03 2.986-1.287-1.508-.948-3.835-.948-3.835 2.326.875 4.27.71 4.27.71"/><path d="M42.29 42.97c-2.634 2.247-10.917 2.247-13.553 0-2.856-2.435-2.495-7.144.1-9.884 2.397-2.527 10.958-2.527 13.355 0 2.595 2.74 2.956 7.45.098 9.883"/></g><g fill="#3e4347"><path d="M36.18 40.48a.69.69 0 0 1-.644-.477c-.227-.67-.77-3.293-.71-5.498.01-.398.325-.71.7-.698.38.01.674.343.663.74-.057 2.01.46 4.466.633 4.974.127.375-.06.786-.414.92a.607.607 0 0 1-.23.04"/><path d="M30.504 43.25c.21-.202.394-.408.582-.61.188-.204.378-.405.57-.604.385-.396.782-.78 1.2-1.145a14.125 14.125 0 0 1 2.745-1.9c.504-.263 1.032-.49 1.59-.654s1.153-.273 1.772-.253c.31.01.623.055.928.146.307.088.602.23.86.416.263.19.485.422.652.684.17.257.287.54.35.83a4.247 4.247 0 0 0-.677-.448 2.567 2.567 0 0 0-.68-.237c-.447-.088-.887-.04-1.33.06-.89.216-1.786.65-2.69 1.114-.905.466-1.818.983-2.776 1.466-.48.24-.97.473-1.48.682-.256.103-.517.202-.783.285-.27.078-.546.155-.833.167"/></g><path fill="#f15a61" d="M41.34 31.743c-1.17-.528-4.757-.57-5.83-.57-1.07 0-4.66.042-5.83.57-.832.376-.187 1.31 2.027 2.116 1.397.506 2.733.666 3.803.666 1.07 0 2.405-.16 3.805-.667 2.213-.808 2.856-1.74 2.025-2.117"/><g fill="#3e4347"><path d="M29.917 23.48l1.61 5.292L26.954 26z"/><path d="M22.645 31.828c-.522 0-.932-.056-1.17-.098-2.986-.52-4.632-1.996-6.09-4.067l.185-2.472c1.52 1.446 3.953 3.76 6.28 4.167 1.156.2 2.853-.016 4.15-1.234 1.537-1.44 2.263-4.05 2.1-7.547l1.635.132c.2 4.312-.116 7.244-2.212 9.212-1.692 1.59-3.613 1.908-4.878 1.908M41.12 23.48l-1.613 5.292L44.08 26z"/><path d="M48.39 31.828c.52 0 .93-.056 1.167-.098 2.99-.52 4.637-1.996 6.09-4.067l-.182-2.472c-1.52 1.446-3.955 3.76-6.28 4.167-1.156.2-2.855-.016-4.154-1.234-1.532-1.44-2.258-4.05-2.095-7.547l-1.636.132c-.202 4.312.114 7.244 2.213 9.212 1.69 1.59 3.61 1.908 4.877 1.908"/></g><path fill="#ffe8bb" d="M30.25 22.09c-.852 5.282-3.728 5.87-6.696 5.577-2.986-.294-5.396-2.667-5.396-6.743 0-4.28 0-4.28 6.647-5.752 6.728-1.49 6 3.437 5.445 6.918"/><path fill="#3e4347" d="M29.16 22.547c-.244 2.534-2.61 4.357-5.287 4.072-2.674-.286-4.645-2.57-4.402-5.102s.28-2.75 5.108-2.237c4.83.514 4.824.737 4.582 3.267"/><path fill="#fff" d="M27.59 21.884c-.16 1.688-1.74 2.903-3.522 2.714-1.785-.19-3.096-1.712-2.936-3.4.163-1.69.186-1.835 3.406-1.493 3.22.344 3.215.49 3.053 2.18"/><g fill="#3e4347"><ellipse cx="25.5" cy="21.08" rx="1.45" ry="1.647"/><path d="M31.27 17.896c.42 0 .807-.284.936-.728.16-.546-.133-1.122-.65-1.29l-5.98-1.924c-.516-.166-1.065.14-1.225.685-.155.543.136 1.12.652 1.287l5.98 1.924a.95.95 0 0 0 .288.046"/></g><path fill="#ffe8bb" d="M40.78 22.09c.855 5.282 3.73 5.87 6.7 5.577 2.984-.294 5.395-2.667 5.395-6.743 0-4.28-.002-4.28-6.646-5.752-6.73-1.49-6.01 3.437-5.45 6.918"/><path fill="#3e4347" d="M41.873 22.547c.243 2.534 2.61 4.357 5.287 4.072 2.674-.286 4.646-2.57 4.402-5.102-.242-2.533-.28-2.75-5.107-2.237-4.83.514-4.824.737-4.582 3.267"/><path fill="#fff" d="M43.44 21.884c.16 1.688 1.737 2.903 3.522 2.714 1.783-.19 3.098-1.712 2.936-3.4-.16-1.69-.188-1.835-3.404-1.493-3.22.344-3.217.49-3.054 2.18"/><g fill="#3e4347"><ellipse cx="47.722" cy="20.932" rx="1.45" ry="1.647"/><path d="M39.76 17.896a.982.982 0 0 1-.935-.728c-.16-.546.132-1.122.65-1.29l5.98-1.924c.517-.166 1.063.14 1.224.685.155.543-.136 1.12-.653 1.287l-5.98 1.924a.96.96 0 0 1-.287.046"/></g></svg>
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/svg/svg-lmtx-microsoft.lua b/Master/texmf-dist/doc/context/sources/general/manuals/svg/svg-lmtx-microsoft.lua
new file mode 100644
index 00000000000..9b55e87ca15
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/svg/svg-lmtx-microsoft.lua
@@ -0,0 +1,113 @@
+return {
+ [[
+ <svg id="glyph7" version="1.1" xmlns="http://www.w3.org/2000/svg">
+ <rect x="100" y="-430" width="200" height="430" fill="darkred" />
+ <rect x="100" y="-635" width="200" height="135" fill="darkblue" />
+ </svg>
+ ]],
+ [[
+ <svg id="glyph7" version="1.1" xmlns="http://www.w3.org/2000/svg" viewBox="0 1000 1000 1000">
+ <rect x="100" y="570" width="200" height="430" fill="darkgreen" />
+ <rect x="100" y="365" width="200" height="135" fill="darkblue" />
+ </svg>
+ ]],
+ [[
+ <svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <defs>
+ <g id="i-base">
+ <rect x="100" y="570" width="200" height="430" fill="darkblue" />
+ </g>
+ </defs>
+ <g id="glyph2" transform="translate(0,-1000)">
+ <use xlink:href="#i-base" />
+ </g>
+ </svg>
+ ]],
+ [[
+ <svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <defs>
+ <g id="i-base">
+ <rect x="100" y="570" width="200" height="430" fill="darkred" />
+ </g>
+ </defs>
+ <g id="glyph13" transform="translate(0,-1000)">
+ <use xlink:href="#i-base" />
+ <rect x="100" y="365" width="200" height="135" fill="darkblue" />
+ </g>
+ </svg>
+ ]],
+ [[
+ <svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <defs>
+ <g id="i-base">
+ <rect x="100" y="570" width="200" height="430" fill="darkgreen" />
+ </g>
+ </defs>
+ <g id="glyph14" transform="translate(0,-1000)">
+ <use xlink:href="#i-base" />
+ <polygon fill="darkblue" points="120,500 280,500 435,342 208,342"/>
+ </g>
+ </svg>
+ ]],
+ [[
+ <svg id="glyph7" version="1.1" xmlns="http://www.w3.org/2000/svg" viewBox="0 1000 1000 1000">
+ <defs>
+ <linearGradient id="grad" x1="0%" y1="0%" x2="0%" y2="100%">
+ <stop offset="0%" stop-color="darkblue" stop-opacity="1" />
+ <stop offset="100%" stop-color="#00aab3" stop-opacity="1" />
+ </linearGradient>
+ </defs>
+ <rect x="100" y="570" width="200" height="430" fill="blue" xfill="url(#grad)" />
+ <rect x="100" y="365" width="200" height="135" fill="green" xfill="currentColor" />
+ </svg>
+ ]],
+ [[
+ <svg id="glyph7" version="1.1" xmlns="http://www.w3.org/2000/svg" viewBox="0 1000 1000 1000">
+ <defs>
+ <linearGradient id="grad" x1="0%" y1="0%" x2="0%" y2="100%">
+ <stop offset="0%" stop-color="var(--color0,darkblue)" stop-opacity="1" />
+ <stop offset="100%" stop-color="var(--color1,#00aab3)" stop-opacity="1" />
+ </linearGradient>
+ </defs>
+ <rect x="100" y="570" width="200" height="430" fill="blue" xfill="url(#grad)" />
+ <rect x="100" y="365" width="200" height="135" fill="darkblue" />
+ </svg>
+ ]],
+ [[
+ <svg id="glyph2" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 1000 1000 1000">
+ <image x="100" y="365" width="200" height="635"
+ xlink:href="data:image/png;base64,
+ iVBORw0KGgoAAAANSUhEUgAAAMgAAAJ7CAYAAACmmd5sAAAFZklEQVR42u3XsQ3D
+ MBAEQUpw9ypahrMPGGwiwcFMCQQW9zzWuu4FbJ2eAAQCAgGBgEBAICAQEAgIBAQC
+ CAQEAgIBgYBAQCAgEBAICAQEAggEBAICAYGAQEAgIBAQCAgEEAgIBAQCAgGBgEBA
+ ICAQEAgIBBAICAQEAgIBgYBAQCAgEBAIIBAQCAgEBAICAYGAQEAgIBAQCCAQEAgI
+ BAQCAgGBgEBAICAQQCAgEBAICAQEAgIBgYBAQCAgEEAgIBAQCAgEBAICAYGAQEAg
+ IBBPAAIBgYBAQCAgEBAICAQEAgIBBAICAYGAQEAgIBAQCAgEBAICAQQCAgGBgEBA
+ ICAQEAgIBAQCCAQEAgIBgYBAQCAgEBAICAQEAggEBAICAYGAQEAgIBAQCAgEAAAA
+ AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
+ AAAA4DHHWtftGWDv80sE2Ds9AQgEBAL+IPBuIAoBJxYIBAQCPukgEHBigUBAIOAP
+ AlgQiAtiQsCCgEDAJx0sCFgQsCAgEHBigQUB5oKYELAgIBDwSQcLAhYELAgIBJxY
+ YEEACwItEIWAEwucWGBBwIKABQGBgBMLLAhYEMCCQFwQEwJOLHBigQUBCwICAScW
+ WBCwIGBBAIFAPbHcWGBBwCcdLAgIBJxYYEHAgoAFAYEA88RyY4EFAZ90sCAgEBAI
+ +IOAQMCJBQIBBALxD+ITAj7p4MQCgYBAwB8EBAJOLBAICATwB4EYiELAiQUCAYGA
+ TzoIBJxYIBAQCPiDABYE4oKYELAgIBDwSQcLAhYELAgIBJxYYEGAuSAmBCwICAR8
+ 0sGCgAUBCwICAScWWBDAgkALRCHgxAInFlgQsCBgQUAg4MQCCwIWBLAgEBfEhIAT
+ C5xYYEHAgoBAwIkFFgQsCFgQQCBQTyw3FlgQ8EkHCwICAScWWBCwIGBBQCDAPLHc
+ WGBBwCcdLAgIBAQC/iAgEHBigUAAgUD8g/iEgE86OLFAICAQ8AcBgYATCwQCAgH8
+ QSAGohBwYoFAQCDgkw4CAScWCAQEAv4ggAWBuCAmBCwICAR80sGCgAUBCwICAScW
+ WBBgLogJAQsCAgGfdLAgYEHAgoBAwIkFFgSwINACUQg4scCJBRYELAhYEBAIOLHA
+ goAFASwIxAUxIeDEAicWWBCwICAQcGKBBQELAhYEEAjUE8uNBRYEfNLBgoBAwIkF
+ FgQsCFgQEAgwTyw3FlgQ8EkHCwICAYGAPwgIBJxYIBBAIBD/ID4h4JMOTiwQCAgE
+ /EFAIODEAoGAQAB/EIiBKAScWCAQEAj4pINAwIkFAgGBgD8IYEEgLogJAQsCAgGf
+ dLAgYEHAgoBAwIkFFgSYC2JCwIKAQMAnHSwIWBCwICAQcGKBBQEsCLRAFAJOLHBi
+ gQUBCwIWBAQCTiywIGBBAAsCcUFMCDixwIkFFgQsCAgEnFhgQcCCgAUBBAL1xHJj
+ gQUBn3SwICAQcGKBBQELAhYEBALME8uNBRYEfNLBgoBAQCDgDwICAScWCAQQCMQ/
+ iE8I+KSDEwsEAgIBfxAQCDixQCAgEMAfBGIgCgEnFggEBAI+6SAQcGKBQEAg4A8C
+ WBCIC2JCwIKAQMAnHSwIWBCwICAQcGKBBQHmgpgQsCAgEPBJBwsCFgQsCAgEnFhg
+ QQALAi0QhYATC5xYYEHAgoAFAYGAEwssCFgQwIJAXBATAk4scGKBBQELAgIBJxZY
+ ELAgYEEAgUA9sdxYYEHAJx0sCAgEnFhgQcCCgAUBgQDzxHJjgQUBn3SwICAQEAj4
+ g4BAwIkFAgEEAvEP4hMCPungxAKBgEDgH3wBrUwJtCBGuc0AAAAASUVORK5CYII=
+ "/>
+ </svg>
+ ]],
+}
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/svg/svg-lmtx-mozilla.lua b/Master/texmf-dist/doc/context/sources/general/manuals/svg/svg-lmtx-mozilla.lua
new file mode 100644
index 00000000000..802efcf3d4a
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/svg/svg-lmtx-mozilla.lua
@@ -0,0 +1,365 @@
+return {
+ [[
+ <svg width="160" height="140" xmlns="http://www.w3.org/2000/svg" version="1.1">
+ <rect x="10" y="10" width="100" height="100" stroke="blue" fill="purple" fill-opacity="0.5" stroke-opacity="0.8"/>
+ </svg>
+ ]],
+ [[
+ <svg width="160" height="140" xmlns="http://www.w3.org/2000/svg" version="1.1">
+ <line x1="40" x2="120" y1="20" y2="20" stroke="black" stroke-width="20" stroke-linecap="butt"/>
+ <line x1="40" x2="120" y1="60" y2="60" stroke="black" stroke-width="20" stroke-linecap="square"/>
+ <line x1="40" x2="120" y1="100" y2="100" stroke="black" stroke-width="20" stroke-linecap="round"/>
+ </svg>
+ ]],
+ [[
+ <svg width="160" height="280" xmlns="http://www.w3.org/2000/svg" version="1.1">
+ <polyline points="40 60 80 20 120 60" stroke="black" stroke-width="20" stroke-linecap="butt" fill="none" stroke-linejoin="miter"/>
+ <polyline points="40 140 80 100 120 140" stroke="black" stroke-width="20" stroke-linecap="round" fill="none" stroke-linejoin="round"/>
+ <polyline points="40 220 80 180 120 220" stroke="black" stroke-width="20" stroke-linecap="square" fill="none" stroke-linejoin="bevel"/>
+ </svg>
+ ]],
+ [[
+ <svg width="200" height="150" xmlns="http://www.w3.org/2000/svg" version="1.1">
+ <path d="M 10 75 Q 50 10 100 75 T 190 75" stroke="black" stroke-linecap="round" stroke-dasharray="5,10,5" fill="none"/>
+ <path d="M 10 75 L 190 75" stroke="red" stroke-linecap="round" stroke-width="1" stroke-dasharray="5,5" fill="none"/>
+ </svg>
+ ]],
+ [[
+ <svg viewBox="0 0 30 10" xmlns="http://www.w3.org/2000/svg">
+ <circle cx="5" cy="5" r="3" stroke="green" />
+ <circle cx="15" cy="5" r="3" stroke="green" stroke-width="3" />
+ <circle cx="25" cy="5" r="3" stroke="green" stroke-width="2%" />
+ </svg>
+ ]],
+ [[
+ <svg viewBox="0 0 38 30" xmlns="http://www.w3.org/2000/svg">
+ <path stroke="black" fill="none" stroke-linejoin="miter" id="p1"
+ d="M1,9 l7 ,-3 l7 ,3
+ m2,0 l3.5 ,-3 l3.5 ,3
+ m2,0 l2 ,-3 l2 ,3
+ m2,0 l0.75,-3 l0.75,3
+ m2,0 l0.5 ,-3 l0.5 ,3" />
+ <path stroke="black" fill="none" stroke-linejoin="miter" stroke-miterlimit="1" id="p2"
+ d="M1,19 l7 ,-3 l7 ,3
+ m2, 0 l3.5 ,-3 l3.5 ,3
+ m2, 0 l2 ,-3 l2 ,3
+ m2, 0 l0.75,-3 l0.75,3
+ m2, 0 l0.5 ,-3 l0.5 ,3" />
+ <path stroke="black" fill="none" stroke-linejoin="miter" stroke-miterlimit="8" id="p3"
+ d="M1,29 l7 ,-3 l7 ,3
+ m2, 0 l3.5 ,-3 l3.5 ,3
+ m2, 0 l2 ,-3 l2 ,3
+ m2, 0 l0.75,-3 l0.75,3
+ m2, 0 l0.5 ,-3 l0.5 ,3" />
+ <path stroke="pink" fill="none" stroke-width="0.05"
+ d="M1, 9 l7,-3 l7,3 m2,0 l3.5,-3 l3.5,3 m2,0 l2,-3 l2,3 m2,0 l0.75,-3 l0.75,3 m2,0 l0.5,-3 l0.5,3
+ M1,19 l7,-3 l7,3 m2,0 l3.5,-3 l3.5,3 m2,0 l2,-3 l2,3 m2,0 l0.75,-3 l0.75,3 m2,0 l0.5,-3 l0.5,3
+ M1,29 l7,-3 l7,3 m2,0 l3.5,-3 l3.5,3 m2,0 l2,-3 l2,3 m2,0 l0.75,-3 l0.75,3 m2,0 l0.5,-3 l0.5,3" />
+ </svg>
+ ]],
+ [[
+ <svg viewBox="-3 0 33 10" xmlns="http://www.w3.org/2000/svg">
+ <line x1="0" y1="1" x2="30" y2="1" stroke="black" />
+ <line x1="0" y1="3" x2="30" y2="3" stroke="black" stroke-dasharray="3 1" />
+ <line x1="0" y1="5" x2="30" y2="5" stroke="black" stroke-dasharray="3 1" stroke-dashoffset="3" />
+ <line x1="0" y1="7" x2="30" y2="7" stroke="black" stroke-dasharray="3 1" stroke-dashoffset="-3" />
+ <line x1="0" y1="9" x2="30" y2="9" stroke="black" stroke-dasharray="3 1" stroke-dashoffset="1" />
+ <path d="M0,5 h-3 M0,7 h3 M0,9 h-1" stroke="rgba(255,0,0,.5)" />
+ </svg>
+ ]],
+ [[
+ <svg width="200" height="150" xmlns="http://www.w3.org/2000/svg" version="1.1">
+ <path d="M 10 75 Q 50 10 100 75 T 190 75" stroke="black" stroke-linecap="round" stroke-dasharray="5,10,5" fill="none"/>
+ <path d="M 10 75 L 190 75" stroke="red" stroke-linecap="round" stroke-dasharray="5,5" fill="none" stroke-width="1"/>
+ </svg>
+ ]],
+ [[
+ <svg viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg">
+ <path fill="none" stroke="red"
+ d="M 10,10 h 10
+ m 0,10 h 10
+ m 0,10 h 10
+ M 40,20 h 10
+ m 0,10 h 10
+ m 0,10 h 10
+ m 0,10 h 10
+ M 50,50 h 10
+ m-20,10 h 10
+ m-20,10 h 10
+ m-20,10 h 10" />
+ </svg>
+ ]],
+ [[
+ <svg viewBox="0 0 200 100" xmlns="http://www.w3.org/2000/svg">
+ <path fill="none" stroke="red" d="M 10,10 L 90,90 V 10 H 50" />
+ <path fill="none" stroke="red" d="M 110,10 l 80,80 v -80 h -40" />
+ </svg>
+ ]],
+ [[
+ <svg viewBox="0 0 200 100" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <path fill="none" stroke="red" d="M 10,90 C 30,90 25,10 50,10 S 70,90 90,90" />
+ <path fill="none" stroke="red" d="M 110,90 c 20,0 15,-80 40,-80 s 20,80 40,80" />
+ <g id="ControlPoints">
+ <line x1="10" y1="90" x2="30" y2="90" stroke="lightgrey" />
+ <circle cx="30" cy="90" r="1.5"/>
+ <line x1="50" y1="10" x2="25" y2="10" stroke="lightgrey" />
+ <circle cx="25" cy="10" r="1.5"/>
+ <line x1="50" y1="10" x2="75" y2="10" stroke="lightgrey" stroke-dasharray="2" />
+ <circle cx="75" cy="10" r="1.5" fill="lightgrey"/>
+ <line x1="90" y1="90" x2="70" y2="90" stroke="lightgrey" />
+ <circle cx="70" cy="90" r="1.5"/>
+ <circle cx="10" cy="90" r="1.5"/>
+ <circle cx="50" cy="10" r="1.5"/>
+ <circle cx="90" cy="90" r="1.5"/>
+ </g>
+ <use xlink:href="#ControlPoints" x="100" />
+ </svg>
+ ]],
+ [[
+ <svg viewBox="0 0 200 100" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <path fill="none" stroke="red" d="M 10,50 Q 25,25 40,50 t 30,0 30,0 30,0 30,0 30,0" />
+ <g>
+ <polyline points="10,50 25,25 40,50" stroke="rgba(0,0,0,.2)" fill="none" />
+ <circle cx="25" cy="25" r="1.5" />
+ <circle cx="10" cy="50" r="1.5"/>
+ <circle cx="40" cy="50" r="1.5"/>
+ <g id="SmoothQuadraticDown">
+ <polyline points="40,50 55,75 70,50" stroke="rgba(0,0,0,.2)" stroke-dasharray="2" fill="none" />
+ <circle cx="55" cy="75" r="1.5" fill="lightgrey" />
+ <circle cx="70" cy="50" r="1.5" />
+ </g>
+ <g id="SmoothQuadraticUp">
+ <polyline points="70,50 85,25 100,50" stroke="rgba(0,0,0,.2)" stroke-dasharray="2" fill="none" />
+ <circle cx="85" cy="25" r="1.5" fill="lightgrey" />
+ <circle cx="100" cy="50" r="1.5" />
+ </g>
+ <use xlink:href="#SmoothQuadraticDown" x="60" />
+ <use xlink:href="#SmoothQuadraticUp" x="60" />
+ <use xlink:href="#SmoothQuadraticDown" x="120" />
+ </g>
+ </svg>
+ ]],
+ [[
+ <svg viewBox="0 0 20 20" xmlns="http://www.w3.org/2000/svg">
+ <path fill="none" stroke="red" d="M 6,10 A 6 4 10 1 0 14,10" />
+ <path fill="none" stroke="lime" d="M 6,10 A 6 4 10 1 1 14,10" />
+ <path fill="none" stroke="purple" d="M 6,10 A 6 4 10 0 1 14,10" />
+ <path fill="none" stroke="pink" d="M 6,10 A 6 4 10 0 0 14,10" />
+ </svg>
+ ]],
+ [[
+ <svg viewBox="0 -1 30 11" xmlns="http://www.w3.org/2000/svg">
+ <path stroke="red" d="M 5,1 l -4,8 8,0" />
+ <path stroke="red" d="M 15,1 l -4,8 8,0 -4,-8" />
+ <path stroke="red" d="M 25,1 l -4,8 8,0 z" />
+ </svg>
+ ]],
+ [[
+ <svg viewBox="0 0 200 100" xmlns="http://www.w3.org/2000/svg">
+ <ellipse cx="100" cy="50" rx="100" ry="50" />
+ </svg>
+ ]],
+ [[
+ <svg viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg">
+ <line x1="0" y1="80" x2="100" y2="20" stroke="black" />
+ </svg>
+ ]],
+ [[
+ <svg viewBox="0 0 200 100" xmlns="http://www.w3.org/2000/svg">
+ <polygon points="0,100 50,25 50,75 100,0" />
+ <polygon points="100,100 150,25 150,75 200,0" fill="none" stroke="black" />
+ </svg>
+ ]],
+ [[
+ <svg viewBox="0 0 200 100" xmlns="http://www.w3.org/2000/svg">
+ <polyline points="0,100 50,25 50,75 100,0" />
+ <polyline points="100,100 150,25 150,75 200,0" fill="none" stroke="black" />
+ </svg>
+ ]],
+ [[
+ <svg viewBox="0 0 220 100" xmlns="http://www.w3.org/2000/svg">
+ <rect width="100" height="100" />
+ <rect x="120" width="100" height="100" rx="15" />
+ </svg>
+ ]],
+ [[
+ <svg viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg">
+ <path fill="none" stroke="red"
+ d="M 10,30
+ A 20,20 0,0,1 50,30
+ A 20,20 0,0,1 90,30
+ Q 90,60 50,90
+ Q 10,60 10,30 z" />
+ </svg>
+ ]],
+ [[
+ <svg viewBox="-10 -10 220 120" xmlns="http://www.w3.org/2000/svg">
+ <polygon fill-rule="nonzero" stroke="red" points="50,0 21,90 98,35 2,35 79,90"/>
+ <polygon fill-rule="evenodd" stroke="red" points="150,0 121,90 198,35 102,35 179,90"/>
+ </svg>
+ ]],
+ [[
+ <svg x="0" width="10" height="10" clip="auto">
+ <circle cx="5" cy="5" r="4" stroke="green" />
+ </svg>
+ ]],
+ [[
+ <svg x="10" width="10" height="10" clip="rect(1, 9, 8, 2)">
+ <circle cx="5" cy="5" r="4" stroke="green" />
+ </svg>
+ </svg>
+ ]],
+ [[
+ <svg viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg">
+ <rect x="0" y="0" width="100%" height="100%" fill="red"/>
+ <circle cx="50%" cy="50%" r="4" fill="yellow"/>
+ </svg>
+ ]],
+ [[
+ <svg viewBox="0 0 10 10" xmlns="http://www.w3.org/2000/svg">
+ <rect x="0" y="0" width="100%" height="100%" fill="green"/>
+ <circle cx="50%" cy="50%" r="4" fill="yellow"/>
+ </svg>
+ ]],
+ [[
+ <svg viewBox="-5 -5 10 10" xmlns="http://www.w3.org/2000/svg">
+ <rect x="0" y="0" width="100%" height="100%" fill="blue"/>
+ <circle cx="50%" cy="50%" r="4" fill="yellow"/>
+ </svg>
+ ]],
+ [[
+ <svg viewBox="0 0 200 200" xmlns="http://www.w3.org/2000/svg">
+ <rect x="10" y="10" width="30" height="20" fill="green" />
+ <rect x="10" y="10" width="30" height="20" fill="red" transform="matrix(3 1 -1 3 30 40)" />
+ </svg>
+ ]],
+ [[
+ <svg viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg">
+ <rect x="5" y="5" width="40" height="40" fill="green" />
+ <rect x="5" y="5" width="40" height="40" fill="blue" transform="translate(50)" />
+ <rect x="5" y="5" width="40" height="40" fill="red" transform="translate(0 50)" />
+ <rect x="5" y="5" width="40" height="40" fill="yellow" transform="translate(50,50)" />
+ </svg>
+ ]],
+ [[
+ <svg viewBox="-50 -50 100 100" xmlns="http://www.w3.org/2000/svg">
+ <circle cx="0" cy="0" r="10" fill="red" transform="scale(4)" />
+ <circle cx="0" cy="0" r="10" fill="yellow" transform="scale(1,4)" />
+ <circle cx="0" cy="0" r="10" fill="pink" transform="scale(4,1)" />
+ <circle cx="0" cy="0" r="10" fill="black" />
+ </svg>
+ ]],
+ [[
+ <svg viewBox="-12 -2 34 14" xmlns="http://www.w3.org/2000/svg">
+ <rect x="0" y="0" width="10" height="10" />
+ <rect x="0" y="0" width="10" height="10" fill="red" transform="rotate(100)" />
+ <rect x="0" y="0" width="10" height="10" fill="green" transform="rotate(100,10,10)" />
+ </svg>
+ ]],
+ [[
+ <svg viewBox="-5 -5 10 10" xmlns="http://www.w3.org/2000/svg">
+ <rect x="-3" y="-3" width="6" height="6" />
+ <rect x="-3" y="-3" width="6" height="6" fill="red" transform="skewX(30)" />
+ </svg>
+ ]],
+ [[
+ <svg viewBox="-5 -5 10 10" xmlns="http://www.w3.org/2000/svg">
+ <rect x="-3" y="-3" width="6" height="6" />
+ <rect x="-3" y="-3" width="6" height="6" fill="red" transform="skewY(30)" />
+ </svg>
+ ]],
+ [[
+ <svg width="100" viewBox="0 0 100 90" xmlns="http://www.w3.org/2000/svg" version="1.1">
+ <defs>
+ <path d="M50,0 21,90 98,35 2,35 79,90z" id="star" />
+ </defs>
+ <clipPath id="emptyStar">
+ <use xlink:href="#star" clip-rule="evenodd" />
+ </clipPath>
+ <rect clip-path="url(#emptyStar)" width="50" height="90" fill="blue" />
+ <clipPath id="filledStar">
+ <use xlink:href="#star" clip-rule="nonzero" />
+ </clipPath>
+ <rect clip-path="url(#filledStar)" width="50" height="90" x="50" fill="red" />
+ </svg>
+ ]],
+-- [[
+-- <svg viewBox="0 0 240 80" xmlns="http://www.w3.org/2000/svg">
+-- <style>
+-- .small { font: italic 13px sans-serif; }
+-- .heavy { font: bold 30px sans-serif; }
+-- .Rrrrr { font: italic 40px serif; fill: red; }
+-- </style>
+-- <text x="20" y="35" class="small">My</text>
+-- <text x="40" y="35" class="heavy">cat</text>
+-- <text x="55" y="55" class="small">is</text>
+-- <text x="65" y="55" class="Rrrrr">Grumpy!</text>
+-- </svg>
+-- ]],
+ [[
+ <svg viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg">
+ <defs>
+ <marker id="arrow" viewBox="0 0 10 10" refX="5" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
+ <path d="M 0 0 L 10 5 L 0 10 z" />
+ </marker>
+ <marker id="dot" viewBox="0 0 10 10" refX="5" refY="5" markerWidth="5" markerHeight="5">
+ <circle cx="5" cy="5" r="5" fill="red" />
+ </marker>
+ </defs>
+ <polyline points="10,10 10,90 90,90" fill="none" stroke="black" marker-start="url(#arrow)" marker-end="url(#arrow)" />
+ <polyline points="15,80 29,50 43,60 57,30 71,40 85,15" fill="none" stroke="grey" marker-start="url(#dot)" marker-mid="url(#dot)" marker-end="url(#dot)" />
+ </svg>
+ ]],
+ -- from the attributes section
+ [[
+ <svg viewBox="0 0 200 100" xmlns="http://www.w3.org/2000/svg">
+ <defs>
+ <linearGradient id="gradient" x1="0%" y1="0%" x2="0" y2="100%">
+ <stop offset="0%" style="stop-color:skyblue;" />
+ <stop offset="100%" style="stop-color:seagreen;" />
+ </linearGradient>
+ </defs>
+ <rect x="0" y="0" width="100%" height="100%" fill="url(#gradient)" />
+ <circle cx="50" cy="50" r="40" fill="black" />
+ <circle cx="150" cy="50" r="40" fill="black" opacity="0.3" />
+ </svg>
+ ]],
+ [[
+ <svg viewBox="0 0 400 100" xmlns="http://www.w3.org/2000/svg">
+ <circle cx="50" cy="50" r="40" />
+ <circle cx="150" cy="50" r="40" fill-opacity="0.7" />
+ <circle cx="250" cy="50" r="40" fill-opacity="50%" />
+ <circle cx="350" cy="50" r="40" style="fill-opacity: .25;" />
+ </svg>
+ ]],
+ [[
+ <svg viewBox="0 0 30 10" xmlns="http://www.w3.org/2000/svg">
+ <line x1="0" y1="1" x2="30" y2="1" stroke="black" />
+ <line x1="0" y1="3" x2="30" y2="3" stroke="black" stroke-dasharray="4" />
+ <line x1="0" y1="5" x2="30" y2="5" stroke="black" stroke-dasharray="4 1" />
+ <line x1="0" y1="7" x2="30" y2="7" stroke="black" stroke-dasharray="4 1 2" />
+ <line x1="0" y1="9" x2="30" y2="9" stroke="black" stroke-dasharray="4 1 2 3" />
+ </svg>
+ ]],
+ [[
+ <svg viewBox="-3 0 33 10" xmlns="http://www.w3.org/2000/svg">
+ <line x1="0" y1="1" x2="30" y2="1" stroke="black" />
+ <line x1="0" y1="3" x2="30" y2="3" stroke="black" stroke-dasharray="3 1" />
+ <line x1="0" y1="5" x2="30" y2="5" stroke="black" stroke-dasharray="3 1" stroke-dashoffset="3" />
+ <line x1="0" y1="7" x2="30" y2="7" stroke="black" stroke-dasharray="3 1" stroke-dashoffset="-3" />
+ <line x1="0" y1="9" x2="30" y2="9" stroke="black" stroke-dasharray="3 1" stroke-dashoffset="1" />
+ <path d="M0,5 h-3 M0,7 h3 M0,9 h-1" stroke="rgba(255,0,0,.5)" />
+ </svg>
+ ]],
+ [[
+ svg viewBox="0 0 120 120" xmlns="http://www.w3.org/2000/svg">
+ <path d="M60,15 L60,110 M30,40 L90,40 M30,75 L90,75 M30,110 L90,110" stroke="grey" />
+ <text text-anchor="start" x="60" y="40">A</text>
+ <text text-anchor="middle" x="60" y="75">A</text>
+ <text text-anchor="end" x="60" y="110">A</text>
+ <circle cx="60" cy="40" r="3" fill="red" />
+ <circle cx="60" cy="75" r="3" fill="red" />
+ <circle cx="60" cy="110" r="3" fill="red" />
+ </svg>
+ ]],
+}
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/svg/svg-lmtx.tex b/Master/texmf-dist/doc/context/sources/general/manuals/svg/svg-lmtx.tex
new file mode 100644
index 00000000000..11cf338957b
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/svg/svg-lmtx.tex
@@ -0,0 +1,547 @@
+% language=us
+
+% \enabletrackers[metapost.svg.result]
+% \enabletrackers[metapost.svg.path]
+
+\enabledirectives[pdf.compact]
+
+% \nopdfcompression
+
+\def\showSVGcode#1#2%
+ {\ctxlua{metapost.showsvgpage{
+ filename = "#1",
+ index = tonumber(#2),
+ method = "code"
+ }}}
+
+\def\showSVGcodeG#1#2%
+ {\ctxlua{metapost.showsvgpage{
+ filename = "#1",
+ index = tonumber(#2),
+ method = "code",
+ x = 0,
+ y = 1000,
+ width = 1000,
+ height = 1000,
+ noclip = true
+ }}}
+
+\def\typeSVGcode#1#2%
+ {\ctxlua{metapost.typesvgpage{
+ filename = "#1",
+ index = tonumber(#2)
+ }}}
+
+\usemodule[abbreviations-logos]
+\usemodule[scite]
+
+\setuppapersize
+ [A4,landscape]
+
+\setuplayout
+ [backspace=1cm,
+ cutspace=2cm,
+ topspace=1cm,
+ width=middle,
+ height=middle,
+ header=0pt,
+ footer=0pt]
+
+\setupbodyfont
+ [dejavu,12pt]
+
+\setupwhitespace
+ [big]
+
+\setuphead
+ [chapter]
+ [style=\bfc,
+ color=darkblue]
+
+\setuphead
+ [section]
+ [style=\bfb,
+ color=darkblue]
+
+\starttext
+
+\startMPpage
+ drawlineoptions (withpen pencircle scaled 0.4 withcolor darkgray) ;
+ drawpointoptions (withpen pencircle scaled 0.8 withcolor darkred) ;
+ drawcontroloptions(withpen pencircle scaled 0.6 withcolor darkgreen) ;
+ drawpathoptions (withpen pencircle scaled 1.0 withcolor darkblue) ;
+
+ drawoptionsfactor := .5 ;
+ detailpaths ;
+
+ StartPage ;
+
+ fill Page withcolor darkblue ;
+
+ draw lmt_svg [
+ filename = "svglogo.svg",
+ origin = true,
+ ]
+ ysized (PaperHeight -64mm)
+ shifted (12mm,52mm) ;
+
+ draw textext.llft ("\strut in context")
+ ysized 34mm
+ shifted lrcorner Page
+ shifted (-8mm,84mm)
+ withcolor white ;
+
+ draw textext.llft ("\strut and metafun xl")
+ ysized 34mm
+ shifted lrcorner Page
+ shifted (-8mm,44mm)
+ withcolor white ;
+
+
+ StopPage ;
+\stopMPpage
+
+\starttitle[title=Introduction]
+
+This document is about using \SVG, an \XML\ based format for describing graphics
+and colorful font shapes in \CONTEXT. It's one of the external figure formats.
+Where we can use \METAPOST\ for all kind of systematic graphics, bitmap images
+and artistic outlines come from outside. Inclusion of \SVG\ using the methods
+discussed here is quite efficient and will work for many graphics, but when it
+doesn't you can always fall back on a conversion by \INKSCAPE. It's work in
+progress anyway.
+
+The document is made for viewing on the screen and has a bunch of examples taken
+from websites. We might add more in due time. The cover page has the \SVG\ logo
+taken from \WIKIPEDIA\ but with some details added. It's not a nice cover image
+but it will do for our purpose. Feel free to suggest additional examples.
+
+\startlines
+Hans Hagen
+Hasselt NL
+October 2019\high{+}
+\stoplines
+
+\stoptitle
+
+\starttitle[title=The \SVG\ format]
+
+\startsection[title=What it is]
+
+The Scalable Vector Graphics format (\SVG) showed up around the turn of this
+century. I remember looking into it and wondering to what extent it was a fresh
+development and not some kind of application format turned \XML. Most elements
+are empty elements and data lives in attributes. What I found most puzzling is
+that a path definition was an attribute and not just content, especially because
+it can be a pretty large blob of numbers and commands. Anyway, at that time I
+played a bit with conversion but in the end decided to just consider it an
+external format for which conversion to (say) \PDF\ by an external program was a
+reasonable. At some point that external program became \INKSCAPE\ and \CONTEXT\
+uses that to convert \SVG\ images to \PDF\ runtime (with caching).
+
+In the meantime edition one turned edition two and the advance of \HTML\ and
+\CSS\ has crept features into the format, thereby not making it look better. But,
+because viewers support rendering \SVG, we now also see graphics showing up. The
+ones that I have to deal with are educational graphics, and when you look into
+the files, they can be curiously inconsistent in the way parts of graphics are
+made. For instance, the numbers along an axis of a mathematical graphic can be a
+mix of references to a font (\type {<text/>}), references to symbols \type
+{<symbol/>} that have paths (\type {<path/>}) or just paths \type {<path/>}.
+Using a tool that can spit out something structured doesn't mean that all its
+users will structure.
+
+The \SVG\ format provides lines, rectangles, circles, ellipses, polylines,
+polygons and paths. Paths are defines as a sequence of moves, lines, cubic and
+quadratic curves, arcs, collected in the \type {d} attribute (a funny short name
+compared to the length of its content and the verbosity of other attribute
+names). They can be open or closed, and use different winding rules. Positions
+are absolute or relative. This all leaves a lot of room for error and confusion.
+When a path looks bad, it can be produced bad, or the interpretation can be bad.
+Interpretation can even be such that errors are catched which makes it hard to
+figure out what is really wrong. And as usual, bugs (and supposed catches) can
+become features in the end. So it might take a while before this kind of support
+in \CONTEXT\ becomes stable but once it is, normally we're okay for a while. And,
+one nice side effect of \XML\ is that it can't really crash processing as it's
+just data.
+
+\stopsection
+
+\startsection[title=Color fonts]
+
+Then color fonts showed up in \OPENTYPE\ and \SVG\ is one of the used
+sub|-|formats in that. Again it was convenient enough to rely on \INKSCAPE\ to do
+the conversion to \PDF\ blobs, but after a while I decided that a more native
+(built|-|in) support start making sense. A lot had happened since 2000, most
+noticeably the arrival of \LUATEX\ and \CONTEXT\ \MKIV\ followed by \LUAMETATEX\
+and \CONTEXT\ \LMTX, so a more direct support because more feasible. A more
+direct support has the advantage that we don't need to call an external program
+and cache the results (think of Emoji fonts with thousands of glyphs in \SVG\
+format). Also, direct conversion makes it possible to tweak colors and such,
+simply because the data goes through the \CONTEXT\ internals as part of the
+typesetting process. So, as a prelude to the \CONTEXT\ 2019 meeting a preliminary
+converter was made, color font support was partially redone, and afterward the
+converter got completed to the level needed for embedding more fancy graphics,
+including relabeling.
+
+\stopsection
+
+\startsection[title=In practice]
+
+In the end all is about paths or glyphs, plus some optional clipping and
+transformations. The rendering is controlled by attributes: color, transparency,
+line thickness, the way lines join and end, etc. Now, in the original
+specification that was done only with attributes, which is a clean and robust way
+of doing it, but later styles and classes were introduced and we now have a whole
+chain to consider when resolving a to be used attribute.
+
+\startitemize[packed]
+ \startitem attributes explicitly set by keys to an element \stopitem
+ \startitem attributes set in the \type {style} attribute \stopitem
+ \startitem attributes set via one or more \type {class} assignments \stopitem
+ \startitem attributes set for the specific element \stopitem
+ \startitem attributes inherited from an ancestor (somewhat vague) \stopitem
+ \startitem redundant (nested) attributes (text styling) \stopitem
+\stopitemize
+
+Where examples are often hand codes and therefore look ok, graphics that get
+generated can look quite horrible: the same parameters being set with different
+methods, even inconsistently, to mention one. But also, graphics can be read in,
+tweaked and saved again which in itself generates artifacts, etc. One can of
+course argue that \XML\ is not for human consumption but personally I tend to
+conclude that when a source file looks bad, the likelyhood is great that what it
+encodes looks bad too. And for instance \INKSCAPE\ provides ways to inspect and
+tweak the \XML\ in the editor.
+
+\stopsection
+
+\startsection[title=The conversion]
+
+This brings us to the conversion. As we need \PDF\ operators one method is to
+directly go from \SVG\ to \PDF. There is the issue of fonts, but as we delegate
+that to \TEX\ anyway, because that is kind of an abstraction. Such a conversion
+is comparable with going from \METAPOST\ to \PDF. However, for practical reasons
+an intermediate step has been chosen: we go from \SVG\ to \METAPOST\ first. This
+has the benefit that we need little code for color and transparency because
+\METAPOST\ (read: \METAFUN) already deals with that. We also don't need that much
+for text, as we deal with that in \METAPOST\ too, and that way we can even
+overload and reposition for instance labels in graphics relatively easy.
+
+Another advantage of the intermediate step is that we can combine \SVG\ graphics
+with \METAPOST\ code. Of course we can already combine external graphics with
+\METAPOST, but there is a big advantage here: the output is quite efficient. When
+we transform paths and pens in \METAPOST, the end result is often just a path,
+but where we to do a direct conversion to \PDF, we would either have to do
+calculations on our own, or we would have to use lots of transformation
+directives. In the end, especially because \METAPOST\ is so fast, the indirect
+route pays of well (and I haven't even optimized it yet).
+
+\stopsection
+
+\startsection[title=Remark]
+
+In the perspective if using \TEX\ and \METAPOST\ it makes sense to keep an eye on
+consistency. You can make quite structured \SVG\ images if you want to. When you
+use a graphical editor you can even consider using a normal text editor to clean
+up the code occasionally. The cleaner the code, the more predictable the outcome
+will become. Looking at the code might also give an impression of what features
+not to use of use differently. Of course this makes most sense in situations
+where there are many graphics and long|-|term (re)use is needed.
+
+\stopsection
+
+\stoptitle
+
+\starttitle[title=Embedding graphics]
+
+\startsection[title=External figures]
+
+At least for now, the default \SVG\ inclusions is done via an external converter
+but you can use the internal one by specifying a conversion. The next example
+demonstrates that it works like any external figure:
+
+\startbuffer
+\startcombination[4*1]
+ {\externalfigure[mozilla-tiger.svg][conversion=mp]} {1}
+ {\externalfigure[mozilla-tiger.svg][conversion=mp,height=1cm]} {2}
+ {\externalfigure[mozilla-tiger.svg][conversion=mp,height=3cm,width=1cm]} {3}
+ {\externalfigure[mozilla-tiger.svg][conversion=mp,height=1cm,width=8cm]} {4}
+\stopcombination
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+We get:
+
+\startlinecorrection
+ \getbuffer
+\stoplinecorrection
+
+\stopsection
+
+\startsection[title=Internal figures]
+
+You can put some \SVG\ code in a buffer:
+
+\startbuffer
+\startbuffer[svgtest]
+ <svg>
+ <rect
+ x="0" y="0" width="80" height="20"
+ fill="blue" stroke="red" stroke-width="3"
+ stroke-linejoin="miter"
+ transform="rotate(10)"
+ />
+ </svg>
+\stopbuffer
+\stopbuffer
+
+\typebuffer[option=TEX] \getbuffer
+
+In the future more options might be added but for now there's only an offset
+possible:
+
+\startbuffer
+\startcombination[2*1]
+ {\framed[offset=overlay]{\includesvgbuffer[svgtest]}} {default}
+ {\framed[offset=overlay]{\includesvgbuffer[svgtest][offset=2bp]}} {some offset}
+\stopcombination
+\stopbuffer
+
+\typebuffer[option=TEX] \getbuffer
+
+There is a companion command \type {\includesvgfile} which accepts a filename
+and also supports offsets. Sometimes the offset is needed to prevent unwanted
+clipping.
+
+\stopsection
+
+\startsection[title=Mixing in \METAFUN]
+
+An \SVG\ image can be directly included in an \METAFUN\ image. This makes it
+possible to enhance (or manipulate) such an image, as in:
+
+\startbuffer
+\startMPcode
+ draw lmt_svg [
+ filename = "mozilla-tiger.svg",
+ origin = true,
+ ] rotated 45 slanted .75 ysized 2cm ;
+
+ setbounds currentpicture to
+ boundingbox currentpicture
+ enlarged 1mm ;
+
+ addbackground
+ withcolor "darkgray" ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+An \SVG\ image included this way becomes a regular \METAPOST\ picture, so a
+collection of paths. Because \METAPOST\ on the average produces rather compact
+output the \SVG\ image normally also is efficiently embedded. You don't need to
+worry about loosing quality, because \METAPOST\ is quite accurate and we use so
+called \quote {double} number mode anyway.
+
+\startlinecorrection
+ \getbuffer
+\stoplinecorrection
+
+Another trick is to inline the code:
+
+\startbuffer
+\startMPcode
+ draw svg "<svg>
+ <circle
+ cx='50' cy='50' r='40'
+ stroke='green' stroke-width='10' stroke-opacity='0.3'
+ fill='red' fill-opacity='0.3'
+ />
+ <circle
+ cx='150' cy='50' r='40'
+ stroke='green' stroke-width='10'
+ fill='red'
+ opacity='0.3'
+ />
+ </svg>" ;
+\stopMPcode
+\stopbuffer
+
+It doesn't really make sense as \METAPOST\ code is just as simple but
+it looks cool:
+
+\startlinecorrection
+ \getbuffer
+\stoplinecorrection
+
+And actually it's less code (which internally of course expands to
+more):
+
+\startbuffer
+\startMPcode
+ pickup pencircle scaled 10;
+ path p ; p := fullcircle scaled 80 ;
+ fill p shifted (50,50) withcolor blue
+ withtransparency(1,0.3) ;
+ draw p shifted (50,50) withcolor yellow
+ withtransparency(1,0.3) ;
+ draw image (
+ fill p shifted (150,50) withcolor blue ;
+ draw p shifted (150,50) withcolor yellow ;
+ setgroup currentpicture to boundingbox currentpicture
+ withtransparency(1,0.3) ;
+ ) ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+It's all a matter of taste. Watch the grouping trick!
+
+\startlinecorrection
+ \getbuffer
+\stoplinecorrection
+
+\stopsection
+
+\startsection[title=Fonts]
+
+{\em This is still experimental.}
+
+\stopsection
+
+\startsection[title=Labels]
+
+{\em This is still experimental.}
+
+\stopsection
+
+\startsection[title=Tracing]
+
+{\em This is still experimental.}
+
+\stopsection
+
+\stoptitle
+
+\starttitle[title=Mozilla test snippets]
+
+The Mozilla documentation pages for \SVG\ are pretty good and contain snippets
+that can be used for testing. More examples might be added in due time.
+
+\dorecurse{38}{
+ \page
+ \startsection[title=Snippet #1]
+ \framed
+ [offset=overlay]
+ {\scale[height=4cm]{\showSVGcode{svg-lmtx-mozilla.lua}{#1}}}
+ \blank
+ \start
+ \switchtobodyfont[10pt]
+ \setupalign[flushleft,verytolerant,broad]
+ \typeSVGcode{svg-lmtx-mozilla.lua}{#1}
+ \par
+ \stop
+ \stopsection
+ \page
+}
+
+\stoptitle
+
+\starttitle[title=Microsoft test snippets]
+
+These snippets come from the \MICROSOFT\ typography pages that discuss \OPENTYPE\
+and \SVG. Because these are actually examples of glyphs, we need to set some
+defaults:
+
+\starttabulate[|cT|rT|]
+\NC x \NC 0 \NC \NR
+\NC y \NC 1000 \NC \NR
+\NC width \NC 1000 \NC \NR
+\NC height \NC 1000 \NC \NR
+\stoptabulate
+
+in order to get the right placement. This has to do with the fact that the
+vertical \SVG\ coordinates go in the other direction compared to \METAPOST\ and
+\PDF.
+
+\dorecurse{8}{
+ \page
+ \startsection[title=Snippet #1]
+ \framed
+ [offset=overlay]
+ {\scale[height=4cm]{\showSVGcodeG{svg-lmtx-microsoft.lua}{#1}}}
+ \blank
+ \start
+ \switchtobodyfont[10pt]
+ \setupalign[flushleft,verytolerant,broad]
+ \typeSVGcode{svg-lmtx-microsoft.lua}{#1}
+ \par
+ \stop
+ \page
+ \stopsection
+ \page
+}
+
+\stoptitle
+
+\starttitle[title=Xah Lee test snippets]
+
+These snippets come from the \type {http://xahlee.info/js/svg_path_spec.html},
+which gives a nice overview of \SVG. Not all examples are here. There are some
+nice interactive examples there plus info about using fonts.
+
+\dorecurse{38}{
+ \page
+ \startsection[title=Snippet #1]
+ \framed
+ [offset=overlay]
+ {\scale[height=4cm]{\showSVGcodeG{svg-lmtx-xahlee.lua}{#1}}}
+ \blank
+ \start
+ \switchtobodyfont[10pt]
+ \setupalign[flushleft,verytolerant,broad]
+ \typeSVGcode{svg-lmtx-xahlee.lua}{#1}
+ \par
+ \stop
+ \page
+ \stopsection
+ \page
+}
+
+\stoptitle
+
+\starttitle[title=Our own snippets]
+
+These snippets were made as part if testing. I had some 1500 \SVG\ graphics that
+internally were quite messy (it's surprising what some applications export) so I
+sometimes had to extract bits and pieces and make my own tests to figure out how
+to deal with it.
+
+\dorecurse{2}{
+ \page
+ \startsection[title=Snippet #1]
+ \framed
+ [offset=overlay]
+ {\scale[height=4cm]{\showSVGcode{svg-lmtx-context.lua}{#1}}}
+ \blank
+ \start
+ \switchtobodyfont[10pt]
+ \setupalign[flushleft,verytolerant,broad]
+ \typeSVGcode{svg-lmtx-context.lua}{#1}
+ \par
+ \stop
+ \page
+ \stopsection
+ \page
+}
+
+\stoptitle
+
+\stoptext
+
+% After some contemplating, while listening to Benmont Tench's solo album (2014),
+% after first listening to a nice long interview, which I hit after following some
+% Hammond links, I finally decided that it made sense to write this manual. Life is
+% too short for delays.
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/svg/svglogo.svg b/Master/texmf-dist/doc/context/sources/general/manuals/svg/svglogo.svg
new file mode 100644
index 00000000000..c23d92b82f8
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/svg/svglogo.svg
@@ -0,0 +1,261 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="100%" height="100%" viewBox="0 0 100 100">
+
+ <title>SVG Logo</title>
+
+ <a xlink:href="http://www.w3.org/Graphics/SVG/"
+ xlink:title="W3C SVG Working Group home page">
+
+ <rect
+ id="background"
+ fill="#FF9900"
+ width="100"
+ height="100"
+ rx="4"
+ ry="4"/>
+
+ <rect
+ id="top-left"
+ fill="#FFB13B"
+ width="50"
+ height="50"
+ rx="4"
+ ry="4"/>
+
+ <rect
+ id="bottom-right"
+ x="50"
+ y="50"
+ fill="#DE8500"
+ width="50"
+ height="50"
+ rx="4"
+ ry="4"/>
+
+ <g id="circles" fill="#FF9900">
+ <circle
+ id="n"
+ cx="50"
+ cy="18.4"
+ r="18.4"/>
+
+ <circle
+ id="ne"
+ cx="72.4"
+ cy="27.6"
+ r="18.4"/>
+
+ <circle
+ id="e"
+ cx="81.6"
+ cy="50"
+ r="18.4"/>
+
+ <circle
+ id="se"
+ cx="72.4"
+ cy="72.4"
+ r="18.4"/>
+
+ <circle
+ id="s"
+ cx="50"
+ cy="81.6"
+ r="18.4"/>
+
+ <circle
+ id="sw"
+ cx="27.6"
+ cy="72.4"
+ r="18.4"/>
+
+ <circle
+ id="w"
+ cx="18.4"
+ cy="50"
+ r="18.4"/>
+
+ <circle
+ id="nw"
+ cx="27.6"
+ cy="27.6"
+ r="18.4"/>
+ </g>
+
+ <g id="stars">
+ <path
+ id="black-star"
+ d="M 63.086, 18.385
+ c 0.000, -7.227 -5.859,-13.086 -13.100,-13.086
+ c -7.235, 0.000 -13.096, 5.859 -13.096, 13.086
+ c -5.100, -5.110 -13.395, -5.110 -18.497, 0.000
+ c -5.119, 5.120 -5.119, 13.408 0.000, 18.524
+ c -7.234, 0.000 -13.103, 5.859 -13.103, 13.085
+ c 0.000, 7.230 5.870, 13.098 13.103, 13.098
+ c -5.119, 5.110 -5.119, 13.395 0.000, 18.515
+ c 5.102, 5.104 13.397, 5.104 18.497, 0.000
+ c 0.000, 7.228 5.860, 13.083 13.096, 13.083
+ c 7.240, 0.000 13.100, -5.855 13.100,-13.083
+ c 5.118, 5.104 13.416, 5.104 18.513, 0.000
+ c 5.101, -5.120 5.101,-13.410 0.000,-18.515
+ c 7.216, 0.000 13.081, -5.869 13.081,-13.098
+ c 0.000, -7.227 -5.865,-13.085 -13.081,-13.085
+ c 5.101, -5.119 5.101,-13.406 0.000,-18.524
+ C 76.502, 13.275 68.206, 13.275 63.086, 18.385 z"/>
+
+ <path
+ id="white-star"
+ fill="#FFFFFF"
+ d="M 55.003, 23.405
+ v 14.488
+ L 65.260, 27.640
+ c 0.000, -1.812 0.691,-3.618 2.066, -5.005
+ c 2.780, -2.771 7.275,-2.771 10.024, 0.000
+ c 2.771, 2.766 2.771, 7.255 0.000, 10.027
+ c -1.377, 1.375 -3.195, 2.072 -5.015, 2.072
+ L 62.101, 44.982
+ H 76.590
+ c 1.290, -1.280 3.054,-2.076 5.011, -2.076
+ c 3.900, 0.000 7.078, 3.179 7.078, 7.087
+ c 0.000, 3.906 -3.178, 7.088 -7.078, 7.088
+ c -1.957, 0.000 -3.721,-0.798 -5.011, -2.072
+ H 62.100
+ l 10.229, 10.244
+ c 1.824, 0.000 3.642, 0.694 5.015, 2.086
+ c 2.774, 2.759 2.774, 7.250 0.000, 10.010
+ c -2.750, 2.774 -7.239, 2.774 -10.025, 0.000
+ c -1.372, -1.372 -2.064,-3.192 -2.064, -5.003
+ L 55.000, 62.094
+ v 14.499
+ c 1.271, 1.276 2.084, 3.054 2.084, 5.013
+ c 0.000, 3.906 -3.177, 7.077 -7.098, 7.077
+ c -3.919, 0.000 -7.094,-3.167 -7.094, -7.077
+ c 0.000, -1.959 0.811,-3.732 2.081, -5.013
+ V 62.094
+ L 34.738, 72.346
+ c 0.000, 1.812 -0.705, 3.627 -2.084, 5.003
+ c -2.769, 2.772 -7.251, 2.772 -10.024, 0.000
+ c -2.775, -2.764 -2.775,-7.253 0.000,-10.012
+ c 1.377, -1.390 3.214,-2.086 5.012, -2.086
+ l 10.257,-10.242
+ H 23.414
+ c -1.289, 1.276 -3.072, 2.072 -5.015, 2.072
+ c -3.917, 0.000 -7.096,-3.180 -7.096, -7.088
+ s 3.177, -7.087 7.096,-7.087
+ c 1.940, 0.000 3.725, 0.796 5.015, 2.076
+ h 14.488
+ L 27.646, 34.736
+ c -1.797, 0.000 -3.632,-0.697 -5.012, -2.071
+ c -2.775, -2.772 -2.775,-7.260 0.000,-10.027
+ c 2.773, -2.771 7.256,-2.771 10.027, 0.000
+ c 1.375, 1.386 2.083, 3.195 2.083, 5.005
+ l 10.235, 10.252
+ V 23.407
+ c -1.270, -1.287 -2.082,-3.053 -2.082, -5.023
+ c 0.000, -3.908 3.175,-7.079 7.096, -7.079
+ c 3.919, 0.000 7.097, 3.168 7.097, 7.079
+ C 57.088, 20.356 56.274,22.119 55.003, 23.405 z"/>
+ </g>
+
+ <g id="svg-textbox">
+ <path
+ id="text-backdrop"
+ fill="black"
+ d="M 5.30,50.00
+ H 94.68
+ V 90.00
+ Q 94.68,95.00 89.68,95.00
+ H 10.30
+ Q 5.30,95.00 5.30,90.00 Z"/>
+
+ <path
+ id="shine"
+ fill="#3F3F3F"
+ d="M 14.657,54.211
+ h 71.394
+ c 2.908, 0.000 5.312, 2.385 5.312, 5.315
+ v 17.910
+ c -27.584,-3.403 -54.926,-8.125 -82.011,-7.683
+ V 59.526
+ C 9.353,56.596 11.743,54.211 14.657,54.211
+ L 14.657,54.211 z"/>
+
+ <g id="svg-text">
+ <title>SVG</title>
+ <path
+ id="S"
+ fill="#FFFFFF"
+ stroke="#000000"
+ stroke-width="0.5035"
+ d="M 18.312,72.927
+ c -2.103,-2.107 -3.407, -5.028 -3.407, -8.253
+ c 0.000,-6.445 5.223,-11.672 11.666,-11.672
+ c 6.446, 0.000 11.667, 5.225 11.667, 11.672
+ h -6.832
+ c 0.000,-2.674 -2.168, -4.837 -4.835, -4.837
+ c -2.663, 0.000 -4.838, 2.163 -4.838, 4.837
+ c 0.000, 1.338 0.549, 2.536 1.415, 3.420
+ l 0.000, 0.000
+ c 0.883, 0.874 2.101, 1.405 3.423, 1.405
+ v 0.012
+ c 3.232, 0.000 6.145, 1.309 8.243, 3.416
+ l 0.000, 0.000
+ c 2.118, 2.111 3.424, 5.034 3.424, 8.248
+ c 0.000, 6.454 -5.221, 11.680 -11.667, 11.680
+ c -6.442, 0.000 -11.666, -5.222 -11.666,-11.680
+ h 6.828
+ c 0.000, 2.679 2.175, 4.835 4.838, 4.835
+ c 2.667, 0.000 4.835, -2.156 4.835, -4.835
+ c 0.000,-1.329 -0.545, -2.527 -1.429, -3.407
+ l 0.000, 0.000
+ c -0.864,-0.880 -2.082, -1.418 -3.406, -1.418
+ l 0.000, 0.000
+ C 23.341,76.350 20.429, 75.036 18.312, 72.927
+ L 18.312,72.927
+ L 18.312,72.927 z"/>
+ <polygon
+ id="V"
+ fill="#FFFFFF"
+ stroke="#000000"
+ stroke-width="0.5035"
+ points="61.588,53.005
+ 53.344,92.854
+ 46.494,92.854
+ 38.236,53.005
+ 45.082,53.005
+ 49.920,76.342
+ 54.755,53.005"/>
+
+ <path
+ id="G"
+ fill="#FFFFFF"
+ stroke="#000000"
+ stroke-width="0.5035"
+ d="M 73.255,69.513
+ h 11.683
+ v 11.664
+ l 0.000, 0.000
+ c 0.000, 6.452 -5.226,11.678 -11.669, 11.678
+ c -6.441, 0.000 -11.666,-5.226 -11.666,-11.678
+ l 0.000, 0.000
+ V 64.676
+ h -0.017
+ C 61.586,58.229 66.827,53.000 73.253, 53.000
+ c 6.459, 0.000 11.683, 5.225 11.683, 11.676
+ h -6.849
+ c 0.000,-2.674 -2.152,-4.837 -4.834, -4.837
+ c -2.647, 0.000 -4.820, 2.163 -4.820, 4.837
+ v 16.501
+ l 0.000, 0.000
+ c 0.000, 2.675 2.173, 4.837 4.820, 4.837
+ c 2.682, 0.000 4.834,-2.162 4.834, -4.827
+ v -0.012
+ v -4.827
+ h -4.834
+ L 73.255,69.513
+ L 73.255,69.513 z"/>
+ </g>
+ </g>
+ </a>
+</svg>
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/swiglib/swiglib-mkiv-gm-1.pdf b/Master/texmf-dist/doc/context/sources/general/manuals/swiglib/swiglib-mkiv-gm-1.pdf
index 4f321315455..0b6b41e9848 100644
--- a/Master/texmf-dist/doc/context/sources/general/manuals/swiglib/swiglib-mkiv-gm-1.pdf
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/swiglib/swiglib-mkiv-gm-1.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/workflows/workflows-graphics.tex b/Master/texmf-dist/doc/context/sources/general/manuals/workflows/workflows-graphics.tex
index 55a8ad701e0..2cff143f41f 100644
--- a/Master/texmf-dist/doc/context/sources/general/manuals/workflows/workflows-graphics.tex
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/workflows/workflows-graphics.tex
@@ -145,9 +145,54 @@ of special and only makes sense when you use the graphic database options. The
and how conversion of images takes place.
The \type {graphics.lognames} will make sure that some extra information about
-used graphics is saved in the log file, while \type {graphics.usage} will produce
-a file \typ {<jobname>-figures-usage.lua} that contains information about found
-(or not found) images and the way they are used.
+used graphics is saved in the log file, The \type {graphics.usage} tracker will
+produce a file \typ {<jobname>-figures-usage.lua} that contains information about
+found (or not found) images and the way they are used.
+
+\stopsection
+
+\startsection[title=Compression]
+
+A \PNG\ image uses several methods for compression. The image data itself can be
+compacted by taking pixels around each individual pixel into account. Storing
+deltas instead of absolute values can for instance result in strips of zeros.
+These in turn compress well using zlib compression. Each scanline starts with a
+filterbyte that indicates how to look at the surrounding pixels. While in \PDF\ a
+\JPEG\ image is included as|-|is, a \PNG\ often take a bit more work. A
+(optional) mask has to be split off, as does an (optional) index. In the worst
+case we need to deinterlace. The \PNG\ inclusion mechanism in \CONTEXT\ \LMTX\
+takes care of this in an as efficient as possible way. Nevertheless there are
+some knobs you can turn:
+
+\starttyping
+\enabledirectives[graphics.png.recompress]
+\enabledirectives[graphics.png.compresslevel=9]
+\stoptyping
+
+A higher compress level makes the run somewhat smaller but also fives smaller
+files. The default compress level is~3. When an image doesn't need to be
+transformed (due to mask, index or interlace), you have to force recompression
+with the \type {recompress} directive. The sample image \type {mill.png} has a
+size of \type {154,869} bytes.
+
+\starttyping
+\startTEXpage
+ \externalfigure[mill.png]
+\stopTEXpage
+\stoptyping
+
+The next table shows the consequences of setting the directives. The runtime is
+of course dependent of the machine you run the sample on. If you have lots of
+images it might make sense to have a final run with a higher compress level. The
+\PDF\ file has some extra overhead (like metadata and page related information).
+
+\starttabulate[|l|c|c|c|]
+\BC \BC compression \BC filesize \BC runtime \NC \NR
+\BC default \NC \NC 156,964 \NC 0.516 \NC \NR
+\BC recompress \NC 3 \NC 144,418 \NC 0.531 \NC \NR
+\BC compresslevel \NC 0 \NC 281,071 \NC 0.516 \NC \NR
+\BC compresslevel \NC 9 \NC 137,375 \NC 0.547 \NC \NR
+\stoptabulate
\stopsection
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/workflows/workflows-mkiv.tex b/Master/texmf-dist/doc/context/sources/general/manuals/workflows/workflows-mkiv.tex
index 52070c49e02..a6d29ac429c 100644
--- a/Master/texmf-dist/doc/context/sources/general/manuals/workflows/workflows-mkiv.tex
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/workflows/workflows-mkiv.tex
@@ -15,7 +15,7 @@
% Group journal or otherwise. Thanks to the editors for corrections. Also thanks
% to users for testing, feedback and corrections.
-\setupbackend[export=yes]
+% \setupbackend[export=yes]
\environment workflows-style