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
so what do we have so far?
template:
above-skip =L [0pt] \caption_above_skip ,
number-format =f2 [#1~#2:~] \caption_number_format:nn ,
nonumber-format =f1 [#1:~] \caption_nonumber_format:n ,
template-alt:
above-skip .set:N = \l_caption_above_skip ,
nonumber-format .function:N = \caption_nonumber_format:nn ,
single-line-format .function:N = \caption_single_line_format:n ,
above-skip .initial:n = 0pt ,
number-format .initial:n = {#1~#2:~} ,
nonumber-format .initial:n = {#1:~} ,
template-Lars:
\Variable {above-skip} {\l_caption_above_skip}
\Function {number-format} {2}{\caption_number_format:nn}
\Function {nonumber-format} {2}{\caption_nonumber_format:nn}
functionally-wise that is all identical, except that Lars was not given a
syntax for specifying defaults in his mail. So what are the differences and
how should they be judged?
template pro:
- each key is immediately identified in terms of what it is allowed to hold
(al length or an integer or a functions with two arg ...)
- it is immediately clear what the key defaults to if it is absent
template con:
- the key identification carries implementation information that is
not relevant for the above (ie to understand what key can receive) but
only important for those that are concerned with the implementation, eg
wether or not a length is a real length or a pseudo one hold in a macro
...
- defaults are tied to setting up a template thus changing defaults prior to
generating instances is not easily possible
- specifying certain types of keys or specify delayed execution doesn't have
a got syntax
------------------------------
template-alt pro:
- same syntax as the proposed l3keys
- 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
- if defaults are needed then the key definitions become fairly unreadable
through length of declaration
------------------------------
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
missing:
- handing of default values, but that could be added as an additional arg
(like template) or as a separate declaration (as in
--------------------------------
there are probably other approaches that we haven't come to yet but assuming
that is all we have right now ...
... what is the best syntax for what kind of user here? and what is the user
that we need to target here?
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
spec)
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. 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.
----------------------------
having written such a long mail on what i think the user will be and what
he/she might need ... what is the opinion of others on these two questions?
cheers
frank
|
