summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/varindex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2006-01-09 00:44:40 +0000
committerKarl Berry <karl@freefriends.org>2006-01-09 00:44:40 +0000
commitb4fc5f639874db951177ec539299d20908adb654 (patch)
tree52f08823ca58fffe3db6a9b075635038c567626c /Master/texmf-dist/doc/latex/varindex
parentdec3d98ebe442d7ea93efbaa8dd2e2be8149a467 (diff)
doc 4
git-svn-id: svn://tug.org/texlive/trunk@80 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/varindex')
-rw-r--r--Master/texmf-dist/doc/latex/varindex/varindex.tex20
-rw-r--r--Master/texmf-dist/doc/latex/varindex/varindex.txt1255
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'.