\documentstyle[twoside]{pamphlet}
\def\IdxTeX{Idx\TeX}
\pagestyle{headings}
\makeindex
\begin{document}
\coverstyle{userguide}
\title{\IdxTeX\ Program}
\author{R L Aurbach}
\authorfacts{CR\&DS MIS Group}
\version{Version 1.1}
\file{IdxTeX}
\begin{thetitle}

\begin{abstract}
The \IdxTeX\ program is used to automate the generation of an Index in a
\LaTeX\ document.  It uses the .IDX file generated by the \verb~\makeindex~
command to create a file which is \verb~\input~ in the document to generate
the Index.
\end{abstract}

\end{thetitle}

\pagenumbering{roman}
\tableofcontents

\pagenumbering{arabic}

\makeheading

\section{The Index Problem}

The \LaTeX\ text formatting program is an extremely versatile tool for the
generation of high-quality documents.  However, its handling of an Index is
incomplete.

\subsection{\LaTeX\ Index Processing}

To make an Index using \LaTeX, the writer includes the 
\verb~\makeindex~\index{\verb~\makeindex~ Command} command
in the preamble\index{Preamble} of the document.  This causes an auxiliary 
file (with file type .IDX\index{IDX File}) to be generated.  For every 
\verb~\index~\index{\verb~\index~ Command} command in the document, a
\verb~\indexentry~\index{\verb~\indexentry~ Command} command is written to 
the auxiliary file, containing the text supplied in the \verb~\index~ command
and the page number of the page on which the \verb~\index~ command occurred. 

It is then the writer's responsibility to use the auxiliary file to create the
series of commands needed to format an appropriate index and to insert these
commands into the document at the appropriate place.

The entire process is described in Sections~4.5 and C.10.5 of the {\em \LaTeX\ 
User's Guide and Reference Manual}.

\subsection{The \IdxTeX\ Solution}

While this procedure is capable of generating an effective, high-quality Index,
a substantial amount of work is required to convert the auxiliary .IDX file into
the appropriate set of commands.  The \IdxTeX\ program was written to automate
this manual part of the process.

\IdxTeX\ uses the .IDX\index{IDX File} auxiliary file to generate a new file
with file type .IND\index{IND File} which contains all of the necessary commands
to create an attractive, two-column index.  This .IND file may then be included
in the document at the appropriate place to generate the Index. 

The \IdxTeX\ program
\begin{itemize}

\item Generates\index{\IdxTeX\ Features>Complete Index Generation}
all of the commands necessary to build the Index, including the
\verb~\begin{theindex}~\index{theindex Environment} and \verb~\end{theindex}~
commands. 

\item Generates\index{\IdxTeX\ Features>Alphabetized, Two-Column Index}
an alphabetized, two-column index.

\item Supports \index{\IdxTeX\ Features>Three Levels of Indexing}
three levels of indexing --- index items, index subitems, and
index subsubitems.

\item Supports \index{\IdxTeX\ Features>Index Item Highlighting}
highlighting effects such as boldface, italics, etc., in the
index items, while maintaining proper alphabetization of entries.

\item Supports \index{\IdxTeX\ Features>Page Number Highlighting}
highlighting effects (boldface, italics, and underlining) of 
page numbers.

\item Supports \index{\IdxTeX\ Features>\verb~\verb~ Command Supported}
the use of \LaTeX\ commands, including \verb~\verb~ commands,
in the index items, while maintaining proper alphabetization of entries.

\end{itemize}

\section{Using \IdxTeX}

The \IdxTeX\ program is easy to use.  However, like B{\sc ib}\TeX, there are a
number of steps necessary to generate the index and to get it included properly
in your document.

\begin{infomap}

\item[Command \\ Definition]
The \IdxTeX\ program is implemented as a foreign DCL command.  The 
symbol\index{Defining the \IdxTeX\ Command} is defined as

\begin{verbatim}

        $ IdxTeX :== $TeX:IdxTeX

\end{verbatim}

\item[Preparing the \\ Document]
Include the \verb~\makeindex~\index{\verb~\makeindex~ Command}
command in the preamble\index{Preamble} area of the document
source file (i.e., between the \verb~\documentstyle~ and \verb~\begin{document}~
commands).  Also, include the appropriate \verb~\index~\index{\verb~\index~
Command} commands (as described below) in the source file.

\item[Generate \\ the IDX File]
Use \LaTeX\ to generate an initial form of the document.  \LaTeX\ will
generate an auxiliary file which has the same filename as the main document file
and a filetype of .IDX\index{IDX File}.

\item[Run \IdxTeX]
Use \IdxTeX\ to generate the formatted index file.\index{Syntax}

\begin{verbatim}

        $ IdxTeX   file  [/TOC={ ARTICLE | REPORT }]

\end{verbatim}

where ``file''\index{Syntax>Filename Parameter} is the filename of the .IDX 
file.  \IdxTeX\ generates a file with the same filename as the .IDX file and a
filetype of .IND\index{IND File}. 

The \verb+/TOC+ qualifier\index{Syntax>/TOC Qualifier} is optional.  If you
specify it, you must specify either the value \verb+ARTICLE+ or the value
\verb+REPORT+.  The /TOC qualifier is used to add an entry into the Table of
Contents for the Index.  The standard document styles ({\em article\/} and
{\em report\/}) do not automatically make a Table of Contents entry for the 
Index.  If you want the Index to be listed in the Table of Contents, you 
{\bf must} use the /TOC qualifier.  The value \verb+ARTICLE+ should be used
with documents which use the {\em article\/} document style or one of its 
derivative.  The value \verb+REPORT+ should be used with documents which use 
the {\em report\/} or {\em book\/} document styles. 

\item[Generate\\the Document]
Insert the command \verb+\input{file.IND}+ into
\index{\verb~\input{file.IND}~} your document source file just before the
\verb~\end{document}~ command. 

Finally, run the document through \LaTeX\ twice (to make sure that the Table of
Contents includes the page reference for the Index).  Your document is now
complete, including a formatted Index. 

\end{infomap}

\section{Special Features}

The \IdxTeX\ program attempts to perform all of the operations needed to 
generate an Index which you can be proud of.  Of course, the quality of the
Index is a function of the amount of effort you put into your writing --- the
program can only generate index entries for items you tell it to index for you.
But if you do a good job of generating index entries, \IdxTeX\ should do a good
job formatting them for you.

\begin{infomap}

\item[Index \\ Generation] \index{^\IdxTeX\ Features>Complete Index Generation}
The .IND\index{IND File} file generated by \IdxTeX\ contains all of the commands
necessary to generate the index.  

The first line in the file is a
\verb~\begin{theindex}~\index{\verb~\begin{theindex}~ Command} command.  This
sets up the Index environment according to your current \verb~\documentstyle~.
For example, in the {\em article\/} \verb~\documentstyle~, the index is an
unnumbered section.  In the {\em report\/} \verb~\documentstyle~, the index is
an unnumbered chapter.

The last line in the file is a \verb~\end{theindex}~\index{\verb~\end{theindex}~
Command} command.  This command ends the Index environment.  Between these lines
are found all of the commands needed to generate the Index.

\item[Alphabetical\\Index] \index{^\IdxTeX\ Features>Alphabetized, Two-Column
Index} The index is generated in an alphabetized, two-column format by major
index entry.  Special characters such as ``\verb~\~'' don't participate in the
alphabetization, so a term like \verb~\begin~ is indexed under ``B'', not
under ``\verb~\~''.

For clarity, the group of index entries which begin with one letter are set off
from the index entries beginning with the next letter of the alphabet with
vertical spacing and a heading.  See the index of this document for examples.

\item[Index Levels] \index{^\IdxTeX\ Features>Three Levels of Indexing}
Items are inserted into the Index by using the \verb~\index~ command.  For 
example, to index the term ``entry'', enter \verb~\index{Entry}~\index{Entry}
at the appropriate place in the text of your document.  The information entered
as the argument to \verb~\index~\index{\verb~\index~ Command} will appear as 
specified (special visual effects are discussed below).  The page number on
which the \verb~\index~ command appeared will be displayed. 

This approach generates a simple Index.  That is, all terms are on the same
footing.  It is often convenient, however, to have terms appear as subindices
under an index term.  For example, if you were discussing ``Commands'', you
might wish to have separate index entries for ``Add Command'' and ``Change
Command''.  However, in addition, you should create an index entry for 
``Commands'' and place ``Add'' and ``Change'' as subindices under it.  This 
technique generates an index which is more helpful for the person looking for
information.

\IdxTeX\ actually supports three such levels of indexing --- a main index item,
a subindex item, and a subsubindex item.  In analogy to the indexing 
capabilities of the RUNOFF program, the 
``\verb~>~''\index{SubIndex (\verb$>$) Command}
\index{\verb~\index~ Command>Use of \verb$>$}
symbol is used to separate
the index term from the subindex term and the subindex term from the subsubindex
term in the \verb~\index~ command.  

For example,

\begin{verbatim}

        \index{Top Level Item>SubItem>SubSubItem}

\end{verbatim}

\index{Top Level Item>SubItem>SubSubItem}generates such three-level deep
index entry in the index.  Look at the index of this document to see it.

There are two important points to note here.

\begin{itemize}
\item First, each \verb~\index~ command generates a single page number reference
in the index.  The page number is associated with the lowest level of the index
specified.  Therefore, in this example, the page number is associated with the
``SubSubItem'' entry, not any of the higher entries.  If you want page numbers
at all levels, you must use several \verb~\index~ commands.

All subitems are displayed in alphabetical order below their top-level item.
All subsubitems are displayed in alphabetical order below their second-level
item.

\item Second, the \verb~>~ symbol used to separate items of different levels
is normally a math symbol.  As such, it is possible that you will want to
index a math expression which contains it.  This is okay, because \IdxTeX\
is sensitive to the use of \$ as a command to enter or leave math mode and
will not consider \verb~>~ a level separator unless it is {\em not\/} in math
mode.

\end{itemize}

\item[Item \\ Highlighting] \index{^\IdxTeX\ Features>Index Item Highlighting}
Sometimes it is desirable to make a word or phrase (or even an entire index
entry) stand out in the Index.  This is referred to as Item Highlighting, and
is an effective technique to make the Index more useful, if not overdone.

Use the normal \LaTeX\ commands to generate the desired highlighting.  For 
example, the following commands appear in this document.

\begin{verbatim}

        \index{Highlighting>A {\bf boldface} entry}
        \index{Highlighting>An {\em italic\/} entry}

\end{verbatim}

\index{Highlighting>A {\bf boldface} entry}\index{Highlighting>An {\em italic\/}
entry} Look for the result in the index!

From the standpoint of \IdxTeX, the item, subitem, and subsubitem are processed
as different text elements.  Therefore, if you wish to highlight more than one
level of the index, you must handle each one independently.  That is,

\verb~\index{{\bf One>Two>Three}}~ \hfill WRONG!

is incorrect, but

\verb~\index{{\bf One}>{\bf Two}>{\bf Three}}~ \hfill CORRECT!

will produce the desired result.

\item[Page Number\\Highlighting] \index{^\IdxTeX\ Features>Page Number 
Highlighting}  Sometimes, when you are indexing the same term in many places in
a document, you may wish to help the reader decide which is the primary 
reference and which are secondary references.  One way of doing this is to
provide visual highlighting of important page numbers.

\IdxTeX\ provides a mechanism to cause a page number of a reference to be
printed in {\bf boldface}, in {\em italics}, or \underline{underlined}.  There
are three special characters recognized by \IdxTeX\ {\bf when they appear as the
first character of an \verb~\index~ command argument}.

\begin{itemize}
\item The \verb~^~ command\index{\verb~\index~ Command>Use of \verb~^~} is 
used to make the page number reference appear in {\bf boldface}. 
\item The \verb!~! command\index{\verb~\index~ Command>Use of \verb!~!} is 
used to make the page number reference appear in {\em italics}.
\item The \_\ command\index{\verb~\index~ Command>Use of \_} is used to make 
the page number reference appear \underline{underlined}.
\end{itemize}

For example, in this document, the following \verb~index~ commands appear.

\begin{verbatim}

        \index{^Page Numbers>boldface}
        \index{~Page Numbers>italics}
        \index{_Page Numbers>underlined}

\end{verbatim}

\index{^Page Numbers>boldface}\index{~Page Numbers>italics}
\index{_Page Numbers>underlined}  Look at the index to see the results!

\begin{note}
These special characters must appear as the first character of an \verb~\index~
command argument.  If they appear after a \verb~>~ (i.e., as the first character
of a subindex entry or a subsubindex entry), they will not work. In fact, they
will cause a \LaTeX\ error!
\end{note}

\item[Special \\ \LaTeX \\ Commands]
\index{^\IdxTeX\ Features>\verb~\verb~ Command Supported}
Occasionally (such as in this document), it is desirable to include \LaTeX\
commands in the index in an index entry to create special effects or because
the command itself is being referenced.  \IdxTeX\ supports this --- just type
the entries as you would expect them to appear.

The trick is that \IdxTeX\ tries to alphabetize your entries correctly.  This
means that it must figure out how to alphabetize \LaTeX\ commands, whose 
displayed images are different than the character strings which generate them.

The following rules attempt to indicate how \IdxTeX\ treats \LaTeX\ commands
when it finds them.

\begin{itemize}
\item Accents are ignored when figuring out how to spell a term.  This means,
for example, that ``\verb+se\~{n}or+'' is treated as if it were spelled 
``\verb+senor+''.

\item Text contained in ``\verb~\verb~'' or ``\verb~\verb*~'' commands are
spelled as if the command were not present.  For example, the index entry
``\verb~\verb+\Pi+~'' is treated as if it were spelled ``\verb~\Pi~''.

\item Commands which affect font size or type style are ignored when figuring
out how something is spelled.  For example, ``\verb~\sc term~'' is treated as if
it were spelled ``\verb~term~''.  Note, however, that this applies only to
spelling. The term will be displayed as you want it.  Note further that \IdxTeX\
will not properly alphabetize a term like ``\verb~The \verb+\bf+ Command~'' ---
the program will alphabetize it as if it were written ``\verb~The Command~''. 

\item Case is ignored in spelling considerations.  Terms like ``large'' and
``Large'' are treated as identical.  Only one reference (with two page numbers)
will appear --- the first form seen will be used.

\item \IdxTeX\ ignores the grouping commands ``\{'', ``\}'', and ``\$'' when
placing a term in alphabetical order.  On the other hand, the sequences which
generate explicit characters (i.e., ``\verb+\{+'', ``\verb+\}+'', and 
``\verb+\$+'') are handled as if they were the characters themselves --- the
``\verb+\+'' is ignored for spelling. For example, the term ``\verb~{\bf The \{
Command}~'' will be alphabetized as if it were spelled ``\verb~The { Command~''.

\item All ``\verb~\~'' characters are ignored.  The term ``\verb~\begin~'' will
be located in the Index as if it began with the ``b'', not the ``\verb~\~''. 

\end{itemize}

\end{infomap}
\input{idxtex.ind}
\end{document}