Node:Using makeindex, Next:Merging indexes, Previous:Internal index, Up:Index
makeindex
In addition to the internal index described in the previous section
(see Internal index), FWEAVE can write the index data to a file
formatted for later, stand-alone processing by the makeindex
utility. (Several such indexes can be merged together; see Merging indexes.) The procedure is simple, although the following discussion goes
into some rather arcane details.
As a quick reference for those who have already read the details in the
next subsection, the procedure to print a stand-alone index with
makeindex
is as follows. First, create, if necessary, a file
index.tex
that \input
s index.ind
. (A skeleton
is illustrated in the next subsection.) Then:
fweave -XI test.web % Creates test.idx and test.sty. makeindex -s test.sty -o index.ind test.idx % Creates index.ind. latex index
If you're not happy with the \pg
macro supplied in
fwebmac.sty
, define it yourself in index.tex
.
In this procedure, note the use of the -XI
option and the use of
a different root name (index
here) for the output file.
To create an index file in a form suitable for later stand-alone
processing by makeindex
, use the -XI
option to
FWEAVE. If the web
file is test.web
, the default
name of the makeindex
output file is test.idx
. (This name
can be overridden by the style-file parameter makeindex.out
.) Run
makeindex
on test.idx
to create the LaTeX file
index.ind
(see following discussion for details). A stand-alone
index can then be produced by saying latex index
, where a skeleton
version of index.tex
would be
% index.tex --- skeleton for printing a stand-alone index. \documentclass{article} \usepackage{fwebmac} \begin{document} \input{\jobname.ind} \end{document}
(In practice, a more involved procedure will probably be followed; see below.)
Usually makeindex
works in conjunction with a style file. [In
fact, the syntax of FWEB's style file (see Style) was motivated
by that of makeindex
.] When the -XI
option (see -X_) is used,
FWEAVE will create an appropriate style file for
makeindex
. (The default name of test.sty
can be overridden
by the style-file parameter makeindex.sty
.) To run
makeindex
on the index data for test.web
and create the
output file index.ind
, one would thus say
makeindex -s test.sty -o index.ind test[.idx]
It's important to use the -o
option with a name different than
the original file name, because it simplifies the construction of the
skeleton file index.tex
that prints the stand-alone index.
FWEAVE writes test.sty
because the contents of that file may
depend on parameter settings in FWEB's style file fweb.sty
.
FWEB's style vocabulary includes all parameters understood by
makeindex
. If a makeindex
parameter is called
param
, one references it in fweb.sty
by
makeindex.param
. Thus, to change the headings_flag
of
makeindex
, one would put into fweb.sty
a line like
makeindex.headings_flag = 1
. To see a list of all
makeindex
-related parameters, say fweave -Zmakeindex
(see -Z_). Remember, do all makeindex
customizations
in fweb.sty
; the actual style file test.sty
that will be
read by makeindex
is written automatically by FWEAVE.
The .idx
file will contain a list of entries that begin with
\indexentry
(more precisely, the value of the parameter
makeindex.keyword
). The general form is
\indexentry{sort key:identifier expression|macro}{page number}
Typical entries are
\indexentry{istream:"\>{istream}|pg{}{}}{1} \indexentry{main:"\>{main}|pg{}\underline}{1} \indexentry{pow:"\@{pow}|pg{}{}}{2} \indexentry{z:"\"|z|pg{}\underline}{2}
Here the colon is the value of makeindex.actual
; it separates the
sort key (before the colon) from the actual expression to be printed.
The macros such as \>
typeset the identifiers in the appropriate
way, depending on their use in the code. Note that the backslashes are
quoted with the value of makeindex.quote
, which is by default the
double quote.
Although one might guess that the typesetting macros such as \>
would be defined in fwebmac.sty
, that is not true. Rather, for
various technical reasons they
are equated to macros in fwebmac.sty
as one of the operations of
the \Wbegin
macro that is executed at the beginning of every
tex
file output by FWEAVE. For example, \Wbegin
does
the equivalent of \let\>\Wid
. Unfortunately, without further
action that equating would be forgotten by a LaTeX run made on the
output index.ind
of makeindex
. For that reason, FWEAVE
appends the appropriate \Wequate
macro to the end of
makeindex.preamble
. This is one specific instance that
necessitates that FWEAVE write the makeindex
style file.
Each of the \indexentry
s contains the encapsulation character
|
(the value of makeindex.encap
). By the conventions of
makeindex
, everything between the encapsulation character and the
closing right brace defines a macro expression that acts on the page
number. E.g., the general form above generates the command
\macro{page number}
. The specific macro construction
output by FWEAVE is
\pg{}{possible action macro}{page number}
Here the name pg
is the value of makeindex.page
. The
action macro is something like \underline
, which would be
used by FWEAVE to underline the page number to indicate where a
variable is defined. A default definition of \pg
is given is
fwebmac.sty
. It is a three-argument macro,
\def\pg#1#2#3{...}
, where the arguments are as follows:
#1 -- Integer file identification number #2 -- Action macro. #3 -- Page number.
The definition should contain the construction #2{#3}
--i.e.,
the page number must be the argument of the action macro. The first
argument is left empty in the .idx
file written by FWEAVE.
This can be filled in later by the utility idxmerge
(see Merging indexes) that merges the indices
from several web
files. For example, in a master index one might
ultimately print page numbers like II.5
, where II
refers to
a file such as test2.web
. To aid this merging process, the root
name of the web
file is written as a comment at the top of the
.idx
file output by FWEAVE.