More docs

[SVN r35839]

v2/doc/src/advanced.xml

@@ -766,6 +766,34 @@ rule my-rule ( properties * )
         requirements can be easier to write and understand.
         </para>
 
+        <para>Requirements explicitly specified for a target are usually
+        combined with the requirements specified for the containing project. You
+        can cause a target to completely ignore specific project's requirement
+        using the syntax by adding minus sign before a property, for example:
+<programlisting>
+exe main : main.cpp : <emphasis role="bold">-&lt;define&gt;UNNECESSARY_DEFINE</emphasis> ;
+</programlisting>
+        This syntax is the only way to ignore free properties from parent,
+        such as defines. It can be also useful for ordinary properties. Consider
+        this example:
+<programlisting>
+project test : requirements &lt;threading;&gt;multi ;
+exe test1 : test1.cpp ;
+exe test2 : test2.cpp : &lt;threading;&gt;single ;
+exe test3 : test3.cpp : -&lt;threading;&gt;multi ;
+</programlisting>
+        Here, <code>test1</code> inherits project requirements and will always
+        be built in multi-threaded mode. The <code>test2</code> target
+        <emphasis>overrides</emphasis> project's requirements and will
+        always be built in single-threaded mode. In contrast, the 
+        <code>test3</code> target <emphasis>removes</emphasis> a property
+        from project requirements and will be built either in single-threaded or
+        multi-threaded mode depending on which variant is requested by the
+        user.</para>
+
+        <para>Note that removing of requirements is completely textual: 
+        you need to specify exactly the same property to remove it.</para>
+        
       </section>
 
       <section>

v2/doc/src/tasks.xml

@@ -458,6 +458,63 @@ actions echo
             
     </section>
 
+    <section id="bbv2.reference.precompiled_headers">
+      <title>Precompiled headers</title>
+
+      <para>Precompiled headers is a mechanism to speed up compilation
+      by creating a partially processed version of some header files,
+      and then using that version during compilations rather then
+      repeatedly parsing the original headers. Boost.Build supports
+      precompiled headers with gcc and msvc toolsets.</para>
+
+      <para>To use precompiled headers, follow these steps:</para>
+      <orderedlist>
+        <listitem><para>Create a header that includes big headers used by your project.
+        It's better to include only headers that are sufficiently stable &#x2014;
+        like headers from the compiler, and external libraries. Please wrap
+        the header in <code>#ifdef BOOST_BUILD_PCH_ENABLED</code>, so that
+        the potentially expensive inclusion of headers is not done
+        when PCH is not enabled. Include the new header at the top of your
+        source files.</para></listitem>
+
+        <listitem><para>Declare new Boost.Build target for the precompiled header
+        and add that precompiled header to sources of the target whose compilation
+        you want to speed up:
+        <programlisting>
+cpp-pch pch : header.hpp ;
+exe main : main.cpp pch ;</programlisting>
+        You can use the <code>c-pch</code> if you want to use the precompiled
+        header in C programs.
+        </para></listitem>
+
+      </orderedlist>
+      <para>The <filename>pch</filename> example in Boost.Build distribution
+      can be used as reference.</para>
+
+      <para>Please note the following:</para>
+      <itemizedlist>
+        <listitem><para>The inclusion of the precompiled header must be the
+        first thing in a source file, before any code or preprocessor directives.
+        </para></listitem>
+
+        <listitem><para>The build properties used to build the sources and the
+        preprocessed must be the same. Consider using project requirements to 
+        assure this.
+        </para></listitem>
+
+        <listitem><para>Precompiled headers must be used purely as a way to
+        improve compilation time, not to save the number of include statements.
+        If a source file needs to include some header, explicitly include
+        it in the source file, even if the same header is included from
+        the precompiled header. This makes sure that your project will build
+        even if precompiled headers are not supported.</para></listitem>
+        
+      </itemizedlist>
+      
+      
+    </section>
+
+
     <section id="bbv2.reference.generated_headers">
       <title>Generated headers</title>
 
@@ -720,7 +777,29 @@ exe app : app.cpp : &lt;implicit-dependency&gt;parser ;
         </listitem>
       </varlistentry>
 
+      <varlistentry><term><literal>tag</literal></term>
 
+        <listitem><para>The <literal>tag</literal> feature is used to customize
+        the name of the generated files. The value should have the form:
+<programlisting>@<replaceable>rulename</replaceable></programlisting> where
+        <replaceable>rulename</replaceable> should be a name of a rule with
+        the following signature:
+<programlisting>rule tag ( name : type ? : property-set )</programlisting>
+        The rule will be called for each target with the default name computed
+        by Boost.Build, the type of the target, and property set. The rule
+        can either return a string that must be used as the name of the
+        target, or empty string, in which case the default name will be used.
+        </para>
+
+        <para>Most typical use of the <literal>tag</literal> feature is
+        to encode build properties, or library version in library target names.
+        You should take care to return non-empty string from the tag rule
+        only for types you care about &#x2014; otherwise, you might
+        end up modifying names of object files, generated header file and
+        other targets for which changing names does not make sense.</para>
+        </listitem>
+
+      </varlistentry>