David Abrahams wrote:
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.
I must've missed it - never mind - it doesn't make up an entire headline anymore.
2. Get Boost ============
1.2.3... 4. checkout a branch from the CVS?
Why should I give that as an option?
There are two possible reasons that might or might not matter to you: - critical bug fixes can be deployed easily - if users fix bugs they can easily create a patch and send us
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?
Well, I wouldn't bet on people won't, at least... People unfamiliar with a command might not know what "adding to the command line" exactly means.
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.
Still, a concrete example that is "wrong" for most people is often better than hard-to-get abstract wisdom that applies everywhere...
"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?
"Ah, interesting - I'm developing for Windows - so I'll use backslashes for consistency with my OS' file system... Didn't know that would work, before..."
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.
Why not? There is only one right and portable way
I don't want to leave it out because people will be confused.
and it isn't clear which one it is. It might add more confusion than it resolves, elsewhere.
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?
It depends... s/Open the Finder/Open a finder window/ would be more accurate.
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.
Isn't there some external document that could be linked to for the "cd/ls tutorial"?
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.
I wouldn't call myself a CSS expert. Anyway, as four eyes see more than two, I can have a look at the details this evening (GMT+1) if no real CSS expert stands up until then. It might have to do with different defaults of different browsers that "shine through" if not overridden explicitly.
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 :(
Hmmm... Maybe setting the 'overflow' attribute will work.
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++.
In case you can pass through verbatim HTML, e.g. http://spirit.sourceforge.net/repository/applications/cpp_to_html.zip could be used to get the job done. Regards, Tobias