Restructure release notes. Add one about use of += on lists returned from Builders changing.

1 files changed, 229 insertions, 161 deletions

diff --git a/src/RELEASE.txt b/src/RELEASE.txt
index 57809e8..1c23c10 100644
--- a/src/RELEASE.txt
+++ b/src/RELEASE.txt
@@ -28,187 +28,255 @@ RELEASE 0.97 - XXX
 
   Please note the following important changes since release 0.96:
 
-    - The ParseConfig() method now adds library file names returned
-      by the specified *-config command to the $LIBS construction
-      variable, instead of returning them (the same way it handles
-      the -l option).
-
-    - By default, the ParseConfig() method now avoids adding duplicate
-      entries to construction variables.  The old behavior may be
-      specified using a new "unique=0" keyword argument.
-
-    - Custom builders that accept directories as source arguments no
-      longer scan entire directory trees by default.  This means that
-      their targets will not be automatically rebuilt if a file that
-      SCons does *not* already know about changes on disk.  Note that
-      the targets *will* still be rebuilt correctly if a file changes
-      that SCons already knows about due to a Builder or other call.
-
-      The existing behavior of scanning directory trees for any changed
-      file on-disk can be maintained by passing the new DirScanner global
-      directory scanner as the source_scanner keyword argument to the
-      Builder call:
-
-          bld = Builder("build < $SOURCE > $TARGET",
+    --  DIRECTORY TREES ARE NO LONGER AUTOMATICALLY SCANNED FOR CHANGES
+
+        Custom builders and Command() calls that accept directories as
+        source arguments no longer scan entire on-disk directory trees
+        by default.  This means that their targets will not be
+        automatically rebuilt if a file changes on disk, and SCons does
+        *not* already know about.  Note that the targets will still be
+        rebuilt correctly if a file changes that SCons already knows
+        about due to a Builder or other call.
+
+        The existing behavior of scanning on-disk directory trees for
+        any changed file can be maintained by passing the new DirScanner
+        global directory scanner as the source_scanner keyword argument
+        to the Builder call:
+
+            bld = Builder("build < $SOURCE > $TARGET",
+                          source_scanner = DirScanner)
+
+        The same keyword argument can also be supplied to any Command()
+        calls that need to scan directory trees on-disk for changed files:
+
+            env.Command("archive.out", "directory",
+                        "archiver -o $TARGET $SOURCE",
                         source_scanner = DirScanner)
 
-      The same keyword argument can also be supplied to any Command()
-      calls that need to scan directory trees on-disk for changed files:
+        This change was made because scanning directories by default
+        could cause huge slowdowns if a configurable directory like /usr
+        or /usr/local was passed as the source to a Builder or Command()
+        call, in which case SCons would scan the entire directory tree.
+
+    --  CACHED Configure() RESULTS ARE STORED IN A DIFFERENT FILE
+
+        The Configure() subsystem now stores its cached results in a
+        different file.  This may cause configuration tests to be re-run
+        the first time after you install 0.97.
+
+    --  setup.py NOW INSTALLS MAN PAGES ON UNIX AND Linux SYSTEMS
+
+        The SCons setup.py script now installs the "scons.1" and
+        "sconsign.1" man pages on UNIX and Linux systems.  A
+        new --no-install-man
+
+    --  ParseConfig() METHOD ADDS LIBRARY FILE NAMES TO THE $LIBS VARIABLE
+
+        The ParseConfig() method now adds library file names returned
+        by the specified *-config command to the $LIBS construction
+        variable, instead of returning them (the same way it handles
+        the -l option).
+
+    --  ParseConfig() METHOD DOESN'T ADD DUPLICATES TO CONSTRUCTION VARIABLES
+
+        By default, the ParseConfig() method now avoids adding duplicate
+        entries to construction variables.  The old behavior may be
+        specified using a new "unique=0" keyword argument.
 
-          env.Command("archive.out", "directory",
-                      "archiver -o $TARGET $SOURCE",
-                      source_scanner = DirScanner)
+    --  WINDOWS %TEMP% and %TMP% VARIABLES ARE PROPAGATED AUTOMATICALLY
 
-    - When compiling with Microsoft Visual Studio, SCons no longer
-      adds the ATL and MFC directories to the INCLUDE and LIB
-      environment variables by default.  If you want these directories
-      included in your environment variables, you should now set the
-      $MSVS_USE_MFC_DIRS *construction* variable when initializing
-      your environment:
+        The %TEMP% and %TMP% external environment variables are now
+        propagated automatically to the command execution environment on
+        Windows systems.
 
-          env = Environment(MSVS_USE_MFC_DIRS = 1)
+    --  VISUAL STUDIO ATL AND MFC DIRECTORIES NOT ADDED BY DEFAULT
 
-    - The following deprecated global functions have been removed:
-      ParseConfig(), SetBuildSignatureType(), SetContentSignatureType(),
-      SetJobs() and GetJobs().
+        When compiling with Microsoft Visual Studio, SCons no longer
+        adds the ATL and MFC directories to the INCLUDE and LIB
+        environment variables by default.  If you want these directories
+        included in your environment variables, you should now set the
+        $MSVS_USE_MFC_DIRS *construction* variable when initializing
+        your environment:
 
-    - The deprecated "validater" keyword to the Options.Add() method
-      has been removed.
+            env = Environment(MSVS_USE_MFC_DIRS = 1)
 
-    - The %TEMP% and %TMP% external environment variables are now
-      propagated automatically to the command execution environment on
-      Windows systems.
+    --  BUILDERS RETURN A LIST-LIKE OBJECT, NOT A REGULAR LIST
 
-    - The Configure() subsystem now reports tests results as "yes" and
-      "no" instead of "ok" and "failed."  This might interfere with any
-      scripts that automatically parse the Configure() output from SCons.
+        Builders calls now return an object that behaves like a list
+        (and which provides some other functionality), not an underlying
+        Python list.  In general, this should not cause any problems,
+        although it introduces a subtle change in the following behavior:
 
-    - The Configure() subsystem now stores its cached results in a
-      different file.  This may cause configuration tests to be re-run
-      the first time after you install 0.97.
+                obj += env.Object('foo.c')
 
-    - The SCons setup.py script now installs the "scons.1" and
-      "sconsign.1" man pages on UNIX and Linux systems.
+        If "obj" is a list, Python will no longer update the "obj" in
+        place, because the return value from env.Object() is no longer
+        the same type.  Python will instead allocate a new object and
+        assign the local variable "obj" to it.  If "obj" is defined in
+        an SConscript file that calls another SConscript file containing
+        the above code, "obj" in the first SConscript file will not
+        contain the objects.
+
+        You can guarantee that a list will be updated in place regardless
+        of which SConscript file defines it and which adds to it by
+        using the list append() method as follows:
+
+                obj.append(env.Object('foo.c'))
+
+    --  OUTPUT OF Configure() SUBSYSTEM CHANGED SLIGHTLY
+
+        The Configure() subsystem now reports tests results as "yes" and
+        "no" instead of "ok" and "failed."  This might interfere with any
+        scripts that automatically parse the Configure() output from SCons.
+
+    --  DEPRECATED GLOBAL FUNCTIONS HAVE BEEN REMOVED
+
+        The following deprecated global functions have been removed:
+        ParseConfig(), SetBuildSignatureType(), SetContentSignatureType(),
+        SetJobs() and GetJobs().
+
+    --  DEPRECATED "validater" KEYWORD HAS BEEN REMOVED
+
+        The deprecated "validater" keyword to the Options.Add() method
+        has been removed.
 
   Please note the following important changes since release 0.95:
 
-    - All Builder calls (both built-in like Program(), Library(),
-      etc. and customer Builders) now always return a list of target
-      Nodes.   If the Builder only builds one target, the Builder
-      call will now return a list containing that target Node, not
-      the target Node itself as it used to do.
-
-      This change should be invisibile to most normal uses of the
-      return values from Builder calls.  It will cause an error if the
-      SConscript file was performing some direct manipulation of the
-      returned Node value.  For example, an attempt to print the name
-      of a target returned by the Object() Builder:
-
-            target = Object('foo.c')
-            # OLD WAY
-            print target
-
-      Will now need to access the first element in the list returned by
-      the Object() call:
-
-            target = Object('foo.c')
-            # NEW AY
-            print target[0]
-
-      This change was introduced to make the data type returned by Builder
-      calls consistent (always a list), regardless of platform or number
-      of returned targets.
-
-    - The SConsignFile() function now uses an internally-supplied
-      SCons.dblite module as the default DB scheme for the .sconsign file.
-      If you are using the SConsignFile() function without an explicitly
-      specified dbm_module argument, this will cause all of your targets
-      to be recompiled the first time you use SCons 0.96.  To preserve the
-      previous behavior, specify the "anydbm" module explicitly:
-
-          import anydbm
-          SConsignFile('.sconsign_file_name', anydbm)
-
-    - The internal format of .sconsign files has been changed.  This might
-      cause warnings about "ignoring corrupt .sconsign files" and rebuilds
-      when you use SCons 0.96 for the first time in a tree that was
-      previously built with SCons 0.95 or earlier.
-
-    - The scan_check function that can be supplied to a custom Scanner now
-      must take two arguments, the Node to be checked and a construction
-      environment.  It previously only used the Node as an argument.
-
-    - The internal Scanner.add_skey() method no longer works for the
-      default scanners, which now use construction variables to hold their
-      lists of suffixes.  If you had a custom Tool specification that was
-      reaching into the internals in this way to add a suffix to one of
-      the following scanner, you must now add the suffix to a construction
-      environment through which you plan to call the scanner, as follows:
-
-          CScan.add_skey('.x')       => env.Append(CPPSUFFIXES = ['.x'])
-          DScan.add_skey('.x')       => env.Append(DSUFFIXES = ['.x'])
-          FortranScan.add_skey('.x') => env.Append(FORTRANSUFFIXES = ['.x'])
-
-    - The "node_factory" and "scanner" keyword arguments to the Builder()
-      function have been removed.  In their place, the separate and more
-      flexible "target_factory," "source_factory," "target_scanner" and
-      "source scanner" keywords should be used instead.
-
-    - SCons now treats file "extensions" that contain all digits (for
-      example, "file.123") as part of the file basename, for easier
-      handling of version numbers in the names of shared libraries
-      and other files.  Builders will now add their file extensions to
-      file names specified with all-digit extensions.  If you need to
-      generate a file with an all-digit extension using a Builder that
-      adds a file extension, you can preserve the previous behavior by
-      wrapping the file name in a File() call.
-
-    - The behavior of the env.Append() and env.Prepend() methods has
-      changed when appending a string value to a UserList, or vice versa.
-      They now behave like normal Python addition of a string to
-      a UserList.  Given an initialization and an env.Append() call like:
-
-          env = Environment(VAR1=UserList(['foo']), VAR2='foo')
-          env.Append(VAR1='bar', VAR2=UserList(['bar'])
-
-      The resulting values of $VAR1 and $VAR2 will now be ['foo', 'b',
-      'a', 'r'] and ['f', 'o', 'o', 'bar'], respectively.  This is because
-      Python UserList objects treat strings as sequences of letters when
-      adding them to the value of the UserList.
-
-      The old behavior of yielding $VAR1 and $VAR2 values of ['foo',
-      'bar'] when either variable is a UserList object now requires that
-      the string variables be enclosed in a list:
-
-          env = Environment(VAR1=UserList(['foo']), VAR2=['foo'])
-          env.Append(VAR1='bar', VAR2=UserList(['bar']))
-
-      Note that the SCons behavior when appending to normal lists has
-      *not* changed, and the behavior of all of the default values that
-      SCons uses to initialize all construction variables has *not*
-      changed.  This change *only* affects any cases where you explicitly
-      use UserList objects to initialize or append to a variable.
+    --  BUILDERS NOW ALWAYS RETURN A LIST OF TARGETS
+
+        All Builder calls (both built-in like Program(), Library(),
+        etc. and customer Builders) now always return a list of target
+        Nodes.   If the Builder only builds one target, the Builder
+        call will now return a list containing that target Node, not
+        the target Node itself as it used to do.
+
+        This change should be invisibile to most normal uses of the
+        return values from Builder calls.  It will cause an error if the
+        SConscript file was performing some direct manipulation of the
+        returned Node value.  For example, an attempt to print the name
+        of a target returned by the Object() Builder:
+
+              target = Object('foo.c')
+              # OLD WAY
+              print target
+
+        Will now need to access the first element in the list returned by
+        the Object() call:
+
+              target = Object('foo.c')
+              # NEW AY
+              print target[0]
+
+        This change was introduced to make the data type returned by Builder
+        calls consistent (always a list), regardless of platform or number
+        of returned targets.
+
+    --  DEFAULT SConsignFile() DATABASE SCHEME HAS CHANGED
+
+        The SConsignFile() function now uses an internally-supplied
+        SCons.dblite module as the default DB scheme for the .sconsign file.
+        If you are using the SConsignFile() function without an explicitly
+        specified dbm_module argument, this will cause all of your targets
+        to be recompiled the first time you use SCons 0.96.  To preserve the
+        previous behavior, specify the "anydbm" module explicitly:
+
+            import anydbm
+            SConsignFile('.sconsign_file_name', anydbm)
+
+    --  INTERNAL .sconsign FILE FORMAT HAS CHANGED
+
+        The internal format of .sconsign files has been changed.  This might
+        cause warnings about "ignoring corrupt .sconsign files" and rebuilds
+        when you use SCons 0.96 for the first time in a tree that was
+        previously built with SCons 0.95 or earlier.
+
+    --  INTERFACE CHANGE OF scan_check FUNCTION TO CUSTOM SCANNERS
+
+        The scan_check function that can be supplied to a custom Scanner now
+        must take two arguments, the Node to be checked and a construction
+        environment.  It previously only used the Node as an argument.
+
+    --  DEFAULT SCANNERS NO LONGER HEED INTERNAL Scanner.add_skey() METHOD
+
+        The internal Scanner.add_skey() method no longer works for the
+        default scanners, which now use construction variables to hold their
+        lists of suffixes.  If you had a custom Tool specification that was
+        reaching into the internals in this way to add a suffix to one of
+        the following scanner, you must now add the suffix to a construction
+        environment through which you plan to call the scanner, as follows:
+
+            CScan.add_skey('.x')       => env.Append(CPPSUFFIXES = ['.x'])
+            DScan.add_skey('.x')       => env.Append(DSUFFIXES = ['.x'])
+            FortranScan.add_skey('.x') => env.Append(FORTRANSUFFIXES = ['.x'])
+
+    --  KEYWORD ARGUMENTS TO Builder() HAVE BEEN REMOVED
+
+        The "node_factory" and "scanner" keyword arguments to the Builder()
+        function have been removed.  In their place, the separate and more
+        flexible "target_factory," "source_factory," "target_scanner" and
+        "source scanner" keywords should be used instead.
+
+    --  ALL-DIGIT FILE "EXTENSIONS" ARE NOW PART OF THE FILE BASENAME
+
+        SCons now treats file "extensions" that contain all digits (for
+        example, "file.123") as part of the file basename, for easier
+        handling of version numbers in the names of shared libraries
+        and other files.  Builders will now add their file extensions to
+        file names specified with all-digit extensions.  If you need to
+        generate a file with an all-digit extension using a Builder that
+        adds a file extension, you can preserve the previous behavior by
+        wrapping the file name in a File() call.
+
+    --  Append()/Prepend() METHODS CHANGED WHEN USING UserList OBJECTS
+
+        The behavior of the env.Append() and env.Prepend() methods has
+        changed when appending a string value to a UserList, or vice versa.
+        They now behave like normal Python addition of a string to
+        a UserList.  Given an initialization and an env.Append() call like:
+
+            env = Environment(VAR1=UserList(['foo']), VAR2='foo')
+            env.Append(VAR1='bar', VAR2=UserList(['bar'])
+
+        The resulting values of $VAR1 and $VAR2 will now be ['foo', 'b',
+        'a', 'r'] and ['f', 'o', 'o', 'bar'], respectively.  This is because
+        Python UserList objects treat strings as sequences of letters when
+        adding them to the value of the UserList.
+
+        The old behavior of yielding $VAR1 and $VAR2 values of ['foo',
+        'bar'] when either variable is a UserList object now requires that
+        the string variables be enclosed in a list:
+
+            env = Environment(VAR1=UserList(['foo']), VAR2=['foo'])
+            env.Append(VAR1='bar', VAR2=UserList(['bar']))
+
+        Note that the SCons behavior when appending to normal lists has
+        *not* changed, and the behavior of all of the default values that
+        SCons uses to initialize all construction variables has *not*
+        changed.  This change *only* affects any cases where you explicitly
+        use UserList objects to initialize or append to a variable.
 
   Please note the following planned, future changes:
 
-    - Several internal variable names in SCons.Defaults for various
-      pre-made default Scanner objects have been deprecated and will
-      be removed in a future revision.  In their place are several new
-      global variable names that are now part of the publicly-supported
-      interface:
+    --  SCANNER NAMES HAVE BEEN DEPRECATED AND WILL BE REMOVED
+
+        Several internal variable names in SCons.Defaults for various
+        pre-made default Scanner objects have been deprecated and will
+        be removed in a future revision.  In their place are several new
+        global variable names that are now part of the publicly-supported
+        interface:
 
-          NEW NAME              DEPRECATED NAME
-          --------              ----------------------------
-          CScanner              SCons.Defaults.CScan
-          DSCanner              SCons.Defaults.DScan
-          SourceFileScanner     SCons.Defaults.ObjSourceScan
-          ProgramScanner        SCons.Defaults.ProgScan
+            NEW NAME              DEPRECATED NAME
+            --------              ----------------------------
+            CScanner              SCons.Defaults.CScan
+            DSCanner              SCons.Defaults.DScan
+            SourceFileScanner     SCons.Defaults.ObjSourceScan
+            ProgramScanner        SCons.Defaults.ProgScan
 
-      Of these, only ObjSourceScan was probably used at all, to add
-      new mappings of file suffixes to other scanners for use by the
-      Object() Builder.  This should now be done as follows:
+        Of these, only ObjSourceScan was probably used at all, to add
+        new mappings of file suffixes to other scanners for use by the
+        Object() Builder.  This should now be done as follows:
 
-          SourceFileScanner.add_scanner('.x', XScanner)
+            SourceFileScanner.add_scanner('.x', XScanner)
 
   SCons is developed with an extensive regression test suite, and a
   rigorous development methodology for continually improving that suite.