docs: misc neovim#24163

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

fix neovim#23251
fix neovim#27367
ref neovim#2252 (comment)

Helped-by: Daniel Kongsgaard <[email protected]>
Co-authored-by: Kevin Pham <[email protected]>

Author: 2 people

CMakeLists.txt

@@ -1,7 +1,9 @@
 # CMAKE REFERENCE
-#   intro: https://codingnest.com/basic-cmake/
-#   best practices (3.0+): https://gist.github.com/mbinna/c61dbb39bca0e4fb7d1f73b0d66a4fd1
-#   pitfalls: https://izzys.casa/2019/02/everything-you-never-wanted-to-know-about-cmake/
+#   - intro: https://codingnest.com/basic-cmake/
+#   - best practices (3.0+): https://gist.github.com/mbinna/c61dbb39bca0e4fb7d1f73b0d66a4fd1
+#   - 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,33 +82,36 @@ 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:
-
-```
-<type>([optional scope]): <description>
-
-[optional body]
-
-[optional footer(s)]
-```
+the VCS/git logs more valuable. The structure of a commit message is:
+
+    type(scope): subject
+
+    Problem:
+    ...
+
+    Solution:
+    ...
+
+- Commit message **subject** (you can **ignore this for "fixup" commits** or any commits you expect to be squashed):
+    - Prefix with a [_type_](https://github.com/commitizen/conventional-commit-types/blob/master/index.json):
+        - `build ci docs feat fix perf refactor revert test vim-patch`
+    - Append an optional `(scope)` such as `(lsp)`, `(treesitter)`, `(float)`, …
+    - Use the _imperative voice_: "Fix bug" rather than "Fixed bug" or "Fixes bug."
+    - Keep it short (under 72 characters).
+- Commit message **body** (detail):
+    - Concisely describe the Problem/Solution in the commit **body**. [Describing the problem](https://lamport.azurewebsites.net/pubs/state-the-problem.pdf)
+      _independently of the solution_ often leads to a better understanding for you, reviewers, and future readers.
+      ```
+      Problem:
+
+      Solution:
+      ```
+- Indicate breaking API changes with "!" after the type, and a "BREAKING CHANGE" footer. Example:
+  ```
+  refactor(provider)!: drop support for Python 2
 
-- Prefix the commit subject with one of these [_types_](https://github.com/commitizen/conventional-commit-types/blob/master/index.json):
-    - `build`, `ci`, `docs`, `feat`, `fix`, `perf`, `refactor`, `revert`, `test`, `vim-patch`
-    - You can **ignore this for "fixup" commits** or any commits you expect to be squashed.
-- Append optional scope to _type_ 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."
-- Try to keep the first line under 72 characters.
-- A blank line must follow the subject.
-- Breaking API changes must be indicated by
-    1. "!" after the type/scope, and
-    2. a "BREAKING CHANGE" footer describing the change.
-       Example:
-       ```
-       refactor(provider)!: drop support for Python 2
-
-       BREAKING CHANGE: refactor to use Python 3 features since Python 2 is no longer supported.
-       ```
+  BREAKING CHANGE: refactor to use Python 3 features since Python 2 is no longer supported.
+  ```
 
 ### News
 

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,
-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

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

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:

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,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: ~

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.