diff -r c2f4c0285180 -r faab25d520dd doc/loupe-test.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/loupe-test.txt	Fri Jan 27 16:18:02 2012 +0000
@@ -0,0 +1,68 @@
+                           bookloupe test framework
+                           ========================
+
+Running existing testcases
+--------------------------
+
+The test harness (the program that runs a test) is called loupe-test. The
+various testcases are stored in multiple text files, typically with a .tst
+extension.
+
+To run a testcase when all of bookloupe, loupe-test and the testcase file are
+in the current directory simply do something like:
+
+% loupe-test missing-space.tst
+
+from a command prompt. Under MS-Windows, this is called a command window and
+the prompt will normally look slightly different, eg.,
+
+C:\DP> loupe-test missing-space.tst
+
+To run all the tests in the current directory, do something like this:
+
+% loupe-test *.tst
+
+If bookloupe is not in the current directory or you want to run the testsuite
+against gutcheck (the program that bookloupe is based on), then you can set an
+environment variable (BOOKLOUPE) to point at it. For example, on MS-Windows
+you might do:
+
+C:\DP> set BOOKLOUPE=C:\GUTCHECK\GUTCHECK.EXE
+C:\DP> loupe-test *.tst
+
+Writing your own testcases
+--------------------------
+
+Writing a new testcase is pretty painless. Most testcases follow this simple
+pattern:
+
+		┌──────────────────────────────────────────┐
+		│**************** INPUT ****************   │
+		│"Look!John, over there!"                  │
+		│**************** EXPECTED ****************│
+		│                                          │
+		│"Look!John, over there!"                  │
+		│    Line 1 column 6 - Missing space?      │
+		└──────────────────────────────────────────┘
+
+The sixteen asterisks in this example form what is known as the "flag". This
+flag must come before and after all tags (eg., INPUT and EXPECTED). In the
+unlikely event that you need sixteen asterisks at the start of a line of text,
+then simply choose a different flag and use it throughout the file (flags
+can be any sequence of ASCII characters except control codes and space).
+
+Note that the header that bookloupe and gutcheck normally output is not
+included in the expected output. This avoids problems with not knowing
+beforehand the name of the file that bookloupe/gutcheck will be asked to
+look at (and saves typing!). bookloupe (and gutcheck) prints a blank line
+before each warning. These are not part of the header and so do need to
+be included.
+
+To test that bookloupe produces no output, you still need to include
+an EXPECTED tag, just with no text following it. If there is no EXPECTED
+tag, then loupe-test will consider that no expectation exists and won't
+check the output at all.
+
+There is no support yet for non-ASCII testcases, embedded linefeeds,
+passing command line options to bookloupe or for testcases which are
+expected to fail.