Update Users Guide to clarify usage of site_scons and site_init.py.

3 files changed, 50 insertions, 3 deletions

diff --git a/doc/user/README b/doc/user/README
index bdccf51..2d05359 100644
--- a/doc/user/README
+++ b/doc/user/README
@@ -3,7 +3,7 @@
 When adding a new file, add it to main.xml and MANIFEST.
 
 To build the .xml files from the .in files:
-  scons -D . BUILDDOC=1
+  scons -D BUILDDOC=1 foo.xml
 To build the whole PDF doc from this dir, for testing:
   scons -D ../../build/doc/PDF/scons-user.pdf 
 
diff --git a/doc/user/builders-writing.in b/doc/user/builders-writing.in
index b953975..dc6e95b 100644
--- a/doc/user/builders-writing.in
+++ b/doc/user/builders-writing.in
@@ -955,17 +955,22 @@ This functionality could be invoked as in the following example:
     to include in &SConscript;s; just put that module in
     <filename>site_scons/my_utils.py</filename> or any valid Python module name of your
     choice.  For instance you can do something like this in
-    <filename>site_scons/my_utils.py</filename> to add a build_id method:
+    <filename>site_scons/my_utils.py</filename> to add build_id and MakeWorkDir functions:
   </para>
     
   <scons_example name="site2">
     <file name="site_scons/my_utils.py" printme=1>
+      from SCons.Script import *   # for Execute and Mkdir
       def build_id():
          """Return a build ID (stub version)"""
          return "100"
+      def MakeWorkDir(workdir):
+         """Create the specified dir immediately"""
+         Execute(Mkdir(workdir))
     </file>
     <file name="SConscript">
       import my_utils
+      MakeWorkDir('/tmp/work')
       print "build_id=" + my_utils.build_id()
     </file>
   </scons_example>
@@ -980,9 +985,28 @@ This functionality could be invoked as in the following example:
   <sconstruct>
       import my_utils
       print "build_id=" + my_utils.build_id()
+      my_utils.MakeWorkDir('/tmp/work')
   </sconstruct>
 
   <para>
+    Note that although you can put this library in
+    <filename>site_scons/site_init.py</filename>,
+    it is no better there than <filename>site_scons/my_utils.py</filename>
+    since you still have to import that module into your &SConscript;.
+    Also note that in order to refer to objects in the SCons namespace
+    such as &Environment; or &Mkdir; or &Execute; in any file other
+    than a &SConstruct; or &SConscript; you always need to do
+  </para>
+  <sconstruct>
+      from SCons.Script import *
+  </sconstruct>
+
+  <para>
+    This is true in modules in <filename>site_scons</filename> such as
+    <filename>site_scons/site_init.py</filename> as well.
+  </para>
+
+  <para>
 
     If you have a machine-wide site dir you'd like to use instead of
     <filename>./site_scons</filename>, use the
diff --git a/doc/user/builders-writing.xml b/doc/user/builders-writing.xml
index c45af8a..2c0f697 100644
--- a/doc/user/builders-writing.xml
+++ b/doc/user/builders-writing.xml
@@ -828,13 +828,17 @@ This functionality could be invoked as in the following example:
     to include in &SConscript;s; just put that module in
     <filename>site_scons/my_utils.py</filename> or any valid Python module name of your
     choice.  For instance you can do something like this in
-    <filename>site_scons/my_utils.py</filename> to add a build_id method:
+    <filename>site_scons/my_utils.py</filename> to add build_id and MakeWorkDir functions:
   </para>
     
   <programlisting>
+      from SCons.Script import *   # for Execute and Mkdir
       def build_id():
          """Return a build ID (stub version)"""
          return "100"
+      def MakeWorkDir(workdir):
+         """Create the specified dir immediately"""
+         Execute(Mkdir(workdir))
   </programlisting>
 
   <para>
@@ -847,9 +851,28 @@ This functionality could be invoked as in the following example:
   <programlisting>
       import my_utils
       print "build_id=" + my_utils.build_id()
+      my_utils.MakeWorkDir('/tmp/work')
   </programlisting>
 
   <para>
+    Note that although you can put this library in
+    <filename>site_scons/site_init.py</filename>,
+    it is no better there than <filename>site_scons/my_utils.py</filename>
+    since you still have to import that module into your &SConscript;.
+    Also note that in order to refer to objects in the SCons namespace
+    such as &Environment; or &Mkdir; or &Execute; in any file other
+    than a &SConstruct; or &SConscript; you always need to do
+  </para>
+  <programlisting>
+      from SCons.Script import *
+  </programlisting>
+
+  <para>
+    This is true in modules in <filename>site_scons</filename> such as
+    <filename>site_scons/site_init.py</filename> as well.
+  </para>
+
+  <para>
 
     If you have a machine-wide site dir you'd like to use instead of
     <filename>./site_scons</filename>, use the