Update documentation
authorali <ali@juiblex.co.uk>
Mon Jan 30 09:11:07 2012 +0000 (2012-01-30)
changeset 10f28ad4577863
parent 9 6a13fe0fc19e
child 11 4a80c6053a66
Update documentation
README
configure.ac
doc/loupe-test.txt
     1.1 --- a/README	Mon Jan 30 00:36:31 2012 +0000
     1.2 +++ b/README	Mon Jan 30 09:11:07 2012 +0000
     1.3 @@ -54,11 +54,56 @@
     1.4  Mac
     1.5  ---
     1.6  
     1.7 -I think this should be quite similar to Linux, doing something like this:
     1.8 +The least intrusive means to build on a Mac is to use Homebrew:
     1.9  
    1.10 -% sudo port install gcc pkgconfig glib2-devel
    1.11 -% ./configure
    1.12 -% make
    1.13 -% sudo make install
    1.14 +http://mxcl.github.com/homebrew/
    1.15  
    1.16 -It may also be possible to use fink instead of macports.
    1.17 +Install Homebrew according to its instructions.
    1.18 +
    1.19 +If you are building bookloupe for your own use, you can use dynamic linking
    1.20 +like this:
    1.21 +
    1.22 +$ brew install glib
    1.23 +
    1.24 +and then install bookloupe using:
    1.25 +
    1.26 +$ ./configure
    1.27 +$ make
    1.28 +$ make install
    1.29 +
    1.30 +If you want to build bookloupe for other people to use, you will probably
    1.31 +want to link staticly. To do this you need to edit the formula for glib
    1.32 +and each of its dependencies (gettext and libffi) using something like:
    1.33 +
    1.34 +$ brew edit gettext
    1.35 +
    1.36 +Each time find the args statement which includes --prefix and insert
    1.37 +--disable-shared,for example change:
    1.38 +
    1.39 +args = ["--disable-dependency-tracking", "--disable-rebuilds",
    1.40 +           "--prefix=#{prefix}",
    1.41 +           "--disable-dtrace"]
    1.42 +
    1.43 +to
    1.44 +
    1.45 +args = ["--disable-dependency-tracking", "--disable-rebuilds",
    1.46 +           "--disable-shared",
    1.47 +           "--prefix=#{prefix}",
    1.48 +           "--disable-dtrace"]
    1.49 +
    1.50 +and then
    1.51 +
    1.52 +$ brew install glib
    1.53 +
    1.54 +before installing bookloupe as normal, but with the extra flag to configure:
    1.55 +
    1.56 +$ ./configure --disable-shared
    1.57 +$ make
    1.58 +$ make install
    1.59 +
    1.60 +Note that if you have previously used dynamic linking this may not work.
    1.61 +(Homebrew doesn't seem to create .la files in a form that libtool can use
    1.62 +when it is asked to prefer static libraries to dynamic ones.) Removing the
    1.63 +dynamic libraries first will solve this problem.
    1.64 +
    1.65 +It may also be possible to use fink or macports.
     2.1 --- a/configure.ac	Mon Jan 30 00:36:31 2012 +0000
     2.2 +++ b/configure.ac	Mon Jan 30 09:11:07 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.50],[ali@juiblex.co.uk])
     2.8 +AC_INIT([bookloupe],[1.51],[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 Jan 30 00:36:31 2012 +0000
     3.2 +++ b/doc/loupe-test.txt	Mon Jan 30 09:11:07 2012 +0000
     3.3 @@ -63,6 +63,86 @@
     3.4  tag, then loupe-test will consider that no expectation exists and won't
     3.5  check the output at all.
     3.6  
     3.7 -There is no support yet for non-ASCII testcases, embedded linefeeds,
     3.8 -passing command line options to bookloupe or for testcases which are
     3.9 -expected to fail.
    3.10 +Non-ASCII testcases
    3.11 +-------------------
    3.12 +
    3.13 +The testcase definitions (the .tst files) are always written in UTF-8
    3.14 +which is a superset of ASCII. Since gutcheck does not understand UTF-8
    3.15 +this causes a problem when it is desired to include characters that
    3.16 +are not in ASCII in a testcase. To solve this problem it is possible
    3.17 +to specify an encoding to use for the test. It is very important to
    3.18 +undertand that this specifies the encoding that loupe-test will use to
    3.19 +talk to bookloupe/gutcheck and _not_ the encoding of the .tst file
    3.20 +(which remains UTF-8). gutcheck understands Latin-1 (at least to a
    3.21 +limited extent), the canonical name for which is ISO-8859-1:
    3.22 +
    3.23 +      ┌─────────────────────────────────────────────────────────────────┐
    3.24 +      │**************** ENCODING ****************                       │
    3.25 +      │ISO-8859-1                                                       │
    3.26 +      │**************** INPUT ****************                          │
    3.27 +      │"Hello," he said, "I wanted to bave a tête-à-tête with you."     │
    3.28 +      │**************** EXPECTED ****************                       │
    3.29 +      │                                                                 │
    3.30 +      │"Hello," he said, "I wanted to bave a tête-à-tête with you."     │
    3.31 +      │    Line 1 column 31 - Query word bave - not reporting duplicates│
    3.32 +      └─────────────────────────────────────────────────────────────────┘
    3.33 +
    3.34 +Embedded linefeeds
    3.35 +------------------
    3.36 +
    3.37 +One of the tests that bookloupe/gutcheck need to do is check that all
    3.38 +lines are ended with CR NL (as required by PG) rather than the UNIX
    3.39 +standard NL. loupe-test deliberately ignores the line endings in testcase
    3.40 +definition files and always uses CR NL. Thus there is needed a means
    3.41 +to embed a linefeed (aka newline) character into the input to be sent
    3.42 +to bookloupe/gutcheck to test that it correctly identified the problem.
    3.43 +loupe-test recognises the unicode symbol for linefeed (U+240A): ␊ which
    3.44 +can be used for this purpose instead of a normal newline.
    3.45 +
    3.46 +Passing command line options
    3.47 +----------------------------
    3.48 +
    3.49 +Some of bookloupe's functionality is only available using command line
    3.50 +options. loupe-test provides a means of specifying these with the
    3.51 +OPTIONS tag:
    3.52 +
    3.53 +		┌──────────────────────────────────────────┐
    3.54 +                │**************** OPTIONS **************** │
    3.55 +                │-m                                        │
    3.56 +                │-d                                        │
    3.57 +                │**************** INPUT ****************   │
    3.58 +                │&ldquo;He went <i>thataway!</i>&rdquo;    │
    3.59 +                │**************** EXPECTED ****************│
    3.60 +		└──────────────────────────────────────────┘
    3.61 +
    3.62 +Extra input files
    3.63 +-----------------
    3.64 +
    3.65 +Under certain circumstances, bookloupe reads other input files than just
    3.66 +the ebook. These can be specified in the testcase definition file by
    3.67 +adding the name of the file to the INPUT tag:
    3.68 +
    3.69 +       ┌───────────────────────────────────────────────────────────────┐
    3.70 +       │**************** OPTIONS ****************                      │
    3.71 +       │-u                                                             │
    3.72 +       │**************** INPUT(gutcheck.typ) ****************          │
    3.73 +       │arid                                                           │
    3.74 +       │**************** INPUT ****************                        │
    3.75 +       │I am the very model of a modern Major-General,                 │
    3.76 +       │I've information vegetable, animal, and mineral,               │
    3.77 +       │I know the kings of England, arid I quote the fights historical│
    3.78 +       │From Marathon to Waterloo, in order categorical;               │
    3.79 +       │I'm very well acquainted, too, with matters mathematical,      │
    3.80 +       │I understand equations, both the simple and quadratical,       │
    3.81 +       │About binomial theorem I'm teeming with a lot o' news--        │
    3.82 +       │With many cheerful facts about the square of the hypotenuse.   │
    3.83 +       │**************** EXPECTED ****************                     │
    3.84 +       │                                                               │
    3.85 +       │I know the kings of England, arid I quote the fights historical│
    3.86 +       │    Line 3 column 29 - Query possible scanno arid              │
    3.87 +       └───────────────────────────────────────────────────────────────┘
    3.88 +
    3.89 +Caveats
    3.90 +-------
    3.91 +
    3.92 +There is no support yet for testcases which are expected to fail.