Incorporate changes from pre-release reviews.

11 files changed, 275 insertions, 11 deletions

diff --git a/doc/user/MANIFEST b/doc/user/MANIFEST
index 58ac2fc..e266393 100644
--- a/doc/user/MANIFEST
+++ b/doc/user/MANIFEST
@@ -36,3 +36,7 @@ sourcecode.sgml
 tasks.sgml
 troubleshoot.sgml
 variants.sgml
+SCons-win32-install-1.jpg
+SCons-win32-install-2.jpg
+SCons-win32-install-3.jpg
+SCons-win32-install-4.jpg
diff --git a/doc/user/SCons-win32-install-1.jpg b/doc/user/SCons-win32-install-1.jpg
new file mode 100644
index 0000000..ecc439d
--- /dev/null
+++ b/doc/user/SCons-win32-install-1.jpg
diff --git a/doc/user/SCons-win32-install-2.jpg b/doc/user/SCons-win32-install-2.jpg
new file mode 100644
index 0000000..f468526
--- /dev/null
+++ b/doc/user/SCons-win32-install-2.jpg
diff --git a/doc/user/SCons-win32-install-3.jpg b/doc/user/SCons-win32-install-3.jpg
new file mode 100644
index 0000000..90d2ed4
--- /dev/null
+++ b/doc/user/SCons-win32-install-3.jpg
diff --git a/doc/user/SCons-win32-install-4.jpg b/doc/user/SCons-win32-install-4.jpg
new file mode 100644
index 0000000..d37973b
--- /dev/null
+++ b/doc/user/SCons-win32-install-4.jpg
diff --git a/doc/user/build-install.in b/doc/user/build-install.in
index 164aabe..0f63bd9 100644
--- a/doc/user/build-install.in
+++ b/doc/user/build-install.in
@@ -256,7 +256,7 @@
       Download the <filename>scons-0.95.win32.exe</filename>
       file from the &SCons; download page at
       <ulink url="http://www.scons.org/download.html">http://www.scons.org/download.html</ulink>.
-      Then all you need to is execute the file
+      Then all you need to do is execute the file
       (usually by clicking on its icon in Windows Explorer).
       These will take you through a small
       sequence of windows that will install
@@ -305,6 +305,46 @@
 
       -->
 
+      <!--
+
+      XXX - don't have the kinks worked out on how to
+      get these to display properly in all formats,
+      so comment them out for now.
+
+      <screenshot>
+      <mediaobject>
+        <imageobject>
+          <imagedata fileref="SCons-win32-install-1.jpg" format="jpg" align="center">
+        </imageobject>
+      </mediaobject>
+      </screenshot>
+
+      <screenshot>
+      <mediaobject>
+        <imageobject>
+          <imagedata fileref="SCons-win32-install-2.jpg" format="jpg" align="center">
+        </imageobject>
+      </mediaobject>
+      </screenshot>
+
+      <screenshot>
+      <mediaobject>
+        <imageobject>
+          <imagedata fileref="SCons-win32-install-3.jpg" format="jpg" align="center">
+        </imageobject>
+      </mediaobject>
+      </screenshot>
+
+      <screenshot>
+      <mediaobject>
+        <imageobject>
+          <imagedata fileref="SCons-win32-install-4.jpg" format="jpg" align="center">
+        </imageobject>
+      </mediaobject>
+      </screenshot>
+
+      -->
+
     </section>
 
   </section>
diff --git a/doc/user/build-install.sgml b/doc/user/build-install.sgml
index 164aabe..0f63bd9 100644
--- a/doc/user/build-install.sgml
+++ b/doc/user/build-install.sgml
@@ -256,7 +256,7 @@
       Download the <filename>scons-0.95.win32.exe</filename>
       file from the &SCons; download page at
       <ulink url="http://www.scons.org/download.html">http://www.scons.org/download.html</ulink>.
-      Then all you need to is execute the file
+      Then all you need to do is execute the file
       (usually by clicking on its icon in Windows Explorer).
       These will take you through a small
       sequence of windows that will install
@@ -305,6 +305,46 @@
 
       -->
 
+      <!--
+
+      XXX - don't have the kinks worked out on how to
+      get these to display properly in all formats,
+      so comment them out for now.
+
+      <screenshot>
+      <mediaobject>
+        <imageobject>
+          <imagedata fileref="SCons-win32-install-1.jpg" format="jpg" align="center">
+        </imageobject>
+      </mediaobject>
+      </screenshot>
+
+      <screenshot>
+      <mediaobject>
+        <imageobject>
+          <imagedata fileref="SCons-win32-install-2.jpg" format="jpg" align="center">
+        </imageobject>
+      </mediaobject>
+      </screenshot>
+
+      <screenshot>
+      <mediaobject>
+        <imageobject>
+          <imagedata fileref="SCons-win32-install-3.jpg" format="jpg" align="center">
+        </imageobject>
+      </mediaobject>
+      </screenshot>
+
+      <screenshot>
+      <mediaobject>
+        <imageobject>
+          <imagedata fileref="SCons-win32-install-4.jpg" format="jpg" align="center">
+        </imageobject>
+      </mediaobject>
+      </screenshot>
+
+      -->
+
     </section>
 
   </section>
diff --git a/doc/user/java.in b/doc/user/java.in
index 6b22de8..66b9c86 100644
--- a/doc/user/java.in
+++ b/doc/user/java.in
@@ -117,11 +117,108 @@
   <section>
   <title>How &SCons; Handles Java Dependencies</title>
 
-    <scons_output example="java">
+    <para>
+
+    In addition to searching the source directory for
+    <filename>.java</filename> files,
+    &SCons; actually runs the <filename>.java</filename> files
+    through a stripped-down Java parser that figures out
+    what classes are defined.
+    In other words, &SCons; knows,
+    without you having to tell it,
+    what <filename>.class</filename> files
+    will be produced by the &javac; call.
+    So our one-liner example from the preceding section:
+
+    </para>
+
+    <scons_example name="java-classes">
+      <file name="SConstruct" printme="1">
+      Java('classes', 'src')
+      </file>
+      <file name="src/Example1.java">
+      public class Example1
+      {
+        public static void main(String[] args)
+        {
+          System.out.println("Hello Java world!\n");
+        }
+      }
+      public class AdditionalClass1
+      {
+        public static void main(String[] args)
+        {
+          System.out.println("Hello Java world!\n");
+        }
+      }
+      </file>
+      <file name="src/Example2.java">
+      public class Example2
+      {
+        class Inner2 {
+          public static void main(String[] args)
+          {
+            System.out.println("Hello Java world!\n");
+          }
+        }
+      }
+      </file>
+      <file name="src/Example3.java">
+      public class Example3
+      {
+        public static void main(String[] args)
+        {
+          System.out.println("Hello Java world!\n");
+        }
+      }
+      public class AdditionalClass3
+      {
+        public static void main(String[] args)
+        {
+          System.out.println("Hello Java world!\n");
+        }
+      }
+      </file>
+    </scons_example>
+
+    <para>
+
+    Will not only tell you reliably
+    that the <filename>.class</filename> files
+    in the <filename>classes</filename> subdirectory 
+    are up-to-date:
+
+    </para>
+
+    <scons_output example="java-classes">
       <command>scons -Q</command>
       <command>scons -Q classes</command>
     </scons_output>
 
+    <para>
+
+    But it will also remove all of the generated
+    <filename>.class</filename> files,
+    even for inner classes,
+    without you having to specify them manually.
+    For example, if our
+    <filename>Example1.java</filename>
+    and
+    <filename>Example3.java</filename>
+    files both define additional classes,
+    and the class defined in <filename>Example2.java</filename>
+    has an inner class,
+    running <userinput>scons -c</userinput>
+    will clean up all of those <filename>.class</filename> files
+    as well:
+
+    </para>
+
+    <scons_output example="java-classes">
+      <command>scons -Q</command>
+      <command>scons -Q -c classes</command>
+    </scons_output>
+
   </section>
 
   <section>
diff --git a/doc/user/java.sgml b/doc/user/java.sgml
index 98135b0..e3eee53 100644
--- a/doc/user/java.sgml
+++ b/doc/user/java.sgml
@@ -89,6 +89,34 @@
   <section>
   <title>How &SCons; Handles Java Dependencies</title>
 
+    <para>
+
+    In addition to searching the source directory for
+    <filename>.java</filename> files,
+    &SCons; actually runs the <filename>.java</filename> files
+    through a stripped-down Java parser that figures out
+    what classes are defined.
+    In other words, &SCons; knows,
+    without you having to tell it,
+    what <filename>.class</filename> files
+    will be produced by the &javac; call.
+    So our one-liner example from the preceding section:
+
+    </para>
+
+    <programlisting>
+      Java('classes', 'src')
+    </programlisting>
+
+    <para>
+
+    Will not only tell you reliably
+    that the <filename>.class</filename> files
+    in the <filename>classes</filename> subdirectory 
+    are up-to-date:
+
+    </para>
+
     <screen>
       % <userinput>scons -Q</userinput>
       javac -d classes -sourcepath src src/Example1.java src/Example2.java src/Example3.java
@@ -96,6 +124,37 @@
       scons: `classes' is up to date.
     </screen>
 
+    <para>
+
+    But it will also remove all of the generated
+    <filename>.class</filename> files,
+    even for inner classes,
+    without you having to specify them manually.
+    For example, if our
+    <filename>Example1.java</filename>
+    and
+    <filename>Example3.java</filename>
+    files both define additional classes,
+    and the class defined in <filename>Example2.java</filename>
+    has an inner class,
+    running <userinput>scons -c</userinput>
+    will clean up all of those <filename>.class</filename> files
+    as well:
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      javac -d classes -sourcepath src src/Example1.java src/Example2.java src/Example3.java
+      % <userinput>scons -Q -c classes</userinput>
+      Removed classes/Example1.class
+      Removed classes/AdditionalClass1.class
+      Removed classes/Example2$Inner2.class
+      Removed classes/Example2.class
+      Removed classes/Example3.class
+      Removed classes/AdditionalClass3.class
+    </screen>
+
   </section>
 
   <section>
diff --git a/doc/user/sconf.in b/doc/user/sconf.in
index 309e862..525b0fc 100644
--- a/doc/user/sconf.in
+++ b/doc/user/sconf.in
@@ -153,7 +153,7 @@
     <para>
 
     Check for the availability of a library
-    using the &CheckLibrary; method.
+    using the &CheckLib; method.
     You only specify the basename of the library,
     you don't need to add a <literal>lib</literal>
     prefix or a <literal>.a</literal> or <literal>.lib</literal> suffix:
@@ -171,9 +171,13 @@
 
     <para>
 
-    If the library requires the inclusion of
-    a header file to compile successfully,
-    add that as a second argument:
+    Because the ability to use a library successfully
+    often depends on having access to a header file
+    that describes the library's interface,
+    you can check for a library
+    <emphasis>and</emphasis> a header file
+    at the same time by using the
+    &CheckLibWithHeader; method:
 
     </para>
 
@@ -186,6 +190,14 @@
     env = conf.Finish()
     </sconstruct>
 
+    <para>
+
+    This is essentially shorthand for
+    separate calls to the &CheckHeader; and &CheckLib;
+    functions.
+
+    </para>
+
   </section>
 
   <section>
diff --git a/doc/user/sconf.sgml b/doc/user/sconf.sgml
index 715ba67..2e2a698 100644
--- a/doc/user/sconf.sgml
+++ b/doc/user/sconf.sgml
@@ -153,7 +153,7 @@
     <para>
 
     Check for the availability of a library
-    using the &CheckLibrary; method.
+    using the &CheckLib; method.
     You only specify the basename of the library,
     you don't need to add a <literal>lib</literal>
     prefix or a <literal>.a</literal> or <literal>.lib</literal> suffix:
@@ -171,9 +171,13 @@
 
     <para>
 
-    If the library requires the inclusion of
-    a header file to compile successfully,
-    add that as a second argument:
+    Because the ability to use a library successfully
+    often depends on having access to a header file
+    that describes the library's interface,
+    you can check for a library
+    <emphasis>and</emphasis> a header file
+    at the same time by using the
+    &CheckLibWithHeader; method:
 
     </para>
 
@@ -186,6 +190,14 @@
     env = conf.Finish()
     </programlisting>
 
+    <para>
+
+    This is essentially shorthand for
+    separate calls to the &CheckHeader; and &CheckLib;
+    functions.
+
+    </para>
+
   </section>
 
   <section>