Re: [boost] New getting started guide

From: Johan Nilsson (r.johan.nilsson_at_[hidden])
Date: 2006-11-22 03:22:15

David Abrahams wrote:
>> I've got a first draft of the new getting started guide ready
>> (enclosed).  Comments would be appreciated.
>>
>> I plan to factor it out into separate documents, e.g. one just for
>> *nix, one just for Visual Studio, etc., which should help make it
>> more coherent... but I need to do a small amount of tool writing
>> before I
>> can accomplish that without duplicating information.  The source file
>> is checked in at more/getting_started.rst

Some quick comments:

Usage of "boost_1_34_0" (everywhere):

- I don't know - is this something that should change in each Boost release 
in the getting started guide? I understand that something like this is 
perhaps easier to understand that e.g. "<boost root>" or $BOOST_ROOT, but 
it'll lead to some extra maintenance for you(?).

References:

- What about adding some explicit references to e.g. the Boost.Build, 
Boost.Jam manuals and perhaps also the Boost.Build wiki somewhere near the 
start of the document?

"*nix (....)" usage in headers:

- I'm not too fond of the usage of "*nix", especially not in headers - why 
not "Unix variants" or similar. Just my personal opinion, though.

The structure of a Boost distribution(2):

- "index.html ... a copy of www.boost.org"; sounds like it contains, well, a 
copy of the site (nagging, yes, I know).

Building a simple Boost program (3):

- "Nearly all Boost libraries are header-only" - ten that are not 
header-only are listed (excluding DateTime). Maybe "Most Boost libraries" 
would be more appropriate?
- Typo (3.2) - "From your computer's Start menu, select if you are a Visual 
Studio 2005 user, select ..." (select ... select).
- Typo(3.2) - the command prompt in the MS examples are "C:PROMPT>" instead 
of "C:\PROMPT>"

Build directory (4.4.3 onwards):

- Is the "--build-dir" option actually respected?
- In the root Jamfile.v2 (and in v1) it is called "--builddir"

Select a prefix directory (4.4.6):

- Maybe it's just me, but "prefix" doesn't feel like a common word for 
selecting the install directory. Why not have "destination" or "install" 
directory in the header, and explain that this is selected using the 
"--prefix" argument?
- What about --includedir and --libdir, should they also be included here, 
or just referenced?

Toolset tags (5.1.1, 5.3, and more ...):

- I believe that the generated toolset tag for e.g. msvc V.1 is actually 
"vc71" ...

Library paths (5.1.1, 5.2):

- Perhaps give the same information and hints for using /LIBPATH: (msvc) as 
for -L (gcc) when not auto-linking.

Staging (4.4.4-5):

- There's some duplication between the two paragrahs (stage target 
explanation)

/ Johan