"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
Some quick comments:
Usage of "boost_1_34_0" (everywhere):
- I don't know - is this something that should change in each Boost release in the getting started guide? I understand that something like this is perhaps easier to understand that e.g. "<boost root>" or $BOOST_ROOT, but it'll lead to some extra maintenance for you(?).
Don't worry, there's a single substitution reference in the source for that file. Not much to maintain.
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. 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.
"*nix (....)" usage in headers:
Headers?
- 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.
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?
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?
- Typo (3.2) - "From your computer's Start menu, select if you are a Visual Studio 2005 user, select ..." (select ... select).
Thanks.
- Typo(3.2) - the command prompt in the MS examples are "C:PROMPT>" instead of "C:\PROMPT>"
Thanks.
Build directory (4.4.3 onwards):
- Is the "--build-dir" option actually respected?
AFAIK. Why?
- 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.
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.
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. They'll get those options from the configure script when they do ./configure --help.
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 ?
Library paths (5.1.1, 5.2):
- Perhaps give the same information and hints for using /LIBPATH: (msvc) as for -L (gcc) when not auto-linking.
Probably a good idea.
Staging (4.4.4-5):
- There's some duplication between the two paragrahs (stage target explanation)
Thanks! -- Dave Abrahams Boost Consulting www.boost-consulting.com