11.2 Creating a stand-alone index with 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.

11.2.1 Creating a stand-alone index: Summary

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 \inputs 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.

11.2.2 Creating a stand-alone index: Details

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.