# HG changeset patch
# User ali <ali@juiblex.co.uk>
# Date 1328602512 0
# Node ID 05d082ebf68584f5a5a20e249e8302f5465852e5
# Parent  6faf1a95a207aa628bd55307a4464d9262e3d0e5
Update documentation

diff -r 6faf1a95a207 -r 05d082ebf685 README
--- a/README	Mon Feb 06 23:55:48 2012 +0000
+++ b/README	Tue Feb 07 08:15:12 2012 +0000
@@ -28,9 +28,10 @@
 Microsoft Windows
 -----------------
 
-It should be possible to use MSYS (http://www.mingw.org/wiki/MSYS) to build
-on a Windows machine. You'll need a copy of the development package for
-glib and its dependencies from http://www.gtk.org/download/win32.php.
+It should be possible to use either MSYS (http://www.mingw.org/wiki/MSYS)
+or cygwin (http://www.cygwin.com/) to build on a Windows machine. You'll
+need a copy of the development package for glib and its dependencies
+from http://www.gtk.org/download/win32.php.
 
 It's much easier to build using a cross-compiler from Linux, if you have
 access to such a system. Under Fedora, RHEL and friends you can do this
diff -r 6faf1a95a207 -r 05d082ebf685 configure.ac
--- a/configure.ac	Mon Feb 06 23:55:48 2012 +0000
+++ b/configure.ac	Tue Feb 07 08:15:12 2012 +0000
@@ -1,7 +1,7 @@
 #                                               -*- Autoconf -*-
 # Process this file with autoconf to produce a configure script.
 
-AC_INIT([bookloupe],[1.51],[ali@juiblex.co.uk])
+AC_INIT([bookloupe],[1.52],[ali@juiblex.co.uk])
 AC_PREREQ(2.59)
 AC_CONFIG_AUX_DIR([config])
 AC_CONFIG_SRCDIR([bookloupe/bookloupe.c])
diff -r 6faf1a95a207 -r 05d082ebf685 doc/loupe-test.txt
--- a/doc/loupe-test.txt	Mon Feb 06 23:55:48 2012 +0000
+++ b/doc/loupe-test.txt	Tue Feb 07 08:15:12 2012 +0000
@@ -142,7 +142,64 @@
        │    Line 3 column 29 - Query possible scanno arid              │
        └───────────────────────────────────────────────────────────────┘
 
-Caveats
--------
+False-positives
+---------------
 
-There is no support yet for testcases which are expected to fail.
+Most of the time, the input can be tweaked so that all warnings bookloupe
+reports represent real errors in the text. Sometimes, however, this either
+cannot be done and still test what we need to. In these cases we need a
+means to describe these false-positives (warnings that do not describe
+a real error). This is important so that a later version of bookloupe can
+be improved to not issue the false-positive warning and still pass the
+test. In order to do this, we need to describe the warnings in a more
+structures manner, like this:
+
+       ┌───────────────────────────────────────────────────────────────┐
+       │**************** OPTIONS ****************                      │
+       │-s                                                             │
+       │**************** INPUT ****************                        │
+       │'In a moment,' Peter replied,' I'm just coming.'               │
+       │                                                               │
+       │'Underneath the girls' scarves.                                │
+       │                                                               │
+       │**************** WARNINGS ****************                     │
+       │<expected>                                                     │
+       │  <error>                                                      │
+       │    <at line="1" column="30"/>                                 │
+       │    <text>Wrongspaced singlequotes?</text>                     │
+       │  </error>                                                     │
+       │  <false-positive>                                             │
+       │    <at line="2"/>                                             │
+       │    <text>Mismatched singlequotes?</text>                      │
+       │  </false-positive>                                            │
+       │  <false-negative>                                             │
+       │    <at line="3" column="1"/>                                  │
+       │    <at line="4"/>                                             │
+       │    <text>Mismatched singlequotes?</text>                      │
+       │  </false-negative>                                            │
+       │</expected>                                                    │
+       └───────────────────────────────────────────────────────────────┘
+
+Here, we use the "WARNINGS" tag instead of "EXPECTED" to denote that we
+wish to use structured warnings and the list of warnings is enclosed in
+an <expected> ... </expected> node.
+
+Each warning, or potential warnings is then described using either an
+"error" node (for warnings that represent real errors in the text), a
+"false-positive" node (for warnings that do not represent real errors),
+or a "false-negative" node (for warnings that should be issued, but that
+are not yet detected by bookloupe).
+
+Within each warning node, there are then one or more "at" nodes which
+list the acceptable locations for the warning to be reported at (the
+first listed should be the preferred location) and exactly one "text"
+node which must match the text of the warning issued.
+
+A testcase will pass if all the warnings marked as errors were issued and
+if no warnings were issued that are not listed in one form or another.
+If the testcase passes with an expected failure (ie., issues a warning
+for a false positive or does not issue a warning for a false negative),
+then the test is counted as passed, but a note will be printed describing
+this, eg.:
+
+sample: PASS (with 1 of 1 false positives and 1 of 1 false negatives)