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

From: David Abrahams (dave_at_[hidden])
Date: 2008-08-11 12:51:57

on Mon Aug 11 2008, Beman Dawes <bdawes-AT-acm.org> wrote:

> 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. 

Yeah, my fault. docutils.jam was hacked together for my standard usage
scenario (working from a development snapshot).  I'd say open a ticket
for that, but I'm hoping we'll retire docutils.jam soon ;-)

> 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.

I don't think you can do any better than making a named link in
release_variables.rst that gets updated for each release.

ReST is pretty limited in some ways and the GSG stretches its inherent
programmability just about to the limit.  I get the impression that
quickbook templates are more flexible and powerful.  I'd like to
collaborate with a quickbook expert on a conversion.

All that said, the link probably shouldn't go in index.rst, since that
file has little content that's likely to change and people are likely to
link to the windows/unix-specific files.

Based on that information, if you still want me to try to make the
change, please let me know.

>>> * 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.

We will probably start selling binary installers for platforms that
Boost isn't directly supporting, so it might not hurt to mention that.

>>> * 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.

Looks fine.  As a stylistic matter, it would probably be better to use
an anonymous hyperlink ("__"), rather than such a long name.  So that it
makes sense when you put the link in release_variables.rst, you can name
the link this way:

    The `Boost website version of this Getting Started guide`__ blah,
    blah...

    __ LatestGSG_

and then use

    .. _LatestGSG: http://www.boost.org/doc/libs/1_36_0/more/getting_started/index.html

in release_variables.rst

>>> [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.

Yeah, but I bet your instructions don't work for MacOS or AIX (which use
different symbols for the library path), or even on Linux if you're a
user who doesn't have write permission on /usr and has to use --prefix=
to install elsewhere (since you didn't mention LD_LIBRARY_PATH in your
instructions).  That's where at least some of the complication is going
to come from.

Honestly, I don't understand why we don't just expand the installed
defaults to include static libraries so the existing instructions work.
If you're worried about destabilizing the release because static
libraries don't build successfully somewhere, I have to ask you: would
it really be acceptable to release Boost like that in the first place?

I worked *extremely* hard to make sure that the instructions as they now
stand will *not* cause people to run into stupid issues that prevent
them from getting started with Boost or decide that Boost is hard to
use, and it's very frustrating to see the potential problems taken so
lightly.  I don't think adjusting the guide to use dynamic libraries is
something you can do at the last minute and not cause problems for our
users.

>>> 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 certain environments on certain platforms.  Er, one environment on
one platform.

>> 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.

No offense intended, but I'm not so sure.

>>> * 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.

I think if you want to have confidence about the result, you'll need to
be a lot more aggressive about looking for pitfalls than you have been
so far.

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