nicematrix (3sep20)

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

1 files changed, 320 insertions, 112 deletions

diff --git a/Master/texmf-dist/source/latex/nicematrix/nicematrix.dtx b/Master/texmf-dist/source/latex/nicematrix/nicematrix.dtx
index 10e84b7b070..03a6705cd39 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{5.2}
-\def\myfiledate{2020/08/19}
+\def\myfileversion{5.3}
+\def\myfiledate{2020/09/03}
 %
 %
 %<*batchfile>
@@ -409,7 +409,7 @@ version 2005/12/01 or later.
 % \end{minipage}
 % 
 % \bigskip
-% \colorbox{yellow!50}{\textbf{New 5.2}}\enskip It's also possible to use the
+% \colorbox{yellow!30}{\textbf{New 5.2}}\enskip It's also possible to use the
 % key |baseline| to align a matrix on an horizontal rule (drawn by |\hline|). In
 % this aim, one should give the value |line-|\textsl{i} where \textsl{i} is the
 % number of the row following the horizontal rule.
@@ -518,6 +518,11 @@ version 2005/12/01 or later.
 % \end{center}
 %
 %
+% \interitem
+% \colorbox{yellow!50}{\textbf{New 5.3}}\enskip 
+%
+% It's possible to use with the command |\Block| the options |l|, |r| and |c|
+% for the horizontal positionning.
 %
 %
 % \interitem
@@ -603,7 +608,7 @@ version 2005/12/01 or later.
 %
 %
 % \bigskip
-% \colorbox{yellow!50}{\textbf{New 5.2}}\enskip However, the vertical rules are
+% \colorbox{yellow!30}{\textbf{New 5.2}}\enskip However, the vertical rules are
 % not drawn in the blocks.
 %
 % \bigskip
@@ -837,7 +842,7 @@ version 2005/12/01 or later.
 % rectangles starting from the cell actually in the corner of the array.
 %
 % \bigskip
-% \colorbox{yellow!50}{\textbf{New 5.2}}\enskip It's possible to give as value to the
+% \colorbox{yellow!30}{\textbf{New 5.2}}\enskip It's possible to give as value to the
 % key |\hvlines-except-corners| a list of the corners to take into
 % consideration. The corners are designed by |NW|, |SW|, |NE| and |SE|
 % (\emph{north west}, \emph{south west}, \emph{north east} and \emph{south
@@ -1155,38 +1160,38 @@ version 2005/12/01 or later.
 % \end{scope}
 %
 % \bigskip
-% \colorbox{yellow!50}{\textbf{New 5.2}}\enskip There is a key |respect-blocks|
-% for the instruction |\rowcolor|. With that key, the ``rows'' alternately
+% \colorbox{yellow!30}{\textbf{New 5.2}}\enskip There is a key |respect-blocks|
+% for the instruction |\rowcolors|. With that key, the ``rows'' alternately
 % colored may extend over several row if they have to incorporate blocks.
 %
 % \medskip
 % \begin{scope}
 % \hfuzz=10cm
 % \begin{BVerbatim}[baseline=c,boxwidth=9cm]
-% \begin{NiceTabular}{cr}[hvlines,code-before =
+% \begin{NiceTabular}{lr}[hvlines,code-before =
 % ~emphase#\rowcolors{1}{blue!10}{}[respect-blocks]@]
-% \Block{2-1}{John} & 12 \\
+% \Block[l]{2-1}{John} & 12 \\
 %                     & 13 \\
 % Stephen & 8 \\
-% \Block{3-1}{Sarah} & 18 \\
+% \Block[l]{3-1}{Sarah} & 18 \\
 %                        & 17 \\
 %                        & 15 \\
 % Ashley & 20 \\
 % Henry & 14 \\
-% \Block{2-1}{Madison} & 15 \\
+% \Block[l]{2-1}{Madison} & 15 \\
 %                      & 19
 % \end{NiceTabular}
 % \end{BVerbatim}
-% \begin{NiceTabular}{cr}[hvlines,code-before = \rowcolors{1}{blue!10}{}[respect-blocks],baseline=c]
-% \Block{2-1}{John} & 12 \\
+% \begin{NiceTabular}{lr}[hvlines,code-before = \rowcolors{1}{blue!10}{}[respect-blocks],baseline=c]
+% \Block[l]{2-1}{John} & 12 \\
 %                     & 13 \\
 % Stephen & 8 \\
-% \Block{3-1}{Sarah} & 18 \\
+% \Block[l]{3-1}{Sarah} & 18 \\
 %                        & 17 \\
 %                        & 15 \\
 % Ashley & 20 \\
 % Henry & 14 \\
-% \Block{2-1}{Madison} & 15 \\
+% \Block[l]{2-1}{Madison} & 15 \\
 %                      & 19
 % \end{NiceTabular}
 % \end{scope}
@@ -1230,7 +1235,7 @@ version 2005/12/01 or later.
 % \begin{NiceTabular}[c]{lSSSS}%
 % [code-before = \rowcolor{red!15}{1-2} \rowcolors{3}{blue!15}{}]
 % ~emphase#\toprule@
-% \Block{2-1}{Product} \\
+% \Block{2-1}{Product} &
 % \Block{1-3}{dimensions (cm)} & & & 
 % \Block{2-1}{\rotate Price} \\
 % ~emphase#\cmidrule(rl){2-4}@
@@ -1280,14 +1285,15 @@ version 2005/12/01 or later.
 % the row;
 % \item |\columncolor| which must be used in the preamble of the environment
 % with the same syntax as the corresponding command of
-% \pkg{colortbl}\footnote{Unlike the command |\columncolor| of \pkg{colortbl},
+% \pkg{colortbl} (however, unlike the command |\columncolor| of \pkg{colortbl},
 % this command |\columncolor| can appear within another command, itself used in the
-% preamble.}. 
+% preamble). 
 % \end{itemize}
 %
 % \medskip
 % \begin{Verbatim}
-% \begin{NiceTabular}[colortbl-like]{*{2}{>{~emphase#\columncolor{blue!15}@}c}c}
+% \NewDocumentCommand { \Blue } { } { ~emphase#\columncolor{blue!15}@ }
+% \begin{NiceTabular}[colortbl-like]{>{\Blue}c>{\Blue}cc} 
 % \toprule
 % ~emphase#\rowcolor{red!15}@
 % Last name & First name & Birth day \\
@@ -1302,7 +1308,8 @@ version 2005/12/01 or later.
 %
 %
 % \begin{center}
-% \begin{NiceTabular}[colortbl-like]{*{2}{>{\columncolor{blue!15}}c}c}
+% \NewDocumentCommand { \Blue } { } { \columncolor{blue!15} }
+% \begin{NiceTabular}[colortbl-like]{>{\Blue}c>{\Blue}cc} 
 % \toprule
 % \rowcolor{red!15}
 % Last name & First name & Birth day \\
@@ -1319,8 +1326,8 @@ version 2005/12/01 or later.
 % Each instruction |\cellcolor|, |\rowcolor| or |\columncolor| will generate an
 % instruction |fill| (coded~|f|) in the resulting \textsc{pdf}. In cases of
 % juxtaposed colored rectangles, one may have a thin white color line in some
-% \textsc{pdf} viewers\footnote{For example SumatraPDF v3.1.2, which uses MuPDF
-% of Artifex Software, whose \textsc{pdf} renderer is called Fitz.} (between the
+% \textsc{pdf} viewers\footnote{For example SumatraPDF, which uses MuPDF
+% of Artifex Software, or PDF.js used by Firefox.} (between the
 % two first columns in the above example). In you want to avoid this problem,
 % you should use the tools in the |code-before|. That's what we do with the
 % following code.
@@ -1931,15 +1938,15 @@ version 2005/12/01 or later.
 % 
 % \subsection{How to generate the continuous dotted lines transparently}
 %
-% The package \pkg{nicematrix} provides an option called |transparent| for using
-% existing code transparently in the environments of the \pkg{amsmath} :
-% |{matrix}|, |{pmatrix}|, |{bmatrix}|, etc. In fact, this
-% option is an alias for the conjonction of two options: 
+% Imagine you have a document with a great number of mathematical matrices with
+% ellipsis. You may wish to use the dotted lines of \pkg{nicematrix} without
+% having to modify the code of each matrix. It's possible with the keys.
 % |renew-dots| and |renew-matrix|.\footnote{The options |renew-dots|,
-% |renew-matrix| and |transparent| can be fixed with the command
+% |renew-matrix| can be fixed with the command
 % |\NiceMatrixOptions| like the other options. However, they can also be fixed
-% as options of the command |\usepackage| (it's an exception for these three
-% specific options.)}
+% as options of the command |\usepackage|. There is also a key |transparent|
+% which is an alias for the conjonction of |renew-dots| and |renew-matrix| but it
+% must be considered as obsolete.}
 %
 % \smallskip
 %
@@ -1959,14 +1966,14 @@ version 2005/12/01 or later.
 % \end{itemize}
 %
 % \bigskip 
-% Therefore, with the option |transparent|, a classical code gives directly the
-% ouput of \pkg{nicematrix}.\par\nobreak
+% Therefore, with the keys |renew-dots| and |renew-matrix|, a classical code
+% gives directly the ouput of \pkg{nicematrix}.\par\nobreak
 %
 % \bigskip
 % \begin{scope}
-% \NiceMatrixOptions{transparent}
+% \NiceMatrixOptions{renew-dots,renew-matrix}
 % \begin{BVerbatim}[baseline=c,boxwidth=10cm]
-% ~emphase#\NiceMatrixOptions{transparent}@
+% ~emphase#\NiceMatrixOptions{renew-dots,renew-matrix}@
 % \begin{pmatrix}
 % 1      & \cdots & \cdots & 1      \\
 % 0      & \ddots &        & \vdots \\
@@ -2481,12 +2488,13 @@ version 2005/12/01 or later.
 % \subsection{Use of \{NiceTabular\} with threeparttable}
 %
 %
-% If you wish to use the environment |{NiceTabular}| in an environment
-% |{threeparttable}| of the eponymous package, you have to patch the environment
-% |{threeparttable}| with the following code:
+% If you wish to use the environment |{NiceTabular}| or |{NiceTabular*}| in an
+% environment |{threeparttable}| of the eponymous package, you have to patch the
+% environment |{threeparttable}| with the following code:
 % \begin{Verbatim}[commandchars=\~\#\!]
 % \makeatletter
-% \AtBeginEnvironment{threeparttable}{\TPT@hookin{NiceTabular}}
+% \AtBeginEnvironment{threeparttable}
+%   {\TPT@hookin{NiceTabular}\TPT@hookin{NiceTabular*}}
 % \makeatother
 % \end{Verbatim}
 %
@@ -3188,7 +3196,7 @@ version 2005/12/01 or later.
 % public and each variable with name beginning with |\g__nicematrix| or
 % |\l__nicematrix| is private.}: 
 % \begin{itemize}
-% \item \colorbox{yellow!50}{\textbf{New 5.2}}\enskip |\g_nicematrix_code_before_tl| ;
+% \item \colorbox{yellow!30}{\textbf{New 5.2}}\enskip |\g_nicematrix_code_before_tl| ;
 % \item |\g_nicematrix_code_after_tl|.
 % \end{itemize}
 % 
@@ -3400,9 +3408,13 @@ version 2005/12/01 or later.
 % a+b    & \Cdots  & a+b & 1
 % \end{pNiceMatrix}$
 %
-%
 % \end{scope}
 %
+% \colorbox{yellow!50}{\textbf{New 5.3}}\enskip It's possible to specify the
+% instruction |\Ddots| which will be drawn first (and which will be used to draw
+% the other diagonal dotted line when the parallelization is in force) with the
+% key |draw-first|: |\Ddots[draw-first]|.
+%
 % \subsection{The ``empty'' cells}
 % 
 % \label{empty-cells}
@@ -5017,8 +5029,8 @@ version 2005/12/01 or later.
 %    \end{macrocode}
 %
 % \bigskip
-% Some cells will be declared as ``empty'' (for example a cell with the
-% instrution |\Cdot|).
+% Some cells will be declared as ``empty'' (for example a cell with an
+% instrution |\Cdots|).
 %    \begin{macrocode}
 \bool_new:N \g_@@_empty_cell_bool
 %    \end{macrocode}
@@ -5087,6 +5099,19 @@ version 2005/12/01 or later.
 %    \begin{macrocode}
 \tl_new:N \l_@@_color_tl
 %    \end{macrocode}
+%
+% \medskip
+% The parameter of position of the label of a block (|c|, |r| or |l|).
+%    \begin{macrocode}
+\tl_new:N \l_@@_pos_of_block_tl
+\tl_set:Nn \l_@@_pos_of_block_tl { c }
+%    \end{macrocode}
+% 
+% \medskip
+% Used when the key |draw-first| is used for |\Ddots| or |\Iddots|.
+%    \begin{macrocode}
+\bool_new:N \l_@@_draw_first_bool
+%    \end{macrocode}
 % 
 % \bigskip
 % \textbf{Variables for the exterior rows and columns}\par\nobreak
@@ -5673,14 +5698,16 @@ version 2005/12/01 or later.
 %    \begin{macrocode}
     down .tl_set:N = \l_@@_xdots_down_tl ,
     up .tl_set:N = \l_@@_xdots_up_tl ,
+%    \end{macrocode}
+% The key |draw-first|, which is meant to be used only with |\Ddots| and
+% |\Iddots|, which be catched when |\Ddots| or |\Iddots| is used (during the
+% construction of the array and not when we draw the dotted lines).
+%    \begin{macrocode}
+    draw-first .code:n = \prg_do_nothing: ,
     unknown .code:n = \@@_error:n { Unknown~option~for~xdots } 
   }
 %    \end{macrocode}
 %
-% \bigskip
-% The following keys are for the tabular notes (specified by the command
-% |\tabularnote| inside |{NiceTabular}| and |{NiceArray}|).
-% 
 %
 % \bigskip
 %    \begin{macrocode}
@@ -5941,6 +5968,9 @@ version 2005/12/01 or later.
 %    \begin{macrocode}
     renew-matrix .code:n = \@@_renew_matrix: ,
     renew-matrix .value_forbidden:n = true ,
+%    \end{macrocode}
+% The key |transparent| is now considered as obsolete (because its name is ambiguous).
+%    \begin{macrocode}
     transparent .meta:n = { renew-dots , renew-matrix } ,
     transparent .value_forbidden:n = true,
 %    \end{macrocode}
@@ -6303,9 +6333,9 @@ version 2005/12/01 or later.
 %    \end{macrocode}
 % 
 % \interitem
-% The first argument of the following command |\@@_instruction_of_type:nn|
+% The second argument of the following command |\@@_instruction_of_type:nnn|
 % defined below is the type of the instruction (|Cdots|, |Vdots|, |Ddots|,
-% etc.). The second argument is the list of options. This command writes in the
+% etc.). The third argument is the list of options. This command writes in the
 % corresponding |\g_@@_|\textsl{type}|_lines_tl| the instruction which will
 % actually draw the line after the construction of the matrix.
 %
@@ -6339,21 +6369,23 @@ version 2005/12/01 or later.
 % 
 % 
 % \bigskip
+% The first argument is a boolean which indicates whether you must put the
+% instruction on the left or on the right on the list of instructions.
 %    \begin{macrocode}
-\cs_new_protected:Npn \@@_instruction_of_type:nn #1 #2
+\cs_new_protected:Npn \@@_instruction_of_type:nnn #1 #2 #3
   { 
 %    \end{macrocode}
 % It's important to use a |\tl_gput_right:cx| and not a |\tl_gput_left:cx|
 % because we want the |\Ddots| lines to be drawn in the order of appearance
 % in the array (for parallelisation).
 %    \begin{macrocode}
-    \tl_gput_right:cx 
-      { g_@@_ #1 _ lines _ tl }
+    \bool_if:nTF { #1 } \tl_gput_left:cx \tl_gput_right:cx 
+      { g_@@_ #2 _ lines _ tl }
       { 
-        \use:c { @@ _ draw _ #1 : nnn }
+        \use:c { @@ _ draw _ #2 : nnn }
           { \int_use:N \c@iRow } 
           { \int_use:N \c@jCol }
-          { \exp_not:n { #2 } } 
+          { \exp_not:n { #3 } } 
       }
   }  
 %    \end{macrocode}
@@ -6371,7 +6403,7 @@ version 2005/12/01 or later.
     \cs_set_eq:NN \@acoll \@arrayacol 
     \cs_set_eq:NN \@acolr \@arrayacol 
     \cs_set_eq:NN \@acol \@arrayacol 
-    \cs_set:Npn \@halignto { }
+    \cs_set_nopar:Npn \@halignto { }
     \@array@array
   }
 %    \end{macrocode}
@@ -6386,8 +6418,8 @@ version 2005/12/01 or later.
           { \dim_set_eq:NN \col@sep \tabcolsep }
           { \dim_set_eq:NN \col@sep \arraycolsep }
         \dim_compare:nNnTF \l_@@_tabular_width_dim = \c_zero_dim
-          { \cs_set:Npn \@halignto { } }
-          { \cs_set:Npx \@halignto { to \dim_use:N \l_@@_tabular_width_dim } }
+          { \cs_set_nopar:Npn \@halignto { } }
+          { \cs_set_nopar:Npx \@halignto { to \dim_use:N \l_@@_tabular_width_dim } }
 %    \end{macrocode}
 % It \pkg{colortbl} is loaded, |\@tabarray| has been redefined to incorporate
 % |\CT@start|. 
@@ -6568,7 +6600,7 @@ version 2005/12/01 or later.
       {
 %    \end{macrocode}
 %    \begin{macrocode}
-        \cs_set:Npn \arraystretch { 0.47 }
+        \cs_set_nopar:Npn \arraystretch { 0.47 }
         \dim_set:Nn \arraycolsep { 1.45 pt }
       }
 %    \end{macrocode}
@@ -6580,7 +6612,7 @@ version 2005/12/01 or later.
 % |\everycr| to |{ }| and we \emph{need} to have to change the value of
 % |\everycr|. 
 %    \begin{macrocode}
-    \cs_set:Npn \ialign 
+    \cs_set_nopar:Npn \ialign 
       { 
         \bool_if:NTF \c_@@_colortbl_loaded_bool
           {
@@ -6744,6 +6776,8 @@ version 2005/12/01 or later.
     \bgroup
     \tl_set:Nn \l_@@_left_delim_tl { #1 }
     \tl_set:Nn \l_@@_right_delim_tl { #2 }
+    \dim_zero:N \g_@@_width_last_col_dim
+    \dim_zero:N \g_@@_width_first_col_dim
     \bool_gset_false:N \g_@@_row_of_col_done_bool
     \str_if_empty:NT \g_@@_name_env_str 
       { \str_gset:Nn \g_@@_name_env_str { NiceArrayWithDelims } } 
@@ -8221,6 +8255,7 @@ version 2005/12/01 or later.
             \skip_horizontal:N \l_@@_left_margin_dim 
             \skip_horizontal:N \l_@@_extra_left_margin_dim
           }
+        \bool_gset_false:N \g_@@_empty_cell_bool
         \skip_horizontal:N -2\col@sep 
       }
   }
@@ -8290,6 +8325,7 @@ version 2005/12/01 or later.
                 \@@_node_for_the_cell:
               }
           } 
+        \bool_gset_false:N \g_@@_empty_cell_bool
       }
   }
 %    \end{macrocode}
@@ -8612,16 +8648,16 @@ version 2005/12/01 or later.
 % etc.) and no corners. In that case, we switch to a shortcut version of
 % |\@@_vline_i:nn| and |\@@_hline:nn|.
 %    \begin{macrocode}
-    % \bool_lazy_all:nT
-    %   { 
-    %     { \seq_if_empty_p:N \g_@@_pos_of_blocks_seq }
-    %     { \seq_if_empty_p:N \g_@@_pos_of_xdots_seq }
-    %     { \seq_if_empty_p:N \l_@@_empty_corner_cells_seq }
-    %   }
-    %   { 
-    %     \cs_set_eq:NN \@@_vline_i:nn \@@_vline_i_complete:nn 
-    %     \cs_set_eq:NN \@@_hline_i:nn \@@_hline_i_complete:nn 
-    %   }
+    \bool_lazy_all:nT
+      { 
+        { \seq_if_empty_p:N \g_@@_pos_of_blocks_seq }
+        { \seq_if_empty_p:N \g_@@_pos_of_xdots_seq }
+        { \seq_if_empty_p:N \l_@@_empty_corner_cells_seq }
+      }
+      { 
+        \cs_set_eq:NN \@@_vline_i:nn \@@_vline_i_complete:nn 
+        \cs_set_eq:NN \@@_hline_i:nn \@@_hline_i_complete:nn 
+      }
     \bool_if:NT \l_@@_hlines_bool \@@_draw_hlines: 
     \bool_if:NT \l_@@_vlines_bool \@@_draw_vlines: 
     \g_@@_internal_code_after_tl
@@ -9201,7 +9237,6 @@ version 2005/12/01 or later.
 %    \begin{macrocode}      
 \cs_new_protected:Npn \@@_draw_Vdots:nnn #1 #2 #3
   { 
-    \tl_if_empty:VF \l_@@_xdots_color_tl { \color { \l_@@_xdots_color_tl } }
     \cs_if_free:cT { @@ _ dotted _ #1 - #2 }
       {
         \@@_find_extremities_of_line:nnnn { #1 } { #2 } 1 0
@@ -9218,6 +9253,8 @@ version 2005/12/01 or later.
                 { \color { nicematrix-last-col } }
             }
           \keys_set:nn { NiceMatrix / xdots } { #3 }
+          \tl_if_empty:VF \l_@@_xdots_color_tl 
+            { \color { \l_@@_xdots_color_tl } }
           \@@_actually_draw_Vdots:
         \group_end:
       }
@@ -9796,7 +9833,7 @@ version 2005/12/01 or later.
             \int_compare:nNnTF \c@jCol = \l_@@_last_col_int
               { \@@_error:nn { in~last~col } \Ldots }
               { 
-                 \@@_instruction_of_type:nn { Ldots } 
+                 \@@_instruction_of_type:nnn \c_false_bool { Ldots } 
                    { #1 , down = #2 , up = #3 } 
               }  
           }
@@ -9815,7 +9852,7 @@ version 2005/12/01 or later.
             \int_compare:nNnTF \c@jCol = \l_@@_last_col_int
               { \@@_error:nn { in~last~col } \Cdots }
               { 
-                 \@@_instruction_of_type:nn { Cdots } 
+                 \@@_instruction_of_type:nnn \c_false_bool { Cdots } 
                    { #1 , down = #2 , up = #3 } 
               }  
           }
@@ -9834,7 +9871,7 @@ version 2005/12/01 or later.
             \int_compare:nNnTF \c@iRow = \l_@@_last_row_int
               { \@@_error:nn { in~last~row } \Vdots }
               { 
-                 \@@_instruction_of_type:nn { Vdots } 
+                 \@@_instruction_of_type:nnn \c_false_bool { Vdots } 
                    { #1 , down = #2 , up = #3 } 
               }  
           }
@@ -9843,6 +9880,7 @@ version 2005/12/01 or later.
       } 
 %    \end{macrocode}
 %
+%
 % \bigskip
 %    \begin{macrocode}
     \exp_args:NNV \NewDocumentCommand \@@_Ddots \l_@@_argspec_tl
@@ -9859,7 +9897,8 @@ version 2005/12/01 or later.
                 \l_@@_last_col_int { \@@_error:nn { in~last~col } \Ddots }  
               }
               {
-                \@@_instruction_of_type:nn { Ddots } 
+                \keys_set_known:nn { NiceMatrix / Ddots } { #1 } 
+                \@@_instruction_of_type:nnn \l_@@_draw_first_bool { Ddots } 
                   { #1 , down = #2 , up = #3 } 
               } 
        
@@ -9885,7 +9924,8 @@ version 2005/12/01 or later.
                 \l_@@_last_col_int { \@@_error:nn { in~last~col } \Iddots }  
               }
               {
-                \@@_instruction_of_type:nn { Iddots } 
+                \keys_set_known:nn { NiceMatrix / Ddots } { #1 } 
+                \@@_instruction_of_type:nnn \l_@@_draw_first_bool { Iddots } 
                   { #1 , down = #2 , up = #3 } 
               } 
        
@@ -9898,7 +9938,18 @@ version 2005/12/01 or later.
 % End of the |\AtBeginDocument|.
 %
 %
-%
+% \bigskip
+% Despite its name, the following set of keys will be used for |\Ddots| but also
+% for |\Iddots|.
+%    \begin{macrocode}
+\keys_define:nn { NiceMatrix / Ddots }
+  { 
+    draw-first .bool_set:N = \l_@@_draw_first_bool ,
+    draw-first .default:n = true ,
+    draw-first .value_forbidden:n = true
+  }
+%    \end{macrocode}
+% 
 % \bigskip
 % The command |\@@_Hspace:| will be linked to |\hspace| in |{NiceArray}|.
 %    \begin{macrocode}
@@ -9918,14 +9969,14 @@ version 2005/12/01 or later.
 \cs_new:Npn \@@_multicolumn:nnn #1 #2 #3
   { 
 %    \begin{macrocode}
-% We have to act in expandable way since it will begin by a |\multicolumn|.
+% We have to act in an expandable way since it will begin by a |\multicolumn|.
 %    \end{macrocode
     \exp_args:NNe 
       \@@_old_multicolumn 
       { #1 } 
 %    \end{macrocode}
-% We will have to replace |\tl_lower_case:n| in the future 
-% since |\tl_lower_case:n| seems to be deprecated.
+% We will have to replace |\tl_lower_case:n| in the future since it seems to be
+% deprecated.
 %    \begin{macrocode}
       { 
         \exp_args:Ne \str_case:nn { \tl_lower_case:n { #2 } }
@@ -9964,6 +10015,8 @@ version 2005/12/01 or later.
               }
           }
         \int_gadd:Nn \c@jCol { #1 - 1 }
+        \int_compare:nNnT \c@jCol > \g_@@_col_total_int
+          { \int_gset_eq:NN \g_@@_col_total_int \c@jCol } 
      }
   }
 %    \end{macrocode}
@@ -9979,8 +10032,12 @@ version 2005/12/01 or later.
 %    \begin{macrocode}
 \cs_new:Npn \@@_Hdotsfor:
   {
-    \multicolumn { 1 } { c } { }
-    \@@_Hdotsfor_i
+    \int_compare:nNnTF \c@jCol = 0
+      { \@@_error:n { Hdotsfor~in~col~0 } }
+      { 
+        \multicolumn { 1 } { c } { }
+        \@@_Hdotsfor_i
+      }
   }
 %    \end{macrocode}
 %
@@ -10010,7 +10067,7 @@ version 2005/12/01 or later.
                 #1 , #3 , 
                 down = \exp_not:n { #4 } , up = \exp_not:n { #5 }
               } 
-          }
+          } 
         \prg_replicate:nn { #2 - 1 } { & \multicolumn { 1 } { c } { } }
       } 
   }
@@ -10799,9 +10856,12 @@ version 2005/12/01 or later.
 \cs_new_protected:Npn \@@_vline_i:nn #1 #2
   {
 %    \end{macrocode}
-% |\l_tmpa_tl| is the number of row and |\l_tmpb_tl| the number of column.
+% |\l_tmpa_tl| is the number of row and |\l_tmpb_tl| the number of column. When
+% we have found a row corresponding to a rule to draw, we note its number in
+% |\l_tmpc_tl|. 
 %    \begin{macrocode}
     \tl_set:Nx \l_tmpb_tl { #1 }
+    \tl_clear_new:N \l_tmpc_tl
     \int_step_variable:nNn \c@iRow \l_tmpa_tl
       {
 %    \end{macrocode}
@@ -10818,8 +10878,34 @@ version 2005/12/01 or later.
            { \@@_test_if_vline_in_block:nnnn ##1 }
          \clist_if_empty:NF \l_@@_except_corners_clist
            \@@_test_in_corner_v:
-         \bool_if:NT \g_tmpa_bool
-           { \@@_vline_ii:nnnn { #1 } { #2 } \l_tmpa_tl \l_tmpa_tl }
+         \bool_if:NTF \g_tmpa_bool
+           { 
+             \tl_if_empty:NT \l_tmpc_tl
+%    \end{macrocode}
+% We keep in memory that we have a rule to draw.
+%    \begin{macrocode}
+               { \tl_set_eq:NN \l_tmpc_tl \l_tmpa_tl }
+           }
+           {
+             \tl_if_empty:NF \l_tmpc_tl
+               { 
+                 \@@_vline_ii:nnnn 
+                   { #1 } 
+                   { #2 } 
+                   \l_tmpc_tl 
+                   { \int_eval:n { \l_tmpa_tl - 1 } }
+                 \tl_clear:N \l_tmpc_tl
+               }
+           }
+      }
+    \tl_if_empty:NF \l_tmpc_tl
+      { 
+        \@@_vline_ii:nnnn 
+          { #1 } 
+          { #2 } 
+          \l_tmpc_tl 
+          { \int_use:N \c@iRow }
+        \tl_clear:N \l_tmpc_tl
       }
   }
 %    \end{macrocode}
@@ -10945,9 +11031,12 @@ version 2005/12/01 or later.
 \cs_new_protected:Npn \@@_hline_i:nn #1 #2
   {
 %    \end{macrocode}
-% |\l_tmpa_tl| is the number of row and |\l_tmpb_tl| the number of column.
+% |\l_tmpa_tl| is the number of row and |\l_tmpb_tl| the number of column. Whe,
+% we have found a column corresponding to a rule to draw, we note its numver in
+% |\l_tmpc_tl|. 
 %    \begin{macrocode}
     \tl_set:Nn \l_tmpa_tl { #1 }
+    \tl_clear_new:N \l_tmpc_tl
     \int_step_variable:nNn \c@jCol \l_tmpb_tl
       {
 %    \end{macrocode}
@@ -10963,8 +11052,34 @@ version 2005/12/01 or later.
          \seq_map_inline:Nn \g_@@_pos_of_xdots_seq
            { \@@_test_if_hline_in_block:nnnn ##1 }
          \clist_if_empty:NF \l_@@_except_corners_clist \@@_test_in_corner_h: 
-         \bool_if:NT \g_tmpa_bool
-           { \@@_hline_ii:nnnn { #1 } { #2 } \l_tmpb_tl \l_tmpb_tl }
+         \bool_if:NTF \g_tmpa_bool
+           { 
+             \tl_if_empty:NT \l_tmpc_tl
+%    \end{macrocode}
+% We keep in memory that we have a rule to draw.
+%    \begin{macrocode}
+               { \tl_set_eq:NN \l_tmpc_tl \l_tmpb_tl }
+           }
+           {
+             \tl_if_empty:NF \l_tmpc_tl
+               { 
+                 \@@_hline_ii:nnnn 
+                   { #1 } 
+                   { #2 } 
+                   \l_tmpc_tl 
+                   { \int_eval:n { \l_tmpb_tl - 1 } }
+                 \tl_clear:N \l_tmpc_tl
+               }
+           }
+      }
+    \tl_if_empty:NF \l_tmpc_tl
+      { 
+        \@@_hline_ii:nnnn 
+          { #1 } 
+          { #2 } 
+          \l_tmpc_tl 
+          { \int_use:N \c@jCol }
+        \tl_clear:N \l_tmpc_tl
       }
   }
 %    \end{macrocode}
@@ -11046,7 +11161,7 @@ version 2005/12/01 or later.
 % \bigskip
 %    \begin{macrocode}
 \cs_new_protected:Npn \@@_hline_i_complete:nn #1 #2
-  { \@@_hline_ii:nnnn #1 #2 1 { \int_use:N \c@jCol } }
+  { \@@_hline_ii:nnnn { #1 } { #2 } 1 { \int_use:N \c@jCol } }
 %    \end{macrocode}
 % 
 % \bigskip
@@ -11910,8 +12025,8 @@ version 2005/12/01 or later.
 %    \begin{macrocode}
 \cs_new_protected:Npn \@@_extract_coords_values: #1 - #2 \q_stop
   { 
-    \cs_set:Npn \@@_i: { #1 } 
-    \cs_set:Npn \@@_j: { #2 }
+    \cs_set_nopar:Npn \@@_i: { #1 } 
+    \cs_set_nopar:Npn \@@_j: { #2 }
   }
 %    \end{macrocode}
 %
@@ -11950,7 +12065,7 @@ version 2005/12/01 or later.
 % because it has an optional argument between |<| and |>| (for TeX instructions
 % put before the math mode of the label)
 %
-% It's mandatory to use a expandable command (probably because of the first
+% It's mandatory to use an expandable command (probably because of the first
 % optional argument?).
 %    \begin{macrocode}
 \NewExpandableDocumentCommand \@@_Block: { O { } m D < > { } m }
@@ -12026,6 +12141,13 @@ version 2005/12/01 or later.
     tikz .value_required:n = true ,
     color .tl_set:N = \l_@@_color_tl ,
     color .value_required:n = true ,
+    l .code:n = \tl_set:Nn \l_@@_pos_of_block_tl l ,
+    l .value_forbidden:n = true ,
+    r .code:n = \tl_set:Nn \l_@@_pos_of_block_tl r ,
+    r .value_forbidden:n = true ,
+    c .code:n = \tl_set:Nn \l_@@_pos_of_block_tl c ,
+    c .value_forbidden:n = true ,
+    unknown .code:n = \@@_error:n { Unknown~key~for~Block }
   }
 %    \end{macrocode}
 %
@@ -12062,15 +12184,15 @@ version 2005/12/01 or later.
 % 
 % \medskip
 %    \begin{macrocode}
-     \cs_set_protected:Npn \diagbox ##1 ##2
-       {
-         \tl_gput_right:Nx \g_@@_internal_code_after_tl    
-           { 
-             \@@_actually_diagbox:nnnnnn 
-               { #1 } { #2 } { #3 } { #4 } 
-               { \exp_not:n { ##1 } } { \exp_not:n { ##2 } }
-           }
-       }  
+    \cs_set_protected_nopar:Npn \diagbox ##1 ##2
+      {
+        \tl_gput_right:Nx \g_@@_internal_code_after_tl    
+          { 
+            \@@_actually_diagbox:nnnnnn 
+              { #1 } { #2 } { #3 } { #4 } 
+              { \exp_not:n { ##1 } } { \exp_not:n { ##2 } }
+          }
+      }  
 %    \end{macrocode}
 % 
 % \medskip
@@ -12176,8 +12298,11 @@ version 2005/12/01 or later.
               \cs_if_exist:cT
                 { pgf @ sh @ ns @ \@@_env: - ##1 - #2 }
                 {
-                  \pgfpointanchor { \@@_env: - ##1 - #2 } { west }
-                  \dim_set:Nn \l_tmpb_dim { \dim_min:nn \l_tmpb_dim \pgf@x } 
+                  \seq_if_in:NnF \g_@@_multicolumn_cells_seq { ##1 - #2 }
+                    {
+                      \pgfpointanchor { \@@_env: - ##1 - #2 } { west }
+                      \dim_set:Nn \l_tmpb_dim { \dim_min:nn \l_tmpb_dim \pgf@x }  
+                    }
                 }
             }
 %    \end{macrocode}
@@ -12196,8 +12321,11 @@ version 2005/12/01 or later.
               \cs_if_exist:cT
                 { pgf @ sh @ ns @ \@@_env: - ##1 - #4 }
                 {
-                  \pgfpointanchor { \@@_env: - ##1 - #4 } { east }
-                  \dim_set:Nn \l_tmpd_dim { \dim_max:nn \l_tmpd_dim \pgf@x }
+                  \seq_if_in:NnF \g_@@_multicolumn_cells_seq { ##1 - #2 }
+                    {
+                      \pgfpointanchor { \@@_env: - ##1 - #4 } { east }
+                      \dim_set:Nn \l_tmpd_dim { \dim_max:nn \l_tmpd_dim \pgf@x }
+                    }
                 }
             }
           \dim_compare:nNnT \l_tmpd_dim = { - \c_max_dim }
@@ -12224,7 +12352,8 @@ version 2005/12/01 or later.
           }
 %    \end{macrocode}
 % \medskip
-% Now, we will put the label of the block.
+% Now, we will put the label of the block beginning with the case of a |\Block|
+% of one row.
 %    \begin{macrocode}
         \int_compare:nNnTF { #1 } = { #3 }
           {
@@ -12248,24 +12377,65 @@ version 2005/12/01 or later.
 %    \end{macrocode}
 % We retrieve (in |\pgf@x|) the $x$-value of the center of the block.
 %    \begin{macrocode}
-            \@@_qpoint:n { #1 - #2 - block - short } 
+            \pgfpointanchor 
+              { \@@_env: - #1 - #2 - block - short } 
+              {
+                \str_case:Vn \l_@@_pos_of_block_tl
+                  {
+                    c { center } 
+                    l { west } 
+                    r { east } 
+                  }
+              } 
 %    \end{macrocode}
 % We put the label of the block which has been composed in |\l_@@_cell_box|.
 %    \begin{macrocode}
             \pgftransformshift { \pgfpoint \pgf@x \l_tmpa_dim }
-            \pgfnode { rectangle } { base } 
+            \pgfset { inner~sep = \c_zero_dim }
+            \pgfnode 
+              { rectangle } 
+              {
+                 \str_case:Vn \l_@@_pos_of_block_tl
+                  {
+                    c { base } 
+                    l { base~west } 
+                    r { base~east } 
+                  } 
+              } 
               { \box_use_drop:N \l_@@_cell_box } { } { }
           }
 %    \end{macrocode}
 %
 % \medskip
 % If the number of rows is different of $1$, we put the label of the block in
-% the center of the (short) node (the label of the block has been composed in
-% |\l_@@_cell_box|). 
+% using the short node (the label of the block has been composed in
+% |\l_@@_cell_box|).
 %    \begin{macrocode}
           { 
-            \pgftransformshift { \@@_qpoint:n { #1 - #2 - block - short } }
-            \pgfnode { rectangle } { center } 
+            \pgftransformshift
+              {
+                \pgfpointanchor 
+                  { \@@_env: - #1 - #2 - block - short } 
+                  {
+                     \str_case:Vn \l_@@_pos_of_block_tl
+                      {
+                        c { center } 
+                        l { west } 
+                        r { east } 
+                      }
+                  } 
+              }
+            \pgfset { inner~sep = \c_zero_dim }
+            \pgfnode 
+              { rectangle } 
+              {
+                 \str_case:Vn \l_@@_pos_of_block_tl
+                  {
+                    c { center } 
+                    l { west } 
+                    r { east } 
+                  }
+              } 
               { \box_use_drop:N \l_@@_cell_box } { } { }
           }   
         \endpgfpicture
@@ -12891,6 +13061,14 @@ version 2005/12/01 or later.
 %    \end{macrocode}
 %
 %    \begin{macrocode}
+\@@_msg_new:nn { Hdotsfor~in~col~0 }
+  {
+    You~can't~use~\token_to_str:N \Hdotsfor\ in~an~exterior~column~of~
+    the~array.~If~you~go~on,~the~corresponding~dotted~line~won't~be~drawn.
+  }
+%    \end{macrocode}
+% 
+%    \begin{macrocode}
 \@@_msg_new:nn { bad~corner }
   {
     #1~is~an~incorrect~specification~for~a~corner~(in~the~keys~
@@ -13009,7 +13187,19 @@ version 2005/12/01 or later.
   }
 %    \end{macrocode}
 %
-%
+%    \begin{macrocode}
+\@@_msg_new:nnn { Unknown~key~for~Block } 
+  {
+    The~key~'\l_keys_key_tl'~is~unknown~for~the~command~\token_to_str:N
+    \Block.\\ If~you~go~on,~it~will~be~ignored. \\
+    For~a~list~of~the~available~keys,~type~H~<return>.
+  }
+  {
+    The~available~options~are~(in~alphabetic~order):~c,~
+    color,~l,~and~r.
+  }
+%    \end{macrocode}
+% 
 %    \begin{macrocode}
 \@@_msg_new:nnn { Unknown~key~for~notes } 
   {
@@ -13265,6 +13455,15 @@ version 2005/12/01 or later.
 % \vspace{1cm}
 % \section{History}
 %
+% The successive versions of the file |nicematrix.sty| provided by TeXLive are available on the
+% \textsc{svn} server of TeXLive:
+%
+% {
+% \small
+% \url{https:www.tug.org/svn/texlive/trunk/Master/texmf-dist/tex/latex/nicematrix/nicematrix.sty}
+% }
+%
+% 
 % \subsection*{Changes between versions 1.0 and 1.1}
 % 
 % The dotted lines are no longer drawn with Tikz nodes but with Tikz circles
@@ -13615,7 +13814,16 @@ version 2005/12/01 or later.
 % The key |baseline| can take in as value of the form \textsl{line-i} to align
 % the |\hline| in the row \textsl{i}.
 %
-% The key |hvlines-except-corners| may take in as value a list of corner (eg: NW,SE).
+% The key |hvlines-except-corners| may take in as value a list of corners (eg: NW,SE).
+%
+% \subsection*{Changes between versions 5.2 and 5.3}
+%
+% Keys |c|, |r| and |l| for the command |\Block|.
+%
+% It's possible to use the key |draw-first| with |\Ddots| and |\Iddots| to
+% specify which dotted line will be drawn first (the other lines will be drawn
+% parallel to that one if parallelization is activated).
+%
 %
 % \PrintIndex
 %