summaryrefslogtreecommitdiff
path: root/texmf-dist/doc/latex/siam/makeindx/makeindx.tex
diff options
context:
space:
mode:
Diffstat (limited to 'texmf-dist/doc/latex/siam/makeindx/makeindx.tex')
-rw-r--r--texmf-dist/doc/latex/siam/makeindx/makeindx.tex474
1 files changed, 474 insertions, 0 deletions
diff --git a/texmf-dist/doc/latex/siam/makeindx/makeindx.tex b/texmf-dist/doc/latex/siam/makeindx/makeindx.tex
new file mode 100644
index 00000000..8e33eb0d
--- /dev/null
+++ b/texmf-dist/doc/latex/siam/makeindx/makeindx.tex
@@ -0,0 +1,474 @@
+% 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}{{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}