Frank Mittelbach wrote:
> perhaps it is time to step back and ask ourselves for whom the interface is
> intended and how is group of people is best served?
> Let's start with the user: in my terminology we are at layer 2, so people
> writing templates would be people who get (conceptually at leat) instructions
> from a designer as in "I need a template for headings with the following
> typographical features and the following things that can vary ... in real life
> of course the designer might not know how to express his/her need in technical
> terms so the person would need several attempts to get to the final template
> So from that perspective a formalism focussing on the implementation side (as
> in template-alt) would be fine. After all a designer who wants to use the
> temple to produce a document class (ie work on layer 1) or modify one would
> not bother with that level but look at the template documentation that has all
> the details he/she needs.
> well ... truth is that we will find that this documentation often not exist,
> don't we know that all? so those people would end up looking at the templates
> directly when writing their instances and even if they may not look very deep
> into the implementation of the template they take use the spec to build the
> instances. And that's why I thought that this spec should be directly helpful
> to the task and if possible should easily convey the template possibilities.
> that needs two things: good key names, which you can't enforce but only hope
> for, and an easy way to grasp the nature of the key and probably the default
> it will produce if not set.
I've been thinking about this some more. The broad thrust of the
argument above is that when using templates (with \DeclareInstance, for
example) the only details about the template that should be needed by
the "designer" is what type of argument and default each key takes. This
can be achieved by documentation, but the thinking is that in reality
many people will simply look at the template declaration to find this
information (whether the documentation is good or not). So the aim of
the current template implementation is to enable someone to read the
template definition and extract information on how to use it without
needing to worry about the implementation.
While LaTeX3 is supposed to be more structured and better documented
than LaTeX2e, I think Frank is probably right that many people will find
it convenient to look at the template declaration to pick up how to use
it. If we accept that, then the current template definition interface
makes a lot of sense. (I would stand by the idea of avoiding
single-letter descriptions of keys under this regime: something like
"\function 2" or "\length" looks clearer to me than "f2" or "l".)