[boost] Boostbook + quickbook for non-boost use (was Re: Boost.Plot? - Scalable Vector Graphics)

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.

[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