Remove duplicate example. Likely caused by bad merge

Fixes #2983

5 files changed, 38 insertions, 52 deletions

diff --git a/doc/generated/examples/builderswriting_MY_EMITTER_1.xml b/doc/generated/examples/builderswriting_MY_EMITTER_1.xml
index 440b105..881fee7 100644
--- a/doc/generated/examples/builderswriting_MY_EMITTER_1.xml
+++ b/doc/generated/examples/builderswriting_MY_EMITTER_1.xml
@@ -1,5 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <screen xmlns="http://www.scons.org/dbxsd/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">% <userinput>scons -Q</userinput>
 my_command file1.input modify1.in &gt; file1.foo
-my_command file2.input modify2.in &gt; file2.foo
+sh: my_command: command not found
+scons: *** [file1.foo] Error 127
 </screen>
diff --git a/doc/generated/examples/caching_ex-random_1.xml b/doc/generated/examples/caching_ex-random_1.xml
index 81cbc5d..6a0337b 100644
--- a/doc/generated/examples/caching_ex-random_1.xml
+++ b/doc/generated/examples/caching_ex-random_1.xml
@@ -1,9 +1,9 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <screen xmlns="http://www.scons.org/dbxsd/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">% <userinput>scons -Q</userinput>
-cc -o f5.o -c f5.c
-cc -o f4.o -c f4.c
+cc -o f2.o -c f2.c
 cc -o f1.o -c f1.c
+cc -o f5.o -c f5.c
 cc -o f3.o -c f3.c
-cc -o f2.o -c f2.c
+cc -o f4.o -c f4.c
 cc -o prog f1.o f2.o f3.o f4.o f5.o
 </screen>
diff --git a/doc/generated/examples/troubleshoot_explain1_3.xml b/doc/generated/examples/troubleshoot_explain1_3.xml
index 32adb2f..e481f76 100644
--- a/doc/generated/examples/troubleshoot_explain1_3.xml
+++ b/doc/generated/examples/troubleshoot_explain1_3.xml
@@ -3,5 +3,5 @@
 cp file.in file.oout
 
 scons: warning: Cannot find target file.out after building
-File "/Users/bdbaddog/devel/scons/git/as_scons/bootstrap/src/script/scons.py", line 201, in &lt;module&gt;
+File "/Users/bdbaddog/devel/scons/git/scons-bugfixes/bootstrap/src/script/scons.py", line 201, in &lt;module&gt;
 </screen>
diff --git a/doc/generated/variables.gen b/doc/generated/variables.gen
index b86690a..2961b91 100644
--- a/doc/generated/variables.gen
+++ b/doc/generated/variables.gen
@@ -480,7 +480,8 @@ An automatically-generated construction variable
 containing the C preprocessor command-line options
 to define values.
 The value of <envar xmlns="http://www.scons.org/dbxsd/v1.0">$_CPPDEFFLAGS</envar> is created
-by appending <envar xmlns="http://www.scons.org/dbxsd/v1.0">$CPPDEFPREFIX</envar> and <envar xmlns="http://www.scons.org/dbxsd/v1.0">$CPPDEFSUFFIX</envar>
+by respectively prepending and appending
+<envar xmlns="http://www.scons.org/dbxsd/v1.0">$CPPDEFPREFIX</envar> and <envar xmlns="http://www.scons.org/dbxsd/v1.0">$CPPDEFSUFFIX</envar>
 to the beginning and end
 of each definition in <envar xmlns="http://www.scons.org/dbxsd/v1.0">$CPPDEFINES</envar>.
 </para>
@@ -503,7 +504,8 @@ If <envar xmlns="http://www.scons.org/dbxsd/v1.0">$CPPDEFINES</envar> is a strin
 the values of the
 <envar xmlns="http://www.scons.org/dbxsd/v1.0">$CPPDEFPREFIX</envar> and <envar xmlns="http://www.scons.org/dbxsd/v1.0">$CPPDEFSUFFIX</envar>
 construction variables
-will be added to the beginning and end.
+will be respectively prepended and appended to the beginning and end
+of each definition in <envar xmlns="http://www.scons.org/dbxsd/v1.0">$CPPDEFINES</envar>.
 </para>
 
 <example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -517,7 +519,7 @@ If <envar xmlns="http://www.scons.org/dbxsd/v1.0">$CPPDEFINES</envar> is a list,
 the values of the
 <envar xmlns="http://www.scons.org/dbxsd/v1.0">$CPPDEFPREFIX</envar> and <envar xmlns="http://www.scons.org/dbxsd/v1.0">$CPPDEFSUFFIX</envar>
 construction variables
-will be appended to the beginning and end
+will be respectively prepended and appended to the beginning and end
 of each element in the list.
 If any element is a list or tuple,
 then the first item is the name being
@@ -535,7 +537,7 @@ If <envar xmlns="http://www.scons.org/dbxsd/v1.0">$CPPDEFINES</envar> is a dicti
 the values of the
 <envar xmlns="http://www.scons.org/dbxsd/v1.0">$CPPDEFPREFIX</envar> and <envar xmlns="http://www.scons.org/dbxsd/v1.0">$CPPDEFSUFFIX</envar>
 construction variables
-will be appended to the beginning and end
+will be respectively prepended and appended to the beginning and end
 of each item from the dictionary.
 The key of each dictionary item
 is a name being defined
@@ -563,7 +565,7 @@ env = Environment(CPPDEFINES={'B':2, 'A':None})
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
 The prefix used to specify preprocessor definitions
 on the C compiler command line.
-This will be appended to the beginning of each definition
+This will be prepended to the beginning of each definition
 in the <envar xmlns="http://www.scons.org/dbxsd/v1.0">$CPPDEFINES</envar> construction variable
 when the <envar xmlns="http://www.scons.org/dbxsd/v1.0">$_CPPDEFFLAGS</envar> variable is automatically generated.
 </para>
@@ -619,7 +621,7 @@ An automatically-generated construction variable
 containing the C preprocessor command-line options
 for specifying directories to be searched for include files.
 The value of <envar xmlns="http://www.scons.org/dbxsd/v1.0">$_CPPINCFLAGS</envar> is created
-by appending <envar xmlns="http://www.scons.org/dbxsd/v1.0">$INCPREFIX</envar> and <envar xmlns="http://www.scons.org/dbxsd/v1.0">$INCSUFFIX</envar>
+by respectively prepending and appending <envar xmlns="http://www.scons.org/dbxsd/v1.0">$INCPREFIX</envar> and <envar xmlns="http://www.scons.org/dbxsd/v1.0">$INCSUFFIX</envar>
 to the beginning and end
 of each directory in <envar xmlns="http://www.scons.org/dbxsd/v1.0">$CPPPATH</envar>.
 </para>
@@ -661,7 +663,7 @@ through the automatically-generated
 <envar xmlns="http://www.scons.org/dbxsd/v1.0">$_CPPINCFLAGS</envar>
 construction variable,
 which is constructed by
-appending the values of the
+respectively prepending and appending the value of the
 <envar xmlns="http://www.scons.org/dbxsd/v1.0">$INCPREFIX</envar> and <envar xmlns="http://www.scons.org/dbxsd/v1.0">$INCSUFFIX</envar>
 construction variables
 to the beginning and end
@@ -2602,7 +2604,8 @@ containing the Fortran compiler command-line options
 for specifying directories to be searched for include
 files and module files.
 The value of <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-_FORTRANINCFLAGS"><envar>$_FORTRANINCFLAGS</envar></link> is created
-by prepending/appending <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-INCPREFIX"><envar>$INCPREFIX</envar></link> and <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-INCSUFFIX"><envar>$INCSUFFIX</envar></link>
+by respectively prepending and appending
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-INCPREFIX"><envar>$INCPREFIX</envar></link> and <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-INCSUFFIX"><envar>$INCSUFFIX</envar></link>
 to the beginning and end
 of each directory in <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-FORTRANPATH"><envar>$FORTRANPATH</envar></link>.
 </para>
@@ -2625,7 +2628,7 @@ for module files, as well.
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
 The prefix used to specify a module directory on the Fortran compiler command
 line.
-This will be appended to the beginning of the directory
+This will be prepended to the beginning of the directory
 in the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-FORTRANMODDIR"><envar>$FORTRANMODDIR</envar></link> construction variables
 when the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-_FORTRANMODFLAG"><envar>$_FORTRANMODFLAG</envar></link> variables is automatically generated.
 </para>
@@ -2637,7 +2640,7 @@ when the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-_FORTRANMODFL
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
 The suffix used to specify a module directory on the Fortran compiler command
 line.
-This will be appended to the beginning of the directory
+This will be appended to the end of the directory
 in the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-FORTRANMODDIR"><envar>$FORTRANMODDIR</envar></link> construction variables
 when the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-_FORTRANMODFLAG"><envar>$_FORTRANMODFLAG</envar></link> variables is automatically generated.
 </para>
@@ -2653,8 +2656,8 @@ for specifying the directory location where the Fortran
 compiler should place any module files that happen to get
 generated during compilation.
 The value of <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-_FORTRANMODFLAG"><envar>$_FORTRANMODFLAG</envar></link> is created
-by prepending/appending <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-FORTRANMODDIRPREFIX"><envar>$FORTRANMODDIRPREFIX</envar></link> and
-<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-FORTRANMODDIRSUFFIX"><envar>$FORTRANMODDIRSUFFIX</envar></link>
+by respectively prepending and appending
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-FORTRANMODDIRPREFIX"><envar>$FORTRANMODDIRPREFIX</envar></link> and <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-FORTRANMODDIRSUFFIX"><envar>$FORTRANMODDIRSUFFIX</envar></link>
 to the beginning and end of the directory in <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-FORTRANMODDIR"><envar>$FORTRANMODDIR</envar></link>.
 </para>
 </listitem>
@@ -2727,7 +2730,7 @@ through the automatically-generated
 <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-_FORTRANINCFLAGS"><envar>$_FORTRANINCFLAGS</envar></link>
 construction variable,
 which is constructed by
-appending the values of the
+respectively prepending and appending the values of the
 <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-INCPREFIX"><envar>$INCPREFIX</envar></link> and <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-INCSUFFIX"><envar>$INCSUFFIX</envar></link>
 construction variables
 to the beginning and end
@@ -3087,7 +3090,7 @@ env = Environment(IMPLICIT_COMMAND_DEPENDENCIES = 0)
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
 The prefix used to specify an include directory on the C compiler command
 line.
-This will be appended to the beginning of each directory
+This will be prepended to the beginning of each directory
 in the <envar xmlns="http://www.scons.org/dbxsd/v1.0">$CPPPATH</envar> and <envar xmlns="http://www.scons.org/dbxsd/v1.0">$FORTRANPATH</envar> construction variables
 when the <envar xmlns="http://www.scons.org/dbxsd/v1.0">$_CPPINCFLAGS</envar> and <envar xmlns="http://www.scons.org/dbxsd/v1.0">$_FORTRANINCFLAGS</envar>
 variables are automatically generated.
@@ -3698,7 +3701,7 @@ An automatically-generated construction variable
 containing the linker command-line options
 for specifying directories to be searched for library.
 The value of <envar xmlns="http://www.scons.org/dbxsd/v1.0">$_LIBDIRFLAGS</envar> is created
-by appending <envar xmlns="http://www.scons.org/dbxsd/v1.0">$LIBDIRPREFIX</envar> and <envar xmlns="http://www.scons.org/dbxsd/v1.0">$LIBDIRSUFFIX</envar>
+by respectively prepending and appending <envar xmlns="http://www.scons.org/dbxsd/v1.0">$LIBDIRPREFIX</envar> and <envar xmlns="http://www.scons.org/dbxsd/v1.0">$LIBDIRSUFFIX</envar>
 to the beginning and end
 of each directory in <envar xmlns="http://www.scons.org/dbxsd/v1.0">$LIBPATH</envar>.
 </para>
@@ -3709,7 +3712,7 @@ of each directory in <envar xmlns="http://www.scons.org/dbxsd/v1.0">$LIBPATH</en
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
 The prefix used to specify a library directory on the linker command line.
-This will be appended to the beginning of each directory
+This will be prepended to the beginning of each directory
 in the <envar xmlns="http://www.scons.org/dbxsd/v1.0">$LIBPATH</envar> construction variable
 when the <envar xmlns="http://www.scons.org/dbxsd/v1.0">$_LIBDIRFLAGS</envar> variable is automatically generated.
 </para>
@@ -3742,7 +3745,7 @@ An automatically-generated construction variable
 containing the linker command-line options
 for specifying libraries to be linked with the resulting target.
 The value of <envar xmlns="http://www.scons.org/dbxsd/v1.0">$_LIBFLAGS</envar> is created
-by appending <envar xmlns="http://www.scons.org/dbxsd/v1.0">$LIBLINKPREFIX</envar> and <envar xmlns="http://www.scons.org/dbxsd/v1.0">$LIBLINKSUFFIX</envar>
+by respectively prepending and appending <envar xmlns="http://www.scons.org/dbxsd/v1.0">$LIBLINKPREFIX</envar> and <envar xmlns="http://www.scons.org/dbxsd/v1.0">$LIBLINKSUFFIX</envar>
 to the beginning and end
 of each filename in <envar xmlns="http://www.scons.org/dbxsd/v1.0">$LIBS</envar>.
 </para>
@@ -3753,7 +3756,7 @@ of each filename in <envar xmlns="http://www.scons.org/dbxsd/v1.0">$LIBS</envar>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
 The prefix used to specify a library to link on the linker command line.
-This will be appended to the beginning of each library
+This will be prepended to the beginning of each library
 in the <envar xmlns="http://www.scons.org/dbxsd/v1.0">$LIBS</envar> construction variable
 when the <envar xmlns="http://www.scons.org/dbxsd/v1.0">$_LIBFLAGS</envar> variable is automatically generated.
 </para>
@@ -3807,7 +3810,7 @@ through the automatically-generated
 <envar xmlns="http://www.scons.org/dbxsd/v1.0">$_LIBDIRFLAGS</envar>
 construction variable,
 which is constructed by
-appending the values of the
+respectively prepending and appending the values of the
 <envar xmlns="http://www.scons.org/dbxsd/v1.0">$LIBDIRPREFIX</envar> and <envar xmlns="http://www.scons.org/dbxsd/v1.0">$LIBDIRSUFFIX</envar>
 construction variables
 to the beginning and end
@@ -3863,7 +3866,7 @@ through the automatically-generated
 <envar xmlns="http://www.scons.org/dbxsd/v1.0">$_LIBFLAGS</envar>
 construction variable,
 which is constructed by
-appending the values of the
+respectively prepending and appending the values of the
 <envar xmlns="http://www.scons.org/dbxsd/v1.0">$LIBLINKPREFIX</envar> and <envar xmlns="http://www.scons.org/dbxsd/v1.0">$LIBLINKSUFFIX</envar>
 construction variables
 to the beginning and end
@@ -5601,7 +5604,8 @@ containing the command-line options
 for specifying directories to be searched
 by the resource compiler.
 The value of <envar xmlns="http://www.scons.org/dbxsd/v1.0">$RCINCFLAGS</envar> is created
-by appending <envar xmlns="http://www.scons.org/dbxsd/v1.0">$RCINCPREFIX</envar> and <envar xmlns="http://www.scons.org/dbxsd/v1.0">$RCINCSUFFIX</envar>
+by respectively prepending and appending
+<envar xmlns="http://www.scons.org/dbxsd/v1.0">$RCINCPREFIX</envar> and <envar xmlns="http://www.scons.org/dbxsd/v1.0">$RCINCSUFFIX</envar>
 to the beginning and end
 of each directory in <envar xmlns="http://www.scons.org/dbxsd/v1.0">$CPPPATH</envar>.
 </para>
@@ -5613,7 +5617,7 @@ of each directory in <envar xmlns="http://www.scons.org/dbxsd/v1.0">$CPPPATH</en
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
 The prefix (flag) used to specify an include directory
 on the resource compiler command line.
-This will be appended to the beginning of each directory
+This will be prepended to the beginning of each directory
 in the <envar xmlns="http://www.scons.org/dbxsd/v1.0">$CPPPATH</envar> construction variable
 when the <envar xmlns="http://www.scons.org/dbxsd/v1.0">$RCINCFLAGS</envar> variable is expanded.
 </para>
@@ -5735,7 +5739,7 @@ An automatically-generated construction variable
 containing the rpath flags to be used when linking
 a program with shared libraries.
 The value of <envar xmlns="http://www.scons.org/dbxsd/v1.0">$_RPATH</envar> is created
-by appending <envar xmlns="http://www.scons.org/dbxsd/v1.0">$RPATHPREFIX</envar> and <envar xmlns="http://www.scons.org/dbxsd/v1.0">$RPATHSUFFIX</envar>
+by respectively prepending <envar xmlns="http://www.scons.org/dbxsd/v1.0">$RPATHPREFIX</envar> and appending <envar xmlns="http://www.scons.org/dbxsd/v1.0">$RPATHSUFFIX</envar>
 to the beginning and end
 of each directory in <envar xmlns="http://www.scons.org/dbxsd/v1.0">$RPATH</envar>.
 </para>
@@ -5763,7 +5767,7 @@ path, you must make it absolute yourself.
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
 The prefix used to specify a directory to be searched for
 shared libraries when running programs.
-This will be appended to the beginning of each directory
+This will be prepended to the beginning of each directory
 in the <envar xmlns="http://www.scons.org/dbxsd/v1.0">$RPATH</envar> construction variable
 when the <envar xmlns="http://www.scons.org/dbxsd/v1.0">$_RPATH</envar> variable is automatically generated.
 </para>
@@ -6935,7 +6939,8 @@ An automatically-generated construction variable
 containing the SWIG command-line options
 for specifying directories to be searched for included files.
 The value of <envar xmlns="http://www.scons.org/dbxsd/v1.0">$_SWIGINCFLAGS</envar> is created
-by appending <envar xmlns="http://www.scons.org/dbxsd/v1.0">$SWIGINCPREFIX</envar> and <envar xmlns="http://www.scons.org/dbxsd/v1.0">$SWIGINCSUFFIX</envar>
+by respectively prepending and appending
+<envar xmlns="http://www.scons.org/dbxsd/v1.0">$SWIGINCPREFIX</envar> and <envar xmlns="http://www.scons.org/dbxsd/v1.0">$SWIGINCSUFFIX</envar>
 to the beginning and end
 of each directory in <envar xmlns="http://www.scons.org/dbxsd/v1.0">$SWIGPATH</envar>.
 </para>
@@ -6946,7 +6951,7 @@ of each directory in <envar xmlns="http://www.scons.org/dbxsd/v1.0">$SWIGPATH</e
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
 The prefix used to specify an include directory on the SWIG command line.
-This will be appended to the beginning of each directory
+This will be prepended to the beginning of each directory
 in the <envar xmlns="http://www.scons.org/dbxsd/v1.0">$SWIGPATH</envar> construction variable
 when the <envar xmlns="http://www.scons.org/dbxsd/v1.0">$_SWIGINCFLAGS</envar> variable is automatically generated.
 </para>
@@ -7020,7 +7025,7 @@ through the automatically-generated
 <envar xmlns="http://www.scons.org/dbxsd/v1.0">$_SWIGINCFLAGS</envar>
 construction variable,
 which is constructed by
-appending the values of the
+respectively prepending and appending the values of the
 <envar xmlns="http://www.scons.org/dbxsd/v1.0">$SWIGINCPREFIX</envar> and <envar xmlns="http://www.scons.org/dbxsd/v1.0">$SWIGINCSUFFIX</envar>
 construction variables
 to the beginning and end
diff --git a/doc/user/builders-writing.xml b/doc/user/builders-writing.xml
index 07f2dec..f740a79 100644
--- a/doc/user/builders-writing.xml
+++ b/doc/user/builders-writing.xml
@@ -826,9 +826,6 @@ env2 = Environment(BUILDERS = {'Foo' : bld},
                    MY_EMITTER = modify2)
 env1.Foo('file1')
 env2.Foo('file2')
-import os
-env1['ENV']['PATH'] = env2['ENV']['PATH'] + os.pathsep + os.getcwd()
-env2['ENV']['PATH'] = env2['ENV']['PATH'] + os.pathsep + os.getcwd()
         </file>
         <file name="file1.input">
 file1.input
@@ -848,23 +845,6 @@ cat
 
     </scons_example>
 
-    <sconstruct>
-bld = Builder(action = 'my_command $SOURCES &gt; $TARGET',
-              suffix = '.foo',
-              src_suffix = '.input',
-              emitter = '$MY_EMITTER')
-def modify1(target, source, env):
-    return target, source + ['modify1.in']
-def modify2(target, source, env):
-    return target, source + ['modify2.in']
-env1 = Environment(BUILDERS = {'Foo' : bld},
-                   MY_EMITTER = modify1)
-env2 = Environment(BUILDERS = {'Foo' : bld},
-                   MY_EMITTER = modify2)
-env1.Foo('file1')
-env2.Foo('file2')
-    </sconstruct>
-
     <para>
 
     In this example, the <filename>modify1.in</filename>