Re: [boost] [review] Formal review of AutoIndex starts 5th May

Subject: Re: [boost] [review] Formal review of AutoIndex starts 5th May
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2011-05-05 13:16:40

> -----Original Message-----
> From: boost-bounces_at_[hidden] [mailto:boost-bounces_at_[hidden]] On Behalf Of Robert
> Ramey
> Sent: Thursday, May 05, 2011 3:22 PM
> To: boost_at_[hidden]
> 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
[phone]  07714330204
pbristow_at_[hidden]