diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/etoolbox/etoolbox.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/etoolbox/etoolbox.tex | 80 |
1 files changed, 64 insertions, 16 deletions
diff --git a/Master/texmf-dist/doc/latex/etoolbox/etoolbox.tex b/Master/texmf-dist/doc/latex/etoolbox/etoolbox.tex index 93bee323ddc..70ecf4fe3f2 100644 --- a/Master/texmf-dist/doc/latex/etoolbox/etoolbox.tex +++ b/Master/texmf-dist/doc/latex/etoolbox/etoolbox.tex @@ -1,14 +1,14 @@ -% $Id: etoolbox.tex,v 1.9 2010/04/10 19:11:49 lehman stable $ +% $Id: etoolbox.tex,v 2.0 2010/08/21 17:07:46 lehman stable $ \documentclass{ltxdockit} \usepackage[latin9]{inputenc} \usepackage[american]{babel} -\usepackage[strict,babel=once]{csquotes} +\usepackage[strict]{csquotes} \usepackage{shortvrb} \MakeAutoQuote{«}{»} \MakeAutoQuote*{<}{>} \MakeShortVerb{\|} -\rcsid{$Id: etoolbox.tex,v 1.9 2010/04/10 19:11:49 lehman stable $} +\rcsid{$Id: etoolbox.tex,v 2.0 2010/08/21 17:07:46 lehman stable $} \titlepage{% title={The \sty{etoolbox} package}, @@ -35,7 +35,7 @@ \subsection{About} -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. Note that the initial versions of this package were released under the name \sty{elatex}. +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} @@ -234,6 +234,10 @@ Clears a \prm{command} such that \etex's \cmd{ifdefined} and \cmd{ifcsname} test Similar to \cmd{undef} except that it takes a control sequence name as its argument. This command is robust and may be prefixed with \cs{global}. +\cmditem{csshow}{csname} + +Similar to the \tex primitive \cmd{show} but takes a control sequence name as its argument. If the control sequence is undefined, this command will not implicitly assign a meaning of \cmd{relax} to it. This command is robust. + \end{ltxsyntax} \subsubsection{Arithmetic definitions} @@ -929,7 +933,7 @@ will yield \prm{true} if \texttt{mybool} is false and \prm{false} if \texttt{myb \begin{ltxcode} \ifboolexpr{ - <<not (>> bool {boolA} and bool {boolB} <<)>> + <<not (>> bool {boolA} or bool {boolB} <<)>> } {true} {false} @@ -1042,14 +1046,22 @@ This command defines a list parser similar to the \cmd{docsvlist} command below, % Note that the list parsers are sensitive to the category code of the \prm{separator}. +\cmditem*{DeclareListParser*}{command}{separator} + +The starred variant of \cmd{DeclareListParser} defines a list parser similar to the \cmd{forcsvlist} command below, which is defined like this: + +\begin{ltxcode} +\DeclareListParser*{\forcsvlist}{,} +\end{ltxcode} + \cmditem{docsvlist}{item, item, ...} -This command loops over a comma"=separated list and executes the auxiliary command \cmd{do} for every item in the list, passing the item as an argument. In contrast to the \cmd{@for} loop in the \latex kernel, \cmd{docsvlist} is expandable. With a suitable definition of \cmd{do}, lists may be processed in an \cmd{edef} or a comparable context. You may use \cmd{listbreak} at the end of the replacement text of \cmd{do} to stop processing and discard the remaining items in the list. Whitespace after list separators is ignored. If an item contains a comma or starts with a space, it must be wrapped in curly braces. The braces will be removed as the list is processed. Here is a usage example which prints a comma"=separated list as an \env{itemize} environment: +This command loops over a comma"=separated list of items and executes the auxiliary command \cmd{do} for every item in the list, passing the item as an argument. In contrast to the \cmd{@for} loop in the \latex kernel, \cmd{docsvlist} is expandable. With a suitable definition of \cmd{do}, lists may be processed in an \cmd{edef} or a comparable context. You may use \cmd{listbreak} at the end of the replacement text of \cmd{do} to stop processing and discard the remaining items in the list. Whitespace after list separators is ignored. If an item contains a comma or starts with a space, it must be wrapped in curly braces. The braces will be removed as the list is processed. Here is a usage example which prints a comma"=separated list as an \env{itemize} environment: \begin{ltxcode} \begin{itemize} - \renewcommand*{\do}[1]{\item #1} - \docsvlist{item1, item2, {item3a, item3b}, item4} +\renewcommand*{\do}[1]{\item #1} +\docsvlist{item1, item2, {item3a, item3b}, item4} \end{itemize} \end{ltxcode} % @@ -1064,12 +1076,20 @@ Here is another example: % In this example, the list is written to the log file as part of an informational message. The list processing takes place during the \cmd{write} operation. +\cmditem{forcsvlist}{handler}{item, item, ...} + +This command is similar to \cmd{docsvlist} except that \cmd{do} is replaced by a \prm{handler} specified at invocation time. The \prm{handler} may also be a sequence of commands, provided that the command given last takes the item as trailing argument. For example, the following code will convert a comma"=separated list of items into an internal list called \cmd{mylist}: + +\begin{ltxcode} +\forcsvlist{\listadd\mylist}{item1, item2, item3} +\end{ltxcode} + \end{ltxsyntax} \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. When processing user input in a list format, see the facilities in section \ref{aut:lst:inp}. +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}. \begin{ltxsyntax} @@ -1111,8 +1131,8 @@ This command loops over all items in a \prm{listmacro} and executes the auxiliar \begin{ltxcode} \begin{itemize} - \renewcommand*{\do}[1]{\item #1} - \dolistloop{\mylist} +\renewcommand*{\do}[1]{\item #1} +\dolistloop{\mylist} \end{itemize} \end{ltxcode} @@ -1120,9 +1140,25 @@ This command loops over all items in a \prm{listmacro} and executes the auxiliar Similar to \cmd{dolistloop} except that it takes a control sequence name as its argument. -\cmditem{ifinlist}{item}{listmacro} +\cmditem{forlistloop}{handler}{listmacro} -This command checks if an \prm{item} is included in a \prm{listmacro}. Note that this test uses pattern matching based on \tex's argument scanner to check if the search string is included in the list. This means that it is usually faster than looping over all items in the list, but it also implies that the items must not include curly braces which would effectively hide them from the scanner. In other words, this macro is most useful when dealing with lists of plain strings rather than printable data. When dealing with printable text, it is safer to use \cmd{dolistloop} to check if an item is in the list as follows: +This command is similar to \cmd{dolistloop} except that \cmd{do} is replaced by a \prm{handler} specified at invocation time. The \prm{handler} may also be a sequence of commands, provided that the command given last takes the item as trailing argument. For example, the following code will prefix all items in the internal list \cmd{mylist} with \cmd{item}, count the items as the list is processed, and append the item count at the end: + +\begin{ltxcode} +\newcounter{itemcount} +\begin{itemize} +\forlistloop{\stepcounter{itemcount}\item}{\mylist} +\item Total: \number\value{itemcount} items +\end{itemize} +\end{ltxcode} + +\cmditem{forlistcsloop}{handler}{listcsname} + +Similar to \cmd{forlistloop} except that it takes a control sequence name as its second argument. + +\cmditem{ifinlist}{item}{listmacro}{true}{false} + +This command executes \prm{true} if the \prm{item} is included in a \prm{listmacro}, and \prm{false} otherwise. Note that this test uses pattern matching based on \tex's argument scanner to check if the search string is included in the list. This means that it is usually faster than looping over all items in the list, but it also implies that the items must not include curly braces which would effectively hide them from the scanner. In other words, this macro is most useful when dealing with lists of plain strings rather than printable data. When dealing with printable text, it is safer to use \cmd{dolistloop} to check if an item is in the list as follows: \begin{ltxcode} \renewcommand*{\do}[1]{% @@ -1132,15 +1168,15 @@ This command checks if an \prm{item} is included in a \prm{listmacro}. Note that \dolistloop{\mylist} \end{ltxcode} -\cmditem{xifinlist}{item}{listmacro} +\cmditem{xifinlist}{item}{listmacro}{true}{false} Similar to \cmd{ifinlist} except that the \prm{item} is expanded prior to the test. -\cmditem{ifinlistcs}{item}{listcsname} +\cmditem{ifinlistcs}{item}{listcsname}{true}{false} Similar to \cmd{ifinlist} except that it takes a control sequence name as its second argument. -\cmditem{xifinlistcs}{item}{listcsname} +\cmditem{xifinlistcs}{item}{listcsname}{true}{false} Similar to \cmd{xifinlist} except that it takes a control sequence name as its second argument. @@ -1175,6 +1211,18 @@ This revision history is a list of changes relevant to users of this package. Ch \begin{changelog} +\begin{release}{2.0}{2010-08-21} + +\item Added \cmd{csshow}\see{aut:def:def} +\item Added \cmd{DeclareListParser*}\see{aut:lst:inp} +\item Added \cmd{forcsvlist}\see{aut:lst:inp} +\item Added \cmd{forlistloop}\see{aut:lst:int} +\item Added \cmd{forlistcsloop}\see{aut:lst:int} +\item Allow testing \cmd{par} in macro tests\see{aut:tst:def} +\item Fixed some bugs + +\end{release} + \begin{release}{1.9}{2010-04-10} \item Improved \cmd{letcs}\see{aut:def:def} |