--- rxvt-unicode/doc/rxvt.1.man.in 2005/02/16 22:16:30 1.17 +++ rxvt-unicode/doc/rxvt.1.man.in 2006/01/25 21:48:47 1.53 @@ -129,7 +129,7 @@ .\" ======================================================================== .\" .IX Title "rxvt 1" -.TH rxvt 1 "2005-02-16" "5.2" "RXVT-UNICODE" +.TH rxvt 1 "2006-01-25" "7.3" "RXVT-UNICODE" .SH "NAME" rxvt\-unicode (ouR XVT, unicode) \- (a VT102 emulator for the X window system) .SH "SYNOPSIS" @@ -216,6 +216,10 @@ Attempt to open a window on the named X display (\fB\-d\fR still respected). In the absence of this option, the display specified by the \&\fB\s-1DISPLAY\s0\fR environment variable is used. +.IP "\fB\-depth\fR \fIbitdepth\fR" 4 +.IX Item "-depth bitdepth" +Compile \fIfrills\fR: Attempt to find a visual with the given bit depth; +resource \fBdepth\fR. .IP "\fB\-geometry\fR \fIgeom\fR" 4 .IX Item "-geometry geom" Window geometry (\fB\-g\fR still respected); resource \fBgeometry\fR. @@ -225,19 +229,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 @@ -271,7 +286,7 @@ .IP "\fB\-fn\fR \fIfontlist\fR" 4 .IX Item "-fn fontlist" Select the fonts to be used. This is a comma separated list of font names -that are used in turn when trying to display Unicode characters. The +that are checked in order when trying to find glyphs for characters. The first font defines the cell size for characters; other fonts might be smaller, but not (in general) larger. A (hopefully) reasonable default font list is always appended to it. See resource \fBfont\fR for more details. @@ -289,16 +304,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 -be printed. See resource \fBboldFont\fR for details. +Compile \fIfont-styles\fR: 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 -be printed. See resource \fBitalicFont\fR for details. +Compile \fIfont-styles\fR: 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 \fIfont-styles\fR: 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 \fIfont-styles\fR: 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 +357,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" @@ -370,6 +391,16 @@ Compile \fIfrills\fR: Set \s-1MWM\s0 hints to request a borderless window, i.e. if honoured by the \s-1WM\s0, the rxvt-unicode window will not have window decorations; resource \fBborderLess\fR. +.IP "\fB\-override\-redirect\fR" 4 +.IX Item "-override-redirect" +Compile \fIfrills\fR: Sets override-redirect on the window; resource +\&\fBoverride-redirect\fR. +.IP "\fB\-sbg\fR" 4 +.IX Item "-sbg" +Compile \fIfrills\fR: Disable the usage of the built-in block graphics/line +drawing characters and just rely on what the specified fonts provide. Use +this if you have a good font and want to use its block graphic glyphs; +resource \fBskipBuiltinGlyphs\fR. .IP "\fB\-lsp\fR \fInumber\fR" 4 .IX Item "-lsp number" Compile \fIfrills\fR: Lines (pixel height) to insert between each row of @@ -390,6 +421,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 +481,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,19 +507,64 @@ 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 \fIfile descriptor\fR" 4 +.IX Item "-pty-fd file descriptor" +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 +As an extremely special case, specifying \f(CW\*(C`\-1\*(C'\fR will completely suppress +pty/tty operations. +.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" +Comma-separated list of perl extension scripts to use (or not to use) in +this terminal instance. See resource \fBperl-ext\fR for details. .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 options) compiled into your version. .PP -There are two different methods that @@RXVT_NAME@@ can use to get the -Xresource data: using the X libraries (Xrm*\-functions) or internal -Xresources reader (\fB~/.Xdefaults\fR). For the first method (ie. -\&\fB@@RXVT_NAME@@ \-h\fR lists \fBXGetDefaults\fR), you can set and change the -resources using X11 tools like \fBxrdb\fR. Many distribution do also load -settings from the \fB~/.Xresources\fR file when X starts. @@RXVT_NAME@@ -will consult the following files/resources in order, with later settings -overwriting earlier ones: +You can set and change the resources using X11 tools like \fBxrdb\fR. Many +distribution do also load settings from the \fB~/.Xresources\fR file when X +starts. @@RXVT_NAME@@ will consult the following files/resources in order, +with later settings overwriting earlier ones: .PP .Vb 5 \& 1. system-wide app-defaults file, either locale-dependent OR global @@ -485,20 +574,20 @@ \& 5. $XENVIRONMENT file OR $HOME/.Xdefaults- .Ve .PP -If compiled with internal Xresources support (i.e. \fB@@RXVT_NAME@@ \-h\fR -lists \fB.Xdefaults\fR) then \fB@@RXVT_NAME@@\fR accepts application defaults -set in XAPPLOADDIR/URxvt (compile\-time defined: usually -\&\fB/usr/lib/X11/app\-defaults/URxvt\fR) and resources set in -\&\fB~/.Xdefaults\fR, or \fB~/.Xresources\fR if \fB~/.Xdefaults\fR does not exist. -Note that when reading X resources, \fB@@RXVT_NAME@@\fR recognizes two -class names: \fBXTerm\fR and \fBURxvt\fR. The class name \fBRxvt\fR allows -resources common to both \fB@@RXVT_NAME@@\fR and the original \fIrxvt\fR to be -easily configured, while the class name \fBURxvt\fR allows resources -unique to \fB@@RXVT_NAME@@\fR, notably colours and key\-handling, to be -shared between different \fB@@RXVT_NAME@@\fR configurations. If no -resources are specified, suitable defaults will be used. Command-line -arguments can be used to override resource settings. The following -resources are allowed: +Note that when reading X resources, \fB@@RXVT_NAME@@\fR recognizes two class +names: \fBRxvt\fR and \fBURxvt\fR. The class name \fBRxvt\fR allows resources +common to both \fB@@RXVT_NAME@@\fR and the original \fIrxvt\fR to be easily +configured, while the class name \fBURxvt\fR allows resources unique to +\&\fB@@RXVT_NAME@@\fR, to be shared between different \fB@@RXVT_NAME@@\fR +configurations. If no resources are specified, suitable defaults will +be used. Command-line arguments can be used to override resource +settings. The following resources are supported (you might want to +check the @@RXVT_NAME@@\fIperl\fR\|(3) manpage for additional settings by perl +extensions not documented here): +.IP "\fBdepth:\fR \fIbitdepth\fR" 4 +.IX Item "depth: bitdepth" +Compile \fIfrills\fR: Attempt to find a visual with the given bit depth; +option \fB\-depth\fR. .IP "\fBgeometry:\fR \fIgeom\fR" 4 .IX Item "geometry: geom" Create the window with the specified X window geometry [default 80x24]; @@ -572,10 +661,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 +680,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 @@ -602,23 +696,16 @@ specifies an integer number of images in that direction. No image will be magnified beyond 10 times its original size. The maximum permitted scale is 1000. [default 0x0+50+50] -.IP "\fBmenu:\fR \fIfile[;tag]\fR" 4 -.IX Item "menu: file[;tag]" -Read in the specified menu file (note the `.menu' extension is -optional) and also optionally specify a starting tag to find. See the -reference documentation for details on the syntax for the menuBar. .IP "\fBpath:\fR \fIpath\fR" 4 .IX Item "path: path" -Specify the colon-delimited search path for finding files (\s-1XPM\s0 and -menus), in addition to the paths specified by the \fB\s-1RXVTPATH\s0\fR and -\&\fB\s-1PATH\s0\fR environment variables. +Specify the colon-delimited search path for finding \s-1XPM\s0 files. .IP "\fBfont:\fR \fIfontlist\fR" 4 .IX Item "font: fontlist" -Select the fonts to be used. This is a comma separated list of font -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. +Select the fonts to be used. This is a comma separated list of font names +that are checked in order when trying to find glyphs for characters. The +first font defines the cell size for characters; other fonts might be +smaller, but not (in general) larger. A (hopefully) reasonable default +font list is always 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. @@ -631,7 +718,7 @@ For example, this font resource .Sp .Vb 5 -\& URxvt*font: 9x15bold,\e +\& URxvt.font: 9x15bold,\e \& -misc-fixed-bold-r-normal--15-140-75-75-c-90-iso10646-1,\e \& -misc-fixed-medium-r-normal--15-140-75-75-c-90-iso10646-1, \e \& [codeset=JISX0208]xft:Kochi Gothic:antialias=false, \e @@ -676,6 +763,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 +778,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 +812,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: @@ -766,6 +871,12 @@ .IX Item "borderLess: boolean" Set \s-1MWM\s0 hints to request a borderless window, i.e. if honoured by the \&\s-1WM\s0, the rxvt-unicode window will not have window decorations; option \fB\-bl\fR. +.IP "\fBskipBuiltinGlyphs:\fR \fIboolean\fR" 4 +.IX Item "skipBuiltinGlyphs: boolean" +Compile \fIfrills\fR: Disable the usage of the built-in block graphics/line +drawing characters and just rely on what the specified fonts provide. Use +this if you have a good font and want to use its block graphic glyphs; +option \fB\-sbg\fR. .IP "\fBtermName:\fR \fItermname\fR" 4 .IX Item "termName: termname" Specifies the terminal type name to be set in the \fB\s-1TERM\s0\fR environment @@ -803,7 +914,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 @@ -817,8 +929,16 @@ with the \fBExecute\fR key. .IP "\fBcutchars:\fR \fIstring\fR" 4 .IX Item "cutchars: string" -The characters used as delimiters for double-click word selection. The -built-in default: +The characters used as delimiters for double-click word selection +(whitespace delimiting is added automatically if resource is given). +.Sp +When the selection extension is in use (the default if compiled in, see +the @@RXVT_NAME@@\fIperl\fR\|(3) manpage), a suitable regex using these characters +will be created (if the resource exists, otherwise, no regex will be +created). In this mode, characters outside \s-1ISO\-8859\-1\s0 can be used. +.Sp +When the selection extension is not used, only \s-1ISO\-8859\-1\s0 characters can +be used. If not specified, the built-in default is used: .Sp \&\fB\s-1BACKSLASH\s0 `"'&()*,;<=>?@[]{|}\fR .IP "\fBpreeditType:\fR \fIstyle\fR" 4 @@ -832,7 +952,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 +965,20 @@ .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. .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, @@ -868,15 +989,21 @@ Specify the reply rxvt-unicode sends to the shell when an \s-1ENQ\s0 (control\-E) character is passed through. It may contain escape values as described in the entry on \fBkeysym\fR following. -.IP "\fBsecondaryScreen:\fR \fIbool\fR" 4 -.IX Item "secondaryScreen: bool" +.IP "\fBsecondaryScreen:\fR \fIboolean\fR" 4 +.IX Item "secondaryScreen: boolean" Turn on/off secondary screen (default enabled). -.IP "\fBsecondaryScroll:\fR \fIbool\fR" 4 -.IX Item "secondaryScroll: bool" +.IP "\fBsecondaryScroll:\fR \fIboolean\fR" 4 +.IX Item "secondaryScroll: boolean" Turn on/off secondary screen scroll (default enabled). If the this 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: \fIboolean\fR" 4 +.IX Item "hold: boolean" +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 @@ -905,10 +1032,10 @@ \&\f(CW\*(C`^@\*(C'\fR: null, \f(CW\*(C`^A\*(C'\fR ...) and may be enclosed with double quotes so that it can start or end with whitespace. .Sp -Please note that you need to double the \f(CW\*(C`\e\*(C'\fR when using -\&\f(CW\*(C`\-\-enable\-xgetdefault\*(C'\fR, as X itself does it's own de-escaping (you can -use \f(CW\*(C`\e033\*(C'\fR instead of \f(CW\*(C`\ee\*(C'\fR (and so on), which will work with both Xt and -@@RXVT_NAME@@'s own processing). +Please note that you need to double the \f(CW\*(C`\e\*(C'\fR in resource files, as +Xlib itself does it's own de-escaping (you can use \f(CW\*(C`\e033\*(C'\fR instead of +\&\f(CW\*(C`\ee\*(C'\fR (and so on), which will work with both Xt and @@RXVT_NAME@@'s own +processing). .Sp You can define a range of keysyms in one shot by providing a \fIstring\fR with pattern \fBlist/PREFIX/MIDDLE/SUFFIX\fR, where the delimeter `/' @@ -937,6 +1064,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 +1110,71 @@ \& URxvt.keysym.M-C-3: command:\e033[8;25;80t \& URxvt.keysym.M-C-4: command:\e033[8;48;110t .Ve +.IP "\fBperl-ext-common\fR: \fIstring\fR" 4 +.IX Item "perl-ext-common: string" +.PD 0 +.IP "\fBperl-ext\fR: \fIstring\fR" 4 +.IX Item "perl-ext: string" +.PD +Comma-separated list(s) of perl extension scripts (default: \f(CW\*(C`default\*(C'\fR) to +use in this terminal instance; option \fB\-pe\fR. +.Sp +Extension names can be prefixed with a \f(CW\*(C`\-\*(C'\fR sign to prohibit using +them. This can be useful to selectively disable some extensions loaded +by default, or specified via the \f(CW\*(C`perl\-ext\-common\*(C'\fR resource. For +example, \f(CW\*(C`default,\-selection\*(C'\fR will use all the default extension except +\&\f(CW\*(C`selection\*(C'\fR. +.Sp +Extension names can also be followed by an argument in angle brackets +(e.g. \f(CW\*(C`searchable\-scrollback\*(C'\fR, which binds the hotkey for +searchable scorllback to Alt/Meta\-s). Mentioning the same extension +multiple times with different arguments will pass multiple arguments to +the extension. +.Sp +Each extension is looked up in the library directories, loaded if +necessary, and bound to the current terminal instance. +.Sp +If both of these resources are the empty string, then the perl +interpreter will not be initialized. The idea behind two options is that +\&\fBperl-ext-common\fR will be used for extensions that should be available to +all instances, while \fBperl-ext\fR is used for specific instances. +.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. Due to security reasons, this resource +will be ignored when running setuid/setgid. +.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. Due to security reasons, this resource +will be ignored when running setuid/setgid. +.Sp +See the @@RXVT_NAME@@\fIperl\fR\|(3) manpage. +.IP "\fBselection.pattern\-\f(BIidx\fB\fR: \fIperl-regex\fR" 4 +.IX Item "selection.pattern-idx: perl-regex" +Additional selection patterns, see the @@RXVT_NAME@@\fIperl\fR\|(3) manpage for +details. +.IP "\fBselection\-autotransform.\f(BIidx\fB\fR: \fIperl-transform\fR" 4 +.IX Item "selection-autotransform.idx: perl-transform" +Selection auto-transform patterns, see the @@RXVT_NAME@@\fIperl\fR\|(3) manpage +for details. +.IP "\fBsearchable\-scrollback:\fR \fIkeysym\fR" 4 +.IX Item "searchable-scrollback: keysym" +Sets the hotkey that starts the incremental scrollback buffer search +(default: \f(CW\*(C`M\-s\*(C'\fR). +.IP "\fBurlLauncher\fR: \fIstring\fR" 4 +.IX Item "urlLauncher: string" +Specifies the program to be started with a \s-1URL\s0 argument. Used by the +\&\f(CW\*(C`selection\-popup\*(C'\fR and \f(CW\*(C`mark\-urls\*(C'\fR perl extensions. +.IP "\fBtransient-for\fR: \fIwindowid\fR" 4 +.IX Item "transient-for: windowid" +Compile \fIfrills\fR: Sets the \s-1WM_TRANSIENT_FOR\s0 property to the given window id. +.IP "\fBoverride-redirect\fR: \fIboolean\fR" 4 +.IX Item "override-redirect: boolean" +Compile \fIfrills\fR: Sets override-redirect for the terminal window, making +it almost invisible to window managers; option \fB\-override\-redirect\fR. .SH "THE SCROLLBAR" .IX Header "THE SCROLLBAR" Lines of text that scroll off the top of the \fB@@RXVT_NAME@@\fR window @@ -989,23 +1211,34 @@ \&\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 -an \fB@@RXVT_NAME@@\fR window causes the current text selection to be -inserted as if it had been typed on the keyboard. +Pressing and releasing the Middle mouse button in an \fB@@RXVT_NAME@@\fR +window causes the value of the \s-1PRIMARY\s0 selection (or \s-1CLIPBOARD\s0 with the +Meta modifier) to be inserted as if it had been typed on the keyboard. +.Sp +Pressing \fBShift-Insert\fR causes the value of the \s-1PRIMARY\s0 selection to be +inserted too. .SH "CHANGING FONTS" .IX Header "CHANGING FONTS" Changing fonts (or font sizes, respectively) via the keypad is not yet supported in rxvt\-unicode. Bug me if you need this. .PP -You can, however, switch fonts at runtime using escape sequences (and -therefore using the menubar), e.g.: +You can, however, switch fonts at runtime using escape sequences, 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 +You can use keyboard shortcuts, too: +.PP +.Vb 2 +\& URxvt.keysym.M-C-1: command:\e033]710;suxuseuro\e007\e033]711;suxuseuro\e007 +\& URxvt.keysym.M-C-2: command:\e033]710;9x15bold\e007\e033]711;9x15bold\e007 .Ve .PP rxvt-unicode will automatically re-apply these fonts to the output so far. @@ -1150,19 +1383,12 @@ .IP "\fB\s-1SHELL\s0\fR" 4 .IX Item "SHELL" The shell to be used for command execution, defaults to \f(CW\*(C`/bin/sh\*(C'\fR. -.IP "\fB\s-1RXVTPATH\s0\fR" 4 -.IX Item "RXVTPATH" -The path where @@RXVT_NAME@@ looks for support files such as menu and xpm -files. -.IP "\fB\s-1PATH\s0\fR" 4 -.IX Item "PATH" -Used in the same way as \f(CW\*(C`RXVTPATH\*(C'\fR. .IP "\fB\s-1RXVT_SOCKET\s0\fR" 4 .IX Item "RXVT_SOCKET" The unix domain socket path used by @@RXVT_NAME@@c(1) and @@RXVT_NAME@@d(1). .Sp -Default \f(CW\*(C`$HOME/.rxvt\-unicode\-" 4 .IX Item "Geoff Wing " -Rewrote screen display and text selection routines. Project Coordinator -(changes.txt 2.4.6 \- rxvt\-unicode) +Rewrote screen display and text selection routines. +.Sp +Project Coordinator (changes.txt 2.4.6 \- rxvt\-unicode) .IP "Marc Alexander Lehmann " 4 .IX Item "Marc Alexander Lehmann " -Forked rxvt\-unicode, rewrote most of the display code and internal -character handling to store text in unicode, improve xterm -compatibility and apply numerous other bugfixes and extensions. +Forked rxvt\-unicode, unicode support, rewrote almost all the code, perl +extension, random hacks, numerous bugfixes and extensions. .Sp Project Coordinator (Changes 1.0 \-) +.IP "Emanuele Giaquinta " 4 +.IX Item "Emanuele Giaquinta " +Pty/tty/utmp/wtmp rewrite, lots of random hacking and bugfixing.