doco: Note some common $TERM mistakes and how to fix them.

Also explain more clearly the difference between Vim and Nvim
when it comes to built-in terminfo entries.

2 files changed, 36 insertions, 3 deletions

diff --git a/runtime/doc/term.txt b/runtime/doc/term.txt
index fcfb548723..b15321e6f2 100644
--- a/runtime/doc/term.txt
+++ b/runtime/doc/term.txt
@@ -24,10 +24,30 @@ the pc terminal, for Unix an ansi terminal.
 On Unix the terminfo database is used.  There is no access to the terminfo
 settings with |:set|.
 
+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.
+
+As noted in the commentary in the terminfo source file:
+ - The correct $TERM for GNOME Terminal has been "gnome" since 1999, or
+   "gnome-256color" since 2006.  "vte" and "vte-256color" are equivalents.
+   "xterm" and "xterm-256color" are incorrect.
+ - The correct $TERM for iTerm.app is "iterm" or "iTerm.app".  "xterm" and
+   "xterm-256color" are incorrect; for starters they do not include
+   iTerm.app's status line capability.
+ - The correct $TERM for Terminal.app is "nsterm".  "vt100", "xterm", and
+   "xterm-256color" are incorrect; for starters they do not include
+   Terminal.app's status line capability or correctly describe its
+   cursor-addressed mode.
+ - The correct $TERM for tmux is "tmux" or "tmux-256color".  "screen" is
+   incorrect; for starters it does not include tmux's italics and status line
+   capabilities or correctly describe how to set inverse video.
+
 					*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".
+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"
@@ -37,6 +57,14 @@ 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.  Note that 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.
+
 Settings depending on terminal			*term-dependent-settings*
 
 If you want to set options or mappings, depending on the terminal name, you
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index cc4f441639..9661f1da98 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -160,6 +160,11 @@ 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.)