Re: [boost] Getting started guide updates

Subject: Re: [boost] Getting started guide updates
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2011-03-20 08:49:21

> -----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, in particular:
> 
> - To make the "bootstrap + bjam" process the only documented one, since it
> turns out to be fairly painless on Unix
> - To clarify some common questions inline
> 
> The result can be previewed at
http://lvk.cs.msu.su/~ghost/unix-variants.pdf ,
> see section 5. I would appreciate if folks take a look and suggest whether
it can
> be improved further.

1  This looks better but it doesn't have an index.

However this PDF version is *much* better because one can search for
words/phrases.

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.

3  "boost root directory - called $BOOST_ROOT"

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

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

6  Amusing typo - "To save complication time,"  should be "compliation" ?
;-)

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

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?

> I plan to make a similar update for Windows, but it's somewhat trickier.

but even more important as MicroSofties tend to be less comfortable with
command line stuff ;-)

Thanks

Paul

---
Paul A. Bristow,
Prizet Farmhouse, Kendal LA8 8AB  UK
[phone]  07714330204
pbristow_at_[hidden]