summaryrefslogtreecommitdiff
path: root/Build/source/utils/xindy-new/xindy/doc/manual-3.html
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/utils/xindy-new/xindy/doc/manual-3.html')
-rw-r--r--Build/source/utils/xindy-new/xindy/doc/manual-3.html1160
1 files changed, 1160 insertions, 0 deletions
diff --git a/Build/source/utils/xindy-new/xindy/doc/manual-3.html b/Build/source/utils/xindy-new/xindy/doc/manual-3.html
new file mode 100644
index 00000000000..3520de7f1ea
--- /dev/null
+++ b/Build/source/utils/xindy-new/xindy/doc/manual-3.html
@@ -0,0 +1,1160 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+<HEAD>
+ <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
+ <TITLE>xindy Manual: Command List</TITLE>
+ <LINK HREF="manual-4.html" REL=next>
+ <LINK HREF="manual-2.html" REL=previous>
+ <LINK HREF="manual.html#toc3" REL=contents>
+</HEAD>
+<BODY>
+<A HREF="manual-4.html">Next</A>
+<A HREF="manual-2.html">Previous</A>
+<A HREF="manual.html#toc3">Contents</A>
+<HR>
+<H2><A NAME="s3">3. Command List</A></H2>
+
+<P>Here is the complete list of <SF>xindy</SF>'s commands that may be used in
+the index style. The symbol <CODE>name</CODE> always refers to a string. We
+separate the commands into the <EM>processing</EM> and
+<EM>markup</EM> commands. The commands are listed in alphabetical order.
+<P>The parenthesis `<CODE>[</CODE>' and `<CODE>]</CODE>' denote optional parts of the
+syntax and `<CODE>{</CODE>' and `<CODE>}</CODE>' denote the grouping of elements. A
+vertical bar indicates alternatives. However, the enclosing round
+braces <EM>are</EM> part of the syntax and must be supplied.
+<P>
+<P>
+<H2><A NAME="ss3.1">3.1 Processing Commands</A>
+</H2>
+
+<P>Here follows the list of processing commands.
+<P>
+<A NAME="define-alphabet"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(define-alphabet name string-list)
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>Defines <CODE>name</CODE> to be the alphabet consisting of all elements of the
+<CODE>string-list</CODE>. Examples:
+<P>
+<PRE>
+ (define-alphabet "example-alphabet" ("An" "Example" "Alphabet"))
+</PRE>
+<P>defines an alphabet consisting of exactly three symbols. For the
+successor relationship holds: <CODE>succ("An")="Example"</CODE> and
+<CODE>succ("Example")="Alphabet"</CODE>. The built-in alphabet <CODE>digits</CODE> is
+defined as follows:
+<P>
+<PRE>
+ (define-alphabet "digits"
+ ("0" "1" "2" "3" "4" "5" "6" "7" "8" "9"))
+</PRE>
+<P>
+<P>
+<P>
+<A NAME="define-attributes"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(define-attributes attribute-list)
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>Defines all attributes the raw index may contain. Parameter
+<CODE>attribute-list</CODE> is a list of list of strings. The nesting level
+must not be more than&nbsp;2. So <CODE>(..(..)..)</CODE> is allowed, whereas
+<CODE>(..(..(..)..)..)</CODE> is not.
+<P>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 <CODE>("definition")</CODE> and <CODE>( ("definition") )</CODE> are equivalent.
+All elements forming a list are a so-called <EM>attribute group</EM>. The
+members of a group are written to the output file before any member
+of the following groups are written.
+<P>Examples of valid attributes lists are:
+<P><CODE>("definition" "usage")</CODE> defines two attribute groups. The first
+one contains all references with the attribute <CODE>definition</CODE> and the
+second one all with the attribute <CODE>usage</CODE>.
+<P><CODE>(("definition" "important") "usage")</CODE> defines two attribute
+groups. The first one contains all references with the attributes
+<CODE>definition</CODE> or <CODE>important</CODE> and the second one all with the
+attribute <CODE>usage</CODE>. In the attribute group <CODE>("definition"
+"important")</CODE> the attribute <CODE>definition</CODE> overrides <CODE>important</CODE>.
+<P>
+<P>
+<P>
+<A NAME="define-crossref-class"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(define-crossref-class name [:unverified])
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>Defines <CODE>name</CODE> to be a class of cross references. We distinguish
+two types of cross reference classes. <EM>Verified</EM> 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 <CODE>:unverified</CODE> can be used to suppress this
+behaviour.
+<P>
+<P>
+<A NAME="define-letter-group"></A>
+<A NAME="define-letter-groups"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(define-letter-group name [:before lgname] [:after lgname]
+ [:prefixes list-of-prefixes])
+
+(define-letter-groups list-of-letter-groups)
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>This command defines a letter group with name <CODE>name</CODE>, which must be
+a string value, grouping all index entries that have a <EM>sort key</EM>
+beginning with the prefix <CODE>name</CODE>. The command
+<P>
+<PRE>
+ (define-letter-group "a")
+</PRE>
+<P>is equivalent to the command
+<P>
+<PRE>
+ (define-letter-group "a" :prefixes ("a"))
+</PRE>
+<P>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.
+<P>Example:
+<P>
+<PRE>
+ (define-letter-group "a")
+</PRE>
+<P>defines a letter group containing all index entries beginning with the
+string <CODE>"a"</CODE>.
+<P>
+<PRE>
+ (define-letter-group "c" :after "a")
+</PRE>
+<P>defines a letter group containing all index entries beginning with the
+string <CODE>"c"</CODE>. The letter group appears behind the letter group "a"
+<P>
+<PRE>
+ (define-letter-group "b" :after "a" :before "c")
+</PRE>
+<P>inserts letter group "b" between letter group "a" and "c". This allows
+incremental definition of letter groups by extending already defined
+ones.
+<P>The arguments <CODE>:after</CODE> and <CODE>:before</CODE> define a partial order on
+the letter groups. <SF>xindy</SF> 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.
+<P>The command <CODE>define-letter-groups</CODE> (with an `s' at the end) is
+simply an abbreviation for a sequence of
+<CODE>define-letter-group</CODE> definitions where the elements are ordered in
+the ordering given by the list. Example:
+<P>
+<PRE>
+ (define-letter-groups ("a" "b" "c")
+</PRE>
+<P>equals the definitions
+<P>
+<PRE>
+ (define-letter-group "a")
+ (define-letter-group "b" :after "a")
+ (define-letter-group "c" :after "b")
+</PRE>
+<P>See also commands <CODE>markup-letter-group-list</CODE> and
+<CODE>markup-letter-group</CODE> for further information.
+<P>
+<P>
+<P>
+<A NAME="define-location-class"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(define-location-class name layer-list
+ [:min-range-length num]
+ [:hierdepth depth]
+ [:var])
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>Defines <CODE>name</CODE> 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 <CODE>:sep</CODE>. If the keyword <CODE>:min-range-length</CODE> is
+specified we define the <EM>minimum range length</EM> to be used when
+building ranges. The argument <CODE>num</CODE> must be a positive integer
+number or the keyword <CODE>none</CODE> in which case the building of ranges
+is disallowed. If the switch <CODE>:var</CODE> is specified the declared class
+is of type <EM>variable</EM>, i.e. it is a <EM>var-location-class</EM>. Since
+building of ranges is currently only allowed for standard classes
+<CODE>:var</CODE> and <CODE>:min-range-length</CODE> must not be used together. The
+keyword argument <CODE>:hierdepth</CODE> can be used to declare that the
+location references have to be tagged in a hierarchical form. Its
+argument <CODE>depth</CODE> must be an integer number indicating the number of
+layers the hierarchy does contain. See command
+<CODE>markup-locref-list</CODE> for more information. Examples:
+<P>
+<PRE>
+ (define-location-class "page-numbers" ("arabic-numbers")
+ :minimum-range-length 3)
+</PRE>
+<P>Defines the location class <CODE>page-numbers</CODE> consisting of one layer
+which is the alphabet <CODE>arabic-numbers</CODE>. 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 <CODE>0</CODE>, <CODE>1</CODE>, ... <CODE>2313</CODE>, etc.
+<P>
+<PRE>
+ (define-location-class "sections" :var
+ ("arabic-numbers" :sep "."
+ "arabic-numbers" :sep "."
+ "arabic-numbers"))
+</PRE>
+<P>defines a variable location class. Valid instances are <CODE>1</CODE>,
+<CODE>1.1</CODE>, <CODE>1.2</CODE>, <CODE>2</CODE>, <CODE>2.4.5</CODE>, but none of <CODE>2-3</CODE> (wrong
+separator), <CODE>1.2.3.4</CODE> (more than 3 layers), <CODE>2.3.iv</CODE> (roman
+number instead of arabic one).
+<P>
+<P>
+<P>
+<A NAME="define-location-class-order"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(define-location-class-order list)
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>Defines the order in which the location classes are written to the
+output file. The parameter <CODE>list</CODE> is a list of names of
+location classes. Examples:
+<P>
+<PRE>
+ (define-location-class-order
+ ("page-numbers" "sections" "xrefs"))
+</PRE>
+<P>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.
+<P>
+<P>
+<P>
+<A NAME="define-rule-set"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(define-rule-set name
+ [ :inherit-from ("rule-set" "rule-set-2") ]
+ :rules (&lt;rule>...) )
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>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 <CODE>sort-rule</CODE>.
+They do not add new functionality that is not already present with
+<CODE>sort-rule</CODE>.
+<P>A rule can be of the form:
+<P>
+<PRE>
+ &lt;rule> ::= ("pattern" "replacement"
+ [:string|:bregexp|:egegexp] [:again])
+</PRE>
+<P>The following incomplete example defines a new rule set of name
+<CODE>isolatin1-tolower</CODE> that inherits definitions from rule set
+<CODE>latin-tolower</CODE>, overriding or adding the sort rules in the list of
+<CODE>:rules</CODE>.
+<P>
+<PRE>
+ (define-rule-set "isolatin1-tolower"
+
+ :inherit-from ("latin-tolower")
+
+ :rules (("À" "à" :string :again)
+ ("Á" "á" :string :again)
+ ("Â" "â" :string :again)
+ ("Ã" "ã" :string :again)
+ ("Ä" "ä" :string :again)
+ ("Å" "å" :string :again)
+ ("Æ" "æ" :string :again)
+ ...
+ )
+ ...)
+</PRE>
+<P>Rule sets can be instantiated with the command <CODE>use-rule-set</CODE>. For
+further descriptions on the sorting model refer to the command
+<CODE>sort-rule</CODE>.
+<P>
+<P>
+<A NAME="define-sort-rule-orientations"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(define-sort-rule-orientations (orientations...))
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>Defines the order for the different sorting phases. The currently
+implemented <EM>orientations</EM> are <CODE>forward</CODE> and <CODE>backward</CODE>. This
+command must precede all <CODE>sort-rule</CODE> commands in an index style. It
+defines the orientations and implicitly sets the maximum number of
+sorting phases performed.
+<P>For further descriptions on the sorting model refer to the command
+<CODE>sort-rule</CODE>.
+<P>
+<P>
+<P>
+<A NAME="merge-rule"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(merge-rule pattern replacement [:again]
+ [:bregexp | :eregexp | :string])
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>Defines a keyword mapping rule that can be used to generate the
+<EM>merge key</EM> from the <EM>main key</EM> 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.
+<P>The parameter <CODE>pattern</CODE> 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 <EM>basic regular
+expressions</EM> (BREs) or <EM>extended regular expressions</EM> (EREs). You
+can use the switch <CODE>:bregexp</CODE> to force the interpretation of the
+pattern as a BRE, or <CODE>:eregexp</CODE> to interpret it as an ERE. If you
+want <SF>xindy</SF> to interpret the pattern literally, use the switch
+<CODE>:string</CODE>. If none of these switches is selected, <SF>xindy</SF> 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.
+<P>The parameter <CODE>replacement</CODE> must be
+a string possibly containing the special characters <CODE>&amp;</CODE>
+(substitutes for the complete match) and <CODE>\1</CODE>,...,<CODE>\9</CODE>
+(substituting for the <EM>n</EM>-th submatch. Examples:
+<P>
+<PRE>
+ (merge-rule "A" "a")
+</PRE>
+
+replaces each occurrence of the uppercase letter `<CODE>A</CODE>' with its
+lowercase counterpart.
+<P>
+<PRE>
+ (merge-rule "\~"([AEOUaeou])" "\1")
+</PRE>
+
+transforms the TeX umlaut-letters into their stripped counterparts,
+such that `<CODE>\"A</CODE>' is treated as an `<CODE>A</CODE>' afterwards.
+<P>The following sequences have a special meaning:
+<P>`<CODE>~n</CODE>' : End of line symbol (<EM>linefeed</EM>).
+<P>`<CODE>~b</CODE>' : The ISO-Latin character with the lowest ordinal number.
+<P>`<CODE>~e</CODE>' : The ISO-Latin character with the highest ordinal number.
+<P>`<CODE>~~</CODE>' : The tilde character.
+<P>`<CODE>~"</CODE>' : The double quote character.
+<P>Tilde characters and double quotes have to be quoted themselves with a
+tilde character. The special characters `<CODE>~b</CODE>' and
+`<CODE>~e</CODE>' 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. `<CODE>m~e</CODE>' is
+lexicographically placed between `<CODE>m</CODE>' and `<CODE>n</CODE>'.
+<P>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
+<P>
+<PRE>
+ (merge-rule "[A-Z]" "&amp;x")
+</PRE>
+<P>it is more efficient (though less comfortable) to use
+<P>
+<PRE>
+ (merge-rule "A" "Ax")
+ (merge-rule "B" "Bx")
+ ...
+ (merge-rule "Z" "Zx")
+</PRE>
+<P>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 `<CODE>alpha</CODE>' is checked before `<CODE>.*</CODE>', but
+`<CODE>auto</CODE>' and `<CODE>a.*</CODE>' are checked in order of their definition.
+<P>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.
+<P>Sometimes it is necessary to apply rules anew to the result of a
+transformation. By specifying the keyword argument <CODE>:again</CODE> in the
+merge rule the rule is marked as <EM>mutable</EM>, which means that after
+using this rule the transformation process shall restart at the same
+place. E.g. the rule
+<P>
+<PRE>
+ (merge-rule "\$(.*)\$" "\1" :again)
+</PRE>
+<P>deletes <EM>all</EM> surrounding `<CODE>$</CODE>' symbols from the input.
+<P>See also command <CODE>sort-rule</CODE>.
+<P>
+<P>
+<A NAME="merge-to"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(merge-to attr-from attr-to [:drop])
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>A <EM>merge rule</EM> says that the attribute <CODE>attr-from</CODE> can be used
+to build ranges in <CODE>attr-to</CODE>. Both attributes must name valid
+attribute names. The switch <CODE>:drop</CODE> indicates, that the original
+location reference with attribute <CODE>attr-from</CODE> has to be dropped
+(removed), if a successful range was built with location references in
+attribute <CODE>attr-to</CODE>. A detailed description is given in the section
+about processing phases.
+<P>
+<P>
+<P>
+<A NAME="require"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(require filename)
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>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
+<CODE>filename</CODE> 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:
+<P>
+<PRE>
+ (require "french/alphabet.xdy")
+ (require "french/sort-rules.xdy")
+ (require "tex/locations.xdy")
+ (require "tex/markup.xdy")
+</PRE>
+<P>Submodules can load other submodules as well. If a file is required
+that was already loaded, the <CODE>require</CODE> command is simply ignored
+and processing continues without including this file twice. See also
+command <CODE>searchpath</CODE>.
+<P>
+<P>
+<P>
+<A NAME="searchpath"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(searchpath {path-string | path-list})
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>This command adds the given paths to the list of paths, <SF>xindy</SF>
+searches for index style files. The argument <CODE>path-string</CODE> 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:
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+ (searchpath ".:/usr/local/lib/xindy:/usr/local/lib/xindy/english:")
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>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
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+ (searchpath ("."
+ "/usr/local/lib/xindy"
+ "/usr/local/lib/xindy/english"
+ :default))
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>yields exactly the same result as the example above. Here
+<CODE>path-list</CODE> must be a list of strings and/or the keyword(s)
+<CODE>:default</CODE> and <CODE>:last</CODE>. The keyword <CODE>:default</CODE> signifies that
+the default pathnames are to be inserted at the specified position in
+the list. The keyword <CODE>:last</CODE> 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.
+<P>
+<P>
+<A NAME="sort-rule"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(sort-rule pattern replacement [:run level] [:again])
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>Defines a keyword mapping rule that can be used to generate the
+<EM>sort key</EM> of an index entry from the <EM>merge key</EM>. This key is
+used to sort the index entries lexicographically after they have been
+merged using the merge key.
+<P>The argument <CODE>:run</CODE> indicates that this rule is only in effect
+a the specified <EM>level</EM> (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
+(<CODE>new-sort-rules</CODE>) that comes with this distribution.
+<P>See command <CODE>merge-rule</CODE> for more information about keyword
+rules.
+<P>
+<P>
+<P>
+<A NAME="use-rule-set"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(use-rule-set [:run phase]
+ [:rule-set ( &lt;rule-set>... ))
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>This command instantiates the gives rule sets to be in effect at
+sorting phase <CODE>phase</CODE>. The order of the rule sets given with
+argument <CODE>:rule-set</CODE> 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.
+<P>The following example declares that in phase 0 the rule sets
+<CODE>din5007</CODE> and <CODE>isolatin1-tolower</CODE> should be active, whereas in
+phase 2 the other rule sets have to be applied.
+<P>
+<PRE>
+ (use-rule-set :run 0
+ :rule-set ("din5007" "isolatin1-tolower"))
+
+ (use-rule-set :run 1
+ :rule-set ("resolve-umlauts"
+ "resolve-sharp-s"
+ "isolatin1-tolower"
+ ))
+</PRE>
+<P>For a discussion on rule sets refer to command <CODE>define-rule-set</CODE>.
+<P>
+<P>
+<P>
+<H2><A NAME="ss3.2">3.2 Markup Commands</A>
+</H2>
+
+<P>
+<P>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 <EM>environments</EM>,
+the syntax and naming scheme of all commands follows a simple
+structure.
+<P>The commands can be separated into <EM>environment</EM> and
+<EM>list-environment</EM> commands. All commands of the first group
+support the keyword arguments <CODE>:open</CODE> and <CODE>:close</CODE>, whereas the
+second group additionally supports the keyword argument <CODE>:sep</CODE>. If
+one of these keyword arguments is missing, the default markup tag is
+<EM>always</EM> the empty tag. The <CODE>:open</CODE> tag is always printed before
+the object itself and the <CODE>:close</CODE> tag is always printed after the
+object has been printed. If a list is printed the <CODE>:sep</CODE>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 `<CODE>-list</CODE>' as part of their command name.
+<P>Since the number of commands and the heavy usage of <EM>default</EM> and
+<EM>specialized</EM> tags makes the markup somehow complex (but very
+powerful) we have added a mechanism to trace the markup tags
+<SF>xindy</SF> omits during its markup phase with the command
+<CODE>markup-trace</CODE>.
+<P>Here follows the list of markup commands in alphabetical order with
+some of the commands grouped together.
+<P>
+<P>
+<A NAME="markup-attribute-group"></A>
+<A NAME="markup-attribute-group-list"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(markup-attribute-group-list [:open string] [:close string]
+ [:sep string])
+
+(markup-attribute-group [:open string] [:close string]
+ [:group group-num])
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>Location class groups consist of lists of attribute groups. The markup
+of this list can be defined with the command
+<CODE>markup-attribute-group-list</CODE>.
+<P>To allow different markup for different attribute groups the command
+<CODE>markup-attribute-group</CODE> can be specialized on the group number
+with the keyword argument <CODE>:group</CODE> which must be an integer number.
+E.g., given are the groups <CODE>("definition" "theorem")</CODE> and
+<CODE>("default")</CODE> with group numbers 0 and 1, then
+<P>
+<PRE>
+ (markup-attribute-group :open "&lt;group0>" :close "&lt;/group0>"
+ :group 0)
+
+ (markup-attribute-group :open "&lt;group1>" :close "&lt;/group1>"
+ :group 1)
+</PRE>
+<P>can be used to assign different markup for both groups in a SGML-based
+language.
+<P>
+<P>
+<A NAME="markup-crossref-layer"></A>
+<A NAME="markup-crossref-layer-list"></A>
+<A NAME="markup-crossref-list"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(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])
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>A crossref class group contains cross references of the same class.
+The separator between the classes is defined with the
+<CODE>(markup-locclass-list :sep)</CODE>-parameter. A list of cross references
+can be tagged with the command <CODE>markup-crossref-list</CODE> that
+specializes on the <CODE>:class</CODE> argument.
+<P>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 <CODE>markup-crossref-layer-list</CODE> can be used.
+<P>Each layer of a cross reference can be assigned two tags that
+specialize on the class of the reference, like all other commands.
+<P>A suitable markup for a cross reference class <CODE>see</CODE> within LaTeX2e
+could look like that:
+<P>
+<PRE>
+ (markup-crossref-list :class "see" :open "\emph{see} "
+ :sep "; ")
+ (markup-crossref-layer-list :class "see" :sep ",")
+ (markup-crossref-layer :class "see"
+ :open "\textbf{" :close "}")
+</PRE>
+<P>An example output could look like
+<P>
+<BLOCKQUOTE>
+... <EM>see</EM> <B>house</B>; <B>garden</B>,<B>winter</B>; <B>greenhouse</B>
+</BLOCKQUOTE>
+<P>
+<P>
+<A NAME="markup-index"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(markup-index [:open string] [:close string]
+ [ :flat | :tree | :hierdepth depth ])
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>Defines the markup tags that enclose the whole index via the
+<CODE>:open</CODE> and <CODE>:close</CODE> parameters. Examples:
+<P>
+<PRE>
+ (markup-index :open "Here comes the index~n"
+ :close "That's all folks!~n")
+</PRE>
+<P>defines that the <CODE>:open</CODE> string is printed before the rest of the
+index and the <CODE>:close</CODE> string appears after the index is printed.
+<P>Additionally one can specify the form of the generated index. It is
+possible to produce flat indexes by specifying the switch <CODE>:flat</CODE>,
+to generate a tree with the <CODE>:tree</CODE> switch or any kind of mixture
+between both by specifying the depth up to which trees shall be built
+with the parameter <CODE>:hierdepth</CODE>. Its argument <CODE>depth</CODE> is the
+number of layers that can be formed into a tree. Therefore <CODE>:flat</CODE>
+is an abbrevation of <CODE>:hierdepth 0</CODE> and <CODE>:tree</CODE> is an
+abbrevation of <CODE>:hierdepth max-depth</CODE>, with <CODE>max-depth</CODE> being
+the maximum number of layers a keyword has. An example: the keywords
+<P>
+<PRE>
+ ("tree" "binary" "AVL")
+ ("tree" "binary" "natural")
+</PRE>
+<P>can be transformed in the following ways:
+<P>A flat index (<CODE>:flat</CODE> or <CODE>:hierdepth 0</CODE>)
+<P>
+<PRE>
+ tree binary AVL
+ tree binary natural
+</PRE>
+<P>with <CODE>:hierdepth 1</CODE>
+<P>
+<PRE>
+ tree
+ binary AVL
+ binary natural
+</PRE>
+<P>and a tree (<CODE>:tree</CODE> or <CODE>:hierdepth</CODE> &gt; 1)
+<P>
+<PRE>
+ tree
+ binary
+ AVL
+ natural
+</PRE>
+<P>Most often one will create tree-like indexes or ones that are flat.
+<P>
+<P>
+<A NAME="markup-indexentry-list"></A>
+<A NAME="markup-indexentry"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(markup-indexentry-list [:open string] [:close string]
+ [:sep string] [:depth integer])
+
+(markup-indexentry [:open string] [:close string]
+ [:depth integer])
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>Letter groups consists of a list of index entries. The command
+<CODE>markup-indexentry-list</CODE> defines the markup of these lists. The
+markup can be specialized on the depth if the index is hierarchically
+organized. The command
+<P>
+<PRE>
+ (markup-indexentry-list :open "\begin{IdxentList}"
+ :close "\end{IdxentList}"
+ :sep "~n")
+</PRE>
+<P>defines that the index entries of all layers are wrapped into the
+given markup tags. If additionally
+<P>
+<PRE>
+ (markup-indexentry-list :open "\begin{IdxentListII}"
+ :close "\end{IdxentListII}"
+ :sep "~n"
+ :depth 2)
+</PRE>
+<P>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.
+<P>The command <CODE>markup-indexentry</CODE> 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 <CODE>:depth</CODE> 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.
+<P>
+<PRE>
+ (markup-indexentry :open "\begin{Indexentry}"
+ :close "\end{Indexentry}")
+</PRE>
+<P>defines that the index entries of all layers are wrapped into the
+given markup tags. If additionally
+<P>
+<PRE>
+ (markup-indexentry :open "\begin{IndexentryII}"
+ :close "\end{IndexentryII}"
+ :depth 2)
+</PRE>
+<P>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.
+<P>
+<P>
+<A NAME="markup-keyword-list"></A>
+<A NAME="markup-keyword"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(markup-keyword-list [:open string] [:close string]
+ [:sep string] [:depth integer])
+
+(markup-keyword [:open string] [:close string]
+ [:depth integer])
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>
+<P>The print key of an index entry consists of a list of strings. The
+markup of this list can be defined with the command
+<CODE>markup-keyword-list</CODE>. The keyword argument <CODE>:depth</CODE> may be
+specified to define the markup of the list at a particular depth.
+<P>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
+<CODE>markup-keyword</CODE>. Since we maybe need different markup for
+different layers, the optional keyword argument can be used to
+specialize this markup for some depth.
+<P>
+<P>
+<A NAME="markup-letter-group-list"></A>
+<A NAME="markup-letter-group"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(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])
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>The first command defines the markup of the letter group with name
+<CODE>group-name</CODE>. 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 <CODE>:open-head</CODE> and <CODE>:close-head</CODE> is specified
+additional markup is added as can be described as follows:
+<P>
+<PRE>
+ &lt;OPEN>
+ IF (:open-head OR :close-head)
+ &lt;OPEN-HEAD>
+ transformer-of(&lt;GROUP-NAME>)
+ &lt;CLOSE-HEAD>
+ FI
+ &lt;INDEXENTRIES...>
+ &lt;CLOSE>
+</PRE>
+<P>Here, <CODE>transformer-of</CODE> 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
+<CODE>:upcase</CODE>, <CODE>:downcase</CODE> and <CODE>:capitalize</CODE> which result in the
+corresponding string conversions. If none of them is specified no
+transformation is done at all.
+<P>The command <CODE>markup-letter-group</CODE> defines the markup of the list of
+letter groups.
+<P>
+<P>
+<A NAME="markup-locclass-list"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(markup-locclass-list [:open string] [:close string]
+ [:sep string])
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>Each index entry contains a list of location class groups. This markup
+command can be used to define the markup of this list.
+<P>
+<P>
+<A NAME="markup-locref"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(markup-locref [:open string] [:close string]
+ [:class locref-class]
+ [:attr attribute]
+ [:depth integer])
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>The markup tags of a location reference can be specialized on the
+three arguments <CODE>:class</CODE>, <CODE>:attr</CODE> and additionally, if
+sub-references are used, <CODE>:depth</CODE>. Most often one will only use a
+tag depending on the attribute. For example, all location references
+with the attribute <CODE>definition</CODE> should appear in a font series like
+bold, emphasizing the importance of this location reference; those
+with the attribute <CODE>default</CODE> 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.
+<P>
+<PRE>
+ (markup-locref :open "&lt;B>" :close "&lt;/B>" :attr "definition")
+ (markup-locref :open "&lt;I>" :close "&lt;/I>" :attr "default")
+</PRE>
+<P>
+<P>
+<A NAME="markup-locref-class"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(markup-locref-class [:open string] [:close string]
+ [:class locref-class])
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>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 <CODE>:class</CODE>.
+<P>
+<P>
+<A NAME="markup-locref-layer-list"></A>
+<A NAME="markup-locref-layer"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(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])
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>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).
+<P>The first command allows to tag the elements of a layer list
+differently. The first element of this list can is specialisable with
+<CODE>:layer 0</CODE>, the next element with <CODE>:layer 1</CODE>, etc. See the next
+example for an example.
+<P>
+<P>
+<A NAME="markup-locref-list"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(markup-locref-list [:open string] [:close string] [:sep string]
+ [:depth integer] [:class locref-class])
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>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 <CODE>:class</CODE>, and on <CODE>:depth</CODE>
+that specializes on the different subentry levels when using
+location references with sub-references.
+<P>Given is a list of location references that have the class description
+<P>
+<PRE>
+ (define-location-class "Appendix"
+ ("ALPHA" :sep "-" "arabic-numbers")
+ :hierdepth 2)
+</PRE>
+<P>This location class has instances like <CODE>A-1</CODE>, <CODE>B-5</CODE>, etc. The
+keyword argument <CODE>:hierdepth 2</CODE> informs <SF>xindy</SF> to markup these
+location references in a hierarchical form. With the commands
+<P>
+<PRE>
+ (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")
+</PRE>
+<P>we obtain a markup sequence for some example data that could look like
+<P>
+<PRE>
+ {\bf A} 1,2,5; {\bf B} 5,6,9; {\bf D} 1,5,8; ...
+</PRE>
+<P>
+<P>
+<P>
+<A NAME="markup-range"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(markup-range [:open string] [:close string] [:sep string]
+ [:class locref-class]
+ [:length num] [:ignore-end])
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>A range consists of two location references. Markup can be specified
+with the <CODE>:open</CODE> and <CODE>:close</CODE> arguments and one separator given
+by the argument <CODE>:sep</CODE>.
+<P>Since both location references are tagged with markup defined by the
+command <CODE>markup-locref</CODE> 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 <CODE>:length</CODE> can be used to define
+different markup for different lengths. In conjunction with
+<CODE>:length</CODE> 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 <EM>Xf.</EM> instead of <EM>X--Y</EM>. This can be accomplished
+with the switch <CODE>:ignore-end</CODE>.
+<P>The markup tags for a range <EM>(X,Y)</EM> can be described as follows:
+<P>
+<PRE>
+ &lt;OPEN>
+ Markup of location reference X
+ &lt;SEP>
+ IF (not :ignore-end)
+ Markup of location reference Y
+ FI
+ &lt;CLOSE>
+</PRE>
+<P>
+<P>The following tags can be used to define a range of page numbers
+(given in a location class <CODE>page-numbers</CODE>) without considering the
+open and close parameters:
+<P>
+<PRE>
+ (markup-range :sep "-" :class "page-numbers")
+</PRE>
+<P>Location ranges then appear separated by a hyphen in a form like this:
+<P>
+<PRE>
+ ..., 5-8, 19-23, ...
+</PRE>
+<P>
+<P>
+<A NAME="markup-trace"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(markup-trace [:on] [:open string] [:close string])
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>This command can be used to activate the tracing of all
+markup commands <SF>xindy</SF> executes. The switch <CODE>:on</CODE> activates the
+trace. If <CODE>:on</CODE> is omitted, the command line flag <CODE>-t</CODE> 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 <CODE>:open</CODE> is `<CODE>&lt;</CODE>' and for <CODE>:close</CODE> is
+`<CODE>></CODE>'. The beginning of an example output could look like:
+<P>
+<PRE>
+ &lt;INDEX:OPEN>
+ &lt;LETTER-GROUP-LIST:OPEN>
+ &lt;LETTER-GROUP:OPEN ["a"]>
+ &lt;INDEXENTRY-LIST:OPEN [0]>
+ &lt;INDEXENTRY:OPEN [0]>
+ &lt;KEYWORD-LIST:OPEN [0]>
+ &lt;KEYWORD:OPEN [0]>
+ ...
+</PRE>
+<P>We use a simple indentation scheme to make the structure of the tags
+visible. The symbolic tag <CODE>&lt;LETTER-GROUP:OPEN ["a"]></CODE> for example
+indicates that the tag that can be specified with the command
+<P>
+<PRE>
+ (markup-letter-group :open "XXX" :group "a" ... )
+</PRE>
+<P>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
+<P>
+<PRE>
+ (markup-trace :open "%%" :close "~n")
+</PRE>
+<P>or a definition in the TeX document like
+<P>
+<PRE>
+ \def\ignore#1{}
+</PRE>
+<P>combined with the command
+<P>
+<PRE>
+ (markup-trace :open "\ignore{" :close "}")
+</PRE>
+<P>
+<P>
+<P>
+<A NAME="raw-index"></A> <H2><A NAME="ss3.3">3.3 Raw Index Interface</A>
+</H2>
+
+<P>
+<P>This section can be skipped if the reader is not interested in
+adapting <SF>xindy</SF> to a new document preparation system.
+<P>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 <SF>xindy</SF>. We also could have
+written an configurable parser performing this task, but usually a
+tool written with some text processing tools such as <CODE>perl</CODE>,
+<CODE>sed</CODE> or <CODE>awk</CODE> can achieve the same task as well. Therefore,
+adapting <SF>xindy</SF> to a completely different system can mostly be
+done by writing an appropriate raw index filter.
+<P>The format of the raw index interface of <SF>xindy</SF> is defined as
+follows:
+<P>
+<A NAME="indexentry"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(indexentry { :key string-list [:print string-list]
+ | :tkey list-of-layers }
+ [:attr string]
+ { :locref string [:open-range | :close-range]
+ | :xref string-list } )
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>The pseudo variable <EM>string</EM> is a sequence of characters
+surrounded by double quotes, e.g.
+<P>
+<PRE>
+ "Hi, it's me" "one" "a string with two \"double quotes\""
+</PRE>
+<P>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 <EM>string list</EM> is simply
+a list of strings separated by whitespaces and surrounded by round
+braces. An example of a string list is
+<P>
+<PRE>
+ ("This" "is" "a" "list" "of" "strings")
+</PRE>
+<P>So far about the syntax. The semantics of the different elements are
+described here.
+<P>
+<P>
+<DL>
+<P>
+<DT><B><CODE>:key</CODE></B><DD><P>The argument <EM>string list</EM> defines the keyword of
+the index entry. It must be a list of strings, since the keyword may
+consist of different layers such as <CODE>("heap" "fibonacci")</CODE>.
+<P>
+<DT><B><CODE>:print</CODE></B><DD><P>The optional <EM>print key</EM> defines the way the
+keyword has to be printed in the markup phase.
+<P>
+<DT><B><CODE>:tkey</CODE></B><DD><P>Another possibility to define the keys of an
+index entry is with the <CODE>:tkey</CODE> keyword argument. It can be used
+instead of the <CODE>:key</CODE> and <CODE>:print</CODE> 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
+<P>
+<PRE>
+ :tkey (("This") ("is") ("a") ("bang" "BANG !!!"))
+</PRE>
+<P>is equivalent to
+<P>
+<PRE>
+ :key ("This" "is" "a" "bang")
+ :print ("This" "is" "a" "BANG !!!")
+</PRE>
+<P>
+<P>
+<DT><B><CODE>:locref</CODE></B><DD><P>The reference an index entry describes can be a
+<EM>location reference</EM> or a <EM>cross reference</EM>. The switch
+<CODE>:locref</CODE> describes a location reference. Its optional arguments
+are <CODE>:open-range</CODE> and <CODE>:close-range</CODE>. The <EM>string</EM> that must
+be supplied must somehow encode the location reference. It might look
+like the string <CODE>"25"</CODE> representing the page number 25, or
+<CODE>"Appendix-I"</CODE> representing the first appendix numbered in
+uppercase roman numerals.
+<P>
+<DT><B><CODE>:open-range</CODE>,<CODE>:close-range</CODE></B><DD><P>These are switches that do not
+take any arguments. They describe the beginning and ending of a
+<EM>range</EM>, starting or ending from the location reference that is
+given by the argument <CODE>:locref</CODE>. If they are supplied, the
+location reference may have influence on the way ranges are build.
+<P>
+<DT><B><CODE>:xref</CODE></B><DD><P>These arguments choose the second alternative. The
+argument <EM>string list</EM> of parameter <CODE>:xref</CODE> describes where the
+index entry should point to.
+<P>
+<DT><B><CODE>:attr</CODE></B><DD><P>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
+<CODE>default</CODE>.
+<P>
+</DL>
+<P>Some examples:
+<P>
+<PRE>
+ (indexentry :key ("airplane") :locref "25" :attr "default")
+</PRE>
+<P>defines an index entry with the key `airplane' indexed on page '25'.
+This index entry has the attribute <CODE>default</CODE>.
+<P>
+<PRE>
+ (indexentry :key ("house") :xref ("building") :attr "see")
+</PRE>
+<P>defines a cross reference with the key 'house' pointing to the term
+'building'. This cross reference belongs to the cross reference class
+<CODE>see</CODE>.
+<P>
+<PRE>
+ (indexentry :key ("house") :xref ("building") :open-range)
+</PRE>
+<P>is an invalid specification, since <CODE>:open-range</CODE> mustn't be used
+together with cross references.
+<P>
+<P>
+<P>
+<HR>
+<A HREF="manual-4.html">Next</A>
+<A HREF="manual-2.html">Previous</A>
+<A HREF="manual.html#toc3">Contents</A>
+</BODY>
+</HTML>