Finish doc'ing the new source code options.

5 files changed, 51 insertions, 37 deletions

diff --git a/doc/changes.rst b/doc/changes.rst
index 91af28be..e2e393f2 100644
--- a/doc/changes.rst
+++ b/doc/changes.rst
@@ -65,7 +65,7 @@ Version 3.2 --- 5 December 2009
 
 - Branch coverage: coverage.py can tell you which branches didn't have both (or
   all) choices executed, even where the choice doesn't affect which lines were
-  executed.  See :ref:`Branch Coverage <branch>` for more details.
+  executed.  See :ref:`branch` for more details.
 
 - The table of contents in the HTML report is now sortable: click the headers
   on any column.  The sorting is persisted so that subsequent reports are
diff --git a/doc/cmd.rst b/doc/cmd.rst
index c0eb85d0..b31b3d1d 100644
--- a/doc/cmd.rst
+++ b/doc/cmd.rst
@@ -44,8 +44,7 @@ Any command can use a configuration file by specifying it with the
 line can also be set in the configuration file.  This can be a better way to
 control coverage.py since the configuration file can be checked into source
 control, and can provide options that other invocation techniques (like test
-runner plugins) may not offer. See :ref:`Configuration Files <config>` for more
-details.
+runner plugins) may not offer. See :ref:`config` for more details.
 
 
 .. _cmd_execution:
@@ -83,7 +82,7 @@ can also be enabled by setting the environment variable COVERAGE_OPTIONS to
 
 If you are measuring coverage in a multi-process program, or across a number of
 machines, you'll want the ``--parallel-mode`` switch to keep the data separate
-during measurement.  See :ref:`Combining data files <cmd_combining>` below.
+during measurement.  See :ref:`cmd_combining` below.
 
 
 .. _cmd_datafile:
@@ -111,7 +110,7 @@ Combining data files
 
 If you need to collect coverage data from different machines or processes,
 coverage can combine multiple files into one for reporting. Use the ``-p`` flag
-during execution to append a machine name and process id to the .coverage data
+during execution to append distinguishing information to the .coverage data
 file name.
 
 Once you have created a number of these files, you can copy them all to a single
@@ -126,8 +125,29 @@ data file::
 Reporting
 ---------
 
-Coverage provides a few styles of reporting.  The simplest is a textual summary
-produced with **report**::
+Coverage provides a few styles of reporting, with the ``report``, ``html``,
+``annotate``, and ``xml`` commands.  They share a number of common options.
+
+The command-line arguments are module or file names to report on, if you'd like
+to report on a subset of the data collected.
+
+The ``--include`` and ``--omit`` flags specify lists of filename patterns. They
+control which files to report on, and are described in more detail
+in :ref:`source`.
+
+The ``-i`` or ``--ignore-errors`` switch tells coverage.py to ignore problems
+encountered trying to find source files to report on.  This can be useful if
+some files are missing, or if your Python execution is tricky enough that file
+names are synthesized without real source files.
+
+
+
+.. _cmd_summary:
+
+Coverage summary
+----------------
+
+The simplest reporting is a textual summary produced with **report**::
 
     $ coverage report
     Name                      Stmts   Exec  Cover
@@ -164,15 +184,7 @@ command line::
     -------------------------------------------------------
     TOTAL                        76     66    87%
 
-The ``--omit`` flag omits files that begin with specified prefixes. For example,
-this will omit any modules in the django directory::
-
-    $ coverage report -m --omit django
-
-.. TODO: modules are morfs.
-.. TODO: omit is file patterns now
-.. TODO Missing: --include
-.. TODO Missing: -i
+Other common reporting options are described above in :ref:`cmd_reporting`.
 
 
 .. _cmd_html:
@@ -197,9 +209,7 @@ The ``-d`` argument specifies an output directory, defaulting to "htmlcov"::
 
     $ coverage html -d coverage_html
 
-.. TODO: modules are morfs.
-.. TODO Missing: -i
-.. TODO Missing: --omit --include
+Other common reporting options are described above in :ref:`cmd_reporting`.
 
 
 .. _cmd_annotation:
@@ -231,9 +241,7 @@ For example::
     >     else:
     >         a = 2
 
-.. TODO: modules are morfs.
-.. TODO Missing: -i
-.. TODO Missing: --omit --include
+Other common reporting options are described above in :ref:`cmd_reporting`.
 
 
 .. _cmd_xml:
@@ -246,10 +254,9 @@ compatible with `Cobertura`_.
 
 .. _Cobertura: http://cobertura.sourceforge.net
 
-.. TODO: modules are morfs.
-.. TODO Missing: -i
-.. TODO Missing: --omit --include
-.. TODO Missing: --output-xml
+You can specify the name of the output file with the ``--output-xml`` switch.
+
+Other common reporting options are described above in :ref:`cmd_reporting`.
 
 
 .. _cmd_debug:
diff --git a/doc/config.rst b/doc/config.rst
index d3c38768..2e0cd766 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -12,7 +12,7 @@ specification of options that are otherwise only available in the
 :ref:`API <api>`.
 
 Configuration files also make it easier to get coverage testing of spawned
-sub-processes.  See :ref:`Subprocess measurement <subprocess>` for more details.
+sub-processes.  See :ref:`subprocess` for more details.
 
 
 
@@ -77,14 +77,22 @@ standard library.
 ``data_file`` (string, default ".coverage"): the name of the data file to use
 for storing or reporting coverage.
 
+``include`` (multi-string): a list of filename patterns, the files to include
+in measurement or reporting.  See :ref:`source` for details.
+
+``omit`` (multi-string): a list of filename patterns, the files to leave out
+of measurement or reporting.  See :ref:`source` for details.
+
 ``parallel`` (boolean, default False): append the machine name, process
 id and random number to the data file name to simplify collecting data from
-many processes.
+many processes.  See :ref:`cmd_combining` for more information.
+
+``source`` (multi-string): a list of packages or directories, the source to
+measure during execution.  See :ref:`source` for details.
 
 ``timid`` (boolean, default False): use a simpler but slower trace method.
 Try this if you get seemingly impossible results.
 
-.. TODO missing: source, include, omit.
 
 [report]
 --------
@@ -100,11 +108,12 @@ supply the "pragma: no cover" regex if you still want to use it.
 ``ignore_errors`` (boolean, default False): ignore source code that can't be
 found.
 
-``omit`` (multi-string): a list of file prefixes.  If a source file begins with
-one of these prefixes, it will be omitted from the report.
+``include`` (multi-string): a list of filename patterns, the files to include
+in reporting.  See :ref:`source` for details.
+
+``omit`` (multi-string): a list of filename patterns, the files to leave out
+of reporting.  See :ref:`source` for details.
 
-.. TODO: omit is file patterns now
-.. TODO missing: include
 
 [html]
 ------
diff --git a/doc/index.rst b/doc/index.rst
index 7d608160..094962e7 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -79,8 +79,7 @@ Some test runners provide coverage integration to make it easy to use coverage
 while running tests.  For example, `nose`_ has a `cover plug-in`_.
 
 You can fine-tune coverage's view of your code by directing it to ignore parts
-that you know aren't interesting.  See :ref:`Excluding Code <excluding>` for
-details.
+that you know aren't interesting.  See :ref:`excluding` for details.
 
 .. _nose:           http://somethingaboutorange.com/mrl/projects/nose
 .. _cover plug-in:  http://somethingaboutorange.com/mrl/projects/nose/0.11.1/plugins/cover.html
diff --git a/doc/source.rst b/doc/source.rst
index edfc2fcf..e39090a4 100644
--- a/doc/source.rst
+++ b/doc/source.rst
@@ -70,7 +70,6 @@ collected, so the data you're looking for may not be in the data available for
 reporting.
 
 Note that these are ways of specifying files to measure.  You can also exclude
-individual source lines.  See :ref:`Excluding code from coverage <excluding>`
-for details.
+individual source lines.  See :ref:`excluding` for details.