summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/tabularray/tabularray.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2022-03-02 03:03:38 +0000
committerNorbert Preining <norbert@preining.info>2022-03-02 03:03:38 +0000
commit1769d3d8842ef66919943128931e647de9756adb (patch)
tree46df94f2204cba9384cccf5ab6ca8cbbcd49bcad /macros/latex/contrib/tabularray/tabularray.tex
parent3e9a44ea155766214d8657ed79db2206592b6e8e (diff)
CTAN sync 202203020303
Diffstat (limited to 'macros/latex/contrib/tabularray/tabularray.tex')
-rw-r--r--macros/latex/contrib/tabularray/tabularray.tex482
1 files changed, 388 insertions, 94 deletions
diff --git a/macros/latex/contrib/tabularray/tabularray.tex b/macros/latex/contrib/tabularray/tabularray.tex
index c2fddc1e36..95416b6d46 100644
--- a/macros/latex/contrib/tabularray/tabularray.tex
+++ b/macros/latex/contrib/tabularray/tabularray.tex
@@ -1,15 +1,19 @@
% -*- coding: utf-8 -*-
% !TEX program = lualatex
\documentclass[oneside]{book}
-\newcommand*{\myversion}{2021Q}
+\newcommand*{\myversion}{2022A}
\newcommand*{\mylpad}[1]{\ifnum#1<10 0\the#1\else\the#1\fi}
\usepackage[a4paper,margin=2.5cm]{geometry}
+\setlength{\parindent}{0pt}
+\setlength{\parskip}{4pt plus 1pt minus 1pt}
+
\usepackage{codehigh} % https://ctan.org/pkg/codehigh
\usepackage{tabularray}
\usepackage{array,multirow,amsmath}
\usepackage{chemmacros,environ}
+\usepackage{enumitem}
\usepackage[firstpage=true]{background}
\backgroundsetup{contents={}}
@@ -84,8 +88,8 @@
%color = black,
contents = {
\begin{tblr}{
- width = \paperwidth, columns = {1}, rows= {4em},
- cell{odd}{odd} = {gray9}, cell{even}{even} = {gray9},
+ width = \paperwidth, columns = {1}, rows= {4em, gray9},
+ hlines = {2.8pt,white}, vlines = {2.8pt,white},
}
& & & & & & & & & & & & & & \\
& & & & & & & & & & & & & & \\
@@ -105,8 +109,6 @@
& & & & & & & & & & & & & & \\
& & & & & & & & & & & & & & \\
& & & & & & & & & & & & & & \\
- & & & & & & & & & & & & & & \\
- & & & & & & & & & & & & & & \\
\end{tblr}
}
}
@@ -154,6 +156,13 @@
\chapter{Overview of Features}
+Before using \verb!tabularray! package, it is better to know how to typeset simple text and
+math tables with traditional \verb!tabular!, \verb!tabularx! and \verb!array! environments,
+because we will compare \verb!tblr! environment from \verb!tabularray! package with these
+environments. You may read web pages on LaTeX tables on
+\href{https://www.learnlatex.org/en/lesson-08}{LearnLaTeX} and
+\href{https://www.overleaf.com/learn/latex/Tables}{Overleaf} first.
+
\section{Vertical Space}
After loading \verb!tabularray! package in the preamble,
@@ -185,7 +194,7 @@ The following is our first example:
\end{tblr}
\end{demohigh}
-You may notice that there is extra space above and below the table rows with \verb!tblr! envirenment.
+You may notice that there is extra space above and below the table rows with \verb!tblr! environment.
This space makes the table look better.
If you don't like it, you could use \verb!\SetTblrInner! command:
@@ -202,7 +211,7 @@ If you don't like it, you could use \verb!\SetTblrInner! command:
\end{tblr}
\end{demohigh}
-But in many cases, this rowsep is useful:
+But in many cases, this \verb!rowsep! is useful:
\begin{demo}
$\begin{array}{rrr}
@@ -367,7 +376,7 @@ It was a hard job to typeset cells with multiple rows and multiple columns. For
& \multicolumn{2}{c|}{2 Columns}
& \multicolumn{2}{c|}{\multirow{2}{*}{2 Rows 2 Columns}} \\
\cline{2-3}
-  & 2-2 & 2-3 & \multicolumn{2}{c|}{} \\
+ & 2-2 & 2-3 & \multicolumn{2}{c|}{} \\
\hline
3-1 & 3-2 & 3-3 & 3-4 & 3-5 \\
\hline
@@ -387,7 +396,7 @@ Therefore it's much simpler to typeset spanned cells:
& \SetCell[c=2]{c} 2 Columns
& & \SetCell[r=2,c=2]{c} 2 Rows 2 Columns & \\
\hline
-  & 2-2 & 2-3 & & \\
+ & 2-2 & 2-3 & & \\
\hline
3-1 & 3-2 & 3-3 & 3-4 & 3-5 \\
\hline
@@ -484,7 +493,7 @@ It's better to specify horizontal alignment in \verb!colspec!,
and vertical alignment in \verb!rowspec!, respectively.
Inside \verb!rowspec!, \verb!|! is the hline type.
-Therefore we need not to write \verb!\hline! commnad, which makes table code cleaner.
+Therefore we need not to write \verb!\hline! command, which makes table code cleaner.
\section{Hlines and Vlines}
@@ -505,7 +514,8 @@ Seven & Eight & Nine \\
\section{Colorful Tables}
To add colors to your tables, you need to load \verb!xcolor! package first.
-\verb!Tabularray! package will also load \verb!ninecolors! package for proper color contrast.
+\verb!Tabularray! package will also load
+\href{https://ctan.org/pkg/ninecolors}{\texttt{ninecolors}} package for proper color contrast.
First you can specify background option for \verb!Q! rows/columns inside \verb!rowspec!/\verb!colspec!:
\begin{demohigh}
@@ -564,6 +574,7 @@ Hlines and vlines can also have colors:
\end{demohigh}
\chapter{Basic Interfaces}
+\label{chap:basic}
\section{Old and New Interfaces}
@@ -583,9 +594,11 @@ hence totally separating the styles and the contents of tables.
]{verb}
Old Interfaces & New Interfaces \\
\verb!\SetHlines! & \K{hlines} \\
- \verb!\SetHline!, \verb!\hline!, \verb!\cline! & \K{hline}, \K{rowspec} \\
+ \verb!\SetHline!, \verb!\hline!, \verb!\hborder!, \verb!\cline!
+ & \K{hline}, \K{hborder}, \K{rowspec} \\
\verb!\SetVlines! & \K{vlines} \\
- \verb!\SetVline!, \verb!\vline!, \verb!\rline! & \K{vline}, \K{colspec} \\
+ \verb!\SetVline!, \verb!\vline!, \verb!\vborder!, \verb!\rline!
+ & \K{vline}, \K{vborder}, \K{colspec} \\
\verb!\SetCells! & \K{cells} \\
\verb!\SetCell! & \K{cell} \\
\verb!\SetRows! & \K{rows} \\
@@ -611,10 +624,6 @@ All available keys for hlines and vlines are described in Table \ref{key:hline}
\K{leftpos} & crossing or trimming position at the left side & \V{1} \\
\K{rightpos} & crossing or trimming position at the right side & \V{1} \\
\K{endpos} & adjust leftpos/rightpos for only the leftmost/rightmost column & \V{false} \\
- \K{abovespace} & set \V{belowsep} of previous row (see Table \ref{key:row}) & \V{2pt} \\
- \K{belowspace} & set \V{abovesep} of current row (see Table \ref{key:row}) & \V{2pt} \\
- \K{abovespace+} & increase \V{belowsep} of previous row & \None \\
- \K{belowspace+} & increase \V{abovesep} of current row & \None \\
\end{spectblr}
\vspace{-2em}
\begin{spectblr}[
@@ -720,7 +729,7 @@ Their values are the same as options \verb!hlines! and \verb!vlines!:
\end{tblr}
\end{demohigh}
-You can use \verb!X!, \verb!Y!, \verb!Z! to denote the last three childs, respectively.
+You can use \verb!X!, \verb!Y!, \verb!Z! to denote the last three children, respectively.
It is especially useful when you are writing long tables:
\begin{demohigh}
@@ -892,6 +901,42 @@ The usages of table commands \verb!\vline!, \verb!\rline!, \verb!\SetVline!, \ve
are similar to those of \verb!\hline!, \verb!\cline!, \verb!\SetHline!, \verb!\SetHlines!, respectively.
But normally you don't need to use them.
+\section{Hborders and Vborders}
+
+Options \verb!hborder{i}! and \verb!vborder{j}! are similar to \verb!hline{i}! and \verb!vline{j}!,
+respectively, but they hold border specifications not related to one specific hline and vline.
+All available keys for \verb!hborder{i}! and \verb!vborder{j}! are described in
+Table~\ref{key:hborder} and Table~\ref{key:vborder}.
+
+\begin{spectblr}[
+ caption = {Keys for Hborders},
+ label = {key:hborder},
+]{}
+ Key & Description and Values & Initial Value \\
+ \K{pagebreak} & pagebreak at this position: \V{yes}, \V{no} or \V{auto}
+ (See Chapter~\ref{chap:long}) & \V{auto} \\
+ \K{abovespace} & set \V{belowsep} of previous row (see Table \ref{key:row}) & \V{2pt} \\
+ \K{belowspace} & set \V{abovesep} of current row (see Table \ref{key:row}) & \V{2pt} \\
+ \K{abovespace+} & increase \V{belowsep} of previous row & \None \\
+ \K{belowspace+} & increase \V{abovesep} of current row & \None \\
+\end{spectblr}
+\vspace{-2em}
+\begin{spectblr}[
+ caption = {Keys for Vborders},
+ label = {key:vborder},
+]{}
+ Key & Description and Values & Initial Value \\
+ \K{leftspace} & set \V{rightsep} of previous column (see Table \ref{key:column}) & \V{6pt} \\
+ \K{rightspace} & set \V{leftsep} of current column (see Table \ref{key:column}) & \V{6pt} \\
+ \K{leftspace+} & increase \V{rightsep} of previous column & \None \\
+ \K{rightspace+} & increase \V{leftsep} of current column & \None \\
+\end{spectblr}
+
+Furthermore, table command \verb!\hborder{<specs>}! at the beginning of row \verb!i!
+is the same as table option \verb!hborder{i}={<specs>}!,
+and table command \verb!\vborder{<specs>}! at the beginning of column \verb!j!
+is the same as table option \verb!vborder{j}={<specs>}!.
+
\section{Cells and Spancells}
All available keys for cells are described in Table \ref{key:cell} and Table \ref{key:cellspan}.
@@ -904,7 +949,7 @@ All available keys for cells are described in Table \ref{key:cell} and Table \re
Key & Description and Values & Initial Value \\
\underline{\K{halign}}
& horizontal alignment: \V{l} (left), \V{c} (center), \V{r} (right) or \V{j} (justify)
- & \V{l} \\
+ & \V{j} \\
\underline{\K{valign}}
& vertical alignment: \V{t} (top), \V{m} (middle), \V{b} (bottom),
\V{h} (head) or \V{f} (foot)
@@ -1040,8 +1085,8 @@ All available keys for rows and columns are described in Table \ref{key:row} and
]{verb}
Key & Description and Values & Initial Value \\
\underline{\K{halign}}
- & horizontal alignment: \V{l} (left), \V{c} (center), or \V{r} (right)
- & \V{l} \\
+ & horizontal alignment: \V{l} (left), \V{c} (center), \V{r} (right) or \V{j} (justify)
+ & \V{j} \\
\underline{\K{valign}}
& vertical alignment: \V{t} (top), \V{m} (middle), \V{b} (bottom),
\V{h} (head) or \V{f} (foot)
@@ -1071,8 +1116,8 @@ All available keys for rows and columns are described in Table \ref{key:row} and
]{verb}
Key & Description and Values & Initial Value \\
\underline{\K{halign}}
- & horizontal alignment: \V{l} (left), \V{c} (center), or \V{r} (right)
- & \V{l} \\
+ & horizontal alignment: \V{l} (left), \V{c} (center), \V{r} (right) or \V{j} (justify)
+ & \V{j} \\
\underline{\K{valign}}
& vertical alignment: \V{t} (top), \V{m} (middle), \V{b} (bottom),
\V{h} (head) or \V{f} (foot)
@@ -1220,7 +1265,7 @@ with column/row type specifiers.
\subsection{Colspec and Width}
-Option \verb!width! are for setting the width of the table with extendable columns.
+Option \verb!width! is for setting the width of the table with extendable columns.
The following example demonstrates the usage of \verb!width! option.
\nopagebreak
\begin{demohigh}
@@ -1302,13 +1347,31 @@ It can have an optional argument when it's defined.
\chapter{Extra Interfaces}
\label{chap:extra}
-\section{Table Specifications}
+In general, \verb!tblr! environment can accepts both inner and outer specifications:
+
+\begin{codehigh}
+\begin{tblr}[<outer specs>]{<inner specs>}
+ <table body>
+\end{tblr}
+\end{codehigh}
+
+\textbf{Inner specifications} are all specifications written in the \underline{mandatory} argument
+of \verb!tblr! environment, which include new interfaces described in Chapter \ref{chap:basic}.
-All available keys for the whole table are described in Table \ref{key:table}.
+\textbf{Outer specifications} are all specifications written in the \underline{optional} argument
+of \verb!tblr! environment, most of which are used for long tables (see Chapter \ref{chap:long}).
+
+You can use \verb!\SetTblrInner! and \verb!\SetTblrOuter! commands
+to set default inner and outer specifications of tables, respectively.
+
+\section{Inner Specifications}
+
+In addition to new interfaces in Chapter \ref{chap:basic},
+there are several inner specifications which are described in Table~\ref{key:inner}.
\begin{spectblr}[
- caption = {Keys for the Whole Table},
- label = {key:table},
+ caption = {Keys for Inner Specifications},
+ label = {key:inner},
]{}
Key & Description and Values & Initial Value \\
\K{rulesep} & space between two hlines or vlines & \V{2pt} \\
@@ -1321,8 +1384,12 @@ All available keys for the whole table are described in Table \ref{key:table}.
\K{colsep} & set horizontal space to both sides of every column & \V{6pt} \\
\K{hspan} & horizontal span algorithm: \V{default}, \V{even}, or \V{minimal} & \V{default} \\
\K{vspan} & vertical span algorithm: \V{default} or \V{even} & \V{default} \\
+ \K{verb} & you need this key to use verb commands & \None \\
+ \K{baseline} & set the baseline of the table & \V{m} \\
\end{spectblr}
+\subsection{Space between Double Rules}
+
The following example shows that we can replace \verb!\doublerulesep! parameter with \verb!rulesep! key.
\nopagebreak
\begin{demohigh}
@@ -1335,6 +1402,8 @@ The following example shows that we can replace \verb!\doublerulesep! parameter
\end{tblr}
\end{demohigh}
+\subsection{Minimal Strut for Cell Text}
+
The following example shows that we can replace \verb!\arraystretch! parameter with \verb!stretch! key.
\begin{demohigh}
@@ -1345,6 +1414,8 @@ The following example shows that we can replace \verb!\arraystretch! parameter w
\end{tblr}
\end{demohigh}
+\subsection{Rowseps and Colseps for All}
+
The following example uses \verb!rowsep! and \verb!colsep! keys to set padding for all rows and columns.
\nopagebreak
\begin{demohigh}
@@ -1356,6 +1427,8 @@ The following example uses \verb!rowsep! and \verb!colsep! keys to set padding f
\end{tblr}
\end{demohigh}
+\subsection{Hspan and Vspan Algorithms}
+
With \verb!hspan=default! or \verb!hspan=even!,
\verb!tabularray! package will compute column widths from span widths.
But with \verb!hspan=minimal!, it will compute span widths from column widths.
@@ -1419,56 +1492,102 @@ The following examples show the results from different \verb!vspan! values.
\end{tblr}
\end{demohigh}
-\section{Default Specifications}
+\subsection{Use Verbatim Commands}
-\verb!Tabularray! package provides \verb!\SetTblrInner! and \verb!\SetTblrOuter! commands
-for you to change the default inner and outer specifications of tables.
-Inner specifications are all specifications written in the mandatory argument of the \verb!tblr! environment,
-while outer specifications are all specifications written in the optional argument of the \verb!tblr! environment.
-At this time, most of the outer specifications are used for long tables (see Chapter \ref{chap:long}).
+With \verb!verb! key, you can write \verb!\verb! commands in the cell text:
-In the below example, the first line draws all hlines and vlines for all tables created afterwards,
-while the second line makes all tables created afterwards vertically align at bottom.
+\begin{demohigh}
+\begin{tblr}{hlines,verb}
+ 20 & 30 & \verb!\hello{world}!40 \\
+ 50 & \verb!\hello!60 & 70 \\
+\end{tblr}
+\end{demohigh}
-\begin{codehigh}
-\SetTblrInner{hlines,vlines}
-\SetTblrOuter{valign=b}
-\end{codehigh}
+\subsection{Set Baseline for the Table}
-You can define new \verb!tabularray! environments using \verb!\NewTblrEnviron! command:
+With \verb!baseline! key, you can set baseline for the table.
+All possible values for \verb!baseline! are as follows:
+
+\begin{center}
+\begin{tblr}{width=0.6\textwidth,colspec={cX[l]},hlines}
+ \V{t} & align the table at the top \\
+ \V{T} & align the table at the first row \\
+ \V{m} & align the table at the middle, initial value \\
+ \V{b} & align the table at the bottom \\
+ \V{B} & align the table at the last row \\
+ \V{<n>} & align the table at row \V{<n>} (a positive integer) \\
+\end{tblr}
+\end{center}
+
+If there is no hline above the first row, you get the same result with either \V{t} or \V{T}.
+But you get different results if there are one or more hlines above the row:
\begin{demohigh}
-\NewTblrEnviron{mytblr}
-\SetTblrInner[mytblr]{hlines,vlines}
-\SetTblrOuter[mytblr]{valign=b}
-Text \begin{mytblr}{cccc}
- Alpha & Beta & Gamma & Delta \\
- Epsilon & Zeta & Eta & Theta \\
- Iota & Kappa & Lambda & Mu \\
-\end{mytblr} Text
+Baseline\begin{tblr}{hlines,baseline=t}
+ Alpha & Beta & Gamma \\
+ Epsilon & Zeta & Eta \\
+ Iota & Kappa & Lambda \\
+\end{tblr}Baseline
\end{demohigh}
-If not giving the optional argument to \verb!\SetTblrInner! or \verb!\SetTblrOuter! command,
-we set the default specifications for \verb!tblr! environment.
-And different tabularray environments could have different default specifications.
+\begin{demohigh}
+Baseline\begin{tblr}{hlines,baseline=T}
+ Alpha & Beta & Gamma \\
+ Epsilon & Zeta & Eta \\
+ Iota & Kappa & Lambda \\
+\end{tblr}Baseline
+\end{demohigh}
-\section{New Table Commands}
+The differences between \verb!b! and \verb!B! are similar to \verb!t! and \verb!T!.
+In fact, these two values \verb!T! and \verb!B! are better replacements
+for currently obsolete \verb!\firsthline! and \verb!\lasthline! commands.
-All commands which change the specifications of tables \textcolor{red3}{must} be defined with \verb!\NewTableCommand!.
-The following example demonstrates how to define a new table command:
+\section{Outer Specifications}
+
+Except for specifications to be introduced in Chapter \ref{chap:long},
+there are several other outer specifications which are described in Table~\ref{key:outer}.
+
+\begin{spectblr}[
+ caption = {Keys for Outer Specifications},
+ label = {key:outer},
+]{}
+ Key & Description and Values & Initial Value \\
+ \K{baseline} & set the baseline of the table & \V{m} \\
+ \K{long} & change the table to a long table & \None \\
+ \K{tall} & change the table to a tall table & \None \\
+ \K{expand} & you need this key to use verb commands & \None \\
+\end{spectblr}
+
+\subsection{Set Baseline in Another Way}
+
+You may notice that you can write \K{baseline} option as either an inner or an outer specification.
+It is true that either way would do the job. But there is a small difference:
+when \verb!baseline=t/T/m/b/B! is an outer specification,
+you can omit the key name and write the value only.
\begin{demohigh}
-\NewTableCommand\myhline{\hline[0.1em,red5]}
-\begin{tblr}{llll}
-\myhline
- Alpha & Beta & Gamma & Delta \\
- Epsilon & Zeta & Eta & Theta \\
- Iota & Kappa & Lambda & Mu \\
-\myhline
-\end{tblr}
+Baseline\begin{tblr}[m]{hlines}
+ Alpha & Beta & Gamma \\
+ Epsilon & Zeta & Eta \\
+ Iota & Kappa & Lambda \\
+\end{tblr}Baseline
\end{demohigh}
-\section{Expand Macros First}
+\subsection{Long and Tall Tables}
+
+You can change a table to long table by passing outer specification \K{long},
+or change it to tall table by passing outer specification \K{tall} (see Chapter~\ref{chap:long}).
+Therefore the following two tables are the same:
+\begin{codehigh}
+\begin{longtblr}{lcr}
+ Alpha & Beta & Gamma
+\end{longtblr}
+\begin{tblr}[long]{lcr}
+ Alpha & Beta & Gamma
+\end{tblr}
+\end{codehigh}
+
+\subsection{Expand Macros First}
\verb!Tabularray! need to see every \verb!&! and \verb!\\! when splitting the table body
with \verb!l3regex!. And you can not put cell text inside any table command defined with
@@ -1495,17 +1614,61 @@ The macro \underline{can not} be defined with \verb!\NewDocumentCommand! or
\end{tblr}
\end{demohigh}
-With this \verb!expand! option, you can also use \verb!environ! package
-to define a new environment based on \verb!tblr! environment:
+\section{Default Specifications}
+
+\verb!Tabularray! package provides \verb!\SetTblrInner! and \verb!\SetTblrOuter! commands
+for you to change the default inner and outer specifications of tables.
+
+In the below example, the first line draws all hlines and vlines for all tables created afterwards,
+while the second line makes all tables created afterwards vertically align at the last row.
+
+\begin{codehigh}
+\SetTblrInner{hlines,vlines}
+\SetTblrOuter{baseline=B}
+\end{codehigh}
+
+\section{New Tabularray Environments}
+
+You can define new \verb!tabularray! environments using \verb!\NewTblrEnviron! command:
\begin{demohigh}
-\NewEnviron{fancytblr}{
- Before Text
- \begin{tblr}[expand=\BODY]{hlines}
- \BODY
- \end{tblr}
- After Text
-}
+\NewTblrEnviron{mytblr}
+\SetTblrInner[mytblr]{hlines,vlines}
+\SetTblrOuter[mytblr]{baseline=B}
+Text \begin{mytblr}{cccc}
+ Alpha & Beta & Gamma & Delta \\
+ Epsilon & Zeta & Eta & Theta \\
+ Iota & Kappa & Lambda & Mu \\
+\end{mytblr} Text
+\end{demohigh}
+
+If not giving the optional argument to \verb!\SetTblrInner! or \verb!\SetTblrOuter! command,
+we set the default specifications for \verb!tblr! environment.
+And different tabularray environments could have different default specifications.
+
+\section{New General Environments}
+
+With \verb!+b! argument type of \verb!\NewDocumentEnvironment! command,
+you can also define a new general environment based on \verb!tblr! environment
+(note that there is an extra pair of curly braces at the end):
+
+\NewDocumentEnvironment{fancytblr}{+b}{
+ Before Text
+ \begin{tblr}{hlines}
+ #1
+ \end{tblr}
+ After Text
+}{}
+\begin{codehigh}
+\NewDocumentEnvironment{fancytblr}{+b}{
+ Before Text
+ \begin{tblr}{hlines}
+ #1
+ \end{tblr}
+ After Text
+}{}
+\end{codehigh}
+\begin{demohigh}
\begin{fancytblr}
One & Two & Three \\
Four & Five & Six \\
@@ -1513,14 +1676,60 @@ to define a new environment based on \verb!tblr! environment:
\end{fancytblr}
\end{demohigh}
-\section{Use Verbatim Commands}
+\section{New Table Commands}
-With inner specification \verb!verb!, you can write \verb!\verb! commands in the cell text:
+All commands which change the specifications of tables \textcolor{red3}{must} be defined with \verb!\NewTableCommand!.
+The following example demonstrates how to define a new table command:
\begin{demohigh}
-\begin{tblr}{hlines,verb}
- 20 & 30 & \verb!\hello{world}!40 \\
- 50 & \verb!\hello!60 & 70 \\
+\NewTableCommand\myhline{\hline[0.1em,red5]}
+\begin{tblr}{llll}
+\myhline
+ Alpha & Beta & Gamma & Delta \\
+ Epsilon & Zeta & Eta & Theta \\
+ Iota & Kappa & Lambda & Mu \\
+\myhline
+\end{tblr}
+\end{demohigh}
+
+\section{Odd and Even Selectors}
+
+From version 2022A, child selectors \verb!odd! and \verb!even! accept an optional argument,
+in which you can specify the start index and the end index of the children.
+
+\begin{demohigh}
+\begin{tblr}{
+ cell{odd}{1} = {red9},
+ cell{odd[4]}{2} = {green9},
+ cell{odd[3-X]}{3} = {blue9},
+}
+ Head & Head & Head \\
+ Talk A & Place A & Date A \\
+ Talk B & Place B & Date B \\
+ Talk C & Place C & Date C \\
+ Talk D & Place D & Date D \\
+ Talk E & Place E & Date E \\
+ Talk F & Place F & Date F \\
+ Talk G & Place G & Date G \\
+ Talk H & Place H & Date H \\
+\end{tblr}
+\end{demohigh}
+
+\begin{demohigh}
+\begin{tblr}{
+ cell{even}{1} = {yellow9},
+ cell{even[4]}{2} = {cyan9},
+ cell{even[3-X]}{3} = {purple9},
+}
+ Head & Head & Head \\
+ Talk A & Place A & Date A \\
+ Talk B & Place B & Date B \\
+ Talk C & Place C & Date C \\
+ Talk D & Place D & Date D \\
+ Talk E & Place E & Date E \\
+ Talk F & Place F & Date F \\
+ Talk G & Place G & Date G \\
+ Talk H & Place H & Date H \\
\end{tblr}
\end{demohigh}
@@ -1773,7 +1982,7 @@ Alpha & Beta & Gamma \\
As you can see in the above example, the appearance of long tables of \verb!tabularray! package
is similar to that of \verb!threeparttablex! packages.
-We support table footnotes, but not page footnotes in \verb!tabularray! package.
+It supports table footnotes, but not page footnotes.
\newpage
@@ -1837,7 +2046,7 @@ The source code for the above long table is shown below. It is mainly self-expla
\end{longtblr}
\end{codehigh}
-As you can see in the above code, we typeset long tables with \verb!longtblr! environemnt.
+As you can see in the above code, we typeset long tables with \verb!longtblr! environment.
And we can totally separate contents and styles of long tables with \verb!tabularray! package.
Row head and row foot consist of some lines of the table and should appear in every page.
@@ -1885,7 +2094,9 @@ in \verb!longtable!, except for the counter.
The template system for table heads and table foots in \verb!tabularray! is largely inspired
by \verb!beamer!, \verb!caption! and \verb!longtable! packages. For elements in Table \ref{tblr:element},
-you can use \verb!\DefTblrTemplate! to define and modify templates,
+you can use \verb!\DefTblrTemplate!\footnote{From version 2022A,
+\texttt{\string\DefTblrTemplate} has another name \texttt{\string\DeclareTblrTemplate}.}
+to define and modify templates,
and use \verb!\SetTblrTemplate! to choose default templates. In defining templates,
you can include other templates with \verb!\UseTblrTemplate! and \verb!\ExpTblrTemplate! commands.
@@ -1996,7 +2207,7 @@ The \verb!capcont! template will be used in \verb!middlehead! and \verb!lasthead
\UseTblrTemplate{caption-tag}{default}
\UseTblrTemplate{caption-sep}{default}
\UseTblrTemplate{caption-text}{default}
- \UseTblrTemplate{conthead}{default}
+ \UseTblrTemplate{conthead-text}{default}
}
\end{codehigh}
@@ -2066,6 +2277,14 @@ The templates for table heads and foots are defined as including other templates
\end{codehigh}
Note that you can define the same template for multiple elements in \verb!\DefTblrTemplate! command.
+If you only want to show table caption in the first page, you may change the definitions of
+\verb!middlehead! and \verb!lasthead! elements:
+
+\begin{codehigh}
+\DefTblrTemplate{middlehead,lasthead}{default}{
+ \UseTblrTemplate{conthead}{default}
+}
+\end{codehigh}
\section{Change Styles}
@@ -2077,12 +2296,14 @@ All available keys for template elements are described in Table \ref{key:element
remark{Note} = {In most cases, you can omit the underlined key names and write only their values.
The keys \K{halign}, \K{indent} and \K{hang} are only for main templates.}
]{}
- Key Name & Key Description \\
- \underline{\K{fg}} & foreground color \\
- \underline{\K{font}} & font commands \\
- \underline{\K{halign}} & horizontal alignment: \V{l} (left), \V{c} (center), or \V{r} (right) \\
- \K{indent} & parindent value \\
- \K{hang} & hangindent value \\
+ Key Name & Key Description & Initial Value\\
+ \underline{\K{fg}} & foreground color & \None \\
+ \underline{\K{font}} & font commands & \None \\
+ \underline{\K{halign}}
+ & horizontal alignment: \V{l} (left), \V{c} (center), \V{r} (right) or \V{j} (justify)
+ & \V{j} \\
+ \K{indent} & parindent value & \V{0pt} \\
+ \K{hang} & hangindent value & \V{0pt} or \V{0.7em} \\
\end{spectblr}
You may change the styles of elements with \verb!\SetTblrStyle! command:
@@ -2228,7 +2449,7 @@ you can also specify rule width and color in the optional argument of any of the
\end{tblr}
\end{demohigh}
-If you need more than one cmidrules, you can use \verb!\cmidrulemore! command.
+If you need more than one \verb!\cmidrule!s, you can use \verb!\cmidrulemore! command.
\begin{demohigh}
\begin{tblr}{llll}
@@ -2320,6 +2541,9 @@ and the other half to \verb!abovesep! of current row.
\end{booktabs}
\end{demohigh}
+From version 2022A, there is a \verb!longtabs! environment for writing long \verb!booktabs! tables,
+and a \verb!talltabs! environment for writing tall \verb!booktabs! tables.
+
\section{Library \texttt{counter}}
You need to load \verb!counter! library with \verb!\UseTblrLibrary{counter}!,
@@ -2434,23 +2658,93 @@ By default, it uses \verb!\hbox! to measure the sizes.
This causes an error if a cell contains some vertical material, such as lists or display maths.
With \verb!\UseTblrLibrary{varwidth}! in the preamble of the document,
-\verb!tabularray! loads \verb!varwidth! package,
-and adds a new inner specification \verb!measure! for tables.
+\verb!tabularray! will load \verb!varwidth! package,
+and add a new inner specification \verb!measure! for tables.
After setting \verb!measure=vbox!, it will use \verb!\vbox! to measure cell widths.
\begin{demohigh}
-\begin{tblr}{measure=vbox}
-\hline
+\begin{tblr}{hlines,measure=vbox}
Text Text Text Text Text Text Text
\begin{itemize}
\item List List List List List List
\item List List List List List List List
\end{itemize}
Text Text Text Text Text Text Text \\
-\hline
\end{tblr}
\end{demohigh}
+From version 2022A, you can remove extra space above and below lists,
+by adding option \verb!stretch=-1!.
+The following example also needs \verb!enumitem! package and its \verb!nosep! option:
+
+{\centering\begin{tblr}{
+ hlines,vlines,rowspec={Q[l,t]Q[l,b]},
+ measure=vbox,stretch=-1,
+}
+ \begin{itemize}[nosep]
+ \item List List List List List
+ \item List List List List List List
+ \end{itemize} & oooo \\
+ \begin{itemize}[nosep]
+ \item List List List List List
+ \item List List List List List List
+ \end{itemize} & gggg \\
+\end{tblr}\par}
+
+%% BUG: there is extra vertical space at the beginning of the first cell if I use demohigh
+%\begin{demohigh}
+\begin{codehigh}
+\begin{tblr}{
+ hlines,vlines,rowspec={Q[l,t]Q[l,b]},
+ measure=vbox,stretch=-1,
+}
+ \begin{itemize}[nosep]
+ \item List List List List List
+ \item List List List List List List
+ \end{itemize} & oooo \\
+ \begin{itemize}[nosep]
+ \item List List List List List
+ \item List List List List List List
+ \end{itemize} & gggg \\
+\end{tblr}
+\end{codehigh}
+%\end{demohigh}
+
+Note that option \verb!stretch=-1! also removes struts from cells, therefore it may not work well
+in \verb!tabularray! environments with \verb!rowsep=0pt!, such as
+\verb!booktabs!/\verb!longtabs!/\verb!talltabs! environments from \verb!booktabs! library.
+
+\chapter{History and Future}
+
+\section{The Future}
+
+Starting from 2022, except for hotfix releases for critical bugs,
+all new releases will be published only in March, June, September or December.
+You may watch the milestones page for the scheduled dates of upcoming releases
+and their changes:\newline
+\centerline{\url{https://github.com/lvjr/tabularray/milestones}}
+
+To make the upcoming releases more stable, you are very welcome to test the latest package file
+in the repository. To test it, you only need to download the following \verb!tabularray.sty!
+and put it into the folder of your TeX documents:\newline
+\centerline{\url{https://github.com/lvjr/tabularray/raw/main/tabularray.sty}}
+
+\section{The History}
+
+The change log of \verb!tabularray! package will be updated on the wiki page:\newline
+\centerline{\url{https://github.com/lvjr/tabularray/wiki/ChangeLog}}
+
+In version 2022A, there were several breaking changes:
+
+\begin{itemize}[nosep]
+ \item \verb!\multicolumn! command was removed; it is better to use \verb!\SetCell! command.
+ \item \verb!\multirow! command was removed; it is better to use \verb!\SetCell! command.
+ \item \verb!\firsthline! command was removed; it is better to use \verb!baseline=T! option.
+ \item \verb!\lasthline! command was removed; it is better to use \verb!baseline=B! option.
+\end{itemize}
+
+For your old documents, you can still rollback to version 2021 by \verb!\usepackage{tabularray}[=v2021]!.
+
\chapter{The Source Code}
%\CodeHigh{lite}