On 14 October 2013 09:11, Paul A. Bristow <pbristow@hetp.u-net.com> wrote:
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Andrey Semashev Sent: Saturday, October 12, 2013 10:31 AM To: boost@lists.boost.org Subject: Re: [boost] Improving Documentation
(and there are others like \sa = see also).
While I agree with you that Doxygen is a great tool for generating reference sections, when I was writing Boost.Log docs I found that Boost stylesheets discarded most of the special tags (AFAIR, \sa was one of them; \cond doesn't always work, I don't remember the others).
I think if \cond doesn't work then it's probably a doxygen bug. I don't think the things that it hides should be included in the xml that doxygen generates. The latest doxygen appears to have a bug here (it messed up the interprocess adapative_pool documentation), so I had to downgrade to fix the build. I haven't investigated it yet.
OK - more work now - and all *could* be made to work - we just need to encourage Steven Watanabe or someone to fix the XSTL code that handles them. The Quickbook admonitions work nicely and look just like in Quickbook.
Some of these tags shouldn't be too hard to support, you just need to look at the doxygen xml file to see what tags are generated, and then work out the boostbook/docbook equivalent. Btw. they're boostbook admonitions, quickbook isn't involved in the doxygen reference documentation (apart from for the asio and geometry documentation).