From 26e5768207677b1287f183ff054431a9733e5c13 Mon Sep 17 00:00:00 2001 From: Tim Allen Date: Tue, 9 Oct 2018 14:18:21 +1100 Subject: [PATCH] Be specific about the units of ranges and cursor positions. --- doc/pages/expansions.asciidoc | 19 ++++++++++++------- doc/pages/options.asciidoc | 20 +++++++++++++------- 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 (`., - .` or `.+`) - 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 <>) + a timestamp (like `%val{timestamp}`, + see <>) + 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 + <>) `set -add` appends the new pair to the list *line-specs*::