summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/etoolbox/etoolbox.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2008-07-01 00:55:29 +0000
committerKarl Berry <karl@freefriends.org>2008-07-01 00:55:29 +0000
commit767674bba9388c657eb685ef4a48aa2254f258d2 (patch)
tree35fa4052e20d7d6dee1f4edc82a173f799b369df /Master/texmf-dist/doc/latex/etoolbox/etoolbox.tex
parent5f754957ed6a0123d34fa53725076de7f73198fb (diff)
etoolbox update (30jun08)
git-svn-id: svn://tug.org/texlive/trunk@9127 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/etoolbox/etoolbox.tex')
-rw-r--r--Master/texmf-dist/doc/latex/etoolbox/etoolbox.tex94
1 files changed, 60 insertions, 34 deletions
diff --git a/Master/texmf-dist/doc/latex/etoolbox/etoolbox.tex b/Master/texmf-dist/doc/latex/etoolbox/etoolbox.tex
index b3e94609535..0efeb661c37 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 1.6 2008/06/22 15:26:57 lehman stable $
+% $Id: etoolbox.tex,v 1.7 2008/06/28 18:25:41 lehman stable $
%
% This is the source of etoolbox.pdf. This file is primarily included
% in the distribution for legal reasons. It will not compile as is
@@ -13,7 +13,7 @@
\MakeAutoQuote*{<}{>}
\MakeShortVerb{\|}
-\rcsid{$Id: etoolbox.tex,v 1.6 2008/06/22 15:26:57 lehman stable $}
+\rcsid{$Id: etoolbox.tex,v 1.7 2008/06/28 18:25:41 lehman stable $}
\titlepage{%
title={The \sty{etoolbox} package},
@@ -42,13 +42,17 @@
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}.
+\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.
+
\subsection{License}
Copyright \textcopyright\ 2007--2008 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]{Feedback and contributions}
+\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. However, I am open to contributions by other class and package authors, provided that the contributed code is sufficiently generic, matches the profile of this package, and may be added to the package without requiring significant adaption.
+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}
@@ -92,6 +96,17 @@ Modifies a \prm{command} defined with \cmd{newcommand} such that it is robust wi
\end{ltxsyntax}
+\subsection{Protection}
+\label{use:pro}
+
+\begin{ltxsyntax}
+
+\cmditem{protecting}{code}
+
+This command applies \latex's protection mechanism, which normally requires prefixing each fragile command with \cmd{protect}, to an entire chunk of arbitrary \prm{code}. Its behavior depends on the current state of \cmd{protect}. Note that the braces around the \prm{code} are mandatory even if it is a single token.
+
+\end{ltxsyntax}
+
\subsection[Lengths and counters]{Length and counter assignments}
\label{use:cal}
@@ -112,52 +127,56 @@ Assigns a value to a \prm{length} register previously initialized with \cmd{newl
\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. The \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. The \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. To sum that up, \latex will perform the following tasks <inside> |\begin{document}|:
+\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.
+
+\begin{ltxsyntax}
+
+\cmditem{AfterPreamble}{code}
+
+This hook is a variant of \cmd{AtBeginDocument} which may be used in both the preamble and the document body. When used in the preamble, it behaves exactely like \cmd{AtBeginDocument}. When used in the document body, it immediately executes its \prm{code} argument. \cmd{AtBeginDocument} would issue an error in this case. This hook is useful to defer code which needs to write to the main \file{aux} file.
+
+\cmditem{AtEndPreamble}{code}
+
+This hook differs from \cmd{AtBeginDocument} in that the \prm{code} is executed right at the end of the preamble, before the main \file{aux} file (as written on the previous \latex pass) is read and prior to any \cmd{AtBeginDocument} code. Note that it is not possible to write to the \file{aux} file at this point.
+
+\cmditem{AfterEndPreamble}{code}
+
+This hook differs from \cmd{AtBeginDocument} in that the \prm{code} is executed at the very end of |\begin{document}|, after any \cmd{AtBeginDocument} code. Note that commands whose scope has been restricted to the preamble with \cmd{@onlypreamble} are no longer available when this hook is executed.
+
+\cmditem{AfterEndDocument}{code}
+
+This hook differs from \cmd{AtEndDocument} in that the \prm{code} is executed at the very end of the document, after the main \file{aux} file (as written on the current \latex pass) has been read and after any \cmd{AtEndDocument} code.
+
+\end{ltxsyntax}
+
+In a way, \cmd{AtBeginDocument} code is part neither of the preamble nor the document body but located in-between them since it gets executed in the middle of the initialization sequence performed prior to typesetting. It is sometimes desirable to move code to the end of the preamble because all requested packages have been loaded at this point. \cmd{AtBeginDocument} code, however, is executed too late if it is required in the \file{aux} file. In contrast to that, \cmd{AtEndPreamble} code is part of the preamble; \cmd{AfterEndPreamble} code is part of the document body and may contain printable text to be typeset at the very beginning of the document. To sum that up, \latex will perform the following tasks <inside> |\begin{document}|:
\begin{itemize}
\setlength{\itemsep}{0pt}
\item Execute any \cmd{AtEndPreamble} code
-\item Start initialization for document body
+\item Start initialization for document body (page layout, default fonts, etc.)
\item Load the main \file{aux} file written on the previous \latex pass
\item Open the main \file{aux} file for writing on the current pass
\item Continue initialization for document body
\item Execute any \cmd{AtBeginDocument} code
\item Complete initialization for document body
-\item Execute any \cmd{AfterBeginDocument} code
+\item Disable all \cmd{@onlypreamble} commands
+\item Execute any \cmd{AfterEndPreamble} code
\end{itemize}
%
-Strictly speaking, \cmd{AtBeginDocument} code is neither part of the preamble nor part of the document body but located in-between these parts of a \latex document because it gets executed in the middle of the initialization sequence performed prior to typesetting. \cmd{AtEndPreamble} code, however, is part of the preamble; \cmd{AfterBeginDocument} code is part of the body and may contain printable text to be typeset as the very first thing in the document. Inside |\end{document}|, \latex will perform the following tasks:
+Inside |\end{document}|, \latex will perform the following tasks:
\begin{itemize}
\setlength{\itemsep}{0pt}
\item Execute any \cmd{AtEndDocument} code
+\item Perform a final \cmd{clearpage} operation
\item Close the main \file{aux} file for writing
\item Load the main \file{aux} file written on the current \latex pass
\item Perform final tests and issue warnings, if applicable
\item Execute any \cmd{AfterEndDocument} code
\end{itemize}
%
-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. \cmd{AtBeginDocument} and \cmd{AtEndDocument} are provided by the \latex kernel. The \sty{etoolbox} package introduces the following additional hooks:
-
-\begin{ltxsyntax}
-
-\cmditem{AtEndPreamble}{code}
-
-This hook differs from \cmd{AtBeginDocument} in that the \prm{code} is executed right at the end of the preamble, before the main \file{aux} file (as written on the previous \latex pass) is read and prior to any \cmd{AtBeginDocument} code. It is sometimes desirable to defer code to the end of the preamble because all requested packages have been loaded at this point. However, \cmd{AtBeginDocument} code is executed too late if it is required in the \file{aux} file.
-
-\cmditem{AfterBeginDocument}{code}
-
-This hook differs from \cmd{AtBeginDocument} in that the \prm{code} is executed as part of the document body, after any \cmd{AtBeginDocument} code. It is possible to perform typesetting tasks such as printing a title page at this point.
-
-\cmditem{AfterEndDocument}{code}
-
-This hook differs from \cmd{AtEndDocument} in that the \prm{code} is executed at the very end of the document, after the main \file{aux} file (as written on the current \latex pass) has been read and after any \cmd{AtEndDocument} code. This hook is useful if a package needs to evaluate any data in the \file{aux} file at the end of a \latex run.
-
-\cmditem{AfterPreamble}{code}
-
-This hook is a variant of \cmd{AtBeginDocument} which may be used in both the preamble and the document body. When used in the preamble, it behaves exactely like \cmd{AtBeginDocument}. When used in the document body, it immediately executes its \prm{code} argument. \cmd{AtBeginDocument} would issue an error in this case.
-
-\end{ltxsyntax}
+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}
@@ -296,6 +315,7 @@ Similar to \cmd{mugdef} except that it takes a control sequence name as its firs
\end{ltxsyntax}
\subsection{Expansion control}
+\label{aut:exp}
The facilities in this section are useful to control expansion in an \cmd{edef} or a similar context.
@@ -303,16 +323,12 @@ The facilities in this section are useful to control expansion in an \cmd{edef}
\cmditem{expandonce}<command>
-This command expands a \prm{command} once and prevents further expansion of the replacement text.
+This command expands a \prm{command} once and prevents further expansion of the replacement text. This command is expandable.
\cmditem{csexpandonce}{csname}
Similar to \cmd{expandonce} except that it takes a control sequence name as its argument.
-\cmditem{protecting}{code}
-
-This command applies \latex's protection mechanism, which normally requires prefixing each fragile command with \cmd{protect}, to an entire chunk of arbitrary \prm{code}. Its behavior depends on the current state of \cmd{protect}. Note that the braces around the \prm{code} are mandatory even if it is a single token.
-
\end{ltxsyntax}
\subsection{Hook management}
@@ -819,8 +835,18 @@ Expands to \prm{true} if \prm{string} is a Roman numeral, and to \prm{false} oth
\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}{1.7}{2008-06-28}
+
+\item Renamed \cmd{AfterBeginDocument} to \cmd{AfterEndPreamble} (name clash)\see{use:pre}
+\item Resolved conflict with \sty{hyperref}
+\item Rearranged manual slightly
+
+\end{release}
+
\begin{release}{1.6}{2008-06-22}
\item Improved \cmd{robustify}\see{use:pat}