[boost] Re: Documentation

From: David Abrahams (dave_at_[hidden])
Date: 2004-06-11 08:51:12

"Reece Dunn" <msclrhd_at_[hidden]> writes:

> 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.

FWIW, I'm not entirely opposed to frames (as long doc pages have a
"link to this page" somewhere.  I really like the general format that
Aleksey is generating for the next revision of the MPL docs, which
use frames.

>>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.

And others; we used ReST for the iterator library.

> 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. 

And it requires writing in XML :-( or translating to it :-|.

> 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. 

Spirit doesn't have reference docs, though.  It only has a long
tutorial.

-- 
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com