Commit: runtime(doc): Clarify visual mark behavior in getpos(), setpos()

[Christian Brabandt]

runtime(doc): Clarify visual mark behavior in getpos(), setpos()

Commit: https://github.com/vim/vim/commit/93eb081eee92180a495d72a495542b24a873e2f3
Author: Larson, Eric <numeric...@gmail.com>
Date: Sat Jan 3 16:46:59 2026 +0000

runtime(doc): Clarify visual mark behavior in getpos(), setpos()

Add documentation notes explaining that visual marks '< and '> have
different behaviors in getpos() and setpos().

Also fix a small typo.

closes: #19070

Signed-off-by: Larson, Eric <numeric...@gmail.com>
Signed-off-by: Christian Brabandt <c...@256bit.org>

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index d149f0a19..c3364d4fb 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -1,4 +1,4 @@
-*builtin.txt* For Vim version 9.1. Last change: 2025 Dec 21
+*builtin.txt* For Vim version 9.1. Last change: 2026 Jan 03


VIM REFERENCE MANUAL by Bram Moolenaar
@@ -4879,6 +4879,11 @@ getpos({expr}) *getpos()*
within the line. To get the character position in the line,
use |getcharpos()|.

+ The visual marks |'<| and |'>| refer to the beginning and end
+ of the visual selection relative to the buffer. Note that
+ this differs from |setpos()|, where they are relative to the
+ cursor position.
+
Note that for '< and '> Visual mode matters: when it is "V"
(visual line mode) the column of '< is zero and the column of
'> is a large number equal to |v:maxcol|.
@@ -10152,9 +10157,14 @@ setpos({expr}, {list}) *setpos()*
preferred column is not set. When it is present and setting a
mark position it is not used.

- Note that for '< and '> changing the line number may result in
- the marks to be effectively be swapped, so that '< is always
- before '>.
+ Note that for |'<| and |'>| changing the line number may
+ result in the marks to be effectively swapped, so that |'<| is
+ always before |'>|.
+
+ The visual marks |'<| and |'>| refer to the beginning and end
+ of the visual selection relative to the cursor position.
+ Note that this differs from |getpos()|, where they are
+ relative to the buffer.

Returns 0 when the position could be set, -1 otherwise.
An error message is given if {expr} is invalid.