[Boost-users] Boost documentation [Was: Re: Getting started with Boost: what did you need to know?]

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