--- rxvt-unicode/doc/rxvt.1.man.in 2007/12/24 08:00:16 1.78 +++ rxvt-unicode/doc/rxvt.1.man.in 2009/12/30 06:14:03 1.88 @@ -1,15 +1,7 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.35 +.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07) .\" .\" Standard preamble: .\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp @@ -25,11 +17,11 @@ .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- @@ -48,22 +40,25 @@ . ds R" '' 'br\} .\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" .\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. -.if \nF \{\ +.ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na +.el \{\ +. de IX +.. +.\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. @@ -129,7 +124,11 @@ .\" ======================================================================== .\" .IX Title "@@RXVT_NAME@@ 1" -.TH @@RXVT_NAME@@ 1 "2007-12-24" "8.9" "RXVT-UNICODE" +.TH @@RXVT_NAME@@ 1 "2009-12-30" "@@RXVT_VERSION@@" "RXVT-UNICODE" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh .SH "NAME" rxvt\-unicode (ouR XVT, unicode) \- (a VT102 emulator for the X window system) .SH "SYNOPSIS" @@ -197,7 +196,7 @@ .IX Header "OPTIONS" The \fB@@RXVT_NAME@@\fR options (mostly a subset of \fIxterm\fR's) are listed below. In keeping with the smaller-is-better philosophy, options may be -eliminated or default values chosen at compile\-time, so options and +eliminated or default values chosen at compile-time, so options and defaults listed may not accurately reflect the version installed on your system. `@@RXVT_NAME@@ \-h' gives a list of major compile-time options on the \fIOptions\fR line. Option descriptions may be prefixed with which @@ -216,13 +215,18 @@ Print out a message describing available options. .IP "\fB\-display\fR \fIdisplayname\fR" 4 .IX Item "-display displayname" -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. +Attempt to open a window on the named X display (the older form \fB\-d\fR +is still respected. but deprecated). 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 \fIxft\fR: Attempt to find a visual with the given bit depth; resource \fBdepth\fR. +.Sp +[Please note that many X servers (and libXft) are buggy with +respect to \f(CW\*(C`\-depth 32\*(C'\fR 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] .IP "\fB\-geometry\fR \fIgeom\fR" 4 .IX Item "-geometry geom" Window geometry (\fB\-g\fR still respected); resource \fBgeometry\fR. @@ -259,14 +263,14 @@ 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. -Please note that certain tint colours can be applied on the server\-side, +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 -\& @@RXVT_NAME@@ -tr -tint blue -sh 40 +\& @@RXVT_NAME@@ \-tr \-tint blue \-sh 40 .Ve .IP "\fB\-sh\fR \fInumber\fR" 4 .IX Item "-sh number" @@ -281,7 +285,7 @@ \&\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. +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 @@ -290,6 +294,11 @@ 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\-icon\fR \fIfile\fR" 4 +.IX Item "-icon file" +Compile \fIafterimage\fR: Use the specified image as application icon. This +is used by many window managers, taskbars and pagers to represent the +application window; resource \fIiconFile\fR. .IP "\fB\-bg\fR \fIcolour\fR" 4 .IX Item "-bg colour" Window background colour; resource \fBbackground\fR. @@ -301,7 +310,7 @@ 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. +command-line; for more details see resource \fBbackgroundPixmap\fR. .IP "\fB\-cr\fR \fIcolour\fR" 4 .IX Item "-cr colour" The cursor colour; resource \fBcursorColor\fR. @@ -324,12 +333,12 @@ font list is always appended to it. See resource \fBfont\fR for more details. .Sp In short, to specify an X11 core font, just specify its name or prefix it -with \f(CW\*(C`x:\*(C'\fR. To specify an XFT\-font, you need to prefix it with \f(CW\*(C`xft:\*(C'\fR, +with \f(CW\*(C`x:\*(C'\fR. To specify an XFT-font, you need to prefix it with \f(CW\*(C`xft:\*(C'\fR, e.g.: .Sp .Vb 2 -\& @@RXVT_NAME@@ -fn "xft:Bitstream Vera Sans Mono:pixelsize=15" -\& @@RXVT_NAME@@ -fn "9x15bold,xft:Bitstream Vera Sans Mono" +\& @@RXVT_NAME@@ \-fn "xft:Bitstream Vera Sans Mono:pixelsize=15" +\& @@RXVT_NAME@@ \-fn "9x15bold,xft:Bitstream Vera Sans Mono" .Ve .Sp See also the question \*(L"How does rxvt-unicode choose fonts?\*(R" in the \s-1FAQ\s0 @@ -371,6 +380,13 @@ .IP "\fB\-sb\fR|\fB+sb\fR" 4 .IX Item "-sb|+sb" Turn on/off scrollbar; resource \fBscrollBar\fR. +.IP "\fB\-sr\fR|\fB+sr\fR" 4 +.IX Item "-sr|+sr" +Put scrollbar on right/left; resource \fBscrollBar_right\fR. +.IP "\fB\-st\fR|\fB+st\fR" 4 +.IX Item "-st|+st" +Display rxvt (non XTerm/NeXT) scrollbar without/with a trough; +resource \fBscrollBar_floating\fR. .IP "\fB\-si\fR|\fB+si\fR" 4 .IX Item "-si|+si" Turn on/off scroll-to-bottom on \s-1TTY\s0 output inhibit; resource @@ -384,13 +400,6 @@ Turn on/off scrolling with the scrollback buffer as new lines appear. This only takes effect if \fB\-si\fR is also given; resource \&\fBscrollWithBuffer\fR. -.IP "\fB\-sr\fR|\fB+sr\fR" 4 -.IX Item "-sr|+sr" -Put scrollbar on right/left; resource \fBscrollBar_right\fR. -.IP "\fB\-st\fR|\fB+st\fR" 4 -.IX Item "-st|+st" -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" If enabled (default), \*(L"Horizontal Tab\*(R" characters are being stored as @@ -401,6 +410,9 @@ .IP "\fB\-bc\fR|\fB+bc\fR" 4 .IX Item "-bc|+bc" Blink the cursor; resource \fBcursorBlink\fR. +.IP "\fB\-uc\fR|\fB+uc\fR" 4 +.IX Item "-uc|+uc" +Make the cursor underlined; resource \fBcursorUnderline\fR. .IP "\fB\-iconic\fR" 4 .IX Item "-iconic" Start iconified, if the window manager supports that option. @@ -422,7 +434,8 @@ .IX Item "-bl" 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. +decorations; resource \fBborderLess\fR. If the window manager does not +support \s-1MWM\s0 hints (e.g. kwin), enables override-redirect mode. .IP "\fB\-override\-redirect\fR" 4 .IX Item "-override-redirect" Compile \fIfrills\fR: Sets override-redirect on the window; resource @@ -438,6 +451,12 @@ Compile \fIfrills\fR: Lines (pixel height) to insert between each row of the display. Useful to work around font rendering problems; resource \&\fBlineSpace\fR. +.IP "\fB\-letsp\fR \fInumber\fR" 4 +.IX Item "-letsp number" +Compile \fIfrills\fR: 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 \fBletterSpace\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 @@ -450,7 +469,7 @@ window; also sets the window title and icon name to be the basename of the program being executed if neither \fI\-title\fR (\fI\-T\fR) nor \fI\-n\fR are given on the command line. If this option is used, it must be the last -on the command\-line. If there is no \fB\-e\fR option then the default is to +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 @@ -458,7 +477,7 @@ run shell commands, you have to specify the shell, like this: .Sp .Vb 1 -\& @@RXVT_NAME@@ -e sh -c "shell commands" +\& @@RXVT_NAME@@ \-e sh \-c "shell commands" .Ve .IP "\fB\-title\fR \fItext\fR" 4 .IX Item "-title text" @@ -493,8 +512,8 @@ .IP "\fB\-tcw\fR" 4 .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 to +button. Only effective when the original (non-perl) selection code is +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" @@ -520,6 +539,11 @@ 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\-cd\fR \fIpath\fR" 4 +.IX Item "-cd path" +Sets the working directory for the shell (or the command specified via +\&\fB\-e\fR). The \fIpath\fR must be an absolute path and it must exist for +@@RXVT_NAME@@ to start; resource \fBchdir\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 @@ -558,9 +582,9 @@ .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 &"; +\& $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 @@ -584,18 +608,14 @@ .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) . "&"; +\& 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; +\& my $slave = $pty\->slave; \& while (<$slave>) { print $slave "got <$_>\en" } .Ve .IP "\fB\-pe\fR \fIstring\fR" 4 @@ -606,7 +626,7 @@ .IX Header "RESOURCES" Note: `@@RXVT_NAME@@ \-\-help' gives a list of all resources (long options) compiled into your version. All resources are also available as -long\-options. +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 @@ -614,12 +634,12 @@ with later settings overwriting earlier ones: .PP .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 +\& 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 +\& 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 @@ -636,6 +656,12 @@ .IX Item "depth: bitdepth" Compile \fIxft\fR: Attempt to find a visual with the given bit depth; option \fB\-depth\fR. +.IP "\fBbuffered:\fR \fIboolean\fR" 4 +.IX Item "buffered: boolean" +Compile \fIxft\fR: 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. .IP "\fBgeometry:\fR \fIgeom\fR" 4 .IX Item "geometry: geom" Create the window with the specified X window geometry [default 80x24]; @@ -746,8 +772,11 @@ 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 blur with the specified radius to the transparent background image; option \fB\-blr\fR. +.IP "\fBiconFile:\fR \fIfile\fR" 4 +.IX Item "iconFile: file" +Set the application icon pixmap; option \fB\-icon\fR. .IP "\fBscrollColor:\fR \fIcolour\fR" 4 .IX Item "scrollColor: colour" Use the specified colour for the scrollbar [default #B2B2B2]. @@ -773,18 +802,18 @@ 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. +\& 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 +blended over transparency image using either alpha-blending, or any other blending type, specified with \fB\-blt \*(L"type\*(R"\fR option. .IP "\fBpath:\fR \fIpath\fR" 4 .IX Item "path: path" @@ -809,8 +838,8 @@ .Sp .Vb 5 \& 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 +\& \-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 \& xft:Code2000:antialias=false .Ve @@ -821,7 +850,7 @@ wide and 15 pixels high. .Sp 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 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 useful supplement. .Sp @@ -842,7 +871,7 @@ The font list to use for displaying \fBbold\fR, \fIitalic\fR or \fB\f(BIbold italic\fB\fR characters, respectively. .Sp -If specified and non\-empty, then the syntax is the same as for the +If specified and non-empty, then the syntax is the same as for the \&\fBfont\fR\-resource, and the given font list will be used as is, which makes it possible to substitute completely different font styles for bold and italic. @@ -860,10 +889,6 @@ intensity foreground/background colours. Disabling this option (\fBFalse\fR, option \fB+is\fR) disables this behaviour, the high intensity colours are not reachable. -.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. .IP "\fBtitle:\fR \fIstring\fR" 4 .IX Item "title: string" Set window title string, the default title is the command-line @@ -882,6 +907,8 @@ .IX Item "urgentOnBell: boolean" \&\fBTrue\fR: set the urgency hint for the wm on receipt of a bell character. \&\fBFalse\fR: do not set the urgency hint [default]. +.Sp +@@RXVT_NAME@@ resets the urgency hint on every focus change. .IP "\fBvisualBell:\fR \fIboolean\fR" 4 .IX Item "visualBell: boolean" \&\fBTrue\fR: use visual bell on receipt of a bell character; option \fB\-vb\fR. @@ -896,22 +923,26 @@ \&\fBTrue\fR: inhibit writing record into the system log file \fButmp\fR; option \fB\-ut\fR. \fBFalse\fR: write record into the system log file \fButmp\fR [default]; option \fB+ut\fR. -.IP "\fBprint\-pipe:\fR \fIstring\fR" 4 +.IP "\fBprint-pipe:\fR \fIstring\fR" 4 .IX Item "print-pipe: string" 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. +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) +\& URxvt.print\-pipe: cat > $(TMPDIR=$HOME mktemp urxvt.XXXXXX) .Ve .Sp This creates a new file in your home directory with the screen contents every time you hit \f(CW\*(C`Print\*(C'\fR. +.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. .IP "\fBscrollBar:\fR \fIboolean\fR" 4 .IX Item "scrollBar: boolean" \&\fBTrue\fR: enable the scrollbar [default]; option \fB\-sb\fR. \fBFalse\fR: @@ -990,6 +1021,10 @@ .IX Item "cursorBlink: boolean" \&\fBTrue\fR: blink the cursor. \fBFalse\fR: do not blink the cursor [default]; option \fB\-bc\fR. +.IP "\fBcursorUnderline:\fR \fIboolean\fR" 4 +.IX Item "cursorUnderline: boolean" +\&\fBTrue\fR: Make the cursor underlined. \fBFalse\fR: Make the cursor a box [default]; +option \fB\-uc\fR. .IP "\fBpointerBlank:\fR \fIboolean\fR" 4 .IX Item "pointerBlank: boolean" \&\fBTrue\fR: blank the pointer when a key is pressed or after a set number @@ -1066,7 +1101,7 @@ 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, +\&\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" @@ -1075,7 +1110,7 @@ \&\fB\-mod\fR. .IP "\fBanswerbackString:\fR \fIstring\fR" 4 .IX Item "answerbackString: string" -Specify the reply rxvt-unicode sends to the shell when an \s-1ENQ\s0 (control\-E) +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 \fIboolean\fR" 4 @@ -1085,14 +1120,20 @@ .IX Item "secondaryScroll: boolean" 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. .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 "\fBchdir\fR: \fIpath\fR" 4 +.IX Item "chdir: path" +Sets the working directory for the shell (or the command specified via +\&\fB\-e\fR). The \fIpath\fR 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 \fB\-cd\fR. .IP "\fBkeysym.\fR\fIsym\fR: \fIstring\fR" 4 .IX Item "keysym.sym: string" Compile \fIfrills\fR: Associate \fIstring\fR with keysym \fIsym\fR. The @@ -1125,15 +1166,15 @@ Its usage can be demonstrated by an example: .Sp .Vb 1 -\& URxvt.keysym.M-C-0x61: list|\e033 +\& URxvt.keysym.M\-C\-0x61: list|\e033 .Ve .Sp The above line is equivalent to the following three lines: .Sp .Vb 3 -\& URxvt.keysym.Meta-Control-0x61: \e033 -\& URxvt.keysym.Meta-Control-0x62: \e033 -\& URxvt.keysym.Meta-Control-0x63: \e033 +\& URxvt.keysym.Meta\-Control\-0x61: \e033 +\& URxvt.keysym.Meta\-Control\-0x62: \e033 +\& URxvt.keysym.Meta\-Control\-0x63: \e033 .Ve .Sp If \fIstring\fR takes the form of \f(CW\*(C`command:STRING\*(C'\fR, the specified \fB\s-1STRING\s0\fR @@ -1142,16 +1183,16 @@ when Control-Meta-c is being pressed": .Sp .Vb 1 -\& URxvt.keysym.M-C-c: command:\e033]701;zh_CN.GBK\e007 +\& 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) +is passed to the \f(CW\*(C`on_user_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 +\& URxvt.keysym.M\-C\-c: perl:selection:rot13 .Ve .Sp Due the the large number of modifier combinations, a defined key mapping @@ -1168,7 +1209,7 @@ .Sp .Vb 2 \& URxvt.keysym.Insert: -\& URxvt.keysym.S-Insert: builtin: +\& URxvt.keysym.S\-Insert: builtin: .Ve .Sp The first line defines a mapping for \f(CW\*(C`Insert\*(C'\fR and \fIany\fR combination @@ -1180,16 +1221,16 @@ font-switching at runtime: .Sp .Vb 2 -\& URxvt.keysym.M-C-1: command:\e033]50;suxuseuro\e007 -\& URxvt.keysym.M-C-2: command:\e033]50;9x15bold\e007 +\& URxvt.keysym.M\-C\-1: command:\e033]50;suxuseuro\e007 +\& URxvt.keysym.M\-C\-2: command:\e033]50;9x15bold\e007 .Ve .Sp Other things are possible, e.g. resizing (see @@RXVT_NAME@@(7) for more info): .Sp .Vb 2 -\& URxvt.keysym.M-C-3: command:\e033[8;25;80t -\& URxvt.keysym.M-C-4: command:\e033[8;48;110t +\& 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" @@ -1222,26 +1263,24 @@ .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. +the @@RXVT_NAME@@\fIperl\fR\|(3) manpage. .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. +\&\fI@@RXVT_LIBDIR@@/urxvt/perl/\fR. .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 +.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 +.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). @@ -1310,19 +1349,19 @@ .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. +supported in rxvt-unicode. Bug me if you need this. .PP You can, however, switch fonts at runtime using escape sequences, e.g.: .PP .Vb 1 -\& printf '\ee]710;%s\e007' "9x15bold,xft:Kochi Gothic" +\& printf \*(Aq\ee]710;%s\e007\*(Aq "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 +\& 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. @@ -1333,8 +1372,9 @@ 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 -.IX Item "5.1: Basic method" +.IP "\(bu" 4 +5.1: Basic method +.Sp This allows you to enter unicode characters using their hexcode. .Sp Start by pressing and holding both \f(CW\*(C`Control\*(C'\fR and \f(CW\*(C`Shift\*(C'\fR, then enter @@ -1349,8 +1389,9 @@ address printed as hexcodes, e.g. \f(CW\*(C`671d 65e5\*(C'\fR. You can enter this easily by pressing \f(CW\*(C`Control\*(C'\fR and \f(CW\*(C`Shift\*(C'\fR, followed by \f(CW\*(C`6\-7\-1\-D\-SPACE\-6\-5\-E\-5\*(C'\fR, followed by releasing the modifier keys. -.IP "* 5.2: Keyboard symbols entry method" 4 -.IX Item "5.2: Keyboard symbols entry method" +.IP "\(bu" 4 +5.2: Keyboard symbols entry method +.Sp This mode lets you input characters representing the keycap symbols of your keyboard, if representable in the current locale encoding. .Sp @@ -1360,13 +1401,15 @@ keycap symbol. The symbol will only be entered when the key has been released, otherwise pressing e.g. \f(CW\*(C`Shift\*(C'\fR would enter the symbol for \&\f(CW\*(C`ISO Level 2 Switch\*(C'\fR, although your intention might have been to enter a -reverse tab (Shift\-Tab). -.IP "* 5.3: Screen-selection entry method" 4 -.IX Item "5.3: Screen-selection entry method" +reverse tab (Shift-Tab). +.IP "\(bu" 4 +5.3: Screen-selection entry method +.Sp While this is implemented already (it's basically the selection mechanism), it could be extended by displaying a unicode character map. -.IP "* 5.4: Feedback method for identifying displayed characters for later input" 4 -.IX Item "5.4: Feedback method for identifying displayed characters for later input" +.IP "\(bu" 4 +5.4: Feedback method for identifying displayed characters for later input +.Sp This method lets you display the unicode character code associated with characters already displayed. .Sp @@ -1415,7 +1458,6 @@ foreground = Black background = White .TE - .PP It is also possible to specify the colour values of \fBforeground\fR, \&\fBbackground\fR, \fBcursorColor\fR, \fBcursorColor2\fR, \fBcolorBD\fR, \fBcolorUL\fR as @@ -1435,35 +1477,60 @@ always swapping the foreground/background colours. This is in contrast to \&\fIxterm\fR(1) where the colours are only swapped if they have not otherwise been specified. For example, -.IP "\fB@@RXVT_NAME@@ \-fg Black \-bg White \-rv\fR" 4 -.IX Item "@@RXVT_NAME@@ -fg Black -bg White -rv" -would yield White on Black, while on \fIxterm\fR(1) it would yield Black -on White. -.Sh "\s-1ALPHA\s0 \s-1CHANNEL\s0 \s-1SUPPORT\s0" +.PP +.Vb 1 +\& @@RXVT_NAME@@ \-fg Black \-bg White \-rv +.Ve +.PP +would yield White on Black, while on \fIxterm\fR(1) it would yield Black on +White. +.SS "\s-1ALPHA\s0 \s-1CHANNEL\s0 \s-1SUPPORT\s0" .IX Subsection "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 \f(CW\*(C`rgba:rrrr/gggg/bbbb/aaaa\*(C'\fR -(recommended, but \fB\s-1MUST\s0\fR 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 \f(CW0\fR is completely -transparent). You can also prefix any color with \f(CW\*(C`[percent]\*(C'\fR, where -\&\f(CW\*(C`percent\*(C'\fR is a decimal percentage (0\-100) that specifies the opacity of -the color, where \f(CW0\fR is completely transparent and \f(CW100\fR is completelxy -opaque. -.PP -You probably need to specify \fB\*(L"\-depth 32\*(R"\fR, too, and have the luck that -your X\-server uses \s-1ARGB\s0 pixel layout, as X is far from just supporting -\&\s-1ARGB\s0 visuals out of the box, and rxvt-unicode just fudges around. +their act together, rxvt-unicode will do it's own alpha channel management: +.PP +You can prefix any color with an opaquenes percentage enclosed in +brackets, i.e. \f(CW\*(C`[percent]\*(C'\fR, where \f(CW\*(C`percent\*(C'\fR is a decimal percentage +(0\-100) that specifies the opacity of the color, where \f(CW0\fR is completely +transparent and \f(CW100\fR is completely opaque. For example, \f(CW\*(C`[50]red\*(C'\fR is a +half-transparent red, while \f(CW\*(C`[95]#00ff00\*(C'\fR is an almost opaque green. This +is the recommended format to specify transparency values, and works with +all ways to specify a colour. +.PP +For complete control, rxvt-unicode also supports +\&\f(CW\*(C`rgba:rrrr/gggg/bbbb/aaaa\*(C'\fR (exactly four hex digits/component) colour +specifications, where the additional \f(CW\*(C`aaaa\*(C'\fR component specifies opacity +(alpha) values. The minimum value of \f(CW0000\fR is completely transparent, +while \f(CW\*(C`ffff\*(C'\fR is completely opaque). The two example colours from +earlier could also be specified as \f(CW\*(C`rgba:ff00/0000/0000/8000\*(C'\fR and +\&\f(CW\*(C`rgba:0000/ff00/0000/f332\*(C'\fR. +.PP +You probably need to specify \fB\*(L"\-depth 32\*(R"\fR, too, to force a visual with +alpha channels, and have the luck that your X\-server uses \s-1ARGB\s0 pixel +layout, as X is far from just supporting \s-1ARGB\s0 visuals out of the box, and +rxvt-unicode just fudges around. .PP -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: .PP .Vb 1 -\& @@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" .Ve .PP -\&\fIPlease note that transparency of any kind if completely unsupported by -the author. Don't bug him with installation questions!\fR +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). +.PP +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 \s-1RENDER\s0 extension, or +fully opaque on servers not supporting the \s-1RENDER\s0 \s-1EXTENSION\s0. +.PP +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 \s-1RENDER\s0 +extension. .SH "ENVIRONMENT" .IX Header "ENVIRONMENT" \&\fB@@RXVT_NAME@@\fR sets and/or uses the following environment variables: @@ -1498,7 +1565,8 @@ .IP "\fB\s-1DISPLAY\s0\fR" 4 .IX Item "DISPLAY" 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 \f(CW\*(C`\-display\*(C'\fR isn't used to override. It +defaults to \f(CW\*(C`:0\*(C'\fR if it doesn't exist. .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. @@ -1507,7 +1575,7 @@ The unix domain socket path used by @@RXVT_NAME@@c(1) and @@RXVT_NAME@@d(1). .Sp -Default \fI$HOME/.rxvt\-unicode\-\fI" Rewrote screen display and text selection routines. .Sp -Project Coordinator (changes.txt 2.4.6 \- rxvt\-unicode) +Project Coordinator (changes.txt 2.4.6 \- rxvt-unicode) .IP "Marc Alexander Lehmann " 4 .IX Item "Marc Alexander Lehmann " -Forked rxvt\-unicode, unicode support, rewrote almost all the code, perl +Forked rxvt-unicode, unicode support, rewrote almost all the code, perl extension, random hacks, numerous bugfixes and extensions. .Sp Project Coordinator (Changes 1.0 \-)