summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/toolbox/toolbox.txt
blob: 8470ef6fdd409f20424ec449fdebf1dee130c0f4 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790

%%#
%%# Author:
%%#
%%# M. V\"ath      martin@mvath.de
%%#
%%# The author thanks
%%#     David Kastrup <David.Kastrup@neuroinformatik.ruhr-uni-bochum.de>
%%#

%%# The package may be distributed and/or modified under the conditions of
%%# the LaTeX Project Public License (version 1.3c or later).

%%#############################################################################
%%#
%%#  The TeX programmer's toolbox; enhanced version.
%%#  This (La)TeX package provides some macros which are convenient for
%%#  writing indices, glossaries, or other macros.
%%#  It contains macros which support
%%#
%%#    - implicit macros - a useful supplement to \index or varindex for
%%#      writing glossaries or indices
%%#    - fancy optional arguments
%%#    - loops over tokenlists and itemlists
%%#    - searching, splitting, and replacing
%%#    - controlled expansion
%%#    - redefinition of macros
%%#    - concatenated macro names
%%#
%%#############################################################################

%%#
%%# This package was tested with plain TeX, LaTeX 2.09, and LaTeX 2e,
%%# and it should actually run with all TeX formats.
%%#


%%# To use toolbox, you have to put `toolbox.sty' in a path where TeX looks
%%# for its input files. The TeX documents using toolbox need the
%%# following modifications in their header:
%%#
%%# a) If you use LaTeX2.09, use toolbox as a style option, e.g.
%%#      \documentstyle[toolbox]{article}
%%#    or
%%#      \documentstyle[toolbox,12pt]{article}
%%# b) If you use LaTeX2e, put in the preamble the command
%%#      \usepackage{toolbox}
%%# c) If you use some other (non-LaTeX) format, you will probably have to
%%#    insert a line like
%%#          \catcode`\@=11\input toolbox.sty\catcode`\@=12\relax
%%#
%%# The only LaTeX-specific commands used in `toolbox.sty' are:
%%#
%%#   \newcommand (only in the form \newcommand{\command}{} to ensure that
%%#                 \command was not defined before)
%%#   \ProvidesPackage
%%#   \typeout
%%#
%%#   The above commands are used only if they are defined.
%%#

%%#
%%# Description of the provided macros:
%%#

%%# General remark: Many macros could appear in several sections.
%%# For example, \toolboxMakeDef and \toolboxSourround might be considered
%%# as macros which support redefinitions of macros. However, we put them
%%# in different sections which perhaps explain better their nature.

%%#
%%# Implicit macro definitions
%%# --------------------------

%%# What we mean by implicit macro definitions is probably best explained by
%%# the following examples which show the intended usage:
%%#
%%# (In the following examples, we always refer to the \index command. Note
%%# that it may be more convenient to use for indices the varindex package in
%%# addition - the documentation of varindex (release 2.3 or newer) gives
%%# additional hints and examples how these two (essentially independent)
%%# approaches can be combined in practice).
%%#
%%# Assume that you want to write an index for a book which has rather
%%# long and complicated \index entries. The first idea that one might have in
%%# this connection is to put the various \index commands at the beginning of
%%# the document into several macros (one for each \index entry), and to use
%%# just these macros in the main text. For example, one might want to write
%%# near the beginning of the document commands like
%%#   \newcommand{\Start}{\index{finish or end}}
%%#   \newcommand{\End}{\index{finish or end}}
%%# and then to use in the main text \Start and \End whenever a reference
%%# in the corresponding index to the current place is desired.
%%# However, this has two major disadvantages:
%%#  1. Unless you are very disciplinary with your macro names, it is easy to
%%#     forget that \End writes an index entry. So the \End in the main text
%%#     might be very confusing.
%%#  2. You cannot choose short and intuitive macro names for common phrases,
%%#     because they are usually already reserved by TeX, LaTeX, or some
%%#     packages.
%%#
%%# To avoid these problems, one may be very disciplinary and call the
%%# involved macros systematically e.g. \GlossaryStart \GlossaryEnd etc.
%%# However, this produces terrible long and unreadable macro names in the
%%# main text.
%%#
%%# The implicit macro definitions of "toolbox" provide a more convenient
%%# solution. The idea is that you do not use the corresponding macros directly
%%# but only implicitly by a call of other macros where your "macro name" is
%%# just an argument.
%%# Moreover, "toolbox" assists you in writing the corresponding definitions.
%%# For example, if you know that you want a set of macros which all expand
%%# into something of the form \index{...}, you can give a ``mask'' which
%%# contains this form, and you only have to fill in the changing content
%%# (similarly as for usual TeX macros with arguments, but the level of
%%# abstraction is one step higher).
%%# For the above task, you might use the command:
%%#
%%#    \toolboxMakeDef{Glossary}{\index{#1}}
%%#
%%# The argument `Glossary' serves to distinguish independent definitions
%%# (this will become clear later). Its effect visible now is that it
%%# determines the name of the following macros which you can use after
%%# the above call:
%%#
%%#    \NewGlossary{start-1}{start}
%%#    \NewGlossary{start-2}{start or beginning}
%%#    \NewGlossary{end}{finish or end}
%%#
%%# These command are now similar to the \newcommand definitions explained
%%# above. However, there is no name collision with the TeX-internal command
%%# \end. Of course, this means that you cannot just write \end in the main
%%# text to get the desired index entry. Instead, you have to write the more
%%# intuitive commands
%%#
%%#    \Glossary{start-1}
%%#    \Glossary{start-2}
%%#    \Glossary{end}
%%#
%%# (again, the name \Glossary stems from our first call of \toolboxMakeDef).
%%# Note that e.g. \Glossary{start-1} expands not only to `start' but
%%# actually to \index{start} (because of our first call of \toolboxMakeDef).
%%# Note also that you can use symbols like - or numbers which are usually
%%# not allowed in TeX macro names.
%%#
%%# Of course, similarly as for \newcommand, you can also do other things with
%%# the macros. For example,
%%#
%%#    \LetGlossary\tempname{end}
%%#    \NewGlossary*{finish}\tempname
%%#
%%# will first define \tempname to expand to the same text as \Glossary{end},
%%# and then defines a new entry \Glossary{finish} to expand to the same text
%%# as \tempname. Hence, the above new lines make the calls \Glossary{end} and
%%# \Glossary{finish} equivalent.
%%#
%%# At the end of your list of \NewGlossary commands, you might want to put
%%#
%%#    \toolboxFreeDef*{Glossary}
%%#
%%# The purpose of this command is that \NewGlossary cannot be used anymore
%%# (unless, of course, you define it again). So you cannot unintentionally
%%# add new entries to your glossary list (but you still can use \Glossary{...}
%%# to reference to the already produced entries).
%%# Moreover, the above command frees some memory which was needed for
%%# \NewGlossary to work.
%%#
%%# If you additionally want to free the memory used by \Glossary, you can use
%%#
%%#    \toolboxFreeDef{Glossary}
%%#
%%# (without the `*'). This may be necessary, if you want to call again e.g.
%%#
%%#    \toolboxMakeDef{Glossary}{\emph{#1}\index{#1}}
%%#
%%# (if you have not freed the memory for \Glossary before this repeated call,
%%# TeX will complain that \Glossary is already defined).
%%#
%%# Of course, it is possible to call \toolboxMakeDef with several different
%%# names, for example, for \Glossary, \SymbolList etc. Another application
%%# might be to use a different command to mark e.g.\ the main occurrence of
%%# some index entry or to output additionally the entry into the running text.
%%# We do this in the following example which simultaneously
%%# demonstrates that the names can also be constructed in another way:
%%#
%%#   \toolboxMakeDef[Ind]{}{\index{#1}}
%%#   \toolboxMakeDef[Ind]{Main}{\index{#1|textbf}}
%%#   \toolboxMakeDef{OutInd}{#1}
%%#
%%#   \IndNew{A}{A is a letter}
%%#   \IndNewMain{A}{A is a letter}
%%#   \NewOutInd{A}{\textbf{The letter A}\Ind{A}}
%%#
%%# After the above commands, you can use \Ind{A}, \IndMain{A}, and
%%# \OutInd{A} to produce the corresponding \index entry, the "main" \index
%%# entry (with a boldface page number), and the text \textbf{The letter A}
%%# with an additional entry into the index, respectively.
%%# Of course, it might usually be more convenient to define the \Ind and
%%# \IndMain" entries simultaneously, e.g. as follows
%%#
%%#    \toolboxMakeDef[Ind]{}{#1}
%%#    \toolboxMakeDef[Ind]{Main}{#1}
%%#    \newcommand{\NewStandardInd}[2]{%
%%#       \IndNew{#1}{\index{#2}}%
%%#       \IndNewMain{#1}{\index{#2|textbf}}}
%%#
%%#    \NewStandardInd{A}{A is a letter}
%%#
%%# This approach has the additional advantage that you can define exceptional
%%# cases "by hand" (e.g. if you want that for certain "main" index
%%# entries the page number is printed with "\textsl" instead of "\textbf").

%%# Since the motivation for implicit definitions now is hopefully clear,
%%# let us now describe in detail which commands are provided by "toolbox"
%%# for this purpose.
%%# As explained in the example, the main generic macro provided to this
%%# purpose is \toolboxMakeDef. Its call syntax is as follows:
%%#
%%# \toolboxMakeDef[Prefix]{Name}{ReplacementMask}
%%#
%%# (the argument [Prefix] is optional and by default empty).
%%# The above command generates new macros
%%#
%%# \PrefixNewName
%%# \PrefixRenewName
%%# \PrefixProvideName
%%# \PrefixDefName
%%# \PrefixLetName
%%# \PrefixName
%%#
%%# which in turn can be called as follows
%%#
%%# \PrefixNewName{something}{RememberText}
%%# \PrefixRenewName{something}{RememberText}
%%# \PrefixProvideName{something}{RememberText}
%%# \PrefixDefName{something}{RememberText}
%%# \PrefixNewName*{something}{\SomeMacro}
%%# \PrefixRenewName*{something}{\SomeMacro}
%%# \PrefixProvideName*{something}{\SomeMacro}
%%# \PrefixDefName*{something}{\SomeMacro}
%%# \PrefixLetName{\SomeMacro}{something}
%%# \PrefixName{something}
%%# \PrefixName*{something}
%%#
%%# These calls are in a sense similar to the respective commands
%%#
%%# \newcommand{\something}{RememberText}
%%# \renewcommand{\something}{RememberText}
%%# \providecommand{\something}{RememberText}
%%# \def\something{RememberText}
%%# \newcommand{\something}{}\let\something\SomeMacro
%%# \renewcommand{\something}{}\let\something\SomeMacro
%%# \@ifundefined\something{\let\something\SomeMacro}{}
%%# \let\something\SomeMacro
%%# \let\SomeMacro{\something}
%%# \something
%%# \something (but without error if \something is undefined).
%%#
%%# with the differences already pointed out before:
%%# 1. The macro name actually used is not \something. Instead, it is a name
%%#    which does not conflict with any existing macro (except one
%%#    generated previously by another \PrefixNewName, but in this case a
%%#    descriptive error is reported). For this reason, it is not possible to
%%#    use this macro directly but only indirectly by the call
%%#    \PrefixName{something} (or with \PrefixLetName).
%%# 2. The replacement text is not `RememberText' but determined by
%%#    ReplacementMask where every occurrence of #1 in ReplacementMask is
%%#    replaced by RememberText (recall the examples). If you want to have the
%%#    plain RememberText, use {#1} as ReplacementMask.
%%#
%%# Since toolbox 4.2 there is another slight difference: The symbol '#'
%%# is treated as usual and not as in a macro definition.
%%#
%%# \toolboxMakeDef gives an error message if the commands
%%# \Prefix... are already defined. If you intentionally want to
%%# change a previous definition, you have to call the command
%%#
%%#    \toolboxFreeDef[Prefix]{Name}
%%#
%%# before. The latter not only lets all of the macros \Prefix... be
%%# \undefined, but also frees all other memory internally used by the
%%# corresponding call of \toolboxMakeDef
%%# (note, however, that the above command does not free the
%%# memory allocated before by calls of \PrefixNew... - to free the latter,
%%# you have to call subsequently e.g.
%%#
%%#    \PrefixNewName*{...}{\undefined}
%%#
%%% before). There is also the command
%%#
%%#    \toolboxFreeDef*[Prefix]{Name}
%%#
%%# which acts similarly as \toolboxFreeDef but which does not undefine the
%%# two macros \PrefixName and \PrefixLetName.
%%#

%%#
%%# Fancy optional argument parsing
%%# -------------------------------

%%# This section contains macros which are convenient if you e.g. write a
%%# package that contains macros which contain a lot of optional arguments
%%# and flags (like "*").
%%# Typically, to read such an optional argument or flag, you save
%%# the next token with \futurelet and then call a macro which decides what to
%%# do with the token read. Thus, a typical use of \futurelet looks like
%%#
%%#    \def\MacroWithOptionalFlag{\futurelet\tokread\myscan}
%%#
%%# which will define \tokread to be the token *following* the macro
%%# \MacroWithOptionalFlag in the token stream and then execute \myscan.
%%# In this context, it is not very convenient that you are *forced*
%%# to define a macro \myscan: It could be more convenient if you could just
%%# write the *content* of \tokread (in braces) into the above definition.
%%# You can indeed do this if you replace \futurelet by \toolboxFuturelet:
%%#
%%# \toolboxFuturelet\token{argument}
%%#
%%# The call \toolboxFuturelet\token{\command} has precisely the same effect as
%%# \futurelet\token\command. The advantage of \toolboxFuturelet is that
%%# instead of a single \command one may use also a sequence of commands.

%%# Let us consider \MacroWithOptionalFlag as above. Assume that the user
%%# has called this macro in the form "\MacroWithOptionalFlag*" where the
%%# "*" is a flag which should cause your macro to do something slightly
%%# different. On some place in your macro definition you will have recognized
%%# (e.g. with \futurelet or \toolboxFuturelet) that a "*" is following
%%# in the calling sequence. So you now want to execute your action
%%# (whatever \MacroWithOptionalFlag is supposed to do).
%%# However, if you do not take special care, after this action, TeX will
%%# print a "*", because this is the next token on the token stream: \futurelet
%%# does not delete any tokens. So you have to "gobble" this token away.
%%# A rude way to do this is by using the macro \gobblenext as the last token
%%# in you macro which can be defined by
%%# \begin{verbatim}
%%# \def\gobblenext#1{}\end{verbatim}
%%# However, this has two major drawbacks:
%%#
%%# 1. This works for "*", but not for "{" or space tokens.
%%#    For space tokens the situation is even worse, since TeX eats spaces
%%#    around arguments, so sometimes space tokens might unexpectedly
%%#    disappear.
%%# 2. It is not possible in this way to read another argument following
%%#    the "*": Recall that \gobblenext must be the *last* token in your
%%#    macro expansion, i.e. you have "lost control" after this call.
%%#
%%# The solution to these problems is instead of calling \gobblenext to use
%%# \toolboxGobbleNext as the last command in your call:
%%# You can pass it an argument which describes the action that
%%# you want to do *after* gobbling the next token ("*" in the above example)
%%# from the token stream. Thus
%%#
%%# \toolboxGobbleNext{cmd}
%%#
%%# erases the token following that command from the token stream and
%%# then executes cmd. This is similar to
%%#   \def\toolboxGobbleNext#1#2{#1}
%%# with the difference that #2 is considered as a token and that no spaces
%%# are eaten.
%%# The effect is that e.g. the call
%%#
%%# Example:
%%#  \toolboxGobbleNext{\foo}{{arg}
%%# is the same as \foo{arg} (the brace "{" is eaten in this example).

%%# As described earlier, the commands "\futurelet" or "\toolboxFuturelet" can
%%# be used to check for optional flags. Frequently you will only want
%%# to test for one particular flag and decide the next action on this flag.
%%# Of course, you can test the token found with \ifx...\f", but this has the
%%# disadvantage that some tokens (e.g. \fi) follow your action, which might
%%# be bad (recall that e.g. \toolboxGobbleNext must be the last command of
%%# your action, i.e. it would in the above examples not gobble the "*" but
%%# the "\fi" which is probably not what you want).
%%# The simplest solution is to use the command \toolboxIfNextToken which
%%# already has the test included. For example, to test for an optional "[",
%%# you can simply write
%%#
%%# \def\MacroWithOptionalBrace{\toolboxIfNextToken[{\yes}{\no}}
%%#
%%# and then the call "\MacroWithOptionalBrace[...]" will expand to "\yes[...]"
%%# while "\MacroWithOptionalBrace x" will expand to "\no x"
%%# (note that the brace is not gobbled - if you want the latter,
%%# use "\toolboxIfNextGobbling" described below).

%%# More precisely, the calling syntax of "\toolboxIfNextToken" is
%%#
%%# \toolboxIfNextToken{token}{IfPart}{ElsePart}
%%#
%%# The semantic is the following:
%%# If the token following this command is `token', then IfPart is executed,
%%# otherwise ElsePart. It is explicitly admissible that `token' is a space.
%%# To support further tests, \toolboxToken is \let to the token which follows
%%# the command. \toolboxToken is only a temporary token, i.e.
%%# it may also be modified by other commands of this package; in particular,
%%# you may also freely to modify \toolboxToken.
%%# The token \toolboxSpaceToken which is described later may be handy
%%# in connection with this command.
%%#
%%# In contrast to similar LaTeX2e macros much care has been taken
%%# that spaces are not eaten. This solves the following problem:
%%#
%%# Assume that you want to write a macro which should have the calling syntax
%%# "\mymacro{arg1}" or "\mymacro{arg1}[arg2]". You will probably implement
%%# \mymacro to read the first argument and then to look whether the next
%%# token is a "[". If you use the LaTeX2e macro to test for "[",
%%# then all spaces until the next non-space token would be gobbled which means
%%# that if you would use the LaTeX2e macros for the test, then the call
%%# "\mymacro{arg1} Text" would behave like "\mymacro{arg1}Text",
%%# i.e. the space is `mysteriously' lost. With the "toolbox" macros this
%%# does not happen. The `disadvantage' is that "\mymacro{arg1} [arg2]"
%%# is not the same as "\mymacro{arg1}[arg2]" (which is reasonable IMHO).
%%#
%%# Example:
%%#
%%# \def\mycmd#1{\toolboxIfNextToken[{\ParseOpt{#1}}{\NoOpt{#1}}}
%%#    \def\ParseOpt#1[#2]{\OptAtEnd{#1}{#2}}
%%#
%%# After the above definition, \mycmd{arg} executes \NoOpt{arg} while
%%# \mycmd{arg}[optional]  executes \OptAtEnd{arg}{optional}
%%# We point out once more that in the first call a space following
%%# \mycmd{arg} does not vanish (as would be the case if the LaTeX 2e macros
%%# would have been used).

%%# If \toolboxIfNextToken has found the required token, it does *not*
%%# gobble that token from the token stream. Of course, you can do this by
%%# yourself using the earlier described macro \toolboxGobbleNext. However,
%%# it is simpler to use
%%#
%%# \toolboxIfNextGobbling{token}{IfPart}{ElsePart}
%%#
%%# This command is analogous to \toolboxIfNextToken with the difference that
%%# in the case that the next token is the desired token, it is gobbled before
%%# IfPart is executed.
%%#
%%# Example:
%%#
%%# \def\myloop{\toolboxIfNextGobbling*\toolboxTokenLoop\toolboxLoop}
%%#
%%# This makes \myloop*... behave like \toolboxTokenLoop, and
%%# \myloop... (without *) behave like \toolboxLoop.

%%# The following macro is one which you may want to use in connection with
%%# LaTeX 2e optional arguments:
%%#
%%# \toolboxIfEmpty{arg}{IfPart}{ElsePart}
%%#
%%# The argument is not expand; it is only used to decide whether the
%%# {IfPart} or the {ElsePart} will be expanded.
%%# For further tests there are more involved macros:
%%#
%%# \toolboxIfx{arg}\macro{IfPart}{ElsePart}
%%#
%%# This tests via \ifx whether \def\Macro{arg} would give the definition
%%# of \macro.
%%#
%%# \toolboxIfX{arga}{argb}{IfPart}{ElsePart}
%%#
%%# This tests whether "arga" and "argb" are the same token sequences.
%%# If you want to avoid the \else and \fi commands to avoid certain side
%%# effects, you can use instead:
%%#
%%# \toolboxIfElse{ifcmd}{IfPart}{ElsePart}
%%#
%%# This is rather analogous to "ifcmd" IfPart \else ElsePart \fi
%%# but has everything in this line already eliminated from the tokenlist
%%# when IfPart resp. ElsePart are expanded.

%%#
%%# Loops over tokenlists and itemlists
%%# -----------------------------------

%%# \toolboxLoop{items}{action}
%%#
%%# This calls iteratively "action{#1}", where #1 runs over each item in the
%%# argument items. Here, an item is either a token or a group braced by {...}.
%%# In the latter case, the braces are lost. Spaces in items are ignored
%%# (unless they are braced). It is admissible that \action is not a single
%%# macro but instead a sequence of tokens.
%%# Examples follow below.
%%#
%%# The counterintuitive order of arguments is explained by the fact that the
%%# typical usage is
%%# \expandafter\toolboxLoop\expandafter{\MacroExpandingToItems}{action}
%%# which for swapped order of arguments could hardly be written.

%%# \toolboxLoop is not reentrant i.e. "action" may not expand
%%# to something which contains a call to \toolboxLoop. To enable such calls
%%# anyway, the command
%%#
%%# \toolboxLoopName{name}{items}{\action}
%%#
%%# is provided which is analogous to \toolboxLoop. This is also not reentrant,
%%# but in contrast to \toolboxLoop, calls with different `name' arguments can
%%# be used independently of each other, i.e. in the `action' part of a
%%# \toolboxLoop (or \toolboxLoopName) can be a call to \toolboxLoopName with
%%# a *different* `name'.
%%# In particular, using a counter in `name' one could easily implement
%%# even recursive calls. In this connection, it should be noted that
%%# `name' is expanded via \csname ... \endcsname, and so you may use
%%# constructs like \the\namecounter there.

%%# \toolboxTokenLoop{tokens}{\action}
%%#
%%# This is similar to \toolboxLoop: The command \action\toolboxToken
%%# is executed iteratively where \toolboxToken runs over each token in tokens.
%%# The important difference is that \toolboxToken is a token (instead of an
%%# item). In particular, \toolboxToken runs through every single token
%%# including spaces and braces.
%%# The token \toolboxSpaceToken which is described later may be handy
%%# in connection with this command.
%%#
%%# Example:
%%#
%%# \toolboxTokenLoop{Some text}{\kern0.1em}
%%#
%%# is the similar to "\kern0.1em S\kern0.1em o\kern0.1em m...", i.e. you
%%# get wider spacing between the letters of "Some text" (I do not claim that
%%# this is typographically a good idea).
%%#
%%# Note that you do not have to take special care about the space.
%%# With \toolboxLoop, you would have to mask the space e.g. with
%%#
%%# \toolboxLoop{Some{ }text}{\kern0.1em}  or
%%# \toolboxLoop{Some\toolboxSpace text}{\kern0.1em}
%%#
%%# In contrast, \toolboxTokenLoop would behave differently here:
%%#
%%# \toolboxTokenLoop{Some{ }text}{\kern0.1em}
%%#
%%# would produce \kern0.1em S...\kern0.1em{\kern0.1em <space>\kern0.1em}...
%%# because the braces are simply considered as tokens.

%%# \toolboxTokenLoop is not reentrant. Analogously to \toolboxLoopName,
%%# independent versions can be generated by
%%#
%%# \toolboxTokenName{name}{tokens}{\action}

%%#
%%# Controlled expansion
%%# --------------------

%%# There are some occasions when you want more control over the expansion.
%%# E.g. you might want to concatenate the contents of two macros to a
%%# further macro or you want to expand a macro by one level but no full
%%# expansion. Usually you can get this effects with \expandafter, but if
%%# you expand several concatenated tokens in this way you either have to
%%# write a lot of \expandafter's or you have to define subsidiary macros
%%# that help you to \expandafter certain parts of macros. The macros in
%%# this section allow you to do this in the most generic way that I could
%%# implement.

%%# \toolboxDef\macrotodefine{argumentlist}
%%#
%%# This call is similar to
%%#    \def\macrotodefine{argumentlist}
%%# with two important differences:
%%#
%%# For \toolboxDef, the argumentlist is expanded precisely by one level.
%%# argumentlist may not contain macros with parameters, and spaces on the
%%# highest level are ignored. If you want to force a space on a particular
%%# place, use the macro \toolboxSpace at this place
%%# (which is described later). Contrary to the usual \def, the symbol # is
%%# treated as a usual symbol.
%%#
%%# Example of usage:
%%#    \toolboxDef\chain{\chain\toolboxSpace\after}
%%# This modifies the macro \chain such that a space and the content of the
%%# macro \after is appended at the end.

%%# \toolboxAppend\macrotodefine{arglist}
%%#
%%# This is equivalent to \toolboxDef\macrotodefine{\macrotodefine arglist}
%%#

%%# \toolboxSurround{ContentBefore}{ContentAfter}\macro
%%#
%%# This redefines \macro such that ContentBefore is put at the beginning
%%# and ContentAfter after the definition of \macro. So this is equivalent to
%%# \def\macro{ContentBefore * ContentAfter}
%%# where * is the old content of \macro. It is required that \macro is a
%%# usual macro without any arguments. If you want to patch more complicated
%%# macros, use the patch.doc package instead.
%%# The order of the arguments may appear strange, but it is convenient if
%%# ContentBefore or ContentAfter are macros which should be expanded with
%%# \expandafter.

%%# There is some subsidiary macro used in the implementation of the above
%%# macros which might be useful also in some other situations:
%%#
%%# \toolboxTokDef{argumentlist}\macrotodefine
%%#
%%# This call is similar to
%%#    \def\macrotodefine{argumentlist}
%%# with the difference that the symbol # is stored as such.
%%# The order of the arguments has been swapped in order to simplify the
%%# application of \expandafter to the argumentlist.

%%#
%%# Searching, splitting, and replacing
%%# ----------------------------------

%%# \toolboxSplitAt{argument}{search}{\beforestring}{\afterstring}
%%#
%%# Here, \beforestring and \afterstring are arbitrary macro names,
%%# and search and argument are any sequences of tokens (which are in
%%# the following considered as `strings').
%%#
%%# This call scans the string `argument' for the first occurrence of `search'.
%%# The macros \beforestring and \afterstring are defined correspondingly
%%# such that \beforestring expands to the part before the first occurrence,
%%# and \afterstring to the part following the first occurrence.
%%# If `search' does not occur in `argument', \beforestring is defined to
%%# `argument', and \afterstring is \let \undefined.
%%#
%%# If \beforestring or \afterstring had already been defined before the
%%# call, the previous definition is tacitly overridden.
%%# It is explicitly allowed that \beforestring and \afterstring are the
%%# same names. In this case, the result has the meaning of \afterstring.
%%#
%%# It is guaranteed that braces {...} are *not* lost in `argument'.
%%# However, `search' may not contain any braces, and `argument' may contain
%%# only matching pairs of braces. Moreover, occurrences of `search' within a
%%# pair of braces in `argument' are not recognized.
%%#
%%# (The order of the arguments has been chosen in order to simplify the
%%# use of \expandafter).
%%#
%%# There are some restrictions for the strings in search. For example,
%%# the symbol '#' is not allowed.
%%#
%%# In the above call, the arguments may not run over several paragraphs.
%%# If you want the latter, you have to use the alternative call
%%#
%%# \toolboxSplitAt*{argument}{search}{\beforestring}{\afterstring}
%%#
%%# Example of usage:
%%#
%%# \def\examplemacro#1{\toolboxSplitAt{#1}{@}\testme\testme
%%#   \ifx\testme\undefined
%%#      ... (do this when #1 contains no `@' token)
%%#   \fi}
%%#

%%# \toolboxMakeSplit{search}{command}
%%#
%%# If \toolboxSplitAt should be used several times with the same search
%%# string, it is much more effective to use the above call: This call
%%# defines a new macro \command (the name is determined by the second argument
%%# of \toolboxMakeSplit) which can be called in the form
%%#
%%#    \command{argument}{\beforestring}{\afterstring}
%%#
%%# and which has the analogous meaning as \toolboxSplitAt (the argument
%%# {search} is implicitly fixed and taken from the call of
%%# \toolboxMakeSplit).
%%# It is explicitly admissible that the above macro \toolboxMakeSplit is
%%# used with an already existing command name. In this case, the previous
%%# definition of \command is tacitly overridden.
%%#
%%# The command created by \toolboxMakeSplit does not accept arguments which
%%# run over several paragraphs. If you want the latter, you have to create
%%# this command by the alternative call
%%#
%%# \toolboxMakeSplit*{search}{command}

%%#
%%# The command
%%#    \toolboxFreeSplit{command}
%%# frees the memory used by a previous \toolboxMakeSplit (and lets \command
%%# again be undefined).

%%# The command
%%#    \toolboxReplace{search}{replace}\macro
%%# replaces in \macro all occurences of {search} by {replace}.
%%# The same matches are found as in \toolboxSplitAt.
%%# If you need to search for the same text several times, it is faster
%%# to use the command
%%#    \toolboxReplaceSplit{replace}\SplitCmd\macro
%%# where \SplitCmd is a command previously generated with \toolboxMakeSplit*
%%# according to your search string. (You could also use \toolboxMakeSplit
%%# to generate \SplitCmd, but then \macro should not contain any \par's).

%%#
%%# Redefinition of macros
%%# ----------------------

%%# \toolboxMakeHarmless{\macro}
%%#
%%# The above call redefines \macro such that it expands to an ASCII text
%%# containing the previous definition of \macro (i.e. the catcodes of \macro
%%# are changed).

%%# \toolboxDropBrace\variable
%%#
%%# drops possible outer braces in \variable. More precisely,
%%# if \variable expands to {content}, then \variable is redefined to
%%# content (without braces). Otherwise, nothing happens.

%%#
%%# \toolboxIf\comparison{DefinitionCommand}{\macro}...
%%#
%%# The above command allows conditional definitions.
%%# Here, {DefinitionCommand} is either \def, {\long\def}, \let, or some
%%# similar command like the LaTeX \newcommand. If the test
%%# \ifx\comparison\macro evaluates positive, then \macro is defined
%%# correspondingly. Otherwise, \macro is not changed.
%%#
%%# Examples:
%%#
%%# \toolboxIf\undefined\def\macro{....}
%%# \toolboxIf\undefined\let\macro...
%%# \toolboxIf\undefined{\long\def}\macro{....}
%%# \toolboxIf\undefined\newcommand{\macro}{....}
%%#
%%# are similar to \def\macro{...} resp. \let\macro... resp.
%%# \long\def\macro{...} resp. \newcommand{\macro}{...} with the difference
%%# that \macro is not changed if it was already defined.
%%# In this sense, \toolboxIf is a more flexible variant of \providecommand.
%%#

%%# \toolboxNewiftrue{name} or \toolboxNewiffalse{name}
%%#
%%# If the command \ifname was already introduced with \newif, then
%%# nothing happens. Otherwise \ifname is introduced similarly to
%%# \newif\ifname and set to `true' respectively `false'.
%%# In contrast to the corresponding command in TeX or LaTeX 2.09, this macro
%%# is not \outer!

%%# \toolboxNewifTrue{name} or \toolboxNewifFalse{name}
%%#
%%# are similar to \toolboxNewiftrue{name} and \toolboxNewiffalse{name},
%%# respectively, with the difference that \ifname is set unconditionally
%%# to `true' respectively `false'.

%%#
%%# Concatenated macro names
%%# ------------------------

%%# \toolboxLet\variable{macroname}
%%#
%%# The above command is analogous to \let\variable\macroname with the
%%# difference that macroname can also contain other tokens like numbers
%%# (it is obtained via \csname). Some converse to this command is
%%#
%%# \toolboxWithNr {number}\cmd{macro}
%%#
%%# which translates into \cmd\macronumber (here, `macro' and `number'
%%# are just concatenated and evaluated via \csname).
%%# Examples:
%%#   \toolboxWithNr 1\let{name}\toolboxEmpty
%%#        This is the same as \let\name1\toolboxEmpty
%%#            (but such that \name1 is considered as a name, not as \name 1)
%%#   \toolboxWithNr {10}\def{name}{Foo}
%%#        This corresponds analogously to \def\name10{Foo}.
%%#   \toolboxLet \mymacro{name\the\mycount}
%%#        This is similar to \let\mymacro\namexx where xx is the content
%%#        of the counter \mycount.

%%#
%%# Various
%%# -------

%%# The following macros have equivalents in most formats (like LaTeX2e).
%%# However, we do not want to rely too much on these formats, so we provide
%%# our own definitions.
%%# The macro
%%#    \toolboxEmpty
%%# expands to nothing (usually, this is the same as \empty).
%%# Similarly, the macro
%%#    \toolboxSpace
%%# expands to a space symbol (usually, this is the same as \space).
%%# The token
%%#    \toolboxSpaceToken
%%# is \let a space token (usually, this is the same as \@sptoken).
%%# This token is convenient in tests of tokens
%%# (because it is hard to get a space there which is not eaten by the TeX
%%#  parser, although sometimes also constructions like
%%#  \expandafter\ifx\toolboxSpace\token can be used).
%%# Also the macros
%%#    \toolboxFirstOfTwo
%%#    \toolboxSecondOfTwo
%%# are provided which read two arguments and return only the first
%%# respectively second argument (usually, this is the same as
%%# \@firstoftwo respectively \@secondoftwo). Similarly,
%%#    \toolboxGobbleArg{argument}
%%# just reads its argument and expands to nothing.

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