Re: [boost] Attention Boosters

From: David Abrahams (dave_at_[hidden])
Date: 2006-12-11 19:01:19

Tobias Schwinger <tschwinger_at_[hidden]> 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