Merge pull request #4059 from mwichmann/scanner-function

Restore doc of passing a dict as Scanner function

1 files changed, 50 insertions, 15 deletions

diff --git a/doc/man/scons.xml b/doc/man/scons.xml
index 4fa6e27..c96d142 100644
--- a/doc/man/scons.xml
+++ b/doc/man/scons.xml
@@ -6941,12 +6941,13 @@ you should be aware of this issue when using the
 
 <para>
 Scanner objects are used
-to scan specific file types for implicit dependencies.
+to scan specific file types for implicit dependencies,
+for example embedded preprocessor/compiler directives
+that cause other files to be included during processing.
 &SCons; has a number of pre-built Scanner objects,
 so it is usually only necessary to set up Scanners for new file types.
-You do this by calling the &f-link-Scanner; function.
-The &f-Scanner;
-function accepts the following arguments,
+You do this by calling the &f-link-Scanner; factory function.
+&f-Scanner; accepts the following arguments,
 only <parameter>function</parameter> is required,
 the rest are optional:
 </para>
@@ -6956,11 +6957,11 @@ the rest are optional:
   <term><parameter>function</parameter></term>
   <listitem>
 <para>
-A Python function that will process
+A scanner function to call to process
 a given Node (usually a file)
 and return a list of Nodes
 representing the implicit
-dependencies (file names) found in the contents.
+dependencies (usually files) found in the contents.
 The function must accept three required arguments,
 <parameter>node</parameter>,
 <parameter>env</parameter> and
@@ -6972,26 +6973,60 @@ the internal &SCons; node representing the file to scan,
 <parameter>env</parameter> is the &consenv; to use during
 the scan, and <parameter>path</parameter> is a tuple
 of directories that can be searched for files,
-as generated by the optional <parameter>path_function</parameter> (see below).
+as generated by the optional scanner
+<parameter>path_function</parameter> (see below).
 If <parameter>argument</parameter> was supplied when the Scanner
 object was created, it is given as <parameter>arg</parameter>
-when the function is called; since <parameter>argument</parameter>
+when the scanner function is called; since <parameter>argument</parameter>
 is optional, the default is no <parameter>arg</parameter>.
 </para>
 <para>
 The function can use use
 <function>str</function>(<parameter>node</parameter>)
-to fetch the name of the file, and
+to fetch the name of the file, 
+<replaceable>node</replaceable>.<function>dir</function>
+to fetch the directory the file is in,
 <replaceable>node</replaceable>.<function>get_contents</function>()
 to fetch the contents of the file as bytes or
 <replaceable>node</replaceable>.<function>get_text_contents</function>()
-to fetch the file's contents as text.
-Note that the file is
+to fetch the contents of the file as text.
+</para>
+<para>
+The function must take into account the <parameter>path</parameter>
+directories when generating the dependency Nodes. To illustrate this,
+a C language source file may contain a line like
+<literal>#include "foo.h"</literal>.  However, there is no guarantee
+that <filename>foo.h</filename> exists in the current directory:
+the contents of &cv-CPPPATH; is passed to the C preprocessor which
+will look in those places for the header,
+so the scanner function needs to look in those places as well
+in order to build Nodes with correct paths.
+Using &f-link-FindPathDirs; with an argument of <literal>CPPPATH</literal>
+as the <parameter>path_function</parameter> in the &f-Scanner; call
+means the scanner function will be called with the paths extracted
+from &cv-CPPPATH; in the environment <parameter>env</parameter> 
+passed as the <parameter>paths</parameter> parameter.
+</para>
+<para>
+Note that the file to scan is
 <emphasis>not</emphasis>
-guaranteed to exist at the time the scanner is called
-(it could be a generated file, not generated yet),
+guaranteed to exist at the time the scanner is called -
+it could be a generated file which has not been generated yet -
 so the scanner function must be tolerant of that.
 </para>
+<para>
+Alternatively, you can supply a dictionary as the
+<parameter>function</parameter> parameter,
+to map keys (such as file suffixes) to other Scanner objects.
+A Scanner created this way serves as a dispatcher:
+the Scanner's <parameter>skeys</parameter> parameter is
+automatically populated with the dictionary's keys,
+indicating that the Scanner handles Nodes which would be
+selected by those keys; the mapping is then used to pass
+the file on to a different Scanner that would not have been
+selected to handle that Node based on its
+own <parameter>skeys</parameter>.
+</para>
   </listitem>
   </varlistentry>
 
@@ -7013,7 +7048,7 @@ will be passed to the scanner function
 and the path function
 <parameter>path_function</parameter>
 when called,
-as the additional argument each of those functions takes.
+as the optional parameter each of those functions takes.
 </para>
   </listitem>
   </varlistentry>
@@ -7045,7 +7080,7 @@ the first target was defined,
 a list of target nodes,
 a list of source nodes,
 and the value of <parameter>argument</parameter>
-if it was supplied when the scanner was created.
+if it was supplied when the Scanner was created.
 Must return a tuple of directories
 that can be searched for files to be returned
 by this Scanner object.