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 self-generated index

One of the most useful features of @FWEB{} is that it automatically generates an Index of all variable usage. One can also insert one's own index entries by using the commands

(More discussion to be completed.)

Creating a stand-alone index with makeindex

In addition to the internal index described in the previous section (see section @FWEB{}'s self-generated 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, 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 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 a stand-alone 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 a stand-alone 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.