diff options
author | Karl Berry <karl@freefriends.org> | 2021-08-01 20:37:16 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2021-08-01 20:37:16 +0000 |
commit | 840ac11675dc87ad8c8ed61a9b95748fdcbaf44e (patch) | |
tree | 47af473d0e437dd020c7c523852b9e22cb9df658 /Master/texmf-dist/doc | |
parent | 9f6f0d1fd20f6010188013cbef1b8a9aa65576df (diff) |
tabularray (1aug21)
git-svn-id: svn://tug.org/texlive/trunk@60140 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc')
-rw-r--r-- | Master/texmf-dist/doc/latex/tabularray/tabularray.pdf | bin | 652813 -> 680990 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/latex/tabularray/tabularray.tex | 956 |
2 files changed, 628 insertions, 328 deletions
diff --git a/Master/texmf-dist/doc/latex/tabularray/tabularray.pdf b/Master/texmf-dist/doc/latex/tabularray/tabularray.pdf Binary files differindex ba8b2838840..c7b3de29caf 100644 --- a/Master/texmf-dist/doc/latex/tabularray/tabularray.pdf +++ b/Master/texmf-dist/doc/latex/tabularray/tabularray.pdf diff --git a/Master/texmf-dist/doc/latex/tabularray/tabularray.tex b/Master/texmf-dist/doc/latex/tabularray/tabularray.tex index 45d486d9950..1e5b4a104e8 100644 --- a/Master/texmf-dist/doc/latex/tabularray/tabularray.tex +++ b/Master/texmf-dist/doc/latex/tabularray/tabularray.tex @@ -6,7 +6,10 @@ \usepackage{codehigh} % https://ctan.org/pkg/codehigh \usepackage{tabularray} \usepackage{array,multirow,amsmath} -\usepackage{chemmacros} +\usepackage{chemmacros,environ} + +\usepackage[firstpage=true]{background} +\backgroundsetup{contents={}} \UseTblrLibrary{booktabs,diagbox,siunitx} @@ -14,7 +17,7 @@ \hypersetup{ colorlinks=true, urlcolor=blue3, - linkcolor=red3, + linkcolor=blue3, } \usepackage{tcolorbox} @@ -26,13 +29,22 @@ \newcommand*{\K}[1]{\texttt{#1}} \newcommand*{\V}[1]{\texttt{#1}} +\newcommand*{\None}{$\times$} + +\NewTblrEnviron{newtblr} +\SetTblrOuter[newtblr]{long} +\SetTblrInner[newtblr]{ + hlines = {white}, column{1,2} = {co=1}, colsep = 5pt, + row{odd} = {brown8}, row{even} = {gray8}, + row{1} = {fg=white, bg=purple2, font=\bfseries\sffamily}, +} \NewTblrEnviron{spectblr} \SetTblrOuter[spectblr]{long} \SetTblrInner[spectblr]{ - hlines = {white}, - row{odd}={brown8},row{even}={gray8},row{1}={fg=white,bg=purple2,font=\bfseries\sffamily}, - column{2} = {co=1}, + hlines = {white}, column{2} = {co=1}, colsep = 5pt, + row{odd} = {brown8}, row{even} = {gray8}, + row{1} = {fg=white, bg=purple2, font=\bfseries\sffamily}, rowhead = 1, } @@ -47,12 +59,10 @@ \renewcommand*{\thefootnote}{*} -\newcommand*{\myversion}{2021L} -\newcommand*{\mydate}{Version \myversion\ (\the\year-\mylpad\month-\mylpad\day)\\\myrepo} -\newcommand*{\myrepo}{\url{https://github.com/lvjr/tabularray}} +\newcommand*{\myversion}{2021M} \newcommand*{\mylpad}[1]{\ifnum#1<10 0\the#1\else\the#1\fi} -\colorlet{highback}{\ifodd\month azure9\else blue9\fi} +\colorlet{highback}{azure9} \CodeHigh{language=latex/table,style/main=highback,style/code=highback} \NewCodeHighEnv{code}{style/main=gray9,style/code=gray9} \NewCodeHighEnv{demo}{style/main=gray9,style/code=gray9,demo} @@ -61,10 +71,81 @@ \begin{document} -\title{\sffamily\color{red3}Tabularray: Typeset Tabulars and Arrays with \LaTeX3} -\author{Jianrui Lyu (tolvjr@163.com)} -\date{\mydate} -\maketitle +\savegeometry{standard} +\newgeometry{left=0pt,right=0pt} + +\begin{titlepage} + +\backgroundsetup{ + scale = 1, + angle = 0, + opacity = 1, + %color = black, + contents = { + \begin{tblr}{ + width = \paperwidth, columns = {1}, rows= {4em}, + cell{odd}{odd} = {gray9}, cell{even}{even} = {gray9}, + } + & & & & & & & & & & & & & & \\ + & & & & & & & & & & & & & & \\ + & & & & & & & & & & & & & & \\ + & & & & & & & & & & & & & & \\ + & & & & & & & & & & & & & & \\ + & & & & & & & & & & & & & & \\ + & & & & & & & & & & & & & & \\ + & & & & & & & & & & & & & & \\ + & & & & & & & & & & & & & & \\ + & & & & & & & & & & & & & & \\ + & & & & & & & & & & & & & & \\ + & & & & & & & & & & & & & & \\ + & & & & & & & & & & & & & & \\ + & & & & & & & & & & & & & & \\ + & & & & & & & & & & & & & & \\ + & & & & & & & & & & & & & & \\ + & & & & & & & & & & & & & & \\ + & & & & & & & & & & & & & & \\ + & & & & & & & & & & & & & & \\ + & & & & & & & & & & & & & & \\ + \end{tblr} + } +} + +\noindent +\begin{tblr}{ + colspec = {lX}, colsep = 12mm, hlines = {2pt, white}, + row{odd} = {azure8}, row{even} = {gray8}, + row{1} = {6em,azure2,fg=white,font=\LARGE\bfseries\sffamily}, + row{2-Z} = {3em,font=\Large}, +} + Tabularray & Typeset Tabulars and Arrays with \LaTeX3 \\ + Author & Jianrui Lyu (tolvjr@163.com) \\ + Version & \myversion\ (\the\year-\mylpad\month-\mylpad\day) \\ + Code & \url{https://github.com/lvjr/tabularray} \\ + Code & \url{https://bitbucket.org/lvjr/tabularray} \\ + Issue & \url{https://github.com/lvjr/tabularray/issues} \\ + Forum & \url{https://github.com/lvjr/tabularray/discussions} \\ +\end{tblr} + +\begin{codehigh}[boxsep=6mm] +\begin{tblr}{ + colspec = {lX}, colsep = 12mm, hlines = {2pt, white}, + row{odd} = {azure8}, row{even} = {gray8}, + row{1} = {6em,azure2,fg=white,font=\LARGE\bfseries\sffamily}, + row{2-Z} = {3em,font=\Large}, +} + Tabularray & Typeset Tabulars and Arrays with \LaTeX3 \\ + Author & Jianrui Lyu (tolvjr@163.com) \\ + Version & \myversion\ (\the\year-\mylpad\month-\mylpad\day) \\ + Code & \url{https://github.com/lvjr/tabularray} \\ + Code & \url{https://bitbucket.org/lvjr/tabularray} \\ + Issue & \url{https://github.com/lvjr/tabularray/issues} \\ + Forum & \url{https://github.com/lvjr/tabularray/discussions} \\ +\end{tblr} +\end{codehigh} + +\end{titlepage} + +\loadgeometry{standard} \tableofcontents @@ -177,7 +258,7 @@ Note that you can use more meaningful \verb!t! instead of \verb!p! for top basel For some users who are familiar with word processors, these \verb!t! and \verb!b! columns are counter-intuitive. In \verb!tabularray! package, there are another two column types \verb!h! and \verb!f!, -which will align cell text at row head and row foot, respectively: +which will align cell text at the head and the foot, respectively: \begin{demohigh} \begin{tblr}{Q[h,4em]Q[t,4em]Q[m,4em]Q[b,4em]Q[f,4em]} @@ -191,9 +272,8 @@ which will align cell text at row head and row foot, respectively: \section{Multirow Cells} -The above \verb!h! and \verb!f! columns are necessary for multirow cells. -In \verb!tabularray!, the \verb!t! and \verb!b! in the optional argument of \verb!\multirow! commands -will be treated as \verb!h! and \verb!f!, respectively: +The above \verb!h! and \verb!f! alignments are necessary +when we write multirow cells with \verb!\SetCell! command in \verb!tabularray!. \begin{demo} \begin{tabular}{|l|l|l|l|} @@ -210,8 +290,8 @@ will be treated as \verb!h! and \verb!f!, respectively: \begin{demohigh} \begin{tblr}{|l|l|l|l|} \hline - \multirow[t]{4}{1.5cm}{Multirow Cell One} & Alpha & - \multirow[b]{4}{1.5cm}{Multirow Cell Two} & Alpha \\ + \SetCell[r=4]{h,1.5cm} Multirow Cell One & Alpha & + \SetCell[r=4]{f,1.5cm} Multirow Cell Two & Alpha \\ & Beta & & Beta \\ & Gamma & & Gamma \\ & Delta & & Delta \\ @@ -222,7 +302,7 @@ will be treated as \verb!h! and \verb!f!, respectively: Note that you don't need to load \verb!multirow! package first, since \verb!tabularray! doesn't depend on it. Furthermore, \verb!tabularray! will always typeset decent multirow cells. -First, it will set correct vertical \verb!c! alignment, +First, it will set correct vertical middle alignment, even though some rows have large height: \begin{demo} @@ -239,7 +319,7 @@ even though some rows have large height: \begin{demohigh} \begin{tblr}{|l|m{4em}|} \hline - \multirow[c]{4}{1.5cm}{Multirow} & Alpha \\ + \SetCell[r=4]{m,1.5cm} Multirow & Alpha \\ & Beta \\ & Gamma \\ & Delta Delta Delta \\ @@ -263,7 +343,7 @@ therefore it always avoids vertical overflow: \begin{demohigh} \begin{tblr}{|l|m{4em}|} \hline - \multirow[c]{2}{1cm}{Line \\ Line \\ Line \\ Line} & Alpha \\ + \SetCell[r=2]{m,1cm} {Line \\ Line \\ Line \\ Line} & Alpha \\ \cline{2} & Beta \\ \hline @@ -477,190 +557,36 @@ Hlines and vlines can also have colors: \end{tblr} \end{demohigh} -\section{New Table Commands} - -All commands which change the specifications of tables \textcolor{red3}{must} be defined with \verb!\NewTableCommand!. -The following example demonstrates how to define similar rules as in \verb!booktabs! package: +\chapter{Basic Interfaces} -\begin{codehigh} -\NewTableCommand\toprule{\hline[0.08em]} -\NewTableCommand\midrule{\hline[0.05em]} -\NewTableCommand\bottomrule{\hline[0.08em]} -\begin{tblr}{llll} -\toprule - Alpha & Beta & Gamma & Delta \\ -\midrule - Epsilon & Zeta & Eta & Theta \\ - Iota & Kappa & Lambda & Mu \\ - Nu & Xi & Omicron & Pi \\ -\bottomrule -\end{tblr} -\end{codehigh} +\section{Old and New Interfaces} -\chapter{The Old Interfaces} +With \verb!tabularray! package, you can change the styles of tables via old interfaces or new interfaces. -With tabularray package, you can still use improved table commands to change the styles of tables. +The old interfaces consist of some table commands inside the table contents. Same as \verb!tabular! and \verb!array! environments, all table commands \textcolor{red3}{must} be put at the beginning ot the cell text. Also, new table commands \textcolor{red3}{must} be defined with \verb!\NewTableCommand!. -\section{Hline Commands} - -The \verb!\hline! command has an optional argument which accepts key-value options. -The available keys are described in Table \ref{key:hvline}. - -\begin{demohigh} -\begin{tblr}{llll} -\hline - Alpha & Beta & Gamma & Delta \\ -\hline[dashed] - Epsilon & Zeta & Eta & Theta \\ -\hline[dotted] - Iota & Kappa & Lambda & Mu \\ -\hline[2pt,blue5] -\end{tblr} -\end{demohigh} - -The \verb!\cline! command also has an optional argument which is the same as \verb!\hline!. - -\begin{demohigh} -\begin{tblr}{llll} -\cline{1-4} - Alpha & Beta & Gamma & Delta \\ -\cline[dashed]{1,3} - Epsilon & Zeta & Eta & Theta \\ -\cline[dashed]{2,4} - Iota & Kappa & Lambda & Mu \\ -\cline[2pt,blue5]{-} -\end{tblr} -\end{demohigh} - -You can use child selectors in the mandatory argument of \verb!\cline!. - -\begin{demohigh} -\begin{tblr}{llll} -\cline{1-4} - Alpha & Beta & Gamma & Delta \\ -\cline[dashed]{odd} - Epsilon & Zeta & Eta & Theta \\ -\cline[dashed]{even} - Iota & Kappa & Lambda & Mu \\ -\cline[2pt,blue5]{-} -\end{tblr} -\end{demohigh} - -\section{Cell Commands} - -The \verb!\SetCell! command has a mandatory argument for setting the styles of current cell. -The available keys are described in Table \ref{key:cell}. - -\begin{demohigh} -\begin{tblr}{llll} -\hline[1pt] - Alpha & \SetCell{bg=teal2,fg=white} Beta & Gamma & Delta \\ -\hline - Epsilon & Zeta & \SetCell{r,font=\scshape} Eta & Theta \\ -\hline - Iota & Kappa & Lambda & Mu \\ -\hline[1pt] -\end{tblr} -\end{demohigh} - -The \verb!\SetCell! command also has an optional argument for setting the multispan of current cell. -The available keys are described in Table \ref{key:cellspan}. - -\begin{demohigh} -\begin{tblr}{|X|X|X|X|X|X|} -\hline - Alpha & Beta & Gamma & Delta & Epsilon & Zeta \\ -\hline - \SetCell[c=2]{c} Eta & 2-2 - & \SetCell[c=2]{c} Iota & 2-4 - & \SetCell[c=2]{c} Lambda & 2-6 \\ -\hline - \SetCell[c=3]{l} Nu & 3-2 & 3-3 - & \SetCell[c=3]{l} Pi & 3-5 & 3-6 \\ -\hline - \SetCell[c=6]{r} Tau & 4-2 & 4-3 & 4-4 & 4-5 & 4-6 \\ -\hline -\end{tblr} -\end{demohigh} - -\section{Row Commands} - -The \verb!\SetRow! command has a mandatory argument for setting the styles of current row. -The available keys are described in Table \ref{key:row}. - -\begin{demohigh} -\begin{tblr}{llll} -\hline[1pt] - \SetRow{azure8} Alpha & Beta & Gamma & Delta \\ -\hline - \SetRow{blue8,c} Epsilon & Zeta & Eta & Theta \\ -\hline - \SetRow{violet8} Iota & Kappa & Lambda & Mu \\ -\hline[1pt] -\end{tblr} -\end{demohigh} - -\section{Column Types} - -The \verb!tabularray! package has only one type of primitive column: the \verb!Q! column. -Other types of columns are defined as \verb!Q! columns with some keys. - -\begin{codehigh} -\NewColumnType{l}{Q[l]} -\NewColumnType{c}{Q[c]} -\NewColumnType{r}{Q[r]} -\NewColumnType{t}[1]{Q[t,wd=#1]} -\NewColumnType{m}[1]{Q[m,wd=#1]} -\NewColumnType{b}[1]{Q[b,wd=#1]} -\NewColumnType{h}[1]{Q[h,wd=#1]} -\NewColumnType{f}[1]{Q[f,wd=#1]} -\NewColumnType{X}[1][]{Q[co=1,#1]} -\end{codehigh} - -\begin{demohigh} -\begin{tblr}{|t{15mm}|m{15mm}|b{20mm}|} - Alpha & Beta & {Gamma\\Gamma} \\ - Epsilon & Zeta & {Eta\\Eta} \\ - Iota & Kappa & {Lambda\\Lambda} \\ -\end{tblr} -\end{demohigh} - -Any new column type must be defined with \verb!\NewColumnType! command. -It can have an optional argument when it's defined. - -\section{Row Types} - -The \verb!tabularray! package has only one type of primitive row: the \verb!Q! row. -Other types of rows are defined as \verb!Q! rows with some keys. - -\begin{codehigh} -\NewRowType{l}{Q[l]} -\NewRowType{c}{Q[c]} -\NewRowType{r}{Q[r]} -\NewRowType{t}[1]{Q[t,ht=#1]} -\NewRowType{m}[1]{Q[m,ht=#1]} -\NewRowType{b}[1]{Q[b,ht=#1]} -\NewRowType{h}[1]{Q[h,ht=#1]} -\NewRowType{f}[1]{Q[f,ht=#1]} -\end{codehigh} - -\begin{demohigh} -\begin{tblr}{rowspec={|t{12mm}|m{10mm}|b{10mm}|}} - Alpha & Beta & {Gamma\\Gamma} \\ - Epsilon & Zeta & {Eta\\Eta} \\ - Iota & Kappa & {Lambda\\Lambda} \\ -\end{tblr} -\end{demohigh} - -Any new row type must be defined with \verb!\NewRowType! command. -It can have an optional argument when it's defined. - -\chapter{The New Interfaces} - -With \verb!tabularray! package, you can separate style and content totally in tables. +The new interfaces consist of some options inside the mandatory argument, +hence totally separating the styles and the contents of tables. + +\begin{newtblr}[ + caption = {Old Interfaces and New Interfaces}, + label = {key:interface}, +]{verb} + Old Interfaces & New Interfaces \\ + \verb!\SetHlines! & \K{hlines} \\ + \verb!\SetHline!, \verb!\hline!, \verb!\cline! & \K{hline}, \K{rowspec} \\ + \verb!\SetVlines! & \K{vlines} \\ + \verb!\SetVline!, \verb!\vline!, \verb!\rline! & \K{vline}, \K{colspec} \\ + \verb!\SetCells! & \K{cells} \\ + \verb!\SetCell! & \K{cell} \\ + \verb!\SetRows! & \K{rows} \\ + \verb!\SetRow! & \K{row}, \K{rowspec} \\ + \verb!\SetColumns! & \K{columns} \\ + \verb!\SetColumn! & \K{column}, \K{colspec} \\ +\end{newtblr} \section{Hlines and Vlines} @@ -673,11 +599,13 @@ All available keys for hlines and vlines are described in Table \ref{key:hvline} ]{} Key & Description and Values & Initial Value \\ \underline{\K{dash}} & dash style: \V{solid}, \V{dashed} or \V{dotted} & \V{solid} \\ - \K{text} & replace hline/vline with text (like \V{!} specifier in \K{colspec}) & None \\ - \underline{\K{wd}} & rule width dimension & None \\ - \underline{\K{fg}} & rule color name & None \\ + \K{text} & replace hline/vline with text (like \V{!} specifier in \K{colspec}) & \None \\ + \underline{\K{wd}} & rule width dimension & \None \\ + \underline{\K{fg}} & rule color name & \None \\ \end{spectblr} +\subsection{Hlines and Vlines in New Interfaces} + Options \verb!hlines! and \verb!vlines! are for setting all hlines and vlines, respectively. With empty value, all hlines/vlines will be solid. @@ -686,9 +614,6 @@ With empty value, all hlines/vlines will be 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} @@ -696,15 +621,11 @@ With values inside one pair of braces, all hlines/vlines will be styled. \begin{demohigh} \begin{tblr}{ - hlines = {1pt,solid}, - vlines = {red3,dashed}, + hlines = {1pt,solid}, vlines = {red3,dashed}, } 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} @@ -746,19 +667,16 @@ Another pair of braces before will draw more hlines/vlines (in which \verb!-! st \begin{demohigh} \begin{tblr}{ - hlines = {1}{-}{dashed}, - hlines = {2}{-}{solid}, + hlines = {1}{-}{dashed}, hlines = {2}{-}{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} Options \verb!hline{i}! and \verb!vline{j}! are for setting some hlines and vlines, respectively. +Their values are the same as options \verb!hliness! and \verb!vlines!: \begin{demohigh} \begin{tblr}{ @@ -775,7 +693,25 @@ Options \verb!hline{i}! and \verb!vline{j}! are for setting some hlines and vlin \end{tblr} \end{demohigh} -At last we show the usage of \verb!text! key by the following example% +You can use \verb!X!, \verb!Y!, \verb!Z! to denote the last three childs, respectively. +It is especially useful when you are writing long tables: + +\begin{demohigh} +\begin{tblr}{ + hline{1,Z} = {2pt}, + hline{2,Y} = {1pt}, + hline{3-X} = {dashed}, +} + 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} + +Now we show the usage of \verb!text! key by the following example% \footnote{Code from \url{https://tex.stackexchange.com/questions/603023/tabularray-and-tabularx-column-separator}.}: \begin{demohigh} @@ -795,10 +731,89 @@ At last we show the usage of \verb!text! key by the following example% You need to load \verb!chemmacros! package for the \verb!\ch! command. +\subsection{Hlines and Vlines in Old Interfaces} + +The \verb!\hline! command has an optional argument which accepts key-value options. +The available keys are described in Table \ref{key:hvline}. + +\begin{demohigh} +\begin{tblr}{llll} +\hline + Alpha & Beta & Gamma & Delta \\ +\hline[dashed] + Epsilon & Zeta & Eta & Theta \\ +\hline[dotted] + Iota & Kappa & Lambda & Mu \\ +\hline[2pt,blue5] +\end{tblr} +\end{demohigh} + +The \verb!\cline! command also has an optional argument which is the same as \verb!\hline!. + +\begin{demohigh} +\begin{tblr}{llll} +\cline{1-4} + Alpha & Beta & Gamma & Delta \\ +\cline[dashed]{1,3} + Epsilon & Zeta & Eta & Theta \\ +\cline[dashed]{2,4} + Iota & Kappa & Lambda & Mu \\ +\cline[2pt,blue5]{-} +\end{tblr} +\end{demohigh} + +You can use child selectors in the mandatory argument of \verb!\cline!. + +\begin{demohigh} +\begin{tblr}{llll} +\cline{1-4} + Alpha & Beta & Gamma & Delta \\ +\cline[dashed]{odd} + Epsilon & Zeta & Eta & Theta \\ +\cline[dashed]{even} + Iota & Kappa & Lambda & Mu \\ +\cline[2pt,blue5]{-} +\end{tblr} +\end{demohigh} + +Commands \verb!\SetHline! combines the usages of \verb!\hline! and \verb!\cline!: + +\begin{demohigh} +\begin{tblr}{llll} +\SetHline{1-3}{blue5,1pt} + Alpha & Beta & Gamma & Delta \\ + Epsilon & Zeta & Eta & Theta \\ + Iota & Kappa & Lambda & Mu \\ +\SetHline{2-4}{teal5,1pt} +\end{tblr} +\end{demohigh} + +\begin{demohigh} +\begin{tblr}{llll} +\SetHline[1]{1-3}{blue5,1pt} +\SetHline[2]{1-3}{azure5,1pt} + Alpha & Beta & Gamma & Delta \\ + Epsilon & Zeta & Eta & Theta \\ + Iota & Kappa & Lambda & Mu \\ +\SetHline[1]{2-4}{teal5,1pt} +\SetHline[2]{2-4}{green5,1pt} +\end{tblr} +\end{demohigh} + +In fact, table command \verb!\SetHline[<index>]{<columns>}{<styles>}! at the beginning of row \verb!i! +is the same as table option \verb!hline{i}={<index>}{<columns>}{<styles>}!. + +Also, table command \verb!\SetHlines[<index>]{<columns>}{<styles>}! at the beginning of some row +is the same as table option \verb!hlines={<index>}{<columns>}{<styles>}!. + +The usages of table commands \verb!\vline!, \verb!\rline!, \verb!\SetVline!, \verb!\SetVlines! +are similar to those of \verb!\hline!, \verb!\cline!, \verb!\SetHline!, \verb!\SetHlines!, respectively. +But normally you don't need to use them. + \section{Cells and Spancells} All available keys for cells are described in Table \ref{key:cell} and Table \ref{key:cellspan}. -\nopagebreak + \begin{spectblr}[ caption = {Keys for the Content of Cells}, label = {key:cell}, @@ -812,13 +827,13 @@ All available keys for cells are described in Table \ref{key:cell} and Table \re & vertical alignment: \V{t} (top), \V{m} (middle), \V{b} (bottom), \V{h} (head) or \V{f} (foot) & \V{t} \\ - \underline{\K{wd}} & width dimension & None \\ - \underline{\K{bg}} & background color name & None \\ - \K{fg} & foreground color name & None \\ - \K{font} & font commands & 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 \\ + \underline{\K{wd}} & width dimension & \None \\ + \underline{\K{bg}} & background color name & \None \\ + \K{fg} & foreground color name & \None \\ + \K{font} & font commands & \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}[ @@ -830,6 +845,8 @@ All available keys for cells are described in Table \ref{key:cell} and Table \re \K{c} & number of columns the cell spans & 1 \\ \end{spectblr} +\subsection{Cells and Spancells in New Interfaces} + Option \verb!cells! is for setting all cells. \nopagebreak \begin{demohigh} @@ -862,6 +879,62 @@ Option \verb!cell{i}{j}! is for setting some cells. \end{tblr} \end{demohigh} +\subsection{Cells and Spancells in Old Interfaces} + +The \verb!\SetCell! command has a mandatory argument for setting the styles of current cell. +The available keys are described in Table \ref{key:cell}. + +\begin{demohigh} +\begin{tblr}{llll} +\hline[1pt] + Alpha & \SetCell{bg=teal2,fg=white} Beta & Gamma \\ +\hline + Epsilon & Zeta & \SetCell{r,font=\scshape} Eta \\ +\hline + Iota & Kappa & Lambda \\ +\hline[1pt] +\end{tblr} +\end{demohigh} + +The \verb!\SetCell! command also has an optional argument for setting the multispan of current cell. +The available keys are described in Table \ref{key:cellspan}. + +\begin{demohigh} +\begin{tblr}{|X|X|X|X|X|X|} +\hline + Alpha & Beta & Gamma & Delta & Epsilon & Zeta \\ +\hline + \SetCell[c=2]{c} Eta & 2-2 + & \SetCell[c=2]{c} Iota & 2-4 + & \SetCell[c=2]{c} Lambda & 2-6 \\ +\hline + \SetCell[c=3]{c} Nu & 3-2 & 3-3 + & \SetCell[c=3]{c} Pi & 3-5 & 3-6 \\ +\hline + \SetCell[c=6]{c} Tau & 4-2 & 4-3 & 4-4 & 4-5 & 4-6 \\ +\hline +\end{tblr} +\end{demohigh} + +\begin{demohigh} +\begin{tblr}{|X|X|X|X|X|X|} +\hline + Alpha & Beta & Gamma & Delta & Epsilon & Zeta \\ +\hline + \SetCell[r=2]{m} Eta + & Theta & Iota & Kappa & Lambda & \SetCell[r=2]{m} Mu \\ +\hline + Nu & Xi & Omicron & Pi & Rho & Sigma \\ +\hline +\end{tblr} +\end{demohigh} + +In fact, table command \verb!\SetCell[<span>]{<styles>}! at the beginning of cell at row \verb!i! +and column \verb!j! is the same as table option \verb!cell{i}{j}={<span>}{<styles>}!. + +Also, table command \verb!\SetCells[<span>]{<styles>}! at the beginning of some cell +is the same as table option \verb!cells={<span>}{<styles>}!. + \section{Rows and Columns} All available keys for rows and columns are described in Table \ref{key:row} and Table \ref{key:column}. @@ -879,19 +952,19 @@ All available keys for rows and columns are described in Table \ref{key:row} and & vertical alignment: \V{t} (top), \V{m} (middle), \V{b} (bottom), \V{h} (head) or \V{f} (foot) & \V{t} \\ - \underline{\K{ht}} & height dimension & None \\ - \underline{\K{bg}} & background color name & None \\ - \K{fg} & foreground color name & None \\ - \K{font} & font commands & None \\ + \underline{\K{ht}} & height dimension & \None \\ + \underline{\K{bg}} & background color name & \None \\ + \K{fg} & foreground color name & \None \\ + \K{font} & font commands & \None \\ \K{abovesep} & set vertical space above the row & \V{2pt} \\ - \K{abovesep+} & increase vertical space above the row & None \\ + \K{abovesep+} & increase vertical space above the row & \None \\ \K{belowsep} & set vertical space below the row & \V{2pt} \\ - \K{belowsep+} & increase vertical space below the row & None \\ + \K{belowsep+} & increase vertical space below the row & \None \\ \K{rowsep} & set vertical space above and below the row & \V{2pt} \\ - \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 \\ + \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}[ @@ -907,30 +980,30 @@ All available keys for rows and columns are described in Table \ref{key:row} and & vertical alignment: \V{t} (top), \V{m} (middle), \V{b} (bottom), \V{h} (head) or \V{f} (foot) & \V{t} \\ - \underline{\K{wd}} & width dimension & None \\ - \underline{\K{co}} & coefficient for the extendable column (\V{X} column) & None \\ - \underline{\K{bg}} & background color name & None \\ - \K{fg} & foreground color name & None \\ - \K{font} & font commands & None \\ + \underline{\K{wd}} & width dimension & \None \\ + \underline{\K{co}} & coefficient for the extendable column (\V{X} column) & \None \\ + \underline{\K{bg}} & background color name & \None \\ + \K{fg} & foreground color name & \None \\ + \K{font} & font commands & \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{leftsep+} & increase horizontal space to the left of the column & \None \\ \K{rightsep} & set horizontal space to the right of the column & \V{6pt} \\ - \K{rightsep+} & increase horizontal space to the right of the column & None \\ + \K{rightsep+} & increase horizontal space to the right of the column & \None \\ \K{colsep} & set horizontal space to both sides of the column & \V{6pt} \\ - \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 \\ + \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} + Options \verb!rows! and \verb!columns! are for setting all rows and columns, respectively. \nopagebreak \begin{demohigh} \begin{tblr}{ - hlines, - vlines, - rows = {7mm}, - columns = {15mm,c}, + hlines, vlines, + rows = {7mm}, columns = {15mm,c}, } Alpha & Beta & Gamma & Delta \\ Epsilon & Zeta & Eta & Theta \\ @@ -967,17 +1040,16 @@ The following example demonstrates the usages of \verb!bg!, \verb!fg! and \verb! Delta & Epsilon & Zeta \\ Eta & Theta & Iota \\ Kappa & Lambda & Mu \\ - Nu Xi Omikron & Pi Rho Sigma & Tau Upsilon Phi \\ + Nu Xi Omicron & Pi Rho Sigma & Tau Upsilon Phi \\ \end{tblr} \end{demohigh} The following example demonstrates the usages of \verb!abovesep!, \verb!belowsep!, \verb!leftsep!, \verb!rightsep! keys. -\nopagebreak +%\nopagebreak \begin{demohigh} \begin{tblr}{ - hlines, - vlines, + hlines, vlines, rows = {abovesep=1pt,belowsep=5pt}, columns = {leftsep=1pt,rightsep=5pt}, } @@ -999,7 +1071,109 @@ The following example shows that we can replace \verb!\\[dimen]! with \verb!belo \end{tblr} \end{demohigh} -\section{The Whole Table} +\subsection{Rows and Columns in Old Interfaces} + +The \verb!\SetRow! command has a mandatory argument for setting the styles of current row. +The available keys are described in Table \ref{key:row}. + +\begin{demohigh} +\begin{tblr}{llll} +\hline[1pt] + \SetRow{azure8} Alpha & Beta & Gamma & Delta \\ +\hline + \SetRow{blue8,c} Epsilon & Zeta & Eta & Theta \\ +\hline + \SetRow{violet8} Iota & Kappa & Lambda & Mu \\ +\hline[1pt] +\end{tblr} +\end{demohigh} + +In fact, table command \verb!\SetRow{<styles>}! at the beginning of row \verb!i! +is the same as table option \verb!row{i}={<styles>}!. + +Also, table command \verb!\SetRows{<styles>}! at the beginning of some row +is the same as table option \verb!rows={<styles>}!. + +The usages of table commands \verb!\SetColumn! and \verb!\SetColumns! +are similar to those of \verb!\SetRow! and \verb!\SetRows!, respectively. +But normally you don't need to use them. + +\section{Colspec and Rowspec} + +Options \verb!colspec!/\verb!rowspec! are for setting column/row specifications +with column/row type specifiers. + +\subsection{Colspec and Width} + +Option \verb!width! are for setting the width of the table with extendable columns. +The following example demonstrates the usage of \verb!width! option. +\nopagebreak +\begin{demohigh} +\begin{tblr}{width=0.8\textwidth, colspec={|l|X[2]|X[3]|X[-1]|}} + Alpha & Beta & Gamma & Delta \\ + Epsilon & Zeta & Eta & Theta \\ + Iota & Kappa & Lambda & Mu \\ +\end{tblr} +\end{demohigh} + +\subsection{Column Types} + +The \verb!tabularray! package has only one type of primitive column: the \verb!Q! column. +Other types of columns are defined as \verb!Q! columns with some keys. + +\begin{codehigh} +\NewColumnType{l}{Q[l]} +\NewColumnType{c}{Q[c]} +\NewColumnType{r}{Q[r]} +\NewColumnType{t}[1]{Q[t,wd=#1]} +\NewColumnType{m}[1]{Q[m,wd=#1]} +\NewColumnType{b}[1]{Q[b,wd=#1]} +\NewColumnType{h}[1]{Q[h,wd=#1]} +\NewColumnType{f}[1]{Q[f,wd=#1]} +\NewColumnType{X}[1][]{Q[co=1,#1]} +\end{codehigh} + +\begin{demohigh} +\begin{tblr}{|t{15mm}|m{15mm}|b{20mm}|} + Alpha & Beta & {Gamma\\Gamma} \\ + Epsilon & Zeta & {Eta\\Eta} \\ + Iota & Kappa & {Lambda\\Lambda} \\ +\end{tblr} +\end{demohigh} + +Any new column type must be defined with \verb!\NewColumnType! command. +It can have an optional argument when it's defined. + +\subsection{Row Types} + +The \verb!tabularray! package has only one type of primitive row: the \verb!Q! row. +Other types of rows are defined as \verb!Q! rows with some keys. + +\begin{codehigh} +\NewRowType{l}{Q[l]} +\NewRowType{c}{Q[c]} +\NewRowType{r}{Q[r]} +\NewRowType{t}[1]{Q[t,ht=#1]} +\NewRowType{m}[1]{Q[m,ht=#1]} +\NewRowType{b}[1]{Q[b,ht=#1]} +\NewRowType{h}[1]{Q[h,ht=#1]} +\NewRowType{f}[1]{Q[f,ht=#1]} +\end{codehigh} + +\begin{demohigh} +\begin{tblr}{rowspec={|t{12mm}|m{10mm}|b{10mm}|}} + Alpha & Beta & {Gamma\\Gamma} \\ + Epsilon & Zeta & {Eta\\Eta} \\ + Iota & Kappa & {Lambda\\Lambda} \\ +\end{tblr} +\end{demohigh} + +Any new row type must be defined with \verb!\NewRowType! command. +It can have an optional argument when it's defined. + +\chapter{Extra Interfaces} + +\section{Table Specifications} All available keys for the whole table are described in Table \ref{key:table}. @@ -1008,9 +1182,6 @@ All available keys for the whole table are described in Table \ref{key:table}. label = {key:table}, ]{} Key & Description and Values & Initial Value \\ - \K{rowspec} & set row specifications with row type specifiers & None \\ - \K{colspec} & set column specifications with column type specifiers & None \\ - \K{width} & width of the table with extendable columns & None \\ \K{rulesep} & space between two hlines or vlines & \V{2pt} \\ \K{stretch} & stretch ratio for struts added to cell text & \V{1} \\ \K{abovesep} & set vertical space above every row & \V{2pt} \\ @@ -1023,16 +1194,6 @@ All available keys for the whole table are described in Table \ref{key:table}. \K{vspan} & vertical span algorithm: \V{default} or \V{even} & \V{default} \\ \end{spectblr} -The following example demonstrates the usage of \verb!width! key. -\nopagebreak -\begin{demohigh} -\begin{tblr}{width=0.8\textwidth, colspec={|l|X[2]|X[3]|X[-1]|}} - Alpha & Beta & Gamma & Delta \\ - Epsilon & Zeta & Eta & Theta \\ - Iota & Kappa & Lambda & Mu \\ -\end{tblr} -\end{demohigh} - The following example shows that we can replace \verb!\doublerulesep! parameter with \verb!rulesep! key. \nopagebreak \begin{demohigh} @@ -1158,6 +1319,80 @@ Text \begin{mytblr}{cccc} \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 Table 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: + +\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} +\end{demohigh} + +\section{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 +\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: + +\begin{demohigh} +\def\tblrbody{ + \hline + 20 & 30 & 40 \\ + 50 & 60 & 70 \\ + \hline +} +\begin{tblr}[expand=\tblrbody]{ccc} + \hline + AA & BB & CC \\ + \tblrbody + DD & EE & FF \\ + \tblrbody + GG & HH & II \\ + \hline +\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: + +\begin{demohigh} +\NewEnviron{fancytblr}{ + Before Text + \begin{tblr}[expand=\BODY]{hlines} + \BODY + \end{tblr} + After Text +} +\begin{fancytblr} + One & Two & Three \\ + Four & Five & Six \\ + Seven & Eight & Nine \\ +\end{fancytblr} +\end{demohigh} + +\section{Use Verbatim Commands} + +With inner specification \verb!verb!, you can write \verb!\verb! commands in the cell text: + +\begin{demohigh} +\begin{tblr}{hlines,verb} + 20 & 30 & \verb!\hello{world}!40 \\ + 50 & \verb!\hello!60 & 70 \\ +\end{tblr} +\end{demohigh} + \section{Counters and Lengths} Counters \verb!rownum!, \verb!colnum!, \verb!rowcount!, \verb!colcount! can be used in cell text: @@ -1214,16 +1449,18 @@ By this approach, alternating row colors should work as expected. remark{Source} = {Made up by myself. Made up by myself. Made up by myself.}, ]{ colspec = {XXX}, width = 0.85\linewidth, - row{odd} = {gray9}, row{even} = {brown9}, rowhead = 2, rowfoot = 1, + rowhead = 2, rowfoot = 1, + row{odd} = {gray9}, row{even} = {brown9}, + row{1-2} = {purple7}, row{Z} = {blue7}, } \hline - \SetRow{purple7} Head & Head & Head \\ + Head & Head & Head \\ \hline - \SetRow{purple7} Head & Head & Head \\ + Head & Head & Head \\ \hline Alpha & Beta & Gamma \\ \hline - Epsilon & Zeta\TblrNote{a} & Eta \\ + Epsilon & Zeta\TblrNote{a} & Eta \\ \hline Iota & Kappa\TblrNote{$\dag$} & Lambda \\ \hline @@ -1365,7 +1602,7 @@ Alpha & Beta & Gamma \\ \hline Phi & Chi & Psi \\ \hline - Alpha & Beta & Gamma\footnote{Hello} \\ + Alpha & Beta & Gamma \\ \hline Epsilon & Zeta & Eta \\ \hline @@ -1401,7 +1638,7 @@ Alpha & Beta & Gamma \\ %\hline % Phi & Chi & Psi \\ \hline - \SetRow{blue7} Foot & Foot & Foot \\ + Foot & Foot & Foot \\ \hline \end{longtblr} @@ -1431,16 +1668,18 @@ The source code for the above long table is shown below. It is mainly self-expla remark{Source} = {Made up by myself. Made up by myself. Made up by myself.}, ]{ colspec = {XXX}, width = 0.85\linewidth, - row{odd} = {gray9}, row{even} = {brown9}, rowhead = 2, rowfoot = 1, + rowhead = 2, rowfoot = 1, + row{odd} = {gray9}, row{even} = {brown9}, + row{1-2} = {purple7}, row{Z} = {blue7}, } \hline - \SetRow{purple7} Head & Head & Head \\ + Head & Head & Head \\ \hline - \SetRow{purple7} Head & Head & Head \\ + Head & Head & Head \\ \hline Alpha & Beta & Gamma \\ \hline - Epsilon & Zeta\TblrNote{a} & Eta \\ + Epsilon & Zeta\TblrNote{a} & Eta \\ \hline Iota & Kappa\TblrNote{$\dag$} & Lambda \\ \hline @@ -1464,7 +1703,7 @@ The source code for the above long table is shown below. It is mainly self-expla \hline Phi & Chi & Psi \\ \hline - \SetRow{blue7} Foot & Foot & Foot \\ + Foot & Foot & Foot \\ \hline \end{longtblr} \end{codehigh} @@ -1489,33 +1728,43 @@ 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 \\ \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 & \texttt{1.5\string\bigskipamount} \\ - \V{postsep} & vertical space between table foot and the below text & \texttt{1.5\string\bigskipamount} \\ - \V{theme} & table theme (including settings for templates and styles) & None \\ - \V{caption} & table caption & None \\ - \V{entry} & short table caption to be put in List of Tables & None \\ - \V{label} & table label & None \\ - \V{note\{<name>\}} & table note with \V{<name>} as tag & None \\ - \V{remark\{<name>\}} & table remark with \V{<name>} as tag & None \\ + \V{presep} & vertical space between table head and the above text & \verb!1.5\bigskipamount! \\ + \V{postsep} & vertical space between table foot and the below text & \verb!1.5\bigskipamount! \\ + \V{theme} & table theme (including settings for templates and styles) & \None \\ + \V{caption} & table caption & \None \\ + \V{entry} & short table caption to be put in List of Tables & \None \\ + \V{label} & table label & \None \\ + \V{note\{<name>\}} & table note with \V{<name>} as tag & \None \\ + \V{remark\{<name>\}} & table remark with \V{<name>} as tag & \None \\ \end{spectblr} +If you write \verb!entry=none!, \verb!tabularray! package will not add an entry in List of Tables. +Therefore \verb!caption=text,entry=none! is similar to \verb!\caption[]{text}! in \verb!longtable!. + +If you write \verb!label=none!, \verb!tabularray! package will not step \verb!table! counter, +and set the \verb!caption-tag! and \verb!caption-sep! elements (see below) to empty. +Therefore \verb!caption=text,entry=none,label=none! is similar to \verb!\caption*{text}! +in \verb!longtable!, except for the counter. + \section{Customize Templates} \subsection{Overview of Templates} -The template system for table heads and table foots in \verb!tabularray! is largely inspired by \verb!beamer!, -\verb!caption! and \verb!longtable! packages. You can use \verb!\DefTblrTemplate! command to define and -modify templates, and \verb!\SetTblrTemplate! command to choose default templates. In defining templates, +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, +and use \verb!\SetTblrTemplate! to choose default templates. In defining templates, you can include other templates with \verb!\UseTblrTemplate! and \verb!\ExpTblrTemplate! commands. \begin{spectblr}[ - caption = {Templates for Table Heads and Table Foots} + caption = {Elements for Table Heads and Table Foots}, + label = {tblr:element}, ]{} - Template Name & Template Description \\ + Element Name & Element Description and Default Template \\ \V{contfoot-text}& continuation text in the foot, normally ``Continued on next page'' \\ \V{contfoot} & continuation paragraph in the foot, normally including \V{contfoot-text} template \\ \V{conthead-text}& continuation text in the head, normally ``(Continued)'' \\ @@ -1542,10 +1791,13 @@ you can include other templates with \verb!\UseTblrTemplate! and \verb!\ExpTblrT \V{foot} & setting all of \V{firstfoot}, \V{middlefoot} and \V{lastfoot} \\ \end{spectblr} -A template which only includes short text is called a \underline{sub template}. -Normally there is one \verb!-! in the name of a sub template. -A template which includes one or more paragraphs is called a \underline{main template}. -Normally there isn't any \verb!-! in the name of a main template. +An element which only includes short text is called a \underline{sub element}. +Normally there is one \verb!-! in the name of a sub element. +An element which includes one or more paragraphs is called a \underline{main element}. +Normally there isn't any \verb!-! in the name of a main element. + +For each of the above elements, two templates \verb!normal! and \verb!empty! are always defined. +You can select one of them with \verb!\SetTblrTemplate! command. \subsection{Continuation Templates} @@ -1560,7 +1812,7 @@ Let us have a look at the code for defining templates of continuation text first In the above code, command \verb!\DefTblrTemplate! defines the templates with name \verb!normal!, and then command \verb!\SetTblrTemplate! sets the templates with name \verb!normal! as default. -The \verb!normal! template is always defined and set as default for any template element in \verb!tabularray!. +The \verb!normal! template is always defined and set as default for any element in \verb!tabularray!. Therefore you had better use another name when defining new templates. If you use \verb!default! as template name in \verb!\DefTblrTemplate!, @@ -1574,8 +1826,8 @@ Therefore the above code can be written in another way: You may modify the code to customize continuation text to fit your needs. -The \verb!contfoot! and \verb!conthead! templates normally -include their sub templates with \verb!\UseTblrTemplate! commands. +The templates for \verb!contfoot! and \verb!conthead! normally +include the templates of their sub elements with \verb!\UseTblrTemplate! commands. But you can also handle user settings such as horizontal alignment here. \begin{codehigh} @@ -1688,19 +1940,10 @@ Note that you can define the same template for multiple elements in \verb!\DefTb \section{Change Styles} -You may change the styles of template elements. - -\begin{codehigh} -\SetTblrStyle{firsthead}{font=\bfseries} -\SetTblrStyle{firstfoot}{fg=blue2} -\SetTblrStyle{middlefoot}{\itshape} -\SetTblrStyle{caption-tag}{red2} -\end{codehigh} - All available keys for template elements are described in Table \ref{key:element}. \begin{spectblr}[ - caption = {Keys for the Styles of Template Elements}, + caption = {Keys for the Styles of Elements}, label = {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.} @@ -1713,9 +1956,18 @@ All available keys for template elements are described in Table \ref{key:element \K{hang} & hangindent value \\ \end{spectblr} +You may change the styles of elements with \verb!\SetTblrStyle! command: + +\begin{codehigh} +\SetTblrStyle{firsthead}{font=\bfseries} +\SetTblrStyle{firstfoot}{fg=blue2} +\SetTblrStyle{middlefoot}{\itshape} +\SetTblrStyle{caption-tag}{red2} +\end{codehigh} + When you write \verb!\UseTblrTemplate{element}{default}! in defining a template, -beside including the code of template \verb!element!, the foreground color and font commands -of the template \verb!element! will be set up automatically. +beside including template code of the \verb!element!, the foreground color and font commands +of the \verb!element! will be set up automatically. In contrast, \verb!\ExpTblrTemplate{element}{default}! will only include template code. \section{Define Themes} @@ -1736,14 +1988,39 @@ a theme consists of some template and style settings. For example: After defining the theme \verb!fancy!, you can use it by writing \verb!theme=fancy! in the optional argument of \verb!longtblr! environment. -\chapter{Use Some Libraries} +\section{Control Page Breaks} -\mywarning{chapter} +Just like \verb!longtable! package, inside \verb!longtblr! environment, +you can use \verb!\\*! or \verb!\nopagebreak! to prohibit a page break, +and use \verb!\pagebreak! to force a page break. + +\section{Floatable Tall Tables} + +There is also a \verb!talltblr! environment as an alternative to \verb!threeparttable! environment. +It can not cross multiple pages, but it can be put inside \verb!table! environment. + +\begin{demohigh} +TEXT\begin{talltblr}[ + caption = {Long Long Long Long Tabular}, + entry = {Short Caption}, + label = {tblr:tall}, + note{a} = {It is the first footnote.}, + note{$\dag$} = {It is the second long long long long long long footnote.}, +]{ + colspec = {XXX}, width = 0.5\linewidth, hlines, +} + Alpha & Beta & Gamma \\ + Epsilon & Zeta & Eta\TblrNote{a} \\ + Iota & Kappa & Lambda\TblrNote{$\dag$} \\ +\end{talltblr}TEXT +\end{demohigh} + +\chapter{Use Some Libraries} 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 \V{booktabs}} +\section{Library \texttt{booktabs}} When you write \verb!\UseTblrLibrary{booktabs}!, \verb!tabularray! package will define commands \verb!\toprule!, \verb!\midrule!, @@ -1764,6 +2041,7 @@ When you write \verb!\UseTblrLibrary{booktabs}!, \end{demohigh} At this moment, \verb!trim! options for \verb!\cmidrule! command are not supported. +(As a workaround, you may insert an empty column to separate two \verb!\cmidrule!'s.) But rule colors are possible just like \verb!\hline! and \verb!\cline! commands. \begin{demohigh} @@ -1780,7 +2058,7 @@ But rule colors are possible just like \verb!\hline! and \verb!\cline! commands. \end{tblr} \end{demohigh} -\section{Library \V{diagbox}} +\section{Library \texttt{diagbox}} When writing \verb!\UseTblrLibrary{diagbox}! in the preamble of the document, \verb!tabularray! package loads \verb!diagbox! package, @@ -1815,48 +2093,70 @@ $\begin{tblr}{|c|cc|} \end{tblr}$ \end{demohigh} -\section{Library \V{siunitx}} +\section{Library \texttt{siunitx}} When writing \verb!\UseTblrLibrary{siunitx}! in the preamble of the document, \verb!tabularray! package loads \verb!siunitx! package, -and defines \verb!S! column for \verb!tblr! environment. +and defines \verb!S! column as \verb!Q! column with \verb!si! key. + +\begin{demohigh} +\begin{tblr}{ + hlines, vlines, + colspec={ + S[table-format=3.2] + S[table-format=3.2] + S[table-format=3.2] + } +} + {{{Head}}} & {{{Head}}} & {{{Head}}} \\ + 111 & 111 & 111 \\ + 2.1 & 2.2 & 2.3 \\ + 33.11 & 33.22 & 33.33 \\ +\end{tblr} +\end{demohigh} \begin{demohigh} \begin{tblr}{ hlines, vlines, colspec={ - S[table-format=2.2] - S[table-format=2.2] - S[table-format=2.2] + Q[si={table-format=3.2},c] + Q[si={table-format=3.2},c] + Q[si={table-format=3.2},c] } } {{{Head}}} & {{{Head}}} & {{{Head}}} \\ - 11 & 11 & 11 \\ + 111 & 111 & 111 \\ 2.1 & 2.2 & 2.3 \\ 33.11 & 33.22 & 33.33 \\ \end{tblr} \end{demohigh} Note that you need to use \underline{triple} pairs of braces to guard non-numeric cells. -If you need to apply other specifications for the \verb!S! columns, -you need to move \verb!siunitx! options into \verb!si! keys of the \verb!Q! columns. + +Also you must use \verb!l!, \verb!c! or \verb!r! to set horizontal alignment for non-numeric cells: \begin{demohigh} \begin{tblr}{ - hlines, vlines, + hlines, vlines, columns={6em}, colspec={ - Q[si={table-format=2.2},blue7] - Q[si={table-format=2.2},teal7] - Q[si={table-format=2.2},purple7] + Q[si={table-format=3.2,table-number-alignment=left},l,blue7] + Q[si={table-format=3.2,table-number-alignment=center},c,teal7] + Q[si={table-format=3.2,table-number-alignment=right},r,purple7] } } {{{Head}}} & {{{Head}}} & {{{Head}}} \\ - 11 & 11 & 11 \\ + 111 & 111 & 111 \\ 2.1 & 2.2 & 2.3 \\ 33.11 & 33.22 & 33.33 \\ \end{tblr} \end{demohigh} +Both \verb!S! and \verb!s! columns are supported. In fact, These two columns are defined as follows: +\begin{codehigh} +\NewColumnType{S}[1][]{Q[si={##1},c]} +\NewColumnType{s}[1][]{Q[si={##1},c,cmd=\TblrUnit]} +\end{codehigh} + \chapter{The Source Code} %\CodeHigh{lite} |