1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> 4<title>Available Indexing Options</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="../configure.html" title="Step 2: Configure Boost.Build jamfile to use AutoIndex"> 9<link rel="prev" href="../configure.html" title="Step 2: Configure Boost.Build jamfile to use AutoIndex"> 10<link rel="next" href="optional.html" title="Making AutoIndex optional"> 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="../configure.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../configure.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="optional.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h4 class="title"> 27<a name="boost_autoindex.tut.configure.options"></a><a class="link" href="options.html" title="Available Indexing Options">Available Indexing 28 Options</a> 29</h4></div></div></div> 30<p> 31 The available options are: 32 </p> 33<div class="variablelist"> 34<p class="title"><b></b></p> 35<dl class="variablelist"> 36<dt><span class="term"><auto-index>off/on</span></dt> 37<dd><p> 38 Turns indexing of the document on, defaults to "off", so 39 be sure to set this if you want AutoIndex invoked! 40 </p></dd> 41<dt><span class="term"><auto-index-internal>off/on</span></dt> 42<dd><p> 43 Chooses whether AutoIndex creates the index itself (feature on), 44 or whether it simply inserts the necessary DocBook markup so that 45 the DocBook XSL stylesheets can create the index. Defaults to "off". 46 </p></dd> 47<dt><span class="term"><auto-index-script>filename</span></dt> 48<dd><p> 49 Specifies the name of the script to load. 50 </p></dd> 51<dt><span class="term"><auto-index-no-duplicates>off/on</span></dt> 52<dd><p> 53 When <span class="emphasis"><em>on</em></span> AutoIndex will only index a term once 54 in any given section, otherwise (the default) multiple index entries 55 per term may be created if the term occurs more than once in the 56 section. 57 </p></dd> 58<dt><span class="term"><auto-index-section-names>off/on</span></dt> 59<dd><p> 60 When <span class="emphasis"><em>on</em></span> AutoIndex will use create two index 61 entries for each term found - one uses the term itself as the primary 62 index key, the other uses the enclosing section name. When off the 63 index entry that uses the section title is not created. Defaults 64 to "on" 65 </p></dd> 66<dt><span class="term"><auto-index-verbose>off/on</span></dt> 67<dd><p> 68 Defaults to "off". When turned on AutoIndex prints progress 69 information - useful for debugging purposes during setup. 70 </p></dd> 71<dt><span class="term"><auto-index-prefix>filename</span></dt> 72<dd> 73<p> 74 Optionally specifies a directory to apply as a prefix to all relative 75 file paths in the script file. 76 </p> 77<p> 78 You may wish to do this to reduce typing of pathnames, and/or where 79 the paths can't be located relative to the script file location, 80 typically if the headers are in the Boost trunk, but the script file 81 is in Boost sandbox. 82 </p> 83<p> 84 For Boost standard library layout, <code class="literal"><auto-index-prefix>../../..</code> 85 will get you back up to the 'root' of the Boost tree, so <code class="literal">!scan-path 86 boost/mylibrary/</code> is where your headers will be, and <code class="literal">libs/mylibrary</code> 87 for other files. Without a prefix all relative paths are relative 88 to the location of the script file. 89 </p> 90</dd> 91<dt><span class="term"><auto-index-type>element-name</span></dt> 92<dd><p> 93 Specifies the name of the XML element in which to enclose an internally 94 generated indexes: defaults to <span class="emphasis"><em>section</em></span>, but 95 could equally be <span class="emphasis"><em>appendix</em></span> or <span class="emphasis"><em>chapter</em></span> 96 or some other block level element that has a formal title. The actual 97 list of available options depends upon the Quickbook document type, 98 the following table gives the available options, assuming that the 99 index is placed at the top level, and not in some sub-section or 100 other container: 101 </p></dd> 102</dl> 103</div> 104<div class="informaltable"><table class="table"> 105<colgroup> 106<col> 107<col> 108</colgroup> 109<thead><tr> 110<th> 111 <p> 112 Document Type 113 </p> 114 </th> 115<th> 116 <p> 117 Permitted Index Types 118 </p> 119 </th> 120</tr></thead> 121<tbody> 122<tr> 123<td> 124 <p> 125 book 126 </p> 127 </td> 128<td> 129 <p> 130 appendix index article chapter reference part 131 </p> 132 </td> 133</tr> 134<tr> 135<td> 136 <p> 137 article 138 </p> 139 </td> 140<td> 141 <p> 142 section appendix index sect1 143 </p> 144 </td> 145</tr> 146<tr> 147<td> 148 <p> 149 chapter 150 </p> 151 </td> 152<td> 153 <p> 154 section index sect1 155 </p> 156 </td> 157</tr> 158<tr> 159<td> 160 <p> 161 library 162 </p> 163 </td> 164<td> 165 <p> 166 The same as Chapter (section index sect1) 167 </p> 168 </td> 169</tr> 170<tr> 171<td> 172 <p> 173 part 174 </p> 175 </td> 176<td> 177 <p> 178 appendix index article chapter reference 179 </p> 180 </td> 181</tr> 182<tr> 183<td> 184 <p> 185 appendix 186 </p> 187 </td> 188<td> 189 <p> 190 section index sect1 191 </p> 192 </td> 193</tr> 194<tr> 195<td> 196 <p> 197 preface 198 </p> 199 </td> 200<td> 201 <p> 202 section index sect1 203 </p> 204 </td> 205</tr> 206<tr> 207<td> 208 <p> 209 qandadiv 210 </p> 211 </td> 212<td> 213 <p> 214 N/A: an index would have to be placed within a subsection of 215 the document. 216 </p> 217 </td> 218</tr> 219<tr> 220<td> 221 <p> 222 qandaset 223 </p> 224 </td> 225<td> 226 <p> 227 N/A: an index would have to be placed within a subsection of 228 the document. 229 </p> 230 </td> 231</tr> 232<tr> 233<td> 234 <p> 235 reference 236 </p> 237 </td> 238<td> 239 <p> 240 N/A: an index would have to be placed within a subsection of 241 the document. 242 </p> 243 </td> 244</tr> 245<tr> 246<td> 247 <p> 248 set 249 </p> 250 </td> 251<td> 252 <p> 253 N/A: an index would have to be placed within a subsection of 254 the document. 255 </p> 256 </td> 257</tr> 258</tbody> 259</table></div> 260<p> 261 In large part then the choice of <code class="computeroutput"><span class="special"><</span><span class="keyword">auto</span><span class="special">-</span><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> 262 depends on the formatting you want to be applied to the index: 263 </p> 264<div class="informaltable"><table class="table"> 265<colgroup> 266<col> 267<col> 268</colgroup> 269<thead><tr> 270<th> 271 <p> 272 XML Container Used for the Index 273 </p> 274 </th> 275<th> 276 <p> 277 Formatting Applied by the XSL Stylesheets 278 </p> 279 </th> 280</tr></thead> 281<tbody> 282<tr> 283<td> 284 <p> 285 appendix 286 </p> 287 </td> 288<td> 289 <p> 290 Starts a new page. 291 </p> 292 </td> 293</tr> 294<tr> 295<td> 296 <p> 297 article 298 </p> 299 </td> 300<td> 301 <p> 302 Starts a new page. 303 </p> 304 </td> 305</tr> 306<tr> 307<td> 308 <p> 309 chapter 310 </p> 311 </td> 312<td> 313 <p> 314 Starts a new page. 315 </p> 316 </td> 317</tr> 318<tr> 319<td> 320 <p> 321 index 322 </p> 323 </td> 324<td> 325 <p> 326 Starts a new page only if it's contained within an article or 327 book. 328 </p> 329 </td> 330</tr> 331<tr> 332<td> 333 <p> 334 part 335 </p> 336 </td> 337<td> 338 <p> 339 Starts a new page. 340 </p> 341 </td> 342</tr> 343<tr> 344<td> 345 <p> 346 reference 347 </p> 348 </td> 349<td> 350 <p> 351 Starts a new page. 352 </p> 353 </td> 354</tr> 355<tr> 356<td> 357 <p> 358 sect1 359 </p> 360 </td> 361<td> 362 <p> 363 Starts a new page as long as it's not the first section (but 364 is controlled by the XSL parameters chunk.section.depth and/or 365 chunk.first.sections). 366 </p> 367 </td> 368</tr> 369<tr> 370<td> 371 <p> 372 section 373 </p> 374 </td> 375<td> 376 <p> 377 Starts a new page as long as it's not the first section or nested 378 within another section (but is controlled by the XSL parameters 379 chunk.section.depth and/or chunk.first.sections). 380 </p> 381 </td> 382</tr> 383</tbody> 384</table></div> 385<p> 386 In almost all cases the default (section) is the correct choice - the exception 387 is when the index is to be placed directly inside a <span class="emphasis"><em>book</em></span> 388 or <span class="emphasis"><em>part</em></span>, in which case you should probably use the 389 same XML container for the index as you use for whatever subdivisions are 390 in the <span class="emphasis"><em>book</em></span> or <span class="emphasis"><em>part</em></span>. In any event 391 placing a <span class="emphasis"><em>section</em></span> within a <span class="emphasis"><em>book</em></span> 392 or <span class="emphasis"><em>part</em></span> will result in invalid XML. 393 </p> 394<p> 395 Finally, if you are using Quickbook to generate the documentation, then 396 you may wish to add: 397 </p> 398<pre class="programlisting"><include>$boost-root/tools/auto_index/include</pre> 399<p> 400 to your projects requirements (replacing $boost-root with the path to the 401 root of the Boost tree), so that the file auto_index_helpers.qbk can be 402 included in your quickbook source with simply a: 403 </p> 404<pre class="programlisting">[include auto_index_helpers.qbk]</pre> 405</div> 406<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 407<td align="left"></td> 408<td align="right"><div class="copyright-footer">Copyright © 2008, 2011 John Maddock<p> 409 Distributed under the Boost Software License, Version 1.0. (See accompanying 410 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>) 411 </p> 412</div></td> 413</tr></table> 414<hr> 415<div class="spirit-nav"> 416<a accesskey="p" href="../configure.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../configure.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="optional.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> 417</div> 418</body> 419</html> 420
