Subject: Re: [boost] Review request: auto-index tool
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2011-01-24 13:57:07
> -----Original Message-----
> From: boost-bounces_at_[hidden] [mailto:boost-bounces_at_[hidden]]
> On Behalf Of Patrick Horgan
> Sent: Monday, January 24, 2011 6:03 PM
> To: boost_at_[hidden]
> Subject: Re: [boost] Review request: auto-index tool
> On 01/24/2011 02:02 AM, Paul A. Bristow wrote:
> > ... elision by patrick...
> > So I feel we need to encourage library authors to produce:
> > 1 PDF version as well as HTML (and so use 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?).
> > 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
> > (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
> 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)).
> What a wonderful email.
> I would volunteer to put Doxygen comments in C++ code for someone.
The structure that John Maddock has set up for Boost.Pool seems OK (except
that I fear we will have some glitches when moving back to trunk, and any
updates to trunk will need to be applied to the 'Guild' version too of
A /Guild folder in boost-sandbox has folders for working copies, for example
guild/pool with usual sub-folder structure (an exact copy of trunk).
If any authors would like to offer their 'baby' to get the Doxygen and
(Raw html-only libraries are more serious work, despite a conversion aid).
Perhaps others will volunteer to tackle the docs (you have to have a
reasonable grasp of the library - I found I didn't have enough for
Boost.Pool and would like some experts to correct and amplify my efforts.
> It seems like we not only need a user-friendly
> Quickbook template, but a good tutorial document from someone that's
> through this and has found success.
I'm working on it :-)
(but listing all the many, many pits on can fall into (been there, done
that) with inscrutable diagnostics is quite a job!)
--- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow_at_[hidden]
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk