added support for configuration files in the following locations:

- ~/.tmux.conf and ~/.tmux.conf.local
- $XDG_CONFIG_HOME/tmux/tmux.conf and $XDG_CONFIG_HOME/tmux/tmux.conf.local
- ~/.config/tmux/tmux.conf and ~/.config/tmux/tmux.conf.local

location of configuration files is determined by the following environment variables:
- TMUX_CONF
- TMUX_CONF_LOCAL

the TMUX_PROGRAM environment variable contains the path to the tmux executable

resolves #200, resolves #221, resolves #439, resolves #586, resolves #624

README.md

@@ -14,9 +14,14 @@ Requirements:
   - awk, perl and sed
   - outside of tmux, `$TERM` must be set to `xterm-256color`
 
-To install, run the following from your terminal: (you may want to backup your
-existing `~/.tmux.conf` first)
+⚠️ Before installing, you may want to backup your existing configuration.
 
+You can install Oh my tmux! at any of the following locations:
+- `~`
+- `$XDG_CONFIG_HOME/tmux`
+- `~/.config/tmux`
+
+Installing in `~`:
 ```
 $ cd
 $ git clone https://github.com/gpakosz/.tmux.git
@@ -24,28 +29,39 @@ $ ln -s -f .tmux/.tmux.conf
 $ cp .tmux/.tmux.conf.local .
 ```
 
-💡 You can clone the repository anywhere you want, provided you create the
-proper `~/.tmux.conf` symlink and you copy the `.tmux.conf.local` sample file in
-your home directory:
-
+Installing in `$XDG_CONFIG_HOME/tmux`:
 ```
-$ git clone https://github.com/gpakosz/.tmux.git /path/to/oh-my-tmux
-$ ln -s -f /path/to/oh-my-tmux/.tmux.conf ~/.tmux.conf
-$ cp /path/to/oh-my-tmux/.tmux.conf.local ~/.tmux.conf.local
+$ git clone https://github.com/gpakosz/.tmux.git "/path/to/oh-my-tmux"
+$ mkdir -p "$XDG_CONFIG_HOME/tmux"
+$ ln -s "/path/to/oh-my-tmux/.tmux.conf" "$XDG_CONFIG_HOME/tmux/tmux.conf"
+$ cp "/path/to/oh-my-tmux/.tmux.conf.local" "$XDG_CONFIG_HOME/tmux/tmux.conf.local"
 ```
 
-Then proceed to [customize] your `~/.tmux.conf.local` copy.
+Installing in `~/.config/tmux`:
+```
+$ git clone https://github.com/gpakosz/.tmux.git "/path/to/oh-my-tmux"
+$ mkdir -p "~/.config/tmux"
+$ ln -s "/path/to/oh-my-tmux/.tmux.conf" "~/.config/tmux/tmux.conf"
+$ cp "/path/to/oh-my-tmux/.tmux.conf.local" "~/.config/tmux/tmux.conf.local"
+```
+⚠️ When installing `$XDG_CONFIG_HOME/tmux` or `~/.config/tmux`, the configuration
+file names don't have a leading `.` character.
 
-[customize]: #configuration
+❗️ You should never alter the main `.tmux.conf` or `tmux.conf` file. If you do,
+you're on your own. Instead, every customization should happen in your
+`.tmux.conf.local` or `tmux.conf.local` customization file copy.
 
 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).
 
-If you're new to tmux, I recommend you read [tmux 2: Productive Mouse-Free
+If you're new to tmux, I recommend you to read [tmux 2: Productive Mouse-Free
 Development][bhtmux2] by [@bphogan].
 
-[bhtmux2]: https://pragprog.com/book/bhtmux2/tmux-2
+Now proceed to [adjust] your `.local` customization file copy.
+
+[bhtmux2]: https://pragprog.com/titles/bhtmux2/tmux-2
 [@bphogan]: https://twitter.com/bphogan
+[adjust]: #configuration
 
 Troubleshooting
 ---------------
@@ -69,23 +85,23 @@ Troubleshooting
    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.
+   For that reason, the default sample `.local` customization 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
+   sure your `.local` customization file copy uses the Powerline code points for
    `tmux_conf_theme_left_separator_XXX` values.
 
- - **I'm using Bash On Windows (WSL), colors and Powerline look are broken.**
+ - **I'm using Bash On Windows (WSL), colors and the Powerline look are broken.**
 
    There is currently a [bug][1681] in the new console powering Bash On Windows
    preventing text attributes (bold, underscore, ...) to combine properly with
-   colors. The workaround is to search your `~/.tmux.conf.local` copy and
+   colors. The workaround is to search your `.local` customization file copy and
    replace attributes with `'none'`.
 
    Also, until Window's console replaces its GDI based render with a DirectWrite
@@ -150,8 +166,8 @@ list of key bindings:
 
 This configuration uses the following bindings:
 
- - `<prefix> e` opens `~/.tmux.conf.local` with the editor defined by the
-   `$EDITOR` environment variable (defaults to `vim` when empty)
+ - `<prefix> e` opens the `.local` customization file copy with the editor
+   defined by the `$EDITOR` environment variable (defaults to `vim` when empty)
  - `<prefix> r` reloads the configuration
  - `C-l` clears both the screen and the tmux history
 
@@ -197,14 +213,16 @@ Configuration
 -------------
 
 While this configuration tries to bring sane default settings, you may want to
-customize it further to your needs. Instead of altering the `~/.tmux.conf` file
-and diverging from upstream, the proper way is to edit the `~/.tmux.conf.local`
-file.
+customize it further to your needs.
 
-Please refer to the sample `.tmux.conf.local` file to know more about variables
-you can adjust to alter different behaviors. Pressing `<prefix> e` will open
-`~/.tmux.conf.local` with the editor defined by the `$EDITOR` environment
-variable (defaults to `vim` when empty).
+❗️ Again, you should never alter the main `.tmux.conf` or `tmux.conf` file.
+If you do, you're on your own.
+
+Please refer to the sample `.local` customization file to know more about the
+variables that allow you to alter different behaviors. Upon successful
+installation, pressing `<prefix> e` will open your `.local` customization file
+copy with the editor defined by the `$EDITOR` environment variable (defaults to
+`vim` when empty).
 
 ### Enabling the Powerline look
 
@@ -226,12 +244,9 @@ To make use of these symbols, there are several options:
 [powerline patched fonts]: https://github.com/powerline/fonts
 [powerline font]: https://github.com/powerline/powerline/raw/develop/font/PowerlineSymbols.otf
 [terminal support]: http://powerline.readthedocs.io/en/master/usage.html#usage-terminal-emulators
-[Powerline manual]: http://powerline.readthedocs.org/en/latest/installation.html#fonts-installation
 
-Please see the [Powerline manual] for further details.
-
-Then edit your `~/.tmux.conf.local` copy (with `<prefix> e`) and adjust the
-following variables:
+Then edit your `.local` customization file copy (with `<prefix> e`) and adjust
+the following variables:
 
 ```
 tmux_conf_theme_left_separator_main='\uE0B0'
@@ -239,12 +254,16 @@ tmux_conf_theme_left_separator_sub='\uE0B1'
 tmux_conf_theme_right_separator_main='\uE0B2'
 tmux_conf_theme_right_separator_sub='\uE0B3'
 ```
+
+The [Powerline manual] contains further details on how to install fonts
+containing the Powerline symbols. You don't need to install Powerline itself
+though.
+
+[Powerline manual]: http://powerline.readthedocs.org/en/latest/installation.html#fonts-installation
+
 ### Configuring the status line
 
-Contrary to the first iterations of this configuration, by now you have total
-control on the content and order of `status-left` and `status-right`.
-
-Edit your `~/.tmux.conf.local` copy (`<prefix> e`) and adjust the
+Edit your `.local` customization file copy (`<prefix> e`) and adjust the
 `tmux_conf_theme_status_left` and `tmux_conf_theme_status_right` variables to
 your own preferences.
 
@@ -272,7 +291,7 @@ This configuration supports the following builtin variables:
  - `#{username_ssh}`: SSH aware username information, blank when not connected
    to a remote server through SSH/Mosh
 
-Beside custom variables mentioned above, the `tmux_conf_theme_status_left` and
+Beside the variables mentioned above, the `tmux_conf_theme_status_left` and
 `tmux_conf_theme_status_right` variables support usual tmux syntax, e.g. using
 `#()` to call an external command that inserts weather information provided by
 [wttr.in]:
@@ -286,8 +305,8 @@ minutes whatever the value of `status-interval`.
 
 [wttr.in]: https://github.com/chubin/wttr.in#one-line-output
 
-💡 You can also define your own custom variables. See the sample
-`.tmux.conf.local` file for instructions.
+💡 You can also define your own custom variables by writing special functions,
+see the sample `.local` customization file for instructions.
 
 Finally, remember `tmux_conf_theme_status_left` and
 `tmux_conf_theme_status_right` end up being given to tmux as `status-left` and
@@ -296,7 +315,7 @@ character has a special meaning and needs to be escaped by doubling it, e.g.
 ```
 tmux_conf_theme_status_right='#(echo foo %% bar)'
 ```
-See `man 3 strftime`.
+See also `man 3 strftime`.
 
 ### Using TPM plugins
 
@@ -305,17 +324,15 @@ This configuration now comes with built-in [TPM] support:
 - whenever a plugin introduces a variable to be used in `status-left` or
   `status-right`, you can use it in `tmux_conf_theme_status_left` and
   `tmux_conf_theme_status_right` variables, see instructions above 👆
-- ⚠️ do not add `set -g @plugin 'tmux-plugins/tpm'`
-- ⚠️ do not add `run '~/.tmux/plugins/tpm/tpm'` to `~/.tmux.conf` or your
-- `~/.tmux.conf.local` copy ← people who are used to alter
-  `.tmux.conf` to add TPM support will have to adapt their configuration
+- ⚠️ do not add `set -g @plugin 'tmux-plugins/tpm'` to any configuration file
+- ⛔️ do not add `run '~/.tmux/plugins/tpm/tpm'` to any configuration file
 
 ⚠️ The TPM bindings differ slightly from upstream:
   - installing plugins: `<prefix> + I`
   - uninstalling plugins: `<prefix> + Alt + u`
   - updating plugins: `<prefix> + u`
 
-See `~/.tmux.conf.local` for instructions.
+See the sample `.local` customization file for instructions.
 
 [TPM]: https://github.com/tmux-plugins/tpm