From 7f990741f7018b5e52833f2da6913b97c6d2d5ee Mon Sep 17 00:00:00 2001
From: Yichao Zhou <broken.zhou@gmail.com>
Date: Sat, 16 Jun 2018 19:28:28 -0700
Subject: TUI: Reset cursor color when applicable #8572
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Resets the TUI cursor color if:
- current 'guicursor' mode does not specify a highlight group
- cursor highlight group has "inverse" or "reverse" flag
- on Nvim exit

We interpret,  "inverse" to mean "default cursor".

Example:

    hi Cursor guifg=bg guibg=fg
    set termguicolors
    set guicursor=n-v-c-sm:block,i-ci-ve:ver25-Cursor,r-cr-o:hor20

    * When the cursor shape is block, its color will be "inverse"
    * When the cursor shape is I-beam, its color will be `hi Cursor`.

This is useful e.g. to prevent `set listchars=eol:¬` causing your cursor
color to a low contrast color in insert mode because you cursor are
often at EOL in insert mode.

close #8572
---
 runtime/doc/options.txt | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

(limited to 'runtime')

diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index fe2fbfc039..2f2db844e8 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -2789,17 +2789,27 @@ A jump table for the options with a short description can be found at |Q_op|.
 			of the numbers is zero, there is no blinking. E.g.: >
 				:set guicursor=n:blinkon0
 <		{group-name}
-			a highlight group name, that sets the color and font
-			for the cursor
+			Highlight group name that sets the color and font for
+			the cursor. |inverse|/reverse and no group-name are
+			interpreted as "the host terminal default cursor
+			colors" which usually invert bg and fg colors.
 		{group-name}/{group-name}
 			Two highlight group names, the first is used when
 			no language mappings are used, the other when they
 			are. |language-mapping|
 
 	Examples of parts:
-	   n-c-v:block-nCursor	in Normal, Command-line and Visual mode, use a
+	   n-c-v:block-nCursor	In Normal, Command-line and Visual mode, use a
 				block cursor with colors from the "nCursor"
 				highlight group
+	   n-v-c-sm:block,i-ci-ve:ver25-Cursor,r-cr-o:hor20
+				In Normal et al. modes, use a block cursor
+				with the default colors defined by the host
+				terminal.  In Insert-likes modes, use
+				a vertical bar cursor with colors from
+				"Cursor" highlight group.  In Replace-likes
+				modes, use a underline cursor with
+				default colors.
 	   i-ci:ver30-iCursor-blinkwait300-blinkon200-blinkoff150
 				In Insert and Command-line Insert mode, use a
 				30% vertical bar cursor with colors from the
-- 
cgit