Merge remote-tracking branch 'Screwtapello/ranges-use-bytes'

2 files changed, 25 insertions, 14 deletions

diff --git a/doc/pages/expansions.asciidoc b/doc/pages/expansions.asciidoc
index 4a105a3d..6649a571 100644
--- a/doc/pages/expansions.asciidoc
+++ b/doc/pages/expansions.asciidoc
@@ -199,8 +199,10 @@ The following expansions are supported (with required context _in italics_):
 
 *%val{cursor_char_column}*::
     _in window scope_ +
-    column of the main cursor (in characters), the fourth component of
-    `%val{selection_desc}`
+    1-based offset from the start of the line to the cursor position in
+    Unicode codepoints, which may differ from visible columns if the document
+    contains full-width codepoints (which occupy two columns) or zero-width
+    codepoints
 
 *%val{cursor_char_value}*::
     _in window scope_ +
@@ -208,7 +210,9 @@ The following expansions are supported (with required context _in italics_):
 
 *%val{cursor_column}*::
     _in window scope_ +
-    column of the main cursor (in bytes)
+    1-based offset from the start of the line to the first byte of the
+    character under the main cursor (in bytes), the fourth component of
+    `%val{selection_desc}`
 
 *%val{cursor_line}*::
     _in window scope_ +
@@ -250,10 +254,11 @@ The following expansions are supported (with required context _in italics_):
 
 *%val{selection_desc}*::
     _in window scope_ +
-    range of the main selection, represented as `a.b,c.d` where _a_
-    is the anchor line, _b_ is the anchor column, _c_ is the cursor
-    line (like `%val{cursor_line}`), _d_ is the cursor column (like
-    `%val{cursor_char_column}`), and all are 1-based decimal integers
+    range of the main selection, represented as `a.b,c.d` where _a_ is the
+    anchor line, _b_ is the number of bytes from the start of the line to the
+    anchor, _c_ is the cursor line (like `%val{cursor_line}`), _d_ is
+    the number of bytes from the start of the line to the cursor (like
+    `%val{cursor_column}`), and all are 1-based decimal integers
 
 *%val{selections_desc}*::
     _in window scope_ +
diff --git a/doc/pages/options.asciidoc b/doc/pages/options.asciidoc
index e76641f0..043b7ba1 100644
--- a/doc/pages/options.asciidoc
+++ b/doc/pages/options.asciidoc
@@ -86,13 +86,19 @@ are exclusively available to built-in options.
     `declare-option`.
 
 *range-specs*::
-    a list of a pair of a buffer range (`<begin line>.<begin column>,
-    <end line>.<end column>` or `<begin line>.<begin column>+<length>`)
-    and a string (separated by `|`), except for the first element which
-    is just the timestamp of the buffer. When the `update-option` is
-    used on an option of this type, its ranges gets updated according
-    to all the buffer modifications that happened since its timestamp.
-    See <<highlighters#specs-highlighters,`:doc highlighters specs-highlighters`>>)
+    a timestamp (like `%val{timestamp}`,
+    see <<expansions#value-expansions,`:doc expansions value-expansions`>>)
+    followed by a list of range descriptors. Each range descriptor must use
+    the syntax `a.b,c.d|string` or `a.b+length|string`, where _a_ is the line
+    containing the first character, _b_ is the number of bytes from the start
+    of the line to the first byte of the first character, _c_ is the line
+    containing the last character, _d_ is the number of bytes from the start of
+    the line to the first byte of the last character, _length_ is the length of
+    the range in bytes and _string_ is an arbitrary string which is associated
+    with the range. All numeric fields are 1-based. When the `update-option` is
+    used on an option of this type, its ranges gets updated according to all the
+    buffer modifications that happened since its timestamp. See
+    <<highlighters#specs-highlighters,`:doc highlighters specs-highlighters`>>)
     `set -add` appends the new pair to the list
 
 *line-specs*::