Boost C++ Libraries Home Libraries People FAQ More

PrevUpHomeNext

Step 3: Add indexes to your documentation

To add a single "include everything" index to a BoostBook/Docbook document, (perhaps generated using Quickbook, and perhaps also using Doxygen reference section), add <index/> 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.

To add multiple indexes, then give each one a title and set its type attribute to specify which terms will be included, for example to place the function, class, macro or typedef names indexed by AutoIndex in separate indexes along with a main "include everything" index as well, one could add:

<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/>
[Note] Note

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 <xsl:param>index.on.type=1 to your projects requirements in the Jamfile.

In Quickbook, you add the same markup but enclose it between two triple-tick ''' escapes, thus

'''<index/>''' 

Or more easily via the helper file auto_index_helpers.qbk, so that given:

[include auto_index_helpers.qbk]

one can simply write:

[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]
[Note] Note

AutoIndex knows nothing of the XML xinclude 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 xinclude.

If you are using AutoIndex's internal index generation on

<auto-index-internal>on

(usually recommended for HTML output, but not the default) then you can also decide what kind of XML wrapper the generated index is placed in. By default this is a <section>...</section> XML block (this replaces the original <index>...</index> 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 <chapter> top level content rather than <section>s then it may be preferable to place the index in a <chapter> or <appendix> block. You can also place the index inside an <index> 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.

You control the type of XML block used by setting the <auto-index-type>element-name attribute in the Jamfile, or via the index-type=element-name command line option to AutoIndex itself. For example, to place the index in an appendix, your Jamfile might look like:

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

PrevUpHomeNext