Re: [boost] [log] Documentation improvement suggestions

Subject: Re: [boost] [log] Documentation improvement suggestions
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2011-08-06 06:32:18

> -----Original Message-----
> From: boost-bounces_at_[hidden] [mailto:boost-bounces_at_[hidden]] On Behalf Of Andrey
> Semashev
> Sent: Friday, August 05, 2011 10:18 AM
> To: boost_at_[hidden]
> Subject: Re: [boost] [log] Documentation improvement suggestions
> 
> 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.

Is it possible that you can insert tooltips  using 

http://www.javascriptkit.com/howto/toolmsg.shtml

 to pass XML item title

http://www.w3schools.com/tags/att_standard_title.asp

<p><abbr title="World Health Organization">WHO</abbr> was founded in 1948.</p>
<p title="Free Web tutorials">W3Schools.com</p>

directly from Quickbook with the Escape option (perhaps with a Quickbook template)?

"Escape

The escape mark-up is used when we don't want to do any processing.

'''
escape (no processing/formatting)
'''

Escaping allows us to pass XML markup to BoostBook or DocBook. For example:

'''
<emphasis role="bold">This is direct XML markup</emphasis>
'''

This is direct XML markup

Important

Be careful when using the escape. The text must conform to BoostBook/DocBook syntax.
"

But I've not tried it :-(

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

Sounds as though it does exactly what you want already?

And you can add index terms that you want indexed from the text too.  (The index terms use regex so
that you can deal with plurals and similar variants.)

Paul

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