diff options
author | Karl Berry <karl@freefriends.org> | 2023-09-29 21:05:29 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2023-09-29 21:05:29 +0000 |
commit | a40c1b67ba5d7a6be3d8f1725ca0041b5956b353 (patch) | |
tree | 542eb940279fcdcddd5741a8606f3e149a55d48d /Master/texmf-dist/doc/latex/nicematrix | |
parent | ff14c4fc4652aedeb907888df883eb9ad0e68340 (diff) |
nicematrix (29sep23)
git-svn-id: svn://tug.org/texlive/trunk@68398 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/nicematrix')
-rw-r--r-- | Master/texmf-dist/doc/latex/nicematrix/nicematrix-code.pdf | bin | 940839 -> 943866 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/latex/nicematrix/nicematrix-french.pdf | bin | 588214 -> 590286 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/latex/nicematrix/nicematrix-french.tex | 250 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/nicematrix/nicematrix.pdf | bin | 604351 -> 606674 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/latex/nicematrix/nicematrix.tex | 230 |
5 files changed, 347 insertions, 133 deletions
diff --git a/Master/texmf-dist/doc/latex/nicematrix/nicematrix-code.pdf b/Master/texmf-dist/doc/latex/nicematrix/nicematrix-code.pdf Binary files differindex 558543af0d5..a946462d28f 100644 --- a/Master/texmf-dist/doc/latex/nicematrix/nicematrix-code.pdf +++ b/Master/texmf-dist/doc/latex/nicematrix/nicematrix-code.pdf diff --git a/Master/texmf-dist/doc/latex/nicematrix/nicematrix-french.pdf b/Master/texmf-dist/doc/latex/nicematrix/nicematrix-french.pdf Binary files differindex 786f5acc729..b8847116e04 100644 --- a/Master/texmf-dist/doc/latex/nicematrix/nicematrix-french.pdf +++ b/Master/texmf-dist/doc/latex/nicematrix/nicematrix-french.pdf diff --git a/Master/texmf-dist/doc/latex/nicematrix/nicematrix-french.tex b/Master/texmf-dist/doc/latex/nicematrix/nicematrix-french.tex index 688885eee9a..a677a356819 100644 --- a/Master/texmf-dist/doc/latex/nicematrix/nicematrix-french.tex +++ b/Master/texmf-dist/doc/latex/nicematrix/nicematrix-french.tex @@ -1,6 +1,6 @@ % -*- coding: utf-8 ; -*- % Ce fichier doit être compilé avec xelatex uniquement. -\documentclass[dvipsnames]{article}% dvipsnames is for xcolor (loaded by Tikz, loaded by nicematrix) +\documentclass[dvipsnames]{article}% dvipsnames is for xcolor (loaded by TikZ, loaded by nicematrix) \usepackage{xltxtra} \usepackage[french]{babel} \frenchsetup{og = « , fg = »} @@ -533,13 +533,16 @@ $\begin{bNiceArray}{cw{c}{1cm}c|c}[margin] \interitem La commande |\Block| accepte en premier argument optionnel (entre crochets) une -liste de couples \textsl{clé=valeur}. Les clés sont les suivantes : +liste de couples \textsl{clé=valeur}. + +\smallskip +Les premières clés sont des outils rapides pour contrôler l'apparence du bloc : + \begin{itemize} \item \index{fill (clé de \texttt{\textbackslash Block})} la clé \Definition{fill} prend en argument une couleur et remplit le bloc avec cette couleur ; \item \index{opacity! (clé de la commande \texttt{\textbackslash Block})} -\colorbox{yellow!50}{\bfseries Nouveau 6.22}\enskip la clé \Definition{opacity} fixe l'opacité de la couleur de remplissage donnée par |fill| ; \item \index{draw (clé de \texttt{\textbackslash Block})} @@ -566,15 +569,46 @@ la clé \Definition{rounded-corners} impose des coins arrondis (pour le cadre dessiné par |draw| et le fond dessiné par |fill|) avec un rayon égal à la valeur de cette clé (la valeur par défaut est 4~pt\footnote{Cette valeur par défaut est la valeur initiale des \emph{rounded - corners} de TikZ.}) ; + corners} de TikZ.}). +\end{itemize} + +\medskip +Ces outils ne sont parfois pas suffisants pour contrôler l'apparence du bloc. +Les clés suivantes sont plus puissantes, mais plus difficiles d'utilisation. +Elles nécessitent également que TikZ soit chargé (par |\usepackage{tikz}|). Par +défaut, \pkg{nicematrix} ne charge pas TikZ mais uniquement \textsc{pgf}, qui +est une sous-couche de TikZ. +\begin{itemize} +\item \index{borders (clé de \texttt{\textbackslash Block})} \index{tikzz@tikz!clé de «borders» de \texttt{\textbackslash Block}} +La clé \Definition{borders} permet de ne tracer que certaines des bordures +du bloc : cette clé prend comme valeur une liste d'éléments parmi les suivants : +|left|, |right|, |top| et |bottom| ; on peut en fait, dans la liste qui est la +valeur de la clé |borders| mettre une entrée de la forme +|tikz={|\textsl{liste}|}| où \textsl{liste} est une liste de couples +\textsl{clé=valeur} de TikZ spécifiant les caractéristiques graphiques des +traits qui seront dessinés (pour un exemple, voir p.~\pageref{tiretes}). + \item \index{tikzz@tikz!clé de \texttt{\textbackslash Block}} -quand la clé \Definition{tikz} est utilisée, le chemin TikZ correspondant +Quand la clé \Definition{tikz} est utilisée, le chemin TikZ correspondant au rectangle délimitant le bloc est exécuté avec TikZ\footnote{TikZ doit être chargé préalablement (par défaut, \pkg{nicematrix} ne charge que \textsc{pgf}), faute de quoi, une erreur sera levée.} en utilisant comme options la valeur de cette clé |tikz| (qui doit donc être une liste de clés TikZ applicables à un chemin de TikZ). Pour des exemples d'utilisation de cette clé -|tikz|, voir p.~\pageref{tikz-key-examples} ; +|tikz|, voir p.~\pageref{tikz-key-examples}. + +\colorbox{yellow!50}{\textbf{Nouveau 6.24}}\enskip En fait, dans la liste des +clés fournies à |tikz|, on peut mettre une clé |offset|. Cette clé n'est pas +fournie par TikZ mais par \pkg{nicematrix}. Elle réduit le rectangle +correspondant au bloc par une marge (horizontalement et verticalement) égale à +la valeur (passée à |offset|). C'est ce rectangle réduit qui sera le chemin +exécuté par TikZ avec comme options les autres clés passées à la clé |tikz|. +\end{itemize} + + +\medskip +Enfin, il existe quelque clés techniques : +\begin{itemize} \item \index{name!clé de \texttt{\textbackslash Block}} la clé \Definition{name} donne un nom au nœud TikZ rectangulaire correspondant au bloc ; on peut utiliser ce nom avec TikZ dans le |\CodeAfter| @@ -582,22 +616,18 @@ correspondant au bloc ; on peut utiliser ce nom avec TikZ dans le |\CodeAfter| \item \index{respect-arraystretch (clé de \texttt{\textbackslash Block})} la clé \Definition{respect-arraystretch} évite la remise à $1$ de |\arraystretch| en début de bloc (qui a lieu par défaut) ; -\item \index{borders (clé de \texttt{\textbackslash Block})} \index{tikzz@tikz!clé de «borders» de \texttt{\textbackslash Block}} -la clé \Definition{borders} permet de ne tracer que certaines des bordures -du bloc : cette clé prend comme valeur une liste d'éléments parmi les suivants : -|left|, |right|, |top| et |bottom| ; on peut en fait, dans la liste qui est la -valeur de la clé |borders| mettre une entrée de la forme -|tikz={|\textsl{liste}|}| où \textsl{liste} est une liste de couples -\textsl{clé=valeur} de TikZ spécifiant les caractéristiques graphiques des -traits qui seront dessinés (pour un exemple, voir p.~\pageref{tiretes}). \item \index{transparent (clé de \texttt{\textbackslash Block})} Par défaut, les filets ne sont pas tracés dans les blocs (voir à ce sujet la partie sur les filets, section~\ref{rules} p.~\pageref{rules}). Néanmoins, si -la clé \Definition{transparent} est utilisée, les filets seront tracés. Pour un -example, voir la section~\ref{tikz-key-examples}, -page~\pageref{tikz-key-examples}. Attention : cette clé n'implique pas du tout -que le contenu du bloc sera transparent. +la clé \Definition{transparent} est utilisée, les filets seront tracés.\footnote{Par +ailleurs, la commande |\TikzEveryCell| disponible dans le |\CodeAfter|, ne +s'applique aux blocs avec la clé |transparent|).} +Pour un exemple, voir la section~\ref{tikz-key-examples}, +page~\pageref{tikz-key-examples}. + +Attention : cette clé n'implique pas du tout que le contenu du bloc sera +transparent. \end{itemize} Il existe aussi des clés de positionnement horizontal et vertical du bloc qui @@ -885,9 +915,9 @@ impliquées dans le bloc. \item Avec la clé \Definition{T}, le contenu du bloc est calé vers le haut. -\colorbox{yellow!50}{Modification 6.18}\enskip Il n'y a plus de marge verticale. -Néanmoins, le contenu du bloc est (toujours) composé en interne dans une |{minipage}|, un -|{tabular}| ou un |{array}|, ce qui fait qu'il y souvent déjà une marge. +Il n'y a pas de marge verticale. Néanmoins, le contenu du bloc est (toujours) +composé en interne dans une |{minipage}|, un |{tabular}| ou un |{array}|, ce qui +fait qu'il y souvent déjà une marge. \item Avec la clé \Definition{B}, le contenu du bloc est calé vers le bas. \end{itemize} @@ -1146,20 +1176,21 @@ Dans les environnements de \pkg{nicematrix}, une instruction Les environnements de \pkg{nicematrix} proposent une clé |rules/width| pour fixer la largeur (on devrait plutôt dire l'épaisseur) des filets dans l'environnement. En fait, cette clé ne fait que fixer la valeur du paramètre -dimensionnel |\arrayrulewidth|. +dimensionnel de LaTeX |\arrayrulewidth|. \smallskip On sait que \pkg{colortbl} propose la commande |\arrayrulecolor| pour spécifier la couleur de ces filets. \smallskip -\indexcommand{arrayrulecolor} +\indexcommand{arrayrulecolor} Avec \pkg{nicematrix}, il est possible de spécifier une couleur même si \pkg{colortbl} n'est pas chargé. Par souci de compatibilité, la commande est -nommée également |\arrayrulecolor|. Les environnements de \pkg{nicematrix} -proposent également une clé |rules/color| qui permet de fixer cette couleur pour -l'environnement en question. Cette clé fixe localement la couleur des filets -(alors que la commande |\arrayrulecolor| agit globalement !). +nommée également |\arrayrulecolor|. Néanmoins, \pkg{nicematrix} propose aussi +une clé |rules/color|, disponible dans |\NiceMatrixOptions| ou dans un +environnement individuel, pour fixer la couleur des filets. Cette clé fixe +localement la couleur des filets (alors que la commande |\arrayrulecolor| agit +globalement !). Elle est à privilégier. \medskip \begin{scope} @@ -1182,6 +1213,11 @@ muguet & dahlia & souci \\ \end{NiceTabular} \end{scope} +\medskip +En fait, dans cet exemple, au lieu de |\hline|, il aurait mieux valu utiliser la +commande |\Hline|, fournie par \pkg{nicematrix} et décrite ci-dessous, car elle +garantit un meilleur résultat dans les lecteurs de PDF aux bas niveaux de zoom. + \medskip @@ -1218,21 +1254,19 @@ p.~\pageref{corners}. \item Pour les rangées et colonnes extérieures, cf. p.~\pageref{exterior}. \end{itemize} -En particulier, cette remarque explique la différence entre la commande standard -|\hline| et la commande |\Hline| proposée par \pkg{nicematrix}. +En particulier, cette remarque montre déjà une différence entre la commande +standard |\hline| et la commande |\Hline| proposée par \pkg{nicematrix}. -La commande |\Hline| admet entre crochets un argument optionnel qui est une -liste de couples \textsl{clé=valeur} qui décrivent un filet. Pour la description -de ces clés, voir |custom-line| p.~\pageref{custom-line}.\footnote{Remarque - technique. Si l'utilisateur définit une commande par-dessus la commande - |\Hline|, il doit veiller à ce qu'elle soit \emph{développable} au sens de - TeX (en utilisant |\NewExpandableDocumentCommand| de LaTeX3, |\newcommand| de - LaTeX ou même |\def| de TeX). Exemple : - |\newcommand{\RedLine}{\Hline{color=red}}|} +Par ailleurs, la commande |\Hline| admet entre crochets un argument optionnel +qui est une liste de couples \textsl{clé=valeur} qui décrivent un filet. Pour la +description de ces clés, voir |custom-line| +p.~\pageref{custom-line}.\footnote{Remarque technique. Si l'utilisateur définit + une commande par-dessus la commande |\Hline|, il doit veiller à ce qu'elle + soit \emph{développable} au sens de TeX (en utilisant + |\NewExpandableDocumentCommand| de LaTeX3, |\newcommand| de LaTeX ou même + |\def| de TeX). Exemple : |\newcommand{\RedLine}{\Hline[color=red]}|} \bigskip -\colorbox{yellow!50}{\textbf{Nouveau 6.23}}\enskip - De même que la commande |\Hline|, le specificateur «\verb+|+» admet entre crochets des options qui caractérisent le filet à tracer. @@ -1516,9 +1550,11 @@ utilisée par l'utilisateur dans le préambule d'un environnement à préambule \bigskip On traite maintenant de la description du filet elle-même. Les options qui -suivent peuvent aussi s'utiliser dans l'argument optionnel d'une |\Hline| -individuelle. +suivent peuvent aussi s'utiliser dans l'argument optionnel d'une commande +|\Hline| individuelle ou dans l'argument optionnel d'un spécificateur «\verb+|+» +dans un préambule d'environnement. +\bigskip Il y a trois possibilités. @@ -1731,7 +1767,7 @@ $\begin{pNiceArray}{cccc:c} Rappelons que l'extension \pkg{colortbl} peut être chargée directement par |\usepackage{colortbl}| ou en chargeant l'extension \pkg{xcolor} avec l'option -|table| : |\usepackage[table]{xcolor}|. +\texttt{table} : |\usepackage[table]{xcolor}|. \medskip Comme l'extension \pkg{nicematrix} est fondée sur \pkg{array}, il est possible @@ -1828,6 +1864,8 @@ De nouvelles commandes sont disponibles dans ce |\CodeBefore|: |\cellcolor|, \index{arraycolor@\texttt{\textbackslash arraycolor} (commande du \texttt{\textbackslash CodeBefore)}} +Les noms de ces commandes sont inspirés des noms des commandes de \pkg{colortbl}. + \medskip Ces commandes ne colorient pas les cases qui se trouvent dans les «coins» si la @@ -2327,13 +2365,13 @@ que la commande éponyme de \pkg{colortbl} (néanmoins, contrairement à la commande |\columncolor| de \pkg{colortbl}, celle de \pkg{nicematrix} peut apparaître à l'intérieur d'une autre commande, elle-même utilisée dans le préambule) ; -\item \colorbox{yellow!50}{\textbf{Nouveau 6.21}}\enskip |\rowcolors| qui prend pour arguments deux couleurs et colorie la suite du +\item |\rowcolors| qui prend pour arguments deux couleurs et colorie la suite du tableau avec ces deux couleurs ; -\item \colorbox{yellow!50}{\textbf{Nouveau 6.21}}\enskip |\rowlistcolors| qui prend pour argument une liste de couleurs et colorie +\item |\rowlistcolors| qui prend pour argument une liste de couleurs et colorie la suite du tableau avec ces couleurs.\footnote{Quand la commande |\rowlistcolors| (ou la commande |\rowcolors|) est utilisée dans une case de - la colonne~$j$, le coloriage ne s'applique que les colonnes au-delà de~$j$ - (à dessein).} + la colonne~$j$, le coloriage ne s'applique que les colonnes au-delà de~$j$ (à + dessein).} \end{itemize} \medskip @@ -2399,7 +2437,7 @@ La clé \Definition{rowcolor} fixe la couleur de fond et la clé \Definition{col fixe la couleur du texte.\footnote{La clé |color| utilise la commande |\color| mais insère aussi une instruction |\leavevmode| devant. Cela évite un espace vertical parasite dans les cases qui correspondent à des colonnes de type - |p|, |b|, |m|, |X| et |V| (qui débutent en mode vertical de LateX).} + |p|, |b|, |m|, |X| et |V| (qui débutent en mode vertical de LaTeX).} \item \index{bold (clé de \texttt{\textbackslash RowStyle})} La clé \Definition{bold} impose des caractères gras aux éléments de la rangée, qu'ils @@ -2590,10 +2628,7 @@ initiale de ce paramètre est |\linewidth| (et non |\textwidth|). Pour se rapprocher davantage de l'environnement |{tabularx}|, \pkg{nicematrix} propose aussi un environnement |{NiceTabularX}| avec une syntaxe similaire à celle de |{tabularx}|, c'est-à-dire que la largeur voulue pour le tableau est -spécifiée en premier argument (obligatoire).\footnote{Si \pkg{tabularx} est - chargé, on doit obligatoirement utiliser |{NiceTabularX}| pour utiliser les - colonnes |X| (cela est dû à un problème de conflit de définition des - spécificateurs de colonne |X|).} +spécifiée en premier argument (obligatoire). Comme avec les extensions \pkg{tabu}\footnote{L'extension \pkg{tabu} est @@ -3270,10 +3305,10 @@ au-dessous et au-dessus de la ligne. Les arguments sont composés en mode mathématique avec |\scriptstyle|. \smallskip -\colorbox{yellow!50}{\textbf{Nouveau 6.22}}\enskip La version 6.22 introduit un -nouveau label spécifié par le caractère~«|:|» pour un label situé \emph{sur} la ligne -elle-même. Ce label est en fait composé sur un fond blanc qui est superposé sur -la ligne en pointillés (voir un exemple p.~\pageref{ex:colon}). +La version 6.22 de \pkg{nicematrix} a introduit un nouveau label spécifié par le +caractère~«|:|» pour un label situé \emph{sur} la ligne elle-même. Ce label est +en fait composé sur un fond blanc qui est superposé sur la ligne en pointillés +(voir un exemple p.~\pageref{ex:colon}). \bigskip \begin{BVerbatim}[baseline=c,boxwidth=10cm] @@ -3355,7 +3390,7 @@ Pour la clarté, dans la suite, on utilisera ces noms-là. \bigskip La clé \Definition{xdots/horizontal-labels} demande que les labels (introduits -par |_| et |^|) restent horizontaux. +par |_|, |^| et |:|) restent horizontaux. \medskip L'option \Definition{xdots/color} indique bien entendu la couleur de la ligne @@ -3477,10 +3512,9 @@ $\begin{bNiceMatrix}[margin,hvlines] \index{blkarray@\pkg{blkarray} (extension)} -\colorbox{yellow!50}{\textbf{Modifié 6.16}}\enskip Pour les environnements à -préambule (|{NiceArray}|, |{pNiceArray}|, etc.), il est possible de placer des -délimiteurs verticaux directement dans le préambule.\footnote{Cette syntaxe est - inspirée de l'extension \pkg{blkarray}.} +Pour les environnements à préambule (|{NiceArray}|, |{pNiceArray}|, etc.), il +est possible de placer des délimiteurs verticaux directement dans le +préambule.\footnote{Cette syntaxe est inspirée de l'extension \pkg{blkarray}.} \label{delimiters-in-preamble}% \smallskip @@ -3581,9 +3615,9 @@ PGF-TikZ créés par \pkg{nicematrix} dans le |\CodeAfter|. Ces nœuds sont déc à partir de la page \pageref{PGF-nodes}. \medskip -Par ailleurs, plusieurs commandes spéciales sont disponibles dans le |\CodeAfter| : -|\line|, |\SubMatrix|, |\OverBrace| et |\UnderBrace|. On va maintenant détailler -ces commandes. +Par ailleurs, plusieurs commandes spéciales sont disponibles dans le +|\CodeAfter| : |\line|, |\SubMatrix|, |\OverBrace|, |\UnderBrace| et +|\TikzEveryCell|. On va maintenant détailler ces commandes. \subsection{La commande \textbackslash line dans le \textbackslash CodeAfter} @@ -4007,7 +4041,7 @@ $\begin{pNiceMatrix} \bigskip Attention : Aucun espace vertical n'est réservé par \pkg{nicematrix} pour ces -accolades.\footnote{Voir à ce sujet: \url{https://tex.stackexchange.com/questions/685755}} +accolades, ni pour leurs labels.\footnote{Voir à ce sujet: \url{https://tex.stackexchange.com/questions/685755}} \bigskip \index{color!clé de \texttt{\textbackslash OverBrace} et \texttt{\textbackslash @@ -4053,6 +4087,77 @@ $\begin{pNiceMatrix} \OverBrace[shorten,yshift=3pt]{1-4}{2-6}{B} \end{pNiceMatrix}$ + +\subsection{La commande \textbackslash TikzEveryCell dans le \textbackslash CodeAfter} + +\index{SubMatrix@\texttt{\textbackslash TikzEveryCell} (commande du +\texttt{\textbackslash CodeAfter}\newline et du +\texttt{\textbackslash CodeBefore})|textbf} + + +\colorbox{yellow!50}{\textbf{Nouveau 6.24}}\enskip La commande |\TikzEveryCell| +exécute avec TikZ le chemin rectangulaire qui correspond à chaque case du tableau, +avec comme paramètres TikZ l'argument de |\TikzEveryCell|. Cet argument doit +être une liste de couples \textsl{clé=valeur} applicables à un chemin +TikZ. En fait, cette commande s'applique à chaque cellule du tableau, exceptées +celles situées dans les rangées et colonnes extérieures (cf.~p.~\pageref{exterior})o et celles situées dans +les coins vides (quand la clé |corners| est utilisée: cf.~p.~\pageref{corners}). Elle s'applique en fait à +chaque bloc (sauf ceux qui ont la clé |transparent|) et ne s'applique pas aux +cellules situées dans ces blocs. + +\medskip +En fait, dans la liste des clés passée en argument on peut mettre une clé +|offset|. Cette clé n'est pas fournie par TikZ mais par \pkg{nicematrix}. Elle +réduit le rectangle correspondant au bloc par une marge (horizontalement et +verticalement) égale à la valeur (passée à |offset|). C'est ce rectangle réduit +qui sera le chemin exécuté par TikZ avec comme options les autres clés de +l'argument de |\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 + + +\medskip +La commande |\TikzEveryCell| possède deux clés : +\begin{itemize} +\item avec la clé \Definition{empty}, la commande ne s'applique qu'aux cellules +vides ; +\item avec la clé \Definition{non-empty}, la commande ne s'applique qu'aux +cellules non vides. +\end{itemize} + + +\medskip +La commande |\TikzEveryCell| est en fait aussi disponible dans le |\CodeBefore|. + + + + + \index{CodeAfter@\texttt{\textbackslash CodeAfter}|)} \section{Les légendes et les notes dans les tableaux} @@ -4204,7 +4309,7 @@ les notes de pied de page). \item Si une commande |\tabularnote{...}| se trouve exactement à la fin d'une case (sans aucun espace après), l'appel de note est composé en débordement vers la droite (cela peut permettre de mieux conserver l'alignement des contenus d'une -colonne). Depuis la version 6.20a, ce comportement n'a lieu que le mode +colonne). Depuis la version 6.20a, ce comportement n'a lieu que si le mode l'alignement de la case est |c| ou |r| (alignement horizontal centré ou en butée à droite). @@ -4524,9 +4629,9 @@ avec des coins arrondis.\footnote{Bien sûr, lorsqu'il s'agit d'un environnement \end{itemize} \bigskip -\colorbox{yellow!50}{\textbf{Nouveau 6.21}} Cette clé est disponible dans tous -les environnements et commandes de \pkg{nicematrix} (comme -|\pAutoNiceMatrix|) et également dans |\NiceMatrixOptions|. +Cette clé est disponible dans tous les environnements et commandes de +\pkg{nicematrix} (comme par exemple |\pAutoNiceMatrix|) et également dans +|\NiceMatrixOptions|. \bigskip \begin{BVerbatim}[baseline=c,boxwidth=9.5cm] @@ -4715,11 +4820,10 @@ $A = \begin{pNiceMatrix}[last-row,last-col=4] \end{varwidth} \bigskip -\colorbox{yellow!50}{\textbf{Nouveau 6.21}}\enskip La commande |\rotate| accepte -une option |c| entre crochets : |\rotate[c]| (les espaces sont supprimés après -|\rotate[c]|). Quand cette clé est utilisée, le contenu, après rotation, est -composé dans une |\vcenter|, ce qui fait que, le plus souvent, on obtiendra un -centrage vertical. +La commande |\rotate| accepte une option |c| entre crochets : |\rotate[c]| (les +espaces sont supprimés après |\rotate[c]|). Quand cette clé est utilisée, le +contenu, après rotation, est composé dans une |\vcenter|, ce qui fait que, le +plus souvent, on obtiendra un centrage vertical. \medskip diff --git a/Master/texmf-dist/doc/latex/nicematrix/nicematrix.pdf b/Master/texmf-dist/doc/latex/nicematrix/nicematrix.pdf Binary files differindex 1c8fbe1e24a..7865c622af3 100644 --- a/Master/texmf-dist/doc/latex/nicematrix/nicematrix.pdf +++ b/Master/texmf-dist/doc/latex/nicematrix/nicematrix.pdf diff --git a/Master/texmf-dist/doc/latex/nicematrix/nicematrix.tex b/Master/texmf-dist/doc/latex/nicematrix/nicematrix.tex index b2da527927e..cec4b584ca0 100644 --- a/Master/texmf-dist/doc/latex/nicematrix/nicematrix.tex +++ b/Master/texmf-dist/doc/latex/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} |