\usemodule[mag-01]

\usemodule[int-load]
\def\loadsetups{}
\usemodule[mod-00]

\setupcolors[state=start]


\def\loadsetups{\complexorsimple\loadsetups}

\def\simpleloadsetups
 {\complexloadsetups[cont-en.xml]}

\def\complexloadsetups[#1]%
 {\startXMLmapping[zero]
  \processXMLfilegrouped{#1}
  \stopXMLmapping}

\loadsetups[arrows.xml]

\setupheadertexts[section]

\setvariables
  [magazine]
  [title={Arrows in \CONTEXT},
   author=Aditya Mahajan,
   date=\currentdate,
  ]

\startbuffer[abstract]
This document describes how to use {\em extensible arrows} in \CONTEXT. It
also explains how you can define new arrows on your own.
\stopbuffer

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

\section{Introduction}
Sometimes one needs to typeset arrows like $\xrightarrow{\text{below}}{\text{above the
arrow}}$. \CONTEXT\ provides extensible arrows to get this result. This {\em
My Way} describes how to use extensible arrows and how to define new ones on
your own.

\section{Usage Syntax}
The following extensible arrows are defined in \CONTEXT.

\midaligned{\starttable[|l|m|]
  \NC \tex{xrightarrow        }  \NC \xrightarrow          \NC \NR
  \NC \tex{xleftarrow         }  \NC \xleftarrow           \NC \NR
  \NC \tex{xequal             }  \NC \xequal               \NC \NR
  \NC \tex{xRightarrow        }  \NC \xRightarrow          \NC \NR
  \NC \tex{xLeftarrow         }  \NC \xLeftarrow           \NC \NR
  \NC \tex{xLeftrightarrow    }  \NC \xLeftrightarrow      \NC \NR
  \NC \tex{xleftrightarrow    }  \NC \xleftrightarrow      \NC \NR
  \NC \tex{xmapsto            }  \NC \xmapsto              \NC \NR
  \NC \tex{xtwoheadrightarrow }  \NC \xtwoheadrightarrow   \NC \NR
  \NC \tex{xtwoheadleftarrow  }  \NC \xtwoheadleftarrow    \NC \NR
  \NC \tex{xrightharpoondown  }  \NC \xrightharpoondown    \NC \NR
  \NC \tex{xrightharpoonup    }  \NC \xrightharpoonup      \NC \NR
  \NC \tex{xleftharpoondown   }  \NC \xleftharpoondown     \NC \NR
  \NC \tex{xleftharpoonup     }  \NC \xleftharpoonup       \NC \NR
  \NC \tex{xleftrightharpoons }  \NC \xleftrightharpoons   \NC \NR
  \NC \tex{xrightleftharpoons }  \NC \xrightleftharpoons   \NC \NR
\stoptable}

The syntax of using these commands is
\startTEX
  \arrowname[options]{below}{above}
\stopTEX

\showsetup{xrightarrow}

where \type{<arrowname>} is one of the arrows shown above. The options effect
the spacing around the above and below material. It can be one of the keywords
or a number (which is converted to math units~\type{mu}.) Compare:

\def\below{\text{\framed{below}}}
\def\above{\text{\framed{above}}}
\midaligned{\starttable[|l|m|]
  \NC  \tex{xrightarrow        } \NC \xrightarrow        {\below}{\above} \NC\NR
  \NC  \tex{xrightarrow[none]  } \NC \xrightarrow  [none]{\below}{\above} \NC\NR
  \NC  \tex{xrightarrow[small] } \NC \xrightarrow [small]{\below}{\above} \NC\NR
  \NC  \tex{xrightarrow[medium]} \NC \xrightarrow[medium]{\below}{\above} \NC\NR
  \NC  \tex{xrightarrow[big]   } \NC \xrightarrow   [big]{\below}{\above} \NC\NR
  \NC  \tex{xrightarrow[50]    } \NC \xrightarrow    [50]{\below}{\above} \NC\NR
\stoptable}

All the arguments are optional, so you can also use
\startTEX
  \arrowname[option]{below}
  \arrowname{below}
  \arrowname[option]
  \arrowname
\stopTEX
for example\footnote{This is different from \AMSTEX\ syntax, where
\type<<\arrowname{above}>> places the material {\em above} the arrow.}

\midaligned{\starttable[|l|m|]
  \NC \type<<\xrightarrow{below}      >> \NC \xrightarrow{\below}     \NC\NR
  \NC \type<<\xrightarrow[big]{below} >> \NC \xrightarrow[big]{\below}\NC\NR
  \NC \type<<\xrightarrow[big]        >> \NC \xrightarrow[big]        \NC\NR
  \NC \type<<\xrightarrow             >> \NC \xrightarrow             \NC\NR
\stoptable}

\section{Defining new arrows}
There are two types of extensible arrows
\startitemize[r,text][stopper=]
  \item Those with a single arrow (e.g.\ \tex{xrightarrow}, \tex{xleftarrow},
    etc.) and,
  \item those with two arrows (e.g.\ \tex{xleftrightharpoons},
    \tex{leftrightharpoons} etc.)
\stopitemize
Here I will explain how to define both kinds of arrows. First you need to define
an {\em extensible arrow fill}, which consists of three parts, which define the
left, middle and right part of the arrow, where the middle part is stretched in
a way that the arrow is atleast as long as the material above and below it. This
can be define using \tex{mtharrowfill}, e.g.\ for \tex{xrightarrow} one defines
\startTEX
\def\rightarrowfill{\mtharrowfill \relbar \relbar \rightarrow}
\stopTEX 
Here \tex{relbar} is \math{\relbar} character, which is basically a horizontal
bar at the middle of math line. Thus \tex{rightarrowfill} is an arrow fill in
which the left part is \tex{relbar}, the middle stretchable part is \tex{relbar}
and the right part is \tex{rightarrow}. Similarly, for \tex{xleftarrow} one
defines
\startTEX
\def\leftarrowfill{\mtharrowfill \leftarrow \relbar \relbar}
\stopTEX 
and so on for different arrows.

An extensible arrow can be defined using the \tex{definearrow} command.
\showsetup{definearrow}
It can best be explained by means of an example. \tex{xrightarrow} is defined as
\startTEX
\definematharrow [xrightarrow]        [0359] [\rightarrowfill]
\stopTEX
The first argument is the name of the arrow (\tex{xrightarrow} in this case.)
The second argument consists of a set of 4 numbers and specify the spacing
correction in math units~\type{mu}. These numbers define:

% Where is the fun, if you do everything manually :-)
\defineconversion[ordinal][\enordinaldaynumber]

% Can 9*broad be calculated automatically?
\startitemize[ordinal,9*broad][stopper={ number:}]
  \item left arrow||tip correction
  \item right arrow||tip correction
  \item left space (multiplied by \tex{matharrfactor} and advanced by
    \tex{matharrextra})
  \item right space (multiplied by \tex{matharrfactor} and advanced by
    \tex{matharrextra})
\stopitemize

The third argument is the name of the extensible fill, that we defined earlier.
This gives us an extensible arrow of the first kind.

To define an extenisble arrow the second kind, (e.g.\ \tex{xrightleftharpoons})
we need to define two extensible fills. 
\startTEX
\def\rightharpoonupfill%
    {\mtharrowfill \relbar          \relbar \rightharpoonup}
\def\leftharpoondownfill%
    {\mtharrowfill \leftharpoondown \relbar \relbar        }
\stopTEX  
Next we need to tell \tex{definearrow} to stack them together.
\startTEX
\definematharrow [xrightleftharpoons] [3095,0359] 
                 [\rightharpoonupfill,\leftharpoondownfill]
\stopTEX
The second and the third set of arguments consist of comma separated values. The
first element of the second argument (\type{3095}) corresponds to the spacing
correction of top arrow fill (\tex{rightarrowupfill}). Similarly, \type{0359}
corresponds to bottom arrow fill \tex{leftharpoondownfill}). Stacking them on
top of each other we get
\math{\xrightleftharpoons[big]{\tex{leftharpoondownfill}}{\tex{rightharpoonupfill}}}.

\section{Concluding Comments}
This is just meant as a usage guide for {\em extensible arrows} in \CONTEXT,and
is by no means exhaustive. If you really want to understand the nitty gritty of
the implementation, you need to look at the code (in \type{math-ext.tex}).

\stoptext