README.rst
1 Introduction 2 ============ 3 4 mtm is the Micro Terminal Multiplexer, a terminal multiplexer. 5 6 It has four major features/principles: 7 8 Simplicity 9 There are only a few commands, two of which are hardly ever used. 10 There are no modes, no dozens of commands, no crazy feature list. 11 12 Compatibility 13 mtm emulates a classic ANSI text terminal. That means it should 14 work out of the box on essentially all terminfo/termcap-based systems 15 (even pretty old ones), without needing to install a new termcap entry. 16 17 Size 18 mtm is small. 19 The entire project is around 1000 lines of code. 20 21 Stability 22 mtm is "finished" as it is now. You don't need to worry about it 23 changing on you unexpectedly. The only changes that can happen at 24 this point are: 25 26 - Bug fixes. 27 - Translation improvements. 28 - Accessibility improvements. 29 - Fixes to keep it working on modern OSes. 30 31 Community 32 ========= 33 34 Rob posts updates about mtm on Twitter at http://twitter.com/TheKingAdRob. 35 36 Installation 37 ============ 38 Installation and configuration is fairly simple: 39 40 - You need ncursesw. 41 If you want to support terminal resizing, ncursesw needs to be 42 compiled with its internal SIGWINCH handler; this is true for most 43 precompiled distributions. Other curses implementations might work, 44 but have not been tested. 45 - Edit the variables at the top of the Makefile if you need to 46 (you probably don't). 47 - If you want to change the default keybindings or other compile-time flags, 48 copy `config.def.h` to `config.h` and edit the copy. Otherwise the build 49 process will use the defaults. 50 - Run:: 51 52 make 53 54 or:: 55 56 make CURSESLIB=curses 57 58 or:: 59 60 make HEADERS='-DNCURSESW_INCLUDE_H="<ncurses.h>"' 61 62 whichever works for you. 63 - Run `make install` if desired. 64 65 Usage 66 ===== 67 68 Usage is simple:: 69 70 mtm [-T NAME] [-t NAME] [-c KEY] 71 72 The `-T` flag tells mtm to assume a different kind of host terminal. 73 74 The `-t` flag tells mtm what terminal type to advertise itself as. 75 Note that this doesn't change how mtm interprets control sequences; it 76 simply controls what the `TERM` environment variable is set to. 77 78 The `-c` flag lets you specify a keyboard character to use as the "command 79 prefix" for mtm when modified with *control* (see below). By default, 80 this is `g`. 81 82 Once inside mtm, things pretty much work like any other terminal. However, 83 mtm lets you split up the terminal into multiple virtual terminals. 84 85 At any given moment, exactly one virtual terminal is *focused*. It is 86 to this terminal that keyboad input is sent. The focused terminal is 87 indicated by the location of the cursor. 88 89 The following commands are recognized in mtm, when preceded by the command 90 prefix (by default *ctrl-g*): 91 92 Up/Down/Left/Right Arrow 93 Focus the virtual terminal above/below/to the left of/to the right of 94 the currently focused terminal. 95 96 o 97 Focus the previously-focused virtual terminal. 98 99 h / v 100 Split the focused virtual terminal in half horizontally/vertically, 101 creating a new virtual terminal to the right/below. The new virtual 102 terminal is focused. 103 104 w 105 Delete the focused virtual terminal. Some other nearby virtual 106 terminal will become focused if there are any left. mtm will exit 107 once all virtual terminals are closed. Virtual terminals will also 108 close if the program started inside them exits. 109 110 l 111 Redraw the screen. 112 113 PgUp/PgDown/End 114 Scroll the screen back/forward half a screenful, or recenter the 115 screen on the actual terminal. 116 117 That's it. There aren't dozens of commands, there are no modes, there's 118 nothing else to learn. 119 120 (Note that these keybindings can be changed at compile time.) 121 122 Screenshots 123 ----------- 124 mtm running three instances of `tine <https://github.com/deadpixi/tine>`_ 125 126 .. image:: screenshot2.png 127 128 mtm running various other programs 129 130 .. image:: screenshot.png 131 132 mtm showing its compatibility 133 134 .. image:: vttest1.png 135 .. image:: vttest2.png 136 137 Compatibility 138 ============= 139 (Note that you only need to read this section if you're curious. mtm should 140 just work out-of-the-box for you, thanks to the efforts of the various 141 hackers over the years to make terminal-independence a reality.) 142 143 By default, mtm advertises itself as a `screen-bce` terminal. This is what `GNU 144 screen` and `tmux` advertise themselves as, and is a well-known terminal 145 type that has been in the default terminfo database for decades. 146 147 (Note that this should not be taken to imply that anyone involved in the 148 `GNU screen` or `tmux` projects endorses or otherwise has anything to do 149 with mtm, and vice-versa. Their work is excellent, though, and you should 150 definitely check it out.) 151 152 The (optional!) `mtm` Terminal Types 153 ------------------------ 154 mtm comes with a terminfo description file called mtm.ti. This file 155 describes all of the features supported by mtm. 156 157 If you want to install this terminal type, use the `tic` compiler that 158 comes with ncurses:: 159 160 tic -s -x mtm.ti 161 162 or simply:: 163 164 make install-terminfo 165 166 This will install the following terminal types: 167 168 mtm 169 This terminal type supports all of the features of mtm, but with 170 the default 8 "ANSI" colors only. 171 172 mtm-256color 173 Note that mtm is not magic and cannot actually display more colors 174 than the host terminal supports. 175 176 mtm-noutf 177 This terminal type supports everything the mtm terminal type does, 178 but does not advertise UTF8 capability. 179 180 That command will compile and install the terminfo entry. After doing so, 181 calling mtm with `-t mtm`:: 182 183 mtm -t mtm 184 185 will instruct programs to use that terminfo entry. 186 You can, of course, replace `mtm` with any of the other above terminal 187 types. 188 189 Using these terminfo entries allows programs to use the full power of mtm's 190 terminal emulation, but it is entirely optional. A primary design goal 191 of mtm was for it to be completely usable on systems that didn't have the 192 mtm terminfo entry installed. By default, mtm advertises itself as the 193 widely-available `screen-bce` terminal type. 194 195 Copyright and License 196 ===================== 197 198 Copyright 2016-2019 Rob King <jking@deadpixi.com> 199 200 This program is free software: you can redistribute it and/or modify 201 it under the terms of the GNU General Public License as published by 202 the Free Software Foundation, either version 3 of the License, or 203 (at your option) any later version. 204 205 This program is distributed in the hope that it will be useful, 206 but WITHOUT ANY WARRANTY; without even the implied warranty of 207 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 208 GNU General Public License for more details. 209 210 You should have received a copy of the GNU General Public License 211 along with this program. If not, see <http://www.gnu.org/licenses/>. 212