[latex3-commits] [git/LaTeX3-latex3-latex3] main: Document ad hoc value adustment (f402746a8)

[Joseph Wright]

Repository : https://github.com/latex3/latex3
On branch  : main
Link       : https://github.com/latex3/latex3/commit/f402746a8b5090c140c6e93edc056974b86fcc94

>---------------------------------------------------------------

commit f402746a8b5090c140c6e93edc056974b86fcc94
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date:   Wed May 25 21:28:08 2022 +0100

    Document ad hoc value adustment


>---------------------------------------------------------------

f402746a8b5090c140c6e93edc056974b86fcc94
 l3packages/CHANGELOG.md            |  3 +++
 l3packages/xtemplate/xtemplate.dtx | 29 +++++++++++++++++++++++++++++
 2 files changed, 32 insertions(+)

diff --git a/l3packages/CHANGELOG.md b/l3packages/CHANGELOG.md
index b2a8dedbd..071b4b7d5 100644
--- a/l3packages/CHANGELOG.md
+++ b/l3packages/CHANGELOG.md
@@ -7,6 +7,9 @@ this project uses date-based 'snapshot' version identifiers.
 
 ## [Unreleased]
 
+### Changed
+- Allow for _ad hoc_ adjustment of template values
+
 ## [2022-01-12]
 
 ### Changed
diff --git a/l3packages/xtemplate/xtemplate.dtx b/l3packages/xtemplate/xtemplate.dtx
index 6605e277b..02f5d8242 100644
--- a/l3packages/xtemplate/xtemplate.dtx
+++ b/l3packages/xtemplate/xtemplate.dtx
@@ -587,6 +587,35 @@
 %   be changed when creating an instance.
 % \end{function}
 %
+% \section{\emph{Ad hoc} adjustment of templates}
+%
+% 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
+% the \texttt{keys} module under the path
+% \texttt{template/\meta{object}/\meta{template}}.
+% For example, after
+% \begin{verbatim}
+%   \DeclareObjectType{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}
+%   \keys_set:nn { template / MyObj /TemplateA }
+%     {
+%       akey = OtherTokens ,
+%       bkey = \AltFunc:nn
+%     }
+% \end{verbatim}
+%
 % \section{Getting information about templates and instances}
 %
 % \begin{function}{\ShowInstanceValues}