mrxvt.1

multi-tabed terminal based on rxvt

In case you want to unbind a default keyboard macro, just bind the appropriate key to the function
.Sq Ic Dummy .
For example
.Vb
Mrxvt.macro.Ctrl+Shift+t:	Dummy
.Ve
will disable the default keyboard shortcut
.Sq Ctrl+Shift+t .
If you want to disable all keyboard macros, use the option
.Sq Fl dm
(which can also be accessed via a pop-up menu). The default keyboard macros are defined in the system configuration file
.Pa /etc/mrxvt/mrxvtrc
so if you only want to disable all default shortcuts keys, don't read the system configuration file by using the 
.Fl nsc
option.
.Pp
.
Notice that keyboard shortcuts definitions are incompatible with X Windows own resource parsing API, i.e., XGetDefaults. So, to enable the keyboard shortcuts, you will need to enable resources but disable xgetdefault when you configure
.Nm Ns .
.Pp
Finally
.Sq action
is the action you want bound to the specified macro key. The available actions you can bind to macros are:
.\" {{{3 Available macros list
.Bl -tag -width 4n -offset 4n
.It Ic Dummy
Clear an existing keyboard shortcut
.\" ------------------------------------------------------------
.It Ic Esc Ar str
Send the escape sequence
.Ar str
to
.Nm .
.\" ------------------------------------------------------------
.It Ic Str Ar str
Send the string
.Ar str
to the child process.
.\" ------------------------------------------------------------
.It Ic Exec Ar command
Executes
.Ar command
asynchronously. The command run without any controlling shell or TTY. This is generally used to launch X11 programs (e.g. open the selected text in firefox). If you want a command run in a new tab, see the
.Ic NewTab
macro).
.Pp
The argument
.Ar command
is word split exactly as described in the
.Fl blc
option (thus for instance beginning it with 
.Sq \&!
will pass it to
.Cd /bin/sh -c
for word splitting and execution). However keep in mind that like all macro arguments,
.Ar command
is first
.Sq Sy \e
interpolated. Thus if on the rare occasion you want
.Sq \e\ 
to be part of
.Ar command ,
then you will have to do something like
.Sq \e\e\e\e\e\e\ 
and not
.Sq \e\e\e\ 
as you would with the argument of
.Fl blc .
.\" ------------------------------------------------------------
.It Ic NewTab Oo Ar -N Oc Oo Ar \*qtitle\*q Oc Op Oo ! Oc Ns Ar command
Open a new tab.
.Ar N
specifies the profile number. If omitted, profile 0 is used. If only
.Sq -
(with no number) is specified, then the profile of the current active tab is used (i.e. this can be used to duplicate the current tab).
.Ar title
is specified (needs to be double quoted), use that for the tab title. If
.Ar command
is specified, execute that command in the new tab (instead of the one specified by the resource file, or the shell).
.Pp
.Ar command
is word split as described in the
.Ic Exec
macro. However if command begins with an
.So ! Sc
then run a shell first, and execute the command in the shell as if the user had typed
.Ar command
at the shell prompt. If instead you want
.Ar command
to be passed to
.Cd /bin/sh -c
for word splitting and execution, then begin
.Ar command
with
.Sq \e! .
.\" ------------------------------------------------------------
.It Ic Close Op Ar N
Close a tab. If no argument is specified, close all tabs and exit. If
.Ar N
is 0, close the active tab. Otherwise close the
.Ar N Ns th tab .
.\" ------------------------------------------------------------
.It Ic GotoTab Op Ar N
Goto tab. If
.Ar N
is ommited or 0, then goto the previous active tab. Otherwise goto the
.Ar N Ns th
tab. If
.Ar N
begins with a
.Sq +
or
.Sq -
then
.Ar N
is relative to the current tab.
.\" ------------------------------------------------------------
.It Ic MoveTab Ar N
Move active tab to position
.Ar N .
If
.Ar N
begins with a
.Sq +
or
.Sq -
then
.Ar N
is relative to the current tab.
.\" ------------------------------------------------------------
.It Ic Scroll Ar amount
Scroll the active tab by
.Ar amount
lines (negative values mean scroll backward). If
.Ar amount
ends with
.Sq p
then scroll
.Ar amount
pages instead of lines.
.\" ------------------------------------------------------------
.It Ic Copy
Copy selection into clipboard (not implemented).
.\" ------------------------------------------------------------
.It Ic Paste Op Ar selection-buffer
Paste selection into active tab. The value
.Ar selection-buffer 
specifies the name of the buffer to be pasted. If not specified the first used buffer in the order PRIMARY, SECONDARY and CLIPBOARD  will be used.
.\" ------------------------------------------------------------
.It Ic PasteFile Ar filename
Paste the content of the file specified by 
.Ar filename
to the currently active tab. This can be used to input text-snippets to a shell
or any other terminal based program (i.e. somthing like a bash-profile
or sequence of administration commands).
.\" ------------------------------------------------------------
.It Ic MonitorTab Ar [ACTIVITY|INACTIVITY|AUTO]
Monitor the current tab-window for  
.Ar ACTIVITY
or
.Ar INACTIVITY
or automatically detect the type of monitoring using the 
.Ar AUTO
option. The amount time which is used to detect the type of monitoring or tab-inactivity
can be specified by the
.Ic monitorTimeout
option. The detection of activity or inactivity is signaled by highlighting the tab of the event and ringing
the system bell. Additionally it is possible to execute a dedicated command using the
.Ic monitorCommand
option.
.\" ------------------------------------------------------------
.It Ic ToggleSubwin Op Oo Ar + Ns | Ns Ar - Oc Ns Op Ar b Ns | Ns Ar m Ns | Ns Ar s Ns | Ns Ar t
Toggle visibility of sub-windows. If the argument begins with a
.Sq +
the subwindow is shown. If it begins with a
.Sq -
the subwindow is hidden. Otherwise it is toggled. The letters
.Sq Ar b ,
.Sq Ar m ,
.Sq Ar s
and
.Sq Ar t
represent the tabbar buttons, menubar, scrollbar and tabbar respectively. NOTE: Currently you can only toggle one subwindow at a time.
.\" ------------------------------------------------------------
.It Ic ResizeFont Oo Ar + Ns | Ns Ar - Oc Ns Ar N
Resize the font. With Xft,
.Ar N
represents the size increment of the xft font. Without Xft,
.Ar N
represents the index of the X11 fonts specified by the
.Cm font Ns Ar N
resources.
.\" ------------------------------------------------------------
.It Ic ToggleVeryBold
Toggle use of bold font for colored text.
.\" ------------------------------------------------------------
.It Ic ToggleTransparency
Toggle pseudo transparency.
.\" ------------------------------------------------------------
.It Ic ToggleBroadcast Op Ar status
If
.Ar status
is omitted or
.Sq -1 ,
then input broadcasting to all tabs is toggled. If it is
.Sq 1 ,
input broadcasting is enabled. If it is
.Sq 0 ,
it is disabled.
.\" ------------------------------------------------------------
.It Ic ToggleHold Op Ar mask
If
.Ar mask
is not specified, then just close all tabs who's child processes have exited. (This is almost compatible with the behaviour of
.Nm
0.5.1 and earlier). If
.Ar mask
is specified, then change the hold status of the current tab.
.Ar mask
must begin with
.Sq Sy + ,
.Sq Sy - ,
or
.Sq Sy \&!
and be followed by a bit mask (as in the
.Ic holdExit
option).
.Sq Sy +
will add bits to the
.Ic holdExit
option for this tab,
.Sq Sy -
will subtract, and
.Sq Sy \&!
will toggle. Remember that if the lowest bit of the current tabs
.Ic holdExit
option is set, then the tab will always be held open and everything else will be ignored.
.\" ------------------------------------------------------------
.It Ic ToggleFullscreen
Toggle between full screen and regular mode. Also enable
.Fl Fl smoothResize
to get true full screen. This will only work if you are running an EWMH compatible window manager (e.g. Fvwm / OpenBox / KDE / Gnome).
.\" ------------------------------------------------------------
.It Ic Raise
Raise the
.Nm
window.
.\" ------------------------------------------------------------
.It Ic SetTitle
Set title of active tab to selection. (The selection must be owned by
.Nm )
.\" ------------------------------------------------------------
.It Ic UseFifo Ar status
Enable or disable using a
.Xr fifo 1
to listen for macros on (see the
.Ic useFifo
option). The argument
.Ar status
should be
.Sy 0 , 1 , -1
to disable, enable or toggle respectively.
.\" ------------------------------------------------------------
.It Ic PrintScreen Oo Fl psn Oc Op Ar command
Dump screen to printer (or
.Ar command ) .
If
.Fl p
is specified, then the output is pretty printed (i.e. escape sequences are used to get the same color in the output as on your screen). If
.Fl s
is specified, then the entire scroll back is printed (instead of just the current screen). If
.Fl n
is specified, then every screen line is terminated with a newline char (by default screen lines that wrap to the next line are not terminated with a newline). Finally, if command is specified it is used as the printer pipe (if not the value of
.Ic printPipe
or the compiled in default is used).
.\" ------------------------------------------------------------
.It Ic SaveConfig Op Ar filename
Save config to file. If no filename is specified, save to
.Pa ~/.mrxvtrc.save .
.\" ------------------------------------------------------------
.It Ic ToggleMacros
Toggle the use of keyboard shortcuts. When macros are disabled (either by using this macro, or by the
.Fl dm
option), then this is the only keyboard shortcut that will work. Thus you can re-enable your keyboard shortcuts via the keyboard using this function.
.\" ------------------------------------------------------------
.El
.Pp
Additionally, the argument to any of the above macros are
.Sq Sy \e
and
.Sq Sy %
interpolated as follows:
.Pp
.Bl -tag -compact -offset 4n -width 8n
.It Sy \ea
Bell
.It Sy \eb
Backspace
.It Sy \eE , \ee
Escape
.It Sy \en
Newline
.It Sy \er
Carriage return
.It Sy \et
Tab
.It Sy \e Ns Ar ddd
Char with octal ASCII code
.Ar ddd .
.It Sy ^@ , ^A .. ^Z .. ^_ , ^?
Control-@, Control-A ...
.Pp
.It Sy %G
Global (static) tab number.
.It Sy %p
PID of child process in current tab.
.It Sy \&%P
PID of
.Nm
.It Sy %n
Tab number.
.It Sy % Ns Sy N
Expands to
.Sq normally
if the process exited normally (e.g. by calling
.Xr exit 1 )
or
.Sq abnormally
otherwise. (Note this is independent of the exit status).
.It Sy %s
Text selected in the
.Nm
window.
.It Sy %S
If the process in this tab is dead, then it expands to the exit status of the child process. Otherwise left unchanged.
.It Sy %t
Tab title.
.It Sy \&%T
Total number of tabs created in
.Nm
lifetime.
.El
.Ed
.Ss Mouse shortcuts \"{{{2
.Bd -filled
.Bl -tag -width 4n
.It Changing tab titles
This mouse shortcut can be used to dynamically change the tab title as follows: Select text in the terminal window. Then middle click on a tab to change the tab's title. If you middle click on the tabbar background, then the title of the active tab is changed.
.It Tab list menu
By default, if you right click on the tab bar, or control-left-click on the terminal window, a popup menu with a list of currently open tabs pops up. The actual menu popped up can be customized as described under the section
.Sx MENUS .
.It Popup menus
If you Control-click on the terminal window (with any mouse button), it pops up a menu. The actual menu popped up can be customized as described under the section
.Sx MENUS .
.It Moving tabs
Click and drag a tab to some other location on the tab-bar to move it.
.El
.Ed
.\"}}}
.
.
.Sh ESCAPE SEQUENCES \"{{{1
.
.
.Bd -filled
You have several escape sequences to control
.Nm .
All default
.Xr rxvt 1
escape sequences are supported by
.Nm .
A few extra escape sequences have been added to improve DEC compatibility, and allow interaction with extra
.Nm
features (e.g. tabs). The supported escape sequences are listed in the file
.Pa mrxvt_seq.txt
included in the distribution.
.Pp
For omissions in the documentation, and a more complete reference to escape sequences you should look at the file
.Pa ctlseqs.txt
that comes with the xterm package,
.Xr console_codes 4
and the original rxvt documentation in the file
.Pa rxvtRef.txt .
.Pp
For basic interaction with
.Nm
(e.g. changing the tab title etc.) you should also look at the programs
.Pa share/scripts/settitle.c
and
.Pa share/scripts/mrxvtset.pl
that are supplied with the
.Nm
distribution.
.Ed
.
.
.Sh ENVIRONMENT \"{{{1
.
.
.Bd -filled
.Bl -tag -width 4n
.It Ev COLORFGBG
Set to the terminal foreground and background colors.
.It Ev COLORTERM
Sets to the terminal sub-name that indicates its color.
.It Ev DISPLAY
Used (and set) to the X display bieng used.
.It Ev PATH_ENV
Path to look for menu / background files (see
.Fl path
option).
.It Ev TERM
Set to the terminal name in the window you have created.
.It Ev MRXVT_TABTITLE
Set to the initial tab title of each terminal. Notice that its value will not be altered if the user uses a shortcut or escape sequence to change the tab title. The user must modify it manually after doing that.
.It Ev WINDOWID
Set to the X window id number of the mrxvt window.
.El
.Ed
.
.
.Sh FILES \"{{{1
.
.
.Bd -filled
The actual pathnames given may differ on your system.
.Bl -tag -width 4n
.It Pa default.menu
The default menu file loaded at startup (searched for in your
.Fl path ) .
.It Pa ~/mrxvt
Directory in which to look for user menu and image files.
.It Pa ~/.mrxvtrc
This is the default configuration file (since 0.3.9). If present, resources read from this file override existing resources.
.It Pa ~/.Xdefaults
(OBSOLETE) This was the default configuration file (before 0.3.9). If present, resources read from this file override existing resources.
.It Pa ~/.Xresources
(OBSOLETE) If both
.Pa .mrxvtrc
and
.Pa .Xdefaults
are not found, try this one.
.It Pa /etc/mrxvt
System wide directory in which to look for user menu and image files.
.It Pa /etc/mrxvt/default.menu
Default menu file read on startup.
.It Pa /etc/mrxvt/mrxvtrc
System wide configuration file. (By default this file only defines the default keyboard macros)
.It Pa /etc/utmp
System file for login records.
.It Pa /usr/lib/X11/rgb.txt 
Color names.
.It Pa /usr/X11R6/lib/X11/app-defaults/XTerm
(OBSOLETE) If enable xgetdefaults at compiled time, this is the first configuration file read. 
.El
.Ed
.
.
.Sh BUGS \"{{{1
.
.
.Ss "Reporting bugs"
.Bd -filled
Please report bugs using the sourceforge bug tracker system at
.Pp
.Bd -centered
.Ad http://sourceforge.net/projects/materm
.Ed
.Pp
Alternately you can send your bug report to the mrxvt developer mailing list at
.Pp
.Bd -centered
.Mt [e-mail]
.Ed
.Pp
Be sure you give us enough details to reproduce the bug ourselves, and check to see if your bug still exists in the current CVS version.
.Ed
.Ss "Known bugs"
.Bd -filled
.Bl -dash -compact -width 2
.It
Tabs don't work properly when running under Xnest.
.It
Transparency and tinting are global, not specific to a terminal.
.It
The transparentForce option does not work well with all window managers (e.g. OpenBox).
.El
.Ed
.
.
.Sh SEE ALSO \"{{{1
.
.
.Bd -filled
.Xr rxvt 1 ,
.Xr xterm 1 ,
.Xr resize 1 ,
.Pa mrxvt_seq.txt ,
.Ar Xterm control sequences
(this is the file
.Pa ctlseqs.ms
or
.Pa ctlseqs.txt ) ,
.Xr console_codes 4
.Pp
.Bd -centered
.Ad http://materm.sourceforge.net
.Ed
.Ed
.
.
.Sh AUTHORS \"{{{1
.
.
.An "Terminator" < Ns Mt [e-mail] Ns >
.An "Gautam Iyer" < Ns Mt [e-mail] Ns >
.An "Marc Schoechlin" < Ns Mt [e-mail] Ns >
.
.