diff --git a/doc/Jamfile b/doc/Jamfile
index 9b7c8841..f6ca225d 100644
--- a/doc/Jamfile
+++ b/doc/Jamfile
@@ -19,5 +19,7 @@ for local b in $(bases)
   ;
 }
 
+exe tst : tst.cpp ;
+
 alias htmls : $(bases) ;
 stage . : $(bases) ;
diff --git a/doc/building.html b/doc/building.html
index 40cc2bea..80978640 100644
--- a/doc/building.html
+++ b/doc/building.html
@@ -9,53 +9,55 @@
 </head>
 <body>
 <div class="document" id="logo-boost-python-build-and-test-howto">
-<h1 class="title"><a class="reference external" href="../index.htm"><img alt="Boost C++ Libraries:" class="boost-logo" src="../../../boost.png" /></a> Boost.Python Build and Test HOWTO</h1>
+<h1 class="title"><a class="reference" href="../index.htm"><img alt="Boost C++ Libraries:" class="boost-logo" src="../../../boost.png" /></a> Boost.Python Build and Test HOWTO</h1>
 
 <!-- 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 class="contents sidebar small topic" id="contents">
-<p class="topic-title first">Contents</p>
+<div class="contents sidebar small topic">
+<p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
 <ul class="auto-toc simple">
-<li><a class="reference internal" href="#requirements" id="id21">1&nbsp;&nbsp;&nbsp;Requirements</a></li>
-<li><a class="reference internal" href="#background" id="id22">2&nbsp;&nbsp;&nbsp;Background</a></li>
-<li><a class="reference internal" href="#no-install-quickstart" id="id23">3&nbsp;&nbsp;&nbsp;No-Install Quickstart</a><ul class="auto-toc">
-<li><a class="reference internal" href="#basic-procedure" id="id24">3.1&nbsp;&nbsp;&nbsp;Basic Procedure</a></li>
-<li><a class="reference internal" href="#in-case-of-trouble" id="id25">3.2&nbsp;&nbsp;&nbsp;In Case of Trouble</a></li>
-<li><a class="reference internal" href="#in-case-everything-seemed-to-work" id="id26">3.3&nbsp;&nbsp;&nbsp;In Case Everything Seemed to Work</a></li>
-<li><a class="reference internal" href="#modifying-the-example-project" id="id27">3.4&nbsp;&nbsp;&nbsp;Modifying the Example Project</a></li>
+<li><a class="reference" href="#requirements" id="id24" name="id24">1&nbsp;&nbsp;&nbsp;Requirements</a></li>
+<li><a class="reference" href="#background" id="id25" name="id25">2&nbsp;&nbsp;&nbsp;Background</a></li>
+<li><a class="reference" href="#no-install-quickstart" id="id26" name="id26">3&nbsp;&nbsp;&nbsp;No-Install Quickstart</a><ul class="auto-toc">
+<li><a class="reference" href="#basic-procedure" id="id27" name="id27">3.1&nbsp;&nbsp;&nbsp;Basic Procedure</a></li>
+<li><a class="reference" href="#in-case-of-trouble" id="id28" name="id28">3.2&nbsp;&nbsp;&nbsp;In Case of Trouble</a></li>
+<li><a class="reference" href="#in-case-everything-seemed-to-work" id="id29" name="id29">3.3&nbsp;&nbsp;&nbsp;In Case Everything Seemed to Work</a></li>
+<li><a class="reference" href="#modifying-the-example-project" id="id30" name="id30">3.4&nbsp;&nbsp;&nbsp;Modifying the Example Project</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#installing-boost-python-on-your-system" id="id28">4&nbsp;&nbsp;&nbsp;Installing Boost.Python on your System</a></li>
-<li><a class="reference internal" href="#configuring-boost-build" id="id29">5&nbsp;&nbsp;&nbsp;Configuring Boost.Build</a><ul class="auto-toc">
-<li><a class="reference internal" href="#python-configuration-parameters" id="id30">5.1&nbsp;&nbsp;&nbsp;Python Configuration Parameters</a></li>
-<li><a class="reference internal" href="#examples" id="id31">5.2&nbsp;&nbsp;&nbsp;Examples</a></li>
+<li><a class="reference" href="#installing-boost-python-on-your-system" id="id31" name="id31">4&nbsp;&nbsp;&nbsp;Installing Boost.Python on your System</a></li>
+<li><a class="reference" href="#configuring-boost-build" id="id32" name="id32">5&nbsp;&nbsp;&nbsp;Configuring Boost.Build</a><ul class="auto-toc">
+<li><a class="reference" href="#python-configuration-parameters" id="id33" name="id33">5.1&nbsp;&nbsp;&nbsp;Python Configuration Parameters</a></li>
+<li><a class="reference" href="#examples" id="id34" name="id34">5.2&nbsp;&nbsp;&nbsp;Examples</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#choosing-a-boost-python-library-binary" id="id32">6&nbsp;&nbsp;&nbsp;Choosing a Boost.Python Library Binary</a><ul class="auto-toc">
-<li><a class="reference internal" href="#the-dynamic-binary" id="id33">6.1&nbsp;&nbsp;&nbsp;The Dynamic Binary</a></li>
-<li><a class="reference internal" href="#the-static-binary" id="id34">6.2&nbsp;&nbsp;&nbsp;The Static Binary</a></li>
+<li><a class="reference" href="#choosing-a-boost-python-library-binary" id="id35" name="id35">6&nbsp;&nbsp;&nbsp;Choosing a Boost.Python Library Binary</a><ul class="auto-toc">
+<li><a class="reference" href="#the-dynamic-binary" id="id36" name="id36">6.1&nbsp;&nbsp;&nbsp;The Dynamic Binary</a></li>
+<li><a class="reference" href="#the-static-binary" id="id37" name="id37">6.2&nbsp;&nbsp;&nbsp;The Static Binary</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#testing" id="id35">7&nbsp;&nbsp;&nbsp;Testing</a></li>
-<li><a class="reference internal" href="#notes-for-mingw-and-cygwin-with-mno-cygwin-gcc-users" id="id36">8&nbsp;&nbsp;&nbsp;Notes for MinGW (and Cygwin with -mno-cygwin) GCC Users</a></li>
+<li><a class="reference" href="#include-issues" id="id38" name="id38">7&nbsp;&nbsp;&nbsp;<tt class="docutils literal"><span class="pre">#include</span></tt> Issues</a></li>
+<li><a class="reference" href="#python-debugging-builds" id="id39" name="id39">8&nbsp;&nbsp;&nbsp;Python Debugging Builds</a></li>
+<li><a class="reference" href="#testing-boost-python" id="id40" name="id40">9&nbsp;&nbsp;&nbsp;Testing Boost.Python</a></li>
+<li><a class="reference" href="#notes-for-mingw-and-cygwin-with-mno-cygwin-gcc-users" id="id41" name="id41">10&nbsp;&nbsp;&nbsp;Notes for MinGW (and Cygwin with -mno-cygwin) GCC Users</a></li>
 </ul>
 </div>
-<div class="section" id="requirements">
-<h1><a class="toc-backref" href="#id21">1&nbsp;&nbsp;&nbsp;Requirements</a></h1>
-<p>Boost.Python requires <a class="reference external" href="http://www.python.org/2.2">Python 2.2</a><a class="footnote-reference" href="#id18" id="id2"><sup>1</sup></a> <em>or</em> <a class="reference external" href="http://www.python.org"><em>newer</em></a>.</p>
+<div class="section">
+<h1><a class="toc-backref" href="#id24" id="requirements" name="requirements">1&nbsp;&nbsp;&nbsp;Requirements</a></h1>
+<p>Boost.Python requires <a class="reference" href="http://www.python.org/2.2">Python 2.2</a><a class="footnote-reference" href="#id21" id="id2" name="id2"><sup>1</sup></a> <em>or</em> <a class="reference" href="http://www.python.org"><em>newer</em></a>.</p>
 </div>
-<div class="section" id="background">
-<h1><a class="toc-backref" href="#id22">2&nbsp;&nbsp;&nbsp;Background</a></h1>
+<div class="section">
+<h1><a class="toc-backref" href="#id25" id="background" name="background">2&nbsp;&nbsp;&nbsp;Background</a></h1>
 <p>There are two basic models for combining C++ and Python:</p>
 <ul class="simple">
-<li><a class="reference external" href="http://www.python.org/doc/current/ext/intro.html">extending</a>, in which the end-user launches the Python interpreter
+<li><a class="reference" href="http://www.python.org/doc/current/ext/intro.html">extending</a>, in which the end-user launches the Python interpreter
 executable and imports Python “extension modules” written in C++.
 Think of taking a library written in C++ and giving it a Python
 interface so Python programmers can use it.  From Python, these
 modules look just like regular Python modules.</li>
-<li><a class="reference external" href="http://www.python.org/doc/current/ext/embedding.html">embedding</a>, in which the end-user launches a program written
+<li><a class="reference" href="http://www.python.org/doc/current/ext/embedding.html">embedding</a>, in which the end-user launches a program written
 in C++ that in turn invokes the Python interpreter as a library
 subroutine.  Think of adding scriptability to an existing
 application.</li>
@@ -63,7 +65,7 @@ application.</li>
 <p>The key distinction between extending and embedding is the location
 of the C++ <tt class="docutils literal"><span class="pre">main()</span></tt> function: in the Python interpreter executable,
 or in some other program, respectively.  Note that even when
-embedding Python in another program, <a class="reference external" href="http://www.python.org/doc/current/ext/extending-with-embedding.html">extension modules are often
+embedding Python in another program, <a class="reference" href="http://www.python.org/doc/current/ext/extending-with-embedding.html">extension modules are often
 the best way to make C/C++ functionality accessible to Python
 code</a>, so the use of extension modules is really at the heart of
 both models.</p>
@@ -72,10 +74,10 @@ dynamically-loaded libraries with a single entry point, which means
 you can change them without rebuilding either the other extension
 modules or the executable containing <tt class="docutils literal"><span class="pre">main()</span></tt>.</p>
 </div>
-<div class="section" id="no-install-quickstart">
-<h1><a class="toc-backref" href="#id23">3&nbsp;&nbsp;&nbsp;No-Install Quickstart</a></h1>
+<div class="section">
+<h1><a class="toc-backref" href="#id26" id="no-install-quickstart" name="no-install-quickstart">3&nbsp;&nbsp;&nbsp;No-Install Quickstart</a></h1>
 <p>There is no need to “install Boost” in order to get started using
-Boost.Python.  These instructions use <a class="reference external" href="../../../tools/build/index.html">Boost.Build</a> projects,
+Boost.Python.  These instructions use <a class="reference" href="../../../tools/build/index.html">Boost.Build</a> projects,
 which will build those binaries as soon as they're needed.  Your
 first tests may take a little longer while you wait for
 Boost.Python to build, but doing things this way will save you from
@@ -103,20 +105,20 @@ you can see what your alternate build system needs to do.</p>
 <!-- .. raw:: html
 
 </div> -->
-<div class="section" id="basic-procedure">
-<h2><a class="toc-backref" href="#id24">3.1&nbsp;&nbsp;&nbsp;Basic Procedure</a></h2>
+<div class="section">
+<h2><a class="toc-backref" href="#id27" id="basic-procedure" name="basic-procedure">3.1&nbsp;&nbsp;&nbsp;Basic Procedure</a></h2>
 <ol class="arabic">
-<li><p class="first">Get Boost; see sections 1 and 2 [<a class="reference external" href="../../../more/getting_started/unix-variants.html#get-boost">Unix/Linux</a>, <a class="reference external" href="../../../more/getting_started/windows.html#get-boost">Windows</a>] of the
-Boost <a class="reference external" href="../../../more/getting_started/index.html">Getting Started Guide</a>.</p>
+<li><p class="first">Get Boost; see sections 1 and 2 [<a class="reference" href="../../../more/getting_started/unix-variants.html#get-boost">Unix/Linux</a>, <a class="reference" href="../../../more/getting_started/windows.html#get-boost">Windows</a>] of the
+Boost <a class="reference" href="../../../more/getting_started/index.html">Getting Started Guide</a>.</p>
 </li>
-<li><p class="first">Get the <tt class="docutils literal"><span class="pre">bjam</span></tt> build driver.  See section 5 [<a class="reference external" href="../../../more/getting_started/unix-variants.html#prepare-to-use-a-boost-library-binary">Unix/Linux</a>,
-<a class="reference external" href="../../../more/getting_started/windows.html#prepare-to-use-a-boost-library-binary">Windows</a>] of the Boost <a class="reference external" href="../../../more/getting_started/index.html">Getting Started Guide</a>.</p>
+<li><p class="first">Get the <tt class="docutils literal"><span class="pre">bjam</span></tt> build driver.  See section 5 [<a class="reference" href="../../../more/getting_started/unix-variants.html#prepare-to-use-a-boost-library-binary">Unix/Linux</a>,
+<a class="reference" href="../../../more/getting_started/windows.html#prepare-to-use-a-boost-library-binary">Windows</a>] of the Boost <a class="reference" href="../../../more/getting_started/index.html">Getting Started Guide</a>.</p>
 </li>
 <li><p class="first">cd into the <tt class="docutils literal"><span class="pre">libs/python/example/quickstart/</span></tt> directory of your
 Boost installation, which contains a small example project.</p>
 </li>
 <li><p class="first">Invoke <tt class="docutils literal"><span class="pre">bjam</span></tt>.  Replace the “<tt class="docutils literal"><span class="pre">stage</span></tt>“ argument from the
-example invocation from section 5 of the <a class="reference external" href="../../../more/getting_started/index.html">Getting Started
+example invocation from section 5 of the <a class="reference" href="../../../more/getting_started/index.html">Getting Started
 Guide</a> with “<tt class="docutils literal"><span class="pre">test</span></tt>,“ to build all the test targets.  Also add
 the argument “<tt class="docutils literal"><span class="pre">--verbose-test</span></tt>” to see the output generated by
 the tests when they are run.</p>
@@ -135,7 +137,7 @@ C:\boost_1_34_0\…\quickstart&gt; <strong>bjam toolset=msvc --verbose-test test
 <p class="last">For the sake of concision, the rest of this guide will use
 unix-style forward slashes in pathnames instead of the
 backslashes with which you may be more familiar.  The forward
-slashes should work everywhere except in <a class="reference external" href="../../../more/getting_started/windows.html#command-prompt">Command Prompt</a>
+slashes should work everywhere except in <a class="reference" href="../../../more/getting_started/windows.html#command-prompt">Command Prompt</a>
 windows, where you should use backslashes.</p>
 </div>
 <p>If you followed this procedure successfully, you will have built an
@@ -144,49 +146,55 @@ Python script called <tt class="docutils literal"><span class="pre">test_extendi
 built and run a simple application called <tt class="docutils literal"><span class="pre">embedding</span></tt> that embeds
 python.</p>
 </div>
-<div class="section" id="in-case-of-trouble">
-<h2><a class="toc-backref" href="#id25">3.2&nbsp;&nbsp;&nbsp;In Case of Trouble</a></h2>
+<div class="section">
+<h2><a class="toc-backref" href="#id28" id="in-case-of-trouble" name="in-case-of-trouble">3.2&nbsp;&nbsp;&nbsp;In Case of Trouble</a></h2>
 <p>If you're seeing lots of compiler and/or linker error messages,
 it's probably because Boost.Build is having trouble finding your
 Python installation.  You might want to pass the
 <tt class="docutils literal"><span class="pre">--debug-configuration</span></tt> option to <tt class="docutils literal"><span class="pre">bjam</span></tt> the first few times
 you invoke it, to make sure that Boost.Build is correctly locating
 all the parts of your Python installation.  If it isn't, consider
-<a class="reference internal" href="#configuring-boost-build">Configuring Boost.Build</a> as detailed below.</p>
+<a class="reference" href="#configuring-boost-build">Configuring Boost.Build</a> as detailed below.</p>
+<p>If you're still having trouble, Someone on one of the following
+mailing lists may be able to help:</p>
+<ul class="simple">
+<li>The <a class="reference" href="../../../more/mailing_lists.htm#jamboost">Boost.Build mailing list</a> for issues related to Boost.Build</li>
+<li>The Python <a class="reference" href="../../../more/mailing_lists.htm#cplussig">C++ Sig</a> for issues specifically related to Boost.Python</li>
+</ul>
 </div>
-<div class="section" id="in-case-everything-seemed-to-work">
-<h2><a class="toc-backref" href="#id26">3.3&nbsp;&nbsp;&nbsp;In Case Everything Seemed to Work</a></h2>
+<div class="section">
+<h2><a class="toc-backref" href="#id29" id="in-case-everything-seemed-to-work" name="in-case-everything-seemed-to-work">3.3&nbsp;&nbsp;&nbsp;In Case Everything Seemed to Work</a></h2>
 <p>Rejoice!  If you're new to Boost.Python, at this point it might be
 a good idea to ignore build issues for a while and concentrate on
-learning the library by going through the <a class="reference external" href="tutorial/index.html">tutorial</a> and perhaps
-some of the <a class="reference external" href="v2/reference.html">reference documentation</a>, trying out what you've
+learning the library by going through the <a class="reference" href="tutorial/index.html">tutorial</a> and perhaps
+some of the <a class="reference" href="v2/reference.html">reference documentation</a>, trying out what you've
 learned about the API by modifying the quickstart project.</p>
 </div>
-<div class="section" id="modifying-the-example-project">
-<h2><a class="toc-backref" href="#id27">3.4&nbsp;&nbsp;&nbsp;Modifying the Example Project</a></h2>
+<div class="section">
+<h2><a class="toc-backref" href="#id30" id="modifying-the-example-project" name="modifying-the-example-project">3.4&nbsp;&nbsp;&nbsp;Modifying the Example Project</a></h2>
 <p>If you're content to keep your extension module forever in one
-source file called <a class="reference external" href="../example/quickstart/extending.cpp"><tt class="docutils literal"><span class="pre">extending.cpp</span></tt></a>, inside your Boost
+source file called <a class="reference" href="../example/quickstart/extending.cpp"><tt class="docutils literal"><span class="pre">extending.cpp</span></tt></a>, inside your Boost
 distribution, and import it forever as <tt class="docutils literal"><span class="pre">extending</span></tt>, then you can
 stop here.  However, it's likely that you will want to make a few
 changes.  There are a few things you can do without having to learn
-<a class="reference external" href="../../../tools/build/index.html">Boost.Build</a> in depth.</p>
+<a class="reference" href="../../../tools/build/index.html">Boost.Build</a> in depth.</p>
 <p>The project you just built is specified in two files in the current
-directory: <a class="reference external" href="../example/quickstart/boost-build.jam"><tt class="docutils literal"><span class="pre">boost-build.jam</span></tt></a>, which tells <tt class="docutils literal"><span class="pre">bjam</span></tt> where it can
+directory: <a class="reference" href="../example/quickstart/boost-build.jam"><tt class="docutils literal"><span class="pre">boost-build.jam</span></tt></a>, which tells <tt class="docutils literal"><span class="pre">bjam</span></tt> where it can
 find the interpreted code of the Boost build system, and
-<a class="reference external" href="../example/quickstart/Jamroot"><tt class="docutils literal"><span class="pre">Jamroot</span></tt></a>, which describes the targets you just built.  These
+<a class="reference" href="../example/quickstart/Jamroot"><tt class="docutils literal"><span class="pre">Jamroot</span></tt></a>, which describes the targets you just built.  These
 files are heavily commented, so they should be easy to modify.
 Take care, however, to preserve whitespace.  Punctuation such as
 <tt class="docutils literal"><span class="pre">;</span></tt> will not be recognized as intended by <tt class="docutils literal"><span class="pre">bjam</span></tt> if it is not
 surrounded by whitespace.</p>
-<div class="section" id="relocate-the-project">
-<h3>Relocate the Project</h3>
+<div class="section">
+<h3><a id="relocate-the-project" name="relocate-the-project">Relocate the Project</a></h3>
 <p>You'll probably want to copy this project elsewhere so you can
 change it without modifying your Boost distribution.  To do that,
 simply</p>
 <ol class="loweralpha simple">
 <li>copy the entire <tt class="docutils literal"><span class="pre">libs/python/example/quickstart/</span></tt> directory
 into a new directory.</li>
-<li>In the new copies of <a class="reference external" href="../example/quickstart/boost-build.jam"><tt class="docutils literal"><span class="pre">boost-build.jam</span></tt></a> and <a class="reference external" href="../example/quickstart/Jamroot"><tt class="docutils literal"><span class="pre">Jamroot</span></tt></a>, locate
+<li>In the new copies of <a class="reference" href="../example/quickstart/boost-build.jam"><tt class="docutils literal"><span class="pre">boost-build.jam</span></tt></a> and <a class="reference" href="../example/quickstart/Jamroot"><tt class="docutils literal"><span class="pre">Jamroot</span></tt></a>, locate
 the relative path near the top of the file that is clearly
 marked by a comment, and edit that path so that it refers to the
 same directory your Boost distribution as it referred to when
@@ -196,7 +204,7 @@ the file was in its original location in the
 <p>For example, if you moved the project from
 <tt class="docutils literal"><span class="pre">/home/dave/boost_1_34_0/libs/python/example/quickstart</span></tt> to
 <tt class="docutils literal"><span class="pre">/home/dave/my-project</span></tt>, you could change the first path in
-<a class="reference external" href="../example/quickstart/boost-build.jam"><tt class="docutils literal"><span class="pre">boost-build.jam</span></tt></a> from</p>
+<a class="reference" href="../example/quickstart/boost-build.jam"><tt class="docutils literal"><span class="pre">boost-build.jam</span></tt></a> from</p>
 <pre class="literal-block">
 <strong>../../../..</strong>/tools/build/v2
 </pre>
@@ -204,7 +212,7 @@ the file was in its original location in the
 <pre class="literal-block">
 <strong>/home/dave/boost_1_34_0</strong>/tools/build/v2
 </pre>
-<p>and change the first path in <a class="reference external" href="../example/quickstart/Jamroot"><tt class="docutils literal"><span class="pre">Jamroot</span></tt></a> from</p>
+<p>and change the first path in <a class="reference" href="../example/quickstart/Jamroot"><tt class="docutils literal"><span class="pre">Jamroot</span></tt></a> from</p>
 <pre class="literal-block">
 <strong>../../../..</strong>
 </pre>
@@ -213,28 +221,28 @@ the file was in its original location in the
 <strong>/home/dave/boost_1_34_0</strong>
 </pre>
 </div>
-<div class="section" id="add-new-or-change-names-of-existing-source-files">
-<h3>Add New or Change Names of Existing Source Files</h3>
+<div class="section">
+<h3><a id="add-new-or-change-names-of-existing-source-files" name="add-new-or-change-names-of-existing-source-files">Add New or Change Names of Existing Source Files</a></h3>
 <p>The names of additional source files involved in building your
 extension module or embedding application can be listed in
-<a class="reference external" href="../example/quickstart/Jamroot"><tt class="docutils literal"><span class="pre">Jamroot</span></tt></a> right alongside <tt class="docutils literal"><span class="pre">extending.cpp</span></tt> or <tt class="docutils literal"><span class="pre">embedding.cpp</span></tt>
+<a class="reference" href="../example/quickstart/Jamroot"><tt class="docutils literal"><span class="pre">Jamroot</span></tt></a> right alongside <tt class="docutils literal"><span class="pre">extending.cpp</span></tt> or <tt class="docutils literal"><span class="pre">embedding.cpp</span></tt>
 respectively.  Just be sure to leave whitespace around each
 filename:</p>
 <pre class="literal-block">
 … file1.cpp file2.cpp file3.cpp …
 </pre>
 <p>Naturally, if you want to change the name of a source file you can
-tell Boost.Build about it by editing the name in <a class="reference external" href="../example/quickstart/Jamroot"><tt class="docutils literal"><span class="pre">Jamroot</span></tt></a>.</p>
+tell Boost.Build about it by editing the name in <a class="reference" href="../example/quickstart/Jamroot"><tt class="docutils literal"><span class="pre">Jamroot</span></tt></a>.</p>
 </div>
-<div class="section" id="change-the-name-of-your-extension-module">
-<h3>Change the Name of your Extension Module</h3>
+<div class="section">
+<h3><a id="change-the-name-of-your-extension-module" name="change-the-name-of-your-extension-module">Change the Name of your Extension Module</a></h3>
 <p>The name of the extension module is determined by two things:</p>
 <ol class="arabic simple">
-<li>the name in <a class="reference external" href="../example/quickstart/Jamroot"><tt class="docutils literal"><span class="pre">Jamroot</span></tt></a> immediately following <tt class="docutils literal"><span class="pre">python-extension</span></tt>, and</li>
-<li>the name passed to <tt class="docutils literal"><span class="pre">BOOST_PYTHON_MODULE</span></tt> in <a class="reference external" href="../example/quickstart/extending.cpp"><tt class="docutils literal"><span class="pre">extending.cpp</span></tt></a>.</li>
+<li>the name in <a class="reference" href="../example/quickstart/Jamroot"><tt class="docutils literal"><span class="pre">Jamroot</span></tt></a> immediately following <tt class="docutils literal"><span class="pre">python-extension</span></tt>, and</li>
+<li>the name passed to <tt class="docutils literal"><span class="pre">BOOST_PYTHON_MODULE</span></tt> in <a class="reference" href="../example/quickstart/extending.cpp"><tt class="docutils literal"><span class="pre">extending.cpp</span></tt></a>.</li>
 </ol>
 <p>To change the name of the extension module from <tt class="docutils literal"><span class="pre">extending</span></tt> to
-<tt class="docutils literal"><span class="pre">hello</span></tt>, you'd edit <a class="reference external" href="../example/quickstart/Jamroot"><tt class="docutils literal"><span class="pre">Jamroot</span></tt></a>, changing</p>
+<tt class="docutils literal"><span class="pre">hello</span></tt>, you'd edit <a class="reference" href="../example/quickstart/Jamroot"><tt class="docutils literal"><span class="pre">Jamroot</span></tt></a>, changing</p>
 <pre class="literal-block">
 python-extension <strong>extending</strong> : extending.cpp ;
 </pre>
@@ -253,13 +261,13 @@ BOOST_PYTHON_MODULE(<strong>hello</strong>)
 </div>
 </div>
 </div>
-<div class="section" id="installing-boost-python-on-your-system">
-<h1><a class="toc-backref" href="#id28">4&nbsp;&nbsp;&nbsp;Installing Boost.Python on your System</a></h1>
+<div class="section">
+<h1><a class="toc-backref" href="#id31" id="installing-boost-python-on-your-system" name="installing-boost-python-on-your-system">4&nbsp;&nbsp;&nbsp;Installing Boost.Python on your System</a></h1>
 <p>Since Boost.Python is a separately-compiled (as opposed to
-<a class="reference external" href="../../../more/getting_started/windows.html#header-only-libraries">header-only</a>) library, its user relies on the services of a
+<a class="reference" href="../../../more/getting_started/windows.html#header-only-libraries">header-only</a>) library, its user relies on the services of a
 Boost.Python library binary.</p>
 <p>If you need a regular installation of the Boost.Python library
-binaries on your system, the Boost <a class="reference external" href="../../../more/getting_started/index.html">Getting Started Guide</a> will
+binaries on your system, the Boost <a class="reference" href="../../../more/getting_started/index.html">Getting Started Guide</a> will
 walk you through the steps of creating one.  If building binaries
 from source, you might want to supply the <tt class="docutils literal"><span class="pre">--with-python</span></tt>
 argument to <tt class="docutils literal"><span class="pre">bjam</span></tt> (or the <tt class="docutils literal"><span class="pre">--with-libraries=python</span></tt> argument
@@ -267,31 +275,31 @@ to <tt class="docutils literal"><span class="pre">configure</span></tt>), so onl
 rather than all the Boost binaries.</p>
 <div class="admonition-windows-users-no-auto-link-support admonition">
 <p class="first admonition-title">Windows Users: No Auto-Link Support</p>
-<p class="last">Boost.Python does not yet support the <a class="reference external" href="../../../more/getting_started/windows.html#link-your-program-to-a-boost-library">auto-link</a> feature, so if
-you're not using the <a class="reference internal" href="#no-install-quickstart">quickstart</a> method, you'll have to pay
+<p class="last">Boost.Python does not yet support the <a class="reference" href="../../../more/getting_started/windows.html#link-your-program-to-a-boost-library">auto-link</a> feature, so if
+you're not using the <a class="reference" href="#no-install-quickstart">quickstart</a> method, you'll have to pay
 attention to the names of generated libraries and add extra link
-arguments not shown in the <a class="reference external" href="../../../more/getting_started/index.html">Getting Started Guide</a> to select the
+arguments not shown in the <a class="reference" href="../../../more/getting_started/index.html">Getting Started Guide</a> to select the
 right library.</p>
 </div>
 </div>
-<div class="section" id="configuring-boost-build">
-<h1><a class="toc-backref" href="#id29">5&nbsp;&nbsp;&nbsp;Configuring Boost.Build</a></h1>
-<p>As described in the <a class="reference external" href="http://www.boost.orgdoc/html/bbv2/advanced.html#bbv2.advanced.configuration">Boost.Build reference manual</a>, a file called
-<tt class="docutils literal"><span class="pre">user-config.jam</span></tt> in your home directory<a class="footnote-reference" href="#home-dir" id="id9"><sup>6</sup></a> is used to
-describe the tools and libraries available to the build system.  If
-your Python installation is unusual, you may need to create or edit
-<tt class="docutils literal"><span class="pre">user-config.jam</span></tt> to tell Boost.Build how to invoke Python,
-<tt class="docutils literal"><span class="pre">#include</span></tt> its headers, and link with its libraries.</p>
+<div class="section">
+<h1><a class="toc-backref" href="#id32" id="configuring-boost-build" name="configuring-boost-build">5&nbsp;&nbsp;&nbsp;Configuring Boost.Build</a></h1>
+<p>As described in the <a class="reference" href="http://www.boost.orgdoc/html/bbv2/advanced.html#bbv2.advanced.configuration">Boost.Build reference manual</a>, a file called
+<tt class="docutils literal"><span class="pre">user-config.jam</span></tt> in your home directory<a class="footnote-reference" href="#home-dir" id="id11" name="id11"><sup>6</sup></a> is used to
+specify the tools and libraries available to the build system. You
+may need to create or edit <tt class="docutils literal"><span class="pre">user-config.jam</span></tt> to tell Boost.Build
+how to invoke Python, <tt class="docutils literal"><span class="pre">#include</span></tt> its headers, and link with its
+libraries.</p>
 <div class="admonition-users-of-unix-variant-oses admonition">
 <p class="first admonition-title">Users of Unix-Variant OSes</p>
 <p class="last">If you are using a unix-variant OS and you ran Boost's
 <tt class="docutils literal"><span class="pre">configure</span></tt> script, it may have generated a
-<tt class="docutils literal"><span class="pre">user-config.jam</span></tt> for you.<a class="footnote-reference" href="#overwrite" id="id11"><sup>4</sup></a> If your <tt class="docutils literal"><span class="pre">configure</span></tt>/<tt class="docutils literal"><span class="pre">make</span></tt> sequence was successful and Boost.Python binaries
+<tt class="docutils literal"><span class="pre">user-config.jam</span></tt> for you.<a class="footnote-reference" href="#overwrite" id="id13" name="id13"><sup>4</sup></a> If your <tt class="docutils literal"><span class="pre">configure</span></tt>/<tt class="docutils literal"><span class="pre">make</span></tt> sequence was successful and Boost.Python binaries
 were built, your <tt class="docutils literal"><span class="pre">user-config.jam</span></tt> file is probably already
 correct.</p>
 </div>
 <p>If you have one fairly “standard” python installation for your
-platform, you don't need to do anything special to describe it.  If
+platform, you might not need to do anything special to describe it.  If
 you haven't configured python in <tt class="docutils literal"><span class="pre">user-config.jam</span></tt> (and you don't
 specify <tt class="docutils literal"><span class="pre">--without-python</span></tt> on the Boost.Build command line),
 Boost.Build will automatically execute the equivalent of</p>
@@ -301,12 +309,12 @@ using python ;
 </pre>
 <p>which automatically looks for Python in the most likely places.
 However, that only happens when using the Boost.Python project file
-(e.g. when referred to by another project as in the <a class="reference internal" href="#no-install-quickstart">quickstart</a>
+(e.g. when referred to by another project as in the <a class="reference" href="#no-install-quickstart">quickstart</a>
 method).  If instead you are linking against separately-compiled
 Boost.Python binaries, you should set up a <tt class="docutils literal"><span class="pre">user-config.jam</span></tt> file
 with at least the minimal incantation above.</p>
-<div class="section" id="python-configuration-parameters">
-<h2><a class="toc-backref" href="#id30">5.1&nbsp;&nbsp;&nbsp;Python Configuration Parameters</a></h2>
+<div class="section">
+<h2><a class="toc-backref" href="#id33" id="python-configuration-parameters" name="python-configuration-parameters">5.1&nbsp;&nbsp;&nbsp;Python Configuration Parameters</a></h2>
 <p>If you have several versions of Python installed, or Python is
 installed in an unusual way, you may want to supply any or all of
 the following optional parameters to <tt class="docutils literal"><span class="pre">using</span> <span class="pre">python</span></tt>.</p>
@@ -342,13 +350,13 @@ modules before the true filename extension.  You almost certainly
 don't need to use this.  Usually this suffix is only used when
 targeting a Windows debug build of Python, and will be set
 automatically for you based on the value of the
-<tt class="docutils literal"><span class="pre">&lt;python-debugging&gt;</span></tt> feature.  However, at least one Linux
+<a class="reference" href="#python-debugging"><tt class="docutils literal"><span class="pre">&lt;python-debugging&gt;</span></tt></a> feature.  However, at least one Linux
 distribution (Ubuntu Feisty Fawn) has a specially configured
-<a class="reference external" href="https://wiki.ubuntu.com/PyDbgBuilds">python-dbg</a> package that claims to use such a suffix.</dd>
+<a class="reference" href="https://wiki.ubuntu.com/PyDbgBuilds">python-dbg</a> package that claims to use such a suffix.</dd>
 </dl>
 </div>
-<div class="section" id="examples">
-<h2><a class="toc-backref" href="#id31">5.2&nbsp;&nbsp;&nbsp;Examples</a></h2>
+<div class="section">
+<h2><a class="toc-backref" href="#id34" id="examples" name="examples">5.2&nbsp;&nbsp;&nbsp;Examples</a></h2>
 <p>Note that in the examples below, case and <em>especially whitespace</em> are
 significant.</p>
 <ul>
@@ -386,8 +394,19 @@ using python
      ;
 </pre>
 </li>
+<li><p class="first">If you have downloaded the Python sources and built both the
+normal and the “<a class="reference" href="#id19">python debugging</a>” builds from source on
+Windows, you might see:</p>
+<pre class="literal-block">
+using python : 2.5 : C:\\src\\Python-2.5\\PCBuild\\python ;
+using python : 2.5 : C:\\src\\Python-2.5\\PCBuild\\python_d
+  : # includes
+  : # libs
+  : &lt;python-debugging&gt;on ;
+</pre>
+</li>
 <li><p class="first">You can set up your user-config.jam so a bjam built under Windows
-can build/test both Windows and <a class="reference external" href="http://cygwin.com">Cygwin</a> python extensions.  Just pass
+can build/test both Windows and <a class="reference" href="http://cygwin.com">Cygwin</a> python extensions.  Just pass
 <tt class="docutils literal"><span class="pre">&lt;target-os&gt;cygwin</span></tt> in the <tt class="docutils literal"><span class="pre">condition</span></tt> parameter
 for the cygwin python installation:</p>
 <pre class="literal-block">
@@ -398,16 +417,16 @@ using python ;
 using python : : c:\\cygwin\\bin\\python2.5 : : : &lt;target-os&gt;cygwin ;
 </pre>
 <p>when you put target-os=cygwin in your build request, it should build
-with the cygwin version of python:<a class="footnote-reference" href="#flavor" id="id13"><sup>5</sup></a></p>
+with the cygwin version of python:<a class="footnote-reference" href="#flavor" id="id15" name="id15"><sup>5</sup></a></p>
 <blockquote>
 <p>bjam target-os=cygwin toolset=gcc</p>
 </blockquote>
 <p>This is supposed to work the other way, too (targeting windows
-python with a <a class="reference external" href="http://cygwin.com">Cygwin</a> bjam) but it seems as though the support in
+python with a <a class="reference" href="http://cygwin.com">Cygwin</a> bjam) but it seems as though the support in
 Boost.Build's toolsets for building that way is broken at the
 time of this writing.</p>
 </li>
-<li><p class="first">Note that because of <a class="reference external" href="http://zigzag.cs.msu.su/boost.build/wiki/AlternativeSelection">the way Boost.Build currently selects target
+<li><p class="first">Note that because of <a class="reference" href="http://zigzag.cs.msu.su/boost.build/wiki/AlternativeSelection">the way Boost.Build currently selects target
 alternatives</a>, you might have be very explicit in your build
 requests.  For example, given:</p>
 <pre class="literal-block">
@@ -426,35 +445,35 @@ bjam target-os=cygwin/python=2.4
 </ul>
 </div>
 </div>
-<div class="section" id="choosing-a-boost-python-library-binary">
-<h1><a class="toc-backref" href="#id32">6&nbsp;&nbsp;&nbsp;Choosing a Boost.Python Library Binary</a></h1>
+<div class="section">
+<h1><a class="toc-backref" href="#id35" id="choosing-a-boost-python-library-binary" name="choosing-a-boost-python-library-binary">6&nbsp;&nbsp;&nbsp;Choosing a Boost.Python Library Binary</a></h1>
 <p>If—instead of letting Boost.Build construct and link with the right
 libraries automatically—you choose to use a pre-built Boost.Python
 library, you'll need to think about which one to link with.  The
 Boost.Python binary comes in both static and dynamic flavors.  Take
-care to choose the right flavor for your application.<a class="footnote-reference" href="#naming" id="id15"><sup>2</sup></a></p>
-<div class="section" id="the-dynamic-binary">
-<h2><a class="toc-backref" href="#id33">6.1&nbsp;&nbsp;&nbsp;The Dynamic Binary</a></h2>
+care to choose the right flavor for your application.<a class="footnote-reference" href="#naming" id="id17" name="id17"><sup>2</sup></a></p>
+<div class="section">
+<h2><a class="toc-backref" href="#id36" id="the-dynamic-binary" name="the-dynamic-binary">6.1&nbsp;&nbsp;&nbsp;The Dynamic Binary</a></h2>
 <p>The dynamic library is the safest and most-versatile choice:</p>
 <ul class="simple">
 <li>A single copy of the library code is used by all extension
-modules built with a given toolset.<a class="footnote-reference" href="#toolset-specific" id="id16"><sup>3</sup></a></li>
+modules built with a given toolset.<a class="footnote-reference" href="#toolset-specific" id="id18" name="id18"><sup>3</sup></a></li>
 <li>The library contains a type conversion registry.  Because one
 registry is shared among all extension modules, instances of a
 class exposed to Python in one dynamically-loaded extension
 module can be passed to functions exposed in another such module.</li>
 </ul>
 </div>
-<div class="section" id="the-static-binary">
-<h2><a class="toc-backref" href="#id34">6.2&nbsp;&nbsp;&nbsp;The Static Binary</a></h2>
+<div class="section">
+<h2><a class="toc-backref" href="#id37" id="the-static-binary" name="the-static-binary">6.2&nbsp;&nbsp;&nbsp;The Static Binary</a></h2>
 <p>It might be appropriate to use the static Boost.Python library in
 any of the following cases:</p>
 <ul class="simple">
-<li>You are <a class="reference external" href="http://www.python.org/doc/current/ext/intro.html">extending</a> python and the types exposed in your
+<li>You are <a class="reference" href="http://www.python.org/doc/current/ext/intro.html">extending</a> python and the types exposed in your
 dynamically-loaded extension module don't need to be used by any
 other Boost.Python extension modules, and you don't care if the
 core library code is duplicated among them.</li>
-<li>You are <a class="reference external" href="http://www.python.org/doc/current/ext/embedding.html">embedding</a> python in your application and either:<ul>
+<li>You are <a class="reference" href="http://www.python.org/doc/current/ext/embedding.html">embedding</a> python in your application and either:<ul>
 <li>You are targeting a Unix variant OS other than MacOS or AIX,
 where the dynamically-loaded extension modules can “see” the
 Boost.Python library symbols that are part of the executable.</li>
@@ -468,25 +487,73 @@ modules (and vice-versa).</li>
 </ul>
 </div>
 </div>
-<div class="section" id="testing">
-<h1><a class="toc-backref" href="#id35">7&nbsp;&nbsp;&nbsp;Testing</a></h1>
+<div class="section">
+<h1><a class="toc-backref" href="#id38" id="include-issues" name="include-issues">7&nbsp;&nbsp;&nbsp;<tt class="docutils literal"><span class="pre">#include</span></tt> Issues</a></h1>
+<ol class="arabic simple">
+<li>If you should ever have occasion to <tt class="docutils literal"><span class="pre">#include</span> <span class="pre">&quot;python.h&quot;</span></tt>
+directly in a translation unit of a program using Boost.Python,
+use <tt class="docutils literal"><span class="pre">#include</span> <span class="pre">&quot;boost/python/detail/wrap_python.hpp&quot;</span></tt> instead.
+It handles several issues necessary for use with Boost.Python,
+one of which is mentioned in the next section.</li>
+<li>Be sure not to <tt class="docutils literal"><span class="pre">#include</span></tt> any system headers before
+<tt class="docutils literal"><span class="pre">wrap_python.hpp</span></tt>.  This restriction is actually imposed by
+Python, or more properly, by Python's interaction with your
+operating system.  See
+<a class="reference" href="http://docs.python.org/ext/simpleExample.html">http://docs.python.org/ext/simpleExample.html</a> for details.</li>
+</ol>
 </div>
-<div class="section" id="notes-for-mingw-and-cygwin-with-mno-cygwin-gcc-users">
-<h1><a class="toc-backref" href="#id36">8&nbsp;&nbsp;&nbsp;Notes for MinGW (and Cygwin with -mno-cygwin) GCC Users</a></h1>
+<div class="section">
+<h1><a class="toc-backref" href="#id39" id="python-debugging-builds" name="python-debugging-builds"><span id="id19"></span><span id="python-debugging"></span>8&nbsp;&nbsp;&nbsp;Python Debugging Builds</a></h1>
+<p>Python can be built in a special “python debugging” configuration
+that adds extra checks and instrumentation that can be very useful
+for developers of extension modules.  The data structures used by
+the debugging configuration contain additional members, so <strong>a
+Python executable built with python debugging enabled cannot be
+used with an extension module or library compiled without it, and
+vice-versa.</strong></p>
+<p>Since pre-built “python debugging” versions of the Python
+executable and libraries are not supplied with most distributions
+of Python, [#get-debug-build] and we didn't want to force our users
+to build them, Boost.Build does not automatically enable python
+debugging in its <tt class="docutils literal"><span class="pre">debug</span></tt> build variant (which is the default).
+Instead there is a special build property called
+<tt class="docutils literal"><span class="pre">python-debugging</span></tt> that, when used as a build property, will
+define the right preprocessor symbols and select the right
+libraries to link with.</p>
+<p>On unix-variant platforms, the debugging versions of Python's data
+structures will only be used if the symbol <tt class="docutils literal"><span class="pre">Py_DEBUG</span></tt> is defined.
+On many windows compilers, when extension modules are built with
+the preprocessor symbol <tt class="docutils literal"><span class="pre">_DEBUG</span></tt>, Python defaults to force
+linking with a special debugging version of the Python DLL.  Since
+that symbol is very commonly used even when Python is not present,
+Boost.Python temporarily undefines _DEBUG when Python.h
+is #included from <tt class="docutils literal"><span class="pre">boost/python/detail/wrap_python.hpp</span></tt> - unless
+<tt class="docutils literal"><span class="pre">BOOST_DEBUG_PYTHON</span></tt> is defined.  The upshot is that if you want
+“python debugging”and you aren't using Boost.Build, you should make
+sure <tt class="docutils literal"><span class="pre">BOOST_DEBUG_PYTHON</span></tt> is defined, or python debugging will be
+suppressed.</p>
+</div>
+<div class="section">
+<h1><a class="toc-backref" href="#id40" id="testing-boost-python" name="testing-boost-python">9&nbsp;&nbsp;&nbsp;Testing Boost.Python</a></h1>
+<p>To run the full test suite for Boost.Python, invoke <tt class="docutils literal"><span class="pre">bjam</span></tt> in the
+<tt class="docutils literal"><span class="pre">libs/python/test</span></tt> subdirectory of your Boost distribution.</p>
+</div>
+<div class="section">
+<h1><a class="toc-backref" href="#id41" id="notes-for-mingw-and-cygwin-with-mno-cygwin-gcc-users" name="notes-for-mingw-and-cygwin-with-mno-cygwin-gcc-users">10&nbsp;&nbsp;&nbsp;Notes for MinGW (and Cygwin with -mno-cygwin) GCC Users</a></h1>
 <p>If you are using a version of Python prior to 2.4.1 with a MinGW
 prior to 3.0.0 (with binutils-2.13.90-20030111-1), you will need to
 create a MinGW-compatible version of the Python library; the one
 shipped with Python will only work with a Microsoft-compatible
 linker. Follow the instructions in the “Non-Microsoft” section of
-the “Building Extensions: Tips And Tricks” chapter in <a class="reference external" href="http://www.python.org/doc/current/inst/index.html">Installing
+the “Building Extensions: Tips And Tricks” chapter in <a class="reference" href="http://www.python.org/doc/current/inst/index.html">Installing
 Python Modules</a> to create <tt class="docutils literal"><span class="pre">libpythonXX.a</span></tt>, where <tt class="docutils literal"><span class="pre">XX</span></tt>
 corresponds to the major and minor version numbers of your Python
 installation.</p>
 <hr class="docutils" />
-<table class="docutils footnote" frame="void" id="id18" rules="none">
+<table class="docutils footnote" frame="void" id="id21" rules="none">
 <colgroup><col class="label" /><col /></colgroup>
 <tbody valign="top">
-<tr><td class="label"><a class="fn-backref" href="#id2">[1]</a></td><td>Note that although we tested earlier versions of
+<tr><td class="label"><a class="fn-backref" href="#id2" name="id21">[1]</a></td><td>Note that although we tested earlier versions of
 Boost.Python with Python 2.2, and we don't <em>think</em> we've done
 anything to break compatibility, this release of Boost.Python
 may not have been tested with versions of Python earlier than
@@ -497,11 +564,11 @@ supported.</td></tr>
 <table class="docutils footnote" frame="void" id="naming" rules="none">
 <colgroup><col class="label" /><col /></colgroup>
 <tbody valign="top">
-<tr><td class="label"><a class="fn-backref" href="#id15">[2]</a></td><td><p class="first">Information about how to identify the
+<tr><td class="label"><a class="fn-backref" href="#id17" name="naming">[2]</a></td><td><p class="first">Information about how to identify the
 static and dynamic builds of Boost.Python:</p>
 <ul class="simple">
-<li><a class="reference external" href="../../../more/getting_started/windows.html#library-naming">on Windows</a></li>
-<li><a class="reference external" href="../../../more/getting_started/unix-variants.html#library-naming">on Unix variants</a></li>
+<li><a class="reference" href="../../../more/getting_started/windows.html#library-naming">on Windows</a></li>
+<li><a class="reference" href="../../../more/getting_started/unix-variants.html#library-naming">on Unix variants</a></li>
 </ul>
 <p class="last">Be sure to read this section even if your compiler supports
 auto-linking, as Boost.Python does not yet take advantage of
@@ -512,9 +579,9 @@ that feature.</p>
 <table class="docutils footnote" frame="void" id="toolset-specific" rules="none">
 <colgroup><col class="label" /><col /></colgroup>
 <tbody valign="top">
-<tr><td class="label"><a class="fn-backref" href="#id16">[3]</a></td><td>Because of the way most *nix platforms
-share symbols among dynamically-loaded objects, I'm not
-certainextension modules built with different compiler toolsets
+<tr><td class="label"><a class="fn-backref" href="#id18" name="toolset-specific">[3]</a></td><td>Because of the way most *nix platforms
+share symbols among dynamically-loaded objects, I'm not certain
+that extension modules built with different compiler toolsets
 will always use different copies of the Boost.Python library
 when loaded into the same Python instance.  Not using different
 libraries could be a good thing if the compilers have compatible
@@ -529,7 +596,7 @@ happens.</td></tr>
 <table class="docutils footnote" frame="void" id="overwrite" rules="none">
 <colgroup><col class="label" /><col /></colgroup>
 <tbody valign="top">
-<tr><td class="label"><a class="fn-backref" href="#id11">[4]</a></td><td><tt class="docutils literal"><span class="pre">configure</span></tt> overwrites the existing
+<tr><td class="label"><a class="fn-backref" href="#id13" name="overwrite">[4]</a></td><td><tt class="docutils literal"><span class="pre">configure</span></tt> overwrites the existing
 <tt class="docutils literal"><span class="pre">user-config.jam</span></tt> in your home directory
 (if any) after making a backup of the old version.</td></tr>
 </tbody>
@@ -537,7 +604,7 @@ happens.</td></tr>
 <table class="docutils footnote" frame="void" id="flavor" rules="none">
 <colgroup><col class="label" /><col /></colgroup>
 <tbody valign="top">
-<tr><td class="label"><a class="fn-backref" href="#id13">[5]</a></td><td>Note that the <tt class="docutils literal"><span class="pre">&lt;target-os&gt;cygwin</span></tt> feature is
+<tr><td class="label"><a class="fn-backref" href="#id15" name="flavor">[5]</a></td><td>Note that the <tt class="docutils literal"><span class="pre">&lt;target-os&gt;cygwin</span></tt> feature is
 different from the <tt class="docutils literal"><span class="pre">&lt;flavor&gt;cygwin</span></tt> subfeature of the <tt class="docutils literal"><span class="pre">gcc</span></tt>
 toolset, and you might need handle both explicitly if you also
 have a MinGW GCC installed.</td></tr>
@@ -546,22 +613,34 @@ have a MinGW GCC installed.</td></tr>
 <table class="docutils footnote" frame="void" id="home-dir" rules="none">
 <colgroup><col class="label" /><col /></colgroup>
 <tbody valign="top">
-<tr><td class="label"><a class="fn-backref" href="#id9">[6]</a></td><td><p class="first">Windows users, your home directory can be
+<tr><td class="label"><a class="fn-backref" href="#id11" name="home-dir">[6]</a></td><td><p class="first">Windows users, your home directory can be
 found by typing:</p>
 <pre class="literal-block">
 ECHO %HOMEDRIVE%%HOMEPATH%
 </pre>
-<p class="last">into a <a class="reference external" href="../../../more/getting_started/windows.html#command-prompt">command prompt</a> window.</p>
+<p class="last">into a <a class="reference" href="../../../more/getting_started/windows.html#command-prompt">command prompt</a> window.</p>
 </td></tr>
 </tbody>
 </table>
+<table class="docutils footnote" frame="void" id="get-debug-build" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="get-debug-build">[7]</a></td><td>On Unix and similar platforms, a debugging
+python and associated libraries are built by adding
+<tt class="docutils literal"><span class="pre">--with-pydebug</span></tt> when configuring the Python build. On
+Windows, the debugging version of Python is generated by
+the &quot;Win32 Debug&quot; target of the Visual Studio project in the
+PCBuild subdirectory of a full Python source code distribution.
+You may also find</td></tr>
+</tbody>
+</table>
 </div>
 </div>
 <div class="footer">
 <hr class="footer" />
-<a class="reference external" href="./building.rst">View document source</a>.
-Generated on: 2007-05-01 15:33 UTC.
-Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
+<a class="reference" href="./building.rst">View document source</a>.
+Generated on: 2007-05-04 00:01 UTC.
+Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
 
 </div>
 </body>
diff --git a/doc/building.rst b/doc/building.rst
index a08fbd87..af15470e 100644
--- a/doc/building.rst
+++ b/doc/building.rst
@@ -169,6 +169,15 @@ you invoke it, to make sure that Boost.Build is correctly locating
 all the parts of your Python installation.  If it isn't, consider
 `Configuring Boost.Build`_ as detailed below.
 
+If you're still having trouble, Someone on one of the following
+mailing lists may be able to help:
+
+* The `Boost.Build mailing list`__ for issues related to Boost.Build
+* The Python `C++ Sig`__ for issues specifically related to Boost.Python
+
+__ ../../../more/mailing_lists.htm#jamboost
+__ ../../../more/mailing_lists.htm#cplussig
+
 In Case Everything Seemed to Work
 ---------------------------------
 
@@ -409,10 +418,12 @@ extension-suffix
   don't need to use this.  Usually this suffix is only used when
   targeting a Windows debug build of Python, and will be set
   automatically for you based on the value of the
-  ``<python-debugging>`` feature.  However, at least one Linux
+  |python-debugging|_ feature.  However, at least one Linux
   distribution (Ubuntu Feisty Fawn) has a specially configured
   `python-dbg`__ package that claims to use such a suffix.
 
+.. |python-debugging| replace:: ``<python-debugging>``
+
 __ https://wiki.ubuntu.com/PyDbgBuilds
 
 
@@ -454,6 +465,17 @@ significant.
          : <toolset>intel # condition
          ;
 
+
+- If you have downloaded the Python sources and built both the
+  normal and the “\ `python debugging`_\ ” builds from source on
+  Windows, you might see::
+
+    using python : 2.5 : C:\\src\\Python-2.5\\PCBuild\\python ;
+    using python : 2.5 : C:\\src\\Python-2.5\\PCBuild\\python_d
+      : # includes
+      : # libs
+      : <python-debugging>on ;
+
 - You can set up your user-config.jam so a bjam built under Windows 
   can build/test both Windows and Cygwin_ python extensions.  Just pass
   ``<target-os>cygwin`` in the ``condition`` parameter
@@ -539,14 +561,63 @@ any of the following cases:
     use the types exposed by your statically-linked extension
     modules (and vice-versa).
 
+``#include`` Issues
+===================
+
+1. If you should ever have occasion to ``#include "python.h"``
+   directly in a translation unit of a program using Boost.Python,
+   use ``#include "boost/python/detail/wrap_python.hpp"`` instead.
+   It handles several issues necessary for use with Boost.Python,
+   one of which is mentioned in the next section.
+
+2. Be sure not to ``#include`` any system headers before
+   ``wrap_python.hpp``.  This restriction is actually imposed by
+   Python, or more properly, by Python's interaction with your
+   operating system.  See
+   http://docs.python.org/ext/simpleExample.html for details.
+
+.. _python-debugging:
+.. _python debugging:
+
+Python Debugging Builds
+=======================
+
+Python can be built in a special “python debugging” configuration
+that adds extra checks and instrumentation that can be very useful
+for developers of extension modules.  The data structures used by
+the debugging configuration contain additional members, so **a
+Python executable built with python debugging enabled cannot be
+used with an extension module or library compiled without it, and
+vice-versa.**
+
+Since pre-built “python debugging” versions of the Python
+executable and libraries are not supplied with most distributions
+of Python, [#get-debug-build] and we didn't want to force our users
+to build them, Boost.Build does not automatically enable python
+debugging in its ``debug`` build variant (which is the default).
+Instead there is a special build property called
+``python-debugging`` that, when used as a build property, will
+define the right preprocessor symbols and select the right
+libraries to link with.
+
+On unix-variant platforms, the debugging versions of Python's data
+structures will only be used if the symbol ``Py_DEBUG`` is defined.
+On many windows compilers, when extension modules are built with
+the preprocessor symbol ``_DEBUG``, Python defaults to force
+linking with a special debugging version of the Python DLL.  Since
+that symbol is very commonly used even when Python is not present,
+Boost.Python temporarily undefines _DEBUG when Python.h
+is #included from ``boost/python/detail/wrap_python.hpp`` - unless
+``BOOST_DEBUG_PYTHON`` is defined.  The upshot is that if you want
+“python debugging”and you aren't using Boost.Build, you should make
+sure ``BOOST_DEBUG_PYTHON`` is defined, or python debugging will be
+suppressed.
+
 Testing Boost.Python
 ====================
 
-
-Python Debug Builds
-===================
-
-
+To run the full test suite for Boost.Python, invoke ``bjam`` in the
+``libs/python/test`` subdirectory of your Boost distribution.
 
 Notes for MinGW (and Cygwin with -mno-cygwin) GCC Users
 =======================================================
@@ -586,8 +657,8 @@ __ http://www.python.org/doc/current/inst/index.html
    that feature.
 
 .. [#toolset-specific] Because of the way most \*nix platforms
-   share symbols among dynamically-loaded objects, I'm not
-   certainextension modules built with different compiler toolsets
+   share symbols among dynamically-loaded objects, I'm not certain
+   that extension modules built with different compiler toolsets
    will always use different copies of the Boost.Python library
    when loaded into the same Python instance.  Not using different
    libraries could be a good thing if the compilers have compatible
@@ -614,3 +685,10 @@ __ http://www.python.org/doc/current/inst/index.html
 
    into a `command prompt`_ window.
 
+.. [#get-debug-build] On Unix and similar platforms, a debugging
+   python and associated libraries are built by adding
+   ``--with-pydebug`` when configuring the Python build. On
+   Windows, the debugging version of Python is generated by
+   the "Win32 Debug" target of the Visual Studio project in the
+   PCBuild subdirectory of a full Python source code distribution.
+   You may also find
\ No newline at end of file
diff --git a/example/Attic/project.zip b/example/Attic/project.zip
deleted file mode 100644
index d863defd..00000000
Binary files a/example/Attic/project.zip and /dev/null differ
diff --git a/example/Jamfile.v2 b/example/Jamfile.v2
deleted file mode 100644
index a8e6e966..00000000
--- a/example/Jamfile.v2
+++ /dev/null
@@ -1,36 +0,0 @@
-# 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)
-
-project : requirements <library>/boost/python//boost_python ;
-    
-python-extension getting_started1 : getting_started1.cpp ;
-
-bpl-test test1 
-    :  # Python test driver
-    test_getting_started1.py
-    # extension modules to use
-    getting_started1 ;
-
-
-python-extension getting_started2 : getting_started2.cpp ;
-
-bpl-test test2
-    :  # Python test driver
-    test_getting_started2.py
-    # extension modules to use
-    getting_started2 ;    
-
-python-extension std_pair : std_pair.cpp ;
-
-bpl-test test3
-    :  # Python test driver
-    test_std_pair.py
-    # extension modules to use
-    std_pair_ext ;
-    
-# Don't run tests by default
-explicit test1 test2 test3 ;
-alias test : test1 test2 test3 ;
-explicit test ;
-
diff --git a/example/Jamrules b/example/Jamrules
deleted file mode 100755
index f9c1e3c3..00000000
--- a/example/Jamrules
+++ /dev/null
@@ -1,36 +0,0 @@
-# Copyright David Abrahams 2003. See accompanying LICENSE for terms
-# and conditions of use.
-
-# If you move this example from its place in the Boost tree, edit this
-# path to point at the root directory of your Boost installation (the
-# one containing a subdirectory called "boost/" and a sub-subdirectory
-# "boost/python/" full of .hpp files).  Absolute paths work, too.
-#
-path-global BOOST_ROOT : ../../.. ;
-
-# Boost.Python configuration variables, as described in
-# http://www.boost.org/libs/python/doc/building.html#configuration.
-# Usually you don't need to set these; the defaults will work.  If you
-# do set them, try to change as few of them as possible, starting with
-# the first ones.
-
-  # PYTHON_VERSION = <the two-part Major.Minor version number, e.g. 2.2> ;
-  # PYTHON_ROOT = <root directory of your Python installation, e.g. /usr> ;
-  # PYTHON_INCLUDES = <path to Python #include directories> ;
-  # PYTHON_LIB_PATH = <path to Python library object> ;
-
-# You may need to configure your compiler toolset, especially if you
-# want to build with a compiler that is not the "system default" or if
-# it is installed in a nonstandard place; see
-# http://www.boost.org/more/getting_started.html#Configuring for
-# details.  
-
-# Makes a project id for boost so that other Boost.Build projects can
-# refer to it by name.
-#
-project boost : $(BOOST_ROOT) ;
-
-# Change this setting to have all your built products placed under a
-# single directory:
-#
-# ALL_LOCATE_TARGET = <root directory for all built products>
diff --git a/example/quickstart/Jamroot b/example/quickstart/Jamroot
new file mode 100755
index 00000000..e514941d
--- /dev/null
+++ b/example/quickstart/Jamroot
@@ -0,0 +1,33 @@
+# 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)
+
+# Specify the path to the Boost project.  If you move this project,
+# adjust the path to refer to the Boost root directory.
+use-project boost 
+  : ../../../.. ;
+
+# Set up the project-wide requirements that everything uses the
+# boost_python library defined in the project whose global ID is
+# /boost/python.
+project
+  : requirements <library>/boost/python//boost_python ;
+
+# Declare a Python extension called hello.
+python-extension extending : extending.cpp ;
+
+# Declare an executable called embedding that embeds Python
+exe embedding : embedding.cpp /python//python ;
+
+import testing ;
+
+# Declare a test of the extension module
+testing.make-test run-pyd : extending test_extending.py : : test_ext ;
+
+# Declare a test of the embedding application
+testing.run embedding 
+  :              # any ordinary arguments
+  : script.py    # any arguments that should be treated as relative paths
+  :              # requirements
+  : test_embed ; # name of test
+
diff --git a/example/quickstart/boost-build.jam b/example/quickstart/boost-build.jam
new file mode 100644
index 00000000..a440ea9f
--- /dev/null
+++ b/example/quickstart/boost-build.jam
@@ -0,0 +1,7 @@
+# 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)
+
+# Edit this path to point at the tools/build/v2 subdirectory of your
+# Boost installation.  Absolute paths work, too.
+boost-build ../../../../tools/build/v2 ;
diff --git a/example/quickstart/embedding.cpp b/example/quickstart/embedding.cpp
new file mode 100644
index 00000000..65bcd16a
--- /dev/null
+++ b/example/quickstart/embedding.cpp
@@ -0,0 +1,154 @@
+// Copyright Stefan Seefeld 2005.
+// 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)
+
+#include <boost/python.hpp>
+
+#include <boost/detail/lightweight_test.hpp>
+#include <iostream>
+
+namespace python = boost::python;
+
+// An abstract base class
+class Base : public boost::noncopyable
+{
+public:
+  virtual ~Base() {};
+  virtual std::string hello() = 0;
+};
+
+// C++ derived class
+class CppDerived : public Base
+{
+public:
+  virtual ~CppDerived() {}
+  virtual std::string hello() { return "Hello from C++!";}
+};
+
+// Familiar Boost.Python wrapper class for Base
+struct BaseWrap : Base, python::wrapper<Base>
+{
+  virtual std::string hello() 
+  {
+#if BOOST_WORKAROUND(BOOST_MSVC, <= 1300)
+    // workaround for VC++ 6.x or 7.0, see
+    // http://boost.org/libs/python/doc/tutorial/doc/html/python/exposing.html#python.class_virtual_functions
+    return python::call<std::string>(this->get_override("hello").ptr());
+#else
+    return this->get_override("hello")();
+#endif
+  }
+};
+
+// Pack the Base class wrapper into a module
+BOOST_PYTHON_MODULE(embedded_hello)
+{
+  python::class_<BaseWrap, boost::noncopyable> base("Base");
+}
+
+
+void exec_test()
+{
+    std::cout << "registering extension module embedded_hello..." << std::endl;
+    
+  // Register the module with the interpreter
+  if (PyImport_AppendInittab("embedded_hello", initembedded_hello) == -1)
+    throw std::runtime_error("Failed to add embedded_hello to the interpreter's "
+                 "builtin modules");
+
+  std::cout << "defining Python class derived from Base..." << std::endl;
+  
+  // Retrieve the main module
+  python::object main = python::import("__main__");
+  
+  // Retrieve the main module's namespace
+  python::object global(main.attr("__dict__"));
+
+  // Define the derived class in Python.
+  python::object result = python::exec(
+    "from embedded_hello import *        \n"
+    "class PythonDerived(Base):          \n"
+    "    def hello(self):                \n"
+    "        return 'Hello from Python!' \n",
+    global, global);
+
+  python::object PythonDerived = global["PythonDerived"];
+
+  // Creating and using instances of the C++ class is as easy as always.
+  CppDerived cpp;
+  BOOST_TEST(cpp.hello() == "Hello from C++!");
+
+  std::cout << "testing derived class from C++..." << std::endl;
+  
+  // But now creating and using instances of the Python class is almost
+  // as easy!
+  python::object py_base = PythonDerived();
+  Base& py = python::extract<Base&>(py_base) BOOST_EXTRACT_WORKAROUND;
+
+  // Make sure the right 'hello' method is called.
+  BOOST_TEST(py.hello() == "Hello from Python!");
+
+  std::cout << "success!" << std::endl;
+}
+
+void exec_file_test(std::string const &script)
+{
+    std::cout << "running file " << script << "..." << std::endl;
+    
+    // Run a python script in an empty environment.
+    python::dict global;
+    python::object result = python::exec_file(script.c_str(), global, global);
+
+    // Extract an object the script stored in the global dictionary.
+    BOOST_TEST(python::extract<int>(global["number"]) ==  42);
+    
+    std::cout << "success!" << std::endl;
+}
+
+void exec_test_error()
+{
+    std::cout << "intentionally causing a python exception..." << std::endl;
+    
+    // Execute a statement that raises a python exception.
+    python::dict global;
+    python::object result = python::exec("print unknown \n", global, global);
+
+    std::cout << "Oops! This statement should be skipped due to an exception" << std::endl;
+}
+
+int main(int argc, char **argv)
+{
+  BOOST_TEST(argc == 2);
+  std::string script = argv[1];
+  // Initialize the interpreter
+  Py_Initialize();
+
+  bool error_expected = false;
+  
+  if (
+      python::handle_exception(exec_test)
+      || python::handle_exception(boost::bind(exec_file_test, script))
+      || (
+          (error_expected = true)
+          && python::handle_exception(exec_test_error)
+      )
+
+  )
+  {
+    if (PyErr_Occurred())
+    {
+        if (!error_expected)
+            BOOST_ERROR("Python Error detected");
+        PyErr_Print();
+    }
+    else
+    {
+        BOOST_ERROR("A C++ exception was thrown  for which "
+                    "there was no exception translator registered.");
+    }
+  }
+  
+  // Boost.Python doesn't support Py_Finalize yet, so don't call it!
+  return boost::report_errors();
+}
diff --git a/example/quickstart/extending.cpp b/example/quickstart/extending.cpp
new file mode 100644
index 00000000..a539d3b4
--- /dev/null
+++ b/example/quickstart/extending.cpp
@@ -0,0 +1,41 @@
+// Copyright Ralf W. Grosse-Kunstleve 2002-2004. 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)
+
+#include <boost/python/class.hpp>
+#include <boost/python/module.hpp>
+#include <boost/python/def.hpp>
+#include <iostream>
+#include <string>
+
+namespace { // Avoid cluttering the global namespace.
+
+  // A friendly class.
+  class hello
+  {
+    public:
+      hello(const std::string& country) { this->country = country; }
+      std::string greet() const { return "Hello from " + country; }
+    private:
+      std::string country;
+  };
+
+  // A function taking a hello object as an argument.
+  std::string invite(const hello& w) {
+    return w.greet() + "! Please come soon!";
+  }
+}
+
+BOOST_PYTHON_MODULE(extending)
+{
+    using namespace boost::python;
+    class_<hello>("hello", init<std::string>())
+        // Add a regular member function.
+        .def("greet", &hello::greet)
+        // Add invite() as a member of hello!
+        .def("invite", invite)
+        ;
+    
+    // Also add invite() as a regular function to the module.
+    def("invite", invite);
+}
diff --git a/example/quickstart/script.py b/example/quickstart/script.py
new file mode 100644
index 00000000..5a8faf79
--- /dev/null
+++ b/example/quickstart/script.py
@@ -0,0 +1,6 @@
+# Copyright Stefan Seefeld 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)
+
+print 'Hello World !'
+number = 42
diff --git a/example/quickstart/test_extending.py b/example/quickstart/test_extending.py
new file mode 100644
index 00000000..14616f7c
--- /dev/null
+++ b/example/quickstart/test_extending.py
@@ -0,0 +1,36 @@
+# Copyright Ralf W. Grosse-Kunstleve 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)
+
+# Using the doctest module here to ensure that the results are as expected.
+r'''>>> from extending import *
+    >>> hi = hello('California')
+    >>> hi.greet()
+    'Hello from California'
+    >>> invite(hi)
+    'Hello from California! Please come soon!'
+    >>> hi.invite()
+    'Hello from California! Please come soon!'
+
+    >>> class wordy(hello):
+    ...     def greet(self):
+    ...         return hello.greet(self) + ', where the weather is fine'
+    ...
+    >>> hi2 = wordy('Florida')
+    >>> hi2.greet()
+    'Hello from Florida, where the weather is fine'
+    >>> invite(hi2)
+    'Hello from Florida! Please come soon!'
+'''
+
+def run(args = None):
+    if args is not None:
+        import sys
+        sys.argv = args
+    import doctest, test_extending
+    return doctest.testmod(test_extending, verbose=True)
+
+if __name__ == '__main__':
+    import sys
+    sys.exit(run()[0])
+
