diff options
| -rw-r--r-- | Master/texmf-dist/source/latex/toolbox/toolbox.dtx | 2859 | ||||
| -rw-r--r-- | Master/texmf-dist/source/latex/toolbox/toolbox.ins | 22 |
2 files changed, 2881 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/toolbox/toolbox.dtx b/Master/texmf-dist/source/latex/toolbox/toolbox.dtx new file mode 100644 index 00000000000..6d7bd8ee20c --- /dev/null +++ b/Master/texmf-dist/source/latex/toolbox/toolbox.dtx @@ -0,0 +1,2859 @@ +% \def\fileversion{5.1}\def\filedate{2004/04/29}\def\docdate{2004/04/29} +%\iffalse These lines are necessary for the doc and docstrip utilities +%<*asciidocu> + +%%# +%%# Author: +%%# +%%# M. V\"ath vaeth@mathematik.uni-wuerzburg.de +%%# +%%# The author thanks +%%# David Kastrup <David.Kastrup@neuroinformatik.ruhr-uni-bochum.de> +%%# + +%%############################################################################# +%%# +%%# 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}{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 file has version number \fileversion{}, last revised \filedate.}} +% \author{Martin V\"ath\relax +%\thanks{\texttt{vaeth@mathematik.uni-wuerzburg.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 vaeth@mathematik.uni-wuerzburg.de +%% + +\ifx\typeout\undefined + \def\tbx@tmp{\immediate\write17}\expandafter\tbx@tmp +\else + \expandafter\typeout +\fi{toolbox.sty by M. Vaeth: The TeX Programmer's Toolbox 5.1} + +%% First, some LaTeX support: +%% We inform LaTeX that this is a package, and we test whether we would +%% override some existing commands. + +\ifx\ProvidesPackage\undefined\else + \ProvidesPackage{toolbox}[2004/04/29 v5.1] +\fi + +\ifx\newcommand\undefined\else + \newcommand{\toolboxMakeDef}{} + \newcommand{\toolboxFreeDef}{} + \newcommand{\toolboxFuturelet}{} + \newcommand{\toolboxGobbleNext}{} + \newcommand{\toolboxIfNextToken}{} + \newcommand{\toolboxIfNextGobbling}{} + \newcommand{\toolboxIfEmpty}{} + \newcommand{\toolboxIfx}{} + \newcommand{\toolboxIfX}{} + \newcommand{\toolboxIfElse}{} + \newcommand{\toolboxLoop}{} + \newcommand{\toolboxLoopName}{} + \newcommand{\toolboxToken}{} + \newcommand{\toolboxTokenName}{} + \newcommand{\toolboxTokDef}{} + \newcommand{\toolboxDef}{} + \newcommand{\toolboxAppend}{} + \newcommand{\toolboxSplitAt}{} + \newcommand{\toolboxMakeSplit}{} + \newcommand{\toolboxFreeSplit}{} + \newcommand{\toolboxReplace}{} + \newcommand{\toolboxReplaceSplit}{} + \newcommand{\toolboxMakeHarmless}{} + \newcommand{\toolboxDropBrace}{} + \newcommand{\toolboxIf}{} + \newcommand{\toolboxNewiftrue}{} + \newcommand{\toolboxNewiffalse}{} + \newcommand{\toolboxLet}{} + \newcommand{\toolboxWithNr}{} + \newcommand{\toolboxEmpty}{} + \newcommand{\toolboxSpace}{} + \newcommand{\toolboxSpaceToken}{} + \newcommand{\toolboxFirstOfTwo}{} + \newcommand{\toolboxSecondOfTwo}{} + \newcommand{\toolboxGobbleArg}{} +\fi + +% \end{macrocode} +% \subsection{Macros for various purposes} +% \begin{macro}{\toolboxSpace}\nocomment +% \begin{macrocode} +\def\toolboxEmpty{} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\toolboxSpace}\nocomment +% \begin{macrocode} +\def\toolboxSpace{ } +% \end{macrocode} +% \end{macro} +% \begin{macro}{\toolboxSpaceToken} +% We cannot just write +% \begin{verbatim*}\let\toolboxSpaceToken= \end{verbatim*} +% because then the space would be eaten by \TeX's parser. +% Also tries like +% \begin{verbatim} +% \expandafter\let\expandafter\toolboxSpaceToken\toolboxSpace\end{verbatim} +% do not work for similar reasons. In contrast, +% \begin{verbatim} +% \futurelet\toolboxSpaceToken{ }\end{verbatim} +% is possible (because the space is not `really' parsed at this time), +% but it would have the side effect that the group "{ }" is executed which +% forces a space output. We could artificially `eat' this output in some box. +% But we proceed differently by replacing "{ }" in +% the above call by an appropriate "\if...\fi". Of course, we have to take +% care that the space is not eaten too early. +% \begin{macrocode} +\expandafter + \futurelet\expandafter\toolboxSpaceToken\expandafter + \if\toolboxSpace\toolboxEmpty\toolboxEmpty\fi + +% \end{macrocode} +% \end{macro} +% \begin{macro}{\toolboxFirstOfTwo}\nocomment +% \begin{macrocode} +\long\def\toolboxFirstOfTwo#1#2{#1} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\toolboxSecondOfTwo}\nocomment +% \begin{macrocode} +\long\def\toolboxSecondOfTwo#1#2{#2} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\toolboxGobbleArg} +% \begin{macrocode} +\long\def\toolboxGobbleArg#1{} + +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\tbx@toks} +% We need a temporary token list +% \begin{macrocode} +\toksdef\tbx@toks=0 + +% \end{macrocode} +% \end{macro} +% +% \subsection{Macros supporting implicit macro definitions} +% +% \begin{macro}{\toolboxMakeDef}\nocomment +% \begin{macrocode} +\def\toolboxMakeDef{\tbx@MakeNames\tbx@MakeDef} +% \end{macrocode} +% \begin{macro}{\tbx@MakeDef} +% The macros for "\toolboxMakeDef" are defined with +% \begin{quote} +% "\tbx@MakeDef\PrefixNewName\PrefixRenewName\PrefixProvideName%"\\ +% " \PrefixDefName\PrefixLetName\PrefixName\tbx@e@Prefix@Name%"\\ +% " "\bracemeta{Prefix}\bracemeta{Name}\bracemeta{Replacement Mask} +% \end{quote} +% Note that \meta{Replacement Mask} must be read implicitly, because it +% contains "#1" which is usually forbidden. +% The macro "\tbx@e@Prefix@Name" is defined as +% \begin{quote} +% "\tbx@long\def\tbx@e@Name#1"\bracemeta{Replacement Mask} +% \end{quote} +% The macros generated by +% \begin{quote} +% "\PrefixNewName"\bracemeta{something}"{"$\ldots$"...}" +% \end{quote} +% carry the names +% \begin{quote} +% "\tbx@l@"\meta{Prefix}"@"\meta{Name}"@"\meta{something} +% \end{quote} +% Observe that the symbol "@" has currently the exceptional letter catcode, +% so that there is no danger that the user mangles up the names (unless he +% uses "\makeatletter" which he should of course not do, usually). +% \makeatletter +% \begin{macrocode} +\def\tbx@MakeDef#1#2#3#4#5#6#7#8#9{% + \tbx@def#1{\toolboxIfNextGobbling*% + {\tbx@MakeNew\let{#8}{#9}}{\tbx@MakeNew\def{#8}{#9}}}% + \tbx@def#2{\toolboxIfNextGobbling*% + {\tbx@MakeRenew\let{#8}{#9}}{\tbx@MakeRenew\def{#8}{#9}}}% + \tbx@def#3{\toolboxIfNextGobbling*% + {\tbx@MakeProvide\let{#8}{#9}}{\tbx@MakeProvide\def{#8}{#9}}}% + \tbx@def#4{\toolboxIfNextGobbling*% + {\tbx@MakeForce\let{#8}{#9}}{\tbx@MakeForce\def{#8}{#9}}}% + \tbx@def#5##1##2{\expandafter + \tbx@MakeLet\csname tbx@l@#8@#9@##2\endcsname##1}% + \tbx@def#6{\toolboxIfNextGobbling*% + {\tbx@MakeUse\tbx@itemEnd{#8}{#9}}{\tbx@MakeUse\relax{#8}{#9}}}% + \long\def#7##1} + +% \end{macrocode} +% \begin{macro}{\tbx@MakeNew} +% "\tbx@MakeNew"\bracemeta{mode}\relax +%\bracemeta{Prefix}\bracemeta{Name}\bracemeta{something}% +%\bracemeta{text to remember} +% \begin{macrocode} +\def\tbx@MakeNew#1#2#3#4{\expandafter + \ifx\csname tbx@l@#2@#3@#4\endcsname\relax\else + \errmessage{#2New#3: entry #4 already exists}% + \fi + \tbx@MakeForce{#1}{#2}{#3}{#4}} + +% \end{macrocode} +% \end{macro} +% \begin{macro}{\tbx@MakeRenew} +% "\tbx@MakeRenew"\bracemeta{mode}\relax +%\bracemeta{Prefix}\bracemeta{Name}\bracemeta{something}% +%\bracemeta{text to remember} +% \begin{macrocode} +\def\tbx@MakeRenew#1#2#3#4{\expandafter + \ifx\csname tbx@l@#2@#3@#4\endcsname\relax + \errmessage{#2Renew#3: entry #4 was not defined before}% + \fi + \tbx@MakeForce{#1}{#2}{#3}{#4}} + +% \end{macrocode} +% \end{macro} +% \begin{macro}{\tbx@MakeProvide} +% "\tbx@MakeProvide"\bracemeta{mode}\relax +%\bracemeta{Prefix}\bracemeta{Name}\bracemeta{something}% +%\bracemeta{text to remember} +% \begin{macrocode} +\def\tbx@MakeProvide#1#2#3#4#5{\expandafter + \ifx\csname tbx@l@#2@#3@#4\endcsname\relax + \tbx@MakeForce{#1}{#2}{#3}{#4}{#5}% + \fi} + +% \end{macrocode} +% \end{macro} +% \begin{macro}{\tbx@MakeForce} +% "\tbx@MakeForce"\bracemeta{mode}\relax +%\bracemeta{Prefix}\bracemeta{Name}\bracemeta{something}% +%\bracemeta{text to remember} +% \begin{macrocode} +\long\def\tbx@MakeForce#1#2#3#4#5{% + \ifx#1\let + \expandafter + \let\csname tbx@l@#2@#3@#4\endcsname#5% + \else + \expandafter + \tbx@MakeDoDef\csname tbx@l@#2@#3@#4\expandafter\endcsname + \csname tbx@e@#2@#3\endcsname{#5}% + \fi} +% \end{macrocode} +% \begin{macro}{\tbx@MakeDoDef} +% \begin{quote} +% "\tbx@MakeDoDef"\relax +%"\tbx@l@"\meta{Prefix}"@"\meta{Name}"@"\meta{something}"%"\\ +%" \tbx@e@"\meta{Prefix}"@"\meta{Name}\bracemeta{text to remember} +% \end{quote} +% \begin{macrocode} +\long\def\tbx@MakeDoDef#1#2#3{\tbx@toks\expandafter{#2{#3}}% + \edef#1{\the\tbx@toks}} + +% \end{macrocode} +% \end{macro} +% \end{macro} +% \begin{macro}{\tbx@MakeLet} +% "\tbx@MakeLet"\cmdmeta{Prefix}"@"\meta{Name}"@"\meta{something}\relax +%\cmdmeta{something} +% \begin{macrocode} +\def\tbx@MakeLet#1#2{% + \ifx#1\relax + \let#2\undefined + \else + \let#2#1% + \fi} + +% \end{macrocode} +% \end{macro} +% \begin{macro}{\tbx@MakeUse} +% "\tbx@MakeUse"\bracemeta{mode}\relax +%\bracemeta{Prefix}\bracemeta{Name}\bracemeta{something} +% \begin{macrocode} +\def\tbx@MakeUse#1#2#3#4{% + \expandafter + \ifx\csname tbx@l@#2@#3@#4\endcsname#1% + \errmessage{Entry #4 was not defined with + #2New#3, #2Provide#3, or #2Def#3}% + \fi + \csname tbx@l@#2@#3@#4\endcsname} + +% \end{macrocode} +% \end{macro} +% \begin{macro}{\tbx@def} +% "\tbx@def" is similar to "\def", but existence is tested (via "\relax") +% \begin{macrocode} +\def\tbx@def#1{% + \ifx#1\relax\else + \errmessage{\string#1 is already defined}% + \fi + \def#1} + +% \end{macrocode} +% \end{macro} +% \end{macro} +% \begin{macro}{\toolboxFreeDef}\nocomment +% \begin{macrocode} +\def\toolboxFreeDef{\toolboxIfNextGobbling*% + {\tbx@MakeNames{\tbx@FreeDef\relax}}{\tbx@MakeNames{\tbx@FreeDef\undefined}}} +% \end{macrocode} +% \begin{macro}{\tbx@FreeDef} +% \begin{quote} +% "\tbx@FreeDef"\bracemeta{mode}"\PrefixNewName\PrefixRenewName%"\\ +% " \PrefixProvideName\PrefixDefName\PrefixLetName\PrefixName"%\\ +% " \tbx@e@Prefix@Name"\bracemeta{Prefix}\bracemeta{Name} +% \end{quote} +% The last two arguments are not needed, but we must gobble them. +% Since a macro can have at most 9 arguments, we must gobble the last one +% separately. +% \begin{macrocode} +\def\tbx@FreeDef#1#2#3#4#5#6#7#8#9{% + \let#2\undefined\let#3\undefined\let#4\undefined\let#5\undefined + \let#8\undefined + \ifx#1\undefined + \let#6\undefined\let#7\undefined + \fi\toolboxGobbleArg} + +% \end{macrocode} +% \end{macro} +% \end{macro} +% \begin{macro}{\tbx@MakeNames} +% The call +% \begin{quote} +% "\tbx@MakeNames"\bracemeta{commands}"["\meta{Prefix}"]"\bracemeta{Name} +% \end{quote} +% (where the "["\meta{Prefix}"]" argument is optional) expands to +% \begin{quote} +% \meta{commands}"\PrefixNewName\PrefixRenewName\PrefixProvideName%"\\ +% " \PrefixLetName\PrefixName\tbx@e@Prefix@Name%"\\ +% " "\bracemeta{Prefix}\bracemeta{Name} +% \end{quote} +% \begin{macrocode} +\def\tbx@MakeNames#1{\toolboxIfNextToken[%] + {\tbx@MakingNames{#1}}{\tbx@MakingNames{#1}[]}} +% \end{macrocode} +% \begin{macro}{\tbx@MakingNames} +% \begin{macrocode} +\def\tbx@MakingNames#1[#2]#3{\expandafter + \tbx@ListSwap\expandafter{% + \csname#2New#3\expandafter\endcsname + \csname#2Renew#3\expandafter\endcsname + \csname#2Provide#3\expandafter\endcsname + \csname#2Def#3\expandafter\endcsname + \csname#2Let#3\expandafter\endcsname + \csname#2#3\expandafter\endcsname + \csname tbx@e@#2@#3\endcsname{#2}{#3}}{#1}} +% \end{macrocode} +% \begin{macro}{\tbx@ListSwap}\nocomment +% \begin{macrocode} +\def\tbx@ListSwap#1#2{#2#1} + +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \subsection{Macros supporting fancy optional argument parsing} +% +% \begin{macro}{\toolboxFuturelet} +% \begin{macrocode} +\long\def\toolboxFuturelet#1#2{\toolboxTokDef{#2}\tbx@tmp\futurelet#1\tbx@tmp} + +% \end{macrocode} +% \end{macro} +% \begin{macro}{\toolboxGobbleNext} +% \begin{macrocode} +\long\def\toolboxGobbleNext#1{\toolboxTokDef{#1}\tbx@tmp + \afterassignment\tbx@tmp + \let\toolboxToken= }% The space here is important to read spaces properly + +% \end{macrocode} +% \end{macro} +% \begin{macro}{\toolboxIfNextToken} +% \begin{macrocode} +\long\def\toolboxIfNextToken#1#2#3{% + \toolboxFuturelet\toolboxToken{% + \ifx#1\toolboxToken + \expandafter\toolboxFirstOfTwo + \else + \expandafter\toolboxSecondOfTwo + \fi{#2}{#3}}} + +% \end{macrocode} +% \end{macro} +% \begin{macro}{\toolboxIfNextGobbling} +% \begin{macrocode} +\long\def\toolboxIfNextGobbling#1#2#3{% + \toolboxIfNextToken{#1}{\toolboxGobbleNext{#2}}{#3}} + +% \end{macrocode} +% \end{macro} +% +% \subsection{Macros supporting loops over tokenlists and itemlists} +% +% \begin{macro}{\toolboxLoop} +% "\toolboxLoop" just calls "\tbx@item" with the magic names +% "\tbx@i" and "\tbx@I". +% \begin{macrocode} +\long\def\toolboxLoop#1#2{\tbx@item\tbx@i\tbx@I{#1}{#2}} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\toolboxLoopName} +% "\toolboxLoopName" calls "\tbx@item" with the magic names "\tbx@i@#1" +% and "\tbx@I#@1" +% \begin{macrocode} +\long\def\toolboxLoopName#1#2#3{\tbx@LoopName{#1}iI\tbx@item{#2}{#3}} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\tbx@LoopName} +% \begin{verbatim} +% \tbx@LoopName{name}{x}{y}{\exec}\end{verbatim} +% is equivalent to +% \begin{verbatim} +% \exec\tbx@x@name\tbx@y@name\end{verbatim} +% \begin{macrocode} +\def\tbx@LoopName#1#2#3#4{% + \expandafter#4\csname tbx@#2@#1\expandafter\endcsname + \csname tbx@#3@#1\endcsname} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\tbx@item} +% The call +% \begin{quote} +% "\tbx@item{\MagicNameA}{\MagicNameB}"\bracemeta{items}\bracemeta{action} +% \end{quote} +% is the essential part of "\toolboxLoop". It has the same semantic with +% the only difference that the names "\MagicNameA" and "\MagicNameB" are used +% as temporary macros (they are the reason why "\tbx@item" is not reentrant). +% \begin{macrocode} +\long\def\tbx@item#1#2#3#4{% + \long\def#1##1{% + \toolboxTokDef{##1}\toolboxToken + \ifx\toolboxToken\tbx@itemEnd + \def#2{\let#1\undefined\let#2\undefined}% + \else + #4{##1}% + \fi + #2}% + \let#2#1% + #1#3\tbx@itemEnd} +% \end{macrocode} +% \begin{macro}{\tbx@itemEnd} +% "\tbx@itemEnd" is the magic token used to mark the end of the list in +% "\tbx@item". +% Of course, we could also use any other macro instead, but this is unique, +% even if we compare with "\ifx". Moreover, we want a short macro to +% avoid unnecessary redundancy in comparing with "\ifx". +% It appears not necessary to make this token change in recursions, because +% in each expansion of a list, the newest item will automatically be the +% earliest. +% \begin{macrocode} +\def\tbx@itemEnd{\tbx@itemEnd} + +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\toolboxTokenLoop} +% "\toolboxTokenLoop" just calls "\tbx@token" with the magic names +% "\tbx@t" and "\tbx@T". +% \begin{macrocode} +\long\def\toolboxTokenLoop#1#2{\tbx@token\tbx@t\tbx@T{#1}{#2}} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\toolboxTokenLoopName} +% "\toolboxTokenLoopName" calls "\tbx@token" with the magic names "\tbx@t@#1" +% and "\tbx@T#@1" +% \begin{macrocode} +\long\def\toolboxTokenLoopName#1#2#3{\tbx@LoopName{#1}tT\tbx@token{#2}{#3}} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\tbx@token} +% The call +% \begin{quote} +% "\tbx@token{\MagicNameA}{\MagicNameB}"\bracemeta{items}\bracemeta{action} +% \end{quote} +% is the essential part of "\toolboxTokenLoop". It has the same semantic with +% the only difference that the names "\MagicNameA" and "\MagicNameB" are used +% as temporary macros (they are the reason why "\tbx@token" is not reentrant). +% \begin{macrocode} +\long\def\tbx@token#1#2#3#4{% + \def#1{% + \ifx\toolboxToken\tbx@tokenEnd + \def#2{\let#1\undefined\let#2\undefined}% + \else + #4\toolboxToken + \fi + #2}% + \def#2{\afterassignment#1\let\toolboxToken= }% + #2#3\tbx@tokenEnd} +% \end{macrocode} +% \begin{macro}{\tbx@tokenEnd} +% "\tbx@tokenEnd" is the magic token used to mark the end of the list +% for "\tbx@token". +% The same remarks as for "\tbx@itemEnd" hold. However, it is not clear +% whether we could just use "\tbx@itemEnd" instead, because the scan rules +% for "\tbx@token" and "\tbx@item" are somewhat different, and thus it is +% not immediately clear whether in some fancy situations such lists (if +% called cross-wise) could overlap: I found no example, but I also did not +% put too much effort in finding one. In any case, we are on the sure side, +% if we just use a different token. +% \begin{macrocode} +\def\tbx@tokenEnd{\tbx@tokenEnd} + +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\toolboxIfEmpty} +% \begin{macrocode} +\long\def\toolboxIfEmpty#1{\toolboxIfx{#1}\toolboxEmpty} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\toolboxIfX} +% \begin{macrocode} +\long\def\toolboxIfX#1#2{\toolboxTokDef{#1}\tbx@ifx\toolboxIfx{#2}\tbx@ifx} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\toolboxIfx} +% \begin{macrocode} +\long\def\toolboxIfx#1#2{\toolboxTokDef{#1}\tbx@tmp + \toolboxIfElse{\ifx\tbx@tmp#2}} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\toolboxIfElse} +% \begin{macrocode} +\long\def\toolboxIfElse#1{#1\expandafter + \toolboxFirstOfTwo\else\expandafter\toolboxSecondOfTwo\fi} + +% \end{macrocode} +% \end{macro} +% +% +% \subsection{Macros supporting controlled expansion} +% +% \begin{macro}{\toolboxTokDef}\nocomment +% \begin{macrocode} +\long\def\toolboxTokDef#1#2{\tbx@toks{#1}\edef#2{\the\tbx@toks}} + +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\toolboxDef} +% This is mainly a call of "\toolboxLoopName". It is slightly faster if we +% call "\tbx@item" immediately (and then we can also give magic names which do +% not clash with any other names). Also for time and memory reasons, we always +% assume that the temporary variable +% \begin{macro}{\tbx@odeftmp} +% "\tbx@odeftmp" +% \end{macro} +% is "\toolboxEmpty" at the beginning; we reset it to "\toolboxEmpty" at +% the end (so that the memory is freed). +% \begin{macrocode} +\def\toolboxDef#1#2{% + \tbx@item\tbx@odefa\tbx@odefb{#2}\tbx@odef + \let#1\tbx@odeftmp\let\tbx@odeftmp\toolboxEmpty} +\let\tbx@odeftmp\toolboxEmpty +% \end{macrocode} +% \begin{macro}{\tbx@odef} +% \begin{macrocode} +\long\def\tbx@odef#1{\expandafter\tbx@odefapp\expandafter{#1}} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\tbx@odefapp} +% "\tbx@odefapp" appends its argument to "\tbx@odeftmp". +% \begin{macrocode} +\long\def\tbx@odefapp#1{\tbx@toks\expandafter{\tbx@odeftmp#1}% + \edef\tbx@odeftmp{\the\tbx@toks}} + +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\toolboxAppend}\nocomment +% \begin{macrocode} +\def\toolboxAppend#1#2{\toolboxDef#1{#1#2}} + +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\toolboxSurround}\nocomment +% \begin{macrocode} +\long\def\toolboxSurround#1#2#3{\tbx@toks{#1}% + \tbx@toks\expandafter{\the\expandafter\tbx@toks#3#2}% + \edef#3{\the\tbx@toks}} + +% \end{macrocode} +% \end{macro} +% +% +% \subsection{Macros supporting searching, splitting, and replacing} +% +% \begin{macro}{\toolboxMakeSplit}\nocomment +% \begin{macrocode} +\def\toolboxMakeSplit{% + \toolboxIfNextGobbling*\tbx@MakeLong\tbx@MakeShort} +% \end{macrocode} +% +% \begin{macro}{\tbx@Makelong} +% \begin{quote} +% "\tbx@Makelong"\bracemeta{search}"{cmd}" +% \end{quote} +% is the same as +% \begin{quote} +% "\tbx@DoSplitInstance{\cmd}{\tbx@cmd@spt}{\tbx@cmd@rst}" +%\bracemeta{search}"\long" +% \end{quote} +% \begin{macrocode} +\long\def\tbx@MakeLong#1#2{% + \tbx@SplitNames{#2}% + \expandafter + \tbx@DoSplitInstance\tbx@splt{#1}\long} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\tbx@MakeShort} +% "\tbx@Makeshort" is essentially the same as "\tbx@Makelong" (just that +% "\long" is missing, of course). We could have used the same macro with +% an additional argument, but it is more convenient for the user if this +% macro itself is not "\long" so that new paragraphs in the passed search +% string already give an error: It makes no sense to look for new paragraphs +% in texts which may not contain new paragraphs. +% \begin{macrocode} +\def\tbx@MakeShort#1#2{% + \tbx@SplitNames{#2}% + \expandafter + \tbx@DoSplitInstance\tbx@splt{#1}{}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\tbx@SplitNames} +% The call "\tbx@SplitNames{cmd}" is equivalent to +% \begin{verbatim} +% \def\tbx@splt{\cmd \tbx@cmd@spt \tbx@cmd@rst}\end{verbatim} +% \begin{macrocode} +\def\tbx@SplitNames#1{% + \expandafter + \def\expandafter\tbx@splt\expandafter{\csname#1\expandafter\endcsname + \csname tbx@#1@spt\expandafter\endcsname + \csname tbx@#1@rst\endcsname}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\tbx@DoSplitInstance} +% The call +% \begin{quote} +% "\tbx@DoSplitInstance{\cmd}{\tbx@cmd@spt}{\tbx@cmd@rst}"\bracemeta{search} +%\bracemeta{long} +% \end{quote} +% creates the instance "\cmd" which splits its argument at +% \bracemeta{search} (also "\tbx@cmd@spt" and "\tbx@cmd@rst" are created +% which are needed for "\cmd" to work). The argument \meta{long} must be +% either "\long" or empty, depending whether long definitions are desired.\par +% The difficulty in the definition of "\cmd" is to ensure that "{xxx}|{yyy}" +% splits into "{xxx}" and "{yyy}" \emph{with} braces (i.e., we have to +% find out whether there are braces which are eliminated by \TeX\ as +% `argument braces'). Actually, this problem occurs only for the part "{yyy}". +% We solve it by appending an "a" to \meta{argument}, i.e., we actually +% split the string "{xxx}|{yyy}a". Of course, we have to eliminate the +% trailing "a" at the end. +% \begin{macrocode} +\long\def\tbx@DoSplitInstance#1#2#3#4#5{% + #5\def#1##1##2##3{% + #2##2##3\toolboxEmpty##1#4#4@tbx@spt% + \ifx##3\toolboxEmpty + \let##3\undefined + \else + #3##3##1a@tbx@rst% + \fi + }% + #5\def#2##1##2##3#4##4#4##5@tbx@spt{\expandafter + \toolboxTokDef\expandafter{##3}##1\toolboxTokDef{##5}##2}% + #5\def#3##1##2#4##3@tbx@rst{\tbx@rememberlasta##3@tbx@dropa% + \tbx@defwithoutlasta##1##3@tbx@dropa}} +% \end{macrocode} +% \begin{macro}{\tbx@rememberlasta} +% The call +% \begin{quote} +% "\tbx@rememberlasta"\meta{arg}"@tbx@dropa" +% \end{quote} +% (no braces: The magic string "@tbx@dropa" is used to find the end of +% \meta{arg}) is only admissible, if the last token in \meta{arg} is an "a". +% In this case, \DescribeMacro{\tbx@droplasta}"\tbx@droplasta" is +% defined as \meta{arg} without the trailing "a" (but it may happen that +% \meta{arg} looses surrounding braces), and the corresponding string with the +% trailing "a" (possibly without surrounding braces) is saved into +% \DescribeMacro{\tbx@rebuilda}"\tbx@rebuilda". +% This macro is used by the instances created +% by "\tbx@DoSplitInstance". +% \begin{macrocode} +\long\def\tbx@rememberlasta#1a@tbx@dropa{\toolboxTokDef{#1}\tbx@droplasta + \toolboxTokDef{#1a}\tbx@rebuilda} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\tbx@defwithoutlasta} +% The call +% \begin{quote} +% "\tbx@defwithoutlasta{\afterstring}"\meta{arg}"@tbx@dropa" +% \end{quote} +% (no braces: The magic string "@tbx@dropa" is used to find the end of +% \meta{arg}) is only admissible, if the last token in \meta{arg} is an "a". +% If \meta{arg} coincides with "\tbx@rebuilda", +% then we know that we did not loose any braces, and we set "\afterstring" +% to the content of "\tbx@droplasta"; otherwise we lost braces and thus +% have additionally to surround the content of "\afterstring" by braces. +% \begin{macrocode} +\long\def\tbx@defwithoutlasta#1#2@tbx@dropa{\toolboxTokDef{#2}\tbx@originala + \ifx\tbx@originala\tbx@rebuilda +% \end{macrocode} +% Did we forget braces in "\tbx@rememberlasta"? +% \begin{macrocode} + \let#1\tbx@droplasta + \else + \expandafter\toolboxTokDef\expandafter{\expandafter{\tbx@droplasta}}#1% + \fi} + +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \begin{macro}{\toolboxFreeSplit}\nocomment +% \begin{macrocode} +\def\toolboxFreeSplit#1{% + \tbx@SplitNames{#1}% + \expandafter + \toolboxLoop\expandafter{\tbx@splt}\tbx@freeSplit} +% \end{macrocode} +% \begin{macro}{\tbx@freeSplit}\nocomment +% \begin{macrocode} +\def\tbx@freeSplit#1{\let#1\undefined} + +% \end{macrocode} +% \end{macro} +% \end{macro} +% \begin{macro}{\toolboxSplitAt} +% "\toolboxSplitAt" just calls "tbx@DoSplitInstance" with dummy temporary +% variables and then executes the corresponding command. +% \begin{macrocode} +\def\toolboxSplitAt{\toolboxIfNextGobbling*\tbx@SplitLong\tbx@SplitShort} +% \end{macrocode} +% \begin{macro}{\tbx@SplitLong}\nocomment +% \begin{macrocode} +\long\def\tbx@SplitLong#1#2#3#4{% + \tbx@DoSplitInstance\tbx@splt\tbx@splta\tbx@spltb{#2}\long + \tbx@splt{#1}{#3}{#4}} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\tbx@SplitShort} +% We cannot use just an additional argument in "\tbx@SplitLong", because +% we really should use a non-"\long" macro to read the arguments. +% \begin{macrocode} +\def\tbx@SplitShort#1#2#3#4{% + \tbx@DoSplitInstance\tbx@splt\tbx@splta\tbx@spltb{#2}{}% + \tbx@splt{#1}{#3}{#4}} + +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\toolboxReplaceSplit} +% "\toolboxReplaceSplit"\bracemeta{replace}"\SplitCmd\macro" +% \begin{macrocode} +\long\def\toolboxReplaceSplit#1#2#3{% + \toolboxTokDef{#1}\tbx@reptext + \expandafter + \tbx@replace\expandafter{#3}{\let#3\toolboxEmpty}#3#2\tbx@reptext} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\tbx@replace} +% "\tbx@replace\bracemeta{text}\bracemeta{first}\macro\SplitCmd\Reptext" +% First executes \meta{first}. +% Then appends to "\macro" the content of \bracemeta{text} with the matches +% of "\SplitCmd" replaced by the content of "\Reptext". +% \begin{macrocode} +\long\def\tbx@replace#1#2#3#4#5{#2% + #4{#1}\tbx@repla\tbx@replb + \toolboxIfElse{\ifx\tbx@replb\undefined}% + {\toolboxDef#3{#3\tbx@repla}}% + {\toolboxDef#3{#3\tbx@repla#5}% + \expandafter\tbx@replace\expandafter{\tbx@replb}{}#3#4#5}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\toolboxReplace} +% "\toolboxReplace"\bracemeta{search}\bracemeta{replace}"\macro" +% just calls "tbx@DoSplitInstance" with dummy temporary variables +% and then executes "\toolboxReplaceSplit". +% \begin{macrocode} +\long\def\toolboxReplace#1#2{% + \tbx@DoSplitInstance\tbx@splt\tbx@splta\tbx@spltb{#1}\long + \toolboxReplaceSplit{#2}\tbx@splt} +% \end{macrocode} +% \end{macro} +% +% \subsection{Macros supporting redefinition of macros} +% +% \begin{macro}{\toolboxMakeHarmless}\nocomment +% \begin{macrocode} +\def\toolboxMakeHarmless#1{\edef#1{\tbx@Nearverbatim#1}} +% \end{macrocode} +% \begin{macro}{\tbx@Nearverbatim}\nocomment +% \begin{macrocode} +\def\tbx@Nearverbatim{\expandafter\tbx@Meaning\meaning} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\tbx@Meaning}\nocomment +% \begin{macrocode} +\long\def\tbx@Meaning#1>{} + +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\toolboxDropBrace}\nocomment +% \begin{macrocode} +\def\toolboxDropBrace#1{\expandafter\tbx@ForgetBrace#1@tbx@dropbrace#1} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\tbx@ForgetBrace}\nocomment +% \begin{macrocode} +\long\def\tbx@ForgetBrace#1@tbx@dropbrace#2{\toolboxTokDef{#1}#2} + +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\toolboxIf}\nocomment +% \begin{macrocode} +\long\def\toolboxIf#1#2#3{% + \ifx#1#3\def\tbx@tmp{#2#3}\else\def\tbx@tmp{#2\tbx@tmp}\fi\tbx@tmp} + +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\toolboxNewiftrue}\nocomment +% \begin{macrocode} +\def\toolboxNewiftrue#1{\tbx@newifexec{#1}{\csname#1true\endcsname}} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\toolboxNewiffalse}\nocomment +% \begin{macrocode} +\def\toolboxNewiffalse#1{\tbx@newifexec{#1}{\csname#1false\endcsname}} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\toolboxNewiftrue}\nocomment +% \begin{macrocode} +\def\toolboxNewifTrue#1{\tbx@newifexec{#1}{}\csname#1true\endcsname} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\toolboxNewiffalse}\nocomment +% \begin{macrocode} +\def\toolboxNewifFalse#1{\tbx@newifexec{#1}{}\csname#1false\endcsname} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\tbx@newifexec} +% \begin{quote} +% "\tbx@newifexec"\bracemeta{name}\bracemeta{initialization} +% \end{quote} +% If the command "\if"\meta{name} already exists, nothing happens. +% Otherwise, the commands \cmdmeta{name}"true" and \cmdmeta{name}"false" are +% created (similarly as by the \TeX\ command "\newif"), and afterwards +% \meta{initialization} is executed. Here, \meta{initialization} should be +% either \cmdmeta{name}"true" or \cmdmeta{name}"false" +% which then defines "\if"\meta{name} to the desired default. +% (It may also be empty if you do this initialization immediately afterwards). +% \meta{initialization} should not contain any potential "\if" tokens.\par +% One must be very careful in the implementation of this macro, +% because "\if"'s are parsed very strange by \TeX. +% However, if an "\if"-command is the first token following our only "\ifx", +% we do not run into problems. Moreover, the first parsing until "\fi" does +% not see any further "\if", because it is hidden in "\csname" which has not +% been expanded by this time. +% \begin{macrocode} +\def\tbx@newifexec#1#2{\expandafter + \ifx\csname if#1\endcsname\relax + \expandafter\tbx@newif\csname if#1\endcsname{#1}% + #2% + \fi} +% \end{macrocode} +% \begin{macro}{\tbx@newif} +% It is rather annoying that D.~E. Knuth has introduced the "\outer" +% directive: +% The sole purpose of that command is to cause problems and to force people +% to think how to get around these problems. It is especially irritating that +% the standard command "\newif" was (before \LaTeXe) defined with this +% attribute. To work in a normal way, we have to define "\newif" by hand +% in a sane way. It is simpler for us, if we do not only pass the name as a +% single token but additionally also the full name without "if". +% So our simpler "\newif" macro is called as follows: +% \begin{quote} +% "\tbx@newif"\cmdmeta{ifname}\bracemeta{name} +% \end{quote} +% This macro does \emph{not} define \cmdmeta{ifname}. But gets automatically +% defined after the first call of \cmdmeta{name}"true" or +% \cmdmeta{name}"false" which should of course happen immediately afterwards. +% \begin{macrocode} +\def\tbx@newif#1#2{% + \expandafter + \def\csname#2true\endcsname{\let#1\iftrue}% + \expandafter + \def\csname#2false\endcsname{\let#1\iffalse}} + +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \subsection{Macros supporting concatenated macro names} +% +% \begin{macro}{\toolboxWithNr}\nocomment +% \begin{macrocode} +\def\toolboxWithNr#1#2#3{\expandafter#2\csname #3#1\endcsname} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\toolboxLet}\nocomment +% \begin{macrocode} +\def\toolboxLet#1#2{\expandafter\let\expandafter#1\csname #2\endcsname} + +% \end{macrocode} +% \end{macro} +% +% \iffalse +%</package> +% \fi +% \Finale\PrintIndex +% +% +% +% \iffalse +%<*metainfo> +% \fi +\iffalse ------------------------------------------------------------- +% +% Just in case that for some reason the file `toolbox.ins' got lost: +% The content of this file is between the lines %<*insfile> and %</insfile>. +% +%\iffalse +%</metainfo> +%<*insfile> +\def\batchfile{toolbox.ins} +\input docstrip.tex +\keepsilent +\nopreamble +\generateFile{toolbox.sty}{f}{\from{toolbox.dtx}{package}} +\generateFile{toolbox.txt}{f}{\from{toolbox.dtx}{asciidocu}} +\generateFile{toolbox.tex}{f}{\from{toolbox.dtx}{driver}} +%%\generateFile{toolbox.ins.dup}{f}{\from{toolbox.dtx}{insfile}} + +\Msg{***************************************************************} +\Msg{*} +\Msg{* To finish the installation you have to move the} +\Msg{* file 'toolbox.sty' into a directory searched by TeX.} +\Msg{*} +\Msg{*} +\Msg{* Run the file toolbox.tex through LaTeX to produce the} +\Msg{* documentation or read the ascii documentation in toolbox.txt} +\Msg{*} +\Msg{*} +\Msg{***************************************************************} +\endbatchfile +%</insfile> +%<*metainfo> +% \fi +\fi +% \iffalse +%</metainfo> +% \fi +\endinput + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "toolbox.tex" +%%% End: diff --git a/Master/texmf-dist/source/latex/toolbox/toolbox.ins b/Master/texmf-dist/source/latex/toolbox/toolbox.ins new file mode 100644 index 00000000000..9032400b2af --- /dev/null +++ b/Master/texmf-dist/source/latex/toolbox/toolbox.ins @@ -0,0 +1,22 @@ +\def\batchfile{toolbox.ins} +\input docstrip.tex +\keepsilent +\nopreamble +\generateFile{toolbox.sty}{f}{\from{toolbox.dtx}{package}} +\generateFile{toolbox.txt}{f}{\from{toolbox.dtx}{asciidocu}} +\generateFile{toolbox.tex}{f}{\from{toolbox.dtx}{driver}} +%%\generateFile{toolbox.ins.dup}{f}{\from{toolbox.dtx}{insfile}} + +\Msg{***************************************************************} +\Msg{*} +\Msg{* To finish the installation you have to move the} +\Msg{* file 'toolbox.sty' into a directory searched by TeX.} +\Msg{*} +\Msg{*} +\Msg{* Run the file toolbox.tex through LaTeX to produce the} +\Msg{* documentation or read the ascii documentation in toolbox.txt} +\Msg{*} +\Msg{*} +\Msg{***************************************************************} +\endbatchfile +%</insfile> |