From: Larson, Eric <numeric.larson@gmail.com>
Date: Sat, 3 Jan 2026 16:46:59 +0000 (+0000)
Subject: runtime(doc): Clarify visual mark behavior in getpos(), setpos()
X-Git-Tag: v9.1.2046~1
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=93eb081eee92180a495d72a495542b24a873e2f3;p=thirdparty%2Fvim.git

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.larson@gmail.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>
---

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index d149f0a193..c3364d4fb7 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.