docs: backport (#35675)

docs: lsp, misc

runtime/doc/api.txt

@@ -1319,9 +1319,9 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes})
     debugging and orchestration. (Note: Something is better than nothing!
     Fields are optional, but at least set `name`.)
 
-    Can be called more than once; the caller should merge old info if
-    appropriate. Example: library first identifies the channel, then a plugin
-    using that library later identifies itself.
+    Can be called more than once; caller should merge old info if appropriate.
+    Example: a library first identifies the channel, then a plugin using that
+    library later identifies itself.
 
     Attributes: ~
         |RPC| only

runtime/doc/change.txt

@@ -1143,23 +1143,23 @@ first word).  You can use the "']" or "`]" command after the put command to
 move the cursor to the end of the inserted text, or use "'[" or "`[" to move
 the cursor to the start.
 
-						*put-Visual-mode* *v_p* *v_P*
+							     *put-Visual-mode*
 When using a put command like |p| or |P| in Visual mode, Vim will try to
-replace the selected text with the contents of the register.  Whether this
-works well depends on the type of selection and the type of the text in the
-register.  With blockwise selection it also depends on the size of the block
-and whether the corners are on an existing character.  (Implementation detail:
-it actually works by first putting the register after the selection and then
-deleting the selection.)
-With |p| the previously selected text is put in the unnamed register (and
-possibly the selection and/or clipboard).  This is useful if you want to put
-that text somewhere else.  But you cannot repeat the same change.
-With |P| the unnamed register is not changed (and neither the selection or
-clipboard), you can repeat the same change. But the deleted text cannot be
-used.  If you do need it you can use |p| with another register.  E.g., yank
-the text to copy, Visually select the text to replace and use "0p .  You can
-repeat this as many times as you like, and the unnamed register will be
-changed each time.
+replace the selected text with the contents of the register.  How this
+works depends on the type of selection and the text. With blockwise selection
+it also depends on the size of the block and whether the corners are on an
+existing character.  (Implementation detail: it actually works by first
+putting the register after the selection and then deleting the selection.)
+									 *v_p*
+|p| in Visual mode puts text and sets the default register (unnamed,
+selection, or clipboard) to the previously-selected text.  Useful if you want
+to put that text somewhere else.  But you cannot repeat the same change.
+									 *v_P*
+|P| in Visual mode puts text without setting the default register. You can
+repeat the change, but the deleted text cannot be used.  If you do need it you
+can use |p| with another register.  E.g., yank the text to copy, Visually
+select the text to replace and use "0p .  You can repeat this as many times as
+you like, and the unnamed register will be changed each time.
 							*blockwise-put*
 When a register contains text from one line (characterwise), using a
 blockwise Visual selection, putting that register will paste that text

runtime/doc/develop.txt

@@ -446,6 +446,8 @@ Use existing common {verb} names (actions) if possible:
     - is_enabled:   Checks if functionality is enabled.
     - open:         Opens something (a buffer, window, …)
     - parse:        Parses something into a structured form
+    - request:      Calls a remote (network, RPC) operation.
+    - send:         Writes data or a message to a channel.
     - set:          Sets a thing (or group of things)
     - start:        Spin up a long-lived process. Prefer "enable" except when
                     "start" is obviously more appropriate.
@@ -456,7 +458,7 @@ Do NOT use these deprecated verbs:
     - contains:     Prefer "has".
     - disable:      Prefer `enable(enable: boolean)`.
     - exit:         Prefer "cancel" (or "stop" if appropriate).
-    - is_disabled:  Prefer `is_enabled()`.
+    - is_disabled:  Prefer `!is_enabled()`.
     - list:         Redundant with "get"
     - notify:       Redundant with "print", "echo"
     - show:         Redundant with "print", "echo"

runtime/doc/lua-guide.txt

@@ -10,9 +10,9 @@
 ==============================================================================
 Introduction                                                         *lua-guide*
 
-This guide introduces the basics of everyday usage of Lua to configure and
-operate Nvim. It assumes some familiarity with the (non-Lua) basics of Nvim
-(commands, options, mappings, autocommands), which are covered in the
+This guide introduces the basics of everyday Lua usage for configuring and
+controlling Nvim. It assumes some familiarity with the (non-Lua) basics of
+Nvim (commands, options, mappings, autocommands), which are covered in the
 |user-manual|.
 
 This is not a comprehensive encyclopedia of all available features. Think of

runtime/doc/lua-plugin.txt

@@ -10,7 +10,7 @@
 ==============================================================================
 Introduction                                                       *lua-plugin*
 
-This document provides guidance for developing Nvim (Lua) plugins:
+This document provides guidance for developing Nvim Lua plugins.
 
 See |lua-guide| for guidance on using Lua to configure and operate Nvim.
 See |luaref| and |lua-concepts| for details on the Lua programming language.
@@ -19,7 +19,7 @@ See |luaref| and |lua-concepts| for details on the Lua programming language.
 Creating your first plugin                                    *lua-plugin-new*
 
 Any Vimscript or Lua code file that lives in the right directory,
-automatically is a "plugin". There's no maniest or "registration" required.
+automatically is a "plugin". There's no manifest or "registration" step.
 
 You can try it right now:
 
@@ -35,7 +35,7 @@ You can try it right now:
 
 Besides `plugin/foo.lua`, which is always run at startup, you can define Lua
 modules in the `lua/` directory. Those modules aren't loaded until your
-`plugin/foo.lua`, the user, calls `require(…)`.
+`plugin/foo.lua`, or the user, calls `require(…)`.
 
 ==============================================================================
 Type safety                                            *lua-plugin-type-safety*
@@ -108,11 +108,11 @@ In your plugin:
 >lua
     vim.keymap.set('n', '<Plug>(SayHello)', function()
         print('Hello from normal mode')
-    end, { noremap = true })
+    end)
 
     vim.keymap.set('v', '<Plug>(SayHello)', function()
         print('Hello from visual mode')
-    end, { noremap = true })
+    end)
 <
 In the user's config:
 >lua
@@ -182,7 +182,9 @@ For example, instead of:
     local foo = require('foo')
     vim.api.nvim_create_user_command('MyCommand', function()
         foo.do_something()
-    end, { -- ... })
+    end, {
+      -- ...
+    })
 <
 which calls `require('foo')` as soon as the module is loaded, you can
 lazy-load it by moving the `require` into the command's implementation:
@@ -233,7 +235,7 @@ A plugin tailored to Rust development might have initialization in
     -- e.g. add a |<Plug>| mapping or create a command
     vim.keymap.set('n', '<Plug>(MyPluginBufferAction)', function()
         print('Hello')
-    end, { noremap = true, buffer = bufnr, })
+    end, { buffer = bufnr, })
 <
 ==============================================================================
 Configuration                                              *lua-plugin-config*
@@ -277,7 +279,7 @@ Versioning and releases                                *lua-plugin-versioning*
 Consider:
 
 - Use |vim.deprecate()| or a `---@deprecate` annotation when you need to
-  communicate a (future) breaking change or discourged practice.
+  communicate a (future) breaking change or discouraged practice.
 - Using SemVer https://semver.org/ tags and releases to properly communicate
   bug fixes, new features, and breaking changes.
 - Automating versioning and releases in CI.
@@ -302,7 +304,9 @@ VERSIONING TOOLS
 Documentation                                                 *lua-plugin-doc*
 
 Provide vimdoc (see |help-writing|), so that users can read your plugin's
-documentation in Nvim, by entering `:h {plugin}` in |command-mode|.
+documentation in Nvim, by entering `:h {plugin}` in |command-mode|. The
+help-tags (the right-aligned "search keywords" in the help documents) are
+regenerated using the |:helptags| command.
 
 DOCUMENTATION TOOLS
 

scripts/cliff.toml

@@ -4,8 +4,8 @@
 # changelog header
 header = """
 # Changelog\n
-For notable changes, see runtime/doc/news.txt (or `:help news` in Nvim).\n
-Following is a list of fixes/features commits.\n
+Following is a list of commits (fixes/features only) in this release.\n
+See `:help news` in Nvim for release notes.\n
 """
 # template for the changelog body
 # https://github.com/Keats/tera

scripts/release.sh

@@ -97,5 +97,5 @@ echo "
 Next steps:
     - Run tests/CI (version_spec.lua)!
     - Push the tag:
-        git push --follow-tags
+        git push v${__VERSION}
     - Update website: index.html"

src/gen/gen_help_html.lua

@@ -72,6 +72,8 @@ local new_layout = {
   ['gui.txt'] = true,
   ['intro.txt'] = true,
   ['lua.txt'] = true,
+  ['lua-guide.txt'] = true,
+  ['lua-plugin.txt'] = true,
   ['luaref.txt'] = true,
   ['news.txt'] = true,
   ['news-0.9.txt'] = true,

src/nvim/README.md

@@ -409,13 +409,18 @@ name, etc.
 
 All the global variables are declared in `globals.h`.
 
-### The main loop
+### The main event-loop
 
 The main loop is implemented in state_enter. The basic idea is that Vim waits
 for the user to type a character and processes it until another character is
 needed.  Thus there are several places where Vim waits for a character to be
 typed.  The `vgetc()` function is used for this.  It also handles mapping.
 
+What we consider the "Nvim event loop" is actually a wrapper around `uv_run` to
+handle both the `fast_events` queue and possibly (a suitable subset of) deferred
+events. Therefore "raw" `vim.uv.run()` is often not enough to "yield" from Lua
+plugins; instead they can call `vim.wait(0)`.
+
 Updating the screen is mostly postponed until a command or a sequence of
 commands has finished.  The work is done by `update_screen()`, which calls
 `win_update()` for every window, which calls `win_line()` for every line.

src/nvim/api/vim.c

@@ -1489,7 +1489,7 @@ Array nvim_get_api_info(uint64_t channel_id, Arena *arena)
 /// orchestration. (Note: Something is better than nothing! Fields are optional, but at least set
 /// `name`.)
 ///
-/// Can be called more than once; the caller should merge old info if appropriate. Example: library
+/// Can be called more than once; caller should merge old info if appropriate. Example: a library
 /// first identifies the channel, then a plugin using that library later identifies itself.
 ///
 /// @param channel_id