Re: [jamboost] V2 documentation feedback from a newbie

From: Vladimir Prus (ghost_at_[hidden])
Date: 2004-01-23 06:23:51

Hi Samuel,

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

I think so. Can't promise you won't hit a bug, but chances are high it will be 
fixed quickly.

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

It will be in a separate file. In fact, Zbynek Winkler has sent me off-list a 
split documentation he made, so it will be in separate file pretty soon.

> 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 :)

Why did you wonder what directories bjam invocation depends on? I'm just 
trying to figure out what exactly should be put to docs.

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

Ok.. I'll see where I can put this statements.

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

Cool! I'll sure add this too ;-)

Thanks,
Volodya