path: root/doc/ratpoison.texi

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename ratpoison.info
@settitle ratpoison manual
@setchapternewpage odd
@c %**end of header

@dircategory X11
@direntry
* ratpoison: (ratpoison).       Say good-bye to the rodent
@end direntry

@ifinfo
This is the ratpoison user manual.

Copyright @copyright{} 2000, 2001 Shawn Betts

Permission is granted to make and distribute verbatim
copies of this manual provided the copyright notice and
this permission notice are preserved on all copies.

@ignore
Permission is granted to process this file through TeX
and print the results, provided the printed document
carries a copying permission notice identical to this
one except for the removal of this paragraph (this
paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified
versions of this manual under the conditions for
verbatim copying, provided also that the sections
entitled ``Copying'' and ``GNU General Public License''
are included exactly as in the original, and provided
that the entire resulting derived work is distributed
under the terms of a permission notice identical to this
one.

Permission is granted to copy and distribute
translations of this manual into another language,
under the above conditions for modified versions,
except that this permission notice may be stated in a
translation approved by the Free Software Foundation.
@end ifinfo

@titlepage
@sp 10
@titlefont{ratpoison}
@author Shawn Betts

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 2000, 2001 Shawn Betts

Permission is granted to make and distribute verbatim
copies of this manual provided the copyright notice and
this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified
versions of this manual under the conditions for
verbatim copying, provided also that the sections
entitled ``Copying'' and ``GNU General Public License''
are included exactly as in the original, and provided
that the entire resulting derived work is distributed
under the terms of a permission notice identical to this
one.

Permission is granted to copy and distribute
translations of this manual into another language,
under the above conditions for modified versions,
except that this permission notice may be stated in a
translation approved by the Free Software Foundation.
@end titlepage

@node Top, About, (dir), (dir)

@ifinfo
This document explains how to use ratpoison.
@end ifinfo

@menu
* About::                       What is ratpoison?
* Contacting::                  How do I contact the ratpoison developers?
* General Use::                 How does this thing work??
* Splitting The Screen::        When you want to see more than one window
* Keystrokes::                  Key commands and functionality
* Commands::                    ratpoison commands
* Command Line Arguments::      ratpoison command-line actions
* Startup file::                They threatened me...with violence!



@end menu

@node About, Contacting, Top, Top
@chapter About

ratpoison 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 GNU Screen which has done wonders in the
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.

ratpoison was written by Shawn Betts (@email{sabetts@@users.sourceforge.net}).

@node Contacting, General Use, About, Top
@chapter Contacting
ratpoison is hosted on @url{sourceforge.net}. To see the latest
developments in ratpoison go to
@url{http://www.sourceforge.net/projects/ratpoison} or visit the
ratpoison webpage at @url{http://ratpoison.sourceforge.net}.

There is also a ratpoison mailing list:
@email{ratpoison-devel@@lists.sourceforge.net}. For details on subscribing
and for the list archives go to the ratpoison sourceforge.net project.

There is a #ratpoison irc channel on irc.openprojects.net.

@node General Use, Splitting The Screen, Contacting, Top
@chapter General Use

When ratpoison starts you should see an empty X server. To open an x
terminal hit @kbd{C-t c}. You can now run shell commands as you would on
any terminal. Notice the terminal maximized full screen. @kbd{C-t !}
will run a single shell command and saves you the effort of opening a
terminal.

Once you have a couple X programs running, you'll want to navigate
between windows. To see what windows are being managed hit @kbd{C-t
w}. Each window has a number. You can jump to a window by hitting
@kbd{C-t} followed by the window's number. This assumes the the window's
number is one digit. You can also switch to a window by typing in part
of its name. To do this hit @kbd{C-t '}.

ratpoison allows you to cycle through the windows with @kbd{C-t n}
and @kbd{C-t p}.

And That concludes a brief introduction on how to use ratpoison. Notice
how we didn't have to drag a single window, or click a single maximize
button? Beautiful wasn't it? Felt fast? Cool? Its modern computing at
its best boys and girls.

@node Splitting The Screen, Keystrokes, General Use, Top
@chapter Splitting The Screen
Sometimes you may want to see two or more windows at the same
time. ratpoison allows you to split the screen into frames. Each frame
can then contain 1 window. To split the current frame horizontally use
@kbd{C-t s}. To split the current frame vertically use @kbd{C-t S}. If
you have enough windows, you'll notice that the new frame will find a
window for itself. You can now use the normal navigation commands to
switch windows in the frame. Note, however, that if you switch by name
or number to a window that is already in another frame, you'll switch
to that frame.

Before too long, you'll probably want to switch to another frame. Use
@kbd{C-t tab} to cycle through the frames. If you want to remove a
frame use @kbd{C-t R}. ratpoison automatically adjusts the size of the
other frames to take up the free space. Unfortunately ratpoison may
not always fill it in the way you might like it to.

Finally, when you've had enough of the splitting and you just want
good ol' full screen ratpoison press @kbd{C-t Q} to remove all splits
and leave you with the current window full screen.

@node Keystrokes, Commands, Splitting The Screen, Top
@chapter Keystrokes

ratpoison is a very simple window manager. Each window is maximized and
has no border decorations. The default keystrokes are listed in this
chapter. Not all commands are accessible by default by keys. A full list
of ratpoison commands is in the next section.

@table @kbd

@item C-t C-t
Switch to the last window.

@item C-t t
Sometimes you need to send a C-t to the current window. This keystroke
does just that.

@item C-t 0-9
Switch to the numbered window.

@item C-t -
Select no window, essentially hiding all windows in the current frame.

@item C-t A
@item C-t C-A
Rename the current window. The window's new name will prevail for the
rest of its lifetime.

@item C-t K
@item C-t C-K
Send a DestroyClient event to the current window. This will terminate
the application without question.

@item C-t n
@item C-t C-n
@item C-t Return
@item C-t C-Return
@item C-t Space
@item C-t C-Space
Go to next window.

@item C-t p
@item C-t C-p
Go to previous window.

@item C-t '
@item C-t C-'
Go to a window by name.  You will usually only need to type the first
few characters of the window name.

@item C-t a
@item C-t C-a
Display the current time of day.

@item C-t c
@item C-t C-c
Open a new X terminal.

@item C-t :
@item C-t C-:
This allows you to execute a single ratpoison command.

@item C-t !
Run a shell command.

@item C-t C-!
Run a shell command through an X terminal.

@item C-t k
@item C-t C-k
Close the current window.

@item C-t m
@item 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. @kbd{C-t m} will force the
current window to maximize.

@item C-t v
@item C-t C-v
Display the version of ratpoison.

@item C-t w
@item C-t C-w
Display the list of managed windows. The current window is highlighted.

@item C-t s
Split the current window horizontally in two. The last accessed window
not occupying a frame will be the second window.

@item C-t S
Split the current window vertically in two. The last accessed window not
occupying a frame will be the second window.

@item C-t tab
Cycle through ratpoison's frames.

@item C-t Q
Kill all frames but the current one.

@item C-t R
Kill the current frame. This is a no-op if there is only one frame.

@item C-t b
@item C-t C-b
Banish the mouse to the lower right corner of the screen.

@item C-t ?
Display a help screen

@item C-t f
@item C-t C-f
Indicate which frame is the current frame.

@end table

@node Commands, Command Line Arguments, Keystrokes, Top
@chapter ratpoison commands

ratpoison can be controlled with commands (so called colon-commands).
The summary of available commands is listed below:

@table @command

@item abort
This is a pretty useless command. By default, it is bound to
@kbd{C-t g}, and its purpose is to abort other commands.

@item banish
Banish the mouse to the lower right corner of the screen.

@item bind @var{Key} @var{command}
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 @kbd{C-t R} to
restart ratpoison:

@example
: bind R exec ratpoison --restart
@end example

If no command is specified then bind works exactly like @command{unbind},
unbinding the key.

@item clock
Show current time. Disappears after 5 seconds, like all other info bars.
In the default setup, the @kbd{C-t a} keystroke is bound to this command.

@item colon @var{command}
Run a ratpoison command.

@item curframe
Indicate which frame is the current frame.

@item defbarloc @var{n}
Set the message bar location. @var{n} is a value between 0 and 3. 0 is
the top left and the values move clockwise around the screen to the
bottom left which is 3.

@item defbartimeout @var{n}
Set the bar's timeout in seconds.

@item defborder @var{n}
Set the border width for all windows.

@item deffont @var{font}
Set the font. @var{font} is a font string like @samp{9x15bold}.

@item definputwidth @var{n}
Set the width of the input window.

@item defmaxsizepos @var{x} @var{y}
Set the default alignment for windows with maxsize hints. See the
@command{pos} command.

@item defpadding @var{left} @var{top} @var{right} @var{bottom}
Set the padding around the edge of the screen.

@item deftranspos @var{x} @var{y}
Set the default alignment for transient windows. See the
@command{pos} command.

@item defwaitcursor @var{n}
Set whether the rat cursor should change into a square when waiting
for a key. A non-zero number means change the cursor. Zero means don't
change the cursor.

@item defwinfmt @var{fmt}
Set the default window format for the @command{windows} command. By
default it is @samp{N-W}. The following is a list of valid format
characters:

@table @samp
@item N
The window number
@item -
Window status (current window, last window, etc)
@item W
Window Name
@item w
Window res name
@item c
Window res class
@item n
X11 Window ID
@end table

@item defwinname @var{name}
There are three resources ratpoison can get a window's name from: the
WMNAME hint, the res_name from the WMCLASS hint, or the res_class from
the WMCLASS hint. @var{name} can be @samp{title} which is what most
window managers put in the title bar, @samp{name} which is the
res_name, or @samp{class} which is the res_class.

@item defwinpos @var{x} @var{y}
Set the default alignment for normal windows. See the
@command{pos} command.

@item deffgcolor @var{color}
Set the foreground color for all text ratpoison displays. @var{color}
is any valid X11 color.

@item defbgcolor @var{color}
Set the background color for all text ratpoison displays. @var{color}
is any valid X11 color.

@item delete
This deletes the current window. You can access it with the @kbd{C-t k}
keystroke.

@item escape @var{key}
Set the prefix to to @var{key}. For example @samp{escape C-b} sets the
prefix key to @key{C-b}.

@item focus
cycle through ratpoison's frames.

@item generate
Send a @kbd{C-t} to the current window.

@item help
Display a help screen that lists all bound keystrokes.

@item echo @var{text}
Display @var{text} as a message.

@item exec @var{command}
Execute a shell command. By default, @kbd{C-t !} does this.

@item kill
This destroys the current window. Normally you should only need to
use @command{delete}, but just in case you need to rip the heart out of a
misbehaving window this command should do the trick. Also available as
@kbd{C-t K}.

@item maximize
Maximize the current window, just like @kbd{C-t m} would do.

@item next
This jumps you to the next window in the window list. This one is
bound to three keystrokes, namely @kbd{C-t n}, @kbd{C-t space},
and @kbd{C-t enter}.

@item newwm @var{window-manager}
This is a bad-bad command. It kills ratpoison and revives that
ugly rodent! Yuck! Avoid!

@item number @var{n}
Set the current window's number to @var{n}. If another window occupies
the requested number already, then the windows' numbers are swapped.

@item only
Kill all frames but the current one.

@item other
This toggles between the current window and the last window. By
default, this is bound to @kbd{C-t C-t}.

@item pos @var{x} @var{y}
Change the alignment of the current window. A normal window will
default to aligning itself to the top-left corner of the screen, but
it can also be aligned to, say, the bottom-right. Valid values for
@var{x} are @samp{left}, @samp{center}, and @samp{right}. Valid values
for @var{y} are @samp{top}, @samp{center}, @samp{bottom}. @var{x} and
@var{y} can be abbreviated to the first letter.

@item prev
This jumps you to the previous window in the window list. By default,
this is bound to @kbd{C-t p}.

@item quit
Quit ratpoison.

@item remove
Kill the current frame. This is a no-op if there is only one frame.

@item rudeness @var{n}
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.

@var{n} is a number from 0 to 15. Each of the four bits determine
which requests ratpoison grants.

@table @asis
@item Bit 0
Tells ratpoison to grant raise requests on transient windows

@item Bit 1
Tells ratpoison to grant raise requests on normal windows

@item Bit 2
Tells ratpoison to grant display requests on new transient windows

@item Bit 3 
Tells ratpoison to grant display requests on new normal windows
@end table

For example, if you wanted only wanted to grant transient windows
raise requests and display requests you would type @samp{rudeness
5}. If a request is not granted ratpoison will tell you about the
request with a message like @samp{Raise request from window 1
(emacs)}.

@item select @var{n}
This jumps you to window @var{n} where @var{n} is the window number as
shown in the Program Bar. You can do the same trick with
@command{C-@var{n}} too. To select no window, blanking the current
frame, type @samp{select -}.

@item select @var{window-name}
Go to a window by name. A shortcut is @kbd{C-t '}.

@item source @var{file}
Read a text file containing ratpoison commands.

@item split
@item hsplit
Split the current window horizontally in two. The last accessed window
not occupying a frame will be the second window.

@item title @var{title}
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 @kbd{C-t A} keystroke is bound to this command.

@item unbind @var{key}
Unbind a keystroke.

@item version
Print ratpoison version.  By default, this is bound to @kbd{C-t v}.

@item vsplit
Split the current window vertically in two. The last accessed window not
occupying a frame will be the second window.

@item windows @var{fmt}
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 @kbd{C-t @var{n}} where @var{n}
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 @kbd{C-t '} and type the number at the
prompt.

After 5 seconds the Program Bar disappears.

This command is bound to @kbd{C-t w} by default.

When invoked from the command-line like this,

@example
$ ratpoison -c windows
@end example

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. This is where @var{fmt} comes into play. If
@command{windows} is given an arg it treats it as the format string as
described in @command{defwinfmt}.

@end table

@node Command Line Arguments, Startup file, Commands, Top
@chapter Command Line Arguments
ratpoison supports command line arguments to request various actions
when invoking ratpoison.

@table @code
@item -h, --help
Display this help screen

@item -v, --version
Display the version

@item -r, --restart
Restart ratpoison

@item -k, --kill
Kill ratpoison

@item -c, --command
Send ratpoison a colon-command. This allows you to control ratpoison
from the command-line. with the @option{-c} option you can script
ratpoison using any programming language that can spawn a
process. Some commands behave differently when invoked this
way. Currently the only command that behaves differently is the
@code{windows} command. Instead of displaying the window list in a
message window, it is printed to stdout. The output can then be
captured and used in the ratpoison script. For instance, this could be
used to check whether a program is running and if it is switch to its
window otherwise launch it.

@end table


@node Startup file,  , Command Line Arguments, Top
@chapter Startup file

Now you've probably read the web page, and you've no doubt dug up some
old file I forgot about. You're probably wondering, ``say, didn't he say
there was no configuration file to customize?''. Okay, ya got me. But lets
be honest here: ratpoison is so pure and fast-acting, customization is
barely worth the extra effort. In the off chance that you need to make
ratpoison your own, we now support it. 

On startup ratpoison looks for @file{~/.ratpoisonrc} and runs it through
the command parser. If @file{~/.ratpoisonrc} does not exist, ratpoison
tries @file{/etc/ratpoisonrc}. This means any command you can bind a key
to or run at the command prompt (@kbd{C-t :}) you can execute in this rc
file.

@bye