summaryrefslogtreecommitdiff
path: root/Build/source/utils/xindy/xindy-src/doc/manual-3.html
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/utils/xindy/xindy-src/doc/manual-3.html')
-rw-r--r--Build/source/utils/xindy/xindy-src/doc/manual-3.html1159
1 files changed, 0 insertions, 1159 deletions
diff --git a/Build/source/utils/xindy/xindy-src/doc/manual-3.html b/Build/source/utils/xindy/xindy-src/doc/manual-3.html
deleted file mode 100644
index 10d4a725a54..00000000000
--- a/Build/source/utils/xindy/xindy-src/doc/manual-3.html
+++ /dev/null
@@ -1,1159 +0,0 @@
-<!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. Use a sufficiently large number (such as 10000) to disallow the building of ranges.
-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")
- :min-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]
- [:attr attribute]
- [: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>The markup of the separator can be specified attributes via
-the<CODE>:attr</CODE> tag.
-<P>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>