Provided by: ratpoison_1.4.9-1_amd64 bug

NAME

     ratpoison — window manager without mouse dependency

SYNOPSIS

     ratpoison [-hv]
     ratpoison [-d dpy] [-s num] [-f file]
     ratpoison [-d dpy] [-s num] [-i] -c command [-c command ...]

DESCRIPTION

     ratpoison is a Window Manager without fat library dependencies, fancy graphics or rat
     dependence.

     The screen can be split into non-overlapping frames.  All windows are kept maximized inside
     their frames.

     All interaction with the window manager is done through keystrokes.  ratpoison has a prefix
     map to minimize key clobbering.

     The options are as follows:

     -c, --command
         Send ratpoison a command.  There must be a ratpoison instance running as window manager
         for the given display/screen for this to work.  Do not forget to quote the command if it
         contains spaces.  For example:
               ratpoison -c "echo hello world"

     -d, --display display
         Set the X display to use or send commands to.

     -f, --file filename
         Specify an alternate configuration file.  If this is not given, ratpoison will try
         $HOME/.ratpoisonrc and if that does not exist /etc/ratpoisonrc and execute each command
         when starting up.

     -h, --help
         Show summary of options.

     -i, --interactive
         Execute commands given with -c or --command in interactive mode.  That means it will
         behave exactly as if called with C-t : like prompting for missing arguments and things
         like that.

     -s, --screen number
         Only use the specified screen.

     -v, --version
         Show version of program.

KEY BINDINGS

     To avoid conflicts with other programs, all default ratpoison key bindings start with an
     escape key, per default C-t (read Control-t).  Some important default key bindings:

     C-t ?   Show key bindings

     C-t c   Start an X terminal

     C-t n   Switch to next window

     C-t p   Switch to previous window

     C-t 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
             Switch to window number 1 | 2 | ...

     C-t k   Close the current window

     C-t K   XKill the current application

     C-t s | S
             Split the current frame into two vertical | horizontal ones

     C-t Tab | Left | Up | Right | Down
             Switch to the next | left | top | right | bottom frame.

     C-t Q   Make the current frame the only one

     C-t :   Execute a ratpoison command

     Further default key bindings can be found in parentheses after the commands in the next
     section.

COMMANDS AND DEFAULT ALIASES

     abort   (C-t C-g) Do nothing and that successfully.  (Useful if you pressed C-t in error).

     addhook event command
             Add a hook: run command whenever event is called.  Possible events are:

             deletewindow
                     Run after a window is withdrawn.

             newwindow
                     Run after a new window is mapped.

             key     Run whenever a top level key is pressed (by default C-t).

             quit    Run before exiting ratpoison.

             restart
                     Run before restarting ratpoison.

             switchframe
                     Run after a frame actually switched, but before the window in it is focused.

             switchgroup
                     Run after selecting a new group.

             switchscreen
                     Run when the user switches to a different screen.

             switchwin
                     Run after a new window is selected.  (With dedication, it may already be
                     inactive again, if it was put into another frame)

     alias alias command
             Add alias as new way to call command.

     bind key command
             alias for "definekey root key command"

     banish  (C-t b) Banish the rat cursor to the lower right corner of the screen.

     banishrel
             Banish the rat cursor to the lower right corner of the current window.  If there
             isn't a window in the current frame, it banishes the rat cursor to the lower right
             corner of the frame.

     chdir [directory]
             If the optional argument is given, change the current directory of ratpoison to
             directory.  If nothing is given, change it to the value of the environment variable
             "HOME".

     clrunmanaged
             Clears the unmanaged window list.

     cnext   Like next but switch to the next window with another resource class than the current
             one.  (That means the next window belonging to another type of application than the
             current one.)

     cprev   Like prev but switch to the previous window with another resource class than the
             current one.  (That means the previous window belonging to another type of
             application than the current one.)

     colon ratpoison-command (C-t :)
             Execute ratpoison-command interactively.  (i.e. ask for possible missing arguments.)

     cother  Like other but switch to the window of the current group that was last accessed and
             has another resource class but is not currently visible.

     curframe (C-t F)
             Show a bar marking the current frame.

     definekey keymap key command
             Add a new key binding in keymap for key to execute command.  Default keymaps are top
             normally only containing C-t, which reads a key from root, containing all the normal
             commands.

             Note that you have to describe ":" by "colon", "!" by "exclam" and so on.  If you
             cannot guess a name of a key, try either C-t key and look at the error message, or
             try :describekey root and pressing the key.

     dedicate [0 | 1]
             Consider the current frame dedicated/chaste (1) or promiscuous (0).

             A dedicated frame will not accept new windows.  When new windows are to be focused,
             they will be opened in a non-dedicated frame instead.

             If no argument is given, toggle the current dedicateness. By default no windows are
             dedicated.

     delete (C-t k)
             Close the current window.

     delkmap keymap
             Deletes the keymap named keymap, that was generated with newkmap.  The keymaps top
             (or whatever was specified by set topkmap) and root cannot be deleted.

     describekey keymap
             Grab the next key. Similar to readkey, describekey shows only the command in keymap,
             that would be executed by readkey.

     echo text
             Show text as ratpoison message.

     escape key
             Update the default escape key to key.

             Strictly speaking it updates the readkey root command in the keymap top to key, the
             other binding in root to key, and meta binding in root to key without modifiers or
             C-key if key has no modifiers.  (If set topkmap was called with an argument other
             than top that will be used instead of top.)

     exchangedown (C-t C-Down)
             Exchange the window in the current frame with the window in the frame below the
             current frame.

     exchangeleft (C-t C-Left)
             Exchange the window in the current frame with the window in the frame left of the
             current frame.

     exchangeright (C-t C-Right)
             Exchange the window in the current frame with the window in the frame right of the
             current frame.

     exchangeup (C-t C-Up)
             Exchange the window in the current frame with the window in the frame above the
             current frame.

     exec shell-command (C-t !)
             Spawn a shell executing shell-command.

     execa shell-command
             Spawn a shell executing shell-command, without remembering the current frame, so
             that _NET_WM_PID declaring programs will be placed into the frame active when they
             open a window instead of the frame active when ratpoison gets this command.

     execf frame shell-command
             Spawn a shell executing shell-command, showing _NET_WM_PID supporting programs in
             the given frame instead of the frame selected when this program is run.

     fdump [screenno]
             Output the defining data for all frames of the current screen, or for screen number
             screenno if this is specified.

     focus (C-t Tab)
             Focus the next frame.

     focuslast
             Switch to the last selected focus.

     focusleft (C-t Left)
             Switch to the frame to the left of the current one.

     focusdown (C-t Down)
             Switch to the frame beneath the current one.

     focusright (C-t Right)
             Switch to the frame to the right of the current one.

     focusprev
             Focus the previous frame.

     focusup (C-t Up)
             Switch to the frame above the current one.

     frestore frames
             Replace the current frames with the ones specified in frames in the format as
             generated by fdump.

     fselect [frameno] (C-t f)
             If an argument is supplied, switch to a frame given by number frameno.

             If no argument is given, show a frame selector in each frame and wait for a key to
             be pressed.  If the key matches an existing frame selector, this frame gets focused.

             Frame selectors are by default the numbers starting with zero, but they can be
             changed by setting framesels.

     gdelete [group]
             If the optional argument group is supplied, delete group.  Otherwise delete the
             current group. If the last group is deleted, a new group with name default is
             created.  The group has to be empty, otherwise it cannot be deleted.

     getenv variable
             Output the value of the environment variable variable.

     getsel  Paste the current X Selection into the current window.

     gmerge group
             Move all windows from group group into the current group.

     gmove group
             Move the current window into group group.

     gnew group
             Create a new group with name group and select it.  Most window commands only see
             (and thus select, consider next, previous or last) windows within the group active
             when they are issued.

     gnewbg group
             Create a new group named group, but do not select it.

     gnext   Select the next group.  Most window commands only see windows in the effective
             group.

     gnumber [old new]
             Give the number new to the group with the number old or the current group.

     gother  Select the last accessed group.  Most window commands only see windows in the
             effective group.

     gprev   Select the prior group.  Most window commands only see windows in the effective
             group.

     gravity [nw | w | sw | n | c | s | ne | e | se]
             Change how in its frame the current window is aligned.

     grename
             Rename current group.

     groups  Output a list of all groups with their number.

     gselect group
             Select the group named group.

     help [keymap]
             If the optional parameter keymap is given, list all keybindings in this keymap,
             otherwise list all key bindings in keymap root.

     hsplit [l/p | [-]pixels] (C-t S)
             Split the current frame into left frame and a right frame.  If no parameter is
             given, split in halves.  If two numbers separated by a slash (‘/’) are given, the
             left one is l times the pth part and the right one (p - l) times the pth part of the
             prior width.  Otherwise the right half is pixels wide or the left one is pixels
             wide, depending whether there is ‘-’ in front of the number or not.

     inext   Like next but switch to the next window with the same resource class as the current
             one.  (That means the next window belonging to the same application as the current
             one.)

     info (C-t i)
             Output the current the width, height, window number and window name of the current
             window.  (What name means is chosen by “set winname”.)

     iprev   Like prev but switch to the previous window with the same resource class as the
             current one.  (That means the previous window belonging to the same application as
             the current one.)

     iother  Like other but switch to the window of the current group that was last accessed and
             has the same resource class but is not currently visible.

     kill (C-t K)
             Close the X-connection of the X-client responsible for the current window.

     lastmsg (C-t m)
             Reshow the last message.

     license (C-t V)
             Show ratpoison's license.

     link key [keymap]
             Do what key is bound to in the keymap keymap if supplied.  Otherwise what key is
             bound to in keymap root.

     listhook event
             List all commands specified with addhook to be executed when even event occurs.

     meta [key] (C-t t)
             Send the escape key (that which normally is C-t) to the current window.  If a key is
             specified, this is sent instead.  Note that some applications by default ignore the
             synthetic key that is sent using this command as it is considered a security hole.
             xterm is one such application.

     msgwait [seconds]
             Set the duration the message window is shown.  If seconds is zero, wait infinitely.
             This command is deprecated, please set the msgwait variable instead.

     newkmap keymap
             Generate a new keymap named keymap.  This keymap can be used to add new key-command
             mappings to it with definekey and can be called with readkey.

     newwm new-window-manager
             Quit ratpoison and execute new-window-manager instead.

     next (C-t Return | C-t n | C-t space)
             Switch to the next window in the current group.

     nextscreen (C-t N)
             Switch to the next screen. (If you have multiple physical ones.)

     number new [old]
             Give the number new to the window with the number old or the current window.

     only (C-t Q)
             Remove all frames on the current screen except the current frame and maximize this
             one to the size of the whole screen.

     other (C-t C-t)
             Switch to the window of the current group that was last accessed but is not
             currently visible.

     prev (C-t p)
             Switch to the previous window in the current group.

     prevscreen (C-t P)
             Switch to the previous screen. (If you have multiple physical ones.)

     prompt [prompt]
             ratpoison will ask the user for input, showing prompt (or a single colon, if no
             argument is given) and output the input the user has made.  Note that this command
             probably does not make much sense in interactive mode.

     putsel x-selection
             Replace the X selection with the text x-selection.  It can be inserted into the
             current window with getsel.

     quit    Quit ratpoison.

     ratinfo
             Display the x y coordinates of the rat cursor relative to the screen.

     ratrelinfo
             Display the x y coordinates of the rat cursor relative to the current window or
             current frame if no window is focused

     ratwarp x y
             Move the rat cursor to the position (x, y).

     ratrelwarp deltax deltay
             Move the rat cursor to (deltax, deltay), relative to the current position.

     ratclick [button]
             Simulate a rat click with button (button 1=left button if none given).

     rathold {up | down} [button]
             Simulate pressing|releasing rat button button (1=left button if none given).

     readkey keymap
             Grab the next key pressed, and execute the command associated to this key in keymap.
             To show it is waiting for a key, ratpoison will change the rat cursor to a square if
             waitcursor is set.  This command is perhaps best described with its usage in the
             default configuration: by pressing C-t, which is the only key in the keymap top ,
             the command "readkey root" is executed.  The next key then executes the command in
             keymap root belonging to this command.

     redisplay (C-t l)
             Extend the current window to the whole size of its current frame and redisplay it.
             (Useful to redisplay normal windows or bring transient windows to the full size of
             the frame as only normal windows are maximized by ratpoison)

     redo (C-t U)
             Revert the last undo of frame changes.

     remhook event command
             Remove command command from the list of commands to be called when event event is
             hit.  (The command has to specified, as an event can have multiple commands attached
             to it.)  Use "listhook hook" to get a list of all attached commands.

     remove (C-t R)
             Remove the current frame and extend some frames around to fill the remaining gap.

     removedown (C-t M-Down)
             Kill frames directly below the current frame, extending the current frame as much as
             possible.

     removeleft (C-t M-Left)
             Kill frames directly left of the current frame, extending the current frame as much
             as possible.

     removeup (C-t M-Up)
             Kill frames directly above the current frame, extending the current frame as much as
             possible.

     removeright (C-t M-Right)
             Kill frames directly right of the current frame, extending the current frame as much
             as possible.

     resize [deltax deltay] (C-t r)
             If deltax and deltay are supplied, resize the current frame by that (i.e. move the
             bottom right corner by the given offsets and then move this frame and resize
             adjacent frames to make the frames fill the whole screen again.)

             If in interactive mode no arguments are supplied, resize the current frame
             interactively:

               Return         finish resizing
               C-g, Escape    abort resizing
               C-n, Down, j   grow vertically
               C-p, Up, k     shrink vertically
               C-f, Right, l  grow horizontally
               C-b, Up, h     shrink horizontally
               s              shrink to size of current window

             While resizing interactively, changes are in multiples of the amount of pixels given
             by set resizeunit (by default 10).

     restart
             Restart ratpoison.

     rudeness [rudeness]
             This command is deprecated, please use the rudeness variable instead.

     sdump   Output the list of all screens.  The screens are separated by commas. Each screen is
             shown as 6 values: its number, its x-coordinate, its y-coordinate, its width, its
             height and if it is currently selected (1=true, 0=false).

     select {- | name | number} (C-t ')
             If a number is given, switch to the window with number number.  If a name is given,
             switch to the window in the current group with name name.  Blank the current frame,
             if - is given.

     set [variable [value]]
             If no argument is given, output all ratpoison variables and their values.

             If one argument is given, output the value of ratpoison variable variable.
             Otherwise set variable to value.  What values are valid depends on the variable.
             See the section VARIABLES later in this document for details.

     setenv variable value
             Set the environment variable variable to value.  (Environment variables will be
             passed to all programs started from ratpoison.)

     sfdump  Output all frames similar to fdump, but not limited to one screen, but all screens
             at once and with the screen number after each frame.

     sfrestore frames
             Replace the current frames with the ones specified in frames in the format as
             generated by sfdump.

     shrink  Shrink the current frame to the size of the current window with in.

     split [split] (C-t s)
             alias for vsplit

     source file
             Read file and execute each line as ratpoison command.

     sselect screennumber
             Switch to the screen screennumber.  (If you have multiple physical ones.)

     startup_message {on | off}
             Select whether ratpoison will show a startup message or not.  This command is
             deprecated, please use the startupmessage variable instead.

     swap dest-frame [src-frame] (C-t x)
             Exchange the window in src-frame (or the current frame if there is no second
             argument) with the window dest-frame (or ask interactively which frame to swap with
             if there is no argument).

     time (C-t a)
             Output current data and time.

     title newname (C-t A)
             Overwrite the title of the current window with newname.  All following ratpoison
             commands will only know the window under the new name.

     tmpwm tmpwm
             Temporarily give control over to the other window manager tmpwm, reclaiming control
             when that WM terminates.

     unalias alias
             Remove the alias alias.

     unbind key
             alias for
                   undefinekey root key

     undefinekey keymap key
             Remove the binding for key from keymap.

     undo (C-t _, C-t u)
             Un-do the last change to the frameset.  (Like splitting, resizing, deleting, ...)

             The amount of steps that can be undone is specified by the variable maxundos.

     unmanage [name]
             Add name to the list of unmanaged windows.  Thus, windows of this name will not be
             managed but allowed to choose their position themselves.

             In non-interactive mode calling it without arguments will print the list.

             The list can be cleared again by calling clrunmanaged.

     unsetenv variable
             Remove variable variable from the list of environment variables.

     verbexec cmdline
             Spawn a shell executing cmdline after showing a message with the command.

     version (C-t v)
             Output version and compile time information.

     vsplit [l/p | pixels-from-top | -pixels-from-bottom] (C-t s)
             Split the current frame into upper frame and a lower frame.  If no parameter is
             given, split in halves.  If two numbers separated by a slash (“/”) are given, the
             upper one is l times the pth part and the lower one (p - l) times the pth part of
             the prior height.  Otherwise the lower one is pixels from bottom wide or the upper
             one pixels from top high, depending whether there is a “-” in front of the number or
             not.

     warp {on | off}
             Select if focusing a window moves the rat cursor to the place it had been last time
             this window was focused, or not.  This command is deprecated, please set the warp
             variable instead.

     windows [format] (C-t w)
             In interactive mode, show the list of all windows in the current group for the
             duration specified by the variable msgwait.  If msgwait was zero, toggle between
             indefinitely showing and not showing.

             The messages are shown in columns or rows depending on the value of winliststyle in
             the format set by set winfmt.  The following substitutions happen in format:

               %a  application name (resource name)
               %c  resource class
               %f  frame number
               %g  gravity of the window
               %h  height of the window
               %H  unit to resize the window vertically (height_inc)
               %i  X Window ID
               %p  process ID
               %l  last access number
               %M  string Maxsize, if it specifies a maximum size
               %n  window number
               %s  window status (‘*’ is active window, ‘+’ would be chosen by other, ‘-’
                   otherwise)
               %S  screen number
               %t  window name (see set winname),
               %T  the string “Transient”, if it is a transient window
               %w  width of the window
               %W  unit to resize the window horizontally (width_inc)
               %x  xine screen number
               %%  litteral ‘%’

             Additionally there can be a positive decimal integer number between the percent sign
             and the format string to specify the length this value should be truncated to if
             longer.  (For example: %20t)

             In non-interactive mode, output the list of windows in the current group line by
             line. The format string can be overwritten by the optional parameter format.

VARIABLES

     ratpoison variables can be shown and set with set.  The following variables are supported:

     resizeunit pixels
             Set the amount of pixels interactive resize will add/subtract in each step.

             Default is 5.

     maxundos number
             The maximal amount of step ratpoison can undo with the undo command.

             Default is 20.

     wingravity {nw | w | sw | n | c | s | ne | e | se}
             Set the default gravity new normal windows will get.  Possible values are the same
             as in the gravity command, which changes the gravity of an existing window: cardinal
             points or numbers 1 to 9.

             Default is nw.

     maxsizegravity {nw | w | sw | n | c | s | ne | e | se}
             Set the default gravity new self-maximized windows will get.  Possible values are
             the same as in the gravity command, which changes the gravity of an existing window:
             cardinal points or numbers 1 to 9.

             Default is c.

     transgravity {nw | w | sw | n | c | s | ne | e | se}
             Set the default gravity new transient windows will get.  Possible values are the
             same as in the gravity command, which changes the gravity of an existing window:
             cardinal points or numbers 1 to 9.

             Default is c.

     bargravity {nw | w | sw | n | c | s | ne | e | se}
             Select the location where message and prompt bars appear.

             Default is ne.

     font font
             Make ratpoison use font font.

     padding left top right bottom
             Set how much space at the borders of the screen will not be used.

             Default is 0 0 0 0.

     border pixels
             Selects how thick the frame around windows is.

             Default is 1.

     barborder pixels
             Selects how thick the frame around ratpoison's prompt or message windows is.

             Default is 1.

     inputwidth pixels
             Determine the width of the input window.

             Default is 200.

     barinpadding {0 | 1}
             If there is padding, determines whether the bar appears at the edge of the screen
             (1) or at the edge of the window area (0).

             Default is 0.

     topkmap kmap
             Make kmap the top keymap ratpoison grabs directly.

             The default value is top.

     waitcursor {0 | 1}
             Determine whether to change the rat cursor when waiting for a key (1) or not (0) See
             readkey and describekey.

             Default is 1.

     winfmt format
             Choose the default format for the the windows command.

             Default is %n%s%t.

     winname {title | name | class}
             Choose what is considered the "name" of the window by ratpoison:

             title   The title of the window.
             name    The resource name of the window.
             class   The resource class i.e. the name of the application.

             Default is title.

     fgcolor color
             The foreground color of the windows ratpoison creates.

             Default is black.

     bgcolor color
             The background color of the windows ratpoison creates.

             Default is white.

     fwcolor color
             The border color of the focused window.

             Default is black.

     bwcolor color
             The border color of unfocused windows.

             Default is black.

     barpadding x y
             Set horizontal padding of ratpoison windows to x and vertical padding to y.

             Default is 4 0.

     winliststyle {row | column}
             Determines whether windows are shown in rows or in columns.

             Default is column.

     framesels selectors
             Override the frame selectors fselect uses.  The first character is the selector for
             the first frame, the second character is the selector for the second frame and so
             on.

             Using this variable, one can directly access more than 10 frames.

             Default is an empty string, which is equivalent to "0123456789".

     historysize number
             Specify maximum number of values kept in input history.

             Default is 20.

     historycompaction {0 | 1}
             Decide if new input lines added to history delete older equal lines from history.

             Default is 1 (on).

     historyexpansion {0 | 1}
             Decide if history expansion using ! is available.  (Can only be activated when
             compiled with readline's libhistory.)

     msgwait seconds
             The duration the message window is shown.  If seconds is zero, wait infinitely.

     framemsgwait seconds
             The duration the ‘Current frame’ indicator is shown.  If seconds is zero, wait until
             the next interactive command.  If seconds is -1, don't show any message.

     startupmessage 0 | 1
             Decide whether to show a greeting message at startup.

     warp 0 | 1
             Decide if focusing a window moves the rat cursor to the place it had been last time
             this window was focused, or not.

             Default is 0 (off).

     rudeness number
             Show or set what kind of windows are allowed to jostle into the foreground.

             number is a bitwise OR of the following values:

               1   Transient windows may raise.
               2   Normal windows may raise.
               4   New transient windows end up in the foreground.
               8   New normal windows end up in the foreground.

             Default is all allowed i.e. 15.

FILES

     ~/.ratpoisonrc    Configuration file read at startup time, if present.
     /etc/ratpoisonrc  Fallback configuration file, if ~/.ratpoisonrc is not found.

EXIT STATUS

     The ratpoison utility exits 0 on success, and >0 if an error occurs.

AUTHORS

     Upstream author is Shawn Betts <sabetts@gmail.com>.

     See the /usr/share/doc/ratpoison/AUTHORS file for other contributors.

     This manual page was written by Bernhard R. Link <brlink@debian.org>.  The conversion to the
     mdoc(7) language (http://mdocml.bsd.lv) was done by Jeremie Courreges-Anglas
     <jca@wxcvbn.org>.

BUGS

     Please report any bug you find to the ratpoison mailing-list, ⟨ratpoison-devel@nongnu.org⟩.