Welcome to the UK List of
TeX Frequently Asked Questions
on the Web

Searching

The index of Frequently Asked Questions about TeX is searchable.

Please enter your keyword here:   then press here: ,    or:
Google

Why doesn’t verbatim work within …?

The LaTeX verbatim commands work by changing category codes. Knuth says of this sort of thing “Some care is needed to get the timing right…”, since once the category code has been assigned to a character, it doesn’t change. So \verb and \begin{verbatim} have to assume that they are getting the first look at the parameter text; if they aren’t, TeX has already assigned category codes so that the verbatim command doesn’t have a chance. For example:

\verb+\error+

will work (typesetting ‘\error’), but if we define no more than a no-op macro,

\newcommand{\unbrace}[1]{#1}

which simply regurgitates its argument, and use it as:

\unbrace{\verb+\error+}

the combinartion will not (it will attempt to execute \error). Other errors one may encounter are ‘\verb ended by end of line’, or even the rather more helpful ‘\verb illegal in command argument’. The same sorts of thing happen with \begin{verbatim}\end{verbatim}:

\ifthenelse{\boolean{foo}}{%
\begin{verbatim}
foobar
\end{verbatim}
}{%
\begin{verbatim}
barfoo
\end{verbatim}
}

provokes errors like ‘File ended while scanning use of \@xverbatim’, as \begin{verbatim} fails to see its matching \end{verbatim}.

This is why the LaTeX book insists that verbatim commands must not appear in the argument of any other command; they aren’t just fragile, they’re quite unusable in any “normal” command parameter, regardless of \protection. (The \verb command tries hard to detect if you’re misusing it; unfortunately, it can’t always do so, and the error message is therefore not reliable as an indication of problems.)

The first question to ask yourself is: “is \verb actually necessary?”.

If you can’t avoid verbatim, the \cprotect command (from the package cprotect) might help. The package manages to make a macro read a verbatim argument in a “sanitised” way by the simple medium of prefixing the macro with \cprotect:

\cprotect\section{Using \verb|verbatim|}

The package does work in this simple case, and deserves consideration in many others cases; the package documentation gives more details.

Another way out is to use one of “argument types” of the \NewDocumentCommand command in the experimental LaTeX3 package xparse:

\NewDocumentCommand\cmd{ m v m }{#1 `#2' #3}
\cmd{Command }|\furble|{ isn't defined}

Which gives us:

Command \furble isn’t defined

The “m” tag argument specifies a normal mandatory argument, and the “v” specifies one of these verbatim arguments. As you see, it’s implanting a \verb-style command argument in the argument sequence of an otherwise “normal” sort of command; that ‘|’ may be any old character that doesn’t conflict with the content of the argument.

This is pretty neat (even if the verbatim is in an argument of its own) but the downside is that xparse pulls in the experimental LaTeX3 programming environment (l3kernel) which is pretty big.

Other than the cprotect package, there are four partial solutions to the problem:

cprotect.sty
macros/latex/contrib/cprotect (or browse the directory); catalogue entry
fancyvrb.sty
macros/latex/contrib/fancyvrb (or browse the directory); catalogue entry
l3kernel bundle
macros/latex/contrib/l3kernel (or browse the directory); catalogue entry
memoir.cls
macros/latex/contrib/memoir (or browse the directory); catalogue entry
newverbs.sty
macros/latex/contrib/newverbs (or browse the directory); catalogue entry
tcolorbox.sty
macros/latex/contrib/tcolorbox (or browse the directory); catalogue entry
url.sty
macros/latex/contrib/url (or browse the directory); catalogue entry
verbatim.sty
macros/latex/required/tools (or browse the directory); catalogue entry
verbatimbox.sty
macros/latex/contrib/verbatimbox (or browse the directory); catalogue entry
verbdef.sty
macros/latex/contrib/verbdef (or browse the directory); catalogue entry
xparse.sty
Distributed as part of macros/latex/contrib/l3packages (or browse the directory); catalogue entry

This answer last edited: 2013-10-21


Go to previous question, or next question

Go to FAQ home.

URL for this question: http://www.tex.ac.uk/cgi-bin/texfaq2html?label=verbwithin

Comments, suggestions, or error reports? - see “how to improve the FAQ”.

This is FAQ version 3.28, released on 2014-06-10.