I recently started working with BoostBook, and while it's not exactly painless it looks promising. However, working my way through the rough spots is taking more time than I'd like - but I'm sure some of that is dealing with the learning curve as I haven't worked extensively with docbook (or even xsl). After perusing the boostbook docs, the archives for this list and the wiki, I still have a few questions. Hopefully the answers will help me determine if I'm moving in the right direction...
1) Is anyone successfully using Doxygen 1.4.x with boostbook?
In the boostbook docs
(http://www.boost.org/regression-logs/cs-win32_metacomm/doc/html/boostbook/setup/manual.html#boostbook.setup.doxygen)
it says that most 1.3.x and 1.4.x versions of doxygen "will suffice". Messages in the list archive seem to indicate that 1.3.7 and 1.3.9 works, but I see no mention of success with any 1.4.x version. I want to use 1.4.x because it deals with nested classes. However, when I initially installed 1.4.1, all the classes disappeared from the docs. After confirming that the issue was the doxygen version (works with 1.3.9.1, classes lost with 1.4.0 and 1.4.1), I started analyzing the differences in autodoc.doxygen and found that 1.4.x no longer adds <innerclass ...> elements to <compounddef ... type="file"> elements, which doxygen2boostbook.xsl was using to find classes. I hacked on doxygen2boostbook.xsl until I got the classes back, but it appears that information on the classes namespace was lost in the process. I think I can get namespaces back in, however I'm not familiar enough with the system to easily recognize whether these changes are introducing other problems. If someone else has already figured all this out, or if it should be working and I've just haven't got everything properly configured, I'd rather get back to the documentation I was working on! If not, is there anyone familiar with doxygen2boostbook.xsl and willing to work with me to see if these changes make sense?
2) Is Doxygen recommend for use with boostbook? For libraries which are not mostly templates (i.e., shouldn't push doxygen too hard), it appears to be a good solution and it's worked well on previous projects (not using boostbook). I generally consider extracting documentation from the source to be a "good thing". However, if the consensus is that there's a better way, or that boostbook's support for doxygen is problematic and may get dropped, I'd rather be looking at the alternatives. (which, other than keeping the docs separate in boostbook xml format, would be... what?)
3) I noticed that viewing the html produced by running "bjam --v2" in the doc directory of my project looks rather spartan compared to the output produced in $(BOOST)/doc/html. This appears to be because boostbook.css didn't get moved to my project's doc/html (copying it over brought the formatting back). Is there some configuration tidbit I'm missing? If not, should this be added to the bjam doxygen rule?
Potentially relevant details:
using Boost 1.32 (didn't see anything newer in CVS that looked
relevant for these problems - although I'm not sure I was looking in all
the right places)
using Windows XP with VC6 (msvc) and VC71 (vc-7_1)
using docbook xsl V1.61.3 and dtd V4.2
using doxygen 1.3.9.1, 1.4.0, and 1.4.1
"bjam --v2" in $(BOOST)/docs successfully rebuilds documentation (as
far as I can tell) when using doxygen 1.3.9.1That's all for now...
- james
------------------------------------------------------- SF email is sponsored by - The IT Product Guide Read honest & candid reviews on hundreds of IT Products from real users. Discover which products truly live up to the hype. Start reading now. http://ads.osdn.com/?ad_id=6595&alloc_id=14396&op=click _______________________________________________ Boost-docs mailing list [email protected] Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs
