docs: misc (#28837)

Co-authored-by: Danymat <d.danymat@gmail.com>
Co-authored-by: Gregory Anders <greg@gpanders.com>
Co-authored-by: Jakub Okoński <jakub@okonski.org>
Co-authored-by: John L. Villalovos <john@sodarock.com>
Co-authored-by: Maria José Solano <majosolano99@gmail.com>
Co-authored-by: Michaili K <git@michaili.dev>
Co-authored-by: TheLeoP <eugenio2305@hotmail.com>
Co-authored-by: Tobias Schmitz <tobiasschmitz2001@gmail.com>
Co-authored-by: W20MC <157727813+W20MC@users.noreply.github.com>
Co-authored-by: Will Hopkins <willothyh@gmail.com>
Co-authored-by: Yifan Hu <141280278+b0ae989c@users.noreply.github.com>
Co-authored-by: glepnir <glephunter@gmail.com>
Co-authored-by: prljav <74116121+prljav@users.noreply.github.com>

.mailmap

@@ -18,6 +18,7 @@ Eisuke Kawashima <e-kwsm@users.noreply.github.com> E Kawashima
 ElPiloto <luis.r.piloto@gmail.com> Luis Piloto
 Eliseo Martínez <eliseomarmol@gmail.com> Eliseo Martínez
 Fabian Viöl <f.vioel@googlemail.com> Fabian
+Famiu Haque <famiuhaque@proton.me> <famiuhaque@protonmail.com>
 Florian Walch <florian@fwalch.com> <fwalch@users.noreply.github.com>
 Gabriel Cruz <gabs.oficial98@gmail.com> <LTKills@users.noreply.github.com>
 Gaelan Steele <gbs@canishe.com> Gaelan

BUILD.md

@@ -84,7 +84,7 @@ make deps
       - Right-click _CMakeLists.txt → Delete Cache_.
       - Right-click _CMakeLists.txt → Generate Cache_.
     - If you see an "access violation" from `ntdll`, you can ignore it and continue.
-4. If you set an error like `msgpackc.dll not found`, try the `nvim.exe (Install)` target. Then switch back to `nvim.exe (bin\nvim.exe)`.
+4. If you see an error like `msgpackc.dll not found`, try the `nvim.exe (Install)` target. Then switch back to `nvim.exe (bin\nvim.exe)`.
 
 ### Windows / MSVC PowerShell
 
@@ -365,13 +365,16 @@ and replacing `neovim-unwrapped` with `neovim-dev`:
 nix-shell '<nixpkgs>' -A neovim-dev
 ```
 
-Neovim contains a Nix flake in the `contrib` folder, with 3 packages:
+A flake for Neovim is hosted at [nix-community/neovim-nightly-overlay](https://github.com/nix-community/neovim-nightly-overlay/), with 3 packages:
 - `neovim` to run the nightly
 - `neovim-debug` to run the package with debug symbols
 - `neovim-developer` to get all the tools to develop on `neovim`
 
-Thus you can run Neovim nightly with `nix run github:neovim/neovim?dir=contrib`.
+Thus you can run Neovim nightly with `nix run github:nix-community/neovim-nightly-overlay`.
-Similarly to develop on Neovim: `nix develop github:neovim/neovim?dir=contrib#neovim-developer`.
+Similarly to develop on Neovim: `nix run github:nix-community/neovim-nightly-overlay#neovim-developer`.
+
+To use a specific version of Neovim, you can pass `--override-input neovim-src .` to use your current directory,
+or a specific SHA1 like `--override-input neovim-src github:neovim/neovim/89dc8f8f4e754e70cbe1624f030fb61bded41bc2`.
 
 ### FreeBSD
 

CONTRIBUTING.md

@@ -42,10 +42,10 @@ Developer guidelines
   make distclean
   make  # Nvim build system uses ninja automatically, if available.
   ```
-- Install `ccache` for faster rebuilds of Nvim. Nvim will use it automatically
+- Install `ccache` or `sccache` for faster rebuilds of Nvim. Nvim will use one
-  if it's found. To disable caching use:
+  of these automatically if it's found. To disable caching use:
   ```bash
-  CCACHE_DISABLE=true make
+  cmake -B build -D CACHE_PRG=OFF
   ```
 
 Pull requests (PRs)

INSTALL.md

@@ -112,7 +112,7 @@ sudo rm -rf /opt/nvim
 sudo tar -C /opt -xzf nvim-linux64.tar.gz
 ```
 
-After this step add this to `~/.bashrc`:
+Then add this to your shell config (`~/.bashrc`, `~/. zshrc`, ...):
 
     export PATH="$PATH:/opt/nvim-linux64/bin"
 
@@ -129,7 +129,7 @@ To expose nvim globally:
     mkdir -p /opt/nvim
     mv nvim.appimage /opt/nvim/nvim
 
-And the following line to `~/.bashrc`:
+And the following line to your shell config (`~/.bashrc`, `~/. zshrc`, ...):
 
     export PATH="$PATH:/opt/nvim/"
 
@@ -204,7 +204,7 @@ You can also get nightly builds of git master from the [Copr automated build sys
     dnf copr enable agriffis/neovim-nightly
     dnf install -y neovim python3-neovim
 
-See the [blog post](https://arongriffis.com/2019/03/02/neovim-nightly-builds) for information on how these are built.
+See the [blog post](https://arongriffis.com/2019-03-02-neovim-nightly-builds) for information on how these are built.
 
 ### Flatpak
 

runtime/doc/api.txt

@@ -2138,14 +2138,14 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts})           *nvim_buf_attach()*
       • |api-buffer-updates-lua|
 
 nvim_buf_call({buffer}, {fun})                               *nvim_buf_call()*
-    call a function with buffer as temporary current buffer
+    Call a function with buffer as temporary current buffer.
 
     This temporarily switches current buffer to "buffer". If the current
-    window already shows "buffer", the window is not switched If a window
+    window already shows "buffer", the window is not switched. If a window
-    inside the current tabpage (including a float) already shows the buffer
+    inside the current tabpage (including a float) already shows the buffer,
-    One of these windows will be set as current window temporarily. Otherwise
+    then one of these windows will be set as current window temporarily.
-    a temporary scratch window (called the "autocmd window" for historical
+    Otherwise a temporary scratch window (called the "autocmd window" for
-    reasons) will be used.
+    historical reasons) will be used.
 
     This is useful e.g. to call Vimscript functions that only work with the
     current buffer/window currently, like |termopen()|.
@@ -2831,7 +2831,7 @@ nvim_set_decoration_provider({ns_id}, {opts})
                     ["buf", bufnr, tick]
 <
                  • on_win: called when starting to redraw a specific window. >
-                    ["win", winid, bufnr, topline, botline]
+                    ["win", winid, bufnr, toprow, botrow]
 <
                  • on_line: called for each buffer line being redrawn. (The
                    interaction with fold lines is subject to change) >

runtime/doc/diagnostic.txt

@@ -516,10 +516,11 @@ Lua module: vim.diagnostic                                    *diagnostic-api*
 *vim.diagnostic.Opts.Jump*
 
     Fields: ~
-      • {float}?     (`boolean|vim.diagnostic.Opts.Float`) Default value of
+      • {float}?     (`boolean|vim.diagnostic.Opts.Float`, default: false)
-                     the {float} parameter of |vim.diagnostic.jump()|.
+                     Default value of the {float} parameter of
-      • {wrap}?      (`boolean`) Default value of the {wrap} parameter of
                      |vim.diagnostic.jump()|.
+      • {wrap}?      (`boolean`, default: true) Default value of the {wrap}
+                     parameter of |vim.diagnostic.jump()|.
       • {severity}?  (`vim.diagnostic.SeverityFilter`) Default value of the
                      {severity} parameter of |vim.diagnostic.jump()|.
 

runtime/doc/gui.txt

@@ -221,7 +221,7 @@ is right aligned, and the "O" is underlined, to indicate it is the shortcut.
 
 					*:am*  *:amenu*  *:an*      *:anoremenu*
 The ":amenu" command can be used to define menu entries for all modes at once,
-expect for Terminal mode.  To make the command work correctly, a character is
+except for Terminal mode.  To make the command work correctly, a character is
 automatically inserted for some modes:
 	mode		inserted	appended	~
 	Normal		nothing		nothing

runtime/doc/lsp.txt

@@ -514,10 +514,10 @@ LspAttach                                                          *LspAttach*
       callback = function(args)
         local bufnr = args.buf
         local client = vim.lsp.get_client_by_id(args.data.client_id)
-        if client.server_capabilities.completionProvider then
+        if client.supports_method("textDocument/completion") then
           vim.bo[bufnr].omnifunc = "v:lua.vim.lsp.omnifunc"
         end
-        if client.server_capabilities.definitionProvider then
+        if client.supports_method("textDocument/definition") then
           vim.bo[bufnr].tagfunc = "v:lua.vim.lsp.tagfunc"
         end
       end,
@@ -874,13 +874,13 @@ start({config}, {opts})                                      *vim.lsp.start()*
       • {config}  (`vim.lsp.ClientConfig`) Configuration for the server. See
                   |vim.lsp.ClientConfig|.
       • {opts}    (`table?`) Optional keyword arguments
-                  • {reuse_client}
+                  • {reuse_client}?
                     (`fun(client: vim.lsp.Client, config: vim.lsp.ClientConfig): boolean`)
                     Predicate used to decide if a client should be re-used.
                     Used on all running clients. The default implementation
                     re-uses a client if name and root_dir matches.
-                  • {bufnr} (`integer`) Buffer handle to attach to if starting
+                  • {bufnr}? (`integer`) Buffer handle to attach to if
-                    or re-using a client (0 for current).
+                    starting or re-using a client (0 for current).
                   • {silent}? (`boolean`) Suppress error reporting if the LSP
                     server fails to start (default false).
 

runtime/doc/lua-guide.txt

@@ -225,7 +225,6 @@ Vimscript are automatically converted:
     end
 
     vim.fn.jobstart('ls', { on_stdout = print_stdout })
-    print(vim.fn.printf('Hello from %s', 'Lua'))
 <
 This works for both |builtin-functions| and |user-function|s.
 

runtime/doc/map.txt

@@ -1381,7 +1381,6 @@ completion can be enabled:
 	-complete=arglist	file names in argument list
 	-complete=augroup	autocmd groups
 	-complete=buffer	buffer names
-	-complete=behave	:behave suboptions
 	-complete=color		color schemes
 	-complete=command	Ex command (and arguments)
 	-complete=compiler	compilers

runtime/doc/quickref.txt

@@ -898,6 +898,7 @@ Short explanation of each option:		*option-list*
 'tagstack'	  'tgst'    push tags onto the tag stack
 'term'			    name of the terminal
 'termbidi'	  'tbidi'   terminal takes care of bi-directionality
+'termguicolors'	  'tgc'     enable 24-bit RGB color in the TUI
 'textwidth'	  'tw'	    maximum width of text that is being inserted
 'thesaurus'	  'tsr'     list of thesaurus files for keyword completion
 'thesaurusfunc'	  'tsrfu'   function to be used for thesaurus completion

runtime/doc/sign.txt

@@ -67,15 +67,12 @@ sign group allows Vim plugins to use unique signs without interfering with
 other plugins using signs.
 
 							*sign-priority*
-Each placed sign is assigned a priority value. When multiple signs are placed
+Each placed sign is assigned a priority value independently of the sign group.
-on the same line, the attributes of the sign with the highest priority is used
+The default priority for a sign is 10. When multiple signs that each have an
-independently of the sign group. The default priority for a sign is 10. The
+icon or text are placed on the same line, signs are ordered with decreasing
-priority is assigned at the time of placing a sign.
+priority from left to right, up until the maximum width set in 'signcolumn'.
-
+Lower priority signs that do not fit are hidden. Highest priority signs with
-When multiple signs that each have an icon or text are present, signs are
+highlight attributes are always shown.
-ordered with increasing priority from left to right, up until the maximum
-width set in 'signcolumn'. Lower priority signs that do not fit are hidden.
-Highest priority signs with highlight attributes are always shown.
 
 When the line on which the sign is placed is deleted, the sign is removed along
 with it.

runtime/lua/vim/_editor.lua

@@ -608,10 +608,9 @@ end
 
 --- Displays a notification to the user.
 ---
---- This function can be overridden by plugins to display notifications using a
+--- This function can be overridden by plugins to display notifications using
---- custom provider (such as the system notification provider). By default,
+--- a custom provider (such as the system notification provider). By default,
 --- writes to |:messages|.
----
 ---@param msg string Content of the notification to show to the user.
 ---@param level integer|nil One of the values from |vim.log.levels|.
 ---@param opts table|nil Optional parameters. Unused by default.

runtime/lua/vim/_meta/api.lua

@@ -276,14 +276,14 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start
 --- @return boolean
 function vim.api.nvim_buf_attach(buffer, send_buffer, opts) end
 
---- call a function with buffer as temporary current buffer
+--- Call a function with buffer as temporary current buffer.
 ---
 --- This temporarily switches current buffer to "buffer". If the current
---- window already shows "buffer", the window is not switched If a window
+--- window already shows "buffer", the window is not switched. If a window
---- inside the current tabpage (including a float) already shows the buffer
+--- inside the current tabpage (including a float) already shows the buffer,
---- One of these windows will be set as current window temporarily. Otherwise
+--- then one of these windows will be set as current window temporarily.
---- a temporary scratch window (called the "autocmd window" for historical
+--- Otherwise a temporary scratch window (called the "autocmd window" for
---- reasons) will be used.
+--- historical reasons) will be used.
 ---
 --- This is useful e.g. to call Vimscript functions that only work with the
 --- current buffer/window currently, like `termopen()`.
@@ -1953,7 +1953,7 @@ function vim.api.nvim_set_current_win(window) end
 ---
 ---             • on_win: called when starting to redraw a specific window.
 --- ```
----                ["win", winid, bufnr, topline, botline]
+---                ["win", winid, bufnr, toprow, botrow]
 --- ```
 ---
 ---             • on_line: called for each buffer line being redrawn. (The

runtime/lua/vim/_options.lua

@@ -95,7 +95,6 @@
 local api = vim.api
 
 -- TODO(tjdevries): Improve option metadata so that this doesn't have to be hardcoded.
---                  Can be done in a separate PR.
 local key_value_options = {
   fillchars = true,
   fcs = true,

runtime/lua/vim/diagnostic.lua

@@ -247,9 +247,11 @@ local M = {}
 --- @class vim.diagnostic.Opts.Jump
 ---
 --- Default value of the {float} parameter of |vim.diagnostic.jump()|.
+--- (default: false)
 --- @field float? boolean|vim.diagnostic.Opts.Float
 ---
 --- Default value of the {wrap} parameter of |vim.diagnostic.jump()|.
+--- (default: true)
 --- @field wrap? boolean
 ---
 --- Default value of the {severity} parameter of |vim.diagnostic.jump()|.

runtime/lua/vim/lsp.lua

@@ -201,10 +201,10 @@ end
 --- Predicate used to decide if a client should be re-used. Used on all
 --- running clients. The default implementation re-uses a client if name and
 --- root_dir matches.
---- @field reuse_client fun(client: vim.lsp.Client, config: vim.lsp.ClientConfig): boolean
+--- @field reuse_client? fun(client: vim.lsp.Client, config: vim.lsp.ClientConfig): boolean
 ---
 --- Buffer handle to attach to if starting or re-using a client (0 for current).
---- @field bufnr integer
+--- @field bufnr? integer
 ---
 --- Suppress error reporting if the LSP server fails to start (default false).
 --- @field silent? boolean

runtime/tutor/en/vim-01-beginner.tutor

@@ -888,7 +888,7 @@ NOTE: If you want to ignore case for just one search command, use [\c](/\c)
 
 Neovim has a comprehensive online help system.
 
-To get started, try one of these three:
+To get started, try one of these two:
 
   - press the `<F1>`{normal} key (if you have one)
   - type `:help`{vim}

src/man/nvim.1

@@ -387,10 +387,10 @@ features like
 .El
 .Sh FILES
 .Bl -tag -width "~/.config/nvim/init.vim"
-.It Pa ~/.config/nvim/init.vim
+.It Pa ~/.config/nvim/init.lua
 User-local
 .Nm
-configuration file.
+Lua configuration file.
 .It Pa ~/.config/nvim
 User-local
 .Nm

src/nvim/api/buffer.c

@@ -1183,12 +1183,12 @@ ArrayOf(Integer, 2) nvim_buf_get_mark(Buffer buffer, String name, Arena *arena,
   return rv;
 }
 
-/// call a function with buffer as temporary current buffer
+/// Call a function with buffer as temporary current buffer.
 ///
 /// This temporarily switches current buffer to "buffer".
-/// If the current window already shows "buffer", the window is not switched
+/// If the current window already shows "buffer", the window is not switched.
 /// If a window inside the current tabpage (including a float) already shows the
-/// buffer One of these windows will be set as current window temporarily.
+/// buffer, then one of these windows will be set as current window temporarily.
 /// Otherwise a temporary scratch window (called the "autocmd window" for
 /// historical reasons) will be used.
 ///

src/nvim/api/extmark.c

@@ -1038,7 +1038,7 @@ void nvim_buf_clear_namespace(Buffer buffer, Integer ns_id, Integer line_start,
 ///               ```
 ///             - on_win: called when starting to redraw a specific window.
 ///               ```
-///                 ["win", winid, bufnr, topline, botline]
+///                 ["win", winid, bufnr, toprow, botrow]
 ///               ```
 ///             - on_line: called for each buffer line being redrawn.
 ///                 (The interaction with fold lines is subject to change)