Update documentation 1.52
authorali <ali@juiblex.co.uk>
Tue Feb 07 08:15:12 2012 +0000 (2012-02-07)
changeset 1905d082ebf685
parent 18 6faf1a95a207
child 20 411a8e696a47
Update documentation
README
configure.ac
doc/loupe-test.txt
     1.1 --- a/README	Mon Feb 06 23:55:48 2012 +0000
     1.2 +++ b/README	Tue Feb 07 08:15:12 2012 +0000
     1.3 @@ -28,9 +28,10 @@
     1.4  Microsoft Windows
     1.5  -----------------
     1.6  
     1.7 -It should be possible to use MSYS (http://www.mingw.org/wiki/MSYS) to build
     1.8 -on a Windows machine. You'll need a copy of the development package for
     1.9 -glib and its dependencies from http://www.gtk.org/download/win32.php.
    1.10 +It should be possible to use either MSYS (http://www.mingw.org/wiki/MSYS)
    1.11 +or cygwin (http://www.cygwin.com/) to build on a Windows machine. You'll
    1.12 +need a copy of the development package for glib and its dependencies
    1.13 +from http://www.gtk.org/download/win32.php.
    1.14  
    1.15  It's much easier to build using a cross-compiler from Linux, if you have
    1.16  access to such a system. Under Fedora, RHEL and friends you can do this
     2.1 --- a/configure.ac	Mon Feb 06 23:55:48 2012 +0000
     2.2 +++ b/configure.ac	Tue Feb 07 08:15:12 2012 +0000
     2.3 @@ -1,7 +1,7 @@
     2.4  #                                               -*- Autoconf -*-
     2.5  # Process this file with autoconf to produce a configure script.
     2.6  
     2.7 -AC_INIT([bookloupe],[1.51],[ali@juiblex.co.uk])
     2.8 +AC_INIT([bookloupe],[1.52],[ali@juiblex.co.uk])
     2.9  AC_PREREQ(2.59)
    2.10  AC_CONFIG_AUX_DIR([config])
    2.11  AC_CONFIG_SRCDIR([bookloupe/bookloupe.c])
     3.1 --- a/doc/loupe-test.txt	Mon Feb 06 23:55:48 2012 +0000
     3.2 +++ b/doc/loupe-test.txt	Tue Feb 07 08:15:12 2012 +0000
     3.3 @@ -142,7 +142,64 @@
     3.4         │    Line 3 column 29 - Query possible scanno arid              │
     3.5         └───────────────────────────────────────────────────────────────┘
     3.6  
     3.7 -Caveats
     3.8 --------
     3.9 +False-positives
    3.10 +---------------
    3.11  
    3.12 -There is no support yet for testcases which are expected to fail.
    3.13 +Most of the time, the input can be tweaked so that all warnings bookloupe
    3.14 +reports represent real errors in the text. Sometimes, however, this either
    3.15 +cannot be done and still test what we need to. In these cases we need a
    3.16 +means to describe these false-positives (warnings that do not describe
    3.17 +a real error). This is important so that a later version of bookloupe can
    3.18 +be improved to not issue the false-positive warning and still pass the
    3.19 +test. In order to do this, we need to describe the warnings in a more
    3.20 +structures manner, like this:
    3.21 +
    3.22 +       ┌───────────────────────────────────────────────────────────────┐
    3.23 +       │**************** OPTIONS ****************                      │
    3.24 +       │-s                                                             │
    3.25 +       │**************** INPUT ****************                        │
    3.26 +       │'In a moment,' Peter replied,' I'm just coming.'               │
    3.27 +       │                                                               │
    3.28 +       │'Underneath the girls' scarves.                                │
    3.29 +       │                                                               │
    3.30 +       │**************** WARNINGS ****************                     │
    3.31 +       │<expected>                                                     │
    3.32 +       │  <error>                                                      │
    3.33 +       │    <at line="1" column="30"/>                                 │
    3.34 +       │    <text>Wrongspaced singlequotes?</text>                     │
    3.35 +       │  </error>                                                     │
    3.36 +       │  <false-positive>                                             │
    3.37 +       │    <at line="2"/>                                             │
    3.38 +       │    <text>Mismatched singlequotes?</text>                      │
    3.39 +       │  </false-positive>                                            │
    3.40 +       │  <false-negative>                                             │
    3.41 +       │    <at line="3" column="1"/>                                  │
    3.42 +       │    <at line="4"/>                                             │
    3.43 +       │    <text>Mismatched singlequotes?</text>                      │
    3.44 +       │  </false-negative>                                            │
    3.45 +       │</expected>                                                    │
    3.46 +       └───────────────────────────────────────────────────────────────┘
    3.47 +
    3.48 +Here, we use the "WARNINGS" tag instead of "EXPECTED" to denote that we
    3.49 +wish to use structured warnings and the list of warnings is enclosed in
    3.50 +an <expected> ... </expected> node.
    3.51 +
    3.52 +Each warning, or potential warnings is then described using either an
    3.53 +"error" node (for warnings that represent real errors in the text), a
    3.54 +"false-positive" node (for warnings that do not represent real errors),
    3.55 +or a "false-negative" node (for warnings that should be issued, but that
    3.56 +are not yet detected by bookloupe).
    3.57 +
    3.58 +Within each warning node, there are then one or more "at" nodes which
    3.59 +list the acceptable locations for the warning to be reported at (the
    3.60 +first listed should be the preferred location) and exactly one "text"
    3.61 +node which must match the text of the warning issued.
    3.62 +
    3.63 +A testcase will pass if all the warnings marked as errors were issued and
    3.64 +if no warnings were issued that are not listed in one form or another.
    3.65 +If the testcase passes with an expected failure (ie., issues a warning
    3.66 +for a false positive or does not issue a warning for a false negative),
    3.67 +then the test is counted as passed, but a note will be printed describing
    3.68 +this, eg.:
    3.69 +
    3.70 +sample: PASS (with 1 of 1 false positives and 1 of 1 false negatives)