summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/FAQ-en/html/FAQ-verbwithin.html
blob: e53d6391b0f89259a65e15b0045ddd6a31221d80 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
<head>
<title>UK TeX FAQ -- question label verbwithin</title>
</head><body>
<h3>Why doesn&#8217;t verbatim work within &#8230;?</h3>
<p/>The LaTeX verbatim commands work by changing category codes.  Knuth
says of this sort of thing &#8220;Some care is needed to get the timing
right&#8230;&#8221;, since once the category code has been assigned to a
character, it doesn&#8217;t change.  So <code>\</code><code>verb</code> and
<code>\</code><code>begin{verbatim}</code> have to assume that they are getting the
first look at the parameter text; if they aren&#8217;t, TeX has already
assigned category codes so that the verbatim command doesn&#8217;t have a
chance.  For example:
<blockquote>
<pre>
\verb+\error+
</pre>
</blockquote><p>
will work (typesetting &#8216;<code>\</code><code>error</code>&#8217;), but
<blockquote>
<pre>
\newcommand{\unbrace}[1]{#1}
\unbrace{\verb+\error+}
</pre>
</blockquote><p>
will not (it will attempt to execute <code>\</code><code>error</code>).  Other errors one
may encounter are &#8216;<code>\</code><code>verb</code> ended by end of line&#8217;, or even the
rather more helpful &#8216;<code>\</code><code>verb</code> illegal in command argument&#8217;.  The
same sorts of thing happen with <code>\</code><code>begin{verbatim}</code> &#8230;
<code>\</code><code>end{verbatim}</code>:
<blockquote>
<pre>
\ifthenelse{\boolean{foo}}{%
\begin{verbatim}
foobar
\end{verbatim}
}{%
\begin{verbatim}
barfoo
\end{verbatim}
}
</pre>
</blockquote><p>
provokes errors like &#8216;File ended while scanning use of
<code>\</code><code>@xverbatim</code>&#8217;, as <code>\</code><code>begin{verbatim}</code> fails to see its
matching <code>\</code><code>end{verbatim}</code>.
<p/>This is why the LaTeX book insists that verbatim
commands must not appear in the argument of any other command; they
aren&#8217;t just fragile, they&#8217;re quite unusable in any &#8220;normal&#8221; command
parameter, 
regardless of <a href="FAQ-protect.html"><code>\</code><code>protect</code>ion</a>.  (The <code>\</code><code>verb</code>
command tries hard to detect if you&#8217;re misusing it; unfortunately, it
can&#8217;t always do so, and the error message is therefore not a reliable
indication of problems.)
<p/>The first question to ask yourself is: &#8220;is <code>\</code><code>verb</code> actually
necessary?&#8221;.
<ul>
<li> If <code>\</code><code>texttt{<em>your text</em>}</code> produces the same result
  as <code>\</code><code>verb</code><code>+<em>your text</em>+</code>, then there&#8217;s no need of
  <code>\</code><code>verb</code> in the first place.
<li> If you&#8217;re using <code>\</code><code>verb</code> to typeset a URL or email
  address or the like, then the <code>\</code><code>url</code> command from the
  <i>url</i> will help: it doesn&#8217;t suffer from all the problems of
  <code>\</code><code>verb</code>, though it&#8217;s still not robust; 
  &#8220;<a href="FAQ-setURL.html">typesetting URLs</a>&#8221; offers advice here.
<li> If you&#8217;re putting <code>\</code><code>verb</code> into the argument of a boxing
  command (such as <code>\</code><code>fbox</code>), consider using the <code>lrbox</code>
  environmen)t:
<blockquote>
<pre>
\newsavebox{\mybox}
...
\begin{lrbox}{\mybox}
  \verb!VerbatimStuff!
\end{lrbox}
\fbox{\usebox{\mybox}}
</pre>
</blockquote><p>
</ul>
<p/>If you can&#8217;t avoid verbatim, the <code>\</code><code>cprotect</code> command (from the
package <i>cprotect</i>) might help.  The package manages to make a
macro read a verbatim argument in a &#8220;sanitised&#8221; way by the simple
medium of prefixing the macro with <code>\</code><code>cprotect</code>:
<blockquote>
<pre>
\cprotect\section{Using \verb|verbatim|}
</pre>
</blockquote><p>
The package (at the time this author tested it) was still under
development (though it <em>does</em> work in this simple case) and
deserves consideration in most cases; the package documentation gives
more details.
<p/>Other than the <i>cprotect</i> package, there are three partial
solutions to the problem:
<ul>
<li> Some packages have macros which are designed to be responsive
  to verbatim text in their arguments.  For example,
  the <i>fancyvrb</i> package defines a command
  <code>\</code><code>VerbatimFootnotes</code>, which redefines the <code>\</code><code>footnotetext</code>
  command, and hence also the behaviour of the <code>\</code><code>footnote</code>)
  command, in such a way that you can include <code>\</code><code>verb</code> commands in
  its argument.  This approach could in principle be extended to the
  arguments of other commands, but it can clash with other packages:
  for example, <code>\</code><code>VerbatimFootnotes</code> interacts poorly with the
  <code>para</code> option of the <i>footmisc</i> package.
<p/>  The <i>memoir</i> class defines its <code>\</code><code>footnote</code> command so that
  it will accept verbatim in its arguments, without any supporting package.
<li> The <i>fancyvrb</i> package defines a command <code>\</code><code>SaveVerb</code>,
  with a corresponding <code>\</code><code>UseVerb</code> command, that allow you to save
  and then to reuse the content of its argument; for details of this
  extremely powerful facility, see the package documentation.
<p/>  Rather simpler is the <i>verbdef</i> package, whose <code>\</code><code>verbdef</code>
  command defines a (robust) command which expands to the verbatim
  argument given.
<li> If you have a single character that is giving trouble (in
  its absence you could simply use <code>\</code><code>texttt</code>), consider using
  <code>\</code><code>string</code>.  <code>\</code><code>texttt{my<code>\</code><code>string</code>_name}</code>
  typesets the same as 
  <code>\verb+my_name+</code>, and will work in the argument of a command.  It
  won&#8217;t, however, work in a moving argument, and no amount of
  <a href="FAQ-protect.html"><code>\</code><code>protect</code>ion</a> will make it work in
  such a case.
<p/>  A robust alternative is:
  <blockquote>
<pre>
\chardef\us=`\_
...
\section{... \texttt{my\us name}}
</pre>
  </blockquote><p>
  Such a definition is &#8216;naturally&#8217; robust; the construction
  &#8220;&lt;<i>back-tick</i>&gt;<code>\</code><code>&lt;<i>char</code></i>&gt;&#8221; may be used for any
  troublesome character (though it&#8217;s plainly not necessary for things
  like percent signs for which (La)TeX already provides
  robust macros).
</ul>
<dl>
<dt><tt><i>cprotect.sty</i></tt><dd><a href="http://mirror.ctan.org/macros/latex/contrib/cprotect.zip">macros/latex/contrib/cprotect</a> (or <a href="http://mirror.ctan.org/macros/latex/contrib/cprotect/">browse the directory</a>); <a href="http://mirror.ctan.org/help/Catalogue/entries/cprotect.html">catalogue entry</a>
<dt><tt><i>fancyvrb.sty</i></tt><dd><a href="http://mirror.ctan.org/macros/latex/contrib/fancyvrb.zip">macros/latex/contrib/fancyvrb</a> (or <a href="http://mirror.ctan.org/macros/latex/contrib/fancyvrb/">browse the directory</a>); <a href="http://mirror.ctan.org/help/Catalogue/entries/fancyvrb.html">catalogue entry</a>
<dt><tt><i>memoir.cls</i></tt><dd><a href="http://mirror.ctan.org/macros/latex/contrib/memoir.zip">macros/latex/contrib/memoir</a> (or <a href="http://mirror.ctan.org/macros/latex/contrib/memoir/">browse the directory</a>); <a href="http://mirror.ctan.org/help/Catalogue/entries/memoir.html">catalogue entry</a>
<dt><tt><i>url.sty</i></tt><dd><a href="http://mirror.ctan.org/macros/latex/contrib/url.zip">macros/latex/contrib/url</a> (or <a href="http://mirror.ctan.org/macros/latex/contrib/url/">browse the directory</a>); <a href="http://mirror.ctan.org/help/Catalogue/entries/url.html">catalogue entry</a>
<dt><tt><i>verbdef.sty</i></tt><dd><a href="http://mirror.ctan.org/macros/latex/contrib/verbdef.zip">macros/latex/contrib/verbdef</a> (or <a href="http://mirror.ctan.org/macros/latex/contrib/verbdef/">browse the directory</a>); <a href="http://mirror.ctan.org/help/Catalogue/entries/verbdef.html">catalogue entry</a>
</dl>
<p/><p>This question on the Web: <a href="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=verbwithin">http://www.tex.ac.uk/cgi-bin/texfaq2html?label=verbwithin</a>
</body>