nicematrix (6feb21)

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

1 files changed, 475 insertions, 81 deletions

diff --git a/Master/texmf-dist/tex/latex/nicematrix/nicematrix.sty b/Master/texmf-dist/tex/latex/nicematrix/nicematrix.sty
index 8e8cb2bc878..6a423f2b113 100644
--- a/Master/texmf-dist/tex/latex/nicematrix/nicematrix.sty
+++ b/Master/texmf-dist/tex/latex/nicematrix/nicematrix.sty
@@ -18,8 +18,8 @@
 %% and version 1.3 or later is part of all distributions of
 %% LaTeX version 2005/12/01 or later.
 %% 
-\def\myfileversion{5.9}
-\def\myfiledate{2021/01/08}
+\def\myfileversion{5.10}
+\def\myfiledate{2021/02/05}
 \RequirePackage{pgfcore}
 \usepgfmodule{shapes}
 \RequirePackage{l3keys2e}
@@ -30,7 +30,6 @@
   {Enhanced arrays with the help of PGF/TikZ}
 \RequirePackage { array }
 \RequirePackage { amsmath }
-\RequirePackage { xparse }
 \cs_new_protected:Npn \__nicematrix_error:n { \msg_error:nn { nicematrix } }
 \cs_new_protected:Npn \__nicematrix_error:nn { \msg_error:nnn { nicematrix } }
 \cs_new_protected:Npn \__nicematrix_error:nnn { \msg_error:nnnn { nicematrix } }
@@ -43,11 +42,15 @@
 \bool_new:N \c__nicematrix_in_preamble_bool
 \bool_set_true:N \c__nicematrix_in_preamble_bool
 \AtBeginDocument { \bool_set_false:N \c__nicematrix_in_preamble_bool }
+\bool_new:N \c__nicematrix_arydshln_loaded_bool
 \bool_new:N \c__nicematrix_booktabs_loaded_bool
 \bool_new:N \c__nicematrix_enumitem_loaded_bool
 \bool_new:N \c__nicematrix_tikz_loaded_bool
 \AtBeginDocument
   {
+    \@ifpackageloaded { arydshln }
+      { \bool_set_true:N \c__nicematrix_arydshln_loaded_bool }
+      { }
     \@ifpackageloaded { booktabs }
       { \bool_set_true:N \c__nicematrix_booktabs_loaded_bool }
       { }
@@ -72,6 +75,8 @@
 \@ifclassloaded { revtex4-2 }
   { \bool_set_true:N \c__nicematrix_revtex_bool }
   { }
+\cs_if_exist:NT \rvtx@ifformat@geq { \bool_set_true:N \c__nicematrix_revtex_bool }
+\cs_generate_variant:Nn \tl_if_single_token_p:n { V }
 \ProvideDocumentCommand \iddots { }
   {
     \mathinner
@@ -301,6 +306,7 @@
 \seq_new:N \g__nicematrix_pos_of_blocks_seq
 \seq_new:N \g__nicematrix_pos_of_xdots_seq
 \seq_new:N \g__nicematrix_pos_of_stroken_blocks_seq
+\seq_new:N \g__nicematrix_submatrix_names_seq
 \int_new:N \g__nicematrix_static_num_of_col_int
 \tl_new:N \l__nicematrix_fill_tl
 \tl_new:N \l__nicematrix_draw_tl
@@ -443,11 +449,11 @@
 \dim_new:N \l__nicematrix_cell_space_top_limit_dim
 \dim_new:N \l__nicematrix_cell_space_bottom_limit_dim
 \dim_new:N \l__nicematrix_inter_dots_dim
-\dim_set:Nn \l__nicematrix_inter_dots_dim { 0.45 em }
+\AtBeginDocument { \dim_set:Nn \l__nicematrix_inter_dots_dim { 0.45 em } }
 \dim_new:N \l__nicematrix_xdots_shorten_dim
-\dim_set:Nn \l__nicematrix_xdots_shorten_dim { 0.3 em }
+\AtBeginDocument { \dim_set:Nn \l__nicematrix_xdots_shorten_dim { 0.3 em } }
 \dim_new:N \l__nicematrix_radius_dim
-\dim_set:Nn \l__nicematrix_radius_dim { 0.53 pt }
+\AtBeginDocument { \dim_set:Nn \l__nicematrix_radius_dim { 0.53 pt } }
 \tl_new:N \l__nicematrix_xdots_line_style_tl
 \tl_const:Nn \c__nicematrix_standard_tl { standard }
 \tl_set_eq:NN \l__nicematrix_xdots_line_style_tl \c__nicematrix_standard_tl
@@ -461,7 +467,7 @@
 \bool_new:N \l__nicematrix_hlines_bool
 \clist_new:N \l__nicematrix_except_corners_clist
 \dim_new:N \l__nicematrix_notes_above_space_dim
-\dim_set:Nn \l__nicematrix_notes_above_space_dim { 1 mm }
+\AtBeginDocument { \dim_set:Nn \l__nicematrix_notes_above_space_dim { 1 mm } }
 \bool_new:N \l__nicematrix_nullify_dots_bool
 \bool_new:N \l__nicematrix_auto_columns_width_bool
 \str_new:N \l__nicematrix_name_str
@@ -511,10 +517,10 @@
     cell-space-top-limit .value_required:n = true ,
     cell-space-bottom-limit .dim_set:N = \l__nicematrix_cell_space_bottom_limit_dim ,
     cell-space-bottom-limit .value_required:n = true ,
-    cell-space-limits .code:n =
+    cell-space-limits .meta:n =
       {
-        \dim_set:Nn \l__nicematrix_cell_space_bottom_limit_dim { #1 }
-        \dim_set:Nn \l__nicematrix_cell_space_top_limit_dim { #1 }
+        cell-space-top-limit = #1 ,
+        cell-space-bottom-limit = #1 ,
       } ,
     cell-spaces-limits .value_required:n = true ,
     xdots .code:n = \keys_set:nn { NiceMatrix / xdots } { #1 } ,
@@ -667,6 +673,8 @@
     NiceMatrixOptions / xdots .inherit:n = NiceMatrix / xdots ,
     NiceMatrixOptions / rules .inherit:n = NiceMatrix / rules ,
     NiceMatrixOptions / notes .inherit:n = NiceMatrix / notes ,
+    NiceMatrixOptions / sub-matrix .inherit:n = NiceMatrix / sub-matrix ,
+    CodeAfter / xdots .inherit:n = NiceMatrix / xdots ,
     NiceMatrix .inherit:n =
       {
         NiceMatrix / Global ,
@@ -707,7 +715,12 @@
     small .value_forbidden:n = true ,
     renew-matrix .code:n = \__nicematrix_renew_matrix: ,
     renew-matrix .value_forbidden:n = true ,
-    transparent .meta:n = { renew-dots , renew-matrix } ,
+    transparent .code:n =
+      {
+        \__nicematrix_renew_matrix:
+        \bool_set_true:N \l__nicematrix_renew_dots_bool
+        \__nicematrix_error:n { Key~transparent }
+      } ,
     transparent .value_forbidden:n = true,
     exterior-arraycolsep .bool_set:N = \l__nicematrix_exterior_arraycolsep_bool ,
     columns-width .code:n =
@@ -726,6 +739,9 @@
     letter-for-dotted-lines .value_required:n = true ,
     notes .code:n = \keys_set:nn { NiceMatrix / notes } { #1 } ,
     notes .value_required:n = true ,
+    sub-matrix .code:n =
+     \keys_set:nn { NiceMatrix / sub-matrix } { #1 } ,
+    sub-matrix .value_required:n = true ,
     unknown .code:n  = \__nicematrix_error:n { Unknown~key~for~NiceMatrixOptions }
   }
 \str_new:N \l__nicematrix_letter_for_dotted_lines_str
@@ -1134,6 +1150,7 @@
     \bgroup
     \tl_set:Nn \l__nicematrix_left_delim_tl { #1 }
     \tl_set:Nn \l__nicematrix_right_delim_tl { #2 }
+    \tl_gset:Nn \g__nicematrix_preamble_tl { #4 }
     \int_gzero:N \g__nicematrix_block_box_int
     \dim_zero:N \g__nicematrix_width_last_col_dim
     \dim_zero:N \g__nicematrix_width_first_col_dim
@@ -1285,14 +1302,14 @@
         \dim_gset:Nn \l__nicematrix_right_delim_dim { 2 \arraycolsep }
       }
       {
-        \hbox_set:Nn \l_tmpa_box { $ \bBigg@ 5 #1 $ }
+        \hbox_set:Nn \l_tmpa_box { $ \bBigg@ 5 \l__nicematrix_left_delim_tl $ }
         \dim_set:Nn \l__nicematrix_left_delim_dim { \box_wd:N \l_tmpa_box }
-        \hbox_set:Nn \l_tmpa_box { $ \bBigg@ 5 #2 $ }
+        \hbox_set:Nn \l_tmpa_box { $ \bBigg@ 5 \l__nicematrix_right_delim_tl $ }
         \dim_set:Nn \l__nicematrix_right_delim_dim { \box_wd:N \l_tmpa_box }
       }
     \box_clear_new:N \l__nicematrix_the_array_box
     \bool_if:NT \c__nicematrix_define_L_C_R_bool \__nicematrix_define_L_C_R:
-    \__nicematrix_construct_preamble:n { #4 }
+    \__nicematrix_construct_preamble:
     \hbox_set:Nw \l__nicematrix_the_array_box
     \skip_horizontal:N \l__nicematrix_left_margin_dim
     \skip_horizontal:N \l__nicematrix_extra_left_margin_dim
@@ -1361,11 +1378,10 @@
             \c_math_toggle_token
             \tl_if_empty:NF \l__nicematrix_delimiters_color_tl
               { \color { \l__nicematrix_delimiters_color_tl } }
-            \left #1
+            \exp_after:wN \left \l__nicematrix_left_delim_tl
             \vcenter
               {
                 \skip_vertical:N -\l_tmpa_dim
-                \skip_vertical:N -\arrayrulewidth
                 \hbox
                   {
                     \bool_if:NTF \l__nicematrix_NiceTabular_bool
@@ -1377,9 +1393,8 @@
                       { \skip_horizontal:N -\arraycolsep }
                   }
                 \skip_vertical:N -\l_tmpb_dim
-                \skip_vertical:N \arrayrulewidth
               }
-            \right #2
+            \exp_after:wN \right \l__nicematrix_right_delim_tl
             \c_math_toggle_token
           }
         \bool_if:NTF \l__nicematrix_max_delimiter_width_bool
@@ -1404,15 +1419,14 @@
     \egroup
     \bool_if:NT \c__nicematrix_footnote_bool \endsavenotes
   }
-\cs_new_protected:Npn \__nicematrix_construct_preamble:n #1
+\cs_new_protected:Npn \__nicematrix_construct_preamble:
   {
     \group_begin:
-    \bool_if:NTF \l__nicematrix_Matrix_bool
-      { \tl_gset:Nn \g__nicematrix_preamble_tl { #1 } }
+    \bool_if:NF \l__nicematrix_Matrix_bool
       {
         \__nicematrix_newcolumntype w [ 2 ] { \__nicematrix_w: { ##1 } { ##2 } }
         \__nicematrix_newcolumntype W [ 2 ] { \__nicematrix_W: { ##1 } { ##2 } }
-        \@temptokena { #1 }
+        \exp_args:NV \@temptokena \g__nicematrix_preamble_tl
         \@tempswatrue
         \@whilesw \if@tempswa \fi { \@tempswafalse \the \NC@list }
         \int_gzero_new:N \c@jCol
@@ -1482,15 +1496,30 @@
         \__nicematrix_w: { \__nicematrix_patch_preamble_v:nnnn { }                          #1 }
         \__nicematrix_W: { \__nicematrix_patch_preamble_v:nnnn { \cs_set_eq:NN \hss \hfil } #1 }
         \__nicematrix_true_c: { \__nicematrix_patch_preamble_vi:n #1 }
-        C { \__nicematrix_error:nn { old~column~type } C }
-        L { \__nicematrix_error:nn { old~column~type } L }
-        R { \__nicematrix_error:nn { old~column~type } R }
+        (  { \__nicematrix_patch_preamble_vii:n #1 }
+        [  { \__nicematrix_patch_preamble_vii:n #1 }
+        \{ { \__nicematrix_patch_preamble_vii:n #1 }
+        )  { \__nicematrix_patch_preamble_viii:n #1 }
+        ]  { \__nicematrix_patch_preamble_viii:n #1 }
+        \} { \__nicematrix_patch_preamble_viii:n #1 }
+        C { \__nicematrix_error:nn { old~column~type } #1 }
+        L { \__nicematrix_error:nn { old~column~type } #1 }
+        R { \__nicematrix_error:nn { old~column~type } #1 }
         \q_stop { }
       }
       {
         \str_if_eq:VnTF \l__nicematrix_letter_for_dotted_lines_str { #1 }
-          { \__nicematrix_patch_preamble_vii:n #1 }
-          { \__nicematrix_fatal:nn { unknown~column~type } { #1 } }
+          { \__nicematrix_patch_preamble_xi:n #1 }
+          {
+            \bool_lazy_and:nnTF
+              { \str_if_eq_p:nn { : } { #1 } }
+              \c__nicematrix_arydshln_loaded_bool
+              {
+                \tl_gput_right:Nn \g__nicematrix_preamble_tl { : }
+                \__nicematrix_patch_preamble:n
+              }
+              { \__nicematrix_fatal:nn { unknown~column~type } { #1 } }
+          }
       }
   }
 \cs_new_protected:Npn \__nicematrix_patch_preamble_i:n #1
@@ -1502,7 +1531,7 @@
         < \__nicematrix_end_Cell:
       }
     \int_gincr:N \c@jCol
-    \__nicematrix_patch_preamble_viii:n
+    \__nicematrix_patch_preamble_x:n
   }
 \cs_new_protected:Npn \__nicematrix_patch_preamble_ii:nn #1 #2
   {
@@ -1554,7 +1583,7 @@
         < { \box_use:N \@arstrutbox \end { minipage } \__nicematrix_end_Cell: }
       }
     \int_gincr:N \c@jCol
-    \__nicematrix_patch_preamble_viii:n
+    \__nicematrix_patch_preamble_x:n
   }
 \cs_new_protected:Npn \__nicematrix_patch_preamble_v:nnnn #1 #2 #3 #4
   {
@@ -1576,23 +1605,53 @@
           }
       }
     \int_gincr:N \c@jCol
-    \__nicematrix_patch_preamble_viii:n
+    \__nicematrix_patch_preamble_x:n
   }
 \cs_new_protected:Npn \__nicematrix_patch_preamble_vi:n #1
   {
     \tl_gput_right:Nn \g__nicematrix_preamble_tl { c }
     \int_gincr:N \c@jCol
-    \__nicematrix_patch_preamble_viii:n
+    \__nicematrix_patch_preamble_x:n
   }
 \cs_new_protected:Npn \__nicematrix_patch_preamble_vii:n #1
   {
+     \bool_if:NT \l__nicematrix_small_bool
+       { \__nicematrix_fatal:n { Delimiter~with~small } }
+    \int_compare:nNnT \c@jCol = \c_zero_int
+      { \tl_gput_right:Nx \g__nicematrix_preamble_tl { ! { \enskip } } }
+    \tl_gput_right:Nx \g__nicematrix_internal_code_after_tl
+      { \__nicematrix_delimiter:nnn #1 { \__nicematrix_succ:n \c@jCol } \c_true_bool }
+    \__nicematrix_patch_preamble:n
+  }
+\cs_new_protected:Npn \__nicematrix_patch_preamble_viii:n #1
+  {
+     \bool_if:NT \l__nicematrix_small_bool
+       { \__nicematrix_fatal:n { Delimiter~with~small } }
+    \tl_gput_right:Nx \g__nicematrix_internal_code_after_tl
+      { \__nicematrix_delimiter:nnn #1 { \int_use:N \c@jCol } \c_false_bool }
+    \__nicematrix_patch_preamble_viii_i:n
+  }
+\cs_new_protected:Npn \__nicematrix_patch_preamble_viii_i:n #1
+  {
+    \bool_lazy_any:nT
+      {
+          { \str_if_eq_p:nn { #1 } ( }
+          { \str_if_eq_p:nn { #1 } [ }
+          { \str_if_eq_p:nn { #1 } \{ }
+          { \str_if_eq_p:nn { #1 } \q_stop }
+      }
+    { \tl_gput_right:Nn \g__nicematrix_preamble_tl { ! { \enskip } } }
+    \__nicematrix_patch_preamble:n #1
+  }
+\cs_new_protected:Npn \__nicematrix_patch_preamble_xi:n #1
+  {
     \tl_gput_right:Nn \g__nicematrix_preamble_tl
       { ! { \skip_horizontal:N 2\l__nicematrix_radius_dim } }
     \tl_gput_right:Nx \g__nicematrix_internal_code_after_tl
       { \__nicematrix_vdottedline:n { \int_use:N \c@jCol } }
     \__nicematrix_patch_preamble:n
   }
-\cs_new_protected:Npn \__nicematrix_patch_preamble_viii:n #1
+\cs_new_protected:Npn \__nicematrix_patch_preamble_x:n #1
   {
     \str_if_eq:nnTF { #1 } { < }
       \__nicematrix_patch_preamble_ix:n
@@ -1608,7 +1667,7 @@
 \cs_new_protected:Npn \__nicematrix_patch_preamble_ix:n #1
   {
     \tl_gput_right:Nn \g__nicematrix_preamble_tl { < { #1 } }
-    \__nicematrix_patch_preamble_viii:n
+    \__nicematrix_patch_preamble_x:n
   }
 \cs_new_protected:Npn \__nicematrix_put_box_in_flow:
   {
@@ -1701,7 +1760,7 @@
             \skip_vertical:N \aboverulesep
             { \CT@arc@ \hrule height \heavyrulewidth }
           }
-          { \__nicematrix_error:n { bottomule~without~booktabs } }
+          { \__nicematrix_error:n { bottomrule~without~booktabs } }
       }
     \l__nicematrix_notes_code_after_tl
     \seq_gclear:N \g__nicematrix_tabularnotes_seq
@@ -2278,8 +2337,11 @@
           }
       }
     \cs_set_eq:NN \line \__nicematrix_line
+    \cs_set_eq:NN \SubMatrix \__nicematrix_SubMatrix
     \cs_set_eq:NN \CodeAfter \prg_do_nothing:
-    \g_nicematrix_code_after_tl
+    \seq_gclear:N \g__nicematrix_submatrix_names_seq
+    \exp_last_unbraced:NV \__nicematrix_CodeAfter_keys: \g_nicematrix_code_after_tl
+    \scan_stop:
     \tl_gclear:N \g_nicematrix_code_after_tl
     \group_end:
     \tl_if_empty:NF \g_nicematrix_code_before_tl
@@ -2300,6 +2362,8 @@
     \__nicematrix_restore_iRow_jCol:
     \cs_gset_eq:NN \CT@arc@ \__nicematrix_old_CT@arc@
   }
+\NewDocumentCommand \__nicematrix_CodeAfter_keys: { O { } }
+  { \keys_set:nn { NiceMatrix / CodeAfter } { #1 } }
 \cs_new_protected:Npn \__nicematrix_adjust_pos_of_blocks_seq:
   {
     \seq_gset_map_x:NNn \g__nicematrix_pos_of_blocks_seq \g__nicematrix_pos_of_blocks_seq
@@ -2806,6 +2870,42 @@
   }
 \cs_new_protected:Npn \__nicematrix_draw_line:
   {
+    \pgfrememberpicturepositiononpagetrue
+    \pgf@relevantforpicturesizefalse
+    \tl_if_eq:NNTF \l__nicematrix_xdots_line_style_tl \c__nicematrix_standard_tl
+      \__nicematrix_draw_standard_dotted_line:
+      \__nicematrix_draw_non_standard_dotted_line:
+  }
+\cs_new_protected:Npn \__nicematrix_draw_non_standard_dotted_line:
+  {
+    \begin { scope }
+    \exp_args:No \__nicematrix_draw_non_standard_dotted_line:n
+      { \l__nicematrix_xdots_line_style_tl , \l__nicematrix_xdots_color_tl }
+  }
+\cs_new_protected:Npn \__nicematrix_draw_non_standard_dotted_line:n #1
+  {
+    \__nicematrix_draw_non_standard_dotted_line:nVV
+      { #1 }
+      \l__nicematrix_xdots_up_tl
+      \l__nicematrix_xdots_down_tl
+  }
+\cs_new_protected:Npn \__nicematrix_draw_non_standard_dotted_line:nnn #1 #2 #3
+  {
+    \draw
+      [
+        #1 ,
+        shorten~> = \l__nicematrix_xdots_shorten_dim ,
+        shorten~< = \l__nicematrix_xdots_shorten_dim ,
+      ]
+          ( \l__nicematrix_x_initial_dim , \l__nicematrix_y_initial_dim )
+       -- node [ sloped , above ] { $ \scriptstyle #2 $ }
+          node [ sloped , below ] { $ \scriptstyle #3 $ }
+          ( \l__nicematrix_x_final_dim , \l__nicematrix_y_final_dim ) ;
+    \end { scope }
+  }
+\cs_generate_variant:Nn \__nicematrix_draw_non_standard_dotted_line:nnn { n V V }
+\cs_new_protected:Npn \__nicematrix_draw_standard_dotted_line:
+  {
     \bool_lazy_and:nnF
       { \tl_if_empty_p:N \l__nicematrix_xdots_up_tl }
       { \tl_if_empty_p:N \l__nicematrix_xdots_down_tl }
@@ -2850,33 +2950,6 @@
           { \pgfusepath { } }
         \endpgfscope
       }
-    \pgfrememberpicturepositiononpagetrue
-    \pgf@relevantforpicturesizefalse
-    \tl_if_eq:NNTF \l__nicematrix_xdots_line_style_tl \c__nicematrix_standard_tl
-      \__nicematrix_draw_standard_dotted_line:
-      \__nicematrix_draw_non_standard_dotted_line:
-  }
-\cs_new_protected:Npn \__nicematrix_draw_non_standard_dotted_line:
-  {
-    \begin { scope }
-    \exp_args:No \__nicematrix_draw_non_standard_dotted_line:n
-      { \l__nicematrix_xdots_line_style_tl , \l__nicematrix_xdots_color_tl }
-  }
-\cs_new_protected:Npn \__nicematrix_draw_non_standard_dotted_line:n #1
-  {
-    \draw
-      [
-        #1 ,
-        shorten~> = \l__nicematrix_xdots_shorten_dim ,
-        shorten~< = \l__nicematrix_xdots_shorten_dim ,
-      ]
-          ( \l__nicematrix_x_initial_dim , \l__nicematrix_y_initial_dim )
-       --
-          ( \l__nicematrix_x_final_dim , \l__nicematrix_y_final_dim ) ;
-    \end { scope }
-  }
-\cs_new_protected:Npn \__nicematrix_draw_standard_dotted_line:
-  {
     \group_begin:
       \dim_zero_new:N \l__nicematrix_l_dim
       \dim_set:Nn \l__nicematrix_l_dim
@@ -2994,7 +3067,8 @@
                    { #1 , down = #2 , up = #3 }
               }
           }
-        \bool_if:NF \l__nicematrix_nullify_dots_bool { \phantom \__nicematrix_old_ldots }
+        \bool_if:NF \l__nicematrix_nullify_dots_bool
+          { \phantom { \ensuremath { \__nicematrix_old_ldots } } }
         \bool_gset_true:N \g__nicematrix_empty_cell_bool
       }
     \exp_args:NNV \NewDocumentCommand \__nicematrix_Cdots \l__nicematrix_argspec_tl
@@ -3009,7 +3083,8 @@
                    { #1 , down = #2 , up = #3 }
               }
           }
-        \bool_if:NF \l__nicematrix_nullify_dots_bool { \phantom \__nicematrix_old_cdots }
+        \bool_if:NF \l__nicematrix_nullify_dots_bool
+          { \phantom { \ensuremath { \__nicematrix_old_cdots } } }
         \bool_gset_true:N \g__nicematrix_empty_cell_bool
       }
     \exp_args:NNV \NewDocumentCommand \__nicematrix_Vdots \l__nicematrix_argspec_tl
@@ -3024,7 +3099,8 @@
                    { #1 , down = #2 , up = #3 }
               }
           }
-        \bool_if:NF \l__nicematrix_nullify_dots_bool { \phantom \__nicematrix_old_vdots }
+        \bool_if:NF \l__nicematrix_nullify_dots_bool
+          { \phantom { \ensuremath { \__nicematrix_old_vdots } } }
         \bool_gset_true:N \g__nicematrix_empty_cell_bool
       }
     \exp_args:NNV \NewDocumentCommand \__nicematrix_Ddots \l__nicematrix_argspec_tl
@@ -3047,7 +3123,8 @@
               }
 
           }
-        \bool_if:NF \l__nicematrix_nullify_dots_bool { \phantom \__nicematrix_old_ddots }
+        \bool_if:NF \l__nicematrix_nullify_dots_bool
+          { \phantom { \ensuremath { \__nicematrix_old_ddots } } }
         \bool_gset_true:N \g__nicematrix_empty_cell_bool
       }
     \exp_args:NNV \NewDocumentCommand \__nicematrix_Iddots \l__nicematrix_argspec_tl
@@ -3068,9 +3145,9 @@
                 \__nicematrix_instruction_of_type:nnn \l__nicematrix_draw_first_bool { Iddots }
                   { #1 , down = #2 , up = #3 }
               }
-
           }
-        \bool_if:NF \l__nicematrix_nullify_dots_bool { \phantom \__nicematrix_old_iddots }
+        \bool_if:NF \l__nicematrix_nullify_dots_bool
+          { \phantom { \ensuremath { \__nicematrix_old_iddots } } }
         \bool_gset_true:N \g__nicematrix_empty_cell_bool
       }
   }
@@ -4975,6 +5052,15 @@
       { \__nicematrix_math_toggle_token: #6 \__nicematrix_math_toggle_token: } { } { }
     \endpgfpicture
   }
+\keys_define:nn { NiceMatrix / CodeAfter }
+  {
+    sub-matrix .code:n =
+     \keys_set:nn { NiceMatrix / sub-matrix } { #1 } ,
+    sub-matrix .value_required:n = true ,
+    delimiters-color .tl_set:N = \l__nicematrix_delimiters_color_tl ,
+    delimiters-color .value_required:n = true ,
+    unknown .code:n = \__nicematrix_error:n { Unknown~key~for~CodeAfter }
+  }
 \cs_new:Npn \__nicematrix_CodeAfter: { \omit \__nicematrix_CodeAfter_i:n }
 \cs_new_protected:Npn \__nicematrix_CodeAfter_i:n #1 \end
   {
@@ -4990,6 +5076,255 @@
         \__nicematrix_CodeAfter_i:n
       }
   }
+\cs_new_protected:Npn \__nicematrix_delimiter:nnn #1 #2 #3
+  {
+    \pgfpicture
+    \pgfrememberpicturepositiononpagetrue
+    \pgf@relevantforpicturesizefalse
+    \__nicematrix_qpoint:n { row - 1 }
+    \dim_set_eq:NN \l__nicematrix_y_initial_dim \pgf@y
+    \__nicematrix_qpoint:n { row - \__nicematrix_succ:n \c@iRow }
+    \dim_set_eq:NN \l__nicematrix_y_final_dim \pgf@y
+    \bool_if:nTF { #3 }
+      { \dim_set_eq:NN \l_tmpa_dim \c_max_dim }
+      { \dim_set:Nn \l_tmpa_dim { - \c_max_dim } }
+    \int_step_inline:nnn \l__nicematrix_first_row_int \g__nicematrix_row_total_int
+      {
+        \cs_if_exist:cT
+          { pgf @ sh @ ns @ \__nicematrix_env: - ##1 - #2 }
+          {
+            \pgfpointanchor
+              { \__nicematrix_env: - ##1 - #2 }
+              { \bool_if:nTF { #3 } { west } { east } }
+            \dim_set:Nn \l_tmpa_dim
+              { \bool_if:nTF { #3 } \dim_min:nn \dim_max:nn \l_tmpa_dim \pgf@x }
+          }
+      }
+    \pgfset { inner~sep = \c_zero_dim }
+    \dim_zero:N \nulldelimiterspace
+    \pgftransformshift
+      {
+        \pgfpoint
+          { \l_tmpa_dim }
+          { ( \l__nicematrix_y_initial_dim + \l__nicematrix_y_final_dim + \arrayrulewidth ) / 2 }
+      }
+    \pgfnode
+      { rectangle }
+      { \bool_if:nTF { #3 } { east } { west } }
+      {
+        \nullfont
+        \c_math_toggle_token
+        \tl_if_empty:NF \l__nicematrix_delimiters_color_tl
+          { \color { \l__nicematrix_delimiters_color_tl } }
+        \bool_if:nTF { #3 } { \left #1 } { \left . }
+        \vcenter
+          {
+            \nullfont
+            \hrule \@height
+                   \dim_eval:n { \l__nicematrix_y_initial_dim - \l__nicematrix_y_final_dim }
+                   \@depth \c_zero_dim
+                   \@width \c_zero_dim
+          }
+        \bool_if:nTF { #3 } { \right . } { \right #1 }
+        \c_math_toggle_token
+      }
+      { }
+      { }
+    \endpgfpicture
+  }
+\keys_define:nn { NiceMatrix / sub-matrix }
+  {
+    extra-height .dim_set:N = \l__nicematrix_submatrix_extra_height_dim ,
+    extra-height .value_required:n = true ,
+    left-xshift .dim_set:N = \l__nicematrix_submatrix_left_xshift_dim ,
+    left-xshift .value_required:n = true ,
+    right-xshift .dim_set:N = \l__nicematrix_submatrix_right_xshift_dim ,
+    right-xshift .value_required:n = true ,
+    xshift .meta:n = { left-xshift = #1, right-xshift = #1 } ,
+    xshift .value_required:n = true ,
+    delimiters-color .tl_set:N = \l__nicematrix_delimiters_color_tl ,
+    delimiters-color .value_required:n = true ,
+    slim .bool_set:N = \l__nicematrix_submatrix_slim_bool ,
+    slim .default:n = true ,
+  }
+\keys_define:nn { NiceMatrix }
+  {
+    SubMatrix .inherit:n = NiceMatrix /sub-matrix ,
+    CodeAfter / sub-matrix .inherit:n = NiceMatrix / sub-matrix
+  }
+\keys_define:nn { NiceMatrix / SubMatrix }
+  {
+    name .code:n =
+      \tl_if_empty:nTF { #1 }
+        { \__nicematrix_error:n { Invalid~name~format } }
+        {
+          \regex_match:nnTF { \A[A-Za-z][A-Za-z0-9]*\Z } { #1 }
+            {
+              \seq_if_in:NnTF \g__nicematrix_submatrix_names_seq { #1 }
+                { \__nicematrix_error:nn { Duplicate~name~for~SubMatrix } { #1 } }
+                {
+                  \str_set:Nn \l__nicematrix_submatrix_name_str { #1 }
+                  \seq_gput_right:Nn \g__nicematrix_submatrix_names_seq { #1 }
+                }
+            }
+            { \__nicematrix_error:n { Invalid~name~format } }
+        } ,
+    name .value_required:n = true ,
+    unknown .code:n = \__nicematrix_error:n { Unknown~key~for~SubMatrix }
+  }
+\NewDocumentCommand \__nicematrix_SubMatrix { m m m m ! O { } }
+  {
+    \group_begin:
+    \__nicematrix_cut_on_hyphen:w #3 \q_stop
+    \tl_clear_new:N \l_tmpc_tl
+    \tl_clear_new:N \l_tmpd_tl
+    \tl_set_eq:NN \l_tmpc_tl \l_tmpa_tl
+    \tl_set_eq:NN \l_tmpd_tl \l_tmpb_tl
+    \__nicematrix_cut_on_hyphen:w #2 \q_stop
+    \bool_lazy_or:nnTF
+      { \int_compare_p:nNn \l_tmpc_tl > \g__nicematrix_row_total_int }
+      { \int_compare_p:nNn \l_tmpd_tl > \g__nicematrix_col_total_int }
+      { \__nicematrix_error:n { SubMatrix~too~large } }
+      {
+        \dim_zero_new:N \l__nicematrix_submatrix_extra_height_dim
+        \dim_zero_new:N \l__nicematrix_submatrix_left_xshift_dim
+        \dim_zero_new:N \l__nicematrix_submatrix_right_xshift_dim
+        \str_clear_new:N \l__nicematrix_submatrix_name_str
+        \keys_set:nn { NiceMatrix / SubMatrix } { #5 }
+        \pgfpicture
+        \pgfrememberpicturepositiononpagetrue
+        \pgf@relevantforpicturesizefalse
+        \pgfset { inner~sep = \c_zero_dim }
+        \dim_set_eq:NN \l__nicematrix_x_initial_dim \c_max_dim
+        \dim_set:Nn \l__nicematrix_x_final_dim { - \c_max_dim }
+        \bool_if:NTF \l__nicematrix_submatrix_slim_bool
+          { \int_step_inline:nnn \l_tmpa_tl  \l_tmpc_tl }
+          { \int_step_inline:nnn \l__nicematrix_first_row_int \g__nicematrix_row_total_int }
+          {
+            \cs_if_exist:cT
+              { pgf @ sh @ ns @ \__nicematrix_env: - ##1 - \l_tmpb_tl }
+              {
+                \pgfpointanchor { \__nicematrix_env: - ##1 - \l_tmpb_tl } { west }
+                \dim_set:Nn \l__nicematrix_x_initial_dim
+                  { \dim_min:nn \l__nicematrix_x_initial_dim \pgf@x }
+              }
+            \cs_if_exist:cT
+              { pgf @ sh @ ns @ \__nicematrix_env: - ##1 - \l_tmpd_tl }
+              {
+                \pgfpointanchor { \__nicematrix_env: - ##1 - \l_tmpd_tl } { east }
+                \dim_set:Nn \l__nicematrix_x_final_dim
+                  { \dim_max:nn \l__nicematrix_x_final_dim \pgf@x }
+              }
+          }
+        \__nicematrix_qpoint:n { row - \l_tmpa_tl - base }
+        \dim_set:Nn \l__nicematrix_y_initial_dim
+          { \pgf@y + ( \box_ht:N \strutbox + \extrarowheight ) * \arraystretch }
+        \__nicematrix_qpoint:n { row - \l_tmpc_tl - base }
+        \dim_set:Nn \l__nicematrix_y_final_dim
+          { \pgf@y - ( \box_dp:N \strutbox ) * \arraystretch }
+        \int_step_inline:nnn \l__nicematrix_first_col_int \g__nicematrix_col_total_int
+          {
+            \cs_if_exist:cT
+              { pgf @ sh @ ns @ \__nicematrix_env: - \l_tmpa_tl - ##1 }
+              {
+                \pgfpointanchor { \__nicematrix_env: - \l_tmpa_tl - ##1 } { north }
+                \dim_set:Nn \l__nicematrix_y_initial_dim
+                  { \dim_max:nn \l__nicematrix_y_initial_dim \pgf@y }
+              }
+            \cs_if_exist:cT
+              { pgf @ sh @ ns @ \__nicematrix_env: - \l_tmpc_tl - ##1 }
+              {
+                \pgfpointanchor { \__nicematrix_env: - \l_tmpc_tl - ##1 } { south }
+                \dim_set:Nn \l__nicematrix_y_final_dim
+                  { \dim_min:nn \l__nicematrix_y_final_dim \pgf@y }
+              }
+          }
+        \dim_set:Nn \l_tmpa_dim
+          {
+            \l__nicematrix_y_initial_dim - \l__nicematrix_y_final_dim +
+            \l__nicematrix_submatrix_extra_height_dim - \arrayrulewidth
+          }
+        \dim_set_eq:NN \nulldelimiterspace \c_zero_dim
+        \str_if_empty:NF \l__nicematrix_submatrix_name_str
+          {
+            \__nicematrix_pgf_rect_node:nnnnn \l__nicematrix_submatrix_name_str
+              \l__nicematrix_x_initial_dim \l__nicematrix_y_initial_dim
+              \l__nicematrix_x_final_dim \l__nicematrix_y_final_dim
+          }
+        \begin { pgfscope }
+        \pgftransformshift
+          {
+            \pgfpoint
+              { \l__nicematrix_x_initial_dim - \l__nicematrix_submatrix_left_xshift_dim }
+              { ( \l__nicematrix_y_initial_dim + \l__nicematrix_y_final_dim ) / 2 }
+          }
+        \str_if_empty:NTF \l__nicematrix_submatrix_name_str
+          { \__nicematrix_node_left:nn #1 { } }
+          { \__nicematrix_node_left:nn #1 { \__nicematrix_env: - \l__nicematrix_submatrix_name_str - left } }
+        \end { pgfscope }
+        \pgftransformshift
+          {
+            \pgfpoint
+              { \l__nicematrix_x_final_dim + \l__nicematrix_submatrix_right_xshift_dim }
+              { ( \l__nicematrix_y_initial_dim + \l__nicematrix_y_final_dim ) / 2 }
+          }
+        \str_if_empty:NTF \l__nicematrix_submatrix_name_str
+          { \__nicematrix_node_right:nn #4 { } }
+          {
+            \__nicematrix_node_right:nn #4 { \__nicematrix_env: - \l__nicematrix_submatrix_name_str - right }
+          }
+        \endpgfpicture
+      }
+    \group_end:
+  }
+\cs_new_protected:Npn \__nicematrix_node_left:nn #1 #2
+  {
+    \pgfnode
+      { rectangle }
+      { east }
+      {
+        \nullfont
+        \c_math_toggle_token
+        \tl_if_empty:NF \l__nicematrix_delimiters_color_tl
+          { \color { \l__nicematrix_delimiters_color_tl } }
+        \left #1
+        \vcenter
+          {
+            \nullfont
+            \hrule \@height \l_tmpa_dim
+                   \@depth \c_zero_dim
+                   \@width \c_zero_dim
+          }
+        \right .
+        \c_math_toggle_token
+      }
+      { #2 }
+      { }
+  }
+\cs_new_protected:Npn \__nicematrix_node_right:nn #1 #2
+  {
+    \pgfnode
+      { rectangle }
+      { west }
+      {
+        \nullfont
+        \c_math_toggle_token
+        \tl_if_empty:NF \l__nicematrix_delimiters_color_tl
+          { \color { \l__nicematrix_delimiters_color_tl } }
+        \left .
+        \vcenter
+          {
+            \nullfont
+            \hrule \@height \l_tmpa_dim
+                   \@depth \c_zero_dim
+                   \@width \c_zero_dim
+          }
+        \right #1
+        \c_math_toggle_token
+      }
+      { #2 }
+      { }
+  }
 %% \medskip
 \bool_new:N \c__nicematrix_footnotehyper_bool
 \bool_new:N \c__nicematrix_footnote_bool
@@ -5004,9 +5339,14 @@
     define-L-C-R,~
     footnote,~
     footnotehyper,~
-    renew-dots,~
-    renew-matrix~and~
-    transparent.
+    renew-dots,~and
+    renew-matrix.
+  }
+\__nicematrix_msg_new:nn { Key~transparent }
+  {
+    The~key~'transparent'~is~now~obsolete~(because~it's~name~
+    is~not~clear).~You~should~use~the~conjonction~of~'renew-dots'~
+    and~'renew-matrix'.~However,~you~can~go~on.
   }
 \keys_define:nn { NiceMatrix / Package }
   {
@@ -5016,7 +5356,12 @@
     renew-dots .value_forbidden:n = true ,
     renew-matrix .code:n = \__nicematrix_renew_matrix: ,
     renew-matrix .value_forbidden:n = true ,
-    transparent .meta:n = { renew-dots , renew-matrix } ,
+    transparent .code:n =
+      {
+        \__nicematrix_renew_matrix:
+        \bool_set_true:N \l__nicematrix_renew_dots_bool
+        \__nicematrix_error:n { Key~transparent }
+      } ,
     transparent .value_forbidden:n = true,
     footnote .bool_set:N = \c__nicematrix_footnote_bool ,
     footnotehyper .bool_set:N = \c__nicematrix_footnotehyper_bool ,
@@ -5044,7 +5389,7 @@
 \bool_if:NT \c__nicematrix_footnote_bool
   {
     \@ifclassloaded { beamer }
-      { \msg_info:nn { nicematrix } { Option~incompatible~with~Beamer } }
+      { \bool_set_false:N \c__nicematrix_footnote_bool }
       {
         \@ifpackageloaded { footnotehyper }
           { \__nicematrix_error:n { footnote~with~footnotehyper~package } }
@@ -5054,7 +5399,7 @@
 \bool_if:NT \c__nicematrix_footnotehyper_bool
   {
     \@ifclassloaded { beamer }
-      { \__nicematrix_info:n  { Option~incompatible~with~Beamer } }
+      { \bool_set_false:N \c__nicematrix_footnote_bool }
       {
         \@ifpackageloaded { footnote }
           { \__nicematrix_error:n { footnotehyper~with~footnote~package } }
@@ -5171,6 +5516,12 @@
     You~can't~use~an~ampersand~(\token_to_str:N &)~to~separate~columns~because~
     ~you~have~used~the~key~'light-syntax'.~This~error~is~fatal.
   }
+\__nicematrix_msg_new:nn { SubMatrix~too~large }
+  {
+    Your~command~\token_to_str:N \SubMatrix\
+    can't~be~drawn~because~your~matrix~is~too~small.\\
+    If~you~go~on,~this~command~will~be~ignored.
+  }
 \__nicematrix_msg_new:nn { double-backslash~in~light-syntax }
   {
     You~can't~use~\token_to_str:N \\~to~separate~rows~because~you~have~used~
@@ -5196,14 +5547,38 @@
     \int_use:N \g__nicematrix_row_total_int\ or~equal~to~'t',~'c'~or~'b'.\\
     If~you~go~on,~a~value~of~1~will~be~used.
   }
+\__nicematrix_msg_new:nn { Invalid~name~format }
+  {
+    You~can't~give~the~name~'\l_keys_value_tl'~to~a~\token_to_str:N
+    \SubMatrix.\\
+    A~name~must~be~accepted~by~the~regular~expression~[A-Za-z][A-Za-z0-9]*.\\
+    If~you~go~on,~this~key~will~be~ignored.
+  }
 \__nicematrix_msg_new:nn { empty~environment }
   { Your~\__nicematrix_full_name_env:\ is~empty.~This~error~is~fatal. }
+\__nicematrix_msg_new:nn { Delimiter~with~small }
+  {
+    You~can't~put~a~delimiter~in~the~preamble~of~your~\__nicematrix_full_name_env:\
+    because~the~key~'small'~is~in~force.\\
+    This~error~is~fatal.
+  }
 \__nicematrix_msg_new:nn { unknown~cell~for~line~in~code-after }
   {
     Your~command~\token_to_str:N\line\{#1\}\{#2\}~in~the~'code-after'~
     can't~be~executed~because~a~cell~doesn't~exist.\\
     If~you~go~on~this~command~will~be~ignored.
   }
+\__nicematrix_msg_new:nnn { Duplicate~name~for~SubMatrix }
+  {
+    The~name~'#1'~is~already~used~for~a~\token_to_str:N \SubMatrix\
+    in~this~\__nicematrix_full_name_env:.\\
+    If~you~go~on,~this~key~will~be~ignored.\\
+    For~a~list~of~the~names~already~used,~type~H~<return>.
+  }
+  {
+    The~names~already~defined~in~this~\__nicematrix_full_name_env:\ are:~
+    \seq_use:Nnnn \g__nicematrix_submatrix_names_seq { ~and~ } { ,~ } { ~and~ }.
+  }
 \__nicematrix_msg_new:nn { Hdotsfor~in~col~0 }
   {
     You~can't~use~\token_to_str:N \Hdotsfor\ in~an~exterior~column~of~
@@ -5258,7 +5633,7 @@
     \{NiceTabular\},~\{NiceArray\}~and~\{NiceMatrix\}. \\
     If~you~go~on,~this~command~will~be~ignored.
   }
-\__nicematrix_msg_new:nn { bottomule~without~booktabs }
+\__nicematrix_msg_new:nn { bottomrule~without~booktabs }
   {
     You~can't~use~the~key~'tabular/bottomrule'~because~you~haven't~
     loaded~'booktabs'.\\
@@ -5301,6 +5676,27 @@
     The~available~keys~are~(in~alphabetic~order):~-,~c,~draw,~fill,~l,~
     line-width~and~r.
   }
+\__nicematrix_msg_new:nnn { Unknown~key~for~CodeAfter }
+  {
+    The~key~'\l_keys_key_str'~is~unknown.\\
+    If~you~go~on,~it~will~be~ignored. \\
+    For~a~list~of~the~available~keys~in~\token_to_str:N
+    \CodeAfter,~type~H~<return>.
+  }
+  {
+    The~available~keys~are~(in~alphabetic~order):~
+    delimiters-color,~
+    sub-matrix~(several~subkeys)~
+    and~xdots~(several~subkeys).~
+    The~latter~is~for~the~command~\token_to_str:N \line.
+  }
+\__nicematrix_msg_new:nn { Unknown~key~for~SubMatrix }
+  {
+    The~key~'\l_keys_key_str'~is~unknown.\\
+    The~only~keys~available~here~are~'delimiters-color',~'extra-height',~
+    'left-xshift',~'name',~'right-xshift',~'slim'~and~'xshift'.\\
+    If~you~go~on,~this~key~will~be~ignored. \\
+  }
 \__nicematrix_msg_new:nnn { Unknown~key~for~notes }
   {
     The~key~'\l_keys_key_str'~is~unknown.\\
@@ -5351,17 +5747,15 @@
     left-margin,~
     letter-for-dotted-lines,~
     light-syntax,~
-    notes~(several subkeys),~
+    notes~(several~subkeys),~
     nullify-dots,~
     renew-dots,~
     renew-matrix,~
     right-margin,~
     small,~
-    transparent,~
+    sub-matrix~(several~subkeys),
     vlines,~
-    xdots/color,~
-    xdots/shorten~and~
-    xdots/line-style.
+    xdots~(several~subkeys).
   }
 \__nicematrix_msg_new:nnn { Unknown~option~for~NiceArray }
   {
@@ -5529,7 +5923,7 @@
   }
   {
     The~names~already~defined~in~this~document~are:~
-    \seq_use:Nnnn \g__nicematrix_names_seq { ,~ } { ,~ } { ~and~ }.
+    \seq_use:Nnnn \g__nicematrix_names_seq { ~and~ } { ,~ } { ~and~ }.
   }
 \__nicematrix_msg_new:nn { Option~auto~for~columns-width }
   {