On Feb 10, 2005, at 12:52 PM, James Fowler wrote:
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?
I ran into some serious problems with Doxygen 1.4.x and had to downgrade. Grrrr.
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".
I think the documentation update sitting on my laptop removes that line, because of the problems with 1.4.1 :(
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.
Oh, that is important. Hmmm.
, 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 got this far, then got frustrated. It isn't the first time Doxygen XML has changed out from under us :(.
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?
I don't believe anyone else has figured this out. Your help would be *greatly* appreciated, and I'll do my best to answer questions, review code, etc.
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?)
I think Doxygen is the right way to go. What really needs to happen is that we establish a report with the Doxygen developer(s), so that the evolution of Doxygen XML goes the way we need it to, instead of biting us every few releases.
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?
It should be added to the bjam rules for BoostBook HTML, I think. Doug
------------------------------------------------------- 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
