Re: [Boost-build] toolset requirement

Subject: Re: [Boost-build] toolset requirement
From: Deane Yang (deane_at_[hidden])
Date: 2008-12-07 08:41:07

Vladimir Prus wrote:
> On Sunday 07 December 2008 07:08:02 Deane Yang wrote:
>> I love Boost Build and refuse to use anything else these days, but there 
>> are a lot of things that are just too well hidden or subtle and that 
>> burn up a lot of my time trying to figure out. Somehow, the messages 
>> generated by a regular run of bjam are not very useful (almost all the 
>> messages refer to code inside Boost Build itself and at most one or two 
>> lines mention my Jamfiles). I hope that some day y'all figure out how to 
>> improve that (and the documentation, which seems very badly organized to 
>> me. I am unable to find anything in it, including things I have found 
>> before. One specific thing I don't like is that some things are 
>> presented in the tutorial and then never again. 
> 
> If you list those things, I'll work on describing them in the main part of
> docs. Also note that current docs actually mention --debug-configuration
> under:
> 
> 	http://www.boost.org/boost-build2/doc/html/bbv2/advanced/configuration.html
> 
> and
> 
> 	http://www.boost.org/boost-build2/doc/html/bbv2/advanced/invocation.html
> 
> so I don't know what more exposure for this option I can provide. Maybe we should
> have a separate 'troubleshooting' section?
> 

How about a troubleshooting wiki, so you and Steve can add an entry 
every time you two help someone?

I know I should help, but I simply don't have any time at all right now. 
I would note that someone should devote some effort to simply 
reorganizing the docs better and creating a better table of contents or 
index. Whenever I need to look up something, I go to:

http://www.boost.org/doc/tools/build/doc/html/index.html

and I realize that I have no idea whether the question I want answered 
would be addressed in the "Tutorial", "Common Tasks" (should I know 
which tasks are common or not?), or "Reference", or elsewhere. So I 
always have to literally scan the entire document, and, because the 
topics always seem to me to be randomly distributed inside these 
chapters, I usually overlook what I am looking for, if it is there at all.

For example, one thing I figure *must* be there, but I've never found it 
is how to do certain types of conditional properties:
1) How to do "not", i.e, if the OS is *not* Windows, then set a property.
2) How to do "or". I just use more than one line right now. Is that the 
only way?
I only see discussion about conditional properties in the Tutorial (none 
of the other sections have any header or subheader that looks remotely 
like conditional properties), which is all too brief.

Here's another thing that is itself not particularly important, but for 
some reason I find annoying. The URL's you provide above seem to 
indicate that they are in the "Advanced" section of the manual. So I 
look at the table of contents, and there is no "Advanced" section. After 
scanning for a while (sorry, I'm getting old and senile), I finally 
notice that these are listed as being in "Overview". I *always* overlook 
the chapter "Overview", because in most docs, the only time you read the 
Overview is the first time you read them. If actual usage details are in 
the Overview, they are merely part of an introduction. You *never* want 
to document things *only* in the Overview.