From a6584b205c5ce94ef9692d99e7e459cb19876691 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Wed, 10 Jun 2026 23:34:09 +0200 Subject: [PATCH] docs: misc --- runtime/doc/api.txt | 23 +++++++++++------- runtime/doc/windows.txt | 32 ++++++++++++-------------- runtime/lua/vim/_meta/api.gen.lua | 18 ++++++++------- src/nvim/api/vim.c | 18 ++++++++------- src/nvim/path.c | 6 ++--- test/functional/options/shell_spec.lua | 4 ++-- 6 files changed, 54 insertions(+), 47 deletions(-) diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index e6d180f25d..62eeed39a4 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -1267,12 +1267,19 @@ nvim_open_term({buf}, {opts}) *nvim_open_term()* be echoed directly by the terminal. This is useful to display ANSI terminal sequences returned as part of an RPC message, or similar. - Note: to directly initiate the terminal using the right size, display the - buffer in a configured window before calling this. For instance, for a - floating display, first create an empty buffer using |nvim_create_buf()|, - then display it using |nvim_open_win()|, and then call this function. Then - |nvim_chan_send()| can be called immediately to process sequences in a - virtual terminal having the intended size. + Note: |:ls| reports the buffer as "R" (running) until the channel is + closed. |chanclose()| + + Note: To initialize the terminal size, display the buffer in a window + first. E.g. for a floating display, + 1. Create an empty buffer using |nvim_create_buf()|. + + 2. Display it with |nvim_open_win()|. + + 3. Call nvim_open_term(). + + 4. Then calling |nvim_chan_send()| will process sequences in a virtual + terminal with the intended size (defined by the window width/height). Example: this `TermHl` command can be used to display and highlight raw ANSI termcodes, so you can use Nvim as a "scrollback pager" (for terminals @@ -1287,8 +1294,8 @@ nvim_open_term({buf}, {opts}) *nvim_open_term()* Since: 0.5.0 Parameters: ~ - • {buf} (`integer`) Buffer to use. Buffer contents (if any) will be - written to the PTY. + • {buf} (`integer`) Buffer which displays the PTY output. The initial + buffer contents (if any) will be written to the PTY. • {opts} (`vim.api.keyset.open_term`) Optional parameters. • force_crlf: (boolean, default true) Convert "\n" to "\r\n". • on_input: Lua callback for input sent, i e keypresses in diff --git a/runtime/doc/windows.txt b/runtime/doc/windows.txt index 1510dea847..3864639121 100644 --- a/runtime/doc/windows.txt +++ b/runtime/doc/windows.txt @@ -1131,25 +1131,23 @@ list of buffers. |unlisted-buffer| "[No Name]" no file name specified Indicators (chars in the same column are mutually exclusive): - u an unlisted buffer (only displayed when [!] is used) - |unlisted-buffer| - % the buffer in the current window - # the alternate buffer for ":e #" and CTRL-^ - a an active buffer: it is loaded and visible - h a hidden buffer: It is loaded, but currently not - displayed in a window |hidden-buffer| - `-` a buffer with 'modifiable' off - = a readonly buffer - R a terminal buffer with a running job - F a terminal buffer with a finished job - ? a terminal buffer without a job: `:terminal NONE` - + a modified buffer - x a buffer with read errors + u |unlisted-buffer| (only displayed when [!] is used) + % buffer in the current window + # |alternate-file| buffer for |:e#| and |CTRL-^| + a an active buffer: loaded and visible + h |hidden-buffer|: loaded, but not displayed in a window + `-` 'nomodifiable' buffer + = readonly buffer + R terminal buffer with a Running job (open channel) + F terminal buffer with a Finished job (closed channel) + ? terminal buffer without a job: `:terminal NONE` + + 'modified' buffer + x buffer with read errors [flags] can be a combination of the following characters, which restrict the buffers to be listed: + modified buffers - `-` buffers with 'modifiable' off + `-` 'nomodifiable' buffers = readonly buffers a active buffers u unlisted buffers (overrides the "!") @@ -1157,8 +1155,8 @@ list of buffers. |unlisted-buffer| x buffers with a read error % current buffer # alternate buffer - R terminal buffers with a running job - F terminal buffers with a finished job + R terminal buffers with a Running job + F terminal buffers with a Finished job t show time last used and sort buffers Combining flags means they are "and"ed together, e.g.: h+ hidden buffers which are modified diff --git a/runtime/lua/vim/_meta/api.gen.lua b/runtime/lua/vim/_meta/api.gen.lua index 301317670d..8f9ebbafe2 100644 --- a/runtime/lua/vim/_meta/api.gen.lua +++ b/runtime/lua/vim/_meta/api.gen.lua @@ -1683,12 +1683,14 @@ function vim.api.nvim_open_tabpage(buf, enter, config) end --- will be echoed directly by the terminal. This is useful to display --- ANSI terminal sequences returned as part of an RPC message, or similar. --- ---- Note: to directly initiate the terminal using the right size, display the ---- buffer in a configured window before calling this. For instance, for a ---- floating display, first create an empty buffer using `nvim_create_buf()`, ---- then display it using `nvim_open_win()`, and then call this function. ---- Then `nvim_chan_send()` can be called immediately to process sequences ---- in a virtual terminal having the intended size. +--- Note: `:ls` reports the buffer as "R" (running) until the channel is closed. `chanclose()` +--- +--- Note: To initialize the terminal size, display the buffer in a window first. E.g. for a floating display, +--- 1. Create an empty buffer using `nvim_create_buf()`. +--- 2. Display it with `nvim_open_win()`. +--- 3. Call nvim_open_term(). +--- 4. Then calling `nvim_chan_send()` will process sequences in a virtual terminal with the +--- intended size (defined by the window width/height). --- --- Example: this `TermHl` command can be used to display and highlight raw ANSI termcodes, so you --- can use Nvim as a "scrollback pager" (for terminals like kitty): [ansi-colorize]() @@ -1700,8 +1702,8 @@ function vim.api.nvim_open_tabpage(buf, enter, config) end --- end, { desc = 'Highlights ANSI termcodes in curbuf' }) --- ``` --- ---- @param buf integer Buffer to use. Buffer contents (if any) will be written ---- to the PTY. +--- @param buf integer Buffer which displays the PTY output. The initial buffer contents (if any) will be +--- written to the PTY. --- @param opts vim.api.keyset.open_term Optional parameters. --- - force_crlf: (boolean, default true) Convert "\n" to "\r\n". --- - on_input: Lua callback for input sent, i e keypresses in terminal diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c index d57994f2f0..0b1517e97f 100644 --- a/src/nvim/api/vim.c +++ b/src/nvim/api/vim.c @@ -1120,12 +1120,14 @@ Buffer nvim_create_buf(Boolean listed, Boolean scratch, Error *err) /// will be echoed directly by the terminal. This is useful to display /// ANSI terminal sequences returned as part of an RPC message, or similar. /// -/// Note: to directly initiate the terminal using the right size, display the -/// buffer in a configured window before calling this. For instance, for a -/// floating display, first create an empty buffer using |nvim_create_buf()|, -/// then display it using |nvim_open_win()|, and then call this function. -/// Then |nvim_chan_send()| can be called immediately to process sequences -/// in a virtual terminal having the intended size. +/// Note: |:ls| reports the buffer as "R" (running) until the channel is closed. |chanclose()| +/// +/// Note: To initialize the terminal size, display the buffer in a window first. E.g. for a floating display, +/// 1. Create an empty buffer using |nvim_create_buf()|. +/// 2. Display it with |nvim_open_win()|. +/// 3. Call nvim_open_term(). +/// 4. Then calling |nvim_chan_send()| will process sequences in a virtual terminal with the +/// intended size (defined by the window width/height). /// /// Example: this `TermHl` command can be used to display and highlight raw ANSI termcodes, so you /// can use Nvim as a "scrollback pager" (for terminals like kitty): [ansi-colorize]() @@ -1137,8 +1139,8 @@ Buffer nvim_create_buf(Boolean listed, Boolean scratch, Error *err) /// end, { desc = 'Highlights ANSI termcodes in curbuf' }) /// ``` /// -/// @param buf Buffer to use. Buffer contents (if any) will be written -/// to the PTY. +/// @param buf Buffer which displays the PTY output. The initial buffer contents (if any) will be +/// written to the PTY. /// @param opts Optional parameters. /// - force_crlf: (boolean, default true) Convert "\n" to "\r\n". /// - on_input: Lua callback for input sent, i e keypresses in terminal diff --git a/src/nvim/path.c b/src/nvim/path.c index 93abe8945d..87fef36c09 100644 --- a/src/nvim/path.c +++ b/src/nvim/path.c @@ -156,10 +156,8 @@ char *path_tail_with_sep(char *fname) /// - "\"path/foo bar/bash\" --login" => "bash" /// - "\"path/foo\\\" bar/bash\" --login" => "bash" /// -/// @param[in] invocation Program invocation string. -/// @param[out] len Stores the length of the executable name. -/// -/// @post if `len` is not null, stores the length of the executable name. +/// @param[in] invocation Program invocation of the form: "path/to/exe [args]". +/// @param[out] len Stores the length of the executable name, if not NULL. /// /// @return The position of the last path separator + 1. const char *invocation_path_tail(const char *invocation, size_t *len) diff --git a/test/functional/options/shell_spec.lua b/test/functional/options/shell_spec.lua index dd6b8c054c..32b368ff7b 100644 --- a/test/functional/options/shell_spec.lua +++ b/test/functional/options/shell_spec.lua @@ -7,7 +7,7 @@ local skip = t.skip local api = n.api local clear = n.clear -describe('applies sensible default options for different shells #28384', function() +describe("'shell…' option defaults based on $SHELL #28384", function() ---@param sh string ---@param shcf string ---@param sp string @@ -69,7 +69,7 @@ describe('applies sensible default options for different shells #28384', functio ) end) - it('even if the path contains spaces', function() + it('if the path contains spaces', function() clear { env = { SHELL = ('%s/foo bar/bash'):format(n.nvim_dir) }, }