RE: [boost] Documentation

From: Reece Dunn (msclrhd_at_[hidden])
Date: 2004-06-11 06:35:41

David B. Held wrote:
>Ok, if the Boost style documentation is too simple, and docs like
>Spirit are too cute, what is a nice, happy median?

Have you looked at the BoostBook generated docs :). Let me know what you 
think of the current L&F: I have updated this a while ago to try and bridge 
the gap between the two looks (the docs now have Spirit-style navigation). 
See 
http://boost.sourceforge.net/regression-logs/cs-win32_metacomm/doc/html/index.html 
for the new-stle docs.

>If we're going
>to demand uniformity in licensing, should we also demand more
>uniformity in documentation?

I agree on this. At the moment, we have the docs written in HTML, those in 
BoostBook format (like Boost.Any and the BBv2 docs) and the Spirit docs 
which have their own format.

As far as I understand it, the BoostBook tool is relatively new and has a 
learning curve, so it will take some time to migrate the docs to this 
format. As for the Spirit docs, they have their own sourceforge area as well 
as being a part of Boost, so forcing them to change doc format wouldn't be 
fair. However, since the Spirit docs are in a special text format that is 
"compiled" into HTML using Spirit, it should be easy to create a BoostBook 
back-end and have the docs in boost in this format and the ones on the 
sourceforge area in the existing format.

With this in mind, it might be beneficial to create a HTML to BoostBook 
converter (possibly using Spirit) to allow easier migration to the BoostBook 
format.

>I think a single documentation style
>across Boost would make it even easier to learn new libraries. I
>recently found it very difficult to find the information I wanted about
>the Boost.Test library, as well as Boost.Preprocessor.  What can
>be done about these issues?

I think the BoostBook format would go a long way to resolving these issues, 
once the docs are all in this uniform format.

Regards,
Reece

_________________________________________________________________
Express yourself with cool new emoticons http://www.msn.co.uk/specials/myemo