summaryrefslogtreecommitdiff
path: root/Master/texmf-doc/doc/english/FAQ-en/html/FAQ-protect.html
blob: dd0389f9118a2263aab889337b079b4be971290d (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
<head>
<title>UK TeX FAQ -- question label protect</title>
</head><body>
<h3>What&rsquo;s the reason for &lsquo;protection&rsquo;?</h3>
<p/>Sometimes LaTeX saves data it will reread later. These data are
often the argument of some command; they are the so-called moving
arguments.  (&lsquo;Moving&rsquo; because data are moved around.)  Candidates
are all arguments that may go into table of contents, list of figures,
<em>etc</em>.; namely, data that are written to an auxiliary file and
read in later.  Other places are those data that might appear in head-
or footlines.  Section headings and figure captions are the most
prominent examples; there&rsquo;s a complete list in Lamport&rsquo;s book
(see <a href="FAQ-books.html">TeX-related books</a>).
<p/>What&rsquo;s going on really, behind the scenes? The commands in moving
arguments are normally expanded to their internal structure during the
process of saving. Sometimes this expansion results in invalid TeX
code, which shows either during expansion or when the code is
processed again. Protecting a command, using
&ldquo;<code>\</code><code>protect</code><code>\</code><code>cmd</code>&rdquo; tells LaTeX to save <code>\</code><code>cmd</code> as
<code>\</code><code>cmd</code>, without expanding it at all.
<p/>So, what is a &lsquo;fragile command&rsquo;? &mdash; it&rsquo;s a command that expands into
illegal TeX code during the save process.
<p/>What is a &lsquo;robust command&rsquo;? &mdash; it&rsquo;s a command that expands into legal
TeX code during the save process.
<p/>Lamport&rsquo;s book says in its description of every LaTeX command whether
it is &lsquo;robust&rsquo; or &lsquo;fragile&rsquo;; it also says that every command with an
optional argument is fragile.  The list isn&rsquo;t reliable, and neither
is the assertion about optional arguments; the statements may have
been true in early versions of LaTeX2e but are not any longer
necessarily so:
<ul>
<li> Some fragile commands, such as <code>\</code><code>cite</code>, have been made robust
  in later revisions of LaTeX.
<li> Some commands, such as <code>\</code><code>end</code> and <code>\</code><code>nocite</code>, are fragile
  even though they have no optional arguments.
<li> The &ldquo;user&rsquo;s way&rdquo; of creating a command with an optional
  argument (using <code>\</code><code>newcommand</code> or <code>\</code><code>newcommand*</code>) now always
  creates a robust command (though macros without optional arguments
  may still be fragile if they do things that are themselves fragile).
<li> There is no reason that a package author should not also make
  robust commands with optional arguments as part of the package.
<li> Some robust commands are redefined by certain packages to be
  fragile (the <code>\</code><code>cite</code> command commonly suffers this treatment).
</ul>
Further, simply &ldquo;hiding&rdquo; a fragile command in another command, has
no effect on fragility.  So, if <code>\</code><code>fred</code> is fragile, and you write:
<blockquote>
<pre>
\newcommand{\jim}{\fred}
</pre>
</blockquote><p>
then <code>\</code><code>jim</code> is fragile too.  There is, however, the
<code>\</code><code>newcommand</code>-replacement <code>\</code><code>DeclareRobustCommand</code>, which
<em>always</em> creates a robust command (whether or not it has optional
arguments).  The syntax of <code>\</code><code>DeclareRobustCommand</code> is substantially
identical to that of <code>\</code><code>newcommand</code>, and if you do the wrapping
trick above as:
<blockquote>
<pre>
\DeclareRobustCommand{\jim}{\fred}
</pre>
</blockquote><p>
then <code>\</code><code>jim</code> is robust.
<p/>Finally, we have the <i>makerobust</i> package, which  defines
<code>\</code><code>MakeRobustCommand</code> to convert a command to be robust.  With the
package, the &ldquo;wrapping&rdquo; above can simply be replaced by:
<blockquote>
<pre>
\MakeRobustCommand\fred
</pre>
</blockquote><p>
Whereafter, <code>\</code><code>fred</code> is robust.  Using the package may be reasonable
if you have lots of fragile commands that you need to use in moving
arguments.
<p/>In short, the situation is confusing.  No-one believes this is
satisfactory; the LaTeX team have removed the need for
protection of some things, but the techniques available in 
current LaTeX mean that this is an expensive exercise.  It remains
a long-term aim of the team to remove all need for <code>\</code><code>protect</code>ion.
<dl>
<dt><tt><i>makerobust.sty</i></tt><dd>Distributed with Heiko Oberdiek&rsquo;s packages
  <a href="ftp://cam.ctan.org/tex-archive/macros/latex/contrib/oberdiek.zip">macros/latex/contrib/oberdiek</a> (<a href="ftp://cam.ctan.org/tex-archive/macros/latex/contrib/oberdiek.tar.gz">gzipped tar</a>, <a href="http://www.tex.ac.uk/tex-archive/macros/latex/contrib/oberdiek/">browse</a>)
</dl>
<p/><p>This question on the Web: <a href="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=protect">http://www.tex.ac.uk/cgi-bin/texfaq2html?label=protect</a>
</body>