mtm.1

.Dd $Mdocdate$
.Dt MTM 1
.Os
.Sh NAME
.Nm mtm
.Nd a micro-terminal multiplexer
.Sh SYNOPSIS
.Nm
.Op Fl T Ar HOST
.Op Fl t Ar TERM
.Op Fl c Ar CHARACTER
.Sh DESCRIPTION
.Nm
is a terminal multiplexer,
a program that allows multiple terminal sessions to run within a single
(physical or virtual)
terminal session.
.Pp
The options are
.Bl -tag -width Ds
.It Fl T Ar HOST
Assume that the host terminal
.Po
i.e. the terminal under which
.Nm
is running
.Pc
is of type
.Ar HOST "."
By default,
the contents of the
.Ev TERM
environment variable are used.
.It Fl t Ar TERM
Set the
.Ev TERM
environment variable within the mtm session to
.Ar TERM "."
By default, this is
.Em "screen-bce" ","
or
.Em "screen-256color-bce"
if
.Nm
detects that the host terminal supports 256 colors.
Note that this default can be changed at compile time,
and thus may differ in your installation.
.It Fl c Ar CHARACTER
Commands are prefixed using
.Ar CHARACTER
in combination with the
.Dq control
key.
By default this is
.Dq "g" "."
Note that this default can be changed at compile time,
and thus may differ in your installation.
.El
.Pp
.Ss Usage
.Nm
divides the screen into multiple virtual terminals.
Each virtual terminal is updated and accessed independently.
At any given time,
exactly one virtual terminal is
.Dq focused ","
meaning that it receives any typed characters.
The currently-focused terminal is indicated by the location of the cursor.
.Pp
While running,
the following keys are recognized as commands to
.Nm
when prefixed with the command character:
.Bl -tag -width Ds
.It Em "Up/Down/Right/Left Arrow"
Select the terminal above/below/to the right of/to the left of the currently focused one.
.It Em "o"
.Pq "the letter oh"
Switch to the last-focused terminal.
.It Em "h" "or" "v"
Split the focused terminal in half and stack horizontally
.Pq "for 'h'"
or stack vertically
.Pq "for 'v'" ";"
the newly-created terminal will be focused.
.It Em "w"
Delete the currently focused terminal.
.It Em "l"
.Pq "the letter ell"
Redraw the screen.
.It Em "PgUp/PgDown/End"
Scroll the terminal up/down/to the bottom.
By default,
.Nm
stores up to 1000 lines of scrolling history.
Note that if the screen is currently scrolled back
.Pq "that is, the scrollback buffer is not at the bottom"
these keys need not be prefixed with the command key.
.Nm
will also scroll to the bottom on user input.
.El
.Pp
Note that these command keys can be changed at compile time,
and therefore may be different for this installation of
.Nm "."
.Pp
.Nm
will exit when its last virtual terminal is closed.
.Ss The Value of Fl t
The terminal name passed to
.Fl t
does not change how
.Nm
interprets command sequences,
but rather changes what kind of terminal
.Nm
claims to be.
Safe bets for this value are
.Bl -tag -width Ds
.It mtm
This is the terminal described by the
.Pa mtm.ti
.Xr terminfo 5
description that shipped with
.Nm "."
It is not necessarily installed on your system,
but if it is, it will tell
.Xr terminfo 5
-aware programs how to use all of the
.Nm
features.
Note that there aren't any user-visible features added here,
but
.Nm
supports some extra cursor-movement commands,
and thus using this terminal type where available may result in slightly
speedier screen updates.
.It mtm-256color
This is the same as the
.Nm
terminal type, but advertising 256-color support.
This can be used if the
.Nm
.Xr terminfo 5
description is installed and the host terminal supports 256 or more colors.
.It screen-bce
This is the default if 256-color support is not detected.
It is widely supported and its description is installed by default on most systems.
This is a good choice if the
.Nm
.Xr terminfo 5
description is not installed everywhere you expect to use
.Nm mtm "."
.It screen-bce-256color
This is the default if 256-color support is detected.
The same advice given for
.Em screen-bce
above applies here too.
.El
.Ss The mtm Environment
.Nm
sets the
.Ev MTM
environment variable to its process ID
.Po
see
.Xr getpid 2
.Pc "."
Programs can test for the presence of this variable to determine if they are
running inside of a
.Nm
instance.
.Sh ENVIRONMENT
The following environment variables affect the operation of
.Nm mtm ":"
.Bl -tag -width Ds
.It Ev TERM
Names the hosting terminal's type.
This can be overridden using the
.Fl T
option.
.It Ev ESCDELAY
This variable specifies the number of milliseconds
.Nm
will wait after seeing an escape character for a special character sequence to complete.
By default this is 1000
.Pq "one second" "."
.It Ev LC_CTYPE Ev LC_ALL Ev LANG
These variables are consulted to determine the encoding used for textual data.
.It SHELL
If set,
.Nm
will launch the program named by this command in new virtual terminals.
If this is unset,
.Nm
will use the value of the
.Dq "command interpreter"
field of the password database
.Po
see
.Xr passwd 5
.Pc
if available,
and will finally fall back to
.Pa "/bin/sh" "."
.Sh SEE ALSO
.Xr sh 1
.Xr terminfo 5
.Sh BUGS
.Pp
.Nm
will attempt to fit all virtual terminals in the window at once.
If many terminals are created and the containing window is shrunk too small,
the display will be suboptimal.
.Pp
The only human language in which output is generated and in which documentation
is available is English,
regardless of the user's preferred language.