[gegl] docs: update abyss_policy.adoc

[Øyvind "pippin" Kolås <ok src gnome org>]

commit 275f7983b66f0d409813ad3b4d077918cb39dd2d
Author: John <jtm home gmail com>
Date:   Sun Feb 14 23:13:46 2021 +0000

    docs: update abyss_policy.adoc

 docs/abyss_policy.adoc | 43 +++++++++++++++++++++++--------------------
 1 file changed, 23 insertions(+), 20 deletions(-)
---
diff --git a/docs/abyss_policy.adoc b/docs/abyss_policy.adoc
index e1e862bad..6e395b6fe 100644
--- a/docs/abyss_policy.adoc
+++ b/docs/abyss_policy.adoc
@@ -1,23 +1,26 @@
-gegl_buffer_get and gegl_buffer_set are the functions to read and
-write pixels in a GeglBuffer. They both take an array of pixels and
-write/read data from tiles according to the region of interest.
+Abyss policy
+------------
 
-Abyss is a rectangle that defines what area of the buffer is
-readable. Abyss policy determines how to read pixels when the
-requested region of interest (or pixel) is not contained within the
-abyss. Abyss policy only affects reading and not writing of pixels and
-does so when gegl_buffer_get is called. Each policy has a separate
-iterator function that reads data to the array. If the region of
-interest is inside the abyss rectangle a simple read function is used
-to avoid the overhead of dealing with abyss. Abyss policy also affects
-samplers since they use gegl_bufer_get.
+Pixels are read from and written to a `GeglBuffer` using the functions
+`gegl_buffer_get()` and `gegl_buffer_set()`. Both functions take an
+array of pixels and write/read data from tiles according to the region
+of interest.
 
-There are 5 abyss policies represented by the following enums
-GEGL_ABYSS_NONE - abyss pixels are zeroed
-GEGL_ABYSS_WHITE - abyss pixels are white
-GEGL_ABYSS_BLACK - abyss pixels are black
-GEGL_ABYSS_CLAMP - each pixel's coordinates are clamped to the abyss
-rectangle
-GEGL_ABYSS_LOOP - each pixel's coordinates wrap when exceeding the
-abyss rectangle (the buffer is essentially tiled)
+The abyss is the rectangle that defines the part of the buffer that is
+readable. The abyss policy determines how the values of pixels within
+the buffer but outside the abyss are interpreted. It is applied when
+`gegl_buffer_get()` is called. Each policy has a separate iterator
+function that reads data to the array. If the region of interest is
+inside the abyss rectangle a simple read function is used to avoid the
+overhead of dealing with abyss. Abyss policy also affects samplers since
+they use `gegl_buffer_get()`.
 
+There are 5 abyss policies represented by the following enums:
+
+* `GEGL_ABYSS_NONE` - abyss pixels are zeroed
+* `GEGL_ABYSS_WHITE` - abyss pixels are white
+* `GEGL_ABYSS_BLACK` - abyss pixels are black
+* `GEGL_ABYSS_CLAMP` - each pixel's coordinates are clamped to the abyss
+    rectangle
+* `GEGL_ABYSS_LOOP` - each pixel's coordinates wrap when exceeding the
+    abyss rectangle (the buffer is essentially tiled)