From cf9be1ea233be86e3dbc5f2d8a1fcb0735d47469 Mon Sep 17 00:00:00 2001 From: zeertzjq Date: Tue, 16 Sep 2025 09:28:37 +0800 Subject: [PATCH] vim-patch:d4c2cb4: runtime(doc): Improve doc for cmdline-ranges in cmdline.txt (#35788) closes: vim/vim#18278 https://github.com/vim/vim/commit/d4c2cb4b271b3e018d13a51245714a387d7006ec Co-authored-by: Peter Kenny --- runtime/doc/cmdline.txt | 98 +++++++++++++++++++++++++++++++---------- runtime/doc/usr_10.txt | 2 + 2 files changed, 76 insertions(+), 24 deletions(-) diff --git a/runtime/doc/cmdline.txt b/runtime/doc/cmdline.txt index 09a7d0a48c..697329abf7 100644 --- a/runtime/doc/cmdline.txt +++ b/runtime/doc/cmdline.txt @@ -701,7 +701,7 @@ 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. - *:,* *:;* + *:,* *:;* When separated with ';' the cursor position will be set to that line before interpreting the next line specifier. This doesn't happen for ','. Examples: > @@ -711,36 +711,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 + + :-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/usr_10.txt b/runtime/doc/usr_10.txt index 98337e4b76..ec79c63775 100644 --- a/runtime/doc/usr_10.txt +++ b/runtime/doc/usr_10.txt @@ -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