path: root/doc/ratpoison.1

.TH RATPOISON 1 "3 March, 2001" "ratpoison 1.0.0" RATPOISON
.SH NAME
ratpoison \- fatless X window manager
.SH SYNOPSIS
.B ratpoison [ \fIoptions\fP ]
.SH DESCRIPTION
This manual page documents briefly the
.B ratpoison
window manager.

\fBratpoison\fP is a simple Window Manager with no fat library
dependencies, no fancy graphics, no window decorations, and no
flashy wank. It is largely modeled after \fIGNU Screen\fP which
has done wonders in virtual terminal market.

All interaction with the window manager is done through
keystrokes. ratpoison has a prefix map to minimize the key
clobbering that cripples EMACS and other quality pieces of
software.
.SH KEYSTROKES
ratpoison is controlled entirely through the keyboard. The default
keystrokes are listed in this section.
.TP
.B C-t C-t
Switch to the last window.
.TP
.B C-t t
Sometimes you need to send a C-t to the current window. This keystroke
does just that.
.TP
.B C\-t 0-9
Switch to the numbered window.
.TP
.B C\-t \-
Select no window, essentially hiding all windows in the current frame.
.TP
.B C\-t A,
.B C\-t C\-A
Rename the current window. The window's new name will prevail for the
rest of its lifetime.
.TP
.B C\-t K,
.B C\-t C\-K
Send a DestroyClient event to the current window. This will terminate
the application without question.
.TP
.B C\-t n,
.B C\-t C\-n,
.B C\-t Return,
.B C\-t C\-Return,
.B C\-t Space,
.B C\-t C\-Space,
Go to next window.
.TP
.B C\-t p,
.B C\-t C\-p
Go to previous window.
.TP
.B C\-t ',
.B C\-t C\-'
Go to a window by name.  You will usually only need to type the first
few characters of the window name.
.TP
.B C\-t a,
.B C\-t C\-a
Display the current time of day.
.TP
.B C\-t c,
.B C\-t C\-c
Open a new X terminal.
.TP
.B C\-t :,
.B C\-t C\-:
This allows you to execute a single ratpoison command.
.TP
.B C\-t !,
Run a shell command.
.TP
.B C\-t C\-!
Run a shell command through an X terminal.
.TP
.B C\-t k,
.B C\-t C\-k
Close the current window.
.TP
.B C\-t m,
.B C\-t C\-m
Maximize the current window. Sometimes windows don't respond correctly
to the initial maximize event and need some coaxing. This is a fancy way
of saying there are still bugs in ratpoison. \fIC\-t m\fP will force the
current window to maximize.
.TP
.B C\-t v,
.B C\-t C\-v
Display the version of ratpoison.
.TP
.B C\-t w,
.B C\-t C\-w
Display the list of managed windows. The current window is highlighted.
.TP
.B C\-t s
Split the current window horizontally in two. The last accessed window
not occupying a frame will be the second window.
.TP
.B C\-t S
Split the current window vertically in two. The last accessed window not
occupying a frame will be the second window.
.TP
.B C\-t tab
Cycle through ratpoison's frames.
.TP
.B C\-t Q
Kill all frames but the current one.
.TP
.B C\-t R
Kill the current frame. This is a no-op if there is only one frame.
.TP
.B C\-t b,
.B C\-t C\-b
Banish the mouse to the lower right corner of the screen.
.TP
.B C\-t ?
Display a help screen
.TP
.B C\-t f
.B C\-t C\-f
Indicate which frame is the current frame.

.SH COMMANDS
Ratpoison can be controlled with commands (so called colon-commands).
The summary of available commands is listed below:
.TP
.B abort
This is a pretty useless command. By default, it is bound to
\fIC\-t g\fP, and its purpose is to abort other commands.
.TP
.B banish
Banish the mouse to the lower right corner of the screen.
.TP
.B bind \fIKey\fP \fIcommand\fP
Bind a key to a ratpoison command. This command takes two arguments: the
key to bind and the command to run. For example, to bind \fIC\-t R\fP to
restart ratpoison:

.IP
: bind R exec ratpoison --restart
.PP
.TP
.B clock
Show current time. Disappears after 5 seconds, like all other info bars.
In the default setup, the \fIC\-t a\fP keystroke is bound to this command.
.TP
.B colon \fIcommand\fP
Run a ratpoison command.
.TP
.B curframe
Indicate which frame is the current frame.
.TP
.B delete
This deletes the current window. You can access it with the \fIC\-t k\fP
keystroke.
.TP
.B escape \fIkey\fP
Set the prefix to to \fIkey\fP. For example \fIescape C-b\fP sets the
prefix key to \fIC\-b\fP.
.TP
.B focus
cycle through ratpoison's frames.
.TP
.B generate
Send a \fIC\-t\fP to the current window.
.TP
.B help
Display a help screen that lists all bound keystrokes.
.TP
.B echo \fItext\fP
Display \fItext\fP as a message.
.TP
.B exec \fIcommand\fP
Execute a shell command. By default, \fIC\-t !\fP does this.
.TP
.B kill
This destroys the current window. Normally you should only need to
use \fIdelete\fP, but just in case you need to rip the heart out of a
misbehaving window this command should do the trick. Also available as
\fIC\-t K\fP.
.TP
.B maximize
Maximize the current window, just like \fIC\-t m\fP would do.
.TP
.B next
This jumps you to the next window in the window list. This one is
bound to three keystrokes, namely \fIC\-t n\fP, \fIC\-t space\fP,
and \fIC\-t enter\fP.
.TP
.B newwm \fIwindow-manager\fP
This is a bad-bad command. It kills ratpoison and revives that
ugly rodent! Yuck! Avoid!
.TP
.B number \fIn\fP
Set the current window's number to \fIn\fP. If another window occupies
the requested number already, then the windows' numbers are swapped.
.TP
.B only
Kill all frames but the current one.
.TP
.B other
This toggles between the current window and the last window. By
default, this is bound to \fIC\-t C\-t\fP.
.TP
.B prev
This jumps you to the previous window in the window list. By default,
this is bound to \fIC\-t p\fP.
.TP
.B quit
Quit ratpoison.
.TP
.B remove
Kill the current frame. This is a no-op if there is only one frame.
.TP
.B rudeness \fIn\fP
The rudeness command lets you decide what windows pop-up automatically
and when. This is often useful for those deep hack sessions when you
absolutely can't be disturbed.

There are two kinds of windows: normal windows (like an xterm) and
transient windows (generally pop-up dialog boxes). When a client
program wants to display a new window it makes a requests to
ratpoison. ratpoison then decides whether to grant the request and
display the window or ignore it. A client program can also request
that one of its windows be raised. You can customize ratpoison to
either honour these requests (the default operation) or ignore them.

\fIn\fP is a number from 0 to 15. Each of the four bits determine
which requests ratpoison grants.

Bit 0 Tells ratpoison to grant raise requests on transient windows.
Bit 1 Tells ratpoison to grant raise requests on normal windows. 
Bit 2 Tells ratpoison to grant display requests on new transient windows.
Bit 3 Tells ratpoison to grant display requests on new normal windows.

For example, if you wanted only wanted to grant transient windows
raise requests and display requests you would type \fIrudeness
5\fP. If a request is not granted ratpoison will tell you about the
request with a message like \fIRaise request from window 1
(emacs)\fP.
.TP
.B select \fIn\fP
This jumps you to window \fIn\fP where \fIn\fP is the window number as
shown in the Program Bar. You can do the same trick with
\fIC\-n\fP too. To select no window, blanking the current
frame, type \fIselect -\fP.
.TP
.B select \fIwindow-name\fP
Go to a window by name. A shortcut is \fIC\-t '\fP.
.TP
.B source \fIfile\fP
Read a text file containing ratpoison commands.
.TP
.B split,
.B hsplit
Split the current window horizontally in two. The last accessed window
not occupying a frame will be the second window.
.TP
.B title \fItitle\fP
Rename the currently active window. This name will remain for the
duration of the window's life, unless you change it again. By default,
the \fIC\-t A\fP keystroke is bound to this command.
.TP
.B unbind \fIkey\fP
Unbind a keystroke.
.TP
.B version
Print ratpoison version.  By default, this is bound to \fIC\-t v\fP.
.TP
.B vsplit
Split the current window vertically in two. The last accessed window not
occupying a frame will be the second window.
.TP
.B windows
This displays the Program Bar which displays the windows you currently
have running. The number before each window name is used to jump to
that window. You can do this by typing \fIC\-t n\fP where \fIn\fP
is the number of the window. Note that only windows with numbers from
0 to 9 can be referenced using this keystroke.  To reach windows with
numbers greater than 9, use \fIC\-t '\fP and type the number at the
prompt.

After 5 seconds the Program Bar disappears.

This command is bound to \fIC\-t w\fP by default.

When invoked from the command-line like this,

$ ratpoison -c windows

Instead of a message bar, you will get a list of the windows printed
to stdout. This allows you to write more advanced scripts than simple
keyboard macros.

.SH OPTIONS
These are the command line options that are recognized by ratpoison:
.TP
\fB\-r\fR, \fB\-\-restart\fR
restart ratpoison
.TP
\fB\-k\fR, \fB\-\-kill\fR
kill ratpoison
.TP
\fB\-v\fR, \fB\-\-version\fR
output version information and exit
.TP
\fB\-h\fR, \fB\-\-help\fR
display this help and exit
.TP
\fB\-c\fR \fIcmd\fP, \fB\-\-command\fR \fIcmd\fP
Tell the running ratpoison process to execute the command
\fIcmd\fP. This is how ratpoison can be controlled from the
command-line or from a script.

.SH "REPORTING BUGS"
Report bugs to <ratpoison-devel@lists.sourceforge.net>.
.SH COPYRIGHT
Copyright \(co 2000, 2001 Shawn Betts
.br
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.SH "SEE ALSO"
The full documentation for
.B ratpoison
is maintained as a Texinfo manual.  If the
.B info
and
.B ratpoison
programs are properly installed at your site, the command
.IP
.B info ratpoison
.PP
should give you access to the complete manual.
.SH AUTHOR
Ratpoison was written by Shawn Betts <sabetts@users.sourceforge.net>.

This manual page was written by Gergely Nagy <8@free.bsd.hu> and
updated by Shawn Betts <sabetts@users.sourceforge.net>.