summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/FAQ-en/faq-mac-prog.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/FAQ-en/faq-mac-prog.tex')
-rw-r--r--Master/texmf-dist/doc/generic/FAQ-en/faq-mac-prog.tex2967
1 files changed, 2967 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/FAQ-en/faq-mac-prog.tex b/Master/texmf-dist/doc/generic/FAQ-en/faq-mac-prog.tex
new file mode 100644
index 00000000000..b6a6b69f721
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/FAQ-en/faq-mac-prog.tex
@@ -0,0 +1,2967 @@
+% $Id: faq-mac-prog.tex,v 1.3 2009/08/25 17:17:55 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}
+\renewcommand{\smooth}[2]{\mumble\OldSmooth{#1}{#2}}
+\end{verbatim}
+\end{wideversion}
+\begin{narrowversion}
+\begin{verbatim}
+\renewcommand{\smooth}[2]%
+ {\mumble\OldSmooth{#1}{#2}}
+\end{verbatim}
+\end{narrowversion}
+\end{quote}
+
+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[patch.doc]\CTANref{patch}
+\item[patchcommand.sty]\CTANref{patchcmd}
+\item[ted.sty]\CTANref{ted}
+\end{ctanrefs}
+
+\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 and use it as:
+\begin{quote}
+\begin{verbatim}
+\def\a#1{+++#1+++#1+++#1+++} \a{b}
+\end{verbatim}
+\end{quote}
+the macro expansion produces `+++b+++b+++b+++',
+which people find normal. However, if we now replace part of the macro:
+\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 people may find strange, even though it is just a
+specialisation of the example above. If you want \csx{a} to
+define \csx{x} to be a macro with one argument, you need to write:
+\begin{quote}
+\begin{verbatim}
+\def\a#1{+++#1+++\def\x ##1{xxx##1}}
+\end{verbatim}
+\end{quote}
+and \csx{a{b}} will expand to
+`+++b+++|\def\x #1{xxx#1}|', because |#1| gets replaced by `b'
+and |##| gets replaced by |#|.
+
+To nest a definition inside a definition inside a definition then
+you need |####1|, as at each stage |##| is replaced by
+|#|. 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}
+\end{ctanrefs}
+
+\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 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.
+
+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. At Joseph's suggestion, discussion of his \Package{keys3}
+package, which is designed for use with the experimental \LaTeX{}3,
+has been omitted.
+\begin{ctanrefs}
+\item[keyval.sty]Distributed as part of \CTANref{graphics}
+\item[kvoptions.sty]Distributed as part of \CTANref{oberdiek}
+\item[kvsetkeys.sty]Distributed as part of \CTANref{oberdiek}
+\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}
+
+\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):
+|\catcode`_=\active|.
+
+Any character could, in principle, be activated this way and defined
+as a macro (\csx{def}\texttt{\_\{}\csx{\_}\texttt{\}}~--- the simple answer to
+% beware line break
+\Qref[question]{using underscores}{Q-underscore}), but 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 ``|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 ``|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 ``|\def z|'', ``|z|'' is no longer interpreted as
+a letter; the space is therefore not necessary~--- ``|\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 |_| 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]Distributed as part of the source of \LaTeX{}, \CTANref{latex}
+\item[shortvrb.sty]Distributed as part of \CTANref{2etools}
+\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-ifpdf]{Am I using \PDFTeX{}?}
+
+It's often useful to know whether your macros are operating within
+\PDFTeX{} or within (``normal'') \TeX{}; getting the right answer is
+surprisingly tricky.
+
+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}
+The above is, in essence, what Heiko Oberdiek's \Package{ifpdf}
+package does; the reasoning is the \acro{FAQ}'s interpretation of
+Heiko's explanation.
+
+As an aside: there are now analogous packages \Package{ifxetex} and
+\Package{ifluatex}, for the two up-and-coming \TeX{}-like engines (see
+the ``\TeX{} project'' answers covering % ! line break
+\Qref[\xetex{}~--- question]{\xetex{}}{Q-xetex}, and
+\Qref[\LuaTeX{}~--- question]{\LuaTeX{}}{Q-luatex}).
+\begin{ctanrefs}
+\item[ifpdf.sty]Distributed with Heiko Oberdiek's packages \CTANref{oberdiek}
+\item[ifluatex.sty]Distributed with Heiko Oberdiek's packages
+ \CTANref{oberdiek}
+\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-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}
+
+\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-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 with Heiko Oberdiek's packages
+ \CTANref{oberdiek}
+\end{ctanrefs}
+
+\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.
+
+The simple answer is to try \csx{show}, in a run of \LaTeX{} 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 use that instead:
+\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.)
+
+If one has a malleable text editor, the same investigation may more
+comfortably 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}
+\end{ctanrefs}
+
+\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{verbatim}
+ \newcommand{\blah}[1][Default]{...}
+\end{verbatim}
+
+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{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}
+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}
+\item[twoopt.sty]Distributed as part of \CTANref{oberdiek}
+\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}
+\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{xxx}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.
+
+\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}
+\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{verbatim}
+\ifthenelse{\isodd{\pageref{foo}}}{odd}{even}
+\end{verbatim}
+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 setting a conditional
+\csx{ifoddpage}. Of course, the \csx{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 is % !line break
+\cmdinvoke{ifthispageodd}{<true>}{<false>} executes different things
+depending on the page number.
+\begin{ctanrefs}
+\item[changepage.sty]\CTANref{changepage}
+\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{narrowversion}
+ \LaTeX{} internal
+\end{narrowversion}
+\begin{wideversion}
+ \Qref{\LaTeX{} internal}{Q-atsigns}
+\end{wideversion}
+\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.
+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}
+
+Many people (for some reason) want a stop after a section number, but
+not after a subsection number, 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{wideversion}
+\begin{quote}
+\begin{verbatim}
+\let\@@seccntformat\@seccntformat
+\renewcommand*{\@seccntformat}[1]{%
+ \expandafter\ifx\csname @seccntformat@#1\endcsname\relax
+ \expandafter\@@seccntformat
+ \else
+ \expandafter
+ \csname @seccntformat@#1\expandafter\endcsname
+ \fi
+ {#1}%
+}
+\end{verbatim}
+\end{quote}
+\end{wideversion}
+\begin{narrowversion}
+\begin{quote}
+\begin{verbatim}
+\let\@@seccntformat\@seccntformat
+\renewcommand*{\@seccntformat}[1]{%
+ \expandafter\ifx
+ \csname @seccntformat@#1\endcsname
+ \relax
+ \expandafter\@@seccntformat
+ \else
+ \expandafter
+ \csname @seccntformat@#1\expandafter
+ \endcsname
+ \fi
+ {#1}%
+}
+\end{verbatim}
+\end{quote}
+\end{narrowversion}
+which looks to see if a second-level command has been defined, and
+uses it if so; otherwise it uses the original. The second-level
+command to define stops after section numbers (only) has the same
+definition as the original ``all levels alike'' version:
+\begin{quote}
+\begin{verbatim}
+\newcommand*{\@seccntformat@section}[1]{%
+ \csname the#1\endcsname.\quad
+}
+\end{verbatim}
+\end{quote}
+Note that all the command definitions of this answer 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}
+\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 use 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.
+\begin{ctanrefs}
+\item[fix-cm.sty]Distributed as part of \CTANref{latex} (an unpacked
+ version is available at \CTANref{fix-cm})
+\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}
+
+\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~--- this is one of them).
+\end{wideversion}
+\begin{narrowversion}
+ (the two error lines both wrapped above; the package provides a demo
+ file which contains most of the sorts of errors you might make~---
+ this is one of them).
+\end{narrowversion}
+
+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[nag.sty]\CTANref{nag}
+\end{ctanrefs}
+