path: root/Master/texmf-dist/doc/latex/toolbox/toolbox.txt

%%#
%%# 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.
%%#


%%# 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.

\endinput
%%
%% End of file `toolbox.txt'.