2021-11-24 19:47:00

5 files changed, 396 insertions, 75 deletions

diff --git a/doc/context/documents/general/manuals/luametatex.pdf b/doc/context/documents/general/manuals/luametatex.pdf
index ac2ab6fd0..822146908 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-building.tex b/doc/context/sources/general/manuals/luametatex/luametatex-building.tex
index eb8375cfa..61b11b18d 100644
--- a/doc/context/sources/general/manuals/luametatex/luametatex-building.tex
+++ b/doc/context/sources/general/manuals/luametatex/luametatex-building.tex
@@ -24,8 +24,8 @@ other chapters. These enhancements are still somewhat experimental.
 
 {\em This section will describe \prm {autoparagraphmode}, \prm
 {shapingpenaltiesmode}, \prm {shapingpenaltymode}, \prm {everybeforepar}, \prm
-{snapshotpar}, \prm {wrapuppar}, enz. For the moment the manuals that come with
-\CONTEXT\ have to do.}
+{snapshotpar}, \prm {wrapuppar}, \prm {orphanpenalties}, \prm {orphanpenalty},
+enz. For the moment the manuals that come with \CONTEXT\ have to do.}
 
 \stopsection
 
@@ -51,17 +51,17 @@ very early in the macro package loading process.
 
 
 \starttabulate[|l|l|p|]
-\DB primitive               \BC traditional           \BC explanation \NC \NR
+\DB primitive               \BC traditional            \BC explanation \NC \NR
 \TB
-\NC \prm {insertdistance}   \NC skip                  \NC the space before the first instance (on a page) \NC \NR
-\NC \prm {insertmultiplier} \NC count                 \NC a factor that is used to calculate the height used \NC \NR
-\NC \prm {insertlimit}      \NC dimen                 \NC the maximum amount of space on a page to be taken \NC \NR
-\NC \prm {insertpenalty}    \NC \prm{insertpenalties} \NC the floating penalty (used when set) \NC \NR
-\NC \prm {insertmaxdepth}   \NC \prm{maxdepth}        \NC the maximum split depth (used when set) \NC \NR
-\NC \prm {insertstorage}    \NC                       \NC signals that the insert has to be stored for later \NC \NR
-\NC \prm {insertheight}     \NC \prm {ht} box         \NC the accumulated height of the inserts so far \NC \NR
-\NC \prm {insertdepth}      \NC \prm {dp} box         \NC the current depth of the inserts so far \NC \NR
-\NC \prm {insertwidth}      \NC \prm {wd} box         \NC the width of the inserts \NC \NR
+\NC \prm {insertdistance}   \NC skip                   \NC the space before the first instance (on a page) \NC \NR
+\NC \prm {insertmultiplier} \NC count                  \NC a factor that is used to calculate the height used \NC \NR
+\NC \prm {insertlimit}      \NC dimen                  \NC the maximum amount of space on a page to be taken \NC \NR
+\NC \prm {insertpenalty}    \NC \prm {insertpenalties} \NC the floating penalty (used when set) \NC \NR
+\NC \prm {insertmaxdepth}   \NC \prm {maxdepth}        \NC the maximum split depth (used when set) \NC \NR
+\NC \prm {insertstorage}    \NC                        \NC signals that the insert has to be stored for later \NC \NR
+\NC \prm {insertheight}     \NC \prm {ht} box          \NC the accumulated height of the inserts so far \NC \NR
+\NC \prm {insertdepth}      \NC \prm {dp} box          \NC the current depth of the inserts so far \NC \NR
+\NC \prm {insertwidth}      \NC \prm {wd} box          \NC the width of the inserts \NC \NR
 \LL
 \stoptabulate
 
@@ -73,8 +73,9 @@ column. If there are three columns, the first two will store inserts. Then when
 the last column is dealt with \prm {insertstoring} can be set to 2 and that will
 signal the builder that we will inject the inserts. In both cases, the value of
 this register will be set to zero so that it doesn't influence further
-processing. More details about these (probably experimental for a while) features
-can be found in documents that come with \CONTEXT.
+processing. You can use \prm {ifinsert} to check if am insert box is void. More
+details about these (probably experimental for a while) features can be found in
+documents that come with \CONTEXT.
 
 A limitation of inserts is that when they are buried too deep, a property they
 share with inserts, they become invisible This can be dealt with by the migration
@@ -100,10 +101,10 @@ number indicates a mark class.
 A problem with marks is that one cannot really reset them. Mark states are kept
 in the node lists and only periodically the state is snapshot into the global
 state variables. The \LUATEX\ engine can reset these global states with \prm
-{clearmarks} but that's only half a solution. In \LUAMETATEX\ we have
-\prm{flushmarks} which, like \prm {marks}, puts a node in the list that does a
-reset. This permits implementing controlled resets of specific marks at the cost
-of a possible interfering mode, but that can normally be dealt with rather well.
+{clearmarks} but that's only half a solution. In \LUAMETATEX\ we have \prm
+{flushmarks} which, like \prm {marks}, puts a node in the list that does a reset.
+This permits implementing controlled resets of specific marks at the cost of a
+possible interfering mode, but that can normally be dealt with rather well.
 
 Another problem with marks is that when they are buried too deep, a property they
 share with inserts, they become invisible. This can be dealt with by the
@@ -114,6 +115,33 @@ The \LUAMETATEX\ engine has some tracing built in that is enabled by setting \pr
 
 \stopsection
 
+\startsection[title={Adjusts}]
+
+The \prm {vadjust} primitive injects something in the vertical list after the
+lien where it ends up. In \PDFTEX\ the \type {pre} keyword was added so that one
+could force something before a previous line (actually this was something that we
+needed in \CONTEXT\ \MKII). The \LUAMETATEX\ engine also supports the \type {post}
+keyword.
+
+We support a few more keywords: \type {before} will prepend the adjustment to the
+already given one, and \type {after} will append it. The \type {index} keyword
+expects an integer and relate that to the current adjustment. This index is
+passed to an (optional) callback when the adjustment is finally moved to the
+vertical list. That move is actually delayed because like inserts and marks these
+(vertical) adjustments can migrate to the \quote {outer} vertical level.
+
+The main reason for the index having no influence on the order is that this
+primitive already could be used multiple times and order is determined by usage.
+\footnote {Under consideration is to let the callback mess with the flushing
+order.}
+
+The \LUAMETATEX\ engine has some tracing built in that is enabled by setting \prm
+{tracingadjusts} to a positive value. Currently there is not that much tracing
+which is why the value has to be at least 2 in order to be compatible with other
+(detailed) tracers.
+
+\stopsection
+
 \startsection[title={Migration}]
 
 A new primitive \prm {automigrationmode} can be used to let deeply burried marks
@@ -124,6 +152,7 @@ and inserts bubble up to the outer level.
 \TB
 \NC \the\markautomigrationcode   \NC migrate marks in the par builder \NC \NR
 \NC \the\insertautomigrationcode \NC migrate inserts in the par builder  \NC \NR
+\NC \the\adjustautomigrationcode \NC migrate adjusts in the par builder  \NC \NR
 \NC \the\preautomigrationcode    \NC migrate prebox material in the page builder \NC \NR
 \NC \the\postautomigrationcode   \NC migrate postbox material in the page builder \NC \NR
 \LL
@@ -143,6 +172,41 @@ behind.
 
 \stopsection
 
+\startsection[title={Local boxes}]
+
+As far as I know the \OMEGA/\ALEPH\ local box mechanism is mostly in those
+engines in order to support repetitive quotes. In \LUATEX\ this mechanism has
+been made more robust and in \LUAMETATEX\ it became more tightly integrated in
+the paragraph properties. In order for it to be a more generic useful feature it
+got more features. For instance it is a bit painful to manage with respect to
+grouping (which is a reason why it's not that much used). The most interesting
+property is that the dimensions are taking into account when a paragraph is
+broken into lines.
+
+There are three commands: \prm {localleftbox}, \prm {localrightbox} and the
+\LUAMETATEX\ specific \prm {localmiddlebox} which is basically a right box but
+when we pass these boxes to a callback they can be distinguished (we could have
+used the index but this was a cheap extra signal so we keep it).
+
+These commands take optional keywords. The \type {index} keyword has to be
+followed by an integer. This index determines the order which doesn't introduce a
+significant compatibility issue: local boxes are hardly used and originally have
+only one instance.
+
+The \type {par} keyword forces the box to be added to the current paragraph head.
+This permits setting them when a paragraph has already started. The
+implementation of these boxes is done via so called (local) paragraph nodes and
+there is one at the start of each paragraph.
+
+The \type {local} keyword tells this mechanism not to update the registers that
+keep these boxes. In that case a next paragraph will start fresh. The \type
+{keep} option will do the opposite and retain the box after a group ends.
+
+There commands: \prm {localleftboxbox}, \prm {localrightboxbox} and \prm
+{localmiddleboxbox} return a copy of the current related register content.
+
+\stopsection
+
 \stopchapter
 
 \stopcomponent
diff --git a/doc/context/sources/general/manuals/luametatex/luametatex-enhancements.tex b/doc/context/sources/general/manuals/luametatex/luametatex-enhancements.tex
index d8e0eeecf..9a03654d8 100644
--- a/doc/context/sources/general/manuals/luametatex/luametatex-enhancements.tex
+++ b/doc/context/sources/general/manuals/luametatex/luametatex-enhancements.tex
@@ -26,8 +26,8 @@ clone (a selection of) primitives with a different prefix, like this:
 \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}. When you clone all primitives you can also do this:
+specified by one or more keywords \type {tex}, \type {etex} or \type {luatex}.
+When you clone all primitives you can also do this:
 
 \starttyping
 \directlua { tex.enableprimitives('normal',true) }
@@ -89,6 +89,10 @@ still going for this new engine are:
     more access from the \LUA\ end to \TEX\ internals: a few more callbacks, more
     options, more robust interfaces, etc
 \stopitem
+\startitem
+    some mechanisms are very specific but can be made more generic (and powerful),
+    like inserts, marks, adjusts and local boxes
+\stopitem
 \stopitemize
 
 I realize that new primitives also can make some \TEX\ code look less threatening
@@ -110,7 +114,20 @@ in a certain way. In fact, I want users to be able to look at the code and
 understand it (apart from maybe a few real dirty low level helpers that are also
 dirty because of performance reasons). Just take this into account when reading on.
 
-And yes, there are still a few possibilities I want to explore \unknown
+And yes, there are still a few possibilities I want to explore \unknown\ some might
+show up temporary so don't be surprises. I'm also aware that some new features can
+have bugs or side effects that didn't show up in \CONTEXT, which after all is the
+benchmark and environment in which all this evolves.
+
+Over time, the other \TEX\ engines might have an occasional feature (primitive)
+added and it is very unlikely that \LUAMETATEX\ will follow up on that. First of
+all we have different internals but most of all because plenty of time went into
+considering what got added and what not, apart from the fact that we have
+callbacks. Decades of \TEX\ development never really have lead to an extensive
+wish list so there is no real need why there should be a demand on anything other
+than we offer here. If \TEX\ worked well for ages, it can as well do for more, so
+there is no need to cripple the code base simply in order to be compatible with
+other engines; \LUAMETATEX\ is already quite different anyway.
 
 \stopsubsection
 
@@ -299,8 +316,10 @@ as well as save and restore housekeeping). In \LUATEX\ the number was bumped to
 memory footprint reasonable, in \LUAMETATEX\ the number of languages, fonts and
 marks is limited. The size of some tables can be limited by configuration
 settings, so they can start out small and grow till configured maximum which is
-smaller than the absolute maximum. The following table shows all kind of defaults
-as reported by \typ {status.getconstants()}.
+smaller than the absolute maximum.
+
+The following table shows all kind of defaults as reported by \typ
+{status.getconstants()}.
 
 \startluacode
     context.starttabulate { "|T|r|" }
@@ -789,7 +808,7 @@ the currently active table, an error is raised.
 
 \startsection[title={Tokens, commands and strings}]
 
-\startsubsection[title={\prm {scantextokens} and \prm {tokenized}}]
+\startsubsection[title={\prm {scantextokens}, \prm {tokenized} and \prm {retokenized}}]
 
 \topicindex {tokens+scanning}
 
@@ -821,6 +840,9 @@ commands we also have this expandable command:
 \tokenized catcodetable <number> {...}
 \stopsyntax
 
+The \prm {retokenized} variant differs in that it doesn't check for a keyword and
+just used the current catcode regime.
+
 The \ETEX\ command \type {\tracingscantokens} has been dropped in the process as
 that was interwoven with the old code.
 
@@ -909,7 +931,7 @@ them are shown.
 
 \stopsubsection
 
-\startsubsection[title={\prm {alignmark}, \prm {aligntab}, \prm {aligncontent} and \prm {tabsize}}]
+\startsubsection[title={\prm {alignmark}, \prm {aligntab}, \prm {aligncontent}, \prm {tabsize} and \prm {everytab}}]
 
 The primitive \prm {alignmark} duplicates the functionality of \type {#} inside
 alignment preambles, while \prm {aligntab} duplicates the functionality of \type
@@ -939,6 +961,9 @@ column. By doing so one can avoid using a box in the preamble which, combined
 with the sparse tabskip features, is a bit easier on memory when you produce
 tables that span hundreds of pages and have a dozen columns.
 
+The \prm {everytab} complements the \prm {everycr} token register but is sort of
+experimental as it might become more selective and powerful some day.
+
 \stopsubsection
 
 \startsubsection[title={\prm {letcharcode}}]
@@ -1766,18 +1791,19 @@ tracing lines in the log and when bit~2 is set the input level is prepended. You
 can set both bits and get both numbers prepended. In \CONTEXT\ we default to
 the value~3, so you get prefixes like \type {3:4:} followed by a space.
 
-When \type {\tracingcommands} is larger than 3 the mode switch will be not be
+When \prm {tracingcommands} is larger than 3 the mode switch will be not be
 prefixed to the \type {{command}} but get its own \type {[line]}.
 
-When \type {\tracinglevels} variable is set to 3 the group and input level are
+When \prm {tracinglevels} variable is set to 3 the group and input level are
 shown, a value of 1 or 2 shows only one of them (in \CONTEXT\ we default to 3).
 
-When \type {\tracinghyphenation} is set to 1 duplicate patterns are reported (in
+When \prm {tracinghyphenation} is set to 1 duplicate patterns are reported (in
 \CONTEXT\ we default to that) and higher values will also show details about the
 \LUA\ hyphenation (exception) feedback loop discussed elsewhere.
 
-When set to 1 the \type {\tracingmath} variable triggers the reporting of the
-mode (inline or display) an mlist is processed.
+When set to 1 the \prm {tracingmath} variable triggers the reporting of the mode
+(inline or display) an mlist is processed. Other new tracing commands are
+discussed where the mechanisms that they relate to are introduced.
 
 Because in \LUATEX\ the saving and restoring of locally redefined macros and set
 variables is optimized a bit in order to prevent redundant stack usage, there
@@ -1786,8 +1812,9 @@ will be less tracing visible.
 Also, because we have a more extensive macro argument parser, a fast path (and
 less storage demands) for macros with no arguments, and flags that can be set for
 macros the way macros are traced can be different in details (we therefore have
-for instance \type {\meaningfull} and \type {\meaningless} as variants of \type
-{\meaning}).
+for instance \prm {meaningfull} (double l's indeed) and \prm {meaningless} as
+variants of \prm {meaning} as well as \prm {meaningasis} for more literal
+alternative).
 
 \stopsubsection
 
@@ -2530,6 +2557,90 @@ is often overkill and gives more noise in a trace.
 
 \stopsection
 
+\startsection[title=Expressions with \prm {numexpression}, \prm {dimexpression}]
+
+The \ETEX\ expression primitives are handy but have some limitations. Although
+the parsers have been rewritten in \LUAMETATEX\ and somewhat more efficient the
+only extension we have is support for an integer division with \type {:}. After
+experimenting for a while and pondering how to make \prm {dimexpr} and \prm
+{numexpr} more powerful I decided to come up with alternatives in order not to
+introduce incompatibilities.
+
+The \prm {numexpression} and \prm {dimexpression} primitives are equivalent but
+offer more. The first one operates in the integer domain and the second one
+assumes scaled values. Often the second one can act like the first when one
+serialized with \prm {number} in front. This is because when \TEX\ sees a
+symbolic reference to an integer or dimension it can treat them as it likes.
+
+The set of operators that we have to support is the following. Most have
+alternatives so that we can get around catcode issues.
+
+\starttabulate[||cT|cT|]
+\DB action    \BC symbol               \BC keyword \NC \NR
+\TB
+\NC add       \NC +                    \NC         \NC \NR
+\NC subtract  \NC -                    \NC         \NC \NR
+\NC multiply  \NC *                    \NC         \NC \NR
+\NC divide    \NC / :                  \NC         \NC \NR
+\NC mod       \NC \letterpercent       \NC mod     \NC \NR
+\NC band      \NC &                    \NC band    \NC \NR
+\NC bxor      \NC ^                    \NC bxor    \NC \NR
+\NC bor       \NC \letterbar \space v  \NC bor     \NC \NR
+\NC and       \NC &&                   \NC and     \NC \NR
+\NC or        \NC \letterbar\letterbar \NC or      \NC \NR
+\NC setbit    \NC <undecided>          \NC bset    \NC \NR
+\NC resetbit  \NC <undecided>          \NC breset  \NC \NR
+\NC left      \NC <<                   \NC         \NC \NR
+\NC right     \NC >>                   \NC         \NC \NR
+\NC less      \NC <                    \NC         \NC \NR
+\NC lessequal \NC <=                   \NC         \NC \NR
+\NC equal     \NC = ==                 \NC         \NC \NR
+\NC moreequal \NC >=                   \NC         \NC \NR
+\NC more      \NC >                    \NC         \NC \NR
+\NC unequal   \NC <> != \lettertilde = \NC         \NC \NR
+\NC not       \NC ! \lettertilde       \NC not     \NC \NR
+\LL
+\stoptabulate
+
+Here are some things that \prm {numexpr} is not suitable:
+
+\starttyping
+\scratchcounter = \numexpression
+    "00000 bor "00001 bor "00020 bor "00400 bor "08000 bor "F0000
+\relax
+
+\ifcase \numexpression
+    (\scratchcounterone > 5) && (\scratchcountertwo > 5)
+\relax yes\else nop\fi
+\stoptyping
+
+You can get an idea what the engines sees by setting \prm {tracingexpressions}
+to a value larger than zero. It shows the expression in rpn form.
+
+\starttyping
+\dimexpression 4pt * 2   + 6pt   \relax
+\dimexpression 2   * 4pt + 6pt   \relax
+\dimexpression 4pt * 2.5 + 6pt   \relax
+\dimexpression 2.5 * 4pt + 6pt   \relax
+\numexpression 2 * 4 + 6         \relax
+\numexpression (1 + 2) * (3 + 4) \relax
+\stoptyping
+
+The \prm {relax} is mandate simply because there are keywords involved so the
+parser needs to know where to stop scanning. It made no sense to be more clever
+and introduce fuzziness (so there is no room for exposing in|-|depth \TEX\
+insight and expertise here). In case you wonder: the difference in performance
+between the \ETEX\ expression mechanism and the more extended variant will
+normally not be noticed, probably because they both use a different approach and
+because the \ETEX\ variant also has been optimized. \footnote {I might add some
+features in the future.}
+
+The if|-|test shown before can be done using the new primitives \prm
+{ifdimexpression} and \prm {ifnumexpression} which are boolean tests with zero
+being \type {false}.
+
+\stopsection
+
 \startsection[title=Nodes]
 
 The \ETEX\ primitive \type {\lastnodetype} is not honest in reporting the
diff --git a/doc/context/sources/general/manuals/luametatex/luametatex-fonts.tex b/doc/context/sources/general/manuals/luametatex/luametatex-fonts.tex
index 8a049e694..83336ffd1 100644
--- a/doc/context/sources/general/manuals/luametatex/luametatex-fonts.tex
+++ b/doc/context/sources/general/manuals/luametatex/luametatex-fonts.tex
@@ -527,6 +527,50 @@ query a font dimensions with \prm {fontdimen} you get the raw value but with \pr
 
 \stopsubsection
 
+\startsubsection[title={\prm {fontspecdef}, \prm {fontspecid}, \prm {fontspecscale}, , \prm {fontspecxscale}, \prm {fontspecyscale}}]
+
+Because we have three scale related primitives \prm {glyphscale}, \prm
+{glyphxscale} and \prm {glyphyscale}, we also have a way to quickly set them all.
+
+\starttyping
+\fontspecdef \MyFontA 2 all 1000
+\fontspecdef \MyFontB \MyFontA xscale 1200
+\stoptyping
+
+The defined control sequence will set the font id (which is 2 in the case of
+\type {\MyFontA}) as well as the scale(s). Possible keywords are \type {scale},
+\type {xscale}, \type {yscale} and \type {all}. By default the values are 1000.
+Instead of an id an already defined specification can be given in which case we
+start from a copy. This mechanism is still somewhat experimental and might
+evolve. The main reason for introducing it is that it gives less tracing.
+
+Say that we have:
+
+\startbuffer
+\fontspecdef\MyFoo\font xscale 1200 \relax
+\stopbuffer
+
+\typebuffer \getbuffer
+
+The four properties of such a specification can then be queried as follows:
+
+\startbuffer
+[\the\fontspecid    \MyFoo]
+[\the\fontspecscale \MyFoo]
+[\the\fontspecxscale\MyFoo]
+[\the\fontspecyscale\MyFoo]
+\stopbuffer
+
+\typebuffer \getbuffer
+
+A font specification obeys grouping but is not a register. Like \prm {integerdef}
+and \prm {dimendef} it is just a control sequence with a special meaning.
+
+% \the\fontspecifiedsize\font
+%     \fontspecifiedname\font
+
+\stopsubsection
+
 \startsubsection[title={\prm {glyphxoffset}, \prm {glyphyoffset}}]
 
 These two parameters control the horizontal and vertical shift of glyphs with,
diff --git a/doc/context/sources/general/manuals/luametatex/luametatex-math.tex b/doc/context/sources/general/manuals/luametatex/luametatex-math.tex
index e147ff6ef..af34af92b 100644
--- a/doc/context/sources/general/manuals/luametatex/luametatex-math.tex
+++ b/doc/context/sources/general/manuals/luametatex/luametatex-math.tex
@@ -11,15 +11,26 @@
 \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
+respect to math. \footnote {This might no longer be true because we have more
+control options that define default behavior and also have a more extensive
+scaling model. Anyway, it should not look worse, and maybe even a bit better.}
+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.
 
+You might be surprised that we don't use all these new control features in
+\CONTEXT\ \LMTX\ but who knows what might happen because users drive it. The main
+reason for adding so much is that I decided it made more sense to be complete now
+than gradually add more and more. At some point we should be able to say \quote
+{This is it}. Also, when looking at these features, you need to keep in mind that
+when it comes to math \LATEX\ is the dominant macro package and it never needed
+these engine features, so most are probably just here for exploration purposes.
+
 \stopsection
 
 \startsection[title={Unicode math characters}]
@@ -135,7 +146,7 @@ sections:
 
 \startsection[title={Math styles}]
 
-\subsection{\prm {mathstyle}}
+\startsubsection[title={\prm {mathstyle}}]
 
 \topicindex {math+styles}
 
@@ -250,7 +261,9 @@ 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{\prm {Ustack}}
+\stopsubsection
+
+\startsubsection[title={\prm {Ustack}}]
 
 \topicindex {math+stacks}
 
@@ -267,7 +280,9 @@ $\Ustack {a \over b}$
 The \prm {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}
+\stopsubsection
+
+\startsubsection[title={The new \type {\cramped...style} commands}]
 
 \topicindex {math+styles}
 \topicindex {math+spacing}
@@ -356,11 +371,13 @@ Now we get:
 
 \start\getbuffer[setup,demo]\stop
 
+\stopsubsection
+
 \stopsection
 
 \startsection[title={Math parameter settings}]
 
-\subsection {Many new \tex {Umath*} primitives}
+\startsubsection[title={Many new \tex {Umath*} primitives}]
 
 \topicindex {math+parameters}
 
@@ -439,7 +456,9 @@ Each of the parameters in this section can be set by a command like this:
 they obey grouping, and you can use \type {\the\Umathquad\displaystyle} if
 needed.
 
-\subsection{Font|-|based math parameters}
+\stopsubsection
+
+\startsubsection[title={Font|-|based math parameters}]
 
 \topicindex {math+parameters}
 
@@ -577,11 +596,13 @@ 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.
 
+\stopsubsection
+
 \stopsection
 
 \startsection[title={Math spacing}]
 
-\subsection{Setting inline surrounding space with \prm {mathsurround} and \prm {mathsurroundskip}}
+\startsubsection[title={Setting inline surrounding space with \prm {mathsurround} and \prm {mathsurroundskip}}]
 
 \topicindex {math+spacing}
 
@@ -637,7 +658,9 @@ 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 \tex {Umath...spacing} commands}
+\stopsubsection
+
+\startsubsection[title={Pairwise spacing and \tex {Umath...spacing} commands}]
 
 \topicindex {math+spacing}
 
@@ -736,7 +759,9 @@ 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 \prm {frozen} settings with}
+\stopsubsection
+
+\startsubsection[title={Local \prm {frozen} settings with}]
 
 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
@@ -777,7 +802,9 @@ unprocessed math list. The result looks as follows:
 
 \blank \getbuffer \blank
 
-\subsection{Checking a state with \prm {ifmathparameter}}
+\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.
 When a parameter is unset its value has the maximum dimension value and you might
@@ -794,7 +821,9 @@ unexpected side effects. For that reason there is a convenient checker: \prm
 \LL
 \stoptabulate
 
-\subsection{Skips around display math and \prm {mathdisplayskipmode}}
+\stopsubsection
+
+\startsubsection[title={Skips around display math and \prm {mathdisplayskipmode}}]
 
 \topicindex {math+spacing}
 
@@ -814,7 +843,9 @@ to fully control spacing. Therefore \LUATEX\ comes with a new directive: \prm
 \LL
 \stoptabulate
 
-\subsection {Nolimit correction with \prm {mathnolimitsmode}}
+\stopsubsection
+
+\startsubsection[title={Nolimit correction with \prm {mathnolimitsmode}}]
 
 \topicindex {math+limits}
 
@@ -872,7 +903,7 @@ shifts to the left. A \prm {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 \prm {mathitalicsmode}}
+% \startsubsection[title={Controlling math italic mess with \prm {mathitalicsmode}}]
 %
 % \topicindex {math+italics}
 %
@@ -901,8 +932,12 @@ experimenting.
 %
 % This kind of parameters relate to the fact that italic correction in \OPENTYPE\
 % math is bound to fuzzy rules. So, control is the solution.
+%
+% \stopsubsection
 
-\subsection {Influencing script kerning with \prm {mathscriptboxmode}}
+\stopsubsection
+
+\startsubsection[title={Influencing script kerning with \prm {mathscriptboxmode}}]
 
 \topicindex {math+kerning}
 \topicindex {math+scripts}
@@ -990,7 +1025,9 @@ control over what one can turn on and off.
     \LL
 \stoptabulate
 
-\subsection{Forcing fixed scripts with \prm {mathscriptsmode}}
+\stopsubsection
+
+\startsubsection[title={Forcing fixed scripts with \prm {mathscriptsmode}}]
 
 We have three parameters that are used for this fixed anchoring:
 
@@ -1027,7 +1064,9 @@ formula.
 
 % if needed we can put the value in stylenodes but maybe more should go there
 
-\subsection{Penalties: \prm {mathpenaltiesmode}}
+\stopsubsection
+
+\startsubsection[title={Penalties: \prm {mathpenaltiesmode}}]
 
 \topicindex {math+penalties}
 
@@ -1051,7 +1090,9 @@ makes sense. As a bonus we also provide two extra penalties:
 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: \prm {matheqnogapstep}}
+\stopsubsection
+
+\startsubsection[title={Equation spacing: \prm {matheqnogapstep}}]
 
 By default \TEX\ will add one quad between the equation and the number. This is
 hard coded. A new primitive can control this:
@@ -1065,11 +1106,13 @@ 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.
 
+\stopsubsection
+
 \stopsection
 
 \startsection[title={Math constructs}]
 
-\subsection {Unscaled fences and \prm{mathdelimitersmode}}
+\startsubsection[title={Unscaled fences and \prm{mathdelimitersmode}}]
 
 \topicindex {math+fences}
 
@@ -1141,7 +1184,9 @@ In typeset form this looks like:
 
 \getbuffer
 
-\subsection[mathacc]{Accent handling with \prm {Umathaccent}}
+\stopsubsection
+
+\startsubsection[title={Accent handling with \prm {Umathaccent}},reference=mathacc]
 
 \topicindex {math+accents}
 
@@ -1190,7 +1235,9 @@ fraction only applies to the stepwise selected shapes and is mostly meant for th
 \type {overlay} location. It also works for the other locations but then it
 concerns the width.
 
-\subsection{Building radicals with \prm {Uradical} and \prm {Uroot}}
+\stopsubsection
+
+\startsubsection[title={Building radicals with \prm {Uradical} and \prm {Uroot}}]
 
 \topicindex {math+radicals}
 
@@ -1207,7 +1254,9 @@ The placement of the degree is controlled by the math parameters \prm
 {Umathradicaldegreeraise}. The degree will be typeset in \prm
 {scriptscriptstyle}.
 
-\subsection{Super- and subscripts}
+\stopsubsection
+
+\startsubsection[title={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}
@@ -1266,8 +1315,10 @@ next higher height and kern pair, or the highest one in the character (if there
 value high enough in the character), or simply zero (if the character has no math kern
 pairs at all).
 
-\subsection{Scripts on extensibles: \prm {Uunderdelimiter}, \prm {Uoverdelimiter},
-\prm {Udelimiterover}, \prm {Udelimiterunder} and \prm {Uhextensible}}
+\stopsubsection
+
+\startsubsection[title={Scripts on extensibles: \prm {Uunderdelimiter}, \prm {Uoverdelimiter},
+\prm {Udelimiterover}, \prm {Udelimiterunder} and \prm {Uhextensible}}]
 
 \topicindex {math+scripts}
 \topicindex {math+delimiters}
@@ -1329,7 +1380,9 @@ $\Uhextensible width 1pt middle 0 "2194$
 font metrics are involved we have a different code path for traditional fonts end
 \OPENTYPE\ fonts.
 
-\subsection{Fractions and the new \prm {Uskewed} and \prm {Uskewedwithdelims}}
+\stopsubsection
+
+\startsubsection[title={Fractions and the new \prm {Uskewed} and \prm {Uskewedwithdelims}}]
 
 \topicindex {math+fractions}
 
@@ -1436,7 +1489,9 @@ $\Uover style \scriptscriptstyle {1234} {5678} $\blank
 
 These render as: \getbuffer
 
-\subsection {Math styles: \prm {Ustyle}}
+\stopsubsection
+
+\startsubsection[title={Math styles: \prm {Ustyle}}]
 
 This primitive accepts a style identifier:
 
@@ -1466,7 +1521,9 @@ Like: \inlinebuffer . Values outside the valid range are ignored.
 There is an extra option \type {norule} that can be used to suppress the rule while
 keeping the spacing compatible.
 
-\subsection {Delimiters: \type{\Uleft}, \prm {Umiddle} and \prm {Uright}}
+\stopsubsection
+
+\startsubsection[title={Delimiters: \type{\Uleft}, \prm {Umiddle} and \prm {Uright}}]
 
 \topicindex {math+delimiters}
 
@@ -1507,7 +1564,9 @@ 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}}
+\stopsubsection
+
+\startsubsection[title={Accents: \type{\mathlimitsmode}}]
 
 \topicindex {math+accents}
 
@@ -1515,12 +1574,14 @@ 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.
 
+\stopsubsection
+
 \stopsection
 
 \startsection[title={Extracting values}]
 
-\subsection{Codes and using \prm {Umathcode}, \prm {Umathcharclass}, \prm
-{Umathcharfam} and \prm {Umathcharslot}}
+\startsubsection[title={Codes and using \prm {Umathcode}, \prm {Umathcharclass}, \prm
+{Umathcharfam} and \prm {Umathcharslot}}]
 
 \topicindex {math+codes}
 
@@ -1557,7 +1618,9 @@ do the following:
 \relax}
 \stoptyping
 
-\subsection {Last lines and \prm{predisplaygapfactor}}
+\stopsubsection
+
+\startsubsection[title={Last lines and \prm{predisplaygapfactor}}]
 
 \topicindex {math+last line}
 
@@ -1581,12 +1644,14 @@ get the length of the last line, the following will often work too:
 \relax}
 \stoptyping
 
+\stopsubsection
+
 \stopsection
 
 \startsection[title={Math mode}]
 
-\subsection {Verbose versions of single|-|character math commands like \prm {Usuperscript}
-and \prm {Usubscript}}
+\startsubsection[title={Verbose versions of single|-|character math commands like \prm {Usuperscript}
+and \prm {Usubscript}}]
 
 \topicindex {math+styles}
 
@@ -1613,7 +1678,9 @@ The \prm {Ustopmath} and \prm {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 \prm {Unosuperscript} and \prm {Unosubscript}}
+\stopsubsection
+
+\startsubsection[title={Script commands \prm {Unosuperscript} and \prm {Unosubscript}}]
 
 \topicindex {math+styles}
 \topicindex {math+scripts}
@@ -1634,7 +1701,9 @@ $
 
 results in \inlinebuffer[script].
 
-\subsection{Allowed math commands in non|-|math modes}
+\stopsubsection
+
+\startsubsection[title={Allowed math commands in non|-|math modes}]
 
 \topicindex {math+text}
 \topicindex {text+math}
@@ -1644,11 +1713,13 @@ the result of \prm {mathchardef} or \prm {Umathchardef} are also acceptable in
 the horizontal and vertical modes. In those cases, the \prm {textfont} from the
 requested math family is used.
 
+\stopsubsection
+
 \stopsection
 
 \startsection[title={Goodies}]
 
-\subsection {Flattening: \prm {mathflattenmode}}
+\startsubsection[title={Flattening: \prm {mathflattenmode}}]
 
 \topicindex {math+flattening}
 
@@ -1691,8 +1762,9 @@ mode parameter. The default value is~1.
 \LL
 \stoptabulate
 
+\stopsubsection
 
-\subsection {Less Tracing}
+\startsubsection[title={Less Tracing}]
 
 \topicindex {math+tracing}
 
@@ -1700,6 +1772,8 @@ 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.
 
+\stopsubsection
+
 \stopsection
 
 \startsection[title={Experiments}]
@@ -1708,7 +1782,7 @@ There are a couple of experimental features. They will stay but details might
 change, for instance more control over spacing. We just show some examples and
 let your imagination work it out. First we have prescripts:
 
-\subsection {Prescripts with \prm {Usuperprescript} and {Usubprescript}}
+\startsubsection[title={Prescripts with \prm {Usuperprescript} and {Usubprescript}}]
 
 \startbuffer
 \hbox{$
@@ -1753,7 +1827,9 @@ These more verbose triggers can be used to build interfaces:
 
 \blank \getbuffer \blank
 
-\subsection {Prescripts with \prm {Usuperprescript} and {Usubprescript}}
+\stopsubsection
+
+\startsubsection[title={Forcing classes with \prm {Umathclass}}]
 
 You can change the class of a math character on the fly:
 
@@ -1773,6 +1849,32 @@ Watch how the spacing changes:
 \getbuffer
 \stoplines
 
+\stopsubsection
+
+\startsubsection[title={Scaling spacing with \prm {Umathxscale} and  \prm {Umathyscale}}]
+
+These two primitives scale the horizontal and vertical scaling related
+parameters. They are set by style. There is no combined scaling primitive.
+
+\startbuffer
+$\Umathxscale\textstyle  800 a + b + x + d + e = f $\par
+$\Umathxscale\textstyle 1000 a + b + x + d + e = f $\par
+$\Umathxscale\textstyle 1200 a + b + x + d + e = f $\blank
+
+$\Umathyscale\textstyle  800 \sqrt[2]{x+1}$\quad
+$\Umathyscale\textstyle 1000 \sqrt[2]{x+1}$\quad
+$\Umathyscale\textstyle 1200 \sqrt[2]{x+1}$\blank
+\stopbuffer
+
+\typebuffer
+
+Normally only small deviations from 1000 make sense but here we want to show the
+effect and use a 20\percent\ scaling:
+
+\getbuffer
+
+\stopsubsection
+
 \stopsection
 
 \stopchapter