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 d149f0a19315c5a6f861fb29ba6ff46aab94a8b1..c3364d4fb7dbd19399ac2a05371df18cec7d6058 100644 (file)
--- 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.