Re: [boost] Attention Boosters - a subset of documentation files

From: Janek Kozicki (janek_listy_at_[hidden])
Date: 2006-12-12 06:44:19

David Abrahams said:     (by the date of Mon, 11 Dec 2006 18:01:23 -0500)

> Janek Kozicki <janek_listy_at_[hidden]> 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                                                         |