From 4aada9c71235f54ec3b6111b29bee4db6c8c3761 Mon Sep 17 00:00:00 2001
From: Gregory Pakosz <gregory.pakosz@gmail.com>
Date: Tue, 14 Mar 2017 14:33:03 +0100
Subject: [PATCH] updated README.me with troubleshooting instructions. Closes
 #56 and #60

---
 README.md | 41 ++++++++++++++++++++++++++++++++++++++---
 1 file changed, 38 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index bdb09a4..06f453a 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@ Installation
 
 Requirements:
 
-  - tmux **`2.1+`** running inside Linux, Mac, OpenBSD or Cygwin
+  - tmux **`>= 2.1`** running inside Linux, Mac, OpenBSD or Cygwin
   - outside of tmux, `$TERM` must be set to `xterm-256color`
 
 To install, run the following from your terminal: (you may want to backup your
@@ -23,11 +23,46 @@ $ ln -s -f .tmux/.tmux.conf
 $ cp .tmux/.tmux.conf.local .
 ```
 
-Then proceed to customize your `~/.tmux.conf.local` copy.
+Then proceed to [customize] your `~/.tmux.conf.local` copy.
+
+[customize]: #enabling-the-powerline-look
 
 If you're a Vim user, setting the `$EDITOR` environment variable to `vim` will
 enable and further customize the vi-style key bindings (see tmux manual).
 
+Troubleshooting
+---------------
+
+ - **I'm running tmux `HEAD` and this don't work properly, what should I do?**
+
+   Please open an issue describing what doesn't work with upcoming tmux. I'll do
+   my best to address it.
+
+ - **Status line is broken and/or gets duplicated at the bottom of the screen.
+   What gives?**
+
+   This particularly happens on Linux when the distribution provides a version
+   of glib that received Unicode 9.0 upgrades (glib `>= 2.50.1`) while providing
+   a version of glibc that didn't (`< 2.26`). You may also configure `LC_CTYPE`
+   to use an `UTF-8` locale. Typically VTE based terminal emulators rely on
+   glib's `g_unichar_iswide()` function while tmux relies on glibc's `wcwidth()`
+   function. When these two functions disagree, display gets messed up.
+
+   This can also happen on MacOS when using iTerm2 and "Use Unicode version 9
+   character widths" is enabled in `Preferences... > Profiles > Text`
+
+   For that reason, the default `/.tmux.conf.local` file stopped using Unicode
+   characters for which width changed in between Unicode 8.0 and 9.0 standards,
+   as well as Emojis.
+
+ - **I installed Powerline and/or (patched) fonts but can't see Powerline
+   symbols.**
+
+   First, you don't need to install Powerline. You only need fonts patched with
+   Powerline symbols or the standalone `PowerlineSymbols.otf` font. Then make
+   sure your `~/.tmux.conf.local` copy uses the right code points for
+   `tmux_conf_theme_left_separator_XXX` values.
+
 Features
 --------
 
@@ -40,7 +75,7 @@ Features
    if available
  - laptop battery status line information
  - uptime status line information
- - optional highlight of focused pane (tmux `2.1+`)
+ - optional highlight of focused pane (tmux `>= 2.1`)
  - configurable new windows and panes behavior (optionally retain current path)
  - SSH aware split pane (reconnects to remote server, experimental)
  - [Facebook PathPicker][] integration if available