Re: [boost] [Documentation] Does Boost-Build support Doxygen documentation for tutorials (rather then quickbook)

Subject: Re: [boost] [Documentation] Does Boost-Build support Doxygen documentation for tutorials (rather then quickbook)
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2010-12-13 07:50:26

> -----Original Message-----
> From: boost-bounces_at_[hidden] [mailto:boost-bounces_at_[hidden]]
> On Behalf Of Artyom
> Sent: Monday, December 13, 2010 8:25 AM
> To: boost_at_[hidden]
> Subject: [boost] [Documentation] Does Boost-Build support Doxygen
> documentation for tutorials (rather then quickbook)
> 
> Hello,
> 
> I would like to know if boost-build supports writing tutorials using
Doxygen
> rather that using HTML or its own "quickbook" tool.
> 
> At this point I have Boost.Locale documentation written with Markdown and
I
> want to transfer it to other tool. I want to use Doxygen for it as
Boost.Locale
> reference is already documented using Doxygen so converting the tutorials
from
> markdown to Doxygen format seems to me much better idea then using
> "internal" boost documentation format.
> 
> Rationale:
> 
> - Doxygen is more widely available tool then quickbook.
> - It is independent from boost itself.
> - It is useful for non-boost project
> - Documentation generation is much simpler (requires running Doxygen)
>   rather then using complicated tool-chain of boost-build.

Downside :-((  the results are not as nice  ;-)

(and it will be as easy to convert Markdown to Quickbook as to convert to
Doxygen.  There is a html to Quickbook conversion tool somewhere too).

You can't easily embed code snippets into the Quickbook text, ensuring that
the code example and the docs don't get separated,
and provide helpful comment when you are reading the full example C++.

And are not available in pdf.  (Very valuable in that one can search the
whole documentation for words, providing a substitute for a proper index
(something we still haven't cracked).

I would still wrap it in Quickbook but you can also provide Doxygen format
as reference AND for tutorial.
(Perhaps some expert can suggest how to get the reference and tutorial
separated ?)

The 'toolchain' in a real pain to get going, but your readers will thank you
for your perseverance!  Once set up it runs painlessly to update, and can be
done by anyone with a text editor

Paul

---
Paul A. Bristow,
Prizet Farmhouse, Kendal LA8 8AB  UK
[phone]  07714330204
pbristow_at_[hidden]