Incorporate changes from pre-release reviews.

13 files changed, 305 insertions, 21 deletions

diff --git a/doc/SConscript b/doc/SConscript
index d33712b..ce5dd6d 100644
--- a/doc/SConscript
+++ b/doc/SConscript
@@ -144,7 +144,14 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
                 'ps'        : 1,
                 'pdf'       : 0,
                 'text'      : 0,
-                'graphics'  : [ 'arch', 'builder', 'job-task', 'node', 'scanner', 'sig' ],
+                'graphics'  : [
+                                'arch.fig',
+                                'builder.fig',
+                                'job-task.fig',
+                                'node.fig',
+                                'scanner.fig',
+                                'sig.fig'
+                              ],
         },
         'reference' : {
                 'htmlindex' : 'book1.html',
@@ -159,6 +166,12 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
                 'ps'        : 1,
                 'pdf'       : 1,
                 'text'      : 0,
+                'graphics'  : [
+                                'SCons-win32-install-1.jpg',
+                                'SCons-win32-install-2.jpg',
+                                'SCons-win32-install-3.jpg',
+                                'SCons-win32-install-4.jpg',
+                              ],
         },
     }
 
@@ -234,14 +247,17 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
             tar_deps.extend([html, htmlindex])
             tar_list.extend([html, htmldir])
 
-            if fig2dev:
-                for g in docs[doc].get('graphics', []):
-                    fig = os.path.join(build, doc, '%s.fig' % g)
-                    jpg = os.path.join(htmldir, '%s.jpg' % g)
+            for g in docs[doc].get('graphics', []):
+                if g[-4:] == '.fig' and fig2dev:
+                    fig = os.path.join(build, doc, g)
+                    jpg = os.path.join(htmldir, g[:-4] + '.jpg')
                     env.Command(jpg, fig,
                                 "%s -L jpeg -q 100 $SOURCES $TARGET" % fig2dev)
                     env.Depends(html, jpg)
                     Local(jpg)
+                else:
+                    src = os.path.join(build, doc, g)
+                    Local(env.Install(htmldir, src))
 
         if docs[doc].get('ps') and jadetex:
             env.Command(ps, main, [
@@ -257,13 +273,16 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
             tar_deps.append(ps)
             tar_list.append(ps)
 
-            if fig2dev:
-                for g in docs[doc].get('graphics', []):
-                    fig = os.path.join(build, doc, '%s.fig' % g)
-                    eps = os.path.join(build, 'PS', '%s.eps' % g)
+            for g in docs[doc].get('graphics', []):
+                if g[-4:] == '.fig' and fig2dev:
+                    fig = os.path.join(build, doc, g)
+                    eps = os.path.join(build, 'PS', g[:-4] + '.eps')
                     env.Command(eps, fig, "%s -L eps $SOURCES $TARGET" % fig2dev)
                     env.Depends(ps, eps)
                     Local(eps)
+                else:
+                    src = os.path.join(build, doc, g)
+                    Local(env.Install(htmldir, src))
 
         if docs[doc].get('pdf') and pdfjadetex:
             env.Command(pdf, main, [
diff --git a/doc/scons.mod b/doc/scons.mod
index 3b15c64..58a6576 100644
--- a/doc/scons.mod
+++ b/doc/scons.mod
@@ -184,7 +184,8 @@
 <!ENTITY CheckCXXHeader "<function>CheckCXXHeader</function>">
 <!ENTITY CheckFunc "<function>CheckFunc</function>">
 <!ENTITY CheckHeader "<function>CheckHeader</function>">
-<!ENTITY CheckLibrary "<function>CheckLibrary</function>">
+<!ENTITY CheckLib "<function>CheckLib</function>">
+<!ENTITY CheckLibWithHeader "<function>CheckLibWithHeader</function>">
 <!ENTITY CheckType "<function>CheckType</function>">
 <!ENTITY TryAction "<function>TryAction</function>">
 <!ENTITY TryBuild "<function>TryBuild</function>">
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>