Merge pull request #38981 from justinmk/release

backport: docs

INSTALL.md

@@ -19,7 +19,8 @@ Downloads are available on the [Releases](https://github.com/neovim/neovim/relea
     * [macOS arm64](https://github.com/neovim/neovim/releases/latest/download/nvim-macos-arm64.tar.gz)
     * [Linux x86_64](https://github.com/neovim/neovim/releases/latest/download/nvim-linux-x86_64.tar.gz)
     * [Linux arm64](https://github.com/neovim/neovim/releases/latest/download/nvim-linux-arm64.tar.gz)
-    * [Windows](https://github.com/neovim/neovim/releases/latest/download/nvim-win64.msi)
+    * [Windows x86_64](https://github.com/neovim/neovim/releases/latest/download/nvim-win64.msi)
+    * [Windows arm64](https://github.com/neovim/neovim/releases/latest/download/nvim-win-arm64.msi)
 * Latest [development prerelease](https://github.com/neovim/neovim/releases/nightly)
 
 
@@ -53,6 +54,7 @@ Several Neovim GUIs are available from scoop (extras): [scoop.sh/#/apps?q=neovim
 ### Pre-built archives
 
 0. If you are missing `VCRUNTIME170.dll`, install the [Visual Studio C++ redistributable](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist) (choose x86_64 or x86 depending on your system).
+    - Hint: if you have scoop, try: `scoop install vcredist`
 1. Choose a package (**nvim-winXX.zip**) from the [releases page](https://github.com/neovim/neovim/releases).
 2. Unzip the package. Any location is fine, administrator privileges are _not_ required.
     - `$VIMRUNTIME` will be set to that location automatically.

runtime/doc/cmdline.txt

@@ -397,6 +397,7 @@ CTRL-D		List names that match the pattern in front of the cursor.
 		to the end.
 		The 'wildoptions' option can be set to "tagfile" to list the
 		file of matching tags.
+
 				*c_CTRL-I* *c_wildchar* *c_<Tab>* */_<Tab>*
 'wildchar' option
 		A match is done on the pattern in front of the cursor.  The
@@ -412,20 +413,25 @@ CTRL-D		List names that match the pattern in front of the cursor.
 		literal <Tab> instead of triggering completion.
 
 		The behavior can be changed with the 'wildmode' option.
+
 							*c_<S-Tab>*
 <S-Tab>		Like 'wildchar' or <Tab>, but begin with the last match and
 		then go to the previous match.
+
 							*c_CTRL-N*
 CTRL-N		After using 'wildchar' which got multiple matches, go to next
 		match.  Otherwise recall more recent command-line from
 		history.
+
 							*c_CTRL-P*
 CTRL-P		After using 'wildchar' which got multiple matches, go to
 		previous match.  Otherwise recall older command-line from
 		history.
+
 							*c_CTRL-A*
 CTRL-A		All names that match the pattern in front of the cursor are
 		inserted.
+
 							*c_CTRL-L*
 CTRL-L		A match is done on the pattern in front of the cursor.  If
 		there is one match, it is inserted in place of the pattern.
@@ -439,19 +445,22 @@ CTRL-L		A match is done on the pattern in front of the cursor.  If
 		'ignorecase' and 'smartcase' are set and the command line has
 		no uppercase characters, the added character is converted to
 		lowercase.
+
 	                                            *c_CTRL-G* */_CTRL-G*
-CTRL-G		When 'incsearch' is set, entering a search pattern for "/" or
-		"?" and the current match is displayed then CTRL-G will move
-		to the next match (does not take |search-offset| into account)
-		Use CTRL-T to move to the previous match.  Hint: on a regular
-		keyboard G is below T.
+CTRL-G		While the "/" or "?" 'incsearch' prompt is active, CTRL-G
+		moves to the next match (without changing the |jumplist|).
+		Does not take |search-offset| into account.
+
+		Use CTRL-T to move to the previous match.
+		Mnemonic: on a regular keyboard G is below T.
+
 	                                            *c_CTRL-T* */_CTRL-T*
-CTRL-T		When 'incsearch' is set, entering a search pattern for "/" or
-		"?" and the current match is displayed then CTRL-T will move
-		to the previous match (does not take |search-offset| into
-		account).
-		Use CTRL-G to move to the next match.  Hint: on a regular
-		keyboard T is above G.
+CTRL-T		While the "/" or "?" 'incsearch' prompt is active, CTRL-T
+		moves to the previous match (without changing the |jumplist|).
+		Does not take |search-offset| into account.
+
+		Use CTRL-G to move to the next match.
+		Mnemonic: on a regular keyboard T is above G.
 
 The 'wildchar' option defaults to <Tab> (CTRL-E when in Vi compatible mode; in
 a previous version <Esc> was used).  In the pattern standard |wildcards| are

runtime/doc/dev_arch.txt

@@ -69,9 +69,11 @@ Lua code lives in one of four places:
      - ❌ nvim.difftool
      - ❌ nvim.tohtml
      - ❌ nvim.undotree
-2. Runtime: `runtime/lua/vim/`. Lazy-loaded modules. Examples: `treesitter`, `lpeg`.
-3. Core: `runtime/lua/vim/_core/`. Compiled-into Nvim binary, may directly
-   interact with Nvim internals. Only available in the main thread. See
+2. Stdlib: `runtime/lua/vim/`. Modules on `vim.*`, lazy-loaded (as opposed to
+   "Core" modules, see below).
+   - Examples: `vim.treesitter`, `vim.lpeg`.
+3. Core: `runtime/lua/vim/_core/`. Internal-only, compiled-in modules. May
+   directly interact with Nvim internals. Only available in main thread. See
    |dev-lua-builtin| below.
 4. "Shared" core: `runtime/lua/vim/_core/shared.lua`. Pure Lua functions which
    always are available. Used in the test runner, and worker threads/processes

runtime/doc/lua.txt

@@ -4260,8 +4260,8 @@ by |vim.Pos| objects.
     To create a new |vim.Pos| object, call `vim.pos()`.
 
     Example: >lua
-        local pos1 = vim.pos(3, 5)
-        local pos2 = vim.pos(4, 0)
+        local pos1 = vim.pos(vim.api.nvim_get_current_buf(), 3, 5)
+        local pos2 = vim.pos(vim.api.nvim_get_current_buf(), 4, 0)
 
         -- Operators are overloaded for comparing two `vim.Pos` objects.
         if pos1 < pos2 then
@@ -4310,7 +4310,7 @@ Pos:to_lsp({position_encoding})                                 *Pos:to_lsp()*
         local pos = vim.pos(buf, 3, 5)
 
         -- Convert to LSP position, you can call it in a method style.
-        local lsp_pos = pos:lsp('utf-16')
+        local lsp_pos = pos:to_lsp('utf-16')
 <
 
     Parameters: ~
@@ -4380,13 +4380,13 @@ Provides operations to compare, calculate, and convert ranges represented by
     format conversions.
 
     Example: >lua
-        local pos1 = vim.pos(3, 5)
-        local pos2 = vim.pos(4, 0)
+        local pos1 = vim.pos(vim.api.nvim_get_current_buf(), 3, 5)
+        local pos2 = vim.pos(vim.api.nvim_get_current_buf(), 4, 0)
 
         -- Create a range from two positions.
         local range1 = vim.range(pos1, pos2)
         -- Or create a range from four integers representing start and end positions.
-        local range2 = vim.range(3, 5, 4, 0)
+        local range2 = vim.range(vim.api.nvim_get_current_buf(), 3, 5, 4, 0)
 
         -- Because `vim.Range` is end exclusive, `range1` and `range2` both represent
         -- a range starting at the row 3, column 5 and ending at where the row 3 ends

runtime/doc/options.txt

@@ -6334,8 +6334,8 @@ A jump table for the options with a short description can be found at |Q_op|.
 	  %-0{minwid}.{maxwid}{item}
 <
 	All fields except {item} are optional.  Use "%%" to show a literal "%"
-	char.  Setting this option to empty (`:set statusline=`) sets its
-	value to the default.
+	char.  Setting to empty (`:set statusline=`) sets the global value to
+	the default.
 
 							*stl-%!*
 	When the option starts with "%!" then it is used as an expression,

runtime/doc/plugins.txt

@@ -6,7 +6,7 @@
                                        Type |gO| to see the table of contents.
 
 ==============================================================================
-Plugins and modules included with Nvim                               *plugins*
+Plugins and modules included with Nvim                       *standard-plugin*
 
 Nvim includes various Lua and Vim plugins or modules which may provide
 commands (such as :TOhtml) or modules that you can optionally require() or

runtime/doc/usr_05.txt

@@ -276,7 +276,7 @@ The global plugins will be discussed first, then the filetype ones
 |add-filetype-plugin|.
 
 
-GLOBAL PLUGINS						*standard-plugin*
+GLOBAL PLUGINS
 
 When you start Vim, it will automatically load a number of global plugins.
 You don't have to do anything for this.  They add functionality that most

runtime/doc/usr_12.txt

@@ -233,9 +233,9 @@ For other ways to count words, lines and other items, see |count-items|.
 ==============================================================================
 *12.6*	Find a man page					*find-manpage*
 
-While editing a shell script or C program, you are using a command or function
-that you want to find the man page for (this is on Unix).  Let's first use a
-simple way: Move the cursor to the word you want to find help on and press >
+While editing a C program, you are using a function that you want to find the
+man page for (this is on Unix).  Let's first use a simple way: Move the cursor
+to the word you want to find help on and press >
 
 	K
 

runtime/doc/vimfn.txt

@@ -3653,7 +3653,7 @@ getfsize({fname})                                                   *getfsize()*
                   (`integer`)
 
 getftime({fname})                                                   *getftime()*
-		Returns the last modification time of the given file {fname}.
+		Returns the last modification time ("mtime") of file {fname}.
 		The value is measured as seconds since 1st Jan 1970, and may
 		be passed to |strftime()|.  See also
 		|localtime()| and |strftime()|.

runtime/lua/vim/_meta/options.lua

@@ -6756,8 +6756,8 @@ vim.wo.stc = vim.wo.statuscolumn
 --- ```
 ---
 --- All fields except {item} are optional.  Use "%%" to show a literal "%"
---- char.  Setting this option to empty (`:set statusline=`) sets its
---- value to the default.
+--- char.  Setting to empty (`:set statusline=`) sets the global value to
+--- the default.
 ---
 --- 						*stl-%!*
 --- When the option starts with "%!" then it is used as an expression,

runtime/lua/vim/_meta/vimfn.lua

@@ -3273,7 +3273,7 @@ function vim.fn.getfperm(fname) end
 --- @return integer
 function vim.fn.getfsize(fname) end
 
---- Returns the last modification time of the given file {fname}.
+--- Returns the last modification time ("mtime") of file {fname}.
 --- The value is measured as seconds since 1st Jan 1970, and may
 --- be passed to |strftime()|.  See also
 --- |localtime()| and |strftime()|.

runtime/lua/vim/pos.lua

@@ -18,8 +18,8 @@ local validate = vim.validate
 ---
 --- Example:
 --- ```lua
---- local pos1 = vim.pos(3, 5)
---- local pos2 = vim.pos(4, 0)
+--- local pos1 = vim.pos(vim.api.nvim_get_current_buf(), 3, 5)
+--- local pos2 = vim.pos(vim.api.nvim_get_current_buf(), 4, 0)
 ---
 --- -- Operators are overloaded for comparing two `vim.Pos` objects.
 --- if pos1 < pos2 then
@@ -127,7 +127,7 @@ end
 --- local pos = vim.pos(buf, 3, 5)
 ---
 --- -- Convert to LSP position, you can call it in a method style.
---- local lsp_pos = pos:lsp('utf-16')
+--- local lsp_pos = pos:to_lsp('utf-16')
 --- ```
 ---@param position_encoding lsp.PositionEncodingKind
 function Pos:to_lsp(position_encoding)

runtime/lua/vim/range.lua

@@ -20,13 +20,13 @@ local api = vim.api
 ---
 --- Example:
 --- ```lua
---- local pos1 = vim.pos(3, 5)
---- local pos2 = vim.pos(4, 0)
+--- local pos1 = vim.pos(vim.api.nvim_get_current_buf(), 3, 5)
+--- local pos2 = vim.pos(vim.api.nvim_get_current_buf(), 4, 0)
 ---
 --- -- Create a range from two positions.
 --- local range1 = vim.range(pos1, pos2)
 --- -- Or create a range from four integers representing start and end positions.
---- local range2 = vim.range(3, 5, 4, 0)
+--- local range2 = vim.range(vim.api.nvim_get_current_buf(), 3, 5, 4, 0)
 ---
 --- -- Because `vim.Range` is end exclusive, `range1` and `range2` both represent
 --- -- a range starting at the row 3, column 5 and ending at where the row 3 ends

src/nvim/api/vim.c

@@ -889,6 +889,7 @@ Union(Integer, String) nvim_echo(ArrayOf(Tuple(String, *HLGroupID)) chunks, Bool
   const int save_lines_left = lines_left;
   const bool save_msg_didany = msg_didany;
   // Similar truncation method to showmode().
+  // TODO(justinmk): drop _truncate feature after ui2 graduates?
   if (opts->_truncate) {
     no_wait_return++;
     lines_left = 0;

src/nvim/eval.lua

@@ -4100,7 +4100,7 @@ M.funcs = {
     args = 1,
     base = 1,
     desc = [=[
-      Returns the last modification time of the given file {fname}.
+      Returns the last modification time ("mtime") of file {fname}.
       The value is measured as seconds since 1st Jan 1970, and may
       be passed to |strftime()|.  See also
       |localtime()| and |strftime()|.

src/nvim/keycodes.c

@@ -635,11 +635,16 @@ int get_mouse_button(int code, bool *is_click, bool *is_drag)
   return 0;         // Shouldn't get here
 }
 
-/// Replace any terminal code strings with the equivalent internal representation.
+/// Encode `<key>` notation into Nvim's internal key representation. (Does NOT process raw terminal
+/// escape sequences, despite the legacy "termcode" terminology.)
 ///
-/// Used for the "from" and "to" part of a mapping, and the "to" part of a menu command.
-/// Any strings like "<C-UP>" are also replaced, unless `special` is false.
-/// K_SPECIAL by itself is replaced by K_SPECIAL KS_SPECIAL KE_FILLER.
+/// Parses keycode notation like `<C-Up>`, `<CR>`, `<Esc>`, `<F1>`, `<Leader>`, `<SID>`, and emits
+/// the corresponding K_SPECIAL byte sequences. Used for the lhs/rhs of mappings, the rhs of menu
+/// commands, and feedkeys input. K_SPECIAL by itself is replaced by K_SPECIAL KS_SPECIAL KE_FILLER.
+///
+/// Also handles `<C-v>` / backslash literal escapes (per 'cpoptions'), `<Leader>`/`<LocalLeader>`
+/// expansion, `<SID>` script-id substitution, and (unless REPTERM_NO_SIMPLIFY) simplifications like
+/// `<C-H>` => 0x08.
 ///
 /// When "flags" has REPTERM_FROM_PART, trailing <C-v> is included, otherwise it is removed (to make
 /// ":map xx ^V" map xx to nothing). When cpo_val contains CPO_BSLASH, a backslash can be used in

src/nvim/options.lua

@@ -8825,8 +8825,8 @@ local options = {
           %-0{minwid}.{maxwid}{item}
         <
         All fields except {item} are optional.  Use "%%" to show a literal "%"
-        char.  Setting this option to empty (`:set statusline=`) sets its
-        value to the default.
+        char.  Setting to empty (`:set statusline=`) sets the global value to
+        the default.
 
         						*stl-%!*
         When the option starts with "%!" then it is used as an expression,