1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> 4<title>Overview</title> 5<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.77.1"> 7<link rel="home" href="../index.html" title="Boost.AutoIndex"> 8<link rel="up" href="../index.html" title="Boost.AutoIndex"> 9<link rel="prev" href="../index.html" title="Boost.AutoIndex"> 10<link rel="next" href="tut.html" title="Getting Started and Tutorial"> 11</head> 12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 13<table cellpadding="2" width="100%"><tr> 14<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td> 15<td align="center"><a href="../../../../../index.html">Home</a></td> 16<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td> 17<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 18<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 19<td align="center"><a href="../../../../../more/index.htm">More</a></td> 20</tr></table> 21<hr> 22<div class="spirit-nav"> 23<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> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 27<a name="boost_autoindex.overview"></a><a class="link" href="overview.html" title="Overview">Overview</a> 28</h2></div></div></div> 29<p> 30 AutoIndex is a tool for taking the grunt work out of indexing a Boostbook/Docbook 31 document (perhaps generated by your Quickbook file mylibrary.qbk, and perhaps 32 using also Doxygen autodoc) that describes C/C++ code. 33 </p> 34<p> 35 Traditionally, in order to index a Docbook document you would have to manually 36 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> 37 for each occurrence of each term to be indexed. 38 </p> 39<p> 40 Instead AutoIndex will automatically scan one or more C/C++ header files and 41 extract all the <span class="emphasis"><em>function</em></span>, <span class="emphasis"><em>class</em></span>, 42 <span class="emphasis"><em>macro</em></span> and <span class="emphasis"><em>typedef</em></span> names that are 43 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 44 into the Docbook XML document for you. 45 </p> 46<p> 47 AutoIndex can also scan using a list of index terms specified in a script file, 48 for example index.idx. These manually provided terms can optionally be regular 49 expressions, and may allow the user to find references to terms that may not 50 occur in the C++ header files. Of course providing a manual list of search 51 terms in to index is a tedious task (especially handling plurals and variants), 52 and requires enough knowledge of the library to guess what users may be seeking 53 to know, but at least the real 'grunt work' of finding the term and listing 54 the page number is automated. 55 </p> 56<p> 57 AutoIndex creates index entries as follows: 58 </p> 59<p> 60 for each occurrence of each search term, it creates two index entries: 61 </p> 62<div class="orderedlist"><ol class="orderedlist" type="1"> 63<li class="listitem"> 64 The search term as the <span class="emphasis"><em>primary index key</em></span> and the 65 <span class="emphasis"><em>title of the section it appears in</em></span> as a subterm. 66 </li> 67<li class="listitem"> 68 The section title as the main index entry and the search term as the subentry. 69 </li> 70</ol></div> 71<p> 72 Thus the user has two chances to find what they're looking for, based upon 73 either the section name or the <span class="emphasis"><em>function</em></span>, <span class="emphasis"><em>class</em></span>, 74 <span class="emphasis"><em>macro</em></span> or <span class="emphasis"><em>typedef</em></span> name. 75 </p> 76<div class="note"><table border="0" summary="Note"> 77<tr> 78<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td> 79<th align="left">Note</th> 80</tr> 81<tr><td align="left" valign="top"><p> 82 This behaviour can be changed so that only one index entry is created (using 83 the search term as the key and not using the section name except as a sub-entry 84 of the search term). 85 </p></td></tr> 86</table></div> 87<p> 88 So for example in Boost.Math the class name <code class="computeroutput"><span class="identifier">students_t_distribution</span></code> 89 has a primary entry that lists all sections the class name appears in: 90 </p> 91<p> 92 <span class="inlinemediaobject"><img src="../../students_t_eg_1.png" alt="students_t_eg_1"></span> 93 </p> 94<p> 95 Then those sections also have primary entries, which list all the search terms 96 those sections contain: 97 </p> 98<p> 99 <span class="inlinemediaobject"><img src="../../students_t_eg_2.png" alt="students_t_eg_2"></span> 100 </p> 101<p> 102 Of course these automated index entries may not be quite what you're looking 103 for: often you'll get a few spurious entries, a few missing entries, and a 104 few entries where the section name used as an index entry is less than ideal. 105 So AutoIndex provides some powerful regular expression based rules that allow 106 you to add, remove, constrain, or rewrite entries. Normally just a few lines 107 in AutoIndex's script file are enough to tailor the output to match the author's 108 expectations (and thus hopefully the index user's expectations too!). 109 </p> 110<p> 111 AutoIndex also supports multiple indexes (as does Docbook), and since it knows 112 which search terms are <span class="emphasis"><em>function</em></span>, <span class="emphasis"><em>class</em></span>, 113 <span class="emphasis"><em>macro</em></span> or <span class="emphasis"><em>typedef</em></span> names, it can add 114 the necessary attributes to the XML so that you can have separate indexes for 115 each of these different types. These specialised indexes only contain entries 116 for the <span class="emphasis"><em>function</em></span>, <span class="emphasis"><em>class</em></span>, <span class="emphasis"><em>macro</em></span> 117 or <span class="emphasis"><em>typedef</em></span> names, <span class="emphasis"><em>section names</em></span> are 118 never used as primary index terms here, unlike the main "include everything" 119 index. 120 </p> 121<p> 122 Finally, while the Docbook XSL stylesheets create nice indexes complete with 123 page numbers for PDF output, the HTML indexes look poorer by comparison, as 124 these use section titles in place of page numbers... but as AutoIndex uses 125 section titles as index entries this leads to a lot of repetition, so as an 126 alternative AutoIndex can be instructed to construct the index itself. This 127 is faster than using the XSL stylesheets, and now each index entry is a hyperlink 128 to the appropriate section: 129 </p> 130<p> 131 <span class="inlinemediaobject"><img src="../../students_t_eg_3.png" alt="students_t_eg_3"></span> 132 </p> 133<p> 134 With internal index generation there is also a helpful navigation bar at the 135 start of each Index: 136 </p> 137<p> 138 <span class="inlinemediaobject"><img src="../../students_t_eg_4.png" alt="students_t_eg_4"></span> 139 </p> 140<p> 141 Finally, you can choose what kind of XML container wraps an internally generated 142 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> 143 but you can use either command line options or Boost.Build Jamfile features, 144 to select an alternative wrapper - for example <span class="emphasis"><em>appendix</em></span> 145 or <span class="emphasis"><em>chapter</em></span> would be good choices, whatever fits best into 146 the flow of the document. You can even set the container wrapper to type <span class="emphasis"><em>index</em></span> 147 provided you turn off index generation by the XSL stylesheets, for example 148 by setting the following build requirements in the Jamfile: 149 </p> 150<pre class="programlisting"><format>html:<auto-index-internal>on # Use internally generated indexes. 151<auto-index-type>index # Use <index>...</index> as the XML wrapper. 152<format>html:<xsl:param>generate.index=0 # Don't let the XSL stylesheets generate indexes. 153</pre> 154</div> 155<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 156<td align="left"></td> 157<td align="right"><div class="copyright-footer">Copyright © 2008, 2011 John Maddock<p> 158 Distributed under the Boost Software License, Version 1.0. (See accompanying 159 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>) 160 </p> 161</div></td> 162</tr></table> 163<hr> 164<div class="spirit-nav"> 165<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> 166</div> 167</body> 168</html> 169
