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

Subject: [boost] [review] Formal review of AutoIndex starts 5th May
From: Daniel James (dnljms_at_[hidden])
Date: 2011-05-04 17:35:49

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.

About AutoIndex
===============

The documentation describes it as "a tool for taking the grunt work
out of indexing a Boostbook/Docbook document that describes C/C++
code".

The documentation is online at:

http://svn.boost.org/svn/boost/sandbox/tools/auto_index/doc/html/index.html

AutoIndex can be downloaded from the vault:

http://www.boostpro.com/vault/index.php?action=downloadfile&filename=auto_index-0.9.zip

The download also contains a pdf of the documentation at
'doc/auto_index.pdf', and a copy of the html documentation at
'doc/html/index.html'.

You can also see some examples of the indexes it generates, in a few
libraries' documentation:

http://www.boost.org/libs/spirit/
http://www.boost.org/libs/type_traits/
http://www.boost.org/libs/math/doc/sf_and_dist/html/

Review guidelines
=================

Reviews should be submitted to the developer list
(boost_at_[hidden]), with '[autoindex]' in the subject. Or if you
don't wish to for some reason, you can send them privately to me. If
so, please let me know whether or not you'd like your review to be
forwarded to the list.

All reviews are appreciated, even if you don't have time for an
in-depth study. It's worth a look even if you don't use docbook or the
boost documentation tools yourself. As someone who uses boost, the
generated indexes are intended for your use so your views do matter.

Even though this isn't a library, I think the (slightly modified)
general guidelines still apply:

   - What is your evaluation of the design?
   - What is your evaluation of the implementation?
   - What is your evaluation of the documentation?
   - What is your evaluation of the potential usefulness of AutoIndex?
   - Did you try to use it?  With what compiler?  Did you have any problems?
   - How much effort did you put into your evaluation? A glance? A
     quick reading? In-depth study?
   - Are you knowledgeable about the problem domain?

And finally, every review should answer this question:

   - Do you think that AutoIndex should be accepted into Boost?
     Be sure to say this explicitly so that your other comments don't
     obscure your overall opinion.

More detail on the review process is available at:

http://www.boost.org/community/reviews.html

I think it should be made clear that if accepted, there won't be any
requirement to use AutoIndex it.

Thanks in advance,

Daniel James
AutoIndex Review Manager