Merge pull request #3261 from mwichmann/doc-default

Improve scons docs regarding Default()

4 files changed, 17 insertions, 9 deletions

diff --git a/doc/man/scons.xml b/doc/man/scons.xml
index 0f59967..dc6c36c 100644
--- a/doc/man/scons.xml
+++ b/doc/man/scons.xml
@@ -274,7 +274,7 @@ scons
 <para>will build all target files in or below the current directory.
 Explicit default targets
 (to be built when no targets are specified on the command line)
-may be defined the SConscript file(s)
+may be defined in the SConscript file(s)
 using the
 <emphasis role="bold">Default()</emphasis>
 function, described below.</para>
diff --git a/doc/user/command-line.xml b/doc/user/command-line.xml
index 1b329e7..d129d2e 100644
--- a/doc/user/command-line.xml
+++ b/doc/user/command-line.xml
@@ -1987,17 +1987,16 @@ foo.c
 
       <para>
 
-      One of the most basic things you can control
-      is which targets &SCons; will build by default--that is,
+      You can control
+      which targets &SCons; will build by default - that is,
       when there are no targets specified on the command line.
       As mentioned previously,
       &SCons; will normally build every target
-      in or below the current directory
-      by default--that is, when you don't
+      in or below the current directory unless you
       explicitly specify one or more targets
       on the command line.
       Sometimes, however, you may want
-      to specify explicitly that only
+      to specify that only
       certain programs, or programs in certain directories,
       should be built by default.
       You do this with the &Default; function:
@@ -2193,7 +2192,8 @@ prog2.c
         <para>
 
         &SCons; supports a &DEFAULT_TARGETS; variable
-        that lets you get at the current list of default targets.
+        that lets you get at the current list of default targets
+        specified by calls to the &Default; function or method.
         The &DEFAULT_TARGETS; variable has
         two important differences from the &COMMAND_LINE_TARGETS; variable.
         First, the &DEFAULT_TARGETS; variable is a list of
@@ -2233,7 +2233,7 @@ prog1.c
         <para>
 
         Second,
-        the contents of the &DEFAULT_TARGETS; list change
+        the contents of the &DEFAULT_TARGETS; list changes
         in response to calls to the &Default; function,
         as you can see from the following &SConstruct; file:
 
@@ -2351,7 +2351,9 @@ prog2.c
 
       Notice how the value of &BUILD_TARGETS;
       changes depending on whether a target is
-      specified on the command line:
+      specified on the command line - &BUILD_TARGETS;
+      takes from  &DEFAULT_TARGETS;
+      only if there are no &COMMAND_LINE_TARGETS;:
 
       </para>
 
diff --git a/src/CHANGES.txt b/src/CHANGES.txt
index c6d7191..5fa5eab 100755
--- a/src/CHANGES.txt
+++ b/src/CHANGES.txt
@@ -32,6 +32,7 @@ RELEASE 3.0.4 - Mon, 20 Jan 2019 22:49:27 +0000
       product from the default Visual Studio
     - Add TEMPFILESUFFIX to allow a customizable filename extension, as
       described in the patch attached to issue #2431.
+    - Doc updates around Default(), and the various *TARGETS variables.
 
   From Daniel Moody:
     - Improved support for VC14.1 and Visual Studio 2017, as well as arm and arm64 targets.
@@ -43,6 +44,7 @@ RELEASE 3.0.4 - Mon, 20 Jan 2019 22:49:27 +0000
     - Enhance cpp scanner regex logic to detect if/elif expressions without whitespaces but
       parenthesis like "#if(defined FOO)" or "#elif!(BAR)" correctly.
 
+
 RELEASE 3.0.3 - Mon, 07 Jan 2019 20:05:22 -0400
   NOTE: 3.0.2 release was dropped because there was a packaging bug. Please consider all 3.0.2
         content.
diff --git a/src/engine/SCons/Script/SConscript.xml b/src/engine/SCons/Script/SConscript.xml
index a6258c4..330a56c 100644
--- a/src/engine/SCons/Script/SConscript.xml
+++ b/src/engine/SCons/Script/SConscript.xml
@@ -38,6 +38,10 @@ Multiple calls to
 &f-Default;
 are legal,
 and add to the list of default targets.
+As noted above, both forms of this call affect the
+same global list of default targets; the
+construction environment method applies
+construction variable expansion to the targets.
 </para>
 
 <para>