Re: [boost] BoostBook

From: Douglas Gregor (gregod_at_[hidden])
Date: 2003-09-22 09:18:54

On Monday 22 September 2003 10:02 am, Kevin S. Van Horn wrote:
> Douglas Gregor wrote:
> > there is a project to normalize the look-n-feel of Boost
> > documentation via the "BoostBook" documentation format.
>
> Looking at the BoostBook Wiki, it states that the goals for the BoostBook
> format include
>
> - should be possible to express mathematical formulas
>
> How well does BoostBook meet these goals?  It seems to be based on DocBook,
> and my experience with DocBook has been that using it is quite painful if
> you have any significant amount of mathematics in your document.

It's failing this goal quite fantastically, for the reason you give. DocBook 
had a whole heck of a lot of advantages that LaTeX did not, but LaTeX had the 
solid math support. 

[Reordered]
> - source format should be easy to write and read.

This is mostly a matter of taste :) XML can be tedious to write (although the 
editor support is very good), but it's not hard. One can write a simple 
BoostBook document using the "HTML conversion guide" that's part of the 
BoostBook documentation. The C++ part of BoostBook is big (lots of elements), 
but similar enough to C++ in terminology and structure that it isn't hard to 
write; besides, one doesn't need to write this part any more because the 
Doxygen bridge is getting much, much better now.

        Doug