Re: [boost] Improving Documentation

Subject: Re: [boost] Improving Documentation
From: Daniel James (daniel_at_[hidden])
Date: 2013-10-14 04:46:54

On 14 October 2013 09:11, Paul A. Bristow <pbristow_at_[hidden]> wrote:
>
>
>> -----Original Message-----
>> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Andrey Semashev
>> Sent: Saturday, October 12, 2013 10:31 AM
>> To: boost_at_[hidden]
>> 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).