# Summary

\starttabulate is a versatile table environment. It supports paragraphs in cells, vertical rules (for those typographically less demanding jobs …), and colorization of those rules, the background of fields as well as the text itself.

Warning: When you want to use tables with macros use \starttable and \stoptable. \starttabulate and \stoptabulate does not work correctly with macros.

# Basic commands

The control sequence \starttabulate[#1] takes a layout string as optional argument. As is common with tables in TeX-based typesetting, this string (in its basic variant) consists primarily of the bar character (“|”) as delimiter for columns, and of the letters c, l, as well as r, denoting the alignment within cells of this row.

For instance consider a two-column table: if any text in the first column should be right aligned (real flushright) and the second column left aligned, the corresponding format string would be |l|r|. NB: those bars, as stated above, denote cell limits only – not vertical lines.

\starttabulate[|r|l|]
\HL
\NC {\bf format} \NC {\bf meaning}                    \NC\NR
\HL
\NC c      \NC centered                               \NC\NR
\NC l      \NC left aligned                           \NC\NR
\NC r      \NC right aligned                          \NC\NR
\NC w(1cm) \NC one line, fixed width                  \NC\NR
\NC p(2cm) \NC paragraph, lines broken to fixed width \NC\NR
\NC cg(.)  \NC align on a character                   \NC\NR
\HL
\stoptabulate

• HL draws a horizontal rule,
• NC marks a new column (or new cell),
• NR starts a new row.
• NB starts a new row as a block (avoids page breaking inside of a block, to keep some lines together; available since beta of 2011-12-21)

When using fixed width, you can use values relative to the current page-width. For example: if you want the previous table take up all the width and having the second column taking three quarters of the space, change the starttabulate to:

\starttabulate[|rw(.25\textwidth)|lw(.75\textwidth)|]


# Spanning Multiple Pages

Tabulate may extend to adjacient pages if needed. To achieve this the argument split must be set to true. NB: the difference between setting and unsetting this argument may not be visible on the first few pages. Rather, it seems to affect the end of the environment.

\setuppapersize[A10, landscape][A8, landscape]
\setuppaper[nx=2,ny=2]
\setuparranging[XY]

\switchtobodyfont[5pt]
\showframe[edge]

\setuptabulate
[split=yes,
title={\color[red] Fenchurch St. Paul},
frame=on]

\starttabulate[|p(1.2cm)|p(1.2cm)|]
\dorecurse{6}{
\NC  Bells:  \NC  Tin tan din dan bim bam bom bo \NC\NR
\HL
\NC  Name:  \NC  Tailor Paul \NC \NR
\HL
}
\stoptabulate


## Titles

A tabulating environment can have an optional name which will be repeated above at every page break that occurs inside the table. This name needs to be specified as the argument of the title key of \setuptabulate. The header key has to be set to text for this to work.

\setuppapersize[A10, landscape][A8, landscape]
\setuppaper[nx=2,ny=2]
\setuparranging[XY]

\switchtobodyfont[5pt]
\showframe[edge]

\setuptabulate
[split=yes,
title={\color[red] Fenchurch St. Paul},
frame=on]

\starttabulate[|p(1.2cm)|p(1.2cm)|]
\dorecurse{6}{
\NC  Bells:  \NC  Tin tan din dan bim bam bom bo \NC\NR
\HL
\NC  Name:  \NC  Tailor Paul \NC \NR
\HL
}
\stoptabulate


Tabulate supports header rows that can be repeated over new table pages instead of the title. There is a separate environment \starttablehead where this header row has to be specified in advance of its use in a tabulation.

\setuptabulate[split=yes,header=repeat]

\HL
\NC {\bf format char} \NC {\bf meaning} \NC \AR
\HL

\starttabulate[|r|l|]
\NC c \NC centered      \NC \AR
\NC l \NC left aligned  \NC \AR
\NC r \NC right aligned \NC \AR
\stoptabulate


# Individualizing the Tabulate Look

Hans initially announced support for vertical lines and colors on the mailing list.[1]

## Rules

### Horizontal Rules

As already demonstrated above, the \HL statement inserts a hairline after the current line. This particularly useful when demarking header and footer rows or separated parts of a table that should not be as closely associated as the rows between the rules.

\starttabulate[|r|c|l|]
\NC test \NC test \NC test \NC\NR
\HL
\NC test \NC test \NC test \NC\NR
\NC test \NC test \NC test \NC\NR
\HL
\NC test \NC test \NC test \NC\NR
\HL
\stoptabulate


Context supports different categories of rules that can be configured individually in order to discern various applications. Their behaviour accounts for the designated use, e. g. \ML (mid rules) are intended to be deployed between ordinary rows of the table body and will prevent page breaks – no way you’d end up with a rogue hairline desecrating the bottom of your page’s text area.

Type Description
\HL standard horizontal rule;
\FL first rule;
\ML mid rule;
\LL bottom rule;
\LL and \TL bottom rule;
\BL last rule.

Additionally, there is an options rulecolor for \setuptabulate that allows for those rules to be tinted.

\setuptabulate[rulecolor=red]

\starttabulate[|r|c|l|]
\FL
\NC first row \NC test \NC test \NC\NR
\ML
\NC rows in   \NC test \NC test \NC\NR
\NC between   \NC test \NC test \NC\NR
\LL
\NC last row  \NC test \NC test \NC\NR
\BL
\stoptabulate


Other types can be discovered in the source (tabl-tbl.mkiv).

### Vertical Rules

The \VL command serves as a replacement for \NC to mark a cell border wherever a vertical rule may be desired (if they are to be desired at all from a typographical point of view).

\starttabulate[||||]
\NC test \VL test \VL test \VL\NR
\VL test \NC test \VL test \VL\NR
\VL test \VL test \NC test \VL\NR
\VL test \VL test \VL test \NC\NR
\stoptabulate


## Coloring

The following elements can be colorized: rules, cell backgrounds, and, obviously, common text.

### Colorizing Rules

For horizontal rules see above.

For vertical rules, \VL takes a defined color as an optional argument.

\starttabulate[|r|c|l|]
\VL test \VL[red]    red rule    \VL test \VL \NR
\VL test \VL[green]  green rule  \VL test \VL \NR
\VL test \VL[blue]   blue rule   \VL test \VL \NR
\stoptabulate


### Colorizing Backgrounds

Backgrounds can be colorized either on column basis or individually by cell.

There are four color-specific control sequences:

 CR color is applied to the background of the text and the remaining space on the right; CC color is applied to the background of the text only; CM color is applied to the background of the text and the remaining space on both sides; CL color is applied to the background of the text and the remaining space on the left.

These are to complement the normal table layout expression (the first argument to \starttabulate. Thus, in order to colorize a four column table with the initial layout |c|c|c|c| it will have to be modified as follows:

\starttabulate[|CR{red}c|CC{yellow}c|CM{green}c|CL{blue}c|]
\NC test \NC test \NC test \NC test \NC \NR
\NC test \NC test \NC test \NC test \NC \NR
\NC test \NC test \NC test \NC test \NC \NR
\NC test \NC test \NC test \NC test \NC \NR
\stoptabulate


Those control sequences, if applied within the table body, can replace the ordinary \NC, allowing individual cells to be colorized.

\starttabulate[|c|c|c|c|c|c|]
\NC g \NC l \NC i \NC d \NC e \NC r \NC \NR
\NC g \NC l \NC i \CM[blue] d \NC e \NC r \NC \NR
\NC g \NC l \NC i \NC d \CM[blue] e \NC r \NC \NR
\NC g \NC l \CM[blue] i \CM[blue] d \CM[blue] e \NC r \NC \NR
\NC g \NC l \NC i \NC d \NC e \NC r \NC \NR
\stoptabulate


caveat emptor! The background coloring does apply only to the first row of a paragraph cell. Any other cell will come out colorless. If you need to color an entire multi-line cell, you will need to switch to another tabulation variant.

### Colorizing Cell Text

Normal text inside cells gets its color via the standard coloring commands.

\starttabulate[|r|c|l|]
\NC test \NC {\colored[red]   test} \NC test \NC\NR
\NC test \NC {\colored[green] test} \NC test \NC\NR
\NC test \NC {\colored[blue]  test} \NC test \NC\NR
\NC test \NC {\colored[cyan]  test} \NC test \NC\NR
\stoptabulate


## Vertical Distance Between Rows

There does not seem to be an official interface for vertical skips. Manually placed \blanks are \unskipped on purpose. However, as expected there is a token list \t_tabl_tabulate_every_after_row that is placed after a line is finished. So, in order to get a vertical spacing of half a baseline distance you can use this code:

\unprotect
\appendtoks
\blank[halfline]
\to \t_tabl_tabulate_every_after_row
\protect



# Using math mode

If you want to display numerics, you can simply use \NN for a new column instead of \NC. This command works similar to the digit-module. Therefore you can also abbreviate:

\starttabulate[|l|l|]
\HL
\NN 10e-3 \NN 10e+3  \NR
\HL
\stoptabulate


\starttabulate[|l|l|]
\HL
\NC $10\cdot 10^{-3}$ \NC $10 \cdot 10^3$ \NR
\HL
\stoptabulate


although both variants do work.

# Itemization inside a tabulation

The following issue is related to MKIV:

When using an itemization inside a tabulation where one uses also the \head command there occurs a snapping problem. This is related to penalties which force a twoline split whereas the snapping mechanism prevents this. As a result two lines are typeset on top of each other. The solution is to add the following statement to the preamble:

\tabulatesplitlinemode \plustwo

The following code provided by Wolfgang Schuster demonstrates the problem: Compile with and without the line \tabulatesplitlinemode\plustwo

\tabulatesplitlinemode \plustwo
\starttabulate[|p|]
\NC
one \par
\blank[penalty:10000]
two \par
\blank[penalty:10000]
three
\NC\NR
\stoptabulate