1.1 --- a/README.mkd	Tue Oct 25 22:15:17 2016 +0200
     1.2 +++ b/README.mkd	Mon Oct 31 13:06:31 2016 +0100
     1.3 @@ -1,4 +1,4 @@
     1.4 -pgLatLon v0.9 documentation
     1.5 +pgLatLon v0.10 documentation
     1.6  ===========================
     1.7  
     1.8  pgLatLon is a spatial database extension for the PostgreSQL object-relational
     1.9 @@ -39,8 +39,8 @@
    1.10  It is also possible to compile and install the extension without GNU Make as
    1.11  follows:
    1.12  
    1.13 -    cc -Wall -O2 -fPIC -shared -I `pg_config --includedir-server` -o latlon-v0008.so latlon-v0008.c
    1.14 -    cp latlon-v0008.so `pg_config --pkglibdir`
    1.15 +    cc -Wall -O2 -fPIC -shared -I `pg_config --includedir-server` -o latlon-v0009.so latlon-v0009.c
    1.16 +    cp latlon-v0009.so `pg_config --pkglibdir`
    1.17      cp latlon.control `pg_config --sharedir`/extension/
    1.18      cp latlon--*.sql `pg_config --sharedir`/extension/
    1.19  
    1.20 @@ -484,22 +484,40 @@
    1.21  The penalty by which the returned distance is increased fulfills (at least) the
    1.22  following properties:
    1.23  
    1.24 -* For search points far away from the `ecluster` (i.e. distance approaching
    1.25 -  infinity), the penalty approaches zero (i.e. `fair_distance` behaves the same
    1.26 -  as `distance`).
    1.27 +* The penalty function is continuous (except noise created by numerical
    1.28 +  integration, see paragraph after this list) as long as no objects are added
    1.29 +  to or removed from the `ecluster`. That particularly means: small changes in
    1.30 +  the search point (second argument) cause only small changes in the result.
    1.31 +* For search points far away from the `ecluster` (i.e. large distances compared
    1.32 +  to the dimensions of the `ecluster`), the penalty approaches zero, i.e. the
    1.33 +  behavior of the `fair_distance` function approaches the behavior of the
    1.34 +  `distance` function.
    1.35  * If the `ecluster` consists of a set of points, the penalty for a search point
    1.36 -  close to one of that points (closer than half of the minimum distance between
    1.37 -  each pair of points in the `ecluster`) is chosen in such a way that the
    1.38 -  adjusted distance is equal to the distance from the search point to the
    1.39 +  close to one of those points (closer than half of the minimum distance
    1.40 +  between each pair of points in the `ecluster`) is chosen in such a way that
    1.41 +  the adjusted distance is equal to the distance from the search point to the
    1.42    closest point in the `ecluster` multiplied by the square root of the count of
    1.43    points in the `ecluster`.
    1.44 +* If the `ecluster` does not cover any area (i.e. only consists of points,
    1.45 +  paths, and/or outlines), and if the search point (second argument) overlaps
    1.46 +  with the `ecluster`, then the penalty (and thus the result) is zero.
    1.47 +* The integral (or average) of the square of the fair distance value (result of
    1.48 +  this function) over all possible search points is independent of the
    1.49 +  `ecluster` as long as the `ecluster` does not cover more than a half of
    1.50 +  earth's surface.
    1.51  
    1.52 -The function interally uses numerical integration (Monte Carlo like) to compute
    1.53 -the result. The third parameter (which defaults to 10000) can be used to adjust
    1.54 -the number of samples taken. It is ensured that the penalty is always positive,
    1.55 -i.e. results returned by the `fair_distance` function are always equal to or
    1.56 -greater than the results returned by the `distance` function regardless of
    1.57 -stochastic effects.
    1.58 +The function uses numerical integration to compute the result. The third
    1.59 +parameter (which defaults to 10000) can be used to adjust the number of samples
    1.60 +taken. A higher sample count increases precision as well as execution time of
    1.61 +the function. Because this function internally uses a spherical model of earth
    1.62 +for certain steps of the calculation, the precision cannot be increased
    1.63 +unboundedly.
    1.64 +
    1.65 +Despite the limitations explained above, it is ensured that the penalty is
    1.66 +always positive, i.e. results returned by the `fair_distance` function are
    1.67 +always equal to or greater than the results returned by the `distance`
    1.68 +function regardless of stochastic effects.  Furthermore, all results are
    1.69 +deterministic and reproducible with the same version of pgLatLon.
    1.70  
    1.71  #### `GeoJSON_to_epoint(jsonb, text)`
    1.72