Document GetBuildPath in Users Guide

2 files changed, 90 insertions, 0 deletions

diff --git a/doc/user/nodes.in b/doc/user/nodes.in
index d8169df..fb5ce23 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>
diff --git a/doc/user/nodes.xml b/doc/user/nodes.xml
index 8f3436a..e27d894 100644
--- a/doc/user/nodes.xml
+++ b/doc/user/nodes.xml
@@ -335,6 +335,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>
+
+    <programlisting>
+      env=Environment(VAR="value")
+      n=File("foo.c")
+      print env.GetBuildPath([n, "sub/dir/$VAR"])
+    </programlisting>
+
+    <para>
+
+    Would print the following file names:
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      ['foo.c', 'sub/dir/value']
+      scons: `.' is up to date.
+    </screen>
+
+    <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>