Available Indexing Options

The available options are:

<auto-index>off/on

Turns indexing of the document on, defaults to "off", so be sure to set this if you want AutoIndex invoked!

<auto-index-internal>off/on

Chooses whether AutoIndex creates the index itself (feature on), or whether it simply inserts the necessary DocBook markup so that the DocBook XSL stylesheets can create the index. Defaults to "off".

<auto-index-script>filename

Specifies the name of the script to load.

<auto-index-no-duplicates>off/on

When on AutoIndex will only index a term once in any given section, otherwise (the default) multiple index entries per term may be created if the term occurs more than once in the section.

<auto-index-section-names>off/on

When on AutoIndex will use create two index entries for each term found - one uses the term itself as the primary index key, the other uses the enclosing section name. When off the index entry that uses the section title is not created. Defaults to "on"

<auto-index-verbose>off/on

Defaults to "off". When turned on AutoIndex prints progress information - useful for debugging purposes during setup.

<auto-index-prefix>filename

Optionally specifies a directory to apply as a prefix to all relative file paths in the script file.

You may wish to do this to reduce typing of pathnames, and/or where the paths can't be located relative to the script file location, typically if the headers are in the Boost trunk, but the script file is in Boost sandbox.

For Boost standard library layout, <auto-index-prefix>../../.. will get you back up to the 'root' of the Boost tree, so !scan-path boost/mylibrary/ is where your headers will be, and libs/mylibrary for other files. Without a prefix all relative paths are relative to the location of the script file.

<auto-index-type>element-name

Specifies the name of the XML element in which to enclose an internally generated indexes: defaults to section, but could equally be appendix or chapter or some other block level element that has a formal title. The actual list of available options depends upon the Quickbook document type, the following table gives the available options, assuming that the index is placed at the top level, and not in some sub-section or other container:

Document Type	Permitted Index Types
book	appendix index article chapter reference part
article	section appendix index sect1
chapter	section index sect1
library	The same as Chapter (section index sect1)
part	appendix index article chapter reference
appendix	section index sect1
preface	section index sect1
qandadiv	N/A: an index would have to be placed within a subsection of the document.
qandaset	N/A: an index would have to be placed within a subsection of the document.
reference	N/A: an index would have to be placed within a subsection of the document.
set	N/A: an index would have to be placed within a subsection of the document.

In large part then the choice of <auto-index-type>element-name depends on the formatting you want to be applied to the index:

XML Container Used for the Index	Formatting Applied by the XSL Stylesheets
appendix	Starts a new page.
article	Starts a new page.
chapter	Starts a new page.
index	Starts a new page only if it's contained within an article or book.
part	Starts a new page.
reference	Starts a new page.
sect1	Starts a new page as long as it's not the first section (but is controlled by the XSL parameters chunk.section.depth and/or chunk.first.sections).
section	Starts a new page as long as it's not the first section or nested within another section (but is controlled by the XSL parameters chunk.section.depth and/or chunk.first.sections).

In almost all cases the default (section) is the correct choice - the exception is when the index is to be placed directly inside a book or part, in which case you should probably use the same XML container for the index as you use for whatever subdivisions are in the book or part. In any event placing a section within a book or part will result in invalid XML.

Finally, if you are using Quickbook to generate the documentation, then you may wish to add:

<include>$boost-root/tools/auto_index/include

to your projects requirements (replacing $boost-root with the path to the root of the Boost tree), so that the file auto_index_helpers.qbk can be included in your quickbook source with simply a:

[include auto_index_helpers.qbk]