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
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Overview</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="../index.html" title="Boost.AutoIndex">
<link rel="prev" href="../index.html" title="Boost.AutoIndex">
<link rel="next" href="tut.html" title="Getting Started and Tutorial">
</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="../index.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="tut.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="boost_autoindex.overview"></a><a class="link" href="overview.html" title="Overview">Overview</a>
</h2></div></div></div>
<p>
AutoIndex is a tool for taking the grunt work out of indexing a Boostbook/Docbook
document (perhaps generated by your Quickbook file mylibrary.qbk, and perhaps
using also Doxygen autodoc) that describes C/C++ code.
</p>
<p>
Traditionally, in order to index a Docbook document you would have to manually
add a large amount of <code class="computeroutput"><span class="special"><</span><span class="identifier">indexterm</span><span class="special">></span></code> markup: in fact one <code class="computeroutput"><span class="special"><</span><span class="identifier">indexterm</span><span class="special">></span></code>
for each occurrence of each term to be indexed.
</p>
<p>
Instead AutoIndex will automatically scan one or more C/C++ header files and
extract all the <span class="emphasis"><em>function</em></span>, <span class="emphasis"><em>class</em></span>,
<span class="emphasis"><em>macro</em></span> and <span class="emphasis"><em>typedef</em></span> names that are
defined by those headers, and then insert the <code class="computeroutput"><span class="special"><</span><span class="identifier">indexterm</span><span class="special">></span></code>s
into the Docbook XML document for you.
</p>
<p>
AutoIndex can also scan using a list of index terms specified in a script file,
for example index.idx. These manually provided terms can optionally be regular
expressions, and may allow the user to find references to terms that may not
occur in the C++ header files. Of course providing a manual list of search
terms in to index is a tedious task (especially handling plurals and variants),
and requires enough knowledge of the library to guess what users may be seeking
to know, but at least the real 'grunt work' of finding the term and listing
the page number is automated.
</p>
<p>
AutoIndex creates index entries as follows:
</p>
<p>
for each occurrence of each search term, it creates two index entries:
</p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">
The search term as the <span class="emphasis"><em>primary index key</em></span> and the
<span class="emphasis"><em>title of the section it appears in</em></span> as a subterm.
</li>
<li class="listitem">
The section title as the main index entry and the search term as the subentry.
</li>
</ol></div>
<p>
Thus the user has two chances to find what they're looking for, based upon
either the section name or 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> name.
</p>
<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>
This behaviour can be changed so that only one index entry is created (using
the search term as the key and not using the section name except as a sub-entry
of the search term).
</p></td></tr>
</table></div>
<p>
So for example in Boost.Math the class name <code class="computeroutput"><span class="identifier">students_t_distribution</span></code>
has a primary entry that lists all sections the class name appears in:
</p>
<p>
<span class="inlinemediaobject"><img src="../../students_t_eg_1.png" alt="students_t_eg_1"></span>
</p>
<p>
Then those sections also have primary entries, which list all the search terms
those sections contain:
</p>
<p>
<span class="inlinemediaobject"><img src="../../students_t_eg_2.png" alt="students_t_eg_2"></span>
</p>
<p>
Of course these automated index entries may not be quite what you're looking
for: often you'll get a few spurious entries, a few missing entries, and a
few entries where the section name used as an index entry is less than ideal.
So AutoIndex provides some powerful regular expression based rules that allow
you to add, remove, constrain, or rewrite entries. Normally just a few lines
in AutoIndex's script file are enough to tailor the output to match the author's
expectations (and thus hopefully the index user's expectations too!).
</p>
<p>
AutoIndex also supports multiple indexes (as does Docbook), and since it knows
which search terms are <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, it can add
the necessary attributes to the XML so that you can have separate indexes for
each of these different types. These specialised indexes only contain entries
for 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, <span class="emphasis"><em>section names</em></span> are
never used as primary index terms here, unlike the main "include everything"
index.
</p>
<p>
Finally, while the Docbook XSL stylesheets create nice indexes complete with
page numbers for PDF output, the HTML indexes look poorer by comparison, as
these use section titles in place of page numbers... but as AutoIndex uses
section titles as index entries this leads to a lot of repetition, so as an
alternative AutoIndex can be instructed to construct the index itself. This
is faster than using the XSL stylesheets, and now each index entry is a hyperlink
to the appropriate section:
</p>
<p>
<span class="inlinemediaobject"><img src="../../students_t_eg_3.png" alt="students_t_eg_3"></span>
</p>
<p>
With internal index generation there is also a helpful navigation bar at the
start of each Index:
</p>
<p>
<span class="inlinemediaobject"><img src="../../students_t_eg_4.png" alt="students_t_eg_4"></span>
</p>
<p>
Finally, you can choose what kind of XML container wraps an internally generated
index - this defaults to <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>
but you can use either command line options or Boost.Build Jamfile features,
to select an alternative wrapper - for example <span class="emphasis"><em>appendix</em></span>
or <span class="emphasis"><em>chapter</em></span> would be good choices, whatever fits best into
the flow of the document. You can even set the container wrapper to type <span class="emphasis"><em>index</em></span>
provided you turn off index generation by the XSL stylesheets, for example
by setting the following build requirements in the Jamfile:
</p>
<pre class="programlisting"><format>html:<auto-index-internal>on # Use internally generated indexes.
<auto-index-type>index # Use <index>...</index> as the XML wrapper.
<format>html:<xsl:param>generate.index=0 # Don't let the XSL stylesheets generate indexes.
</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="../index.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="tut.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
|
