commit 72155121006bca884e154e935640054f2e090367
parent 033810ba23c25a98b7aeb703d1d61463bfcab503
Author: zeertzjq <zeertzjq@outlook.com>
Date: Wed, 12 Jun 2024 11:44:38 +0800
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>
Diffstat:
3 files changed, 45 insertions(+), 12 deletions(-)
diff --git 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
@@ -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
@@ -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
