Using Ratpoison/Printable version

Using Ratpoison

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

Permission is granted to copy, distribute, and/or modify this document under the terms of the Creative Commons Attribution-ShareAlike 3.0 License.

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

1. 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.
2. Rodent usage is minimized and the keyboard is promoted, relieving your arms and shoulders and decreasing the risk of injury
3. Ratpoison works well with multiple monitors.
4. Ratpoison key-bindings are very similar to those of GNU Screen and should be familiar to users with experience using Screen.

Cons

1. 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.
2. 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.
3. 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:

ratpoison

Now start your X server:

startx

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 !).

Example Config

   #.ratpoisonrc --- my own ratpoison customizations
   
   #Copyright (C) 2006 by maru dubshinki
   
   #Author: maru dubshinki <marudubshinki0@gmail.com>
   #License: BSD license, minus advertising clause.
   #Where: http://en.wikipedia.org/wiki/User:Marudubshinki/.ratpoisonrc
   #When:  Time-stamp: "2006-09-06 18:22:39 maru"
   #Keywords: local,customization,ratpoison
   
   #Commentary
   #This is my own all-singing all-dancing personal ratpoisonrc. 
   #It depends on two scripts, rpws, and expose (which can either be gotten
   #at Reactorcore or at the ratpoison wiki) and a number of other programs, chief
   #among which are xclip, surfraw, and firefox.
   #Anyway, there are three main sections, so to speak.
   #The first tweaks some ratpoison settings directly. The main feature of 
   #note is the changing of the escape sequence from two keys, C-t, to a single
   #key (called by ratpoison "less"), and the mirroring of less with another key,
   #so there are actually two equivalent escape keys.
   #The second section runs a number of programs like unclutter. This section generally
   #modifies X, modifies the keybindings (i.e making caps lock a control), and runs some
   #useful programs if possible.
   #The third section handles application key bindings. My general philosophy here has 
   #been to make the lower-case key invoke the "heavy" or feature-rich version of the 
   #idealized type of application, and the uppercase one runs a different, smaller and 
   #lighter-weight application which does much the same thing. For example, d runs 
   #Firefox, and D runs terminal elinks. e runs Emacs, and E runs nano in a terminal.
   #And so on.
   
   ##change directory to $HOME
   chdir
   
   ##What's the shell?
   alias term exec aterm
   
   ##Banish the mouse with each screenchange
   #addhook switchwin banish
   
   ##Setting the prefix keys
   ###Set the ctrl-t key to something easier
   escape less
   
   ###Set the ctrl-t key to something easier
   definekey top Insert readkey root
   definekey root Insert link less
   
   ##Set the mouse warping option.
   warp on
   
   ##Hush up, ratpoison. I know what the prefix key is.
   startup_message off
   
   ##There are three different ways ratpoison can "name" frames.
   ##By title, name, or class. Title gets you gunk like "emacs@localhost.localdomain";
   ##but name and class give you the sensible "emacs" or "Emacs". 
   set winname class
   
   ##Graphics tweaks
   ###Not quite sure what these do, copied from Reactor Core.
   ###Supposedly make borders take up less space.
   defborder 0
   defpadding 0 0 0 0
   defbarpadding 0 0 
   
   #This was suggested on the ratpoison wiki as a way to
   #make messages clearer. Doesn't work right now. Maybe I have the wrong
   #font name?
   #deffont -etl-*-*-r-*-*-*-400-*-*-*-*-*-*
   
   ##What programs do we run on startup?
   ###Do some key re-mapping
   exec xmodmap -quiet ~/.Xmodmap
   
   ###Apparently modifies some low-level GUI bits of X.
   exec xrdb -load ~/.Xresources
   
   ###Change the background and pointer in X
   #exec xsetroot -solid black -cursor_name left_ptr
   exec xsetroot -cursor_name left_ptr
   
   ###I like astronomical images. Let us make use of xplanet.
   #exec xplanet -body earth -fork -random -light_time -transparency -wait 60
   
   ####This is an alternative- setting electricsheep as the background.
   #exec electricsheep --root 1 --nick maru --zoom 1 --mplayer 1 --history 50 &
   
   ###Set a background, randomly picking from a certain directory.
   exec cd ~/pics && xsetbg -border black -fork -type jpeg -fit -onroot -fullscreen `w=(*.jpg); n=${#w[@]}; echo "${w[RANDOM%n]}"` && cd ~/
   #exec xsetbg -border black -fork -type jpeg -fit -onroot -fullscreen `w=(*.jpg); n=${#w[@]}; echo "~/pics/${w[RANDOM%n]}"`
   
   ###Run unclutter so the mouse hangs around no longer than needed.
   exec unclutter -idle 1 -jitter 2 -root
   
   ###I use xscreensaver as a screensaver. The first line makes sure any running xscreensaver is killed.
   ###The second starts and backgrounds xscreensaver
   exec xscreensaver-command -exit
   exec xscreensaver &
   
   ###This should set up rpws and groups
   ###http://ratpoison.elektrubadur.se/rpws
   exec rpws -i
   exec rpws -b
   ###This should be pretty obvious. Why not use function keys?
   bind F1 exec ~/bin/rpws 1
   bind F2 exec ~/bin/rpws 2
   bind F3 exec ~/bin/rpws 3
   bind F4 exec ~/bin/rpws 4
   bind F5 exec ~/bin/rpws 5
   bind F6 exec ~/bin/rpws 6
   bind F7 exec ~/bin/rpws 7
   bind F8 exec ~/bin/rpws 8
   bind F9 exec ~/bin/rpws 9
   bind F10 exec ~/bin/rpws 10
   bind F11 exec ~/bin/rpws 11
   bind F12 exec ~/bin/rpws 12
   
   ###xbindkeys can alias for some neat things.
   #This is last- low priority. Commented out, currently does nothing,
   #exec xbindkeys
   
   
   
   
   ##aliasing keys within ratpoison
   ###make semicolon invoke ratpoison command, and colon shell command.
   bind semicolon colon
   bind colon exec
   
   ###Show-the-root-window script
   alias showroot exec ratpoison -c fdump; ratpoison -c 'select -' -c only
   alias unshowroot exec ratpoison -c "frestore `cat $HOME/.rpfdump`"
   #bind B showroot
   
   ###Change the date from 24-hour to 12-hour
   bind a time
   
   ###(Getting a root terminal. There is no binding for "c", since that
   ###is a default binding, to a terminal.)
   ###I've since changed this since I don't use it very often.
   #bind C exec ssh -X root@127.0.0.1 aterm
   bind C colon exec aterm -e 
   
   ###Shortcut for emacs. Emacsclient is called, but it expects
   ###a filename. This can be circumvented by instructing it to
   ###instead evaluate a Emacslisp expression- the current one
   ###says "open up a new frame on the current display device".
   ###It has to be quoted or else sh will try to open up the lisp
   ###expression in a sub-shell as a shell command.
   ###Neatly, if an emacs isn't already running, then emacsclient runs
   ###$EDITOR, which points back to regular emacs!
   bind M-e exec emacsclient --eval '(make-frame-command)'
   ###Shortcut for nano
   bind M-E exec aterm -e nano
   
   ###Shortcut for firefox
   bind d exec mozilla-firefox
   #bind d exec mozilla-firefox & ratpoison -c "title firefox"
   
   ###A new hack using xclip (which prints out the current text selection) to
   ###open up a new tab in a running firefox with the address as the current selection.
   ###The idea is, you highlight an URL and then instead of manually inputting it,
   ###simply whack R-b ('b' standing for "browse").
   #bind b exec mozilla-firefox -new-tab `xclip -o`
   bind B exec mozilla-firefox -new-tab `$RATPOISON -c getsel`
   bind b colon exec mozilla-firefox 
   
   ###Shortcut for elinks
   bind D elinks http://www.google.com/
   #bind B elinks http://www.google.com/
   
   ###Shortcut for dillo- currently I use elinks instead. dillo's 
   ###keyboard commands are too awkward as of yet.
   #bind D exec dillo
   
   ###Shortcut for gqview
   bind g exec gqview +t
   
   ###Binding for xpdf
   bind x exec xpdf
   
   ###Runs a perl script which emulates the Mac's expose feature.
   ###http://ratpoison.elektrubadur.se/expose.pl
   bind w exec ~/bin/expose.pl
   
   ###Runs a shell script which creates an alt-tab menu analog
   ###http://reactor-core.org/ratpoison-config.html
   bind W exec ~/bin/windows
   
   ###Make prtscreen work, as long as in ratpoison mode. "import" is an Imagemagick command.
   bind Print exec import -window root png:$HOME/xwd-$(date +%s)$$.png
   
   ###Crikey, I'm gonna need a separate section just for surfraw shortcuts.
   ###Anyway, the model for these (thanks to aon) is "bind r colon exec surfraw wikipedia "- note
   ###the space. If the space isn't there, then the user will need to manually add a space, which is not good
   ###In the shell, one can omit the surfraw command, but not in ratpoison, as ratpoison's PATH currently does
   ###not include the directory with the elvi in it.
   ###List of useful surfraw elvi follows:
   ###amazon bbcnews cia cite cnn debbugs debcontents deblists deblogs debpackages debpts deja dmoz ebay etym freshmeat google imdb rfc rhyme slashdot sourceforgen translate
   
   ###Surfraw aliases.
   alias cnn exec surfraw cnn
   alias debbugs exec surfraw debbugs
   alias debbug debbugs
   alias debpackages exec surfraw debpackages
   alias google exec surfraw google
   alias gutenberg exec surfraw gutenberg
   alias surfraw exec surfraw
   alias wayback exec surfraw wayback
   alias wikipedia exec surfraw wikipedia
   alias wookieepedia exec wookieepedia
   
   ###Surfraw keybindings
   bind t colon wikipedia 
   #bind t exec wikipedia `xclip -o` #See previous comment for R-b
   bind T exec wikipedia `$RATPOISON -c getsel`
   bind E google `$RATPOISON -c getsel`
   bind e colon google 
   #bind T colon google 
   bind Y colon wayback 
   bind y colon wookieepedia 
   bind u colon debbugs 
   bind U colon debpackages 
   
   ##Aliasing long commands within ratpoison
   ###Leaving open the option to use conkeror, a skin over firefox.
   ###Wish I could get sane tabbed browsing in it...
   alias conkeror exec mozilla-firefox -chrome chrome://conkeror/content
   alias elinks exec aterm -e elinks

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