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.tex3724
1 files changed, 0 insertions, 3724 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
deleted file mode 100644
index e9a881ba2a5..00000000000
--- a/Master/texmf-dist/doc/generic/FAQ-en/faq-mac-prog.tex
+++ /dev/null
@@ -1,3724 +0,0 @@
-% $Id: faq-mac-prog.tex,v 1.35 2014/01/28 18:17:36 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-repeat-num]{Repeating a command \emph{n} times}
-
-\tex{} was \emph{not} designed as a programming language, but there
-are occasions when you want to repeat some part of your document, just
-as parts of programs need to run several times. An obvious
-example is \tex{}-based drawing: \latex{}'s \environment{picture}
-environment and \Package{pgf} (at least) provide repeat facilities~---
-they are useful for drawing repeating patterns. As a result,
-``common'' programming techniques often have to be emulated using
-obscure macro \tex{}niques.
-
-This answer deals with repeating an operation a given number of times;
-repeating operations once for each of a set of objects is dealt with
-in the answer \Qref*{repeating ``over a set''}{Q-repeat-set}.
-
-Plain \tex{} itself provides a \csx{loop} \dots{} \csx{repeat}
-contruct, which enables you to repeat a command (or set of commands).
-The syntax is simple enough, but it use of \tex{} conditionals is
-different enough that many people find it confusing.
-\begin{quote}
-\begin{verbatim}
-\newcount\foo
-\foo=10
-\loop
- \message{\the\foo}
- \advance \foo -1
-\ifnum \foo>0
-\repeat
-\end{verbatim}
-\end{quote}
-In this slightly tricky code, \csx{loop} starts the construct ended by
-\csx{repeat}, but \csx{repeat} also ``serves as'' the \csx{fi} to the
-\csx{ifnum}. The loop above prints the numbers from 10 down to 1 via
-\tex{} \csx{message} (i.e., on the console output).
-
-The \Package{multido} package is also `generic' (usable both in
-\plaintex{} and latex{}); it defines a command \csx{multido} with
-three arguments:
-\begin{quote}
- % ! line break
- \cmdinvoke{multido}{\meta{variables}}{\meta{repetitions}}{\meta{stuff to repeat}}
-\end{quote}
-When the macro is executing, the \meta{stuff to repeat} gets executed
-\meta{repetitions} times; the \meta{variables} gives a list of
-variables that can be used in \meta{stuff}. Each variable is a
-composite of a command sequence and how it varies; so a variable
-``\csx{iz}\texttt{=2+4}'' sets \csx{iz} to \texttt{2} first time
-around, then \texttt{6} and \texttt{10} in the next two iterations,
-and so on. (The variable \csx{iz} is an integer; variables with other
-initial letters represent different data types.)
-
-% [do these things matter?]
-% The \latexe{} kernel has commands \csx{@for} and \csx{@tfor}.
-%
-% The \latex{}3 kernel includes the command |\prg_replicate:nn|; this
-% information isn't much use unless you're a \latex{}3 user.
-Both current \latex{} and (experimental) \latex{}3 have iteration
-commands for internal use and for package writers; their use is
-probably not recommendable.
-
-The \latex{} distribution package \Package{ifthen} offers the macro
-\csx{whiledo}:
-\begin{quote}
-\begin{verbatim}
-\newcounter{ct}
-...
-\setcounter{ct}{1}
-\whiledo {\value{ct} < 5}%
-{%
- \thect\
- \stepcounter {ct}%
-}
-\end{verbatim}
-\end{quote}
-
-The \Package{forloop} package provides nothing but \csx{forloop}:
-\begin{quote}
-\begin{verbatim}
-\newcounter{ct}
-...
-\forloop{ct}{1}{\value{ct} < 5}%
-{%
- \thect\
-}
-\end{verbatim}
-\end{quote}
-as you can see, the arguments are counter, starting value and
-termination condition; an optional argument supplies a step value
-(default step is 1).
-
-The \latex{} \environment{picture} environment has a simple command
-for repeated drawing:
-\begin{quote}
-\begin{verbatim}
-\multiput(x,y)(xstep,ystep){n}{obj}
-\end{verbatim}
-\end{quote}
-which places \meta{obj} (intended to be a bit of picture)
-\meta{n} times at positions (\meta{x}, \meta{y}),
-(\meta{x}+\meta{xstep}, \meta{y}+\meta{ystep}),
-(\meta{x}+2\meta{xstep}, \meta{y}+2\meta{ystep}) and so on, adding the
-displacement again each time. The command was designed for use in
-\environment{picture}, but it makes no check, and may even be used to
-provide eccentric typesetting in a ``regular'' sentence, such as:
-\begin{quote}
-\begin{verbatim}
-Here \multiput(0,0)(1,1){3}{we} are again.
-\end{verbatim}
-\end{quote}
-with predictable (if not actually desirable) effect. It may be used
-with nothing but an iterative calculation in the braced argument, in
-which case its graphical capabilities have no effect.
-
-The \Package{pgffor} package, which is part of the % ! line break
-\Qref*{\Package{pgf} distribution}{Q-drawing}, also
-provides iterations to support the needs of graphics. Its syntax is
-in the style of common programming languages:
-\begin{quote}
-\begin{verbatim}
-\usepackage{pgffor}
-\newcommand{\cmd}{-x-}
-...
-\foreach \n in {1,...,4}{\cmd{}}
-\end{verbatim}
-\end{quote}
-typesets ``\texttt{-x-\relax-x-\relax-x-\relax-x-}''
-
-The \csx{foreach} command has the potential drawback that its repeated
-unit is executed in a group, so that any calculations done within the
-loop are lost (unless their result is made \csx{global}); however, it
-does not `build in' its graphical origins (as \csx{multiput} does) so
-its potential outside its own graphics environment ``home'' is more
-clear.
-%
-%% can't convince myself that \naturalloop helps with anything
-% The \Package{etextools} package provides \csx{naturalloop}, which
-% repeats material according to a count argument that you give it.
-%
-%% this stuff removed, following the observation that the package's use
-%% of \repeat is inconsistent with both plain tex and latex; pity --
-%% it's a nice package apart from being totally unusable :-(
-%
-% The \Package{repeat} package provides a \csx{for} command that
-% encompasses a lot of the above; for example:
-% \begin{quote}
-% \begin{verbatim}
-% \input repeat
-% \newcount\foo
-% \repeat
-% \for{foo} \from{1} \to{10} \do{x*}
-% \end{verbatim}
-% \end{quote}
-% which will typeset \texttt{x*} ten times (the count \csx{foo} will
-% end up with value 11).
-%
-% Note the \plaintex{} usage: \Package{repeat} is ``generic'' and
-% defines commands that are comfortable to \plaintex{} users, while
-% remaining usable by \latex{} users.
-%
-% The complete syntax is given in the meta-expression:
-% \begin{quote}
-% \begin{verbatim}
-% \repeat
-% \for{var}
-% \from{<start>} \by{<step>} \to{<end>}
-% \downto{<end>} \until{<cond>} \while{<cond>}
-% \do{<operate on something>}
-% \end{verbatim}
-% \end{quote}
-% You must choose a consistent set of \csx{from}, \csx{by}, \csx{to},
-% \csx{downto}, \csx{until} and \csx{while} (none is actually required,
-% but of course any loop has to have \emph{some}).
-
-% In summary, while it is certainly possible to write this sort of code as
-% a private project (for example, using the \etex{} \csx{numexpr}
-% primitive), one cannot deny that plenty of choice for the task is
-% readily available.
-%
-% (the above ignore Pic\tex{}, which almost certainly has similar
-% functions, but in the absence of a manual\dots{})
-\begin{ctanrefs}
-%\item[etextools.sty]\CTANref{etextools}
-\item[forarray.sty]\CTANref{forarray}
-\item[forloop.sty]\CTANref{forloop}
-\item[ifthen.sty]Distributed as part of \CTANref{latex}
-\item[multido.sty]\CTANref{multido}
-\item[pgffor.sty]Distributed as part of \CTANref{pgf}
-%\item[repeat.tex]\CTANref{repeat}
-\end{ctanrefs}
-\LastEdit{2013-03-01}
-
-\Question[Q-repeat-set]{Repeating something for each `thing' in a set}
-
-As another question % line break!
-(\Qref*{repeating something a given number of times}{Q-repeat-num})
-explains, \tex{} is not explicitly designed for `regular' programming
-operations. As a result, we must resort to arcane tricks to do the
-seemingly simple task of repeating an operation. This answer deals
-with repeating an operation for each of a given set of objects.
-
-The \Package{etoolbox} package provides iteration over a
-comma-separated list of items, in its \csx{docsvlist} and
-\csx{forcsvlist} commands; they are well-described in the package
-documentation. The \Package{datatool} package manages ``databases''
-(of its own definition) and you may iterate over entries in such a
-database using the command \csx{DTLforeach}.
-
-The \Package{forarray} package defines its own ``list'' and ``array''
-structures, together with commands \csx{ForEach} and \csx{ForArray}
-which enable a command to be executed for each element in a list or
-array, respectively.
-
-The \Package{dowith} defines a pair of macros \csx{DoWith} and
-\csx{StopDoing} that process each ``thing'' between them; a trivial
-example of use is:
-\begin{quote}
-\begin{verbatim}
-\usepackage{dowith}
-...
-\begin{document}
-\newcommand{\foo}[1]{\message{#1+}
-\DoWith\foo a{BBB}c\StopDoing
-\end{verbatim}
-\end{quote}
-which produces terminal output:
-\begin{quote}
-\begin{verbatim}
-a+ BBB+ c+
-\end{verbatim}
-\end{quote}
-so, the macros have found 3 ``things'', including one with braces
-around it. (The interpolated spaces come from the primitive
-\csx{message} command.)
-
-The only constraint is that all commands in the enclosed stuff are
-``expandable'' (which means, for example, that you may not use
-commands with optional arguments).
-
-From the same stable (as \Package{dowith}) comes the package
-\Package{commado}, that provides commands \csx{DoWithCSL} (apply a
-command to each element of a comma-separated-variable list) and
-\csx{DoWithBasesExts} (apply a command to each of a set of files,
-defined by base name and ``extension''). Use of these \csx{DoWith*}
-macros is also expandable (if the command applied to the list elements
-is itself expandable).
-\begin{ctanrefs}
-\item[commado.sty]\CTANref{commado}
-\item[datatool.sty]\CTANref{datatool}
-\item[dowith.sty]\CTANref{dowith}
-\item[etoolbox.sty]\CTANref{etoolbox}
-\item[filesdo.sty]Distributed with \CTANref{commado}
-\end{ctanrefs}
-\LastEdit{2013-02-20}
-
-%See \url{http://tex.stackexchange.com/questions/16189/repeat-command-n-times}
-%for details (do i need this any more?)
-
-\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 then call the redefined \csx{splat} again; this is an
-`unterminated recursion', that will quickly exhaust \TeX{}'s memory.
-
-Fortunately, the \TeX{} primitive \csx{let} command comes to our
-rescue; it allows us to take a ``snapshot'' of the current state of a
-command, which we can then use in the redefinition of the command.
-So:
-\begin{quote}
-\begin{verbatim}
-\let\OldSmooth\smooth
-\renewcommand{\smooth}{\mumble\OldSmooth}
-\end{verbatim}
-\end{quote}
-effects the required patch, safely. Adding things at the end of a
-command works similarly.
-
-If \csx{smooth} takes arguments, one must pass them on:
-\begin{quote}
-\begin{wideversion}
-\begin{verbatim}
-\let\OldSmooth\smooth
-\renewcommand{\smooth}[2]{\mumble\OldSmooth{#1}{#2}}
-\end{verbatim}
-\end{wideversion}
-\begin{narrowversion}
-\begin{verbatim}
-\let\OldSmooth\smooth
-\renewcommand{\smooth}[2]%
- {\mumble\OldSmooth{#1}{#2}}
-\end{verbatim}
-\end{narrowversion}
-\end{quote}
-
-The situation is more difficult still if \csx{smooth} takes an
-optional argument; the structure of the command is so complex that the
-simple \csx{let} command does not retain the necessary detail. In
-this case, we need the \Package{letltxmacro} package which knows about all
-sorts of \latex{} commands and how to replicate them. Suppose we have
-a command defined as:
-\begin{quote}
-\begin{verbatim}
-\newcommand{\rough}[1][\default]{...}
-\end{verbatim}
-\end{quote}
-with an optional argument (substituted with \csx{default} if it's not
-present) as well as an ordinary one. In this case we copy it using
-\begin{quote}
-\begin{verbatim}
-\LetLtxMacro{\NewRough}{\rough}
-\end{verbatim}
-\end{quote}
-and then repeat the technique we had above, with one extension:
-\begin{quote}
-\begin{verbatim}
-\renewcommand{\rough}[1][\newdef]%
- {\mumble\OldRough[{#1}]{#2}}
-\end{verbatim}
-\end{quote}
-We see here that (for tedious argument-matching reasons) it is
-necessary to provide braces arround the optional argument that is
-being passed on.
-
-The general case may be achieved in two ways. First, one can use the
-\LaTeX{} command \csx{CheckCommand}; this compares an existing command
-with the definition you give it, and issues a warning if two don't
-match. Use is therefore:
-\begin{quote}
- |\CheckCommand{\complex}{|\meta{original definition}|}|\\
- |\renewcommand{\complex}{|\meta{new definition}|}|
-\end{quote}
-This technique is obviously somewhat laborious, but if the original
-command comes from a source that's liable to change under the control
-of someone else, it does at least warn you that your patch is in
-danger of going wrong.
-
-Otherwise, \LaTeX{} users may use one of the \Package{patchcmd},
-\Package{ted} or \Package{etoolbox} packages.
-
-The \Package{patchcmd} package addresses a slightly simpler task, by
-restricting the set of commands that you may patch; you mayn't patch
-any command that has an optional argument, though it does deal with
-the case of commands defined with \csx{DeclareRobustCommand}. The
-package defines a \csx{patchcommand} command, that takes three
-arguments: the command to patch, stuff to stick at the front of its
-definition, and stuff to stick on the end of its definition. So,
-after
-\begin{quote}
-\begin{verbatim}
-\def\b{b}
-\patchcmd\b{a}{c}
-\end{verbatim}
-\end{quote}
-we will have a new version of \csx{b} defined as ``\texttt{abc}''.
-
-The \Package{ted} package is a `token list editor', and provides a
-command \csx{substitute} which will patch the
-contents of a macro, putting the result in a token-list, or
-(in the form \csx{Substitute*}) using the result to (re)define a
-macro. The following example defines a simple macro, and then changes
-its definition:
-\begin{quote}
-\begin{verbatim}
-\newcommand{\myfont}%
- {\Large\sffamily\selectfont}
-\Substitute*[\renewcommand{\myfont}]{\myfont}%
- {\Large\sffamily}{\huge\itshape}
-\end{verbatim}
-\end{quote}
-The macro's definition is now:
-\begin{quote}
-\begin{verbatim}
-\huge\itshape\selectfont
-\end{verbatim}
-\end{quote}
-
-The package also offers a command \csx{ShowTokens}, which shows the
-content of its argument, one token to a line, with details of the
-token's category code, etc. This is recommended as a debugging tool.
-
-The \Package{etoolbox} package (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.)
-
-The \Package{regexpatch} package deals with cases that are
-inaccessible with \Package{etoolbox}; it uses the regular expression
-(pattern-matching) package \Package{l3regex} from the \latex{}3
-distribution to find the code you need to patch. The package also
-``knows about'' robust commands and about
-\Qref*{\Package{biblatex}}{Q-biblatex}.
-
-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[l3regex.sty]Distributed as part of \CTANref{l3experimental}[l3regex]
-\item[letltxmacro.sty]Distributed as part of \CTANref{oberdiek}[letltxmacro]
-\item[patch.doc]\CTANref{patch}
-\item[patchcommand.sty]\CTANref{patchcmd}
-\item[regexpatch.sty]\CTANref{regexpatch}
-\item[ted.sty]\CTANref{ted}
-\end{ctanrefs}
-\LastEdit{2012-12-21}
-
-\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=0#1 \end}
-\def\testresult#1\end{\ifx\end#1\end}
-\end{verbatim}
-\end{narrowversion}
-\begin{wideversion}
-\begin{verbatim}
-\def\testnum#1{\afterassignment\testresult\count255=0#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; the trick for avoiding the
-errors, noted in an earlier version of this answer, was suggested by
-Andreas Matthias).
-In a later thread on the same topic, Michael Downes offered:
-\begin{quote}
-\begin{wideversion}
-\begin{verbatim}
-\def\IsInteger#1{%
- TT\fi
- \begingroup \lccode`\-=`\0 \lccode`+=`\0
- \lccode`\1=`\0 \lccode`\2=`\0 \lccode`\3=`\0
- \lccode`\4=`\0 \lccode`\5=`\0 \lccode`\6=`\0
- \lccode`\7=`\0 \lccode`\8=`\0 \lccode`\9=`\0
- \lowercase{\endgroup
- \expandafter\ifx\expandafter\delimiter
- \romannumeral0\string#1}\delimiter
-}
-\end{verbatim}
-\end{wideversion}
-\begin{narrowversion}
-\begin{verbatim}
-\def\IsInteger#1{%
- TT\fi
- \begingroup \lccode`\-=`\0 \lccode`+=`\0
- \lccode`\1=`\0 \lccode`\2=`\0
- \lccode`\3=`\0 \lccode`\4=`\0
- \lccode`\5=`\0 \lccode`\6=`\0
- \lccode`\7=`\0 \lccode`\8=`\0
- \lccode`\9=`\0
- \lowercase{\endgroup
- \expandafter\ifx\expandafter\delimiter
- \romannumeral0\string#1}\delimiter
-}
-\end{verbatim}
-\end{narrowversion}
-\end{quote}
-which relies on \csx{romannumeral} producing an empty result if its
-argument is zero. Sadly, this technique has the unfortunate property
-that it accepts simple expressions such as `\texttt{1+2-3}'; this
-could be solved by an initial \csx{gobbleminus}-like construction.
-
-All the complete functions above are designed to be used in \TeX{}
-conditionals written ``naturally''~--- for example:
-\begin{quote}
-\begin{verbatim}
-\if\IsInteger{<subject of test>}%
- <deal with integer>%
-\else
- <deal with non-integer>%
-\fi
-\end{verbatim}
-\end{quote}
-The \LaTeX{} \Class{memoir} class has an internal command of its own,
-\cmdinvoke*{checkifinteger}{num}, that sets the conditional command
-\csx{ifinteger} according to whether the argument was an integer.
-
-Of course, all this kerfuffle would be (essentially) void if there was
-a simple means of ``catching'' \TeX{} errors. Imagining an
-error-catching primitive \csx{ifnoerror}, one might write:
-\begin{quote}
-\begin{verbatim}
-\def\IsInteger#1{%
- TT%
- \ifnoerror
- \tempcount=#1\relax
-% carries on if no error
- \expandafter\iftrue
- \else
-% here if there was an error
- \expandafter\iffalse
- \fi
-}
-\end{verbatim}
-\end{quote}
-thus using \TeX{}'s own integer-parsing code to do the check. It's a
-pity that such a mechanism was never defined (it could be that it's
-impossible to program within \TeX{}!).
-\begin{ctanrefs}
-\item[memoir.cls]\CTANref{memoir}
-\end{ctanrefs}
-
-\Question[Q-hash]{Defining macros within macros}
-
-The way to think of this is that |##| gets replaced by |#| in just the
-same way that |#1| gets replaced by `whatever is the first argument'.
-
-So if you define a macro:
-\begin{quote}
-\begin{verbatim}
-\newcommand\a[1]{+#1+#1+#1+}
-\end{verbatim}
-\end{quote}
-or (using the \tex{} primitive \csx{def}):
-\begin{quote}
-\begin{verbatim}
-\def\a#1{+#1+#1+#1+}
-\end{verbatim}
-\end{quote}
-and use it as \cmdinvoke{a}{b},
-the macro expansion produces `+b+b+b+',
-as most people would expect.
-
-However, if we now replace part of the macro:
-\begin{quote}
-\begin{narrowversion}
-\begin{verbatim}
-\newcommand\a[1]{+#1+%
- \newcommand\x[1]{xxx#1}}
-\end{verbatim}
-\end{narrowversion}
-\begin{wideversion}
-\begin{verbatim}
-\newcommand\a[1]{+#1+\newcommand\x[1]{xxx#1}}
-\end{verbatim}
-\end{wideversion}
-\end{quote}
-then \cmdinvoke{a}{b} will give us the rather odd
-\begin{quote}
- +b+\cmdinvoke{newcommand}{x}[1]{xxxb}
-\end{quote}
-so that the new \csx{x} ignores its argument.
-
-If we use the \tex{} primitive:
-\begin{quote}
-\begin{verbatim}
-\def\a#1{+#1+\def\x #1{xxx#1}}
-\end{verbatim}
-\end{quote}
-\cmdinvoke{a}{b} will expand to `+b+|\def\x b{xxxb}|'. This
-defines \csx{x} to be a macro \emph{delimited} by |b|, and taking no
-arguments, which is surely not what was intended!
-
-Actually, to define \csx{x} to take an argument, we need
-\begin{quote}
-\begin{narrowversion}
-\begin{verbatim}
-\newcommand\a[1]{+#1+%
- \newcommand\x[1]{xxx##1}}
-\end{verbatim}
-\end{narrowversion}
-\begin{wideversion}
-\begin{verbatim}
-\newcommand\a[1]{+#1+\newcommand\x[1]{xxx##1}}
-\end{verbatim}
-\end{wideversion}
-\end{quote}
-or, using the \tex{} primitive definition:
-\begin{quote}
-\begin{verbatim}
-\def\a#1{+#1+\def\x ##1{xxx##1}}
-\end{verbatim}
-\end{quote}
-and \cmdinvoke{a}{b} will expand to
-\begin{quote}
- +b+|\def\x #1{xxx#1}|
-\end{quote}
-because |#1| gets replaced by `b'
-and |##| gets replaced by |#|.
-
-To nest a definition inside a definition inside a definition then you
-need |####1|, doubling the number of |#| signs; and at the next level
-you need 8~|#|s each time, and so on.
-
-\Question[Q-spinmacro]{Spaces in macros}
-
-It's very easy to write macros that produce space in the typeset
-output where it's neither desired nor expected. Spaces introduced by
-macros are particularly insidious because they don't amalgamate with
-spaces around the macro (unlike consecutive spaces that you
-type), so your output can have a single bloated space that proves
-to be made up of two or even more spaces that haven't amalgamated.
-And of course, your output can also have a space where none was wanted
-at all.
-
-Spaces are produced, inside a macro as elsewhere, by space or tab
-characters, or by end-of-line characters. There are two basic rules
-to remember when writing a macro: first, the rules for ignoring spaces
-when you're typing macros are just the same as the rules that apply
-when you're typing ordinary text, and second, rules for ignoring
-spaces do \emph{not} apply to spaces produced while a macro is being
-obeyed (``expanded'').
-
-Spaces are ignored in vertical mode (between paragraphs), at the
-beginning of a line, and after a command name. Since sequences of
-spaces are collapsed into one, it `feels as if' spaces are ignored if
-they follow another space. Space can have syntactic meaning after
-certain sorts of non-braced arguments (e.g., \emph{count} and
-\emph{dimen} variable assignments in \plaintex{}) and after certain
-control words (e.g., in \csx{hbox} |to|, so again we have instances
-where it `feels as if' spaces are being ignored when they're merely
-working quietly for their living.
-
-Consider the following macro, fairly faithfully adapted from one that
-appeared on \Newsgroup{comp.text.tex}:
-\begin{narrowversion}
-\begin{quote}
-\begin{verbatim}
-\newcommand{\stline}[1]
- { \bigskip \makebox[2cm]{ \textbf{#1} } }
-\end{verbatim}
-\end{quote}
-(the original appeared on a single line: it's wrapped here to fit in
-the printed \acro{FAQ}'s narrow columns).
-
-\nothtml{\noindent}
-\end{narrowversion}
-\begin{wideversion}
-\begin{quote}
-\begin{verbatim}
-\newcommand{\stline}[1]{ \bigskip \makebox[2cm]{ \textbf{#1} } }
-\end{verbatim}
-\end{quote}
-\end{wideversion}
-The macro definition contains five spaces:
-\begin{itemize}
-\item after the opening |{| of the macro body; this space will be
- ignored, not because ``because the macro appears at the start of a
- line'', but rather because the macro was designed to operate between
- paragraphs
-\item after \csx{bigskip}; this space will be ignored (while the macro
- is being defined) because it follows a command name
-\item after the |{| of the mandatory argument of \csx{makebox}; even
- though this space will inevitably appear at the start of an output
- line, it will \emph{not} be ignored
-\item after the |}| closing the argument of \csx{textbf}; this space
- will not be ignored, but may be overlooked if the argument is well
- within the |2cm| allowed for it
-\item after the |}| closing the mandatory argument of \csx{makebox};
- this space will not be ignored
-\end{itemize}
-The original author of the macro had been concerned that the starts of
-his lines with this macro in them were not at the left margin, and
-that the text appearing after the macro wasn't always properly
-aligned. These problems arose from the space at the start of the
-mandatory argument of \csx{makebox} and the space immediately after the
-same argument. He had written his macro in that way to emphasise the
-meaning of its various parts; unfortunately the meaning was rather
-lost in the problems the macro caused.
-
-The principal technique for suppressing spaces is the use of
-\texttt{\textpercent{}} characters: everything after a
-\texttt{\textpercent{}} is ignored, even the end of line itself (so
-that not even the end of line can contribute an unwanted space). The
-secondary technique is to ensure that the end of line is preceded by a
-command name (since the end of line behaves like a space, it will be
-ignored following a command name). Thus the above command would be
-written (by an experienced programmer with a similar eye to
-emphasising the structure):
-\begin{quote}
-\begin{verbatim}
-\newcommand{\stline}[1]{%
- \bigskip
- \makebox[2cm]{%
- \textbf{#1}\relax
- }%
-}
-\end{verbatim}
-\end{quote}
-Care has been taken to ensure that every space in the revised
-definition is ignored, so none appears in the output. The revised
-definition takes the ``belt and braces'' approach, explicitly dealing
-with every line ending (although, as noted above, a space introduced
-at the end of the first line of the macro would have been ignored in
-actual use of the macro. This is the best technique, in fact~--- it's
-easier to blindly suppress spaces than to analyse at every point
-whether you actually need to. Three techniques were used to suppress
-spaces:
-\begin{itemize}
-\item placing a \texttt{\textpercent{}} character at the end of a line
- (as in the 1st, 3rd and 5th lines),
-\item ending a line `naturally' with a control sequence, as in line 2,
- and
-\item ending a line with an `artificial' control sequence, as in line
- 4; the control sequence in this case (\csx{relax}) is a no-op in many
- circumstances (as here), but this usage is deprecated~--- a
- \texttt{\textpercent{}} character would have been better.
-\end{itemize}
-Beware of the (common) temptation to place a space \emph{before} a
-\texttt{\textpercent{}} character: if you do this you might as well omit
-the \texttt{\textpercent{}} altogether.
-
-In ``real life'', of course, the spaces that appear in macros are far
-more cryptic than those in the example above. The most common spaces
-arise from unprotected line ends, and this is an error that
-occasionally appears even in macros written by the most accomplished
-programmers.
-
-\Question[Q-moren9]{How to break the 9-argument limit}
-
-If you think about it, you will realise that Knuth's command
-definition syntax:
-\begin{quote}
-\begin{verbatim}
-\def\blah#1#2 ... #9{<macro body>}
-\end{verbatim}
-\end{quote}
-is intrinsically limited to just 9 arguments. There's no direct way
-round this: how would you express a 10th argument?~--- and ensure that
-the syntax didn't gobble some other valid usage?
-
-If you really must have more than 9 arguments, the way to go is:
-\begin{quote}
-\begin{verbatim}
-\def\blah#1#2 ... #9{%
- \def\ArgI{{#1}}%
- \def\ArgII{{#2}}%
- ...
- \def\ArgIX{{#9}}%
- \BlahRelay
-}
-\def\BlahRelay#1#2#3{%
- % arguments 1-9 are now in
- % \ArgI-\ArgIX
- % arguments 10-12 are in
- % #1-#3
- <macro body>%
-}
-\end{verbatim}
-\end{quote}
-This technique is easily extendible by concert pianists of the \TeX{}
-keyboard, but is really hard to recommend.
-
-\LaTeX{} users have the small convenience of merely giving a number of
-arguments in the \csx{newcommand} that defines each part of the
-relaying mechanism: Knuth's restriction applies to \csx{newcommand}
-just as it does to \csx{def}. However, \LaTeX{} users also have the
-way out of such barbarous command syntax: the \Package{keyval}
-package. With \Package{keyval}, and a bit of programming, one can
-write really quite sophisticated commands, whose invocation might look
-like:
-\begin{quote}
-\begin{verbatim}
-\flowerinstance{species=Primula veris,
- family=Primulaceae,
- location=Coldham's Common,
- locationtype=Common grazing land,
- date=1995/04/24,
- numplants=50,
- soiltype=alkaline
-}
-\end{verbatim}
-\end{quote}
-The merit of such verbosity is that it is self-explanatory: the typist
-doesn't have to remember that argument twelve is |soiltype|, and so
-on: the commands may be copied from field notes quickly and
-accurately.
-\begin{ctanrefs}
-\item[keyval.sty]Distributed as part of \CTANref{graphics}[keyval]
-\end{ctanrefs}
-
- * faq-mac-prog.tex (q-keyval): tweak words about getoptk
-
-\Question[Q-keyval]{Key-value input for macros and package options}
-
-When we discussed % !line break
-\Qref*{extending the number of arguments to a macro}{Q-moren9}, we
-suggested that large numbers of arguments, distinguished only by their
-position, aren't very kind to the user, and that a package such as
-\Package{keyval} offers a more attractive user interface. We now
-consider the packages that the macro programmer might use, to create
-such a user interface.
-
-The simplest key-value processor (for \latex{}, at least) remains
-\Package{keyval}; it has a command \csx{define@key} to declare a key
-and a \emph{handler} to process it, and a macro \csx{setkeys} to offer
-values to the handler of one or more keys. Thus:
-\begin{quote}
-\begin{verbatim}
-\define@key{my}{foo}{Foo is #1\par}
-\define@key{my}{bar}[99]{Bar is #1\par}
-...
-\setkeys{my}{foo=3,bar}
-\end{verbatim}
-\end{quote}
-will produce output saying:
-\begin{quote}
- Foo is 3\par{}
- Bar is 99
-\end{quote}
-This has defined two keys `\texttt{foo}' and `\texttt{bar}' in family
-`\texttt{my}', and then executed them, the first with argument
-`\texttt{3}' and the second with no argument, so that the default
-value of `\texttt{99}' is picked up. In effect, the two calls to
-\csx{define@key} are simply defining commands, as (for example):
-\begin{quote}
-\begin{verbatim}
-\newcommand{\KV@my@foo}[1]{Foo is #1}
-\end{verbatim}
-\end{quote}
-(the definition of \csx{KV@my@bar} is similar, but trickier). The
-command \csx{setkeys} knows how to find those commands when it needs to
-process each key~--- it is easy to regurgitate the structure of the
-command name, with family name (`\texttt{my}', here) after the first
-`\texttt{@}', and the key name after the second `\texttt{@}'. (The
-`\texttt{KV}' part is fixed, in \Package{keyval}.)
-
-These simple commands are enough, in fact, to process the botanical
-example offered as replacement for multi-argument commands in % ! line break
-\Qref[question]{the question mentioned above}{Q-moren9}, or the
-optional arguments of the \csx{includegraphics} command of the
-\Package{graphicx} package. (The last is, in fact, what
-\Package{keyval} was designed to do.)
-
-However, we need more if we're to to have package options in
-`key-value' form. Packages like \Package{hyperref} have enormously
-complicated package options which need key-value processing at
-\csx{ProcessOptions} time: \Package{keyval} can't do that on its own.
-
-Heiko Oberdiek's \Package{kvoptions} package comes to our help: it
-enables the programmer to declare class or package options that
-operate as key and value pairs. The package defines commands
-\csx{DeclareBoolOption} for options whose value should be either
-\emph{true} or \emph{false}, and \csx{DeclareStringOption} for all
-other options that have a value. Keys are declared using
-\Package{keyval} and may remain available for use within the document,
-or may be `cancelled' to avoid confusion. If you have loaded
-\Package{kvoptions}, the \LaTeX{} kernel's \csx{DeclareOption} becomes
-\csx{DeclareVoidOption} (it's an option with no value), and
-\csx{DeclareOption*} becomes \csx{DeclareDefaultOption}.
-
-Heiko also provides \Package{kvsetkeys} which is a more robust version
-of \Package{setkeys}, with some of the rough edges made smoother.
-
-Hendri Adriaens' \Package{xkeyval} offers more flexibility than
-the original \Package{keyval} and is more robust than the original,
-too. Like \Package{kvoptions}, the package also has mechanisms to
-allow class and package options in key-value form (macros
-\csx{DeclareOptionX}, \csx{ExecuteOptionsX} and \csx{ProcessOptionsX}.
-\Package{Pstricks} bundle packages use a \Package{xkeyval} derivative
-called \Package{pst-xkey} for their own key-value manipulation.
-% xkvview? (i think we can ignore xkvltxp for these purposes)
-
-The (widely-respected) \Package{pgf} graphics package has its own
-key-value package called \Package{pgfkeys}. The documentation of the
-package (part of the huge \Package{pgf} manual, in part 5,
-``utilities'') contains a useful comparison with other key-value
-systems; some notable differences are:
-\begin{itemize}
-\item key organisation: \Package{pgfkeys} uses a tree structure, while
- \Package{keyval} and \Package{xkeyval} both associate keys with a family;
-\item \Package{pgfkeys} supports multi-argument key code; and
-\item \Package{pgfkeys} can support call-backs when an unknown key
- appears (these things are called \emph{handlers}.
-\end{itemize}
-Keys are organized in a tree that is reminiscent of the Unix fille
-tree. A typical key might be, \File{/tikz/coordinate system/x} or
-just \File{/x}. When you specify keys you can provide the complete
-path of the key, but you usually just provide the name of the key
-(corresponding to the file name without any path) and the path is
-added automatically. So a \csx{pgfkeys} command might be:
-\begin{wideversion}
-\begin{quote}
-\begin{verbatim}
-\pgfkeys{/my key=hello,/your keys/main key=something\strange,
- key name without path=something else}
-\end{verbatim}
-\end{quote}
-\end{wideversion}
-\begin{narrowversion}
-\begin{quote}
-\begin{verbatim}
-\pgfkeys{/my key=hello,
- /your keys/main key=something\strange,
- key name without path=something else}
-\end{verbatim}
-\end{quote}
-\end{narrowversion}
-and for each key mentioned, the associated code will be executed.
-\dots{} and that code is also set up using \csx{pgfkeys}:
-\begin{quote}
-\begin{verbatim}
-\pgfkeys{/my key/.code=The value is '#1'.}
-\end{verbatim}
-\end{quote}
-after which
-\begin{quote}
-\begin{verbatim}
-\pgfkeys{/my key=hi!}
-\end{verbatim}
-\end{quote}
-will produce just
-\begin{quote}
- The value is 'hi!'.
-\end{quote}
-The manual goes on, showing how to define a key with two arguments,
-how to provide default value for a key, and how to define aliases for
-particular key sequences (which are called ``styles''). All in all,
-it seems a well thought-out system, offering a lot of flexibility that
-isn't available with the other keys packages. However, there seems to
-be no mechanism for using \Package{pgfkeys} keys as part of the
-options of another package, in the way that \Package{kvoptions} does.
-
-The \Package{l3kernel} programming layer for \Qref*{\LaTeX{}3}{Q-LaTeX3}
-includes the \Package{l3keys} module. Inspired by \Package{pgfkeys},
-it provides a keyval-based method for the programmer to create keys.
-As with keyval and derivatives, \Package{l3keys} uses separate macros
-for defining and setting keys. The package \Package{l3keys2e} makes
-it possible for \latexe{} class and package
-options to be processed using \Package{l3keys}. \Package{L3kernel}
-code can be used within existing LaTeX2e documents, so
-\Package{l3keys} is also available to the \latexe{} programmer `direct'.
-
-Another key-value system that's part of larger set of macros is
-\Package{scrbase}, which uses the facilities of \Package{keyval} to
-build a larger set of facilities, originally for use within the
-\Class{KOMA-script} bundle. For English-speaking authors, there are
-difficulties from the German-only documentation; however, from a
-partial translation available to the author of this answer, a summary
-is possible. The package may build on the facilities either of
-\Package{kyeval} or of \Package{xkeyval}, and builds its functionality
-on the structure of the `key family'. The user may define family
-`members' and keys are defined relative to the members. (For example,
-the package \Package{scrbase} is part of the \Class{KOMA-script}
-bundle; so its keys are all members of the \Package{scrbase.sty}
-family within the \Package{KOMA} family. The function
-\csx{FamilyProcessOptions} allows the programmer to decode the options
-of the package in terms of the package's key family. Note that there
-is no special provision made for ``traditional'' package options, as
-in the \Package{kvoptions} package.
-
-This brief summary was guided by input from two sources: a draft article
-for \textsl{TUGboat} by Joseph Wright, and the partial translation of the
-documentation of package \Package{scrbase} prepared by Philipp
-Stephani.
-
-All the above are (at least) aimed at \latex{} programming; there is
-one package, \Package{getoptk}, aimed at the \plaintex{} programmer.
-\Package{Getoptk} uses syntax inspired by that offered by \tex{}
-primitives such as \csx{hrule} and \csx{hbox}, so we are offered
-syntax such as:
-\begin{wideversion}
-\begin{quote}
-\begin{verbatim}
-\begindisplay file {chapter1} literal offset 20pt
-\end{verbatim}
-\end{quote}
-(taken from the package manual).
-\end{wideversion}
-\begin{narrowversion}
-\begin{quote}
-\begin{verbatim}
-\begindisplay file {chapter1} %
- literal offset 20pt
-\end{verbatim}
-\end{quote}
-(taken from the package manual, but wrapped to fit into narrow
-columns).
-\end{narrowversion}
-
-There are (we know) people who would swear that such syntax is
-wonderful (the present author wouldn't), but the package earns its
-place as the only stand-alone key-value macros that will work in \plaintex{}.
-\begin{ctanrefs}
-\item[getoptk.tex]\CTANref{getoptk}
-\item[keyval.sty]Distributed as part of \CTANref{graphics}[keyval]
-\item[kvoptions.sty]Distributed as part of \CTANref{oberdiek}[kvoptions]
-\item[kvsetkeys.sty]Distributed as part of \CTANref{oberdiek}[kvsetkeys]
-\item[l3keys.sty]Distributed as part of \CTANref{l3kernel}
-\item[l3keys2e.sty]Distributed as part of \CTANref{l3packages}
-\item[pgfkeys.sty]Distributed as part of \CTANref{pgf}
-\item[scrbase.sty]Distributed as part of \CTANref{koma-script}
-\item[xkeyval.sty]\CTANref{xkeyval}
-\end{ctanrefs}
-\LastEdit{2011-09-06}
-
-\Question[Q-activechars]{Defining characters as macros}
-
-Single characters can act as macros (defined commands), and both
-\plaintex{} and \LaTeX{} define the character
-``\texttt{\textasciitilde}'' as a ``non-breakable space''. A
-character is made definable, or ``active'', by setting its
-\emph{category code} (catcode) to be \csx{active} (13):
-\begin{quote}
-\begin{verbatim}
-\catcode`\_=\active
-\end{verbatim}
-\end{quote}
-Any character could, in principle, be activated this way and defined
-as a macro:
-\begin{quote}
-\begin{verbatim}
-\def_{\_}
-\end{verbatim}
-\end{quote}
-which could be characterised as an over-simple answer to % ! line break
-\Qref[question]{using underscores}{Q-underscore}. However, you must be
-wary: whereas people expect an active tilde, other active characters
-may be unexpected and interact badly with other macros. Furthermore,
-by defining an active character, you preclude the character's use for
-other purposes, and there are few characters ``free'' to be subverted
-in this way.
-
-To define the character ``\texttt{z}'' as a command, one would say something
-like:
-\begin{quote}
-\begin{verbatim}
-\catcode`\z=\active
-\def z{Yawn, I'm tired}%
-\end{verbatim}
-\end{quote}
-and each subsequent ``\texttt{z}'' in the text would become a
-yawn. This would be an astoundingly bad idea for most documents, but
-might have special applications. (Note that, in ``\csx{def}\texttt{
- z}'', ``\texttt{z}'' is no longer interpreted as a letter; the space
-is therefore not necessary~--- ``\csx{defz}'' would do; we choose to
-retain the space, for what little clarity we can manage.)
-Some \LaTeX{} packages facilitate such definitions. For example, the
-\Package{shortvrb} package with its \csx{MakeShortVerb} command.
-
-\TeX{} uses category codes to interpret characters as they are read
-from the input.
-% beware line break
-\emph{Changing a catcode value will not affect characters that have already been read}.
-Therefore, it is best if characters have fixed category codes for the
-duration of a document. If catcodes are changed for particular
-purposes (the \csx{verb} command does this), then the altered
-characters will not be interpreted properly when they appear in the
-argument to another command (as, for example, in
-% beware line-break
-\htmlonly{``}\Qref[question]{\csx{verb} in command arguments}{Q-verbwithin}\htmlonly{''}).
-An exemplary case is the \Package{doc} package, which processes .dtx
-files using the \Package{shortvrb} package to define
-\texttt{\textbar\dots{}\textbar} as a shorthand for
-\csx{verb}\texttt{\textbar\dots{}\textbar}. But \texttt{\textbar} is
-also used in the preambles of tabular environments, so that tables in
-\extension{dtx} files can only have vertical line separation between
-columns by employing special measures of some sort.
-
-Another consequence is that catcode assignments made
-in macros often don't work as expected % beware linebreak
-(\htmlonly{see ``}\Qref{Active characters in command arguments}{Q-actinarg}\htmlonly{''}).
-For example, the definition
-\begin{quote}
-\begin{verbatim}
-\def\mistake{%
-\catcode`_=\active
-\def_{\textunderscore\-}%
-}
-\end{verbatim}
-\end{quote}
-does not work because it attempts to define an ordinary \texttt{\_} character:
-When the macro is used, the category change does not apply to the
-underscore character already in the macro definition. Instead, one may
-use:
-\begin{quote}
-\begin{verbatim}
-\begingroup
-\catcode`_=\active
-\gdef\works{% note the global \gdef
- \catcode`_=\active
- \def_{\textunderscore\-}%
-}
-\endgroup
-\end{verbatim}
-\end{quote}
-The alternative (``tricksy'') way of creating such an isolated
-definition depends on the curious properties of \csx{lowercase}, which
-changes characters without altering their catcodes. Since there is
-always \emph{one} active character (``\texttt{\textasciitilde}''), we
-can fool \csx{lowercase} into patching up a definition without ever
-explicitly changing a catcode:
-\begin{quote}
-\begin{verbatim}
-\begingroup
- \lccode`\~=`\_
- \lowercase{\endgroup
- \def~{\textunderscore\-}%
- }%
-\end{verbatim}
-\end{quote}
-The two definitions have the same overall effect (the character is
-defined as a command, but the character does not remain active),
-except that the first defines a \csx{global} command.
-
-For active characters to be used only in maths mode, it is much better
-to leave the character having its ordinary catcode, but assign it a
-special active \emph{maths code}, as with
-\begin{quote}
-\begin{verbatim}
-\begingroup
- \lccode`~=`x
- \lowercase{\endgroup
- \def~{\times}%
- }%
-\mathcode`x="8000
-\end{verbatim}
-\end{quote}
-The special character does not need to be redefined whenever it is
-made active~--- the definition of the command persists even if the
-character's catcode reverts to its original value; the definition
-becomes accessible again if the character once again becomes active.
-\begin{ctanrefs}
-\item[doc.sty]Part of the \LaTeX{} distribution \CTANref{latex}[doc]
-\item[shortvrb.sty]Part of the \LaTeX{} distribution \CTANref{latex}[shortvrb]
-\end{ctanrefs}
-
-
-\Question[Q-actinarg]{Active characters in command arguments}
-
-Occasionally, it's nice to make one or two characters active in the
-argument of a command, to make it easier for authors to code the
-arguments.
-
-Active characters \emph{can} be used safely in such situations; but
-care is needed.
-
-An example arose while this answer was being considered: an aspirant
-macro writer posted to \Newsgroup{comp.text.tex} asking for help to
-make |#| and |b| produce musical sharp and flat signs, respectively,
-in a macro for specifying chords.
-
-The first problem is that both |#| and |b| have rather important uses
-elsewhere in \TeX{} (to say the least!), so that the characters can
-only be made active while the command is executing.
-
-Using the techniques discussed in % beware line break, next line
-\htmlonly{``}\Qref[question]{characters as commands}{Q-activechars}\htmlonly{''},
-we can define:
-\begin{quote}
-\begin{verbatim}
-\begingroup
- \catcode`\#=\active
- \gdef#{$\sharp$}
-\endgroup
-\end{verbatim}
-\end{quote}
-and:
-\begin{quote}
-\begin{verbatim}
-\begingroup
- \lccode`\~=`\b
- \lowercase{\endgroup
- \def~{$\flat$}%
- }
-\end{verbatim}
-\end{quote}
-The second problem is one of timing: the command has to make each
-character active \emph{before} its arguments are read: this means that
-the command can't actually ``have'' arguments itself, but must be
-split in two. So we write:
-\begin{quote}
-\begin{verbatim}
-\def\chord{%
- \begingroup
- \catcode`\#=\active
- \catcode`\b=\active
- \Xchord
-}
-\def\Xchord#1{%
- \chordfont#1%
- \endgroup
-}
-\end{verbatim}
-\end{quote}
-and we can use the command as \cmdinvoke{chord}{F\#} or
-\cmdinvoke{chord}{Bb minor}.
-
-Two features of the coding are important:
-\begin{itemize}
-\item \csx{begingroup} in \csx{chord} opens a group that is closed by
- \csx{endgroup} in \csx{Xchord}; this group limits the change of
- category codes, which is the \emph{raison d'\^etre} of the whole
- exercise.
-\item Although |#| is active while \csx{Xchord} is executed, it's
- \emph{not} active when it's being defined, so that the use of |#1|
- doesn't require any special attention.
-\end{itemize}
-
-Note that the technique used in such macros as \csx{chord}, here, is
-analogous to that used in such commands as \csx{verb}; and, in just the
-same way as \csx{verb} (see
-% beware breaking long line
-\htmlonly{``}\Qref[question]{\csx{verb} doesn't work in arguments}{Q-verbwithin}\htmlonly{''}),
-\csx{chord} won't work inside the argument of another command (the
-error messages, if they appear at all, will probably be rather odd).
-
-
-\Question[Q-csname]{Defining a macro from an argument}
-
-It's common to want a command to create another command: often one
-wants the new command's name to derive from an argument. \LaTeX{}
-does this all the time: for example, \csx{newenvironment} creates
-start- and end-environment commands whose names are derived from the
-name of the environment command.
-
-The (seemingly) obvious approach:
-\begin{quote}
-\begin{verbatim}
-\def\relay#1#2{\def\#1{#2}}
-\end{verbatim}
-\end{quote}
-doesn't work (the \TeX{} engine interprets it
-as a rather strange redefinition of |\#|). The trick is to use
-\csx{csname}, which is a \TeX{} primitive for generating command names
-from random text, together with \csx{expandafter}. The definition
-above should read:
-\begin{quote}
-\begin{verbatim}
-\def\relay#1#2{%
- \expandafter\def\csname #1\endcsname{#2}%
-}
-\end{verbatim}
-\end{quote}
-With this definition, \cmdinvoke{relay}{blah}{bleah} is equivalent to
-\csx{def}\cmdinvoke{blah}{bleah}.
-
-Note that the definition of \csx{relay} omits the braces round the
-`command name' in the \csx{newcommand} it executes. This is
-because they're not necessary (in fact they seldom are), and in this
-circumstance they make the macro code slightly more tedious.
-
-The name created need not (of course) be \emph{just} the argument:
-\begin{quote}
-\begin{narrowversion}
-\begin{verbatim}
-\def\newrace#1#2#3{\expandafter\def
- \csname start#1\endcsname{%
- #2%
- }%
- \expandafter\def
- \csname finish#1\endcsname{%
- #3%
- }%
-}
-\end{verbatim}
-\end{narrowversion}
-\begin{wideversion}
-\begin{verbatim}
-\def\newrace#1#2#3{%
- \expandafter\def\csname start#1\endcsname{%
- #2%
- }%
- \expandafter\def\csname finish#1\endcsname{%
- #3%
- }%
-}
-\end{verbatim}
-\end{wideversion}
-\end{quote}
-With commands
-\begin{quote}
-\begin{verbatim}
-\def\start#1{\csname start#1\endcsname}
-\def\finish#1{\csname finish#1\endcsname}
-\end{verbatim}
-\end{quote}
-these `races' could behave a bit like \LaTeX{} environments.
-
-\Question[Q-cvtlatex]{Transcribing \LaTeX{} command definitions}
-
-At several places in this \acro{FAQ}, questions are answered in terms
-of how to program a \LaTeX{} macro. Sometimes, these macros might
-also help users of \plaintex{} or other packages; this answer
-attempts to provide a rough-and-ready guide to transcribing such macro
-definitions for use in other packages.
-
-The reason \LaTeX{} has commands that replace \csx{def}, is that
-there's a general philosophy within \LaTeX{} that the user should be
-protected from himself: the user has different commands according to
-whether the command to be defined exists (\csx{renewcommand}) or not
-(\csx{newcommand}), and if its status proves not as the user expected,
-an error is reported. A third definition command,
-\csx{providecommand}, only defines if the target is not already
-defined; \LaTeX{} has no direct equivalent of \csx{def}, which ignores
-the present state of the command. The final command of this sort is
-\csx{DeclareRobustCommand}, which creates a command which is ``robust''
-(i.e., will not expand if subjected to \LaTeX{} ``protected
-expansion''); from the \plaintex{} user's point of view,
-\csx{DeclareRobustCommand} should be treated as a non-checking version
-of \csx{newcommand}.
-
-\LaTeX{} commands are, by default, defined \csx{long}; an optional \texttt{*}
-between the \csx{newcommand} and its (other) arguments specifies that
-the command is \emph{not} to be defined \csx{long}. The \texttt{*} is
-detected by a command \csx{@ifstar} which uses \csx{futurelet} to switch
-between two branches, and gobbles the \texttt{*}: \LaTeX{} users are
-encouraged to think of the \texttt{*} as part of the command name.
-
-\LaTeX{}'s checks for unknown command are done by \csx{ifx} comparison
-of a \csx{csname} construction with \csx{relax}; since the command name
-argument is the desired control sequence name, this proves a little
-long-winded. Since \texttt{\#1} is the requisite argument, we have:
-\begin{quote}
-\begin{narrowversion}
-\begin{verbatim}
-\expandafter\ifx
- \csname
- \expandafter\@gobble\string#1%
- \endcsname
- \relax
- ...
-\end{verbatim}
-\end{narrowversion}
-\begin{wideversion}
-\begin{verbatim}
-\expandafter\ifx
- \csname\expandafter\@gobble\string#1\endcsname
- \relax
- ...
-\end{verbatim}
-\end{wideversion}
-\end{quote}
-(\csx{@gobble} simply throws away its argument).
-
-The arguments of a \LaTeX{} command are specified by two optional
-arguments to the defining command: a count of arguments (0--9: if the
-count is 0, the optional count argument may be omitted), and a default
-value for the first argument, if the defined command's first argument
-is to be optional. So:
-\begin{quote}
-\begin{verbatim}
-\newcommand\foo{...}
-\newcommand\foo[0]{...}
-\newcommand\foo[1]{...#1...}
-\newcommand\foo[2][boo]{...#1...#2...}
-\end{verbatim}
-\end{quote}
-In the last case, \csx{foo} may be called as \cmdinvoke{foo}{goodbye},
-which is equivalent to \cmdinvoke{foo}[boo]{goodbye} (employing the
-default value given for the first argument), or as
-\cmdinvoke{foo}[hello]{goodbye} (with an explicit first argument).
-
-Coding of commands with optional arguments is exemplified by the
-coding of the last \csx{foo} above:
-\begin{quote}
-\begin{verbatim}
-\def\foo{\futurelet\next\@r@foo}
-\def\@r@foo{\ifx\next[%
- \let\next\@x@foo
- \else
- \def\next{\@x@foo[boo]}%
- \fi
- \next
-}
-\def\@x@foo[#1]#2{...#1...#2...}
-\end{verbatim}
-\end{quote}
-
-\Question[Q-empty]{Detecting that something is empty}
-
-Suppose you need to know that the argument of your command is empty:
-that is, to distinguish between \cmdinvoke{cmd}{\relax} % \relax doesn't print
-and \cmdinvoke{cmd}{blah}. This is pretty simple:
-\begin{quote}
-\begin{verbatim}
-\def\cmd#1{%
- \def\tempa{}%
- \def\tempb{#1}%
- \ifx\tempa\tempb
- <empty case>
- \else
- <non-empty case>
- \fi
-}
-\end{verbatim}
-\end{quote}
-The case where you want to ignore an argument that consists of nothing
-but spaces, rather than something completely empty, is more tricky.
-It's solved in the code fragment \Package{ifmtarg}, which defines
-commands \csx{@ifmtarg} and \csx{@ifnotmtarg}, which examine their
-first argument, and select (in opposite directions) their second or
-third argument. The package's code also appears in the \LaTeX{}
-\Class{memoir} class.
-
-\Package{Ifmtarg} makes challenging reading; there's also a discussion of the
-issue in number two of the ``around the bend'' articles by the late
-lamented Mike Downes.
-\begin{ctanrefs}
-\item[\nothtml{\rmfamily}Around the bend series]\CTANref{aro-bend}
-\item[ifmtarg.sty]\CTANref{ifmtarg}
-\item[memoir.cls]\CTANref{memoir}
-\end{ctanrefs}
-
-\Question[Q-whatengine]{Am I using \pdftex{}, \xetex{} or \luatex{}?}
-\AliasQuestion{Q-ifpdf}
-
-You often need to know what ``engine'' your macros are running on (the
-engine is the \tex{}-derivative or \tex{}-alike processor that
-typesets your document). The reason that you need to know is that the
-set of functions available in each engine is different. Thus, for
-\tex{} macros to run on any engine, they need to ``know'' what they
-can and cannot do, which depends on the engine in use. Getting the
-right answer is surprisingly tricky (see below for an elaboration of
-one apparently simple test).
-
-There is now a comprehensive set of packages that answer the question
-for you. They all create a \tex{} conditional command:
-\begin{itemize}
-\item \Package{ifpdf} creates a command \csx{ifpdf},
-\item \Package{ifxetex} creates a command \csx{ifxetex} and
-\item \Package{ifluatex} creates a command \csx{ifluatex}.
-\end{itemize}
-These \tex{} commands may be used within the \latex{} conditional
-framework, as (for example):
-\begin{quote}
- \csx{ifthenelse}\texttt{\obracesymbol{}}\cmdinvoke{boolean}{pdf}\texttt{\cbracesymbol{}}\texttt{\obracesymbol{}}\meta{if pdf}\texttt{\cbracesymbol{}}\texttt{\obracesymbol{}}\meta{if not pdf}\texttt{\cbracesymbol{}}
-\end{quote}
-
-The \Package{ifxetex} package also provides a command
-\csx{RequireXeTeX} which creates an error if the code is not running
-under \xetex{}; while the other packages don't provide such a command,
-it's not really difficult to write one for yourself.
-
-% khalighi's iftex package, too -- \require's for all engines, but i'm
-% not entirely sure of the conditionals, so "for later" if at all
-
-Now for those who want to do the job for themselves: here's a
-discussion of doing the job for \pdftex{} and \csx{ifpdf}~--- the
-eager programmer can regenerate \csx{ifxetex} or \csx{ifluatex} in the
-same fashion. It's not recommended\dots
-
-Suppose you need to test whether your output will be \acro{PDF} or
-\acro{DVI}. The natural thing is to check whether you have access to
-some \PDFTeX{}-only primitive; a good one to try (not least because it
-was present in the very first releases of \PDFTeX{}) is
-\csx{pdfoutput}. So you try
-\begin{quote}
-\begin{verbatim}
-\ifx\pdfoutput\undefined
- ... % not running PDFTeX
-\else
- ... % running PDFTeX
-\fi
-\end{verbatim}
-\end{quote}
-Except that neither branch of this conditional is rock-solid. The
-first branch can be misleading, since the ``awkward'' user could have
-written:
-\begin{quote}
-\begin{verbatim}
-\let\pdfoutput\undefined
-\end{verbatim}
-\end{quote}
-so that your test will falsely choose the first alternative. While
-this is a theoretical problem, it is unlikely to be a major one.
-
-More important is the user who loads a package that uses
-\LaTeX{}-style testing for the command name's existence (for example,
-the \LaTeX{} \Package{graphics} package, which is useful even to the
-\plaintex{} user). Such a package may have gone ahead of you, so the
-test may need to be elaborated:
-\begin{quote}
-\begin{verbatim}
-\ifx\pdfoutput\undefined
- ... % not running PDFTeX
-\else
- \ifx\pdfoutput\relax
- ... % not running PDFTeX
- \else
- ... % running PDFTeX
- \fi
-\fi
-\end{verbatim}
-\end{quote}
-If you only want to know whether some \PDFTeX{} extension (such as
-marginal kerning) is present, you can stop at this point: you know as
-much as you need.
-
-However, if you need to know whether you're creating \acro{PDF}
-output, you also need to know about the value of \csx{pdfoutput}:
-\begin{quote}
-\begin{verbatim}
-\ifx\pdfoutput\undefined
- ... % not running PDFTeX
-\else
- \ifx\pdfoutput\relax
- ... % not running PDFTeX
- \else
- % running PDFTeX, with...
- \ifnum\pdfoutput>0
- ... % PDF output
- \else
- ... % DVI output
- \fi
- \fi
-\fi
-\end{verbatim}
-\end{quote}
-\begin{ctanrefs}
-\item[ifpdf.sty]Distributed as part Heiko Oberdiek's bundle
- \CTANref{oberdiek}[ifpdf]
-\item[ifluatex.sty]Distributed as part of Heiko Oberdiek's bundle
- \CTANref{oberdiek}[ifluatex]
-\item[ifxetex.sty]\CTANref{ifxetex}
-\end{ctanrefs}
-\LastEdit{2012-02-13}
-
-\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
-primitive \texttt{\$\ ...\ \$}; except for checking that you're not
-attempting to open a maths environment when you're already in one, or
-attempting to close one when you're not.
-However, \csx{[}\texttt{\ ...\ }\csx{]} has a more significant
-difference from \texttt{\$\$\ ...\ \$\$}: the primitive 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*}''.
-\LastEdit{2013-09-27}
-
-\Question[Q-atsigns]{\csx{@} and \texttt{@} in macro names}
-
-Macro names containing \texttt{@} are \emph{internal} to \LaTeX{}, and
-without special treatment just don't work in ordinary use. A nice
-example of the problems caused is discussed in % ! beware line break
-\Qref*{\csx{@} in vertical mode}{Q-atvert}''.
-
-The problems users see are caused by copying bits of a class
-(\extension{cls} file) or
-package (\extension{sty} file) into a document, or by including a class or
-package file into a \LaTeX{} document by some means other than
-\csx{documentclass} or \csx{usepackage}. \LaTeX{} defines internal
-commands whose names contain the character \texttt{@} to
-avoid clashes between its internal names and names that we would
-normally use in our documents. In order that these commands may work
-at all, \csx{documentclass} and \csx{usepackage} play around with the
-meaning of \texttt{@}.
-
-If you've included a file some other way (for example, using
-\csx{input}), you can probably solve the problem by using the correct
-command.
-
-If you're using a fragment of a package or class, you may well feel
-confused: books such as the first edition of the % ! line break
-\Qref*{The \LaTeX{} Companion}{Q-latex-books}
-are full of fragments of packages as examples for you to employ.
-The second edition of the \emph{Companion} makes clearer how you
-should use these fragments, and in addition, the code of
-all the examples is now available on \acro{CTAN}.
-To see the technique in practice, look at the example below, from file
-\File{2-2-7.ltx} in the \emph{Companion} examples directory:
-\begin{quote}
-\begin{verbatim}
-\makeatletter
-\renewcommand\subsection{\@startsection
- {subsection}{2}{0mm}%name, level, indent
- {-\baselineskip}% beforeskip
- {0.5\baselineskip}% afterskip
- {\normalfont\normalsize\itshape}}% style
-\makeatother
-\end{verbatim}
-\end{quote}
-(That example appears on page 29 of \emph{The \LaTeX{} Companion},
-second edition.)
-
-The alternative is to treat all these fragments as a package proper,
-bundling them up into a \extension{sty} file and including them with
-\csx{usepackage}; this way you hide your \LaTeX{} internal code somewhere
-that \LaTeX{} internal code is expected, which often looks `tidier'.
-\begin{ctanrefs}
-\item[\nothtml{\rmfamily}Examples from the Companion]\CTANref{tlc2}
-\end{ctanrefs}
-\LastEdit{2011-06-01}
-
-\Question[Q-protect]{What's the reason for `protection'?}
-
-Sometimes \LaTeX{} saves data it will reread later. These data are
-often the argument of some command; they are the so-called moving
-arguments. (`Moving' because data are moved around.) Candidates
-are all arguments that may go into table of contents, list of figures,
-\emph{etc}.; namely, data that are written to an auxiliary file and
-read in later. Other places are those data that might appear in head-
-or footlines. Section headings and figure captions are the most
-prominent examples; there's a complete list in Lamport's book
-(see \Qref[question]{\TeX{}-related books}{Q-latex-books}).
-
-What's going on really, behind the scenes? The commands in moving
-arguments are normally expanded to their internal structure during the
-process of saving. Sometimes this expansion results in invalid \TeX{}
-code, which shows either during expansion or when the code is
-processed again. Protecting a command, using
-``\csx{protect}\csx{cmd}'' tells \LaTeX{} to save \csx{cmd} as
-\csx{cmd}, without expanding it at all.
-
-So, what is a `fragile command'?~--- it's a command that expands into
-illegal \TeX{} code during the save process.
-
-What is a `robust command'?~--- it's a command that expands into legal
-\TeX{} code during the save process.
-
-Lamport's book says in its description of every LaTeX command whether
-it is `robust' or `fragile'; it also says that every command with an
-optional argument is fragile. The list isn't reliable, and neither
-is the assertion about optional arguments; the statements may have
-been true in early versions of \LaTeXe{} but are not any longer
-necessarily so:
-\begin{itemize}
-\item Some fragile commands, such as \csx{cite}, have been made robust
- in later revisions of \LaTeX{}.
-\item Some commands, such as \csx{end} and \csx{nocite}, are fragile
- even though they have no optional arguments.
-\item The ``user's way'' of creating a command with an optional
- argument (using \csx{newcommand} or \csx{newcommand*}) now always
- creates a robust command (though macros without optional arguments
- may still be fragile if they do things that are themselves fragile).
-\item There is no reason that a package author should not also make
- robust commands with optional arguments as part of the package.
-\item Some robust commands are redefined by certain packages to be
- fragile (the \csx{cite} command commonly suffers this treatment).
-\end{itemize}
-Further, simply ``hiding'' a fragile command in another command, has
-no effect on fragility. So, if \csx{fred} is fragile, and you write:
-\begin{quote}
-\begin{verbatim}
-\newcommand{\jim}{\fred}
-\end{verbatim}
-\end{quote}
-then \csx{jim} is fragile too. There is, however, the
-\csx{newcommand}-replacement \csx{DeclareRobustCommand}, which
-\emph{always} creates a robust command (whether or not it has optional
-arguments). The syntax of \csx{DeclareRobustCommand} is substantially
-identical to that of \csx{newcommand}, and if you do the wrapping
-trick above as:
-\begin{quote}
-\begin{verbatim}
-\DeclareRobustCommand{\jim}{\fred}
-\end{verbatim}
-\end{quote}
-then \csx{jim} is robust.
-
-Finally, we have the \Package{makerobust} package, which defines
-\csx{MakeRobustCommand} to convert a command to be robust. With the
-package, the ``wrapping'' above can simply be replaced by:
-\begin{quote}
-\begin{verbatim}
-\MakeRobustCommand\fred
-\end{verbatim}
-\end{quote}
-Whereafter, \csx{fred} is robust. Using the package may be reasonable
-if you have lots of fragile commands that you need to use in moving
-arguments.
-
-In short, the situation is confusing. No-one believes this is
-satisfactory; the \LaTeX{} team have removed the need for
-protection of some things, but the techniques available in
-current \LaTeX{} mean that this is an expensive exercise. It remains
-a long-term aim of the team to remove all need for \csx{protect}ion.
-\begin{ctanrefs}
-\item[makerobust.sty]Distributed as part of Heiko Oberdiek's bundle
- \CTANref{oberdiek}[makerobust]
-\end{ctanrefs}
-\LastEdit{2011-06-01}
-
-\Question[Q-edef]{\csx{edef} does not work with \csx{protect}}
-
-Robust \LaTeX{} commands are either ``naturally robust''~--- meaning that
-they never need \csx{protect}, or ``self-protected''~--- meaning that
-they have \csx{protect} built in to their definition in some
-way. Self-protected commands, and fragile commands with
-\csx{protect}ion are only robust in a context where the \csx{protect}
-mechanism is properly handled. The body of an \csx{edef} definition
-doesn't handle \csx{protect} properly, since \csx{edef} is a \TeX{}
-primitive rather than a \LaTeX{} command.
-
-This problem is resolved by a \LaTeX{} internal command
-\csx{protected@edef}, which does the job of \csx{edef} while keeping the
-\csx{protect} mechanism working. There's a corresponding
-\csx{protected@xdef} which does the job of \csx{xdef}.
-
-Of course, these commands need to be tended carefully, since they're
-% beware line break on next line
-internal: see \Qref[question]{'@' in control sequence names}{Q-atsigns}.
-
-\Question[Q-ltxcmds]{The definitions of \LaTeX{} commands}
-
-There are several reasons to want to know the definitions of \LaTeX{}
-commands: from the simplest ``idle curiosity'', to the pressing need
-to patch something to make it ``work the way you want it''. None of
-these are \emph{pure} motives, but knowledge and expertise seldom
-arrive through the purest of motives.
-
-Using a \tex{} executable of some sort, the simple answer is to try
-\csx{show}, in a run that is taking commands from the terminal:
-\begin{quote}
-\begin{verbatim}
-*\makeatletter
-*\show\protected@edef
-> \protected@edef=macro:
-->\let \@@protect \protect
- \let \protect \@unexpandable@protect
- \afterassignment \restore@protect \edef .
-\end{verbatim}
-\end{quote}
-(I've rearranged the output there, from the rather confused version
-\TeX{} itself produces.)
-
-So, what about \csx{@unexpandable@protect}?:
-\begin{quote}
-\begin{verbatim}
-*\show\@unexpandable@protect
-> \@unexpandable@protect=macro:
-->\noexpand \protect \noexpand .
-\end{verbatim}
-\end{quote}
-and we're starting to see how one part of the \csx{protect}ion
-mechanism works (one can probably fairly safely guess what
-\csx{restore@protect} does).
-
-Many kernel commands are declared robust:
-\begin{quote}
-\begin{verbatim}
-*\show\texttt
-> \texttt=macro:
-->\protect \texttt .
-\end{verbatim}
-\end{quote}
-so that \csx{show} isn't much help. Define a command \csx{pshow} as
-shown below, and simply execute the command to find its definition:
-\begin{quote}
-\begin{verbatim}
-*\def\pshow#1{{\let\protect\show #1}}
-*\pshow\texttt
-> \texttt =\long macro:
-#1->\ifmmode \nfss@text {\ttfamily #1}%
- \else \hmode@bgroup \text@command {#1}%
- \ttfamily \check@icl #1\check@icr
- \expandafter \egroup \fi .
-\end{verbatim}
-\end{quote}
-Note that the command name that is protected is the `base' command,
-with a space appended. This is cryptically visible, in a couple of
-places above. (Again, the output has been sanitised.)
-% Similar provisions are made in the package \Package{show2e} but i
-% don't understand them yet...
-
-The command \ProgName{texdef} (or \ProgName{latexdef}~--- the same
-command with a different name) will do all that for you and return the
-results slightly more tidily than \latex{} itself manages. For
-example:
-\begin{quote}
-\begin{verbatim}
-$ latexdef texttt
-\end{verbatim}
-\end{quote}
-gives:
-\begin{quote}
-\begin{verbatim}
-macro:->\protect \texttt
-
-\texttt :
-#1->\ifmmode \nfss@text {\ttfamily #1}%
- \else \hmode@bgroup \text@command {#1}%
- \ttfamily \check@icl #1\check@icr
- \expandafter \egroup \fi .
-\end{verbatim}
-\end{quote}
-(again, the output has been sanitised~--- but we see that
-\ProgName{latexdef} has useful `intelligence' in it, as it has spotted
-and dealt with the \csx{protect}.)
-
-With the \texttt{-s} switch, \ProgName{latexdef} will give you a
-source location:
-\begin{quote}
-\begin{verbatim}
-$ latexdef -s texttt
-% latex.ltx, line 3736:
-\DeclareTextFontCommand{\texttt}{\ttfamily}
-\end{verbatim}
-\end{quote}
-though one should note that it doesn't give you the detail of the
-actual coding, merely the definition's location.
-
-Environments also surrender their details to \ProgName{latexdef}:
-\begin{quote}
-\begin{wideversion}
-\begin{verbatim}
-$ latexdef -E itemize
-
-\itemize:
-macro:->\ifnum \@itemdepth >\thr@@ \@toodeep
- \else \advance \@itemdepth \@ne
- \edef \@itemitem {labelitem\romannumeral \the \@itemdepth}%
- \expandafter \list \csname \@itemitem \endcsname
- {\def \makelabel ##1{\hss \llap {##1}}}%
- \fi
-
-\enditemize:
-macro:->\global \advance \@listdepth \m@ne \endtrivlist
-\end{verbatim}
-\end{wideversion}
-\begin{narrowversion}
-\begin{verbatim}
-$ latexdef -E itemize
-
-\itemize:
-macro:->\ifnum \@itemdepth >\thr@@ \@toodeep
- \else \advance \@itemdepth \@ne
- \edef \@itemitem {labelitem\romannumeral
- \the \@itemdepth}%
- \expandafter \list
- \csname \@itemitem \endcsname
- {\def \makelabel ##1{\hss \llap {##1}}}%
- \fi
-
-\enditemize:
-macro:->\global \advance \@listdepth \m@ne
- \endtrivlist
-\end{verbatim}
-\end{narrowversion}
-\end{quote}
-(Yet again, this is a sanitised version of the macro definition
-output, which appears as a single very wide line for each definition.)
-
-If one has a malleable text editor, the same investigation may be
-conducted by examining the file \File{latex.ltx} (which is usually to
-be found, in a \acro{TDS} system, in directory \path{tex/latex/base}).
-
-In fact, \File{latex.ltx} is the product of a \ProgName{docstrip}
-process on a large number of \Qref*{\extension{dtx} files}{Q-dtx}, and
-you can refer to those instead. The \LaTeX{} distribution includes a file
-\File{source2e.tex}, and most systems retain it, again in
-\path{tex/latex/base}. \File{Source2e.tex} may be processed to
-provide a complete source listing of the \LaTeX{} kernel (in fact the
-process isn't entirely straightforward, but the file produces messages
-advising you what to do). The result is a huge document, with a
-line-number index of control sequences the entire kernel and a
-separate index of changes recorded in each of the files since the
-\LaTeX{} team took over.
-
-The printed kernel is a nice thing to have, but it's unwieldy and sits
-on my shelves, seldom used. One problem is that the comments are
-patchy: the different modules range from well and lucidly documented,
-through modules documented only through an automatic process that
-converted the documentation of the source of \LaTeXo{}, to modules
-that hardly had any useful documentation even in the \LaTeXo{} original.
-
-In fact, each kernel module \extension{dtx} file will process separately
-through \LaTeX{}, so you don't have to work with the whole of
-\File{source2e}. You can easily determine which module defines the
-macro you're interested in: use your ``malleable text editor'' to find
-the definition in \File{latex.ltx}; then search backwards from that
-point for a line that starts % ! line break
-\texttt{\textpercent{}\textpercent{}\textpercent{}\ From File:}~--- that line
-tells you which \extension{dtx} file contains the definition you are interested
-in. Doing this for \csx{protected@edef}, we find:
-\begin{quote}
-\begin{verbatim}
-%%% From File: ltdefns.dtx
-\end{verbatim}
-\end{quote}
-When we come to look at it, \File{ltdefns.dtx} proves to contain
-quite a dissertation on the methods of handling \csx{protect}ion; it
-also contains some automatically-converted \LaTeXo{} documentation.
-
-And of course, the kernel isn't all of \LaTeX{}: your command may be
-defined in one of \LaTeX{}'s class or package files. For example, we
-find a definition of \csx{thebibliography} in \Class{article}, but
-there's no \File{article.dtx}. Some such files are generated from
-parts of the kernel, some from other files in the distribution. You
-find which by looking at the start of the file: in \File{article.cls},
-we find:
-\begin{quote}
-\begin{verbatim}
-%% This is file `article.cls',
-%% generated with the docstrip utility.
-%%
-%% The original source files were:
-%%
-%% classes.dtx (with options: `article')
-\end{verbatim}
-\end{quote}
-so we need to format \File{classes.dtx} to see the definition in
-context.
-
-All these .dtx files are on \acro{CTAN} as part of the main \LaTeX{}
-distribution.
-\begin{ctanrefs}
-\item[\nothtml{\rmfamily}\LaTeX{} distribution]\CTANref{latex}
-\item[texdef,\nothtml{\rmfamily aka} latexdef]\CTANref{texdef}
-\end{ctanrefs}
-\LastEdit{2013-09-27}
-
-\Question[Q-oarglikesect]{Optional arguments like \csx{section}}
-
-Optional arguments, in macros defined using \csx{newcommand}, don't
-quite work like the optional argument to \csx{section}. The default
-value of \csx{section}'s optional argument is the value of the
-mandatory argument, but \csx{newcommand} requires that you `know' the
-value of the default beforehand.
-
-The requisite trick is to use a macro in the optional argument:
-\begin{quote}
-\begin{verbatim}
-\documentclass{article}
-\newcommand\thing[2][\DefaultOpt]{%
- \def\DefaultOpt{#2}%
- optional arg: #1, mandatory arg: #2%
-}
-\begin{document}
-\thing{manda}% #1=#2
-
-\thing[opti]{manda}% #1="opti"
-\end{document}
-\end{verbatim}
-\end{quote}
-\LaTeX{} itself has a trickier (but less readily understandable)
-method, using a macro \csx{@dblarg}; inside \LaTeX{}, the example
-above would have been programmed:
-\begin{quote}
-\begin{verbatim}
-\newcommand\thing{\@dblarg\@thing}
-\newcommand\@thing[2][\@error]{%
- optional arg: #1, mandatory arg: #2%
-}
-\end{verbatim}
-\end{quote}
-In that code, \csx{@thing} is only ever called with an optional and a
-mandatory argument; if the default from the \csx{newcommand} is
-invoked, a bug in user code has bitten\dots{}
-
-\Question[Q-twooptarg]{More than one optional argument}
-
-If you've already read % ! line break
-``\Qref*[question]{breaking the 9-argument limit}{Q-moren9}''.
-you can probably guess the ``simple'' solution to this problem:
-command relaying.
-
-\LaTeX{} allows commands with a single optional argument thus:
-\begin{quote}
-\begin{verbatim}
- \newcommand{\blah}[1][Default]{...}
-\end{verbatim}
-\end{quote}
-
-You may legally call such a command either with its optional argument
-present, as
-\cmdinvoke{blah}[nonDefault] or without, as \csx{blah}; in the latter
-case, the code of \csx{blah} will have an argument of |Default|.
-
-To define a command with two optional arguments, we use the relaying
-technique, as follows:
-\begin{quote}
-\begin{verbatim}
-\newcommand{\blah}[1][Default1]{%
- \def\ArgI{{#1}}%
- \BlahRelay
-}
-\newcommand\BlahRelay[1][Default2]{%
- % the first optional argument is now in
- % \ArgI
- % the second is in #1
- ...%
-}
-\end{verbatim}
-\end{quote}
-Of course, \csx{BlahRelay} may have as many mandatory arguments as are
-allowed, after allowance for the one taken up with its own
-optional argument~--- that is, 8.
-
-Variants of \csx{newcommand} (and friends), with names like
-\csx{newcommandtwoopt}, are available in the \Package{twoopt} package.
-However, if you can, it's probably better to learn to write the commands
-yourself, just to see why they're not even a good idea from the
-programming point of view.
-
-A command with two optional arguments strains the limit of what's
-sensible: obviously you can extend the technique to provide as many
-optional arguments as your fevered imagination can summon. However,
-see the comments on the use of the \Package{keyval} package, in
-``\Qref*[question]{breaking the 9-argument limit}{Q-moren9}'',
-which offers an alternative way forward.
-
-If you must, however, consider the \Package{optparams} or
-\Package{xargs} packages. \Package{Optparams}
-provides a \csx{optparams} command that you use as an intermediate in
-defining commands with up to nine optional arguments. The
-documentation shows examples of commands with four optional arguments
-(and this from an author who has his own key-value package!).
-
-The \Package{xargs} package uses a key-value package
-(\Package{xkeyval}) to \emph{define} the layout of the optional
-arguments. Thus
-\begin{quote}
-\begin{verbatim}
-\usepackage{xargs}
-...
-\newcommandx{\foo}[3][1=1, 3=n]{...}
-\end{verbatim}
-\end{quote}
-defines a command \csx{foo} that has an optional first argument
-(default 1), a mandatory second argument, and an optional third
-argument (default n).
-
-An alternative approach is offered by Scott Pakin's
-\ProgName{newcommand} program, which takes a command name and a
-definition of a set of command arguments (in a fairly
-readily-understood language), and emits \AllTeX{} macros which enable
-the command to be defined. The command requires that a
-\ProgName{Python} interpreter (etc.\@) be installed on your computer.
-\begin{ctanrefs}
-\item[newcommand.py]\CTANref{newcommand}
-\item[optparams.sty]Distributed as part of \CTANref{sauerj}[optparams]
-\item[twoopt.sty]Distributed as part of \CTANref{oberdiek}[twoopt]
-\item[xargs.sty]\CTANref{xargs}
-\item[xkeyval.sty]\CTANref{xkeyval}
-\end{ctanrefs}
-
-\Question[Q-cmdstar]{Commands defined with * options}
-
-\LaTeX{} commands commonly have ``versions'' defined with an asterisk
-tagged onto their name: for example \csx{newcommand} and
-\csx{newcommand*} (the former defines a \csx{long} version of the
-command).
-
-The simple-minded way for a user to write such a command involves use
-of the \Package{ifthen} package:
-\begin{wideversion}
-\begin{quote}
-\begin{verbatim}
-\newcommand{\mycommand}[1]{\ifthenelse{\equal{#1}{*}}%
- {\mycommandStar}%
- {\mycommandNoStar{#1}}%
-}
-\newcommand{\mycommandStar}{starred version}
-\newcommand{\mycommandNoStar}[1]{normal version}
-\end{verbatim}
-\end{quote}
-\end{wideversion}
-\begin{narrowversion}
-\begin{quote}
-\begin{verbatim}
-\newcommand{\mycommand}[1]{%
- \ifthenelse{\equal{#1}{*}}%
- {\mycommandStar}%
- {\mycommandNoStar{#1}}%
-}
-\newcommand{\mycommandStar}%
- {starred version}
-\newcommand{\mycommandNoStar}[1]%
- {normal version}
-\end{verbatim}
-\end{quote}
-\end{narrowversion}
-This does the trick, for sufficiently simple commands, but it has
-various tiresome failure modes, and it requires \csx{mycommandnostar}
-to take an argument.
-
-The \LaTeX{} kernel does a lot of this, and has its own command,
-\csx{@ifstar} (which needs `internal command protection', cf.
-\begin{quote}
-\begin{wideversion}
-\begin{verbatim}
-\makeatletter
-\newcommand{\mycommand}{%
- \@ifstar
- \mycommandStar%
- \mycommandNoStar%
-\makeatother
-}
-\newcommand{\mycommandStar}{starred version}
-\newcommand{\mycommandNoStar}{normal version}
-\end{verbatim}
-\end{wideversion}
-\begin{narrowversion}
-\begin{verbatim}
-\makeatletter
-\newcommand{\mycommand}{\@ifstar
- \mycommandStar%
- \mycommandNoStar%
-}
-\makeatother
-\newcommand{\mycommandStar}{starred version}
-\newcommand{\mycommandNoStar}{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 that the definition 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}
-
-For those of an adventurous disposition, a further option is to use
-the \Package{xparse} package from the \Package{l3packages}
-distribution. The package defines a bunch of commands (such as
-\csx{NewDocumentCommand}) which are somewhat analagous to
-\csx{newcommand} and the like, in \latexe{}. The big difference is
-the specification of command arguments; for each argument, you have a
-set of choices in the command specification. So, to create a
-*-command (in \latexe{} style), one might write:
-\begin{quote}
-\begin{verbatim}
-\NewDocumentCommand \foo { s m } {%
- % #1 is the star indicator
- % #2 is a mandatory argument
- ...
-}
-\end{verbatim}
-\end{quote}
-The ``star indicator'' (\texttt{s}) argument appears as \texttt{\#1}
-and will take values \csx{BooleanTrue} (if there was a star) or
-\csx{BooleanFalse} (otherwise); the other (\texttt{m}) argument is a
-normal \tex{}-style mandatory argument, and appears as \texttt{\#2}.
-
-While \Package{xparse} provides pleasing command argument
-specifications, it \emph{is} part of the % ! line break
-\Qref*{\latex{}~3 experimental harness}{Q-LaTeX3}.
-Simply loading the package to provide \csx{DeclareDocumentCommand}
-``pulls in'' all of the \latex{}3 kernel (a large bunch of packages)
-via the \Package{expl3} package.
-\begin{ctanrefs}
-\item[ifthen.sty]Part of the \LaTeX{} distribution
-\item[suffix.sty]Distributed as part of \CTANref{bigfoot}[suffix]
-\item[xparse.sty]Distributed as part of \CTANref{l3packages}[xparse]
-\item[expl3.sty]Distributed as part of \CTANref{l3kernel}[expl3]
-\end{ctanrefs}
-\LastEdit{2014-04-04}
-
-\nothtml{\hrule height 0pt \nobreak\vskip0pt plus2.5in\vskip 0pt\relax}
-\Question[Q-ltxabbrv]{\LaTeX{} internal ``abbreviations'', etc.}
-
-In the deeps of time, when \TeX{} first happened, computers had
-extremely limited memory, and were (by today's standards) painfully
-slow. When \LaTeX{} came along, things weren't much better, and even
-when \LaTeXe{} appeared, there was a strong imperative to save memory
-space (and to a lesser extent) \acro{CPU} time.
-
-From the very earliest days, Knuth used shortcut macros to speed
-things up. \LaTeX{}, over the years, has extended Knuth's list by a
-substantial amount. An interesting feature of the ``abbreviations'' is
-that on paper, they may look longer than the thing they stand for;
-however, to \AllTeX{} they \emph{feel} smaller\dots{}
-
-The table at the end of this answer lists the commonest of these
-``abbreviations''. It is not complete; as always, if the table
-doesn't help, try the \LaTeX{} source. The table lists each
-abbreviation's \emph{name} and its \emph{value}, which provide most of
-what a user needs to know. The table also lists the abbreviation's
-\emph{type}, which is a trickier concept: if you need to know, the
-only real confusion is that the abbreviations labelled `defn' are
-defined using an \csx{\emph{xxxx}def} command.
-
-\begin{tabular}{lll}
-Name \tbamp Type \tbamp Value \tbeol
-\tbhline
-\csx{m@ne} \tbamp count \tbamp \ensuremath{-1} \tbeol
-\csx{p@} \tbamp dimen \tbamp 1pt \tbeol
-\csx{z@} \tbamp dimen \tbamp 0pt \tbeol
-\csx{z@skip} \tbamp skip \tbamp 0pt plus 0pt minus 0pt \tbeol
-\tbhline
-\csx{@ne} \tbamp defn \tbamp 1 \tbeol
-\csx{tw@} \tbamp defn \tbamp 2\tbeol
-\csx{thr@@} \tbamp defn \tbamp 3 \tbeol
-\csx{sixt@@n} \tbamp defn \tbamp 16 \tbeol
-\csx{@cclv} \tbamp defn \tbamp 255 \tbeol
-\csx{@cclvi} \tbamp defn \tbamp 256 \tbeol
-\csx{@m} \tbamp defn \tbamp 1000 \tbeol
-\csx{@M} \tbamp defn \tbamp 10000 \tbeol
-\csx{@MM} \tbamp defn \tbamp 20000 \tbeol
-\tbhline
-\csx{@vpt} \tbamp macro \tbamp 5 \tbeol
-\csx{@vipt} \tbamp macro \tbamp 6 \tbeol
-\csx{@viipt} \tbamp macro \tbamp 7 \tbeol
-\csx{@viiipt} \tbamp macro \tbamp 8 \tbeol
-\csx{@ixpt} \tbamp macro \tbamp 9 \tbeol
-\csx{@xpt} \tbamp macro \tbamp 10 \tbeol
-\csx{@xipt} \tbamp macro \tbamp 10.95 \tbeol
-\csx{@xiipt} \tbamp macro \tbamp 12 \tbeol
-\csx{@xivpt} \tbamp macro \tbamp 14.4 \tbeol
-\csx{@xviipt} \tbamp macro \tbamp 17.28 \tbeol
-\csx{@xxpt} \tbamp macro \tbamp 20.74 \tbeol
-\csx{@xxvpt} \tbamp macro \tbamp 24.88 \tbeol
-\tbhline
-\csx{@plus} \tbamp macro \tbamp ``\texttt{plus}'' \tbeol
-\csx{@minus} \tbamp macro \tbamp ``\texttt{minus}'' \tbeol
-%\csx{hb@xt@} \tbamp macro \tbamp ``\csx{hbox} \texttt{to}''
-\end{tabular}
-
-\Question[Q-ltxhash]{Defining \LaTeX{} commands within other commands}
-
-\LaTeX{} command definition is significantly different from the \TeX{}
-primitive form discussed in an % ! line break
-\Qref*[\htmlonly]{earlier question}{Q-hash} about definitions within
-macros.
-
-In most ways, the \LaTeX{} situation is simpler (at least in part
-because it imposes more restrictions on the user); however, defining a
-command within a command still requires some care.
-
-The earlier question said you have to double the |#| signs in command
-definitions: in fact, the same rule holds, except that \LaTeX{}
-already takes care of some of the issues, by generating argument lists
-for you.
-
-The basic problem is that:
-\begin{quote}
-\begin{verbatim}
-\newcommand{\abc}[1]{joy, oh #1!%
- \newcommand{\ghi}[1]{gloom, oh #1!}%
-}
-\end{verbatim}
-\end{quote}
-followed by a call:
-\begin{quote}
-\begin{verbatim}
-\cmdinvoke{abc}{joy}
-\end{verbatim}
-\end{quote}
-typesets ``joy, oh joy!'', but defines a command \csx{ghi} that takes
-one parameter, which it ignores; \cmdinvoke{ghi}{gloom} will expand to
-``gloom, oh joy!'', which is presumably not what was expected.
-
-And (as you will probably guess, if you've read the earlier question)
-the definition:
-\begin{quote}
-\begin{verbatim}
-\newcommand{\abc}[1]{joy, oh #1!%
- \newcommand{\ghi}[1]{gloom, oh ##1!}%
-}
-\end{verbatim}
-\end{quote}
-does what is required, and \cmdinvoke{ghi}{gloom} will expand to
-``gloom, oh gloom!'', whatever the argument to \csx{abc}.
-
-The doubling is needed whether or not the enclosing command has an
-argument, so:
-\begin{quote}
-\begin{verbatim}
-\newcommand{\abc}{joy, oh joy!%
- \newcommand{\ghi}[1]{gloom, oh ##1!}%
-}
-\end{verbatim}
-\end{quote}
-is needed to produce a replica of the \csx{ghi} we defined earlier.
-
-\Question[Q-printvar]{How to print contents of variables?}
-\keywords{typeout, print variables, showthe}
-
-It is often useful to print out the values of variables in the log
-file or on the terminal. Three possible ways to print out the
-contents of \csx{textheight} variable are:
-\begin{enumerate}
-\item \csx{showthe}\csx{textheight}
-\item \cmdinvoke{message}{The text height is \csx{the}\csx{textheight}}
-\item \cmdinvoke{typeout}{The text height is \csx{the}\csx{textheight}}
-\end{enumerate}
-These techniques use the \TeX{} primitives \csx{the} (which provides
-the value of a variable), \csx{showthe} (print a variable to the
-terminal and the log, on a line of its own), and \csx{message}, which
-interpolates something into the log. The command \csx{typeout} is
-\LaTeX{}'s general message output mechanism.
-
-In each case, the variable's value is printed as a number of points.
-
-To typeset the value of \csx{textheight}, just
-\csx{the}\csx{textheight} is enough, but a more flexible alternative is
-to use the \Package{printlen} package. \Package{Printlen} allows you
-to choose the units in which you print a variable; this is useful,
-given that the most ordinary people don't think in points
-(particularly Knuth's points, of which there are 72.27 to the inch).
-
-So, using \Package{printlen}, we could say:
-\begin{quote}
-\begin{verbatim}
-\newlength{\foo}
-\setlength{\foo}{12pt}
-\verb|\foo| is \printlength{\foo}
-\end{verbatim}
-\end{quote}
-and get:
-\begin{quote}
-\csx{foo} is 12pt
-\end{quote}
-while, if we say:
-\begin{quote}
-\begin{verbatim}
-\newlength{\foo}
-\setlength{\foo}{12pt}
-\uselengthunit{mm}
-\verb|foo| is \printlength{\foo}
-\end{verbatim}
-\end{quote}
-we get:
-\begin{quote}
-\csx{foo} is 4.21747mm
-\end{quote}
-\begin{ctanrefs}
-\item[printlen.sty]\CTANref{printlen}
-\end{ctanrefs}
-\LastEdit{2012-03-16}
-
-\Question[Q-labelcount]{Using labels as counter values}
-
-Labels are tempting sources of `numbers'~--- their most common use,
-after all, is simply to typeset a number. However, their seeming
-simplicity is deceptive; the packages \Package{babel} and
-\Package{hyperref}, at least, fiddle with the definition of
-\csx{ref} and \csx{pageref} in ways that make
-\begin{quote}
-\begin{verbatim}
-\setcounter{foo}{\ref{bar}}
-\end{verbatim}
-\end{quote}
-(etc.\@) not work; thus the technique may not be relied upon.
-
-The solution is to use the \Package{refcount} package (incidentally,
-by the author of \Package{hyperref}). The package provides four
-commands, all similar to:
-\begin{quote}
-\begin{verbatim}
-\usepackage{refcount}
-...
-\label{bar}
-...
-\setcounterref{foo}{bar}
-\end{verbatim}
-\end{quote}
-(the other three are \csx{addtocounterref}, \csx{setcounterpageref}
-and \csx{addtocounterpageref}).
-
-The package also provides a command
-\cmdinvoke*{getrefnumber}{label-name} that may be used where a
-`number' value is needed. For example:
-\begin{quote}
-\begin{verbatim}
-... \footnote{foo bar ...\label{foofoot}}
-...
-\footnotemark[\getrefnumber{foofoot}]
-\end{verbatim}
-\end{quote}
-which gives you a second footnote mark reference the the footnote.
-(There is also a command \csx{getpagerefnumber}, of course).
-
-The commands could be used by one determined not to use
-\Package{changepage} to determine whether % ! line break
-\Qref*{the current page is odd}{Q-oddpage}, but it's probably no more
-trouble to use the fully-developed tool in this case.
-\begin{ctanrefs}
-\item[refount.sty]Distributed as part of \CTANref{oberdiek}
-\end{ctanrefs}
-\LastEdit*{2011-09-08}
-
-\subsection{\LaTeX{} macro programming}
-
-\Question[Q-fixnam]{How to change \LaTeX{}'s ``fixed names''}
-
-\LaTeX{} document classes define several typographic operations that
-need `canned text' (text not supplied by the user). In the earliest
-days of \LaTeXo{} these bits of text were built in to the body of
-\LaTeX{}'s macros and were rather difficult to change, but ``fixed
-name'' macros were introduced for the benefit of those wishing to use
-\LaTeX{} in languages other than English.
-For example, the special section produced by the \csx{tableofcontents}
-command is always called \csx{contentsname} (or rather, what
-\csx{contentsname} is defined to mean).
-Changing the canned text is now one of the easiest customisations a
-user can do to \LaTeX{}.
-
-The canned text macros are all of the form
-\csx{\meta{thing}name}, and changing them is simplicity
-itself. Put:
-\begin{quote}
-\cmdinvoke{renewcommand}{\csx{\meta{thing}name}}{Res minor}
-\end{quote}
-in the preamble of your document, and the job is done.
-(However, beware of the \Package{babel} package, which requires you to
-use a different mechanism: be sure to check
-% beware line wrap
-\Qref[question]{changing \Package{babel} names}{Q-latexwords} if
-you're using it.)
-
-The names that are defined in the standard \LaTeX{} classes (and the
-\Package{makeidx} package) are listed
-below. Some of the names are only defined in a subset of the classes
-(and the \Class{letter} class has a set of names all of its own);
-the list shows the specialisation of each name, where appropriate.
-
-\nothtml{\noindent}\begin{tabular}{@{}ll}
-\csx{abstractname} \tbamp Abstract\tbeol
-\csx{alsoname} \tbamp see also (\Package{makeidx} package)\tbeol
-\csx{appendixname} \tbamp Appendix\tbeol
-\csx{bibname} \tbamp Bibliography (\Class{report},\Class{book})\tbeol
-\csx{ccname} \tbamp cc (\Class{letter})\tbeol
-\csx{chaptername} \tbamp Chapter (\Class{report},\Class{book})\tbeol
-\csx{contentsname} \tbamp Contents\tbeol
-\csx{enclname} \tbamp encl (\Class{letter})\tbeol
-\csx{figurename} \tbamp Figure (for captions)\tbeol
-\csx{headtoname} \tbamp To (\Class{letter})\tbeol
-\csx{indexname} \tbamp Index\tbeol
-\csx{listfigurename} \tbamp List of Figures\tbeol
-\csx{listtablename} \tbamp List of Tables\tbeol
-\csx{pagename} \tbamp Page (\Class{letter})\tbeol
-\csx{partname} \tbamp Part\tbeol
-\csx{refname} \tbamp References (\Class{article})\tbeol
-\csx{seename} \tbamp see (\Package{makeidx} package)\tbeol
-\csx{tablename} \tbamp Table (for caption)
-\end{tabular}
-
-\Question[Q-latexwords]{Changing the words \Package{babel} uses}
-
-\LaTeX{} uses symbolic names for many of the automatically-generated
-text it produces (special-purpose section headings, captions, etc.).
-As noted in \Qref[question]{``\LaTeX{} fixed names''}{Q-fixnam} (which
-includes a list of the names themselves),
-this enables the user to change the
-names used by the standard classes, which is particularly useful if
-the document is being prepared in some language other than \LaTeX{}'s
-default English. So, for example, a Danish author may wish that her
-table of contents was called ``Indholdsfortegnelse'', and so
-would expect to place a command
-\begin{verbatim}
-\renewcommand{\contentsname}%
- {Indholdsfortegnelse}
-\end{verbatim}
-in the preamble of her document.
-
-However, it's natural for a user of a non-English language to use
-\Package{babel}, because it offers many conveniences and typesetting
-niceties for those preparing documents in those languages. In
-particular, when \Package{babel} is selecting a new language, it
-ensures that \LaTeX{}'s symbolic names are translated appropriately
-for the language in question. Unfortunately, \Package{babel}'s choice
-of names isn't always to everyone's choice, and there is still a need
-for a mechanism to replace the `standard' names.
-
-Whenever a new language is selected, \Package{babel} resets all the
-names to the settings for that language. In particular,
-\Package{babel} selects the document's main language when
-\cmdinvoke{begin}{document} is executed, which immediately destroys
-any changes to these symbolic names made in the prologue of a document
-that uses \Package{babel}.
-
-Therefore, babel defines a command to enable users to change the
-definitions of the symbolic names, on a per-language basis:
-\csx{addto}\csx{captions}\texttt{\meta{language}} is the thing
-(\texttt{\meta{language}} being the language option you gave to
-\Package{babel} in the first place). For example:
-\begin{verbatim}
-\addto\captionsdanish{%
- \renewcommand{\contentsname}%
- {Indholdsfortegnelse}%
-}
-\end{verbatim}
-
-\Question[Q-running-nos]{Running equation, figure and table numbering}
-
-Many \LaTeX{} classes (including the standard \Class{book} class)
-number things per chapter; so figures in chapter 1 are numbered 1.1,
-1.2, and so on. Sometimes this is not appropriate for the user's
-needs.
-
-Short of rewriting the whole class, one may use the \Package{chngcntr}
-package, which provides commands \csx{counterwithin} (which
-establishes this nested numbering relationship) and
-\csx{counterwithout} (which undoes it).
-
-So if you have figures numbered by chapter as 1.1, 1.2, 2.1, \dots{},
-the command
-\begin{quote}
-\begin{verbatim}
-\counterwithout{figure}{chapter}
-\end{verbatim}
-\end{quote}
-will convert them to figures 1, 2, 3, \dots{}. (Note that the command
-has also removed the chapter number from the counter's definition.)
-
-More elaborate use could change things numbered per section to things
-numbered per chapter:
-\begin{quote}
-\begin{verbatim}
-\counterwithout{equation}{section}
-\counterwithin{equation}{chapter}
-\end{verbatim}
-\end{quote}
-(assuming there was a class that did such a thing in the first place...)
-
-The \Package{chngcntr} approach doesn't involve much programming, and
-the enthusiastic \LaTeX{} programmer might choose to try the technique
-that we had to use before the advent of \Package{chngcntr}. Each of
-the packages \Package{removefr} and \Package{remreset} defines a
-\csx{@removefromreset} command, and having included the package one
-writes something like:
-\begin{quote}
-\begin{verbatim}
-\makeatletter
-\@removefromreset{figure}{chapter}
-\makeatother
-\end{verbatim}
-\end{quote}
-and the automatic renumbering stops. You may then need to redefine the
-way in which the figure number (in this case) is printed:
-\begin{quote}
-\begin{verbatim}
-\makeatletter
-\renewcommand{\thefigure}{\@arabic\c@figure}
-\makeatother
-\end{verbatim}
-\end{quote}
-(remember to do the whole job, for every counter you want to
-manipulate, within \csx{makeatletter} \dots{}\@ \csx{makeatother}).
-
-This technique, too, may be used to change where in a multilevel
-structure a counter is reset. Suppose your class numbers figures as
-\meta{chapter}.\meta{section}.\meta{figure}, and you want figures
-numbered per chapter, try:
-\begin{quote}
-\begin{wideversion}
-\begin{verbatim}
-\makeatletter
-\@removefromreset{figure}{section}
-\@addtoreset{figure}{chapter}
-\renewcommand{\thefigure}{\thechapter.\@arabic\c@figure}
-\makeatother
-\end{verbatim}
-\end{wideversion}
-\begin{narrowversion}
-\begin{verbatim}
-\makeatletter
-\@removefromreset{figure}{section}
-\@addtoreset{figure}{chapter}
-\renewcommand{\thefigure}%
- {\thechapter.\@arabic\c@figure}
-\makeatother
-\end{verbatim}
-\end{narrowversion}
-\end{quote}
-(the command \csx{@addtoreset} is a part of \LaTeX{} itself).
-\begin{ctanrefs}
-\item[chngcntr.sty]\CTANref{chngcntr}
-\item[memoir.cls]\CTANref{memoir}
-\item[removefr.tex]\CTANref{removefr} (note, this is constructed as a
- ``fragment'' for use within other packages: load by
- \cmdinvoke{input}{removefr})
-\item[remreset.sty]Distributed as part of \CTANref{carlisle}[remreset]
-\end{ctanrefs}
-
-\Question[Q-labelctr]{Making labels from a counter}
-
-Suppose we have a \LaTeX{} counter, which we've defined with
-\cmdinvoke{newcounter}{foo}. We can increment the value of the counter
-by \cmdinvoke{addtocounter}{foo}{1}, but that's pretty clunky for an
-operation that happens so often \dots{}~so there's a command
-\cmdinvoke{stepcounter}{foo} that does this special case of
-increasing-by-one.
-
-There's an internal \LaTeX{} variable, the ``current label'', that
-remembers the last `labellable' thing that \LaTeX{} has processed.
-You could (if you were to insist) set that value by the relevant
-\TeX{} command (having taken the necessary precautions to ensure that
-the internal command worked)~--- but it's not necessary. If, instead
-of either of the stepping methods above, you say
-\cmdinvoke{refstepcounter}{foo}, the internal variable is set to the
-new value, and (until something else comes along), \csx{label} will
-refer to the counter.
-
-\Question[Q-oddpage]{Finding if you're on an odd or an even page}
-
-\Qref[Question]{Another question}{Q-marginparside} discusses the issue
-of getting \csx{marginpar} commands to put their output in the correct
-margin of two-sided documents. This is an example of the general
-problem of knowing where a particular bit of text lies: the output
-routine is asynchronous, and \AllTeX{} will usually process quite a
-bit of the ``next'' page before deciding to output any page. As a
-result, the |page| counter (known internally in \LaTeX{} as
-\csx{c@page}) is normally only reliable when you're actually \emph{in}
-the output routine.
-
-The solution is to use some version of the \csx{label} mechanism to
-determine which side of the page you're on; the value of the page
-counter that appears in a \csx{pageref} command has been inserted in
-the course of the output routine, and is therefore safe.
-
-However, \csx{pageref} itself isn't reliable: one might hope that
-\begin{quote}
-\begin{verbatim}
-\ifthenelse{\isodd{\pageref{foo}}}{odd}{even}
-\end{verbatim}
-\end{quote}
-would do the necessary, but both the \Package{babel} and
-\Package{hyperref} packages have been known to interfere with the
-output of \csx{pageref}; be careful!
-
-The \Package{changepage} package needs to provide this functionality
-for its own use, and therefore provides a command \csx{checkoddpage};
-this sets a private-use `label', and the page reference part of that
-label is then examined (in a \Package{hyperref}-safe way) to set a
-conditional \csx{ifoddpage} true if the command was issued on an odd
-page. (The \Class{memoir} class has the same command.) \latex{}
-users who are unfamiliar with \tex{}'s \csx{if...} commands may use
-the \Package{ifthen} package:
-\begin{wideversion}
-\begin{quote}
-\begin{verbatim}
-\usepackage{ifthen,changepage}
-...
-\checkoddpage
-\ifthenelse{\boolean{oddpage}}{<odd page stuff>}{<even page stuff>}
-\end{verbatim}
-\end{quote}
-\end{wideversion}
-\begin{narrowversion}
-\begin{quote}
-\begin{verbatim}
-\usepackage{ifthen,changepage}
-...
-\checkoddpage
-\ifthenelse{\boolean{oddpage}}%
- {<odd page stuff>}%
- {<even page stuff>}
-\end{verbatim}
-\end{quote}
-\end{narrowversion}
-
-Of course, the `label' contributes to \LaTeX{}'s ``Rerun to get
-cross-references right'' error messages\dots{}
-
-The Koma-Script classes have an \environment{addmargin*} environment
-that also provides the sorts of facilities that the \Package{changepage}
-offers. Koma-Script's supporting command:
-\begin{quote}
-\cmdinvoke{ifthispageodd}{<true>}{<false>}
-\end{quote}
-executes different things depending on the page number.
-
-The package \Package{ifoddpage} is designed to provide the same
-facility; crucially, it can behave ``sensibly'' even if you are
-typesetting for one-side printing only; like the \Package{changepage}
-it uses a `check' command \csx{checkoddpage}. The conditional `side'
-flags are set using (Plain) \TeX{} conditionals; they are defined
-locally, so that you can minimise their use of \tex{} workspace~---
-see the package documentation for the somewhat tricky sequence
-involved. In addition the package provides a command
-\csx{ifoddpageoroneside}, which is true on odd pages of a two-side
-document, or on all pages of a one-side document. Usage is:
-\begin{quote}
-\begin{verbatim}
-\checkoddpage
-\ifoddpage
- odd-side text
-\else
- even-side text
-\fi
-\end{verbatim}
-\end{quote}
-The author's recommended usage (trickily) includes the whole operation
-in a box; this has the advantage that your test will always work, but
-the usual disadvantage that boxes may not split. In common uses, the
-whole work will be done inside a box (as, for example, in the case of
-a float), so the elaborate work proposed by the author is not
-necessary.
-\begin{ctanrefs}
-\item[changepage.sty]\CTANref{changepage}
-\item[ifoddpage.sty]\CTANref{ifoddpage}
-\item[ifthen.sty]Part of the \latex{} distribution: \CTANref{latex}
-\item[\nothtml{\rmfamily}KOMA script bundle]\CTANref{koma-script}
-\item[memoir.cls]\CTANref{memoir}
-\end{ctanrefs}
-
-\Question[Q-labelformat]{How to change the format of labels}
-
-By default, when a label is created, it takes on the appearance of the
-counter labelled, so the label appears as
-\csx{the}\texttt{\meta{counter}}~--- what would be used if you
-asked to typeset the counter in your text. This isn't always what you
-need: for example, if you have nested enumerated lists with the outer
-numbered and the inner labelled with letters, one might expect to want
-to refer to items in the inner list as ``2(c)''. (Remember, you can
-\nothtml{change the structure of list items~--- }%
-\Qref{change the structure of list items}{Q-enumerate}.)
-The change is of course
-possible by explicit labelling of the parent and using that label to
-construct the typeset result~--- something like
-\begin{quote}
-\begin{verbatim}
-\ref{parent-item}(\ref{child-item})
-\end{verbatim}
-\end{quote}
-which would be both tedious and error-prone. What's more, it would be
-undesirable, since you would be constructing a visual representation
-which is inflexible (you couldn't change all the references to elements
-of a list at one fell swoop).
-
-\LaTeX{} in fact has a label-formatting command built into every label
-definition; by default it's null, but it's available for the user to
-program. For any label \meta{counter} there's a \LaTeX{} internal
-command \csx{p@}\meta{\texttt{counter}}; for example, a label definition
-on an inner list item is supposedly done using the command
-\cmdinvoke{p@enumii}{\csx{theenumii}}. Unfortunately, the internal
-workings of this aren't quite right, and you need to patch the
-\csx{refstepcounter} command:
-\begin{quote}
-\begin{narrowversion}
-\begin{verbatim}
-\renewcommand*\refstepcounter[1]{%
- \stepcounter{#1}%
- \protected@edef\@currentlabel{%
- \csname p@#1\expandafter\endcsname
- \csname the#1\endcsname
- }%
-}
-\end{verbatim}
-\end{narrowversion}
-\begin{wideversion}
-\begin{verbatim}
-\renewcommand*\refstepcounter[1]{\stepcounter{#1}%
- \protected@edef\@currentlabel{%
- \csname p@#1\expandafter\endcsname
- \csname the#1\endcsname
- }%
-}
-\end{verbatim}
-\end{wideversion}
-\end{quote}
-With the patch in place you can now, for example, change the labels on
-all inner lists by adding the following code in your preamble:
-\begin{quote}
-\begin{verbatim}
-\makeatletter
-\renewcommand{\p@enumii}[1]{\theenumi(#1)}
-\makeatother
-\end{verbatim}
-\end{quote}
-This would make the labels for second-level enumerated lists appear as
-``1(a)'' (and so on). The analogous change works for any counter that
-gets used in a \csx{label} command.
-
-In fact, the \Package{fncylab} package does all the above (including
-the patch to \LaTeX{} itself). With the package, the code above is
-(actually quite efficiently) rendered by the command:
-\begin{quote}
-\begin{verbatim}
-\labelformat{enumii}{\theenumi(#1)}
-\end{verbatim}
-\end{quote}
-In fact, the above example, which we can do in several different ways,
-has been rendered obsolete by the appearance of the \Package{enumitem}
-package, which is discussed in the answer about % ! line break
-\Qref*{decorating enumeration lists}{Q-enumerate}.
-\begin{ctanrefs}
-\item[enumitem.sty]\CTANref{enumitem}
-\item[fncylab.sty]\CTANref{fncylab}
-\end{ctanrefs}
-
-\Question[Q-seccntfmt]{Adjusting the presentation of section numbers}
-
-The general issues of adjusting the appearance of section headings are
-pretty complex, and are covered in % beware line breaks (2 lines)
-\latexhtml{question}{the question on}
-\Qref[\htmlonly]{the style of section headings}{Q-secthead}.
-
-However, people regularly want merely to change the way the section
-number appears in the heading, and some such people don't mind writing
-out a few macros. This answer is for \emph{them}.
-
-The section number is typeset using the
-\begin{dviversion}
- \LaTeX{} internal
-\end{dviversion}
-\begin{hyperversion}
- \Qref{\LaTeX{} internal}{Q-atsigns}
-\end{hyperversion}
-\csx{@seccntformat} command, which is given the ``name'' (section,
-subsection, \dots{}) of the heading, as argument. Ordinarily,
-\csx{@seccntformat}
-merely outputs the section number, and then a \csx{quad} of space:
-\begin{quote}
-\begin{verbatim}
-\renewcommand*{\@seccntformat}[1]{%
- \csname the#1\endcsname\quad
-}
-\end{verbatim}
-\end{quote}
-Suppose you want to put a stop after every section (subsection,
-subsubsection, \dots{}) number, a trivial change may be implemented by
-simple modification of the command:
-\begin{quote}
-\begin{verbatim}
-\renewcommand*{\@seccntformat}[1]{%
- \csname the#1\endcsname.\quad
-}
-\end{verbatim}
-\end{quote}
-However, many people want to modify section numbers, but not
-subsection numbers, or any of the others. To do this, one must make
-\csx{@seccntformat} switch according to its argument. The following
-technique for doing the job is slightly wasteful, but is efficient
-enough for a relatively rare operation:
-\begin{quote}
-\begin{verbatim}
-\renewcommand*{\@seccntformat}[1]{%
- \csname the#1\endcsname
- \csname adddot@#1\endcsname\quad
-}
-\end{verbatim}
-\end{quote}
-which uses a second-level command to provide the dot, if it has been
-defined; otherwise it merely appends \csx{relax} (which does nothing
-in this context). The definition of the second-level command (the
-version for the \texttt{section}, here) specifies what to put after a
-section number, but it could be used to put anything after it:
-\begin{quote}
-\begin{verbatim}
-\newcommand*{\adddot@section}{.}
-\end{verbatim}
-\end{quote}
-Note that all the command definitions above are dealing in
-\Qref*{\LaTeX{} internal commands}{Q-atsigns}, so the above
-code should be in a package file, for preference.
-
-The \Class{Koma-script} classes have different commands for specifying
-changes to section number presentation: \csx{partformat},
-\csx{chapterformat} and \csx{othersectionlevelsformat}, but otherwise
-their facilities are similar to those of ``raw'' \LaTeX{}.
-\begin{ctanrefs}
-\item[\nothtml{\rmfamily}KOMA script bundle]\CTANref{koma-script}
-\end{ctanrefs}
-
-\Question[Q-spaftend]{There's a space added after my environment}
-
-You've written your own environment \environment{env}, and it works
-except that a space appears at the start of the first line of typeset
-text after \cmdinvoke{end}{env}. This doesn't happen with similar
-\LaTeX{}-supplied environments.
-
-You could impose the restriction that your users always put a
-``\texttt{\textpercent{}}'' sign after the environment~\dots{}\nothtml{\@} but
-\LaTeX{} environments don't require that, either.
-
-The \LaTeX{} environments' ``secret'' is an internal flag which causes
-the unwanted spaces to be ignored. Fortunately, you don't have to use
-the internal form: since 1996, \LaTeX{} has had a user command
-\csx{ignorespacesafterend}, which sets the internal flag.
-
-\Question[Q-labundef]{Finding if a label is undefined}
-
-People seem to want to know (at run time) if a label is undefined (I
-don't actually understand \emph{why}, particularly: it's a transient
-state, and \LaTeX{} deals with it quite well).
-
-A resolved label is simply a command:
-\csx{r@}\texttt{\meta{label-name}}; determining if the label is set is
-then simply a matter of detecting if the command exists. The usual
-\LaTeX{} internal way of doing this is to use the command
-\csx{@ifundefined}:
-\begin{quote}
- \cmdinvoke*{@ifundefined}{\textup{r@}label-name}{undef-cmds}{def-cmds}
-\end{quote}
-In which, \meta{label-name} is exactly what you would use in
-a \csx{label} command, and the remaining two arguments are command
-sequences to be used if the label is undefined
-(\meta{undef-cmds}) or if it is defined
-(\meta{def-cmds}).
-
-Note that any command that incorporates \csx{@ifundefined} is naturally
-fragile, so remember to create it with \csx{DeclareRobustCommand} or to
-use it with \csx{protect} in a moving argument.
-
-If you're into this game, you may well not care about \LaTeX{}'s
-warning about undefined labels at the end of the document; however,
-if you are, include the command \csx{G@refundefinedtrue} in
-\meta{\texttt{undef-cmds}}.
-
-And of course, remember you're dealing in internal commands, and pay
-attention to the \Qref*{at-signs}{Q-atsigns}.
-
-All the above can be avoided by using the \Package{labelcas} package:
-it provides commands that enable you to switch according to the state
-of a single label, or the states of a list of labels. The package's
-definition is a bit complicated, but the package itself is pretty
-powerful.
-\begin{ctanrefs}
-\item[labelcas.sty]\CTANref{labelcas}
-\end{ctanrefs}
-
-\Question[Q-addtoreset]{Master and slave counters}
-
-It's common to have things numbered ``per chapter'' (for example, in
-the standard \Class{book} and \Class{report} classes, figures, tables
-and footnotes are all numbered thus). The process of resetting is
-done automatically, when the ``master'' counter is stepped (when the
-\csx{chapter} command that starts chapter \meta{n} happens, the
-\texttt{chapter} counter is stepped, and all the dependent counters are set
-to zero).
-
-How would you do that for yourself? You might want to number
-algorithms per section, or corollaries per theorem, for example. If
-you're defining these things by hand, you declare the relationship
-when you define the counter in the first place:
-\begin{quote}
-\cmdinvoke*{newcounter}{new-name}[master]
-\end{quote}
-says that every time counter \meta{master} is stepped, counter
-\meta{new-name} will be reset.
-
-But what if you have an uncooperative package, that defines the
-objects for you, but doesn't provide a programmer interface to make
-the counters behave as you want?
-
-The \csx{newcounter} command uses a \LaTeX{} internal command, and you
-can also use it:
-\begin{quote}
-\cmdinvoke*{@addtoreset}{new-name}{master}
-\end{quote}
-(but remember that it needs to be between \csx{makeatletter} and
-\csx{makeatother}, or in a package of your own).
-
-The \Package{chngcntr} package encapsulates the \csx{@addtoreset}
-command into a command \csx{counterwithin}. So:
-\begin{quote}
-\begin{verbatim}
-\counterwithin*{corrollary}{theorem}
-\end{verbatim}
-\end{quote}
-will make the corollary counter slave to theorem counters. The
-command without its asterisk:
-\begin{quote}
-\begin{verbatim}
-\counterwithin{corrollary}{theorem}
-\end{verbatim}
-\end{quote}
-will do the same, and also redefine \csx{thecorollary} as % line brk!
-\meta{theorem number}.\meta{corollary number}, which is a good scheme
-if you ever want to refer to the corollaries~--- there are potentially
-many ``corollary~1'' in any document, so it's as well to tie its number
-to the counter of the theorem it belongs to. This is true of pretty
-much any such counter-within-another; if you're not using the
-\Package{chngcntr}, refer to the answer to % line break!
-\Qref*{redefining counters' \csx{the-}commands}{Q-the-commands} for
-the necessary techniques.
-
-Note that the technique doesn't work if the master counter is |page|,
-the number of the current page. The |page| counter is stepped deep
-inside the output routine, which usually gets called some time after
-the text for the new page has started to appear: so special
-techniques are required to deal with that. One special case is dealt
-with elsewhere: \Qref*{footnotes numbered per page}{Q-footnpp}. One
-of the techniques described there, using package \Package{perpage},
-may be applied to any counter. The command:
-\begin{quote}
-\cmdinvoke*{MakePerPage}{counter}
-\end{quote}
-will cause \meta{counter} to be reset for each page. The package uses
-a label-like mechanism, and may require more than one run of \LaTeX{}
-to stabilise counter values~--- \LaTeX{} will generate the usual
-warnings about labels changing.
-\begin{ctanrefs}
-\item[chngcntr.sty]\CTANref{chngcntr}
-\item[perpage.sty]Distributed as part \CTANref{bigfoot}[perpage]
-\end{ctanrefs}
-
-\Question[Q-fontsize]{Fonts at arbitrary sizes}
-
-Almost all fonts, nowadays, are provided with \LaTeX{} control
-(\extension{fd}) files, so the temptation to risk the
-\Qref*{problems of \csx{newfont}}{Q-newfont*} is usually easy to
-resist.
-
-However, one temptation remains, arising from the way that \LaTeX{}
-restricts the sizes of fonts. In fact, the restriction only
-significantly applies to the default (Computer Modern) and the
-Cork-encoded (\acro{T}1) EC fonts, but it is widely considered to be
-anomalous, nowadays. In recognition of this problem, there is a
-package \Package{fix-cm} which will allow you to use the fonts, within
-\LaTeX{}, at any size you choose. If you're not using scaleable
-versions of the fonts, most modern distributions will just generate an
-appropriate bitmap for you.
-
-So, suppose you want to produce a heading in Computer Modern Roman at
-30 points, you might be tempted to write:
-\begin{quote}
-\begin{verbatim}
-\newfont{\bigfont}{cmr10 at 30pt}
-\begin{center}
- \bigfont Huge text
-\end{center}
-\end{verbatim}
-\end{quote}
-which will indeed work, but will actually produce a worse result than
-\begin{quote}
-\begin{verbatim}
-\usepackage{fix-cm}
-...
-\begin{center}
- \fontsize{30}{36}\selectfont
- Huge text
-\end{center}
-\end{verbatim}
-\end{quote}
-Note that the \Package{fix-cm} package was not distributed until the
-December 2003 edition of \LaTeX{}; if you have an older distribution,
-the packages \Package{type1cm} (for \acro{CM} fonts) and
-\Package{type1ec} (for \acro{EC} fonts) are available.
-
-\Package{Fix-cm} doesn't has one or two omissions~--- fonts the \latex{}
-team did not consider useful, or something; the CM dunhill fonts (as
-CM, but with stretched ascenders) and the CM fibonacci font (which is only
-available in 8-point design size) are certainly missing. If
-\Package{fix-cm} doesn't do the job, try the \Package{type1xx}
-packages, or the \Package{anyfontsize} package.
-
-A further alternative might be to switch to the
-\Qref*{\FontName{Latin} \FontName{Modern} fonts}{Q-uselmfonts} (which
-provide a close simulacrum of the \FontName{Computer}
-\FontName{Modern} set); these fonts were scaleable from their first
-distribution, and don't therefore need any such trick as the above.
-\begin{ctanrefs}
-\item[anyfontsize.sty]\CTANref{anyfontsize}
-\item[fix-cm.sty]Distributed as part of \CTANref{latex}[fix-cm] (an unpacked
- version is available at \CTANref{fix-cm})
-\item[\nothtml{\rmfamily}\FontName{Latin} \FontName{Modern} fonts]\CTANref{lm}
-\item[type1cm.sty]\CTANref{type1cm}
-\item[type1ec.sty]\CTANref{type1ec} (the package is actually part of
- the \CTANref{cm-super} distribution, but it works happily in
- the absence of the scaled fonts)
-\end{ctanrefs}
-\LastEdit{2013-06-04}
-
-\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 useful\dots{}.
-
-The nicely-named \Package{nag} allows you to apply a configurable set
-of checks to your document, as you run it through \LaTeX{}; you get
-messages like:
-\begin{quote}
-\begin{wideversion}
-\begin{verbatim}
-Package nag Warning: Command \bf is an old LaTeX 2.09 command.
-(nag) Use \bfseries or \textbf instead on input line 30.
-\end{verbatim}
-\end{wideversion}
-\begin{narrowversion}
-\begin{verbatim}
-Package nag Warning: Command \bf is an old
- LaTeX 2.09 command.
-(nag) Use \bfseries or \textbf
- instead on input line 30.
-\end{verbatim}
-\end{narrowversion}
-\end{quote}
-\begin{wideversion}
- (the package provides a demo file which contains most of the sorts
- of errors you might make~--- the example is one of them).
-\end{wideversion}
-\begin{narrowversion}
- (the error lines above represent two lines which have been wrapped;
- the package provides a demo file which contains most of the sorts of
- errors you might make~--- the example is one of them).
-\end{narrowversion}
-While \Package{l2tabu} and \Package{nag} alert you to \emph{possible}
-programming errors, you should not forget that they are merely
-commenting on \emph{style}; don't assume that a \Package{nag} error is
-going to damn your code~--- rather, note the issue and try to train
-your fingers not to do the same ``next time''.
-
-The \ProgName{lacheck} program analyses your source and comments on
-it; its view of what is ``bad'' is \emph{very} subjective (the
-documentation says), but it can be useful.
-
-There's also a web site
-\href{http://www.kohm.name/markus/texidate.html}{TeXidate}
-which will do a static analysis of your document (unfortunately, you
-have to paste your document source into a text window). The site
-doesn't seem as comprehensive as \Package{nag}, but it allows you to
-download its script, which you can then juggle with to make it more
-draconian.
-\begin{ctanrefs}
-\item[l2tabu]Browse \CTANref{l2tabu} for a copy of the document in a
- language that is convenient for you
-\item[lacheck]\CTANref{lacheck}
-\item[nag.sty]\CTANref{nag}
-\end{ctanrefs}
-\LastEdit{2012-10-09}
-
-\Question[Q-ltx-csv]{Process a \acro{CSV} file in \latex{}}
-
-Comma-separated-variable (\acro{CSV}) files are a common means of
-interchanging simple data between applications; for example, most
-spreadsheet applications can provide files containing tables of
-numbers with commas between them. One can envisage these tables as
-``\latex{} tables'', and the packages to process them all provide
-table generation, one way or another.
-
-For rather a long time, the canonical tools for dealing with such
-files have been those provided in the \Package{datatool} bundle;
-packages in the bundle allow the user to write procedures to process
-numbers, currency amounts, names, etc., and to display them in tables
-(including pie charts).
-
-The \Package{csvsimple} does similar tasks. Its processing is
-controlled by keys established via the \Package{pgfkeys} package,
-which define how each row of the \acro{CSV} file is to be processed.
-
-For usage ``nearer to the bone'', one might consider the commands
-\csx{docsvlist} and \csx{forcsvlist} (from the \Package{etoolbox}
-package). The first uses the time-honoured \latex{} technique of
-changing the definition of a \csx{do} command; it runs through the
-list, and processes every item of the list as the argument of the
-\csx{do} command; so:
-\begin{quote}
-\begin{verbatim}
-\begin{itemize}
-\renewcommand*{\do}[1]{\item #1}
-\docsvlist{item1, item2, {item3a, item3b}, item4}
-\end{itemize}
-\end{verbatim}
-\end{quote}
-will convert the elements of a \acro{CSV} list into an itemised list.
-
-The macro \csx{forcsvlist} applies a function to each element of a
-\acro{CSV} list; this can of course be used to implement
-\csx{docsvlist}, at the cost of a little clarity.
-\begin{ctanrefs}
-\item[csvsimple.sty]\CTANref{csvsimple}
-\item[datatool \nothtml{\rmfamily}bundle]\CTANref{datatool}
-\item[etoolbox.sty]\CTANref{etoolbox}
-\item[pgfkeys.sty]Distributed as part of \CTANref{pgf}
-\end{ctanrefs}
-\LastEdit*{2013-09-10}