Daniel, I still owe you the review and I still plan on writing it. Please grant me some more time (a couple of days?). Thanks! Regards Hartmut --------------- http://boost-spirit.com

-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Daniel James Sent: Friday, May 20, 2011 2:18 PM To: boost@lists.boost.org Subject: [boost] [review][autoindex] AutoIndex review ends tomorrow

Hello everyone,

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.

thanks,

Daniel James AutoIndex Review Manager _______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost

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