"Johan Nilsson" <r.johan.nilsson@gmail.com> 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