MAKEINDEX(1L) MISC. REFERENCE MANUAL PAGES MAKEINDEX(1L)



NAME
makeindex - a general purpose, formatter-independent index
processor

SYNOPSIS
makeindex [-ilqrcg] [-s sty] [-o ind] [-t log] [-p no] [
idx0 idx1 idx2 ...]

DESCRIPTION
Makeindex is a general purpose hierarchical index generator;
it accepts one or more input files (often produced by a text
formatter such as TeX (tex(1L)) or troff(1)), sorts the
entries, and produces an output file which can be formatted.
The index can have up to three levels (0, 1, and 2) of subi-
tem nesting. The way in which words are flagged for index-
ing within the main document is specific to the formatter
used; this program does not automate the process of select-
ing these words. As the output index is hierarchical, mak-
eindex can be considered complimentary to the awk (1)-based
make.index (1L) system of Bentley and Kernighan, which is

specific to troff (1), generates non-hierarchical indices,
and employs a much simpler syntax for indicating index
entries.

The formats of the input and output files are specified in a
style file; by default, input is assumed to be a .idx file,
as generated by LaTeX.

Unless specified explicitly, the base name of the first
input file (idx0) is used to determine the names of other
files. For each input file name specified, a file of that
name is sought. If this file is not found and the file name
has no extension, the extension .idx is appended. If no
file with this name is found, the program aborts.

For important notes on how to select index keywords, see the
document by Lamport cited below. As an issue separate from
selecting index keywords, a systematic mechanism for placing
index terms in a document is suggested in ``Index Prepara-
tion and Processing'', a paper cited below.

OPTIONS
-i Take input from stdin. When this option is speci-
fied and -o is not, output is written to stdout.

-l Letter ordering; by default, word ordering is used
(see the ORDERING section).

-q Quiet mode; send no messages to stderr. By
default, progress and error messages are sent to
stderr as well as to the transcript file.




Sun Release 4.0 Last change: 11/11/1989 1






MAKEINDEX(1L) MISC. REFERENCE MANUAL PAGES MAKEINDEX(1L)



-r Disable implicit page range formation; page ranges
must be created by using explicit range operators
(see SPECIAL EFFECTS). By default, three or more
successive pages are automatically abbreviated as
a range (e.g. 1-5).

-c Compress intermediate blanks (ignoring leading and
trailing blanks and tabs). By default, blanks in
the index key are retained.

-g By default makeindex's word ordering is that sym-
bols precede numbers which precede uppercase
letters which precede lowercase letters. The
sequence in German word ordering is symbols,
lowercase letters, uppercase letters, then
numbers. By setting the new option makeindex
sorts the entries considering that word ordering
according to the German rule DIN 5007. Moreover
the -g option enables makeinde to recognize the
German TeX-commands {"a, "o, "u and "s} as {ae,
oe, ue and ss} during the sorting of the entries.
If German sort is active, the quote character must
be redefined in a style file, e.g., redefine quote
as '+'. If -g is set and the quote character is
not redefined makeindex will produce an error mes-
sage and abort.

-s sty Employ sty as the style file (no default). The
environment variable INDEXSTYLE defines the path
where the style file should be found.

-o ind Employ ind as the output index file. By default,
the file name is created by appending the exten-
sion .ind to the base name of the first input file
(idx0).

-t log Employ log as the transcript file. By default,
the file name is created by appending the exten-
sion .ilg to the base name of the first input file
(idx0).

-p num Set the starting page number of the output index
file to be num (useful when the index file is to
be formatted separately). The argument num may be
numerical or one of the following:

any The starting page is the last source
page number plus 1.

odd The starting page is the first odd page
following the last source page number.




Sun Release 4.0 Last change: 11/11/1989 2






MAKEINDEX(1L) MISC. REFERENCE MANUAL PAGES MAKEINDEX(1L)



even The starting page is the first even page
following the last source page number.

The source log file name is determined by append-
ing the extension .log to the base name of the
first input file (idx0). The last source page is
obtained by searching backward in the log file for
the first instance of a number included within
paired square brackets ([...]). If a page number
is missing or the log file is not found, no
attempt will be made to set the starting page
number.

STYLE FILE
This file can reside anywhere in the path defined by the
environment variable INDEXSTYLE. A style file is a list of
pairs. There are two types of
specifiers: input and output. Pairs do not have to appear
in any particular order. A line begun by `%' is a comment.
In the following list of specifiers and arguments,
is an arbitrary string delimited by double quotes ("..."),
is a single letter embraced by single quotes ('...'),
and is a nonnegative integer. The maximum length
of a is 1024. A literal backslash or quote must be
escaped (by a backslash). Anything not specified in the
style file will be assigned a default value, which is shown
in the rightmost column.


Input Style Specifiers

keyword "\\indexentry"
Command which tells makeindex that
its argument is an index entry.

arg_open '{'
Opening delimiter for the index
entry argument.

arg_close '}'
Closing delimiter for the index
entry argument.

range_open '('
Opening delimiter indicating the
beginning of an explicit page
range.

range_close ')'
Closing delimiter indicating the
end of an explicit page range.




Sun Release 4.0 Last change: 11/11/1989 3






MAKEINDEX(1L) MISC. REFERENCE MANUAL PAGES MAKEINDEX(1L)



level '!'
Delimiter denoting a new level of
subitem.

actual '@'
Symbol indicating that the next
entry is to appear in the output
file.

encap '|'
Symbol indicating that the rest of
the argument list is to be used as
the encapsulating command for the
page number.

quote '"'

escape '\\'
Symbol which escapes the following
letter, unless its preceding letter
is escape. Note: quote is used to
escape the letter which immediately
follows it, but if it is preceded
by escape, it is treated as a ordi-
nary character. These two symbols
must be distinct.



Output Style Specifiers

preamble "\\begin{theindex}\n"
Preamble of output file.

postamble "\n\n\\end{theindex}\n"
Postamble of output file.

setpage_prefix "\n \\setcounter{page}{"
Prefix of command which sets the
starting page number.

setpage_suffix "}\n"
Suffix of command which sets the
starting page number.

group_skip "\n\n \\indexspace\n"
Vertical space to be inserted
before a new group begins.

headings_flag 0
Flag indicating treatment of new
group headers, which are inserted



Sun Release 4.0 Last change: 11/11/1989 4






MAKEINDEX(1L) MISC. REFERENCE MANUAL PAGES MAKEINDEX(1L)



when before a new group (symbols,
numbers, and the 26 letters): posi-
tive values cause an uppercase
letter to be inserted between pre-
fix and suffix, and negative values
cause a lowercase letter to be
inserted (default is 0, which pro-
duces no header).

heading_prefix ""
Header prefix to be inserted before
a new letter begins.

symhead_positive
"Symbols"
Heading for symbols to be inserted
if headings_flag is positive.

symhead_negative
"symbols"
Heading for symbols to be inserted
if headings_flag is negative.

numhead_positive
"Numbers"
Heading for numbers to be inserted
if headings_flag is positive.

numhead_negative
"numbers"
Heading for numbers to be inserted
if headings_flag is negative.

item_0 "\n \\item "
Command to be inserted between two
primary (level 0) items.

item_1 "\n \\subitem "
Command to be inserted between two
secondary (level 1) items.

item_2 "\n \\subsubitem "
Command to be inserted between two
level 2 items.

item_01 "\n \\subitem "
Command to be inserted between a
level 0 item and a level 1 item.

item_x1 "\n \\subitem "
Command to be inserted between a
level 0 item and a level 1 item,



Sun Release 4.0 Last change: 11/11/1989 5






MAKEINDEX(1L) MISC. REFERENCE MANUAL PAGES MAKEINDEX(1L)



where the level 0 item does not
have associated page numbers.

item_12 "\n \\subsubitem "
Command to be inserted between a
level 1 item and a level 2 item.

item_x2 "\n \\subsubitem "
Command to be inserted between a
level 1 item and a level 2 item,
where the level 1 item does not
have associated page numbers.

delim_0 ", "
Delimiter to be inserted between a
level 0 key and its first page
number (default: comma followed by
a blank).

delim_1 ", "
Delimiter to be inserted between a
level 1 key and its first page
number (default: comma followed by
a blank).

delim_2 ", "
Delimiter to be inserted between a
level 2 key and its first page
number (default: comma followed by
a blank).

delim_n ", "
Delimiter to be inserted between
two page numbers for the same key
in any level (default: comma fol-
lowed by a blank).

delim_r "--"
Delimiter to be inserted between
the starting and ending page
numbers of a range.

delim_t ""
Delimiter to be inserted at the end
of a page list. This delimeter has
no effect on entries which have no
associated page list.

encap_prefix "\\"
First part of prefix for the com-
mand which encapsulates the page
number.



Sun Release 4.0 Last change: 11/11/1989 6






MAKEINDEX(1L) MISC. REFERENCE MANUAL PAGES MAKEINDEX(1L)



encap_infix "{"
Second part of prefix for the com-
mand which encapsulates the page
number.

encap_suffix "}".
Suffix for the command which encap-
sulates the page number.

line_max 72
Maximum length of a line in the
output, beyond which a line wraps.

indent_space "\t\t"
Space to be inserted in front of a
wrapped line (default: two tabs).

indent_length 16
Length of indent_space (default:
16, equivalent to 2 tabs).

TeX EXAMPLE
The following example shows a style file called book.ist,
which defines an index for a book which can be formatted
independently of the main source:

preamble
"\\documentstyle[12pt]{book}
\\begin{document}
\\begin{theindex}
{\\small\n"
postamble
"\n\n}
\\end{theindex}
\\end{document}\n"

Assuming that a particular book style requires the index (as
well as any chapters) to start from an odd page number, and
that the input file is named foo.idx, the following command
line produces output in file foo-.ind:

makeindex -s book.ist -o foo-.ind -p odd foo

Here a non-default output file name is used to avoid
clobbering the output for the book itself (presumably
foo.dvi, which would have been the default name for the
index output file!).

TROFF EXAMPLE
A sample control file for creating an index, which we will
assume resides in the file sample.ist:




Sun Release 4.0 Last change: 11/11/1989 7






MAKEINDEX(1L) MISC. REFERENCE MANUAL PAGES MAKEINDEX(1L)



keyword "IX:"
preamble
".\\\" start of index output
.SH
.ce
\\s+2INDEX\\s-2
.2C
.de IS
.sp 0.5
\\s+2\\fB
.ce
..
.de IE
.sp 0.5
\\s-2\\fP
..
.de I1
.ti 0.25i
..
.de 1I
.ti 0.25i
..
.de I2
.ti 0.5i
..
.de 2I
.ti 0.5i
.."
postamble "\n.\\\" end of index output"
setpage_prefix "\n.nr % 1\n"
setpage_suffix ""
group_skip "\n.sp"
headings_flag 1
heading_prefix "\n.IS\n"
heading_suffix "\n.IE"
item_0 "\n.br\n"
item_1 "\n.I1\n"
item_2 "\n.I2\n"
item_01 "\n.I1\n"
item_x1 "\n.1I\n"
item_12 "\n.I2\n"
item_x2 "\n.2I\n"
delim_0 ", "
delim_1 ", "
delim_2 ", "
delim_r "-"
delim_t "."
encap_prefix "\\fB"
encap_infix ""
encap_suffix "\\fP"
indent_space " "
indent_length 8\fP



Sun Release 4.0 Last change: 11/11/1989 8






MAKEINDEX(1L) MISC. REFERENCE MANUAL PAGES MAKEINDEX(1L)



The local macro package may require modification, as in this
example of an extension to the -ms macros (note that at some
sites, this macro should replace a pre-existing macro of the
same name):

.
.de IX
.ie '\\n(.z'' .tm IX: \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9 {\\n(PN}
.el \\!.IX \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9 {\\n(PN}
..

(note that the string {\\n(PN} is separated from the rest of
the line by a tab. If your local macro package does not
contain this extension, just include those lines at the
beginning of your file. Here is a simple troff(1) input
file, which we will assume is named sample.txt:

This is a sample file to test the \fImakeindex\fP(1L) program, and see
.IX {indexing!programs!C language}
.IX {makeindex@\fImakeindex\fP(1L)}
.bp
.rs
.IX {Knuth}
.IX {typesetting!computer-aided}
how well if functions in the \fItroff\fP(1) environment.

Note that index entries are indicated by the .IX macro,
which causes the following text to be written to stdout
along with the current page number. To create an input file
for makeindex, in the Bourne shell environment, do the

equivalent at your site of the command:

psroff -ms -Tpsc -t sample.txt > /dev/null 2>
sample.tmp

To filter out any genuine error messages, invoke grep(1):

grep '^IX: ' sample.tmp > sample.idx
This leaves the input for makeindex in sample.inp; the next
step is to invoke makeindex:

makeindex -s sample.ist sample.idx

which leaves troff(1)-ready output in the file sample.ind.

ORDERING
By default, makeindex assumes word ordering; if the -l
option is in effect, letter ordering is used. In word ord-
ering, a blank precedes any letter in the alphabet, whereas
in letter ordering, it does not count at all. This is
illustrated by the following example:




Sun Release 4.0 Last change: 11/11/1989 9






MAKEINDEX(1L) MISC. REFERENCE MANUAL PAGES MAKEINDEX(1L)



word order letter order
sea lion seal
seal sea lion

Numbers are always sorted in numeric order. For instance,

9 (nine), 123
10 (ten), see Derek, Bo

Letters are first sorted without regard to case; when words
are identical, the uppercase version precedes its lowercase
counterpart.

A special symbol is defined here to be any character not
appearing in the union of digits and the English alphabetic.
Patterns starting with special symbols precede numbers,
which precede patterns starting with letters. As a special
case, a string starting with a digit but mixed with non-
digits is considered to be a pattern starting with a special
character.

SPECIAL EFFECTS
Entries such as

\indexentry{alpha}{1}
\indexentry{alpha!beta}{3}
\indexentry{alpha!beta!gamma}{10}
in the input file will be converted to

\item alpha, 1
\subitem beta, 3
\subsubitem gamma, 10
in the output index file. Notice that the level symbol
(`!') is used above to delimit hierarchical levels.

It is possible to make an item appear in a designated form
by using the actual (`@') operator. For instance,

\indexentry{alpha@{\it alpha\/}}{1}
will become

\item {\it alpha\/} 1
after processing. The pattern preceding `@' is used as sort
key, whereas the one following it is written to the output
file. Note that two appearances of the same key, one with
and one without the actual operator, are regarded as dis-
tinct entries.

It is possible to encapsulate a page number with a desig-
nated command using the encap (`|') operator:





Sun Release 4.0 Last change: 11/11/1989 10






MAKEINDEX(1L) MISC. REFERENCE MANUAL PAGES MAKEINDEX(1L)



\indexentry{alpha|bold}{1}
will be converted to

\item alpha \bold{1}
where \bold{n} will expand to {\bf n}. In this example, the
three output attributes associated with page encapsulation
encap_prefix, encap_infix, and encap_suffix, correspond to
backslash, left brace, and right brace, respectively. This
mechanism allows page numbers to be set in different fonts.
For example, the page where the definition of a keyword
appears can be in one font, the location of a primary exam-
ple can be in another font, and other appearances in yet a
third font.

The encap operator can also be used to create cross refer-
ences in the index:

\indexentry{alpha|see{beta}}{1}
will become

\item alpha \see{beta}{1}
in the output file, where

\see{beta}{1}
will expand to

{\it see\/} beta
Note that in a cross reference like this the page number
disappears.

A pair of encap concatenated with range_open (`|(') and
range_close (`|)') creates an explicit page range:

\indexentry{alpha|(}{1}
\indexentry{alpha|)}{5}
will become

\item alpha, 1-5
Intermediate pages indexed by the same key will be merged
into the range implicitly. This is especially useful when
an entire section about a particular subject is to be
indexed, in which case only the range opening and closing
operators need to be inserted at the beginning and end of
the section. Explicit page range formation can also include
an extra command to set the page range in a designated font:

\indexentry{alpha|(bold}{1}
\indexentry{alpha|)}{5}
will become

\item alpha, \bold{1--5}
Several potential problems are worth mentioning. First,



Sun Release 4.0 Last change: 11/11/1989 11






MAKEINDEX(1L) MISC. REFERENCE MANUAL PAGES MAKEINDEX(1L)



entries like

\indexentry{alpha|(}{1}
\indexentry{alpha|bold}{3}
\indexentry{alpha|)}{5}
will be interpreted as

\item alpha, \bold{3}, 1--5
but with a warning message in the transcript about
encountering an inconsistent page encapsulator. An explicit
range beginning in a Roman page number and ending in Arabic
is also considered an error. In this instance, (if possi-
ble) the range is broken into two subranges, one in Roman
and the other in Arabic. For instance,

\indexentry{alpha|(}{i}
\indexentry{alpha}{iv}
\indexentry{alpha}{3}
\indexentry{alpha|)}{7}
will be turned into

\item alpha, 1--iv, 3--7
with a warning message in the transcript file complaining
about an illegal range formation.

Finally, every special symbol mentioned in this section may
be escaped by the quote operator (`"'). Thus

\indexentry{alpha"@beta}{1}
will actually become

\item alpha@beta, 1
as a result of executing makeindex. The quoting power of
quote is eliminated if it is immediately preceded by escape
(`\'). For example,

\indexentry{f\"ur}{1}
becomes

\item f\"ur, 1
which represents an umlaut-accented `u' to the TeX family of
processors.

SEE ALSO
latex(1L), make.index (1L), qsort(3), tex(1L), troff(1L)
Index Preparation and Processing, Pehong Chen and Michael A.
Harrison. Software: Practice and Experience, 18(9):897-915,
September 1988.
Automating Index Preparation, Pehong Chen and Michael A.
Harrison. Technical Report 87/347, Computer Science Divi-
sion, University of California, Berkeley, 1988. This is a
LaTeX document supplied with the makeindex distribution.



Sun Release 4.0 Last change: 11/11/1989 12






MAKEINDEX(1L) MISC. REFERENCE MANUAL PAGES MAKEINDEX(1L)



MakeIndex: An Index Processor for LaTeX, Leslie Lamport,
Feburary 1987. This is a LaTeX document supplied with the
makeindex disstribution.
Tools for Printing Indices, Jon L. Bentley and Brian W. Ker-
nighan, Elextronic Publishing, 1(1), June 1988. Also avail-
able as Computing Science Technical Report No. 128, AT&T
Bell Laboratories, Murray Hill, NJ 07974, 1986.

AUTHOR
Pehong Chen, Chen & Harrison International Systems, Inc.
Palo Alto, California, USA ([email protected]).
Manual page extensively revised and corrected, and troff(1)
examples created by Rick P. C. Rodgers, UCSF School of Phar-
macy ([email protected]).

ACKNOWLEDGMENTS
Leslie Lamport contributed significantly to the design.
Michael Harrison provided valuable comments and suggestions.
Nelson Beebe improved on the portable version significantly.
Andreas Brosig contributed to the German word ordering. The
modification to the -ms macros was derived from a method
proposed by Ravi Sethi of AT&T Bell Laboratories.

































Sun Release 4.0 Last change: 11/11/1989 13