\$1
..
The way in which words are flagged for indexing within the main document is specific to the formatter used; makeindex does not automate the process of selecting these words.
As the output index is hierarchical, makeindex 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. For illustration of use with troff and TeX, see the section \s-2EXAMPLES\s+2 below.
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 or TeX.
Unless specified explicitly, the base name of the first input file (idx1) 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, makeindex aborts.
If exactly one input file was given and no explicit style file was specified using -s, makeindex uses a file with the extension .mst as default style file (when present).
Errors in style files and index entries are logged and counted, but do not terminate processing. When makeindex terminates, it will do so with a non-zero exit status if any errors were found. Some operating systems permit the exit status to control further execution of commands.
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 Preparation and Processing, a paper cited below.
Ports of makeindex to most operating systems are available. On those systems with severe file name length restrictions, such as the IBM PC, you should expect its name to be shortened, to something like makeindx or makidx.
- 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.
- even
- The starting page is the first even page following the last source page number.
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. The source log file name is determined by appending the extension .log to the base name of the first input file (idx1).
Attribute values are strings, characters, or numbers:
A <string> is arbitrary text delimited by double quotes ("..."). Inside the <string>, \n represents a newline character, \t a horizontal tab character, \\ a backslash, and \<other> represents the single character <other>. Unbackslashed newlines are also permitted, so that multiline <string> values can be made more readable. A NUL character in the text terminates the <string> value, so only 255 different characters can be represented. This limitation arises from the C programming language used to implement makeindex. The maximum length of a <string> is 5000 characters.
A <char> is a single character, or a backslash-character pair, embraced by single quotes ('x' or '\x'). The backslash conventions for <string> apply to <char>; thus, a single quote must be represented by '\''. All 256 possible characters can be represented, including NUL. A newline can be represented as '\n', '<newline>', or '\<newline>', where <newline> is a literal newline character.
A <number> is an optionally-signed decimal integer.
Outside <char> and <string> values, a percent, `%', initiates a comment that continues up to, and including, the next newline. Comment may occur anywhere that whitespace can appear.
Use the -d option with an empty index file to get a neatly formatted tabulation of all specifiers and their attribute values for subsequent modification and use as a style file. For example, you can trap the style file output in a file named foo.mst on UNIX with the command
makeindex -d -e foo.mst -i -q -t /dev/null </dev/null >/dev/null
This information is written after any input style file has been processed, so it includes all changes made by the style file.
Errors in style files result in warning messages to stderr, and to the transcript file, but makeindex continues execution; it will, however, terminate with a non-zero exit status.
Default values are provided for all attributes. They are shown at the head of the rightmost column in the following descriptions of input and output specifiers.
Symbol indicating that the next entry is to appear in the output file.
Closing delimiter for the index entry argument.
Opening delimiter for the index entry argument.
Symbol indicating that the rest of the argument list is to be used as the encapsulating command for the page number.
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 ordinary character. These two symbols must be distinct.
Command which tells makeindex that its argument is an index entry.
Delimiter denoting a new level of subitem.
String which separates values in a composite page number. With the default compositor string, page number A-3 would be recognized as the third page of Appendix A.
Note: quote is used to escape the letter which immediately follows it, but if it is preceded by escape, it is treated as a ordinary character. These two symbols must be distinct. If German word ordering is selected by the -g command-line option, the quote character must be redefined in a style file.
Closing delimiter indicating the end of an explicit page range.
Opening delimiter indicating the beginning of an explicit page range.
Delimiter to be inserted between a level 0 key and its first page number (default: comma followed by a blank).
Delimiter to be inserted between a level 1 key and its first page number (default: comma followed by a blank).
Delimiter to be inserted between a level 2 key and its first page number (default: comma followed by a blank).
Delimiter to be inserted between two page numbers for the same key in any level (default: comma followed by a blank).
Delimiter to be inserted between the starting and ending page numbers of a range.
Delimiter to be inserted at the end of a page list. This delimiter has no effect on entries which have no associated page list.
Second part of prefix for the command which encapsulates the page number.
First part of prefix for the command which encapsulates the page number.
Suffix for the command which encapsulates the page number.
Vertical space to be inserted before a new group begins.
Header prefix to be inserted before a new letter begins.
Header suffix to be inserted after a new letter begins.
Flag indicating treatment of new group headers, which are inserted when before a new group (symbols, numbers, and the 26 letters): positive values cause an uppercase letter to be inserted between prefix and suffix, and negative values cause a lowercase letter to be inserted (default is 0, which produces no header).
Length of indent_space (default: 16, equivalent to 2 tabs).
Space to be inserted in front of a wrapped line (default: two tabs).
Command to be inserted between two primary (level 0) items.
Command to be inserted between a level 0 item and a level 1 item.
Command to be inserted between two secondary (level 1) items.
Command to be inserted between a level 1 item and a level 2 item.
Command to be inserted between two level 2 items.
Command to be inserted between a level 0 item and a level 1 item, where the level 0 item does not have associated page numbers.
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.
Maximum length of a line in the output index, beyond which a line wraps. This is not a strict limit, because line breaks are never introduced in index entry text.
Heading for numbers to be inserted if headings_flag is negative.
Heading for numbers to be inserted if headings_flag is positive.
String which defines the output order of various types of page numbers. There should be up to five letters selected without duplication from the following list, in the required order: a (alphabetic lowercase), A (alphabetic uppercase), n (Arabic digits), r (Roman lowercase), and R (Roman uppercase).The default page number precedence string corresponds to that conventionally used in English-language books, where lowercase Roman numerals are used in front matter, Arabic numbers for the main body, and possibly composite page numbers beginning with a letter or an uppercase Roman numeral for appendices.
Postamble of output file.
Preamble of output file.
Prefix of command which sets the starting page number.
Suffix of command which sets the starting page number.
Delimiter to replace the range delimiter and the second page number of a two-page list. When present, it overrides delim_r. Example: "f.".
Delimiter to replace the range delimiter and the second page number of a three-page list. When present, it overrides delim_r and suffix_mp. Example: "ff.".
Delimiter to replace the range delimiter and the second page number of a multiple page list (three or more pages). When present, it overrides delim_r. Example: "f.".
Heading for symbols to be inserted if headings_flag is negative.
Heading for symbols to be inserted if headings_flag is positive.
makeindex -d -e foo.mst -i -q -t /dev/null </dev/null >/dev/null
It is a convenient starting point if you wish to modify style specifiers.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% makeindex portable version 2.13 (beta) [09-Apr-1994]
%% Input style file specifiers
actual '@'
arg_close '}'
arg_open '{'
encap '|'
escape '\\'
keyword "\\indexentry"
level '!'
page_compositor "-"
quote '\"'
range_close ')'
range_open '('
%% Output style file specifiers
delim_0 ", "
delim_1 ", "
delim_2 ", "
delim_n ", "
delim_r "--"
delim_t ""
encap_infix "{"
encap_prefix "\\"
encap_suffix "}"
group_skip "\n\n \\indexspace\n"
heading_prefix ""
heading_suffix ""
headings_flag 0
indent_length 16
indent_space "\t\t"
item_0 "\n \\item "
item_01 "\n \\subitem "
item_1 "\n \\subitem "
item_12 "\n \\subsubitem "
item_2 "\n \\subsubitem "
item_x1 "\n \\subitem "
item_x2 "\n \\subsubitem "
line_max 72
numhead_negative "numbers"
numhead_positive "Numbers"
page_precedence "rnaRA"
postamble "\n\n\\nd{theindex}\n"
preamble "\\begin{theindex}\n"
setpage_prefix "\n \\setcounter{page}{"
setpage_suffix "}\n"
suffix_2p ""
suffix_3p ""
suffix_mp ""
symhead_negative "symbols"
symhead_positive "Symbols"
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
preamble
"\\documentstyle[12pt]{book}
\\begin{document}
\\begin{theindex}
{\\small\n"
postamble
"\n\n}
\\nd{theindex}
\\nd{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 footmp.ind:
makeindex -s book.mst -o footmp.ind -p odd foo
Here a non-default output file name is used to avoid clobbering the output for the book itself (presumably foo.ind, which would have been the default name for the index output file!).
keyword "IX:" preamble ".\\\" start of index output \".\\\" enter two column mode .2C .SH .ce INDEX .XS INDEX .XE .R .ps 9p .vs 11p .sp .de I1 .ti 0.25i .. .de I2 .ti 0.5i .." postamble "\n.\\\" end of index output" setpage_prefix "\n.nr % " setpage_suffix "" group_skip "\n.sp 1.0" 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.I1\n" item_12 "\n.I2\n" item_x2 "\n.I2\n" delim_0 ", " delim_1 ", " delim_2 ", " delim_r "-" delim_t "." encap_prefix "\\" encap_infix "" encap_suffix "\\" indent_space "" indent_length 0
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):
.\" IX - index words to stderr
.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 \makeindex\(1L)
program, and see
.IX {indexing!programs!C language}
.IX {makeindex@\makeindex\(1L)}
.bp
.rs
.IX {Knuth}
.IX {typesetting!computer-aided}
how well it functions in the \troff\(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.
psroff -ms -Tpsc -t sample.txt > /dev/null 2> sample.tmp
Some sites will require ditroff instead of psroff. To filter out any genuine error messages, invoke grep(1):
grep '^IX: ' sample.tmp > sample.idx
psroff -ms -I sample.inp -Tpsc sample.txt
If it is wished to suppress the formatter output:
psroff -ms -I sample.inp -Tpsc -t sample.txt > /dev/null
makeindex -s sample.mst sample.idx
This leaves troff(1)-ready output in the file sample.ind.
word order letter ordersea lion seal
seal sea lion
Numbers are always sorted in numeric order. For instance,
9 (nine), 12310 (ten), see Derek, Bo
Letters are first sorted without regard to case; when words are identical, the uppercase version precedes its lowercase counterpart. The German ordering option, -g, puts lowercase before uppercase.
A special symbol is defined here to be any character not appearing in the union of digits and the English alphabetic characters. 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.
A simple page number may be one of six different types: an Arabic number, an Arabic number followed by an arbitrary string, a lowercase Roman number, an uppercase Roman number, a single lowercase letter, or a single uppercase letter. Because Roman numbers are represented with the letters i(1), v(5), x(10), l(50), c(100), d(500), and m(1000), and their uppercase equivalents, the two letter types may not be distinguishable from Roman numbers. The ambiguity is always resolved in favor of Roman numbers. Examples of simple page numbers are 123, 258abc, xxiv, MCMXCIV, y, and Z.
makeindex's internal representation of page numbers is limited by the size of the C programming language integer data type, int, and the need to distinguish between different types of page numbers. On 32-bit machines, makeindex therefore restricts Arabic and Roman numbers to values in the range 0 ... 99999999. On small machines, it is possible to compile a version that uses only 16-bit integers, in which case page number values are limited to the range 0 ... 9999.
A composite page number is a simple page number separated from a composite page number by the compositor character, which is settable by a page_compositor <string> entry in a style file. Examples of composite numbers are: 10-8-2, 12-a, IV-3, and A-1.
For sorting purposes, each of the six types of simple page numbers is represented as a biased integer in non-overlapping ranges. The default sort order of these six types can be altered by the page_precedence <string> style file option. Sorting is done according to the first simple number, then according to the second, third, ... numbers. In the event a simple page number consists of a digit string followed by an arbitrary string (e.g. 117a), sorting is first by the value of the digit string, then for equal digit strings, by ordinary alphanumeric ordering. Thus, with the default page precedence, the numbers 1, 12, 12a, 12ab, 12abc, 12A, 12-1, a-1, and A-1 are in sorted order.
Although reasonable efforts are made to detect incorrect page numbers, for Roman numbers, equivalent, if unconventional, forms are accepted: iiiiiiiii, viiii, and ix all reduce to the value 9 for sorting and ordering purposes.
The maximum length of a composite page number, and the number of simple page numbers in a composite page number, can be set at compile time; they are at least 100, and 50, respectively.
\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 distinct entries.
The item, subitem, and subsubitem fields may have individual sort keys:
\indexentry{aa@{\it aa\/}!bb@{\it bb\/}!cc@{\it cc\/}}{1}
This will be converted to
\item {\it aa}, 1
\subitem {\it bb}, 3
\subsubitem {\it cc}, 10
It is possible to encapsulate a page number with a designated command using the encap (`|') operator:
\indexentry{alpha|bold}{1}
will be converted to
\item alpha, \bold{1}
where, with a suitable definition for TeX, \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 example can be in another font, and other appearances in yet a third font.
The encap operator can also be used to create cross references 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, 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 possible) 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, i--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.
From version 2.11 of makeindex, the quote operator may quote any character in the range 1 ... 255. Character 0 is excluded because it is used internally in the makeindex source code as a string terminator. With this change, sort keys can be created for all eight-bit characters except the character 0 (this is not the digit zero). The sorting order is
Here is an example showing the indexing of all printable ASCII characters other than letters and digits, assuming the default TeX format. For convenience, the page number references are the corresponding ASCII ordinal values.punctuation characters (in ASCII order), digits, control characters (1 ... 31), space (32), letters (ignoring case), characters 127 ... 255.
\indexentry{" @" (space)}{32}
\indexentry{"!@"! (exclamation point)}{33}
\indexentry{""@"" (quotation mark)}{34}
\indexentry{"#@"\# (sharp sign)}{35}
\indexentry{"$@"\$ (dollar sign)}{36}
\indexentry{"%@"\ (percent sign)}{37}
\indexentry{"&@" (ampersand)}{38}
\indexentry{"<@"$<$ (left angle bracket)}{60}
\indexentry{"=@"= (equals)}{61}
\indexentry{">@"$>$ (right angle bracket)}{62}
\indexentry{"?@"? (query)}{63}
\indexentry{"@@"@ (at sign)}{64}
\indexentry{"[@"[ (left square bracket)}{91}
\indexentry{"\@"\verb=\= (backslash)}{92}
\indexentry{"]@"] (right square bracket)}{93}
\indexentry{"^@"\verb=^= (caret)}{94}
\indexentry{"_@"\verb=_= (underscore)}{95}
\indexentry{"`@"\verb=~= (grave accent)}{96}
\indexentry{"{@"\"{ (left brace)}{123}
\indexentry{"|@"\verb="|= (vertical bar)}{124}
\indexentry{"}@"\"} (right brace)}{125}
\indexentry{"~@"\verb=~= (tilde)}{126}
Characters in the actual fields following the `@' character which
have special significance to TeX must be represented as control
sequences, or as math mode characters. Note particularly how the
entries for the at sign, left and right braces, and the vertical
bar, are coded. The index file output by
makeindex
for this example looks like this:
\begin{theindex}
\item ! (exclamation point), 33
\item " (quotation mark), 34
\item \# (sharp sign), 35
\item \$ (dollar sign), 36
\item \ (percent sign), 37
\item (ampersand), 38
\item $<$ (left angle bracket), 60
\item = (equals), 61
\item $>$ (right angle bracket), 62
\item ? (query), 63
\item @ (at sign), 64
\item [ (left square bracket), 91
\item \verb=\= (backslash), 92
\item ] (right square bracket), 93
\item \verb=^= (caret), 94
\item \verb=_= (underscore), 95
\item \verb=~= (grave accent), 96
\item \{ (left brace), 123
\item \verb=|= (vertical bar), 124
\item \} (right brace), 125
\item \verb=~= (tilde), 126
\indexspace
\item (space), 32
\nd{theindex}
UCSF Enhanced troff/\*(Ts --- An Overview, Richard P. C. Rodgers and Conrad Huang, LSMB Technical Report 90-2, UCSF School of Pharmacy, San Francisco, 1990.
Index Preparation and Processing, Pehong Chen and Michael A. Harrison, Software: Practice and Experience, 19(9), 897--915, September 1988.
Automating Index Preparation, Pehong Chen and Michael A. Harrison. Technical Report 87/347, Computer Science Division, University of California, Berkeley, 1987 (a LaTeX document supplied with makeindex).
MakeIndex: An Index Processor for LaTeX, Leslie Lamport, February 1987 (a LaTeX document supplied with makeindex).
Tools for Printing Indices, Jon L. Bentley and Brian W. Kernighan, Electronic Publishing --- Origination, Dissemination, and Design, 1(1), 3--18, June 1988 (also available as: Computing Science Technical Report No. 128, AT&T Bell Laboratories, Murray Hill, NJ 07974, 1986).
Manual page extensively revised and corrected, and troff(1) examples created by Richard P. C. Rodgers, UCSF School of Pharmacy, San Francisco, CA, USA <rodgers@cca.ucsf.edu>, with later additions by Nelson H. F. Beebe <beebe@math.utah.edu>.
Nelson H. F. Beebe improved on the portable version, and maintains the source distribution for the TeX Users Group. He also instituted major internal redesigns for speed and memory economization, removed small limits on many object sizes, improved handling of composite page numbers, and provided a large validation test suite to enhance confidence in a correct installation of makeindex.
The LOG and CONTRIB files in the makeindex source distribution record other contributions.
The newest version of makeindex is maintained on the Internet host machine ftp.math.utah.edu in the directory tree /pub/tex/pub/makeindex. The distribution is mirrored from there to the major Comprehensive TeX Archive Network (CTAN) hosts, ftp.dante.de (Germany), ftp.shsu.edu (Texas, USA), ftp.tex.ac.uk (England), ...