Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

PrevUpHomeNext

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]

PrevUpHomeNext