Update the README.

1 files changed, 52 insertions, 38 deletions

diff --git a/README b/README
index c4cb119..82b393e 100644
--- a/README
+++ b/README
@@ -1,33 +1,36 @@
 CoverageTestRunner
 ==================
 
-The Python standard library unittest aids in implementing and running
-unit tests. The coverage.py module (not in the standard library) measures
+The Python standard library module `unittest` aids in implementing and running
+unit tests. The `coverage.py` module (not in the standard library) measures
 which parts of a program are executed. A proper unit test suite will
-execute all parts of a program. CoverageTestRunner uses coverage.py to
-run test suites implemented with unittest, and fails the tests if they
+execute all parts of a program. `CoverageTestRunner` uses `coverage.py` to
+run test suites implemented with `unittest`, and fails the tests if they
 do not test the entire program.
 
-CoverageTestRunner makes some assumptions, the most important of which is
+`CoverageTestRunner` makes some assumptions, the most important is
 that the test suite is written so that each module corresponds to a test
 module, and that test module should execute everything in the module.
+If there is a code module `foo.py`, then it must be fully tested by
+`foo_tests.py`.
 
 Ideally, we would test each class and its corresponding test suite, but
-unfortunately coverage.py only allows module granularity. It also only
+unfortunately `coverage.py` only allows module granularity. It also only
 measures at the statement level. This is, however, typically better
 than can be achieved without any measurement tools.
 
 
 Example
-=======
+-------
 
-Assume a Python module in foo.py, and its test suite in foo_tests.py.
-Then running the test suite using CoverageTestRunner can be very simple:
+Assume a Python module in `foo.py`, and its test suite in `foo_tests.py`
+in the same directory.
+Then running the test suite using `CoverageTestRunner` can be very simple:
 
     python -m CoverageTestRunner
 
-This will invoke the module's main program, which scans the current 
-directory (and its subdirectories) for test modules with corresponding
+`CoverageTestRunner` scans the current 
+directory and its subdirectories for test modules with corresponding
 code modules, based on filenames, and then executes them pairwise.
 
 If you have a more complicated setup, you can pair the code and test
@@ -41,9 +44,9 @@ modules manually, using a wrapper script such as follows:
 
 
 Output
-======
+------
 
-CoverageTestRunner writes its output to the standard output, and for
+`CoverageTestRunner` writes its output to the standard output, and for
 a successful run it looks like this:
 
     Running test 2/2: testTrue (foo_tests.FooTests) 
@@ -80,7 +83,7 @@ An unsuccessful run might look like this (shortened for space reasons):
     1 failures, 3 errors
     Time: 5.4 s
 
-In this case, after the line with "FAILED" comes a list of all the
+In this case, after the line with `FAILED` comes a list of all the
 failed tests, with some indication of why they failed, complete with
 Python stack traces. Additionally, if some parts of the code were not
 executed during the tests, a list of files and statement numbers is
@@ -88,11 +91,11 @@ included in the output.
 
 
 Excluding some statements from the coverage analysis
-====================================================
+----------------------------------------------------
 
-Use "# pragma: no cover" to exclude some statements from being included
+Use `# pragma: no cover` to exclude some statements from being included
 in the coverage analysis. The line with that comment is excluded. If
-the line is an if, while, def, or similar, with a "body", the body
+the line is an `if`, `while`, `def`, or similar, with a body, the body
 is also excluded. For example:
 
     if always_true_during_testing:
@@ -106,10 +109,22 @@ if the test suite does not execute them.
 You should only use this after thorough consideration.
 
 
+Excluding whole modules
+-----------------------
+
+Sometimes there are code modules that should not have test modules.
+For example, `setup.py`. You can use the `--ignore-missing` option
+to ignore all such problem, or `--ignore-missing-from=FILE` to
+list excluded modules explicitly.
+
+By default, the `setup.py` module is automatically excluded. However,
+if you list any modules explicitly, you should also list `setup.py`.
+
+
 Your tests are too slow
-=======================
+-----------------------
 
-CoverageTestRunner keeps track of how long each test takes. If the total
+`CoverageTestRunner` keeps track of how long each test takes. If the total
 run time of the tests is more than ten seconds, even if all tests pass,
 it then prints out a list of the slowest tests. This is useful for projects
 whose test suites should run quickly so that developers don't mind running
@@ -121,17 +136,16 @@ set the time limit.
 
 
 Contacts
-========
+--------
 
-Python's unittest is part of the standard library, and was (originally?)
-written by Steve Purcell. coverage.py was originally written by Gareth
+Python's `unittest` is part of the standard library, and was (originally?)
+written by Steve Purcell. `coverage.py` was originally written by Gareth
 Rees and is now maintained by Net Batchelder. Its home page is at
 
     http://www.nedbatchelder.com/code/modules/coverage.html
 
-CoverageTestRunner was written by Lars Wirzenius (liw@iki.fi), and is
-licensed under the GNU General Public License version 2 or at your option
-any later version. The home page is at
+CoverageTestRunner was written by Lars Wirzenius (`liw@liw.fi`). 
+The home page is at
 
     http://braawi.org/coveragetestrunner.html
 
@@ -139,19 +153,19 @@ I welcome any feedback you may have.
 
 
 License
-=======
+--------
 
 Copyright 2007-2011  Lars Wirzenius <liw@liw.fi>
 
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-# 
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-# 
-# You should have received a copy of the GNU General Public License
-# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+ 
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+ 
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.