--- rxvt-unicode/doc/rxvt.7.pod 2006/01/16 15:12:48 1.85 +++ rxvt-unicode/doc/rxvt.7.pod 2013/05/06 05:37:11 1.227 @@ -18,55 +18,135 @@ This document contains the FAQ, the RXVT TECHNICAL REFERENCE documenting all escape sequences, and other background information. -The newest version of this document is -also available on the World Wide Web at -L. +The newest version of this document is also available on the World Wide Web at +L. -=head1 FREQUENTLY ASKED QUESTIONS +The main manual page for @@RXVT_NAME@@ itself is available at +L. -=over 4 +=head1 RXVT-UNICODE/URXVT FREQUENTLY ASKED QUESTIONS -=item The new selection selects pieces that are too big, how can I select -single words? -Yes. For example, if you want to select alphanumeric words, you can use -the following resource: +=head2 Meta, Features & Commandline Issues - URxvt.selection.pattern-0: ([[:word:]]+) +=head3 My question isn't answered here, can I ask a human? -If you click more than twice, the selection will be extended -more and more. +Before sending me mail, you could go to IRC: C, +channel C<#rxvt-unicode> has some rxvt-unicode enthusiasts that might be +interested in learning about new and exciting problems (but not FAQs :). -To get a selection that is very similar to the old code, try this pattern: +=head3 I use Gentoo, and I have a problem... - URxvt.selection.pattern-0: ([^"&'()*,;<=>?@[\\\\]^`{|})]+) +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. -Please also note that the I combination also -selects words like the old code. +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. -=item I don't like the new selection/popups/hotkeys/perl, how do I -change/disable it? +=head3 Does it support tabs, can I have a tabbed rxvt-unicode? -You can disable the perl extension completely by setting the -B resource to the empty string, which also keeps -rxvt-unicode from initialising perl, saving memory. +Beginning with version 7.3, there is a perl extension that implements a +simple tabbed terminal. It is installed by default, so any of these should +give you tabs: -If you only want to disable specific features, you first have to -identify which perl extension is responsible. For this, read the section -B in the @@RXVT_NAME@@perl(3) manpage. For -example, to disable the B and B, specify -this B resource: + @@URXVT_NAME@@ -pe tabbed - URxvt.perl-ext-common: default,-selection-popup,-option-popup + URxvt.perl-ext-common: default,tabbed -This will keep the default extensions, but disable the two popup -extensions. Some extensions can also be configured, for example, -scrollback search mode is triggered by B. You can move it to any -other combination either by setting the B resource: +It will also work fine with tabbing functionality of many window managers +or similar tabbing programs, and its embedding-features allow it to be +embedded into other programs, as witnessed by F or +the upcoming C perl module, which features a tabbed urxvt +(murxvt) terminal as an example embedding application. - URxvt.searchable-scrollback: CM-s +=head3 How do I know which rxvt-unicode version I'm using? + +The version number is displayed with the usage (-h). Also the escape +sequence C sets the window title to the version number. When +using the @@URXVT_NAME@@c client, the version displayed is that of the +daemon. + +=head3 Rxvt-unicode uses gobs of memory, how can I reduce that? + +Rxvt-unicode tries to obey the rule of not charging you for something you +don't use. One thing you should try is to configure out all settings that +you don't need, for example, Xft support is a resource hog by design, +when used. Compiling it out ensures that no Xft font will be loaded +accidentally when rxvt-unicode tries to find a font for your characters. + +Also, many people (me included) like large windows and even larger +scrollback buffers: Without C<--enable-unicode3>, rxvt-unicode will use +6 bytes per screen cell. For a 160x?? window this amounts to almost a +kilobyte per line. A scrollback buffer of 10000 lines will then (if full) +use 10 Megabytes of memory. With C<--enable-unicode3> it gets worse, as +rxvt-unicode then uses 8 bytes per screen cell. -=item Isn't rxvt supposed to be small? Don't all those features bloat? +=head3 How can I start @@URXVT_NAME@@d in a race-free way? + +Try C<@@URXVT_NAME@@d -f -o>, which tells @@URXVT_NAME@@d to open the +display, create the listening socket and then fork. + +=head3 How can I start @@URXVT_NAME@@d automatically when I run @@URXVT_NAME@@c? + +If you want to start @@URXVT_NAME@@d automatically whenever you run +@@URXVT_NAME@@c and the daemon isn't running yet, use this script: + + #!/bin/sh + @@URXVT_NAME@@c "$@" + if [ $? -eq 2 ]; then + @@URXVT_NAME@@d -q -o -f + @@URXVT_NAME@@c "$@" + fi + +This tries to create a new terminal, and if fails with exit status 2, +meaning it couldn't connect to the daemon, it will start the daemon and +re-run the command. Subsequent invocations of the script will re-use the +existing daemon. + +=head3 How do I distinguish whether I'm running rxvt-unicode or a regular +xterm? I need this to decide about setting colours etc. + +The original rxvt and rxvt-unicode always export the variable "COLORTERM", +so you can check and see if that is set. Note that several programs, JED, +slrn, Midnight Commander automatically check this variable to decide +whether or not to use colour. + +=head3 How do I set the correct, full IP address for the DISPLAY variable? + +If you've compiled rxvt-unicode with DISPLAY_IS_IP and have enabled +insecure mode then it is possible to use the following shell script +snippets to correctly set the display. If your version of rxvt-unicode +wasn't also compiled with ESCZ_ANSWER (as assumed in these snippets) then +the COLORTERM variable can be used to distinguish rxvt-unicode from a +regular xterm. + +Courtesy of Chuck Blake with the following shell script +snippets: + + # Bourne/Korn/POSIX family of shells: + [ ${TERM:-foo} = foo ] && TERM=xterm # assume an xterm if we don't know + if [ ${TERM:-foo} = xterm ]; then + stty -icanon -echo min 0 time 15 # see if enhanced rxvt or not + printf "\eZ" + read term_id + stty icanon echo + if [ ""${term_id} = '^[[?1;2C' -a ${DISPLAY:-foo} = foo ]; then + printf '\e[7n' # query the rxvt we are in for the DISPLAY string + read DISPLAY # set it in our local shell + fi + fi + +=head3 How do I compile the manual pages on my own? + +You need to have a recent version of perl installed as F, +one that comes with F, F and F (from +F). Then go to the doc subdirectory and enter C. + +=head3 Isn't rxvt-unicode supposed to be small? Don't all those features bloat? I often get asked about this, and I think, no, they didn't cause extra bloat. If you compare a minimal rxvt and a minimal urxvt, you can see @@ -80,9 +160,9 @@ 98398 1664 24 15695 1824 rxvt --disable-everything 188985 9048 66616 18222 1788 urxvt --disable-everything -When you C<--enable-everything> (which _is_ unfair, as this involves xft +When you C<--enable-everything> (which I unfair, as this involves xft and full locale/XIM support which are quite bloaty inside libX11 and my -libc), the two diverge, but not unreasnobaly so. +libc), the two diverge, but not unreasonably so. text data bss drs rss filename 163431 2152 24 20123 2060 rxvt --enable-everything @@ -108,7 +188,7 @@ startup time, including the hundreds of warnings it spits out), it fares extremely well *g*. -=item Why C++, isn't that unportable/bloated/uncool? +=head3 Why C++, isn't that unportable/bloated/uncool? Is this a question? :) It comes up very often. The simple answer is: I had to write it, and C++ allowed me to write and maintain it in a fraction @@ -121,7 +201,7 @@ domain sockets, which are all less portable than C++ itself. Regarding the bloat, see the above question: It's easy to write programs -in C that use gobs of memory, an certainly possible to write programs in +in C that use gobs of memory, and certainly possible to write programs in C++ that don't. C++ also often comes with large libraries, but this is not necessarily the case with GCC. Here is what rxvt links against on my system with a minimal config: @@ -135,229 +215,219 @@ 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 :) -=item Does it support tabs, can I have a tabbed rxvt-unicode? -rxvt-unicode does not directly support tabs. It will work fine with -tabbing functionality of many window managers or similar tabbing programs, -and its embedding-features allow it to be embedded into other programs, -as witnessed by F or the upcoming C perl -module, which features a tabbed urxvt (murxvt) terminal as an example -embedding application. +=head2 Rendering, Font & Look and Feel Issues -=item How do I know which rxvt-unicode version I'm using? +=head3 I can't get transparency working, what am I doing wrong? -The version number is displayed with the usage (-h). Also the escape -sequence C sets the window title to the version number. When -using the @@RXVT_NAME@@c client, the version displayed is that of the -daemon. +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. -=item I am using Debian GNU/Linux and have a problem... +Here are four ways to get transparency. B read the manpage and option +descriptions for the programs mentioned and rxvt-unicode. Really, do it! -The Debian GNU/Linux package of rxvt-unicode in sarge contains large -patches that considerably change the behaviour of rxvt-unicode. Before -reporting a bug to the original rxvt-unicode author please download and -install the genuine version (L) -and try to reproduce the problem. If you cannot, chances are that the -problems are specific to Debian GNU/Linux, in which case it should be -reported via the Debian Bug Tracking System (use C to report -the bug). +1. Use transparent mode: -For other problems that also affect the Debian package, you can and -probably should use the Debian BTS, too, because, after all, it's also a -bug in the Debian version and it serves as a reminder for other users that -might encounter the same issue. + Esetroot wallpaper.jpg + @@URXVT_NAME@@ -tr -tint red -sh 40 -=item I am maintaining rxvt-unicode for distribution/OS XXX, any recommendation? +That works. If you think it doesn't, you lack transparency and tinting +support, or you are unable to read. +This method requires that the background-setting program sets the +_XROOTPMAP_ID or ESETROOT_PMAP_ID property. Compatible programs +are Esetroot, hsetroot and feh. -You should build one binary with the default options. F -now enables most useful options, and the trend goes to making them -runtime-switchable, too, so there is usually no drawback to enbaling them, -except higher disk and possibly memory usage. The perl interpreter should -be enabled, as important functionality (menus, selection, likely more in -the future) depends on it. +2. Use a simple pixmap and emulate pseudo-transparency. This enables you +to use effects other than tinting and shading: Just shade/tint/whatever +your picture with gimp or any other tool: -You should not overwrite the C snd C resources -system-wide (except maybe with C). This will result in useful -behaviour. If your distribution aims at low memory, add an empty -C resource to the app-defaults file. This will keep the -perl interpreter disabled until the user enables it. + convert wallpaper.jpg -blur 20x20 -modulate 30 background.jpg + @@URXVT_NAME@@ -pixmap "background.jpg;:root" -If you can/want build more binaries, I recommend building a minimal -one with C<--disable-everything> (very useful) and a maximal one with -C<--enable-everything> (less useful, it will be very big due to a lot of -encodings built-in that increase download times and are rarely used). +That works. If you think it doesn't, you lack GDK-PixBuf support, or you +are unable to read. -=item I need to make it setuid/setgid to support utmp/ptys on my OS, is this safe? +3. Use an ARGB visual: -Likely not. While I honestly try to make it secure, and am probably not -bad at it, I think it is simply unreasonable to expect all of freetype -+ fontconfig + xft + xlib + perl + ... + rxvt-unicode itself to all be -secure. Also, rxvt-unicode disables some options when it detects that it -runs setuid or setgid, which is not nice. Besides, with the embedded perl -interpreter the possibility for security problems easily multiplies. - -Elevated privileges are only required for utmp and pty operations on some -systems (for example, GNU/Linux doesn't need any extra privileges for -ptys, but some need it for utmp support). It is planned to mvoe this into -a forked handler process, but this is not yet done. - -So, while setuid/setgid operation is supported and not a problem on your -typical single-user-no-other-logins unix desktop, always remember that -its an awful lot of code, most of which isn't checked for security issues -regularly. + @@URXVT_NAME@@ -depth 32 -fg grey90 -bg rgba:0000/0000/4444/cccc -=item When I log-in to another system it tells me about missing terminfo data? +This requires XFT support, and the support of your X-server. If that +doesn't work for you, blame Xorg and Keith Packard. ARGB visuals aren't +there yet, no matter what they claim. Rxvt-Unicode contains the necessary +bugfixes and workarounds for Xft and Xlib to make it work, but that +doesn't mean that your WM has the required kludges in place. -The terminal description used by rxvt-unicode is not as widely available -as that for xterm, or even rxvt (for which the same problem often arises). +4. Use xcompmgr and let it do the job: -The correct solution for this problem is to install the terminfo, this can -be done like this (with ncurses' infocmp): + xprop -frame -f _NET_WM_WINDOW_OPACITY 32c \ + -set _NET_WM_WINDOW_OPACITY 0xc0000000 - REMOTE=remotesystem.domain - infocmp rxvt-unicode | ssh $REMOTE "cat >/tmp/ti && tic /tmp/ti" +Then click on a window you want to make transparent. Replace C<0xc0000000> +by other values to change the degree of opacity. If it doesn't work and +your server crashes, you got to keep the pieces. -... or by installing rxvt-unicode normally on the remote system, +=head3 Why does rxvt-unicode sometimes leave pixel droppings? -If you cannot or do not want to do this, then you can simply set -C or even C, and live with the small number of -problems arising, which includes wrong keymapping, less and different -colours and some refresh errors in fullscreen applications. It's a nice -quick-and-dirty workaround for rare cases, though. +Most fonts were not designed for terminal use, which means that character +size varies a lot. A font that is otherwise fine for terminal use might +contain some characters that are simply too wide. Rxvt-unicode will avoid +these characters. For characters that are just "a bit" too wide a special +"careful" rendering mode is used that redraws adjacent characters. -If you always want to do this (and are fine with the consequences) you -can either recompile rxvt-unicode with the desired TERM value or use a -resource to set it: +All of this requires that fonts do not lie about character sizes, +however: Xft fonts often draw glyphs larger than their acclaimed bounding +box, and rxvt-unicode has no way of detecting this (the correct way is to +ask for the character bounding box, which unfortunately is wrong in these +cases). - URxvt.termName: rxvt +It's not clear (to me at least), whether this is a bug in Xft, freetype, +or the respective font. If you encounter this problem you might try using +the C<-lsp> option to give the font more height. If that doesn't work, you +might be forced to use a different font. -If you don't plan to use B (quite common...) you could also replace -the rxvt terminfo file with the rxvt-unicode one. +All of this is not a problem when using X11 core fonts, as their bounding +box data is correct. -=item C outputs some error when compiling the terminfo entry. +=head3 How can I keep rxvt-unicode from using reverse video so much? -Most likely it's the empty definition for C. Just replace it by -C and try again. +First of all, make sure you are running with the right terminal settings +(C), which will get rid of most of these effects. Then +make sure you have specified colours for italic and bold, as otherwise +rxvt-unicode might use reverse video to simulate the effect: -=item C's readline does not work correctly under @@RXVT_NAME@@. + URxvt.colorBD: white + URxvt.colorIT: green -=item I need a termcap file entry. +=head3 Some programs assume totally weird colours (red instead of blue), how can I fix that? -One reason you might want this is that some distributions or operating -systems still compile some programs using the long-obsoleted termcap -library (Fedora Core's bash is one example) and rely on a termcap entry -for C. +For some unexplainable reason, some rare programs assume a very weird +colour palette when confronted with a terminal with more than the standard +8 colours (rxvt-unicode supports 88). The right fix is, of course, to fix +these programs not to assume non-ISO colours without very good reasons. -You could use rxvt's termcap entry with resonable results in many cases. -You can also create a termcap entry by using terminfo's infocmp program -like this: +In the meantime, you can either edit your C terminfo +definition to only claim 8 colour support or use C, which will +fix colours but keep you from using other rxvt-unicode features. - infocmp -C rxvt-unicode +=head3 Can I switch the fonts at runtime? -Or you could use this termcap entry, generated by the command above: +Yes, using an escape sequence. Try something like this, which has the same +effect as using the C<-fn> switch, and takes effect immediately: - 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: + printf '\33]50;%s\007' "9x15bold,xft:Kochi Gothic" -=item Why does C no longer have coloured output? +This is useful if you e.g. work primarily with japanese (and prefer a +japanese font), but you have to switch to chinese temporarily, where +japanese fonts would only be in your way. -The C in the GNU coreutils unfortunately doesn't use terminfo to -decide wether a terminal has colour, but uses it's own configuration -file. Needless to say, C is not in it's default file (among -with most other terminals supporting colour). Either add: +You can think of this as a kind of manual ISO-2022 switching. - TERM rxvt-unicode +=head3 Why do italic characters look as if clipped? -to C or simply add: +Many fonts have difficulties with italic characters and hinting. For +example, the otherwise very nicely hinted font C completely fails in its italic face. A workaround might be to +enable freetype autohinting, i.e. like this: - alias ls='ls --color=auto' + URxvt.italicFont: xft:Bitstream Vera Sans Mono:italic:autohint=true + URxvt.boldItalicFont: xft:Bitstream Vera Sans Mono:bold:italic:autohint=true -to your C<.profile> or C<.bashrc>. +=head3 Can I speed up Xft rendering somehow? -=item Why doesn't vim/emacs etc. use the 88 colour mode? +Yes, the most obvious way to speed it up is to avoid Xft entirely, as +it is simply slow. If you still want Xft fonts you might try to disable +antialiasing (by appending C<:antialias=false>), which saves lots of +memory and also speeds up rendering considerably. -=item Why doesn't vim/emacs etc. make use of italic? +=head3 Rxvt-unicode doesn't seem to anti-alias its fonts, what is wrong? -=item Why are the secondary screen-related options not working properly? +Rxvt-unicode will use whatever you specify as a font. If it needs to +fall back to its default font search list it will prefer X11 core +fonts, because they are small and fast, and then use Xft fonts. It has +antialiasing disabled for most of them, because the author thinks they +look best that way. -Make sure you are using C. Some pre-packaged -distributions (most notably Debian GNU/Linux) break rxvt-unicode -by setting C to C, which doesn't have these extra -features. Unfortunately, some of these (most notably, again, Debian -GNU/Linux) furthermore fail to even install the C terminfo -file, so you will need to install it on your own (See the question B on -how to do this). +If you want antialiasing, you have to specify the fonts manually. -=item My numerical keypad acts weird and generates differing output? +=head3 What's with this bold/blink stuff? -Some Debian GNUL/Linux users seem to have this problem, although no -specific details were reported so far. It is possible that this is caused -by the wrong C setting, although the details of wether and how -this can happen are unknown, as C should offer a compatible -keymap. See the answer to the previous question, and please report if that -helped. +If no bold colour is set via C, bold will invert text using the +standard foreground colour. -=item Rxvt-unicode does not seem to understand the selected encoding? +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. -=item Unicode does not seem to work? +On ANSI colours, bold/blink attributes are used to set high-intensity +foreground/background colours. -If you encounter strange problems like typing an accented character but -getting two unrelated other characters or similar, or if program output is -subtly garbled, then you should check your locale settings. +color0-7 are the low-intensity colours. -Rxvt-unicode must be started with the same C setting as the -programs. Often rxvt-unicode is started in the C locale, while the -login script running within the rxvt-unicode window changes the locale to -something else, e.g. C. Needless to say, this is not going to work. +color8-15 are the corresponding high-intensity colours. -The best thing is to fix your startup environment, as you will likely run -into other problems. If nothing works you can try this in your .profile. +=head3 I don't like the screen colours. How do I change them? - printf '\e]701;%s\007' "$LC_CTYPE" +You can change the screen colours at run-time using F<~/.Xdefaults> +resources (or as long-options). -If this doesn't work, then maybe you use a C specification not -supported on your systems. Some systems have a C command which -displays this (also, C can be used to check locale settings, as -it will complain loudly if it cannot set the locale). If it displays something -like: +Here are values that are supposed to resemble a VGA screen, +including the murky brown that passes for low-intensity yellow: - locale: Cannot set LC_CTYPE to default locale: ... + URxvt.color0: #000000 + URxvt.color1: #A80000 + URxvt.color2: #00A800 + URxvt.color3: #A8A800 + URxvt.color4: #0000A8 + URxvt.color5: #A800A8 + URxvt.color6: #00A8A8 + URxvt.color7: #A8A8A8 -Then the locale you specified is not supported on your system. + URxvt.color8: #000054 + URxvt.color9: #FF0054 + URxvt.color10: #00FF54 + URxvt.color11: #FFFF54 + URxvt.color12: #0000FF + URxvt.color13: #FF00FF + URxvt.color14: #00FFFF + URxvt.color15: #FFFFFF -If nothing works and you are sure that everything is set correctly then -you will need to remember a little known fact: Some programs just don't -support locales :( +And here is a more complete set of non-standard colours. -=item Why do some characters look so much different than others? + URxvt.cursorColor: #dc74d1 + URxvt.pointerColor: #dc74d1 + URxvt.background: #0e0e0e + URxvt.foreground: #4ad5e1 + URxvt.color0: #000000 + URxvt.color8: #8b8f93 + URxvt.color1: #dc74d1 + URxvt.color9: #dc74d1 + URxvt.color2: #0eb8c7 + URxvt.color10: #0eb8c7 + URxvt.color3: #dfe37e + URxvt.color11: #dfe37e + URxvt.color5: #9e88f0 + URxvt.color13: #9e88f0 + URxvt.color6: #73f7ff + URxvt.color14: #73f7ff + URxvt.color7: #e1dddd + URxvt.color15: #e1dddd + +They have been described (not by me) as "pretty girly". + +=head3 Why do some characters look so much different than others? + +See next entry. -=item How does rxvt-unicode choose fonts? +=head3 How does rxvt-unicode choose fonts? Most fonts do not contain the full range of Unicode, which is fine. Chances are that the font you (or the admin/package maintainer of @@ -374,7 +444,7 @@ In that case, select a font of your taste and add it to the font list, e.g.: - @@RXVT_NAME@@ -fn basefont,font2,font3... + @@URXVT_NAME@@ -fn basefont,font2,font3... When rxvt-unicode sees a character, it will first look at the base font. If the base font does not contain the character, it will go to the @@ -385,7 +455,7 @@ font, as the base font defines the terminal character cell size, which must be the same due to the way terminals work. -=item Why do some chinese characters look so different than others? +=head3 Why do some chinese characters look so different than others? This is because there is a difference between script and language -- rxvt-unicode does not know which language the text that is output is, @@ -410,37 +480,80 @@ Until then, you might get away with switching fonts at runtime (see L later in this document). -=item Why does rxvt-unicode sometimes leave pixel droppings? +=head3 How can I make mplayer display video correctly? -Most fonts were not designed for terminal use, which means that character -size varies a lot. A font that is otherwise fine for terminal use might -contain some characters that are simply too wide. Rxvt-unicode will avoid -these characters. For characters that are just "a bit" too wide a special -"careful" rendering mode is used that redraws adjacent characters. +We are working on it, in the meantime, as a workaround, use something like: -All of this requires that fonts do not lie about character sizes, -however: Xft fonts often draw glyphs larger than their acclaimed bounding -box, and rxvt-unicode has no way of detecting this (the correct way is to -ask for the character bounding box, which unfortunately is wrong in these -cases). + @@URXVT_NAME@@ -b 600 -geometry 20x1 -e sh -c 'mplayer -wid $WINDOWID file...' -It's not clear (to me at least), wether this is a bug in Xft, freetype, -or the respective font. If you encounter this problem you might try using -the C<-lsp> option to give the font more height. If that doesn't work, you -might be forced to use a different font. -All of this is not a problem when using X11 core fonts, as their bounding -box data is correct. +=head2 Keyboard, Mouse & User Interaction + +=head3 The new selection selects pieces that are too big, how can I select single words? + +If you want to select e.g. alphanumeric words, you can use the following +setting: + + URxvt.selection.pattern-0: ([[:word:]]+) + +If you click more than twice, the selection will be extended +more and more. + +To get a selection that is very similar to the old code, try this pattern: + + URxvt.selection.pattern-0: ([^"&'()*,;<=>?@[\\\\]^`{|})]+) -=item On Solaris 9, many line-drawing characters are too wide. +Please also note that the I combination also +selects words like the old code. -Seems to be a known bug, read -L. Some people use the -following ugly workaround to get non-double-wide-characters working: +=head3 I don't like the new selection/popups/hotkeys/perl, how do I change/disable it? - #define wcwidth(x) wcwidth(x) > 1 ? 1 : wcwidth(x) +You can disable the perl extension completely by setting the +B resource to the empty string, which also keeps +rxvt-unicode from initialising perl, saving memory. -=item My Compose (Multi_key) key is no longer working. +If you only want to disable specific features, you first have to +identify which perl extension is responsible. For this, read the section +B in the @@URXVT_NAME@@perl(3) manpage. For +example, to disable the B and B, specify +this B resource: + + URxvt.perl-ext-common: default,-selection-popup,-option-popup + +This will keep the default extensions, but disable the two popup +extensions. Some extensions can also be configured, for example, +scrollback search mode is triggered by B. You can move it to any +other combination either by setting the B resource: + + URxvt.searchable-scrollback: CM-s + +=head3 The cursor moves when selecting text in the current input line, how do I switch this off? + +See next entry. + +=head3 During rlogin/ssh/telnet/etc. sessions, clicking near the cursor outputs strange escape sequences, how do I fix this? + +These are caused by the C perl extension. Under normal +circumstances, it will move your cursor around when you click into the +line that contains it. It tries hard not to do this at the wrong moment, +but when running a program that doesn't parse cursor movements or in some +cases during rlogin sessions, it fails to detect this properly. + +You can permanently switch this feature off by disabling the C +extension: + + URxvt.perl-ext-common: default,-readline + +=head3 My numerical keypad acts weird and generates differing output? + +Some Debian GNUL/Linux users seem to have this problem, although no +specific details were reported so far. It is possible that this is caused +by the wrong C setting, although the details of whether and how +this can happen are unknown, as C should offer a compatible +keymap. See the answer to the previous question, and please report if that +helped. + +=head3 My Compose (Multi_key) key is no longer working. The most common causes for this are that either your locale is not set correctly, or you specified a B that is not supported by @@ -452,7 +565,11 @@ In this case either do not specify a B or specify more than one pre-edit style, such as B. -=item I cannot type C to get an ASCII NUL character due to ISO 14755 +If it still doesn't work, then maybe your input method doesn't support +compose sequences - to fall back to the built-in one, make sure you don't +specify an input method via C<-im> or C. + +=head3 I cannot type C to get an ASCII NUL character due to ISO 14755 Either try C alone (it often is mapped to ASCII NUL even on international keyboards) or simply use ISO 14755 support to your @@ -460,80 +577,405 @@ codes, too, such as C to type the default telnet escape character and so on. -=item How can I keep rxvt-unicode from using reverse video so much? +=head3 Mouse cut/paste suddenly no longer works. -First of all, make sure you are running with the right terminal settings -(C), which will get rid of most of these effects. Then -make sure you have specified colours for italic and bold, as otherwise -rxvt-unicode might use reverse video to simulate the effect: +Make sure that mouse reporting is actually turned off since killing +some editors prematurely may leave it active. I've +heard that tcsh may use mouse reporting unless it is otherwise specified. A +quick check is to see if cut/paste works when the Alt or Shift keys are +pressed. - URxvt.colorBD: white - URxvt.colorIT: green +=head3 What's with the strange Backspace/Delete key behaviour? -=item Some programs assume totally weird colours (red instead of blue), how can I fix that? +Assuming that the physical Backspace key corresponds to the +Backspace keysym (not likely for Linux ... see the following +question) there are two standard values that can be used for +Backspace: C<^H> and C<^?>. -For some unexplainable reason, some rare programs assume a very weird -colour palette when confronted with a terminal with more than the standard -8 colours (rxvt-unicode supports 88). The right fix is, of course, to fix -these programs not to assume non-ISO colours without very good reasons. +Historically, either value is correct, but rxvt-unicode adopts the debian +policy of using C<^?> when unsure, because it's the one and only correct +choice :). -In the meantime, you can either edit your C terminfo -definition to only claim 8 colour support or use C, which will -fix colours but keep you from using other rxvt-unicode features. +It is possible to toggle between C<^H> and C<^?> with the DECBKM +private mode: -=item I am on FreeBSD and rxvt-unicode does not seem to work at all. + # use Backspace = ^H + $ stty erase ^H + $ printf "\e[?67h" -Rxvt-unicode requires the symbol C<__STDC_ISO_10646__> to be defined -in your compile environment, or an implementation that implements it, -wether it defines the symbol or not. C<__STDC_ISO_10646__> requires that -B is represented as unicode. + # use Backspace = ^? + $ stty erase ^? + $ printf "\e[?67l" -As you might have guessed, FreeBSD does neither define this symobl nor -does it support it. Instead, it uses it's own internal representation of -B. This is, of course, completely fine with respect to standards. +This helps satisfy some of the Backspace discrepancies that occur, but +if you use Backspace = C<^H>, make sure that the termcap/terminfo value +properly reflects that. -However, that means rxvt-unicode only works in C, C and -C locales under FreeBSD (which all use Unicode as B. +The Delete key is a another casualty of the ill-defined Backspace problem. +To avoid confusion between the Backspace and Delete keys, the Delete +key has been assigned an escape sequence to match the vt100 for Execute +(C) and is in the supplied termcap/terminfo. -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) -representation of B makes it impossible to convert between -B (as used by X11 and your applications) and any other encoding -without implementing OS-specific-wrappers for each and every locale. There -simply are no APIs to convert B into anything except the current -locale encoding. +Some other Backspace problems: -Some applications (such as the formidable B) work around this -by carrying their own replacement functions for character set handling -with them, and either implementing OS-dependent hacks or doing multiple -conversions (which is slow and unreliable in case the OS implements -encodings slightly different than the terminal emulator). +some editors use termcap/terminfo, +some editors (vim I'm told) expect Backspace = ^H, +GNU Emacs (and Emacs-like editors) use ^H for help. -The rxvt-unicode author insists that the right way to fix this is in the -system libraries once and for all, instead of forcing every app to carry -complete replacements for them :) +Perhaps someday this will all be resolved in a consistent manner. -=item I use Solaris 9 and it doesn't compile/work/etc. +=head3 I don't like the key-bindings. How do I change them? -Try the diff in F as a base. It fixes the worst -problems with C and a compile problem. +There are some compile-time selections available via configure. Unless +you have run "configure" with the C<--disable-resources> option you can +use the `keysym' resource to alter the keystrings associated with keysyms. -=item How can I use rxvt-unicode under cygwin? +Here's an example for a URxvt session started using C<@@URXVT_NAME@@ -name URxvt> -rxvt-unicode should compile and run out of the box on cygwin, using -the X11 libraries that come with cygwin. libW11 emulation is no -longer supported (and makes no sense, either, as it only supported a -single font). I recommend starting the X-server in C<-multiwindow> or -C<-rootless> mode instead, which will result in similar look&feel as the -old libW11 emulation. + URxvt.keysym.Prior: \033[5~ + URxvt.keysym.Next: \033[6~ + URxvt.keysym.Home: \033[7~ + URxvt.keysym.End: \033[8~ + URxvt.keysym.Up: \033[A + URxvt.keysym.Down: \033[B + URxvt.keysym.Right: \033[C + URxvt.keysym.Left: \033[D -At the time of this writing, cygwin didn't seem to support any multi-byte -encodings (you might try C), so you are likely limited -to 8-bit encodings. +See some more examples in the documentation for the B resource. + +=head3 I'm using keyboard model XXX that has extra Prior/Next/Insert keys. How do I make use of them? For example, the Sun Keyboard type 4 has the following map + + KP_Insert == Insert + F22 == Print + F27 == Home + F29 == Prior + F33 == End + F35 == Next + +Rather than have rxvt-unicode try to accommodate all the various possible +keyboard mappings, it is better to use `xmodmap' to remap the keys as +required for your particular machine. + + +=head2 Terminal Configuration + +=head3 Can I see a typical configuration? + +The default configuration tries to be xterm-like, which I don't like that +much, but it's least surprise to regular users. + +As a rxvt or rxvt-unicode user, you are practically supposed to invest +time into customising your terminal. To get you started, here is the +author's .Xdefaults entries, with comments on what they do. It's certainly +not I, but what's typical... + + URxvt.cutchars: "()*,<>[]{}|' + URxvt.print-pipe: cat >/tmp/xxx + +These are just for testing stuff. + + URxvt.imLocale: ja_JP.UTF-8 + URxvt.preeditType: OnTheSpot,None + +This tells rxvt-unicode to use a special locale when communicating with +the X Input Method, and also tells it to only use the OnTheSpot pre-edit +type, which requires the C perl extension but rewards me +with correct-looking fonts. + + URxvt.perl-lib: /root/lib/urxvt + URxvt.perl-ext-common: default,selection-autotransform,selection-pastebin,xim-onthespot,remote-clipboard + URxvt.selection.pattern-0: ( at .*? line \\d+) + URxvt.selection.pattern-1: ^(/[^:]+):\ + URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/ + URxvt.selection-autotransform.1: s/^ at (.*?) line (\\d+)$/:e \\Q$1\\E\\x0d:$2\\x0d/ + +This is my perl configuration. The first two set the perl library +directory and also tells urxvt to use a large number of extensions. I +develop for myself mostly, so I actually use most of the extensions I +write. + +The selection stuff mainly makes the selection perl-error-message aware +and tells it to convert perl error messages into vi-commands to load the +relevant file and go to the error line number. + + URxvt.scrollstyle: plain + URxvt.secondaryScroll: true + +As the documentation says: plain is the preferred scrollbar for the +author. The C configures urxvt to scroll in full-screen +apps, like screen, so lines scrolled out of screen end up in urxvt's +scrollback buffer. + + URxvt.background: #000000 + URxvt.foreground: gray90 + URxvt.color7: gray90 + URxvt.colorBD: #ffffff + URxvt.cursorColor: #e0e080 + URxvt.throughColor: #8080f0 + URxvt.highlightColor: #f0f0f0 + +Some colours. Not sure which ones are being used or even non-defaults, but +these are in my .Xdefaults. Most notably, they set foreground/background +to light gray/black, and also make sure that the colour 7 matches the +default foreground colour. + + URxvt.underlineColor: yellow + +Another colour, makes underline lines look different. Sometimes hurts, but +is mostly a nice effect. + + URxvt.geometry: 154x36 + URxvt.loginShell: false + URxvt.meta: ignore + URxvt.utmpInhibit: true + +Uh, well, should be mostly self-explanatory. By specifying some defaults +manually, I can quickly switch them for testing. + + URxvt.saveLines: 8192 + +A large scrollback buffer is essential. Really. + + URxvt.mapAlert: true + +The only case I use it is for my IRC window, which I like to keep +iconified till people msg me (which beeps). + + URxvt.visualBell: true + +The audible bell is often annoying, especially when in a crowd. + + URxvt.insecure: true + +Please don't hack my mutt! Ooops... + + URxvt.pastableTabs: false + +I once thought this is a great idea. + + urxvt.font: 9x15bold,\ + -misc-fixed-bold-r-normal--15-140-75-75-c-90-iso10646-1,\ + -misc-fixed-medium-r-normal--15-140-75-75-c-90-iso10646-1, \ + [codeset=JISX0208]xft:Kochi Gothic, \ + xft:Bitstream Vera Sans Mono:autohint=true, \ + xft:Code2000:antialias=false + urxvt.boldFont: -xos4-terminus-bold-r-normal--14-140-72-72-c-80-iso8859-15 + urxvt.italicFont: xft:Bitstream Vera Sans Mono:italic:autohint=true + urxvt.boldItalicFont: xft:Bitstream Vera Sans Mono:bold:italic:autohint=true + +I wrote rxvt-unicode to be able to specify fonts exactly. So don't be +overwhelmed. A special note: the C<9x15bold> mentioned above is actually +the version from XFree-3.3, as XFree-4 replaced it by a totally different +font (different glyphs for C<;> and many other harmless characters), +while the second font is actually the C<9x15bold> from XFree4/XOrg. The +bold version has less chars than the medium version, so I use it for rare +characters, too. When editing sources with vim, I use italic for comments +and other stuff, which looks quite good with Bitstream Vera anti-aliased. + +Terminus is a quite bad font (many very wrong glyphs), but for most of my +purposes, it works, and gives a different look, as my normal (Non-bold) +font is already bold, and I want to see a difference between bold and +normal fonts. + +Please note that I used the C instance name and not the C +class name. That is because I use different configs for different purposes, +for example, my IRC window is started with C<-name IRC>, and uses these +defaults: + + IRC*title: IRC + IRC*geometry: 87x12+535+542 + IRC*saveLines: 0 + IRC*mapAlert: true + IRC*font: suxuseuro + IRC*boldFont: suxuseuro + IRC*colorBD: white + 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 +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. + +The above is all in my C<.Xdefaults> (I don't use C<.Xresources> nor +C). I also have some resources in a separate C<.Xdefaults-hostname> +file for different hosts, for example, on my main desktop, I use: + + URxvt.keysym.C-M-q: command:\033[3;5;5t + URxvt.keysym.C-M-y: command:\033[3;5;606t + URxvt.keysym.C-M-e: command:\033[3;1605;5t + URxvt.keysym.C-M-c: command:\033[3;1605;606t + URxvt.keysym.C-M-p: perl:test + +The first for keysym definitions allow me to quickly bring some windows +in the layout I like most. Ion users might start laughing but will stop +immediately when I tell them that I use my own Fvwm2 module for much the +same effect as Ion provides, and I only very rarely use the above key +combinations :-> + +=head3 Why doesn't rxvt-unicode read my resources? + +Well, why, indeed? It does, in a way very similar to other X +applications. Most importantly, this means that if you or your OS loads +resources into the X display (the right way to do it), rxvt-unicode will +ignore any resource files in your home directory. It will only read +F<$HOME/.Xdefaults> when no resources are attached to the display. + +If you have or use an F<$HOME/.Xresources> file, chances are that +resources are loaded into your X-server. In this case, you have to +re-login after every change (or run F). + +Also consider the form resources have to use: + + URxvt.resource: value + +If you want to use another form (there are lots of different ways of +specifying resources), make sure you understand whether and why it +works. If unsure, use the form above. + +=head3 When I log-in to another system it tells me about missing terminfo data? + +The terminal description used by rxvt-unicode is not as widely available +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 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" + +One some systems you might need to set C<$TERMINFO> to the full path of +F<$HOME/.terminfo> for this to work. Debian systems have a broken tic +which will not be able to overwrite the existing rxvt-unicode terminfo +entry - you might have to manually delete all traces of F +from F. + +If you cannot or do not want to do this, then you can simply set +C or even C, and live with the small number of +problems arising, which includes wrong keymapping, less and different +colours and some refresh errors in fullscreen applications. It's a nice +quick-and-dirty workaround for rare cases, though. + +If you always want to do this (and are fine with the consequences) you +can either recompile rxvt-unicode with the desired TERM value or use a +resource to set it: + + URxvt.termName: rxvt -=item How does rxvt-unicode determine the encoding to use? +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 +C and try again. + +=head3 C's readline does not work correctly under @@URXVT_NAME@@. + +See next entry. + +=head3 I need a termcap file entry. + +One reason you might want this is that some distributions or operating +systems still compile some programs using the long-obsoleted termcap +library (Fedora Core's bash is one example) and rely on a termcap entry +for C. + +You could use rxvt's termcap entry with reasonable results in many cases. +You can also create a termcap entry by using terminfo's infocmp program +like this: + + infocmp -C rxvt-unicode + +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? + +The C in the GNU coreutils unfortunately doesn't use terminfo to +decide whether a terminal has colour, but uses its own configuration +file. Needless to say, C is not in its default file (among +with most other terminals supporting colour). Either add: + + TERM rxvt-unicode + +to C or simply add: + + alias ls='ls --color=auto' + +to your C<.profile> or C<.bashrc>. + +=head3 Why doesn't vim/emacs etc. use the 88 colour mode? + +See next entry. + +=head3 Why doesn't vim/emacs etc. make use of italic? + +See next entry. + +=head3 Why are the secondary screen-related options not working properly? + +Make sure you are using C. Some pre-packaged +distributions (most notably Debian GNU/Linux) break rxvt-unicode +by setting C to C, which doesn't have these extra +features. Unfortunately, some of these (most notably, again, Debian +GNU/Linux) furthermore fail to even install the C terminfo +file, so you will need to install it on your own (See the question B on +how to do this). + + +=head2 Encoding / Locale / Input Method Issues -=item Is there an option to switch encodings? +=head3 Rxvt-unicode does not seem to understand the selected encoding? + +See next entry. + +=head3 Unicode does not seem to work? + +If you encounter strange problems like typing an accented character but +getting two unrelated other characters or similar, or if program output is +subtly garbled, then you should check your locale settings. + +Rxvt-unicode must be started with the same C setting as the +programs running in it. Often rxvt-unicode is started in the C locale, +while the login script running within the rxvt-unicode window changes the +locale to something else, e.g. C. Needless to say, this is +not going to work, and is the most common cause for problems. + +The best thing is to fix your startup environment, as you will likely run +into other problems. If nothing works you can try this in your .profile. + + printf '\33]701;%s\007' "$LC_CTYPE" # $LANG or $LC_ALL are worth a try, too + +If this doesn't work, then maybe you use a C specification not +supported on your systems. Some systems have a C command which +displays this (also, C can be used to check locale settings, as +it will complain loudly if it cannot set the locale). If it displays something +like: + + locale: Cannot set LC_CTYPE to default locale: ... + +Then the locale you specified is not supported on your system. + +If nothing works and you are sure that everything is set correctly then +you will need to remember a little known fact: Some programs just don't +support locales :( + +=head3 How does rxvt-unicode determine the encoding to use? + +See next entry. + +=head3 Is there an option to switch encodings? Unlike some other terminals, rxvt-unicode has no encoding switch, and no specific "utf-8" mode, such as xterm. In fact, it doesn't even know about @@ -544,7 +986,7 @@ applications so everybody agrees on character properties such as width and code number. This mechanism is the I. Applications not using that info will have problems (for example, C gets the width of -characters wrong as it uses it's own, locale-independent table under all +characters wrong as it uses its own, locale-independent table under all locales). Rxvt-unicode uses the C locale category to select encoding. All @@ -568,12 +1010,12 @@ If you want to use a specific encoding you have to make sure you start rxvt-unicode with the correct C category. -=item Can I switch locales at runtime? +=head3 Can I switch locales at runtime? Yes, using an escape sequence. Try something like this, which sets rxvt-unicode's idea of C. - printf '\e]701;%s\007' ja_JP.SJIS + printf '\33]701;%s\007' ja_JP.SJIS See also the previous answer. @@ -582,38 +1024,46 @@ (e.g. UTF-8). For example, I use this script to start C, which first switches to a locale supported by xjdic and back later: - printf '\e]701;%s\007' ja_JP.SJIS + printf '\33]701;%s\007' ja_JP.SJIS xjdic -js - printf '\e]701;%s\007' de_DE.UTF-8 + printf '\33]701;%s\007' de_DE.UTF-8 You can also use xterm's C program, which usually works fine, except for some locales where character width differs between program- and rxvt-unicode-locales. -=item Can I switch the fonts at runtime? +=head3 I have problems getting my input method working. -Yes, using an escape sequence. Try something like this, which has the same -effect as using the C<-fn> switch, and takes effect immediately: +Try a search engine, as this is slightly different for every input method server. - printf '\e]50;%s\007' "9x15bold,xft:Kochi Gothic" +Here is a checklist: -This is useful if you e.g. work primarily with japanese (and prefer a -japanese font), but you have to switch to chinese temporarily, where -japanese fonts would only be in your way. +=over 4 -You can think of this as a kind of manual ISO-2022 switching. +=item - Make sure your locale I the imLocale are supported on your OS. -=item Why do italic characters look as if clipped? +Try C or check the documentation for your OS. -Many fonts have difficulties with italic characters and hinting. For -example, the otherwise very nicely hinted font C completely fails in it's italic face. A workaround might be to -enable freetype autohinting, i.e. like this: +=item - Make sure your locale or imLocale matches a locale supported by your XIM. - URxvt.italicFont: xft:Bitstream Vera Sans Mono:italic:autohint=true - URxvt.boldItalicFont: xft:Bitstream Vera Sans Mono:bold:italic:autohint=true +For example, B does not support UTF-8 locales, you should use +C or equivalent. + +=item - Make sure your XIM server is actually running. -=item My input method wants but I want UTF-8, what can I do? +=item - Make sure the C environment variable is set correctly when I rxvt-unicode. + +When you want to use e.g. B, it must be set to +C<@im=kinput2>. For B, use C<@im=SCIM>. You can see what input +method servers are running with this command: + + xprop -root XIM_SERVERS + +=item + +=back + +=head3 My input method wants but I want UTF-8, what can I do? You can specify separate locales for the input method and the rest of the terminal, using the resource C: @@ -621,11 +1071,11 @@ URxvt.imlocale: ja_JP.EUC-JP Now you can start your terminal with C and still -use your input method. Please note, however, that you will not be able to -input characters outside C in a normal way then, as your input -method limits you. +use your input method. Please note, however, that, depending on your Xlib +version, you may not be able to input characters outside C in a +normal way then, as your input method limits you. -=item Rxvt-unicode crashes when the X Input Method changes or exits. +=head3 Rxvt-unicode crashes when the X Input Method changes or exits. Unfortunately, this is unavoidable, as the XIM protocol is racy by design. Applications can avoid some crashes at the expense of memory @@ -636,281 +1086,134 @@ So the only workaround is not to kill your Input Method Servers. -=item Rxvt-unicode uses gobs of memory, how can I reduce that? -Rxvt-unicode tries to obey the rule of not charging you for something you -don't use. One thing you should try is to configure out all settings that -you don't need, for example, Xft support is a resource hog by design, -when used. Compiling it out ensures that no Xft font will be loaded -accidentally when rxvt-unicode tries to find a font for your characters. +=head2 Operating Systems / Package Maintaining -Also, many people (me included) like large windows and even larger -scrollback buffers: Without C<--enable-unicode3>, rxvt-unicode will use -6 bytes per screen cell. For a 160x?? window this amounts to almost a -kilobyte per line. A scrollback buffer of 10000 lines will then (if full) -use 10 Megabytes of memory. With C<--enable-unicode3> it gets worse, as -rxvt-unicode then uses 8 bytes per screen cell. - -=item Can I speed up Xft rendering somehow? - -Yes, the most obvious way to speed it up is to avoid Xft entirely, as -it is simply slow. If you still want Xft fonts you might try to disable -antialiasing (by appending C<:antialias=false>), which saves lots of -memory and also speeds up rendering considerably. - -=item Rxvt-unicode doesn't seem to anti-alias its fonts, what is wrong? - -Rxvt-unicode will use whatever you specify as a font. If it needs to -fall back to it's default font search list it will prefer X11 core -fonts, because they are small and fast, and then use Xft fonts. It has -antialiasing disabled for most of them, because the author thinks they -look best that way. - -If you want antialiasing, you have to specify the fonts manually. - -=item Mouse cut/paste suddenly no longer works. - -Make sure that mouse reporting is actually turned off since killing -some editors prematurely may leave the mouse in mouse report mode. I've -heard that tcsh may use mouse reporting unless it otherwise specified. A -quick check is to see if cut/paste works when the Alt or Shift keys are -depressed. - -=item What's with this bold/blink stuff? - -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. - -On ANSI colours, bold/blink attributes are used to set high-intensity -foreground/background colors. - -color0-7 are the low-intensity colors. - -color8-15 are the corresponding high-intensity colors. - -=item I don't like the screen colors. How do I change them? - -You can change the screen colors at run-time using F<~/.Xdefaults> -resources (or as long-options). - -Here are values that are supposed to resemble a VGA screen, -including the murky brown that passes for low-intensity yellow: - - URxvt.color0: #000000 - URxvt.color1: #A80000 - URxvt.color2: #00A800 - URxvt.color3: #A8A800 - URxvt.color4: #0000A8 - URxvt.color5: #A800A8 - URxvt.color6: #00A8A8 - URxvt.color7: #A8A8A8 - - URxvt.color8: #000054 - URxvt.color9: #FF0054 - URxvt.color10: #00FF54 - URxvt.color11: #FFFF54 - URxvt.color12: #0000FF - URxvt.color13: #FF00FF - URxvt.color14: #00FFFF - URxvt.color15: #FFFFFF - -And here is a more complete set of non-standard colors described (not by -me) as "pretty girly". - - URxvt.cursorColor: #dc74d1 - URxvt.pointerColor: #dc74d1 - URxvt.background: #0e0e0e - URxvt.foreground: #4ad5e1 - URxvt.color0: #000000 - URxvt.color8: #8b8f93 - URxvt.color1: #dc74d1 - URxvt.color9: #dc74d1 - URxvt.color2: #0eb8c7 - URxvt.color10: #0eb8c7 - URxvt.color3: #dfe37e - URxvt.color11: #dfe37e - URxvt.color5: #9e88f0 - URxvt.color13: #9e88f0 - URxvt.color6: #73f7ff - URxvt.color14: #73f7ff - URxvt.color7: #e1dddd - URxvt.color15: #e1dddd - -=item How can I start @@RXVT_NAME@@d in a race-free way? +=head3 I am using Debian GNU/Linux and have a problem... -Try C<@@RXVT_NAME@@d -f -o>, which tells @@RXVT_NAME@@d to open the -display, create the listening socket and then fork. - -=item What's with the strange Backspace/Delete key behaviour? - -Assuming that the physical Backspace key corresponds to the -BackSpace keysym (not likely for Linux ... see the following -question) there are two standard values that can be used for -Backspace: C<^H> and C<^?>. - -Historically, either value is correct, but rxvt-unicode adopts the debian -policy of using C<^?> when unsure, because it's the one only only correct -choice :). - -Rxvt-unicode tries to inherit the current stty settings and uses the value -of `erase' to guess the value for backspace. If rxvt-unicode wasn't -started from a terminal (say, from a menu or by remote shell), then the -system value of `erase', which corresponds to CERASE in , will -be used (which may not be the same as your stty setting). - -For starting a new rxvt-unicode: - - # use Backspace = ^H - $ stty erase ^H - $ @@RXVT_NAME@@ - - # use Backspace = ^? - $ stty erase ^? - $ @@RXVT_NAME@@ - -Toggle with C / C. - -For an existing rxvt-unicode: - - # use Backspace = ^H - $ stty erase ^H - $ echo -n "^[[36h" - - # use Backspace = ^? - $ stty erase ^? - $ echo -n "^[[36l" - -This helps satisfy some of the Backspace discrepancies that occur, but -if you use Backspace = C<^H>, make sure that the termcap/terminfo value -properly reflects that. - -The Delete key is a another casualty of the ill-defined Backspace problem. -To avoid confusion between the Backspace and Delete keys, the Delete -key has been assigned an escape sequence to match the vt100 for Execute -(C) and is in the supplied termcap/terminfo. - -Some other Backspace problems: +The Debian GNU/Linux package of rxvt-unicode in sarge contains large +patches that considerably change the behaviour of rxvt-unicode (but +unfortunately this notice has been removed). Before reporting a bug to +the original rxvt-unicode author please download and install the genuine +version (L) and try to +reproduce the problem. If you cannot, chances are that the problems are +specific to Debian GNU/Linux, in which case it should be reported via the +Debian Bug Tracking System (use C to report the bug). -some editors use termcap/terminfo, -some editors (vim I'm told) expect Backspace = ^H, -GNU Emacs (and Emacs-like editors) use ^H for help. +For other problems that also affect the Debian package, you can and +probably should use the Debian BTS, too, because, after all, it's also a +bug in the Debian version and it serves as a reminder for other users that +might encounter the same issue. -Perhaps someday this will all be resolved in a consistent manner. +=head3 I am maintaining rxvt-unicode for distribution/OS XXX, any recommendation? -=item I don't like the key-bindings. How do I change them? +You should build one binary with the default options. F +now enables most useful options, and the trend goes to making them +runtime-switchable, too, so there is usually no drawback to enabling them, +except higher disk and possibly memory usage. The perl interpreter should +be enabled, as important functionality (menus, selection, likely more in +the future) depends on it. -There are some compile-time selections available via configure. Unless -you have run "configure" with the C<--disable-resources> option you can -use the `keysym' resource to alter the keystrings associated with keysyms. +You should not overwrite the C and C resources +system-wide (except maybe with C). This will result in useful +behaviour. If your distribution aims at low memory, add an empty +C resource to the app-defaults file. This will keep the +perl interpreter disabled until the user enables it. -Here's an example for a URxvt session started using C<@@RXVT_NAME@@ -name URxvt> +If you can/want build more binaries, I recommend building a minimal +one with C<--disable-everything> (very useful) and a maximal one with +C<--enable-everything> (less useful, it will be very big due to a lot of +encodings built-in that increase download times and are rarely used). - URxvt.keysym.Home: \033[1~ - URxvt.keysym.End: \033[4~ - URxvt.keysym.C-apostrophe: \033 - URxvt.keysym.C-slash: \033 - URxvt.keysym.C-semicolon: \033 - URxvt.keysym.C-grave: \033 - URxvt.keysym.C-comma: \033 - URxvt.keysym.C-period: \033 - URxvt.keysym.C-0x60: \033 - URxvt.keysym.C-Tab: \033 - URxvt.keysym.C-Return: \033 - URxvt.keysym.S-Return: \033 - URxvt.keysym.S-space: \033 - URxvt.keysym.M-Up: \033 - URxvt.keysym.M-Down: \033 - URxvt.keysym.M-Left: \033 - URxvt.keysym.M-Right: \033 - URxvt.keysym.M-C-0: list \033 - URxvt.keysym.M-C-a: list \033 - URxvt.keysym.F12: command:\033]701;zh_CN.GBK\007 +=head3 I need to make it setuid/setgid to support utmp/ptys on my OS, is this safe? -See some more examples in the documentation for the B resource. +It should be, starting with release 7.1. You are encouraged to properly +install urxvt with privileges necessary for your OS now. -=item I'm using keyboard model XXX that has extra Prior/Next/Insert keys. -How do I make use of them? For example, the Sun Keyboard type 4 -has the following mappings that rxvt-unicode doesn't recognize. +When rxvt-unicode detects that it runs setuid or setgid, it will fork +into a helper process for privileged operations (pty handling on some +systems, utmp/wtmp/lastlog handling on others) and drop privileges +immediately. This is much safer than most other terminals that keep +privileges while running (but is more relevant to urxvt, as it contains +things as perl interpreters, which might be "helpful" to attackers). + +This forking is done as the very first within main(), which is very early +and reduces possible bugs to initialisation code run before main(), or +things like the dynamic loader of your system, which should result in very +little risk. - KP_Insert == Insert - F22 == Print - F27 == Home - F29 == Prior - F33 == End - F35 == Next +=head3 I am on FreeBSD and rxvt-unicode does not seem to work at all. -Rather than have rxvt-unicode try to accommodate all the various possible -keyboard mappings, it is better to use `xmodmap' to remap the keys as -required for your particular machine. +Rxvt-unicode requires the symbol C<__STDC_ISO_10646__> to be defined +in your compile environment, or an implementation that implements it, +whether it defines the symbol or not. C<__STDC_ISO_10646__> requires that +B is represented as unicode. -=item How do I distinguish wether I'm running rxvt-unicode or a regular xterm? -I need this to decide about setting colors etc. +As you might have guessed, FreeBSD does neither define this symbol nor +does it support it. Instead, it uses its own internal representation of +B. This is, of course, completely fine with respect to standards. -rxvt and rxvt-unicode always export the variable "COLORTERM", so you can -check and see if that is set. Note that several programs, JED, slrn, -Midnight Commander automatically check this variable to decide whether or -not to use color. +However, that means rxvt-unicode only works in C, C and +C locales under FreeBSD (which all use Unicode as B). -=item How do I set the correct, full IP address for the DISPLAY variable? +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) +representation of B makes it impossible to convert between +B (as used by X11 and your applications) and any other encoding +without implementing OS-specific-wrappers for each and every locale. There +simply are no APIs to convert B into anything except the current +locale encoding. -If you've compiled rxvt-unicode with DISPLAY_IS_IP and have enabled -insecure mode then it is possible to use the following shell script -snippets to correctly set the display. If your version of rxvt-unicode -wasn't also compiled with ESCZ_ANSWER (as assumed in these snippets) then -the COLORTERM variable can be used to distinguish rxvt-unicode from a -regular xterm. +Some applications (such as the formidable B) work around this +by carrying their own replacement functions for character set handling +with them, and either implementing OS-dependent hacks or doing multiple +conversions (which is slow and unreliable in case the OS implements +encodings slightly different than the terminal emulator). -Courtesy of Chuck Blake with the following shell script -snippets: +The rxvt-unicode author insists that the right way to fix this is in the +system libraries once and for all, instead of forcing every app to carry +complete replacements for them :) - # Bourne/Korn/POSIX family of shells: - [ ${TERM:-foo} = foo ] && TERM=xterm # assume an xterm if we don't know - if [ ${TERM:-foo} = xterm ]; then - stty -icanon -echo min 0 time 15 # see if enhanced rxvt or not - echo -n '^[Z' - read term_id - stty icanon echo - if [ ""${term_id} = '^[[?1;2C' -a ${DISPLAY:-foo} = foo ]; then - echo -n '^[[7n' # query the rxvt we are in for the DISPLAY string - read DISPLAY # set it in our local shell - fi - fi +=head3 How can I use rxvt-unicode under cygwin? -=item How do I compile the manual pages for myself? +rxvt-unicode should compile and run out of the box on cygwin, using +the X11 libraries that come with cygwin. libW11 emulation is no +longer supported (and makes no sense, either, as it only supported a +single font). I recommend starting the X-server in C<-multiwindow> or +C<-rootless> mode instead, which will result in similar look&feel as the +old libW11 emulation. -You need to have a recent version of perl installed as F, -one that comes with F, F and F. Then go to -the doc subdirectory and enter C. +At the time of this writing, cygwin didn't seem to support any multi-byte +encodings (you might try C), so you are likely limited +to 8-bit encodings. -=item My question isn't answered here, can I ask a human? +=head3 Character widths are not correct. -Before sending me mail, you could go to IRC: C, -channel C<#rxvt-unicode> has some rxvt-unicode enthusiasts that might be -interested in learning about new and exciting problems (but not FAQs :). +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. -=back +The solution is to upgrade your system or switch to a better one. A +possibly working workaround is to use a wcwidth implementation like -=head1 RXVT TECHNICAL REFERENCE +http://www.cl.cam.ac.uk/~mgk25/ucs/wcwidth.c -=head1 DESCRIPTION +=head1 RXVT-UNICODE TECHNICAL REFERENCE The rest of this document describes various technical aspects of B. First the description of supported command sequences, followed by pixmap support and last by a description of all features selectable at C time. -=head1 Definitions +=head2 Definitions =over 4 =item B<< C >> -The literal character c. +The literal character c (potentially a multi-byte character). =item B<< C >> @@ -932,7 +1235,7 @@ =back -=head1 Values +=head2 Values =over 4 @@ -979,13 +1282,13 @@ Shift In (Ctrl-O), invokes the G0 character set (the default). Switch to Standard Character Set -=item B<< C >> +=item B<< C >> Space Character =back -=head1 Escape Sequences +=head2 Escape Sequences =over 4 @@ -1005,7 +1308,7 @@ Application Keypad (SMKX). See also next sequence. -=item B<<< C<< ESC >> >>> +=item B<<< C<< ESC > >> >>> Normal Keypad (RMKX) @@ -1093,7 +1396,7 @@ X -=head1 CSI (Command Sequence Introducer) Sequences +=head2 CSI (Command Sequence Introducer) Sequences =over 4 @@ -1143,8 +1446,8 @@ =begin table - B<< C >> Clear Below (default) - B<< C >> Clear Above + B<< C >> Clear Right and Below (default) + B<< C >> Clear Left and Above B<< C >> Clear All =end table @@ -1158,6 +1461,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 @@ -1284,33 +1589,33 @@ =begin table - B<< C >> Normal (default) - B<< C >> On / Off Bold (bright fg) - B<< C >> On / Off Italic - B<< C >> On / Off Underline - B<< C >> On / Off Slow Blink (bright bg) - B<< C >> On / Off Rapid Blink (bright bg) - B<< C >> On / Off Inverse - B<< C >> On / Off Invisible (NYI) - B<< C >> fg/bg Black - B<< C >> fg/bg Red - B<< C >> fg/bg Green - B<< C >> fg/bg Yellow - B<< C >> fg/bg Blue - B<< C >> fg/bg Magenta - B<< C >> fg/bg Cyan - B<< C >> set fg/bg to color #m (ISO 8613-6) - B<< C >> fg/bg White - B<< C >> fg/bg Default - B<< C >> fg/bg Bright Black - B<< C >> fg/bg Bright Red - B<< C >> fg/bg Bright Green - B<< C >> fg/bg Bright Yellow - B<< C >> fg/bg Bright Blue - B<< C >> fg/bg Bright Magenta - B<< C >> fg/bg Bright Cyan - B<< C >> fg/bg Bright White - B<< C >> fg/bg Bright Default + B<< C >> Normal (default) + B<< C >> On / Off Bold (bright fg) + B<< C >> On / Off Italic + B<< C >> On / Off Underline + B<< C >> On / Off Slow Blink (bright bg) + B<< C >> On / Off Rapid Blink (bright bg) + B<< C >> On / Off Inverse + B<< C >> On / Off Invisible (NYI) + B<< C >> fg/bg Black + B<< C >> fg/bg Red + B<< C >> fg/bg Green + B<< C >> fg/bg Yellow + B<< C >> fg/bg Blue + B<< C >> fg/bg Magenta + B<< C >> fg/bg Cyan + B<< C >> fg/bg White + B<< C >> set fg/bg to colour #m (ISO 8613-6) + B<< C >> fg/bg Default + B<< C >> fg/bg Bright Black + B<< C >> fg/bg Bright Red + B<< C >> fg/bg Bright Green + B<< C >> fg/bg Bright Yellow + B<< C >> fg/bg Bright Blue + B<< C >> fg/bg Bright Magenta + B<< C >> fg/bg Bright Cyan + B<< C >> fg/bg Bright White + B<< C >> fg/bg Bright Default =end table @@ -1327,6 +1632,20 @@ =end table +=item B<< C >> + +Set Cursor Style (DESCUSR) + +=begin table + + B<< C >> Blink Block + B<< C >> Blink Block + B<< C >> Steady Block + B<< C >> Blink Underline + B<< C >> Steady Underline + +=end table + =item B<< C >> Set Scrolling Region [top;bottom] @@ -1373,7 +1692,7 @@ X -=head1 DEC Private Modes +=head2 DEC Private Modes =over 4 @@ -1399,7 +1718,7 @@ =over 4 -=item B<< C >> (DECCKM) +=item B<< C >> (DECCKM) =begin table @@ -1408,7 +1727,7 @@ =end table -=item B<< C >> (ANSI/VT52 mode) +=item B<< C >> (DECANM) =begin table @@ -1417,61 +1736,61 @@ =end table -=item B<< C >> +=item B<< C >> (DECCOLM) =begin table - B<< C >> 132 Column Mode (DECCOLM) - B<< C >> 80 Column Mode (DECCOLM) + B<< C >> 132 Column Mode + B<< C >> 80 Column Mode =end table -=item B<< C >> +=item B<< C >> (DECSCLM) =begin table - B<< C >> Smooth (Slow) Scroll (DECSCLM) - B<< C >> Jump (Fast) Scroll (DECSCLM) + B<< C >> Smooth (Slow) Scroll + B<< C >> Jump (Fast) Scroll =end table -=item B<< C >> +=item B<< C >> (DECSCNM) =begin table - B<< C >> Reverse Video (DECSCNM) - B<< C >> Normal Video (DECSCNM) + B<< C >> Reverse Video + B<< C >> Normal Video =end table -=item B<< C >> +=item B<< C >> (DECOM) =begin table - B<< C >> Origin Mode (DECOM) - B<< C >> Normal Cursor Mode (DECOM) + B<< C >> Origin Mode + B<< C >> Normal Cursor Mode =end table -=item B<< C >> +=item B<< C >> (DECAWM) =begin table - B<< C >> Wraparound Mode (DECAWM) - B<< C >> No Wraparound Mode (DECAWM) + B<< C >> Wraparound Mode + B<< C >> No Wraparound Mode =end table -=item B<< C >> I +=item B<< C >> (DECARM) I =begin table - B<< C >> Auto-repeat Keys (DECARM) - B<< C >> No Auto-repeat Keys (DECARM) + B<< C >> Auto-repeat Keys + B<< C >> No Auto-repeat Keys =end table -=item B<< C >> X10 XTerm +=item B<< C >> X10 XTerm =begin table @@ -1480,7 +1799,7 @@ =end table -=item B<< C >> +=item B<< C >> (DECTCEM) =begin table @@ -1489,16 +1808,16 @@ =end table -=item B<< C >> +=item B<< C >> =begin table - B<< C >> scrollBar visisble - B<< C >> scrollBar invisisble + B<< C >> scrollBar visible + B<< C >> scrollBar invisible =end table -=item B<< C >> (B) +=item B<< C >> (B) =begin table @@ -1507,11 +1826,11 @@ =end table -=item B<< C >> I +=item B<< C >> I Enter Tektronix Mode (DECTEK) -=item B<< C >> +=item B<< C >> =begin table @@ -1520,7 +1839,7 @@ =end table -=item B<< C >> I +=item B<< C >> I =begin table @@ -1529,7 +1848,7 @@ =end table -=item B<< C >> I +=item B<< C >> I =begin table @@ -1538,9 +1857,9 @@ =end table -=item B<< C >> I +=item B<< C >> I -=item B<< C >> +=item B<< C >> =begin table @@ -1551,25 +1870,25 @@ X -=item B<< C >> +=item B<< C >> (DECNKM) =begin table - B<< C >> Application Keypad (DECPAM) == C - B<< C >> Normal Keypad (DECPNM) == C<< ESC > >> + B<< C >> Application Keypad (DECKPAM/DECPAM) == C + B<< C >> Normal Keypad (DECKPNM/DECPNM) == C<< ESC > >> =end table -=item B<< C >> +=item B<< C >> (DECBKM) =begin table - B<< C >> Backspace key sends B<< C (DECBKM) >> + B<< C >> Backspace key sends B<< C >> B<< C >> Backspace key sends B<< C >> =end table -=item B<< C >> (X11 XTerm) +=item B<< C >> (X11 XTerm) =begin table @@ -1578,7 +1897,7 @@ =end table -=item B<< C >> (X11 XTerm) I +=item B<< C >> (X11 XTerm) I =begin table @@ -1587,7 +1906,39 @@ =end table -=item B<< C >> (B) +=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 >> (X11 XTerm) (Compile frills) + +Try to avoid this mode, it doesn't work sensibly in non-UTF-8 locales. Use +mode C<1015> instead. + +Unlike XTerm, coordinates larger than 2015) will work fine. + +=begin table + + B<< C >> Enable mouse coordinates in locale-specific encoding. + B<< C >> Enable mouse coordinates as binary octets. + +=end table + +=item B<< C >> (B) =begin table @@ -1596,7 +1947,7 @@ =end table -=item B<< C >> (B) +=item B<< C >> (B) =begin table @@ -1605,7 +1956,47 @@ =end table -=item B<< C >> (B) +=item B<< C >> (B) (Compile frills) + +Changes all mouse reporting codes to use decimal parameters instead of +octets or characters. + +This mode should be enabled I actually enabling mouse reporting, +for semi-obvious reasons. + +The sequences received for various modes are as follows: + + ESC [ M o o o !1005, !1015 (three octets) + ESC [ M c c c 1005, !1015 (three characters) + ESC [ Pm M 1015 (three or more numeric parameters) + +The first three parameters are C, C and C. Code is the numeric +code as for the other modes (but encoded as a decimal number, including +the additional offset of 32, so you have to subtract 32 first), C and +C are the coordinates (1|1 is the upper left corner, just as with +cursor positioning). + +Example: Shift-Button-1 press at top row, column 80. + + ESC [ 37 ; 80 ; 1 M + +One can use this feature by simply enabling it and then looking for +parameters to the C reply - if there are any, this mode is +active, otherwise one of the old reporting styles is used. + +Other (to be implemented) reply sequences will use a similar encoding. + +In the future, more parameters might get added (pixel coordinates for +example - anybody out there who needs this?). + +=begin table + + B<< C >> Enable new mouse coordinate reporting. + B<< C >> Use old-style C encoding. + +=end table + +=item B<< C >> (B) =begin table @@ -1614,7 +2005,7 @@ =end table -=item B<< C >> +=item B<< C >> =begin table @@ -1623,7 +2014,7 @@ =end table -=item B<< C >> +=item B<< C >> =begin table @@ -1632,7 +2023,7 @@ =end table -=item B<< C >> +=item B<< C >> =begin table @@ -1641,13 +2032,22 @@ =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 X -=head1 XTerm Operating System Commands +=head2 XTerm Operating System Commands =over 4 @@ -1664,24 +2064,25 @@ 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 default background to B<< C >> - B<< C >> Change default foreground colour to B<< C >>. + B<< C >> Change background colour of highlight characters to B<< C >> + B<< C >> Change foreground colour of highlight characters to B<< C >> + B<< C >> Change background pixmap parameters (see section BACKGROUND IMAGE) (Compile pixbuf). + 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). @@ -1694,73 +2095,27 @@ =back -X - -=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 -sequence of scaling/positioning commands separated by semi-colons. The -scaling/positioning commands are as follows: +For the BACKGROUND IMAGE XTerm escape sequence B<< C >> the value +of B<< C >> can be one of the following commands: =over 4 -=item query scale/position - -B - -=item change scale and position - -B +=item B<< C >> -B (== B) +display scale and position in the title -B (same as B) +=item B<< C<;WxH+X+Y> >> -B (same as B) +change scale and/or position -B (same as B) +=item B<< C >> -B (same as B) - -=item change position (absolute) - -B<=+X+Y> - -B<=+X> (same as B<=+X+Y>) - -=item change position (relative) - -B<+X+Y> - -B<+X> (same as B<+X+Y>) - -=item rescale (relative) - -B -> B - -B<0xH> -> B +change background image =back -For example: - -=over 4 - -=item B<\E]20;funky\a> - -load B as a tiled image - -=item B<\E]20;mona;100\a> - -load B with a scaling of 100% - -=item B<\E]20;;200;?\a> - -rescale the current pixmap to 200% and display the image geometry in -the title - -=back X =head1 Mouse Reporting @@ -1795,14 +2150,16 @@ =over 4 -=item State = B<< C<< ( - SPACE) & 60 >> >> +=item State = B<< C<< ( - SPACE) & ~3 >> >> =begin table 4 Shift 8 Meta 16 Control - 32 Double Click I<(Rxvt extension)> + 32 Motion Notify + 32 Double Click I<(rxvt extension)>, disabled by default + 64 Button1 is actually Button4, Button2 is actually Button5 etc. =end table @@ -1811,16 +2168,17 @@ 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 setting use B to toggle Application-Keypad setting if B is off, toggle Application-Keypad setting. Also note that -values of B, B, B may have been compiled differently on +values of B, B may have been compiled differently on your system. =begin table @@ -1890,10 +2248,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 F<./reconf> script as a base for experiments. F<./reconf> is used by -myself, so it should generally be a working config. 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 @@ -1901,8 +2258,9 @@ =item --enable-everything -Add (or remove) support for all non-multichoice options listed in "./configure ---help". +Add (or remove) support for all non-multichoice options listed +in C<./configure --help>, except for C<--enable-assert> and +C<--enable-256-color>. You can specify this and then disable options you do not like by I this with the appropriate C<--disable-...> arguments, @@ -1910,9 +2268,9 @@ C<--disable-everything> and than adding just the C<--enable-...> arguments you want. -=item --enable-xft (default: enabled) +=item --enable-xft (default: on) -Add support for Xft (anti-aliases, among others) fonts. Xft fonts are +Add support for Xft (anti-aliased, among others) fonts. Xft fonts are slower and require lots of memory, but as long as you don't use them, you don't pay for them. @@ -1921,7 +2279,7 @@ Add support for B, I and B<< I >> font styles. The fonts can be set manually or automatically. -=item --with-codesets=NAME,... (default: all) +=item --with-codesets=CS,... (default: all) Compile in support for additional codeset (encoding) groups (C, C are always compiled in, which includes most 8-bit character sets). These @@ -1935,7 +2293,7 @@ all all available codeset groups zh common chinese encodings - zh_ext rarely used but very big chinese encodigs + zh_ext rarely used but very big chinese encodings jp common japanese encodings jp_ext rarely used but big japanese encodings kr korean encodings @@ -1950,6 +2308,8 @@ =item --enable-unicode3 (default: off) +Recommended to stay off unless you really need non-BMP characters. + Enable direct support for displaying unicode codepoints above 65535 (the basic multilingual page). This increases storage requirements per character from 2 to 4 bytes. X11 fonts do not yet @@ -1957,7 +2317,7 @@ Please note that rxvt-unicode can store unicode code points >65535 even without this flag, but the number of such characters is -limited to a view thousand (shared with combining characters, +limited to a few thousand (shared with combining characters, see next switch), and right now rxvt-unicode cannot display them (input/output and cut&paste still work, though). @@ -1965,14 +2325,13 @@ Enable automatic composition of combining characters into composite characters. This is required for proper viewing of text -where accents are encoded as seperate unicode characters. This is -done by using precomposited characters when available or creating +where accents are encoded as separate unicode characters. This is +done by using precomposed characters when available or creating new pseudo-characters when no precomposed form exists. -Without --enable-unicode3, the number of additional precomposed characters -is rather limited (2048, if this is full, rxvt-unicode will use the -private use area, extending the number of combinations to 8448). With ---enable-unicode3, no practical limit exists. +Without --enable-unicode3, the number of additional precomposed +characters is somewhat limited (the 6400 private use characters will be +(ab-)used). With --enable-unicode3, no practical limit exists. This option will also enable storage (but not display) of characters beyond plane 0 (>65535) when --enable-unicode3 was not specified. @@ -1981,16 +2340,17 @@ but these are not currently used. Bug me if you want these to be used (and tell me how these are to be used...). -=item --enable-fallback(=CLASS) (default: Rxvt) +=item --enable-fallback[=CLASS] (default: Rxvt) -When reading resource settings, also read settings for class CLASS. To disable resource fallback use --disable-fallback. +When reading resource settings, also read settings for class CLASS. To +disable resource fallback use --disable-fallback. =item --with-res-name=NAME (default: urxvt) 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 @@ -2013,22 +2373,26 @@ F) at start of rxvt execution. This option requires --enable-utmp to also be specified. -=item --enable-xpm-background (default: on) +=item --enable-pixbuf (default: on) -Add support for XPM background pixmaps. +Add support for GDK-PixBuf to be used for background images. +It adds support for many file formats including JPG, PNG, +TIFF, GIF, XPM, BMP, ICO and TGA. -=item --enable-transparency (default: on) +=item --enable-startup-notification (default: on) -Add support for inheriting parent backgrounds thus giving a fake -transparency to the term. +Add support for freedesktop startup notifications. This allows window managers +to display some kind of progress indicator during startup. -=item --enable-fading (default: on) +=item --enable-transparency (default: on) -Add support for fading the text when focus is lost (requires C<--enable-transparency>). +Add support for using the root pixmap as background to simulate transparency. +Note that this feature depends on libXrender and on the availability +of the RENDER extension in the X server. -=item --enable-tinting (default: on) +=item --enable-fading (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) @@ -2042,22 +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-half-shadow (default: off) - -Make shadows on the scrollbar only half the normal width & height. -only applicable to rxvt scrollbars. - -=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. @@ -2086,34 +2434,55 @@ MWM-hints EWMH-hints (pid, utf8 names) and protocols (ping) - seperate underline colour (-underlineColor) + urgency hint + separate underline colour (-underlineColor) settable border widths and borderless switch (-w, -b, -bl) - settable extra linespacing /-lsp) - iso-14755-2 and -3, and visual feedback - backindex and forwardindex escape sequence - window op and some xterm/OSC escape sequences + visual depth selection (-depth) + settable extra linespacing (-lsp) + iso-14755 5.1 (basic) support 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 highlight colour (-highlightColor, -highlightTextColor) + extended mouse reporting modes (1005 and 1015). + visual selection via -visual and -depth. + +It also enables some non-essential features otherwise disabled, such as: + + some round-trip time optimisations + nearest colour allocation on pseudocolor screens + UTF8_STRING support for selection sgr modes 90..97 and 100..107 + backindex and forwardindex escape sequences + view change/zero scrollback escape sequences + locale switching escape sequence + window op and some xterm/OSC escape sequences + rectangular selections + trailing space removal for selections + verbose X error handling =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. @@ -2124,42 +2493,48 @@ accelerator) while the control key is held down. This option requires --enable-mousewheel to also be specified. -=item --disable-new-selection - -Remove support for mouse selection style like that of xterm. - -=item --enable-dmalloc (default: off) +=item --enable-smart-resize (default: off) -Use Gray Watson's malloc - which is good for debugging See -http://www.letters.com/dmalloc/ for details If you use either this or the -next option, you may need to edit src/Makefile after compiling to point -DINCLUDE and DLIB to the right places. - -You can only use either this option and the following (should -you use either) . - -=item --enable-dlmalloc (default: off) - -Use Doug Lea's malloc - which is good for a production version -See L for details. +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) Add support to have the pointer disappear when typing or inactive. -=item --enable-perl (default: off) +=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. +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 --enable-assert (default: off) + +Enables the assertions in the code, normally disabled. This switch is only +useful when developing rxvt-unicode. + +=item --enable-256-color (default: off) + +Force use of so-called 256 colour mode, to work around buggy applications +that do not support termcap/terminfo, or simply improve support for +applications hardcoding the xterm 256 colour table. + +This switch breaks termcap/terminfo compatibility to C, +and consequently sets C to C by default +(F contains termcap/terminfo definitions for both). + +It also results in higher memory usage and can slow down @@RXVT_NAME@@ +dramatically when more than six fonts are in use by a terminal instance. =item --with-name=NAME (default: urxvt) @@ -2180,18 +2555,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