commit aa8c86e8f357e4746bce3256dd860b70f80fb23e
parent 237bb9cb59d00264cdf21f5352fda7515c1b2e05
Author: Justin M. Keyes <justinkz@gmail.com>
Date: Wed, 18 Jun 2025 03:46:28 -0700
Merge #34541 docs
Diffstat:
21 files changed, 62 insertions(+), 70 deletions(-)
diff --git a/runtime/doc/api.txt b/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
diff --git a/runtime/doc/autocmd.txt b/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
diff --git a/runtime/doc/channel.txt b/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).
-
-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.
+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 (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
diff --git a/runtime/doc/cmdline.txt b/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
diff --git a/runtime/doc/deprecated.txt b/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()|.
diff --git a/runtime/doc/motion.txt b/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.
diff --git a/runtime/doc/news.txt b/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
diff --git a/runtime/doc/quickref.txt b/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)
diff --git a/runtime/doc/repeat.txt b/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
diff --git a/runtime/doc/syntax.txt b/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
diff --git a/runtime/doc/usr_41.txt b/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.
diff --git a/runtime/doc/usr_44.txt b/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.
diff --git a/runtime/doc/vim_diff.txt b/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.
diff --git a/runtime/doc/vimfn.txt b/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
diff --git a/runtime/lua/vim/_defaults.lua b/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
diff --git a/runtime/lua/vim/_meta/api.lua b/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
diff --git a/runtime/lua/vim/_meta/vimfn.lua b/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
diff --git a/src/nvim/api/buffer.c b/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):
diff --git a/src/nvim/api/extmark.c b/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
diff --git a/src/nvim/eval.lua b/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
diff --git a/test/functional/legacy/prompt_buffer_spec.lua b/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)
