path: root/Master/texmf-dist/source/latex/toolbox/toolbox.dtx

% \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: