summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/FAQ-en/html/FAQ-verbwithin.html
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/FAQ-en/html/FAQ-verbwithin.html')
-rw-r--r--Master/texmf-dist/doc/generic/FAQ-en/html/FAQ-verbwithin.html129
1 files changed, 129 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/FAQ-en/html/FAQ-verbwithin.html b/Master/texmf-dist/doc/generic/FAQ-en/html/FAQ-verbwithin.html
new file mode 100644
index 00000000000..f6379c0d327
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/FAQ-en/html/FAQ-verbwithin.html
@@ -0,0 +1,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>