docs: api, misc

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

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

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)