summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/context/sources
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2020-03-05 00:48:46 +0000
committerKarl Berry <karl@freefriends.org>2020-03-05 00:48:46 +0000
commitf210bce174e1f2f05305ab03e88e120a1cbfc4da (patch)
tree5c4e2ad096b5c745e859516ac3196fa0864292d5 /Master/texmf-dist/doc/context/sources
parent35fd641a3546acc0c62e0aa7f134888e36da30d4 (diff)
context (from cont-tmf.zip of Feb 17 16:00, size 116339406)
git-svn-id: svn://tug.org/texlive/trunk@54086 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/context/sources')
-rw-r--r--Master/texmf-dist/doc/context/sources/general/fonts/manuals-explaining-contents.tex11
-rw-r--r--Master/texmf-dist/doc/context/sources/general/fonts/manuals-explaining-cover.tex199
-rw-r--r--Master/texmf-dist/doc/context/sources/general/fonts/manuals-explaining-environment.tex325
-rw-r--r--Master/texmf-dist/doc/context/sources/general/leaflets/leaflet-common.tex80
-rw-r--r--Master/texmf-dist/doc/context/sources/general/leaflets/leaflet-context.tex129
-rw-r--r--Master/texmf-dist/doc/context/sources/general/leaflets/leaflet-luametatex.tex106
-rw-r--r--Master/texmf-dist/doc/context/sources/general/leaflets/leaflet-mixing.tex450
-rw-r--r--Master/texmf-dist/doc/context/sources/general/magazines/mag-1104-mkiv.tex813
-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.tex (renamed from Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-appendix.tex)0
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-demo-rule.lua (renamed from Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-demo-rule.lua)0
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-environment.tex (renamed from Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-environment.tex)0
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-extensions.tex (renamed from Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-extensions.tex)0
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-features.tex (renamed from Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-features.tex)0
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-formats.tex (renamed from Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-formats.tex)0
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-hooks.tex (renamed from Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-hooks.tex)0
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-introduction.tex (renamed from Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-introduction.tex)0
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-lookups.tex (renamed from Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-lookups.tex)0
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-math.tex (renamed from Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-math.tex)0
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-methods.tex (renamed from Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-methods.tex)0
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-mkiv.tex (renamed from Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-mkiv.tex)0
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-modes.tex (renamed from Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-modes.tex)0
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-scripts.tex (renamed from Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-scripts.tex)0
-rw-r--r--Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-tricks.tex (renamed from Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-tricks.tex)0
-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
145 files changed, 33209 insertions, 1248 deletions
diff --git a/Master/texmf-dist/doc/context/sources/general/fonts/manuals-explaining-contents.tex b/Master/texmf-dist/doc/context/sources/general/fonts/manuals-explaining-contents.tex
deleted file mode 100644
index 3e1fadabc13..00000000000
--- a/Master/texmf-dist/doc/context/sources/general/fonts/manuals-explaining-contents.tex
+++ /dev/null
@@ -1,11 +0,0 @@
-% language=uk
-
-\startcomponent manuals-explaining-contents
-
- \starttitle[title=Contents][color=darkgray]
-
- \placelist[chapter][criterium=text]
-
- \stoptitle
-
-\stopcomponent
diff --git a/Master/texmf-dist/doc/context/sources/general/fonts/manuals-explaining-cover.tex b/Master/texmf-dist/doc/context/sources/general/fonts/manuals-explaining-cover.tex
deleted file mode 100644
index 8b4f3e891ba..00000000000
--- a/Master/texmf-dist/doc/context/sources/general/fonts/manuals-explaining-cover.tex
+++ /dev/null
@@ -1,199 +0,0 @@
-% language=uk
-
-% Please try to be original and don't just copy this cover page as I don't want
-% confusion and be associated with (or responsibility for the look of) similar
-% looking documents.
-
-\startenvironment manuals-explaining-cover
-
-\startsetups document:abstract
- \framed [
- foregroundstyle=bold,
- foregroundcolor=white,
- width=7.5cm,
- align={normal,tolerant},
- frame=off,
- strut=no,
- ] {
- \getbuffer[abstract]
- }
-\stopsetups
-
-\startMPinclusions
-
- def DrawCoverPage (expr what) =
-
- numeric variant ; variant := 1 ;
-
- StartCover ;
-
- save width, height, size, anchor, offset, colors ;
-
- numeric width, height, size ; pair anchor, offset ; string colors[] ;
-
- colors[1] := "\documentvariable{cover:color:1}" ;
- colors[2] := "\documentvariable{cover:color:2}" ;
- colors[3] := "\documentvariable{cover:color:3}" ;
- colors[4] := "\documentvariable{cover:color:4}" ;
- colors[5] := "\documentvariable{cover:color:5}" ;
-
- fill CoverPage enlarged PaperBleed withcolor colors[5] ;
-
- fill Spine bottomenlarged -.5PaperHeight withcolor colors[3] ;
- fill Spine topenlarged -.5PaperHeight withcolor colors[2] ;
-
- width := FrontPageWidth ;
- height := FrontPageHeight ;
- size := 4 * width / 3 ;
- offset := (-1cm,1cm) ;
- anchor := .5[lrcorner CoverPage,urcorner CoverPage] ;
-
- fill anchored.llft(lltriangle scaled size, urcorner FrontPage) withcolor colors[1] ;
- fill anchored.urt (urtriangle scaled size, llcorner FrontPage) withcolor colors[2] ;
- fill anchored.lrt (lrtriangle scaled size, ulcorner FrontPage) withcolor colors[3] ;
- fill anchored.ulft(ultriangle scaled size, lrcorner FrontPage) withcolor colors[4] ;
-
- fill anchored.lrt (lrtriangle scaled size, ulcorner BackPage) withcolor colors[1] ;
- fill anchored.llft(lltriangle scaled size, urcorner BackPage) withcolor colors[3] ;
- fill anchored.ulft(ultriangle scaled size, lrcorner BackPage) withcolor colors[2] ;
- fill anchored.urt (urtriangle scaled size, llcorner BackPage) withcolor colors[4] ;
-
- draw thetextext.llft(
- textext("\bf \documentvariable{title}\hskip-.1em")
- rotated 45 ysized .350height,
- anchor shifted (6*offset+offset)
- ) withcolor white ;
- draw thetextext.llft(
- textext("\bf \documentvariable{subtitle}")
- rotated 45 ysized .275height,
- anchor shifted (5*offset+offset)
- ) withcolor white ;
- draw thetextext.llft(
- textext("\bf \documentvariable{author}")
- rotated 45 ysized .200height,
- anchor shifted (2*offset+offset)
- ) withcolor white ;
- draw thetextext.llft(
- textext("\bf \documentvariable{affiliation}")
- rotated 45 ysized .200height,
- anchor shifted (1*offset+offset)
- ) withcolor white ;
-
- % for the moment
-
- if (what = "back") or (what = "cover") :
-
- draw
- thetextext.top(
- textext("\bf \documentvariable{comment}")
- xsized 4cm,
- lrcorner Page shifted (-3cm,1cm)
- ) withcolor white ;
-
- fi ;
-
- % till here
-
- width := BackPageWidth ;
-
- if (what = "back") or (what = "cover") :
-
- draw thetextext(
- textext("\bf\setups[document:abstract]")
- xsized .65width rotated 45,
- center BackPage
- ) withcolor white ;
-
- fi ;
-
- if what = "cover" :
-
- draw thetextext.bot(
- textext("\bf \documentvariable{title}\hskip-.1em")
- rotated 90 xsized .8SpineWidth,
- .5[ulcorner Spine,urcorner Spine] shifted (0,-1cm)
- ) withcolor white ;
-
- draw thetextext.top(
- textext("\bf \documentvariable{author}")
- rotated 90 xsized .8SpineWidth,
- .5[llcorner Spine,lrcorner Spine] shifted (0,1cm)
- ) withcolor white ;
-
- fi ;
-
- StopCover ;
-
- if what = "front" :
- clip currentpicture to FrontPage ;
- elseif what = "back" :
- clip currentpicture to BackPage ;
- else :
- drawboundary CoverPage ;
- fi ;
-
- enddef ;
-
-\stopMPinclusions
-
-\startsetups document:start
-
- % \startcovermatter[front]
-
- \setupbackgrounds[page][background=]
-
- \doifmodeelse {simple} {
-
- \startMPpage
- DrawCoverPage("front") ;
- \stopMPpage
-
- } {
-
- \startMPpage
- DrawCoverPage("cover") ;
- \stopMPpage
-
- }
-
- \page[dummy]
-
- \setupbackgrounds[page][background=page]
-
- \resetuserpagenumber
-
- % \stopcovermatter
-
-\stopsetups
-
-\startsetups document:stop
-
- \doifmodeelse {simple} {
-
- % \startcovermatter[back]
-
- \page
-
- \setuppagenumbering[page=]
-
- \setupbackgrounds[page][background=]
-
- \page[empty,left]
-
- \setupmakeup[doublesided=no,page=no]
-
- \startMPpage
- DrawCoverPage("back") ;
- \stopMPpage
-
- % \stopcovermatter
-
- } {
-
- % not needed as it's part of the cover page
-
- }
-
-\stopsetups
-
-\stopenvironment
diff --git a/Master/texmf-dist/doc/context/sources/general/fonts/manuals-explaining-environment.tex b/Master/texmf-dist/doc/context/sources/general/fonts/manuals-explaining-environment.tex
deleted file mode 100644
index f896c219bbe..00000000000
--- a/Master/texmf-dist/doc/context/sources/general/fonts/manuals-explaining-environment.tex
+++ /dev/null
@@ -1,325 +0,0 @@
-\startenvironment manuals-explaining-environment
-
-\usemodule[abr-01]
-\usemodule[visual]
-\usemodule[simulate]
-\usemodule[chart]
-\usemodule[nodechart]
-
-% done
-
-\dontcomplain
-
-\definepapersize
- [book]
- [width=18cm,
- height=24cm]
-
-\setuppapersize
- [book]
-
-\startmode[oversized]
-
- \setuppapersize
- [book]
- [oversized]
-
- \setuplayout
- [marking=on]
-
-\stopmode
-
-\setuplayout
- [location=middle,
- topspace=1.5cm,
- bottomspace=2cm,
- backspace=2cm,
- cutspace=2cm,
- header=0cm,
- footer=0cm,
- margindistance=.25cm,
- margin=1.25cm,
- width=middle,
- height=middle]
-
-\setuplayout
- [style=\ss]
-
-\usetypescript
- [dejavu-condensed]
-
-\setupbodyfont
- [ipaex,9pt]
-
-\setupbodyfont
- [dejavu,9pt]
-
-\definetyping
- [narrowtyping]
- [typing]
- [bodyfont=dejavu-condensed]
-
-% This is way too ugly for a manual:
-%
-% \setuptyping
-% [indentnext=no]
-%
-% \setupindenting
-% [medium,yes]
-
-\setupwhitespace
- [big]
-
-\defineoverlay
- [page]
- [\useMPgraphic{page}]
-
-\setupbackgrounds
- [page]
- [background=page]
-
-\setuphead
- [chapter,section,subsection]
- [color=\namedstructureuservariable{chapter}{color}]
-
-\setuphead
- [chapter]
- [style=\bfc]
-
-\setuphead
- [section]
- [style=\bfb]
-
-\setuphead
- [subsection]
- [style=\bf,
- before=\blank,
- after=\blank]
-
-\startsetups document:chapter:inside
- \definecolor[maincolor][1.0(\namedheadparameter{chapter}{color})] % this expands the color
- \definecolor[halfcolor][0.5(maincolor,white)]
-\stopsetups
-
-\setuphead
- [chapter]
- [insidesection=\directsetup{document:chapter:inside}]
-
-\setuppagenumbering
- [alternative=doublesided,
- location=]
-
-\setuplist
- [aligntitle=yes]
-
-\setuplist
- [chapter]
- [pagenumber=no,
- style=bold,
- before={\blank\startcolor[\structurelistuservariable{color}]},
- after={\placelist[section]\stopcolor}]
-
-\setuplist
- [chapter,section]
- [width=3em]
-
-\startuseMPgraphic{page}
-
- StartPage ;
-
- linecap := butt ;
-
- if OnRightPage :
-
- path p ; p := (
- urcorner Page shifted (-2cm,0) --
- urcorner Page --
- urcorner Page shifted (0,-2cm) -- cycle
- ) shifted (-2.5mm,-2.5mm) ;
-
- else :
-
- path p ; p := (
- ulcorner Page shifted (2cm,0) --
- ulcorner Page --
- ulcorner Page shifted (0,-2cm) -- cycle
- ) shifted (2.5mm,-2.5mm) ;
-
- fi ;
-
- fill p
- withpen pencircle scaled 1mm
- withcolor "maincolor" ;
-
- draw thetextext("\bf\userpagenumber",
- if OnRightPage : urcorner p shifted (-5mm,-5mm) else : ulcorner p shifted (5mm,-5mm) fi)
- withcolor white ;
-
- if OnRightPage :
-
- path p ; p := (
- lrcorner Page shifted (-5cm,0) --
- lrcorner Page
- ) shifted (-5mm,10mm)
-
- else :
-
- path p ; p := (
- llcorner Page shifted (5cm,0) --
- llcorner Page
- ) shifted (5mm,10mm) ;
-
- fi ;
-
- draw p
- withpen pencircle scaled 1mm
- withcolor "maincolor" ;
-
- draw if OnRightPage :
- thetextext.lft("\bf\getspecificstructuretitle{chapter}",lrcorner Page shifted (-5mm,5mm))
- else :
- thetextext.rt ("\bf\getspecificstructuretitle{chapter}",llcorner Page shifted ( 5mm,5mm))
- fi withcolor "\namedstructureuservariable{chapter}{color}" ;
-
- StopPage ;
-\stopuseMPgraphic
-
-\definecolor[orange] [r=1,g=.6,b=.1]
-
-\definecolor[middlegray] [s=.75]
-\definecolor[darkgray] [s=.25]
-\definecolor[darkred] [r=.5]
-\definecolor[darkgreen] [g=.5]
-\definecolor[darkblue] [b=.5]
-
-\definecolor[darkyellow] [.5(red,green)]
-\definecolor[darkmagenta][.5(red,blue)]
-\definecolor[darkcyan] [.5(green,blue)]
-
-\definecolor[darkorange] [.5(orange)]
-
-\definecolor[maincolor] [darkgray]
-
-\definecolor [mix-1] [r=1,g=.75,b=.25] \definecolor [darkmix-1][.5(mix-1)]
-\definecolor [mix-2] [r=1,g=.25,b=.75] \definecolor [darkmix-2][.5(mix-2)]
-\definecolor [mix-3] [r=.75,g=1,b=.25] \definecolor [darkmix-3][.5(mix-3)]
-\definecolor [mix-4] [r=.75,g=.25,b=1] \definecolor [darkmix-4][.5(mix-4)]
-\definecolor [mix-5] [r=.25,g=1,b=.75] \definecolor [darkmix-5][.5(mix-5)]
-\definecolor [mix-6] [r=.25,g=.75,b=1] \definecolor [darkmix-6][.5(mix-6)]
-
-% \blackrule[height=1cm,width=10cm,color=mix-1] \blackrule[height=1cm,width=10cm,color=darkmix-1]
-% \blackrule[height=1cm,width=10cm,color=mix-2] \blackrule[height=1cm,width=10cm,color=darkmix-2]
-% \blackrule[height=1cm,width=10cm,color=mix-3] \blackrule[height=1cm,width=10cm,color=darkmix-3]
-% \blackrule[height=1cm,width=10cm,color=mix-4] \blackrule[height=1cm,width=10cm,color=darkmix-4]
-% \blackrule[height=1cm,width=10cm,color=mix-5] \blackrule[height=1cm,width=10cm,color=darkmix-5]
-% \blackrule[height=1cm,width=10cm,color=mix-6] \blackrule[height=1cm,width=10cm,color=darkmix-6]
-
-% modules
-
-\setupsorting
- [logo]
- [style=]
-
-\setupFLOWchart
- [width=6em,
- height=3em,
- offset=-2em, % maybe default : todo: hoffset and voffset
- dx=2em,
- dy=2em]
-
-\setupFLOWlines
- [color=maincolor]
-
-\setupFLOWshapes
- [rulecolor=maincolor]
-
-% tables
-
-\setuptabulate
- [rulethickness=.5mm,
- rulecolor=maincolor]
-
-% special commands
-
-\startuniqueMPgraphic{reference}{color}
- fill
- .5[llcorner OverlayBox,ulcorner OverlayBox] --
- .5[ulcorner OverlayBox,urcorner OverlayBox] --
- .5[urcorner OverlayBox,lrcorner OverlayBox] --
- .5[lrcorner OverlayBox,llcorner OverlayBox] -- cycle
- withcolor \MPvar{color} ;
-\stopuniqueMPgraphic
-
-\startuniqueMPgraphic{reference}{color}
- path p ; p := OverlayBox enlarged -1mm ;
- filldraw
- ulcorner p --
- urcorner p --
- lrcorner p --
- .5[lrcorner p,llcorner p] shifted (0,-1ExHeight) --
- llcorner p -- cycle
- withpen pencircle scaled 1mm
- withcolor \MPvar{color} ;
- setbounds currentpicture to OverlayBox enlarged 1ExHeight ;
-\stopuniqueMPgraphic
-
-\defineoverlay
- [reference]
- [\uniqueMPgraphic{reference}{color=maincolor,}]
-
-\definecolor
- [maincolor]
- [red]
-
-\definemargindata
- [appendixdata]
- %[inner]
- [outer]
- [stack=yes]
-
-\definemarginframed
- [appendixdata]
- [width=3.5em,
- height=\lineheight, % we know what goes in there
- align=middle,
- offset=overlay,
- foregroundcolor=white,
- background=reference]
-
-% todo:
-%
-% \appendixdata[reference=bla]{}
-%
-% whole data
-
-% interaction
-
-\setupinteraction
- [state=start,
- click=no,
- color=,
- contrastcolor=,
- style=]
-
-% whatever
-
-\definestartstop
- [notabene]
- [before=\blank,
- after=\blank,
- style=\em]
-
-\setuphyphenation
- [method=default]
-
-
-\startbuffer[underconstruction]
-\startnotabene
- This document is still under construction. The functionality discussed here
- will stay and more might show up. Of course there are errors, and they're all
- mine. The text is not checked for spelling errors. Feel free to let me know
- what should get added.
-\stopnotabene
-\stopbuffer
-
-\stopenvironment
diff --git a/Master/texmf-dist/doc/context/sources/general/leaflets/leaflet-common.tex b/Master/texmf-dist/doc/context/sources/general/leaflets/leaflet-common.tex
new file mode 100644
index 00000000000..52cc317978e
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/leaflets/leaflet-common.tex
@@ -0,0 +1,80 @@
+\startenvironment leaflet-common
+
+%D Please don't abuse this style for your own purpose as the look and feel
+%D is reserved for our own purpose. Be creative instead.
+
+\usemodule
+ [abbreviations-logos]
+
+\setupbodyfont
+ [plex,12pt]
+
+\setuplayout
+ [page]
+
+\setupalign
+ [verytolerant,stretch]
+
+\startluacode
+ function document.graphic()
+ local min, max, random, round = math.min, math.max, math.random, math.round
+
+ local width = 210
+ local height = 297
+ local r, g, b = 3, 3, 3
+
+ local bitmap = graphics.bitmaps.new(width,height,"rgb",1)
+ local data = bitmap.data
+
+ local graphic = tonumber(documentdata.variable("graphic"))
+
+ if graphic == 1 then
+ r, g, b = 4, 3, 2
+ elseif graphic == 2 then
+ r, g, b = 2, 3, 4
+ end
+
+ for i=1,height do
+ local d = data[i]
+ for j=1,width do
+ local c = random(128,255)
+ -- d[j] = { 0, 0, c }
+ d[j] = { c//r, c//g, c//b }
+ end
+ end
+
+ graphics.bitmaps.tocontext(bitmap,"210bp","297bp")
+ end
+\stopluacode
+
+\definelayer
+ [page]
+ [width=\paperwidth,
+ height=\paperheight]
+
+\setupcolors
+ [textcolor=white]
+
+\setupbackgrounds
+ [page]
+ [background=page]
+
+\setupmakeup
+ [page]
+ [style=\bf,
+ top=,
+ bottom=]
+
+\startsetups document:start
+
+ \setlayerframed
+ [page]
+ [offset=overlay]
+ {\scale
+ [width=\textwidth,
+ height=\textheight]
+ {\ctxlua{document.graphic()}}}
+
+\stopsetups
+
+\stopenvironment
diff --git a/Master/texmf-dist/doc/context/sources/general/leaflets/leaflet-context.tex b/Master/texmf-dist/doc/context/sources/general/leaflets/leaflet-context.tex
new file mode 100644
index 00000000000..7bab43b12a6
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/leaflets/leaflet-context.tex
@@ -0,0 +1,129 @@
+\environment leaflet-common
+
+\startdocument[graphic=1]
+
+\startbuffer[1]
+ There are several ways to deploy \CONTEXT. Most common is to let it render a
+ document, in which case you install it on a system and use an editor to input
+ your document and from a console or by clicking some key trigger a run. The
+ input can be structured using \TEX\ macros but it can also be \XML, or some
+ other format that gets converted to \CONTEXT\ commands before processing.
+\stopbuffer
+
+\startbuffer[2]
+ Instead you can also use \CONTEXT\ as a more hidden application, for instance
+ in a web service or rendering component in a larger application. In that case
+ the end user is not really aware that \TEX\ is being used.
+\stopbuffer
+
+\startbuffer[3]
+ No matter how you use \CONTEXT, you need to install it first. You can for
+ instance use \TEX live or another distribution to pick up \CONTEXT, but you
+ can also install it using the archive (snapshot), in which case you also need
+ to pick up the engine (for instance \LUATEX) and a basic set of fonts. In
+ order to make installation easy we provide a so called standalone
+ distribution that has all you need.
+\stopbuffer
+
+\startbuffer[4]
+
+ The standalone \CONTEXT\ distribution has the following characteristics:
+
+ \startitemize
+ \startitem
+ The installation is self contained. Apart from resources like fonts,
+ the \TEX\ macros, \LUA\ code and \METAPOST\ helpers are provided in
+ one package.
+ \stopitem
+ \startitem
+ There is only one binary involved: \LUAMETATEX. The source code of
+ this program is integral part of the \CONTEXT\ distribution (per end
+ 2019). A user should be able to compile the program if needed. There
+ is no dependency on additional libraries other than those that make
+ up the operating system.
+ \stopitem
+ \startitem
+ The core system is able to typeset documents in an efficient way. The
+ memory footprint is decent and performance acceptable, also on on low
+ power devices and virtual machines. We try not to provide bloatware.
+ \stopitem
+ \startitem
+ The official user interface is stable and the implementation of core
+ components will not change fundamentally. When something can be
+ improved it will be. One can use a snapshot for long term stability.
+ \stopitem
+ \startitem
+ Support is provided by means of a mailing list, a wiki,
+ documentation, meetings, etc. If needed you can consult (or hire)
+ support. There are enough experienced users out there to get you
+ going.
+ \stopitem
+ \stopitemize
+\stopbuffer
+
+\startbuffer[5]
+ The first version of \CONTEXT, now tagged \MKII, has been around since 1995
+ and (still) runs on top of \PDFTEX. The development of its successor \MKIV\
+ started in 2005 as part of the \LUATEX\ development and still carries on. The
+ most recent incarnation is \LMTX, which is \MKIV\ but tuned for \LUAMETATEX,
+ the lean and mean successor of \LUATEX.
+\stopbuffer
+
+% we could use a collector
+
+\startpagemakeup
+ \offinterlineskip
+ \vskip24pt
+ \hbox to \hsize \bgroup
+ \hss
+ \startframed[align=normal,width=.7\textwidth,frame=off]
+ \getbuffer[1]
+ \stopframed
+ \hskip1cm
+ \egroup
+ \vfill
+ \hbox to \hsize \bgroup
+ \hskip1cm
+ \startframed[align=normal,width=.7\textwidth,frame=off]
+ \getbuffer[2]
+ \stopframed
+ \egroup
+ \vfill
+ \hbox to \hsize \bgroup
+ \hss
+ \startframed[align=normal,width=.7\textwidth,frame=off]
+ \getbuffer[3]
+ \stopframed
+ \hskip1cm
+ \egroup
+ \vfill
+ \hbox to \hsize \bgroup
+ \hss
+ \setupitemize[after=]
+ \startframed[align=normal,width=\dimexpr\textwidth-2cm\relax,frame=off]
+ \getbuffer[4]
+ \stopframed
+ \hskip1cm
+ \egroup
+ \vfill
+ \hbox to \hsize \bgroup
+ \hss
+ \startframed[align=normal,width=.7\textwidth,frame=off]
+ \getbuffer[5]
+ \stopframed
+ \hskip1cm
+ \egroup
+ \vfill
+ \vfill
+ \vfill
+ \hbox to \hsize \bgroup
+ \hskip1cm
+ \startframed[align=normal,width=.7\textwidth,frame=off]
+ \bfd \CONTEXT\ \LMTX \enspace \emdash \enspace factsheet
+ \stopframed
+ \hss
+ \egroup
+ \vskip12pt
+\stoppagemakeup
+
+\stopdocument
diff --git a/Master/texmf-dist/doc/context/sources/general/leaflets/leaflet-luametatex.tex b/Master/texmf-dist/doc/context/sources/general/leaflets/leaflet-luametatex.tex
new file mode 100644
index 00000000000..6532a8f9f32
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/leaflets/leaflet-luametatex.tex
@@ -0,0 +1,106 @@
+\environment leaflet-common
+
+\startdocument[graphic=2]
+
+\startbuffer[1]
+ The \LUAMETATEX\ engine is a follow up on \LUATEX. It integrates the \TEX\
+ text rendering engine, the \METAPOST\ graphic engine and the \LUA\ script
+ interpreter. The development is part of the \CONTEXT\ macro package
+ development. This macro package tightly integrates the three subsystems. The
+ \LUAMETATEX\ code is part of the \CONTEXT\ distribution.
+\stopbuffer
+
+\startbuffer[2]
+ The \LUAMETATEX\ engine is lean and mean. There is for instance no backend
+ code present. In \CONTEXT\ this is handled in \LUA. Graphic inclusion is also
+ delegated to \LUA. The \TEX\ frontend is a slightly extended version of the
+ \LUATEX\ one. System depedencies are minimized. Where possible we stay close
+ to the original \TEX\ concept because that is a well documented reference.
+ The binary can also be used as stand alone \LUA\ engine.
+\stopbuffer
+
+\startbuffer[3]
+ The \METAPOST\ library also has access to \LUA, which means that the language
+ can be enhanced and functionality added on demand. There are several graphic
+ libraries provided in \CONTEXT. This graphical language is efficient in
+ runtime and graphical output. In combination with \LUA\ we have a high
+ performance graphical subsystem that can handle a huge amount of data.
+ Additional text (like labels) is typeset at high quality.
+\stopbuffer
+
+\startbuffer[4]
+ The \LUA\ code that comes with \CONTEXT\ contains a lot of helper code which
+ means that one can set up selfcontained workflows without many extra
+ dependencies. Documents can be encoded in \TEX, \LUA, \XML\ or whatever
+ suits. There is support for databases too.
+\stopbuffer
+
+\startbuffer[5]
+ The \CONTEXT\ code base evolved over time. The basic functionality is quite stable.
+ The move from \MKII\ to \MKIV\ to \LMTX\ has been gradual. The efficiency in terms
+ of code and performance has been improved stepwise. Development continues and beta
+ releases occur on a regular basis. The \CONTEXT\ user community is quite willing
+ to experiment with betas that can be installed alongside stable snapshots.
+
+ \blank
+
+ The installation is relatively small (fonts make up much of it) and updating is
+ easy. We operate in the \TEX\ Directory Structure, which is a proven concept.
+\stopbuffer
+
+\startpagemakeup
+ \offinterlineskip
+ \vskip24pt
+ \hbox to \hsize \bgroup
+ \hss
+ \startframed[align=normal,width=.7\textwidth,frame=off]
+ \getbuffer[1]
+ \stopframed
+ \hskip1cm
+ \egroup
+ \vfill
+ \hbox to \hsize \bgroup
+ \hskip1cm
+ \startframed[align=normal,width=.7\textwidth,frame=off]
+ \getbuffer[2]
+ \stopframed
+ \egroup
+ \vfill
+ \hbox to \hsize \bgroup
+ \hss
+ \startframed[align=normal,width=.7\textwidth,frame=off]
+ \getbuffer[3]
+ \stopframed
+ \hskip1cm
+ \egroup
+ \vfill
+ \hbox to \hsize \bgroup
+ \hss
+ \setupitemize[after=]
+ \startframed[align=normal,width=\dimexpr\textwidth-2cm\relax,frame=off]
+ \getbuffer[4]
+ \stopframed
+ \hskip1cm
+ \egroup
+ \vfill
+ \hbox to \hsize \bgroup
+ \hss
+ \startframed[align=normal,width=.7\textwidth,frame=off]
+ \getbuffer[5]
+ \stopframed
+ \hskip1cm
+ \egroup
+ \vfill
+ \vfill
+ \vfill
+ \hbox to \hsize \bgroup
+ \hskip1cm
+ \startframed[align=normal,width=.7\textwidth,frame=off]
+ \bfd \LUAMETATEX \enspace \emdash \enspace factsheet
+ \stopframed
+ \hss
+ \egroup
+ \vskip12pt
+\stoppagemakeup
+
+\stopdocument
diff --git a/Master/texmf-dist/doc/context/sources/general/leaflets/leaflet-mixing.tex b/Master/texmf-dist/doc/context/sources/general/leaflets/leaflet-mixing.tex
new file mode 100644
index 00000000000..9f14525b380
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/leaflets/leaflet-mixing.tex
@@ -0,0 +1,450 @@
+%D Please don't abuse this style for your own purpose as the look and feel
+%D is reserved for our own purpose. Be creative instead.
+
+\setupbodyfont
+ [plex,7pt]
+
+\setuppapersize
+ [A3,landscape]
+
+\setuplayout
+ [width=middle,
+ height=middle,
+ header=0pt,
+ footer=0pt,
+ backspace=5mm,
+ topspace=5mm]
+
+\definelayer
+ [page]
+ [width=\textwidth,
+ height=\textheight]
+
+\setupbackgrounds
+ [page]
+ [background=color,
+ backgroundcolor=middlegray]
+
+\setuptyping
+ [before=,after=]
+
+\usemodule
+ [abbreviations-logos]
+
+\startbuffer[style]
+ \setupbodyfont
+ [plex]
+ \setuplayout
+ [width=middle,
+ height=middle,
+ margin=1cm]
+ \setupcolors
+ [textcolor=white]
+ \usemodule
+ [abbreviations-logos]
+ \setupwhitespace
+ [big]
+ \setuphead
+ [chapter]
+ [style=\bfc]
+\stopbuffer
+
+\startbuffer[intro]
+
+ \starttitle[title={Using \CONTEXT}]
+
+ The \CONTEXT\ macro package is more than just a \TEX\ processor,
+ various input is possible, some we show here. An example of a
+ method not shown here is fetching data from a database. The
+ various input methods can be combined, so depending on what you
+ need you can mix \TEX\ (for typesetting text), \METAPOST\ (for
+ producing graphics) or \LUA\ (as language for manipulating
+ data.
+
+ All these methods are quite efficient and always have access to
+ the full power of the typesetting engine.
+
+ When you use \CONTEXT\ with \LUAMETATEX, you get a reasonable
+ small self contained component that can be used in workflows
+ that need quality rendering. The ecosystem is rather future
+ proof too.
+
+ The \CONTEXT\ macro package has been around for decades and
+ evolved from \MKII, to \MKIV\ and now \LMTX. The development
+ team has always been involved in the development of engines
+ like \PDFTEX, \LUATEX\ and \LUAMETATEX. There is an active
+ mailing list and there are \CONTEXT\ meetings.
+
+ \stoptitle
+
+\stopbuffer
+
+\startbuffer[tex]
+\starttext
+
+ \starttitle[title={Some \TEX}]
+
+ Just an example.
+
+ \starttabulate[|c|c|]
+ \NC first 1 \NC last 1 \NC \NR
+ \NC first 2 \NC last 2 \NC \NR
+ \stoptabulate
+
+ \stoptitle
+
+\stoptext
+\stopbuffer
+
+\startbuffer[xml]
+\startbuffer[demo]
+<?xml version="1.0"?>
+<document>
+ <title>Some XML</title>
+ <p>Just an example.</p>
+ <table>
+ <r> <c>first 1</c> <c>last 1</c> </r>
+ <r> <c>first 2</c> <c>last 2</c> </r>
+ </table>
+</document>
+\stopbuffer
+
+\startxmlsetups xml:basics
+ \xmlsetsetup{#1}{title|p|table}{xml:*}
+\stopxmlsetups
+\startxmlsetups xml:title
+ \title{\xmltext{#1}{.}}
+\stopxmlsetups
+\startxmlsetups xml:p
+ \xmlflush{#1}\par
+\stopxmlsetups
+\startxmlsetups xml:table
+ \starttabulate[|c|c|]
+ \xmlfilter{#1}{/r/command(xml:r)}
+ \stoptabulate
+\stopxmlsetups
+\startxmlsetups xml:r
+ \NC \xmlfilter{#1}{/c/command(xml:c)} \NR
+\stopxmlsetups
+\startxmlsetups xml:c
+ \xmlflush{#1} \NC
+\stopxmlsetups
+
+\xmlregistersetup{xml:basics}
+
+\starttext
+ \xmlprocessbuffer{demo}{demo}{}
+\stoptext
+\stopbuffer
+
+\startbuffer[lua]
+\startluacode
+ local tmp = {
+ { a = "first 1", b = "last 1" },
+ { b = "last 2", a = "first 2" },
+ }
+
+ -- local tmp = table.load("somefile.lua")
+
+ context.starttext()
+
+ context.starttitle { title = "Some Lua" }
+
+ context("Just an example.") context.par()
+
+ context.starttabulate { "|c|c|" }
+ for i=1,#tmp do
+ local t = tmp[i]
+ context.NC()
+ context(t.a) context.NC()
+ context(t.b) context.NC()
+ context.NR()
+ end
+ context.stoptabulate()
+
+ context.stoptitle()
+
+ context.stoptext()
+\stopluacode
+\stopbuffer
+
+\startbuffer[mp]
+\startMPpage
+ draw textext("\bf Some \MetaPost")
+ xsized 4cm
+ rotated(45)
+ withcolor "white" ;
+
+ draw textext("\bs\strut in \ConTeXt")
+ xsized 5cm
+ shifted (0,-40mm)
+ withcolor "white" ;
+
+ draw fullcircle
+ scaled 6cm
+ dashed evenly
+ withcolor "gray" ;
+\stopMPpage
+\stopbuffer
+
+\startbuffer[csv]
+\startluacode
+ local tmp = [[
+ first,second
+ first 1,last 1
+ first 2,last 2
+ ]]
+
+ -- local tmp = io.loaddata("somefile.csv")
+
+ local mycsvsplitter = utilities.parsers.rfc4180splitter()
+ local list, names = mycsvsplitter(tmp,true)
+
+ context.starttext()
+
+ context.starttitle { title = "Some CSV" }
+
+ context("Just an example.") context.par()
+
+ context.starttabulate { "|c|c|" }
+ for i=1,#list do
+ local l = list[i]
+ context.NC()
+ context(l[1]) context.NC()
+ context(l[2]) context.NC()
+ context.NR()
+ end
+ context.stoptabulate()
+
+ context.stoptitle()
+
+ context.stoptext()
+\stopluacode
+\stopbuffer
+
+\startbuffer[json]
+\startluacode
+ require("util-jsn")
+
+ -- local str = io.loaddata("somefile.json")
+
+ local str = [[ {
+ "title": "Some JSON",
+ "text" : "Just an example.",
+ "data" : [
+ { "a" : "first 1", "b" : "last 1" },
+ { "b" : "last 2", "a" : "first 2" }
+ ]
+ } ]]
+
+ local tmp = utilities.json.tolua(str)
+
+ context.starttext()
+
+ context.starttitle { title = tmp.title }
+
+ context(tmp.text) context.par()
+
+ context.starttabulate { "|c|c|" }
+ for i=1,#tmp.data do
+ local d = tmp.data[i]
+ context.NC()
+ context(d.a) context.NC()
+ context(d.b) context.NC()
+ context.NR()
+ end
+ context.stoptabulate()
+
+ context.stoptitle()
+
+ context.stoptext()
+\stopluacode
+\stopbuffer
+
+\startbuffer[mkxi]
+% normally there is already a file:
+
+\startbuffer[demo]
+\starttext
+ \starttitle[title={Some template}]
+
+ Just an example. \blank
+
+ \startlinecorrection
+ \bTABLE
+ <?lua for i=1,20 do ?>
+ \bTR
+ <?lua for j=1,5 do ?>
+ \bTD
+ cell (<?lua inject(i) ?>,<?lua inject(j) ?>)
+ is <?lua inject(variables.text or "unset") ?>
+ \eTD
+ <?lua end ?>
+ \eTR
+ <?lua end ?>
+ \eTABLE
+ \stoplinecorrection
+
+ \stoptitle
+\stoptext
+
+\stopbuffer
+
+\savebuffer[file=demo.mkxi,prefix=no,list=demo]
+
+% the action:
+
+\startluacode
+ document.variables.text = "set"
+\stopluacode
+
+\input{demo.mkxi}
+\stopbuffer
+
+\definemeasure[blobwidth] [\textwidth/4-3mm]
+\definemeasure[blobscale] [\textwidth/4-3mm-4mm]
+\definemeasure[blobheight][\textheight/2-2mm]
+
+\startbuffer[everything]
+
+\setlayerframed
+ [page]
+ [preset=lefttop]
+ [align=normal,
+ offset=2mm,
+ strut=no,
+ frame=off,
+ height=\measure{blobheight},
+ width=\measure{blobwidth},
+ background=color,
+ backgroundcolor=darkgray,
+ foregroundcolor=white]
+ {\doifelsemode{verbose}{\typebuffer[intro]}{\typesetbuffer[style,intro][frame=on,width=\measure{blobscale}]}}
+
+\setlayerframed
+ [page]
+ [preset=lefttop,
+ hoffset=4mm,
+ x=\measure{blobwidth}]
+ [align=normal,
+ offset=2mm,
+ strut=no,
+ frame=off,
+ height=\measure{blobheight},
+ width=\measure{blobwidth},
+ background=color,
+ backgroundcolor=darkred,
+ foregroundcolor=white]
+ {\doifelsemode{verbose}{\typebuffer[tex]}{\typesetbuffer[style,tex][frame=on,width=\measure{blobscale}]}}
+
+\setlayerframed
+ [page]
+ [preset=righttop,
+ hoffset=4mm,
+ x=\measure{blobwidth}]
+ [align=normal,
+ offset=2mm,
+ strut=no,
+ frame=off,
+ height=\measure{blobheight},
+ width=\measure{blobwidth},
+ background=color,
+ backgroundcolor=darkblue,
+ foregroundcolor=white]
+ {\doifelsemode{verbose}{\typebuffer[xml]}{\typesetbuffer[style,xml][frame=on,width=\measure{blobscale}]}}
+
+\setlayerframed
+ [page]
+ [preset=righttop]
+ [align=normal,
+ offset=2mm,
+ strut=no,
+ frame=off,
+ height=\measure{blobheight},
+ width=\measure{blobwidth},
+ background=color,
+ backgroundcolor=darkgreen,
+ foregroundcolor=white]
+ {\doifelsemode{verbose}{\typebuffer[lua]}{\typesetbuffer[style,lua][frame=on,width=\measure{blobscale}]}}
+
+\setlayerframed
+ [page]
+ [preset=lefttop,
+ voffset=4mm,
+ y=\measure{blobheight}]
+ [align=normal,
+ offset=2mm,
+ strut=no,
+ frame=off,
+ height=\measure{blobheight},
+ width=\measure{blobwidth},
+ background=color,
+ backgroundcolor=darkcyan,
+ foregroundcolor=white]
+ {\doifelsemode{verbose}{\typebuffer[mp]}{\typesetbuffer[style,mp][frame=on,width=\measure{blobscale}]}}
+
+\setlayerframed
+ [page]
+ [preset=lefttop,
+ hoffset=4mm,
+ x=\measure{blobwidth},
+ voffset=4mm,
+ y=\measure{blobheight}]
+ [align=normal,
+ offset=2mm,
+ strut=no,
+ frame=off,
+ height=\measure{blobheight},
+ width=\measure{blobwidth},
+ background=color,
+ backgroundcolor=darkmagenta,
+ foregroundcolor=white]
+ {\doifelsemode{verbose}{\typebuffer[csv]}{\typesetbuffer[style,csv][frame=on,width=\measure{blobscale}]}}
+
+\setlayerframed
+ [page]
+ [preset=righttop,
+ hoffset=4mm,
+ x=\measure{blobwidth},
+ voffset=4mm,
+ y=\measure{blobheight}]
+ [align=normal,
+ offset=2mm,
+ strut=no,
+ frame=off,
+ height=\measure{blobheight},
+ width=\measure{blobwidth},
+ background=color,
+ backgroundcolor=darkyellow,
+ foregroundcolor=white]
+ {\doifelsemode{verbose}{\typebuffer[json]}{\typesetbuffer[style,json][frame=on,width=\measure{blobscale}]}}
+
+\setlayerframed
+ [page]
+ [preset=righttop,
+ voffset=4mm,
+ y=\measure{blobheight}]
+ [align=normal,
+ offset=2mm,
+ strut=no,
+ frame=off,
+ height=\measure{blobheight},
+ width=\measure{blobwidth},
+ background=color,
+ backgroundcolor=darkorange,
+ foregroundcolor=white]
+ {\doifelsemode{verbose}{\typebuffer[mkxi]}{\typesetbuffer[style,mkxi][frame=on,width=\measure{blobscale}]}}
+
+\startstandardmakeup
+ \tightlayer[page]
+\stopstandardmakeup
+
+\stopbuffer
+
+\starttext
+
+{\enablemode[verbose] \getbuffer[everything]}
+ \getbuffer[everything]
+
+\stoptext
+
diff --git a/Master/texmf-dist/doc/context/sources/general/magazines/mag-1104-mkiv.tex b/Master/texmf-dist/doc/context/sources/general/magazines/mag-1104-mkiv.tex
new file mode 100644
index 00000000000..ef46b6fe113
--- /dev/null
+++ b/Master/texmf-dist/doc/context/sources/general/magazines/mag-1104-mkiv.tex
@@ -0,0 +1,813 @@
+% 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.
+
+\usemodule[magazine-basic,abr-02]
+
+\usemodule[scite]
+
+\startbuffer[abstract]
+ As part of the \CONTEXT\ \LMTX\ project, we experiment with new ways to
+ interface subsystems and \METAPOST\ makes a good candidate. Here I wrap up some
+ experiments. It's not a manual or a recipe, just food for thought. All you see
+ here might change and|/|or evolve.
+\stopbuffer
+
+\setuplayout
+ [backspace=20mm,
+ topspace=10mm]
+
+\startdocument
+ [title={New interfacing in \METAFUN, a preview},
+ author={Hans Hagen & Alan Braslau},
+ %affiliation=PRAGMA ADE,
+ date=July 2019,
+ number=1104 LMTX]
+
+As we move to \CONTEXT\ \LMTX, some decisions need to be made. For instance, how
+shall we introduce new functionality while not affecting the \MKIV\ code base too
+much with engine related tests, messy and performance sapping. Of course we
+remain downward compatible but the \LUAMETATEX\ engine sometimes permits multiple
+solutions. As this is something new, for a while we can use experimental features
+that may change or later disappear depending on experience. It is not a big deal
+to adapt to these new possibilites and users shouldn't notice, unless of course
+they currently employ (yet undocumented) low|-|level features. Part of the
+solution is to have separate files for \MKIV\ and \LMTX, although that will
+mostly concern low level support modules; even then differences will be subtle
+and should not affect users. I must admit that some of those changes are mostly
+aesthetic and often don't improve performance, although better performance
+sometimes may be the case, in particular concerning \quote {extreme} usage.
+
+But, that said, there are areas where \LMTX\ will offer entirely new
+functionality. One of the areas where we are making interesting developments is
+in \METAFUN, which means \METAPOST. Now, it is not to be said that some of the
+core functionality needed for this will migrate from \LUAMETATEX\ (used by \LMTX)
+to \LUATEX\ (used by \MKIV). But, because (due to external pressure), the later
+engine is now considered stable and its functionality frozen, it is not likely to
+be quickly backported or at least only will happen when this has been throughly
+tested in \CONTEXT|/|\LMTX.
+
+Over the years there have been (small) improvements in the interface but while
+Alan Braslau and I experiment with new graphic abilities, we also are coming up
+with (graphic) interfaces that suit \CONTEXT\ much better. Below, I will show
+some examples. \footnote {These optional argument handlers themselves are
+\emphasize {not} part of \METAPOST\ but implemented in \CONTEXT\ using some
+experimental parsing related extensions to a version of \MPLIB\ used in
+\LUAMETATEX.}
+
+\startbuffer
+\startMPcode{doublefun}
+ draw lmt_grid [
+ nx = 20, ny = 10,
+ dx = 5, dy = 2,
+ tx = 10, ty = 10,
+ ] ysized 5cm withpen pencircle scaled 1mm withcolor "red" ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+What we see here is an key|/|value driven interface that has been one of the
+unique core properties of \CONTEXT\ since it was created. \footnote {Note the use
+of the color string \type {"red"} rather then the \METAPOST\ color variable \type
+{red := (1,0,0)}. This is a small detail but here imports the color definition
+from \CONTEXT, which might be a bit special.} Of course parameters can be
+optional as demonstrated in:
+
+\startbuffer
+\startMPcode{doublefun}
+ draw lmt_grid [
+ nx = 10, ny = 10,
+ dx = 1, dy = 1
+ ] ysized 3cm
+ withpen pencircle scaled 1mm
+ withcolor "darkblue" ;
+
+ draw lmt_grid [
+ nx = 10, ny = 10
+ ] ysized 3cm shifted (4cm,0)
+ withpen pencircle scaled .3mm
+ withcolor "darkgreen" ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+This syntax means that we can also use the already used interface documentation
+system.
+
+We can actually go quite far in what we provide. It's not so much that these
+things were not possible before, but the more concise user interface is something
+new indeed. Let's start with drawing some simple axis:
+
+\startbuffer
+\startMPcode{doublefun}
+ draw lmt_axis [
+ nx = 20, ny = 10,
+ dx = 5, dy = 2,
+ ] ysized 4cm
+ withpen pencircle scaled 1mm
+ withcolor "darkcyan" ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+This \quote {article} is not meant as tutorial but more as a teaser about what is
+possible and hopefully it triggers users in coming up with useful demands. As the
+previous axis example is not that interesting we move on to a more complex one:
+
+\startbuffer
+\startMPcode{doublefun}
+ draw lmt_axis [
+ sx = 5mm, sy = 5mm,
+ nx = 20, ny = 10,
+ dx = 5, dy = 2,
+ tx = 10, ty = 10,
+ ] withpen pencircle scaled 1mm withcolor "darkblue" ;
+
+ draw lmt_connected (
+ for i = 1 step 2 until 20 :
+ -- (i, 1 randomized 8) * 5mm
+ endfor
+ )
+ withpen pencircle scaled 2mm withcolor "darkyellow" ;
+
+ draw lmt_connected (
+ for i = 1 step 2 until 20 :
+ lmt_connection (i, 1 randomized 8) * 5mm
+ endfor
+ )
+ withpen pencircle scaled 2mm withcolor "darkgreen" ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+These examples are made as part of exploring how to best interface with
+\METAPOST, to be used by the upcoming luagraph module, a flexible and high
+performance set of macros aimed at drawing graphs and to visualize data. On the
+one hand, we want to free the user from dealing with details such as scales to
+get the graphics right, but on the other hand it should be possible to
+fine|-|tune when needed.
+
+Again we draw an axis. Using strings as color names, mentioned in the footnote
+earlier, is not new, but already present for a while. It will use the colors
+defined at the \TEX\ end and is more convenient and natural than using the older
+\type {\MPcolor}. The \type {lmt_connected} macro is sort of a gimmick: if you
+look closely you will see that it has to start with a point (coordinate) but that
+one is discarded silently. Again this is something we need to deal with.
+
+% This is obscure, and silly. I'm sure that we can do better. Sure, but so is the
+% HIDE related alternative trrickery. We probably need something getparameterpath.
+
+The next variant uses a list of samples. Watch the use of braces, this is
+something normally not part of \METAPOST\ syntax, and it signals a \LUA|-|like
+list. This is a choice of interfacing. There are subtle and somewhat complicated
+aspects involved here as \METAPOST\ parsing involves primaries, secondaries,
+tertiaries and expressions, symbols, strings, tags and other specialities.
+
+% Why does samples = {} require a second pair of brackets? Wouldn't a
+% comma-separated list be enough in Lua? Because it's \METAPOST\ which has its own
+% ideas about where expressions start and end.
+
+\startbuffer
+\startMPcode{doublefun}
+ draw lmt_axis [
+ sx = 5mm, sy = 5mm,
+ nx = 20, ny = 10,
+ dx = 5, dy = 2,
+ tx = 5, ty = 2,
+ startx = 1, starty = 0,
+
+ connect = true,
+ samples = {
+ {
+ 4, 2, 4, 9, 3, 0, 8, 9, 10, 1,
+ 5, 3, 0, 8, 5, 6, 10, 2, 3, 5
+ }
+ },
+ axiscolor = "darkgreen",
+ textcolor = "darkred",
+ samplecolors = {
+ "darkblue"
+ },
+ ] withpen pencircle scaled 1mm ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+We can have multiple sample lists. But of course dealing with that is really up
+to the underlying code, which itself is not that much related to \METAPOST\ but
+has been delegated to \LUA.
+
+\startbuffer
+\definecolor[tdarkred] [r=.6,a=1,t=.5]
+\definecolor[tdarkgreen][g=.6,a=1,t=.5]
+\definecolor[tdarkblue] [b=.6,a=1,t=.5]
+
+\startMPcode{doublefun}
+ save u ; let u = uniformdeviate ;
+ draw lmt_axis [
+ sx = 5mm, sy = 5mm,
+ nx = 20, ny = 10,
+ dx = 5, dy = 2,
+ tx = 10, ty = 2,
+ samples = {
+ {
+ u10, u10, u10, u10, u10,
+ u10, u10, u10, u10, u10,
+ u10, u10, u10, u10, u10,
+ u10, u10, u10, u10, u10
+ },
+ {
+ u10, u10, u10, u10, u10,
+ u10, u10, u10, u10, u10,
+ u10, u10, u10, u10, u10,
+ u10, u10, u10, u10, u10
+ },
+ {
+ u10, u10, u10, u10, u10,
+ u10, u10, u10, u10, u10,
+ u10, u10, u10, u10, u10,
+ u10, u10, u10, u10, u10
+ }
+ },
+ startx = 1,
+ starty = 0,
+ connect = true,
+ axiscolor = "darkgray",
+ textcolor = "darkyellow",
+ samplecolors = {
+ "tdarkred",
+ "tdarkgreen",
+ "tdarkblue"
+ },
+ ] withpen pencircle scaled 1mm ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+Yet another interesting variant might be this:
+
+\startbuffer
+\startluacode
+ documentdata["lmx-sample-1"] = {
+ {
+ 4, 2, 4, 9, 3, 0, 8, 9, 10, 1,
+ 5, 3, 0, 8, 5, 6, 10, 2, 3, 5
+ }
+ }
+\stopluacode
+\stopbuffer
+
+\typebuffer[option=TEX] \getbuffer
+
+\startbuffer
+\startMPcode{doublefun}
+ draw lmt_axis [
+ sx = 5mm, sy = 5mm,
+ nx = 20, ny = 10,
+ dx = 5, dy = 2,
+ tx = 5, ty = 2,
+ startx = 1, starty = 0,
+
+ samples = "lmx-sample-1",
+ axiscolor = "darkgreen",
+ textcolor = "darkred",
+ samplecolors = { "darkblue" },
+ ] withpen pencircle scaled 1mm ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+% OOPS, doesn't work!
+
+Adding more tricks is not that complex, take, for example:
+
+\startbuffer
+\startMPcode{doublefun}
+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[option=TEX]
+
+yielding
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+but this is experimentation, work in progress, not to be taken as settled.
+
+\blank
+
+A variant on this one is the following:
+
+\startbuffer
+\startMPcode{doublefun}
+draw lmt_function [
+
+ xmin = 0, xmax = 10, xstep = .05,
+ ymin = -2, ymax = 2,
+
+ xticks = "bottom", xsmall = 80, xlarge = 20,
+ yticks = "left", ysmall = 40, ylarge = 4,
+
+ code = "1.5 * math.cosd(240 * math.sqrt(x))",
+
+ xlabels = "yes",
+ ylabels = "yes",
+
+ ycaption = "\strut\tfd \rotate[rotation=90]{vertical}",
+ xcaption = "\strut\tfd horizontal",
+
+ pointsymbol = "dot", pointsize = 4, pointcolor = "orange",
+
+ sx = 2mm, sy = 4mm, linewidth = .025mm, offset = .1mm,
+]
+ xsized 8cm
+;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+A valid question is if this should be combined with the previous but having
+distinctive variants is less likely to complicate the settings, as these can
+depend on the application:
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+A more complex usage (still under exploration) is demonstrated next:
+
+\startbuffer
+\definecolor[MyColorR][r=.5,t=.5,a=1]
+\definecolor[MyColorG][g=.5,t=.5,a=1]
+\definecolor[MyColorB][b=.5,t=.5,a=1]
+\definecolor[MyColorY][r=.5,g=.5,t=.5,a=1]
+
+\startMPcode{doublefun}
+draw lmt_function [
+ sx = 1mm, sy = 4mm, linewidth = .025mm, offset = .1mm,
+
+ xmin = 0, xmax = 20, xstep = .1,
+ ymin = -2, ymax = 2,
+
+ xticks = "bottom", xsmall = 80, xlarge = 20, xlabels = "nolimits",
+ yticks = "left", ysmall = 40, ylarge = 4, ylabels = "yes",
+
+ code = "1.5 * math.sind (50 * x - 150)",
+
+ frame = "sticks", % "ticks"
+
+ functions = {
+ [
+ xmin = 1.0,
+ xmax = 7.0,
+ close = true,
+ fillcolor = "MyColorR"
+ ],
+ [
+ xmin = 7.0,
+ xmax = 12.0,
+ close = true,
+ fillcolor = "MyColorG"
+ ],
+ [
+ xmin = 12.0,
+ xmax = 19.0,
+ close = true,
+ fillcolor = "MyColorB"
+ ],
+ [
+ drawcolor = "darkyellow",
+ drawsize = 2,
+ ],
+ [
+ xmin = 4,
+ xmax = 17,
+ xstep = .25,
+ drawcolor = "darkmagenta",
+ shape = "steps",
+ code = "0.5 * math.random(-2,2)",
+ ],
+ [
+ xmin = 5.0,
+ xmax = 15.0,
+ close = true,
+ fillcolor = "MyColorY"
+ code = "1.75 * math.cosd (50 * x - 150)",
+ ]
+ },
+ ycaption = "\rotate[rotation=90]{\tfd\strut a mix of drawings}",
+ xcaption = "\framed[foregroundstyle=\tfd]{a mixture of $\sin(x), \cos(x), \sqrt{x}$ etc.}",
+]
+ xsized 8cm
+;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+Of course calling the same command multiple times with different code snippets
+will also work.
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+The previous examples used new code but how about improving existing features?
+Let's look at outlines.
+
+\startbuffer
+\startMPcode{doublefun}
+ save h ; h = 12mm ;
+
+ draw lmt_outline [
+ text = "hello"
+ kind = "draw",
+ drawcolor = "darkblue",
+ ] ysized h ;
+
+ draw lmt_outline [
+ text = "hello",
+ kind = "fill",
+ fillcolor = "darkred",
+ ] ysized h shifted (3.75h,0) ;
+
+ draw lmt_outline [
+ test = "hello",
+ kind = "both",
+ fillcolor = "darkred",
+ ] ysized h shifted (7.5h,0mm) ;
+
+ draw lmt_outline [
+ text = "hello",
+ kind = "both",
+ fillcolor = "darkred",
+ drawcolor = "darkblue",
+ rulethickness = 1/5,
+ ] ysized h shifted (0,-1.25h) ;
+
+ draw lmt_outline [
+ text = "hello",
+ kind = "reverse",
+ fillcolor = "darkred",
+ drawcolor = "darkblue",
+ rulethickness = 1/2,
+ ] ysized h shifted (3.75h,-1.25h) ;
+
+ draw lmt_outline [
+ text = "hello",
+ kind = "fillup",
+ fillcolor = "darkgreen",
+ rulethickness = 0,
+ ] ysized h shifted (7.5h,-1.25h) ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+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
+\startMPcode{doublefun}
+ draw lmt_outline [
+ text = "\obeydiscretionaries\samplefile{tufte}",
+ align = "normal",
+ kind = "draw",
+ drawcolor = "darkblue",
+ ] xsized TextWidth ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+\startbuffer
+\startMPcode{doublefun}
+ draw lmt_outline [
+ text = "\obeydiscretionaries\samplefile{ward}",
+ align = "normal,tolerant",
+ width = 10cm,
+ kind = "draw",
+ drawcolor = "darkblue",
+ ] xsized TextWidth ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+\startbuffer
+\startMPcode{doublefun}
+ draw lmt_outline [
+ text = "\obeydiscretionaries\samplefile{sapolsky}",
+ align = "normal,tolerant",
+ style = "bold",
+ width = 10cm,
+ kind = "draw",
+ rulethickness = 1/5,
+ drawcolor = "darkred",
+ ] xsized TextWidth ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+Another \METAFUN\ text related mechanism deals with following a specific path.
+That interface has evolved over time, also due to more advanced possibilities in
+\MKIV. But, it's again time for a upgrade, for example:
+
+\startbuffer
+\startMPcode{doublefun}
+ draw lmt_followtext [
+ text = "How well does it work {\bf 1}! ",
+ path = (fullcircle scaled 4cm),
+ trace = true,
+ spread = true,
+ ] ysized 5cm ;
+
+ draw lmt_followtext [
+ text = "How well does it work {\bf 2}! ",
+ path = fullcircle scaled 4cm,
+ trace = true,
+ spread = false,
+ reverse = true,
+ ] ysized 5cm shifted (0,-6cm) ;
+
+ draw lmt_followtext [
+ text = "How well does it work {\bf 3}! ",
+ trace = true,
+ autoscaleup = "yes"
+ ] ysized 5cm shifted (6cm,0) ;
+
+ draw lmt_followtext [
+ text = "How well does it work {\bf 4}! ",
+ path = fullcircle scaled 2cm,
+ trace = true,
+ autoscaleup = "max"
+ ] ysized 5cm shifted (6cm,-6cm) ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+Although \METAPOST\ can draw arrows a bit more code is involved than one would
+have expected. As a consequence, influencing the way an arrowhead is drawn as
+currently using variables is somewhat cumbersome. Here is an alternative:
+
+\startbuffer
+\startMPcode{doublefun}
+ draw lmt_arrow [
+ path = fullcircle
+ scaled 3cm
+ shifted (0,0cm),
+ ] withcolor "darkred" ;
+
+ draw lmt_arrow [
+ location = "both"
+ path = fullcircle
+ scaled 3cm
+ rotated 90
+ shifted (0,-3.5cm),
+ ] withcolor "darkgreen" ;
+
+ draw lmt_arrow [
+ kind = "draw",
+ location = "middle",
+ alternative = "curved",
+ path = fullcircle
+ scaled 3cm
+ shifted (3.5cm,0cm),
+ ] withcolor "darkblue" ;
+
+ for i = 0 step 5 until 100 :
+ draw lmt_arrow [
+ alternative = "dimpled",
+ location = "percentage",
+ percentage = i,
+ dimple = (1/5 + i/200),
+ headonly = (i = 0),
+ path = fullcircle
+ scaled 3cm
+ shifted (3.5cm,-3.5cm),
+ ] withcolor "darkyellow" ;
+ endfor ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+These new interfaces for outlines, following text and arrows certainly will make
+it in some form to be permanent \METAFUN\ extensions. Some will also be used in
+macros at the \TEX\ end, for instance, when you load the dummy library:
+
+\startbuffer
+\useMPlibrary[dum]
+\stopbuffer
+
+\typebuffer[option=TEX] \getbuffer
+
+You can do this:
+
+\startbuffer
+\startcombination
+ {\externalfigure[crap-001]} {one}
+ {\externalfigure[crap-004][alternative=triangle]} {two}
+\stopcombination
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+and get:
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+This placeholder now also can be accessed directly:
+
+\startbuffer
+\useMPmacro
+ [minifun]
+ [placeholder]
+ [width=10cm,
+ height=3cm,
+ reduction=.2,
+ alternative=triangle,
+ color=orange]
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+The \type {\useMPmacro} is an entirely new interface to \METAFUN\ code. Although
+it is still experimental, we show an example. Of course, as needed, you can throw
+in some \LUA\ magic.
+
+\startbuffer
+\startMPcalculation
+ presetparameters "demo" [
+ n = 5,
+ s = 1cm,
+ ] ;
+
+ def lmt_demo = applyparameters "demo" "lmt_do_demo" enddef ;
+
+ vardef lmt_do_demo =
+ for i=1 upto getparameter "demo" "n" :
+ draw fullcircle scaled (i*getparameter "demo" "s");
+ endfor ;
+ enddef ;
+\stopMPcalculation
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+The calculation wrapper makes this code be processed immediately, which is needed
+because we don't use a module.
+
+\getbuffer
+
+A the \TEX\ end we do this:
+
+\startbuffer
+\defineMPparameterset[demo][n=integer,s=dimension]
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\getbuffer
+
+We can now let the macro do its work:
+
+\startbuffer
+\startcombination[nx=4,location=middle]
+ {\useMPmacro[demo][n=8,s=2mm]} {Demo 1}
+ {\useMPmacro[demo][n=4,s=4mm]} {Demo 2}
+ {\useMPmacro[demo][n=4,s=5\exheight]} {Demo 3}
+ {\useMPmacro[demo]} {Demo 4}
+\stopcombination
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+You can also set the parameters separately. There is one catch: there is no
+grouping so in this case you need to reset the parameters afterwards.
+
+\starttyping
+\presetMPparameters[demo][n=8] \useMPmacro[demo]\blank
+\presetMPparameters[demo][n=4] \useMPmacro[demo]\blank
+\resetMPparameters [demo] \useMPmacro[demo]\blank
+\stoptyping
+
+These examples demonstrate that we can make \METAPOST\ a bit friendlier for users
+who are not that fluent with the language. It remains to be seen to what extent
+additional modules will be written, but the possibilities are there.
+
+\stopdocument
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/fonts/fonts/fonts-appendix.tex b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-appendix.tex
index 2eab26a9371..2eab26a9371 100644
--- a/Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-appendix.tex
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-appendix.tex
diff --git a/Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-demo-rule.lua b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-demo-rule.lua
index 667d1e43c90..667d1e43c90 100644
--- a/Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-demo-rule.lua
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-demo-rule.lua
diff --git a/Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-environment.tex b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-environment.tex
index c884d97e5d3..c884d97e5d3 100644
--- a/Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-environment.tex
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-environment.tex
diff --git a/Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-extensions.tex b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-extensions.tex
index afe6fd82386..afe6fd82386 100644
--- a/Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-extensions.tex
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-extensions.tex
diff --git a/Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-features.tex b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-features.tex
index bf9f39385df..bf9f39385df 100644
--- a/Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-features.tex
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-features.tex
diff --git a/Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-formats.tex b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-formats.tex
index 9ad6bc9bda0..9ad6bc9bda0 100644
--- a/Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-formats.tex
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-formats.tex
diff --git a/Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-hooks.tex b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-hooks.tex
index 7ee5dc198b8..7ee5dc198b8 100644
--- a/Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-hooks.tex
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-hooks.tex
diff --git a/Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-introduction.tex b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-introduction.tex
index 0ca91ee9fee..0ca91ee9fee 100644
--- a/Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-introduction.tex
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-introduction.tex
diff --git a/Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-lookups.tex b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-lookups.tex
index e9448b88456..e9448b88456 100644
--- a/Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-lookups.tex
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-lookups.tex
diff --git a/Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-math.tex b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-math.tex
index 76620493755..76620493755 100644
--- a/Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-math.tex
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-math.tex
diff --git a/Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-methods.tex b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-methods.tex
index eac86d69487..eac86d69487 100644
--- a/Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-methods.tex
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-methods.tex
diff --git a/Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-mkiv.tex b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-mkiv.tex
index fa53492f084..fa53492f084 100644
--- a/Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-mkiv.tex
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-mkiv.tex
diff --git a/Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-modes.tex b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-modes.tex
index 95cb957328f..95cb957328f 100644
--- a/Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-modes.tex
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-modes.tex
diff --git a/Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-scripts.tex b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-scripts.tex
index aed4f0a5c9d..aed4f0a5c9d 100644
--- a/Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-scripts.tex
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-scripts.tex
diff --git a/Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-tricks.tex b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-tricks.tex
index 65b210e2c48..65b210e2c48 100644
--- a/Master/texmf-dist/doc/context/sources/general/fonts/fonts/fonts-tricks.tex
+++ b/Master/texmf-dist/doc/context/sources/general/manuals/fonts/fonts-tricks.tex
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