1 files changed, 397 insertions, 0 deletions
diff --git a/doc/context/sources/general/manuals/math/math-spacing.tex b/doc/context/sources/general/manuals/math/math-spacing.tex
new file mode 100644
index 000000000..3412a3abc
--- /dev/null
+++ b/doc/context/sources/general/manuals/math/math-spacing.tex
@@ -0,0 +1,397 @@
+\environment math-layout
+
+\startcomponent math-spacing
+
+\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 (visualized by the thin rule on its baseline) 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
+
+So this is what we will use by default in \CONTEXT\ in order to better control
+spacing as 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
+
+\stopsection
+
+\startsection[title=Scripts]
+
+Spacing is a trade off because there is no way to predict all usage. Of course a
+font can be very detailed in where italic correction is to be applied and how
+advanced stepwise kerns are used, but not many fonts have extensive information.
+Here are some differences in rendering. In \OPENTYPE\ the super- and subscript of
+an integral are moved right and left half of the italic correction.
+
+\startlinecorrection
+    \startcombination[6*1]
+        {\switchtobodyfont  [modern]\math{F_j = \int\nolimits _a^b}} {Latin Modern}
+        {\switchtobodyfont [pagella]\math{F_j = \int\nolimits _a^b}} {Pagella}
+        {\switchtobodyfont  [dejavu]\math{F_j = \int\nolimits _a^b}} {Dejavu}
+        {\switchtobodyfont [cambria]\math{F_j = \int\nolimits _a^b}} {Cambria}
+        {\switchtobodyfont[lucidaot]\math{F_j = \int\nolimits _a^b}} {Lucida OT}
+        {\switchtobodyfont    [xits]\math{F_j = \int\nolimits _a^b}} {Xits}
+    \stopcombination
+\stoplinecorrection
+
+\stopsection
+
+\startsection[title=Bad fonts]
+
+There might be fonts out there where the italic correction is supposed to be
+added to the width of a glyph. In that case the following trick can be tried:
+
+\starttyping
+\definefontfeature[mathextra][italicwidths=yes] % fix latin modern
+\stoptyping
+
+in which case the following might look better:
+
+\starttyping
+$\left|V\right| = \left|W\right|$
+\stoptyping
+
+Of course better is to fix the font.
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent