Set template keys docu

base/lttemplates.dtx

@@ -36,7 +36,7 @@
 %<*driver>
 % \fi
 \ProvidesFile{lttemplates.dtx}
-  [2024-11-17 v1.0d LaTeX Kernel (Prototype document functions)]
+  [2025-01-08 v1.0d LaTeX Kernel (Prototype document functions)]
 % \iffalse
 \documentclass{l3doc}
 \GetFileInfo{lttemplates.dtx}
@@ -320,7 +320,7 @@
 %       \toprule
 %       \multicolumn{1}{l}{Key-type} & Description of binding \\
 %       \midrule
-%       \    & Boolean variable, \emph{e.g}.~\cs{l_tmpa_bool}      \\
+%       boolean    & Boolean variable, \emph{e.g}.~\cs{l_tmpa_bool}      \\
 %       choice
 %         & List of choice implementations
 %         (see Section~\ref{sec:choices-key}) \\
@@ -351,12 +351,41 @@
 %   In the final argument of \cs{DeclareTemplateCode} the assignment of
 %   keys defined by the template may be delayed by including the command
 %   \cs{AssignTemplateKeys}. If this is \emph{not} present, keys are assigned
-%   immediately before the template code. If \cs{AssignTemplateKeys} is
+%   immediately before the template code. If an
+%    \cs{AssignTemplateKeys} command is
 %   present, assignment is delayed until this point. Note that the
 %   command must be \emph{directly} present in the code, not placed
 %   within a nested command/macro.
 % \end{function}
 %
+
+% \begin{function}{\SetTemplateKeys}
+%   \begin{syntax}
+%    \cs{SetTemplateKeys} \Arg{type} \Arg{template} \Arg{keyvals}
+%   \end{syntax}
+
+%    In the final argument of \cs{DeclareTemplateCode} one can
+%    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
+%    a key/value list can be specified that overwrites the normal
+%    settings. In that case one could use something like
+%\begin{quote}
+%  \verb/\tl_if_empty:nF {#1} { \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
+%    and if used elsewhere has unpredictable results.
+%    If both \cs{AssignTemplateKeys} and \cs{SetTemplateKeys} are used
+%    they should be executed in that order.
+% \end{function}
+%
+
 % \begin{function}{\DeclareTemplateCopy}
 %   \begin{syntax}
 %     \cs{DeclareTemplateCopy}
@@ -517,7 +546,7 @@
 %   is the same as creating an instance using \cs{DeclareInstance}
 %   and immediately using it with \cs{UseInstance}, but without the
 %   instance having any further existence. It is therefore useful where
-%   a template needs to be used once.
+%   a template needs to be used only once.
 %
 %   This function can also be used as the argument to \texttt{instance}
 %   key types:
@@ -565,39 +594,6 @@
 %   template untouched.
 % \end{function}
 %
-% \section{\emph{Ad hoc} adjustment of templates}
-%
-% \begin{function}{\SetTemplateKeys}
-%   \begin{syntax}
-%    \cs{SetTemplateKeys} \Arg{type} \Arg{template} \Arg{keyvals}
-%   \end{syntax}
-%   At point of use it may be useful to apply changed to individual instances.
-%   This is supported as each template key is made available for adjustment
-%   using \cs{SetTemplateKeys}.
-% \end{function}
-%
-% For example, after
-% \begin{verbatim}
-%   \NewTypeType{MyObj}{0}
-%   \DeclareTemplateInterface{MyObj}{TemplateA}{0}
-%     {
-%       akey: tokenlist  ,
-%       bkey: function{2}
-%     }
-%   \DeclareTemplateCode{MyObj}{TemplateA}{0}
-%     {
-%       akey = SomeTokens ,
-%       bkey = \func:nn ,
-%     }
-% \end{verbatim}
-% the template keys could be adjusted in an \emph{ad hoc} fashion using
-% \begin{verbatim}
-%   \SetTemplateKeys{MyObj}{TemplateA}
-%     {
-%       akey = OtherTokens ,
-%       bkey = \AltFunc:nn
-%     }
-% \end{verbatim}
 %
 % \section{Getting information about templates and instances}
 %