summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/l3packages/xtemplate.dtx
blob: 4aac33434a4e188c4181080731f8695202848092 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
% \iffalse meta-comment
%
%% File: xtemplate.dtx
%
% Copyright (C) 1999 Frank Mittelbach, Chris Rowley, David Carlisle
%           (C) 2004-2010 Frank Mittelbach, The LaTeX Project
%           (C) 2011-2024 The LaTeX Project
%
% It may be distributed and/or modified under the conditions of the
% LaTeX Project Public License (LPPL), either version 1.3c of this
% license or (at your option) any later version.  The latest version
% of this license is in the file
%
%    https://www.latex-project.org/lppl.txt
%
% This file is part of the "l3packages bundle" (The Work in LPPL)
% and all files in that bundle must be distributed together.
%
% -----------------------------------------------------------------------
%
% The development version of the bundle can be found at
%
%    https://github.com/latex3/latex3
%
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\usepackage{amstext}
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
%
% \title{^^A
%   The \pkg{xtemplate} package\\ Prototype document functions^^A
% }
%
% \author{^^A
%  The \LaTeX{} Project\thanks
%    {^^A
%      E-mail:
%        \href{mailto:latex-team@latex-project.org}
%          {latex-team@latex-project.org}^^A
%    }^^A
% }
%
% \date{Released 2024-03-14}
%
% \maketitle
%
% \begin{documentation}
%
% There are three broad \enquote{layers} between putting down ideas into
% a source file and ending up with a typeset document. These layers of
% document writing are
% \begin{enumerate}
%   \item authoring of the text with mark-up;
%   \item document layout design;
%   \item implementation (with \TeX{} programming) of the design.
% \end{enumerate}
% We write the text as an author, and we see the visual output of the design
% after the document is generated; the \TeX{} implementation in the middle is
% the glue between the two.
%
% \LaTeX{}'s greatest success has been to standardise a system of mark-up that
% balances the trade-off between ease of reading and ease of writing to suit
% almost all forms of technical writing. It's
% other original strength was a good background in typographical design; while
% the standard \LaTeXe{} classes look somewhat dated now in terms of their
% visual design, their typography is generally sound. (Barring the occasional
% minor faults.)
%
% However, \LaTeXe{} has always lacked a standard approach to customising
% the visual design of a document. Changing the looks of the standard classes
% involved either:
% \begin{itemize}
%   \item Creating a new version of the implementation code of the class and
%     editing it.
%   \item Loading one of the many packages to customise certain elements of
%     the standard classes.
%   \item Loading a completely different document class, such as
%     \cls{KOMA-Script} or \cls{memoir}, that allows easy customisation.
% \end{itemize}
% All three of these approaches have their drawbacks and learning curves.
%
% The idea behind \pkg{xtemplate} is to cleanly separate the three layers
% introduced at the beginning of this section, so that document authors who
% are not programmers can easily change the design of their documents.
% \pkg{xtemplate} also makes it easier for \LaTeX{} programmers to provide
% their own customisations on top of a pre-existing class.
%
% \section{What is a document?}
%
% Besides the textual content of the words themselves, the source file
% of a document contains mark-up elements that add structure to the
% document. These elements include sectional divisions, figure/table
% captions, lists of various sorts, theorems/proofs, and so on.
% The list will be different for every document that can be written.
%
% Each element can be represented logically without worrying about the
% formatting, with mark-up such as \cs{section}, \cs{caption},
% |\begin{enumerate}| and so on. The output of each one of these
% document elements will be a typeset representation of the information
% marked up, and the visual arrangement and design of these elements
% can vary widely in producing a variety of desired outcomes.
%
% For each type of document element, there may be design variations that
% contain the same sort of information but present it in slightly
% different ways. For example, the difference between a numbered and an
% unnumbered section, \cs{section} and |\section*|, or the difference
% between an itemised list or an enumerated list.
%
% There are three distinct layers in the definition of
% \enquote{a document} at this level
% \begin{enumerate}
%   \item semantic elements such as the ideas of sections and lists;
%   \item a set of design solutions for representing these elements
%     visually;
%   \item specific variations for these designs that represent the
%     elements in the document.
% \end{enumerate}
% In the parlance of the template system, these are called object types,
% templates, and instances, and they are discussed below in sections
% \ref{sec:objects}, \ref{sec:templates}, and~\ref{sec:instances},
% respectively.
%
% \section {Objects, templates, and instances}
%
% By formally declaring documents to be composed of mark-up elements
% grouped into objects, which are interpreted and typeset with a set of
% templates, each of which has one or more instances with which to
% compose each and every semantic unit of the text, we can cleanly
% separate the components of document construction.
%
% All of the structures provided by the template system are global,
% and do not respect \TeX{} grouping.
%
% \section{Object types}
% \label{sec:objects}
%
% An \emph{object type} (sometimes just \enquote{object}) is an
% abstract idea of a document element that takes a fixed number of
% arguments corresponding to the information from the document author
% that it is representing. A sectioning object, for example, might take
% three inputs: \enquote{title}, \enquote{short title}, and
% \enquote{label}.
%
% Any given document class will define which object types are to be
% used in the document, and any template of a given object type can be
% used to generate an instance for the object. (Of course, different
% templates will produce different typeset representations, but the
% underlying content will be the same.)
%
% \begin{function}{\DeclareObjectType}
%   \begin{syntax}
%     \cs{DeclareObjectType} \Arg{object type} \Arg{no. of args}
%   \end{syntax}
%  This function defines an \meta{object type} taking
%  \meta{number of arguments}, where the \meta{object type} is an
%  abstraction as discussed above. For example,
%   \begin{verbatim}
%     \DeclareObjectType{sectioning}{3}
%   \end{verbatim}
%  creates an object type \enquote{sectioning}, where each use of that
%  object type will need three arguments.
% \end{function}
%
% \section{Templates}
% \label{sec:templates}
%
% A \emph{template} is a generalised design solution for representing
% the information of a specified object type. Templates that do the same
% thing, but in different ways, are grouped together by their object type
% and given separate names. There are two important parts to a template:
% \begin{itemize}
%   \item the parameters it takes to vary the design it is producing;
%   \item the implementation of the design.
% \end{itemize}
% As a document author or designer does not care about the
% implementation but rather only the interface to the template, these two
% aspects of the template definition are split into two independent
% declarations, \cs{DeclareTemplateInterface} and
% \cs{DeclareTemplateCode}.
%
% \begin{function}{\DeclareTemplateInterface}
%   \begin{syntax}
%     \cs{DeclareTemplateInterface}
%     ~~\Arg{object type} \Arg{template} \Arg{no.~of args}
%     ~~\Arg{key list}
%   \end{syntax}
%   A \meta{template} interface is declared for a particular
%   \meta{object type}, where the \meta{number of arguments} must
%   agree with the object type declaration. The interface itself is
%   defined by the \meta{key list}, which is itself a key--value list
%   taking a specialized format:
%   \begin{quotation}
%     \obeylines
%     \noindent
%      \meta{key1}~":"~\meta{key type1}~","
%      \meta{key2}~":"~\meta{key type2}~","
%      \meta{key3}~":"~\meta{key type3}~"="~\meta{default3}~","
%      \meta{key4}~":"~\meta{key type4}~"="~\meta{default4}~","
%      \ldots
%    \end{quotation}
%   Each \meta{key} name should consist of \textsc{ascii} characters,
%   with the exception of |,|, |=| and \verb*| |. The recommended form
%   for key names is to use lower case letters, with dashes to separate
%   out different parts. Spaces are ignored in key names, so they can be
%   included or missed out at will. Each \meta{key} must have a
%   \meta{key type}, which defined the type of input that the \meta{key}
%   requires. A full list of key types is given in
%   Table~\ref{tab:key-types}.  Each key may have a \meta{default}
%   value, which will be used in by the template if the \meta{key} is
%   not set explicitly. The \meta{default} should be of the correct
%   form to be accepted by the \meta{key type} of the \meta{key}: this
%   is not checked by the code.
% \end{function}
%
%   \begin{table}
%     \centering
%     \begin{tabular}{>{\ttfamily}ll}
%       \toprule
%       \multicolumn{1}{l}{Key-type} & Description of input \\
%       \midrule
%       boolean    & \texttt{true} or \texttt{false}            \\
%       choice\Arg{choices}
%         & A list of pre-defined \meta{choices} \\
%       commalist  & A comma-separated list                        \\
%       function\Arg{$N$}
%         & A function definition with $N$ arguments
%          ($N$ from $0$ to $9$) \\
%       instance\Arg{name}
%         & An instance of type \meta{name} \\
%       integer    & An integer or integer expression            \\
%       length     & A fixed length                              \\
%       muskip     & A math length with shrink and stretch components \\
%       real       & A real (floating point) value               \\
%       skip       & A length with shrink and stretch components \\
%       tokenlist  & A token list: any text or commands          \\
%       \bottomrule
%     \end{tabular}
%     \caption{Key-types for defining template interfaces with
%       \cs{DeclareTemplateInterface}.}
%     \label{tab:key-types}
%   \end{table}
%
% \begin{function}{\KeyValue}
%   \begin{syntax}
%     \cs{KeyValue} \Arg{key name}
%   \end{syntax}
%   There are occasions where the default (or value) for one key
%   should be taken from another. The \cs{KeyValue} function can be
%   used to transfer this information without needing to know the
%   internal implementation of the key:
%   \begin{verbatim}
%     \DeclareTemplateInterface { object } { template } { no. of args }
%       {
%         key-name-1 : key-type = value ,
%         key-name-2 : key-type = \KeyValue { key-name-1 },
%         ...
%       }
%   \end{verbatim}
% \end{function}
%
% \begin{function}{\DeclareTemplateCode}
%   \begin{syntax}
%     \cs{DeclareTemplateCode}
%     ~~\Arg{object type} \Arg{template} \Arg{no.~of args}
%     ~~\Arg{key bindings} \Arg{code}
%   \end{syntax}
%   The relationship between a templates keys and the internal
%   implementation is created using the \cs{DeclareTemplateCode}
%   function. As with \cs{DeclareTemplateInterface}, the
%   \meta{template} name is given along with the \meta{object type}
%   and \meta{number of arguments} required. The \meta{key bindings}
%   argument is a key--value list which specifies the relationship
%   between each \meta{key} of the template interface with an
%   underlying\meta{variable}.
%
%   \begin{quotation}
%     \obeylines
%     \noindent
%     \meta{key1}~"="~\meta{variable1},
%     \meta{key2}~"="~\meta{variable2},
%     \meta{key3}~"="~global~\meta{variable3},
%     \meta{key4}~"="~global~\meta{variable4},
%     \ldots
%   \end{quotation}
%   With the exception of the choice, code and function key types,
%   the \meta{variable} here should be the name of an existing
%   \LaTeX3 register. As illustrated, the key word \enquote{global}
%   may be included in the listing to indicate that the \meta{variable}
%   should be assigned globally. A full list of variable bindings is
%   given in Table~\ref{tab:key-vars}.
%
%   The \meta{code} argument of \cs{DeclareTemplateCode} is used
%   as the replacement text for the template when it is used, either
%   directly or as an instance. This may therefore accept arguments
%   |#1|, |#2|, \emph{etc}.~as detailed by the \meta{number of arguments}
%   taken by the object type.
% \end{function}
%
%   \begin{table}
%     \centering
%     \begin{tabular}{>{\ttfamily}ll}
%       \toprule
%       \multicolumn{1}{l}{Key-type} & Description of binding \\
%       \midrule
%       boolean    & Boolean variable, \emph{e.g}.~\cs{l_tmpa_bool}      \\
%       choice
%         & List of choice implementations
%         (see Section~\ref{sec:choices-key}) \\
%       commalist  & Comma list, \emph{e.g}.~\cs{l_tmpa_clist}           \\
%       function
%         & Function taking $N$ arguments, \emph{e.g}.~\cs{use_i:nn}     \\
%       instance \\
%       integer    & Integer variable, \emph{e.g}.~\cs{l_tmpa_int}       \\
%       length     & Dimension variable, \emph{e.g}.~\cs{l_tmpa_dim}     \\
%       muskip     & Muskip variable, \emph{e.g}.~\cs{l_tmpa_muskip}     \\
%       real       & Floating-point variable, \emph{e.g}.~\cs{l_tmpa_fp} \\
%       skip       & Skip variable, \emph{e.g}.~\cs{l_tmpa_skip}         \\
%       tokenlist  & Token list variable, \emph{e.g}.~\cs{l_tmpa_tl}     \\
%       \bottomrule
%     \end{tabular}
%     \caption{Bindings required for different key types when defining
%       template implementations with \cs{DeclareTemplateCode}. Apart
%       from \texttt{code}, \texttt{choice} and \texttt{function}
%       all of these accept the key word \texttt{global} to carry
%       out a global assignment.}
%     \label{tab:key-vars}
%   \end{table}
%
% \begin{function}{\AssignTemplateKeys}
%   \begin{syntax}
%     \cs{AssignTemplateKeys}
%   \end{syntax}
%   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
%   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}
%
% \section{Multiple choices}
% \label{sec:choices-key}
%
% The \texttt{choice} key type implements multiple choice input. At the
% interface level, only the list of valid choices is needed:
% \begin{verbatim}
%   \DeclareTemplateInterface { foo } { bar } { 0 }
%     { key-name : choice { A, B, C } }
% \end{verbatim}
% where the choices are given as a comma-list (which must therefore
% be wrapped in braces). A default value can also be given:
% \begin{verbatim}
%   \DeclareTemplateInterface { foo } { bar } { 0 }
%     { key-name : choice { A, B, C } = A }
% \end{verbatim}
%
% At the implementation level, each choice is associated with code,
% using a nested key--value list.
% \begin{verbatim}
%   \DeclareTemplateCode { foo } { bar } { 0 }
%     {
%       key-name =
%         {
%           A = Code-A ,
%           B = Code-B ,
%           C = Code-C
%         }
%      }
%      { ... }
% \end{verbatim}
% The two choice lists should match, but in the implementation a
% special \texttt{unknown} choice is also available. This can be used
% to ignore values and implement an \enquote{else} branch:
% \begin{verbatim}
%   \DeclareTemplateCode { foo } { bar } { 0 }
%     {
%       key-name =
%         {
%           A       = Code-A ,
%           B       = Code-B ,
%           C       = Code-C ,
%           unknown = Else-code
%         }
%      }
%      { ... }
% \end{verbatim}
% The \texttt{unknown} entry must be the last one given, and should
% \emph{not} be listed in the interface part of the template.
%
% For keys which accept the values \texttt{true} and \texttt{false}
% both the boolean and choice key types can be used. As template
% interfaces are intended to prompt clarity at the design level, the
% boolean key type should be favoured, with the choice type reserved
% for keys which take arbitrary values.
%
% \section{Instances}
% \label{sec:instances}
%
% After a template is defined it still needs to be put to use. The
% parameters that it expects need to be defined before it can be used in
% a document. Every time a template has parameters given to it, an
% \emph{instance} is created, and this is the code that ends up in the
% document to perform the typesetting of whatever pieces of information
% are input into it.
%
% For example, a template might say \enquote{here is a section with or
% without a number that might be centred or left aligned and print its
% contents in a certain font of a certain size, with a bit of a gap
% before and after it} whereas an instance declares \enquote{this is a
% section with a number, which is centred and set in $12\,\text{pt}$
% italic with a $10\,\text{pt}$ skip before and a
% $12\,\text{pt}$ skip after it}. Therefore, an instance is just a
% frozen version of a template with specific settings as chosen by the
% designer.
%
% \begin{function}{\DeclareInstance}
%   \begin{syntax}
%     \cs{DeclareInstance}
%     ~~\Arg{object type} \Arg{instance} \Arg{template} \Arg{parameters}
%   \end{syntax}
%   This function uses a \meta{template} for an \meta{object type}
%   to create an \meta{instance}. The \meta{instance} will be set
%   up using the \meta{parameters}, which will set some of the
%   \meta{keys} in the \meta{template}.
%
%   As a practical example, consider an object type for document sections
%   (which might include chapters, parts, sections, \emph{etc}.), which
%   is called \texttt{sectioning}. One possible template for this
%   object type might be called \texttt{basic}, and one instance of this
%   template would be a numbered section. The instance declaration might
%   read:
%   \begin{verbatim}
%     \DeclareInstance { sectioning } { section-num } { basic }
%       {
%         numbered      = true ,
%         justification = center ,
%         font          =\normalsize\itshape ,
%         before-skip   = 10pt ,
%         after-skip    = 12pt ,
%       }
%   \end{verbatim}
%   Of course, the key names here are entirely imaginary, but illustrate
%   the general idea of fixing some settings.
% \end{function}
%
% \begin{function}{\IfInstanceExistT, \IfInstanceExistF, \IfInstanceExistTF}
%   \begin{syntax}
%     \cs{IfInstanceExistTF} \Arg{object type} \Arg{instance} \Arg{true code} \Arg{false code}
%   \end{syntax}
%   Tests if the named \meta{instance} of a \meta{object type} exists, and
%   then inserts the appropriate code into the input stream.
% \end{function}
%
% \begin{function}{\DeclareInstanceCopy}
%   \begin{syntax}
%     \cs{DeclareInstanceCopy}
%     ~~\Arg{object type} \Arg{instance2} \Arg{instance1}
%   \end{syntax}
%   Copies the \meta{values} for \meta{instance1} for an
%   \meta{object type} to \meta{instance2}.
% \end{function}
%
% \section{Document interface}
%
% After the instances have been chosen, document commands must be
% declared to use those instances in the document. \cs{UseInstance}
% calls instances directly, and this command should be used internally
% in document-level mark-up.
%
% \begin{function}{\UseInstance}
%   \begin{syntax}
%     \cs{UseInstance}
%     ~~\Arg{object type} \Arg{instance} \meta{arguments}
%   \end{syntax}
%   Uses an \meta{instance} of the \meta{object type}, which will require
%   \meta{arguments} as determined by the number specified for the
%   \meta{object type}. The \meta{instance} must have been declared
%   before it can be used, otherwise an error is raised.
% \end{function}
%
% \begin{function}{\UseTemplate}
%   \begin{syntax}
%     \cs{UseTemplate} \Arg{object type} \Arg{template}
%     ~~\Arg{settings} \meta{arguments}
%   \end{syntax}
%   Uses the \meta{template} of the specified \meta{object type},
%   applying the \meta{settings} and absorbing \meta{arguments} as
%   detailed by the \meta{object type} declaration. This in effect
%   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.
%
%   This function can also be used as the argument to \texttt{instance}
%   key types:
%   \begin{verbatim}
%     \DeclareInstance { object } { template } { instance }
%       {
%         instance-key =
%           \UseTemplate { object2 } { template2 } { <settings> }
%       }
%   \end{verbatim}
% \end{function}
%
% \section{Changing existing definitions}
%
% Template parameters may be assigned specific defaults for instances
% to use if the instance declaration doesn't explicit set those
% parameters. In some cases, the document designer will wish to edit
% these defaults to allow them to \enquote{cascade} to the instances.
% The alternative would be to set each parameter identically for each
% instance declaration, a tedious and error-prone process.
%
% \begin{function}{\EditTemplateDefaults}
%   \begin{syntax}
%     \cs{EditTemplateDefaults}
%     ~~\Arg{object type} \Arg{template} \Arg{new defaults}
%   \end{syntax}
%   Edits the \meta{defaults} for a \meta{template} for an
%   \meta{object type}. The \meta{new defaults}, given as a key--value
%   list, replace the existing defaults for the \meta{template}. This
%   means that the change will apply to instances declared after the
%   editing, but that instances which have already been created are
%   unaffected.
% \end{function}
%
% \begin{function}{\EditInstance}
%   \begin{syntax}
%     \cs{EditInstance}
%     ~~\Arg{object type} \Arg{instance} \Arg{new values}
%   \end{syntax}
%   Edits the \meta{values} for an \meta{instance} for an
%   \meta{object type}. The \meta{new values}, given as a key--value
%   list, replace the existing values for the \meta{instance}. This
%   function is complementary to \cs{EditTemplateDefaults}:
%   \cs{EditInstance} changes a single instance while leaving the
%   template untouched.
% \end{function}
%
% \section{When template parameters should be frozen}
%
% A class designer may be inheriting templates declared by someone else,
% either third-party code or the \LaTeX{} kernel itself. Sometimes these
% templates will be overly general for the purposes of the document.
% The user should be able to customise parts of the template instances,
% but otherwise be restricted to only those parameters allowed by the
% designer.
%
% \begin{function}{\DeclareRestrictedTemplate}
%   \begin{syntax}
%     \cs{DeclareRestrictedTemplate}
%     ~~\Arg{object type} \Arg{parent template} \Arg{new template}
%     ~~\Arg{parameters}
%   \end{syntax}
%   Creates a copy of the \meta{parent template} for the
%   \meta{object type} called \meta{new template}. The key--value list
%   of \meta{parameters} applies in the \meta{new template} and cannot
%   be changed when creating an instance.
% \end{function}
%
% \section{\emph{Ad hoc} adjustment of templates}
%
% \begin{function}{\SetTemplateKeys}
%   \begin{syntax}
%    \cs{SetTemplateKeys} \Arg{object 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}
%   \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}
%   \SetTemplateKeys{MyObj}{TemplateA}
%     {
%       akey = OtherTokens ,
%       bkey = \AltFunc:nn
%     }
% \end{verbatim}
%
% \section{Getting information about templates and instances}
%
% \begin{function}{\ShowInstanceValues}
%   \begin{syntax}
%    \cs{ShowInstanceValues} \Arg{object type} \Arg{instance}
%   \end{syntax}
%   Shows the \meta{values} for an \meta{instance} of the given
%   \meta{object type} at the terminal.
% \end{function}
%
% \begin{function}{\ShowTemplateCode}
%   \begin{syntax}
%     \cs{ShowTemplateCode} \Arg{object type} \Arg{template}
%   \end{syntax}
%   Shows the \meta{code} of a \meta{template} for an \meta{object type}
%   in the terminal.
% \end{function}
%
% \begin{function}{\ShowTemplateDefaults}
%   \begin{syntax}
%     \cs{ShowTemplateDefaults} \Arg{object type} \Arg{template}
%   \end{syntax}
%   Shows the \meta{default} values of a \meta{template} for an
%   \meta{object type} in the terminal.
% \end{function}
%
% \begin{function}{\ShowTemplateInterface}
%   \begin{syntax}
%     \cs{ShowTemplateInterface} \Arg{object type} \Arg{template}
%   \end{syntax}
%  Shows the \meta{keys} and associated \meta{key types} of a
%   \meta{template} for an \meta{object type} in the terminal.
% \end{function}
%
% \begin{function}{\ShowTemplateVariables}
%   \begin{syntax}
%     \cs{ShowTemplateVariables} \Arg{object type} \Arg{template}
%   \end{syntax}
%   Shows the \meta{variables} and associated \meta{keys} of a
%   \meta{template} for an \meta{object type} in the terminal. Note that
%   \texttt{code} and \texttt{choice} keys do not map directly to variables
%   but to arbitrary code. For \texttt{choice} keys, each valid choice
%   is shown as a separate entry in the list, with the key name and choice
%   separated by a space, for example
%   \begin{verbatim}
%     Template 'example' of object type 'example' has variable mapping:
%     >  demo unknown  =>  \def \demo {?}
%     >  demo c  =>  \def \demo {c}
%     >  demo b  =>  \def \demo {b}
%     >  demo a  =>  \def \demo {a}.
%   \end{verbatim}
%   would be shown for a choice key \texttt{demo} with valid choices
%   \texttt{a}, \texttt{b} and \texttt{c}, plus code for an \texttt{unknown}
%   branch.
% \end{function}
%
% \section{Collections}
%
% The implementation of templates includes a concept termed
% \enquote{collections}. The idea is that by activating a collection, a
% set of instances can rapidly be set up. An example use case would be
% collections for \texttt{frontmatter}, \texttt{mainmatter} and
% \texttt{backmatter} in a book. This mechanism is currently implemented
% by the commands \cs{DeclareCollectionInstance}, \cs{EditCollectionInstance}
% and \cs{UseCollection}. However, while the idea of switchable instances is
% a useful one, the team feel that collections are not the correct way to
% achieve this, at least with the current approach. As such, the collection
% functions should be regarded as deprecated: they remain available to support
% existing code, but will be removed when a better mechanism is developed.
%
%
% \begin{function}{\ShowCollectionInstanceValues}
%   \begin{syntax}
%    \cs{ShowInstanceValues} \Arg{collection} \Arg{object type} \Arg{instance}
%   \end{syntax}
%   Shows the \meta{values} for an \meta{instance} within
%   a \meta{collection} of the given \meta{object type} at the terminal.
%   As for other collection commands, this should be regarded as deprecated.
% \end{function}
%
% \end{documentation}
%
% \begin{implementation}
%
% \section{\pkg{xtemplate} implementation}
%
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
%    \begin{macrocode}
%<@@=template>
%    \end{macrocode}
%
% \begin{macro}{\DeclareRestrictedTemplate}
% \begin{macro}{\DeclareObjectType}
%   If the new kernel code is not loaded, hand over to the frozen version.
%   Otherwise, make a couple of compatibility additions.
%    \begin{macrocode}
\@ifundefined{NewTemplateType}
  {%
    \input{xtemplate-2023-10-10.sty}%
    \endinput
  }
  {%
    \ProvidesExplPackage{xtemplate}{2024-03-14}{}
      {L3 Experimental prototype document functions}
    \long\protected\def\DeclareRestrictedTemplate#1#2#3#4{%
      \DeclareTemplateCopy{#1}{#3}{#2}%
      \EditTemplateDefaults{#1}{#3}{#4}%
    }%
  }
\ExplSyntaxOn
\cs_new_protected:Npn \DeclareObjectType #1#2
  { \@@_declare_type:nn {#1} {#2} }
\ExplSyntaxOff
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
%</package>
%    \end{macrocode}
%
%\end{implementation}
%
%\PrintIndex