summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/nicematrix/nicematrix.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/nicematrix/nicematrix.tex')
-rw-r--r--macros/latex/contrib/nicematrix/nicematrix.tex230
1 files changed, 170 insertions, 60 deletions
diff --git a/macros/latex/contrib/nicematrix/nicematrix.tex b/macros/latex/contrib/nicematrix/nicematrix.tex
index b2da527927..cec4b584ca 100644
--- a/macros/latex/contrib/nicematrix/nicematrix.tex
+++ b/macros/latex/contrib/nicematrix/nicematrix.tex
@@ -511,16 +511,17 @@ $\begin{bNiceArray}{cw{c}{1cm}c|c}[margin]
\interitem
In fact, the command |\Block| accepts as first optional argument (between
-square brackets) a list of couples \textsl{key=value}. The available keys are as
-follows:
+square brackets) a list of couples \textsl{key=value}.
+
+First, there are keys which are quick tools to control the apperance of the block.
+
\begin{itemize}
\item \index{fill (key of \texttt{\textbackslash Block})}
the key \Definition{fill} takes in as value a color and fills the block
with that color;
\item \index{opacity (key of \texttt{\textbackslash Block})}
-\colorbox{yellow!50}{\bfseries New 6.22}\enskip the key
-\Definition{opacity} sets the opacity of
-the filling color specified by |fill|;
+the key \Definition{opacity} sets the opacity of the filling color specified by
+|fill|;
\item \index{draw (key of \texttt{\textbackslash Block})}
the key \Definition{draw} takes in as value a color and strokes the
frame of the block with that color (the default value of that key is the
@@ -546,14 +547,50 @@ only when one of the keys |draw|, |hvlines|, |vlines| and |hlines| is used);
the key \Definition{rounded-corners} requires rounded corners (for the
frame drawn by |draw| and the shape drawn by |fill|) with a radius equal to
the value of that key (the default value is 4~pt\footnote{This value is the
-initial value of the \emph{rounded corners} of Tikz.});
+initial value of the \emph{rounded corners} of Tikz.}).
+\end{itemize}
+
+\medskip
+Sometimes, these tools are not sufficient to control the appearance of the
+block. The following keys are more powerful but also more difficult to use.
+Moreover, the require the loading of TikZ by the user (with
+|\usepackage{tikz}|). By default, \pkg{nicematrix} does not load TikZ but only
+\textsc{pgf}, which is a sublayer of TikZ.
+
+\begin{itemize}
+\item \index{borders (key of \texttt{\textbackslash Block})}
+\index{tikzz@tikz!key of ``borders'' de \texttt{\textbackslash Block}}
+The key \Definition{borders} provides the ability to draw only some
+borders of the blocks; the value of that key is a (comma-separated) list of
+elements covered by |left|, |right|, |top| and |bottom|; it's possible, in
+fact, in the list which is the value of the key |borders|, to add an entry of
+the form |tikz={|\textsl{list}|}| where \textsl{list} is a list of couples
+\textsl{key=value} of Tikz specifying the graphical characteristics of the
+lines that will be drawn (for an example, see p.~\pageref{dashed}).
+
\item \index{tikzz@tikz!key of \texttt{\textbackslash Block}}
-when the key \Definition{tikz} is used, the Tikz path corresponding of
+When the key \Definition{tikz} is used, the Tikz path corresponding of
the rectangle which delimits the block is executed with Tikz\footnote{Tikz
should be loaded (by default, \pkg{nicematrix} only loads \textsc{pgf}) and,
if it's not, an error will be raised.} by using as options the value of that
-key |tikz| (which must be a list of keys allowed for a Tikz path). For
-examples, cf. p.~\pageref{tikz-key-examples};
+key |tikz| (which must be a list of keys allowed for a Tikz path).
+
+\colorbox{yellow!50}{\textbf{New 6.24}}\enskip In fact, in the list of the keys
+provided by the user as value of |tikz|, it's possible to put a key |offset|.
+That key is not provided by TikZ but by \pkg{nicematrix}. It will narrow the
+rectangular frame corresponding to the block by a margin (horizontally and
+vertically) equal to the value (of that key |offset|). That new frame, a bit
+narrower, will be executed by TikZ with options which are the other keys in the
+list of keys provided as value to the key |tikz| of |\Block|.
+
+For examples, cf. p.~\pageref{tikz-key-examples}.
+\end{itemize}
+
+
+\medskip
+There is also some technical keys:
+
+\begin{itemize}
\item \index{name!key of \texttt{\textbackslash Block}}
the key \Definition{name} provides a name to the rectangular Tikz node
corresponding to the block; it's possible to use that name with Tikz in the
@@ -562,15 +599,6 @@ corresponding to the block; it's possible to use that name with Tikz in the
the key \Definition{respect-arraystretch} prevents the setting of
|\arraystretch| to $1$ at the beginning of the block (which is the behaviour
by default) ;
-\item \index{borders (key of \texttt{\textbackslash Block})}
-\index{tikzz@tikz!key of ``borders'' de \texttt{\textbackslash Block}}
-the key \Definition{borders} provides the ability to draw only some
-borders of the blocks; the value of that key is a (comma-separated) list of
-elements covered by |left|, |right|, |top| and |bottom|; it's possible, in
-fact, in the list which is the value of the key |borders|, to add an entry of
-the form |tikz={|\textsl{list}|}| where \textsl{list} is a list of couples
-\textsl{key=value} of Tikz specifying the graphical characteristics of the
-lines that will be drawn (for an example, see p.~\pageref{dashed}).
\item \index{transparent (key of \texttt{\textbackslash Block})}
By default, the rules are not drawn in the blocks (see the section about
the rules: section~\ref{rules} p.~\pageref{rules}). However, if the key
@@ -1112,7 +1140,8 @@ is equivalent to |\cline{|\textsl{\texttt{i}}|-|\textsl{\texttt{i}}|}|.
The environments of \pkg{nicematrix} provide a key |rules/width| to set the
width (in fact the thickness) of the rules in the current environment. In
-fact, this key merely sets the value of the length |\arrayrulewidth|.
+fact, this key merely sets the value of the standard LaTeX length
+|\arrayrulewidth|.
\smallskip
It's well known that \pkg{colortbl} provides the command |\arrayrulecolor| in
@@ -1120,12 +1149,12 @@ order to specify the color of the rules.
\smallskip
\indexcommand{arrayrulecolor}
-With \pkg{nicematrix}, it's possible to specify the color of the rules even
-when \pkg{colortbl} is not loaded. For sake of compatibility, the command is
-also named |\arrayrulecolor|. The environments of \pkg{nicematrix} also
-provide a key |rules/color| to fix the color of the rules in the current
-environment. This key sets the value locally (whereas |\arrayrulecolor| acts
-globally!).
+With \pkg{nicematrix}, it's possible to specify the color of the rules even when
+\pkg{colortbl} is not loaded. For sake of compatibility, the command is also
+named |\arrayrulecolor|. However, \pkg{nicematrix} also provides a key
+|rules/color|, available in |\NiceMatrixOptions| or in an individual
+environment, to fix the color of the rules. This key sets the value locally
+(whereas |\arrayrulecolor| acts globally!) and should be prefered.
\medskip
\begin{scope}
@@ -1148,7 +1177,10 @@ muguet & dahlia & souci \\
\end{NiceTabular}
\end{scope}
-
+\medskip
+In fact, in that example, instead of |\hline|, it would have a better choice to
+use |\Hline|, provided by \pkg{nicematrix} and described just below, because it
+ensures a better output in the PDF viewers at the low levels of zoom.
\subsection{The tools of nicematrix for the rules}
@@ -1180,22 +1212,21 @@ p.~\pageref{corners}).
\item For the exterior rows and columns, see~p.~\pageref{exterior}.
\end{itemize}
-In particular, this remark explains the difference between the standard
+In particular, this remark exhibits a first difference between the standard
command |\hline| and the command |\Hline| provided by \pkg{nicematrix}.
-The key |\Hline| takes in an optional argument (between square brackets) which
-is a list of \textsl{key=value} pairs. For the description of those keys, see
-|custom-line| on p.~\pageref{custom-line}.\footnote{Technical remark: If the
- user wants to write a command over the command |\Hline|, it shall be ensured
- that this new command is expandable in the TeX sens (by using, for instance,
- |\NewExpandableDocumentCommand| of LaTeX3, |\newcommand| of LaTeX or |\def| of
- TeX). Example: |\newcommand{\RedLine}{\Hline[color=red]}|}
+Moreover, the key |\Hline| takes in an optional argument (between square
+brackets) which is a list of \textsl{key=value} pairs. For the description of
+those keys, see |custom-line| on p.~\pageref{custom-line}.\footnote{Technical
+ remark: If the user wants to write a command over the command |\Hline|, it
+ shall be ensured that this new command is expandable in the TeX sens (by
+ using, for instance, |\NewExpandableDocumentCommand| of LaTeX3, |\newcommand|
+ of LaTeX or |\def| of TeX). Example:
+ |\newcommand{\RedLine}{\Hline[color=red]}|}
\bigskip
-\colorbox{yellow!50}{\textbf{New 6.23}}\enskip
-
-As well as the command |\Hline|, the specifier ``\verb+|+'' supports a optional
+As well as the command |\Hline|, the specifier ``\verb+|+'' supports an optional
argument between square brackets for the characteristics of the rule.
\medskip
@@ -1472,8 +1503,11 @@ to specify a vertical rule.
\bigskip
We will now speak of the keys which describe the rule itself. Those keys may
-also be used in the (optional) argument of an individual command |\Hline|.
+also be used in the (optional) argument of an individual command |\Hline| or in
+the (optional) argument of a specifier ``\verb+|+'' in the preamble of an
+environment.
+\bigskip
There is three possibilities.
\begin{itemize}
@@ -1775,6 +1809,10 @@ cf.~p.~\pageref{nodes-i}.}
\index{arraycolor@\texttt{\textbackslash arraycolor} (command of \texttt{\textbackslash
CodeBefore)}}
+The names of these commands are inspired by the names of the commands provided
+by \pkg{colortbl}.
+
+
\medskip
These commands don't color the cells which are in the ``corners'' if the key
|corners| is used. That key has been described p.~\pageref{corners}.
@@ -2263,9 +2301,9 @@ with the same syntax as the corresponding command of
\pkg{colortbl} (however, unlike the command |\columncolor| of \pkg{colortbl},
this command |\columncolor| can appear within another command, itself used in the
preamble of the array);
-\item \colorbox{yellow!50}{\textbf{New 6.21}}\enskip |\rowcolors| which takes in as arguments two colors and color the rest of
+\item |\rowcolors| which takes in as arguments two colors and color the rest of
the tabular with those colors;
-\item \colorbox{yellow!50}{\textbf{New 6.21}}\enskip |\rowlistcolors| which takes in as argument a color and color the rest of
+\item |\rowlistcolors| which takes in as argument a color and color the rest of
the tabular with the colors of that list of colors.\footnote{When the command
|\rowlistcolors| (or the command |\rowcolors| is used in a cell of the
column~$j$ of the array, the command applies only on the columns above~$j$ (by
@@ -2519,10 +2557,7 @@ parameter is |\linewidth| (and not |\textwidth|).
For sake of similarity with the environment |{tabularx}|, \pkg{nicematrix}
also provides an environment |{NiceTabularX}| with a syntax similar to the
syntax of |{tabularx}|, that is to say with a first mandatory argument
-which is the width of the tabular.\footnote{If \pkg{tabularx} is loaded, one
-must use |{NiceTabularX}| (and not |{NiceTabular}|) in order to use the
-columns |X| (this point comes from a conflict in the definitions of the
-specifier |X|).}
+which is the width of the tabular.
As with the packages \pkg{tabu}\footnote{The extension \pkg{tabu} is now
considered as deprecated.} and \pkg{tabularray}, the specifier |X| takes
@@ -3189,10 +3224,10 @@ p.~\pageref{line-in-code-after}) accept two optional arguments specified by the
tokens |_| and |^| for labels positionned below and above the line. The
arguments are composed in math mode with |\scriptstyle|.
-\colorbox{yellow!50}{\textbf{New 6.22}}\enskip The version 6.22 introduces a new
-label, specified by the token ``|:|'' for a label placed on the line. The label
-is composed on a white background which is put on the line previously drawn (see
-example on p.~\pageref{ex:colon}).
+The version 6.22 of \pkg{nicematrix} has introduced a new label, specified by
+the token ``|:|'' for a label placed on the line. The label is composed on a
+white background which is put on the line previously drawn (see example on
+p.~\pageref{ex:colon}).
\bigskip
\begin{BVerbatim}[baseline=c,boxwidth=10cm]
@@ -3269,8 +3304,8 @@ For the clarity of the explanations, we will use those names.
\bigskip
-With the key \Definition{xdots/horizontal-labels}, the labels (introduced by |_|
-and |^|) stay horizontal.
+With the key \Definition{xdots/horizontal-labels}, the labels (introduced by~|_|,
+|^| and~|:|) stay horizontal.
\bigskip
The option \Definition{xdots/color} fixes the color or the dotted line. However,
@@ -3498,7 +3533,8 @@ beginning on p.~\pageref{PGF-nodes}.
\medskip
Moreover, several special commands are available in the |\CodeAfter|: |line|,
-|\SubMatrix|, |\OverBrace| and |\UnderBrace|. We will now present these commands.
+|\SubMatrix|, |\OverBrace|, |\UnderBrace| and |\TikzEveryCell|. We will now
+present these commands.
\subsection{The command \textbackslash line in the \textbackslash CodeAfter}
@@ -3914,7 +3950,7 @@ $\begin{pNiceMatrix}
\end{pNiceMatrix}$
\bigskip
-Caution : There is no vertical space reserved for those braces.\footnote{See:
+Caution : There is no vertical space reserved for those braces and their labels.\footnote{See:
\url{https://tex.stackexchange.com/questions/685755}}
@@ -3964,6 +4000,72 @@ $\begin{pNiceMatrix}
\OverBrace[shorten,yshift=3pt]{1-4}{2-6}{B}
\end{pNiceMatrix}$
+
+\subsection{The command \textbackslash TikzEveryCell in the \textbackslash
+ CodeAfter}
+
+
+\index{SubMatrix@\texttt{\textbackslash TikzEveryCell} (command of
+\texttt{\textbackslash CodeAfter}\newline and
+\texttt{\textbackslash CodeBefore})|textbf}
+
+
+
+\colorbox{yellow!50}{\textbf{New 6.24}}\enskip The command |\TikzEveryCell|
+execute with TikZ the rectangular path corresponding to each cell of the tabular
+with parameters of TikZ the argument of |\TikzEveryCell|. That argument must be
+a list of \textsl{key=value} pairs which may be applied to a Tikz path. In fact,
+the command applies to each of the tabular, except those in the exterior rows
+and columns (cf.~p.~\pageref{exterior}) and those in the empty corners (when the
+key |corners| is used: cf.~p.~\pageref{corners}). It applies in fact to each
+block (excepted those with the key |transparent|) and does not apply to the
+cells located within these blocks.
+
+\medskip
+In fact, in the list of keys provided as argument of |\TikzEveryCell|, it's
+possible to put a key |offset|. That key is not provided by TikZ but by
+\pkg{nicematrix}. It will narrow the rectangular frame corresponding to the
+block by a margin (horizontally and vertically) equal to the value (of that key
+|offset|). That new frame, a bit narrower, will be executed by TikZ with options
+which are the other keys in the argument of |\TikzEveryCell|.
+
+\medskip
+\begingroup
+\bigskip
+\begin{BVerbatim}[baseline=c,boxwidth=9cm]
+\renewcommand{\arraystretch}{1.3}
+\begin{NiceTabular}{ccc}[corners]
+ & \Block{1-2}{columns} \\
+ \Block{2-1}{rows}
+ & cell 1 1 & cell 1 2 \\
+ & cell 2 1 & cell 2 2
+\CodeAfter
+ ~emphase#\TikzEveryCell{offset=1pt,draw}@
+\end{NiceTabular}
+\end{BVerbatim}
+\renewcommand{\arraystretch}{1.3}
+\begin{NiceTabular}{ccc}[corners]
+ & \Block{1-2}{columns} \\
+ \Block{2-1}{rows}
+ & cell 1 1 & cell 1 2 \\
+ & cell 2 1 & cell 2 2
+\CodeAfter
+ \TikzEveryCell{offset=1pt,draw}
+\end{NiceTabular}
+\endgroup
+
+\bigskip
+The command |\TikzEveryCell| has two keys:
+\begin{itemize}
+\item with the key \Definition{empty}, the command only acts on the empty cells;
+
+\item with key \Definition{non-empty}, the command only acts on the non-empty cells.
+\end{itemize}
+
+\medskip
+The commmand |\TikzEveryCell| is, in fact, also available in the |\CodeBefore|.
+
+
\index{CodeAfter@\texttt{\textbackslash CodeAfter}|)}
\section{Captions and notes in the tabulars}
@@ -4421,9 +4523,9 @@ exterior rules.}
\end{itemize}
-\colorbox{yellow!50}{New 6.21}\enskip That key is available in all
-the environments and commands (e.g. |\pAutoNiceMatrix|) of \pkg{nicematrix} and also
-in the command |\NiceMatrixOptions|.
+That key is available in all the environments and commands (e.g.
+|\pAutoNiceMatrix|) of \pkg{nicematrix} and also in the command
+|\NiceMatrixOptions|.
\bigskip
\begin{BVerbatim}[baseline=c,boxwidth=9cm]
@@ -4616,10 +4718,9 @@ $A = \begin{pNiceMatrix}[last-row=4,last-col=4]
\end{varwidth}
\bigskip
-\colorbox{yellow!50}{\textbf{New 6.21}}\enskip The command |\rotate| has a key
-|c|: |\rotate[c]| (spaces are deleted after |\rotate[c]|). When that key is
-used, the content is composed in a |\vcenter| and, therefore, in most cases, we
-will have a vertical alignment.
+The command |\rotate| has a key |c|: |\rotate[c]| (spaces are deleted after
+|\rotate[c]|). When that key is used, the content is composed in a |\vcenter|
+and, therefore, in most cases, we will have a vertical alignment.
\bigskip
Caution: the command |\rotate| is designed to be used in a |\Block| or in
@@ -6961,6 +7062,15 @@ The successive versions of the file |nicematrix.sty| provided by TeXLive are ava
\nolinkurl{https:www.tug.org/svn/texlive/trunk/Master/texmf-dist/tex/latex/nicematrix/nicematrix.sty}
}
+
+\subsection*{Changes between version 6.23 and 6.24}
+
+New command |\TikzEveryCell| available in the |\CodeAfter| and the |\CodeBefore|
+to apply the same TikZ instruction to all the cells and blocks of the array.
+
+New key |offset| in the key |tikz| of a command |\Block|.
+
+
\subsection*{Changes between version 6.22 and 6.23}
The specifier ``\verb+|+'' in the preambles of the environments has now an
@@ -6982,7 +7092,7 @@ Key |c| for the command |\tabularnote|.
New commands |\rowcolors| and |\rowlistcolors| available in the array itself
(previously, there were only two commands |\rowcolors| and |\rowlistcolors|
-avaailable in the |\CodeBefore|.
+available in the |\CodeBefore|.
\subsection*{Changes between version 6.20 and 6.20a}