(define-alphabet name string-list)

Defines name to be the alphabet consisting of all elements of the string-list. Examples:

(define-alphabet "example-alphabet" ("An" "Example" "Alphabet"))

defines an alphabet consisting of exactly three symbols. For the successor relationship holds: succ("An")="Example" and succ("Example")="Alphabet". The built-in alphabet digits is defined as follows:

(define-alphabet "digits"
                 ("0" "1" "2" "3" "4" "5" "6" "7" "8" "9"))

(define-attributes attribute-list)

Defines all attributes the raw index may contain. Parameter attribute-list is a list of list of strings. The nesting level must not be more than 2. So (..(..)..) is allowed, whereas (..(..(..)..)..) is not.

The list has two kinds of elements: strings and list of strings. A single string is treated as if it were a single element list. So the lists ("definition") and ( ("definition") ) are equivalent. All elements forming a list are a so-called attribute group. The members of a group are written to the output file before any member of the following groups are written.

Examples of valid attributes lists are:

("definition" "usage") defines two attribute groups. The first one contains all references with the attribute definition and the second one all with the attribute usage.

(("definition" "important") "usage") defines two attribute groups. The first one contains all references with the attributes definition or important and the second one all with the attribute usage. In the attribute group ("definition" "important") the attribute definition overrides important.

(define-crossref-class name [:unverified])

Defines name to be a class of cross references. We distinguish two types of cross reference classes. Verified cross reference classes can be checked for dangling references. If for instance a cross reference points to the non-existent keyword `foo' a warning is issued and the user is advised to correct the invalid cross reference. This is the default. If for some reasons this mechanism must be deactivated the switch :unverified can be used to suppress this behaviour.

(define-letter-group name [:before lgname] [:after lgname]
                          [:prefixes list-of-prefixes])

(define-letter-groups list-of-letter-groups)

This command defines a letter group with name name, which must be a string value, grouping all index entries that have a sort key beginning with the prefix name. The command

(define-letter-group "a")

is equivalent to the command

(define-letter-group "a" :prefixes ("a"))

Using the latter form one can associate more than one prefix with a given letter group. Also further prefixes can be added to an already existing letter group by simply defining the same letter group again. This results not in a redefinition but in adding more prefixes to the currently defined prefixes.

Example:

(define-letter-group "a")

defines a letter group containing all index entries beginning with the string "a".

(define-letter-group "c" :after       "a")

defines a letter group containing all index entries beginning with the string "c". The letter group appears behind the letter group "a"

(define-letter-group "b" :after "a" :before "c")

inserts letter group "b" between letter group "a" and "c". This allows incremental definition of letter groups by extending already defined ones.

The arguments :after and :before define a partial order on the letter groups. xindy tries to convert this partial order into a total one. If this is impossible due to circular definitions, an error is reported. If more than one possible total ordering can result, it is left open which one is used, so one should always define a complete total order.

The command define-letter-groups (with an `s' at the end) is simply an abbreviation for a sequence of define-letter-group definitions where the elements are ordered in the ordering given by the list. Example:

(define-letter-groups ("a" "b" "c")

equals the definitions

(define-letter-group "a")
(define-letter-group "b" :after "a")
(define-letter-group "c" :after "b")

See also commands markup-letter-group-list and markup-letter-group for further information.

(define-location-class name layer-list
                       [:min-range-length num]
                       [:hierdepth depth]
                       [:var])

Defines name to be a location class consisting of the given list of layers. A list of layers consists of names of basetypes and/or strings representing separators. Separators must follow the keyword argument :sep. If the keyword :min-range-length is specified we define the minimum range length to be used when building ranges. The argument num must be a positive integer number or the keyword none in which case the building of ranges is disallowed. If the switch :var is specified the declared class is of type variable, i.e. it is a var-location-class. Since building of ranges is currently only allowed for standard classes :var and :min-range-length must not be used together. The keyword argument :hierdepth can be used to declare that the location references have to be tagged in a hierarchical form. Its argument depth must be an integer number indicating the number of layers the hierarchy does contain. See command markup-locref-list for more information. Examples:

(define-location-class "page-numbers" ("arabic-numbers")
                       :minimum-range-length 3)

Defines the location class page-numbers consisting of one layer which is the alphabet arabic-numbers. Since the minimum range length is set to 3 the location references 2, 3 and 4 don't form a range because the range length is only 2. But the references 6, 7, 8, and 9 are enough to form a range. Some example instances of this class are 0, 1, ... 2313, etc.

(define-location-class "sections" :var
   ("arabic-numbers" :sep "."
    "arabic-numbers" :sep "."
    "arabic-numbers"))

defines a variable location class. Valid instances are 1, 1.1, 1.2, 2, 2.4.5, but none of 2-3 (wrong separator), 1.2.3.4 (more than 3 layers), 2.3.iv (roman number instead of arabic one).

(define-location-class-order list)

Defines the order in which the location classes are written to the output file. The parameter list is a list of names of location classes. Examples:

(define-location-class-order
    ("page-numbers" "sections" "xrefs"))

tells the system that the page numbers should appear before the section numbers and that the cross references should appear at the end. If this command is omitted, the declaration order of the location classes in the index style is implicitly used as the output order. In the case that a location class does not appear in the list, the output may behave unexpectedly, so one should always enumerate all used location classes when using this command.

(define-rule-set name
        [ :inherit-from ("rule-set" "rule-set-2") ]
        :rules (<rule>...) )

A complete specification of a multi-phase sorting process for a language requires that some rules have to appear in several subsequent sorting phases. Rule sets can be used to define a set of rules that can be instantiated in an arbitrary sorting phase. Basically, they offer means to separate the definition of sorting rules from their instantiation, hence, acting as a wrapper for calls to sort-rule. They do not add new functionality that is not already present with sort-rule.

A rule can be of the form:

<rule> ::= ("pattern" "replacement"
            [:string|:bregexp|:egegexp] [:again])

The following incomplete example defines a new rule set of name isolatin1-tolower that inherits definitions from rule set latin-tolower, overriding or adding the sort rules in the list of :rules.

(define-rule-set "isolatin1-tolower"

  :inherit-from ("latin-tolower")

  :rules (("?" "?" :string :again)
          ("?" "?" :string :again)
          ("?" "?" :string :again)
          ("?" "?" :string :again)
          ("?" "?" :string :again)
          ("?" "?" :string :again)
          ("?" "?" :string :again)
       ...
         )
...)

Rule sets can be instantiated with the command use-rule-set. For further descriptions on the sorting model refer to the command sort-rule.

(define-sort-rule-orientations (orientations...))

Defines the order for the different sorting phases. The currently implemented orientations are forward and backward. This command must precede all sort-rule commands in an index style. It defines the orientations and implicitly sets the maximum number of sorting phases performed.

For further descriptions on the sorting model refer to the command sort-rule.

(merge-rule pattern replacement [:again]
                                [:bregexp | :eregexp | :string])

Defines a keyword mapping rule that can be used to generate the merge key from the main key of an index entry. This mapping is necessary to map all keywords that are differently written but belong to the same keyword to the same canonical keyword.

The parameter pattern can be a POSIX-compliant regular expression or an ordinary string. The implementation uses the GNU Rx regular expression library which implements the POSIX regular expressions. Regular expressions (REs) can be specified as basic regular expressions (BREs) or extended regular expressions (EREs). You can use the switch :bregexp to force the interpretation of the pattern as a BRE, or :eregexp to interpret it as an ERE. If you want xindy to interpret the pattern literally, use the switch :string. If none of these switches is selected, xindy uses an auto-detection mechanism to decide, if the pattern is a regular expression or not. If it recognizes the pattern as a RE, it interprets it as an ERE by default.

The parameter replacement must be a string possibly containing the special characters & (substitutes for the complete match) and \1 ,..., \9 (substituting for the n-th submatch. Examples:

(merge-rule "A" "a")

replaces each occurrence of the uppercase letter `A' with its lowercase counterpart.

(merge-rule "\~"([AEOUaeou])" "\1")

transforms the TeX umlaut-letters into their stripped counterparts, such that `\"A ' is treated as an `A' afterwards.

The following sequences have a special meaning:

Tilde characters and double quotes have to be quoted themselves with a tilde character. The special characters ` ~b ' and ` ~e ' allow the definition of arbitrary sorting orders by rules. In connection with an additional character every position in the alphabet can be described. E.g. ` m~e ' is lexicographically placed between `m' and `n'.

Due to efficiency, rules that just exchange characters or substitute constant character sequences are not treated as regular expressions. Therefore, instead of using the rule

(merge-rule "[A-Z]" "&")

it is more efficient (though less comfortable) to use

(merge-rule "A" "Ax")
(merge-rule "B" "Bx")
...
(merge-rule "Z" "Zx")

Usually rules are applied in order of their definition. Rules with a special prefix precede those that begin with a class of characters, so that the search pattern `alpha' is checked before `.*', but `auto' and `a.*' are checked in order of their definition.

The first rule from a style file that matches the input is applied and the process restarts behind the substituted text. If no rule could be applied, the actual character is copied from the input and the process continues with the next character.

Sometimes it is necessary to apply rules anew to the result of a transformation. By specifying the keyword argument :again in the merge rule the rule is marked as mutable, which means that after using this rule the transformation process shall restart at the same place. E.g. the rule

(merge-rule "\$(.*)\$" "\1" :again)

deletes all surrounding `$ ' symbols from the input.

See also command sort-rule.

(merge-to attr-from attr-to [:drop])

A merge rule says that the attribute attr-from can be used to build ranges in attr-to. Both attributes must name valid attribute names. The switch :drop indicates, that the original location reference with attribute attr-from has to be dropped (removed), if a successful range was built with location references in attribute attr-to. A detailed description is given in the section about processing phases.

(require filename)

This command allows to load more index style modules. The module is searched in the directories defined in the search path. The file is read in and processing of the current file continues. The argument filename must be a string. This allows to decompose the index style into several modules that can be included into the topmost index style file. Example:

(require "french/alphabet.xdy")
(require "french/sort-rules.xdy")
(require "tex/locations.xdy")
(require "tex/markup.xdy")

Submodules can load other submodules as well. If a file is required that was already loaded, the require command is simply ignored and processing continues without including this file twice. See also command searchpath.

(searchpath {path-string | path-list})

This command adds the given paths to the list of paths, xindy searches for index style files. The argument path-string must be a colon-separated string of directory names. If this path ends with a colon the default search path is added to the end of the path list. Example:

(searchpath ".:/usr/local/lib/xindy:/usr/local/lib/xindy/english:")

adds the specified directories to the search path. Since the last path ends with a colon, the built-in search path is added at the end. Specifying

(searchpath ("."
             "/usr/local/lib/xindy"
             "/usr/local/lib/xindy/english"
             :default))

yields exactly the same result as the example above. Here path-list must be a list of strings and/or the keyword(s) :default and :last. The keyword :default signifies that the default pathnames are to be inserted at the specified position in the list. The keyword :last allows to insert the currently active paths at the indicated position. Since this allows to insert the built-in paths at any position and incrementally adding new paths to the search path, this version of the command ist more flexible than the first version.

(sort-rule pattern replacement [:run level] [:again])

Defines a keyword mapping rule that can be used to generate the sort key of an index entry from the merge key. This key is used to sort the index entries lexicographically after they have been merged using the merge key.

The argument :run indicates that this rule is only in effect a the specified level (default is level 0). For a detailed discussion on the definition of sort rules for different layers refer to the documentation about the new sorting scheme (new-sort-rules) that comes with this distribution.

See command merge-rule for more information about keyword rules.

(use-rule-set [:run phase]
              [:rule-set ( <rule-set>... ))

This command instantiates the gives rule sets to be in effect at sorting phase phase. The order of the rule sets given with argument :rule-set is significant. Rule set entries of rule set appearing at the beginning of the list override entries in rule sets at the end of the list.

The following example declares that in phase 0 the rule sets din5007 and isolatin1-tolower should be active, whereas in phase 2 the other rule sets have to be applied.

(use-rule-set :run 0
              :rule-set ("din5007" "isolatin1-tolower"))

(use-rule-set :run 1
              :rule-set ("resolve-umlauts"
                         "resolve-sharp-s"
                         "isolatin1-tolower"
                        ))

For a discussion on rule sets refer to command define-rule-set.

(markup-attribute-group-list [:open string] [:close string]
                             [:sep string])

(markup-attribute-group      [:open string] [:close string]
                             [:group group-num])

Location class groups consist of lists of attribute groups. The markup of this list can be defined with the command markup-attribute-group-list.

To allow different markup for different attribute groups the command markup-attribute-group can be specialized on the group number with the keyword argument :group which must be an integer number. E.g., given are the groups ("definition" "theorem") and ("default") with group numbers 0 and 1, then

(markup-attribute-group :open "<group0>" :close </group0>"
                        :group 0)

(markup-attribute-group :open "<group1>" :close "</group1>"
                        :group 1)

can be used to assign different markup for both groups in a SGML-based language.

(markup-crossref-list       [:open string] [:close string]
                            [:sep string]
                            [:class crossref-class])

(markup-crossref-layer-list [:open string] [:close string]
                            [:sep string]
                            [:class crossref-class])

(markup-crossref-layer      [:open string] [:close string]
                            [:class crossref-class])

A crossref class group contains cross references of the same class. The separator between the classes is defined with the (markup-locclass-list :sep)-parameter. A list of cross references can be tagged with the command markup-crossref-list that specializes on the :class argument.

Each cross reference is determined by a list of layers indicating the target of the cross reference. To define a suitable markup for such a list the command markup-crossref-layer-list can be used.

Each layer of a cross reference can be assigned two tags that specialize on the class of the reference, like all other commands.

A suitable markup for a cross reference class see within LaTeX2e could look like that:

(markup-crossref-list :class "see" :open "\emph{see} "
                                   :sep  "; ")
(markup-crossref-layer-list :class "see" :sep ",")
(markup-crossref-layer :class "see"
                                   :open "\textbf{" :close "}")

An example output could look like ... see house; garden,winter; greenhouse

(markup-index [:open string] [:close string]
              [ :flat | :tree | :hierdepth depth ])

Defines the markup tags that enclose the whole index via the :open and :close parameters. Examples:

(markup-index :open  "Here comes the index~n"
              :close "That's all folks!~n")

defines that the :open string is printed before the rest of the index and the :close string appears after the index is printed.

Additionally one can specify the form of the generated index. It is possible to produce flat indexes by specifying the switch :flat, to generate a tree with the :tree switch or any kind of mixture between both by specifying the depth up to which trees shall be built with the parameter :hierdepth. Its argument depth is the number of layers that can be formed into a tree. Therefore :flat is an abbrevation of :hierdepth 0 and :tree is an abbrevation of :hierdepth max-depth, with max-depth being the maximum number of layers a keyword has. An example: the keywords

("tree" "binary" "AVL")
("tree" "binary" "natural")

can be transformed in the following ways:

A flat index (:flat or :hierdepth 0)

tree binary AVL
tree binary natural

with :hierdepth 1

tree
   binary  AVL
   binary  natural

and a tree (:tree or :hierdepth > 1)

tree
   binary
      AVL
      natural

Most often one will create tree-like indexes or ones that are flat.

(markup-indexentry-list [:open string] [:close string]
                        [:sep string]  [:depth integer])

(markup-indexentry      [:open string] [:close string]
                        [:depth integer])

Letter groups consists of a list of index entries. The command markup-indexentry-list defines the markup of these lists. The markup can be specialized on the depth if the index is hierarchically organized. The command

(markup-indexentry-list :open  "\begin{IdxentList}"
                        :close "\end{IdxentList}"
                        :sep   "~n")

defines that the index entries of all layers are wrapped into the given markup tags. If additionally

(markup-indexentry-list :open  "\begin{IdxentListII}"
                        :close "\end{IdxentListII}"
                        :sep   "~n"
                        :depth 2)

is defined, all index entry lists of all layers (except layer 2) are tagged according to the first specification, and the index entry list within depth 2 are tagged according to the second rule.

The command markup-indexentry defines the markup of an index entry at a given depth. Since index entries may also contain subentries and the markup for subentries may be different in different layers, the optional keyword argument :depth can be used to assign different markup for different layers. If depth is ommited the default markup for all possible depths is defined. The top-most index entries have depth 0.

(markup-indexentry :open  "\begin{Indexentry}"
                   :close "\end{Indexentry}")

defines that the index entries of all layers are wrapped into the given markup tags. If additionally

(markup-indexentry :open  "\begin{IndexentryII}"
                   :close "\end{IndexentryII}"
                   :depth 2)

is defined, all index entries of all layers (except layer 2) are tagged according to the first specification, and the index entries with depth 2 are tagged according to the second rule.

(markup-keyword-list [:open string] [:close string]
                     [:sep string] [:depth integer])

(markup-keyword      [:open string] [:close string]
                     [:depth integer])

The print key of an index entry consists of a list of strings. The markup of this list can be defined with the command markup-keyword-list. The keyword argument :depth may be specified to define the markup of the list at a particular depth.

The keyword of an index entry consists of a list of strings. Each of these components is tagged with the strings defined with the command markup-keyword. Since we maybe need different markup for different layers, the optional keyword argument can be used to specialize this markup for some depth.

(markup-letter-group-list [:open string] [:close string]
                          [:sep string])

(markup-letter-group  [:open string] [:close string] [:group group-name]
                      [:open-head string] [:close-head string]
                      [:upcase | :downcase | :capitalize])

The first command defines the markup of the letter group with name group-name. Since the markup of letter groups often contains the name of the letter group as a part of it, the other keyword arguments allow an additional markup for this group name. If one of the parameters :open-head and :close-head is specified additional markup is added as can be described as follows:

<OPEN>
   IF (:open-head OR :close-head)
     <OPEN-HEAD>
       transformer-of(<GROUP-NAME>)
     <CLOSE-HEAD>
   FI
   <INDEXENTRIES...>
<CLOSE>

Here, transformer-of is a function that possibly transforms the string representing the group name into another string. The transformers we currently support can be specified with the switches :upcase, :downcase and :capitalize which result in the corresponding string conversions. If none of them is specified no transformation is done at all.

The command markup-letter-group defines the markup of the list of letter groups.

(markup-locclass-list [:open string] [:close string]
                      [:sep string])

Each index entry contains a list of location class groups. This markup command can be used to define the markup of this list.

(markup-locref [:open string] [:close string]
               [:class locref-class]
               [:attr  attribute]
               [:depth integer])

The markup tags of a location reference can be specialized on the three arguments :class, :attr and additionally, if sub-references are used, :depth. Most often one will only use a tag depending on the attribute. For example, all location references with the attribute definition should appear in a font series like bold, emphasizing the importance of this location reference; those with the attribute default in font shape italic. The markup in this case would not specialize on the depth or any particular class. A valid definition, suitable for a usage within HTML, could look like this.

(markup-locref :open "<B>" :close "</B>" :attr "definition")
(markup-locref :open "<I>" :close "</I>" :attr "default")

(markup-locref-class [:open string] [:close string]
                     [:class locref-class])

All location references of a particular location reference class can be wrapped into the tags defined by this command. It specializes on the keyword argument :class.

(markup-locref-layer      [:open string] [:close string]
                          [:depth integer] [:layer integer]
                          [:class locref-class])

(markup-locref-layer-list [:open string] [:close string]
                          [:sep string]
                          [:depth integer]
                          [:class locref-class])

A location reference contains a list of location reference layers. The second markup command can be used to markup this list. It specializes on the class of the location references and the depth (if sub-references are used).

The first command allows to tag the elements of a layer list differently. The first element of this list can is specialisable with :layer 0, the next element with :layer 1, etc. See the next example for an example.

(markup-locref-list [:open string] [:close string] [:sep string]
                    [:depth integer] [:class locref-class])

An attribute group contains a list of location references and/or ranges. Additionally a layered location reference itself may contain sub-references that are stored as a list of location references. We specialize the markup for these lists on the location class they belong to with the keyword argument :class, and on :depth that specializes on the different subentry levels when using location references with sub-references.

Given is a list of location references that have the class description

(define-location-class "Appendix"
                       ("ALPHA" :sep "-" "arabic-numbers")
                       :hierdepth 2)

This location class has instances like A-1, B-5, etc. The keyword argument :hierdepth 2 informs xindy to markup these location references in a hierarchical form. With the commands

(markup-locref-list            :sep "; "
                     :depth 0  :class "Appendix")
(markup-locref-list  :open " " :sep ","
                     :depth 1  :class "Appendix")
(markup-locref-layer :open "{\bf " :close "}" :layer 0
                     :depth 0  :class "Appendix")

we obtain a markup sequence for some example data that could look like

 \bf A} 1,2,5; {\bf B} 5,6,9; {\bf D} 1,5,8; ...

(markup-range [:open string] [:close string] [:sep string]
              [:class locref-class]
              [:length num] [:ignore-end])

A range consists of two location references. Markup can be specified with the :open and :close arguments and one separator given by the argument :sep.

Since both location references are tagged with markup defined by the command markup-locref a specialization on attributes or depth is not necessary. Specialization is allowed on the class they belong to, because the separator between two location refences may be different for each location class. Argument :length can be used to define different markup for different lengths. In conjunction with :length is may be useful not to print the second location reference at all. For example, one wishes to markup ranges of length 1 in the form Xf. instead of X--Y. This can be accomplished with the switch :ignore-end.

The markup tags for a range (X,Y) can be described as follows:

<OPEN>
  Markup of location reference X
<SEP>
  IF (not :ignore-end)
     Markup of location reference Y
  FI
<CLOSE>

The following tags can be used to define a range of page numbers (given in a location class page-numbers) without considering the open and close parameters:

(markup-range :sep "-" :class "page-numbers")

Location ranges then appear separated by a hyphen in a form like this:

   ..., 5-8, 19-23, ...

This command can be used to activate the tracing of all markup commands xindy executes. The switch :on activates the trace. If :on is omitted, the command line flag -t can be used as well. All tags which are emitted but not yet defined explicitly by the user are tagged with a symbolic notation indicating the commands that must be used to define this tag. The defaults for the keyword argument :open is `<' and for :close is `>'. The beginning of an example output could look like:

<INDEX:OPEN>
  <LETTER-GROUP-LIST:OPEN>
    <LETTER-GROUP:OPEN ["a"]>
      <INDEXENTRY-LIST:OPEN [0]>
        <INDEXENTRY:OPEN [0]>
          <KEYWORD-LIST:OPEN [0]>
            <KEYWORD:OPEN [0]>
 ...

We use a simple indentation scheme to make the structure of the tags visible. The symbolic tag <LETTER-GROUP:OPEN ["a"]> for example indicates that the tag that can be specified with the command

(markup-letter-group :open "XXX" :group "a" ... )

is emitted at this point in the markup process. By incrementally adding markup commands to the index, more and more tags can be defined until the whole markup is defined. This general mechanism should allow everyone understand the markup process. The best is to start with a small index, define the complete markup and afterwards process the whole index. Additionally one can enclose the symbolic tags into an environment that is neutral to the document preparation system, such as a comment. For TeX this could be

(markup-trace :open "%%" :close "~n")

or a definition in the TeX document like

\def\ignore#1{}

combined with the command

(markup-trace :open "\ignore{" :close "}")