1.1 --- a/doc/loupe-test.txt Fri Jan 27 10:30:16 2012 +0000
1.2 +++ b/doc/loupe-test.txt Mon Jan 30 23:32:57 2012 +0000
1.3 @@ -63,6 +63,86 @@
1.4 tag, then loupe-test will consider that no expectation exists and won't
1.5 check the output at all.
1.6
1.7 -There is no support yet for non-ASCII testcases, embedded linefeeds,
1.8 -passing command line options to bookloupe or for testcases which are
1.9 -expected to fail.
1.10 +Non-ASCII testcases
1.11 +-------------------
1.12 +
1.13 +The testcase definitions (the .tst files) are always written in UTF-8
1.14 +which is a superset of ASCII. Since gutcheck does not understand UTF-8
1.15 +this causes a problem when it is desired to include characters that
1.16 +are not in ASCII in a testcase. To solve this problem it is possible
1.17 +to specify an encoding to use for the test. It is very important to
1.18 +undertand that this specifies the encoding that loupe-test will use to
1.19 +talk to bookloupe/gutcheck and _not_ the encoding of the .tst file
1.20 +(which remains UTF-8). gutcheck understands Latin-1 (at least to a
1.21 +limited extent), the canonical name for which is ISO-8859-1:
1.22 +
1.23 + ┌─────────────────────────────────────────────────────────────────┐
1.24 + │**************** ENCODING **************** │
1.25 + │ISO-8859-1 │
1.26 + │**************** INPUT **************** │
1.27 + │"Hello," he said, "I wanted to bave a tête-à-tête with you." │
1.28 + │**************** EXPECTED **************** │
1.29 + │ │
1.30 + │"Hello," he said, "I wanted to bave a tête-à-tête with you." │
1.31 + │ Line 1 column 31 - Query word bave - not reporting duplicates│
1.32 + └─────────────────────────────────────────────────────────────────┘
1.33 +
1.34 +Embedded linefeeds
1.35 +------------------
1.36 +
1.37 +One of the tests that bookloupe/gutcheck need to do is check that all
1.38 +lines are ended with CR NL (as required by PG) rather than the UNIX
1.39 +standard NL. loupe-test deliberately ignores the line endings in testcase
1.40 +definition files and always uses CR NL. Thus there is needed a means
1.41 +to embed a linefeed (aka newline) character into the input to be sent
1.42 +to bookloupe/gutcheck to test that it correctly identified the problem.
1.43 +loupe-test recognises the unicode symbol for linefeed (U+240A): ␊ which
1.44 +can be used for this purpose instead of a normal newline.
1.45 +
1.46 +Passing command line options
1.47 +----------------------------
1.48 +
1.49 +Some of bookloupe's functionality is only available using command line
1.50 +options. loupe-test provides a means of specifying these with the
1.51 +OPTIONS tag:
1.52 +
1.53 + ┌──────────────────────────────────────────┐
1.54 + │**************** OPTIONS **************** │
1.55 + │-m │
1.56 + │-d │
1.57 + │**************** INPUT **************** │
1.58 + │“He went <i>thataway!</i>” │
1.59 + │**************** EXPECTED ****************│
1.60 + └──────────────────────────────────────────┘
1.61 +
1.62 +Extra input files
1.63 +-----------------
1.64 +
1.65 +Under certain circumstances, bookloupe reads other input files than just
1.66 +the ebook. These can be specified in the testcase definition file by
1.67 +adding the name of the file to the INPUT tag:
1.68 +
1.69 + ┌───────────────────────────────────────────────────────────────┐
1.70 + │**************** OPTIONS **************** │
1.71 + │-u │
1.72 + │**************** INPUT(gutcheck.typ) **************** │
1.73 + │arid │
1.74 + │**************** INPUT **************** │
1.75 + │I am the very model of a modern Major-General, │
1.76 + │I've information vegetable, animal, and mineral, │
1.77 + │I know the kings of England, arid I quote the fights historical│
1.78 + │From Marathon to Waterloo, in order categorical; │
1.79 + │I'm very well acquainted, too, with matters mathematical, │
1.80 + │I understand equations, both the simple and quadratical, │
1.81 + │About binomial theorem I'm teeming with a lot o' news-- │
1.82 + │With many cheerful facts about the square of the hypotenuse. │
1.83 + │**************** EXPECTED **************** │
1.84 + │ │
1.85 + │I know the kings of England, arid I quote the fights historical│
1.86 + │ Line 3 column 29 - Query possible scanno arid │
1.87 + └───────────────────────────────────────────────────────────────┘
1.88 +
1.89 +Caveats
1.90 +-------
1.91 +
1.92 +There is no support yet for testcases which are expected to fail.