From d65cff9de89936109bc25aec78dc11a16707fe50 Mon Sep 17 00:00:00 2001 From: Jonathan de Boyne Pollard Date: Wed, 24 May 2017 21:09:25 +0100 Subject: [PATCH] doc: Document some more terminal behaviours. This documents 256-colour and true colour handling, cursor shapes, and scrolling regions. Almost all of these headings are taken from the Vim doco, so that the :help commands that people learn are a transferable skill. --- runtime/doc/syntax.txt | 5 +-- runtime/doc/term.txt | 71 ++++++++++++++++++++++++++++++++++++++-- runtime/doc/vim_diff.txt | 9 +++++ 3 files changed, 78 insertions(+), 7 deletions(-) diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt index d711aa6a29..ed2a97cb3b 100644 --- a/runtime/doc/syntax.txt +++ b/runtime/doc/syntax.txt @@ -5207,10 +5207,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 bb27873e42..13b0b5b37d 100644 --- a/runtime/doc/term.txt +++ b/runtime/doc/term.txt @@ -20,9 +20,21 @@ 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. + + *builtin-terms* *builtin_terms* +If a terminfo database is not available, 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", 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. Settings depending on terminal *term-dependent-settings* @@ -35,6 +47,59 @@ can do this best in your vimrc. Example: > ... vt100, vt102 maps and settings ... 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* *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. |terminfo| does +not contain flags to say when terminals have true colour support. So Nvim +simply assumes true colour support for (all) "xterm", "rxvt", "linux", +"putty", and "iterm" terminal types, or when Konsole 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* *termcap-cursor-shape* +Nvim will adjust the shape of the cursor from a block to a line when in insert +mode, on terminals that support it. If Konsole is detected, it will use the +idiosyncratic Konsole terminal control sequences for this, attempting to do +the right thing if tmux is between Nvim and Konsole. Otherwise, it uses the +conventional DECSCUSR control sequences. + *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 diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt index dabf488465..cc4f441639 100644 --- a/runtime/doc/vim_diff.txt +++ b/runtime/doc/vim_diff.txt @@ -156,6 +156,10 @@ 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. + |:!| does not support "interactive" commands. Use |:terminal| instead. (GUI Vim has a similar limitation, see ":help gui-pty" in Vim.) @@ -281,6 +285,11 @@ Nvim does not have special `t_XX` options nor keycodes to configure terminal capabilities. Instead Nvim treats the terminal as any other UI. For example, 'guicursor' sets the terminal cursor style if possible. + *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