diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/etoolbox/etoolbox.tex')
| -rw-r--r-- | Master/texmf-dist/doc/latex/etoolbox/etoolbox.tex | 88 |
1 files changed, 43 insertions, 45 deletions
diff --git a/Master/texmf-dist/doc/latex/etoolbox/etoolbox.tex b/Master/texmf-dist/doc/latex/etoolbox/etoolbox.tex index 70ecf4fe3f2..4d71a11d5e2 100644 --- a/Master/texmf-dist/doc/latex/etoolbox/etoolbox.tex +++ b/Master/texmf-dist/doc/latex/etoolbox/etoolbox.tex @@ -1,4 +1,4 @@ -% $Id: etoolbox.tex,v 2.0 2010/08/21 17:07:46 lehman stable $ +% $Id: etoolbox.tex,v 2.0a 2010/09/12 11:42:38 lehman stable $ \documentclass{ltxdockit} \usepackage[latin9]{inputenc} \usepackage[american]{babel} @@ -8,11 +8,11 @@ \MakeAutoQuote*{<}{>} \MakeShortVerb{\|} -\rcsid{$Id: etoolbox.tex,v 2.0 2010/08/21 17:07:46 lehman stable $} +\rcsid{$Id: etoolbox.tex,v 2.0a 2010/09/12 11:42:38 lehman stable $} \titlepage{% - title={The \sty{etoolbox} package}, - subtitle={An \etex toolbox for class and package authors}, + title={The \sty{etoolbox} Package}, + subtitle={An \etex Toolbox for Class and Package Authors}, url={http://www.ctan.org/tex-archive/macros/latex/contrib/etoolbox/}, author={Philipp Lehman}, email={plehman@gmx.net}, @@ -20,8 +20,8 @@ date={\rcstoday}} \hypersetup{% - pdftitle={The etoolbox package}, - pdfsubject={An e-TeX toolbox for class and package authors}, + pdftitle={The etoolbox Package}, + pdfsubject={An e-TeX Toolbox for Class and Package Authors}, pdfauthor={Philipp Lehman}, pdfkeywords={tex, e-tex, latex, class, package, programming}} @@ -33,27 +33,19 @@ \section{Introduction} \label{int} -\subsection{About} +\subsection[About]{About \sty{etoolbox}} -The \sty{etoolbox} package is a toolbox of programming facilities geared primarily towards \latex class and package authors. It provides \latex frontends to some of the new primitives provided by \etex as well as some generic tools which are not related to \etex but match the profile of this package. The package is work in progress. - -\subsection{Requirements} - -This package requires \etex. \tex distributions have been shipping \etex binaries for quite some time, most distributions even use them by default these days. This package checks if it is running under \etex. If you get an error message, try compiling the document with \path{elatex} instead of \path{latex} or \path{pdfelatex} instead of \path{pdflatex}, respectively. +The \sty{etoolbox} package is a toolbox of programming facilities geared primarily towards \latex class and package authors. It provides \latex frontends to some of the new primitives provided by \etex as well as some generic tools which are not related to \etex but match the profile of this package. \subsection{License} Copyright \textcopyright\ 2007--2010 Philipp Lehman. Permission is granted to copy, distribute and\slash or modify this software under the terms of the \lppl, version 1.3.\fnurl{http://www.ctan.org/tex-archive/macros/latex/base/lppl.txt} This package is author"=maintained. -\subsection{Feedback} - -I started to work on this package when I found myself implementing the same tools and shorthands I had employed in previous \latex packages for yet another package. For the most part, the facilities provided by \sty{etoolbox} address my needs as a package author and future development is likely to be guided by these needs as well. Please note that I will not be able to address any feature requests. - \subsection{Acknowledgments} The \cmd{ifblank} test of this package is based on code by Donald Arseneau. -\section{User commands} +\section{User Commands} \label{use} The facilities in this section are geared towards regular users as well as class and package authors. @@ -87,7 +79,7 @@ The syntax and behavior of this command is similar to \cmd{providecommand} excep \cmditem{robustify}{command} -Modifies a \prm{command} defined with \cmd{newcommand} such that it is robust without altering its parameters, its prefixes, or its replacement text. If the \prm{command} has been defined with \cmd{DeclareRobustCommand}, this will be detected automatically. \latex's high-level protection mechanism will be replaced by the corresponding low-level \etex facility in this case. +Redefines a \prm{command} defined with \cmd{newcommand} such that it is robust, without altering its parameters, its prefixes, or its replacement text. If the \prm{command} has been defined with \cmd{DeclareRobustCommand}, this will be detected automatically and \latex's high-level protection mechanism will be replaced by the corresponding low-level \etex feature. \end{ltxsyntax} @@ -102,7 +94,7 @@ This command applies \latex's protection mechanism, which normally requires pref \end{ltxsyntax} -\subsection[Lengths and counters]{Length and counter assignments} +\subsection[Lengths and Counters]{Length and Counter Assignments} \label{use:cal} The facilities in this section are replacements for \cmd{setcounter} and \cmd{setlength} which support arithmetic expressions. @@ -119,7 +111,7 @@ Assigns a value to a \prm{length} register previously initialized with \cmd{newl \end{ltxsyntax} -\subsection[Predefined hooks]{Predefined all-purpose hooks} +\subsection[Predefined hooks]{Predefined All-Purpose Hooks} \label{use:pre} \latex provides two hooks which defer the execution of code either to the beginning or to the end of the document body. Any \cmd{AtBeginDocument} code is executed towards the beginning of the document body, \emph{after} the main \file{aux} file has been read for the first time. Any \cmd{AtEndDocument} code is executed at the end of the document body, \emph{before} the main \file{aux} file is read for the second time. The hooks introduced here are similar in concept but defer the execution of their \prm{code} argument to slightly different locations. The \prm{code} may be arbitrary \tex code. Parameter characters in the \prm{code} argument need not be doubled. @@ -173,13 +165,13 @@ Inside |\end{document}|, \latex will perform the following tasks: % Any \cmd{AtEndDocument} code may be considered as being part of the document body insofar as it is still possible to perform typesetting tasks and write to the main \file{aux} file when it gets executed. \cmd{AfterEndDocument} code is not part of the document body. This hook is useful to evaluate the data in the \file{aux} file at the very end of a \latex pass. -\section{Author commands} +\section{Author Commands} The facilities in this section are geared towards class and package authors. \subsection{Definitions} -\subsubsection{Macro definitions} +\subsubsection{Macro Definitions} \label{aut:def:def} The facilities in this section are simple but frequently required shorthands which extend the scope of the \cmd{@namedef} and \cmd{@nameuse} macros from the \latex kernel. @@ -240,7 +232,7 @@ Similar to the \tex primitive \cmd{show} but takes a control sequence name as it \end{ltxsyntax} -\subsubsection{Arithmetic definitions} +\subsubsection{Arithmetic Definitions} \label{aut:def:cal} The facilities in this section permit calculations using macros rather than length registers and counters. @@ -313,7 +305,7 @@ Similar to \cmd{mugdef} except that it takes a control sequence name as its firs \end{ltxsyntax} -\subsection{Expansion control} +\subsection{Expansion Control} \label{aut:exp} The facilities in this section are useful to control expansion in an \cmd{edef} or a similar context. @@ -330,12 +322,12 @@ Similar to \cmd{expandonce} except that it takes a control sequence name as its \end{ltxsyntax} -\subsection{Hook management} +\subsection{Hook Management} \label{aut:hok} The facilities in this section are intended for hook management. A \prm{hook} in this context is a plain macro without any parameters and prefixes which is used to collect code to be executed later. These facilities may also be useful to patch simple macros by appending code to their replacement text. For more complex patching operations, see section \ref{aut:pat}. All commands in this section will initialize the \prm{hook} if it is undefined. -\subsubsection{Appending to a hook} +\subsubsection{Appending to a Hook} \label{aut:hok:app} The facilities in this section append arbitrary code to a hook. @@ -392,7 +384,7 @@ Similar to \cmd{protected@xappto} except that it takes a control sequence name a \end{ltxsyntax} -\subsubsection{Prepending to a hook} +\subsubsection{Prepending to a Hook} \label{aut:hok:pre} The facilities in this section <prepend> arbitrary code to a hook, \ie the code is inserted at the beginning of the hook rather than being added at the end. @@ -482,12 +474,12 @@ Enables tracing for all patching commands, including \cmd{ifpatchable}. The debu \end{ltxsyntax} -\subsection{Boolean flags} +\subsection{Boolean Flags} \label{aut:bol} This package provides two interfaces to boolean flags which are completely independent of each other. The facilities in section \ref{aut:bo1:bol} are a \latex frontend to \cmd{newif}. Those in section \ref{aut:bo1:tgl} use a different mechanism. -\subsubsection{\tex flags} +\subsubsection{\tex Flags} \label{aut:bo1:bol} Since the facilities in this section are based on \cmd{newif} internally, they may be used to test and alter the state of flags previously defined with \cmd{newif}. They are also compatible with the boolean tests of the \sty{ifthen} package and may serve as a \latex interface for querying \tex primitives such as \cmd{ifmmode}. The \cmd{newif} approach requires a total of three macros per flag. @@ -542,7 +534,7 @@ Similar to \cmd{ifbool} but negates the test. \end{ltxsyntax} -\subsubsection{\latex flags} +\subsubsection{\latex Flags} \label{aut:bo1:tgl} In contrast to the flags from section \ref{aut:bo1:bol}, the facilities in this section require only one macro per flag. They also use a separate namespace to avoid name clashes with regular macros. @@ -579,10 +571,10 @@ Similar to \cmd{iftoggle} but negates the test. \end{ltxsyntax} -\subsection{Generic tests} +\subsection{Generic Tests} \label{aut:tst} -\subsubsection{Macro tests} +\subsubsection{Macro Tests} \label{aut:tst:def} \begin{ltxsyntax} @@ -684,7 +676,7 @@ Similar to \cmd{ifdefstring} except that it takes a control sequence name as its \end{ltxsyntax} -\subsubsection{String tests} +\subsubsection{String Tests} \label{aut:tst:str} \begin{ltxsyntax} @@ -707,7 +699,7 @@ Similar to \cmd{ifblank} but negates the test. \end{ltxsyntax} -\subsubsection{Arithmetic tests} +\subsubsection{Arithmetic Tests} \label{aut:tst:num} \begin{ltxsyntax} @@ -782,7 +774,7 @@ Alternative syntax for |\ifdimcomp{...}{<}{...}{...}{...}|. \end{ltxsyntax} -\subsubsection{Boolean expressions} +\subsubsection{Boolean Expressions} \label{aut:tst:bol} The commands in this section are replacements for the \cmd{ifthenelse} command provided by the \sty{ifthen} package. They serve the same purpose but differ in syntax, concept, and implementation. In contrast to \cmd{ifthenelse}, they do not provide any tests of their own but serve as a frontend to other tests. Any test which satisfies certain syntactical requirements may be used in a boolean expression. @@ -999,7 +991,7 @@ The parentheses delimit a subexpression in the \prm{expression}. The subexpressi <<(>> bool {boolC} or bool {boolD} <<)>> \end{ltxcode} % -is true if both subexpressions are true, \ie if at least one of \texttt{boolA}/\texttt{boolB} and at least one of \texttt{boolC}/\texttt{boolD} is true. Note that subexpressions are generally not required if all elements are joined with \texttt{and} or with \texttt{or}. For example, the expressions +is true if both subexpressions are true, \ie if at least one of \texttt{boolA}/\texttt{boolB} and at least one of \texttt{boolC}/\texttt{boolD} is true. Subexpressions are generally not required if all elements are joined with \texttt{and} or with \texttt{or}. For example, the expressions \begin{ltxcode} bool {boolA} <<and>> bool {boolB} <<and>> {boolC} <<and>> bool {boolD} @@ -1009,27 +1001,29 @@ bool {boolA} <<or>> bool {boolB} <<or>> {boolC} <<or>> bool {boolD} will yield the expected results: the first one is true if all elements are true; the second one is true if at least one element is true. However, when combining \texttt{and} and \texttt{or}, it is advisable to always group the elements in subexpressions in order to avoid potential misconceptions which may arise from differences between the semantics of formal boolean expressions and the semantics of natural languages. For example, the following expression \begin{ltxcode} -bool {<<bagel>>} <<and>> bool {<<ham>>} <<or>> bool {<<cheese>>} +bool {<<coffee>>} <<and>> bool {<<milk>>} <<or>> bool {<<sugar>>} \end{ltxcode} % -is always true if \texttt{cheese} is true since the \texttt{or} operator will take the result of the \texttt{and} evaluation as input. In contrast to the meaning of this expression when pronounced in English, it is not processed like this +is always true if \texttt{sugar} is true since the \texttt{or} operator will take the result of the \texttt{and} evaluation as input. In contrast to the meaning of this expression when pronounced in English, it is not processed like this \begin{ltxcode} -bool {<<bagel>>} <<and>> <<(>> bool {<<ham>>} <<or>> bool {<<cheese>>} <<)>> +bool {<<coffee>>} <<and>> <<(>> bool {<<milk>>} <<or>> bool {<<sugar>>} <<)>> \end{ltxcode} % but evaluated strictly from left to right: \begin{ltxcode} -<<(>> bool {<<bagel>>} <<and>> bool {<<ham>>} <<)>> <<or>> bool {<<cheese>>} +<<(>> bool {<<coffee>>} <<and>> bool {<<milk>>} <<)>> <<or>> bool {<<sugar>>} \end{ltxcode} +% +which is probably not what you meant to order. \end{marglist} -\subsection{List processing} +\subsection{List Processing} \label{aut:lst} -\subsubsection{User input} +\subsubsection{User Input} \label{aut:lst:inp} The facilities in this section are primarily designed to handle user input. When building lists for internal use by a package, using the facilities in section \ref{aut:lst:int} may be preferable as they allow testing if an element is in a list. @@ -1086,7 +1080,7 @@ This command is similar to \cmd{docsvlist} except that \cmd{do} is replaced by a \end{ltxsyntax} -\subsubsection{Internal lists} +\subsubsection{Internal Lists} \label{aut:lst:int} The facilities in this section handle internal lists of data. An <internal list> in this context is a plain macro without any parameters and prefixes which is employed to collect data. These lists use a special character as internal list separator.\footnote{The character \texttt{\string|} with category code 3. Note that you may not typeset a list by saying \cmd{listname}. Use \cmd{show} instead to inspect the list.} When processing user input in list format, see the facilities in section \ref{aut:lst:inp}. @@ -1182,7 +1176,7 @@ Similar to \cmd{xifinlist} except that it takes a control sequence name as its s \end{ltxsyntax} -\subsection{Miscellaneous tools} +\subsection{Miscellaneous Tools} \label{aut:msc} \begin{ltxsyntax} @@ -1205,12 +1199,16 @@ Expands to \prm{true} if \prm{string} is a Roman numeral, and to \prm{false} oth \end{ltxsyntax} -\section{Revision history} +\section{Revision History} This revision history is a list of changes relevant to users of this package. Changes of a more technical nature which do not affect the user interface or the behavior of the package are not included in the list. If an entry in the revision history states that a feature has been \emph{improved} or \emph{extended}, this indicates a syntactically backwards compatible modification, such as the addition of an optional argument to an existing command. Entries stating that a feature has been \emph{modified} demand attention. They indicate a modification which may require changes to existing documents in some, hopefully rare, cases. The numbers on the right indicate the relevant section of this manual. \begin{changelog} +\begin{release}{2.0a}{2010-09-12} +\item Fixed bug in \cmd{patchcmd}, \cmd{apptocmd}, \cmd{pretocmd}\see{aut:pat} +\end{release} + \begin{release}{2.0}{2010-08-21} \item Added \cmd{csshow}\see{aut:def:def} |