ceph/src/boost/tools/auto_index/doc/html/boost_autoindex/tut/add_indexes.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Step 3: Add indexes to your documentation</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="../tut.html" title="Getting Started and Tutorial">
   9 <link rel="prev" href="configure/optional.html" title="Making AutoIndex optional">
  10 <link rel="next" href="script.html" title="Step 4: Create the .idx script file - to control what to terms to index">
  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/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>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h3 class="title">
  27 <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
  28       to your documentation</a>
  29 </h3></div></div></div>
  30 <p>
  31         To add a single "include everything" index to a BoostBook/Docbook
  32         document, (perhaps generated using Quickbook, and perhaps also using Doxygen
  33         reference section), add <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">index</span><span class="special">/&gt;</span></code>
  34         at the location where you want the index to appear. The index will be rendered
  35         as a separate section called "Index" when the documentation is
  36         built.
  37       </p>
  38 <p>
  39         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
  40         be included, for example to place the <span class="emphasis"><em>function</em></span>, <span class="emphasis"><em>class</em></span>,
  41         <span class="emphasis"><em>macro</em></span> or <span class="emphasis"><em>typedef</em></span> names indexed
  42         by <span class="emphasis"><em>AutoIndex</em></span> in separate indexes along with a main "include
  43         everything" index as well, one could add:
  44       </p>
  45 <pre class="programlisting">&lt;index type="class_name"&gt;
  46 &lt;title&gt;Class Index&lt;/title&gt;
  47 &lt;/index&gt;
  48
  49 &lt;index type="typedef_name"&gt;
  50 &lt;title&gt;Typedef Index&lt;/title&gt;
  51 &lt;/index&gt;
  52
  53 &lt;index type="function_name"&gt;
  54 &lt;title&gt;Function Index&lt;/title&gt;
  55 &lt;/index&gt;
  56
  57 &lt;index type="macro_name"&gt;
  58 &lt;title&gt;Macro Index&lt;/title&gt;
  59 &lt;/index&gt;
  60
  61 &lt;index/&gt;
  62 </pre>
  63 <div class="note"><table border="0" summary="Note">
  64 <tr>
  65 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td>
  66 <th align="left">Note</th>
  67 </tr>
  68 <tr><td align="left" valign="top"><p>
  69           Multiple indexes like this only work correctly if you tell the XSL stylesheets
  70           to honor the "type" attribute on each index as by default . You
  71           can turn the feature on by adding <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">xsl</span><span class="special">:</span><span class="identifier">param</span><span class="special">&gt;</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
  72           projects requirements in the Jamfile.
  73         </p></td></tr>
  74 </table></div>
  75 <p>
  76         In Quickbook, you add the same markup but enclose it between two triple-tick
  77         ''' escapes, thus
  78       </p>
  79 <pre class="programlisting">'''&lt;index/&gt;''' </pre>
  80 <p>
  81         Or more easily via the helper file auto_index_helpers.qbk, so that given:
  82       </p>
  83 <pre class="programlisting">[include auto_index_helpers.qbk]</pre>
  84 <p>
  85         one can simply write:
  86       </p>
  87 <pre class="programlisting">[named_index class_name Class Index]
  88 [named_index function_name Function Index]
  89 [named_index typedef_name Typedef Index]
  90 [named_index macro_name Macro Index]
  91 [index]
  92 </pre>
  93 <div class="note"><table border="0" summary="Note">
  94 <tr>
  95 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td>
  96 <th align="left">Note</th>
  97 </tr>
  98 <tr><td align="left" valign="top"><p>
  99           AutoIndex knows nothing of the XML <code class="computeroutput"><span class="identifier">xinclude</span></code>
 100           element, so if you're writing raw Docbook XML then you may want to run
 101           this through an XSL processor to flatten everything to one XML file before
 102           passing to AutoIndex. If you're using Boostbook or quickbook though, this
 103           all happens for you anyway, and AutoIndex will index the whole document
 104           including any sections included with <code class="computeroutput"><span class="identifier">xinclude</span></code>.
 105         </p></td></tr>
 106 </table></div>
 107 <p>
 108         If you are using AutoIndex's internal index generation on
 109       </p>
 110 <pre class="programlisting">&lt;auto-index-internal&gt;on
 111 </pre>
 112 <p>
 113         (usually recommended for HTML output, but <span class="emphasis"><em>not</em></span> the default)
 114         then you can also decide what kind of XML wrapper the generated index is
 115         placed in. By default this is a <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">section</span><span class="special">&gt;...&lt;/</span><span class="identifier">section</span><span class="special">&gt;</span></code>
 116         XML block (this replaces the original <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">index</span><span class="special">&gt;...&lt;/</span><span class="identifier">index</span><span class="special">&gt;</span></code>
 117         block). However, depending upon the structure of the document and whether
 118         or not you want the index on a separate page - or else on the front page
 119         after the TOC - you may want to place the index inside a different type of
 120         XML block. For example if your document uses <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">chapter</span><span class="special">&gt;</span></code>
 121         top level content rather than <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">section</span><span class="special">&gt;</span></code>s
 122         then it may be preferable to place the index in a <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">chapter</span><span class="special">&gt;</span></code>
 123         or <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">appendix</span><span class="special">&gt;</span></code> block. You can also place the index inside
 124         an <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">index</span><span class="special">&gt;</span></code> block if you prefer, in which case the
 125         index does not appear in on a page of its own, but after the TOC in the HTML
 126         output.
 127       </p>
 128 <p>
 129         You control the type of XML block used by setting the <code class="literal">&lt;auto-index-type&gt;element-name</code>
 130         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.
 131         For example, to place the index in an appendix, your Jamfile might look like:
 132       </p>
 133 <pre class="programlisting">using quickbook ;
 134 using auto-index ;
 135
 136 xml mylibrary : mylibary.qbk ;
 137 boostbook standalone
 138     :
 139         mylibrary
 140     :
 141         # auto-indexing is on:
 142         &lt;auto-index&gt;on
 143
 144         # PDFs rely on the XSL stylesheets to generate the index:
 145         &lt;format&gt;pdf:&lt;auto-index-internal&gt;off
 146
 147         # HTML output uses auto-index to generate the index:
 148         &lt;format&gt;html:&lt;auto-index-internal&gt;on
 149
 150         # Name of script file to use:
 151         &lt;auto-index-script&gt;index.idx
 152
 153         # Set the XML wrapper for HML Indexes to "appendix":
 154         &lt;format&gt;html:&lt;auto-index-type&gt;appendix
 155
 156         # Turn on multiple index support:
 157         &lt;xsl:param&gt;index.on.type=1
 158 </pre>
 159 </div>
 160 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 161 <td align="left"></td>
 162 <td align="right"><div class="copyright-footer">Copyright &#169; 2008, 2011 John Maddock<p>
 163         Distributed under the Boost Software License, Version 1.0. (See accompanying
 164         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>)
 165       </p>
 166 </div></td>
 167 </tr></table>
 168 <hr>
 169 <div class="spirit-nav">
 170 <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>
 171 </div>
 172 </body>
 173 </html>