-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Robert Ramey Sent: Thursday, May 05, 2011 3:22 PM To: boost@lists.boost.org Subject: Re: [boost] [review] Formal review of AutoIndex starts 5th May
Daniel James wrote:
Hello everyone,
The formal review of John Maddock's AutoIndex starts tomorrow, 5th May and finishes on Saturday 14th May. It's a little different to normal as it's a review of a documentation tool, rather than a library. We'll follow the normal procedure. Hopefully the review will also provide some experience for deciding how to deal with other tools in the future.
I am away during the review period (and my internet connection has gone wrong so even is email flakey), so I would like to 'pre-review' John's autoindex. First a confession - I have been nagging John for some time about a way of producing an index - (mainly of Boost.Math). I have been using the index for some libraries and found that it works well enough. It is not perfect (but then I suspect that no automatic index ever will be) - and lots of manually edited indexes are not that good either, and they cannot survive frequent updates to the text. Even an indifferent index is massively better than no index. (The only other tool I have used is to search the PDF version - if the index term has not been foreseen by the indexer, this remains a good tactic). But the results are certainly functional. (I can vouch for this because I have often used the index to find some information that I know is in my own docs but I am having a 'senior moment' about where ;-) It requires the author to specify the index terms - a skilled but tedious task requiring reading-the-mind-of-the-readers. The regex (I suppose it was inevitable written by Dr Regex himself) mechanism works well enough to deal with the many variants, plurals etc. Writing the regex expressions can be a bit tedious, but it works. The main criticism I have is that it tends to produce too many (often duplicate) index entries. But this is partly due to my lack of skill and patience in refining the index terms file. So I am strongly in favour of immediate acceptance of this tool, and of adoption by all authors using the QuickBook/Doxygen tool chain. I believe we need to do very much better on Boost libraries' documentation and this is an important tool to achieve that. Paul --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com