2022-07-24 12:18:00

6 files changed, 1043 insertions, 324 deletions

diff --git a/doc/context/documents/general/manuals/luametatex.pdf b/doc/context/documents/general/manuals/luametatex.pdf
index 224d64fd1..ab8f8b347 100644
--- a/doc/context/documents/general/manuals/luametatex.pdf
+++ b/doc/context/documents/general/manuals/luametatex.pdf
diff --git a/doc/context/sources/general/manuals/luametatex/luametatex-differences.tex b/doc/context/sources/general/manuals/luametatex/luametatex-differences.tex
index 8dcd2f2d1..403f1a029 100644
--- a/doc/context/sources/general/manuals/luametatex/luametatex-differences.tex
+++ b/doc/context/sources/general/manuals/luametatex/luametatex-differences.tex
@@ -281,17 +281,21 @@ if luatex and luametatex then
 
     local match = string.match
 
-    local index = structures.registers.collected and structures.registers.collected.luatexindex
     local found = { }
 
-    if index then
-        local data = index.entries
-        for i=1,#data do
-            found[match(data[i].list[1][1],"\\tex%s*{(.-)}") or ""] = true
+    local function collect(index)
+        if index then
+            local data = index.entries
+            for i=1,#data do
+                found[match(data[i].list[1][1],"\\tex%s*{(.-)}") or ""] = true
+            end
+         -- inspect(found)
         end
-     -- inspect(found)
     end
 
+    collect(structures.registers.collected and structures.registers.collected.texindex)
+    collect(structures.registers.collected and structures.registers.collected.luatexindex)
+
     luatex     = table.tohash(luatex)
     luametatex = table.tohash(luametatex)
 
@@ -316,8 +320,9 @@ if luatex and luametatex then
 
  -- context.page()
 
-    context("The following primitives are available in \\LUAMETATEX\\ only. ")
-    context("At some point in time some might be added to \\LUATEX.")
+    context("The following primitives are available in \\LUAMETATEX\\ only. In the meantime ")
+    context("the \\LUAMETATEX\\ code base is so different from \\LUATEX\\ that backporting ")
+    context("is no longer reasonable.")
 
     context.blank()
     context.startcolumns { n = 2 }
diff --git a/doc/context/sources/general/manuals/luametatex/luametatex-enhancements.tex b/doc/context/sources/general/manuals/luametatex/luametatex-enhancements.tex
index bdac9047c..e82a41118 100644
--- a/doc/context/sources/general/manuals/luametatex/luametatex-enhancements.tex
+++ b/doc/context/sources/general/manuals/luametatex/luametatex-enhancements.tex
@@ -876,6 +876,14 @@ expand the passed general text. The \type {g} and \type {x} variants are global.
 
 \stopsubsection
 
+\startsubsection[title={\prm {etoks} and \prm {xtoks}}]
+
+A mix between the previously discussed append and prepend primitives and simple
+toks register assignments are these two. They act like \prm {toks} but expand
+their content first. The \type {x} variant does a global assignment.
+
+\stopsubsection
+
 \startsubsection[title={\prm {csstring}, \prm {begincsname} and \prm {lastnamedcs}}]
 
 These are somewhat special. The \prm {csstring} primitive is like
@@ -1015,19 +1023,84 @@ but faster (only measurable with millions of calls) and probably more convenient
 
 \stopsubsection
 
-\startsubsection[title={\prm {defcsname}, \prm {edefcsname}, \prm {edefcsname} and \prm {xdefcsname}}]
+\startsubsection[title={\prm {defcsname}, \prm {edefcsname}, \prm {gdefcsname} and \prm {xdefcsname}}]
 
 Although we can implement these primitives easily using macros it makes sense,
 given the popularity of \prm {csname} to have these as primitives. It also saves
 some \prm {expandafter} usage and it looks a bit better in the source.
 
 \starttyping
-\def\gdefcsname foo\endcsname{oof}
+\gdefcsname foo\endcsname{oof}
+\stoptyping
+
+\stopsubsection
+
+\startsubsection[title={\prm {letcsname} and \prm {gletcsname}}]
+
+These can also be implemented using macros but again they are natively provided
+by the engine for the same reasons: less code and less tracing clutter.
+
+\starttyping
+\gletcsname foo\endcsname \relax
+\stoptyping
+
+\stopsubsection
+
+\startsubsection[title={\prm {futuredef} and \prm {futurecsname}}]
+
+This is just the definition variant of \prm {futurelet} and a simple example
+shows the difference:
+
+\startbuffer
+\def\whatever{[\next:\meaning\next]}
+\futurelet\next\whatever A
+\futuredef\next\whatever B
+\stopbuffer
+
+\typebuffer
+
+\getbuffer
+
+The next one was more an experiment that then stayed around, just to see what
+surprising abuse of this primitive will happen:
+
+\startbuffer
+\def\whateveryes{[YES]}
+\def\whatevernop{[NOP]}
+\let\whatever\undefined
+\futurecsname\whatevernop whatever\endcsname
+\futurecsname\whatevernop whateveryes\endcsname
+\stopbuffer
+
+\typebuffer
+
+When the assembles control sequence is undefined the given one will be expanded,
+a weird one, right? I will probably apply it some day in cases where I want less
+tracing and a more direct expansion of an assembled name.
+
+\getbuffer
+
+Here is a usage example:
+
+\starttyping
+\xdef\Whatever{\futurecsname\whatevernop    whatever\endcsname}
+\xdef\Whatever{\futurecsname\whateveryes whateveryes\endcsname}
+\xdef\Whatever{\ifcsname    whatever\endcsname\lastnamedcs\else\whatevernop\fi}
+\xdef\Whatever{\ifcsname whateveryes\endcsname\lastnamedcs\else\whatevernop\fi}
+\xdef\Whatever{\ifcsname    whatever\endcsname\csname    whatever\endcsname\else\whatevernop\fi}
+\xdef\Whatever{\ifcsname whateveryes\endcsname\csname whateveryes\endcsname\else\whatevernop\fi}
 \stoptyping
 
+The timings for one million times defining each of these definitions are 0.277,
+0.313, 0.310, 0.359, 0.352 and 0.573 seconds (on a 2018 Dell 7250 Precision
+laptop with mobile E3-1505M v6 processor), so there is a little gain here, but of
+course in practice no one will notice that because not that many such macros are
+defined (or used).
+
 \stopsubsection
 
-\startsubsection[title={\prm {expanded}}]
+\startsubsection[title={\prm {expanded}, \prm {localcontrol}, \prm
+{localcontrolled}, \prm {beginlocalcontrol} and \prm {endlocalcontrol}}]
 
 \topicindex {expansion}
 
@@ -1036,113 +1109,115 @@ 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}. The \tex {immediateassignment} and \tex {immediateassigned} commands are
 gone because we have the more powerful local control commands. They are a tad
-slower but this mechanism isn't used that much anyway. Inside an \prm {edef} you
-can use the \type {\immediate} prefix anyway, so if you really want these
-primitives back you can say:
+slower but this mechanism isn't used that much anyway.
 
 \starttyping
-\let\immediateassignment\immediate
-\let\immediateassigned  \localcontrolled
+\let\immediateassigned\localcontrolled % sort of what \LUATEX provides
 \stoptyping
 
+Say that we define:
+
+\startbuffer
+\edef\TestA
+  {\advance\scratchcounter\plusone}
+\edef\TestB
+  {\localcontrol\TestA
+   \the\scratchcounter}
+\edef\TestC
+  {\localcontrolled{\advance\scratchcounter\plusone}%
+   \the\scratchcounter}
+\edef\TestD
+  {\beginlocalcontrol\advance\scratchcounter\plusone\endlocalcontrol
+   \the\scratchcounter}
+\stopbuffer
+
+\typebuffer \getbuffer
+
+With this example:
+
+\startbuffer
+\scratchcounter 10 \meaningasis\TestA
+\scratchcounter 20 \meaningasis\TestB
+\scratchcounter 30 \meaningasis\TestC
+\scratchcounter 40 \meaningasis\TestD
+\stopbuffer
+
+\typebuffer
+
+We get this:
+
+\startlines
+\tttf \getbuffer
+\stoplines
+
+These local control primitives are a bit tricky and error message can be
+confusing. Future versions might have a bit better recovery but in practice it
+works as expected.
+
 \stopsubsection
 
-% \startsubsection[title={\prm {expanded}, \prm {immediateassignment} and \prm {immediateassigned}}]
-%
-% \topicindex {expansion}
-%
-% The \prm {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={\prm {semiprotected}, \prm {semiexpanded}, \prm {expand} and
+\prm {semiexpand}}]
+
+These primitives can best be explained with a few examples. The semi boils down to
+a bit more controlled usage of \prm {protected} macros.
+
+\startbuffer
+               \def\Test {test}
+               \def\TestA{\Test}
+\protected     \def\TestB{\Test}
+\semiprotected \def\TestC{\Test}
+              \edef\TestD{\Test}
+              \edef\TestE{\TestA}
+              \edef\TestF{\TestB}
+              \edef\TestG{\TestC}
+              \edef\TestH{\normalexpanded{\TestB\TestC}} % ctx has \expanded defined
+              \edef\TestI{\semiexpanded{\TestB\TestC}}
+              \edef\TestJ{\expand\TestB\expand\TestC}
+              \edef\TestK{\semiexpand\TestB\semiexpand\TestC}
+\stopbuffer
+
+\typebuffer \getbuffer
+
+The effective meanings are given next (we use \prm {meaningasis} for this):
+
+\startlines \tttf
+\meaningasis\Test
+\meaningasis\TestA
+\meaningasis\TestB
+\meaningasis\TestC
+\meaningasis\TestD
+\meaningasis\TestE
+\meaningasis\TestF
+\meaningasis\TestG
+\meaningasis\TestH
+\meaningasis\TestI
+\meaningasis\TestJ
+\meaningasis\TestK
+\stoplines
+
+\stopsubsection
+
+\startsubsection[title={\prm {norelax}}]
+
+There are a few cases where the \TEX\ scanned skips over spaces and \prm {relax} as
+well as quits on a \prm {relax} in which case it gets pushed back. An example is
+given below:
+
+\startbuffer
+\edef\TestA{\ifnum1=1\relax   Y\else N\fi} \meaningasis\TestA
+\edef\TestB{\ifnum1=1\norelax Y\else N\fi} \meaningasis\TestB
+\stopbuffer
+
+\typebuffer
+
+The second line also contains a sentinel but this time we use \prm {norelax}
+which will not be pushed back. So, this feature is just a trick to get rid of (in
+itself reasonable) side effects.
+
+\startlines\getbuffer \stoplines
+
+\stopsubsection
 
 \startsubsection[title={\prm {ignorepars}}]
 
@@ -1369,6 +1444,42 @@ one might evolve).
 
 \stopsubsection
 
+\startsubsection[title={\prm {ifhastok}, \prm {ifhastoks}, \prm {ifhasxtoks} and \prm {ifhaschar}}]
+
+\topicindex {conditions+tokens}
+\topicindex {tokens}
+
+The first three test primitives run over a token list in order to encounter a
+single token or a sequence. The \type {x} variants applies expansion.
+
+\startbuffer
+\def\ab {ab}
+\def\abc{abc}
+\ifhastok  1    {12} Y\else N\fi
+\ifhastoks {ab} {abc}Y\else N\fi
+\ifhastoks {ab} {\abc}Y\else N\fi
+\ifhastoks {\ab}{\abc}Y\else N\fi
+\ifhasxtoks{ab} {\abc}Y\else N\fi
+\ifhastok  3    {12} Y\else N\fi
+\ifhastoks {de} {abc}Y\else N\fi
+\stopbuffer
+
+\typebuffer \startpacked[blank] {\tt\nospacing\getbuffer} \stoppacked
+
+The \prm {ifhaschar} primitive differs from \prm {ifhastok} in that it handles
+nested balanced \quote {lists}, as in:
+
+\startbuffer
+\ifhastok  a  {abc}Y\else N\fi
+\ifhaschar a  {abc}Y\else N\fi
+\ifhastok  a{{a}bc}Y\else N\fi
+\ifhaschar a{{a}bc}Y\else N\fi
+\stopbuffer
+
+\typebuffer \startpacked[blank] {\tt\nospacing\getbuffer} \stoppacked
+
+\stopsubsection
+
 \startsubsection[title={\prm {ifarguments}, \prm {ifparameters} and \prm {ifparameter}}]
 
 These are part of the extended macro argument parsing features. The \type
@@ -1645,6 +1756,113 @@ a split of the given size but result has the natural dimensions then.
 
 \stopsubsection
 
+\startsubsection[title={\prm {boxxoffset}, \prm {boxyoffset}, \prm {boxxmove}, \prm {boxymove},
+\prm{boxorientation} and \prm{boxgeometry}}]
+
+This repertoire of primitives can be used to do relative positioning. The offsets
+are virtual while the moves adapt the dimensions. The orientation bitset can be
+used to rotate the box over 90, 180 and 270 degrees. It also influences the
+corner, midpoint or baseline.
+
+{\em There is information in the \CONTEXT\ low level manuals and in due time I
+will add a few examples here. This feature needs support in the backend when used
+(as in \CONTEXT) so it might influence performance.}
+
+\stopsubsection
+
+\startsubsection[title={\prm {boxtotal}}]
+
+The \prm {boxtotal} primitive returns the sum of the height and depth and is less
+useful as setter: it just sets the height and depth to half of the given value.
+
+\stopsubsection
+
+\startsubsection[title={\prm {boxshift}}]
+
+In traditional \TEX\ a box has height, depth, width and a shift where the later
+relates to \prm {raise}, \prm {lower}, \prm {moveleft} and \prm {moveright}. This
+primitive can be used to query and set this property.
+
+\startbuffer
+\setbox0\hbox{test test test}
+\setbox2\hbox{test test test} \boxshift2 -10pt
+\ruledhbox{x \raise10pt\box0\ x}
+\ruledhbox{x           \box2\ x}
+\stopbuffer
+
+\typebuffer
+
+\stopsubsection
+
+\startsubsection[title={\prm {boxanchor}, \prm {boxanchors}, \prm {boxsource} and \prm {boxtarget}}]
+
+{\em These are experimental.}
+
+\stopsubsection
+
+\startsubsection[title={\prm {boxfreeze}, \prm {boxadapt} and \prm {boxrepack}}]
+
+This operation will freeze the glue in the given box, something that normally is
+delayed and delegated to the backend.
+
+\startbuffer
+\setbox    0 \hbox to 5cm {\hss test}
+\setbox    2 \hbox to 5cm {\hss test}
+\boxfreeze 2 0
+\ruledhbox{\unhbox   0}
+\ruledhbox{\unhbox   2}
+\stopbuffer
+
+\typebuffer
+
+The second parameter to \prm {boxfreeze} determines recursion. Here we just
+freeze the outer level:
+
+\getbuffer
+
+Repacking will take the content of an existing box and add or subtract from it:
+
+\startbuffer
+\setbox 0 \hbox        {test test test}
+\setbox 2 \hbox {\red   test test test} \boxrepack0 +.2em
+\setbox 4 \hbox {\green test test test} \boxrepack0 -.2em
+\ruledhbox{\box0} \vskip-\lineheight
+\ruledhbox{\box0} \vskip-\lineheight
+\ruledhbox{\box0}
+\stopbuffer
+
+\typebuffer
+
+\getbuffer
+
+We can use this primitive to check the natural dimensions:
+
+\startbuffer
+\setbox 0 \hbox spread 10pt {test test test}
+\ruledhbox{\box0} (\the\boxrepack0,\the\wd0)
+\stopbuffer
+
+\typebuffer
+
+\getbuffer
+
+Adapting will recalculate the dimensions with a scale factor for the glue:
+
+\startbuffer
+\setbox 0 \hbox       {test test test}
+\setbox 2 \hbox {\red  test test test} \boxadapt 0   200
+\setbox 4 \hbox {\blue test test test} \boxadapt 0  -200
+\ruledhbox{\box0} \vskip-\lineheight
+\ruledhbox{\box0} \vskip-\lineheight
+\ruledhbox{\box0}
+\stopbuffer
+
+\typebuffer
+
+\getbuffer
+
+\stopsubsection
+
 \startsubsection[title={Images and reused box objects},reference=sec:imagesandforms]
 
 In original \TEX\ image support is dealt with via specials. It's not a native
@@ -1731,6 +1949,14 @@ mode.
 
 \stopsubsection
 
+\startsubsection[title={\prm {unhpack}, \prm {unvpack}}]
+
+These two are somewhat experimental. They ignore the accumulated pre- and
+postmigrated material bound to a box. I needed it for some experiment so the
+functionality might change when I really need it.
+
+\stopsubsection
+
 \startsubsection[title={\prm {gleaders}},reference=sec:gleaders]
 
 \topicindex {leaders}
@@ -1852,6 +2078,15 @@ they will be stable.
 
 \stopsubsection
 
+\startsubsection[title={\prm {lastboundary} and \prm {unboundary}}]
+
+There are \prm {lastpenalty}, \prm {lastskip}, \prm {lastkern} and \prm {lastbox}
+primitives and \LUAMETATEX\ also offers \prm {lastboundary} which gives the value
+assigned to a user boundary node. This means that we also have a \prm
+{unboundary} to complement the other \tex {un...} primitives.
+
+\stopsubsection
+
 \stopsection
 
 \startsection[title={Files}]
@@ -2516,7 +2751,8 @@ experimental so what gets displayed might change.
 
 \stopsection
 
-\startsection[title={Constants with \prm{integerdef} and \prm {dimensiondef}}]
+\startsection[title={Constants with \prm{integerdef}, \prm {dimensiondef},
+\prm {gluespecdef} and \prm {mugluespecdef}}]
 
 It is rather common to store constant values in a register or character
 definition.
@@ -2530,8 +2766,10 @@ definition.
 But in \LUAMETATEX\ we also can do this:
 
 \starttyping
-\integerdef  \MyConstantC 456
-\dimensiondef\MyConstantD 456pt
+\integerdef    \MyConstantI 456
+\dimensiondef  \MyConstantD 456pt
+\gluespecdef   \MyConstantG 987pt minus 654pt plus 321pt
+\mugluespecdef \MyConstantG 3mu plus 2mu minus 1mu
 \stoptyping
 
 These two are stored as efficient as a register but don't occupy a register slot.
@@ -2544,14 +2782,52 @@ in a previous section.
 
 \stopsection
 
-\startsection[title={Serialization with \prm {todimension}, \prm {toscaled} and \prm {tointeger}}]
+\startsection[title={Getting internal indices with \prm {indexofcharacter} and \prm {indexofregister}}]
+
+When you have defined a register with one of the \tex {...def} primitives but for
+some reasons needs to know the register index you can query that:
+
+\startbuffer
+\the\indexofregister \scratchcounterone,
+\the\indexofregister \scratchcountertwo,
+\the\indexofregister \scratchwidth,
+\the\indexofregister \scratchheight,
+\the\indexofregister \scratchdepth,
+\the\indexofregister \scratchbox
+\stopbuffer
 
-These three serializers take a verbose or symbolic quantity:
+\typebuffer
+
+We lie a little here because in \CONTEXT\ the box index \tex {scratchbox} is
+actually defined as: \normalexpanded {\typ {\meaningasis \scratchbox}} but it
+still is a number so it fits in.
+
+\getbuffer
+
+A similar primitive gives us the (normally \UNICODE) value of a character:
+
+\startbuffer
+\chardef\MyCharA=65
+\the\indexofcharacter A
+\the\indexofcharacter \MyCharA
+\stopbuffer
+
+\typebuffer
+
+The result is equivalent to \type {\number `A} but avoids the back quote:
+\inlinebuffer.
+
+\stopsection
+
+\startsection[title={Serialization with \prm {todimension}, \prm {toscaled}, \prm {tohexadecimal} and \prm {tointeger}}]
+
+These serializers take a verbose or symbolic quantity:
 
 \starttyping
-\todimension 10pt   \todimension \scratchdimen    % with unit
-\toscaled    10pt   \toscaled    \scratchdimen    % without unit
-\tointeger   10     \tointeger   \scratchcounter
+\todimension   10pt   \todimension   \scratchdimen    % with unit
+\toscaled      10pt   \toscaled      \scratchdimen    % without unit
+\tointeger     10     \tointeger     \scratchcounter
+\tohexadecimal 10     \tohexadecimal \scratchcounter
 \stoptyping
 
 This is particularly handy in cases where you don't know what you deal with, for instance
@@ -2565,6 +2841,29 @@ is often overkill and gives more noise in a trace.
 
 \stopsection
 
+\startsection[title={Serialization with \prm {thewithoutunit}, \prm {tosparsedimension} and \prm {tosparsescaled}}]
+
+By default \TEX\ lets \type {1pt} come out as \type {1.0pt} which is why we also have
+two sparse variants:
+
+\startbuffer
+\todimension    10pt\quad\tosparsedimension  10pt
+\todimension   1.2pt\quad\tosparsedimension 1.2pt
+\toscaled       10pt\quad\tosparsescaled     10pt
+\toscaled      1.2pt\quad\tosparsescaled    1.2pt
+\stopbuffer
+
+\typebuffer
+
+This time trailing zeros (and a trailing period) will be dropped:
+
+\startlines \getbuffer \stoplines
+
+The \prm {thewithoutunit} primitive is like \prm {the} on a dimension but it
+omits the unit.
+
+\stopsection
+
 \startsection[title=Expressions with \prm {numexpression}, \prm {dimexpression}]
 
 The \ETEX\ expression primitives are handy but have some limitations. Although
diff --git a/doc/context/sources/general/manuals/luametatex/luametatex-math.tex b/doc/context/sources/general/manuals/luametatex/luametatex-math.tex
index eb3f6c61d..31ee85b77 100644
--- a/doc/context/sources/general/manuals/luametatex/luametatex-math.tex
+++ b/doc/context/sources/general/manuals/luametatex/luametatex-math.tex
@@ -10,7 +10,8 @@
 
 \topicindex {math}
 
-End 2021 this chapter started with this:
+Because we started from \LUATEX, by the end of 2021 this chapter started with
+this, even if we already reworked the engine:
 
 \startquotation
 At this point there is no difference between \LUAMETATEX\ and \LUATEX\ with
@@ -61,10 +62,10 @@ don't expect other macro packages to use the new features anyway.
 
 For various reasons we need to encode a math character in a 32 bit number and
 because we often also need to keep track of families and classes the range of
-characters is limited to 20 bits. There are upto 64 classes (more than in
-\LUATEX) and 64 families (less than in \LUATEX). The upper limit of characters is
-less that what \UNICODE\ offers but for math we're okay. If needed we can provide
-less families.
+characters is limited to 20 bits. There are upto 64 classes (which is a lot more
+than in \LUATEX) and 64 families (less than in \LUATEX). The upper limit of
+characters is less that what \UNICODE\ offers but for math we're okay. If needed
+we can provide less families.
 
 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
@@ -103,7 +104,7 @@ The unaltered ones are:
 In \LUATEX\ we support the single number primitives *with \type {num} in their
 name) conforming the \XETEX\ method. For the moment that still works but you need
 to figure out the number yourself. The split number variants are more future safe
-with respect to classes and families. Wd don't document \prm {Umathcharnumdef},
+with respect to classes and families. We don't document \prm {Umathcharnumdef},
 \prm {Umathcharnum}, \prm {Umathcodenum} and \prm {Udelcodenum} here any longer.
 
 \starttabulate[|l|l|c|c|c|]
@@ -120,12 +121,12 @@ with respect to classes and families. Wd don't document \prm {Umathcharnumdef},
 \stoptabulate
 
 So, there are upto 64 classes of which at this moment about 20 are predefined so,
-taking some future usage by the engine into account,you can assume 32 upto 63 to
+taking some future usage by the engine into account,you can assume 32 upto 60 to
 be available for any purpose. The number of families has been reduced from 256 to
 64 which is plenty for daily use in an \OPENTYPE\ setup. If we ever need to
-expand the \UNICODE\ range there will be less families. The values of begin and
-end classes and the number of classes can be fetched from the \LUA\ status
-table.
+expand the \UNICODE\ range there will be less families or we just go for a larger
+internal record. The values of begin and end classes and the number of classes
+can be fetched from the \LUA\ status table.
 
 Given the above, specifications typically look like:
 
@@ -144,23 +145,20 @@ that moment the distinction between small and large delimiters will be gone. Of
 course an alternative is to support a specific large size but that is unlikely to
 happen.
 
-% For some of these primitives, all information is packed into a single signed
-% integer. For the first two (\prm {Umathcharnum} and \prm {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 \prm {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 \prm {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
+This means that future versions of \LUAMETATEX\ might drop for instance the large
+family in delimiters, if only because we assume a coherent setup where
+extensibles come from the same font so that we don't need to worry about clashing
+font parameters. This is a condition that we can easily meet in \CONTEXT, which is
+the reference for \LUAMETATEX.
+
+% Constructor related primitives like \prm {Umathaccent} accepts optional keywords
+% to control various details regarding their treatment and rendering. See for
+% instance \in {section} [mathacc] for details. Some keywords are specific, but
+% some are shared between the math nodes (aka noads).
+
+There are more new primitives and most of these will be explained in following
 sections. For instance these are variants of radicals and delimiters all are
-set the same::
+set the same:
 
 \starttabulate[|l|c|c|c|]
 \DB primitive              \BC class \BC family \NC character \NC \NR
@@ -186,10 +184,90 @@ options and keywords.
 
 \topicindex{math+control}
 
-Processing math is controlled by \prm {mathfontcontrol}, a numeric bitset
-parameter. The recommended bits are marked with a star but it really depends on
-the macro package to set up the machinery well. Of course one can just enable all
-and see what happens.
+Rendering math has long been dominated by \TEX\ but that changed when \MICROSOFT\
+came with \OPENTYPE\ math: an implementation as well as a font. Some of that was
+modelled after \TEX\ and some was dictated (we think) by the way word processors
+deal with math. For instance, traditional \TEX\ math has a limited set of glyph
+properties and therefore has a somewhat complex interplay between width and
+italic correction. There are no kerns, contrary to \OPENTYPE\ math fonts that
+provides staircase kerns. Interestingly \TEX\ does have some ligature building
+going on in the engine.
+
+In traditional \TEX\ italic correction gets added to the width and selectively
+removed later (or compensated by some shift and|/|or cheating with the box
+width). When we started with \LUATEX\ we had to gamble quite a bit about how to
+apply parameters and glyph properties which resulted in different code paths,
+heuristics, etc. That worked on the average but fonts are often not perfect and
+when served as an example for another one the bad bits can be inherited. That
+said, over time the descriptions improved and this is what the \OPENTYPE\
+specification has to say about italic correction now \footnote {\type
+{https://docs.microsoft.com/en-us/typography/opentype/spec/math}}:
+
+\startitemize [n]
+    \startitem
+        When a run of slanted characters is followed by a straight character
+        (such as an operator or a delimiter), the italics correction of the last
+        glyph is added to its advance width.
+    \stopitem
+    \startitem
+        When positioning limits on an N-ary operator (e.g., integral sign), the
+        horizontal position of the upper limit is moved to the right by half the
+        italics correction, while the position of the lower limit is moved to the
+        left by the same distance.
+    \stopitem
+    \startitem
+        When positioning superscripts and subscripts, their default horizontal
+        positions are also different by the amount of the italics correction of
+        the preceding glyph.
+    \stopitem
+\stopitemize
+
+The first rule is complicated by the fact that \quote {followed} is vague: in
+\TEX\ the sequence \type {$ a b c def $} results in six separate atoms, separated
+by inter atom spacing. The characters in these atoms are the nucleus and there
+can be a super- and|/|or subscript attached and in \LUAMETATEX\ also a prime,
+superprescript and/or subprescript.
+
+The second rule comes from \TEX\ and one can wonder why the available top accent
+anchor is not used. Maybe because bottom accent anchors are missing? Anyway,
+we're stuck with this now.
+
+The third rule also seems to come from \TEX. Take the \quote {\it f} character:
+in \TEX\ fonts that one has a narrow width and part sticks out (in some even at
+the left edge). That means that when the subscript gets attached it will move
+inwards relative to the real dimensions. Before the superscript an italic
+correction is added so what that correction is non|-|zero the scripts are
+horizontally shifted relative to each other.
+
+Now look at this specification of staircase kerns \footnote {Idem.}:
+
+\startnarrower
+    The \type {MathKernInfo} table provides mathematical kerning values used for
+    kerning of subscript and superscript glyphs relative to a base glyph. Its
+    purpose is to improve spacing in situations such as omega with superscript f
+    or capital V with subscript capital A.
+
+    Mathematical kerning is height dependent; that is, different kerning amounts
+    can be specified for different heights within a glyph’s vertical extent. For
+    any given glyph, different values can be specified for four corner positions,
+    top|-|right, to|-|left, etc., allowing for different kerning adjustments
+    according to whether the glyph occurs as a subscript, a superscript, a base
+    being kerned with a subscript, or a base being kerned with a superscript.
+\stopnarrower
+
+Again we're talking super- and subscripts and should we now look at the italic
+correction or assume that the kerns do the job? This is a mixed bag because
+scripts are not always (single) characters. We have to guess a bit here. After
+years of experimenting we came to the conclusion that it will never be okay so
+that's why we settled on controls and runtime fixes to fonts.
+
+This means that processing math is controlled by \prm {mathfontcontrol}, a
+numeric bitset parameter. The recommended bits are marked with a star but it
+really depends on the macro package to set up the machinery well. Of course one
+can just enable all and see what happens. \footnote {This model was more granular
+and could even be font (and character) specific but that was dropped because
+fonts are too inconsistent and an occasional fit is more robust that a generally
+applied rule.}
 
 \starttabulate[|l|l|c|]
 \DB bit             \BC name                            \NC \NC \NR
@@ -212,21 +290,21 @@ and see what happens.
 \NC \type {0x08000} \NC \type {checktextitalickern}     \NC \star \NR
 \NC \type {0x10000} \NC \type {checkspaceitalickern}    \NC       \NR
 \NC \type {0x20000} \NC \type {applyscriptitalickern}   \NC \star \NR
-\NC \type {0x40000} \NC \type {italicshapekern}         \NC \star \NR
+%NC \type {0x40000} \NC \type {italicshapekern}         \NC \star \NR now default
 \LL
 \stoptabulate
 
-One reason for this approach is that traditional and \OPENTYPE\ fonts have
-different approaches (especially when it comes to dealing with the width and
-italic corrections) and is even more complicated by the fact that the fonts are
-often inconsistent (within and between). In \CONTEXT\ we deal with this by
-runtime fixes to fonts. In any case the Cambria font is taken as reference.
+So, to summarize: the reason for this approach is that traditional and \OPENTYPE\
+fonts have different approaches (especially when it comes to dealing with the
+width and italic corrections) and is even more complicated by the fact that the
+fonts are often inconsistent (within and between). In \CONTEXT\ we deal with this
+by runtime fixes to fonts. In any case the Cambria font is taken as reference.
 
 \stopsection
 
 \startsection[title={Math styles}]
 
-\startsubsection[title={\prm {mathstyle}}]
+\startsubsection[title={\prm {mathstyle}, \prm {mathstackstyle} and \prm {Ustyle}}]
 
 \topicindex {math+styles}
 
@@ -235,7 +313,7 @@ expandable fashion (while the math list is still being read). To make this
 possible, \LUATEX\ adds the new primitive: \prm {mathstyle}. This is a \quote
 {convert command} like e.g. \prm {romannumeral}: its value can only be read,
 not set. Beware that contrary to \LUATEX\ this is now a proper number so you need
-to use \type {\number} o r\type {\the} in order to serialize it.
+to use \type {\number} or \type {\the} in order to serialize it.
 
 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
@@ -341,6 +419,69 @@ 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.
 
+So far for the more \LUATEX ish approach. One problem with \prm {mathstyle} is
+that when you got it, and want to act upon it, you need to remap it onto say \prm
+{scriptstyle} which can be done with an eight branched \prm {ifcase}. This is
+why we also have a more efficient alternative that you can use in macros:
+
+\starttyping
+\normalexpand{ ... \Ustyle\the\mathstyle      ...}
+\normalexpand{ ... \Ustyle\the\mathstackstyle ...}
+\stoptyping
+
+This new primitive \prm {Ustyle} accepts a numeric value. The \prm
+{mathstackstyle} primitive is just a bonus (it complements \prm {Ustack}).
+
+The styles that the different math components and their subcomponents start out
+with are no longer hard coded but can be set at runtime:
+
+\starttabulate
+\DB primitive name                        \BC default \NC \NR
+\TB
+\NC \prm {Umathoverlinevariant}           \NC cramped           \NC \NR
+\NC \prm {Umathunderlinevariant}          \NC normal            \NC \NR
+\NC \prm {Umathoverdelimitervariant}      \NC small             \NC \NR
+\NC \prm {Umathunderdelimitervariant}     \NC small             \NC \NR
+\NC \prm {Umathdelimiterovervariant}      \NC normal            \NC \NR
+\NC \prm {Umathdelimiterundervariant}     \NC normal            \NC \NR
+\NC \prm {Umathhextensiblevariant}        \NC normal            \NC \NR
+\NC \prm {Umathvextensiblevariant}        \NC normal            \NC \NR
+\NC \prm {Umathfractionvariant}           \NC cramped           \NC \NR
+\NC \prm {Umathradicalvariant}            \NC cramped           \NC \NR
+\NC \prm {Umathdegreevariant}             \NC doublesuperscript \NC \NR
+\NC \prm {Umathaccentvariant}             \NC cramped           \NC \NR
+\NC \prm {Umathtopaccentvariant}          \NC cramped           \NC \NR
+\NC \prm {Umathbotaccentvariant}          \NC cramped           \NC \NR
+\NC \prm {Umathoverlayaccentvariant}      \NC cramped           \NC \NR
+\NC \prm {Umathnumeratorvariant}          \NC numerator         \NC \NR
+\NC \prm {Umathdenominatorvariant}        \NC denominator       \NC \NR
+\NC \prm {Umathsuperscriptvariant}        \NC superscript       \NC \NR
+\NC \prm {Umathsubscriptvariant}          \NC subscript         \NC \NR
+\NC \prm {Umathprimevariant}              \NC superscript       \NC \NR
+\NC \prm {Umathstackvariant}              \NC numerator         \NC \NR
+\LL
+\stoptabulate
+
+These defaults remap styles are as follows:
+
+\starttabulate[|Tl|l|l|]
+\DB default           \BC result                    \BC mapping \NC \NR
+\TB
+\NC cramped           \NC cramp the style           \NC D' D' T' T' S'  S'  SS' SS' \NC \NR
+\NC subscript         \NC smaller and cramped       \NC S' S' S' S' SS' SS' SS' SS' \NC \NR
+\NC small             \NC smaller                   \NC S  S  S  S  SS  SS  SS  SS  \NC \NR
+\NC superscript       \NC smaller                   \NC S  S  S  S  SS  SS  SS  SS  \NC \NR
+\NC smaller           \NC smaller unless already SS \NC S  S' S  S' SS  SS' SS  SS' \NC \NR
+\NC numerator         \NC smaller unless already SS \NC S  S' S  S' SS  SS' SS  SS' \NC \NR
+\NC denominator       \NC smaller, all cramped      \NC S' S' S' S' SS' SS' SS' SS' \NC \NR
+\NC doublesuperscript \NC smaller, keep cramped     \NC S  S' S  S' SS  SS' SS  SS' \NC \NR
+\LL
+\stoptabulate
+
+The main reason for opening this up was that it permits experiments and removed
+hard coded internal values. But as these defaults served well for decades there
+are no real reasons to change them.
+
 \stopsubsection
 
 \startsubsection[title={\prm {Ustack}}]
@@ -358,7 +499,8 @@ $\Ustack {a \over b}$
 \stoptyping
 
 The \prm {Ustack} command will scan the next brace and start a new math group
-with the correct (numerator) math style.
+with the correct (numerator) math style. The \prm {ustackstyle} relates to this
+feature.
 
 \stopsubsection
 
@@ -423,7 +565,8 @@ we force styles in the script using \prm {scriptstyle} and \prm
 
 \getbuffer[demo]
 
-Now we set the following parameters
+Now we set the following parameters using \prm {setmathspacing} that accepts two
+class identifier, a style and a value.
 
 \startbuffer[setup]
 \setmathspacing 0 3 \scriptstyle = 30mu
@@ -465,12 +608,14 @@ In \LUATEX, the font dimension parameters that \TEX\ used in math typesetting ar
 now accessible via primitive commands. In fact, refactoring of the math engine
 has resulted in turning some hard codes properties into parameters.
 
+{\em The next needs checking ...}
+
 \starttabulate
 \DB primitive name                 \BC description \NC \NR
 \TB
 \NC \prm {Umathquad}               \NC the width of 18 mu's \NC \NR
 \NC \prm {Umathaxis}               \NC height of the vertical center axis of
-                                         the math formula above the baseline \NC \NR
+                                       the math formula above the baseline \NC \NR
 \NC \prm {Umathoperatorsize}       \NC minimum size of large operators in display mode \NC \NR
 \NC \prm {Umathoverbarkern}        \NC vertical clearance above the rule \NC \NR
 \NC \prm {Umathoverbarrule}        \NC the width of the rule \NC \NR
@@ -526,33 +671,81 @@ has resulted in turning some hard codes properties into parameters.
 \LL
 \stoptabulate
 
-In addition to the above official \OPENTYPE\ font parameters we have these:
+In addition to the above official \OPENTYPE\ font parameters we have these (the
+undefined will get presets, quite likely zero):
 
 \starttabulate
-\DB primitive name                            \BC description \NC \NR
+\DB primitive name                             \BC description \NC \NR
 \TB
-\NC \prm{Umathprimeraisepercent}              \NC the percentage that the vertical position is scaled \NC \NR
-\NC \prm{Umathprimeshiftup}                   \NC the prime variant of \prm {SuperscriptShiftUp} \NC \NR
-\NC \prm{Umathprimebaselinedropmax}           \NC the prime variant of \prm {SuperscriptBaselineDropMax} \NC \NR
-\NC \prm{Umathprimeshiftupcramped}            \NC the prime variant of \prm {SuperscriptShiftUpCramped} \NC \NR
-\NC \prm{Umathprimespaceafter}                \NC the prime variant of \prm {UmathSpaceAfterScript} \NC \NR
-\NC \prm{Umathprimewidthpercent}              \NC the percentage of width that gets added \NC \NR
-\NC \prm{Umathspacebeforescript}              \NC the prescript variant of \prm {UmathSpaceAfterScript} \NC \NR
-\NC \prm{Umathnolimitsupfactor}               \NC a multiplier for the way limits are shifted up and down \NC \NR
-\NC \prm{Umathnolimitsubfactor}               \NC a multiplier for the way limits are shifted up and down \NC \NR
-\NC \prm{Umathaccenttopshiftup}               \NC the amount that a top accent is shifted up \NC \NR
-\NC \prm{Umathaccentbottomshiftdown}          \NC the amount that a bottom accent is shifted down \NC \NR
-\NC \prm{Umathflattenedaccenttopshiftup}      \NC the amount that a wide top accent is shifted up \NC \NR
-\NC \prm{Umathflattenedaccentbottomshiftdown} \NC the amount that a wide bottom accent is shifted down \NC \NR
-\NC \prm{Umathaccentbasedepth}                \NC the complement of \prm {UmathAccentBaseHeight} \NC \NR
-\NC \prm{Umathaccentflattenedbasedepth}       \NC the complement of \prm {UmathFlattenedAccentBaseHeight} \NC \NR
-\LL
+\NC \prm {Umathconnectoroverlapmin}            \NC \NC \NR
+\NC \prm {Umathsubscriptsuperscriptshiftdown}  \NC \NC \NR
+\NC \prm {Umathfractiondelsize}                \NC \NC \NR
+\NC \prm {Umathfractiondelsize}                \NC \NC \NR
+\NC \prm {Umathnolimitsupfactor}               \NC a multiplier for the way limits are shifted up and down \NC \NR
+\NC \prm {Umathnolimitsubfactor}               \NC a multiplier for the way limits are shifted up and down \NC \NR
+\NC \prm {Umathaccentbasedepth}                \NC the complement of \prm {UmathAccentBaseHeight} \NC \NR
+\NC \prm {Umathflattenedaccentbasedepth}       \NC the complement of \prm {UmathFlattenedAccentBaseHeight} \NC \NR
+\NC \prm {Umathspacebeforescript}              \NC \NC \NR
+\NC \prm {Umathraisepercent}                   \NC the percentage that the vertical position is scaled \NC \NR
+\NC \prm {Umathprimeshiftup}                   \NC the prime variant of \prm {SuperscriptShiftUp} \NC \NR
+\NC \prm {Umathprimeshiftupcramped}            \NC the prime variant of \prm {SuperscriptShiftUpCramped} \NC \NR
+\NC \prm {Umathprimespaceafter}                \NC the prescript variant of \prm {UmathSpaceAfterScript} \NC \NR
+\NC \prm {Umathprimebaselinedropmax}           \NC the prime variant of \prm {SuperscriptBaselineDropMax} \NC \NR
+\NC \prm {Umathprimewidthpercent}              \NC the percentage of width that gets added \NC \NR
+\NC \prm {Umathskeweddelimitertolerance}       \NC \NC \NR
+\NC \prm {Umathaccenttopshiftup}               \NC the amount that a top accent is shifted up \NC \NR
+\NC \prm {Umathaccentbottomshiftdown}          \NC the amount that a bottom accent is shifted down \NC \NR
+\NC \prm {Umathaccenttopovershoot}             \NC \NC \NR
+\NC \prm {Umathaccentbottomovershoot}          \NC \NC \NR
+\NC \prm {Umathaccentsuperscriptdrop}          \NC \NC \NR
+\NC \prm {Umathaccentsuperscriptpercent}       \NC \NC \NR
+\NC \prm {Umathflattenedaccenttopshiftup}      \NC the amount that a wide top accent is shifted up \NC \NR
+\NC \prm {Umathflattenedaccentbottomshiftdown} \NC the amount that a wide bottom accent is shifted down \NC \NR
+\NC \prm {Umathdelimiterpercent}               \NC \NC \NR
+\NC \prm {Umathdelimitershortfall}             \NC \NC \NR
+\stoptabulate
+
+These relate to the font parameters and in \CONTEXT\ we assign some different
+defaults and tweak them in the goodie files:
+
+\starttabulate[|T|T|c|]
+\DB font parameter                    \BC primitive name                             \BC default   \NC \NR
+\TB
+\NC MinConnectorOverlap               \NC \prm {Umathconnectoroverlapmin}            \NC 0         \NC \NR
+\NC SubscriptShiftDownWithSuperscript \NC \prm {Umathsubscriptsuperscriptshiftdown}  \NC inherited \NC \NR
+\NC FractionDelimiterSize             \NC \prm {Umathfractiondelsize}                \NC undefined \NC \NR
+\NC FractionDelimiterDisplayStyleSize \NC \prm {Umathfractiondelsize}                \NC undefined \NC \NR
+\NC NoLimitSubFactor                  \NC \prm {Umathnolimitsupfactor}               \NC 0         \NC \NR
+\NC NoLimitSupFactor                  \NC \prm {Umathnolimitsubfactor}               \NC 0         \NC \NR
+\NC AccentBaseDepth                   \NC \prm {Umathaccentbasedepth}                \NC reserved  \NC \NR
+\NC FlattenedAccentBaseDepth          \NC \prm {Umathflattenedaccentbasedepth}       \NC reserved  \NC \NR
+\NC SpaceBeforeScript                 \NC \prm {Umathspacebeforescript}              \NC 0         \NC \NR
+\NC PrimeRaisePercent                 \NC \prm {Umathprimeraise}                     \NC 0         \NC \NR
+\NC PrimeShiftUp                      \NC \prm {Umathprimeshiftup}                   \NC 0         \NC \NR
+\NC PrimeShiftUpCramped               \NC \prm {Umathprimeshiftupcramped}            \NC 0         \NC \NR
+\NC PrimeSpaceAfter                   \NC \prm {Umathprimespaceafter}                \NC 0         \NC \NR
+\NC PrimeBaselineDropMax              \NC \prm {Umathprimebaselinedropmax}           \NC 0         \NC \NR
+\NC PrimeWidthPercent                 \NC \prm {Umathprimewidth}                     \NC 0         \NC \NR
+\NC SkewedDelimiterTolerance          \NC \prm {Umathskeweddelimitertolerance}       \NC 0         \NC \NR
+\NC AccentTopShiftUp                  \NC \prm {Umathaccenttopshiftup}               \NC undefined \NC \NR
+\NC AccentBottomShiftDown             \NC \prm {Umathaccentbottomshiftdown}          \NC undefined \NC \NR
+\NC AccentTopOvershoot                \NC \prm {Umathaccenttopovershoot}             \NC 0         \NC \NR
+\NC AccentBottomOvershoot             \NC \prm {Umathaccentbottomovershoot}          \NC 0         \NC \NR
+\NC AccentSuperscriptDrop             \NC \prm {Umathaccentsuperscriptdrop}          \NC 0         \NC \NR
+\NC AccentSuperscriptPercent          \NC \prm {Umathaccentsuperscriptpercent}       \NC 0         \NC \NR
+\NC FlattenedAccentTopShiftUp         \NC \prm {Umathflattenedaccenttopshiftup}      \NC undefined \NC \NR
+\NC FlattenedAccentBottomShiftDown    \NC \prm {Umathflattenedaccentbottomshiftdown} \NC undefined \NC \NR
+\NC DelimiterPercent                  \NC \prm {Umathdelimiterpercent}               \NC 0         \NC \NR
+\NC DelimiterShortfall                \NC \prm {Umathdelimitershortfall}             \NC 0         \NC \NR
 \stoptabulate
 
 These parameters not only provide a bit more control over rendering, they also
 can be used in compensating issues in font, because no font is perfect. Some are
 the side effects of experiments and they have CamelCase companions in the \type
-{MathConstants} table.
+{MathConstants} table. For historical reasons the names are a bit inconsistent as
+some originate in \TEX\ so we prefer to keep those names. Not many users will
+mess around with these font parameters anyway. \footnote {I wonder if some names
+should change, so that decision is pending.}
 
 Each of the parameters in this section can be set by a command like this:
 
@@ -589,6 +782,9 @@ post atom penalties and atom rules.
 
 \topicindex {math+parameters}
 
+We already introduced the font specific math parameters but we tell abit more
+about them and how they relate to the original \TEX\ font dimensions.
+
 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
@@ -613,117 +809,187 @@ 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 \llap{\high{\tx #2\enspace}}\ttbf \prm {#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}
+\MathLine{Umathaxis}                     {}   {}                     {AxisHeight}                              {axis_height}
+\MathLine{Umathaccentbaseheight}         {}   {}                     {AccentBaseHeight}                        {xheight}
+\MathLine{Umathflattenedaccentbaseheight}{}   {}                     {FlattenedAccentBaseHeight}               {xheight}
+\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
 
-{\em Todo: add the extra ones.}
+A few notes:
+
+\startitemize[n]
+
+\startitem
+    \OPENTYPE\ fonts set \prm {Umathlimitabovekern} and \prm
+    {Umathlimitbelowkern} to zero and set \prm {Umathquad} to the font size of
+    the used font, because these are not supported in the \type {MATH} table.
+\stopitem
+
+\startitem
+    Traditional \TFM\ fonts do not set \prm {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 \prm {Umathradicaldegreebefore}, \prm {Umathradicaldegreeafter}, and \prm
+    {Umathradicaldegreeraise}. These are then automatically initialized to
+    $5/18$quad, $-10/18$quad, and 60.
+\stopitem
+
+\startitem
+    If \TFM\ fonts are used, then the \prm {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
+    \prm {Umathradicalvgap} is set, it will not be recalculated any more.
+\stopitem
+
+\startitem
+    When \TFM\ fonts are used a similar situation arises with respect to \prm
+    {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 \prm {Umathspaceafterscript} is set, \prm {scriptspace} will never
+    be looked at again.
+\stopitem
+
+\startitem
+    Traditional \TFM\ fonts set \prm {Umathconnectoroverlapmin} to zero because
+    \TEX82\ always stacks extensibles without any overlap.
+\stopitem
+
+\startitem
+    The \prm {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.
+\stopitem
+
+\startitem
+    The \prm {Umathradicaldegreeraise} is a special case because it is the only
+    parameter that is expressed in a percentage instead of a number of scaled
+    points.
+\stopitem
+
+\startitem
+    \type {SubscriptShiftDownWithSuperscript} does not actually exist in the
+    \quote {standard} \OPENTYPE\ math font Cambria, but it is useful enough to be
+    added.
+\stopitem
+
+\startitem
+    \type {FractionDelimiterDisplayStyleSize} and \type {FractionDelimiterSize}
+    do not actually exist in the \quote {standard} \OPENTYPE\ math font Cambria,
+    but were useful enough to be added.
+\stopitem
+
+\stopitemize
+
+As this mostly refers to \LUATEX\ there is more to tell about how \LUAMETATEX\
+deals with it. However, it is enough to know that much more behavior is
+configurable.
+
+\stopsubsection
 
-Note 1: \OPENTYPE\ fonts set \prm {Umathlimitabovekern} and \prm
-{Umathlimitbelowkern} to zero and set \prm {Umathquad} to the font size of the
-used font, because these are not supported in the \type {MATH} table,
+\stopsection
 
-Note 2: Traditional \TFM\ fonts do not set \prm {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
-\prm {Umathradicaldegreebefore}, \prm {Umathradicaldegreeafter}, and \prm
-{Umathradicaldegreeraise}. These are then automatically initialized to
-$5/18$quad, $-10/18$quad, and 60.
+\startsection[title={Extra parameters}]
 
-Note 3: If \TFM\ fonts are used, then the \prm {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 \prm
-{Umathradicalvgap} is set, it will not be recalculated any more.
+\startsubsection[title={Style related parameters}]
 
-Note 4: When \TFM\ fonts are used a similar situation arises with respect to \prm
-{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 \prm {Umathspaceafterscript} is set, \prm {scriptspace} will never be
-looked at again.
+There are a couple of parameters that don't relate to the font but are more generally
+influencing the appearances. Some were added for experimenting.
 
-Note 5: Traditional \TFM\ fonts set \prm {Umathconnectoroverlapmin} to zero
-because \TEX82\ always stacks extensibles without any overlap.
+\starttabulate[|l|l|]
+\DB primitive \BC meaning \NC \NR
+\prm {Umathextrasubpreshift}    \NC \NR
+\prm {Umathextrasubprespace}    \NC \NR
+\prm {Umathextrasubshift}       \NC \NR
+\prm {Umathextrasubspace}       \NC \NR
+\prm {Umathextrasuppreshift}    \NC \NR
+\prm {Umathextrasupprespace}    \NC \NR
+\prm {Umathextrasupshift}       \NC \NR
+\prm {Umathextrasupspace}       \NC \NR
+\prm {Umathsubshiftdistance}    \NC \NR
+\prm {Umathsupshiftdistance}    \NC \NR
+\prm {Umathpresubshiftdistance} \NC \NR
+\prm {Umathpresupshiftdistance} \NC \NR
+\prm {Umathprimeshiftdrop}      \NC \NR
+\LL
+\stoptabulate
 
-Note 6: The \prm {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.
+\stopsubsection
 
-Note 7: The \prm {Umathradicaldegreeraise} is a special case because it is the
-only parameter that is expressed in a percentage instead of a number of scaled
-points.
+\startsubsection[title={Math struts}]
 
-Note 8: \type {SubscriptShiftDownWithSuperscript} does not actually exist in the
-\quote {standard} \OPENTYPE\ math font Cambria, but it is useful enough to be
-added.
+Todo:
 
-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.
+\starttabulate[|l|l|]
+\DB primitive \BC meaning \NC \NR
+\NC \prm {Umathruleheight} \NC \NR
+\NC \prm {Umathruledepth}  \NC \NR
+\LL
+\stoptabulate
 
 \stopsubsection
 
@@ -818,7 +1084,9 @@ 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. As a bonus we also introduced a \prm {tinymuskip} primitive.
+taken into account. As a bonus we also introduced the \prm {tinymuskip} and \prm
+{pettymuskip} primitives, just because we consider these fundamental, but they
+are not assigned internally to atom spacing combinations.
 
 In \LUAMETATEX\ we go a bit further. Any named dimension, glue and mu glue
 register as well as the constants with these properties can be bound to a pair by
@@ -880,6 +1148,46 @@ unprocessed math list. The result looks as follows:
 
 \stopsubsection
 
+\startsubsection[title={Arbitrary atoms with \prm {mathatom} etc.}]
+
+The original \TEX\ engine has primitives like \prm {mathord} and a limited set of
+possible atoms. In \LUAMETATEX\ we have many more built in and you can add more.
+It will take a while before we have documented all the new math features and more
+details can be found in the manuals that come with \CONTEXT\ for which all this
+was implemented. In addition to \prm {mathord}, \prm {mathop}, \prm {mathbin},
+\prm {mathrel}, \prm {mathopen}, \prm {mathclose}, \prm {mathpunct} and \prm
+{mathinner} we have \prm {mathfrac}, \prm {mathrad}, \prm {mathmiddle}, \prm
+{mathaccent}, \prm {mathfenced}. \prm {mathghost} and the existing \prm
+{underline} and \prm {overline} class driven atoms.
+
+The \prm {mathatom} primitive is the generic one and it accepts a couple of
+keywords:
+
+\starttabulate[|cT|l|]
+\DB keyword    \BC argument \NC meaning \NC \NR
+\TB
+\NC attr       \NC int int \NC attributes to be applied to this atom \NC \NR
+\NC leftclass  \NC class   \NC the left edge class that determines spacing etc \NC \NR
+\NC rightclass \NC class   \NC the right edge class that determines spacing etc \NC \NR
+\NC class      \NC class   \NC the general class \NC \NR
+\NC unpack     \NC         \NC unpack this atom in inline math \NC \NR
+\NC source     \NC int     \NC a symbolic index of the resulting box \NC \NR
+\NC textfont   \NC         \NC use the current text font \NC \NR
+\NC mathfont   \NC         \NC use the current math font \NC \NR
+\NC limits     \NC         \NC put scripts on top and below \NC \NR
+\NC nolimits   \NC         \NC force scripts to be postscripts \NC \NR
+\NC nooverflow \NC         \NC keep (extensible) within target dimensions \NC \NR
+\NC options    \NC int     \NC bitset with options \NC \NR
+\NC void       \NC         \NC discard content and ignore dimensions \NC \NR
+\NC phantom    \NC         \NC discard content but retain dimensions \NC \NR
+\LL
+\stoptabulate
+
+To what extend the options kick in depends on the class as well where and how the
+atom is used.
+
+\stopsubsection
+
 \startsubsection[title={Checking a state with \prm {ifmathparameter}}]
 
 When you adapt math parameters it might make sense to see if they are set at all.
@@ -1188,52 +1496,10 @@ is divided by 1000 which is the usual way to mimmick floating point factors in
 
 \startsection[title={Math constructs}]
 
-\startsubsection[title={Unscaled fences and \prm{mathdelimitersmode}}]
+\startsubsection[title={Cheating with fences}]
 
 \topicindex {math+fences}
 
-The \prm {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.
-
-\starttexdefinition Whatever #1
-    \NC \type{\mathdelimitersmode = #1}
-    \NC \mathdelimitersmode#1\ruledhbox{\showglyphs\showfontkerns\showfontitalics$f(x)$}
-    \NC \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}).
-
 Sometimes you might want to act upon the size of a delimiter, something that is
 not really possible because of the fact that they are calculated {\em after} most
 has been typeset already. For this we have two keyword: \type {phantom} and
@@ -1756,12 +2022,12 @@ the four mathon|/|mathoff commands with explicit dollar sign(s).
 
 \stopsubsection
 
-\startsubsection[title={Script commands \prm {Unosuperscript} and \prm {Unosubscript}}]
+\startsubsection[title={Script commands \prm {Unosuperscript}, \prm {Unosubscript}, \prm {Unosuperprescript} and \prm {Unosubprescript}}]
 
 \topicindex {math+styles}
 \topicindex {math+scripts}
 
-These two commands result in super- and subscripts but with the current style (at the
+These commands result in super- and subscripts but with the current style (at the
 time of rendering). So,
 
 \startbuffer[script]
@@ -1779,13 +2045,55 @@ results in \inlinebuffer[script].
 
 \stopsubsection
 
-\startsubsection[title={Injecting primes with {Uprimescript}}]
+\startsubsection[title={Script commands \prm {Ushiftedsuperscript}, \prm {Ushiftedsubscript}, \prm {Ushiftedsuperprescript} and \prm {Ushiftedsubprescript}}]
+
+\topicindex {math+styles}
+\topicindex {math+scripts}
+\topicindex {math+indices}
+
+Sometimes a script acts as an index in which case is should be anchored
+differently. For that we have four extra primitives. Here the shifted postscripts
+are shown:
+
+\startbuffer[script]
+$
+    x\Usuperscript       {1}\Usubscript       {2} =
+    x\Ushiftedsuperscript{1}\Ushiftedsubscript{2} =
+    x\Usuperscript       {1}\Ushiftedsubscript{2} =
+    x\Ushiftedsuperscript{1}\Usubscript       {2}
+$
+\stopbuffer
 
-{\em Todo: explain this one.}
+\typebuffer[script]
+
+results in \inlinebuffer[script].
 
 \stopsubsection
 
-\startsubsection[title={Prescripts with \prm {Usuperprescript} and {Usubprescript}}]
+\startsubsection[title={Injecting primes with \prm {Uprimescript}}]
+
+This one is a bit special. In \LUAMETATEX\ a prime is a native element of a
+nucleus, alongside the two prescript and two postscripts. The most confusing
+combination of primes and postscripts is the case where we have a prime and
+superscript. In that case we assume that in order to avoid confusion parenthesis
+are applied so we don't covert it. That leaves three cases:
+
+\startbuffer[script]
+$
+    a \Uprimescript{1} \Usuperscript{2} \Usubscript {3} +
+    b \Usubscript  {3} \Uprimescript{1} +
+    c \Uprimescript{1} \Usubscript  {3} = d
+$
+\stopbuffer
+
+\typebuffer[script]
+
+This gets rendered as: \inlinebuffer[script]. In this case a subscript is handled as if
+it were an index.
+
+\stopsubsection
+
+\startsubsection[title={Prescripts with \prm {Usuperprescript} and \prm {Usubprescript}}]
 
 \startbuffer
 \hbox{$
@@ -1957,6 +2265,15 @@ effect and use a 20\percent\ scaling:
 
 \stopsubsection
 
+\startsubsection[title={Spreading math with \prm {maththreshold}}]
+
+Small formulas that don't get unpacked can be made to act like glue, that is,
+they become a sort of leader and permit the par builder to prevent excessive
+spacing because the embedded inter atom glue can now participate in the
+calculations. The \prm {maththreshold} primitive is a regular glue parameter.
+
+\stopsubsection
+
 \stopsection
 
 \stopchapter
diff --git a/doc/context/sources/general/manuals/luametatex/luametatex-rejected.tex b/doc/context/sources/general/manuals/luametatex/luametatex-rejected.tex
new file mode 100644
index 000000000..2cf7edf81
--- /dev/null
+++ b/doc/context/sources/general/manuals/luametatex/luametatex-rejected.tex
@@ -0,0 +1,94 @@
+% language=us runpath=texruns:manuals/luametatex
+
+\environment luametatex-style
+
+\startcomponent luametatex-rejected
+
+\startchapter[reference=rejected,title={Rejected features}]
+
+\startsection[title=Introduction]
+
+I should have started this chapter sooner because some experiments were removed
+without them being documented. This chapter is mostly for myself so that I don't
+revisit rejected features.
+
+\stopsection
+
+\startsection[title=Text]
+
+{\em todo}
+
+\stopsection
+
+\startsection[title=Math]
+
+\startsubsection[title=Fences]
+
+The \tex {mathfencesmode} primitive could be used to force the atom class of the
+fake fences to be the old inner class instead of the new fence class but we
+dropped that: it's now always a fence subtype (class). Unpacking is therefore now
+controlled by a class option and not enforced by the (new in \LUAMETATEX) subtype.
+
+\stopsubsection
+
+\startsubsection[title=Delimiters]
+
+The \tex {mathdelimitersmode} primitive was experimental and dealt 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.
+
+So, when set to 7 fenced subformulas with unscaled delimiters came out the same
+as unfenced ones. This could be handy for cases where one was forced to use \prm
+{left} and \prm {right} always because of unpredictable content. The full list of
+flags that we had at the time of removal 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
+\NC \type{"20} \NC don't error on a missing right  \NC \NR
+\LL
+\stoptabulate
+
+Because the effect depends on the font (and for Cambria one could use for
+instance \type {"16}) we finally decided to kick it out and correct the font
+instead using the font goodie file. After all it's more a \CONTEXT\ preference
+than an overall demand (read: we think no one else cares much about this).
+
+The \type {"20} options to not error on a missing right fence has been turned
+into \prm {mathcheckfencesmode}.
+
+\stopsubsection
+
+\startsubsection[title=Flattening]
+
+The \tex {mathflattenmode} primitive is gone as we have other ways to deal with
+this now. It related to italic corrections in traditional fonts.
+
+\stopsubsection
+
+\startsubsection[title=Rules]
+
+The \tex {mathrulethicknessmode} feature has been turned into a class option
+which is more granular.
+
+\stopsection
+
+\startsubsection[title=Control]
+
+Although it has its use when developing \LUAMETATEX\ the \tex {mathcontrolmode}
+parameters is no longer there. We have plenty of (more) detailed control now.
+
+\stopsection
+
+
+\stopchapter
+
+\stopcomponent
diff --git a/doc/context/sources/general/manuals/luametatex/luametatex.tex b/doc/context/sources/general/manuals/luametatex/luametatex.tex
index 69bfc9509..f2becf0b7 100644
--- a/doc/context/sources/general/manuals/luametatex/luametatex.tex
+++ b/doc/context/sources/general/manuals/luametatex/luametatex.tex
@@ -96,6 +96,9 @@
 
 % with mimalloc and msvc we get a better native performance than crosscompiled
 
+% On the 2018 Dell 7520 Precission Xeon laptop runtime for 322 pages is now exactly
+% 8 seconds (just below 40 pages per second), we talking July 16, 2022.
+
 % \enableexperiments [tabulateusesize]
 % \enableexperiments [tabulatesparseskips]
 
@@ -151,6 +154,7 @@
     \component luametatex-pdf
     \component luametatex-libraries
     \component luametatex-primitives % this generates a list
+    \component luametatex-rejected
 \stopbodymatter
 
 \startbackmatter