Subject: [boost] Boostbook + quickbook for non-boost use (was Re: Boost.Plot? - Scalable Vector Graphics)
From: Ravi (lists_ravi_at_[hidden])
Date: 2009-08-06 23:50:15
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.
> 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
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
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
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk