testing for empty in \SetTemplateKays; more docu; changelog; open: cs…

…name change

base/changes.txt

@@ -6,6 +6,12 @@ to completeness or accuracy and it contains some references to files that are
 not part of the distribution.
 ================================================================================
 
+2025-01-08  Frank Mittelbach  <[email protected]>
+
+	* lttemplates.dtx (subsection{User functions}):
+	Speed up common case of \SetTemplateKeys, i.e., when the
+	key/val list is empty.
+
 2025-01-03  Frank Mittelbach  <[email protected]>
 
 	* lthooks.dtx (subsubsection{Updating code for hooks}):

base/lttemplates.dtx

@@ -36,7 +36,7 @@
 %<*driver>
 % \fi
 \ProvidesFile{lttemplates.dtx}
-  [2025-01-08 v1.0d LaTeX Kernel (Prototype document functions)]
+  [2025-01-08 v1.0e LaTeX Kernel (Prototype document functions)]
 % \iffalse
 \documentclass{l3doc}
 \GetFileInfo{lttemplates.dtx}
@@ -368,18 +368,34 @@
 %    also overwrite the current template key value settings by using the command
 %    \cs{SetTemplateKeys}, i.e., after the template default
 %    values and the values from the instance have been assigned.
-
+%
 %    The main use case for this command is the situation where there
-%    is an argument (normally \texttt{\#1}) to to the template in which
+%    is an argument (normally \texttt{\#1}) to the template in which
 %    a key/value list can be specified that overwrites the normal
-%    settings. In that case one could use something like
+%    settings. In that case one could use
 %\begin{quote}
-%  \verb/\tl_if_empty:nF {#1} { \SetTemplateKeys/\Arg{type}\Arg{template}\verb/{#1} }/
+%  \verb/\SetTemplateKeys/\Arg{type}\Arg{template}\verb/{#1}/
 %\end{quote}
-%    to process this key/value list. The outer test here, is only for
-%    speeding up the processing in case the list is empty.
-%
-%    This command is not supported outside of a template declaration
+%    to process this key/value list inside the template.
+%
+%    If the \meta{keyvals} argument contains keys not known to the
+%    \meta{template} they are simply ignored without generating an
+%    error. This way it is possible to apply the same \meta{keyvals}
+%    specified by the user on a document-level command or environment
+%    to several templates if their combination makes up that command
+%    or environment.  For example, a list, such as \env{enumerate}, is
+%    made up from a \texttt{blockenv}, \texttt{block}, \texttt{list},
+%    and a \texttt{para} template and in the single user-supplied
+%    optional argument to \verb=\begin{enumerate}= key/values for
+%    either of them might get specified. In fact, in that particular
+%    example, that key/val list is also saved and then applied to each
+%    \cs{item} which is implemented through an \texttt{item}
+%    template. This way, one can specify one-off settings to all items
+%    of a single whole list (on the environment level), as well as to
+%    individual items within a list (by specifying them in the
+%    optional argument of an \cs{item}).
+%
+%    The \cs{SetTemplateKeys} command is not supported outside of a template declaration
 %    and if used elsewhere has unpredictable results.
 %    If both \cs{AssignTemplateKeys} and \cs{SetTemplateKeys} are used
 %    they should be executed in that order.
@@ -2616,10 +2632,17 @@
 % \end{macro}
 %
 % \begin{macro}{\SetTemplateKeys}
-%   A friendly wrapper
+%   A friendly wrapper, with some speed up for the common case of the
+%    third argument being empty.
+% \changes{2025-01-08}{v1.0d}{Test for empty key/val list to speed up processing}
 %    \begin{macrocode}
 \cs_new_protected:Npn \SetTemplateKeys #1#2#3
-  { \keys_set_known:nnN { template / #1 / #2 } {#3} \l_@@_tmp_clist }
+  {
+    \tl_if_empty:nF {#3}
+      {
+        \keys_set_known:nnN { template / #1 / #2 } {#3} \l_@@_tmp_clist
+      }
+  }
 %    \end{macrocode}
 % \end{macro}
 %

required/latex-lab/latex-lab-block.dtx

@@ -9,8 +9,8 @@
 %
 %    https://www.latex-project.org/lppl.txt
 %
-\def\ltlabblockdate{2025-01-06}
-\def\ltlabblockversion{0.8x}
+\def\ltlabblockdate{2025-01-08}
+\def\ltlabblockversion{0.8y}
 %<*driver>
 \documentclass[kernel]{l3doc}
 \usepackage{amstext}
@@ -1109,7 +1109,7 @@
 {
   \@@_debug_typeout:n{\l_@@_env_name_tl -env-start}
 %  
-  \tl_if_empty:nF {#1} { \SetTemplateKeys{blockenv}{display}{#1} }
+  \SetTemplateKeys{blockenv}{display}{#1}
 %
 %    \end{macrocode}
 %    We need to know later if we have nested blockenvs inside
@@ -1443,7 +1443,7 @@
   para-class            = \l__tag_para_attr_class_tl ,                          
 }
 {
-  \tl_if_empty:nF {#1} { \SetTemplateKeys{para}{std}{#1} }
+  \SetTemplateKeys{para}{std}{#1}
   \skip_set:Nn \@rightskip \rightskip
 }
 %    \end{macrocode}
@@ -1485,7 +1485,7 @@
   parindent       = \l_@@_parindent_dim ,
 }
 {
-  \tl_if_empty:nF {#1} { \SetTemplateKeys{block}{display}{#1} }
+    \SetTemplateKeys{block}{display}{#1}
 %    \end{macrocode}
 %  \fmi{generalize heading usage (or drop?)}
 %    \begin{macrocode}
@@ -1954,7 +1954,7 @@
 %            to make use of user keys on the list level}
 %    \begin{macrocode}
     \@@_evaluate_saved_user_keys:nn {item}{std} 
-    \tl_if_empty:nF{#1}{ \SetTemplateKeys{item}{std}{#1} }
+    \SetTemplateKeys{item}{std}{#1}
 %    \end{macrocode}
 %    
 %    If no optional argument was given then \cs{l_@@_label_given_tl}