How should I create complex objects using xtemplate?

Consider the following trivial example:

\documentclass{article}
\usepackage{xtemplate}

\ExplSyntaxOn
\DeclareObjectType { test } { 10 }
\ExplSyntaxOff

\begin{document}
oh, nose!
\end{document}

ERROR: xtemplate error: "bad-number-of-arguments"

--- TeX said ---
!
! Bad number of arguments for object type 'test'.
!
! See the xtemplate documentation for further information.
!
! For immediate help type H <return>.
!...............................................

l.8 \DeclareObjectType { test } { 10 }

--- HELP ---
From the .log file...

|'''''''''''''''''''''''''''''''''''''''''''''''
| This is a coding error.
|
| An object may accept between 0 and 9 arguments.
| You asked to use 10 arguments: this is not supported.
|...............................................


As we know, TeX only formally supports macros that take up to 9 arguments:

\def\TooLong#1#2#3#4#5#6#7#8#9{haha!}


When necessary in the past, we've gotten around this by daisy-chaining these:

\def\macro{\@macro@a}
\def\@macro@a#1#2#3#4#5#6#7#8{(something with 8 arguments)\@macro@b}
\def\@macro@b#1#2#3#4#5#6#7#8{(something with 8 more arguments)}


The use of \macro would now necessarily eat 16 tokens from the input stream.

Obviously, having so many arguments has been superseded in the 'modern era' by the use of key-value arguments:

% ... \usepackage{expl3} ... \ExplSyntaxOn ...
\keys_define:nn { test } {
option-1 .tl_set:N = \l_test_key_a_tl,
option-2 .tl_set:N = \l_test_key_b_tl,
option-3 .tl_set:N = \l_test_key_c_tl,
% ...
}


Even though a command using this key-value interface would only consume one token—the group containing the user's key-value settings—the logical understanding is that test takes some n arguments—potentially all of them required (option-n .value_required:).

This logical understanding that an object has n user-definable attributes is something that is valued across the design layers. The document designer isn't going to care that TeX can only take 9 arguments because of some in-borne (and mostly arbitrary) restriction on macro definitions. In reality it won't matter: these arguments will be absorbed via a saner and more maintainable key-value system.

How should the responsible role convey the idea that some object has more than 9 qualities?

If desired, I may bring the general question up on LaTeX-L, but a suggestion of what to do 'for now' will be appreciated as an accepted answer. :)

Example Use Case

I am building a modular (and thus extensible) resume/cv solution, and I'd like to model it after the fantastic exsheets package. To do so, I need to use the templating idea.

Consider an employment record object. I'll note, per the discussion, that not all of these elements are required.

1. Job Title
2. Company
3. Company Title
5. Field
6. Level of Technicality
7. Start date
8. End date
9. Related Technologies
10. etc.

Forgive me for not being able to conjure up more than nine 'real' elements, but I hope I'm getting the idea across. Note that the document designer is the one who decides which arguments are mandatory and which are not; this selection should not be limited (a discussion for LaTeX-L).

I want to take this opportunity that the pure idea of a mandatory argument---just considering the words, here---doesn't imply that it's a positional argument. That would get awful. But that is certainly a discussion rather than a proper question. I'll prepare a proper question / proposal for LaTeX-L when I don't need to do so on company time, though :)

• Can you come up with an example where some document object would actually have more than nine mandatory arguments? The question of various optional things is tricky, of course. – Joseph Wright Aug 14 '14 at 5:56
• Also, the number here is ultimately related to the idea of grabbing TeX arguments: it you did allow say 16 values you are saying that an instance of the object has to be followed by 16 args with position-based meaning. The whole area is quite tricky: when Frank asked last about sectioning commands, what was 'absolutely required' was very hard to pin down! – Joseph Wright Aug 14 '14 at 6:05
• I have a feeling this is likely to have a discussion element: clearly that should go to a more appropriate place (LaTeX-L). – Joseph Wright Aug 14 '14 at 12:44
• Maybe it is out of my understanding but consider that you cannot create a full expandable macro which handles with more than 9 arguments, for example \def\macro#1...#12{#12+#11+#10+#9+...#1} where all 12 arguments are ready for programmer on one place of the code. You need to save the arguments to toks or macros, thus the macro cannot be full expandable. – wipet Aug 14 '14 at 13:21

There are a few things to bear in mind here. First, the template idea is very much experimental: in particular, what's needed are good examples of 'real life' objects and how they are used in different situations. As such, there may need to be adjustments. Secondly, the idea here is to separate design-time decisions from use-time input. The arguments to an object/template are 'dynamic' ones at the point of use. Finally, we are writing TeX-based code here, so there may be the odd place where decisions reflect the underlying system. (Ideally those cases will be limited and not limiting).

Taking the usual example of sectioning commands, it's clear that there is one mandatory argument: the name of the section-like object. However, there are also lots of other potential arguments. Ones that have been suggested include

• TOC short version
• Section number
• Switch for presence in TOC
• Switch for numbering
• Label for cross-referencing

plus others I don't remember at the moment! What's notable in that list is that none of them are absolutely required in all cases for some form of sectioning concept: it's only the name of the section that is vital. We can see that both in LaTeX2e syntax

\section*[Name]{Full Name} % Just the full name absolutely required


and in HTML

<h1>Full name</h1>


That suggests that a template for section probably shouldn't require one argument for each of the potential options I've suggested

\UseInstance{sectioning}{latex2e}{<full-name>}{<TOC name>}{<header name>}...


looks awkward even if then wrapped up using xparse into the same user interface as LaTeX2e provides.

What this type of thing suggests is that objects are likely to require at least one 'multi-part' argument to deal with the various run-time stuff that may or may not be given. It's at least not unreasonable to argue that a it might be sensible to go purely keyval, as you suggest, and have one 'run time args' to cover everything, with the mandatory nature of some of them handled in a different way. (I suspect you'd also want to at least consider a 'one-off design changes' arg, as this is not uncommon as a requirement.)

\UseInstance{sectioning}{latex2e}
{
full-name = <text> ,
TOC-name  = ...
}


There's of course the intermediate position of having one or more 'really mandatory' args plus one 'other stuff' one: something of a hybrid but perhaps for users easier than a 'purist' all keyval situation.

What I think is true is that it's unlikely that most 'real world' object types will require more than nine arguments. If you think about most LaTeX stuff, the nine arg limit very rarely shows up for users (it does occasional pop up when writing low-level parsing and the like, but that's somewhat different).

Coming back to the point about the code being experimental, there are clearly open questions. I can only describe how the code works at the present and what the things it's trying to explore are. Over time, various LaTeX3 concepts have been changed or dropped when it's been clear they don't work properly 'in the wild'. The template code and interfaces are not really 'world tested': it's quite possible that changes are needed. (I've tried to emphasise above that I can see an argument here for taking a different tack: one for LaTeX-L.)

• The last time the team looked at this seriously it was clear that there are still open questions: how to deal with the fact that at point-of-use there are various things you might want to give but which look optional was one of these. (The list of 'potentially useful' items can get pretty big.) – Joseph Wright Aug 14 '14 at 7:39
• I can provide a use case, but I'd like to know how one would normally provide the 'optional' arguments here. When it gets right down to it, I'd also be hard-pressed to find an object where more than nine arguments were absolutely necessary. Still, I think the separation between the logic of the document and the shallow limitations of TeX are murky, here. – Sean Allred Aug 14 '14 at 12:39
• @SeanAllred As I say, my worry with a long list of mandatory args, quite apart from any technical issue, is that with any list longer than about 4 or 5 getting them right becomes very difficult. At that point, it seems to make more sense to use a keyval approach (named args) even if they are all required. – Joseph Wright Aug 14 '14 at 12:41
• @SeanAllred An argument for 'various optional settings' at the moment would simply be another argument, so we might have \DeclareObjectType{sectioning}{2} where one arg is the name and the other is 'all the other stuff'. As I say, this area is still I think one that requires discussion: as I've tried to indicate in my answer, there is an argument that it might be clearer to go down the 'named-args only' route at the design level. – Joseph Wright Aug 14 '14 at 12:43
• But then we come back to the core question. For now, I will necessarily just provide a 1 for the number of qualities the object has, but that is lying to the designer for the sake of TeX. I'm wondering if this isn't the best medium to discuss all this, though. I can definitely see how the whole idea has become quite a headache :) – Sean Allred Aug 14 '14 at 12:44