diff options
Diffstat (limited to 'Build/source/utils/xindy-old/doc/manual-3.html')
| -rw-r--r-- | Build/source/utils/xindy-old/doc/manual-3.html | 1160 |
1 files changed, 0 insertions, 1160 deletions
diff --git a/Build/source/utils/xindy-old/doc/manual-3.html b/Build/source/utils/xindy-old/doc/manual-3.html deleted file mode 100644 index 3520de7f1ea..00000000000 --- a/Build/source/utils/xindy-old/doc/manual-3.html +++ /dev/null @@ -1,1160 +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 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> |