Add caveat about appending the version number of windows compilers for auto-link support.

[SVN r37640]

6 files changed, 42 insertions, 26 deletions

diff --git a/more/getting_started/detail/build-from-source-head.rst b/more/getting_started/detail/build-from-source-head.rst
index b2dfd5cad1..57cdf9f383 100644
--- a/more/getting_started/detail/build-from-source-head.rst
+++ b/more/getting_started/detail/build-from-source-head.rst
@@ -26,7 +26,7 @@ Boost provides |precompiled-bjam|_ for a variety of platforms.
 Alternatively, you can build ``bjam`` yourself using `these
 instructions`__.
 
-__ ../../doc/html/jam/building.html
+__ `building bjam`_
 
 
 .. _toolset:
@@ -38,6 +38,12 @@ Identify Your Toolset
 First, find the toolset corresponding to your compiler in the
 following table.  
 
+.. Note:: If you previously chose a toolset for the purposes of
+  `building bjam`_, you should assume it won't work and instead
+  choose newly from the table below.
+
+.. _building bjam: ../../doc/html/jam/building.html
+
 +-----------+--------------------+-----------------------------+
 |Toolset    |Vendor              |Notes                        |
 |Name       |                    |                             |
@@ -89,13 +95,10 @@ following table.
 __ Boost.Build_
 
 If you have multiple versions of a particular compiler installed,
-you can append the version number to the toolset name, preceded by a
-hyphen, e.g. ``msvc-7.1`` or ``gcc-3.4``.
+you can append the version number to the toolset name, preceded by
+a hyphen, e.g. ``intel-9.0`` or
+``borland-5.4.3``. |windows-version-name-caveat|
 
-.. Note:: if you built ``bjam`` yourself, you may
-  have selected a toolset name for that purpose, but that does not
-  affect this step in any way; you still need to select a Boost.Build
-  toolset from the table.
 
 .. _build directory:
 .. _build-directory:
diff --git a/more/getting_started/detail/common-unix.rst b/more/getting_started/detail/common-unix.rst
index 77fa0420bc..c1cdf491c5 100644
--- a/more/getting_started/detail/common-unix.rst
+++ b/more/getting_started/detail/common-unix.rst
@@ -16,6 +16,9 @@
 
 .. |include-paths| replace:: `` ``
 
+.. |windows-version-name-caveat| replace:: `` ``
+
 .. |command-line tool| replace:: command-line tool
 
+
 .. include:: common.rst
diff --git a/more/getting_started/detail/common-windows.rst b/more/getting_started/detail/common-windows.rst
index f7dc50e048..5e70f36e32 100644
--- a/more/getting_started/detail/common-windows.rst
+++ b/more/getting_started/detail/common-windows.rst
@@ -24,6 +24,11 @@
     **lib**\ |//| .....................\ *precompiled library binaries*
 
 
+.. |windows-version-name-caveat| replace:: Unless you are using the
+   msvc or gcc toolsets (which have special version detection code)
+   **you must append a version number even if you only have one
+   version installed**, or `auto-linking`_ will fail.
+
 .. |command-line tool| replace:: `command-line tool`_
 
 .. include:: common.rst
diff --git a/more/getting_started/unix-variants.html b/more/getting_started/unix-variants.html
index 3e8f61bc69..27cde2b56b 100644
--- a/more/getting_started/unix-variants.html
+++ b/more/getting_started/unix-variants.html
@@ -310,6 +310,12 @@ instructions</a>.</p>
 <span id="toolset-name"></span><span id="toolset"></span><h3><a class="toc-backref" href="#id27">5.2.2&nbsp;&nbsp;&nbsp;Identify Your Toolset</a></h3>
 <p>First, find the toolset corresponding to your compiler in the
 following table.</p>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">If you previously chose a toolset for the purposes of
+<a class="reference external" href="../../doc/html/jam/building.html">building bjam</a>, you should assume it won't work and instead
+choose newly from the table below.</p>
+</div>
 <table border="1" class="docutils">
 <colgroup>
 <col width="18%" />
@@ -398,15 +404,9 @@ Boost.</td>
 </tbody>
 </table>
 <p>If you have multiple versions of a particular compiler installed,
-you can append the version number to the toolset name, preceded by a
-hyphen, e.g. <tt class="docutils literal"><span class="pre">msvc-7.1</span></tt> or <tt class="docutils literal"><span class="pre">gcc-3.4</span></tt>.</p>
-<div class="note">
-<p class="first admonition-title">Note</p>
-<p class="last">if you built <tt class="docutils literal"><span class="pre">bjam</span></tt> yourself, you may
-have selected a toolset name for that purpose, but that does not
-affect this step in any way; you still need to select a Boost.Build
-toolset from the table.</p>
-</div>
+you can append the version number to the toolset name, preceded by
+a hyphen, e.g. <tt class="docutils literal"><span class="pre">intel-9.0</span></tt> or
+<tt class="docutils literal"><span class="pre">borland-5.4.3</span></tt>. <tt class="docutils literal"> </tt></p>
 </div>
 <div class="section" id="select-a-build-directory">
 <span id="id10"></span><span id="build-directory"></span><h3><a class="toc-backref" href="#id28">5.2.3&nbsp;&nbsp;&nbsp;Select a Build Directory</a></h3>
diff --git a/more/getting_started/windows.html b/more/getting_started/windows.html
index 9d2a8d56fc..6ce5565f79 100644
--- a/more/getting_started/windows.html
+++ b/more/getting_started/windows.html
@@ -373,6 +373,12 @@ instructions</a>.</p>
 <span id="toolset-name"></span><span id="toolset"></span><h3><a class="toc-backref" href="#id33">5.2.2&nbsp;&nbsp;&nbsp;Identify Your Toolset</a></h3>
 <p>First, find the toolset corresponding to your compiler in the
 following table.</p>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">If you previously chose a toolset for the purposes of
+<a class="reference external" href="../../doc/html/jam/building.html">building bjam</a>, you should assume it won't work and instead
+choose newly from the table below.</p>
+</div>
 <table border="1" class="docutils">
 <colgroup>
 <col width="18%" />
@@ -461,15 +467,12 @@ Boost.</td>
 </tbody>
 </table>
 <p>If you have multiple versions of a particular compiler installed,
-you can append the version number to the toolset name, preceded by a
-hyphen, e.g. <tt class="docutils literal"><span class="pre">msvc-7.1</span></tt> or <tt class="docutils literal"><span class="pre">gcc-3.4</span></tt>.</p>
-<div class="note">
-<p class="first admonition-title">Note</p>
-<p class="last">if you built <tt class="docutils literal"><span class="pre">bjam</span></tt> yourself, you may
-have selected a toolset name for that purpose, but that does not
-affect this step in any way; you still need to select a Boost.Build
-toolset from the table.</p>
-</div>
+you can append the version number to the toolset name, preceded by
+a hyphen, e.g. <tt class="docutils literal"><span class="pre">intel-9.0</span></tt> or
+<tt class="docutils literal"><span class="pre">borland-5.4.3</span></tt>. Unless you are using the
+msvc or gcc toolsets (which have special version detection code)
+<strong>you must append a version number even if you only have one
+version installed</strong>, or <a class="reference internal" href="#auto-linking">auto-linking</a> will fail.</p>
 </div>
 <div class="section" id="select-a-build-directory">
 <span id="id12"></span><span id="build-directory"></span><h3><a class="toc-backref" href="#id34">5.2.3&nbsp;&nbsp;&nbsp;Select a Build Directory</a></h3>
@@ -555,7 +558,7 @@ in the <a class="reference external" href="../../tools/build/index.html">Boost.B
 the <tt class="docutils literal"><span class="pre">user-config.jam</span></tt> file doesn't work for you, please address
 questions about configuring Boost for your compiler to the
 <a class="reference external" href="../../more/mailing_lists.htm#jamboost">Boost.Build mailing list</a>.</p>
-<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
+<span class="target" id="auto-linking"></span><!-- Copyright David Abrahams 2006. Distributed under the Boost -->
 <!-- Software License, Version 1.0. (See accompanying -->
 <!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
 </div>
diff --git a/more/getting_started/windows.rst b/more/getting_started/windows.rst
index ac27721250..d20569e0c9 100644
--- a/more/getting_started/windows.rst
+++ b/more/getting_started/windows.rst
@@ -206,6 +206,8 @@ For example, your session might look like this: [#continuation]_
 
 .. include:: detail/build-from-source-tail.rst
 
+.. _auto-linking:
+
 .. include:: detail/link-head.rst
 
 .. Admonition:: Auto-Linking