tui: More refactoring, and improvements to cursor shape support.

The details are in the on-line help under :help cursor-shape .

The brief precis is that nvim is following the lead of tmux, and going
beyond what tmux does to make cursor shape changes work on a broad range of
terminals.  This includes on tmux itself, which is no longer bypassed.

2 files changed, 30 insertions, 11 deletions

diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index 2097cbf32b..225336bae3 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -2756,14 +2756,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: >
diff --git a/runtime/doc/term.txt b/runtime/doc/term.txt
index 13b0b5b37d..3425fb93b4 100644
--- a/runtime/doc/term.txt
+++ b/runtime/doc/term.txt
@@ -95,10 +95,33 @@ for this extension.  So Nvim simply assumes that (all) "dtterm", "xterm",
 
 					*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.
+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 "xterm+tmux") do, then nothing more is required.
+
+If your terminfo definition is missing them, then Nvim will on a wide range of
+terminals resort to using the conventional DECSUSR control sequence for
+adjusting the cursor shape.  If Konsole is detected, Nvim will use the
+idiosyncratic Konsole terminal control sequences for this.
+
+Note: tmux itself accepts the conventional DECSUSR control sequence, the same
+as many other terminals do.  It has to translate this into whatever control
+sequence is appropriate for the terminal that it is outputting to.  Like Nvim,
+it will use the "Ss" and "Se" capabilities from terminfo 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 .  It will
+appear that Nvim 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.  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