Go to the first, previous, next, last section, table of contents.


FWEB's INDEX.

FWEB has several powerful indexing facilities:

  1. It sorts and writes its own self-contained (internal) index, including cross-references to all the variables as well as items inserted by the user.
  2. It can write its cross-reference information to a file formatted for use by the makeindex utility. This feature facilitates creation of a master index that contains information about several web files.

FWEB's index

This is generated automatically. One can also insert one's own index entries by using the commands `@^' (entry in Roman type; see section `@^': Make index entry (Roman type)), `@.' (entry in typewriter type; see section `@.': Make index entry (typewriter type)), and `@9' (user-defined format; see section `@9': Make index entry (\9 format)).

(More discussion to be completed.)

Creating an index with makeindex

In addition to the internal index described in the previous section (see section FWEB's 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 section Using the `idxmerge' utility to merge indexes.) The procedure is simple, although the following discussion goes into some rather arcane details.

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.

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 section The Style file) was motivated by that of makeindex.] When the `-XI' option (see section `-X': Print selected cross-reference information (FWEAVE)) 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 section `-Z': Display default style-file parameters). 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, 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 section Using the `idxmerge' utility to merge 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.

Using the `idxmerge' utility to merge indexes

In a large project, one may maintain and work with several FWEB files. It may be useful to produce a global index that spans all of those files. To this end, the utility `idxmerge' and associated LaTeX package idxmerge are supplied with the FWEB distribution.

Using `idxmerge': Summary

As quick reference for those who have already plowed through the following details, here is a summary of the procedure. To print a stand-alone index by merging the indexes from several web sources, do the following. First, create, if necessary, a file `index.tex' that \inputs `index.ind'. Then:

fweave -XI test1.web
fweave -XI test2.web
fweave -XI test3.web

idxmerge -oindex test1.idx test2.idx test3.idx 
        % Creates index.ind and index-names.tex.
makeindex -s test1.sty index
latex index

Note the use of the `-XI' option. For further background, see the previous section, section Creating an index with makeindex.

Using `idxmerge': Details

Suppose one has three files, `test1.web', `test2.web', and `test3.web'. To use `idxmerge', weave each of the files separately, using the `-XI' option to create `test*.idx' and `test*.sty'. Then say

idxmerge -oindex test1.idx test2.idx test3.idx

This creates two output files: `index.idx', and `index-names.tex'. `idxmerge' first sorts the list of file names. It then writes one entry into `index-names.tex' for each file, of the form

\idxname{n}{file_namen}

This file can be \input by the \topofindex command (for an example, see the LaTeX2e package `idxmerge') (supplied with the FWEB distribution) and used to create a list of the merged files.

Then it merges the \indexentry commands from each of the input files into `index.idx', filling in the integer file identifier n (the position of the file in the sorted list) into the first argument of the \pg macro. One can now say

makeindex -s test1.sty index

This creates `index.ind', which can be processed by, for example, a simple modification of the simple LaTeX template given above in section Creating an index with makeindex. The only difference is that the package `idxmerge' was used; in that file, the macros \topofindex and \idxname are appropriately defined to print out a numbered list of the merged files to cross-reference into the numerical file- and page-number entries in the body of the index. Here is an example (provided in the FWEB distribution):

% index.tex -- skeleton for printing a stand-alone index.
\documentclass{article}
\usepackage{fwebmac,idxmerge}

\begin{document}

\input{\jobname.ind}

\end{document}


Go to the first, previous, next, last section, table of contents.