This is ratpoison.info, produced by makeinfo version 4.0f from
ratpoison.texi.

INFO-DIR-SECTION X11
START-INFO-DIR-ENTRY
* ratpoison: (ratpoison).       Say good-bye to the rodent
END-INFO-DIR-ENTRY

   This is the ratpoison user manual.

   Copyright (C) 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.


File: ratpoison.info,  Node: Top,  Next: About,  Prev: (dir),  Up: (dir)

   This document explains how to use ratpoison.

* Menu:

* About::                       What is ratpoison?
* Contacting::                  How do I contact the ratpoison developers?
* Concepts::                    Window manipulation concepts
* General Use::                 How does this thing work??
* Splitting Frames::            When you want to see more than one window
* Multiple Monitors::           What to do with all your computer junk
* Keystrokes::                  Key commands and functionality
* Commands::                    ratpoison commands
* Input::                       Typing text into ratpoison
* Command Line Arguments::      ratpoison command-line actions
* Startup file::                They threatened me...with violence!


File: ratpoison.info,  Node: About,  Next: Contacting,  Prev: Top,  Up: Top

About
*****

   ratpoison is a simple Window Manager with no fat library
dependencies, no fancy graphics, no window decorations, and no rodent
dependence. 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
(<sabetts@users.sourceforge.net>).


File: ratpoison.info,  Node: Contacting,  Next: Concepts,  Prev: About,  Up: Top

Contacting
**********

   ratpoison is hosted on <sourceforge.net>. To see the latest
developments in ratpoison go to
<http://www.sourceforge.net/projects/ratpoison> or visit the ratpoison
webpage at <http://ratpoison.sourceforge.net>.

   There is also a ratpoison mailing list:
<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.


File: ratpoison.info,  Node: Concepts,  Next: General Use,  Prev: Contacting,  Up: Top

Concepts
********

   ratpoison uses the concept of "panes" to place and size windows.
Instead of allowing windows to have arbitary shapes at arbitary
locations on the screen, the display is divided into panes, the same
way a physical window might contain several pieces of glass seperated
by wood. In ratpoison, the panes are called "frames", and windows are
placed in them, maximised. ratpoison starts with one frame, which can
be split into an arbitary number of smaller ones. Each frame can be
split in half either horizontally or vertically. You can move among
them, making different ones the current. For more information, see
*Note Splitting Frames::.

   Each frame has at most one window associated with it, which is
visible in that frame. If you select a window that is associated with a
frame, the focus will move to its associated frame, rather than moving
the window to the current frame. If you select a window that is not
associated with a frame, that window will be opened in the current
frame and resized to fit that frame.

   If the window associated with a frame does not fill the frame
completely, the various gravity commands control how it is placed.

   If no window was open in that frame before the current window was
opened, the X root will be visible behind it.

   Transient windows (dialog boxes, splash screens, and the like) are
handled specially. In order to understand the contents of a transient
window, the previously focused window is often required. Take a search
window, it is useful to be able to see the document you are searching
as well as the search window. For this reason transient windows appear
overtop (according to their gravity) of the previously focused window.


File: ratpoison.info,  Node: General Use,  Next: Splitting Frames,  Prev: Concepts,  Up: Top

General Use
***********

   When ratpoison starts you should see an empty X server. To open an x
terminal hit `C-t c'. You can now run shell commands as you would on
any terminal. Notice the terminal maximized full screen. `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 `C-t w'.
Each window has a number. You can jump to a window by hitting `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 `C-t ''.

   ratpoison allows you to cycle through the windows with `C-t n' and
`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? It's modern
computing at its best.


File: ratpoison.info,  Node: Splitting Frames,  Next: Multiple Monitors,  Prev: General Use,  Up: Top

Splitting Frames
****************

   Sometimes you may want to see two or more windows at the same time.
ratpoison allows you to split the display into frames (see *Note
Concepts::). Each frame can then contain 1 window. To split the current
frame horizontally use `C-t s'. To split the current frame vertically
use `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
`C-t tab' to cycle through the frames. If you want to remove a frame
use `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 `C-t Q' to remove all splits and
leave you with the current window full screen.


File: ratpoison.info,  Node: Multiple Monitors,  Next: Keystrokes,  Prev: Splitting Frames,  Up: Top

Multiple Monitors
*****************

   When you've finally accumulated enough computer junk, you'll find
youself attaching a second monitor to your computer. ratpoison has
functionality to help you get around your new and improved desktop
space.

   The X Windowing System assigns each monitor a screen number. To
switch to another screen use the commands `nextscreen' and
`prevscreen'. ratpoison will tell you which frame has focus by drawing
the current frame indicator in it.

   Many commands operate only on the current screen. This becomes
apparent when you have 2 screens each with 1 frame. In each frame you
have an xterm. If you try to switch to the other xterm with the command
`other', for instance, you'll get a message "No other window."
ratpoison means there's no other window to switch to in the current
screen. If you want to switch to the other xterm you can switch to it
by name (use `select' or `C-t ''), by number, or you can use
`nextscreen' and `prevscreen'.


File: ratpoison.info,  Node: Keystrokes,  Next: Commands,  Prev: Multiple Monitors,  Up: Top

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.

`C-t C-t'
     Switch to the last window.

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

`C-t 0-9'
     Switch to the numbered window.

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

`C-t A'

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

`C-t K'

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

`C-t n'

`C-t C-n'

`C-t Return'

`C-t C-Return'

`C-t Space'

`C-t C-Space'
     Go to next window.

`C-t p'

`C-t C-p'
     Go to previous window.

`C-t ''

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

`C-t a'

`C-t C-a'
     Display the current time of day.

`C-t c'

`C-t C-c'
     Open a new X terminal.

`C-t :'
     This allows you to execute a single ratpoison command.

`C-t !'
     Run a shell command.

`C-t C-!'
     Run a shell command through an X terminal.

`C-t i'

`C-t C-i'
     Display information about the current window.

`C-t k'

`C-t C-k'
     Close the current window.

`C-t l'

`C-t C-l'
     Redisplay 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.
     `C-t l' will force the current window to maximize.

`C-t m'

`C-t C-m'
     Display the last message.

`C-t v'

`C-t C-v'
     Display the version of ratpoison.

`C-t w'

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

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

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

`C-t tab'
     Cycle through ratpoison's frames.

`C-t M-tab'
     Switch to the last focused frame.

`C-t Q'
     Kill all frames but the current one.

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

`C-t b'

`C-t C-b'
     Banish the mouse to the lower right corner of the screen.

`C-t ?'
     Display a help screen

`C-t f'

`C-t C-f'
     Indicate which frame is the current frame.


File: ratpoison.info,  Node: Commands,  Next: Input,  Prev: Keystrokes,  Up: Top

Commands
********

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

`abort'
     This is a pretty useless command. By default, it is bound to `C-t
     g', and its purpose is to abort other commands.

`alias NAME COMMAND'
     An allows you to name a ratpoison command something else. For
     instance, if you frequently open emacs you may want to make an
     alias called `emacs' that loads emacs. You would do it like this:

          : alias emacs exec emacs

     An alias is treated exactly like a colon command in that you can
     call it from the colon prompt, bind it to a key, and call it
     non-interactively with `ratpoison -c'.

`banish'
     Banish the mouse to the lower right corner of the screen.

`bind KEY 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 `C-t R' to restart ratpoison:

          : bind R restart

     If no command is specified then bind works exactly like `unbind',
     unbinding the key.

`chdir'
     Change the current directory for ratpoison.

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

`colon COMMAND'
     Run a ratpoison command.

`curframe'
     Indicate which frame is the current frame.

`defbargravity G'
     Set the default alignment for the message bar. See the `gravity'
     command.

     When called non-interactively with no arguments, the current
     setting is returned.

`defbarpadding X Y'
     Set the horizontal and vertical padding inside the bar.

     When called non-interactively with no arguments, the current
     setting is returned.

`defbarborder N'
     Set the border width for the bar window.

`defbgcolor COLOR'
     Set the background color for all text ratpoison displays. COLOR is
     any valid X11 color.

`defborder N'
     Set the border width for all windows.

     When called non-interactively with no arguments, the current
     setting is returned.

`deffgcolor COLOR'
     Set the foreground color for all text ratpoison displays. COLOR is
     any valid X11 color.

`deffont FONT'
     Set the font. FONT is a font string like `9x15bold'.

`definputwidth N'
     Set the width of the input window.

     When called non-interactively with no arguments, the current
     setting is returned.

`defmaxsizegravity G'
     Set the default alignment for windows with maxsize hints. See the
     `gravity' command.

     When called non-interactively with no arguments, the current
     setting is returned.

`defpadding LEFT TOP RIGHT BOTTOM'
     Set the padding around the edge of the screen.

     When called non-interactively with no arguments, the current
     setting is returned.

`deftransgravity G'
     Set the default alignment for transient windows. See the `gravity'
     command.

     When called non-interactively with no arguments, the current
     setting is returned.

`defwaitcursor 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.

     When called non-interactively with no arguments, the current
     setting is returned.

`defwinfmt FMT'
     Set the default window format for the `windows' command. By
     default it is `N-W'. The following is a list of valid format
     characters:

    `%n'
          The window number

    `%s'
          Window status (current window, last window, etc)

    `%t'
          Window Name

    `%a'
          Application Name

    `%c'
          Resource Class

    `%i'
          X11 Window ID

    `%l'
          A unique number based on when the window was last accessed.
          The higher the number, the more recently it was accessed.

     When called non-interactively with no arguments, the current
     setting is returned.

`defwinname 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. NAME can be `title' which is what
     most window managers put in the title bar, `name' which is the
     res_name, or `class' which is the res_class.

     When called non-interactively with no arguments, the current
     setting is returned.

`defwingravity G'
     Set the default gravity for normal windows. See the `gravity'
     command.

     When called non-interactively with no arguments, the current
     setting is returned.

`delete'
     This deletes the current window. You can access it with the `C-t k'
     keystroke.

`echo TEXT'
     Display TEXT as a message.

`escape KEY'
     Set the prefix to to KEY. For example `escape C-b' sets the prefix
     key to <C-b>.

`exec COMMAND'
     Execute a shell command. By default, `C-t !' does this.

`focus'
     cycle through ratpoison's frames.

`focuslast'
     Switch to the last focused frame.

`focusup'
     Move to the frame above the current frame.

`focusdown'
     Move to the frame below the current frame.

`focusleft'
     Move to the frame left of the current frame.

`focusright'
     Move to the frame right of the current frame.

`gravity G'
     Change the gravity of the current window. A normal window will
     default to the top-left corner of the screen, but it can also be
     placed at the bottom-right corner of the screen. Valid values for
     G are the 8 directions `northwest', `north', `northeast', `east',
     `southeast', `south', `southwest' and `west', clockwise from the
     top left corner. `center' will center the window in the frame. G
     and can be abbreviated to the standard compass 1 and 2 letter
     abbreviations (i.e. `nw', `s', etc).

`help'
     Display a help screen that lists all bound keystrokes.

`info'
     Display information about the current window.

`kill'
     This destroys the current window. Normally you should only need to
     use `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 `C-t K'.

`lastmsg'
     Display the last message.

`link KEY'
     Call the command that KEY is bound to. For instance `link C-t'
     would call the command `other' and switch to the last window.

`meta'
     Send a `C-t' to the current window.

`msgwait N'
     Set the bar's timeout in seconds.

     When called non-interactively with no arguments, the current
     setting is returned.

`next'
     This jumps you to the next window in the window list. This one is
     bound to three keystrokes, namely `C-t n', `C-t space', and `C-t
     enter'.

`nextscreen'
     This jumps you to the next X11 screen. `nextscreen' is used for
     dual-head displays and multiple monitor setups.

`newwm WINDOW-MANAGER'
     This is a bad-bad command. It kills ratpoison and revives that
     ugly rodent! Yuck! Avoid!

`number N TARGET'
     Set a window's number to N. If another window occupies the
     requested number already, then the windows' numbers are swapped.

     The second argument, TARGET, is optional. It should be the number
     of the window whose number will be changed. If TARGET is omitted
     ratpoison defaults to the current window.

`only'
     Kill all frames but the current one.

`other'
     This toggles between the current window and the last window. By
     default, this is bound to `C-t C-t'.

`prev'
     This jumps you to the previous window in the window list. By
     default, this is bound to `C-t p'.

`prevscreen'
     This jumps you to the previous X11 screen. `prevscreen' is used
     for dual-head displays and multiple monitor setups.

`quit'
     Quit ratpoison.

`redisplay'
     Redisplay the current window, just like `C-t l' would do.

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

`restart'
     Restart ratpoison.

`rudeness 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.

     N 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 `rudeness 5'.
     If a request is not granted ratpoison will tell you about the
     request with a message like `Raise request from window 1 (emacs)'.

`select N'
     This jumps you to window N where N is the window number as shown
     in the Program Bar. You can do the same trick with `C-N' too. To
     select no window, blanking the current frame, type `select -'.

`select WINDOW-NAME'
     Go to a window by name. A shortcut is `C-t ''.

`setenv ENV VALUE'
     Set the environment variable ENV to VALUE

`source FILE'
     Read a text file containing ratpoison commands.

`split'

`hsplit'
     Split the current window horizontally in two. The last accessed
     window not occupying a frame will be the second window.

`startup_message STATE'
     Turn on or off the startup_message. This is most useful in your
     .ratpoisonrc file. STATE can be `on' or `off'.

`title 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 `C-t A' keystroke is bound to this command.

`unbind KEY'
     Unbind a keystroke.

`unsetenv ENV'
     Clear the value of the environment variable, ENV.

`version'
     Print ratpoison version.  By default, this is bound to `C-t v'.

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

`windows 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 `C-t N' where 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 `C-t '' and type the
     number at the prompt.

     After 5 seconds the Program Bar disappears.

     This command is bound to `C-t w' 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. This is where FMT comes into play. If
     `windows' is given an arg it treats it as the format string as
     described in `defwinfmt'.


File: ratpoison.info,  Node: Input,  Next: Command Line Arguments,  Prev: Commands,  Up: Top

Input
*****

   At various times ratpoison will prompt you for input. Currently only
very basic text editing commands exist.

<Backspace>
     Deletes one letter preceding the cursor.

<C-p>
     Cycle backwards through the history.

<C-n>
     Cycle forwards through the history.

   All input is stored in the same history list. By default ratpoison
has a history length of 50 entries.


File: ratpoison.info,  Node: Command Line Arguments,  Next: Startup file,  Prev: Input,  Up: Top

Command Line Arguments
**********************

   ratpoison supports command line arguments to request various actions
when invoking ratpoison.

`-h, --help'
     Display this help screen

`-v, --version'
     Display the version

`-c, --command'
     Send ratpoison a colon-command. This allows you to control
     ratpoison from the command-line. with the `-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 commands that behaves differently are the
     `windows' command and some def* commands. 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.

     It should also be noted that multiple `-c' options can be used.

          $ ratpoison -c split -c split

     Here ratpoison would split the current frame twice.


File: ratpoison.info,  Node: Startup file,  Prev: Command Line Arguments,  Up: Top

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 let's 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 `~/.ratpoisonrc' and runs it through
the command parser. If `~/.ratpoisonrc' does not exist, ratpoison tries
`/etc/ratpoisonrc'. This means any command you can bind a key to or run
at the command prompt (`C-t :') you can execute in this rc file.



Tag Table:
Node: Top1084
Node: About1914
Node: Contacting2507
Node: Concepts3074
Node: General Use4879
Node: Splitting Frames5973
Node: Multiple Monitors7215
Node: Keystrokes8302
Node: Commands11094
Node: Input22869
Node: Command Line Arguments23354
Node: Startup file24551

End Tag Table
