From f40f4c7d8a81391c04f721863699b57c9607252c Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Fri, 6 Dec 2024 13:39:29 +0100
Subject: [PATCH] docs: misc

todo

- https://github.com/neovim/neovim/pull/30085#discussion_r1741869280
---
 runtime/doc/gui.txt               | 10 +++++++---
 runtime/doc/intro.txt             | 22 +++++++++++++++-------
 runtime/doc/lsp.txt               | 28 +++++++++-------------------
 runtime/doc/lua.txt               |  4 ++--
 runtime/doc/map.txt               |  2 +-
 runtime/doc/news.txt              |  6 ++++--
 runtime/doc/repeat.txt            |  2 +-
 runtime/doc/vim_diff.txt          | 23 +++++++++++------------
 runtime/lua/vim/_meta/json.lua    | 14 +++++++-------
 test/functional/lua/json_spec.lua |  2 +-
 10 files changed, 58 insertions(+), 55 deletions(-)

diff --git a/runtime/doc/gui.txt b/runtime/doc/gui.txt
index 380fa71537..eb787af3c9 100644
--- a/runtime/doc/gui.txt
+++ b/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/
diff --git a/runtime/doc/intro.txt b/runtime/doc/intro.txt
index ac019a4f25..0c654b8b30 100644
--- a/runtime/doc/intro.txt
+++ b/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*
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 83d191ed48..0dfe46a1c7 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -348,22 +348,17 @@ 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`. The `vim.lsp.handlers` 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 = {
@@ -371,14 +366,9 @@ Handlers can be set by (in increasing priority):
       },
     }
 <
-  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',
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index dad3d92238..5c1d48db97 100644
--- a/runtime/doc/lua.txt
+++ b/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`)
diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt
index 34cf309576..1e472422ce 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			      *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: >
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index ad0835e80f..36e256d3b6 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -61,7 +61,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
 
@@ -123,6 +122,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
 
@@ -176,7 +176,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
 
@@ -253,6 +252,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
 
 OPTIONS
 
@@ -264,6 +264,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
 
diff --git a/runtime/doc/repeat.txt b/runtime/doc/repeat.txt
index abeefb980e..e65caa72ed 100644
--- a/runtime/doc/repeat.txt
+++ b/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
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index c93d2b119e..9f28b373ee 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -24,7 +24,7 @@ User configuration and data files are found in standard |base-directories|
   session information.  |shada|
 
 ==============================================================================
-Defaults                                                    *nvim-defaults*
+Defaults                                            *defaults* *nvim-defaults*
 
 - Filetype detection is enabled by default. This can be disabled by adding
   ":filetype off" to |init.vim|.
@@ -291,7 +291,8 @@ Commands:
   User commands can support |:command-preview| to show results as you type
 - |:write| with "++p" flag creates parent directories.
 
-Events:
+Events (autocommands):
+- Fixed inconsistent behavior in execution of nested autocommands #23368
 - |RecordingEnter|
 - |RecordingLeave|
 - |SearchWrapped|
@@ -299,6 +300,8 @@ Events:
 - |TabNewEntered|
 - |TermClose|
 - |TermOpen|
+- |TermResponse| is fired for any OSC sequence received from the terminal,
+  instead of the Primary Device Attributes response. |v:termresponse|
 - |UIEnter|
 - |UILeave|
 
@@ -366,7 +369,7 @@ Options:
 - 'shortmess'
     - "F" flag does not affect output from autocommands.
     - "q" flag fully hides macro recording message.
-- 'signcolumn'  supports up to 9 dynamic/fixed columns
+- 'signcolumn'  can show multiple signs (dynamic or fixed columns)
 - 'statuscolumn' full control of columns using 'statusline' format
 - 'tabline'     middle-click on tabpage label closes tabpage,
                 and %@Func@foo%X can call any function on mouse-click
@@ -375,6 +378,10 @@ Options:
 - 'winblend'    pseudo-transparency in floating windows |api-floatwin|
 - 'winhighlight' window-local highlights
 
+Performance:
+- Signs are implemented using Nvim's internal "marktree" (btree) structure.
+- Folds are not updated during insert-mode.
+
 Providers:
 - If a Python interpreter is available on your `$PATH`, |:python| and
   |:python3| are always available. See |provider-python|.
@@ -392,6 +399,7 @@ Shell:
 - |system()| does not support writing/reading "backgrounded" commands. |E5677|
 
 Signs:
+- 'signcolumn' can show multiple signs.
 - Signs are removed if the associated line is deleted.
 - Signs placed twice with the same identifier in the same group are moved.
 
@@ -584,9 +592,6 @@ Mappings:
 Motion:
 - The |jumplist| avoids useless/phantom jumps.
 
-Performance:
-- Folds are not updated during insert-mode.
-
 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
@@ -611,12 +616,6 @@ Working directory (Vim implemented some of these after Nvim):
 - `getcwd(-1)` is equivalent to `getcwd(-1, 0)` instead of returning the global
   working directory. Use `getcwd(-1, -1)` to get the global working directory.
 
-Autocommands:
-- Fixed inconsistent behavior in execution of nested autocommands:
-  https://github.com/neovim/neovim/issues/23368
-- |TermResponse| is fired for any OSC sequence received from the terminal,
-  instead of the Primary Device Attributes response. |v:termresponse|
-
 Options:
 - 'titlestring' uses printf-style '%' items (see: 'statusline') to implement
   the default behaviour. The implementation is equivalent to setting
diff --git a/runtime/lua/vim/_meta/json.lua b/runtime/lua/vim/_meta/json.lua
index 1a7e87db9c..0d59de5fa6 100644
--- a/runtime/lua/vim/_meta/json.lua
+++ b/runtime/lua/vim/_meta/json.lua
@@ -25,18 +25,18 @@ vim.json = {}
 ---
 ---@param str string Stringified JSON data.
 ---@param opts? table<string,any> Options table with keys:
----                                 - luanil: (table) Table with keys:
----                                   * object: (boolean) When true, converts `null` in JSON objects
----                                                       to Lua `nil` instead of |vim.NIL|.
----                                   * array: (boolean) When true, converts `null` in JSON arrays
----                                                      to Lua `nil` instead of |vim.NIL|.
+---                               - luanil: (table) Table with keys:
+---                                 - object: (boolean) When true, converts `null` in JSON objects
+---                                   to Lua `nil` instead of |vim.NIL|.
+---                                 - array: (boolean) When true, converts `null` in JSON arrays
+---                                   to Lua `nil` instead of |vim.NIL|.
 ---@return any
 function vim.json.decode(str, opts) end
 
 --- Encodes (or "packs") Lua object {obj} as JSON in a Lua string.
 ---@param obj any
 ---@param 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
 function vim.json.encode(obj, opts) end
diff --git a/test/functional/lua/json_spec.lua b/test/functional/lua/json_spec.lua
index 8df42fcaa1..e4a1df1d4c 100644
--- a/test/functional/lua/json_spec.lua
+++ b/test/functional/lua/json_spec.lua
@@ -152,7 +152,7 @@ describe('vim.json.encode()', function()
     clear()
   end)
 
-  it('dumps strings with & without escaped slash', function()
+  it('escape_slash', function()
     -- With slash
     eq('"Test\\/"', exec_lua([[return vim.json.encode('Test/', { escape_slash = true })]]))
     eq(