Merge pull request SCons#4487 from mwichmann/doc/manpage

Assorted manpage updates

Author: bdbaddog

CHANGES.txt

@@ -91,6 +91,7 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
       harder to decode non-UTF-8 text. SCons.Util.to_Text now exists
       to convert a byte stream, such as "raw" file data.  Fixes #3569, #4462.
       The Pseudo manpage entry was updated to provide more clarity.
+    - Clarify how SCons finds the project top directory, and what that is used for.
     - The internal routine which implements the PyPackageDir function
       would fail with an exception if called with a module which is
       not found.  It will now return None.  Updated manpage entry and
@@ -99,6 +100,9 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
       describe the Microsoft C++ compiler. Update the version table slightly.
       Amplified the usage of MSVC_VERSION.
     - Improve SharedLibrary docs a bit.
+    - More consistent use of &Python; in the manpage.  A few links added.
+      A warning about overwriting env['ENV'] and one about Configure
+      checks possibly not running in in no-exec mode also added.
     - Update warnings module: adds docstrings, drop three unused warnings
       (DeprecatedSourceCodeWarning, TaskmasterNeedsExecuteWarning,
       DeprecatedMissingSConscriptWarning) add two warnings to manpage

RELEASE.txt

@@ -90,12 +90,18 @@ DOCUMENTATION
 -------------
 
 - Fixed the Scanner examples in the User Guide to be runnable and added
-  some more explantion. Clarified discussion of the scanner function in
+  some more explanation. Clarified discussion of the scanner function in
   the Scanner Objects section of the manpage.
 - The manpage entry for Pseudo was clarified.
 - The manpage entry for SharedLibrary was clarified.
 - Update API docs for Warnings framework; add two warns to manpage
   enable/disable control.
+- More consistent use of &Python; in the manpage.  A few links added.
+  A warning about overwriting env['ENV'] and one about Configure
+  checks possibly not running in in no-exec mode also added.
+- Clarify how SCons finds the project top directory, and what that is used for.
+
+
 
 DEVELOPMENT
 -----------

SCons/Defaults.xml

@@ -57,6 +57,14 @@ containing the
 <filename>SConstruct</filename>
 file.
 </para>
+<para>
+If variant directories are in use,
+and the configure check results should not be
+shared between variants,
+you can set &cv-CONFIGUREDIR;
+and &cv-link-CONFIGURELOG; so they are
+unique per variant directory.
+</para>
 </summary>
 </cvar>
 
@@ -71,6 +79,14 @@ containing the
 <filename>SConstruct</filename>
 file.
 </para>
+<para>
+If variant directories are in use,
+and the configure check results should not be
+shared between variants,
+you can set &cv-link-CONFIGUREDIR;
+and &cv-CONFIGURELOG; so they are
+unique per variant directory.
+</para>
 </summary>
 </cvar>
 

SCons/Environment.py

@@ -633,6 +633,17 @@ def setdefault(self, key, default=None):
         return self._dict.setdefault(key, default)
 
     def arg2nodes(self, args, node_factory=_null, lookup_list=_null, **kw):
+        """Converts *args* to a list of nodes.
+
+        Arguments:
+           args - filename strings or nodes to convert; nodes are just
+              added to the list without further processing.
+           node_factory - optional factory to create the nodes; if not
+              specified, will use this environment's ``fs.File method.
+           lookup_list - optional list of lookup functions to call to
+              attempt to find the file referenced by each *args*.
+           kw - keyword arguments that represent additional nodes to add.
+        """
         if node_factory is _null:
             node_factory = self.fs.File
         if lookup_list is _null:

SCons/Environment.xml

@@ -2999,9 +2999,9 @@ method.
 <summary>
 <para>
 Specifies an order-only relationship
-between the specified target file(s)
-and the specified prerequisite file(s).
-The prerequisite file(s)
+between <parameter>target</parameter>
+and <parameter>prerequisite</parameter>.
+The prerequisites
 will be (re)built, if necessary,
 <emphasis>before</emphasis>
 the target file(s),
@@ -3012,6 +3012,9 @@ the prerequisite file(s) change.
 <parameter>target</parameter> and
 <parameter>prerequisite</parameter> may each
 be a string or Node, or a list of strings or Nodes.
+If there are multiple
+<parameter>target</parameter> values,
+the prerequisite(s) are added to each one.
 Returns a list of the affected target nodes.
 </para>