Try to improve variantdir docs [skip appveyor]

Reorder some bits, add some explantaions, include example of
passing different environments to subsidiary SConscript.

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

2 files changed, 57 insertions, 63 deletions

diff --git a/SCons/Environment.xml b/SCons/Environment.xml
index 3a6df97..79289c3 100644
--- a/SCons/Environment.xml
+++ b/SCons/Environment.xml
@@ -3416,42 +3416,35 @@ env.UpdateValue(target = Value(output), source = Value(input))
 </arguments>
 <summary>
 <para>
-Sets up an alternate build location.
-When building in the <parameter>variant_dir</parameter>,
-&SCons; backfills as needed with files from <parameter>src_dir</parameter>
-to create a complete build directory.
+Sets up a mapping to define a variant build directory
+<parameter>variant_dir</parameter>,
+which must be in or underneath the project top directory.
+<parameter>src_dir</parameter> may not be underneath
+<parameter>variant_dir</parameter>.
+A &f-VariantDir; mapping is global, even if called using the
+the &f-env-VariantDir; form.
 &f-VariantDir;
 can be called multiple times with the same
 <parameter>src_dir</parameter>
-to set up multiple builds with different options
-(<emphasis>variants</emphasis>).
-</para>
-
-<para>
-The
-<parameter>variant</parameter>
-location must be in or underneath the project top directory,
-and <parameter>src_dir</parameter>
-may not be underneath
-<parameter>variant_dir</parameter>.
+to set up multiple variant builds with different options.
 </para>
 
 <para>
+When files in <parameter>variant_dir</parameter> are referenced,
+&SCons; backfills as needed with files from <parameter>src_dir</parameter>
+to create a complete build directory.
 By default, &SCons;
-physically duplicates the source files and SConscript files
-as needed into the variant tree.
-Thus, a build performed in the variant tree is guaranteed to be identical
-to a build performed in the source tree even if
+physically duplicates the source files, SConscript files,
+and directory structure as needed into the variant directory.
+Thus, a build performed in the variant directory is guaranteed to be identical
+to a build performed in the source directory even if
 intermediate source files are generated during the build,
 or if preprocessors or other scanners search for included files
-relative to the source file,
+using paths relative to the source file,
 or if individual compilers or other invoked tools are hard-coded
 to put derived files in the same directory as source files.
 Only the files &SCons; calculates are needed for the build are
 duplicated into <parameter>variant_dir</parameter>.
-</para>
-
-<para>
 If possible on the platform,
 the duplication is performed by linking rather than copying.
 This behavior is affected by the
@@ -3470,38 +3463,43 @@ to invoke Builders using the path names of source files in
 <parameter>src_dir</parameter>
 and the path names of derived files within
 <parameter>variant_dir</parameter>.
-This is more efficient than
-<literal>duplicate=True</literal>,
+This is more efficient than duplicating,
 and is safe for most builds;
-revert to <constant>True</constant>
+revert to <literal>duplicate=True</literal>
 if it causes problems.
 </para>
 
 <para>
 &f-VariantDir;
 works most naturally with used with a subsidiary SConscript file.
-The subsidiary SConscript file is called as if it
-were in
+The subsidiary SConscript file must be called as if it were in
 <parameter>variant_dir</parameter>,
 regardless of the value of
 <parameter>duplicate</parameter>.
+When calling an SConscript file,
+you can pass an appropriately set up environment
+using the <parameter>exports</parameter> keyword
+argument so the SConscript can pick up the right settings
+for that variant build.
 This is how you tell
 &scons;
-which variant of a source tree to build:
+which variant of a source directory to build:
 </para>
 
 <example_commands>
+env1 = Environment(...settings for variant1...)
+env2 = Environment(...settings for variant2...)
+
 # run src/SConscript in two variant directories
 VariantDir('build/variant1', 'src')
-SConscript('build/variant1/SConscript')
+SConscript('build/variant1/SConscript', exports={"env": env1})
 VariantDir('build/variant2', 'src')
-SConscript('build/variant2/SConscript')
+SConscript('build/variant2/SConscript', exports={"env": env2})
 </example_commands>
 
 <para>
 See also the
-&f-link-SConscript;
-function, described above,
+&f-link-SConscript; function
 for another way to specify a variant directory
 in conjunction with calling a subsidiary SConscript file.
 </para>
diff --git a/SCons/Script/SConscript.xml b/SCons/Script/SConscript.xml
index 3c5b907..0710ea5 100644
--- a/SCons/Script/SConscript.xml
+++ b/SCons/Script/SConscript.xml
@@ -368,7 +368,7 @@ Return('val1 val2')
 </arguments>
 <summary>
 <para>
-Execute one or more subsidiary SConscript (configuration) files.
+Executes one or more subsidiary SConscript (configuration) files.
 There are two ways to call the
 &f-SConscript; function.
 </para>
@@ -395,8 +395,8 @@ config = SConscript('MyConfig.py')
 <para>
 The second way to call
 &f-SConscript;
-is to specify a list of (sub)directory names
-as a
+is to specify a list of directory names
+using the
 <varname>dirs</varname>=<replaceable>subdirs</replaceable>
 keyword argument.
 In this case,
@@ -448,38 +448,24 @@ 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; function.
+&f-link-VariantDir; function,
+but in effect only during the execution of the SConscript file.
 The <varname>variant_dir</varname>
-argument is interpreted relative to the directory of the calling
-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,
-the source directory is the directory in which the
-SConscript
-file resides and the
-SConscript
+argument is interpreted relative to the directory of the
+<emphasis>calling</emphasis> SConscript file.
+The source directory is the directory in which the
+<emphasis>called</emphasis> SConscript
+file resides and the SConscript
 file is evaluated as if it were in the
 <varname>variant_dir</varname>
-directory:
+directory. Thus:
 </para>
 <example_commands>
 SConscript('src/SConscript', variant_dir='build')
 </example_commands>
 
 <para>
-is equivalent to
+is equivalent to:
 </para>
 
 <example_commands>
@@ -488,9 +474,8 @@ SConscript('build/SConscript')
 </example_commands>
 
 <para>
-This later paradigm is often used when the sources are
-in the same directory as the
-&SConstruct;:
+If the sources are in the same directory as the
+&SConstruct;,
 </para>
 
 <example_commands>
@@ -498,7 +483,7 @@ SConscript('SConscript', variant_dir='build')
 </example_commands>
 
 <para>
-is equivalent to
+is equivalent to:
 </para>
 
 <example_commands>
@@ -507,6 +492,17 @@ SConscript('build/SConscript')
 </example_commands>
 
 <para>
+The optional
+<varname>duplicate</varname> argument is
+interpreted as for &f-link-VariantDir;.
+If the <varname>variant_dir</varname> argument
+is omitted, the <varname>duplicate</varname> argument is ignored.
+See the description of
+&f-link-VariantDir;
+for additional details and restrictions.
+</para>
+
+<para>
 <!--
 If
 <varname>variant_dir</varname>