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