# man > makeindex(1) [_MAKEINDEX_(1)](https://www.chedong.com/phpMan.php/man/MAKEINDEX/1/markdown) TeX Live [_MAKEINDEX_(1)](https://www.chedong.com/phpMan.php/man/MAKEINDEX/1/markdown) ## NAME makeindex - a general purpose, formatter-independent index processor ## SYNOPSIS **makeindex **[**-c**] [**-g**] [**-i**] [**-l**] [**-o _**ind_] [**-p _**num_] [**-q**] [**-r**] [**-s _**sfile_] [**-t _**log_] [**-L**] [**-T**] [_idx0_ _idx1_ _idx2_...] ## DESCRIPTION The program _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)](https://www.chedong.com/phpMan.php/man/tex/1L/markdown)) or [_troff_(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown), 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 subitem nesting. The way in which words are flagged for index‐ ing 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 complementary to the [_awk_(1)](https://www.chedong.com/phpMan.php/man/awk/1/markdown)-based [_make.index_(1L)](https://www.chedong.com/phpMan.php/man/make.index/1L/markdown) system of Bentley and Kernighan, which is specific to [_troff_(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown), 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 EXAMPLES 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. Unless specified explicitly, the base name of the first input file (_idx0_) is used to deter‐ mine 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). 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. ## OPTIONS ### -c default, blanks in the index key are retained. ### -g 5007. By default, _makeindex_ employs a word ordering in which precedence is: sym‐ bols, numbers, uppercase letters, lowercase letters. The sequence in German word ordering is: symbols, lowercase letters, uppercase letters, numbers. Additionally, this option enables _makeindex_ to recognize the German TeX-commands {"a, "o, "u and "s} as {ae, oe, ue and ss} during the sorting of the entries. The quote character must be redefined in a style file (for example, redefine quote as '+'). If the quote character is not redefined, _makeindex_ will produce an error message and abort. ### -i -o written to _stdout_. ### -l ### -o _ pending the extension _.ind_ to the base name of the first input file (_idx0_). ### -p _ 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. _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 (_idx0_). ### -q are sent to _stderr_ as well as to the transcript file. ### -r plicit range operators; see SPECIAL EFFECTS below. By default, three or more suc‐ cessive pages are automatically abbreviated as a range (e.g. 1—5). ### -s _ fines the path where the style file should be found. ### -t _ ing the extension _.ilg_ to the base name of the first input file (_idx0_). ### -L ### -T ## STYLE FILE The style file informs _makeindex_ about the format of the _.idx_ input files and the intended format of the final output file; examples appear below. This file can reside anywhere in the path defined by the environment variable INDEXSTYLE. The style file contains a list of <_specifier_, _attribute_> 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 fol‐ lowing 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 2048. A literal backslash or quote must be escaped (by a backslash). Anything not specified in the style file will be as‐ signed a default value, which is shown at the head of the rightmost column. **INPUT STYLE SPECIFIERS** **actual ** ´@´ Symbol indicating that the next entry is to appear in the output file. **arg_close ** ´}´ Closing delimiter for the index entry argument. **arg_open ** ´{´ Opening delimiter for the index entry argument. **encap ** ´|´ Symbol indicating that the rest of the argument list is to be used as the encapsulating command for the page number. **escape ** ´\\´ Symbol which escapes the following letter, unless its preceding let‐ ter is **escape**. Note: **quote **is used to escape the letter which imme‐ diately follows it, but if it is preceded by **escape**, it is treated as a ordinary character. These two symbols _must_ be distinct. **keyword ** "\\indexentry" Command which tells _makeindex_ that its argument is an index entry. **level ** ´!´ Delimiter denoting a new level of subitem. **page_compositor ** "-" Delimiter separating parts of a composite page number (see SPECIAL EFFECTS below). **quote ** ´"´ 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. **range_close ** ´)´ Closing delimiter indicating the end of an explicit page range. **range_open ** ´(´ Opening delimiter indicating the beginning of an explicit page range. **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 when before a new group (symbols, numbers, and the 26 letters): pos‐ itive values cause an uppercase letter to be inserted between prefix and suffix, and negative values cause a lowercase letter to be in‐ serted (default is 0, which produces no header). **heading_prefix ** "" Letter heading prefix to be inserted before a new letter begins. **heading_suffix ** "" Letter heading suffix to be inserted when 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, 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 followed by a blank). **delim_r ** "--" Delimiter to be inserted between the starting and ending page num‐ bers of a range. **delim_t ** "" Delimiter to be inserted at the end of a page list. This delimiter has no effect on entries which have no associated page list. **encap_prefix ** "\\" First part of prefix for the command which encapsulates the page number. **encap_infix ** "{" Second part of prefix for the command which encapsulates the page number. **encap_suffix ** "}". Suffix for the command which encapsulates the page number. **page_precedence ** "rnaRA". Page type precedence order. The default specifies: lowercase roman, numeric/arabic, lowercase alphabetic, uppercase roman, uppercase al‐ phabetic. **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). **suffix_2p ** "" Delimiter to replace the range delimiter and the second page number of a two page list. When present, it overrides **delim_r**. Example: "f.". **suffix_3p ** "" Delimiter to replace the range delimiter and the second page number of a three page list. When present, it overrides **delim_r **and **suf‐** **fix_mp**. Example: "ff.". **suffix_mp ** "" 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.". ## EXAMPLES ### 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 _footmp.ind_: makeindex -s book.ist -o footmp.ind -p odd foo Here a non-default output file name is used to avoid clobbering the output for the book it‐ self (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 _sam‐_ _ple.ist_: 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 "\\fB" encap_infix "" encap_suffix "\\fP" indent_space "" indent_length 0 The local macro package may require modification, as in this example of an extension to the ### -ms 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 lo‐ cal macro package does not contain this extension, just include those lines at the beginning of your file. Here is a simple [_troff_(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown) input file, which we will assume is named _sam‐_ _ple.txt_: This is a sample file to test the \fImakeindex\[fP(1L)](https://www.chedong.com/phpMan.php/man/fP/1L/markdown) program, and see .IX {indexing!programs!C language} .IX {makeindex@\fImakeindex\[fP(1L)](https://www.chedong.com/phpMan.php/man/fP/1L/markdown)} .bp .rs .IX {Knuth} .IX {typesetting!computer-aided} how well it functions in the \fItroff\[fP(1)](https://www.chedong.com/phpMan.php/man/fP/1/markdown) 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. **CREATING THE INDEX FILE IN THE BOURNE SHELL** 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 Some sites will require _ditroff_ instead of _psroff_. To filter out any genuine error messages, invoke [_grep_(1)](https://www.chedong.com/phpMan.php/man/grep/1/markdown): grep '^IX: ' sample.tmp > sample.idx ### CREATING THE INDEX FILE USING UCSF ENHANCED TROFF/TRANSCRIPT With UCSF Enhanced troff/TRANSCRIPT, the **-I **option of [_psroff_(1L)](https://www.chedong.com/phpMan.php/man/psroff/1L/markdown) can produce both formatter output and an index file: 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 **COMPLETING THE INDEX** Any of the above procedures leaves the input for _makeindex_ in _sample.inp_. The next step is to invoke _makeindex_: makeindex -s sample.ist sample.idx This leaves [_troff_(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown)-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 ordering, 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: _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 ver‐ sion 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 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 charac‐ ter. ## 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 hier‐ archical levels. It is possible to make an item appear in a designated form by using the **actual **(`@') opera‐ tor. 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 mech‐ anism allows page numbers to be set in different fonts. For example, the page where the def‐ inition 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 ex‐ plicit 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 encapsu‐ lator. An explicit range beginning in a Roman page number and ending in Arabic is also con‐ sidered 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. 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 imme‐ diately 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. A page number can be a composite of one or more fields separated by the delimiter bound to **page_compositor **(`-'), e.g., II-12 for page 12 of Chapter II. Page numbers may contain up to ten fields. Since 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 charac‐ ters except 0. The sorting order is punctuation characters (in ASCII order), digits, control characters (1 ... 31), space (32), letters (ignoring case), characters 127 ... 255. 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. \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 particu‐ larly 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 \end{theindex} ## FILES _makeindex_ executable file _$TEXMFMAIN/tex/plain/makeindex/idxmac.tex_ TeX macro file used by _makeindex_ _$TEXMFMAIN/tex/latex/base/makeidx.sty_ TeX macro file used by _makeindex_ ## SEE ALSO [ditroff(1L)](https://www.chedong.com/phpMan.php/man/ditroff/1L/markdown), [latex(1L)](https://www.chedong.com/phpMan.php/man/latex/1L/markdown), make.index (1L), [qsort(3)](https://www.chedong.com/phpMan.php/man/qsort/3/markdown), [tex(1L)](https://www.chedong.com/phpMan.php/man/tex/1L/markdown), [troff(1L)](https://www.chedong.com/phpMan.php/man/troff/1L/markdown) _UCSF_ _Enhanced_ _troff/TRANSCRIPT_ _—_ _An_ _Overview_, R. P. C. Rodgers and Conrad Huang, LSMB Techni‐ cal 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)](https://www.chedong.com/phpMan.php/man/19/9/markdown), 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 sup‐ plied with _makeindex_). _MakeIndex:_ _An_ _Index_ _Processor_ _for_ _LaTeX_, Leslie Lamport, February 1987 (a LaTeX document sup‐ plied with _makeindex_). _Tools_ _for_ _Printing_ _Indices_, Jon L. Bentley and Brian W. Kernighan, _Electronic_ _Publishing_ _—_ _Origination,_ _Dissemination,_ _and_ _Design_, [1(1)](https://www.chedong.com/phpMan.php/man/1/1/markdown), 3–18, June 1988 (also available 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. Manual page extensively revised and corrected, and [_troff_(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown) examples created by Rick P. C. Rodgers, UCSF School of Pharmacy. ## ACKNOWLEDGMENTS Leslie Lamport contributed significantly to the design of MakeIndex. Michael Harrison pro‐ vided valuable comments and suggestions. Nelson Beebe improved on the portable version, and maintained the source distribution for the TeX Users Group for many years. 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. The _LOG_ and _CONTRIB_ files in the _makeindex_ source distribution record other contributions. _makeindex_ is currently maintained as part of the TeX Live distribution (); please send bug reports to . TeX Live 12 November 2014 [_MAKEINDEX_(1)](https://www.chedong.com/phpMan.php/man/MAKEINDEX/1/markdown)