diff options
Diffstat (limited to 'runtime/doc')
113 files changed, 4063 insertions, 3542 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 122ab37e72..ef8b9c7d47 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -1,4 +1,4 @@ -*api.txt* {Nvim} +*api.txt* Nvim NVIM REFERENCE MANUAL by Thiago de Arruda @@ -7,10 +7,11 @@ Nvim API *API* *api* Nvim exposes a powerful API that can be used by plugins and external processes -via |msgpack-rpc|, Lua and VimL (|eval-api|). +via |RPC|, |Lua| and VimL (|eval-api|). -Nvim can also be embedded in C applications as libnvim, so the application -can control the embedded instance by calling the C API directly. +Applications can also embed libnvim to work with the C API directly. + + Type |gO| to see the table of contents. ============================================================================== API Types *api-types* @@ -47,6 +48,7 @@ version.api_compatible API is backwards-compatible with this level version.api_prerelease Declares the current API level as unstable > (version.api_prerelease && fn.since == version.api_level) functions API function signatures +ui_events UI event signatures |ui| {fn}.since API level where function {fn} was introduced {fn}.deprecated_since API level where function {fn} was deprecated types Custom handle types defined by Nvim @@ -55,6 +57,28 @@ error_types Possible error types returned by API functions External programs ("clients") can use the metadata to discover the |rpc-api|. ============================================================================== +API contract *api-contract* + +The API is made of functions and events. Clients call functions like those +described at |api-global|, and may "attach" in order to receive rich events, +described at |rpc-remote-ui|. + +As Nvim develops, its API may change only according the following "contract": + +- New functions and events may be added. + - Any such extensions are OPTIONAL: old clients may ignore them. +- Function signatures will NOT CHANGE (after release). + - Functions introduced in the development (unreleased) version MAY CHANGE. + (Clients can dynamically check `api_prerelease`, etc. |api-metadata|) +- Event parameters will not be removed or reordered (after release). +- Events may be EXTENDED: new parameters may be added. +- New items may be ADDED to map/list parameters/results of functions and + events. + - Any such new items are OPTIONAL: old clients may ignore them. + - Existing items will not be removed (after release). +- Deprecated functions will not be removed until Nvim version 2.0 + +============================================================================== Buffer highlighting *api-highlights* Nvim allows plugins to add position-based highlights to buffers. This is @@ -111,6 +135,26 @@ nvim_command({command}) *nvim_command()* Parameters:~ {command} Ex-command string +nvim_get_hl_by_name({name}, {rgb}) *nvim_get_hl_by_name()* + Gets a highlight definition by name. + + Parameters:~ + {name} Highlight group name + {rgb} Export RGB colors + + Return:~ + Highlight definition map + +nvim_get_hl_by_id({hl_id}, {rgb}) *nvim_get_hl_by_id()* + Gets a highlight definition by id. |hlID()| + + Parameters:~ + {hl_id} Highlight id as returned by |hlID()| + {rgb} Export RGB colors + + Return:~ + Highlight definition map + nvim_feedkeys({keys}, {mode}, {escape_csi}) *nvim_feedkeys()* Passes input keys to Nvim. On VimL error: Does not fail, but updates v:errmsg. @@ -127,7 +171,11 @@ nvim_input({keys}) *nvim_input()* Unlike `nvim_feedkeys`, this uses a lower-level input buffer and the call is not deferred. This is the most reliable way to - emulate real user input. + send real user input. + + Note: + |keycodes| like <CR> are translated, so "<" is special. To + input a literal "<", send <LT>. Attributes:~ {async} @@ -141,7 +189,16 @@ nvim_input({keys}) *nvim_input()* *nvim_replace_termcodes()* nvim_replace_termcodes({str}, {from_part}, {do_lt}, {special}) - Replaces any terminal codes with the internal representation + Replaces terminal codes and |keycodes| (<CR>, <Esc>, ...) in a + string with the internal representation. + + Parameters:~ + {str} String to be converted. + {from_part} Legacy Vim parameter. Usually true. + {do_lt} Also translate <lt>. Ignored if `special` is + false. + {special} Replace |keycodes|, e.g. <CR> becomes a "\n" + char. nvim_command_output({str}) *nvim_command_output()* TODO: Documentation @@ -158,8 +215,10 @@ nvim_eval({expr}) *nvim_eval()* Evaluation result or expanded object nvim_call_function({fname}, {args}) *nvim_call_function()* - Calls a VimL function with the given arguments. On VimL error: - Returns a generic error; v:errmsg is not updated. + Calls a VimL function with the given arguments + + On VimL error: Returns a generic error; v:errmsg is not + updated. Parameters:~ {fname} Function to call @@ -168,7 +227,21 @@ nvim_call_function({fname}, {args}) *nvim_call_function()* Return:~ Result of the function call -nvim_strwidth({str}) *nvim_strwidth()* +nvim_execute_lua({code}, {args}) *nvim_execute_lua()* + Execute lua code. Parameters (if any) are available as `...` + inside the chunk. The chunk can return a value. + + Only statements are executed. To evaluate an expression, + prefix it with `return`: return my_function(...) + + Parameters:~ + {code} lua code to execute + {args} Arguments to the code + + Return:~ + Return value of lua code if present or NIL. + +nvim_strwidth({text}) *nvim_strwidth()* Calculates the number of display cells occupied by `text`. <Tab> counts as one cell. @@ -247,7 +320,7 @@ nvim_get_option({name}) *nvim_get_option()* {name} Option name Return:~ - Option value + Option value (global) nvim_set_option({name}, {value}) *nvim_set_option()* Sets an option value @@ -257,20 +330,24 @@ nvim_set_option({name}, {value}) *nvim_set_option()* {value} New option value nvim_out_write({str}) *nvim_out_write()* - Writes a message to vim output buffer + Writes a message to the Vim output buffer. Does not append + "\n", the message is buffered (won't display) until a linefeed + is written. Parameters:~ {str} Message nvim_err_write({str}) *nvim_err_write()* - Writes a message to vim error buffer + Writes a message to the Vim error buffer. Does not append + "\n", the message is buffered (won't display) until a linefeed + is written. Parameters:~ {str} Message nvim_err_writeln({str}) *nvim_err_writeln()* - Writes a message to vim error buffer. Appends a linefeed to - ensure all contents are written. + Writes a message to the Vim error buffer. Appends "\n", so the + buffer is flushed (and displayed). Parameters:~ {str} Message @@ -291,7 +368,7 @@ nvim_set_current_buf({buffer}) *nvim_set_current_buf()* Sets the current buffer Parameters:~ - {id} Buffer handle + {buffer} Buffer handle nvim_list_wins() *nvim_list_wins()* Gets the current list of window handles @@ -309,7 +386,7 @@ nvim_set_current_win({window}) *nvim_set_current_win()* Sets the current window Parameters:~ - {handle} Window handle + {window} Window handle nvim_list_tabpages() *nvim_list_tabpages()* Gets the current list of tabpage handles @@ -327,7 +404,7 @@ nvim_set_current_tabpage({tabpage}) *nvim_set_current_tabpage()* Sets the current tabpage Parameters:~ - {handle} Tabpage handle + {tabpage} Tabpage handle nvim_subscribe({event}) *nvim_subscribe()* Subscribes to event broadcasts @@ -347,6 +424,27 @@ nvim_get_color_by_name({name}) *nvim_get_color_by_name()* nvim_get_color_map() *nvim_get_color_map()* TODO: Documentation +nvim_get_mode() *nvim_get_mode()* + Gets the current mode. |mode()| "blocking" is true if Nvim is + waiting for input. + + Return:~ + Dictionary { "mode": String, "blocking": Boolean } + + Attributes:~ + {async} + +nvim_get_keymap({mode}) *nvim_get_keymap()* + Gets a list of dictionaries describing global (non-buffer) + mappings. The "buffer" key in the returned dictionary is + always zero. + + Parameters:~ + {mode} Mode short-name ("n", "i", "v", ...) + + Return:~ + Array of maparg()-like dictionaries describing mappings + nvim_get_api_info() *nvim_get_api_info()* TODO: Documentation @@ -379,6 +477,54 @@ nvim_call_atomic({calls}) *nvim_call_atomic()* error ocurred, the values from all preceding calls will still be returned. +nvim__id({obj}) *nvim__id()* + Returns object given as argument + + This API function is used for testing. One should not rely on + its presence in plugins. + + Parameters:~ + {obj} Object to return. + + Return:~ + its argument. + +nvim__id_array({arr}) *nvim__id_array()* + Returns array given as argument + + This API function is used for testing. One should not rely on + its presence in plugins. + + Parameters:~ + {arr} Array to return. + + Return:~ + its argument. + +nvim__id_dictionary({dct}) *nvim__id_dictionary()* + Returns dictionary given as argument + + This API function is used for testing. One should not rely on + its presence in plugins. + + Parameters:~ + {dct} Dictionary to return. + + Return:~ + its argument. + +nvim__id_float({flt}) *nvim__id_float()* + Returns floating-point value given as argument + + This API function is used for testing. One should not rely on + its presence in plugins. + + Parameters:~ + {flt} Value to return. + + Return:~ + its argument. + ============================================================================== Buffer Functions *api-buffer* @@ -457,6 +603,18 @@ nvim_buf_get_changedtick({buffer}) *nvim_buf_get_changedtick()* Return:~ b:changedtickvalue. +nvim_buf_get_keymap({buffer}, {mode}) *nvim_buf_get_keymap()* + Gets a list of dictionaries describing buffer-local mappings. + The "buffer" key in the returned dictionary reflects the + buffer handle where the mapping is present. + + Parameters:~ + {mode} Mode short-name ("n", "i", "v", ...) + {buffer} Buffer handle + + Return:~ + Array of maparg()-like dictionaries describing mappings + nvim_buf_set_var({buffer}, {name}, {value}) *nvim_buf_set_var()* Sets a buffer-scoped (b:) variable @@ -491,15 +649,6 @@ nvim_buf_set_option({buffer}, {name}, {value}) *nvim_buf_set_option()* {name} Option name {value} Option value -nvim_buf_get_number({buffer}) *nvim_buf_get_number()* - Gets the buffer number - - Parameters:~ - {buffer} Buffer handle - - Return:~ - Buffer number - nvim_buf_get_name({buffer}) *nvim_buf_get_name()* Gets the full file name for the buffer @@ -541,24 +690,24 @@ nvim_buf_add_highlight({buffer}, {src_id}, {hl_group}, {line}, {col_start}, {col_end}) Adds a highlight to buffer. - This can be used for plugins which dynamically generate - highlights to a buffer (like a semantic highlighter or - linter). The function adds a single highlight to a buffer. - Unlike matchaddpos() highlights follow changes to line - numbering (as lines are inserted/removed above the highlighted - line), like signs and marks do. - - "src_id" is useful for batch deletion/updating of a set of - highlights. When called with src_id = 0, an unique source id - is generated and returned. Succesive calls can pass in it as - "src_id" to add new highlights to the same source group. All - highlights in the same group can then be cleared with - nvim_buf_clear_highlight. If the highlight never will be - manually deleted pass in -1 for "src_id". - - If "hl_group" is the empty string no highlight is added, but a - new src_id is still returned. This is useful for an external - plugin to synchrounously request an unique src_id at + Useful for plugins that dynamically generate highlights to a + buffer (like a semantic highlighter or linter). The function + adds a single highlight to a buffer. Unlike matchaddpos() + highlights follow changes to line numbering (as lines are + inserted/removed above the highlighted line), like signs and + marks do. + + `src_id` is useful for batch deletion/updating of a set of + highlights. When called with `src_id = 0`, an unique source id + is generated and returned. Successive calls can pass that + `src_id` to associate new highlights with the same source + group. All highlights in the same group can be cleared with + `nvim_buf_clear_highlight`. If the highlight never will be + manually deleted, pass `src_id = -1`. + + If `hl_group` is the empty string no highlight is added, but a + new `src_id` is still returned. This is useful for an external + plugin to synchrounously request an unique `src_id` at initialization, and later asynchronously add and clear highlights in response to buffer changes. @@ -567,7 +716,7 @@ nvim_buf_add_highlight({buffer}, {src_id}, {hl_group}, {line}, {src_id} Source group to use or 0 to use a new group, or -1 for ungrouped highlight {hl_group} Name of the highlight group to use - {line} Line to highlight + {line} Line to highlight (zero-indexed) {col_start} Start of range of columns to highlight {col_end} End of range of columns to highlight, or -1 to highlight to end of line @@ -819,4 +968,4 @@ nvim_ui_try_resize({width}, {height}) *nvim_ui_try_resize()* nvim_ui_set_option({name}, {value}) *nvim_ui_set_option()* TODO: Documentation - vim:tw=78:ts=8:ft=help:norl: + vim:tw=78:ts=8:ft=help:norl:
\ No newline at end of file diff --git a/runtime/doc/arabic.txt b/runtime/doc/arabic.txt index 6f17b38a7a..07350083c6 100644 --- a/runtime/doc/arabic.txt +++ b/runtime/doc/arabic.txt @@ -1,4 +1,4 @@ -*arabic.txt* For Vim version 7.4. Last change: 2010 Nov 13 +*arabic.txt* Nvim VIM REFERENCE MANUAL by Nadim Shaikli @@ -36,7 +36,7 @@ the user interface remains the standard Vi interface. Highlights ---------- -o Editing left-to-right files as in the original VIM hasn't changed. +o Editing left-to-right files as in the original Vim hasn't changed. o Viewing and editing files in right-to-left windows. File orientation is per window, so it is possible to view the same @@ -46,7 +46,7 @@ o No special terminal with right-to-left capabilities is required. The right-to-left changes are completely hardware independent. Only Arabic fonts are necessary. -o Compatible with the original VIM. Almost all features work in +o Compatible with the original Vim. Almost all features work in right-to-left mode (there are liable to be bugs). o Changing keyboard mapping and reverse insert modes using a single @@ -60,14 +60,14 @@ o While in Arabic mode, numbers are entered from left to right. Upon o Arabic keymapping on the command line in reverse insert mode. -o Proper Bidirectional functionality is possible given VIM is +o Proper Bidirectional functionality is possible given Vim is started within a Bidi capable terminal emulator. Arabic Fonts *arabicfonts* ------------ -VIM requires monospaced fonts of which there are many out there. +Vim requires monospaced fonts of which there are many out there. Arabic requires ISO-8859-6 as well as Presentation Form-B fonts (without Form-B, Arabic will _NOT_ be usable). It is highly recommended that users search for so-called 'ISO-10646-1' fonts. @@ -90,13 +90,13 @@ o Installation of fonts for X Window systems (Unix/Linux) Usage ----- -Prior to the actual usage of Arabic within VIM, a number of settings +Prior to the actual usage of Arabic within Vim, a number of settings need to be accounted for and invoked. o Setting the Arabic fonts - + For VIM GUI set the 'guifont' to your_ARABIC_FONT. This is done - by entering the following command in the VIM window. + + For Vim GUI set the 'guifont' to your_ARABIC_FONT. This is done + by entering the following command in the Vim window. > :set guifont=your_ARABIC_FONT < @@ -109,7 +109,7 @@ o Setting the Arabic fonts you can include ':set guifont=your_ARABIC_FONT' to your vimrc file. - + Under the X Window environment, you can also start VIM with + + Under the X Window environment, you can also start Vim with '-fn your_ARABIC_FONT' option. o Setting the appropriate character Encoding @@ -131,11 +131,11 @@ o Setting the appropriate character Encoding o Enable Arabic settings [short-cut] In order to simplify and streamline things, you can either invoke - VIM with the command-line option, + Vim with the command-line option, % vim -A my_utf8_arabic_file ... - or enable 'arabic' via the following command within VIM + or enable 'arabic' via the following command within Vim > :set arabic < @@ -196,7 +196,7 @@ o Enable Arabic settings [short-cut] + Arabic deletion of a combined pair character - By default VIM has the 'delcombine' option disabled. This option + By default Vim has the 'delcombine' option disabled. This option allows the deletion of ALEF in a LAM_ALEF (LAA) combined character and still retain the LAM (i.e. it reverts to treating the combined character as its natural two characters form -- this also pertains @@ -255,7 +255,7 @@ o Enable Arabic settings [short-cut] Keymap/Keyboard *arabickeymap* --------------- -The character/letter encoding used in VIM is the standard UTF-8. +The character/letter encoding used in Vim is the standard UTF-8. It is widely discouraged that any other encoding be used or even attempted. @@ -288,7 +288,7 @@ o Keyboard Restrictions ------------ -o VIM in its GUI form does not currently support Bi-directionality +o Vim in its GUI form does not currently support Bi-directionality (i.e. the ability to see both Arabic and Latin intermixed within the same line). diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index 180127cd52..740f44414a 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -1,4 +1,4 @@ -*autocmd.txt* For Vim version 7.4. Last change: 2016 Jun 09 +*autocmd.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -8,17 +8,7 @@ Automatic commands *autocommand* For a basic explanation, see section |40.3| in the user manual. -1. Introduction |autocmd-intro| -2. Defining autocommands |autocmd-define| -3. Removing autocommands |autocmd-remove| -4. Listing autocommands |autocmd-list| -5. Events |autocmd-events| -6. Patterns |autocmd-patterns| -7. Buffer-local autocommands |autocmd-buflocal| -8. Groups |autocmd-groups| -9. Executing autocommands |autocmd-execute| -10. Using autocommands |autocmd-use| -11. Disabling autocommands |autocmd-disable| + Type |gO| to see the table of contents. ============================================================================== 1. Introduction *autocmd-intro* @@ -30,7 +20,7 @@ files matching *.c. You can also use autocommands to implement advanced features, such as editing compressed files (see |gzip-example|). The usual place to put autocommands is in your vimrc file. - *E203* *E204* *E143* *E855* + *E203* *E204* *E143* *E855* *E937* WARNING: Using autocommands is very powerful, and may lead to unexpected side effects. Be careful not to destroy your text. - It's a good idea to do some testing on an expendable copy of a file first. @@ -65,7 +55,14 @@ Note: The ":autocmd" command can only be followed by another command when the '|' appears before {cmd}. This works: > :augroup mine | au! BufRead | augroup END But this sees "augroup" as part of the defined command: > + :augroup mine | au! BufRead * | augroup END :augroup mine | au BufRead * set tw=70 | augroup END +Instead you can put the group name into the command: > + :au! mine BufRead * + :au mine BufRead * set tw=70 +Or use `:execute`: > + :augroup mine | exe "au! BufRead *" | augroup END + :augroup mine | exe "au BufRead * set tw=70" | augroup END Note that special characters (e.g., "%", "<cword>") in the ":autocmd" arguments are not expanded when the autocommand is defined. These will be @@ -76,11 +73,15 @@ exception is that "<sfile>" is expanded when the autocmd is defined. Example: Here Vim expands <sfile> to the name of the file containing this line. -When your vimrc file is sourced twice, the autocommands will appear twice. -To avoid this, put this command in your vimrc file, before defining -autocommands: > +`:autocmd` adds to the list of autocommands regardless of whether they are +already present. When your .vimrc file is sourced twice, the autocommands +will appear twice. To avoid this, define your autocommands in a group, so +that you can easily clear them: > - :autocmd! " Remove ALL autocommands for the current group. + augroup vimrc + autocmd! " Remove all vimrc autocommands + au BufNewFile,BufRead *.html so <sfile>:h/html.vim + augroup END If you don't want to remove all autocommands, you can instead use a variable to ensure that Vim includes the autocommands only once: > @@ -127,8 +128,13 @@ prompt. When one command outputs two messages this can happen anyway. :au[tocmd]! [group] {event} Remove ALL autocommands for {event}. + Warning: You should not do this without a group for + |BufRead| and other common events, it can break + plugins, syntax highlighting, etc. :au[tocmd]! [group] Remove ALL autocommands. + Warning: You should normally not do this without a + group, it breaks plugins, syntax highlighting, etc. When the [group] argument is not given, Vim uses the current group (as defined with ":augroup"); otherwise, Vim uses the group defined with [group]. @@ -304,6 +310,8 @@ Name triggered by ~ |TabNew| when creating a new tab page |TabNewEntered| after entering a new tab page |TabClosed| after closing a tab page +|CmdlineEnter| after entering cmdline mode +|CmdlineLeave| before leaving cmdline mode |CmdwinEnter| after entering the command-line window |CmdwinLeave| before leaving the command-line window @@ -422,8 +430,8 @@ BufUnload Before unloading a buffer. This is when the NOTE: When this autocommand is executed, the current buffer "%" may be different from the buffer being unloaded "<afile>". - Don't change to another buffer, it will cause - problems. + Don't change to another buffer or window, it + will cause problems! When exiting and v:dying is 2 or more this event is not triggered. *BufWinEnter* @@ -486,6 +494,28 @@ CmdUndefined When a user command is used but it isn't command is defined. An alternative is to always define the user command and have it invoke an autoloaded function. See |autoload|. + *CmdlineEnter* +CmdlineEnter After moving the cursor to the command line, + where the user can type a command or search + string. + <afile> is set to a single character, + indicating the type of command-line. + |cmdline-char| + Sets these |v:event| keys: + cmdlevel + cmdtype + *CmdlineLeave* +CmdlineLeave Before leaving the command line. + <afile> is set to a single character, + indicating the type of command-line. + |cmdline-char| + Sets these |v:event| keys: + abort (mutable) + cmdlevel + cmdtype + Note: `abort` can only be changed from false + to true. An autocmd cannot execute an already + aborted cmdline by changing it to false. *CmdwinEnter* CmdwinEnter After entering the command-line window. Useful for setting options specifically for @@ -606,7 +636,7 @@ FileChangedShell When Vim notices that the modification time of |timestamp| Mostly triggered after executing a shell command, but also with a |:checktime| command - or when Gvim regains input focus. + or when gvim regains input focus. This autocommand is triggered for each changed file. It is not used when 'autoread' is set and the buffer was not changed. If a @@ -617,7 +647,7 @@ FileChangedShell When Vim notices that the modification time of to tell Vim what to do next. NOTE: When this autocommand is executed, the current buffer "%" may be different from the - buffer that was changed "<afile>". + buffer that was changed, which is in "<afile>". NOTE: The commands must not change the current buffer, jump to another buffer or delete a buffer. *E246* *E811* @@ -644,7 +674,8 @@ FileType When the 'filetype' option has been set. The pattern is matched against the filetype. <afile> can be used for the name of the file where this option was set, and <amatch> for - the new value of 'filetype'. + the new value of 'filetype'. Navigating to + another window or buffer is not allowed. See |filetypes|. *FileWriteCmd* FileWriteCmd Before writing to a file, when not writing the @@ -794,7 +825,9 @@ QuickFixCmdPre Before a quickfix command is run (|:make|, |:vimgrepadd|, |:lvimgrepadd|, |:cscope|, |:cfile|, |:cgetfile|, |:caddfile|, |:lfile|, |:lgetfile|, |:laddfile|, |:helpgrep|, - |:lhelpgrep|). + |:lhelpgrep|, |:cexpr|, |:cgetexpr|, + |:caddexpr|, |:cbuffer|, |:cgetbuffer|, + |:caddbuffer|). The pattern is matched against the command being run. When |:grep| is used but 'grepprg' is set to "internal" it still matches "grep". @@ -919,7 +952,7 @@ TermClose When a terminal buffer ends. {Nvim} *TermOpen* TermOpen When a terminal buffer is starting. This can be used to configure the terminal emulator by - setting buffer variables. |terminal-emulator| + setting buffer variables. |terminal| *TermResponse* TermResponse After the response to |t_RV| is received from the terminal. The value of |v:termresponse| @@ -966,9 +999,9 @@ VimEnter After doing all the startup stuff, including VimLeave Before exiting Vim, just after writing the .shada file. Executed only once, like VimLeavePre. - To detect an abnormal exit use |v:dying|. - When v:dying is 2 or more this event is not - triggered. +< Use |v:dying| to detect an abnormal exit. + Use |v:exiting| to get the exit code. + Not triggered if |v:dying| is 2 or more. *VimLeavePre* VimLeavePre Before exiting Vim, just before writing the .shada file. This is executed only once, @@ -976,9 +1009,9 @@ VimLeavePre Before exiting Vim, just before writing the happens to be the current buffer when exiting. Mostly useful with a "*" pattern. > :autocmd VimLeavePre * call CleanupStuff() -< To detect an abnormal exit use |v:dying|. - When v:dying is 2 or more this event is not - triggered. +< Use |v:dying| to detect an abnormal exit. + Use |v:exiting| to get the exit code. + Not triggered if |v:dying| is 2 or more. *VimResized* VimResized After the Vim window was resized, thus 'lines' and/or 'columns' changed. Not when starting @@ -1002,7 +1035,7 @@ WinLeave Before leaving a window. If the window to be *WinNew* WinNew When a new window was created. Not done for - the fist window, when Vim has just started. + the first window, when Vim has just started. Before a WinEnter event. ============================================================================== @@ -1086,6 +1119,9 @@ Note that for all systems the '/' character is used for path separator (even Windows). This was done because the backslash is difficult to use in a pattern and to make the autocommands portable across different systems. +It is possible to use |pattern| items, but they may not work as expected, +because of the translation done for the above. + *autocmd-changes* Matching with the pattern is done when an event is triggered. Changing the buffer name in one of the autocommands, or even deleting the buffer, does not @@ -1184,10 +1220,12 @@ name! different from existing {event} names, as this most likely will not do what you intended. - *:augroup-delete* *E367* + *:augroup-delete* *E367* *W19* *E936* :aug[roup]! {name} Delete the autocmd group {name}. Don't use this if there is still an autocommand using - this group! This is not checked. + this group! You will get a warning if doing + it anyway. when the group is the current group + you will get error E936. To enter autocommands for a specific group, use this method: 1. Select the group with ":augroup {name}". diff --git a/runtime/doc/change.txt b/runtime/doc/change.txt index 31a46f53bb..9610d7359f 100644 --- a/runtime/doc/change.txt +++ b/runtime/doc/change.txt @@ -1,4 +1,4 @@ -*change.txt* For Vim version 7.4. Last change: 2016 Apr 12 +*change.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -9,20 +9,10 @@ changing text means deleting the text and replacing it with other text using one command. You can undo all of these commands. You can repeat the non-Ex commands with the "." command. -1. Deleting text |deleting| -2. Delete and insert |delete-insert| -3. Simple changes |simple-change| *changing* -4. Complex changes |complex-change| - 4.1 Filter commands |filter| - 4.2 Substitute |:substitute| - 4.3 Search and replace |search-replace| - 4.4 Changing tabs |change-tabs| -5. Copying and moving text |copy-move| -6. Formatting text |formatting| -7. Sorting text |sorting| - For inserting text see |insert.txt|. + Type |gO| to see the table of contents. + ============================================================================== 1. Deleting text *deleting* *E470* @@ -259,7 +249,7 @@ Or use "caw" (see |aw|). command is executed. ============================================================================== -3. Simple changes *simple-change* +3. Simple changes *simple-change* *changing* *r* r{char} Replace the character under the cursor with {char}. @@ -398,11 +388,6 @@ CTRL-X Subtract [count] from the number or alphabetic {Visual}CTRL-X Subtract [count] from the number or alphabetic character in the highlighted text. {not in Vi} - On MS-Windows, this is mapped to cut Visual text - |dos-standard-mappings|. If you want to disable the - mapping, use this: > - silent! vunmap <C-X> -< *v_g_CTRL-X* {Visual}g CTRL-X Subtract [count] from the number or alphabetic character in the highlighted text. If several lines @@ -601,8 +586,8 @@ all files in it are deleted. When Vim has the setuid bit set this may cause problems, the temp file is owned by the setuid user but the filter command probably runs as the original user. Directory for temporary files is created in the first suitable directory of: -For Unix: $TMPDIR, /tmp, current-dir, $HOME. -For MS-Windows: $TMP, $TEMP, $USERPROFILE, current-dir. + Unix: $TMPDIR, /tmp, current-dir, $HOME. + Windows: $TMPDIR, $TMP, $TEMP, $USERPROFILE, current-dir. @@ -614,12 +599,14 @@ For MS-Windows: $TMP, $TEMP, $USERPROFILE, current-dir. For the {pattern} see |pattern|. {string} can be a literal string, or something special; see |sub-replace-special|. + *E939* When [range] and [count] are omitted, replace in the - current line only. - When [count] is given, replace in [count] lines, - starting with the last line in [range]. When [range] - is omitted start in the current line. - Also see |cmdline-ranges|. + current line only. When [count] is given, replace in + [count] lines, starting with the last line in [range]. + When [range] is omitted start in the current line. + [count] must be a positive number. Also see + |cmdline-ranges|. + See |:s_flags| for [flags]. :[range]s[ubstitute] [flags] [count] @@ -661,6 +648,7 @@ g& Synonym for `:%s//~/&` (repeat last substitute with *:s_flags* The flags that you can use for the substitute commands: + *:&&* [&] Must be the first one: Keep the flags from the previous substitute command. Examples: > :&& @@ -833,6 +821,7 @@ The numbering of "\1", "\2" etc. is done based on which "\(" comes first in the pattern (going left to right). When a parentheses group matches several times, the last one will be used for "\1", "\2", etc. Example: > :s/\(\(a[a-d] \)*\)/\2/ modifies "aa ab x" to "ab x" +The "\2" is for "\(a[a-d] \)". At first it matches "aa ", secondly "ab ". When using parentheses in combination with '|', like in \([ab]\)\|\([cd]\), either the first or second pattern in parentheses did not match, so either @@ -873,8 +862,7 @@ Exceptions: Substitute with an expression *sub-replace-expression* *sub-replace-\=* *s/\=* When the substitute string starts with "\=" the remainder is interpreted as an -expression. This does not work recursively: a |substitute()| function inside -the expression cannot use "\=" for the substitute string. +expression. The special meaning for characters as mentioned at |sub-replace-special| does not apply except for "<CR>". A <NL> character is used as a line break, you diff --git a/runtime/doc/channel.txt b/runtime/doc/channel.txt new file mode 100644 index 0000000000..c94c64eb84 --- /dev/null +++ b/runtime/doc/channel.txt @@ -0,0 +1,168 @@ +*channel.txt* Nvim + + + NVIM REFERENCE MANUAL by Thiago de Arruda + + +Nvim's facilities for async io *channel* + + Type <M-]> to see the table of contents. + +============================================================================== +1. Introduction *channel-intro* + +Channels are nvim's way of communicating with external processes. + +There are several ways to open a channel: + + 1. Through stdin/stdout when `nvim` is started with `--headless`, and a startup + script or --cmd command opens the stdio channel using |stdioopen()|. + + 2. Through stdin, stdout and stderr of a process spawned by |jobstart()|. + + 3. Through the PTY master end of a PTY opened with + `jobstart(..., {'pty': v:true})` or |termopen()|. + + 4. By connecting to a TCP/IP socket or named pipe with |sockconnect()|. + + 5. By another process connecting to a socket listened to by nvim. This only + supports RPC channels, see |rpc-connecting|. + +Channels support multiple modes or protocols. In the most basic +mode of operation, raw bytes are read and written to the channel. +The |rpc| protocol, based on the msgpack-rpc standard, enables nvim and the +process at the other end to send remote calls and events to each other. +Additionally, the builtin |terminal-emulator|, is implemented on top of PTY +channels. + +============================================================================== +2. Reading and writing raw bytes *channel-bytes* + +By default, channels opened by vimscript functions will operate with raw +bytes. Additionally, for a job channel using rpc, bytes can still be +read over its stderr. Similarily, only bytes can be written to nvim's own stderr. + + *channel-callback* *buffered* + *on_stdout* *on_stderr* *on_stdin* *on_data* +A callback function `on_{stream}` will be invoked with data read from the +channel. By default, the callback will be invoked immediately when data is +available, to facilitate interactive communication. The same callback will +then be invoked with empty data, to indicate that the stream reached EOF. +Alternatively the `{stream}_buffered` option can be set to invoke the callback +only when the underlying stream reaches EOF, and will then be passed in +complete output. This is helpful when only the complete output is useful, and +not partial data. Futhermore if `{stream}_buffered` is set but not a callback, +the data is saved in the options dict, with the stream name as key. + +- The arguments passed to the callback function are: + + 0: The channel id + 1: the raw data read from the channel, formatted as a |readfile()|-style + list. If EOF occured, a single empty string `['']` will be passed in. + Note that the items in this list do not directly correspond to actual + lines in the output. See |channel-lines| + 2: Stream name as a string, like `"stdout"`. This is to allow multiple + on_{event} handlers to be implemented by the same function. The available + events depend on how the channel was opened and in what mode/protocol. + + *channel-lines* + Note: + stream event handlers may receive partial (incomplete) lines. For a given + invocation of on_stdout etc, `a:data` is not guaranteed to end + with a newline. + - `abcdefg` may arrive as `['abc']`, `['defg']`. + - `abc\nefg` may arrive as `['abc', '']`, `['efg']` or `['abc']`, + `['','efg']`, or even `['ab']`, `['c','efg']`. + + If you only are interested in complete output when the process exits, + use buffered mode. Otherwise, an easy way to deal with this: + initialize a list as `['']`, then append to it as follows: > + let s:chunks = [''] + func! s:on_event(job_id, data, event) dict + let s:chunks[-1] .= a:data[0] + call extend(s:chunks, a:data[1:]) + endf +< + +Additionally, if the callbacks are Dictionary functions, |self| can be used to +refer to the options dictionary containing the callbacks. |Partial|s can also be +used as callbacks. + +Data can be sent to the channel using the |chansend()| function. Here is a +simple example, echoing some data through a cat-process: +> + function! s:OnEvent(id, data, event) dict + let str = join(a:data, "\n") + echomsg str + endfunction + let id = jobstart(['cat'], {'on_stdout': function('s:OnEvent') } ) + call chansend(id, "hello!") +< + +Here is a example of setting a buffer to the result of grep, but only after +all data has been processed: +> + function! s:OnEvent(id, data, event) dict + call nvim_buf_set_lines(2, 0, -1, v:true, a:data) + endfunction + let id = jobstart(['grep', '^[0-9]'], { 'on_stdout': function('s:OnEvent'), + \ 'stdout_buffered':v:true } ) + + call chansend(id, "stuff\n10 PRINT \"NVIM\"\nxx") + " no output is received, buffer is empty + + call chansend(id, "xx\n20 GOTO 10\nzz\n") + call chanclose(id, 'stdin') + " now buffer has result +< +For additional examples with jobs, see |job-control|. + + *channel-pty* +A special case is PTY channels opened by `jobstart(..., {'pty': v:true})` . +No preprocessing of ANSI escape sequences is done, these will be sent raw to +the callback. However, change of PTY size can be signaled to the slave using +|jobresize()|. See also |terminal-emulator|. + +============================================================================== +3. Communicating using msgpack-rpc *channel-rpc* + +When channels are opened with the `rpc` option set to true, the channel can be +used for remote method calls in both directions, see |msgpack-rpc|. Note that +rpc channels are implicitly trusted and the process at the other end can +invoke any |api| function! + +============================================================================== +4. Using the stdio channel *channel-stdio* + +When invoked normally, nvim will use stdin and stdout to interact with the +user over the terminal interface (TUI). However when invoked with +`--headless`, the TUI is not started and stdin and stdout can be used as a +channel. To open the stdio channel |stdioopen()| must be called during +|startup|, as there later will be no way of invoking a command. As a +convenience, the stdio channel will always have channel id 1. + +Here is an example: +> + func! OnEvent(id, data, event) + if a:data == [""] + quit + end + call chansend(a:id, map(a:data, {i,v -> toupper(v)})) + endfunc + + call stdioopen({'on_stdin': 'OnEvent'}) +< +Put this in `uppercase.vim` and invoke nvim with +> + nvim --headless --cmd "source uppercase.vim" +< + *--embed* +An common use case is another program embedding nvim and communicating with it +over rpc. Therefore, the option `--embed` exists as a shorthand for +`nvim --headless --cmd "call stdioopen({'rpc': v:true})"` + +Nvim's stderr is implicitly open as a write-only bytes channel. It will +always have channel id 2, however to be explicit |v:stderr| can be used. + +============================================================================== + vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/cmdline.txt b/runtime/doc/cmdline.txt index a123ea711b..00e654841c 100644 --- a/runtime/doc/cmdline.txt +++ b/runtime/doc/cmdline.txt @@ -1,4 +1,4 @@ -*cmdline.txt* For Vim version 7.4. Last change: 2015 Dec 17 +*cmdline.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -13,13 +13,7 @@ Command-line mode is used to enter Ex commands (":"), search patterns Basic command line editing is explained in chapter 20 of the user manual |usr_20.txt|. -1. Command-line editing |cmdline-editing| -2. Command-line completion |cmdline-completion| -3. Ex command-lines |cmdline-lines| -4. Ex command-line ranges |cmdline-ranges| -5. Ex command-line flags |ex-flags| -6. Ex special characters |cmdline-special| -7. Command-line window |cmdline-window| + Type |gO| to see the table of contents. ============================================================================== 1. Command-line editing *cmdline-editing* @@ -219,9 +213,10 @@ CTRL-Y When there is a modeless selection, copy the selection into the clipboard. |modeless-selection| If there is no selection CTRL-Y is inserted as a character. -CTRL-J *c_CTRL-J* *c_<NL>* *c_<CR>* *c_CR* +CTRL-M or CTRL-J *c_CTRL-M* *c_CTRL-J* *c_<NL>* *c_<CR>* *c_CR* <CR> or <NL> start entered command - *c_<Esc>* *c_Esc* + +CTRL-[ *c_CTRL-[* *c_<Esc>* *c_Esc* <Esc> When typed and 'x' not present in 'cpoptions', quit Command-line mode without executing. In macros or when 'x' present in 'cpoptions', start entered command. @@ -332,8 +327,11 @@ terminals) List entries 6 to 12 from the search history: > :history / 6,12 < - List the recent five entries from all histories: > - :history all -5, + List the penultimate entry from all histories: > + :history all -2 +< + List the most recent two entries from all histories: > + :history all -2, :keepp[atterns] {command} *:keepp* *:keeppatterns* Execute {command}, without adding anything to the search @@ -363,7 +361,7 @@ These are the commands that can be used: *c_CTRL-D* CTRL-D List names that match the pattern in front of the cursor. When showing file names, directories are highlighted (see - 'highlight' option). Names where 'suffixes' matches are moved + |highlight-groups|). Names where 'suffixes' matches are moved to the end. The 'wildoptions' option can be set to "tagfile" to list the file of matching tags. @@ -394,12 +392,26 @@ CTRL-L A match is done on the pattern in front of the cursor. If If there are multiple matches the longest common part is inserted in place of the pattern. If the result is shorter than the pattern, no completion is done. + */_CTRL-L* When 'incsearch' is set, entering a search pattern for "/" or "?" and the current match is displayed then CTRL-L will add one character from the end of the current match. If 'ignorecase' and 'smartcase' are set and the command line has no uppercase characters, the added character is converted to lowercase. + *c_CTRL-G* */_CTRL-G* +CTRL-G When 'incsearch' is set, entering a search pattern for "/" or + "?" and the current match is displayed then CTRL-G will move + to the next match (does not take |search-offset| into account) + Use CTRL-T to move to the previous match. Hint: on a regular + keyboard T is above G. + *c_CTRL-T* */_CTRL-T* +CTRL-T When 'incsearch' is set, entering a search pattern for "/" or + "?" and the current match is displayed then CTRL-T will move + to the previous match (does not take |search-offset| into + account). + Use CTRL-G to move to the next match. Hint: on a regular + keyboard T is above G. The 'wildchar' option defaults to <Tab> (CTRL-E when in Vi compatible mode; in a previous version <Esc> was used). In the pattern standard wildcards '*' and @@ -408,6 +420,9 @@ matches exactly one character. The 'wildignorecase' option can be set to ignore case in filenames. +The 'wildmenu' option can be set to show the matches just above the command +line. + If you like tcsh's autolist completion, you can use this mapping: :cnoremap X <C-L><C-D> (Where X is the command key to use, <C-L> is CTRL-L and <C-D> is CTRL-D) @@ -766,6 +781,7 @@ Also see |`=|. *:<cword>* *:<cWORD>* *:<cfile>* *<cfile>* *:<sfile>* *<sfile>* *:<afile>* *<afile>* *:<abuf>* *<abuf>* *:<amatch>* *<amatch>* + *:<cexpr>* *<cexpr>* *<slnum>* *E495* *E496* *E497* *E499* *E500* Note: these are typed literally, they are not special keys! <cword> is replaced with the word under the cursor (like |star|) @@ -773,7 +789,8 @@ Note: these are typed literally, they are not special keys! <cfile> is replaced with the path name under the cursor (like what |gf| uses) <afile> When executing autocommands, is replaced with the file name - for a file read or write. + of the buffer being manipulated, or the file for a read or + write. <abuf> When executing autocommands, is replaced with the currently effective buffer number (for ":r file" and ":so file" it is the current buffer, the file being read/sourced is not in a @@ -999,10 +1016,10 @@ There are several ways to leave the command-line window: Insert and in Normal mode. CTRL-C Continue in Command-line mode. The command-line under the cursor is used as the command-line. Works both in Insert and - in Normal mode. ":close" also works. There is no redraw, - thus the window will remain visible. + in Normal mode. There is no redraw, thus the window will + remain visible. :quit Discard the command line and go back to Normal mode. - ":exit", ":xit" and CTRL-\ CTRL-N also work. + ":close", ":exit", ":xit" and CTRL-\ CTRL-N also work. :qall Quit Vim, unless there are changes in some buffer. :qall! Quit Vim, discarding changes to any buffer. @@ -1071,7 +1088,7 @@ Another example: > :au CmdwinEnter [/?] startinsert This will make Vim start in Insert mode in the command-line window. - *cmdwin-char* + *cmdline-char* *cmdwin-char* The character used for the pattern indicates the type of command-line: : normal Ex command > debug mode command |debug-mode| diff --git a/runtime/doc/debug.txt b/runtime/doc/debug.txt index f03116ffed..422255fa02 100644 --- a/runtime/doc/debug.txt +++ b/runtime/doc/debug.txt @@ -1,4 +1,4 @@ -*debug.txt* For Vim version 7.4. Last change: 2012 Feb 11 +*debug.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -9,9 +9,7 @@ Debugging Vim *debug-vim* This is for debugging Vim itself, when it doesn't work properly. For debugging Vim scripts, functions, etc. see |debug-scripts| -1. Location of a crash, using gcc and gdb |debug-gcc| -2. Locating memory leaks |debug-leaks| -3. Windows Bug Reporting |debug-win32| + Type |gO| to see the table of contents. ============================================================================== diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt index ef00143709..72dfe1230e 100644 --- a/runtime/doc/deprecated.txt +++ b/runtime/doc/deprecated.txt @@ -1,4 +1,4 @@ -*deprecated.txt* {Nvim} +*deprecated.txt* Nvim NVIM REFERENCE MANUAL @@ -26,9 +26,6 @@ Events ~ *EncodingChanged* Never fired; 'encoding' is always "utf-8". *FileEncoding* Never fired; equivalent to |EncodingChanged|. -Highlight groups ~ -*hl-VisualNOS* Obsolete. |vim-differences| {Nvim} - Keycodes ~ *<MouseDown>* Use <ScrollWheelUp> instead. *<MouseUp>* Use <ScrollWheelDown> instead. @@ -40,11 +37,21 @@ Functions ~ *file_readable()* Obsolete name for |filereadable()|. *highlight_exists()* Obsolete name for |hlexists()|. *highlightID()* Obsolete name for |hlID()|. +*jobclose()* Obsolete name for |chanclose()| +*jobsend()* Obsolete name for |chansend()| *last_buffer_nr()* Obsolete name for bufnr("$"). +Modifiers ~ +*:menu-<special>* +*:menu-special* <> notation is always enabled. |cpo-<| +*:map-<special>* +*:map-special* <> notation is always enabled. |cpo-<| + Options ~ *'fe'* 'fenc'+'enc' before Vim 6.0; no longer used. +*'highlight'* *'hl'* Names of builtin |highlight-groups| cannot be changed. +*'langnoremap'* Deprecated alias to 'nolangremap'. *'vi'* *'viminfo'* Deprecated alias to 'shada' option. - vim:tw=78:ts=8:ft=help:norl: + vim:noet:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index b738da9bec..36826e2479 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -1,4 +1,4 @@ -*develop.txt* +*develop.txt* Nvim NVIM REFERENCE MANUAL @@ -6,22 +6,19 @@ Development of Nvim. *development* -1. Design goals |design-goals| -2. Design decisions |design-decisions| - Nvim is open source software. Everybody is encouraged to contribute. https://github.com/neovim/neovim/blob/master/CONTRIBUTING.md -See src/nvim/README.md for a high-level overview of the source code: - https://github.com/neovim/neovim/blob/master/src/nvim/README.md +See src/nvim/README.md for an overview of the source code. + + Type |gO| to see the table of contents. ============================================================================== -1. Design goals *design-goals* +Design goals *design-goals* Most important things come first (roughly). -Note that quite a few items are contradicting. This is intentional. A -balance must be found between them. +Note that some items conflict; this is intentional. A balance must be found. NVIM IS... IMPROVED *design-improved* @@ -41,7 +38,7 @@ completely different editor. Extensions are done with a "Vi spirit". - There are many first-time and inexperienced Vim users. Make it easy for them to start using Vim and learn more over time. - There is no limit to the features that can be added. Selecting new features - is one based on (1) what users ask for, (2) how much effort it takes to + is based on (1) what users ask for, (2) how much effort it takes to implement and (3) someone actually implementing it. @@ -56,33 +53,21 @@ Vim tries to help as many users on as many platforms as possible. - Support many compilers and libraries. Not everybody is able or allowed to install another compiler or GUI library. - People switch from one platform to another, and from GUI to terminal - version. Features should be present in all versions, or at least in as many - as possible with a reasonable effort. Try to avoid that users must switch - between platforms to accomplish their work efficiently. -- That a feature is not possible on some platforms, or only possible on one - platform, does not mean it cannot be implemented. [This intentionally - contradicts the previous item, these two must be balanced.] + version. Features should be present in all versions. NVIM IS... WELL DOCUMENTED *design-documented* - A feature that isn't documented is a useless feature. A patch for a new feature must include the documentation. -- Documentation should be comprehensive and understandable. Using examples is - recommended. +- Documentation should be comprehensive and understandable. Use examples. - Don't make the text unnecessarily long. Less documentation means that an item is easier to find. -- Do not prefix doc-tags with "nvim-". Use |vim_diff.txt| to document - differences from Vim. The {Nvim} annotation is also available - to mark a specific feature. No other distinction is necessary. -- If a feature is removed, delete its doc entry and move its tag to - |vim_diff.txt|. NVIM IS... HIGH SPEED AND SMALL IN SIZE *design-speed-size* -Using Vim must not be a big attack on system resources. Keep it small and -fast. +Keep Nvim small and fast. - Computers are becoming faster and bigger each year. Vim can grow too, but no faster than computers are growing. Keep Vim usable on older systems. - Many users start Vim from a shell very often. Startup time must be short. @@ -118,13 +103,14 @@ NVIM IS... NOT *design-not* Nvim is not an operating system; instead it should be composed with other tools or hosted as a component. Marvim once said: "Unlike Emacs, Nvim does not -include the kitchen sink... but you can use it for plumbing." +include the kitchen sink... but it's good for plumbing." ============================================================================== -2. Design decisions *design-decisions* +Developer guidelines *dev* -JARGON *dev-jargon* + +JARGON *dev-jargon* API client ~ All external UIs and remote plugins (as opposed to regular Vim plugins) are @@ -150,15 +136,16 @@ the xterm window, a window inside Vim to view a buffer. To avoid confusion, other items that are sometimes called window have been given another name. Here is an overview of the related items: -screen The whole display. For the GUI it's something like 1024x768 - pixels. The Vim shell can use the whole screen or part of it. +screen The whole display. shell The Vim application. This can cover the whole screen (e.g., when running in a console) or part of it (xterm or GUI). window View on a buffer. There can be several windows in Vim, together with the command line, menubar, toolbar, etc. they fit in the shell. +frame Windows are kept in a tree of frames. Each frame contains + a column, row, or window ("leaf" frame). -PROVIDERS *dev-provider* +PROVIDERS *dev-provider* A goal of Nvim is to allow extension of the editor without special knowledge in the core. But some Vim components are too tightly coupled; in those cases @@ -201,8 +188,20 @@ defined if a valid external Python host is found. That works well with the Python host isn't installed then the plugin will "think" it is running in a Vim compiled without the |+python| feature. +DOCUMENTATION *dev-doc* -API *dev-api* +- Do not prefix help tags with "nvim-". Use |vim_diff.txt| to document + differences from Vim; no other distinction is necessary. +- If a Vim feature is removed, delete its help section and move its tag to + |vim_diff.txt|. +- Move deprecated features to |deprecated.txt|. +- Use consistent language. + - "terminal" in a help tag always means "the embedded terminal emulator", not + "the user host terminal". + - Use "tui-" to prefix help tags related to the host terminal, and "TUI" + in prose if possible. + +API *dev-api* Use this pattern to name new API functions: nvim_{thing}_{action}_{arbitrary-qualifiers} @@ -233,4 +232,47 @@ _not_ a Buffer). The common {action} "list" indicates that it lists all bufs (plural) in the global context. +API-CLIENT *dev-api-client* + +Package Naming ~ +API client packages should NOT be named something ambiguous like "neovim" or +"python-client". Use "nvim" as a prefix/suffix to some other identifier +following ecosystem conventions. + +For example, Python packages tend to have "py" in the name, so "pynvim" is +a good name: it's idiomatic and unambiguous. If the package is named "neovim", +it confuses users, and complicates documentation and discussions. + +Examples of API-client package names: + GOOD: nvim-racket + GOOD: pynvim + BAD: python-client + BAD: neovim + +Implementation ~ +Consider using libmpack instead of the msgpack.org C/C++ library. libmpack is +small, efficient, and C89-compatible. It can be easily inlined in your +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. + +Common Features ~ +External UIs are expected to implement these common features: +- Cursor style (shape, color) should respond to the 'guicursor' properties + delivered with the mode_info_set UI event. +- Send the "super" key (Windows key, Apple key) as a |<D-| chord. + +Implementation ~ +- Options can be monitored for changes by the |OptionSet| autocmd. E.g. if the + user sets the 'guifont' option, this autocmd notifies channel 42: > + autocmd OptionSet guifont call rpcnotify(42, 'option-changed', 'guifont', &guifont) + + vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/diff.txt b/runtime/doc/diff.txt index 6b45f8552f..b9dccc42a8 100644 --- a/runtime/doc/diff.txt +++ b/runtime/doc/diff.txt @@ -1,4 +1,4 @@ -*diff.txt* For Vim version 7.4. Last change: 2016 Aug 24 +*diff.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -10,14 +10,10 @@ eight versions of the same file. The basics are explained in section |08.7| of the user manual. -1. Starting diff mode |diff-mode| -2. Viewing diffs |view-diffs| -3. Jumping to diffs |jumpto-diffs| -4. Copying diffs |copy-diffs| -5. Diff options |diff-options| + Type |gO| to see the table of contents. ============================================================================== -1. Starting diff mode +1. Starting diff mode *start-vimdiff* To start editing in diff mode, run "nvim -d". This starts Nvim as usual, and additionally sets up for viewing the differences between the arguments. > @@ -123,6 +119,8 @@ file for a moment and come back to the same file and be in diff mode again. related options only happens in a window that has 'diff' set, if the current window does not have 'diff' set then no options in it are changed. + Hidden buffers are also removed from the list of diff'ed + buffers. The `:diffoff` command resets the relevant options to the values they had when using `:diffsplit`, `:diffpatch` , `:diffthis`. or starting Vim in diff mode. @@ -156,7 +154,8 @@ The alignment of text will go wrong when: All the buffers edited in a window where the 'diff' option is set will join in the diff. This is also possible for hidden buffers. They must have been -edited in a window first for this to be possible. +edited in a window first for this to be possible. To get rid of the hidden +buffers use `:diffoff!`. *:DiffOrig* *diff-original-file* Since 'diff' is a window-local option, it's possible to view the same buffer @@ -215,8 +214,8 @@ The diffs are highlighted with these groups: (searching from the end of the line). The text in between is highlighted. This means that parts in the middle that are still the - same are highlighted anyway. Only "iwhite" of - 'diffopt' is used here. + same are highlighted anyway. The 'diffopt' + flags "iwhite" and "icase" are used here. |hl-DiffDelete| DiffDelete Deleted lines. Also called filler lines, because they don't really exist in this buffer. @@ -315,7 +314,7 @@ g:diff_translations to zero: > let g:diff_translations = 0 < -After setting this variable, Reload the syntax script: > +After setting this variable, reload the syntax script: > set syntax=diff < diff --git a/runtime/doc/digraph.txt b/runtime/doc/digraph.txt index 84024fd1b3..d3b03c6ef6 100644 --- a/runtime/doc/digraph.txt +++ b/runtime/doc/digraph.txt @@ -1,4 +1,4 @@ -*digraph.txt* For Vim version 7.4. Last change: 2014 Jun 19 +*digraph.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -14,9 +14,7 @@ with CTRL-V (see |i_CTRL-V|). There is a brief introduction on digraphs in the user manual: |24.9| An alternative is using the 'keymap' option. -1. Defining digraphs |digraphs-define| -2. Using digraphs |digraphs-use| -3. Default digraphs |digraphs-default| + Type |gO| to see the table of contents. ============================================================================== 1. Defining digraphs *digraphs-define* @@ -145,7 +143,7 @@ a standard meaning: Two 2 Hook Nine 9 Horn - Equals = Cyrillic (= used as second char) + Equals = Cyrillic (= used as second char) Asterisk * Greek Percent sign % Greek/Cyrillic special Plus + smalls: Arabic, capitals: Hebrew @@ -924,6 +922,7 @@ char digraph hex dec official name ~ † /- 2020 8224 DAGGER ‡ /= 2021 8225 DOUBLE DAGGER ‥ .. 2025 8229 TWO DOT LEADER +… ,. 2026 8230 HORIZONTAL ELLIPSIS ‰ %0 2030 8240 PER MILLE SIGN ′ 1' 2032 8242 PRIME ″ 2' 2033 8243 DOUBLE PRIME diff --git a/runtime/doc/editing.txt b/runtime/doc/editing.txt index 5bfffac1f1..1b9a1b38fb 100644 --- a/runtime/doc/editing.txt +++ b/runtime/doc/editing.txt @@ -1,4 +1,4 @@ -*editing.txt* For Vim version 7.4. Last change: 2016 Aug 06 +*editing.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -6,17 +6,7 @@ Editing files *edit-files* -1. Introduction |edit-intro| -2. Editing a file |edit-a-file| -3. The argument list |argument-list| -4. Writing |writing| -5. Writing and quitting |write-quit| -6. Dialogs |edit-dialogs| -7. The current directory |current-directory| -8. Editing binary files |edit-binary| -9. Encryption |encryption| -10. Timestamps |timestamps| -11. File Searching |file-searching| + Type |gO| to see the table of contents. ============================================================================== 1. Introduction *edit-intro* @@ -160,7 +150,8 @@ start editing another file, Vim will refuse this. In order to overrule this protection, add a '!' to the command. The changes will then be lost. For example: ":q" will not work if the buffer was changed, but ":q!" will. To see whether the buffer was changed use the "CTRL-G" command. The message includes -the string "[Modified]" if the buffer has been changed. +the string "[Modified]" if the buffer has been changed, or "+" if the 'm' flag +is in 'shortmess'. If you want to automatically save the changes without asking, switch on the 'autowriteall' option. 'autowrite' is the associated Vi-compatible option @@ -245,7 +236,7 @@ If you want to keep the changed buffer without saving it, switch on the *:vie* *:view* :vie[w][!] [++opt] [+cmd] file - When used in Ex mode: Leave |Ex mode|, go back to + When used in Ex mode: Leave |Ex-mode|, go back to Normal mode. Otherwise same as |:edit|, but set 'readonly' option for this buffer. @@ -910,11 +901,12 @@ WRITING WITH MULTIPLE BUFFERS *buffer-write* *:wa* *:wall* :wa[ll] Write all changed buffers. Buffers without a file - name or which are readonly are not written. + name cause an error message. Buffers which are + readonly are not written. :wa[ll]! Write all changed buffers, even the ones that are readonly. Buffers without a file name are not - written. + written and cause an error message. Vim will warn you if you try to overwrite a file that has been changed @@ -1040,6 +1032,7 @@ The names can be in upper- or lowercase. window in the current tab page the current tab page is closed |tab-page|. Triggers the |QuitPre| autocommand event. + See |CTRL-W_q| for quitting another window. :conf[irm] q[uit] Quit, but give prompt when changes have been made, or the last file in the argument list has not been @@ -1273,14 +1266,14 @@ Commands for changing the working directory can be suffixed with a bang "!" *:lc* *:lcd* :lc[d][!] {path} Like |:cd|, but only set the current directory for the current window. The current directory for other - windows or any tabs is not changed. + windows or tabs is not changed. *:lch* *:lchdir* :lch[dir][!] Same as |:lcd|. *:lcd-* :lcd[!] - Change to the previous current directory (before the - previous ":tcd {path}" command). + previous ":lcd {path}" command). *:pw* *:pwd* *E187* :pw[d] Print the current directory name. @@ -1372,6 +1365,13 @@ If you want to automatically reload a file when it has been changed outside of Vim, set the 'autoread' option. This doesn't work at the moment you write the file though, only when the file wasn't changed inside of Vim. +If you do not want to be asked or automatically reload the file, you can use +this: > + set buftype=nofile + +Or, when starting gvim from a shell: > + gvim file.log -c "set buftype=nofile" + Note that if a FileChangedShell autocommand is defined you will not get a warning message or prompt. The autocommand is expected to handle this. @@ -1542,7 +1542,7 @@ There are three different types of searching: This searches the same directories, but in a different order. Note that completion for ":find", ":sfind", and ":tabfind" commands do not - currently work with 'path' items that contain a url or use the double star + currently work with 'path' items that contain a URL or use the double star with depth limiter (/usr/**2) or upward search (;) notations. vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index d94b3b7a2e..d2a3a962e6 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -1,4 +1,4 @@ -*eval.txt* For Vim version 7.4. Last change: 2016 Aug 27 +*eval.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -12,23 +12,7 @@ Note: Expression evaluation can be disabled at compile time. If this has been done, the features in this document are not available. See |+eval| and |no-eval-feature|. -1. Variables |variables| - 1.1 Variable types - 1.2 Function references |Funcref| - 1.3 Lists |Lists| - 1.4 Dictionaries |Dictionaries| - 1.5 More about variables |more-variables| -2. Expression syntax |expression-syntax| -3. Internal variable |internal-variables| -4. Builtin Functions |functions| -5. Defining functions |user-functions| -6. Curly braces names |curly-braces-names| -7. Commands |expression-commands| -8. Exception handling |exception-handling| -9. Examples |eval-examples| -10. No +eval feature |no-eval-feature| -11. The sandbox |eval-sandbox| -12. Textlock |textlock| + Type |gO| to see the table of contents. ============================================================================== 1. Variables *variables* @@ -38,7 +22,9 @@ done, the features in this document are not available. See |+eval| and There are six types of variables: Number A 32 or 64 bit signed number. |expr-number| *Number* - Examples: -123 0x10 0177 + 64-bit Number is available only when compiled with the + |+num64| feature. + Examples: -123 0x10 0177 0b1011 Float A floating point number. |floating-point-format| *Float* Examples: 123.456 1.15e-6 -1.1e3 @@ -107,10 +93,9 @@ To test for a non-empty string, use empty(): > *non-zero-arg* Function arguments often behave slightly different from |TRUE|: If the argument is present and it evaluates to a non-zero Number, |v:true| or a -non-empty String, then the value is considere to be TRUE. -Note that " " and "0" are also non-empty strings, thus cause the mode to be -cleared. A List, Dictionary or Float is not a Number or String, thus -evaluates to FALSE. +non-empty String, then the value is considered to be TRUE. +Note that " " and "0" are also non-empty strings, thus considered to be TRUE. +A List, Dictionary or Float is not a Number or String, thus evaluate to FALSE. *E745* *E728* *E703* *E729* *E730* *E731* List, Dictionary and Funcref types are not automatically converted. @@ -247,7 +232,7 @@ it. To change a list in-place see |list-modification| below. Sublist ~ - + *sublist* A part of the List can be obtained by specifying the first and last index, separated by a colon in square brackets: > :let shortlist = mylist[2:-1] " get List [3, "four"] @@ -394,10 +379,6 @@ This works like: > : let index = index + 1 :endwhile -Note that all items in the list should be of the same type, otherwise this -results in error |E706|. To avoid this |:unlet| the variable at the end of -the loop. - If all you want to do is modify each item in the list then the |map()| function will be a simpler method than a for loop. @@ -631,13 +612,17 @@ It's possible to form a variable name with curly braces, see Expression syntax summary, from least to most significant: -|expr1| expr2 ? expr1 : expr1 if-then-else +|expr1| expr2 + expr2 ? expr1 : expr1 if-then-else -|expr2| expr3 || expr3 .. logical OR +|expr2| expr3 + expr3 || expr3 .. logical OR -|expr3| expr4 && expr4 .. logical AND +|expr3| expr4 + expr4 && expr4 .. logical AND -|expr4| expr5 == expr5 equal +|expr4| expr5 + expr5 == expr5 equal expr5 != expr5 not equal expr5 > expr5 greater than expr5 >= expr5 greater than or equal @@ -654,24 +639,28 @@ Expression syntax summary, from least to most significant: expr5 is expr5 same |List| instance expr5 isnot expr5 different |List| instance -|expr5| expr6 + expr6 .. number addition or list concatenation +|expr5| expr6 + expr6 + expr6 .. number addition or list concatenation expr6 - expr6 .. number subtraction expr6 . expr6 .. string concatenation -|expr6| expr7 * expr7 .. number multiplication +|expr6| expr7 + expr7 * expr7 .. number multiplication expr7 / expr7 .. number division expr7 % expr7 .. number modulo -|expr7| ! expr7 logical NOT +|expr7| expr8 + ! expr7 logical NOT - expr7 unary minus + expr7 unary plus -|expr8| expr8[expr1] byte of a String or item of a |List| +|expr8| expr9 + expr8[expr1] byte of a String or item of a |List| expr8[expr1 : expr1] substring of a String or sublist of a |List| expr8.name entry in a |Dictionary| expr8(expr1, ...) function call with |Funcref| variable -|expr9| number number constant +|expr9| number number constant "string" string constant, backslash is special 'string' string constant, ' is doubled [expr1, ...] |List| @@ -792,14 +781,15 @@ Examples: "abc" == "Abc" evaluates to 1 if 'ignorecase' is set, 0 otherwise *E691* *E692* -A |List| can only be compared with a |List| and only "equal", "not equal" and -"is" can be used. This compares the values of the list, recursively. -Ignoring case means case is ignored when comparing item values. +A |List| can only be compared with a |List| and only "equal", "not equal", +"is" and "isnot" can be used. This compares the values of the list, +recursively. Ignoring case means case is ignored when comparing item values. *E735* *E736* A |Dictionary| can only be compared with a |Dictionary| and only "equal", "not -equal" and "is" can be used. This compares the key/values of the |Dictionary| -recursively. Ignoring case means case is ignored when comparing item values. +equal", "is" and "isnot" can be used. This compares the key/values of the +|Dictionary| recursively. Ignoring case means case is ignored when comparing +item values. *E694* A |Funcref| can only be compared with a |Funcref| and only "equal", "not @@ -899,6 +889,11 @@ When dividing a Number by zero the result depends on the value: <0 / 0 = -0x7fffffff (like negative infinity) (before Vim 7.2 it was always 0x7fffffff) +When 64-bit Number support is enabled: + 0 / 0 = -0x8000000000000000 (like NaN for Float) + >0 / 0 = 0x7fffffffffffffff (like positive infinity) + <0 / 0 = -0x7fffffffffffffff (like negative infinity) + When the righthand side of '%' is zero, the result is 0. None of these work for |Funcref|s. @@ -931,7 +926,7 @@ expr8[expr1] item of String or |List| *expr-[]* *E111* If expr8 is a Number or String this results in a String that contains the expr1'th single byte from expr8. expr8 is used as a String, expr1 as a -Number. This doesn't recognize multi-byte encodings, see |byteidx()| for +Number. This doesn't recognize multi-byte encodings, see `byteidx()` for an alternative, or use `split()` to turn the string into a list of characters. Index zero gives the first byte. This is like it works in C. Careful: @@ -975,10 +970,10 @@ Examples: > :let s = line(".")[4:] " from the fifth byte to the end :let s = s[:-3] " remove last two bytes < - *sublist* *slice* + *slice* If expr8 is a |List| this results in a new |List| with the items indicated by the indexes expr1a and expr1b. This works like with a String, as explained -just above, except that indexes out of range cause an error. Examples: > +just above. Also see |sublist| below. Examples: > :let l = mylist[:3] " first four items :let l = mylist[4:4] " List with one item :let l = mylist[:] " shallow copy of a List @@ -1021,10 +1016,11 @@ When expr8 is a |Funcref| type variable, invoke the function it refers to. *expr9* number ------ -number number constant *expr-number* - *hex-number* *octal-number* +number number constant *expr-number* + *hex-number* *octal-number* *binary-number* -Decimal, Hexadecimal (starting with 0x or 0X), or Octal (starting with 0). +Decimal, Hexadecimal (starting with 0x or 0X), Binary (starting with 0b or 0B) +and Octal (starting with 0). *floating-point-format* Floating point numbers can be written in two forms: @@ -1213,8 +1209,8 @@ The arguments are optional. Example: > < error function *closure* Lambda expressions can access outer scope variables and arguments. This is -often called a closure. Example where "i" a and "a:arg" are used in a lambda -while they exists in the function scope. They remain valid even after the +often called a closure. Example where "i" and "a:arg" are used in a lambda +while they exist in the function scope. They remain valid even after the function returns: > :function Foo(arg) : let i = 3 @@ -1232,7 +1228,7 @@ Examples for using a lambda expression with |sort()|, |map()| and |filter()|: > :echo sort([3,7,2,1,4], {a, b -> a - b}) < [1, 2, 3, 4, 7] -The lambda expression is also useful for Channel, Job and timer: > +The lambda expression is also useful for jobs and timers: > :let timer = timer_start(500, \ {-> execute("echo 'Handler called'", "")}, \ {'repeat': 3}) @@ -1296,7 +1292,8 @@ b:changedtick The total number of changes to the current buffer. It is : let my_changedtick = b:changedtick : call My_Update() :endif -< +< You cannot change or delete the b:changedtick variable. + *window-variable* *w:var* *w:* A variable name that is preceded with "w:" is local to the current window. It is deleted when the window is closed. @@ -1425,8 +1422,8 @@ v:beval_winnr The number of the window, over which the mouse pointer is. Only window gets a number). *v:beval_winid* *beval_winid-variable* -v:beval_winid The window ID of the window, over which the mouse pointer is. - Otherwise like v:beval_winnr. +v:beval_winid The |window-ID| of the window, over which the mouse pointer + is. Otherwise like v:beval_winnr. *v:char* *char-variable* v:char Argument for evaluating 'formatexpr' and used for the typed @@ -1477,7 +1474,6 @@ v:count The count given for the last Normal mode command. Can be used When there are two counts, as in "3d2w", they are multiplied, just like what happens in the command, "d6w" for the example. Also used for evaluating the 'formatexpr' option. - "count" also works, for backwards compatibility. *v:count1* *count1-variable* v:count1 Just like "v:count", but defaults to one when no count is @@ -1524,16 +1520,28 @@ v:errors Errors found by assert functions, such as |assert_true()|. list by the assert function. *v:event* *event-variable* -v:event Dictionary of event data for the current |autocommand|. The - available keys differ per event type and are specified at the - documentation for each |event|. The possible keys are: - operator The operation performed. Unlike - |v:operator|, it is set also for an Ex - mode command. For instance, |:yank| is - translated to "|y|". +v:event Dictionary of event data for the current |autocommand|. Valid + only during the event lifetime; storing or passing v:event is + invalid! Copy it instead: > + au TextYankPost * let g:foo = deepcopy(v:event) +< Keys vary by event; see the documentation for the specific + event, e.g. |DirChanged| or |TextYankPost|. + KEY DESCRIPTION ~ + abort Whether the event triggered during + an aborting condition, i e |c_Esc| or + |c_CTRL-c|for |CmdlineLeave|. + cmdlevel Level of cmdline. + cmdtype Type of cmdline, |cmdline-char|. + cwd Current working directory. + scope Event-specific scope name. + operator Current |operator|. Also set for Ex + commands (unlike |v:operator|). For + example if |TextYankPost| is triggered + by the |:yank| Ex command then + `v:event.operator` is "y". regcontents Text stored in the register as a |readfile()|-style list of lines. - regname Requested register (e.g "x" for "xyy) + regname Requested register (e.g "x" for "xyy) or the empty string for an unnamed operation. regtype Type of register as returned by @@ -1681,7 +1689,7 @@ v:mouse_win Window number for a mouse click obtained with |getchar()|. zero when there was no mouse button click. *v:mouse_winid* *mouse_winid-variable* -v:mouse_winid Window ID for a mouse click obtained with |getchar()|. +v:mouse_winid |window-ID| for a mouse click obtained with |getchar()|. The value is zero when there was no mouse button click. *v:mouse_lnum* *mouse_lnum-variable* @@ -1754,9 +1762,7 @@ v:profiling Normally zero. Set to one after using ":profile start". See |profiling|. *v:progname* *progname-variable* -v:progname Contains the name (with path removed) with which Nvim was - invoked. Allows you to do special initialisations for any - name you might symlink to Nvim. +v:progname The name by which Nvim was invoked (with path removed). Read-only. *v:progpath* *progpath-variable* @@ -1783,11 +1789,11 @@ v:scrollstart String describing the script or function that caused the *v:servername* *servername-variable* *$NVIM_LISTEN_ADDRESS* -v:servername Default {Nvim} server address. Equivalent to +v:servername Default Nvim server address. Equivalent to |$NVIM_LISTEN_ADDRESS| on startup. |serverstop()| Read-only. - + v:searchforward *v:searchforward* *searchforward-variable* Search direction: 1 after a forward search, 0 after a backward search. It is reset to forward when directly setting @@ -1812,6 +1818,13 @@ v:shell_error Result of the last shell command. When non-zero, the last *v:statusmsg* *statusmsg-variable* v:statusmsg Last given status message. It's allowed to set this variable. + *v:stderr* *stderr-variable* +v:stderr Channel id for stderr. Unlike stdin and stdout (see + |stdioopen()|), stderr is always open for writing. This channel + ID is always 2, but this variable can be used to be explicit. + Example: > + :call chansend(v:stderr, "something bad happened\n") +< *v:swapname* *swapname-variable* v:swapname Only valid when executing |SwapExists| autocommands: Name of the swap file found. Read-only. @@ -1852,10 +1865,11 @@ v:t_number Value of Number type. Read-only. See: |type()| v:t_string Value of String type. Read-only. See: |type()| *v:termresponse* *termresponse-variable* -v:termresponse The escape sequence returned by the terminal for the |t_RV| - termcap entry. It is set when Vim receives an escape sequence - that starts with ESC [ or CSI and ends in a 'c', with only - digits, ';' and '.' in between. +v:termresponse The escape sequence returned by the terminal for the DA + (request primary device attributes) control sequence. It is + set when Vim receives an escape sequence that starts with ESC + [ or CSI and ends in a 'c', with only digits, ';' and '.' in + between. When this option is set, the TermResponse autocommand event is fired, so that you can react to the response from the terminal. @@ -1867,6 +1881,8 @@ v:termresponse The escape sequence returned by the terminal for the |t_RV| *v:testing* *testing-variable* v:testing Must be set before using `test_garbagecollect_now()`. + Also, when set certain error messages won't be shown for 2 + seconds. (e.g. "'dictionary' option is empty") *v:this_session* *this_session-variable* v:this_session Full filename of the last loaded or saved session file. See @@ -1917,9 +1933,10 @@ v:vim_did_enter Zero until most of startup is done. It is set to one just v:warningmsg Last given warning message. It's allowed to set this variable. *v:windowid* *windowid-variable* -v:windowid Application-specific window ID ("window handle" in MS-Windows) - which may be set by any attached UI. Defaults to zero. - Note: for windows inside Vim use |winnr()| or |win_getid()|. +v:windowid Application-specific window "handle" which may be set by any + attached UI. Defaults to zero. + Note: For Nvim |windows| use |winnr()| or |win_getid()|, see + |window-ID|. ============================================================================== 4. Builtin Functions *functions* @@ -1942,16 +1959,23 @@ argidx() Number current index in the argument list arglistid([{winnr} [, {tabnr}]]) Number argument list id argv({nr}) String {nr} entry of the argument list argv() List the argument list -assert_equal({exp}, {act} [, {msg}]) none assert {exp} is equal to {act} -assert_exception( {error} [, {msg}]) none assert {error} is in v:exception -assert_fails( {cmd} [, {error}]) none assert {cmd} fails -assert_false({actual} [, {msg}]) none assert {actual} is false +assert_equal({exp}, {act} [, {msg}]) + none assert {exp} is equal to {act} +assert_exception({error} [, {msg}]) + none assert {error} is in v:exception +assert_fails({cmd} [, {error}]) none assert {cmd} fails +assert_false({actual} [, {msg}]) + none assert {actual} is false assert_inrange({lower}, {upper}, {actual} [, {msg}]) - none assert {actual} is inside the range -assert_match( {pat}, {text} [, {msg}]) none assert {pat} matches {text} -assert_notequal( {exp}, {act} [, {msg}]) none assert {exp} is not equal {act} -assert_notmatch( {pat}, {text} [, {msg}]) none assert {pat} not matches {text} -assert_true({actual} [, {msg}]) none assert {actual} is true + none assert {actual} is inside the range +assert_match({pat}, {text} [, {msg}]) + none assert {pat} matches {text} +assert_notequal({exp}, {act} [, {msg}]) + none assert {exp} is not equal {act} +assert_notmatch({pat}, {text} [, {msg}]) + none assert {pat} not matches {text} +assert_report({msg}) none report a test failure +assert_true({actual} [, {msg}]) none assert {actual} is true asin({expr}) Float arc sine of {expr} atan({expr}) Float arc tangent of {expr} atan2({expr}, {expr}) Float arc tangent of {expr1} / {expr2} @@ -1963,7 +1987,7 @@ buflisted({expr}) Number |TRUE| if buffer {expr} is listed bufloaded({expr}) Number |TRUE| if buffer {expr} is loaded bufname({expr}) String Name of the buffer {expr} bufnr({expr} [, {create}]) Number Number of the buffer {expr} -bufwinid({expr}) Number window ID of buffer {expr} +bufwinid({expr}) Number |window-ID| of buffer {expr} bufwinnr({expr}) Number window number of buffer {expr} byte2line({byte}) Number line number at byte count {byte} byteidx({expr}, {nr}) Number byte index of {nr}'th char in {expr} @@ -1972,6 +1996,8 @@ call({func}, {arglist} [, {dict}]) any call {func} with arguments {arglist} ceil({expr}) Float round {expr} up changenr() Number current change number +chanclose({id}[, {stream}]) Number Closes a channel or one of its streams +chansend({id}, {data}) Number Writes {data} to channel char2nr({expr}[, {utf8}]) Number ASCII/UTF8 value of first char in {expr} cindent({lnum}) Number C indent for line {lnum} clearmatches() none clear all matches @@ -1986,7 +2012,7 @@ cos({expr}) Float cosine of {expr} cosh({expr}) Float hyperbolic cosine of {expr} count({list}, {expr} [, {ic} [, {start}]]) Number count how many {expr} are in {list} -cscope_connection([{num} , {dbpath} [, {prepend}]]) +cscope_connection([{num}, {dbpath} [, {prepend}]]) Number checks existence of cscope connection cursor({lnum}, {col} [, {off}]) Number move cursor to {lnum}, {col}, {off} @@ -2016,11 +2042,11 @@ expand({expr} [, {nosuf} [, {list}]]) feedkeys({string} [, {mode}]) Number add key sequence to typeahead buffer filereadable({file}) Number |TRUE| if {file} is a readable file filewritable({file}) Number |TRUE| if {file} is a writable file -filter({expr}, {string}) List/Dict remove items from {expr} where - {string} is 0 -finddir({name}[, {path}[, {count}]]) +filter({expr1}, {expr2}) List/Dict remove items from {expr1} where + {expr2} is 0 +finddir({name} [, {path} [, {count}]]) String find directory {name} in {path} -findfile({name}[, {path}[, {count}]]) +findfile({name} [, {path} [, {count}]]) String find file {name} in {path} float2nr({expr}) Number convert Float {expr} to a Number floor({expr}) Float round {expr} down @@ -2041,7 +2067,7 @@ garbagecollect([{atexit}]) none free memory, breaking cyclic references get({list}, {idx} [, {def}]) any get item {idx} from {list} or {def} get({dict}, {key} [, {def}]) any get item {key} from {dict} or {def} get({func}, {what}) any get property of funcref/partial {func} -getbufinfo( [{expr}]) List information about buffers +getbufinfo([{expr}]) List information about buffers getbufline({expr}, {lnum} [, {end}]) List lines {lnum} to {end} of buffer {expr} getbufvar({expr}, {varname} [, {def}]) @@ -2064,7 +2090,7 @@ getftime({fname}) Number last modification time of file getftype({fname}) String description of type of file {fname} getline({lnum}) String line {lnum} of current buffer getline({lnum}, {end}) List lines {lnum} to {end} of current buffer -getloclist({nr}[, {what}]) List list of location list items +getloclist({nr} [, {what}]) List list of location list items getmatches() List list of current matches getpid() Number process ID of Vim getpos({expr}) List position of cursor, mark, etc. @@ -2106,7 +2132,8 @@ index({list}, {expr} [, {start} [, {ic}]]) Number index in {list} where {expr} appears input({prompt} [, {text} [, {completion}]]) String get input from the user -inputdialog({p} [, {t} [, {c}]]) String like input() but in a GUI dialog +inputdialog({prompt} [, {text} [, {completion}]]) + String like input() but in a GUI dialog inputlist({textlist}) Number let the user pick from a choice list inputrestore() Number restore typeahead inputsave() Number save and clear typeahead @@ -2119,13 +2146,11 @@ isdirectory({directory}) Number |TRUE| if {directory} is a directory islocked({expr}) Number |TRUE| if {expr} is locked id({expr}) String identifier of the container items({dict}) List key-value pairs in {dict} -jobclose({job}[, {stream}]) Number Closes a job stream(s) -jobpid({job}) Number Returns pid of a job. -jobresize({job}, {width}, {height}) - Number Resize {job}'s pseudo terminal window -jobsend({job}, {data}) Number Writes {data} to {job}'s stdin +jobpid({id}) Number Returns pid of a job. +jobresize({id}, {width}, {height}) + Number Resize pseudo terminal window of a job jobstart({cmd}[, {opts}]) Number Spawns {cmd} as a job -jobstop({job}) Number Stops a job +jobstop({id}) Number Stops a job jobwait({ids}[, {timeout}]) Number Wait for a set of jobs join({list} [, {sep}]) String join {list} items into one String json_decode({expr}) any Convert {expr} from JSON @@ -2140,7 +2165,8 @@ lispindent({lnum}) Number Lisp indent for line {lnum} localtime() Number current time log({expr}) Float natural logarithm (base e) of {expr} log10({expr}) Float logarithm of Float {expr} to base 10 -map({expr}, {string}) List/Dict change each item in {expr} to {expr} +luaeval({expr}[, {expr}]) any evaluate Lua expression +map({expr1}, {expr2}) List/Dict change each item in {expr1} to {expr} maparg({name}[, {mode} [, {abbr} [, {dict}]]]) String or Dict rhs of mapping {name} in mode {mode} @@ -2162,8 +2188,8 @@ matchstr({expr}, {pat}[, {start}[, {count}]]) String {count}'th match of {pat} in {expr} matchstrpos({expr}, {pat}[, {start}[, {count}]]) List {count}'th match of {pat} in {expr} -max({list}) Number maximum value of items in {list} -min({list}) Number minimum value of items in {list} +max({expr}) Number maximum value of items in {expr} +min({expr}) Number minimum value of items in {expr} mkdir({name} [, {path} [, {prot}]]) Number create directory {name} mode([expr]) String current editing mode @@ -2187,12 +2213,13 @@ readfile({fname} [, {binary} [, {max}]]) reltime([{start} [, {end}]]) List get time value reltimefloat({time}) Float turn the time value into a Float reltimestr({time}) String turn time value into a String -remote_expr({server}, {string} [, {idvar}]) +remote_expr({server}, {string} [, {idvar} [, {timeout}]]) String send expression remote_foreground({server}) Number bring Vim server to the foreground remote_peek({serverid} [, {retvar}]) Number check for reply string -remote_read({serverid}) String read reply string +remote_read({serverid} [, {timeout}]) + String read reply string remote_send({server}, {string} [, {idvar}]) String send key sequence remove({list}, {idx} [, {end}]) any remove items {idx}-{end} from {list} @@ -2206,7 +2233,6 @@ rpcnotify({channel}, {event}[, {args}...]) Sends an |RPC| notification to {channel} rpcrequest({channel}, {method}[, {args}...]) Sends an |RPC| request to {channel} -rpcstop({channel}) Closes an |RPC| {channel} screenattr({row}, {col}) Number attribute at screen position screenchar({row}, {col}) Number character at screen position screencol() Number current cursor column @@ -2248,6 +2274,8 @@ shiftwidth() Number effective value of 'shiftwidth' simplify({filename}) String simplify filename as much as possible sin({expr}) Float sine of {expr} sinh({expr}) Float hyperbolic sine of {expr} +sockconnect({mode}, {address} [, {opts}]) + Number Connects to socket sort({list} [, {func} [, {dict}]]) List sort {list}, using {func} to compare soundfold({word}) String sound-fold {word} @@ -2257,25 +2285,26 @@ spellsuggest({word} [, {max} [, {capital}]]) split({expr} [, {pat} [, {keepempty}]]) List make |List| from {pat} separated {expr} sqrt({expr}) Float square root of {expr} +stdioopen({dict}) Number open stdio in a headless instance. str2float({expr}) Float convert String to Float str2nr({expr} [, {base}]) Number convert String to Number strchars({expr} [, {skipcc}]) Number character length of the String {expr} -strcharpart({str}, {start}[, {len}]) +strcharpart({str}, {start} [, {len}]) String {len} characters of {str} at {start} strdisplaywidth({expr} [, {col}]) Number display length of the String {expr} -strftime({format}[, {time}]) String time in specified format +strftime({format} [, {time}]) String time in specified format strgetchar({str}, {index}) Number get char {index} from {str} -stridx({haystack}, {needle}[, {start}]) +stridx({haystack}, {needle} [, {start}]) Number index of {needle} in {haystack} string({expr}) String String representation of {expr} value strlen({expr}) Number length of the String {expr} -strpart({str}, {start}[, {len}]) +strpart({str}, {start} [, {len}]) String {len} characters of {str} at {start} strridx({haystack}, {needle} [, {start}]) Number last index of {needle} in {haystack} strtrans({expr}) String translate string to make it printable strwidth({expr}) Number display cell length of the String {expr} -submatch({nr}[, {list}]) String or List +submatch({nr} [, {list}]) String or List specific match in ":s" or substitute() substitute({expr}, {pat}, {sub}, {flags}) String all {pat} in {expr} replaced with {sub} @@ -2291,15 +2320,18 @@ tabpagebuflist([{arg}]) List list of buffer numbers in tab page tabpagenr([{arg}]) Number number of current or last tab page tabpagewinnr({tabarg}[, {arg}]) Number number of current window in tab page -taglist({expr}) List list of tags matching {expr} +taglist({expr}[, {filename}]) List list of tags matching {expr} tagfiles() List tags files used tan({expr}) Float tangent of {expr} tanh({expr}) Float hyperbolic tangent of {expr} tempname() String name for a temporary file test_garbagecollect_now() none free memory right now for testing +timer_info([{id}]) List information about timers +timer_pause({id}, {pause}) none pause or unpause a timer timer_start({time}, {callback} [, {options}]) Number create a timer timer_stop({timer}) none stop a timer +timer_stopall() none stop all timers tolower({expr}) String the String {expr} switched to lowercase toupper({expr}) String the String {expr} switched to uppercase tr({src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr} @@ -2315,10 +2347,10 @@ virtcol({expr}) Number screen column of cursor or mark visualmode([expr]) String last visual mode used wildmenumode() Number whether 'wildmenu' mode is active win_findbuf({bufnr}) List find windows containing {bufnr} -win_getid([{win} [, {tab}]]) Number get window ID for {win} in {tab} -win_gotoid({expr}) Number go to window with ID {expr} -win_id2tabwin({expr}) List get tab and window nr from window ID -win_id2win({expr}) Number get window nr from window ID +win_getid([{win} [, {tab}]]) Number get |window-ID| for {win} in {tab} +win_gotoid({expr}) Number go to |window-ID| {expr} +win_id2tabwin({expr}) List get tab and window nr from |window-ID| +win_id2win({expr}) Number get window nr from |window-ID| winbufnr({nr}) Number buffer number of window {nr} wincol() Number window column of the cursor winheight({nr}) Number height of window {nr} @@ -2409,7 +2441,7 @@ arglistid([{winnr} [, {tabnr}]]) With {winnr} only use this window in the current tab page. With {winnr} and {tabnr} use the window in the specified tab page. - {winnr} can be the window number or the window ID. + {winnr} can be the window number or the |window-ID|. *argv()* argv([{nr}]) The result is the {nr}th file in the argument list of the @@ -2455,7 +2487,7 @@ assert_exception({error} [, {msg}]) *assert_exception()* assert_fails({cmd} [, {error}]) *assert_fails()* Run {cmd} and add an error message to |v:errors| if it does NOT produce an error. - When {error} is given it must match |v:errmsg|. + When {error} is given it must match in |v:errmsg|. assert_false({actual} [, {msg}]) *assert_false()* When {actual} is not false an error message is added to @@ -2503,6 +2535,9 @@ assert_notmatch({pattern}, {actual} [, {msg}]) The opposite of `assert_match()`: add an error message to |v:errors| when {pattern} matches {actual}. +assert_report({msg}) *assert_report()* + Report a test failure directly, using {msg}. + assert_true({actual} [, {msg}]) *assert_true()* When {actual} is not true an error message is added to |v:errors|, like with |assert_equal()|. @@ -2644,7 +2679,7 @@ bufnr({expr} [, {create}]) them. Use bufexists() to test for the existence of a buffer. bufwinid({expr}) *bufwinid()* - The result is a Number, which is the window ID of the first + The result is a Number, which is the |window-ID| of the first window associated with buffer {expr}. For the use of {expr}, see |bufname()| above. If buffer {expr} doesn't exist or there is no such window, -1 is returned. Example: > @@ -2735,7 +2770,36 @@ changenr() *changenr()* redo it is the number of the redone change. After undo it is one less than the number of the undone change. -char2nr({expr}[, {utf8}]) *char2nr()* +chanclose({id}[, {stream}]) {Nvim} *chanclose()* + Close a channel or a specific stream associated with it. + For a job, {stream} can be one of "stdin", "stdout", + "stderr" or "rpc" (closes stdin/stdout for a job started + with `"rpc":v:true`) If {stream} is omitted, all streams + are closed. If the channel is a pty, this will then close the + pty master, sending SIGHUP to the job process. + For a socket, there is only one stream, and {stream} should be + ommited. + +chansend({id}, {data}) {Nvim} *chansend()* + Send data to channel {id}. For a job, it writes it to the + stdin of the process. For the stdio channel |channel-stdio|, + it writes to Nvim's stdout. Returns the number of bytes + written if the write succeeded, 0 otherwise. + See |channel-bytes| for more information. + + {data} may be a string, string convertible, or a list. If + {data} is a list, the items will be joined by newlines; any + newlines in an item will be sent as NUL. To send a final + newline, include a final empty string. Example: > + :call chansend(id, ["abc", "123\n456", ""]) +< will send "abc<NL>123<NUL>456<NL>". + + chansend() writes raw data, not RPC messages. If the channel + was created with `"rpc":v:true` then the channel expects RPC + messages, use |rpcnotify()| and |rpcrequest()| instead. + + +char2nr({expr} [, {utf8}]) *char2nr()* Return number value of the first char in {expr}. Examples: > char2nr(" ") returns 32 char2nr("ABC") returns 65 @@ -2847,8 +2911,6 @@ confirm({msg} [, {choices} [, {default} [, {type}]]]) Confirm() offers the user a dialog, from which a choice can be made. It returns the number of the choice. For the first choice this is 1. - Note: confirm() is only supported when compiled with dialog - support, see |+dialog_con| and |+dialog_gui|. {msg} is displayed in a |dialog| with {choices} as the alternatives. When {choices} is missing or empty, "&OK" is @@ -3034,6 +3096,8 @@ delete({fname} [, {flags}]) *delete()* When {flags} is "rf": Deletes the directory by the name {fname} and everything in it, recursively. BE CAREFUL! + Note: on MS-Windows it is not possible to delete a directory + that is being used. The result is a Number, which is 0 if the delete operation was successful and -1 when the deletion failed or partly failed. @@ -3088,6 +3152,7 @@ did_filetype() Returns |TRUE| when autocommands are being executed and the FileType event has been triggered at least once. Can be used to avoid triggering the FileType event again in the scripts that detect the file type. |FileType| + Returns |FALSE| when `:setf FALLBACK` was used. When editing another file, the counter is reset, thus this really checks if the FileType event has been triggered for the current buffer. This allows an autocommand that starts @@ -3179,7 +3244,7 @@ execute({command} [, {silent}]) *execute()* "" no `:silent` used "silent" `:silent` used "silent!" `:silent!` used - The default is 'silent'. Note that with "silent!", unlike + The default is "silent". Note that with "silent!", unlike `:redir`, error messages are dropped. To get a list of lines use |split()| on the result: > @@ -3198,8 +3263,12 @@ exepath({expr}) *exepath()* *exists()* exists({expr}) The result is a Number, which is |TRUE| if {expr} is - defined, zero otherwise. The {expr} argument is a string, - which contains one of these: + defined, zero otherwise. + + For checking for a supported feature use |has()|. + For checking if a file exists use |filereadable()|. + + The {expr} argument is a string, which contains one of these: &option-name Vim option (only checks if it exists, not if it really works) +option-name Vim option that works. @@ -3247,7 +3316,6 @@ exists({expr}) The result is a Number, which is |TRUE| if {expr} is event and pattern. ##event autocommand for this event is supported. - For checking for a supported feature use |has()|. Examples: > exists("&mouse") @@ -3465,9 +3533,10 @@ filter({expr1}, {expr2}) *filter()* is zero remove the item from the |List| or |Dictionary|. {expr2} must be a |string| or |Funcref|. - if {expr2} is a |string|, inside {expr2} |v:val| has the value + If {expr2} is a |string|, inside {expr2} |v:val| has the value of the current item. For a |Dictionary| |v:key| has the key - of the current item. + of the current item and for a |List| |v:key| has the index of + the current item. For a |Dictionary| |v:key| has the key of the current item. Examples: > call filter(mylist, 'v:val !~ "OLD"') @@ -3490,6 +3559,10 @@ filter({expr1}, {expr2}) *filter()* return a:idx % 2 == 1 endfunc call filter(mylist, function('Odd')) +< It is shorter when using a |lambda|: > + call filter(myList, {idx, val -> idx * val <= 42}) +< If you do not use "val" you can leave it out: > + call filter(myList, {idx -> idx % 2 == 1}) < The operation is done in-place. If you want a |List| or |Dictionary| to remain unmodified make a copy first: > @@ -3502,7 +3575,7 @@ filter({expr1}, {expr2}) *filter()* defined with the "abort" flag. -finddir({name}[, {path}[, {count}]]) *finddir()* +finddir({name} [, {path} [, {count}]]) *finddir()* Find directory {name} in {path}. Supports both downwards and upwards recursive directory searches. See |file-searching| for the syntax of {path}. @@ -3517,7 +3590,7 @@ finddir({name}[, {path}[, {count}]]) *finddir()* {only available when compiled with the |+file_in_path| feature} -findfile({name}[, {path}[, {count}]]) *findfile()* +findfile({name} [, {path} [, {count}]]) *findfile()* Just like |finddir()|, but find a file instead of a directory. Uses 'suffixesadd'. Example: > @@ -3530,17 +3603,19 @@ float2nr({expr}) *float2nr()* decimal point. {expr} must evaluate to a |Float| or a Number. When the value of {expr} is out of range for a |Number| the - result is truncated to 0x7fffffff or -0x7fffffff. NaN results - in -0x80000000. + result is truncated to 0x7fffffff or -0x7fffffff (or when + 64-bit Number support is enabled, 0x7fffffffffffffff or + -0x7fffffffffffffff. NaN results in -0x80000000 (or when + 64-bit Number support is enabled, -0x8000000000000000). Examples: > echo float2nr(3.95) < 3 > echo float2nr(-23.45) < -23 > echo float2nr(1.0e100) -< 2147483647 > +< 2147483647 (or 9223372036854775807) > echo float2nr(-1.0e150) -< -2147483647 > +< -2147483647 (or -9223372036854775807) > echo float2nr(1.0e-100) < 0 @@ -3626,11 +3701,14 @@ foldtext() Returns a String, to be displayed for a closed fold. This is |v:foldstart|, |v:foldend| and |v:folddashes| variables. The returned string looks like this: > +-- 45 lines: abcdef -< The number of dashes depends on the foldlevel. The "45" is - the number of lines in the fold. "abcdef" is the text in the - first non-blank line of the fold. Leading white space, "//" - or "/*" and the text from the 'foldmarker' and 'commentstring' - options is removed. +< The number of leading dashes depends on the foldlevel. The + "45" is the number of lines in the fold. "abcdef" is the text + in the first non-blank line of the fold. Leading white space, + "//" or "/*" and the text from the 'foldmarker' and + 'commentstring' options is removed. + When used to draw the actual foldtext, the rest of the line + will be filled with the fold char from the 'fillchars' + setting. {not available when compiled without the |+folding| feature} foldtextresult({lnum}) *foldtextresult()* @@ -3679,7 +3757,7 @@ function({name} [, {arglist}] [, {dict}]) When {arglist} or {dict} is present this creates a partial. That mans the argument list and/or the dictionary is stored in the Funcref and will be used when the Funcref is called. - + The arguments are passed to the function in front of other arguments. Example: > func Callback(arg1, arg2, name) @@ -3744,10 +3822,10 @@ get({dict}, {key} [, {default}]) get({func}, {what}) Get item {what} from Funcref {func}. Possible values for {what} are: - 'name' The function name - 'func' The function - 'dict' The dictionary - 'args' The list with arguments + "name" The function name + "func" The function + "dict" The dictionary + "args" The list with arguments *getbufinfo()* getbufinfo([{expr}]) @@ -3998,6 +4076,7 @@ getcompletion({pat}, {type} [, {filtered}]) *getcompletion()* augroup autocmd groups buffer buffer names behave :behave suboptions + cmdline |cmdline-completion| color color schemes command Ex command (and arguments) compiler compilers @@ -4016,7 +4095,9 @@ getcompletion({pat}, {type} [, {filtered}]) *getcompletion()* locale locale names (as output of locale -a) mapping mapping name menu menus + messages |:messages| suboptions option options + packadd optional package |pack-add| names shellcmd Shell command sign |:sign| suboptions syntax syntax file names |'syntax'| @@ -4026,7 +4107,7 @@ getcompletion({pat}, {type} [, {filtered}]) *getcompletion()* user user names var user variables - If {pat} is an empty string, then all the matches are returned. + If {pat} is an empty string then all matches are returned. Otherwise only items matching {pat} are returned. See |wildcards| for the use of special characters in {pat}. @@ -4041,13 +4122,16 @@ getcompletion({pat}, {type} [, {filtered}]) *getcompletion()* getcurpos() Get the position of the cursor. This is like getpos('.'), but includes an extra item in the list: [bufnum, lnum, col, off, curswant] ~ - The "curswant" number is the preferred column when moving the - cursor vertically. - This can be used to save and restore the cursor position: > - let save_cursor = getcurpos() - MoveTheCursorAround - call setpos('.', save_cursor) -< + The "curswant" number is the preferred column when moving the + cursor vertically. Also see |getpos()|. + + This can be used to save and restore the cursor position: > + let save_cursor = getcurpos() + MoveTheCursorAround + call setpos('.', save_cursor) +< Note that this only works within the window. See + |winrestview()| for restoring more state. + getcwd([{winnr}[, {tabnr}]]) *getcwd()* With no arguments the result is a String, which is the name of the current effective working directory. With {winnr} or @@ -4059,7 +4143,7 @@ getcwd([{winnr}[, {tabnr}]]) *getcwd()* getcwd(0) getcwd(0, 0) < If {winnr} is -1 it is ignored, only the tab is resolved. - {winnr} can be the window number or the window ID. + {winnr} can be the window number or the |window-ID|. getfsize({fname}) *getfsize()* @@ -4154,7 +4238,7 @@ getline({lnum} [, {end}]) getloclist({nr},[, {what}]) *getloclist()* Returns a list with all the entries in the location list for - window {nr}. {nr} can be the window number or the window ID. + window {nr}. {nr} can be the window number or the |window-ID|. When {nr} is zero the current window is used. For a location list window, the displayed location list is @@ -4229,7 +4313,7 @@ getqflist([{what}]) *getqflist()* type type of the error, 'E', '1', etc. valid |TRUE|: recognized error message - When there is no error list or it's empty an empty list is + When there is no error list or it's empty, an empty list is returned. Quickfix list entries with non-existing buffer number are returned with "bufnr" set to zero. @@ -4243,9 +4327,10 @@ getqflist([{what}]) *getqflist()* If the optional {what} dictionary argument is supplied, then returns only the items listed in {what} as a dictionary. The following string items are supported in {what}: - nr get information for this quickfix list - title get list title - winid get window id (if opened) + nr get information for this quickfix list; zero + means the current quickfix list + title get the list title + winid get the |window-ID| (if opened) all all of the above quickfix properties Non-string items in {what} are ignored. If "nr" is not present then the current quickfix list is used. @@ -4255,7 +4340,7 @@ getqflist([{what}]) *getqflist()* The returned dictionary contains the following entries: nr quickfix list number title quickfix list title text - winid quickfix window id (if opened) + winid quickfix |window-ID| (if opened) Examples: > :echo getqflist({'all': 1}) @@ -4266,7 +4351,7 @@ getreg([{regname} [, 1 [, {list}]]]) *getreg()* The result is a String, which is the contents of register {regname}. Example: > :let cliptext = getreg('*') -< When {regname} was not set the result is a empty string. +< When {regname} was not set the result is an empty string. getreg('=') returns the last evaluated value of the expression register. (For use in maps.) @@ -4302,10 +4387,10 @@ gettabinfo([{arg}]) *gettabinfo()* empty List is returned. Each List item is a Dictionary with the following entries: - nr tab page number. + tabnr tab page number. variables a reference to the dictionary with tabpage-local variables - windows List of window IDs in the tag page. + windows List of |window-ID|s in the tag page. gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()* Get the value of a tab-local variable {varname} in tab page @@ -4329,7 +4414,7 @@ gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()* Note that {varname} must be the name without "w:". Tabs are numbered starting with one. For the current tabpage use |getwinvar()|. - {winnr} can be the window number or the window ID. + {winnr} can be the window number or the |window-ID|. When {winnr} is zero the current window is used. This also works for a global option, buffer-local option and window-local option, but it doesn't work for a global variable @@ -4344,11 +4429,13 @@ gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()* getwinposx() The result is a Number, which is the X coordinate in pixels of the left hand side of the GUI Vim window. The result will be -1 if the information is not available. + The value can be used with `:winpos`. *getwinposy()* getwinposy() The result is a Number, which is the Y coordinate in pixels of the top of the GUI Vim window. The result will be -1 if the information is not available. + The value can be used with `:winpos`. getwininfo([{winid}]) *getwininfo()* Returns information about windows as a List with Dictionaries. @@ -4357,20 +4444,22 @@ getwininfo([{winid}]) *getwininfo()* is returned. If the window does not exist the result is an empty list. - Without an information about all the windows in all the tab - pages is returned. + Without {winid} information about all the windows in all the + tab pages is returned. Each List item is a Dictionary with the following entries: - bufnum number of buffer in the window - height window height + bufnr number of buffer in the window + height window height (excluding winbar) + winbar 1 if the window has a toolbar, 0 + otherwise loclist 1 if showing a location list - nr window number quickfix 1 if quickfix or location list window - tpnr tab page number + tabnr tab page number variables a reference to the dictionary with window-local variables width window width - winid window ID + winid |window-ID| + winnr window number To obtain all window-local variables use: > gettabwinvar({tabnr}, {winnr}, '&') @@ -4474,9 +4563,8 @@ has_key({dict}, {key}) *has_key()* an entry with key {key}. Zero otherwise. haslocaldir([{winnr}[, {tabnr}]]) *haslocaldir()* - The result is a Number, which is 1 when the specified tabpage - or window has a local path set via |:lcd| or |:tcd|, and - 0 otherwise. + The result is a Number, which is 1 when the tabpage or window + has set a local path via |:tcd| or |:lcd|, otherwise 0. Tabs and windows are identified by their respective numbers, 0 means current tab or window. Missing argument implies 0. @@ -4484,7 +4572,9 @@ haslocaldir([{winnr}[, {tabnr}]]) *haslocaldir()* haslocaldir() haslocaldir(0) haslocaldir(0, 0) -< {winnr} can be the window number or the window ID. +< With {winnr} use that window in the current tabpage. + With {winnr} and {tabnr} use the window in that tabpage. + {winnr} can be the window number or the |window-ID|. If {winnr} is -1 it is ignored, only the tab is resolved. hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()* @@ -4523,6 +4613,7 @@ histadd({history}, {item}) *histadd()* "expr" or "=" typed expression history "input" or "@" input line history "debug" or ">" debug command history + empty the current or last used history The {history} string does not need to be the whole name, one character is sufficient. If {item} does already exist in the history, it will be @@ -4652,10 +4743,24 @@ index({list}, {expr} [, {start} [, {ic}]]) *index()* input({prompt} [, {text} [, {completion}]]) *input()* +input({opts}) The result is a String, which is whatever the user typed on the command-line. The {prompt} argument is either a prompt string, or a blank string (for no prompt). A '\n' can be used in the prompt to start a new line. + + In the second form it accepts a single dictionary with the + following keys, any of which may be omitted: + + Key Default Description ~ + prompt "" Same as {prompt} in the first form. + default "" Same as {text} in the first form. + completion nothing Same as {completion} in the first form. + cancelreturn "" Same as {cancelreturn} from + |inputdialog()|. Also works with + input(). + highlight nothing Highlight handler: |Funcref|. + The highlighting set with |:echohl| is used for the prompt. The input is entered just like a command-line, with the same editing commands and mappings. There is a separate history @@ -4677,7 +4782,60 @@ input({prompt} [, {text} [, {completion}]]) *input()* "-complete=" argument. Refer to |:command-completion| for more information. Example: > let fname = input("File: ", "", "file") + +< *input()-highlight* *E5400* *E5402* + The optional `highlight` key allows specifying function which + will be used for highlighting user input. This function + receives user input as its only argument and must return + a list of 3-tuples [hl_start_col, hl_end_col + 1, hl_group] + where + hl_start_col is the first highlighted column, + hl_end_col is the last highlighted column (+ 1!), + hl_group is |:hl| group used for highlighting. + *E5403* *E5404* *E5405* *E5406* + Both hl_start_col and hl_end_col + 1 must point to the start + of the multibyte character (highlighting must not break + multibyte characters), hl_end_col + 1 may be equal to the + input length. Start column must be in range [0, len(input)), + end column must be in range (hl_start_col, len(input)], + sections must be ordered so that next hl_start_col is greater + then or equal to previous hl_end_col. + + Example (try some input with parentheses): > + highlight RBP1 guibg=Red ctermbg=red + highlight RBP2 guibg=Yellow ctermbg=yellow + highlight RBP3 guibg=Green ctermbg=green + highlight RBP4 guibg=Blue ctermbg=blue + let g:rainbow_levels = 4 + function! RainbowParens(cmdline) + let ret = [] + let i = 0 + let lvl = 0 + while i < len(a:cmdline) + if a:cmdline[i] is# '(' + call add(ret, [i, i + 1, 'RBP' . ((lvl % g:rainbow_levels) + 1)]) + let lvl += 1 + elseif a:cmdline[i] is# ')' + let lvl -= 1 + call add(ret, [i, i + 1, 'RBP' . ((lvl % g:rainbow_levels) + 1)]) + endif + let i += 1 + endwhile + return ret + endfunction + call input({'prompt':'>','highlight':'RainbowParens'}) < + Highlight function is called at least once for each new + displayed input string, before command-line is redrawn. It is + expected that function is pure for the duration of one input() + call, i.e. it produces the same output for the same input, so + output may be memoized. Function is run like under |:silent| + modifier. If the function causes any errors, it will be + skipped for the duration of the current input() call. + + Currently coloring is disabled when command-line contains + arabic characters. + NOTE: This function must not be used in a startup file, for the versions that only run in GUI mode (e.g., the Win32 GUI). Note: When input() is called from within a mapping it will @@ -4697,6 +4855,7 @@ input({prompt} [, {text} [, {completion}]]) *input()* :endfunction inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()* +inputdialog({opts}) Like |input()|, but when the GUI is running and text dialogs are supported, a dialog window pops up to input the text. Example: > @@ -4708,7 +4867,6 @@ inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()* omitted an empty string is returned. Hitting <Enter> works like pressing the OK button. Hitting <Esc> works like pressing the Cancel button. - NOTE: Command-line completion is not supported. inputlist({textlist}) *inputlist()* {textlist} must be a |List| of strings. This |List| is @@ -4811,64 +4969,58 @@ items({dict}) *items()* entry and the value of this entry. The |List| is in arbitrary order. -jobclose({job}[, {stream}]) {Nvim} *jobclose()* - Close {job}'s {stream}, which can be one of "stdin", "stdout", - "stderr" or "rpc" (closes the rpc channel for a job started - with the "rpc" option.) If {stream} is omitted, all streams - are closed. If the job is a pty job, this will then close the - pty master, sending SIGHUP to the job process. - -jobpid({job}) {Nvim} *jobpid()* - Return the pid (process id) of {job}. - -jobresize({job}, {width}, {height}) {Nvim} *jobresize()* - Resize {job}'s pseudo terminal window to {width} and {height}. - This function will fail if used on jobs started without the - "pty" option. -jobsend({job}, {data}) {Nvim} *jobsend()* - Send data to {job} by writing it to the stdin of the process. - Returns 1 if the write succeeded, 0 otherwise. - See |job-control| for more information. - - {data} may be a string, string convertible, or a list. If - {data} is a list, the items will be separated by newlines and - any newlines in an item will be sent as a NUL. A final newline - can be sent by adding a final empty string. For example: > - :call jobsend(j, ["abc", "123\n456", ""]) -< will send "abc<NL>123<NUL>456<NL>". +jobpid({job}) *jobpid()* + Return the PID (process id) of |job-id| {job}. - If the job was started with the rpc option this function - cannot be used, instead use |rpcnotify()| and |rpcrequest()| - to communicate with the job. +jobresize({job}, {width}, {height}) *jobresize()* + Resize the pseudo terminal window of |job-id| {job} to {width} + columns and {height} rows. + Fails if the job was not started with `"pty":v:true`. -jobstart({cmd}[, {opts}]) {Nvim} *jobstart()* - Spawns {cmd} as a job. If {cmd} is a |List| it is run - directly. If {cmd} is a |String| it is processed like this: > +jobstart({cmd}[, {opts}]) *jobstart()* + Spawns {cmd} as a job. + If {cmd} is a List it runs directly (no 'shell'). + If {cmd} is a String it runs in the 'shell', like this: > :call jobstart(split(&shell) + split(&shellcmdflag) + ['{cmd}']) -< NOTE: This only shows the idea; see |shell-unquoting| before - constructing lists with 'shell' or 'shellcmdflag'. - - NOTE: On Windows if {cmd} is a List, cmd[0] must be a valid - executable (.exe, .com). If the executable is in $PATH it can - be called by name, with or without an extension: > - :call jobstart(['ping', 'neovim.io']) -< If it is a path (not a name), it must include the extension: > - :call jobstart(['System32\ping.exe', 'neovim.io']) -< +< (See |shell-unquoting| for details.) + + Returns |job-id| on success, 0 on invalid arguments (or job + table is full), -1 if {cmd}[0] or 'shell' is not executable. + For communication over the job's stdio, it is represented as a + |channel|, and a channel ID is returned on success. Use + |chansend()| (or |rpcnotify()| and |rpcrequest()| if "rpc" option + was used) to send data to stdin and |chanclose()| to close stdio + streams without stopping the job explicitly. + + See |job-control| and |rpc|. + + NOTE: on Windows if {cmd} is a List: + - cmd[0] must be an executable (not a "built-in"). If it is + in $PATH it can be called by name, without an extension: > + :call jobstart(['ping', 'neovim.io']) +< If it is a full or partial path, extension is required: > + :call jobstart(['System32\ping.exe', 'neovim.io']) +< - {cmd} is collapsed to a string of quoted args as expected + by CommandLineToArgvW https://msdn.microsoft.com/bb776391 + unless cmd[0] is some form of "cmd.exe". + + *jobstart-options* {opts} is a dictionary with these keys: - on_stdout: stdout event handler (function name or |Funcref|) - on_stderr: stderr event handler (function name or |Funcref|) - on_exit : exit event handler (function name or |Funcref|) + |on_stdout|: stdout event handler (function name or |Funcref|) + stdout_buffered : read stdout in |buffered| mode. + |on_stderr|: stderr event handler (function name or |Funcref|) + stderr_buffered : read stderr in |buffered| mode. + |on_exit| : exit event handler (function name or |Funcref|) cwd : Working directory of the job; defaults to |current-directory|. rpc : If set, |msgpack-rpc| will be used to communicate with the job over stdin and stdout. "on_stdout" is then ignored, but "on_stderr" can still be used. pty : If set, the job will be connected to a new pseudo - terminal, and the job streams are connected to - the master file descriptor. "on_stderr" is ignored - as all output will be received on stdout. + terminal and the job streams are connected to the + master file descriptor. "on_stderr" is ignored, + "on_stdout" receives all output. width : (pty only) Width of the terminal screen height : (pty only) Height of the terminal screen @@ -4876,43 +5028,36 @@ jobstart({cmd}[, {opts}]) {Nvim} *jobstart()* detach : (non-pty only) Detach the job process from the nvim process. The process will not get killed when nvim exits. If the process dies before - nvim exits, on_exit will still be invoked. + nvim exits, "on_exit" will still be invoked. - {opts} is passed as |self| to the callback; the caller may - pass arbitrary data by setting other keys. + {opts} is passed as |self| dictionary to the callback; the + caller may set other keys to pass application-specific data. Returns: - - The job ID on success, which is used by |jobsend()| (or - |rpcnotify()| and |rpcrequest()| if "rpc" option was used) - and |jobstop()| - - 0 on invalid arguments or if the job table is full + - The channel ID on success + - 0 on invalid arguments - -1 if {cmd}[0] is not executable. - See |job-control| and |msgpack-rpc| for more information. + See |job-control|, |channels|, and |msgpack-rpc| for more information. -jobstop({job}) {Nvim} *jobstop()* - Stop a job created with |jobstart()| by sending a `SIGTERM` - to the corresponding process. If the process doesn't exit - cleanly soon, a `SIGKILL` will be sent. When the job is - finally closed, the exit handler provided to |jobstart()| or - |termopen()| will be run. - See |job-control| for more information. +jobstop({id}) *jobstop()* + Stop |job-id| {id} by sending SIGTERM to the job process. If + the process does not terminate after a timeout then SIGKILL + will be sent. When the job terminates its |on_exit| handler + (if any) will be invoked. + See |job-control|. -jobwait({ids}[, {timeout}]) {Nvim} *jobwait()* +jobwait({ids}[, {timeout}]) *jobwait()* Wait for a set of jobs to finish. The {ids} argument is a list - of ids for jobs that will be waited for. If passed, {timeout} - is the maximum number of milliseconds to wait. While this - function is executing, callbacks for jobs not in the {ids} - list can be executed. Also, the screen wont be updated unless - |:redraw| is invoked by one of the callbacks. - - Returns a list of integers with the same length as {ids}, with - each integer representing the wait result for the - corresponding job id. The possible values for the resulting - integers are: - - * the job return code if the job exited - * -1 if the wait timed out for the job - * -2 if the job was interrupted - * -3 if the job id is invalid. + of |job-id|s to wait for. {timeout} is the maximum number of + milliseconds to wait. During jobwait(), callbacks for jobs not + in the {ids} list may be invoked. The screen will not redraw + unless |:redraw| is invoked by a callback. + + Returns a list of len({ids}) integers, where each integer is + the wait-result of the corresponding job. Each wait-result is: + Job exit-code, if the job exited + -1 if the wait timed out for the job + -2 if the job was interrupted + -3 if the |job-id| is invalid. join({list} [, {sep}]) *join()* Join the items in {list} together into one String. @@ -4943,8 +5088,8 @@ json_decode({expr}) *json_decode()* json_encode({expr}) *json_encode()* Convert {expr} into a JSON string. Accepts - |msgpack-special-dict| as the input. Will not convert |Funcref|s, - mappings with non-string keys (can be created as + |msgpack-special-dict| as the input. Will not convert + |Funcref|s, mappings with non-string keys (can be created as |msgpack-special-dict|), values with self-referencing containers, strings which contain non-UTF-8 characters, pseudo-UTF-8 strings which contain codepoints reserved for @@ -5047,7 +5192,10 @@ line({expr}) The result is a Number, which is the line number of the file < *last-position-jump* This autocommand jumps to the last known position in a file just after opening it, if the '" mark is set: > - :au BufReadPost * if line("'\"") > 1 && line("'\"") <= line("$") | exe "normal! g`\"" | endif + :au BufReadPost * + \ if line("'\"") > 1 && line("'\"") <= line("$") && &ft !~# 'commit' + \ | exe "normal! g`\"" + \ | endif line2byte({lnum}) *line2byte()* Return the byte count from the start of the buffer for line @@ -5095,6 +5243,9 @@ log10({expr}) *log10()* :echo log10(0.01) < -2.0 +luaeval({expr}[, {expr}]) + Evaluate Lua expression {expr} and return its result converted + to Vim data structures. See |lua-luaeval| for more details. map({expr1}, {expr2}) *map()* {expr1} must be a |List| or a |Dictionary|. @@ -5123,6 +5274,10 @@ map({expr1}, {expr2}) *map()* return a:key . '-' . a:val endfunc call map(myDict, function('KeyValue')) +< It is shorter when using a |lambda|: > + call map(myDict, {key, val -> key . '-' . val}) +< If you do not use "val" you can leave it out: > + call map(myDict, {key -> 'item: ' . key}) < The operation is done in-place. If you want a |List| or |Dictionary| to remain unmodified make a copy first: > @@ -5135,12 +5290,12 @@ map({expr1}, {expr2}) *map()* defined with the "abort" flag. -maparg({name}[, {mode} [, {abbr} [, {dict}]]]) *maparg()* +maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()* When {dict} is omitted or zero: Return the rhs of mapping {name} in mode {mode}. The returned String has special characters translated like in the output of the ":map" command listing. - + When there is no mapping for {name}, an empty String is returned. @@ -5156,6 +5311,7 @@ maparg({name}[, {mode} [, {abbr} [, {dict}]]]) *maparg()* "s" Select "x" Visual "l" langmap |language-mapping| + "t" Terminal "" Normal, Visual and Operator-pending When {mode} is omitted, the modes for "" are used. @@ -5189,7 +5345,7 @@ maparg({name}[, {mode} [, {abbr} [, {dict}]]]) *maparg()* exe 'nnoremap <Tab> ==' . maparg('<Tab>', 'n') -mapcheck({name}[, {mode} [, {abbr}]]) *mapcheck()* +mapcheck({name} [, {mode} [, {abbr}]]) *mapcheck()* Check if there is a mapping that matches with {name} in mode {mode}. See |maparg()| for {mode} and special names in {name}. @@ -5221,7 +5377,7 @@ mapcheck({name}[, {mode} [, {abbr}]]) *mapcheck()* < This avoids adding the "_vv" mapping when there already is a mapping for "_v" or for "_vvv". -match({expr}, {pat}[, {start}[, {count}]]) *match()* +match({expr}, {pat} [, {start} [, {count}]]) *match()* When {expr} is a |List| then this returns the index of the first item where {pat} matches. Each item is used as a String, |Lists| and |Dictionaries| are used as echoed. @@ -5329,7 +5485,8 @@ matchadd({group}, {pattern}[, {priority}[, {id} [, {dict}]]]) available from |getmatches()|. All matches can be deleted in one operation by |clearmatches()|. -matchaddpos({group}, {pos}[, {priority}[, {id}[, {dict}]]]) *matchaddpos()* + *matchaddpos()* +matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]]) Same as |matchadd()|, but requires a list of positions {pos} instead of a pattern. This command is faster than |matchadd()| because it does not require to handle regular expressions and @@ -5349,7 +5506,7 @@ matchaddpos({group}, {pos}[, {priority}[, {id}[, {dict}]]]) *matchaddpos()* be highlighted. - A list with three numbers, e.g., [23, 11, 3]. As above, but the third number gives the length of the highlight in bytes. - + The maximum number of positions is 8. Example: > @@ -5382,7 +5539,7 @@ matchdelete({id}) *matchdelete()* *E802* *E803* otherwise -1. See example for |matchadd()|. All matches can be deleted in one operation by |clearmatches()|. -matchend({expr}, {pat}[, {start}[, {count}]]) *matchend()* +matchend({expr}, {pat} [, {start} [, {count}]]) *matchend()* Same as |match()|, but return the index of first character after the match. Example: > :echo matchend("testing", "ing") @@ -5401,7 +5558,7 @@ matchend({expr}, {pat}[, {start}[, {count}]]) *matchend()* < result is "-1". When {expr} is a |List| the result is equal to |match()|. -matchlist({expr}, {pat}[, {start}[, {count}]]) *matchlist()* +matchlist({expr}, {pat} [, {start} [, {count}]]) *matchlist()* Same as |match()|, but return a |List|. The first item in the list is the matched string, same as what matchstr() would return. Following items are submatches, like "\1", "\2", etc. @@ -5411,7 +5568,7 @@ matchlist({expr}, {pat}[, {start}[, {count}]]) *matchlist()* < Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', ''] When there is no match an empty list is returned. -matchstr({expr}, {pat}[, {start}[, {count}]]) *matchstr()* +matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()* Same as |match()|, but return the matched string. Example: > :echo matchstr("testing", "ing") < results in "ing". @@ -5424,7 +5581,7 @@ matchstr({expr}, {pat}[, {start}[, {count}]]) *matchstr()* When {expr} is a |List| then the matching item is returned. The type isn't changed, it's not necessarily a String. -matchstrpos({expr}, {pat}[, {start}[, {count}]]) *matchstrpos()* +matchstrpos({expr}, {pat} [, {start} [, {count}]]) *matchstrpos()* Same as |matchstr()|, but return the matched string, the start position and the end position of the match. Example: > :echo matchstrpos("testing", "ing") @@ -5443,16 +5600,65 @@ matchstrpos({expr}, {pat}[, {start}[, {count}]]) *matchstrpos()* The type isn't changed, it's not necessarily a String. *max()* -max({list}) Return the maximum value of all items in {list}. - If {list} is not a list or one of the items in {list} cannot - be used as a Number this results in an error. - An empty |List| results in zero. +max({expr}) Return the maximum value of all items in {expr}. + {expr} can be a list or a dictionary. For a dictionary, + it returns the maximum of all values in the dictionary. + If {expr} is neither a list nor a dictionary, or one of the + items in {expr} cannot be used as a Number this results in + an error. An empty |List| or |Dictionary| results in zero. + +menu_get({path}, {modes}) *menu_get()* + Returns a |List| of |Dictionaries| describing |menus| (defined + by |:menu|, |:amenu|, etc.). + {path} limits the result to a subtree of the menu hierarchy + (empty string matches all menus). E.g. to get items in the + "File" menu subtree: > + :echo menu_get('File','') +< + {modes} is a string of zero or more modes (see |maparg()| or + |creating-menus| for the list of modes). "a" means "all". + + For example: > + nnoremenu &Test.Test inormal + inoremenu Test.Test insert + vnoremenu Test.Test x + echo menu_get("") +< + returns something like this: +> + [ { + "hidden": 0, + "name": "Test", + "priority": 500, + "shortcut": 84, + "submenus": [ { + "hidden": 0, + "mappings": { + i": { + "enabled": 1, + "noremap": 1, + "rhs": "insert", + "sid": 1, + "silent": 0 + }, + n": { ... }, + s": { ... }, + v": { ... } + }, + "name": "Test", + "priority": 500, + "shortcut": 0 + } ] + } ] +< *min()* -min({list}) Return the minimum value of all items in {list}. - If {list} is not a list or one of the items in {list} cannot - be used as a Number this results in an error. - An empty |List| results in zero. +min({expr}) Return the minimum value of all items in {expr}. + {expr} can be a list or a dictionary. For a dictionary, + it returns the minimum of all values in the dictionary. + If {expr} is neither a list nor a dictionary, or one of the + items in {expr} cannot be used as a Number this results in + an error. An empty |List| or |Dictionary| results in zero. *mkdir()* *E739* mkdir({name} [, {path} [, {prot}]]) @@ -5487,16 +5693,20 @@ mode([expr]) Return a string that indicates the current mode. S Select by line CTRL-S Select blockwise i Insert + ic Insert mode completion |compl-generic| + ix Insert mode |i_CTRL-X| completion R Replace |R| + Rc Replace mode completion |compl-generic| Rv Virtual Replace |gR| - t Terminal {Nvim} - c Command-line + Rx Replace mode |i_CTRL-X| completion + c Command-line editing cv Vim Ex mode |gQ| ce Normal Ex mode |Q| r Hit-enter prompt rm The -- more -- prompt r? A |:confirm| query of some sort ! Shell or external command is executing + t Terminal mode: keys go to the job This is useful in the 'statusline' option or when used with |remote_expr()| In most other places it always returns "c" or "n". @@ -5600,7 +5810,7 @@ nextnonblank({lnum}) *nextnonblank()* below it, zero is returned. See also |prevnonblank()|. -nr2char({expr}[, {utf8}]) *nr2char()* +nr2char({expr} [, {utf8}]) *nr2char()* Return a string with a single character, which has the number value {expr}. Examples: > nr2char(64) returns "@" @@ -5638,7 +5848,7 @@ pathshorten({expr}) *pathshorten()* components in the path are reduced to single letters. Leading '~' and '.' characters are kept. Example: > :echo pathshorten('~/.config/nvim/autoload/file1.vim') -< ~/.v/a/file1.vim ~ +< ~/.c/n/a/file1.vim ~ It doesn't matter if the path exists or not. pow({x}, {y}) *pow()* @@ -5683,11 +5893,12 @@ printf({fmt}, {expr1} ...) *printf()* %04x hex number padded with zeros to at least 4 characters %X hex number using upper case letters %o octal number - %f floating point number in the form 123.456 - %e floating point number in the form 1.234e3 - %E floating point number in the form 1.234E3 + %f floating point number as 12.23, inf, -inf or nan + %F floating point number as 12.23, INF, -INF or NAN + %e floating point number as 1.23e3, inf, -inf or nan + %E floating point number as 1.23E3, INF, -INF or NAN %g floating point number, as %f or %e depending on value - %G floating point number, as %f or %E depending on value + %G floating point number, as %F or %E depending on value %% the % character itself %p representation of the pointer to the container @@ -5798,6 +6009,9 @@ printf({fmt}, {expr1} ...) *printf()* s The text of the String argument is used. If a precision is specified, no more bytes than the number specified are used. + If the argument is not a String type, it is + automatically converted to text with the same format + as ":echo". *printf-S* S The text of the String argument is used. If a precision is specified, no more display cells than the @@ -5805,13 +6019,14 @@ printf({fmt}, {expr1} ...) *printf()* feature works just like 's'. *printf-f* *E807* - f F The Float argument is converted into a string of the + f F The Float argument is converted into a string of the form 123.456. The precision specifies the number of digits after the decimal point. When the precision is zero the decimal point is omitted. When the precision is not specified 6 is used. A really big number - (out of range or dividing by zero) results in "inf". - "0.0 / 0.0" results in "nan". + (out of range or dividing by zero) results in "inf" + or "-inf" with %f (INF or -INF with %F). + "0.0 / 0.0" results in "nan" with %f (NAN with %F). Example: > echo printf("%.2f", 12.115) < 12.12 @@ -5870,10 +6085,10 @@ py3eval({expr}) *py3eval()* pyeval({expr}) *pyeval()* Evaluate Python expression {expr} and return its result converted to Vim data structures. - Numbers and strings are returned as they are (strings are + Numbers and strings are returned as they are (strings are copied though). Lists are represented as Vim |List| type. - Dictionaries are represented as Vim |Dictionary| type, + Dictionaries are represented as Vim |Dictionary| type, non-string keys result in error. {only available when compiled with the |+python| feature} @@ -5899,9 +6114,9 @@ range({expr} [, {max} [, {stride}]]) *range()* *readfile()* readfile({fname} [, {binary} [, {max}]]) Read file {fname} and return a |List|, each line of the file - as an item. Lines broken at NL characters. Macintosh files - separated with CR will result in a single long line (unless a - NL appears somewhere). + as an item. Lines are broken at NL characters. Macintosh + files separated with CR will result in a single long line + (unless a NL appears somewhere). All NUL characters are replaced with a NL character. When {binary} contains "b" binary mode is used: - When the last line ends in a NL an extra empty list item is @@ -5984,6 +6199,12 @@ remote_expr({server}, {string} [, {idvar}]) {only available when compiled with the |+clientserver| feature} Note: Any errors will cause a local error message to be issued and the result will be the empty string. + + Variables will be evaluated in the global namespace, + independent of a function currently being active. Except + when in debug mode, then local function variables and + arguments can be evaluated. + Examples: > :echo remote_expr("gvim", "2+2") :echo remote_expr("gvim1", "b:current_syntax") @@ -6135,20 +6356,18 @@ rpcstart({prog}[, {argv}]) {Nvim} *rpcstart()* :let id = jobstart(['prog', 'arg1', 'arg2'], {'rpc': v:true}) rpcstop({channel}) {Nvim} *rpcstop()* - Closes an |RPC| {channel}. If the channel is a job - started with |jobstart()| the job is killed. - It is better to use |jobstop()| in this case, or use - |jobclose|(id, "rpc") to only close the channel without - killing the job. - Closes the socket connection if the channel was opened by - connecting to |v:servername|. - -screenattr(row, col) *screenattr()* - Like screenchar(), but return the attribute. This is a rather + Deprecated. This function was used to stop a job with |rpc| + channel, and additionally closed rpc sockets. Instead use + |jobstop()| to stop any job, and |chanclose|(id, "rpc") to close + rpc communication without stopping the job. Use |chanclose|(id) + to close any socket. + +screenattr({row}, {col}) *screenattr()* + Like |screenchar()|, but return the attribute. This is a rather arbitrary number that can only be used to compare to the attribute at other positions. -screenchar(row, col) *screenchar()* +screenchar({row}, {col}) *screenchar()* The result is a Number, which is the character at position [row, col] on the screen. This works for every possible screen position, also status lines, window separators and the @@ -6204,7 +6423,7 @@ search({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *search()* flag. 'ignorecase', 'smartcase' and 'magic' are used. - + When the 'z' flag is not given, searching always starts in column zero and then matches before the cursor are skipped. When the 'c' flag is present in 'cpo' the next search starts @@ -6419,11 +6638,32 @@ serverlist() *serverlist()* nvim --cmd "echo serverlist()" --cmd "q" < serverstart([{address}]) *serverstart()* - Opens a named pipe or TCP socket at {address} for clients to - connect to and returns {address}. If no address is given, it - is equivalent to: > + Opens a socket or named pipe at {address} and listens for + |RPC| messages. Clients can send |API| commands to the address + to control Nvim. Returns the address string. + + If {address} does not contain a colon ":" it is interpreted as + a named pipe or Unix domain socket path. + + Example: > + if has('win32') + call serverstart('\\.\pipe\nvim-pipe-1234') + else + call serverstart('nvim.sock') + endif +< + If {address} contains a colon ":" it is interpreted as a TCP + address where the last ":" separates the host and port. + Assigns a random port if it is empty or 0. Supports IPv4/IPv6. + + Example: > + :call serverstart('::1:12345') +< + If no address is given, it is equivalent to: > :call serverstart(tempname()) + < |$NVIM_LISTEN_ADDRESS| is set to {address} if not already set. + *--servername* The Vim command-line option `--servername` can be imitated: > nvim --cmd "let g:server_addr = serverstart('foo')" @@ -6520,7 +6760,7 @@ setline({lnum}, {text}) *setline()* setloclist({nr}, {list} [, {action}[, {what}]]) *setloclist()* Create or replace or add to the location list for window {nr}. - {nr} can be the window number or the window ID. + {nr} can be the window number or the |window-ID|. When {nr} is zero the current window is used. For a location list window, the displayed location list is @@ -6651,13 +6891,13 @@ setqflist({list} [, {action}[, {what}]]) *setqflist()* This function can be used to create a quickfix list independent of the 'errorformat' setting. Use a command like - ":cc 1" to jump to the first position. + `:cc 1` to jump to the first position. *setreg()* setreg({regname}, {value} [, {options}]) Set the register {regname} to {value}. - {value} may be any value returned by |getreg()|, including + {value} may be any value returned by |getreg()|, including a |List|. If {options} contains "a" or {regname} is upper case, then the value is appended. @@ -6669,16 +6909,18 @@ setreg({regname}, {value} [, {options}]) used as the width of the selection - if it is not specified then the width of the block is set to the number of characters in the longest line (counting a <Tab> as 1 character). + If {options} contains "u" or '"', then the unnamed register is + set to point to register {regname}. If {options} contains no register settings, then the default - is to use character mode unless {value} ends in a <NL> for - string {value} and linewise mode for list {value}. Blockwise + is to use character mode unless {value} ends in a <NL> for + string {value} and linewise mode for list {value}. Blockwise mode is never selected automatically. Returns zero for success, non-zero for failure. *E883* - Note: you may not use |List| containing more than one item to - set search and expression registers. Lists containing no + Note: you may not use |List| containing more than one item to + set search and expression registers. Lists containing no items act like empty strings. Examples: > @@ -6712,7 +6954,7 @@ settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()* {val}. Tabs are numbered starting with one. For the current tabpage use |setwinvar()|. - {winnr} can be the window number or the window ID. + {winnr} can be the window number or the |window-ID|. When {winnr} is zero the current window is used. This also works for a global or local buffer option, but it doesn't work for a global or local buffer variable. @@ -6813,10 +7055,30 @@ sinh({expr}) *sinh()* :echo sinh(-0.9) < -1.026517 +sockconnect({mode}, {address}, {opts}) *sockconnect()* + Connect a socket to an address. If {mode} is "pipe" then + {address} should be the path of a named pipe. If {mode} is + "tcp" then {address} should be of the form "host:port" where + the host should be an ip adderess or host name, and port the + port number. + + Returns a |channel| ID. Close the socket with |chanclose()|. + Use |chansend()| to send data over a bytes socket, and + |rpcrequest()| and |rpcnotify()| to communicate with a RPC + socket. + + {opts} is a dictionary with these keys: + |on_data| : callback invoked when data was read from socket + data_buffered : read data from socket in |buffered| mode. + rpc : If set, |msgpack-rpc| will be used to communicate + over the socket. + Returns: + - The channel ID on success (greater than zero) + - 0 on invalid arguments or connection failure. sort({list} [, {func} [, {dict}]]) *sort()* *E702* Sort the items in {list} in-place. Returns {list}. - + If you want a list to remain unmodified make a copy first: > :let sortedlist = sort(copy(mylist)) @@ -6827,7 +7089,7 @@ sort({list} [, {func} [, {dict}]]) *sort()* *E702* When {func} is given and it is '1' or 'i' then case is ignored. - + When {func} is given and it is 'n' then all items will be sorted numerical (Implementation detail: This uses the strtod() function to parse numbers, Strings, Lists, Dicts and @@ -6963,6 +7225,27 @@ sqrt({expr}) *sqrt()* "nan" may be different, it depends on system libraries. +stdioopen({opts}) *stdioopen()* + In a nvim launched with the |--headless| option, this opens + stdin and stdout as a |channel|. This function can only be + invoked once per instance. See |channel-stdio| for more + information and examples. Note that stderr is not handled by + this function, see |v:stderr|. + + Returns a |channel| ID. Close the stdio descriptors with |chanclose()|. + Use |chansend()| to send data to stdout, and + |rpcrequest()| and |rpcnotify()| to communicate over RPC. + + {opts} is a dictionary with these keys: + |on_stdin| : callback invoked when stdin is written to. + stdin_buffered : read stdin in |buffered| mode. + rpc : If set, |msgpack-rpc| will be used to communicate + over stdio + Returns: + - The channel ID on success (this is always 1) + - 0 on invalid arguments + + str2float({expr}) *str2float()* Convert String {expr} to a Float. This mostly works the same as when using a floating point number in an expression, see @@ -6997,7 +7280,7 @@ strchars({expr} [, {skipcc}]) *strchars()* counted separately. When {skipcc} set to 1, Composing characters are ignored. Also see |strlen()|, |strdisplaywidth()| and |strwidth()|. - + {skipcc} is only available after 7.4.755. For backward compatibility, you can define a wrapper function: > if has("patch-7.4.755") @@ -7014,15 +7297,15 @@ strchars({expr} [, {skipcc}]) *strchars()* endfunction endif < -strcharpart({src}, {start}[, {len}]) *strcharpart()* +strcharpart({src}, {start} [, {len}]) *strcharpart()* Like |strpart()| but using character index and length instead of byte index and length. When a character index is used where a character does not - exist it is assumed to be one byte. For example: > + exist it is assumed to be one character. For example: > strcharpart('abc', -1, 2) < results in 'a'. -strdisplaywidth({expr}[, {col}]) *strdisplaywidth()* +strdisplaywidth({expr} [, {col}]) *strdisplaywidth()* The result is a Number, which is the number of display cells String {expr} occupies on the screen when it starts at {col}. When {col} is omitted zero is used. Otherwise it is the @@ -7111,7 +7394,7 @@ strlen({expr}) The result is a Number, which is the length of the String |strchars()|. Also see |len()|, |strdisplaywidth()| and |strwidth()|. -strpart({src}, {start}[, {len}]) *strpart()* +strpart({src}, {start} [, {len}]) *strpart()* The result is a String, which is part of {src}, starting from byte {start}, with the byte length {len}. To count characters instead of bytes use |strcharpart()|. @@ -7163,7 +7446,7 @@ strwidth({expr}) *strwidth()* Ambiguous, this function's return value depends on 'ambiwidth'. Also see |strlen()|, |strdisplaywidth()| and |strchars()|. -submatch({nr}[, {list}]) *submatch()* +submatch({nr} [, {list}]) *submatch()* *E935* Only for an expression in a |:substitute| command or substitute() function. Returns the {nr}'th submatch of the matched text. When {nr} @@ -7172,14 +7455,17 @@ submatch({nr}[, {list}]) *submatch()* multi-line match or a NUL character in the text. Also see |sub-replace-expression|. - If {list} is present and non-zero then submatch() returns - a list of strings, similar to |getline()| with two arguments. + If {list} is present and non-zero then submatch() returns + a list of strings, similar to |getline()| with two arguments. NL characters in the text represent NUL characters in the text. Only returns more than one item for |:substitute|, inside |substitute()| this list will always contain one or zero items, since there are no real line breaks. + When substitute() is used recursively only the submatches in + the current (deepest) call can be obtained. + Example: > :s/\d\+/\=submatch(0) + 1/ < This finds the first number in the line and adds one to it. @@ -7190,7 +7476,7 @@ substitute({expr}, {pat}, {sub}, {flags}) *substitute()* the first match of {pat} is replaced with {sub}. When {flags} is "g", all matches of {pat} in {expr} are replaced. Otherwise {flags} should be "". - + This works like the ":substitute" command (without any flags). But the matching with {pat} is always done like the 'magic' option is set and 'cpoptions' is empty (to make scripts @@ -7378,16 +7664,16 @@ systemlist({cmd} [, {input} [, {keepempty}]]) *systemlist()* output separated by NL) with NULs transformed into NLs. Output is the same as |readfile()| will output with {binary} argument set to "b", except that a final newline is not preserved, - unless {keepempty} is present and it's non-zero. + unless {keepempty} is non-zero. + Note that on MS-Windows you may get trailing CR characters. - Returns an empty string on error, so be careful not to run - into |E706|. + Returns an empty string on error. tabpagebuflist([{arg}]) *tabpagebuflist()* The result is a |List|, where each item is the number of the buffer associated with each window in the current tab page. - {arg} specifies the number of tab page to be used. When + {arg} specifies the number of the tab page to be used. When omitted the current tab page is used. When {arg} is invalid the number zero is returned. To get a list of all buffers in all tabs use this: > @@ -7424,8 +7710,13 @@ tagfiles() Returns a |List| with the file names used to search for tags for the current buffer. This is the 'tags' option expanded. -taglist({expr}) *taglist()* +taglist({expr} [, {filename}]) *taglist()* Returns a list of tags matching the regular expression {expr}. + + If {filename} is passed it is used to prioritize the results + in the same way that |:tselect| does. See |tag-priority|. + {filename} should be the full path of the file. + Each list item is a dictionary with at least the following entries: name Name of the tag. @@ -7448,7 +7739,7 @@ taglist({expr}) *taglist()* may appear, they give the name of the entity the tag is contained in. - The ex-command 'cmd' can be either an ex search pattern, a + The ex-command "cmd" can be either an ex search pattern, a line number or a line number followed by a byte number. If there are no matching tags, then an empty list is returned. @@ -7483,7 +7774,7 @@ termopen({cmd}[, {opts}]) {Nvim} *termopen()* and `$TERM` is set to "xterm-256color". Returns the same values as |jobstart()|. - See |terminal-emulator| for more information. + See |terminal| for more information. test_garbagecollect_now() *test_garbagecollect_now()* Like garbagecollect(), but executed right away. This must @@ -7513,7 +7804,36 @@ tanh({expr}) *tanh()* < -0.761594 - *timer_start()* + *timer_info()* +timer_info([{id}]) + Return a list with information about timers. + When {id} is given only information about this timer is + returned. When timer {id} does not exist an empty list is + returned. + When {id} is omitted information about all timers is returned. + + For each timer the information is stored in a Dictionary with + these items: + "id" the timer ID + "time" time the timer was started with + "repeat" number of times the timer will still fire; + -1 means forever + "callback" the callback + +timer_pause({timer}, {paused}) *timer_pause()* + Pause or unpause a timer. A paused timer does not invoke its + callback when its time expires. Unpausing a timer may cause + the callback to be invoked almost immediately if enough time + has passed. + + Pausing a timer is useful to avoid the callback to be called + for a short time. + + If {paused} evaluates to a non-zero Number or a non-empty + String, then the timer is paused, otherwise it is unpaused. + See |non-zero-arg|. + + *timer_start()* *timer* *timers* timer_start({time}, {callback} [, {options}]) Create a timer and return the timer ID. @@ -7522,13 +7842,14 @@ timer_start({time}, {callback} [, {options}]) busy or Vim is not waiting for input the time will be longer. {callback} is the function to call. It can be the name of a - function or a Funcref. It is called with one argument, which + function or a |Funcref|. It is called with one argument, which is the timer ID. The callback is only invoked when Vim is waiting for input. {options} is a dictionary. Supported entries: "repeat" Number of times to repeat calling the - callback. -1 means forever. + callback. -1 means forever. When not present + the callback will be called once. Example: > func MyHandler(timer) @@ -7538,12 +7859,16 @@ timer_start({time}, {callback} [, {options}]) \ {'repeat': 3}) < This will invoke MyHandler() three times at 500 msec intervals. - {only available when compiled with the |+timers| feature} timer_stop({timer}) *timer_stop()* Stop a timer. The timer callback will no longer be invoked. {timer} is an ID returned by timer_start(), thus it must be a - Number. + Number. If {timer} does not exist there is no error. + +timer_stopall() *timer_stopall()* + Stop all timers. The timer callbacks will no longer be + invoked. Useful if some timers is misbehaving. If there are + no timers there is no error. tolower({expr}) *tolower()* The result is a copy of the String given, with all uppercase @@ -7633,7 +7958,7 @@ undotree() *undotree()* "save_last" Number of the last file write. Zero when no write yet. "save_cur" Number of the current position in the undo - tree. + tree. "synced" Non-zero when the last undo block was synced. This happens when waiting from input from the user. See |undo-blocks|. @@ -7745,11 +8070,11 @@ wildmenumode() *wildmenumode()* win_findbuf({bufnr}) *win_findbuf()* - Returns a list with window IDs for windows that contain buffer - {bufnr}. When there is none the list is empty. + Returns a list with |window-ID|s for windows that contain + buffer {bufnr}. When there is none the list is empty. win_getid([{win} [, {tab}]]) *win_getid()* - Get the window ID for the specified window. + Get the |window-ID| for the specified window. When {win} is missing use the current window. With {win} this is the window number. The top window has number 1. @@ -7774,7 +8099,7 @@ win_id2win({expr}) *win_id2win()* *winbufnr()* winbufnr({nr}) The result is a Number, which is the number of the buffer associated with window {nr}. {nr} can be the window number or - the window ID. + the |window-ID|. When {nr} is zero, the number of the buffer in the current window is returned. When window {nr} doesn't exist, -1 is returned. @@ -7788,10 +8113,11 @@ wincol() The result is a Number, which is the virtual column of the winheight({nr}) *winheight()* The result is a Number, which is the height of window {nr}. - {nr} can be the window number or the window ID. + {nr} can be the window number or the |window-ID|. When {nr} is zero, the height of the current window is returned. When window {nr} doesn't exist, -1 is returned. An existing window always has a height of zero or more. + This excludes any window toolbar line. Examples: > :echo "The current window has " . winheight(0) . " lines." < @@ -7814,7 +8140,7 @@ winnr([{arg}]) The result is a Number, which is the number of the current is returned. The number can be used with |CTRL-W_w| and ":wincmd w" |:wincmd|. - Also see |tabpagewinnr()|. + Also see |tabpagewinnr()| and |win_getid()|. *winrestcmd()* winrestcmd() Returns a sequence of |:resize| commands that should restore @@ -7868,7 +8194,7 @@ winsaveview() Returns a |Dictionary| that contains information to restore winwidth({nr}) *winwidth()* The result is a Number, which is the width of window {nr}. - {nr} can be the window number or the window ID. + {nr} can be the window number or the |window-ID|. When {nr} is zero, the width of the current window is returned. When window {nr} doesn't exist, -1 is returned. An existing window always has a width of zero or more. @@ -7877,7 +8203,10 @@ winwidth({nr}) *winwidth()* :if winwidth(0) <= 50 : exe "normal 50\<C-W>|" :endif -< +< For getting the terminal or screen size, see the 'columns' + option. + + wordcount() *wordcount()* The result is a dictionary of byte/chars/word statistics for the current buffer. This is the same info as provided by @@ -7913,6 +8242,12 @@ writefile({list}, {fname} [, {flags}]) appended to the file: > :call writefile(["foo"], "event.log", "a") :call writefile(["bar"], "event.log", "a") +< + When {flags} contains "S" fsync() call is not used, with "s" + it is used, 'fsync' option applies by default. No fsync() + means that writefile() will finish faster, but writes may be + left in OS buffers and not yet written to disk. Such changes + will disappear if system crashes before OS does writing. All NL characters are replaced with a NUL character. Inserting CR characters needs to be done before passing {list} @@ -7942,11 +8277,11 @@ There are four types of features: :if has("cindent") 2. Features that are only supported when certain conditions have been met. Example: > - :if has("gui_running") + :if has("win32") < *has-patch* -3. {Nvim} version. The "nvim-1.2.3" feature means that the Nvim version is - 1.2.3 or later. Example: > - :if has("nvim-1.2.3") +3. Nvim version. The "nvim-0.2.1" feature means that the Nvim version is + 0.2.1 or later. Example: > + :if has("nvim-0.2.1") < 4. Included patches. The "patch123" feature means that patch 123 has been included. Note that this form does not check the version of Vim, you need @@ -7977,17 +8312,14 @@ browse Compiled with |:browse| support, and browse() will browsefilter Compiled with support for |browsefilter|. byte_offset Compiled with support for 'o' in 'statusline' cindent Compiled with 'cindent' support. -clientserver Compiled with remote invocation support |clientserver|. clipboard Compiled with 'clipboard' support. cmdline_compl Compiled with |cmdline-completion| support. cmdline_hist Compiled with |cmdline-history| support. cmdline_info Compiled with 'showcmd' and 'ruler' support. comments Compiled with |'comments'| support. -compatible Compiled to be very Vi compatible. cscope Compiled with |cscope| support. debug Compiled with "DEBUG" defined. dialog_con Compiled with console dialog support. -dialog_gui Compiled with GUI dialog support. digraphs Compiled with support for digraphs. eval Compiled with expression evaluation support. Always true, of course! @@ -8005,9 +8337,6 @@ fname_case Case in file names matters (for Windows this is not present). folding Compiled with |folding| support. gettext Compiled with message translation |multi-lang| -gui Compiled with GUI enabled. -gui_running Vim is running in the GUI, or it will start soon. -gui_win32 Compiled with MS Windows Win32 GUI. iconv Can use iconv() for conversion. insert_expand Compiled with support for CTRL-X expansion commands in Insert mode. @@ -8022,8 +8351,7 @@ lispindent Compiled with support for lisp indenting. listcmds Compiled with commands for the buffer list |:files| and the argument list |arglist|. localmap Compiled with local mappings and abbr. |:map-local| -mac Macintosh version of Vim. -macunix Macintosh version of Vim, using Unix files (OS-X). +mac macOS version of Nvim. menu Compiled with support for |:menu|. mksession Compiled with support for |:mksession|. modify_fname Compiled with file name modifiers. |filename-modifiers| @@ -8031,17 +8359,16 @@ mouse Compiled with support mouse. mouseshape Compiled with support for 'mouseshape'. multi_byte Compiled with support for 'encoding' multi_byte_encoding 'encoding' is set to a multi-byte encoding. -multi_byte_ime Compiled with support for IME input method. multi_lang Compiled with support for multiple languages. +num64 Compiled with 64-bit |Number| support. nvim This is Nvim. |has-patch| -ole Compiled with OLE automation support for Win32. path_extra Compiled with up/downwards search in 'path' and 'tags' persistent_undo Compiled with support for persistent undo history. postscript Compiled with PostScript file printing. printer Compiled with |:hardcopy| support. profile Compiled with |:profile| support. -python Compiled with Python 2.x interface. |has-python| -python3 Compiled with Python 3.x interface. |has-python| +python Legacy Vim Python 2.x API is available. |has-python| +python3 Legacy Vim Python 3.x API is available. |has-python| quickfix Compiled with |quickfix| support. reltime Compiled with |reltime()| support. rightleft Compiled with 'rightleft' support. @@ -8064,15 +8391,14 @@ tag_old_static Compiled with support for old static tags |tag-old-static|. tag_any_white Compiled with support for any white characters in tags files |tag-any-white|. -terminfo Compiled with terminfo instead of termcap. termresponse Compiled with support for |t_RV| and |v:termresponse|. textobjects Compiled with support for |text-objects|. -tgetent Compiled with tgetent support, able to use a termcap - or terminfo file. timers Compiled with |timer_start()| support. title Compiled with window title support |'title'|. -toolbar Compiled with support for |gui-toolbar|. +ttyin input is a terminal (tty) +ttyout output is a terminal (tty) unix Unix version of Vim. +unnamedplus Compiled with support for "unnamedplus" in 'clipboard' user_commands User-defined commands. vertsplit Compiled with vertically split windows |:vsplit|. vim_starting True while initial source'ing takes place. |startup| @@ -8085,17 +8411,9 @@ vreplace Compiled with |gR| and |gr| commands. wildignore Compiled with 'wildignore' option. wildmenu Compiled with 'wildmenu' option. win32 Windows version of Vim (32 or 64 bit). -win32unix Windows version of Vim, using Unix files (Cygwin). -win64 Windows version of Vim (64 bit). winaltkeys Compiled with 'winaltkeys' option. windows Compiled with support for more than one window. writebackup Compiled with 'writebackup' default on. -xfontset Compiled with X fontset support |xfontset|. -xim Compiled with X input method support |xim|. -xpm Compiled with pixmap support. -xpm_w32 Compiled with pixmap support for Win32. (Only for - backward compatibility. Use "xpm" instead.) -x11 Compiled with X11 support. *string-match* Matching a pattern in a String @@ -8166,13 +8484,16 @@ See |:verbose-cmd| for more information. *E124* *E125* *E853* *E884* :fu[nction][!] {name}([arguments]) [range] [abort] [dict] [closure] - Define a new function by the name {name}. The name - must be made of alphanumeric characters and '_', and - must start with a capital or "s:" (see above). Note - that using "b:" or "g:" is not allowed. (since patch - 7.4.260 E884 is given if the function name has a colon - in the name, e.g. for "foo:bar()". Before that patch - no error was given). + Define a new function by the name {name}. The body of + the function follows in the next lines, until the + matching |:endfunction|. + + The name must be made of alphanumeric characters and + '_', and must start with a capital or "s:" (see + above). Note that using "b:" or "g:" is not allowed. + (since patch 7.4.260 E884 is given if the function + name has a colon in the name, e.g. for "foo:bar()". + Before that patch no error was given). {name} can also be a |Dictionary| entry that is a |Funcref|: > @@ -8220,7 +8541,7 @@ See |:verbose-cmd| for more information. : let x += 1 : return x : endfunction - : return function('Bar') + : return funcref('Bar') :endfunction :let F = Foo() @@ -8287,9 +8608,10 @@ to the number of named arguments. When using "...", the number of arguments may be larger. It is also possible to define a function without any arguments. You must -still supply the () then. The body of the function follows in the next lines, -until the matching |:endfunction|. It is allowed to define another function -inside a function body. +still supply the () then. + +It is allowed to define another function inside a function +body. *local-variables* Inside a function local variables can be used. These will disappear when the @@ -8567,6 +8889,11 @@ This does NOT work: > value and the global value are changed. Example: > :let &path = &path . ',/usr/local/include' +< This also works for terminal codes in the form t_xx. + But only for alphanumerical names. Example: > + :let &t_k1 = "\<Esc>[234;" +< When the code does not exist yet it will be created as + a terminal key code, there is no error. :let &{option-name} .= {expr1} For a string option: Append {expr1} to the value. @@ -10139,7 +10466,7 @@ code can be used: > redir => scriptnames_output silent scriptnames redir END - + " Split the output into lines and parse each line. Add an entry to the " "scripts" dictionary. let scripts = {} @@ -10176,6 +10503,22 @@ missing: > : echo "You will _never_ see this message" :endif +To execute a command only when the |+eval| feature is disabled requires a trick, +as this example shows: > + if 1 + nnoremap : :" + endif + normal :set history=111<CR> + if 1 + nunmap : + endif + +The "<CR>" here is a real CR character, type CTRL-V Enter to get it. + +When the |+eval| feature is available the ":" is remapped to add a double +quote, which has the effect of commenting-out the command. without the +|+eval| feature the nnoremap command is skipped and the command is executed. + ============================================================================== 11. The sandbox *eval-sandbox* *sandbox* *E48* diff --git a/runtime/doc/farsi.txt b/runtime/doc/farsi.txt index b85c0a357c..a824c469b0 100644 --- a/runtime/doc/farsi.txt +++ b/runtime/doc/farsi.txt @@ -1,4 +1,4 @@ -*farsi.txt* For Vim version 7.4. Last change: 2010 Aug 07 +*farsi.txt* Nvim VIM REFERENCE MANUAL by Mortaza Ghassab Shiran diff --git a/runtime/doc/filetype.txt b/runtime/doc/filetype.txt index d15815191e..78402b47fe 100644 --- a/runtime/doc/filetype.txt +++ b/runtime/doc/filetype.txt @@ -1,4 +1,4 @@ -*filetype.txt* For Vim version 7.4. Last change: 2016 Jun 20 +*filetype.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -6,12 +6,10 @@ Filetypes *filetype* *file-type* -1. Filetypes |filetypes| -2. Filetype plugin |filetype-plugins| -3. Docs for the default filetype plugins. |ftplugin-docs| - Also see |autocmd.txt|. + Type |gO| to see the table of contents. + ============================================================================== 1. Filetypes *filetypes* *file-types* @@ -34,7 +32,7 @@ Detail: The ":filetype on" command will load one of these files: BufNewFile and BufRead events. If the file type is not found by the name, the file $VIMRUNTIME/scripts.vim is used to detect it from the contents of the file. - When the GUI is running or will start soon, the menu.vim script is + When the GUI is running or will start soon, the |menu.vim| script is also sourced. See |'go-M'| about avoiding that. To add your own file types, see |new-filetype| below. To search for help on a @@ -311,12 +309,12 @@ define yourself. There are a few ways to avoid this: You need to define your own mapping before the plugin is loaded (before editing a file of that type). The plugin will then skip installing the default mapping. - + *no_mail_maps* 3. Disable defining mappings for a specific filetype by setting a variable, which contains the name of the filetype. For the "mail" filetype this would be: > :let no_mail_maps = 1 - +< *no_plugin_maps* 4. Disable defining mappings for all filetypes by setting a variable: > :let no_plugin_maps = 1 < @@ -542,6 +540,7 @@ K or CTRL-] Jump to the manpage for the <cWORD> under the cursor. Takes a count for the section. CTRL-T Jump back to the location that the manpage was opened from. +gO Show the manpage outline. |gO| q :quit if invoked as $MANPAGER, otherwise :close. Variables: @@ -565,6 +564,17 @@ These maps can be disabled with > :let g:no_pdf_maps = 1 < +PYTHON *ft-python-plugin* *PEP8* + +By default the following options are set, in accordance with PEP8: > + + setlocal expandtab shiftwidth=4 softtabstop=4 tabstop=8 + +To disable this behaviour, set the following variable in your vimrc: > + + let g:python_recommended_style = 0 + + RPM SPEC *ft-spec-plugin* Since the text for this plugin is rather long it has been put in a separate @@ -714,6 +724,12 @@ Format description: not recognized here as well. +RUST *ft-rust* + +Since the text for this plugin is rather long it has been put in a separate +file: |ft_rust.txt|. + + SQL *ft-sql* Since the text for this plugin is rather long it has been put in a separate diff --git a/runtime/doc/fold.txt b/runtime/doc/fold.txt index 680e3270f2..c644d63280 100644 --- a/runtime/doc/fold.txt +++ b/runtime/doc/fold.txt @@ -1,4 +1,4 @@ -*fold.txt* For Vim version 7.4. Last change: 2016 Jan 02 +*fold.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -9,10 +9,7 @@ Folding *Folding* *folding* *folds* You can find an introduction on folding in chapter 28 of the user manual. |usr_28.txt| -1. Fold methods |fold-methods| -2. Fold commands |fold-commands| -3. Fold options |fold-options| -4. Behavior of folds |fold-behavior| + Type |gO| to see the table of contents. ============================================================================== 1. Fold methods *fold-methods* @@ -61,7 +58,7 @@ whichever is lower. These are empty or white lines and lines starting with a character in 'foldignore'. White space is skipped before checking for characters in 'foldignore'. For C use "#" to ignore preprocessor lines. -When you want to ignore lines in another way, use the 'expr' method. The +When you want to ignore lines in another way, use the "expr" method. The |indent()| function can be used in 'foldexpr' to get the indent of a line. @@ -76,7 +73,7 @@ This will call a function to compute the fold level: > :set foldexpr=MyFoldLevel(v:lnum) This will make a fold out of paragraphs separated by blank lines: > :set foldexpr=getline(v:lnum)=~'^\\s*$'&&getline(v:lnum+1)=~'\\S'?'<1':1 -this does the same: > +This does the same: > :set foldexpr=getline(v:lnum-1)=~'^\\s*$'&&getline(v:lnum)=~'\\S'?'>1':1 Note that backslashes must be used to escape characters that ":set" handles @@ -136,7 +133,7 @@ fold level. But note that foldlevel() may return -1 if the level is not known yet. And it returns the level at the start of the line, while a fold might end in that line. -It may happened that folds are not updated properly. You can use |zx| or |zX| +It may happen that folds are not updated properly. You can use |zx| or |zX| to force updating folds. @@ -200,7 +197,7 @@ and the level given by the marker: 1. If a marker with the same fold level is encountered, the previous fold ends and another fold with the same level starts. 2. If a marker with a higher fold level is found, a nested fold is started. -3. if a marker with a lower fold level is found, all folds up to and including +3. If a marker with a lower fold level is found, all folds up to and including this level end and a fold with the specified level starts. The number indicates the fold level. A zero cannot be used (a marker with diff --git a/runtime/doc/ft_ada.txt b/runtime/doc/ft_ada.txt index 1e81acff67..c1aa0904c4 100644 --- a/runtime/doc/ft_ada.txt +++ b/runtime/doc/ft_ada.txt @@ -1,4 +1,4 @@ -*ft_ada.txt* For Vim version 7.4. Last change: 2010 Jul 20 +*ft_ada.txt* Nvim ADA FILE TYPE PLUG-INS REFERENCE MANUAL~ @@ -116,7 +116,7 @@ NOTE: "gnat xref -v" is very tricky to use as it has almost no diagnostic then "gnat xref -v *.ad?" 4) Project manager support is completely broken - don't even try "gnat xref -Padacl.gpr". -5) VIM is faster when the tags file is sorted - use "sort --unique +5) Vim is faster when the tags file is sorted - use "sort --unique --ignore-case --output=tags tags" . 6) Remember to insert "!_TAG_FILE_SORTED 2 %sort ui" as first line to mark the file assorted. diff --git a/runtime/doc/ft_rust.txt b/runtime/doc/ft_rust.txt new file mode 100644 index 0000000000..750ba76afc --- /dev/null +++ b/runtime/doc/ft_rust.txt @@ -0,0 +1,237 @@ +*ft_rust.txt* Filetype plugin for Rust + +============================================================================== +CONTENTS *rust* + +1. Introduction |rust-intro| +2. Settings |rust-settings| +3. Commands |rust-commands| +4. Mappings |rust-mappings| + +============================================================================== +INTRODUCTION *rust-intro* + +This plugin provides syntax and supporting functionality for the Rust +filetype. + +============================================================================== +SETTINGS *rust-settings* + +This plugin has a few variables you can define in your vimrc that change the +behavior of the plugin. + + *g:rustc_path* +g:rustc_path~ + Set this option to the path to rustc for use in the |:RustRun| and + |:RustExpand| commands. If unset, "rustc" will be located in $PATH: > + let g:rustc_path = $HOME."/bin/rustc" +< + + *g:rustc_makeprg_no_percent* +g:rustc_makeprg_no_percent~ + Set this option to 1 to have 'makeprg' default to "rustc" instead of + "rustc %": > + let g:rustc_makeprg_no_percent = 1 +< + + *g:rust_conceal* +g:rust_conceal~ + Set this option to turn on the basic |conceal| support: > + let g:rust_conceal = 1 +< + + *g:rust_conceal_mod_path* +g:rust_conceal_mod_path~ + Set this option to turn on |conceal| for the path connecting token + "::": > + let g:rust_conceal_mod_path = 1 +< + + *g:rust_conceal_pub* +g:rust_conceal_pub~ + Set this option to turn on |conceal| for the "pub" token: > + let g:rust_conceal_pub = 1 +< + + *g:rust_recommended_style* +g:rust_recommended_style~ + Set this option to enable vim indentation and textwidth settings to + conform to style conventions of the rust standard library (i.e. use 4 + spaces for indents and sets 'textwidth' to 99). This option is enabled + by default. To disable it: > + let g:rust_recommended_style = 0 +< + + *g:rust_fold* +g:rust_fold~ + Set this option to turn on |folding|: > + let g:rust_fold = 1 +< + Value Effect ~ + 0 No folding + 1 Braced blocks are folded. All folds are open by + default. + 2 Braced blocks are folded. 'foldlevel' is left at the + global value (all folds are closed by default). + + *g:rust_bang_comment_leader* +g:rust_bang_comment_leader~ + Set this option to 1 to preserve the leader on multi-line doc comments + using the /*! syntax: > + let g:rust_bang_comment_leader = 1 +< + + *g:ftplugin_rust_source_path* +g:ftplugin_rust_source_path~ + Set this option to a path that should be prepended to 'path' for Rust + source files: > + let g:ftplugin_rust_source_path = $HOME.'/dev/rust' +< + + *g:rustfmt_command* +g:rustfmt_command~ + Set this option to the name of the 'rustfmt' executable in your $PATH. If + not specified it defaults to 'rustfmt' : > + let g:rustfmt_command = 'rustfmt' +< + *g:rustfmt_autosave* +g:rustfmt_autosave~ + Set this option to 1 to run |:RustFmt| automatically when saving a + buffer. If not specified it defaults to 0 : > + let g:rustfmt_autosave = 0 +< + *g:rustfmt_fail_silently* +g:rustfmt_fail_silently~ + Set this option to 1 to prevent 'rustfmt' from populating the + |location-list| with errors. If not specified it defaults to 0: > + let g:rustfmt_fail_silently = 0 +< + *g:rustfmt_options* +g:rustfmt_options~ + Set this option to a string of options to pass to 'rustfmt'. The + write-mode is already set to 'overwrite'. If not specified it + defaults to '' : > + let g:rustfmt_options = '' +< + + *g:rust_playpen_url* +g:rust_playpen_url~ + Set this option to override the URL for the playpen to use: > + let g:rust_playpen_url = 'https://play.rust-lang.org/' +< + + *g:rust_shortener_url* +g:rust_shortener_url~ + Set this option to override the URL for the URL shortener: > + let g:rust_shortener_url = 'https://is.gd/' +< + + +============================================================================== +COMMANDS *rust-commands* + +:RustRun [args] *:RustRun* +:RustRun! [rustc-args] [--] [args] + Compiles and runs the current file. If it has unsaved changes, + it will be saved first using |:update|. If the current file is + an unnamed buffer, it will be written to a temporary file + first. The compiled binary is always placed in a temporary + directory, but is run from the current directory. + + The arguments given to |:RustRun| will be passed to the + compiled binary. + + If ! is specified, the arguments are passed to rustc instead. + A "--" argument will separate the rustc arguments from the + arguments passed to the binary. + + If |g:rustc_path| is defined, it is used as the path to rustc. + Otherwise it is assumed rustc can be found in $PATH. + +:RustExpand [args] *:RustExpand* +:RustExpand! [TYPE] [args] + Expands the current file using --pretty and displays the + results in a new split. If the current file has unsaved + changes, it will be saved first using |:update|. If the + current file is an unnamed buffer, it will be written to a + temporary file first. + + The arguments given to |:RustExpand| will be passed to rustc. + This is largely intended for specifying various --cfg + configurations. + + If ! is specified, the first argument is the expansion type to + pass to rustc --pretty. Otherwise it will default to + "expanded". + + If |g:rustc_path| is defined, it is used as the path to rustc. + Otherwise it is assumed rustc can be found in $PATH. + +:RustEmitIr [args] *:RustEmitIr* + Compiles the current file to LLVM IR and displays the results + in a new split. If the current file has unsaved changes, it + will be saved first using |:update|. If the current file is an + unnamed buffer, it will be written to a temporary file first. + + The arguments given to |:RustEmitIr| will be passed to rustc. + + If |g:rustc_path| is defined, it is used as the path to rustc. + Otherwise it is assumed rustc can be found in $PATH. + +:RustEmitAsm [args] *:RustEmitAsm* + Compiles the current file to assembly and displays the results + in a new split. If the current file has unsaved changes, it + will be saved first using |:update|. If the current file is an + unnamed buffer, it will be written to a temporary file first. + + The arguments given to |:RustEmitAsm| will be passed to rustc. + + If |g:rustc_path| is defined, it is used as the path to rustc. + Otherwise it is assumed rustc can be found in $PATH. + +:RustPlay *:RustPlay* + This command will only work if you have web-api.vim installed + (available at https://github.com/mattn/webapi-vim). It sends the + current selection, or if nothing is selected, the entirety of the + current buffer to the Rust playpen, and emits a message with the + shortened URL to the playpen. + + |g:rust_playpen_url| is the base URL to the playpen, by default + "https://play.rust-lang.org/". + + |g:rust_shortener_url| is the base URL for the shortener, by + default "https://is.gd/" + +:RustFmt *:RustFmt* + Runs |g:rustfmt_command| on the current buffer. If + |g:rustfmt_options| is set then those will be passed to the + executable. + + If |g:rustfmt_fail_silently| is 0 (the default) then it + will populate the |location-list| with the errors from + |g:rustfmt_command|. If |g:rustfmt_fail_silently| is set to 1 + then it will not populate the |location-list|. + +:RustFmtRange *:RustFmtRange* + Runs |g:rustfmt_command| with selected range. See + |:RustFmt| for any other information. + +============================================================================== +MAPPINGS *rust-mappings* + +This plugin defines mappings for |[[| and |]]| to support hanging indents. + +It also has a few other mappings: + + *rust_<D-r>* +<D-r> Executes |:RustRun| with no arguments. + Note: This binding is only available in MacVim. + + *rust_<D-R>* +<D-R> Populates the command line with |:RustRun|! using the + arguments given to the last invocation, but does not + execute it. + Note: This binding is only available in MacVim. + +============================================================================== + vim:tw=78:sw=4:noet:ts=8:ft=help:norl: diff --git a/runtime/doc/ft_sql.txt b/runtime/doc/ft_sql.txt index 75c55269ef..29268f5753 100644 --- a/runtime/doc/ft_sql.txt +++ b/runtime/doc/ft_sql.txt @@ -1,4 +1,4 @@ -*ft_sql.txt* For Vim version 7.4. Last change: 2013 May 15 +*ft_sql.txt* Nvim by David Fishburn diff --git a/runtime/doc/gui.txt b/runtime/doc/gui.txt index 1e8bb408d9..904c4be19c 100644 --- a/runtime/doc/gui.txt +++ b/runtime/doc/gui.txt @@ -1,4 +1,4 @@ -*gui.txt* For Vim version 7.4. Last change: 2014 Mar 08 +*gui.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -6,34 +6,17 @@ Vim's Graphical User Interface *gui* *GUI* -1. Starting the GUI |gui-start| -2. Scrollbars |gui-scrollbars| -3. Mouse Control |gui-mouse| -4. Making GUI Selections |gui-selections| -5. Menus |menus| -6. Extras |gui-extras| - -Other GUI documentation: -|gui_w32.txt| For specific items of the Win32 GUI. + Type |gO| to see the table of contents. ============================================================================== 1. Starting the GUI *gui-start* *E229* *E233* -First you must make sure you actually have a version of Vim with the GUI code -included. - -How to start the GUI depends on the system used. Mostly you can run the -GUI version of Vim with: - gvim [options] [files...] - *ginit.vim* *gui-init* *gvimrc* *$MYGVIMRC* The gvimrc file is where GUI-specific startup commands should be placed. It is always sourced after the |init.vim| file. If you have one then the $MYGVIMRC environment variable has its name. When the GUI starts up initializations are carried out, in this order: -- The 'term' option is set to "builtin_gui" and terminal options are reset to - their default value for the GUI |terminal-options|. - If the system menu file exists, it is sourced. The name of this file is normally "$VIMRUNTIME/menu.vim". You can check this with ":version". Also see |$VIMRUNTIME|. To skip loading the system menu include 'M' in @@ -63,7 +46,8 @@ When the GUI starts up initializations are carried out, in this order: already set. NOTE: All but the first one are not carried out if Vim was started with -"-u NONE" and no "-U" argument was given, or when started with "-U NONE". +"-u NONE" or "-u DEFAULTS" and no "-U" argument was given, or when started +with "-U NONE". All this happens AFTER the normal Vim initializations, like reading your vimrc file. See |initialization|. @@ -83,28 +67,6 @@ Recommended place for your personal GUI initializations: The personal initialization files are searched in the order specified above and only the first one that is found is read. -There are a number of options which only have meaning in the GUI version of -Vim. These are 'guicursor', 'guifont', and 'guioptions'. They are -documented in |options.txt| with all the other options. - -Another way to set the colors for different occasions is with highlight -groups. The "Normal" group is used to set the background and foreground -colors. Example (which looks nice): > - - :highlight Normal guibg=grey90 - -The "guibg" and "guifg" settings override the normal background and -foreground settings. The other settings for the Normal highlight group are -not used. Use the 'guifont' option to set the font. - -Also check out the 'guicursor' option, to set the colors for the cursor in -various modes. - -Vim tries to make the window fit on the screen when it starts up. This avoids -that you can't see part of it. On the X Window System this requires a bit of -guesswork. You can change the height that is used for the window title and a -task bar with the 'guiheadroom' option. - *:winp* *:winpos* *E188* :winp[os] Display current position of the top left corner of the GUI vim @@ -114,8 +76,7 @@ task bar with the 'guiheadroom' option. :winp[os] {X} {Y} *E466* Put the GUI vim window at the given {X} and {Y} coordinates. The coordinates should specify the position in pixels of the - top left corner of the window. Does not work in all versions. - Does work in an (new) xterm |xterm-color|. + top left corner of the window. When the GUI window has not been opened yet, the values are remembered until the window is opened. The position is adjusted to make the window fit on the screen (if possible). @@ -124,21 +85,6 @@ task bar with the 'guiheadroom' option. :win[size] {width} {height} Set the window height to {width} by {height} characters. Obsolete, use ":set lines=11 columns=22". - If you get less lines than expected, check the 'guiheadroom' - option. - -If you are running the X Window System, you can get information about the -window Vim is running in with these commands: > - :!xwininfo -id $WINDOWID - :!xprop -id $WINDOWID - :execute '!xwininfo -id ' . v:windowid - :execute '!xprop -id ' . v:windowid -< - *gui-IME* *iBus* -Input methods for international characters in X that rely on the XIM -framework, most notably iBus, have been known to produce undesirable results -in gVim. These may include an inability to enter spaces, or long delays -between typing a character and it being recognized by the application. ============================================================================== 2. Scrollbars *gui-scrollbars* @@ -437,6 +383,7 @@ menus and menu items. They are most useful for things that you can't remember what the key sequence was. For creating menus in a different language, see |:menutrans|. +If you don't want to use menus at all, see |'go-M'|. *menu.vim* The default menus are read from the file "$VIMRUNTIME/menu.vim". See @@ -453,7 +400,11 @@ in the menu (which can take a bit of time to load). If you want to have all filetypes already present at startup, add: > :let do_syntax_sel_menu = 1 -< +Note that the menu.vim is sourced when `:syntax on` or `:filetype on` is +executed or after your .vimrc file is sourced. This means that the 'encoding' +option and the language of messages (`:language messages`) must be set before +that (if you want to change them). + *console-menus* Although this documentation is in the GUI section, you can actually use menus in console mode too. You will have to load |menu.vim| explicitly then, it is @@ -545,9 +496,6 @@ expression register: > :amenu Insert.foobar "='foobar'<CR>P -Note that the '<' and 'k' flags in 'cpoptions' also apply here (when -included they make the <> form and raw key codes not being recognized). - Note that <Esc> in Cmdline mode executes the command, like in a mapping. This is Vi compatible. Use CTRL-C to quit Cmdline mode. @@ -559,21 +507,13 @@ The ":set ic" will not be echoed when using this menu. Messages from the executed command are still given though. To shut them up too, add a ":silent" in the executed command: > :menu <silent> Search.Header :exe ":silent normal /Header\r"<CR> -"<silent>" may also appear just after "<special>" or "<script>". - - *:menu-<special>* *:menu-special* -Define a menu with <> notation for special keys, even though the "<" flag -may appear in 'cpoptions'. This is useful if the side effect of setting -'cpoptions' is not desired. Example: > - :menu <special> Search.Header /Header<CR> -"<special>" must appear as the very first argument to the ":menu" command or -just after "<silent>" or "<script>". +"<silent>" may also appear just after "<script>". *:menu-<script>* *:menu-script* The "to" part of the menu will be inspected for mappings. If you don't want this, use the ":noremenu" command (or the similar one for a specific mode). If you do want to use script-local mappings, add "<script>" as the very first -argument to the ":menu" command or just after "<silent>" or "<special>". +argument to the ":menu" command or just after "<silent>". *menu-priority* You can give a priority to a menu. Menus with a higher priority go more to @@ -714,6 +654,8 @@ nr Name Normal action ~ In the Win32 GUI, starting a menu name with ']' excludes that menu from the main menu bar. You must then use the |:popup| command to display it. +When splitting the window the window toolbar is not copied to the new window. + *popup-menu* You can define the special menu "PopUp". This is the menu that is displayed when the right mouse button is pressed, if 'mousemodel' is set to popup or @@ -909,30 +851,4 @@ This section describes other features which are related to the GUI. - In the GUI, several normal keys may have modifiers in mappings etc, these are <Space>, <Tab>, <NL>, <CR>, <Esc>. -- To check in a Vim script if the GUI is being used, you can use something - like this: > - - if has("gui_running") - echo "yes, we have a GUI" - else - echo "Boring old console" - endif -< *setting-guifont* -- When you use the same vimrc file on various systems, you can use something - like this to set options specifically for each type of GUI: > - - if has("gui_running") - if has("gui_gtk2") - :set guifont=Luxi\ Mono\ 12 - elseif has("x11") - " Also for GTK 1 - :set guifont=*-lucidatypewriter-medium-r-normal-*-*-180-*-*-m-*-* - elseif has("gui_win32") - :set guifont=Luxi_Mono:h12:cANSI - endif - endif - -A recommended Japanese font is MS Mincho. You can find info here: -http://www.lexikan.com/mincho.htm - vim:tw=78:sw=4:ts=8:ft=help:norl: diff --git a/runtime/doc/hebrew.txt b/runtime/doc/hebrew.txt index 7bc8f02e7f..642d80adc7 100644 --- a/runtime/doc/hebrew.txt +++ b/runtime/doc/hebrew.txt @@ -1,4 +1,4 @@ -*hebrew.txt* For Vim version 7.4. Last change: 2007 Jun 14 +*hebrew.txt* Nvim VIM REFERENCE MANUAL by Ron Aaron (and Avner Lottem) diff --git a/runtime/doc/help.txt b/runtime/doc/help.txt index b33fb50c06..8a83cbc79c 100644 --- a/runtime/doc/help.txt +++ b/runtime/doc/help.txt @@ -1,4 +1,4 @@ -*help.txt* For Vim version 7.4. Last change: 2016 Mar 31 +*help.txt* Nvim VIM - main help file k @@ -30,7 +30,7 @@ Get specific help: It is possible to go directly to whatever you want help help entries for "word". Or use ":helpgrep word". |:helpgrep| -VIM stands for Vi IMproved. Most of VIM was made by Bram Moolenaar, but only +Vim stands for Vi IMproved. Most of Vim was made by Bram Moolenaar, but only through the help of many others. See |credits|. ------------------------------------------------------------------------------ *doc-file-list* *Q_ct* @@ -93,10 +93,9 @@ General subjects ~ |helphelp.txt| about using the help files |index.txt| alphabetical index of all commands |help-tags| all the tags you can jump to (index of tags) -|howto.txt| how to do the most common editing tasks |tips.txt| various tips on using Vim |message.txt| (error) messages and explanations -|develop.txt| development of Vim +|develop.txt| development of Nvim |debug.txt| debugging Vim itself |uganda.txt| Vim distribution conditions and what to do with your money @@ -134,7 +133,6 @@ Advanced editing ~ Special issues ~ |print.txt| printing |remote.txt| using Vim as a server or client -|term.txt| using different terminals and mice |digraph.txt| list of available digraphs |mbyte.txt| multi-byte text support |mlang.txt| non-English language support @@ -143,33 +141,29 @@ Special issues ~ |hebrew.txt| Hebrew language support and editing |russian.txt| Russian language support and editing |ft_ada.txt| Ada (the programming language) support +|ft_rust.txt| Filetype plugin for Rust |ft_sql.txt| about the SQL filetype plugin |rileft.txt| right-to-left editing mode GUI ~ |gui.txt| Graphical User Interface (GUI) -|gui_w32.txt| Win32 GUI Interfaces ~ |if_cscop.txt| using Cscope with Vim |if_pyth.txt| Python interface |if_ruby.txt| Ruby interface -|debugger.txt| Interface with a debugger |sign.txt| debugging signs Versions ~ |vim_diff.txt| Main differences between Nvim and Vim |vi_diff.txt| Main differences between Vim and Vi - *sys-file-list* -Remarks about specific systems ~ -|os_win32.txt| MS-Windows *standard-plugin-list* Standard plugins ~ |pi_gzip.txt| Reading and writing compressed files |pi_netrw.txt| Reading and writing files over a network |pi_paren.txt| Highlight matching parens +|pi_spec.txt| Filetype plugin to work with rpm spec files |pi_tar.txt| Tar file explorer -|pi_vimball.txt| Create a self-installing Vim script |pi_zip.txt| Zip archive explorer LOCAL ADDITIONS: *local-additions* diff --git a/runtime/doc/helphelp.txt b/runtime/doc/helphelp.txt index ad1611133a..adc72d1835 100644 --- a/runtime/doc/helphelp.txt +++ b/runtime/doc/helphelp.txt @@ -1,4 +1,4 @@ -*helphelp.txt* For Vim version 7.4. Last change: 2016 Apr 01 +*helphelp.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -6,9 +6,7 @@ Help on help files *helphelp* -1. Help commands |online-help| -2. Translated help files |help-translated| -3. Writing help files |help-writing| + Type |gO| to see the table of contents. ============================================================================== 1. Help commands *online-help* @@ -25,12 +23,20 @@ Help on help files *helphelp* The 'helplang' option is used to select a language, if the main help file is available in several languages. + Type |gO| to see the table of contents. + *{subject}* *E149* *E661* :h[elp] {subject} Like ":help", additionally jump to the tag {subject}. - {subject} can include wildcards like "*", "?" and + For example: > + :help options + +< {subject} can include wildcards such as "*", "?" and "[a-z]": :help z? jump to help for any "z" command :help z. jump to the help for "z." + But when a tag exists it is taken literally: + :help :? jump to help for ":?" + If there is no full match for the pattern, or there are several matches, the "best" match will be used. A sophisticated algorithm is used to decide which @@ -67,18 +73,19 @@ Help on help files *helphelp* example to find help for CTRL-V in Insert mode: > :help i^V < - To use a regexp |pattern|, first do ":help" and then + It is also possible to first do ":help" and then use ":tag {pattern}" in the help window. The ":tnext" command can then be used to jump to other matches, "tselect" to list matches and choose one. > - :help index| :tse z. + :help index + :tselect /.*mode < When there is no argument you will see matches for "help", to avoid listing all possible matches (that would be very slow). The number of matches displayed is limited to 300. - This command can be followed by '|' and another + The `:help` command can be followed by '|' and another command, but you don't need to escape the '|' inside a help command. So these both work: > :help | @@ -133,7 +140,8 @@ Help on help files *helphelp* already opened, then the location list for that window is used. Otherwise, a new help window is opened and the location list for that window is set. The - location list for the current window is not changed. + location list for the current window is not changed + then. *:exu* *:exusage* :exu[sage] Show help on Ex commands. Added to simulate the Nvi @@ -298,7 +306,7 @@ the applicable Vim version. The last field specifies the last modification date of the file. Each field is separated by a tab. At the bottom of the help file, place a Vim modeline to set the 'textwidth' -and 'tabstop' options and the 'filetype' to 'help'. Never set a global option +and 'tabstop' options and the 'filetype' to "help". Never set a global option in such a modeline, that can have consequences undesired by whoever reads that help. diff --git a/runtime/doc/howto.txt b/runtime/doc/howto.txt deleted file mode 100644 index 03ae3dbd8d..0000000000 --- a/runtime/doc/howto.txt +++ /dev/null @@ -1,96 +0,0 @@ -*howto.txt* For Vim version 7.4. Last change: 2006 Apr 02 - - - VIM REFERENCE MANUAL by Bram Moolenaar - - -How to ... *howdoi* *how-do-i* *howto* *how-to* - -|tutor| get started -|:quit| exit? I'm trapped, help me! -|initialization| initialize Vim -|vimrc-intro| write a Vim script file (vimrc) -|suspend| suspend Vim -|usr_11.txt| recover after a crash -|07.4| keep a backup of my file when writing over it - -|usr_07.txt| edit files -|23.4| edit binary files -|usr_24.txt| insert text -|deleting| delete text -|usr_04.txt| change text -|04.5| copy and move text -|usr_25.txt| format text -|30.6| format comments -|30.2| indent C programs -|25.3| automatically set indent - -|usr_26.txt| repeat commands -|02.5| undo and redo - -|usr_03.txt| move around -|word-motions| word motions -|left-right-motions| left-right motions -|up-down-motions| up-down motions -|object-motions| text-object motions -|various-motions| various motions -|object-select| text-object selection -|'whichwrap'| move over line breaks -|'virtualedit'| move to where there is no text -|usr_27.txt| specify pattern for searches -|tags-and-searches| do tags and special searches -|29.4| search in include'd files used to find - variables, functions, or macros -|K| look up manual for the keyword under cursor - -|03.7| scroll -|'sidescroll'| scroll horizontally/sideways -|'scrolloff'| set visible context lines - -|mode-switching| change modes -|04.4| use Visual mode -|'insertmode'| start Vim in Insert mode - -|40.1| map keys -|24.7| create abbreviations - -|ins-expandtab| expand a tab to spaces in Insert mode -|i_CTRL-R| insert contents of a register in Insert mode -|24.3| complete words in Insert mode -|25.1| break a line before it gets too long - -|20.1| do command-line editing -|20.3| do command-line completion -|'cmdheight'| increase the height of command-line -|10.3| specify command-line ranges -|40.3| specify commands to be executed automatically - before/after reading/writing entering/leaving a - buffer/window - -|'autowrite'| write automatically -|30.1| speedup edit-compile-edit cycle or compile and fix - errors within Vim - -|options| set options -|auto-setting| set options automatically -|term-dependent-settings| set options depending on terminal name -|save-settings| save settings -|:quote| comment my .vim files -|'helpheight'| change the default help height -|'highlight'| set various highlighting modes -|'title'| set the window title -|'icon'| set window icon title -|'report'| avoid seeing the change messages on every line -|'shortmess'| avoid |hit-enter| prompts - -|mouse-using| use mouse with Vim -|usr_08.txt| manage multiple windows and buffers -|gui.txt| use the gui - -|You can't! (yet)| do dishes using Vim - -|usr_06.txt| switch on syntax highlighting -|2html.vim| convert a colored file to HTML -|less| use Vim like less or more with syntax highlighting - - vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/if_cscop.txt b/runtime/doc/if_cscop.txt index 7482f5eebb..ac3d7a9ed8 100644 --- a/runtime/doc/if_cscop.txt +++ b/runtime/doc/if_cscop.txt @@ -1,4 +1,4 @@ -*if_cscop.txt* For Vim version 7.4. Last change: 2011 Jun 12 +*if_cscop.txt* Nvim VIM REFERENCE MANUAL by Andy Kahn @@ -12,15 +12,7 @@ a cscope query is just like jumping to any tag; it is saved on the tag stack so that with the right keyboard mappings, you can jump back and forth between functions as you normally would with |tags|. -1. Cscope introduction |cscope-intro| -2. Cscope related commands |cscope-commands| -3. Cscope options |cscope-options| -4. How to use cscope in Vim |cscope-howtouse| -5. Limitations |cscope-limitations| -6. Suggested usage |cscope-suggestions| -7. Availability & Information |cscope-info| - -This is currently for Unix and Win32 only. + Type |gO| to see the table of contents. ============================================================================== 1. Cscope introduction *cscope-intro* @@ -90,9 +82,10 @@ suggested use.) 2. Cscope related commands *cscope-commands* *:cscope* *:cs* *:scs* *:scscope* *E259* *E262* *E561* *E560* -All cscope commands are accessed through suboptions to the main cscope -command ":cscope". The shortest abbreviation is ":cs". The ":scscope" -command does the same and also splits the window (short: "scs"). +All cscope commands are accessed through suboptions to the cscope commands. + `:cscope` or `:cs` is the main command + `:scscope` or `:scs` does the same and splits the window + `:lcscope` or `:lcs` uses the location list, see |:lcscope| The available subcommands are: diff --git a/runtime/doc/if_lua.txt b/runtime/doc/if_lua.txt new file mode 100644 index 0000000000..968d882a22 --- /dev/null +++ b/runtime/doc/if_lua.txt @@ -0,0 +1,361 @@ +*if_lua.txt* Nvim + + + NVIM REFERENCE MANUAL + + +Lua Interface to Nvim *lua* *Lua* + + Type |gO| to see the table of contents. + +============================================================================== +Importing modules *lua-require* + +Nvim automatically adjusts `package.path` and `package.cpath` according to +effective 'runtimepath' value. Adjustment happens whenever 'runtimepath' is +changed. `package.path` is adjusted by simply appending `/lua/?.lua` and +`/lua/?/init.lua` to each directory from 'runtimepath' (`/` is actually the +first character of `package.config`). + +Similarly to `package.path`, modified directories from 'runtimepath' are also +added to `package.cpath`. In this case, instead of appending `/lua/?.lua` and +`/lua/?/init.lua` to each runtimepath, all unique `?`-containing suffixes of +the existing `package.cpath` are used. Example: + +1. Given that + - 'runtimepath' contains `/foo/bar,/xxx;yyy/baz,/abc`; + - initial (defined at compile-time or derived from + `$LUA_CPATH`/`$LUA_INIT`) `package.cpath` contains + `./?.so;/def/ghi/a?d/j/g.elf;/def/?.so`. +2. It finds `?`-containing suffixes `/?.so`, `/a?d/j/g.elf` and `/?.so`, in + order: parts of the path starting from the first path component containing + question mark and preceding path separator. +3. The suffix of `/def/?.so`, namely `/?.so` is not unique, as it’s the same + as the suffix of the first path from `package.path` (i.e. `./?.so`). Which + leaves `/?.so` and `/a?d/j/g.elf`, in this order. +4. 'runtimepath' has three paths: `/foo/bar`, `/xxx;yyy/baz` and `/abc`. The + second one contains semicolon which is a paths separator so it is out, + leaving only `/foo/bar` and `/abc`, in order. +5. The cartesian product of paths from 4. and suffixes from 3. is taken, + giving four variants. In each variant `/lua` path segment is inserted + between path and suffix, leaving + + - `/foo/bar/lua/?.so` + - `/foo/bar/lua/a?d/j/g.elf` + - `/abc/lua/?.so` + - `/abc/lua/a?d/j/g.elf` + +6. New paths are prepended to the original `package.cpath`. + +The result will look like this: + + `/foo/bar,/xxx;yyy/baz,/abc` ('runtimepath') + × `./?.so;/def/ghi/a?d/j/g.elf;/def/?.so` (`package.cpath`) + + = `/foo/bar/lua/?.so;/foo/bar/lua/a?d/j/g.elf;/abc/lua/?.so;/abc/lua/a?d/j/g.elf;./?.so;/def/ghi/a?d/j/g.elf;/def/?.so` + +Note: to keep up with 'runtimepath' updates paths added at previous update are +remembered and removed at the next update, while all paths derived from the +new 'runtimepath' are prepended as described above. This allows removing +paths when path is removed from 'runtimepath', adding paths when they are +added and reordering `package.path`/`package.cpath` content if 'runtimepath' +was reordered. + +Note 2: even though adjustments happens automatically Nvim does not track +current values of `package.path` or `package.cpath`. If you happened to +delete some paths from there you need to reset 'runtimepath' to make them +readded. Just running `let &runtimepath = &runtimepath` should work. + +Note 3: skipping paths from 'runtimepath' which contain semicolons applies +both to `package.path` and `package.cpath`. Given that there is a number of +badly written plugins using shell which will not work with paths containing +semicolons it is better to not have them in 'runtimepath' at all. + +------------------------------------------------------------------------------ +Example of a plugin that uses lua modules *lua-require-example* + +The following example plugin adds a command `:MakeCharBlob` which transforms +current buffer into a long `unsigned char` array. Lua contains transformation +function in a module `lua/charblob.lua` which is imported in +`autoload/charblob.vim` (`require("charblob")`). Example plugin is supposed +to be put into any directory from 'runtimepath', e.g. `~/.config/nvim` (in +this case `lua/charblob.lua` means `~/.config/nvim/lua/charblob.lua`). + +autoload/charblob.vim: > + + function charblob#encode_buffer() + call setline(1, luaeval( + \ 'require("charblob").encode(unpack(_A))', + \ [getline(1, '$'), &textwidth, ' '])) + endfunction + +plugin/charblob.vim: > + + if exists('g:charblob_loaded') + finish + endif + let g:charblob_loaded = 1 + + command MakeCharBlob :call charblob#encode_buffer() + +lua/charblob.lua: > + + local function charblob_bytes_iter(lines) + local init_s = { + next_line_idx = 1, + next_byte_idx = 1, + lines = lines, + } + local function next(s, _) + if lines[s.next_line_idx] == nil then + return nil + end + if s.next_byte_idx > #(lines[s.next_line_idx]) then + s.next_line_idx = s.next_line_idx + 1 + s.next_byte_idx = 1 + return ('\n'):byte() + end + local ret = lines[s.next_line_idx]:byte(s.next_byte_idx) + if ret == ('\n'):byte() then + ret = 0 -- See :h NL-used-for-NUL. + end + s.next_byte_idx = s.next_byte_idx + 1 + return ret + end + return next, init_s, nil + end + + local function charblob_encode(lines, textwidth, indent) + local ret = { + 'const unsigned char blob[] = {', + indent, + } + for byte in charblob_bytes_iter(lines) do + -- .- space + number (width 3) + comma + if #(ret[#ret]) + 5 > textwidth then + ret[#ret + 1] = indent + else + ret[#ret] = ret[#ret] .. ' ' + end + ret[#ret] = ret[#ret] .. (('%3u,'):format(byte)) + end + ret[#ret + 1] = '};' + return ret + end + + return { + bytes_iter = charblob_bytes_iter, + encode = charblob_encode, + } + +============================================================================== +Commands *lua-commands* + + *:lua* +:[range]lua {chunk} + Execute Lua chunk {chunk}. + +Examples: +> + :lua vim.api.nvim_command('echo "Hello, Nvim!"') +< +To see the Lua version: > + :lua print(_VERSION) + +To see the LuaJIT version: > + :lua print(jit.version) +< + +:[range]lua << {endmarker} +{script} +{endmarker} + Execute Lua script {script}. + +{endmarker} must NOT be preceded by any white space. If {endmarker} is +omitted from after the "<<", a dot '.' must be used after {script}, like +for the |:append| and |:insert| commands. +This form of the |:lua| command is mainly useful for including Lua code +in Vim scripts. + +Example: +> + function! CurrentLineInfo() + lua << EOF + local linenr = vim.api.nvim_win_get_cursor(0)[1] + local curline = vim.api.nvim_buf_get_lines( + 0, linenr, linenr + 1, false)[1] + print(string.format("Current line [%d] has %d bytes", + linenr, #curline)) + EOF + endfunction + +Note that the `local` variables will disappear when block finishes. This is +not the case for globals. + + *:luado* +:[range]luado {body} Execute Lua function "function (line, linenr) {body} + end" for each line in the [range], with the function + argument being set to the text of each line in turn, + without a trailing <EOL>, and the current line number. + If the value returned by the function is a string it + becomes the text of the line in the current turn. The + default for [range] is the whole file: "1,$". + +Examples: +> + :luado return string.format("%s\t%d", line:reverse(), #line) + + :lua require"lpeg" + :lua -- balanced parenthesis grammar: + :lua bp = lpeg.P{ "(" * ((1 - lpeg.S"()") + lpeg.V(1))^0 * ")" } + :luado if bp:match(line) then return "-->\t" .. line end +< + + *:luafile* +:[range]luafile {file} + Execute Lua script in {file}. + The whole argument is used as a single file name. + +Examples: +> + :luafile script.lua + :luafile % +< + +All these commands execute a Lua chunk from either the command line (:lua and +:luado) or a file (:luafile) with the given line [range]. Similarly to the Lua +interpreter, each chunk has its own scope and so only global variables are +shared between command calls. All Lua default libraries are available. In +addition, Lua "print" function has its output redirected to the Nvim message +area, with arguments separated by a white space instead of a tab. + +Lua uses the "vim" module (see |lua-vim|) to issue commands to Nvim +and manage buffers (|lua-buffer|) and windows (|lua-window|). However, +procedures that alter buffer content, open new buffers, and change cursor +position are restricted when the command is executed in the |sandbox|. + + +============================================================================== +The vim module *lua-vim* + +Lua interfaces Nvim through the "vim" module. Currently it has the `api` +submodule and some Nvim-specific utilities. + +------------------------------------------------------------------------------ +vim.api.* functions + +`vim.api` exposes the Nvim |API| as a table of Lua functions. All functions +are available. + +For example, to use the "nvim_get_current_line()" API function, call +"vim.api.nvim_get_current_line()": > + + print(tostring(vim.api.nvim_get_current_line())) + +------------------------------------------------------------------------------ +vim.* utility functions + +vim.stricmp(a, b) *lua-vim.stricmp* + Function used for case-insensitive string comparison. Takes two + string arguments and returns 0, 1 or -1 if strings are equal, a is + greater then b or a is lesser then b respectively. + +vim.type_idx *lua-vim.type_idx* + Type index for use in |lua-special-tables|. Specifying one of the + values from |lua-vim.types| allows typing the empty table (it is + unclear whether empty lua table represents empty list or empty array) + and forcing integral numbers to be |Float|. See |lua-special-tbl| for + more details. + +vim.val_idx *lua-vim.val_idx* + Value index for tables representing |Float|s. A table representing + floating-point value 1.0 looks like this: > + { + [vim.type_idx] = vim.types.float, + [vim.val_idx] = 1.0, + } +< See also |lua-vim.type_idx| and |lua-special-tbl|. + +vim.types *lua-vim.types* + Table with possible values for |lua-vim.type_idx|. Contains two sets + of key-value pairs: first maps possible values for |lua-vim.type_idx| + to human-readable strings, second maps human-readable type names to + values for |lua-vim.type_idx|. Currently contains pairs for `float`, + `array` and `dictionary` types. + + Note: one must expect that values corresponding to `vim.types.float`, + `vim.types.array` and `vim.types.dictionary` fall under only two + following assumptions: + 1. Value may serve both as a key and as a value in a table. Given the + properties of lua tables this basically means “value is not `nil`”. + 2. For each value in `vim.types` table `vim.types[vim.types[value]]` + is the same as `value`. + No other restrictions are put on types, and it is not guaranteed that + values corresponding to `vim.types.float`, `vim.types.array` and + `vim.types.dictionary` will not change or that `vim.types` table will + only contain values for these three types. + +============================================================================== +The luaeval function *lua-luaeval* *lua-eval* + *luaeval()* + +The (dual) equivalent of "vim.eval" for passing Lua values to Nvim is +"luaeval". "luaeval" takes an expression string and an optional argument used +for _A inside expression and returns the result of the expression. It is +semantically equivalent in Lua to: +> + local chunkheader = "local _A = select(1, ...) return " + function luaeval (expstr, arg) + local chunk = assert(loadstring(chunkheader .. expstr, "luaeval")) + return chunk(arg) -- return typval + end + +Note that "_A" receives the argument to "luaeval". Lua nils, numbers, strings, +tables and booleans are converted to their respective VimL types. An error is +thrown if conversion of any of the remaining Lua types is attempted. + +Note 2: lua tables are used as both dictionaries and lists, thus making it +impossible to determine whether empty table is meant to be empty list or empty +dictionary. Additionally lua does not have integer numbers. To distinguish +between these cases there is the following agreement: + +0. Empty table is empty list. +1. Table with N incrementally growing integral numbers, starting from 1 and + ending with N is considered to be a list. +2. Table with string keys, none of which contains NUL byte, is considered to + be a dictionary. +3. Table with string keys, at least one of which contains NUL byte, is also + considered to be a dictionary, but this time it is converted to + a |msgpack-special-map|. + *lua-special-tbl* +4. Table with `vim.type_idx` key may be a dictionary, a list or floating-point + value: + - `{[vim.type_idx]=vim.types.float, [vim.val_idx]=1}` is converted to + a floating-point 1.0. Note that by default integral lua numbers are + converted to |Number|s, non-integral are converted to |Float|s. This + variant allows integral |Float|s. + - `{[vim.type_idx]=vim.types.dictionary}` is converted to an empty + dictionary, `{[vim.type_idx]=vim.types.dictionary, [42]=1, a=2}` is + converted to a dictionary `{'a': 42}`: non-string keys are ignored. + Without `vim.type_idx` key tables with keys not fitting in 1., 2. or 3. + are errors. + - `{[vim.type_idx]=vim.types.list}` is converted to an empty list. As well + as `{[vim.type_idx]=vim.types.list, [42]=1}`: integral keys that do not + form a 1-step sequence from 1 to N are ignored, as well as all + non-integral keys. + +Examples: > + + :echo luaeval('math.pi') + :function Rand(x,y) " random uniform between x and y + : return luaeval('(_A.y-_A.x)*math.random()+_A.x', {'x':a:x,'y':a:y}) + : endfunction + :echo Rand(1,10) + +Note that currently second argument to `luaeval` undergoes VimL to lua +conversion, so changing containers in lua do not affect values in VimL. Return +value is also always converted. When converting, |msgpack-special-dict|s are +treated specially. + +============================================================================== + vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/if_pyth.txt b/runtime/doc/if_pyth.txt index b6fe234de4..8940e69092 100644 --- a/runtime/doc/if_pyth.txt +++ b/runtime/doc/if_pyth.txt @@ -1,4 +1,4 @@ -*if_pyth.txt* For Vim version 7.4. Last change: 2014 Jul 23 +*if_pyth.txt* Nvim VIM REFERENCE MANUAL by Paul Moore @@ -6,18 +6,10 @@ The Python Interface to Vim *python* *Python* -1. Commands |python-commands| -2. The vim module |python-vim| -3. Buffer objects |python-buffer| -4. Range objects |python-range| -5. Window objects |python-window| -6. Tab page objects |python-tabpage| -7. vim.bindeval objects |python-bindeval-objects| -8. pyeval(), py3eval() Vim functions |python-pyeval| -9. Python 3 |python3| - See |provider-python| for more information. {Nvim} + Type |gO| to see the table of contents. + ============================================================================== 1. Commands *python-commands* @@ -48,7 +40,11 @@ Example: > print 'EAT ME' EOF endfunction -< + +To see what version of Python you have: > + :python import sys + :python print(sys.version) + Note: Python is very sensitive to the indenting. Make sure the "class" line and "EOF" do not have any indent. @@ -181,11 +177,6 @@ vim.eval(str) *python-eval* # string.atoi() to convert to # a number. - :py tagList = vim.eval('taglist("eval_expr")') -< The latter will return a python list of python dicts, for instance: - [{'cmd': '/^eval_expr(arg, nextcmd)$/', 'static': 0, 'name': - 'eval_expr', 'kind': 'f', 'filename': './src/eval.c'}] - vim.bindeval(str) *python-bindeval* Like |python-eval|, but returns special objects described in |python-bindeval-objects|. These python objects let you modify (|List| @@ -688,7 +679,7 @@ vim.Function object *python-Function* 8. pyeval() and py3eval() Vim functions *python-pyeval* To facilitate bi-directional interface, you can use |pyeval()| and |py3eval()| -functions to evaluate Python expressions and pass their values to VimL. +functions to evaluate Python expressions and pass their values to Vim script. ============================================================================== 9. Python 3 *python3* @@ -697,6 +688,10 @@ functions to evaluate Python expressions and pass their values to VimL. The `:py3` and `:python3` commands work similar to `:python`. A simple check if the `:py3` command is working: > :py3 print("Hello") + +To see what version of Python you have: > + :py3 import sys + :py3 print(sys.version) < *:py3file* The `:py3file` command works similar to `:pyfile`. *:py3do* diff --git a/runtime/doc/if_ruby.txt b/runtime/doc/if_ruby.txt index fdd63501ea..ace304c083 100644 --- a/runtime/doc/if_ruby.txt +++ b/runtime/doc/if_ruby.txt @@ -1,22 +1,17 @@ -*if_ruby.txt* +*if_ruby.txt* Nvim VIM REFERENCE MANUAL by Shugo Maeda The Ruby Interface to Vim *ruby* *Ruby* - -1. Commands |ruby-commands| -2. The VIM module |ruby-vim| -3. VIM::Buffer objects |ruby-buffer| -4. VIM::Window objects |ruby-window| -5. Global variables |ruby-globals| - *E266* *E267* *E268* *E269* *E270* *E271* *E272* *E273* The home page for ruby is http://www.ruby-lang.org/. You can find links for downloading Ruby there. + Type |gO| to see the table of contents. + ============================================================================== 1. Commands *ruby-commands* @@ -54,6 +49,9 @@ Example Vim script: > EOF endfunction < +To see what version of Ruby you have: > + :ruby print RUBY_VERSION +< *:rubydo* *:rubyd* *E265* :[range]rubyd[o] {cmd} Evaluate Ruby command {cmd} for each line in the @@ -65,7 +63,7 @@ Example Vim script: > *:rubyfile* *:rubyf* :rubyf[ile] {file} Execute the Ruby script in {file}. This is the same as - ":ruby load 'file'", but allows file name completion. + `:ruby load 'file'`, but allows file name completion. Executing Ruby commands is not possible in the |sandbox|. diff --git a/runtime/doc/indent.txt b/runtime/doc/indent.txt index 496ccbc703..cf45ec4f38 100644 --- a/runtime/doc/indent.txt +++ b/runtime/doc/indent.txt @@ -1,4 +1,4 @@ -*indent.txt* For Vim version 7.4. Last change: 2014 Dec 06 +*indent.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -6,8 +6,7 @@ This file is about indenting C programs and other files. -1. Indenting C style programs |C-indenting| -2. Indenting by expression |indent-expression| + Type |gO| to see the table of contents. ============================================================================== 1. Indenting C style programs *C-indenting* diff --git a/runtime/doc/index.txt b/runtime/doc/index.txt index cedf0266d6..f4f43aeac2 100644 --- a/runtime/doc/index.txt +++ b/runtime/doc/index.txt @@ -1,4 +1,4 @@ -*index.txt* For Vim version 7.4. Last change: 2016 Jul 16 +*index.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -10,22 +10,13 @@ short description. The lists are sorted on ASCII value. Tip: When looking for certain functionality, use a search command. E.g., to look for deleting something, use: "/delete". -1. Insert mode |insert-index| -2. Normal mode |normal-index| - 2.1. Text objects |objects| - 2.2. Window commands |CTRL-W| - 2.3. Square bracket commands |[| - 2.4. Commands starting with 'g' |g| - 2.5. Commands starting with 'z' |z| -3. Visual mode |visual-index| -4. Command-line editing |ex-edit-index| -5. EX commands |ex-cmd-index| - For an overview of options see help.txt |option-list|. For an overview of built-in functions see |functions|. For a list of Vim variables see |vim-variable|. For a complete listing of all help items see |help-tags|. + Type |gO| to see the table of contents. + ============================================================================== 1. Insert mode *insert-index* @@ -307,10 +298,10 @@ tag char note action in Normal mode ~ |B| B 1 cursor N WORDS backward |C| ["x]C 2 change from the cursor position to the end of the line, and N-1 more lines [into - buffer x]; synonym for "c$" + register x]; synonym for "c$" |D| ["x]D 2 delete the characters under the cursor until the end of the line and N-1 more - lines [into buffer x]; synonym for "d$" + lines [into register x]; synonym for "d$" |E| E 1 cursor forward to the end of WORD N |F| F{char} 1 cursor to the Nth occurrence of {char} to the left @@ -327,13 +318,13 @@ tag char note action in Normal mode ~ opposite direction |O| O 2 begin a new line above the cursor and insert text, repeat N times -|P| ["x]P 2 put the text [from buffer x] before the +|P| ["x]P 2 put the text [from register x] before the cursor N times |Q| Q switch to "Ex" mode |R| R 2 enter replace mode: overtype existing characters, repeat the entered text N-1 times -|S| ["x]S 2 delete N lines [into buffer x] and start +|S| ["x]S 2 delete N lines [into register x] and start insert; synonym for "cc". |T| T{char} 1 cursor till after Nth occurrence of {char} to the left @@ -341,8 +332,8 @@ tag char note action in Normal mode ~ |V| V start linewise Visual mode |W| W 1 cursor N WORDS forward |X| ["x]X 2 delete N characters before the cursor [into - buffer x] -|Y| ["x]Y yank N lines [into buffer x]; synonym for + register x] +|Y| ["x]Y yank N lines [into register x]; synonym for "yy" |ZZ| ZZ store current file if modified, and exit |ZQ| ZQ exit current file always @@ -365,12 +356,12 @@ tag char note action in Normal mode ~ |`}| `} 1 cursor to the end of the current paragraph |a| a 2 append text after the cursor N times |b| b 1 cursor N words backward -|c| ["x]c{motion} 2 delete Nmove text [into buffer x] and start - insert -|cc| ["x]cc 2 delete N lines [into buffer x] and start +|c| ["x]c{motion} 2 delete Nmove text [into register x] and + start insert +|cc| ["x]cc 2 delete N lines [into register x] and start insert -|d| ["x]d{motion} 2 delete Nmove text [into buffer x] -|dd| ["x]dd 2 delete N lines [into buffer x] +|d| ["x]d{motion} 2 delete Nmove text [into register x] +|dd| ["x]dd 2 delete N lines [into register x] |do| do 2 same as ":diffget" |dp| dp 2 same as ":diffput" |e| e 1 cursor forward to the end of word N @@ -396,16 +387,16 @@ tag char note action in Normal mode ~ |q?| q? edit ? command-line in command-line window |r| r{char} 2 replace N chars with {char} |s| ["x]s 2 (substitute) delete N characters [into - buffer x] and start insert + register x] and start insert |t| t{char} 1 cursor till before Nth occurrence of {char} to the right |u| u 2 undo changes |v| v start characterwise Visual mode |w| w 1 cursor N words forward |x| ["x]x 2 delete N characters under and after the - cursor [into buffer x] -|y| ["x]y{motion} yank Nmove text [into buffer x] -|yy| ["x]yy yank N lines [into buffer x] + cursor [into register x] +|y| ["x]y{motion} yank Nmove text [into register x] +|yy| ["x]yy yank N lines [into register x] |z| z{char} commands starting with 'z', see |z| below |{| { 1 cursor N paragraphs backward |bar| | 1 cursor to column N @@ -982,7 +973,7 @@ tag command action in Command-line editing mode ~ |c_CTRL-E| CTRL-E cursor to end of command-line |'cedit'| CTRL-F default value for 'cedit': opens the command-line window; otherwise not used - CTRL-G not used +|c_CTRL-G| CTRL-G next match when 'incsearch' is active |c_<BS>| <BS> delete the character in front of the cursor |c_digraph| {char1} <BS> {char2} enter digraph when 'digraph' is on @@ -1000,12 +991,14 @@ tag command action in Command-line editing mode ~ |c_CTRL-L| CTRL-L do completion on the pattern in front of the cursor and insert the longest common part |c_<CR>| <CR> execute entered command -|c_<CR>| CTRL-M same as <CR> +|c_CTRL-M| CTRL-M same as <CR> |c_CTRL-N| CTRL-N after using 'wildchar' with multiple matches: - go to next match, otherwise: same as <Down> + go to next match, otherwise: recall older + command-line from history. CTRL-O not used |c_CTRL-P| CTRL-P after using 'wildchar' with multiple matches: - go to previous match, otherwise: same as <Up> + go to previous match, otherwise: recall older + command-line from history. |c_CTRL-Q| CTRL-Q same as CTRL-V, unless it's used for terminal control flow |c_CTRL-R| CTRL-R {0-9a-z"%#*:= CTRL-F CTRL-P CTRL-W CTRL-A} @@ -1015,7 +1008,7 @@ tag command action in Command-line editing mode ~ insert the contents of a register or object under the cursor literally CTRL-S (used for terminal control flow) - CTRL-T not used +|c_CTRL-T| CTRL-T previous match when 'incsearch' is active |c_CTRL-U| CTRL-U remove all characters |c_CTRL-V| CTRL-V insert next non-digit literally, insert three digit decimal number as a single byte. @@ -1024,7 +1017,7 @@ tag command action in Command-line editing mode ~ CTRL-Y copy (yank) modeless selection CTRL-Z not used (reserved for suspend) |c_<Esc>| <Esc> abandon command-line without executing it -|c_<Esc>| CTRL-[ same as <Esc> +|c_CTRL-[| CTRL-[ same as <Esc> |c_CTRL-\_CTRL-N| CTRL-\ CTRL-N go to Normal mode, abandon command-line |c_CTRL-\_CTRL-G| CTRL-\ CTRL-G go to mode specified with 'insertmode', abandon command-line @@ -1202,7 +1195,7 @@ tag command action ~ |:display| :di[splay] display registers |:djump| :dj[ump] jump to #define |:dl| :dl short for |:delete| with the 'l' flag -|:dl| :del[ete]l short for |:delete| with the 'l' flag +|:del| :del[ete]l short for |:delete| with the 'l' flag |:dlist| :dli[st] list #defines |:doautocmd| :do[autocmd] apply autocommands to current buffer |:doautoall| :doautoa[ll] apply autocommands for all loaded buffers @@ -1234,6 +1227,7 @@ tag command action ~ |:file| :f[ile] show or set the current file name |:files| :files list all files in the buffer list |:filetype| :filet[ype] switch file type detection on/off +|:filter| :filt[er] filter output of following command |:find| :fin[d] find file in 'path' and edit it |:finally| :fina[lly] part of a :try command |:finish| :fini[sh] quit sourcing a Vim script @@ -1339,6 +1333,9 @@ tag command action ~ |:ltag| :lt[ag] jump to tag and add matching tags to the location list |:lunmap| :lu[nmap] like ":unmap!" but includes Lang-Arg mode +|:lua| :lua execute Lua command +|:luado| :luad[o] execute Lua command for each line +|:luafile| :luaf[ile] execute Lua script file |:lvimgrep| :lv[imgrep] search for pattern in files |:lvimgrepadd| :lvimgrepa[dd] like :vimgrep, but append to current list |:lwindow| :lw[indow] open or close location window @@ -1545,13 +1542,17 @@ tag command action ~ |:tjump| :tj[ump] like ":tselect", but jump directly when there is only one match |:tlast| :tl[ast] jump to last matching tag +|:tmapclear| :tmapc[lear] remove all mappings for Terminal-Job mode +|:tmap| :tma[p] like ":map" but for Terminal-Job mode |:tmenu| :tm[enu] define menu tooltip |:tnext| :tn[ext] jump to next matching tag +|:tnoremap| :tno[remap] like ":noremap" but for Terminal-Job mode |:topleft| :to[pleft] make split window appear at top or far left |:tprevious| :tp[revious] jump to previous matching tag |:trewind| :tr[ewind] jump to first matching tag |:try| :try execute commands, abort on error or exception |:tselect| :ts[elect] list matching tags and select one +|:tunmap| :tunma[p] like ":unmap" but for Terminal-Job mode |:tunmenu| :tu[nmenu] remove menu tooltip |:undo| :u[ndo] undo last change(s) |:undojoin| :undoj[oin] join next change with previous undo block diff --git a/runtime/doc/insert.txt b/runtime/doc/insert.txt index 2d3eaafe63..b6cc18ab1b 100644 --- a/runtime/doc/insert.txt +++ b/runtime/doc/insert.txt @@ -1,4 +1,4 @@ -*insert.txt* For Vim version 7.4. Last change: 2016 Jan 31 +*insert.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -13,20 +13,11 @@ commands for inserting text in other ways. An overview of the most often used commands can be found in chapter 24 of the user manual |usr_24.txt|. -1. Special keys |ins-special-keys| -2. Special special keys |ins-special-special| -3. 'textwidth' and 'wrapmargin' options |ins-textwidth| -4. 'expandtab', 'smarttab' and 'softtabstop' options |ins-expandtab| -5. Replace mode |Replace-mode| -6. Virtual Replace mode |Virtual-Replace-mode| -7. Insert mode completion |ins-completion| -8. Insert mode commands |inserting| -9. Ex insert commands |inserting-ex| -10. Inserting a file |inserting-file| - Also see 'virtualedit', for moving the cursor to positions where there is no character. Useful for editing a table. + Type |gO| to see the table of contents. + ============================================================================== 1. Special keys *ins-special-keys* @@ -155,7 +146,8 @@ CTRL-R CTRL-R {0-9a-z"%#*+/:.-=} *i_CTRL-R_CTRL-R* CTRL-R CTRL-O {0-9a-z"%#*+/:.-=} *i_CTRL-R_CTRL-O* Insert the contents of a register literally and don't auto-indent. Does the same as pasting with the mouse - |<MiddleMouse>|. + |<MiddleMouse>|. When the register is linewise this will + insert the text above the current line, like with `P`. Does not replace characters! The '.' register (last inserted text) is still inserted as typed. @@ -616,13 +608,13 @@ Completion can be done for: 10. User defined completion |i_CTRL-X_CTRL-U| 11. omni completion |i_CTRL-X_CTRL-O| 12. Spelling suggestions |i_CTRL-X_s| -13. keywords in 'complete' |i_CTRL-N| +13. keywords in 'complete' |i_CTRL-N| |i_CTRL-P| -All these (except 2) are done in CTRL-X mode. This is a sub-mode of Insert -and Replace modes. You enter CTRL-X mode by typing CTRL-X and one of the -CTRL-X commands. You exit CTRL-X mode by typing a key that is not a valid -CTRL-X mode command. Valid keys are the CTRL-X command itself, CTRL-N (next), -and CTRL-P (previous). +All these, except CTRL-N and CTRL-P, are done in CTRL-X mode. This is a +sub-mode of Insert and Replace modes. You enter CTRL-X mode by typing CTRL-X +and one of the CTRL-X commands. You exit CTRL-X mode by typing a key that is +not a valid CTRL-X mode command. Valid keys are the CTRL-X command itself, +CTRL-N (next), and CTRL-P (previous). Also see the 'infercase' option if you want to adjust the case of the match. @@ -1086,7 +1078,7 @@ items: empty when non-zero this match will be added even when it is an empty string -All of these except 'icase', 'dup' and 'empty' must be a string. If an item +All of these except "icase", "dup" and "empty" must be a string. If an item does not meet these requirements then an error message is given and further items in the list are not used. You can mix string and Dictionary items in the returned list. diff --git a/runtime/doc/intro.txt b/runtime/doc/intro.txt index 786097dd74..6c40264d86 100644 --- a/runtime/doc/intro.txt +++ b/runtime/doc/intro.txt @@ -1,4 +1,4 @@ -*intro.txt* For Vim version 7.4. Last change: 2015 Jan 20 +*intro.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -6,14 +6,7 @@ Introduction to Vim *ref* *reference* -1. Introduction |intro| -2. Vim on the internet |internet| -3. Credits |credits| -4. Notation |notation| -5. Modes, introduction |vim-modes-intro| -6. Switching from mode to mode |mode-switching| -7. The window contents |window-contents| -8. Definitions |definitions| + Type |gO| to see the table of contents. ============================================================================== 1. Introduction *intro* @@ -34,11 +27,6 @@ It can be accessed from within Vim with the <Help> or <F1> key and with the is not located in the default place. You can jump to subjects like with tags: Use CTRL-] to jump to a subject under the cursor, use CTRL-T to jump back. -This manual refers to Vim on various machines. There may be small differences -between different computers and terminals. Besides the remarks given in this -document, there is a separate document for each supported system, see -|sys-file-list|. - *pronounce* Vim is pronounced as one word, like Jim, not vi-ai-em. It's written with a capital, since it's a name, again like Jim. @@ -80,8 +68,8 @@ The Vim pages contain the most recent information about Vim. They also contain links to the most recent version of Vim. The FAQ is a list of Frequently Asked Questions. Read this if you have problems. - VIM home page: http://www.vim.org/ - VIM FAQ: http://vimdoc.sf.net/ + Vim home page: http://www.vim.org/ + Vim FAQ: http://vimdoc.sf.net/ Downloading: ftp://ftp.vim.org/pub/vim/MIRRORS @@ -92,21 +80,18 @@ mention that. *mail-list* *maillist* There are several mailing lists for Vim: -<vim@vim.org> +<vim@vim.org> *vim-use* *vim_use* For discussions about using existing versions of Vim: Useful mappings, questions, answers, where to get a specific version, etc. There are quite a few people watching this list and answering questions, also for beginners. Don't hesitate to ask your question here. -<vim-dev@vim.org> *vim-dev* *vimdev* +<vim-dev@vim.org> *vim-dev* *vim_dev* *vimdev* For discussions about changing Vim: New features, porting, patches, beta-test versions, etc. -<vim-announce@vim.org> *vim-announce* +<vim-announce@vim.org> *vim-announce* *vim_announce* Announcements about new versions of Vim; also for beta-test versions and ports to different systems. This is a read-only list. -<vim-multibyte@vim.org> *vim-multibyte* - For discussions about using and improving the multi-byte aspects of - Vim. -<vim-mac@vim.org> *vim-mac* +<vim-mac@vim.org> *vim-mac* *vim_mac* For discussions about using and improving the Macintosh version of Vim. @@ -131,16 +116,18 @@ http://www.vim.org/maillist.php Bug reports: *bugs* *bug-reports* *bugreport.vim* -Send bug reports to: Vim Developers <vim-dev@vim.org> -This is a maillist, you need to become a member first and many people will see -the message. If you don't want that, e.g. because it is a security issue, -send it to <bugs@vim.org>, this only goes to the Vim maintainer (that's Bram). +Report bugs on GitHub: https://github.com/neovim/neovim/issues Please be brief; all the time that is spent on answering mail is subtracted from the time that is spent on improving Vim! Always give a reproducible -example and try to find out which settings or other things influence the -appearance of the bug. Try different machines, if possible. Send me patches -if you can! +example and try to find out which settings or other things trigger the bug. + +Preferably start Vim with: > + vim --clean -u reproduce.vim +Where reproduce.vim is a script that reproduces the problem. Try different +machines, if relevant (is this an MS-Windows specific bug perhaps?). + +Send me patches if you can! It will help to include information about the version of Vim you are using and your setup. You can get the information with this command: > @@ -254,6 +241,10 @@ Vim would never have become what it is now, without the help of these people! Juergen Weigert Lattice version, AUX improvements, Unix and MS-DOS ports, autoconf Stefan 'Sec' Zehl Maintainer of vim.org + Yasuhiro Matsumoto many MS-Windows improvements + Ken Takata fixes and features + Kazunobu Kuriyama GTK 3 + Christian Brabandt many fixes, features, user support, etc. I wish to thank all the people that sent me bug reports and suggestions. The list is too long to mention them all here. Vim would not be the same without @@ -267,8 +258,7 @@ Vi "the original". Without further remarks this is the version of Vi that appeared in Sun OS 4.x. ":version" returns "Version 3.7, 6/7/85". Sometimes other versions are referred to. Only runs under Unix. Source code only available with a - license. More information on Vi can be found through: - http://vi-editor.org [doesn't currently work...] + license. *Nvi* Nvi The "New" Vi. The version of Vi that comes with BSD 4.4 and FreeBSD. Very good compatibility with the original Vi, with a few extensions. @@ -392,8 +382,7 @@ CTRL-{char} {char} typed as a control character; that is, typing {char} *key-notation* *key-codes* *keycodes* These names for keys are used in the documentation. They can also be used -with the ":map" command (insert the key name by pressing CTRL-K and then the -key you want the name for). +with the ":map" command. notation meaning equivalent decimal value(s) ~ ----------------------------------------------------------------------- @@ -453,7 +442,6 @@ notation meaning equivalent decimal value(s) ~ <M-...> alt-key or meta-key *META* *meta* *alt* *<M-* <A-...> same as <M-...> *<A-* <D-...> command-key or "super" key *<D-* -<t_xx> key with "xx" entry in termcap ----------------------------------------------------------------------- Note: The shifted cursor keys, the help key, and the undo key are only @@ -461,8 +449,8 @@ available on a few terminals. Note: There are two codes for the delete key. 127 is the decimal ASCII value for the delete key, which is always recognized. Some delete keys send another -value, in which case this value is obtained from the termcap entry "kD". Both -values have the same effect. +value, in which case this value is obtained from the |terminfo| entry "key_dc". +Both values have the same effect. Note: The keypad keys are used in the same way as the corresponding "normal" keys. For example, <kHome> has the same effect as <Home>. If a keypad key @@ -488,7 +476,6 @@ the ":map" command. The rules are: <S-F11> Shifted function key 11 <M-a> Meta- a ('a' with bit 8 set) <M-A> Meta- A ('A' with bit 8 set) - <t_kd> "kd" termcap entry (cursor down key) The <> notation uses <lt> to escape the special meaning of key names. Using a backslash also works, but only when 'cpoptions' does not include the 'B' flag. @@ -509,7 +496,7 @@ examples and use them directly. Or type them literally, including the '<' and ============================================================================== 5. Modes, introduction *vim-modes-intro* *vim-modes* -Vim has six BASIC modes: +Vim has seven BASIC modes: *Normal* *Normal-mode* *command-mode* Normal mode In Normal mode you can enter all the normal editor @@ -545,6 +532,13 @@ Ex mode Like Command-line mode, but after entering a command you remain in Ex mode. Very limited editing of the command line. |Ex-mode| + *Terminal-mode* +Terminal mode In Terminal mode all input (except |c_CTRL-\_CTRL-N|) + is sent to the process running in the current + |terminal| buffer. + If the 'showmode' option is on "-- TERMINAL --" is shown + at the bottom of the window. + There are six ADDITIONAL modes. These are variants of the BASIC modes: *Operator-pending* *Operator-pending-mode* @@ -728,9 +722,9 @@ special situation. Vim will show only part of the line, around where the cursor is. There are no special characters shown, so that you can edit all parts of this line. -The '@' occasion in the 'highlight' option can be used to set special -highlighting for the '@' and '~' characters. This makes it possible to -distinguish them from real characters in the buffer. +The |hl-NonText| highlight group can be used to set special highlighting +for the '@' and '~' characters. This makes it possible to distinguish them +from real characters in the buffer. The 'showbreak' option contains the string to put in front of wrapped lines. @@ -797,10 +791,12 @@ by Vim. ============================================================================== 8. Definitions *definitions* + buffer Contains lines of text, usually read from a file. screen The whole area that Vim uses to work in. This can be a terminal emulator window. Also called "the Vim window". - window A view on a buffer. + window A view on a buffer. There can be multiple windows for + one buffer. A screen contains one or more windows, separated by status lines and with the command line at the bottom. diff --git a/runtime/doc/job_control.txt b/runtime/doc/job_control.txt index 1aa7ce06d6..e57015db22 100644 --- a/runtime/doc/job_control.txt +++ b/runtime/doc/job_control.txt @@ -1,46 +1,36 @@ -*job_control.txt* For Nvim. {Nvim} +*job_control.txt* Nvim NVIM REFERENCE MANUAL by Thiago de Arruda -Nvim's facilities for job control *job-control* +Nvim job control *job-control* -1. Introduction |job-control-intro| -2. Usage |job-control-usage| +Job control is a way to perform multitasking in Nvim, so scripts can spawn and +control multiple processes without blocking the current Nvim instance. -============================================================================== -1. Introduction *job-control-intro* + Type |gO| to see the table of contents. -Job control is a simple way to perform multitasking in vimscript. Wikipedia -contains a more generic/detailed description: +============================================================================== +Concepts -"Job control in computing refers to the control of multiple tasks or Jobs on a -computer system, ensuring that they each have access to adequate resources to -perform correctly, that competition for limited resources does not cause a -deadlock where two or more jobs are unable to complete, resolving such -situations where they do occur, and terminating jobs that, for any reason, are -not performing as expected." +Job Id *job-id* -In a few words: It allows a vimscript programmer to concurrently spawn and -control multiple processes without blocking the current Nvim instance. +When a job starts it is assigned a number, unique for the life of the current +Nvim session. Functions like |jobstart()| return job ids. Functions like +|jobsend()|, |jobstop()|, |rpcnotify()|, and |rpcrequest()| take job ids. -Nvim's job control was designed to be simple and familiar to vimscript -programmers, instead of being very powerful but complex. Unlike Vim's -facilities for calling with external commands, job control does not depend on -available shells, instead relying on OS functionality for process management. +The job's stdio streams are represented as a |channel|. It is possible to send +and recieve raw bytes, or use |msgpack-rpc|. +============================================================================== +Usage *job-control-usage* -Internally, Nvim job control is powered by libuv, which has a nice -cross-platform API for managing processes. See https://github.com/libuv/libuv -for details. +To control jobs, use the "job…" family of functions: |jobstart()|, +|jobsend()|, |jobstop()|. -============================================================================== -2. Usage *job-control-usage* +Example: > -Job control is achieved by calling a combination of the |jobstart()|, -|jobsend()| and |jobstop()| functions. Here's an example: -> - function! s:JobHandler(job_id, data, event) dict + function! s:OnEvent(job_id, data, event) dict if a:event == 'stdout' let str = self.shell.' stdout: '.join(a:data) elseif a:event == 'stderr' @@ -52,41 +42,36 @@ Job control is achieved by calling a combination of the |jobstart()|, call append(line('$'), str) endfunction let s:callbacks = { - \ 'on_stdout': function('s:JobHandler'), - \ 'on_stderr': function('s:JobHandler'), - \ 'on_exit': function('s:JobHandler') + \ 'on_stdout': function('s:OnEvent'), + \ 'on_stderr': function('s:OnEvent'), + \ 'on_exit': function('s:OnEvent') \ } let job1 = jobstart(['bash'], extend({'shell': 'shell 1'}, s:callbacks)) let job2 = jobstart(['bash', '-c', 'for i in {1..10}; do echo hello $i!; sleep 1; done'], extend({'shell': 'shell 2'}, s:callbacks)) +To test the above script, copy it to a file ~/foo.vim and run it: > + nvim -u ~/foo.vim < -To test the above, copy it to the file ~/jobcontrol.vim and start with a clean -nvim instance: -> - nvim -u NONE -S ~/jobcontrol.vim -< -Here's what is happening: - -- Two bash instances are spawned by |jobstart()| with their stdin/stdout/stderr - connected to nvim. -- The first shell is idle, waiting to read commands from its stdin. -- The second shell is started with the -c argument, causing it to execute a - command then exit. In this case, the command is a for loop that will print 0 - through 9 then exit. -- The `JobHandler()` function is a callback passed to |jobstart()| to handle - various job events. It takes care of displaying stdout/stderr received from - the shells. -- The arguments passed to `JobHandler()` are: - - 0: The job id - 1: If the event is "stdout" or "stderr", a list with lines read from the - corresponding stream. For "exit", it is the status returned by the - program. - 2: The event type, which is "stdout", "stderr" or "exit". +Description of what happens: + - Two bash shells are spawned by |jobstart()| with their stdin/stdout/stderr + streams connected to nvim. + - The first shell is idle, waiting to read commands from its stdin. + - The second shell is started with -c which executes the command (a for-loop + printing 0 through 9) and then exits. + - `JobHandler()` callback is passed to |jobstart()| to handle various job + events. It displays stdout/stderr data received from the shells. + +For |on_stdout| and |on_stderr| see |channel-callback|. + *on_exit* +Arguments passed to on_exit callback: + 0: |job-id| + 1: Exit-code of the process. + 2: Event type: "exit" + Note: Buffered stdout/stderr data which has not been flushed by the sender - will not trigger the "stdout" callback (but if the process ends, the - "exit" callback will be triggered). + will not trigger the on_stdout/on_stderr callback (but if the process + ends, the on_exit callback will be invoked). For example, "ruby -e" buffers output, so small strings will be buffered unless "auto-flushing" ($stdout.sync=true) is enabled. > function! Receive(job_id, data, event) @@ -97,54 +82,64 @@ Here's what is happening: \ {'on_stdout': 'Receive'}) < https://github.com/neovim/neovim/issues/1592 -The options dictionary is passed as the "self" variable to the callback -function. Here's a more object-oriented version of the above: -> - let Shell = {} + Note 2: + Job event handlers may receive partial (incomplete) lines. For a given + invocation of on_stdout/on_stderr, `a:data` is not guaranteed to end + with a newline. + - `abcdefg` may arrive as `['abc']`, `['defg']`. + - `abc\nefg` may arrive as `['abc', '']`, `['efg']` or `['abc']`, + `['','efg']`, or even `['ab']`, `['c','efg']`. + Easy way to deal with this: initialize a list as `['']`, then append + to it as follows: > + let s:chunks = [''] + func! s:on_stdout(job_id, data, event) dict + let s:chunks[-1] .= a:data[0] + call extend(s:chunks, a:data[1:]) + endf +< - function Shell.on_stdout(job_id, data) dict - call append(line('$'), self.get_name().' stdout: '.join(a:data)) - endfunction +The |jobstart-options| dictionary is passed as |self| to the callback. +The above example could be written in this "object-oriented" style: > - function Shell.on_stderr(job_id, data) dict - call append(line('$'), self.get_name().' stderr: '.join(a:data)) - endfunction + let Shell = {} - function Shell.on_exit(job_id, data) dict - call append(line('$'), self.get_name().' exited') + function Shell.on_stdout(_job_id, data, event) + call append(line('$'), + \ printf('[%s] %s: %s', a:event, self.name, join(a:data[:-2]))) endfunction - function Shell.get_name() dict - return 'shell '.self.name - endfunction + let Shell.on_stderr = function(Shell.on_stdout) - function Shell.new(name, ...) dict - let instance = extend(copy(g:Shell), {'name': a:name}) - let argv = ['bash'] - if a:0 > 0 - let argv += ['-c', a:1] - endif - let instance.id = jobstart(argv, instance) - return instance + function Shell.on_exit(job_id, _data, event) + let msg = printf('job %d ("%s") finished', a:job_id, self.name) + call append(line('$'), printf('[%s] BOOM!', a:event)) + call append(line('$'), printf('[%s] %s!', a:event, msg)) endfunction - let s1 = Shell.new('1') - let s2 = Shell.new('2', 'for i in {1..10}; do echo hello $i!; sleep 1; done') - + function Shell.new(name, cmd) + let object = extend(copy(g:Shell), {'name': a:name}) + let object.cmd = ['sh', '-c', a:cmd] + let object.id = jobstart(object.cmd, object) + $ + return object + endfunction -To send data to the job's stdin, one can use the |jobsend()| function, like -this: -> - :call jobsend(job1, "ls\n") - :call jobsend(job1, "invalid-command\n") - :call jobsend(job1, "exit\n") + let instance = Shell.new('bomb', + \ 'for i in $(seq 9 -1 1); do echo $i 1>&$((i % 2 + 1)); sleep 1; done') +< +To send data to the job's stdin, use |chansend()|: > + :call chansend(job1, "ls\n") + :call chansend(job1, "invalid-command\n") + :call chansend(job1, "exit\n") +< +A job may be killed with |jobstop()|: > + :call jobstop(job1) < A job may be killed at any time with the |jobstop()| function: > :call jobstop(job1) < -When |jobstop()| is called, `SIGTERM` will be sent to the job. If a job does -not exit after 2 seconds, `SIGKILL` will be sent. +Individual streams can be closed without killing the job, see |chanclose()|. ============================================================================== vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt index 53b152dc06..9b61fa6527 100644 --- a/runtime/doc/map.txt +++ b/runtime/doc/map.txt @@ -1,4 +1,4 @@ -*map.txt* For Vim version 7.4. Last change: 2016 Jul 06 +*map.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -9,27 +9,13 @@ Key mapping, abbreviations and user-defined commands. This subject is introduced in sections |05.3|, |24.7| and |40.1| of the user manual. -1. Key mapping |key-mapping| - 1.1 MAP COMMANDS |:map-commands| - 1.2 Special arguments |:map-arguments| - 1.3 Mapping and modes |:map-modes| - 1.4 Listing mappings |map-listing| - 1.5 Mapping special keys |:map-special-keys| - 1.6 Special characters |:map-special-chars| - 1.7 What keys to map |map-which-keys| - 1.8 Examples |map-examples| - 1.9 Using mappings |map-typing| - 1.10 Mapping alt-keys |:map-alt-keys| - 1.11 Mapping an operator |:map-operator| -2. Abbreviations |abbreviations| -3. Local mappings and functions |script-local| -4. User-defined commands |user-commands| + Type |gO| to see the table of contents. ============================================================================== 1. Key mapping *key-mapping* *mapping* *macro* Key mapping is used to change the meaning of typed keys. The most common use -is to define a sequence commands for a function key. Example: > +is to define a sequence of commands for a function key. Example: > :map <F2> a<C-R>=strftime("%c")<CR><Esc> @@ -55,7 +41,7 @@ modes. :im[ap] {lhs} {rhs} |mapmode-i| *:im* *:imap* :lm[ap] {lhs} {rhs} |mapmode-l| *:lm* *:lmap* :cm[ap] {lhs} {rhs} |mapmode-c| *:cm* *:cmap* -:tm[ap] {lhs} {rhs} |mapmode-t| *:tm* *:tmap* +:tma[p] {lhs} {rhs} |mapmode-t| *:tma* *:tmap* Map the key sequence {lhs} to {rhs} for the modes where the map command applies. The result, including {rhs}, is then further scanned for mappings. This @@ -89,7 +75,7 @@ modes. :iu[nmap] {lhs} |mapmode-i| *:iu* *:iunmap* :lu[nmap] {lhs} |mapmode-l| *:lu* *:lunmap* :cu[nmap] {lhs} |mapmode-c| *:cu* *:cunmap* -:tu[nmap] {lhs} |mapmode-t| *:tu* *:tunmap* +:tunma[p] {lhs} |mapmode-t| *:tunma* *:tunmap* Remove the mapping of {lhs} for the modes where the map command applies. The mapping may remain defined for other modes where it applies. @@ -125,7 +111,7 @@ modes. :im[ap] |mapmode-i| :lm[ap] |mapmode-l| :cm[ap] |mapmode-c| -:tm[ap] |mapmode-t| +:tma[p] |mapmode-t| List all key mappings for the modes where the map command applies. Note that ":map" and ":map!" are used most often, because they include the other modes. @@ -140,7 +126,7 @@ modes. :im[ap] {lhs} |mapmode-i| *:imap_l* :lm[ap] {lhs} |mapmode-l| *:lmap_l* :cm[ap] {lhs} |mapmode-c| *:cmap_l* -:tm[ap] {lhs} |mapmode-t| *:tmap_l* +:tma[p] {lhs} |mapmode-t| *:tmap_l* List the key mappings for the key sequences starting with {lhs} in the modes where the map command applies. @@ -163,7 +149,7 @@ type "a", then "bar" will get inserted. 1.2 SPECIAL ARGUMENTS *:map-arguments* -"<buffer>", "<nowait>", "<silent>", "<special>", "<script>", "<expr>" and +"<buffer>", "<nowait>", "<silent>", "<script>", "<expr>" and "<unique>" can be used in any order. They must appear right after the command, before any other arguments. @@ -189,7 +175,7 @@ that starts with ",". Then you need to type another character for Vim to know whether to use the "," mapping or the longer one. To avoid this add the <nowait> argument. Then the mapping will be used when it matches, Vim does not wait for more characters to be typed. However, if the characters were -already type they are used. +already typed they are used. *:map-<silent>* *:map-silent* To define a mapping which will not be echoed on the command line, add @@ -203,12 +189,6 @@ Prompts will still be given, e.g., for inputdialog(). Using "<silent>" for an abbreviation is possible, but will cause redrawing of the command line to fail. - *:map-<special>* *:map-special* -Define a mapping with <> notation for special keys, even though the "<" flag -may appear in 'cpoptions'. This is useful if the side effect of setting -'cpoptions' is not desired. Example: > - :map <special> <F12> /Header<CR> -< *:map-<script>* *:map-script* If the first argument to one of these commands is "<script>" and it is used to define a new mapping or abbreviation, the mapping will only remap characters @@ -437,6 +417,9 @@ with a space. Note: When using mappings for Visual mode, you can use the "'<" mark, which is the start of the last selected Visual area in the current buffer |'<|. +The |:filter| command can be used to select what mappings to list. The +pattern is matched against the {lhs} and {rhs} in the raw form. + *:map-verbose* When 'verbose' is non-zero, listing a key map will also display where it was last defined. Example: > @@ -450,42 +433,28 @@ See |:verbose-cmd| for more information. 1.5 MAPPING SPECIAL KEYS *:map-special-keys* -There are three ways to map a special key: +There are two ways to map a special key: 1. The Vi-compatible method: Map the key code. Often this is a sequence that starts with <Esc>. To enter a mapping like this you type ":map " and then you have to type CTRL-V before hitting the function key. Note that when - the key code for the key is in the termcap (the t_ options), it will - automatically be translated into the internal code and become the second - way of mapping (unless the 'k' flag is included in 'cpoptions'). + the key code for the key is in the |terminfo| entry, it will automatically + be translated into the internal code and become the second way of mapping. 2. The second method is to use the internal code for the function key. To enter such a mapping type CTRL-K and then hit the function key, or use the form "#1", "#2", .. "#9", "#0", "<Up>", "<S-Down>", "<S-F7>", etc. (see table of keys |key-notation|, all keys from <Up> can be used). The first ten function keys can be defined in two ways: Just the number, like "#2", and with "<F>", like "<F2>". Both stand for function key 2. "#0" - refers to function key 10, defined with option 't_f10', which may be - function key zero on some keyboards. The <> form cannot be used when - 'cpoptions' includes the '<' flag. -3. Use the termcap entry, with the form <t_xx>, where "xx" is the name of the - termcap entry. Any string entry can be used. For example: > - :map <t_F3> G -< Maps function key 13 to "G". This does not work if 'cpoptions' includes - the '<' flag. - -The advantage of the second and third method is that the mapping will work on -different terminals without modification (the function key will be -translated into the same internal code or the actual key code, no matter what -terminal you are using. The termcap must be correct for this to work, and you -must use the same mappings). + refers to function key 10. DETAIL: Vim first checks if a sequence from the keyboard is mapped. If it -isn't the terminal key codes are tried (see |terminal-options|). If a -terminal code is found it is replaced with the internal code. Then the check -for a mapping is done again (so you can map an internal code to something -else). What is written into the script file depends on what is recognized. -If the terminal key code was recognized as a mapping the key code itself is -written to the script file. If it was recognized as a terminal code the -internal code is written to the script file. +isn't the terminal key codes are tried. If a terminal code is found it is +replaced with the internal code. Then the check for a mapping is done again +(so you can map an internal code to something else). What is written into the +script file depends on what is recognized. If the terminal key code was +recognized as a mapping the key code itself is written to the script file. If +it was recognized as a terminal code the internal code is written to the +script file. 1.6 SPECIAL CHARACTERS *:map-special-chars* @@ -587,16 +556,17 @@ Upper and lowercase differences are ignored. *map-comments* It is not possible to put a comment after these commands, because the '"' -character is considered to be part of the {lhs} or {rhs}. +character is considered to be part of the {lhs} or {rhs}. However, one can +use |", since this starts a new, empty command with a comment. *map_bar* *map-bar* Since the '|' character is used to separate a map command from the next command, you will have to do something special to include a '|' in {rhs}. There are three methods: use works when example ~ - <Bar> '<' is not in 'cpoptions' :map _l :!ls <Bar> more^M + <Bar> always :map _l :!ls <Bar> more^M \| 'b' is not in 'cpoptions' :map _l :!ls \| more^M - ^V| always, in Vim and Vi :map _l :!ls ^V| more^M + ^V| always :map _l :!ls ^V| more^M (here ^V stands for CTRL-V; to get one CTRL-V you have to type it twice; you cannot use the <> notation "<C-V>" here). @@ -651,8 +621,7 @@ out about, ^D is CTRL-D). 1.8 EXAMPLES *map-examples* -A few examples (given as you type them, for "<CR>" you type four characters; -the '<' flag must not be present in 'cpoptions' for this to work). > +A few examples (as you type them: for "<CR>" you type four characters). > :map <F3> o#include :map <M-g> /foo<CR>cwbar<Esc> @@ -684,7 +653,7 @@ option). After that it assumes that the 'q' is to be interpreted as such. If you type slowly, or your system is slow, reset the 'timeout' option. Then you might want to set the 'ttimeout' option. - *map-precedence* + *map-precedence* Buffer-local mappings (defined using |:map-<buffer>|) take precedence over global mappings. When a buffer-local mapping is the same as a global mapping, Vim will use the buffer-local mapping. In addition, Vim will use a complete @@ -720,9 +689,6 @@ special key: > Don't type a real <Esc>, Vim will recognize the key code and replace it with <F1> anyway. -Another problem may be that when keeping ALT or Meta pressed the terminal -prepends ESC instead of setting the 8th bit. See |:map-alt-keys|. - *recursive_mapping* If you include the {lhs} in the {rhs} you have a recursive mapping. When {lhs} is typed, it will be replaced with {rhs}. When the {lhs} which is @@ -762,46 +728,14 @@ in the original Vi, you would get back the text before the first undo). 1.10 MAPPING ALT-KEYS *:map-alt-keys* -In the GUI Vim handles the Alt key itself, thus mapping keys with ALT should -always work. But in a terminal Vim gets a sequence of bytes and has to figure -out whether ALT was pressed or not. - -By default Vim assumes that pressing the ALT key sets the 8th bit of a typed -character. Most decent terminals can work that way, such as xterm, aterm and -rxvt. If your <A-k> mappings don't work it might be that the terminal is -prefixing the character with an ESC character. But you can just as well type -ESC before a character, thus Vim doesn't know what happened (except for -checking the delay between characters, which is not reliable). - -As of this writing, some mainstream terminals like gnome-terminal and konsole -use the ESC prefix. There doesn't appear a way to have them use the 8th bit -instead. Xterm should work well by default. Aterm and rxvt should work well -when started with the "--meta8" argument. You can also tweak resources like -"metaSendsEscape", "eightBitInput" and "eightBitOutput". - -On the Linux console, this behavior can be toggled with the "setmetamode" -command. Bear in mind that not using an ESC prefix could get you in trouble -with other programs. You should make sure that bash has the "convert-meta" -option set to "on" in order for your Meta keybindings to still work on it -(it's the default readline behavior, unless changed by specific system -configuration). For that, you can add the line: > - - set convert-meta on - -to your ~/.inputrc file. If you're creating the file, you might want to use: > - - $include /etc/inputrc - -as the first line, if that file exists on your system, to keep global options. -This may cause a problem for entering special characters, such as the umlaut. -Then you should use CTRL-V before that character. - -Bear in mind that convert-meta has been reported to have troubles when used in -UTF-8 locales. On terminals like xterm, the "metaSendsEscape" resource can be -toggled on the fly through the "Main Options" menu, by pressing Ctrl-LeftClick -on the terminal; that's a good last resource in case you want to send ESC when -using other applications but not when inside VIM. - +In the GUI Nvim handles the |ALT| key itself, thus mapping keys with ALT +should always work. But in a terminal Nvim gets a sequence of bytes and has +to figure out whether ALT was pressed. Terminals may use ESC to indicate that +ALT was pressed. If ESC is followed by a {key} within 'ttimeoutlen' +milliseconds, the ESC is interpreted as: + <ALT-{key}> +otherwise it is interpreted as two key presses: + <ESC> {key} 1.11 MAPPING AN OPERATOR *:map-operator* @@ -939,7 +873,6 @@ character is mostly ignored otherwise. It is possible to move the cursor after an abbreviation: > :iab if if ()<Left> -This does not work if 'cpoptions' includes the '<' flag. |<>| You can even do more complicated things. For example, to consume the space typed after an abbreviation: > @@ -1087,8 +1020,7 @@ functions used in one script use the same name as in other scripts. To avoid this, they can be made local to the script. *<SID>* *<SNR>* *E81* -The string "<SID>" can be used in a mapping or menu. This requires that the -'<' flag is not present in 'cpoptions'. +The string "<SID>" can be used in a mapping or menu. When executing the map command, Vim will replace "<SID>" with the special key code <SNR>, followed by a number that's unique for the script, and an underscore. Example: > @@ -1171,6 +1103,10 @@ scripts. " Command has the -register attribute b Command is local to current buffer (see below for details on attributes) + The list can be filtered on command name with + |:filter|, e.g., to list all commands with "Pyth" in + the name: > + filter Pyth command :com[mand] {cmd} List the user-defined commands that start with {cmd} @@ -1267,6 +1203,7 @@ completion can be enabled: -complete=locale locale names (as output of locale -a) -complete=mapping mapping name -complete=menu menus + -complete=messages |:messages| suboptions -complete=option options -complete=packadd optional package |pack-add| names -complete=shellcmd Shell command @@ -1411,9 +1348,11 @@ The valid escape sequences are <mods> The command modifiers, if specified. Otherwise, expands to nothing. Supported modifiers are |:aboveleft|, |:belowright|, |:botright|, |:browse|, |:confirm|, |:hide|, |:keepalt|, - |:keepjumps|, |:keepmarks|, |:keeppatterns|, |:lockmarks|, - |:noswapfile|, |:silent|, |:tab|, |:topleft|, |:verbose|, and - |:vertical|. + |:keepjumps|, |:keepmarks|, |:keeppatterns|, |:leftabove|, + |:lockmarks|, |:noswapfile| |:rightbelow|, |:silent|, |:tab|, + |:topleft|, |:verbose|, and |:vertical|. + Note that these are not yet supported: |:noautocmd|, + |:sandbox| and |:unsilent|. Examples: > command! -nargs=+ -complete=file MyEdit \ for f in expand(<q-args>, 0, 1) | diff --git a/runtime/doc/mbyte.txt b/runtime/doc/mbyte.txt index 355a1da423..531629fddc 100644 --- a/runtime/doc/mbyte.txt +++ b/runtime/doc/mbyte.txt @@ -1,4 +1,4 @@ -*mbyte.txt* For Vim version 7.4. Last change: 2016 Jul 21 +*mbyte.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar et al. @@ -14,26 +14,10 @@ For an introduction to the most common features, see |usr_45.txt| in the user manual. For changing the language of messages and menus see |mlang.txt|. -{not available when compiled without the |+multi_byte| feature} - - -1. Getting started |mbyte-first| -2. Locale |mbyte-locale| -3. Encoding |mbyte-encoding| -4. Using a terminal |mbyte-terminal| -5. Fonts on X11 |mbyte-fonts-X11| -6. Fonts on MS-Windows |mbyte-fonts-MSwin| -7. Input on X11 |mbyte-XIM| -8. Input on MS-Windows |mbyte-IME| -9. Input with a keymap |mbyte-keymap| -10. Using UTF-8 |mbyte-utf8| -11. Overview of options |mbyte-options| - -NOTE: This file contains UTF-8 characters. These may show up as strange -characters or boxes when using another encoding. + Type |gO| to see the table of contents. ============================================================================== -1. Getting started *mbyte-first* +Getting started *mbyte-first* This is a summary of the multibyte features in Vim. If you are lucky it works as described and you can start using Vim without much trouble. If something @@ -89,8 +73,7 @@ be displayed and edited correctly. For the GUI you must select fonts that work with UTF-8. This is the difficult part. It depends on the system you are using, the locale and -a few other things. See the chapters on fonts: |mbyte-fonts-X11| for -X-Windows and |mbyte-fonts-MSwin| for MS-Windows. +a few other things. For X11 you can set the 'guifontset' option to a list of fonts that together cover the characters that are used. Example for Korean: > @@ -120,7 +103,7 @@ The options 'iminsert', 'imsearch' and 'imcmdline' can be used to chose the different input methods or disable them temporarily. ============================================================================== -2. Locale *mbyte-locale* +Locale *mbyte-locale* The easiest setup is when your whole system uses the locale you want to work in. But it's also possible to set the locale for one shell you are working @@ -209,7 +192,7 @@ Or specify $LANG when starting Vim: You could make a small shell script for this. ============================================================================== -3. Encoding *mbyte-encoding* +Encoding *mbyte-encoding* In Nvim UTF-8 is always used internally to encode characters. This applies to all the places where text is used, including buffers (files @@ -418,49 +401,7 @@ neither of them can be found Vim will still work but some conversions won't be possible. ============================================================================== -4. Using a terminal *mbyte-terminal* - -The GUI fully supports multi-byte characters. It is also possible in a -terminal, if the terminal supports the same encoding that Vim uses. Thus this -is less flexible. - -For example, you can run Vim in a xterm with added multi-byte support and/or -|XIM|. Examples are kterm (Kanji term) and hanterm (for Korean), Eterm -(Enlightened terminal) and rxvt. - -UTF-8 IN XFREE86 XTERM *UTF8-xterm* - -This is a short explanation of how to use UTF-8 character encoding in the -xterm that comes with XFree86 by Thomas Dickey (text by Markus Kuhn). - -Get the latest xterm version which has now UTF-8 support: - - http://invisible-island.net/xterm/xterm.html - -Compile it with "./configure --enable-wide-chars ; make" - -Also get the ISO 10646-1 version of various fonts, which is available on - - http://www.cl.cam.ac.uk/~mgk25/download/ucs-fonts.tar.gz - -and install the font as described in the README file. - -Now start xterm with > - - xterm -u8 -fn -misc-fixed-medium-r-semicondensed--13-120-75-75-c-60-iso10646-1 -or, for bigger character: > - xterm -u8 -fn -misc-fixed-medium-r-normal--15-140-75-75-c-90-iso10646-1 - -and you will have a working UTF-8 terminal emulator. Try both > - - cat utf-8-demo.txt - vim utf-8-demo.txt - -with the demo text that comes with ucs-fonts.tar.gz in order to see -whether there are any problems with UTF-8 in your xterm. - -============================================================================== -5. Fonts on X11 *mbyte-fonts-X11* +Fonts on X11 *mbyte-fonts-X11* Unfortunately, using fonts in X11 is complicated. The name of a single-byte font is a long string. For multi-byte fonts we need several of these... @@ -596,20 +537,7 @@ Also make sure that you set 'guifontset' before setting fonts for highlight groups. ============================================================================== -6. Fonts on MS-Windows *mbyte-fonts-MSwin* - -The simplest is to use the font dialog to select fonts and try them out. You -can find this at the "Edit/Select Font..." menu. Once you find a font name -that works well you can use this command to see its name: > - - :set guifont - -Then add a command to your |ginit.vim| file to set 'guifont': > - - :set guifont=courier_new:h12 - -============================================================================== -7. Input on X11 *mbyte-XIM* +Input on X11 *mbyte-XIM* X INPUT METHOD (XIM) BACKGROUND *XIM* *xim* *x-input-method* @@ -768,7 +696,7 @@ For example, when you are using kinput2 as |IM-server| and sh, > < ============================================================================== -8. Input on MS-Windows *mbyte-IME* +Input on MS-Windows *mbyte-IME* (Windows IME support) *multibyte-ime* *IME* @@ -842,7 +770,7 @@ Cursor color when IME or XIM is on *CursorIM* status is on. ============================================================================== -9. Input with a keymap *mbyte-keymap* +Input with a keymap *mbyte-keymap* When the keyboard doesn't produce the characters you want to enter in your text, you can use the 'keymap' option. This will translate one or more @@ -1090,7 +1018,7 @@ Combining forms: ﭏ 0xfb4f Xal alef-lamed ============================================================================== -10. Using UTF-8 *mbyte-utf8* *UTF-8* *utf-8* *utf8* +Using UTF-8 *mbyte-utf8* *UTF-8* *utf-8* *utf8* *Unicode* *unicode* The Unicode character set was designed to include all characters from other character sets. Therefore it is possible to write text in any language using @@ -1222,7 +1150,7 @@ not everybody is able to type a composing character. ============================================================================== -11. Overview of options *mbyte-options* +Overview of options *mbyte-options* These options are relevant for editing multi-byte files. Check the help in options.txt for detailed information. diff --git a/runtime/doc/message.txt b/runtime/doc/message.txt index b3a4bf9d72..96c28009c4 100644 --- a/runtime/doc/message.txt +++ b/runtime/doc/message.txt @@ -1,4 +1,4 @@ -*message.txt* For Vim version 7.4. Last change: 2016 Jul 16 +*message.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -8,9 +8,7 @@ This file contains an alphabetical list of messages and error messages that Vim produces. You can use this if you don't understand what the message means. It is not complete though. -1. Old messages |:messages| -2. Error messages |error-messages| -3. Messages |messages| + Type |gO| to see the table of contents. ============================================================================== 1. Old messages *:messages* *:mes* *message-history* @@ -39,10 +37,7 @@ back. Note: If the output has been stopped with "q" at the more prompt, it will only be displayed up to this point. The previous command output is cleared when another command produces output. - -If you are using translated messages, the first printed line tells who -maintains the messages or the translations. You can use this to contact the -maintainer when you spot a mistake. +The "g<" output is not redirected. If you want to find help on a specific (error) message, use the ID at the start of the message. For example, to get help on the message: > @@ -127,8 +122,9 @@ closed properly. Mostly harmless. Command too recursive This happens when an Ex command executes an Ex command that executes an Ex -command, etc. This is only allowed 200 times. When it's more there probably -is an endless loop. Probably a |:execute| or |:source| command is involved. +command, etc. The limit is 200 or the value of 'maxfuncdepth', whatever is +larger. When it's more there probably is an endless loop. Probably a +|:execute| or |:source| command is involved. *E254* > Cannot allocate color {name} @@ -453,12 +449,6 @@ changed. To avoid the message reset the 'warn' option. Something inside Vim went wrong and resulted in a NULL pointer. If you know how to reproduce this problem, please report it. |bugs| - *E172* > - Only one file name allowed - -The ":edit" command only accepts one file name. When you want to specify -several files for editing use ":next" |:next|. - *E41* *E82* *E83* *E342* > Out of memory! Out of memory! (allocating {number} bytes) @@ -635,6 +625,9 @@ starts. It can be fixed in one of these ways: - Just write the file again the next day. Or set your clock to the next day, write the file twice and set the clock back. +If you get W11 all the time, you may need to disable "Acronis Active +Protection" or register Vim as a trusted service/application. + *W12* > Warning: File "{filename}" has changed and the buffer was changed in Vim as well @@ -754,6 +747,13 @@ a user-defined command. You tried to set an option after startup that only allows changes during startup. + *E943* > + Command table needs to be updated, run 'make cmdidxs' + +This can only happen when changing the source code, when adding a command in +src/ex_cmds.h. The lookup table then needs to be updated, by running: > + make cmdidxs + ============================================================================== 3. Messages *messages* diff --git a/runtime/doc/mlang.txt b/runtime/doc/mlang.txt index a2be3cfd49..8284d38fa4 100644 --- a/runtime/doc/mlang.txt +++ b/runtime/doc/mlang.txt @@ -1,4 +1,4 @@ -*mlang.txt* For Vim version 7.4. Last change: 2016 Jan 16 +*mlang.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -11,11 +11,7 @@ multi-byte text see |multibyte|. The basics are explained in the user manual: |usr_45.txt|. -1. Messages |multilang-messages| -2. Menus |multilang-menus| -3. Scripts |multilang-scripts| - -Also see |help-translated| for multi-language help. + Type |gO| to see the table of contents. ============================================================================== 1. Messages *multilang-messages* @@ -176,6 +172,7 @@ Send an e-mail to the Vim maintainer <maintainer@vim.org>. special characters like "&" and "<Tab>" need to be included. Spaces and dots need to be escaped with a backslash, just like in other |:menu| commands. + Case in {english} is ignored. See the $VIMRUNTIME/lang directory for examples. diff --git a/runtime/doc/motion.txt b/runtime/doc/motion.txt index be3170cf92..600eb3ab9e 100644 --- a/runtime/doc/motion.txt +++ b/runtime/doc/motion.txt @@ -1,4 +1,4 @@ -*motion.txt* For Vim version 7.4. Last change: 2016 Jul 12 +*motion.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -10,16 +10,6 @@ These commands move the cursor position. If the new position is off of the screen, the screen is scrolled to show the cursor (see also 'scrolljump' and 'scrolloff' options). -1. Motions and operators |operator| -2. Left-right motions |left-right-motions| -3. Up-down motions |up-down-motions| -4. Word motions |word-motions| -5. Text object motions |object-motions| -6. Text object selection |object-select| -7. Marks |mark-motions| -8. Jumps |jump-motions| -9. Various motions |various-motions| - General remarks: If you want to know where you are in the file use the "CTRL-G" command @@ -36,6 +26,8 @@ The 'virtualedit' option can be set to make it possible to move the cursor to positions where there is no character or within a multi-column character (like a tab). + Type |gO| to see the table of contents. + ============================================================================== 1. Motions and operators *operator* @@ -192,7 +184,7 @@ l or *l* *$* *<End>* *<kEnd>* $ or <End> To the end of the line. When a count is given also go - [count - 1] lines downward |inclusive|. + [count - 1] lines downward. |inclusive| motion. In Visual mode the cursor goes to just after the last character in the line. When 'virtualedit' is active, "$" may move the cursor @@ -894,6 +886,7 @@ was made yet in the current file. then the position can be near the end of what the command changed. For example when inserting a word, the position will be on the last character. + To jump to older changes use |g;|. *'(* *`(* '( `( To the start of the current sentence, like the |(| diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt index c074eb43ff..2d8f5af6d2 100644 --- a/runtime/doc/msgpack_rpc.txt +++ b/runtime/doc/msgpack_rpc.txt @@ -1,4 +1,3 @@ -*msgpack_rpc.txt* {Nvim} NVIM REFERENCE MANUAL by Thiago de Arruda @@ -6,12 +5,7 @@ RPC API for Nvim *RPC* *rpc* *msgpack-rpc* -1. Introduction |rpc-intro| -2. API mapping |rpc-api| -3. Connecting |rpc-connecting| -4. Clients |rpc-api-client| -5. Types |rpc-types| -6. Remote UIs |rpc-remote-ui| + Type |gO| to see the table of contents. ============================================================================== 1. Introduction *rpc-intro* @@ -33,7 +27,7 @@ programs can: The RPC API is like a more powerful version of Vim's `clientserver` feature. ============================================================================== - 2. API mapping *rpc-api* +2. API mapping *rpc-api* The Nvim C |API| is automatically exposed to the RPC API by the build system, which parses headers at src/nvim/api/*. A dispatch function is generated which @@ -66,24 +60,24 @@ To get a formatted dump of the API using python (requires the `pyyaml` and ============================================================================== 3. Connecting *rpc-connecting* -There are several ways to open a msgpack-rpc channel to an Nvim instance: +See |channel-intro|, for various ways to open a channel. Most of the channel +opening functions take an `rpc` key in the options dictionary, to enable rpc. - 1. Through stdin/stdout when `nvim` is started with `--embed`. This is how - applications can embed Nvim. +Additionally, rpc channels can be opened by other processes connecting to +TCP/IP sockets or named pipes listened to by nvim. - 2. Through stdin/stdout of some other process spawned by |jobstart()|. - Set the "rpc" key to |v:true| in the options dict to use the job's stdin - and stdout as a single msgpack channel that is processed directly by - Nvim. Then it is not possible to process raw data to or from the - process's stdin and stdout. stderr can still be used, though. +An rpc socket is automatically created with each instance. The socket + location is stored in |v:servername|. By default this is a named pipe +with an automatically generated address. See |XXX|. - 3. Through the socket automatically created with each instance. The socket - location is stored in |v:servername|. - - 4. Through a TCP/IP socket. To make Nvim listen on a TCP/IP socket, set the - |$NVIM_LISTEN_ADDRESS| environment variable before starting Nvim: > +To make Nvim listen on a TCP/IP socket instead, set the + |$NVIM_LISTEN_ADDRESS| environment variable before starting Nvim: > NVIM_LISTEN_ADDRESS=127.0.0.1:6666 nvim -< +<Also, more sockets and named pipes can be listened on using |serverstart()|. + +Note that localhost TCP sockets are generally less secure than named pipes, +and can lead to vunerabilities like remote code execution. + Connecting to the socket is the easiest way a programmer can test the API, which can be done through any msgpack-rpc client library or full-featured |api-client|. Here's a Ruby script that prints 'hello world!' in the current @@ -180,7 +174,7 @@ contains information that makes this task easier (see also |rpc-types|): even more strongly-typed APIs. - Functions that are considered to be methods that operate on instances of Nvim special types (msgpack EXT) will have the `"method"` attribute set to - `true`. The reciever type is the type of the first argument. The method + `true`. The receiver type is the type of the first argument. The method names are prefixed with `nvim_` plus a shortened type name, e.g. `nvim_buf_get_lines` represents the `get_lines` method of a Buffer instance. - Global functions have `"method"` set to `false` and are prefixed with just @@ -197,7 +191,7 @@ prefix is stripped off. 5. Types *rpc-types* The Nvim C API uses custom types for all functions. |api-types| -For the purpose of mapping to msgpack, the types can be split into two groups: +At the RPC layer, the types can be split into two groups: - Basic types that map natively to msgpack (and probably have a default representation in msgpack-supported programming languages) @@ -219,15 +213,16 @@ Special types (msgpack EXT) ~ Window -> enum value kObjectTypeWindow Tabpage -> enum value kObjectTypeTabpage -An API method expecting one of these types may be passed an integer instead, -although they are not interchangeable. For example, a Buffer may be passed as -an integer, but not a Window or Tabpage. +API functions expecting one of the special EXT types may be passed an integer +instead, but not another EXT type. E.g. Buffer may be passed as an integer but +not as a Window or Tabpage. The EXT object data is the object id encoded as +a msgpack integer: For buffers this is the |bufnr()| and for windows the +|window-ID|. For tabpages the id is an internal handle, not the tabpage +number. + +To determine the type codes of the special EXT types, inspect the `types` key +of the |api-metadata| at runtime. Example JSON representation: > -The most reliable way of determining the type codes for the special Nvim types -is to inspect the `types` key of metadata dictionary returned by the -`nvim_get_api_info` method at runtime. Here's a sample JSON representation of -the `types` object: -> "types": { "Buffer": { "id": 0, @@ -242,176 +237,9 @@ the `types` object: "prefix": "nvim_tabpage_" } } -< + Even for statically compiled clients it is good practice to avoid hardcoding the type codes, because a client may be built against one Nvim version but connect to another with different type codes. -============================================================================== -6. Remote UIs *rpc-remote-ui* - -Nvim allows Graphical user interfaces to be implemented by separate processes -communicating with Nvim over the RPC API. Currently the ui model conists of a -terminal-like grid with one single, monospace font size, with a few elements -that could be drawn separately from the grid (for the momemnt only the popup -menu) - -After connecting to a nvim instance (typically a spawned, embedded instance) -use the |nvim_ui_attach|(width, height, options) API method to tell nvim that your -program wants to draw the nvim screen on a grid with "width" times -"height" cells. "options" should be a dictionary with the following (all -optional) keys: - `rgb`: Controls what color format to use. - Set to true (default) to use 24-bit rgb - colors. - Set to false to use terminal color codes (at - most 256 different colors). - `popupmenu_external`: Instead of drawing the completion popupmenu on - the grid, Nvim will send higher-level events to - the ui and let it draw the popupmenu. - Defaults to false. - -Nvim will then send msgpack-rpc notifications, with the method name "redraw" -and a single argument, an array of screen updates (described below). -These should be processed in order. Preferably the user should only be able to -see the screen state after all updates are processed (not any intermediate -state after processing only a part of the array). - -Screen updates are arrays. The first element a string describing the kind -of update. - -["resize", width, height] - The grid is resized to `width` and `height` cells. - -["clear"] - Clear the screen. - -["eol_clear"] - Clear from the cursor position to the end of the current line. - -["cursor_goto", row, col] - Move the cursor to position (row, col). Currently, the same cursor is - used to define the position for text insertion and the visible cursor. - However, only the last cursor position, after processing the entire - array in the "redraw" event, is intended to be a visible cursor - position. - -["update_fg", color] -["update_bg", color] -["update_sp", color] - Set the default foreground, background and special colors - respectively. - -["highlight_set", attrs] - Set the attributes that the next text put on the screen will have. - `attrs` is a dict with the keys below. Any absent key is reset - to its default value. Color defaults are set by the `update_fg` etc - updates. All boolean keys default to false. - - `foreground`: foreground color. - `background`: backround color. - `special`: color to use for underline and undercurl, when present. - `reverse`: reverse video. Foreground and background colors are - switched. - `italic`: italic text. - `bold`: bold text. - `underline`: underlined text. The line has `special` color. - `undercurl`: undercurled text. The curl has `special` color. - -["put", text] - The (utf-8 encoded) string `text` is put at the cursor position - (and the cursor is advanced), with the highlights as set by the - last `highlight_set` update. - -["set_scroll_region", top, bot, left, right] - Define the scroll region used by `scroll` below. - -["scroll", count] - Scroll the text in the scroll region. The diagrams below illustrate - what will happen, depending on the scroll direction. "=" is used to - represent the SR(scroll region) boundaries and "-" the moved rectangles. - Note that dst and src share a common region. - - If count is bigger than 0, move a rectangle in the SR up, this can - happen while scrolling down. -> - +-------------------------+ - | (clipped above SR) | ^ - |=========================| dst_top | - | dst (still in SR) | | - +-------------------------+ src_top | - | src (moved up) and dst | | - |-------------------------| dst_bot | - | src (cleared) | | - +=========================+ src_bot -< - If count is less than zero, move a rectangle in the SR down, this can - happen while scrolling up. -> - +=========================+ src_top - | src (cleared) | | - |------------------------ | dst_top | - | src (moved down) and dst| | - +-------------------------+ src_bot | - | dst (still in SR) | | - |=========================| dst_bot | - | (clipped below SR) | v - +-------------------------+ -< -["set_title", title] -["set_icon", icon] - Set the window title, and icon (minimized) window title, respectively. - In windowing systems not distinguishing between the two, "set_icon" - can be ignored. - -["mouse_on"] -["mouse_off"] - Tells the client whether mouse support, as determined by |'mouse'| - option, is considered to be active in the current mode. This is mostly - useful for a terminal frontend, or other situations where nvim mouse - 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"] - Nvim started or stopped being busy, and possibly not responsible 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. - -["bell"] -["visual_bell"] - Notify the user with an audible or visual bell, respectively. - -["update_menu"] - The menu mappings changed. - -["mode_change", mode] - The mode changed. Currently sent when "insert", "replace", "cmdline" and - "normal" modes are entered. A client could for instance change the cursor - shape. - -["popupmenu_show", items, selected, row, col] - When `popupmenu_external` is set to true, nvim will not draw the - popupmenu on the grid, instead when the popupmenu is to be displayed - this update is sent. `items` is an array of the items to show, the - items are themselves arrays of the form [word, kind, menu, info] - as defined at |complete-items|, except that `word` is replaced by - `abbr` if present. `selected` is the initially selected item, either a - zero-based index into the array of items, or -1 if no item is - selected. `row` and `col` is the anchor position, where the first - character of the completed word will be. - -["popupmenu_select", selected] - An item in the currently displayed popupmenu is selected. `selected` - is either a zero-based index into the array of items from the last - `popupmenu_show` event, or -1 if no item is selected. - -["popupmenu_hide"] - The popupmenu is hidden. -============================================================================== - vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/nvim.txt b/runtime/doc/nvim.txt index 7dfbbd0cf0..2420227f6c 100644 --- a/runtime/doc/nvim.txt +++ b/runtime/doc/nvim.txt @@ -1,26 +1,30 @@ -*nvim.txt* {Nvim} +*nvim.txt* Nvim NVIM REFERENCE MANUAL -Nvim *nvim* *nvim-intro* +Nvim *nvim* *nvim-intro* -If you are new to Vim (and Nvim) see |help.txt| or type ":Tutor". -If you already use Vim (but not Nvim) see |nvim-from-vim| for a quickstart. +Nvim is based on Vim by Bram Moolenaar. + +If you are new to Vim see |help.txt|, or type ":Tutor". +If you already use Vim see |nvim-from-vim| for a quickstart. Nvim is emphatically a fork of Vim, not a clone: compatibility with Vim is maintained where possible. See |vim_diff.txt| for the complete reference of differences from Vim. + Type |gO| to see the table of contents. + ============================================================================== Transitioning from Vim *nvim-from-vim* -To start the transition, link your previous configuration so Nvim can use it: +To start the transition, create ~/.config/nvim/init.vim with these contents: > - mkdir ~/.config - ln -s ~/.vim ~/.config/nvim - ln -s ~/.vimrc ~/.config/nvim/init.vim + set runtimepath^=~/.vim runtimepath+=~/.vim/after + let &packpath = &runtimepath + source ~/.vimrc < Note: If your system sets `$XDG_CONFIG_HOME`, use that instead of `~/.config` in the code above. Nvim follows the XDG |base-directories| convention. diff --git a/runtime/doc/nvim_terminal_emulator.txt b/runtime/doc/nvim_terminal_emulator.txt index 0954dcb5a7..94e7899b6a 100644 --- a/runtime/doc/nvim_terminal_emulator.txt +++ b/runtime/doc/nvim_terminal_emulator.txt @@ -1,22 +1,27 @@ -*terminal_emulator.txt* {Nvim} +*terminal_emulator.txt* Nvim NVIM REFERENCE MANUAL by Thiago de Arruda -Terminal emulator *terminal-emulator* +Terminal emulator *terminal* *terminal-emulator* Nvim embeds a VT220/xterm terminal emulator based on libvterm. The terminal is presented as a special buffer type, asynchronously updated from the virtual terminal as data is received from the program connected to it. -Terminal buffers behave mostly like normal 'nomodifiable' buffers, except: -- Plugins can set 'modifiable' to modify text, but lines cannot be deleted. -- 'scrollback' controls how many off-screen lines are kept. -- Terminal output is followed if the cursor is on the last line. +Terminal buffers behave like normal buffers, except: +- With 'modifiable', lines can be edited but not deleted. +- 'scrollback' controls how many lines are kept. +- Output is followed if the cursor is on the last line. +- 'modified' is the default. You can set 'nomodified' to avoid a warning when + closing the terminal buffer. +- 'bufhidden' defaults to "hide". + + Type |gO| to see the table of contents. ============================================================================== -Spawning *terminal-emulator-spawning* +Start *terminal-start* There are 3 ways to create a terminal buffer: @@ -33,37 +38,42 @@ There are 3 ways to create a terminal buffer: autocmd VimEnter * nested split term://sh < This is only mentioned for reference; use |:terminal| instead. -When the terminal spawns the program, the buffer will start to mirror the -terminal display and change its name to `term://{cwd}//{pid}:{cmd}`. -The "term://..." scheme enables |:mksession| to "restore" a terminal buffer by -restarting the {cmd} when the session is loaded. +When the terminal starts, the buffer contents are updated and the buffer is +named in the form of `term://{cwd}//{pid}:{cmd}`. This naming scheme is used +by |:mksession| to restore a terminal buffer (by restarting the {cmd}). ============================================================================== -Input *terminal-emulator-input* +Input *terminal-input* -To send input, enter terminal mode using any command that would enter "insert +To send input, enter |Terminal-mode| using any command that would enter "insert mode" in a normal buffer, such as |i| or |:startinsert|. In this mode all keys except <C-\><C-N> are sent to the underlying program. Use <C-\><C-N> to return -to normal mode. |CTRL-\_CTRL-N| +to normal-mode. |CTRL-\_CTRL-N| + +Terminal-mode has its own |:tnoremap| namespace for mappings, this can be used +to automate any terminal interaction. -Terminal mode has its own |:tnoremap| namespace for mappings, this can be used -to automate any terminal interaction. To map <Esc> to exit terminal mode: > +To map <Esc> to exit terminal-mode: > :tnoremap <Esc> <C-\><C-n> -< -Navigating to other windows is only possible in normal mode. For convenience, -you could use these mappings: > - :tnoremap <A-h> <C-\><C-n><C-w>h - :tnoremap <A-j> <C-\><C-n><C-w>j - :tnoremap <A-k> <C-\><C-n><C-w>k - :tnoremap <A-l> <C-\><C-n><C-w>l + +To simulate |i_CTRL-R| in terminal-mode: > + :tnoremap <expr> <C-R> '<C-\><C-N>"'.nr2char(getchar()).'pi' + +To use `ALT+{h,j,k,l}` to navigate windows from any mode: > + :tnoremap <A-h> <C-\><C-N><C-w>h + :tnoremap <A-j> <C-\><C-N><C-w>j + :tnoremap <A-k> <C-\><C-N><C-w>k + :tnoremap <A-l> <C-\><C-N><C-w>l + :inoremap <A-h> <C-\><C-N><C-w>h + :inoremap <A-j> <C-\><C-N><C-w>j + :inoremap <A-k> <C-\><C-N><C-w>k + :inoremap <A-l> <C-\><C-N><C-w>l :nnoremap <A-h> <C-w>h :nnoremap <A-j> <C-w>j :nnoremap <A-k> <C-w>k :nnoremap <A-l> <C-w>l -< -Then you can use `Alt+{h,j,k,l}` to navigate between windows from any mode. -Mouse input is supported, and has the following behavior: +Mouse input has the following behavior: - If the program has enabled mouse events, the corresponding events will be forwarded to the program. @@ -75,23 +85,31 @@ Mouse input is supported, and has the following behavior: the terminal wont lose focus and the hovered window will be scrolled. ============================================================================== -Configuration *terminal-emulator-configuration* +Configuration *terminal-configuration* -Options: 'scrollback' +Options: 'modified', 'scrollback' Events: |TermOpen|, |TermClose| Highlight groups: |hl-TermCursor|, |hl-TermCursorNC| -Terminal colors can be customized with these variables: +Terminal sets local defaults for some options, which may differ from your +global configuration. + +- 'list' is disabled +- 'wrap' is disabled +- 'relativenumber' is disabled in |Terminal-mode| (and cannot be enabled) + +You can change the defaults with a TermOpen autocommand: > + au TermOpen * setlocal list -- `{g,b}:terminal_color_$NUM`: The terminal color palette, where `$NUM` is the - color index, between 0 and 255 inclusive. This setting only affects UIs with - RGB capabilities; for normal terminals the color index is simply forwarded. +TERMINAL COLORS ~ -The `{g,b}:terminal_color_$NUM` variables are processed only when the terminal -starts (after |TermOpen|). +The `{g,b}:terminal_color_$NUM` variables control the terminal color palette, +where `$NUM` is the color index between 0 and 255 inclusive. This setting only +affects UIs with RGB capabilities; for normal terminals the color index is +just forwarded. The variables are read only during |TermOpen|. ============================================================================== -Status Variables *terminal-emulator-status* +Status Variables *terminal-status* Terminal buffers maintain some information about the terminal in buffer-local variables: @@ -99,8 +117,8 @@ variables: - *b:term_title* The settable title of the terminal, typically displayed in the window title or tab title of a graphical terminal emulator. Programs running in the terminal can set this title via an escape sequence. -- *b:terminal_job_id* The nvim job ID of the job running in the terminal. See - |job-control| for more information. +- |'channel'| The nvim channel ID for the underlying PTY. + |chansend()| can be used to send input to the terminal. - *b:terminal_job_pid* The PID of the top-level process running in the terminal. diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt index 23d8287a2c..4fe2e07909 100644 --- a/runtime/doc/options.txt +++ b/runtime/doc/options.txt @@ -1,4 +1,4 @@ -*options.txt* For Vim version 7.4. Last change: 2016 Jul 12 +*options.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -6,11 +6,7 @@ Options *options* -1. Setting options |set-option| -2. Automatically setting options |auto-setting| -3. Options summary |option-summary| - -For an overview of options see help.txt |option-list|. +For an overview of options see quickref.txt |option-list|. Vim has a number of internal variables and switches which can be set to achieve special effects. These options come in three forms: @@ -18,18 +14,15 @@ achieve special effects. These options come in three forms: number has a numeric value string has a string value + Type |gO| to see the table of contents. + ============================================================================== 1. Setting options *set-option* *E764* *:se* *:set* :se[t] Show all options that differ from their default value. -:se[t] all Show all but terminal options. - -:se[t] termcap Show all terminal options. Note that in the GUI the - key codes are not shown, because they are generated - internally and can't be changed. Changing the terminal - codes in the GUI is not useful either... +:se[t] all Show all options. *E518* *E519* :se[t] {option}? Show value of {option}. @@ -130,39 +123,6 @@ A few special texts: Last set from error handler ~ Option was cleared when evaluating it resulted in an error. -{not available when compiled without the |+eval| feature} - - *:set-termcap* *E522* -For {option} the form "t_xx" may be used to set a terminal option. This will -override the value from the termcap. You can then use it in a mapping. If -the "xx" part contains special characters, use the <t_xx> form: > - :set <t_#4>=^[Ot -This can also be used to translate a special code for a normal key. For -example, if Alt-b produces <Esc>b, use this: > - :set <M-b>=^[b -(the ^[ is a real <Esc> here, use CTRL-V <Esc> to enter it) -The advantage over a mapping is that it works in all situations. - -You can define any key codes, e.g.: > - :set t_xy=^[foo; -There is no warning for using a name that isn't recognized. You can map these -codes as you like: > - :map <t_xy> something -< *E846* -When a key code is not set, it's like it does not exist. Trying to get its -value will result in an error: > - :set t_kb= - :set t_kb - E846: Key code not set: t_kb - -The t_xx options cannot be set from a |modeline| or in the |sandbox|, for -security reasons. - -The listing from ":set" looks different from Vi. Long string options are put -at the end of the list. The number of options is quite large. The output of -"set all" probably does not fit on the screen, causing Vim to give the -|more-prompt|. - *option-backslash* To include white space in a string option value it has to be preceded with a backslash. To include a backslash you have to use two. Effectively this @@ -227,7 +187,7 @@ opt+=val" the expansion is done before the adding or removing. Handling of local options *local-options* Some of the options only apply to a window or buffer. Each window or buffer -has its own copy of this option, thus can each have their own value. This +has its own copy of this option, thus each can have its own value. This allows you to set 'list' in one window but not in another. And set 'shiftwidth' to 3 in one buffer and 4 in another. @@ -351,7 +311,7 @@ Note: In the future more global options can be made global-local. Using Setting the filetype -:setf[iletype] {filetype} *:setf* *:setfiletype* +:setf[iletype] [FALLBACK] {filetype} *:setf* *:setfiletype* Set the 'filetype' option to {filetype}, but only if not done yet in a sequence of (nested) autocommands. This is short for: > @@ -362,6 +322,12 @@ Setting the filetype setting the 'filetype' option twice, causing different settings and syntax files to be loaded. + When the optional FALLBACK argument is present, a + later :setfiletype command will override the + 'filetype'. This is to used for filetype detections + that are just a guess. |did_filetype()| will return + false after this command. + *option-window* *optwin* :bro[wse] se[t] *:set-browse* *:browse-set* *:opt* *:options* :opt[ions] Open a window for viewing and setting all options. @@ -388,30 +354,27 @@ On Unix systems the form "${HOME}" can be used too. The name between {} can contain non-id characters then. Note that if you want to use this for the "gf" command, you need to add the '{' and '}' characters to 'isfname'. +NOTE: expanding environment variables and "~/" is only done with the ":set" +command, not when assigning a value to an option with ":let". + + *$HOME-windows* On MS-Windows, if $HOME is not defined as an environment variable, then at runtime Vim will set it to the expansion of $HOMEDRIVE$HOMEPATH. +If $HOMEDRIVE is not set then $USERPROFILE is used. -NOTE: expanding environment variables and "~/" is only done with the ":set" -command, not when assigning a value to an option with ":let". +This expanded value is not exported to the environment, this matters when +running an external command: > + :echo system('set | findstr ^HOME=') +and > + :echo luaeval('os.getenv("HOME")') +should echo nothing (an empty string) despite exists('$HOME') being true. +When setting $HOME to a non-empty string it will be exported to the +subprocesses. Note the maximum length of an expanded option is limited. How much depends on the system, mostly it is something like 256 or 1024 characters. - *Linux-backspace* - Note about Linux: By default the backspace key - produces CTRL-?, which is wrong. You can fix it by - putting this line in your rc.local: > - echo "keycode 14 = BackSpace" | loadkeys -< - *NetBSD-backspace* - Note about NetBSD: If your backspace doesn't produce - the right code, try this: > - xmodmap -e "keycode 22 = BackSpace" -< If this works, add this in your .Xmodmap file: > - keysym 22 = BackSpace -< You need to restart for this to take effect. - ============================================================================== 2. Automatically setting options *auto-setting* @@ -642,7 +605,7 @@ A jump table for the options with a short description can be found at |Q_op|. See Unicode Standard Annex #11 (http://www.unicode.org/reports/tr11). Vim may set this option automatically at startup time when Vim is - compiled with the |+termresponse| feature and if |t_u7| is set to the + compiled with the |+termresponse| feature and if t_u7 is set to the escape sequence to request cursor position report. *'autochdir'* *'acd'* *'noautochdir'* *'noacd'* @@ -765,6 +728,13 @@ A jump table for the options with a short description can be found at |Q_op|. < Vim will guess the value. In the GUI this should work correctly, in other cases Vim might not be able to guess the right value. + When the |t_RB| option is set, Vim will use it to request the background + color from the terminal. If the returned RGB value is dark/light and + 'background' is not dark/light, 'background' will be set and the + screen is redrawn. This may have side effects, make t_BG empty in + your .vimrc if you suspect this problem. The response to |t_RB| can + be found in |v:termrbgresp|. + When starting the GUI, the default value for 'background' will be "light". When the value is not set in the gvimrc, and Vim detects that the background is actually quite dark, 'background' is set to @@ -1013,8 +983,8 @@ A jump table for the options with a short description can be found at |Q_op|. wildmode More matches in |cmdline-completion| available (depends on the 'wildmode' setting). - This is most useful, to fine tune when in insert mode the bell should - be rung. For normal mode and ex commands, the bell is often rung to + This is most useful to fine tune when in Insert mode the bell should + be rung. For Normal mode and Ex commands, the bell is often rung to indicate that an error occurred. It can be silenced by adding the "error" keyword. @@ -1243,6 +1213,12 @@ A jump table for the options with a short description can be found at |Q_op|. < |Nvi| also has this option, but it only uses the first character. See |cmdwin|. + *'channel'* +'channel' number (default: 0) + local to buffer + |Channel| connected to the buffer. Currently only used by + |terminal-emulator|. Is 0 if no terminal is open. Cannot be changed. + *'charconvert'* *'ccv'* *E202* *E214* *E513* 'charconvert' 'ccv' string (default "") global @@ -1349,27 +1325,6 @@ A jump table for the options with a short description can be found at |Q_op|. will additionally copy the text into register '*'. See |clipboard|. - *clipboard-autoselect* - autoselect Works like the 'a' flag in 'guioptions': If present, - then whenever Visual mode is started, or the Visual - area extended, Vim tries to become the owner of the - windowing system's global selection or put the - selected text on the clipboard used by the selection - register "*. See |guioptions_a| and |quotestar| for - details. When the GUI is active, the 'a' flag in - 'guioptions' is used, when the GUI is not active, this - "autoselect" flag is used. - Also applies to the modeless selection. - - *clipboard-autoselectplus* - autoselectplus Like "autoselect" but using the + register instead of - the * register. Compare to the 'P' flag in - 'guioptions'. - - *clipboard-autoselectml* - autoselectml Like "autoselect", but for the modeless selection - only. Compare to the 'A' flag in 'guioptions'. - *'cmdheight'* *'ch'* 'cmdheight' 'ch' number (default 1) global @@ -1620,7 +1575,6 @@ A jump table for the options with a short description can be found at |Q_op|. results in X being mapped to: 'B' included: "\^[" (^[ is a real <Esc>) 'B' excluded: "<Esc>" (5 characters) - ('<' excluded in both cases) *cpo-c* c Searching continues at the end of any match at the cursor position, but not further than the start of the @@ -1670,15 +1624,6 @@ A jump table for the options with a short description can be found at |Q_op|. J A |sentence| has to be followed by two spaces after the '.', '!' or '?'. A <Tab> is not recognized as white space. - *cpo-k* - k Disable the recognition of raw key codes in - mappings, abbreviations, and the "to" part of menu - commands. For example, if <Key> sends ^[OA (where ^[ - is <Esc>), the command ":map X ^[OA" results in X - being mapped to: - 'k' included: "^[OA" (3 characters) - 'k' excluded: "<Key>" (one key code) - Also see the '<' flag below. *cpo-K* K Don't wait for a key code to complete when it is halfway through a mapping. This breaks mapping @@ -1812,14 +1757,6 @@ A jump table for the options with a short description can be found at |Q_op|. + When included, a ":write file" command will reset the 'modified' flag of the buffer, even though the buffer itself may still be different from its file. - *cpo-<* - < Disable the recognition of special key codes in |<>| - form in mappings, abbreviations, and the "to" part of - menu commands. For example, the command - ":map X <Tab>" results in X being mapped to: - '<' included: "<Tab>" (5 characters) - '<' excluded: "^I" (^I is a real <Tab>) - Also see the 'k' flag above. *cpo->* > When appending to a register, put a line break before the appended text. @@ -2106,7 +2043,7 @@ A jump table for the options with a short description can be found at |Q_op|. uhex Show unprintable characters hexadecimal as <xx> instead of using ^C and ~C. - When neither "lastline" or "truncate" is included, a last line that + When neither "lastline" nor "truncate" is included, a last line that doesn't fit is replaced with "@" lines. *'eadirection'* *'ead'* @@ -2233,10 +2170,15 @@ A jump table for the options with a short description can be found at |Q_op|. *'exrc'* *'ex'* *'noexrc'* *'noex'* 'exrc' 'ex' boolean (default off) global - Enables the reading of .nvimrc and .exrc in the current directory. - If you switch this option on you should also consider setting the - 'secure' option (see |initialization|). Using this option comes - with a potential security risk, use with care! + Enables the reading of .vimrc and .exrc in the current directory. + Setting this option is a potential security leak. E.g., consider + unpacking a package or fetching files from github, a .vimrc in there + might be a trojan horse. BETTER NOT SET THIS OPTION! + Instead, define an autocommand in your .vimrc to set options for a + matching directory. + + If you do switch this option on you should also consider setting the + 'secure' option (see |initialization|). This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. Also see |init.vim| and |gui-init|. @@ -2731,7 +2673,7 @@ A jump table for the options with a short description can be found at |Q_op|. *'formatprg'* *'fp'* 'formatprg' 'fp' string (default "") - global + global or local to buffer |global-local| The name of an external program that will be used to format the lines selected with the |gq| operator. The program must take the input on stdin and produce the output on stdout. The Unix program "fmt" is @@ -2754,6 +2696,9 @@ A jump table for the options with a short description can be found at |Q_op|. mode, so it may be undesirable in some situations. Be warned that turning this off increases the chances of data loss after a crash. + Currently applies only to writing the buffer with e.g. |:w| and + |writefile()|. + *'gdefault'* *'gd'* *'nogdefault'* *'nogd'* 'gdefault' 'gd' boolean (default off) global @@ -2776,8 +2721,7 @@ A jump table for the options with a short description can be found at |Q_op|. *'grepprg'* *'gp'* 'grepprg' 'gp' string (default "grep -n ", - Unix: "grep -n $* /dev/null", - Win32: "findstr /n" or "grep -n") + Unix: "grep -n $* /dev/null") global or local to buffer |global-local| Program to use for the |:grep| command. This option may contain '%' and '#' characters, which are expanded like when used in a command- @@ -2792,33 +2736,24 @@ A jump table for the options with a short description can be found at |Q_op|. |:vimgrepadd| and |:lgrepadd| like |:lvimgrepadd|. See also the section |:make_makeprg|, since most of the comments there apply equally to 'grepprg'. - For Win32, the default is "findstr /n" if "findstr.exe" can be found, - otherwise it's "grep -n". This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. *'guicursor'* *'gcr'* *E545* *E546* *E548* *E549* -'guicursor' 'gcr' string (default "n-v-c:block-Cursor/lCursor, - ve:ver35-Cursor, - o:hor50-Cursor, - i-ci:ver25-Cursor/lCursor, - r-cr:hor20-Cursor/lCursor, - sm:block-Cursor - -blinkwait175-blinkoff150-blinkon175", - for Windows console: - "n-v-c:block,o:hor50,i-ci:hor15, - r-cr:hor30,sm:block") - global - {only available when compiled with GUI enabled, and - for Windows console} - This option tells Vim what the cursor should look like in different - modes. It fully works in the GUI. In a Windows console, only - the height of the cursor can be changed. This can be done by - specifying a block cursor, or a percentage for a vertical or - horizontal cursor. - For a console the 't_SI' and 't_EI' escape sequences are used. - - The option is a comma separated list of parts. Each part consist of a +'guicursor' 'gcr' string (default "n-v-c-sm:block,i-ci-ve:ver25,r-cr-o:hor20") + global + Configures the cursor style for each mode. Works in the GUI and many + terminals. See |tui-cursor-shape|. + + To disable cursor-styling, reset the option: > + :set guicursor= + +< To enable mode shapes, "Cursor" highlight, and blinking: > + :set guicursor=n-v-c:block,i-ci-ve:ver25,r-cr:hor20,o:hor50 + \,a:blinkwait700-blinkoff400-blinkon250-Cursor/lCursor + \,sm:block-blinkwait175-blinkoff150-blinkon175 + +< The option is a comma separated list of parts. Each part consists of a mode-list and an argument-list: mode-list:argument-list,mode-list:argument-list,.. The mode-list is a dash separated list of these modes: @@ -2846,16 +2781,9 @@ A jump table for the options with a short description can be found at |Q_op|. the cursor starts blinking, blinkon is the time that the cursor is shown and blinkoff is the time that the cursor is not shown. The times are in msec. When one - of the numbers is zero, there is no blinking. The - default is: "blinkwait700-blinkon400-blinkoff250". - These numbers are used for a missing entry. This - means that blinking is enabled by default. To switch - blinking off you can use "blinkon0". The cursor only - blinks when Vim is waiting for input, not while - executing a command. - To make the cursor blink in an xterm, see - |xterm-blink|. - {group-name} + of the numbers is zero, there is no blinking. E.g.: > + :set guicursor=n:blinkon0 +< {group-name} a highlight group name, that sets the color and font for the cursor {group-name}/{group-name} @@ -2991,18 +2919,6 @@ A jump table for the options with a short description can be found at |Q_op|. If set and valid, 'guifontwide' is used for IME instead of 'guifont'. - *'guiheadroom'* *'ghr'* -'guiheadroom' 'ghr' number (default 50) - global - {only for X11 GUI} - The number of pixels subtracted from the screen height when fitting - the GUI window on the screen. Set this before the GUI is started, - e.g., in your |gvimrc| file. When zero, the whole screen height will - be used by the window. When positive, the specified number of pixel - lines will be left for window decorations and other items on the - screen. Set it to a negative value to allow windows taller than the - screen. - *'guioptions'* *'go'* 'guioptions' 'go' string (default "egmrLT" (MS-Windows)) global @@ -3060,7 +2976,7 @@ A jump table for the options with a short description can be found at |Q_op|. that this flag must be added in the vimrc file, before switching on syntax or filetype recognition (when the |gvimrc| file is sourced the system menu has already been loaded; the - ":syntax on" and ":filetype on" commands load the menu too). + `:syntax on` and `:filetype on` commands load the menu too). *'go-g'* 'g' Grey menu items: Make menu items that are not active grey. If 'g' is not included inactive menu items are not shown at all. @@ -3110,6 +3026,8 @@ A jump table for the options with a short description can be found at |Q_op|. The format of this option is like that of 'statusline'. 'guitabtooltip' is used for the tooltip, see below. + The expression will be evaluated in the |sandbox| when set from a + modeline, see |sandbox-option|. Only used when the GUI tab pages line is displayed. 'e' must be present in 'guioptions'. For the non-GUI tab pages line 'tabline' is @@ -3185,109 +3103,6 @@ A jump table for the options with a short description can be found at |Q_op|. WARNING: It's easy to forget that you have changes in hidden buffers. Think twice when using ":q!" or ":qa!". - *'highlight'* *'hl'* -'highlight' 'hl' string (default (as a single string): - "8:SpecialKey,~:EndOfBuffer,z:TermCursor, - Z:TermCursorNC,@:NonText,d:Directory, - e:ErrorMsg,i:IncSearch,l:Search, - m:MoreMsg,M:ModeMsg,n:LineNr, - N:CursorLineNr,r:Question,s:StatusLine, - S:StatusLineNC,c:VertSplit,t:Title, - v:Visual,w:WarningMsg,W:WildMenu, - f:Folded,F:FoldColumn,A:DiffAdd, - C:DiffChange,D:DiffDelete,T:DiffText, - >:SignColumn,B:SpellBad,P:SpellCap, - R:SpellRare,L:SpellLocal,-:Conceal, - +:Pmenu,=:PmenuSel,x:PmenuSbar, - X:PmenuThumb") - global - This option can be used to set highlighting mode for various - occasions. It is a comma separated list of character pairs. The - first character in a pair gives the occasion, the second the mode to - use for that occasion. The occasions are: - |hl-SpecialKey| 8 Meta and special keys listed with ":map" - |hl-EndOfBuffer| ~ lines after the last line in the buffer - |hl-TermCursor| z Cursor in a focused terminal - |hl-TermCursorNC| Z Cursor in an unfocused terminal - |hl-NonText| @ '@' at the end of the window and - characters from 'showbreak' - |hl-Directory| d directories in CTRL-D listing and other special - things in listings - |hl-ErrorMsg| e error messages - |hl-IncSearch| i 'incsearch' highlighting - |hl-Search| l last search pattern highlighting (see 'hlsearch') - |hl-MoreMsg| m |more-prompt| - |hl-ModeMsg| M Mode (e.g., "-- INSERT --") - |hl-LineNr| n line number for ":number" and ":#" commands, and - when 'number' or 'relativenumber' option is set. - |hl-CursorLineNr| N like n for when 'cursorline' or 'relativenumber' is - set. - |hl-Question| r |hit-enter| prompt and yes/no questions - |hl-StatusLine| s status line of current window |status-line| - |hl-StatusLineNC| S status lines of not-current windows - |hl-Title| t Titles for output from ":set all", ":autocmd" etc. - |hl-VertSplit| c column used to separate vertically split windows - |hl-Visual| v Visual mode - |hl-WarningMsg| w warning messages - |hl-WildMenu| W wildcard matches displayed for 'wildmenu' - |hl-Folded| f line used for closed folds - |hl-FoldColumn| F 'foldcolumn' - |hl-DiffAdd| A added line in diff mode - |hl-DiffChange| C changed line in diff mode - |hl-DiffDelete| D deleted line in diff mode - |hl-DiffText| T inserted text in diff mode - |hl-SignColumn| > column used for |signs| - |hl-SpellBad| B misspelled word |spell| - |hl-SpellCap| P word that should start with capital |spell| - |hl-SpellRare| R rare word |spell| - |hl-SpellLocal| L word from other region |spell| - |hl-Conceal| - the placeholders used for concealed characters - (see 'conceallevel') - |hl-Pmenu| + popup menu normal line - |hl-PmenuSel| = popup menu normal line - |hl-PmenuSbar| x popup menu scrollbar - |hl-PmenuThumb| X popup menu scrollbar thumb - - The display modes are: - r reverse (termcap entry "mr" and "me") - i italic (termcap entry "ZH" and "ZR") - b bold (termcap entry "md" and "me") - s standout (termcap entry "so" and "se") - u underline (termcap entry "us" and "ue") - c undercurl (termcap entry "Cs" and "Ce") - n no highlighting - - no highlighting - : use a highlight group - The default is used for occasions that are not included. - When using the ':' display mode, this must be followed by the name of - a highlight group. A highlight group can be used to define any type - of highlighting, including using color. See |:highlight| on how to - define one. The default uses a different group for each occasion. - See |highlight-default| for the default highlight groups. - - *'hlsearch'* *'hls'* *'nohlsearch'* *'nohls'* -'hlsearch' 'hls' boolean (default on) - global - {not available when compiled without the - |+extra_search| feature} - When there is a previous search pattern, highlight all its matches. - The type of highlighting used can be set with the 'l' occasion in the - 'highlight' option. This uses the "Search" highlight group by - default. Note that only the matching text is highlighted, any offsets - are not applied. - See also: 'incsearch' and |:match|. - When you get bored looking at the highlighted matches, you can turn it - off with |:nohlsearch|. This does not change the option value, as - soon as you use a search command, the highlighting comes back. - 'redrawtime' specifies the maximum time spent on finding matches. - When the search pattern can match an end-of-line, Vim will try to - highlight all of the matched text. However, this depends on where the - search starts. This will be the first line in the window or the first - line below a closed fold. A match in a previous line which is not - drawn may not continue in a newly drawn line. - You can specify whether the highlight status is restored on startup - with the 'h' flag in 'shada' |shada-h|. - *'history'* *'hi'* 'history' 'hi' number (Vim default: 10000, Vi default: 0) global @@ -3310,6 +3125,27 @@ A jump table for the options with a short description can be found at |Q_op|. This is useful if you have a non-Hebrew keyboard. See |rileft.txt|. + *'hlsearch'* *'hls'* *'nohlsearch'* *'nohls'* +'hlsearch' 'hls' boolean (default on) + global + {not available when compiled without the + |+extra_search| feature} + When there is a previous search pattern, highlight all its matches. + The |hl-Search| highlight group determines the highlighting. Note that + only the matching text is highlighted, any offsets are not applied. + See also: 'incsearch' and |:match|. + When you get bored looking at the highlighted matches, you can turn it + off with |:nohlsearch|. This does not change the option value, as + soon as you use a search command, the highlighting comes back. + 'redrawtime' specifies the maximum time spent on finding matches. + When the search pattern can match an end-of-line, Vim will try to + highlight all of the matched text. However, this depends on where the + search starts. This will be the first line in the window or the first + line below a closed fold. A match in a previous line which is not + drawn may not continue in a newly drawn line. + You can specify whether the highlight status is restored on startup + with the 'h' flag in 'shada' |shada-h|. + *'icon'* *'noicon'* 'icon' boolean (default off, on when title can be restored) global @@ -3459,10 +3295,12 @@ A jump table for the options with a short description can be found at |Q_op|. original position when no match is found and when pressing <Esc>. You still need to finish the search command with <Enter> to move the cursor to the match. + You can use the CTRL-G and CTRL-T keys to move to the next and + previous match. |c_CTRL-G| |c_CTRL-T| Vim only searches for about half a second. With a complicated pattern and/or a lot of text the match may not be found. This is to avoid that Vim hangs while you are typing the pattern. - The highlighting can be set with the 'i' flag in 'highlight'. + The |hl-IncSearch| highlight group determines the highlighting. See also: 'hlsearch'. CTRL-L can be used to add one character from after the current match to the command line. If 'ignorecase' and 'smartcase' are set and the @@ -3532,7 +3370,7 @@ A jump table for the options with a short description can be found at |Q_op|. if you want to use Vim as a modeless editor. These Insert mode commands will be useful: - Use the cursor keys to move around. - - Use CTRL-O to execute one Normal mode command |i_CTRL-O|). When + - Use CTRL-O to execute one Normal mode command |i_CTRL-O|. When this is a mapping, it is executed as if 'insertmode' was off. Normal mode remains active until the mapping is finished. - Use CTRL-L to execute a number of Normal mode commands, then use @@ -3722,6 +3560,8 @@ A jump table for the options with a short description can be found at |Q_op|. be able to execute Normal mode commands. This is the opposite of the 'keymap' option, where characters are mapped in Insert mode. + Also consider resetting 'langremap' to avoid 'langmap' applies to + characters resulting from a mapping. This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. @@ -3776,12 +3616,12 @@ A jump table for the options with a short description can be found at |Q_op|. :source $VIMRUNTIME/menu.vim < Warning: This deletes all menus that you defined yourself! - *'langnoremap'* *'lnr'* -'langnoremap' 'lnr' boolean (default on) + *'langremap'* *'lrm'* *'nolangremap'* *'nolrm'* +'langremap' 'lrm' boolean (default off) global - When on, setting 'langmap' does not apply to characters resulting from + When off, setting 'langmap' does not apply to characters resulting from a mapping. If setting 'langmap' disables some of your mappings, make - sure this option is set. + sure this option is off. *'laststatus'* *'ls'* 'laststatus' 'ls' number (default 2) @@ -3830,9 +3670,6 @@ A jump table for the options with a short description can be found at |Q_op|. use this command to get the tallest window possible: > :set lines=999 < Minimum value is 2, maximum value is 1000. - If you get less lines than expected, check the 'guiheadroom' option. - When you set this option and Vim is unable to change the physical - number of lines of the display, the display may be messed up. *'linespace'* *'lsp'* 'linespace' 'lsp' number (default 0, 1 for Win32 GUI) @@ -3932,9 +3769,8 @@ A jump table for the options with a short description can be found at |Q_op|. :set lcs=tab:>-,trail:- :set lcs=tab:>-,eol:<,nbsp:% :set lcs=extends:>,precedes:< -< The "NonText" highlighting will be used for "eol", "extends" and - "precedes". "SpecialKey" for "nbsp", "space", "tab" and "trail". - |hl-NonText| |hl-SpecialKey| +< |hl-NonText| highlighting will be used for "eol", "extends" and + "precedes". |hl-Whitespace| for "nbsp", "space", "tab" and "trail". *'lpl'* *'nolpl'* *'loadplugins'* *'noloadplugins'* 'loadplugins' 'lpl' boolean (default on) @@ -3950,10 +3786,11 @@ A jump table for the options with a short description can be found at |Q_op|. global Changes the special characters that can be used in search patterns. See |pattern|. - NOTE: To avoid portability problems with using patterns, always keep - this option at the default "on". Only switch it off when working with - old Vi scripts. In any other situation write patterns that work when - 'magic' is on. Include "\M" when you want to |/\M|. + WARNING: Switching this option off most likely breaks plugins! That + is because many patterns assume it's on and will fail when it's off. + Only switch it off when working with old Vi scripts. In any other + situation write patterns that work when 'magic' is on. Include "\M" + when you want to |/\M|. *'makeef'* *'mef'* 'makeef' 'mef' string (default: "") @@ -4008,7 +3845,7 @@ A jump table for the options with a short description can be found at |Q_op|. :au FileType c,cpp,java set mps+==:; < For a more advanced way of using "%", see the matchit.vim plugin in - the $VIMRUNTIME/macros directory. |add-local-help| + the $VIMRUNTIME/plugin directory. |add-local-help| *'matchtime'* *'mat'* 'matchtime' 'mat' number (default 5) @@ -4038,6 +3875,8 @@ A jump table for the options with a short description can be found at |Q_op|. catches endless recursion. When using a recursive function with more depth, set 'maxfuncdepth' to a bigger number. But this will use more memory, there is the danger of failing when memory is exhausted. + Increasing this limit above 200 also changes the maximum for Ex + command resursion, see |E169|. See also |:function|. *'maxmapdepth'* *'mmd'* *E223* @@ -4149,7 +3988,7 @@ A jump table for the options with a short description can be found at |Q_op|. local to buffer When off the buffer contents cannot be changed. The 'fileformat' and 'fileencoding' options also can't be changed. - Can be reset with the |-M| command line argument. + Can be reset on startup with the |-M| command line argument. *'modified'* *'mod'* *'nomodified'* *'nomod'* 'modified' 'mod' boolean (default off) @@ -4182,7 +4021,7 @@ A jump table for the options with a short description can be found at |Q_op|. listing continues until finished. *'mouse'* *E538* -'mouse' string (default "a") +'mouse' string (default "") global Enable the use of the mouse. Only works for certain terminals. @@ -4442,7 +4281,7 @@ A jump table for the options with a short description can be found at |Q_op|. *'paste'* *'nopaste'* 'paste' boolean (default off) global - You probably don't have to set this option: |bracketed-paste-mode|. + This option is obsolete; |bracketed-paste-mode| is built-in. Put Vim in Paste mode. This is useful if you want to cut or copy some text from one window and paste it in Vim. This will avoid @@ -4506,7 +4345,8 @@ A jump table for the options with a short description can be found at |Q_op|. Note that typing <F10> in paste mode inserts "<F10>", since in paste mode everything is inserted literally, except the 'pastetoggle' key sequence. - When the value has several bytes 'ttimeoutlen' applies. + No timeout is used, this means that a multi-key 'pastetoggle' can not + be triggered manually. *'pex'* *'patchexpr'* 'patchexpr' 'pex' string (default "") @@ -4646,6 +4486,8 @@ A jump table for the options with a short description can be found at |Q_op|. and |+postscript| features} Expression used to print the PostScript produced with |:hardcopy|. See |pexpr-option|. + This option cannot be set from a |modeline| or in the |sandbox|, for + security reasons. *'printfont'* *'pfn'* 'printfont' 'pfn' string (default "courier") @@ -4720,6 +4562,7 @@ A jump table for the options with a short description can be found at |Q_op|. buffer, unless the 'Z' flag is in 'cpoptions'. When using the ":view" command the 'readonly' option is set for the newly edited buffer. + See 'modifiable' for disallowing changes to the buffer. *'redrawtime'* *'rdt'* 'redrawtime' 'rdt' number (default 2000) @@ -4919,7 +4762,9 @@ A jump table for the options with a short description can be found at |Q_op|. ordering. This is for preferences to overrule or add to the distributed defaults or system-wide settings (rarely needed). - More entries are added when using |packages|. + More entries are added when using |packages|. If it gets very long + then `:set rtp` will be truncated, use `:echo &rtp` to see the full + string. Note that, unlike 'path', no wildcards like "**" are allowed. Normal wildcards are allowed, but can significantly slow down searching for @@ -4950,12 +4795,12 @@ A jump table for the options with a short description can be found at |Q_op|. height with ":set scroll=0". *'scrollback'* *'scbk'* -'scrollback' 'scbk' number (default: 1000 +'scrollback' 'scbk' number (default: 10000 in normal buffers: -1) local to buffer Maximum number of lines kept beyond the visible screen. Lines at the top are deleted if new lines exceed this limit. - Only in |terminal-emulator| buffers. 'buftype' + Only in |terminal| buffers. -1 means "unlimited" for normal buffers, 100000 otherwise. Minimum is 1. @@ -5062,6 +4907,8 @@ A jump table for the options with a short description can be found at |Q_op|. "inclusive" means that the last character of the selection is included in an operation. For example, when "x" is used to delete the selection. + When "old" is used and 'virtualedit' allows the cursor to move past + the end of line the line break still isn't included. Note that when "exclusive" is used and selecting from the end backwards, you cannot include the last character of a line, when starting in Normal mode and 'virtualedit' empty. @@ -5185,8 +5032,8 @@ A jump table for the options with a short description can be found at |Q_op|. saved. When not included, the value of 'history' is used. *shada-c* c Dummy option, kept for compatibility reasons. Has no actual - effect. Current encoding state is described in - |shada-encoding|. + effect: ShaDa always uses UTF-8 and 'encoding' value is fixed + to UTF-8 as well. *shada-f* f Whether file marks need to be stored. If zero, file marks ('0 to '9, 'A to 'Z) are not stored. When not present or when @@ -5285,9 +5132,7 @@ A jump table for the options with a short description can be found at |Q_op|. security reasons. *'shellcmdflag'* *'shcf'* -'shellcmdflag' 'shcf' string (default: "-c"; - Windows, when 'shell' does not - contain "sh" somewhere: "/c") +'shellcmdflag' 'shcf' string (default: "-c"; Windows: "/c") global Flag passed to the shell to execute "!" and ":!" commands; e.g., "bash.exe -c ls" or "cmd.exe /c dir". For Windows @@ -5298,15 +5143,12 @@ A jump table for the options with a short description can be found at |Q_op|. See |option-backslash| about including spaces and backslashes. See |shell-unquoting| which talks about separating this option into multiple arguments. - Also see |dos-shell| for Windows. This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. *'shellpipe'* *'sp'* 'shellpipe' 'sp' string (default ">", "| tee", "|& tee" or "2>&1| tee") global - {not available when compiled without the |+quickfix| - feature} String to be used to put the output of the ":make" command in the error file. See also |:make_makeprg|. See |option-backslash| about including spaces and backslashes. @@ -5348,7 +5190,7 @@ A jump table for the options with a short description can be found at |Q_op|. third-party shells on Windows systems, such as the MKS Korn Shell or bash, where it should be "\"". The default is adjusted according the value of 'shell', to reduce the need to set this option by the - user. See |dos-shell|. + user. This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. @@ -5380,7 +5222,7 @@ A jump table for the options with a short description can be found at |Q_op|. *'shellslash'* *'ssl'* *'noshellslash'* *'nossl'* 'shellslash' 'ssl' boolean (default off) global - {only for MSDOS and MS-Windows} + {only for Windows} When set, a forward slash is used when expanding file names. This is useful when a Unix-like shell is used instead of command.com or cmd.exe. Backward slashes can still be typed, but they are changed to @@ -5397,10 +5239,7 @@ A jump table for the options with a short description can be found at |Q_op|. global When on, use temp files for shell commands. When off use a pipe. When using a pipe is not possible temp files are used anyway. - Currently a pipe is only supported on Unix and MS-Windows 2K and - later. You can check it with: > - :if has("filterpipe") -< The advantage of using a pipe is that nobody can read the temp file + The advantage of using a pipe is that nobody can read the temp file and the 'shell' command does not need to support redirection. The advantage of using a temp file is that the file type and encoding can be detected. @@ -5410,19 +5249,14 @@ A jump table for the options with a short description can be found at |Q_op|. |system()| does not respect this option, it always uses pipes. *'shellxescape'* *'sxe'* -'shellxescape' 'sxe' string (default: ""; - for Windows: "\"&|<>()@^") +'shellxescape' 'sxe' string (default: "") global When 'shellxquote' is set to "(" then the characters listed in this option will be escaped with a '^' character. This makes it possible to execute most external commands with cmd.exe. *'shellxquote'* *'sxq'* -'shellxquote' 'sxq' string (default: ""; - for Win32, when 'shell' is cmd.exe: "(" - for Win32, when 'shell' contains "sh" - somewhere: "\"" - for Unix, when using system(): "\"") +'shellxquote' 'sxq' string (default: "") global Quoting character(s), put around the command passed to the shell, for the "!" and ":!" commands. Includes the redirection. See @@ -5431,12 +5265,6 @@ A jump table for the options with a short description can be found at |Q_op|. When the value is '(' then ')' is appended. When the value is '"(' then ')"' is appended. When the value is '(' then also see 'shellxescape'. - This is an empty string by default on most systems, but is known to be - useful for on Win32 version, either for cmd.exe which automatically - strips off the first and last quote on a command, or 3rd-party shells - such as the MKS Korn Shell or bash, where it should be "\"". The - default is adjusted according the value of 'shell', to reduce the need - to set this option by the user. See |dos-shell|. This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. @@ -5520,8 +5348,7 @@ A jump table for the options with a short description can be found at |Q_op|. < Only printable single-cell characters are allowed, excluding <Tab> and comma (in a future version the comma might be used to separate the part that is shown at the end and at the start of a line). - The characters are highlighted according to the '@' flag in - 'highlight'. + The |hl-NonText| highlight group determines the highlighting. Note that tabs after the showbreak will be displayed differently. If you want the 'showbreak' to appear in between line numbers, add the "n" flag to 'cpoptions'. @@ -5576,10 +5403,7 @@ A jump table for the options with a short description can be found at |Q_op|. 'showmode' 'smd' boolean (Vim default: on, Vi default: off) global If in Insert, Replace or Visual mode put a message on the last line. - Use the 'M' flag in 'highlight' to set the type of highlighting for - this message. - When |XIM| may be used the message will include "XIM". But this - doesn't mean XIM is really active. + The |hl-ModeMsg| highlight group determines the highlighting. *'showtabline'* *'stal'* 'showtabline' 'stal' number (default 1) @@ -5842,7 +5666,7 @@ A jump table for the options with a short description can be found at |Q_op|. word. The expression must evaluate to a List of Lists, each with a suggestion and a score. Example: - [['the', 33], ['that', 44]] + [['the', 33], ['that', 44]] ~ Set 'verbose' and use |z=| to see the scores that the internal methods use. A lower score is better. This may invoke |spellsuggest()| if you temporarily @@ -6423,7 +6247,7 @@ A jump table for the options with a short description can be found at |Q_op|. for any key that can follow <c-f> in a mapping. *'ttimeout'* *'nottimeout'* -'ttimeout' boolean (default off) +'ttimeout' boolean (default on) global This option and 'ttimeoutlen' determine the behavior when part of a key code sequence has been received by the terminal UI. For example, @@ -6438,20 +6262,18 @@ A jump table for the options with a short description can be found at |Q_op|. complete. *'ttimeoutlen'* *'ttm'* -'ttimeoutlen' 'ttm' number (default -1) +'ttimeoutlen' 'ttm' number (default 50) global The time in milliseconds that is waited for a key code sequence to complete. Also used for CTRL-\ CTRL-N and CTRL-\ CTRL-G when part of a command has been typed. *'title'* *'notitle'* -'title' boolean (default off, on when title can be restored) +'title' boolean (default off) global - {not available when compiled without the |+title| - feature} When on, the title of the window will be set to the value of 'titlestring' (if it is not empty), or to: - filename [+=-] (path) - VIM + filename [+=-] (path) - NVIM Where: filename the name of the file being edited - indicates the file cannot be modified, 'ma' off @@ -6459,17 +6281,11 @@ A jump table for the options with a short description can be found at |Q_op|. = indicates the file is read-only =+ indicates the file is read-only and modified (path) is the path of the file being edited - - VIM the server name |v:servername| or "VIM" - Only works if the terminal supports setting window titles - (currently Win32 console, all GUI versions and terminals with a non- - empty 't_ts' option - this is Unix xterm by default, where 't_ts' is - taken from the builtin termcap). + - NVIM the server name |v:servername| or "NVIM" *'titlelen'* 'titlelen' number (default 85) global - {not available when compiled without the |+title| - feature} Gives the percentage of 'columns' to use for the length of the window title. When the title is longer, only the end of the path name is shown. A '<' character before the path name is used to indicate this. @@ -6481,25 +6297,17 @@ A jump table for the options with a short description can be found at |Q_op|. 'titlelen' is also used for the 'titlestring' option. *'titleold'* -'titleold' string (default "Thanks for flying Vim") +'titleold' string (default "") global - {only available when compiled with the |+title| - feature} - This option will be used for the window title when exiting Vim if the - original title cannot be restored. Only happens if 'title' is on or - 'titlestring' is not empty. + If not empty, this option will be used to set the window title when + exiting. Only if 'title' is enabled. This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. *'titlestring'* 'titlestring' string (default "") global - {not available when compiled without the |+title| - feature} When this option is not empty, it will be used for the title of the window. This happens only when the 'title' option is on. - Only works if the terminal supports setting window titles (currently - Win32 console, all GUI versions and terminals with a non-empty 't_ts' - option). When this option contains printf-style '%' items, they will be expanded according to the rules used for 'statusline'. Example: > @@ -6578,7 +6386,7 @@ A jump table for the options with a short description can be found at |Q_op|. Save the whole buffer for undo when reloading it. This applies to the ":e!" command and reloading for when the buffer changed outside of Vim. |FileChangedShell| - The save only happens when this options is negative or when the number + The save only happens when this option is negative or when the number of lines is smaller than the value of this option. Set this option to zero to disable undo for a reload. @@ -6651,7 +6459,7 @@ A jump table for the options with a short description can be found at |Q_op|. security reasons. *'viewoptions'* *'vop'* -'viewoptions' 'vop' string (default: "folds,options,cursor") +'viewoptions' 'vop' string (default: "folds,options,cursor,curdir") global {not available when compiled without the |+mksession| feature} @@ -6659,6 +6467,7 @@ A jump table for the options with a short description can be found at |Q_op|. list of words. Each word enables saving and restoring something: word save and restore ~ cursor cursor position in file and in window + curdir local current directory, if set with |:lcd| folds manually created folds, opened/closed folds and local fold options options options and mappings local to a window or buffer (not @@ -6938,6 +6747,24 @@ A jump table for the options with a short description can be found at |Q_op|. 'winheight' applies to the current window. Use 'winminheight' to set the minimal height for other windows. + *'winhighlight'* *'winhl'* +'winhighlight' 'winhl' string (default empty) + local to window + Window-local highlights. Comma-delimited list of highlight + |group-name| pairs "{hl-builtin}:{hl},..." where each {hl-builtin} is + a built-in |highlight-groups| item to be overridden by {hl} group in + the window. Only built-in |highlight-groups| are supported, not + syntax highlighting (use |:ownsyntax| for that). + + Highlights of vertical separators are determined by the window to the + left of the separator. The highlight of a tabpage in |tabline| is + determined by the last-focused window of the tabpage. Highlights of + the popupmenu are determined by the current window. Highlights in the + message area cannot be overridden. + + Example: show a different color for non-current windows: > + set winhighlight=Normal:MyNormal,NormalNC:MyNormalNC +< *'winfixheight'* *'wfh'* *'nowinfixheight'* *'nowfh'* 'winfixheight' 'wfh' boolean (default off) local to window diff --git a/runtime/doc/os_win32.txt b/runtime/doc/os_win32.txt deleted file mode 100644 index 5dc276c9df..0000000000 --- a/runtime/doc/os_win32.txt +++ /dev/null @@ -1,206 +0,0 @@ -*os_win32.txt* For Vim version 7.4. Last change: 2016 Mar 05 - - - VIM REFERENCE MANUAL by George Reilly - - - *win32* *Win32* *MS-Windows* -This file documents the idiosyncrasies of the Win32 version of Vim. - -The Win32 version of Vim works on Windows XP, Vista and Windows 7. -There are both console and GUI versions. - -The 32 bit version also runs on 64 bit MS-Windows systems. - -1. Known problems |win32-problems| -2. Startup |win32-startup| -3. Using the mouse |win32-mouse| -4. Win32 mini FAQ |win32-faq| - -Additionally, there are a number of common Win32 and DOS items: -File locations |dos-locations| -Using backslashes |dos-backslash| -Standard mappings |dos-standard-mappings| -Screen output and colors |dos-colors| -File formats |dos-file-formats| -:cd command |dos-:cd| -Interrupting |dos-CTRL-Break| -Temp files |dos-temp-files| -Shell option default |dos-shell| - -Win32 GUI |gui-w32| - -Credits: -The Win32 version was written by George V. Reilly <george@reilly.org>. -The GUI version was made by George V. Reilly and Robert Webb. - -============================================================================== -1. Known problems *win32-problems* - -When doing file name completion, Vim also finds matches for the short file -name. But Vim will still find and use the corresponding long file name. For -example, if you have the long file name "this_is_a_test" with the short file -name "this_i~1", the command ":e *1" will start editing "this_is_a_test". - -============================================================================== -2. Startup *win32-startup* - -Current directory *win32-curdir* - -If Vim is started with a single file name argument, and it has a full path -(starts with "x:\"), Vim assumes it was started from the file explorer and -will set the current directory to where that file is. To avoid this when -typing a command to start Vim, use a forward slash instead of a backslash. -Example: > - - vim c:\text\files\foo.txt - -Will change to the "C:\text\files" directory. > - - vim c:/text\files\foo.txt - -Will use the current directory. - - -Term option *win32-term* - -The only kind of terminal type that the Win32 version of Vim understands is -"win32", which is built-in. If you set 'term' to anything else, you will -probably get very strange behavior from Vim. Therefore Vim does not obtain -the default value of 'term' from the environment variable "TERM". - -$PATH *win32-PATH* - -The directory of the Vim executable is appended to $PATH. This is mostly to -make "!xxd" work, as it is in the Tools menu. And it also means that when -executable() returns 1 the executable can actually be executed. - -Quotes in file names *win32-quotes* - -Quotes inside a file name (or any other command line argument) can be escaped -with a backslash. E.g. > - vim -c "echo 'foo\"bar'" - -Alternatively use three quotes to get one: > - vim -c "echo 'foo"""bar'" - -The quotation rules are: - -1. A `"` starts quotation. -2. Another `"` or `""` ends quotation. If the quotation ends with `""`, a `"` - is produced at the end of the quoted string. - -Examples, with [] around an argument: - "foo" -> [foo] - "foo"" -> [foo"] - "foo"bar -> [foobar] - "foo" bar -> [foo], [bar] - "foo""bar -> [foo"bar] - "foo"" bar -> [foo"], [bar] - "foo"""bar" -> [foo"bar] - - -============================================================================== -3. Using the mouse *win32-mouse* - -The Win32 version of Vim supports using the mouse. If you have a two-button -mouse, the middle button can be emulated by pressing both left and right -buttons simultaneously - but note that in the Win32 GUI, if you have the right -mouse button pop-up menu enabled (see 'mouse'), you should err on the side of -pressing the left button first. |mouse-using| - -When the mouse doesn't work, try disabling the "Quick Edit Mode" feature of -the console. - -============================================================================== -4. Win32 mini FAQ *win32-faq* - -Q. How do I change the font? -A. In the GUI version, you can use the 'guifont' option. Example: > - :set guifont=Lucida_Console:h15:cDEFAULT -< In the console version, you need to set the font of the console itself. - You cannot do this from within Vim. - -Q. I'm using Vim to edit a symbolically linked file on a Unix NFS file server. - When I write the file, Vim does not "write through" the symlink. Instead, - it deletes the symbolic link and creates a new file in its place. Why? -A. On Unix, Vim is prepared for links (symbolic or hard). A backup copy of - the original file is made and then the original file is overwritten. This - assures that all properties of the file remain the same. On non-Unix - systems, the original file is renamed and a new file is written. Only the - protection bits are set like the original file. However, this doesn't work - properly when working on an NFS-mounted file system where links and other - things exist. The only way to fix this in the current version is not - making a backup file, by ":set nobackup nowritebackup" |'writebackup'| - -Q. I'm using Vim to edit a file on a Unix file server through Samba. When I - write the file, the owner of the file is changed. Why? -A. When writing a file Vim renames the original file, this is a backup (in - case writing the file fails halfway). Then the file is written as a new - file. Samba then gives it the default owner for the file system, which may - differ from the original owner. - To avoid this set the 'backupcopy' option to "yes". Vim will then make a - copy of the file for the backup, and overwrite the original file. The - owner isn't changed then. - -Q. How do I get to see the output of ":make" while it's running? -A. Basically what you need is to put a tee program that will copy its input - (the output from make) to both stdout and to the errorfile. You can find a - copy of tee (and a number of other GNU tools) at - http://gnuwin32.sourceforge.net or http://unxutils.sourceforge.net - Alternatively, try the more recent Cygnus version of the GNU tools at - http://www.cygwin.com Other Unix-style tools for Win32 are listed at - http://directory.google.com/Top/Computers/Software/Operating_Systems/Unix/Win32/ - When you do get a copy of tee, you'll need to add > - :set shellpipe=\|\ tee -< to your _vimrc. - - *:!start* -Q. How can I run an external command or program asynchronously? -A. When using :! to run an external command, you can run it with "start": > - :!start winfile.exe<CR> -< Using "start" stops Vim switching to another screen, opening a new console, - or waiting for the program to complete; it indicates that you are running a - program that does not affect the files you are editing. Programs begun - with :!start do not get passed Vim's open file handles, which means they do - not have to be closed before Vim. - To avoid this special treatment, use ":! start". - There are two optional arguments (see the next Q): - /min the window will be minimized - /b no console window will be opened - You can use only one of these flags at a time. A second one will be - treated as the start of the command. - -Q. How do I avoid getting a window for programs that I run asynchronously? -A. You have two possible solutions depending on what you want: - 1) You may use the /min flag in order to run program in a minimized state - with no other changes. It will work equally for console and GUI - applications. - 2) You can use the /b flag to run console applications without creating a - console window for them (GUI applications are not affected). But you - should use this flag only if the application you run doesn't require any - input. Otherwise it will get an EOF error because its input stream - (stdin) would be redirected to \\.\NUL (stdout and stderr too). - - Example for a console application, run Exuberant ctags: > - :!start /min ctags -R . -< When it has finished you should see file named "tags" in your current - directory. You should notice the window title blinking on your taskbar. - This is more noticeable for commands that take longer. - Now delete the "tags" file and run this command: > - :!start /b ctags -R . -< You should have the same "tags" file, but this time there will be no - blinking on the taskbar. - Example for a GUI application: > - :!start /min notepad - :!start /b notepad -< The first command runs notepad minimized and the second one runs it - normally. - - *windows-icon* -Q. I don't like the Vim icon, can I change it? -A. Yes, place your favorite icon in bitmaps/vim.ico in a directory of - 'runtimepath'. For example ~/vimfiles/bitmaps/vim.ico. - - - vim:tw=78:fo=tcq2:ts=8:ft=help:norl: diff --git a/runtime/doc/pattern.txt b/runtime/doc/pattern.txt index f3f5bcbd66..ab78b8b71c 100644 --- a/runtime/doc/pattern.txt +++ b/runtime/doc/pattern.txt @@ -1,4 +1,4 @@ -*pattern.txt* For Vim version 7.4. Last change: 2016 Jun 08 +*pattern.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -9,16 +9,7 @@ Patterns and search commands *pattern-searches* The very basics can be found in section |03.9| of the user manual. A few more explanations are in chapter 27 |usr_27.txt|. -1. Search commands |search-commands| -2. The definition of a pattern |search-pattern| -3. Magic |/magic| -4. Overview of pattern items |pattern-overview| -5. Multi items |pattern-multi-items| -6. Ordinary atoms |pattern-atoms| -7. Ignoring case in a pattern |/ignorecase| -8. Composing characters |patterns-composing| -9. Compare with Perl patterns |perl-patterns| -10. Highlighting matches |match-highlight| + Type |gO| to see the table of contents. ============================================================================== 1. Search commands *search-commands* @@ -130,8 +121,7 @@ gD Goto global Declaration. When the cursor is on a ends before the cursor position. *CTRL-C* -CTRL-C Interrupt current (search) command. Use CTRL-Break on - Windows |dos-CTRL-Break|. +CTRL-C Interrupt current (search) command. In Normal mode, any pending command is aborted. *:noh* *:nohlsearch* @@ -354,8 +344,8 @@ For starters, read chapter 27 of the user manual |usr_27.txt|. */\%#=* *two-engines* *NFA* Vim includes two regexp engines: 1. An old, backtracking engine that supports everything. -2. A new, NFA engine that works much faster on some patterns, but does not - support everything. +2. A new, NFA engine that works much faster on some patterns, possibly slower + on some patterns. Vim will automatically select the right engine for you. However, if you run into a problem or want to specifically select one engine or the other, you can @@ -863,10 +853,13 @@ $ At end of pattern or in front of "\|", "\)" or "\n" ('magic' on): \%V Match inside the Visual area. When Visual mode has already been stopped match in the area that |gv| would reselect. This is a |/zero-width| match. To make sure the whole pattern is - inside the Visual area put it at the start and end of the pattern, - e.g.: > + inside the Visual area put it at the start and just before the end of + the pattern, e.g.: > + /\%Vfoo.*ba\%Vr +< This also works if only "foo bar" was Visually selected. This: > /\%Vfoo.*bar\%V -< Only works for the current buffer. +< would match "foo bar" if the Visual selection continues after the "r". + Only works for the current buffer. */\%#* *cursor-position* \%# Matches with the cursor position. Only works when matching in a @@ -1065,12 +1058,16 @@ x A single character, with no special meaning, matches itself ":s/[/x/" searches for "[/x" and replaces it with nothing. It does not search for "[" and replaces it with "x"! + *E944* *E945* If the sequence begins with "^", it matches any single character NOT in the collection: "[^xyz]" matches anything but 'x', 'y' and 'z'. - If two characters in the sequence are separated by '-', this is shorthand for the full list of ASCII characters between them. E.g., - "[0-9]" matches any decimal digit. Non-ASCII characters can be - used, but the character values must not be more than 256 apart. + "[0-9]" matches any decimal digit. If the starting character exceeds + the ending character, e.g. [c-a], E944 occurs. Non-ASCII characters + can be used, but the character values must not be more than 256 apart + in the old regexp engine. For example, searching by [\u3000-\u4000] + after setting re=1 emits a E945 error. Prepending \%#=2 will fix it. - A character class expression is evaluated to the set of characters belonging to that character class. The following character classes are supported: diff --git a/runtime/doc/pi_gzip.txt b/runtime/doc/pi_gzip.txt index df0ba5e52e..f024db1260 100644 --- a/runtime/doc/pi_gzip.txt +++ b/runtime/doc/pi_gzip.txt @@ -1,4 +1,4 @@ -*pi_gzip.txt* For Vim version 7.4. Last change: 2012 Jul 19 +*pi_gzip.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -25,6 +25,8 @@ with these extensions: *.bz2 bzip2 *.lzma lzma *.xz xz + *.lz lzip + *.zst zstd That's actually the only thing you need to know. There are no options. diff --git a/runtime/doc/pi_health.txt b/runtime/doc/pi_health.txt index 69833103d1..bb688770fc 100644 --- a/runtime/doc/pi_health.txt +++ b/runtime/doc/pi_health.txt @@ -2,56 +2,45 @@ Author: TJ DeVries <devries.timothyj@gmail.com> -============================================================================== -1. Introduction |health.vim-intro| -2. Commands and functions |health.vim-manual| -3. Create a healthcheck |health.vim-dev| + Type |gO| to see the table of contents. ============================================================================== -Introduction *healthcheck* *health.vim-intro* +Introduction *health* -Troubleshooting user configuration problems is a time-consuming task that -developers want to minimize. health.vim provides a simple framework for plugin -authors to hook into, and for users to invoke, to check and report the user's -configuration and environment. Type this command to try it: > +health.vim is a minimal framework to help with troubleshooting user +configuration. Nvim ships with healthchecks for configuration, performance, +python support, ruby support, clipboard support, and more. - :CheckHealth -< -For example, some users have broken or unusual Python setups, which breaks the -|:python| command. |:CheckHealth| detects several common Python configuration -problems and reports them. If the Neovim Python module is not installed, it -shows a warning: > +To run the healthchecks, use this command: > - You have not installed the Neovim Python module - You might want to try `pip install Neovim` -< -Plugin authors are encouraged to add healthchecks, see |health.vim-dev|. + :checkhealth +< +Plugin authors are encouraged to write new healthchecks. |health-dev| ============================================================================== -Commands and functions *health.vim-manual* - -Commands ------------------------------------------------------------------------------- - *:CheckHealth* -:CheckHealth Run all healthchecks and show the output in a new - tabpage. These healthchecks are included by default: - - python2 - - python3 - - ruby - - remote plugin - -:CheckHealth {plugins} - Run healthchecks for one or more plugins. E.g. to run +Commands *health-commands* + + *:checkhealth* *:CheckHealth* +:checkhealth Run all healthchecks. + *E5009* + Nvim depends on |$VIMRUNTIME| and 'runtimepath' to find + the standard "runtime files" for syntax highlighting, + filetype-specific behavior, and standard plugins + (including :checkhealth). If the runtime files cannot + be found then those features will not work. + +:checkhealth {plugins} + Run healthcheck(s) for one or more plugins. E.g. to run only the standard Nvim healthcheck: > - :CheckHealth nvim + :checkhealth nvim < To run the healthchecks for the "foo" and "bar" plugins (assuming these plugins are on your 'runtimepath' and they have implemented health#foo#check() and health#bar#check(), respectively): > - :CheckHealth foo bar + :checkhealth foo bar < -Functions ------------------------------------------------------------------------------- +============================================================================== +Functions *health-functions* health.vim functions are for creating new healthchecks. They mostly just do some layout and formatting, to give users a consistent presentation. @@ -62,54 +51,49 @@ health#report_start({name}) *health#report_start* per section. health#report_info({msg}) *health#report_info* - Displays an informational message. + Reports an informational message. health#report_ok({msg}) *health#report_ok* - Displays a "success" message. + Reports a "success" message. -health#report_warn({msg}, [{suggestions}]) *health#report_warn* - Displays a warning. {suggestions} is an optional List of suggestions. +health#report_warn({msg}, [{advice}]) *health#report_warn* + Reports a warning. {advice} is an optional List of suggestions. -health#report_error({msg}, [{suggestions}]) *health#report_error* - Displays an error. {suggestions} is an optional List of suggestions. +health#report_error({msg}, [{advice}]) *health#report_error* + Reports an error. {advice} is an optional List of suggestions. health#{plugin}#check() *health.user_checker* - This is the form of a healthcheck definition. Call the above functions - from this function, then |:CheckHealth| does the rest. Example: > + Healthcheck function for {plugin}. Called by |:checkhealth| + automatically. Example: > function! health#my_plug#check() abort silent call s:check_environment_vars() silent call s:check_python_configuration() endfunction < - The function will be found and called automatically when the user - invokes |:CheckHealth|. - All output will be captured from the healthcheck. Use the health#report_* functions so that your healthcheck has a format consistent with the standard healthchecks. ============================================================================== -Create a healthcheck *health.vim-dev* +Create a healthcheck *health-dev* -Healthchecks are functions that check the health of the system. Neovim has -built-in checkers, found in $VIMRUNTIME/autoload/health/. +Healthchecks are functions that check the user environment, configuration, +etc. Nvim has built-in healthchecks in $VIMRUNTIME/autoload/health/. -To add a new checker for your own plugin, simply define a +To add a new healthcheck for your own plugin, simply define a health#{plugin}#check() function in autoload/health/{plugin}.vim. -|:CheckHealth| automatically finds and invokes such functions. +|:checkhealth| automatically finds and invokes such functions. -If your plugin is named "jslint", then its healthcheck function must be > +If your plugin is named "foo", then its healthcheck function must be > + health#foo#check() - health#jslint#check() -< defined in this file on 'runtimepath': > + autoload/health/foo.vim - autoload/health/jslint.vim -< -Here's a sample to get started: > - - function! health#jslint#check() abort +Copy this sample code into autoload/health/foo.vim and replace "foo" with your +plugin name: > + function! health#foo#check() abort call health#report_start('sanity checks') " perform arbitrary checks " ... @@ -117,11 +101,11 @@ Here's a sample to get started: > if looks_good call health#report_ok('found required dependencies') else - call health#report_error('cannot find jslint', - \ ['npm install --save jslint']) + call health#report_error('cannot find foo', + \ ['npm install --save foo']) endif endfunction -< + ============================================================================== vim:tw=78:ts=8:ft=help:fdm=marker diff --git a/runtime/doc/pi_matchit.txt b/runtime/doc/pi_matchit.txt index c711cd588f..652734f7bb 100644 --- a/runtime/doc/pi_matchit.txt +++ b/runtime/doc/pi_matchit.txt @@ -1,6 +1,6 @@ *pi_matchit.txt* Extended "%" matching -For Vim version 6.3. Last change: 2015 May 21 +For Vim version 6.3. Last change: 2017 May 14 *matchit* *matchit.vim* @@ -211,7 +211,7 @@ Examples: In LaTeX, since "%" is used as the comment character, you can > :let b:match_skip = 'r:%' < Unfortunately, this will skip anything after "\%", an escaped "%". To - allow for this, and also "\\%" (an excaped backslash followed by the + allow for this, and also "\\%" (an escaped backslash followed by the comment character) you can > :let b:match_skip = 'r:\(^\|[^\\]\)\(\\\\\)*%' < @@ -356,7 +356,8 @@ The back reference '\'.d refers to the same thing as '\'.b:match_table[d] in The various |:vmap|s defined in the script (%, |g%|, |[%|, |]%|, |a%|) may have undesired effects in Select mode |Select-mode-mapping|. At least, if you want to replace the selection with any character in "ag%[]" there will be a -pause of |'updatetime'| first. +pause of |'updatetime'| first. E.g., "yV%" would normally work linewise, but +the plugin mapping makes it characterwise. It would be nice if "\0" were recognized as the entire pattern. That is, it would be nice if "foo:\end\0" had the same effect as "\(foo\):\end\1". diff --git a/runtime/doc/pi_msgpack.txt b/runtime/doc/pi_msgpack.txt index d695ac42cb..e9f77e70b0 100644 --- a/runtime/doc/pi_msgpack.txt +++ b/runtime/doc/pi_msgpack.txt @@ -1,4 +1,4 @@ -*pi_msgpack.txt* For NeoVim version 0.1. +*pi_msgpack.txt* Nvim Author: Nikolay Pavlov <kp-pav@yandex.ru> Copyright: (c) 2015 by Nikolay Pavlov diff --git a/runtime/doc/pi_netrw.txt b/runtime/doc/pi_netrw.txt index f740143c61..3e19f0b4af 100644 --- a/runtime/doc/pi_netrw.txt +++ b/runtime/doc/pi_netrw.txt @@ -1,4 +1,4 @@ -*pi_netrw.txt* For Vim version 7.4. Last change: 2016 Apr 20 +*pi_netrw.txt* Nvim ------------------------------------------------ NETRW REFERENCE MANUAL by Charles E. Campbell @@ -530,7 +530,7 @@ variable (ex. scp uses the variable g:netrw_scp_cmd, which is defaulted to let g:netrw_sftp_cmd= '"c:\Program Files\PuTTY\psftp.exe"' < (note: it has been reported that windows 7 with putty v0.6's "-batch" option - doesn't work, so its best to leave it off for that system) + doesn't work, so it's best to leave it off for that system) See |netrw-p8| for more about putty, pscp, psftp, etc. @@ -1204,7 +1204,7 @@ The :NetrwMB command is available outside of netrw buffers (once netrw has been invoked in the session). The file ".netrwbook" holds bookmarks when netrw (and vim) is not active. By -default, its stored on the first directory on the user's |'runtimepath'|. +default, it's stored on the first directory on the user's |'runtimepath'|. Related Topics: |netrw-gb| how to return (go) to a bookmark @@ -1429,7 +1429,7 @@ be used in that count. *.netrwhist* See |g:netrw_dirhistmax| for how to control the quantity of history stack slots. The file ".netrwhist" holds history when netrw (and vim) is not -active. By default, its stored on the first directory on the user's +active. By default, it's stored on the first directory on the user's |'runtimepath'|. Related Topics: @@ -3269,7 +3269,7 @@ The user function is passed one argument; it resembles > fun! ExampleUserMapFunc(islocal) < -where a:islocal is 1 if its a local-directory system call or 0 when +where a:islocal is 1 if it's a local-directory system call or 0 when remote-directory system call. Use netrw#Expose("varname") to access netrw-internal (script-local) @@ -3593,7 +3593,7 @@ Example: Clear netrw's marked file list via a mapping on gu > *netrw-p16* P16. When editing remote files (ex. :e ftp://hostname/path/file), - under Windows I get an |E303| message complaining that its unable + under Windows I get an |E303| message complaining that it's unable to open a swap file. (romainl) It looks like you are starting Vim from a protected @@ -3647,7 +3647,7 @@ Example: Clear netrw's marked file list via a mapping on gu > P21. I've made a directory (or file) with an accented character, but netrw isn't letting me enter that directory/read that file: - Its likely that the shell or o/s is using a different encoding + It's likely that the shell or o/s is using a different encoding than you have vim (netrw) using. A patch to vim supporting "systemencoding" may address this issue in the future; for now, just have netrw use the proper encoding. For example: > diff --git a/runtime/doc/pi_paren.txt b/runtime/doc/pi_paren.txt index 534b3add29..4b425c6cbb 100644 --- a/runtime/doc/pi_paren.txt +++ b/runtime/doc/pi_paren.txt @@ -1,4 +1,4 @@ -*pi_paren.txt* For Vim version 7.4. Last change: 2013 May 08 +*pi_paren.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar diff --git a/runtime/doc/pi_spec.txt b/runtime/doc/pi_spec.txt index 650d1d369b..f4949db2af 100644 --- a/runtime/doc/pi_spec.txt +++ b/runtime/doc/pi_spec.txt @@ -1,4 +1,4 @@ -*pi_spec.txt* For Vim version 7.4. Last change: 2006 Apr 24 +*pi_spec.txt* Nvim by Gustavo Niemeyer ~ diff --git a/runtime/doc/pi_tar.txt b/runtime/doc/pi_tar.txt index b2fab290b3..a189d006dd 100644 --- a/runtime/doc/pi_tar.txt +++ b/runtime/doc/pi_tar.txt @@ -1,4 +1,4 @@ -*pi_tar.txt* For Vim version 7.4. Last change: 2013 Apr 17 +*pi_tar.txt* Nvim +====================+ | Tar File Interface | diff --git a/runtime/doc/pi_zip.txt b/runtime/doc/pi_zip.txt index 0a081f24d3..c20bda1fa1 100644 --- a/runtime/doc/pi_zip.txt +++ b/runtime/doc/pi_zip.txt @@ -1,4 +1,4 @@ -*pi_zip.txt* For Vim version 7.4. Last change: 2013 Apr 17 +*pi_zip.txt* Nvim +====================+ | Zip File Interface | @@ -6,7 +6,7 @@ Author: Charles E. Campbell <NdrOchip@ScampbellPfamily.AbizM> (remove NOSPAM from Campbell's email first) -Copyright: Copyright (C) 2005-2012 Charles E Campbell *zip-copyright* +Copyright: Copyright (C) 2005-2015 Charles E Campbell *zip-copyright* The VIM LICENSE (see |copyright|) applies to the files in this package, including zipPlugin.vim, zip.vim, and pi_zip.vim. except use "zip.vim" instead of "VIM". Like anything else that's free, zip.vim @@ -33,6 +33,9 @@ Copyright: Copyright (C) 2005-2012 Charles E Campbell *zip-copyright* also write to the file. Currently, one may not make a new file in zip archives via the plugin. + *zip-x* + x : may extract a listed file when the cursor is atop it + OPTIONS *g:zip_nomax* @@ -61,6 +64,11 @@ Copyright: Copyright (C) 2005-2012 Charles E Campbell *zip-copyright* file; by default: > let g:zip_zipcmd= "zip" < + *g:zip_extractcmd* + This option specifies the program (and any options needed) used to + extract a file from a zip archive. By default, > + let g:zip_extractcmd= g:zip_unzipcmd +< PREVENTING LOADING~ If for some reason you do not wish to use vim to examine zipped files, @@ -83,8 +91,26 @@ Copyright: Copyright (C) 2005-2012 Charles E Campbell *zip-copyright* One can simply extend this line to accommodate additional extensions that should be treated as zip files. + Alternatively, one may change *g:zipPlugin_ext* in one's .vimrc. + Currently (11/30/15) it holds: > + + let g:zipPlugin_ext= '*.zip,*.jar,*.xpi,*.ja,*.war,*.ear,*.celzip, + \ *.oxt,*.kmz,*.wsz,*.xap,*.docx,*.docm,*.dotx,*.dotm,*.potx,*.potm, + \ *.ppsx,*.ppsm,*.pptx,*.pptm,*.ppam,*.sldx,*.thmx,*.xlam,*.xlsx,*.xlsm, + \ *.xlsb,*.xltx,*.xltm,*.xlam,*.crtx,*.vdw,*.glox,*.gcsx,*.gqsx,*.epub' + ============================================================================== 4. History *zip-history* {{{1 + v28 Oct 08, 2014 * changed the sanity checks for executables to reflect + the command actually to be attempted in zip#Read() + and zip#Write() + * added the extraction of a file capability + Nov 30, 2015 * added *.epub to the |g:zipPlugin_ext| list + Sep 13, 2016 * added *.apk to the |g:zipPlugin_ext| list and + sorted the suffices. + v27 Jul 02, 2013 * sanity check: zipfile must have "PK" as its first + two bytes. + * modified to allow zipfile: entries in quickfix lists v26 Nov 15, 2012 * (Jason Spiro) provided a lot of new extensions that are synonyms for .zip v25 Jun 27, 2011 * using keepj with unzip -Z diff --git a/runtime/doc/print.txt b/runtime/doc/print.txt index 7565d1e976..3ffb52b5ae 100644 --- a/runtime/doc/print.txt +++ b/runtime/doc/print.txt @@ -1,4 +1,4 @@ -*print.txt* For Vim version 7.4. Last change: 2010 Jul 20 +*print.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -6,14 +6,7 @@ Printing *printing* -1. Introduction |print-intro| -2. Print options |print-options| -3. PostScript Printing |postscript-printing| -4. PostScript Printing Encoding |postscript-print-encoding| -5. PostScript CJK Printing |postscript-cjk-printing| -6. PostScript Printing Troubleshooting |postscript-print-trouble| -7. PostScript Utilities |postscript-print-util| -8. Formfeed Characters |printing-formfeed| + Type |gO| to see the table of contents. ============================================================================== 1. Introduction *print-intro* @@ -94,25 +87,25 @@ If the option is empty, then vim will use the system default printer for Macintosh: mac-roman, HPUX: hp-roman8) global -Sets the character encoding used when printing. This option tells VIM which +Sets the character encoding used when printing. This option tells Vim which print character encoding file from the "print" directory in 'runtimepath' to use. This option will accept any value from |encoding-names|. Any recognized names -are converted to VIM standard names - see 'encoding' for more details. Names -not recognized by VIM will just be converted to lower case and underscores +are converted to Vim standard names - see 'encoding' for more details. Names +not recognized by Vim will just be converted to lower case and underscores replaced with '-' signs. -If 'printencoding' is empty or VIM cannot find the file then it will use -'encoding' (if VIM is compiled with |+multi_byte| and it is set an 8-bit -encoding) to find the print character encoding file. If VIM is unable to find +If 'printencoding' is empty or Vim cannot find the file then it will use +'encoding' (if Vim is compiled with |+multi_byte| and it is set an 8-bit +encoding) to find the print character encoding file. If Vim is unable to find a character encoding file then it will use the "latin1" print character encoding file. -When 'encoding' is set to a multi-byte encoding, VIM will try to convert +When 'encoding' is set to a multi-byte encoding, Vim will try to convert characters to the printing encoding for printing (if 'printencoding' is empty then the conversion will be to latin1). Conversion to a printing encoding -other than latin1 will require VIM to be compiled with the |+iconv| feature. +other than latin1 will require Vim to be compiled with the |+iconv| feature. If no conversion is possible then printing will fail. Any characters that cannot be converted will be replaced with upside down question marks. @@ -193,7 +186,7 @@ header is used when this option is empty. 'printmbcharset' 'pmbcs' string (default "") global Sets the CJK character set to be used when generating CJK output from -|:hardcopy|. The following predefined values are currently recognised by VIM: +|:hardcopy|. The following predefined values are currently recognised by Vim: Value Description ~ Chinese GB_2312-80 @@ -260,7 +253,7 @@ Japanese text you would do the following; > If 'printmbcharset' is not one of the above values then it is assumed to specify a custom multi-byte character set and no check will be made that it is -compatible with the value for 'printencoding'. VIM will look for a file +compatible with the value for 'printencoding'. Vim will look for a file defining the character set in the "print" directory in 'runtimepath'. *pmbfn-option* @@ -410,10 +403,10 @@ There are currently a number of limitations with PostScript printing: possible to get all the characters in an encoding to print by installing a new version of the Courier font family. -- Multi-byte support - Currently VIM will try to convert multi-byte characters +- Multi-byte support - Currently Vim will try to convert multi-byte characters to the 8-bit encoding specified by 'printencoding' (or latin1 if it is empty). Any characters that are not successfully converted are shown as - unknown characters. Printing will fail if VIM cannot convert the multi-byte + unknown characters. Printing will fail if Vim cannot convert the multi-byte to the 8-bit encoding. ============================================================================== @@ -424,11 +417,11 @@ you need to define your own PostScript font encoding vector. Details on how to define a font encoding vector is beyond the scope of this help file, but you can find details in the PostScript Language Reference Manual, 3rd Edition, published by Addison-Wesley and available in PDF form at -http://www.adobe.com/. The following describes what you need to do for VIM to +http://www.adobe.com/. The following describes what you need to do for Vim to locate and use your print character encoding. i. Decide on a unique name for your encoding vector, one that does not clash - with any of the recognized or standard encoding names that VIM uses (see + with any of the recognized or standard encoding names that Vim uses (see |encoding-names| for a list), and that no one else is likely to use. ii. Copy $VIMRUNTIME/print/latin1.ps to the print subdirectory in your 'runtimepath' and rename it with your unique name. @@ -436,23 +429,23 @@ iii. Edit your renamed copy of latin1.ps, replacing all occurrences of latin1 with your unique name (don't forget the line starting %%Title:), and modify the array of glyph names to define your new encoding vector. The array must have exactly 256 entries or you will not be able to print! -iv. Within VIM, set 'printencoding' to your unique encoding name and then - print your file. VIM will now use your custom print character encoding. +iv. Within Vim, set 'printencoding' to your unique encoding name and then + print your file. Vim will now use your custom print character encoding. -VIM will report an error with the resource file if you change the order or +Vim will report an error with the resource file if you change the order or content of the first 3 lines, other than the name of the encoding on the line starting %%Title: or the version number on the line starting %%Version:. -[Technical explanation for those that know PostScript - VIM looks for a file +[Technical explanation for those that know PostScript - Vim looks for a file with the same name as the encoding it will use when printing. The file defines a new PostScript Encoding resource called /VIM-name, where name is the -print character encoding VIM will use.] +print character encoding Vim will use.] ============================================================================== 5. PostScript CJK Printing *postscript-cjk-printing* *E673* *E674* *E675* -VIM supports printing of Chinese, Japanese, and Korean files. Setting up VIM +Vim supports printing of Chinese, Japanese, and Korean files. Setting up Vim to correctly print CJK files requires setting up a few more options. Each of these countries has many standard character sets and encodings which @@ -473,7 +466,7 @@ option allows you to specify different fonts to use when printing characters which are syntax highlighted with the font styles normal, italic, bold and bold-italic. -No CJK fonts are supplied with VIM. There are some free Korean, Japanese, and +No CJK fonts are supplied with Vim. There are some free Korean, Japanese, and Traditional Chinese fonts available at: http://examples.oreilly.com/cjkvinfo/adobe/samples/ @@ -488,7 +481,7 @@ CJK fonts can be large containing several thousand glyphs, and it is not uncommon to find that they only contain a subset of a national standard. It is not unusual to find the fonts to not include characters for codes in the ASCII code range. If you find half-width Roman characters are not appearing -in your printout then you should configure VIM to use the Courier font the +in your printout then you should configure Vim to use the Courier font the half-width ASCII characters with 'printmbfont'. If your font does not include other characters then you will need to find another font that does. @@ -496,7 +489,7 @@ Another issue with ASCII characters, is that the various national character sets specify a couple of different glyphs in the ASCII code range. If you print ASCII text using the national character set you may see some unexpected characters. If you want true ASCII code printing then you need to configure -VIM to output ASCII characters for the ASCII code range with 'printmbfont'. +Vim to output ASCII characters for the ASCII code range with 'printmbfont'. It is possible to define your own multi-byte character set although this should not be attempted lightly. A discussion on the process if beyond the @@ -515,13 +508,13 @@ print job completing. There are a number of possible causes as to why the printing may have failed: - Wrong version of the prolog resource file. The prolog resource file - contains some PostScript that VIM needs to be able to print. Each version - of VIM needs one particular version. Make sure you have correctly installed + contains some PostScript that Vim needs to be able to print. Each version + of Vim needs one particular version. Make sure you have correctly installed the runtime files, and don't have any old versions of a file called prolog in the print directory in your 'runtimepath' directory. - Paper size. Some PostScript printers will abort printing a file if they do - not support the requested paper size. By default VIM uses A4 paper. Find + not support the requested paper size. By default Vim uses A4 paper. Find out what size paper your printer normally uses and set the appropriate paper size with 'printoptions'. If you cannot find the name of the paper used, measure a sheet and compare it with the table of supported paper sizes listed @@ -652,7 +645,7 @@ complex print document creation. N-UP PRINTING -The psnup utility takes an existing PostScript file generated from VIM and +The psnup utility takes an existing PostScript file generated from Vim and convert it to an n-up version. The simplest way to create a 2-up printout is to first create a PostScript file with: > @@ -708,16 +701,16 @@ There are a couple of points to bear in mind: ============================================================================== 8. Formfeed Characters *printing-formfeed* -By default VIM does not do any special processing of |formfeed| control -characters. Setting the 'printoptions' formfeed item will make VIM recognize +By default Vim does not do any special processing of |formfeed| control +characters. Setting the 'printoptions' formfeed item will make Vim recognize formfeed characters and continue printing the current line at the beginning of the first line on a new page. The use of formfeed characters provides rudimentary print control but there are certain things to be aware of. -VIM will always start printing a line (including a line number if enabled) +Vim will always start printing a line (including a line number if enabled) containing a formfeed character, even if it is the first character on the line. This means if a line starting with a formfeed character is the first -line of a page then VIM will print a blank page. +line of a page then Vim will print a blank page. Since the line number is printed at the start of printing the line containing the formfeed character, the remainder of the line printed on the new page @@ -726,7 +719,7 @@ lines of a long line when wrap in 'printoptions' is enabled). If the formfeed character is the last character on a line, then printing will continue on the second line of the new page, not the first. This is due to -VIM processing the end of the line after the formfeed character and moving +Vim processing the end of the line after the formfeed character and moving down a line to continue printing. Due to the points made above it is recommended that when formfeed character diff --git a/runtime/doc/provider.txt b/runtime/doc/provider.txt index ac4d7361f4..b806b08f95 100644 --- a/runtime/doc/provider.txt +++ b/runtime/doc/provider.txt @@ -1,4 +1,4 @@ -*provider.txt* {Nvim} +*provider.txt* Nvim NVIM REFERENCE MANUAL by Thiago de Arruda @@ -8,6 +8,8 @@ Providers *provider* Nvim delegates some features to dynamic "providers". + Type |gO| to see the table of contents. + ============================================================================== Python integration *provider-python* @@ -18,7 +20,7 @@ Note: Only the Vim 7.3 API is supported; bindeval (Vim 7.4) is not. PYTHON QUICKSTART ~ If you used a package manager to install Nvim, you might already have the -required `neovim` Python package. Run |:CheckHealth| to see if your system is +required `neovim` Python package. Run |:checkhealth| to see if your system is up-to-date. Following are steps to install the package with Python's `pip` tool. @@ -86,7 +88,7 @@ Ruby integration *provider-ruby* Nvim supports the Vim legacy |ruby-vim| interface via external Ruby interpreters connected via |RPC|. -Run |:CheckHealth| to see if your system is up-to-date. +Run |:checkhealth| to see if your system is up-to-date. RUBY QUICKSTART ~ @@ -97,44 +99,74 @@ RUBY PROVIDER CONFIGURATION ~ *g:loaded_ruby_provider* To disable Ruby support: > let g:loaded_ruby_provider = 1 +< + *g:ruby_host_prog* +Command to start the Ruby host. By default this is `neovim-ruby-host`. For users +who use per-project Ruby versions with tools like RVM or rbenv, setting this can +prevent the need to install the `neovim` gem in every project. + +To use an absolute path (e.g. to an rbenv installation): > + let g:ruby_host_prog = '~/.rbenv/versions/2.4.1/bin/neovim-ruby-host' +< + +To use the RVM "system" Ruby installation: > + let g:ruby_host_prog = 'rvm system do neovim-ruby-host' +< ============================================================================== Clipboard integration *provider-clipboard* *clipboard* -Nvim has no direct connection to the system clipboard. Instead it is -accessible through a |provider| which transparently uses shell commands for -communicating with the clipboard. +Nvim has no direct connection to the system clipboard. Instead it depends on +a |provider| which transparently uses shell commands to communicate with the +system clipboard or any other clipboard "backend". -Clipboard access is implicitly enabled if any of the following clipboard tools -are found in your `$PATH`. +To ALWAYS use the clipboard for ALL operations (instead of interacting with +the '+' and/or '*' registers explicitly): > - - xclip - - xsel (newer alternative to xclip) + set clipboard+=unnamedplus +< +See 'clipboard' for details and options. + + *clipboard-tool* +The presence of a working clipboard tool implicitly enables the '+' and '*' +registers. Nvim looks for these clipboard tools, in order of priority: + + - |g:clipboard| - pbcopy/pbpaste (macOS) + - xsel (if $DISPLAY is set) + - xclip (if $DISPLAY is set) - lemonade (for SSH) https://github.com/pocke/lemonade - doitclient (for SSH) http://www.chiark.greenend.org.uk/~sgtatham/doit/ - -The presence of a suitable clipboard tool implicitly enables the '+' and '*' -registers. - -If you want to ALWAYS use the clipboard for ALL operations (as opposed -to interacting with the '+' and/or '*' registers explicitly), set the -following option: -> - set clipboard+=unnamedplus -< -See 'clipboard' for details and more options. + - win32yank (Windows) + - tmux (if $TMUX is set) + + *g:clipboard* +To configure a custom clipboard tool, set `g:clipboard` to a dictionary: > + let g:clipboard = { + \ 'name': 'myClipboard', + \ 'copy': { + \ '+': 'tmux load-buffer -', + \ '*': 'tmux load-buffer -', + \ }, + \ 'paste': { + \ '+': 'tmux save-buffer -', + \ '*': 'tmux save-buffer -', + \ }, + \ 'cache_enabled': 1, + \ } + +If `cache_enabled` is |TRUE| then when a selection is copied, Nvim will cache +the selection until the copy command process dies. When pasting, if the copy +process has not died, the cached selection is applied. ============================================================================== X11 selection mechanism *clipboard-x11* *x11-selection* -The clipboard providers for X11 store text in what is known as "selections". -Selections are "owned" by an application, so when the application is closed, -the selection text is lost. - +X11 clipboard providers store text in "selections". Selections are owned by an +application, so when the application gets closed, the selection text is lost. The contents of selections are held by the originating application (e.g., upon -a copy), and only passed on to another application when that other application -asks for them (e.g., upon a paste). +a copy), and only passed to another application when that other application +requests them (e.g., upon a paste). *quoteplus* *quote+* diff --git a/runtime/doc/quickfix.txt b/runtime/doc/quickfix.txt index ec0b2cfef6..da167c0f5b 100644 --- a/runtime/doc/quickfix.txt +++ b/runtime/doc/quickfix.txt @@ -1,4 +1,4 @@ -*quickfix.txt* For Vim version 7.4. Last change: 2016 Jul 17 +*quickfix.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -6,15 +6,7 @@ This subject is introduced in section |30.1| of the user manual. -1. Using QuickFix commands |quickfix| -2. The error window |quickfix-window| -3. Using more than one list of errors |quickfix-error-lists| -4. Using :make |:make_makeprg| -5. Using :grep |grep| -6. Selecting a compiler |compiler-select| -7. The error format |error-file-format| -8. The directory stack |quickfix-directory-stack| -9. Specific error file formats |errorformats| + Type |gO| to see the table of contents. ============================================================================= 1. Using QuickFix commands *quickfix* *Quickfix* *E42* @@ -39,11 +31,21 @@ From inside Vim an easy way to run a command and handle the output is with the The 'errorformat' option should be set to match the error messages from your compiler (see |errorformat| below). + *quickfix-ID* +Each quickfix list has a unique identifier called the quickfix ID and this +number will not change within a Vim session. The getqflist() function can be +used to get the identifier assigned to a list. There is also a quickfix list +number which may change whenever more than ten lists are added to a quickfix +stack. + *location-list* *E776* -A location list is similar to a quickfix list and contains a list of positions -in files. A location list is associated with a window and each window can -have a separate location list. A location list can be associated with only -one window. The location list is independent of the quickfix list. +A location list is a window-local quickfix list. You get one after commands +like `:lvimgrep`, `:lgrep`, `:lhelpgrep`, `:lmake`, etc., which create a +location list instead of a quickfix list as the corresponding `:vimgrep`, +`:grep`, `:helpgrep`, `:make` do. +A location list is associated with a window and each window can have a +separate location list. A location list can be associated with only one +window. The location list is independent of the quickfix list. When a window with a location list is split, the new window gets a copy of the location list. When there are no longer any references to a location list, @@ -146,11 +148,15 @@ processing a quickfix or location list command, it will be aborted. current window is used instead of the quickfix list. *:cq* *:cquit* -:cq[uit][!] Quit Vim with an error code, so that the compiler - will not compile the same file again. - WARNING: All changes in files are lost! Also when the - [!] is not used. It works like ":qall!" |:qall|, - except that Vim returns a non-zero exit code. +:[count]cq[uit] Quit Nvim with an error code, or the code specified in + [count]. Useful when Nvim is called from another + program: e.g. `git commit` will abort the comitting + process, `fc` (built-in for shells like bash and zsh) + will not execute the command. + + WARNING: All changes in files are lost. It works like + ":qall!" |:qall|, except that Nvim exits non-zero or + [count]. *:cf* *:cfile* :cf[ile][!] [errorfile] Read the error file and jump to the first error. @@ -872,7 +878,7 @@ need to write down a "todo" list. The Vim plugins in the "compiler" directory will set options to use the -selected compiler. For ":compiler" local options are set, for ":compiler!" +selected compiler. For `:compiler` local options are set, for `:compiler!` global options. *current_compiler* To support older Vim versions, the plugins always use "current_compiler" and @@ -1366,7 +1372,7 @@ prints information about entering a directory in the form "Making all in dir". Making all in dir2 ./dir1/dir2 This can be solved by printing absolute directories in the "enter directory" - message or by printing "leave directory" messages.. + message or by printing "leave directory" messages. To avoid this problem, ensure to print absolute directory names and "leave directory" messages. @@ -1542,4 +1548,4 @@ by Vim. - vim:tw=78:ts=8:ft=help:norl: + vim:noet:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/quickref.txt b/runtime/doc/quickref.txt index 2e2bec7637..b22d2afa7e 100644 --- a/runtime/doc/quickref.txt +++ b/runtime/doc/quickref.txt @@ -1,4 +1,4 @@ -*quickref.txt* For Vim version 7.4. Last change: 2016 Aug 12 +*quickref.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -571,8 +571,7 @@ In Insert or Command-line mode: *Q_op* Options |:set| :se[t] show all modified options -|:set| :se[t] all show all non-termcap options -|:set| :se[t] termcap show all termcap options +|:set| :se[t] all show all options |:set| :se[t] {option} set boolean option (switch it on), show string or number option |:set| :se[t] no{option} reset boolean option (switch it off) @@ -715,7 +714,6 @@ Short explanation of each option: *option-list* 'guifont' 'gfn' GUI: Name(s) of font(s) to be used 'guifontset' 'gfs' GUI: Names of multi-byte fonts to be used 'guifontwide' 'gfw' list of font names for double-wide characters -'guiheadroom' 'ghr' GUI: pixels room for window decorations 'guioptions' 'go' GUI: Which components and options are used 'guitablabel' 'gtl' GUI: custom label for a tab page 'guitabtooltip' 'gtt' GUI: custom tooltip for a tab page @@ -723,7 +721,6 @@ Short explanation of each option: *option-list* 'helpheight' 'hh' minimum height of a new help window 'helplang' 'hlg' preferred help languages 'hidden' 'hid' don't unload buffer when it is |abandon|ed -'highlight' 'hl' sets highlighting mode for various occasions 'hlsearch' 'hls' highlight matches with last search pattern 'history' 'hi' number of command-lines that are remembered 'hkmap' 'hk' Hebrew keyboard mapping @@ -752,7 +749,7 @@ Short explanation of each option: *option-list* 'keywordprg' 'kp' program to use for the "K" command 'langmap' 'lmap' alphabetic characters for other language mode 'langmenu' 'lm' language to be used for the menus -'langnoremap' 'lnr' do not apply 'langmap' to mapped characters +'langremap' 'lrm' do apply 'langmap' to mapped characters 'laststatus' 'ls' tells when last window has status lines 'lazyredraw' 'lz' don't redraw while executing macros 'linebreak' 'lbr' wrap long lines at a blank @@ -989,7 +986,6 @@ Short explanation of each option: *option-list* |g_CTRL-G| g CTRL-G show cursor column, line, and character position |CTRL-C| CTRL-C during searches: Interrupt the search -|dos-CTRL-Break| CTRL-Break Windows: during searches: Interrupt the search |<Del>| <Del> while entering a count: delete last character |:version| :ve[rsion] show version information |:normal| :norm[al][!] {commands} @@ -1028,6 +1024,8 @@ Short explanation of each option: *option-list* |c_<Up>| <Up>/<Down> recall older/newer command-line that starts with current command |c_<S-Up>| <S-Up>/<S-Down> recall older/newer command-line from history +|c_CTRL-G| CTRL-G next match when 'incsearch' is active +|c_CTRL-T| CTRL-T previous match when 'incsearch' is active |:history| :his[tory] show older command-lines Context-sensitive completion on the command-line: @@ -1255,6 +1253,7 @@ Context-sensitive completion on the command-line: |:sfind| :sf[ind] {file} split window, find {file} in 'path' and edit it +|:terminal| :terminal {cmd} open a terminal window |CTRL-W_]| CTRL-W ] split window and jump to tag under cursor |CTRL-W_f| CTRL-W f split window and edit file name under diff --git a/runtime/doc/recover.txt b/runtime/doc/recover.txt index e09138b2f5..0533157072 100644 --- a/runtime/doc/recover.txt +++ b/runtime/doc/recover.txt @@ -1,4 +1,4 @@ -*recover.txt* For Vim version 7.4. Last change: 2014 Mar 27 +*recover.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -15,8 +15,7 @@ You can recover most of your changes from the files that Vim uses to store the contents of the file. Mostly you can recover your work with one command: vim -r filename -1. The swap file |swap-file| -2. Recovery |recovery| + Type |gO| to see the table of contents. ============================================================================== 1. The swap file *swap-file* diff --git a/runtime/doc/remote.txt b/runtime/doc/remote.txt index 933ab3a444..039d8b582e 100644 --- a/runtime/doc/remote.txt +++ b/runtime/doc/remote.txt @@ -1,4 +1,4 @@ -*remote.txt* For Vim version 7.4. Last change: 2015 Mar 01 +*remote.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -6,9 +6,7 @@ Vim client-server communication *client-server* -1. Common functionality |clientserver| -2. X11 specific items |x11-clientserver| -3. MS-Windows specific items |w32-clientserver| + Type |gO| to see the table of contents. ============================================================================== 1. Common functionality *clientserver* @@ -89,7 +87,7 @@ Tell the remote server "BLA" to write all files and exit: > vim --servername BLA --remote-send '<C-\><C-N>:wqa<CR>' -SERVER NAME +SERVER NAME *client-server-name* By default Vim will try to register the name under which it was invoked (gvim, egvim ...). This can be overridden with the --servername argument. If the @@ -139,6 +137,7 @@ the description in |eval.txt| or use CTRL-] on the function name to jump to the full explanation. synopsis explanation ~ + remote_startserver( name) run a server remote_expr( server, string, idvar) send expression remote_send( server, string, idvar) send key sequence serverlist() get a list of available servers diff --git a/runtime/doc/remote_plugin.txt b/runtime/doc/remote_plugin.txt index dddc021d68..eeb9cf8150 100644 --- a/runtime/doc/remote_plugin.txt +++ b/runtime/doc/remote_plugin.txt @@ -1,4 +1,4 @@ -*remote_plugin.txt* For Nvim. {Nvim} +*remote_plugin.txt* Nvim NVIM REFERENCE MANUAL by Thiago de Arruda @@ -6,10 +6,7 @@ Nvim support for remote plugins *remote-plugin* -1. Introduction |remote-plugin-intro| -2. Plugin hosts |remote-plugin-hosts| -3. Example |remote-plugin-example| -4. Plugin manifest |remote-plugin-manifest| + Type |gO| to see the table of contents. ============================================================================== 1. Introduction *remote-plugin-intro* diff --git a/runtime/doc/repeat.txt b/runtime/doc/repeat.txt index ef98556260..421ebab100 100644 --- a/runtime/doc/repeat.txt +++ b/runtime/doc/repeat.txt @@ -1,4 +1,4 @@ -*repeat.txt* For Vim version 7.4. Last change: 2016 Jul 21 +*repeat.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -8,14 +8,7 @@ Repeating commands, Vim scripts and debugging *repeating* Chapter 26 of the user manual introduces repeating |usr_26.txt|. -1. Single repeats |single-repeat| -2. Multiple repeats |multi-repeat| -3. Complex repeats |complex-repeat| -4. Using Vim scripts |using-scripts| -5. Using Vim packages |packages| -6. Creating Vim packages |package-create| -7. Debugging scripts |debug-scripts| -8. Profiling |profiling| + Type |gO| to see the table of contents. ============================================================================== 1. Single repeats *single-repeat* @@ -152,7 +145,7 @@ q Stops recording. :[addr]@: Repeat last command-line. First set cursor at line [addr] (default is current line). - *:@@* +:[addr]@ *:@@* :[addr]@@ Repeat the previous :@{0-9a-z"}. First set cursor at line [addr] (default is current line). @@ -357,8 +350,7 @@ terminal-independent two character codes. This means that they can be used in the same way on different kinds of terminals. The first character of a key code is 0x80 or 128, shown on the screen as "~@". The second one can be found in the list |key-notation|. Any of these codes can also be entered -with CTRL-V followed by the three digit decimal code. This does NOT work for -the <t_xx> termcap codes, these can only be used in mappings. +with CTRL-V followed by the three digit decimal code. *:source_crnl* *W15* Windows: Files that are read with ":source" normally have <CR><NL> <EOL>s. @@ -369,12 +361,6 @@ something like ":map <F1> :help^M", where "^M" is a <CR>. If the first line ends in a <CR>, but following ones don't, you will get an error message, because the <CR> from the first lines will be lost. -Mac Classic: Files that are read with ":source" normally have <CR> <EOL>s. -These always work. If you are using a file with <NL> <EOL>s (for example, a -file made on Unix), this will be recognized if 'fileformats' is not empty and -the first line does not end in a <CR>. Be careful not to use a file with <NL> -linebreaks which has a <CR> in first line. - On other systems, Vim expects ":source"ed files to end in a <NL>. These always work. If you are using a file with <CR><NL> <EOL>s (for example, a file made on Windows), all lines will have a trailing <CR>. This may cause diff --git a/runtime/doc/rileft.txt b/runtime/doc/rileft.txt index e4e495bb18..ba9bb1eba7 100644 --- a/runtime/doc/rileft.txt +++ b/runtime/doc/rileft.txt @@ -1,4 +1,4 @@ -*rileft.txt* For Vim version 7.4. Last change: 2006 Apr 24 +*rileft.txt* Nvim VIM REFERENCE MANUAL by Avner Lottem diff --git a/runtime/doc/russian.txt b/runtime/doc/russian.txt index 36f3d0b715..8c6076146c 100644 --- a/runtime/doc/russian.txt +++ b/runtime/doc/russian.txt @@ -1,4 +1,4 @@ -*russian.txt* For Vim version 7.4. Last change: 2006 Apr 24 +*russian.txt* Nvim VIM REFERENCE MANUAL by Vassily Ragosin @@ -6,10 +6,7 @@ Russian language localization and support in Vim *russian* *Russian* -1. Introduction |russian-intro| -2. Russian keymaps |russian-keymap| -3. Localization |russian-l18n| -4. Known issues |russian-issues| + Type |gO| to see the table of contents. =============================================================================== 1. Introduction *russian-intro* diff --git a/runtime/doc/scroll.txt b/runtime/doc/scroll.txt index a9492fc169..99ebd26db3 100644 --- a/runtime/doc/scroll.txt +++ b/runtime/doc/scroll.txt @@ -1,4 +1,4 @@ -*scroll.txt* For Vim version 7.4. Last change: 2006 Aug 27 +*scroll.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -16,12 +16,7 @@ upwards in the buffer, the text in the window moves downwards on your screen. See section |03.7| of the user manual for an introduction. -1. Scrolling downwards |scroll-down| -2. Scrolling upwards |scroll-up| -3. Scrolling relative to cursor |scroll-cursor| -4. Scrolling horizontally |scroll-horizontal| -5. Scrolling synchronously |scroll-binding| -6. Scrolling with a mouse wheel |scroll-mouse-wheel| + Type |gO| to see the table of contents. ============================================================================== 1. Scrolling downwards *scroll-down* @@ -108,7 +103,8 @@ z^ Without [count]: Redraw with the line just above the 3. Scrolling relative to cursor *scroll-cursor* The following commands reposition the edit window (the part of the buffer that -you see) while keeping the cursor on the same line: +you see) while keeping the cursor on the same line. Note that the 'scrolloff' +option may cause context lines to show above and below the cursor. *z<CR>* z<CR> Redraw, line [count] at top of window (default @@ -215,7 +211,7 @@ past its buffer's limits. However, if a 'scrollbind' window that has a relative offset that is past its buffer's limits is given the cursor focus, the other 'scrollbind' windows must jump to a location where the current window's relative offset is valid. This -behavior can be changed by clearing the 'jump' flag from the 'scrollopt' +behavior can be changed by clearing the "jump" flag from the 'scrollopt' option. *syncbind* *:syncbind* *:sync* diff --git a/runtime/doc/sign.txt b/runtime/doc/sign.txt index fd1fe8dce3..977d73b7b2 100644 --- a/runtime/doc/sign.txt +++ b/runtime/doc/sign.txt @@ -1,4 +1,4 @@ -*sign.txt* For Vim version 7.4. Last change: 2016 Aug 12 +*sign.txt* Nvim VIM REFERENCE MANUAL by Gordon Prieur @@ -7,8 +7,7 @@ Sign Support Features *sign-support* -1. Introduction |sign-intro| -2. Commands |sign-commands| + Type |gO| to see the table of contents. ============================================================================== 1. Introduction *sign-intro* *signs* @@ -188,7 +187,9 @@ JUMPING TO A SIGN *:sign-jump* *E157* If the file isn't displayed in window and the current file can not be |abandon|ed this fails. -:sign jump {id} buffer={nr} - Same, but use buffer {nr}. +:sign jump {id} buffer={nr} *E934* + Same, but use buffer {nr}. This fails if buffer {nr} does not + have a name. + vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/spell.txt b/runtime/doc/spell.txt index 0902d5d10f..718b5d4c1f 100644 --- a/runtime/doc/spell.txt +++ b/runtime/doc/spell.txt @@ -1,4 +1,4 @@ -*spell.txt* +*spell.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -6,10 +6,7 @@ Spell checking *spell* -1. Quick start |spell-quickstart| -2. Remarks on spell checking |spell-remarks| -3. Generating a spell file |spell-mkspell| -4. Spell file format |spell-file-format| + Type |gO| to see the table of contents. ============================================================================== 1. Quick start *spell-quickstart* *E756* @@ -462,7 +459,7 @@ Vim uses a binary file format for spelling. This greatly speeds up loading the word list and keeps it small. *.aff* *.dic* *Myspell* You can create a Vim spell file from the .aff and .dic files that Myspell -uses. Myspell is used by OpenOffice.org and Mozilla. The OpenOffice .oxt +uses. Myspell is used by OpenOffice.org and Mozilla. The OpenOffice .oxt files are zip files which contain the .aff and .dic files. You should be able to find them here: http://extensions.services.openoffice.org/dictionary @@ -707,7 +704,7 @@ Additionally the following items are recognized: = Case must match exactly. ? Rare word. ! Bad (wrong) word. - digit A region in which the word is valid. If no regions are + 1 to 9 A region in which the word is valid. If no regions are specified the word is valid in all regions. Example: @@ -1597,7 +1594,7 @@ COMPOUNDSYLLABLE (Hunspell) *spell-COMPOUNDSYLLABLE* KEY (Hunspell) *spell-KEY* Define characters that are close together on the keyboard. Used to give better suggestions. Not supported. - + LANG (Hunspell) *spell-LANG* This specifies language-specific behavior. This actually moves part of the language knowledge into the program, diff --git a/runtime/doc/sponsor.txt b/runtime/doc/sponsor.txt index a99d66d843..cfdf21abea 100644 --- a/runtime/doc/sponsor.txt +++ b/runtime/doc/sponsor.txt @@ -1,4 +1,4 @@ -*sponsor.txt* For Vim version 7.4. Last change: 2008 Jun 21 +*sponsor.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt index 2c024d3c75..9b33926d04 100644 --- a/runtime/doc/starting.txt +++ b/runtime/doc/starting.txt @@ -1,4 +1,4 @@ -*starting.txt* For Vim version 7.4. Last change: 2016 Jul 03 +*starting.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -6,15 +6,7 @@ Starting Vim *starting* -1. Vim arguments |vim-arguments| -2. Initialization |initialization| -3. $VIM and $VIMRUNTIME |$VIM| -4. Suspending |suspend| -5. Exiting |exiting| -6. Saving settings |save-settings| -7. Views and Sessions |views-sessions| -8. The ShaDa file |shada-file| -9. Base Directories |base-directories| + Type |gO| to see the table of contents. ============================================================================== 1. Vim arguments *vim-arguments* @@ -61,7 +53,7 @@ filename One or more file names. The first one will be the current < Starting in Ex mode: > nvim -e - nvim -E -< Start editing in silent mode. See |-s-ex|. +< Start editing in |silent-mode|. *-t* *-tag* -t {tag} A tag. "tag" is looked up in the tags file, the associated @@ -181,6 +173,7 @@ argument. the executable "view" has the same effect as the -R argument. The 'updatecount' option will be set to 10000, meaning that the swap file will not be updated automatically very often. + See |-M| for disallowing modifications. *-m* -m Modifications not allowed to be written. The 'write' option @@ -207,7 +200,7 @@ argument. *-E* -E Start Vim in improved Ex mode |gQ|. - *-s-ex* + *-s-ex* *silent-mode* -s Silent or batch mode. Only when "-s" is preceded by the "-e" argument. Otherwise see |-s|, which does take an argument while this use of "-s" doesn't. To be used when Vim is used @@ -221,14 +214,14 @@ argument. :set to display option values. When 'verbose' is non-zero messages are printed (for debugging, to stderr). - $TERM is not used. + |$TERM| is not used. If Vim appears to be stuck try typing "qa!<Enter>". You don't get a prompt thus you can't see Vim is waiting for you to type something. Initializations are skipped (except the ones given with the "-u" argument). Example: > - vim -e -s < thefilter thefile + vim -es < thefilter thefile < *-b* -b Binary mode. File I/O will only recognize <NL> to separate @@ -356,13 +349,19 @@ argument. *--api-info* --api-info Print msgpack-encoded |api-metadata| and exit. + *--headless* +--headless Do not start the built-in UI. + See |channel-stdio| for how to use stdio for other purposes + instead. + See also |silent-mode|, which does start a (limited) UI. + ============================================================================== 2. Initialization *initialization* *startup* At startup, Vim checks environment variables and files and sets values accordingly. Vim proceeds in this order: -1. Set the 'shell' option *SHELL* *COMSPEC* *TERM* +1. Set the 'shell' option *SHELL* *COMSPEC* The environment variable SHELL, if it exists, is used to set the 'shell' option. On Windows, the COMSPEC variable is used if SHELL is not set. @@ -425,7 +424,7 @@ accordingly. Vim proceeds in this order: - The environment variable EXINIT. The value of $EXINIT is used as an Ex command line. - c. If the 'exrc' option is on (which is not the default), the current + c. If the 'exrc' option is on (which is NOT the default), the current directory is searched for three files. The first that exists is used, the others are ignored. - The file ".nvimrc" (for Unix) @@ -457,6 +456,8 @@ accordingly. Vim proceeds in this order: searched for the "plugin" sub-directory and all files ending in ".vim" will be sourced (in alphabetical order per directory), also in subdirectories. + However, directories in 'runtimepath' ending in "after" are skipped + here and only loaded after packages, see below. Loading plugins won't be done when: - The 'loadplugins' option was reset in a vimrc file. - The |--noplugin| command line argument is used. @@ -464,13 +465,18 @@ accordingly. Vim proceeds in this order: - When Vim was compiled without the |+eval| feature. Note that using "-c 'set noloadplugins'" doesn't work, because the commands from the command line have not been executed yet. You can - use "--cmd 'set noloadplugins'" |--cmd|. + use "--cmd 'set noloadplugins'" or "--cmd 'set loadplugins'" |--cmd|. Packages are loaded. These are plugins, as above, but found in the "start" directory of each entry in 'packpath'. Every plugin directory found is added in 'runtimepath' and then the plugins are sourced. See |packages|. + The plugins scripts are loaded, as above, but now only the directories + ending in "after" are used. Note that 'runtimepath' will have changed + if packages have been found, but that should not add a directory + ending in "after". + 7. Set 'shellpipe' and 'shellredir' The 'shellpipe' and 'shellredir' options are set according to the value of the 'shell' option, unless they have been set before. @@ -511,7 +517,8 @@ accordingly. Vim proceeds in this order: The |v:vim_did_enter| variable is set to 1. The |VimEnter| autocommands are executed. -Some hints on using initializations: + +Some hints on using initializations ~ Standard setup: Create a vimrc file to set the default settings and mappings for all your edit @@ -533,17 +540,23 @@ the ":version" command. NOTE: System vimrc file needs specific compilation options (one needs to define SYS_VIMRC_FILE macros). If :version command does not show anything like this, consider contacting the nvim package maintainer. -Saving the current state of Vim to a file: + +Saving the current state of Vim to a file ~ + Whenever you have changed values of options or when you have created a mapping, then you may want to save them in a vimrc file for later use. See |save-settings| about saving the current state of settings to a file. -Avoiding setup problems for Vi users: + +Avoiding setup problems for Vi users ~ + Vi uses the variable EXINIT and the file "~/.exrc". So if you do not want to interfere with Vi, then use the variable VIMINIT and the file init.vim instead. -MS-DOS line separators: + +MS-DOS line separators: ~ + On Windows systems Vim assumes that all the vimrc files have <CR> <NL> pairs as line separators. This will give problems if you have a file with only <NL>s and have a line like ":map xx yy^M". The trailing ^M will be ignored. @@ -551,8 +564,10 @@ as line separators. This will give problems if you have a file with only The $MYVIMRC or $MYGVIMRC file will be set to the first found vimrc and/or gvimrc file. -Avoiding trojan horses: *trojan-horse* -While reading the vimrc or the exrc file in the current directory, some + +Avoiding trojan horses ~ + *trojan-horse* +While reading the "vimrc" or the "exrc" file in the current directory, some commands can be disabled for security reasons by setting the 'secure' option. This is always done when executing the command from a tags file. Otherwise it would be possible that you accidentally use a vimrc or tags file that somebody @@ -574,6 +589,8 @@ Be careful! part of the line in the tags file) is always done in secure mode. This works just like executing a command from a vimrc/exrc in the current directory. + +If Vim startup is slow ~ *slow-start* If Vim takes a long time to start up, use the |--startuptime| argument to find out what happens. @@ -583,6 +600,8 @@ while. You can find out if this is the problem by disabling ShaDa for a moment (use the Vim argument "-i NONE", |-i|). Try reducing the number of lines stored in a register with ":set shada='20,<50,s10". |shada-file|. + +Intro message ~ *:intro* When Vim starts without a file name, an introductory message is displayed (for those who don't know what Vim is). It is removed as soon as the display is @@ -616,54 +635,40 @@ though. ============================================================================== 3. $VIM and $VIMRUNTIME *$VIM* -The environment variable "$VIM" is used to locate various user files for Vim, +The environment variable "$VIM" is used to locate various user files for Nvim, such as the user startup script |init.vim|. This depends on the system, see |startup|. -To avoid the need for every user to set the $VIM environment variable, Vim -will try to get the value for $VIM in this order: -1. The value defined by the $VIM environment variable. You can use this to - make Vim look in a specific directory for its support files. Example: > - setenv VIM /home/paul/vim -2. The path from 'helpfile' is used, unless it contains some environment - variable too (the default is "$VIMRUNTIME/doc/help.txt": chicken-egg - problem). The file name ("help.txt" or any other) is removed. Then - trailing directory names are removed, in this order: "doc", "runtime" and - "vim{version}" (e.g., "vim54"). -3. For MSDOS and Win32 Vim tries to use the directory name of the - executable. If it ends in "/src", this is removed. This is useful if you - unpacked the .zip file in some directory, and adjusted the search path to - find the vim executable. Trailing directory names are removed, in this - order: "runtime" and "vim{version}" (e.g., "vim54"). -4. For Unix the compile-time defined installation directory is used (see the - output of ":version"). - -Once Vim has done this once, it will set the $VIM environment variable. To -change it later, use a ":let" command like this: > - :let $VIM = "/home/paul/vim/" -< +Nvim will try to get the value for $VIM in this order: + +1. Environment variable $VIM, if it is set. +2. Path derived from the 'helpfile' option, unless it contains some + environment variable too (default is "$VIMRUNTIME/doc/help.txt"). File + name ("help.txt", etc.) is removed. Trailing directory names are removed, + in this order: "doc", "runtime". +3. Path derived from the location of the `nvim` executable. +4. Compile-time defined installation directory (see output of ":version"). + +After doing this once, Nvim sets the $VIM environment variable. + *$VIMRUNTIME* The environment variable "$VIMRUNTIME" is used to locate various support -files, such as the on-line documentation and files used for syntax -highlighting. For example, the main help file is normally -"$VIMRUNTIME/doc/help.txt". -You don't normally set $VIMRUNTIME yourself, but let Vim figure it out. This -is the order used to find the value of $VIMRUNTIME: -1. If the environment variable $VIMRUNTIME is set, it is used. You can use - this when the runtime files are in an unusual location. -2. If "$VIM/vim{version}" exists, it is used. {version} is the version - number of Vim, without any '-' or '.'. For example: "$VIM/vim54". This is - the normal value for $VIMRUNTIME. -3. If "$VIM/runtime" exists, it is used. -4. The value of $VIM is used. This is for backwards compatibility with older - versions. +files, such as the documentation and syntax-highlighting files. For example, +the main help file is normally "$VIMRUNTIME/doc/help.txt". + +Nvim will try to get the value for $VIMRUNTIME in this order: + +1. Environment variable $VIMRUNTIME, if it is set. +2. Directory path "$VIM/vim{version}", if it exists, where {version} is the + Vim version number without '-' or '.'. For example: "$VIM/vim54". +3. Directory path "$VIM/runtime", if it exists. +4. Value of $VIM environment variable. This is for backwards compatibility + with older Vim versions. 5. If "../share/nvim/runtime" exists relative to |v:progpath|, it is used. -6. When the 'helpfile' option is set and doesn't contain a '$', its value is - used, with "doc/help.txt" removed from the end. +6. Path derived from the 'helpfile' option (if it doesn't contain '$') with + "doc/help.txt" removed from the end. -Once Vim has done this once, it will set the $VIMRUNTIME environment variable. -To change it later, use a ":let" command like this: > - :let $VIMRUNTIME = "/home/piet/vim/vim54" +After doing this once, Nvim sets the $VIMRUNTIME environment variable. In case you need the value of $VIMRUNTIME in a shell (e.g., for a script that greps in the help files) you might be able to use this: > @@ -714,7 +719,7 @@ There are several ways to exit Vim: - Use `:cquit`. Also when there are changes. When using `:cquit` or when there was an error message Vim exits with exit -code 1. Errors can be avoided by using `:silent!`. +code 1. Errors can be avoided by using `:silent!` or with `:catch`. ============================================================================== 6. Saving settings *save-settings* @@ -882,7 +887,7 @@ The output of ":mkview" contains these items: 5. The scroll position and the cursor position in the file. Doesn't work very well when there are closed folds. 6. The local current directory, if it is different from the global current - directory. + directory and 'viewoptions' contains "curdir". Note that Views and Sessions are not perfect: - They don't restore everything. For example, defined functions, autocommands @@ -915,7 +920,7 @@ You might want to clean up your 'viewdir' directory now and then. To automatically save and restore views for *.c files: > au BufWinLeave *.c mkview - au BufWinEnter *.c silent loadview + au BufWinEnter *.c silent! loadview ============================================================================== 8. The ShaDa file *shada* *shada-file* @@ -1090,23 +1095,6 @@ SHADA FILE NAME *shada-file-name* default and the name given with 'shada' or "-i" (unless it's NONE). -CHARACTER ENCODING *shada-encoding* - -The text in the ShaDa file is UTF-8-encoded. Normally you will always work -with the same 'encoding' value, and this works just fine. However, if you -read the ShaDa file with value for 'encoding' different from utf-8 and -'encoding' used when writing ShaDa file, some of the text (non-ASCII -characters) may be invalid as Neovim always attempts to convert the text in -the ShaDa file from the UTF-8 to the current 'encoding' value. Filenames are -never converted, affected elements are: - -- history strings; -- variable values; -- register values; -- last used search and substitute patterns; -- last used substitute replacement string. - - MANUALLY READING AND WRITING *shada-read-write* Two commands can be used to read and write the ShaDa file manually. This @@ -1192,8 +1180,11 @@ running) you have additional options: *:o* *:ol* *:oldfiles* :o[ldfiles] List the files that have marks stored in the ShaDa file. This list is read on startup and only changes - afterwards with ":rshada!". Also see |v:oldfiles|. + afterwards with `:rshada!`. Also see |v:oldfiles|. The number can be used with |c_#<|. + The output can be filtered with |:filter|, e.g.: > + filter /\.vim/ oldfiles +< The filtering happens on the file name. :bro[wse] o[ldfiles][!] List file names as with |:oldfiles|, and then prompt @@ -1214,8 +1205,11 @@ exactly four MessagePack objects: 3. Third goes the length of the fourth entry. Unsigned integer as well, used for fast skipping without parsing. 4. Fourth is actual entry data. All currently used ShaDa entries use - containers to hold data: either map or array. Exact format depends on the - entry type: + containers to hold data: either map or array. All string values in those + containers are either binary (applies to filenames) or UTF-8, yet parser + needs to expect that invalid bytes may be present in a UTF-8 string. + + Exact format depends on the entry type: Entry type (name) Entry data ~ 1 (Header) Map containing data that describes the generator @@ -1279,29 +1273,32 @@ exactly four MessagePack objects: 5 (Register) Map describing one register (|registers|). If key value is equal to default then it is normally not present. Keys: - Key Type Def Description ~ - rt UInteger 0 Register type: - No Description ~ - 0 |characterwise-register| - 1 |linewise-register| - 2 |blockwise-register| - rw UInteger 0 Register width. Only valid - for |blockwise-register|s. - rc Array of binary N/A Register contents. Each - entry in the array - represents its own line. - NUL characters inside the - line should be represented - as NL according to - |NL-used-for-Nul|. - n UInteger N/A Register name: character - code in range [1, 255]. - Example: |quote0| register - has name 48 (ASCII code for - zero character). - * any none Other keys are allowed - for compatibility reasons, - see |shada-compatibility|. + Key Type Def Description ~ + rt UInteger 0 Register type: + No Description ~ + 0 |characterwise-register| + 1 |linewise-register| + 2 |blockwise-register| + rw UInteger 0 Register width. Only valid + for |blockwise-register|s. + rc Array of binary N/A Register contents. Each + entry in the array + represents its own line. + NUL characters inside the + line should be represented + as NL according to + |NL-used-for-Nul|. + ru Boolean false Unnamed register. Whether + the unnamed register had + pointed to this register. + n UInteger N/A Register name: character + code in range [1, 255]. + Example: |quote0| register + has name 48 (ASCII code for + zero character). + * any none Other keys are allowed + for compatibility reasons, + see |shada-compatibility|. 6 (Variable) Array containing two items: variable name (binary) and variable value (any object). Values are converted using the same code |msgpackparse()| uses when reading, @@ -1361,39 +1358,38 @@ file when reading and include: complete MessagePack object. ============================================================================== -9. Base Directories *base-directories* *xdg* - -Nvim conforms to the XDG Base Directory Specification for application -configuration and data file locations. This just means Nvim looks for some -optional settings and uses them if they exist, otherwise defaults are chosen. -https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html - -CONFIGURATION DIRECTORY *$XDG_CONFIG_HOME* - - Base directory default: - Unix: ~/.config - Windows: ~/AppData/Local - - Nvim directory: - Unix: ~/.config/nvim/ - Windows: ~/AppData/Local/nvim/ +9. Standard Paths -DATA DIRECTORY *$XDG_DATA_HOME* +Nvim stores configuration and data in standard locations. Plugins are strongly +encouraged to follow this pattern also. - Base directory default: - Unix: ~/.local/share - Windows: ~/AppData/Local - - Nvim directory: - Unix: ~/.local/share/nvim/ - Windows: ~/AppData/Local/nvim-data/ - -Note on Windows the configuration and data directory defaults are the same -(for lack of an alternative), but the sub-directory for data is named -"nvim-data" to separate it from the configuration sub-directory "nvim". - -Throughout other sections of the user manual, the defaults are used as generic -placeholders, e.g. where "~/.config" is mentioned it should be understood to -mean "$XDG_CONFIG_HOME or ~/.config". + *base-directories* *xdg* +The "base" (root) directories conform to the XDG Base Directory Specification. +https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html +The $XDG_CONFIG_HOME and $XDG_DATA_HOME environment variables are used if they +exist, otherwise default values (listed below) are used. + +Note: Throughout the user manual these defaults are used as placeholders, e.g. +"~/.config" is understood to mean "$XDG_CONFIG_HOME or ~/.config". + +CONFIG DIRECTORY *$XDG_CONFIG_HOME* + Base Nvim ~ +Unix: ~/.config ~/.config/nvim +Windows: ~/AppData/Local ~/AppData/Local/nvim + +DATA DIRECTORY *$XDG_DATA_HOME* + Base Nvim ~ +Unix: ~/.local/share ~/.local/share/nvim +Windows: ~/AppData/Local ~/AppData/Local/nvim-data + +STANDARD PATHS *standard-path* + + *$NVIM_LOG_FILE* +Besides 'debug' and 'verbose', Nvim has a low-level "log of last resort" that +is written directly to the filesystem. This log may also be used by plugins or +RPC clients for debugging. $NVIM_LOG_FILE contains the log file path: > + :echo $NVIM_LOG_FILE +Usually the file is ~/.local/share/nvim/log unless that path is inaccessible +or if $NVIM_LOG_FILE was set before |startup|. vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt index e59f567826..85330f3dec 100644 --- a/runtime/doc/syntax.txt +++ b/runtime/doc/syntax.txt @@ -1,4 +1,4 @@ -*syntax.txt* For Vim version 7.4. Last change: 2016 Aug 10 +*syntax.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -20,24 +20,7 @@ In the User Manual: |usr_06.txt| introduces syntax highlighting. |usr_44.txt| introduces writing a syntax file. -1. Quick start |:syn-qstart| -2. Syntax files |:syn-files| -3. Syntax loading procedure |syntax-loading| -4. Syntax file remarks |:syn-file-remarks| -5. Defining a syntax |:syn-define| -6. :syntax arguments |:syn-arguments| -7. Syntax patterns |:syn-pattern| -8. Syntax clusters |:syn-cluster| -9. Including syntax files |:syn-include| -10. Synchronizing |:syn-sync| -11. Listing syntax items |:syntax| -12. Highlight command |:highlight| -13. Linking groups |:highlight-link| -14. Cleaning up |:syn-clear| -15. Highlighting tags |tag-highlight| -16. Window-local syntax |:ownsyntax| -17. Color xterms |xterm-color| -18. When syntax is slow |:syntime| + Type |gO| to see the table of contents. ============================================================================== 1. Quick start *:syn-qstart* @@ -56,10 +39,12 @@ fine. If it doesn't, try setting the VIM environment variable to the directory where the Vim stuff is located. For example, if your syntax files are in the "/usr/vim/vim50/syntax" directory, set $VIMRUNTIME to "/usr/vim/vim50". You must do this in the shell, before starting Vim. +This command also sources the |menu.vim| script when the GUI is running or +will start soon. See |'go-M'| about avoiding that. *:syn-on* *:syntax-on* -The ":syntax enable" command will keep your current color settings. This -allows using ":highlight" commands to set your preferred colors before or +The `:syntax enable` command will keep your current color settings. This +allows using `:highlight` commands to set your preferred colors before or after using this command. If you want Vim to overrule your settings with the defaults, use: > :syntax on @@ -805,12 +790,9 @@ See |mysyntaxfile-add| for installing script languages permanently. APACHE *apache.vim* *ft-apache-syntax* -The apache syntax file provides syntax highlighting depending on Apache HTTP -server version, by default for 1.3.x. Set "apache_version" to Apache version -(as a string) to get highlighting for another version. Example: > +The apache syntax file provides syntax highlighting for Apache HTTP server +version 2.2.3. - :let apache_version = "2.0" -< *asm.vim* *asmh8300.vim* *nasm.vim* *masm.vim* *asm68k* ASSEMBLY *ft-asm-syntax* *ft-asmh8300-syntax* *ft-nasm-syntax* @@ -1472,7 +1454,7 @@ algorithm should work in the vast majority of cases. In some cases, such as a file that begins with 500 or more full-line comments, the script may incorrectly decide that the fortran code is in fixed form. If that happens, just add a non-comment statement beginning anywhere in the first five columns -of the first twenty five lines, save (:w) and then reload (:e!) the file. +of the first twenty-five lines, save (:w) and then reload (:e!) the file. Tabs in fortran files ~ Tabs are not recognized by the Fortran standards. Tabs are not a good idea in @@ -2125,6 +2107,16 @@ set "msql_minlines" to the value you desire. Example: > :let msql_minlines = 200 +N1QL *n1ql.vim* *ft-n1ql-syntax* + +N1QL is a SQL-like declarative language for manipulating JSON documents in +Couchbase Server databases. + +Vim syntax highlights N1QL statements, keywords, operators, types, comments, +and special values. Vim ignores syntactical elements specific to SQL or its +many dialects, like COLUMN or CHAR, that don't exist in N1QL. + + NCF *ncf.vim* *ft-ncf-syntax* There is one option for NCF syntax highlighting. @@ -2633,9 +2625,9 @@ later, and part earlier) adds. RESTRUCTURED TEXT *rst.vim* *ft-rst-syntax* -You may set what syntax definitions should be used for code blocks via +You may set what syntax definitions should be used for code blocks via > let rst_syntax_code_list = ['vim', 'lisp', ...] - +< REXX *rexx.vim* *ft-rexx-syntax* @@ -2656,68 +2648,103 @@ your vimrc: *g:filetype_r* RUBY *ruby.vim* *ft-ruby-syntax* -There are a number of options to the Ruby syntax highlighting. + Ruby: Operator highlighting |ruby_operators| + Ruby: Whitespace errors |ruby_space_errors| + Ruby: Folding |ruby_fold| |ruby_foldable_groups| + Ruby: Reducing expensive operations |ruby_no_expensive| |ruby_minlines| + Ruby: Spellchecking strings |ruby_spellcheck_strings| -By default, the "end" keyword is colorized according to the opening statement -of the block it closes. While useful, this feature can be expensive; if you -experience slow redrawing (or you are on a terminal with poor color support) -you may want to turn it off by defining the "ruby_no_expensive" variable: > + *ruby_operators* + Ruby: Operator highlighting ~ - :let ruby_no_expensive = 1 +Operators can be highlighted by defining "ruby_operators": > + + :let ruby_operators = 1 < -In this case the same color will be used for all control keywords. + *ruby_space_errors* + Ruby: Whitespace errors ~ -If you do want this feature enabled, but notice highlighting errors while -scrolling backwards, which are fixed when redrawing with CTRL-L, try setting -the "ruby_minlines" variable to a value larger than 50: > +Whitespace errors can be highlighted by defining "ruby_space_errors": > - :let ruby_minlines = 100 + :let ruby_space_errors = 1 < -Ideally, this value should be a number of lines large enough to embrace your -largest class or module. +This will highlight trailing whitespace and tabs preceded by a space character +as errors. This can be refined by defining "ruby_no_trail_space_error" and +"ruby_no_tab_space_error" which will ignore trailing whitespace and tabs after +spaces respectively. -Highlighting of special identifiers can be disabled by removing the -rubyIdentifier highlighting: > + *ruby_fold* *ruby_foldable_groups* + Ruby: Folding ~ + +Folding can be enabled by defining "ruby_fold": > - :hi link rubyIdentifier NONE + :let ruby_fold = 1 < -This will prevent highlighting of special identifiers like "ConstantName", -"$global_var", "@@class_var", "@instance_var", "| block_param |", and -":symbol". +This will set the value of 'foldmethod' to "syntax" locally to the current +buffer or window, which will enable syntax-based folding when editing Ruby +filetypes. + +Default folding is rather detailed, i.e., small syntax units like "if", "do", +"%w[]" may create corresponding fold levels. -Significant methods of Kernel, Module and Object are highlighted by default. -This can be disabled by defining "ruby_no_special_methods": > +You can set "ruby_foldable_groups" to restrict which groups are foldable: > - :let ruby_no_special_methods = 1 + :let ruby_foldable_groups = 'if case %' < -This will prevent highlighting of important methods such as "require", "attr", -"private", "raise" and "proc". +The value is a space-separated list of keywords: + + keyword meaning ~ + -------- ------------------------------------- ~ + ALL Most block syntax (default) + NONE Nothing + if "if" or "unless" block + def "def" block + class "class" block + module "module" block + do "do" block + begin "begin" block + case "case" block + for "for", "while", "until" loops + { Curly bracket block or hash literal + [ Array literal + % Literal with "%" notation, e.g.: %w(STRING), %!STRING! + / Regexp + string String and shell command output (surrounded by ', ", `) + : Symbol + # Multiline comment + << Here documents + __END__ Source code after "__END__" directive + + *ruby_no_expensive* + Ruby: Reducing expensive operations ~ -Ruby operators can be highlighted. This is enabled by defining -"ruby_operators": > +By default, the "end" keyword is colorized according to the opening statement +of the block it closes. While useful, this feature can be expensive; if you +experience slow redrawing (or you are on a terminal with poor color support) +you may want to turn it off by defining the "ruby_no_expensive" variable: > - :let ruby_operators = 1 + :let ruby_no_expensive = 1 < -Whitespace errors can be highlighted by defining "ruby_space_errors": > +In this case the same color will be used for all control keywords. - :let ruby_space_errors = 1 -< -This will highlight trailing whitespace and tabs preceded by a space character -as errors. This can be refined by defining "ruby_no_trail_space_error" and -"ruby_no_tab_space_error" which will ignore trailing whitespace and tabs after -spaces respectively. + *ruby_minlines* -Folding can be enabled by defining "ruby_fold": > +If you do want this feature enabled, but notice highlighting errors while +scrolling backwards, which are fixed when redrawing with CTRL-L, try setting +the "ruby_minlines" variable to a value larger than 50: > - :let ruby_fold = 1 + :let ruby_minlines = 100 < -This will set the 'foldmethod' option to "syntax" and allow folding of -classes, modules, methods, code blocks, heredocs and comments. +Ideally, this value should be a number of lines large enough to embrace your +largest class or module. -Folding of multiline comments can be disabled by defining -"ruby_no_comment_fold": > + *ruby_spellcheck_strings* + Ruby: Spellchecking strings ~ - :let ruby_no_comment_fold = 1 +Ruby syntax will perform spellchecking of strings if you define +"ruby_spellcheck_strings": > + + :let ruby_spellcheck_strings = 1 < SCHEME *scheme.vim* *ft-scheme-syntax* @@ -2815,9 +2842,11 @@ vimrc file: > (Adapted from the html.vim help text by Claudio Fleiner <claudio@fleiner.com>) -SH *sh.vim* *ft-sh-syntax* *ft-bash-syntax* *ft-ksh-syntax* + *ft-posix-synax* *ft-dash-syntax* +SH *sh.vim* *ft-sh-syntax* *ft-bash-syntax* *ft-ksh-syntax* -This covers the "normal" Unix (Bourne) sh, bash and the Korn shell. +This covers syntax highlighting for the older Unix (Bourne) sh, and newer +shells such as bash, dash, posix, and the Korn shells. Vim attempts to determine which shell type is in use by specifying that various filenames are of specific types: > @@ -2826,28 +2855,31 @@ various filenames are of specific types: > bash: .bashrc* bashrc bash.bashrc .bash_profile* *.bash < If none of these cases pertain, then the first line of the file is examined -(ex. /bin/sh /bin/ksh /bin/bash). If the first line specifies a shelltype, -then that shelltype is used. However some files (ex. .profile) are known to -be shell files but the type is not apparent. Furthermore, on many systems -sh is symbolically linked to "bash" (Linux, Windows+cygwin) or "ksh" (Posix). +(ex. looking for /bin/sh /bin/ksh /bin/bash). If the first line specifies a +shelltype, then that shelltype is used. However some files (ex. .profile) are +known to be shell files but the type is not apparent. Furthermore, on many +systems sh is symbolically linked to "bash" (Linux, Windows+cygwin) or "ksh" +(Posix). -One may specify a global default by instantiating one of the following three +One may specify a global default by instantiating one of the following variables in your vimrc: - ksh: > + ksh: > let g:is_kornshell = 1 -< posix: (using this is the same as setting is_kornshell to 1) > +< posix: (using this is the nearly the same as setting g:is_kornshell to 1) > let g:is_posix = 1 < bash: > let g:is_bash = 1 < sh: (default) Bourne shell > let g:is_sh = 1 +< (dash users should use posix) + If there's no "#! ..." line, and the user hasn't availed himself/herself of a default sh.vim syntax setting as just shown, then syntax/sh.vim will assume the Bourne shell syntax. No need to quote RFCs or market penetration statistics in error reports, please -- just select the default version of the -sh your system uses in your vimrc. +sh your system uses and install the associated "let..." in your <.vimrc>. The syntax/sh.vim file provides several levels of syntax-based folding: > @@ -2856,7 +2888,7 @@ The syntax/sh.vim file provides several levels of syntax-based folding: > let g:sh_fold_enabled= 2 (enable heredoc folding) let g:sh_fold_enabled= 4 (enable if/do/for folding) > -then various syntax items (HereDocuments and function bodies) become +then various syntax items (ie. HereDocuments and function bodies) become syntax-foldable (see |:syn-fold|). You also may add these together to get multiple types of folding: > @@ -2880,14 +2912,14 @@ reduce this, the "sh_maxlines" internal variable can be set. Example: > The default is to use the twice sh_minlines. Set it to a smaller number to speed up displaying. The disadvantage is that highlight errors may appear. - *g:sh_isk* *g:sh_noisk* -The shell languages appear to let "." be part of words, commands, etc; -consequently it should be in the isk for sh.vim. As of v116 of syntax/sh.vim, -syntax/sh.vim will append the "." to |'iskeyword'| by default; you may control -this behavior with: > - let g:sh_isk = '..whatever characters you want as part of iskeyword' - let g:sh_noisk= 1 " otherwise, if this exists, the isk will NOT chg +syntax/sh.vim tries to flag certain problems as errors; usually things like +extra ']'s, 'done's, 'fi's, etc. If you find the error handling problematic +for your purposes, you may suppress such error highlighting by putting +the following line in your .vimrc: > + + let g:sh_no_error= 1 < + *sh-embed* *sh-awk* Sh: EMBEDDING LANGUAGES~ @@ -3189,11 +3221,11 @@ syntax highlighting script handles this with the following logic: * If g:tex_stylish exists and is 1 then the file will be treated as a "sty" file, so the "_" will be allowed as part of keywords - (irregardless of g:tex_isk) + (regardless of g:tex_isk) * Else if the file's suffix is sty, cls, clo, dtx, or ltx, then the file will be treated as a "sty" file, so the "_" will be allowed as part of keywords - (irregardless of g:tex_isk) + (regardless of g:tex_isk) * If g:tex_isk exists, then it will be used for the local 'iskeyword' * Else the local 'iskeyword' will be set to 48-57,a-z,A-Z,192-255 @@ -3247,11 +3279,10 @@ improve screen updating rates (see |:syn-sync| for more on this). > The g:vimsyn_embed option allows users to select what, if any, types of embedded script highlighting they wish to have. > - g:vimsyn_embed == 0 : don't embed any scripts - g:vimsyn_embed =~ 'P' : support embedded python + g:vimsyn_embed == 0 : disable (don't embed any scripts) + g:vimsyn_embed == 'lPr' : support embedded lua, python and ruby < -By default, g:vimsyn_embed is a string supporting interpreters that your vim -itself supports. +This option is disabled by default. *g:vimsyn_folding* Some folding is now supported with syntax/vim.vim: > @@ -3262,8 +3293,8 @@ Some folding is now supported with syntax/vim.vim: > g:vimsyn_folding =~ 'P' : fold python script < *g:vimsyn_noerror* -Not all error highlighting that syntax/vim.vim does may be correct; VimL is a -difficult language to highlight correctly. A way to suppress error +Not all error highlighting that syntax/vim.vim does may be correct; Vim script +is a difficult language to highlight correctly. A way to suppress error highlighting is to put the following line in your |vimrc|: > let g:vimsyn_noerror = 1 @@ -3421,6 +3452,8 @@ DEFINING CASE *:syn-case* *E390* "ignore". Note that any items before this are not affected, and all items until the next ":syntax case" command are affected. +:sy[ntax] case + Show either "syntax case match" or "syntax case ignore" (translated). SPELL CHECKING *:syn-spell* @@ -3438,6 +3471,11 @@ SPELL CHECKING *:syn-spell* To activate spell checking the 'spell' option must be set. +:sy[ntax] spell + Show either "syntax spell toplevel", "syntax spell notoplevel" or + "syntax spell default" (translated). + + SYNTAX ISKEYWORD SETTING *:syn-iskeyword* :sy[ntax] iskeyword [clear | {option}] @@ -3461,8 +3499,8 @@ SYNTAX ISKEYWORD SETTING *:syn-iskeyword* and also determines where |:syn-keyword| will be checked for a new match. - It is recommended when writing syntax files, to use this command - to the correct value for the specific syntax language and not change + It is recommended when writing syntax files, to use this command to + set the correct value for the specific syntax language and not change the 'iskeyword' option. DEFINING KEYWORDS *:syn-keyword* @@ -3520,7 +3558,11 @@ DEFINING KEYWORDS *:syn-keyword* DEFINING MATCHES *:syn-match* -:sy[ntax] match {group-name} [{options}] [excludenl] {pattern} [{options}] +:sy[ntax] match {group-name} [{options}] + [excludenl] + [keepend] + {pattern} + [{options}] This defines one match. @@ -3529,6 +3571,9 @@ DEFINING MATCHES *:syn-match* [excludenl] Don't make a pattern with the end-of-line "$" extend a containing match or region. Must be given before the pattern. |:syn-excludenl| + keepend Don't allow contained matches to go past a + match with the end pattern. See + |:syn-keepend|. {pattern} The search pattern that defines the match. See |:syn-pattern| below. Note that the pattern may match more than one @@ -3739,7 +3784,7 @@ Whether or not it is actually concealed depends on the value of the 'conceallevel' option. The 'concealcursor' option is used to decide whether concealable items in the current line are displayed unconcealed to be able to edit the line. -Another way to conceal text with with |matchadd()|. +Another way to conceal text is with |matchadd()|. concealends *:syn-concealends* @@ -4024,6 +4069,9 @@ IMPLICIT CONCEAL *:syn-conceal-implicit* off" returns to the normal state where the "conceal" flag must be given explicitly. +:sy[ntax] conceal + Show either "syntax conceal on" or "syntax conceal off" (translated). + ============================================================================== 7. Syntax patterns *:syn-pattern* *E401* *E402* @@ -4504,12 +4552,11 @@ is mostly used, because it looks better. ============================================================================== 12. Highlight command *:highlight* *:hi* *E28* *E411* *E415* -There are three types of highlight groups: +There are two types of highlight groups: +- The built-in |highlight-groups|. - The ones used for specific languages. For these the name starts with the name of the language. Many of these don't have any attributes, but are linked to a group of the second type. -- The ones used for all syntax languages. -- The ones used for the 'highlight' option. *hitest.vim* You can see all the groups currently active with this command: > :so $VIMRUNTIME/syntax/hitest.vim @@ -4532,7 +4579,14 @@ in their own color. Doesn't work recursively, thus you can't use ":colorscheme" in a color scheme script. - After the color scheme has been loaded the + + To customize a colorscheme use another name, e.g. + "~/.vim/colors/mine.vim", and use `:runtime` to load + the original colorscheme: > + runtime colors/evening.vim + hi Statement ctermfg=Blue guifg=Blue + +< After the color scheme has been loaded the |ColorScheme| autocommand event is triggered. For info about writing a colorscheme file: > :edit $VIMRUNTIME/colors/README.txt @@ -4589,8 +4643,7 @@ 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, these have the "Co" - termcap entry) +cterm a color terminal (Windows console, color-xterm) gui the GUI For each type the highlighting can be given. This makes it possible to use @@ -4630,21 +4683,12 @@ stop={term-list} *term-list* *highlight-stop* highlighted area. This should undo the "start" argument. Otherwise the screen will look messed up. - The {term-list} can have two forms: - - 1. A string with escape sequences. - This is any string of characters, except that it can't start with - "t_" and blanks are not allowed. The <> notation is recognized - here, so you can use things like "<Esc>" and "<Space>". Example: + {term-list} is a a string with escape sequences. This is any string of + characters, except that it can't start with "t_" and blanks are not + allowed. The <> notation is recognized here, so you can use things + like "<Esc>" and "<Space>". Example: start=<Esc>[27h;<Esc>[<Space>r; - 2. A list of terminal codes. - Each terminal code has the form "t_xx", where "xx" is the name of - the termcap entry. The codes have to be separated with commas. - White space is not allowed. Example: - start=t_C1,t_BL - The terminal codes must exist for this to work. - 2. highlight arguments for color terminals @@ -4659,7 +4703,7 @@ cterm={attr-list} *highlight-cterm* ctermfg={color-nr} *highlight-ctermfg* *E421* ctermbg={color-nr} *highlight-ctermbg* The {color-nr} argument is a color number. Its range is zero to - (not including) the number given by the termcap entry "Co". + (not including) the number of |tui-colors| available. The actual color with this number depends on the type of terminal and its settings. Sometimes the color also depends on the settings of "cterm". For example, on some systems "cterm=bold ctermfg=3" gives @@ -4669,7 +4713,7 @@ ctermbg={color-nr} *highlight-ctermbg* unpredictable. See your xterm documentation for the defaults. The colors for a color-xterm can be changed from the .Xdefaults file. Unfortunately this means that it's not possible to get the same colors - for each user. See |xterm-color| for info about color xterms. + for each user. The MSDOS standard colors are fixed (in a console window), so these have been used for the names. But the meaning of color names in X11 @@ -4722,18 +4766,18 @@ ctermbg={color-nr} *highlight-ctermbg* Example: > :highlight Normal ctermfg=grey ctermbg=darkblue < When setting the "ctermbg" color for the Normal group, the - 'background' option will be adjusted automatically. This causes the - highlight groups that depend on 'background' to change! This means - you should set the colors for Normal first, before setting other - colors. + 'background' option will be adjusted automatically, under the + condition that the color is recognized and 'background' was not set + explicitly. This causes the highlight groups that depend on + 'background' to change! This means you should set the colors for + Normal first, before setting other colors. When a colorscheme is being used, changing 'background' causes it to be reloaded, which may reset all colors (including Normal). First delete the "g:colors_name" variable when you don't want this. When you have set "ctermfg" or "ctermbg" for the Normal group, Vim - needs to reset the color when exiting. This is done with the "op" - termcap entry |t_op|. If this doesn't work correctly, try setting the - 't_op' option in your vimrc. + needs to reset the color when exiting. This is done with the + "orig_pair" |terminfo| entry. *E419* *E420* When Vim knows the normal foreground and background colors, "fg" and "bg" can be used as color names. This only works after setting the @@ -4803,10 +4847,7 @@ guisp={color-name} *highlight-guisp* Black White Orange Purple Violet - In the Win32 GUI version, additional system colors are available. See - |win32-colors|. - - You can also specify a color by its Red, Green and Blue values. + You can also specify a color by its RGB (red, green, blue) values. The format is "#rrggbb", where "rr" is the Red value "gg" is the Green value @@ -4815,10 +4856,9 @@ guisp={color-name} *highlight-guisp* :highlight Comment guifg=#11f0c3 guibg=#ff00ff < *highlight-groups* *highlight-default* -These are the default highlighting groups. These groups are used by the -'highlight' option default. Note that the highlighting depends on the value -of 'background'. You can see the current settings with the ":highlight" -command. +These are the builtin highlighting groups. Note that the highlighting depends +on the value of 'background'. You can see the current settings with the +":highlight" command. *hl-ColorColumn* ColorColumn used for the columns set with 'colorcolumn' *hl-Conceal* @@ -4888,6 +4928,8 @@ NonText '@' at the end of the window, characters from 'showbreak' fit at the end of the line). See also |hl-EndOfBuffer|. *hl-Normal* Normal normal text + *hl-NormalNC* +NormalNC normal text in non-current windows *hl-Pmenu* Pmenu Popup menu: normal item. *hl-PmenuSel* @@ -4899,32 +4941,28 @@ PmenuThumb Popup menu: Thumb of the scrollbar. *hl-Question* Question |hit-enter| prompt and yes/no questions *hl-QuickFixLine* -QuickFixLine The selected |quickfix| item in the quickfix window. - |hl-CursorLine| is combined with this when the cursor is on - the currently selected quickfix item. +QuickFixLine Current |quickfix| item in the quickfix window. Combined with + |hl-CursorLine| when the cursor is there. *hl-Search* Search Last search pattern highlighting (see 'hlsearch'). - Also used for highlighting the current line in the quickfix - window and similar items that need to stand out. + Also used for similar items that need to stand out. *hl-SpecialKey* -SpecialKey Meta and special keys listed with ":map", also for text used - to show unprintable characters in the text, 'listchars'. - Generally: text that is displayed differently from what it - really is. +SpecialKey Unprintable characters: text displayed differently from what + it really is. But not 'listchars' whitespace. |hl-Whitespace| *hl-SpellBad* SpellBad Word that is not recognized by the spellchecker. |spell| - This will be combined with the highlighting used otherwise. + Combined with the highlighting used otherwise. *hl-SpellCap* SpellCap Word that should start with a capital. |spell| - This will be combined with the highlighting used otherwise. + Combined with the highlighting used otherwise. *hl-SpellLocal* SpellLocal Word that is recognized by the spellchecker as one that is used in another region. |spell| - This will be combined with the highlighting used otherwise. + Combined with the highlighting used otherwise. *hl-SpellRare* SpellRare Word that is recognized by the spellchecker as one that is hardly ever used. |spell| - This will be combined with the highlighting used otherwise. + Combined with the highlighting used otherwise. *hl-StatusLine* StatusLine status line of current window *hl-StatusLineNC* @@ -4941,8 +4979,12 @@ TabLineSel tab pages line, active tab page label Title titles for output from ":set all", ":autocmd" etc. *hl-Visual* Visual Visual mode selection + *hl-VisualNOS* +VisualNOS Visual mode selection when vim is "Not Owning the Selection". *hl-WarningMsg* WarningMsg warning messages + *hl-Whitespace* +Whitespace "nbsp", "space", "tab" and "trail" in 'listchars' *hl-WildMenu* WildMenu current match in 'wildmenu' completion @@ -5047,8 +5089,6 @@ defaults back: > It is a bit of a wrong name, since it does not reset any syntax items, it only affects the highlighting. -This doesn't change the colors for the 'highlight' option. - Note that the syntax colors that you set in your vimrc file will also be reset back to their Vim default. Note that if you are using a color scheme, the colors defined by the color @@ -5167,146 +5207,12 @@ When splitting the window, the new window will use the original syntax. ============================================================================== 17. Color xterms *xterm-color* *color-xterm* -Most color xterms have only eight colors. If you don't get colors with the -default setup, it should work with these lines in your vimrc: > - :if &term =~ "xterm" - : if has("terminfo") - : set t_Co=8 - : set t_Sf=<Esc>[3%p1%dm - : set t_Sb=<Esc>[4%p1%dm - : else - : set t_Co=8 - : set t_Sf=<Esc>[3%dm - : set t_Sb=<Esc>[4%dm - : endif - :endif -< [<Esc> is a real escape, type CTRL-V <Esc>] - -You might want to change the first "if" to match the name of your terminal, -e.g. "dtterm" instead of "xterm". - -Note: Do these settings BEFORE doing ":syntax on". Otherwise the colors may -be wrong. - *xiterm* *rxvt* -The above settings have been mentioned to work for xiterm and rxvt too. -But for using 16 colors in an rxvt these should work with terminfo: > - :set t_AB=<Esc>[%?%p1%{8}%<%t25;%p1%{40}%+%e5;%p1%{32}%+%;%dm - :set t_AF=<Esc>[%?%p1%{8}%<%t22;%p1%{30}%+%e1;%p1%{22}%+%;%dm -< *colortest.vim* To test your color setup, a file has been included in the Vim distribution. To use it, execute this command: > :runtime syntax/colortest.vim -Some versions of xterm (and other terminals, like the Linux console) can -output lighter foreground colors, even though the number of colors is defined -at 8. Therefore Vim sets the "cterm=bold" attribute for light foreground -colors, when 't_Co' is 8. - - *xfree-xterm* -To get 16 colors or more, get the newest xterm version (which should be -included with XFree86 3.3 and later). You can also find the latest version -at: > - http://invisible-island.net/xterm/xterm.html -Here is a good way to configure it. This uses 88 colors and enables the -termcap-query feature, which allows Vim to ask the xterm how many colors it -supports. > - ./configure --disable-bold-color --enable-88-color --enable-tcap-query -If you only get 8 colors, check the xterm compilation settings. -(Also see |UTF8-xterm| for using this xterm with UTF-8 character encoding). - -This xterm should work with these lines in your vimrc (for 16 colors): > - :if has("terminfo") - : set t_Co=16 - : set t_AB=<Esc>[%?%p1%{8}%<%t%p1%{40}%+%e%p1%{92}%+%;%dm - : set t_AF=<Esc>[%?%p1%{8}%<%t%p1%{30}%+%e%p1%{82}%+%;%dm - :else - : set t_Co=16 - : set t_Sf=<Esc>[3%dm - : set t_Sb=<Esc>[4%dm - :endif -< [<Esc> is a real escape, type CTRL-V <Esc>] - -Without |+terminfo|, Vim will recognize these settings, and automatically -translate cterm colors of 8 and above to "<Esc>[9%dm" and "<Esc>[10%dm". -Colors above 16 are also translated automatically. - -For 256 colors this has been reported to work: > - - :set t_AB=<Esc>[48;5;%dm - :set t_AF=<Esc>[38;5;%dm - -Or just set the TERM environment variable to "xterm-color" or "xterm-16color" -and try if that works. - -You probably want to use these X resources (in your ~/.Xdefaults file): - XTerm*color0: #000000 - XTerm*color1: #c00000 - XTerm*color2: #008000 - XTerm*color3: #808000 - XTerm*color4: #0000c0 - XTerm*color5: #c000c0 - XTerm*color6: #008080 - XTerm*color7: #c0c0c0 - XTerm*color8: #808080 - XTerm*color9: #ff6060 - XTerm*color10: #00ff00 - XTerm*color11: #ffff00 - XTerm*color12: #8080ff - XTerm*color13: #ff40ff - XTerm*color14: #00ffff - XTerm*color15: #ffffff - Xterm*cursorColor: Black - -[Note: The cursorColor is required to work around a bug, which changes the -cursor color to the color of the last drawn text. This has been fixed by a -newer version of xterm, but not everybody is using it yet.] - -To get these right away, reload the .Xdefaults file to the X Option database -Manager (you only need to do this when you just changed the .Xdefaults file): > - xrdb -merge ~/.Xdefaults -< - *xterm-blink* *xterm-blinking-cursor* -To make the cursor blink in an xterm, see tools/blink.c. Or use Thomas -Dickey's xterm above patchlevel 107 (see above for where to get it), with -these resources: - XTerm*cursorBlink: on - XTerm*cursorOnTime: 400 - XTerm*cursorOffTime: 250 - XTerm*cursorColor: White - - *hpterm-color* -These settings work (more or less) for an hpterm, which only supports 8 -foreground colors: > - :if has("terminfo") - : set t_Co=8 - : set t_Sf=<Esc>[&v%p1%dS - : set t_Sb=<Esc>[&v7S - :else - : set t_Co=8 - : set t_Sf=<Esc>[&v%dS - : set t_Sb=<Esc>[&v7S - :endif -< [<Esc> is a real escape, type CTRL-V <Esc>] - - *Eterm* *enlightened-terminal* -These settings have been reported to work for the Enlightened terminal -emulator, or Eterm. They might work for all xterm-like terminals that use the -bold attribute to get bright colors. Add an ":if" like above when needed. > - :set t_Co=16 - :set t_AF=^[[%?%p1%{8}%<%t3%p1%d%e%p1%{22}%+%d;1%;m - :set t_AB=^[[%?%p1%{8}%<%t4%p1%d%e%p1%{32}%+%d;1%;m -< - *TTpro-telnet* -These settings should work for TTpro telnet. Tera Term Pro is a freeware / -open-source program for MS-Windows. > - set t_Co=16 - set t_AB=^[[%?%p1%{8}%<%t%p1%{40}%+%e%p1%{32}%+5;%;%dm - set t_AF=^[[%?%p1%{8}%<%t%p1%{30}%+%e%p1%{22}%+1;%;%dm -Also make sure TTpro's Setup / Window / Full Color is enabled, and make sure -that Setup / Font / Enable Bold is NOT enabled. -(info provided by John Love-Jensen <eljay@Adobe.COM>) - +Nvim uses |256-color| and |true-color| terminal capabilities whereever possible. ============================================================================== 18. When syntax is slow *:syntime* diff --git a/runtime/doc/tabpage.txt b/runtime/doc/tabpage.txt index 4ab5b3c759..6be7cf9746 100644 --- a/runtime/doc/tabpage.txt +++ b/runtime/doc/tabpage.txt @@ -1,4 +1,4 @@ -*tabpage.txt* For Vim version 7.4. Last change: 2015 Apr 18 +*tabpage.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -10,11 +10,7 @@ The commands which have been added to use multiple tab pages are explained here. Additionally, there are explanations for commands that work differently when used in combination with more than one tab page. -1. Introduction |tab-page-intro| -2. Commands |tab-page-commands| -3. Other items |tab-page-other| -4. Setting 'tabline' |setting-tabline| -5. Setting 'guitablabel' |setting-guitablabel| + Type |gO| to see the table of contents. ============================================================================== 1. Introduction *tab-page-intro* @@ -54,6 +50,8 @@ right of the labels. In the GUI tab pages line you can use the right mouse button to open menu. |tabline-menu|. +For the related autocommands see |tabnew-autocmd|. + :[count]tabe[dit] *:tabe* *:tabedit* *:tabnew* :[count]tabnew Open a new tab page with an empty window, after the current @@ -129,10 +127,14 @@ something else. :tabc[lose][!] {count} Close tab page {count}. Fails in the same way as `:tabclose` above. > - :-tabclose " close the previous tab page - :+tabclose " close the next tab page - :1tabclose " close the first tab page - :$tabclose " close the last tab page + :-tabclose " close the previous tab page + :+tabclose " close the next tab page + :1tabclose " close the first tab page + :$tabclose " close the last tab page + :tabclose -2 " close the two previous tab page + :tabclose + " close the next tab page + :tabclose 3 " close the third tab page + :tabclose $ " close the last tab page < *:tabo* *:tabonly* :tabo[nly][!] Close all other tab pages. @@ -145,13 +147,20 @@ something else. never abandoned, so changes cannot get lost. > :tabonly " close all tab pages except the current one -:{count}tabo[nly][!] - Close all tab pages except the {count}th one. > - :.tabonly " as above - :-tabonly " close all tab pages except the previous one - :+tabonly " close all tab pages except the next one - :1tabonly " close all tab pages except the first one - :$tabonly " close all tab pages except the last one. +:tabo[nly][!] {count} + Close all tab pages except {count} one. > + :.tabonly " as above + :-tabonly " close all tab pages except the previous + " one + :+tabonly " close all tab pages except the next one + :1tabonly " close all tab pages except the first one + :$tabonly " close all tab pages except the last one + :tabonly - " close all tab pages except the previous + " one + :tabonly +2 " close all tab pages except the two next + " one + :tabonly 1 " close all tab pages except the first one + :tabonly $ " close all tab pages except the last one SWITCHING TO ANOTHER TAB PAGE: @@ -166,7 +175,20 @@ gt *i_CTRL-<PageDown>* *i_<C-PageDown>* Go to the next tab page. Wraps around from the last to the first one. +:{count}tabn[ext] :tabn[ext] {count} + Go to tab page {count}. The first tab page has number one. > + :-tabnext " go to the previous tab page + :+tabnext " go to the next tab page + :+2tabnext " go to the two next tab page + :1tabnext " go to the first tab page + :$tabnext " go to the last tab page + :tabnext $ " as above + :tabnext - " go to the previous tab page + :tabnext -1 " as above + :tabnext + " go to the next tab page + :tabnext +1 " as above + {count}<C-PageDown> {count}gt Go to tab page {count}. The first tab page has number one. @@ -195,6 +217,12 @@ Other commands: :tabs List the tab pages and the windows they contain. Shows a ">" for the current window. Shows a "+" for modified buffers. + For example: + Tab page 1 ~ + + tabpage.txt ~ + ex_docmd.c ~ + Tab page 2 ~ + > main.c ~ REORDERING TAB PAGES: @@ -273,6 +301,7 @@ Variables local to a tab page start with "t:". |tabpage-variable| Currently there is only one option local to a tab page: 'cmdheight'. + *tabnew-autocmd* The TabLeave and TabEnter autocommand events can be used to do something when switching from one tab page to another. The exact order depends on what you are doing. When creating a new tab page this works as if you create a new diff --git a/runtime/doc/tagsrch.txt b/runtime/doc/tagsrch.txt index 047abb42cc..f0ad2cfd43 100644 --- a/runtime/doc/tagsrch.txt +++ b/runtime/doc/tagsrch.txt @@ -1,4 +1,4 @@ -*tagsrch.txt* For Vim version 7.4. Last change: 2013 Oct 01 +*tagsrch.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -8,12 +8,7 @@ Tags and special searches *tags-and-searches* See section |29.1| of the user manual for an introduction. -1. Jump to a tag |tag-commands| -2. Tag stack |tag-stack| -3. Tag match list |tag-matchlist| -4. Tags details |tag-details| -5. Tags file format |tags-file-format| -6. Include file searches |include-search| + Type |gO| to see the table of contents. ============================================================================== 1. Jump to a tag *tag-commands* @@ -90,7 +85,7 @@ The ignore-case matches are not found for a ":tag" command when: - 'tagcase' is "followscs" and 'smartcase' option is on and the pattern contains an upper case character. -The gnore-case matches are found when: +The ignore-case matches are found when: - a pattern is used (starting with a "/") - for ":tselect" - when 'tagcase' is "followic" and 'ignorecase' is off @@ -194,6 +189,7 @@ the same entry. information in the tags file(s). When [ident] is not given, the last tag name from the tag stack is used. + See |tag-!| for [!]. With a '>' in the first column is indicated which is the current position in the list (if there is one). [ident] can be a regexp pattern, see |tag-regexp|. @@ -432,9 +428,9 @@ The next file in the list is not used when: This also depends on whether case is ignored. Case is ignored when: - 'tagcase' is "followic" and 'ignorecase' is set - 'tagcase' is "ignore" -- 'tagcase' is "smart" and and the pattern only contains lower case +- 'tagcase' is "smart" and the pattern only contains lower case characters. -- 'tagcase' is "followscs" and 'smartcase' is set and and the pattern only +- 'tagcase' is "followscs" and 'smartcase' is set and the pattern only contains lower case characters. If case is not ignored, and the tags file only has a match without matching case, the next tags file is searched for a match with matching case. If no @@ -803,24 +799,24 @@ CTRL-W d Open a new window, with the cursor on the first *:search-args* Common arguments for the commands above: -[!] When included, find matches in lines that are recognized as comments. - When excluded, a match is ignored when the line is recognized as a - comment (according to 'comments'), or the match is in a C comment (after - "//" or inside /* */). Note that a match may be missed if a line is - recognized as a comment, but the comment ends halfway through the line. - And if the line is a comment, but it is not recognized (according to - 'comments') a match may be found in it anyway. Example: > +[!] When included, find matches in lines that are recognized as comments. + When excluded, a match is ignored when the line is recognized as a + comment (according to 'comments'), or the match is in a C comment + (after "//" or inside /* */). Note that a match may be missed if a + line is recognized as a comment, but the comment ends halfway the line. + And if the line is a comment, but it is not recognized (according to + 'comments') a match may be found in it anyway. Example: > /* comment foobar */ -< A match for "foobar" is found, because this line is not recognized as a - comment (even though syntax highlighting does recognize it). - Note: Since a macro definition mostly doesn't look like a comment, the - [!] makes no difference for ":dlist", ":dsearch" and ":djump". -[/] A pattern can be surrounded by '/'. Without '/' only whole words are - matched, using the pattern "\<pattern\>". Only after the second '/' a - next command can be appended with '|'. Example: > +< A match for "foobar" is found, because this line is not recognized as + a comment (even though syntax highlighting does recognize it). + Note: Since a macro definition mostly doesn't look like a comment, the + [!] makes no difference for ":dlist", ":dsearch" and ":djump". +[/] A pattern can be surrounded by '/'. Without '/' only whole words are + matched, using the pattern "\<pattern\>". Only after the second '/' a + next command can be appended with '|'. Example: > :isearch /string/ | echo "the last one" -< For a ":djump", ":dsplit", ":dlist" and ":dsearch" command the pattern - is used as a literal string, not as a search pattern. +< For a ":djump", ":dsplit", ":dlist" and ":dsearch" command the pattern + is used as a literal string, not as a search pattern. vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/term.txt b/runtime/doc/term.txt index 137d3a06db..a694185fc9 100644 --- a/runtime/doc/term.txt +++ b/runtime/doc/term.txt @@ -1,69 +1,188 @@ -*term.txt* For Vim version 7.4. Last change: 2015 Nov 24 +*term.txt* Nvim - VIM REFERENCE MANUAL by Bram Moolenaar + NVIM REFERENCE MANUAL -Terminal information *terminal-info* +Terminal UI *tui* -Vim uses information about the terminal you are using to fill the screen and -recognize what keys you hit. If this information is not correct, the screen -may be messed up or keys may not be recognized. The actions which have to be -performed on the screen are accomplished by outputting a string of -characters. Special keys produce a string of characters. These strings are -stored in the terminal options, see |terminal-options|. +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 +screen may be messed up or keys may not be recognized. -NOTE: Most of this is not used when running the |GUI|. - -1. Startup |startup-terminal| -2. Terminal options |terminal-options| -3. Window size |window-size| -4. Slow and fast terminals |slow-fast-terminal| -5. Using the mouse |mouse-using| + Type |gO| to see the table of contents. ============================================================================== -1. Startup *startup-terminal* +Startup *startup-terminal* -When Vim is started a default terminal type is assumed. for MS-DOS this is -the pc terminal, for Unix an ansi terminal. +Nvim (except in |--headless| mode) guesses a terminal type when it starts. +|$TERM| is the primary hint that determines the terminal type. - *termcap* *terminfo* *E557* *E558* *E559* -On Unix the terminfo database or termcap file is used. This is referred to as -"termcap" in all the documentation. At compile time, when running configure, -the choice whether to use terminfo or termcap is done automatically. When -running Vim the output of ":version" will show |+terminfo| if terminfo is -used. Also see |xterm-screens|. + *terminfo* *E557* *E558* *E559* +The terminfo database is used if available. -Settings depending on terminal *term-dependent-settings* +The Unibilium library (used by Nvim to read terminfo) allows you to override +the system terminfo with one in $HOME/.terminfo/ directory, in part or in +whole. -If you want to set options or mappings, depending on the terminal name, you -can do this best in your vimrc. Example: > +Building your own terminfo is usually as simple as running this as +a non-superuser: +> + curl -LO http://invisible-island.net/datafiles/current/terminfo.src.gz + gunzip terminfo.src.gz + tic terminfo.src +< + *$TERM* +The $TERM environment variable must match the terminal you are using! +Otherwise Nvim cannot know what sequences your terminal expects, and weird +or sub-optimal behavior will result (scrolling quirks, wrong colors, etc.). + +$TERM is also important because it is mirrored by SSH to the remote session, +unlike other common client-end environment variables ($COLORTERM, +$XTERM_VERSION, $VTE_VERSION, $KONSOLE_PROFILE_NAME, $TERM_PROGRAM, ...). + + For this terminal Set $TERM to |builtin-terms| + ------------------------------------------------------------------------- + iTerm (original) iterm, iTerm.app N + iTerm2 (new capabilities) iterm2, iTerm2.app Y + anything libvte-based vte, vte-256color Y + (e.g. GNOME Terminal) (aliases: gnome, gnome-256color) + tmux tmux, tmux-256color Y + screen screen, screen-256color Y + PuTTY putty, putty-256color Y + Terminal.app nsterm N + Linux virtual terminal linux, linux-256color Y + + *builtin-terms* *builtin_terms* +If a |terminfo| database is not available, or no entry for the terminal type is +found in that database, Nvim will use a compiled-in mini-database of terminfo +entries for "xterm", "putty", "screen", "tmux", "rxvt", "iterm", "interix", +"linux", "st", "vte", "gnome", and "ansi". + +The lookup matches the initial portion of the terminal type, so (for example) +"putty-256color" and "putty" will both be mapped to the built-in "putty" +entry. The built-in terminfo entries describe the terminal as 256-colour +capable if possible. See |tui-colors|. + +If no built-in terminfo record matches the terminal type, the built-in "ansi" +terminfo record is used as a final fallback. + +The built-in mini-database is not combined with an external terminfo database, +nor can it be used in preference to one. You can thus entirely override any +omissions or out-of-date information in the built-in terminfo database by +supplying an external one with entries for the terminal type. - if &term == "xterm" - ... xterm maps and settings ... - elseif &term =~ "vt10." - ... vt100, vt102 maps and settings ... - endif +Settings depending on terminal *term-dependent-settings* + +If you want to set terminal-dependent options or mappings, you can do this in +your init.vim. Example: > + + if $TERM =~ '^\(rxvt\|screen\|interix\|putty\)\(-.*\)\?$' + set notermguicolors + elseif $TERM =~ '^\(tmux\|iterm\|vte\|gnome\)\(-.*\)\?$' + set termguicolors + elseif $TERM =~ '^\(xterm\)\(-.*\)\?$' + if $XTERM_VERSION != '' + set termguicolors + elseif $KONSOLE_PROFILE_NAME != '' + set termguicolors + elseif $VTE_VERSION != '' + set termguicolors + else + set notermguicolors + endif + elseif $TERM =~ ... + ... and so forth ... + endif < - *raw-terminal-mode* -For normal editing the terminal will be put into "raw" mode. The strings -defined with 't_ti' and 't_ks' will be sent to the terminal. Normally this -puts the terminal in a state where the termcap codes are valid and activates -the cursor and function keys. When Vim exits the terminal will be put back -into the mode it was before Vim started. The strings defined with 't_te' and -'t_ke' will be sent to the terminal. + *scroll-region* *xterm-scroll-region* +Where possible, Nvim will use the terminal's ability to set a scroll region in +order to redraw faster when a window is scrolled. If the terminal's terminfo +description describes an ability to set top and bottom scroll margins, that is +used. + +This will not speed up scrolling in a window that is not the full width of the +terminal. Xterm has an extra ability, not described by terminfo, to set left +and right scroll margins as well. If Nvim detects that the terminal is Xterm, +it will make use of this ability to speed up scrolling that is not the full +width of the terminal. + +This ability is only present in genuine Xterm, not in the many terminal +emulators that incorrectly describe themselves as xterm. Nvim's detection of +genuine Xterm will not work over an SSH connection, because the environment +variable, set by genuine Xterm, that it looks for is not automatically +replicated over an SSH login session. + + *tui-colors* +Nvim uses 256 colours by default, ignoring |terminfo| for most terminal types, +including "linux" (whose virtual terminals have had 256-colour support since +4.8) and anything claiming to be "xterm". Also when $COLORTERM or $TERM +contain the string "256". + +Nvim similarly assumes that any terminal emulator that sets $COLORTERM to any +value, is capable of at least 16-colour operation. + + *true-color* *xterm-true-color* +Nvim emits true (24-bit) colours in the terminal, if 'termguicolors' is set. + +It uses the "setrgbf" and "setrgbb" |terminfo| extensions (proposed by Rüdiger +Sonderfeld in 2013). If your terminfo definition is missing them, then Nvim +will decide whether to add them to your terminfo definition, using the ISO +8613-6:1994/ITU T.416:1993 control sequences for setting RGB colours (but +modified to use semicolons instead of colons unless the terminal is known to +follow the standard). + +Another convention, pioneered in 2016 by tmux, is the "Tc" terminfo extension. +If terminfo has this flag, Nvim will add constructed "setrgbf" and "setrgbb" +capabilities as if they had been in the terminfo definition. + +If terminfo does not (yet) have this flag, Nvim will fall back to $TERM and +other environment variables. It will add constructed "setrgbf" and "setrgbb" +capabilities in the case of the the "rxvt", "linux", "st", "tmux", and "iterm" +terminal types, or when Konsole, genuine Xterm, a libvte terminal emulator +version 0.36 or later, or a terminal emulator that sets the COLORTERM +environment variable to "truecolor" is detected. + *xterm-resize* +Nvim can resize the terminal display on some terminals that implement an +extension pioneered by dtterm. |terminfo| does not have a flag for this +extension. So Nvim simply assumes that (all) "dtterm", "xterm", "teraterm", +"rxvt" terminal types, and Konsole, are capable of this. + + *tui-cursor-shape* +Nvim will adjust the shape of the cursor from a block to a line when in insert +mode (or as specified by the 'guicursor' option), on terminals that support +it. It uses the same |terminfo| extensions that were pioneered by tmux for +this: "Ss" and "Se". + +If your terminfo definition is missing them, then Nvim will decide whether to +add them to your terminfo definition, by looking at $TERM and other +environment variables. For the "rxvt", "putty", "linux", "screen", +"teraterm", and "iterm" terminal types, or when Konsole, a libvte-based +terminal emulator, or genuine Xterm are detected, it will add constructed +"Ss" and "Se" capabilities. + +Note: Sometimes it will appear that Nvim when run within tmux is not changing +the cursor, but in fact it is tmux receiving instructions from Nvim to change +the cursor and not knowing what to do in turn. tmux has to translate what it +receives from Nvim into whatever control sequence is appropriate for the +terminal that it is outputting to. It shares a common mechanism with Nvim, of +using the "Ss" and "Se" capabilities from terminfo (for the output terminal) +if they are present. Unlike Nvim, if they are not present in terminfo you +must add them by setting "terminal-overrides" in ~/.tmux.conf . + +See the tmux(1) manual page for the details of how and what to do in the tmux +configuration file. It will look something like: > + set -ga terminal-overrides '*:Ss=\E[%p1%d q:Se=\E[ q' +<or (alas!) for Konsole specifically, something more complex like: > + set -ga terminal-overrides 'xterm*:\E]50;CursorShape=%?%p1%{3}%<%t%{0}%e%{1}%;%d\007' +< *cs7-problem* Note: If the terminal settings are changed after running Vim, you might have an illegal combination of settings. This has been reported on Solaris 2.5 with "stty cs8 parenb", which is restored as "stty cs7 parenb". Use "stty cs8 -parenb -istrip" instead, this is restored correctly. -Some termcap entries are wrong in the sense that after sending 't_ks' the -cursor keys send codes different from the codes defined in the termcap. To -avoid this you can set 't_ks' (and 't_ke') to empty strings. This must be -done during initialization (see |initialization|), otherwise it's too late. - Many cursor key codes start with an <Esc>. Vim must find out if this is a single hit of the <Esc> key or the start of a cursor key sequence. It waits for a next character to arrive. If it does not arrive within one second a @@ -92,368 +211,8 @@ them as a cursor key. When you type you normally are not that fast, so they are recognized as individual typed commands, even though Vim receives the same sequence of bytes. - *vt100-function-keys* *xterm-function-keys* -An xterm can send function keys F1 to F4 in two modes: vt100 compatible or -not. Because Vim may not know what the xterm is sending, both types of keys -are recognized. The same happens for the <Home> and <End> keys. - normal vt100 ~ - <F1> t_k1 <Esc>[11~ <xF1> <Esc>OP *<xF1>-xterm* - <F2> t_k2 <Esc>[12~ <xF2> <Esc>OQ *<xF2>-xterm* - <F3> t_k3 <Esc>[13~ <xF3> <Esc>OR *<xF3>-xterm* - <F4> t_k4 <Esc>[14~ <xF4> <Esc>OS *<xF4>-xterm* - <Home> t_kh <Esc>[7~ <xHome> <Esc>OH *<xHome>-xterm* - <End> t_@7 <Esc>[4~ <xEnd> <Esc>OF *<xEnd>-xterm* - -When Vim starts, <xF1> is mapped to <F1>, <xF2> to <F2> etc. This means that -by default both codes do the same thing. If you make a mapping for <xF2>, -because your terminal does have two keys, the default mapping is overwritten, -thus you can use the <F2> and <xF2> keys for something different. - - *xterm-shifted-keys* -Newer versions of xterm support shifted function keys and special keys. Vim -recognizes most of them. Use ":set termcap" to check which are supported and -what the codes are. Mostly these are not in a termcap, they are only -supported by the builtin_xterm termcap. - - *xterm-modifier-keys* -Newer versions of xterm support Alt and Ctrl for most function keys. To avoid -having to add all combinations of Alt, Ctrl and Shift for every key a special -sequence is recognized at the end of a termcap entry: ";*X". The "X" can be -any character, often '~' is used. The ";*" stands for an optional modifier -argument. ";2" is Shift, ";3" is Alt, ";5" is Ctrl and ";9" is Meta (when -it's different from Alt). They can be combined. Examples: > - :set <F8>=^[[19;*~ - :set <Home>=^[[1;*H -Another speciality about these codes is that they are not overwritten by -another code. That is to avoid that the codes obtained from xterm directly -|t_RV| overwrite them. - *xterm-scroll-region* -The default termcap entry for xterm on Sun and other platforms does not -contain the entry for scroll regions. Add ":cs=\E[%i%d;%dr:" to the xterm -entry in /etc/termcap and everything should work. - - *xterm-end-home-keys* -On some systems (at least on FreeBSD with XFree86 3.1.2) the codes that the -<End> and <Home> keys send contain a <Nul> character. To make these keys send -the proper key code, add these lines to your ~/.Xdefaults file: - -*VT100.Translations: #override \n\ - <Key>Home: string("0x1b") string("[7~") \n\ - <Key>End: string("0x1b") string("[8~") - - *xterm-8bit* *xterm-8-bit* -Xterm can be run in a mode where it uses 8-bit escape sequences. The CSI code -is used instead of <Esc>[. The advantage is that an <Esc> can quickly be -recognized in Insert mode, because it can't be confused with the start of a -special key. -For the builtin termcap entries, Vim checks if the 'term' option contains -"8bit" anywhere. It then uses 8-bit characters for the termcap entries, the -mouse and a few other things. You would normally set $TERM in your shell to -"xterm-8bit" and Vim picks this up and adjusts to the 8-bit setting -automatically. -When Vim receives a response to the |t_RV| (request version) sequence and it -starts with CSI, it assumes that the terminal is in 8-bit mode and will -convert all key sequences to their 8-bit variants. - ============================================================================== -2. Terminal options *terminal-options* *termcap-options* *E436* - -The terminal options can be set just like normal options. But they are not -shown with the ":set all" command. Instead use ":set termcap". - -It is always possible to change individual strings by setting the -appropriate option. For example: > - :set t_ce=^V^[[K (CTRL-V, <Esc>, [, K) - -The options are listed below. The associated termcap code is always equal to -the last two characters of the option name. Only one termcap code is -required: Cursor motion, 't_cm'. - -The options 't_da', 't_db', 't_ms', 't_xs' represent flags in the termcap. -When the termcap flag is present, the option will be set to "y". But any -non-empty string means that the flag is set. An empty string means that the -flag is not set. 't_CS' works like this too, but it isn't a termcap flag. - -OUTPUT CODES - option meaning ~ - - t_AB set background color (ANSI) *t_AB* *'t_AB'* - t_AF set foreground color (ANSI) *t_AF* *'t_AF'* - t_AL add number of blank lines *t_AL* *'t_AL'* - t_al add new blank line *t_al* *'t_al'* - t_bc backspace character *t_bc* *'t_bc'* - t_cd clear to end of screen *t_cd* *'t_cd'* - t_ce clear to end of line *t_ce* *'t_ce'* - t_cl clear screen *t_cl* *'t_cl'* - t_cm cursor motion (required!) *E437* *t_cm* *'t_cm'* - t_Co number of colors *t_Co* *'t_Co'* - t_CS if non-empty, cursor relative to scroll region *t_CS* *'t_CS'* - t_cs define scrolling region *t_cs* *'t_cs'* - t_CV define vertical scrolling region *t_CV* *'t_CV'* - t_da if non-empty, lines from above scroll down *t_da* *'t_da'* - t_db if non-empty, lines from below scroll up *t_db* *'t_db'* - t_DL delete number of lines *t_DL* *'t_DL'* - t_dl delete line *t_dl* *'t_dl'* - t_fs set window title end (from status line) *t_fs* *'t_fs'* - t_ke exit "keypad transmit" mode *t_ke* *'t_ke'* - t_ks start "keypad transmit" mode *t_ks* *'t_ks'* - t_le move cursor one char left *t_le* *'t_le'* - t_mb blinking mode *t_mb* *'t_mb'* - t_md bold mode *t_md* *'t_md'* - t_me Normal mode (undoes t_mr, t_mb, t_md and color) *t_me* *'t_me'* - t_mr reverse (invert) mode *t_mr* *'t_mr'* - *t_ms* *'t_ms'* - t_ms if non-empty, cursor can be moved in standout/inverse mode - t_nd non destructive space character *t_nd* *'t_nd'* - t_op reset to original color pair *t_op* *'t_op'* - t_RI cursor number of chars right *t_RI* *'t_RI'* - t_Sb set background color *t_Sb* *'t_Sb'* - t_Sf set foreground color *t_Sf* *'t_Sf'* - t_se standout end *t_se* *'t_se'* - t_so standout mode *t_so* *'t_so'* - t_sr scroll reverse (backward) *t_sr* *'t_sr'* - t_te out of "termcap" mode *t_te* *'t_te'* - t_ti put terminal in "termcap" mode *t_ti* *'t_ti'* - t_ts set window title start (to status line) *t_ts* *'t_ts'* - t_ue underline end *t_ue* *'t_ue'* - t_us underline mode *t_us* *'t_us'* - t_Ce undercurl end *t_Ce* *'t_Ce'* - t_Cs undercurl mode *t_Cs* *'t_Cs'* - t_ut clearing uses the current background color *t_ut* *'t_ut'* - t_vb visual bell *t_vb* *'t_vb'* - t_ve cursor visible *t_ve* *'t_ve'* - t_vi cursor invisible *t_vi* *'t_vi'* - t_vs cursor very visible *t_vs* *'t_vs'* - *t_xs* *'t_xs'* - t_xs if non-empty, standout not erased by overwriting (hpterm) - t_ZH italics mode *t_ZH* *'t_ZH'* - t_ZR italics end *t_ZR* *'t_ZR'* - -Added by Vim (there are no standard codes for these): - t_IS set icon text start *t_IS* *'t_IS'* - t_IE set icon text end *t_IE* *'t_IE'* - t_WP set window position (Y, X) in pixels *t_WP* *'t_WP'* - t_WS set window size (height, width) in characters *t_WS* *'t_WS'* - t_SI start insert mode (bar cursor shape) *t_SI* *'t_SI'* - t_EI end insert mode (block cursor shape) *t_EI* *'t_EI'* - |termcap-cursor-shape| - t_RV request terminal version string (for xterm) *t_RV* *'t_RV'* - |xterm-8bit| |v:termresponse| |xterm-codes| - t_u7 request cursor position (for xterm) *t_u7* *'t_u7'* - see |'ambiwidth'| - -KEY CODES -Note: Use the <> form if possible - - option name meaning ~ - - t_ku <Up> arrow up *t_ku* *'t_ku'* - t_kd <Down> arrow down *t_kd* *'t_kd'* - t_kr <Right> arrow right *t_kr* *'t_kr'* - t_kl <Left> arrow left *t_kl* *'t_kl'* - <xUp> alternate arrow up *<xUp>* - <xDown> alternate arrow down *<xDown>* - <xRight> alternate arrow right *<xRight>* - <xLeft> alternate arrow left *<xLeft>* - <S-Up> shift arrow up - <S-Down> shift arrow down - t_%i <S-Right> shift arrow right *t_%i* *'t_%i'* - t_#4 <S-Left> shift arrow left *t_#4* *'t_#4'* - t_k1 <F1> function key 1 *t_k1* *'t_k1'* - <xF1> alternate F1 *<xF1>* - t_k2 <F2> function key 2 *<F2>* *t_k2* *'t_k2'* - <xF2> alternate F2 *<xF2>* - t_k3 <F3> function key 3 *<F3>* *t_k3* *'t_k3'* - <xF3> alternate F3 *<xF3>* - t_k4 <F4> function key 4 *<F4>* *t_k4* *'t_k4'* - <xF4> alternate F4 *<xF4>* - t_k5 <F5> function key 5 *<F5>* *t_k5* *'t_k5'* - t_k6 <F6> function key 6 *<F6>* *t_k6* *'t_k6'* - t_k7 <F7> function key 7 *<F7>* *t_k7* *'t_k7'* - t_k8 <F8> function key 8 *<F8>* *t_k8* *'t_k8'* - t_k9 <F9> function key 9 *<F9>* *t_k9* *'t_k9'* - t_k; <F10> function key 10 *<F10>* *t_k;* *'t_k;'* - t_F1 <F11> function key 11 *<F11>* *t_F1* *'t_F1'* - t_F2 <F12> function key 12 *<F12>* *t_F2* *'t_F2'* - t_F3 <F13> function key 13 *<F13>* *t_F3* *'t_F3'* - t_F4 <F14> function key 14 *<F14>* *t_F4* *'t_F4'* - t_F5 <F15> function key 15 *<F15>* *t_F5* *'t_F5'* - t_F6 <F16> function key 16 *<F16>* *t_F6* *'t_F6'* - t_F7 <F17> function key 17 *<F17>* *t_F7* *'t_F7'* - t_F8 <F18> function key 18 *<F18>* *t_F8* *'t_F8'* - t_F9 <F19> function key 19 *<F19>* *t_F9* *'t_F9'* - <S-F1> shifted function key 1 - <S-xF1> alternate <S-F1> *<S-xF1>* - <S-F2> shifted function key 2 *<S-F2>* - <S-xF2> alternate <S-F2> *<S-xF2>* - <S-F3> shifted function key 3 *<S-F3>* - <S-xF3> alternate <S-F3> *<S-xF3>* - <S-F4> shifted function key 4 *<S-F4>* - <S-xF4> alternate <S-F4> *<S-xF4>* - <S-F5> shifted function key 5 *<S-F5>* - <S-F6> shifted function key 6 *<S-F6>* - <S-F7> shifted function key 7 *<S-F7>* - <S-F8> shifted function key 8 *<S-F8>* - <S-F9> shifted function key 9 *<S-F9>* - <S-F10> shifted function key 10 *<S-F10>* - <S-F11> shifted function key 11 *<S-F11>* - <S-F12> shifted function key 12 *<S-F12>* - t_%1 <Help> help key *t_%1* *'t_%1'* - t_&8 <Undo> undo key *t_&8* *'t_&8'* - t_kI <Insert> insert key *t_kI* *'t_kI'* - t_kD <Del> delete key *t_kD* *'t_kD'* - t_kb <BS> backspace key *t_kb* *'t_kb'* - t_kB <S-Tab> back-tab (shift-tab) *<S-Tab>* *t_kB* *'t_kB'* - t_kh <Home> home key *t_kh* *'t_kh'* - t_#2 <S-Home> shifted home key *<S-Home>* *t_#2* *'t_#2'* - <xHome> alternate home key *<xHome>* - t_@7 <End> end key *t_@7* *'t_@7'* - t_*7 <S-End> shifted end key *<S-End>* *t_star7* *'t_star7'* - <xEnd> alternate end key *<xEnd>* - t_kP <PageUp> page-up key *t_kP* *'t_kP'* - t_kN <PageDown> page-down key *t_kN* *'t_kN'* - t_K1 <kHome> keypad home key *t_K1* *'t_K1'* - t_K4 <kEnd> keypad end key *t_K4* *'t_K4'* - t_K3 <kPageUp> keypad page-up key *t_K3* *'t_K3'* - t_K5 <kPageDown> keypad page-down key *t_K5* *'t_K5'* - t_K6 <kPlus> keypad plus key *<kPlus>* *t_K6* *'t_K6'* - t_K7 <kMinus> keypad minus key *<kMinus>* *t_K7* *'t_K7'* - t_K8 <kDivide> keypad divide *<kDivide>* *t_K8* *'t_K8'* - t_K9 <kMultiply> keypad multiply *<kMultiply>* *t_K9* *'t_K9'* - t_KA <kEnter> keypad enter key *<kEnter>* *t_KA* *'t_KA'* - t_KB <kPoint> keypad decimal point *<kPoint>* *t_KB* *'t_KB'* - t_KC <k0> keypad 0 *<k0>* *t_KC* *'t_KC'* - t_KD <k1> keypad 1 *<k1>* *t_KD* *'t_KD'* - t_KE <k2> keypad 2 *<k2>* *t_KE* *'t_KE'* - t_KF <k3> keypad 3 *<k3>* *t_KF* *'t_KF'* - t_KG <k4> keypad 4 *<k4>* *t_KG* *'t_KG'* - t_KH <k5> keypad 5 *<k5>* *t_KH* *'t_KH'* - t_KI <k6> keypad 6 *<k6>* *t_KI* *'t_KI'* - t_KJ <k7> keypad 7 *<k7>* *t_KJ* *'t_KJ'* - t_KK <k8> keypad 8 *<k8>* *t_KK* *'t_KK'* - t_KL <k9> keypad 9 *<k9>* *t_KL* *'t_KL'* - <Mouse> leader of mouse code *<Mouse>* - -Note about t_so and t_mr: When the termcap entry "so" is not present the -entry for "mr" is used. And vice versa. The same is done for "se" and "me". -If your terminal supports both inversion and standout mode, you can see two -different modes. If your terminal supports only one of the modes, both will -look the same. - - *keypad-comma* -The keypad keys, when they are not mapped, behave like the equivalent normal -key. There is one exception: if you have a comma on the keypad instead of a -decimal point, Vim will use a dot anyway. Use these mappings to fix that: > - :noremap <kPoint> , - :noremap! <kPoint> , -< *xterm-codes* -There is a special trick to obtain the key codes which currently only works -for xterm. When |t_RV| is defined and a response is received which indicates -an xterm with patchlevel 141 or higher, Vim uses special escape sequences to -request the key codes directly from the xterm. The responses are used to -adjust the various t_ codes. This avoids the problem that the xterm can -produce different codes, depending on the mode it is in (8-bit, VT102, -VT220, etc.). The result is that codes like <xF1> are no longer needed. -Note: This is only done on startup. If the xterm options are changed after -Vim has started, the escape sequences may not be recognized anymore. - - *xterm-resize* -Window resizing with xterm only works if the allowWindowOps resource is -enabled. On some systems and versions of xterm it's disabled by default -because someone thought it would be a security issue. It's not clear if this -is actually the case. - -To overrule the default, put this line in your ~/.Xdefaults or -~/.Xresources: -> - XTerm*allowWindowOps: true - -And run "xrdb -merge .Xresources" to make it effective. You can check the -value with the context menu (right mouse button while CTRL key is pressed), -there should be a tick at allow-window-ops. - - *termcap-colors* -Note about colors: The 't_Co' option tells Vim the number of colors available. -When it is non-zero, the 't_AB' and 't_AF' options are used to set the color. -If one of these is not available, 't_Sb' and 't_Sf' are used. 't_me' is used -to reset to the default colors. - - *termcap-cursor-shape* *termcap-cursor-color* -When Vim enters Insert mode the 't_SI' escape sequence is sent. When leaving -Insert mode 't_EI' is used. But only if both are defined. This can be used -to change the shape or color of the cursor in Insert mode. These are not -standard termcap/terminfo entries, you need to set them yourself. -Example for an xterm, this changes the color of the cursor: > - if &term =~ "xterm" - let &t_SI = "\<Esc>]12;purple\x7" - let &t_EI = "\<Esc>]12;blue\x7" - endif -NOTE: When Vim exits the shape for Normal mode will remain. The shape from -before Vim started will not be restored. - - *termcap-title* -The 't_ts' and 't_fs' options are used to set the window title if the terminal -allows title setting via sending strings. They are sent before and after the -title string, respectively. Similar 't_IS' and 't_IE' are used to set the -icon text. These are Vim-internal extensions of the Unix termcap, so they -cannot be obtained from an external termcap. However, the builtin termcap -contains suitable entries for xterm, so you don't need to set them here. - *hpterm* -If inversion or other highlighting does not work correctly, try setting the -'t_xs' option to a non-empty string. This makes the 't_ce' code be used to -remove highlighting from a line. This is required for "hpterm". Setting the -'weirdinvert' option has the same effect as making 't_xs' non-empty, and vice -versa. - - *scroll-region* -Some termcaps do not include an entry for 'cs' (scroll region), although the -terminal does support it. For example: xterm on a Sun. You can use the -builtin_xterm or define t_cs yourself. For example: > - :set t_cs=^V^[[%i%d;%dr -Where ^V is CTRL-V and ^[ is <Esc>. - -The vertical scroll region t_CV is not a standard termcap code. Vim uses it -internally in the GUI. But it can also be defined for a terminal, if you can -find one that supports it. The two arguments are the left and right column of -the region which to restrict the scrolling to. Just like t_cs defines the top -and bottom lines. Defining t_CV will make scrolling in vertically split -windows a lot faster. Don't set t_CV when t_da or t_db is set (text isn't -cleared when scrolling). - -Unfortunately it is not possible to deduce from the termcap how cursor -positioning should be done when using a scrolling region: Relative to the -beginning of the screen or relative to the beginning of the scrolling region. -Most terminals use the first method. The 't_CS' option should be set to any -string when cursor positioning is relative to the start of the scrolling -region. It should be set to an empty string otherwise. - -Note for xterm users: The shifted cursor keys normally don't work. You can - make them work with the xmodmap command and some mappings in Vim. - - Give these commands in the xterm: - xmodmap -e "keysym Up = Up F13" - xmodmap -e "keysym Down = Down F16" - xmodmap -e "keysym Left = Left F18" - xmodmap -e "keysym Right = Right F19" - - And use these mappings in Vim: - :map <t_F3> <S-Up> - :map! <t_F3> <S-Up> - :map <t_F6> <S-Down> - :map! <t_F6> <S-Down> - :map <t_F8> <S-Left> - :map! <t_F8> <S-Left> - :map <t_F9> <S-Right> - :map! <t_F9> <S-Right> - -Instead of, say, <S-Up> you can use any other command that you want to use the -shift-cursor-up key for. (Note: To help people that have a Sun keyboard with -left side keys F14 is not used because it is confused with the undo key; F15 -is not used, because it does a window-to-front; F17 is not used, because it -closes the window. On other systems you can probably use them.) - -============================================================================== -3. Window size *window-size* +Window size *window-size* [This is about the size of the whole window Vim is using, not a window that is created with the ":split" command.] @@ -462,22 +221,15 @@ On Unix systems, three methods are tried to get the window size: - an ioctl call (TIOCGSIZE or TIOCGWINSZ, depends on your system) - the environment variables "LINES" and "COLUMNS" -- from the termcap entries "li" and "co" +- from the |terminfo| entries "lines" and "columns" If everything fails a default size of 24 lines and 80 columns is assumed. If a window-resize signal is received the size will be set again. If the window size is wrong you can use the 'lines' and 'columns' options to set the -correct values. - -One command can be used to set the screen size: - - *:mod* *:mode* -:mod[e] - -Detects the screen size and redraws the screen. +correct values. See |:mode|. ============================================================================== -4. Slow and fast terminals *slow-fast-terminal* +Slow and fast terminals *slow-fast-terminal* *slow-terminal* If you have a fast terminal you may like to set the 'ruler' option. The @@ -485,33 +237,30 @@ cursor position is shown in the status line. If you are using horizontal scrolling ('wrap' option off) consider setting 'sidescroll' to a small number. -If you have a slow terminal you may want to reset the 'showcmd' option. -The command characters will not be shown in the status line. If the terminal -scrolls very slowly, set the 'scrolljump' to 5 or so. If the cursor is moved -off the screen (e.g., with "j") Vim will scroll 5 lines at a time. Another -possibility is to reduce the number of lines that Vim uses with the command -"z{height}<CR>". +If you have a slow terminal you may want to reset the 'showcmd' and 'ruler' +options. The command characters and cursor positions will not be shown in the +status line (which involves a lot of cursor motions and attribute changes for +every keypress or movement). If the terminal scrolls very slowly, set the +'scrolljump' to 5 or so. If the cursor is moved off the screen (e.g., with +"j") Vim will scroll 5 lines at a time. Another possibility is to reduce the +number of lines that Vim uses with the command "z{height}<CR>". If the characters from the terminal are arriving with more than 1 second between them you might want to set the 'timeout' and/or 'ttimeout' option. See the "Options" chapter |options|. -If you are using a color terminal that is slow, use this command: > +If you are using a color terminal that is slow when displaying lines beyond +the end of a buffer, this is because Nvim is drawing the whitespace twice, in +two sets of colours and attributes. To prevent this, use this command: > hi NonText cterm=NONE ctermfg=NONE -This avoids that spaces are sent when they have different attributes. On most -terminals you can't see this anyway. - -If you are using Vim over a slow serial line, you might want to try running -Vim inside the "screen" program. Screen will optimize the terminal I/O quite -a bit. - -If you are testing termcap options, but you cannot see what is happening, -you might want to set the 'writedelay' option. When non-zero, one character -is sent to the terminal at a time (does not work for MS-DOS). This makes the -screen updating a lot slower, making it possible to see what is happening. +This draws the spaces with the default colours and attributes, which allows the +second pass of drawing to be optimized away. Note: Although in theory the +colours of whitespace are immaterial, in practice they change the colours of +cursors and selections that cross them. This may have a visible, but minor, +effect on some UIs. ============================================================================== -5. Using the mouse *mouse-using* +Using the mouse *mouse-using* This section is about using the mouse on a terminal or a terminal window. How to use the mouse in a GUI window is explained in |gui-mouse|. For scrolling @@ -588,17 +337,12 @@ before using the mouse: "g<RightMouse>" is "<C-RightMouse> ("CTRL-T") *bracketed-paste-mode* -Bracketed paste mode allows terminal emulators to distinguish between typed -text and pasted text. - -For terminal emulators that support it, this mode is enabled by default. Thus -you can paste text without Neovim giving any special meaning to it. Most -notably it won't try reindenting those lines. - -If your terminal emulator doesn't support it yet, you can get the old Vim -behaviour by enabling |'paste'| temporarily. +Bracketed paste mode allows terminal applications to distinguish between typed +text and pasted text. Thus you can paste text without Nvim trying to format or +indent the text. See also https://cirw.in/blog/bracketed-paste -NOTE: See https://cirw.in/blog/bracketed-paste for technical details. +Nvim enables bracketed paste by default. If it does not work in your terminal, +try the 'paste' option instead. *mouse-mode-table* *mouse-overview* A short overview of what the mouse buttons do, when 'mousemodel' is "extend": diff --git a/runtime/doc/tips.txt b/runtime/doc/tips.txt index 9d2eb3deba..011e0f0565 100644 --- a/runtime/doc/tips.txt +++ b/runtime/doc/tips.txt @@ -1,4 +1,4 @@ -*tips.txt* For Vim version 7.4. Last change: 2009 Nov 07 +*tips.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -13,22 +13,7 @@ http://www.vim.org Don't forget to browse the user manual, it also contains lots of useful tips |usr_toc.txt|. -Editing C programs |C-editing| -Finding where identifiers are used |ident-search| -Switching screens in an xterm |xterm-screens| -Scrolling in Insert mode |scroll-insert| -Smooth scrolling |scroll-smooth| -Correcting common typing mistakes |type-mistakes| -Counting words, lines, etc. |count-items| -Restoring the cursor position |restore-position| -Renaming files |rename-files| -Change a name in multiple files |change-name| -Speeding up external commands |speed-up| -Useful mappings |useful-mappings| -Compressing the help files |gzip-helpfile| -Hex editing |hex-editing| -Using <> notation in autocommands |autocmd-<>| -Highlighting matching parens |match-parens| + Type |gO| to see the table of contents. ============================================================================== Editing C programs *C-editing* @@ -119,48 +104,6 @@ archive file on your closest gnu-ftp-mirror). [the idea for this comes from Andreas Kutschera] ============================================================================== -Switching screens in an xterm *xterm-screens* *xterm-save-screen* - -(From comp.editors, by Juergen Weigert, in reply to a question) - -:> Another question is that after exiting vim, the screen is left as it -:> was, i.e. the contents of the file I was viewing (editing) was left on -:> the screen. The output from my previous like "ls" were lost, -:> ie. no longer in the scrolling buffer. I know that there is a way to -:> restore the screen after exiting vim or other vi like editors, -:> I just don't know how. Helps are appreciated. Thanks. -: -:I imagine someone else can answer this. I assume though that vim and vi do -:the same thing as each other for a given xterm setup. - -They not necessarily do the same thing, as this may be a termcap vs. -terminfo problem. You should be aware that there are two databases for -describing attributes of a particular type of terminal: termcap and -terminfo. This can cause differences when the entries differ AND when of -the programs in question one uses terminfo and the other uses termcap -(also see |+terminfo|). - -In your particular problem, you are looking for the control sequences -^[[?47h and ^[[?47l. These switch between xterms alternate and main screen -buffer. As a quick workaround a command sequence like > - echo -n "^[[?47h"; vim ... ; echo -n "^[[?47l" -may do what you want. (My notation ^[ means the ESC character, further down -you'll see that the databases use \E instead). - -On startup, vim echoes the value of the termcap variable ti (terminfo: -smcup) to the terminal. When exiting, it echoes te (terminfo: rmcup). Thus -these two variables are the correct place where the above mentioned control -sequences should go. - -Compare your xterm termcap entry (found in /etc/termcap) with your xterm -terminfo entry (retrieved with "infocmp -C xterm"). Both should contain -entries similar to: > - :te=\E[2J\E[?47l\E8:ti=\E7\E[?47h: - -PS: If you find any difference, someone (your sysadmin?) should better check - the complete termcap and terminfo database for consistency. - -============================================================================== Scrolling in Insert mode *scroll-insert* If you are in insert mode and you want to see something that is just off the @@ -170,7 +113,6 @@ screen, you can use CTRL-X CTRL-E and CTRL-X CTRL-Y to scroll the screen. To make this easier, you could use these mappings: > :inoremap <C-E> <C-X><C-E> :inoremap <C-Y> <C-X><C-Y> -(Type this literally, make sure the '<' flag is not in 'cpoptions'). You then lose the ability to copy text from the line above/below the cursor |i_CTRL-E|. @@ -186,8 +128,6 @@ If you like the scrolling to go a bit smoother, you can use these mappings: > :map <C-U> <C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y> :map <C-D> <C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E> -(Type this literally, make sure the '<' flag is not in 'cpoptions'). - ============================================================================== Correcting common typing mistakes *type-mistakes* @@ -339,9 +279,7 @@ For Emacs-style editing on the command-line: > :cnoremap <Esc><C-B> <S-Left> " forward one word :cnoremap <Esc><C-F> <S-Right> - -NOTE: This requires that the '<' flag is excluded from 'cpoptions'. |<>| - +< *format-bullet-list* This mapping will format any bullet list. It requires that there is an empty line above and below each list entry. The expression commands are used to @@ -357,8 +295,7 @@ be able to give comments to the parts of the mapping. > :execute m |" define the mapping (<> notation |<>|. Note that this is all typed literally. ^W is "^" "W", not -CTRL-W. You can copy/paste this into Vim if '<' is not included in -'cpoptions'.) +CTRL-W.) Note that the last comment starts with |", because the ":execute" command doesn't accept a comment directly. diff --git a/runtime/doc/uganda.txt b/runtime/doc/uganda.txt index c228c65542..cdd677cbd5 100644 --- a/runtime/doc/uganda.txt +++ b/runtime/doc/uganda.txt @@ -1,4 +1,4 @@ -*uganda.txt* For Vim version 7.4. Last change: 2013 Jul 06 +*uganda.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar diff --git a/runtime/doc/ui.txt b/runtime/doc/ui.txt new file mode 100644 index 0000000000..685019aed7 --- /dev/null +++ b/runtime/doc/ui.txt @@ -0,0 +1,308 @@ +*ui.txt* Nvim + + + NVIM REFERENCE MANUAL + + +Nvim UI protocol *ui* + + Type |gO| to see the table of contents. + +============================================================================== +Introduction *ui-intro* + +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, +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 +a dictionary with these (optional) keys: + `rgb` Decides the color format. + Set true (default) for 24-bit RGB colors. + Set false for terminal colors (max of 256). + *ui-ext-options* + `ext_popupmenu` Externalize the popupmenu. |ui-popupmenu| + `ext_tabline` Externalize the tabline. |ui-tabline| + `ext_cmdline` Externalize the cmdline. |ui-cmdline| + `ext_wildmenu` Externalize the wildmenu. |ui-ext-wildmenu| + +Nvim will then send msgpack-rpc notifications, with the method name "redraw" +and a single argument, an array of screen update events. +Update events are tuples whose first element is the event name and remaining +elements the event parameters. + +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. + +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|. + +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 +to be forward-compatible. |api-contract| + +============================================================================== +Global Events *ui-global* + +["set_title", title] +["set_icon", icon] + Set the window title, and icon (minimized) window title, respectively. + In windowing systems not distinguishing between the two, "set_icon" + can be ignored. + +["mode_info_set", cursor_style_enabled, mode_info] + `cursor_style_enabled` is a boolean indicating if the UI should set + the cursor style. `mode_info` is a list of mode property maps. The + current mode is given by the `mode_idx` field of the `mode_change` + event. + + Each mode property map may contain these keys: + + KEY DESCRIPTION ~ + `cursor_shape`: "block", "horizontal", "vertical" + `cell_percentage`: Cell % occupied by the cursor. + `blinkwait`, `blinkon`, `blinkoff`: See |cursor-blinking|. + `hl_id`: Cursor highlight group. + `hl_lm`: Cursor highlight group if 'langmap' is active. + `short_name`: Mode code name, see 'guicursor'. + `name`: Mode descriptive name. + `mouse_shape`: (To be implemented.) + + Some keys are missing in some modes. + +["mode_change", mode, mode_idx] + The mode changed. The first parameter `mode` is a string representing + the current mode. `mode_idx` is an index into the array received in + the `mode_info_set` event. UIs should change the cursor style + according to the properties specified in the corresponding item. The + set of modes reported will change in new versions of Nvim, for + instance more submodes and temporary states might be represented as + separate modes. + +["mouse_on"] +["mouse_off"] + Tells the client whether mouse support, as determined by |'mouse'| + option, is considered to be active in the current mode. This is mostly + useful for a terminal frontend, or other situations where nvim mouse + 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"] + 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. + +["update_menu"] + The menu mappings changed. + +["bell"] +["visual_bell"] + Notify the user with an audible or visual bell, respectively. + +============================================================================== +Grid Events *ui-grid* + +["resize", width, height] + The grid is resized to `width` and `height` cells. + +["clear"] + Clear the grid. + +["eol_clear"] + Clear from the cursor position to the end of the current line. + +["cursor_goto", row, col] + Move the cursor to position (row, col). Currently, the same cursor is + used to define the position for text insertion and the visible cursor. + However, only the last cursor position, after processing the entire + array in the "redraw" event, is intended to be a visible cursor + position. + +["update_fg", color] +["update_bg", color] +["update_sp", color] + Set the default foreground, background and special colors + respectively. + + *ui-event-highlight_set* +["highlight_set", attrs] + Set the attributes that the next text put on the grid will have. + `attrs` is a dict with the keys below. Any absent key is reset + to its default value. Color defaults are set by the `update_fg` etc + updates. All boolean keys default to false. + + `foreground`: foreground color. + `background`: backround color. + `special`: color to use for underline and undercurl, when present. + `reverse`: reverse video. Foreground and background colors are + switched. + `italic`: italic text. + `bold`: bold text. + `underline`: underlined text. The line has `special` color. + `undercurl`: undercurled text. The curl has `special` color. + +["put", text] + The (utf-8 encoded) string `text` is put at the cursor position + (and the cursor is advanced), with the highlights as set by the + last `highlight_set` update. + +["set_scroll_region", top, bot, left, right] + Define the scroll region used by `scroll` below. + +["scroll", count] + Scroll the text in the scroll region. The diagrams below illustrate + what will happen, depending on the scroll direction. "=" is used to + represent the SR(scroll region) boundaries and "-" the moved rectangles. + Note that dst and src share a common region. + + If count is bigger than 0, move a rectangle in the SR up, this can + happen while scrolling down. +> + +-------------------------+ + | (clipped above SR) | ^ + |=========================| dst_top | + | dst (still in SR) | | + +-------------------------+ src_top | + | src (moved up) and dst | | + |-------------------------| dst_bot | + | src (cleared) | | + +=========================+ src_bot +< + If count is less than zero, move a rectangle in the SR down, this can + happen while scrolling up. +> + +=========================+ src_top + | src (cleared) | | + |------------------------ | dst_top | + | src (moved down) and dst| | + +-------------------------+ src_bot | + | dst (still in SR) | | + |=========================| dst_bot | + | (clipped below SR) | v + +-------------------------+ +< +============================================================================== +Popupmenu Events *ui-popupmenu* + +Only sent if `ext_popupmenu` option is set in |ui-options| + +["popupmenu_show", items, selected, row, col] + Show |popupmenu-completion|. `items` is an array of completion items + to show; each item is an array of the form [word, kind, menu, info] as + defined at |complete-items|, except that `word` is replaced by `abbr` + if present. `selected` is the initially-selected item, a zero-based + index into the array of items (-1 if no item is selected). `row` and + `col` give the anchor position, where the first character of the + completed word will be. + +["popupmenu_select", selected] + Select an item in the current popupmenu. `selected` is a zero-based + index into the array of items from the last popupmenu_show event, or + -1 if no item is selected. + +["popupmenu_hide"] + Hide the popupmenu. + +============================================================================== +Tabline Events *ui-tabline* + +Only sent if `ext_tabline` option is set in |ui-options| + +["tabline_update", curtab, tabs] + Tabline was updated. UIs should present this data in a custom tabline + widget. + curtab: Current Tabpage + tabs: List of Dicts [{ "tab": Tabpage, "name": String }, ...] + +============================================================================== +Cmdline Events *ui-cmdline* + +Only sent if `ext_cmdline` option is set in |ui-options| + +["cmdline_show", content, pos, firstc, prompt, indent, level] + content: List of [attrs, string] + [[{}, "t"], [attrs, "est"], ...] + + Triggered when the cmdline is displayed or changed. + The `content` is the full content that should be displayed in the + cmdline, and the `pos` is the position of the cursor that in the + cmdline. The content is divided into chunks with different highlight + attributes represented as a dict (see |ui-event-highlight_set|). + + `firstc` and `prompt` are text, that if non-empty should be + displayed in front of the command line. `firstc` always indicates + built-in command lines such as `:` (ex command) and `/` `?` (search), + while `prompt` is an |input()| prompt. `indent` tells how many spaces + the content should be indented. + + The Nvim command line can be invoked recursively, for instance by + typing `<c-r>=` at the command line prompt. The `level` field is used + to distinguish different command lines active at the same time. The + first invoked command line has level 1, the next recursively-invoked + prompt has level 2. A command line invoked from the |cmd-line-window| + has a higher level than than the edited command line. + +["cmdline_pos", pos, level] + Change the cursor position in the cmdline. + +["cmdline_special_char", c, shift, level] + Display a special char in the cmdline at the cursor position. This is + typically used to indicate a pending state, e.g. after |c_CTRL-V|. If + `shift` is true the text after the cursor should be shifted, otherwise + it should overwrite the char at the cursor. + + Should be hidden at next cmdline_show. + +["cmdline_hide"] + Hide the cmdline. + +["cmdline_block_show", lines] + Show a block of context to the current command line. For example if + the user defines a |:function| interactively: > + :function Foo() + : echo "foo" + : +< + `lines` is a list of lines of highlighted chunks, in the same form as + the "cmdline_show" `contents` parameter. + +["cmdline_block_append", line] + Append a line at the end of the currently shown block. + +["cmdline_block_hide"] + Hide the block. + +============================================================================== +Wildmenu Events *ui-wildmenu* + +Only sent if `ext_wildmenu` option is set in |ui-options| + +["wildmenu_show", items] + Activate the wildmenu (command-line completion). `items` is an array + with the completion items. + +["wildmenu_select", selected] + Select an item in the current wildmenu. `selected` is a zero-based + index into the array of items from the last wildmenu_show event, or -1 + if no item is selected. + +["wildmenu_hide"] + Hide the wildmenu. + +============================================================================== + vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/undo.txt b/runtime/doc/undo.txt index c6c70ab6d2..f8f6049119 100644 --- a/runtime/doc/undo.txt +++ b/runtime/doc/undo.txt @@ -1,4 +1,4 @@ -*undo.txt* For Vim version 7.4. Last change: 2014 May 24 +*undo.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -8,12 +8,7 @@ Undo and redo *undo-redo* The basics are explained in section |02.5| of the user manual. -1. Undo and redo commands |undo-commands| -2. Two ways of undo |undo-two-ways| -3. Undo blocks |undo-blocks| -4. Undo branches |undo-branches| -5. Undo persistence |undo-persistence| -6. Remarks about undo |undo-remarks| + Type |gO| to see the table of contents. ============================================================================== 1. Undo and redo commands *undo-commands* diff --git a/runtime/doc/usr_01.txt b/runtime/doc/usr_01.txt index 2fa15331df..f3a5728d72 100644 --- a/runtime/doc/usr_01.txt +++ b/runtime/doc/usr_01.txt @@ -1,4 +1,4 @@ -*usr_01.txt* For Vim version 7.4. Last change: 2010 Nov 03 +*usr_01.txt* Nvim VIM USER MANUAL - by Bram Moolenaar diff --git a/runtime/doc/usr_02.txt b/runtime/doc/usr_02.txt index c10643940d..a1e3d606ec 100644 --- a/runtime/doc/usr_02.txt +++ b/runtime/doc/usr_02.txt @@ -1,4 +1,4 @@ -*usr_02.txt* For Vim version 7.4. Last change: 2016 Jan 16 +*usr_02.txt* Nvim VIM USER MANUAL - by Bram Moolenaar @@ -543,7 +543,7 @@ Summary: *help-summary* > 8) Ex-commands always start with ":", so to go to the :s command help: > :help :s -9) Commands specifically for debugging start with ">". To go to to the help +9) Commands specifically for debugging start with ">". To go to the help for the "cont" debug command: > :help >cont @@ -578,7 +578,7 @@ Summary: *help-summary* > register: > :help quote: -13) Vim Script (VimL) is available at > +13) Vim Script is available at > :help eval.txt < Certain aspects of the language are available at :h expr-X where "X" is a single letter. E.g. > @@ -588,10 +588,10 @@ Summary: *help-summary* > Also important is > :help function-list < to find a short description of all functions available. Help topics for - VimL functions always include the "()", so: > + Vim script functions always include the "()", so: > :help append() -< talks about the append VimL function rather than how to append text in the - current buffer. +< talks about the append Vim script function rather than how to append text + in the current buffer. 14) Mappings are talked about in the help page :h |map.txt|. Use > :help mapmode-i @@ -652,7 +652,7 @@ Summary: *help-summary* > 22) Autocommand events can be found by their name: > :help BufWinLeave < To see all possible events: > - :help autocommands-events + :help autocommand-events 23) Command-line switches always start with "-". So for the help of the -f command switch of Vim use: > diff --git a/runtime/doc/usr_03.txt b/runtime/doc/usr_03.txt index 943d7b528c..989914687f 100644 --- a/runtime/doc/usr_03.txt +++ b/runtime/doc/usr_03.txt @@ -1,4 +1,4 @@ -*usr_03.txt* For Vim version 7.4. Last change: 2016 Jan 05 +*usr_03.txt* Nvim VIM USER MANUAL - by Bram Moolenaar @@ -182,7 +182,7 @@ the following: This tells you that you might want to fix something on line 33. So how do you find line 33? One way is to do "9999k" to go to the top of the file and "32j" -to go down thirty two lines. It is not a good way, but it works. A much +to go down thirty-two lines. It is not a good way, but it works. A much better way of doing things is to use the "G" command. With a count, this command positions you at the given line number. For example, "33G" puts you on line 33. (For a better way of going through a compiler's error list, see @@ -353,7 +353,7 @@ The "?" command works like "/" but searches backwards: > ?word The "N" command repeats the last search the opposite direction. Thus using -"N" after a "/" command search backwards, using "N" after "?" searches +"N" after a "/" command searches backwards, using "N" after "?" searches forward. @@ -508,7 +508,7 @@ only if it is at the beginning of a line. The $ character matches the end of a line. Therefore, "was$" matches the word was only if it is at the end of a line. -Let's mark the places where "the" matches in this example line with "x"s: +Let's mark the places where "/the" matches in this example line with "x"s: the solder holding one of the chips melted and the ~ xxx xxx xxx diff --git a/runtime/doc/usr_04.txt b/runtime/doc/usr_04.txt index 59ba0b3e73..e02a50e494 100644 --- a/runtime/doc/usr_04.txt +++ b/runtime/doc/usr_04.txt @@ -1,4 +1,4 @@ -*usr_04.txt* For Vim version 7.4. Last change: 2014 Aug 29 +*usr_04.txt* Nvim VIM USER MANUAL - by Bram Moolenaar diff --git a/runtime/doc/usr_05.txt b/runtime/doc/usr_05.txt index f920fd4591..cb7bf94ddc 100644 --- a/runtime/doc/usr_05.txt +++ b/runtime/doc/usr_05.txt @@ -1,4 +1,4 @@ -*usr_05.txt* For Vim version 7.4. Last change: 2016 Mar 28 +*usr_05.txt* Nvim VIM USER MANUAL - by Bram Moolenaar @@ -140,15 +140,13 @@ quite complicated things. Still, it is just a sequence of commands that are executed like you typed them. > - if &t_Co > 2 || has("gui_running") - syntax on - set hlsearch - endif - -This switches on syntax highlighting, but only if colors are available. And -the 'hlsearch' option tells Vim to highlight matches with the last used search -pattern. The "if" command is very useful to set options only when some -condition is met. More about that in |usr_41.txt|. + syntax on + set hlsearch + +This switches on syntax highlighting. And the 'hlsearch' option tells Vim to +highlight matches with the last used search pattern. The "if" command is very +useful to set options only when some condition is met. More about that in +|usr_41.txt|. *vimrc-filetype* > filetype plugin indent on diff --git a/runtime/doc/usr_06.txt b/runtime/doc/usr_06.txt index b4b495ff9f..48f672be78 100644 --- a/runtime/doc/usr_06.txt +++ b/runtime/doc/usr_06.txt @@ -1,4 +1,4 @@ -*usr_06.txt* For Vim version 7.4. Last change: 2009 Oct 28 +*usr_06.txt* Nvim VIM USER MANUAL - by Bram Moolenaar @@ -55,8 +55,7 @@ There can be a number of reasons why you don't see colors: - Your terminal does not support colors. Vim will use bold, italic and underlined text, but this doesn't look very nice. You probably will want to try to get a terminal with - colors. For Unix, I recommend the xterm from the XFree86 project: - |xfree-xterm|. + colors. - Your terminal does support colors, but Vim doesn't know this. Make sure your $TERM setting is correct. For example, when using an @@ -68,9 +67,7 @@ There can be a number of reasons why you don't see colors: TERM=xterm-color; export TERM -< The terminal name must match the terminal you are using. If it - still doesn't work, have a look at |xterm-color|, which shows a few - ways to make Vim display colors (not only for an xterm). +< The terminal name must match the terminal you are using. - The file type is not recognized. Vim doesn't know all file types, and sometimes it's near to impossible diff --git a/runtime/doc/usr_07.txt b/runtime/doc/usr_07.txt index 50e4781cd7..683c9879a7 100644 --- a/runtime/doc/usr_07.txt +++ b/runtime/doc/usr_07.txt @@ -1,4 +1,4 @@ -*usr_07.txt* For Vim version 7.4. Last change: 2006 Apr 24 +*usr_07.txt* Nvim VIM USER MANUAL - by Bram Moolenaar @@ -221,7 +221,7 @@ and write the file with ":w". You edit several other files, and then use ":edit one.txt" to come back to "one.txt". If you now use `" Vim jumps to the last line of the file. Using `. takes you to the position where you deleted the character. Even when you move around in the file `" and `. will take you -to the remembered position, at least until you make another change or leave +to the remembered position. At least until you make another change or leave the file. @@ -233,8 +233,8 @@ another file and place marks there, these are specific for that file. Thus each file has its own set of marks, they are local to the file. So far we were using marks with a lowercase letter. There are also marks with an uppercase letter. These are global, they can be used from any file. -For example suppose that we are editing the file "foo.txt". Go to halfway of -the file ("50%") and place the F mark there (F for foo): > +For example suppose that we are editing the file "foo.txt". Go to halfway +down the file ("50%") and place the F mark there (F for foo): > 50%mF @@ -355,7 +355,7 @@ a sentence to the f register (f for First): > "fyas The "yas" command yanks a sentence like before. It's the "f that tells Vim -the text should be place in the f register. This must come just before the +the text should be placed in the f register. This must come just before the yank command. Now yank three whole lines to the l register (l for line): > diff --git a/runtime/doc/usr_08.txt b/runtime/doc/usr_08.txt index d1f3fbd49d..ef91bf9c0a 100644 --- a/runtime/doc/usr_08.txt +++ b/runtime/doc/usr_08.txt @@ -1,4 +1,4 @@ -*usr_08.txt* For Vim version 7.4. Last change: 2014 Jul 06 +*usr_08.txt* Nvim VIM USER MANUAL - by Bram Moolenaar @@ -45,7 +45,7 @@ top one: +----------------------------------+ What you see here is two windows on the same file. The line with "====" is -that status line. It displays information about the window above it. (In +the status line. It displays information about the window above it. (In practice the status line will be in reverse video.) The two windows allow you to view two parts of the same file. For example, you could make the top window show the variable declarations of a program, and diff --git a/runtime/doc/usr_09.txt b/runtime/doc/usr_09.txt index d68d734b8f..f53076a2ec 100644 --- a/runtime/doc/usr_09.txt +++ b/runtime/doc/usr_09.txt @@ -1,4 +1,4 @@ -*usr_09.txt* For Vim version 7.4. Last change: 2006 Apr 24 +*usr_09.txt* Nvim VIM USER MANUAL - by Bram Moolenaar @@ -21,7 +21,7 @@ Table of contents: |usr_toc.txt| ============================================================================== *09.1* Parts of the GUI -You might have an icon on your desktop that starts gVim. Otherwise, one of +You might have an icon on your desktop that starts gvim. Otherwise, one of these commands should do it: > gvim file.txt @@ -60,7 +60,7 @@ THE WINDOW TITLE At the very top is the window title. This is drawn by your window system. Vim will set the title to show the name of the current file. First comes the name of the file. Then some special characters and the directory of the file -in parens. These special character can be present: +in parens. These special characters can be present: - The file cannot be modified (e.g., a help file) + The file contains changes @@ -180,14 +180,14 @@ currently highlighted. In Vim this is the Visual area (this assumes you are using the default option settings). You can paste this selection in another application without any further action. For example, in this text select a few words with the mouse. Vim will -switch to Visual mode and highlight the text. Now start another gVim, without +switch to Visual mode and highlight the text. Now start another gvim, without a file name argument, so that it displays an empty window. Click the middle mouse button. The selected text will be inserted. The "current selection" will only remain valid until some other text is -selected. After doing the paste in the other gVim, now select some characters +selected. After doing the paste in the other gvim, now select some characters in that window. You will notice that the words that were previously selected -in the other gVim window are displayed differently. This means that it no +in the other gvim window are displayed differently. This means that it no longer is the current selection. You don't need to select text with the mouse, using the keyboard commands for @@ -200,10 +200,10 @@ Now for the other place with which text can be exchanged. We call this the "real clipboard", to avoid confusion. Often both the "current selection" and the "real clipboard" are called clipboard, you'll have to get used to that. To put text on the real clipboard, select a few different words in one of -the gVims you have running. Then use the Edit/Copy menu entry. Now the text +the gvims you have running. Then use the Edit/Copy menu entry. Now the text has been copied to the real clipboard. You can't see this, unless you have -some application that shows the clipboard contents (e.g., KDE's klipper). - Now select the other gVim, position the cursor somewhere and use the +some application that shows the clipboard contents (e.g., KDE's Klipper). + Now select the other gvim, position the cursor somewhere and use the Edit/Paste menu. You will see the text from the real clipboard is inserted. @@ -211,7 +211,7 @@ USING BOTH This use of both the "current selection" and the "real clipboard" might sound a bit confusing. But it is very useful. Let's show this with an example. -Use one gVim with a text file and perform these actions: +Use one gvim with a text file and perform these actions: - Select two words in Visual mode. - Use the Edit/Copy menu to get these words onto the clipboard. diff --git a/runtime/doc/usr_10.txt b/runtime/doc/usr_10.txt index bf7ba18222..044cb1582b 100644 --- a/runtime/doc/usr_10.txt +++ b/runtime/doc/usr_10.txt @@ -1,4 +1,4 @@ -*usr_10.txt* For Vim version 7.4. Last change: 2006 Nov 05 +*usr_10.txt* Nvim VIM USER MANUAL - by Bram Moolenaar diff --git a/runtime/doc/usr_11.txt b/runtime/doc/usr_11.txt index 1a72c300d7..42009519df 100644 --- a/runtime/doc/usr_11.txt +++ b/runtime/doc/usr_11.txt @@ -1,4 +1,4 @@ -*usr_11.txt* For Vim version 7.4. Last change: 2010 Jul 20 +*usr_11.txt* Nvim VIM USER MANUAL - by Bram Moolenaar diff --git a/runtime/doc/usr_12.txt b/runtime/doc/usr_12.txt index f64a230576..e87ed81c97 100644 --- a/runtime/doc/usr_12.txt +++ b/runtime/doc/usr_12.txt @@ -1,4 +1,4 @@ -*usr_12.txt* For Vim version 7.4. Last change: 2007 May 11 +*usr_12.txt* Nvim VIM USER MANUAL - by Bram Moolenaar @@ -278,7 +278,7 @@ command: > The line range "%" is used, thus this works on the whole file. The pattern that the ":substitute" command matches with is "\s\+$". This finds white space characters (\s), 1 or more of them (\+), before the end-of-line ($). -Later will be explained how you write patterns like this |usr_27.txt|. +Later will be explained how you write patterns like this, see |usr_27.txt|. The "to" part of the substitute command is empty: "//". Thus it replaces with nothing, effectively deleting the matched white space. diff --git a/runtime/doc/usr_20.txt b/runtime/doc/usr_20.txt index 5f0a660187..3b8eeae175 100644 --- a/runtime/doc/usr_20.txt +++ b/runtime/doc/usr_20.txt @@ -1,4 +1,4 @@ -*usr_20.txt* For Vim version 7.4. Last change: 2006 Apr 24 +*usr_20.txt* Nvim VIM USER MANUAL - by Bram Moolenaar diff --git a/runtime/doc/usr_21.txt b/runtime/doc/usr_21.txt index f99c3263d0..cfb8c90027 100644 --- a/runtime/doc/usr_21.txt +++ b/runtime/doc/usr_21.txt @@ -1,4 +1,4 @@ -*usr_21.txt* For Vim version 7.4. Last change: 2012 Nov 02 +*usr_21.txt* Nvim VIM USER MANUAL - by Bram Moolenaar diff --git a/runtime/doc/usr_22.txt b/runtime/doc/usr_22.txt index cff8e9db1e..255211f668 100644 --- a/runtime/doc/usr_22.txt +++ b/runtime/doc/usr_22.txt @@ -1,4 +1,4 @@ -*usr_22.txt* For Vim version 7.4. Last change: 2012 Nov 15 +*usr_22.txt* Nvim VIM USER MANUAL - by Bram Moolenaar @@ -93,7 +93,7 @@ browser. This is what you get: > o................Browsing with a Horizontal Split...........|netrw-o| p................Use Preview Window.........................|netrw-p| P................Edit in Previous Window....................|netrw-p| - q................Listing Bookmarks and History..............|netrw-q| + q................Listing Bookmarks and History..............|netrw-qb| r................Reversing Sorting Order....................|netrw-r| < (etc) diff --git a/runtime/doc/usr_23.txt b/runtime/doc/usr_23.txt index 4761203512..cb776d2b5c 100644 --- a/runtime/doc/usr_23.txt +++ b/runtime/doc/usr_23.txt @@ -1,4 +1,4 @@ -*usr_23.txt* For Vim version 7.4. Last change: 2006 Apr 24 +*usr_23.txt* Nvim VIM USER MANUAL - by Bram Moolenaar diff --git a/runtime/doc/usr_24.txt b/runtime/doc/usr_24.txt index ba9d083fe0..b74ed879e0 100644 --- a/runtime/doc/usr_24.txt +++ b/runtime/doc/usr_24.txt @@ -1,4 +1,4 @@ -*usr_24.txt* For Vim version 7.4. Last change: 2006 Jul 23 +*usr_24.txt* Nvim VIM USER MANUAL - by Bram Moolenaar diff --git a/runtime/doc/usr_25.txt b/runtime/doc/usr_25.txt index 24420353dd..ae3d3c4422 100644 --- a/runtime/doc/usr_25.txt +++ b/runtime/doc/usr_25.txt @@ -1,4 +1,4 @@ -*usr_25.txt* For Vim version 7.4. Last change: 2016 Mar 28 +*usr_25.txt* Nvim VIM USER MANUAL - by Bram Moolenaar diff --git a/runtime/doc/usr_26.txt b/runtime/doc/usr_26.txt index e381a1df12..7b0b940da2 100644 --- a/runtime/doc/usr_26.txt +++ b/runtime/doc/usr_26.txt @@ -1,4 +1,4 @@ -*usr_26.txt* For Vim version 7.4. Last change: 2006 Apr 24 +*usr_26.txt* Nvim VIM USER MANUAL - by Bram Moolenaar diff --git a/runtime/doc/usr_27.txt b/runtime/doc/usr_27.txt index d837610698..afea67bd0b 100644 --- a/runtime/doc/usr_27.txt +++ b/runtime/doc/usr_27.txt @@ -1,4 +1,4 @@ -*usr_27.txt* For Vim version 7.4. Last change: 2010 Mar 28 +*usr_27.txt* Nvim VIM USER MANUAL - by Bram Moolenaar diff --git a/runtime/doc/usr_28.txt b/runtime/doc/usr_28.txt index d29b384437..24e995d9ab 100644 --- a/runtime/doc/usr_28.txt +++ b/runtime/doc/usr_28.txt @@ -1,4 +1,4 @@ -*usr_28.txt* For Vim version 7.4. Last change: 2008 Jun 14 +*usr_28.txt* Nvim VIM USER MANUAL - by Bram Moolenaar diff --git a/runtime/doc/usr_29.txt b/runtime/doc/usr_29.txt index 9eb66ce83c..b0cb9d7e88 100644 --- a/runtime/doc/usr_29.txt +++ b/runtime/doc/usr_29.txt @@ -1,4 +1,4 @@ -*usr_29.txt* For Vim version 7.4. Last change: 2016 Feb 27 +*usr_29.txt* Nvim VIM USER MANUAL - by Bram Moolenaar diff --git a/runtime/doc/usr_30.txt b/runtime/doc/usr_30.txt index dbac440ecc..786f2d1800 100644 --- a/runtime/doc/usr_30.txt +++ b/runtime/doc/usr_30.txt @@ -1,4 +1,4 @@ -*usr_30.txt* For Vim version 7.4. Last change: 2007 Nov 10 +*usr_30.txt* Nvim VIM USER MANUAL - by Bram Moolenaar diff --git a/runtime/doc/usr_31.txt b/runtime/doc/usr_31.txt index 7bcf4d428a..2354e27b42 100644 --- a/runtime/doc/usr_31.txt +++ b/runtime/doc/usr_31.txt @@ -1,4 +1,4 @@ -*usr_31.txt* For Vim version 7.4. Last change: 2007 May 08 +*usr_31.txt* Nvim VIM USER MANUAL - by Bram Moolenaar diff --git a/runtime/doc/usr_32.txt b/runtime/doc/usr_32.txt index fd58f2d517..fca802872d 100644 --- a/runtime/doc/usr_32.txt +++ b/runtime/doc/usr_32.txt @@ -1,4 +1,4 @@ -*usr_32.txt* For Vim version 7.4. Last change: 2010 Jul 20 +*usr_32.txt* Nvim VIM USER MANUAL - by Bram Moolenaar diff --git a/runtime/doc/usr_40.txt b/runtime/doc/usr_40.txt index d3cc792c59..4092af703e 100644 --- a/runtime/doc/usr_40.txt +++ b/runtime/doc/usr_40.txt @@ -1,4 +1,4 @@ -*usr_40.txt* For Vim version 7.4. Last change: 2013 Aug 05 +*usr_40.txt* Nvim VIM USER MANUAL - by Bram Moolenaar diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt index 191b0871f4..51d8143440 100644 --- a/runtime/doc/usr_41.txt +++ b/runtime/doc/usr_41.txt @@ -1,4 +1,4 @@ -*usr_41.txt* For Vim version 7.4. Last change: 2016 Aug 07 +*usr_41.txt* Nvim VIM USER MANUAL - by Bram Moolenaar @@ -95,7 +95,7 @@ Then there is the ":let i += 1" command. This does the same thing as to the same variable. The example was given to explain the commands, but would you really want to -make such a loop it can be written much more compact: > +make such a loop, it can be written much more compact: > :for i in range(1, 4) : echo "count is" i @@ -692,6 +692,7 @@ Other computation: *bitwise-function* Variables: *var-functions* type() type of a variable islocked() check if a variable is locked + funcref() get a Funcref for a function reference function() get a Funcref for a function name getbufvar() get a variable value from a specific buffer setbufvar() set a variable in a specific buffer @@ -883,9 +884,11 @@ GUI: *gui-functions* getfontname() get name of current font being used getwinposx() X position of the GUI Vim window getwinposy() Y position of the GUI Vim window + balloon_show() set the balloon content Vim server: *server-functions* serverlist() return the list of server names + remote_startserver() run a server remote_send() send command characters to a Vim server remote_expr() evaluate an expression in a Vim server server2client() send a reply to a client of a Vim server @@ -950,8 +953,10 @@ Various: *various-functions* taglist() get list of matching tags tagfiles() get a list of tags files + luaeval() evaluate Lua expression py3eval() evaluate Python expression (|+python3|) pyeval() evaluate Python expression (|+python|) + pyxeval() evaluate |python_x| expression ============================================================================== *41.7* Defining a function @@ -1539,7 +1544,7 @@ WHITE SPACE Blank lines are allowed and ignored. Leading whitespace characters (blanks and TABs) are always ignored. The -whitespaces between parameters (e.g. between the 'set' and the 'cpoptions' in +whitespaces between parameters (e.g. between the "set" and the "cpoptions" in the example below) are reduced to one blank character and plays the role of a separator, the whitespaces after the last (visible) character may or may not be ignored depending on the situation, see below. @@ -2222,8 +2227,8 @@ plugin for the mail filetype: > endif Two global variables are used: -no_plugin_maps disables mappings for all filetype plugins -no_mail_maps disables mappings for a specific filetype +|no_plugin_maps| disables mappings for all filetype plugins +|no_mail_maps| disables mappings for the "mail" filetype USER COMMANDS diff --git a/runtime/doc/usr_42.txt b/runtime/doc/usr_42.txt index c8eac5f062..ad04555f8c 100644 --- a/runtime/doc/usr_42.txt +++ b/runtime/doc/usr_42.txt @@ -1,4 +1,4 @@ -*usr_42.txt* For Vim version 7.4. Last change: 2008 May 05 +*usr_42.txt* Nvim VIM USER MANUAL - by Bram Moolenaar diff --git a/runtime/doc/usr_43.txt b/runtime/doc/usr_43.txt index bab446af3c..765a525692 100644 --- a/runtime/doc/usr_43.txt +++ b/runtime/doc/usr_43.txt @@ -1,4 +1,4 @@ -*usr_43.txt* For Vim version 7.4. Last change: 2015 Oct 23 +*usr_43.txt* Nvim VIM USER MANUAL - by Bram Moolenaar diff --git a/runtime/doc/usr_44.txt b/runtime/doc/usr_44.txt index a91f92ff4e..b06557b950 100644 --- a/runtime/doc/usr_44.txt +++ b/runtime/doc/usr_44.txt @@ -1,4 +1,4 @@ -*usr_44.txt* For Vim version 7.4. Last change: 2008 Dec 28 +*usr_44.txt* Nvim VIM USER MANUAL - by Bram Moolenaar @@ -686,7 +686,7 @@ that included files do this too, you might have to reset "b:current_syntax" if you include two files. If you want your syntax file to work with Vim 5.x, add a check for v:version. -See yacc.vim for an example. +Find an syntax file in the Vim 7.2 distribution for an example. Do not include anything that is a user preference. Don't set 'tabstop', 'expandtab', etc. These belong in a filetype plugin. diff --git a/runtime/doc/usr_45.txt b/runtime/doc/usr_45.txt index 34b607cbd2..9bbbe82113 100644 --- a/runtime/doc/usr_45.txt +++ b/runtime/doc/usr_45.txt @@ -1,4 +1,4 @@ -*usr_45.txt* For Vim version 7.4. Last change: 2008 Nov 15 +*usr_45.txt* Nvim VIM USER MANUAL - by Bram Moolenaar diff --git a/runtime/doc/usr_toc.txt b/runtime/doc/usr_toc.txt index e021b806e3..ed14d78d22 100644 --- a/runtime/doc/usr_toc.txt +++ b/runtime/doc/usr_toc.txt @@ -1,4 +1,4 @@ -*usr_toc.txt* For Vim version 7.4. Last change: 2016 Mar 25 +*usr_toc.txt* Nvim VIM USER MANUAL - by Bram Moolenaar @@ -48,9 +48,8 @@ Tuning Vim Reference manual |reference_toc| More detailed information for all commands -The user manual is available as a single, ready to print HTML and PDF file -here: - http://vimdoc.sf.net +The user manual is online: + https://neovim.io/doc/user ============================================================================== Getting Started ~ diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt index 0ac294ec37..baac72c106 100644 --- a/runtime/doc/various.txt +++ b/runtime/doc/various.txt @@ -1,4 +1,4 @@ -*various.txt* For Vim version 7.4. Last change: 2016 Jul 09 +*various.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -6,8 +6,7 @@ Various commands *various* -1. Various commands |various-cmds| -2. Using Vim like less or more |less| + Type |gO| to see the table of contents. ============================================================================== 1. Various commands *various-cmds* @@ -85,6 +84,8 @@ g8 Print the hex values of the bytes used in the on paper see |:hardcopy|. In the GUI you can use the File.Print menu entry. See |ex-flags| for [flags]. + The |:filter| command can be used to only show lines + matching a pattern. :[range]p[rint] {count} [flags] Print {count} lines, starting with [range] (default @@ -101,8 +102,7 @@ g8 Print the hex values of the bytes used in the *:nu* *:number* :[range]nu[mber] [count] [flags] Same as :print, but precede each line with its line - number. (See also 'highlight' and 'numberwidth' - option). + number. (See also |hl-LineNr| and 'numberwidth'). See |ex-flags| for [flags]. *:#* @@ -207,15 +207,19 @@ g8 Print the hex values of the bytes used in the :sh[ell] Removed. |vim-differences| {Nvim} *:terminal* *:te* -:te[rminal][!] {cmd} Execute {cmd} with 'shell' in a |terminal-emulator| - buffer. Equivalent to: > +:te[rminal][!] [{cmd}] Execute {cmd} with 'shell' in a new |terminal| buffer. + Equivalent to: > :enew :call termopen('{cmd}') - :startinsert < - See |jobstart()|. + See |termopen()|. - To enter terminal mode automatically: > + Without {cmd}, start an interactive shell. + + Creating the terminal buffer fails when changes have been + made to the current buffer, unless 'hidden' is set. + + To enter |Terminal-mode| automatically: > autocmd BufEnter term://* startinsert autocmd BufLeave term://* stopinsert < @@ -270,6 +274,21 @@ g8 Print the hex values of the bytes used in the < The screen is not redrawn then, thus you have to use CTRL-L or ":redraw!" if the command did display something. + *:!start* +:!start {cmd} (Windows only). Special-case of |:!| which works + asynchronously, for running a program that does not + affect the files you are editing. + Optional arguments (can only use one at a time): + /min window will be minimized + /b no console window will be opened + Note: If the process requires input, /b will get an + EOF error because its input stream (stdin) would be + redirected to \\.\NUL (stdout and stderr too). + + Programs begun with :!start do not get passed Vim's + open file handles, which means they do not have to be + closed before Vim. To avoid this special treatment, + use ":! start". *:!!* :!! Repeat last ":!{cmd}". @@ -305,13 +324,12 @@ N *+cindent* |'cindent'|, C indenting N *+clientserver* Unix and Win32: Remote invocation |clientserver| *+clipboard* |clipboard| support N *+cmdline_compl* command line completion |cmdline-completion| -N *+cmdline_hist* command line history |cmdline-history| +S *+cmdline_hist* command line history |cmdline-history| N *+cmdline_info* |'showcmd'| and |'ruler'| N *+comments* |'comments'| support B *+conceal* "conceal" support, see |conceal| |:syn-conceal| etc. B *+cscope* |cscope| support m *+cursorbind* |'cursorbind'| support -m *+cursorshape* |termcap-cursor-shape| support m *+debug* Compiled for debugging. N *+dialog_gui* Support for |:confirm| with GUI dialog. N *+dialog_con* Support for |:confirm| with console dialog. @@ -329,8 +347,9 @@ N *+gettext* message translations |multi-lang| *+iconv* Compiled with the |iconv()| function *+iconv/dyn* Likewise |iconv-dynamic| |/dyn| N *+insert_expand* |insert_expand| Insert mode completion -N *+jumplist* |jumplist| +S *+jumplist* |jumplist| B *+keymap* |'keymap'| +N *+lambda* |lambda| and |closure| B *+langmap* |'langmap'| N *+libcall* |libcall()| N *+linebreak* |'linebreak'|, |'breakat'| and |'showbreak'| @@ -346,6 +365,7 @@ N *+mouseshape* |'mouseshape'| N *+multi_byte* 16 and 32 bit characters |multibyte| *+multi_byte_ime* Win32 input method for multibyte chars |multibyte-ime| N *+multi_lang* non-English language support |multi-lang| + *+num64* 64-bit Number support |Number| N *+path_extra* Up/downwards search in 'path' and 'tags' N *+persistent_undo* Persistent undo |undo-persistence| *+postscript* |:hardcopy| writes a PostScript file @@ -366,26 +386,24 @@ N *+statusline* Options 'statusline', 'rulerformat' and special formats of 'titlestring' and 'iconstring' N *+syntax* Syntax highlighting |syntax| N *+tablineat* 'tabline' option recognizing %@Func@ items. -N *+tag_binary* binary searching in tags file |tag-binary-search| +T *+tag_binary* binary searching in tags file |tag-binary-search| N *+tag_old_static* old method for static tags |tag-old-static| m *+tag_any_white* any white space allowed in tags file |tag-any-white| B *+termguicolors* 24-bit color in xterm-compatible terminals support - *+terminfo* uses |terminfo| instead of termcap N *+termresponse* support for |t_RV| and |v:termresponse| N *+textobjects* |text-objects| selection - *+tgetent* non-Unix only: able to use external termcap N *+timers* the |timer_start()| function N *+title* Setting the window 'title' and 'icon' N *+toolbar* |gui-toolbar| N *+user_commands* User-defined commands. |user-commands| -N *+vertsplit* Vertically split windows |:vsplit| + *+vertsplit* Vertically split windows |:vsplit| N *+virtualedit* |'virtualedit'| S *+visual* Visual mode |Visual-mode| Always enabled since 7.4.200. N *+visualextra* extra Visual mode commands |blockwise-operators| N *+vreplace* |gR| and |gr| N *+wildignore* |'wildignore'| N *+wildmenu* |'wildmenu'| -S *+windows* more than one window + *+windows* more than one window m *+writebackup* |'writebackup'| is default on m *+xim* X input method |xim| *+xfontset* X fontset support |xfontset| @@ -460,6 +478,29 @@ m *+xpm_w32* Win32 GUI only: pixmap support |w32-xpm-support| :redi[r] END End redirecting messages. + *:filt* *:filter* +:filt[er][!] {pat} {command} +:filt[er][!] /{pat}/ {command} + Restrict the output of {command} to lines matching + with {pat}. For example, to list only xml files: > + :filter /\.xml$/ oldfiles +< If the [!] is given, restrict the output of {command} + to lines that do NOT match {pat}. + + {pat} is a Vim search pattern. Instead of enclosing + it in / any non-ID character (see |'isident'|) can be + used, so long as it does not appear in {pat}. Without + the enclosing character the pattern cannot include the + bar character. + + The pattern is matched against the relevant part of + the output, not necessarily the whole line. Only some + commands support filtering, try it out to check if it + works. + + Only normal messages are filtered, error messages are + not. + *:sil* *:silent* *:silent!* :sil[ent][!] {command} Execute {command} silently. Normal messages will not be given or added to the message history. @@ -566,6 +607,13 @@ which it was defined is reported. the keyword. Only works when the highlighted text is not more than one line. + *gO* +gO Show a filetype-specific, navigable "outline" of the + current buffer. For example, in a |help| buffer this + shows the table of contents. + + Currently works in |help| and |:Man| buffers. + [N]gs *gs* *:sl* *:sleep* :[N]sl[eep] [N] [m] Do nothing for [N] seconds. When [m] is included, sleep for [N] milliseconds. The count for "gs" always @@ -604,4 +652,4 @@ LessInitFunc in your vimrc, for example: > endfunc < - vim:tw=78:ts=8:ft=help:norl: + vim:noet:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/vi_diff.txt b/runtime/doc/vi_diff.txt index 54ef8fecb2..917e0e6f80 100644 --- a/runtime/doc/vi_diff.txt +++ b/runtime/doc/vi_diff.txt @@ -1,4 +1,4 @@ -*vi_diff.txt* For Vim version 7.4. Last change: 2016 Feb 12 +*vi_diff.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -6,8 +6,7 @@ Differences between Vim and Vi *vi-differences* -1. Limits |limits| -2. The most interesting additions |vim-additions| + Type |gO| to see the table of contents. ============================================================================== 1. Limits *limits* @@ -60,7 +59,7 @@ Support for different systems. - Windows (XP SP 2 or greater) - OS X -Multi level undo. |undo| +Multi level persistent undo. |undo| 'u' goes backward in time, 'CTRL-R' goes forward again. Set option 'undolevels' to the number of changes to be remembered (default 1000). Set 'undolevels' to 0 for a Vi-compatible one level undo. Set it to @@ -71,6 +70,9 @@ Multi level undo. |undo| create a branch in the undo tree. This means you can go back to any state of the text, there is no risk of a change causing text to be lost forever. |undo-tree| + The undo information is stored in a file when the 'undofile' option is + set. This means you can exit Vim, start Vim on a previously edited + file and undo changes that were made before exiting Vim. Graphical User Interface (GUI). |gui| Included support for GUI: menu's, mouse, scrollbars, etc. You can @@ -124,6 +126,13 @@ Plugins. |add-plugin| right directory. That's an easy way to start using Vim scripts written by others. Plugins can be for all kind of files, or specifically for a filetype. + Packages make this even easier. |packages| + +Asynchronous communication and timers. |job-control| |timer| + Vim can exchange messages with other processes in the background. + Vim can start a job, communicate with it and stop it. |job-control| + Timers can fire once or repeatedly and invoke a function to do any + work. |timer| Repeat a series of commands. |q| "q{c}" starts recording typed characters into named register {c}. diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt index d7d31b5853..c8155f7a68 100644 --- a/runtime/doc/vim_diff.txt +++ b/runtime/doc/vim_diff.txt @@ -1,4 +1,4 @@ -*vim_diff.txt* For Nvim. {Nvim} +*vim_diff.txt* Nvim NVIM REFERENCE MANUAL @@ -6,17 +6,10 @@ Differences between Nvim and Vim *vim-differences* -Throughout the help files, differences between Nvim and Vim are indicated via -the "{Nvim}" tag. This document is a complete and centralized list of all -these differences. - -1. Configuration |nvim-configuration| -2. Defaults |nvim-defaults| -3. New features |nvim-features| -4. Changed features |nvim-features-changed| -5. Missing legacy features |nvim-features-missing| -6. Removed features |nvim-features-removed| +Nvim differs from Vim in many ways, big and small. This document is +a complete and centralized reference of those differences. + Type |gO| to see the table of contents. ============================================================================== 1. Configuration *nvim-configuration* @@ -45,7 +38,8 @@ these differences. - 'history' defaults to 10000 (the maximum) - 'hlsearch' is set by default - 'incsearch' is set by default -- 'langnoremap' is set by default +- 'langnoremap' is enabled by default +- 'langremap' is disabled by default - 'laststatus' defaults to 2 (statusline is always shown) - 'listchars' defaults to "tab:> ,trail:-,nbsp:+" - 'nocompatible' is always set @@ -64,42 +58,62 @@ these differences. ============================================================================== 3. New Features *nvim-features* - MAJOR COMPONENTS ~ -Embedded terminal emulator |terminal-emulator| -RPC API |RPC| -Shared data |shada| -XDG base directories |xdg| +API |API| +Lua scripting |lua| Job control |job-control| Remote plugins |remote-plugin| -Python plugins |provider-python| -Clipboard integration |provider-clipboard| - +Providers + Clipboard |provider-clipboard| + Python plugins |provider-python| + Ruby plugins |provider-ruby| +Shared data |shada| +Embedded terminal |terminal| +XDG base directories |xdg| USER EXPERIENCE ~ -Working intuitively and consistently is a major goal of Nvim. Examples: +Working intuitively and consistently is a major goal of Nvim. -- Nvim does not have `-X`, a platform-specific option "sometimes" available in - Vim (with potential surprises: http://stackoverflow.com/q/14635295). Nvim - avoids features that cannot be provided on all platforms--instead that is - delegated to external plugins/extensions. + *feature-compile* +- Nvim always includes ALL features, in contrast to Vim (which ships with + various combinations of 100+ optional features). Think of it as a leaner + version of Vim's "HUGE" build. This reduces surface area for bugs, and + removes a common source of confusion and friction for users. -- Test-only globals and functions such as test_autochdir(), test_settime(), - etc., are not exposed (because they don't exist). +- Nvim avoids features that cannot be provided on all platforms; instead that + is delegated to external plugins/extensions. E.g. the `-X` platform-specific + option is "sometimes" available in Vim (with potential surprises: + http://stackoverflow.com/q/14635295). + +- Vim's internal test functions (test_autochdir(), test_settime(), etc.) are + not exposed (nor implemented); instead Nvim has a robust API. + +- Behaviors, options, documentation are removed if they cost users more time + than they save. + +Usability details have been improved where the benefit outweighs any +backwards-compatibility cost. Some examples: + +- |K| in help documents can be used like |CTRL-]|. +- Directories for 'directory' and 'undodir' are auto-created. +- Terminal features such as 'guicursor' are enabled where possible. ARCHITECTURE ~ External plugins run in separate processes. |remote-plugin| This improves -stability and allows those plugins to perform tasks without blocking the -editor. Even "legacy" Python and Ruby plugins which use the old Vim interfaces -(|if_py| and |if_ruby|) run out-of-process. +stability and allows those plugins to work without blocking the editor. Even +"legacy" Python and Ruby plugins which use the old Vim interfaces (|if_py| and +|if_ruby|) run out-of-process. +Platform and I/O facilities are built upon libuv. Nvim benefits from libuv +features and bug fixes, and other projects benefit from improvements to libuv +by Nvim developers. FEATURES ~ -|bracketed-paste-mode| is built-in and enabled by default. +"Outline": Type |gO| in |:Man| and |:help| pages to see a document outline. |META| (ALT) chords are recognized, even in the terminal. Any |<M-| mapping will work. Some examples: <M-1>, <M-2>, <M-BS>, <M-Del>, <M-Ins>, <M-/>, @@ -112,9 +126,12 @@ Some `CTRL-SHIFT-...` key chords are distinguished from `CTRL-...` variants Options: 'cpoptions' flags: |cpo-_| + 'guicursor' works in the terminal 'inccommand' shows interactive results for |:substitute|-like commands + 'scrollback' 'statusline' supports unlimited alignment sections 'tabline' %@Func@foo%X can call any function on mouse-click + 'winhighlight' window-local highlights Variables: |v:event| @@ -123,14 +140,15 @@ Variables: |v:windowid| is always available (for use by external UIs) Commands: - |:CheckHealth| + |:checkhealth| |:drop| is available on all platforms |:Man| is available by default, with many improvements such as completion + |:tchdir| tab-local |current-directory| Functions: |dictwatcheradd()| notifies a callback whenever a |Dict| is modified |dictwatcherdel()| - |execute()| works with |:redir| + |menu_get()| |msgpackdump()|, |msgpackparse()| provide msgpack de/serialization Events: @@ -141,10 +159,20 @@ Events: |TextYankPost| Highlight groups: + |hl-NormalNC| highlights non-current windows |hl-QuickFixLine| |hl-Substitute| |hl-TermCursor| |hl-TermCursorNC| + |hl-Whitespace| highlights 'listchars' whitespace + +UI: + *E5408* *E5409* *g:Nvim_color_expr* *g:Nvim_color_cmdline* + Command-line coloring is supported. Only |input()| and |inputdialog()| may + be colored. For testing purposes expressions (e.g. |i_CTRL-R_=|) and regular + command-line (|:|) are colored by callbacks defined in `g:Nvim_color_expr` + and `g:Nvim_color_cmdline` respectively (these callbacks are for testing + only, and will be removed in a future version). ============================================================================== 4. Changed features *nvim-features-changed* @@ -159,11 +187,22 @@ are always available and may be used simultaneously in separate plugins. The `neovim` pip package must be installed to use Python plugins in Nvim (see |provider-python|). +Because of general |256-color| usage whereever possible, Nvim will even use +256-colour capability on Linux virtual terminals. Vim uses only 8 colours +plus bright foreground on Linux VTs. + +Vim combines what is in its |builtin-terms| with what it reads from termcap, +and has a |ttybuiltin| setting to control how that combination works. Nvim +uses either one or the other of an external |terminfo| entry or the built-in +one. It does not attempt to mix data from the two. + |:!| does not support "interactive" commands. Use |:terminal| instead. (GUI Vim has a similar limitation, see ":help gui-pty" in Vim.) |system()| does not support writing/reading "backgrounded" commands. |E5677| +|:redir| nested in |execute()| works. + Nvim may throttle (skip) messages from shell commands (|:!|, |:grep|, |:make|) if there is too much output. No data is lost, this only affects display and makes things faster. |:terminal| output is never throttled. @@ -219,22 +258,15 @@ Additional differences: - |shada-c| has no effect. - |shada-s| now limits size of every item and not just registers. -- When reading ShaDa files items are merged according to the timestamp. - |shada-merging| - 'viminfo' option got renamed to 'shada'. Old option is kept as an alias for compatibility reasons. - |:wviminfo| was renamed to |:wshada|, |:rviminfo| to |:rshada|. Old commands are still kept. -- When writing (|:wshada| without bang or at exit) it merges much more data, - and does this according to the timestamp. Vim merges only marks. - |shada-merging| - ShaDa file format was designed with forward and backward compatibility in mind. |shada-compatibility| - Some errors make ShaDa code keep temporary file in-place for user to decide what to do with it. Vim deletes temporary file in these cases. |shada-error-handling| -- Vim keeps no timestamps at all, neither in viminfo file nor in the instance - itself. - ShaDa file keeps search direction (|v:searchforward|), viminfo does not. |printf()| returns something meaningful when used with `%p` argument: in Vim @@ -245,23 +277,45 @@ coerced to strings. See |id()| for more details, currently it uses |c_CTRL-R| pasting a non-special register into |cmdline| omits the last <CR>. +Lua interface (|if_lua.txt|): + +- `:lua print("a\0b")` will print `a^@b`, like with `:echomsg "a\nb"` . In Vim + that prints `a` and `b` on separate lines, exactly like + `:lua print("a\nb")` . +- `:lua error('TEST')` will print “TEST” as the error in Vim and “E5105: Error + while calling lua chunk: [string "<VimL compiled string>"]:1: TEST” in + Neovim. +- Lua has direct access to Nvim |API| via `vim.api`. +- Lua package.path and package.cpath are automatically updated according to + 'runtimepath': |lua-require|. + +|input()| and |inputdialog()| support for each other’s features (return on +cancel and completion respectively) via dictionary argument (replaces all +other arguments if used). + +|input()| and |inputdialog()| support user-defined cmdline highlighting. + +Highlight groups: + |hl-ColorColumn|, |hl-CursorColumn| are lower priority than most other + groups + +The variable name "count" is no fallback for |v:count| anymore. + ============================================================================== 5. Missing legacy features *nvim-features-missing* - *if_lua* *if_perl* *if_mzscheme* *if_tcl* -These legacy Vim features may be implemented in the future, but they are not -planned for the current milestone. +Some legacy Vim features are not implemented: - |if_py|: vim.bindeval() and vim.Function() are not supported -- |if_lua| -- |if_perl| -- |if_mzscheme| -- |if_tcl| +- |if_lua|: the `vim` object is missing most legacy methods +- *if_perl* +- *if_mzscheme* +- *if_tcl* ============================================================================== 6. Removed features *nvim-features-removed* -These features are in Vim, but have been intentionally removed from Nvim. +These Vim features were intentionally removed from Nvim. *'cp'* *'nocompatible'* *'nocp'* *'compatible'* Nvim is always "non-compatible" with Vi. @@ -273,6 +327,29 @@ Ed-compatible mode: ":set noedcompatible" is ignored ":set edcompatible" is an error + *t_xx* *:set-termcap* *termcap-options* *t_AB* *t_Sb* *t_vb* *t_SI* +Nvim does not have special `t_XX` options nor <t_XX> keycodes to configure +terminal capabilities. Instead Nvim treats the terminal as any other UI. For +example, 'guicursor' sets the terminal cursor style if possible. + + *'term'* *E529* *E530* *E531* +'term' reflects the terminal type derived from |$TERM| and other environment +checks. For debugging only; not reliable during startup. > + :echo &term +"builtin_x" means one of the |builtin-terms| was chosen, because the expected +terminfo file was not found on the system. + + *termcap* +Nvim never uses the termcap database, only |terminfo| and |builtin-terms|. + + *xterm-8bit* *xterm-8-bit* +Xterm can be run in a mode where it uses true 8-bit CSI. Supporting this +requires autodetection of whether the terminal is in UTF-8 mode or non-UTF-8 +mode, as the 8-bit CSI character has to be written differently in each case. +Vim issues a "request version" sequence to the terminal at startup and looks +at how the terminal is sending CSI. Nvim does not issue such a sequence and +always uses 7-bit control sequences. + 'ttyfast': ":set ttyfast" is ignored ":set nottyfast" is an error @@ -285,9 +362,6 @@ MS-DOS support: 'bioskey' 'conskey' -Highlight groups: - |hl-VisualNOS| - Test functions: test_alloc_fail() test_autochdir() @@ -303,11 +377,12 @@ Test functions: Other options: 'antialias' - 'cpoptions' ("g", "w", "H", "*", "-", "j", and all POSIX flags were removed) + 'cpoptions' (g j k H w < * - and all POSIX flags were removed) 'encoding' ("utf-8" is always used) 'esckeys' 'guioptions' "t" flag was removed *'guipty'* (Nvim uses pipes and PTYs consistently on all platforms.) + 'highlight' (Names of builtin |highlight-groups| cannot be changed.) *'imactivatefunc'* *'imaf'* *'imactivatekey'* *'imak'* *'imstatusfunc'* *'imsf'* @@ -316,7 +391,6 @@ Other options: 'shelltype' *'shortname'* *'sn'* *'noshortname'* *'nosn'* *'swapsync'* *'sws'* - *'term'* *E529* *E530* *E531* *'termencoding'* *'tenc'* (Vim 7.4.852 also removed this for Windows) 'textauto' 'textmode' diff --git a/runtime/doc/visual.txt b/runtime/doc/visual.txt index 6810d50c11..176ce562d8 100644 --- a/runtime/doc/visual.txt +++ b/runtime/doc/visual.txt @@ -1,4 +1,4 @@ -*visual.txt* For Vim version 7.4. Last change: 2014 Mar 23 +*visual.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -11,14 +11,7 @@ operator. It is the only way to select a block of text. This is introduced in section |04.4| of the user manual. -1. Using Visual mode |visual-use| -2. Starting and stopping Visual mode |visual-start| -3. Changing the Visual area |visual-change| -4. Operating on the Visual area |visual-operators| -5. Blockwise operators |blockwise-operators| -6. Repeating |visual-repeat| -7. Examples |visual-examples| -8. Select mode |Select-mode| + Type |gO| to see the table of contents. ============================================================================== 1. Using Visual mode *visual-use* @@ -32,8 +25,7 @@ Using Visual mode consists of three parts: 3. Type an operator command. The highlighted characters will be operated upon. -The 'highlight' option can be used to set the display mode to use for -highlighting in Visual mode. +The |hl-Visual| group determines the highlighting of the visual selection. The 'virtualedit' option can be used to allow positioning the cursor to positions where there is no actual character. @@ -278,7 +270,7 @@ mode. For example, if you would like the "/" command not to extend the Visual area, but instead take the highlighted text and search for that: > :vmap / y/<C-R>"<CR> (In the <> notation |<>|, when typing it you should type it literally; you -need to remove the 'B' and '<' flags from 'cpoptions'.) +need to remove the 'B' flag from 'cpoptions'.) If you want to give a register name using the """ command, do this just before typing the operator character: "v{move-around}"xd". @@ -382,7 +374,7 @@ Here is an example, to replace the selected text with the output of "date": > :vmap _a <Esc>`>a<CR><Esc>`<i<CR><Esc>!!date<CR>kJJ (In the <> notation |<>|, when typing it you should type it literally; you -need to remove the 'B' and '<' flags from 'cpoptions') +need to remove the 'B' flag from 'cpoptions') What this does is: <Esc> stop Visual mode @@ -399,7 +391,7 @@ selected text: > :vmap X y/<C-R>"<CR> (In the <> notation |<>|, when typing it you should type it literally; you -need to remove the 'B' and '<' flags from 'cpoptions') +need to remove the 'B' flag from 'cpoptions') Note that special characters (like '.' and '*') will cause problems. diff --git a/runtime/doc/windows.txt b/runtime/doc/windows.txt index 5b94626e36..e83377471c 100644 --- a/runtime/doc/windows.txt +++ b/runtime/doc/windows.txt @@ -1,4 +1,4 @@ -*windows.txt* For Vim version 7.4. Last change: 2016 Jun 10 +*windows.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -13,18 +13,7 @@ differently when used in combination with more than one window. The basics are explained in chapter 7 and 8 of the user manual |usr_07.txt| |usr_08.txt|. -1. Introduction |windows-intro| -2. Starting Vim |windows-starting| -3. Opening and closing a window |opening-window| -4. Moving cursor to other windows |window-move-cursor| -5. Moving windows around |window-moving| -6. Window resizing |window-resize| -7. Argument and buffer list commands |buffer-list| -8. Do a command in all buffers or windows |list-repeat| -9. Tag or file name under the cursor |window-tag| -10. The preview window |preview-window| -11. Using hidden buffers |buffer-hidden| -12. Special kinds of buffers |special-buffers| + Type |gO| to see the table of contents. ============================================================================== 1. Introduction *windows-intro* *window* @@ -69,7 +58,7 @@ places where a Normal mode command can't be used or is inconvenient. The main Vim window can hold several split windows. There are also tab pages |tab-page|, each of which can hold multiple windows. - + *window-ID* *winid* *windowid* Each window has a unique identifier called the window ID. This identifier will not change within a Vim session. The |win_getid()| and |win_id2tabwin()| functions can be used to convert between the window/tab number and the @@ -117,18 +106,10 @@ This option can be local to the window, so that you can have a different status line in each window. Normally, inversion is used to display the status line. This can be changed -with the 's' character in the 'highlight' option. For example, "sb" sets it to -bold characters. If no highlighting is used for the status line ("sn"), the -'^' character is used for the current window, and '=' for other windows. If -the mouse is supported and enabled with the 'mouse' option, a status line can -be dragged to resize windows. - -Note: If you expect your status line to be in reverse video and it isn't, -check if the 'highlight' option contains "si". In version 3.0, this meant to -invert the status line. Now it should be "sr", reverse the status line, as -"si" now stands for italic! If italic is not available on your terminal, the -status line is inverted anyway; you will only see this problem on terminals -that have termcap codes for italics. +with the |hl-StatusLine| highlight group. If no highlighting is used for the +status line, the '^' character is used for the current window, and '=' for +other windows. If 'mouse' is enabled, a status line can be dragged to resize +windows. ============================================================================== 3. Opening and closing a window *opening-window* *E36* @@ -249,7 +230,7 @@ window will appear. far left and occupies the full height of the Vim window. Doesn't work for |:execute| and |:normal|. - *:botright* + *:bo* *:botright* :bo[tright] {cmd} Execute {cmd}. If it contains a command that splits a window, it will appear at the bottom and occupy the full width of the @@ -287,7 +268,7 @@ CTRL-W CTRL-Q *CTRL-W_CTRL-Q* :1quit " quit the first window :$quit " quit the last window :9quit " quit the last window - " if there are less than 9 windows opened + " if there are fewer than 9 windows opened :-quit " quit the previous window :+quit " quit the next window :+2quit " quit the second next window @@ -330,8 +311,9 @@ CTRL-W CTRL-C *CTRL-W_CTRL-C* *:hide* :hid[e] :{count}hid[e] - Quit the current window, unless it is the last window on the - screen. For {count} see |:quit|. + Without {count}: Quit the current window, unless it is the + last window on the screen. + If {count} is given quit the {count} window. The buffer becomes hidden (unless there is another window editing it or 'bufhidden' is `unload`, `delete` or `wipe`). @@ -534,6 +516,9 @@ CTRL-W > Increase current window width by N (default 1). :vertical res[ize] [N] *:vertical-resize* *CTRL-W_bar* CTRL-W | Set current window width to N (default: widest possible). + *:mod* *:mode* +:mod[e] Detects the screen size and redraws the screen. + You can also resize a window by dragging a status line up or down with the mouse. Or by dragging a vertical separator line left or right. This only works if the version of Vim that is being used supports the mouse and the @@ -602,7 +587,8 @@ The minimal height and width of a window is set with 'winminheight' and 41. :buffers list of buffers The meaning of [N] depends on the command: - [N] is number of buffers to go forward/backward on ?2, ?3, and ?4 + [N] is the number of buffers to go forward/backward on 2/12/22/32, + 3/13/23/33, and 4/14/24/34 [N] is an argument number, defaulting to current argument, for 1 and 21 [N] is a buffer number, defaulting to current buffer, for 11 and 31 [N] is a count for 19 and 39 @@ -685,6 +671,8 @@ can also get to them with the buffer list commands, like ":bnext". - If the file is not open in a window edit the file in the current window. If the current buffer can't be |abandon|ed, the window is split first. + - Windows that are not in the argument list or are not full + width will be closed if possible. The |argument-list| is set, like with the |:next| command. The purpose of this command is that it can be used from a program that wants Vim to edit another file, e.g., a debugger. @@ -1008,6 +996,9 @@ list of buffers. |unlisted-buffer| displayed in a window |hidden-buffer| - a buffer with 'modifiable' off = a readonly buffer + R a terminal buffer with a running job + F a terminal buffer with a finished job + ? a terminal buffer without a job: `:terminal NONE` + a modified buffer x a buffer with read errors @@ -1026,6 +1017,10 @@ list of buffers. |unlisted-buffer| h+ hidden buffers which are modified a+ active buffers which are modified + When using |:filter| the pattern is matched against the + displayed buffer name, e.g.: > + filter /\.vim/ ls +< *:bad* *:badd* :bad[d] [+lnum] {fname} Add file name {fname} to the buffer list, without loading it. @@ -1248,6 +1243,9 @@ help Contains a help file. Will only be created with the |:help| and can't be changed. The 'buflisted' option will be reset for a help buffer. +terminal A terminal window buffer, see |terminal|. The contents cannot + be read or changed until the job ends. + directory Displays directory contents. Can be used by a file explorer plugin. The buffer is created with these settings: > :setlocal buftype=nowrite |