docs: misc, help tags for neovim.io searches #31428

Problem:
Various keywords are commonly searched-for on https://neovim.io, but
don't have help tags.

Solution:
Add help tags.

fix #31327

16 files changed, 115 insertions, 52 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index c5dabeb551..9cb8f72348 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -1114,7 +1114,7 @@ nvim_open_term({buffer}, {opts})                            *nvim_open_term()*
     Open a terminal instance in a buffer
 
     By default (and currently the only option) the terminal will not be
-    connected to an external process. Instead, input send on the channel will
+    connected to an external process. Instead, input sent on the channel will
     be echoed directly by the terminal. This is useful to display ANSI
     terminal sequences returned as part of a rpc message, or similar.
 
@@ -1125,6 +1125,17 @@ nvim_open_term({buffer}, {opts})                            *nvim_open_term()*
     |nvim_chan_send()| can be called immediately to process sequences in a
     virtual terminal having the intended size.
 
+    Example: this `TermHl` command can be used to display and highlight raw
+    ANSI termcodes, so you can use Nvim as a "scrollback pager" (for terminals
+    like kitty):                                   *terminal-scrollback-pager* >lua
+        vim.api.nvim_create_user_command('TermHl', function()
+          local b = vim.api.nvim_create_buf(false, true)
+          local chan = vim.api.nvim_open_term(b, {})
+          vim.api.nvim_chan_send(chan, table.concat(vim.api.nvim_buf_get_lines(0, 0, -1, false), '\n'))
+          vim.api.nvim_win_set_buf(0, b)
+        end, { desc = 'Highlights ANSI termcodes in curbuf' })
+<
+
     Attributes: ~
         not allowed when |textlock| is active
 
diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 585db21a0b..304e63fd95 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -5443,7 +5443,7 @@ jobwait({jobs} [, {timeout}])                                        *jobwait()*
                   • {timeout} (`integer?`)
 
                 Return: ~
-                  (`any`)
+                  (`integer[]`)
 
 join({list} [, {sep}])                                                  *join()*
 		Join the items in {list} together into one String.
@@ -7986,7 +7986,7 @@ rpcnotify({channel}, {event} [, {args}...])                        *rpcnotify()*
                 Parameters: ~
                   • {channel} (`integer`)
                   • {event} (`string`)
-                  • {args} (`any?`)
+                  • {...} (`any`)
 
                 Return: ~
                   (`any`)
@@ -8001,7 +8001,7 @@ rpcrequest({channel}, {method} [, {args}...])                     *rpcrequest()*
                 Parameters: ~
                   • {channel} (`integer`)
                   • {method} (`string`)
-                  • {args} (`any?`)
+                  • {...} (`any`)
 
                 Return: ~
                   (`any`)
@@ -10234,6 +10234,7 @@ str2list({string} [, {utf8}])                                       *str2list()*
 		and exists only for backwards-compatibility.
 		With UTF-8 composing characters are handled properly: >vim
 			echo str2list("á")		" returns [97, 769]
+<
 
                 Parameters: ~
                   • {string} (`string`)
@@ -11991,7 +11992,7 @@ winlayout([{tabnr}])                                               *winlayout()*
                   • {tabnr} (`integer?`)
 
                 Return: ~
-                  (`any`)
+                  (`any[]`)
 
 winline()                                                            *winline()*
 		The result is a Number, which is the screen line of the cursor
diff --git a/runtime/doc/dev_arch.txt b/runtime/doc/dev_arch.txt
index 1cb3b9ad67..2be6221117 100644
--- a/runtime/doc/dev_arch.txt
+++ b/runtime/doc/dev_arch.txt
@@ -46,11 +46,11 @@ Remember to bump NVIM_API_LEVEL if it wasn't already during this development
 cycle.
 
 Other references:
-* |msgpack-rpc|
-* |ui|
-* https://github.com/neovim/neovim/pull/3246
-* https://github.com/neovim/neovim/pull/18375
-* https://github.com/neovim/neovim/pull/21605
+- |msgpack-rpc|
+- |ui|
+- https://github.com/neovim/neovim/pull/3246
+- https://github.com/neovim/neovim/pull/18375
+- https://github.com/neovim/neovim/pull/21605
 
 
 
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index a61c569a67..da64475465 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -300,7 +300,7 @@ vim.paste in runtime/lua/vim/_editor.lua like this: >
     --- @returns false if client should cancel the paste.
 
 
-LUA STDLIB DESIGN GUIDELINES                            *dev-lua*
+STDLIB DESIGN GUIDELINES                                             *dev-lua*
 
 See also |dev-naming|.
 
@@ -337,7 +337,7 @@ preference):
     way. Advantage is that propagation happens for free and it's harder to
     accidentally swallow errors. (E.g. using
     `uv_handle/pipe:write()` without checking return values is common.)
-4. `on_error` parameter
+4. `on_error` callback
   - For async and "visitors" traversing a graph, where many errors may be
     collected while work continues.
 5. `vim.notify` (sometimes with optional `opts.silent` (async, visitors ^))
@@ -434,7 +434,9 @@ Use existing common {verb} names (actions) if possible:
     - eval:         Evaluates an expression
     - exec:         Executes code, may return a result
     - fmt:          Formats
-    - get:          Gets things (often by a query)
+    - get:          Gets things. Two variants (overloads):
+                    1. `get<T>(id: int): T` returns one item.
+                    2. `get<T>(filter: dict): T[]` returns a list.
     - inspect:      Presents a high-level, often interactive, view
     - is_enabled:   Checks if functionality is enabled.
     - open:         Opens something (a buffer, window, …)
diff --git a/runtime/doc/gui.txt b/runtime/doc/gui.txt
index 21f1ba8241..85a0df03f9 100644
--- a/runtime/doc/gui.txt
+++ b/runtime/doc/gui.txt
@@ -20,8 +20,9 @@ features, whereas help tags with the "ui-" prefix refer to the |ui-protocol|.
 Nvim provides a default, builtin UI (the |TUI|), but there are many other
 (third-party) GUIs that you can use instead:
 
-- Firenvim (Nvim in your web browser!) https://github.com/glacambre/firenvim
+							*vscode*
 - vscode-neovim (Nvim in VSCode!) https://github.com/vscode-neovim/vscode-neovim
+- Firenvim (Nvim in your web browser!) https://github.com/glacambre/firenvim
 - Neovide https://neovide.dev/
 - Goneovim https://github.com/akiyosi/goneovim
 - Nvy https://github.com/RMichelsen/Nvy
diff --git a/runtime/doc/intro.txt b/runtime/doc/intro.txt
index d099c29bdb..85169fcc17 100644
--- a/runtime/doc/intro.txt
+++ b/runtime/doc/intro.txt
@@ -49,17 +49,19 @@ For more information try one of these:
 ==============================================================================
 Nvim on the interwebs					*internet*
 
-			*www* *distribution* *download*
-
-	Nvim home page:	  https://neovim.io/
-	Downloads:	  https://github.com/neovim/neovim/releases
-	Vim FAQ:	  https://vimhelp.org/vim_faq.txt.html
-
-
-			*bugs* *bug-report*
-Report bugs and request features here:
-https://github.com/neovim/neovim/issues
-
+			*www* *distribution*
+- Nvim home page: https://neovim.io/
+- Vim FAQ: https://vimhelp.org/vim_faq.txt.html
+
+			*download* *upgrade* *ubuntu*
+To install or upgrade Nvim, you can...
+- Download a pre-built archive:
+  https://github.com/neovim/neovim/releases
+- Use your system package manager:
+  https://github.com/neovim/neovim/blob/master/INSTALL.md#install-from-package
+
+			*bugs* *bug-report* *feature-request*
+Report bugs and request features here: https://github.com/neovim/neovim/issues
 Be brief, yet complete.  Always give a reproducible example and try to find
 out which settings or other things trigger the bug.
 
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 047e263768..48fa595a53 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -17,9 +17,9 @@ get an idea of what lurks beneath: >vim
     :lua vim.print(package.loaded)
 
 Nvim includes a "standard library" |lua-stdlib| for Lua.  It complements the
-"editor stdlib" (|builtin-functions| and |Ex-commands|) and the |API|, all of
-which can be used from Lua code (|lua-vimscript| |vim.api|). Together these
-"namespaces" form the Nvim programming interface.
+"editor stdlib" (|vimscript-functions| + |Ex-commands|) and the |API|, all of
+which can be used from Lua code (|lua-vimscript| |vim.api|). These three
+namespaces form the Nvim programming interface.
 
 Lua plugins and user config are automatically discovered and loaded, just like
 Vimscript. See |lua-guide| for practical guidance.
diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt
index 11048aee30..34cf309576 100644
--- a/runtime/doc/map.txt
+++ b/runtime/doc/map.txt
@@ -12,7 +12,7 @@ manual.
                                       Type |gO| to see the table of contents.
 
 ==============================================================================
-1. Key mapping				*key-mapping* *mapping* *macro*
+1. Key mapping			      *keybind* *key-mapping* *mapping* *macro*
 
 Key mapping is used to change the meaning of typed keys.  The most common use
 is to define a sequence of commands for a function key.  Example: >
diff --git a/runtime/doc/nvim.txt b/runtime/doc/nvim.txt
index 86e344c654..8593511dbc 100644
--- a/runtime/doc/nvim.txt
+++ b/runtime/doc/nvim.txt
@@ -6,21 +6,23 @@
 
 Nvim                                              *nvim* *neovim* *nvim-intro*
 
-Nvim is based on Vim by Bram Moolenaar.
+Nvim is based on Vim by Bram Moolenaar. Nvim is emphatically a fork of Vim,
+not a clone: compatibility with Vim (especially editor and Vimscript features,
+except |Vim9script|) is maintained where possible. See |vim-differences| for
+the complete reference.
 
-If you already use Vim see |nvim-from-vim| for a quickstart.
-If you are new to Vim, try the 30-minute tutorial: >vim
+If you already use Vim, see |nvim-from-vim| for a quickstart. If you just
+installed Nvim and have never used it before, watch this 10-minute
+video: https://youtu.be/TQn2hJeHQbM .
 
-    :Tutor<Enter>
-
-Nvim is emphatically a fork of Vim, not a clone: compatibility with Vim
-(especially editor and Vimscript features) is maintained where possible. See
-|vim-differences| for the complete reference of differences from Vim.
+To learn how to use Vim in 30 minutes, try the tutorial: >vim
 
+    :Tutor<Enter>
+<
                                       Type |gO| to see the table of contents.
 
 ==============================================================================
-Transitioning from Vim                          *nvim-from-vim*
+Transitioning from Vim                                         *nvim-from-vim*
 
 1. To start the transition, create your |init.vim| (user config) file: >vim
 
@@ -71,4 +73,20 @@ the same Nvim configuration on all of your machines, by creating
     source ~/.config/nvim/init.vim
 
 ==============================================================================
+What next?                                                   *nvim-quickstart*
+
+If you are just trying out Nvim for a few minutes, and want to see the
+extremes of what it can do, try one of these popular "extension packs" or
+"distributions" (Note: Nvim is not affiliated with these projects, and does
+not support them):
+
+- *kickstart* https://github.com/nvim-lua/kickstart.nvim
+- *lazyvim* https://www.lazyvim.org/
+- *nvchad* https://nvchad.com/
+
+However, in general, we recommend (eventually) taking time to learn Nvim from
+its stock configuration, and incrementally setting options and adding plugins
+to your |config| as you find an explicit need to do so.
+
+==============================================================================
  vim:tw=78:ts=8:et:ft=help:norl:
diff --git a/runtime/doc/ui.txt b/runtime/doc/ui.txt
index 55eba484bc..77eddfd8e1 100644
--- a/runtime/doc/ui.txt
+++ b/runtime/doc/ui.txt
@@ -788,7 +788,7 @@ must handle.
 
 	kind
 	    Name indicating the message kind:
-		"" (empty)	Unknown (consider a feature-request: |bugs|)
+		"" (empty)	Unknown (consider a |feature-request|)
 		"confirm"	|confirm()| or |:confirm| dialog
 		"confirm_sub"	|:substitute| confirm dialog |:s_c|
 		"emsg"		Error (|errors|, internal error, |:throw|, …)
diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt
index d967e7c75b..5049439337 100644
--- a/runtime/doc/various.txt
+++ b/runtime/doc/various.txt
@@ -534,7 +534,8 @@ gO			Show a filetype-specific, navigable "outline" of the
 			current buffer. For example, in a |help| buffer this
 			shows the table of contents.
 
-			Currently works in |help| and |:Man| buffers.
+			Works in |help| and |:Man| buffers, or any buffer with
+			an active |LSP| client (|lsp-defaults|).
 
 [N]gs							*gs* *:sl* *:sleep*
 :[N]sl[eep] [N][m]	Do nothing for [N] seconds, or [N] milliseconds if [m]
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index 6e1a9adb83..8e19df0160 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -686,7 +686,7 @@ Cscope:
   https://github.com/dhananjaylatkar/cscope_maps.nvim
 
 Eval:
-- Vim9script
+- *Vim9script* (the Vim 9+ flavor of Vimscript) is not supported.
 - *cscope_connection()*
 - *err_teapot()*
 - *js_encode()*
diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index acd12b353d..d74ee11b46 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -1654,7 +1654,7 @@ function vim.api.nvim_notify(msg, log_level, opts) end
 --- Open a terminal instance in a buffer
 ---
 --- By default (and currently the only option) the terminal will not be
---- connected to an external process. Instead, input send on the channel
+--- connected to an external process. Instead, input sent on the channel
 --- will be echoed directly by the terminal. This is useful to display
 --- ANSI terminal sequences returned as part of a rpc message, or similar.
 ---
@@ -1665,6 +1665,18 @@ function vim.api.nvim_notify(msg, log_level, opts) end
 --- Then `nvim_chan_send()` can be called immediately to process sequences
 --- in a virtual terminal having the intended size.
 ---
+--- Example: this `TermHl` command can be used to display and highlight raw ANSI termcodes, so you
+--- can use Nvim as a "scrollback pager" (for terminals like kitty): [terminal-scrollback-pager]()
+---
+--- ```lua
+--- vim.api.nvim_create_user_command('TermHl', function()
+---   local b = vim.api.nvim_create_buf(false, true)
+---   local chan = vim.api.nvim_open_term(b, {})
+---   vim.api.nvim_chan_send(chan, table.concat(vim.api.nvim_buf_get_lines(0, 0, -1, false), '\n'))
+---   vim.api.nvim_win_set_buf(0, b)
+--- end, { desc = 'Highlights ANSI termcodes in curbuf' })
+--- ```
+---
 --- @param buffer integer the buffer to use (expected to be empty)
 --- @param opts vim.api.keyset.open_term Optional parameters.
 --- - on_input: Lua callback for input sent, i e keypresses in terminal
diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index f9b5d93a4b..e207f641de 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -4928,7 +4928,7 @@ function vim.fn.jobstop(id) end
 ---
 --- @param jobs integer[]
 --- @param timeout? integer
---- @return any
+--- @return integer[]
 function vim.fn.jobwait(jobs, timeout) end
 
 --- Join the items in {list} together into one String.
@@ -7244,9 +7244,9 @@ function vim.fn.round(expr) end
 ---
 --- @param channel integer
 --- @param event string
---- @param args? any
+--- @param ... any
 --- @return any
-function vim.fn.rpcnotify(channel, event, args) end
+function vim.fn.rpcnotify(channel, event, ...) end
 
 --- Sends a request to {channel} to invoke {method} via
 --- |RPC| and blocks until a response is received.
@@ -7256,9 +7256,9 @@ function vim.fn.rpcnotify(channel, event, args) end
 ---
 --- @param channel integer
 --- @param method string
---- @param args? any
+--- @param ... any
 --- @return any
-function vim.fn.rpcrequest(channel, method, args) end
+function vim.fn.rpcrequest(channel, method, ...) end
 
 --- @deprecated
 --- Deprecated. Replace  >vim
@@ -9328,6 +9328,7 @@ function vim.fn.str2float(string, quoted) end
 --- and exists only for backwards-compatibility.
 --- With UTF-8 composing characters are handled properly: >vim
 ---   echo str2list("á")    " returns [97, 769]
+--- <
 ---
 --- @param string string
 --- @param utf8? boolean
@@ -10870,7 +10871,7 @@ function vim.fn.winheight(nr) end
 --- <
 ---
 --- @param tabnr? integer
---- @return any
+--- @return any[]
 function vim.fn.winlayout(tabnr) end
 
 --- The result is a Number, which is the screen line of the cursor
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index ab52612f9f..1262af5e40 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -1040,7 +1040,7 @@ fail:
 /// Open a terminal instance in a buffer
 ///
 /// By default (and currently the only option) the terminal will not be
-/// connected to an external process. Instead, input send on the channel
+/// connected to an external process. Instead, input sent on the channel
 /// will be echoed directly by the terminal. This is useful to display
 /// ANSI terminal sequences returned as part of a rpc message, or similar.
 ///
@@ -1051,6 +1051,18 @@ fail:
 /// Then |nvim_chan_send()| can be called immediately to process sequences
 /// in a virtual terminal having the intended size.
 ///
+/// Example: this `TermHl` command can be used to display and highlight raw ANSI termcodes, so you
+/// can use Nvim as a "scrollback pager" (for terminals like kitty): [terminal-scrollback-pager]()
+///
+/// ```lua
+/// vim.api.nvim_create_user_command('TermHl', function()
+///   local b = vim.api.nvim_create_buf(false, true)
+///   local chan = vim.api.nvim_open_term(b, {})
+///   vim.api.nvim_chan_send(chan, table.concat(vim.api.nvim_buf_get_lines(0, 0, -1, false), '\n'))
+///   vim.api.nvim_win_set_buf(0, b)
+/// end, { desc = 'Highlights ANSI termcodes in curbuf' })
+/// ```
+///
 /// @param buffer the buffer to use (expected to be empty)
 /// @param opts   Optional parameters.
 ///          - on_input: Lua callback for input sent, i e keypresses in terminal
diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua
index cd3ccf543e..08c9cd3991 100644
--- a/src/nvim/eval.lua
+++ b/src/nvim/eval.lua
@@ -6049,6 +6049,7 @@ M.funcs = {
     ]=],
     name = 'jobwait',
     params = { { 'jobs', 'integer[]' }, { 'timeout', 'integer' } },
+    returns = 'integer[]',
     signature = 'jobwait({jobs} [, {timeout}])',
   },
   join = {
@@ -8776,7 +8777,7 @@ M.funcs = {
       <
     ]=],
     name = 'rpcnotify',
-    params = { { 'channel', 'integer' }, { 'event', 'string' }, { 'args', 'any' } },
+    params = { { 'channel', 'integer' }, { 'event', 'string' }, { '...', 'any' } },
     signature = 'rpcnotify({channel}, {event} [, {args}...])',
   },
   rpcrequest = {
@@ -8789,7 +8790,7 @@ M.funcs = {
       <
     ]=],
     name = 'rpcrequest',
-    params = { { 'channel', 'integer' }, { 'method', 'string' }, { 'args', 'any' } },
+    params = { { 'channel', 'integer' }, { 'method', 'string' }, { '...', 'any' } },
     signature = 'rpcrequest({channel}, {method} [, {args}...])',
   },
   rpcstart = {
@@ -11155,7 +11156,7 @@ M.funcs = {
       and exists only for backwards-compatibility.
       With UTF-8 composing characters are handled properly: >vim
       	echo str2list("á")		" returns [97, 769]
-
+      <
     ]=],
     name = 'str2list',
     params = { { 'string', 'string' }, { 'utf8', 'boolean' } },
@@ -13091,6 +13092,7 @@ M.funcs = {
     ]=],
     name = 'winlayout',
     params = { { 'tabnr', 'integer' } },
+    returns = 'any[]',
     signature = 'winlayout([{tabnr}])',
   },
   winline = {