docs: misc #24163

- Also delete old perl scripts which are not used since 8+ years ago.

fix #23251
fix #27367
ref https://github.com/neovim/neovim/issues/2252#issuecomment-1902662577

Helped-by: Daniel Kongsgaard <dakongsgaard@gmail.com>
Co-authored-by: Kevin Pham <keevan.pham@gmail.com>

13 files changed, 152 insertions, 94 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index cc5f228920..463301693d 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -112,7 +112,11 @@ Basic types ~
   Dictionary (msgpack: map)
   Object
 <
-  Note: empty Array is accepted as a valid argument for Dictionary parameter.
+  Note:
+    - Empty Array is accepted as a valid Dictionary parameter.
+    - Functions cannot cross RPC boundaries. But API functions (e.g.
+      |nvim_create_autocmd()|) may support Lua function parameters for non-RPC
+      invocations.
 
 Special types (msgpack EXT) ~
 
@@ -504,8 +508,9 @@ Extended marks (extmarks) represent buffer annotations that track text changes
 in the buffer. They can represent cursors, folds, misspelled words, anything
 that needs to track a logical location in the buffer over time. |api-indexing|
 
-Extmark position works like "bar" cursor: it exists between characters. Thus,
-the maximum extmark index on a line is 1 more than the character index: >
+Extmark position works like a "vertical bar" cursor: it exists between
+characters. Thus, the maximum extmark index on a line is 1 more than the
+character index: >
 
      f o o b a r      line contents
      0 1 2 3 4 5      character positions (0-based)
@@ -3447,7 +3452,8 @@ nvim_create_autocmd({event}, {opts})                   *nvim_create_autocmd()*
                    Vimscript function name, if string) called when the
                    event(s) is triggered. Lua callback can return a truthy
                    value (not `false` or `nil`) to delete the autocommand.
-                   Receives a table argument with these keys:
+                   Receives one argument, a table with these keys:
+                                                                  *event-args*
                    • id: (number) autocommand id
                    • event: (string) name of the triggered event
                      |autocmd-events|
@@ -3456,7 +3462,7 @@ nvim_create_autocmd({event}, {opts})                   *nvim_create_autocmd()*
                    • buf: (number) expanded value of <abuf>
                    • file: (string) expanded value of <afile>
                    • data: (any) arbitrary data passed from
-                     |nvim_exec_autocmds()|
+                     |nvim_exec_autocmds()|                       *event-data*
                  • command (string) optional: Vim command to execute on event.
                    Cannot be used with {callback}
                  • once (boolean) optional: defaults to false. Run the
diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt
index b3974e3246..bb84966228 100644
--- a/runtime/doc/autocmd.txt
+++ b/runtime/doc/autocmd.txt
@@ -903,18 +903,18 @@ ShellFilterPost			After executing a shell command with
 				":{range}!cmd", ":w !cmd" or ":r !cmd".
 				Can be used to check for any changed files.
 							*SourcePre*
-SourcePre			Before sourcing a vim/lua file. |:source|
+SourcePre			Before sourcing a Vimscript/Lua file. |:source|
 				<afile> is the name of the file being sourced.
 							*SourcePost*
-SourcePost			After sourcing a vim/lua file. |:source|
+SourcePost			After sourcing a Vimscript/Lua file. |:source|
 				<afile> is the name of the file being sourced.
 				Not triggered when sourcing was interrupted.
 				Also triggered after a SourceCmd autocommand
 				was triggered.
 							*SourceCmd*
-SourceCmd			When sourcing a vim/lua file. |:source|
+SourceCmd			When sourcing a Vimscript/Lua file. |:source|
 				<afile> is the name of the file being sourced.
-				The autocommand must source this file.
+				The autocommand must source that file.
 				|Cmd-event|
 							*SpellFileMissing*
 SpellFileMissing		When trying to load a spell checking file and
@@ -989,18 +989,16 @@ TermClose			When a |terminal| job ends.
 				Sets these |v:event| keys:
 				    status
 							*TermRequest*
-TermRequest			When a |terminal| job emits an OSC or DCS
-				sequence. Sets |v:termrequest|. When used from
-				Lua, the request string is included in the
-				"data" field of the autocommand callback.
+TermRequest			When a |:terminal| child process emits an OSC
+				or DCS sequence. Sets |v:termrequest|. The
+				|event-data| is the request string.
 							*TermResponse*
 TermResponse			When Nvim receives an OSC or DCS response from
-				the terminal.  Sets |v:termresponse|. When used
-				from Lua, the response string is included in
-				the "data" field of the autocommand callback.
-				May be triggered halfway through another event
-				(file I/O, a shell command, or anything else
-				that takes time). Example: >lua
+				the host terminal. Sets |v:termresponse|. The
+				|event-data| is the response string. May be
+				triggered during another event (file I/O,
+				a shell command, or anything else that takes
+				time). Example: >lua
 
 				-- Query the terminal palette for the RGB value of color 1
 				-- (red) using OSC 4
diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt
index 602b033ecc..622bce14b7 100644
--- a/runtime/doc/deprecated.txt
+++ b/runtime/doc/deprecated.txt
@@ -148,8 +148,9 @@ LSP FUNCTIONS
 						`progress` of |vim.lsp.Client|
 - *vim.lsp.get_active_clients()*		Use |vim.lsp.get_clients()|
 - *vim.lsp.for_each_buffer_client()*		Use |vim.lsp.get_clients()|
-- *vim.lsp.util.lookup_section()*		Use |vim.tbl_get()| and
-						|vim.split()| with {plain=true} instead.
+- *vim.lsp.util.lookup_section()*		Use |vim.tbl_get()| instead: >
+						local keys = vim.split(section, '.', { plain = true })
+						local  vim.tbl_get(table, unpack(keys))
 - *vim.lsp.util.trim_empty_lines()*		Use |vim.split()| with `trimempty` instead.
 - *vim.lsp.util.try_trim_markdown_code_blocks()*
 - *vim.lsp.util.set_lines()*
@@ -217,8 +218,10 @@ UI EXTENSIONS
 			by the Nvim core directly instead of the TUI.
 
 VARIABLES
-- *b:terminal_job_pid*	PID of the top-level process in a |:terminal|.
-			Use `jobpid(&channel)` instead.
+- *b:terminal_job_pid*	Use `jobpid(&channel)` instead.
+- *b:terminal_job_id*	Use `&channel` instead. To access in non-current buffer:
+			- Lua: `vim.bo[bufnr].channel`
+			- Vimscript: `getbufvar(bufnr, '&channel')`
 
 
  vim:noet:tw=78:ts=8:ft=help:norl:
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index ba16943979..b843988b94 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -532,6 +532,8 @@ External UIs are expected to implement these common features:
   published in this event. See also "mouse_on", "mouse_off".
 - UIs generally should NOT set |$NVIM_APPNAME| (unless explicitly requested by
   the user).
+- Support the text decorations/attributes given by |ui-event-hl_attr_define|.
+  The "url" attr should be presented as a clickable hyperlink.
 
 
  vim:tw=78:ts=8:sw=4:et:ft=help:norl:
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 3017329506..d199634bae 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -61,7 +61,7 @@ options are not restored when the LSP client is stopped or detached.
 - |K| is mapped to |vim.lsp.buf.hover()| unless |'keywordprg'| is customized or
   a custom keymap for `K` exists.
 
-                 *crr* *v_crr* *crn* *i_CTRL-S* *v_CTRL-R_CTRL-R* *v_CTRL-R_r*
+                 *crr* *crn* *i_CTRL-S* *v_CTRL-R_CTRL-R* *v_CTRL-R_r*
 Some keymaps are created unconditionally when Nvim starts:
 - "crn" is mapped in Normal mode to |vim.lsp.buf.rename()|
 - "crr" is mapped in Normal mode to |vim.lsp.buf.code_action()|
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index c5d656992c..071cdc8ef1 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -592,24 +592,13 @@ A subset of the `vim.*` API is available in threads. This includes:
 ==============================================================================
 VIM.HIGHLIGHT                                                  *vim.highlight*
 
-Nvim includes a function for highlighting a selection on yank.
-
-To enable it, add the following to your `init.vim`: >vim
-    au TextYankPost * silent! lua vim.highlight.on_yank()
-<
-
-You can customize the highlight group and the duration of the highlight via: >vim
-    au TextYankPost * silent! lua vim.highlight.on_yank {higroup="IncSearch", timeout=150}
-<
+vim.highlight.on_yank({opts})                        *vim.highlight.on_yank()*
+    Highlight the yanked text during a |TextYankPost| event.
 
-If you want to exclude visual selections from highlighting on yank, use: >vim
-    au TextYankPost * silent! lua vim.highlight.on_yank {on_visual=false}
+    Add the following to your `init.vim`: >vim
+        autocmd TextYankPost * silent! lua vim.highlight.on_yank {higroup='Visual', timeout=300}
 <
 
-
-vim.highlight.on_yank({opts})                        *vim.highlight.on_yank()*
-    Highlight the yanked text
-
     Parameters: ~
       • {opts}  (`table?`) Optional parameters
                 • higroup highlight group for yanked region (default
@@ -4002,18 +3991,22 @@ Iter:flatten({depth})                                         *Iter:flatten()*
         (`Iter`)
 
 Iter:fold({init}, {f})                                           *Iter:fold()*
-    Folds ("reduces") an iterator into a single value.
+    Folds ("reduces") an iterator into a single value.         *Iter:reduce()*
 
     Examples: >lua
         -- Create a new table with only even values
-        local t = { a = 1, b = 2, c = 3, d = 4 }
-        local it = vim.iter(t)
-        it:filter(function(k, v) return v % 2 == 0 end)
-        it:fold({}, function(t, k, v)
-          t[k] = v
-          return t
-        end)
-        -- { b = 2, d = 4 }
+        vim.iter({ a = 1, b = 2, c = 3, d = 4 })
+          :filter(function(k, v) return v % 2 == 0 end)
+          :fold({}, function(acc, k, v)
+            acc[k] = v
+            return acc
+          end) --> { b = 2, d = 4 }
+
+        -- Get the "maximum" item of an iterable.
+        vim.iter({ -99, -4, 3, 42, 0, 0, 7 })
+          :fold({}, function(acc, v)
+            acc.max = math.max(v, acc.max or v) return acc
+          end) --> { max = 42 }
 <
 
     Parameters: ~
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 700aba31b9..692554295c 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -4,9 +4,9 @@
                             NVIM REFERENCE MANUAL
 
 
-Notable changes in Nvim 0.10 from 0.9                                    *news*
+Notable changes since Nvim 0.9                                  *news*
 
-For changes in Nvim 0.9, see |news-0.9|.
+For changes in the previous release, see |news-0.9|.
 
                                        Type |gO| to see the table of contents.
 
@@ -148,8 +148,10 @@ The following changes may require adaptations in user config or plugins.
 ==============================================================================
 BREAKING CHANGES IN HEAD                                    *news-breaking-dev*
 
-The following breaking changes were made during the development cycle to
-unreleased features on Nvim HEAD.
+              ====== Remove this section before release. ======
+
+The following changes to UNRELEASED features were made during the development
+cycle (Nvim HEAD, the "master" branch).
 
 • Removed `vim.treesitter.foldtext` as transparent foldtext is now supported
   https://github.com/neovim/neovim/pull/20750
@@ -225,6 +227,8 @@ The following new APIs and features were added.
     swapfile is owned by a running Nvim process, instead of prompting. If you
     always want the swapfile dialog, delete the default SwapExists handler:
     `autocmd! nvim_swapfile`. |default-autocmds|
+  • Navigating the |jumplist| with CTRL+O, CTRL+I behaves more intuitively
+    when deleting buffers, and avoids "invalid buffer" cases. #25461
 
 • LSP
   • LSP method names are available in |vim.lsp.protocol.Methods|.
@@ -368,9 +372,10 @@ The following new APIs and features were added.
 
 • |vim.version.le()| and |vim.version.ge()| are added to |vim.version|.
 
-• |extmarks| can be associated with a URL and URLs are included as a new
-  highlight attribute. The TUI will display URLs using the OSC 8 control
-  sequence, enabling clickable text in supporting terminals.
+• |extmarks| can set a "url" highlight attribute, so the text region can
+  become a clickable hyperlink (assuming UI support). The TUI renders URLs
+  using the OSC 8 control sequence, enabling clickable text in supporting
+  terminals.
 
 • Added |nvim_tabpage_set_win()| to set the current window of a tabpage.
 
diff --git a/runtime/doc/nvim_terminal_emulator.txt b/runtime/doc/nvim_terminal_emulator.txt
index d4e05cee26..a6ebc7e958 100644
--- a/runtime/doc/nvim_terminal_emulator.txt
+++ b/runtime/doc/nvim_terminal_emulator.txt
@@ -126,6 +126,46 @@ color index is just forwarded.
 Editor highlighting (|syntax-highlighting|, |highlight-groups|, etc.) has
 higher precedence: it is applied after terminal colors are resolved.
 
+------------------------------------------------------------------------------
+EVENTS						*terminal-events*
+
+Applications running in a :terminal buffer can send requests, which Nvim
+exposes via the |TermRequest| event.
+
+OSC 7: change working directory			*terminal-osc7*
+
+To handle OSC 7 emitted from :terminal processes, this code will :cd to the
+directory indicated in the request. >lua
+
+  vim.api.nvim_create_autocmd({ 'TermRequest' }, {
+    desc = 'Handles OSC 7 dir change requests',
+    callback = function(ev)
+      if string.sub(vim.v.termrequest, 1, 4) == '\x1b]7;' then
+        local dir = string.gsub(vim.v.termrequest, '\x1b]7;file://[^/]*', '')
+        if vim.fn.isdirectory(dir) == 0 then
+          vim.notify('invalid dir: '..dir)
+          return
+        end
+        vim.api.nvim_buf_set_var(ev.buf, 'osc7_dir', dir)
+        if vim.o.autochdir and vim.api.nvim_get_current_buf() == ev.buf then
+          vim.cmd.cd(dir)
+        end
+      end
+    end
+  })
+  vim.api.nvim_create_autocmd({ 'BufEnter', 'WinEnter', 'DirChanged' }, {
+    callback = function(ev)
+      if vim.b.osc7_dir and vim.fn.isdirectory(vim.b.osc7_dir) == 1 then
+        vim.cmd.cd(vim.b.osc7_dir)
+      end
+    end
+  })
+
+To try it out, select the above code and source it with `:'<,'>lua`, then run
+this command in a :terminal buffer: >
+
+   printf "\033]7;file://./foo/bar\033\\"
+
 ==============================================================================
 Status Variables				*terminal-status*
 
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index c44db11acd..edda46e197 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -6837,6 +6837,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 
 	Level   Messages ~
 	----------------------------------------------------------------------
+	1	Enables Lua tracing (see above). Does not produce messages.
 	2	When a file is ":source"'ed, or |shada| file is read or written.
 	3	UI info, terminal capabilities.
 	4	Shell commands.
diff --git a/runtime/doc/remote_plugin.txt b/runtime/doc/remote_plugin.txt
index cfe4b08000..694c339ef2 100644
--- a/runtime/doc/remote_plugin.txt
+++ b/runtime/doc/remote_plugin.txt
@@ -30,9 +30,9 @@ check whether a plugin host is available for their chosen programming language.
 
 Plugin hosts are programs that provide a high-level environment for plugins,
 taking care of most boilerplate involved in defining commands, autocmds, and
-functions that are implemented over |RPC| connections. Hosts are loaded only
-when one of their registered plugins require it, keeping Nvim's startup as
-fast as possible, even if many plugins/hosts are installed.
+functions implemented over |RPC| connections. Hosts are loaded only when one
+of their registered plugins require it, keeping Nvim's startup as fast as
+possible, even if many plugins/hosts are installed.
 
 ==============================================================================
 3. Example					    *remote-plugin-example*
diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt
index 2b9eba1520..7ee3769bbd 100644
--- a/runtime/doc/treesitter.txt
+++ b/runtime/doc/treesitter.txt
@@ -18,15 +18,25 @@ changes. This documentation may also not fully reflect the latest changes.
 PARSER FILES                                              *treesitter-parsers*
 
 Parsers are the heart of treesitter. They are libraries that treesitter will
-search for in the `parser` runtime directory. By default, Nvim bundles parsers
-for C, Lua, Vimscript, Vimdoc and Treesitter query files, but parsers can be
-installed via a plugin like https://github.com/nvim-treesitter/nvim-treesitter
-or even manually.
+search for in the `parser` runtime directory.
+
+Nvim includes these parsers:
+
+- C
+- Lua
+- Markdown
+- Vimscript
+- Vimdoc
+- Treesitter query files |ft-query-plugin|
+
+You can install more parsers manually, or with a plugin like
+https://github.com/nvim-treesitter/nvim-treesitter .
 
 Parsers are searched for as `parser/{lang}.*` in any 'runtimepath' directory.
 If multiple parsers for the same language are found, the first one is used.
 (NOTE: This typically implies the priority "user config > plugins > bundled".)
-A parser can also be loaded manually using a full path: >lua
+
+To load a parser from its filepath: >lua
 
     vim.treesitter.language.add('python', { path = "/path/to/python.so" })
 <
diff --git a/runtime/doc/ui.txt b/runtime/doc/ui.txt
index 969851f027..1f5132bd30 100644
--- a/runtime/doc/ui.txt
+++ b/runtime/doc/ui.txt
@@ -331,8 +331,8 @@ numerical highlight ids to the actual attributes.
 	`blend`:		blend level (0-100). Could be used by UIs to
 				support blending floating windows to the
 				background or to signal a transparent cursor.
-	`url`:			a URL associated with this highlight. UIs can
-				display this URL however they wish.
+	`url`:			URL associated with this highlight. UIs should
+				present the region as a clickable hyperlink.
 
 	For absent color keys the default color should be used. Don't store
 	the default value in the table, rather a sentinel value, so that
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index c30239057d..8ddad66e23 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -317,36 +317,39 @@ Normal commands:
   |Q| replays the last recorded macro instead of switching to Ex mode (|gQ|).
 
 Options:
-  Local values for global-local number/boolean options are unset when the
-  option is set without a scope (e.g. by using |:set|), similarly to how
-  global-local string options work.
-
-  'autoread'    works in the terminal (if it supports "focus" events)
-  'cpoptions'   flags: |cpo-_|
-  'diffopt'     "linematch" feature
-  'exrc'        searches for ".nvim.lua", ".nvimrc", or ".exrc" files. The
+
+Local values for global-local number/boolean options are unset when the option
+is set without a scope (e.g. by using |:set|), similarly to how global-local
+string options work.
+
+- 'autoread'    works in the terminal (if it supports "focus" events)
+- 'cpoptions'   flags: |cpo-_|
+- '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",
+- '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
+- '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' "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
-  'tabline'     middle-click on tabpage label closes tabpage,
+- '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.
+    - "q" flag fully hides macro recording message.
+- 'signcolumn'  supports up to 9 dynamic/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
-  'termpastefilter'
-  'ttimeout', 'ttimeoutlen' behavior was simplified
-  'winblend'    pseudo-transparency in floating windows |api-floatwin|
-  'winhighlight' window-local highlights
+- 'termpastefilter'
+- 'ttimeout', 'ttimeoutlen' behavior was simplified
+- 'winblend'    pseudo-transparency in floating windows |api-floatwin|
+- 'winhighlight' window-local highlights
 
 Providers:
   If a Python interpreter is available on your `$PATH`, |:python| and
@@ -596,9 +599,6 @@ Autocommands:
 - |TermResponse| is fired for any OSC sequence received from the terminal,
   instead of the Primary Device Attributes response. |v:termresponse|
 
-Options:
-- |shm-q| fully hides macro recording message instead of only shortening it.
-
 ==============================================================================
 Missing features					 *nvim-missing*