Debian Codegraph @

texmf-dist/doc/man/man1/makeindex.1

raw
1 .if t .ds LX L\\h'-0.36m'\\v'-0.15v'\\s-2A\\s+2\\h'-0.15m'\\v'0.15v'T\\h'-0.1667m'\\v'0.20v'E\\v'-0.20v'\\h'-0.125m'X
2 .if n .ds LX LaTeX
3 .if t .ds TX T\\h'-0.1667m'\\v'0.20v'E\\v'-0.20v'\\h'-0.125m'X
4 .if n .ds TX TeX
5 .ds Ts T\s-2RAN\s+2S\s-2CRIPT\s+2
6 .if t .ds Uc \fIU\\h'-0.12m'C\\v'0.27m'\\h'-.23m'S\\h'-0.11m'F\\v'-0.27m'\fP
7 .if n .ds Uc UCSF
8 .ds Et \\f(boE\\h'-0.1667m'\\v'-0.20v'T\\v'0.20v'\\h'-0.125m'T\\fP
9 .TH MAKEINDEX 1 "12 November 2014" "TeX Live" "TeX Live"
10 .\"=====================================================================
11 .SH NAME
12 makeindex \- a general purpose, formatter-independent index processor
13 .SH SYNOPSIS
14 .B makeindex
15 .RB [ \-c ]
16 .RB [ \-g ]
17 .RB [ \-i ]
18 .RB [ \-l ]
19 .RB [ \-o
20 .IR ind ]
21 .RB [ \-p
22 .IR num ]
23 .RB [ \-q ]
24 .RB [ \-r ]
25 .RB [ \-s
26 .IR sfile ]
27 .RB [ \-t
28 .IR log ]
29 .RB [ \-L ]
30 .RB [ \-T ]
31 .RI [ idx0
32 .I idx1
33 .IR idx2 .\|.\|.]
34 .\"=====================================================================
35 .SH DESCRIPTION
36 The program
37 .I makeindex
38 is a general purpose hierarchical index generator; it accepts one or
39 more input files (often produced by a text formatter such as \*(TX
40 .RI ( tex (1L))
41 or
42 .IR troff (1),
43 sorts the entries, and produces an output file which can be formatted.
44 The index can have up to three levels (0, 1, and 2) of subitem nesting.
45 The way in which words are flagged for indexing within the main document
46 is specific to the formatter used;
47 .I makeindex
48 does
49 .I not
50 automate the process of selecting these words. As the output index
51 is hierarchical,
52 .I makeindex
53 can be considered complementary to the
54 .IR awk (1)-based
55 .IR make.index (1L)
56 system of Bentley and Kernighan, which is specific to
57 .IR troff (1),
58 generates non-hierarchical indices, and employs a much simpler syntax
59 for indicating index entries. For illustration of use with
60 .I troff
61 and
62 .IR \*(TX ,
63 see the section \s-2EXAMPLES\s+2 below.
64 .LP
65 The formats of the input and output files are
66 specified in a style file; by default, input is assumed to be a
67 .I \&.idx
68 file, as generated by \*(LX.
69 .LP
70 Unless specified explicitly, the base name of the first input file
71 .RI ( idx0 )
72 is used to determine the names of other files. For each input file
73 name specified, a file of that name is sought. If this file is not
74 found and the file name has no extension, the extension
75 .I \&.idx
76 is appended. If no file with this name is found,
77 .I makeindex
78 aborts.
79 .LP
80 If exactly one input file was given and no explicit style file was
81 specified using
82 .BR \-s ,
83 .I makeindex
84 uses a file with the extension
85 .I \&.mst
86 as default style file (when present).
87 .LP
88 For important notes on how to select index keywords, see the document
89 by Lamport cited below. As an issue separate from selecting index
90 keywords, a systematic mechanism for placing index terms in a document
91 is suggested in
92 .IR "Index Preparation and Processing" ,
93 a paper cited below.
94 .\"=====================================================================
95 .SH OPTIONS
96 .TP 10
97 .B \-c
98 Compress intermediate blanks (ignoring leading and trailing blanks and
99 tabs). By default, blanks in the index key are retained.
100 .TP 10
101 .B \-g
102 Employ German word ordering in the index, in accord with rules set forth
103 in DIN 5007. By default,
104 .I makeindex
105 employs a word ordering in which precedence is: symbols, numbers,
106 uppercase letters, lowercase letters. The sequence in German word
107 ordering is: symbols, lowercase letters, uppercase letters, numbers.
108 Additionally, this option enables
109 .I makeindex
110 to recognize the German \*(TX-commands {"a, "o, "u and "s} as {ae, oe,
111 ue and ss} during the sorting of the entries. The quote character
112 must be redefined in a style file (for example, redefine quote
113 as '+'). If the quote character is not redefined,
114 .I makeindex
115 will produce an error message and abort.
116 .TP 10
117 .B \-i
118 Take input from
119 .IR stdin .
120 When this option is specified and
121 .B \-o
122 is not, output is written to
123 .IR stdout .
124 .TP 10
125 .B \-l
126 Letter ordering; by default, word ordering is used (see
127 the \s-2ORDERING\s+2 section).
128 .TP 10
129 .BI \-o " ind"
130 Employ
131 .I ind
132 as the output index file. By default, the file name
133 is created by appending the extension
134 .I .ind
135 to the base name of
136 the first input file
137 .RI ( idx0 ).
138 .TP 10
139 .BI \-p " num"
140 Set the starting page number of the output index file to be
141 .I num
142 (useful when the index file is to be formatted separately). The
143 argument
144 .I num
145 may be numerical or one of the following:
146 .RS
147 .TP 10
148 .I any
149 The starting page is the last source page number plus 1.
150 .TP
151 .I odd
152 The starting page is the first odd page following the last source page
153 number.
154 .TP
155 .I even
156 The starting page is the first even page following the last source
157 page number.
158 .RE
159 .IP
160 The last source page is obtained by searching backward in the log file
161 for the first instance of a number included within paired square
162 brackets
163 .RB ( [ .\|.\|. ] ).
164 If a page number is missing or the log file is not found, no attempt
165 will be made to set the starting page number. The source log file
166 name is determined by appending the extension
167 .I \&.log
168 to the base name of the first input file
169 .RI ( idx0 ).
170 .TP 10
171 .B \-q
172 Quiet mode; send no messages to
173 .IR stderr .
174 By default, progress
175 and error messages are sent to
176 .I stderr
177 as well as to the
178 transcript file.
179 .TP 10
180 .B \-r
181 Disable implicit page range formation; page ranges must be created by
182 using explicit range operators; see \s-2SPECIAL EFFECTS\s+2 below. By
183 default, three or more successive pages are automatically abbreviated
184 as a range (e.g. 1\(em5).
185 .TP 10
186 .BI \-s " sty"
187 Employ
188 .I sty
189 as the style file (no default). The environment
190 variable \s-2INDEXSTYLE\s+2 defines the path where the style file
191 should be found.
192 .TP 10
193 .BI \-t " log"
194 Employ
195 .I log
196 as the transcript file. By default, the file name is
197 created by appending the extension
198 .I .ilg
199 to the base name of the
200 first input file
201 .RI ( idx0 ).
202 .TP 10
203 .BR \-L
204 sort based on locale settings. Not available on all systems.
205 .TP 10
206 .BR \-T
207 special support for Thai documents. Not available on all systems.
208 .\"=====================================================================
209 .SH "STYLE FILE"
210 The style file informs
211 .I makeindex
212 about the format of the
213 .I \&.idx
214 input files and the intended format of the final output file; examples
215 appear below. This file can reside anywhere in the path defined by
216 the environment variable \s-2INDEXSTYLE\s+2. The style file contains
217 a list of
218 .RI < specifier , " attribute" >
219 pairs. There are two types of specifiers: input and output.
220 Pairs do not have to appear in any particular order.
221 A line begun by `%' is a comment. In the following list of
222 specifiers and arguments, <string> is an arbitrary string delimited by
223 double quotes (".\|.\|."), <char> is a single letter embraced by
224 single quotes ('.\|.\|.'), and <number> is a nonnegative integer.
225 The maximum length of a <string> is 2048. A literal backslash or
226 quote must be escaped (by a backslash). Anything not specified in the
227 style file will be assigned a default value, which is shown at the
228 head of the rightmost column.
229 .\"----------------------------------------------------------------------
230 .SS "INPUT STYLE SPECIFIERS"
231 .TP 25
232 .BR actual " <char>"
233 \'@\'
234 .RS
235 Symbol indicating that the next entry is to appear in the output file.
236 .RE
237 .TP
238 .BR arg_close " <char>"
239 \'}\'
240 .RS
241 Closing delimiter for the index entry argument.
242 .RE
243 .TP
244 .BR arg_open " <char>"
245 \'{\'
246 .RS
247 Opening delimiter for the index entry argument.
248 .RE
249 .TP
250 .BR encap " <char>"
251 \'|\'
252 .RS
253 Symbol indicating that the rest of the argument list
254 is to be used as the encapsulating command for the page number.
255 .RE
256 .TP
257 .BR escape " <char>"
258 \'\\\\\'
259 .RS
260 Symbol which escapes the following letter, unless its preceding letter
261 is
262 .BR escape .
263 Note:
264 .B quote
265 is used to escape the letter which immediately follows it, but if it is
266 preceded by
267 .BR escape ,
268 it is treated as a ordinary character. These two symbols
269 .I must
270 be distinct.
271 .RE
272 .TP
273 .BR keyword " <string>"
274 "\\\\indexentry"
275 .RS
276 Command which tells
277 .I makeindex
278 that its argument is an index entry.
279 .RE
280 .TP
281 .BR level " <char>"
282 \'!\'
283 .RS
284 Delimiter denoting a new level of subitem.
285 .RE
286 .TP
287 .BR page_compositor " <string>"
288 "-"
289 .RS
290 Delimiter separating parts of a composite page number (see
291 \s-2SPECIAL EFFECTS\s+2 below).
292 .RE
293 .TP
294 .BR quote " <char>"
295 \'"\'
296 .RS
297 Note:
298 .B quote
299 is used to escape the letter which immediately follows it, but if it is
300 preceded by
301 .BR escape ,
302 it is treated as a ordinary character. These two symbols
303 .I must
304 be distinct.
305 .RE
306 .TP
307 .BR range_close " <char>"
308 \')\'
309 .RS
310 Closing delimiter indicating the end of an explicit page range.
311 .RE
312 .TP
313 .BR range_open " <char>"
314 \'(\'
315 .RS
316 Opening delimiter indicating the beginning of an explicit page range.
317 .RE
318 .\"---------------------------------------------------------------------
319 .SS "OUTPUT STYLE SPECIFIERS"
320 .TP 25
321 .BR preamble " <string>"
322 "\\\\begin{theindex}\\n"
323 .RS
324 Preamble of output file.
325 .RE
326 .TP
327 .BR postamble " <string>"
328 "\\n\\n\\\\end{theindex}\\n"
329 .RS
330 Postamble of output file.
331 .RE
332 .TP
333 .BR setpage_prefix " <string>"
334 "\\n \\\\setcounter{page}{"
335 .RS
336 Prefix of command which sets the starting page number.
337 .RE
338 .TP
339 .BR setpage_suffix " <string>"
340 "}\\n"
341 .RS
342 Suffix of command which sets the starting page number.
343 .RE
344 .TP
345 .BR group_skip " <string>"
346 "\\n\\n \\\\indexspace\\n"
347 .RS
348 Vertical space to be inserted before a new group begins.
349 .RE
350 .TP
351 .BR headings_flag " <string>"
352 0
353 .RS
354 Flag indicating treatment of new group headers, which are inserted
355 when before a new group (symbols, numbers, and the 26 letters):
356 positive values cause an uppercase letter to be inserted between
357 prefix and suffix, and negative values cause a lowercase letter to be
358 inserted (default is 0, which produces no header).
359 .RE
360 .TP
361 .BR heading_prefix " <string>"
362 ""
363 .RS
364 Letter heading prefix to be inserted before a new letter begins.
365 .RE
366 .TP
367 .BR heading_suffix " <string>"
368 ""
369 .RS
370 Letter heading suffix to be inserted when a new letter begins.
371 .RE
372 .TP
373 .BR symhead_positive " <string>"
374 "Symbols"
375 .RS
376 Heading for symbols to be inserted if
377 .B headings_flag
378 is positive.
379 .RE
380 .TP
381 .BR symhead_negative " <string>"
382 "symbols"
383 .RS
384 Heading for symbols to be inserted if
385 .B headings_flag
386 is negative.
387 .RE
388 .TP
389 .BR numhead_positive " <string>"
390 "Numbers"
391 .RS
392 Heading for numbers to be inserted if
393 .B headings_flag
394 is positive.
395 .RE
396 .TP
397 .BR numhead_negative " <string>"
398 "numbers"
399 .RS
400 Heading for numbers to be inserted if
401 .B headings_flag
402 is negative.
403 .RE
404 .TP
405 .BR item_0 " <string>"
406 "\\n \\\\item "
407 .RS
408 Command to be inserted between two primary (level 0) items.
409 .RE
410 .TP
411 .BR item_1 " <string>"
412 "\\n \\\\subitem "
413 .RS
414 Command to be inserted between two secondary (level 1) items.
415 .RE
416 .TP
417 .BR item_2 " <string>"
418 "\\n \\\\subsubitem "
419 .RS
420 Command to be inserted between two level 2 items.
421 .RE
422 .TP
423 .B item_01 " <string>"
424 "\\n \\\\subitem "
425 .RS
426 Command to be inserted between a level 0 item and a level 1 item.
427 .RE
428 .TP
429 .BR item_x1 " <string>"
430 "\\n \\\\subitem "
431 .RS
432 Command to be inserted between a level 0 item and a level 1 item,
433 where the level 0 item does not have associated page numbers.
434 .RE
435 .TP
436 .BR item_12 " <string>"
437 "\\n \\\\subsubitem "
438 .RS
439 Command to be inserted between a level 1 item and a level 2 item.
440 .RE
441 .TP
442 .BR item_x2 " <string>"
443 "\\n \\\\subsubitem "
444 .RS
445 Command to be inserted between a level 1 item and a level 2 item,
446 where the level 1 item does not have associated page numbers.
447 .RE
448 .TP
449 .BR delim_0 " <string>"
450 ", "
451 .RS
452 Delimiter to be inserted between a level 0 key and its first page number
453 (default: comma followed by a blank).
454 .RE
455 .TP
456 .BR delim_1 " <string>"
457 ", "
458 .RS
459 Delimiter to be inserted between a level 1 key and its first page number
460 (default: comma followed by a blank).
461 .RE
462 .TP
463 .BR delim_2 " <string>"
464 ", "
465 .RS
466 Delimiter to be inserted between a level 2 key and its first page number
467 (default: comma followed by a blank).
468 .RE
469 .TP
470 .BR delim_n " <string>"
471 ", "
472 .RS
473 Delimiter to be inserted between two page numbers for the same key
474 in any level (default: comma followed by a blank).
475 .RE
476 .TP
477 .BR delim_r " <string>"
478 "--"
479 .RS
480 Delimiter to be inserted between the starting and ending page numbers
481 of a range.
482 .RE
483 .TP
484 .BR delim_t " <string>"
485 ""
486 .RS
487 Delimiter to be inserted at the end of a page list. This delimiter
488 has no effect on entries which have no associated page list.
489 .RE
490 .TP
491 .BR encap_prefix " <string>"
492 "\\\\"
493 .RS
494 First part of prefix for the command which encapsulates the page number.
495 .RE
496 .TP
497 .BR encap_infix " <string>"
498 "{"
499 .RS
500 Second part of prefix for the command which encapsulates the page
501 number.
502 .RE
503 .TP
504 .BR encap_suffix " <string>"
505 "}".
506 .RS
507 Suffix for the command which encapsulates the page number.
508 .RE
509 .TP
510 .BR page_precedence " <string>"
511 "rnaRA".
512 .RS
513 Page type precedence order. The default specifies: lowercase roman,
514 numeric/arabic, lowercase alphabetic, uppercase roman, uppercase alphabetic.
515 .RE
516 .TP
517 .BR line_max " <number>"
518 72
519 .RS
520 Maximum length of a line in the output, beyond which a line wraps.
521 .RE
522 .TP
523 .BR indent_space " <string>"
524 "\\t\\t"
525 .RS
526 Space to be inserted in front of a wrapped line (default: two tabs).
527 .RE
528 .TP
529 .BR indent_length " <number>"
530 16
531 .RS
532 Length of
533 .B indent_space
534 (default: 16, equivalent to 2 tabs).
535 .RE
536 .TP
537 .BR suffix_2p " <string>"
538 ""
539 .RS
540 Delimiter to replace the range delimiter and the second page number of
541 a two page list. When present, it overrides
542 .BR delim_r .
543 Example: "f.".
544 .RE
545 .TP
546 .BR suffix_3p " <string>"
547 ""
548 .RS
549 Delimiter to replace the range delimiter and the second page number of
550 a three page list. When present, it overrides
551 .B delim_r
552 and
553 .BR suffix_mp .
554 Example: "ff.".
555 .RE
556 .TP
557 .BR suffix_mp " <string>"
558 ""
559 .RS
560 Delimiter to replace the range delimiter and the second page number of
561 a multiple page list (three or more pages). When present, it overrides
562 .BR delim_r .
563 Example: "f.".
564 .RE
565 .\"=====================================================================
566 .SH EXAMPLES
567 .\"---------------------------------------------------------------------
568 .SS "\*(TX EXAMPLE"
569 The following example shows a style file called
570 .IR book.ist ,
571 which defines an index for a book which can be formatted independently
572 of the main source:
573 .LP
574 .RS
575 .nf
576 \fCpreamble
577 "\\\\documentstyle[12pt]{book}
578 \\\\begin{document}
579 \\\\begin{theindex}
580 {\\\\small\\n"
581 postamble
582 "\\n\\n}
583 \\\\end{theindex}
584 \\\\end{document}\\n\fP"
585 .fi
586 .RE
587 .LP
588 Assuming that a particular book style requires the index (as well as any
589 chapters) to start from an odd page number, and that the input file is
590 named
591 .IR foo.idx ,
592 the following command line produces output in file
593 .IR footmp.ind :
594 .LP
595 .RS
596 \fCmakeindex \-s book.ist \-o footmp.ind \-p odd foo\fP
597 .RE
598 .LP
599 Here a non-default output file name is used to avoid clobbering the
600 output for the book itself (presumably
601 .IR foo.dvi ,
602 which would have been the default name for the index output file!).
603 .\"---------------------------------------------------------------------
604 .SS "TROFF EXAMPLE"
605 A sample control file for creating an index, which we will assume
606 resides in the file
607 .IR sample.ist :
608 .LP
609 .RS
610 .nf
611 \&\fCkeyword "IX:"
612 \&preamble
613 \&".\\\\\\" start of index output
614 \&\\".\\\\\\" enter two column mode
615 \&.2C
616 \&.SH
617 \&.ce
618 \&INDEX
619 \&.XS
620 \&INDEX
621 \&.XE
622 \&.R
623 \&.ps 9p
624 \&.vs 11p
625 \&.sp
626 \&.de I1
627 \&.ti 0.25i
628 \&..
629 \&.de I2
630 \&.ti 0.5i
631 \&.."
632 \&postamble "\\n.\\\\\\" end of index output"
633 \&setpage_prefix "\\n.nr % "
634 \&setpage_suffix ""
635 \&group_skip "\\n.sp 1.0"
636 \&headings_flag 1
637 \&heading_prefix "\\n.IS\\n"
638 \&heading_suffix "\\n.IE"
639 \&item_0 "\\n.br\\n"
640 \&item_1 "\\n.I1\\n"
641 \&item_2 "\\n.I2\\n"
642 \&item_01 "\\n.I1\\n"
643 \&item_x1 "\\n.I1\\n"
644 \&item_12 "\\n.I2\\n"
645 \&item_x2 "\\n.I2\\n"
646 \&delim_0 ", "
647 \&delim_1 ", "
648 \&delim_2 ", "
649 \&delim_r "-"
650 \&delim_t "."
651 \&encap_prefix "\\\\fB"
652 \&encap_infix ""
653 \&encap_suffix "\\\\fP"
654 \&indent_space ""
655 \&indent_length 0\fP
656 .fi
657 .RE
658 .LP
659 The local macro package may require modification, as in this example
660 of an extension to the
661 .B \-ms
662 macros (note that at some sites, this macro should
663 .I replace
664 a pre-existing macro of the same name):
665 .LP
666 .RS
667 .nf
668 \fC\&.\" IX - index words to stderr
669 \&.de IX
670 \&.ie '\\\\n(.z'' .tm IX: \\\\$1 \\\\$2 \\\\$3 \\\\$4 \\\\$5 \\\\$6 \\\\$7 \\\\$8 \\\\$9 {\\\\n(PN}
671 \&.el \\\\!.IX \\\\$1 \\\\$2 \\\\$3 \\\\$4 \\\\$5 \\\\$6 \\\\$7 \\\\$8 \\\\$9 {\\\\n(PN}
672 \&..\fP
673 .fi
674 .RE
675 .LP
676 (note that the string {\fC\\\\n(PN\fP} is separated from the rest of the
677 line by a tab.
678 If your local macro package does not contain this extension,
679 just include those lines at the beginning of your file.
680 Here is a simple
681 .IR troff (1)
682 input file, which we will assume is named
683 .IR sample.txt :
684 .LP
685 .RS
686 .nf
687 \fC\&This is a sample file to test the \\fImakeindex\\fP(1L)
688 \&program, and see
689 \&.IX {indexing!programs!C language}
690 \&.IX {makeindex@\\fImakeindex\\fP(1L)}
691 \&.bp
692 \&.rs
693 \&.IX {Knuth}
694 \&.IX {typesetting!computer-aided}
695 \&how well it functions in the \\fItroff\\fP(1) environment.\fP
696 .fi
697 .RE
698 .LP
699 Note that index entries are indicated by the
700 .B .IX
701 macro, which
702 causes the following text to be written to
703 .I stdout
704 along with the
705 current page number.
706 .\"---------------------------------------------------------------------
707 .SS "CREATING THE INDEX FILE IN THE BOURNE SHELL"
708 To create an input file for
709 .IR makeindex ,
710 .B "in the Bourne shell"
711 environment, do the equivalent at your site of the command:
712 .LP
713 .nf
714 \fCpsroff -ms -Tpsc -t sample.txt > /dev/null 2> sample.tmp\fP
715 .fi
716 .LP
717 Some sites will require
718 .I ditroff
719 instead of
720 .IR psroff .
721 To filter out any genuine error messages, invoke
722 .IR grep (1):
723 .LP
724 .RS
725 \fCgrep '^IX: ' sample.tmp > sample.idx\fP
726 .RE
727 .\"---------------------------------------------------------------------
728 .SS "CREATING THE INDEX FILE USING \*(Uc ENHANCED TROFF/\*(Ts"
729 With \*(Uc Enhanced troff/\*(Ts, the
730 .B \-I
731 option of
732 .IR psroff (1L)
733 can produce both formatter output and an index file:
734 .LP
735 .RS
736 \fCpsroff -ms -I sample.inp -Tpsc sample.txt\fP
737 .RE
738 .LP
739 If it is wished to suppress the formatter output:
740 .RS
741 .LP
742 .nf
743 \fCpsroff -ms -I sample.inp -Tpsc -t sample.txt > /dev/null\fP
744 .fi
745 .RE
746 .\"---------------------------------------------------------------------
747 .SS "COMPLETING THE INDEX"
748 Any of the above procedures leaves the input for
749 .I makeindex
750 in
751 .IR sample.inp .
752 The next step is to invoke
753 .IR makeindex :
754 .LP
755 .RS
756 \fCmakeindex -s sample.ist sample.idx\fP
757 .RE
758 .LP
759 This leaves
760 .IR troff (1)-ready
761 output in the file
762 .IR sample.ind .
763 .\"=====================================================================
764 .SH "ORDERING"
765 By default,
766 .I makeindex
767 assumes
768 .IR "word ordering" ;
769 if the
770 .B \-l
771 option is in effect,
772 .I "letter ordering"
773 is used. In word ordering, a blank precedes any letter in the
774 alphabet, whereas in letter ordering, it does not count at all. This
775 is illustrated by the following example:
776 .LP
777 .RS
778 \fIword order letter order\fP
779 .br
780 sea lion seal
781 .br
782 seal sea lion
783 .RE
784 .LP
785 Numbers are always sorted in numeric order. For instance,
786 .LP
787 .RS
788 9 (nine), 123
789 .br
790 10 (ten), see Derek, Bo
791 .RE
792 .LP
793 Letters are first sorted without regard to case; when words are
794 identical, the uppercase version precedes its lowercase counterpart.
795 .LP
796 A special symbol is defined here to be any character not appearing in
797 the union of digits and the English alphabetic characters. Patterns
798 starting with special symbols precede numbers, which precede patterns
799 starting with letters. As a special case, a string starting with a
800 digit but mixed with non-digits is considered to be a pattern starting
801 with a special character.
802 .\"=====================================================================
803 .SH "SPECIAL EFFECTS"
804 Entries such as
805 .LP
806 .RS
807 .nf
808 \fC\\indexentry{alpha}{1}
809 \\indexentry{alpha!beta}{3}
810 \\indexentry{alpha!beta!gamma}{10}\fP
811 .fi
812 .RE
813 .LP
814 in the input file will be converted to
815 .LP
816 .RS
817 .nf
818 \fC\\item alpha, 1
819 \0\0\0\\subitem beta, 3
820 \0\0\0\0\0\0\\subsubitem gamma, 10\fP
821 .fi
822 .RE
823 .LP
824 in the output index file.
825 Notice that the
826 .B level
827 symbol (`!') is used above to delimit
828 hierarchical levels.
829 .LP
830 It is possible to make an item appear in a designated form by
831 using the
832 .B actual
833 (`@') operator. For instance,
834 .LP
835 .RS
836 \fC\\indexentry{alpha@{\\it alpha\\/}}{1}\fP
837 .RE
838 .LP
839 will become
840 .LP
841 .RS
842 \fC\\item {\\it alpha\\/}, 1\fP
843 .RE
844 .LP
845 after processing. The pattern preceding `@' is
846 used as sort key, whereas the one following it is written to the
847 output file. Note that two appearances of the same key, one with and
848 one without the
849 .B actual
850 operator, are regarded as
851 .I distinct
852 entries.
853 .LP
854 The item, subitem, and subsubitem fields may have individual sort keys:
855 .LP
856 .RS
857 .nf
858 \fC\\indexentry{aa@{\\it aa\\/}!bb@{\\it bb\\/}!cc@{\\it cc\\/}}{1}\fP
859 .fi
860 .RE
861 .LP
862 This will be converted to
863 .LP
864 .RS
865 .nf
866 \fC\\item {\\it aa}, 1
867 \0\0\0\\subitem {\\it bb}, 3
868 \0\0\0\0\0\0\\subsubitem {\\it cc}, 10\fP
869 .fi
870 .RE
871 .LP
872 It is possible to encapsulate a page number with a designated
873 command using the
874 .B encap
875 (`|') operator:
876 .LP
877 .RS
878 \fC\\indexentry{alpha|bold}{1}\fP
879 .RE
880 .LP
881 will be converted to
882 .LP
883 .RS
884 \fC\\item alpha, \\bold{1}\fP
885 .RE
886 .LP
887 where, with a suitable definition for \*(TX, \fC\\bold{n}\fP
888 will expand to \fC{\\bf n}\fP.
889 In this example, the three output attributes associated with page
890 encapsulation
891 .BR encap_prefix ,
892 .BR encap_infix ,
893 and
894 .BR encap_suffix ,
895 correspond to backslash, left brace, and right brace, respectively.
896 This mechanism allows page numbers to be set in different fonts. For
897 example, the page where the definition of a keyword appears can be in
898 one font, the location of a primary example can be in another font,
899 and other appearances in yet a third font.
900 .LP
901 The
902 .B encap
903 operator can also be used to create cross references in
904 the index:
905 .LP
906 .RS
907 \fC\\indexentry{alpha|see{beta}}{1}\fP
908 .RE
909 .LP
910 will become
911 .LP
912 .RS
913 \fC\\item alpha, \\see{beta}{1}\fP
914 .RE
915 .LP
916 in the output file, where
917 .LP
918 .RS
919 \fC\\see{beta}{1}\fP
920 .RE
921 .LP
922 will expand to
923 .LP
924 .RS
925 \fC{\\it see\\/} beta\fP
926 .RE
927 .LP
928 Note that in a cross reference like this the page number disappears.
929 .LP
930 A pair of
931 .B encap
932 concatenated with
933 .B range_open
934 (`|(') and
935 .B range_close
936 (`|)') creates an explicit page range:
937 .LP
938 .RS
939 .nf
940 \fC\\indexentry{alpha|(}{1}
941 \\indexentry{alpha|)}{5}\fP
942 .fi
943 .RE
944 .LP
945 will become
946 .LP
947 .RS
948 \fC\\item alpha, 1\(em5\fP
949 .RE
950 .LP
951 Intermediate pages indexed by the same key will be merged into the
952 range implicitly. This is especially useful when an entire section
953 about a particular subject is to be indexed, in which case only the
954 range opening and closing operators need to be inserted at the
955 beginning and end of the section. Explicit page range formation can
956 also include an extra command to set the page range in a designated
957 font:
958 .LP
959 .RS
960 .nf
961 \fC\\indexentry{alpha|(bold}{1}
962 \\indexentry{alpha|)}{5}\fP
963 .fi
964 .RE
965 .LP
966 will become
967 .LP
968 .RS
969 \fC\\item alpha, \\bold{1--5}\fP
970 .RE
971 .LP
972 Several potential problems are worth mentioning. First, entries like
973 .LP
974 .RS
975 .nf
976 \fC\\indexentry{alpha|(}{1}
977 \\indexentry{alpha|bold}{3}
978 \\indexentry{alpha|)}{5}\fP
979 .fi
980 .RE
981 .LP
982 will be interpreted as
983 .LP
984 .RS
985 \fC\\item alpha, \\bold{3}, 1--5\fP
986 .RE
987 .LP
988 but with a warning message in the transcript about encountering an
989 inconsistent page encapsulator.
990 An explicit range beginning in a Roman page number and ending
991 in Arabic is also considered an error. In this instance, (if
992 possible) the range is broken into two subranges, one in Roman and the
993 other in Arabic. For instance,
994 .LP
995 .RS
996 .nf
997 \fC\\indexentry{alpha|(}{i}
998 \\indexentry{alpha}{iv}
999 \\indexentry{alpha}{3}
1000 \\indexentry{alpha|)}{7}\fP
1001 .fi
1002 .RE
1003 .LP
1004 will be turned into
1005 .LP
1006 .RS
1007 \fC\\item alpha, i--iv, 3--7\fP
1008 .RE
1009 .LP
1010 with a warning message in the transcript file complaining about an
1011 illegal range formation.
1012 .LP
1013 Every special symbol mentioned in this section may be
1014 escaped by the
1015 .B quote
1016 operator (`"'). Thus
1017 .LP
1018 .RS
1019 \fC\\indexentry{alpha"@beta}{1}\fP
1020 .RE
1021 .LP
1022 will actually become
1023 .LP
1024 .RS
1025 \fC\\item alpha@beta, 1\fP
1026 .RE
1027 .LP
1028 as a result of executing
1029 .IR makeindex .
1030 The quoting power of
1031 .B quote
1032 is eliminated if it is immediately preceded
1033 by
1034 .B escape
1035 (`\\'). For example,
1036 .LP
1037 .RS
1038 \fC\\indexentry{f\\"ur}{1}\fP
1039 .RE
1040 .LP
1041 becomes
1042 .LP
1043 .RS
1044 \fC\\item f\\"ur, 1\fP
1045 .RE
1046 .LP
1047 which represents an umlaut-accented `u' to the \*(TX family of
1048 processors.
1049 .LP
1050 A page number can be a composite of one or more fields
1051 separated by the delimiter bound to
1052 .B page_compositor
1053 (`-'), e.g., II-12 for page 12 of Chapter II. Page numbers may
1054 contain up to ten fields.
1055 .PP
1056 Since version 2.11 of
1057 .IR makeindex ,
1058 the
1059 .B quote
1060 operator may quote
1061 .I any
1062 character in the range 1 .\|.\|. 255. Character 0 is excluded because
1063 it is used internally in the
1064 .I makeindex
1065 source code as a string terminator. With this change, sort keys can
1066 be created for all eight-bit characters except 0. The sorting order
1067 is
1068 .RS
1069 .nf
1070
1071 punctuation characters (in ASCII order),
1072 digits,
1073 control characters (1 .\|.\|. 31),
1074 space (32),
1075 letters (ignoring case),
1076 characters 127 .\|.\|. 255.
1077
1078 .fi
1079 .RE
1080 Here is an example showing the indexing of all printable ASCII
1081 characters other than letters and digits, assuming the default
1082 \*(TX format. For convenience, the page number references are
1083 the corresponding ASCII ordinal values.
1084 .RS
1085 .nf
1086
1087 \fC\\indexentry{" @" (space)}{32}
1088 \\indexentry{"!@"! (exclamation point)}{33}
1089 \\indexentry{""@"" (quotation mark)}{34}
1090 \\indexentry{"#@"\\# (sharp sign)}{35}
1091 \\indexentry{"$@"\\$ (dollar sign)}{36}
1092 \\indexentry{"%@"\\% (percent sign)}{37}
1093 \\indexentry{"&@"\\& (ampersand)}{38}
1094 \\indexentry{"<@"$<$ (left angle bracket)}{60}
1095 \\indexentry{"=@"= (equals)}{61}
1096 \\indexentry{">@"$>$ (right angle bracket)}{62}
1097 \\indexentry{"?@"? (query)}{63}
1098 \\indexentry{"@@"@ (at sign)}{64}
1099 \\indexentry{"[@"[ (left square bracket)}{91}
1100 \\indexentry{"\\@"\\verb=\\= (backslash)}{92}
1101 \\indexentry{"]@"] (right square bracket)}{93}
1102 \\indexentry{"^@"\\verb=^= (caret)}{94}
1103 \\indexentry{"_@"\\verb=_= (underscore)}{95}
1104 \\indexentry{"`@"\\verb=~= (grave accent)}{96}
1105 \\indexentry{"{@"\\"{ (left brace)}{123}
1106 \\indexentry{"|@"\\verb="|= (vertical bar)}{124}
1107 \\indexentry{"}@"\\"} (right brace)}{125}
1108 \\indexentry{"~@"\\verb=~= (tilde)}{126}\fP
1109
1110 .fi
1111 .RE
1112 Characters in the actual fields following the `@' character which
1113 have special significance to \*(TX must be represented as control
1114 sequences, or as math mode characters. Note particularly how the
1115 entries for the at sign, left and right braces, and the vertical
1116 bar, are coded. The index file output by
1117 .I makeindex
1118 for this example looks like this:
1119 .RS
1120 .nf
1121
1122 \fC\\begin{theindex}
1123
1124 \\item ! (exclamation point), 33
1125 \\item " (quotation mark), 34
1126 \\item \\# (sharp sign), 35
1127 \\item \\$ (dollar sign), 36
1128 \\item \\% (percent sign), 37
1129 \\item \\& (ampersand), 38
1130 \\item $<$ (left angle bracket), 60
1131 \\item = (equals), 61
1132 \\item $>$ (right angle bracket), 62
1133 \\item ? (query), 63
1134 \\item @ (at sign), 64
1135 \\item [ (left square bracket), 91
1136 \\item \\verb=\\= (backslash), 92
1137 \\item ] (right square bracket), 93
1138 \\item \\verb=^= (caret), 94
1139 \\item \\verb=_= (underscore), 95
1140 \\item \\verb=~= (grave accent), 96
1141 \\item \\{ (left brace), 123
1142 \\item \\verb=|= (vertical bar), 124
1143 \\item \\} (right brace), 125
1144 \\item \\verb=~= (tilde), 126
1145
1146 \\indexspace
1147
1148 \\item (space), 32
1149
1150 \\end{theindex}\fP
1151 .fi
1152 .RE
1153 .\"=====================================================================
1154 .SH "FILES"
1155 .TP 2.2i
1156 .I makeindex
1157 executable file
1158 .TP
1159 .I $TEXMFMAIN/tex/plain/makeindex/idxmac.tex
1160 \*(TX macro file used by
1161 .I makeindex
1162 .TP
1163 .I $TEXMFMAIN/tex/latex/base/makeidx.sty
1164 \*(TX macro file used by
1165 .I makeindex
1166 .\"=====================================================================
1167 .SH "SEE ALSO"
1168 ditroff(1L),
1169 latex(1L),
1170 make.index (1L),
1171 qsort(3),
1172 tex(1L),
1173 troff(1L)
1174 .LP
1175 .IR "\*(Uc Enhanced troff/\*(Ts \(em An Overview" ,
1176 R. P. C. Rodgers and Conrad Huang, LSMB Technical Report 90-2,
1177 UCSF School of Pharmacy, San Francisco, 1990.
1178 .LP
1179 .IR "Index Preparation and Processing" ,
1180 Pehong Chen and Michael A. Harrison,
1181 .IR "Software: Practice and Experience" ,
1182 .BR 19 (9),
1183 897\(en915,
1184 September 1988.
1185 .LP
1186 .IR "Automating Index Preparation" ,
1187 Pehong Chen and Michael A. Harrison. Technical Report 87/347,
1188 Computer Science Division, University of California, Berkeley, 1987
1189 (a \*(LX document supplied with
1190 .IR makeindex ).
1191 .LP
1192 .IR "MakeIndex: An Index Processor for \*(LX" ,
1193 Leslie Lamport, February 1987 (a \*(LX document supplied
1194 with
1195 .IR makeindex ).
1196 .LP
1197 .IR "Tools for Printing Indices" ,
1198 Jon L. Bentley and Brian W. Kernighan,
1199 .IR "Electronic Publishing \(em Origination, Dissemination, and Design" ,
1200 1(1), 3\(en18, June 1988 (also available as: Computing Science
1201 Technical Report No. 128,
1202 AT&T Bell Laboratories, Murray Hill, NJ 07974, 1986).
1203 .\"=====================================================================
1204 .SH "AUTHOR"
1205 Pehong Chen, Chen & Harrison International Systems, Inc.
1206 Palo Alto, California, USA.
1207 .br
1208 Manual page extensively revised and corrected, and
1209 .IR troff (1)
1210 examples created by Rick P. C. Rodgers, UCSF School
1211 of Pharmacy.
1212 .\"=====================================================================
1213 .SH ACKNOWLEDGMENTS
1214 Leslie Lamport contributed significantly to the design of MakeIndex.
1215 Michael Harrison provided valuable comments and suggestions.
1216 Nelson Beebe improved on the portable version, and maintained the
1217 source distribution for the \*(TX Users Group for many years.
1218 Andreas Brosig contributed to the German word ordering.
1219 The modification to the
1220 .B \-ms
1221 macros was derived from a method proposed by Ravi Sethi of AT&T
1222 Bell Laboratories.
1223 The
1224 .I LOG
1225 and
1226 .I CONTRIB
1227 files in the
1228 .I makeindex
1229 source distribution record other contributions.
1230 .PP
1231 .I makeindex
1232 is currently maintained as part of the \*(TX Live
1233 distribution (http://tug.org/texlive); please send bug reports to
1234 [email protected].