summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/varindex/varindex.txt
blob: 7adfcf61f0a7d3bb9b31ad2c21685cc202307b37 (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
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258

%%#
%%# Author:
%%#
%%# M. V\"ath      martin@mvath.de
%%#
%%# This package bases on ideas of indextwo.sty which was written jointly with
%%#
%%# O. Karch       karch@informatik.uni-wuerzburg.de
%%# H.-C. Wirth    wirth@informatik.uni-wuerzburg.de

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

%%#############################################################################
%%#
%%#  This LaTeX package provides a luxury front-end for the \index command.
%%#  For example, it allows to generate multiple \index entries in
%%#  almost any form by a single command. Extremely customizable.
%%#  Works with all versions of LaTeX and probably most other TeX formats, too.
%%#  This package requires the toolbox package at least in version 3.1.
%%#
%%#############################################################################

%%#
%%# This package was tested with LaTeX 2.09 and LaTeX 2e and should work
%%# with all other (future) versions of LaTeX and friends, too.
%%# It should even run with other (non-LaTeX) formats if an \index command
%%# with LaTeX-Syntax is provided.
%%#


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

%%#
%%# I strongly recommend to have additionally a look at the documentation
%%# of the "toolbox" package, in particular the \toolboxMakeDef command
%%# (provided since toolbox v3.1) which supplements \varindex.
%%#

%%#
%%# The \varindex command is highly customizable.
%%# So the following examples can only give you a rough impression of what
%%# you can actually do with it. You do not need to understand them now:
%%# The general usage is explained later. (Maybe you want to look up the
%%# examples afterwards).
%%#
%%#
%%# 1. Typical example of usage (using the \varindextwo macros):
%%#
%%#
%%#
%%# Suppose the following customization of the \varindex command was defined:
%%#     \def\Index{\varindex(){\varindextwoScan}{\varindextwo}[\emph]}
%%# Since we used the \varindextwo macros here, by default
%%# TWO index entries are generated with a single command:
%%#
%%# \Index{ring with $1$@one}
%%#
%%# ring
%%#    ~ with $1$            [sorted like: "with one"]
%%#
%%# $1$                      [sorted like: "one" ]
%%#    ring with ~           [sorted like: "ring with" (without " ~") ]
%%#
%%# DIFFERENT entries may be generated by your own rules. E.g.:
%%#
%%# \Index{Hausdorff measure of noncompactness}[4,23 2!~34!1= ]
%%#
%%# generates THREE index entries:
%%#
%%# noncompactness, measure of ~ (sorted like "noncompactness, measure of")
%%#
%%# measure
%%#   ~ of noncompactness
%%#         Hausdorff =    (here, = stands for the $\approx$ symbol)
%%#
%%# Hausdorff measure of noncompactness
%%#
%%# The last of these entries occurs only, because the last character in
%%# the format argument [...] was a space.
%%#
%%# If you want only slight modification(s) of the default, you need also just
%%# slight modifications of the command, e.g.
%%#
%%# \Index*,{ring with $1$@one} is as above, just that the second entry reads
%%#
%%# $1$, ring with ~  [sorted like "one, ring with" ]
%%#
%%# Moreover, since the `*' occured in the previous command, additionally
%%#
%%# \emph{ring with $1$}
%%#
%%# appears in the running text. Praxis shows that changes in the entries as
%%# above have to be made frequently in the `fine tuning' of the index of a
%%# book. Note that with the original \index the command would have to be
%%# changed completely for the above entries, because we have a "sort" entry
%%# for which a different rule applies if we use a subitem instead of a ",".
%%# (BTW: \varindex produces sort entries only if they are necessary).
%%#
%%# Of course, you may combine the default with your own format:
%%#
%%# \Index{internal integrable function}[23,1~ +]  generates
%%#
%%# integrable function, internal ~
%%#
%%# internal
%%#    ~ integrable function
%%#
%%# function
%%#    internal integrable ~
%%#
%%#
%%# 2. A simple example without the \varindextwo macros:
%%#
%%# \varindex*{topology of a normed space}{5!4~!1= 45,12}[|see{norm}]
%%#
%%# produces the two index entries:
%%#
%%#  space
%%#     normed ~
%%#         topology =
%%#
%%#  normed space, topology of
%%#
%%# In both entries not the pagenumber is cited, but the text "see also norm".
%%# Additionally, the tokens {topology of a normed space} are
%%# inserted into the running text (this would not happen if
%%# \varindex is used in place of \varindex*).
%%# Only in the first of the above entries, an `@' part will be added to the
%%# *.idx file: This entry is sorted as if " ~" resp. " =" would not exist.
%%#
%%#
%%# 3. Another example without the \varindextwo macros:
%%#
%%# \varindex[\emph][|textbf]%
%%#     {$\sigma$@sigma!$(\sigma-)$ finite {measure space}}%
%%#     {*1.23 23 23,1- 1-23}
%%#
%%# generates the three index entries:
%%#
%%#  finite measure space
%%#
%%#  finite measure space, $\sigma$- (sorted as "finite measure space, sigma-")
%%#
%%#  $\sigma$-finite measure space   (sorted as "sigma-finite measure space")
%%#
%%# In all three entries the pages are printed using \textbf.
%%#
%%# Moreover, the tokens
%%#   \emph{($\sigma$-)finite measure space}
%%# are put into the running text.
%%#
%%#
%%# 4. A simple example using a flag (without the \varindextwo macros):
%%#
%%# \varindex1{$L$ and $M$@L and M}{}
%%#          ^
%%#
%%# generates the index entry "$L$ and $M$" which is sorted like "L and M".
%%# In the form
%%#   \varindex1*{$L$ and $M$@L and M}{}
%%# or
%%#   \varindex*1{$L$ and $M$@L and M}{}
%%# additionally, {$L$ and $M$} is output into the running text.
%%#
%%# Note that without the `1', the index generated were
%%# "$L$ and $M$ and M" which were sorted like "$L$ and L and M".
%%#
%%#
%%# 5. An example for very primitive customized index commands (without the
%%#    \varindextwo macros):
%%#
%%# \def\myindexA{\varindex[\emph][|textbf]*}
%%# \def\myindexB{\varindex(){}{}[\emph][|textbf]}
%%#
%%# \myindexA{Foo1}{}
%%# \myindexB{Foo2}[][]
%%# \myindexB*{Foo3!{Foo 3}}
%%#
%%# Generates the index entries Foo1, Foo2, and Foo3. Moreover, \emph{Foo1}
%%# and \emph{Foo 3} is put into the running text. The pagenumber of Foo 2 in
%%# the index is printed normal, the others with \textbf.
%%#
%%#
%%# 6. An example of a primitive customized index command (without the
%%#    \varindextwo macros):
%%#
%%# \def\myindex{\varindex(\ifnum\varindexCount=2 1!2 2,1\fi){}{}[\emph]}
%%#
%%# \myindex{Foo Bar}
%%#    generates the index entries
%%#     Foo
%%#        Bar
%%#
%%#     Bar, Foo
%%#
%%# \myindex*{Foo Bar}
%%#    generates the same index entries as above and additionally outputs
%%#    \emph{Foo Bar} into the running text.
%%#
%%# \myindex*{other format}[21]
%%#   generates the index entry
%%#     format other
%%#   and outputs \emph{other format} into the running text.
%%#
%%# \myindex[|textbf]*{BoBo}
%%#   generates the index entry
%%#      BoBo
%%#   where the pagenumber is printed with \textbf.
%%#   Moreover, \emph{BoBo} is output into the running text.
%%#
%%#
%%# 7. A primitive varying customized index command (without the \varindextwo
%%#    macros):
%%#
%%# \def\myindex{\varindex(\ifnum\varindexCount=2 1!2 2,1\fi)%
%%#     (\ifnum\varindexCount=2*2,1 1!2 2,1\fi){}{}[\emph]}
%%#
%%# With the same commands as in 6. the same index entries are generated,
%%# but the tokens \emph{Far, Boo}, \emph{other format}, and \emph{Bobo}
%%# are output into the running text.
%%#
%%#
%%# 8. Examples with the \varindextwo macros:
%%#    We use a similar definition for \Index as in 1., and define an \iemph
%%#    macro which has `*' as a default and outputs with \emph.
%%#    Both sort of definitions are highly recommended for you private style.
%%#
%%# \def\Index{\varindex(){\varindextwoScan}{\varindextwo}[]}
%%# \def\iemph{\varindex(){\varindextwoScan\def\varindexStarPos{}}%
%%#              {\varindextwo}[\emph]}
%%# (note that \def\iemph{\varindex(){\varindextwoScan}{\varindextwo}[\emph]*}
%%#  is not so good as the above definition of \iemph as is explained below).
%%#
%%# \Index*{measure of $\gamma$-noncompactness@gamma-noncompactness!FOO}
%%#
%%#   generates the index entries
%%#
%%#   measure
%%#      ~ of $\gamma$-noncompactness   (sorted as "of gamma-noncompactness")
%%#
%%#   $\gamma$-noncompacntess
%%#      measure of ~
%%#
%%#   and outputs the tokens {measure of FOO} into the running text.
%%#
%%# \Index*,?_'{flic of flac}  generates
%%#
%%#   flic of flac
%%#
%%#   flac, flic
%%#
%%#   and outputs {flic of flac}.
%%#
%%# \Index^={$\sigma$@sigma algebra} generates
%%#
%%#   $\sigma$ (sorted as "sigma")
%%#      ~-algebra   (sorted as "algebra" resp. "-algebra", see below)
%%#
%%#   algebra
%%#      $\sigma$-~  (sorted as "sigma-")
%%#
%%# Here, the sorting "-algebra" is chosen when you used
%%#    \let\varindexOutSortDashBeg\varindexOutSortDash
%%# as described later.
%%#
%%# \Index-^>{$\sigma$@sigma algebra} generates
%%#
%%#   $\sigma$- (sorted as "sigma-")
%%#      ~ algebra   (sorted as "algebra")
%%#
%%# \Index^.,:{ultra filter} generates
%%#
%%#   ultra
%%#      ~filter        (no space following ~)
%%#   filter, ultra~    (no space in front of ~)
%%#
%%# \iemph[|see{recursive recursion}],_{recursive recursion}  generates
%%#
%%#  recursive recursion, \see{recursive recursion}
%%#
%%#  recursion, recursive ~, \see{recursive recursion}
%%#
%%#  and outputs \emph{recursive recursion}. If we would have used instead the
%%#  definition \def\iemph{\varindex(){\varindextwoScan}{\varindextwo}[]*},
%%#  the above call were not possible, since the optional arguments [|see...]
%%#  must occur in front of the flag `*'.
%%#
%%# \Index-;*{Flip Flop}   generates
%%#
%%#    Flip-Flop
%%#
%%#    FlopFlip
%%#
%%#    and outputs {Flip-Flop}  (!!!!!!!)
%%#
%%# \Index>{Flippy Flop!GO}[*2-1-2 2!1-1 1-12 +]
%%#
%%#   generates
%%#
%%#     Flop
%%#        Flippy-Flippy (no tilde!)
%%#
%%#     Flippy-Flippy Flop
%%#
%%#     Flippy
%%#        ~ Flop
%%#
%%#   and outputs {GO-Flippy-GO} (!!!)
%%#
%%# \Index*_,{shape {of a} of star}  generates
%%#
%%#    shape of a star
%%#
%%#    star, shape of ~ (sorted like "star, shape of")
%%#
%%# and outputs {shape of a star}.
%%#
%%# \Index1*{$L$ feature@L feature}
%%# \Index,{No $L$@L feature}
%%# generate
%%#
%%# $L$ feature (sorted like "L feature")
%%#
%%# No
%%#   ~ $L$ feature   (sorted like "L feature")
%%#
%%# feature, No $L$ ~ (sorted like "feature, No L")
%%#
%%# and outputs {$L$ feature}.
%%#
%%#
%%# 9. Example of a simple modification of the \varindextwo macros:
%%#
%%# \def\myindextwoScan{%
%%#      \varindextwoScan
%%#      \varindexNewFlag ~\vxtSpaceA
%%#      \varindexNewFlag 1\vxtSpaceB
%%#      \varindexNewFlag !\varindexOneEntry
%%#      \varindexMakeSplitExpand{/}{vxtSplitAtMagic}%
%%#      \def\varindexStarPos{}%
%%# }
%%# \def\myIndex{\varindex(){\myindextwoScan}{\varindextwo}[]}
%%#
%%# \myIndex behaves similar to the previous example with
%%# the following differences:
%%# 1. The flag `1' now has the previous meaning of "~".
%%# 2. One may now use "~" and "_" equivalently.
%%# 3. The flag `!' now has the originial meaning of the flag `1'.
%%# 4. Instead of `+' in the format string, the character `/' has to be used.

%%#
%%#
%%# Description:
%%#
%%# There are two possible calls:
%%#
%%# a) \varindex[textstyle][pagestyleA]flags{main entries}{format}[pagestyleB]
%%#
%%#    Here, [textstyle], [pagestyleA], [pagestyleB], and flags are optional.
%%#    (If [textstyle] is omitted, also [pagestyleA] must be omitted).
%%#
%%#    textstyle: describes the textstyle used for the output into the
%%#               running text (typically, textstyle is \emph or empty).
%%#    pagestyle: describes the pagestyle used for the output of the pagenumber
%%#               (you may also use a construct like |see{...} here).
%%#               If [pagestyleB] is present, this is the value used.
%%#               Otherwise, the value of [pagestyleA] is used (resp. nothing).
%%#    flags can be one (or both) of the following tokens:
%%#      `*': "Output into running text":
%%#           If no * is used in the format string (see below),
%%#           then the format is automatically prepended by the tokens `* '
%%#           resp. `*' (depending whether format starts with ` ' or not)
%%#      `1': The content of {main entries} is considered as a single entry
%%#           (see below).
%%#    {main entries} and
%%#    {format} are explained later.
%%#
%%# b) \varindex(formatA)(format*A){scanprogram}{mainprogram}
%%#         [textstyle][pagestyleA]flags{main entries}[formatB][pagestyleB]
%%#
%%#    Concerning [textstyle], [pagestyleA], flags, [pagestyleB], the same
%%#    remarks as in a) hold. Also (format*A) and (formatA) are optional.
%%#    (if (formatA) is omitted, also (format*A) must be omitted).
%%#
%%#    The "default" format is formatA resp. format*A (depending whether the
%%#    flag "*" has been used or not). If [formatB] is given, then this is
%%#    used as the format (i.e. it overrides the default).
%%#
%%#    scanprogram is executed immediately when \varindex reads it.
%%#    This can be used to introduce FURTHER flags (other than '*' and `1'),
%%#    see below.
%%#    mainprogram is executed AFTER the format string(s) has been expanded.
%%#
%%#
%%#
%%# It is recommended to define personal macros which contain all parameters up
%%# to the place where the flags occur (either with or without some flags,
%%# depending on the intention). See the examples above.
%%#
%%#
%%#
%%#
%%# The main argument (called {main entries} above) has the form
%%#
%%# entry1[`space' entry2][`space' entry3] ...
%%#
%%# where each of entry1 entry2 entry3 ...  in turn has the form
%%#   indextext@sorttext!outputtext or
%%#   indextext!outputtext@sorttext
%%# In each of these forms, @sorttext and !outputtext are optional.
%%# Here,
%%#   indextext  is the text which is put into the index for the entry
%%#   sorttext   is what is used as a sort criterion for the entry
%%#   outputtext is what is output into the running text for the entry
%%#
%%# Note that the symbol @ has in a sense the opposite meaning as in the
%%# original \index command:
%%# BEFORE that symbol, the desired text appears, and
%%# AFTER the symbol the place where it has to be sorted.
%%# However, we chose the symbols @ and !, because these two
%%# symbols are forbidden anyway (otherwise, makeindex will become confused).
%%#
%%# As usual, multiple spaces are considered as ONE space and do not generate
%%# empty "ghost" entries. Moreover, a space after a TeX-command like \LaTeX
%%# is eliminated by TeX and thus also not considered as a separator.
%%# You may use braces {...} either around a whole entry or
%%# around indextext resp. sorttext resp. outputtext to allow spaces
%%# which do not act as "separators" in the corresponding part. The braces
%%# around these parts will vanish. In particular, you may generate an
%%# empty entry with {} or ! or @ (bordered by spaces).
%%# If you want that braces occur in the OUTPUT, you have to add an
%%# additional pair of braces. Be aware that you write sufficiently
%%# many braces, if you really should need them: For example,
%%# the command \varindex{{{{A B}}}}{} produces the index entry {A B}:
%%# The outermost pair of braces is eliminated immediately by TeX. The second
%%# pair is eliminated, because this is a pair around a complete entry.
%%# Finally, another pair is eliminated, because it is a brace around
%%# indextext.
%%# With the flag `1', {main entries} is considered as one single entry.
%%# Nevertheless, also with this flag, an additional pair of braces around
%%# main entry is eliminated.
%%#
%%#
%%# The format string  has one of the following three forms
%%#   indexa[`space' indexb][`space' indexc] ... [*outputa][*outputb] ...
%%#   [*outputa][`space' indexa][`space' indexb][*outputc] ...
%%#   *
%%# where the order of arguments can be arbitrarily mixed (except for the first
%%# indexa in the first form). indexa indexb ... outputa ... describe the
%%# format of the index entries resp. of the output into the running text.
%%# The output is generated in the given order (this might be important, if
%%# a pagebreak occurs during the output into the running text).
%%# The last case is exceptional and equivalent to `*space'.
%%# The following characters/strings describe the format:
%%#
%%#  1-9: entry1-9
%%#  0:   entry 10
%%#  ~:   a placeholder sign
%%#  =:   alternative placeholder sign
%%#  _:   a space character
%%#  s:   The token \space (but _ is used for the sort entry)
%%#  .:   No space will follow
%%#  ,:   The character , (space will follow)
%%#  -:   The character - (no space will follow)
%%#  !:   Create a new sublevel
%%# All other tokens in this argument are forbidden.
%%# The token ! makes no sense for the output in the running text and thus
%%# is forbidden behind *.
%%#
%%# By a heuristic rule, a space is automatically inserted between two entries
%%# which generate non-empty text.  If the heuristic rule fails, you may always
%%# force a space by either "_" or "s", or forbid a space by ".".
%%#
%%# If a format is empty, all entries are taken in the order of input.
%%# Note that TeX eliminates concatenated spaces, and so you are able to
%%# produce an empty format entry only at the end or in front of a `*'.
%%# If you want to force an empty OUTPUT (is this ever useful?), you may use
%%# just "." as the entry.
%%#
%%# A sort entry is only written to the *.idx file if it differs from the
%%# text entry.

%%#
%%#
%%# Description of the \varindextwo macros:
%%#
%%# The macros
%%#
%%#   \varindextwoScan \varindextwo
%%#
%%# can be used together as parameters {scanprogram} resp. {mainprogram}
%%# for the \varindex command.
%%# If \varindex is called with these macros, and no
%%# explicit format argument is given, these macros generate a format
%%# depending on the number of entries in {main entries}:
%%#
%%# a) If there is only one entry in {main entries},
%%#    then the format "1" resp. "*1 1" is generated
%%#    (depending whether the * flag was used or not), i.e. the
%%#    entry is put into the index, and printed if \varindex was
%%#    called with the * flag.
%%#
%%# b) If there are two main entries like {graulty bazola},
%%#    then the format becomes { 1!~2 1!2~}, i.e. the index entries
%%#
%%#    graulty
%%#      ~ bazola
%%#
%%#    bazola
%%#       graulty ~
%%#
%%#    are produced.
%%#
%%#    You can modify the first format entry with the following flags:
%%#     flags  format used:           If used with `*' additionally:
%%#      _     12                     *12
%%#      -     1-2                    *1-2
%%#      ^     1!~-2 resp.  1!-2      *1-2
%%#      -^    1-!~.2 resp. 1-!~2     *1-2
%%#      .     1.2                    *1.2
%%#      .^    1!~.2                  *1.2
%%#      /     1!2   (without ~)      *12
%%#      <     no entry               *12
%%#
%%#    Here, the combinations -^ and .^ mean that both flags are used
%%#    (the order plays no role).
%%#    The output for ^ respectively -^ is determined by the switches
%%#        \varindextwoDashTildetrue (default)
%%#        \varindextwoDashTildefalse
%%#        \varindextwoDashSpacetrue
%%#        \varindextwoDashSpacefalse   (default)
%%#
%%#    You can modify the second format entry with the following flags:
%%#     flags  format used:
%%#      ,     2,1~ resp. 2,1
%%#      ~     21
%%#      =     2!1-~
%%#      ,=    2,1-~ resp. 2,1-
%%#      +     2-1
%%#      :     2!1.~
%%#      ,:    2,1.~ resp. 2,1
%%#      ;     2.1
%%#      >     no entry
%%#      !     Append ~ (if not already there)
%%#      ?     Without ~
%%#
%%#    Whether the first or the second alternatives in the above forms is used
%%#    depends on the status of the switch
%%#          \varindextwoCommaTildetrue   (default)
%%#          \varindextwoCommaTildefalse
%%#    We point out that "\varindextwoCommaTildefalse" was in earlier versions
%%#    of "varindex" the default (and could not be changed).
%%#    Note that this switch has no effect if the ! or ? flags are used.
%%#
%%#    HINT for remembering the symbols: The symbols _ . - for the first entry
%%#    are the same flags as for the output and the same flags which are used
%%#    in the format string. The corresponding symbols ~ : (and ;) = (and +)
%%#    for the second entry "look similar". The "," is only useful in the
%%#    second entry (and is the same symbol as in the format string).
%%#    The two exceptional symbols ">" and "<" can be read as "generate only
%%#    the forward-directed resp. backward-directed entry".
%%#
%%# c) If there are three main entries like {graulty of bazola}, then the
%%#    format becomes { 1!~23 3!12~}, i.e. the output becomes
%%#
%%#    graulty
%%#      ~ of bazola
%%#
%%#    bazola
%%#      graulty of ~
%%#
%%#    The flags have an analogous effect to b).
%%#    In addition, if the flags  ` resp. ' are used, the second word
%%#    (in our example: `of') is omitted from the output in the first resp.
%%#    in the second index entry. If the * flag and ` are used together, the
%%#    second entry is also omitted from the output into the running text.
%%#
%%# d) If there are four main entries like {graulty of OF bazola}, then the
%%#    format becomes { 1!~24 4!31~}, i.e. the output becomes
%%#
%%#    graulty
%%#      ~ of bazola
%%#
%%#    bazola
%%#      graulty OF ~
%%#
%%#    i.e. we have a similar effect as in c) except that for the first entry
%%#    the third word is skipped, and for the second entry the second word is
%%#    skipped. All flags as in c) can be used with an analogous meaning.
%%#    Also if the * flag is used, the output into the running text is
%%#    analogous to c) (the third word is skipped).
%%#
%%# e) If there are more than four main entries, then
%%#    (formatA) resp. (format*A) is used.
%%#
%%# If an explicit format argument is provided, then this is used except
%%# when it contains the symbol +. In this case, this symbol is replaced by the
%%# output which would be generated "normally". If additionally the `*'-flag
%%# is used, there is a special rule:
%%# If the explicit format contains a `*', then no additional `*'-output is
%%# produced. Otherwise, the `*'-output from a)-e) is prepended to the given
%%# format string (with a space at the end, unless the format string is empty).
%%# This means that `normally' you have the output from a)-e),
%%# unless you write an own `*'-part in the argument.
%%#
%%# If you do not like the tokens chosen for the default symbols, you can
%%# easily choose your own tokens by just replacing \varindextwoScan with your
%%# own macro (or defining your own ``magic'' tokens after \varindextwoScan,
%%# see Example 9. above).

%%#
%%#
%%# Primitive customization:
%%#
%%#
%%# You may use the command
%%#     \varindexUsePlaceholderAfalse
%%#     \varindexUsePlaceholderBfalse
%%# to ignore the sign ~ resp. = in the format entry.
%%# You can easily restore the default by
%%#     \varindexUsePlaceholderAtrue
%%#     \varindexUsePlaceholderBtrue
%%#
%%# If you want to switch off the placeholder only at the beginning of
%%# a new entry (resp. of a new subentry), you can use the commands
%%#     \varindexLeadingPlaceholderAfalse
%%#     \varindexLeadingPlaceholderBfalse
%%# The default is restored with
%%#     \varindexLeadingPlaceholderAtrue
%%#     \varindexLeadingPlaceholderBtrue
%%#
%%# By default, the "," in the format string is in this connection
%%# treated as a symbol generating a new "subentry". You can change this
%%# default with the command
%%#  \varindexCommaLeadsfalse
%%# You may switch back with
%%#  \varindexCommaLeadstrue
%%#
%%#
%%# The content of the macro
%%#   \varindexPlaceholderAText
%%#   \varindexPlaceholderASort
%%#   \varindexPlaceholderBText
%%#   \varindexPlaceholderBSort
%%# is used as the placeholder ~ resp. =  in the index resp. sort entry.
%%# Note that if one of these entries expands empty, different rules for
%%# the automatic insertion of spaces apply (for the index and sort entry
%%# separately).
%%#
%%# You may prefer that the placeholder text resp. sort content changes at
%%# run time to the context of the previous ! entry. For example, you may
%%# want that the command \varindex{Gibble Gobble}{2!~2} produces the index
%%# entry
%%#   Gibble
%%#     Gibble Gobble
%%# (or is at least SORTED as such an entry).
%%#
%%# You can achieve this with the commands
%%#  \varindexPreviousATexttrue
%%#  \varindexPreviousASorttrue
%%#  \varindexPreviousBTexttrue
%%#  \varindexPreviousBSorttrue
%%# for the text and sort entry and the placeholders ~ and =, respectively.
%%# With these commands, the content of \varindexPlaceholderAText etc
%%# is only used as the default if no previous ! entry was given.
%%# You can switch back to the default mode with the respective commands
%%#  \varindexPreviousATextfalse
%%#  \varindexPreviousASortfalse
%%#  \varindexPreviousBTextfalse
%%#  \varindexPreviousBSortfalse
%%#
%%# By default, the ',' in the format entry is considered in this connection
%%# similar to '!'. If you want to change this, use the command
%%#  \varindexCommaExpandfalse
%%# You may switch back with
%%#  \varindexCommaExpandtrue
%%#
%%# Since version 2.2, the dash "-" occurring at the beginning of entry
%%# (or after "!" or even after "," if \varindexCommaExpandtrue is in effect)
%%# is ignored for sorting. You can switch off this feature with the command
%%#
%%#   \let\varindexOutSortDashBeg\varindexOutSortDash
%%#
%%# To restore the new default, use
%%#
%%#   \let\varindexOutSortDashBeg\toolboxEmpty
%%#
%%#
%%# The commands
%%#
%%#   \varindexSetWordString{|}     % Use | as separator for entries instead
%%#                                 % of spaces.
%%#   \varindexSetSortString{>}     % default: @
%%#   \varindexSetPlainString{<}    % default: !
%%#
%%# set the default "magic" strings used for the main argument.
%%# The argument of the above macros is intentionally NOT expanded (so that
%%# you do not have troubles with active characters like ~).
%%# To force expansion, use e.g.
%%#   \expandafter\varindexSetWordString\expandafter{\MacroToExpand}
%%# or some similar construct.
%%#
%%# If you use a different separator than `space' for the entries, you may want
%%# to change the rule how braces are eliminated. With the commands
%%#   \varindexEliminateOuterBracetrue
%%#   \varindexEliminateInnerBracetrue
%%#   \varindexEliminateOuterBracefalse
%%#   \varindexEliminateInnerBracefalse
%%# you may allow resp. forbid the elimination of braces around the entries
%%# resp. around {indextext} {sorttext} and {outputtext}
%%# With the flag `1', {main entries} is considered as one single entry,
%%# but if \varindexEliminateOuterBracetrue is set (which is the default)
%%# also in this case an additional pair of braces around main entry is
%%# eliminated.
%%#
%%# Similarly as above,
%%#
%%#   \varindexSetIndexString{|}    % default: space
%%#   \varindexSetOutputString{<}   % default: *
%%#   \varindexSetTildeAString{~}   % (is default)
%%#   \varindexSetTildeBString{=}   % (is default)
%%#   \varindexSetSpaceString{_}    % (is default)
%%#   \varindexSetSpaceTokString{s} % (is default)
%%#   \varindexSetOmitString{.}     % (is default)
%%#   \varindexSetCommaString{,}    % (is default)
%%#   \varindexSetDashString{-}     % (is default)
%%#   \varindexSetExclamString{!}   % (is default)
%%#   \varindexSetStringForNr 1{a}  % default: 1
%%#   \varindexSetStringForNr{11}{b}% No default!
%%#
%%# sets the default "magic" strings used for the format argument.
%%# In contrast to before, the arguments are fully expanded (with
%%# \varindexedef, see below).
%%# Note that the last command provides a way to access more than 10 entries!
%%#
%%# If you use \varindexSetIndexString{|} (with some non-space token),
%%# you may still use spaces in the format which then are just ignored.
%%#
%%#
%%# Avoid that one string is a prefix of another string: In this case,
%%# strange effects may happen, and this behavior may even change in
%%# future releases of this package.
%%# Note that the above effect may arise unintentionally if you use active
%%# chars. For this reason, `~' is defined to expand to the letter `~',
%%# before the expansion is executed. Maybe in later releases of this package
%%# there will be further such redefinitions.
%%# You can explicitly use this feature in your own macros by using
%%# \varindexedef instead of the usual \edef, see below.
%%#
%%#
%%# You can change the output for the text resp sort entry of the various
%%# symbols used in the format string. More precisely, you can redefine
%%#
%%#     \varindexOutExclam     % Text output for !
%%#     \varindexFollowsExclam % Decide whether magic space after ! is inserted
%%#     \varindexOutTextComma  % Text output for ,
%%#     \varindexOutSortComma  % Sort output for ,
%%#     \varindexFollowsComma  % Decide whether magic space after , is inserted
%%#     \varindexPreceedsComma % Decide whether magic space before , is erased
%%#     \varindexOutTextSpace  % Text output for _
%%#     \varindexOutSortSpace  % Sort output for _
%%#     \varindexFollowsSpace  % Decide whether magic space after _ is inserted
%%#     \varindexPreceedsSpace % Decide whether magic space before _ is erase
%%#     \varindexOutTextSpTok  % Text output for s
%%#     \varindexOutSortSpTok  % Sort output for s
%%#     \varindexFollowsSpTok  % Decide whether magic space after s is inserted
%%#     \varindexPreceedsSpTok % Decide whether magic space before s is erased
%%#     \varindexOutTextDash   % Text output for -
%%#     \varindexOutSortDash   % Sort output for -
%%#     \varindexOutSortDashBeg% Sort output for - if nothing preceeds
%%#     \varindexFollowsDash   % Decide whether magic space after - is inserted
%%#     \varindexPreceedsDash  % Decide whether magic space before - is erased
%%#     \varindexOutTextOmit   % Text output for .
%%#     \varindexOutSortOmit   % Sort output for .
%%#     \varindexFollowsOmit   % Decide whether magic space after . is inserted
%%#     \varindexPreceedsOmit  % Decide whether magic space before . is erased
%%#
%%# The meaning is as follows: \varindexOut... should just expand to the
%%# tokens which should be written into the text resp. sort output.
%%# The corresponding macro \varindexFollows... is typically defined with
%%# one of the following commands:
%%#     \let\varindexFollows...\varindexNextSpace
%%#     \let\varindexFollows...\varindexNoNextSpace
%%# In the first case, a space is `magically' inserted in front of a
%%# subsequent token (unless this token erases the magic space).
%%# In the second case, no space follows, of course.
%%# There is an alternative call:
%%#     \def\varindexFollows...{\varindexSpaceTexttrue\varindexSpaceSortfalse}
%%# This definition achieves that for the text output a space should follow,
%%# but not for the sort output. Of course, you can also use similarly the
%%# commands \varindexSpaceTextfalse and/or \varindexSpaceSorttrue
%%# in the above definition (the effect should be obvious).
%%# In particular, \varindexNextSpace is equivalent to
%%# \varindexSpaceTexttrue\varindexSorttrue.
%%#
%%# The macro \varindexPreceeds... is similarly as \varindexFollows... with
%%# the difference that it is executed BEFORE the token in question is
%%# output. In particular, you can ignore a previous `magic space'.
%%# All of the `magic space' commands are defined by default with
%%#      \let\varindexFollows...\toolboxEmpty
%%#      \let\varindexPreceeds...\varindexNoNextSpace
%%# with the following two exceptions:
%%#      \let\varindexFollowsExclam\varindexNoNextSpace
%%#      \let\varindexFollowsComma\varindexNextSpace
%%#
%%# Documented Features (in later versions, these will still be available,
%%#  and if they contain a bug now, they will be repaired to work this way):
%%#
%%# (In a future release, varindex will cook your coffee, too)
%%#
%%#
%%#
%%# The main argument is NOT expanded, so you can actually write macros
%%# into the *.idx file. The command actually used to write the index is
%%#
%%#      \varindexIndex
%%#
%%# (which by default is of course defined as \index).
%%# Since some implementations of the \index command still (partially) expand
%%# their argument (which might be considered as a bug), the argument of
%%# \varindexIndex is translated before the actual call with the aid of
%%# \toolboxMakeHarmless.
%%# If you want to redefine \varindexIndex to a personal \index-output
%%# function, you might want to skip the \toolboxMakeHarmless step.
%%# This is arranged with the command
%%#
%%#    \varindexNoConvert
%%#
%%# You can cancel the effect of this command with
%%#
%%#    \varindexDoConvert
%%#
%%# Even if \varindexNoConvert is not in effect, the main argument is not
%%# expanded (and in particular, the argument of \varindexIndex consists of
%%# the corresponding entries in an unexpanded form).
%%#
%%# The whole \varindex... procedure takes place in a group, so all your
%%# variables are local to a single call (unless you use \gdef...
%%# (and friends) of course).
%%#
%%# There are no \global directives in any macro related with this package.
%%# In particular, if you call the above macros in a group (or redefine
%%# \varindexIndex), the effect holds only until the end of the group.
%%#
%%# In contrast to the main argument, the format argument is expanded
%%# (with \varindexedef, see below)
%%# (and also formatA resp. format*A is expanded before),
%%# so you can define abbreviations (even simple conditional abbreviations)
%%# for the format. Note, however, that the expansion is essentially only
%%# evaluated with \edef. So, you will probably not want to use e.g. \relax,
%%# since this command expands to itself (and  not into nothing - use
%%# \toolboxEmpty if you want the latter).
%%# If you want more complex abbreviations, use {mainprogram} instead.
%%#
%%# In order to help you write conditional abbreviations, the
%%# following variables are defined when your macro is expanded (and in
%%# particular also in {mainprogram}). You may of course redefine them
%%# appropriately:
%%#
%%#    \varindexAppend     The argument pagestyleA resp. pagestyleB.
%%#    \varindexCount      a TeX counter containing the number of entries in
%%#                        the main argument.
%%#    \varindexLastEntry  This is a macro (NOT a counter) which is usually
%%#                        the value of \the\varindexCount. See below.
%%#    \varindexEntry1-... The (index) text occuring in entry 1-...
%%#    \varindexSort1-...  The corresponding sort entry. If no sort entry was
%%#                        given, this is the same as the corresponding
%%#                        \varindexEntry1-...
%%#    \varindexPlain1-... The text which should be output in the text. If no
%%#                        such entry was given, this is the same as the
%%#                        corresponding \varindexEntry1-...
%%#
%%# \varindexCount may be larger than 10, and correspondingly there may be
%%# also more than 10 different \varindexEntry/Sort/Plain macros.
%%# If you ADD entries, you have to increase \varindexCount correspondingly,
%%# otherwise an error is produced if the format string contains an entry
%%# larger then \varindexCount. However, your additional entries are NOT
%%# output for EMPTY formats: For empty formats the number used is
%%# \varindexLastEntry. So if you want to output also your additional entries
%%# in empty formats, you have to set \varindexLastEntry to your modified
%%# value of \varindexCount in mainprogram. You may e.g. achieve this with
%%# the following lines:
%%#   \expandafter
%%#   \def\expandafter\varindexLastEntry\expandafter{\the\varindexCount}%
%%# It is admissible that \varindexLastEntry is larger than \varindexCount:
%%# In this case all entries until \varindexLastEntry are
%%# output in empty formats without producing an error (provided, of course,
%%# that the corresponding variables \varindexEntry.../Sort.../Plain... are
%%# defined).
%%#
%%# Note that numbers in TeX command names require special handling,
%%# i.e., you have to use something like
%%#
%%# \csname varindexPlain2\endcsname
%%#
%%# to access variables. To avoid this, you may want to use the macros
%%# \toolboxLet and \toolboxWithNr of the toolbox package. Examples are
%%#   \toolboxWithNr 1\let{varindexEntry}\toolboxEmpty
%%#   \toolboxWithNr {10}\def{varindexSort}{Foo}
%%#   \toolboxLet    \mymacro{varindexPlain\the\mycount}
%%# These commands set \varindexEntry1 to \toolboxEmpty, \varindexSort10 to
%%# Foo, and \mymacro to the content of \varindexPlain5 (if \mycount=5).
%%#
%%# All these variables are also available when {mainprogram} is expanded.
%%# In {mainprogram} also the following functions are useful:
%%#
%%# \varindexFormat
%%#    This macro expands to the actual format string which is used.
%%#    The main purpose of {mainprogram} will usually be to (re)define
%%#    this macro. After {mainprogram} has been called, this macro is
%%#    modified in several ways:
%%#    1. \varindexFormat is expanded (with \varindexedef, see below).
%%#       (thus, \varindexFormat is expanded BEFORE AND AFTER the call
%%#        of {mainprogram}).
%%#    2. \ifvarindexStar is true (see below) a `*' resp. `* ' is prepended.
%%#    3. If it is only "*", it is replaced by "* ".
%%#    Note that before execution of {mainprogram}, no tests on the
%%#    validity of the format are done: You may use your own symbols to
%%#    `communicate' with {mainprogram} (if {mainprogram} eliminates these
%%#    symbols afterwards).
%%#
%%# \varindexFormatDefault
%%#    This macro expands to formatA resp format*A (in the expanded form)
%%#    depending whether the * flag has been used in the call.
%%#    Note that this expansion was executed BEFORE the optional format
%%#    argument is expanded for the first time.
%%#
%%# \ifvarindexStar ifpart [ \else elsepart] \fi
%%#    If the optional * was given, the ifpart is executed, otherwise the
%%#    else-part. This is a TeX-if-command. In particular, by
%%#    \varindexStarfalse resp. \varindexStartrue
%%#    you may change the behavior for future if's. This can be used
%%#    to prevent/force that a `*' resp. `* ' is prepended to the format
%%#    after the execution of {mainprogram}.
%%#    Setting of this variable has no effect in {scanprogram}
%%#
%%# \ifvarindexExplicitFormat
%%#    This is a TeX-if-command (see above) which is true if the optional
%%#    format argument [formatB] was given.
%%#
%%#
%%# To "compose" the format, you may want to use the macros
%%#
%%# \toolboxDef\macrotodefine{argumentlist}
%%# \toolboxAppend\macrotoappend{argumentlist}
%%# \varindexedef\macrotodefine{argumentlist}
%%#
%%# All commands work similar to \def resp. \edef with two differences:
%%#
%%# For \toolboxDef\macro the argumentlist is expanded precisely by one level
%%# (for details, see the documentation of the toolbox package).
%%# Of course, for \toolboxAppend, the new definition is appended to the old
%%# definition of \macro.
%%#
%%# \varindexedef fully expands argumentlist. However, some active symbols
%%# (currently only ~, but additional symbols might follow in a future release)
%%# are deactivated before expansion, so that ~ actually expands to ~ and not
%%# to a strange command sequence.
%%#
%%#
%%# To "decompose" the format, you may want to use one of the macros
%%#
%%# \toolboxSplitAt{arg}{critical}{\before}{\after}
%%# \toolboxMakeSplit{critical}{command} resp.
%%# \varindexMakeSplitExpand{\MacrosWhichExpandToCritical}{command}
%%# \varindexMakeVarSplit\variable{\MacrosWhichExpandToCritical}{command}
%%#
%%# The first two macros are described in the toolbox package.
%%# The remaining two macros are similar to \varindexMakeSplit with the
%%# difference that the argument {critical} is obtained by expanding
%%# \MacrosWhichExpandToCritical with the aid of \varindexedef.
%%# In the last form, additionally \variable is (re)defined to expand to
%%# the value of critical.
%%#
%%# The following instances of a command created by \toolboxMakeSplit
%%# exist (the content of "critical" should be obvious):
%%#
%%# \varindexSplitAtIndex   (generated by \varindexSetIndexString)
%%# \varindexSplitAtOutput
%%# \varindexSplitAtTildeA
%%# \varindexSplitAtTildeB
%%# \varindexSplitAtSpace   <- Here the default content of "critical" is "_"
%%# \varindexSplitAtSpaceTok<- Here the default content of "critical" is "s"
%%# \varindexSplitAtOmit
%%# \varindexSplitAtComma
%%# \varindexSplitAtDash
%%# \varindexSplitAtExclam
%%# \varindexSplitAtNr?? (here, ?? is the number as a string; use
%%#    \csname ....\endcsname to call this macro. Only those numbers are
%%#    admissible which have been introduced with \varindexSetStringForNr
%%#    (this is the case for 1-10)).
%%#
%%# There is also the instance
%%# \varindexSplitSpace (to be distinguished from \varindexSplitAtSpace)
%%# where "critical" is the space symbol.
%%#
%%#
%%# In addition, you may use the variables
%%#   \varindexIndexString
%%#   \varindexOutputString
%%#   \varindexTildeAString
%%#   ....
%%#   \varindexNr??String
%%# which expand to the corresponding strings.
%%#
%%# All the previous macros should not be redefined `by hand'.
%%# They are implicitly redefined by the \varindexSet... commands.
%%#
%%#
%%#
%%#
%%# To drop possible braces, use the command
%%#
%%#   \toolboxDropBrace\variable
%%#
%%# of the toolbox package.
%%#
%%#
%%# In {scanprogram} you may already want to call \toolboxMakeSplit:
%%# In this way many choices for the tokens are put into {scanprogram},
%%# and in this sense, you can consider {mainprogram} as `customizable'.
%%# Anyway, the main task of {scanprogram} is to introduce new flags with
%%#
%%#   \varindexNewFlag\token\position[program\varindexEndOfFlag]
%%# or
%%#   \varindexNewFlag\token\position[\programmacro]
%%#
%%# Here, \position is an (undefined) macro, and \token an arbitrary token.
%%# The [program(macro)] part is optional and is explained later.
%%# If token is entered in the current call of \varindex instead (or in
%%# addition to) the star, then \position is defined to expand to a
%%# (literally) number, namely the (last) position where token was given
%%# inside the "*-argument-list" (counting from 0). For example, if
%%#   \varindexNewFlag ,\commapos
%%#   \varindexNewFlag -\minuspos
%%#   \varindexNewFlag .\pointpos
%%# are used in \programA, then in the call
%%# \varindex(){\programA}{\programB},-**-{}
%%# the variable \commapos will expand in \programB to `0', while
%%# \minuspos will expand to `4' (the last position is taken). Finally,
%%# \pointpos is \undefined (unless you defined \pointpos differently AFTER
%%# the call of \varindexNewFlag; in this case, this is the default).
%%# If \varindexNewFlag is called multiple times with the same token,
%%# only the LAST call with this token takes effect.
%%#
%%# The flags `*' and `1' are introduced in this way with
%%#
%%# \varindexNewFlag *\varindexStarPos
%%# \varindexNewFlag 1\varindexOneEntry
%%#
%%# BEFORE {scanprogram} is executed. This means:
%%# 1. Usually, \varindexStarPos contains the (last) position of `*'
%%#    (resp. is undefined). Moreover, if you define \varindexStarPos in
%%#    {scanprogram} or in some flag, you get the same effect as if `*'
%%#    had been used.
%%#    An analogous remark holds for \varindexOneEntry.
%%# 2. If you introduce `*' with \varindexNewFlag, the `*' looses its
%%#    original meaning. The same holds for `1'.
%%#
%%# If you have added a [program(macro)] part, this part is expanded
%%# whenever the flag introduced by \token is used in the call of \varindex
%%# (note that it is not excluded that this happens several times within one
%%# call). More precisely, program is expanded AFTER the variable \position has
%%# been set to the corresponding value, so you may already use \position in
%%# the program part.
%%#
%%# IMPORTANT: The last token expanded in program MUST be \varindexEndOfFlag.
%%# This is not nice but has to do with the way TeX parses its arguments.
%%# Also if you use the form \programmacro, the VERY LAST token expanded
%%# must be \varindexEndOfFlag. Even a construction like
%%# \def\myprogrammacro{\ifx....
%%#   \CallSomeMacroWithvarindexEndOfFlagAtTheEnd
%%# \fi
%%# \varindexEndOfFlag}
%%# is forbidden: In \CallSomeMacroWithvarindexEndOfFlagAtTheEnd an error
%%# would occur at the end, since still the tokens \fi\varindexEndOfFlag
%%# are in the tokenlist when EndOfFlag is reached there.
%%# As a workaround, you may e.g. use
%%# \def\myprogrammacro{\ifx...
%%#    \def\execute{....\varindexEndOfFlag}%
%%# \else
%%#    \def\execute{\varindexEndOfFlag}%
%%# \execute}
%%#
%%# If you use the form [\programmacro], your macro may even read additional
%%# parameters. These parameters are expected in the call of \varindex BEHIND
%%# the flag you have introduced. So you may actually use flags with
%%# parameters. For example, if \scanprogram contains a macro like
%%#    \varindexNewFlag -\minuspos[\readpara]
%%# and you have defined
%%#    \def\readpara#1{\def\merk{#1}\varindexEndOfFlag}
%%# then the call \varindex(){\scanprogram}{\mainprg}*-{Foo}-{Foo 2}*{Entries}
%%# is admissible, and in mainprogram, \merk will have the value Foo 2.
%%#
%%# If you are more familiar with TeX, you can even allow OPTIONAL arguments
%%# following your flag: The value of the next (non-space) token is at the
%%# call of \programmacro already saved into the variable
%%#     \varindexNextToken,
%%# so you can just use it to test for e.g. [. In this connection, you may
%%# also want to use the commands
%%#     \varindexTestAndExec
%%#     \varindexSkipAndExec
%%# Please, see the program text how these commands are applied.

%%# Since version 2.1 you can also hack in personal extensions of the format
%%# string. To do this, use the command
%%#
%%#    \varindexNewFormat\splitcommand{action}
%%#
%%# Here, \splitcommand is a command generated by \toolboxMakeSplit or
%%# friends (preferably by \varindexMakeSplitExpand, because the command should
%%# act on the format string which is expand with \varindexedef).
%%# The string where it splits is the new string you can use
%%# in the format argument after this call. For each
%%# occurrence of the corresponding string in the format argument,
%%# action will be executed. If \splitcommand splits at a string which already
%%# had a previous meaning in the format string (or which is a prefix to
%%# such a string), the old meaning of these tokens in the format string is
%%# overridden.
%%#
%%# Typically, action will contain the following commands:
%%# One action will probably be to output a desired token (sequence) via
%%#
%%#    \varindexTokensOut{TextToken}{SortToken}
%%# or
%%#    \varindexTokensOutExpand\MacroForTextToken\MacroForSortToken
%%#
%%# In the first form, TextToken resp. SortToken is the token sequence put
%%# into the index or running text respectively into the sort entry of the
%%# index for the corresponding format entry. The second form is similar with
%%# the only difference that the arguments must be single macros which expand
%%# to TextToken and SortToken, respectively.
%%#
%%# The variable \ifvarindexIndexMode can be used to test whether the
%%# output goes into the running text or into the index (i.e. whether a `*'
%%# preceeded the current entry). For output into the text, SortToken is
%%# ignored, of course).
%%#
%%# Another action in \varindexNewFormat will probably be to take care of the
%%# magic space flags. This is achieved by a call to \varindexNextSpace or
%%# \varindexNoNextSpace (or separately via \varindexSpaceTexttrue/false resp.
%%# \varindexSpaceTexttrue/false); see the earlier description.
%%# The magic space flags are taken into account in "\varindexTokensOut".
%%# Thus, if you want to ignore the previous flag for some reason you should
%%# set them correspondingly before this call.
%%# However, after the call you should also set them correspondingly for
%%# further processing.
%%#
%%# Example:
%%#   \varindexMakeSplitExpand{:}{splitAtColon}
%%#   \varindexNewFormat\splitAtColon{%
%%#      \varindexNoNextSpace
%%#      \ifvarindexIndexMode
%%#         \varindexTokensOut{:}{}\varindexSpaceTexttrue
%%#      \else
%%#         \varindexTokensOut{---}{}\varindexNoNextSpace
%%#      \fi}
%%#
%%# defines a new format entry `:' which has the meaning that a colon
%%# (automagically followed by a space) is put into the index but not into
%%# the sort entry. Moreover, in the running text, the colon appears as a
%%# long dash with no space followed. In any case, there is no magic space
%%# output in front of the colon.
%%#

%%# As an alternative action in \varindexNewFormat, you can also call the
%%# default commands for the format entries. The corresponding macros are
%%#
%%#        \varindexAddSpace           _
%%#        \varindexAddSpTok           s
%%#        \varindexAddOmit            .
%%#        \varindexAddDash            -
%%#        \varindexAddComma           ,
%%#        \varindexAddExclam          !
%%#        \varindexAddTildeA          ~
%%#        \varindexAddTildeB          =
%%#        \varindexAddNumber{number}  0-9 (the argument is 1-...)
%%#
%%# The precise meaning of these macros is intentionally NOT documented,
%%# because some details or side effects might change in a future release of
%%# "varindex". But just for this reason, it might be advantageous to use the
%%# above macros instead of writing personal substitutes which may fail to
%%# have such side effects.
%%#
%%# Example:
%%#    \varindexMakeSplitExpand{~-}{splitPhrase}% It is important to expand
%%#                                             % (to have correct ~ catcode)
%%#    \varindexNewFormat\splitPhrase{%
%%#       \varindexAddTildeA
%%#       \let\remember\varindexPreceedsDash
%%#       \let\varindexPreceedsDash\toolboxEmpty
%%#       \varindexAddDash
%%#       \let\varindexPreceedsDash\remember}
%%#
%%# After the above command, "~" and "-" have their usual meaning in
%%# the format string except when they follow immediately in the form "~-".
%%# In this case, the behavior of "-" changes as if \varindexPreceedsDash
%%# were empty (which has the effect that the output looks like "~ -" instead
%%# of "~-".
%%# Note that although "~" is a prefix to "~-", the converse is not true:
%%# Thus, the above command does not change the previous meaning of "~"
%%# (and of course also not of "-").

%%#
%%# Some hack:
%%# Tex ignores leading spaces in the argument list of a `normal' macro.
%%# This has the effect that you should be able to insert spaces BETWEEN any
%%# of your arguments without any trouble.
%%# If this does not work the expected way, you can use the command
%%#
%%#    \let\varindexArgumentSpace\varindexSkipTricky
%%#
%%# which implements an own macro which does this task. Sadly, this can only
%%# be done with some catcode trickery which in turn might bring you in trouble
%%# with some (VERY) exotic packages. You can restore the default with
%%#
%%#    \let\varindexArgumentSpace\varindexSkipDefault
%%#
%%#
%%# All above custamization commands/variables may be used anytime between
%%# two \varindex calls. They take effect with the next \varindex call.

%%# The macros \varindextwoScan and \varindextwo are considered as a
%%# (very useful) EXAMPLE for the customization of the \varindex command.
%%# If you need further customization, have a look at their definition first.

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