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

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
[phone]  07714330204
pbristow_at_[hidden]