2018-07-02 14:46:00

1 files changed, 463 insertions, 456 deletions

diff --git a/doc/context/sources/general/manuals/luatex/luatex-math.tex b/doc/context/sources/general/manuals/luatex/luatex-math.tex
index 821ef010d..ad3ce2db3 100644
--- a/doc/context/sources/general/manuals/luatex/luatex-math.tex
+++ b/doc/context/sources/general/manuals/luatex/luatex-math.tex
@@ -6,6 +6,8 @@
 
 \startchapter[reference=math,title={Math}]
 
+\section {Traditional alongside \OPENTYPE}
+
 \topicindex {math}
 
 The handling of mathematics in \LUATEX\ differs quite a bit from how \TEX82 (and
@@ -17,6 +19,115 @@ 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.
 
+\section{Unicode math characters}
+
+\topicindex {math+\UNICODE}
+\topicindex {\UNICODE+math}
+
+Character handling is now extended up to the full \UNICODE\ range (the \type {\U}
+prefix), which is compatible with \XETEX.
+
+The math primitives from \TEX\ are kept as they are, except for the ones that
+convert from input to math commands: \type {mathcode}, and \type {delcode}. These
+two now allow for a 21-bit character argument on the left hand side of the equals
+sign.
+
+Some of the new \LUATEX\ primitives read more than one separate value. This is
+shown in the tables below by a plus sign.
+
+The input for such primitives would look like this:
+
+\starttyping
+\def\overbrace{\Umathaccent 0 1 "23DE }
+\stoptyping
+
+The altered \TEX82 primitives are:
+
+\starttabulate[|l|l|r|c|l|r|]
+\DB primitive       \BC min \BC max    \BC \kern 2em \BC min \BC max    \NC \NR
+\TB
+\NC \prm {mathcode} \NC 0   \NC 10FFFF \NC =         \NC 0   \NC 8000   \NC \NR
+\NC \prm {delcode}  \NC 0   \NC 10FFFF \NC =         \NC 0   \NC FFFFFF \NC \NR
+\LL
+\stoptabulate
+
+The unaltered ones are:
+
+\starttabulate[|l|l|r|]
+\DB primitive          \BC min \BC max     \NC \NR
+\TB
+\NC \prm {mathchardef} \NC 0   \NC    8000 \NC \NR
+\NC \prm {mathchar}    \NC 0   \NC    7FFF \NC \NR
+\NC \prm {mathaccent}  \NC 0   \NC    7FFF \NC \NR
+\NC \prm {delimiter}   \NC 0   \NC 7FFFFFF \NC \NR
+\NC \prm {radical}     \NC 0   \NC 7FFFFFF \NC \NR
+\LL
+\stoptabulate
+
+For practical reasons \prm {mathchardef} will silently accept values larger
+that \type {0x8000} and interpret it as \lpr {Umathcharnumdef}. This is needed
+to satisfy older macro packages.
+
+The following new primitives are compatible with \XETEX:
+
+% somewhat fuzzy:
+
+\starttabulate[|l|l|r|c|l|r|]
+\DB primitive                             \BC min       \BC max         \BC \kern 2em \BC min       \BC max         \NC \NR
+\TB
+\NC \lpr {Umathchardef}                   \NC 0+0+0     \NC 7+FF+10FFFF \NC           \NC           \NC             \NC \NR
+\NC \lpr {Umathcharnumdef}\rlap{\high{5}} \NC -80000000 \NC    7FFFFFFF \NC           \NC           \NC             \NC \NR
+\NC \lpr {Umathcode}                      \NC 0         \NC      10FFFF \NC =         \NC 0+0+0     \NC 7+FF+10FFFF \NC \NR
+\NC \lpr {Udelcode}                       \NC 0         \NC      10FFFF \NC =         \NC 0+0       \NC   FF+10FFFF \NC \NR
+\NC \lpr {Umathchar}                      \NC 0+0+0     \NC 7+FF+10FFFF \NC           \NC           \NC             \NC \NR
+\NC \lpr {Umathaccent}                    \NC 0+0+0     \NC 7+FF+10FFFF \NC           \NC           \NC             \NC \NR
+\NC \lpr {Udelimiter}                     \NC 0+0+0     \NC 7+FF+10FFFF \NC           \NC           \NC             \NC \NR
+\NC \lpr {Uradical}                       \NC 0+0       \NC   FF+10FFFF \NC           \NC           \NC             \NC \NR
+\NC \lpr {Umathcharnum}                   \NC -80000000 \NC    7FFFFFFF \NC           \NC           \NC             \NC \NR
+\NC \lpr {Umathcodenum}                   \NC 0         \NC      10FFFF \NC =         \NC -80000000 \NC    7FFFFFFF \NC \NR
+\NC \lpr {Udelcodenum}                    \NC 0         \NC      10FFFF \NC =         \NC -80000000 \NC    7FFFFFFF \NC \NR
+\LL
+\stoptabulate
+
+Specifications typically look like:
+
+\starttyping
+\Umathchardef\xx="1"0"456
+\Umathcode   123="1"0"789
+\stoptyping
+
+The new primitives that deal with delimiter|-|style objects do not set up a
+\quote {large family}. Selecting a suitable size for display purposes is expected
+to be dealt with by the font via the \lpr {Umathoperatorsize} parameter.
+
+For some of these primitives, all information is packed into a single signed
+integer. For the first two (\lpr {Umathcharnum} and \lpr {Umathcodenum}), the
+lowest 21 bits are the character code, the 3 bits above that represent the math
+class, and the family data is kept in the topmost bits. This means that the values
+for math families 128--255 are actually negative. For \lpr {Udelcodenum} there
+is no math class. The math family information is stored in the bits directly on
+top of the character code. Using these three commands is not as natural as using
+the two- and three|-|value commands, so unless you know exactly what you are
+doing and absolutely require the speedup resulting from the faster input
+scanning, it is better to use the verbose commands instead.
+
+The \lpr {Umathaccent} command accepts optional keywords to control various
+details regarding math accents. See \in {section} [mathacc] below for details.
+
+There are more new primitives and all of these will be explained in following
+sections:
+
+\starttabulate[|l|l|]
+\DB primitive                \BC value range (in hex) \NC \NR
+\TB
+\NC \lpr {Uroot}           \NC 0 + 0--FF + 10FFFF   \NC \NR
+\NC \lpr {Uoverdelimiter}  \NC 0 + 0--FF + 10FFFF   \NC \NR
+\NC \lpr {Uunderdelimiter} \NC 0 + 0--FF + 10FFFF   \NC \NR
+\NC \lpr {Udelimiterover}  \NC 0 + 0--FF + 10FFFF   \NC \NR
+\NC \lpr {Udelimiterunder} \NC 0 + 0--FF + 10FFFF   \NC \NR
+\LL
+\stoptabulate
+
 \section{Math styles}
 
 \subsection{\lpr {mathstyle}}
@@ -150,116 +261,7 @@ $\Ustack {a \over b}$
 The \lpr {Ustack} command will scan the next brace and start a new math group
 with the correct (numerator) math style.
 
-\section{Unicode math characters}
-
-\topicindex {math+\UNICODE}
-\topicindex {\UNICODE+math}
-
-Character handling is now extended up to the full \UNICODE\ range (the \type {\U}
-prefix), which is compatible with \XETEX.
-
-The math primitives from \TEX\ are kept as they are, except for the ones that
-convert from input to math commands: \type {mathcode}, and \type {delcode}. These
-two now allow for a 21-bit character argument on the left hand side of the equals
-sign.
-
-Some of the new \LUATEX\ primitives read more than one separate value. This is
-shown in the tables below by a plus sign.
-
-The input for such primitives would look like this:
-
-\starttyping
-\def\overbrace{\Umathaccent 0 1 "23DE }
-\stoptyping
-
-The altered \TEX82 primitives are:
-
-\starttabulate[|l|l|r|c|l|r|]
-\DB primitive       \BC min \BC max    \BC \kern 2em \BC min \BC max    \NC \NR
-\TB
-\NC \prm {mathcode} \NC 0   \NC 10FFFF \NC =         \NC 0   \NC 8000   \NC \NR
-\NC \prm {delcode}  \NC 0   \NC 10FFFF \NC =         \NC 0   \NC FFFFFF \NC \NR
-\LL
-\stoptabulate
-
-The unaltered ones are:
-
-\starttabulate[|l|l|r|]
-\DB primitive          \BC min \BC max     \NC \NR
-\TB
-\NC \prm {mathchardef} \NC 0   \NC    8000 \NC \NR
-\NC \prm {mathchar}    \NC 0   \NC    7FFF \NC \NR
-\NC \prm {mathaccent}  \NC 0   \NC    7FFF \NC \NR
-\NC \prm {delimiter}   \NC 0   \NC 7FFFFFF \NC \NR
-\NC \prm {radical}     \NC 0   \NC 7FFFFFF \NC \NR
-\LL
-\stoptabulate
-
-For practical reasons \prm {mathchardef} will silently accept values larger
-that \type {0x8000} and interpret it as \lpr {Umathcharnumdef}. This is needed
-to satisfy older macro packages.
-
-The following new primitives are compatible with \XETEX:
-
-% somewhat fuzzy:
-
-\starttabulate[|l|l|r|c|l|r|]
-\DB primitive                             \BC min       \BC max         \BC \kern 2em \BC min       \BC max         \NC \NR
-\TB
-\NC \lpr {Umathchardef}                   \NC 0+0+0     \NC 7+FF+10FFFF \NC           \NC           \NC             \NC \NR
-\NC \lpr {Umathcharnumdef}\rlap{\high{5}} \NC -80000000 \NC    7FFFFFFF \NC           \NC           \NC             \NC \NR
-\NC \lpr {Umathcode}                      \NC 0         \NC      10FFFF \NC =         \NC 0+0+0     \NC 7+FF+10FFFF \NC \NR
-\NC \lpr {Udelcode}                       \NC 0         \NC      10FFFF \NC =         \NC 0+0       \NC   FF+10FFFF \NC \NR
-\NC \lpr {Umathchar}                      \NC 0+0+0     \NC 7+FF+10FFFF \NC           \NC           \NC             \NC \NR
-\NC \lpr {Umathaccent}                    \NC 0+0+0     \NC 7+FF+10FFFF \NC           \NC           \NC             \NC \NR
-\NC \lpr {Udelimiter}                     \NC 0+0+0     \NC 7+FF+10FFFF \NC           \NC           \NC             \NC \NR
-\NC \lpr {Uradical}                       \NC 0+0       \NC   FF+10FFFF \NC           \NC           \NC             \NC \NR
-\NC \lpr {Umathcharnum}                   \NC -80000000 \NC    7FFFFFFF \NC           \NC           \NC             \NC \NR
-\NC \lpr {Umathcodenum}                   \NC 0         \NC      10FFFF \NC =         \NC -80000000 \NC    7FFFFFFF \NC \NR
-\NC \lpr {Udelcodenum}                    \NC 0         \NC      10FFFF \NC =         \NC -80000000 \NC    7FFFFFFF \NC \NR
-\LL
-\stoptabulate
-
-Specifications typically look like:
-
-\starttyping
-\Umathchardef\xx="1"0"456
-\Umathcode   123="1"0"789
-\stoptyping
-
-The new primitives that deal with delimiter|-|style objects do not set up a
-\quote {large family}. Selecting a suitable size for display purposes is expected
-to be dealt with by the font via the \lpr {Umathoperatorsize} parameter.
-
-For some of these primitives, all information is packed into a single signed
-integer. For the first two (\lpr {Umathcharnum} and \lpr {Umathcodenum}), the
-lowest 21 bits are the character code, the 3 bits above that represent the math
-class, and the family data is kept in the topmost bits. This means that the values
-for math families 128--255 are actually negative. For \lpr {Udelcodenum} there
-is no math class. The math family information is stored in the bits directly on
-top of the character code. Using these three commands is not as natural as using
-the two- and three|-|value commands, so unless you know exactly what you are
-doing and absolutely require the speedup resulting from the faster input
-scanning, it is better to use the verbose commands instead.
-
-The \lpr {Umathaccent} command accepts optional keywords to control various
-details regarding math accents. See \in {section} [mathacc] below for details.
-
-There are more new primitives and all of these will be explained in following
-sections:
-
-\starttabulate[|l|l|]
-\DB primitive                \BC value range (in hex) \NC \NR
-\TB
-\NC \lpr {Uroot}           \NC 0 + 0--FF + 10FFFF   \NC \NR
-\NC \lpr {Uoverdelimiter}  \NC 0 + 0--FF + 10FFFF   \NC \NR
-\NC \lpr {Uunderdelimiter} \NC 0 + 0--FF + 10FFFF   \NC \NR
-\NC \lpr {Udelimiterover}  \NC 0 + 0--FF + 10FFFF   \NC \NR
-\NC \lpr {Udelimiterunder} \NC 0 + 0--FF + 10FFFF   \NC \NR
-\LL
-\stoptabulate
-
-\section{Cramped math styles}
+\subsection{Cramped math styles}
 
 \topicindex {math+styles}
 \topicindex {math+spacing}
@@ -350,6 +352,8 @@ Now we get:
 
 \section{Math parameter settings}
 
+\subsection {Many new \lpr {Umath*} primitives}
+
 \topicindex {math+parameters}
 
 In \LUATEX, the font dimension parameters that \TEX\ used in math typesetting are
@@ -426,27 +430,7 @@ 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.
 
-\section{Skips around display math}
-
-\topicindex {math+spacing}
-
-The injection of \prm {abovedisplayskip} and \prm {belowdisplayskip} is not
-symmetrical. An above one is always inserted, also when zero, but the below is
-only inserted when larger than zero. Especially the latter makes it sometimes hard
-to fully control spacing. Therefore \LUATEX\ comes with a new directive: \lpr
-{mathdisplayskipmode}. The following values apply:
-
-\starttabulate[|c|l|]
-\DB value  \BC meaning \NC \NR
-\TB
-\NC 0 \NC normal \TEX\ behaviour \NC \NR
-\NC 1 \NC always (same as 0) \NC \NR
-\NC 2 \NC only when not zero \NC \NR
-\NC 3 \NC never, not even when not zero \NC \NR
-\LL
-\stoptabulate
-
-\section{Font|-|based Math Parameters}
+\subsection{Font|-|based math parameters}
 
 \topicindex {math+parameters}
 
@@ -584,7 +568,185 @@ 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.
 
-\section {Nolimit correction}
+\section {Math spacing}
+
+\subsection{Inline surrounding space}
+
+\topicindex {math+spacing}
+
+Inline math is surrounded by (optional) \prm {mathsurround} spacing but that is a fixed
+dimension. There is now an additional parameter \lpr {mathsurroundskip}. When set to a
+non|-|zero value (or zero with some stretch or shrink) this parameter will replace
+\prm {mathsurround}. By using an additional parameter instead of changing the nature
+of \prm {mathsurround}, we can remain compatible. In the meantime a bit more
+control has been added via \lpr {mathsurroundmode}. This directive can take 6 values
+with zero being the default behaviour.
+
+\start
+
+\def\OneLiner#1#2%
+  {\NC \type{#1}
+   \NC \dontleavehmode\inframed[align=normal,offset=0pt,frame=off]{\mathsurroundmode#1\relax\hsize 100pt   x$x$x}
+   \NC \dontleavehmode\inframed[align=normal,offset=0pt,frame=off]{\mathsurroundmode#1\relax\hsize 100pt x $x$ x}
+   \NC #2
+   \NC \NR}
+
+\startbuffer
+\mathsurround    10pt
+\mathsurroundskip20pt
+\stopbuffer
+
+\typebuffer \getbuffer
+
+\starttabulate[|c|c|c|pl|]
+\DB mode \BC x\$x\$x \BC x \$x\$ x \BC effect \NC \NR
+\TB
+\OneLiner{0}{obey \prm {mathsurround} when \lpr {mathsurroundskip} is 0pt}
+\OneLiner{1}{only add skip to the left}
+\OneLiner{2}{only add skip to the right}
+\OneLiner{3}{add skip to the left and right}
+\OneLiner{4}{ignore the skip setting, obey \prm {mathsurround}}
+\OneLiner{5}{disable all spacing around math}
+\OneLiner{6}{only apply \lpr {mathsurroundskip} when also spacing}
+\OneLiner{7}{only apply \lpr {mathsurroundskip} when no spacing}
+\LL
+\stoptabulate
+
+\stop
+
+Method six omits the surround glue when there is (x)spacing glue present while
+method seven does the opposite, the glue is only applied when there is (x)space
+glue present too. Anything more fancy, like checking the begining or end of a
+paragraph (or edges of a box) would not be robust anyway. If you want that you
+can write a callback that runs over a list and analyzes a paragraph. Actually, in
+that case you could also inject glue (or set the properties of a math node)
+explicitly. So, these modes are in practice mostly useful for special purposes
+and experiments (they originate in a tracker item). Keep in mind that this glue
+is part of the math node and not always treated as normal glue: it travels with
+the begin and end math nodes. Also, method 6 and 7 will zero the skip related
+fields in a node when applicable in the first occasion that checks them
+(linebreaking or packaging).
+
+\subsection{Pairwise spacing}
+
+\topicindex {math+spacing}
+
+Besides the parameters mentioned in the previous sections, there are also 64 new
+primitives to control the math spacing table (as explained in Chapter~18 of the
+\TEX book). The primitive names are a simple matter of combining two math atom
+types, but for completeness' sake, here is the whole list:
+
+\starttwocolumns
+\startlines
+\lpr {Umathordordspacing}
+\lpr {Umathordopspacing}
+\lpr {Umathordbinspacing}
+\lpr {Umathordrelspacing}
+\lpr {Umathordopenspacing}
+\lpr {Umathordclosespacing}
+\lpr {Umathordpunctspacing}
+\lpr {Umathordinnerspacing}
+\lpr {Umathopordspacing}
+\lpr {Umathopopspacing}
+\lpr {Umathopbinspacing}
+\lpr {Umathoprelspacing}
+\lpr {Umathopopenspacing}
+\lpr {Umathopclosespacing}
+\lpr {Umathoppunctspacing}
+\lpr {Umathopinnerspacing}
+\lpr {Umathbinordspacing}
+\lpr {Umathbinopspacing}
+\lpr {Umathbinbinspacing}
+\lpr {Umathbinrelspacing}
+\lpr {Umathbinopenspacing}
+\lpr {Umathbinclosespacing}
+\lpr {Umathbinpunctspacing}
+\lpr {Umathbininnerspacing}
+\lpr {Umathrelordspacing}
+\lpr {Umathrelopspacing}
+\lpr {Umathrelbinspacing}
+\lpr {Umathrelrelspacing}
+\lpr {Umathrelopenspacing}
+\lpr {Umathrelclosespacing}
+\lpr {Umathrelpunctspacing}
+\lpr {Umathrelinnerspacing}
+\lpr {Umathopenordspacing}
+\lpr {Umathopenopspacing}
+\lpr {Umathopenbinspacing}
+\lpr {Umathopenrelspacing}
+\lpr {Umathopenopenspacing}
+\lpr {Umathopenclosespacing}
+\lpr {Umathopenpunctspacing}
+\lpr {Umathopeninnerspacing}
+\lpr {Umathcloseordspacing}
+\lpr {Umathcloseopspacing}
+\lpr {Umathclosebinspacing}
+\lpr {Umathcloserelspacing}
+\lpr {Umathcloseopenspacing}
+\lpr {Umathcloseclosespacing}
+\lpr {Umathclosepunctspacing}
+\lpr {Umathcloseinnerspacing}
+\lpr {Umathpunctordspacing}
+\lpr {Umathpunctopspacing}
+\lpr {Umathpunctbinspacing}
+\lpr {Umathpunctrelspacing}
+\lpr {Umathpunctopenspacing}
+\lpr {Umathpunctclosespacing}
+\lpr {Umathpunctpunctspacing}
+\lpr {Umathpunctinnerspacing}
+\lpr {Umathinnerordspacing}
+\lpr {Umathinneropspacing}
+\lpr {Umathinnerbinspacing}
+\lpr {Umathinnerrelspacing}
+\lpr {Umathinneropenspacing}
+\lpr {Umathinnerclosespacing}
+\lpr {Umathinnerpunctspacing}
+\lpr {Umathinnerinnerspacing}
+\stoplines
+\stoptwocolumns
+
+These parameters are of type \prm {muskip}, so setting a parameter can be done
+like this:
+
+\starttyping
+\Umathopordspacing\displaystyle=4mu plus 2mu
+\stoptyping
+
+They are all initialized by \type {initex} to the values mentioned in the table
+in Chapter~18 of the \TEX book.
+
+Note 1: for ease of use as well as for backward compatibility, \prm {thinmuskip},
+\prm {medmuskip} and \prm {thickmuskip} are treated specially. In their case a
+pointer to the corresponding internal parameter is saved, not the actual \prm
+{muskip} value. This means that any later changes to one of these three
+parameters will be taken into account.
+
+Note 2: Careful readers will realise that there are also primitives for the items
+marked \type {*} in the \TEX book. These will not actually be used as those
+combinations of atoms cannot actually happen, but it seemed better not to break
+orthogonality. They are initialized to zero.
+
+\subsection{Skips around display math}
+
+\topicindex {math+spacing}
+
+The injection of \prm {abovedisplayskip} and \prm {belowdisplayskip} is not
+symmetrical. An above one is always inserted, also when zero, but the below is
+only inserted when larger than zero. Especially the latter makes it sometimes hard
+to fully control spacing. Therefore \LUATEX\ comes with a new directive: \lpr
+{mathdisplayskipmode}. The following values apply:
+
+\starttabulate[|c|l|]
+\DB value  \BC meaning \NC \NR
+\TB
+\NC 0 \NC normal \TEX\ behaviour \NC \NR
+\NC 1 \NC always (same as 0) \NC \NR
+\NC 2 \NC only when not zero \NC \NR
+\NC 3 \NC never, not even when not zero \NC \NR
+\LL
+\stoptabulate
+
+\subsection {Nolimit correction}
 
 \topicindex {math+limits}
 
@@ -642,7 +804,7 @@ shifts to the left. A \lpr {mathnolimitsmode} larger that 15 is considered to
 be a factor for the subscript correction. This feature can be handy when
 experimenting.
 
-\section {Math italic mess}
+\subsection {Math italic mess}
 
 \topicindex {math+italics}
 
@@ -672,7 +834,7 @@ example.
 This kind of parameters relate to the fact that italic correction in \OPENTYPE\
 math is bound to fuzzy rules. So, control is the solution.
 
-\section {Script and kerning}
+\subsection {Script and kerning}
 
 \topicindex {math+kerning}
 \topicindex {math+scripts}
@@ -760,7 +922,84 @@ control over what one can turn on and off.
     \LL
 \stoptabulate
 
-\section {Unscaled fences}
+\subsection{Fixed scripts}
+
+We have three parameters that are used for this fixed anchoring:
+
+\starttabulate[|c|l|]
+\DB parameter \BC register \NC \NR
+\NC $d$ \NC \lpr {Umathsubshiftdown}    \NC \NR
+\NC $u$ \NC \lpr {Umathsupshiftup}      \NC \NR
+\NC $s$ \NC \lpr {Umathsubsupshiftdown} \NC \NR
+\LL
+\stoptabulate
+
+When we set \lpr {mathscriptsmode} to a value other than zero these are used
+for calculating fixed positions. This is something that is needed for instance
+for chemistry. You can manipulate the mentioned variables to achieve different
+effects.
+
+\def\SampleMath#1%
+  {$\mathscriptsmode#1\mathupright CH_2 + CH^+_2 + CH^2_2$}
+
+\starttabulate[|c|c|c|p|]
+\DB mode \BC down          \BC up            \BC example        \NC \NR
+\TB
+\NC 0    \NC dynamic       \NC dynamic       \NC \SampleMath{0} \NC \NR
+\NC 1    \NC $d$           \NC $u$           \NC \SampleMath{1} \NC \NR
+\NC 2    \NC $s$           \NC $u$           \NC \SampleMath{2} \NC \NR
+\NC 3    \NC $s$           \NC $u + s - d$   \NC \SampleMath{3} \NC \NR
+\NC 4    \NC $d + (s-d)/2$ \NC $u + (s-d)/2$ \NC \SampleMath{4} \NC \NR
+\NC 5    \NC $d$           \NC $u + s - d$   \NC \SampleMath{5} \NC \NR
+\LL
+\stoptabulate
+
+The value of this parameter obeys grouping but applies to the whole current
+formula.
+
+% if needed we can put the value in stylenodes but maybe more should go there
+
+\subsection{Penalties: \lpr {mathpenaltiesmode}}
+
+\topicindex {math+penalties}
+
+Only in inline math penalties will be added in a math list. You can force
+penalties (also in display math) by setting:
+
+\starttyping
+\mathpenaltiesmode = 1
+\stoptyping
+
+This primnitive is not really needed in \LUATEX\ because you can use the callback
+\cbk {mlist_to_hlist} to force penalties by just calling the regular routine
+with forced penalties. However, as part of opening up and control this primitive
+makes sense. As a bonus we also provide two extra penalties:
+
+\starttyping
+\prebinoppenalty = -100 % example value
+\prerelpenalty   =  900 % example value
+\stoptyping
+
+They default to inifinite which signals that they don't need to be inserted. When
+set they are injected before a binop or rel noad. This is an experimental feature.
+
+\subsection{Equation spacing: \lpr {matheqnogapstep}}
+
+By default \TEX\ will add one quad between the equation and the number. This is
+hard coded. A new primitive can control this:
+
+\startsyntax
+\matheqnogapstep = 1000
+\stopsyntax
+
+Because a math quad from the math text font is used instead of a dimension, we
+use a step to control the size. A value of zero will suppress the gap. The step
+is divided by 1000 which is the usual way to mimmick floating point factors in
+\TEX.
+
+\section {Math constructs}
+
+\subsection {Unscaled fences}
 
 \topicindex {math+fences}
 
@@ -806,106 +1045,7 @@ with in the engine). The full list of flags is given in the next table:
 
 The effect can depend on the font (and for Cambria one can use for instance \type {"16}).
 
-\section {Math spacing setting}
-
-\topicindex {math+spacing}
-
-Besides the parameters mentioned in the previous sections, there are also 64 new
-primitives to control the math spacing table (as explained in Chapter~18 of the
-\TEX book). The primitive names are a simple matter of combining two math atom
-types, but for completeness' sake, here is the whole list:
-
-\starttwocolumns
-\startlines
-\lpr {Umathordordspacing}
-\lpr {Umathordopspacing}
-\lpr {Umathordbinspacing}
-\lpr {Umathordrelspacing}
-\lpr {Umathordopenspacing}
-\lpr {Umathordclosespacing}
-\lpr {Umathordpunctspacing}
-\lpr {Umathordinnerspacing}
-\lpr {Umathopordspacing}
-\lpr {Umathopopspacing}
-\lpr {Umathopbinspacing}
-\lpr {Umathoprelspacing}
-\lpr {Umathopopenspacing}
-\lpr {Umathopclosespacing}
-\lpr {Umathoppunctspacing}
-\lpr {Umathopinnerspacing}
-\lpr {Umathbinordspacing}
-\lpr {Umathbinopspacing}
-\lpr {Umathbinbinspacing}
-\lpr {Umathbinrelspacing}
-\lpr {Umathbinopenspacing}
-\lpr {Umathbinclosespacing}
-\lpr {Umathbinpunctspacing}
-\lpr {Umathbininnerspacing}
-\lpr {Umathrelordspacing}
-\lpr {Umathrelopspacing}
-\lpr {Umathrelbinspacing}
-\lpr {Umathrelrelspacing}
-\lpr {Umathrelopenspacing}
-\lpr {Umathrelclosespacing}
-\lpr {Umathrelpunctspacing}
-\lpr {Umathrelinnerspacing}
-\lpr {Umathopenordspacing}
-\lpr {Umathopenopspacing}
-\lpr {Umathopenbinspacing}
-\lpr {Umathopenrelspacing}
-\lpr {Umathopenopenspacing}
-\lpr {Umathopenclosespacing}
-\lpr {Umathopenpunctspacing}
-\lpr {Umathopeninnerspacing}
-\lpr {Umathcloseordspacing}
-\lpr {Umathcloseopspacing}
-\lpr {Umathclosebinspacing}
-\lpr {Umathcloserelspacing}
-\lpr {Umathcloseopenspacing}
-\lpr {Umathcloseclosespacing}
-\lpr {Umathclosepunctspacing}
-\lpr {Umathcloseinnerspacing}
-\lpr {Umathpunctordspacing}
-\lpr {Umathpunctopspacing}
-\lpr {Umathpunctbinspacing}
-\lpr {Umathpunctrelspacing}
-\lpr {Umathpunctopenspacing}
-\lpr {Umathpunctclosespacing}
-\lpr {Umathpunctpunctspacing}
-\lpr {Umathpunctinnerspacing}
-\lpr {Umathinnerordspacing}
-\lpr {Umathinneropspacing}
-\lpr {Umathinnerbinspacing}
-\lpr {Umathinnerrelspacing}
-\lpr {Umathinneropenspacing}
-\lpr {Umathinnerclosespacing}
-\lpr {Umathinnerpunctspacing}
-\lpr {Umathinnerinnerspacing}
-\stoplines
-\stoptwocolumns
-
-These parameters are of type \prm {muskip}, so setting a parameter can be done
-like this:
-
-\starttyping
-\Umathopordspacing\displaystyle=4mu plus 2mu
-\stoptyping
-
-They are all initialized by \type {initex} to the values mentioned in the table
-in Chapter~18 of the \TEX book.
-
-Note 1: for ease of use as well as for backward compatibility, \prm {thinmuskip},
-\prm {medmuskip} and \prm {thickmuskip} are treated specially. In their case a
-pointer to the corresponding internal parameter is saved, not the actual \prm
-{muskip} value. This means that any later changes to one of these three
-parameters will be taken into account.
-
-Note 2: Careful readers will realise that there are also primitives for the items
-marked \type {*} in the \TEX book. These will not actually be used as those
-combinations of atoms cannot actually happen, but it seemed better not to break
-orthogonality. They are initialized to zero.
-
-\section[mathacc]{Math accent handling}
+\subsection[mathacc]{Accent handling}
 
 \topicindex {math+accents}
 
@@ -954,7 +1094,7 @@ 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.
 
-\section{Math root extension}
+\subsection{Radical extensions}
 
 \topicindex {math+radicals}
 
@@ -971,7 +1111,7 @@ The placement of the degree is controlled by the math parameters \lpr
 {Umathradicaldegreeraise}. The degree will be typeset in \prm
 {scriptscriptstyle}.
 
-\section{Math kerning in super- and subscripts}
+\subsection{Super- and subscripts}
 
 The character fields in a \LUA|-|loaded \OPENTYPE\ math font can have a \quote
 {mathkern} table. The format of this table is the same as the \quote {mathkern}
@@ -1030,7 +1170,7 @@ 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).
 
-\section{Scripts on horizontally extensible items like arrows}
+\subsection{Scripts on extensibles}
 
 \topicindex {math+scripts}
 \topicindex {math+delimiters}
@@ -1092,38 +1232,7 @@ $\Uhextensible width 1pt middle 0 "2194$
 font metrics are involved we have a different code path for traditional fonts end
 \OPENTYPE\ fonts.
 
-\section {Extracting values}
-
-\topicindex {math+codes}
-
-You can extract the components of a math character. Say that we have defined:
-
-\starttyping
-\Umathcode 1 2 3 4
-\stoptyping
-
-then
-
-\starttyping
-[\Umathcharclass1] [\Umathcharfam1] [\Umathcharslot1]
-\stoptyping
-
-will return:
-
-\starttyping
-[2] [3] [4]
-\stoptyping
-
-These commands are provides as convenience. Before they come available you could
-do the following:
-
-\starttyping
-\def\Umathcharclass{\directlua{tex.print(tex.getmathcode(token.scan_int())[1])}}
-\def\Umathcharfam  {\directlua{tex.print(tex.getmathcode(token.scan_int())[2])}}
-\def\Umathcharslot {\directlua{tex.print(tex.getmathcode(token.scan_int())[3])}}
-\stoptyping
-
-\section{fractions}
+\subsection{Fractions}
 
 \topicindex {math+fractions}
 
@@ -1187,7 +1296,81 @@ For Latin Modern the result looks as follows:
     \stoptabulate
 \stop
 
-\section {Last lines}
+\subsection {Delimiters: \type{\Uleft}, \prm {Umiddle} and \prm {Uright}}
+
+\topicindex {math+delimiters}
+
+Normally you will force delimiters to certain sizes by putting an empty box or
+rule next to it. The resulting delimiter will either be a character from the
+stepwise size range or an extensible. The latter can be quite differently
+positioned than the characters as it depends on the fit as well as the fact if
+the used characters in the font have depth or height. Commands like (plain \TEX
+s) \type {\big} need use this feature. In \LUATEX\ we provide a bit more control
+by three variants that support optional parameters \type {height}, \type {depth}
+and \type {axis}. The following example uses this:
+
+\startbuffer
+\Uleft   height 30pt depth 10pt      \Udelimiter "0 "0 "000028
+\quad x\quad
+\Umiddle height 40pt depth 15pt      \Udelimiter "0 "0 "002016
+\quad x\quad
+\Uright  height 30pt depth 10pt      \Udelimiter "0 "0 "000029
+\quad \quad \quad
+\Uleft   height 30pt depth 10pt axis \Udelimiter "0 "0 "000028
+\quad x\quad
+\Umiddle height 40pt depth 15pt axis \Udelimiter "0 "0 "002016
+\quad x\quad
+\Uright  height 30pt depth 10pt axis \Udelimiter "0 "0 "000029
+\stopbuffer
+
+\typebuffer
+
+\startlinecorrection
+\ruledhbox{\mathematics{\getbuffer}}
+\stoplinecorrection
+
+The keyword \type {exact} can be used as directive that the real dimensions
+should be applied when the criteria can't be met which can happen when we're
+still stepping through the successively larger variants. When no dimensions are
+given the \type {noaxis} command can be used to prevent shifting over the axis.
+
+You can influence the final class with the keyword \type {class} which will
+influence the spacing. The numbers are the same as for character classes.
+
+\section {Extracting values}
+
+\subsection{Codes}
+
+\topicindex {math+codes}
+
+You can extract the components of a math character. Say that we have defined:
+
+\starttyping
+\Umathcode 1 2 3 4
+\stoptyping
+
+then
+
+\starttyping
+[\Umathcharclass1] [\Umathcharfam1] [\Umathcharslot1]
+\stoptyping
+
+will return:
+
+\starttyping
+[2] [3] [4]
+\stoptyping
+
+These commands are provides as convenience. Before they come available you could
+do the following:
+
+\starttyping
+\def\Umathcharclass{\directlua{tex.print(tex.getmathcode(token.scan_int())[1])}}
+\def\Umathcharfam  {\directlua{tex.print(tex.getmathcode(token.scan_int())[2])}}
+\def\Umathcharslot {\directlua{tex.print(tex.getmathcode(token.scan_int())[3])}}
+\stoptyping
+
+\subsection {Last lines}
 
 \topicindex {math+last line}
 
@@ -1211,7 +1394,7 @@ get the length of the last line, the following will often work too:
 \relax}
 \stoptyping
 
-\section {Other Math changes}
+\section {Math mode}
 
 \subsection {Verbose versions of single|-|character math commands}
 
@@ -1271,63 +1454,6 @@ the result of \prm {mathchardef} or \lpr {Umathchardef} are also acceptable in
 the horizontal and vertical modes. In those cases, the \prm {textfont} from the
 requested math family is used.
 
-\section{Math surrounding skips}
-
-\topicindex {math+spacing}
-
-Inline math is surrounded by (optional) \prm {mathsurround} spacing but that is a fixed
-dimension. There is now an additional parameter \lpr {mathsurroundskip}. When set to a
-non|-|zero value (or zero with some stretch or shrink) this parameter will replace
-\prm {mathsurround}. By using an additional parameter instead of changing the nature
-of \prm {mathsurround}, we can remain compatible. In the meantime a bit more
-control has been added via \lpr {mathsurroundmode}. This directive can take 6 values
-with zero being the default behaviour.
-
-\start
-
-\def\OneLiner#1#2%
-  {\NC \type{#1}
-   \NC \dontleavehmode\inframed[align=normal,offset=0pt,frame=off]{\mathsurroundmode#1\relax\hsize 100pt   x$x$x}
-   \NC \dontleavehmode\inframed[align=normal,offset=0pt,frame=off]{\mathsurroundmode#1\relax\hsize 100pt x $x$ x}
-   \NC #2
-   \NC \NR}
-
-\startbuffer
-\mathsurround    10pt
-\mathsurroundskip20pt
-\stopbuffer
-
-\typebuffer \getbuffer
-
-\starttabulate[|c|c|c|pl|]
-\DB mode \BC x\$x\$x \BC x \$x\$ x \BC effect \NC \NR
-\TB
-\OneLiner{0}{obey \prm {mathsurround} when \lpr {mathsurroundskip} is 0pt}
-\OneLiner{1}{only add skip to the left}
-\OneLiner{2}{only add skip to the right}
-\OneLiner{3}{add skip to the left and right}
-\OneLiner{4}{ignore the skip setting, obey \prm {mathsurround}}
-\OneLiner{5}{disable all spacing around math}
-\OneLiner{6}{only apply \lpr {mathsurroundskip} when also spacing}
-\OneLiner{7}{only apply \lpr {mathsurroundskip} when no spacing}
-\LL
-\stoptabulate
-
-\stop
-
-Method six omits the surround glue when there is (x)spacing glue present while
-method seven does the opposite, the glue is only applied when there is (x)space
-glue present too. Anything more fancy, like checking the begining or end of a
-paragraph (or edges of a box) would not be robust anyway. If you want that you
-can write a callback that runs over a list and analyzes a paragraph. Actually, in
-that case you could also inject glue (or set the properties of a math node)
-explicitly. So, these modes are in practice mostly useful for special purposes
-and experiments (they originate in a tracker item). Keep in mind that this glue
-is part of the math node and not always treated as normal glue: it travels with
-the begin and end math nodes. Also, method 6 and 7 will zero the skip related
-fields in a node when applicable in the first occasion that checks them
-(linebreaking or packaging).
-
 % \section{Math todo}
 %
 % The following items are still todo.
@@ -1350,121 +1476,7 @@ fields in a node when applicable in the first occasion that checks them
 % \stopitem
 % \stopitemize
 
-\subsection {Delimiters: \type{\Uleft}, \prm {Umiddle} and \prm {Uright}}
-
-\topicindex {math+delimiters}
-
-Normally you will force delimiters to certain sizes by putting an empty box or
-rule next to it. The resulting delimiter will either be a character from the
-stepwise size range or an extensible. The latter can be quite differently
-positioned than the characters as it depends on the fit as well as the fact if
-the used characters in the font have depth or height. Commands like (plain \TEX
-s) \type {\big} need use this feature. In \LUATEX\ we provide a bit more control
-by three variants that support optional parameters \type {height}, \type {depth}
-and \type {axis}. The following example uses this:
-
-\startbuffer
-\Uleft   height 30pt depth 10pt      \Udelimiter "0 "0 "000028
-\quad x\quad
-\Umiddle height 40pt depth 15pt      \Udelimiter "0 "0 "002016
-\quad x\quad
-\Uright  height 30pt depth 10pt      \Udelimiter "0 "0 "000029
-\quad \quad \quad
-\Uleft   height 30pt depth 10pt axis \Udelimiter "0 "0 "000028
-\quad x\quad
-\Umiddle height 40pt depth 15pt axis \Udelimiter "0 "0 "002016
-\quad x\quad
-\Uright  height 30pt depth 10pt axis \Udelimiter "0 "0 "000029
-\stopbuffer
-
-\typebuffer
-
-\startlinecorrection
-\ruledhbox{\mathematics{\getbuffer}}
-\stoplinecorrection
-
-The keyword \type {exact} can be used as directive that the real dimensions
-should be applied when the criteria can't be met which can happen when we're
-still stepping through the successively larger variants. When no dimensions are
-given the \type {noaxis} command can be used to prevent shifting over the axis.
-
-You can influence the final class with the keyword \type {class} which will
-influence the spacing. The numbers are the same as for character classes.
-
-\subsection{Fixed scripts}
-
-We have three parameters that are used for this fixed anchoring:
-
-\starttabulate[|c|l|]
-\DB parameter \BC register \NC \NR
-\NC $d$ \NC \lpr {Umathsubshiftdown}    \NC \NR
-\NC $u$ \NC \lpr {Umathsupshiftup}      \NC \NR
-\NC $s$ \NC \lpr {Umathsubsupshiftdown} \NC \NR
-\LL
-\stoptabulate
-
-When we set \lpr {mathscriptsmode} to a value other than zero these are used
-for calculating fixed positions. This is something that is needed for instance
-for chemistry. You can manipulate the mentioned variables to achieve different
-effects.
-
-\def\SampleMath#1%
-  {$\mathscriptsmode#1\mathupright CH_2 + CH^+_2 + CH^2_2$}
-
-\starttabulate[|c|c|c|p|]
-\DB mode \BC down          \BC up            \BC example        \NC \NR
-\TB
-\NC 0    \NC dynamic       \NC dynamic       \NC \SampleMath{0} \NC \NR
-\NC 1    \NC $d$           \NC $u$           \NC \SampleMath{1} \NC \NR
-\NC 2    \NC $s$           \NC $u$           \NC \SampleMath{2} \NC \NR
-\NC 3    \NC $s$           \NC $u + s - d$   \NC \SampleMath{3} \NC \NR
-\NC 4    \NC $d + (s-d)/2$ \NC $u + (s-d)/2$ \NC \SampleMath{4} \NC \NR
-\NC 5    \NC $d$           \NC $u + s - d$   \NC \SampleMath{5} \NC \NR
-\LL
-\stoptabulate
-
-The value of this parameter obeys grouping but applies to the whole current
-formula.
-
-% if needed we can put the value in stylenodes but maybe more should go there
-
-\subsection{Penalties: \lpr {mathpenaltiesmode}}
-
-\topicindex {math+penalties}
-
-Only in inline math penalties will be added in a math list. You can force
-penalties (also in display math) by setting:
-
-\starttyping
-\mathpenaltiesmode = 1
-\stoptyping
-
-This primnitive is not really needed in \LUATEX\ because you can use the callback
-\cbk {mlist_to_hlist} to force penalties by just calling the regular routine
-with forced penalties. However, as part of opening up and control this primitive
-makes sense. As a bonus we also provide two extra penalties:
-
-\starttyping
-\prebinoppenalty = -100 % example value
-\prerelpenalty   =  900 % example value
-\stoptyping
-
-They default to inifinite which signals that they don't need to be inserted. When
-set they are injected before a binop or rel noad. This is an experimental feature.
-
-\subsection{Equation spacing: \lpr {matheqnogapstep}}
-
-By default \TEX\ will add one quad between the equation and the number. This is
-hard coded. A new primitive can control this:
-
-\startsyntax
-\matheqnogapstep = 1000
-\stopsyntax
-
-Because a math quad from the math text font is used instead of a dimension, we
-use a step to control the size. A value of zero will suppress the gap. The step
-is divided by 1000 which is the usual way to mimmick floating point factors in
-\TEX.
+\section {Goodies}
 
 \subsection {Flattening: \lpr {mathflattenmode}}
 
@@ -1509,7 +1521,7 @@ mode parameter. The default value is~1.
 \LL
 \stoptabulate
 
-\subsection {Tracing}
+\subsection {Less Tracing}
 
 \topicindex {math+tracing}
 
@@ -1517,20 +1529,20 @@ 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.
 
-\subsection {Math options}
+\subsection {Math options with \lpr {mathoption}}
 
 The logic in the math engine is rather complex and there are often no universal
 solutions (read: what works out well for one font, fails for another). Therefore
-some variations in the implementation are driven by parameters (modes). In addition
-there is a new primitive \lpr {mathoption} which will be used for testing.
-
-\subsubsection {\type {\mathoption old}}
+some variations in the implementation are driven by parameters (modes). In
+addition there is a new primitive \lpr {mathoption} which will be used for
+testing. Don't rely on any option to be there in a production version as they are
+meant for development.
 
 This option was introduced for testing purposes when the math engine got split
 code paths and it forces the engine to treat new fonts as old ones with respect
 to italic correction etc. There are no guarantees given with respect to the final
 result and unexpected side effects are not seen as bugs as they relate to font
-properties.
+properties. Ther eis currently only one option:
 
 \startbuffer
 \mathoption old 1
@@ -1540,11 +1552,6 @@ The \type {oldmath} boolean flag in the \LUA\ font table is the official way to
 force old treatment as it's bound to fonts. Like with all options we may
 temporarily introduce with this command this feature is not meant for production.
 
-\subsubsection {Obsolete options}
-
-The following options are gone: \typ {noitaliccompensation}, \typ {nocharitalic},
-\typ {useoldfractionscaling}, and \typ {umathcodemeaning}.
-
 % % obsolete:
 %
 % \subsubsection {\type {\mathoption noitaliccompensation}}