Merge #21428 docs: naming conventions, guidelines

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -6,15 +6,14 @@ body:
   - type: markdown
     attributes:
       value: |
-        _Before reporting:_ search [existing issues](https://github.com/neovim/neovim/issues?q=is%3Aissue+is%3Aopen+label%3Abug) and check the [FAQ](https://github.com/neovim/neovim/wiki/FAQ). Usage questions such as "How do I...?" belong on the [Neovim Discourse](https://neovim.discourse.group/c/7-category/7) and will be closed.
+        _Before reporting:_ search [existing issues](https://github.com/neovim/neovim/issues?q=is%3Aissue+is%3Aopen+label%3Abug) and check the [FAQ](https://github.com/neovim/neovim/wiki/FAQ). Usage or "How to" questions belong on the [stackoverflow](https://vi.stackexchange.com/) and will be closed.
 
   - type: textarea
     attributes:
-      label: "Describe the bug"
+      label: "Problem"
       description: "Describe the current behavior. May include logs, images, or videos."
     validations:
       required: true
-
   - type: textarea
     attributes:
       label: "Steps to reproduce"
@@ -27,7 +26,6 @@ body:
         yiwp
     validations:
       required: true
-
   - type: textarea
     attributes:
       label: "Expected behavior"

.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,5 @@
 blank_issues_enabled: false
 contact_links:
   - name: Question
-    url: https://neovim.discourse.group/
+    url: https://vi.stackexchange.com/
     about: Ask questions about configuration and usage of Neovim

.github/ISSUE_TEMPLATE/lsp_bug_report.yml

@@ -6,27 +6,14 @@ body:
   - type: markdown
     attributes:
       value: |
-        _Before reporting:_ search [existing issues](https://github.com/neovim/neovim/issues?q=is%3Aissue+is%3Aopen+label%3Abug) and check the [FAQ](https://github.com/neovim/neovim/wiki/FAQ). Usage questions such as "How do I...?" or "Why isn't X language server/feature working?" belong on the [Neovim Discourse](https://neovim.discourse.group/c/7-category/7) and will be closed.
+        _Before reporting:_ search [existing issues](https://github.com/neovim/neovim/issues?q=is%3Aissue+is%3Aopen+label%3Abug) and check the [FAQ](https://github.com/neovim/neovim/wiki/FAQ). Usage questions or "Why isn't X language server/feature working?" belong on [stackoverflow](https://vi.stackexchange.com/) and will be closed.
 
-  - type: input
+  - type: textarea
     attributes:
-      label: "Neovim version (nvim -v)"
+      label: "Problem"
-      placeholder: "0.6.0 commit db1b0ee3b30f"
+      description: "Describe the bug caused by the Nvim LSP client."
     validations:
       required: true
-  - type: input
-    attributes:
-      label: "Language server name/version"
-      placeholder: "rls 0.5.2"
-    validations:
-      required: true
-  - type: input
-    attributes:
-      label: "Operating system/version"
-      placeholder: "emacs 23"
-    validations:
-      required: true
-
   - type: textarea
     attributes:
       label: 'Steps to reproduce using "nvim -u minimal_init.lua"'
@@ -65,14 +52,29 @@ body:
         _Note_: if the issue is with an autocompletion or other LSP plugin, report to that plugin's issue tracker.
     validations:
       required: true
-
   - type: textarea
     attributes:
       label: "Expected behavior"
       description: "Describe the behavior you expect. May include logs, images, or videos."
-  - type: textarea
+
+  - type: input
     attributes:
-      label: "Actual behavior"
+      label: "Neovim version (nvim -v)"
+      placeholder: "0.6.0 commit db1b0ee3b30f"
+    validations:
+      required: true
+  - type: input
+    attributes:
+      label: "Language server name/version"
+      placeholder: "rls 0.5.2"
+    validations:
+      required: true
+  - type: input
+    attributes:
+      label: "Operating system/version"
+      placeholder: "emacs 23"
+    validations:
+      required: true
 
   - type: input
     attributes:

README.md

@@ -75,7 +75,6 @@ See [`:help nvim-from-vim`](https://neovim.io/doc/user/nvim.html#nvim-from-vim)
 Project layout
 --------------
 
-    ├─ ci/              build automation
     ├─ cmake/           CMake utils
     ├─ cmake.config/    CMake defines
     ├─ cmake.deps/      subproject to fetch and build dependencies (optional)

runtime/doc/api.txt

@@ -1461,16 +1461,15 @@ nvim_set_keymap({mode}, {lhs}, {rhs}, {*opts})             *nvim_set_keymap()*
                 "!" for |:map!|, or empty string for |:map|.
       • {lhs}   Left-hand-side |{lhs}| of the mapping.
       • {rhs}   Right-hand-side |{rhs}| of the mapping.
-      • {opts}  Optional parameters map: keys are |:map-arguments|, values are
+      • {opts}  Optional parameters map: Accepts all |:map-arguments| as keys
-                booleans (default false). Accepts all |:map-arguments| as keys
+                except |<buffer>|, values are booleans (default false). Also:
-                excluding |<buffer>| but including |:noremap| and "desc".
+                • "noremap" non-recursive mapping |:noremap|
-                Unknown key is an error. "desc" can be used to give a
+                • "desc" human-readable description.
-                description to the mapping. When called from Lua, also accepts
+                • "callback" Lua function called when the mapping is executed.
-                a "callback" key that takes a Lua function to call when the
+                • "replace_keycodes" (boolean) When "expr" is true, replace
-                mapping is executed. When "expr" is true, "replace_keycodes"
+                  keycodes in the resulting string (see
-                (boolean) can be used to replace keycodes in the resulting
+                  |nvim_replace_termcodes()|). Returning nil from the Lua
-                string (see |nvim_replace_termcodes()|), and a Lua callback
+                  "callback" is equivalent to returning an empty string.
-                returning `nil` is equivalent to returning an empty string.
 
 nvim_set_var({name}, {value})                                 *nvim_set_var()*
     Sets a global (g:) variable.
@@ -1678,7 +1677,7 @@ Command Functions                                                *api-command*
 
                                               *nvim_buf_create_user_command()*
 nvim_buf_create_user_command({buffer}, {name}, {command}, {*opts})
-    Create a new user command |user-commands| in the given buffer.
+    Creates a buffer-local command |user-commands|.
 
     Parameters: ~
       • {buffer}  Buffer handle, or 0 for current buffer.
@@ -1743,15 +1742,12 @@ nvim_cmd({*cmd}, {*opts})                                         *nvim_cmd()*
 
                                                   *nvim_create_user_command()*
 nvim_create_user_command({name}, {command}, {*opts})
-    Create a new user command |user-commands|
+    Creates a global |user-commands| command.
 
-    {name} is the name of the new command. The name must begin with an
+    For Lua usage see |lua-guide-commands-create|.
-    uppercase letter.
-
-    {command} is the replacement text or Lua function to execute.
 
     Example: >vim
-       :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {})
+       :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {'bang': v:true})
        :SayHello
        Hello world!
 <
@@ -1783,13 +1779,14 @@ nvim_create_user_command({name}, {command}, {*opts})
                    • smods: (table) Command modifiers in a structured format.
                      Has the same structure as the "mods" key of
                      |nvim_parse_cmd()|.
-      • {opts}     Optional command attributes. See |command-attributes| for
+      • {opts}     Optional |command-attributes|.
-                   more details. To use boolean attributes (such as
+                   • Set boolean attributes such as |:command-bang| or
-                   |:command-bang| or |:command-bar|) set the value to "true".
+                     |:command-bar| to true (but not |:command-buffer|, use
-                   In addition to the string options listed in
+                     |nvim_buf_create_user_command()| instead).
-                   |:command-complete|, the "complete" key also accepts a Lua
+                   • "complete" |:command-complete| also accepts a Lua
-                   function which works like the "customlist" completion mode
+                     function which works like
-                   |:command-completion-customlist|. Additional parameters:
+                     |:command-completion-customlist|.
+                   • Other parameters:
                      • desc: (string) Used for listing the command when a Lua
                        function is used for {command}.
                      • force: (boolean, default true) Override any previous

runtime/doc/develop.txt

@@ -132,6 +132,18 @@ DOCUMENTATION						*dev-doc*
   optimize for the reader's time and energy: be "precise yet concise".
     - See https://developers.google.com/style/tone
     - Prefer the active voice: "Foo does X", not "X is done by Foo".
+- Start function docstrings with present tense ("Gets"), not imperative
+  ("Get"). This tends to reduce ambiguity and improve clarity. >
+    GOOD:
+    /// Gets a highlight definition.
+    BAD:
+    /// Get a highlight definition.
+- Avoid starting docstrings with "The" or "A" unless needed to avoid
+  ambiguity. This is a visual aid and reduces noise. >
+    GOOD:
+    /// @param dirname Path fragment before `pend`
+    BAD:
+    /// @param dirname The path fragment before `pend`
 - Vim differences:
     - Do not prefix help tags with "nvim-". Use |vim_diff.txt| to catalog
       differences from Vim; no other distinction is necessary.
@@ -143,13 +155,6 @@ DOCUMENTATION						*dev-doc*
       not "the user host terminal".
     - Use "tui-" to prefix help tags related to the host terminal, and "TUI"
       in prose if possible.
-- Docstrings: do not start parameter descriptions with "The" or "A" unless it
-  is critical to avoid ambiguity. >
-    GOOD:
-    /// @param dirname Path fragment before `pend`
-    BAD:
-    /// @param dirname The path fragment before `pend`
-<
 
 Documentation format ~
 
@@ -159,14 +164,14 @@ https://neovim.io/doc/user ).
 
 Strict "vimdoc" subset:
 
-- Use lists (like this!) prefixed with "-", "*", or "•", for adjacent lines
+- Use lists (like this!) prefixed with "-" or "•", for adjacent lines that you
-  that you don't want auto-wrapped. Lists are always rendered with "flow"
+  don't want to auto-wrap. Lists are always rendered with "flow" layout
-  (soft-wrapped) layout instead of preformatted (hard-wrapped) layout common
+  (soft-wrapped) instead of preformatted (hard-wrapped) layout common in
-  in legacy :help docs.
+  legacy :help docs.
   - Limitation: currently the parser https://github.com/neovim/tree-sitter-vimdoc
     does not understand numbered listitems, so use a bullet symbol (- or •)
-    before numbered items, e.g. "- 1." instead of "1.".
+    before numbered items, e.g. "• 1." instead of "1.".
-- Separate blocks (paragraphs) of content by a blank line(s).
+- Separate blocks (paragraphs) of content by a blank line.
 - Do not use indentation in random places—that prevents the page from using
   "flow" layout. If you need a preformatted section, put it in
   a |help-codeblock| starting with ">".
@@ -246,7 +251,9 @@ vim.paste in runtime/lua/vim/_editor.lua like this: >
     ---@returns false if client should cancel the paste.
 
 
-LUA							*dev-lua*
+LUA STDLIB DESIGN GUIDELINES				*dev-lua*
+
+See also |dev-naming|.
 
 - Keep the core Lua modules |lua-stdlib| simple. Avoid elaborate OOP or
   pseudo-OOP designs. Plugin authors just want functions to call, not a big,
@@ -255,10 +262,26 @@ LUA							*dev-lua*
   tables or values are easier to serialize, easier to construct from literals,
   easier to inspect and print, and inherently compatible with all Lua plugins.
   (This guideline doesn't apply to opaque, non-data objects like `vim.cmd`.)
+- stdlib functions should follow these common patterns:
+  - accept iterable instead of table
+    - exception: in some cases iterable doesn't make sense, e.g. spair() sorts
+      the input by definition, so there is no reason for it to accept an
+      iterable, because the input needs to be "hydrated", it can't operate on
+      a "stream".
+  - return iterable instead of table
+  - mimic the pairs() or ipairs() interface if the function is intended to be
+    used in a "for" loop.
 
 
-API							*dev-api*
+API DESIGN GUIDELINES					*dev-api*
 
+See also |dev-naming|.
+
+- When adding an API, check the following:
+  - What precedents did you draw from? How does your solution compare to them?
+  - Does your new API allow future expansion? How? Or why not?
+  - Is the new API similar to existing APIs? Do we need to deprecate the old ones?
+  - Did you cross-reference related concepts in the docs?
 - Avoid "mutually exclusive" parameters--via constraints or limitations, if
   necessary. For example nvim_create_autocmd() has mutually exclusive
   "callback" and "command" args; but the "command" arg could be eliminated by
@@ -266,66 +289,95 @@ API							*dev-api*
   "callback" arg as an Ex command (which can call Vimscript functions). The
   "buffer" arg could also be eliminated by treating a number "pattern" as
   a buffer number.
+- Avoid functions that depend on cursor position, current buffer, etc. Instead
+  the function should take a position parameter, buffer parameter, etc.
 
-                                                              *dev-api-naming*
+NAMING GUIDELINES                                       *dev-naming*
-Use this format to name new RPC |API| functions:
 
-    nvim_{thing}_{action}_{arbitrary-qualifiers}
+Naming is exceedingly important: the name of a thing is the primary interface
+for uses it, discusses it, searches for it, shares it... Consistent
+naming in the stdlib, API, and UI helps both users and developers discover and
+intuitively understand related concepts ("families"), and reduces cognitive
+burden. Discoverability encourages code re-use and likewise avoids redundant,
+overlapping mechanisms, which reduces code surface-area, and thereby minimizes
+bugs...
 
-If the function acts on an object then {thing} is the name of that object
+Naming conventions ~
-(e.g. "buf" or "win"). If the function operates in a "global" context then
-{thing} is usually omitted (but consider "namespacing" your global operations
-with a {thing} that groups functions under a common concept).
 
-Use existing common {action} names if possible:
+In general, look for precedent when choosing a name, that is, look at existing
-    - add       Append to, or insert into, a collection
+(non-deprecated) functions. In particular, see below...
-    - call      Call a function
+
-    - create    Create a new (non-trivial) thing
+							*dev-name-common*
-    - del       Delete a thing (or group of things)
+Use existing common {verb} names (actions) if possible:
-    - eval      Evaluate an expression
+    - add:          Appends or inserts into a collection
-    - exec      Execute code
+    - attach:       Listens to something to get events from it (TODO: rename to "on"?)
-    - fmt       Format
+    - call:         Calls a function
-    - get       Get things (often by a query)
+    - clear:        Clears state but does not destroy the container
-    - open      Open
+    - create:       Creates a new (non-trivial) thing (TODO: rename to "def"?)
-    - parse     Parse something into a structured form
+    - del:          Deletes a thing (or group of things)
-    - set       Set a thing (or group of things)
+    - detach:       Dispose attached listener (TODO: rename to "un"?)
+    - eval:         Evaluates an expression
+    - exec:         Executes code
+    - fmt:          Formats
+    - get:          Gets things (often by a query)
+    - inspect:      Presents a high-level, often interactive, view
+    - open:         Opens something (a buffer, window, …)
+    - parse:        Parses something into a structured form
+    - set:          Sets a thing (or group of things)
+    - try_{verb}:   Best-effort operation, failure returns null or error obj
 
 Do NOT use these deprecated verbs:
-    - list      Redundant with "get"
+    - list:         Redundant with "get"
+    - show:         Redundant with "print", "echo"
+    - notify:       Redundant with "print", "echo"
 
-Use consistent names for {thing} (nouns) in API functions: buffer is called
+Use consistent names for {noun} (nouns) in API functions: buffer is called
 "buf" everywhere, not "buffer" in some places and "buf" in others.
-    - buf       Buffer
+    - buf:          Buffer
-    - chan      |channel|
+    - chan:         |channel|
-    - cmd       Command
+    - cmd:          Command
-    - cmdline   Command-line UI or input
+    - cmdline:      Command-line UI or input
-    - fn        Function
+    - fn:           Function
-    - hl        Highlight
+    - hl:           Highlight
-    - pos       Position
+    - pos:          Position
-    - proc      System process
+    - proc:         System process
-    - tabpage   Tabpage
+    - tabpage:      Tabpage
-    - win       Window
+    - win:          Window
 
 Do NOT use these deprecated nouns:
     - buffer
     - command
     - window
 
-Example:
+							*dev-name-events*
-    `nvim_get_keymap('v')` operates in a global context (first parameter is not
+Use the "on_" prefix to name event-handling callbacks and also the interface for
-    a Buffer). The "get" {action} indicates that it gets anything matching the
+"registering" such handlers (on_key). The dual nature is acceptable to avoid
-    given filter parameter. There is no need for a "list" action because
+a confused collection of naming conventions for these related concepts.
-    `nvim_get_keymap('')` (i.e., empty filter) returns all items.
 
-Example:
+Editor |events| (autocommands) are historically named like: >
-    `nvim_buf_del_mark` acts on a `Buffer` object (the first parameter)
+    {Noun}{Event}
-    and uses the "del" {action}.
 
-Use this format to name new API events:
+Use this format to name API (RPC) events: >
-    nvim_{thing}_{event}_event
+    nvim_{noun}_{event-name}_event
 
-Example:
+Example: >
-    `nvim_buf_changedtick_event`
+    nvim_buf_changedtick_event
+<
+							*dev-name-api*
+Use this format to name new RPC |API| functions: >
+    nvim_{noun}_{verb}_{arbitrary-qualifiers}
+
+If the function acts on an object then {noun} is the name of that object
+(e.g. "buf" or "win"). If the function operates in a "global" context then
+{noun} is usually omitted (but consider "namespacing" your global operations
+with a {noun} that groups functions under a common concept).
+
+- Example: `nvim_get_keymap('v')` operates in a global context (first
+  parameter is not a Buffer). The "get" verb indicates that it gets anything
+  matching the given filter parameter. A "list" verb is unnecessary because
+  `nvim_get_keymap('')` (empty filter) returns all items.
+- Example: `nvim_buf_del_mark` acts on a `Buffer` object (the first parameter)
+  and uses the "del" {verb}.
 
 
 API-CLIENT						*dev-api-client*
@@ -417,19 +469,4 @@ External UIs are expected to implement these common features:
   published in this event. See also "mouse_on", "mouse_off".
 
 
-NAMING							*dev-naming*
-
-Naming is important. Consistent naming in the API and UI helps both users and
-developers discover and intuitively understand related concepts ("families"),
-and reduces cognitive burden. Discoverability encourages code re-use and
-likewise avoids redundant, overlapping mechanisms, which reduces code
-surface-area, and thereby minimizes bugs...
-
-Naming conventions ~
-
-Use the "on_" prefix to name event handlers and also the interface for
-"registering" such handlers (on_key). The dual nature is acceptable to avoid
-a confused collection of naming conventions for these related concepts.
-
-
  vim:tw=78:ts=8:sw=4:et:ft=help:norl:

runtime/doc/editing.txt

@@ -1668,29 +1668,26 @@ There are three different types of searching:
 ==============================================================================
 12. Trusted Files						*trust*
 
-Nvim has the ability to execute arbitrary code through the 'exrc' option. In
+Nvim executes arbitrary code found on the filesystem if 'exrc' is enabled. To
-order to prevent executing code from untrusted sources, Nvim has the concept of
+prevent executing malicious code, only "trusted files" are executed. You can
-"trusted files". An untrusted file will not be executed without the user's
+mark a file as trusted or untrusted using the |:trust| command or the
-consent, and a user can permanently mark a file as trusted or untrusted using
+|vim.secure.read()| function.
-the |:trust| command or the |vim.secure.read()| function.
 
 							*:trust* *E5570*
-:trust [++deny] [++remove] [{file}]
+:trust [++deny] [++remove] [file]
 
-			Manage files in the trust database. Without any options
+			Manage trusted files. Without ++ options, :trust marks
-			or arguments, :trust adds the file associated with the
+			[file] (or current buffer if no [file]) as trusted,
-			current buffer to the trust database, along with the
+			keyed on a hash of its contents. The trust list is
-			SHA256 hash of its contents.
+			stored on disk, Nvim will re-use it after restarting.
 
-			[++deny] marks the file associated with the current
+			[++deny] marks [file] (or current buffer if no [file]) as
-			buffer (or {file}, if given) as denied; no prompts will
+			untrusted: it will never be executed, 'exrc' will
-			be displayed to the user and the file will never be
+			ignore it.
-			executed.
 
-			[++remove] removes the file associated with the current
+			[++remove] removes [file] (or current buffer if no
-			buffer (or {file}, if given) from the trust database.
+			[file]) from the trust list. When the file is
-			Future attempts to read the file in a secure setting
+			discovered by 'exrc' or |vim.secure.read()|, the user
-			(i.e. with 'exrc' or |vim.secure.read()|) will prompt
+			will be asked whether to trust or deny the file.
-			the user if the file is trusted.
 
  vim:tw=78:ts=8:noet:ft=help:norl:

runtime/doc/editorconfig.txt

@@ -6,25 +6,21 @@
 
 EditorConfig integration                                        *editorconfig*
 
-Nvim natively supports EditorConfig. When a file is opened, Nvim searches
+Nvim supports EditorConfig. When a file is opened, Nvim searches all parent
-upward through all of the parent directories of that file looking for
+directories of that file for ".editorconfig" files, parses them, and applies
-".editorconfig" files. Each of these is parsed and any properties that match
+any properties that match the opened file. Think of it like 'modeline' for an
-the opened file are applied.
+entire (recursive) directory. For more information see
-
+https://editorconfig.org/.
-For more information on EditorConfig, see https://editorconfig.org/.
 
                                                *g:editorconfig* *b:editorconfig*
-EditorConfig integration can be disabled globally by adding >lua
+EditorConfig is enabled by default. To disable it, add to your config: >lua
 
     vim.g.editorconfig = false
 <
-to the user's |init.lua| file (or the Vimscript equivalent to |init.vim|). It
+(Vimscript: `let g:editorconfig = v:false`). It can also be disabled
-can also be disabled per-buffer by setting the |b:editorconfig| buffer-local
+per-buffer by setting the |b:editorconfig| buffer-local variable to `false`.
-variable to `false`.
 
-When Nvim finds a valid .editorconfig file it will store the applied
+Nvim stores the applied properties in |b:editorconfig| if it is not `false`.
-properties in the buffer variable |b:editorconfig| if it was not already set to
-`false` by the user.
 
                                                      *editorconfig-properties*
 The following properties are supported by default:
@@ -88,4 +84,4 @@ Example: >lua
       vim.b[bufnr].foo = val
     end
 <
- vim:tw=78:ts=8:noet:ft=help:norl:
+ vim:tw=78:ts=8:et:sw=4:ft=help:norl:

runtime/doc/lua-guide.txt

@@ -657,7 +657,7 @@ See also
 • |nvim_exec_autocmds()|: execute all matching autocommands
 
 ==============================================================================
-User commands                                           *lua-guide-usercommands*
+User commands                                           *lua-guide-commands*
 
 |user-commands| are custom Vim commands that call a Vimscript or Lua function.
 Just like built-in commands, they can have arguments, act on ranges, or have
@@ -665,7 +665,7 @@ custom completion of arguments. As these are most useful for plugins, we will
 cover only the basics of this advanced topic.
 
 ------------------------------------------------------------------------------
-Creating user commands                           *lua-guide-usercommands-create*
+Creating user commands                           *lua-guide-commands-create*
 
 User commands can be created through the Neovim API with
 `vim.api.`|nvim_create_user_command()|. This function takes three mandatory
@@ -734,7 +734,7 @@ the remaining arguments are the same as for |nvim_create_user_command()|:
       { nargs = 1 })
 <
 ------------------------------------------------------------------------------
-Deleting user commands                           *lua-guide-usercommands-delete*
+Deleting user commands                           *lua-guide-commands-delete*
 
 User commands can be deleted with `vim.api.`|nvim_del_user_command()|. The only
 argument is the name of the command:

runtime/doc/lua.txt

@@ -2029,7 +2029,8 @@ uri_to_fname({uri})                                       *vim.uri_to_fname()*
 Lua module: ui                                                        *lua-ui*
 
 input({opts}, {on_confirm})                                   *vim.ui.input()*
-    Prompts the user for input
+    Prompts the user for input, allowing arbitrary (potentially asynchronous)
+    work until `on_confirm`.
 
     Example: >lua
 
@@ -2054,7 +2055,8 @@ input({opts}, {on_confirm})                                   *vim.ui.input()*
                       entered), or `nil` if the user aborted the dialog.
 
 select({items}, {opts}, {on_choice})                         *vim.ui.select()*
-    Prompts the user to pick a single item from a collection of entries
+    Prompts the user to pick from a list of items, allowing arbitrary
+    (potentially asynchronous) work until `on_choice`.
 
     Example: >lua
 
@@ -2253,57 +2255,38 @@ del({modes}, {lhs}, {opts})                                 *vim.keymap.del()*
         |vim.keymap.set()|
 
 set({mode}, {lhs}, {rhs}, {opts})                           *vim.keymap.set()*
-    Add a new |mapping|. Examples: >lua
+    Adds a new |mapping|. Examples: >lua
 
-       -- Can add mapping to Lua functions
+       -- Map to a Lua function:
        vim.keymap.set('n', 'lhs', function() print("real lua function") end)
-
+       -- Map to multiple modes:
-       -- Can use it to map multiple modes
        vim.keymap.set({'n', 'v'}, '<leader>lr', vim.lsp.buf.references, { buffer=true })
-
+       -- Buffer-local mapping:
-       -- Can add mapping for specific buffer
        vim.keymap.set('n', '<leader>w', "<cmd>w<cr>", { silent = true, buffer = 5 })
-
+       -- Expr mapping:
-       -- Expr mappings
        vim.keymap.set('i', '<Tab>', function()
          return vim.fn.pumvisible() == 1 and "<C-n>" or "<Tab>"
        end, { expr = true })
-       -- <Plug> mappings
+       -- <Plug> mapping:
        vim.keymap.set('n', '[%', '<Plug>(MatchitNormalMultiBackward)')
 <
 
-    Note that in a mapping like: >lua
-
-        vim.keymap.set('n', 'asdf', require('jkl').my_fun)
-<
-
-    the `require('jkl')` gets evaluated during this call in order to access the function. If you
-    want to avoid this cost at startup you can wrap it in a function, for
-    example: >lua
-
-        vim.keymap.set('n', 'asdf', function() return require('jkl').my_fun() end)
-<
-
     Parameters: ~
-      • {mode}  string|table Same mode short names as |nvim_set_keymap()|. Can
+      • {mode}  string|table Mode short-name, see |nvim_set_keymap()|. Can
                 also be list of modes to create mapping on multiple modes.
       • {lhs}   (string) Left-hand side |{lhs}| of the mapping.
-      • {rhs}   string|function Right-hand side |{rhs}| of the mapping. Can
+      • {rhs}   string|function Right-hand side |{rhs}| of the mapping, can be
-                also be a Lua function.
+                a Lua function.
-      • {opts}  (table|nil) A table of |:map-arguments|.
+      • {opts}  (table|nil) Table of |:map-arguments|.
-                • Accepts options accepted by the {opts} parameter in
+                • Same as |nvim_set_keymap()| {opts}, except:
-                  |nvim_set_keymap()|, with the following notable differences:
+                  • "replace_keycodes" defaults to `true` if "expr" is `true`.
-                  • replace_keycodes: Defaults to `true` if "expr" is `true`.
+                  • "noremap": inverse of "remap" (see below).
-                  • noremap: Always overridden with the inverse of "remap"
-                    (see below).
 
-                • In addition to those options, the table accepts the
+                • Also accepts:
-                  following keys:
+                  • "buffer" number|boolean Creates buffer-local mapping, `0`
-                  • buffer: (number or boolean) Add a mapping to the given
+                    or `true` for current buffer.
-                    buffer. When `0` or `true`, use the current buffer.
+                  • remap: (boolean) Make the mapping recursive. Inverses
-                  • remap: (boolean) Make the mapping recursive. This is the
+                    "noremap". Defaults to `false`.
-                    inverse of the "noremap" option from |nvim_set_keymap()|.
-                    Defaults to `false`.
 
     See also: ~
         |nvim_set_keymap()|

runtime/doc/news.txt

@@ -13,7 +13,7 @@ BREAKING CHANGES                                                *news-breaking*
 
 The following changes may require adaptations in user config or plugins.
 
-• Cscope support is now removed (see |cscope| and |nvim-features-removed|):
+• Cscope support is now removed (see |cscope| and |nvim-removed|):
   - Commands removed:
     - `:cscope`
     - `:lcscope`
@@ -34,7 +34,7 @@ The following changes may require adaptations in user config or plugins.
 
   See https://github.com/neovim/neovim/pull/20545 for more information.
 
-• `:hardcopy` is now removed (see |hardcopy| and |nvim-features-removed|):
+• `:hardcopy` is now removed (see |hardcopy| and |nvim-removed|):
   - Commands removed:
     - `:hardcopy`
   - Options removed:

runtime/doc/options.txt

@@ -401,20 +401,15 @@ the system, mostly it is something like 256 or 1024 characters.
 ==============================================================================
 2. Automatically setting options			*auto-setting*
 
-Besides changing options with the ":set" command, there are three alternatives
+Besides changing options with the ":set" command, you can set options
-to set options automatically for one or more files:
+automatically in various ways:
 
-1. When starting Vim initializations are read from various places.  See
+1. With a |config| file or a |startup| argument. You can create an
-   |initialization|.  Most of them are performed for all editing sessions,
+   initialization file with |:mkvimrc|, |:mkview| and |:mksession|.
-   and some of them depend on the directory where Vim is started.
+2. |autocommand|s executed when you edit a file.
-   You can create an initialization file with |:mkvimrc|, |:mkview| and
+3. ".nvim.lua" files in the current directory, if 'exrc' is enabled.
-   |:mksession|.
+4. |editorconfig| in the current buffer's directory or ancestors.
-2. If you start editing a new file, the automatic commands are executed.
+5. 'modeline' settings found at the beginning or end of the file. See below.
-   This can be used to set options for files matching a particular pattern and
-   many other things.  See |autocommand|.
-3. If you start editing a new file, and the 'modeline' option is on, a
-   number of lines at the beginning and end of the file are checked for
-   modelines.  This is explained here.
 
 					*modeline* *vim:* *vi:* *ex:* *E520*
 There are two forms of modelines.  The first form:
@@ -2267,15 +2262,13 @@ A jump table for the options with a short description can be found at |Q_op|.
 					*'exrc'* *'ex'* *'noexrc'* *'noex'*
 'exrc' 'ex'		boolean (default off)
 			global
-	Enables the reading of .nvim.lua, .nvimrc, and .exrc files in the current
+	Automatically execute .nvim.lua, .nvimrc, and .exrc files in the
-	directory.
+	current directory, if the file is in the |trust| list. Use |:trust| to
+	manage trusted files. See also |vim.secure.read()|.
 
-	The file is only sourced if the user indicates the file is trusted. If
+	Compare 'exrc' to |editorconfig|:
-	it is, the SHA256 hash of the file contents and the full path of the
+	- 'exrc' can execute any code; editorconfig only specifies settings.
-	file are persisted to a trust database. The user is only prompted
+	- 'exrc' is Nvim-specific; editorconfig works in other editors.
-	again if the file contents change. See |vim.secure.read()|.
-
-	Use |:trust| to manage the trusted file database.
 
 	This option cannot be set from a |modeline| or in the |sandbox|, for
 	security reasons.
@@ -6199,6 +6192,8 @@ A jump table for the options with a short description can be found at |Q_op|.
 	         is a bug that denotes that new mouse button recognition was 
 	         added without modifying code that reacts on mouse clicks on 
 	         this label.
+	      Use |getmousepos()|.winid in the specified function to get the
+	      corresponding window id of the clicked item.
 	< -   Where to truncate line if too long.  Default is at the start.
 	      No width fields allowed.
 	= -   Separation point between alignment sections.  Each section will

runtime/doc/support.txt

@@ -14,12 +14,16 @@ Supported platforms					 *supported-platforms*
 `System`          `Tier`      `Versions`                  `Tested versions`
 Linux            1      >= 2.6.32, glibc >= 2.12     Ubuntu 22.04
 macOS (Intel)    1      >= 10.15                     macOS 12
-Windows 64-bit   1      >= 8                         Windows Server 2019
+Windows 64-bit   1      >= 8 (see note below)        Windows Server 2019
 FreeBSD          1      >= 10                        FreeBSD 13
 macOS (M1)       2      >= 10.15
 OpenBSD          2      >= 7
 MinGW            2      MinGW-w64
 
+Note: Windows 10 "Version 1809" or later is required for |:terminal|. To check
+your Windows version, run the "winver" command and look for "Version xxxx"
+(NOT "OS Build").
+
 Support types ~
 
 * Tier 1: Officially supported and tested with CI. Any contributed patch

runtime/doc/ui.txt

@@ -809,5 +809,8 @@ events, which the UI must handle.
 	Sent when |:messages| command is invoked. History is sent as a list of
 	entries, where each entry is a `[kind, content]` tuple.
 
+["msg_history_clear"] ~
+	Clear the |:messages| history.
+
 ==============================================================================
  vim:tw=78:ts=8:noet:ft=help:norl:

runtime/doc/vim_diff.txt

@@ -13,7 +13,7 @@ centralized reference of the differences.
 				      Type |gO| to see the table of contents.
 
 ==============================================================================
-1. Configuration					    *nvim-config*
+Configuration						    *nvim-config*
 
 - Use `$XDG_CONFIG_HOME/nvim/init.vim` instead of `.vimrc` for your |config|.
 - Use `$XDG_CONFIG_HOME/nvim` instead of `.vim` to store configuration files.
@@ -21,7 +21,7 @@ centralized reference of the differences.
   session information.  |shada|
 
 ==============================================================================
-2. Defaults					            *nvim-defaults*
+Defaults					            *nvim-defaults*
 
 - Filetype detection is enabled by default. This can be disabled by adding
   ":filetype off" to |init.vim|.
@@ -72,13 +72,14 @@ centralized reference of the differences.
 - 'wildmenu' is enabled
 - 'wildoptions' defaults to "pum,tagfile"
 
+- |editorconfig| plugin is enabled, .editorconfig settings are applied.
 - |man.lua| plugin is enabled, so |:Man| is available by default.
 - |matchit| plugin is enabled. To disable it in your config: >vim
     :let loaded_matchit = 1
 
 - |g:vimsyn_embed| defaults to "l" to enable Lua highlighting
 
-Default Mouse ~
+DEFAULT MOUSE
 						*default-mouse* *disable-mouse*
 By default the mouse is enabled, and <RightMouse> opens a |popup-menu| with
 standard actions ("Cut", "Copy", "Paste", …). Mouse is NOT enabled in
@@ -102,7 +103,7 @@ To remove the "How-to disable mouse" menu item and the separator above it: >vim
   aunmenu PopUp.How-to\ disable\ mouse
   aunmenu PopUp.-1-
 <
-Default Mappings ~
+DEFAULT MAPPINGS
 							*default-mappings*
 Nvim creates the following default mappings at |startup|. You can disable any
 of these in your config by simply removing the mapping, e.g. ":unmap Y".
@@ -115,7 +116,7 @@ of these in your config by simply removing the mapping, e.g. ":unmap Y".
 	xnoremap # y?\V<C-R>"<CR>
 	nnoremap & :&&<CR>
 <
-Default Autocommands ~
+DEFAULT AUTOCOMMANDS
 							*default-autocmds*
 Default autocommands exist in the following groups. Use ":autocmd! {group}" to
 remove them and ":autocmd {group}" to see how they're defined.
@@ -127,35 +128,36 @@ nvim_cmdwin:
 - CmdwinEnter: Limits syntax sync to maxlines=1 in the |cmdwin|.
 
 ==============================================================================
-3. New Features						       *nvim-features*
+New Features						       *nvim-features*
 
 MAJOR COMPONENTS
 
-API				|API|
+- API                             |API|
-Job control			|job-control|
+- Job control                     |job-control|
-LSP framework			|lsp|
+- LSP framework                   |lsp|
-Lua scripting			|lua|
+- Lua scripting                   |lua|
-Parsing engine			|treesitter|
+- Parsing engine                  |treesitter|
-Providers
+- Providers
-  Clipboard			|provider-clipboard|
+  - Clipboard                     |provider-clipboard|
-  Node.js plugins		|provider-nodejs|
+  - Node.js plugins               |provider-nodejs|
-  Python plugins		|provider-python|
+  - Python plugins                |provider-python|
-  Ruby plugins			|provider-ruby|
+  - Ruby plugins                  |provider-ruby|
-Remote plugins			|remote-plugin|
+- Remote plugins                  |remote-plugin|
-Shared data			|shada|
+- Shared data                     |shada|
-Terminal emulator		|terminal|
+- Terminal emulator               |terminal|
-Vimscript parser		|nvim_parse_expression()|
+- UI                              |ui| |--listen| |--server|
-XDG base directories		|xdg|
+- Vimscript parser                |nvim_parse_expression()|
+- XDG base directories            |xdg|
 
 USER EXPERIENCE
 
 Working intuitively and consistently is a major goal of Nvim.
 
 							*feature-compile*
-- Nvim always includes ALL features, in contrast to Vim (which ships with
+- Nvim always includes ALL features, in contrast to Vim (which ships various
-  various combinations of 100+ optional features). Think of it as a leaner
+  combinations of 100+ optional features).  |feature-compile| Think of it as
-  version of Vim's "HUGE" build. This reduces surface area for bugs, and
+  a leaner version of Vim's "HUGE" build. This reduces surface area for bugs,
-  removes a common source of confusion and friction for users.
+  and removes a common source of confusion and friction for users.
 
 - Nvim avoids features that cannot be provided on all platforms; instead that
   is delegated to external plugins/extensions. E.g. the `-X` platform-specific
@@ -173,6 +175,7 @@ backwards-compatibility cost. Some examples:
 
 - Directories for 'directory' and 'undodir' are auto-created.
 - Terminal features such as 'guicursor' are enabled where possible.
+- Various "nvim" |cli-arguments| were redesigned.
 
 Some features are built in that otherwise required external plugins:
 
@@ -180,6 +183,11 @@ Some features are built in that otherwise required external plugins:
 
 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.
+
 External plugins run in separate processes. |remote-plugin| This improves
 stability and allows those plugins to work without blocking the editor. Even
 "legacy" Python and Ruby plugins which use the old Vim interfaces (|if_pyth|,
@@ -191,7 +199,7 @@ by Nvim developers.
 
 FEATURES
 
-Command-line highlighting:
+Command-line:
   The expression prompt (|@=|, |c_CTRL-R_=|, |i_CTRL-R_=|) is highlighted
   using a built-in Vimscript expression parser. |expr-highlight|
 					*E5408* *E5409*
@@ -253,34 +261,105 @@ Input/Mappings:
 
 Normal commands:
   |gO| shows a filetype-defined "outline" of the current buffer.
+  |Q| replays the last recorded macro instead of switching to Ex mode (|gQ|).
 
 Options:
   'cpoptions'   flags: |cpo-_|
-  'guicursor'   works in the terminal
+  'diffopt'     "linematch" feature
+  'exrc'        searches for ".nvim.lua", ".nvimrc", or ".exrc" files. The
+                user is prompted whether to trust the file.
   'fillchars'   flags: "msgsep", "horiz", "horizup",
                 "horizdown", "vertleft", "vertright", "verthoriz"
   'foldcolumn'  supports up to 9 dynamic/fixed columns
+  'guicursor'   works in the terminal (TUI)
   'inccommand'  shows interactive results for |:substitute|-like commands
                 and |:command-preview| commands
+  'jumpoptions' "stack" behavior
+  'jumpoptions' "view" tries to restore the |mark-view| when moving through
+  the |jumplist|, |changelist|, |alternate-file| or using |mark-motions|.
   'laststatus'  global statusline support
   'mousescroll' amount to scroll by when scrolling with a mouse
   'pumblend'    pseudo-transparent popupmenu
   'scrollback'
+  'shortmess'   "F" flag does not affect output from autocommands
   'signcolumn'  supports up to 9 dynamic/fixed columns
+  'statuscolumn' full control of columns using 'statusline' format
+  'statusline'  supports unlimited alignment sections
   'tabline'     %@Func@foo%X can call any function on mouse-click
+  'ttimeout', 'ttimeoutlen' behavior was simplified
   'winblend'    pseudo-transparency in floating windows |api-floatwin|
   'winhighlight' window-local highlights
-  'diffopt'     has the option `linematch`.
+
+Providers:
+  If a Python interpreter is available on your `$PATH`, |:python| and
+  |:python3| are always available. See |provider-python|.
+
+Shell:
+  Shell output (|:!|, |:make|, …) is always routed through the UI, so it
+  cannot "mess up" the screen. (You can still use "chansend(v:stderr,…)" if
+  you want to mess up the screen :)
+
+  Nvim throttles (skips) messages from shell commands (|:!|, |:grep|, |:make|)
+  if there is too much output. No data is lost, this only affects display and
+  improves performance. |:terminal| output is never throttled.
+
+  |:!| does not support "interactive" commands. Use |:terminal| instead.
+  (GUI Vim has a similar limitation, see ":help gui-pty" in Vim.)
+
+  :!start is not special-cased on Windows.
+
+  |system()| does not support writing/reading "backgrounded" commands. |E5677|
 
 Signs:
   Signs are removed if the associated line is deleted.
 
+Startup:
+  |-e| and |-es| invoke the same "improved Ex mode" as -E and -Es.
+  |-E| and |-Es| read stdin as text (into buffer 1).
+  |-es| and |-Es| have improved behavior:
+    - Quits automatically, don't need "-c qa!".
+    - Skips swap-file dialog.
+  |-s| reads Normal commands from stdin if the script name is "-".
+  Reading text (instead of commands) from stdin |--|:
+    - works by default: "-" file is optional
+    - works in more cases: |-Es|, file args
+
+TUI:
+			*:set-termcap*
+  Start Nvim with 'verbose' level 3 to show terminal capabilities: >
+	nvim -V3
+<
+			*'term'* *E529* *E530* *E531*
+  'term' reflects the terminal type derived from |$TERM| and other environment
+  checks.  For debugging only; not reliable during startup. >vim
+	  :echo &term
+<  "builtin_x" means one of the |builtin-terms| was chosen, because the expected
+  terminfo file was not found on the system.
+
+  Nvim will use 256-colour capability on Linux virtual terminals.  Vim uses
+  only 8 colours plus bright foreground on Linux VTs.
+
+  Vim combines what is in its |builtin-terms| with what it reads from terminfo,
+  and has a 'ttybuiltin' setting to control how that combination works.  Nvim
+  uses one or the other, it does not attempt to merge the two.
+
+UI/Display:
+  |Visual| selection highlights the character at cursor. |visual-use|
+
+  messages: When showing messages longer than 'cmdheight', only
+  scroll the message lines, not the entire screen. The
+  separator line is decorated by |hl-MsgSeparator| and
+  the "msgsep" flag of 'fillchars'. *msgsep*
+
 Variables:
   |v:progpath| is always absolute ("full")
   |v:windowid| is always available (for use by external UIs)
 
+Vimscript:
+  |:redir| nested in |execute()| works.
+
 ==============================================================================
-4. Upstreamed features					 *nvim-upstreamed*
+Upstreamed features					 *nvim-upstreamed*
 
 These Nvim features were later integrated into Vim.
 
@@ -294,17 +373,9 @@ These Nvim features were later integrated into Vim.
 - 'statusline' supports unlimited alignment sections
 
 ==============================================================================
-5. Changed features					 *nvim-features-changed*
+Changed features					 *nvim-changed*
 
-Nvim always builds with all features, in contrast to Vim which may have
+This section lists various low-level details about other behavior changes.
-certain features removed/added at compile-time. |feature-compile|
-
-Some Vim features were changed in Nvim, and vice versa.
-
-If a Python interpreter is available on your `$PATH`, |:python| and |:python3|
-are always available and may be used simultaneously. See |provider-python|.
-
-|:redir| nested in |execute()| works.
 
 |mkdir()| behaviour changed:
 1. Assuming /tmp/foo does not exist and /tmp can be written to
@@ -345,7 +416,7 @@ are always available and may be used simultaneously. See |provider-python|.
 |json_encode()| behaviour slightly changed: now |msgpack-special-dict| values 
 are accepted, but |v:none| is not.
 
-Viminfo text files were replaced with binary (messagepack) ShaDa files.
+Viminfo text files were replaced with binary (messagepack) |shada| files.
 Additional differences:
 
 - |shada-c| has no effect.
@@ -387,7 +458,7 @@ Commands:
   |:wincmd| accepts a count.
   `:write!` does not show a prompt if the file was updated externally.
 
-Command line completion:
+Command-line:
   The meanings of arrow keys do not change depending on 'wildoptions'.
 
 Functions:
@@ -424,46 +495,6 @@ Mappings:
 Motion:
   The |jumplist| avoids useless/phantom jumps.
 
-Normal commands:
-  |Q| replays the last recorded macro instead of switching to Ex mode.
-  Instead |gQ| can be used to enter Ex mode.
-
-Options:
-  'ttimeout', 'ttimeoutlen' behavior was simplified
-  'jumpoptions' "stack" behavior
-  'jumpoptions' "view" tries to restore the |mark-view| when moving through
-  the |jumplist|, |changelist|, |alternate-file| or using |mark-motions|.
-  'shortmess' the "F" flag does not affect output from autocommands
-  'exrc' searches for ".nvim.lua", ".nvimrc", or ".exrc" files. The user is
-  prompted whether to trust the file.
-
-Shell:
-  Shell output (|:!|, |:make|, …) is always routed through the UI, so it
-  cannot "mess up" the screen. (You can still use "chansend(v:stderr,…)" if
-  you want to mess up the screen :)
-
-  Nvim throttles (skips) messages from shell commands (|:!|, |:grep|, |:make|)
-  if there is too much output. No data is lost, this only affects display and
-  improves performance. |:terminal| output is never throttled.
-
-  |:!| does not support "interactive" commands. Use |:terminal| instead.
-  (GUI Vim has a similar limitation, see ":help gui-pty" in Vim.)
-
-  :!start is not special-cased on Windows.
-
-  |system()| does not support writing/reading "backgrounded" commands. |E5677|
-
-Startup:
-  |-e| and |-es| invoke the same "improved Ex mode" as -E and -Es.
-  |-E| and |-Es| read stdin as text (into buffer 1).
-  |-es| and |-Es| have improved behavior:
-    - Quits automatically, don't need "-c qa!".
-    - Skips swap-file dialog.
-  |-s| reads Normal commands from stdin if the script name is "-".
-  Reading text (instead of commands) from stdin |--|:
-    - works by default: "-" file is optional
-    - works in more cases: |-Es|, file args
-
 Syntax highlighting:
   syncolor.vim has been removed. Nvim now sets up default highlighting groups
   automatically for both light and dark backgrounds, regardless of whether or
@@ -472,40 +503,13 @@ Syntax highlighting:
   after/syntax/syncolor.vim file should transition that file into a
   colorscheme. |:colorscheme|
 
-TUI:
-			*:set-termcap*
-  Start Nvim with 'verbose' level 3 to show terminal capabilities: >
-	nvim -V3
-<
-			*'term'* *E529* *E530* *E531*
-  'term' reflects the terminal type derived from |$TERM| and other environment
-  checks.  For debugging only; not reliable during startup. >vim
-	  :echo &term
-<  "builtin_x" means one of the |builtin-terms| was chosen, because the expected
-  terminfo file was not found on the system.
-
-  Nvim will use 256-colour capability on Linux virtual terminals.  Vim uses
-  only 8 colours plus bright foreground on Linux VTs.
-
-  Vim combines what is in its |builtin-terms| with what it reads from terminfo,
-  and has a 'ttybuiltin' setting to control how that combination works.  Nvim
-  uses one or the other, it does not attempt to merge the two.
-
-UI/Display:
-  |Visual| selection highlights the character at cursor. |visual-use|
-
-  messages: When showing messages longer than 'cmdheight', only
-  scroll the message lines, not the entire screen. The
-  separator line is decorated by |hl-MsgSeparator| and
-  the "msgsep" flag of 'fillchars'. *msgsep*
-
 Vimscript compatibility:
   `count` does not alias to |v:count|
   `errmsg` does not alias to |v:errmsg|
   `shell_error` does not alias to |v:shell_error|
   `this_session` does not alias to |v:this_session|
 
-Working directory (Vim implemented some of these later than Nvim):
+Working directory (Vim implemented some of these after Nvim):
 - |DirChanged| and |DirChangedPre| can be triggered when switching to another
   window or tab.
 - |getcwd()| and |haslocaldir()| may throw errors if the tab page or window
@@ -516,20 +520,15 @@ Working directory (Vim implemented some of these later than Nvim):
   working directory. Use `getcwd(-1, -1)` to get the global working directory.
 
 ==============================================================================
-6. Missing legacy features				 *nvim-features-missing*
+Missing legacy features					 *nvim-missing*
 
-Some legacy Vim features are not yet implemented:
+These legacy Vim features are not yet implemented:
-
-- *if_lua* : Nvim |Lua| API is not compatible with Vim's "if_lua"
-- *if_mzscheme*
-- |if_pyth|: *python-bindeval* *python-Function* are not supported
-- *if_tcl*
 
 *:gui*
 *:gvim*
 
 ==============================================================================
-7. Removed features					 *nvim-features-removed*
+Removed legacy features					 *nvim-removed*
 
 These Vim features were intentionally removed from Nvim.
 
@@ -687,6 +686,13 @@ Options:
 Performance:
   Folds are not updated during insert-mode.
 
+Providers:
+
+- *if_lua* : Nvim |Lua| API is not compatible with Vim's "if_lua".
+- *if_mzscheme*
+- |if_pyth|: *python-bindeval* *python-Function* are not supported.
+- *if_tcl*
+
 Startup:
   --literal (file args are always literal; to expand wildcards on Windows, use
     |:n| e.g. `nvim +"n *"`)

runtime/lua/vim/keymap.lua

@@ -1,51 +1,35 @@
 local keymap = {}
 
---- Add a new |mapping|.
+--- Adds a new |mapping|.
 --- Examples:
 --- <pre>lua
----   -- Can add mapping to Lua functions
+---   -- Map to a Lua function:
 ---   vim.keymap.set('n', 'lhs', function() print("real lua function") end)
----
+---   -- Map to multiple modes:
----   -- Can use it to map multiple modes
 ---   vim.keymap.set({'n', 'v'}, '<leader>lr', vim.lsp.buf.references, { buffer=true })
----
+---   -- Buffer-local mapping:
----   -- Can add mapping for specific buffer
 ---   vim.keymap.set('n', '<leader>w', "<cmd>w<cr>", { silent = true, buffer = 5 })
----
+---   -- Expr mapping:
----   -- Expr mappings
 ---   vim.keymap.set('i', '<Tab>', function()
 ---     return vim.fn.pumvisible() == 1 and "<C-n>" or "<Tab>"
 ---   end, { expr = true })
----   -- <Plug> mappings
+---   -- <Plug> mapping:
 ---   vim.keymap.set('n', '[%%', '<Plug>(MatchitNormalMultiBackward)')
 --- </pre>
 ---
---- Note that in a mapping like:
+---@param mode string|table    Mode short-name, see |nvim_set_keymap()|.
---- <pre>lua
----    vim.keymap.set('n', 'asdf', require('jkl').my_fun)
---- </pre>
----
---- the ``require('jkl')`` gets evaluated during this call in order to access the function.
---- If you want to avoid this cost at startup you can wrap it in a function, for example:
---- <pre>lua
----    vim.keymap.set('n', 'asdf', function() return require('jkl').my_fun() end)
---- </pre>
----
----@param mode string|table    Same mode short names as |nvim_set_keymap()|.
 ---                            Can also be list of modes to create mapping on multiple modes.
 ---@param lhs string           Left-hand side |{lhs}| of the mapping.
----@param rhs string|function  Right-hand side |{rhs}| of the mapping. Can also be a Lua function.
+---@param rhs string|function  Right-hand side |{rhs}| of the mapping, can be a Lua function.
---
+---
----@param opts table|nil A table of |:map-arguments|.
+---@param opts table|nil Table of |:map-arguments|.
----                      + Accepts options accepted by the {opts} parameter in |nvim_set_keymap()|,
+---                      - Same as |nvim_set_keymap()| {opts}, except:
----                        with the following notable differences:
+---                        - "replace_keycodes" defaults to `true` if "expr" is `true`.
----                        - replace_keycodes: Defaults to `true` if "expr" is `true`.
+---                        - "noremap": inverse of "remap" (see below).
----                        - noremap: Always overridden with the inverse of "remap" (see below).
+---                      - Also accepts:
----                      + In addition to those options, the table accepts the following keys:
+---                        - "buffer" number|boolean Creates buffer-local mapping, `0` or `true`
----                        - buffer: (number or boolean) Add a mapping to the given buffer.
+---                        for current buffer.
----                        When `0` or `true`, use the current buffer.
+---                        - remap: (boolean) Make the mapping recursive. Inverses "noremap".
----                        - remap: (boolean) Make the mapping recursive.
----                        This is the inverse of the "noremap" option from |nvim_set_keymap()|.
 ---                        Defaults to `false`.
 ---@see |nvim_set_keymap()|
 function keymap.set(mode, lhs, rhs, opts)

runtime/lua/vim/ui.lua

@@ -1,6 +1,7 @@
 local M = {}
 
---- Prompts the user to pick a single item from a collection of entries
+--- Prompts the user to pick from a list of items, allowing arbitrary (potentially asynchronous)
+--- work until `on_choice`.
 ---
 ---@param items table Arbitrary items
 ---@param opts table Additional options
@@ -35,7 +36,6 @@ local M = {}
 ---     end
 --- end)
 --- </pre>
-
 function M.select(items, opts, on_choice)
   vim.validate({
     items = { items, 'table', false },
@@ -55,7 +55,8 @@ function M.select(items, opts, on_choice)
   end
 end
 
---- Prompts the user for input
+--- Prompts the user for input, allowing arbitrary (potentially asynchronous) work until
+--- `on_confirm`.
 ---
 ---@param opts table Additional options. See |input()|
 ---     - prompt (string|nil)

src/nvim/README.md

@@ -81,6 +81,13 @@ Logs will be written to `${HOME}/logs/*san.PID` then.
 
 For more information: https://github.com/google/sanitizers/wiki/SanitizerCommonFlags
 
+Reproducible build
+------------------
+
+To make a reproducible build of Nvim, set cmake variable `LUA_GEN_PRG` to
+a LuaJIT binary built with `LUAJIT_SECURITY_PRN=0`. See commit
+cb757f2663e6950e655c6306d713338dfa66b18d.
+
 Debug: Performance
 ------------------
 

src/nvim/api/command.c

@@ -899,15 +899,13 @@ static void build_cmdline_str(char **cmdlinep, exarg_T *eap, CmdParseInfo *cmdin
   }
 }
 
-/// Create a new user command |user-commands|
+/// Creates a global |user-commands| command.
 ///
-/// {name} is the name of the new command. The name must begin with an uppercase letter.
+/// For Lua usage see |lua-guide-commands-create|.
-///
-/// {command} is the replacement text or Lua function to execute.
 ///
 /// Example:
 /// <pre>vim
-///    :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {})
+///    :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {'bang': v:true})
 ///    :SayHello
 ///    Hello world!
 /// </pre>
@@ -929,11 +927,12 @@ static void build_cmdline_str(char **cmdlinep, exarg_T *eap, CmdParseInfo *cmdin
 ///                 - mods: (string) Command modifiers, if any |<mods>|
 ///                 - smods: (table) Command modifiers in a structured format. Has the same
 ///                 structure as the "mods" key of |nvim_parse_cmd()|.
-/// @param  opts    Optional command attributes. See |command-attributes| for more details. To use
+/// @param  opts    Optional |command-attributes|.
-///                 boolean attributes (such as |:command-bang| or |:command-bar|) set the value to
+///                 - Set boolean attributes such as |:command-bang| or |:command-bar| to true (but
-///                 "true". In addition to the string options listed in |:command-complete|, the
+///                   not |:command-buffer|, use |nvim_buf_create_user_command()| instead).
-///                 "complete" key also accepts a Lua function which works like the "customlist"
+///                 - "complete" |:command-complete| also accepts a Lua function which works like
-///                 completion mode |:command-completion-customlist|. Additional parameters:
+///                   |:command-completion-customlist|.
+///                 - Other parameters:
 ///                   - desc: (string) Used for listing the command when a Lua function is used for
 ///                                    {command}.
 ///                   - force: (boolean, default true) Override any previous definition.
@@ -955,7 +954,7 @@ void nvim_del_user_command(String name, Error *err)
   nvim_buf_del_user_command(-1, name, err);
 }
 
-/// Create a new user command |user-commands| in the given buffer.
+/// Creates a buffer-local command |user-commands|.
 ///
 /// @param  buffer  Buffer handle, or 0 for current buffer.
 /// @param[out] err Error details, if any.

src/nvim/api/vim.c

@@ -1442,15 +1442,14 @@ ArrayOf(Dictionary) nvim_get_keymap(String mode)
 ///               or "!" for |:map!|, or empty string for |:map|.
 /// @param  lhs   Left-hand-side |{lhs}| of the mapping.
 /// @param  rhs   Right-hand-side |{rhs}| of the mapping.
-/// @param  opts  Optional parameters map: keys are |:map-arguments|, values are booleans (default
+/// @param  opts  Optional parameters map: Accepts all |:map-arguments| as keys except |<buffer>|,
-///               false). Accepts all |:map-arguments| as keys excluding |<buffer>| but including
+///               values are booleans (default false). Also:
-///               |:noremap| and "desc". Unknown key is an error.
+///               - "noremap" non-recursive mapping |:noremap|
-///               "desc" can be used to give a description to the mapping.
+///               - "desc" human-readable description.
-///               When called from Lua, also accepts a "callback" key that takes a Lua function to
+///               - "callback" Lua function called when the mapping is executed.
-///               call when the mapping is executed.
+///               - "replace_keycodes" (boolean) When "expr" is true, replace keycodes in the
-///               When "expr" is true, "replace_keycodes" (boolean) can be used to replace keycodes
+///                 resulting string (see |nvim_replace_termcodes()|). Returning nil from the Lua
-///               in the resulting string (see |nvim_replace_termcodes()|), and a Lua callback
+///                 "callback" is equivalent to returning an empty string.
-///               returning `nil` is equivalent to returning an empty string.
 /// @param[out]   err   Error details, if any.
 void nvim_set_keymap(uint64_t channel_id, String mode, String lhs, String rhs, Dict(keymap) *opts,
                      Error *err)