Boost logo

Boost :

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
quickly.
> >
> > (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)).
>
> 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
course).

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
auto-index treatment?

(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
fought
> 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

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