David Abrahams said: (by the date of Mon, 11 Dec 2006 18:01:23 -0500)
Janek Kozicki <janek_listy@wp.pl> writes:
Oh I see the point "4. Don't be distracted by the doc/ subdirectory... Start with libs/index.html". This explains a bit, but better not to have to explain anything.
Yes it would be much better. Too bad; we have a misleading directory structure.
I see that this subset is a quickbook documentation. Maybe simply rename directory doc/ into qbk_doc/ or quickbook.doc/ or doc.qbk/ or something that will indicate that it's that new format? I think that with this name the directory structure will be less misleading. Consider this: boost_1_34_0/ .................The "boost root directory" index.htm .........A copy of www.boost.org starts here boost/ .........................All Boost Header files libs/ ..........Documentation, .cpps, etc., by library * index.html ........Library documentation starts here (1) algorithm/ any/ array/ ...more libraries... status/ .........................Boost-wide test suite tools/ ...........Utilities, e.g. bjam, quickbook, bcp more/ ..........................Policy documents, etc. doc.qbk/ ...............A subset of Boost library docs * '*' marks modified lines. I removed "Tests" because I felt that you wanted to keep below 80 columns, and because IMHO "Tests" is the least interesting for the target audience of this guide. This is only a suggestion. After reading this list third (or fourth) time I noticed the line (1). Was I blind before? I don't know, I wasn't seeing this earlier. Maybe just make the word "documentation" bold in (1) and disregard changes marked by '*'. I dunno.
Maybe this is out of the scope of your post, but this difficulty in browsing documentation always annoyed me, when the network was slow or down.
Understood. Please volunteer to help fix problems in this area; I really would appreciate it.
Yes I would, the problem I see is that after downloading from CVS, the quickbook docs have to be built (ie. they are not in place for offline browsing). The simplest solution is to add a short README file in this directory which will explain how to build the docs. I don't know how to build them :) If someone will tell me how to build qbk docs for offline browsing, I will gladly submit a patch with README file. -- Janek Kozicki |