docs: breakout ui.txt from msgpack_rpc.txt

3 files changed, 285 insertions, 256 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 8aead087db..159dd93c5e 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -48,7 +48,7 @@ version.api_compatible	API is backwards-compatible with this level
 version.api_prerelease	Declares the current API level as unstable >
 			(version.api_prerelease && fn.since == version.api_level)
 functions		API function signatures
-ui_events		UI event signatures |rpc-remote-ui|
+ui_events		UI event signatures |ui|
 {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
diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt
index 9601e239f2..7af6e401da 100644
--- a/runtime/doc/msgpack_rpc.txt
+++ b/runtime/doc/msgpack_rpc.txt
@@ -243,259 +243,4 @@ Even for statically compiled clients it is good practice to avoid hardcoding
 the type codes, because a client may be built against one Nvim version but
 connect to another with different type codes.
 
-==============================================================================
-6. Remote UIs					           *rpc-remote-ui*
-
-GUIs can be implemented as external processes communicating with Nvim over the
-RPC API. The UI model consists of a terminal-like grid with a single,
-monospace font size. Some elements (UI "widgets") can be drawn separately from
-the grid ("externalized").
-
-After connecting to Nvim (usually a spawned, embedded instance) use the
-|nvim_ui_attach| API method to tell Nvim that your program wants to draw the
-Nvim screen on a grid of width × height cells. `options` must be
-a dictionary with these (optional) keys:
-	`rgb`			Controls what color format to use.
-				Set to true (default) to use 24-bit rgb
-				colors.
-				Set to false to use terminal color codes (at
-				most 256 different colors).
-	`ext_popupmenu`		Externalize the popupmenu. |ui-ext-popupmenu|
-	`ext_tabline`		Externalize the tabline. |ui-ext-tabline|
-	`ext_cmdline`		Externalize the cmdline. |ui-ext-cmdline|
-				Externalized widgets will not be drawn by
-				Nvim; only high-level data will be published
-				in new UI event kinds.
-
-Nvim will then send msgpack-rpc notifications, with the method name "redraw"
-and a single argument, an array of screen updates (described below).  These
-should be processed in order. Preferably the user should only be able to see
-the screen state after all updates in the same "redraw" event are processed
-(not any intermediate state after processing only a part of the array).
-
-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
-to be forward-compatible. |api-contract|
-
-Screen updates are tuples whose first element is the string name of the update
-kind.
-
-["resize", width, height]
-	The grid is resized to `width` and `height` cells.
-
-["clear"]
-	Clear the screen.
-
-["eol_clear"]
-	Clear from the cursor position to the end of the current line.
-
-["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]
-	Set the default foreground, background and special colors
-	respectively.
-
-
-							*ui-event-highlight_set*
-["highlight_set", attrs]
-	Set the attributes that the next text put on the screen 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
-	updates. All boolean keys default to false.
-
-	`foreground`:	foreground color.
-	`background`:	backround color.
-	`special`:	color to use for underline and undercurl, when present.
-	`reverse`:	reverse video. Foreground and background colors are
-			switched.
-	`italic`:	italic text.
-	`bold`:		bold text.
-	`underline`:	underlined text. The line has `special` color.
-	`undercurl`:	undercurled text. The curl has `special` color.
-
-["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]
-	Define the scroll region used by `scroll` below.
-
-["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.
-	Note that dst and src share a common region.
-
-	If count is bigger than 0, move a rectangle in the SR up, this can
-	happen while scrolling down.
->
-		+-------------------------+
-		| (clipped above SR)      |            ^
-		|=========================| dst_top    |
-		| dst (still in SR)       |            |
-		+-------------------------+ src_top    |
-		| src (moved up) and dst  |            |
-		|-------------------------| dst_bot    |
-		| src (cleared)           |            |
-		+=========================+ src_bot
-<
-	If count is less than zero, move a rectangle in the SR down, this can
-	happen while scrolling up.
->
-		+=========================+ src_top
-		| src (cleared)           |            |
-		|------------------------ | dst_top    |
-		| src (moved down) and dst|            |
-		+-------------------------+ src_bot    |
-		| dst (still in SR)       |            |
-		|=========================| dst_bot    |
-		| (clipped below SR)      |            v
-		+-------------------------+
-<
-["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.
-
-["mouse_on"]
-["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
-	would conflict with other usages of the mouse. It is safe for a client
-	to ignore this and always send mouse events.
-
-["busy_on"]
-["busy_off"]
-	Nvim started or stopped being busy, and possibly not responsible to user
-	input. This could be indicated to the user by hiding the cursor.
-
-["suspend"]
-	|:suspend| command or |Ctrl-Z| mapping is used. A terminal client (or other
-	client where it makes sense) could suspend itself.  Other clients can
-	safely ignore it.
-
-["bell"]
-["visual_bell"]
-	Notify the user with an audible or visual bell, respectively.
-
-["update_menu"]
-	The menu mappings changed.
-
-["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` event.
-
-Each mode property map may contain these keys:
-	KEY		DESCRIPTION ~
-	`cursor_shape`:	"block", "horizontal", "vertical"
-	`cell_percentage`: Cell % occupied by the cursor.
-	`blinkwait`, `blinkon`, `blinkoff`: See |cursor-blinking|.
-	`hl_id`:	Cursor highlight group.
-	`hl_lm`:	Cursor highlight group if 'langmap' is active.
-	`short_name`:	Mode code name, see 'guicursor'.
-	`name`:		Mode descriptive name.
-	`mouse_shape`:	(To be implemented.)
-
-Some keys are missing in some modes.
-
-["mode_change", mode, mode_idx]
-The mode changed.  The first parameter `mode` is a string representing the
-current mode. `mode_idx` is an index into the array received in the
-`mode_info_set` event. UIs should change the cursor style according to the
-properties specified in the corresponding item. The set of modes reported will
-change in new versions of Nvim, for instance more submodes and temporary
-states might be represented as separate modes.
-
-							*ui-ext-popupmenu*
-["popupmenu_show", items, selected, row, col]
-	When `popupmenu_external` is set to true, nvim will not draw the
-	popupmenu on the grid, instead when the popupmenu is to be displayed
-	this update is sent. `items` is an array of the items to show, the
-	items are themselves arrays of the form [word, kind, menu, info]
-	as defined at |complete-items|, except that `word` is replaced by
-	`abbr` if present.  `selected` is the initially selected item, either a
-	zero-based index into the array of items, or -1 if no item is
-	selected. `row` and `col` is the anchor position, where the first
-	character of the completed word will be.
-
-["popupmenu_select", selected]
-	An item in the currently displayed popupmenu is selected. `selected`
-	is either a zero-based index into the array of items from the last
-	`popupmenu_show` event, or -1 if no item is selected.
-
-["popupmenu_hide"]
-	The popupmenu is hidden.
-
-							*ui-ext-tabline*
-["tabline_update", curtab, tabs]
-	Tabline was updated. UIs should present this data in a custom tabline
-	widget.
-	curtab:	  Current Tabpage
-	tabs:	  List of Dicts [{ "tab": Tabpage, "name": String }, ...]
-
-							*ui-ext-cmdline*
-["cmdline_show", content, pos, firstc, prompt, indent, level]
-        content: List of [attrs, string]
-	         [[{}, "t"], [attrs, "est"], ...]
-	When cmdline_external is set to true, nvim will not draw the cmdline
-	on the grid, instead nvim will send ui events of the cmdline content
-	and cursor position to the remote ui. The `content` is the full content
-	that should be displayed in the cmdline, and the `pos` is the position
-	of the cursor that in the cmdline. This event will be triggered when
-	you type in the cmdline. The content is divided into chunks with
-	different highlight attributes represented as a dict, see
-	|ui-event-highlight_set|.
-
-	`firstc` and `prompt` are text, that if non-empty should be
-	displayed in front of the command line. `firstc` always indicates
-	built in command lines such as `:` (ex command) and `/` `?` (search),
-	while `prompt` is an |input()| prompt. `indent` tells how many spaces
-	the content should be indented
-
-	The command line in nvim can be invoked recursively, for instance by
-	typing `<c-r>=` at the command line prompt. The `level` field is used
-	to distinguish different command lines active at the same time. The
-	first invoked command line will always have level 1, and the next
-	recursively invoked prompt will have level 2. Also, a command line
-	invoked while in command line window will have a higher level than
-	than the edited command line.
-
-["cmdline_pos", pos, level]
-	Change the cursor position in the cmdline.
-
-["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, like right after Ctrl-V.
-	if shift is true the text after the cursor should be shifted,
-	otherwise it should overshadow the char at the cursor.
-	Should be hidden at next cmdline_char
-
-
-["cmdline_hide"]
-	Hide the cmdline.
-
-["cmdline_block_show", lines]
-	Show a block of context to the current command line. This occurs for
-	instance if a function is interactively defined at the command line.
-	`lines` is a list of lines where each line is represented as a list of
-	highlighted chunks, just like `contents` of |ui-event-cmdline_show|.
-
-["cmdline_block_append", line]
-	Append a line at the end of the currently shown block.
-
-["cmdline_block_hide"]
-	Hide the block.
 
-==============================================================================
- vim:tw=78:ts=8:noet:ft=help:norl:
diff --git a/runtime/doc/ui.txt b/runtime/doc/ui.txt
new file mode 100644
index 0000000000..b875c1b183
--- /dev/null
+++ b/runtime/doc/ui.txt
@@ -0,0 +1,284 @@
+*ui.txt*	Nvim
+
+
+		 NVIM REFERENCE MANUAL    by Thiago de Arruda
+
+
+UI protocol					     *ui*
+
+				      Type <M-]> to see the table of contents.
+
+==============================================================================
+Introduction							     *ui-intro*
+
+GUIs can be implemented as external processes communicating with Nvim over the
+RPC API. The UI model consists of a terminal-like grid with a single,
+monospace font size. Some elements (UI "widgets") can be drawn separately from
+the grid ("externalized").
+
+								    *ui-options*
+After connecting to Nvim (usually a spawned, embedded instance) use the
+|nvim_ui_attach| API method to tell Nvim that your program wants to draw the
+Nvim screen grid with a size of width × height cells. `options` must be
+a dictionary with these (optional) keys:
+	`rgb`			Controls what color format to use.
+				Set to true (default) to use 24-bit rgb
+				colors.
+				Set to false to use terminal color codes (at
+				most 256 different colors).
+	`ext_popupmenu`		Externalize the popupmenu. |ui-popupmenu|
+	`ext_tabline`		Externalize the tabline. |ui-tabline|
+	`ext_cmdline`		Externalize the cmdline. |ui-cmdline|
+
+Nvim will then send msgpack-rpc notifications, with the method name "redraw"
+and a single argument, an array of screen update events.
+Update events are tuples whose first element is the string name of the update
+kind. The rest are parameters for each update, described in the sections below.
+These should be processed in order. Preferably the user should only be able to
+see the screen state after all update events in the same "redraw" event are
+processed (not any intermediate state after processing only a part of the
+array).
+
+Section 2 and 3 describes grid and mode events that are send unconditionally,
+and suffice to implement a terminal-like interface. Nvim also allows a number
+of screen elements to be sent as descriptive events for the GUI to draw
+itself, rather than Nvim drawing itself on the grid. This is controlled by the
+`ext_` options.
+
+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
+to be forward-compatible. |api-contract|
+
+==============================================================================
+Global Events							    *ui-global*
+
+["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]
+	`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`
+	event.
+
+Each mode property map may contain these keys:
+	KEY		DESCRIPTION ~
+	`cursor_shape`:	"block", "horizontal", "vertical"
+	`cell_percentage`: Cell % occupied by the cursor.
+	`blinkwait`, `blinkon`, `blinkoff`: See |cursor-blinking|.
+	`hl_id`:	Cursor highlight group.
+	`hl_lm`:	Cursor highlight group if 'langmap' is active.
+	`short_name`:	Mode code name, see 'guicursor'.
+	`name`:		Mode descriptive name.
+	`mouse_shape`:	(To be implemented.)
+
+Some keys are missing in some modes.
+
+["mode_change", mode, mode_idx]
+	The mode changed.  The first parameter `mode` is a string representing
+	the current mode. `mode_idx` is an index into the array received in
+	the `mode_info_set` event. UIs should change the cursor style
+	according to the properties specified in the corresponding item. The
+	set of modes reported will change in new versions of Nvim, for
+	instance more submodes and temporary states might be represented as
+	separate modes.
+
+
+["mouse_on"]
+["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
+	would conflict with other usages of the mouse. It is safe for a client
+	to ignore this and always send mouse events.
+
+["busy_on"]
+["busy_off"]
+	Nvim started or stopped being busy, and possibly not responsible to user
+	input. This could be indicated to the user by hiding the cursor.
+
+["suspend"]
+	|:suspend| command or |Ctrl-Z| mapping is used. A terminal client (or other
+	client where it makes sense) could suspend itself.  Other clients can
+	safely ignore it.
+
+["update_menu"]
+	The menu mappings changed.
+
+["bell"]
+["visual_bell"]
+	Notify the user with an audible or visual bell, respectively.
+
+==============================================================================
+Grid Events							      *ui-grid*
+
+["resize", width, height]
+	The grid is resized to `width` and `height` cells.
+
+["clear"]
+	Clear the grid.
+
+["eol_clear"]
+	Clear from the cursor position to the end of the current line.
+
+["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]
+	Set the default foreground, background and special colors
+	respectively.
+
+							*ui-event-highlight_set*
+["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
+	updates. All boolean keys default to false.
+
+	`foreground`:	foreground color.
+	`background`:	backround color.
+	`special`:	color to use for underline and undercurl, when present.
+	`reverse`:	reverse video. Foreground and background colors are
+			switched.
+	`italic`:	italic text.
+	`bold`:		bold text.
+	`underline`:	underlined text. The line has `special` color.
+	`undercurl`:	undercurled text. The curl has `special` color.
+
+["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]
+	Define the scroll region used by `scroll` below.
+
+["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.
+	Note that dst and src share a common region.
+
+	If count is bigger than 0, move a rectangle in the SR up, this can
+	happen while scrolling down.
+>
+		+-------------------------+
+		| (clipped above SR)      |            ^
+		|=========================| dst_top    |
+		| dst (still in SR)       |            |
+		+-------------------------+ src_top    |
+		| src (moved up) and dst  |            |
+		|-------------------------| dst_bot    |
+		| src (cleared)           |            |
+		+=========================+ src_bot
+<
+	If count is less than zero, move a rectangle in the SR down, this can
+	happen while scrolling up.
+>
+		+=========================+ src_top
+		| src (cleared)           |            |
+		|------------------------ | dst_top    |
+		| src (moved down) and dst|            |
+		+-------------------------+ src_bot    |
+		| dst (still in SR)       |            |
+		|=========================| dst_bot    |
+		| (clipped below SR)      |            v
+		+-------------------------+
+<
+==============================================================================
+Popupmenu Events						 *ui-popupmenu*
+
+Only sent if `ext_popupmenu` option is set in |ui-options|
+
+["popupmenu_show", items, selected, row, col]
+	`items` is an array of the items to show, the
+	items are themselves arrays of the form [word, kind, menu, info]
+	as defined at |complete-items|, except that `word` is replaced by
+	`abbr` if present.  `selected` is the initially selected item, either a
+	zero-based index into the array of items, or -1 if no item is
+	selected. `row` and `col` is the anchor position, where the first
+	character of the completed word will be.
+
+["popupmenu_select", selected]
+	An item in the currently displayed popupmenu is selected. `selected`
+	is either a zero-based index into the array of items from the last
+	`popupmenu_show` event, or -1 if no item is selected.
+
+["popupmenu_hide"]
+	The popupmenu is hidden.
+
+==============================================================================
+Tabline Events							   *ui-tabline*
+
+Only sent if `ext_tabline` option is set in |ui-options|
+
+["tabline_update", curtab, tabs]
+	Tabline was updated. UIs should present this data in a custom tabline
+	widget.
+	curtab:	  Current Tabpage
+	tabs:	  List of Dicts [{ "tab": Tabpage, "name": String }, ...]
+
+==============================================================================
+Cmdline Events							   *ui-cmdline*
+
+Only sent if `ext_cmdline` option is set in |ui-options|
+
+["cmdline_show", content, pos, firstc, prompt, indent, level]
+        content: List of [attrs, string]
+	         [[{}, "t"], [attrs, "est"], ...]
+	The `content` is the full content that should be displayed in the
+	cmdline, and the `pos` is the position of the cursor that in the
+	cmdline. This event will be triggered when you type in the cmdline.
+	The content is divided into chunks with different highlight attributes
+	represented as a dict, see |ui-event-highlight_set|.
+
+	`firstc` and `prompt` are text, that if non-empty should be
+	displayed in front of the command line. `firstc` always indicates
+	built in command lines such as `:` (ex command) and `/` `?` (search),
+	while `prompt` is an |input()| prompt. `indent` tells how many spaces
+	the content should be indented
+
+	The command line in nvim can be invoked recursively, for instance by
+	typing `<c-r>=` at the command line prompt. The `level` field is used
+	to distinguish different command lines active at the same time. The
+	first invoked command line will always have level 1, and the next
+	recursively invoked prompt will have level 2. Also, a command line
+	invoked while in command line window will have a higher level than
+	than the edited command line.
+
+["cmdline_pos", pos, level]
+	Change the cursor position in the cmdline.
+
+["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, like right after Ctrl-V.
+	if shift is true the text after the cursor should be shifted,
+	otherwise it should overshadow the char at the cursor.
+	Should be hidden at next cmdline_char
+
+["cmdline_hide"]
+	Hide the cmdline.
+
+["cmdline_block_show", lines]
+	Show a block of context to the current command line. This occurs for
+	instance if a function is interactively defined at the command line.
+	`lines` is a list of lines where each line is represented as a list of
+	highlighted chunks, just like `contents` of |ui-event-cmdline_show|.
+
+["cmdline_block_append", line]
+	Append a line at the end of the currently shown block.
+
+["cmdline_block_hide"]
+	Hide the block.
+
+==============================================================================
+ vim:tw=78:ts=8:noet:ft=help:norl: