On 29/08/2011 17:43, Ulrike Fischer wrote: > 1. The first three paragraphs of l3tl: "token list variable" versus > "arbitrary token list". "list of items" versus "list of tokens" I've altered these paragraphs: take a look at the SVN to see the new version. > 2. Packages l3prop, l3keys, l3keyval: What is their relation? Well, Will merged l3keys and l3keyval a couple of days ago, so these are now 'one'. Broadly, processing of key-value lists is about input, with \lkeyval... functions providing a low-level parser and \keys... functions for a higher-level interface to a general set of keyval tools. On the other hand, property lists are a way to store data in a structured form. Thus property lists are intended for use inside code, not as a way to turn input into something else. I've added a note to this effect to the prop module. > 3. l3seq. What is an sequence compared to a token list? Ultimately, you could implement your own ordered list system using token lists. This is about making life easy for the programmer, and also semantics (Token lists are unstructured, and so you loose any sense of what is in them, where there is more information in the data.) > 4. The introduction makes a difference between "functions" and > "variables" but doesn't say which package(s) deal with the one and > which with the other type. It would also help if there were a rule > of thump when a command without argument should be better defined as > a function and when as variable. I'm not quite clear what you mean here. We have a list of data types, and these then need functions to create, modify and use them. For example, the variable type 'prop' is handled in the 'prop' module. On the 'rule of thumb', I assume you mean when to use \cs_set_noar:Npn \module_stuff: { ... } and when to use \tl_set:Nn \l_module_tl { ... } That's a bit awkward, as there is no technical difference. I tend to use token lists for use input, and functions for anything I define. However, this one is not that easy. > 5. In the clist package I was quite bewildered because they didn't > seem to be a command to actually *fill* a list. At the end I found > that I can add more than one item with > \clist_put_left:Nn. I assume you were looking for \clist_set:Nn \l_my_clist { ... } and did something like \clist_put_right:Nn \l_my_clist { a , b } This rather misses the point of a structured data type: you are supposed to deal with each item separately (with a loss of performance, regrettably). \clist_put_right:Nn \l_my_clist { a } \clist_put_right:Nn \l_my_clist { b } Now, comma lists are a bit odd as they are really an input form which is somewhat supported as a stored data type. There has been some discussion within the team about this, as in general the seq data type is more robust. We certainly need to be handle 'explicit' comma lists \foo:n { a , b , c } but the situation with 'stored' ones is less clear. (I'm still not sure about the entire stored-comma lists business. I wonder if we should insist on conversion to sequences.) -- Joseph Wright