nicematrix (2jan20)

git-svn-id: svn://tug.org/texlive/trunk@53304 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 137 insertions, 89 deletions

diff --git a/Master/texmf-dist/source/latex/nicematrix/nicematrix.dtx b/Master/texmf-dist/source/latex/nicematrix/nicematrix.dtx
index 5aa62110929..3b0f3fcad4a 100644
--- a/Master/texmf-dist/source/latex/nicematrix/nicematrix.dtx
+++ b/Master/texmf-dist/source/latex/nicematrix/nicematrix.dtx
@@ -15,8 +15,8 @@
 %
 % \fi
 % \iffalse
-\def\myfileversion{3.7}
-\def\myfiledate{2019/11/11}
+\def\myfileversion{3.8}
+\def\myfiledate{2020/01/02}
 %
 %
 %<*batchfile>
@@ -1240,6 +1240,9 @@ c & c & b & a & e
 %
 % \section{Block matrices}
 %
+% This section has no direct link with the previous one where an environment
+% |{NiceMatrixBlock}| was introduced.
+% 
 % In the environments of \pkg{nicematrix}, it's possible to use the command
 % |\Block| in order to place an element in the center of a rectangle of merged
 % cells of the array.
@@ -1364,7 +1367,7 @@ c & c & b & a & e
 % In the cells of the array, it's possible to use the LaTeX counters |iRow| and
 % |jCol| which represent the number of the current row and the number of the
 % current col\footnote{We recall that the first row (if it exists) has the
-% number~$0$ and that the first col (if it exists) has also the number~$0$).}.
+% number~$0$ and that the first col (if it exists) has also the number~$0$.}.
 % Of course, the user must not change the value of these counters which are used
 % internally by \pkg{nicematrix}.
 %
@@ -1740,7 +1743,12 @@ c & c & b & a & e
 % |{VNiceArrayRC}|.
 % \end{itemize}
 %       
-% They might be deleted in a future version of \pkg{nicematrix}.
+% Since the version 3.8, an error is raised when one of these environments is
+% used. It's still possible to use these environments by loading
+% \pkg{nicematrix} with the option |obsolete-environments|.
+%
+% However, these environments will probably be completely deleted in future
+% version of \pkg{nicematrix}.
 %
 % \section{Examples}
 %
@@ -2401,9 +2409,7 @@ c & c & b & a & e
 % |expl3| code fails.\footnote{cf.
 % |tex.stackexchange.com/questions/57424/using-of-usetikzlibrary-in-an-expl3-package-fails|}  
 % 
-%    \begin{macrocode}
-%<@@=nm>
-%    \end{macrocode}
+%<@@=nicematrix>
 %
 %    \begin{macrocode}
 \RequirePackage{tikz}
@@ -2970,13 +2976,9 @@ c & c & b & a & e
 \keys_define:nn { NiceMatrix / Global }
   {
     code-for-first-col .tl_set:N = \l_@@_code_for_first_col_tl ,
-    code-for-first-col .value_required:n = true ,
     code-for-last-col .tl_set:N = \l_@@_code_for_last_col_tl ,
-    code-for-last-col .value_required:n = true ,
     code-for-first-row .tl_set:N = \l_@@_code_for_first_row_tl ,
-    code-for-first-row .value_required:n = true ,
     code-for-last-row .tl_set:N = \l_@@_code_for_last_row_tl ,
-    code-for-last-row .value_required:n = true ,
     small .bool_set:N = \l_@@_small_bool ,
     hlines .bool_set:N = \l_@@_hlines_bool ,
     parallelize-diags .bool_set:N = \l_@@_parallelize_diags_bool ,
@@ -2988,7 +2990,7 @@ c & c & b & a & e
 % |\Vdots| and |\Ddots|. 
 %    \begin{macrocode}
     renew-dots .bool_set:N = \l_@@_renew_dots_bool ,
-    renew-dots .value_forbidden:n = true ,
+
     nullify-dots .bool_set:N = \l_@@_nullify_dots_bool ,
 %    \end{macrocode}
 %
@@ -3009,6 +3011,20 @@ c & c & b & a & e
     extra-right-margin .dim_set:N = \l_@@_extra_right_margin_dim ,
     extra-margin .meta:n = 
      { extra-left-margin = #1 , extra-right-margin = #1 } ,
+%    \end{macrocode}
+% The following lines are the properties |.value_required:n| and
+% |.value_forbidden:n| or the keys. These properties have no effect because they
+% are not transmitted by inheritance (unfortunately). We maintain these lines in
+% the \textsc{dtx} only for the case of a modification of |l3keys|.
+% 
+%    \begin{macrocode}
+%<*comment>
+    code-for-first-col .value_required:n = true ,
+    code-for-last-col .value_required:n = true ,
+    code-for-first-row .value_required:n = true ,
+    code-for-last-row .value_required:n = true ,
+    renew-dots .value_forbidden:n = true ,
+%</comment>
   }
 %    \end{macrocode}
 %
@@ -3022,7 +3038,6 @@ c & c & b & a & e
       \str_if_eq:nnTF { #1 } { auto }
         { \bool_set_true:N \l_@@_auto_columns_width_bool }
         { \dim_set:Nn \l_@@_columns_width_dim { #1 } } , 
-    columns-width .value_required:n = true ,
     name .code:n = 
       \unless \ifmeasuring@
          \str_set:Nn \l_tmpa_str { #1 }
@@ -3031,13 +3046,23 @@ c & c & b & a & e
            { \seq_gput_left:NV \g_@@_names_seq \l_tmpa_str }
          \str_set_eq:NN \l_@@_name_str \l_tmpa_str 
       \fi ,
-    name .value_required:n = true ,
     code-after .tl_gset:N = \g_@@_code_after_tl ,
-    code-after .value_required:n = true ,
     first-col .code:n = \int_zero:N \l_@@_first_col_int , 
     first-row .code:n = \int_zero:N \l_@@_first_row_int ,
     last-row .int_set:N = \l_@@_last_row_int ,
     last-row .default:n = -1 ,
+%    \end{macrocode}
+% The following lines are the properties |.value_required:n| and
+% |.value_forbidden:n| or the keys. These properties have no effect because they
+% are not transmitted by inheritance (unfortunately). We maintain these lines in
+% the \textsc{dtx} only for the case of a modification of |l3keys|.
+% 
+%    \begin{macrocode}
+%<*comment>
+    columns-width .value_required:n = true ,
+    name .value_required:n = true ,
+    code-after .value_required:n = true ,
+%</comment>
   }
 %    \end{macrocode}
 % 
@@ -5124,10 +5149,7 @@ c & c & b & a & e
           {
             \begin { tikzpicture } [ remember~picture ]
             \tikz@parse@node \pgfutil@firstofone
-              ( 
-                nm - \int_use:N \g_@@_env_int - col - 
-                \int_use:N \c@jCol 
-              ) 
+              ( nm - \int_use:N \g_@@_env_int - col - \int_use:N \c@jCol )
             \dim_gset:Nn \g_@@_x_final_dim \pgf@x
             \end { tikzpicture }
           }
@@ -6477,13 +6499,12 @@ c & c & b & a & e
 % has no direct link with the environment |{NiceMatrixBlock}|.
 % 
 % The following command will be linked to |\Block| in the environments of
-% \pkg{nicematrix}. We define it with |\NewExpandableDocumentCommand| of
-% \pkg{xparse} because it has an optionnal argument between |<| and |>| (for TeX
-% instructions put before the math mode of the label) and because it must be
-% expandable since it reduces (in the case of a block of only one row) to a
-% command |\multicolumn|. 
+% \pkg{nicematrix}. We define it with |\NewDocumentCommand| of \pkg{xparse}
+% because it has an optionnal argument between |<| and |>| (for TeX instructions
+% put before the math mode of the label)
+%
 %    \begin{macrocode}
-\NewExpandableDocumentCommand \@@_Block: { m D < > { } m }
+\NewDocumentCommand \@@_Block: { m D < > { } m }
   { \@@_Block_i #1 \q_stop { #2 } { #3 } }
 %    \end{macrocode}
 % 
@@ -6507,25 +6528,20 @@ c & c & b & a & e
 %    \end{macrocode}
 % 
 % \medskip
-% In the case of a block of only one row, we use a |\multicolumn| and not the
-% general technique because, in this case, we want the label perfectly aligned
-% with the base line of that row of the array.
+% In the case of a block of only one row, we create a special node of shape
+% |coordinate| in order to remember the $y$-value of the baseline of the current
+% row. 
 %    \begin{macrocode}
-    \int_compare:nNnTF { #1 } = 1
+    \int_compare:nNnT { #1 } = 1
       {
-        \multicolumn { #2 } { C } { \hbox:n { #3 $#4$ } }
-        \@@_gobble_ampersands:n { #2 - 1 }
+        \begin { tikzpicture } [ remember~picture , baseline ] 
+          \coordinate
+            ( nm - \int_use:N \g_@@_env_int 
+                 - Block
+                 - \int_use:N \c@iRow 
+                 - \int_use:N \c@jCol ) ;
+        \end { tikzpicture }
       }
-      { \@@_Block_iii:nnnn { #1 } { #2 } { #3 } { #4 } }
-  }
-%    \end{macrocode}
-%
-% \medskip
-% The command |\@@_Block_iii:nnnn| is for the case of a block of $n$~rows with
-% $n>1$. 
-%    \begin{macrocode}
-\cs_new_protected:Npn \@@_Block_iii:nnnn #1 #2 #3 #4
-  {
     \bool_gset_true:N \g_@@_extra_nodes_bool
 %    \end{macrocode}
 % We write an instruction in the |code-after|. We write the instruction in the
@@ -6536,7 +6552,7 @@ c & c & b & a & e
 %    \begin{macrocode}
     \tl_gput_left:Nx \g_@@_code_after_tl
       {
-        \@@_Block_iv:nnnnn
+        \@@_Block_iii:nnnnn
           { \int_use:N \c@iRow }
           { \int_use:N \c@jCol }
           { \int_eval:n { \c@iRow + #1 - 1 } }
@@ -6546,31 +6562,12 @@ c & c & b & a & e
   }
 %    \end{macrocode}
 %
-% \medskip
-% The command |\@@_gobble_ampersands:n| will gobble $n$ ampersands (and also the
-% spaces) where $n$ is the argument of the command. This command is fully
-% expandable and we need this feature.
-%    \begin{macrocode}
-\group_begin:
-  \char_set_catcode_letter:N \&
-  \cs_new:Npn \@@_gobble_ampersands:n #1 
-    {
-      \int_compare:nNnT { #1 } > 0 
-        { 
-          \peek_charcode_remove_ignore_spaces:NT & 
-            { \@@_gobble_ampersands:n { #1 - 1 } } 
-        }
-    }
-\group_end:
-%    \end{macrocode}
-%                          
+% 
 %
 % \medskip
 % The following command |\@@_Block_iii:nnnnn| will be used in the |code-after|.
-% It's necessary to create two Tikz nodes because we want the label |#5| really
-% drawn in the \emph{center} of the node.
 %    \begin{macrocode}
-\cs_new_protected:Npn \@@_Block_iv:nnnnn #1 #2 #3 #4 #5
+\cs_new_protected:Npn \@@_Block_iii:nnnnn #1 #2 #3 #4 #5
   { 
     \bool_if:nTF
       { 
@@ -6579,23 +6576,59 @@ c & c & b & a & e
       }
       { \msg_error:nnnn { nicematrix } { Block~too~large } { #1 } { #2 } }
       {
-        \begin{tikzpicture}
-        \node 
-          [ 
-            fit = ( #1 - #2 - medium . north~west ) 
-                  ( #3 - #4 - medium . south~east ) ,
-            inner~sep = 0 pt ,
-          ] 
+%    \end{macrocode}
+% If the block has only one row, we have to do a special work in order to have
+% the contains of the node aligned with the contents of the other rows of the array.
+% 
+%    \begin{macrocode}
+        \int_compare:nNnTF { #1 } = { #3 }
+          {
+            \begin { tikzpicture }
+%    \end{macrocode}
+% First, we compute in |\l_tmpa_dim| the $y$-value of the baseline of the row.
+% We have constructed a special node of shape |coordinate| in this order.
+%    \begin{macrocode}
+              \tikz@parse@node \pgfutil@firstofone (Block-#1-#2) 
+              \dim_set:Nn \l_tmpa_dim \pgf@y
+              \node 
+                [ 
+                  fit = ( #1 - #2 - medium . north~west ) 
+                        ( #3 - #4 - medium . south~east ) ,
+                  inner~sep = 0 pt ,
+                ] 
+              (#1-#2) { } ;
+%    \end{macrocode}
+% With the following instruction, we retrieve the $x$-value and the $y$-value of
+% the center of the block. We will only use the $x$-value, available in |\pgf@x|.
+%    \begin{macrocode}
+              \tikz@parse@node \pgfutil@firstofone (#1-#2) 
+              \path (\pgf@x,\l_tmpa_dim) node [ anchor = base ] { #5 } ; 
+            \end { tikzpicture }
+          }
+%    \end{macrocode}
+% If the number of rows is different of $1$, it's necessary to create two Tikz
+% nodes because we want the label |#5| really drawn in the \emph{center} of the node.
+%    \begin{macrocode}
+          {
+            \begin { tikzpicture }
+            \node 
+              [ 
+                fit = ( #1 - #2 - medium . north~west ) 
+                      ( #3 - #4 - medium . south~east ) ,
+                inner~sep = 0 pt ,
+              ] 
 %    \end{macrocode}
 % We don't forget the name of the node because the user may wish to use it.
 %    \begin{macrocode}
-          (#1-#2) { } ;
-         \node at (#1-#2.center) { #5 } ;
-    \end{tikzpicture}
+              (#1-#2) { } ;
+             \node at (#1-#2.center) { #5 } ;
+             \end { tikzpicture }
+          }  
       }
   }
 %    \end{macrocode}
 %                          
+%
 % \subsection{How to draw the dotted lines transparently}
 %    \begin{macrocode}
 \cs_set_protected:Npn \@@_renew_matrix:
@@ -6678,7 +6711,7 @@ c & c & b & a & e
         \AutoNiceMatrixWithDelims { #2 } { #3 }
       }  
   }
-%    \end{document}
+%    \end{macrocode}
 %    \begin{macrocode}
 \@@_define_com:nnn p ( ) 
 \@@_define_com:nnn b [ ]
@@ -6708,6 +6741,8 @@ c & c & b & a & e
     renew-matrix .value_forbidden:n = true ,
     transparent .meta:n = { renew-dots , renew-matrix } ,
     transparent .value_forbidden:n = true,
+    obsolete-environments .code:n = 
+      \@@_msg_redirect_name:nn { Obsolete~environment } { none }
   }
 \ProcessKeysOptions { NiceMatrix / Package }
 %    \end{macrocode}
@@ -6973,15 +7008,17 @@ c & c & b & a & e
 %    \begin{macrocode}
 \@@_msg_new:nn { Obsolete~environment }
   {
-    The~environment~\{\@currenvir\}~is~obsolete~and~will~be~deleted~in~future~version.~ 
-    We~should~use~#1~instead.
+    The~environment~\{\@currenvir\}~is~obsolete.~We~should~use~#1~instead.~
+    However,~you~can~go~on~for~this~time.~
+    If~you~don't~want~to~see~this~error~again,~you~should~load~'nicematrix'~
+    with~the~option~'obsolete-environments'.
   }
 %    \end{macrocode}
 %
 %    \begin{macrocode} 
 \NewDocumentEnvironment { pNiceArrayC } { }
   {
-    \msg_info:nnn { nicematrix } { Obsolete~environment } 
+    \@@_error:nn { Obsolete~environment } 
       { the~option~'last-col' }
     \int_set:Nn \l_@@_last_col_int \c_zero_dim
     \pNiceArray
@@ -6992,7 +7029,7 @@ c & c & b & a & e
 %    \begin{macrocode} 
 \NewDocumentEnvironment { bNiceArrayC } { }
   {
-    \msg_info:nnn { nicematrix } { Obsolete~environment } 
+    \@@_error:nn { Obsolete~environment } 
       { the~option~'last-col' }
     \int_set:Nn \l_@@_last_col_int \c_zero_dim
     \bNiceArray
@@ -7003,7 +7040,7 @@ c & c & b & a & e
 %    \begin{macrocode} 
 \NewDocumentEnvironment { BNiceArrayC } { }
   {
-    \msg_info:nnn { nicematrix } { Obsolete~environment } 
+    \@@_error:nn { Obsolete~environment } 
       { the~option~'last-col' }
     \int_set:Nn \l_@@_last_col_int \c_zero_dim
     \BNiceArray
@@ -7014,7 +7051,7 @@ c & c & b & a & e
 %    \begin{macrocode} 
 \NewDocumentEnvironment { vNiceArrayC } { }
   {
-    \msg_info:nnn { nicematrix } { Obsolete~environment } 
+    \@@_error:nn { Obsolete~environment } 
       { the~option~'last-col' }
     \int_set:Nn \l_@@_last_col_int \c_zero_dim
     \vNiceArray
@@ -7025,7 +7062,7 @@ c & c & b & a & e
 %    \begin{macrocode} 
 \NewDocumentEnvironment { VNiceArrayC } { }
   {
-    \msg_info:nnn { nicematrix } { Obsolete~environment } 
+    \@@_error:nn { Obsolete~environment } 
       { the~option~'last-col' }
     \int_set:Nn \l_@@_last_col_int \c_zero_dim
     \VNiceArray
@@ -7036,7 +7073,7 @@ c & c & b & a & e
 %    \begin{macrocode} 
 \NewDocumentEnvironment { pNiceArrayRC } { }
   {
-    \msg_info:nnn { nicematrix } { Obsolete~environment } 
+    \@@_error:nn { Obsolete~environment } 
       { the~options~'last-col'~and~'first-row' } 
     \int_set:Nn \l_@@_last_col_int \c_zero_dim
     \int_set:Nn \l_@@_first_row_int \c_zero_int
@@ -7048,7 +7085,7 @@ c & c & b & a & e
 %    \begin{macrocode} 
 \NewDocumentEnvironment { bNiceArrayRC } { }
   {
-    \msg_info:nnn { nicematrix } { Obsolete~environment } 
+    \@@_error:nn { Obsolete~environment } 
       { the~options~'last-col'~and~'first-row' } 
     \int_set:Nn \l_@@_last_col_int \c_zero_dim
     \int_set:Nn \l_@@_first_row_int \c_zero_int
@@ -7060,7 +7097,7 @@ c & c & b & a & e
 %    \begin{macrocode} 
 \NewDocumentEnvironment { BNiceArrayRC } { }
   {
-    \msg_info:nnn { nicematrix } { Obsolete~environment } 
+    \@@_error:nn { Obsolete~environment } 
       { the~options~'last-col'~and~'first-row' } 
     \int_set:Nn \l_@@_last_col_int \c_zero_dim
     \int_set:Nn \l_@@_first_row_int \c_zero_int
@@ -7072,7 +7109,7 @@ c & c & b & a & e
 %    \begin{macrocode} 
 \NewDocumentEnvironment { vNiceArrayRC } { }
   {
-    \msg_info:nnn { nicematrix } { Obsolete~environment } 
+    \@@_error:nn { Obsolete~environment } 
       { the~options~'last-col'~and~'first-row' } 
     \bool_set_true:N \l_@@_last_col_bool
     \int_set:Nn \l_@@_first_row_int \c_zero_int
@@ -7084,7 +7121,7 @@ c & c & b & a & e
 %    \begin{macrocode} 
 \NewDocumentEnvironment { VNiceArrayRC } { }
   {
-    \msg_info:nnn { nicematrix } { Obsolete~environment } 
+    \@@_error:nn { Obsolete~environment } 
       { the~options~'last-col'~and~'first-row' } 
     \int_set:Nn \l_@@_last_col_int \c_zero_dim
     \int_set:Nn \l_@@_first_row_int \c_zero_int
@@ -7096,7 +7133,7 @@ c & c & b & a & e
 %    \begin{macrocode} 
 \NewDocumentEnvironment { NiceArrayCwithDelims } { }
   {
-    \msg_info:nnn { nicematrix } { Obsolete~environment } 
+    \@@_error:nn { Obsolete~environment } 
       { the~option~'last-col' }
     \int_set:Nn \l_@@_last_col_int \c_zero_dim
     \NiceArrayWithDelims
@@ -7107,7 +7144,7 @@ c & c & b & a & e
 %    \begin{macrocode} 
 \NewDocumentEnvironment { NiceArrayRCwithDelims } { }
   {
-    \msg_info:nnn { nicematrix } { Obsolete~environment } 
+    \@@_error:nn { Obsolete~environment } 
       { the~options~'last-col'~and~'first-row' } 
     \int_set:Nn \l_@@_last_col_int \c_zero_dim
     \int_set:Nn \l_@@_first_row_int \c_zero_int
@@ -7324,7 +7361,18 @@ c & c & b & a & e
 % codes: |code-for-first-col|, |code-for-last-col|, |code-for-first-row| and
 % |code-for-last-row|. 
 %
-% New command |\pAutoNiceMatrix| and its variants (suggestion of Christophe Bal).
+% New command |\pAutoNiceMatrix| and its variants (suggestion of Christophe
+% Bal).
+%
+% \subsection*{Changes between version 3.7 and 3.8} 
+%
+% New programmation for the command |\Block| when the block has only one row. 
+% With this programmation, the vertical rules drawn by the specifier
+% ``\verb+|+'' at the end of the block is actually drawn. In previous versions,
+% they were not because the block of one row was constructed with
+% |\multicolumn|. 
+%
+% An error is raised when an obsolete environment is used.
 % 
 % \PrintIndex
 %