Merge remote-tracking branch 'upstream/master' into mix_20240309HEADrahm

1 files changed, 95 insertions, 162 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index c5dabeb551..92f5a261ee 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -406,18 +406,9 @@ Another use case are plugins that show output in an append-only buffer, and
 want to add highlights to the outputs. Highlight data cannot be preserved
 on writing and loading a buffer to file, nor in undo/redo cycles.
 
-Highlights are registered using the |nvim_buf_add_highlight()| function. If an
-external highlighter plugin wants to add many highlights in a batch,
-performance can be improved by calling |nvim_buf_add_highlight()| as an
-asynchronous notification, after first (synchronously) requesting a source id.
-
-|nvim_buf_add_highlight()| adds highlights as |extmarks|. If highlights need to
-be tracked or manipulated after adding them, it is better to use
-|nvim_buf_set_extmark()| directly, as this function returns the placed |extmark|
-id. Thus, instead of >lua
-  vim.api.nvim_buf_add_highlight(buf, ns_id, hl_group, line, col_start, col_end)
-<
-use >lua
+Highlights are registered using the |nvim_buf_set_extmark()| function, which
+adds highlights as |extmarks|. If highlights need to be tracked or manipulated
+after adding them, the returned |extmark| id can be used. >lua
   -- create the highlight through an extmark
   extid = vim.api.nvim_buf_set_extmark(buf, ns_id, line, col_start, {end_col = col_end, hl_group = hl_group})
 
@@ -428,32 +419,10 @@ use >lua
   vim.api.nvim_buf_set_extmark(buf, ns_id, NEW_LINE, col_start, {end_col = col_end, hl_group = NEW_HL_GROUP, id = extid})
 <
 
-Example using the Python API client (|pynvim|):
->python
-    src = vim.new_highlight_source()
-    buf = vim.current.buffer
-    for i in range(5):
-        buf.add_highlight("String",i,0,-1,src_id=src)
-    # some time later ...
-    buf.clear_namespace(src)
-<
-If the highlights don't need to be deleted or updated, just pass -1 as
-src_id (this is the default in python). Use |nvim_buf_clear_namespace()| to
-clear highlights from a specific source, in a specific line range or the
-entire buffer by passing in the line range 0, -1 (the latter is the default in
-python as used above).
-
-Example using the API from Vimscript: >vim
-
-    call nvim_buf_set_lines(0, 0, 0, v:true, ["test text"])
-    let src = nvim_buf_add_highlight(0, 0, "String", 1, 0, 4)
-    call nvim_buf_add_highlight(0, src, "Identifier", 0, 5, -1)
-    " some time later ...
-    call nvim_buf_clear_namespace(0, src, 0, -1)
-
+See also |vim.hl.range()|.
 
 ==============================================================================
-Floating windows                                                 *api-floatwin*
+Floating windows				*api-floatwin* *floating-windows*
 
 Floating windows ("floats") are displayed on top of normal windows.  This is
 useful to implement simple widgets, such as tooltips displayed next to the
@@ -654,35 +623,22 @@ nvim_del_var({name})                                          *nvim_del_var()*
       • {name}  Variable name
 
 nvim_echo({chunks}, {history}, {opts})                           *nvim_echo()*
-    Echo a message.
+    Prints a message given by a list of `[text, hl_group]` "chunks".
+
+    Example: >lua
+        vim.api.nvim_echo({ { 'chunk1-line1\nchunk1-line2\n' }, { 'chunk2-line1' } }, true, {})
+<
 
     Parameters: ~
-      • {chunks}   A list of `[text, hl_group]` arrays, each representing a
-                   text chunk with specified highlight group name or ID.
-                   `hl_group` element can be omitted for no highlight.
+      • {chunks}   List of `[text, hl_group]` pairs, where each is a `text`
+                   string highlighted by the (optional) name or ID `hl_group`.
       • {history}  if true, add to |message-history|.
       • {opts}     Optional parameters.
-                   • verbose: Message is printed as a result of 'verbose'
-                     option. If Nvim was invoked with -V3log_file, the message
-                     will be redirected to the log_file and suppressed from
-                     direct output.
-
-nvim_err_write({str})                                       *nvim_err_write()*
-    Writes a message to the Vim error buffer. Does not append "\n", the
-    message is buffered (won't display) until a linefeed is written.
-
-    Parameters: ~
-      • {str}  Message
-
-nvim_err_writeln({str})                                   *nvim_err_writeln()*
-    Writes a message to the Vim error buffer. Appends "\n", so the buffer is
-    flushed (and displayed).
-
-    Parameters: ~
-      • {str}  Message
-
-    See also: ~
-      • nvim_err_write()
+                   • err: Treat the message like `:echoerr`. Sets `hl_group`
+                     to |hl-ErrorMsg| by default.
+                   • verbose: Message is controlled by the 'verbose' option.
+                     Nvim invoked with `-V3log` will write the message to the
+                     "log" file instead of standard output.
 
 nvim_eval_statusline({str}, {opts})                   *nvim_eval_statusline()*
     Evaluates statusline string.
@@ -716,7 +672,10 @@ nvim_eval_statusline({str}, {opts})                   *nvim_eval_statusline()*
           true. Each element of the array is a |Dict| with these keys:
           • start: (number) Byte index (0-based) of first character that uses
             the highlight.
-          • group: (string) Name of highlight group.
+          • group: (string) Name of highlight group. May be removed in the
+            future, use `groups` instead.
+          • groups: (array) Names of stacked highlight groups (highest
+            priority last).
 
 nvim_exec_lua({code}, {args})                                *nvim_exec_lua()*
     Execute Lua code. Parameters (if any) are available as `...` inside the
@@ -775,6 +734,8 @@ nvim_get_api_info()                                      *nvim_get_api_info()*
 nvim_get_chan_info({chan})                              *nvim_get_chan_info()*
     Gets information about a channel.
 
+    See |nvim_list_uis()| for an example of how to get channel info.
+
     Parameters: ~
       • {chan}  channel_id, or 0 for current channel
 
@@ -796,7 +757,7 @@ nvim_get_chan_info({chan})                              *nvim_get_chan_info()*
           present if a pty is used (e.g. for conpty on Windows).
         • "buffer" (optional) Buffer connected to |terminal| instance.
         • "client" (optional) Info about the peer (client on the other end of
-          the RPC channel), which it provided via |nvim_set_client_info()|.
+          the channel), as set by |nvim_set_client_info()|.
 
 nvim_get_color_by_name({name})                      *nvim_get_color_by_name()*
     Returns the 24-bit RGB value of a |nvim_get_color_map()| color name or
@@ -1079,6 +1040,12 @@ nvim_list_tabpages()                                    *nvim_list_tabpages()*
 nvim_list_uis()                                              *nvim_list_uis()*
     Gets a list of dictionaries representing attached UIs.
 
+    Example: The Nvim builtin |TUI| sets its channel info as described in
+    |startup-tui|. In particular, it sets `client.name` to "nvim-tui". So you
+    can check if the TUI is running by inspecting the client name of each UI: >lua
+        vim.print(vim.api.nvim_get_chan_info(vim.api.nvim_list_uis()[1].chan).client.name)
+<
+
     Return: ~
         Array of UI dictionaries, each with these keys:
         • "height" Requested height of the UI
@@ -1099,22 +1066,11 @@ nvim_load_context({dict})                                *nvim_load_context()*
     Parameters: ~
       • {dict}  |Context| map.
 
-nvim_notify({msg}, {log_level}, {opts})                        *nvim_notify()*
-    Notify the user with a message
-
-    Relays the call to vim.notify . By default forwards your message in the
-    echo area but can be overridden to trigger desktop notifications.
-
-    Parameters: ~
-      • {msg}        Message to display to the user
-      • {log_level}  The log level
-      • {opts}       Reserved for future use.
-
 nvim_open_term({buffer}, {opts})                            *nvim_open_term()*
     Open a terminal instance in a buffer
 
     By default (and currently the only option) the terminal will not be
-    connected to an external process. Instead, input send on the channel will
+    connected to an external process. Instead, input sent on the channel will
     be echoed directly by the terminal. This is useful to display ANSI
     terminal sequences returned as part of a rpc message, or similar.
 
@@ -1125,6 +1081,17 @@ nvim_open_term({buffer}, {opts})                            *nvim_open_term()*
     |nvim_chan_send()| can be called immediately to process sequences in a
     virtual terminal having the intended size.
 
+    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* *terminal-scrollback-pager* >lua
+        vim.api.nvim_create_user_command('TermHl', function()
+          local b = vim.api.nvim_create_buf(false, true)
+          local chan = vim.api.nvim_open_term(b, {})
+          vim.api.nvim_chan_send(chan, table.concat(vim.api.nvim_buf_get_lines(0, 0, -1, false), '\n'))
+          vim.api.nvim_win_set_buf(0, b)
+        end, { desc = 'Highlights ANSI termcodes in curbuf' })
+<
+
     Attributes: ~
         not allowed when |textlock| is active
 
@@ -1143,13 +1110,6 @@ nvim_open_term({buffer}, {opts})                            *nvim_open_term()*
     Return: ~
         Channel id, or 0 on error
 
-nvim_out_write({str})                                       *nvim_out_write()*
-    Writes a message to the Vim output buffer. Does not append "\n", the
-    message is buffered (won't display) until a linefeed is written.
-
-    Parameters: ~
-      • {str}  Message
-
 nvim_paste({data}, {crlf}, {phase})                             *nvim_paste()*
     Pastes at cursor (in any mode), and sets "redo" so dot (|.|) will repeat
     the input. UIs call this to implement "paste", but it's also intended for
@@ -1248,25 +1208,23 @@ nvim_select_popupmenu_item({item}, {insert}, {finish}, {opts})
 
                                                       *nvim_set_client_info()*
 nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes})
-    Self-identifies the client.
+    Self-identifies the client. Sets the `client` object returned by
+    |nvim_get_chan_info()|.
 
-    The client/plugin/application should call this after connecting, to
-    provide hints about its identity and purpose, for debugging and
-    orchestration.
+    Clients should call this just after connecting, to provide hints for
+    debugging and orchestration. (Note: Something is better than nothing!
+    Fields are optional, but at least set `name`.)
 
     Can be called more than once; the caller should merge old info if
     appropriate. Example: library first identifies the channel, then a plugin
     using that library later identifies itself.
 
-    Note: ~
-      • "Something is better than nothing". You don't need to include all the
-        fields.
-
     Attributes: ~
         |RPC| only
 
     Parameters: ~
-      • {name}        Short name for the connected client
+      • {name}        Client short-name. Sets the `client.name` field of
+                      |nvim_get_chan_info()|.
       • {version}     Dict describing the version, with these (optional) keys:
                       • "major" major version (defaults to 0 if not set, for
                         no release yet)
@@ -1636,11 +1594,9 @@ nvim_command({command})                                       *nvim_command()*
 
     On execution error: fails with Vimscript error, updates v:errmsg.
 
-    Prefer using |nvim_cmd()| or |nvim_exec2()| over this. To evaluate
-    multiple lines of Vim script or an Ex command directly, use
-    |nvim_exec2()|. To construct an Ex command using a structured format and
-    then execute it, use |nvim_cmd()|. To modify an Ex command before
-    evaluating it, use |nvim_parse_cmd()| in conjunction with |nvim_cmd()|.
+    Prefer |nvim_cmd()| or |nvim_exec2()| instead. To modify an Ex command in
+    a structured way before executing it, modify the result of
+    |nvim_parse_cmd()| then pass it to |nvim_cmd()|.
 
     Parameters: ~
       • {command}  Ex command string
@@ -2161,12 +2117,12 @@ nvim_buf_call({buffer}, {fun})                               *nvim_buf_call()*
     This temporarily switches current buffer to "buffer". If the current
     window already shows "buffer", the window is not switched. If a window
     inside the current tabpage (including a float) already shows the buffer,
-    then one of these windows will be set as current window temporarily.
+    then one of those windows will be set as current window temporarily.
     Otherwise a temporary scratch window (called the "autocmd window" for
     historical reasons) will be used.
 
     This is useful e.g. to call Vimscript functions that only work with the
-    current buffer/window currently, like |termopen()|.
+    current buffer/window currently, like `jobstart(…, {'term': v:true})`.
 
     Attributes: ~
         Lua |vim.api| only
@@ -2507,42 +2463,6 @@ nvim_buf_set_var({buffer}, {name}, {value})               *nvim_buf_set_var()*
 ==============================================================================
 Extmark Functions                                                *api-extmark*
 
-                                                    *nvim_buf_add_highlight()*
-nvim_buf_add_highlight({buffer}, {ns_id}, {hl_group}, {line}, {col_start},
-                       {col_end})
-    Adds a highlight to buffer.
-
-    Useful for plugins that dynamically generate highlights to a buffer (like
-    a semantic highlighter or linter). The function adds a single highlight to
-    a buffer. Unlike |matchaddpos()| highlights follow changes to line
-    numbering (as lines are inserted/removed above the highlighted line), like
-    signs and marks do.
-
-    Namespaces are used for batch deletion/updating of a set of highlights. To
-    create a namespace, use |nvim_create_namespace()| which returns a
-    namespace id. Pass it in to this function as `ns_id` to add highlights to
-    the namespace. All highlights in the same namespace can then be cleared
-    with single call to |nvim_buf_clear_namespace()|. If the highlight never
-    will be deleted by an API call, pass `ns_id = -1`.
-
-    As a shorthand, `ns_id = 0` can be used to create a new namespace for the
-    highlight, the allocated id is then returned. If `hl_group` is the empty
-    string no highlight is added, but a new `ns_id` is still returned. This is
-    supported for backwards compatibility, new code should use
-    |nvim_create_namespace()| to create a new empty namespace.
-
-    Parameters: ~
-      • {buffer}     Buffer handle, or 0 for current buffer
-      • {ns_id}      namespace to use or -1 for ungrouped highlight
-      • {hl_group}   Name of the highlight group to use
-      • {line}       Line to highlight (zero-indexed)
-      • {col_start}  Start of (byte-indexed) column range to highlight
-      • {col_end}    End of (byte-indexed) column range to highlight, or -1 to
-                     highlight to end of line
-
-    Return: ~
-        The ns_id that was used
-
                                                   *nvim_buf_clear_namespace()*
 nvim_buf_clear_namespace({buffer}, {ns_id}, {line_start}, {line_end})
     Clears |namespace|d objects (highlights, |extmarks|, virtual text) from a
@@ -2676,6 +2596,8 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts})
                     and below highlight groups can be supplied either as a
                     string or as an integer, the latter of which can be
                     obtained using |nvim_get_hl_id_by_name()|.
+                    Multiple highlight groups can be stacked by passing an
+                    array (highest priority last).
                   • 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).
@@ -2687,6 +2609,13 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts})
                     last).
                   • virt_text_pos : position of virtual text. Possible values:
                     • "eol": right after eol character (default).
+                    • "eol_right_align": display right aligned in the window
+                      unless the virtual text is longer than the space
+                      available. If the virtual text is too long, it is
+                      truncated to fit in the window after the EOL character.
+                      If the line is wrapped, the virtual text is shown after
+                      the end of the line rather than the previous screen
+                      line.
                     • "overlay": display over the specified column, without
                       shifting the underlying text.
                     • "right_align": display right aligned in the window.
@@ -2780,7 +2709,7 @@ nvim_create_namespace({name})                        *nvim_create_namespace()*
     Creates a new namespace or gets an existing one.               *namespace*
 
     Namespaces are used for buffer highlights and virtual text, see
-    |nvim_buf_add_highlight()| and |nvim_buf_set_extmark()|.
+    |nvim_buf_set_extmark()|.
 
     Namespaces can be named or anonymous. If `name` matches an existing
     namespace, the associated id is returned. If `name` is an empty string a
@@ -2838,8 +2767,8 @@ nvim_set_decoration_provider({ns_id}, {opts})
                  • on_start: called first on each screen redraw >
                     ["start", tick]
 <
-                 • on_buf: called for each buffer being redrawn (before window
-                   callbacks) >
+                 • on_buf: called for each buffer being redrawn (once per
+                   edit, before window callbacks) >
                     ["buf", bufnr, tick]
 <
                  • on_win: called when starting to redraw a specific window. >
@@ -3166,11 +3095,13 @@ nvim_open_win({buffer}, {enter}, {config})                   *nvim_open_win()*
       • {config}  Map defining the window configuration. Keys:
                   • relative: Sets the window layout to "floating", placed at
                     (row,col) coordinates relative to:
-                    • "editor" The global editor grid
+                    • "cursor" Cursor position in current window.
+                    • "editor" The global editor grid.
+                    • "laststatus" 'laststatus' if present, or last row.
+                    • "mouse" Mouse position.
+                    • "tabline" Tabline if present, or first row.
                     • "win" Window given by the `win` field, or current
                       window.
-                    • "cursor" Cursor position in current window.
-                    • "mouse" Mouse position
                   • win: |window-ID| window to split, or relative window when
                     creating a float (relative="win").
                   • anchor: Decides which corner of the float to place at
@@ -3483,9 +3414,9 @@ nvim_create_autocmd({event}, {opts})                   *nvim_create_autocmd()*
                    • event: (string) name of the triggered event
                      |autocmd-events|
                    • group: (number|nil) autocommand group id, if any
-                   • match: (string) expanded value of <amatch>
-                   • buf: (number) expanded value of <abuf>
-                   • file: (string) expanded value of <afile>
+                   • file: (string) <afile> (not expanded to a full path)
+                   • match: (string) <amatch> (expanded to a full path)
+                   • buf: (number) <abuf>
                    • data: (any) arbitrary data passed from
                      |nvim_exec_autocmds()|                       *event-data*
                  • command (string) optional: Vim command to execute on event.
@@ -3580,33 +3511,35 @@ nvim_get_autocmds({opts})                                *nvim_get_autocmds()*
 
     Parameters: ~
       • {opts}  Dict with at least one of the following:
-                • group (string|integer): the autocommand group name or id to
-                  match against.
-                • event (string|array): event or events to match against
+                • buffer: (integer) Buffer number or list of buffer numbers
+                  for buffer local autocommands |autocmd-buflocal|. Cannot be
+                  used with {pattern}
+                • event: (string|table) event or events to match against
                   |autocmd-events|.
-                • pattern (string|array): pattern or patterns to match against
+                • id: (integer) Autocommand ID to match.
+                • group: (string|table) the autocommand group name or id to
+                  match against.
+                • pattern: (string|table) pattern or patterns to match against
                   |autocmd-pattern|. Cannot be used with {buffer}
-                • buffer: Buffer number or list of buffer numbers for buffer
-                  local autocommands |autocmd-buflocal|. Cannot be used with
-                  {pattern}
 
     Return: ~
         Array of autocommands matching the criteria, with each item containing
         the following fields:
-        • id (number): the autocommand id (only when defined with the API).
-        • group (integer): the autocommand group id.
-        • group_name (string): the autocommand group name.
-        • desc (string): the autocommand description.
-        • event (string): the autocommand event.
-        • command (string): the autocommand command. Note: this will be empty
+        • buffer: (integer) the buffer number.
+        • buflocal: (boolean) true if the autocommand is buffer local.
+        • command: (string) the autocommand command. Note: this will be empty
           if a callback is set.
-        • callback (function|string|nil): Lua function or name of a Vim script
-          function which is executed when this autocommand is triggered.
-        • once (boolean): whether the autocommand is only run once.
-        • pattern (string): the autocommand pattern. If the autocommand is
+        • callback: (function|string|nil): Lua function or name of a Vim
+          script function which is executed when this autocommand is
+          triggered.
+        • desc: (string) the autocommand description.
+        • event: (string) the autocommand event.
+        • id: (integer) the autocommand id (only when defined with the API).
+        • group: (integer) the autocommand group id.
+        • group_name: (string) the autocommand group name.
+        • once: (boolean) whether the autocommand is only run once.
+        • pattern: (string) the autocommand pattern. If the autocommand is
           buffer local |autocmd-buffer-local|:
-        • buflocal (boolean): true if the autocommand is buffer local.
-        • buffer (number): the buffer number.
 
 
 ==============================================================================