Re: [jamboost] Re: Some V2 manual comments

From: Vladimir Prus (ghost_at_[hidden])
Date: 2004-10-26 06:36:34

Hi Jurko,

> http://boost.org/boost-build2/doc/html/bbv2.extending.tools.html
> - 'method can be overrided when' should read 'method can
> be overridden when'.
> - 'analysing' should be spelled 'analyzing'

This depends on relative distance to U.K and U.S ;-) My spellchecker says 
"analyse" is correct british spelling.

> http://boost.org/boost-build2/doc/html/bbv2.extending.features.html
> - 'and using a more specific feature which is translated to a
> specific options' should perhaps read 'and using a more
> specific feature which is directly translated to specific
> options'
> - but on the other hand this whole paragraph seems unclear
> to me so perhaps a more general rewrite would be
> needed.
> - Strange sentence 'A generic feature is almost always should
> be defined' should be corrected.

What about this rewrite:

<para>
There are two ways to control a tool using features. The
first is to declare a "generic" feature, which value is passed to the
tool without modification. For example, the value of the
<code>cxxflags</code> feature ends up in the compiler's command
line. Such a generic feature allows the user to get full control and
should be always provided when you write a tool.
</para>

<para>The second approach is to declare a more specific feature, 
which is directly translated to specific options. For example, 
the <code>&lt;optimization&gt;speed</code> property might add
<literal>-O3</literal> to the compiler's command line. Specific
features are preferred over generic for a couple of reasons:

> - 'Let's see' should read 'Lets see'

Isn't "Let's" an abbreviation of "Let us"?

> - I believe a hyper-link from 'feature attributes' in 'You should
> have to decide on the set of feature attributes' to the
> 'Feature attributes' paragraf in
> http://boost.org/boost-build2/doc/html/bbv2.reference.html
> would be useful.

Done.

> http://boost.org/boost-build2/doc/html/ch07s02.html
> - I do not understand the example here. What is the variable
> 'path'? It is not used anywhere. How does it relate to the
> text describing the example.

The example should read:

import modules ;
local SOME_LIBRARY_PATH = [ modules.peek : SOME_LIBRARY_PATH ] ;
exe a : a.cpp : <include>$(SOME_LIBRARY_PATH) ;

I've corrected it.

The changes I did not mention specificically are all applied. I did not commit 
them yet, because you've caught me in the middle of restructuring the 
"references" section, which I'll finish tomorrow.

> Okie... that's it for my first pass through the manual...
> will most likely rescan it though when I try to actually
> use Boost.Build V2 on my project.

Thanks again! 

- Volodya