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

From: David Abrahams (dave_at_[hidden])
Date: 2006-03-04 23:54:25

Scott Meyers <usenet_at_[hidden]> writes:

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

I read on assuming you were going to point me at such documents, but
having done so I don't know what you're talking about... oh, the lists
of libraries?

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

Of course.  It would be pretty upsetting to most people if libraries
were listed there and they downloaded the release only to find they
weren't included.

> Still, this page provides links to documentation for each library
> (in libs<libraryName>doc).

What do you mean "still?"  I see no contradiction here.  There are no
libraries in http://www.boost.org/libs/ other than those in the last
release.

If you want to track the current CVS, we have a reflector of it at
http://www.boost-consulting.com/boost, where you can see a complete
list of everything that has been checked into the source code
repository (assuming the authors of the new libraries have updated the
links).

> However, a recent mention on this list of QuickBook, which I had
> never heard of, 

It's not a library.

> led me via Google to http://www.boost.org/doc/html/boostbook.html,
> which is in the middle the BoostBook David mentions above --
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^
Sorry, can't parse it.

> something else I had never heard of.  

Not a library either.

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

Yes, it's a table of contents for the docs that are generated from
BoostBook.  One day we'll port all the library docs to QuickBook or
BoostBook and then it will be complete.

> 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

BoostBook is complete.  It is a documentation format.  Perhaps you
just mean that not all documents appear in the BoostBook TOC?

> what is its purpose?

The documentation format?
http://www.boost.org/doc/html/boostbook/introduction.html

The BoostBook TOC is an index to the docs that happen to be written in
the BoostBook format.  Its existence probably _is_ somewhat confusing.
Should we eliminate it?  I'm not sure.  Maybe it would be better to
simply add a notice to the top that lets people know it doesn't cover
everything.  I've cross-posted this to the Boost documentation list so
others more knowledgeable than me can chime in.

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com