Re: [boost] [1.36.0] Getting Started changes (ticket #1744 plus other fixes)

From: Beman Dawes (bdawes_at_[hidden])
Date: 2008-08-11 09:46:12

David Abrahams wrote:
> on Sat Aug 09 2008, Beman Dawes <bdawes-AT-acm.org> wrote:
> 
>> Before we can ship 1.36.0, some "Getting Started" documentation
>> changes are needed. These changes are the only thing preventing 1.36
>> from shipping. Enough said.
> 
> I'm very glad to make the changes provided we can figure out what they
> are.  That is something I've been with concerned with for weeks.

I've finally gotten rst2html.py working on my machine; bjam was looking 
for it a directory different from where the docutils download puts it. I 
tested by generating the current trunk more/getting_started, and 
identical html files were produced. Thus it seems to be working OK.

Thus I can make minor updates without bother you.

I've committed changes to index.rst and unix-variants.rst, and will do 
windows.rst as soon as testing is complete.

I couldn't figure out how substitution works, so I hard-wired the 
version number on line 23 of index.rst. If you could fix that I would 
appreciate it.

>> * Section 1, Get Boost, both Windows and Unix Variants: need to begin
>> with a suggestion that users first check for the availability of
>> platform specific installers, linked to the correct URL.
>>
>> [Rationale: the platform specific installers are the preferred way for
>> users to install Boost if their platform is one of those supported.]
>>
>> Questions for Doug: Are the platform specific installers to be hosted
>> on SourceForge as part of the "boost" package? What is the initial set
>> of platform specific installers that will be provided for 1.36?
> 
> Waiting for someone to tell me what the URLs are.

I haven't heard from Doug, and in any case I am leery of putting in 
anything specific until the real files are available at the final location.

>> * Section 1, Get Boost, Windows: current text needs to be updated if
>> Boost Consulting 
> 
> ahem. Boostpro Computing :)

Oops! Sorry.

> 
>> is not going to be also providing installers.
>>
>> [Rationale: The current wording is very specific, thus needs careful
>> adjustment to match reality.]
> 
> We probably will continue to provide free installers, but they may be
> the same as the Boost ones.  In that case, it doesn't make much sense to
> point people at Boostpro in the Boost documentation.
> 
>> * New section, before the current section 1:  Suggest visiting
>> http://www.boost.org/doc/libs/1_35_0/more/getting_started/index.html
>> to see if there has been a "Getting Started" documentation update.
> 
> Good idea.  We should make the URL shorter though ;-)

See my draft wording in trunk/more/getting_started/index.html.

> 
>> [Rationale: that way we can push out better docs as soon as available,
>> instead of having to wait for the next release.]
>>
>> * Section 5.2.4, Invoke bjam, both Windows and Unix Variants: needs to
>> say what library variants (static/dynamic, debug/release,
>> multi-threaded/not) are build by default.
>>
>> [Rationale: (1) It is too late to change the default behavior for
>> 1.36.0. (2) The worst problem with the new defaults isn't the specific
>> choices, but that those choices aren't documented, 
> 
> I'm not so sure.  While they may have other benefits, the new defaults
> are going to make the getting started instructions more complicated.

For unix-variants, I added instructions for building all variants, in 
addition to the defaults. That did add a bit more wording, but not 
enough to be worrisome IMO.
> 
>> and (3) it needs to be crystal clear how to build the full set.]
> 
> Yeah, but that's not nearly enough.  We also need to make sure that the
> instructions for building the examples in the getting started guide are
> all correct, including all their command-line variations, for all
> platforms, and don't leave out "silly" details like the potential need
> to set LD_LIBRARY_PATH (or whatever other platform-specific environment
> variable may be required) now that we are no longer building static
> libraries by default.  Testing these instructions for all platforms is a
> large job, and I'm not in a position to do it by myself.

I've tested the two unix-variants build examples on Linux. I'm now 
starting to do similar tests on Windows. That's not as good as testing 
all combinations, but at least we know the given examples do in fact work.

> In case anyone's wondering why I didn't "simply" go ahead and update the
> GSG when I discovered that the default build choices had broken it,
> that's why.

Understood.

>> * Section 5.2.4, Invoke bjam, both Windows and Unix Variants: after
>> the current contents, needs to give the exact command line for
>> building all library variants.
>>
>> [Rationale: resolves (3) in prior item.]
>>
>> Since Dave is on vacation, I'm not sure he will be able to make these
>> changes. If he can't make them, I'll give it a try.
>  
> I'm somewhat available, but like I said, the changes to the defaults
> have made things a lot more problematic than they used to be, so we'll
> need to get lots of people to put attention on this.

Yes. I hope others will read "Getting Started", and actually try the 
instructions on their systems ASAP.

--Beman