What does \do do?

Question

I saw some code using \do and I would like to understand it, which to me means finding out what exactly \do does. However, I haven't been able to find it in any sort of reference manual, and it is, quite obviously, ungoogleable. I suspect it's part of basic TeX, but I'm not sure.

What does \do do and when would I use it? Where can I find it in the TeX or LaTeX documentation?

Answer 1

\do is short for \performsomeactiononanargument and is typically redefined depending on the action that needs to be performed.

For example, consider the verbatim environment (or \verb). We know that the verbatim environment allows you to use certain characters that are otherwise restrictive in their use or application, like $, \, ~, &, %, ... So, in order to set up the environment to treat these characters as characters and not their aforementioned special behaviour, \@verbatim does (see latex.ltx)

\let\do\@makeother \dospecials

where

\def\@makeother#1{\catcode`#112\relax}
\def\dospecials{\do\ \do\\\do\{\do\}\do\$\do\&%
  \do\#\do\^\do\_\do\%\do\~}

Therefore, \dospecials performs a bunch of category code changes (\do's). It's just a condensed notation that varies depending on the definition of \do. It's used in other contexts as well for a similar outcome.

etoolbox adopted this usage/notation for "performing some action on an argument" when processing a list of items. For example, when calling

\docsvlist{first,second,third,last}

\do is applied to each of the elements sequentially, as in \do{first}, \do{second}, \do{third} and \do{last}. This allows the user to (re)define what the meaning of \do is exactly. Here's an example:

\documentclass{article}

\usepackage{etoolbox}

\begin{document}

\begin{enumerate}
  \renewcommand{\do}{\item}
  \docsvlist{first,second,third,last}
\end{enumerate}

\noindent
\begingroup
\renewcommand{\do}[1]{\textbullet~#1 \quad}
\docsvlist{first,second,third,last}
\endgroup

\end{document}

---

In a very limited context, \do is sometimes used to delimit macro arguments. But in that context it makes literal sense, even though a completely different delimiter could have been used. One example of this is used in \@whilenum or as part of \@for (loop) constructions.

Answer 2

It depends on the definition

After

 \def\do{hello}

then \do will expand to hello....

In the core latex format it has two unrelated uses.

It is used in "executable lists" in a style derived from plain TeX and described in the TeXBook.

For example verbatim internally uses a list defined via

\def\dospecials{\do\ \do\\\do\{\do\}\do\$\do\&%
  \do\#\do\^\do\_\do\%\do\~}

If \dospecials list had been defined as

\def\dospecials{,\ ,\\,\{,\},\$,\&%
  ,\#,\^,\_,\%,\~}

or

\def\dospecials{\ \\\{\}\$\&%
  \#\^\_\%\~}

you would need some loop macro to iterate over the list but by having a command separator, all you need to do is define \do locally and then execute the list so `verbatim does

  \let\do\@makeother
  \dospecials

and \@makeother is applied to each of the tokens.

The other use is as a delimited argument. If you had needed a looping macro you could have used the form

\@tfor\tmp:=\dospecials\do{\expandafter\@makeother\tmp}

for the form with no commas, or

\@for\tmp:=\dospecials\do{\expandafter\@makeother\tmp}

for the form with commas.

here := and \do are not actually defined to do anything they are just tokens used to delimit the arguments of \@for which is defined via

\long\def\@for#1:=#2\do#3{%
    ....

so the list variable (#1) is everything up to := and the list (#2) is (after expansion) everything between := and \do, with the list body (#3) being the next token or brace group after \do.

Answer 3

Place holder macro for lists

\do is often used as "place holder" macro in lists. Example is \dospecials, which is defined in the LaTeX kernel:

\def\dospecials{\do\ \do\\\do\{\do\}\do\$\do\&%
  \do\#\do\^\do\_\do\%\do\~}

Here it takes an argument, a letter macro. But the meaning of \do does not matter at this time. Then, at the start of the verbatim environment, the following can be seen in the code:

\let\do\@makeother \dospecials

The \do becomes a meaning: change the category code of the argument to category other (the category for reading verbatim stuff). The list is then executed with this meaning of \do as \@makeother.

Other examples of the LaTeX kernel are:

• \def\verbatim@nolig@list{\do\`\do\<\do\>\do\,\do\'\do\-} and the usage: \def\@noligs{\let\do\do@noligs \verbatim@nolig@list}

• The preamble commands are stored in such a list and deactivated at \begin{document}.

Body macro for loops

Another usage is in loops: \@whilenum, \@whiledim, \@whilesw, \@for, \@tfor. The \@while... macros are followed by some condition and the loop body is available as argument of \do:

\@whilenum\value{section}<10 \do{Something, \stepcounter{section}}

Depending on the evaluation of the condition macro \do is redefined to either process the argument or ignore it to end the loop.