Peter Kenny

unread,

Aug 22, 2026, 11:16:43 PMAug 22

to vim/vim, Subscribed

vim9.txt: Conclusion to the rewrite and enhancements - part 2 of 2 (summary)

This is a very significant update. Initially it considered only Section 2, the last to be enhanced with sourceable Vim9 script examples. Along the way it extended to also include several standardisation changes, plus improvements to some passages of sections 4 and 6 especially. “Part 1” of the rewrite addressed those things in Sections 1, and 3 to 7 (NB: they are listed in the explanation to PR20706).

The description, which follows, is a SUMMARY only.
For more details and the rationale of changes, refer to this Gist: vim9.txt rewrite Section 2 (details).

Some improvements in this “Part 2” update necessarily involve the help files eval.txt and userfunc.txt, where some tags are better relocated either to/from vim9.txt.

Locations of changes are indicated by reference to *tag* in the updated file.

1. Corrections to the current help

:&: currently, the help states this, “cannot be used to repeat a :substitute command”. That is incorrect. Only bare & is unusable; :& remains valid.
Comparing null with 0/false in legacy script: Currently, the help states this “would return true”. That is incorrect because 1 is not literally true, and legacy Vim script returns 1.
Predefined-value type table: The current help states, “the other null_ values have the type indicated by their name”. That is a little misleading. For example, null_partial is v:t_func, not v:t_partial.
For-loop item-deletion “trick”: The current help implies this legacy technique does not apply in Vim9 script, which is not wholly the case because it works identically in a non-compiled scope, only behaving differently when compiled.

2. Error codes

Many are relocated, and almost all are accompanied by sourceable scripts now.

Nearly every error code, below, previously had no sourceable/working example or sat in a location disconnected from what actually triggers it. Most now have a dedicated, sourceable script demonstrating what gives the error.
- New or first-time examples: E1004, E1014, E1017, E1020, E1021, E1025, E1026, E1034, E1050, E1054, E1055, E1068, E1069, E1074, E1075, E1079, E1080, E1082, E1084, E1087, E1091, E1097, E1099, E1100, E1103, E1106, E1124, E1127, E1128, E1130, E1131, E1133, E1134, E1139, E1144, E1147, E1148, E1149, E1150, E1157, E1160, E1163, E1167, E1168, E1171, E1172, E1176, E1178, E1180, E1181, E1182, E1190, E1191, E1202, E1205, E1213, E1254, E1307, E1360 (example only added; the tag remains in `vim9class.txt), E1395, E1581.
- Relocated for logical grouping (i.e., the tag is moved to sit with its actual trigger, rather than a disconnected general list): E1147/E1148 (moved from eval.txt to vim9.txt), E1037 (eval.txt, hot-linked to the new *vim9-comparators*), E1094, E1053, E1071, E1257, E1261, and the E1047–E1262 import/namespace block (12 errors, itemised individually via the companion “Part 1” PR).

3. Other improvements

New tags are added for concepts which previously had none: *vim9-invalid-Ex-commands*, *vim9-no-shorten*, *vim9-functions*, *vim9-any-type*, *vim9-block*, *vim9-no-shadowing*, *vim9-omitting-:call*, *vim9-omitting-:eval*, *vim9-noclear*, and more.
Legacy Vim versus Vim9 script comparisons are added in places where Vim9 script-only or abstract snippets do/would not clearly demonstrate the script version behavioural differences.
The “Predefined values” passage is restructured as a table (type()/typename()/string() per value) rather than prose.
The “Comparators” passage expands string-only coverage to complete treatment of primitive types, jobs/channels, containers, Funcrefs, class objects, and enum values (including enum singleton-mutation behaviour), none of which is documented currently.

4. Open questions

E1146 (“Command not recognised”): This may be unreachable following resolution of Issues 8454, 8563, and 9270. It has been left as-is, though is worth a maintainer’s view regarding whether either it is now redundant or remains an intentional catch-all.
userfunc.txt: The recommendation to prefix autoloaded function calls with g:filename#funcname() appears worthy of revision, though is out of this PR’s scope to change.
null_class/null_enumvalue: The former always errors when used as a value with no apparent legitimate use. Conversely, there is no null_enumvalue, despite it seeming as though it could have real utility. It may be worth a design discussion.
E1213 placement: Currently this is in Section 2’s shadowing passage. Arguably, this could sit with the Import errors in Section 6.
The legacy is/== non-transitivity (v:true == 8 and 8 == 8.0 both work, but v:true == 8.0 errors). This has been documented as an aside because it is outside this PR’s scope to resolve (and given it is in legacy Vim script, probably is not worth messing with, though may be worth considering).

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

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

Commit Summary

eaf5dbb vim9.txt: rewrite Section 2

File Changes

(4 files)

Patch Links:

—
Reply to this email directly, view it on GitHub, or unsubscribe.
Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS and Android. Download it today!
You are receiving this because you are subscribed to this thread.

Mao-Yining

unread,

Aug 23, 2026, 9:03:54 AMAug 23

to vim/vim, Subscribed

mao-yining left a comment (vim/vim#21132)

Vimtags check failed. Could you run helptags ++t for doc/?

—
Reply to this email directly, view it on GitHub, or unsubscribe.
Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS and Android. Download it today!

You are receiving this because you are subscribed to this thread.

Peter Kenny

unread,

Aug 23, 2026, 2:37:04 PMAug 23

to vim/vim, Subscribed

kennypete left a comment (vim/vim#21132)

Vimtags check failed. Could you run helptags ++t for doc/?

An identical tags file is produced with that (i.e., to what is in the PR). I even ran it from two Vim instances to see whether it was different. It isn't; all three (pushed, produced with GitBash w/ 9.0.2112 and produced with Win11 gVim 9.2.0993 are verbatim).

—
Reply to this email directly, view it on GitHub, or unsubscribe.
Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS and Android. Download it today!

You are receiving this because you are subscribed to this thread.

Christian Brabandt

unread,

Aug 23, 2026, 3:05:41 PMAug 23

to vim/vim, Subscribed

chrisbra left a comment (vim/vim#21132)

Vimtags check failed. Could you run helptags ++t for doc/?

An identical tags file is produced with that (i.e., to what is in the PR). I even ran it from two Vim instances to see whether it was different. It isn't; all three (pushed, produced with GitBash w/ 9.0.2112 and produced with Win11 gVim 9.2.0993 are verbatim).

It fails, on this sentence:

null_tuple (because |tuples| are immutable, neither adding to nor
extending them is permitted), and

—
Reply to this email directly, view it on GitHub, or unsubscribe.
Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS and Android. Download it today!

You are receiving this because you are subscribed to this thread.

Peter Kenny

unread,

Sep 15, 2026, 3:01:45 PM (11 days ago) Sep 15

to vim/vim, Subscribed

kennypete left a comment (vim/vim#21132)

great re-work. That must have been a lot of work. Thanks

Thanks, it sure was. Would have been many, many weeks FT in the end with so many revisions, discoveries (as you know, including tangents fixing things like the shortened commands), etc. Nearly there now....

—
Reply to this email directly, view it on GitHub, or unsubscribe.
Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS and Android. Download it today!

You are receiving this because you are subscribed to this thread.

dkearns

unread,

Sep 19, 2026, 12:38:49 PM (7 days ago) Sep 19

to vim/vim, Subscribed

dkearns left a comment (vim/vim#21132)

Yes, thanks for your tireless efforts Peter, we all know it's a nearly thankless task.

Does this need another set of eyes? I'll have to check it out locally. Every time I load up the diff page for this one it takes my browser down in no time at all.

Did this turn up any new syntax highlighting bugs of note? I noticed the null_dict->func() one but I'll fix that in the legacy/vim9 split PR.

—
Reply to this email directly, view it on GitHub, or unsubscribe.
Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS and Android. Download it today!

You are receiving this because you are subscribed to this thread.

Peter Kenny

unread,

Sep 19, 2026, 4:40:48 PM (6 days ago) Sep 19

to vim/vim, Subscribed

kennypete left a comment (vim/vim#21132)

Yes, thanks for your tireless efforts Peter, we all know it's a nearly thankless task.

Nearly, though you guys would know more than me about that given your huge contributions over time ... thanks

Does this need another set of eyes? I'll have to check it out locally. Every time I load up the diff page for this one it takes my browser down in no time at all.

Yes and no:
I'd say "yes" if it's not too "into the weeds" because I'm sure there will be a few things that surface over time but - bigger picture - if it is 99%+ improvements, which is where it is at now (IMO), that'd be a good stopping point. It can always be tweaked later, right!
(And "no" if it's AI reviewing. There are just so many false positive "issues" when given to CoPilot, et al. ... and from responding to past reviews where CoPilot was engaged, those are frustrating because they burn a lot of time to debunk.)

Did this turn up any new syntax highlighting bugs of note? I noticed the null_dict->func() one but I'll fix that in the legacy/vim9 split PR.

I've not had a good look start-to-end in the last while since your vim.vim syntax changes went in. There were a few things I'd found workarounds for, which could perhaps be considered (but aren't essential). One is double quoted content in Vim9 script comments:
image.png (view on web)
My workaround is using a U+00A0, as highlighted in the first line, above, immediately before the ". It's a bit hacky, but could be considered a "feature" when you do want the double quoted text prominent in a comment.

This comparison is interesting too - LHS is with 9021119; RHS is with 9020500
image.png (view on web)

list2blob is clearly an issue now whereas it was fine before
the null_* lines remain an issue, and
the setbufline and getcharstr lines are good now.

Another is the regression here:
image.png (view on web)

I can do a complete sweep of them side-by-side like this to pick the rest.

—
Reply to this email directly, view it on GitHub, or unsubscribe.
Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS and Android. Download it today!

You are receiving this because you are subscribed to this thread.

Peter Kenny

unread,

Sep 20, 2026, 6:08:25 AM (6 days ago) Sep 20

to vim/vim, Subscribed

kennypete left a comment (vim/vim#21132)

Did this turn up any new syntax highlighting bugs of note? I noticed the null_dict->func() one but I'll fix that in the legacy/vim9 split PR.

Continued comparison of syntax - LHS is with 9021119; RHS is with 9020500.

This is an improvement (and line 297 is likewise):
image.png (view on web)

Ironically perhaps, this is an improvement too:
image.png (view on web)

And another improvement:
Image: image (view on web)

More improvements:
Image: image (view on web)

These have regressed, though, now being recognised as vim9UserFunc (plus feedkeys on line 1100, popup_create on 1552, and filter on 1759 are likewise):
image.png (view on web)

This is another improvement:
Image: image (view on web)

These have changed, though they remain incorrect; they should be vimType?
Image: image (view on web)

The difference here is the presentation of the match pattern:
image.png (view on web)

This is arguably an improvement given it's invalid, so not highlighting is better:
image.png (view on web)

Another debatable one. It looks odd, but perhaps it should. Thing is, though, if there is a blank line before the comment it does present as a comment:
image.png (view on web)
...
image.png (view on web)

This is a regression; these should all still be comments:
image.png (view on web)
Image: image (view on web)

..................
That's about half way through. I'll review the rest later.

—
Reply to this email directly, view it on GitHub, or unsubscribe.
Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS and Android. Download it today!

You are receiving this because you are subscribed to this thread.

Peter Kenny

unread,

Sep 20, 2026, 4:08:06 PM (5 days ago) Sep 20

to vim/vim, Subscribed

kennypete left a comment (vim/vim#21132)

.................. That's about half way through. I'll review the rest later.

Continuation ...

This legacy Vim script presentation is off:
image.png (view on web)

Ditto, but for Vim9 script:
image.png (view on web)

This is improved (notwithstanding the Vim9 script one is invalid syntax; so, a stickler could expect that not to be highlighted given the whitespace-before-separator error):

Image: image (view on web)

Arguably, this is better given the incorrect : bool syntax:
image.png (view on web)

I may have already flagged these - the | # Vim9 script comment after legacy ... was working previously, not now:
image.png (view on web)

There's no change here, though (only if it's easy) highlighting the mandatory argument following the optional argument as an error could be an improvement?
image.png (view on web)

Also unchanged, though type casting could possibly be enhanced sometime?
image.png (view on web)

This is called out earlier, though this screenshot shows why:
image.png (view on web)

I think that's it, though this was eyeballing them only.

Given your massive re-write of vim.vim, IMHO it is a remarkable outcome. There are many improvements and only a small number of degradations. 🙏

—
Reply to this email directly, view it on GitHub, or unsubscribe.
Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS and Android. Download it today!

You are receiving this because you are subscribed to this thread.

Christian Brabandt

unread,

Sep 24, 2026, 1:24:45 PM (2 days ago) Sep 24

to vim/vim, Subscribed

chrisbra left a comment (vim/vim#21132)

thanks. Let me merge this now.

—
Reply to this email directly, view it on GitHub, or unsubscribe.
Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS and Android. Download it today!

You are receiving this because you are subscribed to this thread.

dkearns

unread,

Sep 24, 2026, 1:44:00 PM (2 days ago) Sep 24

to vim/vim, Subscribed

dkearns left a comment (vim/vim#21132)

I've not had a good look start-to-end in the last while since your vim.vim syntax changes went in. There were a few things I'd found workarounds for, which could perhaps be considered (but aren't essential). One is double quoted content in Vim9 script comments: My workaround is using a U+00A0, as highlighted in the first line, above, immediately before the ". It's a bit hacky, but could be considered a "feature" when you do want the double quoted text prominent in a comment.

I recently added g:vimsyn_comment_strings to the Vim syntax file to disable this highlighting. We can use that to disable it in the help examples if you like?

—
Reply to this email directly, view it on GitHub, or unsubscribe.
Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS and Android. Download it today!

You are receiving this because you are subscribed to this thread.

Peter Kenny

unread,

Sep 24, 2026, 2:55:16 PM (2 days ago) Sep 24

to vim/vim, Subscribed

kennypete left a comment (vim/vim#21132)

My workaround is using a U+00A0, as highlighted in the first line, above, immediately before the ". It's a bit hacky, but could be considered a "feature" when you do want the double quoted text prominent in a comment.

I recently added g:vimsyn_comment_strings to the Vim syntax file to disable this highlighting. We can use that to disable it in the help examples if you like?

I don't mind either way. It's easy enough to add the non-breaking space before any "content" you want remaining as vim9Comment rather than vimCommentString. And there are instances where stressed quoted content in the comment is useful. Maybe just leave it as-is.

—
Reply to this email directly, view it on GitHub, or unsubscribe.
Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS and Android. Download it today!

You are receiving this because you are subscribed to this thread.

Reply all

Reply to author

Forward

[vim/vim] vim9.txt: rewrite Section 2 (PR #21132)

Peter Kenny

vim9.txt: Conclusion to the rewrite and enhancements - part 2 of 2 (summary)

1. Corrections to the current help

2. Error codes

3. Other improvements

4. Open questions

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

Commit Summary

File Changes

Patch Links:

Mao-Yining

Peter Kenny

Christian Brabandt

Peter Kenny

dkearns

Peter Kenny

Peter Kenny

Peter Kenny

Christian Brabandt

dkearns

Peter Kenny