%%# %%# Author: %%# %%# M. V\"ath martin@mvath.de %%# %%# This package bases on ideas of indextwo.sty which was written jointly with %%# %%# O. Karch karch@informatik.uni-wuerzburg.de %%# H.-C. Wirth wirth@informatik.uni-wuerzburg.de %%# The package may be distributed and/or modified under the conditions of %%# the LaTeX Project Public License (version 1.3c or later). %%############################################################################# %%# %%# This LaTeX package provides a luxury front-end for the \index command. %%# For example, it allows to generate multiple \index entries in %%# almost any form by a single command. Extremely customizable. %%# Works with all versions of LaTeX and probably most other TeX formats, too. %%# This package requires the toolbox package at least in version 3.1. %%# %%############################################################################# %%# %%# This package was tested with LaTeX 2.09 and LaTeX 2e and should work %%# with all other (future) versions of LaTeX and friends, too. %%# It should even run with other (non-LaTeX) formats if an \index command %%# with LaTeX-Syntax is provided. %%# %%# To use varindex, you have to put `varindex.sty' in a path where TeX looks %%# for its input files. You must also have the file `toolbox.sty' of the %%# toolbox package in your path. The TeX documents using varindex need the %%# following modifications in their header: %%# %%# a) If you use LaTeX2.09, use varindex as a style option, e.g. %%# \documentstyle[varindex]{article} %%# or %%# \documentstyle[varindex,12pt]{article} %%# b) If you use LaTeX2e, put in the preamble the command %%# \usepackage{varindex} %%# c) If you use some other (non-LaTeX) format, you will probably have to %%# insert a line like %%# \catcode`\@=11\input varindex.sty\catcode`\@=12\relax %%# %%# For TeX insiders: LaTeX-specific commands used in `varindex.sty' are only: %%# %%# \makeatother %%# \makeatletter %%# \typeout %%# \RequirePackage %%# \newcommand (only in the form \newcommand{\command}{} to ensure that %%# \command was not defined before) %%# \ProvidesPackage %%# %%# The above commands are used only if they are defined (otherwise, %%# natural substitutes are used (\newcommand and \Provides package are %%# then not used at all)) %%# %%# I strongly recommend to have additionally a look at the documentation %%# of the "toolbox" package, in particular the \toolboxMakeDef command %%# (provided since toolbox v3.1) which supplements \varindex. %%# %%# %%# The \varindex command is highly customizable. %%# So the following examples can only give you a rough impression of what %%# you can actually do with it. You do not need to understand them now: %%# The general usage is explained later. (Maybe you want to look up the %%# examples afterwards). %%# %%# %%# 1. Typical example of usage (using the \varindextwo macros): %%# %%# %%# %%# Suppose the following customization of the \varindex command was defined: %%# \def\Index{\varindex(){\varindextwoScan}{\varindextwo}[\emph]} %%# Since we used the \varindextwo macros here, by default %%# TWO index entries are generated with a single command: %%# %%# \Index{ring with $1$@one} %%# %%# ring %%# ~ with $1$ [sorted like: "with one"] %%# %%# $1$ [sorted like: "one" ] %%# ring with ~ [sorted like: "ring with" (without " ~") ] %%# %%# DIFFERENT entries may be generated by your own rules. E.g.: %%# %%# \Index{Hausdorff measure of noncompactness}[4,23 2!~34!1= ] %%# %%# generates THREE index entries: %%# %%# noncompactness, measure of ~ (sorted like "noncompactness, measure of") %%# %%# measure %%# ~ of noncompactness %%# Hausdorff = (here, = stands for the $\approx$ symbol) %%# %%# Hausdorff measure of noncompactness %%# %%# The last of these entries occurs only, because the last character in %%# the format argument [...] was a space. %%# %%# If you want only slight modification(s) of the default, you need also just %%# slight modifications of the command, e.g. %%# %%# \Index*,{ring with $1$@one} is as above, just that the second entry reads %%# %%# $1$, ring with ~ [sorted like "one, ring with" ] %%# %%# Moreover, since the `*' occured in the previous command, additionally %%# %%# \emph{ring with $1$} %%# %%# appears in the running text. Praxis shows that changes in the entries as %%# above have to be made frequently in the `fine tuning' of the index of a %%# book. Note that with the original \index the command would have to be %%# changed completely for the above entries, because we have a "sort" entry %%# for which a different rule applies if we use a subitem instead of a ",". %%# (BTW: \varindex produces sort entries only if they are necessary). %%# %%# Of course, you may combine the default with your own format: %%# %%# \Index{internal integrable function}[23,1~ +] generates %%# %%# integrable function, internal ~ %%# %%# internal %%# ~ integrable function %%# %%# function %%# internal integrable ~ %%# %%# %%# 2. A simple example without the \varindextwo macros: %%# %%# \varindex*{topology of a normed space}{5!4~!1= 45,12}[|see{norm}] %%# %%# produces the two index entries: %%# %%# space %%# normed ~ %%# topology = %%# %%# normed space, topology of %%# %%# In both entries not the pagenumber is cited, but the text "see also norm". %%# Additionally, the tokens {topology of a normed space} are %%# inserted into the running text (this would not happen if %%# \varindex is used in place of \varindex*). %%# Only in the first of the above entries, an `@' part will be added to the %%# *.idx file: This entry is sorted as if " ~" resp. " =" would not exist. %%# %%# %%# 3. Another example without the \varindextwo macros: %%# %%# \varindex[\emph][|textbf]% %%# {$\sigma$@sigma!$(\sigma-)$ finite {measure space}}% %%# {*1.23 23 23,1- 1-23} %%# %%# generates the three index entries: %%# %%# finite measure space %%# %%# finite measure space, $\sigma$- (sorted as "finite measure space, sigma-") %%# %%# $\sigma$-finite measure space (sorted as "sigma-finite measure space") %%# %%# In all three entries the pages are printed using \textbf. %%# %%# Moreover, the tokens %%# \emph{($\sigma$-)finite measure space} %%# are put into the running text. %%# %%# %%# 4. A simple example using a flag (without the \varindextwo macros): %%# %%# \varindex1{$L$ and $M$@L and M}{} %%# ^ %%# %%# generates the index entry "$L$ and $M$" which is sorted like "L and M". %%# In the form %%# \varindex1*{$L$ and $M$@L and M}{} %%# or %%# \varindex*1{$L$ and $M$@L and M}{} %%# additionally, {$L$ and $M$} is output into the running text. %%# %%# Note that without the `1', the index generated were %%# "$L$ and $M$ and M" which were sorted like "$L$ and L and M". %%# %%# %%# 5. An example for very primitive customized index commands (without the %%# \varindextwo macros): %%# %%# \def\myindexA{\varindex[\emph][|textbf]*} %%# \def\myindexB{\varindex(){}{}[\emph][|textbf]} %%# %%# \myindexA{Foo1}{} %%# \myindexB{Foo2}[][] %%# \myindexB*{Foo3!{Foo 3}} %%# %%# Generates the index entries Foo1, Foo2, and Foo3. Moreover, \emph{Foo1} %%# and \emph{Foo 3} is put into the running text. The pagenumber of Foo 2 in %%# the index is printed normal, the others with \textbf. %%# %%# %%# 6. An example of a primitive customized index command (without the %%# \varindextwo macros): %%# %%# \def\myindex{\varindex(\ifnum\varindexCount=2 1!2 2,1\fi){}{}[\emph]} %%# %%# \myindex{Foo Bar} %%# generates the index entries %%# Foo %%# Bar %%# %%# Bar, Foo %%# %%# \myindex*{Foo Bar} %%# generates the same index entries as above and additionally outputs %%# \emph{Foo Bar} into the running text. %%# %%# \myindex*{other format}[21] %%# generates the index entry %%# format other %%# and outputs \emph{other format} into the running text. %%# %%# \myindex[|textbf]*{BoBo} %%# generates the index entry %%# BoBo %%# where the pagenumber is printed with \textbf. %%# Moreover, \emph{BoBo} is output into the running text. %%# %%# %%# 7. A primitive varying customized index command (without the \varindextwo %%# macros): %%# %%# \def\myindex{\varindex(\ifnum\varindexCount=2 1!2 2,1\fi)% %%# (\ifnum\varindexCount=2*2,1 1!2 2,1\fi){}{}[\emph]} %%# %%# With the same commands as in 6. the same index entries are generated, %%# but the tokens \emph{Far, Boo}, \emph{other format}, and \emph{Bobo} %%# are output into the running text. %%# %%# %%# 8. Examples with the \varindextwo macros: %%# We use a similar definition for \Index as in 1., and define an \iemph %%# macro which has `*' as a default and outputs with \emph. %%# Both sort of definitions are highly recommended for you private style. %%# %%# \def\Index{\varindex(){\varindextwoScan}{\varindextwo}[]} %%# \def\iemph{\varindex(){\varindextwoScan\def\varindexStarPos{}}% %%# {\varindextwo}[\emph]} %%# (note that \def\iemph{\varindex(){\varindextwoScan}{\varindextwo}[\emph]*} %%# is not so good as the above definition of \iemph as is explained below). %%# %%# \Index*{measure of $\gamma$-noncompactness@gamma-noncompactness!FOO} %%# %%# generates the index entries %%# %%# measure %%# ~ of $\gamma$-noncompactness (sorted as "of gamma-noncompactness") %%# %%# $\gamma$-noncompacntess %%# measure of ~ %%# %%# and outputs the tokens {measure of FOO} into the running text. %%# %%# \Index*,?_'{flic of flac} generates %%# %%# flic of flac %%# %%# flac, flic %%# %%# and outputs {flic of flac}. %%# %%# \Index^={$\sigma$@sigma algebra} generates %%# %%# $\sigma$ (sorted as "sigma") %%# ~-algebra (sorted as "algebra" resp. "-algebra", see below) %%# %%# algebra %%# $\sigma$-~ (sorted as "sigma-") %%# %%# Here, the sorting "-algebra" is chosen when you used %%# \let\varindexOutSortDashBeg\varindexOutSortDash %%# as described later. %%# %%# \Index-^>{$\sigma$@sigma algebra} generates %%# %%# $\sigma$- (sorted as "sigma-") %%# ~ algebra (sorted as "algebra") %%# %%# \Index^.,:{ultra filter} generates %%# %%# ultra %%# ~filter (no space following ~) %%# filter, ultra~ (no space in front of ~) %%# %%# \iemph[|see{recursive recursion}],_{recursive recursion} generates %%# %%# recursive recursion, \see{recursive recursion} %%# %%# recursion, recursive ~, \see{recursive recursion} %%# %%# and outputs \emph{recursive recursion}. If we would have used instead the %%# definition \def\iemph{\varindex(){\varindextwoScan}{\varindextwo}[]*}, %%# the above call were not possible, since the optional arguments [|see...] %%# must occur in front of the flag `*'. %%# %%# \Index-;*{Flip Flop} generates %%# %%# Flip-Flop %%# %%# FlopFlip %%# %%# and outputs {Flip-Flop} (!!!!!!!) %%# %%# \Index>{Flippy Flop!GO}[*2-1-2 2!1-1 1-12 +] %%# %%# generates %%# %%# Flop %%# Flippy-Flippy (no tilde!) %%# %%# Flippy-Flippy Flop %%# %%# Flippy %%# ~ Flop %%# %%# and outputs {GO-Flippy-GO} (!!!) %%# %%# \Index*_,{shape {of a} of star} generates %%# %%# shape of a star %%# %%# star, shape of ~ (sorted like "star, shape of") %%# %%# and outputs {shape of a star}. %%# %%# \Index1*{$L$ feature@L feature} %%# \Index,{No $L$@L feature} %%# generate %%# %%# $L$ feature (sorted like "L feature") %%# %%# No %%# ~ $L$ feature (sorted like "L feature") %%# %%# feature, No $L$ ~ (sorted like "feature, No L") %%# %%# and outputs {$L$ feature}. %%# %%# %%# 9. Example of a simple modification of the \varindextwo macros: %%# %%# \def\myindextwoScan{% %%# \varindextwoScan %%# \varindexNewFlag ~\vxtSpaceA %%# \varindexNewFlag 1\vxtSpaceB %%# \varindexNewFlag !\varindexOneEntry %%# \varindexMakeSplitExpand{/}{vxtSplitAtMagic}% %%# \def\varindexStarPos{}% %%# } %%# \def\myIndex{\varindex(){\myindextwoScan}{\varindextwo}[]} %%# %%# \myIndex behaves similar to the previous example with %%# the following differences: %%# 1. The flag `1' now has the previous meaning of "~". %%# 2. One may now use "~" and "_" equivalently. %%# 3. The flag `!' now has the originial meaning of the flag `1'. %%# 4. Instead of `+' in the format string, the character `/' has to be used. %%# %%# %%# Description: %%# %%# There are two possible calls: %%# %%# a) \varindex[textstyle][pagestyleA]flags{main entries}{format}[pagestyleB] %%# %%# Here, [textstyle], [pagestyleA], [pagestyleB], and flags are optional. %%# (If [textstyle] is omitted, also [pagestyleA] must be omitted). %%# %%# textstyle: describes the textstyle used for the output into the %%# running text (typically, textstyle is \emph or empty). %%# pagestyle: describes the pagestyle used for the output of the pagenumber %%# (you may also use a construct like |see{...} here). %%# If [pagestyleB] is present, this is the value used. %%# Otherwise, the value of [pagestyleA] is used (resp. nothing). %%# flags can be one (or both) of the following tokens: %%# `*': "Output into running text": %%# If no * is used in the format string (see below), %%# then the format is automatically prepended by the tokens `* ' %%# resp. `*' (depending whether format starts with ` ' or not) %%# `1': The content of {main entries} is considered as a single entry %%# (see below). %%# {main entries} and %%# {format} are explained later. %%# %%# b) \varindex(formatA)(format*A){scanprogram}{mainprogram} %%# [textstyle][pagestyleA]flags{main entries}[formatB][pagestyleB] %%# %%# Concerning [textstyle], [pagestyleA], flags, [pagestyleB], the same %%# remarks as in a) hold. Also (format*A) and (formatA) are optional. %%# (if (formatA) is omitted, also (format*A) must be omitted). %%# %%# The "default" format is formatA resp. format*A (depending whether the %%# flag "*" has been used or not). If [formatB] is given, then this is %%# used as the format (i.e. it overrides the default). %%# %%# scanprogram is executed immediately when \varindex reads it. %%# This can be used to introduce FURTHER flags (other than '*' and `1'), %%# see below. %%# mainprogram is executed AFTER the format string(s) has been expanded. %%# %%# %%# %%# It is recommended to define personal macros which contain all parameters up %%# to the place where the flags occur (either with or without some flags, %%# depending on the intention). See the examples above. %%# %%# %%# %%# %%# The main argument (called {main entries} above) has the form %%# %%# entry1[`space' entry2][`space' entry3] ... %%# %%# where each of entry1 entry2 entry3 ... in turn has the form %%# indextext@sorttext!outputtext or %%# indextext!outputtext@sorttext %%# In each of these forms, @sorttext and !outputtext are optional. %%# Here, %%# indextext is the text which is put into the index for the entry %%# sorttext is what is used as a sort criterion for the entry %%# outputtext is what is output into the running text for the entry %%# %%# Note that the symbol @ has in a sense the opposite meaning as in the %%# original \index command: %%# BEFORE that symbol, the desired text appears, and %%# AFTER the symbol the place where it has to be sorted. %%# However, we chose the symbols @ and !, because these two %%# symbols are forbidden anyway (otherwise, makeindex will become confused). %%# %%# As usual, multiple spaces are considered as ONE space and do not generate %%# empty "ghost" entries. Moreover, a space after a TeX-command like \LaTeX %%# is eliminated by TeX and thus also not considered as a separator. %%# You may use braces {...} either around a whole entry or %%# around indextext resp. sorttext resp. outputtext to allow spaces %%# which do not act as "separators" in the corresponding part. The braces %%# around these parts will vanish. In particular, you may generate an %%# empty entry with {} or ! or @ (bordered by spaces). %%# If you want that braces occur in the OUTPUT, you have to add an %%# additional pair of braces. Be aware that you write sufficiently %%# many braces, if you really should need them: For example, %%# the command \varindex{{{{A B}}}}{} produces the index entry {A B}: %%# The outermost pair of braces is eliminated immediately by TeX. The second %%# pair is eliminated, because this is a pair around a complete entry. %%# Finally, another pair is eliminated, because it is a brace around %%# indextext. %%# With the flag `1', {main entries} is considered as one single entry. %%# Nevertheless, also with this flag, an additional pair of braces around %%# main entry is eliminated. %%# %%# %%# The format string has one of the following three forms %%# indexa[`space' indexb][`space' indexc] ... [*outputa][*outputb] ... %%# [*outputa][`space' indexa][`space' indexb][*outputc] ... %%# * %%# where the order of arguments can be arbitrarily mixed (except for the first %%# indexa in the first form). indexa indexb ... outputa ... describe the %%# format of the index entries resp. of the output into the running text. %%# The output is generated in the given order (this might be important, if %%# a pagebreak occurs during the output into the running text). %%# The last case is exceptional and equivalent to `*space'. %%# The following characters/strings describe the format: %%# %%# 1-9: entry1-9 %%# 0: entry 10 %%# ~: a placeholder sign %%# =: alternative placeholder sign %%# _: a space character %%# s: The token \space (but _ is used for the sort entry) %%# .: No space will follow %%# ,: The character , (space will follow) %%# -: The character - (no space will follow) %%# !: Create a new sublevel %%# All other tokens in this argument are forbidden. %%# The token ! makes no sense for the output in the running text and thus %%# is forbidden behind *. %%# %%# By a heuristic rule, a space is automatically inserted between two entries %%# which generate non-empty text. If the heuristic rule fails, you may always %%# force a space by either "_" or "s", or forbid a space by ".". %%# %%# If a format is empty, all entries are taken in the order of input. %%# Note that TeX eliminates concatenated spaces, and so you are able to %%# produce an empty format entry only at the end or in front of a `*'. %%# If you want to force an empty OUTPUT (is this ever useful?), you may use %%# just "." as the entry. %%# %%# A sort entry is only written to the *.idx file if it differs from the %%# text entry. %%# %%# %%# Description of the \varindextwo macros: %%# %%# The macros %%# %%# \varindextwoScan \varindextwo %%# %%# can be used together as parameters {scanprogram} resp. {mainprogram} %%# for the \varindex command. %%# If \varindex is called with these macros, and no %%# explicit format argument is given, these macros generate a format %%# depending on the number of entries in {main entries}: %%# %%# a) If there is only one entry in {main entries}, %%# then the format "1" resp. "*1 1" is generated %%# (depending whether the * flag was used or not), i.e. the %%# entry is put into the index, and printed if \varindex was %%# called with the * flag. %%# %%# b) If there are two main entries like {graulty bazola}, %%# then the format becomes { 1!~2 1!2~}, i.e. the index entries %%# %%# graulty %%# ~ bazola %%# %%# bazola %%# graulty ~ %%# %%# are produced. %%# %%# You can modify the first format entry with the following flags: %%# flags format used: If used with `*' additionally: %%# _ 12 *12 %%# - 1-2 *1-2 %%# ^ 1!~-2 resp. 1!-2 *1-2 %%# -^ 1-!~.2 resp. 1-!~2 *1-2 %%# . 1.2 *1.2 %%# .^ 1!~.2 *1.2 %%# / 1!2 (without ~) *12 %%# < no entry *12 %%# %%# Here, the combinations -^ and .^ mean that both flags are used %%# (the order plays no role). %%# The output for ^ respectively -^ is determined by the switches %%# \varindextwoDashTildetrue (default) %%# \varindextwoDashTildefalse %%# \varindextwoDashSpacetrue %%# \varindextwoDashSpacefalse (default) %%# %%# You can modify the second format entry with the following flags: %%# flags format used: %%# , 2,1~ resp. 2,1 %%# ~ 21 %%# = 2!1-~ %%# ,= 2,1-~ resp. 2,1- %%# + 2-1 %%# : 2!1.~ %%# ,: 2,1.~ resp. 2,1 %%# ; 2.1 %%# > no entry %%# ! Append ~ (if not already there) %%# ? Without ~ %%# %%# Whether the first or the second alternatives in the above forms is used %%# depends on the status of the switch %%# \varindextwoCommaTildetrue (default) %%# \varindextwoCommaTildefalse %%# We point out that "\varindextwoCommaTildefalse" was in earlier versions %%# of "varindex" the default (and could not be changed). %%# Note that this switch has no effect if the ! or ? flags are used. %%# %%# HINT for remembering the symbols: The symbols _ . - for the first entry %%# are the same flags as for the output and the same flags which are used %%# in the format string. The corresponding symbols ~ : (and ;) = (and +) %%# for the second entry "look similar". The "," is only useful in the %%# second entry (and is the same symbol as in the format string). %%# The two exceptional symbols ">" and "<" can be read as "generate only %%# the forward-directed resp. backward-directed entry". %%# %%# c) If there are three main entries like {graulty of bazola}, then the %%# format becomes { 1!~23 3!12~}, i.e. the output becomes %%# %%# graulty %%# ~ of bazola %%# %%# bazola %%# graulty of ~ %%# %%# The flags have an analogous effect to b). %%# In addition, if the flags ` resp. ' are used, the second word %%# (in our example: `of') is omitted from the output in the first resp. %%# in the second index entry. If the * flag and ` are used together, the %%# second entry is also omitted from the output into the running text. %%# %%# d) If there are four main entries like {graulty of OF bazola}, then the %%# format becomes { 1!~24 4!31~}, i.e. the output becomes %%# %%# graulty %%# ~ of bazola %%# %%# bazola %%# graulty OF ~ %%# %%# i.e. we have a similar effect as in c) except that for the first entry %%# the third word is skipped, and for the second entry the second word is %%# skipped. All flags as in c) can be used with an analogous meaning. %%# Also if the * flag is used, the output into the running text is %%# analogous to c) (the third word is skipped). %%# %%# e) If there are more than four main entries, then %%# (formatA) resp. (format*A) is used. %%# %%# If an explicit format argument is provided, then this is used except %%# when it contains the symbol +. In this case, this symbol is replaced by the %%# output which would be generated "normally". If additionally the `*'-flag %%# is used, there is a special rule: %%# If the explicit format contains a `*', then no additional `*'-output is %%# produced. Otherwise, the `*'-output from a)-e) is prepended to the given %%# format string (with a space at the end, unless the format string is empty). %%# This means that `normally' you have the output from a)-e), %%# unless you write an own `*'-part in the argument. %%# %%# If you do not like the tokens chosen for the default symbols, you can %%# easily choose your own tokens by just replacing \varindextwoScan with your %%# own macro (or defining your own ``magic'' tokens after \varindextwoScan, %%# see Example 9. above). %%# %%# %%# Primitive customization: %%# %%# %%# You may use the command %%# \varindexUsePlaceholderAfalse %%# \varindexUsePlaceholderBfalse %%# to ignore the sign ~ resp. = in the format entry. %%# You can easily restore the default by %%# \varindexUsePlaceholderAtrue %%# \varindexUsePlaceholderBtrue %%# %%# If you want to switch off the placeholder only at the beginning of %%# a new entry (resp. of a new subentry), you can use the commands %%# \varindexLeadingPlaceholderAfalse %%# \varindexLeadingPlaceholderBfalse %%# The default is restored with %%# \varindexLeadingPlaceholderAtrue %%# \varindexLeadingPlaceholderBtrue %%# %%# By default, the "," in the format string is in this connection %%# treated as a symbol generating a new "subentry". You can change this %%# default with the command %%# \varindexCommaLeadsfalse %%# You may switch back with %%# \varindexCommaLeadstrue %%# %%# %%# The content of the macro %%# \varindexPlaceholderAText %%# \varindexPlaceholderASort %%# \varindexPlaceholderBText %%# \varindexPlaceholderBSort %%# is used as the placeholder ~ resp. = in the index resp. sort entry. %%# Note that if one of these entries expands empty, different rules for %%# the automatic insertion of spaces apply (for the index and sort entry %%# separately). %%# %%# You may prefer that the placeholder text resp. sort content changes at %%# run time to the context of the previous ! entry. For example, you may %%# want that the command \varindex{Gibble Gobble}{2!~2} produces the index %%# entry %%# Gibble %%# Gibble Gobble %%# (or is at least SORTED as such an entry). %%# %%# You can achieve this with the commands %%# \varindexPreviousATexttrue %%# \varindexPreviousASorttrue %%# \varindexPreviousBTexttrue %%# \varindexPreviousBSorttrue %%# for the text and sort entry and the placeholders ~ and =, respectively. %%# With these commands, the content of \varindexPlaceholderAText etc %%# is only used as the default if no previous ! entry was given. %%# You can switch back to the default mode with the respective commands %%# \varindexPreviousATextfalse %%# \varindexPreviousASortfalse %%# \varindexPreviousBTextfalse %%# \varindexPreviousBSortfalse %%# %%# By default, the ',' in the format entry is considered in this connection %%# similar to '!'. If you want to change this, use the command %%# \varindexCommaExpandfalse %%# You may switch back with %%# \varindexCommaExpandtrue %%# %%# Since version 2.2, the dash "-" occurring at the beginning of entry %%# (or after "!" or even after "," if \varindexCommaExpandtrue is in effect) %%# is ignored for sorting. You can switch off this feature with the command %%# %%# \let\varindexOutSortDashBeg\varindexOutSortDash %%# %%# To restore the new default, use %%# %%# \let\varindexOutSortDashBeg\toolboxEmpty %%# %%# %%# The commands %%# %%# \varindexSetWordString{|} % Use | as separator for entries instead %%# % of spaces. %%# \varindexSetSortString{>} % default: @ %%# \varindexSetPlainString{<} % default: ! %%# %%# set the default "magic" strings used for the main argument. %%# The argument of the above macros is intentionally NOT expanded (so that %%# you do not have troubles with active characters like ~). %%# To force expansion, use e.g. %%# \expandafter\varindexSetWordString\expandafter{\MacroToExpand} %%# or some similar construct. %%# %%# If you use a different separator than `space' for the entries, you may want %%# to change the rule how braces are eliminated. With the commands %%# \varindexEliminateOuterBracetrue %%# \varindexEliminateInnerBracetrue %%# \varindexEliminateOuterBracefalse %%# \varindexEliminateInnerBracefalse %%# you may allow resp. forbid the elimination of braces around the entries %%# resp. around {indextext} {sorttext} and {outputtext} %%# With the flag `1', {main entries} is considered as one single entry, %%# but if \varindexEliminateOuterBracetrue is set (which is the default) %%# also in this case an additional pair of braces around main entry is %%# eliminated. %%# %%# Similarly as above, %%# %%# \varindexSetIndexString{|} % default: space %%# \varindexSetOutputString{<} % default: * %%# \varindexSetTildeAString{~} % (is default) %%# \varindexSetTildeBString{=} % (is default) %%# \varindexSetSpaceString{_} % (is default) %%# \varindexSetSpaceTokString{s} % (is default) %%# \varindexSetOmitString{.} % (is default) %%# \varindexSetCommaString{,} % (is default) %%# \varindexSetDashString{-} % (is default) %%# \varindexSetExclamString{!} % (is default) %%# \varindexSetStringForNr 1{a} % default: 1 %%# \varindexSetStringForNr{11}{b}% No default! %%# %%# sets the default "magic" strings used for the format argument. %%# In contrast to before, the arguments are fully expanded (with %%# \varindexedef, see below). %%# Note that the last command provides a way to access more than 10 entries! %%# %%# If you use \varindexSetIndexString{|} (with some non-space token), %%# you may still use spaces in the format which then are just ignored. %%# %%# %%# Avoid that one string is a prefix of another string: In this case, %%# strange effects may happen, and this behavior may even change in %%# future releases of this package. %%# Note that the above effect may arise unintentionally if you use active %%# chars. For this reason, `~' is defined to expand to the letter `~', %%# before the expansion is executed. Maybe in later releases of this package %%# there will be further such redefinitions. %%# You can explicitly use this feature in your own macros by using %%# \varindexedef instead of the usual \edef, see below. %%# %%# %%# You can change the output for the text resp sort entry of the various %%# symbols used in the format string. More precisely, you can redefine %%# %%# \varindexOutExclam % Text output for ! %%# \varindexFollowsExclam % Decide whether magic space after ! is inserted %%# \varindexOutTextComma % Text output for , %%# \varindexOutSortComma % Sort output for , %%# \varindexFollowsComma % Decide whether magic space after , is inserted %%# \varindexPreceedsComma % Decide whether magic space before , is erased %%# \varindexOutTextSpace % Text output for _ %%# \varindexOutSortSpace % Sort output for _ %%# \varindexFollowsSpace % Decide whether magic space after _ is inserted %%# \varindexPreceedsSpace % Decide whether magic space before _ is erase %%# \varindexOutTextSpTok % Text output for s %%# \varindexOutSortSpTok % Sort output for s %%# \varindexFollowsSpTok % Decide whether magic space after s is inserted %%# \varindexPreceedsSpTok % Decide whether magic space before s is erased %%# \varindexOutTextDash % Text output for - %%# \varindexOutSortDash % Sort output for - %%# \varindexOutSortDashBeg% Sort output for - if nothing preceeds %%# \varindexFollowsDash % Decide whether magic space after - is inserted %%# \varindexPreceedsDash % Decide whether magic space before - is erased %%# \varindexOutTextOmit % Text output for . %%# \varindexOutSortOmit % Sort output for . %%# \varindexFollowsOmit % Decide whether magic space after . is inserted %%# \varindexPreceedsOmit % Decide whether magic space before . is erased %%# %%# The meaning is as follows: \varindexOut... should just expand to the %%# tokens which should be written into the text resp. sort output. %%# The corresponding macro \varindexFollows... is typically defined with %%# one of the following commands: %%# \let\varindexFollows...\varindexNextSpace %%# \let\varindexFollows...\varindexNoNextSpace %%# In the first case, a space is `magically' inserted in front of a %%# subsequent token (unless this token erases the magic space). %%# In the second case, no space follows, of course. %%# There is an alternative call: %%# \def\varindexFollows...{\varindexSpaceTexttrue\varindexSpaceSortfalse} %%# This definition achieves that for the text output a space should follow, %%# but not for the sort output. Of course, you can also use similarly the %%# commands \varindexSpaceTextfalse and/or \varindexSpaceSorttrue %%# in the above definition (the effect should be obvious). %%# In particular, \varindexNextSpace is equivalent to %%# \varindexSpaceTexttrue\varindexSorttrue. %%# %%# The macro \varindexPreceeds... is similarly as \varindexFollows... with %%# the difference that it is executed BEFORE the token in question is %%# output. In particular, you can ignore a previous `magic space'. %%# All of the `magic space' commands are defined by default with %%# \let\varindexFollows...\toolboxEmpty %%# \let\varindexPreceeds...\varindexNoNextSpace %%# with the following two exceptions: %%# \let\varindexFollowsExclam\varindexNoNextSpace %%# \let\varindexFollowsComma\varindexNextSpace %%# %%# Documented Features (in later versions, these will still be available, %%# and if they contain a bug now, they will be repaired to work this way): %%# %%# (In a future release, varindex will cook your coffee, too) %%# %%# %%# %%# The main argument is NOT expanded, so you can actually write macros %%# into the *.idx file. The command actually used to write the index is %%# %%# \varindexIndex %%# %%# (which by default is of course defined as \index). %%# Since some implementations of the \index command still (partially) expand %%# their argument (which might be considered as a bug), the argument of %%# \varindexIndex is translated before the actual call with the aid of %%# \toolboxMakeHarmless. %%# If you want to redefine \varindexIndex to a personal \index-output %%# function, you might want to skip the \toolboxMakeHarmless step. %%# This is arranged with the command %%# %%# \varindexNoConvert %%# %%# You can cancel the effect of this command with %%# %%# \varindexDoConvert %%# %%# Even if \varindexNoConvert is not in effect, the main argument is not %%# expanded (and in particular, the argument of \varindexIndex consists of %%# the corresponding entries in an unexpanded form). %%# %%# The whole \varindex... procedure takes place in a group, so all your %%# variables are local to a single call (unless you use \gdef... %%# (and friends) of course). %%# %%# There are no \global directives in any macro related with this package. %%# In particular, if you call the above macros in a group (or redefine %%# \varindexIndex), the effect holds only until the end of the group. %%# %%# In contrast to the main argument, the format argument is expanded %%# (with \varindexedef, see below) %%# (and also formatA resp. format*A is expanded before), %%# so you can define abbreviations (even simple conditional abbreviations) %%# for the format. Note, however, that the expansion is essentially only %%# evaluated with \edef. So, you will probably not want to use e.g. \relax, %%# since this command expands to itself (and not into nothing - use %%# \toolboxEmpty if you want the latter). %%# If you want more complex abbreviations, use {mainprogram} instead. %%# %%# In order to help you write conditional abbreviations, the %%# following variables are defined when your macro is expanded (and in %%# particular also in {mainprogram}). You may of course redefine them %%# appropriately: %%# %%# \varindexAppend The argument pagestyleA resp. pagestyleB. %%# \varindexCount a TeX counter containing the number of entries in %%# the main argument. %%# \varindexLastEntry This is a macro (NOT a counter) which is usually %%# the value of \the\varindexCount. See below. %%# \varindexEntry1-... The (index) text occuring in entry 1-... %%# \varindexSort1-... The corresponding sort entry. If no sort entry was %%# given, this is the same as the corresponding %%# \varindexEntry1-... %%# \varindexPlain1-... The text which should be output in the text. If no %%# such entry was given, this is the same as the %%# corresponding \varindexEntry1-... %%# %%# \varindexCount may be larger than 10, and correspondingly there may be %%# also more than 10 different \varindexEntry/Sort/Plain macros. %%# If you ADD entries, you have to increase \varindexCount correspondingly, %%# otherwise an error is produced if the format string contains an entry %%# larger then \varindexCount. However, your additional entries are NOT %%# output for EMPTY formats: For empty formats the number used is %%# \varindexLastEntry. So if you want to output also your additional entries %%# in empty formats, you have to set \varindexLastEntry to your modified %%# value of \varindexCount in mainprogram. You may e.g. achieve this with %%# the following lines: %%# \expandafter %%# \def\expandafter\varindexLastEntry\expandafter{\the\varindexCount}% %%# It is admissible that \varindexLastEntry is larger than \varindexCount: %%# In this case all entries until \varindexLastEntry are %%# output in empty formats without producing an error (provided, of course, %%# that the corresponding variables \varindexEntry.../Sort.../Plain... are %%# defined). %%# %%# Note that numbers in TeX command names require special handling, %%# i.e., you have to use something like %%# %%# \csname varindexPlain2\endcsname %%# %%# to access variables. To avoid this, you may want to use the macros %%# \toolboxLet and \toolboxWithNr of the toolbox package. Examples are %%# \toolboxWithNr 1\let{varindexEntry}\toolboxEmpty %%# \toolboxWithNr {10}\def{varindexSort}{Foo} %%# \toolboxLet \mymacro{varindexPlain\the\mycount} %%# These commands set \varindexEntry1 to \toolboxEmpty, \varindexSort10 to %%# Foo, and \mymacro to the content of \varindexPlain5 (if \mycount=5). %%# %%# All these variables are also available when {mainprogram} is expanded. %%# In {mainprogram} also the following functions are useful: %%# %%# \varindexFormat %%# This macro expands to the actual format string which is used. %%# The main purpose of {mainprogram} will usually be to (re)define %%# this macro. After {mainprogram} has been called, this macro is %%# modified in several ways: %%# 1. \varindexFormat is expanded (with \varindexedef, see below). %%# (thus, \varindexFormat is expanded BEFORE AND AFTER the call %%# of {mainprogram}). %%# 2. \ifvarindexStar is true (see below) a `*' resp. `* ' is prepended. %%# 3. If it is only "*", it is replaced by "* ". %%# Note that before execution of {mainprogram}, no tests on the %%# validity of the format are done: You may use your own symbols to %%# `communicate' with {mainprogram} (if {mainprogram} eliminates these %%# symbols afterwards). %%# %%# \varindexFormatDefault %%# This macro expands to formatA resp format*A (in the expanded form) %%# depending whether the * flag has been used in the call. %%# Note that this expansion was executed BEFORE the optional format %%# argument is expanded for the first time. %%# %%# \ifvarindexStar ifpart [ \else elsepart] \fi %%# If the optional * was given, the ifpart is executed, otherwise the %%# else-part. This is a TeX-if-command. In particular, by %%# \varindexStarfalse resp. \varindexStartrue %%# you may change the behavior for future if's. This can be used %%# to prevent/force that a `*' resp. `* ' is prepended to the format %%# after the execution of {mainprogram}. %%# Setting of this variable has no effect in {scanprogram} %%# %%# \ifvarindexExplicitFormat %%# This is a TeX-if-command (see above) which is true if the optional %%# format argument [formatB] was given. %%# %%# %%# To "compose" the format, you may want to use the macros %%# %%# \toolboxDef\macrotodefine{argumentlist} %%# \toolboxAppend\macrotoappend{argumentlist} %%# \varindexedef\macrotodefine{argumentlist} %%# %%# All commands work similar to \def resp. \edef with two differences: %%# %%# For \toolboxDef\macro the argumentlist is expanded precisely by one level %%# (for details, see the documentation of the toolbox package). %%# Of course, for \toolboxAppend, the new definition is appended to the old %%# definition of \macro. %%# %%# \varindexedef fully expands argumentlist. However, some active symbols %%# (currently only ~, but additional symbols might follow in a future release) %%# are deactivated before expansion, so that ~ actually expands to ~ and not %%# to a strange command sequence. %%# %%# %%# To "decompose" the format, you may want to use one of the macros %%# %%# \toolboxSplitAt{arg}{critical}{\before}{\after} %%# \toolboxMakeSplit{critical}{command} resp. %%# \varindexMakeSplitExpand{\MacrosWhichExpandToCritical}{command} %%# \varindexMakeVarSplit\variable{\MacrosWhichExpandToCritical}{command} %%# %%# The first two macros are described in the toolbox package. %%# The remaining two macros are similar to \varindexMakeSplit with the %%# difference that the argument {critical} is obtained by expanding %%# \MacrosWhichExpandToCritical with the aid of \varindexedef. %%# In the last form, additionally \variable is (re)defined to expand to %%# the value of critical. %%# %%# The following instances of a command created by \toolboxMakeSplit %%# exist (the content of "critical" should be obvious): %%# %%# \varindexSplitAtIndex (generated by \varindexSetIndexString) %%# \varindexSplitAtOutput %%# \varindexSplitAtTildeA %%# \varindexSplitAtTildeB %%# \varindexSplitAtSpace <- Here the default content of "critical" is "_" %%# \varindexSplitAtSpaceTok<- Here the default content of "critical" is "s" %%# \varindexSplitAtOmit %%# \varindexSplitAtComma %%# \varindexSplitAtDash %%# \varindexSplitAtExclam %%# \varindexSplitAtNr?? (here, ?? is the number as a string; use %%# \csname ....\endcsname to call this macro. Only those numbers are %%# admissible which have been introduced with \varindexSetStringForNr %%# (this is the case for 1-10)). %%# %%# There is also the instance %%# \varindexSplitSpace (to be distinguished from \varindexSplitAtSpace) %%# where "critical" is the space symbol. %%# %%# %%# In addition, you may use the variables %%# \varindexIndexString %%# \varindexOutputString %%# \varindexTildeAString %%# .... %%# \varindexNr??String %%# which expand to the corresponding strings. %%# %%# All the previous macros should not be redefined `by hand'. %%# They are implicitly redefined by the \varindexSet... commands. %%# %%# %%# %%# %%# To drop possible braces, use the command %%# %%# \toolboxDropBrace\variable %%# %%# of the toolbox package. %%# %%# %%# In {scanprogram} you may already want to call \toolboxMakeSplit: %%# In this way many choices for the tokens are put into {scanprogram}, %%# and in this sense, you can consider {mainprogram} as `customizable'. %%# Anyway, the main task of {scanprogram} is to introduce new flags with %%# %%# \varindexNewFlag\token\position[program\varindexEndOfFlag] %%# or %%# \varindexNewFlag\token\position[\programmacro] %%# %%# Here, \position is an (undefined) macro, and \token an arbitrary token. %%# The [program(macro)] part is optional and is explained later. %%# If token is entered in the current call of \varindex instead (or in %%# addition to) the star, then \position is defined to expand to a %%# (literally) number, namely the (last) position where token was given %%# inside the "*-argument-list" (counting from 0). For example, if %%# \varindexNewFlag ,\commapos %%# \varindexNewFlag -\minuspos %%# \varindexNewFlag .\pointpos %%# are used in \programA, then in the call %%# \varindex(){\programA}{\programB},-**-{} %%# the variable \commapos will expand in \programB to `0', while %%# \minuspos will expand to `4' (the last position is taken). Finally, %%# \pointpos is \undefined (unless you defined \pointpos differently AFTER %%# the call of \varindexNewFlag; in this case, this is the default). %%# If \varindexNewFlag is called multiple times with the same token, %%# only the LAST call with this token takes effect. %%# %%# The flags `*' and `1' are introduced in this way with %%# %%# \varindexNewFlag *\varindexStarPos %%# \varindexNewFlag 1\varindexOneEntry %%# %%# BEFORE {scanprogram} is executed. This means: %%# 1. Usually, \varindexStarPos contains the (last) position of `*' %%# (resp. is undefined). Moreover, if you define \varindexStarPos in %%# {scanprogram} or in some flag, you get the same effect as if `*' %%# had been used. %%# An analogous remark holds for \varindexOneEntry. %%# 2. If you introduce `*' with \varindexNewFlag, the `*' looses its %%# original meaning. The same holds for `1'. %%# %%# If you have added a [program(macro)] part, this part is expanded %%# whenever the flag introduced by \token is used in the call of \varindex %%# (note that it is not excluded that this happens several times within one %%# call). More precisely, program is expanded AFTER the variable \position has %%# been set to the corresponding value, so you may already use \position in %%# the program part. %%# %%# IMPORTANT: The last token expanded in program MUST be \varindexEndOfFlag. %%# This is not nice but has to do with the way TeX parses its arguments. %%# Also if you use the form \programmacro, the VERY LAST token expanded %%# must be \varindexEndOfFlag. Even a construction like %%# \def\myprogrammacro{\ifx.... %%# \CallSomeMacroWithvarindexEndOfFlagAtTheEnd %%# \fi %%# \varindexEndOfFlag} %%# is forbidden: In \CallSomeMacroWithvarindexEndOfFlagAtTheEnd an error %%# would occur at the end, since still the tokens \fi\varindexEndOfFlag %%# are in the tokenlist when EndOfFlag is reached there. %%# As a workaround, you may e.g. use %%# \def\myprogrammacro{\ifx... %%# \def\execute{....\varindexEndOfFlag}% %%# \else %%# \def\execute{\varindexEndOfFlag}% %%# \execute} %%# %%# If you use the form [\programmacro], your macro may even read additional %%# parameters. These parameters are expected in the call of \varindex BEHIND %%# the flag you have introduced. So you may actually use flags with %%# parameters. For example, if \scanprogram contains a macro like %%# \varindexNewFlag -\minuspos[\readpara] %%# and you have defined %%# \def\readpara#1{\def\merk{#1}\varindexEndOfFlag} %%# then the call \varindex(){\scanprogram}{\mainprg}*-{Foo}-{Foo 2}*{Entries} %%# is admissible, and in mainprogram, \merk will have the value Foo 2. %%# %%# If you are more familiar with TeX, you can even allow OPTIONAL arguments %%# following your flag: The value of the next (non-space) token is at the %%# call of \programmacro already saved into the variable %%# \varindexNextToken, %%# so you can just use it to test for e.g. [. In this connection, you may %%# also want to use the commands %%# \varindexTestAndExec %%# \varindexSkipAndExec %%# Please, see the program text how these commands are applied. %%# Since version 2.1 you can also hack in personal extensions of the format %%# string. To do this, use the command %%# %%# \varindexNewFormat\splitcommand{action} %%# %%# Here, \splitcommand is a command generated by \toolboxMakeSplit or %%# friends (preferably by \varindexMakeSplitExpand, because the command should %%# act on the format string which is expand with \varindexedef). %%# The string where it splits is the new string you can use %%# in the format argument after this call. For each %%# occurrence of the corresponding string in the format argument, %%# action will be executed. If \splitcommand splits at a string which already %%# had a previous meaning in the format string (or which is a prefix to %%# such a string), the old meaning of these tokens in the format string is %%# overridden. %%# %%# Typically, action will contain the following commands: %%# One action will probably be to output a desired token (sequence) via %%# %%# \varindexTokensOut{TextToken}{SortToken} %%# or %%# \varindexTokensOutExpand\MacroForTextToken\MacroForSortToken %%# %%# In the first form, TextToken resp. SortToken is the token sequence put %%# into the index or running text respectively into the sort entry of the %%# index for the corresponding format entry. The second form is similar with %%# the only difference that the arguments must be single macros which expand %%# to TextToken and SortToken, respectively. %%# %%# The variable \ifvarindexIndexMode can be used to test whether the %%# output goes into the running text or into the index (i.e. whether a `*' %%# preceeded the current entry). For output into the text, SortToken is %%# ignored, of course). %%# %%# Another action in \varindexNewFormat will probably be to take care of the %%# magic space flags. This is achieved by a call to \varindexNextSpace or %%# \varindexNoNextSpace (or separately via \varindexSpaceTexttrue/false resp. %%# \varindexSpaceTexttrue/false); see the earlier description. %%# The magic space flags are taken into account in "\varindexTokensOut". %%# Thus, if you want to ignore the previous flag for some reason you should %%# set them correspondingly before this call. %%# However, after the call you should also set them correspondingly for %%# further processing. %%# %%# Example: %%# \varindexMakeSplitExpand{:}{splitAtColon} %%# \varindexNewFormat\splitAtColon{% %%# \varindexNoNextSpace %%# \ifvarindexIndexMode %%# \varindexTokensOut{:}{}\varindexSpaceTexttrue %%# \else %%# \varindexTokensOut{---}{}\varindexNoNextSpace %%# \fi} %%# %%# defines a new format entry `:' which has the meaning that a colon %%# (automagically followed by a space) is put into the index but not into %%# the sort entry. Moreover, in the running text, the colon appears as a %%# long dash with no space followed. In any case, there is no magic space %%# output in front of the colon. %%# %%# As an alternative action in \varindexNewFormat, you can also call the %%# default commands for the format entries. The corresponding macros are %%# %%# \varindexAddSpace _ %%# \varindexAddSpTok s %%# \varindexAddOmit . %%# \varindexAddDash - %%# \varindexAddComma , %%# \varindexAddExclam ! %%# \varindexAddTildeA ~ %%# \varindexAddTildeB = %%# \varindexAddNumber{number} 0-9 (the argument is 1-...) %%# %%# The precise meaning of these macros is intentionally NOT documented, %%# because some details or side effects might change in a future release of %%# "varindex". But just for this reason, it might be advantageous to use the %%# above macros instead of writing personal substitutes which may fail to %%# have such side effects. %%# %%# Example: %%# \varindexMakeSplitExpand{~-}{splitPhrase}% It is important to expand %%# % (to have correct ~ catcode) %%# \varindexNewFormat\splitPhrase{% %%# \varindexAddTildeA %%# \let\remember\varindexPreceedsDash %%# \let\varindexPreceedsDash\toolboxEmpty %%# \varindexAddDash %%# \let\varindexPreceedsDash\remember} %%# %%# After the above command, "~" and "-" have their usual meaning in %%# the format string except when they follow immediately in the form "~-". %%# In this case, the behavior of "-" changes as if \varindexPreceedsDash %%# were empty (which has the effect that the output looks like "~ -" instead %%# of "~-". %%# Note that although "~" is a prefix to "~-", the converse is not true: %%# Thus, the above command does not change the previous meaning of "~" %%# (and of course also not of "-"). %%# %%# Some hack: %%# Tex ignores leading spaces in the argument list of a `normal' macro. %%# This has the effect that you should be able to insert spaces BETWEEN any %%# of your arguments without any trouble. %%# If this does not work the expected way, you can use the command %%# %%# \let\varindexArgumentSpace\varindexSkipTricky %%# %%# which implements an own macro which does this task. Sadly, this can only %%# be done with some catcode trickery which in turn might bring you in trouble %%# with some (VERY) exotic packages. You can restore the default with %%# %%# \let\varindexArgumentSpace\varindexSkipDefault %%# %%# %%# All above custamization commands/variables may be used anytime between %%# two \varindex calls. They take effect with the next \varindex call. %%# The macros \varindextwoScan and \varindextwo are considered as a %%# (very useful) EXAMPLE for the customization of the \varindex command. %%# If you need further customization, have a look at their definition first. \endinput %% %% End of file `varindex.txt'.