Penguin
Recent Changes
Blame: makeindex(1)
EditPageHistoryDiffInfoLikePages
Annotated edit history of makeindex(1) version 4, including all changes. View license author blame.
Rev Author # Line
2 perry 1 MAKEINDEX
2 !!!MAKEINDEX
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 OPTIONS
7 STYLE FILE
8 EXAMPLES
9 ORDERING
10 SPECIAL EFFECTS
11 FILES
12 SEE ALSO
13 AUTHOR
14 ACKNOWLEDGMENTS
15 ----
16 !!NAME
17
18
19 makeindex - a general purpose, formatter-independent index processor
20 !!SYNOPSIS
21
22
23 __makeindex [[__-c__] [[__-g__] [[__-i__] [[__-l__]
24 [[__-o ''ind''] __[[__-p ''num''] __[[__-q__]
25 [[__-r__] [[__-s ''sfile''] __[[__-t ''log'']
26 __[[__''idx0 idx1 idx2''...]
27 !!DESCRIPTION
28
29
30 The program ''makeindex'' is a general purpose
31 hierarchical index generator; it accepts one or more input
32 files (often produced by a text formatter such as TEX
33 (''tex''(1L)) or troff(1), sorts the entries, and
34 produces an output file which can be formatted. The index
35 can have up to three levels (0, 1, and 2) of subitem
36 nesting. The way in which words are flagged for indexing
37 within the main document is specific to the formatter used;
38 ''makeindex'' does ''not'' automate the process of
39 selecting these words. As the output index is hierarchical,
40 ''makeindex'' can be considered complimentary to the
41 awk(1)-based ''make.index''(1L) system of Bentley
42 and Kernighan, which is specific to troff(1),
43 generates non-hierarchical indices, and employs a much
44 simpler syntax for indicating index entries. For
45 illustration of use with ''troff'' and ''TEX'', see
46 the section EXAMPLES below.
47
48
49 The formats of the input and output files are specified in a
50 style file; by default, input is assumed to be a ''.idx''
51 file, as generated by L A TEX.
52
53
54 Unless specified explicitly, the base name of the first
55 input file (''idx0'') is used to determine the names of
56 other files. For each input file name specified, a file of
57 that name is sought. If this file is not found and the file
58 name has no extension, the extension ''.idx'' is
59 appended. If no file with this name is found,
60 ''makeindex'' aborts.
61
62
63 If exactly one input file was given and no explicit style
64 file was specified using __-s__, ''makeindex'' uses a
65 file with the extension ''.mst'' as default style file
66 (when present).
67
68
69 For important notes on how to select index keywords, see the
70 document by Lamport cited below. As an issue separate from
71 selecting index keywords, a systematic mechanism for placing
72 index terms in a document is suggested in ''Index
73 Preparation and Processing'', a paper cited
74 below.
75 !!OPTIONS
76
77
78 __-c__ Compress intermediate blanks (ignoring leading and
79 trailing blanks and tabs). By default, blanks in the index
80 key are retained.
81
82
83 __-g__ Employ German word ordering in the index, in
84 accord with rules set forth in DIN 5007. By default,
85 ''makeindex'' employs a word ordering in which precedence
86 is: symbols, numbers, uppercase letters, lowercase letters.
87 The sequence in German word ordering is: symbols, lowercase
88 letters, uppercase letters, numbers. Additionally, this
89 option enables ''makeindex'' to recognize the German
90 TEX-commands {
91 ''makeindex'' will produce an error message
92 and abort.
93
94
95 __-i__ Take input from ''stdin''. When this option is
96 specified and __-o__ is not, output is written to
97 ''stdout''.
98
99
100 __-l__ Letter ordering; by default, word ordering is used
101 (see the ORDERING section).
102
103
104 __-o__ ''ind''
105
106
107 Employ ''ind'' as the output index file. By default, the
108 file name is created by appending the extension ''.ind''
109 to the base name of the first input file
110 (''idx0'').
111
112
113 __-p__ ''num''
114
115
116 Set the starting page number of the output index file to be
117 ''num'' (useful when the index file is to be formatted
118 separately). The argument ''num'' may be numerical or one
119 of the following:
120
121
122 ''any''
123
124
125 The starting page is the last source page number plus
126 1.
127
128
129 ''odd''
130
131
132 The starting page is the first odd page following the last
133 source page number.
134
135
136 ''even''
137
138
139 The starting page is the first even page following the last
140 source page number.
141
142
143 The last source page is obtained by searching backward in
144 the log file for the first instance of a number included
145 within paired square brackets (__[[__...__]__). If a
146 page number is missing or the log file is not found, no
147 attempt will be made to set the starting page number. The
148 source log file name is determined by appending the
149 extension ''.log'' to the base name of the first input
150 file (''idx0'').
151
152
153 __-q__ Quiet mode; send no messages to ''stderr''. By
154 default, progress and error messages are sent to
155 ''stderr'' as well as to the transcript
156 file.
157
158
159 __-r__ Disable implicit page range formation; page ranges
160 must be created by using explicit range operators; see
161 SPECIAL EFFECTS below. By default, three or
162 more successive pages are automatically abbreviated as a
163 range (e.g. 1--5).
164
165
166 __-s__ sty
167
168
169 Employ ''sty'' as the style file (no default). The
170 environment variable INDEXSTYLE defines the
171 path where the style file should be found.
172
173
174 __-t__ log
175
176
177 Employ ''log'' as the transcript file. By default, the
178 file name is created by appending the extension ''.ilg''
179 to the base name of the first input file
180 (''idx0'').
181 !!STYLE FILE
182
183
184 The style file informs ''makeindex'' about the format of
185 the ''.idx'' input files and the intended format of the
186 final output file; examples appear below. This file can
187 reside anywhere in the path defined by the environment
188 variable INDEXSTYLE . The style file contains
189 a list of specifier'', ''attribute''
190 ''
191
192
193 __INPUT STYLE SPECIFIERS__
194
195
196 __actual__ __
197
198
199 Symbol indicating that the next entry is to appear in the
200 output file.
201
202
203 __arg_close__ __
204
205
206 Closing delimiter for the index entry argument.
207
208
209 __arg_open__ __
210
211
212 Opening delimiter for the index entry argument.
213
214
215 __encap__ __
216
217
218 Symbol indicating that the rest of the argument list is to
219 be used as the encapsulating command for the page
220 number.
221
222
223 __escape__ __
224
225
226 Symbol which escapes the following letter, unless its
227 preceding letter is __escape__. Note: __quote__ is
228 used to escape the letter which immediately follows it, but
229 if it is preceded by __escape__, it is treated as a
230 ordinary character. These two symbols ''must'' be
231 distinct.
232
233
234 __keyword__
235 __
236
237
238 Command which tells ''makeindex'' that its argument is an
239 index entry.
240
241
242 __level__ __
243
244
245 Delimiter denoting a new level of subitem.
246
247
248 __quote__ __
249
250
251 Note: __quote__ is used to escape the letter which
252 immediately follows it, but if it is preceded by
253 __escape__, it is treated as a ordinary character. These
254 two symbols ''must'' be distinct.
255
256
257 __range_close__ __
258
259
260 )
261 Closing delimiter indicating the end of an explicit page
262 range.
263
264
265 __range_open__ __
266
267
268 Opening delimiter indicating the beginning of an explicit
269 page range.
270
271
272 __OUTPUT STYLE SPECIFIERS__
273
274
275 __preamble__
276 __
277
278
279 Preamble of output file.
280
281
282 __postamble__ __
283
284
285 Postamble of output file.
286
287
288 __setpage_prefix__ __
289
290
291 Prefix of command which sets the starting page
292 number.
293
294
295 __setpage_suffix__ __
296
297
298 Suffix of command which sets the starting page
299 number.
300
301
302 __group_skip__ __
303
304
305 Vertical space to be inserted before a new group
306 begins.
307
308
309 __headings_flag__ __
310
311
312 0
313 Flag indicating treatment of new group headers, which are
314 inserted when before a new group (symbols, numbers, and the
315 26 letters): positive values cause an uppercase letter to be
316 inserted between prefix and suffix, and negative values
317 cause a lowercase letter to be inserted (default is 0, which
318 produces no header).
319
320
321 __heading_prefix__ __
322
323
324 Header prefix to be inserted before a new letter
325 begins.
326
327
328 __symhead_positive__ __
329
330
331 Heading for symbols to be inserted if __headings_flag__
332 is positive.
333
334
335 __symhead_negative__ __
336
337
338 Heading for symbols to be inserted if __headings_flag__
339 is negative.
340
341
342 __numhead_positive__ __
343
344
345 Heading for numbers to be inserted if __headings_flag__
346 is positive.
347
348
349 __numhead_negative__ __
350
351
352 Heading for numbers to be inserted if __headings_flag__
353 is negative.
354
355
356 __item_0__
357 __
358
359
360 Command to be inserted between two primary (level 0)
361 items.
362
363
364 __item_1__
365 __
366
367
368 Command to be inserted between two secondary (level 1)
369 items.
370
371
372 __item_2__
373 __
374
375
376 Command to be inserted between two level 2
377 items.
378
379
380 __item_01 __
381 __
382
383
384 Command to be inserted between a level 0 item and a level 1
385 item.
386
387
388 __item_x1__
389 __
390
391
392 Command to be inserted between a level 0 item and a level 1
393 item, where the level 0 item does not have associated page
394 numbers.
395
396
397 __item_12__
398 __
399
400
401 Command to be inserted between a level 1 item and a level 2
402 item.
403
404
405 __item_x2__
406 __
407
408
409 Command to be inserted between a level 1 item and a level 2
410 item, where the level 1 item does not have associated page
411 numbers.
412
413
414 __delim_0__ __
415
416
417 Delimiter to be inserted between a level 0 key and its first
418 page number (default: comma followed by a
419 blank).
420
421
422 __delim_1__ __
423
424
425 Delimiter to be inserted between a level 1 key and its first
426 page number (default: comma followed by a
427 blank).
428
429
430 __delim_2__ __
431
432
433 Delimiter to be inserted between a level 2 key and its first
434 page number (default: comma followed by a
435 blank).
436
437
438 __delim_n__ __
439
440
441 Delimiter to be inserted between two page numbers for the
442 same key in any level (default: comma followed by a
443 blank).
444
445
446 __delim_r__ __
447
448
449 Delimiter to be inserted between the starting and ending
450 page numbers of a range.
451
452
453 __delim_t__ __
454
455
456 Delimiter to be inserted at the end of a page list. This
457 delimiter has no effect on entries which have no associated
458 page list.
459
460
461 __encap_prefix__ __
462
463
464 First part of prefix for the command which encapsulates the
465 page number.
466
467
468 __encap_infix__ __
469
470
471 Second part of prefix for the command which encapsulates the
472 page number.
473
474
475 __encap_suffix__ __
476
477
478 Suffix for the command which encapsulates the page
479 number.
480
481
482 __line_max__ __
483
484
485 Maximum length of a line in the output, beyond which a line
486 wraps.
487
488
489 __indent_space__ __
490
491
492 Space to be inserted in front of a wrapped line (default:
493 two tabs).
494
495
496 __indent_length__ __
497
498
499 16
500 Length of __indent_space__ (default: 16, equivalent to 2
501 tabs).
502
503
504 __suffix_2p__ __
505
506
507 Delimiter to replace the range delimiter and the second page
508 number of a two page list. When present, it overrides
509 __delim_r__. Example: __
510
511
512 __suffix_3p__ __
513
514
515 Delimiter to replace the range delimiter and the second page
516 number of a three page list. When present, it overrides
517 __delim_r__ and __suffix_mp__. Example:
518 __
519
520
521 __suffix_mp__ __
522
523
524 Delimiter to replace the range delimiter and the second page
525 number of a multiple page list (three or more pages). When
526 present, it overrides __delim_r__. Example:
527 __
528 !!EXAMPLES
529
530
531 __TEX EXAMPLE__
532
533
534 The following example shows a style file called
535 ''book.ist'', which defines an index for a book which can
536 be formatted independently of the main source:
537
538
539 preamble
540
541
542 Assuming that a particular book style requires the index (as
543 well as any chapters) to start from an odd page number, and
544 that the input file is named ''foo.idx'', the following
545 command line produces output in file
546 ''footmp.ind'':
547
548
549 makeindex -s book.ist -o footmp.ind -p odd
550 foo
551
552
553 Here a non-default output file name is used to avoid
554 clobbering the output for the book itself (presumably
555 ''foo.dvi'', which would have been the default name for
556 the index output file!).
557
558
559 __TROFF EXAMPLE__
560
561
562 A sample control file for creating an index, which we will
563 assume resides in the file ''sample.ist'':
564
565
566 keyword
567
568
569 The local macro package may require modification, as in this
570 example of an extension to the __-ms__ macros (note that
571 at some sites, this macro should ''replace'' a
572 pre-existing macro of the same name):
573
574
575 .
576 .de IX
577 .ie '\n(.z'' .tm IX: \$1 \$2 \$3 \$4 \$5 \$6 \$7 \$8 \$9 {\n(PN}
578 .el \!.IX \$1 \$2 \$3 \$4 \$5 \$6 \$7 \$8 \$9 {\n(PN}
579 ..
580
581
582 (note that the string {\n(PN} is separated from the
583 rest of the line by a tab. If your local macro package does
584 not contain this extension, just include those lines at the
585 beginning of your file. Here is a simple troff(1)
586 input file, which we will assume is named
587 ''sample.txt'':
588
589
590 This is a sample file to test the fImakeindexfP(1L)
591 program, and see
592 .IX {indexing!programs!C language}
593 .IX {makeindex@fImakeindexfP(1L)}
594 .bp
595 .rs
596 .IX {Knuth}
597 .IX {typesetting!computer-aided}
598 how well it functions in the fItrofffP(1) environment.
599
600
601 Note that index entries are indicated by the __.IX__
602 macro, which causes the following text to be written to
603 ''stdout'' along with the current page
604 number.
605
606
607 __CREATING THE INDEX FILE IN THE BOURNE
608 SHELL__
609
610
611 To create an input file for ''makeindex'', __in the
612 Bourne shell__ environment, do the equivalent at your site
613 of the command:
614
615
616 psroff -ms -Tpsc -t sample.txt
617 Some sites will require ''ditroff'' instead of ''psroff''. To filter out any genuine error messages, invoke grep(1):
618
619
620 grep '^IX: ' sample.tmp
621
622
623 __CREATING THE INDEX FILE USING__ ''UCSF'' __ENHANCED
624 TROFF/T RAN S
625 CRIPT__
626
627
628 With ''UCSF'' Enhanced troff/T RAN S
629 CRIPT , the __-I__ option of
630 ''psroff''(1L) can produce both formatter output and an
631 index file:
632
633
634 psroff -ms -I sample.inp -Tpsc
635 sample.txt
636
637
638 If it is wished to suppress the formatter
639 output:
640
641
642 psroff -ms -I sample.inp -Tpsc -t sample.txt
643
644
645 __COMPLETING THE INDEX__
646
647
648 Any of the above procedures leaves the input for
649 ''makeindex'' in ''sample.inp''. The next step is to
650 invoke ''makeindex'':
651
652
653 makeindex -s sample.ist sample.idx
654
655
656 This leaves troff(1)-ready output in the file
657 ''sample.ind''.
658 !!ORDERING
659
660
661 By default, ''makeindex'' assumes ''word ordering'';
662 if the __-l__ option is in effect, ''letter ordering''
663 is used. In word ordering, a blank precedes any letter in
664 the alphabet, whereas in letter ordering, it does not count
665 at all. This is illustrated by the following
666 example:
667
668
669 ''word order letter order''
670 sea lion seal
671 seal sea lion
672
673
674 Numbers are always sorted in numeric order. For
675 instance,
676
677
678 9 (nine), 123
679 10 (ten), see Derek, Bo
680
681
682 Letters are first sorted without regard to case; when words
683 are identical, the uppercase version precedes its lowercase
684 counterpart.
685
686
687 A special symbol is defined here to be any character not
688 appearing in the union of digits and the English alphabetic
689 characters. Patterns starting with special symbols precede
690 numbers, which precede patterns starting with letters. As a
691 special case, a string starting with a digit but mixed with
692 non-digits is considered to be a pattern starting with a
693 special character.
694 !!SPECIAL EFFECTS
695
696
697 Entries such as
698
699
700 indexentry{alpha}{1}
701 indexentry{alpha!beta}{3}
702 indexentry{alpha!beta!gamma}{10}
703
704
705 in the input file will be converted to
706
707
708 item alpha, 1
709 subitem beta, 3
710 subsubitem gamma, 10
711
712
713 in the output index file. Notice that the __level__
714 symbol (`!') is used above to delimit hierarchical
715 levels.
716
717
718 It is possible to make an item appear in a designated form
719 by using the __actual__ (`@') operator. For
720 instance,
721
722
723 indexentry{alpha@{it alpha/}}{1}
724
725
726 will become
727
728
729 item {it alpha/}, 1
730
731
732 after processing. The pattern preceding `@' is used as sort
733 key, whereas the one following it is written to the output
734 file. Note that two appearances of the same key, one with
735 and one without the __actual__ operator, are regarded as
736 ''distinct'' entries.
737
738
739 The item, subitem, and subsubitem fields may have individual
740 sort keys:
741
742
743 indexentry{aa@{it aa/}!bb@{it bb/}!cc@{it cc/}}{1}
744
745
746 This will be converted to
747
748
749 item {it aa}, 1
750 subitem {it bb}, 3
751 subsubitem {it cc}, 10
752
753
754 It is possible to encapsulate a page number with a
755 designated command using the __encap__ (`|')
756 operator:
757
758
759 indexentry{alpha|bold}{1}
760
761
762 will be converted to
763
764
765 item alpha, bold{1}
766
767
768 where, with a suitable definition for TEX, bold{n}
769 will expand to {bf n}. In this example, the three
770 output attributes associated with page encapsulation
771 __encap_prefix__, __encap_infix__, and
772 __encap_suffix__, correspond to backslash, left brace,
773 and right brace, respectively. This mechanism allows page
774 numbers to be set in different fonts. For example, the page
775 where the definition of a keyword appears can be in one
776 font, the location of a primary example can be in another
777 font, and other appearances in yet a third
778 font.
779
780
781 The __encap__ operator can also be used to create cross
782 references in the index:
783
784
785 indexentry{alpha|see{beta}}{1}
786
787
788 will become
789
790
791 item alpha, see{beta}{1}
792
793
794 in the output file, where
795
796
797 see{beta}{1}
798
799
800 will expand to
801
802
803 {it see/} beta
804
805
806 Note that in a cross reference like this the page number
807 disappears.
808
809
810 A pair of __encap__ concatenated with __range_open__
811 (`|(') and __range_close__ (`|)') creates an explicit
812 page range:
813
814
815 indexentry{alpha|(}{1}
816 indexentry{alpha|)}{5}
817
818
819 will become
820
821
822 item alpha, 1--5
823
824
825 Intermediate pages indexed by the same key will be merged
826 into the range implicitly. This is especially useful when an
827 entire section about a particular subject is to be indexed,
828 in which case only the range opening and closing operators
829 need to be inserted at the beginning and end of the section.
830 Explicit page range formation can also include an extra
831 command to set the page range in a designated
832 font:
833
834
835 indexentry{alpha|(bold}{1}
836 indexentry{alpha|)}{5}
837
838
839 will become
840
841
842 item alpha, bold{1--5}
843
844
845 Several potential problems are worth mentioning. First,
846 entries like
847
848
849 indexentry{alpha|(}{1}
850 indexentry{alpha|bold}{3}
851 indexentry{alpha|)}{5}
852
853
854 will be interpreted as
855
856
857 item alpha, bold{3}, 1--5
858
859
860 but with a warning message in the transcript about
861 encountering an inconsistent page encapsulator. An explicit
862 range beginning in a Roman page number and ending in Arabic
863 is also considered an error. In this instance, (if possible)
864 the range is broken into two subranges, one in Roman and the
865 other in Arabic. For instance,
866
867
868 indexentry{alpha|(}{i}
869 indexentry{alpha}{iv}
870 indexentry{alpha}{3}
871 indexentry{alpha|)}{7}
872
873
874 will be turned into
875
876
877 item alpha, i--iv, 3--7
878
879
880 with a warning message in the transcript file complaining
881 about an illegal range formation.
882
883
884 Finally, every special symbol mentioned in this section may
885 be escaped by the __quote__ operator (`
886 __
887
888
889 indexentry{alpha
890
891
892 will actually become
893
894
895 item alpha@beta, 1
896
897
898 as a result of executing ''makeindex''. The quoting power
899 of __quote__ is eliminated if it is immediately preceded
900 by __escape__ (`'). For example,
901
902
903 indexentry{f
904
905
906 becomes
907
908
909 item f
910
911
912 which represents an umlaut-accented `u' to the TEX family of
913 processors.
914
915
916 From version 2.11 of ''makeindex'', the __quote__
917 operator may quote ''any'' character in the range 1 ...
918 255. Character 0 is excluded because it is used internally
919 in the ''makeindex'' source code as a string terminator.
920 With this change, sort keys can be created for all eight-bit
921 characters except 0. The sorting order is
922
923
924 punctuation characters (in ASCII order),
925 digits,
926 control characters (1 ... 31),
927 space (32),
928 letters (ignoring case),
929 characters 127 ... 255.
930
931
932 Here is an example showing the indexing of all printable
933 ASCII characters other than letters and digits, assuming the
934 default TEX format. For convenience, the page number
935 references are the corresponding ASCII ordinal
936 values.
937
938
939 indexentry{
940
941
942 Characters in the actual fields following the `@' character
943 which have special significance to TEX must be represented
944 as control sequences, or as math mode characters. Note
945 particularly how the entries for the at sign, left and right
946 braces, and the vertical bar, are coded. The index file
947 output by ''makeindex'' for this example looks like
948 this:
949
950
951 begin{theindex}
952 item ! (exclamation point), 33
953 item
954 !!FILES
955
956
957 ''makeindex'' executable file
958
959
960 ''$TEXMFMAIN/tex/plain/misc/idxmac.tex''
961
962
963 TEX macro file used by ''makeindex''
964
965
966 ''$TEXMFMAIN/tex/latex/base/makeidx.sty''
967
968
969 TEX macro file used by ''makeindex''
970 !!SEE ALSO
971
972
973 ditroff(1L), latex(1L), make.index (1L), qsort(3), tex(1L),
974 troff(1L)
975
976
977 ''UCSF Enhanced troff/T RAN S
978 CRIPT -- An Overview'', R. P. C. Rodgers
979 and Conrad Huang, LSMB Technical Report 90-2, UCSF School of
980 Pharmacy, San Francisco, 1990.
981
982
983 ''Index Preparation and Processing'', Pehong Chen and
984 Michael A. Harrison, ''Software: Practice and
4 AristotlePagaltzis 985 Experience'', !19(9), 897-915, September
2 perry 986 1988.
987
988
989 ''Automating Index Preparation'', Pehong Chen and Michael
990 A. Harrison. Technical Report 87/347, Computer Science
991 Division, University of California, Berkeley, 1987 (a L
992 A TEX document supplied with
993 ''makeindex'').
994
995
996 ''!MakeIndex: An Index Processor for L A
997 TEX'', Leslie Lamport, February 1987 (a L A
998 TEX document supplied with ''makeindex'').
999
1000
1001 ''Tools for Printing Indices'', Jon L. Bentley and Brian
1002 W. Kernighan, ''Electronic Publishing -- Origination,
4 AristotlePagaltzis 1003 Dissemination, and Design'', !1(1), 3-18, June 1988 (also
2 perry 1004 available as: Computing Science Technical Report No. 128,
1005 AT
1006 ''
1007 !!AUTHOR
1008
1009
1010 Pehong Chen, Chen
1011 Manual page extensively revised and corrected, and
1012 troff(1) examples created by Rick P. C. Rodgers, UCSF
1013 School of Pharmacy
1014 ''
1015 !!ACKNOWLEDGMENTS
1016
1017
1018 Leslie Lamport contributed significantly to the design.
1019 Michael Harrison provided valuable comments and suggestions.
1020 Nelson Beebe improved on the portable version, and maintains
1021 the source distribution for the TEX Users Group. Andreas
1022 Brosig contributed to the German word ordering. The
1023 modification to the __-ms__ macros was derived from a
1024 method proposed by Ravi Sethi of AT
1025 __LOG'' and ''CONTRIB'' files in the
1026 ''makeindex'' source distribution record other
1027 contributions.
1028 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.