diff -r f600b0d1fc5d -r eca715c100fe doc/loupe-test.txt
--- a/doc/loupe-test.txt	Fri Jan 27 10:30:16 2012 +0000
+++ b/doc/loupe-test.txt	Tue Jan 31 01:07:38 2012 +0000
@@ -63,6 +63,86 @@
 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.
+Non-ASCII testcases
+-------------------
+
+The testcase definitions (the .tst files) are always written in UTF-8
+which is a superset of ASCII. Since gutcheck does not understand UTF-8
+this causes a problem when it is desired to include characters that
+are not in ASCII in a testcase. To solve this problem it is possible
+to specify an encoding to use for the test. It is very important to
+undertand that this specifies the encoding that loupe-test will use to
+talk to bookloupe/gutcheck and _not_ the encoding of the .tst file
+(which remains UTF-8). gutcheck understands Latin-1 (at least to a
+limited extent), the canonical name for which is ISO-8859-1:
+
+      ┌─────────────────────────────────────────────────────────────────┐
+      │**************** ENCODING ****************                       │
+      │ISO-8859-1                                                       │
+      │**************** INPUT ****************                          │
+      │"Hello," he said, "I wanted to bave a tête-à-tête with you."     │
+      │**************** EXPECTED ****************                       │
+      │                                                                 │
+      │"Hello," he said, "I wanted to bave a tête-à-tête with you."     │
+      │    Line 1 column 31 - Query word bave - not reporting duplicates│
+      └─────────────────────────────────────────────────────────────────┘
+
+Embedded linefeeds
+------------------
+
+One of the tests that bookloupe/gutcheck need to do is check that all
+lines are ended with CR NL (as required by PG) rather than the UNIX
+standard NL. loupe-test deliberately ignores the line endings in testcase
+definition files and always uses CR NL. Thus there is needed a means
+to embed a linefeed (aka newline) character into the input to be sent
+to bookloupe/gutcheck to test that it correctly identified the problem.
+loupe-test recognises the unicode symbol for linefeed (U+240A): ␊ which
+can be used for this purpose instead of a normal newline.
+
+Passing command line options
+----------------------------
+
+Some of bookloupe's functionality is only available using command line
+options. loupe-test provides a means of specifying these with the
+OPTIONS tag:
+
+		┌──────────────────────────────────────────┐
+                │**************** OPTIONS **************** │
+                │-m                                        │
+                │-d                                        │
+                │**************** INPUT ****************   │
+                │&ldquo;He went <i>thataway!</i>&rdquo;    │
+                │**************** EXPECTED ****************│
+		└──────────────────────────────────────────┘
+
+Extra input files
+-----------------
+
+Under certain circumstances, bookloupe reads other input files than just
+the ebook. These can be specified in the testcase definition file by
+adding the name of the file to the INPUT tag:
+
+       ┌───────────────────────────────────────────────────────────────┐
+       │**************** OPTIONS ****************                      │
+       │-u                                                             │
+       │**************** INPUT(gutcheck.typ) ****************          │
+       │arid                                                           │
+       │**************** INPUT ****************                        │
+       │I am the very model of a modern Major-General,                 │
+       │I've information vegetable, animal, and mineral,               │
+       │I know the kings of England, arid I quote the fights historical│
+       │From Marathon to Waterloo, in order categorical;               │
+       │I'm very well acquainted, too, with matters mathematical,      │
+       │I understand equations, both the simple and quadratical,       │
+       │About binomial theorem I'm teeming with a lot o' news--        │
+       │With many cheerful facts about the square of the hypotenuse.   │
+       │**************** EXPECTED ****************                     │
+       │                                                               │
+       │I know the kings of England, arid I quote the fights historical│
+       │    Line 3 column 29 - Query possible scanno arid              │
+       └───────────────────────────────────────────────────────────────┘
+
+Caveats
+-------
+
+There is no support yet for testcases which are expected to fail.