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

From: David Abrahams (dave_at_[hidden])
Date: 2006-12-12 17:40:03

Janek Kozicki <janek_listy_at_[hidden]> writes:

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

No, it's BoostBook.

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

Renaming directories in CVS is not simple.  That will have to wait
until we transition to SVN.  Anyway, again, this is outside the
scope of what I'm trying to do with this document.

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

Thanks for the suggestions.

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