updates and addition of defbarborder command

1 files changed, 369 insertions, 181 deletions

diff --git a/doc/ratpoison.1 b/doc/ratpoison.1
index 703e687..15367fa 100644
--- a/doc/ratpoison.1
+++ b/doc/ratpoison.1
@@ -1,214 +1,376 @@
-.TH RATPOISON 1 "9 September, 2001" "ratpoison" RATPOISON
+.TH RATPOISON 1 "26 January, 2002" "ratpoison" RATPOISON
 .SH NAME
 ratpoison \- fatless X window manager
 .SH SYNOPSIS
-.B ratpoison [ \fIoptions\fP ]
-.SH DESCRIPTION
-This manual page documents briefly the
 .B ratpoison
-window manager.
-
-\fBratpoison\fP is a simple Window Manager with no fat library
-dependencies, no fancy graphics, no window decorations, and no
-flashy wank. It is largely modeled after \fIGNU Screen\fP 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.
+[
+\fIoptions\fP
+]
+.SH DESCRIPTION
+ratpoison is a simple Window Manager with no fat library dependencies, no fancy graphics, no window decorations, and no flashy wank. It is largely modeled after GNU Screen which has done wonders in the virtual terminal market.
+.PP
+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.
+.PP
+ratpoison is a very simple window manager. Each window is maximized and has no border decorations. 
 .SH KEYSTROKES
-ratpoison is controlled entirely through the keyboard. The default
-keystrokes are listed in this section.
+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.
 .TP
 .B C\-t C\-t
 Switch to the last window.
 .TP
 .B C\-t t
-Sometimes you need to send a C\-t to the current window. This keystroke
-does just that.
+Sometimes you need to send a C\-t to the current window. This
+keystroke does just that.
 .TP
 .B C\-t 0\-9
 Switch to the numbered window.
 .TP
 .B C\-t \-
-Select no window, essentially hiding all windows in the current frame.
-.TP
-.B C\-t A,
-.B C\-t C\-A
-Rename the current window. The window's new name will prevail for the
-rest of its lifetime.
-.TP
-.B C\-t K,
-.B C\-t C\-K
-Send a DestroyClient event to the current window. This will terminate
-the application without question.
-.TP
-.B C\-t n,
-.B C\-t C\-n,
-.B C\-t Return,
-.B C\-t C\-Return,
-.B C\-t Space,
-.B C\-t C\-Space,
+Select no window, essentially hiding all windows in the current
+frame.
+.TP
+.B C\-t A, C\-t C\-A
+Rename the current window. The window's new name will prevail for
+the rest of its lifetime.
+.TP
+.B C\-t K, C\-t C\-K
+Send a DestroyClient event to the current window. This will
+terminate the application without question.
+.TP
+.B 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.
 .TP
-.B C\-t p,
-.B C\-t C\-p
+.B C\-t p, C\-t C\-p
 Go to previous window.
 .TP
-.B C\-t ',
-.B C\-t C\-'
-Go to a window by name.  You will usually only need to type the first
-few characters of the window name.
+.B 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.
 .TP
-.B C\-t a,
-.B C\-t C\-a
+.B C\-t a, C\-t C\-a
 Display the current time of day.
 .TP
-.B C\-t c,
-.B C\-t C\-c
+.B C\-t c, C\-t C\-c
 Open a new X terminal.
 .TP
-.B C\-t :,
+.B C\-t :
 This allows you to execute a single ratpoison command.
 .TP
-.B C\-t !,
+.B C\-t !
 Run a shell command.
 .TP
 .B C\-t C\-!
 Run a shell command through an X terminal.
 .TP
-.B C\-t k,
-.B C\-t C\-k
+.B C\-t i, C\-t C\-i
+Display information about the current window.
+.TP
+.B C\-t k, C\-t C\-k
 Close the current window.
 .TP
-.B C\-t m,
-.B C\-t C\-m
-Maximize 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. \fIC\-t m\fP will force the
-current window to maximize.
+.B 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.
+.TP
+.B C\-t m, C\-t C\-m
+Display the last message.
 .TP
-.B C\-t v,
-.B C\-t C\-v
+.B C\-t v, C\-t C\-v
 Display the version of ratpoison.
 .TP
-.B C\-t w,
-.B C\-t C\-w
-Display the list of managed windows. The current window is highlighted.
+.B C\-t w, C\-t C\-w
+Display the list of managed windows. The current window is
+highlighted.
 .TP
 .B C\-t s
-Split the current window horizontally in two. The last accessed window
-not occupying a frame will be the second window.
+Split the current window horizontally in two. The last accessed
+window not occupying a frame will be the second window.
 .TP
 .B C\-t S
-Split the current window vertically in two. The last accessed window not
-occupying a frame will be the second window.
+Split the current window vertically in two. The last accessed
+window not occupying a frame will be the second window.
 .TP
 .B C\-t tab
 Cycle through ratpoison's frames.
 .TP
+.B C\-t M\-tab
+Switch to the last focused frame.
+.TP
 .B C\-t Q
 Kill all frames but the current one.
 .TP
 .B C\-t R
 Kill the current frame. This is a no\-op if there is only one frame.
 .TP
-.B C\-t b,
-.B C\-t C\-b
+.B C\-t b, C\-t C\-b
 Banish the mouse to the lower right corner of the screen.
 .TP
 .B C\-t ?
 Display a help screen
 .TP
-.B C\-t f
-.B C\-t C\-f
+.B C\-t f, C\-t C\-f
 Indicate which frame is the current frame.
 .SH COMMANDS
-Ratpoison can be controlled with commands (so called colon-commands).
+ratpoison can be controlled with commands (so called colon\-commands).
 The summary of available commands is listed below:
 .TP
 .B abort
-This is a pretty useless command. By default, it is bound to
-\fIC\-t g\fP, and its purpose is to abort other commands.
+This is a pretty useless command. By default, it is bound to `C\-t
+g', and its purpose is to abort other commands.
+.TP
+.B alias \fINAME COMMAND\fP
+An alias 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'.
 .TP
 .B banish
 Banish the mouse to the lower right corner of the screen.
 .TP
-.B bind \fIKey\fP \fIcommand\fP
-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 \fIC\-t R\fP to
-restart ratpoison:
+.B bind \fIKEY COMMAND\fP
+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:
 
-.IP
-: bind R exec ratpoison \-\-restart
-.PP
+: bind R restart
+
+If no command is specified then bind works exactly like `unbind',
+unbinding the key.
 .TP
-.B clock
-Show current time. Disappears after 5 seconds, like all other info bars.
-In the default setup, the \fIC\-t a\fP keystroke is bound to this command.
+.B chdir
+Change the current directory for ratpoison.
 .TP
-.B colon \fIcommand\fP
+.B colon \fICOMMAND\fP
 Run a ratpoison command.
 .TP
 .B curframe
 Indicate which frame is the current frame.
 .TP
+.B defbarborder \fIN\fP
+Set the border width for the bar.
+
+When called non\-interactively with no arguments, the current
+setting is returned.
+.TP
+.B defbarloc \fILOC\fP
+Set the message bar location. \fILOC\fP can be one of `northeast', `northwest',
+`southeast', `southwest', or their abbreviations.
+
+When called non\-interactively with no arguments, the current
+setting is returned.
+.TP
+.B defbarpadding \fIX Y\fP
+Set the horizontal and vertical padding inside the bar.
+
+When called non\-interactively with no arguments, the current
+setting is returned.
+.TP
+.B defbgcolor \fICOLOR\fP
+Set the background color for all text ratpoison displays. \fICOLOR\fP is any
+valid X11 color.
+.TP
+.B defborder \fIN\fP
+Set the border width for all windows.
+
+When called non\-interactively with no arguments, the current
+setting is returned.
+.TP
+.B deffgcolor \fICOLOR\fP
+Set the foreground color for all text ratpoison displays. \fICOLOR\fP is any
+valid X11 color.
+.TP
+.B deffont \fIFONT\fP
+Set the font. \fIFONT\fP is a font string like `9x15bold'.
+.TP
+.B definputwidth \fIN\fP
+Set the width of the input window.
+
+When called non\-interactively with no arguments, the current
+setting is returned.
+.TP
+.B defmaxsizegravity \fIG\fP
+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.
+.TP
+.B defpadding \fILEFT TOP RIGHT BOTTOM\fP
+Set the padding around the edge of the screen.
+
+When called non\-interactively with no arguments, the current
+setting is returned.
+.TP
+.B deftransgravity \fIG\fP
+Set the default alignment for transient windows. See the `gravity'
+command.
+
+When called non\-interactively with no arguments, the current
+setting is returned.
+.TP
+.B defwaitcursor \fIN\fP
+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.
+.TP
+.B defwinfmt \fIFMT\fP
+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.
+.TP
+.B defwingravity \fIG\fP
+Set the default gravity for normal windows. See the `gravity'
+command.
+
+When called non\-interactively with no arguments, the current
+setting is returned.
+.TP
+.B defwinname \fINAME\fP
+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. \fINAME\fP 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.
+.TP
 .B delete
-This deletes the current window. You can access it with the \fIC\-t k\fP
+This deletes the current window. You can access it with the `C\-t k'
 keystroke.
 .TP
-.B escape \fIkey\fP
-Set the prefix to to \fIkey\fP. For example \fIescape C\-b\fP sets the
-prefix key to \fIC\-b\fP.
+.B echo \fITEXT\fP
+Display \fITEXT\fP as a message.
+.TP
+.B escape \fIKEY\fP
+Set the prefix to to \fIKEY\fP. For example `escape C\-b' sets the prefix key
+to <C\-b>.
+.TP
+.B exec \fICOMMAND\fP
+Execute a shell command. By default, `C\-t !' does this.
 .TP
 .B focus
 cycle through ratpoison's frames.
 .TP
-.B generate
-Send a \fIC\-t\fP to the current window.
+.B focuslast
+Switch to the last focused frame.
+.TP
+.B focusup
+Move to the frame above the current frame.
+.TP
+.B focusdown
+Move to the frame below the current frame.
+.TP
+.B focusleft
+Move to the frame left of the current frame.
+.TP
+.B focusright
+Move to the frame right of the current frame.
+.TP
+.B gravity \fIG\fP
+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 \fIG\fP 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. \fIG\fP and can be abbreviated to one or two letters.
 .TP
 .B help
 Display a help screen that lists all bound keystrokes.
 .TP
-.B echo \fItext\fP
-Display \fItext\fP as a message.
-.TP
-.B exec \fIcommand\fP
-Execute a shell command. By default, \fIC\-t !\fP does this.
+.B info
+Display information about the current window.
 .TP
 .B kill
 This destroys the current window. Normally you should only need to
-use \fIdelete\fP, but just in case you need to rip the heart out of a
-misbehaving window this command should do the trick. Also available as
-\fIC\-t K\fP.
+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'.
 .TP
-.B maximize
-Maximize the current window, just like \fIC\-t m\fP would do.
+.B lastmsg
+Display the last message.
 .TP
-.B next
-This jumps you to the next window in the window list. This one is
-bound to three keystrokes, namely \fIC\-t n\fP, \fIC\-t space\fP,
-and \fIC\-t enter\fP.
+.B link \fIKEY\fP
+Call the command that \fIKEY\fP is bound to. For instance `link C\-t' would
+call the command `other' and switch to the last window.
+.TP
+.B meta
+Send a `C\-t' to the current window.
 .TP
-.B newwm \fIwindow-manager\fP
-This is a bad-bad command. It kills ratpoison and revives that
+.B msgwait \fIN\fP
+Set the bar's timeout in seconds.
+
+When called non\-interactively with no arguments, the current
+setting is returned.
+.TP
+.B redisplay
+Redisplay the current window, just like `C\-t l' would do.
+.TP
+.B restart
+Restart ratpoison.
+.TP
+.B newwm \fIWINDOW\-MANAGER\fP
+This is a bad\-bad command. It kills ratpoison and revives that
 ugly rodent! Yuck! Avoid!
 .TP
-.B number \fIn\fP
-Set the current window's number to \fIn\fP. If another window occupies
-the requested number already, then the windows' numbers are swapped.
+.B 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'.
+.TP
+.B number \fIN TARGET\fP
+Set a window's number to \fIN\fP. If another window occupies the requested
+number already, then the windows' numbers are swapped.
+
+The second argument, \fITARGET\fP, is optional. It should be the number of the
+window whose number will be changed. If \fITARGET\fP is omitted ratpoison
+defaults to the current window.
 .TP
 .B only
 Kill all frames but the current one.
 .TP
 .B other
 This toggles between the current window and the last window. By
-default, this is bound to \fIC\-t C\-t\fP.
+default, this is bound to `C\-t C\-t'.
 .TP
 .B prev
-This jumps you to the previous window in the window list. By default,
-this is bound to \fIC\-t p\fP.
+This jumps you to the previous window in the window list. By
+default, this is bound to `C\-t p'.
 .TP
 .B quit
 Quit ratpoison.
@@ -216,10 +378,10 @@ Quit ratpoison.
 .B remove
 Kill the current frame. This is a no\-op if there is only one frame.
 .TP
-.B rudeness \fIn\fP
-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.
+.B rudeness \fIN\fP
+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
@@ -227,115 +389,141 @@ 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.
+either honour these requests (the default operation) or ignore
+them.
+
+\fIN\fP 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
 
-\fIn\fP is a number from 0 to 15. Each of the four bits determine
-which requests ratpoison grants.
+Bit 1
+Tells ratpoison to grant raise requests on normal windows
 
-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.
+Bit 2
+Tells ratpoison to grant display requests on new transient
+windows
 
-For example, if you wanted only wanted to grant transient windows
-raise requests and display requests you would type \fIrudeness
-5\fP. If a request is not granted ratpoison will tell you about the
-request with a message like \fIRaise request from window 1
-(emacs)\fP.
+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)'.
+.TP
+.B select \fIN\fP
+This jumps you to window \fIN\fP where \fIN\fP 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 \-'.
 .TP
-.B select \fIn\fP
-This jumps you to window \fIn\fP where \fIn\fP is the window number as
-shown in the Program Bar. You can do the same trick with
-\fIC\-n\fP too. To select no window, blanking the current
-frame, type \fIselect \-\fP.
+.B select \fIWINDOW\-NAME\fP
+Go to a window by name. A shortcut is `C\-t ''.
 .TP
-.B select \fIwindow\-name\fP
-Go to a window by name. A shortcut is \fIC\-t '\fP.
+.B setenv \fIENV VALUE\fP
+Set the environment variable \fIENV\fP to \fIVALUE\fP
 .TP
-.B source \fIfile\fP
+.B source \fIFILE\fP
 Read a text file containing ratpoison commands.
 .TP
-.B split,
+.B split
+.PP
 .B hsplit
-Split the current window horizontally in two. The last accessed window
-not occupying a frame will be the second window.
+Split the current window horizontally in two. The last accessed
+window not occupying a frame will be the second window.
+.TP
+.B startup_message \fISTATE\fP
+Turn on or off the startup_message. This is most useful in your
+~/.ratpoisonrc file. \fISTATE\fP can be `on' or `off'.
+.TP
+.B time
+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.
 .TP
-.B title \fItitle\fP
+.B title \fITITLE\fP
 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 \fIC\-t A\fP keystroke is bound to this command.
+duration of the window's life, unless you change it again. By
+default, the `C\-t A' keystroke is bound to this command.
 .TP
-.B unbind \fIkey\fP
+.B unbind \fIKEY\fP
 Unbind a keystroke.
 .TP
+.B unsetenv \fIENV\fP
+Clear the value of the environment variable, \fIENV\fP.
+.TP
 .B version
-Print ratpoison version.  By default, this is bound to \fIC\-t v\fP.
+Print ratpoison version. By default, this is bound to `C\-t v'.
 .TP
 .B vsplit
-Split the current window vertically in two. The last accessed window not
-occupying a frame will be the second window.
-.TP
-.B windows
-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 \fIC\-t n\fP where \fIn\fP
-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 \fIC\-t '\fP and type the number at the
-prompt.
+Split the current window vertically in two. The last accessed
+window not occupying a frame will be the second window.
+.TP
+.B windows \fIFMT\fP
+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 \fIC\-t w\fP by default.
+This command is bound to `C\-t w' by default.
 
-When invoked from the command-line like this,
+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.
-
+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 \fIFMT\fP comes into play. If
+`windows' is given an arg it treats it as the format string as described in
+`defwinfmt'.
 .SH OPTIONS
-These are the command line options that are recognized by ratpoison:
 .TP
-\fB\-r\fR, \fB\-\-restart\fR
-restart ratpoison
+.B \-h, \-\-help
+Display this help screen
 .TP
-\fB\-k\fR, \fB\-\-kill\fR
-kill ratpoison
+.B \-v, \-\-version
+Display the version
 .TP
-\fB\-v\fR, \fB\-\-version\fR
-output version information and exit
+.B \-c \fIcmd\fP, \-\-command \fIcmd\fP
+Send ratpoison a colon\-command.
+.SH FILES
 .TP
-\fB\-h\fR, \fB\-\-help\fR
-display this help and exit
+.B /etc/ratpoisonrc
+System-wide configuration file.
 .TP
-\fB\-c\fR \fIcmd\fP, \fB\-\-command\fR \fIcmd\fP
-Tell the running ratpoison process to execute the command
-\fIcmd\fP. This is how ratpoison can be controlled from the
-command-line or from a script.
+.B $HOME/.ratpoisonrc
+User configuration file.
 .SH "REPORTING BUGS"
 Report bugs to <ratpoison\-devel@lists.sourceforge.net>.
 .SH COPYRIGHT
-Copyright \(co 2000, 2001 Shawn Betts
-.br
-This is free software; see the source for copying conditions.  There is NO
+Copyright \(co 2000, 2001, 2002 Shawn Betts
+.br 
+This is free software; see the source for copying conditions. There is NO
 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 .SH "SEE ALSO"
+ratmenu(1), X(7x)
+.PP
 The full documentation for
-.B ratpoison
-is maintained as a Texinfo manual.  If the
+.B ratpoison 
+is maintained as a Texinfo manual. If the
 .B info
 and
 .B ratpoison
 programs are properly installed at your site, the command
 .IP
 .B info ratpoison
-.PP
+.PP 
 should give you access to the complete manual.
 .SH AUTHOR
 Ratpoison was written by Shawn Betts <sabetts@users.sourceforge.net>.
 
 This manual page was written by Gergely Nagy <8@free.bsd.hu> and
-updated by Shawn Betts <sabetts@users.sourceforge.net>.
+updated by Shawn Betts <sabetts@users.sourceforge.net> and Doug
+Kearns <djkea2@mugca.cc.monash.edu.au>.