Index: /trunk/source/doc/src/using.xml
===================================================================
--- /trunk/source/doc/src/using.xml	(revision 14743)
+++ /trunk/source/doc/src/using.xml	(revision 14744)
@@ -2811,6 +2811,6 @@
 <para>
   Because the code coverage information is associated with compiled
-  functions, load-time toplevel expressions do not get reported
-  on. You can work around this by creating a function and calling
+  functions, code coverage information is not available for load-time toplevel
+  expressions.  You can work around this by creating a function and calling
   it. I.e. instead of
   <programlisting>
@@ -2827,5 +2827,5 @@
   </programlisting>
 Then you can see the coverage information in the definition of
-init-this-and-that.
+<literal>init-this-and-that</literal>.
 </para>
 </sect2>
@@ -2863,10 +2863,10 @@
   <refnamediv>
     <refname>REPORT-COVERAGE</refname>
-    <refpurpose>Generate code coverage report</refpurpose>
+    <refpurpose>Generate a code coverage report</refpurpose>
     <refclass>Function</refclass>
   </refnamediv>
 
   <refsynopsisdiv>
-    <synopsis><function>report-coverage</function> &key;
+    <synopsis><function>report-coverage</function> output-file &key;
     (external-format :default) (statistics t) (html t)
     </synopsis>
@@ -2875,13 +2875,21 @@
   <refsect1><title>Arguments and Values</title>
   <variablelist>
+    <varlistentry>
+      <term>output-file</term>
+      <listitem>
+	<para>
+          Pathname for the output index file.
+	</para>
+      </listitem>
+    </varlistentry>
+    
     <varlistentry>
       <term>html</term>
       <listitem>
 	<para>
-	  If non-nil, this will generate an HTML report, consisting of
-	  an index file and one html file for each instrumented source
-	  file that has been loaded in the current session. The
-	  individual source file reports are stored in the same
-	  directory as the index file.
+	  If non-nil (the default), this will generate an HTML report, consisting of
+	  an index file in <varname>output-file</varname> and, in the same directory,
+          one html file for each instrumented source file that has been loaded in the
+          current session.
 	</para>
       </listitem>
@@ -2899,9 +2907,9 @@
       <listitem>
 	<para>
-	  If :statistics is non-nil, a comma-separated file is also
+	  If non-nil (the default), a comma-separated file is also
 	  generated with the summary of statistics. You can specify a
 	  filename for the statistics argument, otherwise
-	  "statistics.csv" is created in the output directory. See
-	  documentation of ccl:coverage-statistics below for a
+	  "statistics.csv" is created in the directory of <varname>output-file</varname>.
+          See documentation of coverage-statistics below for a
 	  description of the values in the statistics file.
 	</para>
@@ -2916,5 +2924,5 @@
       do
     <programlisting>
-(CCL:REPORT-COVERAGE "/my/dir/coverage/report.html")
+(REPORT-COVERAGE "/my/dir/coverage/report.html")
     </programlisting>
     and this would generate <filename>report.html</filename>,
@@ -2933,5 +2941,5 @@
   
   <refnamediv>
-    <refname>reset-coverage</refname>
+    <refname>RESET-COVERAGE</refname>
     <refpurpose>
       Resets all coverage data back to the "Not Executed" state
@@ -2940,5 +2948,5 @@
   </refnamediv>
 
-  <refsect1><title>Summary</title>
+  <refsect1><title>Description</title>
     <para>
       Resets all coverage data back to the "Not Executed" state
@@ -2953,5 +2961,5 @@
   
   <refnamediv>
-    <refname>clear-coverage</refname>
+    <refname>CLEAR-COVERAGE</refname>
     <refpurpose>
       Forget about all instrumented files that have been loaded.
@@ -2960,5 +2968,5 @@
   </refnamediv>
 
-  <refsect1><title>Summary</title>
+  <refsect1><title>Description</title>
     <para>
       Gets rid of the information about which instrumented files have
@@ -2976,5 +2984,5 @@
   
   <refnamediv>
-    <refname>save-coverage-in-file</refname>
+    <refname>SAVE-COVERAGE-IN-FILE</refname>
     <refpurpose>
       Save all coverage into to a file so you can restore it later.
@@ -2988,5 +2996,5 @@
   </refsynopsisdiv>
 
-  <refsect1><title>Summary</title>
+  <refsect1><title>Description</title>
     <para>
       Saves all coverage info in a file, so you can restore the
@@ -3004,5 +3012,5 @@
   
   <refnamediv>
-    <refname>restore-coverage-from-file</refname>
+    <refname>RESTORE-COVERAGE-FROM-FILE</refname>
     <refpurpose>
       Load coverage state from a file.
@@ -3016,8 +3024,8 @@
   </refsynopsisdiv>
 
-  <refsect1><title>Summary</title>
+  <refsect1><title>Description</title>
     <para>
       Restores the coverage data previously saved with
-      CCL:SAVE-COVERAGE-IN-FILE, for the set of instrumented fasls
+      ccl:save-coverage-in-file, for the set of instrumented fasls
       that were loaded both at save and restore time. I.e. coverage
       info is only restored for files that have been loaded in this
@@ -3025,5 +3033,5 @@
       "foo.lx86fsl" and then saved the coverage info, in this session
       you must load the same "foo.lx86fsl" before calling
-      ccl:restore-coverage-from-file in order to retrieve the stored
+      restore-coverage-from-file in order to retrieve the stored
       coverage info for "foo".  Equivalent to (ccl:restore-coverage
       (ccl:read-coverage-from-file pathname)).
@@ -3038,5 +3046,5 @@
   
   <refnamediv>
-    <refname>save-coverage</refname>
+    <refname>SAVE-COVERAGE</refname>
     <refpurpose>
       Returns a snapshot of the current coverage data.
@@ -3045,5 +3053,5 @@
   </refnamediv>
 
-  <refsect1><title>Summary</title>
+  <refsect1><title>Description</title>
     <para>
       Returns a snapshot of the current coverage data. A snapshot is a
@@ -3074,5 +3082,5 @@
   </refsynopsisdiv>
 
-  <refsect1><title>Summary</title>
+  <refsect1><title>Description</title>
     <para>
       Reinstalls a coverage snapshot as the current coverage state.
@@ -3080,4 +3088,31 @@
   </refsect1>
 </refentry>
+
+<refentry id="f_combine-coverage">
+  <indexterm zone="f_combine-coverage">
+    <primary>combine-coverage</primary>
+  </indexterm>
+  
+  <refnamediv>
+    <refname>COMBINE-COVERAGE</refname>
+    <refpurpose>
+      Combines multiple coverage snapshots into one.
+    </refpurpose>
+    <refclass>Function</refclass>
+  </refnamediv>
+
+   <refsynopsisdiv>
+     <synopsis><function>combine-coverage</function> snapshots
+     </synopsis>
+   </refsynopsisdiv>
+
+  <refsect1><title>Description</title>
+    <para>
+      Takes a list of coverage snapshots and returns a new coverage snapshot
+      representing a union of all the coverage data.
+    </para>
+  </refsect1>
+</refentry>
+
 
 <refentry id="f_write-coverage-to-file">
@@ -3099,5 +3134,5 @@
   </refsynopsisdiv>
 
-  <refsect1><title>Summary</title>
+  <refsect1><title>Description</title>
     <para>
       Saves the coverage snapshot in a file. The snapshot can be
@@ -3128,5 +3163,5 @@
   </refsynopsisdiv>
 
-  <refsect1><title>Summary</title>
+  <refsect1><title>Description</title>
     <para>
       Returns the snapshot saved in pathname. Doesn't affect the
@@ -3147,5 +3182,5 @@
     <refname>COVERAGE-STATISTICS</refname>
     <refpurpose>
-      Returns a sequence of coverage-statistics objects, one per source file.
+      Returns a sequence of ccl:coverage-statistics objects, one per source file.
     </refpurpose>
     <refclass>Function</refclass>
@@ -3157,5 +3192,5 @@
   </refsynopsisdiv>
 
-  <refsect1><title>Summary</title>
+  <refsect1><title>Description</title>
     <para>
       Returns a sequence ccl:coverage-statistics objects, one for each
@@ -3165,5 +3200,5 @@
       <variablelist>
       <varlistentry>
-	<term><function>ccl:coverage-source-file</function></term>
+	<term><function>coverage-source-file</function></term>
 	<listitem>
 	  <para>
@@ -3173,5 +3208,5 @@
       </varlistentry>
       <varlistentry>
-	<term><function>ccl:coverage-expressions-total</function></term>
+	<term><function>coverage-expressions-total</function></term>
 	<listitem>
 	  <para>
@@ -3181,5 +3216,5 @@
       </varlistentry>
       <varlistentry>
-	<term><function>ccl:coverage-expressions-entered</function></term>
+	<term><function>coverage-expressions-entered</function></term>
 	<listitem>
 	  <para>
@@ -3190,5 +3225,5 @@
       </varlistentry>
       <varlistentry>
-	<term><function>ccl:coverage-expressions-covered</function></term>
+	<term><function>coverage-expressions-covered</function></term>
 	<listitem>
 	  <para>
@@ -3198,5 +3233,5 @@
       </varlistentry>
       <varlistentry>
-	<term><function>ccl:coverage-unreached-branches</function></term>
+	<term><function>coverage-unreached-branches</function></term>
 	<listitem>
 	  <para>
@@ -3206,5 +3241,5 @@
       </varlistentry>
       <varlistentry>
-	<term><function>ccl:coverage-code-forms-total</function></term>
+	<term><function>coverage-code-forms-total</function></term>
 	<listitem>
 	  <para>
@@ -3216,5 +3251,5 @@
       </varlistentry>
       <varlistentry>
-	<term><function>ccl:coverage-code-forms-covered</function></term>
+	<term><function>coverage-code-forms-covered</function></term>
 	<listitem>
 	  <para>
@@ -3224,5 +3259,5 @@
       </varlistentry>
       <varlistentry>
-	<term><function>ccl:coverage-functions-total</function></term>
+	<term><function>coverage-functions-total</function></term>
 	<listitem>
 	  <para>
@@ -3232,5 +3267,5 @@
       </varlistentry>
       <varlistentry>
-	<term><function>ccl:coverage-functions-fully-covered</function></term>
+	<term><function>coverage-functions-fully-covered</function></term>
 	<listitem>
 	  <para>
@@ -3240,5 +3275,5 @@
       </varlistentry>
       <varlistentry>
-	<term><function>ccl:coverage-functions-partly-covered</function></term>
+	<term><function>coverage-functions-partly-covered</function></term>
 	<listitem>
 	  <para>
@@ -3248,5 +3283,5 @@
       </varlistentry>
       <varlistentry>
-	<term><function>ccl:coverage-functions-not-entered</function></term>
+	<term><function>coverage-functions-not-entered</function></term>
 	<listitem>
 	  <para>
@@ -3268,5 +3303,5 @@
     <refname>*COMPILE-CODE-COVERAGE*</refname>
     <refpurpose>
-      When true, instrument functions for code coverage.
+      When true, instrument functions being compiled to collect code coverage information.
     </refpurpose>
     <refclass>Variable</refclass>
@@ -3278,5 +3313,5 @@
   </refsynopsisdiv>
 
-  <refsect1><title>Summary</title>
+  <refsect1><title>Description</title>
     <para>
       This variable controls whether functions are instrumented for
@@ -3305,5 +3340,5 @@
   </refsynopsisdiv>
 
-  <refsect1><title>Summary</title>
+  <refsect1><title>Description</title>
     <para>
       This macro arranges so that body doesn't record internal details
@@ -3316,5 +3351,41 @@
 
 </sect2>
+
+<sect2 id="code-coverage-interpreting-code-coloring"><title>Interpreting Code Coloring</title>
+<para>
+
+ The output of ccl:report-coverage consists of formatted source code, with coverage indicated by
+ coloring.  Four colors are used: dark green for forms that compiled to code in which every single
+ instruction was executed, light green for forms that have been entered but weren't totally covered, red
+ for forms that were never entered, and the page background color for toplevel forms that weren't
+ instrumented.
+
+</para>
+<para>
+ The source coloring is applied from outside in.  So for example if you have
+
+  <programlisting>
+(outer-form ... (inner-form ...) ...)
+  </programlisting>
+
+ first the whole outer form is painted with whatever color expresses the outer form coverage, and then the
+ inner form color is replaced with whatever color expresses the inner form coverage.  One consequence of
+ this approach is that every part of the outer form that is not specifically inside some executable inner
+ form will have the outer form's coverage color. If the syntax of outer form involves some non-executable
+ forms, or forms that do not have coverage info of their own for whatever reason, then they will just
+ inherit the color of the outer form, because it doesn't get replaced with a color of its own.
+</para>
+
+<para>
+ One case in which this approach can be confusing is in the case of symbols.  As noted in the Limitations
+ section, coverage information is not recorded for variables; hence the coloring of a variable does not
+ convey information about whether the variable was evaluated or not -- that information is not available,
+ and the variable just inherits the color of the form that contains it.
+</para>
+
+
+</sect2>
 </sect1>
+
 <sect1 id="other-extensions"><title>Other Extensions</title>
 <refentry id="v_quit">