Re: [boost] New getting started guide

From: David Abrahams (dave_at_[hidden])
Date: 2006-12-11 11:58:19

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

> Ok. How about a "References", or "Where to go for further help" section at 
> the end of the document:
>
> Boost.Build reference manual: (hyperlink)
> Boost.Jam reference manual: (hyperlink)
> Boost.Build Wiki: (hyperlink)
> Boost User's mailing list: (hyperlink)

Done.

>>> "*nix (....)" usage in headers:
>>
>> Headers?
>
> Pardon my English. I guess I mean "headings" or perhaps "section headings"?
>
>>
>>> - I'm not too fond of the usage of "*nix", especially not in headers
>
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~headings.
>
>>> - 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.
>
> Unix variants?
> Unix-type systems?
> Unix-compatible systems?
>
> The first is my own preference, at least until I've seen something better. 
> Perhaps adding an explanation near the beginning of the document would be a 
> good idea:

The problem with "Unix variants" is that it makes all kinds of things
incredibly awkward to write and read.  For example, how do you say 

      *nix users
      *nix binaries

??

      users of unix variants
      binaries for unix variants

??

> In this document, the term "Unix variants" is used as a collective reference 
> to different *nix platforms, including ...

I added just such an explanation of *nix.

>>> 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?
>
> Nothing really good, but either "a copy from www.boost.org", or "a copy of 
> www.boost.org/index.html" would at least be more accurate.

"A copy of www.boost.org starts here."

> Actually (just tried this), www.boost.org/index.html renders a 404 error 
> (www.boost.org/index.htm works).

Fixed.

>>
>>> 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?
>
> Because, at least as a non-native English speaker, I find that a ratio of 
> some 55ish header-only out of some 66ish in total sounds more like "most of" 
> than "nearly all" (the number 66 came from the number of directories under 
> <boost root>/libs). Whatever - I don't feel too strongly about this.
>

Fixed.

>>> 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.
>
> Perhaps, but Boost isn't meant for *nix users only.

That section was never supposed to be in the flow of the reading for
non-*nix users.

>>> 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.
>
> I understand that.
>
>>  They'll get those
>> options from the configure script when they do ./configure --help.
>
> So, under Windows, I'll do ./configure --help? (sorry, but you get the 
> point). 

Uh, no.  The instructions for Windows users do not suggest the use of
configure.

> Why not add a reference at the end of the section, e.g.:
>
> For a description of all available installation options, please see <link 
> provided here>.

Sure, great.  What will I link to?

> or
>
> For a description of all available installation options, invoke 
> "bjam --help" from <insert boost root directory here>.

That's more useful; I'll add that.

>>
>>> 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 ?
>
> Typo, should be "msvc 7.1" (of course).

OK, thanks.

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