i spilled some red ink on the plugin documentation.

1 files changed, 32 insertions, 33 deletions

diff --git a/functional_tests/doc_tests/test_multiprocess/multiprocess.rst b/functional_tests/doc_tests/test_multiprocess/multiprocess.rst
index 1cfa0ab..df11a4f 100644
--- a/functional_tests/doc_tests/test_multiprocess/multiprocess.rst
+++ b/functional_tests/doc_tests/test_multiprocess/multiprocess.rst
@@ -9,12 +9,10 @@ Parallel Testing with nose
 ..
 
 Using the `nose.plugin.multiprocess` plugin, you can parallelize a
-test run across a configurable number of worker processes. This can
-speed up CPU-bound test runs (as long as the number of work
-processeses is around the number of processors or cores available),
-but is mainly useful for IO-bound tests which can benefit from greater
-parallelization, since most of the tests spend most of their time
-waiting for data to arrive from someplace else.
+test run across a configurable number of worker processes. While this can
+speed up CPU-bound test runs, it is mainly useful for IO-bound tests
+that spend most of their time waiting for data to arrive from someplace
+else and can benefit from parallelization.
 
 .. _multiprocessing : http://code.google.com/p/python-multiprocessing/
 
@@ -27,15 +25,16 @@ long as the slowest test. This ideal is not attainable in all cases, however,
 because many test suites depend on context (class, module or package)
 fixtures.
 
-The multiprocess plugin can't know -- unless you tell it -- whether a given
-context fixture is re-entrant (that is, can be called many times
-concurrently), or may be shared among tests running in different processes, or
-must be run once and only once for a given set of tests in the same process as
-the tests. Therefore, if a context has fixtures, the default behavior is to
-dispatch the entire context suite to a worker as a unit, so that the fixtures
-are run once, in the same process as the tests. That of course how they are
-run when the multiprocess plugin is not active and all tests are run in a
-single process.
+Some context fixtures are re-entrant -- that is, they can be called many times
+concurrently. Other context fixtures can be shared among tests running in
+different processes. Still others must be run once and only once for a given
+set of tests, and must be in the same process as the tests themselves.
+
+The plugin can't know the difference between these types of context fixtures
+unless you tell it, so the default behavior is to dispatch the entire context
+suite to a worker as a unit. This way, the fixtures are run once, in the same
+process as the tests. (That, of course, is how they are run when the plugin
+is not active: All tests are run in a single process.)
 
 Controlling distribution
 ^^^^^^^^^^^^^^^^^^^^^^^^
@@ -43,7 +42,7 @@ Controlling distribution
 There are two context-level variables that you can use to control this default
 behavior.
 
-If a context's fixtures are re-entrant, set `_multiprocess_can_split_ = True`
+If a context's fixtures are re-entrant, set ``_multiprocess_can_split_ = True``
 in the context, and the plugin will dispatch tests in suites bound to that
 context as if the context had no fixtures. This means that the fixtures will
 execute multiple times, typically once per test, and concurrently.
@@ -67,7 +66,7 @@ A class might look like::
 Alternatively, If a context's fixtures may only be run once, or may not run
 concurrently, but *may* be shared by tests running in different processes
 -- for instance a package-level fixture that starts an external http server or
-initializes a shared database -- then set `_multiprocess_shared_ = True` in
+initializes a shared database -- then set ``_multiprocess_shared_ = True`` in
 the context. Fixtures for contexts so marked will execute in the primary nose
 process, and tests in those contexts will be individually dispatched to run in
 parallel.
@@ -95,7 +94,7 @@ Example
 ~~~~~~~
 
 Consider three versions of the same test suite. One
-is marked `_multiprocess_shared_`, another `_multiprocess_can_split_`,
+is marked ``_multiprocess_shared_``, another ``_multiprocess_can_split_``,
 and the third is unmarked. They all define the same fixtures:
 
     called = []
@@ -108,7 +107,7 @@ and the third is unmarked. They all define the same fixtures:
         print "teardown called"
         called.append('teardown')
     
-And each has two tests that just test that `setup()` has been called
+And each has two tests that just test that ``setup()`` has been called
 once and only once.
 
 When run without the multiprocess plugin, fixtures for the shared,
@@ -173,12 +172,12 @@ And the module that marks its fixtures as re-entrant.
     <BLANKLINE>
     OK
 
-However, when run with the `--processes=2` switch, each test module
+However, when run with the ``--processes=2`` switch, each test module
 behaves differently.
 
     >>> from nose.plugins.multiprocess import MultiProcess
 
-The module marked `_multiprocess_shared_` executes correctly, although as with
+The module marked ``_multiprocess_shared_`` executes correctly, although as with
 any use of the multiprocess plugin, the order in which the tests execute is
 indeterminate.
 
@@ -202,14 +201,14 @@ Then we can run the tests again with the multiprocess plugin active.
     <BLANKLINE>
     OK
 
-As does the one not marked -- however in this case, `--processes=2`
+As does the one not marked -- however in this case, ``--processes=2``
 will do *nothing at all*: since the tests are in a module with
 unmarked fixtures, the entire test module will be dispatched to a
 single runner process.
 
-However, the module marked `_multiprocess_can_split_` will fail, since
+However, the module marked ``_multiprocess_can_split_`` will fail, since
 the fixtures *are not reentrant*. A module such as this *must not* be
-marked `_multiprocess_can_split_`, or tests will fail in one or more
+marked ``_multiprocess_can_split_``, or tests will fail in one or more
 runner processes as fixtures are re-executed.
 
 We have to reset all of the test modules again.
@@ -230,25 +229,25 @@ Then we can run again and see the failures.
 Other differences in test running
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The main difference between using the multiprocess plugin and not is obviously
-that tests run concurrently under multiprocess. There are a few other
-differences that may also impact your test suite:
+The main difference between using the multiprocess plugin and not doing so
+is obviously that tests run concurrently under multiprocess. However, there
+are a few other differences that may impact your test suite:
 
 * More tests may be found
 
   Because tests are dispatched to worker processes by name, a worker
   process may find and run tests in a module that would not be found during a
-  normal test run. For instance, if a non-test module contains a testlike
-  function, that function would be discovered as a test in a worker process,
+  normal test run. For instance, if a non-test module contains a test-like
+  function, that function would be discovered as a test in a worker process
   if the entire module is dispatched to the worker. This is because worker
   processes load tests in *directed* mode -- the same way that nose loads
-  tests when you explicitly name a module -- rather than *discovered* mode,
+  tests when you explicitly name a module -- rather than in *discovered* mode,
   the mode nose uses when looking for tests in a directory.
 
 * Out-of-order output
 
   Test results are collected by workers and returned to the master process for
-  output. Since difference processes may complete their tests at different
+  output. Since different processes may complete their tests at different
   times, test result output order is not determinate.
 
 * Plugin interaction warning
@@ -262,9 +261,9 @@ differences that may also impact your test suite:
 * Python 2.6 warning
 
   This is unlikely to impact you unless you are writing tests for nose itself,
-  but be aware that under python 2.6, the multprocess plugin is not
+  but be aware that under python 2.6, the multiprocess plugin is not
   re-entrant. For example, when running nose with the plugin active, you can't
   use subprocess to launch another copy of nose that also uses the
   multiprocess plugin. This is why this test is skipped under python 2.6 when
-  run with the --processes switch.
+  run with the ``--processes`` switch.