--- rxvt-unicode/doc/rxvt.1.man.in 2007/06/24 22:12:18 1.68 +++ rxvt-unicode/doc/rxvt.1.man.in 2007/12/15 19:10:11 1.76 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 +.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.35 .\" .\" Standard preamble: .\" ======================================================================== @@ -129,7 +129,7 @@ .\" ======================================================================== .\" .IX Title "@@RXVT_NAME@@ 1" -.TH @@RXVT_NAME@@ 1 "2007-06-25" "8.2" "RXVT-UNICODE" +.TH @@RXVT_NAME@@ 1 "2007-12-15" "8.7" "RXVT-UNICODE" .SH "NAME" rxvt\-unicode (ouR XVT, unicode) \- (a VT102 emulator for the X window system) .SH "SYNOPSIS" @@ -142,12 +142,15 @@ require features such as Tektronix 4014 emulation and toolkit-style configurability. As a result, \fBrxvt-unicode\fR uses much less swap space \*(-- a significant advantage on a machine serving many X sessions. +.PP +This document is also available on the World-Wide-Web at +. .SH "FREQUENTLY ASKED QUESTIONS" .IX Header "FREQUENTLY ASKED QUESTIONS" See @@RXVT_NAME@@(7) (try \f(CW\*(C`man 7 @@RXVT_NAME@@\*(C'\fR) for a list of frequently asked questions and answer to them and some common problems. That document is also accessible on the World-Wide-Web at -. +. .SH "RXVT-UNICODE VS. RXVT" .IX Header "RXVT-UNICODE VS. RXVT" Unlike the original rxvt, \fBrxvt-unicode\fR stores all text in Unicode @@ -155,11 +158,11 @@ world. Being a terminal emulator, however, some things are very difficult, especially cursive scripts such as arabic, vertically written scripts like mongolian or scripts requiring extremely complex combining rules, -like tibetan or devenagari. Don't expect pretty output when using these +like tibetan or devanagari. Don't expect pretty output when using these scripts. Most other scripts, latin, cyrillic, kanji, thai etc. should work fine, though. A somewhat difficult case are right-to-left scripts, such as hebrew: \fBrxvt-unicode\fR adopts the view that bidirectional algorithms -belong into the application, not the terminal emulator (too many things \*(-- +belong in the application, not the terminal emulator (too many things \*(-- such as cursor-movement while editing \*(-- break otherwise), but that might change. .PP @@ -232,14 +235,15 @@ .IP "\fB\-ss\fR|\fB+ss\fR" 4 .IX Item "-ss|+ss" Turn on/off skip scrolling (allow multiple screens per refresh); resource \fBskipScroll\fR. -.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\-tr\fR|\fB+tr\fR" 4 +.IX Item "-tr|+tr" +Turn on/off illusion of a transparent window background; resource \fBtransparent\fR. .Sp -\&\fIPlease note that transparency of any kind if completely unsupported by -the author. Don't bug him with installation questions! Read the \s-1FAQ\s0 (man 7 -@@RXVT_NAME@@)!\fR +\&\fB\-ip\fR is still accepted as an obsolete alias but will be removed in +future versions. +.Sp +\&\fIPlease address all transparency related issues to Sasha Vasko at +sasha@aftercode.net. Read the \s-1FAQ\s0 (man 7 @@RXVT_NAME@@)!\fR .IP "\fB\-fade\fR \fInumber\fR" 4 .IX Item "-fade number" Fade the text by the given percentage when focus is lost. Small values @@ -252,9 +256,13 @@ .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. This only works for +transparency is enabled with \fB\-tr\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 +used to brighten or darken the image in addition to tinting it. +Please note that certain tint colours can be applied on the server\-side, +thus yielding performance gain of two orders of magnitude. These colours are: +blue, red, green, cyan, magenta, yellow, and those close to them. Also +pure black and pure white colors essentially mean no tinting; resource \&\fItintColor\fR. Example: .Sp .Vb 1 @@ -262,31 +270,35 @@ .Ve .IP "\fB\-sh\fR \fInumber\fR" 4 .IX Item "-sh number" -Darken (0 .. 100) or lighten (\-1 .. \-100) the transparent -background image in addition to (or instead of) tinting it; +Darken (0 .. 100) or lighten (100 .. 200) the transparent +background image in addition to (or instead of) tinting it; resource \fIshading\fR. .IP "\fB\-blt\fR \fIstring\fR" 4 .IX Item "-blt string" -Specify background blending type. If background pixmap is specified -at the same time as transparency \- such pixmap will be blended over +Specify background blending type. If background pixmap is specified +at the same time as transparency \- such pixmap will be blended over transparency image, using method specified. Supported values are : -\&\fBadd\fR, \fBalphablend\fR, \fBallanon\fR \- color values averaging, \fBcolorize\fR, -\&\fBdarken\fR, \fBdiff\fR, \fBdissipate\fR, \fBhue\fR, \fBlighten\fR, \fBoverlay\fR, -\&\fBsaturate\fR, \fBscreen\fR, \fBsub\fR, \fBtint\fR, \fBvalue\fR. The default is -alpha\-blending; resource \fIblendType\fR. -.IP "\fB\-blr\fR \fInumber\fR" 4 -.IX Item "-blr number" -Apply Gaussian Blur with the specified radius to the transparent -background image; resource \fIblurRadius\fR. +\&\fBadd\fR, \fBalphablend\fR, \fBallanon\fR \- color values averaging, \fBcolorize\fR, +\&\fBdarken\fR, \fBdiff\fR, \fBdissipate\fR, \fBhue\fR, \fBlighten\fR, \fBoverlay\fR, +\&\fBsaturate\fR, \fBscreen\fR, \fBsub\fR, \fBtint\fR, \fBvalue\fR. The default is +alpha\-blending. Compile \fIafterimage\fR; resource \fIblendType\fR. +.IP "\fB\-blr\fR \fIHxV\fR" 4 +.IX Item "-blr HxV" +Apply Gaussian Blur with the specified radii to the transparent +background image. If single number is specified \- both vertical and +horizontal radii are considered to be the same. Setting one of the +radii to 1 and another to a large number creates interesting effects +on some backgrounds. Maximum radius value is 128. Compile \fIafterimage\fR; +resource \fIblurRadius\fR. .IP "\fB\-bg\fR \fIcolour\fR" 4 .IX Item "-bg colour" Window background colour; resource \fBbackground\fR. .IP "\fB\-fg\fR \fIcolour\fR" 4 .IX Item "-fg colour" Window foreground colour; resource \fBforeground\fR. -.IP "\fB\-pixmap\fR \fIfile[;geom]\fR" 4 -.IX Item "-pixmap file[;geom]" -Compile \fIafterimage\fR: Specify image file for the background and also +.IP "\fB\-pixmap\fR \fIfile[;geom[:op1][:op2][...]]\fR" 4 +.IX Item "-pixmap file[;geom[:op1][:op2][...]]" +Compile \fIafterimage\fR: Specify image file for the background and also optionally specify its scaling with a geometry string. Note you may need to add quotes to avoid special shell interpretation of the \f(CW\*(C`;\*(C'\fR in the command\-line; for more details see resource \fBbackgroundPixmap\fR. @@ -337,7 +349,7 @@ 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 +Compile \fIfont-styles\fR: Bold/Blink font styles imply high intensity foreground/background (default). See resource \fBintensityStyles\fR for details. .IP "\fB\-name\fR \fIname\fR" 4 @@ -425,7 +437,7 @@ .IX Item "-lsp number" Compile \fIfrills\fR: Lines (pixel height) to insert between each row of the display. Useful to work around font rendering problems; resource -\&\fBlinespace\fR. +\&\fBlineSpace\fR. .IP "\fB\-tn\fR \fItermname\fR" 4 .IX Item "-tn termname" This option specifies the name of the terminal type to be set in the @@ -482,8 +494,8 @@ .IX Item "-tcw" Change the meaning of triple-click selection with the left mouse button. Only effective when the original (non\-perl) selection code is -in\-use. Instead of selecting a full line it will extend the selection the -end of the logical line only. resource \fBtripleclickwords\fR. +in\-use. Instead of selecting a full line it will extend the selection to +the end of the logical line only. resource \fBtripleclickwords\fR. .IP "\fB\-insecure\fR" 4 .IX Item "-insecure" Enable \*(L"insecure\*(R" mode, which currently enables most of the escape @@ -508,6 +520,18 @@ 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\-xrm\fR \fIstring\fR" 4 +.IX Item "-xrm string" +Works like the X Toolkit option of the same name, by adding the \fIstring\fR +as if it were specified in a resource file. Resource values specified this +way take precedence over all other resource specifications. +.Sp +Note that you need to use the \fIsame\fR syntax as in the .Xdefaults file, +e.g. \f(CW\*(C`*.background: black\*(C'\fR. Also note that all @@RXVT_NAME@@\-specific +options can be specified as long-options on the commandline, so use +of \fB\-xrm\fR is mostly limited to cases where you want to specify other +resources (e.g. for input methods) or for compatibility with other +programs. .IP "\fB\-keysym.\fR\fIsym\fR \fIstring\fR" 4 .IX Item "-keysym.sym string" Remap a key symbol. See resource \fBkeysym\fR. @@ -551,7 +575,8 @@ yourself if you want that. .Sp As an extremely special case, specifying \f(CW\*(C`\-1\*(C'\fR will completely suppress -pty/tty operations. +pty/tty operations, which is probably only useful in conjunction with some +perl extension that manages the terminal. .Sp Here is a example in perl that illustrates how this option can be used (a longer example is in \fIdoc/pty\-fd\fR): @@ -577,22 +602,24 @@ .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)" +.SH "RESOURCES" +.IX Header "RESOURCES" Note: `@@RXVT_NAME@@ \-\-help' gives a list of all resources (long -options) compiled into your version. +options) compiled into your version. All resources are also available as +long\-options. .PP 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 +.Vb 6 \& 1. system-wide app-defaults file, either locale-dependent OR global \& 2. app-defaults file in $XAPPLRESDIR \& 3. RESOURCE_MANAGER property on root-window OR $HOME/.Xdefaults \& 4. SCREEN_RESOURCES for the current screen \& 5. $XENVIRONMENT file OR $HOME/.Xdefaults- +\& 6. resources specified via -xrm on the commandline .Ve .PP Note that when reading X resources, \fB@@RXVT_NAME@@\fR recognizes two class @@ -690,14 +717,15 @@ \&\fBFalse\fR: specify that everything is to be displayed, even if the refresh is too fast for the human eye to read anything (or the monitor to display anything); option \fB+ss\fR. -.IP "\fBinheritPixmap:\fR \fIboolean\fR" 4 -.IX Item "inheritPixmap: boolean" -\&\fBTrue\fR: make the background inherit the parent windows' pixmap, giving -artificial transparency. \fBFalse\fR: do not inherit the parent windows' -pixmap. +.IP "\fBtransparent:\fR \fIboolean\fR" 4 +.IX Item "transparent: boolean" +Turn on/off illusion of a transparent window background. .Sp -\&\fIPlease note that transparency of any kind if completely unsupported by -the author. Don't bug him with installation questions!\fR +\&\fBinheritPixmap\fR is still accepted as an obsolete alias but will be removed in +future versions. +.Sp +\&\fIPlease address all transparency related issues to Sasha Vasko at +sasha@aftercode.net. Read the \s-1FAQ\s0 (man 7 @@RXVT_NAME@@)!\fR .IP "\fBfading:\fR \fInumber\fR" 4 .IX Item "fading: number" Fade the text by the given percentage when focus is lost; option \fB\-fade\fR. @@ -718,7 +746,7 @@ Specify background blending type; option \fB\-blt\fR. .IP "\fBblurRadius:\fR \fInumber\fR" 4 .IX Item "blurRadius: number" -Apply Gaussian Blurr with the specified radius to the transparent +Apply Gaussian Blurr with the specified radius to the transparent background image; option \fB\-blr\fR. .IP "\fBscrollColor:\fR \fIcolour\fR" 4 .IX Item "scrollColor: colour" @@ -731,25 +759,36 @@ .IX Item "borderColor: colour" The colour of the border around the text area and between the scrollbar and the text. -.IP "\fBbackgroundPixmap:\fR \fIfile[;geom]\fR" 4 -.IX Item "backgroundPixmap: file[;geom]" -Use the specified image file for the background and also optionally -specify its scaling with a geometry string \fBWxH+X+Y\fR, -in which \fB\*(L"W\*(R" / \*(L"H\*(R"\fR specify the horizontal/vertical scale (percent), -and \fB\*(L"X\*(R" / \*(L"Y\*(R"\fR locate the image centre (percent). -A scale of 0 displays the image with tiling. A scale of 1 displays the -image without any scaling. A scale of 2 to 9 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. -Special string of \fB\*(L"auto\*(R"\fR used as a geometry will cause image to be -automatically scaled to match window size. -If used in conjunction with \fB\-tr\fR option \- specified pixmap will be -blended over transparency image using either alpha\-blending, or any +.IP "\fBbackgroundPixmap:\fR \fIfile[;geom[:op1][:op2][...]]\fR" 4 +.IX Item "backgroundPixmap: file[;geom[:op1][:op2][...]]" +Use the specified image file for the background and also +optionally specify its scaling with a geometry string \fBWxH+X+Y\fR, +(default \f(CW\*(C`0x0+50+50\*(C'\fR) in which \fB\*(L"W\*(R" / \*(L"H\*(R"\fR specify the +horizontal/vertical scale (percent), and \fB\*(L"X\*(R" / \*(L"Y\*(R"\fR locate the image +centre (percent). A scale of 0 displays the image with tiling. A scale +of 1 displays the image without any scaling. A scale of 2 to 9 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. +Additional operations can be specified after colon \fB:op1:op2...\fR. +Supported operations are: +.Sp +.Vb 8 +\& tile force background image to be tiled and not scaled. Equivalent to 0x0, +\& propscale will scale image keeping proportions, +\& auto will scale image to match window size. Equivalent to 100x100; +\& hscale will scale image horizontally to the window size; +\& vscale will scale image vertically to the window size; +\& scale will scale image to match window size; +\& root will tile image as if it was a root window background, auto-adjusting +\& whenever terminal window moves. +.Ve +.Sp +If used in conjunction with \fB\-tr\fR option, the specified pixmap will be +blended over transparency image using either alpha\-blending, or any other blending type, specified with \fB\-blt \*(L"type\*(R"\fR option. -[default 0x0+50+50] .IP "\fBpath:\fR \fIpath\fR" 4 .IX Item "path: path" -Specify the colon-delimited search path for finding \s-1XPM\s0 files. +Specify the colon-delimited search path for finding background image 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 @@ -817,7 +856,7 @@ .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 +option \fB\-is\fR, the default), bold/blink font styles imply high intensity foreground/background colours. Disabling this option (\fBFalse\fR, option \fB+is\fR) disables this behaviour, the high intensity colours are not reachable. @@ -937,8 +976,8 @@ .IX Item "termName: termname" Specifies the terminal type name to be set in the \fB\s-1TERM\s0\fR environment variable; option \fB\-tn\fR. -.IP "\fBlinespace:\fR \fInumber\fR" 4 -.IX Item "linespace: number" +.IP "\fBlineSpace:\fR \fInumber\fR" 4 +.IX Item "lineSpace: number" Specifies number of lines (pixel height) to insert between each row of the display [default 0]; option \fB\-lsp\fR. .IP "\fBmeta8:\fR \fIboolean\fR" 4 @@ -996,7 +1035,7 @@ 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 +\&\fB\s-1BACKSLASH\s0 `"'&()*,;<=>?@[]^{|}\fR .IP "\fBpreeditType:\fR \fIstyle\fR" 4 .IX Item "preeditType: style" \&\fBOverTheSpot\fR, \fBOffTheSpot\fR, \fBRoot\fR; option \fB\-pt\fR. @@ -1082,17 +1121,8 @@ keysym value (\fB0x0000 \- 0xFFFF\fR). Note that the lookup of \fIsym\fRs is not performed in an exact manner; however, the closest match is assured. .Sp -\&\fIstring\fR may contain escape values (\f(CW\*(C`\ea\*(C'\fR: bell, \f(CW\*(C`\eb\*(C'\fR: backspace, -\&\f(CW\*(C`\ee\*(C'\fR, \f(CW\*(C`\eE\*(C'\fR: escape, \f(CW\*(C`\en\*(C'\fR: newline, \f(CW\*(C`\er\*(C'\fR: carriage return, \f(CW\*(C`\et\*(C'\fR: tab, -\&\f(CW\*(C`\e000\*(C'\fR: octal number) or verbatim control characters (\f(CW\*(C`^?\*(C'\fR: delete, -\&\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. \fBThis feature is deprecated and will -be removed\fR. -.Sp -Please note that you need to double the \f(CW\*(C`\e\*(C'\fR in resource files, as -Xlib itself does its 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). +\&\fIstring\fR may contain escape values (\f(CW\*(C`\en\*(C'\fR: newline, \f(CW\*(C`\e000\*(C'\fR: octal +number), see \s-1RESOURCES\s0 in \f(CW\*(C`man 7 X\*(C'\fR for futher details. .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 delimiter `/' @@ -1306,7 +1336,7 @@ .IX Header "ISO 14755 SUPPORT" \&\s-1ISO\s0 14755 is a standard for entering and viewing unicode characters and character codes using the keyboard. It consists of 4 parts. The -first part is available rxvt-unicode has been compiled with +first part is available if rxvt-unicode has been compiled with \&\f(CW\*(C`\-\-enable\-frills\*(C'\fR, the rest is available when rxvt-unicode was compiled with \f(CW\*(C`\-\-enable\-iso14755\*(C'\fR. .IP "* 5.1: Basic method" 4 @@ -1450,8 +1480,9 @@ .IP "\fB\s-1COLORTERM\s0\fR" 4 .IX Item "COLORTERM" Either \f(CW\*(C`rxvt\*(C'\fR, \f(CW\*(C`rxvt\-xpm\*(C'\fR, depending on whether @@RXVT_NAME@@ was -compiled with \s-1XPM\s0 support, and optionally with the added extension -\&\f(CW\*(C`\-mono\*(C'\fR to indicate that rxvt-unicode runs on a monochrome screen. +compiled with background image support, and optionally with the added +extension \f(CW\*(C`\-mono\*(C'\fR to indicate that rxvt-unicode runs on a monochrome +screen. .IP "\fB\s-1COLORFGBG\s0\fR" 4 .IX Item "COLORFGBG" Set to a string of the form \f(CW\*(C`fg;bg\*(C'\fR or \f(CW\*(C`fg;xpm;bg\*(C'\fR, where \f(CW\*(C`fg\*(C'\fR is @@ -1459,8 +1490,8 @@ \&\f(CW\*(C`default\*(C'\fR to indicate that the default-colour escape sequence is to be used), \f(CW\*(C`bg\*(C'\fR is the colour code used as default background colour (or the string \f(CW\*(C`default\*(C'\fR), and \f(CW\*(C`xpm\*(C'\fR is the string \f(CW\*(C`default\*(C'\fR if @@RXVT_NAME@@ -was compiled with \s-1XPM\s0 support. Libraries like \f(CW\*(C`ncurses\*(C'\fR and \f(CW\*(C`slang\*(C'\fR can -(and do) use this information to optimize screen output. +was compiled with background image support. Libraries like \f(CW\*(C`ncurses\*(C'\fR +and \f(CW\*(C`slang\*(C'\fR can (and do) use this information to optimize screen output. .IP "\fB\s-1WINDOWID\s0\fR" 4 .IX Item "WINDOWID" Set to the (decimal) X Window \s-1ID\s0 of the @@RXVT_NAME@@ window (the toplevel