docs: misc neovim#31479

runtime/doc/channel.txt

@@ -11,21 +11,20 @@ Nvim asynchronous IO					*channel*
 ==============================================================================
 1. Introduction						    *channel-intro*
 
-Channels are nvim's way of communicating with external processes.
+Channels are Nvim's way of communicating with external processes.
 
 There are several ways to open a channel:
 
-  1. Through stdin/stdout when `nvim` is started with `--headless`, and a startup
-     script or --cmd  command opens the stdio channel using |stdioopen()|.
+  1. Through stdin/stdout when `nvim` is started with `--headless` and a startup
+     script or `--cmd` command opens the stdio channel using |stdioopen()|.
 
   2. Through stdin, stdout and stderr of a process spawned by |jobstart()|.
 
-  3. Through the PTY master end of a PTY opened with |nvim_open_term()| or
-     `jobstart(…, {'pty': v:true})`.
+  3. Through the PTY master end opened with `jobstart(…, {'pty': v:true})`.
 
   4. By connecting to a TCP/IP socket or named pipe with |sockconnect()|.
 
-  5. By another process connecting to a socket listened to by nvim. This only
+  5. By another process connecting to a socket listened to by Nvim. This only
      supports RPC channels, see |rpc-connecting|.
 
 Channels support multiple modes or protocols. In the most basic
@@ -146,7 +145,7 @@ from the host TTY, or if Nvim is |--headless| it uses default values: >vim
     :echo system('nvim --headless +"te stty -a" +"sleep 1" +"1,/^$/print" +q')
 
 ==============================================================================
-3. Communicating using msgpack-rpc			      *channel-rpc*
+3. Communicating with msgpack RPC			      *channel-rpc*
 
 When channels are opened with the `rpc` option set to true, the channel can be
 used for remote method calls in both directions, see |msgpack-rpc|. Note that

runtime/doc/gui.txt

@@ -17,10 +17,14 @@ TUI and GUI (assuming the UI supports the given feature). See |TUI| for notes
 specific to the terminal UI. Help tags with the "gui-" prefix refer to UI
 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:
+==============================================================================
+Third-party GUIs                                *third-party-guis* *vscode*
+
+Nvim provides a builtin "terminal UI" (|TUI|), but also works with many
+(third-party) GUIs which may provide a fresh look or extra features on top of
+Nvim. For example, "vscode-neovim" essentally allows you to use VSCode as
+a Nvim GUI.
 
-                                                        *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/

runtime/doc/intro.txt

@@ -32,8 +32,9 @@ and |user-manual|.
 Resources                                               *resources*
 
                                                 *internet* *www* *distribution*
-- Nvim home page: https://neovim.io/
-- Vim FAQ: https://vimhelp.org/vim_faq.txt.html
+Nvim home page:
+
+        https://neovim.io/
 
                                                 *book*
 There are many resources to learn Vi, Vim, and Nvim.  We recommend:
@@ -48,6 +49,7 @@ There are many resources to learn Vi, Vim, and Nvim.  We recommend:
 - For more information try one of these:
   - https://iccf-holland.org/click5.html
   - https://www.vim.org/iccf/click5.html
+- Vim FAQ: https://vimhelp.org/vim_faq.txt.html
 
                                                 *bugs* *bug-report* *feature-request*
 Report bugs and request features here: https://github.com/neovim/neovim/issues
@@ -67,18 +69,24 @@ To install or upgrade Nvim, you can...
 - Build from source:
   https://github.com/neovim/neovim/blob/master/INSTALL.md#install-from-source
 
-                                                *uninstall*
+------------------------------------------------------------------------------
+Un-installing Nvim                                      *uninstall*
+
 To uninstall Nvim:
-- If you downloaded a pre-built archive or built Nvim from source (e.g. `make
-  install`), just delete its files, typically located in: >
+- If you downloaded a pre-built archive or built Nvim from source (e.g.
+  `make install`), just delete its files, typically located in: >
   /usr/local/bin/nvim
   /usr/local/share/nvim
+<
+  - To find where Nvim is installed, run these commands: >
+    :echo v:progpath
+    :echo $VIMRUNTIME
 <
 - If you installed via package manager, read your package manager's
   documentation. Common examples:
   - APT (Debian, Ubuntu, …): `apt-get remove neovim`
-  - Homebrew (macOS): `brew install neovim`
-  - Scoop (Windows): `scoop install neovim`
+  - Homebrew (macOS): `brew uninstall neovim`
+  - Scoop (Windows): `scoop uninstall neovim`
 
 ==============================================================================
 Sponsor Vim/Nvim development                            *sponsor* *register*

runtime/doc/lsp.txt

@@ -344,37 +344,27 @@ Each response handler has this signature: >
                                                       *lsp-handler-resolution*
 Handlers can be set by (in increasing priority):
 
-- Setting a field in vim.lsp.handlers.                      *vim.lsp.handlers*
-  `vim.lsp.handlers` is a global table that contains the default mapping of
-  |lsp-method| names to lsp-handlers.
-
+                                                            *vim.lsp.handlers*
+- Setting a field in `vim.lsp.handlers`. This global table contains the
+  default mappings of |lsp-method| names to handlers. (Note: only for
+  server-to-client requests/notifications, not client-to-server.)
   Example: >lua
-
     vim.lsp.handlers['textDocument/publishDiagnostics'] = my_custom_diagnostics_handler
 <
-  Note: this only applies for requests/notifications made by the
-  server to the client.
-
-- The {handlers} parameter of |vim.lsp.start()|. This sets the default
-  |lsp-handler| for a specific server.
-
+- Passing a {handlers} parameter to |vim.lsp.start()|. This sets the default
+  |lsp-handler| for a specific server. (Note: only for server-to-client
+  requests/notifications, not client-to-server.)
   Example: >lua
-
     vim.lsp.start {
       ..., -- Other configuration omitted.
       handlers = {
         ['textDocument/publishDiagnostics'] = my_custom_server_definition
       },
     }
 <
-  Note: this only applies for requests/notifications made by the
-  server to the client.
-
-- The {handler} parameter of |vim.lsp.buf_request_all()|. This sets
-  the |lsp-handler| ONLY for the given request(s).
-
+- Passing a {handler} parameter to |vim.lsp.buf_request_all()|. This sets the
+  |lsp-handler| ONLY for the given request(s).
   Example: >lua
-
     vim.lsp.buf_request_all(
       0,
       'textDocument/publishDiagnostics',

runtime/doc/lua.txt

@@ -817,8 +817,8 @@ vim.json.encode({obj}, {opts})                             *vim.json.encode()*
     Parameters: ~
       • {obj}   (`any`)
       • {opts}  (`table<string,any>?`) Options table with keys:
-                • escape_slash: (boolean) (default false) When true, escapes
-                  `/` character in JSON strings
+                • escape_slash: (boolean) (default false) Escape slash
+                  characters "/" in string values.
 
     Return: ~
         (`string`)
@@ -3062,11 +3062,13 @@ vim.fs.find({names}, {opts})                                   *vim.fs.find()*
         items
 
 vim.fs.joinpath({...})                                     *vim.fs.joinpath()*
-    Concatenates partial paths into one path. Slashes are normalized
-    (redundant slashes are removed, and on Windows backslashes are replaced
-    with forward-slashes) (e.g., `"foo/"` and `"/bar"` get joined to
-    `"foo/bar"`) (windows: e.g `"a\foo\"` and `"\bar"` are joined to
-    `"a/foo/bar"`)
+    Concatenates partial paths (one absolute or relative path followed by zero
+    or more relative paths). Slashes are normalized: redundant slashes are
+    removed, and (on Windows) backslashes are replaced with forward-slashes.
+
+    Examples:
+    • "foo/", "/bar" => "foo/bar"
+    • Windows: "a\foo\", "\bar" => "a/foo/bar"
 
     Attributes: ~
         Since: 0.10.0

runtime/doc/map.txt

@@ -12,7 +12,7 @@ manual.
                                       Type |gO| to see the table of contents.
 
 ==============================================================================
-1. Key mapping			      *keybind* *key-mapping* *mapping* *macro*
+1. Key mapping				*keybind* *key-mapping* *mapping*
 
 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: >

runtime/doc/news.txt

@@ -67,7 +67,6 @@ DEFAULTS
   current buffer, respectively.
 • 'number', 'relativenumber', 'signcolumn', and 'foldcolumn' are disabled in
   |terminal| buffers. See |terminal-config| for an example of changing these defaults.
-• |vim.json.encode()| no longer escapes the forward slash symbol by default
 
 DIAGNOSTICS
 
@@ -137,6 +136,7 @@ LUA
 • Command-line completions for: `vim.g`, `vim.t`, `vim.w`, `vim.b`, `vim.v`,
   `vim.o`, `vim.wo`, `vim.bo`, `vim.opt`, `vim.opt_local`, `vim.opt_global`,
   and `vim.fn`.
+• |vim.json.encode()| no longer escapes forward slashes "/" by default
 
 OPTIONS
 
@@ -192,7 +192,6 @@ The following new features were added.
 API
 
 • |nvim__ns_set()| can set properties for a namespace
-• |vim.json.encode()| has an option to enable forward slash escaping
 
 DEFAULTS
 
@@ -270,6 +269,7 @@ LUA
   is more performant and easier to read.
 • |vim.str_byteindex()| and |vim.str_utfindex()| gained overload signatures
   supporting two new parameters, `encoding` and `strict_indexing`.
+• |vim.json.encode()| has an option to enable forward slash escaping
 • |vim.fs.abspath()| converts paths to absolute paths.
 
 OPTIONS
@@ -282,6 +282,8 @@ PERFORMANCE
 
 • Significantly reduced redraw time for long lines with treesitter
   highlighting.
+• LSP diagnostics and inlay hints are de-duplicated (new requests cancel
+  inflight requests). This greatly improves performance with slow LSP servers.
 
 PLUGINS
 

runtime/doc/repeat.txt

@@ -111,7 +111,7 @@ To abort this type CTRL-C twice.
 ==============================================================================
 Complex repeats						*complex-repeat*
 
-							*q* *recording*
+							*q* *recording* *macro*
 q{0-9a-zA-Z"}		Record typed characters into register {0-9a-zA-Z"}
 			(uppercase to append).  The 'q' command is disabled
 			while executing a register, and it doesn't work inside

runtime/doc/treesitter.txt

@@ -81,8 +81,7 @@ that user config takes precedence over plugins, which take precedence over
 queries bundled with Nvim). If a query should extend other queries instead
 of replacing them, use |treesitter-query-modeline-extends|.
 
-See |lua-treesitter-query| for the list of available methods for working with
-treesitter queries from Lua.
+The Lua interface is described at |lua-treesitter-query|.
 
 
 TREESITTER QUERY PREDICATES                            *treesitter-predicates*
@@ -1195,6 +1194,10 @@ register({lang}, {filetype})              *vim.treesitter.language.register()*
 ==============================================================================
 Lua module: vim.treesitter.query                        *lua-treesitter-query*
 
+This Lua |treesitter-query| interface allows you to create queries and use
+them to parse text. See |vim.treesitter.query.parse()| for a working example.
+
+
                                         *vim.treesitter.query.add_directive()*
 add_directive({name}, {handler}, {opts})
     Adds a new directive to be used in queries
@@ -1325,21 +1328,30 @@ omnifunc({findstart}, {base})                *vim.treesitter.query.omnifunc()*
       • {base}       (`string`)
 
 parse({lang}, {query})                          *vim.treesitter.query.parse()*
-    Parse {query} as a string. (If the query is in a file, the caller should
-    read the contents into a string before calling).
-
-    Returns a `Query` (see |lua-treesitter-query|) object which can be used to
-    search nodes in the syntax tree for the patterns defined in {query} using
-    the `iter_captures` and `iter_matches` methods.
-
-    Exposes `info` and `captures` with additional context about {query}.
-    • `captures` contains the list of unique capture names defined in {query}.
-    • `info.captures` also points to `captures`.
-    • `info.patterns` contains information about predicates.
+    Parses a {query} string and returns a `Query` object
+    (|lua-treesitter-query|), which can be used to search the tree for the
+    query patterns (via |Query:iter_captures()|, |Query:iter_matches()|), or
+    inspect the query via these fields:
+    • `captures`: a list of unique capture names defined in the query (alias:
+      `info.captures`).
+    • `info.patterns`: information about predicates.
+
+    Example (select the code then run `:'<,'>lua` to try it): >lua
+        local query = vim.treesitter.query.parse('vimdoc', [[
+          ; query
+          ((h1) @str
+            (#trim! @str 1 1 1 1))
+        ]])
+        local tree = vim.treesitter.get_parser():parse()[1]
+        for id, node, metadata in query:iter_captures(tree:root(), 0) do
+           -- Print the node name and source text.
+           vim.print({node:type(), vim.treesitter.get_node_text(node, vim.api.nvim_get_current_buf())})
+        end
+<
 
     Parameters: ~
       • {lang}   (`string`) Language to use for the query
-      • {query}  (`string`) Query in s-expr syntax
+      • {query}  (`string`) Query text, in s-expr syntax
 
     Return: ~
         (`vim.treesitter.Query`) Parsed query
@@ -1349,18 +1361,23 @@ parse({lang}, {query})                          *vim.treesitter.query.parse()*
 
                                                        *Query:iter_captures()*
 Query:iter_captures({node}, {source}, {start}, {stop})
-    Iterate over all captures from all matches inside {node}
-
-    {source} is needed if the query contains predicates; then the caller must
-    ensure to use a freshly parsed tree consistent with the current text of
-    the buffer (if relevant). {start} and {stop} can be used to limit matches
-    inside a row range (this is typically used with root node as the {node},
-    i.e., to get syntax highlight matches in the current viewport). When
-    omitted, the {start} and {stop} row values are used from the given node.
-
-    The iterator returns four values: a numeric id identifying the capture,
-    the captured node, metadata from any directives processing the match, and
-    the match itself. The following example shows how to get captures by name: >lua
+    Iterates over all captures from all matches in {node}.
+
+    {source} is required if the query contains predicates; then the caller
+    must ensure to use a freshly parsed tree consistent with the current text
+    of the buffer (if relevant). {start} and {stop} can be used to limit
+    matches inside a row range (this is typically used with root node as the
+    {node}, i.e., to get syntax highlight matches in the current viewport).
+    When omitted, the {start} and {stop} row values are used from the given
+    node.
+
+    The iterator returns four values:
+    1. the numeric id identifying the capture
+    2. the captured node
+    3. metadata from any directives processing the match
+    4. the match itself
+
+    Example: how to get captures by name: >lua
         for id, node, metadata, match in query:iter_captures(tree:root(), bufnr, first, last) do
           local name = query.captures[id] -- name of the capture in the query
           -- typically useful info about the node: