Re: [boost] [review][autoindex] AutoIndex review ends tomorrow

Subject: Re: [boost] [review][autoindex] AutoIndex review ends tomorrow
From: Hartmut Kaiser (hartmut.kaiser_at_[hidden])
Date: 2011-05-23 10:59:08

Sorry for the late review...

> Just a quick reminder that Saturday 21st May is the final day for the
> AutoIndex review. I'm going to wait for one final review before announcing
> the result, but other than that you need to contact me by then.

Executive summary: 
auto_index should be accepted into Boost.

Longer story: 
We have been using auto_index for some time in Spirit now and we're overall
satisfied with the generated pages. At the time when I added the index
generation to the Spirit docs I already raised a couple of issues with John.
He has addressed almost all of them. The remaining issues are not
exclusively related to auto_index and will probably require some integration
work with quickbook.

The integration into Boost.Build is excellent! The only thing missing is
some general command-line switch enabling index generation from the bjam
command line. We currently use some 'self-made' --enable-index switch,
specific to the Spirit docs (see libs/spirit/doc/Jamfile).

The auto_index insertion/integration into docbook is perfect. It works
flawlessly and that alone makes it worth using the tool.

The auto-scan facilities are a nice feature and will probably work for most
libraries. But it's close to useless for Spirit as almost no symbols found
by the tool are actually to be documented. Spirit's API consists out of a
bunch of single symbols (like int_, char_, lexeme, etc.) which are
predefined variable instances not found by auto_index. That's not a fault of
the tool, for sure, just Spirit specifics. What might work is to have some
means of annotating the sources for auto_index, forcing additional symbols
to be found.

I ended up manually listing all symbols I wanted to have in the index
(tedious!). However, as those are single words used throughout the docs (and
not only when describing the feature, i.e. such words as 'skip', 'omit',
'action', etc.) I needed to narrow the scope of topics where to look for a
certain symbol (even more tedious!):

    word "" ".*reference.binary.binary_native.*" spirit_index

What might help here is some annotation in the quickbook docs allowing to
narrow the search space for a certain symbol to the topic(s) the annotation
is found in. I'm not knowledgeable enough to suggest anything concrete here,
though.

Here is our use case: we would like to 'automate' two things: a) find the
proper keywords while scanning the source files, and b) narrow the lookup
scope in the docs to avoid spurious index entries. Finding the keywords
should be possible using custom scanners, but I'm not sure about the latter.
Either the scanner needs to be able to optionally gather the lookup scope as
well, for instance:

    //!qi_index:word("", ".*qi.reference.binary.binary_native.*")

or, (and here I don't know if that's possible), quickbook needs to be able
to insert annotations into the generated xml. Those annotations shouldn't
show up in the finalized docs, but could be used by auto_index to guide the
lookup process.

Overall, it's a great tool and worth developing further!

Thanks!
Regards Hartmut
---------------
http://boost-spirit.com