--- rxvt-unicode/doc/rxvt.1.txt 2007/02/17 20:36:36 1.65 +++ rxvt-unicode/doc/rxvt.1.txt 2007/11/23 13:11:31 1.71 @@ -6,7 +6,7 @@ rxvt [options] [-e command [ args ]] DESCRIPTION - rxvt-unicode, version 8.2, is a colour vt102 terminal emulator intended + rxvt-unicode, version 8.6, is a colour vt102 terminal emulator intended as an *xterm*(1) replacement for users who do not require features such as Tektronix 4014 emulation and toolkit-style configurability. As a result, rxvt-unicode uses much less swap space -- a significant @@ -24,7 +24,7 @@ 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 + rules, 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: rxvt-unicode adopts the view that bidirectional @@ -97,15 +97,24 @@ Turn on/off simulated reverse video; resource reverseVideo. -j|+j - Turn on/off jump scrolling; resource jumpScroll. + Turn on/off jump scrolling (allow multiple lines per refresh); + resource jumpScroll. - -ip|+ip | -tr|+tr - Turn on/off inheriting parent window's pixmap. Alternative form is - -tr; resource inheritPixmap. + -ss|+ss + Turn on/off skip scrolling (allow multiple screens per refresh); + resource skipScroll. + + -tr|+tr + Turn on/off illusion of a transparent window background. Obsolete + form of it is -ip and it should not be used anymore; resource + transparent. + + *Please note that old resource name of inheritPixmap is obsolete and + should be changed to transparent. Backwards compatibility support + for inheritPixmap will be phased out in future versions of rxvt!* - *Please note that transparency of any kind if completely unsupported - by the author. Don't bug him with installation questions! Read the - FAQ (man 7 rxvt)!* + *Please address all transparency related issues to Sasha Vasko at + sasha@aftercode.net. Read the FAQ (man 7 rxvt)!* -fade *number* Fade the text by the given percentage when focus is lost. Small @@ -118,16 +127,37 @@ -tint *colour* Tint the transparent background pixmap with the given colour when - transparency is enabled with -tr or -ip. This only works for - non-tiled backgrounds, currently. See also the -sh option that can - be used to brighten or darken the image in addition to tinting it; - resource *tintColor*. Example: + transparency is enabled with -tr. This only works for non-tiled + backgrounds, currently. See also the -sh option that can be 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 *tintColor*. Example: rxvt -tr -tint blue -sh 40 - -sh *number* Darken (0 .. 100) or lighten (-1 .. -100) the transparent - background image in addition to tinting it (i.e. -tint must be - specified, too, e.g. "-tint white"); resource *shading*. + -sh *number* + Darken (0 .. 100) or lighten (100 .. 200) the transparent background + image in addition to (or instead of) tinting it; resource *shading*. + + -blt *string* + 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 : + add, alphablend, allanon - color values averaging, colorize, darken, + diff, dissipate, hue, lighten, overlay, saturate, screen, sub, tint, + value. The default is alpha-blending. Compile *afterimage*; resource + *blendType*. + + -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 + *afterimage*; resource *blurRadius*. -bg *colour* Window background colour; resource background. @@ -135,11 +165,11 @@ -fg *colour* Window foreground colour; resource foreground. - -pixmap *file[;geom]* - Compile *XPM*: Specify XPM file for the background and also + -pixmap *file[;geom[:op1][:op2][...]]* + Compile *afterimage*: 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 ";" - in the command-line; resource backgroundPixmap. + in the command-line; for more details see resource backgroundPixmap. -cr *colour* The cursor colour; resource cursorColor. @@ -275,7 +305,7 @@ -lsp *number* Compile *frills*: Lines (pixel height) to insert between each row of the display. Useful to work around font rendering problems; resource - linespace. + lineSpace. -tn *termname* This option specifies the name of the terminal type to be set in the @@ -329,7 +359,8 @@ -tcw Change the meaning of triple-click selection with the left mouse - button. Instead of selecting a full line it will extend the + 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 tripleclickwords. @@ -356,6 +387,19 @@ it exits. Instead, it will wait till it is being killed or closed by the user; resource hold. + -xrm *string* + Works like the X Toolkit option of the same name, by adding the + *string* as if it were specified in a resource file. Resource values + specified this way take precedence over all other resource + specifications. + + Note that you need to use the *same* syntax as in the .Xdefaults + file, e.g. "*.background: black". Also note that all rxvt-specific + options can be specified as long-options on the commandline, so use + of -xrm is mostly limited to cases where you want to specify other + resources (e.g. for input methods) or for compatibility with other + programs. + -keysym.*sym* *string* Remap a key symbol. See resource keysym. @@ -431,6 +475,7 @@ 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 Note that when reading X resources, rxvt recognizes two class names: Rxvt and URxvt. The class name Rxvt allows resources common to both rxvt @@ -507,9 +552,24 @@ note in COLORS AND GRAPHICS section. jumpScroll: *boolean* - True: specify that jump scrolling should be used. When scrolling - quickly, fewer screen updates are performed [default]; option -j. - False: specify that smooth scrolling should be used; option +j. + True: specify that jump scrolling should be used. When receiving + lots of lines, rxvt will only scroll once a whole screen height of + lines has been read, resulting in fewer updates while still + displaying every received line; option -j. + + False: specify that smooth scrolling should be used. rxvt will force + a screen refresh on each new line it received; option +j. + + skipScroll: *boolean* + True: (the default) specify that skip scrolling should be used. When + receiving lots of lines, rxvt will only scroll once in a while + (around 60 times per second), resulting in far fewer updates. This + can result in rxvt not ever displaying some of the lines it + receives; option -ss. + + False: 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 +ss. inheritPixmap: *boolean* True: make the background inherit the parent windows' pixmap, giving @@ -535,6 +595,13 @@ Darken (0 .. 100) or lighten (-1 .. -100) the transparent background image in addition to tinting it; option -sh. + blendType: *string* + Specify background blending type; option -blt. + + blurRadius: *number* + Apply Gaussian Blurr with the specified radius to the transparent + background image; option -blr. + scrollColor: *colour* Use the specified colour for the scrollbar [default #B2B2B2]. @@ -546,19 +613,34 @@ The colour of the border around the text area and between the scrollbar and the text. - backgroundPixmap: *file[;geom]* - Use the specified XPM file (note the `.xpm' extension is optional) - for the background and also optionally specify its scaling with a - geometry string WxH+X+Y, in which "W" / "H" specify the - horizontal/vertical scale (percent) and "X" / "Y" 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. [default 0x0+50+50] + backgroundPixmap: *file[;geom[:op1][:op2][...]]* + Use the specified image file for the background and also optionally + specify its scaling with a geometry string WxH+X+Y, (default + "0x0+50+50") in which "W" / "H" specify the horizontal/vertical + scale (percent), and "X" / "Y" 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 + :op1:op2.... Supported operations are: + + 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. + + If used in conjunction with -tr option, the specified pixmap will be + blended over transparency image using either alpha-blending, or any + other blending type, specified with -blt "type" option. path: *path* - Specify the colon-delimited search path for finding XPM files. + Specify the colon-delimited search path for finding background image + files. font: *fontlist* Select the fonts to be used. This is a comma separated list of font @@ -632,7 +714,8 @@ selectstyle: *mode* Set mouse selection style to old which is 2.20, oldword which is xterm style with 2.20 old word selection, or anything else which - gives xterm style selection. + gives xterm style selection. Only effective when the original + (non-perl) selection code is in use. scrollstyle: *mode* Set scrollbar style to rxvt, plain, next or xterm. plain is the @@ -652,6 +735,10 @@ True: de-iconify (map) on receipt of a bell character. False: no de-iconify (map) on receipt of a bell character [default]. + urgentOnBell: *boolean* + True: set the urgency hint for the wm on receipt of a bell + character. False: do not set the urgency hint [default]. + visualBell: *boolean* True: use visual bell on receipt of a bell character; option -vb. False: no visual bell [default]; option +vb. @@ -738,7 +825,7 @@ Specifies the terminal type name to be set in the TERM environment variable; option -tn. - linespace: *number* + lineSpace: *number* Specifies number of lines (pixel height) to insert between each row of the display [default 0]; option -lsp. @@ -789,8 +876,8 @@ The characters used as delimiters for double-click word selection (whitespace delimiting is added automatically if resource is given). - When the selection extension is in use (the default if compiled in, - see the rxvtperl(3) manpage), a suitable regex using these + When the perl selection extension is in use (the default if compiled + in, see the rxvtperl(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 ISO-8859-1 can be used. @@ -798,7 +885,7 @@ When the selection extension is not used, only ISO-8859-1 characters can be used. If not specified, the built-in default is used: - BACKSLASH `"'&()*,;<=>?@[]{|} + BACKSLASH `"'&()*,;<=>?@[]^{|} preeditType: *style* OverTheSpot, OffTheSpot, Root; option -pt. @@ -852,7 +939,7 @@ Turn on/off secondary screen (default enabled). secondaryScroll: *boolean* - Turn on/off secondary screen scroll (default enabled). If the this + Turn on/off secondary screen scroll (default enabled). If 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. @@ -884,17 +971,8 @@ is not performed in an exact manner; however, the closest match is assured. - *string* may contain escape values ("\a": bell, "\b": backspace, - "\e", "\E": escape, "\n": newline, "\r": carriage return, "\t": tab, - "\000": octal number) or verbatim control characters ("^?": delete, - "^@": null, "^A" ...) and may be enclosed with double quotes so that - it can start or end with whitespace. This feature is deprecated and - will be removed. - - Please note that you need to double the "\" in resource files, as - Xlib itself does its own de-escaping (you can use "\033" instead of - "\e" (and so on), which will work with both Xt and rxvt's own - processing). + *string* may contain escape values ("\n": newline, "\000": octal + number), see RESOURCES in "man 7 X" for futher details. You can define a range of keysyms in one shot by providing a *string* with pattern list/PREFIX/MIDDLE/SUFFIX, where the delimiter @@ -1021,6 +1099,9 @@ making it almost invisible to window managers; option -override-redirect. + iso14755_52: *boolean* + Turn on/off ISO 14755 5.2 mode (default enabled). + THE SCROLLBAR Lines of text that scroll off the top of the rxvt window (resource: saveLines) and can be scrolled back using the scrollbar or by @@ -1043,11 +1124,11 @@ (Next) and ESC [ 5 ~ (Prior), respectively. Similarly, clicking on the up and down arrows sends ESC [ A (Up) and ESC [ B (Down), respectively. -TEXT SELECTION AND INSERTION - The behaviour of text selection and insertion mechanism is similar to - *xterm*(1). +THE SELECTION: SELECTING AND PASTING TEXT + The behaviour of text selection and insertion/pasting mechanism is + similar to *xterm*(1). - Selection: + Selecting: Left click at the beginning of the region, drag to the end of the region and release; Right click to extend the marked region; Left double-click to select a word; Left triple-click to select the @@ -1060,7 +1141,7 @@ the selection, and trailing whitespace is visually underlined and removed from the selection. - Insertion: + Pasting: Pressing and releasing the Middle mouse button in an rxvt window causes the value of the PRIMARY selection (or CLIPBOARD with the Meta modifier) to be inserted as if it had been typed on the @@ -1088,9 +1169,9 @@ ISO 14755 SUPPORT ISO 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 "--enable-frills", - the rest is available when rxvt-unicode was compiled with - "--enable-iso14755". + part is available if rxvt-unicode has been compiled with + "--enable-frills", the rest is available when rxvt-unicode was compiled + with "--enable-iso14755". * 5.1: Basic method This allows you to enter unicode characters using their hexcode. @@ -1229,8 +1310,9 @@ COLORTERM Either "rxvt", "rxvt-xpm", depending on whether rxvt was compiled - with XPM support, and optionally with the added extension "-mono" to - indicate that rxvt-unicode runs on a monochrome screen. + with background image support, and optionally with the added + extension "-mono" to indicate that rxvt-unicode runs on a monochrome + screen. COLORFGBG Set to a string of the form "fg;bg" or "fg;xpm;bg", where "fg" is @@ -1238,8 +1320,9 @@ string "default" to indicate that the default-colour escape sequence is to be used), "bg" is the colour code used as default background colour (or the string "default"), and "xpm" is the string "default" - if rxvt was compiled with XPM support. Libraries like "ncurses" and - "slang" can (and do) use this information to optimize screen output. + if rxvt was compiled with background image support. Libraries like + "ncurses" and "slang" can (and do) use this information to optimize + screen output. WINDOWID Set to the (decimal) X Window ID of the rxvt window (the toplevel