Debian Codegraph @

texmf-dist/source/latex/toolbox/toolbox.dtx

raw
1 % \def\fileversion{5.1}\def\filedate{2004/04/29}\def\docdate{2013/11/26}
2 %\iffalse These lines are necessary for the doc and docstrip utilities
3 %<*asciidocu>
4
5 %%#
6 %%# Author:
7 %%#
8 %%# M. V\"ath [email protected]
9 %%#
10 %%# The author thanks
11 %%# David Kastrup <[email protected]>
12 %%#
13
14 %%# The package may be distributed and/or modified under the conditions of
15 %%# the LaTeX Project Public License (version 1.3c or later).
16
17 %%#############################################################################
18 %%#
19 %%# The TeX programmer's toolbox; enhanced version.
20 %%# This (La)TeX package provides some macros which are convenient for
21 %%# writing indices, glossaries, or other macros.
22 %%# It contains macros which support
23 %%#
24 %%# - implicit macros - a useful supplement to \index or varindex for
25 %%# writing glossaries or indices
26 %%# - fancy optional arguments
27 %%# - loops over tokenlists and itemlists
28 %%# - searching, splitting, and replacing
29 %%# - controlled expansion
30 %%# - redefinition of macros
31 %%# - concatenated macro names
32 %%#
33 %%#############################################################################
34
35 %%#
36 %%# This package was tested with plain TeX, LaTeX 2.09, and LaTeX 2e,
37 %%# and it should actually run with all TeX formats.
38 %%#
39
40 % If you have access to (reasonable new) docstrip TeXfiles, you should run
41 % tex/latex on the file
42 % `toolbox.ins'
43 % to produce the files `toolbox.sty', `toolbox.txt' and `toolbox.tex'.
44 % (In case `toolbox.ins' is lost: You can find its content in the last
45 % few lines of the file you are currently reading between the
46 % lines %<*insfile> and %</insfile>;
47 % BTW: You should name this file here `toolbox.dtx' before you run tex
48 % on toolbox.ins).
49 %
50 % The file `toolbox.txt' contains a `brief' (but complete) ascii
51 % documentation. If you have additionally access to LaTeX 2e, you may run
52 % latex on the generated file `toolbox.tex' to produce `toolbox.dvi' which
53 % contains a more luxury documentation.
54 %
55 % If you do not have access to the docstrip TeXfiles you may simply
56 % copy/rename this file here into
57 % `toolbox.sty'
58 % to use the package and read the ascii documentation in this file.
59 % The ascii documentation (the content of `toolbox.txt') consists of all
60 % lines in this file which start with %%# (this is the above block and another
61 % (very large) block which follows soon).
62 %
63 % But I do not recommended this, because TeX will need more time to read this
64 % longer file, and because there might be a (very slight) incompatibility if
65 % you use it (namely if you load `toolbox.sty' with some *extremely* strange
66 % catcodes).
67 % I recommend in this case instead to generate the file `toolbox.sty' as
68 % anything between the lines %<*package> and %</package> by hand.
69 % (This is not precisely the file which you get with the docstrip TeXfiles,
70 % but a reasonable good substitute. To speed up loading, you may also
71 % eliminate all lines starting with `% ' in `toolbox.sty').
72 % For your information: The file `toolbox.tex' produced by the docstrip
73 % TeXfiles is anything between the lines %<*driver> and %</driver>
74 % (with a line containing \endinput and two comment lines appended)
75 %
76 %
77 % In any case, you end up with the file `toolbox.sty'.
78 %
79 % If you can generate `toolbox.tex', you will probably want to stop
80 % reading now and instead read the `luxury' documentation in `toolbox.dvi'.
81 %
82 % Otherwise, you have to make due with the following ascii documentation.
83 %
84 %
85 % \fi\catcode\#14\relax\iffalse (This line is needed for the doc utility)
86 %
87
88 %%# To use toolbox, you have to put `toolbox.sty' in a path where TeX looks
89 %%# for its input files. The TeX documents using toolbox need the
90 %%# following modifications in their header:
91 %%#
92 %%# a) If you use LaTeX2.09, use toolbox as a style option, e.g.
93 %%# \documentstyle[toolbox]{article}
94 %%# or
95 %%# \documentstyle[toolbox,12pt]{article}
96 %%# b) If you use LaTeX2e, put in the preamble the command
97 %%# \usepackage{toolbox}
98 %%# c) If you use some other (non-LaTeX) format, you will probably have to
99 %%# insert a line like
100 %%# \catcode`\@=11\input toolbox.sty\catcode`\@=12\relax
101 %%#
102 %%# The only LaTeX-specific commands used in `toolbox.sty' are:
103 %%#
104 %%# \newcommand (only in the form \newcommand{\command}{} to ensure that
105 %%# \command was not defined before)
106 %%# \ProvidesPackage
107 %%# \typeout
108 %%#
109 %%# The above commands are used only if they are defined.
110 %%#
111
112 %%#
113 %%# Description of the provided macros:
114 %%#
115
116 %%# General remark: Many macros could appear in several sections.
117 %%# For example, \toolboxMakeDef and \toolboxSourround might be considered
118 %%# as macros which support redefinitions of macros. However, we put them
119 %%# in different sections which perhaps explain better their nature.
120
121 %%#
122 %%# Implicit macro definitions
123 %%# --------------------------
124
125 %%# What we mean by implicit macro definitions is probably best explained by
126 %%# the following examples which show the intended usage:
127 %%#
128 %%# (In the following examples, we always refer to the \index command. Note
129 %%# that it may be more convenient to use for indices the varindex package in
130 %%# addition - the documentation of varindex (release 2.3 or newer) gives
131 %%# additional hints and examples how these two (essentially independent)
132 %%# approaches can be combined in practice).
133 %%#
134 %%# Assume that you want to write an index for a book which has rather
135 %%# long and complicated \index entries. The first idea that one might have in
136 %%# this connection is to put the various \index commands at the beginning of
137 %%# the document into several macros (one for each \index entry), and to use
138 %%# just these macros in the main text. For example, one might want to write
139 %%# near the beginning of the document commands like
140 %%# \newcommand{\Start}{\index{finish or end}}
141 %%# \newcommand{\End}{\index{finish or end}}
142 %%# and then to use in the main text \Start and \End whenever a reference
143 %%# in the corresponding index to the current place is desired.
144 %%# However, this has two major disadvantages:
145 %%# 1. Unless you are very disciplinary with your macro names, it is easy to
146 %%# forget that \End writes an index entry. So the \End in the main text
147 %%# might be very confusing.
148 %%# 2. You cannot choose short and intuitive macro names for common phrases,
149 %%# because they are usually already reserved by TeX, LaTeX, or some
150 %%# packages.
151 %%#
152 %%# To avoid these problems, one may be very disciplinary and call the
153 %%# involved macros systematically e.g. \GlossaryStart \GlossaryEnd etc.
154 %%# However, this produces terrible long and unreadable macro names in the
155 %%# main text.
156 %%#
157 %%# The implicit macro definitions of "toolbox" provide a more convenient
158 %%# solution. The idea is that you do not use the corresponding macros directly
159 %%# but only implicitly by a call of other macros where your "macro name" is
160 %%# just an argument.
161 %%# Moreover, "toolbox" assists you in writing the corresponding definitions.
162 %%# For example, if you know that you want a set of macros which all expand
163 %%# into something of the form \index{...}, you can give a ``mask'' which
164 %%# contains this form, and you only have to fill in the changing content
165 %%# (similarly as for usual TeX macros with arguments, but the level of
166 %%# abstraction is one step higher).
167 %%# For the above task, you might use the command:
168 %%#
169 %%# \toolboxMakeDef{Glossary}{\index{#1}}
170 %%#
171 %%# The argument `Glossary' serves to distinguish independent definitions
172 %%# (this will become clear later). Its effect visible now is that it
173 %%# determines the name of the following macros which you can use after
174 %%# the above call:
175 %%#
176 %%# \NewGlossary{start-1}{start}
177 %%# \NewGlossary{start-2}{start or beginning}
178 %%# \NewGlossary{end}{finish or end}
179 %%#
180 %%# These command are now similar to the \newcommand definitions explained
181 %%# above. However, there is no name collision with the TeX-internal command
182 %%# \end. Of course, this means that you cannot just write \end in the main
183 %%# text to get the desired index entry. Instead, you have to write the more
184 %%# intuitive commands
185 %%#
186 %%# \Glossary{start-1}
187 %%# \Glossary{start-2}
188 %%# \Glossary{end}
189 %%#
190 %%# (again, the name \Glossary stems from our first call of \toolboxMakeDef).
191 %%# Note that e.g. \Glossary{start-1} expands not only to `start' but
192 %%# actually to \index{start} (because of our first call of \toolboxMakeDef).
193 %%# Note also that you can use symbols like - or numbers which are usually
194 %%# not allowed in TeX macro names.
195 %%#
196 %%# Of course, similarly as for \newcommand, you can also do other things with
197 %%# the macros. For example,
198 %%#
199 %%# \LetGlossary\tempname{end}
200 %%# \NewGlossary*{finish}\tempname
201 %%#
202 %%# will first define \tempname to expand to the same text as \Glossary{end},
203 %%# and then defines a new entry \Glossary{finish} to expand to the same text
204 %%# as \tempname. Hence, the above new lines make the calls \Glossary{end} and
205 %%# \Glossary{finish} equivalent.
206 %%#
207 %%# At the end of your list of \NewGlossary commands, you might want to put
208 %%#
209 %%# \toolboxFreeDef*{Glossary}
210 %%#
211 %%# The purpose of this command is that \NewGlossary cannot be used anymore
212 %%# (unless, of course, you define it again). So you cannot unintentionally
213 %%# add new entries to your glossary list (but you still can use \Glossary{...}
214 %%# to reference to the already produced entries).
215 %%# Moreover, the above command frees some memory which was needed for
216 %%# \NewGlossary to work.
217 %%#
218 %%# If you additionally want to free the memory used by \Glossary, you can use
219 %%#
220 %%# \toolboxFreeDef{Glossary}
221 %%#
222 %%# (without the `*'). This may be necessary, if you want to call again e.g.
223 %%#
224 %%# \toolboxMakeDef{Glossary}{\emph{#1}\index{#1}}
225 %%#
226 %%# (if you have not freed the memory for \Glossary before this repeated call,
227 %%# TeX will complain that \Glossary is already defined).
228 %%#
229 %%# Of course, it is possible to call \toolboxMakeDef with several different
230 %%# names, for example, for \Glossary, \SymbolList etc. Another application
231 %%# might be to use a different command to mark e.g.\ the main occurrence of
232 %%# some index entry or to output additionally the entry into the running text.
233 %%# We do this in the following example which simultaneously
234 %%# demonstrates that the names can also be constructed in another way:
235 %%#
236 %%# \toolboxMakeDef[Ind]{}{\index{#1}}
237 %%# \toolboxMakeDef[Ind]{Main}{\index{#1|textbf}}
238 %%# \toolboxMakeDef{OutInd}{#1}
239 %%#
240 %%# \IndNew{A}{A is a letter}
241 %%# \IndNewMain{A}{A is a letter}
242 %%# \NewOutInd{A}{\textbf{The letter A}\Ind{A}}
243 %%#
244 %%# After the above commands, you can use \Ind{A}, \IndMain{A}, and
245 %%# \OutInd{A} to produce the corresponding \index entry, the "main" \index
246 %%# entry (with a boldface page number), and the text \textbf{The letter A}
247 %%# with an additional entry into the index, respectively.
248 %%# Of course, it might usually be more convenient to define the \Ind and
249 %%# \IndMain" entries simultaneously, e.g. as follows
250 %%#
251 %%# \toolboxMakeDef[Ind]{}{#1}
252 %%# \toolboxMakeDef[Ind]{Main}{#1}
253 %%# \newcommand{\NewStandardInd}[2]{%
254 %%# \IndNew{#1}{\index{#2}}%
255 %%# \IndNewMain{#1}{\index{#2|textbf}}}
256 %%#
257 %%# \NewStandardInd{A}{A is a letter}
258 %%#
259 %%# This approach has the additional advantage that you can define exceptional
260 %%# cases "by hand" (e.g. if you want that for certain "main" index
261 %%# entries the page number is printed with "\textsl" instead of "\textbf").
262
263
264 %%# Since the motivation for implicit definitions now is hopefully clear,
265 %%# let us now describe in detail which commands are provided by "toolbox"
266 %%# for this purpose.
267 %%# As explained in the example, the main generic macro provided to this
268 %%# purpose is \toolboxMakeDef. Its call syntax is as follows:
269 %%#
270 %%# \toolboxMakeDef[Prefix]{Name}{ReplacementMask}
271 %%#
272 %%# (the argument [Prefix] is optional and by default empty).
273 %%# The above command generates new macros
274 %%#
275 %%# \PrefixNewName
276 %%# \PrefixRenewName
277 %%# \PrefixProvideName
278 %%# \PrefixDefName
279 %%# \PrefixLetName
280 %%# \PrefixName
281 %%#
282 %%# which in turn can be called as follows
283 %%#
284 %%# \PrefixNewName{something}{RememberText}
285 %%# \PrefixRenewName{something}{RememberText}
286 %%# \PrefixProvideName{something}{RememberText}
287 %%# \PrefixDefName{something}{RememberText}
288 %%# \PrefixNewName*{something}{\SomeMacro}
289 %%# \PrefixRenewName*{something}{\SomeMacro}
290 %%# \PrefixProvideName*{something}{\SomeMacro}
291 %%# \PrefixDefName*{something}{\SomeMacro}
292 %%# \PrefixLetName{\SomeMacro}{something}
293 %%# \PrefixName{something}
294 %%# \PrefixName*{something}
295 %%#
296 %%# These calls are in a sense similar to the respective commands
297 %%#
298 %%# \newcommand{\something}{RememberText}
299 %%# \renewcommand{\something}{RememberText}
300 %%# \providecommand{\something}{RememberText}
301 %%# \def\something{RememberText}
302 %%# \newcommand{\something}{}\let\something\SomeMacro
303 %%# \renewcommand{\something}{}\let\something\SomeMacro
304 %%# \@ifundefined\something{\let\something\SomeMacro}{}
305 %%# \let\something\SomeMacro
306 %%# \let\SomeMacro{\something}
307 %%# \something
308 %%# \something (but without error if \something is undefined).
309 %%#
310 %%# with the differences already pointed out before:
311 %%# 1. The macro name actually used is not \something. Instead, it is a name
312 %%# which does not conflict with any existing macro (except one
313 %%# generated previously by another \PrefixNewName, but in this case a
314 %%# descriptive error is reported). For this reason, it is not possible to
315 %%# use this macro directly but only indirectly by the call
316 %%# \PrefixName{something} (or with \PrefixLetName).
317 %%# 2. The replacement text is not `RememberText' but determined by
318 %%# ReplacementMask where every occurrence of #1 in ReplacementMask is
319 %%# replaced by RememberText (recall the examples). If you want to have the
320 %%# plain RememberText, use {#1} as ReplacementMask.
321 %%#
322 %%# Since toolbox 4.2 there is another slight difference: The symbol '#'
323 %%# is treated as usual and not as in a macro definition.
324 %%#
325 %%# \toolboxMakeDef gives an error message if the commands
326 %%# \Prefix... are already defined. If you intentionally want to
327 %%# change a previous definition, you have to call the command
328 %%#
329 %%# \toolboxFreeDef[Prefix]{Name}
330 %%#
331 %%# before. The latter not only lets all of the macros \Prefix... be
332 %%# \undefined, but also frees all other memory internally used by the
333 %%# corresponding call of \toolboxMakeDef
334 %%# (note, however, that the above command does not free the
335 %%# memory allocated before by calls of \PrefixNew... - to free the latter,
336 %%# you have to call subsequently e.g.
337 %%#
338 %%# \PrefixNewName*{...}{\undefined}
339 %%#
340 %%% before). There is also the command
341 %%#
342 %%# \toolboxFreeDef*[Prefix]{Name}
343 %%#
344 %%# which acts similarly as \toolboxFreeDef but which does not undefine the
345 %%# two macros \PrefixName and \PrefixLetName.
346 %%#
347
348
349 %%#
350 %%# Fancy optional argument parsing
351 %%# -------------------------------
352
353 %%# This section contains macros which are convenient if you e.g. write a
354 %%# package that contains macros which contain a lot of optional arguments
355 %%# and flags (like "*").
356 %%# Typically, to read such an optional argument or flag, you save
357 %%# the next token with \futurelet and then call a macro which decides what to
358 %%# do with the token read. Thus, a typical use of \futurelet looks like
359 %%#
360 %%# \def\MacroWithOptionalFlag{\futurelet\tokread\myscan}
361 %%#
362 %%# which will define \tokread to be the token *following* the macro
363 %%# \MacroWithOptionalFlag in the token stream and then execute \myscan.
364 %%# In this context, it is not very convenient that you are *forced*
365 %%# to define a macro \myscan: It could be more convenient if you could just
366 %%# write the *content* of \tokread (in braces) into the above definition.
367 %%# You can indeed do this if you replace \futurelet by \toolboxFuturelet:
368 %%#
369 %%# \toolboxFuturelet\token{argument}
370 %%#
371 %%# The call \toolboxFuturelet\token{\command} has precisely the same effect as
372 %%# \futurelet\token\command. The advantage of \toolboxFuturelet is that
373 %%# instead of a single \command one may use also a sequence of commands.
374
375 %%# Let us consider \MacroWithOptionalFlag as above. Assume that the user
376 %%# has called this macro in the form "\MacroWithOptionalFlag*" where the
377 %%# "*" is a flag which should cause your macro to do something slightly
378 %%# different. On some place in your macro definition you will have recognized
379 %%# (e.g. with \futurelet or \toolboxFuturelet) that a "*" is following
380 %%# in the calling sequence. So you now want to execute your action
381 %%# (whatever \MacroWithOptionalFlag is supposed to do).
382 %%# However, if you do not take special care, after this action, TeX will
383 %%# print a "*", because this is the next token on the token stream: \futurelet
384 %%# does not delete any tokens. So you have to "gobble" this token away.
385 %%# A rude way to do this is by using the macro \gobblenext as the last token
386 %%# in you macro which can be defined by
387 %%# \begin{verbatim}
388 %%# \def\gobblenext#1{}\end{verbatim}
389 %%# However, this has two major drawbacks:
390 %%#
391 %%# 1. This works for "*", but not for "{" or space tokens.
392 %%# For space tokens the situation is even worse, since TeX eats spaces
393 %%# around arguments, so sometimes space tokens might unexpectedly
394 %%# disappear.
395 %%# 2. It is not possible in this way to read another argument following
396 %%# the "*": Recall that \gobblenext must be the *last* token in your
397 %%# macro expansion, i.e. you have "lost control" after this call.
398 %%#
399 %%# The solution to these problems is instead of calling \gobblenext to use
400 %%# \toolboxGobbleNext as the last command in your call:
401 %%# You can pass it an argument which describes the action that
402 %%# you want to do *after* gobbling the next token ("*" in the above example)
403 %%# from the token stream. Thus
404 %%#
405 %%# \toolboxGobbleNext{cmd}
406 %%#
407 %%# erases the token following that command from the token stream and
408 %%# then executes cmd. This is similar to
409 %%# \def\toolboxGobbleNext#1#2{#1}
410 %%# with the difference that #2 is considered as a token and that no spaces
411 %%# are eaten.
412 %%# The effect is that e.g. the call
413 %%#
414 %%# Example:
415 %%# \toolboxGobbleNext{\foo}{{arg}
416 %%# is the same as \foo{arg} (the brace "{" is eaten in this example).
417
418 %%# As described earlier, the commands "\futurelet" or "\toolboxFuturelet" can
419 %%# be used to check for optional flags. Frequently you will only want
420 %%# to test for one particular flag and decide the next action on this flag.
421 %%# Of course, you can test the token found with \ifx...\f", but this has the
422 %%# disadvantage that some tokens (e.g. \fi) follow your action, which might
423 %%# be bad (recall that e.g. \toolboxGobbleNext must be the last command of
424 %%# your action, i.e. it would in the above examples not gobble the "*" but
425 %%# the "\fi" which is probably not what you want).
426 %%# The simplest solution is to use the command \toolboxIfNextToken which
427 %%# already has the test included. For example, to test for an optional "[",
428 %%# you can simply write
429 %%#
430 %%# \def\MacroWithOptionalBrace{\toolboxIfNextToken[{\yes}{\no}}
431 %%#
432 %%# and then the call "\MacroWithOptionalBrace[...]" will expand to "\yes[...]"
433 %%# while "\MacroWithOptionalBrace x" will expand to "\no x"
434 %%# (note that the brace is not gobbled - if you want the latter,
435 %%# use "\toolboxIfNextGobbling" described below).
436
437 %%# More precisely, the calling syntax of "\toolboxIfNextToken" is
438 %%#
439 %%# \toolboxIfNextToken{token}{IfPart}{ElsePart}
440 %%#
441 %%# The semantic is the following:
442 %%# If the token following this command is `token', then IfPart is executed,
443 %%# otherwise ElsePart. It is explicitly admissible that `token' is a space.
444 %%# To support further tests, \toolboxToken is \let to the token which follows
445 %%# the command. \toolboxToken is only a temporary token, i.e.
446 %%# it may also be modified by other commands of this package; in particular,
447 %%# you may also freely to modify \toolboxToken.
448 %%# The token \toolboxSpaceToken which is described later may be handy
449 %%# in connection with this command.
450 %%#
451 %%# In contrast to similar LaTeX2e macros much care has been taken
452 %%# that spaces are not eaten. This solves the following problem:
453 %%#
454 %%# Assume that you want to write a macro which should have the calling syntax
455 %%# "\mymacro{arg1}" or "\mymacro{arg1}[arg2]". You will probably implement
456 %%# \mymacro to read the first argument and then to look whether the next
457 %%# token is a "[". If you use the LaTeX2e macro to test for "[",
458 %%# then all spaces until the next non-space token would be gobbled which means
459 %%# that if you would use the LaTeX2e macros for the test, then the call
460 %%# "\mymacro{arg1} Text" would behave like "\mymacro{arg1}Text",
461 %%# i.e. the space is `mysteriously' lost. With the "toolbox" macros this
462 %%# does not happen. The `disadvantage' is that "\mymacro{arg1} [arg2]"
463 %%# is not the same as "\mymacro{arg1}[arg2]" (which is reasonable IMHO).
464 %%#
465 %%# Example:
466 %%#
467 %%# \def\mycmd#1{\toolboxIfNextToken[{\ParseOpt{#1}}{\NoOpt{#1}}}
468 %%# \def\ParseOpt#1[#2]{\OptAtEnd{#1}{#2}}
469 %%#
470 %%# After the above definition, \mycmd{arg} executes \NoOpt{arg} while
471 %%# \mycmd{arg}[optional] executes \OptAtEnd{arg}{optional}
472 %%# We point out once more that in the first call a space following
473 %%# \mycmd{arg} does not vanish (as would be the case if the LaTeX 2e macros
474 %%# would have been used).
475
476 %%# If \toolboxIfNextToken has found the required token, it does *not*
477 %%# gobble that token from the token stream. Of course, you can do this by
478 %%# yourself using the earlier described macro \toolboxGobbleNext. However,
479 %%# it is simpler to use
480 %%#
481 %%# \toolboxIfNextGobbling{token}{IfPart}{ElsePart}
482 %%#
483 %%# This command is analogous to \toolboxIfNextToken with the difference that
484 %%# in the case that the next token is the desired token, it is gobbled before
485 %%# IfPart is executed.
486 %%#
487 %%# Example:
488 %%#
489 %%# \def\myloop{\toolboxIfNextGobbling*\toolboxTokenLoop\toolboxLoop}
490 %%#
491 %%# This makes \myloop*... behave like \toolboxTokenLoop, and
492 %%# \myloop... (without *) behave like \toolboxLoop.
493
494 %%# The following macro is one which you may want to use in connection with
495 %%# LaTeX 2e optional arguments:
496 %%#
497 %%# \toolboxIfEmpty{arg}{IfPart}{ElsePart}
498 %%#
499 %%# The argument is not expand; it is only used to decide whether the
500 %%# {IfPart} or the {ElsePart} will be expanded.
501 %%# For further tests there are more involved macros:
502 %%#
503 %%# \toolboxIfx{arg}\macro{IfPart}{ElsePart}
504 %%#
505 %%# This tests via \ifx whether \def\Macro{arg} would give the definition
506 %%# of \macro.
507 %%#
508 %%# \toolboxIfX{arga}{argb}{IfPart}{ElsePart}
509 %%#
510 %%# This tests whether "arga" and "argb" are the same token sequences.
511 %%# If you want to avoid the \else and \fi commands to avoid certain side
512 %%# effects, you can use instead:
513 %%#
514 %%# \toolboxIfElse{ifcmd}{IfPart}{ElsePart}
515 %%#
516 %%# This is rather analogous to "ifcmd" IfPart \else ElsePart \fi
517 %%# but has everything in this line already eliminated from the tokenlist
518 %%# when IfPart resp. ElsePart are expanded.
519
520 %%#
521 %%# Loops over tokenlists and itemlists
522 %%# -----------------------------------
523
524 %%# \toolboxLoop{items}{action}
525 %%#
526 %%# This calls iteratively "action{#1}", where #1 runs over each item in the
527 %%# argument items. Here, an item is either a token or a group braced by {...}.
528 %%# In the latter case, the braces are lost. Spaces in items are ignored
529 %%# (unless they are braced). It is admissible that \action is not a single
530 %%# macro but instead a sequence of tokens.
531 %%# Examples follow below.
532 %%#
533 %%# The counterintuitive order of arguments is explained by the fact that the
534 %%# typical usage is
535 %%# \expandafter\toolboxLoop\expandafter{\MacroExpandingToItems}{action}
536 %%# which for swapped order of arguments could hardly be written.
537
538 %%# \toolboxLoop is not reentrant i.e. "action" may not expand
539 %%# to something which contains a call to \toolboxLoop. To enable such calls
540 %%# anyway, the command
541 %%#
542 %%# \toolboxLoopName{name}{items}{\action}
543 %%#
544 %%# is provided which is analogous to \toolboxLoop. This is also not reentrant,
545 %%# but in contrast to \toolboxLoop, calls with different `name' arguments can
546 %%# be used independently of each other, i.e. in the `action' part of a
547 %%# \toolboxLoop (or \toolboxLoopName) can be a call to \toolboxLoopName with
548 %%# a *different* `name'.
549 %%# In particular, using a counter in `name' one could easily implement
550 %%# even recursive calls. In this connection, it should be noted that
551 %%# `name' is expanded via \csname ... \endcsname, and so you may use
552 %%# constructs like \the\namecounter there.
553
554 %%# \toolboxTokenLoop{tokens}{\action}
555 %%#
556 %%# This is similar to \toolboxLoop: The command \action\toolboxToken
557 %%# is executed iteratively where \toolboxToken runs over each token in tokens.
558 %%# The important difference is that \toolboxToken is a token (instead of an
559 %%# item). In particular, \toolboxToken runs through every single token
560 %%# including spaces and braces.
561 %%# The token \toolboxSpaceToken which is described later may be handy
562 %%# in connection with this command.
563 %%#
564 %%# Example:
565 %%#
566 %%# \toolboxTokenLoop{Some text}{\kern0.1em}
567 %%#
568 %%# is the similar to "\kern0.1em S\kern0.1em o\kern0.1em m...", i.e. you
569 %%# get wider spacing between the letters of "Some text" (I do not claim that
570 %%# this is typographically a good idea).
571 %%#
572 %%# Note that you do not have to take special care about the space.
573 %%# With \toolboxLoop, you would have to mask the space e.g. with
574 %%#
575 %%# \toolboxLoop{Some{ }text}{\kern0.1em} or
576 %%# \toolboxLoop{Some\toolboxSpace text}{\kern0.1em}
577 %%#
578 %%# In contrast, \toolboxTokenLoop would behave differently here:
579 %%#
580 %%# \toolboxTokenLoop{Some{ }text}{\kern0.1em}
581 %%#
582 %%# would produce \kern0.1em S...\kern0.1em{\kern0.1em <space>\kern0.1em}...
583 %%# because the braces are simply considered as tokens.
584
585 %%# \toolboxTokenLoop is not reentrant. Analogously to \toolboxLoopName,
586 %%# independent versions can be generated by
587 %%#
588 %%# \toolboxTokenName{name}{tokens}{\action}
589
590 %%#
591 %%# Controlled expansion
592 %%# --------------------
593
594 %%# There are some occasions when you want more control over the expansion.
595 %%# E.g. you might want to concatenate the contents of two macros to a
596 %%# further macro or you want to expand a macro by one level but no full
597 %%# expansion. Usually you can get this effects with \expandafter, but if
598 %%# you expand several concatenated tokens in this way you either have to
599 %%# write a lot of \expandafter's or you have to define subsidiary macros
600 %%# that help you to \expandafter certain parts of macros. The macros in
601 %%# this section allow you to do this in the most generic way that I could
602 %%# implement.
603
604 %%# \toolboxDef\macrotodefine{argumentlist}
605 %%#
606 %%# This call is similar to
607 %%# \def\macrotodefine{argumentlist}
608 %%# with two important differences:
609 %%#
610 %%# For \toolboxDef, the argumentlist is expanded precisely by one level.
611 %%# argumentlist may not contain macros with parameters, and spaces on the
612 %%# highest level are ignored. If you want to force a space on a particular
613 %%# place, use the macro \toolboxSpace at this place
614 %%# (which is described later). Contrary to the usual \def, the symbol # is
615 %%# treated as a usual symbol.
616 %%#
617 %%# Example of usage:
618 %%# \toolboxDef\chain{\chain\toolboxSpace\after}
619 %%# This modifies the macro \chain such that a space and the content of the
620 %%# macro \after is appended at the end.
621
622 %%# \toolboxAppend\macrotodefine{arglist}
623 %%#
624 %%# This is equivalent to \toolboxDef\macrotodefine{\macrotodefine arglist}
625 %%#
626
627 %%# \toolboxSurround{ContentBefore}{ContentAfter}\macro
628 %%#
629 %%# This redefines \macro such that ContentBefore is put at the beginning
630 %%# and ContentAfter after the definition of \macro. So this is equivalent to
631 %%# \def\macro{ContentBefore * ContentAfter}
632 %%# where * is the old content of \macro. It is required that \macro is a
633 %%# usual macro without any arguments. If you want to patch more complicated
634 %%# macros, use the patch.doc package instead.
635 %%# The order of the arguments may appear strange, but it is convenient if
636 %%# ContentBefore or ContentAfter are macros which should be expanded with
637 %%# \expandafter.
638
639 %%# There is some subsidiary macro used in the implementation of the above
640 %%# macros which might be useful also in some other situations:
641 %%#
642 %%# \toolboxTokDef{argumentlist}\macrotodefine
643 %%#
644 %%# This call is similar to
645 %%# \def\macrotodefine{argumentlist}
646 %%# with the difference that the symbol # is stored as such.
647 %%# The order of the arguments has been swapped in order to simplify the
648 %%# application of \expandafter to the argumentlist.
649
650 %%#
651 %%# Searching, splitting, and replacing
652 %%# ----------------------------------
653
654 %%# \toolboxSplitAt{argument}{search}{\beforestring}{\afterstring}
655 %%#
656 %%# Here, \beforestring and \afterstring are arbitrary macro names,
657 %%# and search and argument are any sequences of tokens (which are in
658 %%# the following considered as `strings').
659 %%#
660 %%# This call scans the string `argument' for the first occurrence of `search'.
661 %%# The macros \beforestring and \afterstring are defined correspondingly
662 %%# such that \beforestring expands to the part before the first occurrence,
663 %%# and \afterstring to the part following the first occurrence.
664 %%# If `search' does not occur in `argument', \beforestring is defined to
665 %%# `argument', and \afterstring is \let \undefined.
666 %%#
667 %%# If \beforestring or \afterstring had already been defined before the
668 %%# call, the previous definition is tacitly overridden.
669 %%# It is explicitly allowed that \beforestring and \afterstring are the
670 %%# same names. In this case, the result has the meaning of \afterstring.
671 %%#
672 %%# It is guaranteed that braces {...} are *not* lost in `argument'.
673 %%# However, `search' may not contain any braces, and `argument' may contain
674 %%# only matching pairs of braces. Moreover, occurrences of `search' within a
675 %%# pair of braces in `argument' are not recognized.
676 %%#
677 %%# (The order of the arguments has been chosen in order to simplify the
678 %%# use of \expandafter).
679 %%#
680 %%# There are some restrictions for the strings in search. For example,
681 %%# the symbol '#' is not allowed.
682 %%#
683 %%# In the above call, the arguments may not run over several paragraphs.
684 %%# If you want the latter, you have to use the alternative call
685 %%#
686 %%# \toolboxSplitAt*{argument}{search}{\beforestring}{\afterstring}
687 %%#
688 %%# Example of usage:
689 %%#
690 %%# \def\examplemacro#1{\toolboxSplitAt{#1}{@}\testme\testme
691 %%# \ifx\testme\undefined
692 %%# ... (do this when #1 contains no `@' token)
693 %%# \fi}
694 %%#
695
696 %%# \toolboxMakeSplit{search}{command}
697 %%#
698 %%# If \toolboxSplitAt should be used several times with the same search
699 %%# string, it is much more effective to use the above call: This call
700 %%# defines a new macro \command (the name is determined by the second argument
701 %%# of \toolboxMakeSplit) which can be called in the form
702 %%#
703 %%# \command{argument}{\beforestring}{\afterstring}
704 %%#
705 %%# and which has the analogous meaning as \toolboxSplitAt (the argument
706 %%# {search} is implicitly fixed and taken from the call of
707 %%# \toolboxMakeSplit).
708 %%# It is explicitly admissible that the above macro \toolboxMakeSplit is
709 %%# used with an already existing command name. In this case, the previous
710 %%# definition of \command is tacitly overridden.
711 %%#
712 %%# The command created by \toolboxMakeSplit does not accept arguments which
713 %%# run over several paragraphs. If you want the latter, you have to create
714 %%# this command by the alternative call
715 %%#
716 %%# \toolboxMakeSplit*{search}{command}
717
718 %%#
719 %%# The command
720 %%# \toolboxFreeSplit{command}
721 %%# frees the memory used by a previous \toolboxMakeSplit (and lets \command
722 %%# again be undefined).
723
724 %%# The command
725 %%# \toolboxReplace{search}{replace}\macro
726 %%# replaces in \macro all occurences of {search} by {replace}.
727 %%# The same matches are found as in \toolboxSplitAt.
728 %%# If you need to search for the same text several times, it is faster
729 %%# to use the command
730 %%# \toolboxReplaceSplit{replace}\SplitCmd\macro
731 %%# where \SplitCmd is a command previously generated with \toolboxMakeSplit*
732 %%# according to your search string. (You could also use \toolboxMakeSplit
733 %%# to generate \SplitCmd, but then \macro should not contain any \par's).
734
735 %%#
736 %%# Redefinition of macros
737 %%# ----------------------
738
739 %%# \toolboxMakeHarmless{\macro}
740 %%#
741 %%# The above call redefines \macro such that it expands to an ASCII text
742 %%# containing the previous definition of \macro (i.e. the catcodes of \macro
743 %%# are changed).
744
745 %%# \toolboxDropBrace\variable
746 %%#
747 %%# drops possible outer braces in \variable. More precisely,
748 %%# if \variable expands to {content}, then \variable is redefined to
749 %%# content (without braces). Otherwise, nothing happens.
750
751 %%#
752 %%# \toolboxIf\comparison{DefinitionCommand}{\macro}...
753 %%#
754 %%# The above command allows conditional definitions.
755 %%# Here, {DefinitionCommand} is either \def, {\long\def}, \let, or some
756 %%# similar command like the LaTeX \newcommand. If the test
757 %%# \ifx\comparison\macro evaluates positive, then \macro is defined
758 %%# correspondingly. Otherwise, \macro is not changed.
759 %%#
760 %%# Examples:
761 %%#
762 %%# \toolboxIf\undefined\def\macro{....}
763 %%# \toolboxIf\undefined\let\macro...
764 %%# \toolboxIf\undefined{\long\def}\macro{....}
765 %%# \toolboxIf\undefined\newcommand{\macro}{....}
766 %%#
767 %%# are similar to \def\macro{...} resp. \let\macro... resp.
768 %%# \long\def\macro{...} resp. \newcommand{\macro}{...} with the difference
769 %%# that \macro is not changed if it was already defined.
770 %%# In this sense, \toolboxIf is a more flexible variant of \providecommand.
771 %%#
772
773 %%# \toolboxNewiftrue{name} or \toolboxNewiffalse{name}
774 %%#
775 %%# If the command \ifname was already introduced with \newif, then
776 %%# nothing happens. Otherwise \ifname is introduced similarly to
777 %%# \newif\ifname and set to `true' respectively `false'.
778 %%# In contrast to the corresponding command in TeX or LaTeX 2.09, this macro
779 %%# is not \outer!
780
781 %%# \toolboxNewifTrue{name} or \toolboxNewifFalse{name}
782 %%#
783 %%# are similar to \toolboxNewiftrue{name} and \toolboxNewiffalse{name},
784 %%# respectively, with the difference that \ifname is set unconditionally
785 %%# to `true' respectively `false'.
786
787 %%#
788 %%# Concatenated macro names
789 %%# ------------------------
790
791 %%# \toolboxLet\variable{macroname}
792 %%#
793 %%# The above command is analogous to \let\variable\macroname with the
794 %%# difference that macroname can also contain other tokens like numbers
795 %%# (it is obtained via \csname). Some converse to this command is
796 %%#
797 %%# \toolboxWithNr {number}\cmd{macro}
798 %%#
799 %%# which translates into \cmd\macronumber (here, `macro' and `number'
800 %%# are just concatenated and evaluated via \csname).
801 %%# Examples:
802 %%# \toolboxWithNr 1\let{name}\toolboxEmpty
803 %%# This is the same as \let\name1\toolboxEmpty
804 %%# (but such that \name1 is considered as a name, not as \name 1)
805 %%# \toolboxWithNr {10}\def{name}{Foo}
806 %%# This corresponds analogously to \def\name10{Foo}.
807 %%# \toolboxLet \mymacro{name\the\mycount}
808 %%# This is similar to \let\mymacro\namexx where xx is the content
809 %%# of the counter \mycount.
810
811 %%#
812 %%# Various
813 %%# -------
814
815 %%# The following macros have equivalents in most formats (like LaTeX2e).
816 %%# However, we do not want to rely too much on these formats, so we provide
817 %%# our own definitions.
818 %%# The macro
819 %%# \toolboxEmpty
820 %%# expands to nothing (usually, this is the same as \empty).
821 %%# Similarly, the macro
822 %%# \toolboxSpace
823 %%# expands to a space symbol (usually, this is the same as \space).
824 %%# The token
825 %%# \toolboxSpaceToken
826 %%# is \let a space token (usually, this is the same as \@sptoken).
827 %%# This token is convenient in tests of tokens
828 %%# (because it is hard to get a space there which is not eaten by the TeX
829 %%# parser, although sometimes also constructions like
830 %%# \expandafter\ifx\toolboxSpace\token can be used).
831 %%# Also the macros
832 %%# \toolboxFirstOfTwo
833 %%# \toolboxSecondOfTwo
834 %%# are provided which read two arguments and return only the first
835 %%# respectively second argument (usually, this is the same as
836 %%# \@firstoftwo respectively \@secondoftwo). Similarly,
837 %%# \toolboxGobbleArg{argument}
838 %%# just reads its argument and expands to nothing.
839
840
841
842 % This is the end of the ascii documentation
843 %</asciidocu>
844 %\fi\catcode\#6\relax
845 %
846 % \iffalse
847 %<*metainfo>
848 % \fi
849
850 % \def\basename{toolbox}
851
852 %% \CharacterTable
853 %% {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
854 %% 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
855 %% Digits \0\1\2\3\4\5\6\7\8\9
856 %% Exclamation \! Double quote \" Hash (number) \#
857 %% Dollar \$ Percent \% Ampersand \&
858 %% Acute accent \' Left paren \( Right paren \)
859 %% Asterisk \* Plus \+ Comma \,
860 %% Minus \- Point \. Solidus \/
861 %% Colon \: Semicolon \; Less than \<
862 %% Equals \= Greater than \> Question mark \?
863 %% Commercial at \@ Left bracket \[ Backslash \\
864 %% Right bracket \] Circumflex \^ Underscore \_
865 %% Grave accent \` Left brace \{ Vertical bar \|
866 %% Right brace \} Tilde \~}
867
868 % \CheckSum{736}
869
870 % \iffalse
871 % \RecordChanges
872 % \fi
873 % \def\mypar{}
874 % \def\ChangesTab{}\let\orichanges\changes
875 % \def\changes#1#2#3{\orichanges{#1}{#2}{#3}
876 % \expandafter\def\expandafter\ChangesTab\expandafter{\ChangesTab
877 % \item[v#1 {\mdseries(\emph{#2})}] {#3.}}}
878 % \newcommand{\cmdcite}[1]{\texttt{\textbackslash#1}}
879 % \newcommand{\bracemeta}[1]{\texttt{\{}\meta{#1}\texttt{\}}}
880 % \newcommand{\cmdmeta}{\textbackslash\meta}
881
882 % \changes{5.1}{2013/11/26}{Update email, add license. Date/version remains the
883 % same since only commments and documentation are modified}
884 % \changes{5.1}{2004/04/29}{Added \cmdcite{toolboxReplace},
885 % \cmdcite{toolboxReplaceSplit}. Some corrections in the documentation.
886 % Added some forgotten \cmdcite{long}'s in the code.}
887 % \changes{4.4}{2003/10/07}{Added \cmdcite{toolboxIfEmpty},
888 % \cmdcite{toolboxIfx}, \cmdcite{toolboxIfX}, \cmdcite{toolboxIfElse}.
889 % Some corrections in the documentation}
890 % \changes{4.3}{2002/09/27}{Major enhancements in documentation: Added lots
891 % of examples and explanation about typical applications.
892 % Bugfix in \cmdcite{toolboxMakeDef}:
893 % \cmdmeta{Prefix}\texttt{Provide}\meta{Name} now behaves like
894 % \cmdcite{providecommand} as documented. The old meaning is now called
895 % \cmdmeta{Prefix}\texttt{Def}\meta{Name}.
896 % Introduced \cmdcite{toolboxGobbleArg}}
897 % \changes{4.2}{2001/09/26}{Treating \texttt{\#} properly now also in
898 % \cmdcite{toolboxMakeDef}}
899 % \changes{4.1}{2001/09/24}{Took more care of treating \texttt{\#} properly
900 % when this symbol occurs in arguments of certain macros (the treatment is
901 % not completely downward compatible; for this reason the major release
902 % number has been changed). For this reason,
903 % also the new macro \cmdcite{toolboxTokDef} is provided. I thank
904 % David Kastrup \texttt{<[email protected]>}
905 % for pointing out this problem (and a solution) to me}
906 % \changes{3.3}{2001/08/19}{Eliminated a bug in \cmdcite{toolboxMakeSplit*}}
907 % \changes{3.2}{2001/05/08}{Eliminated a serious bug in \cmdcite{toolboxIf}.
908 % Due to this bugfix, the usage of \cmdcite{toolboxIf} had to be slightly
909 % restricted}
910 % \changes{3.1}{2001/05/06}{Major advantage: \cmdcite{toolboxMakeDef}
911 % implemented.\mypar
912 % Reimplemented \cmdcite{newif} (apparently by mistake, this had been
913 % declared as \cmdcite{outer} in \TeX\ and \LaTeX 2.09 which caused an
914 % error during loading of \texttt{toolbox.sty}).
915 % For this reason, also \cmdcite{toolboxNewifTrue} and
916 % \cmdcite{toolboxNewifFalse} were introduced}
917 % \changes{2.1}{2001/04/30}{Introduced \cmdcite{toolboxIf},
918 % \cmdcite{toolboxAppend}, and \cmdcite{toolboxSurround}}
919 % \changes{2.0}{2001/04/08}{Many major enhancements and new tools:
920 % Added section (and corresponding macros)
921 % for fancy optional arguments. Made \cmdcite{toolboxLoop} semi-reentrant by
922 % introducing \cmdcite{toolboxLoopName}.
923 % Added \cmdcite{toolboxTokenLoop} and friends.
924 % Added \cmdcite{toolboxSpaceToken}.
925 % Made many macros \cmdcite{long} and added \cmdcite{long} versions
926 % of \cmdcite{toolboxSplitAt} and \cmdcite{toolboxMakeSplit}}
927 % \changes{1.0}{2001/03/29}{First release}
928 %
929 % \iffalse
930 %
931 % The following part is the code needed to compile the documentation.
932 % We do some trickery here, because we want that this file here could be used
933 % for *both*: Compiling the documentation *and* as `toolbox.sty'
934 % (if really required).
935 % Everything between the lines %<*driver> and %</driver>
936 % goes to the file `toolbox.tex'.
937 %
938 % \fi
939 \ifcat @a% If this test is positive, then `@' has letter catcode which means
940 % that this file is loaded as a style file (or as described in the
941 % install section of the documentation).
942 \def\TemporaryDummy{}
943 \else\long\def\TemporaryDummy{%
944 %
945 %
946 % \iffalse
947 %</metainfo>
948 %<*driver>
949 \documentclass{ltxdoc}
950 \OnlyDescription%% Comment this out, or
951 %%\AlsoImplementation%% uncomment this line, if you want to see the source.
952
953 %% If you want an index, uncomment one of the following lines.
954 %% After running latex a first time, you have to use
955 %% makeindex -s gind.ist toolbox
956 %% Then run latex again.
957 %%\CodelineIndex% comment this out if you want an index referring to codelines
958 %%\PageIndex% comment this out if you want an index referring to pages
959 %%\OldMakeindex% uncomment this line, if your MakeIndex is pre-v2.9
960
961 \setlength\hfuzz{15pt}
962 \hbadness=7000
963 \begin{document}
964 \DocInput{toolbox.dtx}
965 \end{document}
966 %</driver>
967 %<*metainfo>
968 % \fi
969 }
970 \fi\TemporaryDummy\let\TemporaryDummy\undefined
971 %
972 % \iffalse
973 % Personal macros used for the doc utility:
974 % \fi
975 % \MakeShortVerb{"}
976 % \newcommand{\filecite}[1]{\texttt{#1}}
977 % \newcommand{\nocomment}{}
978 % \newcommand{\myspace}{\texttt{\textvisiblespace}}
979 % \parindent0pt
980
981 % \title{The \texttt{toolbox} package\thanks
982 % {This package has version number \fileversion{}, last revised \filedate.
983 % The package may be distributed and/or modified under the conditions of the
984 % LaTeX Project Public License, either version 1.3c of this license or (at
985 % your option) any later version. The latest version of this license is in
986 % \texttt{http://www.latex-project.org/lppl.txt}, and version 1.3c or later
987 % is part of all distributions of LaTeX version 2005/12/01 or later.}}
988 % \author{Martin V\"ath\relax
989 %\thanks{\texttt{[email protected]}}
990 %{}\thanks{The author thanks
991 %David Kastrup \texttt{<[email protected]>}.
992 %}}
993 % \date{\docdate}
994 % \maketitle\sloppy
995
996 % \begin{abstract}
997 % The \TeX\ programmer's toolbox; enhanced version.
998 % This package provides some macros which are convenient for writing
999 % indices, glossaries, or other macros. It contains macros which support
1000 % \begin{itemize}
1001 % \item implicit macros -- a useful supplement to \cmdcite{index} or
1002 % \texttt{varindex} for writing glossaries or indices.
1003 % \item fancy optional arguments
1004 % \item loops over tokenlists and itemlists
1005 % \item searching, splitting, and replacing
1006 % \item controlled expansion
1007 % \item redefinition of macros
1008 % \item concatenated macro names
1009 % \end{itemize}
1010 % \end{abstract}
1011
1012 % You may copy this package freely, as long as you distribute only unmodified
1013 % and complete versions.
1014
1015 % \tableofcontents
1016
1017 % \section{Changes}
1018 %
1019 % \begin{description}
1020 % \def\mypar{\par}\ChangesTab
1021 % \end{description}
1022 %
1023
1024 % \section{Installation}
1025
1026 % This package was tested with \TeX, \LaTeX 2.09, and \LaTeXe, and it
1027 % should actually run with all other \TeX\ formats.
1028
1029 % To use \filecite{toolbox}, you have to put the file \filecite{toolbox.sty}
1030 % in a path where \TeX\ looks for its input files. The \TeX\ documents using
1031 % \filecite{toolbox} need the following modifications in their header:
1032 %
1033 % \begin{itemize}
1034 % \item If you use \LaTeXe, put in the preamble the command
1035 % \begin{verbatim}
1036 % \usepackage{toolbox}\end{verbatim}
1037 %
1038 % \item If you use \LaTeX 2.09, use \filecite{toolbox} as a style option, e.g.\
1039 % \begin{verbatim}
1040 % \documentstyle[toolbox]{article}\end{verbatim}
1041 % or
1042 % \begin{verbatim}
1043 % \documentstyle[toolbox,12pt]{article}\end{verbatim}
1044 %
1045 % \item If you use some other (non-\LaTeX) format, you will probably have to
1046 % insert a line like
1047 % \begin{verbatim}
1048 % \catcode`\@=11\input toolbox.sty\catcode`\@=12\relax\end{verbatim}
1049 %
1050 % \end{itemize}
1051 %
1052 % The only \LaTeX-specific commands used in \filecite{toolbox.sty} are:
1053 %
1054 % \begin{itemize}
1055 % \item "\newcommand" (used only in the form "\newcommand{"\meta{command}"}{}"
1056 % to ensure that \meta{command} was not defined before)
1057 % \item "\ProvidesPackage"
1058 % \item "\typeout"
1059 % \end{itemize}
1060 % The above commands are used only if they are defined.
1061
1062 % \section{Description of the macros}
1063 %
1064 % General remark: Many macros could appear in several sections.
1065 % For example, "\toolboxMakeDef" and "\toolboxSourround" might be considered
1066 % as macros which support redefinitions of macros. However, we put them
1067 % in different sections which perhaps explain better their nature.
1068 %
1069 % \subsection{Implicit macro definitions}
1070 %
1071 % What we mean by implicit macro definitions is probably best explained by
1072 % the following examples which show the intended usage:\par\bigskip
1073 %
1074 % (In the following examples, we always refer to the "\index" command. Note
1075 % that it may be more convenient to use for indices the \filecite{varindex}
1076 % package in addition -- the documentation of \filecite{varindex}
1077 % (release 2.3 or newer) gives additional hints and examples how these two
1078 % (essentially independent) approaches can be combined in practice).
1079 % \par\bigskip
1080 %
1081 % Assume that you want to write an index for a book which has rather
1082 % long and complicated "\index" entries. The first idea that one might have in
1083 % this connection is to put the various "\index" commands at the beginning of
1084 % the document into several macros (one for each "\index" entry), and to use
1085 % just these macros in the main text. For example, one might want to write
1086 % near the beginning of the document commands like
1087 % \begin{verbatim}
1088 % \newcommand{\Start}{\index{finish or end}}
1089 % \newcommand{\End}{\index{finish or end}}\end{verbatim}
1090 % and then to use in the main text "\Start" and "\End" whenever a reference
1091 % in the corresponding index to the current place is desired.
1092 % However, this has two major disadvantages:
1093 % \begin{enumerate}
1094 % \item It is easy to forget that "\End" writes an index entry.
1095 % So the macro "\End" in the main text might be very confusing.
1096 % \item You cannot choose short and intuitive macro names for common phrases,
1097 % because they are usually already reserved by \TeX, \LaTeX, or some
1098 % packages. For example, "\end" could not be used.
1099 % \end{enumerate}
1100 % To avoid these problems, one may be very disciplinary and call the
1101 % involved macros systematically e.g.\ "\GlossaryStart" "\GlossaryEnd" etc.
1102 % However, this produces terrible long and unreadable macro names in the main
1103 % text.\par\bigskip
1104 % The implicit macro definitions of \filecite{toolbox} provide a more
1105 % convenient solution.
1106 % The idea is that you do not use the corresponding macros directly but only
1107 % implicitly by a call of other macros where your ``macro name'' is just an
1108 % argument.\par
1109 % Moreover, \filecite{toolbox} assists you in writing the corresponding
1110 % definitions.
1111 % For example, if you know that you want a set of macros which all expand
1112 % into something of the form "\index{...}", you can give a ``mask'' which
1113 % contains this form, and you only have to fill in the changing content
1114 % (similarly as for usual \TeX\ macros with arguments, but the level of
1115 % abstraction is one step higher).
1116 % For the above task, you might use the command:
1117 % \begin{verbatim}
1118 % \toolboxMakeDef{Glossary}{\index{#1}}\end{verbatim}
1119 %
1120 % The argument "Glossary" serves to distinguish independent definitions
1121 % (this will become clear later). Its effect visible now is that it
1122 % determines the name of the following macros which you can use after
1123 % the above call:
1124 % \begin{verbatim}
1125 % \NewGlossary{start-1}{start}
1126 % \NewGlossary{start-2}{start or beginning}
1127 % \NewGlossary{end}{finish or end}\end{verbatim}
1128 %
1129 % These command are now similar to the "\newcommand" definitions explained
1130 % above. However, there is no name collision with the \TeX-internal command
1131 % "\end". Of course, this means that you cannot just write "\end" in the main
1132 % text to get the desired index entry. Instead, you have to write the more
1133 % intuitive commands
1134 % \begin{verbatim}
1135 % \Glossary{start-1}
1136 % \Glossary{start-2}
1137 % \Glossary{end}\end{verbatim}
1138 % (again, the name "\Glossary" stems from our first call of "\toolboxMakeDef").
1139 % Note that e.g.\ "\Glossary{start-1}" expands not only to "start" but
1140 % actually to "\index{start}" (because of our first call of
1141 % "\toolboxMakeDef").\par
1142 % Note also that you can use symbols like ``-'' or numbers which are
1143 % usually not allowed in \TeX\ macro names.
1144 %
1145 % Of course, similarly as for "\newcommand", you can also do other things with
1146 % the macros. For example,
1147 % \begin{verbatim}
1148 % \LetGlossary\tempname{end}
1149 % \NewGlossary*{finish}\tempname\end{verbatim}
1150 %
1151 % will first define "\tempname" to expand to the same text as "\Glossary{end}",
1152 % and then defines a new entry "\Glossary{finish}" to expand to the same text
1153 % as "\tempname". Hence, the above two lines make the calls "\Glossary{end}"
1154 % and "\Glossary{finish}" equivalent.
1155 %
1156 % At the end of your list of "\NewGlossary" commands, you might want to put
1157 % \begin{verbatim}
1158 % \toolboxFreeDef*{Glossary}\end{verbatim}
1159 %
1160 % The purpose of this command is that "\NewGlossary" cannot be used anymore
1161 % (unless, of course, you define it again). So you cannot unintentionally
1162 % add new entries to your glossary list (but you still can use "\Glossary{...}"
1163 % to reference to the already produced entries).
1164 % Moreover, the above command frees some memory which was needed for
1165 % "\NewGlossary" to work.
1166 %
1167 % If you additionally want to free the memory used by "\Glossary", you can use
1168 % \begin{verbatim}
1169 % \toolboxFreeDef{Glossary}\end{verbatim}
1170 %
1171 % (without the "*"). This may be necessary, if you want to call again e.g.
1172 % \begin{verbatim}
1173 % \toolboxMakeDef{Glossary}{\emph{#1}\index{#1}}\end{verbatim}
1174 %
1175 % (if you have not freed the memory for "\Glossary" before this repeated call,
1176 % \TeX\ will complain that "\Glossary" is already defined).\par\smallskip
1177 %
1178 % Of course, it is possible to call "\toolboxMakeDef" with several different
1179 % names, for example, for "\Glossary", "\SymbolList" etc. Another application
1180 % might be to use a different command to mark e.g.\ the main occurrence of
1181 % some index entry or to output additionally the entry into the running text.
1182 % We do this in the following example which simultaneously
1183 % demonstrates that the names can also be constructed in another way:
1184 % \begin{verbatim}
1185 % \toolboxMakeDef[Ind]{}{\index{#1}}
1186 % \toolboxMakeDef[Ind]{Main}{\index{#1|textbf}}
1187 % \toolboxMakeDef{OutInd}{#1}
1188 %
1189 % \IndNew{A}{A is a letter}
1190 % \IndNewMain{A}{A is a letter}
1191 % \NewOutInd{A}{\textbf{The letter A}\Ind{A}}\end{verbatim}
1192 % After the above commands, you can use "\Ind{A}", "\IndMain{A}", and
1193 % "\OutInd{A}" to produce the corresponding "\index" entry, the ``main''
1194 % "\index" entry (with a fat page number), and the text \textbf{The letter A}
1195 % with an additional entry into the index, respectively.
1196 % Of course, it might usually be more convenient to define the "\Ind" and
1197 % "\IndMain" entries simultaneously, e.g.\ by the commands
1198 % \begin{verbatim}
1199 % \toolboxMakeDef[Ind]{}{#1}
1200 % \toolboxMakeDef[Ind]{Main}{#1}
1201 % \newcommand{\NewStandardInd}[2]{%
1202 % \IndNew{#1}{\index{#2}}%
1203 % \IndNewMain{#1}{\index{#2|textbf}}}
1204 %
1205 % \NewStandardInd{A}{A is a letter}\end{verbatim}
1206 % This approach has the additional advantage that you can define exceptional
1207 % cases ``by hand'' (e.g.\ if you want that for certain ``main'' index
1208 % entries the page number is printed with "\textsl" instead of "\textbf").
1209 % \bigskip
1210 %
1211 % Since the motivation for implicit definitions now is hopefully clear,
1212 % let us now describe in detail which commands are provided by
1213 % \filecite{toolbox} for this purpose.
1214 % As explained in the example, the main generic macro provided to this
1215 % purpose is \DescribeMacro{\toolboxMakeDef}"\toolboxMakeDef".
1216 % Its call syntax is as follows:
1217 % \begin{quote}
1218 % "\toolboxMakeDef["\meta{Prefix}"]"\bracemeta{Name}\relax
1219 %\bracemeta{Replacement mask}
1220 % \end{quote}
1221 % (the argument "["\meta{Prefix}"]" is optional and by default empty).
1222 % The above command generates new macros
1223 %
1224 % \begin{quote}
1225 % \cmdmeta{Prefix}"New"\meta{Name}\\
1226 % \cmdmeta{Prefix}"Renew"\meta{Name}\\
1227 % \cmdmeta{Prefix}"Provide"\meta{Name}\\
1228 % \cmdmeta{Prefix}"Def"\meta{Name}\\
1229 % \cmdmeta{Prefix}"Let"\meta{Name}\\
1230 % \cmdmeta{Prefix}\meta{Name}
1231 % \end{quote}
1232 % which in turn can be called as follows:
1233 % \begin{quote}
1234 % \cmdmeta{Prefix}"New"\meta{Name}\bracemeta{something}\relax
1235 %\bracemeta{text to remember}\\
1236 % \cmdmeta{Prefix}"Renew"\meta{Name}\bracemeta{something}\relax
1237 %\bracemeta{text to remember}\\
1238 % \cmdmeta{Prefix}"Provide"\meta{Name}\bracemeta{something}\relax
1239 %\bracemeta{text to remember}\\
1240 % \cmdmeta{Prefix}"Def"\meta{Name}\bracemeta{something}\relax
1241 %\bracemeta{text to remember}\\
1242 % \cmdmeta{Prefix}"New"\meta{Name}"*"\bracemeta{something}\relax
1243 %{\cmdmeta{SomeMacro}}\\
1244 % \cmdmeta{Prefix}"Renew"\meta{Name}"*"\bracemeta{something}\relax
1245 %{\cmdmeta{SomeMacro}}\\
1246 % \cmdmeta{Prefix}"Provide"\meta{Name}"*"\bracemeta{something}\relax
1247 %{\cmdmeta{SomeMacro}}\\
1248 % \cmdmeta{Prefix}"Def"\meta{Name}"*"\bracemeta{something}\relax
1249 %{\cmdmeta{SomeMacro}}\\
1250 % \cmdmeta{Prefix}"Let"\meta{Name}{\cmdmeta{SomeMacro}}\bracemeta{something}\\
1251 % \cmdmeta{Prefix}\meta{Name}\bracemeta{something}\\
1252 % \cmdmeta{Prefix}\meta{Name}"*"\bracemeta{something}
1253 % \end{quote}
1254 % These calls are in a sense similar to the respective commands
1255 % \begin{quote}
1256 % "\newcommand{"\cmdmeta{something}"}"\bracemeta{text to remember}\\
1257 % "\renewcommand{"\cmdmeta{something}"}"\bracemeta{text to remember}\\
1258 % "\providecommand{"\cmdmeta{something}"}"\bracemeta{text to remember}\\
1259 % "\def"\cmdmeta{something}\bracemeta{text to remember}\\
1260 % "\newcommand{"\cmdmeta{something}"}{}"\relax
1261 %"\let"\cmdmeta{something}\cmdmeta{SomeMacro}\\
1262 % "\renewcommand{"\cmdmeta{something}"}{}"\relax
1263 %"\let"\cmdmeta{something}\cmdmeta{SomeMacro}\\
1264 % "\@ifundefined"\bracemeta{something}"{\let"\relax
1265 %\cmdmeta{something}\cmdmeta{SomeMacro}"}{}"\\
1266 % "\let"\cmdmeta{something}\cmdmeta{SomeMacro}\\
1267 % "\let"\cmdmeta{SomeMacro}{\cmdmeta{something}}\\
1268 % \cmdmeta{something}\\
1269 % \cmdmeta{something} (but without error if \cmdmeta{something} is undefined)
1270 % \end{quote}
1271 % with the differences already pointed out before:
1272 % \begin{enumerate}
1273 % \item The macro name actually used is not \cmdmeta{something}.
1274 % Instead, it is a name which does not conflict with any existing macro
1275 % (except one generated previously by another \cmdmeta{Prefix}New\meta{Name},
1276 % but in this case a descriptive error is reported).\par
1277 % For this reason, it is not possible to use this macro directly but only
1278 % indirectly by the call \cmdmeta{Prefix}\meta{Name}\bracemeta{something}
1279 % (or with \cmdmeta{Prefix}Let\meta{Name}).
1280 % \item The replacement text is not \meta{text to remember} but determined by
1281 % \meta{Replacement Mask} where every occurrence of "#1" in
1282 % \meta{Replacement Mask} is replaced by \meta{text to remember}
1283 % (recall the examples). If you want to have the plain
1284 % \meta{text to remember}, use "{#1}" as \meta{Replacement Mask}.
1285 % \end{enumerate}
1286 % Since \filecite{toolbox~4.2} there is another slight difference:
1287 % The symbol "#" is treated as usual and not as in a macro definition.\par
1288 %
1289 % "\toolboxMakeDef" gives an error message if the commands
1290 % \cmdmeta{Prefix}"..." are already defined. If you intentionally want to
1291 % change a previous definition, you have to call the command
1292 %
1293 % \begin{quote}
1294 % \DescribeMacro{\toolboxFreeDef}
1295 % "\toolboxFreeDef["\meta{Prefix}"]"\bracemeta{Name}
1296 % \end{quote}
1297 % before. The latter not only lets all of the macros \cmdmeta{Prefix}"..." be
1298 % "\undefined", but also frees all other memory internally used by the
1299 % corresponding call of "\toolboxMakeDef"
1300 % (note, however, that the above command does not free the
1301 % memory allocated before by calls of \cmdmeta{Prefix}"New..." -- to free the
1302 % latter, you have to call subsequently e.g.
1303 % \begin{quote}
1304 % \cmdmeta{Prefix}"New"\meta{Name}"*{"$\ldots$"}{\undefined}"
1305 % \end{quote}
1306 % before). There is also the command
1307 % \begin{quote}
1308 % "\toolboxFreeDef*["\meta{Prefix}"]"\bracemeta{Name}
1309 % \end{quote}
1310 % which acts similarly as "\toolboxFreeDef" but which does not undefine the
1311 % two macros \cmdmeta{Prefix}\meta{Name} and \cmdmeta{Prefix}"Let"\meta{Name}.
1312 %
1313
1314 % \subsection{Fancy optional argument parsing}
1315 %
1316 % This section contains macros which are convenient if you e.g.\ write a
1317 % package that contains macros which contain a lot of optional arguments
1318 % and flags (like "*").
1319 % Typically, to read such an optional argument or flag, you save
1320 % the next token with "\futurelet" and then call a macro which decides what to
1321 % do with the token read. Thus, a typical use of "\futurelet" looks like
1322 % \begin{verbatim}
1323 % \def\MacroWithOptionalFlag{\futurelet\tokread\myscan}\end{verbatim}
1324 % which will define "\tokread" to be the token \emph{following} the macro
1325 % "\MacroWithOptionalFlag" in the token stream and then execute "\myscan".
1326 % In this context, it is not very convenient that you
1327 % are \emph{forced} to define a macro "\myscan": It could be more convenient
1328 % if you could just write the \emph{content} of "\tokread" (in braces) into
1329 % the above definition. You can indeed do this if you replace "\futurelet"
1330 % by \DescribeMacro{\toolboxFuturelet}"\toolboxFuturelet":
1331 %
1332 % \begin{quote}
1333 % "\toolboxFuturelet\token"\bracemeta{argument}
1334 % \end{quote}
1335 %
1336 % The call "\toolboxFuturelet\token{\command}" has precisely the same
1337 % effect as "\futurelet\token\command". The advantage of "\toolboxFuturelet"
1338 % is that instead of a single "\command" one may use also a sequence of
1339 % commands.\par
1340
1341 % Let us consider "\MacroWithOptionalFlag" as above. Assume that the user
1342 % has called this macro in the form "\MacroWithOptionalFlag*" where the
1343 % "*" is a flag which should cause your macro to do something slightly
1344 % different. On some place in your macro definition you will have recognized
1345 % (e.g.\ with "\futurelet" or "\toolboxFuturelet") that a "*" is following
1346 % in the calling sequence. So you now want to execute your action
1347 % (whatever "\MacroWithOptionalFlag" is supposed to do).
1348 % However, if you do not take special care, after this action, \TeX\ will
1349 % print a "*", because this is the next token on the token stream: "\futurelet"
1350 % does not delete any tokens. So you have to ``gobble'' this token away.
1351 % A rude way to do this is by using the macro "\gobblenext" as the last token
1352 % in you macro which can be defined by
1353 % \begin{verbatim}
1354 % \def\gobblenext#1{}\end{verbatim}
1355 % However, this has two major drawbacks:
1356 % \begin{enumerate}
1357 % \item This works for "*", but not for "{" or space tokens.
1358 % For space tokens the situation is even worse, since \TeX\ eats spaces around
1359 % arguments, so sometimes space tokens might unexpectedly disappear.
1360 % \item It is not possible in this way to \emph{read} another argument
1361 % following the "*": Recall that "\gobblenext" must be the \emph{last} token
1362 % in your macro expansion, i.e.\ you have ``lost control'' after this call.
1363 % \end{enumerate}
1364 % The solution to these problems is instead of calling "\gobblenext" to use
1365 % \DescribeMacro{\toolboxGobbleNext}"\toolboxGobbleNext" as the last command
1366 % in your call: You can pass it an argument which describes the action that
1367 % you want to do \emph{after} gobbling the next token
1368 % ("*" in the above example) from the token stream. Thus
1369 % \begin{quote}
1370 % "\toolboxGobbleNext"\bracemeta{cmd}
1371 % \end{quote}
1372 % erases the token following that command from the token stream and
1373 % then executes \meta{cmd}. This is similar to
1374 % \begin{verbatim}
1375 % \def\toolboxGobbleNext#1#2{#1}\end{verbatim}
1376 % with the difference that "#2" is considered as a token and that no spaces
1377 % are eaten.\par
1378 % The effect is that e.g.\ the call
1379 % \begin{verbatim}
1380 % \toolboxGobbleNext{\foo}{{arg}\end{verbatim}
1381 % is the same as "\foo{arg}" (the brace "{" is eaten in this example).\par
1382
1383 % As described earlier, the commands "\futurelet" or "\toolboxFuturelet" can
1384 % be used to check for optional flags. Frequently you will only want
1385 % to test for one particular flag and decide the next action on this flag.
1386 % Of course, you can test the token found with "\ifx...\fi" but this has the
1387 % disadvantage that some tokens (e.g.\ "\fi") follow your action, which might
1388 % be bad (recall that e.g.\ "\toolboxGobbleNext" must be the last command of
1389 % your action, i.e.\ it would in the above examples not gobble the "*" but
1390 % the "\fi" which is probably not what you want).
1391 % The simplest solution is to use the command
1392 % \DescribeMacro{\toolboxIfNextToken}"\toolboxIfNextToken" which already
1393 % has the test included. For example, to test for an optional "[", you can
1394 % simply write
1395 % \begin{verbatim}
1396 % \def\MacroWithOptionalBrace{\toolboxIfNextToken[{\yes}{\no}}\end{verbatim}
1397 % and then the call "\MacroWithOptionalBrace[...]" will expand to "\yes[...]"
1398 % while "\MacroWithOptionalBrace x" will expand to "\no x" (note that the
1399 % brace is not gobbled---if you want the latter, use "\toolboxIfNextGobbling"
1400 % described below).\par
1401 % More precisely, the calling syntax of "\toolboxIfNextToken" is
1402 % \begin{quote}
1403 % \DescribeMacro{\toolboxIfNextToken}
1404 % "\toolboxIfNextToken"\bracemeta{token}\bracemeta{if}\bracemeta{else}
1405 % \end{quote}
1406 % The semantic is the following: If the token following this command is
1407 % \meta{token}, then \meta{if} is executed, otherwise \meta{else}.
1408 % It is explicitly admissible that \meta{token} is a space.
1409 % To support further tests, \DescribeMacro{\toolboxToken}"\toolboxToken"
1410 % is "\let" to the token which follows the command.
1411 % "\toolboxToken" is only a temporary token,
1412 % i.e.\ it may also be modified by other commands of this package;
1413 % in particular, you may also freely modify "\toolboxToken".\par
1414 % The token "\toolboxSpaceToken" which is described later may be handy
1415 % in connection with this command.\par
1416 % In contrast to similar \LaTeXe\ macros
1417 % much care has been taken that spaces are not eaten. This solves the
1418 % following problem:\par
1419 %
1420 % Assume that you want to write a macro which should have the calling syntax
1421 % "\mymacro{arg1}" or "\mymacro{arg1}[arg2]". You will probably implement
1422 % "\mymacro" to read the first argument and then to look whether the next
1423 % token is a "[". If you use the \LaTeXe\ macro to test for "[",
1424 % then all spaces until the next non-space token would be gobbled which means
1425 % that if you would use the \LaTeXe\ macros for the test, then the call
1426 % "\mymacro{arg1}"\myspace"Text" would behave like "\mymacro{arg1}Text",
1427 % i.e.\ the space is ``mysteriously'' lost. With the \filecite{toolbox}
1428 % macros this does not happen. The ``disadvantage'' is that
1429 % "\mymacro{arg1}"\myspace"[arg2]" is not the same as
1430 % "\mymacro{arg1}[arg2]" either (which is reasonable IMHO).
1431 %
1432 % Example:
1433 % \begin{verbatim}
1434 % \def\mycmd#1{\toolboxIfNextToken[{\ParseOpt{#1}}{\NoOpt{#1}}}
1435 % \def\ParseOpt#1[#2]{\OptAtEnd{#1}{#2}}\end{verbatim}
1436 % After the above definition, "\mycmd{arg}" executes "\NoOpt{arg}" while
1437 % "\mycmd{arg}[optional]" executes "\OptAtEnd{arg}{optional}".
1438 % We point out once more that in the first call a space following
1439 % "\mycmd{arg}" does not vanish (as would be the case if the \LaTeXe\ macros
1440 % would have been used).\par
1441
1442 % If "\toolboxIfNextToken" has found the required token, it does \emph{not}
1443 % gobble that token from the token stream. Of course, you can do this by
1444 % yourself using the earlier described macro "\toolboxGobbleNext". However,
1445 % it is simpler to use
1446 % \begin{quote}
1447 % \DescribeMacro{\toolboxIfNextGobbling}
1448 % "\toolboxIfNextGobbling"\bracemeta{token}\bracemeta{if}\bracemeta{else}
1449 % \end{quote}
1450 % This command is analogous to "\toolboxIfNextToken" with the difference that
1451 % in the case that the next token is \meta{token}, it is gobbled before
1452 % \meta{if} is executed.\par
1453 %
1454 % Example:
1455 % \begin{verbatim}
1456 % \def\my{\toolboxIfNextGobbling*\toolboxTokenLoop\toolboxLoop}\end{verbatim}
1457 % This makes "\my*..." behave like "\toolboxTokenLoop..." and
1458 % "\my..." (without "*") behave like "\toolboxLoop...".\par
1459
1460 % The following macro is one which you may want to use in connection with
1461 % \LaTeX2e\ optional arguments:
1462 %
1463 % \begin{quote}
1464 % \DescribeMacro{\toolboxIfEmpty}
1465 % "\toolboxIfEmpty"\bracemeta{arg}\bracemeta{if}\bracemeta{else}
1466 % \end{quote}
1467 %
1468 % \meta{arg} is not expand; it is only used to decide whether \meta{if} or
1469 % \meta{else} will be expanded.\par
1470 % For further tests there are more involved macros:
1471 %
1472 % \begin{quote}
1473 % \DescribeMacro{\toolboxIfx}
1474 % "\toolboxIfx"\bracemeta{arg}"\macro"\bracemeta{if}\bracemeta{else}
1475 % \end{quote}
1476 % This tests via "\ifx" whether "\def\Macro"\bracemeta{arg} would give
1477 % the definition of "\macro".
1478 %
1479 % \begin{quote}
1480 % \DescribeMacro{\toolboxIfX}
1481 % "\toolboxIfX"\bracemeta{arg 1}\bracemeta{arg 2}\bracemeta{if}\bracemeta{else}
1482 % \end{quote}
1483 % This tests whether \meta{arg 1} and \meta{arg 2} are the same token
1484 % sequences.\par
1485 %
1486 % If you want to avoid the "\else" and "\fi" commands to avoid certain side
1487 % effects, you can use instead:
1488 %
1489 % \begin{quote}
1490 % \DescribeMacro{\toolboxIfElse}
1491 % "\toolboxIfElse"\bracemeta{ifcmd}\bracemeta{if}\bracemeta{else}
1492 % \end{quote}
1493 % This is rather analogous to \meta{ifcmd}\meta{if}"\else"\meta{else}"\fi"
1494 % but has everything in this line already eliminated from the tokenlist when
1495 % \meta{if} resp.\ \meta{else} are expanded.
1496
1497 % \subsection{Loops over tokenlists and itemlists}
1498 %
1499 % \begin{quote}
1500 % \DescribeMacro{\toolboxLoop}
1501 % "\toolboxLoop"\bracemeta{items}\bracemeta{action}
1502 % \end{quote}
1503 %
1504 % This calls iteratively \meta{action}"{#1}", where "#1" runs over each item in
1505 % \meta{items}. Here, an item is either a token or a group
1506 % braced by "{...}".
1507 % In the latter case, the braces are lost. Spaces in \meta{items} are ignored
1508 % (unless they are braced). It is admissible that \meta{action} is not a single
1509 % macro but instead a sequence of tokens.\par
1510 % Examples follow below.\par
1511 % The counterintuitive order of arguments is explained by the fact that the
1512 % typical usage is
1513 % \begin{quote}
1514 % "\expandafter\toolboxLoop\expandafter{\ExpandingMacro}"\bracemeta{action}
1515 % \end{quote}
1516 % which for swapped order of arguments could hardly be written.\par
1517 %
1518 % "\toolboxLoop" is not reentrant, i.e.\ \bracemeta{action} may not expand
1519 % to something which contains a call to "\toolboxLoop". To enable such calls
1520 % anyway, the command
1521 % \begin{quote}
1522 % \DescribeMacro{\toolboxLoopName}
1523 % "\toolboxLoopName"\bracemeta{name}\bracemeta{items}\bracemeta{action}
1524 % \end{quote}
1525 % is provided which is analogous to "\toolboxLoopName". This is also
1526 % not reentrant, but in contrast to "\toolboxLoop",
1527 % calls with different \meta{name} can
1528 % be used independently of each other, i.e.\ in the \bracemeta{action} part
1529 % of a "\toolboxLoop" (or "\toolboxLoopName") can be a call to
1530 % "\toolboxLoopName" with a \emph{different} \meta{name} argument.
1531 % In particular, using a counter in \meta{name}, one could easily implement
1532 % even recursive calls. In this connection, it should be noted that
1533 % \meta{name} is expanded via "\csname ... \endcsname", and so you may use
1534 % constructs like "\the\namecounter" there.\par
1535
1536 % \begin{quote}
1537 % \DescribeMacro{\toolboxTokenLoop}
1538 % "\toolboxTokenLoop"\bracemeta{tokens}\bracemeta{action}
1539 % \end{quote}
1540 % This is similar to "\toolboxLoop": The command \meta{action}"\toolboxToken"
1541 % is executed iteratively where "\toolboxToken" runs over each token in
1542 % \meta{tokens}. The important difference is that "\toolboxToken" is a token
1543 % (instead of an item). In particular, "\toolboxToken" runs through every
1544 % single token including spaces and braces.\par
1545 % The token "\toolboxSpaceToken" which is described later may be handy
1546 % in connection with this command.\par
1547
1548 % Example:
1549 % \begin{verbatim}
1550 % \toolboxTokenLoop{Some text}{\kern0.1em}\end{verbatim}
1551 % is the similar to "\kern0.1em S\kern0.1em o\kern0.1em m...", i.e.\ you
1552 % get wider spacing between the letters of "Some text" (I do not claim that
1553 % this is typographically a good idea).\par
1554 %
1555 % Note that you do not have to take special care about the space.
1556 % With "\toolboxLoop", you would have to mask the space e.g.\ with
1557 %
1558 % \begin{verbatim}
1559 % \toolboxLoop{Some{ }text}{\kern0.1em}\end{verbatim}
1560 % or
1561 % \begin{verbatim}
1562 % \toolboxLoop{Some\toolboxSpace text}{\kern0.1em}\end{verbatim}
1563 % In contrast, "\toolboxTokenLoop" would behave differently here:
1564 % \begin{verbatim}
1565 % \toolboxTokenLoop{Some{ }text}{\kern0.1em}\end{verbatim}
1566 % would produce "\kern0.1em S...\kern0.1em{\kern0.1em"\myspace"\kern0.1em}..."
1567 % because the braces are simply considered as tokens.
1568
1569 %
1570 % "\toolboxTokenLoop" is not reentrant. Analogously to "\toolboxLoopName",
1571 % independent versions can be generated by
1572 % \begin{quote}
1573 % \DescribeMacro{\toolboxTokenName}
1574 % "\toolboxTokenName"\bracemeta{name}\bracemeta{tokens}\bracemeta{action}
1575 % \end{quote}
1576
1577 % \subsection{Controlled expansion}
1578 %
1579 % There are some occasions when you want more control over the expansion.
1580 % E.g.\ you might want to concatenate the contents of two macros to a
1581 % further macro or you want to expand a macro by one level but no full
1582 % expansion. Usually you can get this effects with "\expandafter", but if
1583 % you expand several concatenated tokens in this way you either have to
1584 % write a lot of "\expandafter"s or you have to define subsidiary macros
1585 % that help you to "\expandafter" certain parts of macros. The macros in
1586 % this section allow you to do this in the most generic way that I could
1587 % implement.
1588 %
1589 % \begin{quote}
1590 % \DescribeMacro{\toolboxDef}
1591 % "\toolboxDef\macrotodefine"\bracemeta{argumentlist}
1592 % \end{quote}
1593 %
1594 % This call is similar to
1595 % \begin{quote}
1596 % "\def\macrotodefine"\bracemeta{argumentlist}
1597 % \end{quote}
1598 % with two important differences:
1599 %
1600 % For "\toolboxDef", \meta{argumentlist} is expanded precisely by one level.
1601 % \meta{argumentlist} may not contain macros with parameters, and spaces in the
1602 % highest level are ignored. If you want to force a space on a particular
1603 % place, use the macro \DescribeMacro{\toolboxSpace}"\toolboxSpace" at this
1604 % place (which is described later). Contrary to the usual "\def", the
1605 % symbol "#" is treated as a usual symbol.
1606 %
1607 % Example of usage:
1608 % \begin{verbatim}
1609 % \toolboxDef\chain{\chain\toolboxSpace\after}\end{verbatim}
1610 % This modifies the macro "\chain" such that a space and the content of the
1611 % macro "\after" is appended at the end.
1612 %
1613 % \begin{quote}
1614 % \DescribeMacro{\toolboxAppend}
1615 % "\toolboxAppend\macrotodefine"\bracemeta{argumentlist}
1616 % \end{quote}
1617 % This is equivalent to
1618 % \begin{quote}
1619 % "\toolboxDef\macrotodefine{\macrotodefine"\meta{argumentlist}"}"
1620 % \end{quote}
1621 % \par
1622
1623 % The macro
1624 % \begin{quote}
1625 % \DescribeMacro{\toolboxSurround}
1626 % "\toolboxSurround"\bracemeta{content before}\bracemeta{content after}"\macro"
1627 % \end{quote}
1628 % redefines "\macro" such that \meta{content before} is put at the
1629 % beginning and \meta{content after} after the definition of "\macro".
1630 % So this is equivalent to
1631 % \begin{quote}
1632 % "\def\macro{"\meta{content before}\meta{old content of \cmdcite{macro}}\relax
1633 %\meta{content after}"}"
1634 % \end{quote}
1635 % It is required that "\macro" is a usual macro without any arguments.
1636 % If you want to patch more complicated macros, use the \filecite{patch.doc}
1637 % package instead.
1638
1639 % The order of the arguments may appear strange, but it is convenient if
1640 % \meta{content before} or \meta{content after} are macros which should be
1641 % expanded with "\expandafter".
1642
1643 % There is some subsidiary macro used in the implementation of the above
1644 % macros which might be useful also in some other situations:
1645 %
1646 % \begin{quote}
1647 % \DescribeMacro{\toolboxTokDef}
1648 % "\toolboxTokDef"\bracemeta{argumentlist}"\macrotodefine"
1649 % \end{quote}
1650 % This call is similar to
1651 % \begin{quote}
1652 % "\def\macrotodefine"\bracemeta{argumentlist}
1653 % \end{quote}
1654 % with the difference that the symbol "#" is stored as such.
1655 % The order of the arguments has been swapped in order to simplify the
1656 % application of "\expandafter" to \meta{argumentlist}.
1657 %
1658
1659 % \subsection{Searching, splitting, and replacing}
1660 %
1661 % \begin{quote}
1662 % \DescribeMacro{\toolboxSplitAt}
1663 % "\toolboxSplitAt"\bracemeta{argument}\bracemeta{search}\relax
1664 %"{\beforestring}{\afterstring}"
1665 % \end{quote}
1666 %
1667 % Here, "\beforestring" and "\afterstring" are arbitrary macro names,
1668 % and \meta{search} and \meta{argument} are any sequences of tokens (which
1669 % are in the following considered as `strings').
1670 %
1671 % This call scans \meta{argument} for the first occurrence of \meta{search}.
1672 % The macros "\beforestring" and "\afterstring" are defined correspondingly
1673 % such that "\beforestring" expands to the part before the first occurrence,
1674 % and "\afterstring" to the part following the first occurrence.
1675 % If \meta{search} does not occur in \meta{argument}, "\beforestring" is
1676 % defined to \meta{argument}, and "\afterstring" is "\let" "\undefined".
1677 %
1678 % If "\beforestring" or "\afterstring" had already been defined before the
1679 % call, the previous definition is tacitly overridden.
1680 % It is explicitly allowed that "\beforestring" and "\afterstring" are the
1681 % same names. In this case, the result has the meaning of "\afterstring".
1682 %
1683 % It is guaranteed that braces "{...}" are \emph{not} lost in \meta{argument}.
1684 % However, \meta{search} may not contain any braces, and \meta{argument} may
1685 % contain only matching pairs of braces. Moreover, occurrences of \meta{search}
1686 % within a pair of braces in \meta{argument} are not recognized.
1687 %
1688 % (The order of the arguments has been chosen in order to simplify the
1689 % use of "\expandafter").
1690 %
1691 % There are some restrictions for the strings in search. For example,
1692 % the symbol "#" is not allowed.
1693 %
1694 % In the above call, the arguments may not run over several paragraphs.
1695 % If you want the latter, you have to use the alternative call
1696 % \begin{quote}
1697 % "\toolboxSplitAt*"\bracemeta{argument}\bracemeta{search}\relax
1698 %"{\beforestring}{\afterstring}"
1699 % \end{quote}
1700
1701 %
1702 % Example of usage:
1703 %
1704 % \begin{verbatim}
1705 % \def\examplemacro#1{\toolboxSplitAt{#1}{@}\testme\testme
1706 % \ifx\testme\undefined
1707 % ... (do this when #1 contains no `@' token)
1708 % \fi}\end{verbatim}
1709 %
1710
1711 % If "\toolboxSplitAt" should be used several times with the same
1712 % \meta{search} string, it is much more efficient to use the following command:
1713 %
1714 % \begin{quote}
1715 % \DescribeMacro{\toolboxMakeSplit}
1716 % "\toolboxMakeSplit"\bracemeta{search}"{command}"
1717 % \end{quote}
1718 %
1719 % This call defines a new macro "\command" (the name is determined by the
1720 % second argument of "\toolboxMakeSplit") which can be called in the form
1721 %
1722 % \begin{quote}
1723 % "\command"\bracemeta{argument}"{\beforestring}{\afterstring}"
1724 % \end{quote}
1725 %
1726 % and which has the analogous meaning as "\SplitAt" (the argument
1727 % \bracemeta{search} is implicitly fixed and taken from the call of
1728 % "\toolboxMakeSplit").
1729 % It is explicitly admissible that the above macro "\toolboxMakeSplit" is
1730 % used with an already existing command name. In this case, the previous
1731 % definition of "\command" is tacitly overridden.
1732 %
1733 % The command created by "\toolboxMakeSplit" does not accept arguments which
1734 % run over several paragraphs. If you want the latter, you have to create
1735 % this command by the alternative call
1736 %
1737 % \begin{quote}
1738 % "\toolboxMakeSplit*"\bracemeta{search}"{command}"
1739 % \end{quote}
1740
1741 % The command
1742 % \begin{quote}
1743 % "\toolboxFreeSplit"\bracemeta{command}
1744 % \end{quote}
1745 % frees the memory used by a previous "\toolboxMakeSplit" (and lets "\command"
1746 % again be undefined).
1747
1748 % The command
1749 % \begin{quote}
1750 % \DescribeMacro{\toolboxReplace}
1751 % "\toolboxReplace"\bracemeta{search}\bracemeta{replace}"\macro"
1752 % \end{quote}
1753 % replaces in "\macro" all occurences of \meta{search} by \meta{replace}.
1754 % The same matches are found as in "\toolboxSplitAt".
1755 % If you need to search for the same text several times, it is faster
1756 % to use the command
1757 % \begin{quote}
1758 % \DescribeMacro{\toolboxReplaceSplit}
1759 % "\toolboxReplaceSplit"\bracemeta{replace}"\SplitCmd\macro"
1760 % \end{quote}
1761 % where "\SplitCmd" is a command previously generated with "\toolboxMakeSplit*"
1762 % according to your \meta{search} string. (You could also use
1763 % "\toolboxMakeSplit" to generate "\SplitCmd", but then "\macro" should not
1764 % contain any "\par"s).
1765
1766 % \subsection{Redefinition of macros}
1767 %
1768 %
1769 % \begin{quote}
1770 % \DescribeMacro{\toolboxMakeHarmless}
1771 % "\toolboxMakeHarmless{\macro}"
1772 % \end{quote}
1773 %
1774 % The above call redefines "\macro" such that it expands to an ASCII text
1775 % containing the previous definition of "\macro" (i.e.\ the catcodes of
1776 % "\macro" are changed).
1777
1778 % The call
1779 % \begin{quote}
1780 % \DescribeMacro{\toolboxDropBrace}
1781 % "\toolboxDropBrace{\macro}"
1782 % \end{quote}
1783 % drops possible outer braces of "\macro". More precisely,
1784 % if "\macro" expands to \bracemeta{content}, then "\macro" is redefined
1785 % to \meta{content} (without braces). Otherwise, nothing happens.
1786
1787 % The command
1788 % \begin{quote}
1789 % \DescribeMacro{\toolboxIf}
1790 % "\toolboxIf"\meta{comparison}\bracemeta{definition commands}\relax
1791 %\cmdmeta{macro}$\ldots$
1792 % \end{quote}
1793 % allows conditional definitions. Here, \bracemeta{definition command}
1794 % is either "\def", "{\long\def}", "\let", or some similar command like
1795 % e.g.\ the \LaTeX\ "\newcommand". If the test
1796 % "\ifx"\meta{comparison}\cmdmeta{macro} evaluates positive, then
1797 % \cmdmeta{macro} is defined correspondingly. Otherwise, \cmdmeta{macro}
1798 % is not changed.\par\smallskip
1799 %
1800 % \textbf{Examples:}
1801 %
1802 % \begin{verbatim}
1803 % \toolboxIf\undefined\def\macro{....}
1804 % \toolboxIf\undefined\let\macro...
1805 % \toolboxIf\undefined{\long\def}\macro{....}
1806 % \toolboxIf\undefined\newcommand{\macro}{....}\end{verbatim}
1807 %
1808 % are similar to "\def\macro{...}" resp.\ "\let\macro..."
1809 % resp.\ "\long\def\macro{...}" resp.\ "\newcommand{\macro}" with the
1810 % difference that "\macro" is not changed if it was already defined.
1811 % In this sense, "\toolboxIf" is a more flexible variant of "\providecommand".
1812 %
1813
1814 % The commands
1815 % \begin{quote}
1816 % \DescribeMacro{\toolboxNewiftrue}
1817 % "\toolboxNewiftrue"\bracemeta{name}\\
1818 % \DescribeMacro{\toolboxNewiffalse}
1819 % "\toolboxNewiffalse"\bracemeta{name}
1820 % \end{quote}
1821 % test whether the command "\if"\meta{name} was already introduced with
1822 % "\newif"; in this case nothing happens. Otherwise, "\if"\meta{name} is
1823 % introduced similarly to "\newif\if"\meta{name} and set to "true"
1824 % respectively "false".
1825 % In contrast to the corresponding command in \TeX\ or \LaTeX 2.09, this macro
1826 % is not "\outer"!
1827 % \begin{quote}
1828 % \DescribeMacro{\toolboxNewifTrue}
1829 % "\toolboxNewifTrue"\bracemeta{name}\\
1830 % \DescribeMacro{\toolboxNewifFalse}
1831 % "\toolboxNewifFalse"\bracemeta{name}
1832 % \end{quote}
1833 % are similar to "\toolboxNewiftrue"\bracemeta{name} and
1834 % "\toolboxNewiffalse"\bracemeta{name}, respectively,
1835 % with the difference that "\if"\meta{name} is set unconditionally
1836 % to "true" respectively "false".
1837
1838 % \subsection{Concatenated macro names}
1839 %
1840 % \begin{quote}
1841 % \DescribeMacro{\toolboxLet}
1842 % "\toolboxLet\variable"\bracemeta{macroname}
1843 % \end{quote}
1844 % The above command is analogous to "\let\variable\macroname" with the
1845 % difference that \meta{macroname} can also contain other tokens like numbers
1846 % (it is obtained via "\csname"). Some converse to this command is
1847 %
1848 % \begin{quote}
1849 % "\toolboxWithNr"\bracemeta{number}"\command"\bracemeta{macro}
1850 % \end{quote}
1851 % which translates into "\command\macronumber" (here, \meta{macro} and
1852 % \meta{number} are just concatenated and evaluated via "\csname").
1853 % Examples:
1854 % \begin{verbatim}
1855 % \toolboxWithNr 1\let{name}\toolboxEmpty\end{verbatim}
1856 % This is the same as "\let\name1\toolboxEmpty" (but such that "\name1" is
1857 % considered as a name, not as "\name 1")
1858 % \begin{verbatim}
1859 % \toolboxWithNr {10}\def{name}{Foo}\end{verbatim}
1860 % This corresponds analogously to "\def\name10{Foo}".
1861 % \begin{verbatim}
1862 % \toolboxLet\mymacro{name\the\mycount}\end{verbatim}
1863 % This is similar to "\let\mymacro\namexx" where "xx" is the content
1864 % of the counter "\mycount".
1865
1866 % \subsection{Various}
1867 %
1868 % The following macros have equivalents in most formats (like \LaTeXe).
1869 % However, we do not want to rely too much on these formats, so we provide
1870 % our own definitions.
1871 % The macro
1872 % \begin{quote}
1873 % \DescribeMacro{\toolboxEmpty}"\toolboxEmpty"
1874 % \end{quote}
1875 % expands to nothing (usually, this is the same as "\empty").
1876 % Similarly, the macro
1877 % \begin{quote}
1878 % \DescribeMacro{\toolboxSpace}"\toolboxSpace"
1879 % \end{quote}
1880 % expands to a space symbol (usually, this is the same as "\space").
1881 % The token
1882 % \begin{quote}
1883 % \DescribeMacro{\toolboxSpaceToken}"\toolboxSpaceToken"
1884 % \end{quote}
1885 % is "\let" a space token (usually, this is the same as "\@sptoken").
1886 % This token is convenient in tests of tokens
1887 % (because it is hard to get a space there which is not eaten by the
1888 % \TeX\ parser, although sometimes also constructions like
1889 % \begin{verbatim}
1890 % \expandafter\ifx\toolboxSpace\token\end{verbatim}
1891 % can be used). Also the macros
1892 % \begin{quote}
1893 % \DescribeMacro{\toolboxFirstOfTwo}"\toolboxFirstOfTwo"\\
1894 % \DescribeMacro{\toolboxSecondOfTwo}"\toolboxSecondOfTwo"
1895 % \end{quote}
1896 % are provided which read two arguments and return only the first
1897 % respectively second argument (usually, this is the same as
1898 % "\@firstoftwo" respectively "\@secondoftwo"). Similarly,
1899 % \begin{quote}
1900 % \DescribeMacro{\toolboxGobbleArg}
1901 % "\toolboxGobbleArg"\bracemeta{argument}
1902 % \end{quote}
1903 % just reads its argument and expands to nothing.
1904
1905 % \iffalse
1906 %</metainfo>
1907 % \fi
1908 % \iffalse--------------------------------------------------------------\fi
1909 % \StopEventually{\PrintChanges}
1910 % \section{Implementation}
1911 %
1912 % \iffalse--------------------------------------------------------------
1913 %
1914 %
1915 %<*package>
1916 % \fi
1917 % \begin{macrocode}
1918 %%
1919 %% This file was generated by the docstrip utility from toolbox.dtx.
1920 %% You may distribute this file only together with the source toolbox.dtx
1921 %% (and if possible with toolbox.ins) and only if these files are unmodified.
1922 %%
1923 %% Author:
1924 %%
1925 %% M. V\"ath [email protected]
1926 %%
1927
1928 \ifx\typeout\undefined
1929 \def\tbx@tmp{\immediate\write17}\expandafter\tbx@tmp
1930 \else
1931 \expandafter\typeout
1932 \fi{toolbox.sty by M. Vaeth: The TeX Programmer's Toolbox 5.1}
1933
1934 %% First, some LaTeX support:
1935 %% We inform LaTeX that this is a package, and we test whether we would
1936 %% override some existing commands.
1937
1938 \ifx\ProvidesPackage\undefined\else
1939 \ProvidesPackage{toolbox}[2004/04/29 v5.1]
1940 \fi
1941
1942 \ifx\newcommand\undefined\else
1943 \newcommand{\toolboxMakeDef}{}
1944 \newcommand{\toolboxFreeDef}{}
1945 \newcommand{\toolboxFuturelet}{}
1946 \newcommand{\toolboxGobbleNext}{}
1947 \newcommand{\toolboxIfNextToken}{}
1948 \newcommand{\toolboxIfNextGobbling}{}
1949 \newcommand{\toolboxIfEmpty}{}
1950 \newcommand{\toolboxIfx}{}
1951 \newcommand{\toolboxIfX}{}
1952 \newcommand{\toolboxIfElse}{}
1953 \newcommand{\toolboxLoop}{}
1954 \newcommand{\toolboxLoopName}{}
1955 \newcommand{\toolboxToken}{}
1956 \newcommand{\toolboxTokenName}{}
1957 \newcommand{\toolboxTokDef}{}
1958 \newcommand{\toolboxDef}{}
1959 \newcommand{\toolboxAppend}{}
1960 \newcommand{\toolboxSplitAt}{}
1961 \newcommand{\toolboxMakeSplit}{}
1962 \newcommand{\toolboxFreeSplit}{}
1963 \newcommand{\toolboxReplace}{}
1964 \newcommand{\toolboxReplaceSplit}{}
1965 \newcommand{\toolboxMakeHarmless}{}
1966 \newcommand{\toolboxDropBrace}{}
1967 \newcommand{\toolboxIf}{}
1968 \newcommand{\toolboxNewiftrue}{}
1969 \newcommand{\toolboxNewiffalse}{}
1970 \newcommand{\toolboxLet}{}
1971 \newcommand{\toolboxWithNr}{}
1972 \newcommand{\toolboxEmpty}{}
1973 \newcommand{\toolboxSpace}{}
1974 \newcommand{\toolboxSpaceToken}{}
1975 \newcommand{\toolboxFirstOfTwo}{}
1976 \newcommand{\toolboxSecondOfTwo}{}
1977 \newcommand{\toolboxGobbleArg}{}
1978 \fi
1979
1980 % \end{macrocode}
1981 % \subsection{Macros for various purposes}
1982 % \begin{macro}{\toolboxSpace}\nocomment
1983 % \begin{macrocode}
1984 \def\toolboxEmpty{}
1985 % \end{macrocode}
1986 % \end{macro}
1987 % \begin{macro}{\toolboxSpace}\nocomment
1988 % \begin{macrocode}
1989 \def\toolboxSpace{ }
1990 % \end{macrocode}
1991 % \end{macro}
1992 % \begin{macro}{\toolboxSpaceToken}
1993 % We cannot just write
1994 % \begin{verbatim*}\let\toolboxSpaceToken= \end{verbatim*}
1995 % because then the space would be eaten by \TeX's parser.
1996 % Also tries like
1997 % \begin{verbatim}
1998 % \expandafter\let\expandafter\toolboxSpaceToken\toolboxSpace\end{verbatim}
1999 % do not work for similar reasons. In contrast,
2000 % \begin{verbatim}
2001 % \futurelet\toolboxSpaceToken{ }\end{verbatim}
2002 % is possible (because the space is not `really' parsed at this time),
2003 % but it would have the side effect that the group "{ }" is executed which
2004 % forces a space output. We could artificially `eat' this output in some box.
2005 % But we proceed differently by replacing "{ }" in
2006 % the above call by an appropriate "\if...\fi". Of course, we have to take
2007 % care that the space is not eaten too early.
2008 % \begin{macrocode}
2009 \expandafter
2010 \futurelet\expandafter\toolboxSpaceToken\expandafter
2011 \if\toolboxSpace\toolboxEmpty\toolboxEmpty\fi
2012
2013 % \end{macrocode}
2014 % \end{macro}
2015 % \begin{macro}{\toolboxFirstOfTwo}\nocomment
2016 % \begin{macrocode}
2017 \long\def\toolboxFirstOfTwo#1#2{#1}
2018 % \end{macrocode}
2019 % \end{macro}
2020 % \begin{macro}{\toolboxSecondOfTwo}\nocomment
2021 % \begin{macrocode}
2022 \long\def\toolboxSecondOfTwo#1#2{#2}
2023 % \end{macrocode}
2024 % \end{macro}
2025 % \begin{macro}{\toolboxGobbleArg}
2026 % \begin{macrocode}
2027 \long\def\toolboxGobbleArg#1{}
2028
2029 % \end{macrocode}
2030 % \end{macro}
2031 %
2032 % \begin{macro}{\tbx@toks}
2033 % We need a temporary token list
2034 % \begin{macrocode}
2035 \toksdef\tbx@toks=0
2036
2037 % \end{macrocode}
2038 % \end{macro}
2039 %
2040 % \subsection{Macros supporting implicit macro definitions}
2041 %
2042 % \begin{macro}{\toolboxMakeDef}\nocomment
2043 % \begin{macrocode}
2044 \def\toolboxMakeDef{\tbx@MakeNames\tbx@MakeDef}
2045 % \end{macrocode}
2046 % \begin{macro}{\tbx@MakeDef}
2047 % The macros for "\toolboxMakeDef" are defined with
2048 % \begin{quote}
2049 % "\tbx@MakeDef\PrefixNewName\PrefixRenewName\PrefixProvideName%"\\
2050 % " \PrefixDefName\PrefixLetName\PrefixName\tbx@e@Prefix@Name%"\\
2051 % " "\bracemeta{Prefix}\bracemeta{Name}\bracemeta{Replacement Mask}
2052 % \end{quote}
2053 % Note that \meta{Replacement Mask} must be read implicitly, because it
2054 % contains "#1" which is usually forbidden.
2055 % The macro "\tbx@e@Prefix@Name" is defined as
2056 % \begin{quote}
2057 % "\tbx@long\def\tbx@e@Name#1"\bracemeta{Replacement Mask}
2058 % \end{quote}
2059 % The macros generated by
2060 % \begin{quote}
2061 % "\PrefixNewName"\bracemeta{something}"{"$\ldots$"...}"
2062 % \end{quote}
2063 % carry the names
2064 % \begin{quote}
2065 % "\tbx@l@"\meta{Prefix}"@"\meta{Name}"@"\meta{something}
2066 % \end{quote}
2067 % Observe that the symbol "@" has currently the exceptional letter catcode,
2068 % so that there is no danger that the user mangles up the names (unless he
2069 % uses "\makeatletter" which he should of course not do, usually).
2070 % \makeatletter
2071 % \begin{macrocode}
2072 \def\tbx@MakeDef#1#2#3#4#5#6#7#8#9{%
2073 \tbx@def#1{\toolboxIfNextGobbling*%
2074 {\tbx@MakeNew\let{#8}{#9}}{\tbx@MakeNew\def{#8}{#9}}}%
2075 \tbx@def#2{\toolboxIfNextGobbling*%
2076 {\tbx@MakeRenew\let{#8}{#9}}{\tbx@MakeRenew\def{#8}{#9}}}%
2077 \tbx@def#3{\toolboxIfNextGobbling*%
2078 {\tbx@MakeProvide\let{#8}{#9}}{\tbx@MakeProvide\def{#8}{#9}}}%
2079 \tbx@def#4{\toolboxIfNextGobbling*%
2080 {\tbx@MakeForce\let{#8}{#9}}{\tbx@MakeForce\def{#8}{#9}}}%
2081 \tbx@def#5##1##2{\expandafter
2082 \tbx@MakeLet\csname tbx@l@#8@#9@##2\endcsname##1}%
2083 \tbx@def#6{\toolboxIfNextGobbling*%
2084 {\tbx@MakeUse\tbx@itemEnd{#8}{#9}}{\tbx@MakeUse\relax{#8}{#9}}}%
2085 \long\def#7##1}
2086
2087 % \end{macrocode}
2088 % \begin{macro}{\tbx@MakeNew}
2089 % "\tbx@MakeNew"\bracemeta{mode}\relax
2090 %\bracemeta{Prefix}\bracemeta{Name}\bracemeta{something}%
2091 %\bracemeta{text to remember}
2092 % \begin{macrocode}
2093 \def\tbx@MakeNew#1#2#3#4{\expandafter
2094 \ifx\csname tbx@l@#2@#3@#4\endcsname\relax\else
2095 \errmessage{#2New#3: entry #4 already exists}%
2096 \fi
2097 \tbx@MakeForce{#1}{#2}{#3}{#4}}
2098
2099 % \end{macrocode}
2100 % \end{macro}
2101 % \begin{macro}{\tbx@MakeRenew}
2102 % "\tbx@MakeRenew"\bracemeta{mode}\relax
2103 %\bracemeta{Prefix}\bracemeta{Name}\bracemeta{something}%
2104 %\bracemeta{text to remember}
2105 % \begin{macrocode}
2106 \def\tbx@MakeRenew#1#2#3#4{\expandafter
2107 \ifx\csname tbx@l@#2@#3@#4\endcsname\relax
2108 \errmessage{#2Renew#3: entry #4 was not defined before}%
2109 \fi
2110 \tbx@MakeForce{#1}{#2}{#3}{#4}}
2111
2112 % \end{macrocode}
2113 % \end{macro}
2114 % \begin{macro}{\tbx@MakeProvide}
2115 % "\tbx@MakeProvide"\bracemeta{mode}\relax
2116 %\bracemeta{Prefix}\bracemeta{Name}\bracemeta{something}%
2117 %\bracemeta{text to remember}
2118 % \begin{macrocode}
2119 \def\tbx@MakeProvide#1#2#3#4#5{\expandafter
2120 \ifx\csname tbx@l@#2@#3@#4\endcsname\relax
2121 \tbx@MakeForce{#1}{#2}{#3}{#4}{#5}%
2122 \fi}
2123
2124 % \end{macrocode}
2125 % \end{macro}
2126 % \begin{macro}{\tbx@MakeForce}
2127 % "\tbx@MakeForce"\bracemeta{mode}\relax
2128 %\bracemeta{Prefix}\bracemeta{Name}\bracemeta{something}%
2129 %\bracemeta{text to remember}
2130 % \begin{macrocode}
2131 \long\def\tbx@MakeForce#1#2#3#4#5{%
2132 \ifx#1\let
2133 \expandafter
2134 \let\csname tbx@l@#2@#3@#4\endcsname#5%
2135 \else
2136 \expandafter
2137 \tbx@MakeDoDef\csname tbx@l@#2@#3@#4\expandafter\endcsname
2138 \csname tbx@e@#2@#3\endcsname{#5}%
2139 \fi}
2140 % \end{macrocode}
2141 % \begin{macro}{\tbx@MakeDoDef}
2142 % \begin{quote}
2143 % "\tbx@MakeDoDef"\relax
2144 %"\tbx@l@"\meta{Prefix}"@"\meta{Name}"@"\meta{something}"%"\\
2145 %" \tbx@e@"\meta{Prefix}"@"\meta{Name}\bracemeta{text to remember}
2146 % \end{quote}
2147 % \begin{macrocode}
2148 \long\def\tbx@MakeDoDef#1#2#3{\tbx@toks\expandafter{#2{#3}}%
2149 \edef#1{\the\tbx@toks}}
2150
2151 % \end{macrocode}
2152 % \end{macro}
2153 % \end{macro}
2154 % \begin{macro}{\tbx@MakeLet}
2155 % "\tbx@MakeLet"\cmdmeta{Prefix}"@"\meta{Name}"@"\meta{something}\relax
2156 %\cmdmeta{something}
2157 % \begin{macrocode}
2158 \def\tbx@MakeLet#1#2{%
2159 \ifx#1\relax
2160 \let#2\undefined
2161 \else
2162 \let#2#1%
2163 \fi}
2164
2165 % \end{macrocode}
2166 % \end{macro}
2167 % \begin{macro}{\tbx@MakeUse}
2168 % "\tbx@MakeUse"\bracemeta{mode}\relax
2169 %\bracemeta{Prefix}\bracemeta{Name}\bracemeta{something}
2170 % \begin{macrocode}
2171 \def\tbx@MakeUse#1#2#3#4{%
2172 \expandafter
2173 \ifx\csname tbx@l@#2@#3@#4\endcsname#1%
2174 \errmessage{Entry #4 was not defined with
2175 #2New#3, #2Provide#3, or #2Def#3}%
2176 \fi
2177 \csname tbx@l@#2@#3@#4\endcsname}
2178
2179 % \end{macrocode}
2180 % \end{macro}
2181 % \begin{macro}{\tbx@def}
2182 % "\tbx@def" is similar to "\def", but existence is tested (via "\relax")
2183 % \begin{macrocode}
2184 \def\tbx@def#1{%
2185 \ifx#1\relax\else
2186 \errmessage{\string#1 is already defined}%
2187 \fi
2188 \def#1}
2189
2190 % \end{macrocode}
2191 % \end{macro}
2192 % \end{macro}
2193 % \begin{macro}{\toolboxFreeDef}\nocomment
2194 % \begin{macrocode}
2195 \def\toolboxFreeDef{\toolboxIfNextGobbling*%
2196 {\tbx@MakeNames{\tbx@FreeDef\relax}}{\tbx@MakeNames{\tbx@FreeDef\undefined}}}
2197 % \end{macrocode}
2198 % \begin{macro}{\tbx@FreeDef}
2199 % \begin{quote}
2200 % "\tbx@FreeDef"\bracemeta{mode}"\PrefixNewName\PrefixRenewName%"\\
2201 % " \PrefixProvideName\PrefixDefName\PrefixLetName\PrefixName"%\\
2202 % " \tbx@e@Prefix@Name"\bracemeta{Prefix}\bracemeta{Name}
2203 % \end{quote}
2204 % The last two arguments are not needed, but we must gobble them.
2205 % Since a macro can have at most 9 arguments, we must gobble the last one
2206 % separately.
2207 % \begin{macrocode}
2208 \def\tbx@FreeDef#1#2#3#4#5#6#7#8#9{%
2209 \let#2\undefined\let#3\undefined\let#4\undefined\let#5\undefined
2210 \let#8\undefined
2211 \ifx#1\undefined
2212 \let#6\undefined\let#7\undefined
2213 \fi\toolboxGobbleArg}
2214
2215 % \end{macrocode}
2216 % \end{macro}
2217 % \end{macro}
2218 % \begin{macro}{\tbx@MakeNames}
2219 % The call
2220 % \begin{quote}
2221 % "\tbx@MakeNames"\bracemeta{commands}"["\meta{Prefix}"]"\bracemeta{Name}
2222 % \end{quote}
2223 % (where the "["\meta{Prefix}"]" argument is optional) expands to
2224 % \begin{quote}
2225 % \meta{commands}"\PrefixNewName\PrefixRenewName\PrefixProvideName%"\\
2226 % " \PrefixLetName\PrefixName\tbx@e@Prefix@Name%"\\
2227 % " "\bracemeta{Prefix}\bracemeta{Name}
2228 % \end{quote}
2229 % \begin{macrocode}
2230 \def\tbx@MakeNames#1{\toolboxIfNextToken[%]
2231 {\tbx@MakingNames{#1}}{\tbx@MakingNames{#1}[]}}
2232 % \end{macrocode}
2233 % \begin{macro}{\tbx@MakingNames}
2234 % \begin{macrocode}
2235 \def\tbx@MakingNames#1[#2]#3{\expandafter
2236 \tbx@ListSwap\expandafter{%
2237 \csname#2New#3\expandafter\endcsname
2238 \csname#2Renew#3\expandafter\endcsname
2239 \csname#2Provide#3\expandafter\endcsname
2240 \csname#2Def#3\expandafter\endcsname
2241 \csname#2Let#3\expandafter\endcsname
2242 \csname#2#3\expandafter\endcsname
2243 \csname tbx@e@#2@#3\endcsname{#2}{#3}}{#1}}
2244 % \end{macrocode}
2245 % \begin{macro}{\tbx@ListSwap}\nocomment
2246 % \begin{macrocode}
2247 \def\tbx@ListSwap#1#2{#2#1}
2248
2249 % \end{macrocode}
2250 % \end{macro}
2251 % \end{macro}
2252 % \end{macro}
2253 % \end{macro}
2254 %
2255 % \subsection{Macros supporting fancy optional argument parsing}
2256 %
2257 % \begin{macro}{\toolboxFuturelet}
2258 % \begin{macrocode}
2259 \long\def\toolboxFuturelet#1#2{\toolboxTokDef{#2}\tbx@tmp\futurelet#1\tbx@tmp}
2260
2261 % \end{macrocode}
2262 % \end{macro}
2263 % \begin{macro}{\toolboxGobbleNext}
2264 % \begin{macrocode}
2265 \long\def\toolboxGobbleNext#1{\toolboxTokDef{#1}\tbx@tmp
2266 \afterassignment\tbx@tmp
2267 \let\toolboxToken= }% The space here is important to read spaces properly
2268
2269 % \end{macrocode}
2270 % \end{macro}
2271 % \begin{macro}{\toolboxIfNextToken}
2272 % \begin{macrocode}
2273 \long\def\toolboxIfNextToken#1#2#3{%
2274 \toolboxFuturelet\toolboxToken{%
2275 \ifx#1\toolboxToken
2276 \expandafter\toolboxFirstOfTwo
2277 \else
2278 \expandafter\toolboxSecondOfTwo
2279 \fi{#2}{#3}}}
2280
2281 % \end{macrocode}
2282 % \end{macro}
2283 % \begin{macro}{\toolboxIfNextGobbling}
2284 % \begin{macrocode}
2285 \long\def\toolboxIfNextGobbling#1#2#3{%
2286 \toolboxIfNextToken{#1}{\toolboxGobbleNext{#2}}{#3}}
2287
2288 % \end{macrocode}
2289 % \end{macro}
2290 %
2291 % \subsection{Macros supporting loops over tokenlists and itemlists}
2292 %
2293 % \begin{macro}{\toolboxLoop}
2294 % "\toolboxLoop" just calls "\tbx@item" with the magic names
2295 % "\tbx@i" and "\tbx@I".
2296 % \begin{macrocode}
2297 \long\def\toolboxLoop#1#2{\tbx@item\tbx@i\tbx@I{#1}{#2}}
2298 % \end{macrocode}
2299 % \end{macro}
2300 % \begin{macro}{\toolboxLoopName}
2301 % "\toolboxLoopName" calls "\tbx@item" with the magic names "\tbx@i@#1"
2302 % and "\tbx@I#@1"
2303 % \begin{macrocode}
2304 \long\def\toolboxLoopName#1#2#3{\tbx@LoopName{#1}iI\tbx@item{#2}{#3}}
2305 % \end{macrocode}
2306 % \end{macro}
2307 % \begin{macro}{\tbx@LoopName}
2308 % \begin{verbatim}
2309 % \tbx@LoopName{name}{x}{y}{\exec}\end{verbatim}
2310 % is equivalent to
2311 % \begin{verbatim}
2312 % \exec\tbx@x@name\tbx@y@name\end{verbatim}
2313 % \begin{macrocode}
2314 \def\tbx@LoopName#1#2#3#4{%
2315 \expandafter#4\csname tbx@#2@#1\expandafter\endcsname
2316 \csname tbx@#3@#1\endcsname}
2317 % \end{macrocode}
2318 % \end{macro}
2319 % \begin{macro}{\tbx@item}
2320 % The call
2321 % \begin{quote}
2322 % "\tbx@item{\MagicNameA}{\MagicNameB}"\bracemeta{items}\bracemeta{action}
2323 % \end{quote}
2324 % is the essential part of "\toolboxLoop". It has the same semantic with
2325 % the only difference that the names "\MagicNameA" and "\MagicNameB" are used
2326 % as temporary macros (they are the reason why "\tbx@item" is not reentrant).
2327 % \begin{macrocode}
2328 \long\def\tbx@item#1#2#3#4{%
2329 \long\def#1##1{%
2330 \toolboxTokDef{##1}\toolboxToken
2331 \ifx\toolboxToken\tbx@itemEnd
2332 \def#2{\let#1\undefined\let#2\undefined}%
2333 \else
2334 #4{##1}%
2335 \fi
2336 #2}%
2337 \let#2#1%
2338 #1#3\tbx@itemEnd}
2339 % \end{macrocode}
2340 % \begin{macro}{\tbx@itemEnd}
2341 % "\tbx@itemEnd" is the magic token used to mark the end of the list in
2342 % "\tbx@item".
2343 % Of course, we could also use any other macro instead, but this is unique,
2344 % even if we compare with "\ifx". Moreover, we want a short macro to
2345 % avoid unnecessary redundancy in comparing with "\ifx".
2346 % It appears not necessary to make this token change in recursions, because
2347 % in each expansion of a list, the newest item will automatically be the
2348 % earliest.
2349 % \begin{macrocode}
2350 \def\tbx@itemEnd{\tbx@itemEnd}
2351
2352 % \end{macrocode}
2353 % \end{macro}
2354 % \end{macro}
2355 %
2356 % \begin{macro}{\toolboxTokenLoop}
2357 % "\toolboxTokenLoop" just calls "\tbx@token" with the magic names
2358 % "\tbx@t" and "\tbx@T".
2359 % \begin{macrocode}
2360 \long\def\toolboxTokenLoop#1#2{\tbx@token\tbx@t\tbx@T{#1}{#2}}
2361 % \end{macrocode}
2362 % \end{macro}
2363 % \begin{macro}{\toolboxTokenLoopName}
2364 % "\toolboxTokenLoopName" calls "\tbx@token" with the magic names "\tbx@t@#1"
2365 % and "\tbx@T#@1"
2366 % \begin{macrocode}
2367 \long\def\toolboxTokenLoopName#1#2#3{\tbx@LoopName{#1}tT\tbx@token{#2}{#3}}
2368 % \end{macrocode}
2369 % \end{macro}
2370 % \begin{macro}{\tbx@token}
2371 % The call
2372 % \begin{quote}
2373 % "\tbx@token{\MagicNameA}{\MagicNameB}"\bracemeta{items}\bracemeta{action}
2374 % \end{quote}
2375 % is the essential part of "\toolboxTokenLoop". It has the same semantic with
2376 % the only difference that the names "\MagicNameA" and "\MagicNameB" are used
2377 % as temporary macros (they are the reason why "\tbx@token" is not reentrant).
2378 % \begin{macrocode}
2379 \long\def\tbx@token#1#2#3#4{%
2380 \def#1{%
2381 \ifx\toolboxToken\tbx@tokenEnd
2382 \def#2{\let#1\undefined\let#2\undefined}%
2383 \else
2384 #4\toolboxToken
2385 \fi
2386 #2}%
2387 \def#2{\afterassignment#1\let\toolboxToken= }%
2388 #2#3\tbx@tokenEnd}
2389 % \end{macrocode}
2390 % \begin{macro}{\tbx@tokenEnd}
2391 % "\tbx@tokenEnd" is the magic token used to mark the end of the list
2392 % for "\tbx@token".
2393 % The same remarks as for "\tbx@itemEnd" hold. However, it is not clear
2394 % whether we could just use "\tbx@itemEnd" instead, because the scan rules
2395 % for "\tbx@token" and "\tbx@item" are somewhat different, and thus it is
2396 % not immediately clear whether in some fancy situations such lists (if
2397 % called cross-wise) could overlap: I found no example, but I also did not
2398 % put too much effort in finding one. In any case, we are on the sure side,
2399 % if we just use a different token.
2400 % \begin{macrocode}
2401 \def\tbx@tokenEnd{\tbx@tokenEnd}
2402
2403 % \end{macrocode}
2404 % \end{macro}
2405 % \end{macro}
2406 %
2407 % \begin{macro}{\toolboxIfEmpty}
2408 % \begin{macrocode}
2409 \long\def\toolboxIfEmpty#1{\toolboxIfx{#1}\toolboxEmpty}
2410 % \end{macrocode}
2411 % \end{macro}
2412 % \begin{macro}{\toolboxIfX}
2413 % \begin{macrocode}
2414 \long\def\toolboxIfX#1#2{\toolboxTokDef{#1}\tbx@ifx\toolboxIfx{#2}\tbx@ifx}
2415 % \end{macrocode}
2416 % \end{macro}
2417 % \begin{macro}{\toolboxIfx}
2418 % \begin{macrocode}
2419 \long\def\toolboxIfx#1#2{\toolboxTokDef{#1}\tbx@tmp
2420 \toolboxIfElse{\ifx\tbx@tmp#2}}
2421 % \end{macrocode}
2422 % \end{macro}
2423 % \begin{macro}{\toolboxIfElse}
2424 % \begin{macrocode}
2425 \long\def\toolboxIfElse#1{#1\expandafter
2426 \toolboxFirstOfTwo\else\expandafter\toolboxSecondOfTwo\fi}
2427
2428 % \end{macrocode}
2429 % \end{macro}
2430 %
2431 %
2432 % \subsection{Macros supporting controlled expansion}
2433 %
2434 % \begin{macro}{\toolboxTokDef}\nocomment
2435 % \begin{macrocode}
2436 \long\def\toolboxTokDef#1#2{\tbx@toks{#1}\edef#2{\the\tbx@toks}}
2437
2438 % \end{macrocode}
2439 % \end{macro}
2440 %
2441 % \begin{macro}{\toolboxDef}
2442 % This is mainly a call of "\toolboxLoopName". It is slightly faster if we
2443 % call "\tbx@item" immediately (and then we can also give magic names which do
2444 % not clash with any other names). Also for time and memory reasons, we always
2445 % assume that the temporary variable
2446 % \begin{macro}{\tbx@odeftmp}
2447 % "\tbx@odeftmp"
2448 % \end{macro}
2449 % is "\toolboxEmpty" at the beginning; we reset it to "\toolboxEmpty" at
2450 % the end (so that the memory is freed).
2451 % \begin{macrocode}
2452 \def\toolboxDef#1#2{%
2453 \tbx@item\tbx@odefa\tbx@odefb{#2}\tbx@odef
2454 \let#1\tbx@odeftmp\let\tbx@odeftmp\toolboxEmpty}
2455 \let\tbx@odeftmp\toolboxEmpty
2456 % \end{macrocode}
2457 % \begin{macro}{\tbx@odef}
2458 % \begin{macrocode}
2459 \long\def\tbx@odef#1{\expandafter\tbx@odefapp\expandafter{#1}}
2460 % \end{macrocode}
2461 % \end{macro}
2462 % \begin{macro}{\tbx@odefapp}
2463 % "\tbx@odefapp" appends its argument to "\tbx@odeftmp".
2464 % \begin{macrocode}
2465 \long\def\tbx@odefapp#1{\tbx@toks\expandafter{\tbx@odeftmp#1}%
2466 \edef\tbx@odeftmp{\the\tbx@toks}}
2467
2468 % \end{macrocode}
2469 % \end{macro}
2470 % \end{macro}
2471 %
2472 % \begin{macro}{\toolboxAppend}\nocomment
2473 % \begin{macrocode}
2474 \def\toolboxAppend#1#2{\toolboxDef#1{#1#2}}
2475
2476 % \end{macrocode}
2477 % \end{macro}
2478 %
2479 % \begin{macro}{\toolboxSurround}\nocomment
2480 % \begin{macrocode}
2481 \long\def\toolboxSurround#1#2#3{\tbx@toks{#1}%
2482 \tbx@toks\expandafter{\the\expandafter\tbx@toks#3#2}%
2483 \edef#3{\the\tbx@toks}}
2484
2485 % \end{macrocode}
2486 % \end{macro}
2487 %
2488 %
2489 % \subsection{Macros supporting searching, splitting, and replacing}
2490 %
2491 % \begin{macro}{\toolboxMakeSplit}\nocomment
2492 % \begin{macrocode}
2493 \def\toolboxMakeSplit{%
2494 \toolboxIfNextGobbling*\tbx@MakeLong\tbx@MakeShort}
2495 % \end{macrocode}
2496 %
2497 % \begin{macro}{\tbx@Makelong}
2498 % \begin{quote}
2499 % "\tbx@Makelong"\bracemeta{search}"{cmd}"
2500 % \end{quote}
2501 % is the same as
2502 % \begin{quote}
2503 % "\tbx@DoSplitInstance{\cmd}{\tbx@cmd@spt}{\tbx@cmd@rst}"
2504 %\bracemeta{search}"\long"
2505 % \end{quote}
2506 % \begin{macrocode}
2507 \long\def\tbx@MakeLong#1#2{%
2508 \tbx@SplitNames{#2}%
2509 \expandafter
2510 \tbx@DoSplitInstance\tbx@splt{#1}\long}
2511 % \end{macrocode}
2512 % \end{macro}
2513 % \begin{macro}{\tbx@MakeShort}
2514 % "\tbx@Makeshort" is essentially the same as "\tbx@Makelong" (just that
2515 % "\long" is missing, of course). We could have used the same macro with
2516 % an additional argument, but it is more convenient for the user if this
2517 % macro itself is not "\long" so that new paragraphs in the passed search
2518 % string already give an error: It makes no sense to look for new paragraphs
2519 % in texts which may not contain new paragraphs.
2520 % \begin{macrocode}
2521 \def\tbx@MakeShort#1#2{%
2522 \tbx@SplitNames{#2}%
2523 \expandafter
2524 \tbx@DoSplitInstance\tbx@splt{#1}{}}
2525 % \end{macrocode}
2526 % \end{macro}
2527 %
2528 % \begin{macro}{\tbx@SplitNames}
2529 % The call "\tbx@SplitNames{cmd}" is equivalent to
2530 % \begin{verbatim}
2531 % \def\tbx@splt{\cmd \tbx@cmd@spt \tbx@cmd@rst}\end{verbatim}
2532 % \begin{macrocode}
2533 \def\tbx@SplitNames#1{%
2534 \expandafter
2535 \def\expandafter\tbx@splt\expandafter{\csname#1\expandafter\endcsname
2536 \csname tbx@#1@spt\expandafter\endcsname
2537 \csname tbx@#1@rst\endcsname}}
2538 % \end{macrocode}
2539 % \end{macro}
2540 %
2541 % \begin{macro}{\tbx@DoSplitInstance}
2542 % The call
2543 % \begin{quote}
2544 % "\tbx@DoSplitInstance{\cmd}{\tbx@cmd@spt}{\tbx@cmd@rst}"\bracemeta{search}
2545 %\bracemeta{long}
2546 % \end{quote}
2547 % creates the instance "\cmd" which splits its argument at
2548 % \bracemeta{search} (also "\tbx@cmd@spt" and "\tbx@cmd@rst" are created
2549 % which are needed for "\cmd" to work). The argument \meta{long} must be
2550 % either "\long" or empty, depending whether long definitions are desired.\par
2551 % The difficulty in the definition of "\cmd" is to ensure that "{xxx}|{yyy}"
2552 % splits into "{xxx}" and "{yyy}" \emph{with} braces (i.e., we have to
2553 % find out whether there are braces which are eliminated by \TeX\ as
2554 % `argument braces'). Actually, this problem occurs only for the part "{yyy}".
2555 % We solve it by appending an "a" to \meta{argument}, i.e., we actually
2556 % split the string "{xxx}|{yyy}a". Of course, we have to eliminate the
2557 % trailing "a" at the end.
2558 % \begin{macrocode}
2559 \long\def\tbx@DoSplitInstance#1#2#3#4#5{%
2560 #5\def#1##1##2##3{%
2561 #2##2##3\toolboxEmpty##1#4#4@tbx@spt%
2562 \ifx##3\toolboxEmpty
2563 \let##3\undefined
2564 \else
2565 #3##3##1a@tbx@rst%
2566 \fi
2567 }%
2568 #5\def#2##1##2##3#4##4#4##5@tbx@spt{\expandafter
2569 \toolboxTokDef\expandafter{##3}##1\toolboxTokDef{##5}##2}%
2570 #5\def#3##1##2#4##3@tbx@rst{\tbx@rememberlasta##3@tbx@dropa%
2571 \tbx@defwithoutlasta##1##3@tbx@dropa}}
2572 % \end{macrocode}
2573 % \begin{macro}{\tbx@rememberlasta}
2574 % The call
2575 % \begin{quote}
2576 % "\tbx@rememberlasta"\meta{arg}"@tbx@dropa"
2577 % \end{quote}
2578 % (no braces: The magic string "@tbx@dropa" is used to find the end of
2579 % \meta{arg}) is only admissible, if the last token in \meta{arg} is an "a".
2580 % In this case, \DescribeMacro{\tbx@droplasta}"\tbx@droplasta" is
2581 % defined as \meta{arg} without the trailing "a" (but it may happen that
2582 % \meta{arg} looses surrounding braces), and the corresponding string with the
2583 % trailing "a" (possibly without surrounding braces) is saved into
2584 % \DescribeMacro{\tbx@rebuilda}"\tbx@rebuilda".
2585 % This macro is used by the instances created
2586 % by "\tbx@DoSplitInstance".
2587 % \begin{macrocode}
2588 \long\def\tbx@rememberlasta#1a@tbx@dropa{\toolboxTokDef{#1}\tbx@droplasta
2589 \toolboxTokDef{#1a}\tbx@rebuilda}
2590 % \end{macrocode}
2591 % \end{macro}
2592 % \begin{macro}{\tbx@defwithoutlasta}
2593 % The call
2594 % \begin{quote}
2595 % "\tbx@defwithoutlasta{\afterstring}"\meta{arg}"@tbx@dropa"
2596 % \end{quote}
2597 % (no braces: The magic string "@tbx@dropa" is used to find the end of
2598 % \meta{arg}) is only admissible, if the last token in \meta{arg} is an "a".
2599 % If \meta{arg} coincides with "\tbx@rebuilda",
2600 % then we know that we did not loose any braces, and we set "\afterstring"
2601 % to the content of "\tbx@droplasta"; otherwise we lost braces and thus
2602 % have additionally to surround the content of "\afterstring" by braces.
2603 % \begin{macrocode}
2604 \long\def\tbx@defwithoutlasta#1#2@tbx@dropa{\toolboxTokDef{#2}\tbx@originala
2605 \ifx\tbx@originala\tbx@rebuilda
2606 % \end{macrocode}
2607 % Did we forget braces in "\tbx@rememberlasta"?
2608 % \begin{macrocode}
2609 \let#1\tbx@droplasta
2610 \else
2611 \expandafter\toolboxTokDef\expandafter{\expandafter{\tbx@droplasta}}#1%
2612 \fi}
2613
2614 % \end{macrocode}
2615 % \end{macro}
2616 % \end{macro}
2617 % \end{macro}
2618 % \begin{macro}{\toolboxFreeSplit}\nocomment
2619 % \begin{macrocode}
2620 \def\toolboxFreeSplit#1{%
2621 \tbx@SplitNames{#1}%
2622 \expandafter
2623 \toolboxLoop\expandafter{\tbx@splt}\tbx@freeSplit}
2624 % \end{macrocode}
2625 % \begin{macro}{\tbx@freeSplit}\nocomment
2626 % \begin{macrocode}
2627 \def\tbx@freeSplit#1{\let#1\undefined}
2628
2629 % \end{macrocode}
2630 % \end{macro}
2631 % \end{macro}
2632 % \begin{macro}{\toolboxSplitAt}
2633 % "\toolboxSplitAt" just calls "tbx@DoSplitInstance" with dummy temporary
2634 % variables and then executes the corresponding command.
2635 % \begin{macrocode}
2636 \def\toolboxSplitAt{\toolboxIfNextGobbling*\tbx@SplitLong\tbx@SplitShort}
2637 % \end{macrocode}
2638 % \begin{macro}{\tbx@SplitLong}\nocomment
2639 % \begin{macrocode}
2640 \long\def\tbx@SplitLong#1#2#3#4{%
2641 \tbx@DoSplitInstance\tbx@splt\tbx@splta\tbx@spltb{#2}\long
2642 \tbx@splt{#1}{#3}{#4}}
2643 % \end{macrocode}
2644 % \end{macro}
2645 % \begin{macro}{\tbx@SplitShort}
2646 % We cannot use just an additional argument in "\tbx@SplitLong", because
2647 % we really should use a non-"\long" macro to read the arguments.
2648 % \begin{macrocode}
2649 \def\tbx@SplitShort#1#2#3#4{%
2650 \tbx@DoSplitInstance\tbx@splt\tbx@splta\tbx@spltb{#2}{}%
2651 \tbx@splt{#1}{#3}{#4}}
2652
2653 % \end{macrocode}
2654 % \end{macro}
2655 % \end{macro}
2656 %
2657 % \begin{macro}{\toolboxReplaceSplit}
2658 % "\toolboxReplaceSplit"\bracemeta{replace}"\SplitCmd\macro"
2659 % \begin{macrocode}
2660 \long\def\toolboxReplaceSplit#1#2#3{%
2661 \toolboxTokDef{#1}\tbx@reptext
2662 \expandafter
2663 \tbx@replace\expandafter{#3}{\let#3\toolboxEmpty}#3#2\tbx@reptext}
2664 % \end{macrocode}
2665 % \end{macro}
2666 %
2667 % \begin{macro}{\tbx@replace}
2668 % "\tbx@replace\bracemeta{text}\bracemeta{first}\macro\SplitCmd\Reptext"
2669 % First executes \meta{first}.
2670 % Then appends to "\macro" the content of \bracemeta{text} with the matches
2671 % of "\SplitCmd" replaced by the content of "\Reptext".
2672 % \begin{macrocode}
2673 \long\def\tbx@replace#1#2#3#4#5{#2%
2674 #4{#1}\tbx@repla\tbx@replb
2675 \toolboxIfElse{\ifx\tbx@replb\undefined}%
2676 {\toolboxDef#3{#3\tbx@repla}}%
2677 {\toolboxDef#3{#3\tbx@repla#5}%
2678 \expandafter\tbx@replace\expandafter{\tbx@replb}{}#3#4#5}}
2679 % \end{macrocode}
2680 % \end{macro}
2681 %
2682 % \begin{macro}{\toolboxReplace}
2683 % "\toolboxReplace"\bracemeta{search}\bracemeta{replace}"\macro"
2684 % just calls "tbx@DoSplitInstance" with dummy temporary variables
2685 % and then executes "\toolboxReplaceSplit".
2686 % \begin{macrocode}
2687 \long\def\toolboxReplace#1#2{%
2688 \tbx@DoSplitInstance\tbx@splt\tbx@splta\tbx@spltb{#1}\long
2689 \toolboxReplaceSplit{#2}\tbx@splt}
2690 % \end{macrocode}
2691 % \end{macro}
2692 %
2693 % \subsection{Macros supporting redefinition of macros}
2694 %
2695 % \begin{macro}{\toolboxMakeHarmless}\nocomment
2696 % \begin{macrocode}
2697 \def\toolboxMakeHarmless#1{\edef#1{\tbx@Nearverbatim#1}}
2698 % \end{macrocode}
2699 % \begin{macro}{\tbx@Nearverbatim}\nocomment
2700 % \begin{macrocode}
2701 \def\tbx@Nearverbatim{\expandafter\tbx@Meaning\meaning}
2702 % \end{macrocode}
2703 % \end{macro}
2704 % \begin{macro}{\tbx@Meaning}\nocomment
2705 % \begin{macrocode}
2706 \long\def\tbx@Meaning#1>{}
2707
2708 % \end{macrocode}
2709 % \end{macro}
2710 % \end{macro}
2711 %
2712 % \begin{macro}{\toolboxDropBrace}\nocomment
2713 % \begin{macrocode}
2714 \def\toolboxDropBrace#1{\expandafter\tbx@ForgetBrace#1@tbx@dropbrace#1}
2715 % \end{macrocode}
2716 % \end{macro}
2717 % \begin{macro}{\tbx@ForgetBrace}\nocomment
2718 % \begin{macrocode}
2719 \long\def\tbx@ForgetBrace#1@tbx@dropbrace#2{\toolboxTokDef{#1}#2}
2720
2721 % \end{macrocode}
2722 % \end{macro}
2723 %
2724 % \begin{macro}{\toolboxIf}\nocomment
2725 % \begin{macrocode}
2726 \long\def\toolboxIf#1#2#3{%
2727 \ifx#1#3\def\tbx@tmp{#2#3}\else\def\tbx@tmp{#2\tbx@tmp}\fi\tbx@tmp}
2728
2729 % \end{macrocode}
2730 % \end{macro}
2731 %
2732 % \begin{macro}{\toolboxNewiftrue}\nocomment
2733 % \begin{macrocode}
2734 \def\toolboxNewiftrue#1{\tbx@newifexec{#1}{\csname#1true\endcsname}}
2735 % \end{macrocode}
2736 % \end{macro}
2737 % \begin{macro}{\toolboxNewiffalse}\nocomment
2738 % \begin{macrocode}
2739 \def\toolboxNewiffalse#1{\tbx@newifexec{#1}{\csname#1false\endcsname}}
2740 % \end{macrocode}
2741 % \end{macro}
2742 % \begin{macro}{\toolboxNewiftrue}\nocomment
2743 % \begin{macrocode}
2744 \def\toolboxNewifTrue#1{\tbx@newifexec{#1}{}\csname#1true\endcsname}
2745 % \end{macrocode}
2746 % \end{macro}
2747 % \begin{macro}{\toolboxNewiffalse}\nocomment
2748 % \begin{macrocode}
2749 \def\toolboxNewifFalse#1{\tbx@newifexec{#1}{}\csname#1false\endcsname}
2750 % \end{macrocode}
2751 % \end{macro}
2752 % \begin{macro}{\tbx@newifexec}
2753 % \begin{quote}
2754 % "\tbx@newifexec"\bracemeta{name}\bracemeta{initialization}
2755 % \end{quote}
2756 % If the command "\if"\meta{name} already exists, nothing happens.
2757 % Otherwise, the commands \cmdmeta{name}"true" and \cmdmeta{name}"false" are
2758 % created (similarly as by the \TeX\ command "\newif"), and afterwards
2759 % \meta{initialization} is executed. Here, \meta{initialization} should be
2760 % either \cmdmeta{name}"true" or \cmdmeta{name}"false"
2761 % which then defines "\if"\meta{name} to the desired default.
2762 % (It may also be empty if you do this initialization immediately afterwards).
2763 % \meta{initialization} should not contain any potential "\if" tokens.\par
2764 % One must be very careful in the implementation of this macro,
2765 % because "\if"'s are parsed very strange by \TeX.
2766 % However, if an "\if"-command is the first token following our only "\ifx",
2767 % we do not run into problems. Moreover, the first parsing until "\fi" does
2768 % not see any further "\if", because it is hidden in "\csname" which has not
2769 % been expanded by this time.
2770 % \begin{macrocode}
2771 \def\tbx@newifexec#1#2{\expandafter
2772 \ifx\csname if#1\endcsname\relax
2773 \expandafter\tbx@newif\csname if#1\endcsname{#1}%
2774 #2%
2775 \fi}
2776 % \end{macrocode}
2777 % \begin{macro}{\tbx@newif}
2778 % It is rather annoying that D.~E. Knuth has introduced the "\outer"
2779 % directive:
2780 % The sole purpose of that command is to cause problems and to force people
2781 % to think how to get around these problems. It is especially irritating that
2782 % the standard command "\newif" was (before \LaTeXe) defined with this
2783 % attribute. To work in a normal way, we have to define "\newif" by hand
2784 % in a sane way. It is simpler for us, if we do not only pass the name as a
2785 % single token but additionally also the full name without "if".
2786 % So our simpler "\newif" macro is called as follows:
2787 % \begin{quote}
2788 % "\tbx@newif"\cmdmeta{ifname}\bracemeta{name}
2789 % \end{quote}
2790 % This macro does \emph{not} define \cmdmeta{ifname}. But gets automatically
2791 % defined after the first call of \cmdmeta{name}"true" or
2792 % \cmdmeta{name}"false" which should of course happen immediately afterwards.
2793 % \begin{macrocode}
2794 \def\tbx@newif#1#2{%
2795 \expandafter
2796 \def\csname#2true\endcsname{\let#1\iftrue}%
2797 \expandafter
2798 \def\csname#2false\endcsname{\let#1\iffalse}}
2799
2800 % \end{macrocode}
2801 % \end{macro}
2802 % \end{macro}
2803 %
2804 % \subsection{Macros supporting concatenated macro names}
2805 %
2806 % \begin{macro}{\toolboxWithNr}\nocomment
2807 % \begin{macrocode}
2808 \def\toolboxWithNr#1#2#3{\expandafter#2\csname #3#1\endcsname}
2809 % \end{macrocode}
2810 % \end{macro}
2811 % \begin{macro}{\toolboxLet}\nocomment
2812 % \begin{macrocode}
2813 \def\toolboxLet#1#2{\expandafter\let\expandafter#1\csname #2\endcsname}
2814
2815 % \end{macrocode}
2816 % \end{macro}
2817 %
2818 % \iffalse
2819 %</package>
2820 % \fi
2821 % \Finale\PrintIndex
2822 %
2823 %
2824 %
2825 % \iffalse
2826 %<*metainfo>
2827 % \fi
2828 \iffalse -------------------------------------------------------------
2829 %
2830 % Just in case that for some reason the file `toolbox.ins' got lost:
2831 % The content of this file is between the lines %<*insfile> and %</insfile>.
2832 %
2833 %\iffalse
2834 %</metainfo>
2835 %<*insfile>
2836 \def\batchfile{toolbox.ins}
2837 \input docstrip.tex
2838 \keepsilent
2839 \nopreamble
2840 \generateFile{toolbox.sty}{f}{\from{toolbox.dtx}{package}}
2841 \generateFile{toolbox.txt}{f}{\from{toolbox.dtx}{asciidocu}}
2842 \generateFile{toolbox.tex}{f}{\from{toolbox.dtx}{driver}}
2843 %%\generateFile{toolbox.ins.dup}{f}{\from{toolbox.dtx}{insfile}}
2844
2845 \Msg{***************************************************************}
2846 \Msg{*}
2847 \Msg{* To finish the installation you have to move the}
2848 \Msg{* file 'toolbox.sty' into a directory searched by TeX.}
2849 \Msg{*}
2850 \Msg{*}
2851 \Msg{* Run the file toolbox.tex through LaTeX to produce the}
2852 \Msg{* documentation or read the ascii documentation in toolbox.txt}
2853 \Msg{*}
2854 \Msg{*}
2855 \Msg{***************************************************************}
2856 \endbatchfile
2857 %</insfile>
2858 %<*metainfo>
2859 % \fi
2860 \fi
2861 % \iffalse
2862 %</metainfo>
2863 % \fi
2864 \endinput
2865
2866 %%% Local Variables:
2867 %%% mode: latex
2868 %%% TeX-master: "toolbox.tex"
2869 %%% End: