runtime(doc): clarify documentation for "v" position at line()

Problem: the previous documentation falsely states that "v" always
refers to the start of a visual area.  In fact, the reference of "v" and
"." complement each other.  If the cursor is at the start of
a (characterwise) visual area, then "v" refers to the end of the area.

Solution: be more verbose and explicit about the connection between "."
and "v" and also refer to |v_o| which many vim users will be familiar
with for visual areas.

Signed-off-by: Peter Aronoff <peter@aronoff.org>
Signed-off-by: Christian Brabandt <cb@256bit.org>

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 2ed94ea9321428f92cc63e614ad5870cb7c597da..66f1bae1325192b1e988dcb929c6c8237ccf2567 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: 2024 Jun 06
+*builtin.txt*  For Vim version 9.1.  Last change: 2024 Jun 11
 
 
                  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -6191,10 +6191,21 @@ line({expr} [, {winid}])                                *line()*
                            display isn't updated, e.g. in silent Ex mode)
                    w$      last line visible in current window (this is one
                            less than "w0" if no lines are visible)
-                   v       In Visual mode: the start of the Visual area (the
-                           cursor is the end).  When not in Visual mode
-                           returns the cursor position.  Differs from |'<| in
-                           that it's updated right away.
+                   v       When not in Visual mode, returns the cursor
+                           position.  In Visual mode, returns the other end
+                           of the Visual area.  A good way to think about
+                           this is that in Visual mode "v" and "." complement
+                           each other.  While "." refers to the cursor
+                           position, "v" refers to where |v_o| would move the
+                           cursor.  As a result, you can use "v" and "."
+                           together to work on all of a selection in
+                           characterwise visual mode.  If the cursor is at
+                           the end of a characterwise visual area, "v" refers
+                           to the start of the same visual area.  And if the
+                           cursor is at the start of a characterwise visual
+                           area, "v" refers to the end of the same visual
+                           area.  "v" differs from |'<| and |'>| in that it's
+                           updated right away.
                Note that a mark in another file can be used.  The line number
                then applies to another buffer.
                To get the column number use |col()|.  To get both use