docs: build up description of export/import/return [ci skip]

User Guide wording missed some details - one of which is
mentioned in an issue.  Fixes #798.

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

1 files changed, 97 insertions, 44 deletions

diff --git a/doc/user/hierarchy.xml b/doc/user/hierarchy.xml
index e5a8470..b54e2a5 100644
--- a/doc/user/hierarchy.xml
+++ b/doc/user/hierarchy.xml
@@ -508,7 +508,7 @@ x
     In the previous example,
     each of the subsidiary &SConscript; files
     created its own construction environment
-    by calling &Environment; separately.
+    by calling &f-link-Environment; separately.
     This obviously works fine,
     but if each program must be built
     with the same construction variables,
@@ -521,10 +521,10 @@ x
 
     <para>
 
-    &SCons; supports the ability to <emphasis>export</emphasis> variables
-    from a parent &SConscript; file
-    to its subsidiary &SConscript; files,
-    which allows you to share common initialized
+    &SCons; supports the ability to <firstterm>export</firstterm> variables
+    from an &SConscript; file
+    so they can be <firstterm>imported</firstterm> by other 
+    &SConscript; files, thus allowing you to share common initialized
     values throughout your build hierarchy.
 
     </para>
@@ -534,17 +534,13 @@ x
 
       <para>
 
-      There are two ways to export a variable,
-      such as a construction environment,
-      from an &SConscript; file,
-      so that it may be used by other &SConscript; files.
-      First, you can call the &Export;
-      function with a list of variables,
-      or a string of white-space separated variable names.
-      Each call to &Export; adds one
-      or more variables to a global list
-      of variables that are available for import
-      by other &SConscript; files.
+      There are two ways to export a variable
+      from an &SConscript; file.
+      The first way is to call the &f-link-Export; function.
+      &Export; takes one or more arguments that are
+      string representations of the variable names - that is,
+      to export the variable <varname>env</varname>,
+      you supply the string <quote>env</quote> to &Export;:
 
       </para>
 
@@ -567,9 +563,9 @@ Export('env', 'debug')
 
       <para>
 
-      Because white space is not legal in Python variable names,
-      the &Export; function will even automatically split
-      a string into separate names for you:
+      Beacuse a Python identifier cannot contain spaces,
+      &Export; assumes a string containing spaces is multiple
+      variable names to export and splits it for you:
 
       </para>
 
@@ -579,9 +575,42 @@ Export('env debug')
 
       <para>
 
-      Second, you can specify a list of
-      variables to export as a second argument
-      to the &SConscript; function call:
+      &Export; will also accept arguments in keyword style.
+      This style can be used, for example, to set variables
+      that have not been set by name in the SConscript file,
+      and thus the keys are the intended variable names,
+      not a string representation:
+
+      </para>
+
+      <sconstruct>
+Export(MODE="DEBUG", TARGET="arm")
+      </sconstruct>
+
+      <para>
+
+      The styles can be mixed, however note that Python function calling
+      syntax requires all non-keyword arguments to precede any
+      keyword arguments in the call.
+
+      </para>
+
+      <para>
+
+      The &Export; function adds the variables to a global
+      location from which other &SConscript; files can import.
+      Exporting conceptually works the same as Python assignment
+      statements - if you assign a name to something, then later assign
+      the same name to something else, the reference to the original
+      is lost.
+
+      </para>
+
+      <para>
+
+      The other way to export is you can specify a list of
+      variables as a second argument
+      to the &f-link-SConscript; function call:
 
       </para>
 
@@ -591,7 +620,7 @@ SConscript('src/SConscript', 'env')
 
       <para>
 
-      Or as the &exports; keyword argument:
+      Or (preferably, for readability) as the &exports; keyword argument:
 
       </para>
 
@@ -602,7 +631,7 @@ SConscript('src/SConscript', exports='env')
       <para>
 
       These calls export the specified variables
-      to only the listed &SConscript; files.
+      to only the listed &SConscript; file.
       You may, however, specify more than one
       &SConscript; file in a list:
 
@@ -632,7 +661,7 @@ SConscript(['src1/SConscript',
       Once a variable has been exported from a calling
       &SConscript; file,
       it may be used in other &SConscript; files
-      by calling the &Import; function:
+      by calling the &f-link-Import; function:
 
       </para>
 
@@ -643,43 +672,66 @@ env.Program('prog', ['prog.c'])
 
       <para>
 
-      The &Import; call makes the <literal>env</literal> construction
-      environment available to the &SConscript; file,
-      after which the variable can be used to build
-      programs, libraries, etc.
+      The &Import; call makes the previously defined <varname>env</varname> 
+      variable available to the &SConscript; file.
+      Assuming <varname>env</varname> is a &consenv;,
+      after import it can be used to build programs, libraries, etc.
+      The use case of passing around a &consenv; is extremely common
+      in larger &scons; builds.
 
       </para>
 
       <para>
 
       Like the &Export; function,
-      the &Import; function can be used
+      the &Import; function can be called
       with multiple variable names:
 
       </para>
 
       <sconstruct>
 Import('env', 'debug')
-env = env.Clone(DEBUG = debug)
+env = env.Clone(DEBUG=debug)
 env.Program('prog', ['prog.c'])
       </sconstruct>
+      
+      <para>
+
+      In this example, we pull in the common &consenv;
+      <varname>env</varname>, and
+      use the value of the <varname>debug</varname>
+      variable to make a modified copy by passing
+      that to a &f-link-Clone; call.
+
+      </para>
 
       <para>
 
-      And the &Import; function will similarly
-      split a string along white-space
+      The &Import; function will (like &Export;)
+      split a string containing white-space
       into separate variable names:
 
       </para>
 
       <sconstruct>
 Import('env debug')
-env = env.Clone(DEBUG = debug)
+env = env.Clone(DEBUG=debug)
 env.Program('prog', ['prog.c'])
       </sconstruct>
 
       <para>
 
+      &Import; prefers a local defintion to a global one,
+      so that if there is a global export of <varname>foo</varname>,
+      <emphasis>and</emphasis> the calling SConscript has
+      exported <varname>foo</varname> to this SConscript,
+      the import will find the <varname>foo</varname> 
+      exported to this SConscript.
+
+      </para>
+
+      <para>
+
       Lastly, as a special case,
       you may import all of the variables that
       have been exported by supplying an asterisk
@@ -689,7 +741,7 @@ env.Program('prog', ['prog.c'])
 
       <sconstruct>
 Import('*')
-env = env.Clone(DEBUG = debug)
+env = env.Clone(DEBUG=debug)
 env.Program('prog', ['prog.c'])
       </sconstruct>
 
@@ -713,13 +765,14 @@ env.Program('prog', ['prog.c'])
       &SConscript; file in some way.
       For example,
       suppose that you want to create one
-      library from source files
-      scattered throughout a number
-      of subsidiary &SConscript; files.
-      You can do this by using the &Return;
+      library from object files built by
+      several subsidiary &SConscript; files.
+      You can do this by using the &f-link-Return;
       function to return values
       from the subsidiary &SConscript; files
-      to the calling file.
+      to the calling file. Like &Import; and &Export;,
+      &Return; takes a string representation of the variable
+      name, not the variable name itself.
 
       </para>
 
@@ -727,8 +780,8 @@ env.Program('prog', ['prog.c'])
 
       If, for example, we have two subdirectories
       &foo; and &bar;
-      that should each contribute a source
-      file to a Library,
+      that should each contribute an object
+      file to a library,
       what we'd like to be able to do is
       collect the object files
       from the subsidiary &SConscript; calls
@@ -770,7 +823,7 @@ void bar(void) { printf("bar/bar.c\n"); }
 
       We can do this by using the &Return;
       function in the
-      <literal>foo/SConscript</literal> file like this:
+      <filename>foo/SConscript</filename> file like this:
 
       </para>
 
@@ -780,7 +833,7 @@ void bar(void) { printf("bar/bar.c\n"); }
       <para>
 
       (The corresponding
-      <literal>bar/SConscript</literal>
+      <filename>bar/SConscript</filename>
       file should be pretty obvious.)
       Then when we run &SCons;,
       the object files from the subsidiary subdirectories