On 1/24/2011 5:02 AM, Paul A. Bristow wrote:
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Bryce Lelbach Sent: Friday, January 21, 2011 12:44 PM To: boost@lists.boost.org Subject: Re: [boost] Review request: auto-index tool
:) Hey John. As one of the users of this tool, I'd be happy to do an (informal) review of this.
I'm also a user of John's Auto-index and I'd like to indulge in a few thoughts on indexing, and indeed Boost documentation in general.
snipped...
So I feel we need to encourage library authors to produce:
1 PDF version as well as HTML (and so use Quickbook?).
Is there some simple doc on how to produce PDF from 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?).
If by "Doxygen comments" you mean comments in the implementation portion of the code, I do not see the value of this to the end-user. OTOH perhaps you mean the normal Doxygen documentation which generates the Doxygen reference section.
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.
This would be very nice. In order to produce the docs for my sandbox libraries I borrowed from you and others but there really does not seem to be an official Quickbook template to use.
(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)).