\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