feat(lua)!: register_keystroke_callback => on_key

Analogous to nodejs's `on('data', …)` interface, here on_key is the "add
listener" interface.

ref 3ccdbc570d85 #12536

BREAKING_CHANGE: vim.register_keystroke_callback() is now an error.

4 files changed, 16 insertions, 37 deletions

diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt
index 3b5287ee44..861aed4884 100644
--- a/runtime/doc/deprecated.txt
+++ b/runtime/doc/deprecated.txt
@@ -14,6 +14,7 @@ updated.
 
 API ~
 *nvim_buf_clear_highlight()*	Use |nvim_buf_clear_namespace()| instead.
+*nvim_buf_set_virtual_text()*	Use |nvim_buf_set_extmark()| instead.
 *nvim_command_output()*		Use |nvim_exec()| instead.
 *nvim_execute_lua()*		Use |nvim_exec_lua()| instead.
 
@@ -54,6 +55,8 @@ Functions ~
 			without stopping the job. Use chanclose(id) to close
 			any socket.
 
+Lua ~
+*vim.register_keystroke_callback()* Use |vim.on_key()| instead.
 
 Modifiers ~
 *cpo-<*
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index 60a3f870a9..06760fae35 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -356,4 +356,11 @@ External UIs are expected to implement these common features:
   published in this event. See also "mouse_on", "mouse_off".
 
 
+NAMING							*dev-naming*
+
+Naming is very important. Consistent naming in the API and UI helps users
+discover and intuitively understand  related "families" of things.  It reduces
+cognitive burden.
+
+
  vim:tw=78:ts=8:noet:ft=help:norl:
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index a44b2e42f5..bf063ca69f 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1243,37 +1243,6 @@ region({bufnr}, {pos1}, {pos2}, {regtype}, {inclusive})         *vim.region()*
                 Return: ~
                     region lua table of the form {linenr = {startcol,endcol}}
 
-                                           *vim.register_keystroke_callback()*
-register_keystroke_callback({fn}, {ns_id})
-                Register a lua {fn} with an {id} to be run after every
-                keystroke.
-
-                If {fn} is nil, it removes the callback for the associated
-                {ns_id}
-                Note:
-                    {fn} will not be cleared from |nvim_buf_clear_namespace()|
-
-                Note:
-                    {fn} will receive the keystrokes after mappings have been
-                    evaluated
-
-                Parameters: ~
-                    {fn}     function: Function to call. It should take one
-                          argument, which is a string. The string will contain
-                          the literal keys typed. See |i_CTRL-V|
-                    {ns_id}  number? Namespace ID. If not passed or 0, will
-                             generate and return a new namespace ID from
-                             |nvim_create_namesapce()|
-
-                Return: ~
-                    number Namespace ID associated with {fn}
-
-                Note:
-                    {fn} will be automatically removed if an error occurs
-                    while calling. This is to prevent the annoying situation
-                    of every keystroke erroring while trying to remove a
-                    broken callback.
-
 schedule_wrap({cb})                                      *vim.schedule_wrap()*
                 Defers callback `cb` until the Nvim API is safe to call.
 
diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt
index d6b54fbd01..87a48e6d2a 100644
--- a/runtime/doc/starting.txt
+++ b/runtime/doc/starting.txt
@@ -329,12 +329,12 @@ argument.
 -w{number}	Set the 'window' option to {number}.
 
 							*-w*
--w {scriptout}	All the characters that you type are recorded in the file
-		"scriptout", until you exit Vim.  This is useful if you want
-		to create a script file to be used with "vim -s" or
-		":source!".  When the "scriptout" file already exists, new
-		characters are appended.  See also |complex-repeat|.
-		{scriptout} cannot start with a digit.
+-w {scriptout}	All keys that you type are recorded in the file "scriptout",
+		until you exit Vim.  Useful to create a script file to be used
+		with "vim -s" or ":source!".  Appends to the "scriptout" file
+		if it already exists. {scriptout} cannot start with a digit.
+		See also |vim.on_key()|.
+		See also |complex-repeat|.
 
 							*-W*
 -W {scriptout}	Like -w, but do not append, overwrite an existing file.