# TikZ programming/macros, \list construct

TikZ 3.0 manual, on page 83, we have (not complete code):

    \list{--}{\topsep=2pt\itemsep=0pt\parsep=0pt
\parskip=0pt\labelwidth=8pt\leftmargin=8pt
\itemindent=0pt\labelsep=2pt}
#5
\endlist


Question:

1. The ability to pass input to commands (the #5 goes into the -- of the list) like this is some TikZ property or we already have it in plain TeX?
2. What other commands allow me to pass inputs like this?

The \list above does not seem to be LaTeX because there is no \begin{list} and \end{list} also the definition above compiles fine in TeX using input tikz.tex

Sorry if this is too basic, I'm trying to learn more about the "magic" but I don't know much about plain TeX (just ordered the TeX book).

• \list needs LaTeX – egreg May 7 '14 at 22:24
• @greg thanks! btw is there documentation for \list? in TikZ manual I found it only on examples. – Sergio Parreiras May 7 '14 at 22:29
• you might like Definitive guide to trivlists for some details about lists – cmhughes May 7 '14 at 22:38
• @egreg I'm not sure the \list is LaTeX because there is no \begin{list} and \end{list} also the definition above compiles fine in TeX using input tikz.tex – Sergio Parreiras May 8 '14 at 8:19
• @SergioParreiras \list is defined in LaTeX but not plain: try \show\list to see this. – Joseph Wright May 8 '14 at 8:27

## First question: is \list LaTeX?

First, if a command is LaTeX or not usually means: is it defined in the LaTeX format or not? In the case of \list yes, it is defined in LaTeX, it is not a primitive of TeX nor defined in plainTeX.

Second, you may wonder if this is LaTeX since it is not following the \begin{list}-\end{list} style. I am calling this style because \begin and \end are themselves commands defined in LaTeX, not primitives, so there's nothing preventing you to redefine them, use their definition directly or hiding them in other macros. Specifically,

\begin{something}{arg}
content
\end{something}


this is basically expanded to

\something{arg}content\endsomething


So the code in your question is LaTeX because it uses macros defined in the LaTeX format, not just TeX. It does not follow the LaTeX style but it is equivalent to it. You often find this equivalent version when there are complications with the parsing involved (such as finding \endsomething to understand when the environment ends).

## Second question: kev-val arguments

I am guessing that when you write "pass inputs like this" you mean "pass arguments in the key-val style".

So let's see the difference between normal and key-val style.

When you write

\newcommand{\bla}[2]{Hi #1, #2 #2 bla}


to use \bla properly you have to specify one mandatory argument in curly braces (this has again something to do with LaTeX conventions) like this:

\bla{Manu}{bye}  % produces Hi Manu, bye bye bla


Let's call this style "positional arguments". This is quite simple but when your macro takes a lot of arguments, maybe not all mandatory, it becomes quite cumbersome to 1) write the macro 2) remember which argument is which. An example of this can be found in the \cventry command of moderncv.

Since TikZ allows you to customize every aspect of every graphical item, if it were to use the standard interface with positional arguments it would be incredibly difficult to remember which argument means what, which is optional and which is not etc. Instead, and this is one of the strengths of TikZ, they defined a package called pfgkeys that allows you to parse a string of key-val arguments and do something with it. By key-val arguments I mean this

color=red, draw, right=1 of a


Now note how you use these kind of arguments:

\tikz[color=red, draw, right=1 of a] {...}


This suggests that the \tikz command has an optional argument and a mandatory one, ideally:

\newcommand{\tikz}[2][]{
% #1 contains an optional list of key-val args
% #2 contains some other stuff describing graphics
}


So you see, the key-val arguments are still packed into a single positional argument. What \tikz does internally is pass that argument to a "parse key-val" macro that is capable of breaking the key-val list into its items and act on it accordingly to how the keys are defined (somwhere else).

I recommend reading the "Key management" section of the PGF manual, the pgfkeys package is very powerful.

### Back to \list

Now, you may have noticed that you example is a bit different from the key-val code I wrote above: my keys do not start with \. And this is the main difference! What the \list macro does internally ideally works like this:

\newenvironment{list}[2]{
% do some fancy stuff
\begingroup  % limit the scope of modifications to this env
#2 % just execute whatever is in arg 2
\def\labelitemi{#1}  % set the label of items to be arg 1
% other fancy stuff to start the list
}{
\endgroup
% code to end the list
}


This is not what really happens but it is good for illustration. Note that arg 1 is necessary only to enable you inserting code between the fancy stuff \list is doing and not just before or after all of it. Specifically the example code binds #1 to

\topsep=2pt\itemsep=0pt\parsep=0pt
\parskip=0pt\labelwidth=8pt\leftmargin=8pt
\itemindent=0pt\labelsep=2pt


which may look like a key-val list but is not! This list does not need to be parsed in order to make sense, it is just a chunk of code that can be executed as is. The various assignments are basically equivalent to the LaTeX \setlength{\topsep}{2pt}. So with lengths you can use the assignment syntax that is readable and looks a lot like a key-val interface, but it is a peculiarity of lengths (and little else).

### What other packages use the key-val interface?

There are many, and I wish there were more! There are few packages that are written specifically to parse (interpret) lists of key-val arguments with facilities to define keys and their effect. The ones I am aware of are

1. keyval
2. xkeyval
3. pgfkeys
4. LaTeX3 packages offer similar facilities

The most powerful and readable of all is in my opinion pgfkeys, the one used internally by PGF/TikZ.

But the only part of LaTeX itself where something vaguely similar to the key-val interface is present is documentclass arguments; using the key-val interface is an independent choice of each package and you have to read the documentation of each to understand what is the interface for arguments they went for (or look in their source-code for the key-val packages I mentioned!).

• I'm not suppose to thank here but this is a great answer. Thanks for the step-by-step explanations! – Sergio Parreiras May 8 '14 at 13:25
• @SergioParreiras No worries, this is not Stackoverflow. We are still human and enjoy social constructs. Thank you for your rebellious(!) thanks ;) – percusse Mar 9 '15 at 19:41