From 568066f46cf194676ba50742e218cb4bcf10ed88 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Tue, 10 Aug 2021 21:14:09 +0000 Subject: nicematrix (10aug21) git-svn-id: svn://tug.org/texlive/trunk@60214 c570f23f-e606-0410-a88d-b1316a301751 --- .../doc/latex/nicematrix/nicematrix-french.pdf | Bin 466543 -> 470144 bytes .../doc/latex/nicematrix/nicematrix-french.tex | 248 ++++++++++++++------- .../texmf-dist/doc/latex/nicematrix/nicematrix.pdf | Bin 1355018 -> 1377012 bytes 3 files changed, 173 insertions(+), 75 deletions(-) (limited to 'Master/texmf-dist/doc/latex') diff --git a/Master/texmf-dist/doc/latex/nicematrix/nicematrix-french.pdf b/Master/texmf-dist/doc/latex/nicematrix/nicematrix-french.pdf index 6965309fe96..7a1973e08e3 100644 Binary files a/Master/texmf-dist/doc/latex/nicematrix/nicematrix-french.pdf and b/Master/texmf-dist/doc/latex/nicematrix/nicematrix-french.pdf differ diff --git a/Master/texmf-dist/doc/latex/nicematrix/nicematrix-french.tex b/Master/texmf-dist/doc/latex/nicematrix/nicematrix-french.tex index d941d2f9f8a..7d7d915bc38 100644 --- a/Master/texmf-dist/doc/latex/nicematrix/nicematrix-french.tex +++ b/Master/texmf-dist/doc/latex/nicematrix/nicematrix-french.tex @@ -139,7 +139,7 @@ l'instruction habituelle : |\usepackage{nicematrix}|. \bigskip L'idée de \pkg{nicematrix} est de créer des nœuds \textsc{pgf} derrière les cases et les positions des filets des tableaux créés par \pkg{array} et de les utiliser pour développer de nouvelles fonctionnalités. Comme toujours avec -\textsc{pgf}, les coordonnées de ces nœuds sont écrites dans le fichier |.aux| pour être utilisées à la +\textsc{pgf}, les coordonnées de ces nœuds sont écrites dans le fichier |aux| pour être utilisées à la compilation suivante. C'est pourquoi l'utilisation de \pkg{nicematrix} nécessite \textbf{plusieurs compilations successives}.\footnote{Si vous utilisez Overleaf, Overleaf effectue automatiquement le nombre de @@ -200,19 +200,6 @@ crochets, une liste optionnelle de paires de la forme \textsl{clé=valeur}. {\bfseries Il doit n'y avoir aucun espace devant le crochet ouvrant (|[|) de cette liste d'options.} -\bigskip -\textbf{Important}\par\nobreak - -Avant la version 5.0, il fallait, pour des raisons techniques, utiliser les -lettres |L|, |C| et |R| au lieu de |l|, |c| et |r| dans les préambules des -environnements de \pkg{nicematrix}. Pour pouvoir continuer à utiliser ces -lettres |L|, |C| et |R|, \pkg{nicematrix} doit être chargé avec l'option -|define-L-C-R|. -\begin{Verbatim} -\usepackage[define-L-C-R]{nicematrix} -\end{Verbatim} -\textbf{Cette clé sera probablement supprimée dans une future version de - \pkg{nicematrix}.} \section{L'espace vertical entre les rangées} @@ -512,7 +499,7 @@ $\begin{bNiceArray}{ccc|c}[margin] \interitem La commande |\Block| accepte en fait en premier argument optionnel (entre -crochets) une liste de couples clé-valeur. Les clés sont les suivantes : +crochets) une liste de couples \textsl{clé=valeur}. Les clés sont les suivantes : \begin{itemize} \item les clés |l|, |c| et |r| réglent le positionnement horizontal comme dit précédemment ; @@ -589,6 +576,10 @@ Les blocs mono-colonne ont un comportement spécial. \item La largeur naturelle du contenu de ces blocs est prise en compte pour la largeur de la colonne courante. +\colorbox{yellow!50}{\textbf{Nouveau 6.0}}\enskip Dans les colonnes à largeur +fixée (colonnes |w{...}{...}|, |p{...}|, |b{...}|, |m{...}| et |X|), le contenu +du bloc est mis en forme comme un paragraphe de cette largeur. + \item La spécification d'alignement horizontal donnée par le type de colonne (|c|, |r| ou |l|) est prise en compte pour le bloc (mais le bloc peut avoir sa propre spécification d'alignement horizontal). @@ -1307,8 +1298,8 @@ l'environnement. \smallskip De nouvelles commandes sont disponibles dans ce |\CodeBefore|: -|\cellcolor|, |\rectanglecolor|, |\rowcolor|, |\columncolor|, |\rowcolors| -|\chessboardcolors| et |\arraycolor|.\footnote{On pourra remarquer que, dans le +|\cellcolor|, |\rectanglecolor|, |\rowcolor|, |\columncolor|, |\rowcolors|, +|\rowlistcolors|, |\chessboardcolors| et |\arraycolor|.\footnote{On pourra remarquer que, dans le \verb|\CodeBefore|, des nœuds PGF/Tikz de la forme \verb+(i-|j)+ correspondant à la position des filets éventuels sont également accessibles : cf. p.~\pageref{noeuds-i}.} \label{code-before} @@ -1590,6 +1581,46 @@ Henri & 14 \\ + + +\bigskip +\item \colorbox{yellow!50}{\textbf{Nouveau 6.0}}\enskip L'extension +\pkg{nicematrix} propose aussi une commande |\rowlistcolors|. Cette commande +généralise la commande |\rowcolors|: au lieu de prendre deux arguments +successifs pour les couleurs, elle prend un seul argument qui est une liste de +couleurs séparées par des virgules. Dans cette liste, le symbole |=| représente +une couleur identique à la précédente. + +\smallskip +\begin{BVerbatim}[boxwidth=10cm,baseline=c] +\begin{NiceTabular}{c} +\CodeBefore + ~emphase#\rowlistcolors{1}{red!15,blue!15,green!15}@ +\Body +Mathilde \\ +Pierre \\ +Paul \\ +Amélie \\ +Jacques \\ +Antoine \\ +Stéphanie \\ +\end{NiceTabular} +\end{BVerbatim} +\begin{NiceTabular}{c} +\CodeBefore + \rowlistcolors{1}{red!15,blue!15,green!15} +\Body +Mathilde \\ +Pierre \\ +Paul \\ +Amélie \\ +Jacques \\ +Antoine \\ +Stéphanie \\ +\end{NiceTabular} + +\end{itemize} + \bigskip On rappelle que toutes les commandes de coloriage que l'on vient de décrire ne colorient pas les cases qui sont dans les «coins». Dans l'exemple suivant, on @@ -1601,7 +1632,7 @@ utilise la clé |corners| pour demander de considérer le coin \emph{north east} \begin{BVerbatim}[boxwidth=9cm,baseline=c] \begin{NiceTabular}{cccccc}[~emphase#corners=NE@,margin,hvlines,first-row,first-col] \CodeBefore - ~emphase#\rowcolors{1}{blue!15}{}@ + ~emphase#\rowlistcolors{1}{blue!15, }@ \Body & 0 & 1 & 2 & 3 & 4 & 5 & 6 \\ 0 & 1 \\ @@ -1615,7 +1646,7 @@ utilise la clé |corners| pour demander de considérer le coin \emph{north east} \end{BVerbatim} \begin{NiceTabular}{ccccccc}[corners=NE,margin,hvlines,first-row,first-col] \CodeBefore - \rowcolors{1}{blue!15}{} + \rowlistcolors{1}{blue!15, } \Body & 0 & 1 & 2 & 3 & 4 & 5 & 6 \\ 0 & 1 \\ @@ -1628,7 +1659,6 @@ utilise la clé |corners| pour demander de considérer le coin \emph{north east} \end{NiceTabular} \end{scope} -\end{itemize} \bigskip @@ -1776,9 +1806,11 @@ La commande |\rotate| est présentée p.~\pageref{rotate}. \section{La largeur des colonnes} \label{width} +\subsection{Techniques de base} + Dans les environnements avec un préambule explicite (comme |{NiceTabular}|, |{NiceArray}|, etc.), il est possible de fixer la largeur d'une colonne avec les -lettres classiques |w| et |W| de l'extension \pkg{array}. +lettres classiques |w|, |W|, |p|, |b| et |m| de l'extension \pkg{array}. \medskip \begin{BVerbatim}[baseline=c,boxwidth=9cm] @@ -1797,8 +1829,9 @@ Rio & Tokyo & Oslo \bigskip Dans les environnements de \pkg{nicematrix}, il est aussi possible de fixer la -largeur \emph{minimale} de toutes les colonnes de la matrice directement avec -l'option |columns-width|. +largeur \emph{minimale} de toutes les colonnes (à l'exception des éventuelles +colonnes extérieures: cf. p.~\pageref{exterior}) directement avec l'option +|columns-width|. \medskip \begin{BVerbatim}[baseline=c,boxwidth=10cm] @@ -1824,7 +1857,7 @@ supprimé (il est évidemment possible de le supprimer en mettant |\tabcolsep| o Il est possible de donner la valeur spéciale |auto| à l'option |columns-width|: toutes les colonnes du tableau auront alors une largeur égale à la largeur de la case la plus large du tableau.\footnote{Le résultat est atteint dès la première - compilation (mais PGF/Tikz écrivant des informations dans le fichier |.aux|, + compilation (mais PGF/Tikz écrivant des informations dans le fichier |aux|, un message demandant une deuxième compilation apparaîtra).}\par\nobreak \medskip @@ -1843,7 +1876,7 @@ $\begin{pNiceMatrix}[columns-width = auto] \bigskip Sans surprise, il est possible de fixer la largeur minimale de toutes les -colonnes de toutes les matrices dans une certaine portion de document avec la +colonnes de tous les tableaux dans une certaine portion de document avec la commande |\NiceMatrixOptions|.\par\nobreak \medskip @@ -1907,12 +1940,56 @@ $\begin{array}{c} \end{NiceMatrixBlock} +\subsection{Les colonnes X} + +\colorbox{yellow!50}{\textbf{Nouveau 6.0}} + +L'environnement |{NiceTabular}| propose aussi des colonnes |X| similaires à +celles proposées par l'environnement |{tabularx}| de l'extension éponyme. + +La valeur requise par la largeur du tableau peut être passée en argument de la +clé |width|. La valeur initiale de ce paramètre est |\linewidth|. + +Pour se rapprocher davantage de l'environnement |{tabularx}|, \pkg{nicematrix} +propose aussi un environnement |{NiceTabularX}| qui prend en premier argument +(obligatoire) la largeur voulue pour le tableau. + +Comme avec les extensions \pkg{tabu} et \pkg{tabularray}, le spécificateur |X| +accepte entre crochets un argument optionnel qui est une liste de clés. +\begin{itemize} +\item On peut spécifier un poids pour la colonne en mettant directement un +entier comme argument du spécificateur |X|. Par exemple, une colonne |X[2]| aura +une largeur double de celle d'une colonne |X| (qui a un poids de 1). +\item On peut spécifier l'alignement horizontal avec une des lettres |l|, |c| et +|r| (qui insèrent respectivement |\raggedright|, |\centering| et |\raggedleft| +suivi de |\arraybackslash|). +\item On peut spécifier l'alignement vertical avec l'une des lettres |t| (alias +|p|), |m| et |b| (qui construisent respectivement des colonnes de types |p|, |m| +et |b|). La valeur par défaut est |t|. +\end{itemize} + +\begin{Verbatim} +\begin{NiceTabular}~emphase#[width=9cm]{X[2,l]X[l]}@[hvlines] +Un texte relativement long qui tient sur plusieurs lignes. & +Un texte relativement long qui tient sur plusieurs lignes. \\ +Un texte plus court. & Un texte plus court. +\end{NiceTabular} +\end{Verbatim} + + +\begin{center} +\begin{NiceTabular}[width=9cm]{X[2,l]X[l]}[hvlines] +Un texte relativement long qui tient sur plusieurs lignes. & +Un texte relativement long qui tient sur plusieurs lignes. \\ +Un texte plus court. & Un texte plus court. +\end{NiceTabular} +\end{center} \bigskip \section{Les rangées et colonnes extérieures} Les environnements de \pkg{nicematrix} permettent de composer des rangées et des colonnes «extérieures» grâce aux options |first-row|, |last-row|, |first-col| et -|last-col|. +|last-col|. C'est particulièrement intéressant pour les matrices (mathématiques). \label{exterior} Si elle est présente, la «première rangée» (extérieure) est numérotée par $0$ @@ -1970,7 +2047,7 @@ tableau. L'analyse du contenu de l'environnement donne le nombre de rangées (mais pas le nombre de colonnes). \item Dans les autres cas, \pkg{nicematrix} détermine le nombre de rangées et de -colonnes à la première compilation et l'écrit dans le fichier |.aux| pour +colonnes à la première compilation et l'écrit dans le fichier |aux| pour pouvoir l'utiliser à la compilation suivante. \textsl{Néanmoins, il est possible de donner le numéro de la dernière rangée et @@ -2466,7 +2543,7 @@ Pour la clarté, dans la suite, on utilisera ces noms-là. \smallskip L'option |xdots/color| indique bien entendu la couleur de la ligne tracée. On remarquera néanmoins que les lignes tracées dans les rangées et colonnes -extérieures (décrites plus loin) bénificient d'un régime spécial : cf. +extérieures (décrites plus loin) bénéficient d'un régime spécial : cf. p.~\pageref{exterior}. @@ -2545,8 +2622,8 @@ b & a & b & \Ddots & & \Vdots \\ Les lignes pointillées délimitent des blocs virtuels qui ont le même comportement vis à vis des filets que les blocs créés par |\Block| (les filets spécifiés par le spécificateur \verb+|+ dans le préambule, la commande |\Hline| -et par les clés |vlines|, |hlines| et |hvlines| ne sont pas tracés dans les -blocs).\footnote{En revanche, la commande \verb|\line| dans le \verb|\CodeAfter| +et par les clés |vlines|, |hlines|, |hvlines| et |hvlines-except-borders| ne +sont pas tracés dans les blocs).\footnote{En revanche, la commande \verb|\line| dans le \verb|\CodeAfter| (cf.~p.~\pageref{line-in-code-after}) ne crée pas de bloc.} \medskip @@ -2707,7 +2784,7 @@ $\begin{NiceArray}{ccc@{\hspace{1.5em}}c}[cell-space-limits=2pt,margin] \bigskip \colorbox{yellow!50}{\bfseries Nouveau 5.18}\enskip La commande |\SubMatrix| accepte en fait également deux arguments optionnels spécifiés par les symboles -traditionnels |^| et |_| pour des élements en exposant et en indice. +traditionnels |^| et |_| pour des éléments en exposant et en indice. \medskip \begin{scope} @@ -3184,14 +3261,14 @@ Pour un exemple de personnalisation des notes de tableau, voir p.~\pageref{ex:no \subsection{Utilisation de \{NiceTabular\} avec threeparttable} -Si vous souhaitez utiliser l'environnement |{NiceTabular}| ou |{NiceTabular*}| -dans un environnement |{threeparttable}| de l'extension éponyme, vous devez -patcher |{threeparttable}| avec le code suivant (avec une version de LaTeX -postérieure à 2020/10/01). +Si vous souhaitez utiliser les environnements |{NiceTabular}|, |{NiceTabular*}| +ou |{NiceTabularX}| dans un environnement |{threeparttable}| de l'extension +éponyme, vous devez patcher l'environnement |{threeparttable}| avec le code +suivant (avec une version de LaTeX postérieure à 2020/10/01). \begin{Verbatim}[commandchars=\~\#\!] \makeatletter \AddToHook{env/threeparttable/begin} - {\TPT@hookin{NiceTabular}\TPT@hookin{NiceTabular*}} + {\TPT@hookin{NiceTabular}\TPT@hookin{NiceTabular*}\TPT@hookin{NiceTabularX}} \makeatother \end{Verbatim} @@ -3369,7 +3446,7 @@ colonne courante\footnote{On rappelle que le numéro de la «première rangée» existe) est $0$ également.}. Bien entendu, l'utilisateur ne doit pas modifier les valeurs de ces compteurs qui sont utilisés en interne par \pkg{nicematrix}. -Dans le |code-before| (cf. p. \pageref{code-before}) et dans le |\CodeAfter| +Dans le |\CodeBefore| (cf. p. \pageref{code-before}) et dans le |\CodeAfter| (cf. p. \pageref{code-after}), |iRow| représente le nombre total de rangées (hors éventuelles rangées extérieures) et |jCol| le nombre total de colonnes (hors potentielles colonnes extérieures). @@ -3412,8 +3489,8 @@ nommées |\AutoNiceMatrix|, |\pAutoNiceMatrix|, |\bAutoNiceMatrix|, Chacune de ces commandes prend deux arguments obligatoires : le premier est la taille de la matrice, sous la forme $n$-$p$, où $n$ est le nombre de rangées et $p$ est le nombre de colonnes et le deuxième est le motif (c'est-à-dire -simplement des tokens qui seront insérés dans chaque case de la matrice, -exceptées celles des éventuelles rangées et colonnes extérieures). +simplement des tokens qui seront insérés dans chaque case de la matrice). + \medskip \begin{Verbatim} @@ -4003,78 +4080,99 @@ L'extension \pkg{nicematrix} fournit deux variables internes mais publiques\foot \end{itemize} \medskip -Ces variables constituent le code du «|code-before|» et du «|code-after|». Le -développeur peut donc les utiliser pour y ajouter du code à partir d'une case -du tableau (l'affectation devra être globale, ce qui permettra de sortir de la -case, qui est un groupe au sens de TeX). +Ces variables constituent le code du «|code-before|» (que l'on rentre souvent +avec la syntaxte utilisant |\CodeBefore| et |\Body| en début d'environnement et +du «|code-after|» (que l'on rentre souvent en fin d'environnement après le +mot-clé |\CodeAfter|). Le développeur peut donc les utiliser pour y ajouter du +code à partir d'une case du tableau (l'affectation devra être globale, ce qui +permettra de sortir de la case, qui est un groupe au sens de TeX). \medskip On remarquera que l'utilisation de |\g_nicematrix_code_before_tl| nécessite une compilation supplémentaire (car les instructions sont écrites dans le fichier |aux| pour être utilisées à la compilation suivante). -\bigskip -\emph{Example} : On souhaite écrire une commande |\hatchcell| pour hachurer la -case courante (avec un argument optionnel entre crochets pour la couleur des -hachures). Il est possible de programmer une telle commande |\hatchcell| comme -suit, en utilisant explicitement la variable publique -|\g_nicematrix_code_before_tl| (ce code nécessite le chargement préalable de la -bibliothèque Tikz \pkg{patterns} : |\usetikzlibrary{patterns}|). + + + +\medskip +\emph{Exemple} : On souhaite écrire une commande |\crossbox| qui barre en croix +la cellule courante. Cette commande prendra en argument optionnel une liste de +couples \textsl{clé}-\textsl{valeur} qui sera passée à Tikz avant que la croix +ne soit tracée. + + +On peut alors programmer cette commande |\crossbox| de la manière suivante, qui +utilise explicitement la variable publique |\g_nicematrix_code_after_tl|. \begin{scope} \fvset{commandchars=\§\¤\μ} \begin{Verbatim} \ExplSyntaxOn -\cs_new_protected:Nn \__pantigny_hatch:nnn +\cs_new_protected:Nn \__pantigny_crossbox:nnn { - \tikz \fill [ pattern = north~west~lines , pattern~color = #3 ] - ( #1 -| #2) rectangle ( \int_eval:n { #1 + 1 } -| \int_eval:n { #2 + 1 } ) ; + \tikz \draw [ #3 ] + ( #1 -| \int_eval:n { #2 + 1 } ) -- ( \int_eval:n { #1 + 1 } -| #2 ) + ( #1 -| #2 ) -- ( \int_eval:n { #1 + 1 } -| \int_eval:n { #2 + 1 } ) ; } -\NewDocumentCommand \hatchcell { ! O { black } } +\NewDocumentCommand \crossbox { ! O { } } { - \tl_gput_right:Nx §emphase¤\g_nicematrix_code_before_tlμ - { \__pantigny_hatch:nnn { \arabic { iRow } } { \arabic { jCol } } { #1 } } + \tl_gput_right:Nx §emphase¤\g_nicematrix_code_after_tlμ + { + \__pantigny_crossbox:nnn + { \int_use:c { c@iRow } } + { \int_use:c { c@jCol } } + { \exp_not:n { #1 } } + } } \ExplSyntaxOff \end{Verbatim} \end{scope} + \ExplSyntaxOn -\cs_new_protected:Nn \__pantigny_hatch:nnn +\cs_new_protected:Nn \__pantigny_crossbox:nnn { - \tikz \fill [ pattern = north~west~lines , pattern~color = #3 ] - ( #1 -| #2 ) rectangle ( \int_eval:n { #1 + 1 } -| \int_eval:n { #2 + 1 } ) ; + \tikz \draw [ #3 ] + ( #1 -| \int_eval:n { #2 + 1 } ) -- ( \int_eval:n { #1 + 1 } -| #2 ) + ( #1 -| #2 ) -- ( \int_eval:n { #1 + 1 } -| \int_eval:n { #2 + 1 } ) ; } -\NewDocumentCommand \hatchcell { ! O { black } } + +\NewDocumentCommand \crossbox { ! O { } } { - \tl_gput_right:Nx \g_nicematrix_code_before_tl - { \__pantigny_hatch:nnn { \arabic { iRow } } { \arabic { jCol } } { #1 } } + \tl_gput_right:Nx \g_nicematrix_code_after_tl + { + \__pantigny_crossbox:nnn + { \int_use:c { c@iRow } } + { \int_use:c { c@jCol } } + { \exp_not:n { #1 } } + } } \ExplSyntaxOff - - \bigskip -Voici un exemple d'utilisation. +Voici un exemple d'utilisation : \medskip \begin{BVerbatim}[baseline=c,boxwidth=9cm] \begin{NiceTabular}{ccc}[hvlines] -Tokyo & Paris & Londres \\ -Lima & ~emphase#\hatchcell[blue!30]@Oslo & Miami \\ -Los Angeles & Madrid & Rome +merlan & requin & cabillaud \\ +baleine & ~emphase#\crossbox[red]@ & morue \\ +mante & raie & poule \end{NiceTabular} \end{BVerbatim} \begin{NiceTabular}{ccc}[hvlines] -Tokyo & Paris & Londres \\ -Lima & \hatchcell[blue!30]Oslo & Miami \\ -Los Angeles & Madrid & Rome +merlan & requin & cabillaud \\ +baleine & \crossbox[red] & morue \\ +mante & raie & poule \end{NiceTabular} + + \section{Remarques techniques} Première remarque : l'extension \pkg{nicematrix} doit être chargée après @@ -4836,13 +4934,13 @@ a_{41} & a_{42} & a_{43} & \Block[draw]{}{a_{44}} \\ On remarquera que les traits que l'on vient de tracer sont dessinés \emph{après} la matrice sans modifier la position des composantes de celle-ci. En revanche, -les traits tracés par |\hline|, |\Hline|, le spécificateur «\verb+|+» ou les options -|hlines|, |vlines| et |hvlines| «écartent» les composantes de la -matrice.\footnote{Pour la commande |\cline|, voir la remarque +les traits tracés par |\hline|, |\Hline|, le spécificateur «\verb+|+» ou les +options |hlines|, |vlines|, |hvlines| et |hvlines-except-borders| «écartent» les +composantes de la matrice.\footnote{Pour la commande |\cline|, voir la remarque p.~\pageref{remark-cline}.} \vspace{1cm} -Il est possible de colorier une rangée avec |\rowcolor| dans le |code-before| +Il est possible de colorier une rangée avec |\rowcolor| dans le |\CodeBefore| (ou avec |\rowcolor| dans une case de la rangée si on utilise la clé |colortbl-like| − même si \pkg{colortbl} n'est pas chargé). diff --git a/Master/texmf-dist/doc/latex/nicematrix/nicematrix.pdf b/Master/texmf-dist/doc/latex/nicematrix/nicematrix.pdf index db334606dab..12158c89540 100644 Binary files a/Master/texmf-dist/doc/latex/nicematrix/nicematrix.pdf and b/Master/texmf-dist/doc/latex/nicematrix/nicematrix.pdf differ -- cgit v1.2.3