V2 documentation feedback from a newbie

From: Samuel Krempp (krempp_at_[hidden])
Date: 2004-01-22 12:43:16

I'm finally taking some time to use Boost.Buildv2 for some of my projects. 
I do not have much v1 experience (except for making boost test Jamfiles),
but I thought it could be a good idea to go directly for v2 (is it ?) and
this way I'd try to note every time I feel like I'm lost and can't find
anything in the docu to save me, hopefully leading to improving the doc, as
stated earlier here (<200310201118.41432.ghost_at_[hidden]>) .

I think the detailed_reference should be in a separate file, it's a bit
confusing to have different styles and notations in one file and not
knowing which section you are in (for instance when text-searching
something)

Also, it wasnt clear to me at first what other directories a bjam invocation
in my directory would depend on.
The fact a project root's boost-build.jam has to point to a certain
boost_build_root directory (namely $boost_root/tools/build/v2) should have
been a sufficient hint, but not at the time when I worked my way through my
first contact with Boost.Build, and actually it didnt break the vague
mystery surrounding all Boost.Build until a few hours later. Maybe I'm
dumb :)
I feel the docu should state the obvious here, and just plainly explain in
the very beginning that when invoked bjam will use the directory hierarchy
rooted at boost_build_root and parse the jam files there as a first step.
It would be a good time to state that the jam files in this directory
hierarchy are well commented and are the ultimate place to go to when you
don't understand something with Boost.Build.
-- 
Samuel