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.

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 <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.
 
+								*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