diff --git a/doc/src/advanced.xml b/doc/src/advanced.xml
index d1d748818..7334136d4 100644
--- a/doc/src/advanced.xml
+++ b/doc/src/advanced.xml
@@ -402,6 +402,23 @@ bjam optimization=space
           </listitem>
         </varlistentry>
 
+        <varlistentry>
+          <term><option>--build-dir</option></term>
+          <listitem>
+            <para>Changes build directories for all project roots being built. When
+            this option is specified, all Jamroot files should declare project name.
+            The build directory for the project root will be computed by contanating 
+            the value of the <option>--build-dir</option> option, the project name 
+            specified in Jamroot, and the build dir specified in Jamroot 
+            (or <literal>bin</literal>, if none is specified).
+            </para>
+
+            <para>The option is primarily useful when building from read-only
+            media, when you can't modify Jamroot.
+            </para>
+          </listitem>
+        </varlistentry>
+
         <varlistentry>
           <term><option>--version</option></term>
           <listitem>