doc (#8652)

runtime/doc/autocmd.txt

@@ -297,8 +297,8 @@ Name			triggered by ~
 |SourceCmd|		before sourcing a Vim script |Cmd-event|
 
 |VimResized|		after the Vim window size changed
-|FocusGained|		Vim got input focus
+|FocusGained|		Nvim got focus
-|FocusLost|		Vim lost input focus
+|FocusLost|		Nvim lost focus
 |CursorHold|		the user doesn't press a key for a while
 |CursorHoldI|		the user doesn't press a key for a while in Insert mode
 |CursorMoved|		the cursor was moved in Normal mode
@@ -735,14 +735,10 @@ FilterWritePre			Before writing a file for a filter command or
 				filter command.
 				Not triggered when 'shelltemp' is off.
 							*FocusGained*
-FocusGained			When Vim got input focus.  Only for the GUI
+FocusGained			Nvim got focus.
-				version and a few console versions where this
-				can be detected.
 							*FocusLost*
-FocusLost			When Vim lost input focus.  Only for the GUI
+FocusLost			Nvim lost focus.  Also (potentially) when
-				version and a few console versions where this
+				a GUI dialog pops up.
-				can be detected.  May also happen when a
-				dialog pops up.
 							*FuncUndefined*
 FuncUndefined			When a user function is used but it isn't
 				defined.  Useful for defining a function only

runtime/doc/develop.txt

@@ -262,26 +262,22 @@ C project source, too.  https://github.com/libmpack/libmpack/
 
 EXTERNAL UI 						*dev-ui*
 
-Compatibility ~
 External UIs should be aware of the |api-contract|. In particular, future
 versions of Nvim may add new items to existing events. The API is strongly
-backwards-compatible, but clients must not break if new fields are added to
+backwards-compatible, but clients must not break if new (optional) fields are
-existing events.
+added to existing events.
 
-Common Features ~
 External UIs are expected to implement these common features:
-- Cursor style (shape, color) should respond to the 'guicursor' properties
+- Cursor style (shape, color) should conform to the 'guicursor' properties
   delivered with the mode_info_set UI event.
 - Send the ALT/META ("Option" on macOS) key as a |<M-| chord.
 - Send the "super" key (Windows key, Apple key) as a |<D-| chord.
-- Avoid mappings that conflict with Nvim defaults. GUIs have many new chords
+- Avoid mappings that conflict with the Nvim keymap-space; GUIs have many new
-  like <C-,> <C-Enter> <C-S-x> <D-x> and patterns like "shift shift", which
+  chords (<C-,> <C-Enter> <C-S-x> <D-x>) and patterns ("shift shift") that do
-  don't conflict with typical Nvim mappings.
+  not potentially conflict with Nvim defaults, plugins, etc.
-
+- Consider the "option_set" |ui-global| event as a hint for other GUI
-Implementation ~
+  behaviors. UI-related options ('guifont', 'ambiwidth', …) are published in
-- UI-related options ('guifont', 'ambiwidth', …) are published in the
+  this event.
-  "option_set" |ui-global| event.  The event is triggered when the UI first
-  connects to Nvim and whenever an option is changed by the user or a plugin.
 
 
  vim:tw=78:ts=8:ft=help:norl:

runtime/doc/syntax.txt

@@ -1727,7 +1727,7 @@ Functions and variable names are the same color by default, because VIM
 doesn't specify different colors for Functions and Identifiers.  To change
 this (which is recommended if you want function names to be recognizable in a
 different color) you need to add the following line to your vimrc: >
-  :hi Function term=underline cterm=bold ctermfg=LightGray
+  :hi Function cterm=bold ctermfg=LightGray
 
 Of course, the ctermfg can be a different color if you choose.
 
@@ -2183,9 +2183,8 @@ with the correct typesetting of your file, is to define an eye-catching
 highlighting definition for the syntax groups "nroffDefinition" and
 "nroffDefSpecial" in your configuration files.  For example: >
 
-  hi def nroffDefinition term=italic cterm=italic gui=reverse
+  hi def nroffDefinition cterm=italic gui=reverse
-  hi def nroffDefSpecial term=italic,bold cterm=italic,bold
+  hi def nroffDefSpecial cterm=italic,bold gui=reverse,bold
-			 \ gui=reverse,bold
 
 If you want to navigate preprocessor entries in your source file as easily as
 with section markers, you can activate the following option in your vimrc
@@ -4628,37 +4627,36 @@ a file with ":highlight" commands such as this: >
 Note that all settings that are not included remain the same, only the
 specified field is used, and settings are merged with previous ones.  So, the
 result is like this single command has been used: >
-   :hi Comment	term=bold ctermfg=Cyan guifg=#80a0ff gui=bold
+   :hi Comment	ctermfg=Cyan guifg=#80a0ff gui=bold
 <
 							*:highlight-verbose*
 When listing a highlight group and 'verbose' is non-zero, the listing will
 also tell where it was last set.  Example: >
 	:verbose hi Comment
-<	Comment        xxx term=bold ctermfg=4 guifg=Blue ~
+<	Comment        xxx ctermfg=4 guifg=Blue ~
 	   Last set from /home/mool/vim/vim7/runtime/syntax/syncolor.vim ~
 
 When ":hi clear" is used then the script where this command is used will be
 mentioned for the default values. See |:verbose-cmd| for more information.
 
 					*highlight-args* *E416* *E417* *E423*
-There are three types of terminals for highlighting:
+There are two types of UIs for highlighting:
-term	a normal terminal (vt100, xterm)
+cterm	terminal UI (|TUI|)
-cterm	a color terminal (Windows console, color-xterm)
+gui	GUI or RGB-capable TUI ('termguicolors')
-gui	the GUI
 
 For each type the highlighting can be given.  This makes it possible to use
-the same syntax file on all terminals, and use the optimal highlighting.
+the same syntax file on all UIs.
 
-1. highlight arguments for normal terminals
+1. TUI highlight arguments
 
 					*bold* *underline* *undercurl*
 					*inverse* *italic* *standout*
-term={attr-list}			*attr-list* *highlight-term* *E418*
+cterm={attr-list}			*attr-list* *highlight-cterm* *E418*
 	attr-list is a comma separated list (without spaces) of the
 	following items (in any order):
 		bold
 		underline
-		undercurl	a curly underline
+		undercurl	curly underline
 		reverse
 		inverse		same as reverse
 		italic
@@ -4689,17 +4687,6 @@ stop={term-list}				*term-list* *highlight-stop*
         like "<Esc>" and "<Space>".  Example:
 		start=<Esc>[27h;<Esc>[<Space>r;
 
-
-2. highlight arguments for color terminals
-
-cterm={attr-list}					*highlight-cterm*
-	See above for the description of {attr-list} |attr-list|.
-	The "cterm" argument is likely to be different from "term", when
-	colors are used.  For example, in a normal terminal comments could
-	be underlined, in a color terminal they can be made Blue.
-	Note: Many terminals (e.g., DOS console) can't mix these attributes
-	with coloring.	Use only one of "cterm=" OR "ctermfg=" OR "ctermbg=".
-
 ctermfg={color-nr}				*highlight-ctermfg* *E421*
 ctermbg={color-nr}				*highlight-ctermbg*
 	The {color-nr} argument is a color number.  Its range is zero to
@@ -4709,7 +4696,7 @@ ctermbg={color-nr}				*highlight-ctermbg*
 	"cterm".  For example, on some systems "cterm=bold ctermfg=3" gives
 	another color, on others you just get color 3.
 
-	The following names are recognized, with the color number used:
+	The following (case-insensitive) names are recognized:
 
 							*cterm-colors*
 	    NR-16   NR-8    COLOR NAME ~
@@ -4740,7 +4727,6 @@ ctermbg={color-nr}				*highlight-ctermbg*
 	"cterm=" argument AFTER the "ctermfg=" or "ctermbg=" argument.	Or use
 	a number instead of a color name.
 
-	The case of the color names is ignored.
 	Note that for 16 color ansi style terminals (including xterms), the
 	numbers in the NR-8 column is used.  Here '*' means 'add 8' so that Blue
 	is 12, DarkGray is 8 etc.
@@ -4779,7 +4765,7 @@ ctermbg={color-nr}				*highlight-ctermbg*
 	"fg" and "bg" colors will not be adjusted.
 
 
-3. highlight arguments for the GUI
+2. GUI highlight arguments
 
 gui={attr-list}						*highlight-gui*
 	These give the attributes to use in the GUI mode.

runtime/doc/term.txt

@@ -4,7 +4,7 @@
                             NVIM REFERENCE MANUAL
 
 
-Terminal UI						*tui*
+Terminal UI						*TUI* *tui*
 
 Nvim (except in |--headless| mode) uses information about the terminal you are
 using to present a built-in UI.  If that information is not correct, the

runtime/doc/ui.txt

@@ -30,34 +30,31 @@ a dictionary with these (optional) keys:
 	`ext_cmdline`		Externalize the cmdline. |ui-cmdline|
 	`ext_wildmenu`		Externalize the wildmenu. |ui-ext-wildmenu|
 
-Specifying a non-existent option is an error. To facilitate an ui that
+Specifying a non-existent option is an error. UIs can check the |api-metadata|
-supports different versions of Nvim, the |api-metadata| key `ui_options`
+`ui_options` key for supported options. Additionally Nvim (currently) requires
-contains the list of 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 will be used to specify which widgets actually are
+UIs. The "option_set" event announces which widgets actually are active.
-active.
 
-After attaching, Nvim will send msgpack-rpc notifications, with the method
+Nvim sends msgpack-rpc notifications to all attached UIs, with method name
-name "redraw" and a single argument, an array of screen update events.  Update
+"redraw" and a single argument: an array (batch) of screen "update events".
-events are arrays whose first element is the event name and remaining elements
+Each update event is itself an array whose first element is the event name and
-are each tuples of event parameters. This allows multiple events of the same
+remaining elements are event-parameter tuples. This allows multiple events of
-kind to be sent in a row without the event name being repeated. This batching
+the same kind to be sent in a row without the event name being repeated. This
-is mostly used for "put", as each "put" event just puts contents in one screen
+batching is mostly used for "put", because each "put" event puts contents in
-cell, but clients must be prepared for multiple argument sets being batched
+one screen cell, but clients must be prepared for multiple argument sets being
-for all event kinds.
+batched for all event kinds.
 
-Events must be handled in order. The user should only see the updated screen
+Events must be handled in-order. The user should only see the updated screen
 state after all events in the same "redraw" batch are processed (not any
 intermediate state after processing only part of the array).
 
 Nvim sends |ui-global| and |ui-grid| events unconditionally; these suffice to
-implement a terminal-like interface.
+implement a terminal-like layout.
 
 Nvim optionally sends screen elements "semantically" as structured events
-instead of raw grid-lines. Then the UI must decide how to present those
+instead of raw grid-lines, controlled by |ui-ext-options|. The UI must present
-elements itself; Nvim will not draw those elements on the grid. This is
+those elements itself; Nvim will not draw those elements on the |ui-grid|.
-controlled by the |ui-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,
@@ -93,8 +90,7 @@ Global Events							    *ui-global*
 	Some keys are missing in some modes.
 
 ["option_set", name, value]
-	The value of ui related option `name` changed. The sent options are
+	UI-related option changed, where `name` is one of:
-	listed below:
 
 	'arabicshape'
 	'ambiwidth'
@@ -105,15 +101,18 @@ Global Events							    *ui-global*
 	'linespace'
 	'showtabline'
 	'termguicolors'
-	`ext_*` (all |ui-ext-options|)
+	"ext_*" (all |ui-ext-options|)
 
-	Options are not added to the list if their effects are already taken
+	Triggered when the UI first connects to Nvim, and whenever an option
-	care of. For instance, instead of forwarding the raw 'mouse' option
+	is changed by the user or a plugin.
-	value, `mouse_on` and `mouse_off` directly indicate if mouse support
+
-	is active right now. Some options like 'ambiwidth' have already taken
+	Options are not represented here if their effects are communicated in
-	effect on the grid, where appropriate empty cells are added, however
+	other UI events. For example, instead of forwarding the 'mouse' option
-	an ui might still use these options when rendering raw text sent from
+	value, the "mouse_on" and "mouse_off" UI events directly indicate if
-	Nvim, like the text of the cmdline when |ui-ext-cmdline| is set.
+	mouse support is active. Some options like 'ambiwidth' have already
+	taken effect on the grid, where appropriate empty cells are added,
+	however a UI might still use such options when rendering raw text
+	sent from Nvim, like for |ui-ext-cmdline|.
 
 ["mode_change", mode, mode_idx]
 	The mode changed.  The first parameter `mode` is a string representing