% language=us runpath=texruns:manuals/math

\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

\startsection[title=Multiline]

Inline formulas can span lines but display math normally sits on one line unless
one uses alignment mechanisms. Take this:

\startbuffer[demo]
\startformula
    x\dorecurse{30}{ + #1x^{#1x}} = 10
\stopformula
\stopbuffer

\typebuffer[demo]

\par \start \setupformula[split=no]  \getbuffer[demo] \stop \par

You can set \type {split} to \type {yes} using \type {\setupformula} and get the
following:

\par \start \setupformula[split=yes] \getbuffer[demo] \stop \par

Maybe nicer is to also set \type {align} to \type {flushleft}:

\par \start \setupformula[split=yes,align=flushleft] \getbuffer[demo] \stop \par

If you want the binary operators to start the lines you can set this:

\startbuffer[setup]
\setupmathematics[setups=math:spacing:split]
\setupformulas[split=yes,align=flushleft]
\stopbuffer

\typebuffer[setup]

\par \start \getbuffer[setup,demo] \stop \par

You can prevent a split with a large penalty. Here is a test that yuou can run
to play with this feature:

\starttyping
\dostepwiserecurse {30} {100} {1} {
    \hsize \dimexpr 40pt + #1pt \relax
    \startformula
        y = a \dorecurse {50} {
            \penalty 10000 {\bf + ##1b}
             + ##1c^2
        }
    \stopformula
    \page
}
\stoptyping

There is an experimental alignment mechanism available. Watch the following
examples:

\startbuffer[demo]
before
    \startformula
        z + 3y = \alignhere x
                 \dorecurse{20}{ + #1x^{#1x}}
    \stopformula
inbetween
    \startformula
        z + 3y \alignhere = 1
               \dorecurse{4}{
                    \dorecurse{#1}{+ #1x^{##1x}}
                    \ifnum#1<4\breakhere\fi
               }
    \stopformula
after
\stopbuffer

\typebuffer[demo]

\startbuffer[setup]
\setupformula
  [split=no]
\stopbuffer

\typebuffer[setup] \start \getbuffer[setup,demo] \stop

\startbuffer[setup]
\setupformula
  [split=yes,
   align=flushleft]
\stopbuffer

\typebuffer[setup] \start \getbuffer[setup,demo] \stop

\startbuffer[setup]
\setupformula
  [split=yes,
   align=flushleft,
   hang=auto]
\stopbuffer

\typebuffer[setup] \start \getbuffer[setup,demo] \stop

\startbuffer[setup]
\setupformula
  [split=yes,
   align=flushleft,
   hang=auto,
   distance=1em]
\stopbuffer

\typebuffer[setup] \start \getbuffer[setup,demo] \stop

\startbuffer[setup]
\setupformula
  [split=yes,
   align=flushleft,
   hang=yes,
   distance=2em]
\stopbuffer

\typebuffer[setup] \start \getbuffer[setup,demo] \stop

\startbuffer[setup]
\setupformula
  [split=yes,
   align=flushleft,
   hang=yes,
   distance=2em,
   interlinespace=1.5\lineheight]
\stopbuffer

\typebuffer[setup] \start \getbuffer[setup,demo] \stop

If you want to split over pages, you can say:

\starttyping
\setupformula
  [split=page,
   align=middle]
\stoptyping

but that is rather experimental (especially in combination with other
number placement related options).

\stopsection

\startsection[title=Scripts]

Superscripts and subscripts are typeset in a smaller size than their nucleus. You
can influence that as follows:

\startbuffer
\startformula
x^{2} = x^{\textstyle 2}
      = x^{\scriptstyle 2}
      = x^{\scriptscriptstyle 2}
\stopformula
\stopbuffer

\typebuffer \getbuffer

You can also use macros instead of a \type {^} and \type {_}, as in:

\startbuffer
\startformula
x \superscript   {2} =
x \superscript   {\textstyle 2} =
x \superscript   {\scriptstyle 2} =
x \superscript   {\scriptscriptstyle 2} =
x \nosuperscript {2}
\stopformula
\stopbuffer

\typebuffer \getbuffer

The \type {\nosuperscript} primitive makes sure that we get the same size as the
nucleus.

\startbuffer
\startformula
x \superscript   {2} \subscript   {i} =
x \nosuperscript {2} \subscript   {i} =
x \superscript   {2} \nosubscript {i} =
x \nosuperscript {2} \nosubscript {i}
\stopformula
\stopbuffer

\typebuffer \getbuffer

\stopsection

\startsection[title=Text accents]

You can put an accent over a character:

\startbuffer
$\grave{x} \neq \grave{i}$\quad
$\ddot {x} \neq \ddot {i}$\quad
$\bar  {x} \neq \bar  {i}$\quad
$\acute{x} \neq \acute{i}$\quad
$\hat  {x} \neq \hat  {i}$\quad
$\check{x} \neq \check{i}$\quad
$\breve{x} \neq \breve{i}$\quad
$\dot  {x} \neq \dot  {i}$\quad
$\ring {x} \neq \ring {i}$\quad
$\tilde{x} \neq \tilde{i}$\quad
$\dddot{x} \neq \dddot{i}$\quad
\stopbuffer

\typebuffer

This comes out as: \inlinebuffer. For regular text you can better use proper composed
\UTF\ encoded characters.

\stopsection

\startsection[title=Directions]

Math has its own direction control:

\starttexdefinition unexpanded MathTest #1#2#3
    \ruledvbox \bgroup
        \mathdirection#1\relax
        \textdirection#2\relax
        \pardirection #3\relax
        \hsize=30mm
        \startformula
            a^2+b^2=c^2
        \stopformula
   \egroup
\stoptexdefinition

\starttexdefinition unexpanded MathShow #1#2#3#4
    \hbox \bgroup
        \infofont #1 : m=#2 t=#3 p=#4
    \egroup
\stoptexdefinition

\startbuffer
\startcombination[nx=4,ny=2,distance=1cm]
    {\MathTest{0}{0}{0}} {\MathShow1{0}{0}{0}}
    {\MathTest{0}{0}{1}} {\MathShow2{0}{0}{1}}
    {\MathTest{0}{1}{0}} {\MathShow3{0}{1}{0}}
    {\MathTest{0}{1}{1}} {\MathShow4{0}{1}{1}}
    {\MathTest{1}{0}{0}} {\MathShow5{1}{0}{0}}
    {\MathTest{1}{0}{1}} {\MathShow6{1}{0}{1}}
    {\MathTest{1}{1}{0}} {\MathShow7{1}{1}{0}}
    {\MathTest{1}{1}{1}} {\MathShow8{1}{1}{1}}
\stopcombination
\stopbuffer

\typebuffer

Normally you will not control directions this way but use the proper parameters
in layout related setup commands.

\startlinecorrection
\getbuffer
\stoplinecorrection

\stopsection

\startsection[title=Surround]

The spacing around inline formulas is consistent with other
spacing but it can be enlarged. We just show a few examples:

\startbuffer[demo]
\hsize 20em
We have
\dorecurse {8} {%
    \ifcase#1\or\else and \fi
    $x+#1$ and $x-#1$ and $x \times #1$
}
\removeunwantedspaces .
\par
\stopbuffer

\typebuffer[demo]

\blank \start \getbuffer[demo] \stop

\startbuffer[setup]
\setupmathematics
  [textdistance=2pt plus 1pt minus 1pt]
\stopbuffer

\typebuffer[setup]

\blank \start \getbuffer[setup,demo] \stop

\startbuffer[setup]
\setupmathematics
  [textdistance=4pt plus 2pt minus 2pt]
\stopbuffer

\typebuffer[setup]

\blank \start \getbuffer[setup,demo] \stop

\stopsection

\startsection[title=Choices]

The next examples are generated using this macro:

\startbuffer
\starttexdefinition unexpanded Test#1#2

    \begingroup

    \showmakeup[depth]

    \def\TestA{\dontleavehmode\ruledhbox{\dorecurse{8}{before }}}
    \def\TestB{\dontleavehmode\ruledhbox{\dorecurse{8}{after }}}
    \def\TestC{\dorecurse{18}{x+}x}

    \setdisplaymathspacemodel[3]
    \setupalign[flushleft]  1\space:\space\TestA \par
    \startformula #2 \TestC \stopformula \par
    \setupalign[flushleft]  2\space:\space\TestB \par

    \setdisplaymathspacemodel[4]

    \vskip#1\lineheight

    \setupalign[flushright] \TestA\space:\space2 \par
    \startformula #2 \TestC \stopformula \par
    \setupalign[flushright] \TestB\space:\space2 \par

    \endgroup

\stoptexdefinition
\stopbuffer

\typebuffer \getbuffer

It demonstrates the often hard decisions that we have to make with regards to
spacing. On the one hand we want to be adaptive, on the other hand we want to be
consistent, for instance in the depth of lines. These examples overlay the two
variants (which is of course font and style dependent).

\Test{-4.70}{}                      \blank[2*line]
\Test{-6.00}{\frac{1}{2}}           \blank[2*line]
\Test{-6.55}{\frac{1}{\frac{1}{2}}}

One side effect of these options is that at some point we need to choose a
default and then easily forget about the other variants.

\stopsection

\stopchapter

\stopcomponent