Add some info to User Guide on #/paths [skip appveyor]

Signed-off-by: Mats Wichmann <mats@linux.com>

3 files changed, 60 insertions, 11 deletions

diff --git a/doc/generated/examples/hierarchy_hash_1.xml b/doc/generated/examples/hierarchy_hash_1.xml
new file mode 100644
index 0000000..371746d
--- /dev/null
+++ b/doc/generated/examples/hierarchy_hash_1.xml
@@ -0,0 +1,5 @@
+<screen xmlns="http://www.scons.org/dbxsd/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">% <userinput>scons -Q</userinput>
+path = #/include
+force-interpreted path = include
+scons: `.' is up to date.
+</screen>
diff --git a/doc/user/hierarchy.xml b/doc/user/hierarchy.xml
index ec1864c..e63d230 100644
--- a/doc/user/hierarchy.xml
+++ b/doc/user/hierarchy.xml
@@ -303,8 +303,7 @@ SConscript(['display/SConscript',
 
     <scons_example name="hierarchy_ex1">
       <file name="SConstruct" printme="1">
-SConscript(['prog1/SConscript',
-            'prog2/SConscript'])
+SConscript(['prog1/SConscript', 'prog2/SConscript'])
       </file>
       <file name="prog1/SConscript">
 env = Environment()
@@ -384,7 +383,7 @@ x
   </section>
 
   <section>
-  <title>Top-Level Path Names in Subsidiary &SConscript; Files</title>
+  <title>Top-Relative Path Names in Subsidiary &SConscript; Files</title>
 
     <para>
 
@@ -397,8 +396,7 @@ x
     You can tell &SCons; to interpret a path name
     as relative to the top-level &SConstruct; directory,
     not the local directory of the &SConscript; file,
-    by appending a &hash; (hash mark)
-    to the beginning of the path name:
+    by prepending a &hash; (hash mark) in front of the path name:
 
     </para>
 
@@ -446,6 +444,52 @@ x
 
     </para>
 
+    <para>
+
+    A couple of notes on top-relative paths:
+
+      <orderedlist>
+        <listitem><para>
+
+        &SCons; doesn't care whether you add a slash after the &hash;.
+        Some people consider <literal>'#/lib/foo1.c'</literal>
+        more readable than <literal>'#lib/foo1.c'</literal>,
+        but they're functionally equivalent.
+
+        </para></listitem>
+
+        <listitem><para>
+
+        The top-relative syntax is <emphasis>only</emphasis>
+        evaluated by &SCons;, the &Python; language itself does not
+        understand about it.  This becomes immediately obvious
+        if you like to use <function>print</function> for debugging,
+        or write a Python function that wants to evaluate a path.
+        You can force &SCons; to evaluate a top-relative path by
+        creating a Node object from it:
+
+        </para>
+
+        </listitem>
+      </orderedlist>
+
+      <scons_example name="hierarchy_hash">
+        <file name="SConstruct" printme="1">
+path = "#/include"
+
+print("path =", path)
+print("force-interpreted path =", Entry(path))
+        </file>
+      </scons_example>
+
+      Which shows:
+
+      <scons_output example="hierarchy_hash" suffix="1">
+         <scons_output_command>scons -Q</scons_output_command>
+      </scons_output>
+
+    </para>
+
   </section>
 
   <section>
diff --git a/doc/user/separate.xml b/doc/user/separate.xml
index 236556d..cfb7c8b 100644
--- a/doc/user/separate.xml
+++ b/doc/user/separate.xml
@@ -55,12 +55,12 @@
   and header files differ.  If you build "Controller A" first,
   then "Controller B", on the second build everything would
   have to be rebuilt, because &SCons; sees that the build
-  instructions differ, and thus the targets that depend on those
-  different instructions are not valid for the current build.
+  instructions are different to the ones used to build the
+  existing targets,  and thus the existing targets are invalid.
   Now when you go back and build for "Controller A",
   things have to be rebuilt from scratch again for the same reason.
-  However, if you can separate the places the output files
-  go, this problem can be avoided.
+  However, if you can separate the places the output files go,
+  this problem can be avoided.
   You can even set up to do both builds in one invocation of &SCons;.
 
   </para>
@@ -69,8 +69,8 @@
 
   You can enable this separation by creating one or more
   <firstterm>variant directory</firstterm> trees
-  that are used to hold the built objects files, libraries,
-  and executable programs, etc.
+  that are used to perform the build in, and thus provide a unique
+  home for object files, libraries, and executable programs, etc.
   for a specific flavor, or variant, of build.
   &SCons; provides two ways to do this,
   one through the &f-link-SConscript; function that we've already seen,