README formatting, spelling and some readability changes.

1 files changed, 54 insertions, 37 deletions

diff --git a/README b/README
index 35dcdd6..e569685 100644
--- a/README
+++ b/README
@@ -18,48 +18,65 @@ Dependencies:
 Note that pyunit3k is required for *running* the tests for testresources. You
 can use testresources in your own app without using pyunit3k.
 
+
 How testresources works:
 ========================
+
 There are three main components to make testresources work:
+
 1) testresources.TestResource
-   A TestResource is a object that tests can use, which provide a getResource()
-   method that returns and object implementing whichever interface the client
-   needs, and which will accept that same object back on its finishedWith()
-   method.
-   Commonly the TestResource will be a class, though that is not a requirement.
-   Most importantly, two getResources with no finishedWith call in the middle,
-   to the same TestResource, should return the same object.
-   XXX the same object requirement may not be needed - but for expensive
-   resources that is the optimisation goal.
-   The goals for TestResources that cannot finish properly are not yet clear,
-   so for now the behaviour will to silently continue.
-   See pydoc testresources.TestResource for details.
-2) testresources.OptimisingTestSuite
-   This TestSuite will introspect all the test cases it holds directly and
-   if they declare needed resources, will run the tests in an order that
-   attempts to minimise the number of setup and tear downs required.
-   It attempts to achieve this by callling getResource() and finishedWith()
-   around the sequence of tests that use a specific resource.
-
-   OptimisingTestSuite has a new method over normal TestSuites:
-   adsorbSuite(suite), which scans another test suite and incorporates all of
-   its tests directly into the OptimisingTestSuite. This allows for you to
-   optimise across as broad or small a collection of tests as you wish.
+
+A TestResource is an object that tests can use, which provides a getResource()
+method that returns an object implementing whichever interface the client
+needs, and which will accept that same object back on its finishedWith()
+method.
+
+Most importantly, two getResources to the same TestResource with no
+finishedWith call in the middle, should return the same object.
+
+    XXX the same object requirement may not be needed - but for expensive
+    resources that is the optimisation goal. -- rbc
+
+The goals for TestResources that cannot finish properly are not yet clear, so
+for now the behaviour will to silently continue.
+
+See pydoc testresources.TestResource for details.
+
+
+2) testresources.OptimizingTestSuite
+
+This TestSuite will introspect all the test cases it holds directly and if
+they declare needed resources, will run the tests in an order that attempts to
+minimise the number of setup and tear downs required. It attempts to achieve
+this by callling getResource() and finishedWith() around the sequence of tests
+that use a specific resource.
+
+OptimisingTestSuite has a new method over normal TestSuites:
+flatAddTest(test_case_or_suite), which scans another test suite and
+incorporates all of its tests directly into the OptimisingTestSuite. This
+allows for you to optimise across as broad or small a collection of tests as
+you wish.
+
+    XXX - that last sentence needs some unpacking, I think. -- jml
+
 
 3) testresources.ResourcedTestCase
-   ResourceTestCase can be used as a base class for tests, and when that is
-   done tests will have their _resources attribute automatically checked for
-   resources by both OptimisingTestSuite and their own setUp() and tearDown()
-   methods. (This allows tests to remain functional without needing this
-   specific TestSuite as a container). Alternatively, you can call
-   ResourceTestCase.setUpResources(self) and
-   ResourceTestCase.tearDownResources(self) from your own classes setUp and
-   tearDown and the same behaviour will be activated.
-
-   Do declare the use of a resource, set _resources as an attribute listing
-   tuples of attribute name, TestResource. During setUp self._attribute_name
-   will be set to TestResource.getResource(), and finsh() will be called for
-   you during tearDown().
+
+ResourceTestCase can be used as a base class for tests, and when that is done
+tests will have their resources attribute automatically checked for resources
+by both OptimizingTestSuite and their own setUp() and tearDown() methods.
+(This allows tests to remain functional without needing this specific
+TestSuite as a container). Alternatively, you can call
+ResourceTestCase.setUpResources(self) and
+ResourceTestCase.tearDownResources(self) from your own classes setUp and
+tearDown and the same behaviour will be activated.
+
+To declare the use of a resource, set resources as an attribute listing tuples
+of (attribute name, TestResource). During setUp, self._attribute_name will be
+set to TestResource.getResource(), and finishedWith() will be called for you
+during tearDown().
+
 
 4) testresources.TestLoader
-   This is a trivial TestLoader that creates OptimisingTestSuites by default.
+
+This is a trivial TestLoader that creates OptimizingTestSuites by default.