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


Step 4: Create the .idx script file - to control what to terms to index

AutoIndex works by reading a script file that tells it what terms to index.

If your document contains largely text, and only a small amount of simple C++, and/or if you are using Doxygen to provide a C++ Reference section (that lists the C++ elements), and/or if you are relying on the indexing provided from a Standalone Doxygen Index, you may decide that a index is not needed and that you may only want the text part indexed.

But if you want C++ classes functions, typedefs and/or macros AutoIndexed, optionally, the script file also tells which other C++ files to scan.

At its simplest, it will scan one or more headers for terms that should be indexed in the documentation. So for example to scan "myheader.hpp" the script file would just contain:

!scan myheader.hpp
!scan mydetailsheader.hpp

Or, more likely in practice, so we can recursively scan through directories looking for all the files to scan whose name matches a particular regular expression:

!scan-path "boost/mylibrary" ".*.hpp" true 

Each argument is whitespace separated and can be optionally enclosed in "double quotes" (recommended).

The final true argument indicates that subdirectories in /boost/math/mylibrary should be searched recursively in addition to that directory.

[Caution] Caution

The second file-name-regex argument is a regular expression and not a filename GLOB!

[Caution] Caution

The scan-path is modified by any setting of <auto-index-prefix>. The examples here assume that this is <auto-index-prefix>../../.. so that boost/mylibrary will be your header files, libs/mylibrary/doc will contain your documentation files and libs/mylibrary/example will contain your examples.

You could also scan any examples (.cpp) files, typically in folder /mylibrary/lib/example.

# All example source files, assuming no sub-folders.
!scan-path "libs/mylibrary/example" ".*.cpp"

Often the scan or scan-path rules will bring in too many terms to search for, so we need to be able to exclude terms as well:

!exclude type

Which excludes the term "type" from being indexed.

We can also add terms manually:


will index occurrences of "foobar" and:

foobar \<\w*(foo|bar)\w*\>

will index any whole word containing either "foo" or "bar" within it, this is useful when you want to index a lot of similar or related words under one entry, for example:


Will only index occurrences of "reflex" as a whole word, but:

reflex \<reflex\w*\>

will index occurrences of "reflex", "reflexing" and "reflexed" all under the same entry reflex. You will very often need to use this to deal with plurals and other variants.

This inclusion rule can also restrict the term to certain sections, and add an index category that the term should belong to (so it only appears in certain indexes).

Finally the script can add rewrite rules, that rename section names that are automatically used as index entries. For example we might want to remove leading "A" or "The" prefixes from section titles when AutoIndex uses them as an index entry:

!rewrite-name "(?i)(?:A|The)\s+(.*)" "\1"