diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/nicematrix/nicematrix.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/nicematrix/nicematrix.tex | 254 |
1 files changed, 194 insertions, 60 deletions
diff --git a/Master/texmf-dist/doc/latex/nicematrix/nicematrix.tex b/Master/texmf-dist/doc/latex/nicematrix/nicematrix.tex index 35de3000996..a3a6f548c24 100644 --- a/Master/texmf-dist/doc/latex/nicematrix/nicematrix.tex +++ b/Master/texmf-dist/doc/latex/nicematrix/nicematrix.tex @@ -486,8 +486,7 @@ If this argument is empty, its default value is |1-1|. If the number of rows is not specified, or equal to |*|, the block extends until the last row (idem for the columns). -\item The second argument is the content of the block. It's possible to use -|\\| in that content to have a content on several lines. In |{NiceTabular}|, +\item The second argument is the content of the block. In |{NiceTabular}|, |{NiceTabular*}| and |{NiceTabularX}|, the content of the block is composed in text mode whereas, in the other environments, it is composed in math mode. \end{itemize} @@ -614,13 +613,13 @@ 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). -\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 -\Definition{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|. +In fact, in the list of the keys provided by the user as value of |tikz|, it's +possible to put a key \Definition{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} @@ -694,9 +693,10 @@ In the columns with a fixed width (columns |w{...}{...}|, |W{...}{...}|, formatted as a paragraph of that width. \item The specification of the horizontal position provided by the type of -column (|c|, |r| or |l|) is taken into account for the blocks (but the -|\Block| may have its own specification of alignment: -cf.~\ref{horizontal-block} p.~\pageref{horizontal-block}). +column (|c|, |r| or |l|) is taken into account for the blocks. For a block in a +column ot type |p{...}| (without option for |p|) , the alignment |c| will be +used for the block. Of course, the |\Block| may have its own specification of +alignment: cf.~\ref{horizontal-block} p.~\pageref{horizontal-block}. \item The specifications of font specified for the column by a construction |>{...}| in the preamble of the array are taken into account for the @@ -800,8 +800,8 @@ first mandatory argument of |\Block| is |1-1|.} \label{horizontal-block} -The command |\Block| accepts the keys |l|, |c| and |r| for the horizontal -position of its content. +The command |\Block| accepts the keys \Definition{l}, \Definition{c} and +\Definition{r} for the horizontal position of its content. \medskip \begin{Code}[width=10.6cm] @@ -863,10 +863,10 @@ Rank & \Block{1-3}{First group} & & & \Block{1-3}{Second group} \\ \end{center} \medskip -In order to have an horizontal positionning of the content of the block -computed with the limits of the columns of the LaTeX array (and not with the -contents of those columns), one may use the key |L|, |R| and |C| of the -command |\Block|. +In order to have an horizontal positionning of the content of the block computed +with the limits of the columns of the LaTeX array (and not with the contents of +those columns), one may use the key \Definition{L}, \Definition{R} and +\Definition{C} of the command |\Block|. \medskip Here is the same example with the key |C| for the first block. @@ -904,6 +904,16 @@ Rank & \Block[C]{1-3}{First group} & & & \Block{1-3}{Second group} \\ \end{center} +\bigskip +\colorbox{yellow!50}{\bfseries New 6.28}\par\nobreak + +\smallskip +The command |\Block| supports also a key |p|. With that key, the content of the +block is formatted like a paragraph (as in a column of type |p|). That key may +be used in conjunction with the key |l|, |c| or |r|, and, in that case, the +paragraph is formatted with |\raggedright|, |\centering| or |\raggedleft|. With +the key |j|, the paragraph is justified. + \subsection{Vertical position of the content of the block} \label{vertical-pos-block} @@ -925,7 +935,8 @@ array involved in the block. No vertical margin is added. However, the contents of the block is (always) composed by \pkg{nicematrix} in a |{minipage}|, a |{tabular}| or an |{array}| -and, hence, there will still remain a margin (in most cases). +and, hence, there will still remain a margin (in most cases). If needed, it's +always possible to add a |\strut|... \item With the key \Definition{B}, the content of the block is set downwards. \end{itemize} @@ -1028,6 +1039,61 @@ text & text \\ \end{scope} +\subsection{\textbackslash\textbackslash\ and \& in the blocks} + +\index{ampersand-in-blocks} + +\colorbox{yellow!50}{\bfseries New 6.28}\par\nobreak + +The extension \pkg{nicemtrix} provides the ability to use |\\| and |&| directly +in the content of a block (in order to format its contents) but there is some rectrictions. + +\begin{itemize} +\item One must not use both |\\| and |&| in the same block. + +\item For |\\|, there is no other restriction. It's possible to use |\\| in a +block to format a text on several rows. + +\item In order to use |&|, the key |ampersand-in-blocks| must been activated. Then, +the block is divided in sub-blocks as illustrated below. Be careful: with +|ampersand-in-blocks| is in force, the (main) argument of the command |\Block| +is syntactically divided into sub-blocks by splitting on the ampersands~|&|, the +ampersands between curly braced are protected but not those in an +environment.\footnote{It's not possible to write + |\Block[ampersand-in-blocks]{}{\begin{array}{cc}1&2\end{array}}|. Of course, + it's possible without the key |ampersand-in-blocks|.} +\end{itemize} + +When the key |ampersand-in-blocks| +As we can see, the blocks (which was are in fact mono-cell blocks) are divided +into sub-blocks of the same size. However, maybe the following code would be prefered. + +\medskip +\begin{Code}[width=85mm] +\begin{NiceTabular}{lccccc}% + [hvlines,ampersand-in-blocks] + & \Block{1-5}{the five first + natural numbers} \\ +3 & \Block{1-5}{one & two & three} \\ +4 & \Block{1-5}{one& two & three & four} \\ +5 & one & two & three & four & five \\ +\end{NiceTabular} +\end{Code} +% +\begin{NiceTabular}{lccccc}% + [hvlines,ampersand-in-blocks] + & \Block{1-5}{the five first natural numbers} \\ +3 & \Block{1-5}{one & two & three} \\ +4 & \Block{1-5}{one& two & three & four} \\ +5 & one & two & three & four & five \\ +\end{NiceTabular} + +\medskip +In this code, we have blocks of size |1-5| which are divided into three or four +sub-blocks. + + + \index{Blocks@\textbf{Blocks in the tabulars}|)} @@ -1264,7 +1330,7 @@ argument between square brackets for the characteristics of the rule. \medskip \begin{Code}[width=10cm] -\begin{NiceTabular}{|c\emph{|[color=blue]}c|} +\begin{NiceTabular}{ | c \emph{|[color=blue]} c |} \Hline a & b \\ \emph{\Hline[color=red]} @@ -1587,7 +1653,8 @@ created by |\hline\hline| or \verb+||+ in the preamble of an environment; \item the key |color| sets the color of the rules ; \item the key |sep-color| sets the color between two successive rules (should be -used only in conjonction with |multiplicity|). +used only in conjonction with |multiplicity|). The name of that key is inspired +by the command |\doublerulesepcolor| of \pkg{colortbl}. \end{itemize} \medskip @@ -1625,6 +1692,51 @@ Product C & 5 & 4 & 1 \\ \bigskip +The key |sep-color| with the value |white| may also be used in case of an +horizontal double-rule on the top of a colored cell (if we want the space +between both rules above the cell not colored by the color of the cell). + +\begin{scope} +\NiceMatrixOptions + { + custom-line = + { + command = DoubleRule , + multiplicity = 2 , + sep-color = white + } + } + + +\begin{Code}[width=10cm] +\NiceMatrixOptions + { + custom-line = + { + command = DoubleRule , + multiplicity = 2 , + \emph{sep-color = white} + } + } + +\begin{NiceTabular}{ccc}[color-inside] +one & two & three \\ +\emph{\DoubleRule} +four & \cellcolor{yellow} five & six \\ +\end{NiceTabular} +\end{Code} +\begin{NiceTabular}{ccc}[color-inside] +one & two & three \\ +\DoubleRule +four & \cellcolor{yellow} five & six \\ +\end{NiceTabular} + +\end{scope} + + + + +\bigskip \item \emph{Second possibility}\par\nobreak \index{tikzz@tikz!key of ``custom-line''} @@ -1682,7 +1794,7 @@ seven & eight & nine \end{scope} \bigskip -\item \emph{Third possibility} : the key |dotted| +\item \emph{Third possibility} : the key \Definition{dotted} \label{dotted} \index{dotted (key of ``custom-line'')} \indexcommand{hdottedline} @@ -1696,15 +1808,15 @@ value of the key |total-width| is, in this case, equal to the diameter of the do dotted rules are also used by \pkg{nicematrix} to draw continuous dotted rules between cells of the matrix with |\Cdots|, |\Vdots|, etc. (cf. p.~\pageref{Cdots}). -In fact, \pkg{nicematrix} defines by default the commands |\hdottedline| and -|\cdottedline |and the letter ``|:|'' for those dotted -rules.\footnote{However, it's possible to overwrite those definitions with a -|custom-line| (in order, for example, to switch to dashed lines).} +In fact, \pkg{nicematrix} defines by default the commands +\Definition{hdottedline} and \Definition{cdottedline} and the letter ``|:|'' for +those dotted rules.\footnote{However, it's possible to overwrite those + definitions with a |custom-line| (in order, for example, to switch to dashed + lines).} \smallskip \begin{Code} - -\NiceMatrixOptions % \textsl{present in nicematrix.sty} +\NiceMatrixOptions \emph{% \textsl{present in nicematrix.sty}} { custom-line = { @@ -2453,14 +2565,13 @@ Dupont & Chantal & 15 janvier 1998 \\ \end{center} \bigskip -\colorbox{yellow!50}{\textbf{New 6.25}}\enskip Each use of the command -|\rowlistcolors| (or |\rowcolors|, which is, in fact, a special case of -|\rowlistcolors|) stops the potential coloring schemes\footnote{We say - \emph{schemes} in plural form because it's possible to start simultaneously - several coloring schemes if they apply on different columns.} specified by a -previous command |\rowlistcolors|. In particular, it's possible to start -coloring the rows with |\rowlistcolors{...}| and stop coloring by a command -|\rowlistcolors| with an empty argument. +Each use of the |\rowlistcolors| (or |\rowcolors|, which is, in fact, a +special case of |\rowlistcolors|) stops the potential coloring +schemes\footnote{We say \emph{schemes} in plural form because it's possible to + start simultaneously several coloring schemes if they apply on different + columns.} specified by a previous command |\rowlistcolors|. In particular, +it's possible to start coloring the rows with |\rowlistcolors{...}| and stop +coloring by a command |\rowlistcolors| with an empty argument. \bigskip \begin{Code}[width=10cm] @@ -2493,10 +2604,9 @@ seven \\ \index{nocolor} -\colorbox{yellow!50}{\textbf{New 6.26}}\enskip The extension \pkg{nicematrix} -provides the special color |nocolor| which may be used in all the coloring -commands provided by \pkg{nicematrix} (in the |\CodeBefore| or the array -itself). +The extension \pkg{nicematrix} provides the special color |nocolor| which may be +used in all the coloring commands provided by \pkg{nicematrix} (in the +|\CodeBefore| or the array itself). The cells marked by this color won't be colored, whatever the other instructions of coloring which may apply to these cells. @@ -2686,7 +2796,7 @@ $\begin{array}{c} \end{bNiceMatrix} \\ \\ \begin{bNiceMatrix} 1 & 1245345 \\ 345 & 2 -\end{bNiceMatrix} +\end{bNiceMatrix} \\ \end{array}$ \emph{\end{NiceMatrixBlock}} \end{Code} @@ -2697,7 +2807,7 @@ $\begin{array}{c} \end{bNiceMatrix} \\ \\ \begin{bNiceMatrix} 1 & 1245345 \\ 345 & 2 -\end{bNiceMatrix} +\end{bNiceMatrix} \\ \end{array}$ \end{NiceMatrixBlock} @@ -4198,9 +4308,8 @@ $\begin{pNiceMatrix} \index{empty (key of \texttt{\textbackslash TikzEveryCell})} \index{non empty (key of \texttt{\textbackslash TikzEveryCell})} - -\colorbox{yellow!50}{\textbf{New 6.24}}\enskip The command |\TikzEveryCell| -execute with TikZ the rectangular path corresponding to each cell of the tabular +The command |\TikzEveryCell| +executes 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 @@ -5089,9 +5198,9 @@ environment of LaTeX which only put TeX commands before and after the content.} \medskip \index{light-syntax-expanded} -\colorbox{yellow!50}{\textbf{New 6.27}}\enskip The key |light-syntax-expanded| -has the same behaviour as the key |light-syntax| but the body of the -environment is expanded (in the TeX sens\footnote{More precisely, it's a + +The key |light-syntax-expanded| has the same behaviour as the key |light-syntax| +but the body of the environment is expanded (in the TeX sens\footnote{More precisely, it's a expansion of type |e| of L3.}) before being splitted in lines (but after the extraction of a potential |\CodeAfter|). @@ -5649,9 +5758,14 @@ The package \pkg{nicematrix} creates a PGF/TikZ node merely called $i$ (with the classical prefix) at the intersection of the horizontal rule of number~$i$ and the vertical rule of number~$i$ (more specifically the potential position of those rules because maybe there are not actually drawn). The last node has -also an alias called |last|. There is also a node called $i$|.5| midway -between the node $i$ and the node $i+1$. +also an alias called |last|. +\smallskip +\colorbox{yellow!50}{\bfseries Modification 6.28}\enskip There are also nodes +called $i$|.1|, $i$|.2|, … , $i$|.9| between the node~$i$ and the node~$i+1$ +(before the version 6.28, there was only the node $i$|.5|). + +\smallskip These nodes are available in the |\CodeBefore| and the |\CodeAfter|. \begin{center} @@ -6054,10 +6168,20 @@ environments of \pkg{nicematrix} are not affected). \index{Incompatibilities} The package \pkg{nicematrix} is not compatible with the class \cls{ieeeaccess} -(because that class is not compatible with PGF/TikZ).\footnote{See - \url{https://tex.stackexchange.com/questions/528975/error-loading-tikz-in-ieeeaccess-class}} +because that class is not compatible with PGF/TikZ. However, there is a simple +workaround by writing:\footnote{See + \url{https://tex.stackexchange.com/questions/528975/error-loading-tikz-in-ieeeaccess-class}}\par\nobreak + +\begin{Code} +\let\TeXyear\year +\documentclass{IEEEaccess} +\let\year\TeXyear +\end{Code} + + \bigskip +% the following requirement is still in force on April 23, 2024 In order to use \pkg{nicematrix} with the class \cls{aastex631} (of the \emph{American Astronomical Society}), you have to add the following lines in the preamble of your document : @@ -6089,7 +6213,7 @@ may be wrong in some circonstances. \bigskip The package \pkg{nicematrix} is not fully compatible with the package \pkg{arydshln} (because this package redefines many internals of \pkg{array}) -and does support the columns~|V| of \pkg{boldline} (because the letter |V| is +and does not support the columns~|V| of \pkg{boldline} (because the letter |V| is reserved for the columns~|V| of \pkg{varwidth}). By any means, \pkg{nicematrix} provides, with the key |custom-line| (cf. part~\ref{custom-line}, p.~\pageref{custom-line}), tools to draw dashed rules and rules of different @@ -6621,7 +6745,7 @@ with the environment |{NiceMatrixBlock}| and its option |auto-columns-width|. last-col, code-for-last-col = \color{blue}\scriptstyle, vlines = 5 , matrix/columns-type = r , - no-cell-nodes + no-cell-nodes % only for speedup } \setlength{\extrarowheight}{1mm} @@ -6720,7 +6844,7 @@ composed with the maximal width, thanks to the boolean key last-col, code-for-last-col = \color{blue}\scriptstyle, vlines = 5 , matrix/columns-type = r , - no-cell-nodes + no-cell-nodes % only for speedup } \setlength{\extrarowheight}{1mm} @@ -6933,14 +7057,14 @@ the command |\Block| is left empty, that means that the block is a mono-cell blo \begin{Code} -$\begin{pNiceArray}{>{\strut}cccc}[margin,rules/color=blue] +$\begin{pNiceArray}{>{\strut}cccc}[margin,rules/color=blue,no-cell-nodes] \emph{\Block[draw]{}{a_{11}}} & a_{12} & a_{13} & a_{14} \\ a_{21} & \Block[draw]{}{a_{22}} & a_{23} & a_{24} \\ a_{31} & a_{32} & \Block[draw]{}{a_{33}} & a_{34} \\ a_{41} & a_{42} & a_{43} & \Block[draw]{}{a_{44}} \\ \end{pNiceArray}$ \end{Code} -\[\begin{pNiceArray}{>{\strut}cccc}[margin,rules/color=blue] +\[\begin{pNiceArray}{>{\strut}cccc}[margin,rules/color=blue,no-cell-nodes] \Block[draw]{}{a_{11}} & a_{12} & a_{13} & a_{14} \\ a_{21} & \Block[draw]{}{a_{22}} & a_{23} & a_{24} \\ a_{31} & a_{32} & \Block[draw]{}{a_{33}} & a_{34} \\ @@ -6966,7 +7090,8 @@ used−even when \pkg{colortbl} is not loaded). \medskip \begin{Code} -\begin{pNiceArray}{>{\strut}cccc}[margin, extra-margin=2pt,color-inside] +\begin{pNiceArray}{>{\strut}cccc}% <-- % mandatory + [margin, extra-margin=2pt,color-inside,no-cell-nodes] \emph{\rowcolor{red!15}}A_{11} & A_{12} & A_{13} & A_{14} \\ A_{21} & \emph{\rowcolor{red!15}}A_{22} & A_{23} & A_{24} \\ A_{31} & A_{32} & \emph{\rowcolor{red!15}}A_{33} & A_{34} \\ @@ -6974,7 +7099,7 @@ used−even when \pkg{colortbl} is not loaded). \end{pNiceArray} \end{Code} -\[\begin{pNiceArray}{>{\strut}cccc}[margin, extra-margin=2pt,color-inside] +\[\begin{pNiceArray}{>{\strut}cccc}[margin, extra-margin=2pt,color-inside,no-cell-nodes] \rowcolor{red!15}A_{11} & A_{12} & A_{13} & A_{14} \\ A_{21} & \rowcolor{red!15}A_{22} & A_{23} & A_{24} \\ A_{31} & A_{32} & \rowcolor{red!15}A_{33} & A_{34} \\ @@ -7281,7 +7406,16 @@ 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.25 and 6.26} +\subsection*{Changes between version 6.27 and 6.28} + +Sub-blocks with the character |&| (when the key |ampersand-in-block| is in +force). + +Keys |p| and |j| for the command |\Block|. + +PGF nodes i.1, i.2, i.3, etc. + +\subsection*{Changes between version 6.26 and 6.27} New key |light-syntax-expanded|. |