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>

CMakeLists.txt

@@ -1,7 +1,9 @@
 # CMAKE REFERENCE
-#   intro: https://codingnest.com/basic-cmake/
+#   - intro: https://codingnest.com/basic-cmake/
-#   best practices (3.0+): https://gist.github.com/mbinna/c61dbb39bca0e4fb7d1f73b0d66a4fd1
+#   - best practices (3.0+): https://gist.github.com/mbinna/c61dbb39bca0e4fb7d1f73b0d66a4fd1
-#   pitfalls: https://izzys.casa/2019/02/everything-you-never-wanted-to-know-about-cmake/
+#   - pitfalls: https://izzys.casa/2019/02/everything-you-never-wanted-to-know-about-cmake/
+#   - troubleshooting:
+#     - variable_watch https://cmake.org/cmake/help/latest/command/variable_watch.html
 
 # Version should match the tested CMAKE_URL in .github/workflows/build.yml.
 cmake_minimum_required(VERSION 3.13)
@@ -167,6 +169,7 @@ endif()
 
 option(ENABLE_ASAN_UBSAN "Enable Clang address & undefined behavior sanitizer for nvim binary." OFF)
 option(ENABLE_MSAN "Enable Clang memory sanitizer for nvim binary." OFF)
+# TSAN exists to test Luv threads.
 option(ENABLE_TSAN "Enable Clang thread sanitizer for nvim binary." OFF)
 
 if((ENABLE_ASAN_UBSAN AND ENABLE_MSAN)

CONTRIBUTING.md

@@ -82,28 +82,31 @@ a comment.
 ### Commit messages
 
 Follow the [conventional commits guidelines][conventional_commits] to *make reviews easier* and to make
-the VCS/git logs more valuable. The general structure of a commit message is:
+the VCS/git logs more valuable. The structure of a commit message is:
 
-```
+    type(scope): subject
-<type>([optional scope]): <description>
 
-[optional body]
+    Problem:
+    ...
 
-[optional footer(s)]
+    Solution:
-```
+    ...
 
-- Prefix the commit subject with one of these [_types_](https://github.com/commitizen/conventional-commit-types/blob/master/index.json):
+- Commit message **subject** (you can **ignore this for "fixup" commits** or any commits you expect to be squashed):
-    - `build`, `ci`, `docs`, `feat`, `fix`, `perf`, `refactor`, `revert`, `test`, `vim-patch`
+    - Prefix with a [_type_](https://github.com/commitizen/conventional-commit-types/blob/master/index.json):
-    - You can **ignore this for "fixup" commits** or any commits you expect to be squashed.
+        - `build ci docs feat fix perf refactor revert test vim-patch`
-- Append optional scope to _type_ such as `(lsp)`, `(treesitter)`, `(float)`, …
+    - Append an optional `(scope)` such as `(lsp)`, `(treesitter)`, `(float)`, …
-- _Description_ shouldn't start with a capital letter or end in a period.
+    - Use the _imperative voice_: "Fix bug" rather than "Fixed bug" or "Fixes bug."
-- Use the _imperative voice_: "Fix bug" rather than "Fixed bug" or "Fixes bug."
+    - Keep it short (under 72 characters).
-- Try to keep the first line under 72 characters.
+- Commit message **body** (detail):
-- A blank line must follow the subject.
+    - Concisely describe the Problem/Solution in the commit **body**. [Describing the problem](https://lamport.azurewebsites.net/pubs/state-the-problem.pdf)
-- Breaking API changes must be indicated by
+      _independently of the solution_ often leads to a better understanding for you, reviewers, and future readers.
-    1. "!" after the type/scope, and
+      ```
-    2. a "BREAKING CHANGE" footer describing the change.
+      Problem:
-       Example:
+
+      Solution:
+      ```
+- Indicate breaking API changes with "!" after the type, and a "BREAKING CHANGE" footer. Example:
   ```
   refactor(provider)!: drop support for Python 2
 

MAINTAIN.md

@@ -165,12 +165,14 @@ These dependencies are "vendored" (inlined), we must update the sources manually
 * `runtime/lua/coxpcall.lua`: coxpcall (only needed for PUC lua, builtin to luajit)
 * `src/termkey`: [libtermkey](https://github.com/neovim/libtermkey)
 
-Non-technical dependencies
+Other dependencies
 --------------------------
 
 * GitHub users:
     * https://github.com/marvim
     * https://github.com/nvim-winget
+* Org secrets/tokens:
+    * `CODECOV_TOKEN`
 * Domain names (held in https://namecheap.com):
     * neovim.org
     * neovim.io

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,
+Extmark position works like a "vertical bar" cursor: it exists between
-the maximum extmark index on a line is 1 more than the character index: >
+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

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
+TermRequest			When a |:terminal| child process emits an OSC
-				sequence. Sets |v:termrequest|. When used from
+				or DCS sequence. Sets |v:termrequest|. The
-				Lua, the request string is included in the
+				|event-data| is the request string.
-				"data" field of the autocommand callback.
 							*TermResponse*
 TermResponse			When Nvim receives an OSC or DCS response from
-				the terminal.  Sets |v:termresponse|. When used
+				the host terminal. Sets |v:termresponse|. The
-				from Lua, the response string is included in
+				|event-data| is the response string. May be
-				the "data" field of the autocommand callback.
+				triggered during another event (file I/O,
-				May be triggered halfway through another event
+				a shell command, or anything else that takes
-				(file I/O, a shell command, or anything else
+				time). Example: >lua
-				that takes time). Example: >lua
 
 				-- Query the terminal palette for the RGB value of color 1
 				-- (red) using OSC 4

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.lsp.util.lookup_section()*		Use |vim.tbl_get()| instead: >
-						|vim.split()| with {plain=true} 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|.
+- *b:terminal_job_pid*	Use `jobpid(&channel)` instead.
-			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:

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:

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()|

runtime/doc/lua.txt

@@ -592,23 +592,12 @@ 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}
-<
-
-If you want to exclude visual selections from highlighting on yank, use: >vim
-    au TextYankPost * silent! lua vim.highlight.on_yank {on_visual=false}
-<
-
-
 vim.highlight.on_yank({opts})                        *vim.highlight.on_yank()*
-    Highlight the yanked text
+    Highlight the yanked text during a |TextYankPost| event.
+
+    Add the following to your `init.vim`: >vim
+        autocmd TextYankPost * silent! lua vim.highlight.on_yank {higroup='Visual', timeout=300}
+<
 
     Parameters: ~
       • {opts}  (`table?`) Optional parameters
@@ -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 }
+        vim.iter({ a = 1, b = 2, c = 3, d = 4 })
-        local it = vim.iter(t)
+          :filter(function(k, v) return v % 2 == 0 end)
-        it:filter(function(k, v) return v % 2 == 0 end)
+          :fold({}, function(acc, k, v)
-        it:fold({}, function(t, k, v)
+            acc[k] = v
-          t[k] = v
+            return acc
-          return t
+          end) --> { b = 2, d = 4 }
-        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: ~

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
+              ====== Remove this section before release. ======
-unreleased features on Nvim HEAD.
+
+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
+• |extmarks| can set a "url" highlight attribute, so the text region can
-  highlight attribute. The TUI will display URLs using the OSC 8 control
+  become a clickable hyperlink (assuming UI support). The TUI renders URLs
-  sequence, enabling clickable text in supporting terminals.
+  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.
 

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*
 

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.

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
+functions implemented over |RPC| connections. Hosts are loaded only when one
-when one of their registered plugins require it, keeping Nvim's startup as
+of their registered plugins require it, keeping Nvim's startup as fast as
-fast as possible, even if many plugins/hosts are installed.
+possible, even if many plugins/hosts are installed.
 
 ==============================================================================
 3. Example					    *remote-plugin-example*

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
+search for in the `parser` runtime directory.
-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
+Nvim includes these parsers:
-or even manually.
+
+- 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" })
 <

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
+	`url`:			URL associated with this highlight. UIs should
-				display this URL however they wish.
+				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

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)
+Local values for global-local number/boolean options are unset when the option
-  'cpoptions'   flags: |cpo-_|
+is set without a scope (e.g. by using |:set|), similarly to how global-local
-  'diffopt'     "linematch" feature
+string options work.
-  'exrc'        searches for ".nvim.lua", ".nvimrc", or ".exrc" files. The
+
+- '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
+- 'foldcolumn'  supports up to 9 dynamic/fixed columns
-  'guicursor'   works in the terminal (TUI)
+- 'guicursor'   works in the terminal (TUI)
-  'inccommand'  shows interactive results for |:substitute|-like commands
+- 'inccommand'  shows interactive results for |:substitute|-like commands
                 and |:command-preview| commands
-  'jumpoptions' "view" tries to restore the |mark-view| when moving through
+- 'jumpoptions' "view" tries to restore the |mark-view| when moving through
-  the |jumplist|, |changelist|, |alternate-file| or using |mark-motions|.
+- the |jumplist|, |changelist|, |alternate-file| or using |mark-motions|.
-  'laststatus'  global statusline support
+- 'laststatus'  global statusline support
-  'mousescroll' amount to scroll by when scrolling with a mouse
+- 'mousescroll' amount to scroll by when scrolling with a mouse
-  'pumblend'    pseudo-transparent popupmenu
+- 'pumblend'    pseudo-transparent popupmenu
-  'scrollback'
+- 'scrollback'
-  'shortmess'   "F" flag does not affect output from autocommands
+- 'shortmess'
-  'signcolumn'  supports up to 9 dynamic/fixed columns
+    - "F" flag does not affect output from autocommands.
-  'statuscolumn' full control of columns using 'statusline' format
+    - "q" flag fully hides macro recording message.
-  'tabline'     middle-click on tabpage label closes tabpage,
+- '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'
+- 'termpastefilter'
-  'ttimeout', 'ttimeoutlen' behavior was simplified
+- 'ttimeout', 'ttimeoutlen' behavior was simplified
-  'winblend'    pseudo-transparency in floating windows |api-floatwin|
+- 'winblend'    pseudo-transparency in floating windows |api-floatwin|
-  'winhighlight' window-local highlights
+- '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*
 

runtime/lua/vim/_defaults.lua

@@ -255,7 +255,7 @@ do
 
   vim.api.nvim_create_autocmd('TermRequest', {
     group = nvim_terminal_augroup,
-    desc = 'Respond to OSC foreground/background color requests',
+    desc = 'Handles OSC foreground/background color requests',
     callback = function(args)
       --- @type integer
       local channel = vim.bo[args.buf].channel

runtime/lua/vim/_meta/api.lua

@@ -897,8 +897,8 @@ function vim.api.nvim_create_augroup(name, opts) end
 ---             • callback (function|string) optional: Lua function (or
 ---               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
+---               `false` or `nil`) to delete the autocommand. Receives one
----               table argument with these keys:
+---               argument, a table with these keys:              *event-args*
 ---               • id: (number) autocommand id
 ---               • event: (string) name of the triggered event
 ---                 `autocmd-events`
@@ -907,7 +907,7 @@ function vim.api.nvim_create_augroup(name, opts) end
 ---               • 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

runtime/lua/vim/_meta/options.lua

@@ -7446,6 +7446,7 @@ vim.bo.vts = vim.bo.vartabstop
 ---
 --- 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.

runtime/lua/vim/highlight.lua

@@ -1,26 +1,3 @@
----@brief
----
---- 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}
---- ```
----
---- If you want to exclude visual selections from highlighting on yank, use:
----
---- ```vim
---- au TextYankPost * silent! lua vim.highlight.on_yank {on_visual=false}
---- ```
----
-
 local api = vim.api
 
 local M = {}
@@ -97,7 +74,13 @@ local yank_ns = api.nvim_create_namespace('hlyank')
 local yank_timer --- @type uv.uv_timer_t?
 local yank_cancel --- @type fun()?
 
---- Highlight the yanked text
+--- Highlight the yanked text during a |TextYankPost| event.
+---
+--- Add the following to your `init.vim`:
+---
+--- ```vim
+--- autocmd TextYankPost * silent! lua vim.highlight.on_yank {higroup='Visual', timeout=300}
+--- ```
 ---
 --- @param opts table|nil Optional parameters
 ---              - higroup   highlight group for yanked region (default "IncSearch")

runtime/lua/vim/iter.lua

@@ -450,20 +450,24 @@ function Iter:join(delim)
   return table.concat(self:totable(), delim)
 end
 
---- 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 }
+--- vim.iter({ a = 1, b = 2, c = 3, d = 4 })
---- local it = vim.iter(t)
+---   :filter(function(k, v) return v % 2 == 0 end)
---- it:filter(function(k, v) return v % 2 == 0 end)
+---   :fold({}, function(acc, k, v)
---- it:fold({}, function(t, k, v)
+---     acc[k] = v
----   t[k] = v
+---     return acc
----   return t
+---   end) --> { b = 2, d = 4 }
---- 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 }
 --- ```
 ---
 ---@generic A

scripts/movedocs.pl

@@ -1,180 +0,0 @@
-#!/usr/bin/perl
-
-use strict;
-use warnings;
-
-if ($ARGV[0] eq '--help') {
-  print << "EOF";
-Usage:
-
-  $0 file.h file.c
-
-Removes documentation attached to function declarations in file.h and adds them 
-to function definitions found in file.c.
-
-  $0 file.c
-
-Moves documentation attached to function declaration present in the same file as 
-the definition.
-EOF
-  exit 0;
-}
-
-my $hfile = shift @ARGV;
-my @cfiles = @ARGV;
-
-my %docs = ();
-my $F;
-
-sub write_lines {
-  my $file = shift;
-  my @lines = @_;
-
-  my $F;
-
-  open $F, '>', $file;
-  print $F (join "", @lines);
-  close $F;
-}
-
-if (@cfiles) {
-  open $F, '<', $hfile
-    or die "Failed to open $hfile.";
-
-  my @hlines = ();
-
-  my $lastdoc = '';
-
-  while (<$F>) {
-    if (/^\/\/\/?/) {
-      $lastdoc .= $_;
-    } elsif (/^\S.*?(\w+)\(.*(?:,|\);?|FUNC_ATTR_\w+;?)$/) {
-      die "Documentation for $1 was already defined" if (defined $docs{$1});
-      if ($lastdoc ne '') {
-        $docs{$1} = $lastdoc;
-        $lastdoc = '';
-      }
-      push @hlines, $_;
-    } elsif ($lastdoc ne '') {
-      push @hlines, $lastdoc;
-      $lastdoc = '';
-      push @hlines, $_;
-    } else {
-      push @hlines, $_;
-    }
-  }
-
-  close $F;
-
-  my %clines_hash = ();
-
-  for my $cfile (@cfiles) {
-    open $F, '<', $cfile
-      or die "Failed to open $cfile.";
-
-    my @clines = ();
-
-    while (<$F>) {
-      if (/^\S.*?(\w+)\(.*[,)]$/ and defined $docs{$1}) {
-        push @clines, $docs{$1};
-        delete $docs{$1};
-      } elsif (/^(?!static\s)\S.*?(\w+)\(.*[,)]$/ and not defined $docs{$1}) {
-        print STDERR "Documentation not defined for $1\n";
-      }
-      push @clines, $_;
-    }
-
-    close $F;
-
-    $clines_hash{$cfile} = \@clines;
-  }
-
-  while (my ($func, $value) = each %docs) {
-    die "Function not found: $func\n";
-  }
-
-  write_lines($hfile, @hlines);
-  while (my ($cfile, $clines) = each %clines_hash) {
-    write_lines($cfile, @$clines);
-  }
-} else {
-  open $F, '<', $hfile;
-
-  my @lines;
-
-  my $lastdoc = '';
-  my $defstart = '';
-  my $funcname;
-
-  sub clear_lastdoc {
-    if ($lastdoc ne '') {
-      push @lines, $lastdoc;
-      $lastdoc = '';
-    }
-  }
-
-  sub record_lastdoc {
-    my $funcname = shift;
-    if ($lastdoc ne '') {
-      $docs{$funcname} = $lastdoc;
-      $lastdoc = '';
-    }
-  }
-
-  sub add_doc {
-    my $funcname = shift;
-    if (defined $docs{$funcname}) {
-      push @lines, $docs{$funcname};
-      delete $docs{$funcname};
-    }
-  }
-
-  sub clear_defstart {
-    push @lines, $defstart;
-    $defstart = '';
-  }
-
-  while (<$F>) {
-    if (/\/\*/ .. /\*\// and not /\/\*.*?\*\//) {
-      push @lines, $_;
-    } elsif (/^\/\/\/?/) {
-      $lastdoc .= $_;
-    } elsif (/^\S.*?(\w+)\(.*(?:,|(\);?))$/) {
-      if (not $2) {
-        $defstart .= $_;
-        $funcname = $1;
-      } elsif ($2 eq ');') {
-        record_lastdoc $1;
-        push @lines, $_;
-      } elsif ($2 eq ')') {
-        clear_lastdoc;
-        add_doc $1;
-        push @lines, $_;
-      }
-    } elsif ($defstart ne '') {
-      $defstart .= $_;
-      if (/[{}]/) {
-        clear_lastdoc;
-        clear_defstart;
-      } elsif (/\);$/) {
-        record_lastdoc $funcname;
-        clear_defstart;
-      } elsif (/\)$/) {
-        clear_lastdoc;
-        add_doc $funcname;
-        clear_defstart;
-      }
-    } else {
-      clear_lastdoc;
-      push @lines, $_;
-    }
-  }
-
-  close $F;
-
-  while (my ($func, $value) = each %docs) {
-    die "Function not found: $func\n";
-  }
-
-  write_lines($hfile, @lines);
-}

src/nvim/api/autocmd.c

@@ -381,15 +381,15 @@ cleanup:
 ///             - desc (string) optional: description (for documentation and troubleshooting).
 ///             - callback (function|string) optional: Lua function (or 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
+///             value (not `false` or `nil`) to delete the autocommand. Receives one argument,
-///             with these keys:
+///             a table with these keys: [event-args]()
 ///                 - id: (number) autocommand id
 ///                 - event: (string) name of the triggered event |autocmd-events|
 ///                 - group: (number|nil) autocommand group id, if any
 ///                 - match: (string) expanded value of [<amatch>]
 ///                 - buf: (number) expanded value of [<abuf>]
 ///                 - file: (string) expanded value of [<afile>]
-///                 - data: (any) arbitrary data passed from [nvim_exec_autocmds()]
+///                 - data: (any) arbitrary data passed from [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 autocommand

src/nvim/channel.c

@@ -544,10 +544,9 @@ uint64_t channel_from_stdio(bool rpc, CallbackReader on_output, const char **err
   }
 #else
   if (embedded_mode) {
-    // In embedded mode redirect stdout and stdin to stderr, since they are used for the UI channel.
+    // Redirect stdout/stdin (the UI channel) to stderr. Use fnctl(F_DUPFD_CLOEXEC) instead of dup()
-    // NOTE: fnctl with F_DUPFD_CLOEXEC is used instead of dup to prevent child processes from
+    // to prevent child processes from inheriting the file descriptors, which are used by UIs to
-    // inheriting the file descriptors, which make it impossible for UIs to detect when nvim exits
+    // detect when Nvim exits.
-    // while one or more of its child processes are still running.
     stdin_dup_fd = fcntl(STDIN_FILENO, F_DUPFD_CLOEXEC, STDERR_FILENO + 1);
     stdout_dup_fd = fcntl(STDOUT_FILENO, F_DUPFD_CLOEXEC, STDERR_FILENO + 1);
     dup2(STDERR_FILENO, STDOUT_FILENO);

src/nvim/options.lua

@@ -9310,6 +9310,7 @@ return {
 
         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.