diff -r 000000000000 -r ec364358631b doc/gc-test.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/gc-test.txt	Thu Jan 26 23:35:52 2012 +0000
@@ -0,0 +1,64 @@
+                            gutcheck test framework
+                            =======================
+
+Running existing testcases
+--------------------------
+
+The test harness (the program that runs a test) is called gc-test. The various
+testcases are stored in multiple text files, typically with a .tst extension.
+
+To run a testcase when all of gutcheck, gc-test and the testcase file are
+in the current directory simply do something like:
+
+% gc-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> gc-test missing-space.tst
+
+To run all the tests in the current directory, do something like this:
+
+% gc-test *.tst
+
+If gutcheck is not in the current directory, then you can set an environment
+variable (GUTCHECK) to point at it. For example, on MS-Windows you might do:
+
+C:\DP> set GUTCHECK=C:\GUTCHECK\GUTCHECK.EXE
+C:\DP> gc-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 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 gutcheck normally outputs is not included in the
+expected output. This avoids problems with not knowing beforehand the name
+of the file that gutcheck will be asked to look at (and saves typing!).
+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 gutcheck produces no output, you still need to include
+an EXPECTED tag, just with no text following it. If there is no EXPECTED
+tag, then gc-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 gutcheck or for testcases which are
+expected to fail.