View Source: makeindex(1) - Waikato Linux Users Group

Edit PageHistory Diff Info LikePages
MAKEINDEX
!!!MAKEINDEX
NAME
SYNOPSIS
DESCRIPTION
OPTIONS
STYLE FILE
EXAMPLES
ORDERING
SPECIAL EFFECTS
FILES
SEE ALSO
AUTHOR
ACKNOWLEDGMENTS
----
!!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'']
__[[__''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)) or troff(1), 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 indexing
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 complimentary to the
awk(1)-based ''make.index''(1L) system of Bentley
and Kernighan, which is specific to troff(1),
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 L A TEX.


Unless specified explicitly, the base name of the first
input file (''idx0'') is used to determine 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__ Compress intermediate blanks (ignoring leading and
trailing blanks and tabs). By default, blanks in the index
key are retained.


__-g__ Employ German word ordering in the index, in
accord with rules set forth in DIN 5007. By default,
''makeindex'' employs a word ordering in which precedence
is: symbols, 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 {
''makeindex'' will produce an error message
and abort.


__-i__ Take input from ''stdin''. When this option is
specified and __-o__ is not, output is written to
''stdout''.


__-l__ Letter ordering; by default, word ordering is used
(see the ORDERING section).


__-o__ ''ind''


Employ ''ind'' as the output index file. By default, the
file name is created by appending the extension ''.ind''
to the base name of the first input file
(''idx0'').


__-p__ ''num''


Set the starting page number of the output index file to be
''num'' (useful when the 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__ Quiet mode; send no messages to ''stderr''. By
default, progress and error messages are sent to
''stderr'' as well as to the transcript
file.


__-r__ Disable implicit page range formation; page ranges
must be created by using explicit range operators; see
SPECIAL EFFECTS below. By default, three or
more successive pages are automatically abbreviated as a
range (e.g. 1--5).


__-s__ sty


Employ ''sty'' as the style file (no default). The
environment variable INDEXSTYLE defines the
path where the style file should be found.


__-t__ log


Employ ''log'' as the transcript file. By default, the
file name is created by appending the extension ''.ilg''
to the base name of the first input file
(''idx0'').
!!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''
''


__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 letter is __escape__. 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.


__keyword__
__


Command which tells ''makeindex'' that its argument is an
index entry.


__level__ __


Delimiter denoting a new level of subitem.


__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__
__


Preamble of output file.


__postamble__ __


Postamble of output file.


__setpage_prefix__ __


Prefix of command which sets the starting page
number.


__setpage_suffix__ __


Suffix of command which sets the starting page
number.


__group_skip__ __


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): positive values cause an uppercase letter to be
inserted between prefix and suffix, and negative values
cause a lowercase letter to be inserted (default is 0, which
produces no header).


__heading_prefix__ __


Header prefix to be inserted before a new letter
begins.


__symhead_positive__ __


Heading for symbols to be inserted if __headings_flag__
is positive.


__symhead_negative__ __


Heading for symbols to be inserted if __headings_flag__
is negative.


__numhead_positive__ __


Heading for numbers to be inserted if __headings_flag__
is positive.


__numhead_negative__ __


Heading for numbers to be inserted if __headings_flag__
is negative.


__item_0__
__


Command to be inserted between two primary (level 0)
items.


__item_1__
__


Command to be inserted between two secondary (level 1)
items.


__item_2__
__


Command to be inserted between two level 2
items.


__item_01 __
__


Command to be inserted between a level 0 item and a level 1
item.


__item_x1__
__


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__
__


Command to be inserted between a level 1 item and a level 2
item.


__item_x2__
__


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 numbers 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.


__line_max__ __


Maximum length of a line in the output, beyond which a line
wraps.


__indent_space__ __


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: __


__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 __suffix_mp__. Example:
__


__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:
__
!!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


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 itself (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 ''sample.ist'':


keyword


The local macro package may require modification, as in this
example of an extension to the __-ms__ macros (note that
at some sites, this macro should ''replace'' a
pre-existing macro of the 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 local macro package does
not contain this extension, just include those lines at the
beginning of your file. Here is a simple troff(1)
input file, which we will assume is named
''sample.txt'':


This is a sample file to test the fImakeindexfP(1L)
program, and see
.IX {indexing!programs!C language}
.IX {makeindex@fImakeindexfP(1L)}
.bp
.rs
.IX {Knuth}
.IX {typesetting!computer-aided}
how well it functions in the fItrofffP(1) 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
Some sites will require ''ditroff'' instead of ''psroff''. To filter out any genuine error messages, invoke grep(1):


grep '^IX: ' sample.tmp


__CREATING THE INDEX FILE USING__ ''UCSF'' __ENHANCED
TROFF/T RAN S
CRIPT__


With ''UCSF'' Enhanced troff/T RAN S
CRIPT , the __-I__ option of
''psroff''(1L) 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


__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)-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 version 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 character.
!!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 hierarchical
levels.


It is possible to make an item appear in a designated form
by using the __actual__ (`@') operator. 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 mechanism allows page
numbers to be set in different fonts. For example, the page
where the definition 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 explicit
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 encapsulator. An explicit
range beginning in a Roman page number and ending in Arabic
is also considered 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.


Finally, every special symbol mentioned in this section may
be escaped by the __quote__ operator (`
__


indexentry{alpha


will actually become


item alpha@beta, 1


as a result of executing ''makeindex''. The quoting power
of __quote__ is eliminated if it is immediately preceded
by __escape__ (`'). For example,


indexentry{f


becomes


item f


which represents an umlaut-accented `u' to the TEX family of
processors.


From 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
characters 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{


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
particularly 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
!!FILES


''makeindex'' executable file


''$TEXMFMAIN/tex/plain/misc/idxmac.tex''


TEX macro file used by ''makeindex''


''$TEXMFMAIN/tex/latex/base/makeidx.sty''


TEX macro file used by ''makeindex''
!!SEE ALSO


ditroff(1L), latex(1L), make.index (1L), qsort(3), tex(1L),
troff(1L)


''UCSF Enhanced troff/T RAN S
CRIPT -- An Overview'', R. P. C. Rodgers
and Conrad Huang, LSMB Technical 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), 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 L
A TEX document supplied with
''makeindex'').


''!MakeIndex: An Index Processor for L A
TEX'', Leslie Lamport, February 1987 (a L A
TEX document supplied with ''makeindex'').


''Tools for Printing Indices'', Jon L. Bentley and Brian
W. Kernighan, ''Electronic Publishing -- Origination,
Dissemination, and Design'', !1(1), 3-18, June 1988 (also
available as: Computing Science Technical Report No. 128,
AT
''
!!AUTHOR


Pehong Chen, Chen
Manual page extensively revised and corrected, and
troff(1) examples created by Rick P. C. Rodgers, UCSF
School of Pharmacy
''
!!ACKNOWLEDGMENTS


Leslie Lamport contributed significantly to the design.
Michael Harrison provided valuable comments and suggestions.
Nelson Beebe improved on the portable version, and maintains
the source distribution for the TEX Users Group. 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
__LOG'' and ''CONTRIB'' files in the
''makeindex'' source distribution record other
contributions.
----
4 pages link to makeindex(1):
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.
Last edited on Sunday, August 17, 2003 8:07:16 am by AristotlePagaltzis
Edit PageHistory Diff Info LikePages