]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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"><</span><span class="identifier">index</span><span class="special">/></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"><index type="class_name"> | |
46 | <title>Class Index</title> | |
47 | </index> | |
48 | ||
49 | <index type="typedef_name"> | |
50 | <title>Typedef Index</title> | |
51 | </index> | |
52 | ||
53 | <index type="function_name"> | |
54 | <title>Function Index</title> | |
55 | </index> | |
56 | ||
57 | <index type="macro_name"> | |
58 | <title>Macro Index</title> | |
59 | </index> | |
60 | ||
61 | <index/> | |
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"><</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 | |
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">'''<index/>''' </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"><auto-index-internal>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"><</span><span class="identifier">section</span><span class="special">>...</</span><span class="identifier">section</span><span class="special">></span></code> | |
116 | 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> | |
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"><</span><span class="identifier">chapter</span><span class="special">></span></code> | |
121 | top level content rather than <code class="computeroutput"><span class="special"><</span><span class="identifier">section</span><span class="special">></span></code>s | |
122 | 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> | |
123 | 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 | |
124 | 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 | |
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"><auto-index-type>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 | <auto-index>on | |
143 | ||
144 | # PDFs rely on the XSL stylesheets to generate the index: | |
145 | <format>pdf:<auto-index-internal>off | |
146 | ||
147 | # HTML output uses auto-index to generate the index: | |
148 | <format>html:<auto-index-internal>on | |
149 | ||
150 | # Name of script file to use: | |
151 | <auto-index-script>index.idx | |
152 | ||
153 | # Set the XML wrapper for HML Indexes to "appendix": | |
154 | <format>html:<auto-index-type>appendix | |
155 | ||
156 | # Turn on multiple index support: | |
157 | <xsl:param>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 © 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> |