doc 4

git-svn-id: svn://tug.org/texlive/trunk@80 c570f23f-e606-0410-a88d-b1316a301751

2 files changed, 1275 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/latex/varindex/varindex.tex b/Master/texmf-dist/doc/latex/varindex/varindex.tex
new file mode 100644
index 00000000000..8d9f19803da
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/varindex/varindex.tex
@@ -0,0 +1,20 @@
+\documentclass{ltxdoc}
+\OnlyDescription%% Comment this out, or
+%%\AlsoImplementation%% uncomment this line, if you want to see the source.
+
+%% If you want an index, uncomment one of the following lines.
+%% After running latex a first time, you have to use
+%%      makeindex -s gind.ist varindex
+%% Then run latex again.
+%%\CodelineIndex% comment this out if you want an index referring to codelines
+%%\PageIndex% comment this out if you want an index referring to pages
+%%\OldMakeindex% uncomment this line, if your MakeIndex is pre-v2.9
+
+\setlength\hfuzz{15pt}
+\hbadness=7000
+\begin{document}
+\DocInput{varindex.dtx}
+\end{document}
+\endinput
+%%
+%% End of file `varindex.tex'.
diff --git a/Master/texmf-dist/doc/latex/varindex/varindex.txt b/Master/texmf-dist/doc/latex/varindex/varindex.txt
new file mode 100644
index 00000000000..7443bc41d51
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/varindex/varindex.txt
@@ -0,0 +1,1255 @@
+
+%%#
+%%# Author:
+%%#
+%%# M. V\"ath      vaeth@mathematik.uni-wuerzburg.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
+
+%%#############################################################################
+%%#
+%%#  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'.