Re: [boost] New getting started guide

From: David Abrahams (dave_at_[hidden])
Date: 2006-11-22 23:22:52

"Johan Nilsson" <r.johan.nilsson_at_[hidden]> writes:

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

Don't worry, there's a single substitution reference in the source for
that file.  Not much to maintain.

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

There already are explicit references to everything but the wiki.  If
you want to suggest a patch, I'll gladly consider specific changes.
However, I don't want to get the user involved with any of that stuff
near the beginning of the document because most likely she doesn't
need it in order to get started.

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

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.

Just going with someone else's suggestion who was unhappy with
specific mentions of unix.  I'm open to whatever people decide is most
comfortable.

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

Okay, that could be more accurate, but do you have a specific
suggestion?

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

Why?

> - Typo (3.2) - "From your computer's Start menu, select if you are a Visual 
> Studio 2005 user, select ..." (select ... select).

Thanks.

> - Typo(3.2) - the command prompt in the MS examples are "C:PROMPT>" instead 
> of "C:\PROMPT>"

Thanks.

> Build directory (4.4.3 onwards):
>
> - Is the "--build-dir" option actually respected?

AFAIK.  Why?

> - In the root Jamfile.v2 (and in v1) it is called "--builddir"

What does Jamfile.v2 have to do with it?  It's provided by the build
system, not the Jamfiles.

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

Maybe it's just you.  That's the standard *nix terminology.

> Why not have "destination" or "install" 
> directory in the header, and explain that this is selected using the 
> "--prefix" argument?

I'm not sure it could be as clear.

> - What about --includedir and --libdir, should they also be included here, 
> or just referenced?

Neither.  I don't want to tell people how to customize everything,
just how to get over the hump of getting started.  They'll get those
options from the configure script when they do ./configure --help.

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

msvc V.1 ?

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

Probably a good idea.

> Staging (4.4.4-5):
>
> - There's some duplication between the two paragrahs (stage target 
> explanation)

Thanks!

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