docs: misc, custom text-object #39877

text-object-define is a pattern I found in tpope's plugins (e.g.
https://github.com/tpope/vim-jdaddy) which shows an elegant way to
define a text-object. (Any mistakes in the example are my fault.)

runtime/doc/api.txt

@@ -2228,8 +2228,8 @@ nvim_del_autocmd({id})                                    *nvim_del_autocmd()*
       • {id}  (`integer`) Autocommand id returned by |nvim_create_autocmd()|
 
 nvim_exec_autocmds({event}, {opts})                     *nvim_exec_autocmds()*
-    Executes handlers for {event} that match the corresponding {opts} query.
-    |autocmd-execute|
+    Executes {event} handlers matching the {opts} query, in the context of
+    {buf} (if given). |autocmd-execute|
 
     Attributes: ~
         Since: 0.7.0

runtime/doc/motion.txt

@@ -772,6 +772,43 @@ matching end tag.  These are ignored.
 
 The text objects are tolerant about mistakes.  Stray end tags are ignored.
 
+------------------------------------------------------------------------------
+Custom text object					  *text-object-define*
+
+The following code example shows how to define your own custom text-object.
+Notice how the Visual-mode (xnoremap) mapping is defined as an <expr> mapping
+which sets the |'[| |']| marks, then the Operator-pending (onoremap) mapping
+is implemented using Visual-mode.
+
+>vim
+    " text-object: entire buffer
+    function! s:line_outer_movement(count) abort
+      if empty(getline(1)) && 1 == line('$')
+        return "\<Esc>"
+      endif
+      let [lopen, copen, lclose, cclose] = [1, 1, line('$'), 1]
+      call setpos("'[", [0, lopen, copen, 0])
+      call setpos("']", [0, lclose, cclose, 0])
+      return "'[o']"
+    endfunction
+    xnoremap <expr>   al <SID>line_outer_movement(v:count1)
+    onoremap <silent> al :normal Val<CR>
+
+    " text-object: line
+    function! s:line_inner_movement(count) abort
+      "TODO: handle count
+      if empty(getline('.'))
+        return "\<Esc>"
+      endif
+      let [lopen, copen, lclose, cclose] = [line('.'), 1, line('.'), col('$')-1]
+      call setpos("'[", [0, lopen, copen, 0])
+      call setpos("']", [0, lclose, cclose, 0])
+      return "`[o`]"
+    endfunction
+    xnoremap <expr>   il <SID>line_inner_movement(v:count1)
+    onoremap <silent> il :normal vil<CR>
+<
+
 ==============================================================================
 7. Marks					*mark-motions* *E20* *E78*
 

runtime/doc/news.txt

@@ -201,11 +201,11 @@ LUA
 • |vim.npcall()| calls the function `fn` in protected-mode like |pcall()|,
   but returns `nil` on error.
 • |vim.pos| can now convert between positions and buffer offsets.
+• |vim.pos| and |vim.range| can now convert between mark positions.
 • |vim.ui.input()| now allows setting input scope.
-• |vim.log| for easily creating loggers.
+• |vim.log| provides a logging interface.
 • |vim.pack.get()| output includes revision of a pending update.
 • |vim.pack.get()| can fetch new updates before computing the output.
-• |vim.pos| and |vim.range| can now convert between mark positions.
 
 OPTIONS
 
@@ -218,15 +218,13 @@ PERFORMANCE
 
 • |treesitter-highlight| performance on large injection-heavy files improves
   by 50% to 100% by reusing edited child-tree ranges.
-
 • Nvim architecture allows pure-Lua implementations of some `vim.fn`
   functions, which skips the Vimscript <=> Lua "bridge" (no data
   conversion/marshalling) entirely, if the `vim.fn` function is called from
   Lua.
-• The table holding LSP data is now cleared using `table.clear`,
-  thus reducing GC and memory reallocation during each data reset.
-• When parsing the received Content-Length messages,
-  the RPC client will no longer allocate extra strings.
+• Internal LSP data is cleared using `table.clear`, which reduces GC and
+  memory reallocation during each data reset.
+• RPC client avoids string allocations when parsing Content-Length messages.
 
 PLUGINS
 
@@ -275,6 +273,7 @@ CHANGED FEATURES                                                 *news-changed*
 
 These existing features changed their behavior.
 
+• `nvim_exec_autocmds({buf=…})` runs in the context of the target buffer.
 • |OptionSet| is no longer triggered during startup by automatic
   |'background'| detection.
 • |:Open| with no arguments uses the current file.

runtime/doc/remote.txt

@@ -111,25 +111,5 @@ yet. The following command line arguments are not yet available:
    --remote-tab-wait-silent	Not yet supported by Nvim.
 				Like --remote-wait-silent but open each file
 				in a new tabpage.
-							    *--servername*
-   --servername {name}          Not yet supported by Nvim.
-				Become the server {name}.  When used together
-                                with one of the --remote commands: connect to
-                                server {name} instead of the default (see
-                                below).  The name used will be uppercase.
-
-								*--serverlist*
-   --serverlist			Not yet supported by Nvim.
-				Output a list of server names.
-
-
-
-
-SERVER NAME						*client-server-name*
-
-By default Vim will try to register the name under which it was invoked (gvim,
-egvim ...).  This can be overridden with the --servername argument.  Nvim
-either listens on a named pipe or a socket and does not yet support this
---servername functionality.
 
  vim:tw=78:sw=4:ts=8:noet:ft=help:norl:

runtime/doc/vim_diff.txt

@@ -231,7 +231,7 @@ MAJOR COMPONENTS
 - API                             |API|
 - Job control                     |job-control|
 - LSP framework                   |lsp|
-- Lua scripting                   |lua|
+- Lua scripting                   |lua| |-l|
 - Parsing engine                  |treesitter|
 - Plugin manager                  |vim.pack|
 - Providers
@@ -239,6 +239,7 @@ MAJOR COMPONENTS
   - Node.js plugins               |provider-nodejs|
   - Python plugins                |provider-python|
   - Ruby plugins                  |provider-ruby|
+- Remote                          |--remote-ui| |:connect| |:detach|
 - Remote plugins                  |remote-plugin|
 - Shared data                     |shada|
 - Terminal emulator               |terminal|
@@ -282,8 +283,7 @@ ARCHITECTURE
 
 The Nvim UI is "decoupled" from the core editor: all UIs, including the
 builtin |TUI| are just plugins that connect to a Nvim server (via |--server|
-or |--embed|). Multiple Nvim UI clients can connect to the same Nvim editor
-server.
+or |--embed|). Multiple UI clients can |:connect| to the same editor server.
 
 External plugins run in separate processes. |remote-plugin| This improves
 stability and allows those plugins to work without blocking the editor. Even
@@ -292,7 +292,7 @@ stability and allows those plugins to work without blocking the editor. Even
 
 Platform and I/O facilities are built upon libuv. Nvim benefits from libuv
 features and bug fixes, and other projects benefit from improvements to libuv
-by Nvim developers.
+by Nvim developers. This enables features such as |vim.wait()| and |vim.uv|.
 
 FEATURES
 
@@ -910,6 +910,8 @@ Providers:
 Startup:
 - `--literal`: File args are always literal; to expand wildcards on Windows,
   use |:n| e.g. `nvim +"n *"`
+- *--serverlist* Use instead: `nvim -es -V1 +'echo serverlist()'`
+- *--servername* Use instead: |--server| or |:connect|.
 - Easy mode: eview, evim, nvim -y
 - Restricted mode: rview, rvim, nvim -Z
 - Vi mode: nvim -v

runtime/lua/vim/_meta/api.gen.lua

@@ -1231,7 +1231,8 @@ function vim.api.nvim_exec(src, output) end
 --- - output: (string|nil) Output if `opts.output` is true.
 function vim.api.nvim_exec2(src, opts) end
 
---- Executes handlers for {event} that match the corresponding {opts} query. `autocmd-execute`
+--- Executes {event} handlers matching the {opts} query, in the context of {buf} (if given). `autocmd-execute`
+---
 --- @see `:help :doautocmd`
 --- @param event vim.api.keyset.events|vim.api.keyset.events[] Event(s) to execute.
 --- @param opts vim.api.keyset.exec_autocmds Optional filters:

runtime/plugin/net.lua

@@ -82,7 +82,7 @@ vim.api.nvim_create_autocmd('BufReadCmd', {
           return
         end
 
-        vim.api.nvim_exec_autocmds('BufRead', { group = 'filetypedetect', buffer = ev.buf })
+        vim.api.nvim_exec_autocmds('BufRead', { group = 'filetypedetect', buf = ev.buf })
         vim.bo[ev.buf].modified = false
         vim.notify(('Loaded %s'):format(url), vim.log.levels.INFO)
       end)

src/nvim/api/autocmd.c

@@ -678,7 +678,8 @@ void nvim_del_augroup_by_name(String name, Error *err)
   });
 }
 
-/// Executes handlers for {event} that match the corresponding {opts} query. |autocmd-execute|
+/// Executes {event} handlers matching the {opts} query, in the context of {buf} (if given). |autocmd-execute|
+///
 /// @param event Event(s) to execute.
 /// @param opts Optional filters:
 ///        - buf (`integer?`) Buffer where the event is applied. |autocmd-buflocal| Not allowed with {pattern}.