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

1 files changed, 119 insertions, 112 deletions

diff --git a/runtime/doc/ui.txt b/runtime/doc/ui.txt
index 3fb9ed1125..3110d0817c 100644
--- a/runtime/doc/ui.txt
+++ b/runtime/doc/ui.txt
@@ -23,40 +23,41 @@ screen grid with a size of width × height cells. This is typically done by an
 embedder at startup (see |ui-startup|), but UIs can also connect to a running
 Nvim instance and invoke nvim_ui_attach(). The `options` parameter is a map
 with these (optional) keys:
+
 							*ui-rgb*
-	`rgb`			Decides the color format.
-				true:	(default) 24-bit RGB colors
-				false:	Terminal colors (8-bit, max 256)
-							*ui-override*
-	`override`		Decides how UI capabilities are resolved.
-				true:	Enable requested UI capabilities, even
-					if not supported by all connected UIs
-					(including |TUI|).
-				false:	(default) Disable UI capabilities not
-					supported by all connected UIs
-					(including TUI).
-							*ui-ext-options*
-	`ext_cmdline`		Externalize the cmdline. |ui-cmdline|
-	`ext_hlstate`		Detailed highlight state. |ui-hlstate|
-				Sets `ext_linegrid` implicitly.
-	`ext_linegrid`		Line-based grid events. |ui-linegrid|
-				Deactivates |ui-grid-old| implicitly.
-	`ext_messages`		Externalize messages. |ui-messages|
-				Sets `ext_linegrid` and `ext_cmdline` implicitly.
-	`ext_multigrid`		Per-window grid events. |ui-multigrid|
-				Sets `ext_linegrid` implicitly.
-	`ext_popupmenu`		Externalize |popupmenu-completion| and
-				'wildmenu'. |ui-popupmenu|
-	`ext_tabline`		Externalize the tabline. |ui-tabline|
-	`ext_termcolors`	Use external default colors.
-	`term_name`		Sets the name of the terminal 'term'.
-	`term_colors`		Sets the number of supported colors 't_Co'.
-	`term_background`	Sets the default value of 'background'.
-	`stdin_fd`		Read buffer from `fd` as if it was a stdin pipe
-				This option can only used by |--embed| ui,
-				see |ui-startup-stdin|.
+- `rgb`			Decides the color format.
+			- true:	(default) 24-bit RGB colors
+			- false:	Terminal colors (8-bit, max 256)
 
+							*ui-override*
+- `override`		Decides how UI capabilities are resolved.
+			- true:	Enable requested UI capabilities, even if not
+			  supported by all connected UIs (including |TUI|).
+			- false: (default) Disable UI capabilities not
+			  supported by all connected UIs (including TUI).
 
+							*ui-ext-options*
+- `ext_cmdline`		Externalize the cmdline. |ui-cmdline|
+- `ext_hlstate`		Detailed highlight state. |ui-hlstate|
+			Sets `ext_linegrid` implicitly.
+- `ext_linegrid`	Line-based grid events. |ui-linegrid|
+			Deactivates |ui-grid-old| implicitly.
+- `ext_messages`	Externalize messages. |ui-messages|
+			Sets `ext_linegrid` and `ext_cmdline` implicitly.
+- `ext_multigrid`	Per-window grid events. |ui-multigrid|
+			Sets `ext_linegrid` implicitly.
+- `ext_popupmenu`	Externalize |popupmenu-completion| and
+			'wildmenu'. |ui-popupmenu|
+- `ext_tabline`		Externalize the tabline. |ui-tabline|
+- `ext_termcolors`	Use external default colors.
+- `term_name`		Sets the name of the terminal 'term'.
+- `term_colors`		Sets the number of supported colors 't_Co'.
+- `term_background`	Sets the default value of 'background'.
+- `stdin_fd`		Read buffer from `fd` as if it was a stdin pipe
+			This option can only used by |--embed| ui,
+			see |ui-startup-stdin|.
+	`stdin_tty`		Tells if `stdin` is a `tty` or not.
+	`stdout_tty`		Tells if `stdout` is a `tty` or not.
 
 Specifying an unknown option is an error; UIs can check the |api-metadata|
 `ui_options` key for supported options.
@@ -120,7 +121,7 @@ for forward-compatibility. |api-contract|
 UI startup							   *ui-startup*
 
 UI embedders (clients that start Nvim with |--embed| and later call
-|nvim_ui_attach()|) must start Nvim without |--headless|: >
+|nvim_ui_attach()|) must start Nvim without |--headless|: >bash
     nvim --embed
 Nvim will pause before loading startup files and reading buffers, so the UI
 has a chance to invoke requests and do early initialization. Startup will
@@ -133,14 +134,18 @@ procedure:
 
 1. Invoke |nvim_get_api_info()|, if needed to setup the client library and/or
    to get the list of supported UI extensions.
+
 2. Do any configuration that should be happen before user config is loaded.
    Buffers and windows are not available at this point, but this could be used
    to set |g:| variables visible to init.vim
+
 3. If the UI wants to do additional setup after user config is loaded,
-   register a VimEnter autocmd: >
+   register a VimEnter autocmd: >vim
       nvim_command("autocmd VimEnter * call rpcrequest(1, 'vimenter')")
-<4. Now invoke |nvim_ui_attach()|. The UI must handle user input by now:
+
+4. Now invoke |nvim_ui_attach()|. The UI must handle user input by now:
    sourcing init.vim and loading buffers might lead to blocking prompts.
+
 5. If step 3 was used, Nvim will send a blocking "vimenter" request to the UI.
    Inside this request handler, the UI can safely do any initialization before
    entering normal mode, for example reading variables set by init.vim.
@@ -164,13 +169,13 @@ Global Events							    *ui-global*
 The following UI events are always emitted, and describe global state of
 the editor.
 
-["set_title", title]
-["set_icon", icon]
+["set_title", title] ~
+["set_icon", icon] ~
 	Set the window title, and icon (minimized) window title, respectively.
 	In windowing systems not distinguishing between the two, "set_icon"
 	can be ignored.
 
-["mode_info_set", cursor_style_enabled, mode_info]
+["mode_info_set", cursor_style_enabled, mode_info] ~
 	`cursor_style_enabled` is a boolean indicating if the UI should set
 	the cursor style. `mode_info` is a list of mode property maps. The
 	current mode is given by the `mode_idx` field of the `mode_change`
@@ -197,20 +202,21 @@ the editor.
 	`hl_id`:	Use `attr_id` instead.
 	`hl_lm`:	Use `attr_id_lm` instead.
 
-["option_set", name, value]
+["option_set", name, value] ~
 	UI-related option changed, where `name` is one of:
 
-	'arabicshape'
-	'ambiwidth'
-	'emoji'
-	'guifont'
-	'guifontwide'
-	'linespace'
-	'mousefocus'
-	'pumblend'
-	'showtabline'
-	'termguicolors'
-	"ext_*" (all |ui-ext-options|)
+	- 'arabicshape'
+	- 'ambiwidth'
+	- 'emoji'
+	- 'guifont'
+	- 'guifontwide'
+	- 'linespace'
+	- 'mousefocus'
+	- 'mousemoveevent'
+	- 'pumblend'
+	- 'showtabline'
+	- 'termguicolors'
+	- "ext_*" (all |ui-ext-options|)
 
 	Triggered when the UI first connects to Nvim, and whenever an option
 	is changed by the user or a plugin.
@@ -223,7 +229,7 @@ the editor.
 	however a UI might still use such options when rendering raw text
 	sent from Nvim, like for |ui-cmdline|.
 
-["mode_change", mode, mode_idx]
+["mode_change", mode, mode_idx] ~
 	Editor mode changed.  The `mode` parameter is a string representing
 	the current mode. `mode_idx` is an index into the array emitted in
 	the `mode_info_set` event. UIs should change the cursor style
@@ -232,30 +238,30 @@ the editor.
 	instance more submodes and temporary states might be represented as
 	separate modes.
 
-["mouse_on"]
-["mouse_off"]
+["mouse_on"] ~
+["mouse_off"] ~
 	'mouse' was enabled/disabled in the current editor mode. Useful for
 	a terminal UI, or embedding into an application where Nvim mouse would
 	conflict with other usages of the mouse. Other UI:s may ignore this event.
 
-["busy_start"]
-["busy_stop"]
+["busy_start"] ~
+["busy_stop"] ~
 	Indicates to the UI that it must stop rendering the cursor. This event
 	is misnamed and does not actually have anything to do with busyness.
 
-["suspend"]
+["suspend"] ~
 	|:suspend| command or |CTRL-Z| mapping is used. A terminal client (or
 	another client where it makes sense) could suspend itself.  Other
 	clients can safely ignore it.
 
-["update_menu"]
+["update_menu"] ~
 	The menu mappings changed.
 
-["bell"]
-["visual_bell"]
+["bell"] ~
+["visual_bell"] ~
 	Notify the user with an audible or visual bell, respectively.
 
-["flush"]
+["flush"] ~
 	Nvim is done redrawing the screen. For an implementation that renders
 	to an internal buffer, this is the time to display the redrawn parts
 	to the user.
@@ -278,11 +284,11 @@ be created; to enable per-window grids, activate |ui-multigrid|.
 Highlight attribute groups are predefined. UIs should maintain a table to map
 numerical highlight ids to the actual attributes.
 
-["grid_resize", grid, width, height]
+["grid_resize", grid, width, height] ~
 	Resize a `grid`. If `grid` wasn't seen by the client before, a new grid is
 	being created with this size.
 
-["default_colors_set", rgb_fg, rgb_bg, rgb_sp, cterm_fg, cterm_bg]
+["default_colors_set", rgb_fg, rgb_bg, rgb_sp, cterm_fg, cterm_bg] ~
 	The first three arguments set the default foreground, background and
 	special colors respectively. `cterm_fg` and `cterm_bg` specifies the
 	default color codes to use in a 256-color terminal.
@@ -299,7 +305,7 @@ numerical highlight ids to the actual attributes.
 	screen with changed background color itself.
 
 							*ui-event-hl_attr_define*
-["hl_attr_define", id, rgb_attr, cterm_attr, info]
+["hl_attr_define", id, rgb_attr, cterm_attr, info] ~
 	Add a highlight with `id`  to the highlight table, with the
 	attributes specified by the `rgb_attr` and `cterm_attr` dicts, with the
 	following (all optional) keys.
@@ -318,6 +324,7 @@ numerical highlight ids to the actual attributes.
 	`underdouble`:		double underlined text. The lines have `special` color.
 	`underdotted`:		underdotted text. The dots have `special` color.
 	`underdashed`:		underdashed text. The dashes have `special` color.
+	`altfont`:		alternative font.
 	`blend`:		Blend level (0-100). Could be used by UIs to
 				support blending floating windows to the
 				background or to signal a transparent cursor.
@@ -345,7 +352,7 @@ numerical highlight ids to the actual attributes.
 	`info` is an empty array by default, and will be used by the
 	|ui-hlstate| extension explained below.
 
-["hl_group_set", name, hl_id]
+["hl_group_set", name, hl_id] ~
 	The bulitin highlight group `name` was set to use the attributes `hl_id`
 	defined by a previous `hl_attr_define` call. This event is not needed
 	to render the grids which use attribute ids directly, but is useful
@@ -354,7 +361,7 @@ numerical highlight ids to the actual attributes.
 	use the |hl-Pmenu| family of builtin highlights.
 
 							    *ui-event-grid_line*
-["grid_line", grid, row, col_start, cells]
+["grid_line", grid, row, col_start, cells] ~
 	Redraw a continuous part of a `row` on a `grid`, starting at the column
 	`col_start`. `cells` is an array of arrays each with 1 to 3 items:
 	`[text(, hl_id, repeat)]` . `text` is the UTF-8 text that should be put in
@@ -373,19 +380,19 @@ numerical highlight ids to the actual attributes.
 	enough to cover the remaining line, will be sent when the rest of the
 	line should be cleared.
 
-["grid_clear", grid]
+["grid_clear", grid] ~
 	Clear a `grid`.
 
-["grid_destroy", grid]
+["grid_destroy", grid] ~
 	`grid` will not be used anymore and the UI can free any data associated
 	with it.
 
-["grid_cursor_goto", grid, row, column]
+["grid_cursor_goto", grid, row, column] ~
 	Makes `grid` the current grid and `row, column` the cursor position on this
 	grid.  This event will be sent at most once in a `redraw` batch and
 	indicates the visible cursor position.
 
-["grid_scroll", grid, top, bot, left, right, rows, cols]
+["grid_scroll", grid, top, bot, left, right, rows, cols] ~
 	Scroll a region of `grid`. This is semantically unrelated to editor
 	|scrolling|, rather this is an optimized way to say "copy these screen
 	cells".
@@ -438,30 +445,30 @@ Grid Events (cell-based)					   *ui-grid-old*
 This is the legacy representation of the screen grid, emitted if |ui-linegrid|
 is not active. New UIs should implement |ui-linegrid| instead.
 
-["resize", width, height]
+["resize", width, height] ~
 	The grid is resized to `width` and `height` cells.
 
-["clear"]
+["clear"] ~
 	Clear the grid.
 
-["eol_clear"]
+["eol_clear"] ~
 	Clear from the cursor position to the end of the current line.
 
-["cursor_goto", row, col]
+["cursor_goto", row, col] ~
 	Move the cursor to position (row, col). Currently, the same cursor is
 	used to define the position for text insertion and the visible cursor.
 	However, only the last cursor position, after processing the entire
 	array in the "redraw" event, is intended to be a visible cursor
 	position.
 
-["update_fg", color]
-["update_bg", color]
-["update_sp", color]
+["update_fg", color] ~
+["update_bg", color] ~
+["update_sp", color] ~
 	Set the default foreground, background and special colors
 	respectively.
 
 							*ui-event-highlight_set*
-["highlight_set", attrs]
+["highlight_set", attrs] ~
 	Set the attributes that the next text put on the grid will have.
 	`attrs` is a dict with the keys below. Any absent key is reset
 	to its default value. Color defaults are set by the `update_fg` etc
@@ -481,18 +488,18 @@ is not active. New UIs should implement |ui-linegrid| instead.
 	`underdotted`:	underdotted text. The dots have `special` color.
 	`underdashed`:	underdashed text. The dashes have `special` color.
 
-["put", text]
+["put", text] ~
 	The (utf-8 encoded) string `text` is put at the cursor position
 	(and the cursor is advanced), with the highlights as set by the
 	last `highlight_set` update.
 
-["set_scroll_region", top, bot, left, right]
+["set_scroll_region", top, bot, left, right] ~
 	Define the scroll region used by `scroll` below.
 
 	Note: ranges are end-inclusive, which is inconsistent with API
 	conventions.
 
-["scroll", count]
+["scroll", count] ~
 	Scroll the text in the scroll region. The diagrams below illustrate
 	what will happen, depending on the scroll direction. "=" is used to
 	represent the SR(scroll region) boundaries and "-" the moved rectangles.
@@ -575,7 +582,7 @@ The multigrid extension gives UIs more control over how windows are displayed:
   per-window. Or reserve space around the border of the window for its own
   elements, such as scrollbars from the UI toolkit.
 - A dedicated grid is used for messages, which may scroll over the window
-  area. (Alternatively |ext_messages| can be used).
+  area. (Alternatively |ui-messages| can be used).
 
 By default, the grid size is handled by Nvim and set to the outer grid size
 (i.e. the size of the window frame in Nvim) whenever the split is created.
@@ -587,46 +594,46 @@ A window can be hidden and redisplayed without its grid being deallocated.
 This can happen multiple times for the same window, for instance when switching
 tabs.
 
-["win_pos", grid, win, start_row, start_col, width, height]
+["win_pos", grid, win, start_row, start_col, width, height] ~
 	Set the position and size of the grid in Nvim (i.e. the outer grid
 	size). If the window was previously hidden, it should now be shown
 	again.
 
-["win_float_pos", grid, win, anchor, anchor_grid, anchor_row, anchor_col, focusable]
+["win_float_pos", grid, win, anchor, anchor_grid, anchor_row, anchor_col, focusable] ~
 	Display or reconfigure floating window `win`. The window should be
 	displayed above another grid `anchor_grid` at the specified position
 	`anchor_row` and `anchor_col`. For the meaning of `anchor` and more
 	details of positioning, see |nvim_open_win()|.
 
-["win_external_pos", grid, win]
+["win_external_pos", grid, win] ~
 	Display or reconfigure external window `win`. The window should be
 	displayed as a separate top-level window in the desktop environment,
 	or something similar.
 
-["win_hide", grid]
+["win_hide", grid] ~
 	Stop displaying the window. The window can be shown again later.
 
-["win_close", grid]
+["win_close", grid] ~
 	Close the window.
 
-["msg_set_pos", grid, row, scrolled, sep_char]
-	Display messages on `grid`.  The grid will be displayed at `row` on the
-	default grid (grid=1), covering the full column width. `scrolled`
+["msg_set_pos", grid, row, scrolled, sep_char] ~
+	Display messages on `grid`.  The grid will be displayed at `row` on
+	the default grid (grid=1), covering the full column width. `scrolled`
 	indicates whether the message area has been scrolled to cover other
-	grids. It can be useful to draw a separator then ('display' msgsep
-	flag). The Builtin TUI draws a full line filled with `sep_char` and
-	|hl-MsgSeparator| highlight.
+	grids. It can be useful to draw a separator then |msgsep|. The Builtin
+	TUI draws a full line filled with `sep_char` ('fillchars' msgsep
+	field) and |hl-MsgSeparator| highlight.
 
-	When |ext_messages| is active, no message grid is used, and this event
+	When |ui-messages| is active, no message grid is used, and this event
 	will not be sent.
 
-["win_viewport", grid, win, topline, botline, curline, curcol]
+["win_viewport", grid, win, topline, botline, curline, curcol] ~
 	Indicates the range of buffer text displayed in the window, as well
 	as the cursor position in the buffer. All positions are zero-based.
 	`botline` is set to one more than the line count of the buffer, if
 	there are filler lines past the end.
 
-["win_extmark", grid, win, ns_id, mark_id, row, col]
+["win_extmark", grid, win, ns_id, mark_id, row, col] ~
 	Updates the position of an extmark which is currently visible in a
 	window. Only emitted if the mark has the `ui_watched` attribute. 
 
@@ -638,7 +645,7 @@ Activated by the `ext_popupmenu` |ui-option|.
 This UI extension delegates presentation of the |popupmenu-completion| and
 command-line 'wildmenu'.
 
-["popupmenu_show", items, selected, row, col, grid]
+["popupmenu_show", items, selected, row, col, grid] ~
 	Show |popupmenu-completion|. `items` is an array of completion items
 	to show; each item is an array of the form [word, kind, menu, info] as
 	defined at |complete-items|, except that `word` is replaced by `abbr`
@@ -650,12 +657,12 @@ command-line 'wildmenu'.
 	set to -1 to indicate the popupmenu should be anchored to the external
 	cmdline. Then `col` will be a byte position in the cmdline text.
 
-["popupmenu_select", selected]
+["popupmenu_select", selected] ~
 	Select an item in the current popupmenu. `selected` is a zero-based
 	index into the array of items from the last popupmenu_show event, or
 	-1 if no item is selected.
 
-["popupmenu_hide"]
+["popupmenu_hide"] ~
 	Hide the popupmenu.
 
 ==============================================================================
@@ -663,7 +670,7 @@ Tabline Events							   *ui-tabline*
 
 Activated by the `ext_tabline` |ui-option|.
 
-["tabline_update", curtab, tabs, curbuf, buffers]
+["tabline_update", curtab, tabs, curbuf, buffers] ~
 	Tabline was updated. UIs should present this data in a custom tabline
 	widget. Note: options `curbuf` + `buffers` were added in API7.
 	curtab:   Current Tabpage
@@ -679,7 +686,7 @@ Activated by the `ext_cmdline` |ui-option|.
 This UI extension delegates presentation of the |cmdline| (except 'wildmenu').
 For command-line 'wildmenu' UI events, activate |ui-popupmenu|.
 
-["cmdline_show", content, pos, firstc, prompt, indent, level]
+["cmdline_show", content, pos, firstc, prompt, indent, level] ~
         content: List of [attrs, string]
 	         [[{}, "t"], [attrs, "est"], ...]
 
@@ -702,10 +709,10 @@ For command-line 'wildmenu' UI events, activate |ui-popupmenu|.
 	prompt has level 2. A command line invoked from the |cmdline-window|
 	has a higher level than than the edited command line.
 
-["cmdline_pos", pos, level]
+["cmdline_pos", pos, level] ~
 	Change the cursor position in the cmdline.
 
-["cmdline_special_char", c, shift, level]
+["cmdline_special_char", c, shift, level] ~
 	Display a special char in the cmdline at the cursor position. This is
 	typically used to indicate a pending state, e.g. after |c_CTRL-V|. If
 	`shift` is true the text after the cursor should be shifted, otherwise
@@ -713,12 +720,12 @@ For command-line 'wildmenu' UI events, activate |ui-popupmenu|.
 
 	Should be hidden at next cmdline_show.
 
-["cmdline_hide"]
+["cmdline_hide"] ~
 	Hide the cmdline.
 
-["cmdline_block_show", lines]
+["cmdline_block_show", lines] ~
 	Show a block of context to the current command line. For example if
-	the user defines a |:function| interactively: >
+	the user defines a |:function| interactively: >vim
 	    :function Foo()
 	    :  echo "foo"
 	    :
@@ -726,10 +733,10 @@ For command-line 'wildmenu' UI events, activate |ui-popupmenu|.
 	`lines` is a list of lines of highlighted chunks, in the same form as
 	the "cmdline_show" `contents` parameter.
 
-["cmdline_block_append", line]
+["cmdline_block_append", line] ~
 	Append a line at the end of the currently shown block.
 
-["cmdline_block_hide"]
+["cmdline_block_hide"] ~
 	Hide the block.
 
 ==============================================================================
@@ -746,7 +753,7 @@ Nvim will not allocate screen space for the cmdline or messages, and
 'cmdheight' will be forced zero. Cmdline state is emitted as |ui-cmdline|
 events, which the UI must handle.
 
-["msg_show", kind, content, replace_last]
+["msg_show", kind, content, replace_last] ~
 	Display a message to the user.
 
 	kind
@@ -780,25 +787,25 @@ events, which the UI must handle.
 	    true:  Replace the message in the most-recent `msg_show` call,
 		   but any other visible message should still remain.
 
-["msg_clear"]
+["msg_clear"] ~
 	Clear all messages currently displayed by "msg_show". (Messages sent
 	by other "msg_" events below will not be affected).
 
-["msg_showmode", content]
+["msg_showmode", content] ~
 	Shows 'showmode' and |recording| messages. `content` has the same
 	format as in "msg_show". This event is sent with empty `content` to
 	hide the last message.
 
-["msg_showcmd", content]
+["msg_showcmd", content] ~
 	Shows 'showcmd' messages. `content` has the same format as in "msg_show".
 	This event is sent with empty `content` to hide the last message.
 
-["msg_ruler", content]
+["msg_ruler", content] ~
 	Used to display 'ruler' when there is no space for the ruler in a
 	statusline. `content` has the same format as in "msg_show". This event is
 	sent with empty `content` to hide the last message.
 
-["msg_history_show", entries]
+["msg_history_show", entries] ~
 	Sent when |:messages| command is invoked. History is sent as a list of
 	entries, where each entry is a `[kind, content]` tuple.