TTY Office: tmux
================

According to the official tmux wiki, "tmux is a terminal multiplexer. 
It lets you switch easily between several programs in one terminal, 
detach them (they keep running in the background) and reattach them to 
a different terminal." (https://github.com/tmux/tmux/wiki)

More colloquially, tmux provides "windowing" on the command line, 
allowing the user to have multiple programs open and visible at the 
same time. It's indispensable when working with several documents at 
once. 

There's a "Getting Started with tmux" guide here:
https://github.com/tmux/tmux/wiki/Getting-Started

When reading the tmux documentation, think of "panes" as windows and 
"windows" as desktops.


Part I: Selecting Text 
----------------------

For me, the major obstacle to adopting tmux for my office setup was 
that tmux broke the regular SHIFT-arrow key combinations for selecting 
text in the nano and micro text editors.

I found the solution to this problem here:
https://github.com/micro-editor/micro/issues/2443#issuecomment-1233373047 

Create a file containing the following script. Mine's called 
shift-to-select.sh (note that there is commented out code in this 
script that I'll discuss below).

#!/bin/bash

tmp=$(mktemp)

cat >$tmp <<EOL
# Right
control keycode 106 = F100
shift keycode 106 = F101
control shift keycode 106 = F102
# Left
control keycode 105 = F103
shift keycode 105 = F104
control shift keycode 105 = F105
# Up
shift keycode 103 = F106
# Down
shift keycode 108 = F107
# Set Winkey (Super key) as backtick
#keycode 125 = F108

string F100 = "\033[1;5C"
string F101 = "\033[1;2C"
string F102 = "\033[1;6C"
string F103 = "\033[1;5D"
string F104 = "\033[1;2D"
string F105 = "\033[1;6D"
string F106 = "\033[1;2A"
string F107 = "\033[1;2B"
#string F108 = "\`"

EOL

sudo loadkeys "$tmp"


Make the file executable: chmod +x shift-to-select.sh

After executing the script, text selection should work properly in 
nano and micro while using tmux. However, the change is not persistent 
between boots. To make sure it runs every time on my pi zero w, I 
added the script to root's crontab, since it requires root permissions 
to run.

If you haven't used crontab before, you should look it up before 
proceeding further. But the essential steps are:

1. login as root.

2. enter this command: crontab -e

3. add the following line to the bottom of the file:

@reboot /path/to/shift-to-select.sh


Replace "/path/to" with the actual path to your file's location.

I'm sure there are other ways to do this, but I wanted one that I 
understood and that would be easy to reverse if necessary. So far, I 
haven't bumped into any problems as a result of remapping the key 
combinations in this manner.


Part II: Custom Navigation
--------------------------

Navigation between panes and windows in tmux is done by means of key 
combinations. Other essential functions are executed in the same 
manner. First, the user enters 'command mode' by pressing a 'prefix' 
key or combination of keys (ctrl-b is the default) and then the user 
presses another key or combination of keys, such as the right arrow to 
move one pane to the right.

For my TTY office setup, I've customized the keyboard shortcuts by 
creating a custom .tmux.conf file, which is at the bottom of this 
page. The section preceding the file describes each of the custom 
keyboard shortcuts and a few default shortcuts that I use regularly.

You don't need to customize the keyboard shortcuts in tmux, but if you 
want to, my setup should provide a sense of what's possible.

As noted above, the default key combination to enter command mode is 
ctrl-b. Pressing ctrl-b all the time is awkward, so I use the ` 
(backtick) key to enter command mode instead. You can still type a 
backtick by pressing the button twice.

If you want to use the windows (super) key to enter command mode, you 
can set the backtick as the command prefix and then map the windows 
key to the backtick. To do so, uncomment these two lines in the 
shift-to-select.sh script above, and use it in combination with the 
.tmux.conf script at the bottom of this page:

   #keycode 125 = F108
   #string F108 = "\`"

To uncomment the lines, remove the octothorpe (number sign) at the 
beginning of each line.[1]

For all keyboard shortcuts below, press one key, release it, and then 
press the other. Do not hold down backtick and press the accompanying 
key at the same time.

Navigate between panes (non-traditional bindings):
   ` + arrow key
    or
   `j         left
   `k         right      I like being able to hit ` with one hand and
   `h         up         navigate from the home row with the other.
   `l         down
   ` + Tab    cycle      Alt-Tab style pane switching

Toggle a pane to fullscreen:
   `i         toggle fullscreen and back
              (the default for zooming is 'z', but 'i' is conveniently 
              above the home row. I think of it as 'i' for zoom 'IN'.)               

Split a pane:
   `| or `\   split pane horizontally
   `_ or `-   split pane vertically

Close a pane:
   quit any programs and type exit at the prompt

Copy and paste within and between windows / panes: 
   `[         enter copy mode
   While in copy mode:
      Arrow keys   navigate
      [            start selection
      ]            copy selection to buffer and exit copy mode
   `]         paste from buffer 

(Think of this custom copy and paste sequence as double bracketing the 
text that you want to copy and paste.)

Additional:
   `?         list keybindings
   `r         reload tmux configuration on the fly


To use this configuration, save the following lines to .tmux.conf in 
your home directory. Just delete anything you don't like and add 
anything you prefer.


# Change prefix
unbind C-b
set -g prefix `
bind ` send-prefix

# Switch panes
bind h select-pane -U
bind j select-pane -L
bind k select-pane -R
unbind l
bind l select-pane -D

# Cycle through panes Alt-Tab style
bind -r Tab select-pane -t :.+

# List shortcuts
bind ? list-keys
bind / list-keys -a

# Zoom a pane
unbind i
bind i resize-pane -Z

# Copy and paste with [[]]
bind -T copy-mode [ send-keys -X begin-selection
bind -T copy-mode ] send-keys -X copy-pipe-and-cancel

# Split panes with | and -
bind | split-window -h
bind \\ split-window -h
unbind -
bind - split-window -v
bind _ split-window -v

# Reload config with r
unbind r
bind r source-file ~/.tmux.conf \; display "Config reloaded!"

# bar position and color
set -g status-position top
set -g status-style bg=blue


In the next installation of this series, I'll discuss setting fonts 
and font sizes in a TTY and creating custom tty fonts from your 
favourite TrueType fonts.


----------------

[1] If the WIN key fails to activate command mode after setting up the 
    scripts, it may be that it is not key 125 on your keyboard. To 
    check, type "showkey" (without the quotation marks) at the command 
    prompt and then press the windows key. Record the number and wait 
    10 seconds for showkey to exit. Edit the shift-to-select.sh file, 
    replacing "125" in the line

        keycode 125 = F108

    with your WIN key's number.