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
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Step 3: Add indexes to your documentation</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
<link rel="home" href="../../index.html" title="Boost.AutoIndex">
<link rel="up" href="../tut.html" title="Getting Started and Tutorial">
<link rel="prev" href="configure/optional.html" title="Making AutoIndex optional">
<link rel="next" href="script.html" title="Step 4: Create the .idx script file - to control what to terms to index">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="configure/optional.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tut.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="script.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boost_autoindex.tut.add_indexes"></a><a class="link" href="add_indexes.html" title="Step 3: Add indexes to your documentation">Step 3: Add indexes
to your documentation</a>
</h3></div></div></div>
<p>
To add a single "include everything" index to a BoostBook/Docbook
document, (perhaps generated using Quickbook, and perhaps also using Doxygen
reference section), add <code class="computeroutput"><span class="special"><</span><span class="identifier">index</span><span class="special">/></span></code>
at the location where you want the index to appear. The index will be rendered
as a separate section called "Index" when the documentation is
built.
</p>
<p>
To add multiple indexes, then give each one a title and set its <code class="computeroutput"><span class="identifier">type</span></code> attribute to specify which terms will
be included, for example to place the <span class="emphasis"><em>function</em></span>, <span class="emphasis"><em>class</em></span>,
<span class="emphasis"><em>macro</em></span> or <span class="emphasis"><em>typedef</em></span> names indexed
by <span class="emphasis"><em>AutoIndex</em></span> in separate indexes along with a main "include
everything" index as well, one could add:
</p>
<pre class="programlisting"><index type="class_name">
<title>Class Index</title>
</index>
<index type="typedef_name">
<title>Typedef Index</title>
</index>
<index type="function_name">
<title>Function Index</title>
</index>
<index type="macro_name">
<title>Macro Index</title>
</index>
<index/>
</pre>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
Multiple indexes like this only work correctly if you tell the XSL stylesheets
to honor the "type" attribute on each index as by default . You
can turn the feature on by adding <code class="computeroutput"><span class="special"><</span><span class="identifier">xsl</span><span class="special">:</span><span class="identifier">param</span><span class="special">></span><span class="identifier">index</span><span class="special">.</span><span class="identifier">on</span><span class="special">.</span><span class="identifier">type</span><span class="special">=</span><span class="number">1</span></code> to your
projects requirements in the Jamfile.
</p></td></tr>
</table></div>
<p>
In Quickbook, you add the same markup but enclose it between two triple-tick
''' escapes, thus
</p>
<pre class="programlisting">'''<index/>''' </pre>
<p>
Or more easily via the helper file auto_index_helpers.qbk, so that given:
</p>
<pre class="programlisting">[include auto_index_helpers.qbk]</pre>
<p>
one can simply write:
</p>
<pre class="programlisting">[named_index class_name Class Index]
[named_index function_name Function Index]
[named_index typedef_name Typedef Index]
[named_index macro_name Macro Index]
[index]
</pre>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
AutoIndex knows nothing of the XML <code class="computeroutput"><span class="identifier">xinclude</span></code>
element, so if you're writing raw Docbook XML then you may want to run
this through an XSL processor to flatten everything to one XML file before
passing to AutoIndex. If you're using Boostbook or quickbook though, this
all happens for you anyway, and AutoIndex will index the whole document
including any sections included with <code class="computeroutput"><span class="identifier">xinclude</span></code>.
</p></td></tr>
</table></div>
<p>
If you are using AutoIndex's internal index generation on
</p>
<pre class="programlisting"><auto-index-internal>on
</pre>
<p>
(usually recommended for HTML output, but <span class="emphasis"><em>not</em></span> the default)
then you can also decide what kind of XML wrapper the generated index is
placed in. By default this is a <code class="computeroutput"><span class="special"><</span><span class="identifier">section</span><span class="special">>...</</span><span class="identifier">section</span><span class="special">></span></code>
XML block (this replaces the original <code class="computeroutput"><span class="special"><</span><span class="identifier">index</span><span class="special">>...</</span><span class="identifier">index</span><span class="special">></span></code>
block). However, depending upon the structure of the document and whether
or not you want the index on a separate page - or else on the front page
after the TOC - you may want to place the index inside a different type of
XML block. For example if your document uses <code class="computeroutput"><span class="special"><</span><span class="identifier">chapter</span><span class="special">></span></code>
top level content rather than <code class="computeroutput"><span class="special"><</span><span class="identifier">section</span><span class="special">></span></code>s
then it may be preferable to place the index in a <code class="computeroutput"><span class="special"><</span><span class="identifier">chapter</span><span class="special">></span></code>
or <code class="computeroutput"><span class="special"><</span><span class="identifier">appendix</span><span class="special">></span></code> block. You can also place the index inside
an <code class="computeroutput"><span class="special"><</span><span class="identifier">index</span><span class="special">></span></code> block if you prefer, in which case the
index does not appear in on a page of its own, but after the TOC in the HTML
output.
</p>
<p>
You control the type of XML block used by setting the <code class="literal"><auto-index-type>element-name</code>
attribute in the Jamfile, or via the <code class="computeroutput"><span class="identifier">index</span><span class="special">-</span><span class="identifier">type</span><span class="special">=</span><span class="identifier">element</span><span class="special">-</span><span class="identifier">name</span></code> command line option to AutoIndex itself.
For example, to place the index in an appendix, your Jamfile might look like:
</p>
<pre class="programlisting">using quickbook ;
using auto-index ;
xml mylibrary : mylibary.qbk ;
boostbook standalone
:
mylibrary
:
# auto-indexing is on:
<auto-index>on
# PDFs rely on the XSL stylesheets to generate the index:
<format>pdf:<auto-index-internal>off
# HTML output uses auto-index to generate the index:
<format>html:<auto-index-internal>on
# Name of script file to use:
<auto-index-script>index.idx
# Set the XML wrapper for HML Indexes to "appendix":
<format>html:<auto-index-type>appendix
# Turn on multiple index support:
<xsl:param>index.on.type=1
</pre>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2008, 2011 John Maddock<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="configure/optional.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tut.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="script.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
|
