Boost logo

Boost :

From: Johan Nilsson (r.johan.nilsson_at_[hidden])
Date: 2006-11-23 03:29:04

David Abrahams wrote:
> "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


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

Do you refer to the hyperlinks under 4.4? I didn't consider hyperlinks being
explicit references, hence my wording.

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

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)

(not a patch, I know)

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


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

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

>> The structure of a Boost distribution(2):
>> - "index.html ... a copy of"; 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", or "a copy of" would at least be more accurate.

Actually (just tried this), renders a 404 error
( works).

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


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

Ok, just tested it and works fine. See next point though, which is the
reason why I was wondering.

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

Try to invoke bjam --help from the boost root and check the listed options.
The help is (at least partially AFAIK) extracted from the root Jamfile.v2.

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

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


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

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

[snip rest]

Regards / Johan

Boost list run by bdawes at, gregod at, cpdaniel at, john at