From c4d400d058136a9045857b99d816595e7a655125 Mon Sep 17 00:00:00 2001
From: Norbert Preining <norbert@preining.info>
Date: Fri, 2 Jul 2021 03:02:09 +0000
Subject: CTAN sync 202107020302

---
 macros/latex/contrib/tabularray/tabularray.tex | 1216 ++++++++++++++++++++++--
 1 file changed, 1147 insertions(+), 69 deletions(-)

(limited to 'macros/latex/contrib/tabularray/tabularray.tex')

diff --git a/macros/latex/contrib/tabularray/tabularray.tex b/macros/latex/contrib/tabularray/tabularray.tex
index 5b1912c063..45d486d995 100644
--- a/macros/latex/contrib/tabularray/tabularray.tex
+++ b/macros/latex/contrib/tabularray/tabularray.tex
@@ -6,6 +6,9 @@
 \usepackage{codehigh} % https://ctan.org/pkg/codehigh
 \usepackage{tabularray}
 \usepackage{array,multirow,amsmath}
+\usepackage{chemmacros}
+
+\UseTblrLibrary{booktabs,diagbox,siunitx}
 
 \usepackage{hyperref}
 \hypersetup{
@@ -13,17 +16,43 @@
   urlcolor=blue3,
   linkcolor=red3,
 }
+
+\usepackage{tcolorbox}
+\tcbset{sharp corners, boxrule=0.5pt, colback=red9}
+
+\usepackage{float}
+
+\setcounter{tocdepth}{1}
+
+\newcommand*{\K}[1]{\texttt{#1}}
+\newcommand*{\V}[1]{\texttt{#1}}
+
+\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},
+  rowhead = 1,
+}
+
+\newcommand{\mywarning}[1]{%
+  \begin{tcolorbox}
+  The interfaces in this #1 should be seen as
+  \textcolor{red3}{\bfseries experimental}
+  and are likely to change in future releases, if necessary.
+  Don’t use them in important documents.
+  \end{tcolorbox}
+}
+
 \renewcommand*{\thefootnote}{*}
 
-\newcommand*{\myversion}{2021K}
+\newcommand*{\myversion}{2021L}
 \newcommand*{\mydate}{Version \myversion\ (\the\year-\mylpad\month-\mylpad\day)\\\myrepo}
 \newcommand*{\myrepo}{\url{https://github.com/lvjr/tabularray}}
 \newcommand*{\mylpad}[1]{\ifnum#1<10 0\the#1\else\the#1\fi}
 
-\colorlet{highback}{\ifcase\month\or
-  red9\or brown9\or yellow9\or cyan9\or azure9\or blue9\or
-  red9\or brown9\or yellow9\or cyan9\or azure9\or blue9\fi
-}
+\colorlet{highback}{\ifodd\month azure9\else blue9\fi}
 \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}
@@ -39,11 +68,11 @@
 
 \tableofcontents
 
-\chapter{From Old to New}
+\chapter{Overview of Features}
 
 \section{Vertical Space}
 
-After loading \verb!tabularrray! package in the preamble,
+After loading \verb!tabularray! package in the preamble,
 we can use \verb!tblr! environments to typeset tabulars and arrays.
 The name \verb!tblr! is short for \verb!tabularray! or \verb!top-bottom-left-right!.
 The following is our first example:
@@ -74,10 +103,10 @@ The following is our first example:
 
 You may notice that there is extra space above and below the table rows with \verb!tblr! envirenment.
 This space makes the table look better.
-If you don't like it, you could use \verb!\SetTblrDefault! command:
+If you don't like it, you could use \verb!\SetTblrInner! command:
 
 \begin{demohigh}
-\SetTblrDefault{rowsep=0pt}
+\SetTblrInner{rowsep=0pt}
 \begin{tblr}{lccr}
 \hline
  Alpha   & Beta  & Gamma  & Delta \\
@@ -191,8 +220,8 @@ will be treated as \verb!h! and \verb!f!, respectively:
 \end{demohigh}
 
 Note that you don't need to load \verb!multirow! package first,
-since \verb!tabularrray! doesn't depend on it.
-Furthermore, \verb!tabularray! will always typeset descent multirow cells.
+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,
 even though some rows have large height:
 
@@ -309,7 +338,7 @@ which will help us to locate cells when the tables are rather complex:
 
 \verb!Tabularray! package supports all normal column types, as well as
 the extendable \verb!X! column type,
-which first occured in \verb!tabularx! package and was largely improved by \verb!tabu! package:
+which first occurred in \verb!tabularx! package and was largely improved by \verb!tabu! package:
 
 \begin{demohigh}
 \begin{tblr}{|X[2,l]|X[3,l]|X[1,r]|X[r]|}
@@ -453,7 +482,7 @@ Hlines and vlines can also have colors:
 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:
 
-\begin{demohigh}
+\begin{codehigh}
 \NewTableCommand\toprule{\hline[0.08em]}
 \NewTableCommand\midrule{\hline[0.05em]}
 \NewTableCommand\bottomrule{\hline[0.08em]}
@@ -466,14 +495,189 @@ The following example demonstrates how to define similar rules as in \verb!bookt
  Nu      & Xi    & Omicron & Pi    \\
 \bottomrule
 \end{tblr}
+\end{codehigh}
+
+\chapter{The Old Interfaces}
+
+With tabularray package, you can still use improved table commands to change the styles of tables.
+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}
 
-\chapter{New Interfaces}
+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.
 
 \section{Hlines and Vlines}
 
+All available keys for hlines and vlines are described in Table \ref{key:hvline}.
+
+\begin{spectblr}[
+  caption = {Keys for Hlines and Vlines},
+  label = {key:hvline},
+  remark{Note} = {In most cases, you can omit the underlined key names and write only their values.}
+]{}
+  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 \\
+\end{spectblr}
+
 Options \verb!hlines! and \verb!vlines! are for setting all hlines and vlines, respectively.
 With empty value, all hlines/vlines will be solid.
 
@@ -571,18 +775,69 @@ 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%
+\footnote{Code from \url{https://tex.stackexchange.com/questions/603023/tabularray-and-tabularx-column-separator}.}:
+
+\begin{demohigh}
+\begin{tblr}{
+  vlines, hlines,
+  colspec = {lX[c]X[c]X[c]X[c]},
+  vline{2} = {1}{text=\clap{:}},
+  vline{3} = {1}{text=\clap{\ch{+}}},
+  vline{4} = {1}{text=\clap{\ch{->}}},
+  vline{5} = {1}{text=\clap{\ch{+}}},
+}
+  Equation & \ch{CH4} & \ch{2 O2} & \ch{CO2} & \ch{2 H2O} \\
+  Initial  & $n_1$    & $n_2$     & 0        & 0 \\
+  Final    & $n_1-x$  & $n_2-2x$  & $x$      & $2x$ \\
+\end{tblr}
+\end{demohigh}
+
+You need to load \verb!chemmacros! package for the \verb!\ch! command.
+
 \section{Cells and Spancells}
 
-Option \verb!cells! is for setting all cells.
+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},
+  remark{Note} = {In most cases, you can omit the underlined key names and write only their values.}
+]{}
+  Key & Description and Values & Initial Value \\
+  \underline{\K{halign}}
+    & horizontal alignment: \V{l} (left), \V{c} (center), or \V{r} (right)
+    & \V{l} \\
+  \underline{\K{valign}}
+    & 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 \\
+\end{spectblr}
+\vspace{-2em}
+\begin{spectblr}[
+  caption = {Keys for Multispan of Cells},
+  label = {key:cellspan},
+]{}
+  Key & Description and Values & Initial Value \\
+  \K{r} & number of rows the cell spans    & 1 \\
+  \K{c} & number of columns the cell spans & 1 \\
+\end{spectblr}
 
+Option \verb!cells! is for setting all cells.
+\nopagebreak
 \begin{demohigh}
 \begin{tblr}{hlines={white},cells={c,blue7}}
  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}
 
@@ -609,8 +864,67 @@ Option \verb!cell{i}{j}! is for setting some cells.
 
 \section{Rows and Columns}
 
-Options \verb!rows! and \verb!columns! are for setting all rows and columns, respectively.
+All available keys for rows and columns are described in Table \ref{key:row} and Table \ref{key:column}.
+
+\begin{spectblr}[
+  caption = {Keys for Rows},
+  label = {key:row},
+  remark{Note} = {In most cases, you can omit the underlined key names and write only their values.}
+]{}
+  Key & Description and Values & Initial Value \\
+  \underline{\K{halign}}
+    & horizontal alignment: \V{l} (left), \V{c} (center), or \V{r} (right)
+    & \V{l} \\
+  \underline{\K{valign}}
+    & 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 \\
+  \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} \\
+  \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 \\
+\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.}
+]{}
+  Key & Description and Values & Initial Value \\
+  \underline{\K{halign}}
+    & horizontal alignment: \V{l} (left), \V{c} (center), or \V{r} (right)
+    & \V{l} \\
+  \underline{\K{valign}}
+    & 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 \\
+  \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} \\
+  \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 \\
+\end{spectblr}
 
+Options \verb!rows! and \verb!columns! are for setting all rows and columns, respectively.
+\nopagebreak
 \begin{demohigh}
 \begin{tblr}{
  hlines,
@@ -642,13 +956,10 @@ Options \verb!row{i}! and \verb!column{j}! are for setting some rows and columns
 \end{tblr}
 \end{demohigh}
 
-We can specify foreground colors, background colors and fonts with
-\verb!bg!, \verb!fg! and \verb!font! keys, respectively, for cells/rows/columns.
-In most cases, \verb!bg! key can be omitted, which you can see in the previous examples.
-
+The following example demonstrates the usages of \verb!bg!, \verb!fg! and \verb!font! keys.
+\nopagebreak
 \begin{demohigh}
 \begin{tblr}{
- colspec  = {lcr},
  row{odd} = {bg=azure8},
  row{1}   = {bg=azure3, fg=white, font=\sffamily},
 }
@@ -660,21 +971,9 @@ In most cases, \verb!bg! key can be omitted, which you can see in the previous e
 \end{tblr}
 \end{demohigh}
 
-\section{Space in Tables}
-
-Options \verb!rowsep! and \verb!colsep! are for setting padding for rows and columns, respectively.
-
-\begin{demohigh}
-\SetTblrDefault{rowsep=2pt,colsep=2pt}
-\begin{tblr}{hlines,vlines}
- Alpha   & Beta  & Gamma  & Delta \\
- Epsilon & Zeta  & Eta    & Theta \\
- Iota    & Kappa & Lambda & Mu    \\
-\end{tblr}
-\end{demohigh}
-
-Also \verb!abovesep!, \verb!belowsep!, \verb!leftsep!, \verb!rightsep! options are available:
-
+The following example demonstrates the usages of
+\verb!abovesep!, \verb!belowsep!, \verb!leftsep!, \verb!rightsep! keys.
+\nopagebreak
 \begin{demohigh}
 \begin{tblr}{
  hlines,
@@ -688,7 +987,7 @@ Also \verb!abovesep!, \verb!belowsep!, \verb!leftsep!, \verb!rightsep! options a
 \end{tblr}
 \end{demohigh}
 
-And \verb!\\[dimen]! can be replaced by \verb!belowsep+! option:
+The following example shows that we can replace \verb!\\[dimen]! with \verb!belowsep+! key.
 
 \begin{demohigh}
 \begin{tblr}{
@@ -700,8 +999,42 @@ And \verb!\\[dimen]! can be replaced by \verb!belowsep+! option:
 \end{tblr}
 \end{demohigh}
 
-Also \verb!\doublerulesep! parameter can be replaced by \verb!rulesep! option:
+\section{The Whole Table}
+
+All available keys for the whole table are described in Table \ref{key:table}.
+
+\begin{spectblr}[
+  caption = {Keys for the Whole 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} \\
+  \K{belowsep} & set vertical space below every row & \V{2pt} \\
+  \K{rowsep} & set vertical space above and below every row & \V{2pt} \\
+  \K{leftsep} & set horizontal space to the left of every column & \V{6pt} \\
+  \K{rightsep} & set horizontal space to the right of every column & \V{6pt} \\
+  \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} \\
+\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}
 \begin{tblr}{
  colspec={||llll||},rowspec={|QQQ|},rulesep=4pt,
@@ -712,7 +1045,7 @@ Also \verb!\doublerulesep! parameter can be replaced by \verb!rulesep! option:
 \end{tblr}
 \end{demohigh}
 
-Also \verb!\arraystretch! parameter can be replaced by \verb!stretch! option:
+The following example shows that we can replace \verb!\arraystretch! parameter with \verb!stretch! key.
 
 \begin{demohigh}
 \begin{tblr}{hlines,stretch=1.5}
@@ -722,39 +1055,34 @@ Also \verb!\arraystretch! parameter can be replaced by \verb!stretch! option:
 \end{tblr}
 \end{demohigh}
 
-\section{Counters in Tables}
-
-Counters \verb!rownum!, \verb!colnum!, \verb!rowcount!, \verb!colcount! can be used in cell text:
-
+The following example uses \verb!rowsep! and \verb!colsep! keys to set padding for all rows and columns.
+\nopagebreak
 \begin{demohigh}
-\begin{tblr}{hlines}
- Cell[\arabic{rownum}][\arabic{colnum}] & Cell[\arabic{rownum}][\arabic{colnum}] &
- Cell[\arabic{rownum}][\arabic{colnum}] & Cell[\arabic{rownum}][\arabic{colnum}] \\
- Cell[\arabic{rownum}][\arabic{colnum}] & Cell[\arabic{rownum}][\arabic{colnum}] &
- Cell[\arabic{rownum}][\arabic{colnum}] & Cell[\arabic{rownum}][\arabic{colnum}] \\
- Row=\arabic{rowcount}, Col=\arabic{colcount} &
- Row=\arabic{rowcount}, Col=\arabic{colcount} &
- Row=\arabic{rowcount}, Col=\arabic{colcount} &
- Row=\arabic{rowcount}, Col=\arabic{colcount} \\
- Cell[\arabic{rownum}][\arabic{colnum}] & Cell[\arabic{rownum}][\arabic{colnum}] &
- Cell[\arabic{rownum}][\arabic{colnum}] & Cell[\arabic{rownum}][\arabic{colnum}] \\
- Cell[\arabic{rownum}][\arabic{colnum}] & Cell[\arabic{rownum}][\arabic{colnum}] &
- Cell[\arabic{rownum}][\arabic{colnum}] & Cell[\arabic{rownum}][\arabic{colnum}] \\
+\SetTblrInner{rowsep=2pt,colsep=2pt}
+\begin{tblr}{hlines,vlines}
+ Alpha   & Beta  & Gamma  & Delta \\
+ Epsilon & Zeta  & Eta    & Theta \\
+ Iota    & Kappa & Lambda & Mu    \\
 \end{tblr}
 \end{demohigh}
 
-\section{Experimental Interfaces}
+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.
+The following examples show the results from different \verb!hspan! values.
 
-Everything described in this section is in \underline{\textcolor{red3}{\textbf{experimental}}} status.
-Don’t use them in important documents, unless you have time
-to update them for the newer versions of \verb!tabularray! package in the future.
-
-By default \verb!tabularray! package will compute column widths from span widths.
-By setting option \verb!hspan=minimal!, it will compute span widths from column widths.
-The following two examples show this difference:
+\begin{demohigh}
+\SetTblrInner{hlines, vlines, hspan=default}
+\begin{tblr}{cell{2}{1}={c=2}{l},cell{3}{1}={c=3}{l},cell{4}{2}={c=2}{l}}
+ 111 111 & 222 222 & 333 333 \\
+ 12 Multi Columns Multi Columns 12 & & 333 \\
+ 13 Multi Columns Multi Columns Multi Columns 13 & & \\
+ 111 & 23 Multi Columns Multi Columns 23 & \\
+\end{tblr}
+\end{demohigh}
 
 \begin{demohigh}
-\SetTblrDefault{hlines,vlines}
+\SetTblrInner{hlines, vlines, hspan=even}
 \begin{tblr}{cell{2}{1}={c=2}{l},cell{3}{1}={c=3}{l},cell{4}{2}={c=2}{l}}
  111 111 & 222 222 & 333 333 \\
  12 Multi Columns Multi Columns 12 & & 333 \\
@@ -764,7 +1092,7 @@ The following two examples show this difference:
 \end{demohigh}
 
 \begin{demohigh}
-\SetTblrDefault{hlines,vlines,hspan=minimal}
+\SetTblrInner{hlines, vlines, hspan=minimal}
 \begin{tblr}{cell{2}{1}={c=2}{l},cell{3}{1}={c=3}{l},cell{4}{2}={c=2}{l}}
  111 111 & 222 222 & 333 333 \\
  12 Multi Columns Multi Columns 12 & & 333 \\
@@ -773,13 +1101,763 @@ The following two examples show this difference:
 \end{tblr}
 \end{demohigh}
 
+The following examples show the results from different \verb!vspan! values.
+\nopagebreak
+\begin{demohigh}
+\SetTblrInner{hlines, vlines, vspan=default}
+\begin{tblr}{column{2}={3.25cm}, cell{2}{2}={r=3}{l}}
+  Column1 & Column2 \\
+  Row1 & Long text that needs multiple lines.
+         Long text that needs multiple lines.
+         Long text that needs multiple lines. \\
+  Row2 & \\
+  Row3 & \\
+  Row4 & Short text \\
+\end{tblr}
+\end{demohigh}
+
+\begin{demohigh}
+\SetTblrInner{hlines, vlines, vspan=even}
+\begin{tblr}{column{2}={3.25cm}, cell{2}{2}={r=3}{l}}
+  Column1 & Column2 \\
+  Row1 & Long text that needs multiple lines.
+         Long text that needs multiple lines.
+         Long text that needs multiple lines. \\
+  Row2 & \\
+  Row3 & \\
+  Row4 & Short text \\
+\end{tblr}
+\end{demohigh}
+
+\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.
+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}).
+
+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{codehigh}
+\SetTblrInner{hlines,vlines}
+\SetTblrOuter{valign=b}
+\end{codehigh}
+
+You can define new \verb!tabularray! environments using \verb!\NewTblrEnviron! command:
+
+\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
+\end{demohigh}
+
+\section{Counters and Lengths}
+
+Counters \verb!rownum!, \verb!colnum!, \verb!rowcount!, \verb!colcount! can be used in cell text:
+\nopagebreak
+\begin{demohigh}
+\begin{tblr}{hlines}
+ Cell[\arabic{rownum}][\arabic{colnum}] & Cell[\arabic{rownum}][\arabic{colnum}] &
+ Cell[\arabic{rownum}][\arabic{colnum}] & Cell[\arabic{rownum}][\arabic{colnum}] \\
+ Row=\arabic{rowcount}, Col=\arabic{colcount} &
+ Row=\arabic{rowcount}, Col=\arabic{colcount} &
+ Row=\arabic{rowcount}, Col=\arabic{colcount} &
+ Row=\arabic{rowcount}, Col=\arabic{colcount} \\
+ Cell[\arabic{rownum}][\arabic{colnum}] & Cell[\arabic{rownum}][\arabic{colnum}] &
+ Cell[\arabic{rownum}][\arabic{colnum}] & Cell[\arabic{rownum}][\arabic{colnum}] \\
+\end{tblr}
+\end{demohigh}
+
+Also, lengths \verb!\leftsep!, \verb!\rightsep!, \verb!\abovesep!, \verb!\belowsep! can be used in cell text.
+
+\section{Tracing Tabularray}
+
 To trace internal data behind \verb!tblr! environment, you can use \verb!\SetTblrTracing! command.
 For example, \verb!\SetTblrTracing{all}! will turn on all tracings,
 and \verb!\SetTblrTracing{none}! will turn off all tracings.
 \verb!\SetTblrTracing{+row,+column}! will only tracing row and column data.
 All tracing messages will be written to the log files.
 
-\chapter{Source Code}
+\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
+\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.
+
+\NewTblrTheme{fancy}{
+  \SetTblrStyle{firsthead}{font=\bfseries}
+  \SetTblrStyle{firstfoot}{fg=blue2}
+  \SetTblrStyle{middlefoot}{\itshape}
+  \SetTblrStyle{caption-tag}{red2}
+}
+\begin{longtblr}[
+  theme = fancy,
+  caption = {A Long Long Long Long Long Long Long Table},
+  entry = {Short Caption},
+  label = {tblr:test},
+  note{a} = {It is the first footnote.},
+  note{$\dag$} = {It is the second long long long long long long footnote.},
+  remark{Note} = {Some general note. Some general note. Some general note.},
+  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,
+}
+\hline
+ \SetRow{purple7} Head & Head & Head \\
+\hline
+ \SetRow{purple7} Head & Head & Head \\
+\hline
+ Alpha   & Beta  & Gamma   \\
+\hline
+ Epsilon & Zeta\TblrNote{a} & Eta \\
+\hline
+ Iota    & Kappa\TblrNote{$\dag$} & 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
+ 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
+ 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
+ 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
+ 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
+ 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
+ Alpha   & Beta  & Gamma\footnote{Hello}   \\
+\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
+% Alpha   & Beta  & Gamma   \\
+%\hline
+% Epsilon & Zeta  & Eta     \\
+%\hline
+% Iota    & Kappa & Lambda  \\
+%\hline
+% Nu      & Xi    & Omicron \\
+%\hline
+% Rho     & Sigma & Tau     \\
+%\hline
+% Phi     & Chi   & Psi     \\
+\hline
+ \SetRow{blue7} 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.
+We support table footnotes, but not page footnotes in \verb!tabularray! package.
+
+\newpage
+
+The source code for the above long table is shown below. It is mainly self-explanatory.
+
+\begin{codehigh}
+\NewTblrTheme{fancy}{
+  \SetTblrStyle{firsthead}{font=\bfseries}
+  \SetTblrStyle{firstfoot}{fg=blue2}
+  \SetTblrStyle{middlefoot}{\itshape}
+  \SetTblrStyle{caption-tag}{red2}
+}
+\begin{longtblr}[
+  theme = fancy,
+  caption = {A Long Long Long Long Long Long Long Table},
+  entry = {Short Caption},
+  label = {tblr:test},
+  note{a} = {It is the first footnote.},
+  note{$\dag$} = {It is the second long long long long long long footnote.},
+  remark{Note} = {Some general note. Some general note. Some general note.},
+  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,
+}
+\hline
+ \SetRow{purple7} Head & Head & Head \\
+\hline
+ \SetRow{purple7} Head & Head & Head \\
+\hline
+ Alpha   & Beta  & Gamma   \\
+\hline
+ Epsilon & Zeta\TblrNote{a} & Eta \\
+\hline
+ Iota    & Kappa\TblrNote{$\dag$} & Lambda \\
+\hline
+ Nu      & Xi    & Omicron \\
+\hline
+ Rho     & Sigma & Tau     \\
+\hline
+ Phi     & Chi   & Psi     \\
+\hline
+......
+\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
+ \SetRow{blue7} Foot & Foot & Foot \\
+\hline
+\end{longtblr}
+\end{codehigh}
+
+As you can see in the above code, we typeset long tables with \verb!longtblr! environemnt.
+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.
+Their options are inner specifications and should be put in the mandatory argument of the \verb!longtblr! environment.
+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 \\
+  \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}
+
+Table head and table foot consist of the caption, continuation text, footnotes and remarks.
+Their options are outer specifications and should be put in the optional argument of the \verb!longtblr! environment.
+
+\begin{spectblr}[
+  caption = {Outer Specifications for Table Heads and Table Foots}
+]{}
+  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 \\
+\end{spectblr}
+
+\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,
+you can include other templates with \verb!\UseTblrTemplate! and \verb!\ExpTblrTemplate! commands.
+
+\begin{spectblr}[
+  caption = {Templates for Table Heads and Table Foots}
+]{}
+  Template Name    & Template Description \\
+  \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)'' \\
+  \V{conthead}     & continuation paragraph in the head, normally including \V{conthead-text} template \\
+  \V{caption-tag}  & caption tag, normally like ``Table 4.2'' \\
+  \V{caption-sep}  & caption separator, normally like ``:\quad'' \\
+  \V{caption-text} & caption text, normally using user provided value \\
+  \V{caption}      & including \V{caption-tag} + \V{caption-sep} + \V{caption-text} \\
+  \V{note-tag}     & note tag, normally using user provided value \\
+  \V{note-sep}     & note separator, normally like ``\enskip'' \\
+  \V{note-text}    & note tag, normally using user provided value \\
+  \V{note}         & including \V{note-tag} + \V{note-sep} + \V{note-text} \\
+  \V{remark-tag}   & remark tag, normally using user provided value \\
+  \V{remark-sep}   & remark separator, normally like ``:\enskip'' \\
+  \V{remark-text}  & remark text, normally using user provided value\\
+  \V{remark}       & including \V{remark-tag} + \V{remark-sep} + \V{remark-text} \\
+  \V{firsthead}    & table head on the first page, normally including \V{caption} template \\
+  \V{middlehead}   & table head on middle pages, normally including \V{caption} and \V{conthead} templates \\
+  \V{lasthead}     & table head on the last page, normally including \V{caption} and \V{conthead} templates \\
+  \V{head}         & setting all of \V{firsthead}, \V{middlehead} and \V{lasthead} \\
+  \V{firstfoot}    & table foot on the first page, normally including \V{contfoot} template \\
+  \V{middlefoot}   & table foot on middle pages, normally including \V{contfoot} template \\
+  \V{lastfoot}     & table foot on the last page, normally including \V{note} and \V{remark} templates \\
+  \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.
+
+\subsection{Continuation Templates}
+
+Let us have a look at the code for defining templates of continuation text first:
+
+\begin{codehigh}
+\DefTblrTemplate{contfoot-text}{normal}{Continued on next page}
+\SetTblrTemplate{contfoot-text}{normal}
+\DefTblrTemplate{conthead-text}{normal}{(Continued)}
+\SetTblrTemplate{conthead-text}{normal}
+\end{codehigh}
+
+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!.
+Therefore you had better use another name when defining new templates.
+
+If you use \verb!default! as template name in \verb!\DefTblrTemplate!,
+you define and set it as default at the same time.
+Therefore the above code can be written in another way:
+
+\begin{codehigh}
+\DefTblrTemplate{contfoot-text}{default}{Continued on next page}
+\DefTblrTemplate{conthead-text}{default}{(Continued)}
+\end{codehigh}
+
+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.
+But you can also handle user settings such as horizontal alignment here.
+
+\begin{codehigh}
+\DefTblrTemplate{contfoot}{default}{\UseTblrTemplate{contfoot-text}{default}}
+\DefTblrTemplate{conthead}{default}{\UseTblrTemplate{conthead-text}{default}}
+\end{codehigh}
+
+\subsection{Caption Templates}
+
+Normally a caption consists of three parts, and their templates are defined with the follow code:
+
+\begin{codehigh}
+\DefTblrTemplate{caption-tag}{default}{Table\hspace{0.25em}\thetable}
+\DefTblrTemplate{caption-sep}{default}{:\enskip}
+\DefTblrTemplate{caption-text}{default}{\InsertTblrText{caption}}
+\end{codehigh}
+
+The command \verb!\InsertTblrText{caption}! inserts the value of \verb!caption! key,
+which you could write in the optional argument of \verb!longtblr! environment.
+
+The \verb!caption! template normally includes three sub templates with \verb!\UseTblrTemplate! commands:
+The \verb!caption! template will be used in \verb!firsthead! template.
+
+\begin{codehigh}
+\DefTblrTemplate{caption}{default}{
+  \UseTblrTemplate{caption-tag}{default}
+  \UseTblrTemplate{caption-sep}{default}
+  \UseTblrTemplate{caption-text}{default}
+}
+\end{codehigh}
+
+Furthermore \verb!capcont! template includes \verb!conthead! template as well.
+The \verb!capcont! template will be used in \verb!middlehead! and \verb!lasthead! templates.
+
+\begin{codehigh}
+\DefTblrTemplate{capcont}{default}{
+  \UseTblrTemplate{caption-tag}{default}
+  \UseTblrTemplate{caption-sep}{default}
+  \UseTblrTemplate{caption-text}{default}
+  \UseTblrTemplate{conthead}{default}
+}
+\end{codehigh}
+
+\subsection{Note and Remark Templates}
+
+The templates for table notes can be defined like this:
+
+\begin{codehigh}
+\DefTblrTemplate{note-tag}{default}{\textsuperscript{\InsertTblrNoteTag}}
+\DefTblrTemplate{note-sep}{default}{\space}
+\DefTblrTemplate{note-text}{default}{\InsertTblrNoteText}
+\end{codehigh}
+\begin{codehigh}
+\DefTblrTemplate{note}{default}{
+  \MapTblrNotes{
+    \noindent
+    \UseTblrTemplate{note-tag}{default}
+    \UseTblrTemplate{note-sep}{default}
+    \UseTblrTemplate{note-text}{default}
+    \par
+  }
+}
+\end{codehigh}
+
+The \verb!\MapTblrNotes! command loops for all table notes,
+which are written in the optional argument of \verb!longtblr! environment.
+Inside the loop, you can use \verb!\InsertTblrNoteTag! and \verb!\InsertTblrNoteText!
+commands to insert current note tag and note text, respectively.
+
+The definition of remark templates are similar to note templates.
+\nopagebreak
+\begin{codehigh}
+\DefTblrTemplate{remark-tag}{default}{\InsertTblrRemarkTag}
+\DefTblrTemplate{remark-sep}{default}{:\space}
+\DefTblrTemplate{remark-text}{default}{\InsertTblrRemarkText}
+\end{codehigh}
+\begin{codehigh}
+\DefTblrTemplate{remark}{default}{
+  \MapTblrRemarks{
+    \noindent
+    \UseTblrTemplate{remark-tag}{default}
+    \UseTblrTemplate{remark-sep}{default}
+    \UseTblrTemplate{remark-text}{default}
+    \par
+  }
+}
+\end{codehigh}
+
+\subsection{Head and Foot Templates}
+
+The templates for table heads and foots are defined as including other templates:
+
+\begin{codehigh}
+\DefTblrTemplate{firsthead}{default}{
+  \UseTblrTemplate{caption}{default}
+}
+\DefTblrTemplate{middlehead,lasthead}{default}{
+  \UseTblrTemplate{capcont}{default}
+}
+\DefTblrTemplate{firstfoot,middlefoot}{default}{
+  \UseTblrTemplate{contfoot}{default}
+}
+\DefTblrTemplate{lastfoot}{default}{
+  \UseTblrTemplate{note}{default}
+  \UseTblrTemplate{remark}{default}
+}
+\end{codehigh}
+
+Note that you can define the same template for multiple elements in \verb!\DefTblrTemplate! command.
+
+\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},
+  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.}
+]{}
+  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 \\
+\end{spectblr}
+
+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.
+In contrast, \verb!\ExpTblrTemplate{element}{default}! will only include template code.
+
+\section{Define Themes}
+
+You may define your own themes for table heads and foots with \verb!\NewTblrTheme! command.
+a theme consists of some template and style settings. For example:
+\nopagebreak
+\begin{codehigh}
+\NewTblrTheme{fancy}{
+  \DefTblrTemplate{conthead}{default}{[Continued]}
+  \SetTblrStyle{firsthead}{font=\bfseries}
+  \SetTblrStyle{firstfoot}{fg=blue2}
+  \SetTblrStyle{middlefoot}{\itshape}
+  \SetTblrStyle{caption-tag}{red2}
+}
+\end{codehigh}
+
+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}
+
+\mywarning{chapter}
+
+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}}
+
+When you write \verb!\UseTblrLibrary{booktabs}!,
+\verb!tabularray! package will define commands \verb!\toprule!, \verb!\midrule!,
+\verb!\bottomrule! and \verb!\cmidrule! inside \verb!tblr! environment.
+
+\begin{demohigh}
+\begin{tblr}{llll}
+\toprule
+ Alpha   & Beta  & Gamma   & Delta \\
+\midrule
+ Epsilon & Zeta  & Eta     & Theta \\
+\cmidrule{1-3}
+ Iota    & Kappa & Lambda  & Mu    \\
+\cmidrule{2-4}
+ Nu      & Xi    & Omicron & Pi    \\
+\bottomrule
+\end{tblr}
+\end{demohigh}
+
+At this moment, \verb!trim! options for \verb!\cmidrule! command are not supported.
+But rule colors are possible just like \verb!\hline! and \verb!\cline! commands.
+
+\begin{demohigh}
+\begin{tblr}{llll}
+\toprule[purple3]
+ Alpha   & Beta  & Gamma   & Delta \\
+\midrule[blue3]
+ Epsilon & Zeta  & Eta     & Theta \\
+\cmidrule[azure3]{1-3}
+ Iota    & Kappa & Lambda  & Mu    \\
+\cmidrule[azure3]{2-4}
+ Nu      & Xi    & Omicron & Pi    \\
+\bottomrule[purple3]
+\end{tblr}
+\end{demohigh}
+
+\section{Library \V{diagbox}}
+
+When writing \verb!\UseTblrLibrary{diagbox}! in the preamble of the document,
+\verb!tabularray! package loads \verb!diagbox! package,
+and you can use \verb!\diagbox! and \verb!\diagboxthree! commands inside \verb!tblr! environment.
+
+\begin{demohigh}
+\begin{tblr}{hlines,vlines}
+ \diagbox{Aa}{Pp} & Beta & Gamma \\
+ Epsilon & Zeta  & Eta \\
+ Iota    & Kappa & Lambda \\
+\end{tblr}
+\end{demohigh}
+
+\begin{demohigh}
+\begin{tblr}{hlines,vlines}
+ \diagboxthree{Aa}{Pp}{Hh} & Beta & Gamma \\
+ Epsilon & Zeta  & Eta \\
+ Iota    & Kappa & Lambda \\
+\end{tblr}
+\end{demohigh}
+
+You can also use \verb!\diagbox! and \verb!\diagboxthree! commands in math mode.
+\nopagebreak
+\begin{demohigh}
+$\begin{tblr}{|c|cc|}
+\hline
+ \diagbox{X_1}{X_2} & 0 & 1 \\
+\hline
+  0 & 0.1 & 0.2 \\
+  1 & 0.3 & 0.4 \\
+\hline
+\end{tblr}$
+\end{demohigh}
+
+\section{Library \V{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.
+
+\begin{demohigh}
+\begin{tblr}{
+  hlines, vlines,
+  colspec={
+    S[table-format=2.2]
+    S[table-format=2.2]
+    S[table-format=2.2]
+  }
+}
+ {{{Head}}} & {{{Head}}} & {{{Head}}} \\
+    11      &    11      &    11      \\
+     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.
+
+\begin{demohigh}
+\begin{tblr}{
+  hlines, vlines,
+  colspec={
+    Q[si={table-format=2.2},blue7]
+    Q[si={table-format=2.2},teal7]
+    Q[si={table-format=2.2},purple7]
+  }
+}
+ {{{Head}}} & {{{Head}}} & {{{Head}}} \\
+    11      &    11      &    11      \\
+     2.1    &     2.2    &     2.3    \\
+    33.11   &    33.22   &    33.33   \\
+\end{tblr}
+\end{demohigh}
+
+\chapter{The Source Code}
 
 %\CodeHigh{lite}
 \dochighinput[language=latex/latex3]{tabularray.sty}
-- 
cgit v1.2.3

