summaryrefslogtreecommitdiff
path: root/Build/source/utils/xindy/xindy-src/doc/manual-3.html
blob: e00cf79c6f7ad7fdf18a4aaef9eb06cfe397e991 (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
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
 <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
 <TITLE>xindy Manual: Command List</TITLE>
 <LINK HREF="manual-4.html" REL=next>
 <LINK HREF="manual-2.html" REL=previous>
 <LINK HREF="manual.html#toc3" REL=contents>
</HEAD>
<BODY>
<A HREF="manual-4.html">Next</A>
<A HREF="manual-2.html">Previous</A>
<A HREF="manual.html#toc3">Contents</A>
<HR>
<H2><A NAME="s3">3. Command List</A></H2>

<P>Here is the complete list of <SF>xindy</SF>'s commands that may be used in
the index style. The symbol <CODE>name</CODE> always refers to a string. We
separate the commands into the <EM>processing</EM> and
<EM>markup</EM> commands. The commands are listed in alphabetical order.
<P>The parenthesis `<CODE>[</CODE>' and `<CODE>]</CODE>' denote optional parts of the
syntax and `<CODE>{</CODE>' and `<CODE>}</CODE>' denote the grouping of elements. A
vertical bar indicates alternatives. However, the enclosing round
braces <EM>are</EM> part of the syntax and must be supplied.
<P>
<P>
<H2><A NAME="ss3.1">3.1 Processing Commands</A>
</H2>

<P>Here follows the list of processing commands.
<P>
<A NAME="define-alphabet"></A> 
<BLOCKQUOTE><CODE>
<PRE>
(define-alphabet name string-list)
</PRE>
</CODE></BLOCKQUOTE>
<P>Defines <CODE>name</CODE> to be the alphabet consisting of all elements of the
<CODE>string-list</CODE>. Examples:
<P>
<PRE>
  (define-alphabet "example-alphabet" ("An" "Example" "Alphabet"))
</PRE>
<P>defines an alphabet consisting of exactly three symbols. For the
successor relationship holds: <CODE>succ("An")="Example"</CODE> and
<CODE>succ("Example")="Alphabet"</CODE>. The built-in alphabet <CODE>digits</CODE> is
defined as follows:
<P>
<PRE>
  (define-alphabet "digits"
                   ("0" "1" "2" "3" "4" "5" "6" "7" "8" "9"))
</PRE>
<P>
<P>
<P>
<A NAME="define-attributes"></A> 
<BLOCKQUOTE><CODE>
<PRE>
(define-attributes attribute-list)
</PRE>
</CODE></BLOCKQUOTE>
<P>Defines all attributes the raw index may contain. Parameter
<CODE>attribute-list</CODE> is a list of list of strings. The nesting level
must not be more than&nbsp;2. So <CODE>(..(..)..)</CODE> is allowed, whereas
<CODE>(..(..(..)..)..)</CODE> is not.
<P>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 <CODE>("definition")</CODE> and <CODE>( ("definition") )</CODE> are equivalent.
All elements forming a list are a so-called <EM>attribute group</EM>. The
members of a group are written to the output file before any member
of the following groups are written.
<P>Examples of valid attributes lists are:
<P><CODE>("definition" "usage")</CODE> defines two attribute groups. The first
one contains all references with the attribute <CODE>definition</CODE> and the
second one all with the attribute <CODE>usage</CODE>.
<P><CODE>(("definition" "important") "usage")</CODE> defines two attribute
groups. The first one contains all references with the attributes
<CODE>definition</CODE> or <CODE>important</CODE> and the second one all with the
attribute <CODE>usage</CODE>. In the attribute group <CODE>("definition"
"important")</CODE> the attribute <CODE>definition</CODE> overrides <CODE>important</CODE>.
<P>
<P>
<P>
<A NAME="define-crossref-class"></A> 
<BLOCKQUOTE><CODE>
<PRE>
(define-crossref-class name [:unverified])
</PRE>
</CODE></BLOCKQUOTE>
<P>Defines <CODE>name</CODE> to be a class of cross references. We distinguish
two types of cross reference classes. <EM>Verified</EM> 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 <CODE>:unverified</CODE> can be used to suppress this
behaviour.
<P>
<P>
<A NAME="define-letter-group"></A> 
<A NAME="define-letter-groups"></A> 
<BLOCKQUOTE><CODE>
<PRE>
(define-letter-group name [:before lgname] [:after lgname]
                          [:prefixes list-of-prefixes])

(define-letter-groups list-of-letter-groups)
</PRE>
</CODE></BLOCKQUOTE>
<P>This command defines a letter group with name <CODE>name</CODE>, which must be
a string value, grouping all index entries that have a <EM>sort key</EM>
beginning with the prefix <CODE>name</CODE>. The command
<P>
<PRE>
  (define-letter-group "a")
</PRE>
<P>is equivalent to the command
<P>
<PRE>
  (define-letter-group "a" :prefixes ("a"))
</PRE>
<P>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.
<P>Example:
<P>
<PRE>
  (define-letter-group "a")
</PRE>
<P>defines a letter group containing all index entries beginning with the
string <CODE>"a"</CODE>.
<P>
<PRE>
  (define-letter-group "c" :after "a")
</PRE>
<P>defines a letter group containing all index entries beginning with the
string <CODE>"c"</CODE>. The letter group appears behind the letter group "a"
<P>
<PRE>
  (define-letter-group "b" :after "a" :before "c")
</PRE>
<P>inserts letter group "b" between letter group "a" and "c". This allows
incremental definition of letter groups by extending already defined
ones.
<P>The arguments <CODE>:after</CODE> and <CODE>:before</CODE> define a partial order on
the letter groups. <SF>xindy</SF> 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.
<P>The command <CODE>define-letter-groups</CODE> (with an `s' at the end) is
simply an abbreviation for a sequence of
<CODE>define-letter-group</CODE> definitions where the elements are ordered in
the ordering given by the list. Example:
<P>
<PRE>
  (define-letter-groups ("a" "b" "c")
</PRE>
<P>equals the definitions
<P>
<PRE>
  (define-letter-group "a")
  (define-letter-group "b" :after "a")
  (define-letter-group "c" :after "b")
</PRE>
<P>See also commands <CODE>markup-letter-group-list</CODE> and
<CODE>markup-letter-group</CODE> for further information.
<P>
<P>
<P>
<A NAME="define-location-class"></A> 
<BLOCKQUOTE><CODE>
<PRE>
(define-location-class name layer-list
                       [:min-range-length num]
                       [:hierdepth depth]
                       [:var])
</PRE>
</CODE></BLOCKQUOTE>
<P>Defines <CODE>name</CODE> 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 <CODE>:sep</CODE>. If the keyword <CODE>:min-range-length</CODE> is
specified we define the <EM>minimum range length</EM> to be used when
building ranges. The argument <CODE>num</CODE> must be a positive integer
number. Use a sufficiently large number (such as 10000) to disallow the building of ranges.
If the switch <CODE>:var</CODE> is specified the declared class
is of type <EM>variable</EM>, i.e. it is a <EM>var-location-class</EM>. Since
building of ranges is currently only allowed for standard classes
<CODE>:var</CODE> and <CODE>:min-range-length</CODE> must not be used together. The
keyword argument <CODE>:hierdepth</CODE> can be used to declare that the
location references have to be tagged in a hierarchical form. Its
argument <CODE>depth</CODE> must be an integer number indicating the number of
layers the hierarchy does contain. See command
<CODE>markup-locref-list</CODE> for more information. Examples:
<P>
<PRE>
  (define-location-class "page-numbers" ("arabic-numbers")
                         :min-range-length 3)
</PRE>
<P>Defines the location class <CODE>page-numbers</CODE> consisting of one layer
which is the alphabet <CODE>arabic-numbers</CODE>. 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 <CODE>0</CODE>, <CODE>1</CODE>, ... <CODE>2313</CODE>, etc.
<P>
<PRE>
  (define-location-class "sections" :var
     ("arabic-numbers" :sep "."
      "arabic-numbers" :sep "."
      "arabic-numbers"))
</PRE>
<P>defines a variable location class. Valid instances are <CODE>1</CODE>,
<CODE>1.1</CODE>, <CODE>1.2</CODE>, <CODE>2</CODE>, <CODE>2.4.5</CODE>, but none of <CODE>2-3</CODE> (wrong
separator), <CODE>1.2.3.4</CODE> (more than 3 layers), <CODE>2.3.iv</CODE> (roman
number instead of arabic one).
<P>
<P>
<P>
<A NAME="define-location-class-order"></A> 
<BLOCKQUOTE><CODE>
<PRE>
(define-location-class-order list)
</PRE>
</CODE></BLOCKQUOTE>
<P>Defines the order in which the location classes are written to the
output file. The parameter <CODE>list</CODE> is a list of names of
location classes. Examples:
<P>
<PRE>
  (define-location-class-order
      ("page-numbers" "sections" "xrefs"))
</PRE>
<P>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.
<P>
<P>
<P>
<A NAME="define-rule-set"></A> 
<BLOCKQUOTE><CODE>
<PRE>
(define-rule-set name
        [ :inherit-from ("rule-set" "rule-set-2") ]
        :rules (&lt;rule>...) )
</PRE>
</CODE></BLOCKQUOTE>
<P>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 <CODE>sort-rule</CODE>.
They do not add new functionality that is not already present with
<CODE>sort-rule</CODE>.
<P>A rule can be of the form:
<P>
<PRE>
  &lt;rule> ::= ("pattern" "replacement"
              [:string|:bregexp|:egegexp] [:again])
</PRE>
<P>The following incomplete example defines a new rule set of name
<CODE>isolatin1-tolower</CODE> that inherits definitions from rule set
<CODE>latin-tolower</CODE>, overriding or adding the sort rules in the list of
<CODE>:rules</CODE>.
<P>
<PRE>
   (define-rule-set "isolatin1-tolower"

     :inherit-from ("latin-tolower")

     :rules (("À" "à" :string :again)
             ("Á" "á" :string :again)
             ("Â" "â" :string :again)
             ("Ã" "ã" :string :again)
             ("Ä" "ä" :string :again)
             ("Å" "å" :string :again)
             ("Æ" "æ" :string :again)
          ...
            )
   ...)
</PRE>
<P>Rule sets can be instantiated with the command <CODE>use-rule-set</CODE>. For
further descriptions on the sorting model refer to the command
<CODE>sort-rule</CODE>.
<P>
<P>
<A NAME="define-sort-rule-orientations"></A> 
<BLOCKQUOTE><CODE>
<PRE>
(define-sort-rule-orientations (orientations...))
</PRE>
</CODE></BLOCKQUOTE>
<P>Defines the order for the different sorting phases. The currently
implemented <EM>orientations</EM> are <CODE>forward</CODE> and <CODE>backward</CODE>. This
command must precede all <CODE>sort-rule</CODE> commands in an index style. It
defines the orientations and implicitly sets the maximum number of
sorting phases performed.
<P>For further descriptions on the sorting model refer to the command
<CODE>sort-rule</CODE>.
<P>
<P>
<P>
<A NAME="merge-rule"></A> 
<BLOCKQUOTE><CODE>
<PRE>
(merge-rule pattern replacement [:again]
                                [:bregexp | :eregexp | :string])
</PRE>
</CODE></BLOCKQUOTE>
<P>Defines a keyword mapping rule that can be used to generate the
<EM>merge key</EM> from the <EM>main key</EM> 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.
<P>The parameter <CODE>pattern</CODE> 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 <EM>basic regular
expressions</EM> (BREs) or <EM>extended regular expressions</EM> (EREs). You
can use the switch <CODE>:bregexp</CODE> to force the interpretation of the
pattern as a BRE, or <CODE>:eregexp</CODE> to interpret it as an ERE. If you
want <SF>xindy</SF> to interpret the pattern literally, use the switch
<CODE>:string</CODE>. If none of these switches is selected, <SF>xindy</SF> 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.
<P>The parameter <CODE>replacement</CODE> must be
a string possibly containing the special characters <CODE>&amp;</CODE>
(substitutes for the complete match) and <CODE>\1</CODE>,...,<CODE>\9</CODE>
(substituting for the <EM>n</EM>-th submatch. Examples:
<P>
<PRE>
  (merge-rule "A" "a")
</PRE>

replaces each occurrence of the uppercase letter `<CODE>A</CODE>' with its
lowercase counterpart.
<P>
<PRE>
  (merge-rule "\~"([AEOUaeou])" "\1")
</PRE>

transforms the TeX umlaut-letters into their stripped counterparts,
such that `<CODE>\"A</CODE>' is treated as an `<CODE>A</CODE>' afterwards.
<P>The following sequences have a special meaning:
<P>`<CODE>~n</CODE>' : End of line symbol (<EM>linefeed</EM>).
<P>`<CODE>~b</CODE>' : The ISO-Latin character with the lowest ordinal number.
<P>`<CODE>~e</CODE>' : The ISO-Latin character with the highest ordinal number.
<P>`<CODE>~~</CODE>' : The tilde character.
<P>`<CODE>~"</CODE>' : The double quote character.
<P>Tilde characters and double quotes have to be quoted themselves with a
tilde character. The special characters `<CODE>~b</CODE>' and
`<CODE>~e</CODE>' 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. `<CODE>m~e</CODE>' is
lexicographically placed between `<CODE>m</CODE>' and `<CODE>n</CODE>'.
<P>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
<P>
<PRE>
  (merge-rule "[A-Z]" "&amp;x")
</PRE>
<P>it is more efficient (though less comfortable) to use
<P>
<PRE>
  (merge-rule "A" "Ax")
  (merge-rule "B" "Bx")
  ...
  (merge-rule "Z" "Zx")
</PRE>
<P>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 `<CODE>alpha</CODE>' is checked before `<CODE>.*</CODE>', but
`<CODE>auto</CODE>' and `<CODE>a.*</CODE>' are checked in order of their definition.
<P>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.
<P>Sometimes it is necessary to apply rules anew to the result of a
transformation. By specifying the keyword argument <CODE>:again</CODE> in the
merge rule the rule is marked as <EM>mutable</EM>, which means that after
using this rule the transformation process shall restart at the same
place. E.g. the rule
<P>
<PRE>
  (merge-rule "\$(.*)\$" "\1" :again)
</PRE>
<P>deletes <EM>all</EM> surrounding `<CODE>$</CODE>' symbols from the input.
<P>See also command <CODE>sort-rule</CODE>.
<P>
<P>
<A NAME="merge-to"></A> 
<BLOCKQUOTE><CODE>
<PRE>
(merge-to attr-from attr-to [:drop])
</PRE>
</CODE></BLOCKQUOTE>
<P>A <EM>merge rule</EM> says that the attribute <CODE>attr-from</CODE> can be used
to build ranges in <CODE>attr-to</CODE>. Both attributes must name valid
attribute names. The switch <CODE>:drop</CODE> indicates, that the original
location reference with attribute <CODE>attr-from</CODE> has to be dropped
(removed), if a successful range was built with location references in
attribute <CODE>attr-to</CODE>. A detailed description is given in the section
about processing phases.
<P>
<P>
<P>
<A NAME="require"></A> 
<BLOCKQUOTE><CODE>
<PRE>
(require filename)
</PRE>
</CODE></BLOCKQUOTE>
<P>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
<CODE>filename</CODE> 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:
<P>
<PRE>
  (require "french/alphabet.xdy")
  (require "french/sort-rules.xdy")
  (require "tex/locations.xdy")
  (require "tex/markup.xdy")
</PRE>
<P>Submodules can load other submodules as well. If a file is required
that was already loaded, the <CODE>require</CODE> command is simply ignored
and processing continues without including this file twice. See also
command <CODE>searchpath</CODE>.
<P>
<P>
<P>
<A NAME="searchpath"></A> 
<BLOCKQUOTE><CODE>
<PRE>
(searchpath {path-string | path-list})
</PRE>
</CODE></BLOCKQUOTE>
<P>This command adds the given paths to the list of paths, <SF>xindy</SF>
searches for index style files. The argument <CODE>path-string</CODE> 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:
<P>
<BLOCKQUOTE><CODE>
<PRE>
  (searchpath ".:/usr/local/lib/xindy:/usr/local/lib/xindy/english:")
</PRE>
</CODE></BLOCKQUOTE>
<P>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
<P>
<BLOCKQUOTE><CODE>
<PRE>
  (searchpath ("."
               "/usr/local/lib/xindy"
               "/usr/local/lib/xindy/english"
               :default))
</PRE>
</CODE></BLOCKQUOTE>
<P>yields exactly the same result as the example above. Here
<CODE>path-list</CODE> must be a list of strings and/or the keyword(s)
<CODE>:default</CODE> and <CODE>:last</CODE>. The keyword <CODE>:default</CODE> signifies that
the default pathnames are to be inserted at the specified position in
the list. The keyword <CODE>:last</CODE> 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.
<P>
<P>
<A NAME="sort-rule"></A> 
<BLOCKQUOTE><CODE>
<PRE>
(sort-rule pattern replacement [:run level] [:again])
</PRE>
</CODE></BLOCKQUOTE>
<P>Defines a keyword mapping rule that can be used to generate the
<EM>sort key</EM> of an index entry from the <EM>merge key</EM>. This key is
used to sort the index entries lexicographically after they have been
merged using the merge key.
<P>The argument <CODE>:run</CODE> indicates that this rule is only in effect
a the specified <EM>level</EM> (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
(<CODE>new-sort-rules</CODE>) that comes with this distribution.
<P>See command <CODE>merge-rule</CODE> for more information about keyword
rules.
<P>
<P>
<P>
<A NAME="use-rule-set"></A> 
<BLOCKQUOTE><CODE>
<PRE>
(use-rule-set [:run phase]
              [:rule-set ( &lt;rule-set>... ))
</PRE>
</CODE></BLOCKQUOTE>
<P>This command instantiates the gives rule sets to be in effect at
sorting phase <CODE>phase</CODE>. The order of the rule sets given with
argument <CODE>:rule-set</CODE> 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.
<P>The following example declares that in phase 0 the rule sets
<CODE>din5007</CODE> and <CODE>isolatin1-tolower</CODE> should be active, whereas in
phase 2 the other rule sets have to be applied.
<P>
<PRE>
  (use-rule-set :run 0
                :rule-set ("din5007" "isolatin1-tolower"))

  (use-rule-set :run 1
                :rule-set ("resolve-umlauts"
                           "resolve-sharp-s"
                           "isolatin1-tolower"
                           ))
</PRE>
<P>For a discussion on rule sets refer to command <CODE>define-rule-set</CODE>.
<P>
<P>
<P>
<H2><A NAME="ss3.2">3.2 Markup Commands</A>
</H2>

<P>
<P>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 <EM>environments</EM>,
the syntax and naming scheme of all commands follows a simple
structure.
<P>The commands can be separated into <EM>environment</EM>  and
<EM>list-environment</EM> commands. All commands of the first group
support the keyword arguments <CODE>:open</CODE> and <CODE>:close</CODE>, whereas the
second group additionally supports the keyword argument <CODE>:sep</CODE>. If
one of these keyword arguments is missing, the default markup tag is
<EM>always</EM> the empty tag. The <CODE>:open</CODE> tag is always printed before
the object itself and the <CODE>:close</CODE> tag is always printed after the
object has been printed. If a list is printed the <CODE>:sep</CODE>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 `<CODE>-list</CODE>' as part of their command name.
<P>Since the number of commands and the heavy usage of <EM>default</EM> and
<EM>specialized</EM> tags makes the markup somehow complex (but very
powerful) we have added a mechanism to trace the markup tags
<SF>xindy</SF> omits during its markup phase with the command
<CODE>markup-trace</CODE>.
<P>Here follows the list of markup commands in alphabetical order with
some of the commands grouped together.
<P>
<P>
<A NAME="markup-attribute-group"></A> 
<A NAME="markup-attribute-group-list"></A> 
<BLOCKQUOTE><CODE>
<PRE>
(markup-attribute-group-list [:open string] [:close string]
                             [:sep string])

(markup-attribute-group      [:open string] [:close string]
                             [:group group-num])
</PRE>
</CODE></BLOCKQUOTE>
<P>Location class groups consist of lists of attribute groups. The markup
of this list can be defined with the command
<CODE>markup-attribute-group-list</CODE>.
<P>To allow different markup for different attribute groups the command
<CODE>markup-attribute-group</CODE> can be specialized on the group number
with the keyword argument <CODE>:group</CODE> which must be an integer number.
E.g., given are the groups <CODE>("definition" "theorem")</CODE> and
<CODE>("default")</CODE> with group numbers 0 and 1, then
<P>
<PRE>
  (markup-attribute-group :open "&lt;group0>" :close "&lt;/group0>"
                          :group 0)

  (markup-attribute-group :open "&lt;group1>" :close "&lt;/group1>"
                          :group 1)
</PRE>
<P>can be used to assign different markup for both groups in a SGML-based
language.
<P>
<P>
<A NAME="markup-crossref-layer"></A> 
<A NAME="markup-crossref-layer-list"></A> 
<A NAME="markup-crossref-list"></A> 
<BLOCKQUOTE><CODE>
<PRE>
(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])
</PRE>
</CODE></BLOCKQUOTE>
<P>A crossref class group contains cross references of the same class.
The separator between the classes is defined with the
<CODE>(markup-locclass-list :sep)</CODE>-parameter. A list of cross references
can be tagged with the command <CODE>markup-crossref-list</CODE> that
specializes on the <CODE>:class</CODE> argument.
<P>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 command <CODE>markup-crossref-layer-list</CODE> can be used.
<P>Each layer of a cross reference can be assigned two tags that
specialize on the class of the reference, like all other commands.
<P>A suitable markup for a cross reference class <CODE>see</CODE> within LaTeX2e
could look like that:
<P>
<PRE>
  (markup-crossref-list :class "see" :open "\emph{see} "
                                     :sep  "; ")
  (markup-crossref-layer-list :class "see" :sep ",")
  (markup-crossref-layer :class "see"
                                     :open "\textbf{" :close "}")
</PRE>
<P>An example output could look like
<P>
<BLOCKQUOTE>
... <EM>see</EM>  <B>house</B>; <B>garden</B>,<B>winter</B>; <B>greenhouse</B>
</BLOCKQUOTE>
<P>
<P>
<A NAME="markup-index"></A> 
<BLOCKQUOTE><CODE>
<PRE>
(markup-index [:open string] [:close string]
              [ :flat | :tree | :hierdepth depth ])
</PRE>
</CODE></BLOCKQUOTE>
<P>Defines the markup tags that enclose the whole index via the
<CODE>:open</CODE> and <CODE>:close</CODE> parameters. Examples:
<P>
<PRE>
  (markup-index :open  "Here comes the index~n"
                :close "That's all folks!~n")
</PRE>
<P>defines that the <CODE>:open</CODE> string is printed before the rest of the
index and the <CODE>:close</CODE> string appears after the index is printed.
<P>Additionally one can specify the form of the generated index. It is
possible to produce flat indexes by specifying the switch <CODE>:flat</CODE>,
to generate a tree with the <CODE>:tree</CODE> switch or any kind of mixture
between both by specifying the depth up to which trees shall be built
with the parameter <CODE>:hierdepth</CODE>. Its argument <CODE>depth</CODE> is the
number of layers that can be formed into a tree. Therefore <CODE>:flat</CODE>
is an abbrevation of <CODE>:hierdepth 0</CODE> and <CODE>:tree</CODE> is an
abbrevation of <CODE>:hierdepth max-depth</CODE>, with <CODE>max-depth</CODE> being
the maximum number of layers a keyword has. An example: the keywords
<P>
<PRE>
  ("tree" "binary" "AVL")
  ("tree" "binary" "natural")
</PRE>
<P>can be transformed in the following ways:
<P>A flat index (<CODE>:flat</CODE> or <CODE>:hierdepth 0</CODE>)
<P>
<PRE>
  tree binary AVL
  tree binary natural
</PRE>
<P>with <CODE>:hierdepth 1</CODE>
<P>
<PRE>
  tree
     binary  AVL
     binary  natural
</PRE>
<P>and a tree (<CODE>:tree</CODE> or <CODE>:hierdepth</CODE> &gt; 1)
<P>
<PRE>
  tree
     binary
        AVL
        natural
</PRE>
<P>Most often one will create tree-like indexes or ones that are flat.
<P>
<P>
<A NAME="markup-indexentry-list"></A> 
<A NAME="markup-indexentry"></A> 
<BLOCKQUOTE><CODE>
<PRE>
(markup-indexentry-list [:open string] [:close string]
                        [:sep string]  [:depth integer])

(markup-indexentry      [:open string] [:close string]
                        [:depth integer])
</PRE>
</CODE></BLOCKQUOTE>
<P>Letter groups consists of a list of index entries. The command
<CODE>markup-indexentry-list</CODE> defines the markup of these lists. The
markup can be specialized on the depth if the index is hierarchically
organized. The command
<P>
<PRE>
  (markup-indexentry-list :open  "\begin{IdxentList}"
                          :close "\end{IdxentList}"
                          :sep   "~n")
</PRE>
<P>defines that the index entries of all layers are wrapped into the
given markup tags. If additionally
<P>
<PRE>
  (markup-indexentry-list :open  "\begin{IdxentListII}"
                          :close "\end{IdxentListII}"
                          :sep   "~n"
                          :depth 2)
</PRE>
<P>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.
<P>The command <CODE>markup-indexentry</CODE> 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 <CODE>:depth</CODE> 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.
<P>
<PRE>
  (markup-indexentry :open  "\begin{Indexentry}"
                     :close "\end{Indexentry}")
</PRE>
<P>defines that the index entries of all layers are wrapped into the
given markup tags. If additionally
<P>
<PRE>
  (markup-indexentry :open  "\begin{IndexentryII}"
                     :close "\end{IndexentryII}"
                     :depth 2)
</PRE>
<P>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.
<P>
<P>
<A NAME="markup-keyword-list"></A> 
<A NAME="markup-keyword"></A> 
<BLOCKQUOTE><CODE>
<PRE>
(markup-keyword-list [:open string] [:close string]
                     [:sep string] [:depth integer])

(markup-keyword      [:open string] [:close string]
                     [:depth integer])
</PRE>
</CODE></BLOCKQUOTE>
<P>
<P>The print key of an index entry consists of a list of strings. The
markup of this list can be defined with the command
<CODE>markup-keyword-list</CODE>. The keyword argument <CODE>:depth</CODE> may be
specified to define the markup of the list at a particular depth.
<P>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
<CODE>markup-keyword</CODE>. Since we maybe need different markup for
different layers, the optional keyword argument can be used to
specialize this markup for some depth.
<P>
<P>
<A NAME="markup-letter-group-list"></A> 
<A NAME="markup-letter-group"></A> 
<BLOCKQUOTE><CODE>
<PRE>
(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])
</PRE>
</CODE></BLOCKQUOTE>
<P>The first command defines the markup of the letter group with name
<CODE>group-name</CODE>. 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 <CODE>:open-head</CODE> and <CODE>:close-head</CODE> is specified
additional markup is added as can be described as follows:
<P>
<PRE>
  &lt;OPEN>
     IF (:open-head OR :close-head)
       &lt;OPEN-HEAD>
         transformer-of(&lt;GROUP-NAME>)
       &lt;CLOSE-HEAD>
     FI
     &lt;INDEXENTRIES...>
  &lt;CLOSE>
</PRE>
<P>Here, <CODE>transformer-of</CODE> 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
<CODE>:upcase</CODE>, <CODE>:downcase</CODE> and <CODE>:capitalize</CODE> which result in the
corresponding string conversions. If none of them is specified no
transformation is done at all.
<P>The command <CODE>markup-letter-group</CODE> defines the markup of the list of
letter groups.
<P>
<P>
<A NAME="markup-locclass-list"></A> 
<BLOCKQUOTE><CODE>
<PRE>
(markup-locclass-list [:open string] [:close string]
                      [:sep string])
</PRE>
</CODE></BLOCKQUOTE>
<P>Each index entry contains a list of location class groups. This markup
command can be used to define the markup of this list.
<P>
<P>
<A NAME="markup-locref"></A> 
<BLOCKQUOTE><CODE>
<PRE>
(markup-locref [:open string] [:close string]
               [:class locref-class]
               [:attr  attribute]
               [:depth integer])
</PRE>
</CODE></BLOCKQUOTE>
<P>The markup tags of a location reference can be specialized on the
three arguments <CODE>:class</CODE>, <CODE>:attr</CODE> and additionally, if
sub-references are used, <CODE>:depth</CODE>. Most often one will only use a
tag depending on the attribute. For example, all location references
with the attribute <CODE>definition</CODE> should appear in a font series like
bold, emphasizing the importance of this location reference; those
with the attribute <CODE>default</CODE> 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.
<P>
<PRE>
  (markup-locref :open "&lt;B>" :close "&lt;/B>" :attr "definition")
  (markup-locref :open "&lt;I>" :close "&lt;/I>" :attr "default")
</PRE>
<P>
<P>
<A NAME="markup-locref-class"></A> 
<BLOCKQUOTE><CODE>
<PRE>
(markup-locref-class [:open string] [:close string]
                     [:class locref-class])
</PRE>
</CODE></BLOCKQUOTE>
<P>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 <CODE>:class</CODE>.
<P>
<P>
<A NAME="markup-locref-layer-list"></A> 
<A NAME="markup-locref-layer"></A> 
<BLOCKQUOTE><CODE>
<PRE>
(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])
</PRE>
</CODE></BLOCKQUOTE>
<P>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).
<P>The first command allows to tag the elements of a layer list
differently. The first element of this list can is specialisable with
<CODE>:layer 0</CODE>, the next element with <CODE>:layer 1</CODE>, etc. See the next
example for an example.
<P>
<P>
<A NAME="markup-locref-list"></A> 
<BLOCKQUOTE><CODE>
<PRE>
(markup-locref-list [:open string] [:close string] [:sep string]
                    [:depth integer] [:class locref-class])
</PRE>
</CODE></BLOCKQUOTE>
<P>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 <CODE>:class</CODE>, and on <CODE>:depth</CODE>
that specializes on the different subentry levels when using
location references with sub-references.
<P>Given is a list of location references that have the class description
<P>
<PRE>
  (define-location-class "Appendix"
                         ("ALPHA" :sep "-" "arabic-numbers")
                         :hierdepth 2)
</PRE>
<P>This location class has instances like <CODE>A-1</CODE>, <CODE>B-5</CODE>, etc. The
keyword argument <CODE>:hierdepth 2</CODE> informs <SF>xindy</SF> to markup these
location references in a hierarchical form. With the commands
<P>
<PRE>
  (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")
</PRE>
<P>we obtain a markup sequence for some example data that could look like
<P>
<PRE>
  {\bf A} 1,2,5; {\bf B} 5,6,9; {\bf D} 1,5,8; ...
</PRE>
<P>
<P>
<P>
<A NAME="markup-range"></A> 
<BLOCKQUOTE><CODE>
<PRE>
(markup-range [:open string] [:close string] [:sep string]
              [:class locref-class]
              [:length num] [:ignore-end])
</PRE>
</CODE></BLOCKQUOTE>
<P>A range consists of two location references. Markup can be specified
with the <CODE>:open</CODE> and <CODE>:close</CODE> arguments and one separator given
by the argument <CODE>:sep</CODE>.
<P>Since both location references are tagged with markup defined by the
command <CODE>markup-locref</CODE> 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 <CODE>:length</CODE> can be used to define
different markup for different lengths. In conjunction with
<CODE>:length</CODE> 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 <EM>Xf.</EM> instead of <EM>X--Y</EM>. This can be accomplished
with the switch <CODE>:ignore-end</CODE>.
<P>The markup tags for a range <EM>(X,Y)</EM> can be described as follows:
<P>
<PRE>
  &lt;OPEN>
    Markup of location reference X
  &lt;SEP>
    IF (not :ignore-end)
       Markup of location reference Y
    FI
  &lt;CLOSE>
</PRE>
<P>
<P>The following tags can be used to define a range of page numbers
(given in a location class <CODE>page-numbers</CODE>) without considering the
open and close parameters:
<P>
<PRE>
  (markup-range :sep "-" :class "page-numbers")
</PRE>
<P>Location ranges then appear separated by a hyphen in a form like this:
<P>
<PRE>
   ..., 5-8, 19-23, ...
</PRE>
<P>
<P>
<A NAME="markup-trace"></A> 
<BLOCKQUOTE><CODE>
<PRE>
(markup-trace [:on] [:open string] [:close string])
</PRE>
</CODE></BLOCKQUOTE>
<P>This command can be used to activate the tracing of all
markup commands <SF>xindy</SF> executes. The switch <CODE>:on</CODE> activates the
trace. If <CODE>:on</CODE> is omitted, the command line flag <CODE>-t</CODE> 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 <CODE>:open</CODE> is `<CODE>&lt;</CODE>' and for <CODE>:close</CODE> is
`<CODE>></CODE>'. The beginning of an example output could look like:
<P>
<PRE>
  &lt;INDEX:OPEN>
    &lt;LETTER-GROUP-LIST:OPEN>
      &lt;LETTER-GROUP:OPEN ["a"]>
        &lt;INDEXENTRY-LIST:OPEN [0]>
          &lt;INDEXENTRY:OPEN [0]>
            &lt;KEYWORD-LIST:OPEN [0]>
              &lt;KEYWORD:OPEN [0]>
   ...
</PRE>
<P>We use a simple indentation scheme to make the structure of the tags
visible. The symbolic tag <CODE>&lt;LETTER-GROUP:OPEN ["a"]></CODE> for example
indicates that the tag that can be specified with the command
<P>
<PRE>
  (markup-letter-group :open "XXX" :group "a" ... )
</PRE>
<P>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
<P>
<PRE>
  (markup-trace :open "%%" :close "~n")
</PRE>
<P>or a definition in the TeX document like
<P>
<PRE>
  \def\ignore#1{}
</PRE>
<P>combined with the command
<P>
<PRE>
  (markup-trace :open "\ignore{" :close "}")
</PRE>
<P>
<P>
<P>
<A NAME="raw-index"></A> <H2><A NAME="ss3.3">3.3 Raw Index Interface</A>
</H2>

<P>
<P>This section can be skipped if the reader is not interested in
adapting <SF>xindy</SF> to a new document preparation system.
<P>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 <SF>xindy</SF>. We also could have
written an configurable parser performing this task, but usually a
tool written with some text processing tools such as <CODE>perl</CODE>,
<CODE>sed</CODE> or <CODE>awk</CODE> can achieve the same task as well. Therefore,
adapting <SF>xindy</SF> to a completely different system can mostly be
done by writing an appropriate raw index filter.
<P>The format of the raw index interface of <SF>xindy</SF> is defined as
follows:
<P>
<A NAME="indexentry"></A> 
<BLOCKQUOTE><CODE>
<PRE>
(indexentry { :key string-list [:print string-list]
            | :tkey list-of-layers }
            [:attr string]
            { :locref string  [:open-range | :close-range]
            | :xref string-list } )
</PRE>
</CODE></BLOCKQUOTE>
<P>The pseudo variable <EM>string</EM> is a sequence of characters
surrounded by double quotes, e.g.
<P>
<PRE>
  "Hi, it's me"  "one"  "a string with two \"double quotes\""
</PRE>
<P>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 <EM>string list</EM> is simply
a list of strings separated by whitespaces and surrounded by round
braces. An example of a string list is
<P>
<PRE>
  ("This" "is" "a" "list" "of" "strings")
</PRE>
<P>So far about the syntax. The semantics of the different elements are
described here.
<P>
<P>
<DL>
<P>
<DT><B><CODE>:key</CODE></B><DD><P>The argument <EM>string list</EM> defines the keyword of
the index entry. It must be a list of strings, since the keyword may
consist of different layers such as <CODE>("heap" "fibonacci")</CODE>.
<P>
<DT><B><CODE>:print</CODE></B><DD><P>The optional <EM>print key</EM> defines the way the
keyword has to be printed in the markup phase.
<P>
<DT><B><CODE>:tkey</CODE></B><DD><P>Another possibility to define the keys of an
index entry is with the <CODE>:tkey</CODE> keyword argument. It can be used
instead of the <CODE>:key</CODE> and <CODE>:print</CODE> 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
<P>
<PRE>
  :tkey (("This") ("is") ("a") ("bang" "BANG !!!"))
</PRE>
<P>is equivalent to
<P>
<PRE>
  :key   ("This" "is" "a" "bang")
  :print ("This" "is" "a" "BANG !!!")
</PRE>
<P>
<P>
<DT><B><CODE>:locref</CODE></B><DD><P>The reference an index entry describes can be a
<EM>location reference</EM> or a <EM>cross reference</EM>. The switch
<CODE>:locref</CODE> describes a location reference. Its optional arguments
are <CODE>:open-range</CODE> and <CODE>:close-range</CODE>. The <EM>string</EM> that must
be supplied must somehow encode the location reference. It might look
like the string <CODE>"25"</CODE> representing the page number 25, or
<CODE>"Appendix-I"</CODE> representing the first appendix numbered in
uppercase roman numerals.
<P>
<DT><B><CODE>:open-range</CODE>,<CODE>:close-range</CODE></B><DD><P>These are switches that do not
take any arguments. They describe the beginning and ending of a
<EM>range</EM>, starting or ending from the location reference that is
given by the argument <CODE>:locref</CODE>. If they are supplied, the
location reference may have influence on the way ranges are build.
<P>
<DT><B><CODE>:xref</CODE></B><DD><P>These arguments choose the second alternative. The
argument <EM>string list</EM> of parameter <CODE>:xref</CODE> describes where the
index entry should point to.
<P>
<DT><B><CODE>:attr</CODE></B><DD><P>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
<CODE>default</CODE>.
<P>
</DL>
<P>Some examples:
<P>
<PRE>
  (indexentry :key ("airplane") :locref "25" :attr "default")
</PRE>
<P>defines an index entry with the key `airplane' indexed on page '25'.
This index entry has the attribute <CODE>default</CODE>.
<P>
<PRE>
  (indexentry :key ("house") :xref ("building") :attr "see")
</PRE>
<P>defines a cross reference with the key 'house' pointing to the term
'building'. This cross reference belongs to the cross reference class
<CODE>see</CODE>.
<P>
<PRE>
  (indexentry :key ("house") :xref ("building") :open-range)
</PRE>
<P>is an invalid specification, since <CODE>:open-range</CODE> mustn't be used
together with cross references.
<P>
<P>
<P>
<HR>
<A HREF="manual-4.html">Next</A>
<A HREF="manual-2.html">Previous</A>
<A HREF="manual.html#toc3">Contents</A>
</BODY>
</HTML>