Boost logo

Boost :

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


Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk