Scott Meyers
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