Difference between revisions of "Tabulate"

From Wiki
Jump to navigation Jump to search
m (Text replace - "\[\[cmd:(.*)\|(.*)\]\]" to "{{cmd|$1}}")
m (Document that [] is required for \starttabulatehead in MkIV. Email by Wolfgang Schuster 2018-11-12.)
(23 intermediate revisions by 8 users not shown)
Line 10: Line 10:
 
as the text itself.
 
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.
+
'''Warning''': When you want to use tables with macros use {{cmd|starttable}} and \stoptable. {{cmd|starttabulate}} and \stoptabulate does not work correctly with macros.
  
 
=Basic commands=
 
=Basic commands=
  
The control sequence <tt>\starttabulate[#1]</tt> takes a layout
+
The control sequence {{cmd|starttabulate|[#1]}} takes a layout
 
string as optional argument.
 
string as optional argument.
 
As is common with tables in TeX-based typesetting, this string
 
As is common with tables in TeX-based typesetting, this string
Line 33: Line 33:
 
  -  wtf this listing was full of <tab> chars‽ Was this supposed
 
  -  wtf this listing was full of <tab> chars‽ Was this supposed
 
  -  to be a bad pun on *tabulate*?
 
  -  to be a bad pun on *tabulate*?
 +
-  - No, I formatted it readably in my text editor. --HR
 
-->
 
-->
 
{|
 
{|
Line 40: Line 41:
 
  |-
 
  |-
 
  | <texcode>
 
  | <texcode>
\starttabulate[|r|l|]
+
\starttabulate[|r|l|lB|]
 
\HL
 
\HL
\NC {\bf format} \NC {\bf meaning}                   \NC\NR
+
\NC {\bf format} \NC {\bf meaning} \NC Mk \NC\NR
 
\HL
 
\HL
\NC c      \NC centered                              \NC\NR
+
\NC c      \NC centered                              \NC \NC\NR
\NC l      \NC left aligned                          \NC\NR
+
\NC l      \NC left aligned                          \NC \NC\NR
\NC r      \NC right aligned                          \NC\NR
+
\NC r      \NC right aligned                          \NC \NC\NR
\NC w(1cm) \NC one line, fixed width                  \NC\NR
+
\NC w(1cm) \NC one line, fixed width                  \NC \NC\NR
\NC p(2cm) \NC paragraph, lines broken to fixed width \NC\NR
+
\NC p(2cm) \NC paragraph, lines broken to fixed width \NC \NC\NR
\NC cg(.)  \NC align on a character                   \NC\NR
+
\NC cg(.)  \NC align on a character \NC IV: cg{.} \NC\NR
 +
\NC m      \NC math mode                          \NC IV only \NC\NR
 +
\NC b      \NC before e.g. b{\star}                          \NC IV only \NC\NR
 +
\NC a      \NC after, e.g. a{\percent}                        \NC IV only \NC\NR
 
\HL
 
\HL
 
\stoptabulate
 
\stoptabulate
Line 55: Line 59:
 
|
 
|
 
|<context>
 
|<context>
\starttabulate[|r|l|]
+
\setuppapersize[A5]
 +
\starttabulate[|r|l|lB|]
 
\HL
 
\HL
\NC {\bf format} \NC {\bf meaning}                   \NC\NR
+
\NC {\bf format} \NC {\bf meaning}\NC Mk \NC\NR
 
\HL
 
\HL
 
\NC c      \NC centered                              \NC\NR
 
\NC c      \NC centered                              \NC\NR
Line 64: Line 69:
 
\NC w(1cm) \NC one line, fixed width                  \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 p(2cm) \NC paragraph, lines broken to fixed width \NC\NR
\NC cg(.)  \NC align on a character                   \NC\NR
+
\NC cg(.)  \NC align on a character \NC\NR
 
\HL
 
\HL
 
\stoptabulate
 
\stoptabulate
Line 70: Line 75:
 
|}
 
|}
  
* <tt>HL</tt> draws a horizontal rule,
+
* <cmd>HL</cmd> draws a horizontal rule,
* <tt>NC</tt> marks a new column (or new cell),
+
* <cmd>NC</cmd> marks a new column (or new cell),
* <tt>NR</tt> starts a new row.
+
* <cmd>NN</cmd> marks a new math column/cell (see below),
* <tt>NB</tt> 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)
+
* <cmd>NR</cmd> starts a new row,
 
+
* <cmd>NB</cmd> 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-->);
 +
* <cmd>TB</cmd> (= "Table Blank") adds some vertical space between rows -- see an example bellow,
 +
* <cmd>VL</cmd> (instead of <cmd>NC</cmd>) draws a vertical rule -- for more info see below.
  
 
When using fixed width, you can use values relative to the
 
When using fixed width, you can use values relative to the
 
current page-width. For example: if you want the previous table
 
current page-width. For example: if you want the previous table
 
take up all the width and having the second column taking three
 
take up all the width and having the second column taking three
quarters of the space, change the starttabulate to:
+
quarters of the space, change the {{cmd|starttabulate}} to:
 +
<texcode>
 +
\starttabulate[|rw(.25\textwidth)|lw(.75\textwidth)|]
 +
</texcode>
 +
(Mistake: This doesn’t account for the width of the column distance!)
 +
 
 +
=Horizontal centering table on the page=
 +
 
 +
<!--(Solution from the mailing list)-->
 +
 
 +
<context source=yes>
 +
This is a very long text, longer than the width of the table.
 +
It must be long enough to flow to the next line to see the effect.
 +
 
 +
\placetable[force,none]{}{%
 +
  \starttabulate[|r|l|]
 +
  \HL
 +
  \NC I want this table \NC aligned in the center.\NC\NR
 +
  \HL
 +
  \stoptabulate
 +
}</context>
  
\starttabulate[|rw(.25\textwidth)|lw(.75\textwidth)|]
+
This can also be done with the start/stop syntax (showing only source here, since it does not compile on the wiki):
  
 +
<context source=yes>
 +
This is a very long text, longer than the width of the table.
 +
It must be long enough to flow to the next line to see the effect.
  
It is generally not necessary to conclude lines with
+
\startplacetable[location=force,number=no]
<tt>\NC\NR</tt> as <tt>\AR</tt> (for <em>a</em>uto<em>r</em>ow)
+
  \starttabulate[|r|l|]
will do the job as well.
+
  \HL
 +
  \NC I want this table \NC aligned in the center.\NC\NR
 +
  \HL
 +
  \stoptabulate
 +
\stopplacetable
 +
</context>
  
 
=Spanning Multiple Pages=
 
=Spanning Multiple Pages=
Line 93: Line 128:
 
To achieve this the argument <tt>split</tt> must be set to
 
To achieve this the argument <tt>split</tt> must be set to
 
''true''.
 
''true''.
 +
 
''NB'': the difference between setting and unsetting this
 
''NB'': the difference between setting and unsetting this
 
argument may not be visible on the first few pages. Rather, it
 
argument may not be visible on the first few pages. Rather, it
 
seems to affect the ''end'' of the environment.
 
seems to affect the ''end'' of the environment.
  
<context source="yes">
+
<context source=yes>
\setuppapersize [XY][A4]
+
\setuppapersize[A10, landscape][A8, landscape]
\setuppaper     [nx=2,ny=2]
+
\setuppaper[nx=2,ny=2]
\setuparranging [XY]
+
\setuparranging[XY]
\setupbodyfont[10pt]
 
  
\starttext
+
\switchtobodyfont[5pt]
 +
\setuppagenumbering[location={header,inright}]
 +
\showframe[edge]
  
\setuptabulate[split=yes]
+
\setuptabulate
 +
  [split=yes,
 +
    header=text,
 +
    title={\color[red] Fenchurch St. Paul},
 +
    frame=on]
  
\starttabulate
+
\starttabulate[|p(1.2cm)|p(1.2cm)|]
\dorecurse{2}{
+
\dorecurse{6}{
   \NC test \NC \input tufte  \relax \NC \NR  
+
   \NC Bells:  \NC Tin tan din dan bim bam bom bo \NC\NR
   \NC test \NC \input dawkins \relax \NC \NR  
+
  \HL
 +
   \NC Name:  \NC Tailor Paul \NC \NR                                            
 +
  \HL
 
}
 
}
 
\stoptabulate
 
\stoptabulate
 +
</context>
  
\stoptext \endinput
 
</context>
 
  
 
==Titles==
 
==Titles==
Line 122: Line 164:
 
repeated above at every page break that occurs inside the table.
 
repeated above at every page break that occurs inside the table.
 
This name needs to be specified as the argument of the
 
This name needs to be specified as the argument of the
<tt>title</tt> key of <tt>\setuptabulate</tt>.
+
<tt>title</tt> key of {{cmd|setuptabulate}}.
 
The <tt>header</tt> key has to be set to <em>text</em> for this
 
The <tt>header</tt> key has to be set to <em>text</em> for this
 
to work.
 
to work.
  
<texcode>
+
<context source=yes>
\setuptabulate[split=yes,header=text,title={\sc Table Titles Undisclosed!}]
+
\setuppapersize[A10, landscape][A8, landscape]
 
+
\setuppaper[nx=2,ny=2]
\starttabulate
+
\setuparranging[XY]
\dorecurse{2}{
 
  \NC Ed Tufte    \NC \input tufte  \relax \NC \NR
 
  \NC Dick Dawkins \NC \input dawkins \relax \NC \NR
 
}
 
</texcode>
 
 
 
<context>
 
\setuppapersize [XY][A4]
 
\setuppaper     [nx=2,ny=2]
 
\setuparranging [XY]
 
  
\starttext
+
\switchtobodyfont[5pt]
 +
\setuppagenumbering[location={header,inright}]
 +
\showframe[edge]
  
\setuptabulate[split=yes,header=text,title={\sc Table Titles Undisclosed!}]
+
\setuptabulate
 +
  [split=yes,
 +
    header=text,
 +
    title={\color[red] Fenchurch St. Paul},
 +
    frame=on]
  
\starttabulate
+
\starttabulate[|p(1.2cm)|p(1.2cm)|]
\dorecurse{2}{
+
\dorecurse{6}{
   \NC Ed Tufte    \NC \input tufte  \relax \NC \NR                                            
+
   \NC Bells:  \NC Tin tan din dan bim bam bom bo \NC\NR
   \NC Dick Dawkins \NC \input dawkins \relax \NC \NR
+
  \HL
 +
   \NC Name:  \NC Tailor Paul \NC \NR                                            
 +
  \HL
 
}
 
}
 
\stoptabulate
 
\stoptabulate
 
\stoptext \endinput
 
 
</context>
 
</context>
  
Line 162: Line 200:
 
  -  “\setuptabulate” but I couldn’t notice any effect.
 
  -  “\setuptabulate” but I couldn’t notice any effect.
 
-->
 
-->
 +
 
==Headers==
 
==Headers==
 
Tabulate supports header rows that can be repeated over new table
 
Tabulate supports header rows that can be repeated over new table
 
pages instead of the title.
 
pages instead of the title.
There is a separate environment <tt>\starttablehead</tt> where
+
There is a separate environment {{cmd|starttabulatehead}} where
 
this header row has to be specified in advance of its use in a
 
this header row has to be specified in advance of its use in a
 
tabulation.
 
tabulation.
 +
 +
In ConTeXt MkIV the command requires an additional [], thus you need
 +
to write {{cmd|starttabulatehead}}[] instead.
  
 
{|
 
{|
Line 178: Line 220:
  
 
\starttabulatehead
 
\starttabulatehead
   \HL
+
   \FL
   \NC {\bf format char} \NC {\bf meaning} \AR
+
   \NC {\bf format char} \NC {\bf meaning} \NC \AR
   \HL
+
   \LL
 
\stoptabulatehead
 
\stoptabulatehead
  
 
\starttabulate[|r|l|]
 
\starttabulate[|r|l|]
     \NC c \NC centered      \AR
+
     \NC c \NC centered      \NC \AR
     \NC l \NC left aligned  \AR
+
     \NC l \NC left aligned  \NC \AR
     \NC r \NC right aligned \AR
+
     \NC r \NC right aligned \NC \AR
 
\stoptabulate
 
\stoptabulate
 
</texcode>
 
</texcode>
 
|
 
|
 
| <context>
 
| <context>
 +
\setuppapersize[A5]
 +
 
\setuptabulate[split=yes,header=repeat]
 
\setuptabulate[split=yes,header=repeat]
  
 
\starttabulatehead
 
\starttabulatehead
   \HL
+
   \FL
 
   \NC {\bf format char} \NC {\bf meaning} \AR
 
   \NC {\bf format char} \NC {\bf meaning} \AR
   \HL
+
   \LL
 
\stoptabulatehead
 
\stoptabulatehead
  
Line 206: Line 250:
 
</context>
 
</context>
 
|}
 
|}
 +
 +
Note the use of <tt>\FL</tt> and <tt>\LL</tt> in the tabulate header rather than <tt>\HL</tt> which is a standard rule command (see below) that tries to guess automatically its position.
  
 
=Individualizing the Tabulate Look=
 
=Individualizing the Tabulate Look=
  
 
Hans initially announced support for vertical lines and colors on
 
Hans initially announced support for vertical lines and colors on
the mailing list.[http://archive.contextgarden.net/message/20101117.123950.739657a7.en.html]
+
the mailing list. [http://archive.contextgarden.net/message/20101117.123950.739657a7.en.html]
  
 
==Rules==
 
==Rules==
Line 253: Line 299:
 
Context supports different categories of rules that can be
 
Context supports different categories of rules that can be
 
configured individually in order to discern various applications.
 
configured individually in order to discern various applications.
Their behaviour accounts for the designated use, e.&nbsp;g.
+
Their behaviour accounts for the designated use, e.g.
 
<tt>\ML</tt> (mid rules) are intended to be deployed between
 
<tt>\ML</tt> (mid rules) are intended to be deployed between
 
ordinary rows of the table body and will prevent page breaks
 
ordinary rows of the table body and will prevent page breaks
Line 274: Line 320:
 
|}
 
|}
  
Additionally, there is an options <tt>rulecolor</tt> for
+
Additionally, there is an option <tt>rulecolor</tt> for
<tt>\setuptabulate</tt> that allows for those rules to be tinted.
+
{{cmd|setuptabulate}} that allows for those rules to be tinted.
  
 
<texcode>
 
<texcode>
Line 297: Line 343:
 
===Vertical Rules===
 
===Vertical Rules===
  
The <tt>\VL</tt> command serves as a replacement for <tt>\NC</tt>
+
The <cmd>VL</cmd> command serves as a replacement for <cmd>NC</cmd>
 
to mark a cell border wherever a vertical rule may be desired (if
 
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
 
they are to be desired at all from a typographical point of
Line 320: Line 366:
 
For ''horizontal rules'' see above.
 
For ''horizontal rules'' see above.
  
For ''vertical rules'', <tt>\VL</tt> takes a defined color as an
+
For ''vertical rules'', <cmd>VL</cmd> takes a defined color as an
 
optional argument.
 
optional argument.
  
Line 331: Line 377:
 
</texcode>
 
</texcode>
  
===Colorizing Backgrounds===
+
===Colorizing Backgrounds & Text===
''Backgrounds'' can be colorized either on column basis or
+
Backgrounds and text can be colorized either on column basis or
 
individually by cell.
 
individually by cell.
  
There are four color-specific control sequences:
+
There are five color-specific control sequences:
 
{|
 
{|
|<tt>CR</tt> || color is applied to the background of the text and the remaining space on the right;
+
|<cmd>CR</cmd> || color is applied to the background of the text and the remaining space on the right.
 
|-
 
|-
|<tt>CC</tt> || color is applied to the background of the text only;
+
|<cmd>CC</cmd> || color is applied to the background of the text only.
 
|-
 
|-
|<tt>CM</tt> || color is applied to the background of the text and the remaining space on both sides;
+
|<cmd>CM</cmd> || color is applied to the background of the text and the remaining space on both sides.
 
|-
 
|-
|<tt>CL</tt> || color is applied to the background of the text and the remaining space on the left.
+
|<cmd>CL</cmd> || color is applied to the background of the text and the remaining space on the left.
 +
|-
 +
|<cmd>CT</cmd> || color is applied to the text itself - in other words, the "foreground color."
 
|}
 
|}
 
These are to complement the normal table layout expression (the
 
These are to complement the normal table layout expression (the
first argument to <tt>\starttabulate</tt>.
+
first argument to {{cmd|starttabulate}.
 
Thus, in order to colorize a four column table with the initial
 
Thus, in order to colorize a four column table with the initial
 
layout <tt>|c|c|c|c|</tt> it will have to be modified as follows:
 
layout <tt>|c|c|c|c|</tt> it will have to be modified as follows:
Line 359: Line 407:
  
 
Those control sequences, if applied within the table body, can
 
Those control sequences, if applied within the table body, can
replace the ordinary <tt>\NC</tt>, allowing individual cells to
+
replace the ordinary <cmd>NC</cmd>, allowing individual cells to
 
be colorized.
 
be colorized.
 
<texcode>
 
<texcode>
Line 371: Line 419:
 
</texcode>
 
</texcode>
  
 +
'''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
 +
[[Tables Overview|tabulation variant]].
  
 
===Colorizing Cell Text===
 
===Colorizing Cell Text===
 
''Normal text'' inside cells gets its color via the
 
''Normal text'' inside cells gets its color via the
[[Colors|standard coloring commands]].
+
[[Color|standard coloring commands]], or by the
 +
shorter variant described above.
  
 
<texcode>
 
<texcode>
Line 384: Line 438:
 
\stoptabulate
 
\stoptabulate
 
</texcode>
 
</texcode>
 +
 +
== Vertical Distance Between Rows ==
 +
 +
<!--
 +
There does not seem to be an official interface for
 +
vertical skips.
 +
Manually placed <code>\blank</code>s are
 +
<code>\unskipped</code> on purpose.
 +
However, as expected there is a token list
 +
<code>\t_tabl_tabulate_every_after_row</code> 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:
 +
 +
<texcode>
 +
\unprotect
 +
\appendtoks
 +
  \blank[halfline]
 +
\to \t_tabl_tabulate_every_after_row
 +
\protect
 +
</texcode>
 +
 +
-->
 +
 +
<context mode=mkiv source=yes>
 +
\starttabulate
 +
  \NC one  \NC two  \NC\NR
 +
  \NC two  \NC three \NC\NR
 +
  \TB[halfline]
 +
  \NC four  \NC five  \NC\NR
 +
  \TB[line]
 +
  \NC four  \NC five  \NC\NR
 +
  \TB[1cm]
 +
  \NC eight \NC nine \NC\NR
 +
\stoptabulate
 +
</context>
  
 
=Using math mode=
 
=Using math mode=
Line 408: Line 498:
 
although both variants do work.
 
although both variants do work.
  
 +
If you always need math in one column, consider math mode columns:
  
=Itemization inside a tabulation=
+
<texcode>
 +
\starttabulate[|m|m|]
 +
\HL
 +
\NC 10e-3 \NC 10e+3  \NR
 +
\HL
 +
\stoptabulate
 +
</texcode>
 +
 
 +
 
 +
=Itemization or framed objects inside a tabulation=
  
<!--(added by Willi Egger 04-08-2011)-->
+
<!--(added by Willi Egger 04-08-2011, edited by Hraban 2015-10-06)-->
 
   
 
   
The following issue is related to MKIV:
+
The following issue is related to MkIV:
  
 
When using an itemization inside a tabulation where one uses also the  
 
When using an itemization inside a tabulation where one uses also the  
<tt>\head</tt> 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:
+
{{cmd|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:
 
<texcode>\tabulatesplitlinemode \plustwo</texcode>
 
<texcode>\tabulatesplitlinemode \plustwo</texcode>
  
Line 434: Line 534:
 
</texcode>
 
</texcode>
  
 +
The same is true if you use {{cmd|framed}} or something that uses it internally, like [[Widgets]], within Tabulate.
  
=See also=
+
=Combining enumerations and tabulations=
 +
 
 +
{{cmd|NI}} (new item) exists since 2017-09-25. {{cmd|itemtag}} is old, but undocumented. Source: http://source.contextgarden.net/tex/context/base/mkiv/strc-itm.mkvi?search=itemtag
 +
 
 +
<context mode=mkiv source=yes>
 +
\startitemize[n]
 +
\starttabulate[|||||]
 +
\NC p \NC \itemtag \NC q \NC r \NC \NR
 +
\NC p \NC \itemtag \NC q \NC r \NC \NR
 +
\NC p \NC \itemtag \NC q \NC r \NC \NR
 +
\NC p \NC \itemtag \NC q \NC r \NC \NR
 +
\stoptabulate
 +
\stopitemize
 +
</context>
 +
 
 +
<texcode>
 +
\startitemize[n]
 +
\starttabulate[|||||]
 +
\NI x \NC y \NC z \NC \NR
 +
\NI x \NC y \NC z \NC \NR
 +
\NI x \NC y \NC z \NC \NR
 +
\NI x \NC y \NC z \NC \NR
 +
\stoptabulate
 +
\stopitemize
 +
 
 +
\startitemize[n]
 +
\starttabulate[|||||]
 +
\NI b \NC c \NC d \NC \NR
 +
\NC a \NI c \NC d \NC \NR
 +
\NC a \NC b \NI d \NC \NR
 +
\NC a \NC b \NC c \NI \NR
 +
\stoptabulate
 +
\stopitemize
 +
</texcode>
  
* More features are constantly added and documented only in the [[source:tabl-tbl.mkiv|source]].
 
  
* {{cmd|starttabulate}}
+
=See also=
  
 +
* More features are constantly added and documented in the {{src|tabl-tbl.mkiv|source}}.
 +
* {{cmd|starttabulate}}, {{cmd|setuptabulate}}
 
* [[TABLE|Natural Tables]]
 
* [[TABLE|Natural Tables]]
 
+
* {{cmd|starttable}}, <s>{{cmd|setuptable}}</s>
* {{cmd|starttable}}
 
  
 
[[Category:Tables]]
 
[[Category:Tables]]

Revision as of 11:54, 21 December 2018

< Tables Overview | Table >


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|lB|]
\HL
\NC {\bf format} \NC {\bf meaning} \NC Mk \NC\NR
\HL
\NC c      \NC centered                               \NC \NC\NR
\NC l      \NC left aligned                           \NC \NC\NR
\NC r      \NC right aligned                          \NC \NC\NR
\NC w(1cm) \NC one line, fixed width                  \NC \NC\NR
\NC p(2cm) \NC paragraph, lines broken to fixed width \NC \NC\NR
\NC cg(.)  \NC align on a character \NC IV: cg{.} \NC\NR
\NC m      \NC math mode                          \NC IV only \NC\NR
\NC b      \NC before e.g. b{\star}                          \NC IV only \NC\NR
\NC a      \NC after, e.g. a{\percent}                        \NC IV only \NC\NR
\HL
\stoptabulate
  • \HL draws a horizontal rule,
  • \NC marks a new column (or new cell),
  • \NN marks a new math column/cell (see below),
  • \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);
  • \TB (= "Table Blank") adds some vertical space between rows -- see an example bellow,
  • \VL (instead of \NC) draws a vertical rule -- for more info see below.

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)|]

(Mistake: This doesn’t account for the width of the column distance!)

Horizontal centering table on the page

This is a very long text, longer than the width of the table.
It must be long enough to flow to the next line to see the effect.

\placetable[force,none]{}{%
  \starttabulate[|r|l|]
  \HL
  \NC I want this table \NC aligned in the center.\NC\NR
  \HL
  \stoptabulate
}

This can also be done with the start/stop syntax (showing only source here, since it does not compile on the wiki):

This is a very long text, longer than the width of the table.
It must be long enough to flow to the next line to see the effect.

\startplacetable[location=force,number=no]
  \starttabulate[|r|l|]
  \HL
  \NC I want this table \NC aligned in the center.\NC\NR
  \HL
  \stoptabulate
\stopplacetable

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]
\setuppagenumbering[location={header,inright}]
\showframe[edge]

\setuptabulate
   [split=yes,
    header=text,
    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

internal error: convert failed


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]
\setuppagenumbering[location={header,inright}]
\showframe[edge]

\setuptabulate
   [split=yes,
    header=text,
    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

internal error: convert failed


Headers

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

In ConTeXt MkIV the command requires an additional [], thus you need to write \starttabulatehead[] instead.

\setuptabulate[split=yes,header=repeat]

\starttabulatehead
  \FL
  \NC {\bf format char} \NC {\bf meaning} \NC \AR
  \LL
\stoptabulatehead

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

Note the use of \FL and \LL in the tabulate header rather than \HL which is a standard rule command (see below) that tries to guess automatically its position.

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 option 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 & Text

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

There are five 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.
\CT color is applied to the text itself - in other words, the "foreground color."

These are to complement the normal table layout expression (the first argument to {{cmd|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, or by the shorter variant described above.

\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

\starttabulate
  \NC one   \NC two   \NC\NR 
  \NC two   \NC three \NC\NR 
  \TB[halfline]
  \NC four  \NC five  \NC\NR 
  \TB[line]
  \NC four  \NC five  \NC\NR 
  \TB[1cm]
  \NC eight \NC nine \NC\NR 
\stoptabulate

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

instead of

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

although both variants do work.

If you always need math in one column, consider math mode columns:

\starttabulate[|m|m|]
\HL
\NC 10e-3 \NC 10e+3  \NR
\HL
\stoptabulate


Itemization or framed objects 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

The same is true if you use \framed or something that uses it internally, like Widgets, within Tabulate.

Combining enumerations and tabulations

\NI (new item) exists since 2017-09-25. \itemtag is old, but undocumented. Source: http://source.contextgarden.net/tex/context/base/mkiv/strc-itm.mkvi?search=itemtag

\startitemize[n]
\starttabulate[|||||]
\NC p \NC \itemtag \NC q \NC r \NC \NR
\NC p \NC \itemtag \NC q \NC r \NC \NR
\NC p \NC \itemtag \NC q \NC r \NC \NR
\NC p \NC \itemtag \NC q \NC r \NC \NR
\stoptabulate
\stopitemize

\startitemize[n]
\starttabulate[|||||]
\NI x \NC y \NC z \NC \NR
\NI x \NC y \NC z \NC \NR
\NI x \NC y \NC z \NC \NR
\NI x \NC y \NC z \NC \NR
\stoptabulate
\stopitemize

\startitemize[n]
\starttabulate[|||||]
\NI b \NC c \NC d \NC \NR
\NC a \NI c \NC d \NC \NR
\NC a \NC b \NI d \NC \NR
\NC a \NC b \NC c \NI \NR
\stoptabulate
\stopitemize


See also