From a77deb8a1058df87320fadced52041b60ec60496 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Mon, 3 Jan 2011 23:49:15 +0000 Subject: etoolbox 2.1 (3jan11) git-svn-id: svn://tug.org/texlive/trunk@20922 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/etoolbox/README | 2 +- Master/texmf-dist/doc/latex/etoolbox/etoolbox.pdf | Bin 275812 -> 188352 bytes Master/texmf-dist/doc/latex/etoolbox/etoolbox.tex | 144 +++++++++++++++++----- 3 files changed, 113 insertions(+), 33 deletions(-) (limited to 'Master/texmf-dist/doc/latex/etoolbox') diff --git a/Master/texmf-dist/doc/latex/etoolbox/README b/Master/texmf-dist/doc/latex/etoolbox/README index e6fe1c4a489..db96fdfc6cb 100644 --- a/Master/texmf-dist/doc/latex/etoolbox/README +++ b/Master/texmf-dist/doc/latex/etoolbox/README @@ -1,4 +1,4 @@ -$Id: README,v 2.0a 2010/09/12 11:42:38 lehman stable $ +$Id: README,v 2.1 2011/01/03 19:14:10 lehman stable $ ABOUT diff --git a/Master/texmf-dist/doc/latex/etoolbox/etoolbox.pdf b/Master/texmf-dist/doc/latex/etoolbox/etoolbox.pdf index 5e4fbbfee2d..78f8d15be9d 100644 Binary files a/Master/texmf-dist/doc/latex/etoolbox/etoolbox.pdf and b/Master/texmf-dist/doc/latex/etoolbox/etoolbox.pdf differ diff --git a/Master/texmf-dist/doc/latex/etoolbox/etoolbox.tex b/Master/texmf-dist/doc/latex/etoolbox/etoolbox.tex index 4d71a11d5e2..728f3d9dec1 100644 --- a/Master/texmf-dist/doc/latex/etoolbox/etoolbox.tex +++ b/Master/texmf-dist/doc/latex/etoolbox/etoolbox.tex @@ -1,5 +1,5 @@ -% $Id: etoolbox.tex,v 2.0a 2010/09/12 11:42:38 lehman stable $ -\documentclass{ltxdockit} +% $Id: etoolbox.tex,v 2.1 2011/01/03 19:14:10 lehman stable $ +\documentclass{ltxdockit}[2010/09/26] \usepackage[latin9]{inputenc} \usepackage[american]{babel} \usepackage[strict]{csquotes} @@ -8,7 +8,7 @@ \MakeAutoQuote*{<}{>} \MakeShortVerb{\|} -\rcsid{$Id: etoolbox.tex,v 2.0a 2010/09/12 11:42:38 lehman stable $} +\rcsid{$Id: etoolbox.tex,v 2.1 2011/01/03 19:14:10 lehman stable $} \titlepage{% title={The \sty{etoolbox} Package}, @@ -35,20 +35,16 @@ \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 \sty{etoolbox} package is a toolbox of programming tools 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{Acknowledgments} - -The \cmd{ifblank} test of this package is based on code by Donald Arseneau. +Copyright \textcopyright\ 2007--2011 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. \section{User Commands} \label{use} -The facilities in this section are geared towards regular users as well as class and package authors. +The tools in this section are geared towards regular users as well as class and package authors. \subsection{Definitions} \label{use:def} @@ -97,7 +93,7 @@ This command applies \latex's protection mechanism, which normally requires pref \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. +The tools in this section are replacements for \cmd{setcounter} and \cmd{setlength} which support arithmetic expressions. \begin{ltxsyntax} @@ -111,10 +107,10 @@ Assigns a value to a \prm{length} register previously initialized with \cmd{newl \end{ltxsyntax} -\subsection[Predefined hooks]{Predefined All-Purpose Hooks} +\subsection[Document Hooks]{Additional Document 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. +\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, 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, 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 are permissible and need not be doubled. \begin{ltxsyntax} @@ -165,16 +161,41 @@ 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. +\subsection[Environment Hooks]{Environment Hooks} +\label{use:env} + +The tools in this section provide hooks for arbitrary environments. Note that they will not modify the definition of the \prm{environment}. They hook into the \cmd{begin} and \cmd{end} commands instead. Redefining the \prm{environment} will not clear the corresponding hooks. The \prm{code} may be arbitrary \tex code. Parameter characters in the \prm{code} argument are permissible and need not be doubled. + +\begin{ltxsyntax} + +\cmditem{AtBeginEnvironment}{environment}{code} + +Appends arbitrary \prm{code} to a hook executed by the \cmd{begin} command at the beginning of a given \prm{environment}, immediately before \cmd{\prm{environment}}, inside the group opened by \cmd{begin}. + +\cmditem{AtEndEnvironment}{environment}{code} + +Appends arbitrary \prm{code} to a hook executed by the \cmd{end} command at the end of a given \prm{environment}, immediately before \cmd{end\prm{environment}}, inside the group opened by \cmd{begin}. + +\cmditem{BeforeBeginEnvironment}{environment}{code} + +Appends arbitrary \prm{code} to a hook executed at a very early point by the \cmd{begin} command, before the group holding the environment is opened. + +\cmditem{AfterEndEnvironment}{environment}{code} + +Appends arbitrary \prm{code} to a hook executed at a very late point by the \cmd{end} command, after the group holding the environment has been closed. + +\end{ltxsyntax} + \section{Author Commands} -The facilities in this section are geared towards class and package authors. +The tools in this section are geared towards class and package authors. \subsection{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. +The tools 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. \begin{ltxsyntax} @@ -235,7 +256,7 @@ Similar to the \tex primitive \cmd{show} but takes a control sequence name as it \subsubsection{Arithmetic Definitions} \label{aut:def:cal} -The facilities in this section permit calculations using macros rather than length registers and counters. +The tools in this section permit calculations using macros rather than length registers and counters. \begin{ltxsyntax} @@ -308,7 +329,7 @@ Similar to \cmd{mugdef} except that it takes a control sequence name as its firs \subsection{Expansion Control} \label{aut:exp} -The facilities in this section are useful to control expansion in an \cmd{edef} or a similar context. +The tools in this section are useful to control expansion in an \cmd{edef} or a similar context. \begin{ltxsyntax} @@ -325,12 +346,12 @@ Similar to \cmd{expandonce} except that it takes a control sequence name as its \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. +The tools 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 tools 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} \label{aut:hok:app} -The facilities in this section append arbitrary code to a hook. +The tools in this section append arbitrary code to a hook. \begin{ltxsyntax} @@ -387,7 +408,7 @@ Similar to \cmd{protected@xappto} except that it takes a control sequence name a \subsubsection{Prepending to a Hook} \label{aut:hok:pre} -The facilities in this section arbitrary code to a hook, \ie the code is inserted at the beginning of the hook rather than being added at the end. +The tools in this section arbitrary code to a hook, \ie the code is inserted at the beginning of the hook rather than being added at the end. \begin{ltxsyntax} @@ -444,7 +465,7 @@ Similar to \cmd{protected@xpreto} except that it takes a control sequence name a \subsection{Patching} \label{aut:pat} -The facilities in this section are useful to hook into or modify existing code. All commands presented here preserve the parameters and the prefixes of the patched \prm{command}. Note that \cs{outer} commands may not be patched. Also note that the commands in this section will not automatically issue any error messages if patching fails. Instead, they take a \prm{failure} argument which should provide suitable fallback code or an error message. Issuing \cmd{tracingpatches} in the preamble will cause the commands to write debugging information to the transcript file. +The tools in this section are useful to hook into or modify existing code. All commands presented here preserve the parameters and the prefixes of the patched \prm{command}. Note that \cs{outer} commands may not be patched. Also note that the commands in this section will not automatically issue any error messages if patching fails. Instead, they take a \prm{failure} argument which should provide suitable fallback code or an error message. Issuing \cmd{tracingpatches} in the preamble will cause the commands to write debugging information to the transcript file. \begin{ltxsyntax} @@ -477,12 +498,12 @@ Enables tracing for all patching commands, including \cmd{ifpatchable}. The debu \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. +This package provides two interfaces to boolean flags which are completely independent of each other. The tools 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} \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. +Since the tools 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. \begin{ltxsyntax} @@ -537,7 +558,7 @@ Similar to \cmd{ifbool} but negates the test. \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. +In contrast to the flags from section \ref{aut:bo1:bol}, the tools in this section require only one macro per flag. They also use a separate namespace to avoid name clashes with regular macros. \begin{ltxsyntax} @@ -645,7 +666,7 @@ Similar to \cmd{ifdefempty} except that it takes a control sequence name as its \cmditem{ifdefvoid}{control sequence}{true}{false} -Expands to \prm{true} if the \prm{control sequence} is undefined, is a macro whose meaning is \cmd{relax}, or is a parameterless macro whose replacement text is empty, and to \prm{false} otherwise. +Expands to \prm{true} if the \prm{control sequence} is undefined, if is a macro whose meaning is \cmd{relax}, or a parameterless macro whose replacement text is empty, and to \prm{false} otherwise. \cmditem{ifcsvoid}{csname}{true}{false} @@ -661,19 +682,62 @@ Similar to \cmd{ifdefequal} except that it takes control sequence names as argum \cmditem{ifdefstring}{command}{string}{true}{false} -Compares the replacement text of a \prm{command} to a \prm{string} and executes \prm{true} if they are equal, and \prm{false} otherwise. Neither the \prm{command} nor the \prm{string} is expanded in the test and the comparison is category code agnostic. Control sequence tokens in the \prm{string} argument will be detokenized and treated as strings. This command is robust. Note that it will only consider the replacement text of the \prm{command}. For example, this code +Compares the replacement text of a \prm{command} to a \prm{string} and executes \prm{true} if they are equal, and \prm{false} otherwise. Neither the \prm{command} nor the \prm{string} is expanded in the test and the comparison is category code agnostic. Control sequence tokens in the \prm{string} argument will be detokenized and treated as strings. This command is robust. Note that it will only consider the replacement text of the \prm{command}. For example, this test \begin{ltxcode} -\long\def\@gobbletwo#1#2{} -\ifdefstring{\@gobbletwo}{}{true}{false} +\long\edef\mymacro#1#2{\string&} +\ifdefstring{\mymacro}{&}{true}{false} \end{ltxcode} % -would yield \prm{true}. The prefix and the parameters of \cmd{@gobbletwo} are ignored. +would yield \prm{true}. The prefix and the parameters of \cmd{mymacro} as well as the category codes in the replacement text are ignored. \cmditem{ifcsstring}{csname}{string}{true}{false} Similar to \cmd{ifdefstring} except that it takes a control sequence name as its first argument. +\cmditem{ifdefstrequal}{command}{command}{true}{false} + +Performs a category code agnostic string comparison of the replacement text of two commands. This command is similar to \cmd{ifdefstring} except that both arguments to be compared are macros. This command is robust. + +\cmditem{ifcsstrequal}{csname}{csname}{true}{false} + +Similar to \cmd{ifdefstrequal} except that it takes control sequence names as arguments. + +\end{ltxsyntax} + +\subsubsection{Counter and Length Tests} +\label{aut:tst:cnt} + +\begin{ltxsyntax} + +\cmditem{ifdefcounter}{control sequence}{true}{false} + +Expands to \prm{true} if the \prm{control sequence} is a \tex \cmd{count} register allocated with \cmd{newcount}, and to \prm{false} otherwise. + +\cmditem{ifcscounter}{csname}{true}{false} + +Similar to \cmd{ifdefcounter} except that it takes a control sequence name as its first argument. + +\cmditem{ifltxcounter}{name}{true}{false} + +Expands to \prm{true} if \prm{name} is a \latex counter allocated with \cmd{newcounter}, and to \prm{false} otherwise. + +\cmditem{ifdeflength}{control sequence}{true}{false} + +Expands to \prm{true} if the \prm{control sequence} is a \tex \cmd{skip} register allocated with \cmd{newskip} or \cmd{newlength}, and to \prm{false} otherwise. + +\cmditem{ifcslength}{csname}{true}{false} + +Similar to \cmd{ifdeflength} except that it takes a control sequence name as its first argument. + +\cmditem{ifdefdimen}{control sequence}{true}{false} + +Expands to \prm{true} if the \prm{control sequence} is a \tex \cmd{dimen} register allocated with \cmd{newdimen}, and to \prm{false} otherwise. + +\cmditem{ifcsdimen}{csname}{true}{false} + +Similar to \cmd{ifdefdimen} except that it takes a control sequence name as its first argument. + \end{ltxsyntax} \subsubsection{String Tests} @@ -691,7 +755,7 @@ Expands to \prm{true} if the \prm{string} is empty, and to \prm{false} otherwise \cmditem{ifblank}{string}{true}{false} -Expands to \prm{true} if the \prm{string} is blank (empty or spaces), and to \prm{false} otherwise. The \prm{string} is not expanded in the test. +Expands to \prm{true} if the \prm{string} is blank (empty or spaces), and to \prm{false} otherwise. The \prm{string} is not expanded in the test.\footnote{This macro is based on code by Donald Arseneau.} \cmditem{notblank}{string}{not true}{not false} @@ -1026,7 +1090,7 @@ which is probably not what you meant to order. \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. +The tools in this section are primarily designed to handle user input. When building lists for internal use by a package, using the tools in section \ref{aut:lst:int} may be preferable as they allow testing if an element is in a list. \begin{ltxsyntax} @@ -1083,7 +1147,7 @@ This command is similar to \cmd{docsvlist} except that \cmd{do} is replaced by a \subsubsection{Internal Lists} \label{aut:lst:int} -The facilities in this section handle internal lists of data. An 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}. +The tools in this section handle internal lists of data. An 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 tools in section \ref{aut:lst:inp}. \begin{ltxsyntax} @@ -1205,6 +1269,22 @@ This revision history is a list of changes relevant to users of this package. Ch \begin{changelog} +\begin{release}{2.1}{2011-01-03} +\item Added \cmd{AtBeginEnvironment}\see{use:env} +\item Added \cmd{AtEndEnvironment}\see{use:env} +\item Added \cmd{BeforeBeginEnvironment}\see{use:env} +\item Added \cmd{AfterEndEnvironment}\see{use:env} +\item Added \cmd{ifdefstrequal}\see{aut:tst:def} +\item Added \cmd{ifcsstrequal}\see{aut:tst:def} +\item Added \cmd{ifdefcounter}\see{aut:tst:cnt} +\item Added \cmd{ifcscounter}\see{aut:tst:cnt} +\item Added \cmd{ifltxcounter}\see{aut:tst:cnt} +\item Added \cmd{ifdeflength}\see{aut:tst:cnt} +\item Added \cmd{ifcslength}\see{aut:tst:cnt} +\item Added \cmd{ifdefdimen}\see{aut:tst:cnt} +\item Added \cmd{ifcsdimen}\see{aut:tst:cnt} +\end{release} + \begin{release}{2.0a}{2010-09-12} \item Fixed bug in \cmd{patchcmd}, \cmd{apptocmd}, \cmd{pretocmd}\see{aut:pat} \end{release} -- cgit v1.2.3