Make references to [range] consistent #13971

JJCUBER · 2024-02-03T21:43:24Z

Some parts of the vimdocs refer to ranges with {range} instead of [range]. Since there are more instances of [range] and only information on the [range] variant exists (:h [range] and :h :[range] exist, :h {range} does not), I made all of the references consistent.

The EX commands index is the only instance where it is left as {range} but consequently clarified as normally being denoted with [range], since that section of the helpdocs uses [...] to mean optional. ([range] is not optional for :[range], since it would otherwise be :, which is specified as a separate command.)

I also noticed that this line used the wrong tag for the command (it linked to information about ranges, [range], instead of information about the command :[range]).

Below is context for what I am referring to (with my proposed changes included):

6. EX commands					*ex-cmd-index* *:index*

This is a brief but complete listing of all the ":" commands, without
mentioning any arguments.  The optional part of the command name is inside [].
The commands are sorted on the non-optional part of their name.

tag		command		action ~
------------------------------------------------------------------------------

|:|		:		nothing
-|:range|	:{range}	go to last line in {range}
+|:[range]|	:{range}	go to last line in {range} (normally denoted |[range]|)

Previously, it referred to information about the range itself ( :range -- a subsection of [range] ) instead of information about the actual command ( :[range] ).

zeertzjq · 2024-02-03T22:14:30Z

I don't think this makes sense. {range} means it's mandatory and [range] means it's optional.

JJCUBER · 2024-02-03T22:27:02Z

I don't think this makes sense. {range} means it's mandatory and [range] means it's optional.

The issue, in my opinion, is that

[ranges] are inherently optional (they default to a range over the current line)
Information on ranges themselves are explicitly put under [ranges] in the helpdocs, as opposed to {ranges} or ranges

Additionally, the very helpdocs for [range] say this:

Some Ex commands accept a line range in front of them. This is noted as
[range]. It consists of one or more line specifiers, separated with ',' or
';'.

This makes it sound like it should always be denoted as [range].

I feel like this unification I proposed makes the most sense overall, though other methods of unification (or clarifying notation/adding synonyms to parts of the helpdocs) might work.

zeertzjq · 2024-02-03T22:35:13Z

IMO, if omitting the range leads to completely different behavior, the range isn't really optional. :normal with and without range is an example.

JJCUBER · 2024-02-03T22:46:31Z

It seems to me that the behavior of both with and without the [range] is identical for :normal. The only difference documentation-wise is an extra clarification for how it behaves with ranges; this could easily be combined with the description of :normal (instead, just having :[range]normal). The extra clarification would still be accurate for when the range is over a single line.

This would be consistent with how some commands work which only have a single helpdocs entry for the range variant, while still having the "optional" notation (i.e. :[range]g :[range]> which both don't have a non-range variant, yet use the "optional" notation).

Of course, I did not help create the helpdocs over the years, so maybe this is just some artifact of changes in notation and I am misunderstanding things; however, ~~none~~ almost none of the commands with separate entries say anything about the (explicit) range which would be inconsistent for a single line (implicit range).

Edit

I stand corrected; norm does behave differently. This still means that the helpdocs are inconsistent with use of notation, though.

chrisbra · 2024-02-06T15:25:58Z

not really sure it is worth it. Mostly it seems the {range} is used to denote when a range is not really optional. There are a few cases however, where [range] is okay I think.

JJCUBER · 2024-02-06T16:32:55Z

Would it make sense, as an alternative, to have {range} also jump to the same helpdocs location as [range]? Currently, it doesn't have any entry.

chrisbra · 2024-02-07T16:57:20Z

yes, makes sense.

chrisbra · 2024-02-06T15:16:12Z

runtime/doc/fold.txt

@@ -297,8 +297,8 @@ zf{motion}  or
 							*zF*
 zF		Create a fold for [count] lines.  Works like "zf".

-:{range}fo[ld]						*:fold* *:fo*
-		Create a fold for the lines in {range}.  Works like "zf".
+:[range]fo[ld]						*:fold* *:fo*


I think here [range] is not really optional. Please leave it as before

chrisbra · 2024-02-06T15:16:47Z

runtime/doc/fold.txt

-:{range}foldo[pen][!]
-		Open folds in {range}.  When [!] is added all folds are
-		opened.  Useful to see all the text in {range}.  Without [!]
+:[range]foldo[pen][!]


chrisbra · 2024-02-06T15:16:59Z

runtime/doc/fold.txt

-:{range}foldc[lose][!]
-		Close folds in {range}.  When [!] is added all folds are
-		closed.  Useful to hide all the text in {range}.  Without [!]
+:[range]foldc[lose][!]


chrisbra · 2024-02-06T15:18:14Z

runtime/doc/index.txt

@@ -1161,7 +1161,7 @@ The commands are sorted on the non-optional part of their name.
 tag		command		action ~
 ------------------------------------------------------------------------------
 |:|		:		nothing
-|:range|	:{range}	go to last line in {range}
+|:[range]|	:{range}	go to last line in {range} (normally denoted |[range]|)


same here, [range] is not really optionally

The issue here is :range links to something other than what they were expecting. However, once making {range} point to the same place as [range], this will be easy to resolve.

chrisbra · 2024-02-06T15:19:12Z

runtime/doc/insert.txt

@@ -2043,7 +2043,7 @@ NOTE: These commands cannot be used with |:global| or |:vglobal|.
 			the cursor.
 			See |++opt| for the possible values of [++opt].

-:{range}r[ead] [++opt] [name]
+:[range]r[ead] [++opt] [name]
 			Insert the file [name] (default: current file) below
 			the specified line.


Below the specified {range} ?

chrisbra · 2024-02-06T15:22:14Z

runtime/doc/usr_25.txt

@@ -134,9 +134,9 @@ if your text can't be properly formatted with Vim's builtin command.  See the

 To center a range of lines, use the following command: >

-	:{range}center [width]
+	:[range]center [width]


not really optional from the context above.

chrisbra · 2024-02-06T15:23:45Z

runtime/doc/various.txt

@@ -185,7 +185,7 @@ g8			Print the hex values of the bytes used in the
 := [flags]		Print the last line number.
 			See |ex-flags| for [flags].

-:{range}= [flags]	Prints the last line number in {range}.  For example,
+:[range]= [flags]	Prints the last line number in [range].  For example,


this is specifically how the = command handles the [range]. So not really optional from the context (else it would be the same as line 185 above).

chrisbra · 2024-02-06T15:24:15Z

runtime/doc/various.txt

 			Execute Normal mode commands {commands} for each line
-			in the {range}.  Before executing the {commands}, the
+			in the [range].  Before executing the {commands}, the


not really optional as well.

chrisbra · 2024-02-06T15:24:42Z

src/ex_eval.c

@@ -76,7 +76,7 @@ static int cause_abort = FALSE;

 /*
 * Return TRUE when immediately aborting on error, or when an interrupt
- * occurred or an exception was thrown but not caught.  Use for ":{range}call"
+ * occurred or an exception was thrown but not caught.  Use for ":[range]call"


not really optional from context.

chrisbra · 2024-02-06T15:25:05Z

src/match.c

@@ -437,7 +437,7 @@ next_search_hl(
    int		called_emsg_before = called_emsg;
    int		timed_out = FALSE;

-    // for :{range}s/pat only highlight inside the range
+    // for :[range]s/pat only highlight inside the range


not really optional as well from context.

JJCUBER · 2024-02-15T15:38:22Z

When I get the chance, I will revert the changes specified to stay in accordance to the optional/required syntax. I'll also look through the existing uses of [...] (optional) to make sure they don't need to be converted to required.

chrisbra · 2024-02-15T18:59:05Z

sure thanks.

JJCUBER added 2 commits February 3, 2024 15:58

Make references to [range] consistent

bc370b4

Correct range tag in EX commands index

7d2aa32

Previously, it referred to information about the range itself ( :range -- a subsection of [range] ) instead of information about the actual command ( :[range] ).

chrisbra added the needs more work used for a pull request that isn't ready to include (other than needing a test) label Feb 9, 2024

chrisbra reviewed Feb 14, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Make references to [range] consistent #13971

Make references to [range] consistent #13971

JJCUBER commented Feb 3, 2024

zeertzjq commented Feb 3, 2024

JJCUBER commented Feb 3, 2024 •

edited

zeertzjq commented Feb 3, 2024

JJCUBER commented Feb 3, 2024 •

edited

chrisbra commented Feb 6, 2024

JJCUBER commented Feb 6, 2024 •

edited

chrisbra commented Feb 7, 2024

chrisbra Feb 6, 2024

chrisbra Feb 6, 2024

chrisbra Feb 6, 2024

chrisbra Feb 6, 2024

JJCUBER Feb 15, 2024

chrisbra Feb 6, 2024

chrisbra Feb 6, 2024

chrisbra Feb 6, 2024

chrisbra Feb 6, 2024

chrisbra Feb 6, 2024

chrisbra Feb 6, 2024

JJCUBER commented Feb 15, 2024

chrisbra commented Feb 15, 2024

Make references to [range] consistent #13971

Are you sure you want to change the base?

Make references to [range] consistent #13971

Conversation

JJCUBER commented Feb 3, 2024

zeertzjq commented Feb 3, 2024

JJCUBER commented Feb 3, 2024 • edited

zeertzjq commented Feb 3, 2024

JJCUBER commented Feb 3, 2024 • edited

Edit

chrisbra commented Feb 6, 2024

JJCUBER commented Feb 6, 2024 • edited

chrisbra commented Feb 7, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

JJCUBER commented Feb 15, 2024

chrisbra commented Feb 15, 2024

JJCUBER commented Feb 3, 2024 •

edited

JJCUBER commented Feb 3, 2024 •

edited

JJCUBER commented Feb 6, 2024 •

edited