Boost C++ Libraries

AutoIndex is a tool for taking the grunt work out of indexing a Boostbook/Docbook document (perhaps generated by your Quickbook file mylibrary.qbk, and perhaps using also Doxygen autodoc) that describes C/C++ code.

Traditionally, in order to index a Docbook document you would have to manually add a large amount of <indexterm> markup: in fact one <indexterm> for each occurrence of each term to be indexed.

Instead AutoIndex will automatically scan one or more C/C++ header files and extract all the function, class, macro and typedef names that are defined by those headers, and then insert the <indexterm>s into the Docbook XML document for you.

AutoIndex can also scan using a list of index terms specified in a script file, for example index.idx. These manually provided terms can optionally be regular expressions, and may allow the user to find references to terms that may not occur in the C++ header files. Of course providing a manual list of search terms in to index is a tedious task (especially handling plurals and variants), and requires enough knowledge of the library to guess what users may be seeking to know, but at least the real 'grunt work' of finding the term and listing the page number is automated.

AutoIndex creates index entries as follows:

for each occurrence of each search term, it creates two index entries:

Thus the user has two chances to find what they're looking for, based upon either the section name or the function, class, macro or typedef name.

	Note
	This behaviour can be changed so that only one index entry is created (using the search term as the key and not using the section name except as a sub-entry of the search term).

So for example in Boost.Math the class name students_t_distribution has a primary entry that lists all sections the class name appears in:

Then those sections also have primary entries, which list all the search terms those sections contain:

Of course these automated index entries may not be quite what you're looking for: often you'll get a few spurious entries, a few missing entries, and a few entries where the section name used as an index entry is less than ideal. So AutoIndex provides some powerful regular expression based rules that allow you to add, remove, constrain, or rewrite entries. Normally just a few lines in AutoIndex's script file are enough to tailor the output to match the author's expectations (and thus hopefully the index user's expectations too!).

AutoIndex also supports multiple indexes (as does Docbook), and since it knows which search terms are function, class, macro or typedef names, it can add the necessary attributes to the XML so that you can have separate indexes for each of these different types. These specialised indexes only contain entries for the function, class, macro or typedef names, section names are never used as primary index terms here, unlike the main "include everything" index.

Finally, while the Docbook XSL stylesheets create nice indexes complete with page numbers for PDF output, the HTML indexes look poorer by comparison, as these use section titles in place of page numbers... but as AutoIndex uses section titles as index entries this leads to a lot of repetition, so as an alternative AutoIndex can be instructed to construct the index itself. This is faster than using the XSL stylesheets, and now each index entry is a hyperlink to the appropriate section:

With internal index generation there is also a helpful navigation bar at the start of each Index:

Finally, you can choose what kind of XML container wraps an internally generated index - this defaults to <section>...</section> but you can use either command line options or Boost.Build Jamfile features, to select an alternative wrapper - for example appendix or chapter would be good choices, whatever fits best into the flow of the document. You can even set the container wrapper to type index provided you turn off index generation by the XSL stylesheets, for example by setting the following build requirements in the Jamfile:

<format>html:<auto-index-internal>on       # Use internally generated indexes.
<auto-index-type>index                     # Use <index>...</index> as the XML wrapper.
<format>html:<xsl:param>generate.index=0   # Don't let the XSL stylesheets generate indexes.