Merge commit 'upstream/2.1.0'

18 files changed, 113 insertions, 35 deletions

diff --git a/src/engine/SCons/Scanner/C.py b/src/engine/SCons/Scanner/C.py
index 3ac769a..0b07c13 100644
--- a/src/engine/SCons/Scanner/C.py
+++ b/src/engine/SCons/Scanner/C.py
@@ -5,7 +5,7 @@ This module implements the depenency scanner for C/C++ code.
 """
 
 #
-# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -27,7 +27,7 @@ This module implements the depenency scanner for C/C++ code.
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 
-__revision__ = "src/engine/SCons/Scanner/C.py 5134 2010/08/16 23:02:40 bdeegan"
+__revision__ = "src/engine/SCons/Scanner/C.py 5357 2011/09/09 21:31:03 bdeegan"
 
 import SCons.Node.FS
 import SCons.Scanner
diff --git a/src/engine/SCons/Scanner/CTests.py b/src/engine/SCons/Scanner/CTests.py
index 0b1d751..559bb38 100644
--- a/src/engine/SCons/Scanner/CTests.py
+++ b/src/engine/SCons/Scanner/CTests.py
@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -21,7 +21,7 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 
-__revision__ = "src/engine/SCons/Scanner/CTests.py 5134 2010/08/16 23:02:40 bdeegan"
+__revision__ = "src/engine/SCons/Scanner/CTests.py 5357 2011/09/09 21:31:03 bdeegan"
 
 import SCons.compat
 
diff --git a/src/engine/SCons/Scanner/D.py b/src/engine/SCons/Scanner/D.py
index 2293ddd..b4b26ba 100644
--- a/src/engine/SCons/Scanner/D.py
+++ b/src/engine/SCons/Scanner/D.py
@@ -8,7 +8,7 @@ Coded by Andy Friesen
 """
 
 #
-# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -30,7 +30,7 @@ Coded by Andy Friesen
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 
-__revision__ = "src/engine/SCons/Scanner/D.py 5134 2010/08/16 23:02:40 bdeegan"
+__revision__ = "src/engine/SCons/Scanner/D.py 5357 2011/09/09 21:31:03 bdeegan"
 
 import re
 
diff --git a/src/engine/SCons/Scanner/Dir.py b/src/engine/SCons/Scanner/Dir.py
index df0de4e..aa1239f 100644
--- a/src/engine/SCons/Scanner/Dir.py
+++ b/src/engine/SCons/Scanner/Dir.py
@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -20,7 +20,7 @@
 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
-__revision__ = "src/engine/SCons/Scanner/Dir.py 5134 2010/08/16 23:02:40 bdeegan"
+__revision__ = "src/engine/SCons/Scanner/Dir.py 5357 2011/09/09 21:31:03 bdeegan"
 
 import SCons.Node.FS
 import SCons.Scanner
diff --git a/src/engine/SCons/Scanner/DirTests.py b/src/engine/SCons/Scanner/DirTests.py
index e67d983..7ab3f26 100644
--- a/src/engine/SCons/Scanner/DirTests.py
+++ b/src/engine/SCons/Scanner/DirTests.py
@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -21,7 +21,7 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 
-__revision__ = "src/engine/SCons/Scanner/DirTests.py 5134 2010/08/16 23:02:40 bdeegan"
+__revision__ = "src/engine/SCons/Scanner/DirTests.py 5357 2011/09/09 21:31:03 bdeegan"
 
 import os.path
 import sys
diff --git a/src/engine/SCons/Scanner/Fortran.py b/src/engine/SCons/Scanner/Fortran.py
index 63d34e4..13f670d 100644
--- a/src/engine/SCons/Scanner/Fortran.py
+++ b/src/engine/SCons/Scanner/Fortran.py
@@ -5,7 +5,7 @@ This module implements the dependency scanner for Fortran code.
 """
 
 #
-# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -26,7 +26,7 @@ This module implements the dependency scanner for Fortran code.
 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
-__revision__ = "src/engine/SCons/Scanner/Fortran.py 5134 2010/08/16 23:02:40 bdeegan"
+__revision__ = "src/engine/SCons/Scanner/Fortran.py 5357 2011/09/09 21:31:03 bdeegan"
 
 import re
 
diff --git a/src/engine/SCons/Scanner/FortranTests.py b/src/engine/SCons/Scanner/FortranTests.py
index 92f6c21..e19f162 100644
--- a/src/engine/SCons/Scanner/FortranTests.py
+++ b/src/engine/SCons/Scanner/FortranTests.py
@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -21,7 +21,7 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 
-__revision__ = "src/engine/SCons/Scanner/FortranTests.py 5134 2010/08/16 23:02:40 bdeegan"
+__revision__ = "src/engine/SCons/Scanner/FortranTests.py 5357 2011/09/09 21:31:03 bdeegan"
 
 import os
 import os.path
diff --git a/src/engine/SCons/Scanner/IDL.py b/src/engine/SCons/Scanner/IDL.py
index 8ccda1b..206a106 100644
--- a/src/engine/SCons/Scanner/IDL.py
+++ b/src/engine/SCons/Scanner/IDL.py
@@ -6,7 +6,7 @@ Definition Language) files.
 """
 
 #
-# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -28,7 +28,7 @@ Definition Language) files.
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 
-__revision__ = "src/engine/SCons/Scanner/IDL.py 5134 2010/08/16 23:02:40 bdeegan"
+__revision__ = "src/engine/SCons/Scanner/IDL.py 5357 2011/09/09 21:31:03 bdeegan"
 
 import SCons.Node.FS
 import SCons.Scanner
diff --git a/src/engine/SCons/Scanner/IDLTests.py b/src/engine/SCons/Scanner/IDLTests.py
index 9e1cb8c..606bc23 100644
--- a/src/engine/SCons/Scanner/IDLTests.py
+++ b/src/engine/SCons/Scanner/IDLTests.py
@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -21,7 +21,7 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 
-__revision__ = "src/engine/SCons/Scanner/IDLTests.py 5134 2010/08/16 23:02:40 bdeegan"
+__revision__ = "src/engine/SCons/Scanner/IDLTests.py 5357 2011/09/09 21:31:03 bdeegan"
 
 import TestCmd
 import SCons.Scanner.IDL
diff --git a/src/engine/SCons/Scanner/LaTeX.py b/src/engine/SCons/Scanner/LaTeX.py
index ae542cf..913e64b 100644
--- a/src/engine/SCons/Scanner/LaTeX.py
+++ b/src/engine/SCons/Scanner/LaTeX.py
@@ -5,7 +5,7 @@ This module implements the dependency scanner for LaTeX code.
 """
 
 #
-# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -27,7 +27,7 @@ This module implements the dependency scanner for LaTeX code.
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 
-__revision__ = "src/engine/SCons/Scanner/LaTeX.py 5134 2010/08/16 23:02:40 bdeegan"
+__revision__ = "src/engine/SCons/Scanner/LaTeX.py 5357 2011/09/09 21:31:03 bdeegan"
 
 import os.path
 import re
@@ -148,6 +148,8 @@ class LaTeX(SCons.Scanner.Base):
     env['TEXINPUTS'] for "lstinputlisting" keyword
     env['BIBINPUTS'] for "bibliography" keyword
     env['BSTINPUTS'] for "bibliographystyle" keyword
+    env['INDEXSTYLE'] for "makeindex" keyword, no scanning support needed
+                      just allows user to set it if needed.
 
     FIXME: also look for the class or style in document[class|style]{}
     FIXME: also look for the argument of bibliographystyle{}
@@ -157,6 +159,7 @@ class LaTeX(SCons.Scanner.Base):
                      'includegraphics': 'TEXINPUTS',
                      'bibliography': 'BIBINPUTS',
                      'bibliographystyle': 'BSTINPUTS',
+                     'makeindex': 'INDEXSTYLE',
                      'usepackage': 'TEXINPUTS',
                      'lstinputlisting': 'TEXINPUTS'}
     env_variables = SCons.Util.unique(list(keyword_paths.values()))
diff --git a/src/engine/SCons/Scanner/LaTeXTests.py b/src/engine/SCons/Scanner/LaTeXTests.py
index 2bbb9d6..00e6483 100644
--- a/src/engine/SCons/Scanner/LaTeXTests.py
+++ b/src/engine/SCons/Scanner/LaTeXTests.py
@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -21,7 +21,7 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 
-__revision__ = "src/engine/SCons/Scanner/LaTeXTests.py 5134 2010/08/16 23:02:40 bdeegan"
+__revision__ = "src/engine/SCons/Scanner/LaTeXTests.py 5357 2011/09/09 21:31:03 bdeegan"
 
 import SCons.compat
 
diff --git a/src/engine/SCons/Scanner/Prog.py b/src/engine/SCons/Scanner/Prog.py
index 0312132..0df80f8 100644
--- a/src/engine/SCons/Scanner/Prog.py
+++ b/src/engine/SCons/Scanner/Prog.py
@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -21,7 +21,7 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 
-__revision__ = "src/engine/SCons/Scanner/Prog.py 5134 2010/08/16 23:02:40 bdeegan"
+__revision__ = "src/engine/SCons/Scanner/Prog.py 5357 2011/09/09 21:31:03 bdeegan"
 
 import SCons.Node
 import SCons.Node.FS
diff --git a/src/engine/SCons/Scanner/ProgTests.py b/src/engine/SCons/Scanner/ProgTests.py
index 1d7a343..ba6e0a7 100644
--- a/src/engine/SCons/Scanner/ProgTests.py
+++ b/src/engine/SCons/Scanner/ProgTests.py
@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -21,7 +21,7 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 
-__revision__ = "src/engine/SCons/Scanner/ProgTests.py 5134 2010/08/16 23:02:40 bdeegan"
+__revision__ = "src/engine/SCons/Scanner/ProgTests.py 5357 2011/09/09 21:31:03 bdeegan"
 
 import os.path
 import sys
diff --git a/src/engine/SCons/Scanner/RC.py b/src/engine/SCons/Scanner/RC.py
index 9013a09..a650581 100644
--- a/src/engine/SCons/Scanner/RC.py
+++ b/src/engine/SCons/Scanner/RC.py
@@ -6,7 +6,7 @@ Definition Language) files.
 """
 
 #
-# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -28,7 +28,7 @@ Definition Language) files.
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 
-__revision__ = "src/engine/SCons/Scanner/RC.py 5134 2010/08/16 23:02:40 bdeegan"
+__revision__ = "src/engine/SCons/Scanner/RC.py 5357 2011/09/09 21:31:03 bdeegan"
 
 import SCons.Node.FS
 import SCons.Scanner
@@ -40,7 +40,7 @@ def RCScan():
     res_re= r'^(?:\s*#\s*(?:include)|' \
             '.*?\s+(?:ICON|BITMAP|CURSOR|HTML|FONT|MESSAGETABLE|TYPELIB|REGISTRY|D3DFX)' \
             '\s*.*?)' \
-            '\s*(<|"| )([^>"\s]+)(?:[>" ])*$'
+            '\s*(<|"| )([^>"\s]+)(?:[>"\s])*$'
     resScanner = SCons.Scanner.ClassicCPP( "ResourceScanner",
                                            "$RCSUFFIXES",
                                            "CPPPATH",
diff --git a/src/engine/SCons/Scanner/RCTests.py b/src/engine/SCons/Scanner/RCTests.py
index 6f93413..2f09d78 100644
--- a/src/engine/SCons/Scanner/RCTests.py
+++ b/src/engine/SCons/Scanner/RCTests.py
@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -21,7 +21,7 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 
-__revision__ = "src/engine/SCons/Scanner/RCTests.py 5134 2010/08/16 23:02:40 bdeegan"
+__revision__ = "src/engine/SCons/Scanner/RCTests.py 5357 2011/09/09 21:31:03 bdeegan"
 
 import TestCmd
 import SCons.Scanner.RC
@@ -57,6 +57,7 @@ TEST_D3DFX   D3DFX DISCARDABLE "testEffect.fx"
 
 """)
 
+test.write('t3.rc','#include "t1.h"\r\n')
 
 # Create dummy include files
 headers = ['t1.h',
@@ -144,12 +145,22 @@ class RCScannerTestCase2(unittest.TestCase):
                    'testregis.rgs','testtypelib.tlb']
         deps_match(self, deps, headers)
 
+class RCScannerTestCase3(unittest.TestCase):
+    def runTest(self):
+        path = []
+        env = DummyEnvironment(RCSUFFIXES=['.rc','.rc2'],
+                               CPPPATH=path)
+        s = SCons.Scanner.RC.RCScan()
+        deps = s(env.File('t3.rc'), env, path)
+        headers = ['t1.h']
+        deps_match(self, deps, headers)
         
 
 def suite():
     suite = unittest.TestSuite()
     suite.addTest(RCScannerTestCase1())
     suite.addTest(RCScannerTestCase2())
+    suite.addTest(RCScannerTestCase3())
     return suite
 
 if __name__ == "__main__":
diff --git a/src/engine/SCons/Scanner/ScannerTests.py b/src/engine/SCons/Scanner/ScannerTests.py
index 140fc82..5d9607f 100644
--- a/src/engine/SCons/Scanner/ScannerTests.py
+++ b/src/engine/SCons/Scanner/ScannerTests.py
@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -20,7 +20,7 @@
 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
-__revision__ = "src/engine/SCons/Scanner/ScannerTests.py 5134 2010/08/16 23:02:40 bdeegan"
+__revision__ = "src/engine/SCons/Scanner/ScannerTests.py 5357 2011/09/09 21:31:03 bdeegan"
 
 import SCons.compat
 
diff --git a/src/engine/SCons/Scanner/__init__.py b/src/engine/SCons/Scanner/__init__.py
index 1a8dcbc..d2d7a62 100644
--- a/src/engine/SCons/Scanner/__init__.py
+++ b/src/engine/SCons/Scanner/__init__.py
@@ -5,7 +5,7 @@ The Scanner package for the SCons software construction utility.
 """
 
 #
-# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -27,7 +27,7 @@ The Scanner package for the SCons software construction utility.
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 
-__revision__ = "src/engine/SCons/Scanner/__init__.py 5134 2010/08/16 23:02:40 bdeegan"
+__revision__ = "src/engine/SCons/Scanner/__init__.py 5357 2011/09/09 21:31:03 bdeegan"
 
 import re
 
diff --git a/src/engine/SCons/Scanner/__init__.xml b/src/engine/SCons/Scanner/__init__.xml
new file mode 100644
index 0000000..f16de90
--- /dev/null
+++ b/src/engine/SCons/Scanner/__init__.xml
@@ -0,0 +1,64 @@
+<!--
+Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
+
+This file is processed by the bin/SConsDoc.py module.
+See its __doc__ string for a discussion of the format.
+-->
+
+<scons_function name="FindPathDirs">
+<arguments signature="global">
+(variable)
+</arguments>
+<summary>
+Returns a function
+(actually a callable Python object)
+intended to be used as the
+<varname>path_function</varname>
+of a Scanner object.
+The returned object will look up the specified
+<varname>variable</varname>
+in a construction environment
+and treat the construction variable's value as a list of
+directory paths that should be searched
+(like
+&cv-link-CPPPATH;,
+&cv-link-LIBPATH;,
+etc.).
+
+Note that use of
+&f-FindPathDirs;
+is generally preferable to
+writing your own
+<varname>path_function</varname>
+for the following reasons:
+1) The returned list will contain all appropriate directories
+found in source trees
+(when
+&f-link-VariantDir;
+is used)
+or in code repositories
+(when
+&f-Repository;
+or the
+<option>-Y</option>
+option are used).
+2) scons will identify expansions of
+<varname>variable</varname>
+that evaluate to the same list of directories as,
+in fact, the same list,
+and avoid re-scanning the directories for files,
+when possible.
+
+Example:
+
+<example>
+def my_scan(node, env, path, arg):
+    # Code to scan file contents goes here...
+    return include_files
+
+scanner = Scanner(name = 'myscanner',
+                  function = my_scan,
+                  path_function = FindPathDirs('MYPATH'))
+</example>
+</summary>
+</scons_function>