\usemodule[mag-01]
\input mathfix %Bugfix by Taco
%D Hoping that this will be part of the core soon.

\setuptyping[style=\ttx\setupinterlinespace]
\setupheadertexts[section]

\setupbodyfontenvironment	[default][em=italic]

\definetextbackground
  [example]
  [width=\textwidth,
   background=color,
   backgroundcolor=lightgray,
   frame=off,
   leftoffset=1em,
   rightoffset=1em,
   location=paragraph,
   after={\blank[small]},
   before={\blank[small]}]

\def\ShowExample
  {\startexample
%     \nobreak
    \typebuffer
   \stopexample
   \getbuffer}

% When things go wrong
% \def\ShowExample
%   {\hairline
%    \typebuffer
%    \hairline
%    \getbuffer}


\setvariables
  [magazine]
  [title={Using \textbackslash startalign and friends},
   author=Aditya Mahajan,
   date=\currentdate,
  ]

\startbuffer[abstract]
Mathalignment support has been recently added into \CONTEXT. This document is
an attempt to explain the usage of \tex{startalign} and
\tex{startmathalignment}. It also explains the features of
\tex{startmathmatrix} and \tex{startmathcases}.  Examples are used to illustrate how to use various
options.
\stopbuffer

\starttext \setups[titlepage] \setups[title]


\section{Introduction}
\tex{startalign} and \tex{startmathalignment} macros provides an easy and
elegant way to type multiline equations. As the names suggests, they are
designed for {\em aligned} equations.  This document is a summary of their
various configurable features and provides examples of different usages. Both
\tex{startalign} and \tex{startmathalignment} can be used interchangeably.
\tex{startalign} follows the naming convention of \AMSTEX\ while
\tex{startmathalignment} is named according the \CONTEXT\ naming conventions.
In this document, I will use \tex{startalign}; primarily because it uses less
typing.


\section{Simple Alignment}
By default, \tex{startalign} provides two columns, the first is right aligned
and the second is left aligned. This is useful when one wants to align
equations at \type{=} sign.
\startbuffer
\startformula \startalign
  \NC a_1 x + b_1 y \NC = c_1 \NR
  \NC a_2 x + b_2 y \NC = c_2 \NR
\stopalign \stopformula
\stopbuffer
\ShowExample

Lets look at how this is working. The \tex{startformula} starts the \CONTEXT\
display mode, \tex{startalign} moves to the multiline display mode. \tex{NC}
starts a {\em New Column} and \tex{NR} starts a {\em New Row}. By default,
there are only two columns, first aligned right and the second left. There can
be arbitrary number of rows.

It is possible to increase the number of columns and their alignment.

\subsection{Increasing the number of columns}
The number of columns can be increased by passing the option \type{n=<cols>}
to \tex{startalign}, where \type{<col>} specifies the number of desired
columns. By default, all new columns are left aligned.
\startbuffer
\startformula \startalign[n=3]
  \NC a_1 x + b_1 y \NC = c_1 \NC =  d_1 u + e_1 v \NR
  \NC a_2 x + b_2 y \NC = c_2 + c_3 \NC =  d_2 u + e_2 v + f_1 w\NR
\stopalign \stopformula
\stopbuffer
\ShowExample

\subsection{Modifying Column Alignment}
The default column alignment is \type{right,left,left,}\unknown. This can be
changed by using the option \type<<align=>> to \tex{startalign}. This option
accepts a comma separated list of entries, each of which is \type{right},
\type{left} or \type{middle}.
For example, to get the second column to be middle aligned, we can specify
\type<<[n=3, align={right,middle,left}]>>.

\startbuffer
\startformula \startalign[n=3, align={right,middle,left}]
  \NC a_1 x + b_1 y \NC = c_1 \NC =  d_1 u + e_1 v \NR
  \NC a_2 x + b_2 y \NC = c_2 + c_3 \NC =  d_2 u + e_2 v + f_1 w\NR
\stopalign \stopformula
\stopbuffer
\ShowExample

Oops, this doesn't look too good. We need to specify each \type{=} sign as a
separate column.
\startbuffer
\startformula \startalign[n=4, align={right,middle,middle,left}]
  \NC a_1 x + b_1 y \NC = \NC c_1 \NC =  d_1 u + e_1 v \NR
  \NC a_2 x + b_2 y \NC = \NC c_2 + c_3 \NC =  d_2 u + e_2 v + f_1 w\NR
\stopalign \stopformula
\stopbuffer
\ShowExample

A useful application to change the default alignment is writing a short
description on the left. For example
\startbuffer
\startformula \startalign[n=3, align={left,right,left}]
  \NC \NC 12(x-1) + 20(y-3) + 14(z-2) \NC = 0 \NR
  \NC \text{which is same as } \qquad \NC 6x + 10y + 7z \NC = 0 \NR
\stopalign \stopformula
\stopbuffer
\pagereference[desc]
\ShowExample
See \at{page}[comments] for a more elaborate way of adding descriptions (or
comments) to equations.


\section{Side by Side Aligns}
Sometimes one wants more than one align placed side by side. \CONTEXT\
provides two ways to achieve this. Let us call the number of aligns as {\em
pairs}.  The simplest way to specify more than one pair is pass an option
\type{m=<pairs>} to \tex{startalign}, where \type{<pairs>} is the number of
desired pairs.
\startbuffer
\startformula \startalign[m=2]
  \NC a_1 x + b_1 y \NC = c_1 \NC d_1 u + e_1 v \NC = f_1 \NR
  \NC a_2 x + b_2 y \NC = c_2 \NC d_2 u + e_2 v \NC = f_2 \NR
\stopalign \stopformula
\stopbuffer
\ShowExample

The distance between the pairs can be increased by the option
\type<<distance>> of \tex{startalign}.
\startbuffer
\startformula \startalign[m=2,distance=5em]
  \NC a_1 x + b_1 y \NC = c_1 \NC d_1 u + e_1 v \NC = f_1 \NR
  \NC a_2 x + b_2 y \NC = c_2 \NC d_2 u + e_2 v \NC = f_2 \NR
\stopalign \stopformula
\stopbuffer
\ShowExample

A combination of \type<<[m=...,n=...]>> can be used.
\startbuffer
\startformula \startalign[m=2,distance=8em,n=5,
  align={right,middle,middle,middle,left}]
  \NC 0 \NC < \NC 2x + 5y \NC < \NC 10
  \NC 4 \NC < \NC 3x +  y \NC < \NC 9  \NR
  \NC 3 \NC < \NC 2y + 3z \NC < \NC 15
  \NC 10\NC < \NC 8y + 5z \NC < \NC 20 \NR
\stopalign \stopformula
\stopbuffer
\ShowExample


Sometimes, one simply wants to display two separate set of equations side by
side. For such applications the above pairs mode can be cumbersome to work
with.  There is another alternative in \tex{startformulas}

\startbuffer
\startformulas
  \startformula \startalign
    \NC a_1 x + b_1 y \NC = c_1 \NR
    \NC a_2 x + b_2 y \NC = c_2 \NR
  \stopalign \stopformula
  \startformula \startalign
    \NC d_1 u + e_1 v \NC = f_1 \NR
    \NC d_2 u + e_2 v \NC = f_2 \NR
  \stopalign \stopformula
\stopformulas
\stopbuffer
\ShowExample

More than two groups can also be placed.
\startbuffer
\startformulas
    \dorecurse{5}{\startformula
        \startalign[n=3,align={middle,middle,middle}]
            \NC a  \NC = \NC b  \NR
            \NC 2a \NC = \NC 2b \NR
        \stopalign
    \stopformula}
\stopformulas
\stopbuffer
\ShowExample

The system of equations need not have the same number of lines.
\startbuffer
\startformulas
  \startformula \startalign
    \NC 2x + 3 \NC = 7 \NR
    \NC 2x \NC = 4 \NR
    \NC x \NC = 2 \NR
  \stopalign \stopformula
  \startformula \startalign
    \NC x^2 + 2x \NC = 3 \NR
    \NC x^2 + (3-1)x - 3 \NC = 0 \NR
    \NC x(x + 3) -1(x + 3) \NC = 0 \NR
    \NC (x + 3)(x - 1) \NC = 0 \NR
    \NC x \NC = -3 \text{ or } 1 \NR
  \stopalign \stopformula
\stopformulas
\stopbuffer
\ShowExample


\section{Equation Numbering and Referring}
To number multiline displays, two things need to be done. Write
\tex{placeformula} before \tex{startformula} to start up equation numbering.
To actually number the equations, you need to type \type{[+]} with each
\tex{NR}.

\startbuffer
\placeformula
\startformula \startalign
  \NC a_1 x + b_1 y \NC = c_1 \NR[+]
  \NC a_2 x + b_2 y \NC = c_2 \NR[+]
\stopalign \stopformula
\stopbuffer
\ShowExample

This numbering mechanism provides a lot of flexibility. If we want to number
only some specific equations, add \type<<[+]>> to only those equations.
Suppose in the above example, we want to only number the second equation.
\startbuffer
\placeformula
\startformula \startalign
  \NC a_1 x + b_1 y \NC = c_1 \NR
  \NC a_2 x + b_2 y \NC = c_2 \NR[+]
\stopalign \stopformula
\stopbuffer
\ShowExample

Some more examples \unknown
\startbuffer
\placeformula
\startformula \startalign[n=3, align={right,middle,left}]
  \NC a_1 x + b_1 y \NC = c_1 \NC =  d_1 u + e_1 v \NR[+]
  \NC a_2 x + b_2 y \NC = c_2 + c_3 \NC =  d_2 u + e_2 v + f_1 w\NR
\stopalign \stopformula
\stopbuffer
\ShowExample

While specifying number of pairs by \type{m=<pairs>}, it is not possible to
number each pair. \tex{startformulas} makes it easy to number equations from
all pairs.
\startbuffer
\placeformula
\startformula \startalign[m=2]
  \NC a_1 x + b_1 y \NC = c_1 \NC d_1 u + e_1 v \NC = f_1 \NR
  \NC a_2 x + b_2 y \NC = c_2 \NC d_2 u + e_2 v \NC = f_2 \NR[+]
\stopalign \stopformula
\stopbuffer
\ShowExample
\startbuffer
\placeformula
\startformulas
  \startformula \startalign
    \NC a_1 x + b_1 y \NC = c_1 \NR[+]
    \NC a_2 x + b_2 y \NC = c_2 \NR
  \stopalign \stopformula
  \startformula \startalign
    \NC d_1 u + e_1 v \NC = f_1 \NR
    \NC d_2 u + e_2 v \NC = f_2 \NR[+]
  \stopalign \stopformula
\stopformulas
\stopbuffer
\ShowExample

\subsection{Referencing Numbered Alignments}
There is no fun numbering equations if can not refer to it. Well, referencing
an equation is easy. Instead of the \type<<[+]>>, you can specify
\type<<[eq:tag]>> and then refer to the equation using \type{\in[eq:tag]}. For
example,

\startbuffer
\placeformula
\startformula \startalign
  \NC a_1 x + b_1 y \NC = c_1 \NR[eq:1]
  \NC a_2 x + b_2 y \NC = c_2 \NR[eq:2]
\stopalign \stopformula
As seen from (\in[eq:1]) and (\in[eq:2]), referring equations is straight
forward.
\stopbuffer
\ShowExample

{\bf Note that you need to put the tag with the \tex{NR} and not with
\tex{placeformula} (as is done with single line equations).}

\subsection{Numbering subformula}
To get subformula numbering for any equation in the alignment, use
\tex{placesubformula} and pass the letter for the subformula to
\type{\NR[eq:tag][subformula letter]}.

\startbuffer
\placesubformula
\startformula \startalign
  \NC a_1 x + b_1 y \NC = c_1 \NR[+][a]
  \NC a_2 x + b_2 y \NC = c_2 \NR[+][b]
\stopalign \stopformula
\stopbuffer
\ShowExample

The subformulas can be referred to by using a tag instead of \type{+}.
\startbuffer
\placesubformula
\startformula \startalign
  \NC a_1 x + b_1 y \NC = c_1 \NR[eq:c][c]
  \NC a_2 x + b_2 y \NC = c_2 \NR[eq:d][d]
\stopalign \stopformula
(\in[eq:c]) and (\in[eq:d]) form a linear system of equations.
\stopbuffer
\ShowExample

Notice that the formula number did not increase. This allows for using the
same formula||number for separate subformulas. If you want to increment the
formula number with the next set of subformulas, an explicit
\tex{increment[formula]} needs to be given.

\startbuffer
\incrementnumber[formula]
\placesubformula
\startformula \startalign
  \NC a_1 x + b_1 y \NC = c_1 \NR[+][a]
  \NC a_2 x + b_2 y \NC = c_2 \NR[+][b]
\stopalign \stopformula
\stopbuffer
\ShowExample

If this kind of numbering is needed often, one can define a
\tex{placesubformulawithnumber} (or something with a shorter name)
\pagereference[placesubformulawithnumber]

\startbuffer
\def\placesubformulawithnumber{%
  \dodoubleempty\doplacesubformulawithnumber}

\def\doplacesubformulawithnumber[#1][#2]%#2 gobbles spaces
  {\incrementnumber[formula]
    \makesectionnumber[formula]
  \iffirstargument
    \rawreference{for}{#1}{\composedsectionnumber}
  \fi\placesubformula}

\placesubformulawithnumber
\startformula \startalign
  \NC a_1 x + b_1 y \NC = c_1 \NR[+][a]
  \NC a_2 x + b_2 y \NC = c_2 \NR[+][b]
\stopalign \stopformula
\stopbuffer
\ShowExample

This definition also allows referring to the main formula as well as the
subequations.

\startbuffer
% Define div and rot operators
\startmathcollection[default]
  \definemathcommand [div]      [nolop] {\mfunction{div}}
  \definemathcommand [rot]      [nolop] {\mfunction{rot}}
\stopmathcollection

\placesubformulawithnumber[eqn1]
 \startformula
 \startalign
   \NC \div  \vec{E} \NC =  \epsilon_{0}^{-1} \rho  \NR[eqn1:A][a]
   \NC \rot  \vec{E} \NC =  0 \NR
   \NC \div  \vec{B} \NC =  0 \NR[eqn1:B][b]
   \NC \rot  \vec{B} \NC =  \mu_{0} \vec{j} \NR
 \stopalign
 \stopformula
 See (\in[eqn1]) for the static Maxwell equations, where we are going to
 examine (\in[eqn1:A]) a bit further \unknown
\stopbuffer
\ShowExample

A mixed style of formula and subformula numbers is possible.
\startbuffer
\placesubformulawithnumber
\startformula \startalign
  \NC c^2 \NC = a^2 + b^2 \NR[+][a]
  \NC a^2 + b^2 \NC = c^2 \NR[+][b]
  \incrementnumber[formula]
  \NC d^2 \NC = e^2 \NR[+]
\stopalign \stopformula
\stopbuffer
\ShowExample

You can avoid typing a \tex{incrementnumber} each time by defining your own
command.
\startbuffer
\def\NNR{\incrementnumber[formula]\NR} %Numbered NR

\placesubformulawithnumber
\startformula \startalign
  \NC c^2 \NC = a^2 + b^2 \NR[+][a]
  \NC a^2 + b^2 \NC = c^2 \NR[+][b]
  \NC d^2 \NC = e^2 \NNR[+]
\stopalign \stopformula
\stopbuffer
\ShowExample

Suppose you want to number only a few equations by a subformula and have
normal formula numbering for others, it can be achieved by
\startbuffer
\def\CNR{\decrementnumber[formula]\NR} %Continued NR

\placeformula
\startformula \startalign
  \NC c^2 \NC = a^2 + b^2 \NR[+][a]
  \NC a^2 + b^2 \NC = c^2 \CNR[+][b]
  \NC d^2 \NC = e^2 \NR[+]
\stopalign \stopformula
\stopbuffer
\ShowExample

\section{Intertext}
Sometimes you want to place some text between two parts of math equations
without disturbing equation alignment. \CONTEXT\ provides \tex{startintertext}
environment to achieve this.

\startbuffer
\startformula \startalign
  \NC A_1 \NC= \left| \int_0^1 (x^2 - 3x)\, dx \right|
    + \left| \int_1^2 (x^2 -5x + 6)\, dx \right| \NR
  \startintertext
    Take limits of both integrals
  \stopintertext
  \NC \NC = \left| \frac{x^3}{3} - \frac{3}{2} x^2 \right|_0^1
    + \left| \frac {x ^3}{3} - 7 \frac{5}{2} x^2 + 6x \right|_1^2 \NR
    \NC \NC = \left| - \frac{7}{6} \right| + \left|\frac{14}{3} -
    \frac{23}{6}\right| = \frac{7}{6} + \frac{5}{6} = 2 \NR
\stopalign \stopformula
\stopbuffer
\ShowExample

\section{Aligned Matrices}
\CONTEXT\ provides \tex{startmatrix} for generic alignment mechanism.
\startbuffer
\startformula
  \startmatrix
    \NC A \NC B \NC C \NR
    \NC a \NC b \NC c \NR
    \NC 1 \NC 2 \NC 3 \NR
  \stopmatrix
\stopformula
\stopbuffer
\ShowExample

It can take a \type<<left=>> and \type<<right=>> option which can be used to
typeset matrices
\startbuffer
\startformula
  I = \startmatrix[left={\left(\,},right={\,\right)}]
    \NC 1 \NC 0 \NC 0 \NR
    \NC 0 \NC 1 \NC 0 \NR
    \NC 0 \NC 0 \NC 1 \NR
  \stopmatrix
\stopformula
\stopbuffer
\ShowExample

It is possible to \tex{definemathmatrix} to use the construct repeatedly.
\startbuffer
% Paranthesis
\definemathmatrix
  [pmatrix]
  [left={\left(\,},right={\,\right)}]

% Brackets
\definemathmatrix
  [bmatrix]
  [left={\left[\,},right={\,\right]}]

% Curly braces
\definemathmatrix
  [Bmatrix]
  [left={\left\{\,},right={\,\right\}}]

% vertical bars
\definemathmatrix
  [vmatrix]
  [left={\left\vert\,},right={\,\right\vert}]

% double vertical bars
\definemathmatrix
  [Vmatrix]
  [left={\left\Vert\,},right={\,\right\Vert}]

\startformula
  I = \startpmatrix
    \NC 1 \NC 0 \NC 0 \NR
    \NC 0 \NC 1 \NC 0 \NR
    \NC 0 \NC 0 \NC 1 \NR
  \stoppmatrix
  = \startbmatrix
    \NC 1 \NC 0 \NC 0 \NR
    \NC 0 \NC 1 \NC 0 \NR
    \NC 0 \NC 0 \NC 1 \NR
  \stopbmatrix
  = \startBmatrix
    \NC 1 \NC 0 \NC 0 \NR
    \NC 0 \NC 1 \NC 0 \NR
    \NC 0 \NC 0 \NC 1 \NR
  \stopBmatrix
\stopformula
\startformula
  \startvmatrix
    \NC a \NC b \NR
    \NC c \NC d \NR
  \stopvmatrix
  \quad
  \startVmatrix
    \NC a \NC b \NR
    \NC c \NC d \NR
  \stopVmatrix
\stopformula
\stopbuffer
\ShowExample

It is possible to change the alignment of columns using \type{align=} option.
\startbuffer
\startformula
  \text{Let } A = \startpmatrix[align={left,right}]
    \NC 1 \NC 2  \NR
    \NC 3 \NC -5 \NR
  \stoppmatrix
\stopformula
\stopbuffer
\ShowExample

Sometimes extra space is needed between rows. \tex{noalign} can be used to
provide that space.
\pagereference[needspace]

\start %To limit newmat
\startbuffer
\usemodule[newmat] %Needed for \dfrac

\gdef\needspace{\noalign{\vskip .15\bodyfontsize}}

\startformula
  \startBmatrix
    \NC 1 \NC \dfrac 12 \NR
    \NC 3 \NC 2 \NR
  \stopBmatrix
  \quad \text{ vs } \quad
  \startBmatrix
    \needspace
    \NC 1 \NC \dfrac 12 \NR
    \needspace
    \NC 3 \NC 2 \NR
  \stopBmatrix
\stopformula
\stopbuffer
\ShowExample
\stop

%D Why is smallmatrix not defined??
% There is a \type{smallmatrix} environment to define matrices for subscripts
% superscripts and inline math.
% \startbuffer
% Consider a matrix $A = (\startsmallmatrix \NC a \NC b \NR \NC c \NC d \NR
% \stopsmallmatrix)$ \unknown
% \stopbuffer
% \ShowExample

\section{Aligned limits}
Sometimes one wants to have multiple lines in the limit. \TEX\ provides
\tex{atop} for multiple limits. \CONTEXT\ provides a more general purpose
\tex{startsubstack} for this purpose.

\startbuffer
\startformula
  \sum_{\startsubstack
    1 \le i \le p \NR
    1 \le j \le q \NR
    1 \le k \le r \NR
  \stopsubstack}
  a_{ij}b_{jk}c_{ki}
\stopformula
\stopbuffer
\ShowExample

\subsection{Some other macros for limits}
Sometimes, long limits take too much space, and the resulting expression does
not look good.
\startbuffer
\startformula
  X = \sum_{1\le i \le j \le n} X_{ij}
\stopformula
\stopbuffer
\ShowExample

For text mode, \TEX\ has \tex{clap}, \tex{llap} and \tex{rlap} macros that
hide the width of the box. Similar macros for math mode can be defined (Herbert
Voss' solution)

\startbuffer
\def\mathllap{\mathpalette\domathllap}

\def\domathllap#1#2{%
  \llap{$\mathsurround=0pt#1{#2}$}}

\def\mathclap{\mathpalette\domathclap}

\def\domathclap#1#2{%
  \clap{$\mathsurround=0pt#1{#2}$}}

\def\mathrlap{\mathpalette\domathrlap}

\def\domathrlap#1#2{%
  \rlap{$\mathsurround=0pt#1{#2}$}}

\startformula
  X = \sum_{\mathclap{1\le i \le j \le n}} X_{ij}
\stopformula
\stopbuffer
\ShowExample



\subsection{Smashing Limits}
Having stacked limits in parenthesis causes problems.
\startbuffer
\startformula
  P = \left( \sum_{\startsubstack
    1 \le i \le p \NR
    1 \le j \le q \NR
    1 \le k \le r \NR
  \stopsubstack}
  a_{ij}b_{jk}c_{ki} \right)
\stopformula
\stopbuffer
\ShowExample

% \startbuffer
% \startformula
%   P = \left(\startmatrix \displaystyle
%     \NC \sum_{\startsubstack
%       1 \le i \le p \NR
%       1 \le j \le q \NR
%       1 \le k \le r \NR
%     \stopsubstack}
%     a_{ij}b_{jk}c_{ki}\NR \stopmatrix
%     \right) \text{is this aligned}
% \stopformula
% \stopbuffer
% \ShowExample
%D Baseline not aligned.

One way to get the right size for the parenthesis is to \tex{smash} them.
\startbuffer
\startformula
  P = \left(\vphantom{\sum}\smash[d]{\sum_{\startsubstack
      1 \le i \le p \NR
      1 \le j \le q \NR
      1 \le k \le r \NR
    \stopsubstack}}
    a_{ij}b_{jk}c_{ki}
  \right)
  \vphantom{\sum_{\startsubstack
      1 \le i \le p \NR
      1 \le j \le q \NR
      1 \le k \le r \NR
    \stopsubstack}}
\stopformula
\stopbuffer
\ShowExample

In general if you do not want sub or super||scripts to contribute to the
height of the \tex{left} \tex{right} parenthesis, you can \tex{smash} them.
Lets define a macro \tex{opsmash} that does this.

\startbuffer
\def\opsmash#1{\doopsmash#1\stopdosmash\smash[td]{#1}}
\def\stopdosmash{}
\def\doopsmash#1#2\stopdosmash{\vphantom{#1}}
%#1 is the operator, #2 the limits

\startformula
  \text{original} \quad \left( 1 + {\prod_{i = 1}^n } p_i \right)^2 \quad
  \text{ vs smashed} \quad
%   \left( 1 + \vphantom{\prod}\smash[td] {\prod_{i = 1}^n } p_i \right)^2
  \left( 1 + \opsmash{\prod_{i = 1}^n } p_i \right)^2
\stopformula
\stopbuffer
\ShowExample

% Sometimes it is useful to smash the width of subscripts. One can define a
% \tex{smashoperator} for this purpose.
% \startbuffer
% \def\smashoperator{%
%   \dodoubleempty\dosmashoperator}

% \def\dosmashoperator[#1][#2]%
%   \ifsecondargument
%   %l r or lr
%   \else
%   \dodosmashoperator#2\relax
% \startformula
%   X = \sum_{1 \le i \le j \le n} X_{ij}
%   X = \smashoperator[\sum_{1 \le i \le j \le n}] X_{ij}
% \stopformula
% \stopbuffer
% \ShowExample
%D Work on copying from mathtools.


\section{Cases}
\CONTEXT\ provides support for the case construct. The simplest use is
\startbuffer
\startformula
  f(x) = \startcases
    \NC x   \MC 0 \le x < 1 \NR
    \NC 1-x \MC 1 \le x < 2 \NR
    \NC 0   \NC otherwise   \NR
  \stopcases
\stopformula
\stopbuffer
\ShowExample

This consists of two columns with a big brace on the left. There are two ways
of specifying the second column --- \tex{MC} (Math Column) and \tex{NC} (New
Column). If \tex{MC} is used, the second column is in \tex{math mode}, with
\tex{NC} it is in \quote{text mode}.

The bracket on the left can be configured by passing an argument to
\type{startcases}.
\startbuffer
\startformula
  f(x) = \startcases[left={\left(\,}]
    \NC x   \MC 0 \le x < 1 \NR
    \NC 1-x \MC 1 \le x < 2 \NR
    \NC 0   \NC otherwise   \NR
  \stopcases
\stopformula
\stopbuffer
\ShowExample

The distance between the two columns can be changed using \type<<distance=>>
option.
\startbuffer
\startformula
  f(x) = \startcases[distance=10em]
    \NC x   \MC 0 \le x < 1 \NR
    \NC 1-x \MC 1 \le x < 2 \NR
    \NC 0   \NC otherwise   \NR
  \stopcases
\stopformula
\stopbuffer
\ShowExample


\subsection{Numbered Cases}
Sometimes, each of the rows of the case need to be numbered. This can be done
by adding \tex{NR[+]} or \tex{NR[eq:label]}. The distance between the case
environment and the number is controlled by \type<<numberdistance>>.
\startbuffer
\placeformula \startformula
  f(x) = \startcases[numberdistance=10em]
    \NC x   \MC 0 \le x < 1 \NR[eq:1]
    \NC 1-x \MC 1 \le x < 2 \NR[eq:2]
    \NC 0   \NC otherwise   \NR[eq:3]
  \stopcases
\stopformula
(\in[eq:1]) shows that $f(x)$ is linear increasing between $0$ and $1$ and
(\in[eq:2]) shows that it is linear decreasing between $1$ and $2$.
\stopbuffer
\ShowExample

It is possible to give subformula numbers to each subcase. (We will reuse
\tex{placesubformulawithnumber} defined \at{page}[placesubformulawithnumber])

\startbuffer
\placesubformulawithnumber[eq:cases] \startformula
  f(x) = \startcases[numberdistance=10em]
    \NC x   \MC 0 \le x < 1 \NR[eq:4][a]
    \NC 1-x \MC 1 \le x < 2 \NR[eq:5][b]
    \NC 0   \NC otherwise   \NR[eq:6][c]
  \stopcases
\stopformula
Condider $f(x)$ as defined in (\in[eq:cases]). (\in[eq:4]) shows that $f(x)$
is linear increasing between $0$ and $1$ and (\in[eq:5]) shows that it is
linear decreasing between $1$ and $2$.
\stopbuffer
\ShowExample

If a number for all the cases in not required, the case construct can be
hidden using \tex{startalign}
\startbuffer
\placesubformulawithnumber[eq:cases1] \startformula \startalign
  \NC f(x) = \startcases[numberdistance=10em]
    \NC x   \MC 0 \le x < 1 \NR[eq:7][a]
    \NC 1-x \MC 1 \le x < 2 \NR[eq:8][b]
    \NC 0   \NC otherwise   \NR[eq:9][c]
  \stopcases \NR
\stopalign \stopformula
Condider $f(x)$ as defined in (\in[eq:cases1]). (\in[eq:7]) shows that $f(x)$
is linear increasing between $0$ and $1$ and (\in[eq:8]) shows that it is
linear decreasing between $1$ and $2$.
\stopbuffer
\ShowExample

\subsection{Display cases}
Each row in the \tex{startcases} envrionment is set in inline math mode.
Consider, for example,
\startbuffer
\startformula
  a = \startcases
    \NC E = mc^2 \NC nothing interesting to see here \NR
    \NC \int_0^1 x - 3 d\,x \NC Integral is in text mode \NR
  \stopcases
\stopformula
\stopbuffer
\ShowExample

You can use \type<<style=\displaystyle>> option to make things come out in
display mode.
\startbuffer
\definemathcases[displaycases][style=\displaystyle]
\startformula
  a = \startdisplaycases
    \NC E = mc^2 \NC nothing interesting to see here \NR
    \NC \int_0^1 x - 3 d\,x \NC Integral is in text mode \NR
  \stopdisplaycases
\stopformula
\stopbuffer
\ShowExample

\section{Some Advanced Tips}

\subsection{Defining \type{amsmath} like commands}
\type{amsmath} package for \LATEX\ defines some useful multiline display
environments like \type{split} and \type{gather}. It is easy to replicate
these features with the alignment mechanism of context.

Consider the split environment, where only the last equation is numbered.
Notice that to get the numbering correct, the last line {\em should not} end
with a \tex{NR}.
\start %To keep the definition of split local. Defined again using mathmatrix
\startbuffer
\def\startsplit
  {\startalign} % no number by default

\def\stopsplit
  {&\doalignNR[+][]\crcr % for a number on last line
   \stopalign}

\placeformula \startformula \startsplit
  \NC f(x) \NC = (x+2)^2 + 2(x+2) + 3 \NR
  \NC \NC = x^2 + 4x + 4 + 2x + 4 + 3 \NR
  \NC \NC = x^2 + 6x + 11
\stopsplit \stopformula
\stopbuffer
\ShowExample
\stop %Stop local group
If you want only the last line of the equation to be numbered, it is simpler
to use \tex{startalign} and just number the last line using \type<<[+]>> or
\type<<[eq:tag]>> with the last \tex{NR}. If you want the equation number to
be present in the center of the display, see the definition in
\in{section}[sec:split].

We can also define a \type{gather} environment. This environment centers all
the lines.
\startbuffer
\definemathalignment
  [gather]
  [n=1,align=middle]

\startformula \startgather
  (a+b)^2 = a^2 + 2ab + b^2 \NR
  (a+b)^3 = a^3 + 3ab(a+b) + b^3 \NR
\stopgather \stopformula
\stopbuffer
\ShowExample

Suppose, we want the equations to be left aligned. We can define a
\type{lgather} environment to achieve this.
\startbuffer
\definemathalignment
  [lgather]
  [n=1,align=left]

\startformula \startlgather
  (a+b)^2 = a^2 + 2ab + b^2 \NR
  (a+b)^3 = a^3 + 3ab(a+b) + b^3 \NR
\stoplgather \stopformula
\stopbuffer
\ShowExample

For multi-pair alignments, it is possible to have {\em spread out} alignments,
similar to \type{flalign} environment of \type{amsmath}.
\startbuffer
\definemathalignment
  [flalign]
  [m=2, distance=5em plus 1 fil] %We need to set a default value for m

\startformula \startflalign[m=3]
  \NC i_{11} \NC = 0.25 \NC i_{12} \NC = i_{21} \NC i_{13} \NC = i_{23} \NR
  \NC i_{21} \NC = \frac{1}{3} i_{11} \NC i_{22} \NC = 0.5 i_{12} \NC i_{23}
  \NC =  i_{31} \NR
  \NC i_{31} \NC = 0.33 i_{22} \NC i_{32} \NC = 0.15 i_{32} \NC i_{33} \NC =
  i_{11} \NR
\stopflalign \stopformula
\stopbuffer
\ShowExample

This environment can be used to mix left and middle align equations, without
changing system wide \tex{setupformulas}.
\startbuffer
\startformula \startalign
  \NC f(x) \NC = \int \frac {1}{x^2}\, dx \NR
\stopalign \stopformula
\startformula \startflalign
  \NC f(x) \NC = \int \frac {1}{x^2}\, dx \NR
\stopflalign \stopformula
\stopbuffer
\ShowExample

Another usage is writing a description on the left. (Compare from an example
given on \at{page}[desc] and \in{section}[comments].)
\startbuffer
\startformula \startflalign
  \NC\NC \NC 12(x-1) + 20(y-3) + 14(z-2) \NC = 0 \NR
  \NC \text{which is same as } \NC\NC 6x + 10y + 7z \NC = 0 \NR
\stopflalign \stopformula
\stopbuffer
\ShowExample

\subsection[comments]{Writing explainations with aligned equations}
Sometimes one wants to write an explaination with each step of an equation.

\startbuffer
 \definemathalignment
     [doaligncomments]
     [m=3,distance=4em plus 1 fil]

\def\startaligncomments#1\stopaligncomments{%
   \def\Comment##1\NR{\NC\NC\text{##1}\dodoubleempty\doComment}
   %\qquad is for some space between the comment and the number
   \def\doComment[##1][##2]{%
    \iffirstargument \qquad \fi
    \NR[##1][##2]\NC\NC}
   \startdoaligncomments
   \NC\NC#1\stopdoaligncomments}

\placeformula\startformula \startaligncomments
    \NC 2x + 3     \NC = 5     \Comment Add -3 to both sides   \NR
    \NC 2x + 3 - 3 \NC = 5 - 3 \Comment Simplify               \NR
    \NC 2x         \NC = 2     \Comment Divide both sides by 2 \NR
 \stopaligncomments \stopformula
\stopbuffer
\ShowExample

If one simple wants to add comments to left aligned equations then one can use
\startbuffer
 \definemathalignment
    [dogathercomments]
    [n=1,align={left},m=3,distance=4em plus 1 fil]

 \def\startgathercomments#1\stopgathercomments{%
    \def\Comment##1\NR{\NC\text{##1}\dodoubleempty\doComment}
    \def\doComment[##1][##2]{%
      \iffirstargument \qquad \fi
      \NR[##1][##2]\NC}
    \startdogathercomments\NC#1\stopdogathercomments}

 \startformula \startgathercomments
    \NC 2x + 3     = 5     \Comment Add -3 to both sides   \NR
    \NC 2x + 3 - 3 = 5 - 3 \Comment Simplify               \NR
    \NC 2x         = 2     \Comment Divide both sides by 2 \NR
 \stopgathercomments \stopformula
\stopbuffer
\ShowExample

If the explaination is to be given on the left, one can write
\startbuffer
\definemathalignment
  [doleftcomments]
  [n=2,m=3,distance=4em plus 1 fil]

\def\startleftcomments#1\stopleftcomments{%
  \def\Comment##1\NC{\NC\NC\text{##1}\NC}
  \startdoleftcomments#1\stopdoleftcomments}

\startformula \startleftcomments
  \Comment                       \NC 2x + 3     \EQ 5    \NR
  \Comment Add -3 to both sides  \NC 2x + 3 - 3 \EQ 5- 3 \NR
  \Comment Simplify              \NC 2x         \EQ 2    \NR
  \Comment Divide both sides by 2\NC  x         \EQ 2    \NR
\stopleftcomments \stopformula
\stopbuffer
\ShowExample


\subsection{\type{aligned} family of commands}
\type{amsmath} also provides \type{aligned} and \type{gathered} commands, that
can be used to group equations. It is easy to copy these commands using
\tex{startmathmatrix}.
\startbuffer
\definemathmatrix
  [aligned]
  [n=2,distance=0pt,align={right,left},style=\displaystyle]

\definemathmatrix
  [gathered]
  [n=1,align=middle,style=\displaystyle]

\startformula
  a = \frac{\left(\startaligned
    \NC xy \NC {}+ xy + xy \NR
    \NC    \NC {}+ xy + xy \NR
  \stopaligned \right)}{z}
  = \frac{\left(\startgathered
    \NC xy  + xy + xy \NR
    \NC   {}+ xy + xy \NR
  \stopgathered \right)}{z}
\stopformula
\stopbuffer
\ShowExample

The \type<<location=top|middle|bottom>> option of \tex{definemathmatrix} can
be used alter the baseline of aligned and gathered stuff.
\startbuffer
\startformula \startgather
  \NC f(x,y) \startaligned[location=top,align=left]
      \NC = (2x+3y)^2 - 4xy \NR
      \NC = 4x^2 + 9y^2 + 12xy -4xy \NR
      \NC = 4x^2 + 9y^2 + 8xy \NR
    \stopaligned \NR
  \NC \frac{\partial f(x)}{\partial x} = 8(x + 1)
\stopgather \stopformula
\stopbuffer
\ShowExample
  

\subsection[sec:split]{split (again)}
\type{mathmatrix} can also be used to define a split environment, with
equations number at the center of the display.

\startbuffer
\definemathmatrix
  [dosplit]
  [n=2,distance=0pt,align={right,left},style=\displaystyle]

%D Need to change domatrixNC to have a {} so that bin operators
%D are treated properly

\def\startsplit#1\stopsplit{
  \def\dodomatrixNC
    {\gdef\domatrixNC{\endmath&{}}}
  \startdosplit#1\stopdosplit}

\placeformula \startformula \startsplit
  \NC f(x) \NC = (x+2)^2 + 2(x+2) + 3 \NR
  \NC \NC = x^2 + 4x + 4 + 2x + 4 + 3 \NR
  \NC \NC = x^2 + 6x + 11 \NR
\stopsplit \stopformula
\stopbuffer
\ShowExample

The interline spacing is not perfect as the following example shows.

\startbuffer
\placeformula \startformula \startsplit
  \NC f_{h,\varepsilon}(x,y)
  \NC = \varepsilon \bold{E}_{x,y} \int_0^{t_\varepsilon}
  L_{x,y_\varepsilon(\varepsilon u)}\varphi(x)\,du\NR
  \NC \NC = h\int L_{x,z}\varphi(x)\rho_x(dz)\NR
  \NC \NC\quad+h\biggl[\frac{1}{t_\varepsilon}\biggl(\bold{E}_{y}
  \int_0^{t_\varepsilon}L_{x,y^x(s)}\varphi(x)\,ds
  -t_\varepsilon\int L_{x,z}\varphi(x)\rho_x(dz)\biggr)\NR
  \NC \NC\phantom{{=}+h\biggl[}+\frac{1}{t_\varepsilon}
  \biggl(\bold{E}_{y}\int_0^{t_\varepsilon}L_{x,y^x(s)}
  \varphi(x)\,ds -\bold{E}_{x,y}\int_0^{t_\varepsilon}
  L_{x,y_\varepsilon(\varepsilon s)}
  \varphi(x)\,ds\biggr)\biggr]\NR
  \NC \NC=h\widehat{L}_x\varphi(x)+h\theta_\varepsilon(x,y), \NR
\stopsplit \stopformula
\stopbuffer
\ShowExample

\section{Some Problems}

\subsection{What happened to my square brackets?}
\startbuffer
\startformula \startgather
  [p] = 100 \NR
  [v] = 200 \NR
\stopgather \stopformula
\stopbuffer
\ShowExample

This is not what you would expect. An easy way to avoid such unexpected
behavior is to start each line with \tex{NC}.
\startbuffer
\startformula \startgather
  \NC [p] = 100 \NR
  \NC [v] = 200 \NR
\stopgather \stopformula
\stopbuffer
\ShowExample

\section{Compatibility with \type{amsmath}}
\tex{startalign} provides a compatibility mode with \type{amsmath} syntax,
which makes it easier to reuse work written in \LATEX.
\startbuffer
\placeformula \startformula \startalign
  f(x) &= x^3 + 2x^2 + 3 \\
  f'(x) &= 3x^2 + 4x \\
\stopalign \stopformula
\stopbuffer
\ShowExample

However, Hans does not like the syntax, especially the {\em loose label} for
referring equations. This compatibility feature may disappear in the future. So,
I suggest not to use it. There are subtle differences from the \type{amsmath}
syntax, and it is much easier (and logical) to follow the \CONTEXT\ syntax.

\section{Missing Features}
Somewhere between March and Arpril, \tex{startalign} lost the ability to break
equations across pages. Hopefully, it will be added back soon.

As compared to \AMSTEX\ and \type{amsmath} package of \LATEX, the only display
math environment missing from \CONTEXT\ is \type{multline}. I do not
completely understand what is the expected behavior of \type{multline}
environment. If someone understands what it is supposed to do, and needs that
feature, make a feature request \type{:-)}.

The definitions of \type{aligned}, \type{gathered} and \type{split} here are
not perfect. However they fit my needs \type{:-)}. If you want proper support
for these environments, ask on the mailing list.

Subformula numbering is a kludge. The subformula number needs to be specified
manually.  Using mixed formula and subformula number needs some user
intervention.  However, it is possible to make these transparent by defining
your own macros.



\stoptext
\setups[lastpage]