Go to the first, previous, next, last section, table of contents.
@FWEB{} has several powerful indexing facilities:
- 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.
- 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 severalweb
files.
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.)
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.
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 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{}.
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.
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 \input
s `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
.
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.