summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/toolbox
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/toolbox
Initial commit
Diffstat (limited to 'macros/latex/contrib/toolbox')
-rw-r--r--macros/latex/contrib/toolbox/README18
-rw-r--r--macros/latex/contrib/toolbox/toolbox.dtx2869
-rw-r--r--macros/latex/contrib/toolbox/toolbox.ins22
-rw-r--r--macros/latex/contrib/toolbox/toolbox.pdfbin0 -> 153145 bytes
4 files changed, 2909 insertions, 0 deletions
diff --git a/macros/latex/contrib/toolbox/README b/macros/latex/contrib/toolbox/README
new file mode 100644
index 0000000000..c1ac72ba57
--- /dev/null
+++ b/macros/latex/contrib/toolbox/README
@@ -0,0 +1,18 @@
+The TeX programmer's toolbox; enhanced version.
+This (La)TeX package provides some macros which are convenient for
+writing indices, glossaries, or other macros.
+It contains macros which support
+
+ - implicit macros - a useful supplement to \index or varindex for
+ writing glossaries or indices
+ - fancy optional arguments
+ - loops over tokenlists and itemlists
+ - searching, splitting, and replacing
+ - controlled expansion
+ - redefinition of macros
+ - concatenated macro names
+
+Author: M. V\"ath martin@mvath.de
+
+The package may be distributed and/or modified under the conditions of
+the LaTeX Project Public License (version 1.3c or later).
diff --git a/macros/latex/contrib/toolbox/toolbox.dtx b/macros/latex/contrib/toolbox/toolbox.dtx
new file mode 100644
index 0000000000..c784c40ebc
--- /dev/null
+++ b/macros/latex/contrib/toolbox/toolbox.dtx
@@ -0,0 +1,2869 @@
+% \def\fileversion{5.1}\def\filedate{2004/04/29}\def\docdate{2013/11/26}
+%\iffalse These lines are necessary for the doc and docstrip utilities
+%<*asciidocu>
+
+%%#
+%%# Author:
+%%#
+%%# M. V\"ath martin@mvath.de
+%%#
+%%# The author thanks
+%%# David Kastrup <David.Kastrup@neuroinformatik.ruhr-uni-bochum.de>
+%%#
+
+%%# The package may be distributed and/or modified under the conditions of
+%%# the LaTeX Project Public License (version 1.3c or later).
+
+%%#############################################################################
+%%#
+%%# The TeX programmer's toolbox; enhanced version.
+%%# This (La)TeX package provides some macros which are convenient for
+%%# writing indices, glossaries, or other macros.
+%%# It contains macros which support
+%%#
+%%# - implicit macros - a useful supplement to \index or varindex for
+%%# writing glossaries or indices
+%%# - fancy optional arguments
+%%# - loops over tokenlists and itemlists
+%%# - searching, splitting, and replacing
+%%# - controlled expansion
+%%# - redefinition of macros
+%%# - concatenated macro names
+%%#
+%%#############################################################################
+
+%%#
+%%# This package was tested with plain TeX, LaTeX 2.09, and LaTeX 2e,
+%%# and it should actually run with all TeX formats.
+%%#
+
+% If you have access to (reasonable new) docstrip TeXfiles, you should run
+% tex/latex on the file
+% `toolbox.ins'
+% to produce the files `toolbox.sty', `toolbox.txt' and `toolbox.tex'.
+% (In case `toolbox.ins' is lost: You can find its content in the last
+% few lines of the file you are currently reading between the
+% lines %<*insfile> and %</insfile>;
+% BTW: You should name this file here `toolbox.dtx' before you run tex
+% on toolbox.ins).
+%
+% The file `toolbox.txt' contains a `brief' (but complete) ascii
+% documentation. If you have additionally access to LaTeX 2e, you may run
+% latex on the generated file `toolbox.tex' to produce `toolbox.dvi' which
+% contains a more luxury documentation.
+%
+% If you do not have access to the docstrip TeXfiles you may simply
+% copy/rename this file here into
+% `toolbox.sty'
+% to use the package and read the ascii documentation in this file.
+% The ascii documentation (the content of `toolbox.txt') consists of all
+% lines in this file which start with %%# (this is the above block and another
+% (very large) block which follows soon).
+%
+% But I do not recommended this, because TeX will need more time to read this
+% longer file, and because there might be a (very slight) incompatibility if
+% you use it (namely if you load `toolbox.sty' with some *extremely* strange
+% catcodes).
+% I recommend in this case instead to generate the file `toolbox.sty' as
+% anything between the lines %<*package> and %</package> by hand.
+% (This is not precisely the file which you get with the docstrip TeXfiles,
+% but a reasonable good substitute. To speed up loading, you may also
+% eliminate all lines starting with `% ' in `toolbox.sty').
+% For your information: The file `toolbox.tex' produced by the docstrip
+% TeXfiles is anything between the lines %<*driver> and %</driver>
+% (with a line containing \endinput and two comment lines appended)
+%
+%
+% In any case, you end up with the file `toolbox.sty'.
+%
+% If you can generate `toolbox.tex', you will probably want to stop
+% reading now and instead read the `luxury' documentation in `toolbox.dvi'.
+%
+% Otherwise, you have to make due with the following ascii documentation.
+%
+%
+% \fi\catcode\#14\relax\iffalse (This line is needed for the doc utility)
+%
+
+%%# To use toolbox, you have to put `toolbox.sty' in a path where TeX looks
+%%# for its input files. The TeX documents using toolbox need the
+%%# following modifications in their header:
+%%#
+%%# a) If you use LaTeX2.09, use toolbox as a style option, e.g.
+%%# \documentstyle[toolbox]{article}
+%%# or
+%%# \documentstyle[toolbox,12pt]{article}
+%%# b) If you use LaTeX2e, put in the preamble the command
+%%# \usepackage{toolbox}
+%%# c) If you use some other (non-LaTeX) format, you will probably have to
+%%# insert a line like
+%%# \catcode`\@=11\input toolbox.sty\catcode`\@=12\relax
+%%#
+%%# The only LaTeX-specific commands used in `toolbox.sty' are:
+%%#
+%%# \newcommand (only in the form \newcommand{\command}{} to ensure that
+%%# \command was not defined before)
+%%# \ProvidesPackage
+%%# \typeout
+%%#
+%%# The above commands are used only if they are defined.
+%%#
+
+%%#
+%%# Description of the provided macros:
+%%#
+
+%%# General remark: Many macros could appear in several sections.
+%%# For example, \toolboxMakeDef and \toolboxSourround might be considered
+%%# as macros which support redefinitions of macros. However, we put them
+%%# in different sections which perhaps explain better their nature.
+
+%%#
+%%# Implicit macro definitions
+%%# --------------------------
+
+%%# What we mean by implicit macro definitions is probably best explained by
+%%# the following examples which show the intended usage:
+%%#
+%%# (In the following examples, we always refer to the \index command. Note
+%%# that it may be more convenient to use for indices the varindex package in
+%%# addition - the documentation of varindex (release 2.3 or newer) gives
+%%# additional hints and examples how these two (essentially independent)
+%%# approaches can be combined in practice).
+%%#
+%%# Assume that you want to write an index for a book which has rather
+%%# long and complicated \index entries. The first idea that one might have in
+%%# this connection is to put the various \index commands at the beginning of
+%%# the document into several macros (one for each \index entry), and to use
+%%# just these macros in the main text. For example, one might want to write
+%%# near the beginning of the document commands like
+%%# \newcommand{\Start}{\index{finish or end}}
+%%# \newcommand{\End}{\index{finish or end}}
+%%# and then to use in the main text \Start and \End whenever a reference
+%%# in the corresponding index to the current place is desired.
+%%# However, this has two major disadvantages:
+%%# 1. Unless you are very disciplinary with your macro names, it is easy to
+%%# forget that \End writes an index entry. So the \End in the main text
+%%# might be very confusing.
+%%# 2. You cannot choose short and intuitive macro names for common phrases,
+%%# because they are usually already reserved by TeX, LaTeX, or some
+%%# packages.
+%%#
+%%# To avoid these problems, one may be very disciplinary and call the
+%%# involved macros systematically e.g. \GlossaryStart \GlossaryEnd etc.
+%%# However, this produces terrible long and unreadable macro names in the
+%%# main text.
+%%#
+%%# The implicit macro definitions of "toolbox" provide a more convenient
+%%# solution. The idea is that you do not use the corresponding macros directly
+%%# but only implicitly by a call of other macros where your "macro name" is
+%%# just an argument.
+%%# Moreover, "toolbox" assists you in writing the corresponding definitions.
+%%# For example, if you know that you want a set of macros which all expand
+%%# into something of the form \index{...}, you can give a ``mask'' which
+%%# contains this form, and you only have to fill in the changing content
+%%# (similarly as for usual TeX macros with arguments, but the level of
+%%# abstraction is one step higher).
+%%# For the above task, you might use the command:
+%%#
+%%# \toolboxMakeDef{Glossary}{\index{#1}}
+%%#
+%%# The argument `Glossary' serves to distinguish independent definitions
+%%# (this will become clear later). Its effect visible now is that it
+%%# determines the name of the following macros which you can use after
+%%# the above call:
+%%#
+%%# \NewGlossary{start-1}{start}
+%%# \NewGlossary{start-2}{start or beginning}
+%%# \NewGlossary{end}{finish or end}
+%%#
+%%# These command are now similar to the \newcommand definitions explained
+%%# above. However, there is no name collision with the TeX-internal command
+%%# \end. Of course, this means that you cannot just write \end in the main
+%%# text to get the desired index entry. Instead, you have to write the more
+%%# intuitive commands
+%%#
+%%# \Glossary{start-1}
+%%# \Glossary{start-2}
+%%# \Glossary{end}
+%%#
+%%# (again, the name \Glossary stems from our first call of \toolboxMakeDef).
+%%# Note that e.g. \Glossary{start-1} expands not only to `start' but
+%%# actually to \index{start} (because of our first call of \toolboxMakeDef).
+%%# Note also that you can use symbols like - or numbers which are usually
+%%# not allowed in TeX macro names.
+%%#
+%%# Of course, similarly as for \newcommand, you can also do other things with
+%%# the macros. For example,
+%%#
+%%# \LetGlossary\tempname{end}
+%%# \NewGlossary*{finish}\tempname
+%%#
+%%# will first define \tempname to expand to the same text as \Glossary{end},
+%%# and then defines a new entry \Glossary{finish} to expand to the same text
+%%# as \tempname. Hence, the above new lines make the calls \Glossary{end} and
+%%# \Glossary{finish} equivalent.
+%%#
+%%# At the end of your list of \NewGlossary commands, you might want to put
+%%#
+%%# \toolboxFreeDef*{Glossary}
+%%#
+%%# The purpose of this command is that \NewGlossary cannot be used anymore
+%%# (unless, of course, you define it again). So you cannot unintentionally
+%%# add new entries to your glossary list (but you still can use \Glossary{...}
+%%# to reference to the already produced entries).
+%%# Moreover, the above command frees some memory which was needed for
+%%# \NewGlossary to work.
+%%#
+%%# If you additionally want to free the memory used by \Glossary, you can use
+%%#
+%%# \toolboxFreeDef{Glossary}
+%%#
+%%# (without the `*'). This may be necessary, if you want to call again e.g.
+%%#
+%%# \toolboxMakeDef{Glossary}{\emph{#1}\index{#1}}
+%%#
+%%# (if you have not freed the memory for \Glossary before this repeated call,
+%%# TeX will complain that \Glossary is already defined).
+%%#
+%%# Of course, it is possible to call \toolboxMakeDef with several different
+%%# names, for example, for \Glossary, \SymbolList etc. Another application
+%%# might be to use a different command to mark e.g.\ the main occurrence of
+%%# some index entry or to output additionally the entry into the running text.
+%%# We do this in the following example which simultaneously
+%%# demonstrates that the names can also be constructed in another way:
+%%#
+%%# \toolboxMakeDef[Ind]{}{\index{#1}}
+%%# \toolboxMakeDef[Ind]{Main}{\index{#1|textbf}}
+%%# \toolboxMakeDef{OutInd}{#1}
+%%#
+%%# \IndNew{A}{A is a letter}
+%%# \IndNewMain{A}{A is a letter}
+%%# \NewOutInd{A}{\textbf{The letter A}\Ind{A}}
+%%#
+%%# After the above commands, you can use \Ind{A}, \IndMain{A}, and
+%%# \OutInd{A} to produce the corresponding \index entry, the "main" \index
+%%# entry (with a boldface page number), and the text \textbf{The letter A}
+%%# with an additional entry into the index, respectively.
+%%# Of course, it might usually be more convenient to define the \Ind and
+%%# \IndMain" entries simultaneously, e.g. as follows
+%%#
+%%# \toolboxMakeDef[Ind]{}{#1}
+%%# \toolboxMakeDef[Ind]{Main}{#1}
+%%# \newcommand{\NewStandardInd}[2]{%
+%%# \IndNew{#1}{\index{#2}}%
+%%# \IndNewMain{#1}{\index{#2|textbf}}}
+%%#
+%%# \NewStandardInd{A}{A is a letter}
+%%#
+%%# This approach has the additional advantage that you can define exceptional
+%%# cases "by hand" (e.g. if you want that for certain "main" index
+%%# entries the page number is printed with "\textsl" instead of "\textbf").
+
+
+%%# Since the motivation for implicit definitions now is hopefully clear,
+%%# let us now describe in detail which commands are provided by "toolbox"
+%%# for this purpose.
+%%# As explained in the example, the main generic macro provided to this
+%%# purpose is \toolboxMakeDef. Its call syntax is as follows:
+%%#
+%%# \toolboxMakeDef[Prefix]{Name}{ReplacementMask}
+%%#
+%%# (the argument [Prefix] is optional and by default empty).
+%%# The above command generates new macros
+%%#
+%%# \PrefixNewName
+%%# \PrefixRenewName
+%%# \PrefixProvideName
+%%# \PrefixDefName
+%%# \PrefixLetName
+%%# \PrefixName
+%%#
+%%# which in turn can be called as follows
+%%#
+%%# \PrefixNewName{something}{RememberText}
+%%# \PrefixRenewName{something}{RememberText}
+%%# \PrefixProvideName{something}{RememberText}
+%%# \PrefixDefName{something}{RememberText}
+%%# \PrefixNewName*{something}{\SomeMacro}
+%%# \PrefixRenewName*{something}{\SomeMacro}
+%%# \PrefixProvideName*{something}{\SomeMacro}
+%%# \PrefixDefName*{something}{\SomeMacro}
+%%# \PrefixLetName{\SomeMacro}{something}
+%%# \PrefixName{something}
+%%# \PrefixName*{something}
+%%#
+%%# These calls are in a sense similar to the respective commands
+%%#
+%%# \newcommand{\something}{RememberText}
+%%# \renewcommand{\something}{RememberText}
+%%# \providecommand{\something}{RememberText}
+%%# \def\something{RememberText}
+%%# \newcommand{\something}{}\let\something\SomeMacro
+%%# \renewcommand{\something}{}\let\something\SomeMacro
+%%# \@ifundefined\something{\let\something\SomeMacro}{}
+%%# \let\something\SomeMacro
+%%# \let\SomeMacro{\something}
+%%# \something
+%%# \something (but without error if \something is undefined).
+%%#
+%%# with the differences already pointed out before:
+%%# 1. The macro name actually used is not \something. Instead, it is a name
+%%# which does not conflict with any existing macro (except one
+%%# generated previously by another \PrefixNewName, but in this case a
+%%# descriptive error is reported). For this reason, it is not possible to
+%%# use this macro directly but only indirectly by the call
+%%# \PrefixName{something} (or with \PrefixLetName).
+%%# 2. The replacement text is not `RememberText' but determined by
+%%# ReplacementMask where every occurrence of #1 in ReplacementMask is
+%%# replaced by RememberText (recall the examples). If you want to have the
+%%# plain RememberText, use {#1} as ReplacementMask.
+%%#
+%%# Since toolbox 4.2 there is another slight difference: The symbol '#'
+%%# is treated as usual and not as in a macro definition.
+%%#
+%%# \toolboxMakeDef gives an error message if the commands
+%%# \Prefix... are already defined. If you intentionally want to
+%%# change a previous definition, you have to call the command
+%%#
+%%# \toolboxFreeDef[Prefix]{Name}
+%%#
+%%# before. The latter not only lets all of the macros \Prefix... be
+%%# \undefined, but also frees all other memory internally used by the
+%%# corresponding call of \toolboxMakeDef
+%%# (note, however, that the above command does not free the
+%%# memory allocated before by calls of \PrefixNew... - to free the latter,
+%%# you have to call subsequently e.g.
+%%#
+%%# \PrefixNewName*{...}{\undefined}
+%%#
+%%% before). There is also the command
+%%#
+%%# \toolboxFreeDef*[Prefix]{Name}
+%%#
+%%# which acts similarly as \toolboxFreeDef but which does not undefine the
+%%# two macros \PrefixName and \PrefixLetName.
+%%#
+
+
+%%#
+%%# Fancy optional argument parsing
+%%# -------------------------------
+
+%%# This section contains macros which are convenient if you e.g. write a
+%%# package that contains macros which contain a lot of optional arguments
+%%# and flags (like "*").
+%%# Typically, to read such an optional argument or flag, you save
+%%# the next token with \futurelet and then call a macro which decides what to
+%%# do with the token read. Thus, a typical use of \futurelet looks like
+%%#
+%%# \def\MacroWithOptionalFlag{\futurelet\tokread\myscan}
+%%#
+%%# which will define \tokread to be the token *following* the macro
+%%# \MacroWithOptionalFlag in the token stream and then execute \myscan.
+%%# In this context, it is not very convenient that you are *forced*
+%%# to define a macro \myscan: It could be more convenient if you could just
+%%# write the *content* of \tokread (in braces) into the above definition.
+%%# You can indeed do this if you replace \futurelet by \toolboxFuturelet:
+%%#
+%%# \toolboxFuturelet\token{argument}
+%%#
+%%# The call \toolboxFuturelet\token{\command} has precisely the same effect as
+%%# \futurelet\token\command. The advantage of \toolboxFuturelet is that
+%%# instead of a single \command one may use also a sequence of commands.
+
+%%# Let us consider \MacroWithOptionalFlag as above. Assume that the user
+%%# has called this macro in the form "\MacroWithOptionalFlag*" where the
+%%# "*" is a flag which should cause your macro to do something slightly
+%%# different. On some place in your macro definition you will have recognized
+%%# (e.g. with \futurelet or \toolboxFuturelet) that a "*" is following
+%%# in the calling sequence. So you now want to execute your action
+%%# (whatever \MacroWithOptionalFlag is supposed to do).
+%%# However, if you do not take special care, after this action, TeX will
+%%# print a "*", because this is the next token on the token stream: \futurelet
+%%# does not delete any tokens. So you have to "gobble" this token away.
+%%# A rude way to do this is by using the macro \gobblenext as the last token
+%%# in you macro which can be defined by
+%%# \begin{verbatim}
+%%# \def\gobblenext#1{}\end{verbatim}
+%%# However, this has two major drawbacks:
+%%#
+%%# 1. This works for "*", but not for "{" or space tokens.
+%%# For space tokens the situation is even worse, since TeX eats spaces
+%%# around arguments, so sometimes space tokens might unexpectedly
+%%# disappear.
+%%# 2. It is not possible in this way to read another argument following
+%%# the "*": Recall that \gobblenext must be the *last* token in your
+%%# macro expansion, i.e. you have "lost control" after this call.
+%%#
+%%# The solution to these problems is instead of calling \gobblenext to use
+%%# \toolboxGobbleNext as the last command in your call:
+%%# You can pass it an argument which describes the action that
+%%# you want to do *after* gobbling the next token ("*" in the above example)
+%%# from the token stream. Thus
+%%#
+%%# \toolboxGobbleNext{cmd}
+%%#
+%%# erases the token following that command from the token stream and
+%%# then executes cmd. This is similar to
+%%# \def\toolboxGobbleNext#1#2{#1}
+%%# with the difference that #2 is considered as a token and that no spaces
+%%# are eaten.
+%%# The effect is that e.g. the call
+%%#
+%%# Example:
+%%# \toolboxGobbleNext{\foo}{{arg}
+%%# is the same as \foo{arg} (the brace "{" is eaten in this example).
+
+%%# As described earlier, the commands "\futurelet" or "\toolboxFuturelet" can
+%%# be used to check for optional flags. Frequently you will only want
+%%# to test for one particular flag and decide the next action on this flag.
+%%# Of course, you can test the token found with \ifx...\f", but this has the
+%%# disadvantage that some tokens (e.g. \fi) follow your action, which might
+%%# be bad (recall that e.g. \toolboxGobbleNext must be the last command of
+%%# your action, i.e. it would in the above examples not gobble the "*" but
+%%# the "\fi" which is probably not what you want).
+%%# The simplest solution is to use the command \toolboxIfNextToken which
+%%# already has the test included. For example, to test for an optional "[",
+%%# you can simply write
+%%#
+%%# \def\MacroWithOptionalBrace{\toolboxIfNextToken[{\yes}{\no}}
+%%#
+%%# and then the call "\MacroWithOptionalBrace[...]" will expand to "\yes[...]"
+%%# while "\MacroWithOptionalBrace x" will expand to "\no x"
+%%# (note that the brace is not gobbled - if you want the latter,
+%%# use "\toolboxIfNextGobbling" described below).
+
+%%# More precisely, the calling syntax of "\toolboxIfNextToken" is
+%%#
+%%# \toolboxIfNextToken{token}{IfPart}{ElsePart}
+%%#
+%%# The semantic is the following:
+%%# If the token following this command is `token', then IfPart is executed,
+%%# otherwise ElsePart. It is explicitly admissible that `token' is a space.
+%%# To support further tests, \toolboxToken is \let to the token which follows
+%%# the command. \toolboxToken is only a temporary token, i.e.
+%%# it may also be modified by other commands of this package; in particular,
+%%# you may also freely to modify \toolboxToken.
+%%# The token \toolboxSpaceToken which is described later may be handy
+%%# in connection with this command.
+%%#
+%%# In contrast to similar LaTeX2e macros much care has been taken
+%%# that spaces are not eaten. This solves the following problem:
+%%#
+%%# Assume that you want to write a macro which should have the calling syntax
+%%# "\mymacro{arg1}" or "\mymacro{arg1}[arg2]". You will probably implement
+%%# \mymacro to read the first argument and then to look whether the next
+%%# token is a "[". If you use the LaTeX2e macro to test for "[",
+%%# then all spaces until the next non-space token would be gobbled which means
+%%# that if you would use the LaTeX2e macros for the test, then the call
+%%# "\mymacro{arg1} Text" would behave like "\mymacro{arg1}Text",
+%%# i.e. the space is `mysteriously' lost. With the "toolbox" macros this
+%%# does not happen. The `disadvantage' is that "\mymacro{arg1} [arg2]"
+%%# is not the same as "\mymacro{arg1}[arg2]" (which is reasonable IMHO).
+%%#
+%%# Example:
+%%#
+%%# \def\mycmd#1{\toolboxIfNextToken[{\ParseOpt{#1}}{\NoOpt{#1}}}
+%%# \def\ParseOpt#1[#2]{\OptAtEnd{#1}{#2}}
+%%#
+%%# After the above definition, \mycmd{arg} executes \NoOpt{arg} while
+%%# \mycmd{arg}[optional] executes \OptAtEnd{arg}{optional}
+%%# We point out once more that in the first call a space following
+%%# \mycmd{arg} does not vanish (as would be the case if the LaTeX 2e macros
+%%# would have been used).
+
+%%# If \toolboxIfNextToken has found the required token, it does *not*
+%%# gobble that token from the token stream. Of course, you can do this by
+%%# yourself using the earlier described macro \toolboxGobbleNext. However,
+%%# it is simpler to use
+%%#
+%%# \toolboxIfNextGobbling{token}{IfPart}{ElsePart}
+%%#
+%%# This command is analogous to \toolboxIfNextToken with the difference that
+%%# in the case that the next token is the desired token, it is gobbled before
+%%# IfPart is executed.
+%%#
+%%# Example:
+%%#
+%%# \def\myloop{\toolboxIfNextGobbling*\toolboxTokenLoop\toolboxLoop}
+%%#
+%%# This makes \myloop*... behave like \toolboxTokenLoop, and
+%%# \myloop... (without *) behave like \toolboxLoop.
+
+%%# The following macro is one which you may want to use in connection with
+%%# LaTeX 2e optional arguments:
+%%#
+%%# \toolboxIfEmpty{arg}{IfPart}{ElsePart}
+%%#
+%%# The argument is not expand; it is only used to decide whether the
+%%# {IfPart} or the {ElsePart} will be expanded.
+%%# For further tests there are more involved macros:
+%%#
+%%# \toolboxIfx{arg}\macro{IfPart}{ElsePart}
+%%#
+%%# This tests via \ifx whether \def\Macro{arg} would give the definition
+%%# of \macro.
+%%#
+%%# \toolboxIfX{arga}{argb}{IfPart}{ElsePart}
+%%#
+%%# This tests whether "arga" and "argb" are the same token sequences.
+%%# If you want to avoid the \else and \fi commands to avoid certain side
+%%# effects, you can use instead:
+%%#
+%%# \toolboxIfElse{ifcmd}{IfPart}{ElsePart}
+%%#
+%%# This is rather analogous to "ifcmd" IfPart \else ElsePart \fi
+%%# but has everything in this line already eliminated from the tokenlist
+%%# when IfPart resp. ElsePart are expanded.
+
+%%#
+%%# Loops over tokenlists and itemlists
+%%# -----------------------------------
+
+%%# \toolboxLoop{items}{action}
+%%#
+%%# This calls iteratively "action{#1}", where #1 runs over each item in the
+%%# argument items. Here, an item is either a token or a group braced by {...}.
+%%# In the latter case, the braces are lost. Spaces in items are ignored
+%%# (unless they are braced). It is admissible that \action is not a single
+%%# macro but instead a sequence of tokens.
+%%# Examples follow below.
+%%#
+%%# The counterintuitive order of arguments is explained by the fact that the
+%%# typical usage is
+%%# \expandafter\toolboxLoop\expandafter{\MacroExpandingToItems}{action}
+%%# which for swapped order of arguments could hardly be written.
+
+%%# \toolboxLoop is not reentrant i.e. "action" may not expand
+%%# to something which contains a call to \toolboxLoop. To enable such calls
+%%# anyway, the command
+%%#
+%%# \toolboxLoopName{name}{items}{\action}
+%%#
+%%# is provided which is analogous to \toolboxLoop. This is also not reentrant,
+%%# but in contrast to \toolboxLoop, calls with different `name' arguments can
+%%# be used independently of each other, i.e. in the `action' part of a
+%%# \toolboxLoop (or \toolboxLoopName) can be a call to \toolboxLoopName with
+%%# a *different* `name'.
+%%# In particular, using a counter in `name' one could easily implement
+%%# even recursive calls. In this connection, it should be noted that
+%%# `name' is expanded via \csname ... \endcsname, and so you may use
+%%# constructs like \the\namecounter there.
+
+%%# \toolboxTokenLoop{tokens}{\action}
+%%#
+%%# This is similar to \toolboxLoop: The command \action\toolboxToken
+%%# is executed iteratively where \toolboxToken runs over each token in tokens.
+%%# The important difference is that \toolboxToken is a token (instead of an
+%%# item). In particular, \toolboxToken runs through every single token
+%%# including spaces and braces.
+%%# The token \toolboxSpaceToken which is described later may be handy
+%%# in connection with this command.
+%%#
+%%# Example:
+%%#
+%%# \toolboxTokenLoop{Some text}{\kern0.1em}
+%%#
+%%# is the similar to "\kern0.1em S\kern0.1em o\kern0.1em m...", i.e. you
+%%# get wider spacing between the letters of "Some text" (I do not claim that
+%%# this is typographically a good idea).
+%%#
+%%# Note that you do not have to take special care about the space.
+%%# With \toolboxLoop, you would have to mask the space e.g. with
+%%#
+%%# \toolboxLoop{Some{ }text}{\kern0.1em} or
+%%# \toolboxLoop{Some\toolboxSpace text}{\kern0.1em}
+%%#
+%%# In contrast, \toolboxTokenLoop would behave differently here:
+%%#
+%%# \toolboxTokenLoop{Some{ }text}{\kern0.1em}
+%%#
+%%# would produce \kern0.1em S...\kern0.1em{\kern0.1em <space>\kern0.1em}...
+%%# because the braces are simply considered as tokens.
+
+%%# \toolboxTokenLoop is not reentrant. Analogously to \toolboxLoopName,
+%%# independent versions can be generated by
+%%#
+%%# \toolboxTokenName{name}{tokens}{\action}
+
+%%#
+%%# Controlled expansion
+%%# --------------------
+
+%%# There are some occasions when you want more control over the expansion.
+%%# E.g. you might want to concatenate the contents of two macros to a
+%%# further macro or you want to expand a macro by one level but no full
+%%# expansion. Usually you can get this effects with \expandafter, but if
+%%# you expand several concatenated tokens in this way you either have to
+%%# write a lot of \expandafter's or you have to define subsidiary macros
+%%# that help you to \expandafter certain parts of macros. The macros in
+%%# this section allow you to do this in the most generic way that I could
+%%# implement.
+
+%%# \toolboxDef\macrotodefine{argumentlist}
+%%#
+%%# This call is similar to
+%%# \def\macrotodefine{argumentlist}
+%%# with two important differences:
+%%#
+%%# For \toolboxDef, the argumentlist is expanded precisely by one level.
+%%# argumentlist may not contain macros with parameters, and spaces on the
+%%# highest level are ignored. If you want to force a space on a particular
+%%# place, use the macro \toolboxSpace at this place
+%%# (which is described later). Contrary to the usual \def, the symbol # is
+%%# treated as a usual symbol.
+%%#
+%%# Example of usage:
+%%# \toolboxDef\chain{\chain\toolboxSpace\after}
+%%# This modifies the macro \chain such that a space and the content of the
+%%# macro \after is appended at the end.
+
+%%# \toolboxAppend\macrotodefine{arglist}
+%%#
+%%# This is equivalent to \toolboxDef\macrotodefine{\macrotodefine arglist}
+%%#
+
+%%# \toolboxSurround{ContentBefore}{ContentAfter}\macro
+%%#
+%%# This redefines \macro such that ContentBefore is put at the beginning
+%%# and ContentAfter after the definition of \macro. So this is equivalent to
+%%# \def\macro{ContentBefore * ContentAfter}
+%%# where * is the old content of \macro. It is required that \macro is a
+%%# usual macro without any arguments. If you want to patch more complicated
+%%# macros, use the patch.doc package instead.
+%%# The order of the arguments may appear strange, but it is convenient if
+%%# ContentBefore or ContentAfter are macros which should be expanded with
+%%# \expandafter.
+
+%%# There is some subsidiary macro used in the implementation of the above
+%%# macros which might be useful also in some other situations:
+%%#
+%%# \toolboxTokDef{argumentlist}\macrotodefine
+%%#
+%%# This call is similar to
+%%# \def\macrotodefine{argumentlist}
+%%# with the difference that the symbol # is stored as such.
+%%# The order of the arguments has been swapped in order to simplify the
+%%# application of \expandafter to the argumentlist.
+
+%%#
+%%# Searching, splitting, and replacing
+%%# ----------------------------------
+
+%%# \toolboxSplitAt{argument}{search}{\beforestring}{\afterstring}
+%%#
+%%# Here, \beforestring and \afterstring are arbitrary macro names,
+%%# and search and argument are any sequences of tokens (which are in
+%%# the following considered as `strings').
+%%#
+%%# This call scans the string `argument' for the first occurrence of `search'.
+%%# The macros \beforestring and \afterstring are defined correspondingly
+%%# such that \beforestring expands to the part before the first occurrence,
+%%# and \afterstring to the part following the first occurrence.
+%%# If `search' does not occur in `argument', \beforestring is defined to
+%%# `argument', and \afterstring is \let \undefined.
+%%#
+%%# If \beforestring or \afterstring had already been defined before the
+%%# call, the previous definition is tacitly overridden.
+%%# It is explicitly allowed that \beforestring and \afterstring are the
+%%# same names. In this case, the result has the meaning of \afterstring.
+%%#
+%%# It is guaranteed that braces {...} are *not* lost in `argument'.
+%%# However, `search' may not contain any braces, and `argument' may contain
+%%# only matching pairs of braces. Moreover, occurrences of `search' within a
+%%# pair of braces in `argument' are not recognized.
+%%#
+%%# (The order of the arguments has been chosen in order to simplify the
+%%# use of \expandafter).
+%%#
+%%# There are some restrictions for the strings in search. For example,
+%%# the symbol '#' is not allowed.
+%%#
+%%# In the above call, the arguments may not run over several paragraphs.
+%%# If you want the latter, you have to use the alternative call
+%%#
+%%# \toolboxSplitAt*{argument}{search}{\beforestring}{\afterstring}
+%%#
+%%# Example of usage:
+%%#
+%%# \def\examplemacro#1{\toolboxSplitAt{#1}{@}\testme\testme
+%%# \ifx\testme\undefined
+%%# ... (do this when #1 contains no `@' token)
+%%# \fi}
+%%#
+
+%%# \toolboxMakeSplit{search}{command}
+%%#
+%%# If \toolboxSplitAt should be used several times with the same search
+%%# string, it is much more effective to use the above call: This call
+%%# defines a new macro \command (the name is determined by the second argument
+%%# of \toolboxMakeSplit) which can be called in the form
+%%#
+%%# \command{argument}{\beforestring}{\afterstring}
+%%#
+%%# and which has the analogous meaning as \toolboxSplitAt (the argument
+%%# {search} is implicitly fixed and taken from the call of
+%%# \toolboxMakeSplit).
+%%# It is explicitly admissible that the above macro \toolboxMakeSplit is
+%%# used with an already existing command name. In this case, the previous
+%%# definition of \command is tacitly overridden.
+%%#
+%%# The command created by \toolboxMakeSplit does not accept arguments which
+%%# run over several paragraphs. If you want the latter, you have to create
+%%# this command by the alternative call
+%%#
+%%# \toolboxMakeSplit*{search}{command}
+
+%%#
+%%# The command
+%%# \toolboxFreeSplit{command}
+%%# frees the memory used by a previous \toolboxMakeSplit (and lets \command
+%%# again be undefined).
+
+%%# The command
+%%# \toolboxReplace{search}{replace}\macro
+%%# replaces in \macro all occurences of {search} by {replace}.
+%%# The same matches are found as in \toolboxSplitAt.
+%%# If you need to search for the same text several times, it is faster
+%%# to use the command
+%%# \toolboxReplaceSplit{replace}\SplitCmd\macro
+%%# where \SplitCmd is a command previously generated with \toolboxMakeSplit*
+%%# according to your search string. (You could also use \toolboxMakeSplit
+%%# to generate \SplitCmd, but then \macro should not contain any \par's).
+
+%%#
+%%# Redefinition of macros
+%%# ----------------------
+
+%%# \toolboxMakeHarmless{\macro}
+%%#
+%%# The above call redefines \macro such that it expands to an ASCII text
+%%# containing the previous definition of \macro (i.e. the catcodes of \macro
+%%# are changed).
+
+%%# \toolboxDropBrace\variable
+%%#
+%%# drops possible outer braces in \variable. More precisely,
+%%# if \variable expands to {content}, then \variable is redefined to
+%%# content (without braces). Otherwise, nothing happens.
+
+%%#
+%%# \toolboxIf\comparison{DefinitionCommand}{\macro}...
+%%#
+%%# The above command allows conditional definitions.
+%%# Here, {DefinitionCommand} is either \def, {\long\def}, \let, or some
+%%# similar command like the LaTeX \newcommand. If the test
+%%# \ifx\comparison\macro evaluates positive, then \macro is defined
+%%# correspondingly. Otherwise, \macro is not changed.
+%%#
+%%# Examples:
+%%#
+%%# \toolboxIf\undefined\def\macro{....}
+%%# \toolboxIf\undefined\let\macro...
+%%# \toolboxIf\undefined{\long\def}\macro{....}
+%%# \toolboxIf\undefined\newcommand{\macro}{....}
+%%#
+%%# are similar to \def\macro{...} resp. \let\macro... resp.
+%%# \long\def\macro{...} resp. \newcommand{\macro}{...} with the difference
+%%# that \macro is not changed if it was already defined.
+%%# In this sense, \toolboxIf is a more flexible variant of \providecommand.
+%%#
+
+%%# \toolboxNewiftrue{name} or \toolboxNewiffalse{name}
+%%#
+%%# If the command \ifname was already introduced with \newif, then
+%%# nothing happens. Otherwise \ifname is introduced similarly to
+%%# \newif\ifname and set to `true' respectively `false'.
+%%# In contrast to the corresponding command in TeX or LaTeX 2.09, this macro
+%%# is not \outer!
+
+%%# \toolboxNewifTrue{name} or \toolboxNewifFalse{name}
+%%#
+%%# are similar to \toolboxNewiftrue{name} and \toolboxNewiffalse{name},
+%%# respectively, with the difference that \ifname is set unconditionally
+%%# to `true' respectively `false'.
+
+%%#
+%%# Concatenated macro names
+%%# ------------------------
+
+%%# \toolboxLet\variable{macroname}
+%%#
+%%# The above command is analogous to \let\variable\macroname with the
+%%# difference that macroname can also contain other tokens like numbers
+%%# (it is obtained via \csname). Some converse to this command is
+%%#
+%%# \toolboxWithNr {number}\cmd{macro}
+%%#
+%%# which translates into \cmd\macronumber (here, `macro' and `number'
+%%# are just concatenated and evaluated via \csname).
+%%# Examples:
+%%# \toolboxWithNr 1\let{name}\toolboxEmpty
+%%# This is the same as \let\name1\toolboxEmpty
+%%# (but such that \name1 is considered as a name, not as \name 1)
+%%# \toolboxWithNr {10}\def{name}{Foo}
+%%# This corresponds analogously to \def\name10{Foo}.
+%%# \toolboxLet \mymacro{name\the\mycount}
+%%# This is similar to \let\mymacro\namexx where xx is the content
+%%# of the counter \mycount.
+
+%%#
+%%# Various
+%%# -------
+
+%%# The following macros have equivalents in most formats (like LaTeX2e).
+%%# However, we do not want to rely too much on these formats, so we provide
+%%# our own definitions.
+%%# The macro
+%%# \toolboxEmpty
+%%# expands to nothing (usually, this is the same as \empty).
+%%# Similarly, the macro
+%%# \toolboxSpace
+%%# expands to a space symbol (usually, this is the same as \space).
+%%# The token
+%%# \toolboxSpaceToken
+%%# is \let a space token (usually, this is the same as \@sptoken).
+%%# This token is convenient in tests of tokens
+%%# (because it is hard to get a space there which is not eaten by the TeX
+%%# parser, although sometimes also constructions like
+%%# \expandafter\ifx\toolboxSpace\token can be used).
+%%# Also the macros
+%%# \toolboxFirstOfTwo
+%%# \toolboxSecondOfTwo
+%%# are provided which read two arguments and return only the first
+%%# respectively second argument (usually, this is the same as
+%%# \@firstoftwo respectively \@secondoftwo). Similarly,
+%%# \toolboxGobbleArg{argument}
+%%# just reads its argument and expands to nothing.
+
+
+
+% This is the end of the ascii documentation
+%</asciidocu>
+%\fi\catcode\#6\relax
+%
+% \iffalse
+%<*metainfo>
+% \fi
+
+% \def\basename{toolbox}
+
+%% \CharacterTable
+%% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
+%% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
+%% Digits \0\1\2\3\4\5\6\7\8\9
+%% Exclamation \! Double quote \" Hash (number) \#
+%% Dollar \$ Percent \% Ampersand \&
+%% Acute accent \' Left paren \( Right paren \)
+%% Asterisk \* Plus \+ Comma \,
+%% Minus \- Point \. Solidus \/
+%% Colon \: Semicolon \; Less than \<
+%% Equals \= Greater than \> Question mark \?
+%% Commercial at \@ Left bracket \[ Backslash \\
+%% Right bracket \] Circumflex \^ Underscore \_
+%% Grave accent \` Left brace \{ Vertical bar \|
+%% Right brace \} Tilde \~}
+
+% \CheckSum{736}
+
+% \iffalse
+% \RecordChanges
+% \fi
+% \def\mypar{}
+% \def\ChangesTab{}\let\orichanges\changes
+% \def\changes#1#2#3{\orichanges{#1}{#2}{#3}
+% \expandafter\def\expandafter\ChangesTab\expandafter{\ChangesTab
+% \item[v#1 {\mdseries(\emph{#2})}] {#3.}}}
+% \newcommand{\cmdcite}[1]{\texttt{\textbackslash#1}}
+% \newcommand{\bracemeta}[1]{\texttt{\{}\meta{#1}\texttt{\}}}
+% \newcommand{\cmdmeta}{\textbackslash\meta}
+
+% \changes{5.1}{2013/11/26}{Update email, add license. Date/version remains the
+% same since only commments and documentation are modified}
+% \changes{5.1}{2004/04/29}{Added \cmdcite{toolboxReplace},
+% \cmdcite{toolboxReplaceSplit}. Some corrections in the documentation.
+% Added some forgotten \cmdcite{long}'s in the code.}
+% \changes{4.4}{2003/10/07}{Added \cmdcite{toolboxIfEmpty},
+% \cmdcite{toolboxIfx}, \cmdcite{toolboxIfX}, \cmdcite{toolboxIfElse}.
+% Some corrections in the documentation}
+% \changes{4.3}{2002/09/27}{Major enhancements in documentation: Added lots
+% of examples and explanation about typical applications.
+% Bugfix in \cmdcite{toolboxMakeDef}:
+% \cmdmeta{Prefix}\texttt{Provide}\meta{Name} now behaves like
+% \cmdcite{providecommand} as documented. The old meaning is now called
+% \cmdmeta{Prefix}\texttt{Def}\meta{Name}.
+% Introduced \cmdcite{toolboxGobbleArg}}
+% \changes{4.2}{2001/09/26}{Treating \texttt{\#} properly now also in
+% \cmdcite{toolboxMakeDef}}
+% \changes{4.1}{2001/09/24}{Took more care of treating \texttt{\#} properly
+% when this symbol occurs in arguments of certain macros (the treatment is
+% not completely downward compatible; for this reason the major release
+% number has been changed). For this reason,
+% also the new macro \cmdcite{toolboxTokDef} is provided. I thank
+% David Kastrup \texttt{<David.Kastrup@neuroinformatik.ruhr-uni-bochum.de>}
+% for pointing out this problem (and a solution) to me}
+% \changes{3.3}{2001/08/19}{Eliminated a bug in \cmdcite{toolboxMakeSplit*}}
+% \changes{3.2}{2001/05/08}{Eliminated a serious bug in \cmdcite{toolboxIf}.
+% Due to this bugfix, the usage of \cmdcite{toolboxIf} had to be slightly
+% restricted}
+% \changes{3.1}{2001/05/06}{Major advantage: \cmdcite{toolboxMakeDef}
+% implemented.\mypar
+% Reimplemented \cmdcite{newif} (apparently by mistake, this had been
+% declared as \cmdcite{outer} in \TeX\ and \LaTeX 2.09 which caused an
+% error during loading of \texttt{toolbox.sty}).
+% For this reason, also \cmdcite{toolboxNewifTrue} and
+% \cmdcite{toolboxNewifFalse} were introduced}
+% \changes{2.1}{2001/04/30}{Introduced \cmdcite{toolboxIf},
+% \cmdcite{toolboxAppend}, and \cmdcite{toolboxSurround}}
+% \changes{2.0}{2001/04/08}{Many major enhancements and new tools:
+% Added section (and corresponding macros)
+% for fancy optional arguments. Made \cmdcite{toolboxLoop} semi-reentrant by
+% introducing \cmdcite{toolboxLoopName}.
+% Added \cmdcite{toolboxTokenLoop} and friends.
+% Added \cmdcite{toolboxSpaceToken}.
+% Made many macros \cmdcite{long} and added \cmdcite{long} versions
+% of \cmdcite{toolboxSplitAt} and \cmdcite{toolboxMakeSplit}}
+% \changes{1.0}{2001/03/29}{First release}
+%
+% \iffalse
+%
+% The following part is the code needed to compile the documentation.
+% We do some trickery here, because we want that this file here could be used
+% for *both*: Compiling the documentation *and* as `toolbox.sty'
+% (if really required).
+% Everything between the lines %<*driver> and %</driver>
+% goes to the file `toolbox.tex'.
+%
+% \fi
+\ifcat @a% If this test is positive, then `@' has letter catcode which means
+% that this file is loaded as a style file (or as described in the
+% install section of the documentation).
+\def\TemporaryDummy{}
+\else\long\def\TemporaryDummy{%
+%
+%
+% \iffalse
+%</metainfo>
+%<*driver>
+\documentclass{ltxdoc}
+\OnlyDescription%% Comment this out, or
+%%\AlsoImplementation%% uncomment this line, if you want to see the source.
+
+%% If you want an index, uncomment one of the following lines.
+%% After running latex a first time, you have to use
+%% makeindex -s gind.ist toolbox
+%% Then run latex again.
+%%\CodelineIndex% comment this out if you want an index referring to codelines
+%%\PageIndex% comment this out if you want an index referring to pages
+%%\OldMakeindex% uncomment this line, if your MakeIndex is pre-v2.9
+
+\setlength\hfuzz{15pt}
+\hbadness=7000
+\begin{document}
+\DocInput{toolbox.dtx}
+\end{document}
+%</driver>
+%<*metainfo>
+% \fi
+}
+\fi\TemporaryDummy\let\TemporaryDummy\undefined
+%
+% \iffalse
+% Personal macros used for the doc utility:
+% \fi
+% \MakeShortVerb{"}
+% \newcommand{\filecite}[1]{\texttt{#1}}
+% \newcommand{\nocomment}{}
+% \newcommand{\myspace}{\texttt{\textvisiblespace}}
+% \parindent0pt
+
+% \title{The \texttt{toolbox} package\thanks
+% {This package has version number \fileversion{}, last revised \filedate.
+% The package may be distributed and/or modified under the conditions of the
+% LaTeX Project Public License, either version 1.3c of this license or (at
+% your option) any later version. The latest version of this license is in
+% \texttt{http://www.latex-project.org/lppl.txt}, and version 1.3c or later
+% is part of all distributions of LaTeX version 2005/12/01 or later.}}
+% \author{Martin V\"ath\relax
+%\thanks{\texttt{martin@mvath.de}}
+%{}\thanks{The author thanks
+%David Kastrup \texttt{<David.Kastrup@neuroinformatik.ruhr-uni-bochum.de>}.
+%}}
+% \date{\docdate}
+% \maketitle\sloppy
+
+% \begin{abstract}
+% The \TeX\ programmer's toolbox; enhanced version.
+% This package provides some macros which are convenient for writing
+% indices, glossaries, or other macros. It contains macros which support
+% \begin{itemize}
+% \item implicit macros -- a useful supplement to \cmdcite{index} or
+% \texttt{varindex} for writing glossaries or indices.
+% \item fancy optional arguments
+% \item loops over tokenlists and itemlists
+% \item searching, splitting, and replacing
+% \item controlled expansion
+% \item redefinition of macros
+% \item concatenated macro names
+% \end{itemize}
+% \end{abstract}
+
+% You may copy this package freely, as long as you distribute only unmodified
+% and complete versions.
+
+% \tableofcontents
+
+% \section{Changes}
+%
+% \begin{description}
+% \def\mypar{\par}\ChangesTab
+% \end{description}
+%
+
+% \section{Installation}
+
+% This package was tested with \TeX, \LaTeX 2.09, and \LaTeXe, and it
+% should actually run with all other \TeX\ formats.
+
+% To use \filecite{toolbox}, you have to put the file \filecite{toolbox.sty}
+% in a path where \TeX\ looks for its input files. The \TeX\ documents using
+% \filecite{toolbox} need the following modifications in their header:
+%
+% \begin{itemize}
+% \item If you use \LaTeXe, put in the preamble the command
+% \begin{verbatim}
+% \usepackage{toolbox}\end{verbatim}
+%
+% \item If you use \LaTeX 2.09, use \filecite{toolbox} as a style option, e.g.\
+% \begin{verbatim}
+% \documentstyle[toolbox]{article}\end{verbatim}
+% or
+% \begin{verbatim}
+% \documentstyle[toolbox,12pt]{article}\end{verbatim}
+%
+% \item If you use some other (non-\LaTeX) format, you will probably have to
+% insert a line like
+% \begin{verbatim}
+% \catcode`\@=11\input toolbox.sty\catcode`\@=12\relax\end{verbatim}
+%
+% \end{itemize}
+%
+% The only \LaTeX-specific commands used in \filecite{toolbox.sty} are:
+%
+% \begin{itemize}
+% \item "\newcommand" (used only in the form "\newcommand{"\meta{command}"}{}"
+% to ensure that \meta{command} was not defined before)
+% \item "\ProvidesPackage"
+% \item "\typeout"
+% \end{itemize}
+% The above commands are used only if they are defined.
+
+% \section{Description of the macros}
+%
+% General remark: Many macros could appear in several sections.
+% For example, "\toolboxMakeDef" and "\toolboxSourround" might be considered
+% as macros which support redefinitions of macros. However, we put them
+% in different sections which perhaps explain better their nature.
+%
+% \subsection{Implicit macro definitions}
+%
+% What we mean by implicit macro definitions is probably best explained by
+% the following examples which show the intended usage:\par\bigskip
+%
+% (In the following examples, we always refer to the "\index" command. Note
+% that it may be more convenient to use for indices the \filecite{varindex}
+% package in addition -- the documentation of \filecite{varindex}
+% (release 2.3 or newer) gives additional hints and examples how these two
+% (essentially independent) approaches can be combined in practice).
+% \par\bigskip
+%
+% Assume that you want to write an index for a book which has rather
+% long and complicated "\index" entries. The first idea that one might have in
+% this connection is to put the various "\index" commands at the beginning of
+% the document into several macros (one for each "\index" entry), and to use
+% just these macros in the main text. For example, one might want to write
+% near the beginning of the document commands like
+% \begin{verbatim}
+% \newcommand{\Start}{\index{finish or end}}
+% \newcommand{\End}{\index{finish or end}}\end{verbatim}
+% and then to use in the main text "\Start" and "\End" whenever a reference
+% in the corresponding index to the current place is desired.
+% However, this has two major disadvantages:
+% \begin{enumerate}
+% \item It is easy to forget that "\End" writes an index entry.
+% So the macro "\End" in the main text might be very confusing.
+% \item You cannot choose short and intuitive macro names for common phrases,
+% because they are usually already reserved by \TeX, \LaTeX, or some
+% packages. For example, "\end" could not be used.
+% \end{enumerate}
+% To avoid these problems, one may be very disciplinary and call the
+% involved macros systematically e.g.\ "\GlossaryStart" "\GlossaryEnd" etc.
+% However, this produces terrible long and unreadable macro names in the main
+% text.\par\bigskip
+% The implicit macro definitions of \filecite{toolbox} provide a more
+% convenient solution.
+% The idea is that you do not use the corresponding macros directly but only
+% implicitly by a call of other macros where your ``macro name'' is just an
+% argument.\par
+% Moreover, \filecite{toolbox} assists you in writing the corresponding
+% definitions.
+% For example, if you know that you want a set of macros which all expand
+% into something of the form "\index{...}", you can give a ``mask'' which
+% contains this form, and you only have to fill in the changing content
+% (similarly as for usual \TeX\ macros with arguments, but the level of
+% abstraction is one step higher).
+% For the above task, you might use the command:
+% \begin{verbatim}
+% \toolboxMakeDef{Glossary}{\index{#1}}\end{verbatim}
+%
+% The argument "Glossary" serves to distinguish independent definitions
+% (this will become clear later). Its effect visible now is that it
+% determines the name of the following macros which you can use after
+% the above call:
+% \begin{verbatim}
+% \NewGlossary{start-1}{start}
+% \NewGlossary{start-2}{start or beginning}
+% \NewGlossary{end}{finish or end}\end{verbatim}
+%
+% These command are now similar to the "\newcommand" definitions explained
+% above. However, there is no name collision with the \TeX-internal command
+% "\end". Of course, this means that you cannot just write "\end" in the main
+% text to get the desired index entry. Instead, you have to write the more
+% intuitive commands
+% \begin{verbatim}
+% \Glossary{start-1}
+% \Glossary{start-2}
+% \Glossary{end}\end{verbatim}
+% (again, the name "\Glossary" stems from our first call of "\toolboxMakeDef").
+% Note that e.g.\ "\Glossary{start-1}" expands not only to "start" but
+% actually to "\index{start}" (because of our first call of
+% "\toolboxMakeDef").\par
+% Note also that you can use symbols like ``-'' or numbers which are
+% usually not allowed in \TeX\ macro names.
+%
+% Of course, similarly as for "\newcommand", you can also do other things with
+% the macros. For example,
+% \begin{verbatim}
+% \LetGlossary\tempname{end}
+% \NewGlossary*{finish}\tempname\end{verbatim}
+%
+% will first define "\tempname" to expand to the same text as "\Glossary{end}",
+% and then defines a new entry "\Glossary{finish}" to expand to the same text
+% as "\tempname". Hence, the above two lines make the calls "\Glossary{end}"
+% and "\Glossary{finish}" equivalent.
+%
+% At the end of your list of "\NewGlossary" commands, you might want to put
+% \begin{verbatim}
+% \toolboxFreeDef*{Glossary}\end{verbatim}
+%
+% The purpose of this command is that "\NewGlossary" cannot be used anymore
+% (unless, of course, you define it again). So you cannot unintentionally
+% add new entries to your glossary list (but you still can use "\Glossary{...}"
+% to reference to the already produced entries).
+% Moreover, the above command frees some memory which was needed for
+% "\NewGlossary" to work.
+%
+% If you additionally want to free the memory used by "\Glossary", you can use
+% \begin{verbatim}
+% \toolboxFreeDef{Glossary}\end{verbatim}
+%
+% (without the "*"). This may be necessary, if you want to call again e.g.
+% \begin{verbatim}
+% \toolboxMakeDef{Glossary}{\emph{#1}\index{#1}}\end{verbatim}
+%
+% (if you have not freed the memory for "\Glossary" before this repeated call,
+% \TeX\ will complain that "\Glossary" is already defined).\par\smallskip
+%
+% Of course, it is possible to call "\toolboxMakeDef" with several different
+% names, for example, for "\Glossary", "\SymbolList" etc. Another application
+% might be to use a different command to mark e.g.\ the main occurrence of
+% some index entry or to output additionally the entry into the running text.
+% We do this in the following example which simultaneously
+% demonstrates that the names can also be constructed in another way:
+% \begin{verbatim}
+% \toolboxMakeDef[Ind]{}{\index{#1}}
+% \toolboxMakeDef[Ind]{Main}{\index{#1|textbf}}
+% \toolboxMakeDef{OutInd}{#1}
+%
+% \IndNew{A}{A is a letter}
+% \IndNewMain{A}{A is a letter}
+% \NewOutInd{A}{\textbf{The letter A}\Ind{A}}\end{verbatim}
+% After the above commands, you can use "\Ind{A}", "\IndMain{A}", and
+% "\OutInd{A}" to produce the corresponding "\index" entry, the ``main''
+% "\index" entry (with a fat page number), and the text \textbf{The letter A}
+% with an additional entry into the index, respectively.
+% Of course, it might usually be more convenient to define the "\Ind" and
+% "\IndMain" entries simultaneously, e.g.\ by the commands
+% \begin{verbatim}
+% \toolboxMakeDef[Ind]{}{#1}
+% \toolboxMakeDef[Ind]{Main}{#1}
+% \newcommand{\NewStandardInd}[2]{%
+% \IndNew{#1}{\index{#2}}%
+% \IndNewMain{#1}{\index{#2|textbf}}}
+%
+% \NewStandardInd{A}{A is a letter}\end{verbatim}
+% This approach has the additional advantage that you can define exceptional
+% cases ``by hand'' (e.g.\ if you want that for certain ``main'' index
+% entries the page number is printed with "\textsl" instead of "\textbf").
+% \bigskip
+%
+% Since the motivation for implicit definitions now is hopefully clear,
+% let us now describe in detail which commands are provided by
+% \filecite{toolbox} for this purpose.
+% As explained in the example, the main generic macro provided to this
+% purpose is \DescribeMacro{\toolboxMakeDef}"\toolboxMakeDef".
+% Its call syntax is as follows:
+% \begin{quote}
+% "\toolboxMakeDef["\meta{Prefix}"]"\bracemeta{Name}\relax
+%\bracemeta{Replacement mask}
+% \end{quote}
+% (the argument "["\meta{Prefix}"]" is optional and by default empty).
+% The above command generates new macros
+%
+% \begin{quote}
+% \cmdmeta{Prefix}"New"\meta{Name}\\
+% \cmdmeta{Prefix}"Renew"\meta{Name}\\
+% \cmdmeta{Prefix}"Provide"\meta{Name}\\
+% \cmdmeta{Prefix}"Def"\meta{Name}\\
+% \cmdmeta{Prefix}"Let"\meta{Name}\\
+% \cmdmeta{Prefix}\meta{Name}
+% \end{quote}
+% which in turn can be called as follows:
+% \begin{quote}
+% \cmdmeta{Prefix}"New"\meta{Name}\bracemeta{something}\relax
+%\bracemeta{text to remember}\\
+% \cmdmeta{Prefix}"Renew"\meta{Name}\bracemeta{something}\relax
+%\bracemeta{text to remember}\\
+% \cmdmeta{Prefix}"Provide"\meta{Name}\bracemeta{something}\relax
+%\bracemeta{text to remember}\\
+% \cmdmeta{Prefix}"Def"\meta{Name}\bracemeta{something}\relax
+%\bracemeta{text to remember}\\
+% \cmdmeta{Prefix}"New"\meta{Name}"*"\bracemeta{something}\relax
+%{\cmdmeta{SomeMacro}}\\
+% \cmdmeta{Prefix}"Renew"\meta{Name}"*"\bracemeta{something}\relax
+%{\cmdmeta{SomeMacro}}\\
+% \cmdmeta{Prefix}"Provide"\meta{Name}"*"\bracemeta{something}\relax
+%{\cmdmeta{SomeMacro}}\\
+% \cmdmeta{Prefix}"Def"\meta{Name}"*"\bracemeta{something}\relax
+%{\cmdmeta{SomeMacro}}\\
+% \cmdmeta{Prefix}"Let"\meta{Name}{\cmdmeta{SomeMacro}}\bracemeta{something}\\
+% \cmdmeta{Prefix}\meta{Name}\bracemeta{something}\\
+% \cmdmeta{Prefix}\meta{Name}"*"\bracemeta{something}
+% \end{quote}
+% These calls are in a sense similar to the respective commands
+% \begin{quote}
+% "\newcommand{"\cmdmeta{something}"}"\bracemeta{text to remember}\\
+% "\renewcommand{"\cmdmeta{something}"}"\bracemeta{text to remember}\\
+% "\providecommand{"\cmdmeta{something}"}"\bracemeta{text to remember}\\
+% "\def"\cmdmeta{something}\bracemeta{text to remember}\\
+% "\newcommand{"\cmdmeta{something}"}{}"\relax
+%"\let"\cmdmeta{something}\cmdmeta{SomeMacro}\\
+% "\renewcommand{"\cmdmeta{something}"}{}"\relax
+%"\let"\cmdmeta{something}\cmdmeta{SomeMacro}\\
+% "\@ifundefined"\bracemeta{something}"{\let"\relax
+%\cmdmeta{something}\cmdmeta{SomeMacro}"}{}"\\
+% "\let"\cmdmeta{something}\cmdmeta{SomeMacro}\\
+% "\let"\cmdmeta{SomeMacro}{\cmdmeta{something}}\\
+% \cmdmeta{something}\\
+% \cmdmeta{something} (but without error if \cmdmeta{something} is undefined)
+% \end{quote}
+% with the differences already pointed out before:
+% \begin{enumerate}
+% \item The macro name actually used is not \cmdmeta{something}.
+% Instead, it is a name which does not conflict with any existing macro
+% (except one generated previously by another \cmdmeta{Prefix}New\meta{Name},
+% but in this case a descriptive error is reported).\par
+% For this reason, it is not possible to use this macro directly but only
+% indirectly by the call \cmdmeta{Prefix}\meta{Name}\bracemeta{something}
+% (or with \cmdmeta{Prefix}Let\meta{Name}).
+% \item The replacement text is not \meta{text to remember} but determined by
+% \meta{Replacement Mask} where every occurrence of "#1" in
+% \meta{Replacement Mask} is replaced by \meta{text to remember}
+% (recall the examples). If you want to have the plain
+% \meta{text to remember}, use "{#1}" as \meta{Replacement Mask}.
+% \end{enumerate}
+% Since \filecite{toolbox~4.2} there is another slight difference:
+% The symbol "#" is treated as usual and not as in a macro definition.\par
+%
+% "\toolboxMakeDef" gives an error message if the commands
+% \cmdmeta{Prefix}"..." are already defined. If you intentionally want to
+% change a previous definition, you have to call the command
+%
+% \begin{quote}
+% \DescribeMacro{\toolboxFreeDef}
+% "\toolboxFreeDef["\meta{Prefix}"]"\bracemeta{Name}
+% \end{quote}
+% before. The latter not only lets all of the macros \cmdmeta{Prefix}"..." be
+% "\undefined", but also frees all other memory internally used by the
+% corresponding call of "\toolboxMakeDef"
+% (note, however, that the above command does not free the
+% memory allocated before by calls of \cmdmeta{Prefix}"New..." -- to free the
+% latter, you have to call subsequently e.g.
+% \begin{quote}
+% \cmdmeta{Prefix}"New"\meta{Name}"*{"$\ldots$"}{\undefined}"
+% \end{quote}
+% before). There is also the command
+% \begin{quote}
+% "\toolboxFreeDef*["\meta{Prefix}"]"\bracemeta{Name}
+% \end{quote}
+% which acts similarly as "\toolboxFreeDef" but which does not undefine the
+% two macros \cmdmeta{Prefix}\meta{Name} and \cmdmeta{Prefix}"Let"\meta{Name}.
+%
+
+% \subsection{Fancy optional argument parsing}
+%
+% This section contains macros which are convenient if you e.g.\ write a
+% package that contains macros which contain a lot of optional arguments
+% and flags (like "*").
+% Typically, to read such an optional argument or flag, you save
+% the next token with "\futurelet" and then call a macro which decides what to
+% do with the token read. Thus, a typical use of "\futurelet" looks like
+% \begin{verbatim}
+% \def\MacroWithOptionalFlag{\futurelet\tokread\myscan}\end{verbatim}
+% which will define "\tokread" to be the token \emph{following} the macro
+% "\MacroWithOptionalFlag" in the token stream and then execute "\myscan".
+% In this context, it is not very convenient that you
+% are \emph{forced} to define a macro "\myscan": It could be more convenient
+% if you could just write the \emph{content} of "\tokread" (in braces) into
+% the above definition. You can indeed do this if you replace "\futurelet"
+% by \DescribeMacro{\toolboxFuturelet}"\toolboxFuturelet":
+%
+% \begin{quote}
+% "\toolboxFuturelet\token"\bracemeta{argument}
+% \end{quote}
+%
+% The call "\toolboxFuturelet\token{\command}" has precisely the same
+% effect as "\futurelet\token\command". The advantage of "\toolboxFuturelet"
+% is that instead of a single "\command" one may use also a sequence of
+% commands.\par
+
+% Let us consider "\MacroWithOptionalFlag" as above. Assume that the user
+% has called this macro in the form "\MacroWithOptionalFlag*" where the
+% "*" is a flag which should cause your macro to do something slightly
+% different. On some place in your macro definition you will have recognized
+% (e.g.\ with "\futurelet" or "\toolboxFuturelet") that a "*" is following
+% in the calling sequence. So you now want to execute your action
+% (whatever "\MacroWithOptionalFlag" is supposed to do).
+% However, if you do not take special care, after this action, \TeX\ will
+% print a "*", because this is the next token on the token stream: "\futurelet"
+% does not delete any tokens. So you have to ``gobble'' this token away.
+% A rude way to do this is by using the macro "\gobblenext" as the last token
+% in you macro which can be defined by
+% \begin{verbatim}
+% \def\gobblenext#1{}\end{verbatim}
+% However, this has two major drawbacks:
+% \begin{enumerate}
+% \item This works for "*", but not for "{" or space tokens.
+% For space tokens the situation is even worse, since \TeX\ eats spaces around
+% arguments, so sometimes space tokens might unexpectedly disappear.
+% \item It is not possible in this way to \emph{read} another argument
+% following the "*": Recall that "\gobblenext" must be the \emph{last} token
+% in your macro expansion, i.e.\ you have ``lost control'' after this call.
+% \end{enumerate}
+% The solution to these problems is instead of calling "\gobblenext" to use
+% \DescribeMacro{\toolboxGobbleNext}"\toolboxGobbleNext" as the last command
+% in your call: You can pass it an argument which describes the action that
+% you want to do \emph{after} gobbling the next token
+% ("*" in the above example) from the token stream. Thus
+% \begin{quote}
+% "\toolboxGobbleNext"\bracemeta{cmd}
+% \end{quote}
+% erases the token following that command from the token stream and
+% then executes \meta{cmd}. This is similar to
+% \begin{verbatim}
+% \def\toolboxGobbleNext#1#2{#1}\end{verbatim}
+% with the difference that "#2" is considered as a token and that no spaces
+% are eaten.\par
+% The effect is that e.g.\ the call
+% \begin{verbatim}
+% \toolboxGobbleNext{\foo}{{arg}\end{verbatim}
+% is the same as "\foo{arg}" (the brace "{" is eaten in this example).\par
+
+% As described earlier, the commands "\futurelet" or "\toolboxFuturelet" can
+% be used to check for optional flags. Frequently you will only want
+% to test for one particular flag and decide the next action on this flag.
+% Of course, you can test the token found with "\ifx...\fi" but this has the
+% disadvantage that some tokens (e.g.\ "\fi") follow your action, which might
+% be bad (recall that e.g.\ "\toolboxGobbleNext" must be the last command of
+% your action, i.e.\ it would in the above examples not gobble the "*" but
+% the "\fi" which is probably not what you want).
+% The simplest solution is to use the command
+% \DescribeMacro{\toolboxIfNextToken}"\toolboxIfNextToken" which already
+% has the test included. For example, to test for an optional "[", you can
+% simply write
+% \begin{verbatim}
+% \def\MacroWithOptionalBrace{\toolboxIfNextToken[{\yes}{\no}}\end{verbatim}
+% and then the call "\MacroWithOptionalBrace[...]" will expand to "\yes[...]"
+% while "\MacroWithOptionalBrace x" will expand to "\no x" (note that the
+% brace is not gobbled---if you want the latter, use "\toolboxIfNextGobbling"
+% described below).\par
+% More precisely, the calling syntax of "\toolboxIfNextToken" is
+% \begin{quote}
+% \DescribeMacro{\toolboxIfNextToken}
+% "\toolboxIfNextToken"\bracemeta{token}\bracemeta{if}\bracemeta{else}
+% \end{quote}
+% The semantic is the following: If the token following this command is
+% \meta{token}, then \meta{if} is executed, otherwise \meta{else}.
+% It is explicitly admissible that \meta{token} is a space.
+% To support further tests, \DescribeMacro{\toolboxToken}"\toolboxToken"
+% is "\let" to the token which follows the command.
+% "\toolboxToken" is only a temporary token,
+% i.e.\ it may also be modified by other commands of this package;
+% in particular, you may also freely modify "\toolboxToken".\par
+% The token "\toolboxSpaceToken" which is described later may be handy
+% in connection with this command.\par
+% In contrast to similar \LaTeXe\ macros
+% much care has been taken that spaces are not eaten. This solves the
+% following problem:\par
+%
+% Assume that you want to write a macro which should have the calling syntax
+% "\mymacro{arg1}" or "\mymacro{arg1}[arg2]". You will probably implement
+% "\mymacro" to read the first argument and then to look whether the next
+% token is a "[". If you use the \LaTeXe\ macro to test for "[",
+% then all spaces until the next non-space token would be gobbled which means
+% that if you would use the \LaTeXe\ macros for the test, then the call
+% "\mymacro{arg1}"\myspace"Text" would behave like "\mymacro{arg1}Text",
+% i.e.\ the space is ``mysteriously'' lost. With the \filecite{toolbox}
+% macros this does not happen. The ``disadvantage'' is that
+% "\mymacro{arg1}"\myspace"[arg2]" is not the same as
+% "\mymacro{arg1}[arg2]" either (which is reasonable IMHO).
+%
+% Example:
+% \begin{verbatim}
+% \def\mycmd#1{\toolboxIfNextToken[{\ParseOpt{#1}}{\NoOpt{#1}}}
+% \def\ParseOpt#1[#2]{\OptAtEnd{#1}{#2}}\end{verbatim}
+% After the above definition, "\mycmd{arg}" executes "\NoOpt{arg}" while
+% "\mycmd{arg}[optional]" executes "\OptAtEnd{arg}{optional}".
+% We point out once more that in the first call a space following
+% "\mycmd{arg}" does not vanish (as would be the case if the \LaTeXe\ macros
+% would have been used).\par
+
+% If "\toolboxIfNextToken" has found the required token, it does \emph{not}
+% gobble that token from the token stream. Of course, you can do this by
+% yourself using the earlier described macro "\toolboxGobbleNext". However,
+% it is simpler to use
+% \begin{quote}
+% \DescribeMacro{\toolboxIfNextGobbling}
+% "\toolboxIfNextGobbling"\bracemeta{token}\bracemeta{if}\bracemeta{else}
+% \end{quote}
+% This command is analogous to "\toolboxIfNextToken" with the difference that
+% in the case that the next token is \meta{token}, it is gobbled before
+% \meta{if} is executed.\par
+%
+% Example:
+% \begin{verbatim}
+% \def\my{\toolboxIfNextGobbling*\toolboxTokenLoop\toolboxLoop}\end{verbatim}
+% This makes "\my*..." behave like "\toolboxTokenLoop..." and
+% "\my..." (without "*") behave like "\toolboxLoop...".\par
+
+% The following macro is one which you may want to use in connection with
+% \LaTeX2e\ optional arguments:
+%
+% \begin{quote}
+% \DescribeMacro{\toolboxIfEmpty}
+% "\toolboxIfEmpty"\bracemeta{arg}\bracemeta{if}\bracemeta{else}
+% \end{quote}
+%
+% \meta{arg} is not expand; it is only used to decide whether \meta{if} or
+% \meta{else} will be expanded.\par
+% For further tests there are more involved macros:
+%
+% \begin{quote}
+% \DescribeMacro{\toolboxIfx}
+% "\toolboxIfx"\bracemeta{arg}"\macro"\bracemeta{if}\bracemeta{else}
+% \end{quote}
+% This tests via "\ifx" whether "\def\Macro"\bracemeta{arg} would give
+% the definition of "\macro".
+%
+% \begin{quote}
+% \DescribeMacro{\toolboxIfX}
+% "\toolboxIfX"\bracemeta{arg 1}\bracemeta{arg 2}\bracemeta{if}\bracemeta{else}
+% \end{quote}
+% This tests whether \meta{arg 1} and \meta{arg 2} are the same token
+% sequences.\par
+%
+% If you want to avoid the "\else" and "\fi" commands to avoid certain side
+% effects, you can use instead:
+%
+% \begin{quote}
+% \DescribeMacro{\toolboxIfElse}
+% "\toolboxIfElse"\bracemeta{ifcmd}\bracemeta{if}\bracemeta{else}
+% \end{quote}
+% This is rather analogous to \meta{ifcmd}\meta{if}"\else"\meta{else}"\fi"
+% but has everything in this line already eliminated from the tokenlist when
+% \meta{if} resp.\ \meta{else} are expanded.
+
+% \subsection{Loops over tokenlists and itemlists}
+%
+% \begin{quote}
+% \DescribeMacro{\toolboxLoop}
+% "\toolboxLoop"\bracemeta{items}\bracemeta{action}
+% \end{quote}
+%
+% This calls iteratively \meta{action}"{#1}", where "#1" runs over each item in
+% \meta{items}. Here, an item is either a token or a group
+% braced by "{...}".
+% In the latter case, the braces are lost. Spaces in \meta{items} are ignored
+% (unless they are braced). It is admissible that \meta{action} is not a single
+% macro but instead a sequence of tokens.\par
+% Examples follow below.\par
+% The counterintuitive order of arguments is explained by the fact that the
+% typical usage is
+% \begin{quote}
+% "\expandafter\toolboxLoop\expandafter{\ExpandingMacro}"\bracemeta{action}
+% \end{quote}
+% which for swapped order of arguments could hardly be written.\par
+%
+% "\toolboxLoop" is not reentrant, i.e.\ \bracemeta{action} may not expand
+% to something which contains a call to "\toolboxLoop". To enable such calls
+% anyway, the command
+% \begin{quote}
+% \DescribeMacro{\toolboxLoopName}
+% "\toolboxLoopName"\bracemeta{name}\bracemeta{items}\bracemeta{action}
+% \end{quote}
+% is provided which is analogous to "\toolboxLoopName". This is also
+% not reentrant, but in contrast to "\toolboxLoop",
+% calls with different \meta{name} can
+% be used independently of each other, i.e.\ in the \bracemeta{action} part
+% of a "\toolboxLoop" (or "\toolboxLoopName") can be a call to
+% "\toolboxLoopName" with a \emph{different} \meta{name} argument.
+% In particular, using a counter in \meta{name}, one could easily implement
+% even recursive calls. In this connection, it should be noted that
+% \meta{name} is expanded via "\csname ... \endcsname", and so you may use
+% constructs like "\the\namecounter" there.\par
+
+% \begin{quote}
+% \DescribeMacro{\toolboxTokenLoop}
+% "\toolboxTokenLoop"\bracemeta{tokens}\bracemeta{action}
+% \end{quote}
+% This is similar to "\toolboxLoop": The command \meta{action}"\toolboxToken"
+% is executed iteratively where "\toolboxToken" runs over each token in
+% \meta{tokens}. The important difference is that "\toolboxToken" is a token
+% (instead of an item). In particular, "\toolboxToken" runs through every
+% single token including spaces and braces.\par
+% The token "\toolboxSpaceToken" which is described later may be handy
+% in connection with this command.\par
+
+% Example:
+% \begin{verbatim}
+% \toolboxTokenLoop{Some text}{\kern0.1em}\end{verbatim}
+% is the similar to "\kern0.1em S\kern0.1em o\kern0.1em m...", i.e.\ you
+% get wider spacing between the letters of "Some text" (I do not claim that
+% this is typographically a good idea).\par
+%
+% Note that you do not have to take special care about the space.
+% With "\toolboxLoop", you would have to mask the space e.g.\ with
+%
+% \begin{verbatim}
+% \toolboxLoop{Some{ }text}{\kern0.1em}\end{verbatim}
+% or
+% \begin{verbatim}
+% \toolboxLoop{Some\toolboxSpace text}{\kern0.1em}\end{verbatim}
+% In contrast, "\toolboxTokenLoop" would behave differently here:
+% \begin{verbatim}
+% \toolboxTokenLoop{Some{ }text}{\kern0.1em}\end{verbatim}
+% would produce "\kern0.1em S...\kern0.1em{\kern0.1em"\myspace"\kern0.1em}..."
+% because the braces are simply considered as tokens.
+
+%
+% "\toolboxTokenLoop" is not reentrant. Analogously to "\toolboxLoopName",
+% independent versions can be generated by
+% \begin{quote}
+% \DescribeMacro{\toolboxTokenName}
+% "\toolboxTokenName"\bracemeta{name}\bracemeta{tokens}\bracemeta{action}
+% \end{quote}
+
+% \subsection{Controlled expansion}
+%
+% There are some occasions when you want more control over the expansion.
+% E.g.\ you might want to concatenate the contents of two macros to a
+% further macro or you want to expand a macro by one level but no full
+% expansion. Usually you can get this effects with "\expandafter", but if
+% you expand several concatenated tokens in this way you either have to
+% write a lot of "\expandafter"s or you have to define subsidiary macros
+% that help you to "\expandafter" certain parts of macros. The macros in
+% this section allow you to do this in the most generic way that I could
+% implement.
+%
+% \begin{quote}
+% \DescribeMacro{\toolboxDef}
+% "\toolboxDef\macrotodefine"\bracemeta{argumentlist}
+% \end{quote}
+%
+% This call is similar to
+% \begin{quote}
+% "\def\macrotodefine"\bracemeta{argumentlist}
+% \end{quote}
+% with two important differences:
+%
+% For "\toolboxDef", \meta{argumentlist} is expanded precisely by one level.
+% \meta{argumentlist} may not contain macros with parameters, and spaces in the
+% highest level are ignored. If you want to force a space on a particular
+% place, use the macro \DescribeMacro{\toolboxSpace}"\toolboxSpace" at this
+% place (which is described later). Contrary to the usual "\def", the
+% symbol "#" is treated as a usual symbol.
+%
+% Example of usage:
+% \begin{verbatim}
+% \toolboxDef\chain{\chain\toolboxSpace\after}\end{verbatim}
+% This modifies the macro "\chain" such that a space and the content of the
+% macro "\after" is appended at the end.
+%
+% \begin{quote}
+% \DescribeMacro{\toolboxAppend}
+% "\toolboxAppend\macrotodefine"\bracemeta{argumentlist}
+% \end{quote}
+% This is equivalent to
+% \begin{quote}
+% "\toolboxDef\macrotodefine{\macrotodefine"\meta{argumentlist}"}"
+% \end{quote}
+% \par
+
+% The macro
+% \begin{quote}
+% \DescribeMacro{\toolboxSurround}
+% "\toolboxSurround"\bracemeta{content before}\bracemeta{content after}"\macro"
+% \end{quote}
+% redefines "\macro" such that \meta{content before} is put at the
+% beginning and \meta{content after} after the definition of "\macro".
+% So this is equivalent to
+% \begin{quote}
+% "\def\macro{"\meta{content before}\meta{old content of \cmdcite{macro}}\relax
+%\meta{content after}"}"
+% \end{quote}
+% It is required that "\macro" is a usual macro without any arguments.
+% If you want to patch more complicated macros, use the \filecite{patch.doc}
+% package instead.
+
+% The order of the arguments may appear strange, but it is convenient if
+% \meta{content before} or \meta{content after} are macros which should be
+% expanded with "\expandafter".
+
+% There is some subsidiary macro used in the implementation of the above
+% macros which might be useful also in some other situations:
+%
+% \begin{quote}
+% \DescribeMacro{\toolboxTokDef}
+% "\toolboxTokDef"\bracemeta{argumentlist}"\macrotodefine"
+% \end{quote}
+% This call is similar to
+% \begin{quote}
+% "\def\macrotodefine"\bracemeta{argumentlist}
+% \end{quote}
+% with the difference that the symbol "#" is stored as such.
+% The order of the arguments has been swapped in order to simplify the
+% application of "\expandafter" to \meta{argumentlist}.
+%
+
+% \subsection{Searching, splitting, and replacing}
+%
+% \begin{quote}
+% \DescribeMacro{\toolboxSplitAt}
+% "\toolboxSplitAt"\bracemeta{argument}\bracemeta{search}\relax
+%"{\beforestring}{\afterstring}"
+% \end{quote}
+%
+% Here, "\beforestring" and "\afterstring" are arbitrary macro names,
+% and \meta{search} and \meta{argument} are any sequences of tokens (which
+% are in the following considered as `strings').
+%
+% This call scans \meta{argument} for the first occurrence of \meta{search}.
+% The macros "\beforestring" and "\afterstring" are defined correspondingly
+% such that "\beforestring" expands to the part before the first occurrence,
+% and "\afterstring" to the part following the first occurrence.
+% If \meta{search} does not occur in \meta{argument}, "\beforestring" is
+% defined to \meta{argument}, and "\afterstring" is "\let" "\undefined".
+%
+% If "\beforestring" or "\afterstring" had already been defined before the
+% call, the previous definition is tacitly overridden.
+% It is explicitly allowed that "\beforestring" and "\afterstring" are the
+% same names. In this case, the result has the meaning of "\afterstring".
+%
+% It is guaranteed that braces "{...}" are \emph{not} lost in \meta{argument}.
+% However, \meta{search} may not contain any braces, and \meta{argument} may
+% contain only matching pairs of braces. Moreover, occurrences of \meta{search}
+% within a pair of braces in \meta{argument} are not recognized.
+%
+% (The order of the arguments has been chosen in order to simplify the
+% use of "\expandafter").
+%
+% There are some restrictions for the strings in search. For example,
+% the symbol "#" is not allowed.
+%
+% In the above call, the arguments may not run over several paragraphs.
+% If you want the latter, you have to use the alternative call
+% \begin{quote}
+% "\toolboxSplitAt*"\bracemeta{argument}\bracemeta{search}\relax
+%"{\beforestring}{\afterstring}"
+% \end{quote}
+
+%
+% Example of usage:
+%
+% \begin{verbatim}
+% \def\examplemacro#1{\toolboxSplitAt{#1}{@}\testme\testme
+% \ifx\testme\undefined
+% ... (do this when #1 contains no `@' token)
+% \fi}\end{verbatim}
+%
+
+% If "\toolboxSplitAt" should be used several times with the same
+% \meta{search} string, it is much more efficient to use the following command:
+%
+% \begin{quote}
+% \DescribeMacro{\toolboxMakeSplit}
+% "\toolboxMakeSplit"\bracemeta{search}"{command}"
+% \end{quote}
+%
+% This call defines a new macro "\command" (the name is determined by the
+% second argument of "\toolboxMakeSplit") which can be called in the form
+%
+% \begin{quote}
+% "\command"\bracemeta{argument}"{\beforestring}{\afterstring}"
+% \end{quote}
+%
+% and which has the analogous meaning as "\SplitAt" (the argument
+% \bracemeta{search} is implicitly fixed and taken from the call of
+% "\toolboxMakeSplit").
+% It is explicitly admissible that the above macro "\toolboxMakeSplit" is
+% used with an already existing command name. In this case, the previous
+% definition of "\command" is tacitly overridden.
+%
+% The command created by "\toolboxMakeSplit" does not accept arguments which
+% run over several paragraphs. If you want the latter, you have to create
+% this command by the alternative call
+%
+% \begin{quote}
+% "\toolboxMakeSplit*"\bracemeta{search}"{command}"
+% \end{quote}
+
+% The command
+% \begin{quote}
+% "\toolboxFreeSplit"\bracemeta{command}
+% \end{quote}
+% frees the memory used by a previous "\toolboxMakeSplit" (and lets "\command"
+% again be undefined).
+
+% The command
+% \begin{quote}
+% \DescribeMacro{\toolboxReplace}
+% "\toolboxReplace"\bracemeta{search}\bracemeta{replace}"\macro"
+% \end{quote}
+% replaces in "\macro" all occurences of \meta{search} by \meta{replace}.
+% The same matches are found as in "\toolboxSplitAt".
+% If you need to search for the same text several times, it is faster
+% to use the command
+% \begin{quote}
+% \DescribeMacro{\toolboxReplaceSplit}
+% "\toolboxReplaceSplit"\bracemeta{replace}"\SplitCmd\macro"
+% \end{quote}
+% where "\SplitCmd" is a command previously generated with "\toolboxMakeSplit*"
+% according to your \meta{search} string. (You could also use
+% "\toolboxMakeSplit" to generate "\SplitCmd", but then "\macro" should not
+% contain any "\par"s).
+
+% \subsection{Redefinition of macros}
+%
+%
+% \begin{quote}
+% \DescribeMacro{\toolboxMakeHarmless}
+% "\toolboxMakeHarmless{\macro}"
+% \end{quote}
+%
+% The above call redefines "\macro" such that it expands to an ASCII text
+% containing the previous definition of "\macro" (i.e.\ the catcodes of
+% "\macro" are changed).
+
+% The call
+% \begin{quote}
+% \DescribeMacro{\toolboxDropBrace}
+% "\toolboxDropBrace{\macro}"
+% \end{quote}
+% drops possible outer braces of "\macro". More precisely,
+% if "\macro" expands to \bracemeta{content}, then "\macro" is redefined
+% to \meta{content} (without braces). Otherwise, nothing happens.
+
+% The command
+% \begin{quote}
+% \DescribeMacro{\toolboxIf}
+% "\toolboxIf"\meta{comparison}\bracemeta{definition commands}\relax
+%\cmdmeta{macro}$\ldots$
+% \end{quote}
+% allows conditional definitions. Here, \bracemeta{definition command}
+% is either "\def", "{\long\def}", "\let", or some similar command like
+% e.g.\ the \LaTeX\ "\newcommand". If the test
+% "\ifx"\meta{comparison}\cmdmeta{macro} evaluates positive, then
+% \cmdmeta{macro} is defined correspondingly. Otherwise, \cmdmeta{macro}
+% is not changed.\par\smallskip
+%
+% \textbf{Examples:}
+%
+% \begin{verbatim}
+% \toolboxIf\undefined\def\macro{....}
+% \toolboxIf\undefined\let\macro...
+% \toolboxIf\undefined{\long\def}\macro{....}
+% \toolboxIf\undefined\newcommand{\macro}{....}\end{verbatim}
+%
+% are similar to "\def\macro{...}" resp.\ "\let\macro..."
+% resp.\ "\long\def\macro{...}" resp.\ "\newcommand{\macro}" with the
+% difference that "\macro" is not changed if it was already defined.
+% In this sense, "\toolboxIf" is a more flexible variant of "\providecommand".
+%
+
+% The commands
+% \begin{quote}
+% \DescribeMacro{\toolboxNewiftrue}
+% "\toolboxNewiftrue"\bracemeta{name}\\
+% \DescribeMacro{\toolboxNewiffalse}
+% "\toolboxNewiffalse"\bracemeta{name}
+% \end{quote}
+% test whether the command "\if"\meta{name} was already introduced with
+% "\newif"; in this case nothing happens. Otherwise, "\if"\meta{name} is
+% introduced similarly to "\newif\if"\meta{name} and set to "true"
+% respectively "false".
+% In contrast to the corresponding command in \TeX\ or \LaTeX 2.09, this macro
+% is not "\outer"!
+% \begin{quote}
+% \DescribeMacro{\toolboxNewifTrue}
+% "\toolboxNewifTrue"\bracemeta{name}\\
+% \DescribeMacro{\toolboxNewifFalse}
+% "\toolboxNewifFalse"\bracemeta{name}
+% \end{quote}
+% are similar to "\toolboxNewiftrue"\bracemeta{name} and
+% "\toolboxNewiffalse"\bracemeta{name}, respectively,
+% with the difference that "\if"\meta{name} is set unconditionally
+% to "true" respectively "false".
+
+% \subsection{Concatenated macro names}
+%
+% \begin{quote}
+% \DescribeMacro{\toolboxLet}
+% "\toolboxLet\variable"\bracemeta{macroname}
+% \end{quote}
+% The above command is analogous to "\let\variable\macroname" with the
+% difference that \meta{macroname} can also contain other tokens like numbers
+% (it is obtained via "\csname"). Some converse to this command is
+%
+% \begin{quote}
+% "\toolboxWithNr"\bracemeta{number}"\command"\bracemeta{macro}
+% \end{quote}
+% which translates into "\command\macronumber" (here, \meta{macro} and
+% \meta{number} are just concatenated and evaluated via "\csname").
+% Examples:
+% \begin{verbatim}
+% \toolboxWithNr 1\let{name}\toolboxEmpty\end{verbatim}
+% This is the same as "\let\name1\toolboxEmpty" (but such that "\name1" is
+% considered as a name, not as "\name 1")
+% \begin{verbatim}
+% \toolboxWithNr {10}\def{name}{Foo}\end{verbatim}
+% This corresponds analogously to "\def\name10{Foo}".
+% \begin{verbatim}
+% \toolboxLet\mymacro{name\the\mycount}\end{verbatim}
+% This is similar to "\let\mymacro\namexx" where "xx" is the content
+% of the counter "\mycount".
+
+% \subsection{Various}
+%
+% The following macros have equivalents in most formats (like \LaTeXe).
+% However, we do not want to rely too much on these formats, so we provide
+% our own definitions.
+% The macro
+% \begin{quote}
+% \DescribeMacro{\toolboxEmpty}"\toolboxEmpty"
+% \end{quote}
+% expands to nothing (usually, this is the same as "\empty").
+% Similarly, the macro
+% \begin{quote}
+% \DescribeMacro{\toolboxSpace}"\toolboxSpace"
+% \end{quote}
+% expands to a space symbol (usually, this is the same as "\space").
+% The token
+% \begin{quote}
+% \DescribeMacro{\toolboxSpaceToken}"\toolboxSpaceToken"
+% \end{quote}
+% is "\let" a space token (usually, this is the same as "\@sptoken").
+% This token is convenient in tests of tokens
+% (because it is hard to get a space there which is not eaten by the
+% \TeX\ parser, although sometimes also constructions like
+% \begin{verbatim}
+% \expandafter\ifx\toolboxSpace\token\end{verbatim}
+% can be used). Also the macros
+% \begin{quote}
+% \DescribeMacro{\toolboxFirstOfTwo}"\toolboxFirstOfTwo"\\
+% \DescribeMacro{\toolboxSecondOfTwo}"\toolboxSecondOfTwo"
+% \end{quote}
+% are provided which read two arguments and return only the first
+% respectively second argument (usually, this is the same as
+% "\@firstoftwo" respectively "\@secondoftwo"). Similarly,
+% \begin{quote}
+% \DescribeMacro{\toolboxGobbleArg}
+% "\toolboxGobbleArg"\bracemeta{argument}
+% \end{quote}
+% just reads its argument and expands to nothing.
+
+% \iffalse
+%</metainfo>
+% \fi
+% \iffalse--------------------------------------------------------------\fi
+% \StopEventually{\PrintChanges}
+% \section{Implementation}
+%
+% \iffalse--------------------------------------------------------------
+%
+%
+%<*package>
+% \fi
+% \begin{macrocode}
+%%
+%% This file was generated by the docstrip utility from toolbox.dtx.
+%% You may distribute this file only together with the source toolbox.dtx
+%% (and if possible with toolbox.ins) and only if these files are unmodified.
+%%
+%% Author:
+%%
+%% M. V\"ath martin@mvath.de
+%%
+
+\ifx\typeout\undefined
+ \def\tbx@tmp{\immediate\write17}\expandafter\tbx@tmp
+\else
+ \expandafter\typeout
+\fi{toolbox.sty by M. Vaeth: The TeX Programmer's Toolbox 5.1}
+
+%% First, some LaTeX support:
+%% We inform LaTeX that this is a package, and we test whether we would
+%% override some existing commands.
+
+\ifx\ProvidesPackage\undefined\else
+ \ProvidesPackage{toolbox}[2004/04/29 v5.1]
+\fi
+
+\ifx\newcommand\undefined\else
+ \newcommand{\toolboxMakeDef}{}
+ \newcommand{\toolboxFreeDef}{}
+ \newcommand{\toolboxFuturelet}{}
+ \newcommand{\toolboxGobbleNext}{}
+ \newcommand{\toolboxIfNextToken}{}
+ \newcommand{\toolboxIfNextGobbling}{}
+ \newcommand{\toolboxIfEmpty}{}
+ \newcommand{\toolboxIfx}{}
+ \newcommand{\toolboxIfX}{}
+ \newcommand{\toolboxIfElse}{}
+ \newcommand{\toolboxLoop}{}
+ \newcommand{\toolboxLoopName}{}
+ \newcommand{\toolboxToken}{}
+ \newcommand{\toolboxTokenName}{}
+ \newcommand{\toolboxTokDef}{}
+ \newcommand{\toolboxDef}{}
+ \newcommand{\toolboxAppend}{}
+ \newcommand{\toolboxSplitAt}{}
+ \newcommand{\toolboxMakeSplit}{}
+ \newcommand{\toolboxFreeSplit}{}
+ \newcommand{\toolboxReplace}{}
+ \newcommand{\toolboxReplaceSplit}{}
+ \newcommand{\toolboxMakeHarmless}{}
+ \newcommand{\toolboxDropBrace}{}
+ \newcommand{\toolboxIf}{}
+ \newcommand{\toolboxNewiftrue}{}
+ \newcommand{\toolboxNewiffalse}{}
+ \newcommand{\toolboxLet}{}
+ \newcommand{\toolboxWithNr}{}
+ \newcommand{\toolboxEmpty}{}
+ \newcommand{\toolboxSpace}{}
+ \newcommand{\toolboxSpaceToken}{}
+ \newcommand{\toolboxFirstOfTwo}{}
+ \newcommand{\toolboxSecondOfTwo}{}
+ \newcommand{\toolboxGobbleArg}{}
+\fi
+
+% \end{macrocode}
+% \subsection{Macros for various purposes}
+% \begin{macro}{\toolboxSpace}\nocomment
+% \begin{macrocode}
+\def\toolboxEmpty{}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\toolboxSpace}\nocomment
+% \begin{macrocode}
+\def\toolboxSpace{ }
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\toolboxSpaceToken}
+% We cannot just write
+% \begin{verbatim*}\let\toolboxSpaceToken= \end{verbatim*}
+% because then the space would be eaten by \TeX's parser.
+% Also tries like
+% \begin{verbatim}
+% \expandafter\let\expandafter\toolboxSpaceToken\toolboxSpace\end{verbatim}
+% do not work for similar reasons. In contrast,
+% \begin{verbatim}
+% \futurelet\toolboxSpaceToken{ }\end{verbatim}
+% is possible (because the space is not `really' parsed at this time),
+% but it would have the side effect that the group "{ }" is executed which
+% forces a space output. We could artificially `eat' this output in some box.
+% But we proceed differently by replacing "{ }" in
+% the above call by an appropriate "\if...\fi". Of course, we have to take
+% care that the space is not eaten too early.
+% \begin{macrocode}
+\expandafter
+ \futurelet\expandafter\toolboxSpaceToken\expandafter
+ \if\toolboxSpace\toolboxEmpty\toolboxEmpty\fi
+
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\toolboxFirstOfTwo}\nocomment
+% \begin{macrocode}
+\long\def\toolboxFirstOfTwo#1#2{#1}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\toolboxSecondOfTwo}\nocomment
+% \begin{macrocode}
+\long\def\toolboxSecondOfTwo#1#2{#2}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\toolboxGobbleArg}
+% \begin{macrocode}
+\long\def\toolboxGobbleArg#1{}
+
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\tbx@toks}
+% We need a temporary token list
+% \begin{macrocode}
+\toksdef\tbx@toks=0
+
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection{Macros supporting implicit macro definitions}
+%
+% \begin{macro}{\toolboxMakeDef}\nocomment
+% \begin{macrocode}
+\def\toolboxMakeDef{\tbx@MakeNames\tbx@MakeDef}
+% \end{macrocode}
+% \begin{macro}{\tbx@MakeDef}
+% The macros for "\toolboxMakeDef" are defined with
+% \begin{quote}
+% "\tbx@MakeDef\PrefixNewName\PrefixRenewName\PrefixProvideName%"\\
+% " \PrefixDefName\PrefixLetName\PrefixName\tbx@e@Prefix@Name%"\\
+% " "\bracemeta{Prefix}\bracemeta{Name}\bracemeta{Replacement Mask}
+% \end{quote}
+% Note that \meta{Replacement Mask} must be read implicitly, because it
+% contains "#1" which is usually forbidden.
+% The macro "\tbx@e@Prefix@Name" is defined as
+% \begin{quote}
+% "\tbx@long\def\tbx@e@Name#1"\bracemeta{Replacement Mask}
+% \end{quote}
+% The macros generated by
+% \begin{quote}
+% "\PrefixNewName"\bracemeta{something}"{"$\ldots$"...}"
+% \end{quote}
+% carry the names
+% \begin{quote}
+% "\tbx@l@"\meta{Prefix}"@"\meta{Name}"@"\meta{something}
+% \end{quote}
+% Observe that the symbol "@" has currently the exceptional letter catcode,
+% so that there is no danger that the user mangles up the names (unless he
+% uses "\makeatletter" which he should of course not do, usually).
+% \makeatletter
+% \begin{macrocode}
+\def\tbx@MakeDef#1#2#3#4#5#6#7#8#9{%
+ \tbx@def#1{\toolboxIfNextGobbling*%
+ {\tbx@MakeNew\let{#8}{#9}}{\tbx@MakeNew\def{#8}{#9}}}%
+ \tbx@def#2{\toolboxIfNextGobbling*%
+ {\tbx@MakeRenew\let{#8}{#9}}{\tbx@MakeRenew\def{#8}{#9}}}%
+ \tbx@def#3{\toolboxIfNextGobbling*%
+ {\tbx@MakeProvide\let{#8}{#9}}{\tbx@MakeProvide\def{#8}{#9}}}%
+ \tbx@def#4{\toolboxIfNextGobbling*%
+ {\tbx@MakeForce\let{#8}{#9}}{\tbx@MakeForce\def{#8}{#9}}}%
+ \tbx@def#5##1##2{\expandafter
+ \tbx@MakeLet\csname tbx@l@#8@#9@##2\endcsname##1}%
+ \tbx@def#6{\toolboxIfNextGobbling*%
+ {\tbx@MakeUse\tbx@itemEnd{#8}{#9}}{\tbx@MakeUse\relax{#8}{#9}}}%
+ \long\def#7##1}
+
+% \end{macrocode}
+% \begin{macro}{\tbx@MakeNew}
+% "\tbx@MakeNew"\bracemeta{mode}\relax
+%\bracemeta{Prefix}\bracemeta{Name}\bracemeta{something}%
+%\bracemeta{text to remember}
+% \begin{macrocode}
+\def\tbx@MakeNew#1#2#3#4{\expandafter
+ \ifx\csname tbx@l@#2@#3@#4\endcsname\relax\else
+ \errmessage{#2New#3: entry #4 already exists}%
+ \fi
+ \tbx@MakeForce{#1}{#2}{#3}{#4}}
+
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\tbx@MakeRenew}
+% "\tbx@MakeRenew"\bracemeta{mode}\relax
+%\bracemeta{Prefix}\bracemeta{Name}\bracemeta{something}%
+%\bracemeta{text to remember}
+% \begin{macrocode}
+\def\tbx@MakeRenew#1#2#3#4{\expandafter
+ \ifx\csname tbx@l@#2@#3@#4\endcsname\relax
+ \errmessage{#2Renew#3: entry #4 was not defined before}%
+ \fi
+ \tbx@MakeForce{#1}{#2}{#3}{#4}}
+
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\tbx@MakeProvide}
+% "\tbx@MakeProvide"\bracemeta{mode}\relax
+%\bracemeta{Prefix}\bracemeta{Name}\bracemeta{something}%
+%\bracemeta{text to remember}
+% \begin{macrocode}
+\def\tbx@MakeProvide#1#2#3#4#5{\expandafter
+ \ifx\csname tbx@l@#2@#3@#4\endcsname\relax
+ \tbx@MakeForce{#1}{#2}{#3}{#4}{#5}%
+ \fi}
+
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\tbx@MakeForce}
+% "\tbx@MakeForce"\bracemeta{mode}\relax
+%\bracemeta{Prefix}\bracemeta{Name}\bracemeta{something}%
+%\bracemeta{text to remember}
+% \begin{macrocode}
+\long\def\tbx@MakeForce#1#2#3#4#5{%
+ \ifx#1\let
+ \expandafter
+ \let\csname tbx@l@#2@#3@#4\endcsname#5%
+ \else
+ \expandafter
+ \tbx@MakeDoDef\csname tbx@l@#2@#3@#4\expandafter\endcsname
+ \csname tbx@e@#2@#3\endcsname{#5}%
+ \fi}
+% \end{macrocode}
+% \begin{macro}{\tbx@MakeDoDef}
+% \begin{quote}
+% "\tbx@MakeDoDef"\relax
+%"\tbx@l@"\meta{Prefix}"@"\meta{Name}"@"\meta{something}"%"\\
+%" \tbx@e@"\meta{Prefix}"@"\meta{Name}\bracemeta{text to remember}
+% \end{quote}
+% \begin{macrocode}
+\long\def\tbx@MakeDoDef#1#2#3{\tbx@toks\expandafter{#2{#3}}%
+ \edef#1{\the\tbx@toks}}
+
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \begin{macro}{\tbx@MakeLet}
+% "\tbx@MakeLet"\cmdmeta{Prefix}"@"\meta{Name}"@"\meta{something}\relax
+%\cmdmeta{something}
+% \begin{macrocode}
+\def\tbx@MakeLet#1#2{%
+ \ifx#1\relax
+ \let#2\undefined
+ \else
+ \let#2#1%
+ \fi}
+
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\tbx@MakeUse}
+% "\tbx@MakeUse"\bracemeta{mode}\relax
+%\bracemeta{Prefix}\bracemeta{Name}\bracemeta{something}
+% \begin{macrocode}
+\def\tbx@MakeUse#1#2#3#4{%
+ \expandafter
+ \ifx\csname tbx@l@#2@#3@#4\endcsname#1%
+ \errmessage{Entry #4 was not defined with
+ #2New#3, #2Provide#3, or #2Def#3}%
+ \fi
+ \csname tbx@l@#2@#3@#4\endcsname}
+
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\tbx@def}
+% "\tbx@def" is similar to "\def", but existence is tested (via "\relax")
+% \begin{macrocode}
+\def\tbx@def#1{%
+ \ifx#1\relax\else
+ \errmessage{\string#1 is already defined}%
+ \fi
+ \def#1}
+
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \begin{macro}{\toolboxFreeDef}\nocomment
+% \begin{macrocode}
+\def\toolboxFreeDef{\toolboxIfNextGobbling*%
+ {\tbx@MakeNames{\tbx@FreeDef\relax}}{\tbx@MakeNames{\tbx@FreeDef\undefined}}}
+% \end{macrocode}
+% \begin{macro}{\tbx@FreeDef}
+% \begin{quote}
+% "\tbx@FreeDef"\bracemeta{mode}"\PrefixNewName\PrefixRenewName%"\\
+% " \PrefixProvideName\PrefixDefName\PrefixLetName\PrefixName"%\\
+% " \tbx@e@Prefix@Name"\bracemeta{Prefix}\bracemeta{Name}
+% \end{quote}
+% The last two arguments are not needed, but we must gobble them.
+% Since a macro can have at most 9 arguments, we must gobble the last one
+% separately.
+% \begin{macrocode}
+\def\tbx@FreeDef#1#2#3#4#5#6#7#8#9{%
+ \let#2\undefined\let#3\undefined\let#4\undefined\let#5\undefined
+ \let#8\undefined
+ \ifx#1\undefined
+ \let#6\undefined\let#7\undefined
+ \fi\toolboxGobbleArg}
+
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \begin{macro}{\tbx@MakeNames}
+% The call
+% \begin{quote}
+% "\tbx@MakeNames"\bracemeta{commands}"["\meta{Prefix}"]"\bracemeta{Name}
+% \end{quote}
+% (where the "["\meta{Prefix}"]" argument is optional) expands to
+% \begin{quote}
+% \meta{commands}"\PrefixNewName\PrefixRenewName\PrefixProvideName%"\\
+% " \PrefixLetName\PrefixName\tbx@e@Prefix@Name%"\\
+% " "\bracemeta{Prefix}\bracemeta{Name}
+% \end{quote}
+% \begin{macrocode}
+\def\tbx@MakeNames#1{\toolboxIfNextToken[%]
+ {\tbx@MakingNames{#1}}{\tbx@MakingNames{#1}[]}}
+% \end{macrocode}
+% \begin{macro}{\tbx@MakingNames}
+% \begin{macrocode}
+\def\tbx@MakingNames#1[#2]#3{\expandafter
+ \tbx@ListSwap\expandafter{%
+ \csname#2New#3\expandafter\endcsname
+ \csname#2Renew#3\expandafter\endcsname
+ \csname#2Provide#3\expandafter\endcsname
+ \csname#2Def#3\expandafter\endcsname
+ \csname#2Let#3\expandafter\endcsname
+ \csname#2#3\expandafter\endcsname
+ \csname tbx@e@#2@#3\endcsname{#2}{#3}}{#1}}
+% \end{macrocode}
+% \begin{macro}{\tbx@ListSwap}\nocomment
+% \begin{macrocode}
+\def\tbx@ListSwap#1#2{#2#1}
+
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \subsection{Macros supporting fancy optional argument parsing}
+%
+% \begin{macro}{\toolboxFuturelet}
+% \begin{macrocode}
+\long\def\toolboxFuturelet#1#2{\toolboxTokDef{#2}\tbx@tmp\futurelet#1\tbx@tmp}
+
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\toolboxGobbleNext}
+% \begin{macrocode}
+\long\def\toolboxGobbleNext#1{\toolboxTokDef{#1}\tbx@tmp
+ \afterassignment\tbx@tmp
+ \let\toolboxToken= }% The space here is important to read spaces properly
+
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\toolboxIfNextToken}
+% \begin{macrocode}
+\long\def\toolboxIfNextToken#1#2#3{%
+ \toolboxFuturelet\toolboxToken{%
+ \ifx#1\toolboxToken
+ \expandafter\toolboxFirstOfTwo
+ \else
+ \expandafter\toolboxSecondOfTwo
+ \fi{#2}{#3}}}
+
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\toolboxIfNextGobbling}
+% \begin{macrocode}
+\long\def\toolboxIfNextGobbling#1#2#3{%
+ \toolboxIfNextToken{#1}{\toolboxGobbleNext{#2}}{#3}}
+
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection{Macros supporting loops over tokenlists and itemlists}
+%
+% \begin{macro}{\toolboxLoop}
+% "\toolboxLoop" just calls "\tbx@item" with the magic names
+% "\tbx@i" and "\tbx@I".
+% \begin{macrocode}
+\long\def\toolboxLoop#1#2{\tbx@item\tbx@i\tbx@I{#1}{#2}}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\toolboxLoopName}
+% "\toolboxLoopName" calls "\tbx@item" with the magic names "\tbx@i@#1"
+% and "\tbx@I#@1"
+% \begin{macrocode}
+\long\def\toolboxLoopName#1#2#3{\tbx@LoopName{#1}iI\tbx@item{#2}{#3}}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\tbx@LoopName}
+% \begin{verbatim}
+% \tbx@LoopName{name}{x}{y}{\exec}\end{verbatim}
+% is equivalent to
+% \begin{verbatim}
+% \exec\tbx@x@name\tbx@y@name\end{verbatim}
+% \begin{macrocode}
+\def\tbx@LoopName#1#2#3#4{%
+ \expandafter#4\csname tbx@#2@#1\expandafter\endcsname
+ \csname tbx@#3@#1\endcsname}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\tbx@item}
+% The call
+% \begin{quote}
+% "\tbx@item{\MagicNameA}{\MagicNameB}"\bracemeta{items}\bracemeta{action}
+% \end{quote}
+% is the essential part of "\toolboxLoop". It has the same semantic with
+% the only difference that the names "\MagicNameA" and "\MagicNameB" are used
+% as temporary macros (they are the reason why "\tbx@item" is not reentrant).
+% \begin{macrocode}
+\long\def\tbx@item#1#2#3#4{%
+ \long\def#1##1{%
+ \toolboxTokDef{##1}\toolboxToken
+ \ifx\toolboxToken\tbx@itemEnd
+ \def#2{\let#1\undefined\let#2\undefined}%
+ \else
+ #4{##1}%
+ \fi
+ #2}%
+ \let#2#1%
+ #1#3\tbx@itemEnd}
+% \end{macrocode}
+% \begin{macro}{\tbx@itemEnd}
+% "\tbx@itemEnd" is the magic token used to mark the end of the list in
+% "\tbx@item".
+% Of course, we could also use any other macro instead, but this is unique,
+% even if we compare with "\ifx". Moreover, we want a short macro to
+% avoid unnecessary redundancy in comparing with "\ifx".
+% It appears not necessary to make this token change in recursions, because
+% in each expansion of a list, the newest item will automatically be the
+% earliest.
+% \begin{macrocode}
+\def\tbx@itemEnd{\tbx@itemEnd}
+
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\toolboxTokenLoop}
+% "\toolboxTokenLoop" just calls "\tbx@token" with the magic names
+% "\tbx@t" and "\tbx@T".
+% \begin{macrocode}
+\long\def\toolboxTokenLoop#1#2{\tbx@token\tbx@t\tbx@T{#1}{#2}}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\toolboxTokenLoopName}
+% "\toolboxTokenLoopName" calls "\tbx@token" with the magic names "\tbx@t@#1"
+% and "\tbx@T#@1"
+% \begin{macrocode}
+\long\def\toolboxTokenLoopName#1#2#3{\tbx@LoopName{#1}tT\tbx@token{#2}{#3}}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\tbx@token}
+% The call
+% \begin{quote}
+% "\tbx@token{\MagicNameA}{\MagicNameB}"\bracemeta{items}\bracemeta{action}
+% \end{quote}
+% is the essential part of "\toolboxTokenLoop". It has the same semantic with
+% the only difference that the names "\MagicNameA" and "\MagicNameB" are used
+% as temporary macros (they are the reason why "\tbx@token" is not reentrant).
+% \begin{macrocode}
+\long\def\tbx@token#1#2#3#4{%
+ \def#1{%
+ \ifx\toolboxToken\tbx@tokenEnd
+ \def#2{\let#1\undefined\let#2\undefined}%
+ \else
+ #4\toolboxToken
+ \fi
+ #2}%
+ \def#2{\afterassignment#1\let\toolboxToken= }%
+ #2#3\tbx@tokenEnd}
+% \end{macrocode}
+% \begin{macro}{\tbx@tokenEnd}
+% "\tbx@tokenEnd" is the magic token used to mark the end of the list
+% for "\tbx@token".
+% The same remarks as for "\tbx@itemEnd" hold. However, it is not clear
+% whether we could just use "\tbx@itemEnd" instead, because the scan rules
+% for "\tbx@token" and "\tbx@item" are somewhat different, and thus it is
+% not immediately clear whether in some fancy situations such lists (if
+% called cross-wise) could overlap: I found no example, but I also did not
+% put too much effort in finding one. In any case, we are on the sure side,
+% if we just use a different token.
+% \begin{macrocode}
+\def\tbx@tokenEnd{\tbx@tokenEnd}
+
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\toolboxIfEmpty}
+% \begin{macrocode}
+\long\def\toolboxIfEmpty#1{\toolboxIfx{#1}\toolboxEmpty}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\toolboxIfX}
+% \begin{macrocode}
+\long\def\toolboxIfX#1#2{\toolboxTokDef{#1}\tbx@ifx\toolboxIfx{#2}\tbx@ifx}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\toolboxIfx}
+% \begin{macrocode}
+\long\def\toolboxIfx#1#2{\toolboxTokDef{#1}\tbx@tmp
+ \toolboxIfElse{\ifx\tbx@tmp#2}}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\toolboxIfElse}
+% \begin{macrocode}
+\long\def\toolboxIfElse#1{#1\expandafter
+ \toolboxFirstOfTwo\else\expandafter\toolboxSecondOfTwo\fi}
+
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \subsection{Macros supporting controlled expansion}
+%
+% \begin{macro}{\toolboxTokDef}\nocomment
+% \begin{macrocode}
+\long\def\toolboxTokDef#1#2{\tbx@toks{#1}\edef#2{\the\tbx@toks}}
+
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\toolboxDef}
+% This is mainly a call of "\toolboxLoopName". It is slightly faster if we
+% call "\tbx@item" immediately (and then we can also give magic names which do
+% not clash with any other names). Also for time and memory reasons, we always
+% assume that the temporary variable
+% \begin{macro}{\tbx@odeftmp}
+% "\tbx@odeftmp"
+% \end{macro}
+% is "\toolboxEmpty" at the beginning; we reset it to "\toolboxEmpty" at
+% the end (so that the memory is freed).
+% \begin{macrocode}
+\def\toolboxDef#1#2{%
+ \tbx@item\tbx@odefa\tbx@odefb{#2}\tbx@odef
+ \let#1\tbx@odeftmp\let\tbx@odeftmp\toolboxEmpty}
+\let\tbx@odeftmp\toolboxEmpty
+% \end{macrocode}
+% \begin{macro}{\tbx@odef}
+% \begin{macrocode}
+\long\def\tbx@odef#1{\expandafter\tbx@odefapp\expandafter{#1}}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\tbx@odefapp}
+% "\tbx@odefapp" appends its argument to "\tbx@odeftmp".
+% \begin{macrocode}
+\long\def\tbx@odefapp#1{\tbx@toks\expandafter{\tbx@odeftmp#1}%
+ \edef\tbx@odeftmp{\the\tbx@toks}}
+
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\toolboxAppend}\nocomment
+% \begin{macrocode}
+\def\toolboxAppend#1#2{\toolboxDef#1{#1#2}}
+
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\toolboxSurround}\nocomment
+% \begin{macrocode}
+\long\def\toolboxSurround#1#2#3{\tbx@toks{#1}%
+ \tbx@toks\expandafter{\the\expandafter\tbx@toks#3#2}%
+ \edef#3{\the\tbx@toks}}
+
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \subsection{Macros supporting searching, splitting, and replacing}
+%
+% \begin{macro}{\toolboxMakeSplit}\nocomment
+% \begin{macrocode}
+\def\toolboxMakeSplit{%
+ \toolboxIfNextGobbling*\tbx@MakeLong\tbx@MakeShort}
+% \end{macrocode}
+%
+% \begin{macro}{\tbx@Makelong}
+% \begin{quote}
+% "\tbx@Makelong"\bracemeta{search}"{cmd}"
+% \end{quote}
+% is the same as
+% \begin{quote}
+% "\tbx@DoSplitInstance{\cmd}{\tbx@cmd@spt}{\tbx@cmd@rst}"
+%\bracemeta{search}"\long"
+% \end{quote}
+% \begin{macrocode}
+\long\def\tbx@MakeLong#1#2{%
+ \tbx@SplitNames{#2}%
+ \expandafter
+ \tbx@DoSplitInstance\tbx@splt{#1}\long}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\tbx@MakeShort}
+% "\tbx@Makeshort" is essentially the same as "\tbx@Makelong" (just that
+% "\long" is missing, of course). We could have used the same macro with
+% an additional argument, but it is more convenient for the user if this
+% macro itself is not "\long" so that new paragraphs in the passed search
+% string already give an error: It makes no sense to look for new paragraphs
+% in texts which may not contain new paragraphs.
+% \begin{macrocode}
+\def\tbx@MakeShort#1#2{%
+ \tbx@SplitNames{#2}%
+ \expandafter
+ \tbx@DoSplitInstance\tbx@splt{#1}{}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\tbx@SplitNames}
+% The call "\tbx@SplitNames{cmd}" is equivalent to
+% \begin{verbatim}
+% \def\tbx@splt{\cmd \tbx@cmd@spt \tbx@cmd@rst}\end{verbatim}
+% \begin{macrocode}
+\def\tbx@SplitNames#1{%
+ \expandafter
+ \def\expandafter\tbx@splt\expandafter{\csname#1\expandafter\endcsname
+ \csname tbx@#1@spt\expandafter\endcsname
+ \csname tbx@#1@rst\endcsname}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\tbx@DoSplitInstance}
+% The call
+% \begin{quote}
+% "\tbx@DoSplitInstance{\cmd}{\tbx@cmd@spt}{\tbx@cmd@rst}"\bracemeta{search}
+%\bracemeta{long}
+% \end{quote}
+% creates the instance "\cmd" which splits its argument at
+% \bracemeta{search} (also "\tbx@cmd@spt" and "\tbx@cmd@rst" are created
+% which are needed for "\cmd" to work). The argument \meta{long} must be
+% either "\long" or empty, depending whether long definitions are desired.\par
+% The difficulty in the definition of "\cmd" is to ensure that "{xxx}|{yyy}"
+% splits into "{xxx}" and "{yyy}" \emph{with} braces (i.e., we have to
+% find out whether there are braces which are eliminated by \TeX\ as
+% `argument braces'). Actually, this problem occurs only for the part "{yyy}".
+% We solve it by appending an "a" to \meta{argument}, i.e., we actually
+% split the string "{xxx}|{yyy}a". Of course, we have to eliminate the
+% trailing "a" at the end.
+% \begin{macrocode}
+\long\def\tbx@DoSplitInstance#1#2#3#4#5{%
+ #5\def#1##1##2##3{%
+ #2##2##3\toolboxEmpty##1#4#4@tbx@spt%
+ \ifx##3\toolboxEmpty
+ \let##3\undefined
+ \else
+ #3##3##1a@tbx@rst%
+ \fi
+ }%
+ #5\def#2##1##2##3#4##4#4##5@tbx@spt{\expandafter
+ \toolboxTokDef\expandafter{##3}##1\toolboxTokDef{##5}##2}%
+ #5\def#3##1##2#4##3@tbx@rst{\tbx@rememberlasta##3@tbx@dropa%
+ \tbx@defwithoutlasta##1##3@tbx@dropa}}
+% \end{macrocode}
+% \begin{macro}{\tbx@rememberlasta}
+% The call
+% \begin{quote}
+% "\tbx@rememberlasta"\meta{arg}"@tbx@dropa"
+% \end{quote}
+% (no braces: The magic string "@tbx@dropa" is used to find the end of
+% \meta{arg}) is only admissible, if the last token in \meta{arg} is an "a".
+% In this case, \DescribeMacro{\tbx@droplasta}"\tbx@droplasta" is
+% defined as \meta{arg} without the trailing "a" (but it may happen that
+% \meta{arg} looses surrounding braces), and the corresponding string with the
+% trailing "a" (possibly without surrounding braces) is saved into
+% \DescribeMacro{\tbx@rebuilda}"\tbx@rebuilda".
+% This macro is used by the instances created
+% by "\tbx@DoSplitInstance".
+% \begin{macrocode}
+\long\def\tbx@rememberlasta#1a@tbx@dropa{\toolboxTokDef{#1}\tbx@droplasta
+ \toolboxTokDef{#1a}\tbx@rebuilda}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\tbx@defwithoutlasta}
+% The call
+% \begin{quote}
+% "\tbx@defwithoutlasta{\afterstring}"\meta{arg}"@tbx@dropa"
+% \end{quote}
+% (no braces: The magic string "@tbx@dropa" is used to find the end of
+% \meta{arg}) is only admissible, if the last token in \meta{arg} is an "a".
+% If \meta{arg} coincides with "\tbx@rebuilda",
+% then we know that we did not loose any braces, and we set "\afterstring"
+% to the content of "\tbx@droplasta"; otherwise we lost braces and thus
+% have additionally to surround the content of "\afterstring" by braces.
+% \begin{macrocode}
+\long\def\tbx@defwithoutlasta#1#2@tbx@dropa{\toolboxTokDef{#2}\tbx@originala
+ \ifx\tbx@originala\tbx@rebuilda
+% \end{macrocode}
+% Did we forget braces in "\tbx@rememberlasta"?
+% \begin{macrocode}
+ \let#1\tbx@droplasta
+ \else
+ \expandafter\toolboxTokDef\expandafter{\expandafter{\tbx@droplasta}}#1%
+ \fi}
+
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \begin{macro}{\toolboxFreeSplit}\nocomment
+% \begin{macrocode}
+\def\toolboxFreeSplit#1{%
+ \tbx@SplitNames{#1}%
+ \expandafter
+ \toolboxLoop\expandafter{\tbx@splt}\tbx@freeSplit}
+% \end{macrocode}
+% \begin{macro}{\tbx@freeSplit}\nocomment
+% \begin{macrocode}
+\def\tbx@freeSplit#1{\let#1\undefined}
+
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \begin{macro}{\toolboxSplitAt}
+% "\toolboxSplitAt" just calls "tbx@DoSplitInstance" with dummy temporary
+% variables and then executes the corresponding command.
+% \begin{macrocode}
+\def\toolboxSplitAt{\toolboxIfNextGobbling*\tbx@SplitLong\tbx@SplitShort}
+% \end{macrocode}
+% \begin{macro}{\tbx@SplitLong}\nocomment
+% \begin{macrocode}
+\long\def\tbx@SplitLong#1#2#3#4{%
+ \tbx@DoSplitInstance\tbx@splt\tbx@splta\tbx@spltb{#2}\long
+ \tbx@splt{#1}{#3}{#4}}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\tbx@SplitShort}
+% We cannot use just an additional argument in "\tbx@SplitLong", because
+% we really should use a non-"\long" macro to read the arguments.
+% \begin{macrocode}
+\def\tbx@SplitShort#1#2#3#4{%
+ \tbx@DoSplitInstance\tbx@splt\tbx@splta\tbx@spltb{#2}{}%
+ \tbx@splt{#1}{#3}{#4}}
+
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\toolboxReplaceSplit}
+% "\toolboxReplaceSplit"\bracemeta{replace}"\SplitCmd\macro"
+% \begin{macrocode}
+\long\def\toolboxReplaceSplit#1#2#3{%
+ \toolboxTokDef{#1}\tbx@reptext
+ \expandafter
+ \tbx@replace\expandafter{#3}{\let#3\toolboxEmpty}#3#2\tbx@reptext}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\tbx@replace}
+% "\tbx@replace\bracemeta{text}\bracemeta{first}\macro\SplitCmd\Reptext"
+% First executes \meta{first}.
+% Then appends to "\macro" the content of \bracemeta{text} with the matches
+% of "\SplitCmd" replaced by the content of "\Reptext".
+% \begin{macrocode}
+\long\def\tbx@replace#1#2#3#4#5{#2%
+ #4{#1}\tbx@repla\tbx@replb
+ \toolboxIfElse{\ifx\tbx@replb\undefined}%
+ {\toolboxDef#3{#3\tbx@repla}}%
+ {\toolboxDef#3{#3\tbx@repla#5}%
+ \expandafter\tbx@replace\expandafter{\tbx@replb}{}#3#4#5}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\toolboxReplace}
+% "\toolboxReplace"\bracemeta{search}\bracemeta{replace}"\macro"
+% just calls "tbx@DoSplitInstance" with dummy temporary variables
+% and then executes "\toolboxReplaceSplit".
+% \begin{macrocode}
+\long\def\toolboxReplace#1#2{%
+ \tbx@DoSplitInstance\tbx@splt\tbx@splta\tbx@spltb{#1}\long
+ \toolboxReplaceSplit{#2}\tbx@splt}
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection{Macros supporting redefinition of macros}
+%
+% \begin{macro}{\toolboxMakeHarmless}\nocomment
+% \begin{macrocode}
+\def\toolboxMakeHarmless#1{\edef#1{\tbx@Nearverbatim#1}}
+% \end{macrocode}
+% \begin{macro}{\tbx@Nearverbatim}\nocomment
+% \begin{macrocode}
+\def\tbx@Nearverbatim{\expandafter\tbx@Meaning\meaning}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\tbx@Meaning}\nocomment
+% \begin{macrocode}
+\long\def\tbx@Meaning#1>{}
+
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\toolboxDropBrace}\nocomment
+% \begin{macrocode}
+\def\toolboxDropBrace#1{\expandafter\tbx@ForgetBrace#1@tbx@dropbrace#1}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\tbx@ForgetBrace}\nocomment
+% \begin{macrocode}
+\long\def\tbx@ForgetBrace#1@tbx@dropbrace#2{\toolboxTokDef{#1}#2}
+
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\toolboxIf}\nocomment
+% \begin{macrocode}
+\long\def\toolboxIf#1#2#3{%
+ \ifx#1#3\def\tbx@tmp{#2#3}\else\def\tbx@tmp{#2\tbx@tmp}\fi\tbx@tmp}
+
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\toolboxNewiftrue}\nocomment
+% \begin{macrocode}
+\def\toolboxNewiftrue#1{\tbx@newifexec{#1}{\csname#1true\endcsname}}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\toolboxNewiffalse}\nocomment
+% \begin{macrocode}
+\def\toolboxNewiffalse#1{\tbx@newifexec{#1}{\csname#1false\endcsname}}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\toolboxNewiftrue}\nocomment
+% \begin{macrocode}
+\def\toolboxNewifTrue#1{\tbx@newifexec{#1}{}\csname#1true\endcsname}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\toolboxNewiffalse}\nocomment
+% \begin{macrocode}
+\def\toolboxNewifFalse#1{\tbx@newifexec{#1}{}\csname#1false\endcsname}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\tbx@newifexec}
+% \begin{quote}
+% "\tbx@newifexec"\bracemeta{name}\bracemeta{initialization}
+% \end{quote}
+% If the command "\if"\meta{name} already exists, nothing happens.
+% Otherwise, the commands \cmdmeta{name}"true" and \cmdmeta{name}"false" are
+% created (similarly as by the \TeX\ command "\newif"), and afterwards
+% \meta{initialization} is executed. Here, \meta{initialization} should be
+% either \cmdmeta{name}"true" or \cmdmeta{name}"false"
+% which then defines "\if"\meta{name} to the desired default.
+% (It may also be empty if you do this initialization immediately afterwards).
+% \meta{initialization} should not contain any potential "\if" tokens.\par
+% One must be very careful in the implementation of this macro,
+% because "\if"'s are parsed very strange by \TeX.
+% However, if an "\if"-command is the first token following our only "\ifx",
+% we do not run into problems. Moreover, the first parsing until "\fi" does
+% not see any further "\if", because it is hidden in "\csname" which has not
+% been expanded by this time.
+% \begin{macrocode}
+\def\tbx@newifexec#1#2{\expandafter
+ \ifx\csname if#1\endcsname\relax
+ \expandafter\tbx@newif\csname if#1\endcsname{#1}%
+ #2%
+ \fi}
+% \end{macrocode}
+% \begin{macro}{\tbx@newif}
+% It is rather annoying that D.~E. Knuth has introduced the "\outer"
+% directive:
+% The sole purpose of that command is to cause problems and to force people
+% to think how to get around these problems. It is especially irritating that
+% the standard command "\newif" was (before \LaTeXe) defined with this
+% attribute. To work in a normal way, we have to define "\newif" by hand
+% in a sane way. It is simpler for us, if we do not only pass the name as a
+% single token but additionally also the full name without "if".
+% So our simpler "\newif" macro is called as follows:
+% \begin{quote}
+% "\tbx@newif"\cmdmeta{ifname}\bracemeta{name}
+% \end{quote}
+% This macro does \emph{not} define \cmdmeta{ifname}. But gets automatically
+% defined after the first call of \cmdmeta{name}"true" or
+% \cmdmeta{name}"false" which should of course happen immediately afterwards.
+% \begin{macrocode}
+\def\tbx@newif#1#2{%
+ \expandafter
+ \def\csname#2true\endcsname{\let#1\iftrue}%
+ \expandafter
+ \def\csname#2false\endcsname{\let#1\iffalse}}
+
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \subsection{Macros supporting concatenated macro names}
+%
+% \begin{macro}{\toolboxWithNr}\nocomment
+% \begin{macrocode}
+\def\toolboxWithNr#1#2#3{\expandafter#2\csname #3#1\endcsname}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\toolboxLet}\nocomment
+% \begin{macrocode}
+\def\toolboxLet#1#2{\expandafter\let\expandafter#1\csname #2\endcsname}
+
+% \end{macrocode}
+% \end{macro}
+%
+% \iffalse
+%</package>
+% \fi
+% \Finale\PrintIndex
+%
+%
+%
+% \iffalse
+%<*metainfo>
+% \fi
+\iffalse -------------------------------------------------------------
+%
+% Just in case that for some reason the file `toolbox.ins' got lost:
+% The content of this file is between the lines %<*insfile> and %</insfile>.
+%
+%\iffalse
+%</metainfo>
+%<*insfile>
+\def\batchfile{toolbox.ins}
+\input docstrip.tex
+\keepsilent
+\nopreamble
+\generateFile{toolbox.sty}{f}{\from{toolbox.dtx}{package}}
+\generateFile{toolbox.txt}{f}{\from{toolbox.dtx}{asciidocu}}
+\generateFile{toolbox.tex}{f}{\from{toolbox.dtx}{driver}}
+%%\generateFile{toolbox.ins.dup}{f}{\from{toolbox.dtx}{insfile}}
+
+\Msg{***************************************************************}
+\Msg{*}
+\Msg{* To finish the installation you have to move the}
+\Msg{* file 'toolbox.sty' into a directory searched by TeX.}
+\Msg{*}
+\Msg{*}
+\Msg{* Run the file toolbox.tex through LaTeX to produce the}
+\Msg{* documentation or read the ascii documentation in toolbox.txt}
+\Msg{*}
+\Msg{*}
+\Msg{***************************************************************}
+\endbatchfile
+%</insfile>
+%<*metainfo>
+% \fi
+\fi
+% \iffalse
+%</metainfo>
+% \fi
+\endinput
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: "toolbox.tex"
+%%% End:
diff --git a/macros/latex/contrib/toolbox/toolbox.ins b/macros/latex/contrib/toolbox/toolbox.ins
new file mode 100644
index 0000000000..9032400b2a
--- /dev/null
+++ b/macros/latex/contrib/toolbox/toolbox.ins
@@ -0,0 +1,22 @@
+\def\batchfile{toolbox.ins}
+\input docstrip.tex
+\keepsilent
+\nopreamble
+\generateFile{toolbox.sty}{f}{\from{toolbox.dtx}{package}}
+\generateFile{toolbox.txt}{f}{\from{toolbox.dtx}{asciidocu}}
+\generateFile{toolbox.tex}{f}{\from{toolbox.dtx}{driver}}
+%%\generateFile{toolbox.ins.dup}{f}{\from{toolbox.dtx}{insfile}}
+
+\Msg{***************************************************************}
+\Msg{*}
+\Msg{* To finish the installation you have to move the}
+\Msg{* file 'toolbox.sty' into a directory searched by TeX.}
+\Msg{*}
+\Msg{*}
+\Msg{* Run the file toolbox.tex through LaTeX to produce the}
+\Msg{* documentation or read the ascii documentation in toolbox.txt}
+\Msg{*}
+\Msg{*}
+\Msg{***************************************************************}
+\endbatchfile
+%</insfile>
diff --git a/macros/latex/contrib/toolbox/toolbox.pdf b/macros/latex/contrib/toolbox/toolbox.pdf
new file mode 100644
index 0000000000..344b64507f
--- /dev/null
+++ b/macros/latex/contrib/toolbox/toolbox.pdf
Binary files differ