Re: [BBv2 docs editorial] Installation

From: David Abrahams (dave_at_[hidden])
Date: 2005-09-21 10:59:24

Reece Dunn <msclrhd_at_[hidden]> writes:

>
>>>>4. You should now be able to go to the example/hello/ directory and
>>>> run bjam there. A simple application will be built. You can also
>>>> play with other projects in the example/ directory.
>>>>
>>>>If you are using Boost's CVS state, be sure to rebuild bjam even if
>>>>you have a previous version.
>
> Replace this line with "If you have taken a copy of Boost from the CVS 
> source control repository, it is necessary to rebuild bjam."

I prefer using the terms "a copy of the Boost source under active
development" and "a Boost release"

>>>>The CVS version of Boost.Build requires the CVS version of Boost.Jam.
>
> Should this be more generic like "Boost.Build requires an equal or 
> higher version of Boost.Jam in order to run."

I don't know if we want material like that in the introductory stuff.
Maybe in the troubleshooting section.

>>>Add
>>> We recommend this approach: once you've set up a boost-build.jam
>>> file in a parent directory of the one in which you do most of
>>> your development, it should almost never be necessary to think
>>> about it again, and you won't be cluttering your environment
>>> with settings specific to a single tool.
>> 
>> If a user creates c:\boost_build, puts bjam.exe there and adds 
>> c:\boost_build to the path, it will be "cluttering your environment
>> with settings specific to a single tool" too. 

No, "the environment" does not include every bit of semi-permanent
state on your computer: it's a collection of shell variable settings.
However, I wouldn't mind adding the word "shell" before "environment"
or the word "variable" before "settings."

>> So we should discourage such policy and recommend to use a common
>> folder like \dev\bin for bjam and other tools like doxygen etc. IMO
>> it's a good practice.

For some reason I feel like this is a little bit paternalistic, but I
think I'll just stop resisting because you're probably right. Then we
can give people the exact command-lines to add that directory to the
PATH, or tell them how to add it to their computer's properties. The
real problem is Unix because there are so many shells with their own
ways of establishing these settings. Oh, and .shrc, .login, .profile,
etc. Don't get me started; I could never really figure that stuff out
myself :(

>>>>distribution, so it is itself a valid Boost.Build root directory. It
>>>>also contains the tools/build/jam_src subdirectory of a full Boost
>>>>distribution, so you can rebuild Boost.Jam from source.
>> 
>> The last sentense sounds like you are unable to rebuild Boost.Jam if you 
>> have downloaded complete Boost tree.
>
> How about the last line being: "If you have the full Boost distribution, 
> the tools/build/jam_src subdirectory allows you to build the Boost.Jam 
> executable.".

It doesn't allow you to do anything; it "contains a copy of the
Boost.Jam sources."

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