Remove a bunch of out-of-date stuff from the FAQ or stuff that is documentation

for other programs.

FAQ

@@ -14,135 +14,55 @@ tmux frequently asked questions
 
 * How is tmux different from GNU screen?
 
-tmux and GNU screen have many similarities. Some of the main differences I am
-aware of are (bearing in mind I haven't used screen for a few years now):
+tmux and GNU screen have many similarities and similar goals but now many
+differences. Most things that can be achieved one can be achieved in the other,
+however.
 
-- tmux uses a client-server model. Each server has single Unix domain socket in
-  /tmp and within one server there are multiple sessions which may be attached
-  to multiple clients (terminals).
+* What is TERM and what does it do?
 
-  This has advantages, notably: windows may be linked simultaneously to
-  multiple sessions; windows may be moved freely between sessions; and a client
-  may be switched between sessions easily (C-b D). There is one major
-  disadvantage: if the server crashes, game over, all sessions die. In
-  practice, however, tmux is quite stable and gets more so as people report any
-  bugs they hit :-).
+The environment variable TERM tells applications the name of a terminal
+description to read from the terminfo(5) database. Each description consists of
+a number of named capabilities which tell applications what to send to control
+the terminal. For example, the "cup" capability contains the escape sequence
+used to move the cursor up.
 
-  This model is different from screen, where typically each new screen instance
-  is independent. tmux supports the same behaviour by using multiple servers
-  with the -L option but it is not typically recommended.
+It is important that TERM points to the correct description for the terminal an
+application is running in - if it doesn't, applications may misbehave. 
 
-- Different command interfaces. One of the goals of tmux is that the shell
-  should be easily usable as a scripting language - almost all tmux commands
-  can be used from the shell and behave identically whether used from the
-  shell, from a key binding or from the command prompt. Personally I also find
-  tmux's command interface much more consistent and clearer, but this is
-  subjective.
+The infocmp(1) command shows the contents of a terminal description and the
+tic(1) command builds and installs a description from a file (the -x flag is
+normally required with both).
 
-- tmux calls window names (what you see in the status line) "names", screen
-  calls them "titles".
-
-- tmux has a multiple paste buffers. Not a major one but comes in handy quite a
-  lot.
-
-- tmux supports automatically renaming windows to the running application
-  without gross hacks using escape sequences. Its even on by default.
-
-- tmux has a choice of vi or emacs key layouts. Again, not major, but I use
-  emacs so if tmux did support only one key set it would be emacs and then all
-  the vi users would get humpy. Key bindings may be completely reconfigured in
-  any case.
-
-- tmux has an option to limit the window size.
-
-- tmux has search in windows (C-b f).
-
-- The window split (pane) model is different. tmux has two objects, windows and
-  panes; screen has just windows. This difference has several implications:
-
-  * In screen you can have a window appear in several layouts, in tmux a pane
-  can only be in one window (fixing this is a big todo item but quite
-  invasive).
-
-  * tmux layouts are immutable and do not get changed unless you modify them.
-
-  * In tmux, all panes are closed when you kill a window.
-
-  * tmux panes do not have individual names, titles and so on.
-
-  I think tmux's model is much easier to manage and navigate within a window,
-  but breaking panes off from and joining them to windows is more clumsy.
-
-  tmux also has support for preset pane layouts.
-
-- tmux's status line syntax is more readable and easier to use. I think it'd be
-  hard for anyone to argue with this. tmux doesn't support running a command
-  constantly and always using the last line of its output, commands must be run
-  again each time.
-
-- tmux has modern, easily extended code. Again hard to argue screen is better
-  if you have looked at the code.
-
-- tmux depends on libevent. I don't see this as a disadvantage: libevent is
-  small and portable, and on modern systems with current package management
-  systems dependencies are not an issue. libevent brings advantages in code
-  simplicity and performance.
-
-- screen allows the window to be bigger than the terminal and can pan around
-  it. tmux limits the size to the largest attached client. This is a big todo
-  item for tmux but it is not trivial.
-
-- screen has builtin serial and telnet support; this is bloat and is unlikely
-  to be added to tmux.
-
-- Environment handling is different.
-
-- tmux tends to be more demanding on the terminal so tends to show up terminal
-  and application bugs which screen does not.
-
-- screen has wider platform support, for example IRIX, and for odd terminals.
-
-* I found a bug! What do I do?
+* I found a bug in tmux! What do I do?
 
 Check the latest version of tmux from Git to see if the problem is still
-reproducible.  Sometimes the length of time between releases means a lot of
-fixes can be sitting in Git and the problem might already be fixed.
+present.
 
 Please send bug reports by email to nicholas.marriott@gmail.com or
-tmux-users@googlegroups.com. Please include as much of the following
-information as possible:
-
-- the version of tmux you are running;
-- the operating system you are using and its version;
-- the terminal emulator you are using and the TERM setting when tmux was
-  started;
-- a description of the problem;
-- if the problem is repeatable, the steps to repeat the problem;
-- for screen corruption issues, a screenshot and the output of "infocmp $TERM"
-  from outside tmux are often very useful.
+tmux-users@googlegroups.com or by opening a GitHub issue. Please see the
+CONTRIBUTING file for information on what to include.
 
 * Why doesn't tmux do $x?
 
 Please send feature requests by email to tmux-users@googlegroups.com.
 
-* Why do you use the screen terminal description inside tmux? It sucks.
+* Why do you use the screen terminal description inside tmux?
 
-It is already widely available. It is planned to change to something else such
-as xterm-xfree86 at some point, if possible.
+It is already widely available. tmux and tmux-256color entries are provided by
+modern ncurses and can be used instead by setting the default-terminal option.
 
 * I don't see any colour in my terminal! Help!
 
-On some platforms, common terminal descriptions such as xterm do not include
+On a few platforms, common terminal descriptions such as xterm do not include
 colour. screen ignores this, tmux does not. If the terminal emulator in use
 supports colour, use a value for TERM which correctly lists this, such as
 xterm-color.
 
-* tmux freezes my terminal when I attach to a session. I even have to kill -9
-  the shell it was started from to recover!
+* tmux freezes my terminal when I attach to a session. I have to kill -9 the
+  shell it was started from to recover!
 
-Some consoles really really don't like attempts to set the window title. Tell
-tmux not to do this by turning off the "set-titles" option (you can do this
-in .tmux.conf):
+Some consoles don't like attempts to set the window title. Tell tmux not to do
+this by turning off the "set-titles" option (you can do this in .tmux.conf):
 
 	set -g set-titles off
 
@@ -151,13 +71,11 @@ If this doesn't fix it, send a bug report.
 * Why is C-b the prefix key? How do I change it?
 
 The default key is C-b because the prototype of tmux was originally developed
-inside screen and C-b was chosen not to clash with the screen meta key. It
-also has the advantage of not interfering with the use of C-a for start-of-line
-in emacs and the shell (although it does interfere with previous-character).
+inside screen and C-b was chosen not to clash with the screen meta key.
 
-Changing is simple: change the "prefix-key" option, and - if required - move
-the binding of the "send-prefix" command from C-b (C-b C-b sends C-b by
-default) to the new key. For example:
+To change it, change the "prefix" option, and - if required - move the binding
+of the "send-prefix" command from C-b (C-b C-b sends C-b by default) to the new
+key. For example:
 
 	set -g prefix C-a
 	unbind C-b
@@ -165,120 +83,39 @@ default) to the new key. For example:
 
 * How do I use UTF-8?
 
-When running tmux in a UTF-8 capable terminal, UTF-8 must be turned on in tmux;
-as of release 0.9, tmux attempts to autodetect a UTF-8-capable terminal by
-checking the LC_ALL, LC_CTYPE and LANG environment variables. list-clients may
-be used to check if this is detected correctly; if not, the -u command-line
-flag may be specified when creating or attaching a client to a tmux session:
+tmux requires a system that supports UTF-8 (that is, where the C library has a
+UTF-8 locale) and will not start if support is missing.
+
+tmux will attempt to detect if the terminal it is running in supports UTF-8 by
+looking at the LC_ALL, LC_CTYPE and LANG environment variables.
+
+If it believes the terminal is not compatible with UTF-8, any UTF-8 characters
+will be replaced with underscores. The -u flag explicitly tells tmux that the
+terminal supports UTF-8:
 
 	$ tmux -u new
 
-Since the 1.0 release, tmux will turn on UTF-8 related options automatically
-(ie status-utf8, and utf8) if the above conditions are met.
-
 * How do I use a 256 colour terminal?
 
 Provided the underlying terminal supports 256 colours, it is usually sufficient
-to add the following to ~/.tmux.conf:
+to add one of the following to ~/.tmux.conf:
 
 	set -g default-terminal "screen-256color"
 
-Note that some platforms do not support "screen-256color" ("infocmp
-screen-256color" will return an error) - in this case see the next entry in
-this FAQ.
+Or:
 
-tmux attempts to detect a 256 colour terminal both by looking at the colors
-terminfo entry and by looking for the string "256col" in the TERM environment
-variable.
+	set -g default-terminal "tmux-256color"
 
-If both these methods fail, the -2 flag may be passed to tmux when attaching
-to a session to indicate the terminal supports 256 colours.
+And make sure that TERM outside tmux also shows 256 colours, or use the tmux -2
+flag.
 
-* vim or $otherprogram doesn't display 256 colours. What's up?
+* How do I make Ctrl-PgUp and Ctrl-PgDn work inside tmux?
 
-Some programs attempt to detect the number of colours a terminal is capable of
-by checking the colors terminfo or Co termcap entry. However, this is not
-reliable, and in any case is missing from the "screen" terminal description
-used inside tmux.
-
-There are two options (aside from using "screen-256color") to allow programs to
-recognise they are running on a 256-colour terminal inside tmux:
-
-- Manually force the application to use 256 colours always or if TERM is set to
-  screen. For vim, you can do this by overriding the t_Co option, see
-  http://vim.wikia.com/wiki/256_colors_in_vim.
-- Creating a custom terminfo file that includes colors#256 in ~/.terminfo and
-  using it instead. These may be compiled with tic(1).
-
-* How do I make Ctrl-PgUp and Ctrl-PgDn work in vim?
-
-tmux supports passing through ctrl (and where supported by the client terminal,
-alt and shift) modifiers to function keys using xterm(1)-style key sequences.
-This may be enabled per window, or globally with the tmux command:
-
-	setw -g xterm-keys on
-
-Because the TERM variable inside tmux must be set to "screen", vim will not
-automatically detect these keys are available; however, the appropriate key
-sequences can be overridden in .vimrc using the following:
-
-	if &term == "screen"
-	set t_kN=^[[6;*~
-	set t_kP=^[[5;*~
-	endif
-
-And similarly for any other keys for which modifiers are desired.
-
-Please note that the "xterm-keys" setting may affect other programs, in the
-same way as running them in a standard xterm; for example most shells do not
-expect to receive xterm(1)-style key sequences so this setting may prevent keys
-such as ctrl-left and ctrl-right working correctly. tmux also passes through
-the ctrl (bit 5 set, for example ^[[5~ to ^[[5^) modifier in non-xterm(1) mode;
-it may be possible to configure vim to accept these, an example of how to do so
-would be welcome.
-
-vim users may also want to set the "ttyfast" option inside tmux.
-
-* How do I make ctrl and shift arrow keys work in emacs?
-
-The terminal-init-screen function in term/screen.el is called for new frames,
-but it doesn't configure any function keys.
-
-If the tmux xterm-keys option is on, it is enough to define the same keys as
-xterm. Add the following to init.el or .emacs to do this:
-
-(defadvice terminal-init-screen
-  ;; The advice is named `tmux', and is run before `terminal-init-screen' runs.
-  (before tmux activate)
-  ;; Docstring.  This describes the advice and is made available inside emacs;
-  ;; for example when doing C-h f terminal-init-screen RET
-  "Apply xterm keymap, allowing use of keys passed through tmux."
-  ;; This is the elisp code that is run before `terminal-init-screen'.
-  (if (getenv "TMUX")
-    (let ((map (copy-keymap xterm-function-map)))
-    (set-keymap-parent map (keymap-parent input-decode-map))
-    (set-keymap-parent input-decode-map map))))
-
-And ensure .tmux.conf contains "set -g xterm-keys on".
-
-Alternatively, the screen.el file can be copied to the load path and
-customized.
-
-* Why doesn't elinks set the window title inside tmux?
-
-There isn't a way to detect if a terminal supports setting the window title, so
-elinks attempts to guess by looking at the environment. Rather than looking for
-TERM=screen, it uses the STY variable to detect if it is running in screen;
-tmux does not use this so the check fails. A workaround is to set STY before
-running elinks.
-
-The following shell function does this, and also clears the window title on
-exit (elinks, for some strange reason, sets it to the value of TERM):
-
-	elinks() {
-        	STY= `which elinks` $*
-	        echo -ne \\033]0\;\\007;
-	}
+tmux sends modified function keys using xterm(1)-style escape
+sequences. However, many applications don't accept these when TERM is set to
+screen or screen-256color inside tmux because these terminal descriptions lack
+the capabilities for modified function keys. The tmux and tmux-256color
+descriptions do have such capabilities, so using those instead may work.
 
 * What is the proper way to escape characters with #(command)?
 
@@ -301,14 +138,6 @@ Automatic window renaming may use a lot of CPU, particularly on slow computers:
 if this is a problem, turn it off with "setw -g automatic-rename off". If this
 doesn't fix it, please report the problem.
 
-* I use PuTTY and my tmux window pane separators are all qqqqqqqqq's! 
-
-PuTTY is using a character set translation that doesn't support ACS line
-drawing. With a Unicode font, try setting PuTTY to use a different translation
-on the Window -> Translation configuration page. For example, change UTF-8 to
-ISO-8859-1 or CP437. It may also be necessary to adjust the way PuTTY treats
-line drawing characters in the lower part of the same configuration page.
-
 * What is the best way to display the load average? Why no #L?
 
 It isn't possible to get the load average portably in code and it is preferable
@@ -324,85 +153,18 @@ One or more of the windows can be linked into multiple sessions manually with
 link-window, or a grouped session with all the windows can be created with
 new-session -t.
 
-* Ctrl and arrow keys doesn't work in putty! What do I do?
+* I don't see italics! Or italics and reverse are the wrong way round!
 
-putty inverts the sense of the cursor key mode on ctrl, which is a bit hard for
-tmux to detect properly. To get ctrl keys right, change the terminfo settings
-so kUP5 (Ctrl-Up etc) are the adjusted versions, and disable smkx/rmkx so tmux
-doesn't change the mode. For example with this line in .tmux.conf (assuming you
-have TERM set to xterm):
-
-set -g terminal-overrides "xterm*:kLFT5=\eOD:kRIT5=\eOC:kUP5=\eOA:kDN5=\eOB:smkx@:rmkx@"
-
-Note that this will only work in tmux 1.2 and above.
-
-* How can I blank the tmux window?
-
-GNU screen has a feature whereby it will blank the screen after a period of
-inactivity. To do the same thing in tmux, use the lock-command setting, for
-example (with GNU bash):
-
-set -g lock-command 'tput civis && read -s -n1'
-
-This will remove the cursor and tell the shell to quit once a key has been
-pressed. For zsh, use "read -s -k1".
-
-In addition, it's possible to have both blanking and locking (for instance via
-lock(1) or vlock(1)) by using the following:
-
-bind x set lock-command '/usr/bin/vlock' \; lock-client \; set lock-command 'tput civis && read -s -n1'
-
-* I don't see italics! Or less and vim show italics and reverse the wrong way round!
-
-GNU screen does not support italics and the "screen" terminfo description uses
+GNU screen does not support italics and the "screen" terminal description uses
 the italics escape sequence incorrectly.
 
 As of tmux 2.1, if default-terminal is set to "screen" or matches "screen-*",
 tmux will behave like screen and italics will be disabled.
 
-To enable italics, create a new terminfo entry called "tmux" (some platforms
-may already have this, you can check with "infocmp tmux"):
-
-	$ cat <<EOF|tic -x -
-	tmux|tmux terminal multiplexer,
-		ritm=\E[23m, rmso=\E[27m, sitm=\E[3m, smso=\E[7m, Ms@,
-		use=xterm+tmux, use=screen,
-
-	tmux-256color|tmux with 256 colors,
-		use=xterm+256setaf, use=tmux,
-	EOF
-	$
-
-And tell tmux to use it in ~/.tmux.conf:
+To enable italics, make sure you are using the tmux terminal description:
 	
 	set -g default-terminal "tmux"
 
-If using urxvt, make sure you have an italics capable font enabled. for
-example, add to ~/.Xdefaults:
-
-	urxvt.italicFont: xft:Bitstream Vera Sans Mono:italic:autohint=true
-
-* How can I make tmux use my terminal's scrollback buffer?
-
-Normally, tmux enables the terminal's "alternate screen". Most terminals (such
-as xterm) do not save scrollback for the alternate screen. You might prefer
-tmux to use the normal screen, so it uses your terminal's scrollback
-buffer. This way, you can access the scrollback buffer as usual, for example
-using the mouse wheel - although there is no guarantee output inside tmux will
-always (or ever) be added to the scrollback.
-
-You can make tmux use the normal screen by telling it that your terminal does
-not have an alternate screen. Put the following in ~/.tmux.conf:
-
-        set -ga terminal-overrides ',xterm*:smcup@:rmcup@'
-
-Adjust if your $TERM does not start with xterm.
-
-tmux will still emulate the alternate screen for applications run under tmux,
-so you don't really lose anything with this setting. The only disadvantage is
-that when you exit tmux, it will not restore whatever was there before you
-started.
-
 * How do I see the default configuration?
 
 Show the default session options by starting a new tmux server with no
@@ -417,8 +179,8 @@ Or the default window options:
 * How do I copy a selection from tmux to the system's clipboard?
 
 When running in xterm(1), tmux can automatically send copied text to the
-clipboard. This is controlled by the set-clipboard option and also needs this
-X resource to be set:
+clipboard. This is controlled by the set-clipboard option and also needs this X
+resource to be set:
 
 	XTerm*disallowedWindowOps: 20,21,SetXprop
 
@@ -436,16 +198,6 @@ Or for inside and outside copy mode with the prefix key:
 
 On OS X, look at the pbcopy(1) and pbpaste(1) commands.
 
-* Why don't some commands work inside tmux on OS X?
-
-Apple requires some undocumented, unsupported fiddling to allow commands that
-interact with the GUI to work. Neither tmux itself nor most shells do this, so
-an external program is required. This can be found here:
-
-        https://github.com/ChrisJohnsen/tmux-MacOSX-pasteboard
-
-Affected commands may include say(1), pbcopy(1), pbpaste(1) and ssh(1).
-
 * Why do I see dots around a session when I attach to it?
 
 tmux limits the size of the window to the smallest attached session. If