Token list vs control sequence in LaTeX3

Question

In LaTeX3, should I use a token list or a (none argument) control sequence?

For example, I need to use a macro for some format like \itshape, so which one is better?

\tl_new:N  \l__mydoc_format_tl
\tl_set:Nn \l__mydoc_format_tl { \itshape }

or

\cs_new:Nn \__mydoc_format: { \itshape }

Answer 1

There is no big difference in what you get from the two examples: both \l__mydoc_format_tl and \__mydoc_format: become TeX macros that expand to \itshape. From

\documentclass{article}
\usepackage{expl3}

\ExplSyntaxOn

\tl_new:N  \l__mydoc_format_tl
\tl_set:Nn \l__mydoc_format_tl { \itshape }
\cs_new:Nn \__mydoc_format: { \itshape }

\show\l__mydoc_format_tl
\show\__mydoc_format:

where I purposely use \show in order not to add any possible doubt, I get

> \l__mydoc_format_tl=macro:
->\itshape .
l.10 \show\l__mydoc_format_tl

? 
> \__mydoc_format:=\long macro:
->\itshape .
l.11 \show\__mydoc_format:

If we used \cs_new_nopar:Nn, the two macros would be \ifx-equivalent.

The difference is more conceptual than technical. A token list variable such as \l__mydoc_format_tl is a container, whereas a function such as \__mydoc_format: is meant to “do something”. A similar distinction is present in almost all programming languages, but is blurred in classical (La)TeX programming, due to the fact that, apart from registers, TeX only has macros.

The LaTeX3 team, since inception of the project, felt that a distinction should be made, in order to make programs more readable.

How do you choose between the two types? It depend on what's the use of the new object.

A token list variable is meant as a container of tokens that we plan to deliver at some point or we need for comparison with other token lists. You can map through a token list, which is (conceptually) meaningless with a function. A function does something, a variable is used by functions.

However, there is a technical difference between the two. If you change the assignments above into

\tl_set:Nn \l__mydoc_format_tl { ## }
\cs_new:Nn \__mydoc_format: { ## }

you'll see

> \l__mydoc_format_tl=macro:
->####.
l.10 \show\l__mydoc_format_tl

? 
> \__mydoc_format:=\long macro:
->##.
l.11 \show\__mydoc_format:

so the token list variable contains two # tokens (that \show prints doubled), whereas the function expands to a single # token.

By the way, if you intend to have a function that acts doing a particular font selection, it should be “protected”:

\cs_new_protected:Nn \__mydoc_format: { \itshape }

because the action this function does is not “expandable”, so we won't run the risk that the function is untimely expanded in some contexts (such as a write operation).