174 lines
10 KiB
HTML
174 lines
10 KiB
HTML
<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.77.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>
|