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
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
<TITLE>XINDY Style File Tutorial: Advanced Features</TITLE>
<LINK HREF="style-tutorial-4.html" REL=next>
<LINK HREF="style-tutorial-2.html" REL=previous>
<LINK HREF="style-tutorial.html#toc3" REL=contents>
</HEAD>
<BODY>
<A HREF="style-tutorial-4.html">Next</A>
<A HREF="style-tutorial-2.html">Previous</A>
<A HREF="style-tutorial.html#toc3">Contents</A>
<HR>
<H2><A NAME="s3">3. Advanced Features</A></H2>
<P>In the following sections you'll learn more about the features of
<SF>xindy</SF>. We'll show you how you can define your own
location classes, specify the letter groups in more detail and bring
you close to more specfic markup features. After reading this chapter
you should be able to master about 95% of the commonly used indexes.
<P>
<P>
<H2><A NAME="ss3.1">3.1 Location Classes</A>
</H2>
<P>We continue using a more complex index. Copy the current style to a
new file (now <CODE>style2.xdy</CODE>) and run <SF>xindy</SF> on the raw index
<CODE>ex2.raw</CODE> by typing:
<P>
<BLOCKQUOTE><CODE>
<PRE>
eg$ cp style1.xdy style2.xdy
eg$ xindy -t ex2.xlg -M style2 -I xindy ex2.raw
</PRE>
</CODE></BLOCKQUOTE>
<P>You should see some error messages indicating that something is
unknown to <SF>xindy</SF>. What has happend? The messages should be
similar to the following snapshot:
<P>
<BLOCKQUOTE><CODE>
<PRE>
...
WARNING:
location-reference "B-5" did not match any location-class! (ignored)
WARNING:
location-reference "C-8" did not match any location-class! (ignored)
WARNING:
location-reference "iv" did not match any location-class! (ignored)
WARNING:
location-reference "ii" did not match any location-class! (ignored)
...
</PRE>
</CODE></BLOCKQUOTE>
<P>The index contains new, and therefore unknown, location classes. The
first one has an appendix-like style, whereas the second one seems to
be lowercase roman numerals. <SF>xindy</SF> reported, that it doesn't know
these locations and therefore knows nothing about their internal
structure. We make them known to the system by adding the following
commands to the style file.
<P>
<BLOCKQUOTE><CODE>
<PRE>
(define-location-class "roman-pages" ("roman-numerals-lowercase"))
(define-location-class "appendices" ("ALPHA" :sep "-" "arabic-numbers"))
(define-location-class-order ("roman-pages" "appendices"))
</PRE>
</CODE></BLOCKQUOTE>
<P>The first command tells <SF>xindy</SF> that there exist some page numbers
that are written with roman lowercase letters. The second one defines
the structure of the appendix locations. They consist of three
elements, a capital letter, a separator---which is a hyphen in our
case---and finally an arabic number. To be able to correctly
distinguish separator strings from the names of the known
<EM>basetypes</EM>, the argument <CODE>:sep</CODE> indicates, that the following
is a separator. The last command simply says that the locations which
are roman numerals shall appear before the appendix locations. So far
we know three different basetypes. The built-in basetypes of
<SF>xindy</SF> are:
<P>
<DL>
<DT><B><CODE>arabic-numbers</CODE></B><DD><P>contains all non-negative numbers beginning
with zero: 0, 1, 2, ....
<P>
<DT><B><CODE>roman-numerals-uppercase</CODE>, <CODE>roman-numerals-lowercase</CODE></B><DD><P>the
roman numerals I, II, III, (IIII/IV), V, ... It contains the old and
new roman numeral system. Two versions for uppercase and lowercase
letters are supported.
<P>
<DT><B><CODE>ALPHA</CODE>, <CODE>alpha</CODE></B><DD><P>The US-ASCII alphabet letters (uppercase
and lowercase letters).
<P>
<DT><B><CODE>digits</CODE></B><DD><P>the digits 0, 1, 2, 3, 4, 5, 6, 7, 8 and 9 in this
order.
</DL>
<P>`Fine,', you'll say, `but what if my basetypes are completely
different?' You're right! But <SF>xindy</SF> offers you to define your own
alphabets. For example, you can define a new alphabet by writing
<P>
<BLOCKQUOTE><CODE>
<PRE>
(define-alphabet "my-personal-alphabet" ("Hi" "ho" "here" "I" "go"))
</PRE>
</CODE></BLOCKQUOTE>
<P>This is a valid alphabet that consists of 5 <EM>letters</EM>. You can now
define a location class
<P>
<BLOCKQUOTE><CODE>
<PRE>
(define-location-class "my-personal-class"
("my-personal-alphabet" :sep "-" "arabic-numbers"))
</PRE>
</CODE></BLOCKQUOTE>
<P>to match all of the following locations: <EM>Hi-12, ho-2, here-709,
I-9, go-42</EM>. <SF>xindy</SF> will recognize them and be able to sort them
according to your specification which says that <EM>Hi</EM> comes before
all others and <EM>here</EM> is exactly at the third position. So they
will be sorted lexicographically, layer by layer, until it can decide
which one is before or after the other. We have prepared a concrete
example. Do you remember the example we gave when we spoke about
indexing bible verses? This exactly matches the situation of such a
self-defined alphabet which could look like the following definitions:
<P>
<BLOCKQUOTE><CODE>
<PRE>
(define-alphabet "bible-chapters"
("Genesis" "Exodus" "Leviticus" "Numbers" "Deuteronomy"
... ))
(define-location-class "bible-verses"
("bible-chapters" :sep " " "arabic-numbers" :sep "," "arabic-numbers"))
</PRE>
</CODE></BLOCKQUOTE>
<P>This description would match locations like <EM>Genesis 1,3</EM>,
<EM>Exodus 7,8</EM>, etc.
<P>Now run LaTeX on <CODE>ex2.tex</CODE> and view the results. It looks a
little bit strange since <SF>xindy</SF> has automatically built ranges of
successive locations. The first locations of the index entry <EM>roman</EM>
actually denote the range <EM>ii</EM> until <EM>iv</EM>. <EM>Ranges</EM> consist
of location references. To typeset them correctly you can specify
<P>
<BLOCKQUOTE><CODE>
<PRE>
(markup-range :sep "--")
</PRE>
</CODE></BLOCKQUOTE>
<P>This indicates that location reference forming a range shall be
separated by a hyphen. Running <SF>xindy</SF> and LaTeX again gives a
better idea of how it should look like. Here is a part of the
generated output.
<P>
<BLOCKQUOTE><CODE>
<PRE>
...
\item appendices\quad{}A-1, A-7, A-11, B-3--B-5, C-1, C-8, C-12,
C-13, C-22, D-2, D-3, D-5, D-10
...
</PRE>
</CODE></BLOCKQUOTE>
<P>
<H2><A NAME="ss3.2">3.2 Hierarchical Location Classes</A>
</H2>
<P>Somehow a lot of space is wasted when looking at the first index entry.
Modify the definition of the location class for appendices as follows
and add the other commands as well:
<P>
<BLOCKQUOTE><CODE>
<PRE>
(define-location-class "appendices"
("ALPHA" :sep "-" "arabic-numbers")
:hierdepth 2)
(markup-locref-list :sep "; " :depth 0 :class "appendices")
(markup-locref-list :open "~~" :sep ", " :depth 1 :class "appendices")
</PRE>
</CODE></BLOCKQUOTE>
<P><EM>Note: Since the tilde character serves as our quoting character it
must be quoted itself in the above example.</EM> Run <SF>xindy</SF> and view
the output stored in <CODE>ex2.ind</CODE>. The output looks similar to the
following:
<P>
<BLOCKQUOTE><CODE>
<PRE>
...
\item appendices\quad{}A~1, 7, 11; B~3--5; C~1, 8, 12, 13, 22;
D~2, 3, 5, 10
...
</PRE>
</CODE></BLOCKQUOTE>
<P>You can see that the location references of this class have been
transformed into a hierarchical structure caused by the
<CODE>:hierdepth</CODE> argument. Additionally we have specified markup for
the layers of this class separately for the depths 0 and 1. The
locations at depth 0 are separated by a `;' whereas the ones at depth
1 are separated by a `,'.
<P>Maybe you get an impression why we named <SF>xindy</SF> a <EM>flexible</EM>
system.
<P>
<H2><A NAME="ss3.3">3.3 More about Letter Groups</A>
</H2>
<P>More problems arise when using languages with different letter
schemes. Hungarian is an example. In Hungarian indexes the words
beginning with the letters <EM>Cs, Ly, Ny</EM> and more are printed in a
separate block. The words beginning with <EM>Ly</EM>, for example, appear
behind the words beginning with an <EM>L</EM>. <SF>xindy</SF> allows to define
this kind of letter groups as well. Add the following lines to the
style file.
<P>
<BLOCKQUOTE><CODE>
<PRE>
(define-letter-group "ly" :after "l" :before "m")
(define-letter-group "ny" :after "n" :before "o")
(markup-letter-group :open-head "~n {\bf " :close-head "}"
:capitalize)
</PRE>
</CODE></BLOCKQUOTE>
<P>The result looks like the following:
<P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
...
{\bf Ly}
\item lyuk\quad{}1
\item lyukas\quad{}2
\indexspace
{\bf M}
\item maga\quad{}1
\item magyar\quad{}2
\indexspace
{\bf N}
\item nagy\quad{}1
\item nagyon\quad{}9
\item ngy\quad{}4
\indexspace
{\bf Ny}
\item nyelv\quad{}1
\item nyolc\quad{}8
...
</PRE>
</CODE></BLOCKQUOTE>
<P>The result describes what the purpose of the above commands is. It
becomes prettier from step to step, doesn't it?
<P>You have now learned most of the features of <SF>xindy</SF>. Go playing
around a little bit. For a detailed description of all commands and
all their arguments and switches you should reference the manual that
comes with this distribution.
<P>
<P>
<P>
<HR>
<A HREF="style-tutorial-4.html">Next</A>
<A HREF="style-tutorial-2.html">Previous</A>
<A HREF="style-tutorial.html#toc3">Contents</A>
</BODY>
</HTML>
|
