Re: [boost] [autoindex] Rationale Question

Subject: Re: [boost] [autoindex] Rationale Question
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2011-05-06 14:16:18

> -----Original Message-----
> From: boost-bounces_at_[hidden] [mailto:boost-bounces_at_[hidden]] On Behalf Of Artyom
> Sent: Friday, May 06, 2011 5:45 PM
> To: boost_at_[hidden]
> Subject: [boost] [autoindex] Rationale Question
> 
> Hello,
> 
> It is not a review but rather questions about this tool rationale.
> 
> Form the very brief look into AutoIndex documentation I see.
> 
> > ... AutoIndex will automatically scan one or more C/C++ header files
> > and extract all the function, class, macro and typedef names that are
> > defined by those headers, and then insert the <indexterm>s into the
> > Docbook XML document for you.
 
> So there is a well debugged, tested, supported indexing tool (Doxygen) that as far as I know works
fine and
> is already used by Boost.
> 
> So the question are
> 1. How does it differs from Doxygen indexing?

It indexes *everything* in Docbook documentation text, not just the functions, macros ... that
Doxygen does
(and should be done by Doxygen in the Library Reference section).   (Actually you can control what
it indexes and what it doesn't, quite finely, and create sub-indexes, etc but the simple default
action is to index everything).

The *big* limitation of a Doxygen index is that you have to know (or guess) the name of the
function/class...

If you just want to know 'how to do something', you are stuck - and I often find I am :-)

You can get the flavour of a trivial (silly even) demo/template at

https://svn.boost.org/svn/boost/sandbox/guild/mylibrary/doc/mylibrary.pdf

and bit more of the flavour of a small real-life Boost library refurbishment project at

https://svn.boost.org/svn/boost-sandbox/guild/pool/libs/pool/doc/pool.pdf

and if you are prepared to wait download 6 Mbyte

https://svn.boost.org/svn/boost/sandbox/SOC/2007/visualization/libs/svg_plot/doc/pdf/svg_plot.pdf

has quite full Doxygen function documentation AND an index of the documentation.

None of these are as good as I would wish, but that's lack of time and enthusiasm, not the tool.

So AutoIndex is *additional to*, not instead of Doxygen indexing.

HTH

Paul

---
Paul A. Bristow,
Prizet Farmhouse, Kendal LA8 8AB  UK
[phone]  07714330204
pbristow_at_[hidden]