--- rxvt-unicode/doc/rxvt.1.man.in 2005/02/16 22:16:30 1.17 +++ rxvt-unicode/doc/rxvt.1.man.in 2005/12/27 12:24:09 1.29 @@ -129,7 +129,7 @@ .\" ======================================================================== .\" .IX Title "rxvt 1" -.TH rxvt 1 "2005-02-16" "5.2" "RXVT-UNICODE" +.TH rxvt 1 "2005-12-27" "6.1" "RXVT-UNICODE" .SH "NAME" rxvt\-unicode (ouR XVT, unicode) \- (a VT102 emulator for the X window system) .SH "SYNOPSIS" @@ -225,19 +225,30 @@ .IP "\fB\-j\fR|\fB+j\fR" 4 .IX Item "-j|+j" Turn on/off jump scrolling; resource \fBjumpScroll\fR. -.IP "\fB\-ip\fR|\fB+ip\fR" 4 -.IX Item "-ip|+ip" +.IP "\fB\-ip\fR|\fB+ip\fR | \fB\-tr\fR|\fB+tr\fR" 4 +.IX Item "-ip|+ip | -tr|+tr" Turn on/off inheriting parent window's pixmap. Alternative form is \&\fB\-tr\fR; resource \fBinheritPixmap\fR. .IP "\fB\-fade\fR \fInumber\fR" 4 .IX Item "-fade number" -Fade the text by the given percentage when focus is lost. resource \fBfading\fR. +Fade the text by the given percentage when focus is lost. Small values +fade a little only, 100 completely replaces all colours by the fade +colour; resource \fBfading\fR. +.IP "\fB\-fadecolor\fR \fIcolour\fR" 4 +.IX Item "-fadecolor colour" +Fade to this colour when fading is used (see \fB\-fade\fR). The default colour +is black. resource \fBfadeColor\fR. .IP "\fB\-tint\fR \fIcolour\fR" 4 .IX Item "-tint colour" Tint the transparent background pixmap with the given colour when -transparency is enabled with \fB\-tr\fR or \fB\-ip\fR. See also the \fB\-sh\fR -option that can be used to brighten or darken the image in addition to -tinting it. +transparency is enabled with \fB\-tr\fR or \fB\-ip\fR. This only works for +non-tiled backgrounds, currently. See also the \fB\-sh\fR option that can be +used to brighten or darken the image in addition to tinting it; resource +\&\fItintColor\fR. Example: +.Sp +.Vb 1 +\& @@RXVT_NAME@@ -tr -tint blue -sh 40 +.Ve .IP "\fB\-sh\fR" 4 .IX Item "-sh" \&\fInumber\fR Darken (0 .. 100) or lighten (\-1 .. \-100) the transparent @@ -336,7 +347,7 @@ Put scrollbar on right/left; resource \fBscrollBar_right\fR. .IP "\fB\-st\fR|\fB+st\fR" 4 .IX Item "-st|+st" -Display normal (non XTerm/NeXT) scrollbar without/with a trough; +Display rxvt (non XTerm/NeXT) scrollbar without/with a trough; resource \fBscrollBar_floating\fR. .IP "\fB\-ptab\fR|\fB+ptab\fR" 4 .IX Item "-ptab|+ptab" @@ -390,6 +401,13 @@ on the command\-line. If there is no \fB\-e\fR option then the default is to run the program specified by the \fB\s-1SHELL\s0\fR environment variable or, failing that, \fI\fIsh\fI\|(1)\fR. +.Sp +Please note that you must specify a program with arguments. If you want to +run shell commands, you have to specify the shell, like this: +.Sp +.Vb 1 +\& @@RXVT_NAME@@ -e sh -c "shell commands" +.Ve .IP "\fB\-title\fR \fItext\fR" 4 .IX Item "-title text" Window title (\fB\-T\fR still respected); the default title is the basename @@ -443,11 +461,17 @@ .IX Item "-ssr|+ssr" Turn on/off secondary screen scroll (default enabled); resource \&\fBsecondaryScroll\fR. -.IP "\fB\-keysym.\fR\fIsym\fR: \fIstring\fR" 4 -.IX Item "-keysym.sym: string" +.IP "\fB\-hold\fR|\fB+hold\fR" 4 +.IX Item "-hold|+hold" +Turn on/off hold window after exit support. If enabled, @@RXVT_NAME@@ +will not immediately destroy its window when the program executed within +it exits. Instead, it will wait till it is being killed or closed by the +user; resource \fBhold\fR. +.IP "\fB\-keysym.\fR\fIsym\fR \fIstring\fR" 4 +.IX Item "-keysym.sym string" Remap a key symbol. See resource \fBkeysym\fR. -.IP "\fB\-embed\fR: \fIwindowid\fR" 4 -.IX Item "-embed: windowid" +.IP "\fB\-embed\fR \fIwindowid\fR" 4 +.IX Item "-embed windowid" Tells @@RXVT_NAME@@ to embed it's windows into an already-existing window, which enables applications to easily embed a terminal. .Sp @@ -463,6 +487,48 @@ can use file descriptors to communicate with the programs within the terminal. This works regardless of wether the \f(CW\*(C`\-embed\*(C'\fR option was used or not. +.Sp +Here is a short Gtk2\-perl snippet that illustrates how this option can be +used (a longer example is in \fIdoc/embed\fR): +.Sp +.Vb 5 +\& my $rxvt = new Gtk2::Socket; +\& $rxvt->signal_connect_after (realize => sub { +\& my $xid = $_[0]->window->get_xid; +\& system "@@RXVT_NAME@@ -embed $xid &"; +\& }); +.Ve +.IP "\fB\-pty\-fd\fR \fIfileno\fR" 4 +.IX Item "-pty-fd fileno" +Tells @@RXVT_NAME@@ \s-1NOT\s0 to execute any commands or create a new pty/tty +pair but instead use the given filehandle as the tty master. This is +useful if you want to drive @@RXVT_NAME@@ as a generic terminal emulator +without having to run a program within it. +.Sp +If this switch is given, @@RXVT_NAME@@ will not create any utmp/wtmp +entries and will not tinker with pty/tty permissions \- you have to do that +yourself if you want that. +.Sp +Here is a example in perl that illustrates how this option can be used (a +longer example is in \fIdoc/pty\-fd\fR): +.Sp +.Vb 2 +\& use IO::Pty; +\& use Fcntl; +.Ve +.Sp +.Vb 4 +\& my $pty = new IO::Pty; +\& fcntl $pty, F_SETFD, 0; # clear close-on-exec +\& system "@@RXVT_NAME@@ -pty-fd " . (fileno $pty) . "&"; +\& close $pty; +.Ve +.Sp +.Vb 3 +\& # now communicate with rxvt +\& my $slave = $pty->slave; +\& while (<$slave>) { print $slave "got <$_>\en" } +.Ve .SH "RESOURCES (available also as long\-options)" .IX Header "RESOURCES (available also as long-options)" Note: `@@RXVT_NAME@@ \-\-help' gives a list of all resources (long @@ -572,10 +638,15 @@ pixmap. .IP "\fBfading:\fR \fInumber\fR" 4 .IX Item "fading: number" -Fade the text by the given percentage when focus is lost. +Fade the text by the given percentage when focus is lost; option \fB\-fade\fR. +.IP "\fBfadeColor:\fR \fIcolour\fR" 4 +.IX Item "fadeColor: colour" +Fade to this colour, when fading is used (see \fBfading:\fR). The default +colour is black; option \fB\-fadecolor\fR. .IP "\fBtintColor:\fR \fIcolour\fR" 4 .IX Item "tintColor: colour" -Tint the transparent background pixmap with the given colour. +Tint the transparent background pixmap with the given colour; option +\&\fB\-tint\fR. .IP "\fBshading:\fR \fInumber\fR" 4 .IX Item "shading: number" Darken (0 .. 100) or lighten (\-1 .. \-100) the transparent background @@ -586,7 +657,7 @@ .IP "\fBtroughColor:\fR \fIcolour\fR" 4 .IX Item "troughColor: colour" Use the specified colour for the scrollbar's trough area [default -#969696]. Only relevant for normal (non XTerm/NeXT) scrollbar. +#969696]. Only relevant for rxvt (non XTerm/NeXT) scrollbar. .IP "\fBborderColor:\fR \fIcolour\fR" 4 .IX Item "borderColor: colour" The colour of the border around the text area and between the scrollbar @@ -684,7 +755,7 @@ .IP "\fBscrollstyle:\fR \fImode\fR" 4 .IX Item "scrollstyle: mode" Set scrollbar style to \fBrxvt\fR, \fBplain\fR, \fBnext\fR or \fBxterm\fR. \fBplain\fR is -the author's favourite.. +the author's favourite. .IP "\fBtitle:\fR \fIstring\fR" 4 .IX Item "title: string" Set window title string, the default title is the command-line @@ -718,6 +789,17 @@ Specify a command pipe for vt100 printer [default \fI\fIlpr\fI\|(1)\fR]. Use \&\fBPrint\fR to initiate a screen dump to the printer and \fBCtrl-Print\fR or \&\fBShift-Print\fR to include the scrollback as well. +.Sp +The string will be interpreted as if typed into the shell as\-is. +.Sp +Example: +.Sp +.Vb 1 +\& URxvt*print-pipe: cat > $(TMPDIR=$HOME mktemp urxvt.XXXXXX) +.Ve +.Sp +This creates a new file in your home directory with the screen contents +everytime you hit \f(CW\*(C`Print\*(C'\fR. .IP "\fBscrollBar:\fR \fIboolean\fR" 4 .IX Item "scrollBar: boolean" \&\fBTrue\fR: enable the scrollbar [default]; option \fB\-sb\fR. \fBFalse\fR: @@ -803,7 +885,8 @@ Mouse pointer background colour. .IP "\fBpointerBlankDelay:\fR \fInumber\fR" 4 .IX Item "pointerBlankDelay: number" -Specifies number of seconds before blanking the pointer [default 2]. +Specifies number of seconds before blanking the pointer [default 2]. Use a +large number (e.g. \f(CW987654321\fR) to effectively disable the timeout. .IP "\fBbackspacekey:\fR \fIstring\fR" 4 .IX Item "backspacekey: string" The string to send when the backspace key is pressed. If set to \fB\s-1DEC\s0\fR @@ -851,13 +934,15 @@ Enables \*(L"insecure\*(R" mode. Rxvt-unicode offers some escape sequences that echo arbitrary strings like the icon name or the locale. This could be abused if somebody gets 8\-bit\-clean access to your display, whether -throuh a mail client displaying mail bodies unfiltered or though -\&\fIwrite\fR\|(1). Therefore, these sequences are disabled by default. (Note -that other terminals, including xterm, have these sequences -enabled by default). You can enable them by setting this boolean -resource or specifying \fB\-insecure\fR as an option. At the moment, this -enabled display\-answer, locale, findfont, icon label and window title -requests as well as dynamic menubar dispatch. +through a mail client displaying mail bodies unfiltered or through +\&\fIwrite\fR\|(1) or any other means. Therefore, these sequences are disabled by +default. (Note that many other terminals, including xterm, have these +sequences enabled by default, which doesn't make it safer, though). +.Sp +You can enable them by setting this boolean resource or specifying +\&\fB\-insecure\fR as an option. At the moment, this enables display\-answer, +locale, findfont, icon label and window title requests as well as dynamic +menubar dispatch. .IP "\fBmodifier:\fR \fImodifier\fR" 4 .IX Item "modifier: modifier" Set the key to be interpreted as the Meta key to: \fBalt\fR, \fBmeta\fR, @@ -877,6 +962,12 @@ option is enabled, scrolls on the secondary screen will change the scrollback buffer and switching to/from the secondary screen will instead scroll the screen up. +.IP "\fBhold\fR: \fIbool\fR" 4 +.IX Item "hold: bool" +Turn on/off hold window after exit support. If enabled, @@RXVT_NAME@@ +will not immediately destroy its window when the program executed within +it exits. Instead, it will wait till it is being killed or closed by the +user. .IP "\fBkeysym.\fR\fIsym\fR: \fIstring\fR" 4 .IX Item "keysym.sym: string" Compile \fIfrills\fR: Associate \fIstring\fR with keysym \fIsym\fR. The @@ -937,6 +1028,27 @@ \& URxvt.keysym.M-C-c: command:\e033]701;zh_CN.GBK\e007 .Ve .Sp +Due the the large number of modifier combinations, a defined key mapping +will match if at \fIat least\fR the specified identifiers are being set, and +no other key mappings with those and more bits are being defined. That +means that defining a key map for \f(CW\*(C`a\*(C'\fR will automatically provide +definitions for \f(CW\*(C`Meta\-a\*(C'\fR, \f(CW\*(C`Shift\-a\*(C'\fR and so on, unless some of those are defined +mappings themselves. +.Sp +Unfortunately, this will override built-in key mappings. For example +if you overwrite the \f(CW\*(C`Insert\*(C'\fR key you will disable @@RXVT_NAME@@'s +\&\f(CW\*(C`Shift\-Insert\*(C'\fR mapping. To re-enable that, you can poke \*(L"holes\*(R" into the +user-defined keymap using the \f(CW\*(C`builtin:\*(C'\fR replacement: +.Sp +.Vb 2 +\& URxvt.keysym.Insert: +\& URxvt.keysym.S-Insert: builtin: +.Ve +.Sp +The first line defines a mapping for \f(CW\*(C`Insert\*(C'\fR and \fIany\fR combination +of modifiers. The second line re-establishes the default mapping for +\&\f(CW\*(C`Shift\-Insert\*(C'\fR. +.Sp The following example will map Control\-Meta\-1 and Control\-Meta\-2 to the fonts \f(CW\*(C`suxuseuro\*(C'\fR and \f(CW\*(C`9x15bold\*(C'\fR, so you can have some limited font-switching at runtime: @@ -989,8 +1101,10 @@ \&\fBtripleclickwords\fR. .Sp Starting a selection while pressing the \fBMeta\fR key (or \fBMeta+Ctrl\fR keys) -(Compile: \fIfrills\fR) will create a rectangular selection instead of a normal -one. +(Compile: \fIfrills\fR) will create a rectangular selection instead of a +normal one. In this mode, every selected row becomes its own line in the +selection, and trailing whitespace is visually underlined and removed from +the selection. .IP "\fBInsertion\fR:" 4 .IX Item "Insertion:" Pressing and releasing the Middle mouse button (or \fBShift-Insert\fR) in @@ -1005,7 +1119,7 @@ therefore using the menubar), e.g.: .PP .Vb 1 -\& printf '\ee]701;%s\e007' "9x15bold,xft:Kochi Gothic" +\& printf '\ee]710;%s\e007' "9x15bold,xft:Kochi Gothic" .Ve .PP rxvt-unicode will automatically re-apply these fonts to the output so far. @@ -1162,7 +1276,7 @@ The unix domain socket path used by @@RXVT_NAME@@c(1) and @@RXVT_NAME@@d(1). .Sp -Default \f(CW\*(C`$HOME/.rxvt\-unicode\-