vim-patch:d4c2cb4: runtime(doc): Improve doc for cmdline-ranges in cmdline.txt (#35788)

closes: vim/vim#18278

d4c2cb4b27

Co-authored-by: Peter Kenny <github.com@k1w1.cyou>

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.
+commands ":write" and ":global" have the whole buffer (1,$) as default.
-
-If more line specifiers are given than required for the command, the first
-one(s) will be ignored.
 
+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 current line			   *:.*
-	$		the last line in the file		  *:$*
+	$		the last line of the buffer		   *:$*
-	%		equal to 1,$ (the entire file)		  *:%*
+	%		equal to 1,$ (the entire buffer)	   *:%*
-	't		position of mark t (lowercase)		  *:'*
+	*		equal to '<,'> (the lines of the last
-	'T		position of mark T (uppercase); when the mark is in
+			selected Visual area; see |:star| below)
-			another file it cannot be used in a range
+	'x		the line of the position of mark x	   *:'x*
-	/{pattern}[/]	the next line where {pattern} matches	  *:/*
+			(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
+	\/		the next line where the most recent
-			pattern matches
+			search pattern matches
-	\?		the previous line where the previously used search
+	\?		the previous line where the most recent
-			pattern matches
+			search pattern matches
-	\&		the next line where the previously used substitute
+	\&		the next line where the most recent
-			pattern matches
+			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.
+Each line specifier may be followed by one or more '+' or '-' and an optional
-This number is added or subtracted from the preceding line number.  If the
+number.  That value is added or subtracted from the preceding line number.
-number is omitted, 1 is used.  If there is nothing before the '+' or '-' then
+So, for example, 'x+2 is two lines after the line containing mark x.  If the
-the current line is used.
+number is omitted, +1 is used for each '+' and -1 for each '-' so, e.g., 'x++
-						*:range-closed-fold*
+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.
 

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