docs #24061

- nvim requires rpc responses in reverse order. https://github.com/neovim/neovim/issues/19932
- NVIM_APPNAME: UIs normally should NOT set this.

ref #23520
fix #24050
fix #23660
fix #23353
fix #23337
fix #22213
fix #19161
fix #18088
fix #20693

17 files changed, 106 insertions, 100 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 1727b571ca..9adca7620f 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -17,8 +17,15 @@ Applications can also embed libnvim to work with the C API directly.
 API Usage                                               *api-rpc* *RPC* *rpc*
 
                                                         *msgpack-rpc*
-RPC is the typical way to control Nvim programmatically.  Nvim implements the
-MessagePack-RPC protocol:
+RPC is the main way to control Nvim programmatically.  Nvim implements the
+MessagePack-RPC protocol with these extra (out-of-spec) constraints:
+
+1. Responses must be given in reverse order of requests (like "unwinding
+   a stack").
+2. Nvim processes all messages (requests and notifications) in the order they
+   are received.
+
+MessagePack-RPC specification:
   https://github.com/msgpack-rpc/msgpack-rpc/blob/master/spec.md
   https://github.com/msgpack/msgpack/blob/0b8f5ac/spec.md
 
diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index d170240ef7..f1c4782d1b 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -8842,10 +8842,13 @@ termopen({cmd} [, {opts}])			*termopen()*
 		to the current (unmodified) buffer. Parameters and behavior
 		are the same as |jobstart()| except "pty", "width", "height",
 		and "TERM" are ignored: "height" and "width" are taken from
-		the current window.
-		Returns the same values as |jobstart()|.
+		the current window. Note that termopen() implies a "pty" arg
+		to jobstart(), and thus has the implications documented at
+		|jobstart()|.
 
-		Terminal environment is initialized as in ||jobstart-env|,
+		Returns the same values as jobstart().
+
+		Terminal environment is initialized as in |jobstart-env|,
 		except $TERM is set to "xterm-256color". Full behavior is
 		described in |terminal|.
 
diff --git a/runtime/doc/channel.txt b/runtime/doc/channel.txt
index 1c52b2d692..afc4ef3787 100644
--- a/runtime/doc/channel.txt
+++ b/runtime/doc/channel.txt
@@ -151,7 +151,7 @@ from the host TTY, or if Nvim is |--headless| it uses default values: >vim
 When channels are opened with the `rpc` option set to true, the channel can be
 used for remote method calls in both directions, see |msgpack-rpc|. Note that
 rpc channels are implicitly trusted and the process at the other end can
-invoke any |api| function!
+invoke any |API| function!
 
 ==============================================================================
 4. Standard IO channel					    *channel-stdio*
diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt
index 29a0470ded..6fb11f0987 100644
--- a/runtime/doc/deprecated.txt
+++ b/runtime/doc/deprecated.txt
@@ -117,6 +117,13 @@ internally and are no longer exposed as part of the API. Instead, use
 - *vim.lsp.diagnostic.set_virtual_text()*
 
 LSP FUNCTIONS
+- *vim.lsp.buf.server_ready()*
+  Use |LspAttach| instead, depending on your use-case. "Server ready" is not
+  part of the LSP spec, so the Nvim LSP client cannot meaningfully implement
+  it. "Ready" is ambiguous because:
+  - Language servers may finish analyzing the workspace, but edits can always
+    re-trigger analysis/builds.
+  - Language servers can serve some requests even while processing changes.
 - *vim.lsp.buf.range_code_action()*		Use |vim.lsp.buf.code_action()| with
 						the `range` parameter.
 - *vim.lsp.util.diagnostics_to_items()*		Use |vim.diagnostic.toqflist()| instead.
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index 891b068051..be4068d8c8 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -478,6 +478,8 @@ External UIs are expected to implement these common features:
 - Consider the "option_set" |ui-global| event as a hint for other GUI
   behaviors. Various UI-related options ('guifont', 'ambiwidth', …) are
   published in this event. See also "mouse_on", "mouse_off".
+- UIs generally should NOT set |$NVIM_APPNAME| (unless explicitly requested by
+  the user).
 
 
  vim:tw=78:ts=8:sw=4:et:ft=help:norl:
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 4f2c457107..ca4570e392 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -207,10 +207,10 @@ specification. These LSP requests/notifications are defined by default:
 
                                                                  *lsp-handler*
 
-lsp-handlers are functions with special signatures that are designed to handle
-responses and notifications from LSP servers.
+LSP handlers are functions with signatures designed to handle LSP responses
+and notifications.
 
-For |lsp-request|, each |lsp-handler| has this signature: >
+For |lsp-response|, each |lsp-handler| has this signature: >
 
   function(err, result, ctx, config)
 <
@@ -363,42 +363,37 @@ To configure the behavior of a builtin |lsp-handler|, the convenient method
 Handlers can be set by:
 
 - Setting a field in vim.lsp.handlers.                      *vim.lsp.handlers*
-    vim.lsp.handlers is a global table that contains the default mapping of
-    |lsp-method| names to |lsp-handlers|.
-
-    To override the handler for the `"textDocument/definition"` method: >lua
+  vim.lsp.handlers is a global table that contains the default mapping of
+  |lsp-method| names to |lsp-handlers|. To override the handler for the
+  `"textDocument/definition"` method: >lua
 
     vim.lsp.handlers["textDocument/definition"] = my_custom_default_definition
 <
-- The {handlers} parameter for |vim.lsp.start_client()|.
-    This will set the |lsp-handler| as the default handler for this server.
-
-    For example: >lua
+- The {handlers} parameter of |vim.lsp.start()|. This sets the default
+  |lsp-handler| for the server being started. Example: >lua
 
-    vim.lsp.start_client {
+    vim.lsp.start {
       ..., -- Other configuration omitted.
       handlers = {
         ["textDocument/definition"] = my_custom_server_definition
       },
     }
 
-- The {handler} parameter for |vim.lsp.buf_request()|.
-    This will set the |lsp-handler| ONLY for the current request.
-
-    For example: >lua
+- The {handler} parameter of |vim.lsp.buf_request_all()|. This sets
+  the |lsp-handler| ONLY for the given request(s). Example: >lua
 
-    vim.lsp.buf_request(
+    vim.lsp.buf_request_all(
       0,
       "textDocument/definition",
-      definition_params,
-      my_request_custom_definition
+      my_request_params,
+      my_handler
     )
 <
 In summary, the |lsp-handler| will be chosen based on the current |lsp-method|
 in the following order:
 
-1. Handler passed to |vim.lsp.buf_request()|, if any.
-2. Handler defined in |vim.lsp.start_client()|, if any.
+1. Handler passed to |vim.lsp.buf_request_all()|, if any.
+2. Handler defined in |vim.lsp.start()|, if any.
 3. Handler defined in |vim.lsp.handlers|, if any.
 
                                                             *vim.lsp.log_levels*
@@ -709,31 +704,27 @@ buf_notify({bufnr}, {method}, {params})                 *vim.lsp.buf_notify()*
         (boolean) success true if any client returns true; false otherwise
 
                                                    *vim.lsp.buf_request_all()*
-buf_request_all({bufnr}, {method}, {params}, {callback})
-    Sends an async request for all active clients attached to the buffer.
-    Executes the callback on the combined result. Parameters are the same as
-    |vim.lsp.buf_request()| but the return result and callback are different.
+buf_request_all({bufnr}, {method}, {params}, {handler})
+    Sends an async request for all active clients attached to the buffer and
+    executes the `handler` callback with the combined result.
 
     Parameters: ~
-      • {bufnr}     (integer) Buffer handle, or 0 for current.
-      • {method}    (string) LSP method name
-      • {params}    (table|nil) Parameters to send to the server
-      • {callback}  (function) The callback to call when all requests are
-                    finished. Unlike `buf_request`, this will collect all the
-                    responses from each server instead of handling them. A map
-                    of client_id:request_result will be provided to the
-                    callback.
+      • {bufnr}    (integer) Buffer handle, or 0 for current.
+      • {method}   (string) LSP method name
+      • {params}   (table|nil) Parameters to send to the server
+      • {handler}  (function) Handler called after all requests are completed.
+                   Server results are passed as a `client_id:result` map.
 
     Return: ~
-        fun() cancel A function that will cancel all requests
+        fun() cancel Function that cancels all requests.
 
                                                   *vim.lsp.buf_request_sync()*
 buf_request_sync({bufnr}, {method}, {params}, {timeout_ms})
     Sends a request to all server and waits for the response of all of them.
 
     Calls |vim.lsp.buf_request_all()| but blocks Nvim while awaiting the
-    result. Parameters are the same as |vim.lsp.buf_request()| but the return
-    result is different. Wait maximum of {timeout_ms} (default 1000) ms.
+    result. Parameters are the same as |vim.lsp.buf_request_all()| but the
+    result is different. Waits a maximum of {timeout_ms} (default 1000) ms.
 
     Parameters: ~
       • {bufnr}       (integer) Buffer handle, or 0 for current.
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index a4890898a3..1110fb7fc3 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1002,10 +1002,18 @@ Log levels are one of the values defined in `vim.log.levels`:
 ------------------------------------------------------------------------------
 LUA-VIMSCRIPT BRIDGE                                           *lua-vimscript*
 
-Nvim Lua provides an interface to Vimscript variables and functions, and
-editor commands and options.
+Nvim Lua provides an interface or "bridge" to Vimscript variables and
+functions, and editor commands and options.
+
+Objects passed over this bridge are COPIED (marshalled): there are no
+"references". |lua-guide-variables| For example, using `vim.fn.remove()` on
+a Lua list copies the list object to Vimscript and does NOT modify the Lua
+list: >lua
+
+    local list = { 1, 2, 3 }
+    vim.fn.remove(list, 0)
+    vim.print(list)  --> "{ 1, 2, 3 }"
 
-See also https://github.com/nanotee/nvim-lua-guide.
 
 vim.call({func}, {...})                                           *vim.call()*
     Invokes |vim-function| or |user-function| {func} with arguments {...}.
diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt
index 25ab91b89e..ffd7b6bc1d 100644
--- a/runtime/doc/map.txt
+++ b/runtime/doc/map.txt
@@ -1546,6 +1546,7 @@ supports incremental command preview:
 	-- If invoked as a preview callback, performs 'inccommand' preview by
 	-- highlighting trailing whitespace in the current buffer.
 	local function trim_space_preview(opts, preview_ns, preview_buf)
+	  vim.cmd('hi clear Whitespace')
 	  local line1 = opts.line1
 	  local line2 = opts.line2
 	  local buf = vim.api.nvim_get_current_buf()
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index 0f53288608..78d38095a8 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -2088,17 +2088,13 @@ A jump table for the options with a short description can be found at |Q_op|.
 	    :set dir=c:\\tmp,\ dir\\,with\\,commas,\\\ dir\ with\ spaces
 <	- For backwards compatibility with Vim version 3.0 a '>' at the start
 	  of the option is removed.
-	Using "." first in the list is recommended.  This means that editing
-	the same file twice will result in a warning.  Using "/tmp" on Unix is
-	discouraged: When the system crashes you lose the swap file.
-	"/var/tmp" is often not cleared when rebooting, thus is a better
-	choice than "/tmp".  But others on the computer may be able to see the
-	files, and it can contain a lot of files, your swap files get lost in
-	the crowd.  That is why a "tmp" directory in your home directory is
-	tried first.
-	The use of |:set+=| and |:set-=| is preferred when adding or removing
-	directories from the list.  This avoids problems when a future version
-	uses another default.
+
+	Editing the same file twice will result in a warning.  Using "/tmp" on
+	is discouraged: if the system crashes you lose the swap file. And
+	others on the computer may be able to see the files.
+	Use |:set+=| and |:set-=| when adding or removing directories from the
+	list, this avoids problems if the Nvim default is changed.
+
 	This option cannot be set from a |modeline| or in the |sandbox|, for
 	security reasons.
 
diff --git a/runtime/doc/pattern.txt b/runtime/doc/pattern.txt
index 625e1f95e1..8437496011 100644
--- a/runtime/doc/pattern.txt
+++ b/runtime/doc/pattern.txt
@@ -1298,7 +1298,6 @@ will probably never match.
 When "\Z" appears anywhere in the pattern, all composing characters are
 ignored.  Thus only the base characters need to match, the composing
 characters may be different and the number of composing characters may differ.
-Only relevant when 'encoding' is "utf-8".
 Exception: If the pattern starts with one or more composing characters, these
 must match.
 							*/\%C*
diff --git a/runtime/doc/russian.txt b/runtime/doc/russian.txt
index 8d3ed360c8..89be1a3c5a 100644
--- a/runtime/doc/russian.txt
+++ b/runtime/doc/russian.txt
@@ -34,7 +34,6 @@ enter Normal mode command, you can also set 'langmap' option:
     :set langmap=ФИСВУАПРШОЛДЬТЩЗЙКЫЕГМЦЧНЯ;ABCDEFGHIJKLMNOPQRSTUVWXYZ,
     фисвуапршолдьтщзйкыегмцчня;abcdefghijklmnopqrstuvwxyz
 
-This is in utf-8, you cannot read this if your 'encoding' is not utf-8.
 You have to type this command in one line, it is wrapped for the sake of
 readability.
 
diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt
index 2c7b7ed61b..51cbf4c93d 100644
--- a/runtime/doc/starting.txt
+++ b/runtime/doc/starting.txt
@@ -1384,20 +1384,23 @@ STATE DIRECTORY (DEFAULT) ~
     Unix:         ~/.local/state              ~/.local/state/nvim
     Windows:      ~/AppData/Local             ~/AppData/Local/nvim-data
 
-Note: Throughout the user manual these defaults are used as placeholders, e.g.
+Note: Throughout the help pages these defaults are used as placeholders, e.g.
 "~/.config" is understood to mean "$XDG_CONFIG_HOME or ~/.config".
 
 NVIM_APPNAME					*$NVIM_APPNAME*
-The XDG directories used by Nvim can be further configured by setting the
-`$NVIM_APPNAME` environment variable. This variable controls the directory
-Neovim will look for (and auto-create) in the various XDG parent directories.
-For example, setting `$NVIM_APPNAME` to "neovim" before running Neovim will
-result in Neovim looking for configuration files in `$XDG_CONFIG_HOME/neovim`
-instead of `$XDG_CONFIG_HOME/nvim`.
-
-Note: Similarly to the $XDG environment variables, when
-`$XDG_CONFIG_HOME/nvim` is mentioned, it should be understood as
-`$XDG_CONFIG_HOME/$NVIM_APPNAME`.
+The standard directories can be further configured by the `$NVIM_APPNAME`
+environment variable. This variable controls the sub-directory that Nvim will
+read from (and auto-create) in each of the base directories. For example,
+setting `$NVIM_APPNAME` to "foo" before starting will cause Nvim to look for
+configuration files in `$XDG_CONFIG_HOME/foo` instead of
+`$XDG_CONFIG_HOME/nvim`.
+
+One use-case for $NVIM_APPNAME is to "isolate" Nvim applications.
+Alternatively, for true isolation, on Linux you can use cgroups namespaces: >
+    systemd-run --user -qt -p PrivateUsers=yes -p BindPaths=/home/user/profile_xy:/home/user/.config/nvim nvim
+
+Note: Throughout the help pages, wherever `$XDG_CONFIG_…/nvim` is mentioned it
+is understood to mean `$XDG_CONFIG_…/$NVIM_APPNAME`.
 
 LOG FILE					*log* *$NVIM_LOG_FILE* *E5430*
 Besides 'debug' and 'verbose', Nvim keeps a general log file for internal
diff --git a/runtime/doc/usr_11.txt b/runtime/doc/usr_11.txt
index 361fe51caa..1fa7fb6f77 100644
--- a/runtime/doc/usr_11.txt
+++ b/runtime/doc/usr_11.txt
@@ -82,9 +82,8 @@ You must be in the right directory, otherwise Vim can't find the swap file.
 ==============================================================================
 *11.2*	Where is the swap file?
 
-Vim can store the swap file in several places.  Normally it is in the same
-directory as the original file.  To find it, change to the directory of the
-file, and use: >
+Vim can store the swap file in several places.  To find it, change to the
+directory of the file, and use: >
 
 	vim -r
 
diff --git a/runtime/doc/usr_45.txt b/runtime/doc/usr_45.txt
index 95a2bc8f79..85710b15d5 100644
--- a/runtime/doc/usr_45.txt
+++ b/runtime/doc/usr_45.txt
@@ -190,8 +190,7 @@ font.  Example: >
 
    xterm -u8 -fn -misc-fixed-medium-r-normal--18-120-100-100-c-90-iso10646-1
 
-Now you can run Vim inside this terminal.  Set 'encoding' to "utf-8" as
-before.  That's all.
+Now you can run Vim inside this terminal.
 
 
 USING UNICODE IN AN ORDINARY TERMINAL
diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt
index 7b0e724e31..4e2ee14537 100644
--- a/runtime/doc/various.txt
+++ b/runtime/doc/various.txt
@@ -88,13 +88,10 @@ g8			Print the hex values of the bytes used in the
 
 							*8g8*
 8g8			Find an illegal UTF-8 byte sequence at or after the
-			cursor.  This works in two situations:
-			1. when 'encoding' is any 8-bit encoding
-			2. when 'encoding' is "utf-8" and 'fileencoding' is
-			   any 8-bit encoding
-			Thus it can be used when editing a file that was
-			supposed to be UTF-8 but was read as if it is an 8-bit
-			encoding because it contains illegal bytes.
+			cursor.
+			Can be used when editing a file that was supposed to
+			be UTF-8 but was read as if it is an 8-bit encoding
+			because it contains illegal bytes.
 			Does not wrap around the end of the file.
 			Note that when the cursor is on an illegal byte or the
 			cursor is halfway through a multibyte character the
diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua
index 9118e7e2e1..761a8406f2 100644
--- a/runtime/lua/vim/lsp.lua
+++ b/runtime/lua/vim/lsp.lua
@@ -1491,7 +1491,7 @@ function lsp.start_client(config)
   ---successful, then it will return {request_id} as the
   ---second result. You can use this with `client.cancel_request(request_id)`
   ---to cancel the-request.
-  ---@see |vim.lsp.buf_request()|
+  ---@see |vim.lsp.buf_request_all()|
   function client.request(method, params, handler, bufnr)
     if not handler then
       handler = assert(
@@ -2119,22 +2119,19 @@ function lsp.buf_request(bufnr, method, params, handler)
   return client_request_ids, _cancel_all_requests
 end
 
----Sends an async request for all active clients attached to the buffer.
----Executes the callback on the combined result.
----Parameters are the same as |vim.lsp.buf_request()| but the return result and callback are
----different.
+--- Sends an async request for all active clients attached to the buffer and executes the `handler`
+--- callback with the combined result.
 ---
 ---@param bufnr (integer) Buffer handle, or 0 for current.
 ---@param method (string) LSP method name
 ---@param params (table|nil) Parameters to send to the server
----@param callback fun(request_results: table<integer, {error: lsp.ResponseError, result: any}>) (function)
---- The callback to call when all requests are finished.
---- Unlike `buf_request`, this will collect all the responses from each server instead of handling them.
---- A map of client_id:request_result will be provided to the callback.
----
----@return fun() cancel A function that will cancel all requests
-function lsp.buf_request_all(bufnr, method, params, callback)
-  local request_results = {}
+---@param handler fun(results: table<integer, {error: lsp.ResponseError, result: any}>) (function)
+--- Handler called after all requests are completed. Server results are passed as
+--- a `client_id:result` map.
+---
+---@return fun() cancel Function that cancels all requests.
+function lsp.buf_request_all(bufnr, method, params, handler)
+  local results = {}
   local result_count = 0
   local expected_result_count = 0
 
@@ -2147,12 +2144,12 @@ function lsp.buf_request_all(bufnr, method, params, callback)
   end)
 
   local function _sync_handler(err, result, ctx)
-    request_results[ctx.client_id] = { error = err, result = result }
+    results[ctx.client_id] = { error = err, result = result }
     result_count = result_count + 1
     set_expected_result_count()
 
     if result_count >= expected_result_count then
-      callback(request_results)
+      handler(results)
     end
   end
 
@@ -2164,8 +2161,8 @@ end
 --- Sends a request to all server and waits for the response of all of them.
 ---
 --- Calls |vim.lsp.buf_request_all()| but blocks Nvim while awaiting the result.
---- Parameters are the same as |vim.lsp.buf_request()| but the return result is
---- different. Wait maximum of {timeout_ms} (default 1000) ms.
+--- Parameters are the same as |vim.lsp.buf_request_all()| but the result is
+--- different. Waits a maximum of {timeout_ms} (default 1000) ms.
 ---
 ---@param bufnr (integer) Buffer handle, or 0 for current.
 ---@param method (string) LSP method name
diff --git a/scripts/gen_help_html.lua b/scripts/gen_help_html.lua
index 7bc48a0662..6cdf028f5c 100644
--- a/scripts/gen_help_html.lua
+++ b/scripts/gen_help_html.lua
@@ -62,7 +62,6 @@ local exclude_invalid = {
   ["'string'"] = "eval.txt",
   Query = 'treesitter.txt',
   ['eq?'] = 'treesitter.txt',
-  ['lsp-request'] = 'lsp.txt',
   matchit = 'vim_diff.txt',
   ['matchit.txt'] = 'help.txt',
   ["set!"] = "treesitter.txt",
@@ -70,7 +69,6 @@ local exclude_invalid = {
   ['v:_null_dict'] = 'builtin.txt',
   ['v:_null_list'] = 'builtin.txt',
   ['v:_null_string'] = 'builtin.txt',
-  ['vim.lsp.buf_request()'] = 'lsp.txt',
   ['vim.lsp.util.get_progress_messages()'] = 'lsp.txt',
 }