From: Scott Meyers (usenet_at_[hidden])
Date: 2006-03-03 00:02:27
David Abrahams wrote:
> I don't know what you mean by "extra," but it goes like this: the
> Boost source code repository contains at least four different
> documentation formats:
>
> 1. Straight HTML, authored by the library writer, in
> libs/<libraryName>/doc. Once upon a time, all our docs were
> written by hand in HTML.
>
> 2. ReStructuredText. This is used to generate HTML, and sometimes,
> PDF. Generally the resulting files are checked into the
> repository somewhere under libs/<libraryName>/doc.
>
> 3. BoostBook. This is used to generate HTML, and sometimes, PDF.
> The results become one unified document (see "Nightly generated
> BoostBook documentation" at
> http://engineering.meta-comm.com/boost.aspx) and are too big to
> check into the source code repository. They're generated
> on-the-fly and
Having followed Boost from afar for many years and now trying to know it better,
my perspective is that different formats are mildly annoying, but different
documents on the same topics in different locations is pretty baffling. Go to
the Boost home page and click on Libraries>Documentation, and you're taken to
http://www.boost.org/libs/libraries.htm. This appears to be a comprehensive
listing of libraries in Boost, but, as was clarified for me in an earlier
thread, this includes only libraries in the current release; libraries accepted
into Boost since then are not listed here. Still, this page provides links to
documentation for each library (in libs<libraryName>doc).
However, a recent mention on this list of QuickBook, which I had never heard of,
led me via Google to http://www.boost.org/doc/html/boostbook.html, which is in
the middle the BoostBook David mentions above -- something else I had never
heard of. Working my way up the path from there led me to
http://www.boost.org/doc/html/, which is another listing of libraries in Boost,
but this one is much shorter than the one above. Until I read David's post
above, I was planning to post a question asking about the relationship between
the two lists of libraries. Now I'll simply remark that the current situation
is, in my view, confusing. Given that the BoostBook is far from complete, what
is its purpose?
Scott