README.markdown in testr-14.1.0 vs README.markdown in testr-14.1.1

@@ -26,11 +26,11 @@
   * Logs the output from your tests into separate files: one log per test.
     The path of a log file is simply the path of its test file plus ".log".
 
   * Configurable through a Ruby script in your current working directory.
 
-  * Implemented in less than 360 lines (SLOC) of pure Ruby code! :-)
+  * Implemented in less than 380 lines (SLOC) of pure Ruby code! :-)
 
 ------------------------------------------------------------------------------
 Architecture
 ------------------------------------------------------------------------------
 
@@ -42,10 +42,27 @@
 * `testr-master` absorbs test execution overhead and forks to run your tests
 
 You can build your own custom TestR user interface by wrapping `testr-driver`!
 
 ------------------------------------------------------------------------------
+Usage and theory of operation
+------------------------------------------------------------------------------
+
+Run `testr` to launch the command-line user interface for `testr-driver`.  It
+will present a menu of commands and then wait for you to input a command while
+the driver waits for `testr-herald` to tell it about changes in your tests.
+
+When the driver hears about changes in your test files, it tells the master to
+fork a worker process to run the tests affected by those changes.  This is all
+performed automatically.  But what if you want to manually run a test file?
+
+You can re-run any test file by simply saving it!  When you do, TestR tries to
+figure out which tests inside your newly saved test file have changed (using
+diff and regexps) and then attempts to run just those.  To make it run *all*
+tests in your saved file, simply save the file *again* without changing it.
+
+------------------------------------------------------------------------------
 Prerequisites
 ------------------------------------------------------------------------------
 
   * Ruby 1.8.7 or 1.9.2 or newer.
 
@@ -250,20 +267,20 @@
 overhead) because that would necessitate the reloading of said overhead
 whenever you change an existing factory definition or create a new one.
 
 Instead, use `at_exit()` to wait until (1) after the master process has forked
 a worker process and (2) just before that worker process runs its test suite
-(whose execution is started by your test framework's own `at_exit()` handler).
+(whose execution is started by your test framework's own `at_exit()` handler):
 
+    require 'factory_girl'
+    at_exit { FactoryGirl.find_definitions unless $! }
+
 This way, worker processes will pick up changes in your factories "for free"
 whenever they (re)run your test files.  Also, don't load your factories or do
 anything else in your `at_exit()` handler if Ruby is exiting because of a
-raised exception (denoted by the `$!` global variable in the snippet below).
+raised exception (denoted by the `$!` global variable in the snippet above).
 
-    require 'factory_girl'
-    at_exit { FactoryGirl.find_definitions unless $! }
-
 ------------------------------------------------------------------------------
 Known issues
 ------------------------------------------------------------------------------
 
 ### Ruby on Rails
@@ -275,14 +292,16 @@
         config.cache_classes = false
 
     Otherwise, TestR will appear to ignore source-code changes in your
     models, controllers, helpers, and other Ruby source files.
 
-  * SQLite3 [raises `SQLite3::BusyException: database is locked` errors](
-    https://github.com/sunaku/test-loop/issues/2 ) because TestR runs your
-    test files in parallel.  You can work around this by using an [in-memory
-    adapter for SQLite3]( https://github.com/mvz/memory_test_fix ) or by using
+  * If SQLite3 raises one of the following errors, try using an [in-memory
+    adapter for SQLite3]( https://github.com/mvz/memory_test_fix ) or use
     different database software (such as MySQL) for your test environment.
+
+    * SQLite3::BusyException: database is locked
+
+    * cannot start a transaction within a transaction
 
 ------------------------------------------------------------------------------
 License
 ------------------------------------------------------------------------------