[vim/vim] runtime/doc/vim9.txt Section 1 (PR #18855)

1 view

Skip to first unread message

Peter Kenny

unread,

Dec 2, 2025, 10:32:02 PM (8 hours ago) Dec 2

to vim/vim, Subscribed

vim9.txt - Section 1 - rewrite / enhancements

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

1. What is Vim9 script?

The paragraph starting, “Vim9 script syntax ...”, is updated to include “behavior”. That is because some things operate/behave differently too. So, it is not just a matter of syntax and semantics differing.
[Not changed:]
- The sentence, “When using :function”, is not quite the whole story - e.g., behaviour may differ too. It would be too early (and dilute the point about scriptversion) for an example, though a variant of the example now provided at :vim9[cmd] would demonstrate that it is not just a matter of syntax:
```
vim9script
function Elegacy()
    echo 'é'[0]
endfunction
def Enine(): void
    echo 'é'[0]
enddef
Elegacy()  # Echos byte <c3>
Enine()    # Echos é
```
- The scriptversion point is a bit inconsistent in using the word, “highest”, noting that eval.txt says explicitly:
  
  When using a legacy function, defined with `:function`, in |Vim9| script then scriptversion 4 is used.”
  
  (It is probably of little consequence with, I'm guessing, most of those reading vim9.txt not wanting to use legacy Vim script anyway, and even fewer wanting to use a scriptversion other than the latest.)

*:vim9* *:vim9cmd*

The tag *E1164* is relocated later (with an example).
The paragraph is extended to stress that behaviour is relevant too.

An example and explanation demonstrates the points, i.e., just a few lines show important differences in syntax, semantics, and behaviour.
It could also include this explanation (in the first note):

In the first popup notification, the result is "[769, 101]", being the
second byte of the penultimate character, "é" - itself made up of "e" and a
combining acute accent (U+0301, decimal 769) - and the last character, "e"
(U+0065, decimal 101).  The second popup notification returns "[101]"
because the sixth character in the string is the "e" (i.e., at the end
of the word, "entrée".

That has not been provided. I think that may be too much / dilute the other the points.

*E1164*

This is separated because it is specific to using :vim9[cmd] without any following command.

*:leg* *:legacy*

Tags *E1189* and *E1234* are relocated later because they are caused by very specific things (which deserve distinct, explicit explanations).
The first two sentences have similar adjustments as the one relating to :vim9cmd. The example, which is the Vim9 script equivalent to the example preceding it, is similarly brief.
The Note, “cannot use local variables”, is amended. That is because :legacy can utilise Vim9 script-local variables by prefixing "s:", just like in a legacy Vim script. So, the paragraph replaces the Note, and now focuses on what you can do.

*E1189*

This is explained, along with an example. The current help is silent on what the error is caused by, which is not very helpful.

*E1234*

Like *E1164*, for a standalone vim9cmd, this is explained separately, though should hopefully be sufficiently obvious to not require an example.
[Amusingly, vim9cmd legacy standalone is also an E1189 error, also showing that they can be “stacked”, though it is better not to go there! – vim9cmd legacy vim9cmd legacy vim9cmd echo "hi" anyone?]
“See some examples...”, now is redundant. vim9.txt - aside from Section 2 - now has lots of complete, sourceable examples. (Section 2 is all that is left to update once this PR has been merged.)

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

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

Commit Summary

fdb5865 runtime/doc/vim9.txt Section 1

File Changes

(1 file)

M runtime/doc/vim9.txt (78)

Patch Links:

—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.

Reply all

Reply to author

Forward

0 new messages