LATEX-L Archives

Mailing list for the LaTeX3 project

LATEX-L@LISTSERV.UNI-HEIDELBERG.DE

Options: Use Classic View

Use Monospaced Font
Show Text Part by Default
Condense Mail Headers

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

Print Reply
Mime-Version: 1.0 (Apple Message framework v935.3)
Content-Type: text/plain; charset=US-ASCII; format=flowed; delsp=yes
Date: Wed, 2 Sep 2009 19:12:51 +0930
Reply-To: Mailing list for the LaTeX3 project <[log in to unmask]>
From: Will Robertson <[log in to unmask]>
In-Reply-To: <[log in to unmask]>
Content-Transfer-Encoding: 7bit
Sender: Mailing list for the LaTeX3 project <[log in to unmask]>
Parts/Attachments: text/plain (173 lines)
Hello all,

Thanks for the good summary of the discussion around template, Frank.  
I think you've touched on all of the important points regarding the  
interface differences.

I'm writing this slightly in parallel with digesting Joseph's  
responses; I think we've seen enough examples and thought about it all  
enough that we might be able to pencil in a proposal or two for what's  
going on. I'm not trying to address every point that's been raised so  
far since I'm starting to get lost in all the words. Not to say that  
I'm ignoring the other points, but trying to focus on two main points  
that I think we can agree on first of all.

In everything below, I'm especially trying to ignore the syntax of the  
template definitions entirely; I think the two points I raise below  
are fairly independent to whether we use letters or tokens or whatever  
to define the template keytypes.

* * *

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 :)

* * *

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:~} ,
   }

Template authors may then use one or the other as appropriate for the  
application, and users of layer 1 can use the function to help create  
their instances.

PROPOSAL: Whatever the interface itself, both ways of setting defaults  
should be offered. (And whether it's optional or not, per Joseph's  
recent post, is still up for debate.)

* * *

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

        above-skip         =L           [0pt]  
\l_caption_above_skip       ,
        number-format      =f2      [#1~#2:~]  
\caption_number_format:nn   ,

I would prefer to write (the '=*' is arbitrary)

        above-skip         =*          [0pt]  
\l_caption_above_skip       ,
        number-format      =*      [#1~#2:~]  
\caption_number_format:nn   ,

and rather than

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

I would prefer to write

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

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!

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 register...so in both cases I don't follow your criticism. (But  
I'm probably misunderstanding your point.)

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:

        above-skip    .set:Nn = \l_caption_above_skip     {0pt}    ,
        above-skip    .skip_set:Nn = \l_caption_above_skip      
{0pt}    ,

or
        above-skip         =L           [0pt]  
\l_caption_above_skip        ,
        above-skip         =*           [0pt]  
\l_caption_above_skip        ,

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

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

* * *

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? :)

Thanks for all of your time,
Will

ATOM RSS1 RSS2