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