path: root/Master/texmf-dist/doc/generic/FAQ-en/faq-mac-prog.tex

% $Id: faq-mac-prog.tex,v 1.25 2011/09/09 19:35:14 rf10 Exp rf10 $

\section{Macro programming}

\subsection{``Generic'' macros and techniques}

\Question[Q-linmacnames]{Non-letters in macro names}

New \LaTeX{} users are often suprised that macro definitions
containing non-letters, such as
\begin{quote}
\begin{verbatim}
\newcommand{\cul8r}{Goodbye!}
\end{verbatim}
\end{quote}
fail to compile.  The reason is that the \TeX{} macro language, unlike
most programming languages, allows % ! loin break (twatbili)
\Qref*{nothing but letters in macro names}{Q-whatmacros}.

There are a number of techniques for defining a macro with a name like
\csx{cul8r}.  Unfortunately, none of the techniques is particularly
good:
\begin{enumerate}
\item Use \csx{csname}\dots\csx{endcsname} to define and invoke the
  macro:
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
\expandafter\newcommand
       \csname cul8r\endcsname{Goodbye!}
I said, ``\csname cul8r\endcsname''.
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
\expandafter\newcommand\csname cul8r\endcsname{Goodbye!}
I said, ``\csname cul8r\endcsname''.
\end{verbatim}
\end{wideversion}
\end{quote}
  \begin{description}
  \item[Pro:] No unexpected side effects
  \item[Con:] So verbose as to be unusable
  \end{description}
\item Define a ``special-command generator'', and  use the resulting
  commands:
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
\newcommand{\DefineRemark}[2]{%
  \expandafter\newcommand
     \csname rmk-#1\endcsname{#2}%
}
\newcommand{\Remark}[1]{%
  \csname rmk-#1\endcsname%
}
...
\DefineRemark{cul8r}{Goodbye!}
...
I said, ``\Remark{cul8r}''.
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
\newcommand{\DefineRemark}[2]{%
  \expandafter\newcommand\csname rmk-#1\endcsname{#2}%
}
\newcommand{\Remark}[1]{\csname rmk-#1\endcsname}
...
\DefineRemark{cul8r}{Goodbye!}
...
\Remark{cul8r}
\end{verbatim}
\end{wideversion}
\end{quote}
  \begin{description}
  \item[Pro:] Straightforward to use, not too untidy
  \item[Con:] It's hardly doing what we set out to do (experts will
    see that you are defining a macro, but others likely won't)
  \end{description}
\item Convince \TeX{} that ``\texttt{8}'' is a letter:
\begin{quote}
\begin{verbatim}
\catcode`8 = 11 
\newcommand{\cul8r}{Goodbye!}
I said, ``\cul8r''.
\end{verbatim}
\end{quote}
  \begin{description}
  \item[Pro:] \csx{cul8r} can be used directly
  \item[Con:] Likely to break other uses of ``\texttt{8}'' (such as
    numbers or dimensions; so
    \cmdinvoke{setlength}{\csx{paperwidth}}{8in} tells us:
\begin{quote}
\begin{verbatim}
! Missing number, treated as zero.
<to be read again> 
                   8
\end{verbatim}
\end{quote}
  \end{description}
  As a general rule, changing category codes is something to use
  \emph{in extremis}, 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.
\item Define a macro \csx{cul} which must always be followed by
  ``\texttt{8r}'':
\begin{quote}
\begin{verbatim}
\def\cul8r{Goodbye!}
I said, ``\cul8r''.
\end{verbatim}
\end{quote}
  \begin{description}
  \item[Pro:] \csx{cul8r} can be used directly
  \item[Con~\#1:] Breaks if \csx{cul} is followed by anything other
    than ``\texttt{8r}'', with a confusing diagnostic~---
    \csx{cul99} produces:
\begin{quote}
\begin{wideversion}
\begin{verbatim}
! Use of \cul doesn't match its definition.
<*> \cul9
         9
\end{verbatim}
\end{wideversion}
\begin{narrowversion}
\begin{verbatim}
! Use of \cul doesn't match its 
                           definition.
<*> \cul9
         9
\end{verbatim}
\end{narrowversion}
\end{quote}
    (which would confuse someone who hadn't even realised there
    \emph{was} a definition of \csx{cul} in the document).
  \item[Con~\#2:] Silently redefines existing \csx{cul}, if any;
    as a result, the technique cannot be used to define both a
    \csx{cul8r} and, say, a \csx{cul123} macro in the same
    document.
  \end{description}
\end{enumerate}
Technique~3 is in fact commonly used~--- in a limited form~--- within
most \LaTeX{} packages and within \LaTeX{} itself.  The convention is to
use ``\texttt{@}'' within the names of internal macros to hide them
from the user and thereby prevent naming conflicts.  To this end,
\LaTeX{} automatically treats ``\texttt{@}'' as a letter while
processing classes and packages and as a non-letter while processing
the user's document.  The key to this technique is the separation:
internally a non-letter is used for macro names, and the user doesn't
see anything of it, while the status remains ``frozen'' in all the
definitions created within the class or package.  See % ! line break
\Qref[question]{\csx{@} and \texttt{@} in macro names}{Q-atsigns} for
more information.

Note that analogous use of technique~3 in this example would give us
\begin{quote}
\begin{verbatim}
\begingroup
  \catcode`8 = 11 
  \gdef\cul8r{Goodbye!}
  \gdef\later{\cul8r}
\endgroup
I said, ``\later''.
\end{verbatim}
\end{quote}
which works, but rather defeats the object of the exercise.
(\csx{later} has the ``frozen'' catcode for `8', even though the value
has reverted to normal by the time it's used; note, also, the use of
the primitive command \csx{gdef}, since \csx{newcommand} can't make a
macro that's available outside the group.)

\emph{Recommendation}: Either choose another mechanism (such as
\csx{DefineRemark} 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:
\begin{quote}
\begin{verbatim}
\newcommand{\culVIIIr}{Goodbye!}
\end{verbatim}
\end{quote}
which rather spoils the intent of the joke implicit in the example
\csx{cul8r}!
\LastEdit*{2009-06-03}

\Question[Q-findwidth]{Finding the width of a letter, word, or phrase}

Put the word in a box, and measure the width of the box. For example,
\begin{quote}
\begin{verbatim}
\newdimen\stringwidth
\setbox0=\hbox{hi}
\stringwidth=\wd0
\end{verbatim}
\end{quote}
Note that if the quantity in the \csx{hbox} is a phrase, the actual
measurement only approximates the width that the phrase will occupy in
running text, since the inter-word glue can be adjusted in paragraph
mode.

The same sort of thing is expressed in \LaTeX{} by:
\begin{quote}
\begin{verbatim}
\newlength{\gnat}
\settowidth{\gnat}{\textbf{small}}
\end{verbatim}
\end{quote}
This sets the value of the length command |\gnat| to the width of ``small''
in bold-face text.

\Question[Q-patch]{Patching existing commands}

In the general case (possibly sticking something in the middle of an
existing command) this is difficult.  However, the common requirement,
to add some code at the beginning or the end of an existing command,
is conceptually quite easy.  Suppose we want to define a version of a
command that does some small extension of its original definition: we
would naturally write:
\begin{quote}
\begin{verbatim}
\renewcommand{\splat}{\mumble\splat}
\end{verbatim}
\end{quote}
However, this would not work: a call to \csx{splat} would execute
\csx{mumble}, and the call the redefined \csx{splat} again; this is an
`unterminated recursion', that will quickly exhaust \TeX{}'s memory.

Fortunately, the \TeX{} primitive \csx{let} command comes to our
rescue; it allows us to take a ``snapshot'' of the current state of a
command, which we can then use in the redefinition of the command.
So:
\begin{quote}
\begin{verbatim}
\let\OldSmooth\smooth
\renewcommand{\smooth}{\mumble\OldSmooth}
\end{verbatim}
\end{quote}
effects the required patch, safely.  Adding things at the end of a
command works similarly.

If \csx{smooth} takes arguments, one must pass them on:
\begin{quote}
\begin{wideversion}
\begin{verbatim}
\let\OldSmooth\smooth
\renewcommand{\smooth}[2]{\mumble\OldSmooth{#1}{#2}}
\end{verbatim}
\end{wideversion}
\begin{narrowversion}
\begin{verbatim}
\let\OldSmooth\smooth
\renewcommand{\smooth}[2]%
             {\mumble\OldSmooth{#1}{#2}}
\end{verbatim}
\end{narrowversion}
\end{quote}

The situation is more difficult still if \csx{smooth} takes an
optional argument; the structure of the command is so complex that the
simple \csx{let} command does not retain the necessary detail.  In
this case, we need the \Package{letltxmacro} package which knows about all
sorts of \latex{} commands and how to replicate them.  Suppose we have
a command defined as:
\begin{quote}
\begin{verbatim}
\newcommand{\rough}[1][\default]{...}
\end{verbatim}
\end{quote}
with an optional argument (substituted with \csx{default} if it's not
present) as well as an ordinary one.  In this case we copy it using
\begin{quote}
\begin{verbatim}
\LetLtxMacro{\NewRough}{\rough}
\end{verbatim}
\end{quote}
and then repeat the technique we had above, with one extension:
\begin{quote}
\begin{verbatim}
\renewcommand{\rough}[1][\newdef]%
             {\mumble\OldRough[{#1}]{#2}}
\end{verbatim}
\end{quote}
We see here that (for tedious argument-matching reasons) it is
necessary to provide braces arround the optional argument that is
being passed on.

The general case may be achieved in two ways.  First, one can use the
\LaTeX{} command \csx{CheckCommand}; this compares an existing command
with the definition you give it, and issues a warning if two don't
match.  Use is therefore:
\begin{quote}
  |\CheckCommand{\complex}{|\meta{original definition}|}|\\
  |\renewcommand{\complex}{|\meta{new definition}|}|
\end{quote}
This technique is obviously somewhat laborious, but if the original
command comes from a source that's liable to change under the control
of someone else, it does at least warn you that your patch is in
danger of going wrong.

Otherwise, \LaTeX{} users may use one of the \Package{patchcmd},
\Package{ted} or \Package{etoolbox} packages.

The \Package{patchcmd} package addresses a slightly simpler task, by
restricting the set of commands that you may patch; you mayn't patch
any command that has an optional argument, though it does deal with
the case of commands defined with \csx{DeclareRobustCommand}.  The
package defines a \csx{patchcommand} command, that takes three
arguments: the command to patch, stuff to stick at the front of its
definition, and stuff to stick on the end of its definition.  So,
after
\begin{quote}
\begin{verbatim}
\def\b{b}
\patchcmd\b{a}{c}
\end{verbatim}
\end{quote}
we will have a new version of \csx{b} defined as ``\texttt{abc}''.

The \Package{ted} package is a `token list editor', and provides a
command \csx{substitute} which will patch the
contents of a macro, putting the result in a token-list, or
(in the form \csx{Substitute*}) using the result to (re)define a
macro.  The following example defines a simple macro, and then changes
its definition:
\begin{quote}
\begin{verbatim}
\newcommand{\myfont}%
    {\Large\sffamily\selectfont}
\Substitute*[\renewcommand{\myfont}]{\myfont}%
    {\Large\sffamily}{\huge\itshape}
\end{verbatim}
\end{quote}
The macro's definition is now:
\begin{quote}
\begin{verbatim}
\huge\itshape\selectfont
\end{verbatim}
\end{quote}

The package also offers a command \csx{ShowTokens}, which shows the
content of its argument, one token to a line, with details of the
token's category code, etc.  This is recommended as a debugging tool.

The \Package{etoolbox} (which provides user access to \eTeX{}'s
programming facilities) provides a command \csx{patchcmd} which is
very similar to \csx{Substitute}, except that it only replaces a
single instance of the token(s) in its search pattern.  Since not all
commands may be patched in this way, \csx{patchcmd} takes extra
arguments for \emph{success} and \emph{failure} cases.  The
package also provides commands that prepend (\csx{pretocmd}) or append
(\csx{apptocmd}) to the definition of a command.  Not all commands may
be patched in this way; the package provides a command
\csx{ifpatchable} which checks the prerequisites, and checks that the
target command's body does indeed include the patch string you propose
to use.  (The command \csx{ifpatchable*} omits the test on the patch
string.)

Finally, we'll briefly consider a package that is (just about)
usable, but not really recommendable.  \Package{Patch} gives you an
ingenious (and difficult to understand) mechanism, and comes as an
old-style \LaTeX{} documented macro file, which can no longer be
processed to \Qref*{produce formatted documentation, etc.\@}{Q-install-doc}.
Fortunately, the file (\File{patch.doc}) may be input directly, and
``documentation'' may found by reading the source of the package.
Roughly speaking, one gives the command a set of instructions
analogous to \ProgName{sed} substitutions, and it regenerates the
command thus amended.  Unless you can't do your job any other way,
\Package{patch} is best avoided.
\begin{ctanrefs}
\item[etoolbox.sty]\CTANref{etoolbox}
\item[letltxmacro.sty]Distributed as part of \CTANref{oberdiek}[letltxmacro]
\item[patch.doc]\CTANref{patch}
\item[patchcommand.sty]\CTANref{patchcmd}
\item[ted.sty]\CTANref{ted}
\end{ctanrefs}
\LastEdit{2011-06-29}

\Question[Q-compjobnam]{Comparing the ``job name''}

The token \csx{jobname} amusingly produces a sequence of characters
whose category code is 12 (`other'), regardless of what the characters
actually are.  Since one inevitably has to compare a macro with the
contents of another macro (using \csx{ifx}, somewhere) one needs to
create a macro whose expansion looks the same as the expansion of
\csx{jobname}.  We find we can do this with \csx{meaning}, if we strip
the ``\csx{show} command'' prefix.

The full command looks like:
\begin{quote}
\begin{wideversion}
\begin{verbatim}
\def\StripPrefix#1>{}
\def\jobis#1{FF\fi
  \def\predicate{#1}%
  \edef\predicate{\expandafter\StripPrefix\meaning\predicate}%
  \edef\job{\jobname}%
  \ifx\job\predicate
}
\end{verbatim}
\end{wideversion}
\begin{narrowversion}
\begin{verbatim}
\def\StripPrefix#1>{}
\def\jobis#1{FF\fi
  \def\predicate{#1}%
  \edef\predicate{\expandafter\StripPrefix
                    \meaning\predicate}%
  \edef\job{\jobname}%
  \ifx\job\predicate
}
\end{verbatim}
\end{narrowversion}
\end{quote}
And it's used as:
\begin{quote}
\begin{verbatim}
\if\jobis{mainfile}%
  \message{YES}%
\else
  \message{NO}%
\fi
\end{verbatim}
\end{quote}
Note that the command \csx{StripPrefix} need not be defined if you're
using \LaTeX{}~--- there's already an % line break!
\Qref*{internal command}{Q-atsigns} \csx{strip@prefix} that you can
use.

\Question[Q-isitanum]{Is the argument a number?}

\TeX{}'s own lexical analysis doesn't offer the macro programmer
terribly much support: while category codes will distinguish letters
(or what \TeX{} currently thinks of as letters) from everything else,
there's no support for analysing numbers.

The simple-minded solution is to compare numeric characters with the
characters of the argument, one by one, by a sequence of direct tests,
and to declare the argument ``not a number'' if any character fails
all comparisons:
\begin{quote}
\begin{verbatim}
\ifx1#1
\else\ifx2#1
...
\else\ifx9#1
\else\isanumfalse
\fi\fi...\fi
\end{verbatim}
\end{quote}
which one would then use in a tail-recursing macro to gobble an
argument.  One could do slightly better by assuming (pretty safely)
that the digits' character codes are consecutive:
\begin{quote}
\begin{verbatim}
\ifnum`#1<`0 \isanumfalse
\else\ifnum`#1>`9 \isanumfalse
     \fi
\fi
\end{verbatim}
\end{quote}
again used in tail-recursion.  However, these forms aren't very
satisfactory: getting the recursion ``right'' is troublesome (it has a
tendency to gobble spaces in the argument), and in any case \TeX{}
itself has mechanisms for reading numbers, and it would be nice to use
them.

Donald Arseneau's \Package{cite} package offers the following test
for an argument being a strictly positive integer:
\begin{quote}
\begin{verbatim}
\def\IsPositive#1{%
  TT\fi
  \ifcat_\ifnum0<0#1 _\else A\fi
}
\end{verbatim}
\end{quote}
which can be adapted to a test for a non-negative integer thus:
\begin{quote}
\begin{verbatim}
\def\IsNonNegative{%
  \ifcat_\ifnum9<1#1 _\else A\fi
}
\end{verbatim}
\end{quote}
or a test for any integer:
\begin{quote}
\begin{verbatim}
\def\gobbleminus#1{\ifx-#1\else#1\fi}
\def\IsInteger#1{%
  TT\fi
  \ifcat_\ifnum9<1\gobbleminus#1 _\else A\fi
}
\end{verbatim}
\end{quote}
but this surely stretches the technique further than is reasonable.

If we don't care about the sign, we can use \TeX{} to remove the
entire number (sign and all) from the input stream, and then look at
what's left:
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
\def\testnum#1{\afterassignment\testresult
               \count255=#1 \end}
\def\testresult#1\end{\ifx\end#1\end}
\def\IsInteger#1{TT\fi \testnum{#1}}
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
\def\testnum#1{\afterassignment\testresult\count255=#1 \end}
\def\testresult#1\end{\ifx\end#1\end\isanumtrue\else\isanumfalse\fi}
\end{verbatim}
\end{wideversion}
\end{quote}
(which technique is due to David Kastrup); this can provoke errors.
In a later thread on the same topic, Michael Downes offered:
\begin{quote}
\begin{wideversion}
\begin{verbatim}
\def\IsInteger#1{%
  TT\fi
  \begingroup \lccode`\-=`\0 \lccode`+=`\0
    \lccode`\1=`\0 \lccode`\2=`\0 \lccode`\3=`\0
    \lccode`\4=`\0 \lccode`\5=`\0 \lccode`\6=`\0
    \lccode`\7=`\0 \lccode`\8=`\0 \lccode`\9=`\0
  \lowercase{\endgroup
    \expandafter\ifx\expandafter\delimiter
    \romannumeral0\string#1}\delimiter
}
\end{verbatim}
\end{wideversion}
\begin{narrowversion}
\begin{verbatim}
\def\IsInteger#1{%
  TT\fi
  \begingroup \lccode`\-=`\0 \lccode`+=`\0
    \lccode`\1=`\0 \lccode`\2=`\0
    \lccode`\3=`\0 \lccode`\4=`\0
    \lccode`\5=`\0 \lccode`\6=`\0
    \lccode`\7=`\0 \lccode`\8=`\0
    \lccode`\9=`\0
  \lowercase{\endgroup
    \expandafter\ifx\expandafter\delimiter
    \romannumeral0\string#1}\delimiter
}
\end{verbatim}
\end{narrowversion}
\end{quote}
which relies on \csx{romannumeral} producing an empty result if its
argument is zero.  Sadly, this technique has the unfortunate property
that it accepts simple expressions such as `\texttt{1+2-3}'; this
could be solved by an initial \csx{gobbleminus}-like construction.

All the complete functions above are designed to be used in \TeX{}
conditionals written ``naturally''~--- for example:
\begin{quote}
\begin{verbatim}
\if\IsInteger{<subject of test>}%
  <deal with integer>%
\else
  <deal with non-integer>%
\fi
\end{verbatim}
\end{quote}
The \LaTeX{} \Class{memoir} class has an internal command of its own,
\cmdinvoke*{checkifinteger}{num}, that sets the conditional command
\csx{ifinteger} according to whether the argument was an integer.

Of course, all this kerfuffle would be (essentially) void if there was
a simple means of ``catching'' \TeX{} errors.  Imagining an
error-catching primitive \csx{ifnoerror}, one might write:
\begin{quote}
\begin{verbatim}
\def\IsInteger#1{%
  TT%
  \ifnoerror
    \tempcount=#1\relax
% carries on if no error
    \expandafter\iftrue
  \else
% here if there was an error
    \expandafter\iffalse
  \fi
}
\end{verbatim}
\end{quote}
thus using \TeX{}'s own integer-parsing code to do the check.  It's a
pity that such a mechanism was never defined (it could be that it's
impossible to program within \TeX{}!).
\begin{ctanrefs}
\item[memoir.cls]\CTANref{memoir}
\end{ctanrefs}

\Question[Q-hash]{Defining macros within macros}

The way to think of this is that |##| gets replaced by |#| in just the
same way that |#1| gets replaced by `whatever is the first argument'.

So if you define a macro:
\begin{quote}
\begin{verbatim}
\newcommand\a[1]{+#1+#1+#1+}
\end{verbatim}
\end{quote}
or (using the \tex{} primitive \csx{def}):
\begin{quote}
\begin{verbatim}
\def\a#1{+#1+#1+#1+}
\end{verbatim}
\end{quote}
and use it as \cmdinvoke{a}{b},
the macro expansion produces `+b+b+b+',
as most people would expect.

However, if we now replace part of the macro:
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
\newcommand\a[1]{+#1+%
                 \newcommand\x[1]{xxx#1}}
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
\newcommand\a[1]{+#1+\newcommand\x[1]{xxx#1}}
\end{verbatim}
\end{wideversion}
\end{quote}
then \cmdinvoke{a}{b} will give us the rather odd
\begin{quote}
  +b+\cmdinvoke{newcommand}{x}[1]{xxxb}
\end{quote}
so that the new \csx{x} ignores its argument.

If we use the \tex{} primitive: 
\begin{quote}
\begin{verbatim}
\def\a#1{+#1+\def\x #1{xxx#1}}
\end{verbatim}
\end{quote}
\cmdinvoke{a}{b} will expand to `+b+|\def\x b{xxxb}|'.  This
defines \csx{x} to be a macro \emph{delimited} by |b|, and taking no
arguments, which is surely not what was intended!

Actually, to define \csx{x} to take an argument, we need
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
\newcommand\a[1]{+#1+%
                 \newcommand\x[1]{xxx##1}}
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
\newcommand\a[1]{+#1+\newcommand\x[1]{xxx##1}}
\end{verbatim}
\end{wideversion}
\end{quote}
or, using the \tex{} primitive definition:
\begin{quote}
\begin{verbatim}
\def\a#1{+#1+\def\x ##1{xxx##1}}
\end{verbatim}
\end{quote}
and \cmdinvoke{a}{b} will expand to 
\begin{quote}
  +b+|\def\x #1{xxx#1}|
\end{quote}
because |#1| gets replaced by `b'
and |##| gets replaced by |#|.

To nest a definition inside a definition inside a definition then you
need |####1|, doubling the number of |#| signs; and at the next level
you need 8~|#|s each time, and so on.

\Question[Q-spinmacro]{Spaces in macros}

It's very easy to write macros that produce space in the typeset
output where it's neither desired nor expected.  Spaces introduced by
macros are particularly insidious because they don't amalgamate with
spaces around the macro (unlike consecutive spaces that you
type), so your output can have a single bloated space that proves
to be made up of two or even more spaces that haven't amalgamated.
And of course, your output can also have a space where none was wanted
at all.

Spaces are produced, inside a macro as elsewhere, by space or tab
characters, or by end-of-line characters.  There are two basic rules
to remember when writing a macro: first, the rules for ignoring spaces
when you're typing macros are just the same as the rules that apply
when you're typing ordinary text, and second, rules for ignoring
spaces do \emph{not} apply to spaces produced while a macro is being
obeyed (``expanded'').

Spaces are ignored in vertical mode (between paragraphs), at the
beginning of a line, and after a command name.  Since sequences of
spaces are collapsed into one, it `feels as if' spaces are ignored if
they follow another space.  Space can have syntactic meaning after
certain sorts of non-braced arguments (e.g., \emph{count} and
\emph{dimen} variable assignments in \plaintex{}) and after certain
control words (e.g., in \csx{hbox} |to|, so again we have instances
where it `feels as if' spaces are being ignored when they're merely
working quietly for their living.

Consider the following macro, fairly faithfully adapted from one that
appeared on \Newsgroup{comp.text.tex}:
\begin{narrowversion}
\begin{quote}
\begin{verbatim}
\newcommand{\stline}[1]
  { \bigskip \makebox[2cm]{ \textbf{#1} } }
\end{verbatim}
\end{quote}
(the original appeared on a single line: it's wrapped here to fit in
the printed \acro{FAQ}'s narrow columns).

\noindent
\end{narrowversion}
\begin{wideversion}
\begin{quote}
\begin{verbatim}
\newcommand{\stline}[1]{ \bigskip \makebox[2cm]{ \textbf{#1} } }
\end{verbatim}
\end{quote}
\end{wideversion}
The macro definition contains five spaces:
\begin{itemize}
\item after the opening |{| of the macro body; this space will be
  ignored, not because ``because the macro appears at the start of a
  line'', but rather because the macro was designed to operate between
  paragraphs
\item after \csx{bigskip}; this space will be ignored (while the macro
  is being defined) because it follows a command name
\item after the |{| of the mandatory argument of \csx{makebox}; even
  though this space will inevitably appear at the start of an output
  line, it will \emph{not} be ignored
\item after the |}| closing the argument of \csx{textbf}; this space
  will not be ignored, but may be overlooked if the argument is well
  within the |2cm| allowed for it
\item after the |}| closing the mandatory argument of \csx{makebox};
  this space will not be ignored
\end{itemize}
The original author of the macro had been concerned that the starts of
his lines with this macro in them were not at the left margin, and
that the text appearing after the macro wasn't always properly
aligned.  These problems arose from the space at the start of the
mandatory argument of \csx{makebox} and the space immediately after the
same argument.  He had written his macro in that way to emphasise the
meaning of its various parts; unfortunately the meaning was rather
lost in the problems the macro caused.

The principal technique for suppressing spaces is the use of
\texttt{\textpercent} characters: everything after a
\texttt{\textpercent} is ignored, even the end of line itself (so
that not even the end of line can contribute an unwanted space).  The
secondary technique is to ensure that the end of line is preceded by a
command name (since the end of line behaves like a space, it will be
ignored following a command name).  Thus the above command would be
written (by an experienced programmer with a similar eye to
emphasising the structure):
\begin{quote}
\begin{verbatim}
\newcommand{\stline}[1]{%
  \bigskip
  \makebox[2cm]{%
    \textbf{#1}\relax
  }%
}
\end{verbatim}
\end{quote}
Care has been taken to ensure that every space in the revised
definition is ignored, so none appears in the output.  The revised
definition takes the ``belt and braces'' approach, explicitly dealing
with every line ending (although, as noted above, a space introduced
at the end of the first line of the macro would have been ignored in
actual use of the macro.  This is the best technique, in fact~--- it's
easier to blindly suppress spaces than to analyse at every point
whether you actually need to.  Three techniques were used to suppress
spaces:
\begin{itemize}
\item placing a \texttt{\textpercent} character at the end of a line
  (as in the 1st, 3rd and 5th lines),
\item ending a line `naturally' with a control sequence, as in line 2,
  and
\item ending a line with an `artificial' control sequence, as in line
  4; the control sequence in this case (\csx{relax}) is a no-op in many
  circumstances (as here), but this usage is deprecated~--- a
  \texttt{\textpercent} character would have been better.
\end{itemize}
Beware of the (common) temptation to place a space \emph{before} a
\texttt{\textpercent} character: if you do this you might as well omit
the \texttt{\textpercent} altogether.

In ``real life'', of course, the spaces that appear in macros are far
more cryptic than those in the example above.  The most common spaces
arise from unprotected line ends, and this is an error that
occasionally appears even in macros written by the most accomplished
programmers.

\Question[Q-moren9]{How to break the 9-argument limit}

If you think about it, you will realise that Knuth's command
definition syntax:
\begin{quote}
\begin{verbatim}
\def\blah#1#2 ... #9{<macro body>}
\end{verbatim}
\end{quote}
is intrinsically limited to just 9 arguments.  There's no direct way
round this: how would you express a 10th argument?~--- and ensure that
the syntax didn't gobble some other valid usage?

If you really must have more than 9 arguments, the way to go is:
\begin{quote}
\begin{verbatim}
\def\blah#1#2 ... #9{%
  \def\ArgI{{#1}}%
  \def\ArgII{{#2}}%
  ...
  \def\ArgIX{{#9}}%
  \BlahRelay
}
\def\BlahRelay#1#2#3{%
  % arguments 1-9 are now in
  %   \ArgI-\ArgIX
  % arguments 10-12 are in
  %   #1-#3
  <macro body>%
}
\end{verbatim}
\end{quote}
This technique is easily extendible by concert pianists of the \TeX{}
keyboard, but is really hard to recommend.

\LaTeX{} users have the small convenience of merely giving a number of
arguments in the \csx{newcommand} that defines each part of the
relaying mechanism: Knuth's restriction applies to \csx{newcommand}
just as it does to \csx{def}.  However, \LaTeX{} users also have the
way out of such barbarous command syntax: the \Package{keyval}
package.  With \Package{keyval}, and a bit of programming, one can
write really quite sophisticated commands, whose invocation might look
like:
\begin{quote}
\begin{verbatim}
\flowerinstance{species=Primula veris,
  family=Primulaceae,
  location=Coldham's Common,
  locationtype=Common grazing land,
  date=1995/04/24,
  numplants=50,
  soiltype=alkaline
}
\end{verbatim}
\end{quote}
The merit of such verbosity is that it is self-explanatory: the typist
doesn't have to remember that argument twelve is |soiltype|, and so
on: the commands may be copied from field notes quickly and
accurately.
\begin{ctanrefs}
\item[keyval.sty]Distributed as part of \CTANref{graphics}[keyval]
\end{ctanrefs}

	* faq-mac-prog.tex (q-keyval): tweak words about getoptk

\Question[Q-keyval]{Key-value input for macros and package options}

When we discussed % !line break
\Qref*{extending the number of arguments to a macro}{Q-moren9}, we
suggested that large numbers of arguments, distinguished only by their
position, aren't very kind to the user, and that a package such as
\Package{keyval} offers a more attractive user interface.  We now
consider the packages that the macro programmer might use, to create
such a user interface.

The simplest key-value processor (for \latex{}, at least) remains
\Package{keyval}; it has a command \csx{define@key} to declare a key
and a \emph{handler} to process it, and a macro \csx{setkeys} to offer
values to the handler of one or more keys.  Thus:
\begin{quote}
\begin{verbatim}
\define@key{my}{foo}{Foo is #1\par}
\define@key{my}{bar}[99]{Bar is #1\par}
...
\setkeys{my}{foo=3,bar}
\end{verbatim}
\end{quote}
will produce output saying:
\begin{quote}
  Foo is 3\par{}
  Bar is 99
\end{quote}
This has defined two keys `\texttt{foo}' and `\texttt{bar}' in family
`\texttt{my}', and then executed them, the first with argument
`\texttt{3}' and the second with no argument, so that the default
value of `\texttt{99}' is picked up.  In effect, the two calls to
\csx{define@key} are simply defining commands, as (for example):
\begin{quote}
\begin{verbatim}
\newcommand{\KV@my@foo}[1]{Foo is #1}
\end{verbatim}
\end{quote}
(the definition of \csx{KV@my@bar} is similar, but trickier).  The
command \csx{setkeys} knows how to find those commands when it needs to
process each key~--- it is easy to regurgitate the structure of the
command name, with family name (`\texttt{my}', here) after the first
`\texttt{@}', and the key name after the second `\texttt{@}'.  (The
`\texttt{KV}' part is fixed, in \Package{keyval}.)

These simple commands are enough, in fact, to process the botanical
example offered as replacement for multi-argument commands in % ! line break
\Qref[question]{the question mentioned above}{Q-moren9}, or the
optional arguments of the \csx{includegraphics} command of the
\Package{graphicx} package.  (The last is, in fact, what
\Package{keyval} was designed to do.)

However, we need more if we're to to have package options in
`key-value' form.  Packages like \Package{hyperref} have enormously
complicated package options which need key-value processing at
\csx{ProcessOptions} time: \Package{keyval} can't do that on its own.

Heiko Oberdiek's \Package{kvoptions} package comes to our help: it
enables the programmer to declare class or package options that
operate as key and value pairs.  The package defines commands
\csx{DeclareBoolOption} for options whose value should be either
\emph{true} or \emph{false}, and \csx{DeclareStringOption} for all
other options that have a value.  Keys are declared using
\Package{keyval} and may remain available for use within the document,
or may be `cancelled' to avoid confusion.  If you have loaded
\Package{kvoptions}, the \LaTeX{} kernel's \csx{DeclareOption} becomes
\csx{DeclareVoidOption} (it's an option with no value), and
\csx{DeclareOption*} becomes \csx{DeclareDefaultOption}.

Heiko also provides \Package{kvsetkeys} which is a more robust version
of \Package{setkeys}, with some of the rough edges made smoother.

Hendri Adriaens' \Package{xkeyval} offers more flexibility than
the original \Package{keyval} and is more robust than the original,
too.  Like \Package{kvoptions}, the package also has mechanisms to
allow class and package options in key-value form (macros
\csx{DeclareOptionX}, \csx{ExecuteOptionsX} and \csx{ProcessOptionsX}.
\Package{Pstricks} bundle packages use a \Package{xkeyval} derivative
called \Package{pst-xkey} for their own key-value manipulation.
% xkvview? (i think we can ignore xkvltxp for these purposes)

The (widely-respected) \Package{pgf} graphics package has its own
key-value package called \Package{pgfkeys}.  The documentation of the
package (part of the huge \Package{pgf} manual, in part 5,
``utilities'') contains a useful comparison with other key-value
systems; some notable differences are:
\begin{itemize}
\item key organisation: \Package{pgfkeys} uses a tree structure, while
  \Package{keyval} and \Package{xkeyval} both associate keys with a family;
\item \Package{pgfkeys} supports multi-argument key code; and
\item \Package{pgfkeys} can support call-backs when an unknown key
  appears (these things are called \emph{handlers}.
\end{itemize}
Keys are organized in a tree that is reminiscent of the Unix fille
tree.  A typical key might be, \File{/tikz/coordinate system/x} or
just \File{/x}.  When you specify keys you can provide the complete
path of the key, but you usually just provide the name of the key
(corresponding to the file name without any path) and the path is
added automatically.  So a \csx{pgfkeys} command might be:
\begin{wideversion}
\begin{quote}
\begin{verbatim}
\pgfkeys{/my key=hello,/your keys/main key=something\strange,
  key name without path=something else}
\end{verbatim}
\end{quote}
\end{wideversion}
\begin{narrowversion}
\begin{quote}
\begin{verbatim}
\pgfkeys{/my key=hello,
  /your keys/main key=something\strange,
  key name without path=something else}
\end{verbatim}
\end{quote}
\end{narrowversion}
and for each key mentioned, the associated code will be executed.
\dots{} and that code is also set up using \csx{pgfkeys}:
\begin{quote}
\begin{verbatim}
\pgfkeys{/my key/.code=The value is '#1'.}
\end{verbatim}
\end{quote}
after which
\begin{quote}
\begin{verbatim}
\pgfkeys{/my key=hi!}
\end{verbatim}
\end{quote}
will produce just
\begin{quote}
  The value is 'hi!'.
\end{quote}
The manual goes on, showing how to define a key with two arguments,
how to provide default value for a key, and how to define aliases for
particular key sequences (which are called ``styles'').  All in all,
it seems a well thought-out system, offering a lot of flexibility that
isn't available with the other keys packages.  However, there seems to
be no mechanism for using \Package{pgfkeys} keys as part of the
options of another package, in the way that \Package{kvoptions} does.

The \Package{l3kernel} programming layer for \Qref*{\LaTeX{}3}{Q-LaTeX3}
includes the \Package{l3keys} module.  Inspired by \Package{pgfkeys},
it provides a keyval-based method for the programmer to create keys.
As with keyval and derivatives, \Package{l3keys} uses separate macros
for defining and setting keys.  The package \Package{l3keys2e} makes
it possible for \latexe{} class and package
options to be processed using \Package{l3keys}. \Package{L3kernel}
code can be used within existing LaTeX2e documents, so
\Package{l3keys} is also available to the \latexe{} programmer `direct'.

Another key-value system that's part of larger set of macros is
\Package{scrbase}, which uses the facilities of \Package{keyval} to
build a larger set of facilities, originally for use within the
\Class{KOMA-script} bundle.  For English-speaking authors, there are
difficulties from the German-only documentation; however, from a
partial translation available to the author of this answer, a summary
is possible.  The package may build on the facilities either of
\Package{kyeval} or of \Package{xkeyval}, and builds its functionality
on the structure of the `key family'.  The user may define family
`members' and keys are defined relative to the members.  (For example,
the package \Package{scrbase} is part of the \Class{KOMA-script}
bundle; so its keys are all members of the \Package{scrbase.sty}
family within the \Package{KOMA} family.  The function
\csx{FamilyProcessOptions} allows the programmer to decode the options
of the package in terms of the package's key family.  Note that there
is no special provision made for ``traditional'' package options, as
in the \Package{kvoptions} package.

This brief summary was guided by input from two sources: a draft article
for \textsl{TUGboat} by Joseph Wright, and the partial translation of the
documentation of package \Package{scrbase} prepared by Philipp
Stephani.

All the above are (at least) aimed at \latex{} programming; there is
one package, \Package{getoptk}, aimed at the \plaintex{} programmer.
\Package{Getoptk} uses syntax inspired by that offered by \tex{}
primitives such as \csx{hrule} and \csx{hbox}, so we are offered
syntax such as:
\begin{wideversion}
\begin{quote}
\begin{verbatim}
\begindisplay file {chapter1} literal offset 20pt
\end{verbatim}
\end{quote}
(taken from the package manual).
\end{wideversion}
\begin{narrowversion}
\begin{quote}
\begin{verbatim}
\begindisplay file {chapter1} %
                literal offset 20pt
\end{verbatim}
\end{quote}
(taken from the package manual, but wrapped to fit into narrow
columns).
\end{narrowversion}

There are (we know) people who would swear that such syntax is
wonderful (the present author wouldn't), but the package earns its
place as the only stand-alone key-value macros that will work in \plaintex{}.
\begin{ctanrefs}
\item[getoptk.tex]\CTANref{getoptk}
\item[keyval.sty]Distributed as part of \CTANref{graphics}[keyval]
\item[kvoptions.sty]Distributed as part of \CTANref{oberdiek}[kvoptions]
\item[kvsetkeys.sty]Distributed as part of \CTANref{oberdiek}[kvsetkeys]
\item[l3keys.sty]Distributed as part of \CTANref{l3kernel}
\item[l3keys2e.sty]Distributed as part of \CTANref{l3packages}
\item[pgfkeys.sty]Distributed as part of \CTANref{pgf}
\item[scrbase.sty]Distributed as part of \CTANref{koma-script}
\item[xkeyval.sty]\CTANref{xkeyval}
\end{ctanrefs}
\LastEdit{2011-09-06}

\Question[Q-activechars]{Defining characters as macros}

Single characters can act as macros (defined commands), and both
\plaintex{} and \LaTeX{} define the character
``\texttt{\textasciitilde}'' as a ``non-breakable space''.  A
character is made definable, or ``active'', by setting its
\emph{category code} (catcode) to be \csx{active} (13):
\begin{quote}
\begin{verbatim}
\catcode`\_=\active
\end{verbatim}
\end{quote}
Any character could, in principle, be activated this way and defined
as a macro:
\begin{quote}
\begin{verbatim}
\def_{\_}
\end{verbatim}
\end{quote}
which could be characterised as an over-simple answer to % ! line break
\Qref[question]{using underscores}{Q-underscore}.  However, you must be
wary: whereas people expect an active tilde, other active characters
may be unexpected and interact badly with other macros.  Furthermore,
by defining an active character, you preclude the character's use for
other purposes, and there are few characters ``free'' to be subverted
in this way.

To define the character ``\texttt{z}'' as a command, one would say something
like:
\begin{quote}
\begin{verbatim}
\catcode`\z=\active
\def z{Yawn, I'm tired}%
\end{verbatim}
\end{quote}
and each subsequent ``\texttt{z}'' in the text would become a
yawn. This would be an astoundingly bad idea for most documents, but
might have special applications.  (Note that, in ``\csx{def}\texttt{
  z}'', ``\texttt{z}'' is no longer interpreted as a letter; the space
is therefore not necessary~--- ``\csx{defz}'' would do; we choose to
retain the space, for what little clarity we can manage.)
Some \LaTeX{} packages facilitate such definitions. For example, the
\Package{shortvrb} package with its \csx{MakeShortVerb} command.

\TeX{} uses category codes to interpret characters as they are read 
from the input.
% beware line break
\emph{Changing a catcode value will not affect characters that have already been read}.
Therefore, it is best if characters have fixed category codes for the
duration of a document.  If catcodes are changed for particular
purposes (the \csx{verb} command does this), then the altered
characters will not be interpreted properly when they  appear in the
argument to another command (as, for example, in
% beware line-break
\htmlonly{``}\Qref[question]{\csx{verb} in command arguments}{Q-verbwithin}\htmlonly{''}).
An exemplary case is the \Package{doc} package, which processes .dtx
files using the \Package{shortvrb} package to define
\texttt{\textbar\dots{}\textbar} as a shorthand for
\csx{verb}\texttt{\textbar\dots{}\textbar}. But \texttt{\textbar} is
also used in the preambles of tabular environments, so that tables in
\extension{dtx} files can only have vertical line separation between
columns by employing special measures of some sort.

Another consequence is that catcode assignments made
in macros often don't work as expected % beware linebreak
(\htmlonly{see ``}\Qref{Active characters in command arguments}{Q-actinarg}\htmlonly{''}).
For example, the definition
\begin{quote}
\begin{verbatim}
\def\mistake{%
\catcode`_=\active
\def_{\textunderscore\-}%
}
\end{verbatim}
\end{quote}
does not work because it attempts to define an ordinary \texttt{\_} character:
When the macro is used, the category change does not apply to the 
underscore character already in the macro definition.  Instead, one may
use:
\begin{quote}
\begin{verbatim}
\begingroup
\catcode`_=\active
\gdef\works{%    note the global \gdef
  \catcode`_=\active
  \def_{\textunderscore\-}%
}
\endgroup
\end{verbatim}
\end{quote}
The alternative (``tricksy'') way of creating such an isolated
definition depends on the curious properties of \csx{lowercase}, which
changes characters without altering their catcodes.  Since there is
always \emph{one} active character (``\texttt{\textasciitilde}''), we
can fool \csx{lowercase} into patching up a definition without ever
explicitly changing a catcode:
\begin{quote}
\begin{verbatim}
\begingroup
  \lccode`\~=`\_
  \lowercase{\endgroup
    \def~{\textunderscore\-}%
  }%
\end{verbatim}
\end{quote}
The two definitions have the same overall effect (the character is
defined as a command, but the character does not remain active),
except that the first defines a \csx{global} command.

For active characters to be used only in maths mode, it is much better
to leave the character having its ordinary catcode, but assign it a
special active \emph{maths code}, as with
\begin{quote}
\begin{verbatim}
\begingroup
  \lccode`~=`x
  \lowercase{\endgroup
    \def~{\times}%
  }%
\mathcode`x="8000
\end{verbatim}
\end{quote}
The special character does not need to be redefined whenever it is
made active~--- the definition of the command persists even if the
character's catcode reverts to its original value; the definition
becomes accessible again if the character once again becomes active.
\begin{ctanrefs}
\item[doc.sty]Part of the \LaTeX{} distribution \CTANref{latex}[doc]
\item[shortvrb.sty]Part of the \LaTeX{} distribution \CTANref{latex}[shortvrb]
\end{ctanrefs}


\Question[Q-actinarg]{Active characters in command arguments}

Occasionally, it's nice to make one or two characters active in the
argument of a command, to make it easier for authors to code the
arguments.

Active characters \emph{can} be used safely in such situations; but
care is needed.

An example arose while this answer was being considered: an aspirant
macro writer posted to \Newsgroup{comp.text.tex} asking for help to
make |#| and |b| produce musical sharp and flat signs, respectively,
in a macro for specifying chords.

The first problem is that both |#| and |b| have rather important uses
elsewhere in \TeX{} (to say the least!), so that the characters can
only be made active while the command is executing.

Using the techniques discussed in % beware line break, next line
\htmlonly{``}\Qref[question]{characters as commands}{Q-activechars}\htmlonly{''},
we can define:
\begin{quote}
\begin{verbatim}
\begingroup
  \catcode`\#=\active
  \gdef#{$\sharp$}
\endgroup
\end{verbatim}
\end{quote}
and:
\begin{quote}
\begin{verbatim}
\begingroup
  \lccode`\~=`\b
  \lowercase{\endgroup
    \def~{$\flat$}%
  }
\end{verbatim}
\end{quote}
The second problem is one of timing: the command has to make each
character active \emph{before} its arguments are read: this means that
the command can't actually ``have'' arguments itself, but must be
split in two.  So we write:
\begin{quote}
\begin{verbatim}
\def\chord{%
  \begingroup
    \catcode`\#=\active
    \catcode`\b=\active
    \Xchord
}
\def\Xchord#1{%
    \chordfont#1%
  \endgroup
}
\end{verbatim}
\end{quote}
and we can use the command as \cmdinvoke{chord}{F\#} or
\cmdinvoke{chord}{Bb minor}.

Two features of the coding are important:
\begin{itemize}
\item \csx{begingroup} in \csx{chord} opens a group that is closed by
  \csx{endgroup} in \csx{Xchord}; this group limits the change of
  category codes, which is the \emph{raison d'\^etre} of the whole
  exercise.
\item Although |#| is active while \csx{Xchord} is executed, it's
  \emph{not} active when it's being defined, so that the use of |#1|
  doesn't require any special attention.
\end{itemize}

Note that the technique used in such macros as \csx{chord}, here, is
analogous to that used in such commands as \csx{verb}; and, in just the
same way as \csx{verb} (see
% beware breaking long line
\htmlonly{``}\Qref[question]{\csx{verb} doesn't work in arguments}{Q-verbwithin}\htmlonly{''}),
\csx{chord} won't work inside the argument of another command (the
error messages, if they appear at all, will probably be rather odd).


\Question[Q-csname]{Defining a macro from an argument}

It's common to want a command to create another command: often one
wants the new command's name to derive from an argument.  \LaTeX{}
does this all the time: for example, \csx{newenvironment} creates
start- and end-environment commands whose names are derived from the
name of the environment command.

The (seemingly) obvious approach:
\begin{quote}
\begin{verbatim}
\def\relay#1#2{\def\#1{#2}}
\end{verbatim}
\end{quote}
doesn't work (the \TeX{} engine interprets it
as a rather strange redefinition of |\#|).  The trick is to use
\csx{csname}, which is a \TeX{} primitive for generating command names
from random text, together with \csx{expandafter}.  The definition
above should read:
\begin{quote}
\begin{verbatim}
\def\relay#1#2{%
  \expandafter\def\csname #1\endcsname{#2}%
}
\end{verbatim}
\end{quote}
With this definition, \cmdinvoke{relay}{blah}{bleah} is equivalent to
\csx{def}\cmdinvoke{blah}{bleah}.

Note that the definition of \csx{relay} omits the braces round the
`command name' in the \csx{newcommand} it executes.  This is
because they're not necessary (in fact they seldom are), and in this
circumstance they make the macro code slightly more tedious.

The name created need not (of course) be \emph{just} the argument:
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
\def\newrace#1#2#3{\expandafter\def
    \csname start#1\endcsname{%
      #2%
  }%
  \expandafter\def
    \csname finish#1\endcsname{%
      #3%
  }%
}
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
\def\newrace#1#2#3{%
  \expandafter\def\csname start#1\endcsname{%
    #2%
  }%
  \expandafter\def\csname finish#1\endcsname{%
    #3%
  }%
}
\end{verbatim}
\end{wideversion}
\end{quote}
With commands
\begin{quote}
\begin{verbatim}
\def\start#1{\csname start#1\endcsname}
\def\finish#1{\csname finish#1\endcsname}
\end{verbatim}
\end{quote}
these `races' could behave a bit like \LaTeX{} environments.

\Question[Q-cvtlatex]{Transcribing \LaTeX{} command definitions}

At several places in this \acro{FAQ}, questions are answered in terms
of how to program a \LaTeX{} macro.  Sometimes, these macros might
also help users of \plaintex{} or other packages; this answer
attempts to provide a rough-and-ready guide to transcribing such macro
definitions for use in other packages.

The reason \LaTeX{} has commands that replace \csx{def}, is that
there's a general philosophy within \LaTeX{} that the user should be
protected from himself: the user has different commands according to
whether the command to be defined exists (\csx{renewcommand}) or not
(\csx{newcommand}), and if its status proves not as the user expected,
an error is reported.  A third definition command,
\csx{providecommand}, only defines if the target is not already
defined; \LaTeX{} has no direct equivalent of \csx{def}, which ignores
the present state of the command.  The final command of this sort is
\csx{DeclareRobustCommand}, which creates a command which is ``robust''
(i.e., will not expand if subjected to \LaTeX{} ``protected
expansion''); from the \plaintex{} user's point of view,
\csx{DeclareRobustCommand} should be treated as a non-checking version
of \csx{newcommand}.

\LaTeX{} commands are, by default, defined \csx{long}; an optional \texttt{*}
between the \csx{newcommand} and its (other) arguments specifies that
the command is \emph{not} to be defined \csx{long}.  The \texttt{*} is
detected by a command \csx{@ifstar} which uses \csx{futurelet} to switch
between two branches, and gobbles the \texttt{*}: \LaTeX{} users are
encouraged to think of the \texttt{*} as part of the command name.

\LaTeX{}'s checks for unknown command are done by \csx{ifx} comparison
of a \csx{csname} construction with \csx{relax}; since the command name
argument is the desired control sequence name, this proves a little
long-winded.  Since \texttt{\#1} is the requisite argument, we have:
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
\expandafter\ifx
  \csname
    \expandafter\@gobble\string#1%
  \endcsname
  \relax
    ...
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
\expandafter\ifx
  \csname\expandafter\@gobble\string#1\endcsname
  \relax
    ...
\end{verbatim}
\end{wideversion}
\end{quote}
(\csx{@gobble} simply throws away its argument).

The arguments of a \LaTeX{} command are specified by two optional
arguments to the defining command: a count of arguments (0--9: if the
count is 0, the optional count argument may be omitted), and a default
value for the first argument, if the defined command's first argument
is to be optional.  So:
\begin{quote}
\begin{verbatim}
\newcommand\foo{...}
\newcommand\foo[0]{...}
\newcommand\foo[1]{...#1...}
\newcommand\foo[2][boo]{...#1...#2...}
\end{verbatim}
\end{quote}
In the last case, \csx{foo} may be called as \cmdinvoke{foo}{goodbye},
which is equivalent to \cmdinvoke{foo}[boo]{goodbye} (employing the
default value given for the first argument), or as
\cmdinvoke{foo}[hello]{goodbye} (with an explicit first argument).

Coding of commands with optional arguments is exemplified by the
coding of the last \csx{foo} above:
\begin{quote}
\begin{verbatim}
\def\foo{\futurelet\next\@r@foo}
\def\@r@foo{\ifx\next[%
    \let\next\@x@foo
  \else
    \def\next{\@x@foo[boo]}%
  \fi
  \next
}
\def\@x@foo[#1]#2{...#1...#2...}
\end{verbatim}
\end{quote}

\Question[Q-empty]{Detecting that something is empty}

Suppose you need to know that the argument of your command is empty:
that is, to distinguish between \cmdinvoke{cmd}{\relax} % \relax doesn't print
and \cmdinvoke{cmd}{blah}.  This is pretty simple:
\begin{quote}
\begin{verbatim}
\def\cmd#1{%
  \def\tempa{}%
  \def\tempb{#1}%
  \ifx\tempa\tempb
    <empty case>
  \else
    <non-empty case>
  \fi
}
\end{verbatim}
\end{quote}
The case where you want to ignore an argument that consists of nothing
but spaces, rather than something completely empty, is more tricky.
It's solved in the code fragment \Package{ifmtarg}, which defines
commands \csx{@ifmtarg} and \csx{@ifnotmtarg}, which examine their
first argument, and select (in opposite directions) their second or
third argument.  The package's code also appears in the \LaTeX{}
\Class{memoir} class.

\Package{Ifmtarg} makes challenging reading; there's also a discussion of the
issue in number two of the ``around the bend'' articles by the late
lamented Mike Downes.
\begin{ctanrefs}
\item[\nothtml{\rmfamily}Around the bend series]\CTANref{aro-bend}
\item[ifmtarg.sty]\CTANref{ifmtarg}
\item[memoir.cls]\CTANref{memoir}
\end{ctanrefs}

\Question[Q-whatengine]{Am I using \pdftex{}, \xetex{} or \luatex{}?}
\AliasQuestion{Q-ifpdf}

You often need to know what ``engine'' your macros are running on (the
engine is the \tex{}-derivative or \tex{}-alike processor that
typesets your document).  The reason that you need to know is that the
set of functions available in each engine is different.  Thus, for
\tex{} macros to run on any engine, they need to ``know'' what they
can and cannot do, which depends on the engine in use.  Getting the
right answer is surprisingly tricky (see below for an elaboration of
one apparently simple test).

There is now a comprehensive set of packages that answer the question
for you.  They all create a \tex{} conditional command:
\begin{itemize}
\item \Package{ifpdf} creates a command \csx{ifpdf},
\item \Package{ifxetex} creates a command \csx{ifxetex} and
\item \Package{ifluatex} creates a command \csx{ifluatex}.
\end{itemize}
These \tex{} commands may be used within the \latex{} conditional
framework, as (for example):
\begin{quote}
  \csx{ifthenelse}\texttt{\char`\{}\cmdinvoke{boolean}{pdf}\texttt{\char`\}\char`\{\meta{if pdf}\char`\}\char`\{\meta{not pdf}\char`\}}
\end{quote}

The \Package{ifxetex} package also provides a command
\csx{RequireXeTeX} which creates an error if the code is not running
under \xetex{}; while the other packages don't provide such a command,
it's not really difficult to write one for yourself.

% khalighi's iftex package, too -- \require's for all engines, but i'm
% not entirely sure of the conditionals, so "for later" if at all

Now for those who want to do the job for themselves: here's a
discussion of doing the job for \pdftex{} and \csx{ifpdf}~--- the
eager programmer can regenerate \csx{ifxetex} or \csx{ifluatex} in the
same fashion.  It's not recommended\dots

Suppose you need to test whether your output will be \acro{PDF} or
\acro{DVI}.  The natural thing is to check whether you have access to
some \PDFTeX{}-only primitive; a good one to try (not least because it
was present in the very first releases of \PDFTeX{}) is
\csx{pdfoutput}.  So you try
\begin{quote}
\begin{verbatim}
\ifx\pdfoutput\undefined
  ... % not running PDFTeX
\else
  ... % running PDFTeX
\fi
\end{verbatim}
\end{quote}
Except that neither branch of this conditional is rock-solid.  The
first branch can be misleading, since the ``awkward'' user could have
written:
\begin{quote}
\begin{verbatim}
\let\pdfoutput\undefined
\end{verbatim}
\end{quote}
so that your test will falsely choose the first alternative.  While
this is a theoretical problem, it is unlikely to be a major one.

More important is the user who loads a package that uses
\LaTeX{}-style testing for the command name's existence (for example,
the \LaTeX{} \Package{graphics} package, which is useful even to the
\plaintex{} user).  Such a package may have gone ahead of you, so the
test may need to be elaborated:
\begin{quote}
\begin{verbatim}
\ifx\pdfoutput\undefined
  ... % not running PDFTeX
\else
  \ifx\pdfoutput\relax
    ... % not running PDFTeX
  \else
    ... % running PDFTeX
  \fi
\fi
\end{verbatim}
\end{quote}
If you only want to know whether some \PDFTeX{} extension (such as
marginal kerning) is present, you can stop at this point: you know as
much as you need.

However, if you need to know whether you're creating \acro{PDF}
output, you also need to know about the value of \csx{pdfoutput}:
\begin{quote}
\begin{verbatim}
\ifx\pdfoutput\undefined
  ... % not running PDFTeX
\else
  \ifx\pdfoutput\relax
    ... % not running PDFTeX
  \else
    % running PDFTeX, with...
    \ifnum\pdfoutput>0
      ... % PDF output
    \else
      ... % DVI output
    \fi
  \fi
\fi
\end{verbatim}
\end{quote}
\begin{ctanrefs}
\item[ifpdf.sty]Distributed as part Heiko Oberdiek's bundle
  \CTANref{oberdiek}[ifpdf]
\item[ifluatex.sty]Distributed as part of Heiko Oberdiek's bundle
  \CTANref{oberdiek}[ifluatex]
\item[ifxetex.sty]\CTANref{ifxetex}
\end{ctanrefs}

\Question[Q-subverttoks]{Subverting a token register}

A common requirement is to ``subvert'' a token register that other
macros may use.  The requirement arises when you want to add something
to a system token register (\csx{output} or \csx{every*}), but know
that other macros use the token register, too.  (A common requirement
is to work on \csx{everypar}, but \LaTeX{} changes \csx{everypar} at
every touch and turn.)

The following technique, due to David Kastrup, does what you need, and
allows an independent package to play the exact same game:
\begin{quote}
\begin{wideversion}
\begin{verbatim}
\let\mypkg@@everypar\everypar
\newtoks\mypkg@everypar
\mypkg@everypar\expandafter{\the\everypar}
\mypkg@@everypar{\mypkgs@ownstuff\the\mypkg@everypar}
\def\mypkgs@ownstuff{%
  <stuff to do at the start of the token register>%
}
\let\everypar\mypkg@everypar
\end{verbatim}
\end{wideversion}
\begin{narrowversion}
\begin{verbatim}
\let\mypkg@@everypar\everypar
\newtoks\mypkg@everypar
\mypkg@everypar\expandafter{\the\everypar}
\mypkg@@everypar{\mypkgs@ownstuff
                      \the\mypkg@everypar}
\def\mypkgs@ownstuff{%
  <stuff to do at the start of
                      the token register>%
}
\let\everypar\mypkg@everypar
\end{verbatim}
\end{narrowversion}
\end{quote}
As you can see, the package (\Package{mypkg})
\begin{itemize}
\item creates an alias for the existing ``system'' \csx{everypar}
  (which is frozen into any surrounding environment, which will carry
  on using the original);
\item creates a token register to subvert \csx{everypar} and
  initialises it with the current contents of \csx{everypar};
\item sets the ``old'' \csx{everypar} to execute its own extra code,
  as well as the contents of its own token register;
\item defines the macro for the extra code; and
\item points the token \csx{everypar} at the new token register.
\end{itemize}
and away we go.

The form \csx{mypkg@...} is (sort of) blessed for \LaTeX{} package
internal names, which is why this example uses macros of that form.

\Question[Q-isdef]{Is this command defined?}

Macro sets from the earliest days of \TeX{} programming may be
observed to test whether commands exist by using
\begin{quote}
\csx{ifx} \csx{}\texttt{\emph{command}} \csx{undefined} \meta{stuff} \dots{}
\end{quote}
(which of course actually tests that the command \emph{doesn't}
exist).  \LaTeX{} programmers can make use of the internal command
\begin{quote}
  \cmdinvoke*{@ifundefined}{cmd name}{action1}{action2}
\end{quote}
which executes \texttt{action1} if the command is undefined, and
\texttt{action2} if it is defined
(\emph{cmd name} is the command name only, omitting the `|\|' character).

The \csx{@ifundefined} command is based on the sequence
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
\expandafter
    \ifx\csname cmd name\endcsname\relax
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
\expandafter \ifx \csname cmd name\endcsname \relax
\end{verbatim}
\end{wideversion}
\end{quote}
which relies on the way \csx{csname} works: if the command doesn't
exist, it simply creates it as an alias for \csx{relax}.

So: what is wrong with these techniques?

Using \csx{undefined} blithely assumes that the command is indeed not
defined.  This isn't entirely safe; one could make the name more
improbable, but that may simply make it more difficult to spot a
problem when things go wrong.  \LaTeX{} programmers who use the
technique will typically employ \csx{@undefined}, adding a single
level of obscurity.

The \csx{@ifundefined} mechanism has the unfortunate property of
polluting the name space: each test that turns out undefined adds a
name to the set \TeX{} is holding, and often all those ``\csx{relax}''
names serve no purpose whatever.  Even so (sadly) there are places in
the code of \LaTeX{} where the existence of the \csx{relax} is relied
upon, after the test, so we can't get away from \csx{@ifundefined}
altogether.

David Kastrup offers the (rather tricky)
\begin{quote}
\begin{wideversion}
\begin{verbatim}
{\expandafter}\expandafter\ifx \csname cmd name\endcsname\relax ...
\end{verbatim}
\end{wideversion}
\begin{narrowversion}
\begin{verbatim}
{\expandafter}\expandafter
    \ifx \csname cmd name\endcsname \relax ...
\end{verbatim}
\end{narrowversion}
\end{quote}
which ``creates'' the \csx{relax}-command inside the group of the first
\csx{expandafter}, therefore forgets it again once the test is done.
The test is about as good as you can do with macros.

The \Qref*{\eTeX{} system}{Q-etex} system comes to our help here: it
defines two new primitives:
\begin{itemize}
\item \csx{ifdefined}, which tests whether a thing is defined (the
  negative of comparing with \csx{undefined}, as it were), and
\item \csx{ifcsname} \texttt{cmd name}\csx{endcsname}, which does the
  negative of \csx{@ifundefined} without the \csx{relax}-command
  side-effect.
\end{itemize}
So, in an \eTeX{}-based system, the following two conditional clauses do
the same thing:
\begin{quote}
\begin{verbatim}
\ifdefined\foo
  \message{\string\foo\space is defined}%
\else
  \message{no command \string\foo}%
\fi
%
\ifcsname foo\endcsname
  \message{\string\foo\space is defined}%
\else
  \message{no command \string\foo}%
\fi
\end{verbatim}
\end{quote}
However, after using the \LaTeX{}
\cmdinvoke{@ifundefined}{foo}\dots{}, the conditionals will detect the
command as ``existing'' (since it has been \csx{let} to \csx{relax});
so it is important not to mix mechanisms for detecting the state of a
command.

Since most distributions nowadays use \eTeX{} as their base executable
for most packages, these two primitives may be expected appear widely
in new macro packages.

\subsection{\LaTeX{} macro tools and techniques}

\Question[Q-plninltx*]{Using Plain or primitive commands in \LaTeX{}}

It's well-known that \LaTeX{} commands tend to be more complex, and to
run more slowly than, any \plaintex{} (or primitive) command that they
replace.  There is therefore great temptation not to use \LaTeX{}
commands when macro programming.  Nevertheless, the general rule is
that you should use \LaTeX{} commands, if there are seeming
equivalents.  The exception is when you are sure you know the
differences between the two commands and you know that you need the
\plaintex{} version.  So, for example, use \csx{mbox} in place of \csx{hbox}
unless you know that the extras that \LaTeX{} provides in \csx{mbox}
would cause trouble in your application.  Similarly, use
\csx{newcommand} (or one of its relatives) unless you need one of the
constructs that cannot be achieved without the use of \csx{def} (or friends).

As a general rule, any \LaTeX{} text command will start a new
paragraph if necessary; this isn't the case with \plaintex{}
commands, a fact which has a potential to confuse.

The commands \csx{smallskip}, \csx{medskip} and \csx{bigskip} exist both
in \plaintex{} and \LaTeX{}, but behave slightly differently: in
\plaintex{} they terminate the current paragraph, but in \LaTeX{} they 
don't.  The command \csx{line} is part of picture mode in \LaTeX{},
whereas it's defined as ``\csx{hbox}\texttt{ to }\csx{hsize}'' in
\plaintex{}. (There's no equivalent for users of the \plaintex{} command in
\LaTeX{}: an equivalent appears as the internal command \csx{@@line}).

Maths setting shows a case where the \LaTeX{} version \emph{is}
essentially equivalent to the \TeX{} primitive commands: the \LaTeX{}
\csx{(}\texttt{\ ...\ }\csx{)} does essentially no different to the
\TeX{} \texttt{\$\ ...\ \$}
(except for checking that you're not attempting to open a maths
environment when you're already in one, or vice versa).  % ! line break
However, \csx{[}\texttt{\ ...\ }\csx{]} \emph{isn't} the same as 
\texttt{\$\$\ ...\ \$\$}: the \TeX{} version, used
in \LaTeX{}, can miss the effect of the class option \pkgoption{fleqn}.

Font handling is, of course, wildly different in \plaintex{} and
\LaTeX{}.  \plaintex{}'s font loading command
(\csx{font}\csx{foo=}\meta{fontname}) and its \LaTeX{} equivalent
(\csx{newfont}) should be avoided wherever possible.  They are only
safe in the most trivial contexts, and are potential sources of great
confusion in many circumstances.   Further discussion of this issue
may be found in ``\Qref*{What's wrong with \csx{newfont}?}{Q-newfont*}''.
%%
%% Consider \csx{vskip} (or \plaintex{} users of it like \csx{medskip})
%% \emph{vs}.\nothtml{\@} \csx{vspace} or \csx{vspace*}, but most
%% especially \csx{addvspace}.
%% \begin{ctanrefs}
%% \item[fntguide.pdf]\CTANref{fntguide.pdf}
%% \item[fntguide.tex]Distributed with \CTANref{latex}
%% \end{ctanrefs}

\Question[Q-atsigns]{\csx{@} and \texttt{@} in macro names}

Macro names containing \texttt{@} are \emph{internal} to \LaTeX{}, and
without special treatment just don't work in ordinary use.  A nice
example of the problems caused is discussed in % ! beware line break
\Qref*{\csx{@} in vertical mode}{Q-atvert}''.

The problems users see are caused by copying bits of a class
(\extension{cls} file) or 
package (\extension{sty} file) into a document, or by including a class or
package file into a \LaTeX{} document by some means other than
\csx{documentclass} or \csx{usepackage}.  \LaTeX{} defines internal
commands whose names contain the character \texttt{@} to
avoid clashes between its internal names and names that we would
normally use in our documents.  In order that these commands may work
at all, \csx{documentclass} and \csx{usepackage} play around with the
meaning of \texttt{@}.

If you've included a file some other way (for example, using
\csx{input}), you can probably solve the problem by using the correct
command.

If you're using a fragment of a package or class, you may well feel
confused: books such as the first edition of the % ! line break
\Qref*{The \LaTeX{} Companion}{Q-latex-books} 
are full of fragments of packages as examples for you to employ.
The second edition of the \emph{Companion} makes clearer how you
should use these fragments, and in addition, the code of
all the examples is now available on \acro{CTAN}.
To see the technique in practice, look at the example below, from file
\File{2-2-7.ltx} in the \emph{Companion} examples directory:
\begin{quote}
\begin{verbatim}
\makeatletter
\renewcommand\subsection{\@startsection
  {subsection}{2}{0mm}%name, level, indent
  {-\baselineskip}%             beforeskip
  {0.5\baselineskip}%            afterskip
  {\normalfont\normalsize\itshape}}% style
\makeatother
\end{verbatim}
\end{quote}
(That example appears on page 29 of \emph{The \LaTeX{} Companion},
second edition.)

The alternative is to treat all these fragments as a package proper,
bundling them up into a \extension{sty} file and including them with
\csx{usepackage}; this way you hide your \LaTeX{} internal code somewhere
that \LaTeX{} internal code is expected, which often looks `tidier'.
\begin{ctanrefs}
\item[\nothtml{\rmfamily}Examples from the Companion]\CTANref{tlc2}
\end{ctanrefs}
\LastEdit{2011-06-01}

\Question[Q-protect]{What's the reason for `protection'?}

Sometimes \LaTeX{} saves data it will reread later. These data are
often the argument of some command; they are the so-called moving
arguments.  (`Moving' because data are moved around.)  Candidates
are all arguments that may go into table of contents, list of figures,
\emph{etc}.; 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's a complete list in Lamport's book
(see \Qref[question]{\TeX{}-related books}{Q-latex-books}).

What'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
``\csx{protect}\csx{cmd}'' tells \LaTeX{} to save \csx{cmd} as
\csx{cmd}, without expanding it at all.

So, what is a `fragile command'?~--- it's a command that expands into
illegal \TeX{} code during the save process.

What is a `robust command'?~--- it's a command that expands into legal
\TeX{} code during the save process.

Lamport's book says in its description of every LaTeX command whether
it is `robust' or `fragile'; it also says that every command with an
optional argument is fragile.  The list isn't reliable, and neither
is the assertion about optional arguments; the statements may have
been true in early versions of \LaTeXe{} but are not any longer
necessarily so:
\begin{itemize}
\item Some fragile commands, such as \csx{cite}, have been made robust
  in later revisions of \LaTeX{}.
\item Some commands, such as \csx{end} and \csx{nocite}, are fragile
  even though they have no optional arguments.
\item The ``user's way'' of creating a command with an optional
  argument (using \csx{newcommand} or \csx{newcommand*}) now always
  creates a robust command (though macros without optional arguments
  may still be fragile if they do things that are themselves fragile).
\item There is no reason that a package author should not also make
  robust commands with optional arguments as part of the package.
\item Some robust commands are redefined by certain packages to be
  fragile (the \csx{cite} command commonly suffers this treatment).
\end{itemize}
Further, simply ``hiding'' a fragile command in another command, has
no effect on fragility.  So, if \csx{fred} is fragile, and you write:
\begin{quote}
\begin{verbatim}
\newcommand{\jim}{\fred}
\end{verbatim}
\end{quote}
then \csx{jim} is fragile too.  There is, however, the
\csx{newcommand}-replacement \csx{DeclareRobustCommand}, which
\emph{always} creates a robust command (whether or not it has optional
arguments).  The syntax of \csx{DeclareRobustCommand} is substantially
identical to that of \csx{newcommand}, and if you do the wrapping
trick above as:
\begin{quote}
\begin{verbatim}
\DeclareRobustCommand{\jim}{\fred}
\end{verbatim}
\end{quote}
then \csx{jim} is robust.

Finally, we have the \Package{makerobust} package, which  defines
\csx{MakeRobustCommand} to convert a command to be robust.  With the
package, the ``wrapping'' above can simply be replaced by:
\begin{quote}
\begin{verbatim}
\MakeRobustCommand\fred
\end{verbatim}
\end{quote}
Whereafter, \csx{fred} is robust.  Using the package may be reasonable
if you have lots of fragile commands that you need to use in moving
arguments.

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 \csx{protect}ion.
\begin{ctanrefs}
\item[makerobust.sty]Distributed as part of Heiko Oberdiek's bundle
  \CTANref{oberdiek}[makerobust]
\end{ctanrefs}
\LastEdit{2011-06-01}

\Question[Q-edef]{\csx{edef} does not work with \csx{protect}}

Robust \LaTeX{} commands are either ``naturally robust''~--- meaning that
they never need \csx{protect}, or ``self-protected''~--- meaning that
they have \csx{protect} built in to their definition in some
way.  Self-protected commands, and fragile commands with
\csx{protect}ion are only robust in a context where the \csx{protect}
mechanism is properly handled.  The body of an \csx{edef} definition
doesn't handle \csx{protect} properly, since \csx{edef} is a \TeX{}
primitive rather than a \LaTeX{} command.

This problem is resolved by a \LaTeX{} internal command
\csx{protected@edef}, which does the job of \csx{edef} while keeping the
\csx{protect} mechanism working.  There's a corresponding
\csx{protected@xdef} which does the job of \csx{xdef}.

Of course, these commands need to be tended carefully, since they're
% beware line break on next line
internal: see \Qref[question]{'@' in control sequence names}{Q-atsigns}.

\Question[Q-ltxcmds]{The definitions of \LaTeX{} commands}

There are several reasons to want to know the definitions of \LaTeX{}
commands: from the simplest ``idle curiosity'', to the pressing need
to patch something to make it ``work the way you want it''.  None of
these are \emph{pure} motives, but knowledge and expertise seldom
arrive through the purest of motives.

Using a \tex{} executable of some sort, the simple answer is to try
\csx{show}, in a run that is taking commands from the terminal:
\begin{quote}
\begin{verbatim}
*\makeatletter
*\show\protected@edef
> \protected@edef=macro:
->\let \@@protect \protect
  \let \protect \@unexpandable@protect
  \afterassignment \restore@protect \edef .
\end{verbatim}
\end{quote}
(I've rearranged the output there, from the rather confused version
\TeX{} itself produces.)

We may perhaps, now, wonder about \csx{@unexpandable@protect}:
\begin{quote}
\begin{verbatim}
*\show\@unexpandable@protect
> \@unexpandable@protect=macro:
->\noexpand \protect \noexpand .
\end{verbatim}
\end{quote}
and we're starting to see how one part of the \csx{protect}ion
mechanism works (one can probably fairly safely guess what
\csx{restore@protect} does).

Many kernel commands are declared robust:
\begin{quote}
\begin{verbatim}
*\show\texttt
> \texttt=macro:
->\protect \texttt  .
\end{verbatim}
\end{quote}
so that \csx{show} isn't much help.  Define a command \csx{pshow} as
shown below, and simply execute the command to find its definition:
\begin{quote}
\begin{verbatim}
*\def\pshow#1{{\let\protect\show #1}}
*\pshow\texttt
> \texttt =\long macro:
#1->\ifmmode \nfss@text {\ttfamily #1}%
    \else \hmode@bgroup \text@command {#1}%
          \ttfamily \check@icl #1\check@icr
    \expandafter \egroup \fi .
\end{verbatim}
\end{quote}
Note that the command name that is protected is the `base' command,
with a space appended.  This is cryptically visible, in a couple of
places above.  (Again, the output has been sanitised.)

The command \ProgName{texdef} (or \ProgName{latexdef}~--- the same
command with a different name) will do all that for you and return the
results slightly more tidily than \latex{} itself manages.  For
example:
\begin{quote}
\begin{verbatim}
latexdef texttt
\end{verbatim}
\end{quote}
gives:
\begin{quote}
\begin{verbatim}
$ latexdef texttt

\texttt:
macro:->\protect \texttt  

\texttt :
#1->\ifmmode \nfss@text {\ttfamily #1}%
    \else \hmode@bgroup \text@command {#1}%
          \ttfamily \check@icl #1\check@icr
    \expandafter \egroup \fi .
\end{verbatim}
\end{quote}
(again, the output has been sanitised~--- but we see that
\ProgName{latexdef} has useful `intelligence' in it, as it has spotted
and dealt with the \csx{protect}.)

If one has a malleable text editor, the same investigation may be
conducted by examining the file \File{latex.ltx} (which is usually to
be found, in a \acro{TDS} system, in directory \path{tex/latex/base}).

In fact, \File{latex.ltx} is the product of a \ProgName{docstrip}
process on a large number of \Qref*{\extension{dtx} files}{Q-dtx}, and
you can refer to those instead.  The \LaTeX{} distribution includes a file
\File{source2e.tex}, and most systems retain it, again in
\path{tex/latex/base}.  \File{Source2e.tex} may be processed to
provide a complete source listing of the \LaTeX{} kernel (in fact the
process isn't entirely straightforward, but the file produces messages
advising you what to do).  The result is a huge document, with a
line-number index of control sequences the entire kernel and a
separate index of changes recorded in each of the files since the
\LaTeX{} team took over.

The printed kernel is a nice thing to have, but it's unwieldy and sits
on my shelves, seldom used.  One problem is that the comments are
patchy: the different modules range from well and lucidly documented,
through modules documented only through an automatic process that
converted the documentation of the source of \LaTeXo{}, to modules
that hardly had any useful documentation even in the \LaTeXo{} original.

In fact, each kernel module \extension{dtx} file will process separately
through \LaTeX{}, so you don't have to work with the whole of
\File{source2e}.  You can easily determine which module defines the
macro you're interested in: use your ``malleable text editor'' to find
the definition in \File{latex.ltx}; then search backwards from that
point for a line that starts % ! line break
\texttt{\textpercent\textpercent\textpercent\ From File:}~--- that line
tells you which \extension{dtx} file contains the definition you are interested
in.  Doing this for \csx{protected@edef}, we find:
\begin{quote}
\begin{verbatim}
%%% From File: ltdefns.dtx
\end{verbatim}
\end{quote}
When we come to look at it, \File{ltdefns.dtx} proves to contain
quite a dissertation on the methods of handling \csx{protect}ion; it
also contains some automatically-converted \LaTeXo{} documentation.

And of course, the kernel isn't all of \LaTeX{}: your command may be
defined in one of \LaTeX{}'s class or package files.  For example, we
find a definition of \csx{thebibliography} in \Class{article}, but
there's no \File{article.dtx}.  Some such files are generated from
parts of the kernel, some from other files in the distribution.  You
find which by looking at the start of the file: in \File{article.cls},
we find:
\begin{quote}
\begin{verbatim}
%% This is file `article.cls',
%% generated with the docstrip utility.
%%
%% The original source files were:
%%
%% classes.dtx  (with options: `article')
\end{verbatim}
\end{quote}
so we need to format \File{classes.dtx} to see the definition in
context.

All these .dtx files are on \acro{CTAN} as part of the main \LaTeX{}
distribution.
\begin{ctanrefs}
\item[\nothtml{\rmfamily}\LaTeX{} distribution]\CTANref{latex}
\item[texdef, \nothtml{{\rmfamily aka }}latexdef]\CTANref{texdef}
\end{ctanrefs}
\LastEdit{2011-03-17}

\Question[Q-oarglikesect]{Optional arguments like \csx{section}}

Optional arguments, in macros defined using \csx{newcommand}, don't
quite work like the optional argument to \csx{section}.  The default
value of \csx{section}'s optional argument is the value of the
mandatory argument, but \csx{newcommand} requires that you `know' the
value of the default beforehand.

The requisite trick is to use a macro in the optional argument:
\begin{quote}
\begin{verbatim}
\documentclass{article}
\newcommand\thing[2][\DefaultOpt]{%
  \def\DefaultOpt{#2}%
  optional arg: #1,  mandatory arg: #2%
}
\begin{document}
\thing{manda}% #1=#2

\thing[opti]{manda}% #1="opti"
\end{document}
\end{verbatim}
\end{quote}
\LaTeX{} itself has a trickier (but less readily understandable)
method, using a macro \csx{@dblarg}; inside \LaTeX{}, the example
above would have been programmed:
\begin{quote}
\begin{verbatim}
\newcommand\thing{\@dblarg\@thing}
\newcommand\@thing[2][\@error]{%
  optional arg: #1,  mandatory arg: #2%
}
\end{verbatim}
\end{quote}
In that code, \csx{@thing} is only ever called with an optional and a
mandatory argument; if the default from the \csx{newcommand} is
invoked, a bug in user code has bitten\dots{}

\Question[Q-twooptarg]{More than one optional argument}

If you've already read % ! line break
``\Qref*[question]{breaking the 9-argument limit}{Q-moren9}''.
you can probably guess the ``simple'' solution to this problem:
command relaying.

\LaTeX{} allows commands with a single optional argument thus:
\begin{quote}
\begin{verbatim}
  \newcommand{\blah}[1][Default]{...}
\end{verbatim}
\end{quote}

You may legally call such a command either with its optional argument
present, as
\cmdinvoke{blah}[nonDefault] or without, as \csx{blah}; in the latter
case, the code of \csx{blah} will have an argument of |Default|.

To define a command with two optional arguments, we use the relaying
technique, as follows:
\begin{quote}
\begin{verbatim}
\newcommand{\blah}[1][Default1]{%
  \def\ArgI{{#1}}%
  \BlahRelay
}
\newcommand\BlahRelay[1][Default2]{%
  % the first optional argument is now in
  % \ArgI
  % the second is in #1
  ...%
}
\end{verbatim}
\end{quote}
Of course, \csx{BlahRelay} may have as many mandatory arguments as are
allowed, after allowance for the one taken up with its own
optional argument~--- that is, 8.

Variants of \csx{newcommand} (and friends), with names like
\csx{newcommandtwoopt}, are available in the \Package{twoopt} package.
However, if you can, it's probably better to learn to write the commands
yourself, just to see why they're not even a good idea from the
programming point of view.

A command with two optional arguments strains the limit of what's
sensible: obviously you can extend the technique to provide as many
optional arguments as your fevered imagination can summon.  However,
see the comments on the use of the \Package{keyval} package, in 
``\Qref*[question]{breaking the 9-argument limit}{Q-moren9}'',
which offers an alternative way forward.

If you must, however, consider the \Package{optparams} or
\Package{xargs} packages.  \Package{Optparams}
provides a \csx{optparams} command that you use as an intermediate in
defining commands with up to nine optional arguments.  The
documentation shows examples of commands with four optional arguments
(and this from an author who has his own key-value package!).

The \Package{xargs} package uses a key-value package
(\Package{xkeyval}) to \emph{define} the layout of the optional
arguments.  Thus
\begin{quote}
\begin{verbatim}
\usepackage{xargs}
...
\newcommandx{\foo}[3][1=1, 3=n]{...}
\end{verbatim}
\end{quote}
defines a command \csx{foo} that has an optional first argument
(default 1), a mandatory second argument, and an optional third
argument (default n).

An alternative approach is offered by Scott Pakin's
\ProgName{newcommand} program, which takes a command name and a
definition of a set of command arguments (in a fairly
readily-understood language), and emits \AllTeX{} macros which enable
the command to be defined.  The command requires that a
\ProgName{Python} interpreter (etc.\@) be installed on your computer.
\begin{ctanrefs}
\item[newcommand.py]\CTANref{newcommand}
\item[optparams.sty]Distributed as part of \CTANref{sauerj}[optparams]
\item[twoopt.sty]Distributed as part of \CTANref{oberdiek}[twoopt]
\item[xargs.sty]\CTANref{xargs}
\item[xkeyval.sty]\CTANref{xkeyval}
\end{ctanrefs}

\Question[Q-cmdstar]{Commands defined with * options}

\LaTeX{} commands commonly have ``versions'' defined with an asterisk
tagged onto their name: for example \csx{newcommand} and
\csx{newcommand*} (the former defines a \csx{long} version of the
command).

The simple-minded way for a user to write such a command involves use
of the \Package{ifthen} package:
\begin{wideversion}
\begin{quote}
\begin{verbatim}
\newcommand{\mycommand}[1]{\ifthenelse{\equal{#1}{*}}%
  {\mycommandStar}%
  {\mycommandNoStar{#1}}%
}
\newcommand{\mycommandStar}{starred version}
\newcommand{\mycommandNoStar}[1]{normal version}
\end{verbatim}
\end{quote}
\end{wideversion}
\begin{narrowversion}
\begin{quote}
\begin{verbatim}
\newcommand{\mycommand}[1]{%
  \ifthenelse{\equal{#1}{*}}%
    {\mycommandStar}%
    {\mycommandNoStar{#1}}%
}
\newcommand{\mycommandStar}%
                {starred version}
\newcommand{\mycommandNoStar}[1]%
                 {normal version}
\end{verbatim}
\end{quote}
\end{narrowversion}
This does the trick, for sufficiently simple commands, but it has
various tiresome failure modes, and it requires \csx{mycommandnostar}
to take an argument.

Of course, the \LaTeX{} kernel has something slicker than this:
\begin{quote}
\begin{wideversion}
\begin{verbatim}
\newcommand{\mycommand}{\@ifstar
                     \mycommandStar%
                     \mycommandNoStar%
}
\newcommand{\mycommandStar}[2]{starred version}
\newcommand{\mycommandNoStar}[1]{normal version}
\end{verbatim}
\end{wideversion}
\begin{narrowversion}
\begin{verbatim}
\newcommand{\mycommand}{\@ifstar
                     \mycommandStar%
                     \mycommandNoStar%
}
\newcommand{\mycommandStar}[2]{starred version}
\newcommand{\mycommandNoStar}[1]{normal version}
\end{verbatim}
\end{narrowversion}
\end{quote}
(Note that arguments to \csx{mycommandStar} and \csx{mycommandNoStar}
are independent~--- either can have their own arguments, unconstrained
by the technique we're using, unlike the trick described above.)
The \csx{@ifstar} trick is all very well, is fast and efficient, but
it requires the definition to be % ! line break
\Qref*{\csx{makeatletter} protected}{Q-atsigns}.

A pleasing alternative is the \Package{suffix} package.  This elegant
piece of code allows you to define variants of your commands:
\begin{narrowversion}
\begin{quote}
\begin{verbatim}
\newcommand\mycommand{normal version}
\WithSuffix\newcommand\mycommand*%
                     {starred version}
\end{verbatim}
\end{quote}
\end{narrowversion}
\begin{wideversion}
\begin{quote}
\begin{verbatim}
\newcommand\mycommand{normal version}
\WithSuffix\newcommand\mycommand*{starred version}
\end{verbatim}
\end{quote}
\end{wideversion}
The package needs \Qref*{\elatex{}}{Q-etex}, but any new enough
distribution defines \LaTeX{} as \elatex{} by default.  Command
arguments may be specified in the normal way, in both command
definitions (after the ``\texttt{*}'' in the \csx{WithSuffix}
version).  You can also use the \TeX{} primitive commands, creating a
definition like:
\begin{quote}
\begin{verbatim}
\WithSuffix\gdef\mycommand*{starred version}
\end{verbatim}
\end{quote}
\begin{ctanrefs}
\item[ifthen.sty]Part of the \LaTeX{} distribution
\item[suffix.sty]Distributed as part of \CTANref{bigfoot}[suffix]
\end{ctanrefs}

\nothtml{\hrule height 0pt \nobreak\vskip0pt plus2.5in\vskip 0pt\relax}
\Question[Q-ltxabbrv]{\LaTeX{} internal ``abbreviations'', etc.}

In the deeps of time, when \TeX{} first happened, computers had
extremely limited memory, and were (by today's standards) painfully
slow.  When \LaTeX{} came along, things weren't much better, and even
when \LaTeXe{} appeared, there was a strong imperative to save memory
space (and to a lesser extent) \acro{CPU} time.

From the very earliest days, Knuth used shortcut macros to speed
things up.  \LaTeX{}, over the years, has extended Knuth's list by a
substantial amount.  An interesting feature  of the ``abbreviations'' is
that on paper, they may look longer than the thing they stand for;
however, to \AllTeX{} they \emph{feel} smaller\dots{}

The table at the end of this answer lists the commonest of these
``abbreviations''.  It is not complete; as always, if the table
doesn't help, try the \LaTeX{} source.  The table lists each
abbreviation's \emph{name} and its \emph{value}, which provide most of
what a user needs to know.  The table also lists the abbreviation's
\emph{type}, which is a trickier concept: if you need to know, the
only real confusion is that the abbreviations labelled `defn' are
defined using an \csx{\emph{xxxx}def} command.

\begin{tabular}{lll}
Name \tbamp Type \tbamp Value \tbeol
\tbhline
\csx{m@ne} \tbamp count \tbamp \ensuremath{-1} \tbeol
\csx{p@}  \tbamp dimen \tbamp 1pt \tbeol
\csx{z@}  \tbamp dimen \tbamp 0pt \tbeol
\csx{z@skip} \tbamp skip \tbamp 0pt plus 0pt minus 0pt \tbeol
\tbhline
\csx{@ne} \tbamp defn \tbamp 1 \tbeol
\csx{tw@} \tbamp defn \tbamp 2\tbeol
\csx{thr@@} \tbamp defn \tbamp 3 \tbeol
\csx{sixt@@n} \tbamp defn \tbamp 16 \tbeol
\csx{@cclv} \tbamp defn \tbamp 255 \tbeol
\csx{@cclvi} \tbamp defn \tbamp 256 \tbeol
\csx{@m} \tbamp defn \tbamp 1000 \tbeol
\csx{@M} \tbamp defn \tbamp 10000 \tbeol
\csx{@MM} \tbamp defn \tbamp 20000 \tbeol
\tbhline
\csx{@vpt} \tbamp macro \tbamp 5 \tbeol
\csx{@vipt} \tbamp macro \tbamp 6 \tbeol
\csx{@viipt} \tbamp macro \tbamp 7 \tbeol
\csx{@viiipt} \tbamp macro \tbamp 8 \tbeol
\csx{@ixpt} \tbamp macro \tbamp 9 \tbeol
\csx{@xpt} \tbamp macro \tbamp 10 \tbeol
\csx{@xipt} \tbamp macro \tbamp 10.95 \tbeol
\csx{@xiipt} \tbamp macro \tbamp 12 \tbeol
\csx{@xivpt} \tbamp macro \tbamp 14.4 \tbeol
\csx{@xviipt} \tbamp macro \tbamp 17.28 \tbeol
\csx{@xxpt} \tbamp macro \tbamp 20.74 \tbeol
\csx{@xxvpt} \tbamp macro \tbamp 24.88 \tbeol
\tbhline
\csx{@plus} \tbamp macro \tbamp ``\texttt{plus}'' \tbeol
\csx{@minus} \tbamp macro \tbamp ``\texttt{minus}'' \tbeol
%\csx{hb@xt@} \tbamp macro \tbamp ``\csx{hbox} \texttt{to}''
\end{tabular}

\Question[Q-ltxhash]{Defining \LaTeX{} commands within other commands}

\LaTeX{} command definition is significantly different from the \TeX{}
primitive form discussed in an % ! line break
\Qref*[\htmlonly]{earlier question}{Q-hash} about definitions within
macros.

In most ways, the \LaTeX{} situation is simpler (at least in part
because it imposes more restrictions on the user); however, defining a
command within a command still requires some care.

The earlier question said you have to double the |#| signs in command
definitions: in fact, the same rule holds, except that \LaTeX{}
already takes care of some of the issues, by generating argument lists
for you.

The basic problem is that:
\begin{quote}
\begin{verbatim}
\newcommand{\abc}[1]{joy, oh #1!%
  \newcommand{\ghi}[1]{gloom, oh #1!}%
}
\end{verbatim}
\end{quote}
followed by a call:
\begin{quote}
\begin{verbatim}
\cmdinvoke{abc}{joy}
\end{verbatim}
\end{quote}
typesets ``joy, oh joy!'', but defines a command \csx{ghi} that takes
one parameter, which it ignores; \cmdinvoke{ghi}{gloom} will expand to
``gloom, oh joy!'', which is presumably not what was expected.

And (as you will probably guess, if you've read the earlier question)
the definition:
\begin{quote}
\begin{verbatim}
\newcommand{\abc}[1]{joy, oh #1!%
  \newcommand{\ghi}[1]{gloom, oh ##1!}%
}
\end{verbatim}
\end{quote}
does what is required, and \cmdinvoke{ghi}{gloom} will expand to
``gloom, oh gloom!'', whatever the argument to \csx{abc}.

The doubling is needed whether or not the enclosing command has an
argument, so:
\begin{quote}
\begin{verbatim}
\newcommand{\abc}{joy, oh joy!%
  \newcommand{\ghi}[1]{gloom, oh ##1!}%
}
\end{verbatim}
\end{quote}
is needed to produce a replica of the \csx{ghi} we defined earlier.

\Question[Q-printvar]{How to print contents of variables?}
\keywords{typeout, print variables, showthe}

It is often useful to print out the values of variables in the log
file or on the terminal.  Three possible ways to print out the
contents of \csx{textheight} variable are:
\begin{enumerate}
\item \csx{showthe}\csx{textheight}
\item \cmdinvoke{message}{The text height is \csx{the}\csx{textheight}}
\item \cmdinvoke{typeout}{The text height is \csx{the}\csx{textheight}}
\end{enumerate}
These techniques use the \TeX{} primitives \csx{the} (which provides
the value of a variable), \csx{showthe} (print a variable to the
terminal and the log, on a line of its own), and \csx{message}, which
interpolates something into the log.  The command \csx{typeout} is
\LaTeX{}'s general message output mechanism.

In each case, the variable's value is printed as a number of points.

To typeset the value of \csx{textheight}, just
\csx{the}\csx{textheight} is enough, but a more flexible alternative is
to use the \Package{printlen} package.  \Package{Printlen} allows you
to choose the units in which you print a variable; this is useful,
given that the most ordinary people don't think in points
(particularly Knuth's points, of which there are 72.27 to the inch).

So, using \Package{printlen}, we could say:
\begin{quote}
\begin{verbatim}
\newlength{\foo}
\setlength{\foo}{12pt}
\verb|\foo| is \printlength{\foo}
\end{verbatim}
\end{quote}
and get:
\begin{quote}
\verb|\foo| is 12pt
\end{quote}
while, if we say:
\begin{quote}
\begin{verbatim}
\newlength{\foo}
\setlength{\foo}{12pt}
\uselengthunit{mm}
\verb|\foo| is \printlength{\foo}
\end{verbatim}
\end{quote}
we get:
\begin{quote}
\verb|\foo| is 4.21747mm
\end{quote}
\begin{ctanrefs}
\item[printlen.sty]\CTANref{printlen}
\end{ctanrefs}
\LastEdit*{2011-09-08}

\Question[Q-labelcount]{Using labels as counter values}

Labels are tempting sources of `numbers'~--- their most common use,
after all, is simply to typeset a number.  However, their seeming
simplicity is deceptive; the packages \Package{babel} and
\Package{hyperref}, at least, fiddle with the definition of
\csx{ref} and \csx{pageref} in ways that make
\begin{quote}
\begin{verbatim}
\setcounter{foo}{\ref{bar}}
\end{verbatim}
\end{quote}
(etc.\@) not work; thus the technique may not be relied upon.

The solution is to use the \Package{refcount} package (incidentally,
by the author of \Package{hyperref}).  The package provides four
commands, all similar to:
\begin{quote}
\begin{verbatim}
\usepackage{refcount}
...
\label{bar}
...
\setcounterref{foo}{bar}
\end{verbatim}
\end{quote}
(the other three are \csx{addtocounterref}, \csx{setcounterpageref}
and \csx{addtocounterpageref}).

The package also provides a command
\cmdinvoke*{getrefnumber}{label-name} that may be used where a
`number' value is needed.  For example:
\begin{quote}
\begin{verbatim}
... \footnote{foo bar ...\label{foofoot}}
...
\footnotemark[\getrefnumber{foofoot}]
\end{verbatim}
\end{quote}
which gives you a second footnote mark reference the the footnote.
(There is also a command \csx{getpagerefnumber}, of course).

The commands could be used by one determined not to use
\Package{changepage} to determine whether % ! line break
\Qref*{the current page is odd}{Q-oddpage}, but it's probably no more
trouble to use the fully-developed tool in this case.
\begin{ctanrefs}
\item[refount.sty]Distributed as part of \CTANref{oberdiek}
\end{ctanrefs}
\LastEdit*{2011-09-08}

\subsection{\LaTeX{} macro programming}

\Question[Q-fixnam]{How to change \LaTeX{}'s ``fixed names''}

\LaTeX{} document classes define several typographic operations that
need `canned text' (text not supplied by the user).  In the earliest
days of \LaTeXo{} these bits of text were built in to the body of
\LaTeX{}'s macros and were rather difficult to change, but ``fixed
name'' macros were introduced for the benefit of those wishing to use
\LaTeX{} in languages other than English.
For example, the special section produced by the \csx{tableofcontents}
command is always called \csx{contentsname} (or rather, what
\csx{contentsname} is defined to mean).
Changing the canned text is now one of the easiest customisations a
user can do to \LaTeX{}.

The canned text macros are all of the form
\csx{\meta{thing}name}, and changing them is simplicity
itself.  Put:
\begin{quote}
\cmdinvoke{renewcommand}{\csx{\meta{thing}name}}{Res minor}
\end{quote}
in the preamble of your document, and the job is done.
(However, beware of the \Package{babel} package, which requires you to
use a different mechanism: be sure to check
% beware line wrap
\Qref[question]{changing \Package{babel} names}{Q-latexwords} if
you're using it.)

The names that are defined in the standard \LaTeX{} classes (and the
\Package{makeidx} package) are listed
below.  Some of the names are only defined in a subset of the classes
(and the \Class{letter} class has a set of names all of its own);
the list shows the specialisation of each name, where appropriate.

\nothtml{\noindent}\begin{tabular}{@{}ll}
\csx{abstractname} \tbamp Abstract\tbeol
\csx{alsoname} \tbamp see also (\Package{makeidx} package)\tbeol
\csx{appendixname} \tbamp Appendix\tbeol
\csx{bibname} \tbamp Bibliography (\Class{report},\Class{book})\tbeol
\csx{ccname} \tbamp cc (\Class{letter})\tbeol
\csx{chaptername} \tbamp Chapter (\Class{report},\Class{book})\tbeol
\csx{contentsname} \tbamp Contents\tbeol
\csx{enclname} \tbamp encl (\Class{letter})\tbeol
\csx{figurename} \tbamp Figure (for captions)\tbeol
\csx{headtoname} \tbamp To (\Class{letter})\tbeol
\csx{indexname} \tbamp Index\tbeol
\csx{listfigurename} \tbamp List of Figures\tbeol
\csx{listtablename} \tbamp List of Tables\tbeol
\csx{pagename} \tbamp Page (\Class{letter})\tbeol
\csx{partname} \tbamp Part\tbeol
\csx{refname} \tbamp References (\Class{article})\tbeol
\csx{seename} \tbamp see (\Package{makeidx} package)\tbeol
\csx{tablename} \tbamp Table (for caption)
\end{tabular}

\Question[Q-latexwords]{Changing the words \Package{babel} uses}

\LaTeX{} uses symbolic names for many of the automatically-generated
text it produces (special-purpose section headings, captions, etc.).
As noted in \Qref[question]{``\LaTeX{} fixed names''}{Q-fixnam} (which
includes a list of the names themselves),
this enables the user to change the
names used by the standard classes, which is particularly useful if
the document is being prepared in some language other than \LaTeX{}'s
default English.  So, for example, a Danish author may wish that her
table of contents was called ``Indholdsfortegnelse'', and so 
would expect to place a command
\begin{verbatim}
\renewcommand{\contentsname}%
    {Indholdsfortegnelse}
\end{verbatim}
in the preamble of her document.

However, it's natural for a user of a non-English language to use
\Package{babel}, because it offers many conveniences and typesetting
niceties for those preparing documents in those languages.  In
particular, when \Package{babel} is selecting a new language, it
ensures that \LaTeX{}'s symbolic names are translated appropriately
for the language in question.  Unfortunately, \Package{babel}'s choice
of names isn't always to everyone's choice, and there is still a need
for a mechanism to replace the `standard' names.

Whenever a new language is selected, \Package{babel} resets all the
names to the settings for that language.  In particular,
\Package{babel} selects the document's main language when
\cmdinvoke{begin}{document} is executed, which immediately destroys
any changes to these symbolic names made in the prologue of a document
that uses \Package{babel}. 

Therefore, babel defines a command to enable users to change the
definitions of the symbolic names, on a per-language basis:
\csx{addto}\csx{captions}\texttt{\meta{language}} is the thing
(\texttt{\meta{language}} being the language option you gave to
\Package{babel} in the first place).  For example:
\begin{verbatim}
\addto\captionsdanish{%
  \renewcommand{\contentsname}%
    {Indholdsfortegnelse}%
}
\end{verbatim}

\Question[Q-running-nos]{Running equation, figure and table numbering}

Many \LaTeX{} classes (including the standard \Class{book} class)
number things per chapter; so figures in chapter 1 are numbered 1.1,
1.2, and so on.  Sometimes this is not appropriate for the user's
needs.

Short of rewriting the whole class, one may use the \Package{chngcntr}
package, which provides commands \csx{counterwithin} (which
establishes this nested numbering relationship) and
\csx{counterwithout} (which undoes it).

So if you have figures numbered by chapter as 1.1, 1.2, 2.1, \dots{},
the command 
\begin{quote}
\begin{verbatim}
\counterwithout{figure}{chapter}
\end{verbatim}
\end{quote}
will convert them to figures 1, 2, 3, \dots{}.  (Note that the command
has also removed the chapter number from the counter's definition.)

More elaborate use could change things numbered per section to things
numbered per chapter:
\begin{quote}
\begin{verbatim}
\counterwithout{equation}{section}
\counterwithin{equation}{chapter}
\end{verbatim}
\end{quote}
(assuming there was a class that did such a thing in the first place...)

The \Package{chngcntr} approach doesn't involve much programming, and
the enthusiastic \LaTeX{} programmer might choose to try the technique
that we had to use before the advent of \Package{chngcntr}.  Each of
the packages \Package{removefr} and \Package{remreset} defines a
\csx{@removefromreset} command, and having included the package one
writes something like:
\begin{quote}
\begin{verbatim}
\makeatletter
\@removefromreset{figure}{chapter}
\makeatother
\end{verbatim}
\end{quote}
and the automatic renumbering stops.  You may then need to redefine the
way in which the figure number (in this case) is printed:
\begin{quote}
\begin{verbatim}
\makeatletter
\renewcommand{\thefigure}{\@arabic\c@figure}
\makeatother
\end{verbatim}
\end{quote}
(remember to do the whole job, for every counter you want to
manipulate, within \csx{makeatletter} \dots{}\@ \csx{makeatother}).

This technique, too, may be used to change where in a multilevel
structure a counter is reset.  Suppose your class numbers figures as
\meta{chapter}.\meta{section}.\meta{figure}, and you want figures
numbered per chapter, try:
\begin{quote}
\begin{wideversion}
\begin{verbatim}
\makeatletter
\@removefromreset{figure}{section}
\@addtoreset{figure}{chapter}
\renewcommand{\thefigure}{\thechapter.\@arabic\c@figure}
\makeatother
\end{verbatim}
\end{wideversion}
\begin{narrowversion}
\begin{verbatim}
\makeatletter
\@removefromreset{figure}{section}
\@addtoreset{figure}{chapter}
\renewcommand{\thefigure}%
             {\thechapter.\@arabic\c@figure}
\makeatother
\end{verbatim}
\end{narrowversion}
\end{quote}
(the command \csx{@addtoreset} is a part of \LaTeX{} itself).
\begin{ctanrefs}
\item[chngcntr.sty]\CTANref{chngcntr}
\item[memoir.cls]\CTANref{memoir}
\item[removefr.tex]\CTANref{removefr} (note, this is constructed as a
  ``fragment'' for use within other packages: load by
  \cmdinvoke{input}{removefr})
\item[remreset.sty]Distributed as part of \CTANref{carlisle}[remreset]
\end{ctanrefs}

\Question[Q-labelctr]{Making labels from a counter}

Suppose we have a \LaTeX{} counter, which we've defined with
\cmdinvoke{newcounter}{foo}.  We can increment the value of the counter
by \cmdinvoke{addtocounter}{foo}{1}, but that's pretty clunky for an
operation that happens so often \dots{}~so there's a command
\cmdinvoke{stepcounter}{foo} that does this special case of
increasing-by-one.

There's an internal \LaTeX{} variable, the ``current label'', that
remembers the last `labellable' thing that \LaTeX{} has processed.
You could (if you were to insist) set that value by the relevant
\TeX{} command (having taken the necessary precautions to ensure that
the internal command worked)~--- but it's not necessary.  If, instead
of either of the stepping methods above, you say
\cmdinvoke{refstepcounter}{foo}, the internal variable is set to the
new value, and (until something else comes along), \csx{label} will
refer to the counter.

\Question[Q-oddpage]{Finding if you're on an odd or an even page}

\Qref[Question]{Another question}{Q-marginparside} discusses the issue
of getting \csx{marginpar} commands to put their output in the correct
margin of two-sided documents.  This is an example of the general
problem of knowing where a particular bit of text lies: the output
routine is asynchronous, and \AllTeX{} will usually process quite a
bit of the ``next'' page before deciding to output any page.  As a
result, the |page| counter (known internally in \LaTeX{} as
\csx{c@page}) is normally only reliable when you're actually \emph{in}
the output routine.

The solution is to use some version of the \csx{label} mechanism to
determine which side of the page you're on; the value of the page
counter that appears in a \csx{pageref} command has been inserted in
the course of the output routine, and is therefore safe.

However, \csx{pageref} itself isn't reliable: one might hope that
\begin{quote}
\begin{verbatim}
\ifthenelse{\isodd{\pageref{foo}}}{odd}{even}
\end{verbatim}
\end{quote}
would do the necessary, but both the \Package{babel} and
\Package{hyperref} packages have been known to interfere with the
output of \csx{pageref}; be careful!

The \Package{changepage} package needs to provide this functionality
for its own use, and therefore provides a command \csx{checkoddpage};
this sets a private-use `label', and the page reference part of that
label is then examined (in a \Package{hyperref}-safe way) to set a
conditional \csx{ifoddpage} true if the command was issued on an odd
page.  (The \Class{memoir} class has the same command.)  \latex{}
users who are unfamiliar with \tex{}'s \csx{if...} commands may use
the \Package{ifthen} package:
\begin{wideversion}
\begin{quote}
\begin{verbatim}
\usepackage{ifthen,changepage}
...
\checkoddpage
\ifthenelse{\boolean{oddpage}}{<odd page stuff>}{<even page stuff>}
\end{verbatim}
\end{quote}
\end{wideversion}
\begin{narrowversion}
\begin{quote}
\begin{verbatim}
\usepackage{ifthen,changepage}
...
\checkoddpage
\ifthenelse{\boolean{oddpage}}%
    {<odd page stuff>}%
    {<even page stuff>}
\end{verbatim}
\end{quote}
\end{narrowversion}

Of course, the `label' contributes to \LaTeX{}'s ``Rerun to get
cross-references right'' error messages\dots{}

The Koma-Script classes have an \environment{addmargin*} environment
that also provides the sorts of facilities that the \Package{changepage}
offers.  Koma-Script's supporting command:
\begin{quote}
\cmdinvoke{ifthispageodd}{<true>}{<false>}
\end{quote}
executes different things depending on the page number.
\begin{ctanrefs}
\item[changepage.sty]\CTANref{changepage}
\item[ifthen.sty]Part of the \latex{} distribution: \CTANref{latex}
\item[\nothtml{\rmfamily}KOMA script bundle]\CTANref{koma-script}
\item[memoir.cls]\CTANref{memoir}
\end{ctanrefs}

\Question[Q-labelformat]{How to change the format of labels}

By default, when a label is created, it takes on the appearance of the
counter labelled, so the label appears as
\csx{the}\texttt{\meta{counter}}~--- what would be used if you
asked to typeset the counter in your text.  This isn't always what you
need: for example, if you have nested enumerated lists with the outer
numbered and the inner labelled with letters, one might expect to want
to refer to items in the inner list as ``2(c)''.   (Remember, you can
\nothtml{change the structure of list items~--- }%
\Qref{change the structure of list items}{Q-enumerate}.)
The change is of course
possible by explicit labelling of the parent and using that label to
construct the typeset result~--- something like
\begin{quote}
\begin{verbatim}
\ref{parent-item}(\ref{child-item})
\end{verbatim}
\end{quote}
which would be both tedious and error-prone.  What's more, it would be
undesirable, since you would be constructing a visual representation
which is inflexible (you couldn't change all the references to elements
of a list at one fell swoop).

\LaTeX{} in fact has a label-formatting command built into every label
definition; by default it's null, but it's available for the user to
program.  For any label \meta{counter} there's a \LaTeX{} internal
command \csx{p@}\meta{\texttt{counter}}; for example, a label definition
on an inner list item is supposedly done using the command
\cmdinvoke{p@enumii}{\csx{theenumii}}.  Unfortunately, the internal
workings of this aren't quite right, and you need to patch the
\csx{refstepcounter} command:
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
\renewcommand*\refstepcounter[1]{%
  \stepcounter{#1}%
  \protected@edef\@currentlabel{%
    \csname p@#1\expandafter\endcsname
      \csname the#1\endcsname
  }%
}
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
\renewcommand*\refstepcounter[1]{\stepcounter{#1}%
  \protected@edef\@currentlabel{%
    \csname p@#1\expandafter\endcsname
      \csname the#1\endcsname
  }%
}
\end{verbatim}
\end{wideversion}
\end{quote}
With the patch in place you can now, for example, change the labels on
all inner lists by adding the following code in your preamble:
\begin{quote}
\begin{verbatim}
\makeatletter
\renewcommand{\p@enumii}[1]{\theenumi(#1)}
\makeatother
\end{verbatim}
\end{quote}
This would make the labels for second-level enumerated lists appear as
``1(a)'' (and so on).  The analogous change works for any counter that
gets used in a \csx{label} command.

In fact, the \Package{fncylab} package does all the above (including
the patch to \LaTeX{} itself).  With the package, the code above is
(actually quite efficiently) rendered by the command:
\begin{quote}
\begin{verbatim}
\labelformat{enumii}{\theenumi(#1)}
\end{verbatim}
\end{quote}
In fact, the above example, which we can do in several different ways,
has been rendered obsolete by the appearance of the \Package{enumitem}
package, which is discussed in the answer about % ! line break
\Qref*{decorating enumeration lists}{Q-enumerate}.
\begin{ctanrefs}
\item[enumitem.sty]\CTANref{enumitem}
\item[fncylab.sty]\CTANref{fncylab}
\end{ctanrefs}

\Question[Q-seccntfmt]{Adjusting the presentation of section numbers}

The general issues of adjusting the appearance of section headings are
pretty complex, and are covered in % beware line breaks (2 lines)
\latexhtml{question}{the question on}
\Qref[\htmlonly]{the style of section headings}{Q-secthead}.

However, people regularly want merely to change the way the section
number appears in the heading, and some such people don't mind writing
out a few macros.  This answer is for \emph{them}.

The section number is typeset using the
\begin{dviversion}
  \LaTeX{} internal
\end{dviversion}
\begin{hyperversion}
  \Qref{\LaTeX{} internal}{Q-atsigns}
\end{hyperversion}
\csx{@seccntformat} command, which is given the ``name'' (section,
subsection, \dots{}) of the heading, as argument.  Ordinarily,
\csx{@seccntformat} 
merely outputs the section number, and then a \csx{quad} of space:
\begin{quote}
\begin{verbatim}
\renewcommand*{\@seccntformat}[1]{%
  \csname the#1\endcsname\quad
}
\end{verbatim}
\end{quote}
Suppose you want to put a stop after every section (subsection,
subsubsection, \dots{}) number, a trivial change may be implemented by
simple modification of the command:
\begin{quote}
\begin{verbatim}
\renewcommand*{\@seccntformat}[1]{%
  \csname the#1\endcsname.\quad
}
\end{verbatim}
\end{quote}
However, many people want to modify section numbers, but not
subsection numbers, or any of the others.  To do this, one must make
\csx{@seccntformat} switch according to its argument.  The following
technique for doing the job is slightly wasteful, but is efficient
enough for a relatively rare operation:
\begin{quote}
\begin{verbatim}
\renewcommand*{\@seccntformat}[1]{%
  \csname the#1\endcsname
  \csname adddot@#1\endcsname\quad
}
\end{verbatim}
\end{quote}
which uses a second-level command to provide the dot, if it has been
defined; otherwise it merely appends \csx{relax} (which does nothing
in this context).  The definition of the second-level command (the
version for the \texttt{section}, here) specifies what to put after a
section number, but it could be used to put anything after it:
\begin{quote}
\begin{verbatim}
\newcommand*{\adddot@section}{.}
\end{verbatim}
\end{quote}
Note that all the command definitions above are dealing in
\Qref*{\LaTeX{} internal commands}{Q-atsigns}, so the above
code should be in a package file, for preference.

The \Class{Koma-script} classes have different commands for specifying
changes to section number presentation: \csx{partformat},
\csx{chapterformat} and \csx{othersectionlevelsformat}, but otherwise
their facilities are similar to those of ``raw'' \LaTeX{}.
\begin{ctanrefs}
\item[\nothtml{\rmfamily}KOMA script bundle]\CTANref{koma-script}
\end{ctanrefs}

\Question[Q-spaftend]{There's a space added after my environment}

You've written your own environment \environment{env}, and it works
except that a space appears at the start of the first line of typeset
text after \cmdinvoke{end}{env}.  This doesn't happen with similar
\LaTeX{}-supplied environments.

You could impose the restriction that your users always put a
``\texttt{\textpercent}'' sign after the environment~\dots{}\nothtml{\@} but
\LaTeX{} environments don't require that, either.

The \LaTeX{} environments' ``secret'' is an internal flag which causes
the unwanted spaces to be ignored.  Fortunately, you don't have to use
the internal form: since 1996, \LaTeX{} has had a user command
\csx{ignorespacesafterend}, which sets the internal flag.

\Question[Q-labundef]{Finding if a label is undefined}

People seem to want to know (at run time) if a label is undefined (I
don't actually understand \emph{why}, particularly: it's a transient
state, and \LaTeX{} deals with it quite well).

A resolved label is simply a command:
\csx{r@}\texttt{\meta{label-name}}; determining if the label is set is
then simply a matter of detecting if the command exists.  The usual
\LaTeX{} internal way of doing this is to use the command
\csx{@ifundefined}:
\begin{quote}
  \cmdinvoke*{@ifundefined}{\textup{r@}label-name}{undef-cmds}{def-cmds}
\end{quote}
In which, \meta{label-name} is exactly what you would use in
a \csx{label} command, and the remaining two arguments are command
sequences to be used if the label is undefined
(\meta{undef-cmds}) or if it is defined
(\meta{def-cmds}).

Note that any command that incorporates \csx{@ifundefined} is naturally
fragile, so remember to create it with \csx{DeclareRobustCommand} or to
use it with \csx{protect} in a moving argument.

If you're into this game, you may well not care about \LaTeX{}'s
warning about undefined labels at the end of the document; however,
if you are, include the command \csx{G@refundefinedtrue} in
\meta{\texttt{undef-cmds}}.

And of course, remember you're dealing in internal commands, and pay
attention to the \Qref*{at-signs}{Q-atsigns}.

All the above can be avoided by using the \Package{labelcas} package:
it provides commands that enable you to switch according to the state
of a single label, or the states of a list of labels.  The package's
definition is a bit complicated, but the package itself is pretty
powerful.
\begin{ctanrefs}
\item[labelcas.sty]\CTANref{labelcas}
\end{ctanrefs}

\Question[Q-addtoreset]{Master and slave counters}

It's common to have things numbered ``per chapter'' (for example, in
the standard \Class{book} and \Class{report} classes, figures, tables
and footnotes are all numbered thus).  The process of resetting is
done automatically, when the ``master'' counter is stepped (when the
\csx{chapter} command that starts chapter \meta{n} happens, the
\texttt{chapter} counter is stepped, and all the dependent counters are set
to zero).

How would you do that for yourself?  You might want to number
algorithms per section, or corollaries per theorem, for example.  If
you're defining these things by hand, you declare the relationship
when you define the counter in the first place:
\begin{quote}
\cmdinvoke*{newcounter}{new-name}[master]
\end{quote}
says that every time counter \meta{master} is stepped, counter
\meta{new-name} will be reset.

But what if you have an uncooperative package, that defines the
objects for you, but doesn't provide a programmer interface to make
the counters behave as you want?

The \csx{newcounter} command uses a \LaTeX{} internal command, and you
can also use it:
\begin{quote}
\cmdinvoke*{@addtoreset}{new-name}{master}
\end{quote}
(but remember that it needs to be between \csx{makeatletter} and
\csx{makeatother}, or in a package of your own).

The \Package{chngcntr} package encapsulates the \csx{@addtoreset}
command into a command \csx{counterwithin}.  So:
\begin{quote}
\begin{verbatim}
\counterwithin*{corrollary}{theorem}
\end{verbatim}
\end{quote}
will make the corollary counter slave to theorem counters.  The
command without its asterisk:
\begin{quote}
\begin{verbatim}
\counterwithin{corrollary}{theorem}
\end{verbatim}
\end{quote}
will do the same, and also redefine \csx{thecorollary} as % line brk!
\meta{theorem number}.\meta{corollary number}, which is a good scheme
if you ever want to refer to the corollaries~--- there are potentially
many ``corollary~1'' in any document, so it's as well to tie its number
to the counter of the theorem it belongs to.  This is true of pretty
much any such counter-within-another; if you're not using the
\Package{chngcntr}, refer to the answer to % line break!
\Qref*{redefining counters' \csx{the-}commands}{Q-the-commands} for
the necessary techniques.

Note that the technique doesn't work if the master counter is |page|,
the number of the current page.  The |page| counter is stepped deep
inside the output routine, which usually gets called some time after
the text for the new page has started to appear: so special
techniques are required to deal with that.  One special case is dealt
with elsewhere: \Qref*{footnotes numbered per page}{Q-footnpp}.  One
of the techniques described there, using package \Package{perpage},
may be applied to any counter.  The command:
\begin{quote}
\cmdinvoke*{MakePerPage}{counter}
\end{quote}
will cause \meta{counter} to be reset for each page.  The package uses
a label-like mechanism, and may require more than one run of \LaTeX{}
to stabilise counter values~--- \LaTeX{} will generate the usual
warnings about labels changing.
\begin{ctanrefs}
\item[chngcntr.sty]\CTANref{chngcntr}
\item[perpage.sty]Distributed as part \CTANref{bigfoot}[perpage]
\end{ctanrefs}

\Question[Q-fontsize]{Fonts at arbitrary sizes}

Almost all fonts, nowadays, are provided with \LaTeX{} control
(\extension{fd}) files, so the temptation to risk the
\Qref*{problems of \csx{newfont}}{Q-newfont*} is usually easy to
resist.

However, one temptation remains, arising from the way that \LaTeX{}
restricts the sizes of fonts.  In fact, the restriction only
significantly applies to the default (Computer Modern) and the
Cork-encoded (\acro{T}1) EC fonts, but it is widely considered to be
anomalous, nowadays.  In recognition of this problem, there is a
package \Package{fix-cm} which will allow you to use the fonts, within
\LaTeX{}, at any size you choose.  If you're not using scaleable
versions of the fonts, most modern distributions will just generate an
appropriate bitmap for you.

So, suppose you want to produce a heading in Computer Modern Roman at
30 points, you might be tempted to write:
\begin{quote}
\begin{verbatim}
\newfont{\bigfont}{cmr10 at 30pt}
\begin{center}
  \bigfont Huge text
\end{center}
\end{verbatim}
\end{quote}
which will indeed work, but will actually produce a worse result than
\begin{quote}
\begin{verbatim}
\usepackage{fix-cm}
...
\begin{center}
  \fontsize{30}{36}\selectfont
  Huge text
\end{center}
\end{verbatim}
\end{quote}
Note that the \Package{fix-cm} package was not distributed until the
December 2003 edition of \LaTeX{}; if you have an older distribution,
the packages \Package{type1cm} (for \acro{CM} fonts) and
\Package{type1ec} (for \acro{EC} fonts) are available.

If \Package{fix-cm} doesn't do the job for you, try one of the other
two; \Package{fix-cm} has one or two omissions~--- fonts the \latex{}
team did not consider useful, or something; the CM dunhill fonts (as
CM, but with stretched ascenders) and the CM fibonacci (which is only
available in 8-point design size) are certainly missing.

A further alternative might be to switch to the
\Qref*{\FontName{Latin} \FontName{Modern} fonts}{Q-uselmfonts} (which
provide a close simulacrum of the \FontName{Computer}
\FontName{Modern} set); these fonts were scaleable from their first
distribution, and don't therefore need any such trick as the above.
\begin{ctanrefs}
\item[fix-cm.sty]Distributed as part of \CTANref{latex}[fix-cm] (an unpacked
  version is available at \CTANref{fix-cm})
\item[\nothtml{\rmfamily}\FontName{Latin} \FontName{Modern} fonts]\CTANref{lm}
\item[type1cm.sty]\CTANref{type1cm}
\item[type1ec.sty]\CTANref{type1ec} (the package is actually part of
  the \CTANref{cm-super} distribution, but it works happily in
  the absence of the scaled fonts)
\end{ctanrefs}
\LastEdit{2011-06-02}

\Question[Q-latexqual]{The quality of your \LaTeX{}}

The \Package{l2tabu} tutorial (mentioned in % ! line break
\Qref[question]{online introductions}{Q-man-latex}) is undoubtedly a
good read.

However, it's always difficult to remember the things you should
\emph{not} do, when there are so many things to remember that you
really must do: some automation is needed\dots{}.

The nicely-named \Package{nag} allows you to apply a configurable set
of checks to your document, as you run it through \LaTeX{}; you get
messages like:
\begin{quote}
\begin{wideversion}
\begin{verbatim}
Package nag Warning: Command \bf is an old LaTeX 2.09 command. 
(nag)                Use \bfseries or \textbf instead on input line 30.
\end{verbatim}
\end{wideversion}
\begin{narrowversion}
\begin{verbatim}
Package nag Warning: Command \bf is an old
                          LaTeX 2.09 command. 
(nag)                Use \bfseries or \textbf
                    instead on input line 30.
\end{verbatim}
\end{narrowversion}
\end{quote}
\begin{wideversion}
  (the package provides a demo file which contains most of the sorts
  of errors you might make~--- the example is one of them).
\end{wideversion}
\begin{narrowversion}
  (the error lines above represent two lines which have been wrapped;
  the package provides a demo file which contains most of the sorts of
  errors you might make~--- the example is one of them).
\end{narrowversion}

The \ProgName{lacheck} program analyses your source and comments on
it; its view of what is ``bad'' is \emph{very} subjective (the
documentation says), but it can be useful.

There's also a web site
\href{http://www.kohm.name/markus/texidate.html}{TeXidate}
which will do a static analysis of your document (unfortunately, you
have to paste your document source into a text window).  The site
doesn't seem as comprehensive as \Package{nag}, but it allows you to
download its script, which you can then juggle with to make it more
draconian.
\begin{ctanrefs}
\item[l2tabu]Browse \CTANref{l2tabu} for a copy in a language that's
  convenient for you
\item[lacheck]\CTANref{lacheck}
\item[nag.sty]\CTANref{nag}
\end{ctanrefs}