Re: [boost] [log] Documentation improvement suggestions

Subject: Re: [boost] [log] Documentation improvement suggestions
From: Andrey Semashev (andrey.semashev_at_[hidden])
Date: 2011-08-05 05:17:51

On 08/05/2011 12:42 PM, Paul A. Bristow wrote:
>
>
>> Regarding the note about definitions. Does anyone know if it's
>> possible to make a tooltip in quickbook?
>
> As far as I know, this is not possible - but you can provide a link
> so that the puzzled can click drill down for more explanation.
>
> This is widely used to provide links to outside reference sources
> like Wikipedia.  IMO they are very easy to add and very helpful to
> the less-well-informed reader.

Yes, it seems I'll have to put links instead. It's just too inconvenient 
IMHO since the link changes the viewing context of the reader.

> (One of the virtues of the Quickbook toolchain is that it can (and
> does) produce single file PDFs.  These include hyperlinks, but not
> tooltips.)

I see. Perhaps, tooltips could be added just for html output? I find 
them really useful in contexts like this, it's a shame to lose this tool.

> PS Don't forget too that John Maddock's Autoindex is now available.
> You can index C++ class, function etc names from the Doxygen
> reference, and also index terms (that the author thinks may be
> useful) in the text part.  To ensure that the index takes the reader
> to the 'page' containing the index term, it is wise to avoid too long
> sections, so I would advise using sections quite freely - no bad
> thing anyway (as one reader of your draft commented).

Interesting, I also implemented an indexing mechanism as a part of 
Boost.Log docs compilation so that it creates macros that add links to 
corresponding sections of reference. I'll take a look at Autoindex.