Merge commit 'upstream/2.0.0'

1 files changed, 45 insertions, 0 deletions

diff --git a/doc/user/nodes.in b/doc/user/nodes.in
index e583ea9..c65a2ad 100644
--- a/doc/user/nodes.in
+++ b/doc/user/nodes.in
@@ -332,6 +332,51 @@
 
   </section>
 
+  <section>
+  <title>&GetBuildPath;: Getting the Path From a &Node; or String</title>
+
+    <para>
+
+    <function>env.GetBuildPath(file_or_list)</function>
+    returns the path of a &Node; or a string representing a
+    path.  It can also take a list of &Node;s and/or strings, and
+    returns the list of paths.  If passed a single &Node;, the result
+    is the same as calling <literal>str(node)</literal> (see above).
+    The string(s) can have embedded construction variables, which are
+    expanded as usual, using the calling environment's set of
+    variables.  The paths can be files or directories, and do not have
+    to exist.
+
+    </para>
+
+    <scons_example name="GetBuildPath">
+      <file name="SConstruct" printme="1">
+      env=Environment(VAR="value")
+      n=File("foo.c")
+      print env.GetBuildPath([n, "sub/dir/$VAR"])
+      </file>
+    </scons_example>
+
+    <para>
+
+    Would print the following file names:
+
+    </para>
+
+    <scons_output example="GetBuildPath" os="posix">
+      <scons_output_command>scons -Q</scons_output_command>
+    </scons_output>
+
+    <para>
+
+    There is also a function version of &GetBuildPath; which can
+    be called without an &Environment;; that uses the default SCons
+    &Environment; to do substitution on any string arguments.
+
+    </para>
+
+  </section>
+
   <!--
 
   <section>