[boost] [autoindex] Review

Subject: [boost] [autoindex] Review
From: Edward Diener (eldiener_at_[hidden])
Date: 2011-05-10 17:31:16

This is my review of autoindex.

- What is your evaluation of the design?

Very clean and easy to understand.

- What is your evaluation of the implementation?

Did not look at the internals.

- What is your evaluation of the documentation?

Generally good. Here is a list of mostly grammatical errors:

1) Overview:

"the HTML indexes look a lot less good"
->
"the HTML indexes look a lot worse"

Step 1: Build the AutoIndex tool:

"Finally note that tools/auto_index/auto-index.jam gets copied into the 
same directory as the rest of the Boost.Build tools."
->
I am not sure if this means that building AutoIndex does this 
automatically or the end-user must do it but the sentence grammar 
suggests the former, which does not happen for me. If the end-user 
should do it, the line should read "Finally note that 
tools/auto_index/auto-index.jam should be copied into the same directory 
as the rest of the Boost.Build tools."

2) Step 2: Configure Boost.Build jamfile to use AutoIndex

"Always send the output to a log file. It will contain of lot of stuff, 
but is invaluable to check if all has gone right, and else diagnose what 
has gone wrong.
->
..."and also diagnose what has gone wrong."
..."or else diagnose what has gone wrong."

3) Available Indexing Options:

For Document Type 'library', Available Index Types says 'See Chapter'. I 
am guessing this means it is the same as Document Type 'chapter' but it 
should be made clearer in the remark.

4) Step 7: Iterate - to refine your index:

"You can restrict which sections are indexed for a particular term. So 
assuming that the docbook document has the usual hierarchical names for 
section ID's hierarchical names for section IDs(as Quickbook generates, 
for example), you can easily place a constraint on which sections are 
examined for a particular term. " '
->
remove the second repeated "hierarchical names for section IDs".

"This would avoid an index entry every time ° kelvin is found, something 
the user is unlikely to find helpful. "
->
"This would avoid an index entry every time 'Kelvin' is found, something 
the user is unlikely to find helpful. "

5) Script File (.idx) Reference:

"Blank lines consisting of only whitespace are ignored, so are lines 
that start with a #. (But, of course, you can't append # comments onto 
the end of a line!). "
->
I am guessing this should be:
"...(But, of course, you can append # comments onto the end of a line!)."

"recurse

     An optional boolean value - either "true" or "false" - that 
indicates whether to recurse into subdirectories. This defaults to "false"
->
Needs a period at the end.

"type

     The type to which items found using this rule will assigned, index 
terms created from the source file and then found in the XML, will have 
the type attribute set to this value, and may then appear in a 
specialized index with the same type attribute "
->
Needs a period at the end.

The only other issue in the documentation is that while there is very 
good documentation about what type of XML container wraps an internally 
generated index, I am not sure what this actually means to a Quickbook 
author. No doubt somewhere there is probably a discussion in Docbook of 
what these XML containers mean and do but, aside from experimentation, 
the user of AutoIndex is not likely to understand what it means to put 
the Index in a specific XML container and how this affects the final 
layout of the documentation. Perhaps some further explanation of what 
this actually means for an AutoIndex user, especially for a Quickbook 
document, would be appropriate.

- What is your evaluation of the potential usefulness of AutoIndex?

Immense. Searching through documentation of even mildly complex 
libraries which have little or no index is very frustrating.

- Did you try to use it?  With what compiler?  Did you have any problems?

I have used it for the documentation of my VMD and TTI libraries with 
both gcc and vc++ under Windows. Any problems were of my own making and 
the author of AutoIndex answered my questions when I was stuck.

- How much effort did you put into your evaluation? A glance? A
      quick reading? In-depth study?

A pretty deep study, although I have not tried to add anything to the 
index file other than 'scan' statements.

- Are you knowledgeable about the problem domain?

Yes.

I vote for the library to be accepted into Boost.

Edward Diener