summaryrefslogtreecommitdiff
path: root/Master/texmf-doc/source/english/tex-refs/tex-refs-chapter-xindy.xml
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-doc/source/english/tex-refs/tex-refs-chapter-xindy.xml')
-rw-r--r--Master/texmf-doc/source/english/tex-refs/tex-refs-chapter-xindy.xml1434
1 files changed, 1434 insertions, 0 deletions
diff --git a/Master/texmf-doc/source/english/tex-refs/tex-refs-chapter-xindy.xml b/Master/texmf-doc/source/english/tex-refs/tex-refs-chapter-xindy.xml
new file mode 100644
index 00000000000..ce1a4c2c1aa
--- /dev/null
+++ b/Master/texmf-doc/source/english/tex-refs/tex-refs-chapter-xindy.xml
@@ -0,0 +1,1434 @@
+<?xml version='1.0' encoding='ISO-8859-1'?>
+
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+ <!ENTITY % tex-refs-ent SYSTEM "tex-refs.ent" >
+%tex-refs-ent;
+]>
+
+<!-- $Id: tex-refs-chapter-xindy.xml 139 2004-08-26 16:58:10Z mw $ -->
+
+ <chapter id="xindy" lang="en">
+ <title id="xindy-title">&xindy;</title>
+ <indexterm><primary>&xindy;</primary></indexterm>
+
+ <note><para>The content of this section was taken from the original
+ documentation of &xindy; V2.1
+ (<filename>Doc/manual*.html</filename>).
+ </para></note>
+
+ <para><emphasis>xindy</emphasis> means
+ fle<emphasis>x</emphasis>ible <emphasis>ind</emphasis>exing
+ s<emphasis>y</emphasis>stem.
+ It is an indexing system that can be used to generate
+ book-like indexes for arbitrary document
+ preparation systems. This term includes systems such as
+ &tex; and &latex;, the Nroff-family or SGML-based systems
+ (e.g. HTML) that process some kind of text and generate
+ indexing information. It is not fixed to any specific system,
+ but can be configured for a wide variety of purposes.
+ </para>
+
+ <section id="xindy-command-list">
+ <title>Command List</title>
+ <indexterm>
+ <primary>&xindy;</primary>
+ <secondary>Command List</secondary>
+ </indexterm>
+ <para>Here is the complete list of xindy's commands that may
+ be used in the index style. The symbol <literal>name</literal>
+ always refers to a string. We separate the commands into
+ the processing and markup commands. The commands are listed
+ in alphabetical order.
+ </para>
+ <para>The parenthesis <literal>[</literal> and
+ <literal>]</literal> denote optional parts of the syntax
+ and <literal>{</literal> and <literal>}</literal> denote
+ the grouping of elements. A vertical bar indicates
+ alternatives. However, the enclosing round braces
+ <emphasis>are</emphasis> part of the syntax and
+ must be supplied.
+ </para>
+
+ <section id="xindy-command-list-processing">
+ <title>Processing Commands</title>
+ <indexterm>
+ <primary>&xindy;</primary>
+ <secondary>Processing Commands</secondary>
+ </indexterm>
+
+ <section id="xindy-command-list-processing-define-alphabet">
+ <title><literal>define-alphabet</literal></title>
+ <indexterm>
+ <primary>&xindy;</primary>
+ <secondary>Processing Commands</secondary>
+ <tertiary>define-alphabet</tertiary>
+ </indexterm>
+ <para><programlisting>(define-alphabet name string-list)</programlisting></para>
+ <para>Defines <literal>name</literal> to be the alphabet
+ consisting of all elements of the
+ <literal>string-list</literal>.
+ Examples:
+ <programlisting>(define-alphabet "example-alphabet" ("An" "Example" "Alphabet"))</programlisting>
+ defines an alphabet consisting of exactly three symbols.
+ For the successor relationship holds:
+ <literal>succ("An")="Example"</literal> and
+ <literal>succ("Example")="Alphabet"</literal>. The built-in
+ alphabet <literal>digits</literal> is defined as follows:
+ <programlisting>(define-alphabet "digits"
+ ("0" "1" "2" "3" "4" "5" "6" "7" "8" "9"))</programlisting>
+ </para>
+ </section>
+
+ <section id="xindy-command-list-processing-define-attributes">
+ <title><literal>define-attributes</literal></title>
+ <indexterm>
+ <primary>&xindy;</primary>
+ <secondary>Processing Commands</secondary>
+ <tertiary>define-attributes</tertiary>
+ </indexterm>
+
+ <para><programlisting>(define-attributes attribute-list)</programlisting></para>
+ <para>Defines all attributes the raw index may contain.
+ Parameter <literal>attribute-list</literal> is a list of
+ list of strings. The nesting level must not be more than 2.
+ So <literal>(..(..)..)</literal> is allowed, whereas
+ <literal>(..(..(..)..)..)</literal> is not.
+ </para>
+ <para>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
+ <literal>("definition")</literal> and
+ <literal>( ("definition") )</literal> are equivalent.
+ All elements forming a list are a so-called
+ <emphasis>attribute group</emphasis>. The members of a group
+ are written to the output file before any member of the
+ following groups are written.
+ </para>
+ <para>Examples of valid attributes lists are:</para>
+ <para><literal>("definition" "usage")</literal> defines two
+ attribute groups. The first one contains all references
+ with the attribute <literal>definition</literal> and the
+ second one all with the attribute <literal>usage</literal>.
+ </para>
+ <para><literal>(("definition" "important") "usage")</literal>
+ defines two attribute groups. The first one contains all
+ references with the attributes <literal>definition</literal>
+ or <literal>important</literal> and the second one all with
+ the attribute <literal>usage</literal>. In the attribute
+ group <literal>("definition" "important")</literal> the
+ attribute <literal>definition</literal> overrides
+ <literal>important</literal>.
+ </para>
+ </section>
+
+ <section id="xindy-command-list-processing-define-crossref-class">
+ <title><literal>define-crossref-class</literal></title>
+ <indexterm>
+ <primary>&xindy;</primary>
+ <secondary>Processing Commands</secondary>
+ <tertiary>define-crossref-class</tertiary>
+ </indexterm>
+
+ <para><programlisting>(define-crossref-class name [:unverified])</programlisting></para>
+ <para>Defines <literal>name</literal> to be a class of
+ cross references. We distinguish two types of cross
+ reference classes. <emphasis>Verified</emphasis> 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 <literal>:unverified</literal> can
+ be used to suppress this behaviour.
+ </para>
+ </section>
+
+ <section id="xindy-command-list-processing-define-letter-group">
+ <title><literal>define-letter-group</literal></title>
+ <indexterm>
+ <primary>&xindy;</primary>
+ <secondary>Processing Commands</secondary>
+ <tertiary>define-letter-group</tertiary>
+ </indexterm>
+
+ <para><programlisting>(define-letter-group name [:before lgname] [:after lgname]
+ [:prefixes list-of-prefixes])</programlisting></para>
+ <para><programlisting>(define-letter-groups list-of-letter-groups)</programlisting></para>
+ <para>This command defines a letter group with name
+ <literal>name</literal>, which must be a string value,
+ grouping all index entries that have a
+ <emphasis>sort key</emphasis> beginning with the prefix
+ <literal>name</literal>. The command
+ <programlisting>(define-letter-group "a")</programlisting>
+ is equivalent to the command
+ <programlisting>(define-letter-group "a" :prefixes ("a"))</programlisting>
+ </para>
+ <para>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.
+ </para>
+ <para>Example:
+ <programlisting>(define-letter-group "a")</programlisting>
+ defines a letter group containing all index entries
+ beginning with the string <literal>"a"</literal>.
+ </para>
+ <para><programlisting>(define-letter-group "c" :after "a")</programlisting>
+ defines a letter group containing all index entries beginning
+ with the string <literal>"c"</literal>. The letter group
+ appears behind the letter group <literal>"a"</literal>
+ </para>
+ <para><programlisting>(define-letter-group "b" :after "a" :before "c")</programlisting>
+ inserts letter group <literal>"b"</literal> between letter
+ group <literal>"a"</literal> and <literal>"c"</literal>.
+ This allows incremental definition of letter groups by
+ extending already defined ones.
+ </para>
+ <para>The arguments <literal>:after</literal> and
+ <literal>:before</literal> 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.
+ </para>
+ <para>The command <literal>define-letter-groups</literal>
+ (with an `s' at the end) is simply an abbreviation for
+ a sequence of <literal>define-letter-group</literal>
+ definitions where the elements are ordered in the
+ ordering given by the list. Example:
+ <programlisting>(define-letter-groups ("a" "b" "c")</programlisting>
+ equals the definitions
+ <programlisting>(define-letter-group "a")
+(define-letter-group "b" :after "a")
+(define-letter-group "c" :after "b")</programlisting>
+ </para>
+ <para>See also commands
+ <literal>markup-letter-group-list</literal>
+ and <literal>markup-letter-group</literal> for further
+ information.
+ </para>
+ </section>
+
+ <section id="xindy-command-list-processing-define-location-class">
+ <title><literal>define-location-class</literal></title>
+ <indexterm>
+ <primary>&xindy;</primary>
+ <secondary>Processing Commands</secondary>
+ <tertiary>define-location-class</tertiary>
+ </indexterm>
+
+ <programlisting>(define-location-class name layer-list
+ [:min-range-length num]
+ [:hierdepth depth]
+ [:var])</programlisting>
+
+ <para>Defines <literal>name</literal> 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 <literal>:sep</literal>. If the keyword
+ <literal>:min-range-length</literal> is specified we
+ define the <emphasis>minimum range length</emphasis>
+ to be used when building ranges. The argument
+ <literal>num</literal> must be a positive integer number
+ or the keyword <literal>none</literal> in which case
+ the building of ranges is disallowed. If the switch
+ <literal>:var</literal> is specified the declared class
+ is of type <emphasis>variable</emphasis>, i.e. it is a
+ <emphasis>var-location-class</emphasis>. Since building
+ of ranges is currently only allowed for standard classes
+ <literal>:var</literal> and
+ <literal>:min-range-length</literal>
+ must not be used together. The keyword argument
+ <literal>:hierdepth</literal> can be used to declare that
+ the location references have to be tagged in a
+ hierarchical form. Its argument <literal>depth</literal>
+ must be an integer number indicating the number of layers
+ the hierarchy does contain. See command
+ <literal>markup-locref-list</literal> for more information.
+ Examples:
+ <programlisting>(define-location-class "page-numbers" ("arabic-numbers")
+ :minimum-range-length 3)</programlisting>
+ Defines the location class <literal>page-numbers</literal>
+ consisting of one layer which is the alphabet
+ <literal>arabic-numbers</literal>. 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
+ <literal>0, 1, ... 2313</literal>, etc.
+ <programlisting>(define-location-class "sections" :var
+ ("arabic-numbers" :sep "."
+ "arabic-numbers" :sep "."
+ "arabic-numbers"))</programlisting>
+ defines a variable location class. Valid instances are
+ <literal>1, 1.1, 1.2, 2, 2.4.5</literal>, but none of
+ <literal>2-3</literal> (wrong separator),
+ <literal>1.2.3.4</literal> (more than 3 layers),
+ <literal>2.3.iv</literal> (roman number instead of arabic one).
+ </para>
+ </section>
+
+ <section id="xindy-command-list-processing-define-location-class-order">
+ <title><literal>define-location-class-order</literal></title>
+ <indexterm>
+ <primary>&xindy;</primary>
+ <secondary>Processing Commands</secondary>
+ <tertiary>define-location-class-order</tertiary>
+ </indexterm>
+
+ <para><programlisting>(define-location-class-order list)</programlisting></para>
+ <para>Defines the order in which the location classes are
+ written to the output file. The parameter
+ <literal>list</literal> is a list of names of location
+ classes. Examples:
+ <programlisting>(define-location-class-order
+ ("page-numbers" "sections" "xrefs"))</programlisting>
+ 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.
+ </para>
+ </section>
+
+ <section id="xindy-command-list-processing-define-rule-set">
+ <title><literal>define-rule-set</literal></title>
+ <indexterm>
+ <primary>&xindy;</primary>
+ <secondary>Processing Commands</secondary>
+ <tertiary>define-rule-set</tertiary>
+ </indexterm>
+
+ <para><programlisting>(define-rule-set name
+ [ :inherit-from ("rule-set" "rule-set-2") ]
+ :rules (&lt;rule&gt;...) )</programlisting></para>
+ <para>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 <literal>sort-rule</literal>. They do not add new
+ functionality that is not already present with
+ <literal>sort-rule</literal>.
+ </para>
+ <para>A rule can be of the form:
+ <programlisting>&lt;rule&gt; ::= ("pattern" "replacement"
+ [:string|:bregexp|:egegexp] [:again])</programlisting>
+ </para>
+ <para>The following incomplete example defines a new rule
+ set of name <literal>isolatin1-tolower</literal> that
+ inherits definitions from rule set
+ <literal>latin-tolower</literal>, overriding or adding
+ the sort rules in the list of <literal>:rules</literal>.
+ <programlisting>(define-rule-set "isolatin1-tolower"
+
+ :inherit-from ("latin-tolower")
+
+ :rules (("?" "?" :string :again)
+ ("?" "?" :string :again)
+ ("?" "?" :string :again)
+ ("?" "?" :string :again)
+ ("?" "?" :string :again)
+ ("?" "?" :string :again)
+ ("?" "?" :string :again)
+ ...
+ )
+...)</programlisting>
+ Rule sets can be instantiated with the command
+ <literal>use-rule-set</literal>. For further descriptions
+ on the sorting model refer to the command
+ <literal>sort-rule</literal>.
+ </para>
+ </section>
+
+ <section id="xindy-command-list-processing-define-sort-rule-orientations">
+ <title><literal>define-sort-rule-orientations</literal></title>
+ <indexterm>
+ <primary>&xindy;</primary>
+ <secondary>Processing Commands</secondary>
+ <tertiary>define-sort-rule-orientations</tertiary>
+ </indexterm>
+
+ <para><programlisting>(define-sort-rule-orientations (orientations...))</programlisting></para>
+ <para>Defines the order for the different sorting phases.
+ The currently implemented <emphasis>orientations</emphasis>
+ are <literal>forward</literal> and
+ <literal>backward</literal>.
+ This command must precede all <literal>sort-rule</literal>
+ commands in an index style. It defines the orientations
+ and implicitly sets the maximum number of sorting
+ phases performed.
+ </para>
+ <para>For further descriptions on the sorting model refer
+ to the command <literal>sort-rule</literal>.
+ </para>
+ </section>
+
+ <section id="xindy-command-list-processing-merge-rule">
+ <title><literal>merge-rule</literal></title>
+ <indexterm>
+ <primary>&xindy;</primary>
+ <secondary>Processing Commands</secondary>
+ <tertiary>merge-rule</tertiary>
+ </indexterm>
+ <para><programlisting>(merge-rule pattern replacement [:again]
+ [:bregexp | :eregexp | :string])</programlisting></para>
+ <para>Defines a keyword mapping rule that can be used to
+ generate the <emphasis>merge key</emphasis> from the
+ <emphasis>main key</emphasis> 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.
+ </para>
+ <para>The parameter <literal>pattern</literal> 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
+ <emphasis>basic regular expressions</emphasis> (BREs) or
+ <emphasis>extended regular expressions</emphasis> (EREs).
+ You can use the switch <literal>:bregexp</literal> to
+ force the interpretation of the pattern as a BRE, or
+ <literal>:eregexp</literal> to interpret it as an ERE.
+ If you want xindy to interpret the pattern literally, use
+ the switch <literal>:string</literal>. 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.
+ </para>
+ <para>The parameter <literal>replacement</literal> must be
+ a string possibly containing the special characters
+ <literal>&amp;</literal> (substitutes for the complete
+ match) and <literal>\1 ,..., \9</literal> (substituting
+ for the <emphasis>n</emphasis>-th submatch. Examples:
+ <programlisting>(merge-rule "A" "a")</programlisting>
+ replaces each occurrence of the uppercase letter
+ <literal>`A'</literal> with its lowercase counterpart.
+ <programlisting>(merge-rule "\~"([AEOUaeou])" "\1")</programlisting>
+ transforms the &tex; umlaut-letters into their stripped
+ counterparts, such that <literal>`\"A '</literal> is
+ treated as an <literal>`A'</literal> afterwards.
+ </para>
+ <para>The following sequences have a special meaning:
+ <variablelist role="db2latex:compact">
+ <varlistentry>
+ <term><literal>` ~n '</literal></term>
+ <listitem>
+ <para>End of line symbol
+ (<emphasis>linefeed</emphasis>).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>` ~b '</literal></term>
+ <listitem>
+ <para>The ISO-Latin character with the lowest
+ ordinal number.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>` ~e ' </literal></term>
+ <listitem>
+ <para>The ISO-Latin character with the highest ordinal
+ number.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>` ~~ ' </literal></term>
+ <listitem>
+ <para>The tilde character.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>` ~" '</literal></term>
+ <listitem>
+ <para>The double quote character.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ <para>Tilde characters and double quotes have to be quoted
+ themselves with a tilde character. The special characters
+ <literal>` ~b '</literal> and <literal>` ~e '</literal>
+ 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.
+ <literal>` m~e '</literal> is lexicographically placed
+ between <literal>`m'</literal> and <literal>`n'</literal>.
+ </para>
+ <para>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
+ <programlisting>(merge-rule "[A-Z]" "&amp;")</programlisting>
+ it is more efficient (though less comfortable) to use
+ <programlisting>(merge-rule "A" "Ax")
+(merge-rule "B" "Bx")
+...
+(merge-rule "Z" "Zx")</programlisting>
+ </para>
+ <para>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
+ <literal>`alpha'</literal> is checked before
+ <literal>`.*'</literal>, but <literal>`auto'</literal> and
+ <literal>`a.*'</literal> are checked in order of their
+ definition.
+ </para>
+ <para>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.
+ </para>
+ <para>Sometimes it is necessary to apply rules anew to the
+ result of a transformation. By specifying the keyword
+ argument <literal>:again</literal> 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
+ <programlisting>(merge-rule "\$(.*)\$" "\1" :again)</programlisting>
+ deletes <emphasis>all</emphasis> surrounding
+ <literal>`$ '</literal> symbols from the input.
+ </para>
+ <para>See also command <literal>sort-rule</literal>.</para>
+ </section>
+
+ <section id="xindy-command-list-processing-merge-to">
+ <title><literal>merge-to</literal></title>
+ <indexterm>
+ <primary>&xindy;</primary>
+ <secondary>Processing Commands</secondary>
+ <tertiary>merge-to</tertiary>
+ </indexterm>
+
+ <para><programlisting>(merge-to attr-from attr-to [:drop])</programlisting></para>
+ <para>A merge rule says that the attribute
+ <literal>attr-from</literal> can be used to build ranges in
+ <literal>attr-to</literal>. Both attributes must name valid
+ attribute names. The switch <literal>:drop</literal>
+ indicates, that the original location reference with
+ attribute <literal>attr-from</literal> has to be dropped
+ (removed), if a successful range was built with location
+ references in attribute <literal>attr-to</literal>.
+ A detailed description is given in the section about
+ processing phases.
+ </para>
+ </section>
+
+ <section id="xindy-command-list-processing-require">
+ <title><literal>require</literal></title>
+ <indexterm>
+ <primary>&xindy;</primary>
+ <secondary>Processing Commands</secondary>
+ <tertiary>require</tertiary>
+ </indexterm>
+
+ <para><programlisting>(require filename)</programlisting></para>
+ <para>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
+ <literal>filename</literal> 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:
+ <programlisting>(require "french/alphabet.xdy")
+(require "french/sort-rules.xdy")
+(require "tex/locations.xdy")
+(require "tex/markup.xdy")</programlisting>
+ Submodules can load other submodules as well. If a file is
+ required that was already loaded, the
+ <literal>require</literal> command is simply ignored and
+ processing continues without including this file twice.
+ See also command searchpath.
+ </para>
+ </section>
+
+ <section id="xindy-command-list-processing-searchpath">
+ <title><literal>searchpath</literal></title>
+ <indexterm>
+ <primary>&xindy;</primary>
+ <secondary>Processing Commands</secondary>
+ <tertiary>searchpath</tertiary>
+ </indexterm>
+
+ <para><programlisting>(searchpath {path-string | path-list})</programlisting></para>
+ <para>This command adds the given paths to the list of paths,
+ xindy searches for index style files. The argument
+ <literal>path-string</literal> 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:
+ <programlisting>(searchpath ".:/usr/local/lib/xindy:/usr/local/lib/xindy/english:")</programlisting>
+ 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
+ <programlisting>(searchpath ("."
+ "/usr/local/lib/xindy"
+ "/usr/local/lib/xindy/english"
+ :default))</programlisting>
+ yields exactly the same result as the example above. Here
+ <literal>path-list</literal> must be a list of strings and/or
+ the keyword(s) <literal>:default</literal> and
+ <literal>:last</literal>. The keyword
+ <literal>:default</literal> signifies that the default pathnames
+ are to be inserted at the specified position in the list.
+ The keyword <literal>:last</literal> 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.
+ </para>
+ </section>
+
+ <section id="xindy-command-list-processing-sort-rule">
+ <title><literal>sort-rule</literal></title>
+ <indexterm>
+ <primary>&xindy;</primary>
+ <secondary>Processing Commands</secondary>
+ <tertiary>sort-rule</tertiary>
+ </indexterm>
+
+ <para><programlisting>(sort-rule pattern replacement [:run level] [:again])</programlisting></para>
+ <para>Defines a keyword mapping rule that can be used to
+ generate the <emphasis>sort key</emphasis> of an index entry
+ from the <emphasis>merge key</emphasis>. This key is used
+ to sort the index entries lexicographically after they
+ have been merged using the merge key.
+ </para>
+ <para>The argument <literal>:run</literal> indicates that this
+ rule is only in effect a the specified
+ <emphasis>level</emphasis> (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 (<literal>new-sort-rules</literal>) that
+ comes with this distribution.
+ </para>
+ <para>See command <literal>merge-rule</literal> for more
+ information about keyword rules.
+ </para>
+ </section>
+
+ <section id="xindy-command-list-processing-use-rule-set">
+ <title><literal>use-rule-set</literal></title>
+ <indexterm>
+ <primary>&xindy;</primary>
+ <secondary>Processing Commands</secondary>
+ <tertiary>use-rule-set</tertiary>
+ </indexterm>
+
+ <para><programlisting>(use-rule-set [:run phase]
+ [:rule-set ( &lt;rule-set&gt;... ))</programlisting>
+ </para>
+ <para>This command instantiates the gives rule sets to be
+ in effect at sorting phase <literal>phase</literal>.
+ The order of the rule sets given with argument
+ <literal>:rule-set</literal> 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.
+ </para>
+ <para>The following example declares that in phase 0 the
+ rule sets <literal>din5007</literal> and
+ <literal>isolatin1-tolower</literal> should be active,
+ whereas in phase 2 the other rule sets have to be applied.
+ <programlisting>(use-rule-set :run 0
+ :rule-set ("din5007" "isolatin1-tolower"))
+
+(use-rule-set :run 1
+ :rule-set ("resolve-umlauts"
+ "resolve-sharp-s"
+ "isolatin1-tolower"
+ ))</programlisting>
+ </para>
+ <para>For a discussion on rule sets refer to command
+ <literal>define-rule-set</literal>.
+ </para>
+ </section>
+ </section>
+
+ <section id="xindy-command-list-markup">
+ <title>Markup Commands</title>
+ <indexterm>
+ <primary>&xindy;</primary>
+ <secondary>Command List</secondary>
+ <tertiary>Markup Commands</tertiary>
+ </indexterm>
+
+ <para>The following commands can be used to define the
+ markup of the index. They don't have any influence
+ on the indexing process. Since the markup scheme is
+ characterized by the concept of
+ <emphasis>environments</emphasis>, the syntax and naming
+ scheme of all commands follows a simple structure.
+ </para>
+ <para>The commands can be separated into
+ <emphasis>environment</emphasis> and
+ <emphasis>list-environment</emphasis> commands. All
+ commands of the first group support the keyword arguments
+ <literal>:open</literal> and <literal>:close</literal>,
+ whereas the second group additionally supports the keyword
+ argument <literal>:sep</literal>. If one of these keyword
+ arguments is missing, the default markup tag is always
+ the empty tag. The <literal>:open</literal> tag is always
+ printed before the object itself and the
+ <literal>:close</literal> tag is always printed after the
+ object has been printed. If a list is printed the
+ <literal>:sep</literal> tag is printed between two elements
+ of the list but not before the first element, or after the
+ last one. All commands dealing with a list have the suffix
+ <literal>`-list'</literal> as part of their command name.
+ </para>
+ <para>Since the number of commands and the heavy usage of
+ <emphasis>default</emphasis> and
+ <emphasis>specialized</emphasis> tags makes the markup
+ somehow complex (but very powerful) we have added a
+ mechanism to trace the markup tags xindy omits during
+ its markup phase with the command
+ <literal>markup-trace</literal>.
+ </para>
+ <para>Here follows the list of markup commands in alphabetical
+ order with some of the commands grouped together.
+ </para>
+
+ <section>
+ <title><literal>markup-attribute-group-list</literal></title>
+ <para><programlisting>(markup-attribute-group-list [:open string] [:close string]
+ [:sep string])
+
+(markup-attribute-group [:open string] [:close string]
+ [:group group-num])</programlisting>
+ </para>
+ <para>Location class groups consist of lists of attribute
+ groups. The markup of this list can be defined with the
+ command <literal>markup-attribute-group-list</literal>.
+ </para>
+ <para>To allow different markup for different attribute
+ groups the command <literal>markup-attribute-group</literal>
+ can be specialized on the group number with the keyword
+ argument <literal>:group</literal> which must be an integer
+ number. E.g., given are the groups
+ <literal>("definition" "theorem")</literal> and
+ <literal>("default")</literal> with group numbers 0 and 1,
+ then
+ <programlisting>(markup-attribute-group :open "&lt;group0&gt;" :close &lt;/group0&gt;"
+ :group 0)
+
+(markup-attribute-group :open "&lt;group1&gt;" :close "&lt;/group1&gt;"
+ :group 1)</programlisting>
+ can be used to assign different markup for both groups
+ in a SGML-based language.
+ </para>
+ </section>
+
+ <section>
+ <title><literal>markup-crossref-list</literal></title>
+ <para><programlisting>(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])</programlisting>
+ </para>
+ <para>A crossref class group contains cross references of the
+ same class. The separator between the classes is defined with
+ the <literal>(markup-locclass-list :sep)</literal>-parameter.
+ A list of cross references can be tagged with the
+ <literal>command markup-crossref-list</literal> that
+ specializes on the <literal>:class</literal> argument.
+ </para>
+ <para>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
+ <literal>command markup-crossref-layer-list</literal>
+ can be used.
+ </para>
+ <para>Each layer of a cross reference can be assigned two tags
+ that specialize on the class of the reference, like all
+ other commands.
+ </para>
+ <para>A suitable markup for a cross reference class
+ <literal>see</literal> within &latex2e; could look like that:
+ <programlisting>(markup-crossref-list :class "see" :open "\emph{see} "
+ :sep "; ")
+(markup-crossref-layer-list :class "see" :sep ",")
+(markup-crossref-layer :class "see"
+ :open "\textbf{" :close "}")</programlisting>
+ An example output could look like
+ <literal>... see house; garden,winter; greenhouse</literal>
+ </para>
+ </section>
+
+ <section>
+ <title><literal>markup-index</literal></title>
+ <para><programlisting>(markup-index [:open string] [:close string]
+ [ :flat | :tree | :hierdepth depth ])</programlisting>
+ </para>
+ <para>Defines the markup tags that enclose the whole index
+ via the <literal>:open</literal> and
+ <literal>:close</literal> parameters. Examples:
+ <programlisting>(markup-index :open "Here comes the index~n"
+ :close "That's all folks!~n")</programlisting>
+ defines that the <literal>:open</literal> string is printed
+ before the rest of the index and the <literal>:close</literal>
+ string appears after the index is printed.
+ </para>
+ <para>Additionally one can specify the form of the generated
+ index. It is possible to produce flat indexes by specifying
+ the switch <literal>:flat</literal>, to generate a tree with
+ the <literal>:tree</literal> switch or any kind of mixture
+ between both by specifying the depth up to which trees shall
+ be built with the parameter <literal>:hierdepth</literal>.
+ Its argument depth is the number of layers that can be formed
+ into a tree. Therefore <literal>:flat</literal> is an
+ abbrevation of <literal>:hierdepth 0</literal> and
+ <literal>:tree</literal> is an abbrevation of
+ <literal>:hierdepth max-depth</literal>, with
+ <literal>max-depth</literal> being the maximum number of
+ layers a keyword has. An example: the keywords
+ <programlisting>("tree" "binary" "AVL")
+("tree" "binary" "natural")</programlisting>
+ can be transformed in the following ways:
+ </para>
+ <para>A flat index (<literal>:flat</literal> or
+ <literal>:hierdepth 0</literal>)
+ <programlisting>tree binary AVL
+tree binary natural</programlisting>
+ with <literal>:hierdepth 1</literal>
+ <programlisting>tree
+ binary AVL
+ binary natural</programlisting>
+ and a tree (<literal>:tree</literal> or
+ <literal>:hierdepth > 1</literal>)
+ <programlisting>tree
+ binary
+ AVL
+ natural</programlisting>
+ Most often one will create tree-like indexes or
+ ones that are flat.
+ </para>
+ </section>
+
+ <section>
+ <title><literal>markup-indexentry-list</literal></title>
+ <para><programlisting>(markup-indexentry-list [:open string] [:close string]
+ [:sep string] [:depth integer])
+
+(markup-indexentry [:open string] [:close string]
+ [:depth integer])</programlisting>
+ </para>
+ <para>Letter groups consists of a list of index entries. The
+ command <literal>markup-indexentry-list</literal> defines
+ the markup of these lists. The markup can be specialized
+ on the depth if the index is hierarchically organized.
+ The command
+ <programlisting>(markup-indexentry-list :open "\begin{IdxentList}"
+ :close "\end{IdxentList}"
+ :sep "~n")</programlisting>
+ defines that the index entries of all layers are wrapped
+ into the given markup tags. If additionally
+ <programlisting>(markup-indexentry-list :open "\begin{IdxentListII}"
+ :close "\end{IdxentListII}"
+ :sep "~n"
+ :depth 2)</programlisting>
+ 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.
+ </para>
+ <para>The command <literal>markup-indexentry</literal> 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 <literal>:depth</literal>
+ 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.
+ </para>
+ <para><programlisting>(markup-indexentry :open "\begin{Indexentry}"
+ :close "\end{Indexentry}")</programlisting>
+ defines that the index entries of all layers are wrapped into
+ the given markup tags. If additionally
+ <programlisting>(markup-indexentry :open "\begin{IndexentryII}"
+ :close "\end{IndexentryII}"
+ :depth 2)</programlisting>
+ 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.
+ </para>
+ </section>
+
+ <section>
+ <title><literal>markup-keyword-list</literal></title>
+ <para><programlisting>(markup-keyword-list [:open string] [:close string]
+ [:sep string] [:depth integer])
+
+(markup-keyword [:open string] [:close string]
+ [:depth integer])</programlisting>
+ </para>
+ <para>The print key of an index entry consists of a list of
+ strings. The markup of this list can be defined with the
+ command <literal>markup-keyword-list</literal>. The keyword
+ argument <literal>:depth</literal> may be specified to
+ define the markup of the list at a particular depth.
+ </para>
+ <para>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
+ <literal>markup-keyword</literal>. Since we maybe need
+ different markup for different layers, the optional
+ keyword argument can be used to specialize this
+ markup for some depth.
+ </para>
+ </section>
+
+ <section>
+ <title><literal>markup-letter-group-list</literal></title>
+ <para><programlisting>(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])</programlisting>
+ </para>
+ <para>The first command defines the markup of the letter
+ group with name <literal>group-name</literal>. 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 <literal>:open-head</literal> and
+ <literal>:close-head</literal> is specified additional markup
+ is added as can be described as follows:
+ <programlisting>&lt;OPEN&gt;
+ IF (:open-head OR :close-head)
+ &lt;OPEN-HEAD&gt;
+ transformer-of(&lt;GROUP-NAME&gt;)
+ &lt;CLOSE-HEAD&gt;
+ FI
+ &lt;INDEXENTRIES...&gt;
+&lt;CLOSE&gt;</programlisting>
+ Here, <literal>transformer-of</literal> 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
+ <literal>:upcase</literal>, <literal>:downcase</literal>
+ and <literal>:capitalize</literal> which result in the
+ corresponding string conversions. If none of them is
+ specified no transformation is done at all.
+ </para>
+ <para>The command <literal>markup-letter-group</literal>
+ defines the markup of the list of letter groups.
+ </para>
+ </section>
+
+ <section>
+ <title><literal>markup-locclass-list</literal></title>
+ <para><programlisting>(markup-locclass-list [:open string] [:close string]
+ [:sep string])</programlisting>
+ </para>
+ <para>Each index entry contains a list of location class groups.
+ This markup command can be used to define the markup of
+ this list.
+ </para>
+ </section>
+
+ <section>
+ <title><literal>markup-locref</literal></title>
+ <para><programlisting>(markup-locref [:open string] [:close string]
+ [:class locref-class]
+ [:attr attribute]
+ [:depth integer])</programlisting>
+ </para>
+ <para>The markup tags of a location reference can be
+ specialized on the three arguments <literal>:class</literal>,
+ <literal>:attr</literal> and additionally, if
+ sub-references are used, <literal>:depth</literal>.
+ Most often one will only use a tag depending on the
+ attribute. For example, all location references with the
+ attribute <literal>definition</literal> should appear in
+ a font series like bold, emphasizing the importance of
+ this location reference; those with the attribute
+ <literal>default</literal> 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.
+ <programlisting>(markup-locref :open "&lt;B&gt;" :close "&lt;/B&gt;" :attr "definition")
+(markup-locref :open "&lt;I&gt;" :close "&lt;/I&gt;" :attr "default")</programlisting>
+ </para>
+ </section>
+
+ <section>
+ <title><literal>markup-locref-class</literal></title>
+ <para><programlisting>(markup-locref-class [:open string] [:close string]
+ [:class locref-class])</programlisting>
+ </para>
+ <para>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 <literal>:class</literal>.
+ </para>
+ </section>
+
+ <section>
+ <title><literal>markup-locref-layer</literal></title>
+ <para><programlisting>(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])</programlisting>
+ </para>
+ <para>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).
+ </para>
+ <para>The first command allows to tag the elements of a layer
+ list differently. The first element of this list can is
+ specialisable with <literal>:layer 0</literal>, the next
+ element with <literal>:layer 1</literal>, etc. See the next
+ example for an example.
+ </para>
+ </section>
+
+ <section>
+ <title><literal>markup-locref-list</literal></title>
+ <para><programlisting>(markup-locref-list [:open string] [:close string] [:sep string]
+ [:depth integer] [:class locref-class])</programlisting>
+ </para>
+ <para>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
+ <literal>:class</literal>, and on <literal>:depth</literal>
+ that specializes on the different subentry levels when using
+ location references with sub-references.
+ </para>
+ <para>Given is a list of location references that have the
+ class description
+ <programlisting>(define-location-class "Appendix"
+ ("ALPHA" :sep "-" "arabic-numbers")
+ :hierdepth 2)</programlisting>
+ </para>
+ <para>This location class has instances like
+ <literal>A-1</literal>, <literal>B-5</literal>, etc. The
+ keyword argument <literal>:hierdepth 2</literal> informs
+ &xindy; to markup these location references in a
+ hierarchical form. With the commands
+ <programlisting>(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")</programlisting>
+ we obtain a markup sequence for some example data that
+ could look like
+ <programlisting> \bf A} 1,2,5; {\bf B} 5,6,9; {\bf D} 1,5,8; ...</programlisting>
+ </para>
+ </section>
+
+ <section>
+ <title><literal>markup-range</literal></title>
+ <programlisting>(markup-range [:open string] [:close string] [:sep string]
+ [:class locref-class]
+ [:length num] [:ignore-end])</programlisting>
+
+ <para>A range consists of two location references. Markup
+ can be specified with the <literal>:open</literal> and
+ <literal>:close</literal> arguments and one separator given
+ by the argument <literal>:sep</literal>.</para>
+ <para>Since both location references are tagged with markup
+ defined by the command <literal>markup-locref</literal> 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
+ <literal>:length</literal> can be used to define different
+ markup for different lengths. In conjunction with
+ <literal>:length</literal> 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
+ <literal>:ignore-end</literal>.</para>
+ <para>The markup tags for a range (X,Y) can be described
+ as follows:
+ <programlisting>&lt;OPEN&gt;
+ Markup of location reference X
+&lt;SEP&gt;
+ IF (not :ignore-end)
+ Markup of location reference Y
+ FI
+&lt;CLOSE&gt;</programlisting>
+ </para>
+ <para>The following tags can be used to define a range of
+ page numbers (given in a location class
+ <literal>page-numbers</literal>) without considering the
+ open and close parameters:
+ <programlisting>(markup-range :sep "-" :class "page-numbers")</programlisting>
+ </para>
+ <para>Location ranges then appear separated by a hyphen in a
+ form like this:
+ <programlisting> ..., 5-8, 19-23, ...</programlisting>
+ </para>
+ </section>
+
+ <section>
+ <title><literal>(markup-trace [:on] [:open string] [:close string])</literal></title>
+ <para>This command can be used to activate the tracing of
+ all markup commands xindy executes. The switch
+ <literal>:on</literal> activates the trace. If
+ <literal>:on</literal> is omitted, the command line
+ flag <literal>-t</literal> 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 <literal>:open</literal> is
+ <literal>`&lt;'</literal> and for <literal>:close</literal>
+ is <literal>`&gt;'</literal>. The beginning of an example
+ output could look like:
+ <programlisting>&lt;INDEX:OPEN&gt;
+ &lt;LETTER-GROUP-LIST:OPEN&gt;
+ &lt;LETTER-GROUP:OPEN ["a"]&gt;
+ &lt;INDEXENTRY-LIST:OPEN [0]&gt;
+ &lt;INDEXENTRY:OPEN [0]&gt;
+ &lt;KEYWORD-LIST:OPEN [0]&gt;
+ &lt;KEYWORD:OPEN [0]&gt;
+ ...</programlisting>
+ </para>
+ <para>We use a simple indentation scheme to make the structure
+ of the tags visible. The symbolic tag
+ <literal>&lt;LETTER-GROUP:OPEN ["a"]&gt;</literal> for
+ example indicates that the tag that can be specified with
+ the command
+ <programlisting>(markup-letter-group :open "XXX" :group "a" ... )</programlisting>
+ 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
+ <programlisting>(markup-trace :open "%%" :close "~n")</programlisting>
+ or a definition in the TeX document like
+ <programlisting>\def\ignore#1{}</programlisting>
+ combined with the command
+ <programlisting>(markup-trace :open "\ignore{" :close "}")</programlisting>
+ </para>
+ </section>
+
+ </section>
+
+ <section id="xindy-command-list-raw-index">
+ <title>Raw Index Interface</title>
+ <indexterm>
+ <primary>&xindy;</primary>
+ <secondary>Command List</secondary>
+ <tertiary>Raw Index Interface</tertiary>
+ </indexterm>
+ <para>This section can be skipped if the reader is not
+ interested in adapting xindy to a new document
+ preparation system.
+ </para>
+ <para>The raw index is the file that represents the index
+ that is to be processed. Since many different document
+ preparation systems may use different forms of index
+ representations, their output must be transformed in a
+ form readable by xindy. We also could have written an
+ configurable parser performing this task, but usually
+ a tool written with some text processing tools such as
+ <command>perl</command>, <command>sed</command> or
+ <command>awk</command> can achieve the same task as well.
+ Therefore, adapting xindy to a completely different system
+ can mostly be done by writing an appropriate raw index filter.
+ </para>
+ <para>The format of the raw index interface of xindy is
+ defined as follows:
+ </para>
+ <programlisting>(indexentry { :key string-list [:print string-list]
+ | :tkey list-of-layers }
+ [:attr string]
+ { :locref string [:open-range | :close-range]
+ | :xref string-list } )</programlisting>
+ <para>The pseudo variable <emphasis>string</emphasis> is a
+ sequence of characters surrounded by double quotes, e.g.
+ <programlisting>"Hi, it's me" "one" "a string with two \"double quotes\""</programlisting>
+ are three examples of valid strings. If you need to include
+ a double quote as a literal character, you must quote it
+ itself with a backslash as shown in the third example.
+ A <emphasis>string list</emphasis> is simply a list of strings
+ separated by whitespaces and surrounded by round braces.
+ An example of a string list is
+ <programlisting>("This" "is" "a" "list" "of" "strings")</programlisting>
+ </para>
+ <para>So far about the syntax. The semantics of the
+ different elements are described here.
+ </para>
+ <variablelist role="db2latex:compact">
+ <varlistentry>
+ <term><literal>:key</literal></term>
+ <listitem>
+ <para>The argument <emphasis>string list</emphasis>
+ defines the keyword of the index entry. It must be
+ a list of strings, since the keyword may consist of
+ different layers such as
+ <literal>("heap" "fibonacci")</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>:print</literal></term>
+ <listitem>
+ <para>The optional <emphasis>print key</emphasis> defines
+ the way the keyword has to be printed in the markup phase.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>:tkey</literal></term>
+ <listitem>
+ <para>Another possibility to define the keys of an index
+ entry is with the <literal>:tkey</literal> keyword
+ argument. It can be used instead of the
+ <literal>:key</literal> and <literal>:print</literal>
+ arguments. Instead of specifying separately the key
+ and the corresponding print key, we define the keyword
+ by its layers. Each layer consist of a list of one or
+ two strings. The first string will be interpreted as the
+ main key, whereas the second one will become the print
+ key. If the print key is ommited, the main key is taken
+ instead. So the definition
+ <programlisting>:tkey (("This") ("is") ("a") ("bang" "BANG !!!"))</programlisting>
+ is equivalent to
+ <programlisting>:key ("This" "is" "a" "bang")
+:print ("This" "is" "a" "BANG !!!")</programlisting>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>:locref</literal></term>
+ <listitem>
+ <para>The reference an index entry describes can be a
+ <emphasis>location reference</emphasis> or a
+ <emphasis>cross reference</emphasis>. The switch
+ <literal>:locref</literal> describes a location
+ reference. Its optional arguments are
+ <literal>:open-range</literal> and
+ <literal>:close-range</literal>. The
+ <emphasis>string</emphasis> that must be supplied must
+ somehow encode the location reference. It might look
+ like the string <literal>"25"</literal> representing
+ the page number 25, or <literal>"Appendix-I"</literal>
+ representing the first appendix numbered in
+ uppercase roman numerals.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>:open-range,:close-range</literal></term>
+ <listitem>
+ <para>These are switches that do not take any arguments.
+ They describe the beginning and ending of a
+ <emphasis>range</emphasis>, starting or ending from
+ the location reference that is given by the argument
+ <literal>:locref</literal>. If they are supplied,
+ the location reference may have influence on the
+ way ranges are build.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>:xref</literal></term>
+ <listitem>
+ <para>These arguments choose the second alternative.
+ The argument <emphasis>string list</emphasis> of
+ parameter <literal>:xref</literal> describes where
+ the index entry should point to.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>:attr</literal></term>
+ <listitem>
+ <para>This parameter may be used to tag a location
+ reference with a certain attribute or it names the
+ class of a cross reference. It may also used to
+ associate different markup for different attributes
+ in the markup phase. If this parameter is omitted
+ or is the empty string, the indexentry is declared
+ to have the attribute <literal>default</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>Some examples:
+ <programlisting>(indexentry :key ("airplane") :locref "25" :attr "default")</programlisting>
+ defines an index entry with the key
+ <emphasis>airplane'</emphasis> indexed on page
+ <emphasis>25'</emphasis>. This index entry has the
+ attribute <literal>default</literal>.
+ </para>
+ <para><programlisting>(indexentry :key ("house") :xref("building") :attr "see")</programlisting>
+ defines a cross reference with the key
+ <literal>house</literal> pointing to the term
+ <literal>building</literal>. This cross reference belongs to
+ the cross reference class <literal>see</literal>.
+ </para>
+ <para><programlisting>(indexentry :key ("house") :xref("building") :open-range)</programlisting>
+ is an invalid specification, since
+ <literal>:open-range</literal>
+ mustn't be used together with cross references.
+ </para>
+ </section>
+
+ </section>
+
+ <section id="xindy-invoking">
+ <title>Invoking xindy</title>
+ <indexterm>
+ <primary>&xindy;</primary>
+ <secondary>Invoking</secondary>
+ </indexterm>
+
+ <section id="xindy-invoking-cmdline">
+ <title>Command Line Options</title>
+ <indexterm>
+ <primary>&xindy;</primary>
+ <secondary>Invoking</secondary>
+ <tertiary>Command Line Options</tertiary>
+ </indexterm>
+ <para>The following command line options are accepted:</para>
+ <programlisting>xindy [-h] [-t] [-v] [-l logfile] [-o outfile]
+ [-L n] [-f filterprog]
+ indexstyle raw-index</programlisting>
+ <para>The argument <literal>indexstyle</literal> names a file,
+ containing the index style description. The argument
+ <literal>raw-index</literal> names a file, containing
+ the raw index. Both arguments are mandatory.
+ </para>
+
+ <para><variablelist role="db2latex:compact">
+ <varlistentry>
+ <term>-h</term>
+ <listitem>
+ <para>Gives a short summary of all command line options.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>-l</term>
+ <listitem>
+ <para>Writes helpful information into the
+ specified <literal>logfile</literal>. For example,
+ the keyword mappings are written into this file,
+ so one can check if the intended mappings were
+ actually performed this way.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>-o</term>
+ <listitem>
+ <para>Explicitly defines the name of the
+ <literal>output</literal> file.
+ If not given, the name of the
+ <literal>raw-index</literal> is used with
+ its extension changed to <literal>.ind</literal>
+ (or added, if it had no extension at all).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>-t</term>
+ <listitem>
+ <para>Enters tracing mode of the symbolic markup tags.
+ The format of the emitted tags can be defined with
+ the command <literal>markup-trace</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>-L</term>
+ <listitem>
+ <para>Set the xindy logging-level to <literal>n</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>-f</term>
+ <listitem>
+ <para>Run <literal>filterprog</literal> on
+ <literal>raw-index</literal> before reading.
+ The program must act as a filter reading from
+ <literal>stdin</literal> and writing to
+ <literal>stdout</literal>. The most obvious use
+ of this option in conjunction with TeX is to run
+ <literal>-f tex2xindy</literal> on the index file
+ prior to reading the entries into xindy.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>-v</term>
+ <listitem>
+ <para>Shows the version number of xindy.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ Errors and warnings are reported to <literal>stdout</literal>
+ and additionally to the logfile if <literal>-l</literal>
+ was specified.
+ </para>
+ </section>
+
+ <section id="xindy-search-path">
+ <title>Search Path</title>
+ <indexterm>
+ <primary>&xindy;</primary>
+ <secondary>Invoking</secondary>
+ <tertiary>Search Path</tertiary>
+ </indexterm>
+ <para>The system uses the concept of a search path for
+ finding the index style files and modules. The searchpath
+ can be set with the environment variable
+ <envar>XINDY_SEARCHPATH</envar> which must contain a
+ list of colon-separated directories. If it ends with a
+ colon, the built-in searchpath is added to the entire
+ searchpath. See the command
+ <link linkend="xindy-command-list-processing-searchpath">searchpath</link>
+ for further details.
+ </para>
+ </section>
+
+ </section>
+
+</chapter>
+