summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/tabularray/tabularray.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2023-03-02 03:04:09 +0000
committerNorbert Preining <norbert@preining.info>2023-03-02 03:04:09 +0000
commitfe8af26a7b8f32a0cc1b761e3ffb95ed0867a845 (patch)
tree35bb91961c5021c2b0f6a620d9c732a5567222b9 /macros/latex/contrib/tabularray/tabularray.tex
parent37485ae5d642200a29ffc623bae1150d9e8e7978 (diff)
CTAN sync 202303020304
Diffstat (limited to 'macros/latex/contrib/tabularray/tabularray.tex')
-rw-r--r--macros/latex/contrib/tabularray/tabularray.tex114
1 files changed, 96 insertions, 18 deletions
diff --git a/macros/latex/contrib/tabularray/tabularray.tex b/macros/latex/contrib/tabularray/tabularray.tex
index db993f27d3..3c050a4537 100644
--- a/macros/latex/contrib/tabularray/tabularray.tex
+++ b/macros/latex/contrib/tabularray/tabularray.tex
@@ -1,7 +1,7 @@
% -*- coding: utf-8 -*-
% !TEX program = lualatex
\documentclass[oneside]{book}
-\newcommand*{\myversion}{2022D}
+\newcommand*{\myversion}{2023A}
\newcommand*{\mylpad}[1]{\ifnum#1<10 0\the#1\else\the#1\fi}
\usepackage[a4paper,margin=2.5cm]{geometry}
@@ -729,7 +729,8 @@ 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 children, respectively.
+You can use \verb!U!, \verb!V!, \verb!W!, \verb!X!, \verb!Y!, \verb!Z! to
+denote the last six children, respectively.
It is especially useful when you are writing long tables:
\begin{demohigh}
@@ -1384,7 +1385,7 @@ there are several inner specifications which are described in Table~\ref{key:inn
\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{verb} & you need this key to use verb commands & \None \\
\K{baseline} & set the baseline of the table & \V{m} \\
\end{spectblr}
@@ -1504,14 +1505,17 @@ The following examples show the results from different \verb!vspan! values.
\subsection{Use Verbatim Commands}
-With \verb!verb! key, you can write \verb!\verb! commands in the cell text:
+%With \verb!verb! key, 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}
-\begin{demohigh}
-\begin{tblr}{hlines,verb}
- 20 & 30 & \verb!\hello{world}!40 \\
- 50 & \verb!\hello!60 & 70 \\
-\end{tblr}
-\end{demohigh}
+The inner key \verb!verb! is obsolete from version 2023A, and will be removed in the future.
+Instead you can use more reliable \verb!\fakeverb! command (see Section \ref{sec:fakeverb}).
\subsection{Set Baseline for the Table}
@@ -1599,15 +1603,17 @@ Therefore the following two tables are the same:
\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
-\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.
-The macro \underline{can not} be defined with \verb!\NewDocumentCommand! or
-\verb!\NewExpandableDocumentCommand!, and \underline{can not} have optional argument.
+In contrast to traditional \verb!tabular! environment, \verb!tabularray! environments
+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 key \verb!expand! to make \verb!tabularray! expand
+every occurrence of a specified macro \underline{once} before splitting the table body.
+Note that you \underline{can not} expand a command defined with \verb!\NewDocumentCommand!.
+
+To expand a command without optional argument, you can define it with \verb!\newcommand!.
\begin{demohigh}
-\def\tblrbody{
+\newcommand*\tblrbody{
\hline
20 & 30 & 40 \\
50 & 60 & 70 \\
@@ -1624,7 +1630,23 @@ The macro \underline{can not} be defined with \verb!\NewDocumentCommand! or
\end{tblr}
\end{demohigh}
-\section{Default Specifications}
+To expand commands with optional arguments, you \underline{can not} define them
+with \verb!\newcommand!. But you can define them with \verb!\NewExpandableDocumentCommand!,
+and use option \verb!expand=\expanded! to do exhaustive expansions.
+
+\begin{demohigh}
+\NewExpandableDocumentCommand\yes{O{Yes}m}{\SetCell{bg=green9}#1}
+\NewExpandableDocumentCommand\no{O{No}m}{\SetCell{bg=red9}#1}
+\begin{tblr}[expand=\expanded]{hlines}
+ What I get & is below \\
+ \expanded{\yes{}} & \expanded{\no{}} \\
+ \expanded{\yes[Great]{}} & \expanded{\no[Bad]{}}
+\end{tblr}
+\end{demohigh}
+
+Note that you need to protect fragile commands (if any) inside them with \verb!\unexpanded! command.
+
+\section{Default Specifications}%
\label{sec:default}
\verb!Tabularray! package provides \verb!\SetTblrInner! and \verb!\SetTblrOuter! commands
@@ -2713,6 +2735,9 @@ You can even generate the whole table with some function.
\end{tblr}
\end{demohigh}
+From version 2023A, you can evaluate all functions in the table body
+with option \texttt{evaluate=all}.
+
\subsection{Inner key \texttt{process} in action}
With inner key \verb!process!, you can modify the contents and styles before the table is built.
@@ -2987,6 +3012,55 @@ in \verb!tabularray! environments with \verb!rowsep=0pt!, such as
From version 2022D, you can load \verb!zref! library
to make \verb!\zref! and \verb!longtblr! work together.
+\chapter{Tips and Tricks}
+
+\section{Control Horizontal Alignment}
+
+You can control horizontal alignment of cells in \texttt{tabularray} with
+\href{https://www.ctan.org/pkg/ragged2e}{\texttt{ragged2e}} package,
+by redefining some of the following commands:
+
+\begin{codehigh}
+\RenewDocumentCommand\TblrAlignBoth{}{\justifying}
+\RenewDocumentCommand\TblrAlignLeft{}{\RaggedRight}
+\RenewDocumentCommand\TblrAlignCenter{}{\Centering}
+\RenewDocumentCommand\TblrAlignRight{}{\RaggedLeft}
+\end{codehigh}
+
+Please read the documentation of \texttt{ragged2e} package for more details of
+their alignment commands.
+
+\section{Use Safe Verbatim Commands}%
+\label{sec:fakeverb}
+
+Due to the limitation of TeX, even if you have passed \texttt{verb} option to a
+\texttt{tabularray} table, you still could not use some special characters in a
+\verb!\verb! command. As an replacement, you may use \verb|\fakeverb| command from \href{https://www.ctan.org/pkg/codehigh}{\texttt{codehigh}} package.
+
+The \verb|\fakeverb| command will remove the backslashes in the following control symbols before
+typesetting its content: \fakeverb{\\\\}, \fakeverb{\\\{}, \fakeverb{\\\}}, \fakeverb{\\\#}, \fakeverb{\\\^} and \texttt{\textbackslash\textvisiblespace}, \fakeverb{\\\%}.
+Also the argument of \verb|\fakeverb| command need to be enclosed with curly braces.
+Therefore it could be safely used inside \verb|tabularray| tables and other LaTeX commands.
+
+Here is an example of using \verb!\fakeverb! commands inside a \verb|tblr| environment
+(you don't need \texttt{verb} option to use \verb!\fakeverb!):
+
+\begin{demohigh}
+\begin{tblr}{hlines}
+ Special & \fakeverb{\abc{}$&^_^uvw 123} \\
+ Spacing & \fakeverb{\bfseries\ \#\%} \\
+ Nesting & \fbox{\fakeverb{$\left\\\{A\right.$\#}}
+\end{tblr}
+\end{demohigh}
+
+In the above example, balanced curly braces and control words (such as \verb!\bfseries!)
+need not to be escaped---only several special characters need to be escaped.
+Please read the documentation of \texttt{codehigh} package for more details of
+\verb|\fakeverb| commands.%
+\footnote{By the way, \fakeverb{\EscVerb} command from
+\href{https://www.ctan.org/pkg/fvextra}{\texttt{fvextra}} package is similar to
+\fakeverb{\fakeverb} command, but with \fakeverb{\EscVerb} you need to escape every control word.}
+
\chapter{History and Future}
\section{The Future}
@@ -3007,6 +3081,10 @@ and put it into the folder of your TeX documents:\newline
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 2023A, inner key \verb!verb! was marked as obsolete,
+and it will be removed in the future. But don't worry too much,
+because you can stick to old version by \verb!\usepackage{tabularray}[=2023-03-01]!.
+
In version 2022A, there were several breaking changes:
\begin{itemize}[nosep]