Newcommand: What cannot be done?

Question

It is not the first time I tried to create a new command unsuccessfully. Some things I found out did not work (getting "undefined control sequence" or other errors).

• Use a quote-endquote argument.

  \newcommand{\mytest}[1]{
    \quote #1 \endquote
  }
  

• Use the \verb command with the argument

  \newcommand{\mytest}[1]{
    \verb+#1+
  }
  

• Use the begin{lstlisting} environment:

  \newcommand{\mytest}[1]{
    \begin{lstlisting}
    #1
    \end{lstlisting}
  }
  

Do you know where I can find an exhaustive list of what I can do with \newcommand and what I cannot? and even better, why?

Answer 1

It's quite difficult to say what you can do with a \newcommand, because the possibilities are (really) infinite.

I can talk about your two examples, pointing out the errors you're making.

In the first definition you use \quote and \endquote and this is a mistake; \quote is the command LaTeX performs when it finds \begin{quote}, but this happens after a group is opened as a side effect of \begin. The group is normally closed by \end when LaTeX finds \end{quote} thus automatically undoing the settings of the parameters performed by \quote.

With your definition, after \mytest{something} you'll find that the line width is permanently changed and the left indentation will go on forever. Instead, it is safe to say

\newenvironment{myenv}{\quote}{\endquote}

because the grouping will be provided by \begin{myenv} and \end{myenv}.

What's the main feature of \newcommand? Let's look at a simple example:

\newcommand{\foo}[1]{?#1!}

Now, if you type \foo{xyz}, it is exactly the same as typing

?xyz!

because when TeX scans \foo it knows that it has to find an argument (the first token after \foo if it's not { or the entire token list up to the matching }) and to replace \foo<argument> with the replacement text specified in the \newcommand instruction, where <argument> is denoted by #1.

You can have up to nine arguments (even none at all). All it's done is this “replacement”. With suitable definitions, together with conditional structures, you can even define recursive macros, but this would be too long to describe. The largest part of “user's definitions” are just simple (or mildly complex) replacements for marking up logical units.

TeX doesn't scan what comes after a command until it has to. So, when doing \foo, it won't go past the argument and expand no macro inside the argument until the macro replacement ends. So after

\foo{\baz{x}}

TeX will see

?\baz{x}!

after which it will first process ? and then \baz{x} as if those had been in the input from the beginning but with a small difference that shows up in your second example.

The difference in typing \foo{\baz{x}} and ?\baz{x}! is that TeX will already have tokenized \baz{x}.

The \verb command works by changing the meaning of all special characters. It does so by delaying until possible the absorption of the text to be typeset verbatim and this will happen in a group; so

\verb+\baz{x}+

will do the following steps

1. Open a group (by supplying {)
2. Start typesetting in the monospaced font
3. Change the meaning of all special characters to “printable”
4. Define + to behave as } (the group closing token)
5. Go on typesetting whatever you find
6. The trailing + will undo all special settings

The description is not complete, but sufficient for our purposes; there are other technical details that are irrelevant for understanding the whole picture.

What happens when you define

\newcommand{\foo}[1]{\verb+#1+}

as you propose? When TeX sees \foo{\baz{x}} it know it has to scan for an argument and tokenizes it. Therefore the argument is four tokens (I separate them by •)

\baz • { • x • }

and no change in the meaning of \, { and } can be performed any more. Even worse, the + that should change its meaning to become the group closing token can't be modified, because it has already been tokenized at definition time. Therefore LaTeX has a protection mechanism that disallows \verb to be in the argument to a command, because any sort of evil could happen if you use it in such a place: changing the meaning of special characters without having the possibility of undoing the setting would put you in a corner without any escape.

Are there workarounds? Yes, see How to put \verb command inside of \textbf{} block?, but first of all ask yourself if you really need verbatim in the argument to a command to begin with.