diff options
Diffstat (limited to 'Build/source/utils/xindy-old/doc/manual-2.html')
-rw-r--r-- | Build/source/utils/xindy-old/doc/manual-2.html | 302 |
1 files changed, 0 insertions, 302 deletions
diff --git a/Build/source/utils/xindy-old/doc/manual-2.html b/Build/source/utils/xindy-old/doc/manual-2.html deleted file mode 100644 index c3a7a87be77..00000000000 --- a/Build/source/utils/xindy-old/doc/manual-2.html +++ /dev/null @@ -1,302 +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: How the Index Processor Works</TITLE> - <LINK HREF="manual-3.html" REL=next> - <LINK HREF="manual-1.html" REL=previous> - <LINK HREF="manual.html#toc2" REL=contents> -</HEAD> -<BODY> -<A HREF="manual-3.html">Next</A> -<A HREF="manual-1.html">Previous</A> -<A HREF="manual.html#toc2">Contents</A> -<HR> -<H2><A NAME="how-works"></A> <A NAME="s2">2. How the Index Processor Works</A></H2> - -<P> -<P> -<H2><A NAME="ss2.1">2.1 Data Flow</A> -</H2> - -<P>Usually document preparation systems produce some form data that -describe the <EM>index entries</EM> and the <EM>locations</EM> they point to. -This data is called the <EM>raw index</EM> since it consists of raw data -which contains structured information about the entries of the index. -The raw index is fed into the index processor and is processed -according to a specification called the <EM>index style</EM>. This is a -user-definable description how the index is to be processed, what -sort rules for the keywords should be used, which kind of locations -may appear, and finally, what tags should be emitted when writing the -index into the output file. The result is sometimes fed back into the -document preparation system, as it is in the case of TeX, or used -otherwise. The following figure illustrates this embedding into the -document preparation process. -<P> -<FIGURE> -<EPS FILE="dataflow.eps"> -<IMG SRC="dataflow.gif"> -</FIGURE> -<P>The <SF>xindy</SF> system is oriented on book-like indexes in a form that -is described later in detail. The format of the input data is fixed -and a small tool that converts some system dependent raw index in a -form suitable for <SF>xindy</SF> should not be a big hurdle. The user is -normally not involved in the correct format suitable for <SF>xindy</SF> -and some tools will make this work invisible to him. -<P>In contrast, the output of the <SF>xindy</SF> system is highly -configurable and can produce a variety of different markups. -Additionally, the way <SF>xindy</SF> processes the index data can be -parametrized and controlled in many ways and gives the user a powerful -framework for describing complex indexes. The user can tell <SF>xindy</SF> -how it should produce an output according to his wishes or simply use -some of the predefined styles that come with the distribution. -<P> -<P> -<P> -<P> -<H2><A NAME="general-concepts"></A> <A NAME="ss2.2">2.2 General Concepts and Terms</A> -</H2> - -<P>In the following sections we introduce some terms that are necessary -to understand the way <SF>xindy</SF> works. -<P>The development of <SF>xindy</SF> started with the devlopment of a model -of a <EM>book-like</EM> index. This rather vague term will now be fleshed -out by giving a semi-formal description of the model. If the structure -of an index conforms to this model it can be processed by <SF>xindy</SF>. -We first present a diagram that describes the structure of a processed -index. It is a hierarchical recursive data structure which we will -describe now. -<P> -<FIGURE> -<EPS FILE="index.eps"> -<IMG SRC="index.gif"> -</FIGURE> -<P>Boxed objects contain elements from the raw index such as the keywords -or the location reference layers. We start from the root of the -diagram and explain the different elements. -<P> -<P> -<P> -<DL> -<P> -<DT><B>index</B><DD><P>An index consists of a list of <SF>letter-groups</SF>. -<P> -<P> -<A NAME="def letter-group"></A> <DT><B>letter-group</B><DD><P>The letter groups serve as containers for -<SF>indexentries</SF>. The letter groups are intended to group all -index entries sharing a common <SF>keyword</SF> prefix, allowing the -assignment of a specific markup for each group. For example, indexes -are often organized in a way that new index entries beginning with a -new letter are separated by a specific markup. The following example -illustrates this style. -<P> -<PRE> - B - bread 25, 27 - butter 26 - - M - marmalade 19 - milk 21 -</PRE> -<P>Here we have two letter groups for the letters `B' and `M' because the -keywords `bread' and `butter' share the same prefix `b' and -`marmalade' and `milk' share the prefix `m'. <SF>xindy</SF> can be advised -to define arbitrary letter groups with a particular markup for each of -them. See command <CODE>define-letter-group</CODE> for further details. -<P> -<P> -<DT><B>indexentry</B><DD><P>An index entry consists of three components: the -<SF>keyword</SF> and optionally the list of <SF>location-class-groups</SF> and -the sub-<SF>indexentries</SF>. An example: -<P> -<PRE> - bread 25-30 - brown 26 - white 27 -</PRE> -<P>This index entry consists of the keyword `bread', the -location class list `25-30' and the sub-entries `brown 26' and `white -27'. The sub-entries themselves are complete index entries as well, -forming a recursive data structure. -<P> -<P> -<DT><B>keyword</B><DD><P>The keyword is the identifier of an index entry. It -consists of a list of strings being the <EM>key</EM> if the index entry. In -our model the keyword constists of a list of strings, since indexes -are often organized hierarchically with different layers. In the -example -<P> -<PRE> - bread 25-30 - bread, brown 26 - bread, white 27 -</PRE> -<P>we have keywords `bread', `bread, brown' and `bread, white'. -<P>A keyword is actually separated into four different keys. The -<SF>main-key</SF> is the key that is specified from the author who indexes -a document. The <SF>merge-key</SF> is derived from the main key with the -so-called <EM>merge mapping</EM>. This mapping is accomplished with a set -of rewrite rules. The <SF>sort-key</SF> is derived from the merge key with -another set of rewrite rules called the <EM>sort mapping</EM>. The -<SF>print-key</SF> can be specified by the user explicitely or, if it is -ommited, equals the main key. The rewrite rules consist of string -substitutions that also include regular expression features. -<P>The following figure describes this: -<P> -<FIGURE> -<EPS FILE="mappings.eps"> -<IMG SRC="mappings.gif"> -</FIGURE> -<P> -<P>The <SF>merge-key</SF> is necessary to define the equality of -index entry keys. See command <CODE>merge-rule</CODE> for further details about -defining the merge mapping. -<P>The <SF>sort-key</SF> is necessary to define a total order on the -keywords. Since we need a scheme that is independent from any specific -character set such as ASCII or ISO-Latin, we must be able to define -completely new alphabets. The index entries are then sorted according -to the ISO-Latin alphabet. See the command <CODE>sort-rule</CODE> for an -explanation how these mapping can be specified. -<P>The <SF>print-key</SF> is used for the final markup and contains the -string that appears in the generated markup. -<P> -<P> -<DT><B>location-class-group</B><DD><P>There exist two kinds of -location class groups namely <SF>location-reference-groups</SF> and -<SF>cross-reference-groups</SF>. -<P> -<DT><B>location-reference-group</B><DD><P>consists of a list of -<SF>attribute-groups</SF>. -<P> -<P> -<DT><B>attribute-groups</B><DD><P>Each <SF>location-reference-group</SF> consists of -a list of <SF>attribute-groups</SF>. Attribute groups are defined by a set -of <SF>attributes</SF>. In the markup phase, all location references are -sorted according to the group number their attributes belong to. -Additionally all location references of a particular attribute group -appear together in the index. -<P>See command <CODE>define-attribute-groups</CODE> for further information about -the handling of attribute-groups. -<P>An attribute group consists of a list of <SF>location-references</SF> -and/or <SF>ranges</SF>. -<P> -<P> -<A NAME="def locref-class"></A> <DT><B>location-reference-class, location-reference, location</B><DD><P>Each -index entry of an index references at least one <SF>location</SF> in the -document. A <SF>location</SF> is a logical or physical part of a document, -such as a single page, a section or subsection, etc. The symbolic name -of a location is called a <SF>location-reference</SF>. The -location reference is always represented as a string (a sequence of -characters). Each location reference is associated a special tag -called <SF>attribute</SF>. The following examples may give you an idea how -location references could look like. -<P> -<BLOCKQUOTE> -<CODE>"25" </CODE> represents a page number. -</BLOCKQUOTE> -<P> -<BLOCKQUOTE> -<CODE>"Chapter-3"</CODE> represents the third chapter of a document. -</BLOCKQUOTE> -<P> -<BLOCKQUOTE> -<CODE>"A-I" </CODE> represents the first page, written in uppercase roman -numerals of the appendix `A', separated by a hyphen. -</BLOCKQUOTE> -<P> -<BLOCKQUOTE> -<CODE>"2.3.4" </CODE> represents the sub-sub-section 2.3.4 of a document. -</BLOCKQUOTE> -<P>As we can see, the location references are often composed -hierarchically of smaller entities, such as numbers or names. All -location references that belong to the same class form a -<SF>location-class</SF>. A location class is composed of <SF>alphabets</SF> -and <SF>separators</SF>. See command <CODE>define-location-class</CODE> for a -description how classes can be defined. -<P> -<P> -<DT><B>alphabet, separator</B><DD><P>As we have seen in the previous section, -location classes consist of alphabets and separators. xindy has the -following built-in set of basic alphabets: -<P> -<BLOCKQUOTE><CODE> -<PRE> -<tag/<tt/arabic-numbers// contains all non-negative numbers beginning -with zero: 0, 1, 2, .... - -<tag/<tt/roman-numerals-uppercase// the roman numerals I, II, III, -(IIII/IV), V, ... It recognizes the old and new roman numeral system. - -<tag/<tt/roman-numerals-lowercase// the same for the lowercase roman -numerals. - -<tag/<tt/ALPHA// the US-ASCII alphabet (uppercase letters). - -<tag/<tt/alpha// the US-ASCII alphabet (lowercase letters). - -<tag/<tt/digits// the digits 0, 1, 2, 3, 4, 5, 6, 7, 8 and 9 in this -order. -</PRE> -</CODE></BLOCKQUOTE> -<P>The user is free to define new alphabets as he wishes. See the -commands <CODE>define-alphabet</CODE> and <CODE>define-enumeration</CODE> for further -details. -<P>A complete location class can be defined by composing alphabets and -separators. The location class of the example <CODE>"A-I"</CODE> can be -defined as follows -<P> -<PRE> - (define-location-class "appendix" - (ALPHA "-" roman-numerals-uppercase)) -</PRE> -<P>This is a list that completely describes all possible instances of -this location class. Other valid members are <CODE>A-II</CODE>, <CODE>B-VI</CODE>, -etc. Location classes are defined with the command -<CODE>define-location-class</CODE>. -<P><SF>xindy</SF> reads the incoming strings representing location references -and tries to match them against a previously defined location class. -There exist no predefined location classes. -<P> -<DT><B>range</B><DD><P>A <SF>range</SF> is a pair of <SF>location-references</SF>. A -sequence of location references following one another is transformed -into an range if the length of the sequence exceeds a certain -user-definable limit. For example, the location references 11, 12, 13 -and 14 may be transformed into the range 11--14. See command -<CODE>define-location-class</CODE> for further details. -<P> -<P> -<DT><B>cross-reference-group</B><DD><P>Container for all -<SF>cross-references</SF> of a particular <SF>cross-reference-class</SF>. -<P> -<P> -<A NAME="def crossref-class"></A> <DT><B>cross-reference-class, cross-reference</B><DD><P>A <SF>cross-reference</SF> is -an unstructured reference. <SF>Cross-reference-classes</SF> are used to -define different classes of cross references. All elements of a -cross reference class appear together in the index. A cross reference -consists of a list of strings. -<P> -<P> -<DT><B>attributes</B><DD><P>Each location reference contains a so-called -<SF>attribute</SF>. Attributes may be used to give a location reference a -different meaning that may influence the processing and markup of this -reference. Sometimes location references pointing to semantically -different locations such as a definition or a usage of a term are -tagged differently. They often appear in <EM>italics</EM> or <B>boldface</B> -indicating this difference. An attribute may now be used to express -this difference. Since <SF>xindy</SF> needs to know the possible -attributes before the index entries are read in, the command -<CODE>define-attributes</CODE> must be used to define a set of attributes and -how they interact. -<P> -</DL> -<P> -<P> -<P> -<P> -<HR> -<A HREF="manual-3.html">Next</A> -<A HREF="manual-1.html">Previous</A> -<A HREF="manual.html#toc2">Contents</A> -</BODY> -</HTML> |