Boost logo

Boost-Build :

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.


Boost-Build list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk