shelllet
diff --git a/‎doc/PyConDC_2003/bpl.txt‎
Lines changed: 946 additions & 4 deletions b/‎doc/PyConDC_2003/bpl.txt‎
Lines changed: 946 additions & 4 deletions
diff --git a/‎doc/building.qbk‎
Lines changed: 49 additions & 46 deletions b/‎doc/building.qbk‎
Lines changed: 49 additions & 46 deletions
diff --git a/‎doc/configuration.qbk‎
Lines changed: 3 additions & 3 deletions b/‎doc/configuration.qbk‎
Lines changed: 3 additions & 3 deletions
diff --git a/‎doc/faq.qbk‎
Lines changed: 19 additions & 20 deletions b/‎doc/faq.qbk‎
Lines changed: 19 additions & 20 deletions
@@ -54,7 +54,7 @@ modules or the executable containing `main()`.
 [section No-Install Quickstart]
 
 There is no need to “install Boost” in order to get started using
-Boost.Python.  These instructions use [@http://boost.org/build] projects,
+Boost.Python.  These instructions use _bb_ 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
@@ -69,9 +69,9 @@ compiler options to use yourself.
    build system* without first following these instructions.
 
    If you want to use another system anyway, we suggest that you
-   follow these instructions, and then invoke ``bjam`` with the
+   follow these instructions, and then invoke `bjam` with the
 
-   `-a -o`\ *filename* 
+   `-a -o`\ /filename/ 
 
    options to dump the build commands it executes to a file, so
    you can see what your alternate build system needs to do.]
@@ -91,19 +91,19 @@ compiler options to use yourself.
    to see the output generated by the tests when they are run.
    On Windows, your `bjam` invocation might look something like:
    ``
-     C:\\boost_1_34_0\\...\\quickstart> bjam toolset=msvc --verbose-test test
+     C:\\...\\quickstart> bjam toolset=msvc --verbose-test test
    ``
    and on Unix variants, perhaps,
    ``
-     ~/boost_1_34_0/.../quickstart$ bjam toolset=gcc --verbose-test test
+     .../quickstart$ bjam toolset=gcc --verbose-test test
    ``
 
 [note For the sake of concision, the rest of this guide will use
    unix-style forward slashes in pathnames instead of the
    backslashes with which Windows users may be more familiar.  The forward
    slashes should work everywhere except in
-   [@http://www.boost.org/more/getting_started/windows.html#command-prompt Command Prompt windows],
-   where you should use backslashes.]
+   [@http://www.boost.org/more/getting_started/windows.html#command-prompt
+   Command Prompt] windows, where you should use backslashes.]
 
 If you followed this procedure successfully, you will have built an
 extension module called `extending` and tested it by running a
@@ -178,11 +178,11 @@ For example, if you moved the project from
 `/home/dave/my-project`, you could change the first path in
 `boost-build.jam` from
 ``
-  ../../../../tools/build/v2
+  ../../../../tools/build/src
 ``
 to
 ``
-  /home/dave/boost_1_34_0/tools/build/v2
+  /home/dave/boost_1_34_0/tools/build/src
 ``
 and change the first path in `Jamroot` from
 ``
@@ -212,8 +212,8 @@ tell Boost.Build about it by editing the name in `Jamroot`.
 
 The name of the extension module is determined by two things:
 
-1. the name in `Jamroot` immediately following `python-extension`, and 
-2. the name passed to ``BOOST_PYTHON_MODULE`` in `extending.cpp`.
+# the name in `Jamroot` immediately following `python-extension`, and 
+# the name passed to `BOOST_PYTHON_MODULE` in `extending.cpp`.
 
 To change the name of the extension module from `extending` to
 `hello`, you'd edit `Jamroot`, changing
@@ -235,6 +235,7 @@ to
 ``
 [endsect]
 [endsect]
+[endsect]
 [section Installing Boost.Python on your System]
 
 Since Boost.Python is a separately-compiled (as opposed to
@@ -252,7 +253,7 @@ rather than all the Boost binaries.
 [endsect]
 [section Configuring Boost.Build]
 
-As described in the _reference_, a file called
+As described in the [@http://www.boost.org/build/doc/html/bbv2/overview/configuration.html Boost.Build Reference Manual], a file called
 `user-config.jam` in your home directory is used to
 specify the tools and libraries available to the build system. You
 may need to create or edit `user-config.jam` to tell Boost.Build
@@ -284,59 +285,60 @@ method).  If instead you are linking against separately-compiled
 Boost.Python binaries, you should set up a `user-config.jam` file
 with at least the minimal incantation above.
 
-[endsect]
 [section Python Configuration Parameters]
 
 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 `using python`.
 
-* *version*
+[variablelist
+ [[version]
 
-  the version of Python to use.  Should be in Major.Minor
+  [the version of Python to use.  Should be in Major.Minor
   format, for example, `2.3`.  Do not include the subminor
   version (i.e. *not* `2.5.1`).  If you have multiple Python
   versions installed, the version will usually be the only
-  configuration argument required.
+  configuration argument required.]]
 
-* *cmd-or-prefix*
+ [[cmd-or-prefix]
 
-  preferably, a command that invokes a Python interpreter.
+  [preferably, a command that invokes a Python interpreter.
   Alternatively, the installation prefix for Python libraries and
   header files.  Only use the alternative formulation if there is
-  no appropriate Python executable available.
+  no appropriate Python executable available.]]
 
-* *includes*
+ [[*includes*]
 
-  the `#include` paths for Python headers.  Normally the correct
+  [the `#include` paths for Python headers.  Normally the correct
   path(s) will be automatically deduced from `version` and/or
-  `cmd-or-prefix`.  
+  `cmd-or-prefix`.]]
 
-* *libraries*
+ [[*libraries*]
 
-  the path to Python library binaries.  On MacOS/Darwin,
+  [the path to Python library binaries.  On MacOS/Darwin,
   you can also pass the path of the Python framework.  Normally the
   correct path(s) will be automatically deduced from `version`
-  and/or `cmd-or-prefix`. 
+  and/or `cmd-or-prefix`.]]
 
-* *condition*
+ [[*condition*]
 
-  if specified, should be a set of Boost.Build
+  [if specified, should be a set of Boost.Build
   properties that are matched against the build configuration when
   Boost.Build selects a Python configuration to use.  See examples
-  below for details.
+  below for details.]]
 
-* *extension-suffix*
+ [[*extension-suffix*]
 
-  A string to append to the name of extension
+  [A string to append to the name of extension
   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
-  |python-debugging|_ feature.  However, at least one Linux
-  distribution (Ubuntu Feisty Fawn) has a specially configured
-  [@https://wiki.ubuntu.com/PyDbgBuilds <python-debugging>] package
-  that claims to use such a suffix.
+  [link building.python_debugging_builds <python-debugging>] feature.
+  However, at least one Linux distribution (Ubuntu Feisty Fawn) has
+  a specially configured [@https://wiki.ubuntu.com/PyDbgBuilds <python-dbg>]
+  package that claims to use such a suffix.]]
+  ]
 
 [endsect]
 [section Examples]
@@ -381,8 +383,8 @@ significant.
   ``
 
 * If you have downloaded the Python sources and built both the
-  normal and the “\ `python debugging`_\ ” builds from source on
-  Windows, you might see:
+  normal and the [link building.python_debugging_builds "python debugging"]
+  builds from source on Windows, you might see:
 
   ``
     using python : 2.5 : C:\\src\\Python-2.5\\PCBuild\\python ;
@@ -443,8 +445,8 @@ 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. [footnote
 Information about how to identify the static and dynamic builds of Boost.Python on
-[@http://boost.org/getting_started/windows.html#library-naming Windows] /
-[@http://boost.org/getting_started/unix-variants.html#library-naming Unix variants]]
+[@http://boost.org/more/getting_started/windows.html#library-naming Windows] /
+[@http://boost.org/more/getting_started/unix-variants.html#library-naming Unix variants]]
 
 [section The Dynamic Binary]
 
@@ -475,12 +477,12 @@ The dynamic library is the safest and most-versatile choice:
 It might be appropriate to use the static Boost.Python library in
 any of the following cases:
 
-* You are extending python and the types exposed in your
+* You are _extending_ 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.
 
-* You are embedding python in your application and either:
+* You are _embedding_ python in your application and either:
 
   * You are targeting a Unix variant OS other than MacOS or AIX,
     where the dynamically-loaded extension modules can “see” the
@@ -506,7 +508,7 @@ any of the following cases:
    `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.
+   [@http://docs.python.org/ext/simpleExample.html] for details.
 
 [endsect]
 [section Python Debugging Builds]
@@ -521,7 +523,7 @@ 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
+of Python, [footnote 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.] 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
@@ -535,7 +537,7 @@ 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
+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
@@ -556,8 +558,9 @@ 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 [@http://www.python.org/doc/current/inst/index.html Installing Python Modules] to create `libpythonXX.a`, where `XX`
-corresponds to the major and minor version numbers of your Python
-installation.
+the “Building Extensions: Tips And Tricks” chapter in
+[@https://docs.python.org/2/install/index.html Installing Python Modules]
+to create `libpythonXX.a`, where `XX` corresponds to the major and minor
+version numbers of your Python installation.
 
 [endsect]
@@ -9,12 +9,12 @@
 [section Configuration]
 
 [section Introduction]
-*Boost.Python* uses several configuration macros in `<boost/config.hpp>`, as well as configuration macros meant to be supplied by the application. These macros are documented here.
+[*Boost.Python] uses several configuration macros in `<boost/config.hpp>`, as well as configuration macros meant to be supplied by the application. These macros are documented here.
 
 [endsect]
 [section Application Defined Macros]
 
-These are the macros that may be defined by an application using Boost.Python. Note that if you extend a strict interpretation of the C++ standard to cover dynamic libraries, using different values of these macros when compiling different libraries (including extension modules and the Boost.Python library itself) is a violation of the ODR. However, we know of no C++ implementations on which this particular violation is detectable or causes any problems.
+These are the macros that may be defined by an application using Boost.Python. Note that if you extend a strict interpretation of the C++ standard to cover dynamic libraries, using different values of these macros when compiling different libraries (including extension modules and the Boost.Python library itself) is a violation of the [link odr ODR]. However, we know of no C++ implementations on which this particular violation is detectable or causes any problems.
 
 [table
  [[Macro][Default][Meaning]]
@@ -49,7 +49,7 @@ These are the macros that may be defined by an application using Boost.Python. N
 ]
 [endsect]
 [section Library Defined Defined Macros]
-
+These macros are defined by *Boost.Python* and are implementation details of interest only to implementors and those porting to new platforms.
 [table
  [[Macro][Default][Meaning]]
  [[BOOST_PYTHON_TYPE_ID_NAME][ /not defined/ ]
 
@@ -1,4 +1,4 @@
-[chapter FAQ
+[chapter Frequently Asked Questions (FAQs)
     [quickbook 1.7]
     [id faq]
 ]
@@ -79,25 +79,24 @@ situation at runtime and helpfully throws an exception instead of letting
 you do that.
 
 [endsect]
-[section Is return_internal_reference efficient?]
+[section Is `return_internal_reference` efficient?]
 
-[*Q:] /I have an object composed of 12 doubles. A const& to
+[*Q:] /I have an object composed of 12 doubles. A `const&` to
 this object is returned by a member function of another class. From the
 viewpoint of using the returned object in Python I do not care if I get
-a copy or a reference to the returned object. In Boost.Python Version 2
-I have the choice of using copy_const_reference or
-return_internal_reference. Are there considerations that would lead me
-to prefer one over the other, such as size of generated code or memory
-overhead?/
+a copy or a reference to the returned object. In Boost.Python I have the
+choice of using `copy_const_reference` or `return_internal_reference`.
+Are there considerations that would lead me to prefer one over the other,
+such as size of generated code or memory overhead?/
 
 [*A:] `copy_const_reference` will make an instance with storage
-for one of your objects, size = base_size + 12 * sizeof(double).
-return_internal_reference will make an instance with storage for a
-pointer to one of your objects, size = base_size + sizeof(void*).
+for one of your objects, `size = base_size + 12 * sizeof(double)`.
+`return_internal_reference` will make an instance with storage for a
+pointer to one of your objects, `size = base_size + sizeof(void*)`.
 However, it will also create a weak reference object which goes in the
 source object's weakreflist and a special callback object to manage the
 lifetime of the internally-referenced object. My guess?
-copy_const_reference is your friend here, resulting in less overall
+`copy_const_reference` is your friend here, resulting in less overall
 memory use and less fragmentation, also probably fewer total
 cycles.
 
@@ -113,8 +112,8 @@ Ralf W. Grosse-Kunstleve provides these notes:
       ...
     ;
   ``
-  This can be moved to a template so that several types (double, int,
-  long, etc.) can be wrapped with the same code. This technique is used
+  This can be moved to a template so that several types (`double`, `int`,
+  `long`, etc.) can be wrapped with the same code. This technique is used
   in the file `scitbx/include/scitbx/array_family/boost_python/flex_wrapper.h`
   in the "scitbx" package. The file could easily be modified for
   wrapping `std::vector<>` instantiations.
@@ -157,7 +156,7 @@ C++:
     }
   }
 ``
-Python:
+Python: [python]
 ``
   >>> l = [1, 2, 3]
   >>> foo(l)
@@ -187,7 +186,7 @@ CVS:
 
 # Break your source file up into multiple translation units.
 
-  `my_module.cpp`:
+  `my_module.cpp`: [c++]
 
   ``
     ...
@@ -208,7 +207,7 @@ CVS:
       ...
     }
   ``
-  If you find that a [link reference.class-spec class_]<...> declaration
+  If you find that a `class_<...>` declaration
   can't fit in a single source file without triggering the error, you
   can always pass a reference to the `class_` object to a
   function in another source file, and call some of its member
@@ -522,20 +521,20 @@ Then make a thin wrapper function which takes an auto_ptr parameter:
     a.release();
   }
 ``
-Wrap that as B.add. Note that pointers returned via [link reference.manage_new_object manage_new_object]
+Wrap that as B.add. Note that pointers returned via `manage_new_object`
 will also be held by `auto_ptr`, so this transfer-of-ownership
 will also work correctly.
 
 [endsect]
 [section Compilation takes too much time and eats too much memory!
  What can I do to make it faster?]
 
-Please refer to the [link tutorial.python.reducing_compiling_time Reducing Compiling Time] section in the tutorial.
+Please refer to the `Reducing Compiling Time` section in the _tutorial_.
 
 [endsect]
 [section How do I create sub-packages using Boost.Python?]
 
-Please refer to the [link tutorial.python.creating_packages Creating Packages] section in the tutorial.
+Please refer to the `Creating Packages` section in the _tutorial_.
 
 [endsect]
 [section error C2064: term does not evaluate to a function taking 2 arguments]