--- rxvt-unicode/doc/rxvt.1.pod 2007/11/23 11:18:04 1.147 +++ rxvt-unicode/doc/rxvt.1.pod 2010/12/18 12:20:18 1.192 @@ -14,12 +14,15 @@ configurability. As a result, B uses much less swap space -- a significant advantage on a machine serving many X sessions. +This document is also available on the World-Wide-Web at +L. + =head1 FREQUENTLY ASKED QUESTIONS See @@RXVT_NAME@@(7) (try C) 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 -L. +L. =head1 RXVT-UNICODE VS. RXVT @@ -32,7 +35,7 @@ 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: B 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. @@ -91,15 +94,20 @@ =item B<-display> I -Attempt to open a window on the named X display (B<-d> still -respected). In the absence of this option, the display specified by the -B environment variable is used. +Attempt to open a window on the named X display (the older form B<-d> +is still respected. but deprecated). In the absence of this option, the +display specified by the B environment variable is used. =item B<-depth> I Compile I: Attempt to find a visual with the given bit depth; resource B. +[Please note that many X servers (and libXft) are buggy with +respect to C<-depth 32> and/or alpha channels, and will cause all sorts +of graphical corruption. This is harmless, but we can't do anything about +this, so watch out] + =item B<-geometry> I Window geometry (B<-g> still respected); resource B. @@ -118,15 +126,10 @@ =item B<-tr>|B<+tr> -Turn on/off illusion of a transparent window background. Obsolete form of it is -B<-ip> and it should not be used anymore; resource B. - -I is obsolete and should be -changed to B. Backwards compatibility support for B will -be phased out in future versions of rxvt!> +Turn on/off pseudo-transparency by using the root pixmap as background; resource B. -I +B<-ip> is still accepted as an obsolete alias but will be removed in +future versions. =item B<-fade> I @@ -141,30 +144,20 @@ =item B<-tint> I -Tint the transparent background pixmap with the given colour when -transparency is enabled with B<-tr>. This only works for -non-tiled backgrounds, currently. See also the B<-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 -I. Example: - - @@RXVT_NAME@@ -tr -tint blue -sh 40 +Tint the transparent background with the given colour; +resource I. =item B<-sh> I -Darken (0 .. 100) or lighten (100 .. 200) the transparent -background image in addition to (or instead of) tinting it; -resource I. +Darken (0 .. 99) or lighten (101 .. 200) the transparent background. +A value of 100 means no shading; resource I. =item B<-blt> I 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 : -B, B, B - color values averaging, B, +the transparent background, using the method specified. Supported values are: +B, B, B - colour values averaging, B, B, B, B, B, B, B, B, B, B, B, B. The default is alpha-blending. Compile I; resource I. @@ -172,12 +165,18 @@ =item B<-blr> I Apply Gaussian Blur with the specified radii to the transparent -background image. If single number is specified - both vertical and +background. If a 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 I; +on some backgrounds. Maximum radius value is 128; resource I. +=item B<-icon> I + +Compile I or I: Use the specified image as application icon. This +is used by many window managers, taskbars and pagers to represent the +application window; resource I. + =item B<-bg> I Window background colour; resource B. @@ -188,7 +187,7 @@ =item B<-pixmap> I -Compile I: Specify image file for the background and also +Compile I or I: 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 C<;> in the command-line; for more details see resource B. @@ -246,7 +245,7 @@ =item B<-is>|B<+is> -Compile I: Bold/Italic font styles imply high intensity +Compile I: Bold/Blink font styles imply high intensity foreground/background (default). See resource B for details. @@ -274,6 +273,15 @@ Turn on/off scrollbar; resource B. +=item B<-sr>|B<+sr> + +Put scrollbar on right/left; resource B. + +=item B<-st>|B<+st> + +Display rxvt (non XTerm/NeXT) scrollbar without/with a trough; +resource B. + =item B<-si>|B<+si> Turn on/off scroll-to-bottom on TTY output inhibit; resource @@ -290,15 +298,6 @@ This only takes effect if B<-si> is also given; resource B. -=item B<-sr>|B<+sr> - -Put scrollbar on right/left; resource B. - -=item B<-st>|B<+st> - -Display rxvt (non XTerm/NeXT) scrollbar without/with a trough; -resource B. - =item B<-ptab>|B<+ptab> If enabled (default), "Horizontal Tab" characters are being stored as @@ -311,6 +310,10 @@ Blink the cursor; resource B. +=item B<-uc>|B<+uc> + +Make the cursor underlined; resource B. + =item B<-iconic> Start iconified, if the window manager supports that option. @@ -336,7 +339,8 @@ Compile I: Set MWM hints to request a borderless window, i.e. if honoured by the WM, the rxvt-unicode window will not have window -decorations; resource B. +decorations; resource B. If the window manager does not +support MWM hints (e.g. kwin), enables override-redirect mode. =item B<-override-redirect> @@ -356,6 +360,13 @@ the display. Useful to work around font rendering problems; resource B. +=item B<-letsp> I + +Compile I: Amount to adjust the computed character width by +to control overall letter spacing. Negative values will tighten up the +letter spacing, positive values will space letters out more. Useful to +work around odd font metrics; resource B. + =item B<-tn> I This option specifies the name of the terminal type to be set in the @@ -419,8 +430,8 @@ 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 B. +in-use. Instead of selecting a full line it will extend the selection to +the end of the logical line only. resource B. =item B<-insecure> @@ -451,6 +462,12 @@ it exits. Instead, it will wait till it is being killed or closed by the user; resource B. +=item B<-cd> I + +Sets the working directory for the shell (or the command specified via +B<-e>). The I must be an absolute path and it must exist for +@@RXVT_NAME@@ to start; resource B. + =item B<-xrm> I Works like the X Toolkit option of the same name, by adding the I @@ -507,7 +524,8 @@ yourself if you want that. As an extremely special case, specifying C<-1> will completely suppress -pty/tty operations. +pty/tty operations, which is probably only useful in conjunction with some +perl extension that manages the terminal. Here is a example in perl that illustrates how this option can be used (a longer example is in F): @@ -531,10 +549,11 @@ =back -=head1 RESOURCES (available also as long-options) +=head1 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. You can set and change the resources using X11 tools like B. Many distribution do also load settings from the B<~/.Xresources> file when X @@ -566,6 +585,13 @@ Compile I: Attempt to find a visual with the given bit depth; option B<-depth>. +=item B I + +Compile I: Turn on/off double-buffering for xft (default enabled). +On some card/driver combination enabling it slightly decreases +performance, on most it greatly helps it. The slowdown is small, so it +should normally be enabled. + =item B I Create the window with the specified X window geometry [default 80x24]; @@ -588,7 +614,7 @@ high-intensity (bold = bright foreground, blink = bright background) colours. The canonical names are as follows: 0=black, 1=red, 2=green, 3=yellow, 4=blue, 5=magenta, 6=cyan, 7=white, but the actual colour -names used are listed in the B section. +names used are listed in the B section. Colours higher than 15 cannot be set using resources (yet), but can be changed using an escape command (see @@RXVT_NAME@@(7)). @@ -609,16 +635,21 @@ Use the specified colour to display underlined characters when the foreground colour is the default. -=item B I - -Use the specified colour as the background for reverse video characters -when OPTION_HC is disabled (--disable-frills). - =item B I If set, use the specified colour as the colour for the underline itself. If unset, use the foreground colour. +=item B I + +If set, use the specified colour as the background for highlighted +characters. If unset, use reverse video. + +=item B I + +If set and highlightColor is set, use the specified colour as the +foreground for highlighted characters. + =item B I Use the specified colour for the cursor. The default is to use the @@ -634,7 +665,7 @@ B: simulate reverse video by foreground and background colours; option B<-rv>. B: regular screen colours [default]; option -B<+rv>. See note in B section. +B<+rv>. See note in B section. =item B I @@ -658,14 +689,12 @@ if the refresh is too fast for the human eye to read anything (or the monitor to display anything); option B<+ss>. -=item B I +=item B I -B: make the background inherit the parent windows' pixmap, giving -artificial transparency. B: do not inherit the parent windows' -pixmap. +Turn on/off pseudo-transparency by using the root pixmap as background. -I +B is still accepted as an obsolete alias but will be removed in +future versions. =item B I @@ -678,13 +707,16 @@ =item B I -Tint the transparent background pixmap with the given colour; option -B<-tint>. +Tint the transparent background with the given colour. If the RENDER +extension is not available only black, red, green, yellow, blue, +magenta, cyan and white tints can be performed server-side. Note that +a black tint yields a completely black image while a white tint yields +the image unchanged; option B<-tint>. =item B I -Darken (0 .. 100) or lighten (-1 .. -100) the transparent background image -in addition to tinting it; option B<-sh>. +Darken (0 .. 99) or lighten (101 .. 200) the transparent background. +A value of 100 means no shading; option B<-sh>. =item B I @@ -692,8 +724,12 @@ =item B I -Apply Gaussian Blurr with the specified radius to the transparent -background image; option B<-blr>. +Apply gaussian blur with the specified radius to the transparent +background; option B<-blr>. + +=item B I + +Set the application icon pixmap; option B<-icon>. =item B I @@ -713,27 +749,26 @@ Use the specified image file for the background and also optionally specify its scaling with a geometry string B, -(default C<0x0+50+50>) in which B<"W" / "H"> specify the +(default C<100x100+50+50>) in which B<"W" / "H"> specify the horizontal/vertical scale (percent), and B<"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. +centre (percent). A scale of 0 displays the image with tiling. +The maximum permitted scale is 1000. Additional operations can be specified after colon B<: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; + 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. + whenever terminal window moves If used in conjunction with B<-tr> option, the specified pixmap will be -blended over transparency image using either alpha-blending, or any -other blending type, specified with B<-blt "type"> option. +blended over the transparent background using alpha-blending. If I +support has been compiled in it is possible to choose other blending +types with B<-blt "type"> option. =item B I @@ -770,7 +805,7 @@ The second font is just used to add additional unicode characters not in the base font, likewise the third, which is unfortunately non-bold, but -the bold version of the font does contain less characters, so this is a +the bold version of the font does contain fewer characters, so this is a useful supplement. The third font is an Xft font with aliasing turned off, and the characters @@ -804,23 +839,11 @@ =item B I When font styles are not enabled, or this option is enabled (B, -option B<-is>, the default), bold and italic font styles imply high +option B<-is>, the default), bold/blink font styles imply high intensity foreground/background colours. Disabling this option (B, option B<+is>) disables this behaviour, the high intensity colours are not reachable. -=item B I - -Set mouse selection style to B which is 2.20, B which -is xterm style with 2.20 old word selection, or anything else which -gives xterm style selection. Only effective when the original (non-perl) -selection code is in use. - -=item B I - -Set scrollbar style to B, B, B or B. B is -the author's favourite. - =item B I Set window title string, the default title is the command-line @@ -843,6 +866,8 @@ B: set the urgency hint for the wm on receipt of a bell character. B: do not set the urgency hint [default]. +@@RXVT_NAME@@ resets the urgency hint on every focus change. + =item B I B: use visual bell on receipt of a bell character; option B<-vb>. @@ -875,6 +900,11 @@ This creates a new file in your home directory with the screen contents every time you hit C. +=item B I + +Set scrollbar style to B, B, B or B. B is +the author's favourite. + =item B I B: enable the scrollbar [default]; option B<-sb>. B: @@ -971,6 +1001,11 @@ B: blink the cursor. B: do not blink the cursor [default]; option B<-bc>. +=item B I + +B: Make the cursor underlined. B: Make the cursor a box [default]; +option B<-uc>. + =item B I B: blank the pointer when a key is pressed or after a set number @@ -993,7 +1028,7 @@ =item B I The string to send when the backspace key is pressed. If set to B -or unset it will send B (code 127) or, if shifted, B +or unset it will send B (code 127) or, with control, B (code 8) - which can be reversed with the appropriate DEC private mode escape sequence. @@ -1082,8 +1117,8 @@ 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. +scrollback buffer and, when secondaryScreen is off, switching +to/from the secondary screen will instead scroll the screen up. =item B: I @@ -1092,6 +1127,13 @@ it exits. Instead, it will wait till it is being killed or closed by the user. +=item B: I + +Sets the working directory for the shell (or the command specified via +B<-e>). The I must be an absolute path and it must exist for +@@RXVT_NAME@@ to start. If it isn't specified then the current working +directory will be used; option B<-cd>. + =item BI: I Compile I: Associate I with keysym I. The @@ -1115,7 +1157,7 @@ performed in an exact manner; however, the closest match is assured. I may contain escape values (C<\n>: newline, C<\000>: octal -number), see RESOURCES in C for futher details. +number), see RESOURCES in C for further details. You can define a range of keysyms in one shot by providing a I with pattern B, where the delimiter `/' @@ -1139,14 +1181,14 @@ URxvt.keysym.M-C-c: command:\033]701;zh_CN.GBK\007 If I takes the form C, then the specified B -is passed to the C perl handler. See the @@RXVT_NAME@@perl(3) +is passed to the C perl handler. See the @@RXVT_NAME@@perl(3) manpage. For example, the F extension (activated via C<@@RXVT_NAME@@ -pe selection>) listens for C events: URxvt.keysym.M-C-c: perl:selection:rot13 Due the the large number of modifier combinations, a defined key mapping -will match if at I the specified identifiers are being set, and +will match if I 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 C will automatically provide definitions for C, C and so on, unless some of those are defined @@ -1207,16 +1249,14 @@ =item B: I Perl code to be evaluated when all extensions have been registered. See -the @@RXVT_NAME@@perl(3) manpage. Due to security reasons, this resource -will be ignored when running setuid/setgid. +the @@RXVT_NAME@@perl(3) manpage. =item B: I Colon-separated list of additional directories that hold extension scripts. When looking for extensions specified by the C resource, @@RXVT_NAME@@ will first look in these directories and then in -F<@@RXVT_LIBDIR@@/urxvt/perl/>. Due to security reasons, this resource -will be ignored when running setuid/setgid. +F<@@RXVT_LIBDIR@@/urxvt/perl/>. See the @@RXVT_NAME@@perl(3) manpage. @@ -1249,6 +1289,10 @@ Compile I: Sets override-redirect for the terminal window, making it almost invisible to window managers; option B<-override-redirect>. +=item B I + +Turn on/off ISO 14755 (default enabled). + =item B I Turn on/off ISO 14755 5.2 mode (default enabled). @@ -1400,12 +1444,15 @@ allow this feature, B<@@RXVT_NAME@@> may need to be installed setuid root on some systems or setgid to root or to some other group on others. -=head1 COLORS AND GRAPHICS +=head1 COLOURS AND GRAPHICS In addition to the default foreground and background colours, -B<@@RXVT_NAME@@> can display up to 16 colours (8 ANSI colours plus -high-intensity bold/blink versions of the same). Here is a list of the -colours with their names. +B<@@RXVT_NAME@@> can display up to 88/256 colours: 8 ANSI colours plus +high-intensity (potentially bold/blink) versions of the same, and 72 (or +240 in 256 colour mode) colours arranged in an 4x4x4 (or 6x6x6) colour RGB +cube plus a 8 (24) colour greyscale ramp. + +Here is a list of the ANSI colours with their names. =begin table @@ -1435,52 +1482,80 @@ a number 0-15, as a convenient shorthand to reference the colour name of color0-color15. -In addition to the colours defined above, @@RXVT_NAME@@ offers an -additional 72 colours. The first 64 of those (with indices 16 to 79) -consist of a 4*4*4 RGB colour cube (i.e. I), followed by 8 additional shades of gray (with indices 80 to 87). - -Together, all those colours implement the 88 colour xterm colours. Only -the first 16 can be changed using resources currently, the rest can only -be changed via command sequences ("escape codes"). +The following text gives values for the standard 88 colour mode (and +values for the 256 colour mode in parentheses). + +The RGB cube uses indices 16..79 (16..231) using the following formulas: + + index_88 = (r * 4 + g) * 4 + b + 16 # r, g, b = 0..3 + index_256 = (r * 16 + g) * 16 + b + 16 # r, g, b = 0..15 + +The grayscale ramp uses indices 80..87 (232..239), from 10% to 90% in 10% +steps (1/26 to 25/26 in 1/26 steps) - black and white are already part of +the RGB cube. + +Together, all those colours implement the 88 (256) colour xterm +colours. Only the first 16 can be changed using resources currently, the +rest can only be changed via command sequences ("escape codes"). + +Applications are advised to use terminfo or command sequences to discover +number and RGB values of all colours (yes, you can query this...). Note that B<-rv> (B<"reverseVideo: True">) simulates reverse video by always swapping the foreground/background colours. This is in contrast to I(1) where the colours are only swapped if they have not otherwise been specified. For example, -=over 4 - -=item B<@@RXVT_NAME@@ -fg Black -bg White -rv> - -would yield White on Black, while on I(1) it would yield Black -on White. + @@RXVT_NAME@@ -fg Black -bg White -rv -=back +would yield White on Black, while on I(1) it would yield Black on +White. =head2 ALPHA CHANNEL SUPPORT If Xft support has been compiled in and as long as Xft/Xrender/X don't get -their act together, rxvt-unicode will support C -(recommended, but B have 4 digits/component) colour specifications, -in addition to the ones provided by X, where the additional A component -specifies opacity (alpha) values. The minimum value of C<0> is completely -transparent). You can also prefix any color with C<[percent]>, where -C is a decimal percentage (0-100) that specifies the opacity of -the color, where C<0> is completely transparent and C<100> is completelxy -opaque. - -You probably need to specify B<"-depth 32">, too, and have the luck that -your X-server uses ARGB pixel layout, as X is far from just supporting -ARGB visuals out of the box, and rxvt-unicode just fudges around. +their act together, rxvt-unicode will do it's own alpha channel management: + +You can prefix any colour with an opaqueness percentage enclosed in +brackets, i.e. C<[percent]>, where C is a decimal percentage +(0-100) that specifies the opacity of the colour, where C<0> is completely +transparent and C<100> is completely opaque. For example, C<[50]red> is a +half-transparent red, while C<[95]#00ff00> is an almost opaque green. This +is the recommended format to specify transparency values, and works with +all ways to specify a colour. + +For complete control, rxvt-unicode also supports +C (exactly four hex digits/component) colour +specifications, where the additional C component specifies opacity +(alpha) values. The minimum value of C<0000> is completely transparent, +while C is completely opaque). The two example colours from +earlier could also be specified as C and +C. + +You probably need to specify B<"-depth 32">, too, to force a visual with +alpha channels, and have the luck that your X-server uses ARGB pixel +layout, as X is far from just supporting ARGB visuals out of the box, and +rxvt-unicode just fudges around. -For example, the following selects an almost completely transparent red +For example, the following selects an almost completely transparent black background, and an almost opaque pink foreground: - @@RXVT_NAME@@ -depth 32 -bg rgba:0000/0000/0000/aaaa -fg "[80]pink" + @@RXVT_NAME@@ -depth 32 -bg rgba:0000/0000/0000/4444 -fg "[80]pink" -I +When not using a background image, then the interpretation of the +alpha channel is up to your compositing manager (most interpret it as +transparency of course). + +When using a background pixmap or pseudo-transparency, then the background +colour will always behave as if it were completely transparent (so the +background image shows instead), regardless of how it was specified, while +other colours will either be transparent as specified (the background +image will show through) on servers supporting the RENDER extension, or +fully opaque on servers not supporting the RENDER EXTENSION. + +Please note that due to bugs in Xft, specifying alpha values might result +in garbage being displayed when the X-server does not support the RENDER +extension. =head1 ENVIRONMENT @@ -1524,7 +1599,8 @@ =item B Used by @@RXVT_NAME@@ to connect to the display and set to the correct -display in its child processes. +display in its child processes if C<-display> isn't used to override. It +defaults to C<:0> if it doesn't exist. =item B @@ -1535,7 +1611,7 @@ The unix domain socket path used by @@RXVT_NAME@@c(1) and @@RXVT_NAME@@d(1). -Default F<<< $HOME/.rxvt-unicode-I<< > >>>. +Default F<<< $HOME/.rxvt-unicode-I<< >> >>>. =item B @@ -1545,7 +1621,7 @@ =item B -Directory where various X resource files are being located. +Directory where application-specific X resource files are located. =item B @@ -1560,7 +1636,7 @@ =item B -Color names. +Colour names. =back @@ -1621,7 +1697,7 @@ =item Emanuele Giaquinta L<< >> -Pty/tty/utmp/wtmp rewrite, lots of random hacking and bugfixing. +pty/utmp code rewrite, image code improvements, many random hacks and bugfixes. =back