Re: [boost] [autoindex] Review

Subject: Re: [boost] [autoindex] Review
From: John Maddock (boost.regex_at_[hidden])
Date: 2011-05-11 05:10:19

>"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."

Hmm, it should get copied over, but whatever this step will go away if the 
tool is accepted into Boost as the Jamfile will be in Boost.Build already.

>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!)."

No you can't - will reword - likewise the other typos!

>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.

Will add something on that - Quickbook's support for anything other than 
<section>'s is pretty flaky at present, so very likely the solution is "use 
a section".

Many thanks for the feedback, John.