From 6e1e12c7b72177b53da196be8b70c8e79dc2a2b8 Mon Sep 17 00:00:00 2001
From: Dave Abrahams <dave@boostpro.com>
Date: Tue, 6 Jul 2004 10:05:32 +0000
Subject: [PATCH] Cleanups

[SVN r23366]
---
 v2/doc/src/howto.xml    |   7 +-
 v2/doc/src/install.xml  | 113 ++++++++++++++++---------
 v2/doc/src/tutorial.xml | 179 ++++++++++++++++++++++++++--------------
 3 files changed, 193 insertions(+), 106 deletions(-)

diff --git a/v2/doc/src/howto.xml b/v2/doc/src/howto.xml
index dcb44670f..109d77d63 100644
--- a/v2/doc/src/howto.xml
+++ b/v2/doc/src/howto.xml
@@ -26,8 +26,11 @@
     </para>
 
     <para>
-      Finally, if nothing applies to you, write to our mailing list,
-      telling what information you'd like to know.
+      If you have questions, please post them to our <ulink
+      url="../../../../more/mailing_lists.htm#jamboost">mailing
+      list</ulink>, and be sure to indicate in the subject line that
+      you're asking about Boost.Build <emphasis
+      role="bold">V2</emphasis>.
     </para>
 
   </chapter>
diff --git a/v2/doc/src/install.xml b/v2/doc/src/install.xml
index d164a5907..fc7e18c77 100644
--- a/v2/doc/src/install.xml
+++ b/v2/doc/src/install.xml
@@ -6,54 +6,81 @@
     <title>Installation</title>
 
     <para>
-      Assuming you're installing Boost.Build from released source
-      distribution, the following steps are needed. All paths are
-      given relatively to Boost.Build root directory, which is the
-      directory with the document you are reading.
+      This section describes how to install Boost.Build from a
+      released source distribution. All paths are given relative to
+      the <firstterm>Boost.Build v2 root directory</firstterm>, which is 
+
+      <!-- the normal location of the document you are reading.
+      Boost.Build is -->
+
+      <!-- That is a lie AFAICT, at least in a Boost distro.  You need
+      to say something that will be true if you want to cover BBv2 as
+      distributed separately -->
+
+      located in the <filename>tools/build/v2</filename> subdirectory
+      of a full <ulink url="http://www.boost.org">Boost</ulink>
+      distribution.
     </para>
 
     <orderedlist>
       <listitem>
         <simpara>
-          Go to "jam_src" directory and build Boost.Jam. Two convenient
-          scripts are provided, "build.sh" (for Unix systems) and
-          "build.bat" (for Windows). Run the appropriate one and
-          Boost.Jam will be built to directory
-          <filename>bin.{platform_name}.</filename>. The <ulink url=
-          "../jam_src/index.html">Boost.Jam documentation</ulink> has
-          more details in case you need them.
+          Boost.Build uses <ulink
+          url= "../jam_src/index.html">Boost.Jam</ulink>, an
+          extension of the <ulink
+          url="http://www.perforce.com/jam/jam.html">Perforce
+          Jam</ulink> portable <command>make</command> replacement. The
+          recommended way to get Boost.Jam is to <emphasis
+          role="bold"><ulink
+          url= "http://sourceforge.net/project/showfiles.php?group_id=7586&amp;package_id=72941">download
+          a prebuilt executable</ulink></emphasis> from SourceForge.
+          If a prebuilt executable is not provided for your platform
+          or you are using Boost's sources in an unreleased state, it
+          may be neccessary to <ulink
+          url= "../../jam_src/index.html#building_bjam">build <command>bjam</command>
+          from sources</ulink> included in the Boost source tree.
         </simpara>
       </listitem>
 
       <listitem>
         <para>
-          Place the Boost.Jam binary, called "bjam" or "bjam.exe",
-          somewhere in your <envar>PATH</envar>. Go to the root
-          directory of Boost.Build and run "bjam --version". You should
-          get 
 
-          <screen>Boost.Build V2 (Milestone N)</screen>
+          To install Boost.Jam, copy the executable,
+          called <command>bjam</command>
+          or <command>bjam.exe</command> to a location accessible in
+          your <envar>PATH</envar>.  Go to the Boost.Build root
+          directory and
+          run <command>bjam <option>--version</option></command>. You
+          should see:
 
-          (where N is the version you've downloaded).
+          <screen>
+            Boost.Build V2 (Milestone N)
+            Boost.Jam xx.xx.xx 
+          </screen>
+
+          where N is the version of Boost.Build you're using.
         </para>
       </listitem>
 
       <listitem>
         <simpara>
-          Configure toolsets to use. Open the
-          <filename>user-config.jam</filename> file and follow
-          instructions there to specify what compiles/libraries you
-          have and where they are located.
+          Configure Boost.Build to recognize the build resources (such
+          as compilers and libraries) you have installed on your
+          system.  Open the
+          <filename>user-config.jam</filename> file in the Boost.Build
+          root directory and follow the instructions there to describe
+          your toolsets and libraries, and, if neccessary, where they
+          are located.
         </simpara>
       </listitem>
 
       <listitem>
         <simpara>
-          You should now be able to go to
-          <filename>example/hello</filename>, and run
+          You should now be able to go to the
+          <filename>example/hello/</filename> directory and run
           <command>bjam</command> there. A simple application will be
-          built. You can also play with other projects in
-          <filename>example</filename>. 
+          built. You can also play with other projects in the
+          <filename>example/</filename> directory. 
     <!-- This part should not go into intoduction docs, but we need to
          place it somewhere. 
 
@@ -69,43 +96,47 @@
     </orderedlist>
 
     <para>
-      If you use Boost distribution, or Boost CVS, the Boost.Build
-      root is located at <filename>$boost_root/tools/build/v2</filename>
-      and the installation steps are the same. However, don't skip
-      the bjam rebuilding step, even if you have a previous version.
-      CVS version of Boost.Build requires CVS version of Boost.Jam.
+      If you are using Boost's CVS state, be sure to
+      rebuild <command>bjam</command> even if you have a previous
+      version.  The CVS version of Boost.Build requires the CVS
+      version of Boost.Jam.
     </para>
 
     <para>
-      When starting a new project which uses Boost.Build, you need
-      to make sure that build system can be found. There are two
-      ways.
+      When <command>bjam</command> is invoked, it always needs to be
+      able to find the Boost.Build root directory, where the
+      interpreted source code of Boost.Build is located.  There are
+      two ways to tell <command>bjam</command> about the root directory:
     </para>
 
     <itemizedlist>
       <listitem>
         <simpara>
-          Set enviromnetal variable <envar>BOOST_BUILD_PATH</envar>
-          to the absolute path to Boost.Build installation directory.
+          Set the environment variable <envar>BOOST_BUILD_PATH</envar>
+          to the absolute path of the Boost.Build root directory.
         </simpara>
       </listitem>
 
       <listitem>
         <para>
-          Create, at the top of your project, a file called
+          At the root directory of your project or in any of its
+          parent directories, create a file called
           <filename>boost-build.jam</filename>, with a single line:
 
 <programlisting>
-boost-build /path/to/boost.build ;
+boost-build <replaceable>/path/to/boost.build</replaceable> ;
 </programlisting>
 
         </para>
       </listitem>
     </itemizedlist>
 
-  <para>If you're trying to use Boost.Build V2 on Boost itself, please
-  note that when building Boost, V1 is used by default. You'd have
-  to add <option>--v2</option> command line option to all "bjam"
-  invocations.</para>
+  <para><emphasis role="bold">N.B.</emphasis>
+  When <command>bjam</command> is invokedfrom anywhere in the Boost
+  directory tree <emphasis>other than</emphasis> the Boost.Build root
+  and its subdirectories, <ulink url="../../tools/build">Boost.Build
+  v1</ulink> is used by default. To overide the default and use
+  Boost.Build v2, you have to add the <option>--v2</option> command
+  line option to all <command>bjam</command> invocations.</para>
 
   </chapter>
diff --git a/v2/doc/src/tutorial.xml b/v2/doc/src/tutorial.xml
index 7fb5ae4d0..03fc08b86 100644
--- a/v2/doc/src/tutorial.xml
+++ b/v2/doc/src/tutorial.xml
@@ -9,49 +9,56 @@
     <title>Hello, world</title>
 
     <para>The simplest project that Boost.Build can construct is
-    stored in example/hello directory. The targets are declared in
-    a file called <filename>Jamfile</filename>, which contains the
-    following:
+    stored in <filename>example/hello/</filename> directory. The
+    project is described by a file
+    called <filename>Jamfile</filename> that contains:
 
 <programlisting>
 exe hello : hello.cpp ;
 </programlisting>
 
       Even with this simple setup, you can do some interesting
-      things. First of all, running "bjam" would build binary "hello"
-      from hello.cpp, in debug version. After that, you can run
+      things. First of all, just invoking <command>bjam</command> will
+      build the debug variant of the <command>hello</command>
+      executable by compiling and
+      linking <filename>hello.cpp</filename>.  Now, to build the
+      release variant of <command>hello</command>, invoke
 
 <screen>
 bjam release
 </screen>
 
-      which would create release version of the 'hello' binary.
-      Note that debug and release version would be created in different
-      directories, so if you want to switch from debug to release
-      version and back, no recompilation is needed. Let's extend the
-      example by adding another line to Jamfile:
+      Note that debug and release variants are created in different
+      directories, so you can switch between variants or even build
+      multiple variants at once, without any unneccessary
+      recompilation. Let's extend the example by adding another line
+      to our project's <filename>Jamfile</filename>:
 
 <programlisting>
 exe hello2 : hello.cpp ;
 </programlisting>
 
-      You can now rebuild both debug and release versions:
+      Now we can build both the debug and release variants of our
+      project:
 
 <screen>
 bjam debug release
 </screen>
 
-      You'll see that two versions of "hello2" binary are linked.
-      Of course, hello.cpp won't be recompiled. Now you decide to remove
-      all build products. You do that with the following command
+      Note that two variants of <command>hello2</command> are linked.
+      Since we have already built both variants
+      of <command>hello</command>, hello.cpp won't be recompiled;
+      instead the existing object files will just be linked into the
+      corresponding variants of <command>hello2</command>. Now 
+      let's remove all the built products:
 
 <screen>
 bjam --clean debug release
 </screen>
 
-      It's also possible to create or clean only specific targets.
-      Both following commands are legal and create or clean only files
-      that belonging the the named binary:
+      It's also possible to build or clean specific targets.  The
+      following two commands, respectively, build or clean only the
+      debug version of <command>hello2</command>.
 
 <screen>
 bjam hello2
@@ -63,67 +70,112 @@ bjam --clean hello2
     <section id="bbv2.tutorial.properties">
       <title>Properties</title>
 
-  <para>Boost.Build attempts to allow building different variants of
-  projects, e.g. for debugging and release, or in single and
-  multithreaded mode. In order to stay portable, it uses the
-  concept of <emphasis>features</emphasis>, which is abstract aspect of
-  build configuration. <emphasis>Property</emphasis> is just a (feature,
-  value) pair. For example, there's a feature "debug-symbols", which can
-  have a value of "on" or "off". When users asks to build project is a
-  particual value, Boost.Build will automatically find the
-  appropriate flags to the used compiler.</para>
+  <para>
+    To portably represent aspects of target configuration such as
+    debug and release variants, or single- and multi-threaded
+    builds, Boost.Build uses <firstterm>features</firstterm> with
+    associated <firstterm>values</firstterm>.  For
+    example, the "debug-symbols" feature can have a value of "on" or
+    "off".  A <firstterm>property</firstterm> is just a (feature,
+    value) pair.  When a user initiates a build, Boost.Build
+    automatically translates the requested properties into appropriate
+    command-line flags for invoking toolset components like compilers
+    and linkers.</para>
 
-  <para>The "release" and "debug" in bjam invocation that we've seen
-  are just are short form of specifying values of feature
-  "variant". There is a lot of builtin features, and it's possible
-  to write something like:</para>
+  <para>There are many built-in features that can be combined to
+  produce arbitrary build configurations.  The following command
+  builds the project's &quot;release&quot; variant with inlining
+  disabled and debug symbols enabled:
 
 <screen>
 bjam release inlining=off debug-symbols=on
 </screen>
+</para>
 
-      <para>
-      The first command line element specified the value of feature
-      "variant". The feature is very common and is therefore special
-      &#x2014; it's possible to specify only value. Another feature,
-      "inlining" is not special, and you should use
+<para>Properties on the command-line are specified with the syntax:
 
 <screen>
-feature-name=feature-value
+<replaceable>feature-name</replaceable>=<replaceable>feature-value</replaceable>
 </screen>
+</para>
 
-      syntax for it. Complete description of features can be found
-      <link linkend="bbv2.reference.features">here</link>. The set of
-      properties specified in the command line constitute
-      <emphasis>build request</emphasis> &#x2014; the desired properties
-      for requested targets, or for the project in the current
-      directory. The actual set of properties used for building is
-      often different. For example, when compiling a program you need
-      some include paths. It's not reasonable to ask the user to specify
-      those paths with each bjam invocation, so must be specified in
-      Jamfile and added to the build request. For another example,
-      certain application can only be linked in multithreaded mode. To
-      support such situations, every target is allowed to specify
-      <emphasis>requirements</emphasis> -- properties that are required
-      to its building. Consider this example:
+<para>The "release" and "debug" that we've seen
+  in <command>bjam</command> invocations are just a shorthand way to
+  specify values of the "variant" feature.  For example, the command
+  above could also have been written this way:
+
+<screen>
+bjam variant=release inlining=off debug-symbols=on
+</screen>
+</para>
+
+<para>  &quot;variant&quot; is so commonly-used that it has been given
+  special status as an <firstterm>implicit</firstterm> feature
+  &#x2014; Boost.Build will deduce the its identity just from the name
+  of one of its values.  
+</para>
+
+<para>
+      A complete description of features can be found
+      <link linkend="bbv2.reference.features">here</link>. 
+</para>
+
+
+    <section id="bbv2.tutorial.properties.requirements">
+      <title>Build Requests and Target Requirements</title>
+
+<para>      
+      The set of properties specified in the command line constitute a
+      <firstterm>build request</firstterm> &#x2014; a description of
+      the desired properties for building the requested targets (or,
+      if no targets were explicitly requested, the project in the
+      current directory).  The <emphasis>actual</emphasis> properties
+      used for building targets is typically a combination of the
+      build request and properties derived from the
+      project's <filename>Jamfile</filename>s.  For example, the
+      locations of <code>#include</code>d header files are normally
+      not specified on the command-line, but described
+      in <filename>Jamfile</filename>s as <firstterm>target
+      requirements</firstterm> and automatically combined with the
+      build request for those targets.  Multithread-enabled
+      compilation is another example of a typical target requirement.
+      The <filename>Jamfile</filename> fragment below illustrates how
+      these requirements might be specified.
+</para>
 
 <programlisting>
 exe hello 
     : hello.cpp
     : &lt;include&gt;/home/ghost/Work/boost &lt;threading&gt;multi
+    ;
 </programlisting>
 
-    In this case, when hello is build, the two specified properties will
-    always be present. This leads to a question: what if user explictly
-    requested single-threading. The answer is that requirement can
-    affect build properties only to a certain degree: the requested and
-    actual properties must be link-compatible. See <xref linkend=
-    "bbv2.reference.variants.compat"/> below. If they are not link
-    compatible, the bulding of the target is skipped. Previously, we've
-    added "hello2" target. Seems like we have to specify the same
-    requirements for it, which results in duplication. But there's a
-    better way. Each project (i.e. each Jamfile), can specify a set of
-    attributes, including requirements:
+<para>    When <filename>hello</filename> is built, the two requirements
+    specified above will normally always be present.  If the build
+    request given on the <command>bjam</command> command-line
+    explictly contradicts a target's requirements, the command-line
+    usually overrides (or, in the case of &quot;free&quot; feautures
+    like <code>&lt;include&gt;</code>, augments) the target
+    requirements.  However, when a contradiction of a target's
+    requrements involves certain
+    <firstterm>link-incompatible</firstterm> features, the target will
+    be skipped.  See <xref linkend=
+    "bbv2.reference.variants.compat"/> for more information.
+</para>
+
+    </section>
+    <section id="bbv2.tutorial.properties.project_attributes">
+      <title>Project Attributes</title>
+
+<para>
+    If we want the same requirements for our other
+    target, <filename>hello2</filename>, we could simply duplicate
+    them.  However, as projects grow, that approach leads to a great
+    deal of repeated boilerplate in Jamfiles.
+    
+    Fortunately, there's a better way. Each project (i.e. each
+    <filename>Jamfile</filename>), can specify a set of attributes,
+    including requirements:
 
 <programlisting>
 project 
@@ -134,10 +186,11 @@ exe hello : hello.cpp ;
 exe hello2 : hello.cpp ;
 </programlisting>
 
-      The effect would be as if we specified this requirement for
-      both "hello" and "hello2".
+      The effect would be as if we specified the same requirement for
+      both <command>hello</command> and <command>hello2</command>.
       </para>
     </section>
+    </section>
 
     <section id="bbv2.tutorial.hierarchy">
       <title>Project hierarchy</title>