auto_index/doc/auto_index.qbk

[article AutoIndex
    [quickbook 1.4]
    [copyright 2008 John Maddock]
    [license
        Distributed under the Boost Software License, Version 1.0.
        (See accompanying file LICENSE_1_0.txt or copy at
        [@http://www.boost.org/LICENSE_1_0.txt])
    ]
    [authors [Maddock, John]]
    [/last-revision $Date: 2008-11-04 17:11:53 +0000 (Tue, 04 Nov 2008) $]
]

[section:overview Overview]

AutoIndex is a tool for taking the grunt work out of indexing a
Quickbook\/Boostbook\/Docbook document 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 occurance of each term to be
indexed.  

Instead AutoIndex will 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 XML document for you.

AutoIndex creates index entries as follows - for each occurance of 
each search term, it creates two index entries - one has the search term
as the primary index key and the title of the section it appears in as
a subterm, the other has the section title as the main index entry and the
search term as the subentry.  Thus the user has two chances to find what their
looking for, based upon either the section name or the ['function], ['class], ['macro] 
or ['typedef] name.

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

[$../students_t_eg_1.png]

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

[$../students_t_eg_2.png]

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 authors
expectations.

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 attritubes 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 a lot less good, 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 
approprate section:

[$../students_t_eg_3.png]

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

[$../students_t_eg_4.png]

[endsect]

[section:tut Getting Started and Tutorial]

[h4 Step 1: Build the tool]

cd into `tools/auto_index/build` and invoke bjam as:

   bjam release

Optionally pass the name of the compiler toolset you want to use to bjam as well:

   bjam release gcc

[h4 Step 2: Configure Boost.Build]

TODO: we need BoostBook integration!!!

Currently the tool can only be run manually.

[h4 Step 3: Add indexes to your documentation]

To add a single index to a BoostBook\/Docbook document, then add
`<index/>` at the location where you want the index to appear.  The
index will be rendered as a separate section when the documentation
is built.

To add multiple indexes, then give each one a title and set it's
`type` attribute to specify which terms will be included, for example
to place the ['function], ['class], ['macro] or ['typedef] names
indexed by ['auto_index] in separate indexes along with a main
"include everything" index as well, one could add:

  <index type="class_name">
  <title>Class Index</title>
  </index>

  <index type="typedef_name">
  <title>Typedef Index</title>
  </index>

  <index type="function_name">
  <title>Function Index</title>
  </index>

  <index type="macro_name">
  <title>Macro Index</title>
  </index>

  <index/>
  
In quickbook, you add the same markup but enclose it in an escape:

   '''<index/>'''
   
[h4 Step 4: Create the script file]

AutoIndex works by reading a script file that tells it what to index,
at it's 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
   
Or we can recursively scan through directories looking for all
the files to scan whose name matches a particular regular expression:

   !scan-path "../../../../boost/math" ".*\.hpp" true
   
Note how each argument is whitespace separated and can be optionally
enclosed in "double quotes".  The final ['true] argument indicates
that subdirectories in `../../../../boost/math` should be searched
in addition to that directory.

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:

   foobar
   
will index occurances of "foobar" and:

   foo bar
   
will index occurances of "foo" under the name "bar".

This inclusion rule can also restict 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"
   
[h4 Step 5: Iterate]

Creating a good index is an iterative process, often the first step is
just to add a header scanning rule to the script file and then generate
the documentation and see:

* What's missing.
* What's been included that shouldn't be.
* What's been included under a poor name.

Further rules can then be added to the script to handle these cases
and the next iteration examined, and so on.

[endsect]

[section:script_ref Script File Reference]


[endsect]

[section:comm_ref Command Line Reference]

[endsect]