--- rxvt-unicode/doc/rxvt.1.pod 2007/12/30 22:43:40 1.156 +++ rxvt-unicode/doc/rxvt.1.pod 2009/05/30 08:51:23 1.170 @@ -94,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. @@ -179,6 +184,12 @@ on some backgrounds. Maximum radius value is 128. Compile I; resource I. +=item B<-icon> I + +Compile 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. @@ -275,6 +286,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 @@ -291,15 +311,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 @@ -337,7 +348,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> @@ -357,6 +369,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 @@ -452,6 +471,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 @@ -569,6 +594,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]; @@ -696,9 +728,13 @@ =item B I -Apply Gaussian Blurr with the specified radius to the transparent +Apply gaussian blur with the specified radius to the transparent background image; option B<-blr>. +=item B I + +Set the application icon pixmap; option B<-icon>. + =item B I Use the specified colour for the scrollbar [default #B2B2B2]. @@ -813,11 +849,6 @@ option B<+is>) disables this behaviour, the high intensity colours are not reachable. -=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 @@ -840,6 +871,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>. @@ -872,6 +905,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: @@ -1079,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 @@ -1089,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 @@ -1204,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. @@ -1458,26 +1501,48 @@ =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 color with an opaquenes percentage enclosed in +brackets, i.e. 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 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 @@ -1521,7 +1586,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