Re: [BBv2 doc editorial] tutorial/hierarchy

From: David Abrahams (dave_at_[hidden])
Date: 2005-09-22 10:43:03

Vladimir Prus <ghost_at_[hidden]> writes:

> On Wednesday 21 September 2005 19:37, David Abrahams wrote:
>> Vladimir Prus <ghost_at_[hidden]> writes:
>> > On Tuesday 20 September 2005 21:07, David Abrahams wrote:
>> >> > the project root is top/. Because there is no Jamfile in top/util/,
>> >> > the projects in top/app/ and top/util/foo/ are immediate children of
>> >> > the root project.
>> >>
>> >> It is not at all clear what the significance of the latter statement
>> >> is. I find it confusing to see it here with no explanation or way of
>> >> relating it to what I'm going to do with BB.
>> >
>> > I've just removed the "Because" clause. It did not add much value.
>>
>> That doesn't help. What does it mean to me that these things are
>> immediate children? Nothing! Without some more information (and
>> perhaps even with it), that has no semantic value to the reader.
>
> What I'm trying to say is that those "immediate children" inherit properties 
> from their parent. 

Really? That was totally opaque to me, and I know about the concept of
property inheritance! How will the poor reader feel?

Furthermore, at this point in the document, you haven't even
introduced the idea of properties associated with projects yet. So
it's merely confusing.

> Maybe I can strike the last sentence and say that 
> "app/Jamfile" and "util/foo/Jamfile" inherit properties from top/Jamroot?

I think you can just strike that sentence and leave it at that. In
fact, the whole discussion of project requirements and their
inheritance is misplaced on this page.

>> >> > Building a project does not automatically cause its sub-projects to
>> >> > be built unless the parent project's Jamfile explicitly requests it.
>> >> > In our example, top/Jamroot might contain:
>> >> >
>> >> > build-project app ;
>> >>
>> >> ^^^
>> >> Is this a directory or a subproject name?
>>
>> I don't actually know the answer to this question, you know.
>
> It's a directory name.

In that case the rule should be called "build-directory."
Seriously.

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