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

[Peter Kenny]

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)

• M runtime/doc/eval.txt (278)
• M runtime/doc/tags (22)
• M runtime/doc/userfunc.txt (7)
• M runtime/doc/vim9.txt (4086)

Patch Links:

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

—
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.Message ID: <vim/vim/pull/21132@github.com>

[Mao-Yining]

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.Message ID: <vim/vim/pull/21132/c5386136212@github.com>

[Peter Kenny]

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.Message ID: <vim/vim/pull/21132/c5387768525@github.com>

[Christian Brabandt]

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

I believe this is because |tuples| is not a valid help reference, only |tuple| or |Tuples| 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.Message ID: <vim/vim/pull/21132/c5387914682@github.com>