diff options
Diffstat (limited to 'runtime')
| -rw-r--r-- | runtime/autoload/man.vim | 11 | ||||
| -rw-r--r-- | runtime/doc/eval.txt | 8 | ||||
| -rw-r--r-- | runtime/doc/starting.txt | 2 | ||||
| -rw-r--r-- | runtime/doc/syntax.txt | 7 | ||||
| -rw-r--r-- | runtime/doc/ui.txt | 113 |
5 files changed, 101 insertions, 40 deletions
diff --git a/runtime/autoload/man.vim b/runtime/autoload/man.vim index 8ca78f2782..21f2dfc58a 100644 --- a/runtime/autoload/man.vim +++ b/runtime/autoload/man.vim @@ -149,9 +149,9 @@ function! s:system(cmd, ...) abort endfunction function! s:get_page(path) abort - " Disable hard-wrap by setting $MANWIDTH to a high value. - " Use soft wrap instead (ftplugin/man.vim sets 'wrap', 'breakindent'). - let manwidth = 9999 + " Disable hard-wrap by using a big $MANWIDTH (max 1000 on some systems #9065). + " We use soft wrap: ftplugin/man.vim sets wrap/breakindent/…. + let manwidth = 999 " Force MANPAGER=cat to ensure Vim is not recursively invoked (by man-db). " http://comments.gmane.org/gmane.editors.vim.devel/29085 " Set MAN_KEEP_FORMATTING so Debian man doesn't discard backspaces. @@ -168,9 +168,10 @@ function! s:put_page(page) abort silent keepjumps 1delete _ endwhile " XXX: nroff justifies text by filling it with whitespace. That interacts - " badly with our use of $MANWIDTH=9999. Hack around this by using a fixed + " badly with our use of $MANWIDTH=999. Hack around this by using a fixed " size for those whitespace regions. - silent! keeppatterns keepjumps %s/\s\{999,}/\=repeat(' ', 10)/g + silent! keeppatterns keepjumps %s/\s\{199,}/\=repeat(' ', 10)/g + 1 lua require("man").highlight_man_page() setlocal filetype=man endfunction diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index 064c08c190..2e1d89c524 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -9136,6 +9136,14 @@ This does NOT work: > variables are automatically deleted when the function ends. +:unl[et] ${env-name} ... *:unlet-environment* *:unlet-$* + Remove environment variable {env-name}. + Can mix {name} and ${env-name} in one :unlet command. + No error message is given for a non-existing + variable, also without !. + If the system does not support deleting an environment + variable, it is made emtpy. + :lockv[ar][!] [depth] {name} ... *:lockvar* *:lockv* Lock the internal variable {name}. Locking means that it can no longer be changed (until it is unlocked). diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt index dd9f9ad0f3..34c4db4047 100644 --- a/runtime/doc/starting.txt +++ b/runtime/doc/starting.txt @@ -358,6 +358,8 @@ argument. instance a `nvim_get_api_info` call so that UI features can be safely detected by the UI before attaching. + See |ui-startup| for more information about UI startup. + To embed nvim without using the UI protocol, `--headless` should be supplied together with `--embed`. Then initialization is performed without waiting for an UI. This is also equivalent diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt index 6a73061aca..c3664ece18 100644 --- a/runtime/doc/syntax.txt +++ b/runtime/doc/syntax.txt @@ -4665,8 +4665,8 @@ cterm={attr-list} *attr-list* *highlight-cterm* *E418* Note that "bold" can be used here and by using a bold font. They have the same effect. - If running in a terminal, "undercurl" acts as an alias for "underline". - It is set using |highlight-guisp|. + "undercurl" falls back to "underline" in a terminal that does not + support it. The color is set using |highlight-guisp|. start={term-list} *highlight-start* *E422* stop={term-list} *term-list* *highlight-stop* @@ -4799,7 +4799,8 @@ guifg={color-name} *highlight-guifg* guibg={color-name} *highlight-guibg* guisp={color-name} *highlight-guisp* These give the foreground (guifg), background (guibg) and special - (guisp) color to use in the GUI. "guisp" is used for undercurl. + (guisp) color to use in the GUI. "guisp" is used for undercurl + and underline. There are a few special names: NONE no color (transparent) bg use normal background color diff --git a/runtime/doc/ui.txt b/runtime/doc/ui.txt index 42ce7a5edf..a0f1b0770e 100644 --- a/runtime/doc/ui.txt +++ b/runtime/doc/ui.txt @@ -16,10 +16,12 @@ 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 +The |nvim_ui_attach()| API method is used to tell Nvim that your program wants to +draw the Nvim screen grid with a size of width × height cells. This is typically +done by an embedder, see |ui-startup| below for details, but an UI can also +connect to a running nvim instance and invoke this method. `options` must be a dictionary with these (optional) keys: `rgb` Decides the color format. *ui-rgb* Set true (default) for 24-bit RGB colors. @@ -29,7 +31,7 @@ a dictionary with these (optional) keys: `ext_tabline` Externalize the tabline. |ui-tabline| `ext_cmdline` Externalize the cmdline. |ui-cmdline| `ext_wildmenu` Externalize the wildmenu. |ui-wildmenu| - `ext_newgrid` Use new revision of the grid events. |ui-newgrid| + `ext_linegrid` Use new revision of the grid events. |ui-linegrid| `ext_hlstate` Use detailed highlight state. |ui-hlstate| Specifying a non-existent option is an error. UIs can check the |api-metadata| @@ -43,22 +45,26 @@ Nvim sends msgpack-rpc notifications to all attached UIs, with method name 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 -state after all events in the same "redraw" batch are processed (not any -intermediate state after processing only part of the array). +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 +sets being batched for all event kinds. + +Events must be handled in-order. A "flush" event is sent when nvim is done +redrawing the entire screen (so that all windows have a consistent view of +buffer state, options etc). Clients should be prepared that several "redraw" +batches are sent before the entire screen has been redrawn, and only the last +batch will end in "flush". The user should only see the final state when +"flush" is sent, and not any intermediate state after processing only part of +the batch array, nor after a batch not ending with "flush". 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-newgrid|, enabled by -`ext_newgrid` option, has some improvements, such as a more efficient -representation of highlighted text, simplified events and room for futher -enhancements that will use multiple grids. The older revision is available and -used by default only for backwards compatibility reasons. New UIs are strongly -recommended to use |ui-newgrid|, as further protocol extensions will require it. +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 +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. Nvim optionally sends screen elements "semantically" as structured events instead of raw grid-lines, controlled by |ui-ext-options|. The UI must present @@ -69,8 +75,44 @@ to existing update kinds. Clients must be prepared to ignore such extensions, for forward-compatibility. |api-contract| ============================================================================== +UI startup *ui-startup* + +Nvim defines a standard procedure for how an embedding UI should interact with +the startup phase of Nvim. When spawning the nvim process, use the |--embed| flag +but not the |--headless| flag. The started Nvim process will pause before loading +startup files and reading buffers, and give the UI a chance to invoke requests +to do early initialization. As soon as the UI invokes |nvim_ui_attach()|, the +startup will continue. + +A simple UI only need to do a single |nvim_ui_attach()| request and then +be prepared to handle any UI event. A more featureful UI, which might need +additional configuration of the nvim process, should use the following startup +procedure: + +1. Invoke |nvim_get_api_info()|, if this is needed to setup the client library + and/or to get the list of supported UI extensions. +2. At this time, any configuration that should be happen before init.vim + loading should be done. Buffers and windows are not available at this + point, but this could be used to set |g:| variables visible to init.vim +3. If the UI wants to do additional setup after the init.vim file was loaded + register an autocmd for VimEnter at this point: > + + nvim_command("autocmd VimEnter * call rpcrequest(1, 'vimenter')") + +<4. Now invoke |nvim_ui_attach()|. The UI will need to handle keyboard input + at this point, as sourcing init.vim and loading buffers might lead to + blocking prompts. +5. If step 3 was used, nvim will send a blocking "vimenter" request to the + UI. Inside this request handler, the UI can safely do any initialization + before entering normal mode, for instance reading variables set by + init.vim. + +============================================================================== Global Events *ui-global* +The following events will always be available, and describe global state of +the editor. + ["set_title", title] ["set_icon", icon] Set the window title, and icon (minimized) window title, respectively. @@ -144,15 +186,15 @@ Global Events *ui-global* 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"] +["busy_start"] +["busy_stop"] Nvim started or stopped being busy, and possibly not responsive 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. + |:suspend| command or |CTRL-Z| mapping is used. A terminal client (or + another client where it makes sense) could suspend itself. Other + clients can safely ignore it. ["update_menu"] The menu mappings changed. @@ -161,16 +203,24 @@ Global Events *ui-global* ["visual_bell"] Notify the user with an audible or visual bell, respectively. +["flush"] + Nvim is done redrawing the screen. For an implementation that renders + to an internal buffer, this is the time to display the redrawn parts + to the user. + ============================================================================== -Grid Events (new revision) *ui-newgrid* +Grid Events (line-based) *ui-linegrid* -These events are used if `ext_newgrid` option is set (recommended for all new -UIs). +These events are used if `ext_linegrid` option is set (recommended for all new +UIs). The biggest change compared to previous revision is to use a single +event `grid_line` to update the contents of a screen line (where the old +protocol used a combination of cursor, highlight and text events) Most of these events take a `grid` index as first parameter. Grid 1 is the global grid used by default for the entire editor screen state. Grids other -than that will be defined by future extensions. Just activating the `ext_newgrid` -option by itself will never cause any additional grids to be created. +than that will be defined by future extensions. Just activating the +`ext_linegrid` option by itself will never cause any additional grids to be +created. Highlight attribute groups are predefined. UIs should maintain a table to map numerical highlight `id`:s to the actual attributes. @@ -299,10 +349,10 @@ numerical highlight `id`:s to the actual attributes. from `set_scroll_region` which was end-inclusive. ============================================================================== -Grid Events (first revision) *ui-grid-old* +Legacy Grid Events (cell based) *ui-grid-old* -This is an older representation of the screen grid, used if `ext_newgrid` -option is not set. +This is an older representation of the screen grid, used if `ext_linegrid` +option is not set. New UIs should use |ui-linegrid|. ["resize", width, height] The grid is resized to `width` and `height` cells. @@ -389,9 +439,8 @@ option is not set. ============================================================================== Detailed highlight state Extension *ui-hlstate* - Only sent if `ext_hlstate` option is set in |ui-options|. `ext_hlstate` implies -`ext_newgrid`. +`ext_linegrid`. By default, nvim will only describe grid cells using the final calculated higlight attributes, as described by the dict keys in |ui-event-highlight_set|. |