Tobias Schwinger <tschwinger@neoscientists.org> writes:
David Abrahams wrote:
You can review the guide at http://www.boost-consulting.com/boost/more/getting_started.html.
The document suddenly changed while I was reviewing it ;-O. Some remaining comments:
1. Introduction ===============
Why "*nix?" and not "Shell", "Shell environment", "UNIX-style shell environment" or "others?"
Any number of reasons, some of which I addressed in messages to this list earlier today.
2. Get Boost ============
1.2.3... 4. checkout a branch from the CVS?
Why should I give that as an option? I could also add "buy a DVD from Boost Consulting" if I'm going to add that. The point is not to describe every way you might acquire Boost, but to point people at the two easiest supported ways and describe the third way that many people are tempted to use but that might not be easy for us to support.
3. The structure of a Boost Distribution ========================================
I'm not sure it's a good idea to put a single command line option in one line
-I/path/to/boost_1_34_0
maybe an exemplary compiler invocation works better ("I enter -I... and nothing happens").
Do you really think people will copy that line into their shell without even reading the sentence that surrounds it? If I give an example invocation that will be wrong for some people too: I type "c++ -Ic:\boost" and it tells me: "c++: command not found." I'd rather not be specific if it makes me wrong.
"Even Windows users can use forward slashes in #include directives; your compiler doesn't care".
The recommendation to use forward slashes should be either stronger or left out.
Why? It's not a recommendation. It's a note designed to de-confuse windows users who use the sample code in the tutorial. I don't mean to evangelize the use of forward slashes, so I don't want to strengthen it. I don't want to leave it out because people will be confused.
Appendix ========
How about "Open the Finder, select Applications, open the Utilities folder and double click Terminal" for the MacOS X case (guessing that there might be MacOS developers without a UNIX background)?
Don't you have to select "new window" from the finder menu before you can select Applications? The other problem here is that, to do these people justice I have to explain everything I tell the Windows people, e.g. about the current directory, and then that part becomes a Unix-universal section on using the shell. I'm thinking that maybe MacOS programmers who don't know how to use a shell are not a big enough audience to warrant lengthening the tutorial document.
Layout notes (viewed with Firefox): ===================================
The big font for the filesystem structure seems one font size too many for my eye. It looks a bit better for the code blocks (probably because the text isn't bold), but I still believe using a single font size will look best.
Am I using multiple font sizes? I'm not a CSS expert and would be happy to have help with this.
With some window width "C:\Progam Files\boost\boost_1_34_0" floats into the "Header Organization" column
I noticed.
('pre' won't break -
That's not the problem; it should break before the "C:"
and preformatting isn't really needed, so 'tt' or an equivalent style should be enough).
Oh, heh, I'm not sure I can control that so easily. It looks like docutils puts a <pre>...</pre> around all "inline literals" (text formatted with <tt>...</tt>). Maybe I'll ask about that on the docutils mailing list, but maybe not: even without <pre> I can make it collide :(
The code could use some syntax highlighting for the final version (which you might have planned anyway).
Nope, I hadn't. Docutils doesn't syntax-highlight C++. -- Dave Abrahams Boost Consulting www.boost-consulting.com