summaryrefslogtreecommitdiff
path: root/Build/source/utils/xindy/xindy-src/doc/manual-4.html
blob: 6d39d7ba240f864131ed74984e14c009addf75a8 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
 <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
 <TITLE>xindy Manual: Processing Phases</TITLE>
 <LINK HREF="manual-5.html" REL=next>
 <LINK HREF="manual-3.html" REL=previous>
 <LINK HREF="manual.html#toc4" REL=contents>
</HEAD>
<BODY>
<A HREF="manual-5.html">Next</A>
<A HREF="manual-3.html">Previous</A>
<A HREF="manual.html#toc4">Contents</A>
<HR>
<H2><A NAME="startup-phase"></A> <A NAME="s4">4. Processing Phases</A></H2>

<H2><A NAME="ss4.1">4.1 The Startup Phase</A>
</H2>

<P>After the system is started, <SF>xindy</SF> reads in the index style that
is passed as a command line argument. Each <CODE>require</CODE> command is
executed and the internal data structures representing the index style
are built up. The index style must completely be read in before the
raw index can be read.
<P>
<P>
<A NAME="processing-phase"></A> <H2><A NAME="ss4.2">4.2 The Processing Phase</A>
</H2>

<P>The processing phase starts with reading the complete raw index. The
name of the raw index file must be passed via the command line. All
index entries are read in and pre-processed. All attributes and
cross reference classes are checked if they are already known to the
system. All strings representing location references are matched
against all known location classes. Appropriate warnings are issued,
if errors are encountered.
<P>After the raw index has completely been read in, the
location references of each index entry are merged, separated and
sorted and the building of ranges takes place. This phase is the most
complex one and we will describe it in detail.
<P>
<OL>
<LI> All location references are separated according to the class
they belong to. These groups are called <EM>location class groups</EM>.
Possible groups are all defined location  and crossref classes. See
the commands <CODE>define-location-class</CODE> and
<CODE>define-crossref-class</CODE> for a description how these classes can
be defined.

The classes are sorted according to an order that can be defined with
the command <CODE>define-location-class-order</CODE>.
</LI>
<LI> The further processing of each location class group is
different for the location classes and the crossref classes.

<UL>
<LI> Cross references are sorted lexicographically based on
the ISO-Latin alphabet.

<A NAME="sort-merge-locrefs"></A> </LI>
<LI> To illustrate the processing of location references we assume
the following list:

<BLOCKQUOTE>
 <EM>13</EM>, <EM>14</EM>, <EM>15</EM>, <EM>18</EM>, <B>12</B>, <B>13</B>,
<B>14</B>, <B>16</B>, 14, 16 
</BLOCKQUOTE>


The location references in italics own the attribute `important,
those with in boldface have attribute `definition', and all others
are own the attribute `default'. Imagine, the attribute groups were
defined with the commands

<BLOCKQUOTE><CODE>
<PRE>
   (define-attribute-groups (("definition" "important")
                             ("default")))

   (merge-to "definition" "default" :drop)
   
</PRE>
</CODE></BLOCKQUOTE>


See commands <CODE>define-attributes</CODE> and <CODE>merge-to</CODE> for a
detailed description.

The substitution rules are applied. This means that
location references <B>13</B> and <B>14</B> with attribute `important'
are <EM>substituted</EM> by the location references <EM>13</EM> and <EM>14</EM>
with attribute `definition'. Substitution means removing from the
list of location references.

Substitution occurs because the definition of the attribute groups
implicitly defines <CODE>"definition"</CODE> <EM>substitutes</EM>
<CODE>"important"</CODE>.

The resulting list is now

<BLOCKQUOTE>
 <EM>13</EM>, <EM>14</EM>, <EM>15</EM>, <EM>18</EM>, <B>12</B>, <B>16</B>, 14,
16 
</BLOCKQUOTE>


<A NAME="def merge-to"></A>  The <CODE>merge-to</CODE> rules are applied.
Their meaning is to make location references appear with another
attribute as well, but only in the function of supporting the
building of ranges. They disappear after the ranges are built. The
location references that cause new location refererences to be
added are called <EM>parents</EM>, whereas the new ones are called
<EM>childs</EM>. The example rule results in the adding of all
refernces with attribute `definition' to the attribute `default'
which results in the list

<BLOCKQUOTE>
 <EM>13</EM>, <EM>14</EM>, <EM>15</EM>, <EM>18</EM>, <B>12</B>, <B>16</B>, (13),
14, (15), 16, (18) 
</BLOCKQUOTE>


The childs are put in parenthesis since they may only be used to
build up ranges.

For each attribute we now try to build ranges. Since the switch
<CODE>:drop</CODE> was specified we must start with the attribute
`default', because a successful merging of location references may
result in dropping the parents. This results in the range `13--16'.
The childs
(13) and (15) were used in the building of ranges, so their parents
<EM>13</EM> and <EM>15</EM> have to be removed from the list of
location references. This step would be omitted if the switch
<CODE>:drop</CODE> were not specified. After unsucessfully trying to build
more ranges and dropping the location references <EM>13</EM>, <EM>15</EM>
and (18)--which was only meant to build ranges--we obtain the list

<BLOCKQUOTE>
<EM>14</EM>, <EM>18</EM>, <B>12</B>, <B>16</B>, 13--16
</BLOCKQUOTE>


Finally the attributes are brought into the right order. In our
example the location references of the first attribute group are
merged and sorted lexicographically resulting in two attribute groups

<BLOCKQUOTE>
(<B>12</B>, <EM>14</EM>, <B>16</B>, <EM>18</EM>) (13--16)
</BLOCKQUOTE>























































</LI>
</UL>

</LI>
</OL>
<P>After all index entries have been processed the letter groups are
formed and the index entries and location references are transformed
into tree like structures as defined in the index style.
<P>
<P>
<P>
<A NAME="markup-phase"></A> <H2><A NAME="ss4.3">4.3 The Markup Phase</A>
</H2>

<P>After the index has completely been processed, the markup phase
traverses the tree-like structure of the index. Each step triggers the
appropriate markup events resulting in the emitting of markup tags.
<P>
<P>
<P>
<HR>
<A HREF="manual-5.html">Next</A>
<A HREF="manual-3.html">Previous</A>
<A HREF="manual.html#toc4">Contents</A>
</BODY>
</HTML>