From 58df501913c17cb3a79f41548088d0f0bcf3a305 Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Wed, 18 Jun 2025 13:39:35 +0200
Subject: [PATCH 1/3] docs: api, pack, events, develop

---
 runtime/doc/api.txt                          |  22 ++--
 runtime/doc/autocmd.txt                      |  30 ++---
 runtime/doc/channel.txt                      | 118 +++++++++----------
 runtime/doc/develop.txt                      |   7 +-
 runtime/doc/gui.txt                          |   4 +-
 runtime/doc/lsp.txt                          |  24 ++--
 runtime/doc/lua-guide.txt                    |  21 ++--
 runtime/doc/lua.txt                          |   4 +-
 runtime/doc/options.txt                      |   4 +-
 runtime/doc/repeat.txt                       |  43 ++++---
 runtime/doc/ui.txt                           |   2 +-
 runtime/doc/usr_41.txt                       |   2 +-
 runtime/doc/vimeval.txt                      |   2 +-
 runtime/doc/vimfn.txt                        |   7 +-
 runtime/lua/vim/_meta/options.lua            |   4 +-
 runtime/lua/vim/_meta/vimfn.lua              |   3 +-
 runtime/lua/vim/keymap.lua                   |   4 +-
 runtime/lua/vim/lsp.lua                      |  14 +--
 runtime/lua/vim/lsp/client.lua               |   5 +-
 src/gen/gen_eval_files.lua                   |   4 +-
 src/gen/gen_help_html.lua                    |   8 +-
 src/nvim/CMakeLists.txt                      |   3 +-
 src/nvim/eval.lua                            |   3 +-
 src/nvim/options.lua                         |   4 +-
 test/functional/lua/system_spec.lua          |  21 +---
 test/functional/vimscript/eval_spec.lua      |   2 +-
 test/functional/vimscript/functions_spec.lua |   2 +-
 27 files changed, 169 insertions(+), 198 deletions(-)

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 6e734c1645..470722a959 100644
--- a/runtime/doc/api.txt
+++ b/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:
-  - Functions introduced in the development (unreleased) version MAY CHANGE.
-    (Clients can dynamically check `api_prerelease`, etc. |api-metadata|)
-  - New items may be ADDED to map/list parameters/results of functions and
-    events.
-    - Any such new items are OPTIONAL: old clients may ignore them.
-    - Existing items will not be removed (after release).
-  - Return type may change from void to non-void. Old clients MAY ignore the
+- New functions MAY CHANGE before release. Clients can dynamically check
+  `api_prerelease`, |api-metadata|.
+- Function signatures will NOT CHANGE after release, except as follows:
+  - Map/list parameters/results may be EXTENDED (new fields may be added).
+    - Such new fields are OPTIONAL: old clients MAY ignore them.
+    - Existing fields will not be removed.
+  - 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.
-    - Unlimited optional parameters may be added following an `opts`
-      parameter.
+  - An optional `opts` parameter may be ADDED.
+  - Optional parameters may be ADDED following an `opts` 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:
 
diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt
index 9091199daf..5482dabc40 100644
--- a/runtime/doc/autocmd.txt
+++ b/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
-				specified with 'updatetime'.  Not triggered
-				until the user has pressed a key (i.e. doesn't
-				fire every 'updatetime' ms if you leave Vim to
-				make some coffee. :)  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.
+CursorHold			When there is no user input for 'updatetime'
+				duration, in Normal-mode. Not triggered while
+				waiting for a command argument or movement
+				after an operator, nor while |recording|
+				a macro. See |CursorHold-example|.
 
 				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.
 
diff --git a/runtime/doc/channel.txt b/runtime/doc/channel.txt
index 20d2aba625..b2fd4d034a 100644
--- a/runtime/doc/channel.txt
+++ b/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:
-- Use a normal buffer and handle all possible commands yourself.
-  This will be complicated, since there are so many possible commands.
-- 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.
-  See |terminal|.
-- Use a window with a prompt buffer. This works well when entering lines for
-  the job in Vim while displaying (possibly filtered) output from the job.
+Prompt buffers provide a "prompt" interface: they are like regular buffers,
+except only the last section of the buffer is editable, and the user can
+"submit" the prompt by hitting Enter. Useful for implementing:
+
+- chat UI
+- REPL or shell plugins
+- advanced "picker" plugins
 
 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
-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).
+    :set buftype=prompt
 
-Only the text after the last prompt (starting from the |':| mark), is
-user-editable. The rest of the buffer is not modifiable with Normal mode
-commands.  It can be modified by functions such as |append()|.  Using other
-commands may mess up the buffer.
+The user can edit and enter text at the end of the buffer. Pressing Enter in
+the prompt section invokes the |prompt_setcallback()| callback, which is
+typically expected to process the prompt and show results by appending to the
+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
-mode, use `:startinsert` if you want to enter Insert mode, so that the user
-can start typing a line.
+Only the "prompt" part of the buffer user-editable, given by the |':| mark.
+The rest of the buffer is not modifiable with Normal mode commands, though it
+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
-no prompt is set with |prompt_setprompt()|, "% " is used. You can get the
-effective prompt text for a buffer, with |prompt_getprompt()|.
+After setting `buftype=prompt`:
+- Nvim unsets the 'comments' option.
+- 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
-switch to the next window.  This also works in Insert mode (use Shift-CTRL-W
-to delete a word). When leaving the window Insert mode will be stopped.  When
-coming back to the prompt window Insert mode will be restored.
+By default during prompt insert-mode, the CTRL-W key can be used to start
+a window command, such as CTRL-W w to switch to the next window. (Use
+Shift-CTRL-W to delete a word). When leaving the window Insert mode will be
+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
-for the next shell command.  Output from the shell is displayed above the
-prompt. >vim
+Example: start a shell in the background and prompt for the next shell
+command, displaying shell output above the prompt: >vim
 
-	" Function handling a line of text that has been typed.
-	func TextEntered(text)
-	  " Send the text to a shell with Enter appended.
-	  call chansend(g:shell_job, [a:text, ''])
-	endfunc
+    " Handles a line of user input.
+    func OnSubmit(text)
+      " Send the text to a shell with Enter appended.
+      call chansend(g:shell_job, [a:text, ''])
+    endfunc
 
-	" Function handling output from the shell: Add it above the prompt.
-	func GotOutput(channel, msg, name)
-	  call append(line("$") - 1, a:msg)
-	endfunc
+    " Handles output from the shell.
+    func OnOutput(channel, msg, name)
+      " Add shell output above the prompt.
+      call append(line('$') - 1, a:msg)
+    endfunc
 
-	" Function handling the shell exits: close the window.
-	func JobExit(job, status, event)
-	  quit!
-	endfunc
+    " Handles the shell exit.
+    func JobExit(job, status, event)
+      quit!
+    endfunc
 
-	" Start a shell in the background.
-	let shell_job = jobstart(["/bin/sh"], #{
-		\ on_stdout: function('GotOutput'),
-		\ on_stderr: function('GotOutput'),
-		\ on_exit: function('JobExit'),
-		\ })
+    " Start a shell in the background.
+    let shell_job = jobstart(['/bin/sh'], #{
+        \ on_stdout: function('OnOutput'),
+        \ on_stderr: function('OnOutput'),
+        \ on_exit: function('JobExit'),
+        \ })
 
-	new
-	set buftype=prompt
-	let buf = bufnr('')
-	call prompt_setcallback(buf, function("TextEntered"))
-	call prompt_setprompt(buf, "shell command: ")
+    new
+    set buftype=prompt
+    let buf = bufnr('')
+    call prompt_setcallback(buf, function('OnSubmit'))
+    call prompt_setprompt(buf, 'shell command: ')
 
-	" start accepting shell commands
-	startinsert
+    " Start accepting shell commands.
+    startinsert
 <
 
- vim:tw=78:ts=8:noet:ft=help:norl:
+ vim:tw=78:ts=8:et:sw=4:ft=help:norl:
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index 74cec354ea..358c615261 100644
--- a/runtime/doc/develop.txt
+++ b/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:
diff --git a/runtime/doc/gui.txt b/runtime/doc/gui.txt
index a4117e1f05..56d1d54e74 100644
--- a/runtime/doc/gui.txt
+++ b/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*
 
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 713d4ee9e5..a9ba6b988f 100644
--- a/runtime/doc/lsp.txt
+++ b/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
-    that are not in the LSP specification.
+    Map of client-defined handlers implementing custom (off-spec) commands
+    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
-    `vim.lsp.commands`, the command will be executed via the LSP server using
-    `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.
+    If an LSP response requests a command not defined client-side, Nvim will
+    forward it to the server as `workspace/executeCommand`.
     • 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
-                               user-defined functions. Commands passed to
-                               `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.
+                               Map of client-defined commands overriding the
+                               global |vim.lsp.commands|.
       • {detached}?            (`boolean`, default: `true`) Daemonize the
                                server process so that it runs in a separate
                                process group from Nvim. Nvim will shutdown the
diff --git a/runtime/doc/lua-guide.txt b/runtime/doc/lua-guide.txt
index fadaabcb13..9ad66f2e3f 100644
--- a/runtime/doc/lua-guide.txt
+++ b/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
-well as |user-function|s in Vimscript. These are accessed through |vim.cmd()|
-and |vim.fn| respectively, which are discussed under |lua-guide-vimscript|
-below.
+1. The "Vim API" inherited from Vim: |Ex-commands| and |vimscript-functions|
+   as well as |user-function|s in Vimscript. These are accessed through
+   |vim.cmd()| and |vim.fn| respectively, which are discussed under
+   |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
-• |function-list|:     list of all Vimscript functions grouped by topic
-• |:runtime|:          run all Lua scripts matching a pattern in |'runtimepath'|
+• |vimscript-functions|: descriptions of all Vimscript functions
+• |function-list|: Vimscript functions grouped by topic
+• |:runtime|: run all Lua scripts matching a pattern in |'runtimepath'|
 
 ==============================================================================
 Variables                                                  *lua-guide-variables*
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index f82718f1b3..a148b20c4a 100644
--- a/runtime/doc/lua.txt
+++ b/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)')
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index 1871b33e99..cf737ca2e8 100644
--- a/runtime/doc/options.txt
+++ b/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|.
diff --git a/runtime/doc/repeat.txt b/runtime/doc/repeat.txt
index cdb07e3a0e..859b2d0fc5 100644
--- a/runtime/doc/repeat.txt
+++ b/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'
-			and source any plugin files found.  The directory must
-			match:
-				pack/*/opt/{name} ~
-			The directory is added to 'runtimepath' if it wasn't
-			there yet.
-			If the directory pack/*/opt/{name}/after exists it is
+:pa[ckadd][!] {name}	|pack-add| Search for an optional plugin directory in
+			'packpath', source any plugin files found, and add it
+			to 'runtimepath'.  The directory must match: >
+				pack/*/opt/{name}
+<			If the directory pack/*/opt/{name}/after exists it is
 			added at the end of 'runtimepath'.
 
-			If loading packages from "pack/*/start" was skipped,
-			then this directory is searched first:
-				pack/*/start/{name} ~
+			Note: Use |vim.pack.add()) to install from a URL.
 
+			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
-				pack/*/opt/{name}/plugin/**/*.vim ~
-				pack/*/opt/{name}/plugin/**/*.lua ~
-			will be sourced.  This allows for using subdirectories
+			of the .vim file.  All files matching the patterns >
+				pack/*/opt/{name}/plugin/**/*.vim
+				pack/*/opt/{name}/plugin/**/*.lua
+<			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
-			ftdetect scripts are loaded, only the matching
+			When the optional "!" is given, no plugin/ files or
+			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
-			that the loading order will be reversed, because each
-			directory is inserted before others). In this case, the
-			ftdetect scripts will be loaded during |initialization|,
-			before the |load-plugins| step.
-
-			Also see |pack-add|.
+			loaded during the |load-plugins| |initialization| step
+			(note that the loading order will be reversed because
+			each directory is inserted before others), after
+			loading the ftdetect scripts.
 
 						*:packl* *:packloadall*
 :packl[oadall][!]	Load all packages in the "start" directory under each
diff --git a/runtime/doc/ui.txt b/runtime/doc/ui.txt
index 6f3a60902c..576c5b6842 100644
--- a/runtime/doc/ui.txt
+++ b/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.
 
diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt
index 45d996effb..1924198662 100644
--- a/runtime/doc/usr_41.txt
+++ b/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*
diff --git a/runtime/doc/vimeval.txt b/runtime/doc/vimeval.txt
index 706ed89c1a..b75590d7da 100644
--- a/runtime/doc/vimeval.txt
+++ b/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*
diff --git a/runtime/doc/vimfn.txt b/runtime/doc/vimfn.txt
index 62d3a08bec..a6b628619b 100644
--- a/runtime/doc/vimfn.txt
+++ b/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
-		specify |FALSE| as "number" in {opts}.
+		To always get a string, specify "number" as |FALSE| in {opts}.
 
 		Without {expr} and when {expr} is 0 a whole character or
 		special key is returned.  If it is a single character, the
diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua
index d5db159855..94779b139d 100644
--- a/runtime/lua/vim/_meta/options.lua
+++ b/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`.
diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index a563611693..2fd2aa82fe 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/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
---- specify |FALSE| as "number" in {opts}.
+--- To always get a string, specify "number" as |FALSE| in {opts}.
 ---
 --- Without {expr} and when {expr} is 0 a whole character or
 --- special key is returned.  If it is a single character, the
diff --git a/runtime/lua/vim/keymap.lua b/runtime/lua/vim/keymap.lua
index 4c19435ef8..2afb628267 100644
--- a/runtime/lua/vim/keymap.lua
+++ b/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)')
diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua
index 0135cda2f6..beaa8f8e8e 100644
--- a/runtime/lua/vim/lsp.lua
+++ b/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
---- specification.
+--- Map of client-defined handlers implementing custom (off-spec) commands 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 `vim.lsp.commands`, the command will
---- be executed via the LSP server using `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.
+--- If an LSP response requests a command not defined client-side, Nvim will forward it to the
+--- server as `workspace/executeCommand`.
 ---
 --- - 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')
diff --git a/runtime/lua/vim/lsp/client.lua b/runtime/lua/vim/lsp/client.lua
index fe271ff801..df3d688606 100644
--- a/runtime/lua/vim/lsp/client.lua
+++ b/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()`
---- 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.
+--- Map of client-defined commands overriding the global |vim.lsp.commands|.
 --- @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.
diff --git a/src/gen/gen_eval_files.lua b/src/gen/gen_eval_files.lua
index 334e32e445..0752ce0e4d 100755
--- a/src/gen/gen_eval_files.lua
+++ b/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 = {
diff --git a/src/gen/gen_help_html.lua b/src/gen/gen_help_html.lua
index 8eb18237c2..5475d219ed 100644
--- a/src/gen/gen_help_html.lua
+++ b/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(
diff --git a/src/nvim/CMakeLists.txt b/src/nvim/CMakeLists.txt
index f198f94cf5..1b7341560d 100644
--- a/src/nvim/CMakeLists.txt
+++ b/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
-  # https://github.com/neovim/neovim/issues/25295
+  # ENABLE_EXPORTS is set. 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)
diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua
index 755c08fa30..10dcc98cf9 100644
--- a/src/nvim/eval.lua
+++ b/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
-      specify |FALSE| as "number" in {opts}.
+      To always get a string, specify "number" as |FALSE| in {opts}.
 
       Without {expr} and when {expr} is 0 a whole character or
       special key is returned.  If it is a single character, the
diff --git a/src/nvim/options.lua b/src/nvim/options.lua
index 0816a2578f..0991b00bc9 100644
--- a/src/nvim/options.lua
+++ b/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|.
diff --git a/test/functional/lua/system_spec.lua b/test/functional/lua/system_spec.lua
index 7016ffbc59..3d1c70efb7 100644
--- a/test/functional/lua/system_spec.lua
+++ b/test/functional/lua/system_spec.lua
@@ -74,23 +74,12 @@ describe('vim.system', function()
       end)
 
       it('can set environment', function()
-        eq(
-          'TESTVAL',
-          system(
-            { n.testprg('printenv-test'), 'TEST' },
-            { env = { TEST = 'TESTVAL' }, text = true }
-          ).stdout
-        )
-      end)
+        local function test_env(opt)
+          eq('TESTVAL', system({ n.testprg('printenv-test'), 'TEST' }, opt).stdout)
+        end
 
-      it('can set environment with clear_env = true', function()
-        eq(
-          'TESTVAL',
-          system(
-            { n.testprg('printenv-test'), 'TEST' },
-            { clear_env = true, env = { TEST = 'TESTVAL' }, text = true }
-          ).stdout
-        )
+        test_env({ env = { TEST = 'TESTVAL' }, text = true })
+        test_env({ clear_env = true, env = { TEST = 'TESTVAL' }, text = true })
       end)
 
       it('can set environment with clear_env = true and env = nil', function()
diff --git a/test/functional/vimscript/eval_spec.lua b/test/functional/vimscript/eval_spec.lua
index bdea40b4e4..49cb5cfee5 100644
--- a/test/functional/vimscript/eval_spec.lua
+++ b/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
 
diff --git a/test/functional/vimscript/functions_spec.lua b/test/functional/vimscript/functions_spec.lua
index 7d9e80a32b..c9e412ae93 100644
--- a/test/functional/vimscript/functions_spec.lua
+++ b/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

From e78c877688123c092b1be9f11d2e8c85b70d63e8 Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Tue, 24 Jun 2025 22:11:24 +0200
Subject: [PATCH 2/3] docs: rename ui.txt => api-ui-events.txt

---
 runtime/doc/{ui.txt => api-ui-events.txt} | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)
 rename runtime/doc/{ui.txt => api-ui-events.txt} (99%)

diff --git a/runtime/doc/ui.txt b/runtime/doc/api-ui-events.txt
similarity index 99%
rename from runtime/doc/ui.txt
rename to runtime/doc/api-ui-events.txt
index 576c5b6842..c221521af8 100644
--- a/runtime/doc/ui.txt
+++ b/runtime/doc/api-ui-events.txt
@@ -1,4 +1,4 @@
-*ui.txt*	Nvim
+*api-ui-events.txt*	Nvim
 
 
 			    NVIM REFERENCE MANUAL
@@ -6,6 +6,9 @@
 
 Nvim UI protocol					*UI* *ui* *api-ui-events*
 
+This document describes the UI protocol. See |gui| and |tui| for user-facing
+UI components and features.
+
                                       Type |gO| to see the table of contents.
 
 ==============================================================================

From c3e2926f17e38e89eef570666b59aa9ffdeaf0f0 Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Fri, 27 Jun 2025 21:55:33 +0200
Subject: [PATCH 3/3] docs: deprecate :ownsyntax

---
 runtime/doc/cmdline.txt    |  1 -
 runtime/doc/deprecated.txt |  2 +-
 runtime/doc/index.txt      |  1 -
 runtime/doc/syntax.txt     | 35 ++---------------------------------
 src/nvim/syntax.c          |  1 +
 5 files changed, 4 insertions(+), 36 deletions(-)

diff --git a/runtime/doc/cmdline.txt b/runtime/doc/cmdline.txt
index d0c7aa475f..e2cc1eef59 100644
--- a/runtime/doc/cmdline.txt
+++ b/runtime/doc/cmdline.txt
@@ -568,7 +568,6 @@ that see the '"' as part of their argument:
     :menu (and the like)
     :mkspell
     :normal
-    :ownsyntax
     :popup
     :registers
     :return
diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt
index a2676171c1..99300750c3 100644
--- a/runtime/doc/deprecated.txt
+++ b/runtime/doc/deprecated.txt
@@ -26,7 +26,7 @@ DIAGNOSTICS
 
 HIGHLIGHTS
 
-• todo
+• *:ownsyntax* *w:current_syntax*	Use 'winhighlight' instead.
 
 LSP
 
diff --git a/runtime/doc/index.txt b/runtime/doc/index.txt
index dc847c0b5b..b74479fe5c 100644
--- a/runtime/doc/index.txt
+++ b/runtime/doc/index.txt
@@ -1473,7 +1473,6 @@ tag		command		action ~
 |:options|	:opt[ions]	open the options-window
 |:ounmap|	:ou[nmap]	like ":unmap" but for Operator-pending mode
 |:ounmenu|	:ounme[nu]	remove menu for Operator-pending mode
-|:ownsyntax|	:ow[nsyntax]	set new local syntax highlight for this window
 |:packadd|	:pa[ckadd]	add a plugin from 'packpath'
 |:packloadall|	:packl[oadall]	load all packages under 'packpath'
 |:pbuffer|	:pb[uffer]	edit buffer in the preview window
diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt
index d4fbf4564c..c3731a47ee 100644
--- a/runtime/doc/syntax.txt
+++ b/runtime/doc/syntax.txt
@@ -5505,38 +5505,7 @@ And put these lines in your vimrc: >
    autocmd BufRead,BufNewFile *.[ch] endif
 
 ==============================================================================
-17. Window-local syntax				*:ownsyntax*
-
-Normally all windows on a buffer share the same syntax settings. It is
-possible, however, to set a particular window on a file to have its own
-private syntax setting. A possible example would be to edit LaTeX source
-with conventional highlighting in one window, while seeing the same source
-highlighted differently (so as to hide control sequences and indicate bold,
-italic etc regions) in another. The 'scrollbind' option is useful here.
-
-To set the current window to have the syntax "foo", separately from all other
-windows on the buffer: >
-   :ownsyntax foo
-<						*w:current_syntax*
-This will set the "w:current_syntax" variable to "foo".  The value of
-"b:current_syntax" does not change.  This is implemented by saving and
-restoring "b:current_syntax", since the syntax files do set
-"b:current_syntax".  The value set by the syntax file is assigned to
-"w:current_syntax".
-Note: This resets the 'spell', 'spellcapcheck', 'spellfile' and 'spelloptions'
-options.
-
-Once a window has its own syntax, syntax commands executed from other windows
-on the same buffer (including :syntax clear) have no effect. Conversely,
-syntax commands executed from that window do not affect other windows on the
-same buffer.
-
-A window with its own syntax reverts to normal behavior when another buffer
-is loaded into that window or the file is reloaded.
-When splitting the window, the new window will use the original syntax.
-
-==============================================================================
-18. Color xterms				*xterm-color* *color-xterm*
+17. Color xterms				*xterm-color* *color-xterm*
 
 							*colortest.vim*
 To test your color setup, a file has been included in the Vim distribution.
@@ -5546,7 +5515,7 @@ To use it, execute this command: >
 Nvim uses 256-color and |true-color| terminal capabilities wherever possible.
 
 ==============================================================================
-19. When syntax is slow						*:syntime*
+18. When syntax is slow						*:syntime*
 
 This is aimed at authors of a syntax file.
 
diff --git a/src/nvim/syntax.c b/src/nvim/syntax.c
index 6a41c2ad05..f4bf220898 100644
--- a/src/nvim/syntax.c
+++ b/src/nvim/syntax.c
@@ -5252,6 +5252,7 @@ void ex_syntax(exarg_T *eap)
   }
 }
 
+/// @deprecated
 void ex_ownsyntax(exarg_T *eap)
 {
   if (curwin->w_s == &curwin->w_buffer->b_s) {