2016-06-02 21:33:00

47 files changed, 739 insertions, 1 deletions

diff --git a/doc/context/documents/general/columnsets/columnsets.pdf b/doc/context/documents/general/manuals/columnsets.pdf
index 0d4e862f1..0d4e862f1 100644
--- a/doc/context/documents/general/columnsets/columnsets.pdf
+++ b/doc/context/documents/general/manuals/columnsets.pdf
diff --git a/doc/context/documents/general/manuals/luatex.pdf b/doc/context/documents/general/manuals/luatex.pdf
index 8a178e0b2..b727209ef 100644
--- a/doc/context/documents/general/manuals/luatex.pdf
+++ b/doc/context/documents/general/manuals/luatex.pdf
diff --git a/doc/context/documents/general/manuals/math-mkiv.pdf b/doc/context/documents/general/manuals/math-mkiv.pdf
new file mode 100644
index 000000000..eed4d598e
--- /dev/null
+++ b/doc/context/documents/general/manuals/math-mkiv.pdf
diff --git a/doc/context/documents/general/manuals/spacing-mkiv.pdf b/doc/context/documents/general/manuals/spacing-mkiv.pdf
index c717e6abf..1f0057f1d 100644
--- a/doc/context/documents/general/manuals/spacing-mkiv.pdf
+++ b/doc/context/documents/general/manuals/spacing-mkiv.pdf
diff --git a/doc/context/documents/general/manuals/xml-mkiv.pdf b/doc/context/documents/general/manuals/xml-mkiv.pdf
index 7305fb7a8..932b4cbaf 100644
--- a/doc/context/documents/general/manuals/xml-mkiv.pdf
+++ b/doc/context/documents/general/manuals/xml-mkiv.pdf
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-000.tex b/doc/context/sources/general/manuals/columnsets/columnsets-000.tex
index 429a067de..429a067de 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-000.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-000.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-001.tex b/doc/context/sources/general/manuals/columnsets/columnsets-001.tex
index 689f4e044..689f4e044 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-001.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-001.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-002.tex b/doc/context/sources/general/manuals/columnsets/columnsets-002.tex
index a67dd3161..a67dd3161 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-002.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-002.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-003.tex b/doc/context/sources/general/manuals/columnsets/columnsets-003.tex
index eed0286f8..eed0286f8 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-003.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-003.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-004.tex b/doc/context/sources/general/manuals/columnsets/columnsets-004.tex
index a58ddf621..a58ddf621 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-004.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-004.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-005.tex b/doc/context/sources/general/manuals/columnsets/columnsets-005.tex
index f1d970d9e..f1d970d9e 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-005.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-005.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-006.tex b/doc/context/sources/general/manuals/columnsets/columnsets-006.tex
index 033619970..033619970 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-006.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-006.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-007.tex b/doc/context/sources/general/manuals/columnsets/columnsets-007.tex
index 137a414d9..137a414d9 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-007.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-007.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-101.tex b/doc/context/sources/general/manuals/columnsets/columnsets-101.tex
index f9c7b59cb..f9c7b59cb 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-101.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-101.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-102.tex b/doc/context/sources/general/manuals/columnsets/columnsets-102.tex
index 3cf4dcd0e..3cf4dcd0e 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-102.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-102.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-103.tex b/doc/context/sources/general/manuals/columnsets/columnsets-103.tex
index f1d4dbedc..f1d4dbedc 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-103.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-103.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-201.tex b/doc/context/sources/general/manuals/columnsets/columnsets-201.tex
index 37b26c391..37b26c391 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-201.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-201.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-202.tex b/doc/context/sources/general/manuals/columnsets/columnsets-202.tex
index 1721d9cbc..1721d9cbc 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-202.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-202.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-203.tex b/doc/context/sources/general/manuals/columnsets/columnsets-203.tex
index 6c15578bc..6c15578bc 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-203.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-203.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-204.tex b/doc/context/sources/general/manuals/columnsets/columnsets-204.tex
index d390f468e..d390f468e 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-204.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-204.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-205.tex b/doc/context/sources/general/manuals/columnsets/columnsets-205.tex
index b53709770..b53709770 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-205.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-205.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-206.tex b/doc/context/sources/general/manuals/columnsets/columnsets-206.tex
index 8b9f524b1..8b9f524b1 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-206.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-206.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-301.tex b/doc/context/sources/general/manuals/columnsets/columnsets-301.tex
index 4d21f2b02..4d21f2b02 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-301.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-301.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-401.tex b/doc/context/sources/general/manuals/columnsets/columnsets-401.tex
index ee91e608c..ee91e608c 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-401.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-401.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-402.tex b/doc/context/sources/general/manuals/columnsets/columnsets-402.tex
index 00db6017c..00db6017c 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-402.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-402.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-403.tex b/doc/context/sources/general/manuals/columnsets/columnsets-403.tex
index c9bc2e648..c9bc2e648 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-403.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-403.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-404.tex b/doc/context/sources/general/manuals/columnsets/columnsets-404.tex
index 05a25acfe..05a25acfe 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-404.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-404.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-405.tex b/doc/context/sources/general/manuals/columnsets/columnsets-405.tex
index fa20ef34c..fa20ef34c 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-405.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-405.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-601.tex b/doc/context/sources/general/manuals/columnsets/columnsets-601.tex
index b139210f4..b139210f4 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-601.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-601.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-701.tex b/doc/context/sources/general/manuals/columnsets/columnsets-701.tex
index b2c50cfaf..b2c50cfaf 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-701.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-701.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-702.tex b/doc/context/sources/general/manuals/columnsets/columnsets-702.tex
index 5b9a879c1..5b9a879c1 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-702.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-702.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-703.tex b/doc/context/sources/general/manuals/columnsets/columnsets-703.tex
index 549b49f61..549b49f61 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-703.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-703.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-704.tex b/doc/context/sources/general/manuals/columnsets/columnsets-704.tex
index 7fa6cb313..7fa6cb313 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-704.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-704.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-801.tex b/doc/context/sources/general/manuals/columnsets/columnsets-801.tex
index 1a84f99ab..1a84f99ab 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-801.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-801.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-802.tex b/doc/context/sources/general/manuals/columnsets/columnsets-802.tex
index a126d0012..a126d0012 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-802.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-802.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-803.tex b/doc/context/sources/general/manuals/columnsets/columnsets-803.tex
index 58a278bb1..58a278bb1 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-803.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-803.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-804.tex b/doc/context/sources/general/manuals/columnsets/columnsets-804.tex
index c2b7a6b1e..c2b7a6b1e 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-804.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-804.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-805.tex b/doc/context/sources/general/manuals/columnsets/columnsets-805.tex
index fc80e7e9c..fc80e7e9c 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-805.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-805.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-806.tex b/doc/context/sources/general/manuals/columnsets/columnsets-806.tex
index 0322a336f..0322a336f 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-806.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-806.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-901.tex b/doc/context/sources/general/manuals/columnsets/columnsets-901.tex
index 300458bf5..300458bf5 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-901.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-901.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-902.tex b/doc/context/sources/general/manuals/columnsets/columnsets-902.tex
index fda2969af..fda2969af 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-902.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-902.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets-903.tex b/doc/context/sources/general/manuals/columnsets/columnsets-903.tex
index 68cd31ae2..68cd31ae2 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets-903.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets-903.tex
diff --git a/doc/context/sources/general/columnsets/columnsets/columnsets.tex b/doc/context/sources/general/manuals/columnsets/columnsets.tex
index 7d68872ef..7d68872ef 100644
--- a/doc/context/sources/general/columnsets/columnsets/columnsets.tex
+++ b/doc/context/sources/general/manuals/columnsets/columnsets.tex
diff --git a/doc/context/sources/general/manuals/luatex/luatex-modifications.tex b/doc/context/sources/general/manuals/luatex/luatex-modifications.tex
index 0507a56e0..e59e09e1e 100644
--- a/doc/context/sources/general/manuals/luatex/luatex-modifications.tex
+++ b/doc/context/sources/general/manuals/luatex/luatex-modifications.tex
@@ -67,7 +67,17 @@ most still comes from the original. But we divert a bit.
 \stopitem
 
 \startitem
-    Magnification (\type {\mag}) is only supported in \DVI\ output mode.
+    Magnification (\type {\mag}) is only supported in \DVI\ output mode. You can
+    set this parameter and it even works with \type {true} units till you switch
+    to \PDF\ output mode. When you use \PDF\ output you can best not touch the
+    \type {\mag} variable. This fuzzy behaviour is not much different from using
+    \PDF\ backend related functionality while eventually \DVI\ output is
+    required.
+
+    After the output mode has been frozen (normally that happens when the first
+    page is shipped out) or when \PDF\ output is enabled, the \type {true}
+    specification is ignored. When you preload a plain format adapted to
+    \LUATEX\ it can be that the \type {\mag} parameter already has been set.
 \stopitemize
 
 \stopsubsection
diff --git a/doc/context/sources/general/manuals/luatex/luatex-nodes.tex b/doc/context/sources/general/manuals/luatex/luatex-nodes.tex
index 32e641789..21ef0232d 100644
--- a/doc/context/sources/general/manuals/luatex/luatex-nodes.tex
+++ b/doc/context/sources/general/manuals/luatex/luatex-nodes.tex
@@ -201,6 +201,26 @@ its internal link structure is correct, otherwise an error may be result.
 The subtype numbers~4 and~5 belong to the \quote {of-f-ice} explanation given
 elsewhere.
 
+These disc nodes are kind of special as at some point they also keep information
+about breakpoints and nested ligatures. The \type {pre}, \type {post} and \type
+{replace} fields at the \LUA\ end are in fact indirectly accessed and have a
+\type {prev} pointer that is not \type {nil}. This means that when you mess
+around with the head of these (three) lists, you also need to reassign them
+because that will restore the proper \type {prev} pointer, so:
+
+\starttyping
+pre = d.pre
+-- change the list starting with pre
+d.pre = pre
+\stoptyping
+
+Otherwise you can end up with an invalid internal perception of reality and
+\LUATEX\ might even decide to crash on you. It also means that running forward
+over for instance \type {pre} is ok but backward you need to stop at \type {pre}.
+And you definitely must not mess with the node that \type {prev} points to, if
+only because it is not really an node but part of the disc data structure (so
+freeing it again might crash \LUATEX).
+
 \subsubsection{math nodes}
 
 \starttabulate[|lT|l|p|]
diff --git a/doc/context/sources/general/manuals/math/math-mkiv.tex b/doc/context/sources/general/manuals/math/math-mkiv.tex
new file mode 100644
index 000000000..0148a8807
--- /dev/null
+++ b/doc/context/sources/general/manuals/math/math-mkiv.tex
@@ -0,0 +1,631 @@
+% language=uk
+
+\setupbodyfont
+  [pagella]
+
+\setupwhitespace
+  [big]
+
+\setuppagenumbering
+  [alternative=doublesided]
+
+\setuplayout
+  [backspace=2cm,
+   width=middle,
+   cutspace=2cm,
+   topspace=2cm,
+   header=2cm,
+   height=middle,
+   footer=0pt,
+   bottomspace=2cm]
+
+\usemodule[x][setups-basics]
+
+\usemodule[visual]
+
+\loadsetups[i-context]
+
+\starttext
+
+\startMPpage
+
+StartPage;
+    fill Page withcolor .35magenta ;
+    picture p ; p := image ( draw outlinetext.b
+        ("\textdollar")
+        (withcolor .35green)
+        (withcolor .5yellow withpen pencircle scaled .1) ;
+    ) ;
+    p := p xysized(PaperWidth - 20pt,PaperHeight - 20pt ) ;
+    p := p shifted - llcorner p shifted (10pt,10pt) ;
+    draw p ;
+    picture p ; p := image ( draw outlinetext.b
+        ("math")
+        (withcolor .35green)
+        (withcolor .5yellow withpen pencircle scaled .2) ;
+    ) ;
+    p := p xsized(PaperWidth/2 - 40pt) ;
+    p := p shifted - llcorner p shifted (10pt,10pt) ;
+    draw p shifted (PaperWidth/2 + 20pt,20pt);
+StopPage;
+
+\stopMPpage
+
+\page[empty] \setuppagenumber[number=1]
+
+\setuplayout
+  [backspace=2cm,
+   topspace=2cm,
+   header=2cm,
+   height=middle,
+   width=middle]
+
+\setuphead
+  [chapter]
+  [header=high,
+   style=\bfc,
+   color=darkmagenta]
+
+\setuphead
+  [section]
+  [style=\bfb]
+
+\setuphead
+  [subsection]
+  [style=\bfa]
+
+\starttitle[title=Introduction]
+
+This manual is not a systematic discussion about math in \CONTEXT\ but more a
+collection of wrap|-|ups. The file also serves as testcase. The content can
+change over time and can also serve as a trigger for discussions on the mailing
+list. Feel free to contribute.
+
+\startlines
+Hans Hagen
+Hasselt NL
+% May 2016
+\stoplines
+
+\stoptitle
+
+\startchapter[title=Vertical spacing]
+
+The low level way to input inline math in \TEX\ is
+
+\starttyping
+$ e = mc^2 $
+\stoptyping
+
+while display math can be entered like:
+
+\starttyping
+$$ e = mc^2 $$
+\stoptyping
+
+The inline method is still valid, but for display math the \type {$$} method
+should not be used. This has to do with the fact that we want to control spacing
+in a consistent way. In \CONTEXT\ the vertical spacing model is rather stable
+although in \MKIV\ the implementation is quite different. It has always been a
+challenge to let this mechanism work well with space round display formulas. This
+has to do with the fact that (in the kind of documents that we have to produce)
+interaction with already present spacing is somewhat tricky.
+
+Of course much can be achieved in \TEX\ but in \CONTEXT\ we need to have control
+over the many mechanisms that can interact. Given the way \TEX\ handles space
+around display math there is no real robust solution possible that gives visually
+consistent space in all cases so that is why we basically disable the existing
+spacing model. Disabling is easier in \LUATEX\ and recent versions of \MKIV\ have
+been adapted to that.
+
+In pure \TEX\ what happens is this:
+
+\startbuffer
+$$ x $$
+\stopbuffer
+
+\typebuffer \par \start \showboxes \getbuffer \par \stop
+
+A horizontal box get added which triggers a baselineskip. Then the formula is put
+below it. We can get rid of that box with \type {\noindent}:
+
+\startbuffer
+\noindent $$ x $$
+\stopbuffer
+
+\typebuffer \par \start \showboxes \getbuffer \par \stop
+
+In addition (not shown here) vertical space is added before and after the formula
+and left- and rightskip on the edges. In fact typesetting display math goes like this:
+
+\startitemize[packed]
+    \startitem
+        typeset the formula using display mode and wrap it in a box
+    \stopitem
+    \startitem
+        add an equation number, if possible in the same line, otherwise on a line
+        below
+    \stopitem
+    \startitem
+        in the process center the formula using the available display width and
+        required display indentation
+    \stopitem
+    \startitem
+        add vertical space above and below (depending also in displays being
+        short in relation to the previous line
+    \stopitem
+    \startitem
+        at the same time also add penalties that determine the break across
+        pages
+    \stopitem
+\stopitemize
+
+Apart from the spacing around the formula and the equation number, typesetting is
+not different from:
+
+\starttyping
+\hbox {$ \displaystyle x $}
+\stoptyping
+
+This spacing around math is a sensitive issue. Because math itself can have a
+narrow band, for instance a lone $x$, or relative much depth, as with $y$, or
+both depth and height as in $(1,2)$ and $x^2 + y_2$ and because a preceding line
+can have no or little depth and a following line little height, the visual
+appearance can become inconsistent. The default approach is to force consistent
+spacing, but when needed we can implement variants.
+
+Spacing around display math is set up with \type {\setupformulas}:
+
+\starttyping
+  \setupformulas
+    [spacebefore=big,
+     spaceafter=big]
+\stoptyping
+
+When the whitespace is larger that setting wins because as usual the larger
+of blanks or whitespace wins.
+
+% \showdefinition[setupformula]
+% \showdefinition[setupmathematics]
+
+In \in {figures} [whitespace-no], \in {figures} [whitespace-medium] \in {and}
+[whitespace-big] we see how things interact. We show lines with and without
+maximum line height and depth (enforced by struts) alongside.
+
+% no whitespace
+
+\startbuffer[demo-1]
+\disablemode[with-struts]
+\showmakeup
+\setupformulas[spacebefore=none,spaceafter=none]
+\setupwhitespace[none]
+\input math-spacing-001.tex
+\stopbuffer
+
+\startbuffer[demo-2]
+\enablemode[with-struts]
+\showmakeup
+\setupformulas[spacebefore=none,spaceafter=none]
+\setupwhitespace[none]
+\input math-spacing-001.tex
+\stopbuffer
+
+\startbuffer[demo-3]
+\disablemode[with-struts]
+\showmakeup
+\setupformulas[spacebefore=medium,spaceafter=medium]
+\setupwhitespace[none]
+\input math-spacing-001.tex
+\stopbuffer
+
+\startbuffer[demo-4]
+\enablemode[with-struts]
+\showmakeup
+\setupformulas[spacebefore=medium,spaceafter=medium]
+\setupwhitespace[none]
+\input math-spacing-001.tex
+\stopbuffer
+
+\startplacefigure[location=page,reference=whitespace-no,title={No whitespace.}]
+    \startcombination[2*2]
+        {\typesetbuffer[demo-1][height=.45\textheight]} {\tttf natural + none   + ws none}
+        {\typesetbuffer[demo-2][height=.45\textheight]} {\tttf strut   + none   + ws none}
+        {\typesetbuffer[demo-3][height=.45\textheight]} {\tttf natural + medium + ws none}
+        {\typesetbuffer[demo-4][height=.45\textheight]} {\tttf strut   + medium + ws none}
+    \stopcombination
+\stopplacefigure
+
+% whitespace medium same as medium spacing around math
+
+\startbuffer[demo-1]
+\disablemode[with-struts]
+\showmakeup
+\setupformulas[spacebefore=none,spaceafter=none]
+\setupwhitespace[medium]
+\input math-spacing-001.tex
+\stopbuffer
+
+\startbuffer[demo-2]
+\enablemode[with-struts]
+\showmakeup
+\setupformulas[spacebefore=none,spaceafter=none]
+\setupwhitespace[medium]
+\input math-spacing-001.tex
+\stopbuffer
+
+\startbuffer[demo-3]
+\disablemode[with-struts]
+\showmakeup
+\setupformulas[spacebefore=medium,spaceafter=medium]
+\setupwhitespace[medium]
+\input math-spacing-001.tex
+\stopbuffer
+
+\startbuffer[demo-4]
+\enablemode[with-struts]
+\showmakeup
+\setupformulas[spacebefore=medium,spaceafter=medium]
+\setupwhitespace[medium]
+\input math-spacing-001.tex
+\stopbuffer
+
+\startplacefigure[location=page,reference=whitespace-medium,title={Whitespace the same as display spacing.}]
+    \startcombination[2*2]
+        {\typesetbuffer[demo-1][height=.45\textheight]} {\tttf natural + none   + ws medium}
+        {\typesetbuffer[demo-2][height=.45\textheight]} {\tttf strut   + none   + ws medium}
+        {\typesetbuffer[demo-3][height=.45\textheight]} {\tttf natural + medium + ws medium}
+        {\typesetbuffer[demo-4][height=.45\textheight]} {\tttf strut   + medium + ws medium}
+    \stopcombination
+\stopplacefigure
+
+% whitespace big wins from medium spacing around math
+
+\startbuffer[demo-1]
+\disablemode[with-struts]
+\showmakeup
+\setupformulas[spacebefore=none,spaceafter=none]
+\setupwhitespace[big]
+\input math-spacing-001.tex
+\stopbuffer
+
+\startbuffer[demo-2]
+\enablemode[with-struts]
+\showmakeup
+\setupformulas[spacebefore=none,spaceafter=none]
+\setupwhitespace[big]
+\input math-spacing-001.tex
+\stopbuffer
+
+\startbuffer[demo-3]
+\disablemode[with-struts]
+\showmakeup
+\setupformulas[spacebefore=medium,spaceafter=medium]
+\setupwhitespace[big]
+\input math-spacing-001.tex
+\stopbuffer
+
+\startbuffer[demo-4]
+\enablemode[with-struts]
+\showmakeup
+\setupformulas[spacebefore=medium,spaceafter=medium]
+\setupwhitespace[big]
+\input math-spacing-001.tex
+\stopbuffer
+
+\startplacefigure[location=page,reference=whitespace-big,title={Whitespace larger than display spacing.}]
+    \startcombination[2*2]
+        {\typesetbuffer[demo-1][height=.45\textheight]} {\tttf natural + none   + ws big}
+        {\typesetbuffer[demo-2][height=.45\textheight]} {\tttf strut   + none   + ws big}
+        {\typesetbuffer[demo-3][height=.45\textheight]} {\tttf natural + medium + ws big}
+        {\typesetbuffer[demo-4][height=.45\textheight]} {\tttf strut   + medium + ws big}
+    \stopcombination
+\stopplacefigure
+
+Because we want to have control over the placement of the formula number but also
+want to be able to align the formula with the left or right edge of the text
+area, we don't use the native display handler by default. We still have a way to
+force this, but this is only for testing purposes. By default a formula is placed
+centered relative to the current text, including left and right margins.
+
+\startbuffer
+\fakewords{20}{40}
+
+\startitemize
+    \startitem
+        \fakewords{20}{40}
+        \placeformula
+            \startformula
+                \fakeformula
+            \stopformula
+    \stopitem
+    \startitem
+        \fakewords{20}{40}
+    \stopitem
+\stopitemize
+
+\fakewords{20}{40}\epar
+\stopbuffer
+
+\typebuffer
+
+\start \getbuffer \stop
+
+In the next examples we explicitly align formulas to the left (\type
+{flushleft}), center (\type {middle}) and right (\type {flushright}):
+
+\startbuffer[demo]
+\setupformulas[align=flushleft]
+\startformula\fakeformula\stopformula
+\setupformulas[align=middle]
+\startformula\fakeformula\stopformula
+\setupformulas[align=flushright]
+\startformula\fakeformula\stopformula
+\stopbuffer
+
+\typebuffer[demo]
+
+The three cases show up as:
+
+\start \getbuffer[demo] \stop
+
+You can also set a left and|/|or right margin:
+
+\startbuffer[setting]
+\setupformulas
+  [leftmargin=3cm,
+   rightmargin=3cm]
+\stopbuffer
+
+\start \getbuffer[setting] \getbuffer[demo] \stop
+
+With formula numbers these formulas look as follows:
+
+\startbuffer[demo]
+\setupformulas[align=flushleft]
+\placeformula \startformula\fakeformula\stopformula
+\setupformulas[align=middle]
+\placeformula \startformula\fakeformula\stopformula
+\setupformulas[align=flushright]
+\placeformula \startformula\fakeformula\stopformula
+\stopbuffer
+
+\start \getbuffer[demo] \stop
+
+and the same with margins:
+
+\start \getbuffer[setting] \getbuffer[demo] \stop
+
+\page
+
+When the \type {margin} option is set to \type {standard} or \type {yes} the
+current indentation (when set) or left skip is added to the left side.
+
+\startbuffer
+\setupformulas[align=flushleft]
+\startformula \fakeformula \stopformula
+\placeformula \startformula \fakeformula \stopformula
+\stopbuffer
+
+\typebuffer \start \getbuffer \stop
+
+\startbuffer
+\setupformulas[align=flushleft,margin=standard]
+\startformula \fakeformula \stopformula
+\placeformula \startformula \fakeformula \stopformula
+\stopbuffer
+
+\typebuffer \start \getbuffer \stop
+
+The distance between the formula and the number is only applied when the formula
+is left or right aligned.
+
+\startbuffer
+\setupformulas[align=flushright,distance=0pt]
+\startformula \fakeformula \stopformula
+\placeformula \startformula \fakeformula \stopformula
+\stopbuffer
+
+\typebuffer \start \getbuffer \stop
+
+\startbuffer
+\setupformulas[align=flushright,distance=2em]
+\startformula \fakeformula \stopformula
+\placeformula \startformula \fakeformula \stopformula
+\stopbuffer
+
+\typebuffer \start \getbuffer \stop
+
+\stopchapter
+
+% \startchapter[title=Numbering]
+
+% \stopchapter
+
+\startchapter[title=Framing]
+
+The \type {\framed} macro is one of the core constructors in \CONTEXT\ and it's
+used all over the place. This macro is unlikely to change its behaviour and as it
+has evolved over years it comes with quite some options and some can interfere
+with the expectations one has. In general using this macro works out well but you
+need to keep an eye on using struts and alignment.
+
+\startbuffer
+\framed{$e=mc^2$}
+\stopbuffer
+
+\typebuffer
+
+The outcome of this is:
+
+\startlinecorrection \getbuffer \stoplinecorrection
+
+There is a bit of offset (that you can set) but also struts are added as can be
+seen when we visualize them:
+
+\startlinecorrection \showstruts \getbuffer \stoplinecorrection
+
+These struts can be disabled:
+
+\startbuffer
+\framed[strut=no]{$e=mc^2$}
+\stopbuffer
+
+\typebuffer
+
+Now the result is more tight.
+
+\startlinecorrection \showstruts \getbuffer \stoplinecorrection
+
+These struts are the way to get a consistent look and feel and are used
+frequently in \CONTEXT. We mention these struts because they get in the way when
+we frame a display formula. Let's first look at what happens when we
+just package a formula in a box:
+
+\startbuffer
+\vbox\bgroup
+    \startformula
+        e = mc^2
+    \stopformula
+\egroup
+\stopbuffer
+
+\typebuffer
+
+We get:
+
+\startlinecorrection \start \showmakeup \getbuffer \stop \stoplinecorrection
+
+Now there are a few properties of displaymath that one needs to keep in mind when
+messing around with them this way. First of all display math is meant to be used
+as part of the page stream. This means that spacing above and below is adapted to
+what comes before and after. It also means that, because formulas can be numbered,
+we have some settings that relate to horizontal placement.
+
+The default vertical spacing is easy to get rid of:
+
+\startbuffer
+\vbox\bgroup
+    \startformula[packed]
+        e = mc^2
+    \stopformula
+\egroup
+\stopbuffer
+
+\typebuffer
+
+This gives:
+
+\startlinecorrection \start \showmakeup \getbuffer \stop \stoplinecorrection
+
+Another handy keyword is \type {tight}:
+
+\startbuffer
+\vbox\bgroup
+    \startformula[tight]
+        e = mc^2
+    \stopformula
+\egroup
+\stopbuffer
+
+\typebuffer
+
+This gives:
+
+\startlinecorrection \start \showmakeup \getbuffer \stop \stoplinecorrection
+
+We can combine these two:
+
+\startbuffer
+\vbox\bgroup
+    \startformula[packed,tight]
+        e = mc^2
+    \stopformula
+\egroup
+\stopbuffer
+
+\typebuffer
+
+This gives:
+
+\startlinecorrection \start \showmakeup \getbuffer \stop \stoplinecorrection
+
+Just in case you wonder why we need to go through these troubles: keep in mind
+that we are wrapping something (math) that normally goes in a vertical list with
+text above and below.
+
+The \type {packed} and \type {tight} options can help when we want to wrap
+a formula in a frame:
+
+\startbuffer
+\framed
+    [strut=no]
+    {
+        \startformula[packed,tight]
+            e = mc^2
+        \stopformula
+    }
+\stopbuffer
+
+\typebuffer
+
+which renders as:
+
+\startlinecorrection \getbuffer \stoplinecorrection
+
+There is a dedicated math framed instance that is tuned to give better results
+and automatically switches to math mode:
+
+\startbuffer
+\mframed {
+    e = mc^2
+}
+\stopbuffer
+
+\typebuffer
+
+becomes:
+
+\startlinecorrection \getbuffer \stoplinecorrection
+
+Multiple formulas can be combined:
+
+\startbuffer
+\startformulas
+    \startformula
+        a + b = c
+    \stopformula
+    \startformula
+        d - e = f
+    \stopformula
+\stopformulas
+\stopbuffer
+
+\typebuffer
+
+We might add some more control in the future, but this is what you get:
+
+\startlinecorrection \getbuffer \stoplinecorrection
+
+\stopchapter
+
+\stoptext
+
+% when we compare these tables with the one that the ff loader produces we notice
+% some differences: this is because (deduced from source) that ff does some kind
+% of interpolation for missing heights for the last kern (for n=2 adding 100 and
+% for adding 1 the max height) ... this is probably a side effect if missing specs
+% here we don't do that
+% \enabledirectives[fontgoodies.mathkerning]
+
+% \startTEXpage[offset=2mm]
+%     \startcombination[4*2]
+%         {\hbox to 50pt{\hss\showboxes\switchtobodyfont  [modern]$V_i^i = W_i^i$\hss}} {\infofont modern}
+%         {\hbox to 50pt{\hss\showboxes\switchtobodyfont [cambria]$V_i^i = W_i^i$\hss}} {\infofont cambria}
+%         {\hbox to 50pt{\hss\showboxes\switchtobodyfont[lucidaot]$V_i^i = W_i^i$\hss}} {\infofont lucida}
+%         {\hbox to 50pt{\hss\showboxes\switchtobodyfont  [dejavu]$V_i^i = W_i^i$\hss}} {\infofont dejavu}
+%         {\hbox to 50pt{\hss\showboxes\switchtobodyfont [pagella]$V_i^i = W_i^i$\hss}} {\infofont pagella}
+%         {\hbox to 50pt{\hss\showboxes\switchtobodyfont  [termes]$V_i^i = W_i^i$\hss}} {\infofont termes}
+%         {\hbox to 50pt{\hss\showboxes\switchtobodyfont   [bonum]$V_i^i = W_i^i$\hss}} {\infofont bonum}
+%         {\hbox to 50pt{\hss\showboxes\switchtobodyfont  [schola]$V_i^i = W_i^i$\hss}} {\infofont schola}
+%     \stopcombination
+% \stopTEXpage
diff --git a/doc/context/sources/general/manuals/xml/xml-mkiv.tex b/doc/context/sources/general/manuals/xml/xml-mkiv.tex
index 42ec7df9a..3933c0063 100644
--- a/doc/context/sources/general/manuals/xml/xml-mkiv.tex
+++ b/doc/context/sources/general/manuals/xml/xml-mkiv.tex
@@ -2747,6 +2747,83 @@ Tags like \type {t7}, \type {t8} etc.\ can represent versions.
 
 \stopsection
 
+\startsection[title=preprocessing]
+
+% local match    = lpeg.match
+% local replacer = lpeg.replacer("BAD TITLE:","<bold>BAD TITLE:</bold>")
+%
+% function lxml.preprocessor(data,settings)
+%     return match(replacer,data)
+% end
+
+\startbuffer[pre-code]
+\startluacode
+    function lxml.preprocessor(data,settings)
+        return string.find(data,"BAD TITLE:")
+           and string.gsub(data,"BAD TITLE:","<bold>BAD TITLE:</bold>")
+            or data
+    end
+\stopluacode
+\stopbuffer
+
+\startbuffer[pre-xml]
+\startxmlsetups pre:demo:initialize
+    \xmlsetsetup{#1}{*}{pre:demo:*}
+\stopxmlsetups
+
+\xmlregisterdocumentsetup{pre:demo}{pre:demo:initialize}
+
+\startxmlsetups pre:demo:root
+    \xmlflush{#1}
+\stopxmlsetups
+
+\startxmlsetups pre:demo:bold
+    \begingroup\bf\xmlflush{#1}\endgroup
+\stopxmlsetups
+
+\starttext
+    \xmlprocessbuffer{pre:demo}{demo}{}
+\stoptext
+\stopbuffer
+
+Say that you have the following \XML\ setup:
+
+\typebuffer[pre-xml]
+
+and that (such things happen) the input looks like this:
+
+\startbuffer[demo]
+<root>
+BAD TITLE: crap crap crap ...
+
+BAD TITLE: crap crap crap ...
+</root>
+\stopbuffer
+
+\typebuffer[demo]
+
+You can then clean up these \type {BAD TITLE}'s as follows:
+
+\typebuffer[pre-code]
+
+and get as result:
+
+\start \getbuffer[pre-code,pre-xml] \stop
+
+The preprocessor function gets as second argument the current settings, an d
+the field \type {currentresource} can be used to limit the actions to
+specific resources, in our case it's \type {buffer: demo}. Afterwards you can
+reset the proprocessor with:
+
+\startluacode
+lxml.preprocessor = nil
+\stopluacode
+
+Future versions might give some more control over preprocessors. For now consider
+it to be a quick hack.
+
+\stopsection
+
 \stopchapter
 
 \startchapter[title={Lookups using lpaths}]