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?
> 
> as i see it right now we aren't arguing functionality but rather presentation
> (well with some exceptions on the side-discussions). there is nothing wrong
> with that in fact, I think it is good to do that and I would like to thank
> Joseph to enable that discussion by trying and succeeding to implement a first
> alternative to the original interface. so in that sense I think it is not
> template vs template-alt but simply: get to an interface for templates that is
> best serving the purpose

Indeed. My aim with template-alt was simply to examine how things work.
As you say, at a functionality level there should be no difference
(although I know not everything currently works in template-alt!).

> template-alt pro:
> 
>  - same syntax as the proposed l3keys

Well, we may yet need to revise some things in l3keys in light of the
discussion here. So lets not worry too much about the similarity at the
moment!

>  - setting up defaults is separated from setting up keys (allowing to separate
>    that even furthers)
> 
>  - certain key types have a very natural syntax (like multiple choices)
> 
> template-alt cons:
> 
>  - the key settings more or less completely hide the nature of the key, eg
>    .functions:N means a function is expected (in contrast to a variable of
>    some kind) but it is not clear what kind of function is needed or what kind
>    of variable is expected

On the .set:N idea, this could soon be dropped to go back to .int_set:N,
.tl_set:N, and so on. I can see the advantages of both methods!

>  - if defaults are needed then the key definitions become fairly unreadable
>    through length of declaration

With the current implementation, I'd agree if every item needs a
default. However, you can imagine different approaches which avoid this.

> template-Lars:
> 
> I would claim that it is more like template, except that it is given in a
> syntax that is easier to write a parser for as it can essentially direcly
> executed. So
> 
> pros:
> 
>  - easy to parse/execute
>  - clear expectation what different keys are receiving
> 
> cons
> 
>  - I think it is less easy to read compared to template (guess that is the
>    expense for simpler parsing) but then I simply might be more used to the
>    latter

I'd agree here: I like the general idea of using a keyval method. But
perhaps like you it's because I'm used to it.

> 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. And that is what:
> 
> 
>         above-skip         =L           [0pt] \caption_above_skip ,
>         number-format      =f2      [#1~#2:~] \caption_number_format:nn   ,
> 
> offers. the right hand side is not helping here and actually even distracting
> but to take it out and specify it elsewhere would have made the declaration
> for the programmer cumbersome (or so I thought back then). Perhaps that is
> wrong and perhaps a  better approach would be something like this:
> 
>         above-skip         =L           [0pt] {Skip above the caption} ,
>         number-format      =f2      [#1~#2:~] {format of number and caption
>                                                label},
> 
> and a second section in the template declaration that maps external to
> internal separately:
> 
>         above-skip         = \caption_above_skip ,
>         number-format      = \caption_number_format:nn   ,
> 
> Not sure, I still think the original solution strikes a fair balance between
> the two somewhat conflicting goals.

The reason I've gone for "properties" in template-alt is that I find the
longer descriptions more helpful than single letters. We could perhaps
imagine taking a somewhat hybrid approach:

  above-skip    .skip_set:N    = [0pt]     \caption_above_skip,
  number-format .func_2_args:N = [#1~#2:~] \caption_number_format:nn,

I'm not so sure about the default values in the current form. For a
start, I'm not a fan of \DelayEvaluation as a concept. Using
.initial:n/N/V seems to get round needing it in most circumstances.
However, if it is best to include the default in the same line as the
key itself then I guess this approach is necessary. Could we have a
shorter name?

More importantly, the xparse discussion seemed to conclude that optional
arguments should only be used at "layer -1", not design level. So
perhaps something like

  above-skip    .skip_set:Nn    = \caption_above_skip       {0pt}    ,
  number-format .func_2_args:Nn = \caption_number_format:nn {#1~#2:~},

(or the same concept with either the template or template-Lars
interface) would be better.

I think the last example above is quite readable, and lays things out
nicely for the designer:

"above-skip is a skip-setting key which stores it's value in
\caption_above_skip and will have value 0 pt is not otherwise specified."

(BTW, I wonder if it might be better to drop the arg-spec part of the
properties and go with something like

  above-skip    .skip-set    = \caption_above_skip       {0pt}    ,
  number-format .func-2-args = \caption_number_format:nn {#1~#2:~},

The only problem is then the current .code:x idea, but perhaps just
.code and .code-x would work.)
-- 
Joseph Wright