diff options
Diffstat (limited to 'doc/ratpoison.texi')
-rw-r--r-- | doc/ratpoison.texi | 1895 |
1 files changed, 0 insertions, 1895 deletions
diff --git a/doc/ratpoison.texi b/doc/ratpoison.texi deleted file mode 100644 index 7b9ce78..0000000 --- a/doc/ratpoison.texi +++ /dev/null @@ -1,1895 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename ratpoison.info -@include version.texi -@settitle Ratpoison @value{VERSION} manual -@c %**end of header - -@dircategory X11 -@direntry -* ratpoison: (ratpoison). Say good-bye to the rodent -@end direntry - -@copying -Copyright @copyright{} 2000, 2001, 2002, 2003, 2004, 2005, 2006 Shawn Betts - -@quotation -The ratpoison user manual is free documentation; permission is granted to -copy, distribute and/or modify this document under the terms of either: - -a) the GNU General Public License as published by the Free Software -Foundation; either version 2 of the License, or (at your option) -any later version, or - -b) the GNU Free Documentation License, version 1.2 or any later -version published by the Free Software Foundation; with no -Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. - -The ratpoison manual is distributed in the hope that it will be -useful, but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -General Public License or GNU Free Documentation License for more -details. - -A copy of the FDL is included in the section entitled -@ref{GNU Free Documentation License}. -You should have received a copy of the GNU General Public License -along with this software; see the file COPYING. If not, write to -the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, -MA 02110-1301, USA. - -If you choose to allow use of your version of this content only under the -terms of one of the licenses, indicate your decision by deleting the notice -of the other license. If you do not delete any of those, a recipient may use -your version of this file unter the terms of either the GNU FDL or the GNU GPL. -@end quotation -@end copying - -@titlepage -@title The ratpoison user manual -@author Shawn Betts - -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@ifnottex -@node Top -@top Ratpoison - -This document explains how to use ratpoison @value{VERSION}. - -@insertcopying -@end ifnottex - -@contents - -@menu -* About:: What Is Ratpoison? -* Contacting:: How Do I Contact The Ratpoison Developers? -* Concepts:: Window Manipulation Concepts -* General Use:: How Does This Thing Work?? -* Windows:: Navigating The Windows -* Groups:: Grouping Windows Together -* Frames:: Dividing The Screen -* Multiple Monitors:: What To Do With All Your Computer Junk -* Keystrokes:: Key Commands And Functionality -* Hooks:: Attaching Scripts To Ratpoison Events -* The Status Bar:: Ratpoison's Input/Output Area -* Using Other Window Managers:: Return To Evil -* Other Commands:: Miscellaneous Commands -* Input:: Typing Text Into Ratpoison -* Command Line Arguments:: ratpoison Command-Line Actions -* Startup file:: They Threatened Me...With Violence! -* GNU Free Documentation License:: -* Command Index:: Index - -@detailmenu - --- The Detailed Node Listing --- - -Windows - -* Manipulating Windows:: -* Window Classes:: -* Unmanaged Windows:: -* Rudeness:: - -Frames - -* Splitting Frames:: -* Resizing Frames:: -* Frame Navigation Commands:: -* Saving and Restoring Frame Sets:: -* Frame Numbering:: -* Dedicated Frames:: - -Keystrokes - -* Key Maps:: -* Default Key Bindings:: - -@end detailmenu -@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 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 (@email{sabetts@@gmail.com}). - -@node Contacting -@chapter Contacting -ratpoison is hosted on @url{http://savannah.nongnu.org}. To see the latest -developments in ratpoison go to -@url{http://savannah.nongnu.org/projects/ratpoison} or visit the -ratpoison webpage at @url{http://www.nongnu.org/ratpoison}. - -There is also a ratpoison mailing list: -@email{ratpoison-devel@@nongnu.org}. For details on subscribing -and for the list archives go to the ratpoison Savannah project. - -There is a @url{irc://irc.freenode.net/#ratpoison, #ratpoison} IRC -channel on the @url{http://freenode/, Freenode} network. - -@node Concepts -@chapter Concepts - -ratpoison uses the concept of @dfn{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 @dfn{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 @ref{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. - -Every window belongs in a group. A group is simply that: a group of -windows. By default there is only one group (the @dfn{default group}) -that all windows exist in. You can create new groups. When a program -creates a window it will be added to the current group. Groups are -generally used to organize windows into different classes such as work -and wasting-time-at-work. - -@node General Use -@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? It's modern computing at -its best. - -@node Windows -@chapter Windows - -Windows are what ratpoison manages. - -@menu -* Manipulating Windows:: -* Window Classes:: -* Unmanaged Windows:: -* Rudeness:: -@end menu - -@node Manipulating Windows -@section Manipulating Windows - -The following are commands used to manipulate windows. - -@deffn Command 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 -@kbd{C-@var{n}} too. To select no window, blanking the current -frame, type @samp{select -}. -@end deffn - -@deffn Command select @var{window-name} -Go to a window by name. A shortcut is @kbd{C-t '}. -@end deffn - -@deffn Command 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 argument it treats it as the format string as -described in @command{set winfmt}. -@end deffn - -@deffn Command 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. -@end deffn - -@deffn Command other -This toggles between the current window and the last window. By -default, this is bound to @kbd{C-t C-t}. -@end deffn - -@deffn Command prev -This jumps you to the previous window in the window list. By default, -this is bound to @kbd{C-t p}. -@end deffn - -@deffn Command 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}. -@end deffn - -@deffn Command 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}. -@end deffn - - -@deffn Command info @var{fmt} -Display information about the current window. At optional @var{fmt} -argument can be passed to override the default format. @command{info} -accepts the same format options as @command{windows}. - -@end deffn - -@deffn Command gravity @var{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 @var{g} are the 8 -directions @samp{northwest}, @samp{north}, @samp{northeast}, -@samp{east}, @samp{southeast}, @samp{south}, @samp{southwest} and -@samp{west}, clockwise from the top left corner. @samp{center} will -center the window in the frame. @var{g} and can be abbreviated to the -standard compass 1 and 2 letter abbreviations (i.e. @samp{nw}, -@samp{s}, etc). - -When called with no arguments, the current setting is -returned. -@end deffn - -@deffn Command delete -This deletes the current window. You can access it with the @kbd{C-t k} -keystroke. -@end deffn - -@deffn Command {set infofmt} @var{fmt} -Set the default window format for the @command{info} command. See -@command{set winfmt} for accepted format characters. -@end deffn - -@deffn Command {set winname} @var{name} -@c @deffnx Command 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. - -When called with no arguments, the current setting is returned. -@end deffn - -@deffn Command {set wingravity} @var{g} -@c @deffnx Command defwingravity @var{g} -Set the default gravity for normal windows. See the -@command{gravity} command. - -When called with no arguments, the current setting is returned. -@end deffn - -@deffn Command {set winliststyle} @var{setting} -@c @deffnx Command defwinliststyle @var{setting} -The window list can be displayed in a row or a column. @var{setting} -can be @samp{row} or @samp{column}. -@end deffn - -@deffn Command {set winfmt} @var{fmt} -@c @deffnx Command defwinfmt @var{fmt} -Set the default window format for the @command{windows} command. By -default it is @samp{%n%s%t}. The following is a list of valid format -characters: - -@table @samp -@item %a -Application Name -@item %c -Resource Class -@item %f -The frame number the window is displayed in or a space if it is not in -a frame. -@item %g -The window's gravity setting -@item %h -The window's height -@item %H -The window's height increment hint. -@item %i -X11 Window ID -@item %l -A unique number based on when the window was last accessed. The higher -the number, the more recently it was accessed. -@item %n -The window number -@item %p -Process ID ('?' if _NET_WM_PID isn't set) -@item %s -Window status (current window, last window, etc) -@item %S -The window's screen -@item %t -Window Name -@item %T -Whether the window is a transient or not. -@item %M -Whether the window is a maxsize window or not. -@item %w -The window's width -@item %W -The window's width increment hint -@item %x -the window's xinerama screen -@end table - -Additionally there can be a number between the percent sign and the format -character, denoting a maximum length this value is to truncate to, e.g. @samp{%n%s%20t}. - -When called with no arguments, the current setting is -returned. -@end deffn - -@deffn Command number @var{n} @var{target} -Set a window's number to @var{n}. If another window occupies the -requested number already, then the windows' numbers are swapped. - -The second argument, @var{target}, is optional. It should be the -number of the window whose number will be changed. If @var{target} is -omitted ratpoison defaults to the current window. -@end deffn - -@deffn Command {set transgravity} @var{g} -@c @deffnx Command deftransgravity @var{g} -Set the default alignment for transient windows. See the -@command{gravity} command. - -When called with no arguments, the current setting is -returned. -@end deffn - -@deffn Command {set maxsizegravity} @var{g} -@c @deffnx Command defmaxsizegravity @var{g} -Set the default alignment for windows with maxsize hints. See the -@command{gravity} command. - -When called with no arguments, the current setting is -returned. -@end deffn - -@deffn Command {set border} @var{n} -@c @deffnx Command defborder @var{n} -Set the border width for all windows. - -When called with no arguments, the current setting is -returned. -@end deffn - -@node Window Classes -@section Window Classes - -Window classes are a way of grouping windows together. Windows that -are part of the same program generally have the same class. Ratpoison -takes advantage of this to help you navigate between windows of the -same class. This is useful if you only want to cycle through Emacs -frames or XTerms. - -@deffn Command inext -Go to the next window in the window list that is in the same class as -the current window. -@end deffn - -@deffn Command iprev -Go to the previous window in the window list that is in the same class -as the current window. -@end deffn - -@deffn Command iother -Go to the last accessed window that is in the same class as the -current window. -@end deffn - -@deffn Command cnext -Go to the next window in the window list that is in a different class -from the current window. -@end deffn - -@deffn Command cprev -Go to the previous window in the window list that is in a different -class from the current window. -@end deffn - -@deffn Command cother -Go to the last accessed window that is in a different class from the -current window. -@end deffn - -@node Unmanaged Windows -@section Unmanaged Windows - -ratpoison can intentionally not manage windows. ratpoison keeps a list -of strings and if any new window's name matches a string in the list, -then it will not be picked up and managed by ratpoison. - -The following are commands to manipulate this list - - -@deffn Command clrunmanaged -Clear the unmanaged window list. -@end deffn - -@deffn Command unmanage @var{text} -Add @var{text} to the unmanaged window list. Any window whose name -matches any of the strings in the unmanaged window list will not be -handled in any way by ratpoison. This only applies to new windows (not -windows already managed by ratpoison). - -When called with no arguments, the list is returned. -@end deffn - -@node Rudeness -@section Rudeness - -Some programs will attempt to steal the focus without the users -permission. Not only is this a sign of a lame programmers attempt to fix -a window manager problem in the wrong place, it's just plain rude. By -default ratpoison will honour these rudeness requests, but it doesn't -have to. Use the @command{rudeness} command to deal with such programs. - -@deffn Command 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)}. - -When called with no arguments, the current setting is -returned. -@end deffn - -@node Groups -@chapter Groups -ratpoison provides functionality to group windows together. This -coupled with saving and restoring frames configurations is what most -people would call @dfn{virtual desktops} or @dfn{workspaces}. - -While ratpoison doesn't explicitly provide support for such things, it -does allow you to write scripts to this end. Such a script exists in -@file{contrib/} called @file{rpws}. Consult that file for details on -setting up workspaces inside ratpoison. - -Groups are more general purpose than workspaces. windows from one -group can be visible along with windows from another group. If you -switch to a different group nothing changes except the list of windows -you can cycle through. ratpoison allows the user to move a window from -one group to another, merge two groups, create new groups, and delete -existing ones. - -The following is a list of of commands used for manipulating groups. - -@deffn Command gnew @var{name} -Create a new group with the name @var{name}. @var{name} is -optional. The new group becomes the current group. -@end deffn - -@deffn Command gnewbg @var{name} -This is the same as @command{gnew} except that the current group does -not change. -@end deffn - -@deffn Command groups -Display a list of groups with a similar format to @command{windows}. -@end deffn - -@deffn Command gmove @var{group} -Move the current window to @var{group}. -@end deffn - -@deffn Command gnext -Go to the next group in the list. -@end deffn - -@deffn Command gother -Go to the last accessed group. -@end deffn - -@deffn Command gprev -Go to the previous group in the list. -@end deffn - -@deffn Command grename -Rename current group. -@end deffn - -@deffn Command gnumber @var{GROUP} @var{target} -Set a group's number to @var{GROUP}. If another group occupies the -requested number already, then the groups' numbers are swapped. - -The second argument, @var{target}, is optional. It should be the -number of the group whose number will be changed. If @var{target} is -omitted ratpoison defaults to the current group. -@end deffn - -@deffn Command gselect @var{group} -Select a particular group by name or number. If @var{group} is not -provided, ratpoison will interactively prompt for the group. -@end deffn - -@deffn Command gmerge @var{group} -Merge @var{group} with the current group. All windows in @var{group} -will be moved to the current group. @var{group} is not deleted. -@end deffn - -@deffn Command gdelete @var{group} -Delete a group. @var{group} is optional. If it is not specified -ratpoison will attempt to delete the current group. Only empty groups -can be deleted. To empty a group see @command{gmerge}. -@end deffn - -@node Frames -@chapter 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 -@ref{Concepts}). Each frame can then contain 1 window. - -@menu -* Splitting Frames:: -* Resizing Frames:: -* Frame Navigation Commands:: -* Saving and Restoring Frame Sets:: -* Frame Numbering:: -* Dedicated Frames:: -@end menu - -@node Splitting Frames -@section Splitting Frames - -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. - -@deffn Command remove -Kill the current frame. This is a no-op if there is only one frame. -@end deffn - -@deffn Command only -Kill all frames but the current one. -@end deffn - -@deffn Command split @var{n} -@deffnx Command vsplit @var{n} -Split the current frame vertically in two. The last accessed window -not occupying a frame will be the second window. - -@var{n} is either a fraction of the form @code{x/y} or a number. If it -is a fraction then the current frame is resized to that fraction of -its original size and the new frame takes up the remaining space. For -instance, @code{split 1/4} will split the current frame to a quarter -of its original size and the new frame will then be 3/4 of the size of -the original frame. - -If it is a pixel, the original frame is resized to that many -pixels. If @var{n} has a minus sign before it, then the new frame will -shrink by that many pixels. -@end deffn - -@deffn Command hsplit @var{n} -Split the current frame horizontally in two. The last accessed window -not occupying a frame will be the second window. - -@var{n} is either a fraction of the form @code{x/y} or a number. If it -is a fraction then the current frame is resized to that fraction of -its original size and the new frame takes up the remaining space. For -instance, @code{split 1/4} will split the current frame to a quarter -of its original size and the new frame will then be 3/4 of the size of -the original frame. - -If it is a pixel, the original frame is resized to that many -pixels. If @var{n} has a minus sign before it, then the new frame will -shrink by that many pixels. -@end deffn - -@node Resizing Frames -@section Resizing Frames -ratpoison provides a command, @command{resize}, that resizes the -current frame. It is bound to the key @kbd{C-t r} by -default. @command{resize} can be used non-interactively by providing -two arguments: the number of pixels to grow horizontally and the -number to grow vertically. For example, if you wanted to grow the -current window by 10 pixels horizontally and shrink it vertically by -50 you could enter the command: - -@example -resize 10 -50 -@end example - -When resizing interactively, the following keys are used: - -@table @kbd -@item C-p -Grow the frame vertically. -@item C-n -Shrink the frame vertically. -@item C-f -Grow the frame horizontally. -@item C-b -Shrink the frame horizontally. -@item return -Accept the new frame size. -@item C-g -Abort and restore the frame to its original size. -@end table - -The increment size used to resize the frame interactively is -customized with the command @command{set resizeunit}. - -@deffn Command {set resizeunit} @var{pixels} -@c @deffnx Command defresizeunit @var{pixels} -Set the number of pixels a frame will grow or shrink by when being -dynamically resized. - -When called with no arguments, the current setting is returned. -@end deffn - -@deffn Command resize @var{horizontal} @var{vertical} -Resize the current frame by @var{horizontal} pixels horizontally, and -@var{vertical} pixels vertically. If no arguments are given and the -command is called interactively, ratpoison will let the user -dynamically resize the frame using @kbd{C-p} to shrink vertically, -@kbd{C-n} to grow vertically, @kbd{C-b} to shrink horizontally, -@kbd{C-f} to grow horizontally, and @kbd{s} to shrink the frame to the -size of the window (See the @command{shrink} command). When you have -resized the frame to your liking, press @kbd{Return} to finish. -@end deffn - -@deffn Command shrink -If a window has resize increment hints, such as xterms, the window may -not be able to take up the whole frame. In this case, use this command -to suck the frame up to the to window, reclaiming any wasted space. -@end deffn - -@node Frame Navigation Commands -@section Frame Navigation Commands - -Here are the commands for Navigating frames. - -@deffn Command fselect @var{n} -Select a frame by number. If an argument is passed to it then attempt -to select the frame whose number is @var{n}. If not, ratpoison will -print a number at the top left corner of each frame and wait for the -user to type the number they wish to select. Currently there is no way -to select a frame whose number is greater than 9 unless the number is -passed as an argument. -@end deffn - -@deffn Command curframe -Indicate which frame is the current frame. -@end deffn - -@deffn Command focus -cycle through ratpoison's frames. -@end deffn - -@deffn Command focusprev -cycle through ratpoison's frames backwards. -@end deffn - -@deffn Command focusdown -Move to the frame below the current frame. -@end deffn - -@deffn Command focuslast -Switch to the last focused frame. -@end deffn - -@deffn Command focusleft -Move to the frame left of the current frame. -@end deffn - -@deffn Command focusright -Move to the frame right of the current frame. -@end deffn - -@deffn Command focusup -Move to the frame above the current frame. -@end deffn - -@node Saving and Restoring Frame Sets -@section Saving and Restoring Frame Sets -ratpoison provides two commands, @command{fdump} and -@command{frestore}, that allow the user to save and restore frame -configurations. Let's say, for example, you have split your desktop -into several frames with some windows in these frames and now you want -to quickly bring Emacs forward and browse some code (full-screen of -course) then return to your funky frame configuration. You could use -@command{fdump} to dump the frames, hit @kbd{C-t Q} to remove all -frames, and then select your emacs window. When you've finished with -emacs you could use @command{frestore} to restore the windows and -frames. - -If a frame contained a window when you dumped the frame layout but -that window is not present when you restore the layout, the frame -holding that window will be blank. - -Calling @command{fdump} and @command{frestore} and copying and pasting -the layout by hand each time is a bit cumbersome. There are some -simple bindings in @file{doc/sample.ratpoisonrc} that allow you to -save and restore frame layouts with the press of a key. - -@deffn Command fdump @var{screen-num} -Dump the current frame layout as text. - -Without an argument the current screen's frames are dumped. With an -argument the @var{screen-num}th screen is dumped. @xref{Multiple Monitors}. -@end deffn - -@deffn Command frestore @var{frames} -Restore the frame layout based on the list of frames -@var{frames}. @var{frames} should be the text that was printed after -calling @code{fdump}. -@end deffn - -@deffn Command undo -Undo the last change of frame layout. This is especially helpful -after a @command{only} command. One can step at most @dfn{maxundos} -steps back in frame layout history. -@end deffn - -@deffn Command redo -redo the last change that was undone. -@end deffn - -@node Frame Numbering -@section Frame Numbering - -Frames are normally numbered starting from 0. But this can be changed -with @command{set framesels} to, for instance, include letters as well. - -@example -set framesels abcdefghijklmnopqrstuvwxyz -@end example - -The above code will bind letters to frames instead of numbers. - -@deffn Command set framesels @var{order} -Tell ratpoison what alphanumeric character to give each frame and in -what order. - -When called with no arguments, the current setting is returned. -@end deffn - -@node Dedicated Frames -@section Dedicated Frames - -A dedicated frame is a frame that will not allow new windows to appear -in it. Only the user may switch windows in this frame. - -@deffn Command dedicate -Toggle whether the current frame is dedicated or not. -@end deffn - -@node Multiple Monitors -@chapter Multiple Monitors -When you've finally accumulated enough computer junk, you'll find -yourself 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 @command{nextscreen} and -@command{prevscreen}. Or, @command{sselect} to jump to a specified -screen. 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 @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 @command{select} or @kbd{C-t '}), by number, -or you can use @command{nextscreen}, @command{prevscreen}, and -@command{sselect}. - -@deffn Command nextscreen -This jumps you to the next X11 screen. @command{nextscreen} is -used for dual-head displays and multiple monitor setups. -@end deffn - -@deffn Command prevscreen -This jumps you to the previous X11 screen. @command{prevscreen} is -used for dual-head displays and multiple monitor setups. -@end deffn - -@deffn Command sselect @var{n} -This jumps you to the @var{n}th X11 screen. Screen numbers start at 0. -@end deffn - -@deffn Command sdump -Like fdump, but dump information about each screen instead of each frame. -@end deffn - -@deffn Command sfdump -Dump all the screen number and the frames on all screens. -@end deffn - -@deffn Command sfrestore -restore a frame configuration created using @command{sfdump}. -@end deffn - -@node Keystrokes -@chapter Keystrokes - -Interactive control of ratpoison is done entirely through -keystrokes. This chapter explains how keystrokes are stored and -manipulated. - -ratpoison uses the Emacs style key notation. A combination of -modifiers and one non-modifier key combine to invoke an action. The -syntax is one or more modifiers seperated with dashes followed by a -dash and the non-modifier key name. For instance, holding down -control, shift, and super then pressing the spacebar would be -described as: - -@example -S-C-s-space -@end example - -The following is a list of modifiers ratpoison accepts: - -@table @asis -@item S -Shift modifier -@item C -Control modifier -@item M -Meta modifier -@item A -Alt modifier -@item H -Hyper modifier -@item s -Super modifier -@end table - -ratpoison uses the X11 keysym names for keys. Alphanumeric key names -are exactly what you see on your keyboard. Punctuation and other keys -have longer names which vary from X server to X server. To find the -name of a key, see the @command{describekey} command. Or to find the -name of a key not yet bound to an action, type @kbd{C-t} and then the -key. ratpoison will tell you it isn't bound and give you the name of -the key. - -@menu -* Key Maps:: -* Default Key Bindings:: -@end menu - -@node Key Maps -@section Key Maps - -All keystrokes exist inside a keymap. When you press the prefix key you -are accessing the @samp{root} keymap. By default all commands reside in -the @samp{root} key map and are accessed by pressing @kbd{C-t}. - -There is also a top level key map, @samp{top}. Any keystroke in this key -map can be accessed simply by pressing the key. This is where the prefix -key resides. - -The following example adds a @kbd{C-x b} key binding to switch windows, -much like @kbd{C-x b} in Emacs. See the functions below for full -descriptions. - -@example -# Create the key map -newkmap ctrl-x -# Bind b to 'select' on our new key map -definekey ctrl-x b select -# Attach our keymap to the top level key map via C-x. -definekey top C-x readkey ctrl-x -@end example - -The following functions control creating, editing, and deleting key maps. - -@deffn Command newkmap @var{kmap} -Create a new keymap named @var{kmap}. - -@end deffn - -@deffn Command delkmap @var{kmap} -Delete the keymap, @var{kmap}. -@end deffn - -@deffn Command bind @var{Key} @var{command} -Bind a key to a ratpoison command on the @samp{root} keymap. 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 restart -@end example -@end deffn - -@deffn Command unbind @var{key} -Unbind a keystroke on the @samp{root} keymap. -@end deffn - -@deffn Command definekey @var{kmap} @var{key} @var{command} -@command{definekey} works exactly like @command{bind} except that it -can bind keys on any key map (not just @samp{root}). -@end deffn - -@deffn Command undefinekey @var{kmap} @var{key} -Like @command{unbind} except that you pass it a key map in @var{kmap}. -@end deffn - -@deffn Command readkey @var{kmap} -Read a key from the keyboard and execute the command associated with -it in the keymap, @var{kmap}. -@end deffn - -@deffn Command link @var{key} -Call the command that @var{key} is bound to. For instance -@command{link C-t} would call the command @command{other} and switch -to the last window. -@end deffn - -@deffn Command describekey @var{keymap} -An interactive way to find the command bound to a given key on the -specified keymap. This command will wait for the user to type a -key. When the user does, the command will display the command bound to -this key. -@end deffn - -@deffn Command {set topkmap} @var{kmap} -Set the top level keymap to @var{kmap}. You might use this to swap -between several common keymappings or to implement modes. -@end deffn - -@node Default Key Bindings -@section Default Key Bindings - -The default keystrokes are listed in this chapter. Not all commands -are accessible by default by keys. - -@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 : -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 i -@item C-t C-i -Display information about the current window. - -@item C-t k -@item C-t C-k -Close the current window. - -@item C-t l -@item 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. @kbd{C-t l} will force the -current window to maximize. - -@item C-t m -@item C-t C-m -Display the last message. - -@item C-t v -@item C-t C-v -Display the version of ratpoison. - -@item C-t V -@item C-t C-V -Display ratpoison's license. - -@item C-t w -@item C-t C-w -Display the list of managed windows. The current window is highlighted. - -@item C-t s -@item C-t C-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 -@item C-t C-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 M-tab -Switch to the last focused frame. - -@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 r -@item C-t C-r -Resize the current 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 -select a frame by number. - -@item C-t F -Indicate which frame is the current frame. - -@item C-t Down -Move to the frame below the current frame. - -@item C-t Left -Move to the frame left of the current frame. - -@item C-t Right -Move to the frame right of the current frame. - -@item C-t Up -Move to the frame above the current frame. - -@item C-t C-Down -Exchange the window in the current frame with the window in the frame below it. - -@item C-t C-Left -Exchange the window in the current frame with the window in the frame to the left of it. - -@item C-t C-Right -Exchange the window in the current frame with the window in the frame to the rigth of it. - -@item C-t C-Up -Exchange the window in the current frame with the window in the frame above it. - -@item C-t x -@item C-t C-x -Choose a frame and exchange the window in the current frame with the -window in the chosen frame. - -@end table - -@node Hooks -@chapter Hooks - -One of the goals of ratpoison is to allow users to create exciting -customization to fit their specific needs. Hooks allow a user to latch -scripts onto certain events. - -Each hook contains a list of commands to be executed when the -appropriate event occurs in ratpoison. For example, if you want to warp -the rat to corner of the screen every time you press a top level bound -key, you could add this to you .ratpoisonrc file: - -@example -addhook key banish -@end example - -That should keep the rat out of your way. - -@deffn Command addhook @var{hook} @var{command} -Add a @var{command} to @var{hook}. When the hook is run, @var{command} -will be executed. - -The following hooks are available: - -@table @asis -@item key -Run when a top level key is pressed (by default the only top level key -is the prefix key). -@item switchwin -Run when the user switches to a different window in the current frame. -@item switchframe -Run when the user switches to another frame. This is also run when the -user switches to a different screen, since a frame switch also occurs. -@item switchgroup -Run when the user switches to a different group. -@item deletewindow -Run when a window is deleted. -@item newwindow -Run after a new window is mapped. -@item titlechanged -Run when the current window's title changes. -@item quit -Run when ratpoison exits. -@item restart -Run when ratpoison restarts. -@end table - -@end deffn - -@deffn Command remhook @var{hook} @var{command} -Remove @var{command} from the hook. See @command{addhook} for a list -of available hooks. -@end deffn - -@deffn Command listhook @var{hook} -List the commands that will be run when @var{hook} is fired. -@end deffn - -@node The Status Bar -@chapter The Status Bar - -ratpoison presents status and output through the status bar. By default -it is located in the top right corner of the screen. - -This chapter presents commands for manipulating the status bar. - -Since it is the only visible evidence that ratpoison is running (as -opposed to the invisible evidence including the lack of title bars and -your favorite desktop background) there are also copious visual -customizations available for those rainy days. - -@deffn Command msgwait @var{n} -Set the bar's timeout in seconds. - -When called with no arguments, the current setting is -returned. -@end deffn - -@deffn Command lastmsg -Display the last message. -@end deffn - -@deffn Command echo @var{text} -Display @var{text} as a message. -@end deffn - -@deffn Command {set inputwidth} @var{n} -@c @deffnx Command definputwidth @var{n} -Set the width of the input window. - -When called with no arguments, the current setting is -returned. -@end deffn - -@deffn Command {set font} @var{font} -@c @deffnx Command deffont @var{font} -Set the font. @var{font} is a font string like @samp{9x15bold}. - -When called with no arguments, the current setting is returned. -@end deffn - -@deffn Command {set framefmt} @var{fmt} -Set the text that appears when the @command{curframe} command is -called. @var{fmt} is a format string that accepts the same format -characters as @command{set winfmt}. -@end deffn - -@deffn Command {set fgcolor} @var{color} -@c @deffnx Command deffgcolor @var{color} -Set the foreground color for all text ratpoison displays. @var{color} -is any valid X11 color. - -When called with no arguments, the current setting is returned. -@end deffn - -@deffn Command {set bgcolor} @var{color} -@c @deffnx Command defbgcolor @var{color} -Set the background color for all text ratpoison displays. @var{color} -is any valid X11 color. - -When called with no arguments, the current setting is returned. -@end deffn - -@deffn Command {set fwcolor} @var{color} -Set the border color for the focused window. -is any valid X11 color. - -When called with no arguments, the current setting is returned. -@end deffn - -@deffn Command {set bwcolor} @var{color} -Set the border color for unfocused windows. -is any valid X11 color. - -When called with no arguments, the current setting is returned. -@end deffn - -@deffn Command {set barpadding} @var{x} @var{y} -@c @deffnx Command defbarpadding @var{x} @var{y} -Set the horizontal and vertical padding inside the bar. - -When called with no arguments, the current setting is -returned. -@end deffn - -@deffn Command {set bargravity} @var{g} -@c @deffnx Command defbargravity @var{g} -Set the default alignment for the message bar. See the @command{gravity} command. - -When called with no arguments, the current setting is -returned. -@end deffn - - -@deffn Command {set barborder} @var{n} -@c @deffnx Command defbarborder @var{n} -Set the border width for the bar window. - -When called with no arguments, the current setting is returned. -@end deffn - - -@deffn Command {set barinpadding} @var{n} -@c @deffnx Command defbarinpadding @var{n} -Set whether the bar window appears at the edge of the screen when there is -padding -- that is, within the "padding" area -- or whether it appears at the -edge of the window area. "1" represents the former, "0" the latter. See the -@command{set padding} and @command{set bargravity} commands. - -When called with no arguments, the current setting is returned. -@end deffn - - -@node Using Other Window Managers -@chapter Using Other Window Managers - -There are times when a program has been so badly written that it is -virtually impossible to use under ratpoison. Some authors have tailored -their programs to certain window management paradigms so aggressively -that very little can be done. Ratpoison has two commands to help you -through these difficult times: @command{tmpwm} and @command{newwm}. - -These commands should be used sparingly. They were created to allow -users to understand how a poorly designed program is intended to -function so they can build a replacement or patch an existing -alternative's missing functionality. - -According to independant studies, @command{tmpwm} has been used almost -exclusively to verify its correct operation -- like a vintage sports -car: always kept in prime condition and never used. - -@command{tmpwm} and @command{newwm} are provided for boasting and -completeness. - -@deffn Command tmpwm @var{WM} -Gives control over to another window manager and regains control once -it has terminated. @var{WM} is the path to the new window -manager. This command is useful when you want to temporarily take a -look at another window manager, or program under a different window -manager, but you want to come back to ratpoison when you've finished -your investigation. -@end deffn - -@deffn Command newwm @var{window-manager} -This is a bad-bad command. It kills ratpoison and revives that -ugly rodent! Yuck! Avoid! -@end deffn - -@node Other Commands -@chapter Other Commands - -The following is a list of commands that don't fit in any existing -chapters. - -@deffn Command abort -This is a pretty useless command. By default, it is bound to @kbd{C-t -g} and its purpose is to abort the current chain of keystrokes (just -like @kbd{C-g} in @samp{Emacs}). -@end deffn - -@deffn Command alias @var{name} @var{command} -Allows you to name a ratpoison command something else. For -instance, if you frequently open emacs you may want to make an alias -called @samp{emacs} that loads emacs. You would do it like this: - -@example -alias emacs exec emacs -@end example - -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 @command{ratpoison -c}. -@end deffn - -@deffn Command banish -Banish the mouse to the lower right corner of the screen. -@end deffn - -@deffn Command banishrel -Banish the rat cursor to the lower right corner of the curren window. -If there isn't a window in the current frame, it banishes the rat cursor -to the lower right corner of the frame. -@end deffn - -@deffn Command chdir -Change the current directory for ratpoison. -@end deffn - -@deffn Command colon @var{command} -Run a ratpoison command. -@end deffn - -@deffn Command compat -Install the now obsolete @samp{def*} commands as aliases to the -corresponding @samp{set *} command. -@end deffn - -@deffn Command {set padding} @var{left} @var{top} @var{right} @var{bottom} -@c @deffnx Command defpadding @var{left} @var{top} @var{right} @var{bottom} -Set the padding around the edge of the screen. - -When called with no arguments, the current setting is returned. -@end deffn - -@deffn Command {set waitcursor} @var{n} -@c @deffnx Command 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. - -When called with no arguments, the current setting is returned. -@end deffn - -@deffn Command {set historysize} @var{n} -Set how many lines of history should be recorded. - -When called with no arguments, the current setting is returned. -@end deffn - -@deffn Command {set historcompaction} @var{bool} -Set whether to remove multiple equal lines from history, -even if not adjacent. - -When called with no arguments, the current setting is returned. -@end deffn - -@deffn Command {set historexpansion} @var{bool} -Set whether to expand ! using readline's libhistory in input. - -When called with no arguments, the current setting is returned. -@end deffn - -@deffn Command escape @var{key} -Set the prefix to @var{key}. For example @samp{escape C-b} sets the -prefix key to @key{C-b}. -@end deffn - -@deffn Command exchangedown -Exchange the current frame with the one below it. -@end deffn - -@deffn Command exchangeleft -Exchange the current frame with the one to the left of it. -@end deffn - -@deffn Command exchangeright -Exchange the current frame with the one to the right of it. -@end deffn - -@deffn Command exchangeup -Exchange the current frame with the one above it. -@end deffn - -@deffn Command exec @var{command} -Execute a shell command. By default, @kbd{C-t !} does this. -@end deffn - -@deffn Command execa @var{command} -Execute a shell command but don't record which frame it was executed -from. The client's windows will pop up in whatever frame is current. -@end deffn - -@deffn Command execf @var{frame} @var{command} -Execute a shell command and choose which frame the client's first -window will open in. The client must be netwm compliant for this to -work. -@end deffn - -@deffn Command getenv @var{env} -Display the value of the environment variable, @var{env}. -@end deffn - -@deffn Command getsel -Return the contents of the X11 selection. -@end deffn - -@deffn Command help -Display a help screen that lists all bound keystrokes. -@end deffn - -@deffn Command license -Display ratpoison's license. By default, this is bound to @kbd{C-t V}. -@end deffn - -@deffn Command meta @var{key} -@var{key} is an optional argument. When @var{key} is omitted, send a -@kbd{C-t} to the current window. Otherwise, send the key described by -@var{key} to the current window. 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. - -For example, if your @samp{Emacs} window is focused, - -@example -meta M-x -@end example - -Would cause emacs to prompt for an extended command. -@end deffn - -@deffn Command prompt @var{prompt} -This command is only useful when called -non-interactively. @command{prompt} prompts the user for input using -@var{prompt} and returns the input. -@end deffn - -@deffn Command putsel @var{text} -Make text the X11 selection. -@end deffn - -@deffn Command quit -Quit ratpoison. -@end deffn - -@deffn Command ratinfo -Display the x y coordinates of the rat cursor relative to the screen. -@end deffn - -@deffn Command ratrelinfo -Display the x y coordinates of the rat cursor relative to the current window or current frame if no window is focused. -@end deffn - -@deffn Command ratrelwarp @var{x} @var{y} -Warp the rat to the specified location relative to the current rat -position. -@end deffn - -@deffn Command ratwarp @var{x} @var{y} -Warp the rat to the specified absolute location. -@end deffn - -@deffn Command ratclick @var{button} -click the rat. @var{button} is either 1, 2, or 3. @var{button} -defaults to button 1. -@end deffn - -@deffn Command rathold @var{state} @var{button} -click the rat button down if @var{state} is @samp{down} or release the button if @var{state} is @samp{up}. -@end deffn - -@deffn Command redisplay -Extend the current window to the whole size of its current frame and -redisplay it. This can be used to: - -@itemize @bullet -@item redisplay normal windows or bring transient windows to the full size of the frame as only normal windows are maximized by ratpoison. -@item fix xterms that didn't catch ratpoison's initial maximize event. -@end itemize - -@end deffn - -@deffn Command restart -Restart ratpoison. -@end deffn - -@deffn Command set @var{var} @var{value} -Set the value of a ratpoison variable. This command replaces the older -@samp{def*} variable get/set style. - -Here is a list of variables that can be set: - -@itemize @bullet -@item framesels -@item winliststyle -@item barpadding -@item bgcolor -@item fgcolor -@item winname -@item winfmt -@item waitcursor -@item inputwidth -@item barborder -@item border -@item padding -@item font -@item bargravity -@item maxsizegravity -@item transgravity -@item wingravity -@item maxundos -@item resizeunit -@item historysize -@item historycompaction -@item historyexpansion -@end itemize - -@end deffn - -@deffn Command setenv @var{env} @var{value} -Set the environment variable @var{env} to @var{value} -@end deffn - -@deffn Command source @var{file} -Read a text file containing ratpoison commands. -@end deffn - -@deffn Command startup_message @var{state} -Turn on or off the startup_message. This is most useful in your -.ratpoisonrc file. @var{state} can be @code{on} or @code{off}. - -When called with no arguments, the current setting is -returned. -@end deffn - -@deffn Command swap @var{destination-frame} @var{source-frame} -When called interactively prompt for a frame and swap its window with -the window in the current frame. An optional second argument allows -swapping of windows between arbitrary frames. -@end deffn - -@deffn Command time -Show current time in the status bar. -@end deffn - -@deffn Command unalias @var{name} -Remove @var{name} from the list of defined aliases. -@end deffn - -@deffn Command unsetenv @var{env} -Clear the value of the environment variable, @var{env}. -@end deffn - -@deffn Command verbexec @var{command} -Verbosely exec the shell command @var{command}. Raptoison displays a -message saying command was executed. -@end deffn - -@deffn Command version -Print ratpoison version. By default, this is bound to @kbd{C-t v}. -@end deffn - -@deffn Command warp @var{state} -Toggle rat warping. By default ratpoison saves the position of the -rat when leaving a window and when the user returns to the window the -rat's position is restored. This can be counter-intuitive, so you can -toggle it with this command. @var{state} can be @code{on} or @code{off}. -@end deffn - -@node Input -@chapter Input -At various times ratpoison will prompt you for input. Ratpoison sports -a fully featured line editor. The following table lists the keystrokes -and actions: - -@table @key -@item C-g -@itemx escape -abort the command requesting input. - -@item C-f -@itemx right arrow -move forward a character. - -@item C-b -@itemx left arrow -move backward a character. - -@item M-f -move forward a word. - -@item M-b -move backward a word. - -@item C-a -@itemx home -move to the beginning of the line. - -@item C-e -@itemx end -move to the end of the line. - -@item C-d -@itemx delete -delete the character at point. - -@item M-d -delete the word at point. -@item backspace -delete the character before the point. - -@item M-backspace -delete the word before the point. - -@item C-k -delete from the point to the end of the line. - -@item C-u -delete from the point to the beginning of the line. - -@item C-y -Yank the text from the X11 cut buffer. - -@item C-p -@itemx up arrow -Cycle backwards through the history (This command does nothing if -ratpoison was configured with the @code{--disable-history} configure -option). - -@item C-n -@itemx down arrow -Cycle forwards through the history (This command does nothing if -ratpoison was configured with the @code{--disable-history} configure -option). - -@item return -submit the line of text. - -@item tab -complete the text up to the point or if there are several possible -completions, cycle through them. This only works in certain -contexts. Tab completion will complete a shell command, a window name, -a group name, and colon commands in their appropriate context -(i.e. when being asked for a window name). - -@item S-iso-lefttab -This is shift + tab by the way. This does the same as tab, but cycles -backwards through the completions. - -@end table - -All input is stored in the same history list. By default ratpoison has -a history length of 100 entries. This history is saved to the file -@file{~/.ratpoison_history} and is loaded when you start -ratpoison. This means your history sticks between sessions. This -assumes history has not been disabled on compilation. - -@node Command Line Arguments -@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 -d, --display -Specify the X display to connect to. - -@item -s, --screen -Specify the screen to use. By default ratpoison runs on all -screens. You can tell it to use just one with this option. - -@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 commands that behaves differently are the -@code{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 @option{-c} options can be used. - -to facilitate writing scripts, the @env{RATPOISON} environment -variable is set to the full path of the ratpoison binary. - -@example -$ ratpoison -c split -c split -@end example - -Here ratpoison would split the current frame twice. - -@item -i, --interactive -Force ratpoison to execute commands in interactive mode. This is used -in conjunction with the @option{-c} option. - -@item -f, --file -Specify an alternate configuration file. @xref{Startup file}. - -@end table - -@node Startup file -@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 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 @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. - -You can also use the @option{-f} option to specify another startup -file, allowing you to switch between different configurations -(@pxref{Command Line Arguments}). - -@node GNU Free Documentation License -@chapter GNU Free Documentation License -@include fdl.texi - -@node Command Index -@unnumbered Command Index - -@printindex fn - -@bye |