.* Makeindx help file for CMS (heavily hacked up version of manpage
.* from Berkeley.
.* This file should be run through the Waterloo Script processor with
.* the memo option and then renamed to MAKEINDX HELPCMS if it is
.* changed.
.* Apologies to LaTeX fans and other document structure purists...this
.* file is truly a quick and dirty job.
.if &syspdev = TERM .th .do begin
.cm .ch /›|/|/
.cm .ch /›%/%/
.do end
.dc rb &
.ju off
.ll 73
.tm 0
.bm 0
.pl 1
.oc .cs 1 on;
.la makeindx
.sp
.il 3
›|makeindx›%is a general purpose index processor.  It takes one or more
raw index files (normally generated by a formatter), sorts the entries,
and produces the actual index file.  It is not dependent on any particular
format of raw index file, although the›|.idx›%file
(that is, the file with filetype›|IDX)›%generated
by LaTeX is default.  Up to three levels (0, 1, and 2) of subitem nesting
within the same entry is supported.
The input format may be redefined in a style file
so that raw index or glossary output from other formatters may be processed.
The style file also defines the style of output index file.
See the file TEST TEX for information on how to use makeindx
with LaTeX.
.il 3
Makeindx was originally written in a Unix environment and then
ported to CMS...in the following discussion I have tried to
keep separate information about makeindx itself and information
specifically about the CMS implementation of makeindx by putting
the latter in parentheses.
The current port of makeindx for CMS is a preliminary one...use at
your own risk!  Comments, criticisms or complaints about the
implementation should be directed to Chris Carruthers
(CJC@UOTTAWA.BITNET).   See also the AUTHOR section at the end of the
help file.
(N.B., the original name for this program was makeindex but CMS
limits program names (and any filename) to 8 characters so...)
 
.br;.oc .cs 1 off;
.sp;.oc .cs 2 on;
.la Format:
.sp
makeindx [-ilqrc] [-s sty] [-o ind] [-t log] [-p no] [idx0 idx1 idx2 ...]
.br;.oc .cs 2 off;
.sp;.oc .cs 3 on;
.la Parameters:
(N.B., in the following discussion the words stdin, stdout and stderr
reflect makeindx's C and Unix origins.  In CMS with Waterloo C these
all refer to the same device by default:
the interactive terminal; the use of
these devices allows for 'redirection' of input and output, that is,
input (or output) can be requested from (or to) a file.  Not sure
why this is useful in the context of makeindx since these features are
already part of makeindx but makeindx makes use of these devices
so it makes sense to allow for redirection in the CMS implementation.
As implemented redirection is requested
with the use of the characters '<' and '>': one puts
'<fileidi>fileido' at the end of the commandline
where fileidi is the CMS fileid requested for input
and fileido is the CMS fileid requested for output.   Either input
or output redirection can be requested.  A redirection request is
meaningful only
if stdin for input (or stdout for output) is being used by
the program.  If the program is using stdin and redirection
is not requested then input is from the terminal and to end input
you push PF3.)
.sp;.of 10
›|-i›%&&&&&
Use›|stdin›%as the input file.  When this option is specified and
the›|-o›%is not, output is written to›|stdout.›%
.sp;.of 10
›|-l›%&&&&&
Use letter ordering.  Default is word ordering (explained in
the›|ORDERING›%section).
.sp;.of 10
›|-q›%&&&&&
Quiet mode, send no messages to›|stderr.›% By default progress and
error messages are sent to›|stderr›%as well as the transcript file.
The›|-q›%option disables the›|stderr›%messages.
.br
(N.B.,›|stderr›%in
the CMS implementation of makeindx means the terminal.)
.sp;.of 10
›|-r›%&&&&&
Disable implicit page range formation.  By default three or more successive
pages will be automatically abbreviated as a range
(e.g. 1--5).  The›|-r›%option disables it,
making the explicit range operators the only way to create
page ranges (see the›|SPECIAL&EFFECTS›%section below).
.sp;.of 10
›|-c›%&&&&&
Enable blank compression.  By default every blank counts in the
index key.  The›|-c›%option ignores leading and trailing blanks and tabs
and compresses intermediate ones to a single space.
.sp;.of 10
›|-s›| sty›%
Take›|sty›%as the style file.  There is no default for the style file
name.  The environment variable INDEXSTYLE defines the path where
the style file should be found.
.sp;.of 10
›|-o›| ind›%
Take›|ind›%as the output index file.  By default the file name base of
the first input file›|idx0›%concatenated with the
extension›|.ind›%is used as the output file name.
.sp;.of 10
›|-t›| log›%
Take›|log›%as the transcript file.  By default the file name base
(in CMS this means the filename) of
the first input file›|idx0›%concatenated with the
extension›|.ilg›%is used as the transcript file name.
.sp;.of 10
›|-p›| no›%&
Set the starting page number of the output index file to
be›|no.›% This is useful when the index file is to be formatted separately.
Other than pure numbers, three special cases are allowed
for›|no:&any,&odd,›%and›|even.›% In
these special cases, the starting
page number is determined by retrieving the last page number
from the source log file.  The source log file name is determined by
concatenating the file name base of the first raw index
file›|(idx0)›%with the extension›|.texlog.›% The
last source page is obtained by
searching backward in the log file for the first instance of a number included
in›|[...].›% If a page number is missing or the log file is not
found, no attempt will be made to set the starting page number.
(N.B., in the CMS implementation this does not seem to be to useful
since the texlog created by the CMS version of TeX does not have this
number in the expected place.)
The meaning of each of these cases follows.
.sp;.cm R start
.sp;.of 10
›|any›%&&&&
The starting page is the last source page number plus 1.
.sp;.of 10
›|odd›%&&&&
The starting page is the first odd page following the last source page number.
.sp;.of 10
›|even›%&&&
The starting page is the first even page following the last source page number.
.sp;.cm R end
.sp;.of 10
›|idx0...›%
This is the name of the raw input file that makeindx should use to
generate the index.   It can be specified in the CMS implementation
as›|fn›%or›|fn.ft›%or›|fn.ft.fm›%where ›|fn›%is the filename,›|ft›%is
the filetype and ›|fm›%is the filemode of the file in question.
Unless specified otherwise, the file name base of the first input
file›|(idx0)›%is used to determine other related input/output files.
For each input file name specified, the name itself is first used.  If not
found and the name has no extension part, it is concatenated
with the›|.idx›%extension (N.B., in the CMS implementation 'extension'
means filemode).  If this again fails, the program aborts.
.of 0
.br;.oc .cs 3 off;
.sp;.oc .cs 5 on;
.la Notes:
.sp
.la STYLE FILE
The style file format is very simple.  It is a list
of›|<specifier,&attribute>›%pairs.
There are two types of specifiers (input and output).
The pairs don't have to obey any particular order in the file.
A line lead by `%' is a comment.  The following is a list of
all the specifiers and their respective arguments where <string> is an
arbitrary string delimited by double quotes ("..."),
<char> is a single letter embraced by
single quotes ('...'), and <number> is a nonnegative integer.
The maximum length of a <string> is 144.  Notice that a backslash
must be escaped (by an extra backslash) in the string quotation.
Anything not specified in the style file
will be assigned a default value, which is shown at the rightmost
column.
This file can reside anywhere in the path defined by the environment
variable INDEXSTYLE.
(In the CMS implementation this 'path' is specified by using GLOBALV
(see the GLOBALV help file for more information)
and
should be a valid filemode or '*' as follows:
.br
  GLOBALV SELECT MAKEINDX SET INDEXSTYLE fm
.br
where›|fm›%is the filemode required.  If a filemode is specified
explicitly on the command line any path which is specified has no
effect.)
.il 3
(N.B., in the style file there are some characters that cannot be
specified directly ('\' is specified as '\\') or that are more
conveniently expressed symbolically (to get a blank line in the output
file use '\n', to get a tab use '\t').  The reason for this is that
makeindx was written in C and the above correspond to the conventions
used for these characters in C.  Most any C manual or reference
should have a complete list of these so called escape characters.)
.sp
›|Input Style Specifiers›%
.tb set $
.tb 10 40
$›|keyword›% <string> $ "\\indexentry"
.sp;.cm R start
This is the command which tells›|makeindx›%that its argument is
an index entry.
.sp;.cm R end
.tb 10 40
$›|arg_open›% <char> $ '{'
.sp;.cm R start
This is the opening delimiter for the index entry argument.
.sp;.cm R end
.tb 10 40
$›|arg_close›% <char> $ '}'
.sp;.cm R start
This is the closing delimiter for the index entry argument.
.sp;.cm R end
.tb 10 40
$›|range_open›% <char> $ '('
.sp;.cm R start
The opening delimiter indicating the beginning of an explicit page range.
.sp;.cm R end
.tb 10 40
$›|range_close›% <char> $ ')'
.sp;.cm R start
The closing delimiter indicating the end of an explicit page range.
.sp;.cm R end
.tb 10 40
$›|level›% <char> $ '!'
.sp;.cm R start
The delimiter which denotes a new level of subitem.
.sp;.cm R end
.tb 10 40
$›|actual›% <char> $ '@'
.sp;.cm R start
The symbol which indicates that the next entry is to appear in the actual
index file.
.sp;.cm R end
.tb 10 40
$›|encap›% <char> $ '|'
.sp;.cm R start
The symbol which indicates that the rest of the argument list
is to be used as the encapsulating command for the page number.
.sp;.cm R end
.tb 10 40
$›|quote›% <char> $ '"'
.tb 10 40
$›|escape›% <char> $ '\\'
.sp;.cm R start
The symbol which escapes the next letter, unless its preceding letter
is›|escape.›% In other words,›|quote›%is used to escape the letter
which immediately follows it.
But if it is preceded by›|escape,›%it does not escape anything.
Notice that the two symbols must be distinct.
.sp;.cm R end
.sp 1
sp
›|Output Style Specifiers›%
.tb 10 40
$›|preamble›% <string> $ "\\begin{theindex}\n"
.sp;.cm R start
The preamble of actual index file.
.sp;.cm R end
.tb 10 40
$›|postamble›% <string> $ "\n\n\\end{theindex}\n"
.sp;.cm R start
The postamble of actual index file.
.sp;.cm R end
.tb 10 40
$›|setpage_prefix›% <string> $ "\n  \\setcounter{page}{"
.sp;.cm R start
The prefix of the command which sets the starting page number.
.sp;.cm R end
.tb 10 40
$›|setpage_suffix›% <string> $ "}\n"
.sp;.cm R start
The suffix of the command which sets the starting page number.
.sp;.cm R end
.tb 10 40
$\|group_skip\% <string> $ "\n\n  \\indexspace\n"
.sp;.cm R start
The vertical space to be inserted before a new group begins.
.sp;.cm R end
.tb 10 40
$›|lethead_prefix›% <string> $ ""
.sp;.cm R start
The header prefix to be inserted before a new letter begins.
.sp;.cm R end
.tb 10 40
$›|lethead_suffix›% <string> $ ""
.sp;.cm R start
The header suffix to be inserted before a new letter begins.
.sp;.cm R end
.tb 10 40
$›|lethead_flag›% <string> $ 0
.sp;.cm R start
The flag indicating the condition of inserting new letter header.
Default is 0, which means no header.  Positive means insert an uppercase
letter between prefix and suffix.  Negative means insert an lowercase letter.
.sp;.cm R end
.tb 10 40
$›|item_0›% <string> $ "\n  \\item "
.sp;.cm R start
The command to be inserted between two primary (level 0) items.
.sp;.cm R end
.tb 10 40
$›|item_1›% <string> $ "\n     \\subitem "
.sp;.cm R start
The command to be inserted between two secondary (level 1) items.
.sp;.cm R end
.tb 10 40
$›|item_2›% <string> $ "\n       \\subsubitem "
.sp;.cm R start
The command to be inserted between two level 2 items.
.sp;.cm R end
.tb 10 40
$›|item_01›% <string> $ "\n    \\subitem "
.sp;.cm R start
The command to be inserted between a level 0 item and a level 1 item.
.sp;.cm R end
.tb 10 40
$›|item_x1›% <string> $ "\n    \\subitem "
.sp;.cm R start
The command to be inserted between a level 0 item and a level 1 item.
The difference between this and previous is that in this case the level 0
item doesn't have any page numbers.
.sp;.cm R end
.tb 10 40
$›|item_12›% <string> $ "\n    \\subsubitem "
.sp;.cm R start
The command to be inserted between a level 1 item and a level 2 item.
.sp;.cm R end
.tb 10 40
$›|item_x2›% <string> $ "\n    \\subsubitem "
.sp;.cm R start
The command to be inserted between a level 1 item and a level 2 item.
The difference between this and previous is that in this case the level 1 item
doesn't have any page number.
.sp;.cm R end
.tb 10 40
$›|delim_0›% <string> $ ", "
.sp;.cm R start
The delimiter to be inserted between a level 0 key and its first page number.
Default is a comma followed by a blank.
.sp;.cm R end
.tb 10 40
$›|delim_1›% <string> $ ", "
.sp;.cm R start
The delimiter to be inserted between a level 1 key and its first page number.
Default is a comma followed by a blank.
.sp;.cm R end
.tb 10 40
$›|delim_2›% <string> $ ", "
.sp;.cm R start
The delimiter to be inserted between a level 2 key and its first page number.
Default is a comma followed by a blank.
.sp;.cm R end
.tb 10 40
$›|delim_n›% <string> $ ", "
.sp;.cm R start
The delimiter to be inserted between two page numbers for the same key
in any level.  Default is a comma followed by a blank.
.sp;.cm R end
.tb 10 40
$›|delim_r›% <string> $ "--"
.sp;.cm R start
The delimiter to be inserted between the starting and ending page numbers
of a range.
.sp;.cm R end
.tb 10 40
$›|encap_prefix›% <string> $ "\\"
.sp;.cm R start
The prefix for the command which encapsulates the page number.
.sp;.cm R end
.tb 10 40
$›|encap_infix›% <string> $ "{"
.sp;.cm R start
The prefix for the command which encapsulates the page number.
.sp;.cm R end
.tb 10 40
$›|encap_suffix›% <string> $ "}".
.sp;.cm R start
The prefix for the command which encapsulates the page number.
.sp;.cm R end
.tb 10 40
$›|line_max›% <number> $ 72
.sp;.cm R start
The maximum length of a line in the output beyond which a line wraps around.
.sp;.cm R end
.tb 10 40
$›|indent_space›% <string> $ "\t\t"
.sp;.cm R start
The space to be inserted in front of a wrapped line.  Default is two tabs.
.sp;.cm R end
.tb 10 40
$›|indent_length›% <number> $ 16
.sp;.cm R start
The length of›|indent_space.›% In the default case this is 16 (for 2 tabs).
.sp;.cm R end
.br;.oc .cs 5 off;
.sp;.oc .cs 6 on;
.la EXAMPLE
.il 3
The following example shows a style file called›|book.isty›%which
defines a stand-alone index for a book.  By stand-alone, we mean it can
be formatted independent of the main source.
.sp;.cm R start
.sp;.cm R start
›|preamble›%
.br
"\\documentstyle[12pt]{book}
.br
\\begin{document}
.br
\\begin{theindex}
.br
{\\small\n"
.sp 1
›|postamble›%
.br
"\n\n}
.br
\\end{theindex}
.br
\\end{document}\n"
.sp;.cm R end
.sp;.cm R end
.br;.cm .LP
Suppose a particular book style requires the index (as well as any
chapters) to start from an odd page number.
Given›|foo.idx›%as the raw index file,
the following command line produces an index in file›|foo-.ind.›%
.il 3
.sp;.cm R start
›|makeindx  -s book.isty  -o foo-.ind  -p odd  foo›%
.sp;.cm R end
.br;.cm .LP
The reason to use a non-default output file name is to avoid clobbering the
source output (presumably›|foo.dvi)›%because if the index is in
file›|foo.ind,›% its output will also be in›|foo.dvi›%as a result of
separate formatting using LaTeX.  In the example the index is
in›|foo-.ind,›% its output will be in›|foo-.dvi›%and thus introduces
no confusion.
.br;.oc .cs 6 off;
.sp;
.la ORDERING
.il 3
By default›|makeindx›%assumes›|word ordering.›% The›|-l›%option
turns it into›|letter ordering.›% The only difference is whether a blank
is treated as an effective letter or not.  In word ordering, a blank precedes
any letter in the alphabet, whereas in letter ordering, it doesn't count
at all.  This is best illustrated by the following example:
.sp;.cm R start
›|word order                   letter order›%
.br
 sea lion                     seal
.br
 seal                         sea lion
.sp;.cm R end
.br;.cm .LP
Numbers are sorted in numeric order.  For instance,
.sp;.cm R start
9 (nine),  123
.br
10 (ten), see Derek, Bo
.sp;.cm R end
.il 3
Letters are first sorted with uppercase and lowercase considered identical;
then, within identical words the uppercase letter precedes its lowercase
counterpart.
.il 3
Patterns lead by a special symbol precede numbers, which precede
patterns lead by a letter.  The symbol here refers to anything not in
the union of digits and English alphabet.  This includes those which follow
'z' in the ASCII (or EBCDIC, as in the CMS implementation) chart.  As a
special case, anything started with a digit but mixed with
non-digits is considered a symbol-leading pattern instead of a number.
.sp;
.la SPECIAL EFFECTS
In the normal case entries such as
.sp;.cm R start
\indexentry{alpha}{1}
.br
\indexentry{alpha!beta}{3}
.br
\indexentry{alpha!beta!gamma}{10}
.sp;.cm R end
in the raw index file will be converted to
.sp;.cm R start
\item alpha, 1
.br
  \subitem beta, 3
.br
    \subsubitem gamma, 10
.sp;.cm R end
in the output index file by›|makeindx.›%
Notice that the›|level›%symbol (`!') is used to delimit levels of nesting.
.il 3
It is possible to make an item appear in a designated form by
using the›|actual›%(`@') operator.  For instance,
.sp;.cm R start
\indexentry{alpha@{\it alpha\/}}{1}
.sp;.cm R end
will become
.sp;.cm R start
\item {\it alpha\/}  1
.sp;.cm R end
after the conversion.  The idea is that the pattern preceding `@' is
used as sort key, whereas the one following it is put in the actual
result.  However, the same key with and without the›|actual›%part
are regarded as distinct entries.
.il 3
It is also possible to encapsulate a page number with a designated
command using the›|encap›%(`|') operator.  For example, in the
default case,
.sp;.cm R start
\indexentry{alpha|bold}{1}
.sp;.cm R end
will be converted to
.sp;.cm R start
\item alpha \bold{1}
.sp;.cm R end
where \bold{n} will expand to {\bf n}.  This allows
the›|encap›%operator to be used to set pages
in different fonts, thereby conveying more information about whatever
being indexed.  For instance, given the same key the page where its definition
appears can be in one font while where its primary example
is given can be in another, with other ordinary appearances in a third.
Notice that in this example, the three output
attributes associated with page
encapsulation›|encap_prefix,&encap_infix,›%and›|encap_suffix›%correspond
respectively
to backslash, left brace, and right brace.  If this is to be formatted
by languages other than LaTeX, they would be defined differently.
.il 3
By the same token, the›|encap›%operator can be used to
make cross references in the index.  For instance,
.sp;.cm R start
\indexentry{alpha|see{beta}}{1}
.sp;.cm R end
will become
.sp;.cm R start
\item alpha \see{beta}{1}
.sp;.cm R end
in the output index file after the conversion, where
.sp;.cm R start
\see{beta}{1}
.sp;.cm R end
will expand to
.sp;.cm R start
{\it see\/} beta
.sp;.cm R end
Notice that in a cross reference like this the page number disappears.
Therefore, where to insert such a command in the source is immaterial.
.il 3
A pair of›|encap›%concatenated with›|range_open›%(`|(') and
with›|range_close›%(`|)') creates an explicit page range.  That is,
.sp;.cm R start
\indexentry{alpha|(}{1}
.br
\indexentry{alpha|)}{5}
.sp;.cm R end
will become
.sp;.cm R start
\item alpha, 1--5
.sp;.cm R end
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, respectively.
.il 3
This explicit page range formation can also include an extra command
to set the page range in a designated font.  Thus
.sp;.cm R start
\indexentry{alpha|(bold}{1}
.br
\indexentry{alpha|)}{5}
.sp;.cm R end
will become
.sp;.cm R start
\item alpha, \bold{1--5}
.sp;.cm R end
A couple of special cases are worth mentioning here.  First, entries like
.sp;.cm R start
\indexentry{alpha|(}{1}
.br
\indexentry{alpha|bold}{3}
.br
\indexentry{alpha|)}{5}
.sp;.cm R end
will be interpreted as
.sp;.cm R start
\item alpha, \bold{3}, 1--5
.sp;.cm R end
but with a warning message in the
transcript about the encounter of an inconsistent page encapsulator.
Secondly, an explicit range beginning in a Roman page number and ending
in Arabic is considered an error.  In a case like this the range is broken
into two subranges, if possible, one in Roman, the other in Arabic.
For instance,
.sp;.cm R start
\indexentry{alpha|(}{i}
.br
\indexentry{alpha}{iv}
.br
\indexentry{alpha}{3}
.br
\indexentry{alpha|)}{7}
.sp;.cm R end
will be turned into
.sp;.cm R start
\item alpha, 1--iv, 3--7
.sp;.cm R end
with a warning message in the transcript complaining about the illegal
range formation.
.il 3
Finally, every special symbol mentioned in this section may be
escaped by the›|quote›%operator (`"').  Thus
.sp;.cm R start
\indexentry{alpha"@beta}{1}
.sp;.cm R end
will actually become
.sp;.cm R start
\item alpha@beta,  1
.sp;.cm R end
as a result of executing›|makeindx.›% However, if›|quote›%is
preceded by›|escape›%(`\'), its following letter is not escaped.
That is,
.sp;.cm R start
\indexentry{f\"ur}{1}
.sp;.cm R end
means
.sp;.cm R start
\item f\"ur, 1
.sp;.cm R end
which represents umlaut accented `u' to the TeX family of processors.
.sp;
.la SEE ALSO
.la tex(l), latex(l), qsort(3)
.sp;
.la AUTHOR
Pehong Chen
.br
Computer Science Division
.br
University of California, Berkeley
.br
phc@berkeley.edu
.sp;
.la THANKS
Leslie Lamport contributed significantly to the design.
Michael Harrison provided valuable comments and suggestions.