docs: api, pack, events, develop

runtime/doc/api.txt

@@ -231,21 +231,19 @@ As Nvim evolves the API may change in compliance with this CONTRACT:
 
 - New functions and events may be added.
   - Any such extensions are OPTIONAL: old clients may ignore them.
-- Function signatures will NOT CHANGE (after release), except as follows:
+- New functions MAY CHANGE before release. Clients can dynamically check
-  - Functions introduced in the development (unreleased) version MAY CHANGE.
+  `api_prerelease`, |api-metadata|.
-    (Clients can dynamically check `api_prerelease`, etc. |api-metadata|)
+- Function signatures will NOT CHANGE after release, except as follows:
-  - New items may be ADDED to map/list parameters/results of functions and
+  - Map/list parameters/results may be EXTENDED (new fields may be added).
-    events.
+    - Such new fields are OPTIONAL: old clients MAY ignore them.
-    - Any such new items are OPTIONAL: old clients may ignore them.
+    - Existing fields will not be removed.
-    - Existing items will not be removed (after release).
+  - Return type MAY CHANGE from void to non-void. Old clients MAY ignore the
-  - Return type may change from void to non-void. Old clients MAY ignore the
     new return value.
-  - An `opts` parameter may be added, which is not required in the request.
+  - An optional `opts` parameter may be ADDED.
-    - Unlimited optional parameters may be added following an `opts`
+  - Optional parameters may be ADDED following an `opts` parameter.
-      parameter.
 - Event parameters will not be removed or reordered (after release).
 - Events may be EXTENDED: new parameters may be added.
-- Deprecated functions will not be removed until Nvim version 2.0
+- Deprecated functions will not be removed until Nvim 2.0.
 
 "Private" interfaces are NOT covered by this contract:
 

runtime/doc/autocmd.txt

@@ -73,7 +73,8 @@ Or use `:execute`: >
 Note that special characters (e.g., "%", "<cword>") in the ":autocmd"
 arguments are not expanded when the autocommand is defined.  These will be
 expanded when the Event is recognized, and the {cmd} is executed.  The only
-exception is that "<sfile>" is expanded when the autocmd is defined.  Example:
+exception is that "<sfile>" (unlike "<script>") is expanded when the autocmd
+is defined.  Example:
 >
 	:au BufNewFile,BufRead *.html so <sfile>:h/html.vim
 
@@ -261,7 +262,7 @@ BufLeave			Before leaving to another buffer.  Also when
 				Not used for ":qa" or ":q" when exiting Vim.
 							*BufModifiedSet*
 BufModifiedSet			After the `'modified'` value of a buffer has
-				been changed.
+				been changed. Special-case of |OptionSet|.
 							*BufNew*
 BufNew				After creating a new buffer (except during
 				startup, see |VimEnter|) or renaming an
@@ -497,22 +498,11 @@ CompleteDone			After Insert mode completion is done.  Either
 						  abandoned for other reason.
 
 							*CursorHold*
-CursorHold			When the user doesn't press a key for the time
+CursorHold			When there is no user input for 'updatetime'
-				specified with 'updatetime'.  Not triggered
+				duration, in Normal-mode. Not triggered while
-				until the user has pressed a key (i.e. doesn't
+				waiting for a command argument or movement
-				fire every 'updatetime' ms if you leave Vim to
+				after an operator, nor while |recording|
-				make some coffee. :)  See |CursorHold-example|
+				a macro. See |CursorHold-example|.
-				for previewing tags.
-				This event is only triggered in Normal mode.
-				It is not triggered when waiting for a command
-				argument to be typed, or a movement after an
-				operator.
-				While recording the CursorHold event is not
-				triggered. |q|
-							*<CursorHold>*
-				Internally the autocommand is triggered by the
-				<CursorHold> key. In an expression mapping
-				|getchar()| may see this character.
 
 				Note: Interactive commands cannot be used for
 				this event.  There is no hit-enter prompt,
@@ -837,6 +827,10 @@ OptionSet			After setting an option (except during
 				always use |:noautocmd| to prevent triggering
 				OptionSet.
 
+				Note: Not triggered by the 'modified' option;
+				the |BufModifiedSet| event may be used to
+				handle that.
+
 				Non-recursive: |:set| in the autocommand does
 				not trigger OptionSet again.
 

runtime/doc/channel.txt

@@ -177,85 +177,85 @@ Put this in `uppercase.vim` and run:  >bash
 ==============================================================================
 5. Using a prompt buffer				*prompt-buffer*
 
-If you want to type input for the job in a Vim window you have a few options:
+Prompt buffers provide a "prompt" interface: they are like regular buffers,
-- Use a normal buffer and handle all possible commands yourself.
+except only the last section of the buffer is editable, and the user can
-  This will be complicated, since there are so many possible commands.
+"submit" the prompt by hitting Enter. Useful for implementing:
-- Use a terminal window.  This works well if what you type goes directly to
+
-  the job and the job output is directly displayed in the window.
+- chat UI
-  See |terminal|.
+- REPL or shell plugins
-- Use a window with a prompt buffer. This works well when entering lines for
+- advanced "picker" plugins
-  the job in Vim while displaying (possibly filtered) output from the job.
 
 A prompt buffer is created by setting 'buftype' to "prompt". You would
-normally only do that in a newly created buffer.
+normally only do that in a newly created buffer: >vim
 
-The user can edit and enter text at the very last line of the buffer. Pressing
+    :set buftype=prompt
-Enter in the prompt line invokes the |prompt_setcallback()| callback. Use
-Shift+Enter to add a new line without submitting the prompt, or paste
-multiline text using any |put| or |paste| command. The callback is typically
-expected to process the prompt and show results by appending to the buffer,
-below the prompt (and above the next prompt).
 
-Only the text after the last prompt (starting from the |':| mark), is
+The user can edit and enter text at the end of the buffer. Pressing Enter in
-user-editable. The rest of the buffer is not modifiable with Normal mode
+the prompt section invokes the |prompt_setcallback()| callback, which is
-commands.  It can be modified by functions such as |append()|.  Using other
+typically expected to process the prompt and show results by appending to the
-commands may mess up the buffer.
+buffer. To input multiline text, use Shift+Enter to add a new line without
+submitting the prompt, or just |put| or |paste| multiline text.
 
-After setting 'buftype' to "prompt" Vim does not automatically start Insert
+Only the "prompt" part of the buffer user-editable, given by the |':| mark.
-mode, use `:startinsert` if you want to enter Insert mode, so that the user
+The rest of the buffer is not modifiable with Normal mode commands, though it
-can start typing a line.
+can be modified by functions such as |append()|.  Using other commands may
+mess up the buffer.
 
-The text of the prompt can be set with the |prompt_setprompt()| function. If
+After setting `buftype=prompt`:
-no prompt is set with |prompt_setprompt()|, "% " is used. You can get the
+- Nvim unsets the 'comments' option.
-effective prompt text for a buffer, with |prompt_getprompt()|.
+- Nvim does not automatically start Insert mode (use `:startinsert` if you
+  want to enter Insert mode)
+
+The prompt prefix defaults to "% ", but can be set with |prompt_setprompt()|.
+You can get the effective prompt prefix for with |prompt_getprompt()|.
 
 The user can go to Normal mode and navigate through the buffer.  This can be
 useful to see older output or copy text.
 
-The CTRL-W key can be used to start a window command, such as CTRL-W w to
+By default during prompt insert-mode, the CTRL-W key can be used to start
-switch to the next window.  This also works in Insert mode (use Shift-CTRL-W
+a window command, such as CTRL-W w to switch to the next window. (Use
-to delete a word). When leaving the window Insert mode will be stopped.  When
+Shift-CTRL-W to delete a word). When leaving the window Insert mode will be
-coming back to the prompt window Insert mode will be restored.
+stopped. When coming back to the prompt window Insert mode will be restored.
 
 Any command that starts Insert mode, such as "a", "i", "A" and "I", will move
 the cursor to the last line.  "A" will move to the end of the line, "I" to the
 start of the line.
 
-Here is an example for Unix.  It starts a shell in the background and prompts
+Example: start a shell in the background and prompt for the next shell
-for the next shell command.  Output from the shell is displayed above the
+command, displaying shell output above the prompt: >vim
-prompt. >vim
 
-	" Function handling a line of text that has been typed.
+    " Handles a line of user input.
-	func TextEntered(text)
+    func OnSubmit(text)
-	  " Send the text to a shell with Enter appended.
+      " Send the text to a shell with Enter appended.
-	  call chansend(g:shell_job, [a:text, ''])
+      call chansend(g:shell_job, [a:text, ''])
-	endfunc
+    endfunc
 
-	" Function handling output from the shell: Add it above the prompt.
+    " Handles output from the shell.
-	func GotOutput(channel, msg, name)
+    func OnOutput(channel, msg, name)
-	  call append(line("$") - 1, a:msg)
+      " Add shell output above the prompt.
-	endfunc
+      call append(line('$') - 1, a:msg)
+    endfunc
 
-	" Function handling the shell exits: close the window.
+    " Handles the shell exit.
-	func JobExit(job, status, event)
+    func JobExit(job, status, event)
-	  quit!
+      quit!
-	endfunc
+    endfunc
 
-	" Start a shell in the background.
+    " Start a shell in the background.
-	let shell_job = jobstart(["/bin/sh"], #{
+    let shell_job = jobstart(['/bin/sh'], #{
-		\ on_stdout: function('GotOutput'),
+        \ on_stdout: function('OnOutput'),
-		\ on_stderr: function('GotOutput'),
+        \ on_stderr: function('OnOutput'),
-		\ on_exit: function('JobExit'),
+        \ on_exit: function('JobExit'),
-		\ })
+        \ })
 
-	new
+    new
-	set buftype=prompt
+    set buftype=prompt
-	let buf = bufnr('')
+    let buf = bufnr('')
-	call prompt_setcallback(buf, function("TextEntered"))
+    call prompt_setcallback(buf, function('OnSubmit'))
-	call prompt_setprompt(buf, "shell command: ")
+    call prompt_setprompt(buf, 'shell command: ')
 
-	" start accepting shell commands
+    " Start accepting shell commands.
-	startinsert
+    startinsert
 <
 
- vim:tw=78:ts=8:noet:ft=help:norl:
+ vim:tw=78:ts=8:et:sw=4:ft=help:norl:

runtime/doc/develop.txt

@@ -426,6 +426,9 @@ Use existing common {verb} names (actions) if possible:
     - add:          Appends or inserts into a collection
     - attach:       Listens to something to get events from it (TODO: rename to "on"?)
     - call:         Calls a function
+    - callback      Continuation callback: a single function parameter (not
+                    a field) that returns the result of an async function. Use
+                    "on_…" for all other callbacks and event handlers.
     - cancel:       Cancels or dismisses an event or interaction, typically
                     user-initiated and without error. (Compare "abort", which
                     cancels and signals error/failure.)
@@ -444,6 +447,8 @@ Use existing common {verb} names (actions) if possible:
     - has:          Checks for the presence of an item, feature, etc.
     - inspect:      Presents a high-level, often interactive, view
     - is_enabled:   Checks if functionality is enabled.
+    - on_…:         Handles events or async results, or registers such
+                    a handler. |dev-name-events|
     - open:         Opens something (a buffer, window, …)
     - parse:        Parses something into a structured form
     - set:          Sets a thing (or group of things)
@@ -477,7 +482,6 @@ everywhere, not "buffer" in some places and "buf" in others.
 
 Do NOT use these deprecated nouns:
     - buffer        Use "buf" instead
-    - callback      Use on_foo instead
     - command       Use "cmd" instead
     - window        Use "win" instead
 
@@ -669,6 +673,7 @@ External UIs are expected to implement these common features:
 - Support the text decorations/attributes given by |ui-event-hl_attr_define|.
   The "url" attr should be presented as a clickable hyperlink.
 - Handle the "restart" UI event so that |:restart| works.
+- Detect capslock and show an indicator if capslock is active.
 
 
  vim:tw=78:ts=8:sw=4:et:ft=help:norl:

runtime/doc/gui.txt

@@ -17,6 +17,8 @@ TUI and GUI (assuming the UI supports the given feature). See |TUI| for notes
 specific to the terminal UI. Help tags with the "gui-" prefix refer to UI
 features, whereas help tags with the "ui-" prefix refer to the |ui-protocol|.
 
+                                      Type |gO| to see the table of contents.
+
 ==============================================================================
 Third-party GUIs                                *third-party-guis* *vscode*
 
@@ -34,8 +36,6 @@ a Nvim GUI.
 - VimR (macOS) https://github.com/qvacua/vimr
 - Others https://github.com/neovim/neovim/wiki/Related-projects#gui
 
-                                      Type |gO| to see the table of contents.
-
 ==============================================================================
 Starting the GUI                                *gui-config* *gui-start*
 

runtime/doc/lsp.txt

@@ -859,16 +859,13 @@ buf_request_sync({bufnr}, {method}, {params}, {timeout_ms})
         describing the failure reason, and `result` is nil.
 
 commands                                                    *vim.lsp.commands*
-    Registry (a table) for client-side handlers, for custom server-commands
+    Map of client-defined handlers implementing custom (off-spec) commands
-    that are not in the LSP specification.
+    which a server may invoke. Each key is a unique command name; each value
+    is a function which is called when an LSP action (code action, code
+    lenses, …) requests it by name.
 
-    If an LSP response contains a command which is not found in
+    If an LSP response requests a command not defined client-side, Nvim will
-    `vim.lsp.commands`, the command will be executed via the LSP server using
+    forward it to the server as `workspace/executeCommand`.
-    `workspace/executeCommand`.
-
-    Each key in the table is a unique command name, and each value is a
-    function which is called when an LSP action (code action, code lenses,
-    …) triggers the command.
     • Argument 1 is the `Command`: >
       Command
       title: String
@@ -1381,13 +1378,8 @@ Lua module: vim.lsp.client                                        *lsp-client*
                                    { PORT = 8080; HOST = '0.0.0.0'; }
 <
       • {commands}?            (`table<string,fun(command: lsp.Command, ctx: table)>`)
-                               Client commands. Map of command names to
+                               Map of client-defined commands overriding the
-                               user-defined functions. Commands passed to
+                               global |vim.lsp.commands|.
-                               `start()` take precedence over the global
-                               command registry. Each key must be a unique
-                               command name, and the value is a function which
-                               is called if any LSP action (code action, code
-                               lenses, …) triggers the command.
       • {detached}?            (`boolean`, default: `true`) Daemonize the
                                server process so that it runs in a separate
                                process group from Nvim. Nvim will shutdown the

runtime/doc/lua-guide.txt

@@ -30,16 +30,17 @@ The purpose of this guide is to introduce the different ways of interacting
 with Nvim through Lua (the "API"). This API consists of three different
 layers:
 
-1. The "Vim API" inherited from Vim: |Ex-commands| and |builtin-functions| as
+1. The "Vim API" inherited from Vim: |Ex-commands| and |vimscript-functions|
-well as |user-function|s in Vimscript. These are accessed through |vim.cmd()|
+   as well as |user-function|s in Vimscript. These are accessed through
-and |vim.fn| respectively, which are discussed under |lua-guide-vimscript|
+   |vim.cmd()| and |vim.fn| respectively, which are discussed under
-below.
+   |lua-guide-vimscript| below.
 
 2. The "Nvim API" written in C for use in remote plugins and GUIs; see |api|.
-These functions are accessed through |vim.api|.
+   These functions are accessed through |vim.api|.
 
 3. The "Lua API" written in and specifically for Lua. These are any other
-functions accessible through `vim.*` not mentioned already; see |lua-stdlib|.
+   functions accessible through `vim.*` not mentioned already; see
+   |lua-stdlib|.
 
 This distinction is important, as API functions inherit behavior from their
 original layer: For example, Nvim API functions always need all arguments to
@@ -223,7 +224,7 @@ Vimscript are automatically converted:
 
     vim.fn.jobstart('ls', { on_stdout = print_stdout })
 <
-This works for both |builtin-functions| and |user-function|s.
+This works for both |vimscript-functions| and |user-function|s.
 
 Note that hashes (`#`) are not valid characters for identifiers in Lua, so,
 e.g., |autoload| functions have to be called with this syntax:
@@ -232,9 +233,9 @@ e.g., |autoload| functions have to be called with this syntax:
 <
 ------------------------------------------------------------------------------
 See also:
-• |builtin-functions|: alphabetic list of all Vimscript functions
+• |vimscript-functions|: descriptions of all Vimscript functions
-• |function-list|:     list of all Vimscript functions grouped by topic
+• |function-list|: Vimscript functions grouped by topic
-• |:runtime|:          run all Lua scripts matching a pattern in |'runtimepath'|
+• |:runtime|: run all Lua scripts matching a pattern in |'runtimepath'|
 
 ==============================================================================
 Variables                                                  *lua-guide-variables*

runtime/doc/lua.txt

@@ -3177,12 +3177,12 @@ vim.keymap.set({mode}, {lhs}, {rhs}, {opts})                *vim.keymap.set()*
 
     Examples: >lua
         -- Map "x" to a Lua function:
-        vim.keymap.set('n', 'x', function() print("real lua function") end)
+        vim.keymap.set('n', 'x', function() print('real lua function') end)
         -- Map "<leader>x" to multiple modes for the current buffer:
         vim.keymap.set({'n', 'v'}, '<leader>x', vim.lsp.buf.references, { buffer = true })
         -- Map <Tab> to an expression (|:map-<expr>|):
         vim.keymap.set('i', '<Tab>', function()
-          return vim.fn.pumvisible() == 1 and "<C-n>" or "<Tab>"
+          return vim.fn.pumvisible() == 1 and '<C-n>' or '<Tab>'
         end, { expr = true })
         -- Map "[%%" to a <Plug> mapping:
         vim.keymap.set('n', '[%%', '<Plug>(MatchitNormalMultiBackward)')

runtime/doc/options.txt

@@ -1178,10 +1178,10 @@ A jump table for the options with a short description can be found at |Q_op|.
 	  help		help buffer (do not set this manually)
 	  nofile	buffer is not related to a file, will not be written
 	  nowrite	buffer will not be written
+	  prompt	buffer where only the last section can be edited, for
+			use by plugins. |prompt-buffer|
 	  quickfix	list of errors |:cwindow| or locations |:lwindow|
 	  terminal	|terminal-emulator| buffer
-	  prompt	buffer where only the last line can be edited, meant
-			to be used by a plugin, see |prompt-buffer|
 
 	This option is used together with 'bufhidden' and 'swapfile' to
 	specify special kinds of buffers.   See |special-buffers|.

runtime/doc/repeat.txt

@@ -265,24 +265,24 @@ For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|.
 			about each searched file.
 
 							*:pa* *:packadd* *E919*
-:pa[ckadd][!] {name}	Search for an optional plugin directory in 'packpath'
+:pa[ckadd][!] {name}	|pack-add| Search for an optional plugin directory in
-			and source any plugin files found.  The directory must
+			'packpath', source any plugin files found, and add it
-			match:
+			to 'runtimepath'.  The directory must match: >
-				pack/*/opt/{name} ~
+				pack/*/opt/{name}
-			The directory is added to 'runtimepath' if it wasn't
+<			If the directory pack/*/opt/{name}/after exists it is
-			there yet.
-			If the directory pack/*/opt/{name}/after exists it is
 			added at the end of 'runtimepath'.
 
-			If loading packages from "pack/*/start" was skipped,
+			Note: Use |vim.pack.add()) to install from a URL.
-			then this directory is searched first:
-				pack/*/start/{name} ~
 
+			If loading packages from "pack/*/start" was skipped,
+			then this directory is searched first: >
+				pack/*/start/{name}
+<
 			Note that {name} is the directory name, not the name
-			of the .vim file.  All files matching the patterns
+			of the .vim file.  All files matching the patterns >
-				pack/*/opt/{name}/plugin/**/*.vim ~
+				pack/*/opt/{name}/plugin/**/*.vim
-				pack/*/opt/{name}/plugin/**/*.lua ~
+				pack/*/opt/{name}/plugin/**/*.lua
-			will be sourced.  This allows for using subdirectories
+<			will be sourced.  This allows for using subdirectories
 			below "plugin", just like with plugins in
 			'runtimepath'.
 
@@ -293,17 +293,14 @@ For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|.
 			"pack/*/opt/{name}", this command will also look
 			for "{name}/ftdetect/*.vim" files.
 
-			When the optional ! is added no plugin files or
+			When the optional "!" is given, no plugin/ files or
-			ftdetect scripts are loaded, only the matching
+			ftdetect/ scripts are loaded, only the matching
 			directories are added to 'runtimepath'.  This is
 			useful in your |init.vim|.  The plugins will then be
-			loaded during |initialization|, see |load-plugins| (note
+			loaded during the |load-plugins| |initialization| step
-			that the loading order will be reversed, because each
+			(note that the loading order will be reversed because
-			directory is inserted before others). In this case, the
+			each directory is inserted before others), after
-			ftdetect scripts will be loaded during |initialization|,
+			loading the ftdetect scripts.
-			before the |load-plugins| step.
-
-			Also see |pack-add|.
 
 						*:packl* *:packloadall*
 :packl[oadall][!]	Load all packages in the "start" directory under each

runtime/doc/ui.txt

@@ -4,7 +4,7 @@
 			    NVIM REFERENCE MANUAL
 
 
-Nvim UI protocol					*UI* *ui*
+Nvim UI protocol					*UI* *ui* *api-ui-events*
 
                                       Type |gO| to see the table of contents.
 

runtime/doc/usr_41.txt

@@ -588,7 +588,7 @@ after the substitute() call.
 FUNCTIONS						*function-list*
 
 There are many functions.  We will mention them here, grouped by what they are
-used for.  You can find an alphabetical list here: |builtin-function-details|.
+used for.  You can find an alphabetical list here: |vimscript-functions|.
 Use CTRL-] on the function name to jump to detailed help on it.
 
 String manipulation:					*string-functions*

runtime/doc/vimeval.txt

@@ -1813,7 +1813,7 @@ functions.  Scripts can also define |user-function|s.
 See |function-list| to browse functions by topic.
 
 The alphabetic list of all builtin functions and details are in a separate
-help file: |builtin-functions|.
+help file: |vimscript-functions|.
 
 ==============================================================================
 5. Defining functions					*user-function*

runtime/doc/vimfn.txt

@@ -4,13 +4,13 @@
 		  NVIM REFERENCE MANUAL
 
 
-Vimscript functions	*vimscript-functions* *builtin-functions* *builtin.txt*
+Vimscript functions			*vimscript-functions* *builtin.txt*
 
 For functions grouped by what they are used for see |function-list|.
 
 				      Type |gO| to see the table of contents.
 ==============================================================================
-1. Details					*builtin-function-details*
+1. Details					*vimscript-functions-details*
 
 abs({expr})                                                              *abs()*
 		Return the absolute value of {expr}.  When {expr} evaluates to
@@ -3165,8 +3165,7 @@ getchar([{expr} [, {opts}]])                                         *getchar()*
 			Return zero otherwise.
 		If {expr} is 1, only check if a character is available, it is
 			not consumed.  Return zero if no character available.
-		If you prefer always getting a string use |getcharstr()|, or
+		To always get a string, specify "number" as |FALSE| in {opts}.
-		specify |FALSE| as "number" in {opts}.
 
 		Without {expr} and when {expr} is 0 a whole character or
 		special key is returned.  If it is a single character, the

runtime/lua/vim/_meta/options.lua

@@ -619,10 +619,10 @@ vim.bo.bl = vim.bo.buflisted
 ---   help		help buffer (do not set this manually)
 ---   nofile	buffer is not related to a file, will not be written
 ---   nowrite	buffer will not be written
+---   prompt	buffer where only the last section can be edited, for
+--- 		use by plugins. `prompt-buffer`
 ---   quickfix	list of errors `:cwindow` or locations `:lwindow`
 ---   terminal	`terminal-emulator` buffer
----   prompt	buffer where only the last line can be edited, meant
---- 		to be used by a plugin, see `prompt-buffer`
 ---
 --- This option is used together with 'bufhidden' and 'swapfile' to
 --- specify special kinds of buffers.   See `special-buffers`.

runtime/lua/vim/_meta/vimfn.lua

@@ -2828,8 +2828,7 @@ function vim.fn.getchangelist(buf) end
 ---   Return zero otherwise.
 --- If {expr} is 1, only check if a character is available, it is
 ---   not consumed.  Return zero if no character available.
---- If you prefer always getting a string use |getcharstr()|, or
+--- To always get a string, specify "number" as |FALSE| in {opts}.
---- specify |FALSE| as "number" in {opts}.
 ---
 --- Without {expr} and when {expr} is 0 a whole character or
 --- special key is returned.  If it is a single character, the

runtime/lua/vim/keymap.lua

@@ -21,12 +21,12 @@ local keymap = {}
 ---
 --- ```lua
 --- -- Map "x" to a Lua function:
---- vim.keymap.set('n', 'x', function() print("real lua function") end)
+--- vim.keymap.set('n', 'x', function() print('real lua function') end)
 --- -- Map "<leader>x" to multiple modes for the current buffer:
 --- vim.keymap.set({'n', 'v'}, '<leader>x', vim.lsp.buf.references, { buffer = true })
 --- -- Map <Tab> to an expression (|:map-<expr>|):
 --- vim.keymap.set('i', '<Tab>', function()
----   return vim.fn.pumvisible() == 1 and "<C-n>" or "<Tab>"
+---   return vim.fn.pumvisible() == 1 and '<C-n>' or '<Tab>'
 --- end, { expr = true })
 --- -- Map "[%%" to a <Plug> mapping:
 --- vim.keymap.set('n', '[%%', '<Plug>(MatchitNormalMultiBackward)')

runtime/lua/vim/lsp.lua

@@ -1653,14 +1653,12 @@ function lsp.with(handler, override_config)
   end
 end
 
---- Registry (a table) for client-side handlers, for custom server-commands that are not in the LSP
+--- Map of client-defined handlers implementing custom (off-spec) commands which a server may
---- specification.
+--- invoke. Each key is a unique command name; each value is a function which is called when an LSP
+--- action (code action, code lenses, …) requests it by name.
 ---
---- If an LSP response contains a command which is not found in `vim.lsp.commands`, the command will
+--- If an LSP response requests a command not defined client-side, Nvim will forward it to the
---- be executed via the LSP server using `workspace/executeCommand`.
+--- server as `workspace/executeCommand`.
----
---- Each key in the table is a unique command name, and each value is a function which is called
---- when an LSP action (code action, code lenses, …) triggers the command.
 ---
 --- - Argument 1 is the `Command`:
 ---   ```
@@ -1686,7 +1684,7 @@ end
 --- end
 --- ```
 ---
---- @type table<string,function>
+--- @type table<string,fun(command: lsp.Command, ctx: table)>
 lsp.commands = setmetatable({}, {
   __newindex = function(tbl, key, value)
     assert(type(key) == 'string', 'The key for commands in `vim.lsp.commands` must be a string')

runtime/lua/vim/lsp/client.lua

@@ -63,10 +63,7 @@ local validate = vim.validate
 --- ```
 --- @field cmd_env? table
 ---
---- Client commands. Map of command names to user-defined functions. Commands passed to `start()`
+--- Map of client-defined commands overriding the global |vim.lsp.commands|.
---- take precedence over the global command registry. Each key must be a unique command name, and
---- the value is a function which is called if any LSP action (code action, code lenses, …) triggers
---- the command.
 --- @field commands? table<string,fun(command: lsp.Command, ctx: table)>
 ---
 --- Daemonize the server process so that it runs in a separate process group from Nvim.

src/gen/gen_eval_files.lua

@@ -858,13 +858,13 @@ local CONFIG = {
       '\t\t  NVIM REFERENCE MANUAL',
       '',
       '',
-      'Vimscript functions\t*vimscript-functions* *builtin-functions* *builtin.txt*',
+      'Vimscript functions\t\t\t*vimscript-functions* *builtin.txt*',
       '',
       'For functions grouped by what they are used for see |function-list|.',
       '',
       '\t\t\t\t      Type |gO| to see the table of contents.',
       '==============================================================================',
-      '1. Details					*builtin-function-details*',
+      '1. Details					*vimscript-functions-details*',
       '',
     },
     footer = {

src/gen/gen_help_html.lua

@@ -88,8 +88,9 @@ local new_layout = {
 -- Map of new:old pages, to redirect renamed pages.
 local redirects = {
   ['credits'] = 'backers',
-  ['tui'] = 'term',
   ['terminal'] = 'nvim_terminal_emulator',
+  ['tui'] = 'term',
+  ['api-ui-events'] = 'ui',
 }
 
 -- TODO: These known invalid |links| require an update to the relevant docs.
@@ -1343,7 +1344,10 @@ This document moved to: |%s|
       local redirect_to = ('%s/%s'):format(to_dir, get_helppage(redirect_from))
       local redirect_html, _ =
         gen_one(redirect_from, redirect_text, redirect_to, false, commit or '?', parser_path)
-      assert(redirect_html:find(helpfile_tag))
+      assert(
+        redirect_html:find(vim.pesc(helpfile_tag)),
+        ('not found in redirect html: %s'):format(helpfile_tag)
+      )
       tofile(redirect_to, redirect_html)
 
       print(

src/nvim/CMakeLists.txt

@@ -157,8 +157,7 @@ elseif(CMAKE_SYSTEM_NAME MATCHES "Darwin")
   target_link_libraries(nvim_bin PRIVATE "-framework CoreServices")
 
   # Actually export symbols - symbols may not be visible even though
-  # ENABLE_EXPORTS is set to true. See
+  # ENABLE_EXPORTS is set. https://github.com/neovim/neovim/issues/25295
-  # https://github.com/neovim/neovim/issues/25295
   target_link_options(nvim_bin PRIVATE "-Wl,-export_dynamic")
 elseif(CMAKE_SYSTEM_NAME MATCHES "OpenBSD")
   target_link_libraries(main_lib INTERFACE pthread c++abi)

src/nvim/eval.lua

@@ -3564,8 +3564,7 @@ M.funcs = {
       	Return zero otherwise.
       If {expr} is 1, only check if a character is available, it is
       	not consumed.  Return zero if no character available.
-      If you prefer always getting a string use |getcharstr()|, or
+      To always get a string, specify "number" as |FALSE| in {opts}.
-      specify |FALSE| as "number" in {opts}.
 
       Without {expr} and when {expr} is 0 a whole character or
       special key is returned.  If it is a single character, the

src/nvim/options.lua

@@ -903,10 +903,10 @@ local options = {
           help		help buffer (do not set this manually)
           nofile	buffer is not related to a file, will not be written
           nowrite	buffer will not be written
+          prompt	buffer where only the last section can be edited, for
+        		use by plugins. |prompt-buffer|
           quickfix	list of errors |:cwindow| or locations |:lwindow|
           terminal	|terminal-emulator| buffer
-          prompt	buffer where only the last line can be edited, meant
-        		to be used by a plugin, see |prompt-buffer|
 
         This option is used together with 'bufhidden' and 'swapfile' to
         specify special kinds of buffers.   See |special-buffers|.

test/functional/lua/system_spec.lua

@@ -74,23 +74,12 @@ describe('vim.system', function()
       end)
 
       it('can set environment', function()
-        eq(
+        local function test_env(opt)
-          'TESTVAL',
+          eq('TESTVAL', system({ n.testprg('printenv-test'), 'TEST' }, opt).stdout)
-          system(
+        end
-            { n.testprg('printenv-test'), 'TEST' },
-            { env = { TEST = 'TESTVAL' }, text = true }
-          ).stdout
-        )
-      end)
 
-      it('can set environment with clear_env = true', function()
+        test_env({ env = { TEST = 'TESTVAL' }, text = true })
-        eq(
+        test_env({ clear_env = true, env = { TEST = 'TESTVAL' }, text = true })
-          'TESTVAL',
-          system(
-            { n.testprg('printenv-test'), 'TEST' },
-            { clear_env = true, env = { TEST = 'TESTVAL' }, text = true }
-          ).stdout
-        )
       end)
 
       it('can set environment with clear_env = true and env = nil', function()

test/functional/vimscript/eval_spec.lua

@@ -5,7 +5,7 @@
 --    null_spec.lua
 --    operators_spec.lua
 --
--- Tests for the Vimscript |builtin-functions| library should live in:
+-- Tests for the Vimscript |vimscript-functions| library should live in:
 --    test/functional/vimscript/<funcname>_spec.lua
 --    test/functional/vimscript/functions_spec.lua
 

test/functional/vimscript/functions_spec.lua

@@ -1,4 +1,4 @@
--- Tests for misc Vimscript |builtin-functions|.
+-- Tests for misc Vimscript |vimscript-functions|.
 --
 -- If a function is non-trivial, consider moving its spec to:
 --    test/functional/vimscript/<funcname>_spec.lua