On Wednesday 29 July 2009 10:06:54 Paul A. Bristow wrote:
Unusually, there is lots (too much? - 6Mbyte hyperlinked and indexed PDF!) of documentation, produced using the C++ in QuickBook with Doxygen reference info and John Maddock's auto-indexing. But there are hundreds of options, so you will need all the help you can get from tutorials, examples and indexes.
[snip]
PS Thanks to all those who have offered support, especially John Maddock of course. It has stress-tested the Quickbook - Doxygen indexing system ;-) I haven't managed to make the index work perfectly yet and I'm sure it can be improved.
The library is already proving useful for me but the documentation is even better than the library for some purposes. As a real software masochist, I have been using quickbook+boostbook for documentation generation at work and have run into some problems which you seem to have solved. Here are some questions and some comments on the boostbook + quickbook toolchain: 0. Is the indexing system available somewhere? 1. Occasionally, on some template classes, the generated doxygen documentation in PDF (HTML is fine) has extra hyphen characters after the class name. Your documentation does not; is some special magic required? 2. You do not have any SVGs embedded in the class reference even though examples may be very useful there. Is that intentional? 3. Which version of fop did you use? 0.95.x seems to have problems with inline attributes. I ended up using an SVN version from a few weeks ago. 4. Is there any way of convincing boostbook to actually list the following? - Template parameters to functions (using doxygen \tparam) - Bug list (doxygen \bug) and todo list (doxygen \todo) - private members of classes which have doxygen documentation - an equivalent of doxygen \see The required changes to doxygen2boostbook.xsl seem straightforward but boostbook itself might need to be modified to support this. 5. When applying doxygen2boostbook.xsl, unless my code is in a subdirectory of a directory called boost, passing in a value for boost.doxygen.header.prefix generates incorrect links (if the value passed in is x, links go to x/x/foo.h instead of x/foo.h). Do you avoid this by virtue of using the file layout in the sandbox? 6. I also had to get rid of the HTML navbar by setting the layout to none and replacing the image with a 1px transparent gif, though the pages don't look as nice then. 7. LaTeX equations in doxygen documentation which are transformed to PNGs look extremely ugly in the generated boostbook PDF documentation. I looked at Eric's support logic in boostbook but much more work is required to get Doxygen to produce PDFs which can then be directly used. For reference, the docbook dtd and stylesheets are those than come with Fedora 11. Regards, Ravi