aboutsummaryrefslogtreecommitdiff
path: root/runtime
diff options
context:
space:
mode:
Diffstat (limited to 'runtime')
-rw-r--r--runtime/autoload/health.vim3
-rw-r--r--runtime/autoload/health/provider.vim4
-rw-r--r--runtime/autoload/provider/clipboard.vim19
-rw-r--r--runtime/doc/api.txt105
-rw-r--r--runtime/doc/cmdline.txt14
-rw-r--r--runtime/doc/deprecated.txt8
-rw-r--r--runtime/doc/eval.txt9
-rw-r--r--runtime/doc/gui.txt15
-rw-r--r--runtime/doc/if_lua.txt142
-rw-r--r--runtime/doc/intro.txt4
-rw-r--r--runtime/doc/job_control.txt40
-rw-r--r--runtime/doc/map.txt27
-rw-r--r--runtime/doc/options.txt37
-rw-r--r--runtime/doc/provider.txt53
-rw-r--r--runtime/doc/quickref.txt4
-rw-r--r--runtime/doc/starting.txt4
-rw-r--r--runtime/doc/syntax.txt12
-rw-r--r--runtime/doc/term.txt242
-rw-r--r--runtime/doc/tips.txt10
-rw-r--r--runtime/doc/vim_diff.txt33
-rw-r--r--runtime/doc/visual.txt6
-rw-r--r--runtime/doc/windows.txt2
-rw-r--r--runtime/ftplugin/help.vim5
-rw-r--r--runtime/ftplugin/vim.vim5
-rw-r--r--runtime/syntax/vim.vim2
25 files changed, 611 insertions, 194 deletions
diff --git a/runtime/autoload/health.vim b/runtime/autoload/health.vim
index 1d8cae7d19..f875c8b797 100644
--- a/runtime/autoload/health.vim
+++ b/runtime/autoload/health.vim
@@ -33,7 +33,8 @@ function! health#check(plugin_names) abort
setlocal wrap breakindent
setlocal filetype=markdown
setlocal conceallevel=2 concealcursor=nc
- setlocal keywordprg=:help iskeyword=@,48-57,_,192-255,-,#
+ setlocal keywordprg=:help
+ let &l:iskeyword='!-~,^*,^|,^",192-255'
call s:enhance_syntax()
if empty(healthchecks)
diff --git a/runtime/autoload/health/provider.vim b/runtime/autoload/health/provider.vim
index 31a235a397..ec20615f69 100644
--- a/runtime/autoload/health/provider.vim
+++ b/runtime/autoload/health/provider.vim
@@ -125,6 +125,10 @@ function! s:check_clipboard() abort
call health#report_warn(
\ 'No clipboard tool found. Clipboard registers will not work.',
\ [':help clipboard'])
+ elseif exists('g:clipboard') && (type({}) != type(g:clipboard)
+ \ || !has_key(g:clipboard, 'copy') || !has_key(g:clipboard, 'paste'))
+ call health#report_error(
+ \ 'g:clipboard exists but is malformed. It must be a dictionary with the keys documented at :help g:clipboard')
else
call health#report_ok('Clipboard tool found: '. clipboard_tool)
endif
diff --git a/runtime/autoload/provider/clipboard.vim b/runtime/autoload/provider/clipboard.vim
index e15aa1f2bd..a67681d28e 100644
--- a/runtime/autoload/provider/clipboard.vim
+++ b/runtime/autoload/provider/clipboard.vim
@@ -8,7 +8,7 @@ let s:paste = {}
" ownership of the selection, so we know how long the cache is valid.
let s:selection = { 'owner': 0, 'data': [] }
-function! s:selection.on_exit(jobid, data, event)
+function! s:selection.on_exit(jobid, data, event) abort
" At this point this nvim instance might already have launched
" a new provider instance. Don't drop ownership in this case.
if self.owner == a:jobid
@@ -18,7 +18,7 @@ endfunction
let s:selections = { '*': s:selection, '+': copy(s:selection)}
-function! s:try_cmd(cmd, ...)
+function! s:try_cmd(cmd, ...) abort
let argv = split(a:cmd, " ")
let out = a:0 ? systemlist(argv, a:1, 1) : systemlist(argv, [''], 1)
if v:shell_error
@@ -34,7 +34,7 @@ function! s:try_cmd(cmd, ...)
endfunction
" Returns TRUE if `cmd` exits with success, else FALSE.
-function! s:cmd_ok(cmd)
+function! s:cmd_ok(cmd) abort
call system(a:cmd)
return v:shell_error == 0
endfunction
@@ -47,7 +47,12 @@ function! provider#clipboard#Error() abort
endfunction
function! provider#clipboard#Executable() abort
- if has('mac') && executable('pbcopy')
+ if exists('g:clipboard')
+ let s:copy = get(g:clipboard, 'copy', { '+': v:null, '*': v:null })
+ let s:paste = get(g:clipboard, 'paste', { '+': v:null, '*': v:null })
+ let s:cache_enabled = get(g:clipboard, 'cache_enabled', 1)
+ return get(g:clipboard, 'name', 'g:clipboard')
+ elseif has('mac') && executable('pbcopy')
let s:copy['+'] = 'pbcopy'
let s:paste['+'] = 'pbpaste'
let s:copy['*'] = s:copy['+']
@@ -102,14 +107,14 @@ endif
let s:clipboard = {}
-function! s:clipboard.get(reg)
+function! s:clipboard.get(reg) abort
if s:selections[a:reg].owner > 0
return s:selections[a:reg].data
end
return s:try_cmd(s:paste[a:reg])
endfunction
-function! s:clipboard.set(lines, regtype, reg)
+function! s:clipboard.set(lines, regtype, reg) abort
if a:reg == '"'
call s:clipboard.set(a:lines,a:regtype,'+')
if s:copy['*'] != s:copy['+']
@@ -144,6 +149,6 @@ function! s:clipboard.set(lines, regtype, reg)
let selection.owner = jobid
endfunction
-function! provider#clipboard#Call(method, args)
+function! provider#clipboard#Call(method, args) abort
return call(s:clipboard[a:method],a:args,s:clipboard)
endfunction
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index ebc2a40561..7c6b8a3c1a 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -165,7 +165,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>. Does nothing if
+ `special` is false.
+ {special} Replace |keycodes|, e.g. <CR> becomes a "\n"
+ char.
nvim_command_output({str}) *nvim_command_output()*
TODO: Documentation
@@ -182,8 +191,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
@@ -192,6 +203,23 @@ nvim_call_function({fname}, {args}) *nvim_call_function()*
Return:~
Result of the function call
+nvim_execute_lua({code}, {args}) *nvim_execute_lua()*
+ Execute lua code. Parameters might be passed, they are
+ available inside the chunk as `...`. The chunk can return a
+ value.
+
+ To evaluate an expression, it must be prefixed with "return ".
+ For instance, to call a lua function with arguments sent in
+ and get its return value back, use the code "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({str}) *nvim_strwidth()*
Calculates the number of display cells occupied by `text`.
<Tab> counts as one cell.
@@ -382,6 +410,17 @@ nvim_get_mode() *nvim_get_mode()*
Return:~
Dictionary { "mode": String, "blocking": Boolean }
+nvim_get_keymap({mode}) *nvim_get_keymap()*
+ Get a list of dictionaries describing global (i.e. non-buffer)
+ mappings Note that the "buffer" key will be 0 to represent
+ false.
+
+ Parameters:~
+ {mode} The abbreviation for the mode
+
+ Return:~
+ An array of maparg() like dictionaries describing mappings
+
nvim_get_api_info() *nvim_get_api_info()*
TODO: Documentation
@@ -414,6 +453,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*
@@ -492,6 +579,18 @@ nvim_buf_get_changedtick({buffer}) *nvim_buf_get_changedtick()*
Return:~
b:changedtickvalue.
+nvim_buf_get_keymap({buffer}, {mode}) *nvim_buf_get_keymap()*
+ Get a list of dictionaries describing buffer-local mappings
+ Note that the buffer key in the dictionary will represent the
+ buffer handle where the mapping is present
+
+ Parameters:~
+ {mode} The abbreviation for the mode
+ {buffer_id} Buffer handle
+
+ Return:~
+ An array of maparg() like dictionaries describing mappings
+
nvim_buf_set_var({buffer}, {name}, {value}) *nvim_buf_set_var()*
Sets a buffer-scoped (b:) variable
diff --git a/runtime/doc/cmdline.txt b/runtime/doc/cmdline.txt
index 948c921431..d870a72600 100644
--- a/runtime/doc/cmdline.txt
+++ b/runtime/doc/cmdline.txt
@@ -389,12 +389,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
diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt
index 26cd5b24cc..b3e2f7a92f 100644
--- a/runtime/doc/deprecated.txt
+++ b/runtime/doc/deprecated.txt
@@ -39,10 +39,16 @@ Functions ~
*highlightID()* Obsolete name for |hlID()|.
*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.
*'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/eval.txt b/runtime/doc/eval.txt
index 2262c01374..e51f0f5dfc 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -1852,10 +1852,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.
diff --git a/runtime/doc/gui.txt b/runtime/doc/gui.txt
index 0bd3a40a7c..b66a60c860 100644
--- a/runtime/doc/gui.txt
+++ b/runtime/doc/gui.txt
@@ -490,9 +490,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.
@@ -504,21 +501,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
diff --git a/runtime/doc/if_lua.txt b/runtime/doc/if_lua.txt
index 470f3bde7a..c4efd57b45 100644
--- a/runtime/doc/if_lua.txt
+++ b/runtime/doc/if_lua.txt
@@ -9,7 +9,147 @@ Lua Interface to Nvim *lua* *Lua*
Type <M-]> to see the table of contents.
==============================================================================
-1. Commands *lua-commands*
+1. Importing modules *lua-require*
+
+Neovim lua interface automatically adjusts `package.path` and `package.cpath`
+according to effective &runtimepath value. Adjustment happens after
+'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. Here is an 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 Neovim 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.
+
+------------------------------------------------------------------------------
+1.1. Example of the plugin which 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,
+ }
+
+==============================================================================
+2. Commands *lua-commands*
*:lua*
:[range]lua {chunk}
diff --git a/runtime/doc/intro.txt b/runtime/doc/intro.txt
index c745d60ebc..88d04aa76b 100644
--- a/runtime/doc/intro.txt
+++ b/runtime/doc/intro.txt
@@ -442,8 +442,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
diff --git a/runtime/doc/job_control.txt b/runtime/doc/job_control.txt
index da592d6eb0..edbc1bca81 100644
--- a/runtime/doc/job_control.txt
+++ b/runtime/doc/job_control.txt
@@ -102,36 +102,30 @@ function. Here's a more object-oriented version of the above:
>
let Shell = {}
- function Shell.on_stdout(job_id, data) dict
- call append(line('$'), self.get_name().' stdout: '.join(a:data))
+ 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.on_stderr(job_id, data) dict
- call append(line('$'), self.get_name().' stderr: '.join(a:data))
- endfunction
-
- function Shell.on_exit(job_id, data) dict
- call append(line('$'), self.get_name().' exited')
- endfunction
+ let Shell.on_stderr = function(Shell.on_stdout)
- function Shell.get_name() dict
- return 'shell '.self.name
+ 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
- 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.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
- let s1 = Shell.new('1')
- let s2 = Shell.new('2', 'for i in {1..10}; do echo hello $i!; sleep 1; done')
-
-
+ 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, one can use the |jobsend()| function, like
this:
>
diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt
index 16c044a21d..bfcf621cb8 100644
--- a/runtime/doc/map.txt
+++ b/runtime/doc/map.txt
@@ -149,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,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
@@ -443,17 +437,15 @@ 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, 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. The <> form cannot be used when 'cpoptions'
- includes the '<' flag.
+ 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. If a terminal code is found it is
@@ -571,9 +563,9 @@ 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).
@@ -628,8 +620,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>
@@ -881,7 +872,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: >
@@ -1029,8 +1019,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: >
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index bb5cfb4a80..dc968cd666 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -24,10 +24,7 @@ achieve special effects. These options come in three forms:
: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] termcap Do nothing. Nvim uses |terminfo|.
*E518* *E519*
:se[t] {option}? Show value of {option}.
@@ -1571,7 +1568,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
@@ -1621,15 +1617,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
@@ -1763,14 +1750,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.
@@ -2756,14 +2735,10 @@ A jump table for the options with a short description can be found at |Q_op|.
*'guicursor'* *'gcr'* *E545* *E546* *E548* *E549*
'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 some
- terminals.
+ Configures the cursor style for each mode. Works in the GUI and many
+ terminals. See |cursor-shape| for details.
- With tmux you might need this in ~/.tmux.conf (see terminal-overrides
- in the tmux(1) manual page): >
- set -ga terminal-overrides ',*:Ss=\E[%p1%d q:Se=\E[2 q'
-
-< To disable cursor-styling, reset the option: >
+ To disable cursor-styling, reset the option: >
:set guicursor=
< To enable mode shapes, "Cursor" highlight, and blinking: >
@@ -6272,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,
@@ -6287,7 +6262,7 @@ 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
diff --git a/runtime/doc/provider.txt b/runtime/doc/provider.txt
index 435646bd1c..50307ccbf3 100644
--- a/runtime/doc/provider.txt
+++ b/runtime/doc/provider.txt
@@ -116,29 +116,48 @@ To use the RVM "system" Ruby installation: >
==============================================================================
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): >
+ 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)
- xclip
- xsel (newer alternative to xclip)
- - pbcopy/pbpaste (macOS)
- 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*
diff --git a/runtime/doc/quickref.txt b/runtime/doc/quickref.txt
index 128c70ee94..bcbf8c365d 100644
--- a/runtime/doc/quickref.txt
+++ b/runtime/doc/quickref.txt
@@ -571,8 +571,8 @@ 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] termcap Do nothing. (|terminfo|)
|: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)
diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt
index 8581bcfb72..d869516bff 100644
--- a/runtime/doc/starting.txt
+++ b/runtime/doc/starting.txt
@@ -214,7 +214,7 @@ argument.
:set to display option values.
When 'verbose' is non-zero messages are printed (for
debugging, to stderr).
- $TERM is not used.
+ $TERM (see |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.
@@ -355,7 +355,7 @@ argument.
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.
diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt
index 07af856e6b..a66f547675 100644
--- a/runtime/doc/syntax.txt
+++ b/runtime/doc/syntax.txt
@@ -4696,7 +4696,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 |terminfo-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
@@ -4768,9 +4768,8 @@ ctermbg={color-nr} *highlight-ctermbg*
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
@@ -5207,10 +5206,7 @@ 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.
+Nvim uses |256-color| and |true-color| terminal capabilities whereever possible.
==============================================================================
18. When syntax is slow *:syntime*
diff --git a/runtime/doc/term.txt b/runtime/doc/term.txt
index cdff8760fc..bce944eab5 100644
--- a/runtime/doc/term.txt
+++ b/runtime/doc/term.txt
@@ -20,21 +20,194 @@ 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.
- *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.
+ *terminfo* *E557* *E558* *E559*
+On Unix the terminfo database is used. There is no access to the terminfo
+settings with |:set|.
+
+The Unibilium library (used by Nvim to read terminfo) allows you to override
+an out-of-date system terminfo database with one in your $HOME/.terminfo/
+directory, in part or in whole.
+
+Building your own up-to-date terminfo database is usually as simple as running
+this as a non-superuser:
+>
+ wget http://invisible-island.net/datafiles/current/terminfo.src.gz
+ gunzip terminfo.src.gz
+ tic terminfo.src
+<
+ *TERM*
+If you experience terminal difficulties, first ensure that you have set the
+correct terminal type in your $TERM environment variable so that Nvim is
+pulling the correct entry from the terminfo database in the first place.
+
+Per the terminfo source file from ncurses:
+
+ For these terminals Set $TERM to |builtin-terms|?
+
+ iTerm.app "iterm" or "iTerm.app" Y
+ anything libvte based "vte" or "vte-256color" Y
+ (e.g. GNOME Terminal) ("gnome" and "gnome-256color" are
+ available as aliases for these)
+ tmux "tmux" or "tmux-256color" Y
+ screen "screen" or "screen-256color" Y
+ PuTTY "putty" or "putty-256color" Y
+ Terminal.app "nsterm" N
+ Linux virtual terminal "linux" or "linux-256color" Y
+
+Describing any of these as "xterm" or "xterm-256colour" will not describe the
+terminal correctly to Nvim, and will cause various kinds of problematic
+behaviours.
+
+Setting your $TERM environment variable to the correct value also avoids the
+problem that SSH does not mirror arbitrary client-end environment variables
+such as $COLORTERM, $XTERM_VERSION, $VTE_VERSION, $KONSOLE_PROFILE_NAME, and
+$TERM_PROGRAM to the server end, whereas it does send the $TERM environment
+variable.
+
+See |terminfo| for dealing with out of date terminfo databases.
+
+ *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 look up the terminal type in 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 |termcap-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.
Settings depending on terminal *term-dependent-settings*
If you want to set options or mappings, depending on the terminal name, you
-can do this best in your vimrc. Example: >
-
- if &term == "xterm"
- ... xterm maps and settings ...
- elseif &term =~ "vt10."
- ... vt100, vt102 maps and settings ...
- endif
+can do this best 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
<
+ *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.
+
+ *256-color* *terminfo-colors* *termcap-colors*
+Nvim can make use of 256-colour terminals and tries to do so whereever it can.
+
+If the |terminfo| description of the terminal says that it supports fewer
+colours, Nvim will override this for many terminal types, including "linux"
+(whose virtual terminals have had 256-colour support since version 4.8) and
+anything (even if falsely) claiming to be "xterm". It will also set 256
+colours when the COLORTERM or TERM environment variables contain the string
+"256" somewhere.
+
+Nvim similarly assumes that any terminal emulator that sets the COLORTERM
+environment variable at all, to anything, is capable of at least 16-colour
+operation; and it will override |terminfo| saying that it has fewer colours
+available.
+
+ *true-color* *xterm-true-color*
+Nvim supports using true (24-bit) colours in the terminal, on terminals that
+support it. It uses the same |terminfo| extensions that were proposed by
+Rüdiger Sonderfeld in 2013 for this: "setrgbf" and "setrgbb". If your
+terminfo definition specifies these, then nothing more is required.
+
+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.
+(Semicolons cause ambiguities that the standard avoided by specifying colons
+as a sub-parameter delimiter. A historical misunderstanding meant that many
+terminal emulators ended up using semicolons for many years, though.)
+
+A new convention, pioneered in 2016 by tmux, is the "Tc" terminfo extension.
+If your terminal's terminfo definition has this flag, Nvim will add
+constructed "setrgbf" and "setrgbb" capabilities as if they had been in the
+terminfo definition.
+
+If your terminal's terminfo definition does not (yet) have this flag, Nvim
+will fall back to looking at the 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 the dtterm program. |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.
+
+ *cursor-shape* *terminfo-cursor-shape* *termcap-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 specifies these, as some
+(such as those based upon "xterm+tmux") do, then nothing more is required.
+
+If your terminfo definition is missing them, then Nvim will decide whether to
+add them to your terminfo definition, by looking at the 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
+will have to add them by setting the tmux "terminal-overrides" setting in
+$HOME/.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'
+<but these are only rough examples that do not include all of the other stuff
+that occurs in that setting.
+
*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
@@ -69,20 +242,6 @@ 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.
- *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 "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.
-
==============================================================================
Window size *window-size*
@@ -93,7 +252,7 @@ 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
@@ -116,30 +275,27 @@ 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.
==============================================================================
Using the mouse *mouse-using*
diff --git a/runtime/doc/tips.txt b/runtime/doc/tips.txt
index 9b34cd7599..0ac9a8303d 100644
--- a/runtime/doc/tips.txt
+++ b/runtime/doc/tips.txt
@@ -113,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|.
@@ -129,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*
@@ -282,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
@@ -300,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/vim_diff.txt b/runtime/doc/vim_diff.txt
index 8851ef2d4b..5801da1132 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -156,6 +156,15 @@ 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.)
@@ -244,6 +253,8 @@ Lua interface (|if_lua.txt|):
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|.
- Currently, most legacy Vim features are missing.
|input()| and |inputdialog()| gained support for each other’s features (return
@@ -281,6 +292,25 @@ 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*
+The 'term' option has a fixed value, present only for script compatibility and
+intentionally not the same as any known terminal type name. It should be a
+rare case in Nvim where one needs |term-dependent-settings|, for which use the
+|TERM| environment variable.
+
+ *termcap*
+Nvim never uses the termcap database and only uses |terminfo|. See
+|builtin-terms| for what happens on operating systems without a terminfo
+database.
+
+ *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
@@ -308,7 +338,7 @@ 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
@@ -322,7 +352,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 e9f5bf91f8..cf804444e5 100644
--- a/runtime/doc/visual.txt
+++ b/runtime/doc/visual.txt
@@ -271,7 +271,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".
@@ -375,7 +375,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
@@ -392,7 +392,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 1941ac0972..651d617a76 100644
--- a/runtime/doc/windows.txt
+++ b/runtime/doc/windows.txt
@@ -117,7 +117,7 @@ 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.
+that have |terminfo| capabilities for italics.
==============================================================================
3. Opening and closing a window *opening-window* *E36*
diff --git a/runtime/ftplugin/help.vim b/runtime/ftplugin/help.vim
index c94b2ef3eb..9d2361b413 100644
--- a/runtime/ftplugin/help.vim
+++ b/runtime/ftplugin/help.vim
@@ -11,13 +11,16 @@ let b:did_ftplugin = 1
let s:cpo_save = &cpo
set cpo&vim
-let b:undo_ftplugin = "setl fo< tw< cole< cocu<"
+let b:undo_ftplugin = "setl fo< tw< cole< cocu< keywordprg<"
setlocal formatoptions+=tcroql textwidth=78
if has("conceal")
setlocal cole=2 cocu=nc
endif
+" Prefer Vim help instead of manpages.
+setlocal keywordprg=:help
+
if !exists('g:no_plugin_maps')
function! s:show_toc() abort
let bufname = bufname('%')
diff --git a/runtime/ftplugin/vim.vim b/runtime/ftplugin/vim.vim
index f355d2837d..ba9ed76169 100644
--- a/runtime/ftplugin/vim.vim
+++ b/runtime/ftplugin/vim.vim
@@ -14,7 +14,7 @@ let b:did_ftplugin = 1
let s:cpo_save = &cpo
set cpo-=C
-let b:undo_ftplugin = "setl fo< isk< com< tw< commentstring<"
+let b:undo_ftplugin = "setl fo< isk< com< tw< commentstring< keywordprg<"
\ . "| unlet! b:match_ignorecase b:match_words b:match_skip"
" Set 'formatoptions' to break comment lines but not other lines,
@@ -36,6 +36,9 @@ endif
" Comments start with a double quote
setlocal commentstring=\"%s
+" Prefer Vim help instead of manpages.
+setlocal keywordprg=:help
+
" Move around functions.
nnoremap <silent><buffer> [[ m':call search('^\s*fu\%[nction]\>', "bW")<CR>
vnoremap <silent><buffer> [[ m':<C-U>exe "normal! gv"<Bar>call search('^\s*fu\%[nction]\>', "bW")<CR>
diff --git a/runtime/syntax/vim.vim b/runtime/syntax/vim.vim
index 85ced1ed3e..7025ee5369 100644
--- a/runtime/syntax/vim.vim
+++ b/runtime/syntax/vim.vim
@@ -21,7 +21,7 @@ syn keyword vimTodo contained COMBAK FIXME TODO XXX
syn cluster vimCommentGroup contains=vimTodo,@Spell
" Special and plugin vim commands {{{2
-syn match vimCommand contained "\<z[-+^.=]\="
+syn match vimCommand contained "\<z[-+^.=]\=\>"
syn keyword vimOnlyCommand contained fix[del] op[en] sh[ell] P[rint]
syn keyword vimStdPlugin contained DiffOrig Man N[ext] S TOhtml XMLent XMLns
generated by cgit (git 2.34.1) at 2025-05-29 08:00:43 +0000