Re: [boost] Getting started guide updates

Subject: Re: [boost] Getting started guide updates
From: Dave Abrahams (dave_at_[hidden])
Date: 2011-03-21 13:55:30

On Sun, Mar 20, 2011 at 5:49 AM, Paul A. Bristow
<pbristow_at_[hidden]> wrote:
>
>
>> -----Original Message-----
>> From: boost-bounces_at_[hidden] [mailto:boost-bounces_at_[hidden]]
>> On Behalf Of Vladimir Prus
>> Sent: Sunday, March 20, 2011 10:49 AM
>> To: boost_at_[hidden]
>> Subject: [boost] Getting started guide updates
>>
>> I've tried to update the getting started guide (for Unix so far) to better
> explain
>> building,

If you're doing this the "right" way, by editing the ReST source, most
of the changes will be in common files and much of the Windows
instructions will update appropriately.

> 2  Yet more examples would be even more helpful.
>
> No everyone will remember/RTFM to realise that italics mean 'your choice
> here', so be explicit?
>
> For example, unless you are going to automatically update the version number
> , it would be clearer to write
>
> "
> 1  download (probably latest) Boost version package,
> boost_1_version_1.tar.bz2  ('version' in italics of course)
>
>  for example, boost_1_46_1.tar.bz2
> "
>
> or
>
> #include <boost/whatever.hpp>
>
> for example: #include <boost/lambda/lambda.hpp>
>
> and many others too.

+1.  These would be useful changes.

> 3  "boost root directory - called $BOOST_ROOT"

I don't understand this comment.

> 4 A *much* bigger collection of examples of building command lines would be
> even better.

Yes, with the caveat that this should remain a *Getting Started*
guide.  Information for less-common usage must not obscure the
information that the newbie needs.

> 5  Would a collection of command files .sh (or .bat for MS)  be even better?

I don't understand this comment.

> 7  Queries should a widespread confusion about which items (options) need --
> and which (properties) don't.

Nor this one.

> A table of both of these, or a link to them (in Boost.Build documentation)
> would reduce this confusion greatly.
>
> But there is no substitute for *examples* - people hate to RTFM!
>
> 8  Sending a log file should be 'standard' and shown in most of the
> examples?

Sending it where?

-- 
Dave Abrahams
BoostPro Computing
http://www.boostpro.com