runtime(doc): Improve doc for cmdline-ranges in cmdline.txt
Commit:
https://github.com/vim/vim/commit/d4c2cb4b271b3e018d13a51245714a387d7006ec
Author: Peter Kenny <[email protected]>
Date: Mon Sep 15 18:35:53 2025 +0000
runtime(doc): Improve doc for cmdline-ranges in cmdline.txt
closes: https://github.com/vim/vim/issues/18278
Signed-off-by: Peter Kenny <[email protected]>
Signed-off-by: Christian Brabandt <[email protected]>
diff --git a/runtime/doc/cmdline.txt b/runtime/doc/cmdline.txt
index 097ad2d2d..e6f2d146f 100644
--- a/runtime/doc/cmdline.txt
+++ b/runtime/doc/cmdline.txt
@@ -1,4 +1,4 @@
-*cmdline.txt* For Vim version 9.1. Last change: 2025 Sep 10
+*cmdline.txt* For Vim version 9.1. Last change: 2025 Sep 15
VIM REFERENCE MANUAL by Bram Moolenaar
@@ -745,16 +745,17 @@ Some Ex commands accept a line range in front of them.
This is noted as
The basics are explained in section |10.3| of the user manual.
-In |Vim9| script a range needs to be prefixed with a colon to avoid ambiguity
+In |Vim9| script, a range needs to be prefixed with a colon to avoid ambiguity
with continuation lines. For example, "+" can be used for a range but is also
a continuation of an expression: >
var result = start
+ print
-If the "+" is a range then it must be prefixed with a colon: >
- var result = start
+<If the "+" is a range, as it is here, in Vim9 script it must be prefixed
+with a colon (otherwise you will get error |E1050|): >
+ vim9script
:+ print
<
- *:,* *:;*
+ *:,* *:;*
When separated with ';' the cursor position will be set to that line
before interpreting the next line specifier. This doesn't happen for ','.
Examples: >
@@ -764,36 +765,86 @@ Examples: >
< from line 5 till match with "that line" after line 5.
The default line specifier for most commands is the cursor position, but the
-commands ":write" and ":global" have the whole file (1,$) as default.
-
-If more line specifiers are given than required for the command, the first
-one(s) will be ignored.
-
+commands ":write" and ":global" have the whole buffer (1,$) as default.
+
+If more line specifiers are given than required for the command, when comma
+separated, the leftmost one(s) will be ignored, e.g., the -2,+ in this: >
+ :-2,+,-2,. print
+<When semicolon separated, the leftmost specifier to the penultimate one are
+summed, e.g., -4 + 3 - 1 = -2, in this: >
+ :-4;+3;-1;+2 print
+<
Line numbers may be specified with: *:range* *{address}*
{number} an absolute line number *E1247*
- . the current line *:.*
- $ the last line in the file *:$*
- % equal to 1,$ (the entire file) *:%*
- 't position of mark t (lowercase) *:'*
- 'T position of mark T (uppercase); when the mark is in
- another file it cannot be used in a range
- /{pattern}[/] the next line where {pattern} matches *:/*
+ . the current line *:.*
+ $ the last line of the buffer *:$*
+ % equal to 1,$ (the entire buffer) *:%*
+ * equal to '<,'> (the lines of the last
+ selected Visual area; see |:star| below)
+ 'x the line of the position of mark x *:'x*
+ (where x is any {a-z} mark)
+ 'X the line of the position of mark X *:'X*
+ (where X is any {A-Z0-9} mark, though
+ when X is in another buffer it cannot
+ be used in a range)
+ '[ the first line of the most recent *:'[*
+ change or yank
+ '] the last line of the most recent *:']*
+ change or yank
+ '< the first line of the most recently *:'<*
+ selected Visual area
+ '> the last line of the most recently *:'>*
+ selected Visual area
+ '' the line of the position before the *:''*
+ latest jump, or where the last "m'"/"m`"
+ command was given (though '' is 1 if it
+ isn't in the current buffer)
+ '" the line of the cursor position when *:'quote*
+ last exiting the buffer
+ '^ the line of the cursor position the *:'^*
+ last time Insert mode was stopped
+ '. the line of the cursor position when the *:'.*
+ buffer was last changed
+ '( the line of the first character of the *:'(*
+ current sentence
+ ') the line of the first character after *:')*
+ the end of the current sentence
+ '{ the first empty line before the *:'{*
+ paragraph containing the cursor
+ '} the first empty line after the *:'}*
+ paragraph containing the cursor
+ /{pattern}[/] the next line where {pattern} matches *:/*
also see |:range-pattern| below
- ?{pattern}[?] the previous line where {pattern} matches *:?*
+ ?{pattern}[?] the previous line where {pattern} matches *:?*
also see |:range-pattern| below
- \/ the next line where the previously used search
- pattern matches
- \? the previous line where the previously used search
- pattern matches
- \& the next line where the previously used substitute
- pattern matches
+ \/ the next line where the most recent
+ search pattern matches
+ \? the previous line where the most recent
+ search pattern matches
+ \& the next line where the most recent
+ substitute pattern matches
+
+ Note: "next line" and "previous line" do not include matches appearing
+ in the current line.
*:range-offset*
-Each may be followed (several times) by '+' or '-' and an optional number.
-This number is added or subtracted from the preceding line number. If the
-number is omitted, 1 is used. If there is nothing before the '+' or '-' then
-the current line is used.
- *:range-closed-fold*
+Each line specifier may be followed by one or more '+' or '-' and an optional
+number. That value is added or subtracted from the preceding line number.
+So, for example, 'x+2 is two lines after the line containing mark x. If the
+number is omitted, +1 is used for each '+' and -1 for each '-' so, e.g., 'x++
+and 'x+2 are synonymous. If there is nothing before the '+' or '-', for the
+first line number in [range] the current line is used as the relative
+starting point. So, -,. means, "the line before the current line to the
+current line". The value of the second line number in [range] depends on
+whether a comma or semicolon separates the line numbers (see |:,| and |:;|).
+Examples: If the cursor is within the line below this one, any of these
+commands will print the tag line ":range-offset" and the line, "Each...": >
+ :-11;+1 print
+ :-----------,-10 print
+ :?Each line?-;+ print
+ :'{+,'{+2 print
+ :'{+1;')-1 print
+< *:range-closed-fold*
When a line number after the comma is in a closed fold it is adjusted to the
last line of the fold, thus the whole fold is included.
diff --git a/runtime/doc/tags b/runtime/doc/tags
index 31f55bdb0..c47e797c8 100644
--- a/runtime/doc/tags
+++ b/runtime/doc/tags
@@ -2094,7 +2094,20 @@ $quote eval.txt /*$quote*
:% cmdline.txt /*:%*
:& change.txt /*:&*
:&& change.txt /*:&&*
-:' cmdline.txt /*:'*
+:'' cmdline.txt /*:''*
+:'( cmdline.txt /*:'(*
+:') cmdline.txt /*:')*
+:'. cmdline.txt /*:'.*
+:'< cmdline.txt /*:'<*
+:'> cmdline.txt /*:'>*
+:'X cmdline.txt /*:'X*
+:'[ cmdline.txt /*:'[*
+:'] cmdline.txt /*:']*
+:'^ cmdline.txt /*:'^*
+:'quote cmdline.txt /*:'quote*
+:'x cmdline.txt /*:'x*
+:'{ cmdline.txt /*:'{*
+:'} cmdline.txt /*:'}*
:++ vim9.txt /*:++*
:, cmdline.txt /*:,*
:-- vim9.txt /*:--*
diff --git a/runtime/doc/usr_10.txt b/runtime/doc/usr_10.txt
index 29ccd9f88..505ca480f 100644
--- a/runtime/doc/usr_10.txt
+++ b/runtime/doc/usr_10.txt
@@ -1,4 +1,4 @@
-*usr_10.txt* For Vim version 9.1. Last change: 2024 Nov 12
+*usr_10.txt* For Vim version 9.1. Last change: 2025 Sep 15
VIM USER MANUAL - by Bram Moolenaar
@@ -339,6 +339,8 @@ then ":". For example, when you type "5:", you will get: >
Now you can type the command you want to use. It will use the range "."
(current line) until ".+4" (four lines down). Thus it spans five lines.
+See also |:range|, for an overview of all possible ways to specify a range.
+
==============================================================================
*10.4* The global command
--
--
You received this message from the "vim_dev" maillist.
Do not top-post! Type your reply below the text you are replying to.
For more information, visit http://www.vim.org/maillist.php
---
You received this message because you are subscribed to the Google Groups
"vim_dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To view this discussion visit
https://groups.google.com/d/msgid/vim_dev/E1uyECH-008ZrI-Om%40256bit.org.
