Boost logo

Boost :

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


Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk