updating and reorganizing docu after review

base/lttemplates.dtx

@@ -36,7 +36,7 @@
 %<*driver>
 % \fi
 \ProvidesFile{lttemplates.dtx}
-  [2025-01-18 v1.0e LaTeX Kernel (Prototype document functions)]
+  [2025-01-20 v1.0e LaTeX Kernel (Prototype document functions)]
 % \iffalse
 \documentclass{l3doc}
 \GetFileInfo{lttemplates.dtx}
@@ -359,10 +359,12 @@
 % \end{function}
 %
 
-% \begin{function}{\SetKnownTemplateKeys,\SetTemplateKeys}
+% \begin{function}{\SetKnownTemplateKeys,\SetTemplateKeys,\UnusedTemplateKeys}
 %   \begin{syntax}
 %   \cs{SetKnownTemplateKeys} \Arg{type} \Arg{template} \Arg{keyvals}
 %   \cs{SetTemplateKeys}      \Arg{type} \Arg{template} \Arg{keyvals}
+%
+%   \cs{UnknownTemplateKeys} \% all \meta{keyvals} unused by previous \cs{SetKnownTemplateKeys}
 %   \end{syntax}
 %
 %    In the final argument of \cs{DeclareTemplateCode} one can also
@@ -371,6 +373,12 @@
 %    \cs{SetTemplateKeys}, i.e., they can overwrite the template default values and
 %    the values assigned by the instance.
 %
+%    The \cs{SetKnownTemplateKeys} and \cs{SetTemplateKeys} commands
+%    are only supported within the code of a template; using them
+%    elsewhere has unpredictable results.  If they are used together
+%    with \cs{AssignTemplateKeys} then the latter command should come first
+%    in the template code.
+%
 %    The main use case for these commands is the situation where there
 %    is an argument (normally \texttt{\#1}) to the template in which
 %    a key/value list can be specified that overwrites the normal
@@ -379,18 +387,20 @@
 %  \verb/\SetKnownTemplateKeys/\Arg{type}\Arg{template}\verb/{#1}/
 %\end{quote}
 %    to process this key/value list inside the template.
-% \end{function}
 %
-%    If the \meta{keyvals} argument contains keys not known to the
+%    If \cs{SetKnownTemplateKeys} is executed and the \meta{keyvals} argument contains keys not known to the
 %    \meta{template} they are simply ignored and stored in the
 %    tokenlist \cs{UnusedTemplateKeys}
 %    without generating an error. This way it is possible to
 %    apply the same key/val list specified by the user on a
 %    document-level command or environment to several templates, which
 %    is useful, if the command or environment is implemented by calling several different template instances.
-%    As a variation of that, you can use this key/value
+%
+% \end{function}
+%
+%    As a variation of that, you can use this key/val
 %    list the first time, and for the next template instance use what remains in
-%    \cs{UnusedTemplateKeys}. The final processing step could then be
+%    \cs{UnusedTemplateKeys} (i.e., the key/val list with only the keys that have not been processed previously). The final processing step could then be
 %    \cs{SetTemplateKeys}, which unconditionally attempts to set the
 %    \meta{keyvals} received in its third argument. This command
 %    complains if any of them are unknown keys. Alternatively, you
@@ -402,12 +412,14 @@
 %    case use  \cs{SetKnownTemplateKeys} and afterwards check whether
 %    \cs{UnusedTemplateKeys} is empty;  if it is not empty then generate your own
 %    error message.}
-
+%
 %    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 of \env{enumerate} key/values by any of these templates might
-%    be specified. In fact, in that particular example,
+%    argument of \env{enumerate} key/values for any of these templates might
+%    be specified.
+%
+%    In fact, in the particular example of list environments,
 %    the supplied key/value 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 for all the items
@@ -427,12 +439,6 @@
 %    generate a warning message, which is easy, given that the unused
 %    key/values are available in the \cs{UnusedTemplateKeys} variable.
 %
-%    The \cs{SetKnownTemplateKeys} and \cs{SetTemplateKeys} commands
-%    are only supported within the code of a template; using them
-%    elsewhere has unpredictable results.  If they are used together
-%    with \cs{AssignTemplateKeys} then the latter command should come first
-%    in the template code.
-%
 %
 % \begin{function}{\DeclareTemplateCopy}
 %   \begin{syntax}