diff options
Diffstat (limited to 'Build/source/utils/xindy/doc/manual-3.html')
| -rw-r--r-- | Build/source/utils/xindy/doc/manual-3.html | 1160 |
1 files changed, 1160 insertions, 0 deletions
diff --git a/Build/source/utils/xindy/doc/manual-3.html b/Build/source/utils/xindy/doc/manual-3.html new file mode 100644 index 00000000000..3520de7f1ea --- /dev/null +++ b/Build/source/utils/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 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 (<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> + <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>&</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]" "&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 ( <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 "<group0>" :close "</group0>" + :group 0) + + (markup-attribute-group :open "<group1>" :close "</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> > 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> + <OPEN> + IF (:open-head OR :close-head) + <OPEN-HEAD> + transformer-of(<GROUP-NAME>) + <CLOSE-HEAD> + FI + <INDEXENTRIES...> + <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 "<B>" :close "</B>" :attr "definition") + (markup-locref :open "<I>" :close "</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> + <OPEN> + Markup of location reference X + <SEP> + IF (not :ignore-end) + Markup of location reference Y + FI + <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><</CODE>' and for <CODE>:close</CODE> is +`<CODE>></CODE>'. The beginning of an example output could look like: +<P> +<PRE> + <INDEX:OPEN> + <LETTER-GROUP-LIST:OPEN> + <LETTER-GROUP:OPEN ["a"]> + <INDEXENTRY-LIST:OPEN [0]> + <INDEXENTRY:OPEN [0]> + <KEYWORD-LIST:OPEN [0]> + <KEYWORD:OPEN [0]> + ... +</PRE> +<P>We use a simple indentation scheme to make the structure of the tags +visible. The symbolic tag <CODE><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> |