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

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