Branch for User's Guide work.

14 files changed, 323 insertions, 50 deletions

diff --git a/doc/user/builders-commands.sgml b/doc/user/builders-commands.sgml
index 64c81e5..49ba08d 100644
--- a/doc/user/builders-commands.sgml
+++ b/doc/user/builders-commands.sgml
@@ -71,7 +71,7 @@
 
   <programlisting>
      env = Environment()
-     env.Command('foo.out', 'foo.in', "sed 's/x/y/' < $SOURCE > $TARGET")
+     env.Command('foo.out', 'foo.in', "sed 's/x/y/' &lt; $SOURCE &gt; $TARGET")
   </programlisting>
 
   <literallayout>
diff --git a/doc/user/builders-writing.in b/doc/user/builders-writing.in
index 50c9114..d68b872 100644
--- a/doc/user/builders-writing.in
+++ b/doc/user/builders-writing.in
@@ -221,7 +221,7 @@ This functionality could be invoked as in the following example:
 
     <scons_example name="ex2">
        <file name="SConstruct" printme="1">
-       bld = Builder(action = 'foobuild < $SOURCE > $TARGET')
+       bld = Builder(action = 'foobuild &lt; $SOURCE &gt; $TARGET')
        env = Environment(BUILDERS = {'Foo' : bld})
        env.Foo('file.foo', 'file.input')
        env.Program('hello.c')
@@ -409,7 +409,7 @@ This functionality could be invoked as in the following example:
       the target or targets to be
       built by this builder function.
       The file names of these target(s)
-      may be extracted using the Python &str; funcion.
+      may be extracted using the Python &str; function.
 
       </para>
       </listitem>
@@ -425,7 +425,7 @@ This functionality could be invoked as in the following example:
       the sources to be
       used by this builder function to build the targets.
       The file names of these source(s)
-      may be extracted using the Python &str; funcion.
+      may be extracted using the Python &str; function.
 
       </para>
       </listitem>
@@ -542,7 +542,7 @@ This functionality could be invoked as in the following example:
       by the command or other action
       generated by this function.
       The file names of these source(s)
-      may be extracted using the Python &str; funcion.
+      may be extracted using the Python &str; function.
 
       </para>
       </listitem>
@@ -560,7 +560,7 @@ This functionality could be invoked as in the following example:
       by the command or other action
       generated by this function.
       The file names of these target(s)
-      may be extracted using the Python &str; funcion.
+      may be extracted using the Python &str; function.
 
       </para>
       </listitem>
diff --git a/doc/user/builders-writing.sgml b/doc/user/builders-writing.sgml
index 796e199..4dddb55 100644
--- a/doc/user/builders-writing.sgml
+++ b/doc/user/builders-writing.sgml
@@ -207,7 +207,7 @@ This functionality could be invoked as in the following example:
     </para>
 
     <programlisting>
-       bld = Builder(action = 'foobuild < $SOURCE > $TARGET')
+       bld = Builder(action = 'foobuild &lt; $SOURCE &gt; $TARGET')
        env = Environment(BUILDERS = {'Foo' : bld})
        env.Foo('file.foo', 'file.input')
        env.Program('hello.c')
@@ -355,7 +355,7 @@ This functionality could be invoked as in the following example:
       the target or targets to be
       built by this builder function.
       The file names of these target(s)
-      may be extracted using the Python &str; funcion.
+      may be extracted using the Python &str; function.
 
       </para>
       </listitem>
@@ -371,7 +371,7 @@ This functionality could be invoked as in the following example:
       the sources to be
       used by this builder function to build the targets.
       The file names of these source(s)
-      may be extracted using the Python &str; funcion.
+      may be extracted using the Python &str; function.
 
       </para>
       </listitem>
@@ -484,7 +484,7 @@ This functionality could be invoked as in the following example:
       by the command or other action
       generated by this function.
       The file names of these source(s)
-      may be extracted using the Python &str; funcion.
+      may be extracted using the Python &str; function.
 
       </para>
       </listitem>
@@ -502,7 +502,7 @@ This functionality could be invoked as in the following example:
       by the command or other action
       generated by this function.
       The file names of these target(s)
-      may be extracted using the Python &str; funcion.
+      may be extracted using the Python &str; function.
 
       </para>
       </listitem>
diff --git a/doc/user/command-line.in b/doc/user/command-line.in
index 6f523a8..70c7ca7 100644
--- a/doc/user/command-line.in
+++ b/doc/user/command-line.in
@@ -67,9 +67,9 @@
       def b(target, source, env):
           pass
       def s(target, source, env):
-          return "    ..."
+          return "    ... [build output] ..."
       a = Action(b, strfunction = s)
-      env = Environment(BUILDERS = {'A' : a})
+      env = Environment(BUILDERS = {'A' : Builder(action=a)})
       env.A('foo.out', 'foo.in')
       </file>
       <file name="foo.in">
@@ -80,7 +80,7 @@
     <scons_output example="SCONSFLAGS">
       <command>scons</command>
       <command>export SCONSFLAGS="-Q"</command>
-      <command>scons</command>
+      <command environment="SCONSFLAGS=-Q">scons</command>
     </scons_output>
 
     <para>
diff --git a/doc/user/command-line.sgml b/doc/user/command-line.sgml
index cf15b93..78c94e1 100644
--- a/doc/user/command-line.sgml
+++ b/doc/user/command-line.sgml
@@ -67,19 +67,13 @@
     <literallayout>
       % <userinput>scons</userinput>
       scons: Reading SConscript files ...
-          ...
       scons: done reading SConscript files.
       scons: Building targets ...
-      scons: `.' is up to date.
+          ... [build output] ...
       scons: done building targets.
       % <userinput>export SCONSFLAGS="-Q"</userinput>
       % <userinput>scons</userinput>
-      scons: Reading SConscript files ...
-          ...
-      scons: done reading SConscript files.
-      scons: Building targets ...
-      scons: `.' is up to date.
-      scons: done building targets.
+          ... [build output] ...
     </literallayout>
 
     <para>
diff --git a/doc/user/depends.in b/doc/user/depends.in
index bedc91d..43ec7f3 100644
--- a/doc/user/depends.in
+++ b/doc/user/depends.in
@@ -379,7 +379,7 @@ operating system on which the build is performed (as reported by C<uname
        Program('hello.c', CPPPATH = '.')
       </file>
       <file name="hello.c" printme="1">
-       #include "hello.h" 
+       #include &lt;hello.h&gt;
        int
        main()
        {
@@ -741,9 +741,8 @@ operating system on which the build is performed (as reported by C<uname
     </para>
 
     <programlisting>
-       env = Environment()
-       hello = env.Program('hello.c')
-       env.Ignore(hello, '/usr/include/stdio.h')
+       hello = Program('hello.c')
+       Ignore(hello, '/usr/include/stdio.h')
     </programlisting>
 
   </section>
@@ -765,9 +764,8 @@ operating system on which the build is performed (as reported by C<uname
     </para>
 
     <programlisting>
-       env = Environment()
-       hello = env.Program('hello.c')
-       env.Depends(hello, 'other_file')
+       hello = Program('hello.c')
+       Depends(hello, 'other_file')
     </programlisting>
 
     <!-- XXX mention that you can use arrays for target and source? -->
diff --git a/doc/user/depends.sgml b/doc/user/depends.sgml
index f595e08..09fb62d 100644
--- a/doc/user/depends.sgml
+++ b/doc/user/depends.sgml
@@ -386,7 +386,7 @@ operating system on which the build is performed (as reported by C<uname
     </para>
 
     <programlisting>
-       #include "hello.h" 
+       #include &lt;hello.h&gt;
        int
        main()
        {
@@ -753,9 +753,8 @@ operating system on which the build is performed (as reported by C<uname
     </para>
 
     <programlisting>
-       env = Environment()
-       hello = env.Program('hello.c')
-       env.Ignore(hello, '/usr/include/stdio.h')
+       hello = Program('hello.c')
+       Ignore(hello, '/usr/include/stdio.h')
     </programlisting>
 
   </section>
@@ -777,9 +776,8 @@ operating system on which the build is performed (as reported by C<uname
     </para>
 
     <programlisting>
-       env = Environment()
-       hello = env.Program('hello.c')
-       env.Depends(hello, 'other_file')
+       hello = Program('hello.c')
+       Depends(hello, 'other_file')
     </programlisting>
 
     <!-- XXX mention that you can use arrays for target and source? -->
diff --git a/doc/user/environments.sgml b/doc/user/environments.sgml
index 2b4fb5d..eb9bf5b 100644
--- a/doc/user/environments.sgml
+++ b/doc/user/environments.sgml
@@ -506,7 +506,7 @@ environment undisturbed.
    <literallayout>
       % <userinput>scons -Q</userinput>
       
-      scons: *** Two different environments were specified for the same target: foo.o
+      scons: *** Two environments with different actions were specified for the same target: foo.o
       File "SConstruct", line 6, in ?
    </literallayout>
 
diff --git a/doc/user/libraries.in b/doc/user/libraries.in
index a31b2b4..7a88d6f 100644
--- a/doc/user/libraries.in
+++ b/doc/user/libraries.in
@@ -46,9 +46,6 @@
       <file name="SConstruct" printme="1">
       Library('foo', ['f1.c', 'f2.c', 'f3.c'])
       </file>
-      <file name="hello.c">
-      int main() { printf("Hello, world!\n"); }
-      </file>
       <file name="f1.c">
       void f1() { printf("f1.c\n"); }
       </file>
@@ -96,6 +93,91 @@
 
     </para>
 
+    <section>
+    <title>Building Static Libraries Explicitly</title>
+
+      <para>
+
+      The &Library; function builds a traditional static library.
+      If you want to be explicit about the type of library being built,
+      you can use the synonym &StaticLibrary; function
+      instead of &Library:
+
+      </para>
+
+      <scons_example name="StaticLibrary" printme="1">
+        <file name="SConstruct" printme="1">
+        StaticLibrary('foo', ['f1.c', 'f2.c', 'f3.c'])
+        </file>
+      </scons_example>
+
+      <para>
+
+      There is no functional difference between the
+      &StaticLibrary; and &Library; functions.
+
+      </para>
+
+    </section>
+
+    <section>
+    <title>Building Shared (DLL) Libraries</title>
+
+      <para>
+
+      If you want to build a shared library (on POSIX systems)
+      or a DLL file (on Windows systems),
+      you use the &SharedLibrary; function:
+
+      </para>
+
+      <scons_example name="SharedLibrary" printme="1">
+        <file name="SConstruct" printme="1">
+        SharedLibrary('foo', ['f1.c', 'f2.c', 'f3.c'])
+        </file>
+        <file name="f1.c">
+        void f1() { printf("f1.c\n"); }
+        </file>
+        <file name="f2.c">
+        void f2() { printf("f2.c\n"); }
+        </file>
+        <file name="f3.c">
+        void f3() { printf("f3.c\n"); }
+        </file>
+      </scons_example>
+
+      <para>
+
+      The output on POSIX:
+
+      </para>
+
+      <scons_output example="SharedLibrary" os="posix">
+        <command>scons -Q</command>
+      </scons_output>
+
+      <para>
+
+      And the output on Windows:
+
+      </para>
+
+      <scons_output example="SharedLibrary" os="win32">
+        <command>scons -Q</command>
+      </scons_output>
+
+      <para>
+
+      Notice again that &SCons; takes care of
+      building the output file correctly,
+      adding the <literal>-shared</literal> option
+      for a POSIX compilation,
+      and the <literal>/dll</literal> option on Windows.
+
+      </para>
+
+    </section>
+
   </section>
 
   <section>
diff --git a/doc/user/libraries.sgml b/doc/user/libraries.sgml
index fedeb7f..a47446a 100644
--- a/doc/user/libraries.sgml
+++ b/doc/user/libraries.sgml
@@ -91,6 +91,86 @@
 
     </para>
 
+    <section>
+    <title>Building Static Libraries Explicitly</title>
+
+      <para>
+
+      The &Library; function builds a traditional static library.
+      If you want to be explicit about the type of library being built,
+      you can use the synonym &StaticLibrary; function
+      instead of &Library;:
+
+      </para>
+
+      <programlisting>
+        StaticLibrary('foo', ['f1.c', 'f2.c', 'f3.c'])
+      </programlisting>
+
+      <para>
+
+      There is no functional difference between the
+      &StaticLibrary; and &Library; functions.
+
+      </para>
+
+    </section>
+
+    <section>
+    <title>Building Shared (DLL) Libraries</title>
+
+      <para>
+
+      If you want to build a shared library (on POSIX systems)
+      or a DLL file (on Windows systems),
+      you use the &SharedLibrary; function:
+
+      </para>
+
+      <programlisting>
+        SharedLibrary('foo', ['f1.c', 'f2.c', 'f3.c'])
+      </programlisting>
+
+      <para>
+
+      The output on POSIX:
+
+      </para>
+
+      <literallayout>
+        % <userinput>scons -Q</userinput>
+        cc -c -o f1.os f1.c
+        cc -c -o f2.os f2.c
+        cc -c -o f3.os f3.c
+        cc -shared -o libfoo.so f1.os f2.os f3.os
+      </literallayout>
+
+      <para>
+
+      And the output on Windows:
+
+      </para>
+
+      <literallayout>
+        C:\><userinput>scons -Q</userinput>
+        cl /nologo /c f1.c /Fof1.obj
+        cl /nologo /c f2.c /Fof2.obj
+        cl /nologo /c f3.c /Fof3.obj
+        link /nologo /dll /out:foo.dll /implib:foo.lib f1.obj f2.obj f3.obj
+      </literallayout>
+
+      <para>
+
+      Notice again that &SCons; takes care of
+      building the output file correctly,
+      adding the <literal>-shared</literal> option
+      for a POSIX compilation,
+      and the <literal>/dll</literal> option on Windows.
+
+      </para>
+
+    </section>
+
   </section>
 
   <section>
diff --git a/doc/user/scanners.in b/doc/user/scanners.in
index fe409ad..254b433 100644
--- a/doc/user/scanners.in
+++ b/doc/user/scanners.in
@@ -291,7 +291,7 @@ over the file scanning rather than being called for each input line:
         env = Environment(ENV = {'PATH' : '__ROOT__/usr/local/bin'})
         env.Append(SCANNERS = kscan)
 
-        env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
+        env.Command('foo', 'foo.k', 'kprocess &lt; $SOURCES &gt; $TARGET')
       </file>
       <file name="foo.k">
       include other_file
diff --git a/doc/user/scanners.sgml b/doc/user/scanners.sgml
index 23cd044..ee82b43 100644
--- a/doc/user/scanners.sgml
+++ b/doc/user/scanners.sgml
@@ -290,7 +290,7 @@ over the file scanning rather than being called for each input line:
         env = Environment(ENV = {'PATH' : '/usr/local/bin'})
         env.Append(SCANNERS = kscan)
 
-        env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
+        env.Command('foo', 'foo.k', 'kprocess &lt; $SOURCES &gt; $TARGET')
     </programlisting>
 
     <!--
diff --git a/doc/user/simple.in b/doc/user/simple.in
index 3940bc3..3d9d7dc 100644
--- a/doc/user/simple.in
+++ b/doc/user/simple.in
@@ -111,6 +111,58 @@
  </para>
 
  <section>
+ <title>Cleaning Up After a Build</title>
+
+   <para>
+
+   When using &SCons;, it is unnecessary to add special
+   commands or target names to clean up after a build.
+   Instead, you simply use the
+   <literal>-c</literal> or <literal>--clean</literal>
+   option when you invoke &SCons;,
+   and &SCons; removes the appropriate built files.
+   So if we build our example above
+   and then invoke <literal>scons -c</literal>
+   afterwards, the output on POSIX looks like:
+
+   </para>
+
+   <scons_example name="clean">
+      <file name="SConstruct">
+      Program('hello.c')
+      </file>
+      <file name="hello.c">
+      int main() { printf("Hello, world!\n"); }
+      </file>
+   </scons_example>
+
+   <scons_output example="clean" os="posix">
+      <command>scons</command>
+      <command>scons -c</command>
+   </scons_output>
+
+   <para>
+
+   And the output on Windows looks like:
+
+   </para>
+
+   <scons_output example="clean" os="win32">
+      <command>scons</command>
+      <command>scons -c</command>
+   </scons_output>
+
+   <para>
+
+   Notice that &SCons; changes its output to tell you that it
+   is <literal>Cleaning targets ...</literal> and
+   <literal>done cleaning targets.</literal>
+
+   </para>
+
+ </section>
+
+ <section>
  <title>The &SConstruct; File</title>
 
    <para>
@@ -347,7 +399,7 @@
    </para>
 
    <programlisting>
-      Program('program', Split('main.c file1.c file2.'))
+      Program('program', Split('main.c file1.c file2.c'))
    </programlisting>
 
    <para>
@@ -381,7 +433,7 @@
    </para>
 
    <programlisting>
-      list = Split('main.c file1.c file2.')
+      list = Split('main.c file1.c file2.c')
       Program('program', list)
    </programlisting>
 
@@ -422,7 +474,7 @@
    </para>
 
    <programlisting>
-      list = Split('main.c file1.c file2.')
+      list = Split('main.c file1.c file2.c')
       Program(target = 'program', source = list)
    </programlisting>
 
@@ -435,7 +487,7 @@
    </para>
 
    <programlisting>
-      list = Split('main.c file1.c file2.')
+      list = Split('main.c file1.c file2.c')
       Program(source = list, target = 'program')
    </programlisting>
 
diff --git a/doc/user/simple.sgml b/doc/user/simple.sgml
index 02a57ef..4309837 100644
--- a/doc/user/simple.sgml
+++ b/doc/user/simple.sgml
@@ -118,6 +118,75 @@
  </para>
 
  <section>
+ <title>Cleaning Up After a Build</title>
+
+   <para>
+
+   When using &SCons;, it is unnecessary to add special
+   commands or target names to clean up after a build.
+   Instead, you simply use the
+   <literal>-c</literal> or <literal>--clean</literal>
+   option when you invoke &SCons;,
+   and &SCons; removes the appropriate built files.
+   So if we build our example above
+   and then invoke <literal>scons -c</literal>
+   afterwards, the output on POSIX looks like:
+
+   </para>
+
+   
+
+   <literallayout>
+      % <userinput>scons</userinput>
+      scons: Reading SConscript files ...
+      scons: done reading SConscript files.
+      scons: Building targets ...
+      cc -c -o hello.o hello.c
+      cc -o hello hello.o
+      scons: done building targets.
+      % <userinput>scons -c</userinput>
+      scons: Reading SConscript files ...
+      scons: done reading SConscript files.
+      scons: Cleaning targets ...
+      Removed hello.o
+      Removed hello
+      scons: done cleaning targets.
+   </literallayout>
+
+   <para>
+
+   And the output on Windows looks like:
+
+   </para>
+
+   <literallayout>
+      C:\><userinput>scons</userinput>
+      scons: Reading SConscript files ...
+      scons: done reading SConscript files.
+      scons: Building targets ...
+      cl /nologo /c hello.c /Fohello.obj
+      link /nologo /OUT:hello.exe hello.obj
+      scons: done building targets.
+      C:\><userinput>scons -c</userinput>
+      scons: Reading SConscript files ...
+      scons: done reading SConscript files.
+      scons: Cleaning targets ...
+      Removed hello.obj
+      Removed hello.exe
+      scons: done cleaning targets.
+   </literallayout>
+
+   <para>
+
+   Notice that &SCons; changes its output to tell you that it
+   is <literal>Cleaning targets ...</literal> and
+   <literal>done cleaning targets.</literal>
+
+   </para>
+
+ </section>
+
+ <section>
  <title>The &SConstruct; File</title>
 
    <para>
@@ -352,7 +421,7 @@
    </para>
 
    <programlisting>
-      Program('program', Split('main.c file1.c file2.'))
+      Program('program', Split('main.c file1.c file2.c'))
    </programlisting>
 
    <para>
@@ -386,7 +455,7 @@
    </para>
 
    <programlisting>
-      list = Split('main.c file1.c file2.')
+      list = Split('main.c file1.c file2.c')
       Program('program', list)
    </programlisting>
 
@@ -427,7 +496,7 @@
    </para>
 
    <programlisting>
-      list = Split('main.c file1.c file2.')
+      list = Split('main.c file1.c file2.c')
       Program(target = 'program', source = list)
    </programlisting>
 
@@ -440,7 +509,7 @@
    </para>
 
    <programlisting>
-      list = Split('main.c file1.c file2.')
+      list = Split('main.c file1.c file2.c')
       Program(source = list, target = 'program')
    </programlisting>