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
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
|
<?xml version='1.0' encoding='ISO-8859-1'?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[
<!ENTITY % tex-refs-ent SYSTEM "tex-refs.ent" >
%tex-refs-ent;
]>
<!-- $Id: tex-refs-chapter-xindy.xml 139 2004-08-26 16:58:10Z mw $ -->
<chapter id="xindy" lang="en">
<title id="xindy-title">&xindy;</title>
<indexterm><primary>&xindy;</primary></indexterm>
<note><para>The content of this section was taken from the original
documentation of &xindy; V2.1
(<filename>Doc/manual*.html</filename>).
</para></note>
<para><emphasis>xindy</emphasis> means
fle<emphasis>x</emphasis>ible <emphasis>ind</emphasis>exing
s<emphasis>y</emphasis>stem.
It is an indexing system that can be used to generate
book-like indexes for arbitrary document
preparation systems. This term includes systems such as
&tex; and &latex;, the Nroff-family or SGML-based systems
(e.g. HTML) that process some kind of text and generate
indexing information. It is not fixed to any specific system,
but can be configured for a wide variety of purposes.
</para>
<section id="xindy-command-list">
<title>Command List</title>
<indexterm>
<primary>&xindy;</primary>
<secondary>Command List</secondary>
</indexterm>
<para>Here is the complete list of xindy's commands that may
be used in the index style. The symbol <literal>name</literal>
always refers to a string. We separate the commands into
the processing and markup commands. The commands are listed
in alphabetical order.
</para>
<para>The parenthesis <literal>[</literal> and
<literal>]</literal> denote optional parts of the syntax
and <literal>{</literal> and <literal>}</literal> denote
the grouping of elements. A vertical bar indicates
alternatives. However, the enclosing round braces
<emphasis>are</emphasis> part of the syntax and
must be supplied.
</para>
<section id="xindy-command-list-processing">
<title>Processing Commands</title>
<indexterm>
<primary>&xindy;</primary>
<secondary>Processing Commands</secondary>
</indexterm>
<section id="xindy-command-list-processing-define-alphabet">
<title><literal>define-alphabet</literal></title>
<indexterm>
<primary>&xindy;</primary>
<secondary>Processing Commands</secondary>
<tertiary>define-alphabet</tertiary>
</indexterm>
<para><programlisting>(define-alphabet name string-list)</programlisting></para>
<para>Defines <literal>name</literal> to be the alphabet
consisting of all elements of the
<literal>string-list</literal>.
Examples:
<programlisting>(define-alphabet "example-alphabet" ("An" "Example" "Alphabet"))</programlisting>
defines an alphabet consisting of exactly three symbols.
For the successor relationship holds:
<literal>succ("An")="Example"</literal> and
<literal>succ("Example")="Alphabet"</literal>. The built-in
alphabet <literal>digits</literal> is defined as follows:
<programlisting>(define-alphabet "digits"
("0" "1" "2" "3" "4" "5" "6" "7" "8" "9"))</programlisting>
</para>
</section>
<section id="xindy-command-list-processing-define-attributes">
<title><literal>define-attributes</literal></title>
<indexterm>
<primary>&xindy;</primary>
<secondary>Processing Commands</secondary>
<tertiary>define-attributes</tertiary>
</indexterm>
<para><programlisting>(define-attributes attribute-list)</programlisting></para>
<para>Defines all attributes the raw index may contain.
Parameter <literal>attribute-list</literal> is a list of
list of strings. The nesting level must not be more than 2.
So <literal>(..(..)..)</literal> is allowed, whereas
<literal>(..(..(..)..)..)</literal> is not.
</para>
<para>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
<literal>("definition")</literal> and
<literal>( ("definition") )</literal> are equivalent.
All elements forming a list are a so-called
<emphasis>attribute group</emphasis>. The members of a group
are written to the output file before any member of the
following groups are written.
</para>
<para>Examples of valid attributes lists are:</para>
<para><literal>("definition" "usage")</literal> defines two
attribute groups. The first one contains all references
with the attribute <literal>definition</literal> and the
second one all with the attribute <literal>usage</literal>.
</para>
<para><literal>(("definition" "important") "usage")</literal>
defines two attribute groups. The first one contains all
references with the attributes <literal>definition</literal>
or <literal>important</literal> and the second one all with
the attribute <literal>usage</literal>. In the attribute
group <literal>("definition" "important")</literal> the
attribute <literal>definition</literal> overrides
<literal>important</literal>.
</para>
</section>
<section id="xindy-command-list-processing-define-crossref-class">
<title><literal>define-crossref-class</literal></title>
<indexterm>
<primary>&xindy;</primary>
<secondary>Processing Commands</secondary>
<tertiary>define-crossref-class</tertiary>
</indexterm>
<para><programlisting>(define-crossref-class name [:unverified])</programlisting></para>
<para>Defines <literal>name</literal> to be a class of
cross references. We distinguish two types of cross
reference classes. <emphasis>Verified</emphasis> 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 <literal>:unverified</literal> can
be used to suppress this behaviour.
</para>
</section>
<section id="xindy-command-list-processing-define-letter-group">
<title><literal>define-letter-group</literal></title>
<indexterm>
<primary>&xindy;</primary>
<secondary>Processing Commands</secondary>
<tertiary>define-letter-group</tertiary>
</indexterm>
<para><programlisting>(define-letter-group name [:before lgname] [:after lgname]
[:prefixes list-of-prefixes])</programlisting></para>
<para><programlisting>(define-letter-groups list-of-letter-groups)</programlisting></para>
<para>This command defines a letter group with name
<literal>name</literal>, which must be a string value,
grouping all index entries that have a
<emphasis>sort key</emphasis> beginning with the prefix
<literal>name</literal>. The command
<programlisting>(define-letter-group "a")</programlisting>
is equivalent to the command
<programlisting>(define-letter-group "a" :prefixes ("a"))</programlisting>
</para>
<para>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.
</para>
<para>Example:
<programlisting>(define-letter-group "a")</programlisting>
defines a letter group containing all index entries
beginning with the string <literal>"a"</literal>.
</para>
<para><programlisting>(define-letter-group "c" :after "a")</programlisting>
defines a letter group containing all index entries beginning
with the string <literal>"c"</literal>. The letter group
appears behind the letter group <literal>"a"</literal>
</para>
<para><programlisting>(define-letter-group "b" :after "a" :before "c")</programlisting>
inserts letter group <literal>"b"</literal> between letter
group <literal>"a"</literal> and <literal>"c"</literal>.
This allows incremental definition of letter groups by
extending already defined ones.
</para>
<para>The arguments <literal>:after</literal> and
<literal>:before</literal> define a partial order on the
letter groups. &xindy; 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.
</para>
<para>The command <literal>define-letter-groups</literal>
(with an `s' at the end) is simply an abbreviation for
a sequence of <literal>define-letter-group</literal>
definitions where the elements are ordered in the
ordering given by the list. Example:
<programlisting>(define-letter-groups ("a" "b" "c")</programlisting>
equals the definitions
<programlisting>(define-letter-group "a")
(define-letter-group "b" :after "a")
(define-letter-group "c" :after "b")</programlisting>
</para>
<para>See also commands
<literal>markup-letter-group-list</literal>
and <literal>markup-letter-group</literal> for further
information.
</para>
</section>
<section id="xindy-command-list-processing-define-location-class">
<title><literal>define-location-class</literal></title>
<indexterm>
<primary>&xindy;</primary>
<secondary>Processing Commands</secondary>
<tertiary>define-location-class</tertiary>
</indexterm>
<programlisting>(define-location-class name layer-list
[:min-range-length num]
[:hierdepth depth]
[:var])</programlisting>
<para>Defines <literal>name</literal> 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 <literal>:sep</literal>. If the keyword
<literal>:min-range-length</literal> is specified we
define the <emphasis>minimum range length</emphasis>
to be used when building ranges. The argument
<literal>num</literal> must be a positive integer number
or the keyword <literal>none</literal> in which case
the building of ranges is disallowed. If the switch
<literal>:var</literal> is specified the declared class
is of type <emphasis>variable</emphasis>, i.e. it is a
<emphasis>var-location-class</emphasis>. Since building
of ranges is currently only allowed for standard classes
<literal>:var</literal> and
<literal>:min-range-length</literal>
must not be used together. The keyword argument
<literal>:hierdepth</literal> can be used to declare that
the location references have to be tagged in a
hierarchical form. Its argument <literal>depth</literal>
must be an integer number indicating the number of layers
the hierarchy does contain. See command
<literal>markup-locref-list</literal> for more information.
Examples:
<programlisting>(define-location-class "page-numbers" ("arabic-numbers")
:minimum-range-length 3)</programlisting>
Defines the location class <literal>page-numbers</literal>
consisting of one layer which is the alphabet
<literal>arabic-numbers</literal>. 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
<literal>0, 1, ... 2313</literal>, etc.
<programlisting>(define-location-class "sections" :var
("arabic-numbers" :sep "."
"arabic-numbers" :sep "."
"arabic-numbers"))</programlisting>
defines a variable location class. Valid instances are
<literal>1, 1.1, 1.2, 2, 2.4.5</literal>, but none of
<literal>2-3</literal> (wrong separator),
<literal>1.2.3.4</literal> (more than 3 layers),
<literal>2.3.iv</literal> (roman number instead of arabic one).
</para>
</section>
<section id="xindy-command-list-processing-define-location-class-order">
<title><literal>define-location-class-order</literal></title>
<indexterm>
<primary>&xindy;</primary>
<secondary>Processing Commands</secondary>
<tertiary>define-location-class-order</tertiary>
</indexterm>
<para><programlisting>(define-location-class-order list)</programlisting></para>
<para>Defines the order in which the location classes are
written to the output file. The parameter
<literal>list</literal> is a list of names of location
classes. Examples:
<programlisting>(define-location-class-order
("page-numbers" "sections" "xrefs"))</programlisting>
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.
</para>
</section>
<section id="xindy-command-list-processing-define-rule-set">
<title><literal>define-rule-set</literal></title>
<indexterm>
<primary>&xindy;</primary>
<secondary>Processing Commands</secondary>
<tertiary>define-rule-set</tertiary>
</indexterm>
<para><programlisting>(define-rule-set name
[ :inherit-from ("rule-set" "rule-set-2") ]
:rules (<rule>...) )</programlisting></para>
<para>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 <literal>sort-rule</literal>. They do not add new
functionality that is not already present with
<literal>sort-rule</literal>.
</para>
<para>A rule can be of the form:
<programlisting><rule> ::= ("pattern" "replacement"
[:string|:bregexp|:egegexp] [:again])</programlisting>
</para>
<para>The following incomplete example defines a new rule
set of name <literal>isolatin1-tolower</literal> that
inherits definitions from rule set
<literal>latin-tolower</literal>, overriding or adding
the sort rules in the list of <literal>:rules</literal>.
<programlisting>(define-rule-set "isolatin1-tolower"
:inherit-from ("latin-tolower")
:rules (("?" "?" :string :again)
("?" "?" :string :again)
("?" "?" :string :again)
("?" "?" :string :again)
("?" "?" :string :again)
("?" "?" :string :again)
("?" "?" :string :again)
...
)
...)</programlisting>
Rule sets can be instantiated with the command
<literal>use-rule-set</literal>. For further descriptions
on the sorting model refer to the command
<literal>sort-rule</literal>.
</para>
</section>
<section id="xindy-command-list-processing-define-sort-rule-orientations">
<title><literal>define-sort-rule-orientations</literal></title>
<indexterm>
<primary>&xindy;</primary>
<secondary>Processing Commands</secondary>
<tertiary>define-sort-rule-orientations</tertiary>
</indexterm>
<para><programlisting>(define-sort-rule-orientations (orientations...))</programlisting></para>
<para>Defines the order for the different sorting phases.
The currently implemented <emphasis>orientations</emphasis>
are <literal>forward</literal> and
<literal>backward</literal>.
This command must precede all <literal>sort-rule</literal>
commands in an index style. It defines the orientations
and implicitly sets the maximum number of sorting
phases performed.
</para>
<para>For further descriptions on the sorting model refer
to the command <literal>sort-rule</literal>.
</para>
</section>
<section id="xindy-command-list-processing-merge-rule">
<title><literal>merge-rule</literal></title>
<indexterm>
<primary>&xindy;</primary>
<secondary>Processing Commands</secondary>
<tertiary>merge-rule</tertiary>
</indexterm>
<para><programlisting>(merge-rule pattern replacement [:again]
[:bregexp | :eregexp | :string])</programlisting></para>
<para>Defines a keyword mapping rule that can be used to
generate the <emphasis>merge key</emphasis> from the
<emphasis>main key</emphasis> 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.
</para>
<para>The parameter <literal>pattern</literal> 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
<emphasis>basic regular expressions</emphasis> (BREs) or
<emphasis>extended regular expressions</emphasis> (EREs).
You can use the switch <literal>:bregexp</literal> to
force the interpretation of the pattern as a BRE, or
<literal>:eregexp</literal> to interpret it as an ERE.
If you want xindy to interpret the pattern literally, use
the switch <literal>:string</literal>. If none of these
switches is selected, xindy 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.
</para>
<para>The parameter <literal>replacement</literal> must be
a string possibly containing the special characters
<literal>&</literal> (substitutes for the complete
match) and <literal>\1 ,..., \9</literal> (substituting
for the <emphasis>n</emphasis>-th submatch. Examples:
<programlisting>(merge-rule "A" "a")</programlisting>
replaces each occurrence of the uppercase letter
<literal>`A'</literal> with its lowercase counterpart.
<programlisting>(merge-rule "\~"([AEOUaeou])" "\1")</programlisting>
transforms the &tex; umlaut-letters into their stripped
counterparts, such that <literal>`\"A '</literal> is
treated as an <literal>`A'</literal> afterwards.
</para>
<para>The following sequences have a special meaning:
<variablelist role="db2latex:compact">
<varlistentry>
<term><literal>` ~n '</literal></term>
<listitem>
<para>End of line symbol
(<emphasis>linefeed</emphasis>).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>` ~b '</literal></term>
<listitem>
<para>The ISO-Latin character with the lowest
ordinal number.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>` ~e ' </literal></term>
<listitem>
<para>The ISO-Latin character with the highest ordinal
number.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>` ~~ ' </literal></term>
<listitem>
<para>The tilde character.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>` ~" '</literal></term>
<listitem>
<para>The double quote character.</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>Tilde characters and double quotes have to be quoted
themselves with a tilde character. The special characters
<literal>` ~b '</literal> and <literal>` ~e '</literal>
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.
<literal>` m~e '</literal> is lexicographically placed
between <literal>`m'</literal> and <literal>`n'</literal>.
</para>
<para>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
<programlisting>(merge-rule "[A-Z]" "&")</programlisting>
it is more efficient (though less comfortable) to use
<programlisting>(merge-rule "A" "Ax")
(merge-rule "B" "Bx")
...
(merge-rule "Z" "Zx")</programlisting>
</para>
<para>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
<literal>`alpha'</literal> is checked before
<literal>`.*'</literal>, but <literal>`auto'</literal> and
<literal>`a.*'</literal> are checked in order of their
definition.
</para>
<para>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.
</para>
<para>Sometimes it is necessary to apply rules anew to the
result of a transformation. By specifying the keyword
argument <literal>:again</literal> in the merge rule the
rule is marked as mutable, which means that after using
this rule the transformation process shall restart
at the same place. E.g. the rule
<programlisting>(merge-rule "\$(.*)\$" "\1" :again)</programlisting>
deletes <emphasis>all</emphasis> surrounding
<literal>`$ '</literal> symbols from the input.
</para>
<para>See also command <literal>sort-rule</literal>.</para>
</section>
<section id="xindy-command-list-processing-merge-to">
<title><literal>merge-to</literal></title>
<indexterm>
<primary>&xindy;</primary>
<secondary>Processing Commands</secondary>
<tertiary>merge-to</tertiary>
</indexterm>
<para><programlisting>(merge-to attr-from attr-to [:drop])</programlisting></para>
<para>A merge rule says that the attribute
<literal>attr-from</literal> can be used to build ranges in
<literal>attr-to</literal>. Both attributes must name valid
attribute names. The switch <literal>:drop</literal>
indicates, that the original location reference with
attribute <literal>attr-from</literal> has to be dropped
(removed), if a successful range was built with location
references in attribute <literal>attr-to</literal>.
A detailed description is given in the section about
processing phases.
</para>
</section>
<section id="xindy-command-list-processing-require">
<title><literal>require</literal></title>
<indexterm>
<primary>&xindy;</primary>
<secondary>Processing Commands</secondary>
<tertiary>require</tertiary>
</indexterm>
<para><programlisting>(require filename)</programlisting></para>
<para>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
<literal>filename</literal> 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:
<programlisting>(require "french/alphabet.xdy")
(require "french/sort-rules.xdy")
(require "tex/locations.xdy")
(require "tex/markup.xdy")</programlisting>
Submodules can load other submodules as well. If a file is
required that was already loaded, the
<literal>require</literal> command is simply ignored and
processing continues without including this file twice.
See also command searchpath.
</para>
</section>
<section id="xindy-command-list-processing-searchpath">
<title><literal>searchpath</literal></title>
<indexterm>
<primary>&xindy;</primary>
<secondary>Processing Commands</secondary>
<tertiary>searchpath</tertiary>
</indexterm>
<para><programlisting>(searchpath {path-string | path-list})</programlisting></para>
<para>This command adds the given paths to the list of paths,
xindy searches for index style files. The argument
<literal>path-string</literal> 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:
<programlisting>(searchpath ".:/usr/local/lib/xindy:/usr/local/lib/xindy/english:")</programlisting>
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
<programlisting>(searchpath ("."
"/usr/local/lib/xindy"
"/usr/local/lib/xindy/english"
:default))</programlisting>
yields exactly the same result as the example above. Here
<literal>path-list</literal> must be a list of strings and/or
the keyword(s) <literal>:default</literal> and
<literal>:last</literal>. The keyword
<literal>:default</literal> signifies that the default pathnames
are to be inserted at the specified position in the list.
The keyword <literal>:last</literal> 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.
</para>
</section>
<section id="xindy-command-list-processing-sort-rule">
<title><literal>sort-rule</literal></title>
<indexterm>
<primary>&xindy;</primary>
<secondary>Processing Commands</secondary>
<tertiary>sort-rule</tertiary>
</indexterm>
<para><programlisting>(sort-rule pattern replacement [:run level] [:again])</programlisting></para>
<para>Defines a keyword mapping rule that can be used to
generate the <emphasis>sort key</emphasis> of an index entry
from the <emphasis>merge key</emphasis>. This key is used
to sort the index entries lexicographically after they
have been merged using the merge key.
</para>
<para>The argument <literal>:run</literal> indicates that this
rule is only in effect a the specified
<emphasis>level</emphasis> (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 (<literal>new-sort-rules</literal>) that
comes with this distribution.
</para>
<para>See command <literal>merge-rule</literal> for more
information about keyword rules.
</para>
</section>
<section id="xindy-command-list-processing-use-rule-set">
<title><literal>use-rule-set</literal></title>
<indexterm>
<primary>&xindy;</primary>
<secondary>Processing Commands</secondary>
<tertiary>use-rule-set</tertiary>
</indexterm>
<para><programlisting>(use-rule-set [:run phase]
[:rule-set ( <rule-set>... ))</programlisting>
</para>
<para>This command instantiates the gives rule sets to be
in effect at sorting phase <literal>phase</literal>.
The order of the rule sets given with argument
<literal>:rule-set</literal> 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.
</para>
<para>The following example declares that in phase 0 the
rule sets <literal>din5007</literal> and
<literal>isolatin1-tolower</literal> should be active,
whereas in phase 2 the other rule sets have to be applied.
<programlisting>(use-rule-set :run 0
:rule-set ("din5007" "isolatin1-tolower"))
(use-rule-set :run 1
:rule-set ("resolve-umlauts"
"resolve-sharp-s"
"isolatin1-tolower"
))</programlisting>
</para>
<para>For a discussion on rule sets refer to command
<literal>define-rule-set</literal>.
</para>
</section>
</section>
<section id="xindy-command-list-markup">
<title>Markup Commands</title>
<indexterm>
<primary>&xindy;</primary>
<secondary>Command List</secondary>
<tertiary>Markup Commands</tertiary>
</indexterm>
<para>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
<emphasis>environments</emphasis>, the syntax and naming
scheme of all commands follows a simple structure.
</para>
<para>The commands can be separated into
<emphasis>environment</emphasis> and
<emphasis>list-environment</emphasis> commands. All
commands of the first group support the keyword arguments
<literal>:open</literal> and <literal>:close</literal>,
whereas the second group additionally supports the keyword
argument <literal>:sep</literal>. If one of these keyword
arguments is missing, the default markup tag is always
the empty tag. The <literal>:open</literal> tag is always
printed before the object itself and the
<literal>:close</literal> tag is always printed after the
object has been printed. If a list is printed the
<literal>:sep</literal> 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
<literal>`-list'</literal> as part of their command name.
</para>
<para>Since the number of commands and the heavy usage of
<emphasis>default</emphasis> and
<emphasis>specialized</emphasis> tags makes the markup
somehow complex (but very powerful) we have added a
mechanism to trace the markup tags xindy omits during
its markup phase with the command
<literal>markup-trace</literal>.
</para>
<para>Here follows the list of markup commands in alphabetical
order with some of the commands grouped together.
</para>
<section>
<title><literal>markup-attribute-group-list</literal></title>
<para><programlisting>(markup-attribute-group-list [:open string] [:close string]
[:sep string])
(markup-attribute-group [:open string] [:close string]
[:group group-num])</programlisting>
</para>
<para>Location class groups consist of lists of attribute
groups. The markup of this list can be defined with the
command <literal>markup-attribute-group-list</literal>.
</para>
<para>To allow different markup for different attribute
groups the command <literal>markup-attribute-group</literal>
can be specialized on the group number with the keyword
argument <literal>:group</literal> which must be an integer
number. E.g., given are the groups
<literal>("definition" "theorem")</literal> and
<literal>("default")</literal> with group numbers 0 and 1,
then
<programlisting>(markup-attribute-group :open "<group0>" :close </group0>"
:group 0)
(markup-attribute-group :open "<group1>" :close "</group1>"
:group 1)</programlisting>
can be used to assign different markup for both groups
in a SGML-based language.
</para>
</section>
<section>
<title><literal>markup-crossref-list</literal></title>
<para><programlisting>(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])</programlisting>
</para>
<para>A crossref class group contains cross references of the
same class. The separator between the classes is defined with
the <literal>(markup-locclass-list :sep)</literal>-parameter.
A list of cross references can be tagged with the
<literal>command markup-crossref-list</literal> that
specializes on the <literal>:class</literal> argument.
</para>
<para>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
<literal>command markup-crossref-layer-list</literal>
can be used.
</para>
<para>Each layer of a cross reference can be assigned two tags
that specialize on the class of the reference, like all
other commands.
</para>
<para>A suitable markup for a cross reference class
<literal>see</literal> within &latex2e; could look like that:
<programlisting>(markup-crossref-list :class "see" :open "\emph{see} "
:sep "; ")
(markup-crossref-layer-list :class "see" :sep ",")
(markup-crossref-layer :class "see"
:open "\textbf{" :close "}")</programlisting>
An example output could look like
<literal>... see house; garden,winter; greenhouse</literal>
</para>
</section>
<section>
<title><literal>markup-index</literal></title>
<para><programlisting>(markup-index [:open string] [:close string]
[ :flat | :tree | :hierdepth depth ])</programlisting>
</para>
<para>Defines the markup tags that enclose the whole index
via the <literal>:open</literal> and
<literal>:close</literal> parameters. Examples:
<programlisting>(markup-index :open "Here comes the index~n"
:close "That's all folks!~n")</programlisting>
defines that the <literal>:open</literal> string is printed
before the rest of the index and the <literal>:close</literal>
string appears after the index is printed.
</para>
<para>Additionally one can specify the form of the generated
index. It is possible to produce flat indexes by specifying
the switch <literal>:flat</literal>, to generate a tree with
the <literal>:tree</literal> switch or any kind of mixture
between both by specifying the depth up to which trees shall
be built with the parameter <literal>:hierdepth</literal>.
Its argument depth is the number of layers that can be formed
into a tree. Therefore <literal>:flat</literal> is an
abbrevation of <literal>:hierdepth 0</literal> and
<literal>:tree</literal> is an abbrevation of
<literal>:hierdepth max-depth</literal>, with
<literal>max-depth</literal> being the maximum number of
layers a keyword has. An example: the keywords
<programlisting>("tree" "binary" "AVL")
("tree" "binary" "natural")</programlisting>
can be transformed in the following ways:
</para>
<para>A flat index (<literal>:flat</literal> or
<literal>:hierdepth 0</literal>)
<programlisting>tree binary AVL
tree binary natural</programlisting>
with <literal>:hierdepth 1</literal>
<programlisting>tree
binary AVL
binary natural</programlisting>
and a tree (<literal>:tree</literal> or
<literal>:hierdepth > 1</literal>)
<programlisting>tree
binary
AVL
natural</programlisting>
Most often one will create tree-like indexes or
ones that are flat.
</para>
</section>
<section>
<title><literal>markup-indexentry-list</literal></title>
<para><programlisting>(markup-indexentry-list [:open string] [:close string]
[:sep string] [:depth integer])
(markup-indexentry [:open string] [:close string]
[:depth integer])</programlisting>
</para>
<para>Letter groups consists of a list of index entries. The
command <literal>markup-indexentry-list</literal> defines
the markup of these lists. The markup can be specialized
on the depth if the index is hierarchically organized.
The command
<programlisting>(markup-indexentry-list :open "\begin{IdxentList}"
:close "\end{IdxentList}"
:sep "~n")</programlisting>
defines that the index entries of all layers are wrapped
into the given markup tags. If additionally
<programlisting>(markup-indexentry-list :open "\begin{IdxentListII}"
:close "\end{IdxentListII}"
:sep "~n"
:depth 2)</programlisting>
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.
</para>
<para>The command <literal>markup-indexentry</literal> 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 <literal>:depth</literal>
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.
</para>
<para><programlisting>(markup-indexentry :open "\begin{Indexentry}"
:close "\end{Indexentry}")</programlisting>
defines that the index entries of all layers are wrapped into
the given markup tags. If additionally
<programlisting>(markup-indexentry :open "\begin{IndexentryII}"
:close "\end{IndexentryII}"
:depth 2)</programlisting>
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.
</para>
</section>
<section>
<title><literal>markup-keyword-list</literal></title>
<para><programlisting>(markup-keyword-list [:open string] [:close string]
[:sep string] [:depth integer])
(markup-keyword [:open string] [:close string]
[:depth integer])</programlisting>
</para>
<para>The print key of an index entry consists of a list of
strings. The markup of this list can be defined with the
command <literal>markup-keyword-list</literal>. The keyword
argument <literal>:depth</literal> may be specified to
define the markup of the list at a particular depth.
</para>
<para>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
<literal>markup-keyword</literal>. Since we maybe need
different markup for different layers, the optional
keyword argument can be used to specialize this
markup for some depth.
</para>
</section>
<section>
<title><literal>markup-letter-group-list</literal></title>
<para><programlisting>(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])</programlisting>
</para>
<para>The first command defines the markup of the letter
group with name <literal>group-name</literal>. 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 <literal>:open-head</literal> and
<literal>:close-head</literal> is specified additional markup
is added as can be described as follows:
<programlisting><OPEN>
IF (:open-head OR :close-head)
<OPEN-HEAD>
transformer-of(<GROUP-NAME>)
<CLOSE-HEAD>
FI
<INDEXENTRIES...>
<CLOSE></programlisting>
Here, <literal>transformer-of</literal> 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
<literal>:upcase</literal>, <literal>:downcase</literal>
and <literal>:capitalize</literal> which result in the
corresponding string conversions. If none of them is
specified no transformation is done at all.
</para>
<para>The command <literal>markup-letter-group</literal>
defines the markup of the list of letter groups.
</para>
</section>
<section>
<title><literal>markup-locclass-list</literal></title>
<para><programlisting>(markup-locclass-list [:open string] [:close string]
[:sep string])</programlisting>
</para>
<para>Each index entry contains a list of location class groups.
This markup command can be used to define the markup of
this list.
</para>
</section>
<section>
<title><literal>markup-locref</literal></title>
<para><programlisting>(markup-locref [:open string] [:close string]
[:class locref-class]
[:attr attribute]
[:depth integer])</programlisting>
</para>
<para>The markup tags of a location reference can be
specialized on the three arguments <literal>:class</literal>,
<literal>:attr</literal> and additionally, if
sub-references are used, <literal>:depth</literal>.
Most often one will only use a tag depending on the
attribute. For example, all location references with the
attribute <literal>definition</literal> should appear in
a font series like bold, emphasizing the importance of
this location reference; those with the attribute
<literal>default</literal> 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.
<programlisting>(markup-locref :open "<B>" :close "</B>" :attr "definition")
(markup-locref :open "<I>" :close "</I>" :attr "default")</programlisting>
</para>
</section>
<section>
<title><literal>markup-locref-class</literal></title>
<para><programlisting>(markup-locref-class [:open string] [:close string]
[:class locref-class])</programlisting>
</para>
<para>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 <literal>:class</literal>.
</para>
</section>
<section>
<title><literal>markup-locref-layer</literal></title>
<para><programlisting>(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])</programlisting>
</para>
<para>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).
</para>
<para>The first command allows to tag the elements of a layer
list differently. The first element of this list can is
specialisable with <literal>:layer 0</literal>, the next
element with <literal>:layer 1</literal>, etc. See the next
example for an example.
</para>
</section>
<section>
<title><literal>markup-locref-list</literal></title>
<para><programlisting>(markup-locref-list [:open string] [:close string] [:sep string]
[:depth integer] [:class locref-class])</programlisting>
</para>
<para>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
<literal>:class</literal>, and on <literal>:depth</literal>
that specializes on the different subentry levels when using
location references with sub-references.
</para>
<para>Given is a list of location references that have the
class description
<programlisting>(define-location-class "Appendix"
("ALPHA" :sep "-" "arabic-numbers")
:hierdepth 2)</programlisting>
</para>
<para>This location class has instances like
<literal>A-1</literal>, <literal>B-5</literal>, etc. The
keyword argument <literal>:hierdepth 2</literal> informs
&xindy; to markup these location references in a
hierarchical form. With the commands
<programlisting>(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")</programlisting>
we obtain a markup sequence for some example data that
could look like
<programlisting> \bf A} 1,2,5; {\bf B} 5,6,9; {\bf D} 1,5,8; ...</programlisting>
</para>
</section>
<section>
<title><literal>markup-range</literal></title>
<programlisting>(markup-range [:open string] [:close string] [:sep string]
[:class locref-class]
[:length num] [:ignore-end])</programlisting>
<para>A range consists of two location references. Markup
can be specified with the <literal>:open</literal> and
<literal>:close</literal> arguments and one separator given
by the argument <literal>:sep</literal>.</para>
<para>Since both location references are tagged with markup
defined by the command <literal>markup-locref</literal> 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
<literal>:length</literal> can be used to define different
markup for different lengths. In conjunction with
<literal>:length</literal> 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 Xf. instead
of X--Y. This can be accomplished with the switch
<literal>:ignore-end</literal>.</para>
<para>The markup tags for a range (X,Y) can be described
as follows:
<programlisting><OPEN>
Markup of location reference X
<SEP>
IF (not :ignore-end)
Markup of location reference Y
FI
<CLOSE></programlisting>
</para>
<para>The following tags can be used to define a range of
page numbers (given in a location class
<literal>page-numbers</literal>) without considering the
open and close parameters:
<programlisting>(markup-range :sep "-" :class "page-numbers")</programlisting>
</para>
<para>Location ranges then appear separated by a hyphen in a
form like this:
<programlisting> ..., 5-8, 19-23, ...</programlisting>
</para>
</section>
<section>
<title><literal>(markup-trace [:on] [:open string] [:close string])</literal></title>
<para>This command can be used to activate the tracing of
all markup commands xindy executes. The switch
<literal>:on</literal> activates the trace. If
<literal>:on</literal> is omitted, the command line
flag <literal>-t</literal> 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 <literal>:open</literal> is
<literal>`<'</literal> and for <literal>:close</literal>
is <literal>`>'</literal>. The beginning of an example
output could look like:
<programlisting><INDEX:OPEN>
<LETTER-GROUP-LIST:OPEN>
<LETTER-GROUP:OPEN ["a"]>
<INDEXENTRY-LIST:OPEN [0]>
<INDEXENTRY:OPEN [0]>
<KEYWORD-LIST:OPEN [0]>
<KEYWORD:OPEN [0]>
...</programlisting>
</para>
<para>We use a simple indentation scheme to make the structure
of the tags visible. The symbolic tag
<literal><LETTER-GROUP:OPEN ["a"]></literal> for
example indicates that the tag that can be specified with
the command
<programlisting>(markup-letter-group :open "XXX" :group "a" ... )</programlisting>
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
<programlisting>(markup-trace :open "%%" :close "~n")</programlisting>
or a definition in the TeX document like
<programlisting>\def\ignore#1{}</programlisting>
combined with the command
<programlisting>(markup-trace :open "\ignore{" :close "}")</programlisting>
</para>
</section>
</section>
<section id="xindy-command-list-raw-index">
<title>Raw Index Interface</title>
<indexterm>
<primary>&xindy;</primary>
<secondary>Command List</secondary>
<tertiary>Raw Index Interface</tertiary>
</indexterm>
<para>This section can be skipped if the reader is not
interested in adapting xindy to a new document
preparation system.
</para>
<para>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 xindy. We also could have written an
configurable parser performing this task, but usually
a tool written with some text processing tools such as
<command>perl</command>, <command>sed</command> or
<command>awk</command> can achieve the same task as well.
Therefore, adapting xindy to a completely different system
can mostly be done by writing an appropriate raw index filter.
</para>
<para>The format of the raw index interface of xindy is
defined as follows:
</para>
<programlisting>(indexentry { :key string-list [:print string-list]
| :tkey list-of-layers }
[:attr string]
{ :locref string [:open-range | :close-range]
| :xref string-list } )</programlisting>
<para>The pseudo variable <emphasis>string</emphasis> is a
sequence of characters surrounded by double quotes, e.g.
<programlisting>"Hi, it's me" "one" "a string with two \"double quotes\""</programlisting>
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 <emphasis>string list</emphasis> is simply a list of strings
separated by whitespaces and surrounded by round braces.
An example of a string list is
<programlisting>("This" "is" "a" "list" "of" "strings")</programlisting>
</para>
<para>So far about the syntax. The semantics of the
different elements are described here.
</para>
<variablelist role="db2latex:compact">
<varlistentry>
<term><literal>:key</literal></term>
<listitem>
<para>The argument <emphasis>string list</emphasis>
defines the keyword of the index entry. It must be
a list of strings, since the keyword may consist of
different layers such as
<literal>("heap" "fibonacci")</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>:print</literal></term>
<listitem>
<para>The optional <emphasis>print key</emphasis> defines
the way the keyword has to be printed in the markup phase.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>:tkey</literal></term>
<listitem>
<para>Another possibility to define the keys of an index
entry is with the <literal>:tkey</literal> keyword
argument. It can be used instead of the
<literal>:key</literal> and <literal>:print</literal>
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
<programlisting>:tkey (("This") ("is") ("a") ("bang" "BANG !!!"))</programlisting>
is equivalent to
<programlisting>:key ("This" "is" "a" "bang")
:print ("This" "is" "a" "BANG !!!")</programlisting>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>:locref</literal></term>
<listitem>
<para>The reference an index entry describes can be a
<emphasis>location reference</emphasis> or a
<emphasis>cross reference</emphasis>. The switch
<literal>:locref</literal> describes a location
reference. Its optional arguments are
<literal>:open-range</literal> and
<literal>:close-range</literal>. The
<emphasis>string</emphasis> that must be supplied must
somehow encode the location reference. It might look
like the string <literal>"25"</literal> representing
the page number 25, or <literal>"Appendix-I"</literal>
representing the first appendix numbered in
uppercase roman numerals.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>:open-range,:close-range</literal></term>
<listitem>
<para>These are switches that do not take any arguments.
They describe the beginning and ending of a
<emphasis>range</emphasis>, starting or ending from
the location reference that is given by the argument
<literal>:locref</literal>. If they are supplied,
the location reference may have influence on the
way ranges are build.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>:xref</literal></term>
<listitem>
<para>These arguments choose the second alternative.
The argument <emphasis>string list</emphasis> of
parameter <literal>:xref</literal> describes where
the index entry should point to.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>:attr</literal></term>
<listitem>
<para>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 <literal>default</literal>.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>Some examples:
<programlisting>(indexentry :key ("airplane") :locref "25" :attr "default")</programlisting>
defines an index entry with the key
<emphasis>airplane'</emphasis> indexed on page
<emphasis>25'</emphasis>. This index entry has the
attribute <literal>default</literal>.
</para>
<para><programlisting>(indexentry :key ("house") :xref("building") :attr "see")</programlisting>
defines a cross reference with the key
<literal>house</literal> pointing to the term
<literal>building</literal>. This cross reference belongs to
the cross reference class <literal>see</literal>.
</para>
<para><programlisting>(indexentry :key ("house") :xref("building") :open-range)</programlisting>
is an invalid specification, since
<literal>:open-range</literal>
mustn't be used together with cross references.
</para>
</section>
</section>
<section id="xindy-invoking">
<title>Invoking xindy</title>
<indexterm>
<primary>&xindy;</primary>
<secondary>Invoking</secondary>
</indexterm>
<section id="xindy-invoking-cmdline">
<title>Command Line Options</title>
<indexterm>
<primary>&xindy;</primary>
<secondary>Invoking</secondary>
<tertiary>Command Line Options</tertiary>
</indexterm>
<para>The following command line options are accepted:</para>
<programlisting>xindy [-h] [-t] [-v] [-l logfile] [-o outfile]
[-L n] [-f filterprog]
indexstyle raw-index</programlisting>
<para>The argument <literal>indexstyle</literal> names a file,
containing the index style description. The argument
<literal>raw-index</literal> names a file, containing
the raw index. Both arguments are mandatory.
</para>
<para><variablelist role="db2latex:compact">
<varlistentry>
<term>-h</term>
<listitem>
<para>Gives a short summary of all command line options.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-l</term>
<listitem>
<para>Writes helpful information into the
specified <literal>logfile</literal>. For example,
the keyword mappings are written into this file,
so one can check if the intended mappings were
actually performed this way.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-o</term>
<listitem>
<para>Explicitly defines the name of the
<literal>output</literal> file.
If not given, the name of the
<literal>raw-index</literal> is used with
its extension changed to <literal>.ind</literal>
(or added, if it had no extension at all).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-t</term>
<listitem>
<para>Enters tracing mode of the symbolic markup tags.
The format of the emitted tags can be defined with
the command <literal>markup-trace</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-L</term>
<listitem>
<para>Set the xindy logging-level to <literal>n</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-f</term>
<listitem>
<para>Run <literal>filterprog</literal> on
<literal>raw-index</literal> before reading.
The program must act as a filter reading from
<literal>stdin</literal> and writing to
<literal>stdout</literal>. The most obvious use
of this option in conjunction with TeX is to run
<literal>-f tex2xindy</literal> on the index file
prior to reading the entries into xindy.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-v</term>
<listitem>
<para>Shows the version number of xindy.
</para>
</listitem>
</varlistentry>
</variablelist>
Errors and warnings are reported to <literal>stdout</literal>
and additionally to the logfile if <literal>-l</literal>
was specified.
</para>
</section>
<section id="xindy-search-path">
<title>Search Path</title>
<indexterm>
<primary>&xindy;</primary>
<secondary>Invoking</secondary>
<tertiary>Search Path</tertiary>
</indexterm>
<para>The system uses the concept of a search path for
finding the index style files and modules. The searchpath
can be set with the environment variable
<envar>XINDY_SEARCHPATH</envar> which must contain a
list of colon-separated directories. If it ends with a
colon, the built-in searchpath is added to the entire
searchpath. See the command
<link linkend="xindy-command-list-processing-searchpath">searchpath</link>
for further details.
</para>
</section>
</section>
</chapter>
|