Frank Mittelbach wrote:
> here is my view of that world:
> 
> A template is function that receives document input in a defined number of
> arguments (which can be zero) processes this document input and generates some
> output. Tied to a template is always an implementation of how the output is
> produced. By offering design parameters that give the designer a certain
> amount of flexibility to influence the output (the layout). Depending on the
> template implementation that flexibility might be higher or lower. Both the
> implementation and the parameters define the range of layouts a template can
> produce.
> 
> To take a simple example from the 2e world: \@startsection could be viewed as
> a template for producing headings offering something like 8 or 10 parameters
> for the designer to specify the heading layout (somewhat cryptically for sure,
> like negating values to indicate certain things, but lets ignore that for the
> moment). The more important aspect is that \@startsection, while offering
> design flexibility, was offering that only in a specific range: you can
> produce run-in heading, you can produce vertically oriented headings both with
> or without numbers but you can't produce something like LaTeX's chapter
> heading or other heading layouts. If you want to you have to pick a different
> template (not that 2e actually offer you much in that case, ie only \secdef to
> build one on your own).
> 
> But the point being that each template is providing a range of layouts and you
> will have a number of templates to choose from depending on your document
> layout needs.
> 
> So if you step back and consider what such a set of templates (plus those that
> haven't been written, but could be imagined) have in common, what do we find?
> 
> I think what we find as the common level is an abstraction that divides the
> templates into equivalent classes where one template within a class is
> exchangable with another without restrictions.
> 
> The equivalences classes are defined by
> 
>   * the number of template arguments
>   * the kind of document input the arguments expect
>   * the conceptual type of activity the template provides (ie abstracted from
>      layout considerations)
> 
> One level further up in the abstraction you then have equivalent classes of document
> designs and the template types are used (though not directly) to define those.
> 
> In contrast to templates, where I envision more and more templates to appear
> to satisfy additional layout needs, I think that template types to a large
> extent will be defined once fairly close to the kernel, e.g., the practice of
> current xpackages to define template types along the way is more a bootup
> process than something that should stay this way in the long run.
> 
> So what are the benfits of thinking with template types?
> 
> Well for starters, "instances" now have types so on that abstraction level it
> is well-defined what can be replaced by what. (That is actually a mistake in
> Joseph's earlier mail where he simplified too much):
> 
> \DeclareDocumentCommand \chapter { s o m } {
>   \IfNoValueTF {#2} {
>     % No short title, so re-use the long one
>     \UseInstance { chapter } { division } #1 {#3} {#3}
>   }{
>     % Separate short title
>     \UseInstance { chapter } { division } #1 {#2} {#3}
>   }
> }
> 
> here "division" would be a type and on that level it would not be known which
> template was used to define the "chapter" instance other than it has to be a
> template of template type "division"
> 
> Thus if you define a bunch of such document commands you effectively define a
> document class by providing
> 
>   * the document level syntax, e.g. a \chapter command in this class takes an
>     optional star an optional argument (denoting ...) and a mandatory argument
>     (denoting ...)
> 
>   * and its semantic meaning by restricting the possible layouts to those of a
>     specific type (which provides this meaning).
> 
> But you do not define anything on the layout level through explicitly mentioning
> templates to use (which define ranges of layouts).
> 
> So to produce an instance of this document class, say, proceedings for the
> AMS,  the designer would need instantiate the named instances, ie for the
> above he/she would need to do
> 
> \DeclareInstance { division } { chapter } {  <some-suitable-template> }
>                                           {  <suitable-parameter-settings> }
> 
> Another, though related aspect is the use of template instances within parameters
> to other templates, e.g., if "pshape" is a template type for templates that
> format paragraphs in certain ways then more complex templates, e.g., one for
> formatting a caption may have parameters of type "pshape" ie expecting to
> receive an instance of that type (and not an specific template)
> 
> 
> in summary, I think that template types are important ingredients for
> providing a clean and manageable separation between document syntax, semantics
> and layout. Perhaps the name isn't perfect tying it to "template" rather than
> tying it to "semantics" though I couldn't think of a better name back then nor
> now really

Hello Frank,

Thanks very much for the detailed explanation.  I think I see how things
work now.  To make sure, I'll run through a couple of examples, with a
few terminology changes I think might help.

I'd say "template class" is clearer than "template type" (you could also
consider "set", but I'm not so sure about that). So, following my
division-of-the-document example, the base layer could be

\DeclareTemplateClass { sectioning } 3 % Assuming 3 args.

then there might be some templates: for an book-like document there
might be two:

\DeclareTemplate { sectioning } { chapter } { <keys> } { <code> }
\DeclareTemplate { sectioning } { section } { <keys> } { <code> }

(Based on the \cs_set:Nn idea, I'm not keen on repeating the number of
arguments here: should be picked up from the type.)

Finally, there are instances (I'm going to use a function
"\DeclareTemplateInstance": explanation in a moment).

\DeclareTemplateInstance { sectioning } { chapter } { chapter }
  { <keys> }
\DeclareTemplateInstance { sectioning } { section } { section }
  { <keys> }
\DeclareTemplateInstance { sectioning } { section } { subsection }
  { <keys> }
\DeclareTemplateInstance { sectioning } { section } { subsubsection }
  { <keys> }

Which are then used in document functions:

\DeclareDocumentCommand \chapter { s o m } {
  % Other things to include
  \UseTemplateInstance { sectioning } { chapter }
}
\DeclareDocumentCommand \section { s o m } {
  % Other things to include
  \UseTemplateInstance { sectioning } { section }
}
\DeclareDocumentCommand \subsection { s o m } {
  % Other things to include
  \UseTemplateInstance { sectioning } { subsection }
}
\DeclareDocumentCommand \subsubsection { s o m } {
  % Other things to include
  \UseTemplateInstance { sectioning } { subsubsection }
}

The idea here is that the "chapter" template might do very different
things to the "section" one. It would also be possible to swap out the
template to do something more complex, for example:

\DeclareTemplateInstance { sectioning } { fancy-chapter } { chapter }
  { <keys> }
\DeclareTemplateInstance { sectioning } { extra-special } { section }
  { <keys> }
\DeclareTemplateInstance { sectioning } { section } { subsection }
  { <keys> }
\DeclareTemplateInstance { sectioning } { invisible } { subsubsection }
  { <keys> }

without altering the document command part of the code.

Have I got all of that about right? If I have, I'll take a look again at
my template-alt code and revise it as appropriate.

My reasoning for \DeclareTemplateInstance rather than just
\DeclareInstance is that I'd feel more comfortable if the functions all
formed a set, and we avoid any possible clashes anywhere.  If everything
includes the word "Template" it is pretty clear what the functions are
about.
-- 
Joseph Wright