...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
The available options are:
Turns indexing of the document on, defaults to "off", so be sure to set this if you want AutoIndex invoked!
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".
Specifies the name of the script to load.
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.
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"
Defaults to "off". When turned on AutoIndex prints progress information - useful for debugging purposes during setup.
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.
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]