multigrid: doc update

runtime/doc/ui.txt

@@ -12,9 +12,10 @@ Nvim UI protocol							  *ui*
 UI Events							    *ui-events*
 
 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,
+RPC API. The default UI model consists of a terminal-like grid with a single,
-monospace font size. Some elements (UI "widgets") can be drawn separately from
+monospace font size. The UI can opt-in to have windows drawn on separate
-the grid ("externalized").
+grids, as well as to have some elements (UI "widgets") be drawn by the UI
+itself rather than by nvim ("externalized").
 
 
 								  *ui-options*
@@ -47,7 +48,7 @@ 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 screen line, but clients must be prepared for multiple argument
+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
@@ -62,13 +63,12 @@ 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 effecient representation of text (especially
-highlighted text), and room for futher enhancements that will use
+highlighted text), and allows extensions that use multiple grids.
-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 will require it.
 
-The new grid-based events |ui-multigrid| enables the newer revision |ui-linegrid|
+The older revision is available and used by default only for backwards
-implicitly. The UIs need not enable them and must be prepared to handle them.
+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
@@ -480,29 +480,30 @@ because 'winhighlight' was used. UI items will be transmitted, even if the
 highlight group is cleared, so `ui_name` can always be used to reliably identify
 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` implicitly.
+`ext_linegrid` extension implicitly.
 
-The multigrid enables the UIs to manipulate window grids individually. The UIs
+The multigrid extension gives the UIs more control over how windows are
-receive a grid update for each new window. The UIs can set a grid size
+displayed. The UIs receive updates on a separate grid for each window. The UIs
-independent of how a window is positioned in the UI. This enables the UIs to
+can set the grid size independently of how much space the window occupies on
-set a different font size for each window if the UI so desires. The UIs can
+the global layout. This enables the UIs to set a different font size for each
-also utilize this feature to reserve space for scrollbars consitent with their
+window if the UI so desires. The UI can also reserve space around the border
-UI toolkit.
+of the window for its own elements, for instance 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 a new split is created. To delegate
+the UI must change the grid size whenever the outer size is changed. To
-the handling of grid size back to nvim, the UIs can request the size to be set
+delegate the handling of grid size back to nvim, the UIs should request the
-to (0, 0).
+size (0, 0).
 
-The same window can be hiden and redisplayed multiple times. This happens for
+A window can be hidden and redisplayed without its grid being deallocated.
-instance when switching tabs.
+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
@@ -525,7 +526,6 @@ instance when switching tabs.
 See |ui-linegrid| for grid events.
 See |nvim_ui_try_resize_grid| in |api-ui| to request changing the grid size.
 
-
 ==============================================================================
 Popupmenu Events						 *ui-popupmenu*