/usr/share/doc/fweb/html-info/Using-makeindex.html is in fweb-doc 1.62-13.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 6.1, http://www.gnu.org/software/texinfo/ -->
<head>
<title>FWEB: Using makeindex</title>
<meta name="description" content="FWEB: Using makeindex">
<meta name="keywords" content="FWEB: Using makeindex">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Concept-index.html#Concept-index" rel="index" title="Concept index">
<link href="Parameter-index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Index.html#Index" rel="up" title="Index">
<link href="Merging-indexes.html#Merging-indexes" rel="next" title="Merging indexes">
<link href="Internal-index.html#Internal-index" rel="prev" title="Internal index">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>
</head>
<body lang="en">
<a name="Using-makeindex"></a>
<div class="header">
<p>
Next: <a href="Merging-indexes.html#Merging-indexes" accesskey="n" rel="next">Merging indexes</a>, Previous: <a href="Internal-index.html#Internal-index" accesskey="p" rel="prev">Internal index</a>, Up: <a href="Index.html#Index" accesskey="u" rel="up">Index</a> [<a href="Parameter-index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-index.html#Concept-index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Creating-a-stand_002dalone-index-with-makeindex"></a>
<h3 class="section">11.2 Creating a stand-alone index with <code>makeindex</code></h3>
<a name="index-Index_002c-stand_002dalone"></a>
<a name="index-Makeindex_002c-using"></a>
<p>In addition to the internal index described in the previous section
(see <a href="Internal-index.html#Internal-index">Internal index</a>), <small>FWEAVE</small> can write the index data to a file
formatted for later, stand-alone processing by the <code>makeindex</code>
utility. (Several such indexes can be merged together; see <a href="Merging-indexes.html#Merging-indexes">Merging indexes</a>.) The procedure is simple, although the following discussion goes
into some rather arcane details.
</p>
<a name="Creating-a-stand_002dalone-index_003a-Summary"></a>
<h4 class="subsection">11.2.1 Creating a stand-alone index: Summary</h4>
<p>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
<code>makeindex</code> is as follows. First, create, if necessary, a file
<samp>index.tex</samp> that <code>\input</code>s <samp>index.ind</samp>. (A skeleton
is illustrated in the next subsection.) Then:
</p>
<div class="example">
<pre class="example">fweave -XI test.web <span class="roman">% Creates test.idx and test.sty.</span>
makeindex -s test.sty -o index.ind test.idx <span class="roman">% Creates index.ind.</span>
latex index
</pre></div>
<p>If you’re not happy with the <code>\pg</code> macro supplied in
<samp>fwebmac.sty</samp>, define it yourself in <samp>index.tex</samp>.
</p>
<p>In this procedure, note the use of the ‘<samp>-XI</samp>’ option and the use of
a different root name (<samp>index</samp> here) for the output file.
</p>
<a name="Creating-a-stand_002dalone-index_003a-Details"></a>
<h4 class="subsection">11.2.2 Creating a stand-alone index: Details</h4>
<a name="index-_002dXI"></a>
<p>To create an index file in a form suitable for later stand-alone
processing by <code>makeindex</code>, use the ‘<samp>-XI</samp>’ option to
<small>FWEAVE</small>. If the <code>web</code> file is <samp>test.web</samp>, the default
name of the <code>makeindex</code> output file is <samp>test.idx</samp>. (This name
can be overridden by the style-file parameter <code>makeindex.out</code>.) Run
<code>makeindex</code> on <samp>test.idx</samp> to create the LaTeX file
<samp>index.ind</samp> (see following discussion for details). A stand-alone
index can then be produced by saying ‘<samp>latex index</samp>’, where a skeleton
version of <samp>index.tex</samp> would be
</p>
<div class="example">
<pre class="example">% index.tex --- skeleton for printing a stand-alone index.
\documentclass{article}
\usepackage{fwebmac}
\begin{document}
\input{\jobname.ind}
\end{document}
</pre></div>
<p>(In practice, a more involved procedure will probably be followed; see below.)
</p>
<a name="index-Style-file_002c-for-makeindex"></a>
<p>Usually <code>makeindex</code> works in conjunction with a style file. [In
fact, the syntax of <small>FWEB</small>’s style file (see <a href="Style.html#Style">Style</a>) was motivated
by that of <code>makeindex</code>.] When the ‘<samp>-XI</samp>’ option (see <a href="_002dX_005f.html#g_t_002dX_005f">-X_</a>) is used,
<small>FWEAVE</small> will <em>create</em> an appropriate style file for
<code>makeindex</code>. (The default name of <samp>test.sty</samp> can be overridden
by the style-file parameter <code>makeindex.sty</code>.) To run
<code>makeindex</code> on the index data for <samp>test.web</samp> and create the
output file <samp>index.ind</samp>, one would thus say
</p>
<div class="example">
<pre class="example">makeindex -s test.sty -o index.ind test[.idx]
</pre></div>
<p>It’s important to use the ‘<samp>-o</samp>’ option with a name different than
the original file name, because it simplifies the construction of the
skeleton file <samp>index.tex</samp> that prints the stand-alone index.
</p>
<p><small>FWEAVE</small> writes <samp>test.sty</samp> because the contents of that file may
depend on parameter settings in <small>FWEB</small>’s style file <samp>fweb.sty</samp>.
<small>FWEB</small>’s style vocabulary includes all parameters understood by
<code>makeindex</code>. If a <code>makeindex</code> parameter is called
‘<samp>param</samp>’, one references it in <samp>fweb.sty</samp> by
‘<samp>makeindex.param</samp>’. Thus, to change the ‘<samp>headings_flag</samp>’ of
<code>makeindex</code>, one would put into <samp>fweb.sty</samp> a line like
‘<samp>makeindex.headings_flag = 1</samp>’. To see a list of all
<code>makeindex</code>-related parameters, say ‘<samp>fweave -Zmakeindex</samp>’
(see <a href="_002dZ_005f.html#g_t_002dZ_005f">-Z_</a>). Remember, <em>do all <code>makeindex</code> customizations
in <samp>fweb.sty</samp>; the actual style file <samp>test.sty</samp> that will be
read by <code>makeindex</code> is written automatically by <small>FWEAVE</small>.</em>
</p>
<p>The <samp>.idx</samp> file will contain a list of entries that begin with
‘<samp>\indexentry</samp>’ (more precisely, the value of the parameter
‘<samp>makeindex.keyword</samp>’). The general form is
</p>
<div class="example">
<pre class="example">\indexentry{sort key:identifier expression|macro}{page number}
</pre></div>
<p>Typical entries are
</p>
<div class="example">
<pre class="example">\indexentry{istream:"\>{istream}|pg{}{}}{1}
\indexentry{main:"\>{main}|pg{}\underline}{1}
\indexentry{pow:"\@{pow}|pg{}{}}{2}
\indexentry{z:"\"|z|pg{}\underline}{2}
</pre></div>
<p>Here the colon is the value of ‘<samp>makeindex.actual</samp>’; it separates the
sort key (before the colon) from the actual expression to be printed.
The macros such as ‘<samp>\></samp>’ typeset the identifiers in the appropriate
way, depending on their use in the code. Note that the backslashes are
quoted with the value of ‘<samp>makeindex.quote</samp>’, which is by default the
double quote.
</p>
<p>Although one might guess that the typesetting macros such as ‘<samp>\></samp>’
would be defined in <samp>fwebmac.sty</samp>, that is not true. Rather, for
various technical reasons they
are equated to macros in <samp>fwebmac.sty</samp> as one of the operations of
the ‘<samp>\Wbegin</samp>’ macro that is executed at the beginning of every
<code>tex</code> file output by <small>FWEAVE</small>. For example, ‘<samp>\Wbegin</samp>’ does
the equivalent of ‘<samp>\let\>\Wid</samp>’. Unfortunately, without further
action that equating would be forgotten by a LaTeX run made on the
output <samp>index.ind</samp> of <code>makeindex</code>. For that reason, <small>FWEAVE</small>
appends the appropriate ‘<samp>\Wequate</samp>’ macro to the end of
‘<samp>makeindex.preamble</samp>’. This is one specific instance that
necessitates that <small>FWEAVE</small> write the <code>makeindex</code> style file.
</p>
<p>Each of the ‘<samp>\indexentry</samp>’s contains the encapsulation character
‘<samp>|</samp>’ (the value of ‘<samp>makeindex.encap</samp>’). By the conventions of
<code>makeindex</code>, 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
‘<samp>\macro{<i>page number</i>}</samp>’. The specific macro construction
output by <small>FWEAVE</small> is
</p>
<div class="example">
<pre class="example">\pg{}{<i>possible action macro</i>}{<i>page number</i>}
</pre></div>
<p>Here the name ‘<samp>pg</samp>’ is the value of ‘<samp>makeindex.page</samp>’. The
<em>action macro</em> is something like ‘<samp>\underline</samp>’, which would be
used by <small>FWEAVE</small> to underline the page number to indicate where a
variable is defined. A default definition of ‘<samp>\pg</samp>’ is given is
<samp>fwebmac.sty</samp>. It is a three-argument macro,
‘<samp>\def\pg#1#2#3{...}</samp>’, where the arguments are as follows:
<a name="index-_005cpg"></a>
</p>
<div class="example">
<pre class="example">#1 <span class="roman">— Integer file identification number</span>
#2 <span class="roman">— Action macro.</span>
#3 <span class="roman">— Page number.</span>
</pre></div>
<p>The definition should contain the construction ‘<samp>#2{#3}</samp>’—i.e.,
the page number must be the argument of the action macro. The first
argument is left empty in the <samp>.idx</samp> file written by <small>FWEAVE</small>.
This can be filled in later by the utility <code>idxmerge</code>
(see <a href="Merging-indexes.html#Merging-indexes">Merging indexes</a>) that merges the indices
from several <code>web</code> files. For example, in a master index one might
ultimately print page numbers like ‘<samp>II.5</samp>’, where ‘<samp>II</samp>’ refers to
a file such as <samp>test2.web</samp>. To aid this merging process, the root
name of the <code>web</code> file is written as a comment at the top of the
<samp>.idx</samp> file output by <small>FWEAVE</small>.
</p>
<hr>
<div class="header">
<p>
Next: <a href="Merging-indexes.html#Merging-indexes" accesskey="n" rel="next">Merging indexes</a>, Previous: <a href="Internal-index.html#Internal-index" accesskey="p" rel="prev">Internal index</a>, Up: <a href="Index.html#Index" accesskey="u" rel="up">Index</a> [<a href="Parameter-index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-index.html#Concept-index" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
|