Joseph,

 > I'd say "template class" is clearer than "template type" (you could also
 > consider "set", but I'm not so sure about that). 

I'm fine with that for now though I'm not thinking that it get much better
this way, my feeling is that one should probably get rid of "Template" in the
name as the semantics of that thing is broader than templates really. But lets
leave the command naming aside for now

 > So, following my
 > division-of-the-document example, the base layer could be
 > 
 > \DeclareTemplateClass { sectioning } 3 % Assuming 3 args.

yep, except (or in addition) with the declaration that should be a
documentation of the semantics defined by the templatetype/class. Of course,
we don't have a way to verify it being obeyed other than by human, but it is
an integral part of the definition. (might well be another argument that
receives text - at the moment it is just documentation that provides this
essential part).

 > 
 > 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> }

well, I'm not to keen on the wording you use here; templates types/classes are
independent of document classes, and therefore templates essentially
too. Starting from that observation I would typically not use names like
"chapter" or "section" but rather something more conveying the idea of what
range of layouts this template can produce. But as they are just names we are
fine for now (I think fncyhead package in 2e (if you think of it as a kind of
template idea) comes up with template names named after their originators, so
anything is possible.


 > (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.)

yes it could but I'm personally not too keen on this kind of indirection but
that again is a totally separate discussion and should worry us now.

 > 
 > 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> }

ok, except that this is a classic case better for choosing different names as
I said earlier: I mean there is nothing really wrong with calling a template
that defines a range of chapter layouts "chapter" but in my opinion that name
is better reserved for the instance in a document class while using some more
layout specific names for the templates .
 > 
 > 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.

yes, that's roughly the idea, except that I don't think the changed command names made
things better, see below.

 > 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.

\DeclareTemplateInstance is fine enough since that is precisely what the
function does, taking a template of a certain type/class and instantiating it.

However, conceptually speaking

\UseTemplateInstance        and  \DeclareTemplateClass/Type

are both wrong, because in case of an instance as in 


 \DeclareDocumentCommand \chapter { s o m } {
     \UseTemplateInstance { sectioning } { chapter }
  }

we don't actually care whether or not that came from a template through
instantiation, do we? If worst come to worst one could write the "chapter"
instance by hand without any template involved: all that is required is that
by the end of the day calling 

     \UseXXX { sectioning } { chapter }

results in picking up a defined number of argument (three in our example)
processing them according to the semantic description behind "sectioning"

For that reason both commands aren't really tied to templates even though in
practical terms in most cases realization is done via templates and
instantiation of templates


Having said all this I would propose that you stick with the old names (and
order of arguments) for now, rather than "improving" names as we go along as
that is likely to make things worse and make it much more difficult to test
out different implementations.

It needs an holistic view to see what works best and while I agree that naming
argument orders etc can and should be improved, I don't think we are ready for
this.

frank