--- rxvt-unicode/doc/rxvt.7.pod 2007/06/24 23:13:21 1.134 +++ rxvt-unicode/doc/rxvt.7.pod 2009/05/30 08:53:48 1.177 @@ -19,7 +19,10 @@ all escape sequences, and other background information. The newest version of this document is also available on the World Wide Web at -L. +L. + +The main manual page for @@RXVT_NAME@@ itself is available at +L. =head1 RXVT-UNICODE/URXVT FREQUENTLY ASKED QUESTIONS @@ -32,6 +35,18 @@ channel C<#rxvt-unicode> has some rxvt-unicode enthusiasts that might be interested in learning about new and exciting problems (but not FAQs :). +=head3 I use Gentoo, and I have a problem... + +There are three big problems with Gentoo Linux: first of all, most if not +all Gentoo systems are completely broken (missing or mismatched header +files, broken compiler etc. are just the tip of the iceberg); secondly, +the Gentoo maintainer thinks it is a good idea to add broken patches to +the code; and lastly, it should be called Gentoo GNU/Linux. + +For these reasons, it is impossible to support rxvt-unicode on +Gentoo. Problems appearing on Gentoo systems will usually simply be +ignored unless they can be reproduced on non-Gentoo systems. + =head3 Does it support tabs, can I have a tabbed rxvt-unicode? Beginning with version 7.3, there is a perl extension that implements a @@ -199,9 +214,9 @@ libX11.so.6 => /usr/X11R6/lib/libX11.so.6 (0x00002aaaaabc3000) libgcc_s.so.1 => /lib/libgcc_s.so.1 (0x00002aaaaada2000) - libc.so.6 => /lib/libc.so.6 (0x00002aaaaaeb0000) - libdl.so.2 => /lib/libdl.so.2 (0x00002aaaab0ee000) - /lib64/ld-linux-x86-64.so.2 (0x00002aaaaaaab000) + libc.so.6 => /lib/libc.so.6 (0x00002aaaaaeb0000) + libdl.so.2 => /lib/libdl.so.2 (0x00002aaaab0ee000) + /lib64/ld-linux-x86-64.so.2 (0x00002aaaaaaab000) No large bloated libraries (of course, none were linked in statically), except maybe libX11 :) @@ -211,18 +226,17 @@ =head3 I can't get transparency working, what am I doing wrong? -First of all, transparency isn't officially supported in rxvt-unicode, so -you are mostly on your own. Do not bug the author about it (but you may -bug everybody else). Also, if you can't get it working consider it a rite -of passage: ... and you failed. +First of all, please address all transparency related issues to Sasha Vasko at +sasha@aftercode.net and do not bug the author about it. Also, if you can't +get it working consider it a rite of passage: ... and you failed. Here are four ways to get transparency. B read the manpage and option descriptions for the programs mentioned and rxvt-unicode. Really, do it! -1. Use inheritPixmap: +1. Use transparent mode: Esetroot wallpaper.jpg - @@URXVT_NAME@@ -ip -tint red -sh 40 + @@URXVT_NAME@@ -tr -tint red -sh 40 That works. If you think it doesn't, you lack transparency and tinting support, or you are unable to read. @@ -231,10 +245,10 @@ to use effects other than tinting and shading: Just shade/tint/whatever your picture with gimp or any other tool: - convert wallpaper.jpg -blur 20x20 -modulate 30 background.xpm - @@URXVT_NAME@@ -pixmap background.xpm -pe automove-background + convert wallpaper.jpg -blur 20x20 -modulate 30 background.jpg + @@URXVT_NAME@@ -pixmap "background.jpg;:root" -That works. If you think it doesn't, you lack XPM and Perl support, or you +That works. If you think it doesn't, you lack AfterImage support, or you are unable to read. 3. Use an ARGB visual: @@ -344,10 +358,9 @@ If no bold colour is set via C, bold will invert text using the standard foreground colour. -For the standard background colour, blinking will actually make the -text blink when compiled with C<--enable-blinking>. with standard -colours. Without C<--enable-blinking>, the blink attribute will be -ignored. +For the standard background colour, blinking will actually make +the text blink when compiled with C<--enable-text-blink>. Without +C<--enable-text-blink>, the blink attribute will be ignored. On ANSI colours, bold/blink attributes are used to set high-intensity foreground/background colors. @@ -462,6 +475,13 @@ Until then, you might get away with switching fonts at runtime (see L later in this document). +=head3 How can I make mplayer display video correctly? + +We are working on it, in the meantime, as a workaround, use something like: + + @@URXVT_NAME@@ -b 600 -geometry 20x1 -e sh -c 'mplayer -wid $WINDOWID file...' + + =head2 Keyboard, Mouse & User Interaction =head3 The new selection selects pieces that are too big, how can I select single words? @@ -478,7 +498,7 @@ URxvt.selection.pattern-0: ([^"&'()*,;<=>?@[\\\\]^`{|})]+) -Please also note that the I combination also +Please also note that the I combination also selects words like the old code. =head3 I don't like the new selection/popups/hotkeys/perl, how do I change/disable it? @@ -606,7 +626,7 @@ Some other Backspace problems: -some editors use termcap/terminfo, +some editors use termcap/terminfo, some editors (vim I'm told) expect Backspace = ^H, GNU Emacs (and Emacs-like editors) use ^H for help. @@ -657,7 +677,6 @@ required for your particular machine. - =head2 Terminal Configuration =head3 Can I see a typical configuration? @@ -793,7 +812,7 @@ IRC*keysym.M-C-1: command:\033]710;suxuseuro\007\033]711;suxuseuro\007 IRC*keysym.M-C-2: command:\033]710;9x15bold\007\033]711;9x15bold\007 -C and C switch between two different font +C and C switch between two different font sizes. C allows me to keep an eye (and actually read) stuff while keeping a very small window. If somebody pastes something complicated (e.g. japanese), I temporarily switch to a larger font. @@ -840,13 +859,14 @@ as that for xterm, or even rxvt (for which the same problem often arises). The correct solution for this problem is to install the terminfo, this can -be done like this (with ncurses' infocmp and works as user and admin): +be done by simply installing rxvt-unicode on the remote system as well +(in case you have a nice package manager ready), or you can install the +terminfo database manually like this (with ncurses infocmp. works as +user and root): REMOTE=remotesystem.domain infocmp rxvt-unicode | ssh $REMOTE "mkdir -p .terminfo && cat >/tmp/ti && tic /tmp/ti" -... or by installing rxvt-unicode normally on the remote system, - One some systems you might need to set C<$TERMINFO> to the full path of F<$HOME/.terminfo> for this to work. @@ -865,6 +885,12 @@ If you don't plan to use B (quite common...) you could also replace the rxvt terminfo file with the rxvt-unicode one and use C. +=head3 nano fails with "Error opening terminal: rxvt-unicode" + +This exceptionally confusing and useless error message is printed by nano +when it can't find the terminfo database. Nothing is wrong with your +terminal, read the previous answer for a solution. + =head3 C outputs some error when compiling the terminfo entry. Most likely it's the empty definition for C. Just replace it by @@ -887,28 +913,8 @@ infocmp -C rxvt-unicode -Or you could use this termcap entry, generated by the command above: - - rxvt-unicode|rxvt-unicode terminal (X Window System):\ - :am:bw:eo:km:mi:ms:xn:xo:\ - :co#80:it#8:li#24:lm#0:\ - :AL=\E[%dL:DC=\E[%dP:DL=\E[%dM:DO=\E[%dB:IC=\E[%d@:\ - :K1=\EOw:K2=\EOu:K3=\EOy:K4=\EOq:K5=\EOs:LE=\E[%dD:\ - :RI=\E[%dC:SF=\E[%dS:SR=\E[%dT:UP=\E[%dA:ae=\E(B:al=\E[L:\ - :as=\E(0:bl=^G:cd=\E[J:ce=\E[K:cl=\E[H\E[2J:\ - :cm=\E[%i%d;%dH:cr=^M:cs=\E[%i%d;%dr:ct=\E[3g:dc=\E[P:\ - :dl=\E[M:do=^J:ec=\E[%dX:ei=\E[4l:ho=\E[H:\ - :i1=\E[?47l\E=\E[?1l:ic=\E[@:im=\E[4h:\ - :is=\E[r\E[m\E[2J\E[H\E[?7h\E[?1;3;4;6l\E[4l:\ - :k1=\E[11~:k2=\E[12~:k3=\E[13~:k4=\E[14~:k5=\E[15~:\ - :k6=\E[17~:k7=\E[18~:k8=\E[19~:k9=\E[20~:kD=\E[3~:\ - :kI=\E[2~:kN=\E[6~:kP=\E[5~:kb=\177:kd=\EOB:ke=\E[?1l\E>:\ - :kh=\E[7~:kl=\EOD:kr=\EOC:ks=\E[?1h\E=:ku=\EOA:le=^H:\ - :mb=\E[5m:md=\E[1m:me=\E[m\017:mr=\E[7m:nd=\E[C:rc=\E8:\ - :sc=\E7:se=\E[27m:sf=^J:so=\E[7m:sr=\EM:st=\EH:ta=^I:\ - :te=\E[r\E[?1049l:ti=\E[?1049h:ue=\E[24m:up=\E[A:\ - :us=\E[4m:vb=\E[?5h\E[?5l:ve=\E[?25h:vi=\E[?25l:\ - :vs=\E[?25h: +Or you could use the termcap entry in doc/etc/rxvt-unicode.termcap, +generated by the command above. =head3 Why does C no longer have coloured output? @@ -1070,7 +1076,7 @@ xprop -root XIM_SERVERS -=item +=item =back @@ -1153,14 +1159,6 @@ things like the dynamic loader of your system, which should result in very little risk. -=head3 On Solaris 9, many line-drawing characters are too wide. - -Seems to be a known bug, read -L. Some people use the -following ugly workaround to get non-double-wide-characters working: - - #define wcwidth(x) wcwidth(x) > 1 ? 1 : wcwidth(x) - =head3 I am on FreeBSD and rxvt-unicode does not seem to work at all. Rxvt-unicode requires the symbol C<__STDC_ISO_10646__> to be defined @@ -1173,7 +1171,7 @@ B. This is, of course, completely fine with respect to standards. However, that means rxvt-unicode only works in C, C and -C locales under FreeBSD (which all use Unicode as B. +C locales under FreeBSD (which all use Unicode as B). C<__STDC_ISO_10646__> is the only sane way to support multi-language apps in an OS, as using a locale-dependent (and non-standardized) @@ -1193,11 +1191,6 @@ system libraries once and for all, instead of forcing every app to carry complete replacements for them :) -=head3 I use Solaris 9 and it doesn't compile/work/etc. - -Try the diff in F as a base. It fixes the worst -problems with C and a compile problem. - =head3 How can I use rxvt-unicode under cygwin? rxvt-unicode should compile and run out of the box on cygwin, using @@ -1211,6 +1204,25 @@ encodings (you might try C), so you are likely limited to 8-bit encodings. +=head3 Character widths are not correct. + +urxvt uses the system wcwidth function to know the information about +the width of characters, so on systems with incorrect locale data you +will likely get bad results. Two notorious examples are Solaris 9, +where single-width characters like U+2514 are reported as double-width, +and Darwin 8, where combining chars are reported having width 1. + +The solution is to upgrade your system or switch to a better one. A +possibly working workaround is to use a wcwidth implementation like + +http://www.cl.cam.ac.uk/~mgk25/ucs/wcwidth.c + +=head3 I want 256 colors + +Are you sure you need 256 colors? 88 colors should be enough for most +purposes. If you really need more, there is an unsupported patch for +it in the doc directory, but please do not ask for it to be applied. + =head1 RXVT-UNICODE TECHNICAL REFERENCE The rest of this document describes various technical aspects of @@ -1472,6 +1484,8 @@ B<< C >> Clear to Right (default) B<< C >> Clear to Left B<< C >> Clear All + B<< C >> Like Ps = 0, but is ignored when wrapped + (@@RXVT_NAME@@ extension) =end table @@ -1807,8 +1821,8 @@ =begin table - B<< C >> scrollBar visisble - B<< C >> scrollBar invisisble + B<< C >> scrollBar visible + B<< C >> scrollBar invisible =end table @@ -1901,6 +1915,24 @@ =end table +=item B<< C >> (X11 XTerm) + +=begin table + + B<< C >> Send Mouse X & Y on button press and release, and motion with a button pressed. + B<< C >> No mouse reporting. + +=end table + +=item B<< C >> (X11 XTerm) + +=begin table + + B<< C >> Send Mouse X & Y on button press and release, and motion. + B<< C >> No mouse reporting. + +=end table + =item B<< C >> (B) =begin table @@ -1955,6 +1987,15 @@ =end table +=item B<< C >> + +=begin table + + B<< C >> Enable bracketed paste mode - prepend / append to the pasted text the control sequences C / C + B<< C >> Disable bracketed paste mode + +=end table + =back =back @@ -1978,25 +2019,26 @@ B<< C >> Change Window Title to B<< C >> B<< C >> If B<< C >> starts with a B<< C >>, query the (STRING) property of the window and return it. If B<< C >> contains a B<< C<=> >>, set the named property to the given value, else delete the specified property. B<< C >> B<< C >> is a semi-colon separated sequence of one or more semi-colon separated B/B pairs, where B is an index to a colour and B is the name of a colour. Each pair causes the Bed colour to be changed to B. Numbers 0-7 corresponds to low-intensity (normal) colours and 8-15 corresponds to high-intensity colours. 0=black, 1=red, 2=green, 3=yellow, 4=blue, 5=magenta, 6=cyan, 7=white - B<< C >> Change colour of text foreground to B<< C >> B<(NB: may change in future)> - B<< C >> Change colour of text background to B<< C >> B<(NB: may change in future)> + B<< C >> Change colour of text foreground to B<< C >> + B<< C >> Change colour of text background to B<< C >> B<< C >> Change colour of text cursor foreground to B<< C >> B<< C >> Change colour of mouse foreground to B<< C >> B<< C >> Change colour of highlight characters to B<< C >> B<< C >> Change colour of bold characters to B<< C >> [deprecated, see 706] B<< C >> Change colour of underlined characters to B<< C >> [deprecated, see 707] - B<< C >> Change background pixmap parameters (see section XPM) (Compile XPM). - B<< C >> Change default foreground colour to B<< C >>. + B<< C >> Change background pixmap parameters (see section BACKGROUND IMAGE) (Compile AfterImage). + B<< C >> Change default foreground colour to B<< C >>. [deprecated, use 10] B<< C >> Change Log File to B<< C >> I - B<< C >> Change default background colour to B<< C >>. + B<< C >> Change default background colour to B<< C >>. [deprecated, use 11] B<< C >> Set fontset to B<< C >>, with the following special values of B<< C >> (B) B<< C<#+n> >> change up B<< C >> B<< C<#-n> >> change down B<< C >> if B<< C >> is missing of 0, a value of 1 is used I change to font0 B<< C >> change to font B<< C >> - B<< C >> Log all scrollback buffer and all of screen to B<< C >> + B<< C >> Log all scrollback buffer and all of screen to B<< C >> [disabled] B<< C >> Change current locale to B<< C >>, or, if B<< C >> is B<< C >>, return the current locale (Compile frills). B<< C >> Request version if B<< C >> is B<< C >>, returning C, the resource name, the major and minor version numbers, e.g. C. B<< C >> Change colour of italic characters to B<< C >> B<< C >> Change background pixmap tint colour to B<< C >> (Compile transparency). B<< C >> Change colour of bold characters to B<< C >> B<< C >> Change colour of underlined characters to B<< C >> + B<< C >> Change colour of the border to B<< C >> B<< C >> Set normal fontset to B<< C >>. Same as C. B<< C >> Set bold fontset to B<< C >>. Similar to C (Compile styles). B<< C >> Set italic fontset to B<< C >>. Similar to C (Compile styles). @@ -2009,10 +2051,10 @@ =back -=head1 XPM +=head1 BACKGROUND IMAGE -For the XPM XTerm escape sequence B<< C >> then value -of B<< C >> can be the name of the background pixmap followed by a +For the BACKGROUND IMAGE XTerm escape sequence B<< C >> the value +of B<< C >> can be the name of the background image file followed by a sequence of scaling/positioning commands separated by semi-colons. The scaling/positioning commands are as follows: @@ -2060,13 +2102,13 @@ =over 4 -=item B<\E]20;funky\a> +=item B<\E]20;funky.jpg\a> -load B as a tiled image +load B as a tiled image -=item B<\E]20;mona;100\a> +=item B<\E]20;mona.jpg;100\a> -load B with a scaling of 100% +load B with a scaling of 100% =item B<\E]20;;200;?\a> @@ -2074,6 +2116,7 @@ the title =back + X =head1 Mouse Reporting @@ -2124,10 +2167,11 @@ Row = B<< C<< - SPACE >> >> =back -X =head1 Key Codes +X + Note: B + B-B generates B-B For the keypad, use B to temporarily override Application-Keypad @@ -2203,9 +2247,9 @@ General hint: if you get compile errors, then likely your configuration hasn't been tested well. Either try with C<--enable-everything> or use -the default configuration (i.e. C<--enable-xxx> or C<--disable-xxx>). Of -course, you should always report when a combination doesn't work, so it -can be fixed. Marc Lehmann . +the default configuration (i.e. no C<--enable-xxx> or C<--disable-xxx> +switches). Of course, you should always report when a combination doesn't +work, so it can be fixed. Marc Lehmann . All @@ -2304,7 +2348,7 @@ Use the given name as default application name when reading resources. Specify --with-res-name=rxvt to replace rxvt. -=item --with-res-class=CLASS /default: URxvt) +=item --with-res-class=CLASS (default: URxvt) Use the given class as default application class when reading resources. Specify --with-res-class=Rxvt to replace @@ -2327,22 +2371,28 @@ F) at start of rxvt execution. This option requires --enable-utmp to also be specified. -=item --enable-xpm-background (default: on) +=item --enable-afterimage (default: on) -Add support for XPM background pixmaps. +Add support for libAfterImage to be used for transparency and background +images. It adds support for many file formats including JPG, PNG, +SVG, TIFF, GIF, XPM, BMP, ICO, XCF, TGA and AfterStep image XML +(L). + +This option also adds such eye candy as blending an image over the root +background, as well as dynamic scaling and bluring of background images. + +Note that with this option enabled, @@RXVT_NAME@@'s memory footprint might +increase by a few megabytes even if no extra features are used (mostly due +to third-party libraries used by libAI). Memory footprint may somewhat be +lowered if libAfterImage is configured without support for SVG. =item --enable-transparency (default: on) -Add support for inheriting parent backgrounds thus giving a fake -transparency to the term. +Add support for backgrounds, creating illusion of transparency in the term. =item --enable-fading (default: on) -Add support for fading the text when focus is lost (requires C<--enable-transparency>). - -=item --enable-tinting (default: on) - -Add support for tinting of transparent backgrounds (requires C<--enable-transparency>). +Add support for fading the text when focus is lost. =item --enable-rxvt-scroll (default: on) @@ -2356,17 +2406,6 @@ Add support for an Xterm-like scrollbar. -=item --enable-plain-scroll (default: on) - -Add support for a very unobtrusive, plain-looking scrollbar that -is the favourite of the rxvt-unicode author, having used it for -many years. - -=item --enable-ttygid (default: off) - -Change tty device setting to group "tty" - only use this if -your system uses this type of security. - =item --disable-backspace-key Removes any handling of the backspace key by us - let the X server do it. @@ -2404,10 +2443,11 @@ tripleclickwords (-tcw) settable insecure mode (-insecure) keysym remapping support - cursor blinking and underline cursor (-cb, -uc) + cursor blinking and underline cursor (-bc, -uc) XEmbed support (-embed) user-pty (-pty-fd) hold on exit (-hold) + compile in built-in block graphics skip builtin block graphics (-sbg) separate highlightcolor support (-hc) @@ -2427,16 +2467,20 @@ =item --enable-iso14755 (default: on) -Enable extended ISO 14755 support (see @@RXVT_NAME@@(1), or -F). Basic support (section 5.1) is enabled by -C<--enable-frills>, while support for 5.2, 5.3 and 5.4 is enabled with -this switch. +Enable extended ISO 14755 support (see @@RXVT_NAME@@(1)). +Basic support (section 5.1) is enabled by C<--enable-frills>, while +support for 5.2, 5.3 and 5.4 is enabled with this switch. =item --enable-keepscrolling (default: on) Add support for continual scrolling of the display when you hold the mouse button down on a scrollbar arrow. +=item --enable-selectionscrolling (default: on) + +Add support for scrolling when the selection moves to the top or +bottom of the screen. + =item --enable-mousewheel (default: on) Add support for scrolling via mouse wheel or buttons 4 & 5. @@ -2447,15 +2491,15 @@ accelerator) while the control key is held down. This option requires --enable-mousewheel to also be specified. -=item --disable-new-selection +=item --enable-smart-resize (default: off) -Remove support for mouse selection style like that of xterm. +Add smart growth/shrink behaviour when resizing. +This should keep the window corner which is closest to a corner of +the screen in a fixed position. -=item --enable-smart-resize (default: on) +=item --enable-text-blink (default: on) -Add smart growth/shrink behaviour when changing font size via hot -keys. This should keep the window corner which is closest to a corner of -the screen in a fixed position. +Add support for blinking text. =item --enable-pointer-blank (default: on) @@ -2464,14 +2508,18 @@ =item --enable-perl (default: on) Enable an embedded perl interpreter. See the B<@@RXVT_NAME@@perl(3)> -manpage (F) for more info on this feature, or the -files in F for the extensions that are installed by -default. The perl interpreter that is used can be specified via the -C environment variable when running configure. Even when compiled -in, perl will I be initialised when all extensions have been disabled +manpage for more info on this feature, or the files in F +for the extensions that are installed by default. +The perl interpreter that is used can be specified via the C +environment variable when running configure. Even when compiled in, +perl will I be initialised when all extensions have been disabled C<-pe "" --perl-ext-common "">, so it should be safe to enable from a resource standpoint. +=item --with-afterimage-config=DIR + +Look for the libAfterImage config script in DIR. + =item --with-name=NAME (default: urxvt) Set the basename for the installed binaries, resulting @@ -2491,18 +2539,6 @@ Use the X Window System (pretty much default, eh?). -=item --with-xpm-includes=DIR - -Look for the XPM includes in DIR. - -=item --with-xpm-library=DIR - -Look for the XPM library in DIR. - -=item --with-xpm - -Not needed - define via --enable-xpm-background. - =back =head1 AUTHORS