Add troubleshooting information

Makefile

@@ -48,9 +48,9 @@ RPM_RELEASE = $(word 2,$(RPM_VERLIST))$(if $(WTDIRTY),.dirty)
 DFLAGS	= -g -DDEBUG -Werror -O0
 EXE	= src/tig
 TOOLS	= test/tools/test-graph tools/doc-gen
-TXTDOC	= doc/tig.1.adoc doc/tigrc.5.adoc doc/manual.adoc NEWS.adoc README.adoc INSTALL.adoc test/API.adoc
+TXTDOC	= doc/tig.1.adoc doc/tigrc.5.adoc doc/manual.adoc NEWS.adoc README.adoc TROUBLESHOOTING.adoc INSTALL.adoc test/API.adoc
 MANDOC	= doc/tig.1 doc/tigrc.5 doc/tigmanual.7
-HTMLDOC = doc/tig.1.html doc/tigrc.5.html doc/manual.html README.html INSTALL.html NEWS.html
+HTMLDOC = doc/tig.1.html doc/tigrc.5.html doc/manual.html README.html TROUBLESHOOTING.html INSTALL.html NEWS.html
 ALLDOC	= $(MANDOC) $(HTMLDOC) doc/manual.html-chunked doc/manual.pdf
 
 # Never include the release number in the tarname for tagged
@@ -403,6 +403,9 @@ doc/manual.html: ASCIIDOC_FLAGS += -ainclude-manual-toc
 README.html: README.adoc doc/asciidoc.conf
 	$(QUIET_ASCIIDOC)$(ASCIIDOC) $(ASCIIDOC_FLAGS) -b xhtml11 -d article -a readme $<
 
+TROUBLESHOOTING.html: TROUBLESHOOTING.adoc doc/asciidoc.conf
+	$(QUIET_ASCIIDOC)$(ASCIIDOC) $(ASCIIDOC_FLAGS) -b xhtml11 -d article $<
+
 INSTALL.html: INSTALL.adoc doc/asciidoc.conf
 	$(QUIET_ASCIIDOC)$(ASCIIDOC) $(ASCIIDOC_FLAGS) -b xhtml11 -d article $<
 

README.adoc

@@ -26,6 +26,9 @@ Resources
 
 Bugs and Feature Requests
 -------------------------
+Please check out link:TROUBLESHOOTING.{docext}[the troubleshooting guide]
+if you are experiencing issues with Tig.
+
 Bugs and feature requests can be reported using the
 https://github.com/jonas/tig/issues[issue tracker] or by mail to either
 the Git mailing list or directly to the maintainer. Ensure that the word

TROUBLESHOOTING.adoc

@@ -0,0 +1,97 @@
+Troubleshooting
+===============
+:docext: adoc
+
+Display
+-------
+
+Tig is based on ncurses and relies on the terminal characteristics
+stored in the terminfo database. If you are lying about the capabilities
+of your terminal, you cannot expect Tig to work properly.
+
+ncursesw
+~~~~~~~~
+
+If you did not compile Tig with `ncursesw` (or default `ncurses` on
+macOS) then Unicode characters cannot be displayed.
+
+To make sure which ncurses version you are using, first confirm
+which `tig` executable you are running and then use `ldd -r` (Linux) or
+`otool -L` (macOS).
+
+If mouse scroll down does not work, check that ncurses was compiled
+with `--enable-ext-mouse`. See https://bugs.debian.org/838376 for
+more details.
+
+TERM
+~~~~
+
+The `TERM` variable must be set in accordance with your terminal type.
+
+If you are using a terminal multiplexer like GNU screen or tmux (but not
+dtach), then the `TERM` variable *before* starting the terminal multiplexer
+must be set in accordance with your terminal type and the `TERM` variable
+*inside* the terminal multiplexer must be set to `screen` or any
+compatible variant.
+
+You can check with `infocmp` that you have the proper entry for your
+terminal type in your terminfo database.
+If you want to use an alternate terminfo database, you can use
+`export TERMINFO=/path/to/terminfo`.
+
+Some OS (e.g. OS X 10.11) are shipping with an incomplete terminfo
+description for screen resulting, for example, in the diff-highlight
+option not working when running Tig inside screen/tmux. It can be
+fixed locally (for the current user) with:
+```
+curl -O https://invisible-island.net/datafiles/current/terminfo.src.gz
+gunzip terminfo.src
+tic -x -o "$HOME/.terminfo" -e screen terminfo.src
+```
+
+Note that macOS still comes with and old version of ncurses (5.7) which
+may not work well with newer 256-color terminfo entries.
+
+Note that while PuTTY identifies itself by default as `xterm`, it is
+not fully compatible with it. If you have problems with the keyboard
+mapping (e.g. Home/End), try to use `putty` instead. Check out
+https://invisible-island.net/xterm/xterm.faq.html#known_bugs[XTerm FAQ]
+for more details and information on other terminal emulators.
+
+LANG
+~~~~
+
+The `LANG` variable must be set in accordance with your terminal
+encoding settings. If the `LANG` variable is not properly set,
+accented characters will be distorted.
+
+Use `locale -a` to check if your `LANG` variable is present in the
+list of available locales (on Linux, you may find that `UTF-8` has
+been substituted for `utf8` but they are equivalent).
+
+Note that the ability to set the `LANG` variable to values such as
+`en_DE` with KDE does not imply their validity.
+
+Also check the `LC_ALL` variable as it has precedence over `LANG`.
+
+ESCDELAY
+~~~~~~~~
+
+See ESCDELAY environment variable in ncurses(3x) to reduce the one
+second delay after pressing the escape key. Nowadays,
+`export ESCDELAY=100` should be more than enough.
+
+Git
+---
+
+Tig relies entirely on Git to access your repository data. If Tig fails
+to show any commit, first check the corresponding `git log` command. To
+find out which options Tig is using, try `TIG_TRACE=/tmp/tig.log tig`.
+
+Note that Tig's command line parser is not as permissive as that of Git.
+For example, arguments such as -S/-G or --grep must be passed without
+space:
+```
+tig -G"<string>"
+tig --grep="<string>"
+```

book.md

@@ -2,6 +2,7 @@
 
  - [Installation](INSTALL.adoc)
  - [Release notes](NEWS.adoc)
+ - [Troubleshooting](TROUBLESHOOTING.adoc)
  - [tig(1)](doc/tig.1.adoc)
  - [tigrc(5)](doc/tigrc.5.adoc)
  - [Manual](doc/manual.adoc)

contrib/tig.spec.in

@@ -48,7 +48,7 @@ CFLAGS="$RPM_OPT_FLAGS -DVERSION=tig-%{version}-%{release}"
 %defattr(-,root,root)
 %{_bindir}/*
 %{_sysconfdir}/*
-%doc README.adoc COPYING INSTALL.adoc NEWS.adoc contrib/tig-completion.bash contrib/tig-completion.zsh
+%doc README.adoc COPYING TROUBLESHOOTING.adoc INSTALL.adoc NEWS.adoc contrib/tig-completion.bash contrib/tig-completion.zsh
 %{!?_without_docs: %{_mandir}/man1/*.1*}
 %{!?_without_docs: %{_mandir}/man5/*.5*}
 %{!?_without_docs: %{_mandir}/man7/*.7*}