# Using Ratpoison/Printable version

The current, editable version of this book is available in Wikibooks, the open-content textbooks collection, at
https://en.wikibooks.org/wiki/Using_Ratpoison

# Introduction

Welcome to the Using Ratpoison Wikibook.

## Purpose

This is intended to be a book aimed at the intermediate/advanced GNU/Linux user who wants to start using the Ratpoison Window manager.
Thusly, only the window manager itself will be covered- this guide assumes that you have a working system running, from the kernel up to the X11 Windowing System, and it assumes you have competent grasp on Linux- this book will not teach you how to use GNU/Linux in general. Please see your distribution documentation or the Linux Guide to learn Linux in general.

## Who is this guide suitable for?

Basically, any GNU/Linux or BSD user who wants to try something new or exciting, but also the user who wants to experiment with a different approach to mouse usage.

## What is ratpoison?

Ratpoison is a window manager written for X Window, and principally developed by Linux users (though it should run on any operating system and platform X Window does). It is very different from most other window managers in that it is a tiling window manager and because it tries to minimize or completely eliminate the use of the mouse, in order to relieve stress on the arms and shoulders.
In keeping with this old-school approach, ratpoison is also extremely lightweight, and there are no "fat library dependencies", no fancy graphics beyond what other programs provide, and no window decoration. While this might seem odd at first, starting to use it is in fact quite simple. If you've ever used the GNU Screen terminal multiplexer or GNU Emacs, you'll be quite familiar with the interface, since most of the hotkeys and design ideas are borrowed from those programs. Indeed, the developers are very much fans of Emacs, as evidenced in one of the FAQs:
   * "I want feature XYZ."
   ** "What you want is probably already in Emacs. If you don't use Emacs, start. If do use Emacs, use it more. If you *still* can't do what you want to do, you probably shouldn't do it." (sic)

### Pros

* Ratpoison is extremely lightweight and will therefore start up and run very quickly; it will also run well on ancient hardware as well as more modern setups such as a 32-way SPARC.
* Rodent usage is minimized and the keyboard is promoted, relieving your arms and shoulders and decreasing the risk of injury
* Ratpoison works well with multiple monitors.
* Ratpoison key-bindings are very similar to those of GNU Screen and should be familiar to users with experience using Screen.

### Cons

* High learning curve. Not particularly suited for UNIX beginners, without a lot of customization- this is a window manager written by experts for experts, so to speak.
* Some programs like the GIMP (which uses a multitude of small windows) are simply not designed to work with tiling window managers and do not work very well.
* Java GUI applications have some issues with the way Ratpoison handles window parenting and most Java GUI applications will only render as a grey box. (This problem could be solved by issuing 'export AWT_TOOLKIT=MToolkit' command before starting Java app).

## Concepts

To start with, ratpoison has some radically different concepts about using a computer. First, you cannot drag windows around the "desktop", all windows are maximized to the full screen size and that cannot be changed. Because of this, you don't need window decorations, since they would steal precious space. When you look at a program, the only thing you see is the program. You are not forced to look at only one program at a time however: a window can be subdivided into a number of adjacent (but not overlapping!) frames; each of these frames holds a single program which is maximized within its frame. In Emacs terms, there is one window, split into one or more frames, in which each buffer is shown in one and only one frame.

# Your first steps

As stated in the introduction, these instructions assume a working X system.

## Starting ratpoison

To launch ratpoison as your default window manager you need to edit the file .xinitrc in your home directory; this might already have been done for you by a package manager. The file ~/.xinitrc should just contain one line:
Now start your X server:
Within a second or two, you'll see a cursor in the middle of the screen superimposed on a dappled grey background, and a small welcome text in the upper right corner that welcomes you to ratpoison. This welcome message instructs you to type in C-t ? if you have any questions. Now is where the fun starts, but first some background on how to interact with and control ratpoison.

## The almighty escape key

Ratpoison is only controlled by the keyboard; no matter what you click with your mouse on the root window, nothing will happen. Instead, you give it a keyboard command. All ratpoison commands are initiated by typing the escape key sequence. By default, this is Ctrl+t (in Emacs notation, which is preferentially used by ratpoison documentation and users: C‑t). Try typing Ctrl+t, and you'll see that the mouse changes into a white square. This means that ratpoison has taken over the keyboard and is ready to interpret any letter typed as a command (as opposed to normal operation where anything typed is sent to an application to deal with). After typing Ctrl+t, try hit the c key (note that this is a lowercase key; capital C does not currently do anything). Immediately an X terminal opens up and takes over the screen (assuming xterm is installed as it usually is); in other words, the command c creates a console window. Now you can do anything you could do on the command line, and you can even run your graphical programs like Firefox – ratpoison will automatically switch to the newest windows.
Note that if constantly pressing Ctrl+t to prefix all commands is uncomfortable (if you, for example are using the Dvorak keyboard layout) you can change it dynamically or in the configuration file. Please see one of the advanced chapters for more information on adjusting key bindings.

## Key strokes

Try a few different key strokes – you can find the command list in the ratpoison manual or info documentation, or you can type Ctrl+t ?, which will give a brief list of sequences. Remember, all key strokes are preceded with Ctrl+t.
A useful pair of commands are Ctrl+t n (shifts your view to the next window; like conventional alt+Tab ↹) and its inverse Ctrl+t p (shifts your view to the previous window; if you just Ctrl+t n'ed, for example, a Ctrl+t p will take you back to the original window).

# Basic Keystrokes

There are a few important keystrokes that are good to remember while using Ratpoison. When you have started your console window, why stop there? It is time to learn how to execute any program, and to switch between these in an effective manner.

## Switching and killing programs

Assuming that you have your console still running (if not, do Ctrl+t c), you can execute programs from within that window, just like any other window manager. Again, the difference is that there are no borders and that you cannot switch between these programs with your mouse. Type xclock if you are out of ideas about which program to start. Now, to change back to the console window you press Ctrl+t n. N of course means next, so you probably already guessed that Ctrl+t p moves to the previous window. Now, the difference between “next” and “previous” is non-existent if you are running only two programs, but as you run more and more programs simultaneously, it becomes ever more useful to be able to move “forward” and “backward” in some sense.
Now, how do you close a program? A number of programs have their own kill bindings (ex. Ctrl+x Ctrl+c for Emacs, Ctrl+w for Firefox and Xchat etc.) but ratpoison provides one command guaranteed to close and kill all running programs: the Ctrl+t k salute. The k stands for kill, and is implemented much the same way as clicking on the “close” button mainstream window managers provide.

## Handling many programs

Now, if you have got a multitude of programs running, it is tiresome to repetitively type Ctrl+n n enough times to get to the proper program when you need it. Ctrl+t number switches to a certain window. Keep in mind that this list is zero-indexed and sorted chronologically—the first program started is accessed via Ctrl+t 0, not 1.
Also, you can use Ctrl+t instead of Ctrl+t n to move to the next program. If you want to do a quick alt tab-like (that is, switch to last program accessed) command, Ctrl+t Ctrl+t will do that.

# Advanced Usage

This section deals with largely modifying keys and commands to do other things and to extend ratpoison's functionality.

# Aliasing
## The command shell

Ratpoison has a built-in "run" dialog, a quick way to launch any program without having to start a console. Type C-t ! to get a little command box from which you can launch your program. This is most useful for launching graphical applications without tying up a console, as you won't be able to see any of the output of any purely command line programs.
From the same command prompt you can invoke the ratpoison command to tweak settings and do various actions. All these commands can be looked up in the mainpage, and they are all preceded by ratpoison -c.
For example, to set the "rudeness level" to five (will be explained soon) you type ratpoison -c rudeness 5.
All these commands can of course be executed from within a console window; C-t ! is simply a more convenient variant of a command shell.

### Aliasing

As mentioned before, ratpoison can be thought of as GNU Screen for window managing; like command line shells, it is possible to alias long commands to shorter versions.
This can be done through the extended command ability (which resembles C-t !), which is invoked via "C-t :". This opens a little box just like C-t ! does, but instead of executing shell commands, the input will be sent to ratpoison which will attempt to interpret this input as a ratpoison command; suppose one often runs Mozilla Firefox, but one grew weary of always opening a shell with C-t c and then typing in "mozilla-firefox &" (the ampersand is necessary so you can use the terminal for other things, otherwise the terminal will simply display any error or informative messages Firefox emits), or "C-t ! mozilla-firefox"?
One could decide to use a shorter name- input C-t :, and enter in "alias firefox exec mozilla-firefox", which would allow one to simply C-t: firefox, and Firefox would open up; one could even go C-t: "alias f exec mozilla-firefox" if they were rather lazy, and used no other programs beginning with the letter "f".
Aliasing is not limited to regular program names- if one drops the "exec", one could alias the command "quit" to "q": "C-t : alias q quit".
As a matter of fact, all the keyboard shortcuts one has learned for ratpoison, like C-t p, they all are actually aliases for longer commands! C-t q (which quits ratpoison) is actually an alias for C-t : quit. This is another area of borrowing from Emacs- Emacs similarly represents all keys on a keyboard and all combinations thereof, as aliases of Emacs functions.
(In these examples the command "exec" is necessary to have ratpoison evaluate the succeeding string as a shell command, and not another ratpoison command. Please see the official documentation on exec for more details; exec essentially does the same thing as C-t !).

# External Resources
## Documentation

* Official homepage
** HTML version of the info manual
* ratpoison wiki

## Addon programs

* Debian package page for ratmenu, an add-on program for ratpoison
* Homepage for ratmen; same purpose as ratmenu, but author claims it is superior
* Summary page (Savannah) of Xbindkeys, another program that works well with ratpoison