summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/tabularray/tabularray.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/tabularray/tabularray.tex')
-rw-r--r--macros/latex/contrib/tabularray/tabularray.tex204
1 files changed, 164 insertions, 40 deletions
diff --git a/macros/latex/contrib/tabularray/tabularray.tex b/macros/latex/contrib/tabularray/tabularray.tex
index 0d502f3bbc..bda64717b4 100644
--- a/macros/latex/contrib/tabularray/tabularray.tex
+++ b/macros/latex/contrib/tabularray/tabularray.tex
@@ -1,6 +1,9 @@
% -*- coding: utf-8 -*-
% !TEX program = lualatex
\documentclass[oneside]{book}
+\newcommand*{\myversion}{2021P}
+\newcommand*{\mylpad}[1]{\ifnum#1<10 0\the#1\else\the#1\fi}
+
\usepackage[a4paper,margin=2.5cm]{geometry}
\usepackage{codehigh} % https://ctan.org/pkg/codehigh
@@ -11,7 +14,7 @@
\usepackage[firstpage=true]{background}
\backgroundsetup{contents={}}
-\UseTblrLibrary{booktabs,diagbox,siunitx,varwidth}
+\UseTblrLibrary{amsmath,booktabs,counter,diagbox,siunitx,varwidth}
\usepackage{hyperref}
\hypersetup{
@@ -58,10 +61,7 @@
\end{tcolorbox}
}
-\renewcommand*{\thefootnote}{*}
-
-\newcommand*{\myversion}{2021N}
-\newcommand*{\mylpad}[1]{\ifnum#1<10 0\the#1\else\the#1\fi}
+%\renewcommand*{\thefootnote}{*}
\colorlet{highback}{azure9}
\CodeHigh{language=latex/table,style/main=highback,style/code=highback}
@@ -353,6 +353,9 @@ therefore it always avoids vertical overflow:
\end{tblr}
\end{demohigh}
+If you want to distribute extra vertical space evenly to two rows,
+you may use \verb!vspan! option described in Chapter \ref{chap:extra}.
+
\section{Multi Rows and Columns}
It was a hard job to typeset cells with multiple rows and multiple columns. For example:
@@ -607,6 +610,7 @@ All available keys for hlines and vlines are described in Table \ref{key:hline}
\underline{\K{fg}} & rule color name & \None \\
\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 \\
@@ -657,14 +661,13 @@ Another pair of braces before will select segments in all hlines/vlines.
\begin{demohigh}
\begin{tblr}{
vlines = {1,3,5}{dashed},
- vlines = {2,4,6}{solid},
+ vlines = {2,4}{solid},
}
Alpha & Beta & Gamma & Delta \\
Epsilon & Zeta & Eta & Theta \\
Iota & Kappa & Lambda & Mu \\
Nu & Xi & Omicron & Pi \\
Rho & Sigma & Tau & Upsilon \\
- Phi & Chi & Psi & Omega \\
\end{tblr}
\end{demohigh}
@@ -682,7 +685,6 @@ Advanced users could read the source code for this.)
Iota & Kappa & Lambda & Mu \\
Nu & Xi & Omicron & Pi \\
Rho & Sigma & Tau & Upsilon \\
- Phi & Chi & Psi & Omega \\
\end{tblr}
\end{demohigh}
@@ -795,6 +797,22 @@ Here is an example for these four keys:
\end{tblr}
\end{demohigh}
+There is also an \verb!endpos! option for adjusting \verb!leftpos!/\verb!rightpos!
+for only the leftmost/rightmost column:
+
+\begin{demohigh}
+\begin{tblr}{
+ hline{1,4} = {1}{-}{},
+ hline{1,4} = {2}{-}{},
+ hline{2,3} = {leftpos = -1, rightpos = -1, endpos},
+ vline{1,4} = {abovepos = 1, belowpos = 1},
+}
+ Alpha & Beta & Gamma \\
+ Epsilon & Zeta & Eta \\
+ Iota & Kappa & Lambda \\
+\end{tblr}
+\end{demohigh}
+
\subsection{Hlines and Vlines in Old Interfaces}
The \verb!\hline! command has an optional argument which accepts key-value options.
@@ -882,7 +900,7 @@ All available keys for cells are described in Table \ref{key:cell} and Table \re
caption = {Keys for the Content of Cells},
label = {key:cell},
remark{Note} = {In most cases, you can omit the underlined key names and write only their values.}
-]{}
+]{verb}
Key & Description and Values & Initial Value \\
\underline{\K{halign}}
& horizontal alignment: \V{l} (left), \V{c} (center), \V{r} (right) or \V{j} (justify)
@@ -895,9 +913,12 @@ All available keys for cells are described in Table \ref{key:cell} and Table \re
\underline{\K{bg}} & background color name & \None \\
\K{fg} & foreground color name & \None \\
\K{font} & font commands & \None \\
+ \K{mode} & set cell mode: \V{math}, \V{imath}, \V{dmath} or \V{text} & \None \\
+ \verb!$! & same as \V{mode=math} & \None \\
+ \verb!$$! & same as \V{mode=dmath} & \None \\
+ \K{cmd} & execute command for the cell text & \None \\
\K{preto} & prepend text to the cell & \None \\
\K{appto} & append text to the cell & \None \\
- \K{cmd} & execute command for the cell text & \None \\
\end{spectblr}
\vspace{-2em}
\begin{spectblr}[
@@ -922,7 +943,16 @@ Option \verb!cells! is for setting all cells.
\end{tblr}
\end{demohigh}
-Option \verb!cell{i}{j}! is for setting some cells.
+Option \verb!cell{i}{j}! is for setting some cells,
+where \verb!i! stands for the row numbers and \verb!j! stands for the column numbers.
+\nopagebreak
+\begin{demohigh}
+\begin{tblr}{
+ cell{1}{2-4} = {cmd=\fbox}
+}
+ Alpha & Beta & Gamma & Delta
+\end{tblr}
+\end{demohigh}
\begin{demohigh}
\begin{tblr}{
@@ -1007,7 +1037,7 @@ All available keys for rows and columns are described in Table \ref{key:row} and
caption = {Keys for Rows},
label = {key:row},
remark{Note} = {In most cases, you can omit the underlined key names and write only their values.}
-]{}
+]{verb}
Key & Description and Values & Initial Value \\
\underline{\K{halign}}
& horizontal alignment: \V{l} (left), \V{c} (center), or \V{r} (right)
@@ -1020,6 +1050,10 @@ All available keys for rows and columns are described in Table \ref{key:row} and
\underline{\K{bg}} & background color name & \None \\
\K{fg} & foreground color name & \None \\
\K{font} & font commands & \None \\
+ \K{mode} & set mode for row cells: \V{math}, \V{imath}, \V{dmath} or \V{text} & \None \\
+ \verb!$! & same as \V{mode=math} & \None \\
+ \verb!$$! & same as \V{mode=dmath} & \None \\
+ \K{cmd} & execute command for every cell text & \None \\
\K{abovesep} & set vertical space above the row & \V{2pt} \\
\K{abovesep+} & increase vertical space above the row & \None \\
\K{belowsep} & set vertical space below the row & \V{2pt} \\
@@ -1028,14 +1062,13 @@ All available keys for rows and columns are described in Table \ref{key:row} and
\K{rowsep+} & increase vertical space above and below the row & \None \\
\K{preto} & prepend text to every cell (like \V{>} specifier in \K{rowspec}) & \None \\
\K{appto} & append text to every cell (like \V{<} specifier in \K{rowspec}) & \None \\
- \K{cmd} & execute command for every cell text & \None \\
\end{spectblr}
\vspace{-2em}
\begin{spectblr}[
caption = {Keys for Columns},
label = {key:column},
remark{Note} = {In most cases, you can omit the underlined key names and write only their values.}
-]{}
+]{verb}
Key & Description and Values & Initial Value \\
\underline{\K{halign}}
& horizontal alignment: \V{l} (left), \V{c} (center), or \V{r} (right)
@@ -1049,6 +1082,10 @@ All available keys for rows and columns are described in Table \ref{key:row} and
\underline{\K{bg}} & background color name & \None \\
\K{fg} & foreground color name & \None \\
\K{font} & font commands & \None \\
+ \K{mode} & set mode for column cells: \V{math}, \V{imath}, \V{dmath} or \V{text} & \None \\
+ \verb!$! & same as \V{mode=math} & \None \\
+ \verb!$$! & same as \V{mode=dmath} & \None \\
+ \K{cmd} & execute command for every cell text & \None \\
\K{leftsep} & set horizontal space to the left of the column & \V{6pt} \\
\K{leftsep+} & increase horizontal space to the left of the column & \None \\
\K{rightsep} & set horizontal space to the right of the column & \V{6pt} \\
@@ -1057,7 +1094,6 @@ All available keys for rows and columns are described in Table \ref{key:row} and
\K{colsep+} & increase horizontal space to both sides of the column & \None \\
\K{preto} & prepend text to every cell (like \V{>} specifier in \K{colspec}) & \None \\
\K{appto} & append text to every cell (like \V{<} specifier in \K{colspec}) & \None \\
- \K{cmd} & execute command for every cell text & \None \\
\end{spectblr}
\subsection{Rows and Columns in New Interfaces}
@@ -1093,7 +1129,7 @@ Options \verb!row{i}! and \verb!column{j}! are for setting some rows and columns
\end{tblr}
\end{demohigh}
-The following example demonstrates the usages of \verb!bg!, \verb!fg! and \verb!font! keys.
+The following example demonstrates the usages of \verb!bg!, \verb!fg! and \verb!font! keys:
\nopagebreak
\begin{demohigh}
\begin{tblr}{
@@ -1108,8 +1144,23 @@ The following example demonstrates the usages of \verb!bg!, \verb!fg! and \verb!
\end{tblr}
\end{demohigh}
+The following example demonstrates the usages of \verb!mode! key:
+\nopagebreak
+\begin{demohigh}
+$\begin{tblr}{
+ column{1} = {mode=text},
+ column{3} = {mode=dmath},
+}
+\hline
+ Alpha & \frac12 & \frac12 \\
+ Epsilon & \frac34 & \frac34 \\
+ Iota & \frac56 & \frac56 \\
+\hline
+\end{tblr}$
+\end{demohigh}
+
The following example demonstrates the usages of
-\verb!abovesep!, \verb!belowsep!, \verb!leftsep!, \verb!rightsep! keys.
+\verb!abovesep!, \verb!belowsep!, \verb!leftsep!, \verb!rightsep! keys:
%\nopagebreak
\begin{demohigh}
\begin{tblr}{
@@ -1180,6 +1231,19 @@ The following example demonstrates the usage of \verb!width! option.
\end{tblr}
\end{demohigh}
+You can omit \verb!colspec! name if it is the only key you use inside the mandatory argument.
+The following example demonstrates the usages of \verb!$! and \verb!$$! keys:
+\nopagebreak
+\begin{demohigh}
+\begin{tblr}{Q[l]Q[r,$]Q[r,$$]}
+\hline
+ Alpha & \frac12 & \frac12 \\
+ Epsilon & \frac34 & \frac34 \\
+ Iota & \frac56 & \frac56 \\
+\hline
+\end{tblr}
+\end{demohigh}
+
\subsection{Column Types}
The \verb!tabularray! package has only one type of primitive column: the \verb!Q! column.
@@ -1236,6 +1300,7 @@ Any new row type must be defined with \verb!\NewRowType! command.
It can have an optional argument when it's defined.
\chapter{Extra Interfaces}
+\label{chap:extra}
\section{Table Specifications}
@@ -1408,7 +1473,9 @@ The following example demonstrates how to define a new table command:
\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
\verb!\NewTableCommand!. But you could use outer specification \verb!expand! to make \verb!tabularray!
-expand every occurrence of a specified macro \underline{once} before splitting the table body:
+expand every occurrence of a specified macro \underline{once} before splitting the table body.
+The macro \underline{can not} be defined with \verb!\NewDocumentCommand! or
+\verb!\NewExpandableDocumentCommand!, and \underline{can not} have optional argument.
\begin{demohigh}
\def\tblrbody{
@@ -1487,14 +1554,12 @@ All tracing messages will be written to the log files.
\chapter{Use Long Tables}
\label{chap:long}
-\mywarning{chapter}
-
\section{A Simple Example}
-In fact, to make a decent long table with header and footer, it is better to separate header/footer as
+To make a decent long table with header and footer, it is better to separate header/footer as
\underline{table head/foot} (which includes caption, footnotes, continuation text)
and \underline{row head/foot} (which includes some rows of the table that should appear in every page).
-By this approach, alternating row colors should work as expected.
+By this approach, alternating row colors work as expected.
\NewTblrTheme{fancy}{
\SetTblrStyle{firsthead}{font=\bfseries}
@@ -1689,25 +1754,25 @@ Alpha & Beta & Gamma \\
Rho & Sigma & Tau \\
\hline
Phi & Chi & Psi \\
-%\hline
-% Alpha & Beta & Gamma \\
-%\hline
-% Epsilon & Zeta & Eta \\
-%\hline
-% Iota & Kappa & Lambda \\
-%\hline
-% Nu & Xi & Omicron \\
-%\hline
-% Rho & Sigma & Tau \\
-%\hline
-% Phi & Chi & Psi \\
+\hline
+ Alpha & Beta & Gamma \\
+\hline
+ Epsilon & Zeta & Eta \\
+\hline
+ Iota & Kappa & Lambda \\
+\hline
+ Nu & Xi & Omicron \\
+\hline
+ Rho & Sigma & Tau \\
+\hline
+ Phi & Chi & Psi \\
\hline
Foot & Foot & Foot \\
\hline
\end{longtblr}
As you can see in the above example, the appearance of long tables of \verb!tabularray! package
-is similar to that of \verb!threeparttable! and \verb!threeparttablex! packages.
+is similar to that of \verb!threeparttablex! packages.
We support table footnotes, but not page footnotes in \verb!tabularray! package.
\newpage
@@ -1782,7 +1847,7 @@ In the above example, We set \verb!rowhead=2! and \verb!rowfoot=1!.
\begin{spectblr}[
caption = {Inner Specifications for Row Heads and Row Foots}
]{}
- Key Nama & Key Description & Initial Value \\
+ Key Name & Key Description & Initial Value \\
\V{rowhead} & number of the first rows of the table appear in every page & \V{0} \\
\V{rowfoot} & number of the last rows of the table appear in every page & \V{0} \\
\end{spectblr}
@@ -1793,7 +1858,7 @@ Their options are outer specifications and should be put in the optional argumen
\begin{spectblr}[
caption = {Outer Specifications for Table Heads and Table Foots}
]{verb}
- Key Nama & Key Description & Initial Value \\
+ Key Name & Key Description & Initial Value \\
\V{headsep} & vertical space between table head and table body & \V{6pt} \\
\V{footsep} & vertical space between table foot and table body & \V{6pt} \\
\V{presep} & vertical space between table head and the above text & \verb!1.5\bigskipamount! \\
@@ -2084,6 +2149,49 @@ TEXT\begin{talltblr}[
The \verb!tabularray! package emulates or fixes some commands in other packages.
To avoid potential conflict, you need to enable them with \verb!\UseTblrLibrary! command.
+\section{Library \texttt{amsmath}}
+
+With \verb!\UseTblrLibrary{amsmath}! in the preamble of the document,
+\verb!tabularray! will load \verb!amsmath! package, and define \verb!+array!, \verb!+matrix!,
+\verb!+bmatrix!, \verb!+Bmatrix!, \verb!+pmatrix!, \verb!+vmatrix!, \verb!+Vmatrix! and \verb!+cases!
+environments. Each of the environments is similar to the environment without \verb!+! prefix in its name,
+but has default \verb!rowsep=2pt! just as \verb!tblr! environment. Every environment
+except \verb!+array! accepts an optional argument, where you can write inner specifications.
+
+\begin{demo}
+$\begin{pmatrix}
+ \dfrac{2}{3} & \dfrac{2}{3} & \dfrac{1}{3} \\
+ \dfrac{2}{3} & -\dfrac{1}{3} & -\dfrac{2}{3} \\
+ \dfrac{1}{3} & -\dfrac{2}{3} & \dfrac{2}{3} \\
+\end{pmatrix}$
+\end{demo}
+
+\begin{demohigh}
+$\begin{+pmatrix}[cells={r},row{2}={purple8}]
+ \dfrac{2}{3} & \dfrac{2}{3} & \dfrac{1}{3} \\
+ \dfrac{2}{3} & -\dfrac{1}{3} & -\dfrac{2}{3} \\
+ \dfrac{1}{3} & -\dfrac{2}{3} & \dfrac{2}{3} \\
+\end{+pmatrix}$
+\end{demohigh}
+
+\begin{demo}
+$f(x)=\begin{cases}
+ 0, & x=1; \\
+ \dfrac{1}{3}, & x=2; \\
+ \dfrac{2}{3}, & x=3; \\
+ 1, & x=4. \\
+\end{cases}$
+\end{demo}
+
+\begin{demohigh}
+$f(x)=\begin{+cases}
+ 0, & x=1; \\
+ \dfrac{1}{3}, & x=2; \\
+ \dfrac{2}{3}, & x=3; \\
+ 1, & x=4. \\
+\end{+cases}$
+\end{demohigh}
+
\section{Library \texttt{booktabs}}
With \verb!\UseTblrLibrary{booktabs}! in the preamble of the document,
@@ -2212,6 +2320,21 @@ and the other half to \verb!abovesep! of current row.
\end{booktabs}
\end{demohigh}
+\section{Library \texttt{counter}}
+
+You need to load \verb!counter! library with \verb!\UseTblrLibrary{counter}!,
+if you want to modify some LaTeX counters inside \verb!tabularray! tables.
+
+\begin{demohigh}
+\newcounter{mycnta}
+\newcommand{\mycnta}{\stepcounter{mycnta}\arabic{mycnta}}
+\begin{tblr}{hlines}
+ \mycnta & \mycnta & \mycnta \\
+ \mycnta & \mycnta & \mycnta \\
+ \mycnta & \mycnta & \mycnta \\
+\end{tblr}
+\end{demohigh}
+
\section{Library \texttt{diagbox}}
When writing \verb!\UseTblrLibrary{diagbox}! in the preamble of the document,
@@ -2297,11 +2420,12 @@ Also you must use \verb!l!, \verb!c! or \verb!r! to set horizontal alignment for
\end{tblr}
\end{demohigh}
-Both \verb!S! and \verb!s! columns are supported. In fact, These two columns are defined as follows:
+Both \verb!S! and \verb!s! columns are supported. In fact, These two columns have been defined as follows:
\begin{codehigh}
-\NewColumnType{S}[1][]{Q[si={##1},c]}
-\NewColumnType{s}[1][]{Q[si={##1},c,cmd=\TblrUnit]}
+\NewColumnType{S}[1][]{Q[si={#1},c]}
+\NewColumnType{s}[1][]{Q[si={#1},c,cmd=\TblrUnit]}
\end{codehigh}
+You don't need to and are not allowed to define them again.
\section{Library \texttt{varwidth}}