summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/FAQ-en/html/FAQ-verbwithin.html
blob: f6379c0d327bc16386311879ceb140d344a9d54a (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
<head>
<title>UK TeX FAQ -- question label verbwithin</title>
</head><body>
<h3>Why doesn&rsquo;t verbatim work within ...?</h3>
<p/>The LaTeX verbatim commands work by changing category codes.  Knuth
says of this sort of thing &ldquo;Some care is needed to get the timing
right...&rdquo;, since once the category code has been assigned to a
character, it doesn&rsquo;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&rsquo;t, TeX has already
assigned category codes so that the verbatim command doesn&rsquo;t have a
chance.  For example:
<blockquote>
<pre>
\verb+\error+
</pre>
</blockquote><p>
will work (typesetting &lsquo;<code>\</code><code>error</code>&rsquo;), 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 &lsquo;<code>\</code><code>verb</code> ended by end of line&rsquo;, or even the
rather more helpful &lsquo;<code>\</code><code>verb</code> illegal in command argument&rsquo;.  The
same sorts of thing happen with <code>\</code><code>begin{verbatim}</code> ...
<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 &lsquo;File ended while scanning use of
<code>\</code><code>@xverbatim</code>&rsquo;, 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&rsquo;t just fragile, they&rsquo;re quite unusable in any 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&rsquo;re misusing it; unfortunately, it
can&rsquo;t always do so, and the error message is therefore not a reliable
indication of problems.)
<p/>The first question to ask yourself is: &ldquo;is <code>\</code><code>verb</code> actually
necessary?&rdquo;.
<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&rsquo;s no need of
  <code>\</code><code>verb</code> in the first place.
<li> If you&rsquo;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&rsquo;t suffer from all the problems of
  <code>\</code><code>verb</code>, though it&rsquo;s still not robust; 
  &rdquo;<a href="FAQ-setURL.html">typesetting URLs</a>&rdquo; offers advice here.
<li> If you&rsquo;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>
  environment:
<blockquote>
<pre>
\newsavebox{\mybox}
...
\begin{lrbox}{\mybox}
  \verb!VerbatimStuff!
\end{lrbox}
\fbox{\usebox{\mybox}}
</pre>
</blockquote><p>
</ul>
<p/>Otherwise, 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> (and
  hence the <code>\</code><code>footnote</code>) commands 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 to 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, which 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&rsquo;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 &lsquo;naturally&rsquo; robust; the construction
  &ldquo;&lt;<i>back-tick</i>&gt;<code>\</code><code>&lt;<i>char</code></i>&gt;&rdquo; may be used for any
  troublesome character (though it&rsquo;s plainly not necessary for things
  like percent signs for which (La)TeX already provides
  robust macros).
</ul>
Documentation of both <i>url</i> and <i>verbdef</i> is in the
package files.
<dl>
<dt><tt><i>fancyvrb.sty</i></tt><dd><a href="ftp://cam.ctan.org/tex-archive/macros/latex/contrib/fancyvrb.zip">macros/latex/contrib/fancyvrb</a> (<a href="ftp://cam.ctan.org/tex-archive/macros/latex/contrib/fancyvrb.tar.gz">gzipped tar</a>, <a href="http://www.tex.ac.uk/tex-archive/macros/latex/contrib/fancyvrb/">browse</a>)
<dt><tt><i>memoir.cls</i></tt><dd><a href="ftp://cam.ctan.org/tex-archive/macros/latex/contrib/memoir.zip">macros/latex/contrib/memoir</a> (<a href="ftp://cam.ctan.org/tex-archive/macros/latex/contrib/memoir.tar.gz">gzipped tar</a>, <a href="http://www.tex.ac.uk/tex-archive/macros/latex/contrib/memoir/">browse</a>)
<dt><tt><i>url.sty</i></tt><dd><a href="ftp://cam.ctan.org/tex-archive/macros/latex/contrib/misc/url.sty">macros/latex/contrib/misc/url.sty</a>
<dt><tt><i>verbdef.sty</i></tt><dd><a href="ftp://cam.ctan.org/tex-archive/macros/latex/contrib/misc/verbdef.sty">macros/latex/contrib/misc/verbdef.sty</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>