Merge pull request #443 from muzimuzhi/docs/booktabs-lib

Improve docs for `booktabs` lib

manual/manual-1.tex

@@ -62,7 +62,7 @@ \section{Vertical Space}
  Iota    & Kappa & Lambda & Mu    \\
 \hline
 \end{tblr}
-\end{demohigh} 
+\end{demohigh}
 
 But in many cases, this \verb!rowsep! is useful:
 
@@ -101,7 +101,7 @@ \section{Multiline Cells}
  {L \\ Left} & {C \\ Cent \\ Center} & R \\
 \hline
 \end{tblr}
-\end{demohigh} 
+\end{demohigh}
 
 \section{Cell Alignment}
 
@@ -117,7 +117,7 @@ \section{Cell Alignment}
  {Top Baseline \\ Left Left} & Middle Center & {Right Right \\ Bottom Baseline} \\
 \hline
 \end{tblr}
-\end{demohigh} 
+\end{demohigh}
 
 Note that you can use more meaningful \verb!t! instead of \verb!p! for top baseline alignment.
 For some users who are familiar with word processors,
@@ -271,7 +271,7 @@ \section{Multi Rows and Columns}
 \begin{demohigh}
 \begin{tblr}{|ll|c|rr|}
 \hline
- \SetCell[r=3,c=2]{h} r=3 c=2 & 1-2 & \SetCell[r=2,c=3]{r} r=2 c=3 & 1-4 & 1-5 \\ 
+ \SetCell[r=3,c=2]{h} r=3 c=2 & 1-2 & \SetCell[r=2,c=3]{r} r=2 c=3 & 1-4 & 1-5 \\
  2-1 & 2-2 & 2-3 & 2-4 & 2-5 \\
 \hline
  3-1 & 3-2 & MIDDLE & \SetCell[r=3,c=2]{f} r=3 c=2 & 3-5 \\

manual/manual-2.tex

@@ -42,7 +42,7 @@ \section{Old and New Interfaces}
   \verb!\SetColumn!                              & \K{column}, \K{colspec} \\
 \end{newtblr}
 
-\section{Hlines and Vlines}
+\section{Hlines and Vlines}\label{sec:hlines-vlines}
 
 All available keys for hlines and vlines are described in Table \ref{key:hline} and Table \ref{key:vline}.
 
@@ -58,6 +58,9 @@ \section{Hlines and Vlines}
   \underline{\K{fg}}   & rule color name & \None \\
   \K{leftpos}          & crossing or trimming position at the left side  & \V{1} \\
   \K{rightpos}         & crossing or trimming position at the right side & \V{1} \\
+  \K{l}                & same as \K{leftpos}, default \V{-0.8} & \V{1} \\
+  \K{r}                & same as \K{rightpos}, default \V{-0.8} & \V{1} \\
+  \K{lr}               & crossing or trimming positions at both sides, default \V{-0.8} & \V{1} \\
   \K{endpos}           & adjust leftpos/rightpos for only the leftmost/rightmost column & \V{false} \\
 \end{spectblr}
 \vspace{-2em}
@@ -304,7 +307,7 @@ \subsection{Hlines and Vlines in Old Interfaces}
 \end{demohigh}
 
 Commands \verb!\SetHline! combines the usages of \verb!\hline! and \verb!\cline!:
- 
+
 \begin{demohigh}
 \begin{tblr}{llll}
 \SetHline{1-3}{blue5,1pt}

manual/manual-5.tex

@@ -60,8 +60,11 @@ \section{Library \texttt{booktabs}}
 
 With \verb!\UseTblrLibrary{booktabs}! in the preamble of the document,
 \verb!tabularray! will load \verb!booktabs! package,
-and define \verb!\toprule!, \verb!\midrule!,
-\verb!\bottomrule! and \verb!\cmidrule! inside \verb!tblr! environment.
+and define
+  \verb!\toprule!, \verb!\midrule!, \verb!\bottomrule!,
+  \verb!\cmidrule!, \verb!\cmidrulemore!, \verb!\morecmidrules!,
+  \verb!\specialrule!, \verb!\addrowspace!, and \verb!\addlinespace!
+as table commands.
 
 \begin{demohigh}
 \begin{tblr}{llll}
@@ -78,7 +81,14 @@ \section{Library \texttt{booktabs}}
 \end{demohigh}
 
 Just like \verb!\hline! and \verb!\cline! commands,
-you can also specify rule width and color in the optional argument of any of these commands.
+you can also specify rule width and color by using hline keys in the optional
+argument of any of these commands.
+
+Like in \verb!booktabs!, by default
+  width of \verb!\toprule! and \verb!\bottomrule! are determined by \verb!\heavyrulewidth!,
+  width of \verb!\midrule! is determined by \verb!\lightrulewidth!, and
+  width of \verb!\cmidrule! and \verb!\cmidrulemore! are determined by \verb!\cmidrulewidth!, respectively.
+All three \verb!\...rulewidth! are dimensions.
 
 \begin{demohigh}
 \begin{tblr}{llll}
@@ -92,7 +102,10 @@ \section{Library \texttt{booktabs}}
 \end{tblr}
 \end{demohigh}
 
-If you need more than one \verb!\cmidrule!s, you can use \verb!\cmidrulemore! command.
+If you need more than one \verb!\cmidrule!s, you can use \verb!\cmidrulemore!
+command, which is simpler than the \verb!booktabs! usage
+\verb!\morecmidrules\cmidrule!.
+\verb!\cmidrulemore! can receive hline keys in an optional argument too.
 
 \begin{demohigh}
 \begin{tblr}{llll}
@@ -106,8 +119,11 @@ \section{Library \texttt{booktabs}}
 \end{tblr}
 \end{demohigh}
 
-From version 2021N (2021-09-01), trim options (\verb!l!, \verb!r!, \verb!lr!)
-for \verb!\cmidrule! command are also supported.
+From version 2021N (2021-09-01), you can set trimming positions of
+\verb!\cmidrule! and \verb!\cmidrulemore!, using newly introduced trimming
+options (\verb!leftpos!, \verb!rightpos!, \verb!endpos!, \verb!l!, \verb!r!,
+and \verb!lr!) (see Section~\ref{sec:hlines-vlines}).
+Option \verb!endpos! is already applied to these two commands.
 
 \begin{demohigh}
 \begin{tblr}{llll}
@@ -121,11 +137,10 @@ \section{Library \texttt{booktabs}}
 \end{tblr}
 \end{demohigh}
 
-Note that you need to put \verb!l!, \verb!r! or \verb!lr! option into
-the \underline{\color{red3}square brackets}.
-and the possible values are decimal numbers between \verb!-1! and \verb!0!,
-where \verb!-1! means trimming the whole colsep, and \verb!0! means no trimming.
-The default value is \verb!-0.8!, which makes similar result as \verb!booktabs! package does.
+Since \verb!booktabs! tables usually don't have vlines, the meaningful values
+here are decimal numbers between \verb!-1! and \verb!0!.
+The default value \verb!-0.8! for \verb!l!, \verb!r!, and \verb!lr! is chosen to
+make similar result as \verb!booktabs! package does.
 
 There is also a \verb!booktabs! environment for you. With this environment,
 the default \verb!rowsep=0pt!, but extra vertical space will be added by
@@ -166,9 +181,11 @@ \section{Library \texttt{booktabs}}
 \end{booktabs}
 \end{demohigh}
 
-At last, there is also an \verb!\addlinespace! command.
-You can specify the size of vertical space to be added in its optional argument,
-and the default size is \verb!0.5em!.
+At last, there is also an \verb!\addlinespace! command, with an alternative
+name \verb!\addrowspace!.
+You can specify the size of vertical space to be added in its optional
+argument, and the default size is determinted by \verb!\defaultaddspace!
+dimension, initially \verb!0.5em!.
 This command adds one half of the space to \verb!belowsep! of previous row,
 and the other half to \verb!abovesep! of current row.
 

tabularray.tex

@@ -209,7 +209,7 @@ \section{Vertical Space}
  Iota    & Kappa & Lambda & Mu    \\
 \hline
 \end{tblr}
-\end{demohigh} 
+\end{demohigh}
 
 But in many cases, this \verb!rowsep! is useful:
 
@@ -248,7 +248,7 @@ \section{Multiline Cells}
  {L \\ Left} & {C \\ Cent \\ Center} & R \\
 \hline
 \end{tblr}
-\end{demohigh} 
+\end{demohigh}
 
 \section{Cell Alignment}
 
@@ -264,7 +264,7 @@ \section{Cell Alignment}
  {Top Baseline \\ Left Left} & Middle Center & {Right Right \\ Bottom Baseline} \\
 \hline
 \end{tblr}
-\end{demohigh} 
+\end{demohigh}
 
 Note that you can use more meaningful \verb!t! instead of \verb!p! for top baseline alignment.
 For some users who are familiar with word processors,
@@ -418,7 +418,7 @@ \section{Multi Rows and Columns}
 \begin{demohigh}
 \begin{tblr}{|ll|c|rr|}
 \hline
- \SetCell[r=3,c=2]{h} r=3 c=2 & 1-2 & \SetCell[r=2,c=3]{r} r=2 c=3 & 1-4 & 1-5 \\ 
+ \SetCell[r=3,c=2]{h} r=3 c=2 & 1-2 & \SetCell[r=2,c=3]{r} r=2 c=3 & 1-4 & 1-5 \\
  2-1 & 2-2 & 2-3 & 2-4 & 2-5 \\
 \hline
  3-1 & 3-2 & MIDDLE & \SetCell[r=3,c=2]{f} r=3 c=2 & 3-5 \\
@@ -607,7 +607,7 @@ \section{Old and New Interfaces}
   \verb!\SetColumn!                              & \K{column}, \K{colspec} \\
 \end{newtblr}
 
-\section{Hlines and Vlines}
+\section{Hlines and Vlines}\label{sec:hlines-vlines}
 
 All available keys for hlines and vlines are described in Table \ref{key:hline} and Table \ref{key:vline}.
 
@@ -623,6 +623,9 @@ \section{Hlines and Vlines}
   \underline{\K{fg}}   & rule color name & \None \\
   \K{leftpos}          & crossing or trimming position at the left side  & \V{1} \\
   \K{rightpos}         & crossing or trimming position at the right side & \V{1} \\
+  \K{l}                & same as \K{leftpos}, default \V{-0.8} & \V{1} \\
+  \K{r}                & same as \K{rightpos}, default \V{-0.8} & \V{1} \\
+  \K{lr}               & crossing or trimming positions at both sides, default \V{-0.8} & \V{1} \\
   \K{endpos}           & adjust leftpos/rightpos for only the leftmost/rightmost column & \V{false} \\
 \end{spectblr}
 \vspace{-2em}
@@ -869,7 +872,7 @@ \subsection{Hlines and Vlines in Old Interfaces}
 \end{demohigh}
 
 Commands \verb!\SetHline! combines the usages of \verb!\hline! and \verb!\cline!:
- 
+
 \begin{demohigh}
 \begin{tblr}{llll}
 \SetHline{1-3}{blue5,1pt}
@@ -2471,8 +2474,11 @@ \section{Library \texttt{booktabs}}
 
 With \verb!\UseTblrLibrary{booktabs}! in the preamble of the document,
 \verb!tabularray! will load \verb!booktabs! package,
-and define \verb!\toprule!, \verb!\midrule!,
-\verb!\bottomrule! and \verb!\cmidrule! inside \verb!tblr! environment.
+and define
+  \verb!\toprule!, \verb!\midrule!, \verb!\bottomrule!,
+  \verb!\cmidrule!, \verb!\cmidrulemore!, \verb!\morecmidrules!,
+  \verb!\specialrule!, \verb!\addrowspace!, and \verb!\addlinespace!
+as table commands.
 
 \begin{demohigh}
 \begin{tblr}{llll}
@@ -2489,7 +2495,14 @@ \section{Library \texttt{booktabs}}
 \end{demohigh}
 
 Just like \verb!\hline! and \verb!\cline! commands,
-you can also specify rule width and color in the optional argument of any of these commands.
+you can also specify rule width and color by using hline keys in the optional
+argument of any of these commands.
+
+Like in \verb!booktabs!, by default
+  width of \verb!\toprule! and \verb!\bottomrule! are determined by \verb!\heavyrulewidth!,
+  width of \verb!\midrule! is determined by \verb!\lightrulewidth!, and
+  width of \verb!\cmidrule! and \verb!\cmidrulemore! are determined by \verb!\cmidrulewidth!, respectively.
+All three \verb!\...rulewidth! are dimensions.
 
 \begin{demohigh}
 \begin{tblr}{llll}
@@ -2503,7 +2516,10 @@ \section{Library \texttt{booktabs}}
 \end{tblr}
 \end{demohigh}
 
-If you need more than one \verb!\cmidrule!s, you can use \verb!\cmidrulemore! command.
+If you need more than one \verb!\cmidrule!s, you can use \verb!\cmidrulemore!
+command, which is simpler than the \verb!booktabs! usage
+\verb!\morecmidrules\cmidrule!.
+\verb!\cmidrulemore! can receive hline keys in an optional argument too.
 
 \begin{demohigh}
 \begin{tblr}{llll}
@@ -2517,8 +2533,11 @@ \section{Library \texttt{booktabs}}
 \end{tblr}
 \end{demohigh}
 
-From version 2021N (2021-09-01), trim options (\verb!l!, \verb!r!, \verb!lr!)
-for \verb!\cmidrule! command are also supported.
+From version 2021N (2021-09-01), you can set trimming positions of
+\verb!\cmidrule! and \verb!\cmidrulemore!, using newly introduced trimming
+options (\verb!leftpos!, \verb!rightpos!, \verb!endpos!, \verb!l!, \verb!r!,
+and \verb!lr!) (see Section~\ref{sec:hlines-vlines}).
+Option \verb!endpos! is already applied to these two commands.
 
 \begin{demohigh}
 \begin{tblr}{llll}
@@ -2532,11 +2551,10 @@ \section{Library \texttt{booktabs}}
 \end{tblr}
 \end{demohigh}
 
-Note that you need to put \verb!l!, \verb!r! or \verb!lr! option into
-the \underline{\color{red3}square brackets}.
-and the possible values are decimal numbers between \verb!-1! and \verb!0!,
-where \verb!-1! means trimming the whole colsep, and \verb!0! means no trimming.
-The default value is \verb!-0.8!, which makes similar result as \verb!booktabs! package does.
+Since \verb!booktabs! tables usually don't have vlines, the meaningful values
+here are decimal numbers between \verb!-1! and \verb!0!.
+The default value \verb!-0.8! for \verb!l!, \verb!r!, and \verb!lr! is chosen to
+make similar result as \verb!booktabs! package does.
 
 There is also a \verb!booktabs! environment for you. With this environment,
 the default \verb!rowsep=0pt!, but extra vertical space will be added by
@@ -2577,9 +2595,11 @@ \section{Library \texttt{booktabs}}
 \end{booktabs}
 \end{demohigh}
 
-At last, there is also an \verb!\addlinespace! command.
-You can specify the size of vertical space to be added in its optional argument,
-and the default size is \verb!0.5em!.
+At last, there is also an \verb!\addlinespace! command, with an alternative
+name \verb!\addrowspace!.
+You can specify the size of vertical space to be added in its optional
+argument, and the default size is determinted by \verb!\defaultaddspace!
+dimension, initially \verb!0.5em!.
 This command adds one half of the space to \verb!belowsep! of previous row,
 and the other half to \verb!abovesep! of current row.
 

testfiles/cell-001.tex

@@ -74,7 +74,7 @@
 
 \bigskip\hrule\bigskip
 
-%% h and t cells could align with t/m/b cells with strut 
+%% h and t cells could align with t/m/b cells with strut
 \BEGINTEST{normal cells: h/t/m/b/f cells with strut}
 \begin{tblr}{|Q[h]|Q[t]|Q[m]|Q[b]|Q[f]|}
 \hline

testfiles/hvline-003.tex

@@ -89,7 +89,7 @@
   vline{4} = {2}{abovepos=0,belowpos=1},
 }
   AAAAAA & BBBBB  & CCCCC  \\
-  AAAAA  & BBBBBB & CCCCCC 
+  AAAAA  & BBBBBB & CCCCCC
 \end{tblr}
 \quad
 \begin{tblr}{

testfiles/library-013.tex

@@ -22,7 +22,7 @@
 \zref@addprop{main}{table}
 \zref@addprop{main}{section}
 \zref@addprop{main}{subsection}
-\makeatother 
+\makeatother
 
 \begin{document}
 

testfiles/library-014.tex

@@ -22,14 +22,14 @@
 \BEGINTEST{testing delimiters} % issue #300
 Hello$\begin{tblr}{}
   alpha & beta \\
-  delta & gamma \\ 
+  delta & gamma \\
 \end{tblr}$World
 \qquad
 Hello$\begin{tblr}{
   delimiter = {left=[,right=]}
 }
   alpha & beta \\
-  delta & gamma \\ 
+  delta & gamma \\
 \end{tblr}$World
 \ENDTEST
 

testfiles/long-003.tex

@@ -30,7 +30,7 @@
 \hline
  \SetRow{purple7}
  Head & Head & Head \\
-\hline                               
+\hline
  \SetRow{purple7}
  Head & Head & Head \\
 \hline

testfiles/rowcol-004.tex

@@ -26,7 +26,7 @@
 \BEGINTEST{normal columns with large widths}
 \begin{tblr}{width=300pt,colspec=|l|Q[-1]|Q[-2]|Q[-5]|Q[-2]|l|Q[2]|Q[3]|l|}
 \hline
-\replicate{6}{\rule{10pt}{2pt}\hfil} & \rule{6pt}{2pt} & \rule{10pt}{2pt} & 
+\replicate{6}{\rule{10pt}{2pt}\hfil} & \rule{6pt}{2pt} & \rule{10pt}{2pt} &
 \rule{6pt}{2pt} & \rule{10pt}{2pt} & \replicate{7}{\rule{10pt}{2pt}\hfil} &
 \rule{10pt}{2pt} & \rule{6pt}{2pt} & \replicate{8}{\rule{10pt}{2pt}\hfil} \\
 \hline

testfiles/table-006.tex

@@ -17,16 +17,16 @@
 
 \BEGINTEST{testing \SetTblrDefault}
 \begin{tblr}{}
-  A & B \\ C & D 
+  A & B \\ C & D
 \end{tblr}
 \begingroup
   \SetTblrDefault{hlines,vlines,stretch=2}
   \begin{tblr}{}
-    A & B \\ C & D 
+    A & B \\ C & D
   \end{tblr}
 \endgroup
 \begin{tblr}{}
-  A & B \\ C & D 
+  A & B \\ C & D
 \end{tblr}
 \ENDTEST