From 84017a7917bdd163625ce40b5e6c0cc1f867523c Mon Sep 17 00:00:00 2001
From: Frank LENORMAND <lenormf@gmail.com>
Date: Fri, 23 Feb 2018 11:19:54 +0300
Subject: [PATCH] faq: Document how to render colors properly in `tmux`

---
 contrib/tmux-256color.terminfo |  4 ++++
 doc/pages/faq.asciidoc         | 27 ++++++++++++++++++++++++---
 2 files changed, 28 insertions(+), 3 deletions(-)
 create mode 100644 contrib/tmux-256color.terminfo

diff --git a/contrib/tmux-256color.terminfo b/contrib/tmux-256color.terminfo
new file mode 100644
index 00000000..cef5adcf
--- /dev/null
+++ b/contrib/tmux-256color.terminfo
@@ -0,0 +1,4 @@
+tmux-256color|tmux with 256 color and palette setting,
+	use=tmux-256color,
+	ccc,
+	initc=\E]4;%p1%d;rgb\:%p2%{255}%*%{1000}%/%2.2X/%p3%{255}%*%{1000}%/%2.2X/%p4%{255}%*%{1000}%/%2.2X\E\\,
diff --git a/doc/pages/faq.asciidoc b/doc/pages/faq.asciidoc
index 66f9ce63..a86e8c1e 100644
--- a/doc/pages/faq.asciidoc
+++ b/doc/pages/faq.asciidoc
@@ -45,9 +45,30 @@ This variable should be set by the terminal emulator, and not overridden with
 an arbitrary value, otherwise it might interfere with general UI rendering on
 the terminal's window.
 
-Note that if you're using `tmux`, the proper -official- way to get Kakoune to
-work is to add the following line to your `tmux` configuration file:
-`set -sg default-terminal screen-256color`
+== I'm using `tmux` and colors look weird
+
+If you're using a tool that doesn't support "palette switching", colors will
+still be slightly off: they are being rounded down to values supported by the
+regular color palette by Kakoune. Fortunately, on recent versions of `tmux`
+(>=2.6), you can work around that by using the following configuration
+settings:
+
+~/.tmux.conf
+```
+set -g default-terminal "tmux-256color"
+set -ga terminal-overrides ",*col*:Tc"
+```
+
+Note: `\*col*` is a regular expression that matches your terminal's `$TERM`
+value, modify it if necessary, e.g. `xterm-termite`.
+
+Next, run the following command to create a local `terminfo` override:
+
+```
+$ tic /path/to/kakoune/contrib/tmux-256color.terminfo
+```
+
+Finally, quit all existing sessions (`tmux kill-server`), and restart `tmux`.
 
 == Why does leaving insert mode take more than half a second in `tmux` ?