From 166aaf178cce457381e80f0e5230a0f941f0e17c Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Thu, 28 Jun 2018 00:48:17 +0200 Subject: [PATCH] doc (#8652) --- runtime/doc/autocmd.txt | 14 ++++------- runtime/doc/develop.txt | 22 +++++++---------- runtime/doc/syntax.txt | 42 +++++++++++-------------------- runtime/doc/term.txt | 2 +- runtime/doc/ui.txt | 55 ++++++++++++++++++++--------------------- 5 files changed, 56 insertions(+), 79 deletions(-) diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index 6e6d50d21f..5b2e226fbb 100644 --- a/runtime/doc/autocmd.txt +++ b/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 -|FocusLost| Vim lost input focus +|FocusGained| Nvim got 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 - version and a few console versions where this - can be detected. +FocusGained Nvim got focus. *FocusLost* -FocusLost When Vim lost input focus. Only for the GUI - version and a few console versions where this - can be detected. May also happen when a - dialog pops up. +FocusLost Nvim lost focus. Also (potentially) when + a GUI dialog pops up. *FuncUndefined* FuncUndefined When a user function is used but it isn't defined. Useful for defining a function only diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index 689f720583..b3b60cbab8 100644 --- a/runtime/doc/develop.txt +++ b/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 -existing events. +backwards-compatible, but clients must not break if new (optional) fields are +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 | and patterns like "shift shift", which - don't conflict with typical Nvim mappings. - -Implementation ~ -- UI-related options ('guifont', 'ambiwidth', …) are published in the - "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. +- Avoid mappings that conflict with the Nvim keymap-space; GUIs have many new + chords ( ) and patterns ("shift shift") that do + not potentially conflict with Nvim defaults, plugins, etc. +- Consider the "option_set" |ui-global| event as a hint for other GUI + behaviors. UI-related options ('guifont', 'ambiwidth', …) are published in + this event. vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt index fa66d9d071..88b45900a2 100644 --- a/runtime/doc/syntax.txt +++ b/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 nroffDefSpecial term=italic,bold cterm=italic,bold - \ gui=reverse,bold + hi def nroffDefinition cterm=italic gui=reverse + hi def nroffDefSpecial cterm=italic,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: -term a normal terminal (vt100, xterm) -cterm a color terminal (Windows console, color-xterm) -gui the GUI +There are two types of UIs for highlighting: +cterm terminal UI (|TUI|) +gui GUI or RGB-capable TUI ('termguicolors') 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 "" and "". Example: start=[27h;[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. diff --git a/runtime/doc/term.txt b/runtime/doc/term.txt index 075ffdac52..418623687f 100644 --- a/runtime/doc/term.txt +++ b/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 diff --git a/runtime/doc/ui.txt b/runtime/doc/ui.txt index e11fdb5271..3ce8ac1d89 100644 --- a/runtime/doc/ui.txt +++ b/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 -supports different versions of Nvim, the |api-metadata| key `ui_options` -contains the list of supported options. Additionally Nvim currently requires +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 will be used to specify which widgets actually are -active. +UIs. The "option_set" event announces which widgets actually are active. -After attaching, Nvim will send msgpack-rpc notifications, with the method -name "redraw" and a single argument, an array of screen update events. Update -events are arrays whose first element is the event name and remaining elements -are each tuples of event parameters. 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 "put", as each "put" event just puts contents in one screen -cell, but clients must be prepared for multiple argument sets being batched -for all event kinds. +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 "put", because each "put" event puts contents in +one screen cell, but clients must be prepared for multiple argument sets being +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 -elements itself; Nvim will not draw those elements on the grid. This is -controlled by the |ui-ext-options|. +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 |ui-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, @@ -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 - listed below: + UI-related option changed, where `name` is one of: '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 - care of. For instance, instead of forwarding the raw 'mouse' option - value, `mouse_on` and `mouse_off` directly indicate if mouse support - is active right now. Some options like 'ambiwidth' have already taken - effect on the grid, where appropriate empty cells are added, however - an ui might still use these options when rendering raw text sent from - Nvim, like the text of the cmdline when |ui-ext-cmdline| is set. + Triggered when the UI first connects to Nvim, and whenever an option + is changed by the user or a plugin. + + Options are not represented here if their effects are communicated in + other UI events. For example, instead of forwarding the 'mouse' option + value, the "mouse_on" and "mouse_off" UI events directly indicate if + 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