Re: [boost] New getting started guide

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

[snip]

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

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

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

Actually (just tried this), www.boost.org/index.html renders a 404 error 
(www.boost.org/index.htm 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.

[snip]

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

or

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