From e65ced18e9bc02fdb3c4e3166821f96cf5cf9ff9 Mon Sep 17 00:00:00 2001
From: Mats Wichmann <mats@linux.com>
Date: Sat, 25 Apr 2020 13:33:22 -0600
Subject: 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>
---
 doc/user/hierarchy.xml | 141 ++++++++++++++++++++++++++++++++++---------------
 1 file 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
-- 
cgit v0.12


From b3f2e6671a3cfa34b9e73f2ca20eac1ef9d409a0 Mon Sep 17 00:00:00 2001
From: Mats Wichmann <mats@linux.com>
Date: Sun, 26 Apr 2020 10:37:09 -0600
Subject: Exports doc fixes  [ci skip]

Fix a couple of typos discoverted by sider.

Update doc entries in the (shared) function descriptions
of Export, Import and Return (Environment.xml)

Signed-off-by: Mats Wichmann <mats@linux.com>
---
 doc/user/hierarchy.xml                 |  4 +-
 src/engine/SCons/Script/SConscript.xml | 82 +++++++++++++++++-----------------
 2 files changed, 44 insertions(+), 42 deletions(-)

diff --git a/doc/user/hierarchy.xml b/doc/user/hierarchy.xml
index b54e2a5..11a68f9 100644
--- a/doc/user/hierarchy.xml
+++ b/doc/user/hierarchy.xml
@@ -563,7 +563,7 @@ Export('env', 'debug')
 
       <para>
 
-      Beacuse a Python identifier cannot contain spaces,
+      Because a Python identifier cannot contain spaces,
       &Export; assumes a string containing spaces is multiple
       variable names to export and splits it for you:
 
@@ -721,7 +721,7 @@ env.Program('prog', ['prog.c'])
 
       <para>
 
-      &Import; prefers a local defintion to a global one,
+      &Import; prefers a local definition 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,
diff --git a/src/engine/SCons/Script/SConscript.xml b/src/engine/SCons/Script/SConscript.xml
index a1e0129..d42fdac 100644
--- a/src/engine/SCons/Script/SConscript.xml
+++ b/src/engine/SCons/Script/SConscript.xml
@@ -26,7 +26,7 @@ See its __doc__ string for a discussion of the format.
 
 <scons_function name="Default">
 <arguments>
-(targets)
+(targets...)
 </arguments>
 <summary>
 <para>
@@ -163,21 +163,23 @@ is used if no value is specified.
 
 <scons_function name="Export">
 <arguments>
-(vars)
+([vars...], [key=value...])
 </arguments>
 <summary>
 <para>
-This tells
-&scons;
-to export a list of variables from the current
-SConscript file to all other SConscript files.
-The exported variables are kept in a global collection,
-so subsequent calls to
+Exports a list of variables from the current
+SConscript file to a global collection where they can be
+imported by any other SConscript file.
+<parameter>vars</parameter> are keys used to
+look up the value, so they must be
+string represenations of the names of the variables
+to be exported.
+Subsequent calls to
 &f-Export;
-will over-write previous exports that have the same name.
+will over-write any previous exports that have the same name.
 Multiple variable names can be passed to
 &f-Export;
-as separate arguments or as a list.
+as separate arguments or as words in a space-separated string.
 Keyword arguments can be used to provide names and their values.
 A dictionary can be used to map variables to a different name when exported.
 Both local variables and global variables can be exported.
@@ -214,7 +216,7 @@ function supports an
 argument that makes it easier to to export a variable or
 set of variables to a single SConscript file.
 See the description of the
-&f-SConscript;
+&f-link-SConscript;
 function, below.
 </para>
 </summary>
@@ -270,26 +272,25 @@ message.
 
 <scons_function name="Import">
 <arguments>
-(vars)
+(vars...)
 </arguments>
 <summary>
 <para>
-This tells
-&scons;
-to import a list of variables into the current SConscript file. This
-will import variables that were exported with
-&f-Export;
-or in the
+Imports a list of variables into the current SConscript file.
+The variables must be string representations of variable
+names which have been previously exported either by the
+&f-link-Export; function or by the
 <varname>exports</varname>
 argument to
 &f-link-SConscript;.
 Variables exported by
 &f-SConscript;
-have precedence.
+take precedence.
 Multiple variable names can be passed to
 &f-Import;
-as separate arguments or as a list. The variable "*" can be used
-to import all variables.
+as separate arguments or as words in a space-separated string.
+The wildcard <literal>"*"</literal> can be used to import all
+available variables.
 </para>
 
 <para>
@@ -311,32 +312,35 @@ Import("*")
 </arguments>
 <summary>
 <para>
-By default,
-this stops processing the current SConscript
-file and returns to the calling SConscript file
-the values of the variables named in the
+Return to the calling SConscript, optionally
+returning the values of variables named in the
 <varname>vars</varname>
 string arguments.
 Multiple strings contaning variable names may be passed to
-&f-Return;.
-Any strings that contain white space
+&f-Return;. A string containing white space
+is split into words, which are considered individual
+variable names.
+Returns a tuple of values, or value that evaluates
+<constant>False</constant>
+if no <parameter>vars</parameter> were specified.
 </para>
 
 <para>
+By default &Return; stops processing the current SConscript
+and returns immediately.
 The optional
 <literal>stop=</literal>
 keyword argument may be set to a false value
 to continue processing the rest of the SConscript
 file after the
 &f-Return;
-call.
-This was the default behavior prior to SCons 0.98.
+call (this was the default behavior prior to SCons 0.98.)
 However, the values returned
 are still the values of the variables in the named
 <varname>vars</varname>
 at the point
 &f-Return;
-is called.
+was called.
 </para>
 
 <para>
@@ -434,17 +438,15 @@ SConscript(dirs=['sub1', 'sub2'], name='MySConscript')
 <para>
 The optional
 <varname>exports</varname>
-argument provides a list of variable names or a dictionary of
-named values to export to the
-<varname>script(s)</varname>.
-These variables are locally exported only to the specified
-<varname>script(s)</varname>,
-and do not affect the global pool of variables used by the
-&f-Export;
+argument provides a list of string representations of
+variable names or a dictionary of named values to export.
+These variables are locally exported only to the called
+SConscript files
+and do not affect the global pool of variables managed by the
+&f-link-Export;
 function.
 <!-- If multiple dirs are provided, each script gets a fresh export. -->
-The subsidiary
-<varname>script(s)</varname>
+The subsidiary SConscript files
 must use the
 &f-link-Import;
 function to import the variables.
@@ -482,7 +484,7 @@ argument is interpreted relative to the directory of the calling
 file.
 See the description of the
 &f-VariantDir;
-function below for additional details and restrictions.
+function for additional details and restrictions.
 </para>
 
 <para>
-- 
cgit v0.12


From 163e83e856edb4eb420fe103f1337b52fff05ae8 Mon Sep 17 00:00:00 2001
From: Mats Wichmann <mats@linux.com>
Date: Tue, 28 Apr 2020 08:15:27 -0600
Subject: docs: tweak Export wording a bit more  [ci skip]

Be more clear in response to a review comment.

Signed-off-by: Mats Wichmann <mats@linux.com>
---
 doc/user/hierarchy.xml | 69 ++++++++++++++++++++++++++++++++------------------
 1 file changed, 44 insertions(+), 25 deletions(-)

diff --git a/doc/user/hierarchy.xml b/doc/user/hierarchy.xml
index 11a68f9..92639cf 100644
--- a/doc/user/hierarchy.xml
+++ b/doc/user/hierarchy.xml
@@ -2,7 +2,7 @@
 <!DOCTYPE sconsdoc [
     <!ENTITY % scons SYSTEM "../scons.mod">
     %scons;
-    
+
     <!ENTITY % builders-mod SYSTEM "../generated/builders.mod">
     %builders-mod;
     <!ENTITY % functions-mod SYSTEM "../generated/functions.mod">
@@ -11,7 +11,7 @@
     %tools-mod;
     <!ENTITY % variables-mod SYSTEM "../generated/variables.mod">
     %variables-mod;
-    
+
 ]>
 
 <chapter id="chap-hierarchical"
@@ -523,7 +523,7 @@ x
 
     &SCons; supports the ability to <firstterm>export</firstterm> variables
     from an &SConscript; file
-    so they can be <firstterm>imported</firstterm> by other 
+    so they can be <firstterm>imported</firstterm> by other
     &SConscript; files, thus allowing you to share common initialized
     values throughout your build hierarchy.
 
@@ -537,10 +537,9 @@ x
       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;:
+      &Export; is pretty flexible - in the simplest form,
+      you pass it a string that represents the name of
+      the variable, and &Export; stores that with its value:
 
       </para>
 
@@ -564,22 +563,42 @@ Export('env', 'debug')
       <para>
 
       Because a Python identifier cannot contain spaces,
-      &Export; assumes a string containing spaces is multiple
-      variable names to export and splits it for you:
+      &Export; assumes a string containing spaces is is a
+      shortcut for multiple variable names to export and
+      splits it up for you:
 
       </para>
 
       <sconstruct>
+env = Environment()
+debug = ARGUMENTS['debug']
 Export('env debug')
       </sconstruct>
 
       <para>
 
+      You can also pass &Export; a dictionary of values.
+      This form allows the opportunity to export a variable
+      from the current scope under a different name -
+      in this example, the value of <varname>foo</varname>
+      is exported under the name <literal>"bar"</literal>:
+
+      <sconstruct>
+env = Environment()
+foo = "FOO"
+args = {"env": env, "bar": foo}
+Export(args)
+      </sconstruct>
+
+      </para>
+
+      <para>
+
       &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:
+      This form adds the ability to create exported variables
+      that have not actually been set locally in the SConscript file.
+      When used this way, the key is the intended variable name,
+      not a string representation as with the other forms:
 
       </para>
 
@@ -589,7 +608,7 @@ Export(MODE="DEBUG", TARGET="arm")
 
       <para>
 
-      The styles can be mixed, however note that Python function calling
+      The styles can be mixed, though Python function calling
       syntax requires all non-keyword arguments to precede any
       keyword arguments in the call.
 
@@ -599,10 +618,10 @@ Export(MODE="DEBUG", TARGET="arm")
 
       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.
+      Calls to &Export; are cumulative. When you call &Export;
+      you are actually updating a Python dictionary, so it
+      is fine to export a variable you have already exported,
+      but when doing so, the previoue value is lost.
 
       </para>
 
@@ -620,7 +639,7 @@ SConscript('src/SConscript', 'env')
 
       <para>
 
-      Or (preferably, for readability) as the &exports; keyword argument:
+      Or (preferably, for readability) using the &exports; keyword argument:
 
       </para>
 
@@ -631,8 +650,8 @@ SConscript('src/SConscript', exports='env')
       <para>
 
       These calls export the specified variables
-      to only the listed &SConscript; file.
-      You may, however, specify more than one
+      to only the listed &SConscript; file(s).
+      You may specify more than one
       &SConscript; file in a list:
 
       </para>
@@ -672,7 +691,7 @@ env.Program('prog', ['prog.c'])
 
       <para>
 
-      The &Import; call makes the previously defined <varname>env</varname> 
+      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.
@@ -694,7 +713,7 @@ Import('env', 'debug')
 env = env.Clone(DEBUG=debug)
 env.Program('prog', ['prog.c'])
       </sconstruct>
-      
+
       <para>
 
       In this example, we pull in the common &consenv;
@@ -725,7 +744,7 @@ env.Program('prog', ['prog.c'])
       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> 
+      the import will find the <varname>foo</varname>
       exported to this SConscript.
 
       </para>
@@ -749,7 +768,7 @@ env.Program('prog', ['prog.c'])
 
       If you're dealing with a lot of &SConscript; files,
       this can be a lot simpler than keeping
-      arbitrary lists of imported variables in each file.
+      arbitrary lists of imported variables up to date in each file.
 
       </para>
 
-- 
cgit v0.12


From aaf6595eba0f393fe474b42fda7360b734ae590e Mon Sep 17 00:00:00 2001
From: Mats Wichmann <mats@linux.com>
Date: Tue, 28 Apr 2020 10:27:20 -0600
Subject: docs: tweak "manpage" (shared) Return, SConscript   [ci skip]

After previous updates, the manpage part (also shared to the
userguide) was a little less precise than it could be.
SConscript definition now describes the return value more
accurately (e.g. add what happens if multiple scripts called)
and moved to its own paragraph (at end) rather than inline.

Signed-off-by: Mats Wichmann <mats@linux.com>
---
 src/engine/SCons/Script/SConscript.xml | 177 ++++++++++++++++-----------------
 1 file changed, 83 insertions(+), 94 deletions(-)

diff --git a/src/engine/SCons/Script/SConscript.xml b/src/engine/SCons/Script/SConscript.xml
index d42fdac..8a6a928 100644
--- a/src/engine/SCons/Script/SConscript.xml
+++ b/src/engine/SCons/Script/SConscript.xml
@@ -167,21 +167,22 @@ is used if no value is specified.
 </arguments>
 <summary>
 <para>
-Exports a list of variables from the current
+Exports variables from the current
 SConscript file to a global collection where they can be
-imported by any other SConscript file.
-<parameter>vars</parameter> are keys used to
-look up the value, so they must be
-string represenations of the names of the variables
-to be exported.
-Subsequent calls to
-&f-Export;
-will over-write any previous exports that have the same name.
-Multiple variable names can be passed to
-&f-Export;
-as separate arguments or as words in a space-separated string.
+imported by other SConscript files.
+<parameter>vars</parameter> may be one or more
+strings representing variable names to be exported.
+If a string contains whitespace, it is split into
+separate strings, as if multiple string arguments
+had been given.  A <parameter>vars</parameter> argument
+may also be a dictionary, which can be used to map variables
+to different names when exported.
 Keyword arguments can be used to provide names and their values.
-A dictionary can be used to map variables to a different name when exported.
+</para>
+
+<para>
+&f-Export; calls are cumulative. Specifying a previously
+exported variable will overwirte the earlier value.
 Both local variables and global variables can be exported.
 </para>
 
@@ -202,22 +203,19 @@ Export("env", "package")
 Export(["env", "package"])
 
 # Make env available using the name debug:
-Export(debug = env)
+Export(debug=env)
 
 # Make env available using the name debug:
-Export({"debug":env})
+Export({"debug": env})
 </example_commands>
 
 <para>
 Note that the
-&f-SConscript;
-function supports an
-<varname>exports</varname>
-argument that makes it easier to to export a variable or
-set of variables to a single SConscript file.
-See the description of the
 &f-link-SConscript;
-function, below.
+function supports an &exports;
+argument that allows exporting a variable or
+set of variables to a specific SConscript file or files.
+See the description below.
 </para>
 </summary>
 </scons_function>
@@ -276,12 +274,12 @@ message.
 </arguments>
 <summary>
 <para>
-Imports a list of variables into the current SConscript file.
-The variables must be string representations of variable
-names which have been previously exported either by the
+Imports variables into the current SConscript file.
+<parameter>vars</parameter>
+must be strings representating names of variables
+which have been previously exported either by the
 &f-link-Export; function or by the
-<varname>exports</varname>
-argument to
+&exports; argument to
 &f-link-SConscript;.
 Variables exported by
 &f-SConscript;
@@ -308,29 +306,29 @@ Import("*")
 
 <scons_function name="Return">
 <arguments signature="global">
-([vars..., stop=])
+([vars..., stop=True])
 </arguments>
 <summary>
 <para>
 Return to the calling SConscript, optionally
-returning the values of variables named in the
-<varname>vars</varname>
-string arguments.
+returning the values of variables named in
+<varname>vars</varname>.
 Multiple strings contaning variable names may be passed to
 &f-Return;. A string containing white space
-is split into words, which are considered individual
-variable names.
-Returns a tuple of values, or value that evaluates
-<constant>False</constant>
-if no <parameter>vars</parameter> were specified.
+is split into individual variable names.
+Returns the value if one variable is specified,
+else returns a tuple of values.
+Returns an empty tuple if <parameter>vars</parameter>
+is omitted.
 </para>
 
 <para>
 By default &Return; stops processing the current SConscript
 and returns immediately.
 The optional
-<literal>stop=</literal>
-keyword argument may be set to a false value
+<literal>stop</literal>
+keyword argument
+may be set to a false value
 to continue processing the rest of the SConscript
 file after the
 &f-Return;
@@ -348,7 +346,7 @@ Examples:
 </para>
 
 <example_commands>
-# Returns without returning a value.
+# Returns no values (evaluates False)
 Return()
 
 # Returns the value of the 'foo' Python variable.
@@ -374,22 +372,13 @@ Return('val1 val2')
 </arguments>
 <summary>
 <para>
-This tells
-&scons;
-to execute
-one or more subsidiary SConscript (configuration) files.
-Any variables returned by a called script using
-&f-link-Return;
-will be returned by the call to
-&f-SConscript;.
+Execute one or more subsidiary SConscript (configuration) files.
 There are two ways to call the
-&f-SConscript;
-function.
+&f-SConscript; function.
 </para>
 
 <para>
-The first way you can call
-&f-SConscript;
+The first calling style
 is to explicitly specify one or more
 <varname>scripts</varname>
 as the first argument.
@@ -408,22 +397,22 @@ config = SConscript('MyConfig.py')
 </example_commands>
 
 <para>
-The second way you can call
+The second way to call
 &f-SConscript;
 is to specify a list of (sub)directory names
 as a
-<literal>dirs=</literal><varname>subdirs</varname>
+<varname>dirs</varname>=<replaceable>subdirs</replaceable>
 keyword argument.
 In this case,
 &scons;
-will, by default,
+will
 execute a subsidiary configuration file named
 &SConscript;
 in each of the specified directories.
 You may specify a name other than
 &SConscript;
 by supplying an optional
-<literal>name=</literal><varname>script</varname>
+<varname>name</varname>=<replaceable>script</replaceable>
 keyword argument.
 The first three examples below have the same effect
 as the first three examples above:
@@ -438,10 +427,10 @@ SConscript(dirs=['sub1', 'sub2'], name='MySConscript')
 <para>
 The optional
 <varname>exports</varname>
-argument provides a list of string representations of
-variable names or a dictionary of named values to export.
+argument provides a string or list of strings representing
+variable names, or a dictionary of named values, to export.
 These variables are locally exported only to the called
-SConscript files
+SConscript file(s)
 and do not affect the global pool of variables managed by the
 &f-link-Export;
 function.
@@ -463,49 +452,34 @@ SConscript(dirs=['one', 'two', 'three'], exports='shared_info')
 If the optional
 <varname>variant_dir</varname>
 argument is present, it causes an effect equivalent to the
-&f-link-VariantDir;
-method described below.
-(If
-<varname>variant_dir</varname>
-is not present, the
-<!-- <varname>src_dir</varname> and -->
-<varname>duplicate</varname>
-<!-- arguments are ignored.) -->
-argument is ignored.)
-The
-<varname>variant_dir</varname>
-<!--
-and
-<varname>src_dir</varname>
-arguments are interpreted relative to the directory of the calling
--->
+&f-link-VariantDir; function.
+The <varname>variant_dir</varname>
 argument is interpreted relative to the directory of the calling
-&SConscript;
-file.
-See the description of the
-&f-VariantDir;
-function for additional details and restrictions.
+SConscript file.
+The optional
+<varname>duplicate</varname> argument is
+interpreted as for &f-link-VariantDir;.
+If <varname>variant_dir</varname>
+is omitted, the <varname>duplicate</varname> argument is ignored.
+See the description of
+&f-link-VariantDir;
+below for additional details and restrictions.
 </para>
 
 <para>
 If
 <varname>variant_dir</varname>
 is present,
-<!--
-but
-<varname>src_dir</varname>
-is not,
--->
 the source directory is the directory in which the
-&SConscript;
+SConscript
 file resides and the
-&SConscript;
+SConscript
 file is evaluated as if it were in the
 <varname>variant_dir</varname>
 directory:
 </para>
 <example_commands>
-SConscript('src/SConscript', variant_dir = 'build')
+SConscript('src/SConscript', variant_dir='build')
 </example_commands>
 
 <para>
@@ -524,7 +498,7 @@ in the same directory as the
 </para>
 
 <example_commands>
-SConscript('SConscript', variant_dir = 'build')
+SConscript('SConscript', variant_dir='build')
 </example_commands>
 
 <para>
@@ -570,14 +544,17 @@ TODO??? SConscript('build/SConscript', src_dir='src')
 </para>
 
 <para>
-The optional
+If the optional
 <varname>must_exist</varname>
-argument, if true, causes an exception to be raised if a requested
-&SConscript; file is not found. The current default is false,
-causing only a warning to be omitted, but this behavior is deprecated.
+is <constant>True</constant>,
+causes an exception to be raised if a requested
+SConscript file is not found. The current default is
+<constant>False</constant>,
+causing only a warning to be emitted, but this default is deprecated
+(<emphasis>since 3.1</emphasis>).
 For scripts which truly intend to be optional, transition to
-explicty supplying
-<literal>must_exist=False</literal> to the call.
+explicitly supplying
+<literal>must_exist=False</literal> to the &f-SConscript; call.
 </para>
 
 <para>
@@ -613,6 +590,18 @@ SConscript('doc/SConscript', variant_dir='build/doc', duplicate=0)
 SConscript('src/SConscript', variant_dir='build/x86', duplicate=0)
 SConscript('src/SConscript', variant_dir='build/ppc', duplicate=0)
 </example_commands>
+
+<para>
+&f-SConscript; returns the values of any variables
+named by the executed SConscript(s) in arguments
+to the &f-link-Return; function (see above for details).
+If a single &f-SConscript; call causes multiple scripts to
+be executed, the return value is a tuple containing
+the returns of all of the scripts. If an executed
+script does not explicitly call &Return;, it returns
+<constant>None</constant>.
+</para>
+
 </summary>
 </scons_function>
 
-- 
cgit v0.12


From 7114b9c214e14ea40c12c47f0799e92feaa9d817 Mon Sep 17 00:00:00 2001
From: Mats Wichmann <mats@linux.com>
Date: Tue, 28 Apr 2020 10:37:52 -0600
Subject: docs: fix typos from sider

Signed-off-by: Mats Wichmann <mats@linux.com>
---
 doc/user/hierarchy.xml                 | 2 +-
 src/engine/SCons/Script/SConscript.xml | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/user/hierarchy.xml b/doc/user/hierarchy.xml
index 92639cf..ec1864c 100644
--- a/doc/user/hierarchy.xml
+++ b/doc/user/hierarchy.xml
@@ -621,7 +621,7 @@ Export(MODE="DEBUG", TARGET="arm")
       Calls to &Export; are cumulative. When you call &Export;
       you are actually updating a Python dictionary, so it
       is fine to export a variable you have already exported,
-      but when doing so, the previoue value is lost.
+      but when doing so, the previous value is lost.
 
       </para>
 
diff --git a/src/engine/SCons/Script/SConscript.xml b/src/engine/SCons/Script/SConscript.xml
index 8a6a928..8b88dca 100644
--- a/src/engine/SCons/Script/SConscript.xml
+++ b/src/engine/SCons/Script/SConscript.xml
@@ -182,7 +182,7 @@ Keyword arguments can be used to provide names and their values.
 
 <para>
 &f-Export; calls are cumulative. Specifying a previously
-exported variable will overwirte the earlier value.
+exported variable will overwrite the earlier value.
 Both local variables and global variables can be exported.
 </para>
 
@@ -276,7 +276,7 @@ message.
 <para>
 Imports variables into the current SConscript file.
 <parameter>vars</parameter>
-must be strings representating names of variables
+must be strings representing names of variables
 which have been previously exported either by the
 &f-link-Export; function or by the
 &exports; argument to
-- 
cgit v0.12