diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/etoolbox')
-rw-r--r-- | Master/texmf-dist/doc/latex/etoolbox/LICENSE | 415 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/etoolbox/README | 32 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/etoolbox/etoolbox.pdf | bin | 166178 -> 213634 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/latex/etoolbox/etoolbox.tex | 366 |
4 files changed, 650 insertions, 163 deletions
diff --git a/Master/texmf-dist/doc/latex/etoolbox/LICENSE b/Master/texmf-dist/doc/latex/etoolbox/LICENSE new file mode 100644 index 00000000000..063434a00ab --- /dev/null +++ b/Master/texmf-dist/doc/latex/etoolbox/LICENSE @@ -0,0 +1,415 @@ +The LaTeX Project Public License +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- + +LPPL Version 1.3c 2006-05-20 + +Copyright 1999 2002-2006 LaTeX3 Project + Everyone is allowed to distribute verbatim copies of this + license document, but modification of it is not allowed. + + +PREAMBLE +======== + +The LaTeX Project Public License (LPPL) is the primary license under +which the the LaTeX kernel and the base LaTeX packages are distributed. + +You may use this license for any work of which you hold the copyright +and which you wish to distribute. This license may be particularly +suitable if your work is TeX-related (such as a LaTeX package), but +it is written in such a way that you can use it even if your work is +unrelated to TeX. + +The section `WHETHER AND HOW TO DISTRIBUTE WORKS UNDER THIS LICENSE', +below, gives instructions, examples, and recommendations for authors +who are considering distributing their works under this license. + +This license gives conditions under which a work may be distributed +and modified, as well as conditions under which modified versions of +that work may be distributed. + +We, the LaTeX3 Project, believe that the conditions below give you +the freedom to make and distribute modified versions of your work +that conform with whatever technical specifications you wish while +maintaining the availability, integrity, and reliability of +that work. If you do not see how to achieve your goal while +meeting these conditions, then read the document `cfgguide.tex' +and `modguide.tex' in the base LaTeX distribution for suggestions. + + +DEFINITIONS +=========== + +In this license document the following terms are used: + + `Work' + Any work being distributed under this License. + + `Derived Work' + Any work that under any applicable law is derived from the Work. + + `Modification' + Any procedure that produces a Derived Work under any applicable + law -- for example, the production of a file containing an + original file associated with the Work or a significant portion of + such a file, either verbatim or with modifications and/or + translated into another language. + + `Modify' + To apply any procedure that produces a Derived Work under any + applicable law. + + `Distribution' + Making copies of the Work available from one person to another, in + whole or in part. Distribution includes (but is not limited to) + making any electronic components of the Work accessible by + file transfer protocols such as FTP or HTTP or by shared file + systems such as Sun's Network File System (NFS). + + `Compiled Work' + A version of the Work that has been processed into a form where it + is directly usable on a computer system. This processing may + include using installation facilities provided by the Work, + transformations of the Work, copying of components of the Work, or + other activities. Note that modification of any installation + facilities provided by the Work constitutes modification of the Work. + + `Current Maintainer' + A person or persons nominated as such within the Work. If there is + no such explicit nomination then it is the `Copyright Holder' under + any applicable law. + + `Base Interpreter' + A program or process that is normally needed for running or + interpreting a part or the whole of the Work. + + A Base Interpreter may depend on external components but these + are not considered part of the Base Interpreter provided that each + external component clearly identifies itself whenever it is used + interactively. Unless explicitly specified when applying the + license to the Work, the only applicable Base Interpreter is a + `LaTeX-Format' or in the case of files belonging to the + `LaTeX-format' a program implementing the `TeX language'. + + + +CONDITIONS ON DISTRIBUTION AND MODIFICATION +=========================================== + +1. Activities other than distribution and/or modification of the Work +are not covered by this license; they are outside its scope. In +particular, the act of running the Work is not restricted and no +requirements are made concerning any offers of support for the Work. + +2. You may distribute a complete, unmodified copy of the Work as you +received it. Distribution of only part of the Work is considered +modification of the Work, and no right to distribute such a Derived +Work may be assumed under the terms of this clause. + +3. You may distribute a Compiled Work that has been generated from a +complete, unmodified copy of the Work as distributed under Clause 2 +above, as long as that Compiled Work is distributed in such a way that +the recipients may install the Compiled Work on their system exactly +as it would have been installed if they generated a Compiled Work +directly from the Work. + +4. If you are the Current Maintainer of the Work, you may, without +restriction, modify the Work, thus creating a Derived Work. You may +also distribute the Derived Work without restriction, including +Compiled Works generated from the Derived Work. Derived Works +distributed in this manner by the Current Maintainer are considered to +be updated versions of the Work. + +5. If you are not the Current Maintainer of the Work, you may modify +your copy of the Work, thus creating a Derived Work based on the Work, +and compile this Derived Work, thus creating a Compiled Work based on +the Derived Work. + +6. If you are not the Current Maintainer of the Work, you may +distribute a Derived Work provided the following conditions are met +for every component of the Work unless that component clearly states +in the copyright notice that it is exempt from that condition. Only +the Current Maintainer is allowed to add such statements of exemption +to a component of the Work. + + a. If a component of this Derived Work can be a direct replacement + for a component of the Work when that component is used with the + Base Interpreter, then, wherever this component of the Work + identifies itself to the user when used interactively with that + Base Interpreter, the replacement component of this Derived Work + clearly and unambiguously identifies itself as a modified version + of this component to the user when used interactively with that + Base Interpreter. + + b. Every component of the Derived Work contains prominent notices + detailing the nature of the changes to that component, or a + prominent reference to another file that is distributed as part + of the Derived Work and that contains a complete and accurate log + of the changes. + + c. No information in the Derived Work implies that any persons, + including (but not limited to) the authors of the original version + of the Work, provide any support, including (but not limited to) + the reporting and handling of errors, to recipients of the + Derived Work unless those persons have stated explicitly that + they do provide such support for the Derived Work. + + d. You distribute at least one of the following with the Derived Work: + + 1. A complete, unmodified copy of the Work; + if your distribution of a modified component is made by + offering access to copy the modified component from a + designated place, then offering equivalent access to copy + the Work from the same or some similar place meets this + condition, even though third parties are not compelled to + copy the Work along with the modified component; + + 2. Information that is sufficient to obtain a complete, + unmodified copy of the Work. + +7. If you are not the Current Maintainer of the Work, you may +distribute a Compiled Work generated from a Derived Work, as long as +the Derived Work is distributed to all recipients of the Compiled +Work, and as long as the conditions of Clause 6, above, are met with +regard to the Derived Work. + +8. The conditions above are not intended to prohibit, and hence do not +apply to, the modification, by any method, of any component so that it +becomes identical to an updated version of that component of the Work as +it is distributed by the Current Maintainer under Clause 4, above. + +9. Distribution of the Work or any Derived Work in an alternative +format, where the Work or that Derived Work (in whole or in part) is +then produced by applying some process to that format, does not relax or +nullify any sections of this license as they pertain to the results of +applying that process. + +10. a. A Derived Work may be distributed under a different license + provided that license itself honors the conditions listed in + Clause 6 above, in regard to the Work, though it does not have + to honor the rest of the conditions in this license. + + b. If a Derived Work is distributed under a different license, that + Derived Work must provide sufficient documentation as part of + itself to allow each recipient of that Derived Work to honor the + restrictions in Clause 6 above, concerning changes from the Work. + +11. This license places no restrictions on works that are unrelated to +the Work, nor does this license place any restrictions on aggregating +such works with the Work by any means. + +12. Nothing in this license is intended to, or may be used to, prevent +complete compliance by all parties with all applicable laws. + + +NO WARRANTY +=========== + +There is no warranty for the Work. Except when otherwise stated in +writing, the Copyright Holder provides the Work `as is', without +warranty of any kind, either expressed or implied, including, but not +limited to, the implied warranties of merchantability and fitness for a +particular purpose. The entire risk as to the quality and performance +of the Work is with you. Should the Work prove defective, you assume +the cost of all necessary servicing, repair, or correction. + +In no event unless required by applicable law or agreed to in writing +will The Copyright Holder, or any author named in the components of the +Work, or any other party who may distribute and/or modify the Work as +permitted above, be liable to you for damages, including any general, +special, incidental or consequential damages arising out of any use of +the Work or out of inability to use the Work (including, but not limited +to, loss of data, data being rendered inaccurate, or losses sustained by +anyone as a result of any failure of the Work to operate with any other +programs), even if the Copyright Holder or said author or said other +party has been advised of the possibility of such damages. + + +MAINTENANCE OF THE WORK +======================= + +The Work has the status `author-maintained' if the Copyright Holder +explicitly and prominently states near the primary copyright notice in +the Work that the Work can only be maintained by the Copyright Holder +or simply that it is `author-maintained'. + +The Work has the status `maintained' if there is a Current Maintainer +who has indicated in the Work that they are willing to receive error +reports for the Work (for example, by supplying a valid e-mail +address). It is not required for the Current Maintainer to acknowledge +or act upon these error reports. + +The Work changes from status `maintained' to `unmaintained' if there +is no Current Maintainer, or the person stated to be Current +Maintainer of the work cannot be reached through the indicated means +of communication for a period of six months, and there are no other +significant signs of active maintenance. + +You can become the Current Maintainer of the Work by agreement with +any existing Current Maintainer to take over this role. + +If the Work is unmaintained, you can become the Current Maintainer of +the Work through the following steps: + + 1. Make a reasonable attempt to trace the Current Maintainer (and + the Copyright Holder, if the two differ) through the means of + an Internet or similar search. + + 2. If this search is successful, then enquire whether the Work + is still maintained. + + a. If it is being maintained, then ask the Current Maintainer + to update their communication data within one month. + + b. If the search is unsuccessful or no action to resume active + maintenance is taken by the Current Maintainer, then announce + within the pertinent community your intention to take over + maintenance. (If the Work is a LaTeX work, this could be + done, for example, by posting to comp.text.tex.) + + 3a. If the Current Maintainer is reachable and agrees to pass + maintenance of the Work to you, then this takes effect + immediately upon announcement. + + b. If the Current Maintainer is not reachable and the Copyright + Holder agrees that maintenance of the Work be passed to you, + then this takes effect immediately upon announcement. + + 4. If you make an `intention announcement' as described in 2b. above + and after three months your intention is challenged neither by + the Current Maintainer nor by the Copyright Holder nor by other + people, then you may arrange for the Work to be changed so as + to name you as the (new) Current Maintainer. + + 5. If the previously unreachable Current Maintainer becomes + reachable once more within three months of a change completed + under the terms of 3b) or 4), then that Current Maintainer must + become or remain the Current Maintainer upon request provided + they then update their communication data within one month. + +A change in the Current Maintainer does not, of itself, alter the fact +that the Work is distributed under the LPPL license. + +If you become the Current Maintainer of the Work, you should +immediately provide, within the Work, a prominent and unambiguous +statement of your status as Current Maintainer. You should also +announce your new status to the same pertinent community as +in 2b) above. + + +WHETHER AND HOW TO DISTRIBUTE WORKS UNDER THIS LICENSE +====================================================== + +This section contains important instructions, examples, and +recommendations for authors who are considering distributing their +works under this license. These authors are addressed as `you' in +this section. + +Choosing This License or Another License +---------------------------------------- + +If for any part of your work you want or need to use *distribution* +conditions that differ significantly from those in this license, then +do not refer to this license anywhere in your work but, instead, +distribute your work under a different license. You may use the text +of this license as a model for your own license, but your license +should not refer to the LPPL or otherwise give the impression that +your work is distributed under the LPPL. + +The document `modguide.tex' in the base LaTeX distribution explains +the motivation behind the conditions of this license. It explains, +for example, why distributing LaTeX under the GNU General Public +License (GPL) was considered inappropriate. Even if your work is +unrelated to LaTeX, the discussion in `modguide.tex' may still be +relevant, and authors intending to distribute their works under any +license are encouraged to read it. + +A Recommendation on Modification Without Distribution +----------------------------------------------------- + +It is wise never to modify a component of the Work, even for your own +personal use, without also meeting the above conditions for +distributing the modified component. While you might intend that such +modifications will never be distributed, often this will happen by +accident -- you may forget that you have modified that component; or +it may not occur to you when allowing others to access the modified +version that you are thus distributing it and violating the conditions +of this license in ways that could have legal implications and, worse, +cause problems for the community. It is therefore usually in your +best interest to keep your copy of the Work identical with the public +one. Many works provide ways to control the behavior of that work +without altering any of its licensed components. + +How to Use This License +----------------------- + +To use this license, place in each of the components of your work both +an explicit copyright notice including your name and the year the work +was authored and/or last substantially modified. Include also a +statement that the distribution and/or modification of that +component is constrained by the conditions in this license. + +Here is an example of such a notice and statement: + + %% pig.dtx + %% Copyright 2005 M. Y. Name + % + % This work may be distributed and/or modified under the + % conditions of the LaTeX Project Public License, either version 1.3 + % of this license or (at your option) any later version. + % The latest version of this license is in + % http://www.latex-project.org/lppl.txt + % and version 1.3 or later is part of all distributions of LaTeX + % version 2005/12/01 or later. + % + % This work has the LPPL maintenance status `maintained'. + % + % The Current Maintainer of this work is M. Y. Name. + % + % This work consists of the files pig.dtx and pig.ins + % and the derived file pig.sty. + +Given such a notice and statement in a file, the conditions +given in this license document would apply, with the `Work' referring +to the three files `pig.dtx', `pig.ins', and `pig.sty' (the last being +generated from `pig.dtx' using `pig.ins'), the `Base Interpreter' +referring to any `LaTeX-Format', and both `Copyright Holder' and +`Current Maintainer' referring to the person `M. Y. Name'. + +If you do not want the Maintenance section of LPPL to apply to your +Work, change `maintained' above into `author-maintained'. +However, we recommend that you use `maintained', as the Maintenance +section was added in order to ensure that your Work remains useful to +the community even when you can no longer maintain and support it +yourself. + +Derived Works That Are Not Replacements +--------------------------------------- + +Several clauses of the LPPL specify means to provide reliability and +stability for the user community. They therefore concern themselves +with the case that a Derived Work is intended to be used as a +(compatible or incompatible) replacement of the original Work. If +this is not the case (e.g., if a few lines of code are reused for a +completely different task), then clauses 6b and 6d shall not apply. + + +Important Recommendations +------------------------- + + Defining What Constitutes the Work + + The LPPL requires that distributions of the Work contain all the + files of the Work. It is therefore important that you provide a + way for the licensee to determine which files constitute the Work. + This could, for example, be achieved by explicitly listing all the + files of the Work near the copyright notice of each file or by + using a line such as: + + % This work consists of all files listed in manifest.txt. + + in that place. In the absence of an unequivocal list it might be + impossible for the licensee to determine what is considered by you + to comprise the Work and, in such a case, the licensee would be + entitled to make reasonable conjectures as to which files comprise + the Work. diff --git a/Master/texmf-dist/doc/latex/etoolbox/README b/Master/texmf-dist/doc/latex/etoolbox/README index 34f858271aa..fdb0fb0030c 100644 --- a/Master/texmf-dist/doc/latex/etoolbox/README +++ b/Master/texmf-dist/doc/latex/etoolbox/README @@ -1,4 +1,4 @@ -$Id: README,v 1.4 2008/01/24 22:25:08 lehman stable $ +$Id: README,v 1.5 2008/04/26 18:23:00 lehman stable $ ABOUT @@ -12,17 +12,21 @@ elatex. LICENSE -Copyright (c) 2007 Philipp Lehman. This package is author- +Copyright (c) 2007--2008 Philipp Lehman. This package is author- maintained. Permission is granted to copy, distribute and/or modify this software under the terms of the LaTeX Project Public License -(LPPL), version 1.3. This software is provided `as is', without +(LPPL), version 1.3. This software is provided 'as is', without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. +REQUIREMENTS + +This package requires e-TeX. + INSTALLATION -Copy the file `etoolbox.sty' to +Copy the file 'etoolbox.sty' to <TEXMFLOCAL>/tex/latex/etoolbox/ @@ -31,17 +35,21 @@ tree, for example /usr/local/share/texmf/ or - c:\localtexmf\ + /usr/share/texmf-local/ +or + C:\Local TeX Files\ + +The manual ('etoolbox.pdf') goes to + + <TEXMFLOCAL>/doc/latex/etoolbox/ + +or to any other place where you will find it later. Note that you may have to create those directories if this is the first package you're installing locally (as opposed to via a package manager). Don't forget to update the file hash tables after -installing the files. Please see the following TeX FAQ answers for -further details: +installing the files. Please see the TeX FAQ at -http://www.tex.ac.uk/cgi-bin/texfaq2html?label=instpackages -http://www.tex.ac.uk/cgi-bin/texfaq2html?label=wherefiles -http://www.tex.ac.uk/cgi-bin/texfaq2html?label=tds + http://www.tex.ac.uk/faq -The manual may be copied to the `doc' subdirectory of the local TeX -installation tree or to any other place where you will find it later. +for further details. diff --git a/Master/texmf-dist/doc/latex/etoolbox/etoolbox.pdf b/Master/texmf-dist/doc/latex/etoolbox/etoolbox.pdf Binary files differindex e62400ba915..6a2733679bc 100644 --- a/Master/texmf-dist/doc/latex/etoolbox/etoolbox.pdf +++ b/Master/texmf-dist/doc/latex/etoolbox/etoolbox.pdf diff --git a/Master/texmf-dist/doc/latex/etoolbox/etoolbox.tex b/Master/texmf-dist/doc/latex/etoolbox/etoolbox.tex index 1a9bf266fbb..1e88f17e6f1 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.4 2008/01/24 22:25:08 lehman stable $ +% $Id: etoolbox.tex,v 1.5 2008/04/26 18:23:00 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 @@ -7,11 +7,13 @@ \documentclass{latexdoc} \usepackage[latin9]{inputenc} \usepackage[american]{babel} -\usepackage[strict,style=american]{csquotes} +\usepackage[strict,babel=once]{csquotes} +\usepackage{shortvrb} \MakeAutoQuote{«}{»} \MakeAutoQuote*{<}{>} +\MakeShortVerb{\|} -\rcsid{$Id: etoolbox.tex,v 1.4 2008/01/24 22:25:08 lehman stable $} +\rcsid{$Id: etoolbox.tex,v 1.5 2008/04/26 18:23:00 lehman stable $} \titlepage{% title={The \sty{etoolbox} package}, @@ -26,7 +28,7 @@ pdftitle={The etoolbox package}, pdfsubject={An e-TeX toolbox for class and package authors}, pdfauthor={Philipp Lehman}, - pdfkeywords={tex, etex, latex, class, package}} + pdfkeywords={tex, e-tex, latex, class, package, programming}} \begin{document} @@ -38,11 +40,11 @@ \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 previous 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. Note that the initial versions of this package were released under the name \sty{elatex}. \subsection{License} -Copyright \textcopyright\ 2007 Philipp Lehman. This package is author"=maintained. 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 software is provided <as is>, without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. +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} @@ -60,61 +62,110 @@ The facilities in this section are geared towards regular users as well as class \subsection{Definitions} \label{use:def} -\begin{syntax} +\begin{ltxsyntax} -\cmd{newrobustcmd}{command}[arguments][optarg default]{definition} +\cmd{newrobustcmd}{command}[arguments][optarg default]{replacement text} +\cmd*{newrobustcmd*}{command}[arguments][optarg default]{replacement text} -The syntax and behavior of this command is similar to \ltxcmd{newcommand} except that the newly defined \ltxarg{command} is robust. This command differs from the \ltxcmd{DeclareRobustCommand} command from the \latex kernel in that it issues an error rather than just an informational message if the \ltxarg{command} is already defined. Since it uses \etex's low-level protection mechanism rather than the corresponding high-level \latex facilities, it does not require an additional macro to implement the <robustness>. This command itself is also robust. +The syntax and behavior of this command is similar to \ltxcmd{newcommand} except that the newly defined \ltxarg{command} will be robust. This command differs from the \ltxcmd{DeclareRobustCommand} command from the \latex kernel in that it issues an error rather than just an informational message if the \ltxarg{command} is already defined. Since it uses \etex's low-level protection mechanism rather than the corresponding higher-level \latex facilities, it also does not require an additional macro to implement the <robustness>. This command itself is also robust. -\cmd{renewrobustcmd}{command}[arguments][optarg default]{definition} +\cmd{renewrobustcmd}{command}[arguments][optarg default]{replacement text} +\cmd*{renewrobustcmd*}{command}[arguments][optarg default]{replacement text} -The syntax and behavior of this command is similar to \ltxcmd{renewcommand} except that the redefined \ltxarg{command} is robust. This command itself is also robust. +The syntax and behavior of this command is similar to \ltxcmd{renewcommand} except that the redefined \ltxarg{command} will be robust. This command itself is also robust. -\cmd{providerobustcmd}{command}[arguments][optarg default]{definition} +\cmd{providerobustcmd}{command}[arguments][optarg default]{replacement text} +\cmd*{providerobustcmd*}{command}[arguments][optarg default]{replacement text} -The syntax and behavior of this command is similar to \ltxcmd{providecommand} except that the newly defined \ltxarg{command} is robust. Note that this command only provides a robust definition if the \ltxarg{command} is undefined. It will not make an already defined \ltxarg{command} robust. This command itself is robust. +The syntax and behavior of this command is similar to \ltxcmd{providecommand} except that a newly defined \ltxarg{command} will be robust. Note that this command only provides a robust definition if the \ltxarg{command} is undefined. It will not make an already defined \ltxarg{command} robust. This command itself is robust. + +\end{ltxsyntax} \subsection{Patching} \label{use:pat} +\begin{ltxsyntax} + \cmd{robustify}{command} -Redefines a \ltxarg{command} such that it is robust without altering its syntax or definition. If the \ltxarg{command} has been defined with \ltxcmd{DeclareRobustCommand}, this will be detected automatically. \latex's high-level protection mechanism is replaced by the corresponding low-level \etex facility in this case. This command is robust and may only be used in the document preamble. +Modifies an already defined \ltxarg{command} such that it is robust without altering its parameters, its prefixes, or its replacement text. If the \ltxarg{command} has been defined with \ltxcmd{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. This command is robust and may only be used in the document preamble. + +\end{ltxsyntax} + +\subsection[Lengths and counters]{Length and counter assignments} +\label{use:cal} + +The facilities in this section are replacements for \ltxcmd{setcounter} and \ltxcmd{setlength} which support arithmetic expressions. + +\begin{ltxsyntax} + +\cmd{defcounter}{counter}{integer expression} + +Assigns a value to a \latex \ltxarg{counter} previously initialized with \ltxcmd{newcounter}. This command is similar in concept and syntax to \ltxcmd{setcounter} except for two major differences. 1) The second argument may be an \ltxarg{integer expression} which will be processed with \ltxcmd{numexpr}. The \ltxarg{integer expression} may be any arbitrary code which is valid in this context. The value assigned to the \ltxarg{counter} will be the result of that calculation. 2) In contrast to \ltxcmd{setcounter}, the assignment is local by default but \ltxcmd{defcounter} may be prefixed with \ltxcmd{global}. The functional equivalent of \ltxcmd{setcounter} would be |\global\defcounter|. -\end{syntax} +\cmd{deflength}{length}{dimen expression} + +Assigns a value to a \ltxarg{length} register previously initialized with \ltxcmd{newlength}. This command is similar in concept and syntax to \ltxcmd{setlength} except that the second argument may be a \ltxarg{dimen expression} which will be processed with \ltxcmd{dimexpr}. The \ltxarg{dimen expression} may be any arbitrary code which is valid in this context. The value assigned to the \ltxarg{length} register will be the result of that calculation. The assignment is local by default but \ltxcmd{deflength} may be prefixed with \ltxcmd{global}. This command may be used as a drop-in replacement for \ltxcmd{setlength}. + +\end{ltxsyntax} + +\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 the end of the document body. The \ltxcmd{AtBeginDocument} code is executed at the beginning of the document body, \emph{after} the main \file{aux} file has been read for the first time. The \ltxcmd{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 \ltxarg{code} argument to slightly different locations. The \ltxarg{code} may be arbitrary \tex code. Macro parameter characters in the \ltxarg{code} argument need not be doubled. + +\begin{ltxsyntax} + +\cmd{AtEndPreamble}{code} + +This hook differs from \ltxcmd{AtBeginDocument} in that the \ltxarg{code} is executed right at the end of the preamble, before the main \file{aux} file (as written during the previous \latex pass) is read and prior to any \ltxcmd{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. Code deferred with \ltxcmd{AtBeginDocument}, however, is executed too late if it is required in the \file{aux} file. + +\cmd{AfterEndDocument}{code} + +This hook differs from \ltxcmd{AtEndDocument} in that the \ltxarg{code} is executed at the very end of the document, after the main \file{aux} file (as written during the current \latex pass) has been read and after any \ltxcmd{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. + +\cmd{AfterPreamble}{code} + +This hook is a variant of \ltxcmd{AtBeginDocument} which may be used in both the preamble and the document body. When used in the preamble, it behaves exactely like \ltxcmd{AtBeginDocument}. When used in the document body, it immediately executes its \ltxarg{code} argument (\ltxcmd{AtBeginDocument} issues an error in this case). + +\end{ltxsyntax} \section{Author commands} The facilities in this section are geared towards class and package authors. +%\addtocontents{toc}{\protect\columnbreak} + \subsection{Definitions} -\label{aut:def} + +\subsubsection{Macro definitions} +\label{aut:def:def} The facilities in this section are simple but frequently required shorthands which extend the scope of the \ltxcmd{@namedef} and \ltxcmd{@nameuse} macros from the \latex kernel. -\begin{syntax} +\begin{ltxsyntax} -\cmd{csdef}{csname}<arguments>{definition} +\cmd{csdef}{csname}<arguments>{replacement text} Similar to the \tex primitive \ltxcmd{def} except that it takes a control sequence name as its first argument. This command is robust and corresponds to \ltxcmd{@namedef}. -\cmd{csgdef}{csname}<arguments>{definition} +\cmd{csgdef}{csname}<arguments>{replacement text} Similar to the \tex primitive \ltxcmd{gdef} except that it takes a control sequence name as its first argument. This command is robust. -\cmd{csedef}{csname}<arguments>{definition} +\cmd{csedef}{csname}<arguments>{replacement text} Similar to the \tex primitive \ltxcmd{edef} except that it takes a control sequence name as its first argument. This command is robust. -\cmd{csxdef}{csname}<arguments>{definition} +\cmd{csxdef}{csname}<arguments>{replacement text} Similar to the \tex primitive \ltxcmd{xdef} except that it takes a control sequence name as its first argument. This command is robust. -\cmd{protected@csedef}{csname}<arguments>{definition} +\cmd{protected@csedef}{csname}<arguments>{replacement text} Similar to \ltxcmd{csedef} except that \latex's protection mechanism is temporarily enabled. To put it in other words: this command is similar to the \latex kernel command \ltxcmd{protected@edef} except that it takes a control sequence name as its first argument. This command is robust. -\cmd{protected@csxdef}{csname}<arguments>{definition} +\cmd{protected@csxdef}{csname}<arguments>{replacement text} Similar to \ltxcmd{csxdef} except that \latex's protection mechanism is temporarily enabled. To put it in other words: this command is similar to the \latex kernel command \ltxcmd{protected@xdef} except that it takes a control sequence name as its first argument. This command is robust. @@ -136,26 +187,26 @@ Takes a control sequence name as its argument and forms a control sequence token \cmd{undef}<command> -Clears the definition of \ltxarg{command} such that \etex's \ltxcmd{ifdefined} and \ltxcmd{ifcsname} tests will consider it as undefined. This command is robust and may be prefixed with \ltxcmd{global}. +Clears a \ltxarg{command} such that \etex's \ltxcmd{ifdefined} and \ltxcmd{ifcsname} tests will consider it as undefined. This command is robust and may be prefixed with \ltxcmd{global}. \cmd{csundef}{csname} Similar to \ltxcmd{undef} except that it takes a control sequence name as its argument. This command is robust and may be prefixed with \ltxcmd{global}. -\end{syntax} +\end{ltxsyntax} -\subsection{Arithmetic definitions} -\label{aut:cal} +\subsubsection{Arithmetic definitions} +\label{aut:def:cal} The facilities in this section permit calculations using macros rather than length registers and counters. -\begin{syntax} +\begin{ltxsyntax} -\cmd{numdef}{command}{integer expression} +\cmd{numdef}<command>{integer expression} -This command is similar to \ltxcmd{edef} except that the \ltxarg{integer expression} is processed with \ltxcmd{numexpr}. The \ltxarg{integer expression} may be any arbitrary code which is valid in this context. The definition assigned to \ltxarg{command} will be the result of that calculation. If the \ltxarg{command} is undefined, it will be initialized to <\texttt{0}> before the \ltxarg{integer expression} is processed. +Similar to \ltxcmd{edef} except that the \ltxarg{integer expression} is processed with \ltxcmd{numexpr}. The \ltxarg{integer expression} may be any arbitrary code which is valid in this context. The replacement text assigned to the \ltxarg{command} will be the result of that calculation. If the \ltxarg{command} is undefined, it will be initialized to <\texttt{0}> before the \ltxarg{integer expression} is processed. -\cmd{numgdef}{command}{integer expression} +\cmd{numgdef}<command>{integer expression} Similar to \ltxcmd{numdef} except that the assignment is global. @@ -167,11 +218,11 @@ Similar to \ltxcmd{numdef} except that it takes a control sequence name as its f Similar to \ltxcmd{numgdef} except that it takes a control sequence name as its first argument. -\cmd{dimdef}{command}{dimen expression} +\cmd{dimdef}<command>{dimen expression} -This command is similar to \ltxcmd{edef} except that the \ltxarg{dimen expression} is processed with \ltxcmd{dimexpr}. The \ltxarg{dimen expression} may be any arbitrary code which is valid in this context. The definition assigned to \ltxarg{command} will be the result of that calculation. If the \ltxarg{command} is undefined, it will be initialized to <\texttt{0pt}> before the \ltxarg{dimen expression} is processed. +Similar to \ltxcmd{edef} except that the \ltxarg{dimen expression} is processed with \ltxcmd{dimexpr}. The \ltxarg{dimen expression} may be any arbitrary code which is valid in this context. The replacement text assigned to the \ltxarg{command} will be the result of that calculation. If the \ltxarg{command} is undefined, it will be initialized to <\texttt{0pt}> before the \ltxarg{dimen expression} is processed. -\cmd{dimgdef}{command}{dimen expression} +\cmd{dimgdef}<command>{dimen expression} Similar to \ltxcmd{dimdef} except that the assignment is global. @@ -183,11 +234,11 @@ Similar to \ltxcmd{dimdef} except that it takes a control sequence name as its f Similar to \ltxcmd{dimgdef} except that it takes a control sequence name as its first argument. -\cmd{gluedef}{command}{glue expression} +\cmd{gluedef}<command>{glue expression} -This command is similar to \ltxcmd{edef} except that the \ltxarg{glue expression} is processed with \ltxcmd{glueexpr}. The \ltxarg{glue expression} may be any arbitrary code which is valid in this context. The definition assigned to \ltxarg{command} will be the result of that calculation. If the \ltxarg{command} is undefined, it will be initialized to <\texttt{0pt plus 0pt minus 0pt}> before the \ltxarg{glue expression} is processed. +Similar to \ltxcmd{edef} except that the \ltxarg{glue expression} is processed with \ltxcmd{glueexpr}. The \ltxarg{glue expression} may be any arbitrary code which is valid in this context. The replacement text assigned to the \ltxarg{command} will be the result of that calculation. If the \ltxarg{command} is undefined, it will be initialized to <\texttt{0pt plus 0pt minus 0pt}> before the \ltxarg{glue expression} is processed. -\cmd{gluegdef}{command}{glue expression} +\cmd{gluegdef}<command>{glue expression} Similar to \ltxcmd{gluedef} except that the assignment is global. @@ -199,11 +250,11 @@ Similar to \ltxcmd{gluedef} except that it takes a control sequence name as its Similar to \ltxcmd{gluegdef} except that it takes a control sequence name as its first argument. -\cmd{mudef}{command}{muglue expression} +\cmd{mudef}<command>{muglue expression} -This command is similar to \ltxcmd{edef} except that the \ltxarg{muglue expression} is processed with \ltxcmd{muexpr}. The \ltxarg{muglue expression} may be any arbitrary code which is valid in this context. The definition assigned to \ltxarg{command} will be the result of that calculation. If the \ltxarg{command} is undefined, it will be initialized to <\texttt{0mu}> before the \ltxarg{muglue expression} is processed. +Similar to \ltxcmd{edef} except that the \ltxarg{muglue expression} is processed with \ltxcmd{muexpr}. The \ltxarg{muglue expression} may be any arbitrary code which is valid in this context. The replacement text assigned to the \ltxarg{command} will be the result of that calculation. If the \ltxarg{command} is undefined, it will be initialized to <\texttt{0mu}> before the \ltxarg{muglue expression} is processed. -\cmd{mugdef}{command}{muglue expression} +\cmd{mugdef}<command>{muglue expression} Similar to \ltxcmd{mudef} except that the assignment is global. @@ -215,15 +266,15 @@ Similar to \ltxcmd{mudef} except that it takes a control sequence name as its fi Similar to \ltxcmd{mugdef} except that it takes a control sequence name as its first argument. -\end{syntax} +\end{ltxsyntax} \subsection{Expansion control} The facilities in this section are useful to control expansion in an \ltxcmd{edef} or a similar context. -\begin{syntax} +\begin{ltxsyntax} -\cmd{expandonce}{command} +\cmd{expandonce}<command> This command expands \ltxarg{command} once and prevents further expansion of the replacement text. @@ -233,43 +284,43 @@ Similar to \ltxcmd{expandonce} except that it takes a control sequence name as i \cmd{protecting}{code} -This command applies \latex's protection mechanism, which normally requires prefixing each fragile command with \ltxcmd{protect}, to an entire chunk of arbitrary \ltxarg{code} or text. Its behavior depends on the current state of \ltxcmd{protect}. Note that the braces around \ltxarg{code} are mandatory even if it is a single token. +This command applies \latex's protection mechanism, which normally requires prefixing each fragile command with \ltxcmd{protect}, to an entire chunk of arbitrary \ltxarg{code}. Its behavior depends on the current state of \ltxcmd{protect}. Note that the braces around the \ltxarg{code} are mandatory even if it is a single token. -\end{syntax} +\end{ltxsyntax} \subsection{Hook management} \label{aut:hok} -The facilities in this section are intended for hook management. A <hook> in this context is a plain macro without any arguments 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 them. For more complex patching operations, see section \ref{aut:pat}. All commands in this section will initialize the hook if it is undefined. +The facilities in this section are intended for hook management. A \ltxarg{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 \ltxarg{hook} if it is undefined. -\subsubsection{Appending code to a hook} +\subsubsection{Appending to a hook} \label{aut:hok:app} The facilities in this section append arbitrary code to a hook. -\begin{syntax} +\begin{ltxsyntax} -\cmd{appto}{command}{code} +\cmd{appto}<hook>{code} -This command appends arbitrary \ltxarg{code} to a \ltxarg{command}. If the \ltxarg{code} contains any parameter characters, they need not be doubled. This command is robust. +This command appends arbitrary \ltxarg{code} to a \ltxarg{hook}. If the \ltxarg{code} contains any parameter characters, they need not be doubled. This command is robust. -\cmd{gappto}{command}{code} +\cmd{gappto}<hook>{code} Similar to \ltxcmd{appto} except that the assignment is global. This command may be used as a drop-in replacement for the \ltxcmd{g@addto@macro} command in the \latex kernel. -\cmd{eappto}{command}{code} +\cmd{eappto}<hook>{code} -This command appends arbitrary \ltxarg{code} to a \ltxarg{command}. The \ltxarg{code} is expanded at definition"=time. Only the new \ltxarg{code} is expanded, the current definition of \ltxarg{command} is not. This command is robust. +This command appends arbitrary \ltxarg{code} to a \ltxarg{hook}. The \ltxarg{code} is expanded at definition"=time. Only the new \ltxarg{code} is expanded, the current replacement text of the \ltxarg{hook} is not. This command is robust. -\cmd{xappto}{command}{code} +\cmd{xappto}<hook>{code} Similar to \ltxcmd{eappto} except that the assignment is global. -\cmd{protected@eappto}{command}{code} +\cmd{protected@eappto}<hook>{code} Similar to \ltxcmd{eappto} except that \latex's protection mechanism is temporarily enabled. -\cmd{protected@xappto}{command}{code} +\cmd{protected@xappto}<hook>{code} Similar to \ltxcmd{xappto} except that \latex's protection mechanism is temporarily enabled. @@ -289,44 +340,44 @@ Similar to \ltxcmd{eappto} except that it takes a control sequence name as its f Similar to \ltxcmd{xappto} except that it takes a control sequence name as its first argument. -\cmd{protected@cseappto}{command}{code} +\cmd{protected@cseappto}<hook>{code} Similar to \ltxcmd{protected@eappto} except that it takes a control sequence name as its first argument. -\cmd{protected@csxappto}{command}{code} +\cmd{protected@csxappto}<hook>{code} Similar to \ltxcmd{protected@xappto} except that it takes a control sequence name as its first argument. -\end{syntax} +\end{ltxsyntax} -\subsubsection{Prepending code 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. -\begin{syntax} +\begin{ltxsyntax} -\cmd{preto}{command}{code} +\cmd{preto}<hook>{code} Similar to \ltxcmd{appto} except that the \ltxarg{code} is prepended. -\cmd{gpreto}{command}{code} +\cmd{gpreto}<hook>{code} Similar to \ltxcmd{preto} except that the assignment is global. -\cmd{epreto}{command}{code} +\cmd{epreto}<hook>{code} Similar to \ltxcmd{eappto} except that the \ltxarg{code} is prepended. -\cmd{xpreto}{command}{code} +\cmd{xpreto}<hook>{code} Similar to \ltxcmd{epreto} except that the assignment is global. -\cmd{protected@epreto}{command}{code} +\cmd{protected@epreto}<hook>{code} Similar to \ltxcmd{epreto} except that \latex's protection mechanism is temporarily enabled. -\cmd{protected@xpreto}{command}{code} +\cmd{protected@xpreto}<hook>{code} Similar to \ltxcmd{xpreto} except that \latex's protection mechanism is temporarily enabled. @@ -346,66 +397,45 @@ Similar to \ltxcmd{epreto} except that it takes a control sequence name as its f Similar to \ltxcmd{xpreto} except that it takes a control sequence name as its first argument. -\cmd{protected@csepreto}{command}{code} +\cmd{protected@csepreto}<hook>{code} Similar to \ltxcmd{protected@epreto} except that it takes a control sequence name as its first argument. -\cmd{protected@csxpreto}{command}{code} +\cmd{protected@csxpreto}<hook>{code} Similar to \ltxcmd{protected@xpreto} except that it takes a control sequence name as its first argument. -\end{syntax} - -\subsection[Predefined hooks]{Predefined all-purpose hooks} -\label{aut:pre} - -\latex provides two hooks which defer the execution of code either to the beginning or the end of the document body. The \ltxcmd{AtBeginDocument} code is executed at the beginning of the document body, \emph{after} the main \file{aux} file has been read for the first time. The \ltxcmd{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 \ltxarg{code} argument to slightly different locations. The \ltxarg{code} may be arbitrary \tex code. Macro parameter characters in the \ltxarg{code} argument need not be doubled. - -\begin{syntax} - -\cmd{AtEndPreamble}{code} - -This hook differs from \ltxcmd{AtBeginDocument} in that the \ltxarg{code} is executed right at the end of the preamble, before the main \file{aux} file (as written during the previous \latex pass) is read and prior to any \ltxcmd{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. Code deferred with \ltxcmd{AtBeginDocument}, however, is executed too late if it is required in the \file{aux} file. - -\cmd{AfterEndDocument}{code} - -This hook differs from \ltxcmd{AtEndDocument} in that the \ltxarg{code} is executed at the very end of the document, after the main \file{aux} file (as written during the current \latex pass) has been read and after any \ltxcmd{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. - -\cmd{AfterPreamble}{code} - -This hook is a variant of \ltxcmd{AtBeginDocument} which may also be used in the document body. When used in the document preamble, it behaves exactely like \ltxcmd{AtBeginDocument}. When used in the document body, it immediately executes its \ltxarg{code} argument (\ltxcmd{AtBeginDocument} issues an error in this case). - -\end{syntax} +\end{ltxsyntax} \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 number of arguments and the prefixes of the patched \ltxarg{command}. Note that the patching process involves detokenizing the \ltxarg{command} and retokenizing it under the current category code regime after patching. The category code of <@> is temporarily set to 11. If the definition of the \ltxarg{command} includes any tokens with non"=standard category codes, the respective category codes must be adjusted prior to patching. If the code to be replaced or inserted refers to the parameters of the \ltxarg{command} to be patched, the parameter characters need not be doubled when invoking one of the commands below. Note that \ltxcmd{outer} commands may not be patched. +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 \ltxarg{command}. Note that the patching process involves detokenizing the replacement text of the \ltxarg{command} and retokenizing it under the current category code regime after patching. The category code of <@> is temporarily set to 11. If the replacement text of the \ltxarg{command} includes any tokens with non"=standard category codes, the respective category codes must be adjusted prior to patching. If the code to be replaced or inserted refers to the parameters of the \ltxarg{command} to be patched, the parameter characters need not be doubled when invoking one of the commands below. Note that \ltxcmd{outer} commands may not be patched. -\begin{syntax} +\begin{ltxsyntax} \cmd{patchcmd}[prefix]{command}{search}{replace}{success}{failure} -This command extracts the definition of a \ltxarg{command}, replaces \ltxarg{search} with \ltxarg{replace}, and reassembles the \ltxarg{command}. The pattern match is category code agnostic and matches the first occurence of the \ltxarg{search} string in the definition of the \ltxarg{command} to be patched. If an optional \ltxarg{prefix} is specified, it replaces the prefixes of the \ltxarg{command}. An empty \ltxarg{prefix} strips all prefixes from the \ltxarg{command}. This command executes \ltxarg{success} if patching succeeds, and \ltxarg{failure} otherwise. It is robust and may only be used in the document preamble. The assignment is local. +This command extracts the replacement text of a \ltxarg{command}, replaces \ltxarg{search} with \ltxarg{replace}, and reassembles the \ltxarg{command}. The pattern match is category code agnostic and matches the first occurence of the \ltxarg{search} pattern in the replacement text of the \ltxarg{command} to be patched. If an optional \ltxarg{prefix} is specified, it replaces the prefixes of the \ltxarg{command}. An empty \ltxarg{prefix} strips all prefixes from the \ltxarg{command}. This command executes \ltxarg{success} if patching succeeds, and \ltxarg{failure} otherwise. It is robust and may only be used in the document preamble. The assignment is local. \cmd{ifpatchable}{command}{search}{true}{false} -This command executes \ltxarg{true} if the \ltxarg{command} is defined and the \ltxarg{search} pattern is found in its definition, and \ltxarg{false} otherwise. This command is robust and may only be used in the document preamble. +This command executes \ltxarg{true} if the \ltxarg{command} is defined and the \ltxarg{search} pattern is found in its replacement text, and \ltxarg{false} otherwise. This command is robust and may only be used in the document preamble. \cmd{apptocmd}{command}{code} -This command appends \ltxarg{code} to the definition of \ltxarg{command}. In contrast to the \ltxcmd{appto} command from section \ref{aut:hok:app}, this one may be used to patch a \ltxarg{command} which takes an arbitrary number of arguments. The \ltxarg{code} may refer to the parameters of the \ltxarg{command} in this case. This command is robust and may only be used in the document preamble. The assignment is local. +This command appends \ltxarg{code} to the replacement text of a \ltxarg{command}. In contrast to the \ltxcmd{appto} command from section \ref{aut:hok:app}, this one may be used to patch commands with an arbitrary number of parameters. The \ltxarg{code} may refer to the parameters of the \ltxarg{command} in this case. This command is robust and may only be used in the document preamble. The assignment is local. \cmd{pretocmd}{command}{code} -This command is similar to \ltxcmd{apptocmd} except that the \ltxarg{code} is <prepended>, \ie inserted at the beginning of the definition of \ltxarg{command}. In contrast to the \ltxcmd{preto} command from section \ref{aut:hok:app}, this one may be used to patch a \ltxarg{command} which takes an arbitrary number of arguments. The \ltxarg{code} may refer to the parameters of the \ltxarg{command} in this case. This command is robust and may only be used in the document preamble. The assignment is local. +This command is similar to \ltxcmd{apptocmd} except that the \ltxarg{code} is <prepended>, \ie inserted at the beginning of the replacement text of the \ltxarg{command}. In contrast to the \ltxcmd{preto} command from section \ref{aut:hok:app}, this one may be used to patch commands with an arbitrary number of parameters. The \ltxarg{code} may refer to the parameters of the \ltxarg{command} in this case. This command is robust and may only be used in the document preamble. The assignment is local. -\end{syntax} +\end{ltxsyntax} \subsection{Generic tests} \label{aut:tst} -\begin{syntax} +\begin{ltxsyntax} \cmd{ifdef}{command}{true}{false} @@ -425,7 +455,7 @@ Expands to \ltxarg{true} if \ltxarg{csname} is undefined, and to \ltxarg{false} \cmd{ifdefvoid}{command}{true}{false} -Expands to \ltxarg{true} if \ltxarg{command} is undefined, its meaning is \ltxcmd{relax}, or its definition is empty, and to \ltxarg{false} otherwise. +Expands to \ltxarg{true} if the \ltxarg{command} is undefined, its meaning is \ltxcmd{relax}, or its replacement text is empty, and to \ltxarg{false} otherwise. \cmd{ifcsvoid}{csname}{true}{false} @@ -433,12 +463,27 @@ Similar to \ltxcmd{ifdefvoid} except that it takes a control sequence name as it \cmd{ifdefequal}{command}{command}{true}{false} -Compares the definitions of two commands and expands to \ltxarg{true} if they are equal, and to \ltxarg{false} otherwise. In contrast to the \tex primitive \ltxcmd{ifx}, this test will also yield \ltxarg{false} if both commands are undefined or have a meaning of \ltxcmd{relax}. +Compares two commands and expands to \ltxarg{true} if they are equal in the sense of the \tex primitive \ltxcmd{ifx}, and to \ltxarg{false} otherwise. In contrast to \ltxcmd{ifx}, this test will also yield \ltxarg{false} if both commands are undefined or have a meaning of \ltxcmd{relax}. \cmd{ifcsequal}{csname}{csname}{true}{false} Similar to \ltxcmd{ifdefequal} except that it takes control sequence names as arguments. +\cmd{ifdefstring}{command}{string}{true}{false} + +Compares the replacement text of a \ltxarg{command} to a \ltxarg{string} and executes \ltxarg{true} if they are equal, and \ltxarg{false} otherwise. Neither the \ltxarg{command} nor the \ltxarg{string} is expanded in the test and the comparison is category code agnostic. Control sequence tokens in the \ltxarg{string} argument will be detokenized and treated as strings. This command is robust. Note that it will only consider the replacement text of the \ltxarg{command}. For example, this code + +\begin{ltxcode} +\long\def\@gobbletwo#1#2{} +\ifdefstring{\@gobbletwo}{}{true}{false} +\end{ltxcode} +% +would yield \ltxarg{true}. The prefix and the parameters of |\@gobbletwo| are ignored. + +\cmd{ifcsstring}{csname}{string}{true}{false} + +Similar to \ltxcmd{ifdefstring} except that it takes a control sequence name as its first argument. + \cmd{ifstrequal}{string}{string}{true}{false} Compares two strings and executes \ltxarg{true} if they are equal, and \ltxarg{false} otherwise. The strings are not expanded in the test and the comparison is category code agnostic. Control sequence tokens in any of the \ltxarg{string} arguments will be detokenized and treated as strings. This command is robust. @@ -447,19 +492,19 @@ Compares two strings and executes \ltxarg{true} if they are equal, and \ltxarg{f Expands to \ltxarg{true} if the \ltxarg{string} is blank (empty or spaces), and to \ltxarg{false} otherwise. The \ltxarg{string} is not expanded in the test. -\end{syntax} +\end{ltxsyntax} \subsection{Boolean switches} \label{aut:bol} This package provides two interfaces to boolean switches which are completely independent of each other. The facilities in section \ref{aut:bo1:bol} are a \latex frontend to \ltxcmd{newif}. Those in section \ref{aut:bo1:swi} use a different mechanism. -\subsubsection{Backwards-compatible switches} +\subsubsection{\tex switches} \label{aut:bo1:bol} Since the facilities in this section are based on \ltxcmd{newif} internally, they may be used to test and alter the state of switches previously defined with \ltxcmd{newif}. They are also compatible with the boolean tests of the \sty{ifthen} package. The \ltxcmd{newif} approach requires a total of three macros per switch. -\begin{syntax} +\begin{ltxsyntax} \cmd{newbool}{name} @@ -485,14 +530,14 @@ Expands to \ltxarg{true} if the state of the boolean switch \ltxarg{name} is \te Similar to \ltxcmd{ifbool} but reverses the logic of the test. -\end{syntax} +\end{ltxsyntax} -\subsubsection{Pure \latex switches} +\subsubsection{\latex switches} \label{aut:bo1:swi} In contrast to the switches from section \ref{aut:bo1:bol}, the facilities in this section require only one macro per switch. They also use a separate namespace to avoid name clashes with regular macros. -\begin{syntax} +\begin{ltxsyntax} \cmd{newtoggle}{name} @@ -518,7 +563,7 @@ Expands to \ltxarg{true} if the state of the boolean switch \ltxarg{name} is \te Similar to \ltxcmd{iftoggle} but reverses the logic of the test. -\end{syntax} +\end{ltxsyntax} \subsection{List processing} \label{aut:lst} @@ -526,44 +571,44 @@ Similar to \ltxcmd{iftoggle} but reverses the logic of the test. \subsubsection{User input} \label{aut:lst:inp} -The facilities in this section are primarily designed to handle user input. When building lists internally, using the facilities in section \ref{aut:lst:int} is preferable. +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} is preferable. -\begin{syntax} +\begin{ltxsyntax} \cmd{DeclareListParser}{command}{separator} -This command defines a list parser similar to the \ltxcmd{docsvlist} command below, which is defined with <\verb|\DeclareListParser{\docsvlist}{,}|>. Note that the list parsers are sensitive to the category code of the \ltxarg{separator}. +This command defines a list parser similar to the \ltxcmd{docsvlist} command below, which is defined with <|\DeclareListParser{\docsvlist}{,}|>. Note that the list parsers are sensitive to the category code of the \ltxarg{separator}. \cmd{docsvlist}{item, item, ...} -This command loops over a comma"=separated list and executes the auxiliary command \ltxcmd{do} for every item in the list, passing the item as an argument. In contrast to the \ltxcmd{@for} loop in the \latex kernel, \ltxcmd{docsvlist} is expandable. With a suitable definition of \ltxcmd{do}, lists may be processed inside an \ltxcmd{edef} or a comparable context. You may use \ltxcmd{listbreak} in the definition of \ltxcmd{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 \ltxenv{itemize} environment: +This command loops over a comma"=separated list and executes the auxiliary command \ltxcmd{do} for every item in the list, passing the item as an argument. In contrast to the \ltxcmd{@for} loop in the \latex kernel, \ltxcmd{docsvlist} is expandable. With a suitable definition of \ltxcmd{do}, lists may be processed inside an \ltxcmd{edef} or a comparable context. You may use \ltxcmd{listbreak} at the end of the replacement text of \ltxcmd{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 \ltxenv{itemize} environment: -\begin{lstlisting}[style=latex]{} +\begin{ltxcode} \begin{itemize} \renewcommand*{\do}[1]{\item #1} \docsvlist{item1, item2, {item3a, item3b}, item4} \end{itemize} -\end{lstlisting} +\end{ltxcode} % Here is another example: -\begin{lstlisting}[style=latex]{} +\begin{ltxcode} \renewcommand*{\do}[1]{* #1\MessageBreak} \PackageInfo{mypackage}{% Example list:\MessageBreak \docsvlist{item1, item2, {item3a, item3b}, item4}} -\end{lstlisting} +\end{ltxcode} % In this example, the list is written to the log file as part of an informational message. The list processing takes place during the \ltxcmd{write} operation. -\end{syntax} +\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 arguments 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. When processing user input in a list format, see the facilities in section \ref{aut:lst:inp}. -\begin{syntax} +\begin{ltxsyntax} \cmd{listadd}{listmacro}{item} @@ -575,7 +620,7 @@ Similar to \ltxcmd{listadd} except that the assignment is global. \cmd{listeadd}{listmacro}{item} -Similar to \ltxcmd{listadd} except that the \ltxarg{item} is expanded at definition"=time. Only the new \ltxarg{item} is expanded, the current definition of the list is not. This command is robust. +Similar to \ltxcmd{listadd} except that the \ltxarg{item} is expanded at definition"=time. Only the new \ltxarg{item} is expanded, the current list is not. \cmd{listxadd}{listmacro}{item} @@ -599,14 +644,14 @@ Similar to \ltxcmd{listcseadd} except that the assignment is global. \cmd{dolistloop}{listmacro} -This command loops over all items in a \ltxarg{listmacro} and executes the auxiliary command \ltxcmd{do} for every item in the list, passing the item as an argument. The list loop itself is expandable. You may use \ltxcmd{listbreak} in the definition of \ltxcmd{do} to stop processing and discard the remaining items in the list. Here is a usage example which prints an internal list called \ltxcmd{mylist} as an \ltxenv{itemize} environment: +This command loops over all items in a \ltxarg{listmacro} and executes the auxiliary command \ltxcmd{do} for every item in the list, passing the item as an argument. The list loop itself is expandable. You may use \ltxcmd{listbreak} at the end of the replacement text of \ltxcmd{do} to stop processing and discard the remaining items in the list. Here is a usage example which prints an internal list called \ltxcmd{mylist} as an \ltxenv{itemize} environment: -\begin{lstlisting}[style=latex]{} +\begin{ltxcode} \begin{itemize} \renewcommand*{\do}[1]{\item #1} \dolistloop{\mylist} \end{itemize} -\end{lstlisting} +\end{ltxcode} \cmd{dolistcsloop}{listcsname} @@ -614,20 +659,19 @@ Similar to \ltxcmd{dolistloop} except that it takes a control sequence name as i \cmd{ifinlist}{item}{listmacro} -This command checks if an \ltxarg{item} is included in a \ltxarg{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, e.g. the identifiers used in the argument of \ltxcmd{label} and \ltxcmd{ref}. When dealing with printable text, it may be preferable to use \ltxcmd{dolistloop} to check if an item is in the list as follows: +This command checks if an \ltxarg{item} is included in a \ltxarg{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 may be preferable to use \ltxcmd{dolistloop} to check if an item is in the list as follows: -\begin{lstlisting}[style=latex]{} +\begin{ltxcode} \renewcommand*{\do}[1]{% \ifstrequal{#1}{<<item>>} {item found!\listbreak} {}} \dolistloop{\mylist} - -\end{lstlisting} +\end{ltxcode} \cmd{xifinlist}{item}{listmacro} -Similar to \ltxcmd{ifinlist} except that the \ltxarg{item} is expanded prior to performing the test. +Similar to \ltxcmd{ifinlist} except that the \ltxarg{item} is expanded prior to the test. \cmd{ifinlistcs}{item}{listcsname} @@ -637,32 +681,52 @@ Similar to \ltxcmd{ifinlist} except that it takes a control sequence name as its Similar to \ltxcmd{xifinlist} except that it takes a control sequence name as its second argument. -\end{syntax} +\end{ltxsyntax} \subsection{Miscellaneous tools} \label{aut:msc} -\begin{syntax} +\begin{ltxsyntax} \cmd{rmntonum}{numeral} -The \tex primitive \ltxcmd{romannumeral} converts an integer to a Roman numeral but \tex or \latex provide no command which goes the opposite way. The \ltxcmd{rmntonum} command is such a macro which converts a Roman numeral to an integer. The parsing of the numeral is case"=insensitive. Since \ltxcmd{rmntonum} is expandable, it may be used in counter assignments, \ltxcmd{ifnum} comparisons, or in an \ltxcmd{edef}. For example: +The \tex primitive \ltxcmd{romannumeral} converts an integer to a Roman numeral but \tex or \latex provide no command which goes the opposite way. \ltxcmd{rmntonum} fills this gap. It takes a Roman numeral as its argument and converts it to the corresponding integer. Since it is expandable, it may also be used in counter assignments or \ltxcmd{ifnum} comparisons: -\begin{lstlisting}[style=latex]{} +\begin{ltxcode} +\rmntonum{mcmxcv} \setcounter{counter}{\rmntonum{CXVI}} \ifnum\rmntonum{mcmxcviii}<2000 ... -\end{lstlisting} +\end{ltxcode} % -Any invalid tokens in the \ltxarg{numeral} argument are silently ignored and have a numeric value of zero. Also note that \ltxcmd{rmntonum} will not check the numeral for formal validity. For example, both <v> and <vx> would yield <5>. +The \ltxarg{numeral} argument must be a literal string. It will be detokenized prior to parsing. The parsing of the numeral is case"=insensitive and whitespace in the argument is ignored. If there is an invalid token in the argument, \ltxcmd{rmntonum} will expand to~\texttt{-1}; an empty argument will yield an empty string. Note that \ltxcmd{rmntonum} will not check the numeral for formal validity. For example, both \texttt{V} and \texttt{VX} will yield~\texttt{5}. + +\cmd{ifrmnum}{string}{true}{false} -\end{syntax} +Expands to \ltxarg{true} if \ltxarg{string} is a Roman numeral, and to \ltxarg{false} otherwise. The \ltxarg{string} will be detokenized prior to performing the test. The test is case"=insensitive and ignores whitespace in the \ltxarg{string}. Note that \ltxcmd{ifrmnum} will not check the numeral for formal validity. For example, both \texttt{V} and \texttt{VXV} will yield \ltxarg{true}. Strictly speaking, what \ltxcmd{ifrmnum} does is parse the \ltxarg{string} in order to find out if it consists of characters which may form a valid Roman numeral. + +\end{ltxsyntax} \section{Revision history} \begin{changelog} -\begin{release}{1.4}{2007-01-24} +\begin{release}{1.5}{2008-04-26} + +\item Added \ltxcmd{defcounter}\see{use:cal} +\item Added \ltxcmd{deflength}\see{use:cal} +\item Added \ltxcmd{ifdefstring}\see{aut:tst} +\item Added \ltxcmd{ifcsstring}\see{aut:tst} +\item Improved \ltxcmd{rmntonum}\see{aut:msc} +\item Added \ltxcmd{ifrmnum}\see{aut:msc} +\item Added extended \pdf bookmarks to this manual +\item Rearranged manual slightly + +\end{release} + +\begin{release}{1.4}{2008-01-24} + \item Resolved conflict with \sty{tex4ht} + \end{release} \begin{release}{1.3}{2007-10-08} @@ -674,11 +738,11 @@ Any invalid tokens in the \ltxarg{numeral} argument are silently ignored and hav \item Renamed \ltxcmd{switchfalse} to \ltxcmd{togglefalse} (consistency)\see{aut:bo1:swi} \item Renamed \ltxcmd{ifswitch} to \ltxcmd{iftoggle} (consistency)\see{aut:bo1:swi} \item Renamed \ltxcmd{notswitch} to \ltxcmd{nottoggle} (consistency)\see{aut:bo1:swi} -\item Added \ltxcmd{undef}\see{aut:def} -\item Added \ltxcmd{csundef}\see{aut:def} -\item Added \ltxcmd{AtEndPreamble}\see{aut:pre} -\item Added \ltxcmd{AfterEndDocument}\see{aut:pre} -\item Added \ltxcmd{AfterPreamble}\see{aut:pre} +\item Added \ltxcmd{AtEndPreamble}\see{use:pre} +\item Added \ltxcmd{AfterEndDocument}\see{use:pre} +\item Added \ltxcmd{AfterPreamble}\see{use:pre} +\item Added \ltxcmd{undef}\see{aut:def:def} +\item Added \ltxcmd{csundef}\see{aut:def:def} \item Added \ltxcmd{ifdefvoid}\see{aut:tst} \item Added \ltxcmd{ifcsvoid}\see{aut:tst} \item Added \ltxcmd{ifdefequal}\see{aut:tst} @@ -726,16 +790,16 @@ Any invalid tokens in the \ltxarg{numeral} argument are silently ignored and hav \begin{release}{1.1}{2007-05-28} -\item Added \ltxcmd{protected@csedef}\see{aut:def} -\item Added \ltxcmd{protected@csxdef}\see{aut:def} -\item Added \ltxcmd{gluedef}\see{aut:cal} -\item Added \ltxcmd{gluegdef}\see{aut:cal} -\item Added \ltxcmd{csgluedef}\see{aut:cal} -\item Added \ltxcmd{csgluegdef}\see{aut:cal} -\item Added \ltxcmd{mudef}\see{aut:cal} -\item Added \ltxcmd{mugdef}\see{aut:cal} -\item Added \ltxcmd{csmudef}\see{aut:cal} -\item Added \ltxcmd{csmugdef}\see{aut:cal} +\item Added \ltxcmd{protected@csedef}\see{aut:def:def} +\item Added \ltxcmd{protected@csxdef}\see{aut:def:def} +\item Added \ltxcmd{gluedef}\see{aut:def:cal} +\item Added \ltxcmd{gluegdef}\see{aut:def:cal} +\item Added \ltxcmd{csgluedef}\see{aut:def:cal} +\item Added \ltxcmd{csgluegdef}\see{aut:def:cal} +\item Added \ltxcmd{mudef}\see{aut:def:cal} +\item Added \ltxcmd{mugdef}\see{aut:def:cal} +\item Added \ltxcmd{csmudef}\see{aut:def:cal} +\item Added \ltxcmd{csmugdef}\see{aut:def:cal} \item Added \ltxcmd{protected@eappto}\see{aut:hok:app} \item Added \ltxcmd{protected@xappto}\see{aut:hok:app} \item Added \ltxcmd{protected@cseappto}\see{aut:hok:app} |