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.
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.)
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.
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, 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.
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.
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 an index with makeindex
.
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.