-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Patrick Horgan Sent: Monday, January 24, 2011 6:03 PM To: boost@lists.boost.org 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@hetp.u-net.com