[vim/vim] Improve doc for cmdline-ranges in cmdline.txt (PR #18278)

[Peter Kenny]

Improvements to cmdline-ranges

While writing a help file for a plugin, I started listing all the potential line number specifiers but then thought Why not just reference the Vim help? and wondered where it is. The closest is at *cmdline-ranges*, though it has only some specifiers. So this help update addresses that, along with a few other things either side of that passage in cmdline.txt, including some distinguising and corrective points.

1. Lines 748-757 now provide clearer, sourceable scripts to illustrate that, in Vim9 script, a range must be prefixed with a colon, including a hotlink to E1050 in vim9.txt, which goes into more detail.
2. Line 769 uses “whole buffer” rather than “whole file” (which is better and aligned with :h :write, which has, “Write the whole buffer…”).
3. Line 771 is clearer, using “leftmost one(s)” rather than “first ones”, providing a sourceable script to demonstrate the point, which may not be immediately obvious. Also, the statement was only correct for comma separated line specifiers. When semicolon separated, the behaviour is different. So, that is covered with explanations and examples demonstrating the difference. (Whether that is the intention, who knows, but it is clear from the examples superfluous , versus ; work differently in practice.)
4. Lines 778 to 826. Now all line specifiers are listed (I think). Issues with the current help are addressed too:
   • $ was “in the file”, which should be either “in the buffer” or could be omitted.
   • % was “the entire file”, which should be “the entire buffer”.
   • 't and 'T:
     • These read, “position of mark...”, which is better reworded to a line reference, so, “the line of the position of mark...”.
     • It's better to distinguish {a-z}, {A-Z0-9}, and the many other marks to explain what is available.
     • The formatting was a bit off for the 'T line in that it looked messy going into the tags “column”, which is fixed. The “table” now has three distinct, non-overlapping, “columns”.
     • Changing 't to 'x is more consistent with usage elsewhere. For example, getpos() in builtin.txt uses 'x.
     • Finally, the tag :' is made :'x and :'X, which distinguishes it/them from the other new tags, outlined below.
   • It is more helpful to provide a comprehensive list of line specifiers. The marks '< and '> especially may generate “aha” moments (e.g., :'<,'> from using : in a Visual mode is common, though perhaps not well understood?). There are nuances to these that make them worth spelling out too given their linewise operation.
     • *, since it is another range synonym like %, is included for completeness. It is covered later in detail, so a hotlink to :star makes sense too.
     • Further to the point, above, 'x/'X have the :' tag removed. (Although it could be retained, with the addition of the other ' tags, the :' aggregated tag does not seem necessary.)
     • '[ to '} are added. Some are particularly useful, so awareness of them, and what they represent in a linewise context, is helpful. Corresponding tags are added for each too.
     • \/, \?, and \& are slightly reworded to, “most recent”, rather than, “previously used”, which is ambiguous. (Does “previously used” mean “the most recent”, “the penultimately most recent”, “any previous”, etc.?)
     • A note clarifies that where “next line” and “previous line” are used the current line is not included. That is important because, when using /, for example, /mypattern from the cursor will find matches within the current line whereas :/mypattern/ finds mypattern after the current line.
5. Lines 830-846. The explanation of :range-offset was scant and questionable.
   • The first sentence could have been interpreted as meaning multiple '+' or '-' are required (i.e., it read, “may be followed (several times) by '+' or '-'”).
   • Although “Each” was unlikely to be misunderstood when the prior passage had been read as well, by itself it isn’t clear what, “Each” is referring to. Now, it is clear.
   • The expanded explanation covers lots more, including the distinction between using '+' or '-' as the line specifier for the first versus the last line of a range, hotlinking back to :, and :;, which are important distinctions.
   • The explanation is rounded out with examples, which tie together not only the points regarding how '+' and '-' work, but also some of the line specifiers explained in the expanded :range list.

---

You can view, comment on, or merge this pull request online at:

  https://github.com/vim/vim/pull/18278

Commit Summary

• 3244390 Improve doc for cmdline-ranges in cmdline.txt

File Changes

(2 files)

• M runtime/doc/cmdline.txt (111)
• M runtime/doc/tags (16)

Patch Links:

• https://github.com/vim/vim/pull/18278.patch
• https://github.com/vim/vim/pull/18278.diff

—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.Message ID: <vim/vim/pull/18278@github.com>

[zeertzjq]

@zeertzjq commented on this pull request.

---

In runtime/doc/cmdline.txt:

> +	'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

Why do the documentation of different marks have to be repeated here?

—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.Message ID: <vim/vim/pull/18278/review/3213952681@github.com>

[Peter Kenny]

@kennypete commented on this pull request.

Explained, above, in detail. They are not "repeated" in the context of being line specifiers - there is no comprehensive list anywhere of them. It's useful to know what they are in the line specifier context, not just a 'jump to mark' context, where mark-motions has them spread over many "pages", and in that context it is the specific position, rather than line, that's relevant.

—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.Message ID: <vim/vim/pull/18278/review/3214048774@github.com>

[Christian Brabandt]

chrisbra left a comment (vim/vim#18278)

thanks, this is a nice summary.

—
Reply to this email directly, view it on GitHub.

You are receiving this because you are subscribed to this thread.Message ID: <vim/vim/pull/18278/c3293384554@github.com>

[Christian Brabandt]

chrisbra left a comment (vim/vim#18278)

I have made a few changes:

• I added a link to usr_10.txt.
• I did not understand the When the following legacy Vim script is sourced, it prints the line number and " + print": > so I kept the original. (and it was a bit verbose).

—
Reply to this email directly, view it on GitHub.

You are receiving this because you are subscribed to this thread.Message ID: <vim/vim/pull/18278/c3293448073@github.com>

[Christian Brabandt]

Closed #18278 via d4c2cb4.

—
Reply to this email directly, view it on GitHub.

You are receiving this because you are subscribed to this thread.Message ID: <vim/vim/pull/18278/issue_event/19708321663@github.com>

[Christian Brabandt]

chrisbra left a comment (vim/vim#18278)

that is a good goal. I appreciate making the examples self-contained and being able to source those directly from the help file.

It depends on how many changes this will contain. Reviewing 1000s of lines is exhausting, so I'd appreciate if you can group into smaller commits, each fixing some logical sections in the help file. Then you can also split up your description directly into the commit message and as such it does not get lost when I decide to merge each individual commit (instead of squashing all into a single commit).

—
Reply to this email directly, view it on GitHub.

You are receiving this because you are subscribed to this thread.Message ID: <vim/vim/pull/18278/c3300019901@github.com>

[Shane-XB-Qian]

Shane-XB-Qian left a comment (vim/vim#18278)

> It depends on how many changes this will contain. Reviewing 1000s of lines is exhausting, so I'd appreciate if you can group into smaller commits, each fixing some logical sections in the help file. Then you can also split up your description directly into the commit message and as such it does not get lost when I decide to merge each individual commit (instead of squashing all into a single commit).

BTW: *if* some commits was going to modify one same fs, i think better squash to signal commit;
// tho to my point, squash all commits to one maybe more better.
// @chrisbra may have his own style, but i *wish* we can follow such simple 'rule', to make chk commit easy.

--
shane.xb.qian

—
Reply to this email directly, view it on GitHub.

You are receiving this because you are subscribed to this thread.Message ID: <vim/vim/pull/18278/c3301662245@github.com>