From 8c32eaea7c88346e7a187fe501c9997ef623ad3f Mon Sep 17 00:00:00 2001
From: grbd <garlicbready@googlemail.com>
Date: Sat, 23 Sep 2017 19:25:46 +0100
Subject: addition to user docs

---
 doc/user/less-simple.xml | 59 +++++++++++++++++++++++++++++++++++++++++++++++-
 doc/user/scanners.xml    | 57 ++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 113 insertions(+), 3 deletions(-)

diff --git a/doc/user/less-simple.xml b/doc/user/less-simple.xml
index 9f27738..3473a90 100644
--- a/doc/user/less-simple.xml
+++ b/doc/user/less-simple.xml
@@ -644,4 +644,61 @@ Program('bar', bar_files)
 
   </section>
 
-</chapter>
+  <section>
+  <title>Overriding construction variables when calling a Builder</title>
+
+    <para>
+
+    It is possible to override or add construction variables
+    when calling a builder method by passing additional keyword arguments.
+    These overridden or added variables will only be in effect when
+    building the target, so they will not affect other parts of the build.
+    For example, if you want to add additional libraries for just one program:
+
+    </para>
+
+    <programlisting>
+env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
+    </programlisting>
+
+    <para>
+
+    or generate a shared library with a non-standard suffix:
+
+    </para>
+
+    <programlisting>
+env.SharedLibrary('word', 'word.cpp',
+                  SHLIBSUFFIX='.ocx',
+                  LIBSUFFIXES=['.ocx'])
+    </programlisting>
+
+    <para>
+
+    It is also possible to use the <literal>parse_flags</literal> keyword argument in an
+    override:
+
+    </para>
+
+    <para>
+
+    This example adds 'include' to &cv-link-CPPPATH;,
+    'EBUG' to &cv-link-CPPDEFINES;, and 'm' to &cv-link-LIBS;.
+
+    </para>
+
+    <programlisting>
+env = Program('hello', 'hello.c', parse_flags = '-Iinclude -DEBUG -lm')
+    </programlisting>
+
+    <para>
+
+    Within the call to the builder action the environment is not cloned,
+    instead an OverrideEnvironment() is created which is more
+    light weight than a whole Environment()
+
+    </para>
+
+  </section>
+
+</chapter>
\ No newline at end of file
diff --git a/doc/user/scanners.xml b/doc/user/scanners.xml
index 1506254..fd4bc6c 100644
--- a/doc/user/scanners.xml
+++ b/doc/user/scanners.xml
@@ -410,6 +410,59 @@ kscan = Scanner(function = kfile_scan,
     This is important since many files get scanned in a typical build.
     
     </para>
-    </section>
+  </section>
+
+  <section>
+  <title>Using scanners with Builders</title>
+
+    <para>
+
+	One approach for the use of scanners is with builders.
+    There are two optional parameters we can use with a builder
+    <literal>source_scanner</literal> and <literal>target_scanner</literal>.
+
+    </para>
+
+    <scons_example name="scanners_builders">
+      <file name="SConstruct" printme="1">
+
+def kfile_scan(node, env, path, arg):
+    contents = node.get_text_contents()
+    return env.File(include_re.findall(contents))
+
+kscan = Scanner(function = kfile_scan,
+            skeys = ['.k'],
+            path_function = FindPathDirs('KPATH'))
+
+def build_function(target, source, env):
+    # Code to build "target" from "source"
+    return None
+
+bld = Builder(action = build_function,
+            suffix = '.foo',
+            source_scanner = kscan
+            src_suffix = '.input')
+env = Environment(BUILDERS = {'Foo' : bld})
+env.Foo('file')
+
+      </file>
+    </scons_example>
+
+    <para>
+
+    An emiter function can modify the list of sources or targets
+    passed to the action function when the builder is triggered.
+
+    </para>
+
+	<para>
+
+    A scanner function will not affect the list of sources or targets
+    seen by the builder during the build action. The scanner function
+    will however affect if the builder should be rebuilt (if any of
+    the files sourced by the scanner have changed for example).
+
+    </para>
+  </section>
 
-</chapter>
+</chapter>
\ No newline at end of file
-- 
cgit v0.12