summaryrefslogtreecommitdiff
path: root/Master/texmf-doc/source/english/tex-refs/tex-refs-chapter-xindy.xml
blob: ce1a4c2c1aa6ee59541d72fc1824169bee5197f6 (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
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 (&lt;rule&gt;...) )</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>&lt;rule&gt; ::= ("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>&amp;</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]" "&amp;")</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 ( &lt;rule-set&gt;... ))</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 "&lt;group0&gt;" :close &lt;/group0&gt;"
                        :group 0)

(markup-attribute-group :open "&lt;group1&gt;" :close "&lt;/group1&gt;"
                        :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>&lt;OPEN&gt;
   IF (:open-head OR :close-head)
     &lt;OPEN-HEAD&gt;
       transformer-of(&lt;GROUP-NAME&gt;)
     &lt;CLOSE-HEAD&gt;
   FI
   &lt;INDEXENTRIES...&gt;
&lt;CLOSE&gt;</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 "&lt;B&gt;" :close "&lt;/B&gt;" :attr "definition")
(markup-locref :open "&lt;I&gt;" :close "&lt;/I&gt;" :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>&lt;OPEN&gt;
  Markup of location reference X
&lt;SEP&gt;
  IF (not :ignore-end)
     Markup of location reference Y
  FI
&lt;CLOSE&gt;</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>`&lt;'</literal> and for <literal>:close</literal> 
	    is <literal>`&gt;'</literal>. The beginning of an example 
	    output could look like:
	    <programlisting>&lt;INDEX:OPEN&gt;
  &lt;LETTER-GROUP-LIST:OPEN&gt;
    &lt;LETTER-GROUP:OPEN ["a"]&gt;
      &lt;INDEXENTRY-LIST:OPEN [0]&gt;
        &lt;INDEXENTRY:OPEN [0]&gt;
          &lt;KEYWORD-LIST:OPEN [0]&gt;
            &lt;KEYWORD:OPEN [0]&gt;
 ...</programlisting>
	  </para>
	  <para>We use a simple indentation scheme to make the structure
	    of the tags visible. The symbolic tag 
	    <literal>&lt;LETTER-GROUP:OPEN ["a"]&gt;</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>