LATEX-L Archives

Mailing list for the LaTeX3 project


Options: Use Forum View

Use Monospaced Font
Show Text Part by Default
Show All Mail Headers

Message: [<< First] [< Prev] [Next >] [Last >>]
Topic: [<< First] [< Prev] [Next >] [Last >>]
Author: [<< First] [< Prev] [Next >] [Last >>]

Print Reply
Frank Mittelbach <[log in to unmask]>
Reply To:
Mailing list for the LaTeX3 project <[log in to unmask]>
Wed, 2 Sep 2009 23:34:58 +0200
text/plain (206 lines)

 > In everything below, I'm especially trying to ignore the syntax of the  
 > template definitions entirely; 

good start :-)

 > Before I start with that, an answer to Frank's question:
 > > 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?
 > I think we should assume
 > (a) anyone looking at a template definition should be able to  
 > interpret it, no matter the syntax and how well documented the  
 > templates are
 > (b) nonetheless, the syntax should be made as simple as possible for  
 > the majority of keytypes for the sanity of those reading and writing  
 > the things
 > But perhaps these don't exactly answer the questions you had in mind :)

no it is not answering my question and you know it :-)

and I fact I don't quite agree with you here, at least not all the way. 

I know that with 2e classes anybody trying to change things would have needed
a fair understanding of LaTeX's inner working to pull it off. Still, if you
look at the questions people ask, many users who have never seen a TeX book
(whatever flavor) or done any TeX programming or looked at the kernel attempt
to do design changes by looking for clues that indicate to them where the
places for change really are.

With a template approach, I think (and hope) that this is getting far simpler
and even casual users would get enabled to do this kind of design mods, and
that changes the picture somewhat in my opinion. I.e., I think that it is
important that the template spec (not the implementation, ie the body) should
be easy to interpret for people who have no clue (or not much) about expl3.

 > * * *
 > Regarding whether to put template defaults inline or in a separate  
 > definition entirely, I think I've been persuaded that we should offer  
 > both. After all, some defaults really do belong to be tied to their  
 > definition, such as for a fallback font. (Whereas for, say, a template  
 > for a pagestyle that need many design parameters it makes less sense  
 > to have default/initial values.)
 > That is, we should offer something that looks like template's
 >         above-skip         =L           [0pt]  
 > \l_caption_above_skip        ,
 >         number-format      =f2      [#1~#2:~]  
 > \caption_number_format:nn    ,
 > as well as providing a function such as
 >    \DeclareTemplateDefaults{type}{template}{
 >      above-skip = 0pt          ,
 >      number-format = {#1~#2:~} ,
 >    }

I would probably vote for calling this declaration something like


i.e. think of it as "changing" the template default (with the notion that if a
template doesn't give a default for something, changing here means setting it
for the first time). Not really important but a slight twist in the view

Otherwise I agree I think both should be provided

 > * * *
 > The other point of contention is automagic detection for key types. I  
 > know Lars doesn't like this sort of thing, but I think it aids  
 > usability significantly since you don't need to remember letters at  
 > all. 

I think I side with Lars ... I don't like it.

 > I would prefer to write
 >         above-skip    .set:Nn = \l_caption_above_skip     {0pt}    ,
 >         number-format .set:Nn = \caption_number_format:nn {#1~#2:~},

and even less this one (partly because the :Nn gives to me (with the head  of
a programmer) a strong visual clue that is unimportant in the context and thus
wrong, ie all assignment will be essentially :Nn but the importances that the
first expects a length value and the second a function with 2 args is hidden
in the obscurity of the righthand name

 > It would be a shame to be able to write  \cs_set:Nn \foo:nnnn  
 > { #1..#4 }  in code and not have the same freedom with template  
 > definitions!

sorry don't get this argument

 > On this point, Frank wrote:
 > > - 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
 > I don't understand this, sorry. If I write '=f2' then I don't know  
 > what kind of function is needed (unless you mean the number of  
 > arguments? Which follows from the function name...), and if I write  
 > '.set:Nn \l_caption_above_skip' then it's clear that we're setting a  
 > length in both cases I don't follow your criticism. (But  
 > I'm probably misunderstanding your point.)

well you are thinking layer 2/3 ie you are thinking as a programmer, a person
that is concerned with writing expl3 code. But I want this interface (or the
spec part of it) equally readable for layer 1 people, ie people that look at
it from a design perspective, ie those who do not necessarily consider expl3 a
lingua franca and in fact don't need to (see top part of the message)

for such a person (imho) seeing that a key "above" expects a length gives
him/her a clue what to put in the instance decl or that a key "number-format"
expects a function with two arguments. Those are the important points for
him/her at layer 1 and that is why I want them to stand out and not to be
deduced from conventions in the language used at layer 3

the other point I like to make is that contratry to all good intentions people
slip up when coding fast "and just to check something out ..." so the right
hand side might as well be something like \tmpa (I've been guilty on that
account myself) and then my stay so forever

of course the key name might be equally bad but that is less likely to
happen. but again the above is a good example: from "number-format" I wouldn't
necessarily guess that this key is actually not formatting a number but rather
formatting a number plus a label, so seeing this key to require 2 args
signals, "wait, what is this doing"

 > I think a good compromise is to implement both schemes, so that all  
 > the existing explicit variable- and function-setting keytypes would  
 > remain for those people who like to use them or who don't use the  
 > expl3 naming scheme. That is, these would be equivalent:

don't like the compromise. I seriously thin this will do more harm then good,
as people need to learn two conventions rather than one and that without any
real benefit

that's quite different from the topic of defaults where the use of external
defaults serve a different purpose (namely being able to change the defaults
after setting up some instances to set up later instances in a different way)
So if that also ends up allowing two different ways to initialize the first
set of defaults for the templates that doesn't hurt (it is just a side effect). 
 >    Aside: The other reason I like implicit .set:Nn is for
 >      "extra variable/data types". If Joseph were to invent an
 >      expnum datatype that allowed input like '3e-4' for siunitx
 >      then (and we allowed this sort of thing) template
 >      definitions would be able to use the corresponding
 >      \expnum_set:Nn function without adding any extra code
 >      (or letters to remember) to template itself.
 >      (For this to work, each datatype would have to declare
 >      itself in a property list with a name and functions for
 >      using it. Not sure if it's just a crazy idea or something
 >      useful, at this stage of the day.)

a good point, how good I have to ponder over a glas of wine :-)

 > 1. Only explicit keytypes (no automagic) like template is now
 > 2. Only implicit keytypes like template-alt is now
 > 3. Both of the above
 > I'd like to propose option #3 not because I like "automagic" but  
 > because I believe it will help to simplify the interface, while still  
 > providing "plain" keytypes for those cases where the disambiguation is  
 > necessary.

and I don't like it when putting on layer 1 head. There I prefer option 1
at this time of the day

 > * * *
 > These are only two points, but I hope we can decide on them before  
 > moving onto the next troublesome parts. As I said, I'm trying to  
 > ignore the interface at this stage so I don't care if the default is  
 > optional or not or before the variable or after it; similarly, all I  
 > care about with the different keytypes is that we need a bunch of them  
 > for different variables and other things, not what they're called or  
 > what they look like.
 > So the big question is: can we agree on the two points raised above,  
 > first? :)

I would perhaps postpone that second question as I don't think it isn't really
relevant for "moving onto the next troublesome parts" whatever they are :-) -
it is presentational syntactic sugar, in contrast to the default stuff which
is a functionality change