docs: lsp, ui events, dev guidance, osc7

fix #34981

runtime/doc/api-ui-events.txt

@@ -882,6 +882,12 @@ must handle.
 	clearing the screen (messages sent by other "msg_" events below should
 	not be affected).
 
+	Guidance: The "clear messages" behavior is UI-specific. If the UI
+	presents messages in a new window, it may choose to clear messages
+	after a few seconds. If the UI presents messages in a persistent area
+	(e.g. cmdline), it should clear messages at the start of the next
+	batch (typically, the next event-loop cycle).
+
 ["msg_showmode", content] ~
 	Shows 'showmode' and |recording| messages. `content` has the same
 	format as in "msg_show". This event is sent with empty `content` to

runtime/doc/api.txt

@@ -1311,6 +1311,9 @@ nvim_replace_termcodes({str}, {from_part}, {do_lt}, {special})
     Replaces terminal codes and |keycodes| (<CR>, <Esc>, ...) in a string with
     the internal representation.
 
+    Note: ~
+      • Lua can use |vim.keycode()| instead.
+
     Attributes: ~
         Since: 0.1.0
 

runtime/doc/develop.txt

@@ -353,7 +353,7 @@ Where possible, these patterns apply to _both_ Lua and the API:
   - Examples: |vim.lsp.codelens.clear()| |vim.diagnostic.enable()|
 - Any function signature that accepts a callback (example: |table.foreach()|)
   should place it as the LAST parameter (after opts), if possible (or ALWAYS
-  for "continuation callbacks"—functions called exactly once).
+  for |continuation|s——functions called exactly once).
   - Improves readability by placing the less "noisy" arguments near the start.
   - Consistent with luv.
   - Useful for future async lib which transforms functions of the form
@@ -426,9 +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
+    - callback      |continuation|: Function parameter (NOT a field) that
-                    a field) that returns the result of an async function. Use
+                    returns the result of an async function. Use the "on_…"
-                    "on_…" for all other callbacks and event handlers.
+                    naming-convention 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.)
@@ -499,6 +499,14 @@ Use this format to name API (RPC) events: >
 Example: >
     nvim_buf_changedtick_event
 <
+                                                        *continuation*
+A "continuation" is implemented as a callback function that returns the result
+of an async function and is called exactly once. Often accepts `err` as the
+first parameter, to avoid erroring on the main thread. Example: >
+    foo(…, callback: fun(err, …))
+Use the name `callback` only for a continuation. All other callbacks and event
+handlers should be named with the |dev-name-events| "on_…" convention.
+
                                                         *dev-api-name*
 Use this format to name new RPC |API| functions: >
     nvim_{topic}_{verb}_{arbitrary-qualifiers}

runtime/doc/editing.txt

@@ -1242,10 +1242,10 @@ MULTIPLE WINDOWS AND BUFFERS				*window-exit*
 							*:confirm* *:conf*
 :conf[irm] {command}	Execute {command}, and use a dialog when an
 			operation has to be confirmed.  Can be used on the
-			|:edit|, |:q|, |:qa| and |:w| commands (the latter to
+			|:edit|, |:restart|, |:q|, |:qa| and |:w| commands
-			override a read-only setting), and any commands that
+			(the latter to override a read-only setting), and any
-			can fail because of unsaved changes, such as |:only|,
+			commands that can fail because of unsaved changes,
-			|:buffer|, |:bdelete|, etc.
+			such as |:only|, |:buffer|, |:bdelete|, etc.
 
 Examples: >
   :confirm w foo

runtime/doc/help.txt

@@ -112,7 +112,6 @@ API (EXTENSIBILITY/SCRIPTING/PLUGINS)
 |channel|		Nvim asynchronous IO
 |vimscript|		Vimscript reference
 |vimscript-functions|	Vimscript functions
-|testing.txt|		Vimscript testing functions
 |remote-plugin|		Nvim remote plugins
 |health|		Health checking
 

runtime/doc/lsp.txt

@@ -28,26 +28,19 @@ Follow these steps to get LSP features:
    upstream installation instructions. You can find language servers here:
    https://microsoft.github.io/language-server-protocol/implementors/servers/
 
-2. Use |vim.lsp.config()| to define a configuration for an LSP client
+2. Define a new config |lsp-new-config| (or install https://github.com/neovim/nvim-lspconfig).
-   (see https://github.com/neovim/nvim-lspconfig for examples).
    Example: >lua
      vim.lsp.config['luals'] = {
        -- Command and arguments to start the server.
        cmd = { 'lua-language-server' },
-
        -- Filetypes to automatically attach to.
        filetypes = { 'lua' },
-
+       -- Sets the "workspace" to the directory where any of these files is found.
-       -- Sets the "root directory" to the parent directory of the file in the
+       -- Files that share a root directory will reuse the LSP server connection.
-       -- current buffer that contains either a ".luarc.json" or a
-       -- ".luarc.jsonc" file. Files that share a root directory will reuse
-       -- the connection to the same LSP server.
        -- Nested lists indicate equal priority, see |vim.lsp.Config|.
        root_markers = { { '.luarc.json', '.luarc.jsonc' }, '.git' },
-
+       -- Specific settings to send to the server. The schema is server-defined.
-       -- Specific settings to send to the server. The schema for this is
+       -- Example: https://raw.githubusercontent.com/LuaLS/vscode-lua/master/setting/schema.json
-       -- defined by the server. For example the schema for lua-language-server
-       -- can be found here https://raw.githubusercontent.com/LuaLS/vscode-lua/master/setting/schema.json
        settings = {
          Lua = {
            runtime = {
@@ -57,7 +50,7 @@ Follow these steps to get LSP features:
        }
      }
 
-3. Use |vim.lsp.enable()| to enable a configuration.
+3. Use |vim.lsp.enable()| to enable the config.
    Example: >lua
      vim.lsp.enable('luals')
 <
@@ -130,21 +123,46 @@ CONFIG                                                  *lsp-config*
 You can configure LSP behavior statically via vim.lsp.config(), and
 dynamically via |lsp-attach| or |Client:on_attach()|.
 
-Use |vim.lsp.config()| to define, and selectively enable, LSP configurations.
+Use |vim.lsp.config()| to define or modify LSP configurations, and
-This is basically a wrapper around |vim.lsp.start()| which allows you to share
+|vim.lsp.enable()| to auto-activate them. This is basically a wrapper around
-and merge configs (which may be provided by Nvim or third-party plugins).
+|vim.lsp.start()| which allows you to share and merge configs (provided by
+Nvim, plugins, and your local config).
 
-When an LSP client starts, it resolves its configuration by merging from the
+                                                        *lsp-new-config*
-following (in increasing priority):
+To create a new config you can either use `vim.lsp.config()` or create
+a `lsp/<config-name>.lua` file.
+
+EXAMPLE: DEFINE A CONFIG AS CODE ~
+
+1. Run `:lua vim.lsp.config('foo', {cmd={'true'}})`
+2. Run `:lua vim.lsp.enable('foo')`
+3. Run `:checkhealth vim.lsp`, check "Enabled Configurations". 😎
+
+EXAMPLE: DEFINE A CONFIG AS A FILE ~
+
+1. Create a file `lsp/foo.lua` somewhere on your 'runtimepath'. >
+   :exe 'edit' stdpath('config') .. '/lsp/foo.lua'
+2. Add this code to the file (or copy an example from
+   https://github.com/neovim/nvim-lspconfig): >
+   return {
+     cmd = { 'true' },
+   }
+3. Save the file (with `++p` to ensure its parent directory is created). >
+   :write ++p
+4. Enable the config. >
+   :lua vim.lsp.enable('foo')
+5. Run `:checkhealth vim.lsp`, check "Enabled Configurations". 🌈
+
+                                                        *lsp-config-merge*
+When an LSP client starts, it resolves its configuration by merging the
+following sources (merge semantics defined by |vim.tbl_deep_extend()|), in
+order of increasing priority:
 
 1. Configuration defined for the `'*'` name.
 2. Configuration from the result of merging all tables returned by
    `lsp/<name>.lua` files in 'runtimepath' for a server of name `name`.
 3. Configurations defined anywhere else.
 
-Note: The merge semantics of configurations follow the behaviour of
-|vim.tbl_deep_extend()|.
-
 Example: given the following configs... >lua
   -- Defined in init.lua
   vim.lsp.config('*', {

runtime/doc/lua.txt

@@ -191,7 +191,7 @@ IMPORTING LUA MODULES                                        *lua-module-load*
 Modules are searched for under the directories specified in 'runtimepath' and
 |packages-runtimepath|, in the order they appear in the output of this command
 >vim
-	:echo nvim_list_runtime_paths()
+    :echo nvim_list_runtime_paths()
 <
 Any "." in the module name is treated as a directory separator when searching.
 For a module `foo.bar`, each directory is searched for `lua/foo/bar.lua`, then
@@ -230,6 +230,11 @@ Note:
   plugins using shell, which will not work with paths containing semicolons,
   it is better to not have them in 'runtimepath' at all.
 
+                                                         *lua-script-location*
+To get its own location, Lua scripts/modules can use |debug.getinfo()|: >
+    debug.getinfo(1, 'S').source:sub(2)
+<
+
 ==============================================================================
 COMMANDS                                                        *lua-commands*
 
@@ -1784,6 +1789,10 @@ SystemObj:write({data})                                    *SystemObj:write()*
 vim.system({cmd}, {opts}, {on_exit})                            *vim.system()*
     Runs a system command or throws an error if {cmd} cannot be run.
 
+    The command runs directly (not in 'shell') so shell builtins such as
+    "echo" in cmd.exe, cmdlets in powershell, or "help" in bash, will not work
+    unless you actually invoke a shell: `vim.system({'bash', '-c', 'help'})`.
+
     Examples: >lua
         local on_exit = function(obj)
           print(obj.code)

runtime/doc/news.txt

@@ -63,10 +63,7 @@ DIAGNOSTICS
 
 EDITOR
 
-• |vim.secure.read()| now removes the choice "(a)llow" from the prompt reply for
+• todo
-  files unlisted in the user's trust database, and thus requires the user to
-  choose (v)iew then run `:trust`. Previously the user would be able to press
-  the single key 'a' to execute the arbitrary execution immediately.
 
 EVENTS
 
@@ -174,6 +171,8 @@ EDITOR
   commands.
 • 'wildchar' now enables completion in search contexts using |/|, |?|, |:g|, |:v|
    and |:vimgrep| commands.
+• For security, 'exrc' no longer shows an "(a)llow" choice. Instead you must
+  "(v)iew" then run `:trust`.
 
 EVENTS
 
@@ -277,7 +276,7 @@ TERMINAL
 
 TREESITTER
 
-• todo
+• |:EditQuery| command gained tab-completion, works with injected languages.
 
 TUI
 

runtime/doc/options.txt

@@ -2566,7 +2566,8 @@ A jump table for the options with a short description can be found at |Q_op|.
 	Unset 'exrc' to stop further searching of 'exrc' files in parent
 	directories, similar to |editorconfig.root|.
 
-	To get its own location, Lua exrc files can use |debug.getinfo()|.
+	To get its own location, a Lua exrc file can use |debug.getinfo()|.
+	See |lua-script-location|.
 
 	Compare 'exrc' to |editorconfig|:
 	- 'exrc' can execute any code; editorconfig only specifies settings.
@@ -2576,7 +2577,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 	1. Enable 'exrc'.
 	2. Place LSP configs at ".nvim/lsp/*.lua" in your project root.
 	3. Create ".nvim.lua" in your project root directory with this line: >lua
-	     vim.cmd[[set runtimepath+=.nvim]]
+	    vim.cmd[[set runtimepath+=.nvim]]
 <
 	This option cannot be set from a |modeline| or in the |sandbox|, for
 	security reasons.

runtime/doc/repeat.txt

@@ -191,7 +191,7 @@ Using Vim scripts					*using-scripts*
 
 For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|.
 
-					*:so* *:source* *load-vim-script*
+					*:so* *:source*
 :so[urce] {file}	Runs |Ex-commands| or Lua code (".lua" files) from
 			{file}.
 			Triggers the |SourcePre| autocommand.

runtime/doc/terminal.txt

@@ -138,35 +138,43 @@ exposes via the |TermRequest| event.
 
 OSC 7: change working directory			*terminal-osc7*
 
-To handle OSC 7 emitted from :terminal processes, this code will :cd to the
+Shells can emit the "OSC 7" sequence to announce when the current directory
-directory indicated in the request. >lua
+(CWD) changed.
+
+You can configure your shell init (e.g. ~/.bashrc) to emit OSC 7, or your
+terminal may attempt to do it for you.
+
+To configure bash to emit OSC 7: >bash
+  function print_osc7() {
+    printf '\033]7;file://%s\033\\' "$PWD"
+  }
+  PROMPT_COMMAND='print_osc7'
+
+Having ensured that your shell emits OSC 7, you can now handle it in Nvim. The
+following code will run :lcd whenever your shell CWD changes in a :terminal
+buffer: >lua
 
   vim.api.nvim_create_autocmd({ 'TermRequest' }, {
     desc = 'Handles OSC 7 dir change requests',
     callback = function(ev)
-      if string.sub(ev.data.sequence, 1, 4) == '\x1b]7;' then
+      local val, n = string.gsub(ev.data.sequence, '\027]7;file://[^/]*', '')
-        local dir = string.gsub(ev.data.sequence, '\x1b]7;file://[^/]*', '')
+      if n > 0 then
+        -- OSC 7: dir-change
+        local dir = val
         if vim.fn.isdirectory(dir) == 0 then
           vim.notify('invalid dir: '..dir)
           return
         end
-        vim.api.nvim_buf_set_var(ev.buf, 'osc7_dir', dir)
+        vim.b[ev.buf].osc7_dir = dir
-        if vim.o.autochdir and vim.api.nvim_get_current_buf() == ev.buf then
+        if vim.api.nvim_get_current_buf() == ev.buf then
-          vim.cmd.cd(dir)
+          vim.cmd.lcd(dir)
         end
       end
     end
   })
-  vim.api.nvim_create_autocmd({ 'BufEnter', 'WinEnter', 'DirChanged' }, {
-    callback = function(ev)
-      if vim.b.osc7_dir and vim.fn.isdirectory(vim.b.osc7_dir) == 1 then
-        vim.cmd.cd(vim.b.osc7_dir)
-      end
-    end
-  })
 
-To try it out, select the above code and source it with `:'<,'>lua` (or
+To try it out, select the above code and source it with `:'<,'>lua`, then run
-`g==`), then run this command in a :terminal buffer: >
+this command in a :terminal buffer: >
 
     printf "\033]7;file://./foo/bar\033\\"
 
@@ -191,7 +199,7 @@ Shells can emit semantic escape sequences (OSC 133) to mark where each prompt
 starts and ends. The start of a prompt is marked by sequence `OSC 133 ; A ST`,
 and the end by `OSC 133 ; B ST`.
 
-You can configure your shell "rc" (e.g. ~/.bashrc) to emit OSC 133 sequences,
+You can configure your shell init (e.g. ~/.bashrc) to emit OSC 133 sequences,
 or your terminal may attempt to do it for you (assuming your shell config
 doesn't interfere).
 

runtime/doc/testing.txt

@@ -1,54 +0,0 @@
-*testing.txt*	Nvim
-
-
-		  VIM REFERENCE MANUAL	  by Bram Moolenaar
-
-
-Testing Vim and Vim script			*testing-support*
-
-Expression evaluation is explained in |eval.txt|.  This file goes into details
-about writing tests in Vim script.  This can be used for testing Vim itself
-and for testing plugins.
-
-1. Testing Vim				|testing|
-2. Test functions			|test-functions-details|
-3. Assert functions			|assert-functions-details|
-
-==============================================================================
-1. Testing Vim						*testing*
-
-Vim can be tested after building it, usually with "make test".
-The tests are located in the directory "src/testdir".
-
-						*new-style-testing*
-New tests should be added as new style tests.  The test scripts are named
-test_<feature>.vim (replace <feature> with the feature under test). These use
-functions such as |assert_equal()| to keep the test commands and the expected
-result in one place.
-
-Find more information in the file src/testdir/README.txt.
-
-==============================================================================
-2. Test functions				*test-functions-details*
-
-See |test_garbagecollect_now()|.
-
-==============================================================================
-3. Assert functions				*assert-functions-details*
-
-See:
-  - |assert_beeps()|
-  - |assert_equal()|
-  - |assert_equalfile()|
-  - |assert_exception()|
-  - |assert_fails()|
-  - |assert_false()|
-  - |assert_inrange()|
-  - |assert_match()|
-  - |assert_nobeep()|
-  - |assert_notequal()|
-  - |assert_notmatch()|
-  - |assert_report()|
-  - |assert_true()|
-
- vim:tw=78:ts=8:noet:ft=help:norl:

runtime/doc/treesitter.txt

@@ -1321,10 +1321,8 @@ add_predicate({name}, {handler}, {opts})
 edit({lang})                                     *vim.treesitter.query.edit()*
     Opens a live editor to query the buffer you started from.
 
-    Can also be shown with `:EditQuery`.                          *:EditQuery*
+    Can also be shown with the *:EditQuery* command. `:EditQuery <tab>`
-
+    completes available parsers.
-    `:EditQuery <tab>` completes the treesitter parser names in the runtime
-    path.
 
     If you move the cursor to a capture name ("@foo"), text matching the
     capture is highlighted in the source buffer. The query editor is a scratch

runtime/doc/usr_41.txt

@@ -31,7 +31,7 @@ script.  There are a lot of them, thus this is a long chapter.
 Table of contents: |usr_toc.txt|
 
 ==============================================================================
-*41.1*	Introduction				*vim-script-intro* *script*
+*41.1*	Introduction				*vimscript-intro*
 
 Your first experience with Vim scripts is the vimrc file.  Vim reads it when
 it starts up and executes the commands.  You can set options to values you

runtime/doc/various.txt

@@ -248,10 +248,15 @@ gx			Opens the current filepath or URL (decided by
 :sh[ell]		Removed. |vim-differences|
 
 						  *:terminal* *:te*
-:te[rminal][!] [{cmd}]	Run {cmd} in a non-interactive 'shell' in a new
+:te[rminal][!] [cmd]	Run [cmd] in a non-interactive 'shell' in a new
-			|terminal-emulator| buffer. Without {cmd}, start an
+			|terminal-emulator| buffer. Without [cmd], start an
 			interactive 'shell'.
 
+			By default the current window is used. To open in
+			a split window, use |:horizontal| or |:vertical|: >
+				:hor te
+				:vert te
+<
 			Type |i| to enter |Terminal-mode|, then keys are sent to
 			the job running in the terminal. Type <C-\><C-N> to
 			leave Terminal-mode. |CTRL-\_CTRL-N|. Type <C-\><C-O>
@@ -260,7 +265,7 @@ gx			Opens the current filepath or URL (decided by
 			Fails if changes have been made to the current buffer,
 			unless 'hidden' is set.
 
-			If {cmd} is omitted, and the 'shell' job exits with no
+			If [cmd] is omitted, and the 'shell' job exits with no
 			error, the buffer is closed automatically
 			|default-autocmds|.
 

runtime/doc/vimeval.txt

@@ -3774,7 +3774,7 @@ This is not allowed when the textlock is active:
 	- etc.
 
 ==============================================================================
-Vim script library					*vim-script-library*
+Vim script library					*vimscript-library*
 
 Vim comes bundled with a Vim script library, that can be used by runtime,
 script authors.  Currently, it only includes very few functions, but it may

runtime/doc/vimfn.txt

@@ -2098,35 +2098,35 @@ expand({string} [, {nosuf} [, {list}]])                               *expand()*
 		done like for the |cmdline-special| variables with their
 		associated modifiers.  Here is a short overview:
 
-			%		current file name
+			%		Current file name
-			#		alternate file name
+			#		Alternate file name
-			#n		alternate file name n
+			#n		Alternate file name n
-			<cfile>		file name under the cursor
+			<cfile>		File name under the cursor
-			<afile>		autocmd file name
+			<afile>		Autocmd file name
-			<abuf>		autocmd buffer number (as a String!)
+			<abuf>		Autocmd buffer number (as a String!)
-			<amatch>	autocmd matched name
+			<amatch>	Autocmd matched name
 			<cexpr>		C expression under the cursor
-			<sfile>		deprecated, use <script> or <stack>
+			<sfile>		Deprecated, use <script> or <stack>
-			<slnum>		sourced script line number or function
+			<slnum>		Sourced script line number or function
 					line number
-			<sflnum>	script file line number, also when in
+			<sflnum>	Script file line number, also when in
 					a function
 			<SID>		"<SNR>123_"  where "123" is the
 					current script ID  |<SID>|
-			<script>	sourced script file, or script file
+			<script>	Sourced script file, or script file
 					where the current function was defined.
-					Use |debug.getinfo()| in Lua scripts.
+					For Lua see |lua-script-location|.
-			<stack>		call stack
+			<stack>		Call stack
-			<cword>		word under the cursor
+			<cword>		Word under the cursor
 			<cWORD>		WORD under the cursor
-			<client>	the {clientid} of the last received
+			<client>	The {clientid} of the last received
 					message
 		Modifiers:
-			:p		expand to full path
+			:p		Expand to full path
-			:h		head (last path component removed)
+			:h		Head (last path component removed)
-			:t		tail (last path component only)
+			:t		Tail (last path component only)
-			:r		root (one extension removed)
+			:r		Root (one extension removed)
-			:e		extension only
+			:e		Extension only
 
 		Example: >vim
 			let &tags = expand("%:p:h") .. "/tags"

runtime/doc/windows.txt

@@ -257,8 +257,8 @@ and 'winminwidth' are relevant.
 
 						*:hor* *:horizontal*
 :hor[izontal] {cmd}
-		Execute {cmd}.  Currently only makes a difference for
+		Execute {cmd} in a horizontal split window. Supports these
-		the following commands:
+		commands:
 		- `:wincmd =`: equalize windows only horizontally.
 		- |:terminal|: open a |terminal| buffer in a split window.
 		- |:checkhealth|: open a healthcheck buffer in a split window.

runtime/lua/vim/_core/server.lua

@@ -1,17 +1,18 @@
 local M = {}
 
---- Called by builtin serverlist(). Returns all running servers.
+--- Called by builtin serverlist(). Returns all running servers in stdpath("run").
---- in stdpath("run"). Does not include named pipes or TCP servers.
+---
+--- - TODO: track TCP servers, somehow.
+--- - TODO: support Windows named pipes.
 ---
 --- @param listed string[] Already listed servers
---- @return string[] A list of currently running servers in stdpath("run")
+--- @return string[] # List of servers found on the current machine in stdpath("run").
 function M.serverlist(listed)
-  -- TODO: also get named pipes on Windows
   local socket_paths = vim.fs.find(function(name, _)
     return name:match('nvim.*')
   end, { path = vim.fn.stdpath('run'), type = 'socket', limit = math.huge })
 
-  local running_sockets = {}
+  local found = {} ---@type string[]
   for _, socket in ipairs(socket_paths) do
     -- Don't list servers twice
     if not vim.list_contains(listed, socket) then
@@ -20,14 +21,14 @@ function M.serverlist(listed)
         -- Check that the server is responding
         -- TODO: do we need a timeout or error handling here?
         if vim.fn.rpcrequest(chan, 'nvim_get_chan_info', 0).id then
-          table.insert(running_sockets, socket)
+          table.insert(found, socket)
         end
         vim.fn.chanclose(chan)
       end
     end
   end
 
-  return running_sockets
+  return found
 end
 
 return M

runtime/lua/vim/_meta/api.lua

@@ -2045,6 +2045,10 @@ function vim.api.nvim_put(lines, type, after, follow) end
 --- Replaces terminal codes and `keycodes` ([<CR>], [<Esc>], ...) in a string with
 --- the internal representation.
 ---
+---
+--- Note:
+--- Lua can use |vim.keycode()| instead.
+---
 --- @see replace_termcodes
 --- @see cpoptions
 --- @param str string String to be converted.

runtime/lua/vim/_meta/options.lua

@@ -2239,7 +2239,8 @@ vim.bo.et = vim.bo.expandtab
 --- Unset 'exrc' to stop further searching of 'exrc' files in parent
 --- directories, similar to `editorconfig.root`.
 ---
---- To get its own location, Lua exrc files can use `debug.getinfo()`.
+--- To get its own location, a Lua exrc file can use `debug.getinfo()`.
+--- See `lua-script-location`.
 ---
 --- Compare 'exrc' to `editorconfig`:
 --- - 'exrc' can execute any code; editorconfig only specifies settings.
@@ -2251,7 +2252,7 @@ vim.bo.et = vim.bo.expandtab
 --- 3. Create ".nvim.lua" in your project root directory with this line:
 ---
 --- ```lua
----      vim.cmd[[set runtimepath+=.nvim]]
+---     vim.cmd[[set runtimepath+=.nvim]]
 --- ```
 ---
 --- This option cannot be set from a `modeline` or in the `sandbox`, for

runtime/lua/vim/_meta/vimfn.lua

@@ -1855,35 +1855,35 @@ function vim.fn.exp(expr) end
 --- done like for the |cmdline-special| variables with their
 --- associated modifiers.  Here is a short overview:
 ---
----   %    current file name
+---   %    Current file name
----   #    alternate file name
+---   #    Alternate file name
----   #n    alternate file name n
+---   #n    Alternate file name n
----   <cfile>    file name under the cursor
+---   <cfile>    File name under the cursor
----   <afile>    autocmd file name
+---   <afile>    Autocmd file name
----   <abuf>    autocmd buffer number (as a String!)
+---   <abuf>    Autocmd buffer number (as a String!)
----   <amatch>  autocmd matched name
+---   <amatch>  Autocmd matched name
 ---   <cexpr>    C expression under the cursor
----   <sfile>    deprecated, use <script> or <stack>
+---   <sfile>    Deprecated, use <script> or <stack>
----   <slnum>    sourced script line number or function
+---   <slnum>    Sourced script line number or function
 ---       line number
----   <sflnum>  script file line number, also when in
+---   <sflnum>  Script file line number, also when in
 ---       a function
 ---   <SID>    "<SNR>123_"  where "123" is the
 ---       current script ID  |<SID>|
----   <script>  sourced script file, or script file
+---   <script>  Sourced script file, or script file
 ---       where the current function was defined.
----       Use |debug.getinfo()| in Lua scripts.
+---       For Lua see |lua-script-location|.
----   <stack>    call stack
+---   <stack>    Call stack
----   <cword>    word under the cursor
+---   <cword>    Word under the cursor
 ---   <cWORD>    WORD under the cursor
----   <client>  the {clientid} of the last received
+---   <client>  The {clientid} of the last received
 ---       message
 --- Modifiers:
----   :p    expand to full path
+---   :p    Expand to full path
----   :h    head (last path component removed)
+---   :h    Head (last path component removed)
----   :t    tail (last path component only)
+---   :t    Tail (last path component only)
----   :r    root (one extension removed)
+---   :r    Root (one extension removed)
----   :e    extension only
+---   :e    Extension only
 ---
 --- Example: >vim
 ---   let &tags = expand("%:p:h") .. "/tags"

runtime/lua/vim/_system.lua

@@ -471,6 +471,10 @@ end
 
 --- Runs a system command or throws an error if {cmd} cannot be run.
 ---
+--- The command runs directly (not in 'shell') so shell builtins such as "echo" in cmd.exe, cmdlets
+--- in powershell, or "help" in bash, will not work unless you actually invoke a shell:
+--- `vim.system({'bash', '-c', 'help'})`.
+---
 --- Examples:
 ---
 --- ```lua

runtime/lua/vim/net.lua

@@ -40,17 +40,11 @@ function M.request(url, opts, on_response)
   table.insert(args, url)
 
   local function on_exit(res)
-    local err_msg = nil
+    local s = 'Request failed with exit code %d'
-    local response = nil
+    local err_msg = res.code ~= 0
-
+        and ((res.stderr ~= '' and res.stderr) or string.format(s, res.code))
-    if res.code ~= 0 then
+      or nil
-      err_msg = (res.stderr ~= '' and res.stderr)
+    local response = res.code == 0 and { body = opts.outpath and true or res.stdout } or nil
-        or string.format('Request failed with exit code %d', res.code)
-    else
-      response = {
-        body = opts.outpath and true or res.stdout,
-      }
-    end
 
     if on_response then
       on_response(err_msg, response)

runtime/lua/vim/shared.lua

@@ -1104,7 +1104,7 @@ do
         err_msg = is_valid(name, value, validator, msg, false)
       end
     elseif type(name) == 'table' then -- Form 2
-      vim.deprecate('vim.validate', 'vim.validate(name, value, validator, optional_or_msg)', '1.0')
+      vim.deprecate('vim.validate{<table>}', 'vim.validate(<params>)', '1.0')
       err_msg = validate_spec(name)
     else
       error('invalid arguments')

runtime/lua/vim/treesitter/query.lua

@@ -1163,9 +1163,8 @@ end
 
 --- Opens a live editor to query the buffer you started from.
 ---
---- Can also be shown with `:EditQuery`. [:EditQuery]()
+--- Can also be shown with the [:EditQuery]() command. `:EditQuery <tab>` completes available
----
+--- parsers.
---- `:EditQuery <tab>` completes the treesitter parser names in the runtime path.
 ---
 --- If you move the cursor to a capture name ("@foo"), text matching the capture is highlighted in
 --- the source buffer. The query editor is a scratch buffer, use `:write` to save it. You can find

scripts/vim-patch.sh

@@ -207,7 +207,7 @@ preprocess_patch() {
   2>/dev/null $nvim --cmd 'set dir=/tmp' +'g@^diff --git a/runtime/\<\%('"${na_rt}"'\)\>@exe "norm! d/\\v(^diff)|%$\r"' +w +q "$file"
 
   # Remove unwanted Vim doc files.
-  local na_doc='channel\.txt\|if_cscop\.txt\|netbeans\.txt\|os_\w\+\.txt\|print\.txt\|term\.txt\|todo\.txt\|vim9\.txt\|tags'
+  local na_doc='channel\.txt\|if_cscop\.txt\|netbeans\.txt\|os_\w\+\.txt\|print\.txt\|term\.txt\|testing\.txt\|todo\.txt\|vim9\.txt\|tags'
   2>/dev/null $nvim --cmd 'set dir=/tmp' +'g@^diff --git a/runtime/doc/\<\%('"${na_doc}"'\)\>@exe "norm! d/\\v(^diff)|%$\r"' +w +q "$file"
 
   # Remove "Last change ..." changes in doc files.

src/nvim/api/vim.c

@@ -466,12 +466,14 @@ error:
 /// Replaces terminal codes and |keycodes| ([<CR>], [<Esc>], ...) in a string with
 /// the internal representation.
 ///
+/// @note Lua can use |vim.keycode()| instead.
+/// @see replace_termcodes
+/// @see cpoptions
+///
 /// @param str        String to be converted.
 /// @param from_part  Legacy Vim parameter. Usually true.
 /// @param do_lt      Also translate [<lt>]. Ignored if `special` is false.
 /// @param special    Replace |keycodes|, e.g. [<CR>] becomes a "\r" char.
-/// @see replace_termcodes
-/// @see cpoptions
 String nvim_replace_termcodes(String str, Boolean from_part, Boolean do_lt, Boolean special)
   FUNC_API_SINCE(1) FUNC_API_RET_ALLOC
 {

src/nvim/eval.lua

@@ -2405,35 +2405,35 @@ M.funcs = {
       done like for the |cmdline-special| variables with their
       associated modifiers.  Here is a short overview:
 
-      	%		current file name
+      	%		Current file name
-      	#		alternate file name
+      	#		Alternate file name
-      	#n		alternate file name n
+      	#n		Alternate file name n
-      	<cfile>		file name under the cursor
+      	<cfile>		File name under the cursor
-      	<afile>		autocmd file name
+      	<afile>		Autocmd file name
-      	<abuf>		autocmd buffer number (as a String!)
+      	<abuf>		Autocmd buffer number (as a String!)
-      	<amatch>	autocmd matched name
+      	<amatch>	Autocmd matched name
       	<cexpr>		C expression under the cursor
-      	<sfile>		deprecated, use <script> or <stack>
+      	<sfile>		Deprecated, use <script> or <stack>
-      	<slnum>		sourced script line number or function
+      	<slnum>		Sourced script line number or function
       			line number
-      	<sflnum>	script file line number, also when in
+      	<sflnum>	Script file line number, also when in
       			a function
       	<SID>		"<SNR>123_"  where "123" is the
       			current script ID  |<SID>|
-      	<script>	sourced script file, or script file
+      	<script>	Sourced script file, or script file
       			where the current function was defined.
-      			Use |debug.getinfo()| in Lua scripts.
+      			For Lua see |lua-script-location|.
-      	<stack>		call stack
+      	<stack>		Call stack
-      	<cword>		word under the cursor
+      	<cword>		Word under the cursor
       	<cWORD>		WORD under the cursor
-      	<client>	the {clientid} of the last received
+      	<client>	The {clientid} of the last received
       			message
       Modifiers:
-      	:p		expand to full path
+      	:p		Expand to full path
-      	:h		head (last path component removed)
+      	:h		Head (last path component removed)
-      	:t		tail (last path component only)
+      	:t		Tail (last path component only)
-      	:r		root (one extension removed)
+      	:r		Root (one extension removed)
-      	:e		extension only
+      	:e		Extension only
 
       Example: >vim
       	let &tags = expand("%:p:h") .. "/tags"

src/nvim/globals.h

@@ -421,20 +421,20 @@ EXTERN int sc_col;              // column for shown command
 
 // First NO_SCREEN, then NO_BUFFERS, then 0 when startup finished.
 EXTERN int starting INIT( = NO_SCREEN);
-// true when planning to exit. Might keep running if there is a changed buffer.
+// Planning to exit. Might keep running if there is a changed buffer.
 EXTERN bool exiting INIT( = false);
-// true when planning to restart.
+// Planning to restart.
 EXTERN bool restarting INIT( = false);
-// internal value of v:dying
+// Internal value of v:dying
 EXTERN int v_dying INIT( = 0);
-// is stdin a terminal?
+// Is stdin a terminal?
 EXTERN bool stdin_isatty INIT( = true);
-// is stdout a terminal?
+// Is stdout a terminal?
 EXTERN bool stdout_isatty INIT( = true);
-// is stderr a terminal?
+// Is stderr a terminal?
 EXTERN bool stderr_isatty INIT( = true);
 
-/// filedesc set by embedder for reading first buffer like `cmd | nvim -`
+/// Filedesc set by embedder for reading first buffer like `cmd | nvim -`.
 EXTERN int stdin_fd INIT( = -1);
 
 // true when doing full-screen output, otherwise only writing some messages.

src/nvim/options.lua

@@ -2847,7 +2847,8 @@ local options = {
         Unset 'exrc' to stop further searching of 'exrc' files in parent
         directories, similar to |editorconfig.root|.
 
-        To get its own location, Lua exrc files can use |debug.getinfo()|.
+        To get its own location, a Lua exrc file can use |debug.getinfo()|.
+        See |lua-script-location|.
 
         Compare 'exrc' to |editorconfig|:
         - 'exrc' can execute any code; editorconfig only specifies settings.
@@ -2857,7 +2858,7 @@ local options = {
         1. Enable 'exrc'.
         2. Place LSP configs at ".nvim/lsp/*.lua" in your project root.
         3. Create ".nvim.lua" in your project root directory with this line: >lua
-             vim.cmd[[set runtimepath+=.nvim]]
+            vim.cmd[[set runtimepath+=.nvim]]
         <
         This option cannot be set from a |modeline| or in the |sandbox|, for
         security reasons.

test/functional/core/server_spec.lua

@@ -187,22 +187,22 @@ describe('server', function()
     -- After serverstop() the servers should NOT be in the list.
     eq(_n, eval('len(serverlist())'))
 
-    -- serverlist({ peer = true }) returns servers from other Nvim sessions.
+    -- serverlist({peer=true}) returns servers from other Nvim sessions.
     if t.is_os('win') then
       return
     end
-    local client_address = n.new_pipename()
+    local peer_addr = n.new_pipename()
     local client = n.new_session(
       true,
-      { args = { '-u', 'NONE', '--listen', client_address, '--embed' }, merge = false }
+      { args = { '--clean', '--listen', peer_addr, '--embed' }, merge = false }
     )
     n.set_session(client)
-    eq(client_address, fn.serverlist()[1])
+    eq(peer_addr, fn.serverlist()[1])
 
     n.set_session(current_server)
 
     new_servs = fn.serverlist({ peer = true })
-    eq(true, vim.list_contains(new_servs, client_address))
+    eq(true, vim.list_contains(new_servs, peer_addr))
     client:close()
   end)
 end)