Re: [boost] Attention Boosters

From: Tobias Schwinger (tschwinger_at_[hidden])
Date: 2006-12-12 04:28:07

David Abrahams wrote:
> 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.
> 

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