--- rxvt-unicode/doc/rxvt.1.man.in 2005/02/16 22:16:30 1.17 +++ rxvt-unicode/doc/rxvt.1.man.in 2006/01/03 23:41:37 1.35 @@ -129,7 +129,7 @@ .\" ======================================================================== .\" .IX Title "rxvt 1" -.TH rxvt 1 "2005-02-16" "5.2" "RXVT-UNICODE" +.TH rxvt 1 "2006-01-04" "6.2" "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 @@ -289,16 +300,22 @@ section of @@RXVT_NAME@@(7). .IP "\fB\-fb\fR \fIfontlist\fR" 4 .IX Item "-fb fontlist" -Compile font\-styles: The bold font list to use when bold characters are to +Compile font\-styles: The bold font list to use when \fBbold\fR characters are to be printed. See resource \fBboldFont\fR for details. .IP "\fB\-fi\fR \fIfontlist\fR" 4 .IX Item "-fi fontlist" -Compile font\-styles: The italic font list to use when bold characters are to +Compile font\-styles: The italic font list to use when \fIitalic\fR characters are to be printed. See resource \fBitalicFont\fR for details. .IP "\fB\-fbi\fR \fIfontlist\fR" 4 .IX Item "-fbi fontlist" -Compile font\-styles: The bold italic font list to use when bold characters are to -be printed. See resource \fBboldItalicFont\fR for details. +Compile font\-styles: The bold italic font list to use when \fB\f(BIbold +italic\fB\fR characters are to be printed. See resource \fBboldItalicFont\fR +for details. +.IP "\fB\-is\fR|\fB+is\fR" 4 +.IX Item "-is|+is" +Compile font\-styles: Bold/Italic font styles imply high intensity +foreground/background (default). See resource \fBintensityStyles\fR for +details. .IP "\fB\-name\fR \fIname\fR" 4 .IX Item "-name name" Specify the application name under which resources are to be obtained, @@ -336,7 +353,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 +407,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 +467,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 +493,51 @@ 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 +.IP "\fB\-pe\fR \fIstring\fR" 4 +.IX Item "-pe string" +Colon-separated list of perl extension scripts to use in this terminal instance. See resource \fBperl-ext\fR. .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 +647,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 +666,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 @@ -618,7 +698,7 @@ names that are used in turn when trying to display Unicode characters. The first font defines the cell size for characters; other fonts might be smaller, but not larger. A reasonable default font list is always -appended to it. option \fB\-fn\fR. +appended to it; option \fB\-fn\fR. .Sp Each font can either be a standard X11 core font (\s-1XLFD\s0) name, with optional prefix \f(CW\*(C`x:\*(C'\fR or a Xft font (Compile \fIxft\fR), prefixed with \f(CW\*(C`xft:\*(C'\fR. @@ -676,6 +756,13 @@ .Sp If set, but empty, then this specific style is disabled and the normal text font will being used for the given style. +.IP "\fBintensityStyles:\fR \fIboolean\fR" 4 +.IX Item "intensityStyles: boolean" +When font styles are not enabled, or this option is enabled (\fBTrue\fR, +option \fB\-is\fR, the default), bold and italic font styles imply high +intensity foreground/backround colours. Disabling this option (\fBFalse\fR, +option \fB+is\fR) disables this behaviour, the high intensity colours are not +reachable. .IP "\fBselectstyle:\fR \fImode\fR" 4 .IX Item "selectstyle: mode" Set mouse selection style to \fBold\fR which is 2.20, \fBoldword\fR which is @@ -684,7 +771,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 +805,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 +901,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 @@ -832,7 +931,7 @@ The locale to use for opening the \s-1IM\s0. You can use an \f(CW\*(C`LC_CTYPE\*(C'\fR of e.g. \&\f(CW\*(C`de_DE.UTF\-8\*(C'\fR for normal text processing but \f(CW\*(C`ja_JP.EUC\-JP\*(C'\fR for the input extension to be able to input japanese characters while staying in -another locale. option \fB\-imlocale\fR. +another locale; option \fB\-imlocale\fR. .IP "\fBimFont:\fR \fIfontset\fR" 4 .IX Item "imFont: fontset" Specify the font-set used for \s-1XIM\s0 styles \f(CW\*(C`OverTheSpot\*(C'\fR or @@ -845,19 +944,21 @@ .IX Item "tripleclickwords: boolean" Change the meaning of triple-click selection with the left mouse button. Instead of selecting a full line it will extend the selection to -the end of the logical line only. option \fB\-tcw\fR. +the end of the logical line only; option \fB\-tcw\fR. .IP "\fBinsecure:\fR \fIboolean\fR" 4 .IX Item "insecure: boolean" 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 +978,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 +1044,36 @@ \& URxvt.keysym.M-C-c: command:\e033]701;zh_CN.GBK\e007 .Ve .Sp +If \fIstring\fR takes the form \f(CW\*(C`perl:STRING\*(C'\fR, then the specified \fB\s-1STRING\s0\fR +is passed to the \f(CW\*(C`on_keyboard_command\*(C'\fR perl handler. See the @@RXVT_NAME@@\fIperl\fR\|(3) +manpage. For example, the \fIselection\fR extension (activated via +\&\f(CW\*(C`@@RXVT_NAME@@ \-pe selection\*(C'\fR) listens for \f(CW\*(C`selection:rot13\*(C'\fR events: +.Sp +.Vb 1 +\& URxvt.keysym.M-C-c: perl:selection:rot13 +.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: @@ -953,6 +1090,25 @@ \& URxvt.keysym.M-C-3: command:\e033[8;25;80t \& URxvt.keysym.M-C-4: command:\e033[8;48;110t .Ve +.IP "\fBperl-ext\fR: \fIstring\fR" 4 +.IX Item "perl-ext: string" +Colon-separated list of perl extension scripts to use in this terminal +instance. Each extension is looked up in the library directories, loaded +if necessary, and bound to the current terminal instance. If this resource +is empty or missing, then the perl interpreter will not be initialized; +option \fB\-pe\fR. +.IP "\fBperl-eval\fR: \fIstring\fR" 4 +.IX Item "perl-eval: string" +Perl code to be evaluated when all extensions have been registered. See the +@@RXVT_NAME@@\fIperl\fR\|(3) manpage. +.IP "\fBperl-lib\fR: \fIpath\fR" 4 +.IX Item "perl-lib: path" +Colon-separated list of additional directories that hold extension +scripts. When looking for extensions specified by the \f(CW\*(C`perl\*(C'\fR resource, +@@RXVT_NAME@@ will first look in these directories and then in +\&\fI@@RXVT_LIBDIR@@/urxvt/perl/\fR. +.Sp +See the @@RXVT_NAME@@\fIperl\fR\|(3) manpage. .SH "THE SCROLLBAR" .IX Header "THE SCROLLBAR" Lines of text that scroll off the top of the \fB@@RXVT_NAME@@\fR window @@ -989,8 +1145,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 +1163,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 +1320,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\-