path: root/indexing/makeindex/doc/makeindex.tex

% makeindex.tex -- released 17  February 1987
% Copyright(c) 1987 by Leslie Lamport
%   for LaTeX version 2.09
%
\documentstyle[11pt]{article}

%&v&\verb|#|&
%&i&\verb|\index{#}|&
%&t&{\tt #}&
\newcommand{\MakeIndex}{{\it MakeIndex\/}}
\newcommand{\fn}{}
\newcommand{\ff}


% Definition of the iexample environment and \sindex command.  
% They are used as follows:
%   \begin{iexample}
%      Page 7   & \verb|\index{foo}|\\
%      Page 22  & \verb|\index{bar}|
%   \sindex
%      bar, 22 \\
%      foo, 7
%   \end{iexample}
\newenvironment{iexample}{\begin{quote}
   \begin{tabular}[t]{@{}ll||@{\hspace{1em}}}}{\end{tabbing}\end{minipage}
   \end{quote}}
\newcommand{\sindex}{\end{tabular}\hspace{1em}\begin{minipage}[t]{\textwidth}
   \begin{tabbing}}

\newcommand{\sitem}{\hspace*{20pt}}
\newcommand{\ssitem}{\hspace*{30pt}}


\title{\MakeIndex: An Index Processor For \LaTeX}

\author{Leslie Lamport}
\date{17 February 1987}
\begin{document}
\maketitle

\section{How to Use \MakeIndex}

\MakeIndex\ is a program for
making an index in a document generated with \LaTeX. The first step in
producing the index is to put the necessary \verb|\index| commands in
your document, as described in the next section.  Here, I describe how
to generate the index after the \verb|\index| commands are in place.

Let's suppose that the root file of your document is {\tt myfile.tex}.
You must make the following changes to your document:
\begin{itemize}

\item Add the {\tt makeidx} document-style option to the list of
options in the \verb|\documentstyle| command.  (See page 21 of the
\LaTeX\ manual.)

\item Put a \verb|\makeindex| command in the preamble (between the 
  \linebreak%%%%%
\verb|\documentstyle| and \verb|\begin{document}| commands).

\item Put a \verb|\printindex| command where you want the index to
appear---usually at the end, right before the \verb|\end{document}|
command.
\end{itemize}
You then run \LaTeX\ on your entire document, causing it to
generate the file {\tt myfile.idx}, which I will call the {\tt idx} file.
Next, run the \MakeIndex\ program by
typing the following Unix command:
\begin{quote}
    {\tt makeindex myfile.idx}
\end{quote}
This produces the file {\tt myfile.ind}, which I will call the {\tt
ind} file.  If \MakeIndex\ generated no error messages, you can now rerun
\LaTeX\ on your document and the index will appear.  (You can remove
the \verb|\makeindex| command first so the {\tt idx} file is not
regenerated.)  If there were error messages, see
Section~\ref{sec:errors}.

By reading the index, you may discover additional mistakes.  These should be
corrected by changing the appropriate \verb|\index| commands in the
document and regenerating the {\tt ind} file.  If there are
problems that cannot be corrected in this way, you can always edit 
the {\tt ind} file directly.  However, such editing is to be
avoided because it must be repeated every time you generate a new
version of the index.


\section{How to Generate Index Entries}

\subsection{When, Why, What, and How to Index}

It's tempting to generate the index as you write the document.  Resist
the temptation.  It is virtually impossible to obtain any consistency
in an index that is  generated in this way.

An index is there to help the reader find what he's looking for.  With
this in mind, common sense can help in figuring out what should be in
the index and how it should be organized.  Since it's often hard to
distinguish common sense from equally common nonsense, professional
advice is useful.  Many style guides discuss indexing; the pamphlet
{\em Indexing Your Book\/} by Sina Spiker (The University of Wisconsin
Press, 1954) is, according to its subtitle, ``A Practical
Guide for Authors''.  

Unfortunately, these guides to indexing seem to have been written when
high tech meant using a ball-point pen instead of a quill, so their
advice on the mechanics of creating an index revolve around how to
stack your $3\times 5$ index cards.  You'll have to figure out your own
method of using the computer to lighten the chore.  An alphabetical
list of every word in your document, with duplicates removed, is not a
bad place to start.  If your system has Howard Trickey's {\tt delatex}
program, then the following Unix command generates such a list from the
file {\tt myfile.tex} and puts it on the file {\tt foo}:
\begin{quote}
\tt delatex myfile.tex | sort -uf > foo
\end{quote}

The computer is only a tool; it can't write the index for you.  It may
be easy to choose which words are important and mechanically generate
an index citing every occurrence of those words, but the resulting
index will not be as useful to the reader as one prepared with more
care.




\subsection{The Basics}

Each \verb|\index| command causes \LaTeX\ to write an entry on the {\tt
idx} file.  The following example shows some simple
\verb|\index| commands and the index entries that they produce.  The
page number refers to the page containing the text where the
\verb|\index| command appears.\footnote{To avoid any ambiguity if a
page break occurs right at an {\tt \symbol{'134}index} command, it's a
good idea to attach the command to a word instead of putting it between
words.}
\begin{iexample}
Page ii    & \verb|\index{Alpha}| \\
Page viii: & \verb|\index{alpha}| \\
Page ix:   & \verb|\index{alpha}| \\
           & \verb|\index{Alphabet}| \\
Page 22:   & \verb|\index{alpha}|    \\
           & \verb|\index{alphas}| \\
Page 23:   & \verb|\index{alphabet}| \\
           & \verb|\index{alphabet}| \\
Page 24:   & \verb|\index{alpha bet}|
\sindex
Alpha, ii \\
alpha, viii, ix, 22 \\
alpha bet, 24\\
Alphabet, ix\\
alphabet, 23\\
alphas, 22
\end{iexample}
Note that the duplicate \verb|\index{alphabet}| commands on
page 23 produce only one ``23'' in the index.


To produce a subentry, the argument of the \verb|\index|
command should contain both the main entry and the subentry, separated
by a \verb|!| character.
\begin{iexample}
Page 7: & \verb|\index{gnat!size of}| \\
Page 32: & \verb|\index{gnat}|         \\
Page 35: & \verb|\index{gnat!anatomy}| \\
         & \verb|\index{gnus!good}|    \\
Page 38: & \verb|\index{gnus!bad}| \\
 & 
\sindex
gnat, 32 \\
\sitem anatomy, 35 \\
\sitem size of, 7\\
gnus \\
\sitem bad, 38\\
\sitem good, 35
\end{iexample}
You can also have subsubentries.
\begin{iexample}
Page 8: & \verb|\index{bites!animal!gnats}| \\
Page 10: & \verb|\index{bites!animal!gnus}| \\
Page 12 : & \verb|\index{bites!vegetable}| \\
 & \\
 & 
\sindex
bites              \\
\sitem animal      \\
\ssitem gnats, 8   \\
\ssitem gnus, 10   \\
\sitem vegetable, 12
\end{iexample}
\LaTeX\ and \MakeIndex\ support only three levels of indexing; you
can't have subsubsubentries.


To specify a page range, put an \verb/\index{...|(}/
command at the beginning of the range and an \verb/\index{...|)}/
command at the end of the range.
\begin{iexample}
Page vi: & \verb/\index{gnat|(}/ \\
Page x:  & \verb/\index{gnat|)}/ \\
Page 22: & \verb|\index{gnat}| \\
         & \verb/\index{gnus!bad|(}/ \\
         & \verb/\index{gnus!bad|)}/ \\
Page 28: & \verb/\index{gnus!good|(}/ \\
Page 30: & \verb|\index{gnus!good}| \\
Page 32: & \verb/\index{gnus!good|)}/ 
\sindex
gnat, vi--x, 22 \\
gnus \\
\sitem bad, 22\\
\sitem good, 28--32
\end{iexample}
Note that \MakeIndex\ does the right thing when both ends of the range
fall on the same page.\footnote{The use of ``28ff.'' rather than
``28--32'' is frowned upon by the experts.}

Sometimes, you want to add a cross-reference with no page
number.  This is done as follows;
\begin{iexample}
Page 2: & \verb|\index{at}| \\
Page 2: & \verb/\index{at!bat|see{bat, at}}/
\sindex
at, 2 \\
\sitem bat, {\em see\/} bat, at
\end{iexample}
Since the ``see'' entry does not print any page number, it doesn't
matter where the \verb/\index{...|see{...}}/ command goes, so
long as it follows the \verb|\begin{document}| command.  You
might want to put all such cross-referencing commands in one place.


If you specify an entry of the form $\sigma$\verb|@|$\tau$, the string
$\sigma$ determines the alphabetical position of the entry, while the
string $\tau$ produces the text of the entry.
\begin{iexample}
Page 44: & \verb|\index{twenty}| \\
Page 46: & \verb|\index{twenty-one}| \\
Page 55: & \verb|\index{twenty@xx}| 
\sindex
twenty, 44 \\
xx, 55 \\
twenty-one, 46
\end{iexample}
This feature is useful because the argument of the \verb|\index|
command provides the actual input string that \LaTeX\ uses to generate
the index entry.  In the following example, the input \verb|$\alpha$|
produces the symbol $\alpha$,
\begin{iexample}
Page 12: & \verb|\index{alphas}| \\
Page 13:  & \verb|\index{alpha}| \\
Page 14: & \verb|\index{alpha@$\alpha$}| 
\sindex
alpha, 13 \\
$\alpha$, 14 \\
alphas, 12
\end{iexample}
Similarly, the command \verb|\index{gnu@{\bf gnu}}| produces
a boldface {\bf gnu} index entry.

In some indexes, certain page numbers are specially formatted---for
example, an italic page number may indicate the primary reference, and
an {\em n\/} after a page number may denote that the item appears in a
footnote on that page.  \MakeIndex\ makes it easy to format an
individual page number any way you want.  For any string of characters
$\sigma$, the command \verb/\index{...|/$\sigma$\verb|}| produces a
page number of the form \verb|\|$\sigma$\verb|{|$n$\verb|}|.
Similarly, the command \verb/\index{...|(/$\sigma$\verb|}| may produce
a page number of the form \verb|\|$\sigma$\verb|{|$n$--$m$\verb|}|.
Thus, suppose the document contains the following command definitions:
\begin{quote}
\verb|\newcommand{\ii}[1]{{\it #1}}| \\
\verb|\newcommand{\nn}[1]{#1n}| 
\end{quote}
We could then have:
\begin{iexample}
Page 3: & \verb/\index{gnat|ii}/ \\
Page 4: & \verb/\index{gnat|nn}/ \\
Page 5: & \verb/\index{gnu}/   \\
Page 44: & \verb/\index{gnu|(ii}/  \\
Page 46: & \verb/\index{gnu|)}/  
\sindex
gnat, {\em 3}, 4n \\
gnu, 5, {\em 44--46}
\end{iexample}
The ``see'' option is a special case of this facility, where the
\verb|\see| command is predefined by the {\tt makeidx} document-style
option.


\subsection{The Fine Print}

Commands in an index entry are expanded when the index is typeset,
not when the {\tt idx} file is written.  Hence, the command
\verb|\index{\gnu}| produces an entry that is alphabetized by
\verb|\gnu|, regardless of how the \verb|\gnu| command is defined.

Recall that special characters like \verb|\| may appear in the argument
of an \verb|\index| command only if that command is not itself
contained in the argument of another command.  This is most likely to
be a problem when indexing items in a footnote.  Even in this case,
robust commands can be placed in the ``\verb|@|'' part of an entry, as
in \verb|\index{gnu@{\it gnu}}|, and fragile commands can be used
if protected with the \verb|\protect| command.\footnote{In
versions of \LaTeX\ released before 3 February 1987, you must
use the {\tt\symbol{'134}string} command instead of
{\tt\symbol{'134}protect}.}

Remember that the argument of an \verb|\index| command must always have
matching braces, where the brace in a \verb|\{| or \verb|\}| command
counts.

\MakeIndex\ assumes that all page numbers are either arabic or lower-case
roman numerals; it assumes that pages numbered with roman numerals
precede those numbered with arabic numerals.

To put a \verb|!|, \verb|@|, or \verb/|/ character in an index entry,
{\em quote\/} it by preceding the character with a \verb|"|.  More
precisely, any a character is said to be quoted if it follows an
unquoted \verb|"| that is not part of a \verb|\"| command.  A quoted
\verb|!|, \verb|@|, or \verb/|/ character is treated like an 
ordinary character rather than having its usual meaning.   The
\verb|"| preceding a quoted character is deleted before the
entries are alphabetized.
\begin{iexample}
Page 2: & \verb|\index{exclaim ("!)}| \\
Page 3: & \verb|\index{exclaim ("!)!loudly}| \\
Page 4: & \verb|\index{fur@f\"{u}r}| \\
Page 5: & \verb|\index{quote (\verb+""+)}|
\sindex
exclaim (!), 2 \\
\sitem loudly, 3\\
f\"{u}r, 4\\
quote (\verb+""+), 5
\end{iexample}


\MakeIndex\ regards spaces as ordinary characters when alphabetizing the
entries and deciding whether two entries are the same.  Thus, letting
``\verb*| |'' denote a space character, the commands
\verb*|\index{gnu}|, \verb*|\index{ gnu}|, and \verb*|\index{gnu }|
produce three separate entries, the first appearing near the beginning
of the index, since \verb*| | comes before any letter in \MakeIndex's
``alphabetical'' order.  All three entries look the same when
printed, since \LaTeX\ ignores extra spaces in the input.  Similarly,
 \verb*|\index{a space}| and \verb*|\index{a  space}| produce two
different entries that look the same when printed.  Do not
split the argument of an \verb|\index| command across lines in the
input file.



\section{Error Messages} \label{sec:errors}

\MakeIndex\ types out on the terminal the number of lines read and
written and how many errors were found.  Message to identify the error
are written on a file with extension {\tt ilg}.  There are two phases
in which \MakeIndex\ can produce error messages: when it is reading the
{\tt idx} file, and when it is writing the {\tt ind} file.  Each error
message prints the nature of the error followed by a line number,
identifying where in the file the error occurs.  In the reading phase,
the line number refers to the {\tt idx} file; in the writing phase, it
refers to the {\tt ind} file.

\subsection{Errors in Reading Phase}

\subsubsection*{\tt Extra `!' at position ...}

The \verb|\index| command's argument has more than two unquoted
\verb|!| characters.  Perhaps some of them should be quoted.

\subsubsection*{\tt Extra `@' at position ...}

The \verb|\index| command argument has two or more unquoted \verb|@|
characters with no intervening \verb|!|.  Perhaps one of the \verb|@|
characters should be quoted.

\subsubsection*{\tt Extra `|' at position ...}

The \verb|\index| command's argument has more than one unquoted \verb|!|
characters.  Perhaps the extras should be quoted.

\subsubsection*{\tt Illegal null field}

The \verb|\index| command argument doesn't make sense because some
string is null that shouldn't be.  The command \verb|\index{!big}| will
produce this error, since it specifies a subentry ``big'' with no
entry.  Similarly, the command \verb|\index{@big}| is incorrect because
it specifies a null string for alphabetizing.

%\subsubsection*{\tt No \symbol{'134}indexentry}
%
%Each line of an {\tt idx} file written by \LaTeX\ should contain an
%\verb|\indexentry| command.  \MakeIndex\ has found a line in the {\tt idx}
%file that does not contain an \verb|\indexentry| command.  The {\tt
%idx} file has probably been corrupted.
%
%\subsubsection*{\tt Missing \symbol{'173}}
%
%\MakeIndex\ believes that the braces in the argument of the \verb|\index|
%command are not properly matched.  Since \LaTeX\ must
%have thought that the braces were properly matched, the problem 
%is probably due to a corrupted {\tt idx} file.
%
%\subsubsection*{\tt Missing \symbol{'175}}
%
%See ``{\tt Missing \symbol{'173}}'' error.

\subsubsection*{\tt Argument ... too long (max 1024).}

Your document contained an \verb|\index| command with a very long
argument.  You probably forgot the right brace that was supposed
to delimit the argument.

\subsubsection*{Other errors}

\MakeIndex\ can produce a variety of other error messages indicating
that something is seriously wrong with the {\tt idx} file.  If you
get one, it probably means that the {\tt idx} file was corrupted in
some way.  If \LaTeX\ did not generate any errors when it created
the {\tt idx} file, then it is highly unlikely to have produced
a bad {\tt idx} file.  If it did, you'll have to examine the
{\tt idx} file to figure out what went wrong.


\subsection{Errors in Writing Phase}

\subsubsection*{\tt Unmatched range opening operator}

An \verb/\index{...|(}/ command was not followed by a matching
  \linebreak%%%%%
\verb/\index{...|)}/ command.  The ``\verb|...|'' in the two
commands must be completely identical.


\subsubsection*{\tt Unmatched range closing operator }

An \verb/\index{...|(}/ command was not preceded by a matching
  \linebreak%%%%%
\verb/\index{...|)}/ command. 

\subsubsection*{\tt Extra range opening operator }

Two \verb/\index{...|(}/ commands appear in the document with no intervening
\verb/\index{...|)}/ command.



\subsubsection*{\tt Inconsistent page encapsulator ... within range}

\MakeIndex\ has been instructed to include a page range for an entry
and a single page number within that range that is formatted
differently---for example, by having a 
\verb+\index{gnu|ii}+ command between a \verb+\index{gnu|(}+
and a \verb+\index{gnu|)}+ command.


\subsubsection*{\tt Conflicting entries}

\MakeIndex\ thinks it has been instructed to print the same page number
twice in two different ways---for example, by the commands
\verb|\index{gnu}| and \verb/\index{gnu|(see{...}}/ appearing on the
same page.



\section*{Acknowledgements}

\MakeIndex\ is a C program written by Pehong Chen, with a little
advice from me.  It was inspired by a program written by Mike Urban,
which was based on a program written by Marshall Rose.  Perhaps someday
someone will rewrite \MakeIndex\ in Web, making it available to all
\LaTeX\ users.

\end{document}