\setupcolors[state=start]
\definecolor [BufferColor] [r=1,g=1,b=0.5]

\setuptyping[option=color]
\gdef\ShowExample{
  \blank
  \framed[align=normal,width=broad,frame=off,background=screen]
  {\tfx \typebuffer}
  \framed[align=normal,width=broad,frame=off,
  background=color,backgroundcolor=BufferColor] {\getbuffer}}

\starttext
\section{Basic Alignment}
The purpose of this document is to show how to do multi-line display equations 
in \CONTEXT. Hans has provided a configurable align environment that can be 
used for general purpose multiline display equations. Lets look at few 
examples to understand how it works. In many cases, we need to align a 
sequence of equations at the $=$ sign. This is how it can be done
\starttyping
\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

\stoptyping

\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




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} 
specifies to start a {\em New Column} is starting and \tex{NR} specifies to 
start a {\em New Row}. By default, the first column is right aligned and the 
second is left aligned. You can increase the number of alignments by 
specifying \type{n=?} as options to \tex{startalign}. By default all the new 
columns are left aligned.
\starttyping
\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

\stoptyping

\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



The default column alignment can be changed by using 
\type<<align={...,...,...}>> construct. This is a comma separated list, each 
value is either \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}]>>
\starttyping
\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

\stoptyping

\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



Oops, this doesn't look too good. We need to specify each \type{=} sign as a 
separate column.
\starttyping
\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

\stoptyping

\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



Sometimes one wants to have two columns of equations, next to one another.  
This can be done by specifying the number of blocks in \type<<m=?>>.
\starttyping
\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

\stoptyping

\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



The distance between the blocks can be increased by specifying (well you 
guessed it) \type<<distance>> in the parameters of align.
\starttyping
\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

\stoptyping

\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



However, this block mode can be cumbersome to work with. You need to work with 
two formulas at the same time and this can be confusing. There is another 
alternative in \tex{startformulas}
\starttyping
\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

\stoptyping

\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



More than two groups can also be placed.
\starttyping
\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

\stoptyping

\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



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

\starttyping
\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

\stoptyping

\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



If you only want to number a some specific equations, just add \type<<[+]>> to 
that equation only. Suppose in the above example, we want to only number the 
second equation.
\starttyping
\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

\stoptyping

\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



Some more examples \unknown
\starttyping
\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

\stoptyping

\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




\starttyping
\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

\stoptyping

\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


\starttyping
\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

\stoptyping

\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



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,

\starttyping
\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.

\stoptyping

\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.



{\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).}


\section{Some Advanced Tips}
Well, need to understand more myself before writing this. Write about 
\tex{setupalign}, \tex{definealign}. Give examples of defining \type<<gather>> 
and \type<<split>> environments.




\stoptext
