Tweaks to variant dir documentation [skip appveyor]

Manpage/shared VariantDir function wording tries to make more
clear that build happens in the variant. Other tweaking.

User guide variant description similarly updated. A (worded) example
of why one might want variants is added.

Formerly separate chapter doc/user/variants.xml is now included
as a section in the previous chapter.  An additional example
is enabled (was in the file but commented out), which some
introductiory wording. The introduction to the other sample
in the file is also built up slightly.

Dropped embedded comments that were the old Cons documentation
for these topics.

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

1 files changed, 36 insertions, 55 deletions

diff --git a/SCons/Environment.xml b/SCons/Environment.xml
index ac40f74..13d0754 100644
--- a/SCons/Environment.xml
+++ b/SCons/Environment.xml
@@ -3171,8 +3171,8 @@ def create(target, source, env):
     # A function that will write a 'prefix=$SOURCE'
     # string into the file name specified as the
     # $TARGET.
-    f = open(str(target[0]), 'wb')
-    f.write('prefix=' + source[0].get_contents())
+    with open(str(target[0]), 'wb') as f:
+        f.write('prefix=' + source[0].get_contents())
 
 # Fetch the prefix= argument, if any, from the command
 # line, and use /usr/local as the default.
@@ -3206,90 +3206,75 @@ env.UpdateValue(target = Value(output), source = Value(input))
 </arguments>
 <summary>
 <para>
-Use the
-&f-VariantDir;
-function to create a copy of your sources in another location:
-if a name under
-<parameter>variant_dir</parameter>
-is not found but exists under
-<parameter>src_dir</parameter>,
-the file or directory is copied to
-<parameter>variant_dir</parameter>.
-Target files can be built in a different directory
-than the original sources by simply refering to the sources (and targets)
-within the variant tree.
-</para>
-
-<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.
 &f-VariantDir;
 can be called multiple times with the same
 <parameter>src_dir</parameter>
 to set up multiple builds with different options
-(<parameter>variants</parameter>).
+(<emphasis>variants</emphasis>).
+</para>
+
+<para>
 The
-<parameter>src_dir</parameter>
-location must be in or underneath the SConstruct file's directory, and
-<parameter>variant_dir</parameter>
+<parameter>variant</parameter>
+location must be in or underneath the project top directory,
+and <parameter>src_dir</parameter>
 may not be underneath
-<parameter>src_dir</parameter>.
-<!--
-TODO: Can the above restrictions be clarified or relaxed?
-TODO: The latter restriction is clearly not completely right;
-TODO: src_dir = '.' works fine with a build dir under it.
--->
+<parameter>variant_dir</parameter>.
 </para>
 
 <para>
-The default behavior is for
-&scons;
-to physically duplicate the source files in the variant tree.
+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
 intermediate source files are generated during the build,
-or preprocessors or other scanners search for included files
+or if preprocessors or other scanners search for included files
 relative to the source file,
-or individual compilers or other invoked tools are hard-coded
+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;
-see also the
+the duplication is performed by linking rather than copying.
+This behavior is affected by the
 <option>--duplicate</option>
 command-line option.
-Moreover, only the files needed for the build are duplicated;
-files and directories that are not used are not present in
-<parameter>variant_dir</parameter>.
 </para>
 
 <para>
-Duplicating the source tree may be disabled by setting the
-<literal>duplicate</literal>
+Physically duplicating the source files may be disabled by setting the
+<parameter>duplicate</parameter>
 argument to
-<literal>0</literal>
-(zero).
+<constant>False</constant>.
 This will cause
-&scons;
+&SCons;
 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 always more efficient than
-<literal>duplicate=1</literal>,
-and is usually safe for most builds
-(but see above for cases that may cause problems).
+This is more efficient than
+<literal>duplicate=True</literal>,
+and is safe for most builds;
+revert to <constant>True</constant>
+if it causes problems.
 </para>
 
 <para>
-Note that
 &f-VariantDir;
-works most naturally with a subsidiary SConscript file.
-However, you would then call the subsidiary SConscript file
-not in the source directory, but in the
+works most naturally with used with a subsidiary SConscript file.
+The subsidiary SConscript file is called as if it
+were in
 <parameter>variant_dir</parameter>,
 regardless of the value of
-<literal>duplicate</literal>.
+<parameter>duplicate</parameter>.
 This is how you tell
 &scons;
 which variant of a source tree to build:
@@ -3319,15 +3304,11 @@ Examples:
 # use names in the build directory, not the source directory
 VariantDir('build', 'src', duplicate=0)
 Program('build/prog', 'build/source.c')
-</example_commands>
 
-<example_commands>
 # this builds both the source and docs in a separate subtree
 VariantDir('build', '.', duplicate=0)
 SConscript(dirs=['build/src','build/doc'])
-</example_commands>
 
-<example_commands>
 # same as previous example, but only uses SConscript
 SConscript(dirs='src', variant_dir='build/src', duplicate=0)
 SConscript(dirs='doc', variant_dir='build/doc', duplicate=0)