Merge #34541 docs

runtime/doc/api.txt

@@ -2222,7 +2222,7 @@ whether a buffer is loaded.
 
 
 nvim_buf_attach({buffer}, {send_buffer}, {opts})           *nvim_buf_attach()*
-    Activates buffer-update events on a channel, or as Lua callbacks.
+    Activates |api-buffer-updates| events on a channel, or as Lua callbacks.
 
     Example (Lua): capture buffer updates in a global `events` variable (use
     "vim.print(events)" to see its contents): >lua
@@ -2875,7 +2875,7 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts})
                   • hl_eol : when true, for a multiline highlight covering the
                     EOL of a line, continue the highlight for the rest of the
                     screen line (just like for diff and cursorline highlight).
-                  • virt_text : virtual text to link to this mark. A list of
+                  • virt_text : *virtual-text* to link to this mark. A list of
                     `[text, highlight]` tuples, each representing a text chunk
                     with specified highlight. `highlight` element can either
                     be a single highlight group, or an array of multiple

runtime/doc/autocmd.txt

@@ -78,6 +78,9 @@ exception is that "<sfile>" is expanded when the autocmd is defined.  Example:
 	:au BufNewFile,BufRead *.html so <sfile>:h/html.vim
 
 Here Vim expands <sfile> to the name of the file containing this line.
+Use <script> instead to avoid that: >
+
+	:au BufNewFile,BufRead *.html so <script>:h/html.vim
 
 `:autocmd` adds to the list of autocommands regardless of whether they are
 already present.  When your .vimrc file is sourced twice, the autocommands
@@ -87,7 +90,7 @@ that you can easily clear them: >
 	augroup vimrc
 	  " Remove all vimrc autocommands
 	  autocmd!
-	  au BufNewFile,BufRead *.html so <sfile>:h/html.vim
+	  au BufNewFile,BufRead *.html so <script>:h/html.vim
 	augroup END
 
 If you don't want to remove all autocommands, you can instead use a variable

runtime/doc/channel.txt

@@ -189,17 +189,17 @@ If you want to type input for the job in a Vim window you have a few options:
 A prompt buffer is created by setting 'buftype' to "prompt". You would
 normally only do that in a newly created buffer.
 
-The user can edit and enter text at the very last line of the buffer.  When
-pressing Enter in the prompt line the callback set with |prompt_setcallback()|
-is invoked. To enter multiple lines user can use Shift+Enter that'd add a new
-line. The final Enter submits the lines to  |prompt_setcallback()|. It would
-normally send the line to a job. Another callback would receive the output
-from the job and display it in the buffer, below the prompt (and above the
-next prompt).
+The user can edit and enter text at the very last line of the buffer. Pressing
+Enter in the prompt line invokes the |prompt_setcallback()| callback. Use
+Shift+Enter to add a new line without submitting the prompt, or paste
+multiline text using any |put| or |paste| command. The callback is typically
+expected to process the prompt and show results by appending to the buffer,
+below the prompt (and above the next prompt).
 
-Only the text after the last prompt, is editable. The rest of the buffer is
-not modifiable with Normal mode commands.  It can be modified by calling
-functions, such as |append()|.  Using other commands may mess up the buffer.
+Only the text after the last prompt (starting from the |':| mark), is
+user-editable. The rest of the buffer is not modifiable with Normal mode
+commands.  It can be modified by functions such as |append()|.  Using other
+commands may mess up the buffer.
 
 After setting 'buftype' to "prompt" Vim does not automatically start Insert
 mode, use `:startinsert` if you want to enter Insert mode, so that the user

runtime/doc/cmdline.txt

@@ -937,14 +937,6 @@ Note: these are typed literally, they are not special keys!
 		   events).
 		   When the match is with a file name, it is expanded to the
 		   full path.
-							*:<sfile>* *<sfile>*
-	<sfile>    When executing a `:source` command, is replaced with the
-		   file name of the sourced file.  *E498*
-		   When executing a function, is replaced with the call stack,
-		   as with <stack> (this is for backwards compatibility, using
-		   <stack> or <script> is preferred).
-		   Note that filename-modifiers are useless when <sfile> is
-		   not used inside a script.
 							*:<stack>* *<stack>*
 	<stack>	   is replaced with the call stack, using
 		   "function {function-name}[{lnum}]" for a function line
@@ -952,7 +944,7 @@ Note: these are typed literally, they are not special keys!
 		   ".." in between items.  E.g.:
 		   "function {function-name1}[{lnum}]..{function-name2}[{lnum}]"
 		   If there is no call stack you get error *E489* .
-							*:<script>* *<script>*
+							*:<script>* *<script>* *E498*
 	<script>   When executing a `:source` command, is replaced with the file
 		   name of the sourced file.  When executing a function, is
 		   replaced with the file name of the script where it is
@@ -971,7 +963,7 @@ Note: these are typed literally, they are not special keys!
 							 *filename-modifiers*
 *:_%:* *::8* *::p* *::.* *::~* *::h* *::t* *::r* *::e* *::s* *::gs* *::S*
      *%:8* *%:p* *%:.* *%:~* *%:h* *%:t* *%:r* *%:e* *%:s* *%:gs* *%:S*
-The file name modifiers can be used after "%", "#", "#n", "<cfile>", "<sfile>",
+The file name modifiers can be used after "%", "#", "#n", "<cfile>", "<script>",
 "<afile>" or "<abuf>".  They are also used with the |fnamemodify()| function.
 These modifiers can be given, in this order:
 	:p	Make file name a full path.  Must be the first modifier.  Also

runtime/doc/deprecated.txt

@@ -330,13 +330,12 @@ UI EXTENSIONS
 • *term_background*	Unused. The terminal background color is now detected
 			by the Nvim core directly instead of the TUI.
 
-VARIABLES
+VIMSCRIPT
+• *<sfile>*		Use |<script>| or |<stack>| 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')`
-
-VIMSCRIPT
 • *buffer_exists()*	Obsolete name for |bufexists()|.
 • *buffer_name()*	Obsolete name for |bufname()|.
 • *buffer_number()*	Obsolete name for |bufnr()|.

runtime/doc/motion.txt

@@ -795,14 +795,6 @@ m<  or  m>		Set the |'<| or |'>| mark.  Useful to change what the
 			Note that the Visual mode cannot be set, only the
 			start and end position.
 
-						*m:*
-m:			Special mark for prompt buffers. It always shows the
-			line where current prompt starts. Text from this line
-			and below will be submitted when user submits.
-			Note: This mark is readonly. You can not modify it's
-			location. Also this mark is unique to prompt buffers as
-			a result not available in regular buffers.
-
 						*:ma* *:mark* *E191*
 :[range]ma[rk] {a-zA-Z'}
 			Set mark {a-zA-Z'} at last line number in [range],
@@ -950,6 +942,11 @@ was made yet in the current file.
 			the position will be on the last character.
 			To jump to older changes use |g;|.
 
+							*':* *`:*
+':			In a prompt buffer, the start of the current prompt.
+			Text from this line until end of buffer will be
+			submitted when the user submits the prompt.
+
 							*'(* *`(*
 '(  `(			To the start of the current sentence, like the |(|
 			command.

runtime/doc/news.txt

@@ -18,6 +18,10 @@ BREAKING CHANGES IN HEAD OR EXPERIMENTAL                    *news-breaking-dev*
 The following changes to UNRELEASED features were made during the development
 cycle (Nvim HEAD, the "master" branch).
 
+EVENTS
+
+• Renamed "nvim.find_exrc" |default-autocmds| group to "nvim.exrc".
+
 EXPERIMENTS
 
 • todo

runtime/doc/quickref.txt

@@ -1112,10 +1112,10 @@ Context-sensitive completion on the command-line:
 			   expected) (see |WORD|)
 |:<cfile>|  <cfile>	file name under the cursor (only where a file name is
 			   expected)
-|:<sfile>|  <sfile>	file name of a ":source"d file, within that file (only
+|:<script>| <script>	file name of a ":source"d file, within that file (only
 			   where a file name is expected)
 
-		After "%", "#", "<cfile>", "<sfile>" or "<afile>"
+		After "%", "#", "<cfile>", "<script>" or "<afile>"
 		|::p|	    :p		full path
 		|::h|	    :h		head (file name removed)
 		|::t|	    :t		tail (file name only)

runtime/doc/repeat.txt

@@ -413,12 +413,12 @@ make a top-down hierarchy of script files.  The ':source' command can be
 nested as deep as the number of files that can be opened at one time (about
 15).  The ':source!' command can be nested up to 15 levels deep.
 
-You can use the "<sfile>" string (literally, this is not a special key) inside
+You can use the "<script>" string (literally, this is not a special key) inside
 of the sourced file, in places where a file name is expected.  It will be
 replaced by the file name of the sourced file.  For example, if you have a
 "other.vimrc" file in the same directory as your |init.vim| file, you can
 source it from your |init.vim| file with this command: >
-	:source <sfile>:h/other.vimrc
+	:source <script>:h/other.vimrc
 
 In script files terminal-dependent key codes are represented by
 terminal-independent two character codes.  This means that they can be used

runtime/doc/syntax.txt

@@ -4616,11 +4616,11 @@ two different ways:
 	  that list. >
 
    " In perl.vim:
-   :syntax include @Pod <sfile>:p:h/pod.vim
+   :syntax include @Pod <script>:p:h/pod.vim
    :syntax region perlPOD start="^=head" end="^=cut" contains=@Pod
 <
 	  When {file-name} is an absolute path (starts with "/", "c:", "$VAR"
-	  or "<sfile>") that file is sourced.  When it is a relative path
+	  or "<script>") that file is sourced.  When it is a relative path
 	  (e.g., "syntax/pod.vim") the file is searched for in 'runtimepath'.
 	  All matching files are loaded.  Using a relative path is
 	  recommended, because it allows a user to replace the included file

runtime/doc/usr_41.txt

@@ -2556,7 +2556,7 @@ The following example shows how it's done: >
 		map <F19> :call BufNetWrite('something')<CR>
 
 		let s:did_load = 1
-		exe 'au FuncUndefined BufNet* source ' .. expand('<sfile>')
+		exe 'au FuncUndefined BufNet* source ' .. expand('<script>')
 		finish
 	endif
 
@@ -2592,7 +2592,7 @@ startup.  This is the sequence of events that happens:
    event.  Since the pattern "BufNet*" matches the invoked function, the
    command "source fname" will be executed.  "fname" will be equal to the name
    of the script, no matter where it is located, because it comes from
-   expanding "<sfile>" (see |expand()|).
+   expanding "<script>" (see |expand()|).
 
 4. The script is sourced again, the "s:did_load" variable exists and the
    functions are defined.

runtime/doc/usr_44.txt

@@ -511,7 +511,7 @@ syntax file.  The ":syntax include" command reads in a syntax file and stores
 the elements it defined in a syntax cluster.  For Perl, the statements are as
 follows: >
 
-	:syntax include @Pod <sfile>:p:h/pod.vim
+	:syntax include @Pod <script>:p:h/pod.vim
 	:syntax region perlPOD start=/^=head/ end=/^=cut/ contains=@Pod
 
 When "=head" is found in a Perl file, the perlPOD region starts.  In this
@@ -522,7 +522,7 @@ region ends and we go back to the items defined in the Perl file.
 command in the included file.  And an argument such as "contains=ALL" will
 only contain items defined in the included file, not in the file that includes
 it.
-   The "<sfile>:p:h/" part uses the name of the current file (<sfile>),
+   The "<script>:p:h/" part uses the name of the current file (<script>),
 expands it to a full path (:p) and then takes the head (:h).  This results in
 the directory name of the file.  This causes the pod.vim file in the same
 directory to be included.

runtime/doc/vim_diff.txt

@@ -210,7 +210,7 @@ nvim.swapfile:
   swapfile is owned by a running Nvim process. Shows |W325| "Ignoring
   swapfile…" message.
 
-nvim.find_exrc:
+nvim.exrc:
 - VimEnter: Extend 'exrc' to also search for project-local configuration files
   in all parent directories.
 
@@ -304,6 +304,10 @@ Commands:
   User commands can support |:command-preview| to show results as you type
 - |:write| with "++p" flag creates parent directories.
 
+Editor:
+- |prompt-buffer| supports multiline input/paste, undo/redo, and o/O normal
+  commands.
+
 Events (autocommands):
 - Fixed inconsistent behavior in execution of nested autocommands #23368
 - |RecordingEnter|
@@ -472,12 +476,6 @@ Variables:
   instead of always being strings. |v:option_old| is now the old global value
   for all global-local options, instead of just string global-local options.
 
-Prompt-Buffer:
-- supports multiline inputs.
-- supports multiline paste.
-- supports undo/redo on current prompt.
-- supports normal o/O operations.
-
 Vimscript:
 - |:redir| nested in |execute()| works.
 

runtime/doc/vimfn.txt

@@ -2106,7 +2106,7 @@ expand({string} [, {nosuf} [, {list}]])                               *expand()*
 			<abuf>		autocmd buffer number (as a String!)
 			<amatch>	autocmd matched name
 			<cexpr>		C expression under the cursor
-			<sfile>		sourced script file or function name
+			<sfile>		deprecated, use <script> or <stack>
 			<slnum>		sourced script line number or function
 					line number
 			<sflnum>	script file line number, also when in

runtime/lua/vim/_defaults.lua

@@ -935,7 +935,7 @@ do
   end
 
   vim.api.nvim_create_autocmd('VimEnter', {
-    group = vim.api.nvim_create_augroup('nvim.find_exrc', {}),
+    group = vim.api.nvim_create_augroup('nvim.exrc', {}),
     desc = 'Find exrc files in parent directories',
     callback = function()
       if not vim.o.exrc then

runtime/lua/vim/_meta/api.lua

@@ -159,7 +159,7 @@ function vim.api.nvim__unpack(str) end
 --- @return integer
 function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start, col_end) end
 
---- Activates buffer-update events on a channel, or as Lua callbacks.
+--- Activates `api-buffer-updates` events on a channel, or as Lua callbacks.
 ---
 --- Example (Lua): capture buffer updates in a global `events` variable
 --- (use "vim.print(events)" to see its contents):
@@ -575,7 +575,7 @@ function vim.api.nvim_buf_line_count(buffer) end
 ---            EOL of a line, continue the highlight for the rest
 ---            of the screen line (just like for diff and
 ---            cursorline highlight).
---- - virt_text : virtual text to link to this mark.
+--- - virt_text : [](virtual-text) to link to this mark.
 ---     A list of `[text, highlight]` tuples, each representing a
 ---     text chunk with specified highlight. `highlight` element
 ---     can either be a single highlight group, or an array of

runtime/lua/vim/_meta/vimfn.lua

@@ -1863,7 +1863,7 @@ function vim.fn.exp(expr) end
 ---   <abuf>    autocmd buffer number (as a String!)
 ---   <amatch>  autocmd matched name
 ---   <cexpr>    C expression under the cursor
----   <sfile>    sourced script file or function name
+---   <sfile>    deprecated, use <script> or <stack>
 ---   <slnum>    sourced script line number or function
 ---       line number
 ---   <sflnum>  script file line number, also when in

src/nvim/api/buffer.c

@@ -87,7 +87,7 @@ Integer nvim_buf_line_count(Buffer buffer, Error *err)
   return buf->b_ml.ml_line_count;
 }
 
-/// Activates buffer-update events on a channel, or as Lua callbacks.
+/// Activates |api-buffer-updates| events on a channel, or as Lua callbacks.
 ///
 /// Example (Lua): capture buffer updates in a global `events` variable
 /// (use "vim.print(events)" to see its contents):

src/nvim/api/extmark.c

@@ -407,7 +407,7 @@ Array nvim_buf_get_extmarks(Buffer buffer, Integer ns_id, Object start, Object e
 ///                          EOL of a line, continue the highlight for the rest
 ///                          of the screen line (just like for diff and
 ///                          cursorline highlight).
-///               - virt_text : virtual text to link to this mark.
+///               - virt_text : [](virtual-text) to link to this mark.
 ///                   A list of `[text, highlight]` tuples, each representing a
 ///                   text chunk with specified highlight. `highlight` element
 ///                   can either be a single highlight group, or an array of

src/nvim/eval.lua

@@ -2413,7 +2413,7 @@ M.funcs = {
       	<abuf>		autocmd buffer number (as a String!)
       	<amatch>	autocmd matched name
       	<cexpr>		C expression under the cursor
-      	<sfile>		sourced script file or function name
+      	<sfile>		deprecated, use <script> or <stack>
       	<slnum>		sourced script line number or function
       			line number
       	<sflnum>	script file line number, also when in

test/functional/legacy/prompt_buffer_spec.lua

@@ -247,7 +247,7 @@ describe('prompt buffer', function()
       Close]])
   end)
 
-  it('can insert mutli line text', function()
+  it('can insert multiline text', function()
     source_script()
     feed('line 1<s-cr>line 2<s-cr>line 3')
     screen:expect([[
@@ -275,7 +275,7 @@ describe('prompt buffer', function()
     ]])
   end)
 
-  it('can paste multiline text', function()
+  it('can put (p) multiline text', function()
     source_script()
     fn('setreg', 'a', 'line 1\nline 2\nline 3')
     feed('<esc>"ap')
@@ -302,7 +302,7 @@ describe('prompt buffer', function()
     ]])
   end)
 
-  it('undo works for current prompt', function()
+  it('can undo current prompt', function()
     source_script()
     -- text editiing alowed in current prompt
     feed('tests-initial<esc>')
@@ -507,19 +507,18 @@ describe('prompt buffer', function()
     ]])
   end)
 
-  it(': mark follows current prompt', function()
+  it("sets the ': mark", function()
     source_script()
     feed('asdf')
     eq({ 1, 1 }, api.nvim_buf_get_mark(0, ':'))
     feed('<cr>')
     eq({ 3, 1 }, api.nvim_buf_get_mark(0, ':'))
-  end)
+    -- Multiline prompt.
+    feed('<s-cr>line1<s-cr>line2<s-cr>line3<cr>')
+    eq({ 11, 1 }, api.nvim_buf_get_mark(0, ':'))
 
-  it(': mark only available in prompt buffer', function()
-    source_script()
-    feed('asdf')
-    eq({ 1, 1 }, api.nvim_buf_get_mark(0, ':'))
+    -- ': mark is only available in prompt buffer.
     source('set buftype=')
-    eq(false, pcall(api.nvim_buf_get_mark, 0, ':'))
+    eq("Invalid mark name: ':'", t.pcall_err(api.nvim_buf_get_mark, 0, ':'))
   end)
 end)