summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/FAQ-en/html/FAQ-linmacnames.html
blob: cb3a073af25e470c983b9a41b9bf5cba5dc868ce (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
145
146
147
148
<head>
<title>UK TeX FAQ -- question label linmacnames</title>
</head><body>
<h3>Non-letters in macro names</h3>
<p/>New LaTeX users are often suprised that macro definitions
containing non-letters, such as
<blockquote>
<pre>
\newcommand{\cul8r}{Goodbye!}
</pre>
</blockquote><p>
fail to compile.  The reason is that the TeX macro language, unlike
most programming languages, allows 
<a href="FAQ-whatmacros.html">nothing but letters in macro names</a>.
<p/>There are a number of techniques for defining a macro with a name like
<code>\</code><code>cul8r</code>.  Unfortunately, none of the techniques is particularly
good:
<ol>
<li> Use <code>\</code><code>csname</code>\dots<code>\</code><code>endcsname</code> to define and invoke the
  macro:
  <blockquote>

<pre>
\expandafter\newcommand\csname cul8r\endcsname{Goodbye!}
I said, ``\csname cul8r\endcsname''.
</pre>
  </blockquote><p>
  <dl>
  <dt>Pro:<dd> No unexpected side effects
  <dt>Con:<dd> So verbose as to be unusable
  </dl>
<li> Define a &ldquo;special-command generator&rdquo;, and  use the resulting
  commands:
<blockquote>

<pre>
\newcommand{\DefineRemark}[2]{%
  \expandafter\newcommand\csname rmk-#1\endcsname{#2}%
}
\newcommand{\Remark}[1]{\csname rmk-#1\endcsname}
...
\DefineRemark{cul8r}{Goodbye!}
...
\Remark{cul8r}
</pre>
</blockquote><p>
  <dl>
  <dt>Pro:<dd> Straightforward to use, not too untidy
  <dt>Con:<dd> It&rsquo;s hardly doing what we set out to do (experts will
    see that you are defining a macro, but others likely won&rsquo;t)
  </dl>
<li> Convince TeX that &ldquo;<code>8</code>&rdquo; is a letter:
  <blockquote>
<pre>
\catcode`8 = 11 
\newcommand{\cul8r}{Goodbye!}
I said, ``\cul8r''.
</pre>
  </blockquote><p>
  <dl>
  <dt>Pro:<dd> <code>\</code><code>cul8r</code> can be used directly
  <dt>Con:<dd> Likely to break other uses of &ldquo;<code>8</code>&rdquo; (such as
    numbers or dimensions; so
    <code>\</code><code>setlength{<code>\</code><code>paperwidth</code>}{8in}</code> tells us:
    <blockquote>
<pre>
! Missing number, treated as zero.
&lt;to be read again&gt; 
                   8
</pre>
    </blockquote><p>
  </dl>
  As a general rule, changing category codes is something to use
  <em>in extremis</em>, after detailed examination of options.  It is
  conceivable that such drastic action could be useful for you, but
  most ordinary users are well advised not even to try such a
  technique.
<li> Define a macro <code>\</code><code>cul</code> which must always be followed by
  &ldquo;<code>8r</code>&rdquo;:
  <blockquote>
<pre>
\def\cul8r{Goodbye!}
I said, ``\cul8r''.
</pre>
  </blockquote><p>
  <dl>
  <dt>Pro:<dd> <code>\</code><code>cul8r</code> can be used directly
  <dt>Con #1:<dd> Breaks if <code>\</code><code>cul</code> is followed by anything other
    than &ldquo;<code>8r</code>&rdquo;, with a confusing diagnostic &mdash;
    <code>\</code><code>cul99</code> produces:
    <blockquote>
<pre>
! Use of \cul doesn't match its definition.
&lt;*&gt; \cul9
         9
</pre>

    </blockquote><p>
    (which would confuse someone who hadn&rsquo;t even realised there
    <em>was</em> a definition of <code>\</code><code>cul</code> in the document).
  <dt>Con #2:<dd> Silently redefines existing <code>\</code><code>cul</code>, if any;
    as a result, the technique cannot be used to define both a
    <code>\</code><code>cul8r</code> and, say, a <code>\</code><code>cul123</code> macro in the same
    document.
  </dl>
</ol>
Technique 3 is in fact commonly used &mdash; in a limited form &mdash; within
most LaTeX packages and within LaTeX itself.  The convention is to
use &ldquo;<code>@</code>&rdquo; within the names of internal macros to hide them
from the user and thereby prevent naming conflicts.  To this end,
LaTeX automatically treats &ldquo;<code>@</code>&rdquo; as a letter while
processing classes and packages and as a non-letter while processing
the user&rsquo;s document.  The key to this technique is the separation:
internally a non-letter is used for macro names, and the user doesn&rsquo;t
see anything of it, while the status remains &ldquo;frozen&rdquo; in all the
definitions created within the class or package.  See 
<a href="FAQ-atsigns.html"><code>\</code><code>@</code> and <code>@</code> in macro names</a> for
more information.
<p/>Note that analogous use of technique 3 in this example would give us
<blockquote>
<pre>
\begingroup
  \catcode`8 = 11 
  \gdef\cul8r{Goodbye!}
  \gdef\later{\cul8r}
\endgroup
I said, ``\later''.
</pre>
</blockquote><p>
which works, but rather defeats the object of the exercise.
(<code>\</code><code>later</code> has the &ldquo;frozen&rdquo; catcode for &lsquo;8&rsquo;, even though the value
has reverted to normal by the time it&rsquo;s used; note, also, the use of
the primitive command <code>\</code><code>gdef</code>, since <code>\</code><code>newcommand</code> can&rsquo;t make a
macro that&rsquo;s available outside the group.)
<p/><em>Recommendation</em>: Either choose another mechanism (such as
<code>\</code><code>DefineRemark</code> above), or choose another name for your macro, one
that contains only ordinary letters.  A common approach is to use
roman numerals in place of arabic ones:
<blockquote>
<pre>
\newcommand{\culVIIIr}{Goodbye!}
</pre>
</blockquote><p>
which rather spoils the intent of the joke implicit in the example
<code>\</code><code>cul8r</code>!
<p><em>This answer was added: 2009-06-03</em></p>
<p/><p>This question on the Web: <a href="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=linmacnames">http://www.tex.ac.uk/cgi-bin/texfaq2html?label=linmacnames</a>
</body>