kevin/neovim
1
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2024-12-20 03:05:11 -07:00
Code Issues Packages Projects Releases Wiki Activity

doc (#8652)

Browse Source
This commit is contained in:
Justin M. Keyes 2018-06-28 00:48:17 +02:00 committed by GitHub
parent b40f87cdf5
commit 166aaf178c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 56 additions and 79 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
runtime/doc/autocmd.txt
View File

@ -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

22
runtime/doc/develop.txt
View File

@ -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 |<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
like <C-,> <C-Enter> <C-S-x> <D-x> 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 (<C-,> <C-Enter> <C-S-x> <D-x>) 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:

42
runtime/doc/syntax.txt
View File

@ -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 "<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.

2
runtime/doc/term.txt
View File

@ -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

55
runtime/doc/ui.txt
View File

@ -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