vim-patch:210b39c: runtime(doc): clarify documentation for "v" position at line() (#29296)

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.

https://github.com/vim/vim/commit/210b39c2d686d875e2464ca1f42131453dc6bd41

Co-authored-by: Peter Aronoff <peter@aronoff.org>

3 files changed, 45 insertions, 12 deletions

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 1a762c6ec0..8ee01d6156 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -4102,10 +4102,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
diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index 87e2852efd..ad057d902b 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -4971,10 +4971,21 @@ function vim.fn.libcallnr(libname, funcname, argument) end
 ---       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
diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua
index 0e7b0bf4ec..f5706f9553 100644
--- a/src/nvim/eval.lua
+++ b/src/nvim/eval.lua
@@ -6081,10 +6081,21 @@ M.funcs = {
       	    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