doc

6 files changed, 156 insertions, 131 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index fb4818bc2f..7c87ca7887 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -46,7 +46,7 @@ version.api_prerelease	Declares the API as unstable/unreleased >
 			(version.api_prerelease && fn.since == version.api_level)
 functions		API function signatures
 ui_events		UI event signatures |ui|
-ui_options		Supported |ui-options|
+ui_options		Supported |ui-option|s
 {fn}.since		API level where function {fn} was introduced
 {fn}.deprecated_since	API level where function {fn} was deprecated
 types			Custom handle types defined by Nvim
@@ -766,7 +766,7 @@ 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 "#rrggbb" hexadecimal string.
 
-                Examples: >
+                Example: >
                     :echo nvim_get_color_by_name("Pink")
                     :echo nvim_get_color_by_name("#cbcbcb")
 <
@@ -1104,11 +1104,11 @@ nvim_list_uis()                                              *nvim_list_uis()*
 
                 Return: ~
                     Array of UI dictionaries, each with these keys:
-                    - "height" requested height of the UI
-                    - "width" requested width of the UI
+                    - "height" Requested height of the UI
+                    - "width" Requested width of the UI
                     - "rgb" true if the UI uses RGB colors (false implies
                       |cterm-colors|)
-                    - "ext_..." Requested UI extensions, see |ui-options|
+                    - "ext_..." Requested UI extensions, see |ui-option|
                     - "chan" Channel id of remote UI (not present for TUI)
 
 nvim_get_proc_children({pid})                       *nvim_get_proc_children()*
@@ -1765,7 +1765,7 @@ nvim_ui_attach({width}, {height}, {options})                *nvim_ui_attach()*
                 Parameters: ~
                     {width}    Requested screen columns
                     {height}   Requested screen rows
-                    {options}  |ui-options| map
+                    {options}  |ui-option| map
 
 nvim_ui_detach()                                            *nvim_ui_detach()*
                 Deactivates UI events on the channel.
diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt
index e6b6a9df45..b56240353f 100644
--- a/runtime/doc/deprecated.txt
+++ b/runtime/doc/deprecated.txt
@@ -69,7 +69,7 @@ Options ~
 
 UI extensions~
 *ui-wildmenu*		Use |ui-cmdline| with |ui-popupmenu| instead. Enabled
-			by `ext_wildmenu` |ui-options|. Emits these events:
+			by the `ext_wildmenu` |ui-option|. Emits these events:
 				["wildmenu_show", items]
 				["wildmenu_select", selected]
 				["wildmenu_hide"]
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index a6ba7ee9c5..843e23ee54 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -157,28 +157,32 @@ with a {thing} that groups functions under a common concept).
 
 Use existing common {action} names if possible:
     add   Append to, or insert into, a collection
-    get   Get a thing (or subset of things by some query)
-    set   Set a thing
+    get   Get a thing (or group of things by query)
+    set   Set a thing (or group of things)
     del   Delete a thing (or group of things)
     list  Get all things
 
 Use consistent names for {thing} in all API functions. E.g. a buffer is called
 "buf" everywhere, not "buffer" in some places and "buf" in others.
 
-Example: `nvim_get_current_line` acts on the global editor state; the common
-{action} "get" is used but {thing} is omitted.
+Example:
+    `nvim_get_current_line` acts on the global editor state; the common
+    {action} "get" is used but {thing} is omitted.
 
-Example: `nvim_buf_add_highlight` acts on a `Buffer` object (the first
-parameter) and uses the common {action} "add".
+Example:
+    `nvim_buf_add_highlight` acts on a `Buffer` object (the first parameter)
+    and uses the common {action} "add".
 
-Example: `nvim_list_bufs` operates in a global context (first parameter is
-_not_ a Buffer). The common {action} "list" indicates that it lists all
-bufs (plural) in the global context.
+Example:
+    `nvim_list_bufs` operates in a global context (first parameter is not
+    a Buffer). The common {action} "list" indicates that it lists all bufs
+    (plural) in the global context.
 
 Use this template to name new API events:
     nvim_{thing}_{event}_event
 
-Example: `nvim_buf_changedtick_event`.
+Example:
+    `nvim_buf_changedtick_event`
 
 
 API-CLIENT						*dev-api-client*
diff --git a/runtime/doc/ui.txt b/runtime/doc/ui.txt
index 9b0b32299a..60d55bda61 100644
--- a/runtime/doc/ui.txt
+++ b/runtime/doc/ui.txt
@@ -11,22 +11,23 @@ Nvim UI protocol							  *ui*
 ==============================================================================
 UI Events							    *ui-events*
 
-GUIs can be implemented as external processes communicating with Nvim over the
-RPC API. The default UI model consists of a terminal-like grid with a single,
-monospace font size. The UI can opt-in to have windows drawn on separate
-grids, as well as to have some elements (UI "widgets") be drawn by the UI
-itself rather than by nvim ("externalized").
-
-
-								  *ui-options*
-The |nvim_ui_attach()| API method is used to tell Nvim that your program wants to
-draw the Nvim screen grid with a size of width × height cells. This is typically
-done by an embedder, see |ui-startup| below for details, but an UI can also
-connect to a running nvim instance and invoke this method. `options` must be
-a dictionary with these (optional) keys:
-	`rgb`			Decides the color format. *ui-rgb*
+UIs can be implemented as external client processes communicating with Nvim
+over the RPC API. The default UI model is a terminal-like grid with a single,
+monospace font. The UI can opt-in to have windows drawn on separate grids, and
+have some elements ("widgets") presented by the UI itself rather than by Nvim
+("externalized").
+
+							*ui-option*
+Call |nvim_ui_attach()| to tell Nvim that your program wants to draw the Nvim
+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
@@ -34,54 +35,74 @@ a dictionary with these (optional) keys:
 				false:	(default) Disable UI capabilities not
 					supported by all connected UIs
 					(including TUI).
-							      *ui-ext-options*
+							*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_cmdline`		Externalize the cmdline. |ui-cmdline|
-	`ext_messages`		Externalize messages. |ui-messages|
-	`ext_linegrid`		Use new revision of the grid events. |ui-linegrid|
-	`ext_multigrid`		Use per-window grid based events. |ui-multigrid|
-	`ext_hlstate`		Use detailed highlight state. |ui-hlstate|
 	`ext_termcolors`	Use external default colors.
 
-Specifying a non-existent option is an error. UIs can check the |api-metadata|
-`ui_options` key for supported options. Additionally Nvim (currently) requires
-that all connected UIs use the same set of widgets. Therefore the active
-widgets will be the intersection of the requested widget sets of all connected
-UIs. The "option_set" event announces which widgets actually are active.
-
-Nvim sends msgpack-rpc notifications to all attached UIs, with method name
-"redraw" and a single argument: an array (batch) of screen "update events".
-Each update event is itself an array whose first element is the event name and
-remaining elements are event-parameter tuples. This allows multiple events of
-the same kind to be sent in a row without the event name being repeated. This
-batching is mostly used for "grid_line", because each "grid_line" event puts
-contents in one grid line, but clients must be prepared for multiple argument
-sets being batched for all event kinds.
-
-Events must be handled in-order. A "flush" event is sent when nvim is done
-redrawing the entire screen (so that all windows have a consistent view of
-buffer state, options etc). Clients should be prepared that several "redraw"
-batches are sent before the entire screen has been redrawn, and only the last
-batch will end in "flush". The user should only see the final state when
-"flush" is sent, and not any intermediate state after processing only part of
-the batch array, nor after a batch not ending with "flush".
-
-By default, Nvim sends |ui-global| and |ui-grid-old| events; these suffice to
-implement a terminal-like interface. However there are two revisions of the
-grid part of the protocol. The newer revision |ui-linegrid|, enabled by
-`ext_linegrid` option, has a more efficient representation of text (especially
-highlighted text), and allows extensions that use multiple grids.
-
-The older revision is available and used by default only for backwards
-compatibility reasons. New UIs are strongly recommended to use |ui-linegrid|,
-as further protocol extensions require it. The |ui-multigrid| extension
-enables |ui-linegrid| implicitly.
-
-Nvim optionally sends screen elements "semantically" as structured events
-instead of raw grid-lines, controlled by |ui-ext-options|. The UI must present
-those elements itself; Nvim will not draw those elements on the grid.
+Specifying an unknown option is an error; UIs can check the |api-metadata|
+`ui_options` key for supported options.
+
+By default Nvim requires all connected UIs to support the same capabilities,
+thus the active capabilities are the intersection of those requested. UIs may
+specify |ui-override| to invert this behavior (useful for debugging). The
+"option_set" event announces which capabilities are active.
+
+Nvim sends RPC notifications to all attached UIs, with method name "redraw"
+and a single argument: an array (batch) of screen "update events". Each update
+event is itself an array whose first element is the event name and remaining
+elements are event-parameter tuples. Thus multiple events of the same kind can
+be sent contiguously without repeating the event name.
+
+Example of a typical "redraw" batch in a single RPC notification: >
+
+    ['notification', 'redraw',
+      [
+	['grid_resize', [2, 77, 36]],
+	['grid_line',
+	  [2, 0, 0, [[' ' , 0, 77]]],
+	  [2, 1, 0, [['~', 7], [' ', 7, 76]]],
+	  [2, 9, 0, [['~', 7], [' ', 7, 76]]], 
+	  ...
+	  [2, 35, 0, [['~', 7], [' ', 7, 76]]],
+	  [1, 36, 0, [['[', 9], ['N'], ['o'], [' '], ['N'], ['a'], ['m'], ['e'], [']']]],
+	  [1, 36, 9, [[' ', 9, 50]]],
+	  [1, 36, 59, [['0', 9], [','], ['0'], ['-' ], ['1'], [' ', 9, 10], ['A'], ['l', 9, 2]]]
+	],
+	['msg_showmode', [[]]],
+	['win_pos', [2, 1000, 0, 0, 77, 36]],
+	['grid_cursor_goto', [2, 0, 0]],
+	['flush', []]
+      ]
+    ]
+
+Events must be handled in-order. Nvim sends a "flush" event when it has
+completed a redraw of the entire screen (so all windows have a consistent view
+of buffer state, options, etc.). Multiple "redraw" batches may be sent before
+the entire screen has been redrawn, with "flush" following only the last
+batch. The user should only see the final state (when "flush" is sent), not
+any intermediate state while processing part of the batch array, nor after
+a batch not ending with "flush".
+
+By default, Nvim sends |ui-global| and |ui-grid-old| events (for backwards
+compatibility); these suffice to implement a terminal-like interface. However
+the new |ui-linegrid| represents text more efficiently (especially highlighted
+text), and allows UI capabilities requiring multiple grids. New UIs should
+implement |ui-linegrid| instead of |ui-grid-old|.
+
+Nvim optionally sends various screen elements "semantically" as structured
+events instead of raw grid-lines, as specified by |ui-ext-options|. The UI
+must present such elements itself, Nvim will not draw them on the grid.
 
 Future versions of Nvim may add new update kinds and may append new parameters
 to existing update kinds. Clients must be prepared to ignore such extensions,
@@ -99,7 +120,7 @@ continue as soon as the UI invokes |nvim_ui_attach()|.
 
 A simple UI only needs to do a single |nvim_ui_attach()| request and then
 prepare to handle any UI event. A more featureful UI, which might need
-additional configuration of the nvim process, should use the following startup
+additional configuration of the Nvim process, should use the following startup
 procedure:
 
 1. Invoke |nvim_get_api_info()|, if needed to setup the client library and/or
@@ -119,7 +140,7 @@ procedure:
 ==============================================================================
 Global Events							    *ui-global*
 
-The following events will always be available, and describe global state of
+The following UI events are always emitted, and describe global state of
 the editor.
 
 ["set_title", title]
@@ -192,7 +213,7 @@ the editor.
 ["mouse_off"]
 	Tells the client whether mouse support, as determined by |'mouse'|
 	option, is considered to be active in the current mode. This is mostly
-	useful for a terminal frontend, or other situations where nvim mouse
+	useful for a terminal frontend, or other situations where Nvim mouse
 	would conflict with other usages of the mouse. It is safe for a client
 	to ignore this and always send mouse events.
 
@@ -221,17 +242,17 @@ the editor.
 ==============================================================================
 Grid Events (line-based)					  *ui-linegrid*
 
-These events are used if `ext_linegrid` option is set (recommended for all new
-UIs). The biggest change compared to previous revision is to use a single
-`grid_line` event to update the contents of a screen line (where the old
-protocol used a combination of cursor, highlight and text events)
+Activated by the `ext_linegrid` |ui-option|. Recommended for all new UIs.
+Deactivates |ui-grid-old| implicitly.
+
+The biggest change compared to |ui-grid-old| is to use a single `grid_line`
+event to update the contents of a screen line (whereas the old protocol used
+a combination of cursor, highlight and text events)
 
 Most of these events take a `grid` index as first parameter.  Grid 1 is the
-global grid used by default for the entire editor screen state. Grids other
-than that will be defined by future extensions. Just activating the
-`ext_linegrid` option by itself will never cause any additional grids to be
-created.  To enable per-window grids, `ext_multigrid` option should be set (see
-|ui-multigrid|).
+global grid used by default for the entire editor screen state. The
+`ext_linegrid` capability by itself will never cause any additional grids to
+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.
@@ -375,10 +396,10 @@ numerical highlight ids to the actual attributes.
 	part of handling the scroll event.
 
 ==============================================================================
-Legacy Grid Events (cell based)					   *ui-grid-old*
+Grid Events (cell-based)					   *ui-grid-old*
 
-This is an older representation of the screen grid, used if `ext_linegrid`
-option is not set. New UIs should use |ui-linegrid|.
+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]
 	The grid is resized to `width` and `height` cells.
@@ -465,8 +486,8 @@ option is not set. New UIs should use |ui-linegrid|.
 ==============================================================================
 Detailed highlight state Extension 				  *ui-hlstate*
 
-Only sent if `ext_hlstate` option is set in |ui-options|. `ext_hlstate` implies
-`ext_linegrid`.
+Activated by the `ext_hlstate` |ui-option|.
+Activates |ui-linegrid| implicitly.
 
 By default Nvim will only describe grid cells using the final calculated
 highlight attributes, as described by the dict keys in |ui-event-highlight_set|.
@@ -499,30 +520,32 @@ screen elements, even if no attributes have been applied.
 ==============================================================================
 Multigrid Events 	  					 *ui-multigrid*
 
-Only sent if `ext_multigrid` option is set in |ui-options|. Enables the
-`ext_linegrid` extension implicitly.
-
-The multigrid extension gives the UIs more control over how windows are
-displayed. The UIs receive updates on a separate grid for each window. The UIs
-can set the grid size independently of how much space the window occupies on
-the global layout. This enables the UIs to set a different font size for each
-window if the UI so desires. The UI can also reserve space around the border
-of the window for its own elements, for instance scrollbars from the UI
-toolkit.
+Activated by the `ext_multigrid` |ui-option|.
+Activates |ui-linegrid| implicitly.
 
-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.
-Once a UI sets a grid size, nvim does not handle the size for that grid and
+See |ui-linegrid| for grid events.
+See |nvim_ui_try_resize_grid()| to request changing the grid size.
+See |nvim_input_mouse()| for sending mouse events to Nvim.
+
+The multigrid extension gives UIs more control over how windows are displayed:
+- UIs receive updates on a separate grid for each window.
+- UIs can set the grid size independently of how much space the window
+  occupies on the global layout. So the UI could use a different font size
+  per-window. Or reserve space around the border of the window for its own
+  elements, such as scrollbars from the UI toolkit.
+
+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.
+Once a UI sets a grid size, Nvim does not handle the size for that grid and
 the UI must change the grid size whenever the outer size is changed. To
-delegate the handling of grid size back to nvim, the UIs should request the
-size (0, 0).
+delegate grid-size handling back to Nvim, request the size (0, 0).
 
 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]
-	Set the position and size of the grid in nvim (i.e. the outer grid
+	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.
 
@@ -553,15 +576,13 @@ tabs.
 ["win_close", grid]
 	Close the window.
 
-See |ui-linegrid| for grid events.
-See |nvim_ui_try_resize_grid| in |api-ui| to request changing the grid size.
-See |nvim_input_mouse| for sending mouse events to Nvim.
-
 ==============================================================================
 Popupmenu Events						 *ui-popupmenu*
 
-Only sent if `ext_popupmenu` option is set in |ui-options|.
-Events for |popupmenu-completion| and command-line 'wildmenu'.
+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]
 	Show |popupmenu-completion|. `items` is an array of completion items
@@ -586,7 +607,7 @@ Events for |popupmenu-completion| and command-line 'wildmenu'.
 ==============================================================================
 Tabline Events							   *ui-tabline*
 
-Only sent if `ext_tabline` option is set in |ui-options|
+Activated by the `ext_tabline` |ui-option|.
 
 ["tabline_update", curtab, tabs]
 	Tabline was updated. UIs should present this data in a custom tabline
@@ -597,8 +618,10 @@ Only sent if `ext_tabline` option is set in |ui-options|
 ==============================================================================
 Cmdline Events							   *ui-cmdline*
 
-Only sent if `ext_cmdline` option is set in |ui-options|. To handle
-command-line 'wildmenu', enable |ui-popupmenu| and handle its events.
+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]
         content: List of [attrs, string]
@@ -654,20 +677,18 @@ command-line 'wildmenu', enable |ui-popupmenu| and handle its events.
 	Hide the block.
 
 ==============================================================================
-Message Events							   *ui-messages*
+Message/Dialog Events					   *ui-messages*
 
-Only sent if `ext_messages` option is set in |ui-options|. This option
-implicitly enables `ext_linegrid` and `ext_cmdline`. |ui-linegrid| and
-|ui-cmdline| events will thus also be sent.
+Activated by the `ext_messages` |ui-option|.
+Activates |ui-linegrid| and |ui-cmdline| implicitly.
 
-This extension allows the UI to control the display of messages that otherwise
-would have been displayed in the message/cmdline area in the bottom of the
-screen.
+This UI extension delegates presentation of messages and dialogs. Messages
+that would otherwise render in the message/cmdline screen space, are emitted
+as UI events.
 
-Activating this extension means that Nvim will not allocate screen space for
-the cmdline or messages, 'cmdheight' will be zero.  Attempting to change
-'cmdheight' will be silently ignored. |ui-cmdline| events represent the state
-of the cmdline.
+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]
 	Display a message to the user.
diff --git a/src/nvim/api/ui.c b/src/nvim/api/ui.c
index 9f12ae6888..4f28ea5af3 100644
--- a/src/nvim/api/ui.c
+++ b/src/nvim/api/ui.c
@@ -89,7 +89,7 @@ void remote_ui_wait_for_attach(void)
 /// @param channel_id
 /// @param width  Requested screen columns
 /// @param height  Requested screen rows
-/// @param options  |ui-options| map
+/// @param options  |ui-option| map
 /// @param[out] err Error details, if any
 void nvim_ui_attach(uint64_t channel_id, Integer width, Integer height,
                     Dictionary options, Error *err)
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index 9e59eca396..37f2d3c367 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -2048,10 +2048,10 @@ Dictionary nvim__stats(void)
 /// Gets a list of dictionaries representing attached UIs.
 ///
 /// @return Array of UI dictionaries, each with these keys:
-///   - "height"  requested height of the UI
-///   - "width"   requested width of the UI
+///   - "height"  Requested height of the UI
+///   - "width"   Requested width of the UI
 ///   - "rgb"     true if the UI uses RGB colors (false implies |cterm-colors|)
-///   - "ext_..." Requested UI extensions, see |ui-options|
+///   - "ext_..." Requested UI extensions, see |ui-option|
 ///   - "chan"    Channel id of remote UI (not present for TUI)
 Array nvim_list_uis(void)
   FUNC_API_SINCE(4)