Re: [boost] Review request: auto-index tool

Subject: Re: [boost] Review request: auto-index tool
From: Edward Diener (eldiener_at_[hidden])
Date: 2011-01-24 13:04:43

On 1/24/2011 5:02 AM, Paul A. Bristow wrote:
>>> -----Original Message-----
>>> From: boost-bounces_at_[hidden]
>>> [mailto:boost-bounces_at_[hidden]]
>>> On Behalf Of Bryce Lelbach
>>> Sent: Friday, January 21, 2011 12:44 PM
>>> To: boost_at_[hidden]
>>> Subject: Re: [boost] Review request: auto-index tool
>
>>> :) Hey John. As one of the users of this tool, I'd be happy to do an
>> (informal) review of this.
>
>   I'm also a user of John's Auto-index and I'd like to indulge in a few
> thoughts on indexing, and indeed Boost documentation in general.

snipped...

>
> So I feel we need to encourage library authors to produce:
>
> 1  PDF version as well as HTML (and so use Quickbook?).

Is there some simple doc on how to produce PDF from Quickbook ?

>
> 2  Quickbook and Doxygen reference section.
>
> 2  Doxygen comments in C++ code about everything. (Perhaps GSoC or
> Boost.Guild people could volunteer to do this?).

If by "Doxygen comments" you mean comments in the implementation portion 
of the code, I do not see the value of this to the end-user. OTOH 
perhaps you mean the normal Doxygen documentation which generates the 
Doxygen reference section.

>
> 3  Auto-indexing of functions.,classes ... as standard. (So we need to get
> auto-index into next Boost release package).
>
> 4  Conventional word index - Indexing of words in the text.
>
> 5  A user-friendly Quickbook template so new authors can get going quickly.

This would be very nice. In order to produce the docs for my sandbox 
libraries I borrowed from you and others but there really does not seem 
to be an official Quickbook template to use.

>
> (I don't feel I am alone in finding that it's pretty hard going getting
> setting up all the tools in place, jamfiles, correct links to tools and
> headers.  Moving the code messes some 'would-be' relative address in
> jamfiles.  Getting locations of images users graphs, equations, logos,
> admonitions, navigations,  png versus svg images etc have caused me grief.
> The requirement to use only relative addressing means that there are loads
> of copies of image files bloating the file system.  And to produce a
> packable html requires installing images and style sheet(s)).