Update docs for Variables

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

6 files changed, 456 insertions, 294 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index e938a74..45a195d 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -40,6 +40,7 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
       build pdf versions which are then ignored.
     - Add the ability to print a Variables object for debugging purposes
       (provides a __str__ method in the class).
+    - Update manpage and user guide for Variables usage.
 
 
 RELEASE 4.7.0 -  Sun, 17 Mar 2024 17:22:20 -0700
diff --git a/RELEASE.txt b/RELEASE.txt
index 12d4b07..661cddf 100644
--- a/RELEASE.txt
+++ b/RELEASE.txt
@@ -63,6 +63,7 @@ DOCUMENTATION
 
 - Updated Value Node docs.
 - Update manpage for Tools, and for the TOOL variable.
+- Update manpage and user guide for Variables usage.
 
 
 
diff --git a/doc/man/scons.xml b/doc/man/scons.xml
index 0ac9916..e62e734 100644
--- a/doc/man/scons.xml
+++ b/doc/man/scons.xml
@@ -108,7 +108,7 @@ details do not have to be recalculated each run.
 
 <para>&scons; requires &Python; 3.6 or later to run;
 there should be no other dependencies or requirements,
-unless the experimental Ninja tool is used.
+unless the experimental Ninja tool is used (requires the ninja package).
 </para>
 <para>
 <emphasis>Changed in version 4.3.0:</emphasis>
@@ -4654,63 +4654,94 @@ env = conf.Finish()
 <title>Command-Line Construction Variables</title>
 
 <para>Often when building software,
-some variables need to be specified at build time.
-For example, libraries needed for the build may be in non-standard
-locations, or site-specific compiler options may need to be passed to the
-compiler.
-&SCons;
-provides a <firstterm>&Variables;</firstterm>
-object to support overriding &consvars; with values obtained
-from various sources, often from the command line:</para>
+specialized information needs to be conveyed at build time
+to override the defaults in the build scripts.
+Commandline arguments (like <literal>--implcit-cache</literal>)
+and giving names of build targets are two ways to do that.
+Another is to provide variable-assignment arguments
+on the command line.
+For the particular case where you want to specify new
+values for &consvars;,
+&SCons; provides a <firstterm>&Variables;</firstterm>
+object to simplify collecting those
+and updating a &consenv; with the values.
+The typical calling style looks like:
+</para>
 
 <screen>
 <userinput>scons VARIABLE=foo</userinput>
 </screen>
 
-<para>The variable values can also be specified in a configuration file
-or an &SConscript; file.</para>
+<para>
+Variables specified in the above way
+can be manually processed by accessing the
+<link linkend="v-ARGUMENTS">&ARGUMENTS;</link> dictionary
+(or <link linkend="v-ARGLIST">&ARGLIST;</link> list),
+but using a &Variables; object allows you to describe anticipated
+variables and structure them into types with validation,
+value conversion, defaults, help messages and aliases,
+conceptually similar to the structure of options
+(see &f-link-AddOption;).
+It also allows pulling variables from a saved
+configuration file or a custom dictionary in an &SConscript; file.
+The processed variables can then be applied to the desired &consenv;.
+</para>
+
+<para>
+Conceptually, arguments are used to convey information to the
+&SCons; program about how it should behave;
+variables are used to convey information to the build
+(though the line between the two is certainly not absolute).
+</para>
 
-<para>To obtain the object for manipulating values,
-call the &Variables; function:</para>
+<para>To obtain an object for manipulating variables,
+call the &Variables; factory function:</para>
 
 <variablelist>
   <varlistentry id="v-Variables">
   <term><function>Variables</function>([<parameter>files, [args]]</parameter>)</term>
   <listitem>
-<para>If <parameter>files</parameter> is a file or
-list of files, they are executed as &Python; scripts,
-and the values of (global) &Python; variables set in
-those files are added as &consvars; in the &DefEnv;.
-If no files are specified,
+<para>If <parameter>files</parameter> is a file or list of files,
+they are considered to be &Python; scripts which will
+be executed when the
+<link linkend='v-Update'><function>Update</function></link>
+method is called -
+this allows the use of &Python; syntax in the assignments.
+If <parameter>files</parameter> is not specified,
 or the
 <parameter>files</parameter>
 argument is
 <constant>None</constant>,
 then no files will be read
-(supplying <constant>None</constant> is necessary
+(supplying <constant>None</constant> is required
 if there are no files but you want to specify
-<parameter>args</parameter> as a positional argument).
+<parameter>args</parameter> as a positional argument;
+this can be omitted if using the keyword argument style).
 </para>
 
 <para>
-The following example file
+Either of the following example file
 contents could be used to set an alternative C compiler:</para>
 
 <programlisting language="python">
 CC = 'my_cc'
+CC = os.environ.get('CC')
 </programlisting>
 
 <para>If
 <parameter>args</parameter>
-is specified, it is a dictionary of
-values that will override anything read from
-<parameter>files</parameter>.
-The primary use is to pass the
+is specified, it must be a dictionary.
+The key-value pairs will be added to those
+obtained from
+<parameter>files</parameter>, if any.
+Keys from <parameter>args</parameter>
+take precendence over same-named keys from <parameter>files</parameter>.
+The most common usage is to pass the
 &ARGUMENTS; dictionary that holds variables
 specified on the command line,
 allowing you to indicate that if a setting appears
 on both the command line and in the file(s),
-the command line setting takes precedence.
+the command line setting is preferred.
 However, any dictionary can be passed.
 Examples:</para>
 
@@ -4718,6 +4749,7 @@ Examples:</para>
 vars = Variables('custom.py')
 vars = Variables('overrides.py', ARGUMENTS)
 vars = Variables(None, {FOO:'expansion', BAR:7})
+vars = Variables(args={FOO:'expansion', BAR:7})
 </programlisting>
 
 <para>
@@ -4727,24 +4759,57 @@ Calling &Variables; with no arguments is equivalent to:
 vars = Variables(files=None, args=ARGUMENTS)
 </programlisting>
 
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+A &Variables; object serves as a container for
+descriptions of variables,
+which are added by calling methods of the object.
+Each variable consists of a name (which will
+become a &consvar;), aliases for the name,
+a help message, a default value,
+and functions to validate and convert values.
+Once the object is asked to process variables,
+it matches up data from the input
+sources it was given with the definitions,
+and generates key-value pairs which are added
+to the specified &consenv;,
+except that if any variable was described
+to have a default of <literal>None</literal>,
+it is <emphasis>not</emphasis> added to
+the construction environment unless it
+appears in the input sources.
+Otherwise, a variable not in the
+input sources is added using its default value.
+</para>
+
 <para>
 Note that since the variables are eventually added as &consvars;,
 you should choose variable names which do not unintentionally change
 pre-defined &consvars; that your project will make use of
-(see <xref linkend="construction_variables"/>).
+(see <xref linkend="construction_variables"/> for a reference),
+since variables obtained have values overridden, not merged.
 </para>
 
-  </listitem>
-  </varlistentry>
-  </variablelist>
+<para>
+Also note there is currently no way to use the &Variables;
+mechanism to define a variable which the user is
+<emphasis>required</emphasis> to supply;
+if necessary this can be implemented by accessing
+<link linkend="v-ARGUMENTS">&ARGUMENTS;</link> directly,
+although that only applies to the command-line,
+not to any stored-values files.
+</para>
 
-<para>Variables objects have the following methods:</para>
+<para>A Variables object has the following methods:</para>
 
-  <variablelist>
+<variablelist>
   <varlistentry id="v-Add">
   <term><replaceable>vars</replaceable>.<function>Add</function>(<parameter>key, [help, default, validator, converter]</parameter>)</term>
   <listitem>
-<para>Add a customizable &consvar; to the Variables object.
+<para>Add a customizable &consvar; to the &Variables; object.
 <parameter>key</parameter>
 is either the name of the variable,
 or a tuple (or list), in which case
@@ -4756,45 +4821,48 @@ is the help text for the variable
 <parameter>default</parameter>
 is the default value of the variable
 (default <constant>None</constant>).
-If <parameter>default</parameter> is
-<constant>None</constant>
-and a value is not specified,
-the &consvar; will not
-be added to the &consenv;.
 </para>
+
+<para>
+If the optional <parameter>validator</parameter> argument is supplied,
+it is a callback function to validate the value of the variable.
+A validator function must accept three arguments:
+<parameter>key</parameter>,
+<parameter>value</parameter>
+and <parameter>env</parameter>,
+and should raise an exception (with a helpful error message)
+if <parameter>value</parameter> is invalid.
+No return value is expected from the validator.
+</para>
+
+<para>
+If the optional <parameter>converter</parameter> argument is supplied,
+it is a callback function to convert the value into
+one suitable for adding to the environment,
+and should accept either a value
+or a value and &consenv; as parameters.
+The converter is called before the validator;
+it must return a value, which is then passed to the
+<parameter>validator</parameter> (if any)
+and finally added to the &consenv; -
+it is recommended to avoid performing validation
+checks in the converter.
+</para>
+
 <para>
 As a special case, if <parameter>key</parameter>
 is a tuple (or list) and is the <emphasis>only</emphasis>
 argument, the tuple is unpacked into the five parameters
 listed above left to right, with any missing members filled with
-the respecitive default values. This form allows <function>Add</function>
+the respective default values. This form allows &Add;
 to consume a tuple emitted by the convenience functions
-<link linkend='v-BoolVariable'><function>BoolVariable</function></link>,
-<link linkend='v-EnumVariable'><function>EnumVariable</function></link>,
-<link linkend='v-ListVariable'><function>ListVariable</function></link>,
-<link linkend='v-PackageVariable'><function>PackageVariable</function></link>
+<link linkend='v-BoolVariable'>&BoolVariable;</link>,
+<link linkend='v-EnumVariable'>&EnumVariable;</link>,
+<link linkend='v-ListVariable'>&ListVariable;</link>,
+<link linkend='v-PackageVariable'>&PackageVariable;</link>
 and
-<link linkend='v-PathVariable'><function>PathVariable</function></link>.
+<link linkend='v-PathVariable'>&PathVariable;</link>.
 </para>
-<para>
-If the optional <parameter>validator</parameter> is supplied,
-it is called to validate the value of the variable.
-A function supplied as a validator must accept
-three arguments: <parameter>key</parameter>,
-<parameter>value</parameter> and <parameter>env</parameter>,
-and should raise an exception with a helpful error message
-if <parameter>value</parameter> is invalid.
-No return value is expected from the validator.
-</para>
-<para>
-If the optional <parameter>converter</parameter> is supplied,
-it is called to convert the value before putting it in the environment,
-and should take either a value
-or a value and environment as parameters.
-The converter function must return a value,
-which will be converted into a string and be passed to the
-<parameter>validator</parameter> (if any)
-and then added to the &consenv;.</para>
 
 <para>Examples:</para>
 
@@ -4815,7 +4883,7 @@ vars.Add('COLOR', validator=valid_color)
   <listitem>
 <para>A convenience method that adds
 one or more customizable &consvars;
-to a Variables object in one call;
+to a &Variables; object in one call;
 equivalent to calling &Add; multiple times.
 The <parameter>args</parameter>
 are tuples (or lists)
@@ -4843,24 +4911,30 @@ opt.AddVariables(
   <varlistentry id="v-Update">
   <term><replaceable>vars</replaceable>.<function>Update</function>(<parameter>env, [args]</parameter>)</term>
   <listitem>
-<para>Update a &consenv;
+<para>Process the arguments given as
+<parameter>files</parameter> and/or
+<parameter>args</parameter>
+when the &Variables; object was created,
+and update
 <parameter>env</parameter>
 with the customized &consvars;.
 Any specified variables that are not
-configured for the Variables object
-will be saved and may be
-retrieved using the
+configured in the &Variables; object
+will be saved and may be retrieved using the
 <link linkend='v-UnknownVariables'>&UnknownVariables;</link>
 method.</para>
 
-<para>Normally this method is not called directly,
-but rather invoked indirectly by passing the Variables object to
+<para>Normally, &Update; is not called directly,
+but rather invoked indirectly by passing the &Variables; object to
 the &f-link-Environment; function:</para>
 
 <programlisting language="python">
-env = Environment(variables=vars)
+env = Environment(..., variables=vars)
 </programlisting>
 
+<para>
+</para>
+
   </listitem>
   </varlistentry>
 
@@ -4868,11 +4942,15 @@ env = Environment(variables=vars)
   <term><replaceable>vars</replaceable>.<function>UnknownVariables</function>()</term>
   <listitem>
 <para>Returns a dictionary containing any
-variables that were specified
-either in the files or the dictionary
-with which the Variables object was initialized,
-but for which the Variables object was
-not configured.</para>
+variables that were specified in the
+<parameter>files</parameter> and/or
+<parameter>args</parameter> parameters
+when <link linkend='v-Variables'>&Variables;</link>
+was called, but the object was not actually configured for.
+This information is not available until the
+<link linkend='v-Update'><function>Update</function></link>
+method has run.
+</para>
 
 <programlisting language="python">
 env = Environment(variables=vars)
@@ -4886,13 +4964,14 @@ for key, value in vars.UnknownVariables():
   <varlistentry id="v-Save">
   <term><replaceable>vars</replaceable>.<function>Save</function>(<parameter>filename, env</parameter>)</term>
   <listitem>
-<para>Save the currently set variables into a script file named
-by <parameter>filename</parameter>. Only variables that are
-set to non-default values are saved.
-You can load these saved settings on a subsequent run
+<para>Saves the currently set variables into a script file named
+by <parameter>filename</parameter>.
+This provides a way to cache particular variable settings for reuse.
+Only variables that are set to non-default values are saved.
+You can load these saved variables on a subsequent run
 by passing <parameter>filename</parameter> to the
 <link linkend='v-Variables'>&Variables;</link> function,
-providing a way to cache particular settings for reuse.
+
 </para>
 
 <programlisting language="python">
@@ -4909,22 +4988,28 @@ vars.Save('variables.cache', env)
   <varlistentry id="v-GenerateHelpText">
   <term><replaceable>vars</replaceable>.<function>GenerateHelpText</function>(<parameter>env, [sort]</parameter>)</term>
   <listitem>
-<para>Generate help text documenting the customizable construction
-variables, suitable for passing in to the &f-link-Help; function.
-<parameter>env</parameter>
-is the &consenv; that will be used to get the actual values
-of the customizable variables. If the (optional)
-value of <parameter>sort</parameter>
-is callable, it is used as a comparison function to
+<para>
+Return a formatted string with the help text collected
+from all the variables configured in this &Variables; object.
+This string is suitable for passing in to the &f-link-Help; function.
+The generated string include an indication of the
+actual value in the environment given by <parameter>env</parameter>.
+</para>
+
+<para>
+If the optional
+<parameter>sort</parameter> parameter is set to
+a callable value, it is used as a comparison function to
 determine how to sort the added variables.
 This function must accept two arguments, compare them,
 and return a negative integer if the first is
-less-than the second, zero for equality, or a positive integer
-for greater-than.
-
-Optionally a Boolean value of <constant>True</constant>
-for <parameter>sort</parameter> will cause a standard
-alphabetical sort to be performed.</para>
+less-than the second, zero if equal, or a positive integer
+if greater-than.
+If <parameter>sort</parameter> is not callable,
+but is set to <constant>True</constant>,
+an alphabetical sort is performed.
+The default is <constant>False</constant> (unsorted).
+</para>
 
 <programlisting language="python">
 Help(vars.GenerateHelpText(env))
@@ -4943,7 +5028,7 @@ Help(vars.GenerateHelpText(env, sort=cmp))
   <listitem>
 <para>Returns a formatted string
 containing the printable help text
-for one option.
+for the single option <parameter>opt</parameter>.
 It is normally not called directly,
 but is called by the &GenerateHelpText;
 method to create the returned help text.
@@ -4965,31 +5050,30 @@ vars.FormatVariableHelpText = my_format
 </programlisting>
   </listitem>
   </varlistentry>
-  </variablelist>
+</variablelist>
 
 
-<para>To make it more convenient to work with customizable Variables,
-&scons;
-provides a number of functions
-that make it easy to set up
-various types of Variables.
-Each of these return a tuple ready to be passed to
+<para>
+To make it more convenient to describe custom variables,
+&SCons; provides some pre-defined variable types,
+acessible through factory functions that generate
+a tuple appropriate for directly passing to
 the &Add; or &AddVariables; method:</para>
 
-  <variablelist>
+<variablelist>
   <varlistentry id="v-BoolVariable">
   <term><function>BoolVariable</function>(<parameter>key, help, default</parameter>)</term>
   <listitem>
-<para>Return a tuple of arguments
-to set up a Boolean option.
-The option will use
+<para>
+Set up a Boolean variable.
+The variable will use
 the specified name
 <parameter>key</parameter>,
 have a default value of
 <parameter>default</parameter>,
 and <parameter>help</parameter>
 will form the descriptive part of the help text.
-The option will interpret the command-line values
+The variable will interpret the command-line values
 <userinput>y</userinput>,
 <userinput>yes</userinput>,
 <userinput>t</userinput>,
@@ -5015,30 +5099,26 @@ as false.</para>
   <varlistentry id="v-EnumVariable">
   <term><function>EnumVariable</function>(<parameter>key, help, default, allowed_values, [map, ignorecase]</parameter>)</term>
   <listitem>
-<para>Returns a tuple of arguments
-to set up an option
-whose value may be one
-of a specified list of legal enumerated values.
-The option will use
-the specified name
+<para>
+Set up a variable
+whose value may only be from
+a specified list ("enumeration") of values.
+The variable will have the name
 <parameter>key</parameter>,
 have a default value of
-<parameter>default</parameter>,
+<parameter>default</parameter>
 and <parameter>help</parameter>
 will form the descriptive part of the help text.
-The option will only support those
-values in the
+Any value that is not in
 <parameter>allowed_values</parameter>
-list.
-The optional
+will raise an error,
+except that the optional
 <parameter>map</parameter>
 argument is a dictionary
-that can be used to convert
-input values into specific legal values
-in the
-<parameter>allowed_values</parameter>
-list.
-If the value of
+that can be used to map additional names into
+a particular name in the
+<parameter>allowed_values</parameter> list.
+If the value of optional
 <parameter>ignore_case</parameter>
 is
 <literal>0</literal>
@@ -5064,23 +5144,21 @@ converted to lower case.</para>
   <varlistentry id="v-ListVariable">
   <term><function>ListVariable</function>(<parameter>key, help, default, names, [map]</parameter>)</term>
   <listitem>
-<para>Returns a tuple of arguments
-to set up an option
+<para>
+Set up a variable
 whose value may be one or more
-of a specified list of legal enumerated values.
-The option will use
-the specified name
+from a specified list of values.
+The variable will have the name
 <parameter>key</parameter>,
 have a default value of
 <parameter>default</parameter>,
 and <parameter>help</parameter>
 will form the descriptive part of the help text.
-The option will only accept the values
-<quote>all</quote>,
-<quote>none</quote>,
-or the values in the
-<parameter>names</parameter>
-list.
+Any value that is not in
+<parameter>names</parameter> or the special values
+<userinput>all</userinput> or
+<userinput>none</userinput>
+will raise an error.
 More than one value may be specified,
 separated by commas.
 The default may be a string of
@@ -5103,60 +5181,72 @@ reflected in the generated help message).  </para>
   <varlistentry id="v-PackageVariable">
   <term><function>PackageVariable</function>(<parameter>key, help, default</parameter>)</term>
   <listitem>
-<para>Returns a tuple of arguments
-to set up an option
-whose value is a path name
-of a package that may be
-enabled, disabled or
-given an explicit path name.
-The option will use
-the specified name
-<parameter>key</parameter>,
-have a default value of
+<para>
+Set up a variable for a <emphasis>package</emphasis>,
+where if the variable is specified,
+the &consvar; named by <parameter>key</parameter>
+will end with a value of <literal>True</literal>,
+<literal>False</literal>, or a user-specified value.
+For example,
+a package could be a third-party software component,
+the build could use the information to
+exclude the package, include the package in the standard way,
+or include the package using a specified
+directory path to find the package files.
+</para>
+<para>
+The variable will have a default value
 <parameter>default</parameter>,
 and <parameter>help</parameter>
 will form the descriptive part of the help text.
-The option will support the values
+The variable supports (case-insensitive) truthy values
+<userinput>1</userinput>,
 <userinput>yes</userinput>,
 <userinput>true</userinput>,
 <userinput>on</userinput>,
 <userinput>enable</userinput>
-or
-<userinput>search</userinput>,
-in which case the specified
-<parameter>default</parameter>
-will be used,
-or the option may be set to an
-arbitrary string
-(typically the path name to a package
-that is being enabled).
-The option will also support the values
+and
+<userinput>search</userinput>
+to indicate the package is "enabled",
+and the (case-insensitive) falsy values
+<userinput>0</userinput>,
 <userinput>no</userinput>,
 <userinput>false</userinput>,
 <userinput>off</userinput>
-or
+and
 <userinput>disable</userinput>
-to disable use of the specified option.</para>
+to indicate the package is "disabled".
+</para>
+<para>
+The value
+of the variable may also be set to an
+arbitrary string,
+which is taken to be the path name to the package
+that is being enabled.
+The validator will raise an exception
+if this path does not exist in the filesystem.
+</para>
   </listitem>
   </varlistentry>
 
   <varlistentry id="v-PathVariable">
   <term><function>PathVariable</function>(<parameter>key, help, default, [validator]</parameter>)</term>
   <listitem>
-<para>Returns a tuple of arguments
-to set up an option
+<para>
+Set up a variable
 whose value is expected to be a path name.
-The option will use
-the specified name
-<parameter>key</parameter>,
-have a default value of
+The &consvar; named by <parameter>key</parameter>
+will have have a default value of
 <parameter>default</parameter>,
 and <parameter>help</parameter>
 will form the descriptive part of the help text.
-An additional
-<parameter>validator</parameter>
-may be specified
-that will be called to
+</para>
+
+<para>
+An optional
+<parameter>validator</parameter> argument
+may be specified.
+The validator will be called to
 verify that the specified path
 is acceptable.
 SCons supplies the
@@ -5209,14 +5299,14 @@ created as part of the build process, for example.</para>
 You may supply your own
 <emphasis>validator</emphasis>
 function,
-which must accept three arguments
-(<parameter>key</parameter>,
+which must accept three arguments:
+<parameter>key</parameter>,
 the name of the variable to be set;
 <parameter>val</parameter>,
 the specified value being checked;
 and
 <parameter>env</parameter>,
-the &consenv;)
+the &consenv;,
 and should raise an exception
 if the specified value is not acceptable.</para>
   </listitem>
diff --git a/doc/scons.mod b/doc/scons.mod
index 2288879..e954916 100644
--- a/doc/scons.mod
+++ b/doc/scons.mod
@@ -291,6 +291,7 @@
 <!ENTITY Touch "<function xmlns='http://www.scons.org/dbxsd/v1.0'>Touch</function>">
 <!ENTITY UnknownOptions "<function xmlns='http://www.scons.org/dbxsd/v1.0'>UnknownOptions</function>">
 <!ENTITY UnknownVariables "<function xmlns='http://www.scons.org/dbxsd/v1.0'>UnknownVariables</function>">
+<!ENTITY Update "<function xmlns='http://www.scons.org/dbxsd/v1.0'>Update</function>">
 
 
 <!-- Environment methods -->
diff --git a/doc/user/command-line.xml b/doc/user/command-line.xml
index d8f9389..ede4825 100644
--- a/doc/user/command-line.xml
+++ b/doc/user/command-line.xml
@@ -26,11 +26,10 @@ SPDX-License-Identifier: MIT
          xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
 <title>Controlling a Build From the Command Line</title>
 
-<para>
+  <para>
 
   &SCons; provides a number of ways
-  for you as the writer of the &SConscript; files
-  to give you (and your users)
+  for you as the build system writer to grant
   the ability to control the build execution.
   The arguments that can be specified on
   the command line are broken down into three types:
@@ -45,12 +44,13 @@ SPDX-License-Identifier: MIT
     <listitem>
     <para>
 
-    Command-line options always begin with
-    one or two <literal>-</literal> (hyphen) characters.
+    Command-line arguments that begin with a
+    <literal>-</literal> (hyphen) characters
+    are called <firstterm>options</firstterm>.
     &SCons; provides ways for you to examine
-    and set options values from within your &SConscript; files,
-    as well as the ability to define your own
-    custom options.
+    and act on options and their values,
+    as well as the ability to define custom options
+    for your project.
     See <xref linkend="sect-command-line-options"></xref>, below.
 
     </para>
@@ -63,17 +63,16 @@ SPDX-License-Identifier: MIT
     <listitem>
     <para>
 
-    Any command-line argument containing an <literal>=</literal>
-    (equal sign) is considered a variable setting with the form
-    <varname>variable</varname>=<replaceable>value</replaceable>.
+    Command-line arguments containing an <literal>=</literal>
+    (equal sign) character are called <firstterm>build variables</firstterm>
+    (or just <firstterm>variables</firstterm>).
     &SCons; provides direct access to
-    all of the command-line variable settings,
-    the ability to apply command-line variable settings
-    to &consenvs;,
-    and functions for configuring
-    specific types of variables
-    (Boolean values, path names, etc.)
-    with automatic validation of the specified values.
+    all of the build variable settings from the command line,
+    as well as a higher-level interface that lets you
+    define known build variables,
+    including defining types, default vaules, help text,
+    and automatic validation,
+    as well as applying those to a &consenv;.
     See <xref linkend="sect-command-line-variables"></xref>, below.
 
     </para>
@@ -86,12 +85,12 @@ SPDX-License-Identifier: MIT
     <listitem>
     <para>
 
-    Any command-line argument that is not an option
-    or a variable setting
-    (does not begin with a hyphen
-    and does not contain an equal sign)
-    is considered a target that the you
-    are telling &SCons; to build.
+    Command-line arguments that are neither options
+    nor build variables
+    (that is, do not begin with a hyphen
+    and do not contain an equal sign)
+    are considered <firstterm>targets</firstterm>
+    that you are telling &SCons; to build.
     &SCons; provides access to the list of specified targets,
     as well as ways to set the default list of targets
     from within the &SConscript; files.
@@ -108,21 +107,22 @@ SPDX-License-Identifier: MIT
 
     <para>
 
-    &SCons; has many <firstterm>command-line options</firstterm>
-    that control its behavior.
-    An &SCons; command-line option
-    always begins with one or two hyphen (<literal>-</literal>)
-    characters.
+    &SCons; has many command-line options that control its behavior.
+    A command-line option always begins with one
+    or two hyphen (<literal>-</literal>) characters.
+    The &SCons; manual page contains the description of
+    the current options
+    (see <ulink url="https://scons.org/doc/production/HTML/scons-man.html"/>).
 
     </para>
 
-    <section>
+    <section id="sect-SCONSFLAGS">
     <title>Not Having to Specify Command-Line Options Each Time:  the &SCONSFLAGS; Environment Variable</title>
 
       <para>
 
       You may find yourself using
-      the same command-line options every time
+      certain command-line options every time
       you run &SCons;.
       For example, you might find it saves time
       to specify <userinput>-j 2</userinput>
@@ -209,35 +209,33 @@ C:\Users\foo> <userinput>set SCONSFLAGS="-Q"</userinput>
 
     </section>
 
-    <section>
+    <section id="sect-GetOption">
     <title>Getting Values Set by Command-Line Options:  the &GetOption; Function</title>
 
       <para>
 
       &SCons; provides the &f-link-GetOption; function
-      to get the values set by the various command-line options.
+      to query the values set by the various command-line options.
 
       </para>
 
       <para>
 
-      One use case for &GetOption; is to check whether or not
-      the <option>-h</option> or <option>--help</option> option
-      has been specified.
+      One use case for &GetOption; is to check the operation
+      mode in order to bypass some steps,
+      for example, checking whether
+      the <option>-h</option> (or <option>--help</option>)
+      option was given.
       Normally, &SCons; does not print its help text
       until after it has read all of the SConscript files,
-      because it's possible that help text has been added
-      by some subsidiary SConscript file deep in the
-      source tree hierarchy.
+      since any SConscript can make additions to the help text.
       Of course, reading all of the SConscript files
       takes extra time.
       If you know that your configuration does not define
       any additional help text in subsidiary SConscript files,
       you can speed up displaying the command-line help
-      by using the &GetOption; function to load the
-      subsidiary SConscript files only if
-      the <option>-h</option> or <option>--help</option> option
-      has <emphasis>not</emphasis> been specified like this:
+      by using a &GetOption; query as a guard for whether
+      to load the subsidiary SConscript files:
 
       </para>
 
@@ -248,6 +246,15 @@ if not GetOption('help'):
 
       <para>
 
+      The same technique can be used to special-case the
+      clean (<literal>GetOption('clean')</literal>)
+      and no-execute (<literal>GetOption('no_exec')</literal>)
+      modes.
+
+      </para>
+
+      <para>
+
       In general, the string that you pass to the
       &f-GetOption; function to fetch the value of a command-line
       option setting is the same as the "most common" long option name
@@ -265,7 +272,9 @@ if not GetOption('help'):
 
       &f-GetOption; can be used to retrieve the values of options
       defined by calls to &f-link-AddOption;. A &f-GetOption; call
-      must appear after the &f-AddOption; call for that option.
+      must appear after the &f-AddOption; call for that option
+      (unlike the defining of build targets,
+      this is a case where "order matters" in &SCons;).
       If the &f-AddOption; call supplied a <parameter>dest</parameter>
       keyword argument, a string with that name is what to pass
       as the argument to &f-GetOption;, otherwise it is a
@@ -276,12 +285,12 @@ if not GetOption('help'):
 
     </section>
 
-    <section>
+    <section id="sect-SetOption">
     <title>Setting Values of Command-Line Options:  the &SetOption; Function</title>
 
       <para>
 
-      You can also set the values of &SCons;
+      You can also set the values of certain (but not all) &SCons;
       command-line options from within the &SConscript; files
       by using the &f-link-SetOption; function.
       The strings that you use to set the values of &SCons;
@@ -610,16 +619,17 @@ foo.in
 
     </section>
 
-    <section>
+    <section id="sec-AddOption">
     <title>Adding Custom Command-Line Options:  the &AddOption; Function</title>
 
       <para>
 
-      &SCons; also allows you to define your own
-      command-line options with the &f-link-AddOption; function.
+      &SCons; lets you define your own command-line options
+      for the project with the &f-link-AddOption; function.
       The &AddOption; function takes the same arguments
       as the <function>add_option</function> method
-      from the standard Python library module <emphasis>optparse</emphasis>.
+      from the &Python; standard library module
+      <systemitem>optparse</systemitem>
       <footnote>
       <para>
       The &AddOption; function is,
@@ -627,13 +637,14 @@ foo.in
       of <classname>optparse.OptionParser</classname>.
       </para>
       </footnote>
+      (see <ulink url="https://docs.python.org/3/library/optparse.html"/>).
       </para>
 
       <para>
       Once you add a custom command-line option
       with the &AddOption; function,
       the value of the option (if any) is immediately available
-      using the standard &f-link-GetOption; function.
+      using the &f-link-GetOption; function.
       The argument to &f-GetOption; must be the name of the
       variable which holds the option.
       If the <parameter>dest</parameter>
@@ -723,35 +734,42 @@ foo.in
 
       <note>
       <para>
-      Option-arguments separated from long options by whitespace,
-      rather than by an <literal>=</literal>, cannot be correctly
-      resolved by &SCons;.
-      While <option>--input=ARG</option>
-      is clearly opt followed by arg, for <option>--input ARG</option>
+      The <systemitem>optparse</systemitem> parser which &SCons; uses
+      allows option-arguments to follow their options after either
+      an <literal>=</literal> or space separator,
+      however the latter form does not work well in &SCons; for
+      added options and should be avoided.
+      &SCons; does not place an ordering constraint on the
+      types of command-line arguments,
+      so while <option>--input=ARG</option> is unambiguous,
+      for <option>--input ARG</option>
       it is not possible to tell without instructions whether
       <parameter>ARG</parameter> is an argument belonging to the
-      <parameter>input</parameter> option or a positional argument.
-      &SCons; treats positional arguments as either
-      command-line build options or command-line targets
-      which are made available for use in an &SConscript;
+      <parameter>input</parameter> option or a standalone word.
+      &SCons; considers words on the command line which do not
+      begin with hyphen as either command-line build variables
+      or command-line targets,
+      both of which are made available for use in an &SConscript;
       (see the immediately following sections for details).
       Thus, they must be collected before &SConscript; processing
-      takes place. Since &AddOption; calls, which provide
-      the processing instructions to resolve any ambiguity,
-      happen in an &SConscript;,
-      &SCons; does not know in time
-      for options added this way, and unexpected things happen,
-      such as option-arguments assigned as targets and/or exceptions
-      due to missing option-arguments.
-      </para>
-      <para>
-      As a result, this usage style should be avoided when invoking
-      &scons;.  For single-argument
-      options, use the <option>--input=ARG</option> form on the
-      command line. For multiple-argument options
-      (<parameter>nargs</parameter> greater than one),
-      set <parameter>nargs</parameter> to one in
-      &AddOption; calls and either: combine the option-arguments into one word
+      takes place. &AddOption; calls do provide the
+      the necessary instructions to resolve the ambiguity,
+      but as they appear in &SConscript; files,
+      &SCons; does not have the information early enough,
+      and unexpected things may happen,
+      such as option-arguments appearing in the list of targets,
+      and processing exceptions due to missing option-arguments.
+      </para>
+      <para>
+      As a result,
+      this usage style should be avoided when invoking &scons;.
+      For single-argument options,
+      tell your users to use the <option>--input=ARG</option>
+      form on the command line.
+      For multiple-argument options
+      (<parameter>nargs</parameter> value greater than one),
+      set <parameter>nargs</parameter> to one in the
+      &AddOption; call and either: combine the option-arguments into one word
       with a separator, and parse the result in your own code
       (see the built-in <option>--debug</option> option, which
       allows specifying multiple arguments as a single comma-separated
@@ -795,7 +813,7 @@ foo.in
     aspects of your build in response
     to specifications on the command line.
     (Note that unless you want to require
-    a variable <emphasis>always</emphasis>
+    a variable to <emphasis>always</emphasis>
     be specified you probably want to use
     the Python dictionary <methodname>get</methodname> method,
     which allows you to designate a default value
@@ -841,9 +859,38 @@ prog.c
        <scons_output_command>scons -Q debug=1</scons_output_command>
     </scons_output>
 
+    <note><para>
+
+    Two usage notes (both shown in the example above):
+
+    <itemizedlist>
+      <listitem>
+        <para>
+          No matter how you intend to use them, the values read from
+          a command line (i.e., external to the program) are
+          always strings. You may need to do type conversion.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          When you retrieve from the &ARGUMENTS; dictionary,
+          it is useful to use the &Python; dictionary
+          <methodname>get</methodname> method,
+          so you can supply a default value if there is not
+          one given on the command line. Otherwise, the build
+          will fail with a <exceptionname>KeyError</exceptionname>
+          if the user does not supply the build option.
+        </para>
+      </listitem>
+    </itemizedlist>
+
+
+
+    </para></note>
+
     <para>
 
-    &SCons; keeps track of the precise command line used to build each object file,
+    &SCons; keeps track of the precise build command used to build each object file,
     and as a result can determine that the object and executable files
     need rebuilding when the value of the <parameter>debug</parameter>
     argument has changed.
@@ -854,7 +901,7 @@ prog.c
 
     The &ARGUMENTS; dictionary has two minor drawbacks.
     First, because it is a dictionary,
-    it can only store one value for each specified keyword,
+    it can only map each keyword to one value,
     and thus only "remembers" the last setting
     for each keyword on the command line.
     This makes the &ARGUMENTS; dictionary
@@ -868,17 +915,18 @@ prog.c
     you want the configuration to
     behave differently in response
     to the order in which the build
-    variable settings were specified on the command line.
+    variable settings were specified on the command line
+    (&Python; versions since 3.6 now maintain dictionaries in
+    insertion order, so this problem is mitigated).
 
     </para>
 
     <para>
 
     To accomodate these requirements,
-    &SCons; provides an &ARGLIST; variable
-    that gives you direct access to
-    <varname>variable</varname>=<replaceable>value</replaceable>
-    settings on the command line,
+    &SCons; also provides an &ARGLIST; variable
+    that gives you direct access to build variable
+    settings from the command line,
     in the exact order they were specified,
     and without removing any duplicate settings.
     Each element in the &ARGLIST; variable
@@ -946,7 +994,7 @@ prog.c
 
     </para>
 
-    <section>
+    <section id="sect-controlling-cli-variables">
     <title>Controlling Command-Line Build Variables</title>
 
       <para>
@@ -958,8 +1006,8 @@ prog.c
       check for errors and provide appropriate messages,
       and apply the values to a &consvar;.
       To help with this,
-      &SCons; provides a &Variables; class to
-      define such build variables easily,
+      &SCons; provides a &Variables; container class to
+      hold defintions of such build variables,
       and a mechanism to apply the
       build variables to a &consenv;.
       This allows you to control how the build variables affect
@@ -974,7 +1022,7 @@ prog.c
       command line whenever the time comes to build
       a program for release,
       and that the value of this variable
-      should be added to the command line
+      should be added to the build command
       with the appropriate define
       to pass the value to the C compiler.
       Here's how you might do that by setting
@@ -1000,9 +1048,8 @@ bar.c
 
       <para>
 
-      This &SConstruct; file first creates a &Variables; object
-      which uses the values from the command-line options dictionary &ARGUMENTS;
-      (the <literal>vars=Variables(None, ARGUMENTS)</literal> call).
+      This &SConstruct; snippet first creates a &Variables; object which
+      uses the values from the command-line variables dictionary &ARGUMENTS;.
       It then uses the object's &Add;
       method to indicate that the &RELEASE;
       variable can be set on the command line, and that
@@ -1025,15 +1072,32 @@ bar.c
 
       <para>
 
-      Historical note:  In old &SCons; (prior to 0.98.1),
+      The <literal>Variables()</literal> call in this example looks
+      a little awkward. The function takes two optional arguments:
+      a script name and a dictionary.  In order to specify the
+      dictionary as the second argument, you must provide the
+      script argument as the first; since there's actually no script,
+      use <constant>None</constant> as a sentinel value.
+      However, if you omit all the arguments,
+      the default behavior is to read from the &ARGUMENTS; dictionary anyway,
+      which is what we want.  The example shows it this way because the arguments
+      were introduced in this order, but you should feel free to just
+      leave off the arguments if the default behavior is what you want.
+
+      </para>
+
+      <para>
+
+      Historical note:  In old &SCons; (prior to 0.98.1 from 2008),
       these build variables were known as "command-line build options."
-      At that time, class was named &Options;
+      At that time, the class was named &Options;
       and the predefined functions to construct options were named
       &BoolOption;, &EnumOption;, &ListOption;,
       &PathOption;, &PackageOption; and &AddOptions; (contrast
       with the current names in
       <xref linkend="sect-build-variable-functions"></xref>, below).
-      You may encounter these names in older
+      Because the Internet has a very long memory,
+      you may encounter these names in older
       &SConscript; files, wiki pages, blog entries, StackExchange
       articles, etc.
       These old names no longer work, but a mental substitution
@@ -1044,19 +1108,19 @@ bar.c
 
     </section>
 
-    <section>
+    <section id="secr-variables-help">
     <title>Providing Help for Command-Line Build Variables</title>
 
       <para>
 
-      To make command-line build variables most useful,
-      you ideally want to provide
+      To make command-line build variables more useful,
+      you may want to provide
       some help text to describe the available variables
-      when the you ask for help (run <userinput>scons -h</userinput>).
+      when you ask for help (run <userinput>scons -h</userinput>).
       You can write this text by hand,
       but &SCons; provides some assistance.
       Variables objects provide a
-      &GenerateHelpText; method the
+      &GenerateHelpText; method to
       generate text that describes
       the various variables that
       have been added to it. The default text includes
@@ -1072,7 +1136,7 @@ bar.c
 
       <scons_example name="commandline_Variables_Help">
         <file name="SConstruct" printme="1">
-vars = Variables(None, ARGUMENTS)
+vars = Variables()
 vars.Add('RELEASE', help='Set to 1 to build for release', default=0)
 env = Environment(variables=vars)
 Help(vars.GenerateHelpText(env))
@@ -1081,7 +1145,7 @@ Help(vars.GenerateHelpText(env))
 
       <para>
 
-      &SCons; now displays some useful text
+      &scons; now displays some useful text
       when the <option>-h</option> option is used:
 
       </para>
@@ -1099,7 +1163,7 @@ Help(vars.GenerateHelpText(env))
 
     </section>
 
-    <section>
+    <section id="sect-variables-file">
     <title>Reading Build Variables From a File</title>
 
       <para>
@@ -1112,8 +1176,7 @@ Help(vars.GenerateHelpText(env))
       every time you run &SCons;.
       To make this easier,
       you can provide customized build variable settings
-      in a local file by providing a
-      file name when the
+      in a &Python; script by providing a file name when the
       &Variables; object is created:
 
       </para>
@@ -1140,7 +1203,7 @@ RELEASE = 1
       <para>
 
       This then allows you to control the &RELEASE;
-      variable by setting it in the &custom_py; file:
+      variable by setting it in the &custom_py; script:
 
       </para>
 
@@ -1149,7 +1212,7 @@ RELEASE = 1
       <para>
 
       Note that this file is actually executed
-      like a Python script.
+      like a &Python; script.
       Now when you run &SCons;:
 
       </para>
@@ -1206,11 +1269,17 @@ vars = Variables('custom.py', ARGUMENTS)
 
       <para>
 
-      where values in the option file &custom_py; get overwritten
-      by the ones specified on the command line.
+      If both a variables script and a dictionary are supplied,
+      the dictionary is evaluated last, so values from the
+      command line "win" if there are any duplicate keys.
+      This rule allows you to move some common settings
+      to a variables script, but still be able to override those
+      for a given build without changing the script.
 
       </para>
 
+      <!-- TODO: maybe show a variable used to select between vairable scripts? -->
+
     </section>
 
     <section id="sect-build-variable-functions">
@@ -1219,7 +1288,7 @@ vars = Variables('custom.py', ARGUMENTS)
       <para>
 
       &SCons; provides a number of convenience functions
-      that provide ready-made behaviors
+      that provide pre-made behavior definitions
       for various types of command-line build variables.
       These functions all return a tuple which is ready
       to be passed to the &Add; or &AddVariables; method call.
@@ -1228,7 +1297,7 @@ vars = Variables('custom.py', ARGUMENTS)
 
       </para>
 
-      <section>
+      <section id="sect-variables-bool">
       <title>True/False Values:  the &BoolVariable; Build Variable Function</title>
 
         <para>
@@ -1340,7 +1409,7 @@ foo.c
 
       </section>
 
-      <section>
+      <section id="sect-variables-enum">
       <title>Single Value From a Selection:  the &EnumVariable; Build Variable Function</title>
 
         <para>
@@ -1576,7 +1645,7 @@ foo.c
 
       </section>
 
-      <section>
+      <section id="sect-variables-list">
       <title>Multiple Values From a List:  the &ListVariable; Build Variable Function</title>
 
         <para>
@@ -1670,7 +1739,7 @@ foo.c
 
       </section>
 
-      <section>
+      <section id="sect-variables-path">
       <title>Path Names:  the &PathVariable; Build Variable Function</title>
 
         <para>
@@ -1856,7 +1925,7 @@ foo.c
 
       </section>
 
-      <section>
+      <section id="sect-variables-package">
       <title>Enabled/Disabled Path Names: the &PackageVariable; Build Variable Function</title>
 
         <para>
@@ -1915,7 +1984,7 @@ foo.c
 
     </section>
 
-    <section>
+    <section id="sect-variables-multiple">
     <title>Adding Multiple Command-Line Build Variables at Once</title>
 
       <para>
@@ -1971,7 +2040,7 @@ vars.AddVariables(
 
     </section>
 
-    <section>
+    <section id="sect-variables-unknown">
     <title>Handling Unknown Command-Line Build Variables:  the &UnknownVariables; Function</title>
 
       <para>
@@ -2074,7 +2143,7 @@ foo.c
   <section id="sect-command-line-targets">
   <title>Command-Line Targets</title>
 
-    <section>
+    <section id="sect-var-COMMAND-LINE-TARGETS">
     <title>Fetching Command-Line Targets: the &COMMAND_LINE_TARGETS; Variable</title>
 
       <para>
@@ -2132,7 +2201,7 @@ foo.c
 
     </section>
 
-    <section>
+    <section id="sect-default-targets-function">
     <title>Controlling the Default Targets:  the &Default; Function</title>
 
       <para>
@@ -2336,7 +2405,7 @@ prog2.c
          <scons_output_command>scons -Q .</scons_output_command>
       </scons_output>
 
-      <section>
+      <section id="sect-var-DEFAULT-TARGETS">
       <title>Fetching the List of Default Targets: the &DEFAULT_TARGETS; Variable</title>
 
         <para>
@@ -2432,7 +2501,7 @@ prog2.c
 
     </section>
 
-    <section>
+    <section id="sect-var-BUILD-TARGETS">
     <title>Fetching the List of Build Targets, Regardless of Origin: the &BUILD_TARGETS; Variable</title>
 
       <para>
diff --git a/doc/user/output.xml b/doc/user/output.xml
index ebcf06e..9fc00aa 100644
--- a/doc/user/output.xml
+++ b/doc/user/output.xml
@@ -39,7 +39,7 @@ SPDX-License-Identifier: MIT
 
   </para>
 
-  <section>
+  <section id="sect-build-help">
   <title>Providing Build Help:  the &Help; Function</title>
 
     <para>
@@ -360,7 +360,7 @@ cc -o foo foo.o
 
   </section>
 
-  <section>
+  <section id="sect-build-progress">
   <title>Providing Build Progress Output:  the &Progress; Function</title>
 
     <para>
@@ -593,7 +593,7 @@ Progress(progress_function)
 
   </section>
 
-  <section>
+  <section id="sect-build-status">
   <title>Printing Detailed Build Status:  the &GetBuildFailures; Function</title>
 
     <para>