\startAbstract

This article describes the \CONTEXT\ tabulate environment,
which can be used to typeset tables that are part of the
text flow. This mechanism differs from the \TABLE\ based
table mechanism, but recognizes the same preamble commands.
It offers automatic width calculations when typesetting
(multiple) paragraphs in tables and splits the tables over
pages.

\stopAbstract

\Keywords{tables, alignment, \ConTeXt}

In a text, tabulated information can be included either in
the text flow, fixed at the place it should appear, or it
can be included at a preferred place, but given some freedom
to float when there is no room. The tabulate commands
discussed here take care of the fixed alternative, while the
table commands are primary meant for floats. However, one is
free to use whatever suits best, because none of them are
limited to the cases mentioned.

While the table commands are in fact a layer around the
\TABLE\ package, the tabulate commands are written from
scratch. Both have a definition preamble, and to keep things
simple, the tabulate preamble keys are similar to those used
in tables. We use \type {\NC} to as column separators, and
\type {\NR} to go to the next row.

%\NC ditjes en datjes \NC links en rechts \NC hier en daar \NC \NR
%\NC zus en zo        \NC op en neer      \NC hot naar her \NC \NR

\startbuffer
\starttabulate[|l|c|r|]
\NC this and that \NC left and right \NC here and there \NC \NR
\NC such and so   \NC up and down    \NC on and on      \NC \NR
\stoptabulate
\stopbuffer

\typebuffer

\getbuffer

The three keys mean:

\starttabulate[|lT|p|]
\NC l \NC left aligned  \NC \NR
\NC c \NC centered      \NC \NR
\NC r \NC right aligned \NC \NR
\stoptabulate

There are also some spacing commands. These apply to both
line and paragraph columns.

\starttabulate[|lT|p|]
\NC i\sl n \NC set space left   \NC \NR
\NC j\sl n \NC set space right  \NC \NR
\NC k\sl n \NC set space around \NC \NR
\stoptabulate

In these three keys {\ttsl n} multiplies the spacing unit as
set up with \type {\setuptabulate} (default: .5em).

%\NC ditjes en datjes \NC links en rechts \NC hier en daar \NC \NR
%\NC zus en zo        \NC op en neer      \NC hot naar her \NC \NR

\startbuffer
\starttabulate[|l|k2c|r|]
\NC this and that \NC left and right \NC here and there \NC \NR
\NC such and so   \NC up and down    \NC on and on      \NC \NR
\stoptabulate
\stopbuffer

\typebuffer

\getbuffer

It is possible to specify the width of a column:

%\NC ditjes en datjes \NC links en rechts \NC hier en daar \NC \NR
%\NC zus en zo        \NC op en neer      \NC hot naar her \NC \NR

\startbuffer
\starttabulate[|lw(4cm)|w(4cm)l|r|]
\NC this and that \NC left and right \NC here and there \NC \NR
\NC such and so   \NC up and down    \NC on and on      \NC \NR
\stoptabulate
\stopbuffer

\typebuffer

\getbuffer

The main reason for writing these tabulate commands, was that
we wanted to typeset tables with paragraphs that would span
the full available width. The related preamble keys are:

\starttabulate[|lT|p|]
\NC w({\sl d}) \NC fixed width one liner   \NC \NR
\NC p({\sl d}) \NC fixed width paragraph   \NC \NR
\NC p          \NC maximum width paragraph \NC \NR
\stoptabulate

In the next example the first column has an unknown width,
the next one contains a left aligned paragraph and has a
width of 4cm. The third column has 2cm width one||liner,
while last paragraph column occupies the rest of the available
width.

\starttyping
\starttabulate[|l|p(4cm)l|w(2cm)|p|]
...
\stoptabulate
\stoptyping

A four column table with paragraph entries can be specified
by saying:

\starttyping
\starttabulate[|p|p|p|p|]
...
\stoptabulate
\stoptyping

Instead of retyping font switches, we can specify a font for
a column. In the next table, the preamble specifies \type
{[|lT|p|]}.

\starttabulate[|lT|p|]
\NC B \NC \bf boldface \NC \NR
\NC I \NC \it italic   \NC \NR
\NC R \NC \sl roman    \NC \NR
\NC S \NC \sl slanted  \NC \NR
\NC T \NC \tt teletype \NC \NR
\stoptabulate

For math there is:

\starttabulate[|lT|p|]
\NC m \NC in line math mode \NC \NR
\NC M \NC display math mode \NC \NR
\stoptabulate

Using the \type {f} key, it is possible to define arbitrary
font switches, for instance \type{f\bs}. There are some more
hooks:

\starttabulate[|lT|p|]
\NC f\tex{command} \NC font specification   \NC \NR
\NC b\arg{..}      \NC put before entry     \NC \NR
\NC a\arg{..}      \NC put after entry      \NC \NR
\NC h\tex{command} \NC do with entry (hook) \NC \NR
\stoptabulate

The next example shows how to apply a hook (\type{h}) and
also puts something around en entry.

\startbuffer
\starttabulate[|w(2cm)h\inframed|b{(}a{)}|p|]
\HC {Ugly} \NC indeed      \NC he said.     \NC \NR
\HC {Nice} \NC but useless \NC I would say. \NC \NR
\stoptabulate
\stopbuffer

\typebuffer

Here \type {\inframed} keeps the frame within the normal
line height and depth (this is a special case of \type
{\framed}). Watch careful: hooked entries are marked with
\type {\HC} and don't forget the braces, or whatever the
hook||command expects! This example turns up as:

\getbuffer

One can use the hook for specific formatting purposes, like
in:

\startbuffer
\def\SomeBar#1{\blackrule[width=#1em]}
\starttabulate[|l|lh\SomeBar|]
\HL
\NC \bf item \NC \bf quantity \NC \NR
\HL
\NC figures  \HC  {5}         \NC \NR
\NC tables   \HC  {8}         \NC \NR
\NC formulas \HC {12}         \NC \NR
\HL
\stoptabulate
\stopbuffer

\getbuffer

There are three specially typeset cells. Watch the braces!

\typebuffer

Until now, we used \type {\NC} to go to the next column. For
special purposes one can use \type {\EQ} to force a column
separator.

\startbuffer
\starttabulate
\NC equal \EQ one can change the separator by changing the \type {EQ}
              variable with the tabulate setup command \NC \NR
\NC colon \EQ by default, a colon is used, but an equal sign suits
              well too \NC \NR
\stoptabulate
\stopbuffer

\typebuffer

Typeset this turns up as:

\getbuffer

We've seen \type {\NC} for normal entries, \type {\EQ} for
entries seperated by an equal sign, and \type {\HC} for
hooked ones. There is also \type {\HQ} for a hooked entry
with separator. When one does not want any formatting at
all, \type {\RC} and \type {\RQ} can be used.

\startbuffer
\starttabulate[|*{4}{cBh\type|}]
\NC           \NC normal \NC raw   \NC hook  \NC \NR
\RC \bf equal \HC {\EQ}  \HC {\RQ} \HC {\HQ} \NC \NR
\RC \bf none  \HC {\NC}  \HC {\RC} \HC {\HC} \NC \NR
\stoptabulate
\stopbuffer

\getbuffer

This small table shows all three categories. We've got
4~centered columns, either {\bf bold} or \type {verbatim} and
two cells are aligned different. This table is coded as:

\typebuffer

The equal sign, or whatever else symbol is set up, can also
be forced by the \type {e}~key in the preamble.

\starttabulate[|lT|p|]
\NC e \NC insert an equal symbol in the next column \NC \NR
\stoptabulate

When we have multiple columns with similar templates, we can
save some typing by repeating them. We have of course to
make sure that the number of \type{|}'s is ok.

%\NC ditjes en datjes \NC links en rechts \NC hier en daar
%\NC zus en zo        \NC op en neer      \NC hot naar her \NC \NR

\startbuffer
\starttabulate[|*{6}{k1pc|}]
\NC this and that \NC left and right \NC here and there \NC
    such and so   \NC up and down    \NC on and on      \NC \NR
\stoptabulate
\stopbuffer

\typebuffer

Counting the \type{|}'s, we have $1+6\times1=7$ of them.

\getbuffer

A better example of automatic width calculation is given
below:

\startbuffer
\starttabulate[|l|p|]
\NC tables   \NC We use the \type {\starttable} command when we are
                 typesetting tables that are separate entities, that
                 may float and are sort of independent of the normal
                 text flow. \NC \NR
\NC tabulate \NC The \type {\starttabulate} command is meant for
                 typesetting tabular text in the normal text flow.
                 Therefore automatic width calculation, as demonstrated
                 here, comes in handy. \NC \NR
\stoptabulate
\stopbuffer

\getbuffer

This was entered as:

\typebuffer

When no template is given, \type{[|l|p|]} is assumed, which
sometimes saves some typing. There is however a better way
to save time, because one can define specific tabulate
environments, like:

\startbuffer
\definetabulate[Three][|lB|lS|p|]
\startThree
\NC one \NC two \NC three four five six seven eight nine ten
                    eleven twelve and so on and on and on \NC \NR
\stopThree
\stopbuffer

\typebuffer

\getbuffer

The three tabulate commands can be summarized with:

\setup{\y!definetabulate}

The first argument identifies the tabulation. The second
argument is optional and identifies a related tabulation.
More on that later. The last argument always defines the
preamble.

\setup{\e!start\e!tabulate}

The (optional) first argument holds the preamble, and the
optional second one can be used to change settings.

\setup{\y!setuptabulate}

The optional argument specifies a related tabulation. By
setting \type {indenting} to \type {yes}, the table is
indented according to the current indentation scheme. Left
and right skips are always taken into account! The unit
concerns the spacing as set by the spacing keys~\type {i},
\type {j} and~\type {k}. Commands assigned to \type {inner}
are executed before the first columns is typeset.

One can add horizontal lines to a table by \type {\HL}. This
command automatically takes care of spacing:

\startbuffer
\starttabulate[|l|p|]
\HL
\NC small  \NC They say, small is beautiful.            \NC \NR
\HL
\NC medium \NC It seems that the medium is the message. \NC \NR
\HL
\NC large  \NC Large T||shirts are always sold out.     \NC \NR
\HL
\stoptabulate
\stopbuffer

\typebuffer

When a page break occurs at such a horizontal rule, the rule
is automatically duplicated. One can force top, mid or
bottom rules with \type {\FL}, \type {\ML} and \type {\LL}.

\getbuffer

Although the tabulate environment is primary meant for use
in the text flow, it is quite legal to use it in floating
tables. When used as float, the spacing around a tabulation
is automatically surpressed. In the text flow however, the
tabulate commands adjust themselves to the current text
width and indentation.

\startbuffer
\starttabulate
\NC see this \NC As to be expected, paragraph entries are
                 automatically adjusted to the smaller text
                 width. \NC \NR
\stoptabulate
\stopbuffer

\startitemize

\item This means that a table created with this environment
      can be used within for instance an itemize.

\getbuffer

\item This small table was entered as:

\typebuffer

\stopitemize

Although tables in themselves can be used to format text in
columns, occasionally using for instance an itemize in a
table makes sense. The next, a bit weird, example shows this.

\startbuffer
\starttabulate[|p(2cm)|p(5cm)|p|]
\NC \startitemize[n,packed]
    \item first \item second \item third
    \stopitemize
\NC \startitemize[packed][items=5,width=2.5em,distance=.5em]
    \its this or that \its such or so \its here or there
    \stopitemize
\NC \startitemize[g,packed,broad]
    \item alpha \item beta \item gamma
    \stopitemize
\NC\NR
\stoptabulate
\stopbuffer

\getbuffer

In such situations, packing items just looks better.

\typebuffer

Because the table content is read in before it is processed,
there are some limitations when on||the||fly \type
{\catcode} changes are involved. In day||to||day use
however, one will not run into trouble that fast. The
tabulate environment is mildly \ETEX\ aware, so one can
expect less \type {\catcode} related problems when using
this \TEX\ alternative.

Tabulations can for instance be used to compose tables with
numbered material, like the one below:

\startbuffer
\starttabulate[|l|r|]
\NC not to much     \NC          1.220  \NC \NR
\NC pretty much     \NC          5.186  \NC \NR
\NC totalling up to \NC \overbar{6.406} \NC \NR
\stoptabulate
\stopbuffer

\getbuffer

This table is entered as:

\typebuffer

Sometimes one wants to align entries in such tables by hand,
and like in the \TABLE\ based table environment, we can
use~\type {~} for this purpose. This character inserts an
one digit wide space. Normally such a tie produces an
unbreakable space, so changing its meaning is to be specified
in the preamble.

\starttyping
\starttabulate[|l|~c|]
\NC this much \NC ~12 \NC \NR
\NC that far  \NC 185 \NC \NR
\stoptabulate
\stoptyping

The next few examples show how we can define related
tabulations. Actually, the main reason for programming this
mechanism, originates in the wish to re||implement the legend
macros.

\starttyping
\definetabulate [legend]       [|emj1|i1|mR|]
\definetabulate [legend] [two] [|emj1|emk1|i1|mR|]
\setuptabulate  [legend]       [unit=.75em,EQ={=}]
\stoptyping

Now we can say things like:

\startbuffer
\startlegend
\NC w \NC the width of the box  \NC pt \NR
\NC h \NC the height of the box \NC pt \NR
\NC d \NC the depth of the box  \NC pt \NR
\stoplegend
\stopbuffer

\typebuffer

This simple legend turns up as:

\getbuffer

An additional entry is possible with the \type {two}
alternative.

\startbuffer
\startlegend[two]
\NC w \NC width  \NC the width of the box  \NC pt \NR
\NC h \NC height \NC the height of the box \NC pt \NR
\NC d \NC depth  \NC the depth of the box  \NC pt \NR
\stoplegend
\stopbuffer

\typebuffer

This related tabulation inherits the settings from the
parent tabulation. Of course we could have defined \type
{\startlegendtwo}, but we wanted downward compatibility with
existing macros.

\getbuffer

The related fact macros are defined as:

\starttyping
\definetabulate [fact] [|R|ecmj1|i1mR|]
\setuptabulate  [fact] [unit=.75em,EQ={=}]
\stoptyping

The first column is typeset in roman, the next one is
separated from the first one by an equal sign, is centered,
is typeset in math mode, and gets a bit more space
afterwards. The last column is typeset in math mode, but
inside there we switch to roman; some extra space is added in
front. So:

\startbuffer
\startfact
\NC width  \NC w \NC 48pt \NR
\NC height \NC h \NC  9pt \NR
\NC depth  \NC d \NC  3pt \NR
\stopfact
\stopbuffer

\typebuffer

Indeed gives:

\getbuffer

In real life the definitions shown here also have something
assigned to \type {inner}, which enables more compact
specifications:

\starttyping
\startfact
\\ width  \\ w \\ 48pt \\
\\ height \\ h \\  9pt \\
\\ depth  \\ d \\  3pt \\
\stopfact
\stoptyping

We show one last example, demonstrating the automatic
paragraph width calculation. This example also shows that
the last \type {\NC} is redundant.

\startbuffer
\starttabulate[|Bl|p|Bl|]
\NC Example \NC \input tufte \NC Edward Tufte \NR
\stoptabulate
\stopbuffer

\typebuffer

\getbuffer

As can be expected, these commands have their dutch and
german counterparts:

\starttabulate[|*{4}{c|}]
\NC \bf english                \NC
    \bf dutch                  \NC
    \bf german                 \NC\NR
\NC \type{\starttabulate}      \NC
    \type{\starttabulatie}     \NC
    \type{\starttabulator}     \NC\NR
\NC \type{\definetabulate}     \NC
    \type{\definieertabulatie} \NC
    \type{\definieretabulator} \NC\NR
\NC \type{\setuptabulate}      \NC
    \type{\steltabulatiein}    \NC
    \type{\stelletabulatorein} \NC\NR
\stoptabulate

The preamble commands and column and row separators are
independant of the interface.
