ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/rxvt-unicode/doc/rxvt.7.pod
(Generate patch)

Comparing rxvt-unicode/doc/rxvt.7.pod (file contents):
Revision 1.23 by root, Wed Aug 25 03:47:20 2004 UTC vs.
Revision 1.162 by ayin, Sat Jan 19 15:00:49 2008 UTC

1=head1 NAME 1=head1 NAME
2 2
3RXVT TECHNICAL REFERENCE - command sequences and background information 3RXVT REFERENCE - FAQ, command sequences and other background information
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 # set a new font set 7 # set a new font set
8 printf '\33]50;%s\007' 9x15,xft:Kochi" Mincho" 8 printf '\33]50;%s\007' 9x15,xft:Kochi" Mincho"
… …
13 # set window title 13 # set window title
14 printf '\33]2;%s\007' "new window title" 14 printf '\33]2;%s\007' "new window title"
15 15
16=head1 DESCRIPTION 16=head1 DESCRIPTION
17 17
18This document contains the FAQ, the RXVT TECHNICAL REFERENCE documenting
19all escape sequences, and other background information.
20
21The newest version of this document is also available on the World Wide Web at
22L<http://pod.tst.eu/http://cvs.schmorp.de/rxvt-unicode/doc/rxvt.7.pod>.
23
24The main manual page for @@RXVT_NAME@@ itself is available at
25L<http://pod.tst.eu/http://cvs.schmorp.de/rxvt-unicode/doc/rxvt.1.pod>.
26
27=head1 RXVT-UNICODE/URXVT FREQUENTLY ASKED QUESTIONS
28
29
30=head2 Meta, Features & Commandline Issues
31
32=head3 My question isn't answered here, can I ask a human?
33
34Before sending me mail, you could go to IRC: C<irc.freenode.net>,
35channel C<#rxvt-unicode> has some rxvt-unicode enthusiasts that might be
36interested in learning about new and exciting problems (but not FAQs :).
37
38=head3 Does it support tabs, can I have a tabbed rxvt-unicode?
39
40Beginning with version 7.3, there is a perl extension that implements a
41simple tabbed terminal. It is installed by default, so any of these should
42give you tabs:
43
44 @@URXVT_NAME@@ -pe tabbed
45
46 URxvt.perl-ext-common: default,tabbed
47
48It will also work fine with tabbing functionality of many window managers
49or similar tabbing programs, and its embedding-features allow it to be
50embedded into other programs, as witnessed by F<doc/rxvt-tabbed> or
51the upcoming C<Gtk2::URxvt> perl module, which features a tabbed urxvt
52(murxvt) terminal as an example embedding application.
53
54=head3 How do I know which rxvt-unicode version I'm using?
55
56The version number is displayed with the usage (-h). Also the escape
57sequence C<ESC [ 8 n> sets the window title to the version number. When
58using the @@URXVT_NAME@@c client, the version displayed is that of the
59daemon.
60
61=head3 Rxvt-unicode uses gobs of memory, how can I reduce that?
62
63Rxvt-unicode tries to obey the rule of not charging you for something you
64don't use. One thing you should try is to configure out all settings that
65you don't need, for example, Xft support is a resource hog by design,
66when used. Compiling it out ensures that no Xft font will be loaded
67accidentally when rxvt-unicode tries to find a font for your characters.
68
69Also, many people (me included) like large windows and even larger
70scrollback buffers: Without C<--enable-unicode3>, rxvt-unicode will use
716 bytes per screen cell. For a 160x?? window this amounts to almost a
72kilobyte per line. A scrollback buffer of 10000 lines will then (if full)
73use 10 Megabytes of memory. With C<--enable-unicode3> it gets worse, as
74rxvt-unicode then uses 8 bytes per screen cell.
75
76=head3 How can I start @@URXVT_NAME@@d in a race-free way?
77
78Try C<@@URXVT_NAME@@d -f -o>, which tells @@URXVT_NAME@@d to open the
79display, create the listening socket and then fork.
80
81=head3 How can I start @@URXVT_NAME@@d automatically when I run @@URXVT_NAME@@c?
82
83If you want to start @@URXVT_NAME@@d automatically whenever you run
84@@URXVT_NAME@@c and the daemon isn't running yet, use this script:
85
86 #!/bin/sh
87 @@URXVT_NAME@@c "$@"
88 if [ $? -eq 2 ]; then
89 @@URXVT_NAME@@d -q -o -f
90 @@URXVT_NAME@@c "$@"
91 fi
92
93This tries to create a new terminal, and if fails with exit status 2,
94meaning it couldn't connect to the daemon, it will start the daemon and
95re-run the command. Subsequent invocations of the script will re-use the
96existing daemon.
97
98=head3 How do I distinguish whether I'm running rxvt-unicode or a regular xterm? I need this to decide about setting colors etc.
99
100The original rxvt and rxvt-unicode always export the variable "COLORTERM",
101so you can check and see if that is set. Note that several programs, JED,
102slrn, Midnight Commander automatically check this variable to decide
103whether or not to use color.
104
105=head3 How do I set the correct, full IP address for the DISPLAY variable?
106
107If you've compiled rxvt-unicode with DISPLAY_IS_IP and have enabled
108insecure mode then it is possible to use the following shell script
109snippets to correctly set the display. If your version of rxvt-unicode
110wasn't also compiled with ESCZ_ANSWER (as assumed in these snippets) then
111the COLORTERM variable can be used to distinguish rxvt-unicode from a
112regular xterm.
113
114Courtesy of Chuck Blake <cblake@BBN.COM> with the following shell script
115snippets:
116
117 # Bourne/Korn/POSIX family of shells:
118 [ ${TERM:-foo} = foo ] && TERM=xterm # assume an xterm if we don't know
119 if [ ${TERM:-foo} = xterm ]; then
120 stty -icanon -echo min 0 time 15 # see if enhanced rxvt or not
121 echo -n '^[Z'
122 read term_id
123 stty icanon echo
124 if [ ""${term_id} = '^[[?1;2C' -a ${DISPLAY:-foo} = foo ]; then
125 echo -n '^[[7n' # query the rxvt we are in for the DISPLAY string
126 read DISPLAY # set it in our local shell
127 fi
128 fi
129
130=head3 How do I compile the manual pages on my own?
131
132You need to have a recent version of perl installed as F</usr/bin/perl>,
133one that comes with F<pod2man>, F<pod2text> and F<pod2xhtml> (from
134F<Pod::Xhtml>). Then go to the doc subdirectory and enter C<make alldoc>.
135
136=head3 Isn't rxvt-unicode supposed to be small? Don't all those features bloat?
137
138I often get asked about this, and I think, no, they didn't cause extra
139bloat. If you compare a minimal rxvt and a minimal urxvt, you can see
140that the urxvt binary is larger (due to some encoding tables always being
141compiled in), but it actually uses less memory (RSS) after startup. Even
142with C<--disable-everything>, this comparison is a bit unfair, as many
143features unique to urxvt (locale, encoding conversion, iso14755 etc.) are
144already in use in this mode.
145
146 text data bss drs rss filename
147 98398 1664 24 15695 1824 rxvt --disable-everything
148 188985 9048 66616 18222 1788 urxvt --disable-everything
149
150When you C<--enable-everything> (which I<is> unfair, as this involves xft
151and full locale/XIM support which are quite bloaty inside libX11 and my
152libc), the two diverge, but not unreasonably so.
153
154 text data bss drs rss filename
155 163431 2152 24 20123 2060 rxvt --enable-everything
156 1035683 49680 66648 29096 3680 urxvt --enable-everything
157
158The very large size of the text section is explained by the east-asian
159encoding tables, which, if unused, take up disk space but nothing else
160and can be compiled out unless you rely on X11 core fonts that use those
161encodings. The BSS size comes from the 64k emergency buffer that my c++
162compiler allocates (but of course doesn't use unless you are out of
163memory). Also, using an xft font instead of a core font immediately adds a
164few megabytes of RSS. Xft indeed is responsible for a lot of RSS even when
165not used.
166
167Of course, due to every character using two or four bytes instead of one,
168a large scrollback buffer will ultimately make rxvt-unicode use more
169memory.
170
171Compared to e.g. Eterm (5112k), aterm (3132k) and xterm (4680k), this
172still fares rather well. And compared to some monsters like gnome-terminal
173(21152k + extra 4204k in separate processes) or konsole (22200k + extra
17443180k in daemons that stay around after exit, plus half a minute of
175startup time, including the hundreds of warnings it spits out), it fares
176extremely well *g*.
177
178=head3 Why C++, isn't that unportable/bloated/uncool?
179
180Is this a question? :) It comes up very often. The simple answer is: I had
181to write it, and C++ allowed me to write and maintain it in a fraction
182of the time and effort (which is a scarce resource for me). Put even
183shorter: It simply wouldn't exist without C++.
184
185My personal stance on this is that C++ is less portable than C, but in
186the case of rxvt-unicode this hardly matters, as its portability limits
187are defined by things like X11, pseudo terminals, locale support and unix
188domain sockets, which are all less portable than C++ itself.
189
190Regarding the bloat, see the above question: It's easy to write programs
191in C that use gobs of memory, an certainly possible to write programs in
192C++ that don't. C++ also often comes with large libraries, but this is
193not necessarily the case with GCC. Here is what rxvt links against on my
194system with a minimal config:
195
196 libX11.so.6 => /usr/X11R6/lib/libX11.so.6 (0x00002aaaaabc3000)
197 libc.so.6 => /lib/libc.so.6 (0x00002aaaaadde000)
198 libdl.so.2 => /lib/libdl.so.2 (0x00002aaaab01d000)
199 /lib64/ld-linux-x86-64.so.2 (0x00002aaaaaaab000)
200
201And here is rxvt-unicode:
202
203 libX11.so.6 => /usr/X11R6/lib/libX11.so.6 (0x00002aaaaabc3000)
204 libgcc_s.so.1 => /lib/libgcc_s.so.1 (0x00002aaaaada2000)
205 libc.so.6 => /lib/libc.so.6 (0x00002aaaaaeb0000)
206 libdl.so.2 => /lib/libdl.so.2 (0x00002aaaab0ee000)
207 /lib64/ld-linux-x86-64.so.2 (0x00002aaaaaaab000)
208
209No large bloated libraries (of course, none were linked in statically),
210except maybe libX11 :)
211
212
213=head2 Rendering, Font & Look and Feel Issues
214
215=head3 I can't get transparency working, what am I doing wrong?
216
217First of all, please address all transparency related issues to Sasha Vasko at
218sasha@aftercode.net and do not bug the author about it. Also, if you can't
219get it working consider it a rite of passage: ... and you failed.
220
221Here are four ways to get transparency. B<Do> read the manpage and option
222descriptions for the programs mentioned and rxvt-unicode. Really, do it!
223
2241. Use transparent mode:
225
226 Esetroot wallpaper.jpg
227 @@URXVT_NAME@@ -tr -tint red -sh 40
228
229That works. If you think it doesn't, you lack transparency and tinting
230support, or you are unable to read.
231
2322. Use a simple pixmap and emulate pseudo-transparency. This enables you
233to use effects other than tinting and shading: Just shade/tint/whatever
234your picture with gimp or any other tool:
235
236 convert wallpaper.jpg -blur 20x20 -modulate 30 background.jpg
237 @@URXVT_NAME@@ -pixmap "background.jpg;:root"
238
239That works. If you think it doesn't, you lack AfterImage support, or you
240are unable to read.
241
2423. Use an ARGB visual:
243
244 @@URXVT_NAME@@ -depth 32 -fg grey90 -bg rgba:0000/0000/4444/cccc
245
246This requires XFT support, and the support of your X-server. If that
247doesn't work for you, blame Xorg and Keith Packard. ARGB visuals aren't
248there yet, no matter what they claim. Rxvt-Unicode contains the necessary
249bugfixes and workarounds for Xft and Xlib to make it work, but that
250doesn't mean that your WM has the required kludges in place.
251
2524. Use xcompmgr and let it do the job:
253
254 xprop -frame -f _NET_WM_WINDOW_OPACITY 32c \
255 -set _NET_WM_WINDOW_OPACITY 0xc0000000
256
257Then click on a window you want to make transparent. Replace C<0xc0000000>
258by other values to change the degree of opacity. If it doesn't work and
259your server crashes, you got to keep the pieces.
260
261=head3 Why does rxvt-unicode sometimes leave pixel droppings?
262
263Most fonts were not designed for terminal use, which means that character
264size varies a lot. A font that is otherwise fine for terminal use might
265contain some characters that are simply too wide. Rxvt-unicode will avoid
266these characters. For characters that are just "a bit" too wide a special
267"careful" rendering mode is used that redraws adjacent characters.
268
269All of this requires that fonts do not lie about character sizes,
270however: Xft fonts often draw glyphs larger than their acclaimed bounding
271box, and rxvt-unicode has no way of detecting this (the correct way is to
272ask for the character bounding box, which unfortunately is wrong in these
273cases).
274
275It's not clear (to me at least), whether this is a bug in Xft, freetype,
276or the respective font. If you encounter this problem you might try using
277the C<-lsp> option to give the font more height. If that doesn't work, you
278might be forced to use a different font.
279
280All of this is not a problem when using X11 core fonts, as their bounding
281box data is correct.
282
283=head3 How can I keep rxvt-unicode from using reverse video so much?
284
285First of all, make sure you are running with the right terminal settings
286(C<TERM=rxvt-unicode>), which will get rid of most of these effects. Then
287make sure you have specified colours for italic and bold, as otherwise
288rxvt-unicode might use reverse video to simulate the effect:
289
290 URxvt.colorBD: white
291 URxvt.colorIT: green
292
293=head3 Some programs assume totally weird colours (red instead of blue), how can I fix that?
294
295For some unexplainable reason, some rare programs assume a very weird
296colour palette when confronted with a terminal with more than the standard
2978 colours (rxvt-unicode supports 88). The right fix is, of course, to fix
298these programs not to assume non-ISO colours without very good reasons.
299
300In the meantime, you can either edit your C<rxvt-unicode> terminfo
301definition to only claim 8 colour support or use C<TERM=rxvt>, which will
302fix colours but keep you from using other rxvt-unicode features.
303
304=head3 Can I switch the fonts at runtime?
305
306Yes, using an escape sequence. Try something like this, which has the same
307effect as using the C<-fn> switch, and takes effect immediately:
308
309 printf '\33]50;%s\007' "9x15bold,xft:Kochi Gothic"
310
311This is useful if you e.g. work primarily with japanese (and prefer a
312japanese font), but you have to switch to chinese temporarily, where
313japanese fonts would only be in your way.
314
315You can think of this as a kind of manual ISO-2022 switching.
316
317=head3 Why do italic characters look as if clipped?
318
319Many fonts have difficulties with italic characters and hinting. For
320example, the otherwise very nicely hinted font C<xft:Bitstream Vera Sans
321Mono> completely fails in its italic face. A workaround might be to
322enable freetype autohinting, i.e. like this:
323
324 URxvt.italicFont: xft:Bitstream Vera Sans Mono:italic:autohint=true
325 URxvt.boldItalicFont: xft:Bitstream Vera Sans Mono:bold:italic:autohint=true
326
327=head3 Can I speed up Xft rendering somehow?
328
329Yes, the most obvious way to speed it up is to avoid Xft entirely, as
330it is simply slow. If you still want Xft fonts you might try to disable
331antialiasing (by appending C<:antialias=false>), which saves lots of
332memory and also speeds up rendering considerably.
333
334=head3 Rxvt-unicode doesn't seem to anti-alias its fonts, what is wrong?
335
336Rxvt-unicode will use whatever you specify as a font. If it needs to
337fall back to its default font search list it will prefer X11 core
338fonts, because they are small and fast, and then use Xft fonts. It has
339antialiasing disabled for most of them, because the author thinks they
340look best that way.
341
342If you want antialiasing, you have to specify the fonts manually.
343
344=head3 What's with this bold/blink stuff?
345
346If no bold colour is set via C<colorBD:>, bold will invert text using the
347standard foreground colour.
348
349For the standard background colour, blinking will actually make
350the text blink when compiled with C<--enable-text-blink>. Without
351C<--enable-text-blink>, the blink attribute will be ignored.
352
353On ANSI colours, bold/blink attributes are used to set high-intensity
354foreground/background colors.
355
356color0-7 are the low-intensity colors.
357
358color8-15 are the corresponding high-intensity colors.
359
360=head3 I don't like the screen colors. How do I change them?
361
362You can change the screen colors at run-time using F<~/.Xdefaults>
363resources (or as long-options).
364
365Here are values that are supposed to resemble a VGA screen,
366including the murky brown that passes for low-intensity yellow:
367
368 URxvt.color0: #000000
369 URxvt.color1: #A80000
370 URxvt.color2: #00A800
371 URxvt.color3: #A8A800
372 URxvt.color4: #0000A8
373 URxvt.color5: #A800A8
374 URxvt.color6: #00A8A8
375 URxvt.color7: #A8A8A8
376
377 URxvt.color8: #000054
378 URxvt.color9: #FF0054
379 URxvt.color10: #00FF54
380 URxvt.color11: #FFFF54
381 URxvt.color12: #0000FF
382 URxvt.color13: #FF00FF
383 URxvt.color14: #00FFFF
384 URxvt.color15: #FFFFFF
385
386And here is a more complete set of non-standard colors.
387
388 URxvt.cursorColor: #dc74d1
389 URxvt.pointerColor: #dc74d1
390 URxvt.background: #0e0e0e
391 URxvt.foreground: #4ad5e1
392 URxvt.color0: #000000
393 URxvt.color8: #8b8f93
394 URxvt.color1: #dc74d1
395 URxvt.color9: #dc74d1
396 URxvt.color2: #0eb8c7
397 URxvt.color10: #0eb8c7
398 URxvt.color3: #dfe37e
399 URxvt.color11: #dfe37e
400 URxvt.color5: #9e88f0
401 URxvt.color13: #9e88f0
402 URxvt.color6: #73f7ff
403 URxvt.color14: #73f7ff
404 URxvt.color7: #e1dddd
405 URxvt.color15: #e1dddd
406
407They have been described (not by me) as "pretty girly".
408
409=head3 Why do some characters look so much different than others?
410
411See next entry.
412
413=head3 How does rxvt-unicode choose fonts?
414
415Most fonts do not contain the full range of Unicode, which is
416fine. Chances are that the font you (or the admin/package maintainer of
417your system/os) have specified does not cover all the characters you want
418to display.
419
420B<rxvt-unicode> makes a best-effort try at finding a replacement
421font. Often the result is fine, but sometimes the chosen font looks
422bad/ugly/wrong. Some fonts have totally strange characters that don't
423resemble the correct glyph at all, and rxvt-unicode lacks the artificial
424intelligence to detect that a specific glyph is wrong: it has to believe
425the font that the characters it claims to contain indeed look correct.
426
427In that case, select a font of your taste and add it to the font list,
428e.g.:
429
430 @@URXVT_NAME@@ -fn basefont,font2,font3...
431
432When rxvt-unicode sees a character, it will first look at the base
433font. If the base font does not contain the character, it will go to the
434next font, and so on. Specifying your own fonts will also speed up this
435search and use less resources within rxvt-unicode and the X-server.
436
437The only limitation is that none of the fonts may be larger than the base
438font, as the base font defines the terminal character cell size, which
439must be the same due to the way terminals work.
440
441=head3 Why do some chinese characters look so different than others?
442
443This is because there is a difference between script and language --
444rxvt-unicode does not know which language the text that is output is,
445as it only knows the unicode character codes. If rxvt-unicode first
446sees a japanese/chinese character, it might choose a japanese font for
447display. Subsequent japanese characters will use that font. Now, many
448chinese characters aren't represented in japanese fonts, so when the first
449non-japanese character comes up, rxvt-unicode will look for a chinese font
450-- unfortunately at this point, it will still use the japanese font for
451chinese characters that are also in the japanese font.
452
453The workaround is easy: just tag a chinese font at the end of your font
454list (see the previous question). The key is to view the font list as
455a preference list: If you expect more japanese, list a japanese font
456first. If you expect more chinese, put a chinese font first.
457
458In the future it might be possible to switch language preferences at
459runtime (the internal data structure has no problem with using different
460fonts for the same character at the same time, but no interface for this
461has been designed yet).
462
463Until then, you might get away with switching fonts at runtime (see L<Can
464I switch the fonts at runtime?> later in this document).
465
466=head3 How can I make mplayer display video correctly?
467
468We are working on it, in the meantime, as a workaround, use something like:
469
470 @@URXVT_NAME@@ -b 600 -geometry 20x1 -e sh -c 'mplayer -wid $WINDOWID file...'
471
472
473=head2 Keyboard, Mouse & User Interaction
474
475=head3 The new selection selects pieces that are too big, how can I select single words?
476
477If you want to select e.g. alphanumeric words, you can use the following
478setting:
479
480 URxvt.selection.pattern-0: ([[:word:]]+)
481
482If you click more than twice, the selection will be extended
483more and more.
484
485To get a selection that is very similar to the old code, try this pattern:
486
487 URxvt.selection.pattern-0: ([^"&'()*,;<=>?@[\\\\]^`{|})]+)
488
489Please also note that the I<LeftClick Shift-LeftClick> combination also
490selects words like the old code.
491
492=head3 I don't like the new selection/popups/hotkeys/perl, how do I change/disable it?
493
494You can disable the perl extension completely by setting the
495B<perl-ext-common> resource to the empty string, which also keeps
496rxvt-unicode from initialising perl, saving memory.
497
498If you only want to disable specific features, you first have to
499identify which perl extension is responsible. For this, read the section
500B<PREPACKAGED EXTENSIONS> in the @@URXVT_NAME@@perl(3) manpage. For
501example, to disable the B<selection-popup> and B<option-popup>, specify
502this B<perl-ext-common> resource:
503
504 URxvt.perl-ext-common: default,-selection-popup,-option-popup
505
506This will keep the default extensions, but disable the two popup
507extensions. Some extensions can also be configured, for example,
508scrollback search mode is triggered by B<M-s>. You can move it to any
509other combination either by setting the B<searchable-scrollback> resource:
510
511 URxvt.searchable-scrollback: CM-s
512
513=head3 The cursor moves when selecting text in the current input line, how do I switch this off?
514
515See next entry.
516
517=head3 During rlogin/ssh/telnet/etc. sessions, clicking near the cursor outputs strange escape sequences, how do I fix this?
518
519These are caused by the C<readline> perl extension. Under normal
520circumstances, it will move your cursor around when you click into the
521line that contains it. It tries hard not to do this at the wrong moment,
522but when running a program that doesn't parse cursor movements or in some
523cases during rlogin sessions, it fails to detect this properly.
524
525You can permanently switch this feature off by disabling the C<readline>
526extension:
527
528 URxvt.perl-ext-common: default,-readline
529
530=head3 My numerical keypad acts weird and generates differing output?
531
532Some Debian GNUL/Linux users seem to have this problem, although no
533specific details were reported so far. It is possible that this is caused
534by the wrong C<TERM> setting, although the details of whether and how
535this can happen are unknown, as C<TERM=rxvt> should offer a compatible
536keymap. See the answer to the previous question, and please report if that
537helped.
538
539=head3 My Compose (Multi_key) key is no longer working.
540
541The most common causes for this are that either your locale is not set
542correctly, or you specified a B<preeditStyle> that is not supported by
543your input method. For example, if you specified B<OverTheSpot> and
544your input method (e.g. the default input method handling Compose keys)
545does not support this (for instance because it is not visual), then
546rxvt-unicode will continue without an input method.
547
548In this case either do not specify a B<preeditStyle> or specify more than
549one pre-edit style, such as B<OverTheSpot,Root,None>.
550
551=head3 I cannot type C<Ctrl-Shift-2> to get an ASCII NUL character due to ISO 14755
552
553Either try C<Ctrl-2> alone (it often is mapped to ASCII NUL even on
554international keyboards) or simply use ISO 14755 support to your
555advantage, typing <Ctrl-Shift-0> to get a ASCII NUL. This works for other
556codes, too, such as C<Ctrl-Shift-1-d> to type the default telnet escape
557character and so on.
558
559=head3 Mouse cut/paste suddenly no longer works.
560
561Make sure that mouse reporting is actually turned off since killing
562some editors prematurely may leave the mouse in mouse report mode. I've
563heard that tcsh may use mouse reporting unless it otherwise specified. A
564quick check is to see if cut/paste works when the Alt or Shift keys are
565depressed.
566
567=head3 What's with the strange Backspace/Delete key behaviour?
568
569Assuming that the physical Backspace key corresponds to the
570Backspace keysym (not likely for Linux ... see the following
571question) there are two standard values that can be used for
572Backspace: C<^H> and C<^?>.
573
574Historically, either value is correct, but rxvt-unicode adopts the debian
575policy of using C<^?> when unsure, because it's the one and only correct
576choice :).
577
578Rxvt-unicode tries to inherit the current stty settings and uses the value
579of `erase' to guess the value for backspace. If rxvt-unicode wasn't
580started from a terminal (say, from a menu or by remote shell), then the
581system value of `erase', which corresponds to CERASE in <termios.h>, will
582be used (which may not be the same as your stty setting).
583
584For starting a new rxvt-unicode:
585
586 # use Backspace = ^H
587 $ stty erase ^H
588 $ @@URXVT_NAME@@
589
590 # use Backspace = ^?
591 $ stty erase ^?
592 $ @@URXVT_NAME@@
593
594Toggle with C<ESC [ 36 h> / C<ESC [ 36 l>.
595
596For an existing rxvt-unicode:
597
598 # use Backspace = ^H
599 $ stty erase ^H
600 $ echo -n "^[[36h"
601
602 # use Backspace = ^?
603 $ stty erase ^?
604 $ echo -n "^[[36l"
605
606This helps satisfy some of the Backspace discrepancies that occur, but
607if you use Backspace = C<^H>, make sure that the termcap/terminfo value
608properly reflects that.
609
610The Delete key is a another casualty of the ill-defined Backspace problem.
611To avoid confusion between the Backspace and Delete keys, the Delete
612key has been assigned an escape sequence to match the vt100 for Execute
613(C<ESC [ 3 ~>) and is in the supplied termcap/terminfo.
614
615Some other Backspace problems:
616
617some editors use termcap/terminfo,
618some editors (vim I'm told) expect Backspace = ^H,
619GNU Emacs (and Emacs-like editors) use ^H for help.
620
621Perhaps someday this will all be resolved in a consistent manner.
622
623=head3 I don't like the key-bindings. How do I change them?
624
625There are some compile-time selections available via configure. Unless
626you have run "configure" with the C<--disable-resources> option you can
627use the `keysym' resource to alter the keystrings associated with keysyms.
628
629Here's an example for a URxvt session started using C<@@URXVT_NAME@@ -name URxvt>
630
631 URxvt.keysym.Home: \033[1~
632 URxvt.keysym.End: \033[4~
633 URxvt.keysym.C-apostrophe: \033<C-'>
634 URxvt.keysym.C-slash: \033<C-/>
635 URxvt.keysym.C-semicolon: \033<C-;>
636 URxvt.keysym.C-grave: \033<C-`>
637 URxvt.keysym.C-comma: \033<C-,>
638 URxvt.keysym.C-period: \033<C-.>
639 URxvt.keysym.C-0x60: \033<C-`>
640 URxvt.keysym.C-Tab: \033<C-Tab>
641 URxvt.keysym.C-Return: \033<C-Return>
642 URxvt.keysym.S-Return: \033<S-Return>
643 URxvt.keysym.S-space: \033<S-Space>
644 URxvt.keysym.M-Up: \033<M-Up>
645 URxvt.keysym.M-Down: \033<M-Down>
646 URxvt.keysym.M-Left: \033<M-Left>
647 URxvt.keysym.M-Right: \033<M-Right>
648 URxvt.keysym.M-C-0: list \033<M-C- 0123456789 >
649 URxvt.keysym.M-C-a: list \033<M-C- abcdefghijklmnopqrstuvwxyz >
650 URxvt.keysym.F12: command:\033]701;zh_CN.GBK\007
651
652See some more examples in the documentation for the B<keysym> resource.
653
654=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
655
656 KP_Insert == Insert
657 F22 == Print
658 F27 == Home
659 F29 == Prior
660 F33 == End
661 F35 == Next
662
663Rather than have rxvt-unicode try to accommodate all the various possible
664keyboard mappings, it is better to use `xmodmap' to remap the keys as
665required for your particular machine.
666
667
668=head2 Terminal Configuration
669
670=head3 Can I see a typical configuration?
671
672The default configuration tries to be xterm-like, which I don't like that
673much, but it's least surprise to regular users.
674
675As a rxvt or rxvt-unicode user, you are practically supposed to invest
676time into customising your terminal. To get you started, here is the
677author's .Xdefaults entries, with comments on what they do. It's certainly
678not I<typical>, but what's typical...
679
680 URxvt.cutchars: "()*,<>[]{}|'
681 URxvt.print-pipe: cat >/tmp/xxx
682
683These are just for testing stuff.
684
685 URxvt.imLocale: ja_JP.UTF-8
686 URxvt.preeditType: OnTheSpot,None
687
688This tells rxvt-unicode to use a special locale when communicating with
689the X Input Method, and also tells it to only use the OnTheSpot pre-edit
690type, which requires the C<xim-onthespot> perl extension but rewards me
691with correct-looking fonts.
692
693 URxvt.perl-lib: /root/lib/urxvt
694 URxvt.perl-ext-common: default,selection-autotransform,selection-pastebin,xim-onthespot,remote-clipboard
695 URxvt.selection.pattern-0: ( at .*? line \\d+)
696 URxvt.selection.pattern-1: ^(/[^:]+):\
697 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/
698 URxvt.selection-autotransform.1: s/^ at (.*?) line (\\d+)$/:e \\Q$1\\E\\x0d:$2\\x0d/
699
700This is my perl configuration. The first two set the perl library
701directory and also tells urxvt to use a large number of extensions. I
702develop for myself mostly, so I actually use most of the extensions I
703write.
704
705The selection stuff mainly makes the selection perl-error-message aware
706and tells it to convert perl error messages into vi-commands to load the
707relevant file and go tot he error line number.
708
709 URxvt.scrollstyle: plain
710 URxvt.secondaryScroll: true
711
712As the documentation says: plain is the preferred scrollbar for the
713author. The C<secondaryScroll> configures urxvt to scroll in full-screen
714apps, like screen, so lines scrolled out of screen end up in urxvt's
715scrollback buffer.
716
717 URxvt.background: #000000
718 URxvt.foreground: gray90
719 URxvt.color7: gray90
720 URxvt.colorBD: #ffffff
721 URxvt.cursorColor: #e0e080
722 URxvt.throughColor: #8080f0
723 URxvt.highlightColor: #f0f0f0
724
725Some colours. Not sure which ones are being used or even non-defaults, but
726these are in my .Xdefaults. Most notably, they set foreground/background
727to light gray/black, and also make sure that the colour 7 matches the
728default foreground colour.
729
730 URxvt.underlineColor: yellow
731
732Another colour, makes underline lines look different. Sometimes hurts, but
733is mostly a nice effect.
734
735 URxvt.geometry: 154x36
736 URxvt.loginShell: false
737 URxvt.meta: ignore
738 URxvt.utmpInhibit: true
739
740Uh, well, should be mostly self-explanatory. By specifying some defaults
741manually, I can quickly switch them for testing.
742
743 URxvt.saveLines: 8192
744
745A large scrollback buffer is essential. Really.
746
747 URxvt.mapAlert: true
748
749The only case I use it is for my IRC window, which I like to keep
750iconified till people msg me (which beeps).
751
752 URxvt.visualBell: true
753
754The audible bell is often annoying, especially when in a crowd.
755
756 URxvt.insecure: true
757
758Please don't hack my mutt! Ooops...
759
760 URxvt.pastableTabs: false
761
762I once thought this is a great idea.
763
764 urxvt.font: 9x15bold,\
765 -misc-fixed-bold-r-normal--15-140-75-75-c-90-iso10646-1,\
766 -misc-fixed-medium-r-normal--15-140-75-75-c-90-iso10646-1, \
767 [codeset=JISX0208]xft:Kochi Gothic, \
768 xft:Bitstream Vera Sans Mono:autohint=true, \
769 xft:Code2000:antialias=false
770 urxvt.boldFont: -xos4-terminus-bold-r-normal--14-140-72-72-c-80-iso8859-15
771 urxvt.italicFont: xft:Bitstream Vera Sans Mono:italic:autohint=true
772 urxvt.boldItalicFont: xft:Bitstream Vera Sans Mono:bold:italic:autohint=true
773
774I wrote rxvt-unicode to be able to specify fonts exactly. So don't be
775overwhelmed. A special note: the C<9x15bold> mentioned above is actually
776the version from XFree-3.3, as XFree-4 replaced it by a totally different
777font (different glyphs for C<;> and many other harmless characters),
778while the second font is actually the C<9x15bold> from XFree4/XOrg. The
779bold version has less chars than the medium version, so I use it for rare
780characters, too. When editing sources with vim, I use italic for comments
781and other stuff, which looks quite good with Bitstream Vera anti-aliased.
782
783Terminus is a quite bad font (many very wrong glyphs), but for most of my
784purposes, it works, and gives a different look, as my normal (Non-bold)
785font is already bold, and I want to see a difference between bold and
786normal fonts.
787
788Please note that I used the C<urxvt> instance name and not the C<URxvt>
789class name. Thats because I use different configs for different purposes,
790for example, my IRC window is started with C<-name IRC>, and uses these
791defaults:
792
793 IRC*title: IRC
794 IRC*geometry: 87x12+535+542
795 IRC*saveLines: 0
796 IRC*mapAlert: true
797 IRC*font: suxuseuro
798 IRC*boldFont: suxuseuro
799 IRC*colorBD: white
800 IRC*keysym.M-C-1: command:\033]710;suxuseuro\007\033]711;suxuseuro\007
801 IRC*keysym.M-C-2: command:\033]710;9x15bold\007\033]711;9x15bold\007
802
803C<Alt-Shift-1> and C<Alt-Shift-2> switch between two different font
804sizes. C<suxuseuro> allows me to keep an eye (and actually read)
805stuff while keeping a very small window. If somebody pastes something
806complicated (e.g. japanese), I temporarily switch to a larger font.
807
808The above is all in my C<.Xdefaults> (I don't use C<.Xresources> nor
809C<xrdb>). I also have some resources in a separate C<.Xdefaults-hostname>
810file for different hosts, for example, on ym main desktop, I use:
811
812 URxvt.keysym.C-M-q: command:\033[3;5;5t
813 URxvt.keysym.C-M-y: command:\033[3;5;606t
814 URxvt.keysym.C-M-e: command:\033[3;1605;5t
815 URxvt.keysym.C-M-c: command:\033[3;1605;606t
816 URxvt.keysym.C-M-p: perl:test
817
818The first for keysym definitions allow me to quickly bring some windows
819in the layout I like most. Ion users might start laughing but will stop
820immediately when I tell them that I use my own Fvwm2 module for much the
821same effect as Ion provides, and I only very rarely use the above key
822combinations :->
823
824=head3 Why doesn't rxvt-unicode read my resources?
825
826Well, why, indeed? It does, in a way very similar to other X
827applications. Most importantly, this means that if you or your OS loads
828resources into the X display (the right way to do it), rxvt-unicode will
829ignore any resource files in your home directory. It will only read
830F<$HOME/.Xdefaults> when no resources are attached to the display.
831
832If you have or use an F<$HOME/.Xresources> file, chances are that
833resources are loaded into your X-server. In this case, you have to
834re-login after every change (or run F<xrdb -merge $HOME/.Xresources>).
835
836Also consider the form resources have to use:
837
838 URxvt.resource: value
839
840If you want to use another form (there are lots of different ways of
841specifying resources), make sure you understand whether and why it
842works. If unsure, use the form above.
843
844=head3 When I log-in to another system it tells me about missing terminfo data?
845
846The terminal description used by rxvt-unicode is not as widely available
847as that for xterm, or even rxvt (for which the same problem often arises).
848
849The correct solution for this problem is to install the terminfo, this can
850be done like this (with ncurses' infocmp and works as user and admin):
851
852 REMOTE=remotesystem.domain
853 infocmp rxvt-unicode | ssh $REMOTE "mkdir -p .terminfo && cat >/tmp/ti && tic /tmp/ti"
854
855... or by installing rxvt-unicode normally on the remote system,
856
857One some systems you might need to set C<$TERMINFO> to the full path of
858F<$HOME/.terminfo> for this to work.
859
860If you cannot or do not want to do this, then you can simply set
861C<TERM=rxvt> or even C<TERM=xterm>, and live with the small number of
862problems arising, which includes wrong keymapping, less and different
863colours and some refresh errors in fullscreen applications. It's a nice
864quick-and-dirty workaround for rare cases, though.
865
866If you always want to do this (and are fine with the consequences) you
867can either recompile rxvt-unicode with the desired TERM value or use a
868resource to set it:
869
870 URxvt.termName: rxvt
871
872If you don't plan to use B<rxvt> (quite common...) you could also replace
873the rxvt terminfo file with the rxvt-unicode one and use C<TERM=rxvt>.
874
875=head3 C<tic> outputs some error when compiling the terminfo entry.
876
877Most likely it's the empty definition for C<enacs=>. Just replace it by
878C<enacs=\E[0@> and try again.
879
880=head3 C<bash>'s readline does not work correctly under @@URXVT_NAME@@.
881
882See next entry.
883
884=head3 I need a termcap file entry.
885
886One reason you might want this is that some distributions or operating
887systems still compile some programs using the long-obsoleted termcap
888library (Fedora Core's bash is one example) and rely on a termcap entry
889for C<rxvt-unicode>.
890
891You could use rxvt's termcap entry with reasonable results in many cases.
892You can also create a termcap entry by using terminfo's infocmp program
893like this:
894
895 infocmp -C rxvt-unicode
896
897Or you could use this termcap entry, generated by the command above:
898
899 rxvt-unicode|rxvt-unicode terminal (X Window System):\
900 :am:bw:eo:km:mi:ms:xn:xo:\
901 :co#80:it#8:li#24:lm#0:\
902 :AL=\E[%dL:DC=\E[%dP:DL=\E[%dM:DO=\E[%dB:IC=\E[%d@:\
903 :K1=\EOw:K2=\EOu:K3=\EOy:K4=\EOq:K5=\EOs:LE=\E[%dD:\
904 :RI=\E[%dC:SF=\E[%dS:SR=\E[%dT:UP=\E[%dA:ae=\E(B:al=\E[L:\
905 :as=\E(0:bl=^G:cd=\E[J:ce=\E[K:cl=\E[H\E[2J:\
906 :cm=\E[%i%d;%dH:cr=^M:cs=\E[%i%d;%dr:ct=\E[3g:dc=\E[P:\
907 :dl=\E[M:do=^J:ec=\E[%dX:ei=\E[4l:ho=\E[H:\
908 :i1=\E[?47l\E=\E[?1l:ic=\E[@:im=\E[4h:\
909 :is=\E[r\E[m\E[2J\E[H\E[?7h\E[?1;3;4;6l\E[4l:\
910 :k1=\E[11~:k2=\E[12~:k3=\E[13~:k4=\E[14~:k5=\E[15~:\
911 :k6=\E[17~:k7=\E[18~:k8=\E[19~:k9=\E[20~:kD=\E[3~:\
912 :kI=\E[2~:kN=\E[6~:kP=\E[5~:kb=\177:kd=\EOB:ke=\E[?1l\E>:\
913 :kh=\E[7~:kl=\EOD:kr=\EOC:ks=\E[?1h\E=:ku=\EOA:le=^H:\
914 :mb=\E[5m:md=\E[1m:me=\E[m\017:mr=\E[7m:nd=\E[C:rc=\E8:\
915 :sc=\E7:se=\E[27m:sf=^J:so=\E[7m:sr=\EM:st=\EH:ta=^I:\
916 :te=\E[r\E[?1049l:ti=\E[?1049h:ue=\E[24m:up=\E[A:\
917 :us=\E[4m:vb=\E[?5h\E[?5l:ve=\E[?25h:vi=\E[?25l:\
918 :vs=\E[?25h:
919
920=head3 Why does C<ls> no longer have coloured output?
921
922The C<ls> in the GNU coreutils unfortunately doesn't use terminfo to
923decide whether a terminal has colour, but uses its own configuration
924file. Needless to say, C<rxvt-unicode> is not in its default file (among
925with most other terminals supporting colour). Either add:
926
927 TERM rxvt-unicode
928
929to C</etc/DIR_COLORS> or simply add:
930
931 alias ls='ls --color=auto'
932
933to your C<.profile> or C<.bashrc>.
934
935=head3 Why doesn't vim/emacs etc. use the 88 colour mode?
936
937See next entry.
938
939=head3 Why doesn't vim/emacs etc. make use of italic?
940
941See next entry.
942
943=head3 Why are the secondary screen-related options not working properly?
944
945Make sure you are using C<TERM=rxvt-unicode>. Some pre-packaged
946distributions (most notably Debian GNU/Linux) break rxvt-unicode
947by setting C<TERM> to C<rxvt>, which doesn't have these extra
948features. Unfortunately, some of these (most notably, again, Debian
949GNU/Linux) furthermore fail to even install the C<rxvt-unicode> terminfo
950file, so you will need to install it on your own (See the question B<When
951I log-in to another system it tells me about missing terminfo data?> on
952how to do this).
953
954
955=head2 Encoding / Locale / Input Method Issues
956
957=head3 Rxvt-unicode does not seem to understand the selected encoding?
958
959See next entry.
960
961=head3 Unicode does not seem to work?
962
963If you encounter strange problems like typing an accented character but
964getting two unrelated other characters or similar, or if program output is
965subtly garbled, then you should check your locale settings.
966
967Rxvt-unicode must be started with the same C<LC_CTYPE> setting as the
968programs running in it. Often rxvt-unicode is started in the C<C> locale,
969while the login script running within the rxvt-unicode window changes the
970locale to something else, e.g. C<en_GB.UTF-8>. Needless to say, this is
971not going to work, and is the most common cause for problems.
972
973The best thing is to fix your startup environment, as you will likely run
974into other problems. If nothing works you can try this in your .profile.
975
976 printf '\33]701;%s\007' "$LC_CTYPE" # $LANG or $LC_ALL are worth a try, too
977
978If this doesn't work, then maybe you use a C<LC_CTYPE> specification not
979supported on your systems. Some systems have a C<locale> command which
980displays this (also, C<perl -e0> can be used to check locale settings, as
981it will complain loudly if it cannot set the locale). If it displays something
982like:
983
984 locale: Cannot set LC_CTYPE to default locale: ...
985
986Then the locale you specified is not supported on your system.
987
988If nothing works and you are sure that everything is set correctly then
989you will need to remember a little known fact: Some programs just don't
990support locales :(
991
992=head3 How does rxvt-unicode determine the encoding to use?
993
994See next entry.
995
996=head3 Is there an option to switch encodings?
997
998Unlike some other terminals, rxvt-unicode has no encoding switch, and no
999specific "utf-8" mode, such as xterm. In fact, it doesn't even know about
1000UTF-8 or any other encodings with respect to terminal I/O.
1001
1002The reasons is that there exists a perfectly fine mechanism for selecting
1003the encoding, doing I/O and (most important) communicating this to all
1004applications so everybody agrees on character properties such as width
1005and code number. This mechanism is the I<locale>. Applications not using
1006that info will have problems (for example, C<xterm> gets the width of
1007characters wrong as it uses its own, locale-independent table under all
1008locales).
1009
1010Rxvt-unicode uses the C<LC_CTYPE> locale category to select encoding. All
1011programs doing the same (that is, most) will automatically agree in the
1012interpretation of characters.
1013
1014Unfortunately, there is no system-independent way to select locales, nor
1015is there a standard on how locale specifiers will look like.
1016
1017On most systems, the content of the C<LC_CTYPE> environment variable
1018contains an arbitrary string which corresponds to an already-installed
1019locale. Common names for locales are C<en_US.UTF-8>, C<de_DE.ISO-8859-15>,
1020C<ja_JP.EUC-JP>, i.e. C<language_country.encoding>, but other forms
1021(i.e. C<de> or C<german>) are also common.
1022
1023Rxvt-unicode ignores all other locale categories, and except for
1024the encoding, ignores country or language-specific settings,
1025i.e. C<de_DE.UTF-8> and C<ja_JP.UTF-8> are the normally same to
1026rxvt-unicode.
1027
1028If you want to use a specific encoding you have to make sure you start
1029rxvt-unicode with the correct C<LC_CTYPE> category.
1030
1031=head3 Can I switch locales at runtime?
1032
1033Yes, using an escape sequence. Try something like this, which sets
1034rxvt-unicode's idea of C<LC_CTYPE>.
1035
1036 printf '\33]701;%s\007' ja_JP.SJIS
1037
1038See also the previous answer.
1039
1040Sometimes this capability is rather handy when you want to work in
1041one locale (e.g. C<de_DE.UTF-8>) but some programs don't support it
1042(e.g. UTF-8). For example, I use this script to start C<xjdic>, which
1043first switches to a locale supported by xjdic and back later:
1044
1045 printf '\33]701;%s\007' ja_JP.SJIS
1046 xjdic -js
1047 printf '\33]701;%s\007' de_DE.UTF-8
1048
1049You can also use xterm's C<luit> program, which usually works fine, except
1050for some locales where character width differs between program- and
1051rxvt-unicode-locales.
1052
1053=head3 I have problems getting my input method working.
1054
1055Try a search engine, as this is slightly different for every input method server.
1056
1057Here is a checklist:
1058
1059=over 4
1060
1061=item - Make sure your locale I<and> the imLocale are supported on your OS.
1062
1063Try C<locale -a> or check the documentation for your OS.
1064
1065=item - Make sure your locale or imLocale matches a locale supported by your XIM.
1066
1067For example, B<kinput2> does not support UTF-8 locales, you should use
1068C<ja_JP.EUC-JP> or equivalent.
1069
1070=item - Make sure your XIM server is actually running.
1071
1072=item - Make sure the C<XMODIFIERS> environment variable is set correctly when I<starting> rxvt-unicode.
1073
1074When you want to use e.g. B<kinput2>, it must be set to
1075C<@im=kinput2>. For B<scim>, use C<@im=SCIM>. You can see what input
1076method servers are running with this command:
1077
1078 xprop -root XIM_SERVERS
1079
1080=item
1081
1082=back
1083
1084=head3 My input method wants <some encoding> but I want UTF-8, what can I do?
1085
1086You can specify separate locales for the input method and the rest of the
1087terminal, using the resource C<imlocale>:
1088
1089 URxvt.imlocale: ja_JP.EUC-JP
1090
1091Now you can start your terminal with C<LC_CTYPE=ja_JP.UTF-8> and still
1092use your input method. Please note, however, that, depending on your Xlib
1093version, you may not be able to input characters outside C<EUC-JP> in a
1094normal way then, as your input method limits you.
1095
1096=head3 Rxvt-unicode crashes when the X Input Method changes or exits.
1097
1098Unfortunately, this is unavoidable, as the XIM protocol is racy by
1099design. Applications can avoid some crashes at the expense of memory
1100leaks, and Input Methods can avoid some crashes by careful ordering at
1101exit time. B<kinput2> (and derived input methods) generally succeeds,
1102while B<SCIM> (or similar input methods) fails. In the end, however,
1103crashes cannot be completely avoided even if both sides cooperate.
1104
1105So the only workaround is not to kill your Input Method Servers.
1106
1107
1108=head2 Operating Systems / Package Maintaining
1109
1110=head3 I am using Debian GNU/Linux and have a problem...
1111
1112The Debian GNU/Linux package of rxvt-unicode in sarge contains large
1113patches that considerably change the behaviour of rxvt-unicode (but
1114unfortunately this notice has been removed). Before reporting a bug to
1115the original rxvt-unicode author please download and install the genuine
1116version (L<http://software.schmorp.de#rxvt-unicode>) and try to reproduce
1117the problem. If you cannot, chances are that the problems are specific to
1118Debian GNU/Linux, in which case it should be reported via the Debian Bug
1119Tracking System (use C<reportbug> to report the bug).
1120
1121For other problems that also affect the Debian package, you can and
1122probably should use the Debian BTS, too, because, after all, it's also a
1123bug in the Debian version and it serves as a reminder for other users that
1124might encounter the same issue.
1125
1126=head3 I am maintaining rxvt-unicode for distribution/OS XXX, any recommendation?
1127
1128You should build one binary with the default options. F<configure>
1129now enables most useful options, and the trend goes to making them
1130runtime-switchable, too, so there is usually no drawback to enabling them,
1131except higher disk and possibly memory usage. The perl interpreter should
1132be enabled, as important functionality (menus, selection, likely more in
1133the future) depends on it.
1134
1135You should not overwrite the C<perl-ext-common> snd C<perl-ext> resources
1136system-wide (except maybe with C<defaults>). This will result in useful
1137behaviour. If your distribution aims at low memory, add an empty
1138C<perl-ext-common> resource to the app-defaults file. This will keep the
1139perl interpreter disabled until the user enables it.
1140
1141If you can/want build more binaries, I recommend building a minimal
1142one with C<--disable-everything> (very useful) and a maximal one with
1143C<--enable-everything> (less useful, it will be very big due to a lot of
1144encodings built-in that increase download times and are rarely used).
1145
1146=head3 I need to make it setuid/setgid to support utmp/ptys on my OS, is this safe?
1147
1148It should be, starting with release 7.1. You are encouraged to properly
1149install urxvt with privileges necessary for your OS now.
1150
1151When rxvt-unicode detects that it runs setuid or setgid, it will fork
1152into a helper process for privileged operations (pty handling on some
1153systems, utmp/wtmp/lastlog handling on others) and drop privileges
1154immediately. This is much safer than most other terminals that keep
1155privileges while running (but is more relevant to urxvt, as it contains
1156things as perl interpreters, which might be "helpful" to attackers).
1157
1158This forking is done as the very first within main(), which is very early
1159and reduces possible bugs to initialisation code run before main(), or
1160things like the dynamic loader of your system, which should result in very
1161little risk.
1162
1163=head3 I am on FreeBSD and rxvt-unicode does not seem to work at all.
1164
1165Rxvt-unicode requires the symbol C<__STDC_ISO_10646__> to be defined
1166in your compile environment, or an implementation that implements it,
1167whether it defines the symbol or not. C<__STDC_ISO_10646__> requires that
1168B<wchar_t> is represented as unicode.
1169
1170As you might have guessed, FreeBSD does neither define this symbol nor
1171does it support it. Instead, it uses its own internal representation of
1172B<wchar_t>. This is, of course, completely fine with respect to standards.
1173
1174However, that means rxvt-unicode only works in C<POSIX>, C<ISO-8859-1> and
1175C<UTF-8> locales under FreeBSD (which all use Unicode as B<wchar_t>.
1176
1177C<__STDC_ISO_10646__> is the only sane way to support multi-language
1178apps in an OS, as using a locale-dependent (and non-standardized)
1179representation of B<wchar_t> makes it impossible to convert between
1180B<wchar_t> (as used by X11 and your applications) and any other encoding
1181without implementing OS-specific-wrappers for each and every locale. There
1182simply are no APIs to convert B<wchar_t> into anything except the current
1183locale encoding.
1184
1185Some applications (such as the formidable B<mlterm>) work around this
1186by carrying their own replacement functions for character set handling
1187with them, and either implementing OS-dependent hacks or doing multiple
1188conversions (which is slow and unreliable in case the OS implements
1189encodings slightly different than the terminal emulator).
1190
1191The rxvt-unicode author insists that the right way to fix this is in the
1192system libraries once and for all, instead of forcing every app to carry
1193complete replacements for them :)
1194
1195=head3 How can I use rxvt-unicode under cygwin?
1196
1197rxvt-unicode should compile and run out of the box on cygwin, using
1198the X11 libraries that come with cygwin. libW11 emulation is no
1199longer supported (and makes no sense, either, as it only supported a
1200single font). I recommend starting the X-server in C<-multiwindow> or
1201C<-rootless> mode instead, which will result in similar look&feel as the
1202old libW11 emulation.
1203
1204At the time of this writing, cygwin didn't seem to support any multi-byte
1205encodings (you might try C<LC_CTYPE=C-UTF-8>), so you are likely limited
1206to 8-bit encodings.
1207
1208=head3 Character widths are not correct.
1209
1210urxvt uses the system wcwidth function to know the information about
1211the width of characters, so on systems with incorrect locale data you
1212will likely get bad results. Two notorious examples are Solaris 9,
1213where single-width characters like U+2514 are reported as double-width,
1214and Darwin 8, where combining chars are reported having width 1.
1215
1216The solution is to upgrade your system or switch to a better one. A
1217possibly working workaround is to use a wcwidth implementation like
1218
1219http://www.cl.cam.ac.uk/~mgk25/ucs/wcwidth.c
1220
1221=head1 RXVT-UNICODE TECHNICAL REFERENCE
1222
18The rest of this document describes various technical aspects of 1223The rest of this document describes various technical aspects of
19B<rxvt-unicode>. First the description of supported command sequences, 1224B<rxvt-unicode>. First the description of supported command sequences,
20followed by menu and pixmap support and last by a description of all 1225followed by pixmap support and last by a description of all features
21features selectable at C<configure> time. 1226selectable at C<configure> time.
22 1227
23=head1 RXVT TECHNICAL REFERENCE
24
25=head1 Definitions 1228=head2 Definitions
26 1229
27=over 4 1230=over 4
28 1231
29=item B<< C<c> >> 1232=item B<< C<c> >>
30 1233
… …
48 1251
49A text parameter composed of printable characters. 1252A text parameter composed of printable characters.
50 1253
51=back 1254=back
52 1255
53=head1 Values 1256=head2 Values
54 1257
55=over 4 1258=over 4
56 1259
57=item B<< C<ENQ> >> 1260=item B<< C<ENQ> >>
58 1261
… …
101 1304
102Space Character 1305Space Character
103 1306
104=back 1307=back
105 1308
106=head1 Escape Sequences 1309=head2 Escape Sequences
107 1310
108=over 4 1311=over 4
109 1312
110=item B<< C<ESC # 8> >> 1313=item B<< C<ESC # 8> >>
111 1314
… …
157Single Shift Select of G3 Character Set (SS3): affects next character 1360Single Shift Select of G3 Character Set (SS3): affects next character
158only I<unimplemented> 1361only I<unimplemented>
159 1362
160=item B<< C<ESC Z> >> 1363=item B<< C<ESC Z> >>
161 1364
162Obsolete form of returns: B<< C<ESC[?1;2C> >> I<rxvt-unicode compile-time option> 1365Obsolete form of returns: B<< C<ESC [ ? 1 ; 2 C> >> I<rxvt-unicode compile-time option>
163 1366
164=item B<< C<ESC c> >> 1367=item B<< C<ESC c> >>
165 1368
166Full reset (RIS) 1369Full reset (RIS)
167 1370
… …
171 1374
172=item B<< C<ESC o> >> 1375=item B<< C<ESC o> >>
173 1376
174Invoke the G3 Character Set (LS3) 1377Invoke the G3 Character Set (LS3)
175 1378
176=item B<< C<ESC> ( C> >> 1379=item B<< C<ESC ( C> >>
177 1380
178Designate G0 Character Set (ISO 2022), see below for values of C<C>. 1381Designate G0 Character Set (ISO 2022), see below for values of C<C>.
179 1382
180=item B<< C<ESC> ) C> >> 1383=item B<< C<ESC ) C> >>
181 1384
182Designate G1 Character Set (ISO 2022), see below for values of C<C>. 1385Designate G1 Character Set (ISO 2022), see below for values of C<C>.
183 1386
184=item B<< C<ESC * C> >> 1387=item B<< C<ESC * C> >>
185 1388
… …
209 1412
210=back 1413=back
211 1414
212X<CSI> 1415X<CSI>
213 1416
214=head1 CSI (Command Sequence Introducer) Sequences 1417=head2 CSI (Command Sequence Introducer) Sequences
215 1418
216=over 4 1419=over 4
217 1420
218=item B<< C<ESC [ Ps @> >> 1421=item B<< C<ESC [ Ps @> >>
219 1422
… …
326 1529
327=item B<< C<ESC [ Ps c> >> 1530=item B<< C<ESC [ Ps c> >>
328 1531
329Send Device Attributes (DA) 1532Send Device Attributes (DA)
330B<< C<Ps = 0> >> (or omitted): request attributes from terminal 1533B<< C<Ps = 0> >> (or omitted): request attributes from terminal
331returns: B<< C<ESC[?1;2c> >> (``I am a VT100 with Advanced Video 1534returns: B<< C<ESC [ ? 1 ; 2 c> >> (``I am a VT100 with Advanced Video
332Option'') 1535Option'')
333 1536
334=item B<< C<ESC [ Ps d> >> 1537=item B<< C<ESC [ Ps d> >>
335 1538
336Cursor to Line B<< C<Ps> >> (VPA) 1539Cursor to Line B<< C<Ps> >> (VPA)
… …
452 1655
453=item B<< C<ESC [ s> >> 1656=item B<< C<ESC [ s> >>
454 1657
455Save Cursor (SC) 1658Save Cursor (SC)
456 1659
1660=item B<< C<ESC [ Ps;Pt t> >>
1661
1662Window Operations
1663
1664=begin table
1665
1666 B<< C<Ps = 1> >> Deiconify (map) window
1667 B<< C<Ps = 2> >> Iconify window
1668 B<< C<Ps = 3> >> B<< C<ESC [ 3 ; X ; Y t> >> Move window to (X|Y)
1669 B<< C<Ps = 4> >> B<< C<ESC [ 4 ; H ; W t> >> Resize to WxH pixels
1670 B<< C<Ps = 5> >> Raise window
1671 B<< C<Ps = 6> >> Lower window
1672 B<< C<Ps = 7> >> Refresh screen once
1673 B<< C<Ps = 8> >> B<< C<ESC [ 8 ; R ; C t> >> Resize to R rows and C columns
1674 B<< C<Ps = 11> >> Report window state (responds with C<Ps = 1> or C<Ps = 2>)
1675 B<< C<Ps = 13> >> Report window position (responds with C<Ps = 3>)
1676 B<< C<Ps = 14> >> Report window pixel size (responds with C<Ps = 4>)
1677 B<< C<Ps = 18> >> Report window text size (responds with C<Ps = 7>)
1678 B<< C<Ps = 19> >> Currently the same as C<Ps = 18>, but responds with C<Ps = 9>
1679 B<< C<Ps = 20> >> Reports icon label (B<< C<ESC ] L NAME \234> >>)
1680 B<< C<Ps = 21> >> Reports window title (B<< C<ESC ] l NAME \234> >>)
1681 B<< C<Ps = 24..> >> Set window height to C<Ps> rows
1682
1683=end table
1684
1685=item B<< C<ESC [ u> >>
1686
1687Restore Cursor
1688
457=item B<< C<ESC [ Ps x> >> 1689=item B<< C<ESC [ Ps x> >>
458 1690
459Request Terminal Parameters (DECREQTPARM) 1691Request Terminal Parameters (DECREQTPARM)
460 1692
461=item B<< C<ESC [ u> >>
462
463Restore Cursor
464
465=back 1693=back
466 1694
467X<PrivateModes> 1695X<PrivateModes>
468 1696
469=head1 DEC Private Modes 1697=head2 DEC Private Modes
470 1698
471=over 4 1699=over 4
472 1700
473=item B<< C<ESC [ ? Pm h> >> 1701=item B<< C<ESC [ ? Pm h> >>
474 1702
… …
490 1718
491Toggle DEC Private Mode Values (rxvt extension). I<where> 1719Toggle DEC Private Mode Values (rxvt extension). I<where>
492 1720
493=over 4 1721=over 4
494 1722
495=item B<< C<Ps = 1> >> (DECCKM) 1723=item B<< C<Pm = 1> >> (DECCKM)
496 1724
497=begin table 1725=begin table
498 1726
499 B<< C<h> >> Application Cursor Keys 1727 B<< C<h> >> Application Cursor Keys
500 B<< C<l> >> Normal Cursor Keys 1728 B<< C<l> >> Normal Cursor Keys
501 1729
502=end table 1730=end table
503 1731
504=item B<< C<Ps = 2> >> (ANSI/VT52 mode) 1732=item B<< C<Pm = 2> >> (ANSI/VT52 mode)
505 1733
506=begin table 1734=begin table
507 1735
508 B<< C<h> >> Enter VT52 mode 1736 B<< C<h> >> Enter VT52 mode
509 B<< C<l> >> Enter VT52 mode 1737 B<< C<l> >> Enter VT52 mode
510 1738
511=end table 1739=end table
512 1740
513=item B<< C<Ps = 3> >> 1741=item B<< C<Pm = 3> >>
514 1742
515=begin table 1743=begin table
516 1744
517 B<< C<h> >> 132 Column Mode (DECCOLM) 1745 B<< C<h> >> 132 Column Mode (DECCOLM)
518 B<< C<l> >> 80 Column Mode (DECCOLM) 1746 B<< C<l> >> 80 Column Mode (DECCOLM)
519 1747
520=end table 1748=end table
521 1749
522=item B<< C<Ps = 4> >> 1750=item B<< C<Pm = 4> >>
523 1751
524=begin table 1752=begin table
525 1753
526 B<< C<h> >> Smooth (Slow) Scroll (DECSCLM) 1754 B<< C<h> >> Smooth (Slow) Scroll (DECSCLM)
527 B<< C<l> >> Jump (Fast) Scroll (DECSCLM) 1755 B<< C<l> >> Jump (Fast) Scroll (DECSCLM)
528 1756
529=end table 1757=end table
530 1758
531=item B<< C<Ps = 5> >> 1759=item B<< C<Pm = 5> >>
532 1760
533=begin table 1761=begin table
534 1762
535 B<< C<h> >> Reverse Video (DECSCNM) 1763 B<< C<h> >> Reverse Video (DECSCNM)
536 B<< C<l> >> Normal Video (DECSCNM) 1764 B<< C<l> >> Normal Video (DECSCNM)
537 1765
538=end table 1766=end table
539 1767
540=item B<< C<Ps = 6> >> 1768=item B<< C<Pm = 6> >>
541 1769
542=begin table 1770=begin table
543 1771
544 B<< C<h> >> Origin Mode (DECOM) 1772 B<< C<h> >> Origin Mode (DECOM)
545 B<< C<l> >> Normal Cursor Mode (DECOM) 1773 B<< C<l> >> Normal Cursor Mode (DECOM)
546 1774
547=end table 1775=end table
548 1776
549=item B<< C<Ps = 7> >> 1777=item B<< C<Pm = 7> >>
550 1778
551=begin table 1779=begin table
552 1780
553 B<< C<h> >> Wraparound Mode (DECAWM) 1781 B<< C<h> >> Wraparound Mode (DECAWM)
554 B<< C<l> >> No Wraparound Mode (DECAWM) 1782 B<< C<l> >> No Wraparound Mode (DECAWM)
555 1783
556=end table 1784=end table
557 1785
558=item B<< C<Ps = 8> >> I<unimplemented> 1786=item B<< C<Pm = 8> >> I<unimplemented>
559 1787
560=begin table 1788=begin table
561 1789
562 B<< C<h> >> Auto-repeat Keys (DECARM) 1790 B<< C<h> >> Auto-repeat Keys (DECARM)
563 B<< C<l> >> No Auto-repeat Keys (DECARM) 1791 B<< C<l> >> No Auto-repeat Keys (DECARM)
564 1792
565=end table 1793=end table
566 1794
567=item B<< C<Ps = 9> >> X10 XTerm 1795=item B<< C<Pm = 9> >> X10 XTerm
568 1796
569=begin table 1797=begin table
570 1798
571 B<< C<h> >> Send Mouse X & Y on button press. 1799 B<< C<h> >> Send Mouse X & Y on button press.
572 B<< C<l> >> No mouse reporting. 1800 B<< C<l> >> No mouse reporting.
573 1801
574=end table 1802=end table
575 1803
576=item B<< C<Ps = 10> >> (B<rxvt>)
577
578=begin table
579
580 B<< C<h> >> menuBar visible
581 B<< C<l> >> menuBar invisible
582
583=end table
584
585=item B<< C<Ps = 25> >> 1804=item B<< C<Pm = 25> >>
586 1805
587=begin table 1806=begin table
588 1807
589 B<< C<h> >> Visible cursor {cnorm/cvvis} 1808 B<< C<h> >> Visible cursor {cnorm/cvvis}
590 B<< C<l> >> Invisible cursor {civis} 1809 B<< C<l> >> Invisible cursor {civis}
591 1810
592=end table 1811=end table
593 1812
594=item B<< C<Ps = 30> >> 1813=item B<< C<Pm = 30> >>
595 1814
596=begin table 1815=begin table
597 1816
598 B<< C<h> >> scrollBar visisble 1817 B<< C<h> >> scrollBar visible
599 B<< C<l> >> scrollBar invisisble 1818 B<< C<l> >> scrollBar invisible
600 1819
601=end table 1820=end table
602 1821
603=item B<< C<Ps = 35> >> (B<rxvt>) 1822=item B<< C<Pm = 35> >> (B<rxvt>)
604 1823
605=begin table 1824=begin table
606 1825
607 B<< C<h> >> Allow XTerm Shift+key sequences 1826 B<< C<h> >> Allow XTerm Shift+key sequences
608 B<< C<l> >> Disallow XTerm Shift+key sequences 1827 B<< C<l> >> Disallow XTerm Shift+key sequences
609 1828
610=end table 1829=end table
611 1830
612=item B<< C<Ps = 38> >> I<unimplemented> 1831=item B<< C<Pm = 38> >> I<unimplemented>
613 1832
614Enter Tektronix Mode (DECTEK) 1833Enter Tektronix Mode (DECTEK)
615 1834
616=item B<< C<Ps = 40> >> 1835=item B<< C<Pm = 40> >>
617 1836
618=begin table 1837=begin table
619 1838
620 B<< C<h> >> Allow 80/132 Mode 1839 B<< C<h> >> Allow 80/132 Mode
621 B<< C<l> >> Disallow 80/132 Mode 1840 B<< C<l> >> Disallow 80/132 Mode
622 1841
623=end table 1842=end table
624 1843
625=item B<< C<Ps = 44> >> I<unimplemented> 1844=item B<< C<Pm = 44> >> I<unimplemented>
626 1845
627=begin table 1846=begin table
628 1847
629 B<< C<h> >> Turn On Margin Bell 1848 B<< C<h> >> Turn On Margin Bell
630 B<< C<l> >> Turn Off Margin Bell 1849 B<< C<l> >> Turn Off Margin Bell
631 1850
632=end table 1851=end table
633 1852
634=item B<< C<Ps = 45> >> I<unimplemented> 1853=item B<< C<Pm = 45> >> I<unimplemented>
635 1854
636=begin table 1855=begin table
637 1856
638 B<< C<h> >> Reverse-wraparound Mode 1857 B<< C<h> >> Reverse-wraparound Mode
639 B<< C<l> >> No Reverse-wraparound Mode 1858 B<< C<l> >> No Reverse-wraparound Mode
640 1859
641=end table 1860=end table
642 1861
643=item B<< C<Ps = 46> >> I<unimplemented> 1862=item B<< C<Pm = 46> >> I<unimplemented>
644 1863
645=item B<< C<Ps = 47> >> 1864=item B<< C<Pm = 47> >>
646 1865
647=begin table 1866=begin table
648 1867
649 B<< C<h> >> Use Alternate Screen Buffer 1868 B<< C<h> >> Use Alternate Screen Buffer
650 B<< C<l> >> Use Normal Screen Buffer 1869 B<< C<l> >> Use Normal Screen Buffer
651 1870
652=end table 1871=end table
653 1872
654X<Priv66> 1873X<Priv66>
655 1874
656=item B<< C<Ps = 66> >> 1875=item B<< C<Pm = 66> >>
657 1876
658=begin table 1877=begin table
659 1878
660 B<< C<h> >> Application Keypad (DECPAM) == C<ESC => 1879 B<< C<h> >> Application Keypad (DECPAM) == C<ESC =>
661 B<< C<l> >> Normal Keypad (DECPNM) == C<< ESC > >> 1880 B<< C<l> >> Normal Keypad (DECPNM) == C<< ESC > >>
662 1881
663=end table 1882=end table
664 1883
665=item B<< C<Ps = 67> >> 1884=item B<< C<Pm = 67> >>
666 1885
667=begin table 1886=begin table
668 1887
669 B<< C<h> >> Backspace key sends B<< C<BS> (DECBKM) >> 1888 B<< C<h> >> Backspace key sends B<< C<BS> (DECBKM) >>
670 B<< C<l> >> Backspace key sends B<< C<DEL> >> 1889 B<< C<l> >> Backspace key sends B<< C<DEL> >>
671 1890
672=end table 1891=end table
673 1892
674=item B<< C<Ps = 1000> >> (X11 XTerm) 1893=item B<< C<Pm = 1000> >> (X11 XTerm)
675 1894
676=begin table 1895=begin table
677 1896
678 B<< C<h> >> Send Mouse X & Y on button press and release. 1897 B<< C<h> >> Send Mouse X & Y on button press and release.
679 B<< C<l> >> No mouse reporting. 1898 B<< C<l> >> No mouse reporting.
680 1899
681=end table 1900=end table
682 1901
683=item B<< C<Ps = 1001> >> (X11 XTerm) I<unimplemented> 1902=item B<< C<Pm = 1001> >> (X11 XTerm) I<unimplemented>
684 1903
685=begin table 1904=begin table
686 1905
687 B<< C<h> >> Use Hilite Mouse Tracking. 1906 B<< C<h> >> Use Hilite Mouse Tracking.
688 B<< C<l> >> No mouse reporting. 1907 B<< C<l> >> No mouse reporting.
689 1908
690=end table 1909=end table
691 1910
1911=item B<< C<Pm = 1002> >> (X11 XTerm)
1912
1913=begin table
1914
1915 B<< C<h> >> Send Mouse X & Y on button press and release, and motion with a button pressed.
1916 B<< C<l> >> No mouse reporting.
1917
1918=end table
1919
1920=item B<< C<Pm = 1003> >> (X11 XTerm)
1921
1922=begin table
1923
1924 B<< C<h> >> Send Mouse X & Y on button press and release, and motion.
1925 B<< C<l> >> No mouse reporting.
1926
1927=end table
1928
692=item B<< C<Ps = 1010> >> (B<rxvt>) 1929=item B<< C<Pm = 1010> >> (B<rxvt>)
693 1930
694=begin table 1931=begin table
695 1932
696 B<< C<h> >> Don't scroll to bottom on TTY output 1933 B<< C<h> >> Don't scroll to bottom on TTY output
697 B<< C<l> >> Scroll to bottom on TTY output 1934 B<< C<l> >> Scroll to bottom on TTY output
698 1935
699=end table 1936=end table
700 1937
701=item B<< C<Ps = 1011> >> (B<rxvt>) 1938=item B<< C<Pm = 1011> >> (B<rxvt>)
702 1939
703=begin table 1940=begin table
704 1941
705 B<< C<h> >> Scroll to bottom when a key is pressed 1942 B<< C<h> >> Scroll to bottom when a key is pressed
706 B<< C<l> >> Don't scroll to bottom when a key is pressed 1943 B<< C<l> >> Don't scroll to bottom when a key is pressed
707 1944
708=end table 1945=end table
709 1946
1947=item B<< C<Pm = 1021> >> (B<rxvt>)
1948
1949=begin table
1950
1951 B<< C<h> >> Bold/italic implies high intensity (see option B<-is>)
1952 B<< C<l> >> Font styles have no effect on intensity (Compile styles)
1953
1954=end table
1955
710=item B<< C<Ps = 1047> >> 1956=item B<< C<Pm = 1047> >>
711 1957
712=begin table 1958=begin table
713 1959
714 B<< C<h> >> Use Alternate Screen Buffer 1960 B<< C<h> >> Use Alternate Screen Buffer
715 B<< C<l> >> Use Normal Screen Buffer - clear Alternate Screen Buffer if returning from it 1961 B<< C<l> >> Use Normal Screen Buffer - clear Alternate Screen Buffer if returning from it
716 1962
717=end table 1963=end table
718 1964
719=item B<< C<Ps = 1048> >> 1965=item B<< C<Pm = 1048> >>
720 1966
721=begin table 1967=begin table
722 1968
723 B<< C<h> >> Save cursor position 1969 B<< C<h> >> Save cursor position
724 B<< C<l> >> Restore cursor position 1970 B<< C<l> >> Restore cursor position
725 1971
726=end table 1972=end table
727 1973
728=item B<< C<Ps = 1049> >> 1974=item B<< C<Pm = 1049> >>
729 1975
730=begin table 1976=begin table
731 1977
732 B<< C<h> >> Use Alternate Screen Buffer - clear Alternate Screen Buffer if switching to it 1978 B<< C<h> >> Use Alternate Screen Buffer - clear Alternate Screen Buffer if switching to it
733 B<< C<l> >> Use Normal Screen Buffer 1979 B<< C<l> >> Use Normal Screen Buffer
… …
738 1984
739=back 1985=back
740 1986
741X<XTerm> 1987X<XTerm>
742 1988
743=head1 XTerm Operating System Commands 1989=head2 XTerm Operating System Commands
744 1990
745=over 4 1991=over 4
746 1992
747=item B<< C<ESC ] Ps;Pt ST> >> 1993=item B<< C<ESC ] Ps;Pt ST> >>
748 1994
… …
755 B<< C<Ps = 0> >> Change Icon Name and Window Title to B<< C<Pt> >> 2001 B<< C<Ps = 0> >> Change Icon Name and Window Title to B<< C<Pt> >>
756 B<< C<Ps = 1> >> Change Icon Name to B<< C<Pt> >> 2002 B<< C<Ps = 1> >> Change Icon Name to B<< C<Pt> >>
757 B<< C<Ps = 2> >> Change Window Title to B<< C<Pt> >> 2003 B<< C<Ps = 2> >> Change Window Title to B<< C<Pt> >>
758 B<< C<Ps = 3> >> If B<< C<Pt> >> starts with a B<< C<?> >>, query the (STRING) property of the window and return it. If B<< C<Pt> >> contains a B<< C<=> >>, set the named property to the given value, else delete the specified property. 2004 B<< C<Ps = 3> >> If B<< C<Pt> >> starts with a B<< C<?> >>, query the (STRING) property of the window and return it. If B<< C<Pt> >> contains a B<< C<=> >>, set the named property to the given value, else delete the specified property.
759 B<< C<Ps = 4> >> B<< C<Pt> >> is a semi-colon separated sequence of one or more semi-colon separated B<number>/B<name> pairs, where B<number> is an index to a colour and B<name> is the name of a colour. Each pair causes the B<number>ed colour to be changed to B<name>. 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 2005 B<< C<Ps = 4> >> B<< C<Pt> >> is a semi-colon separated sequence of one or more semi-colon separated B<number>/B<name> pairs, where B<number> is an index to a colour and B<name> is the name of a colour. Each pair causes the B<number>ed colour to be changed to B<name>. 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
760 B<< C<Ps = 10> >> Change colour of text foreground to B<< C<Pt> >> B<(NB: may change in future)> 2006 B<< C<Ps = 10> >> Change colour of text foreground to B<< C<Pt> >>
761 B<< C<Ps = 11> >> Change colour of text background to B<< C<Pt> >> B<(NB: may change in future)> 2007 B<< C<Ps = 11> >> Change colour of text background to B<< C<Pt> >>
762 B<< C<Ps = 12> >> Change colour of text cursor foreground to B<< C<Pt> >> 2008 B<< C<Ps = 12> >> Change colour of text cursor foreground to B<< C<Pt> >>
763 B<< C<Ps = 13> >> Change colour of mouse foreground to B<< C<Pt> >> 2009 B<< C<Ps = 13> >> Change colour of mouse foreground to B<< C<Pt> >>
764 B<< C<Ps = 17> >> Change colour of highlight characters to B<< C<Pt> >> 2010 B<< C<Ps = 17> >> Change colour of highlight characters to B<< C<Pt> >>
765 B<< C<Ps = 18> >> Change colour of bold characters to B<< C<Pt> >> 2011 B<< C<Ps = 18> >> Change colour of bold characters to B<< C<Pt> >> [deprecated, see 706]
766 B<< C<Ps = 19> >> Change colour of underlined characters to B<< C<Pt> >> 2012 B<< C<Ps = 19> >> Change colour of underlined characters to B<< C<Pt> >> [deprecated, see 707]
767 B<< C<Ps = 20> >> Change default background to B<< C<Pt> >> 2013 B<< C<Ps = 20> >> Change background pixmap parameters (see section BACKGROUND IMAGE) (Compile AfterImage).
768 B<< C<Ps = 39> >> Change default foreground colour to B<< C<Pt> >> I<rxvt compile-time option> 2014 B<< C<Ps = 39> >> Change default foreground colour to B<< C<Pt> >>. [deprecated, use 10]
769 B<< C<Ps = 46> >> Change Log File to B<< C<Pt> >> I<unimplemented> 2015 B<< C<Ps = 46> >> Change Log File to B<< C<Pt> >> I<unimplemented>
770 B<< C<Ps = 49> >> Change default background colour to B<< C<Pt> >> I<rxvt compile-time option> 2016 B<< C<Ps = 49> >> Change default background colour to B<< C<Pt> >>. [deprecated, use 11]
771 B<< C<Ps = 50> >> Set fontset to B<< C<Pt> >>, with the following special values of B<< C<Pt> >> (B<rxvt>) B<< C<#+n> >> change up B<< C<n> >> B<< C<#-n> >> change down B<< C<n> >> if B<< C<n> >> is missing of 0, a value of 1 is used I<empty> change to font0 B<< C<n> >> change to font B<< C<n> >> 2017 B<< C<Ps = 50> >> Set fontset to B<< C<Pt> >>, with the following special values of B<< C<Pt> >> (B<rxvt>) B<< C<#+n> >> change up B<< C<n> >> B<< C<#-n> >> change down B<< C<n> >> if B<< C<n> >> is missing of 0, a value of 1 is used I<empty> change to font0 B<< C<n> >> change to font B<< C<n> >>
772 B<< C<Ps = 55> >> Log all scrollback buffer and all of screen to B<< C<Pt> >> 2018 B<< C<Ps = 55> >> Log all scrollback buffer and all of screen to B<< C<Pt> >>
773 B<< C<Ps = 701> >> Change current locale to B<< C<Pt> >>, or, if B<< C<Pt> >> is B<< C<?> >>, return the current locale (@@RXVT_NAME@@ extension) 2019 B<< C<Ps = 701> >> Change current locale to B<< C<Pt> >>, or, if B<< C<Pt> >> is B<< C<?> >>, return the current locale (Compile frills).
774 B<< C<Ps = 703> >> Menubar command B<< C<Pt> >> I<rxvt compile-time option> (rxvt-unicode extension) 2020 B<< C<Ps = 702> >> Request version if B<< C<Pt> >> is B<< C<?> >>, returning C<rxvt-unicode>, the resource name, the major and minor version numbers, e.g. C<ESC ] 702 ; rxvt-unicode ; urxvt ; 7 ; 4 ST>.
775 B<< C<Ps = 704> >> Change colour of italic characters to B<< C<Pt> >> 2021 B<< C<Ps = 704> >> Change colour of italic characters to B<< C<Pt> >>
776 B<< C<Ps = 705> >> Change background pixmap tint colour to B<< C<Pt> >> 2022 B<< C<Ps = 705> >> Change background pixmap tint colour to B<< C<Pt> >> (Compile transparency).
2023 B<< C<Ps = 706> >> Change colour of bold characters to B<< C<Pt> >>
2024 B<< C<Ps = 707> >> Change colour of underlined characters to B<< C<Pt> >>
777 B<< C<Ps = 710> >> Set normal fontset to B<< C<Pt> >>. Same as C<Ps = 50>. 2025 B<< C<Ps = 710> >> Set normal fontset to B<< C<Pt> >>. Same as C<Ps = 50>.
778 B<< C<Ps = 711> >> Set bold fontset to B<< C<Pt> >>. Similar to C<Ps = 50>. 2026 B<< C<Ps = 711> >> Set bold fontset to B<< C<Pt> >>. Similar to C<Ps = 50> (Compile styles).
779 B<< C<Ps = 712> >> Set italic fontset to B<< C<Pt> >>. Similar to C<Ps = 50>. 2027 B<< C<Ps = 712> >> Set italic fontset to B<< C<Pt> >>. Similar to C<Ps = 50> (Compile styles).
780 B<< C<Ps = 713> >> Set bold-italic fontset to B<< C<Pt> >>. Similar to C<Ps = 50>. 2028 B<< C<Ps = 713> >> Set bold-italic fontset to B<< C<Pt> >>. Similar to C<Ps = 50> (Compile styles).
2029 B<< C<Ps = 720> >> Move viewing window up by B<< C<Pt> >> lines, or clear scrollback buffer if C<Pt = 0> (Compile frills).
2030 B<< C<Ps = 721> >> Move viewing window down by B<< C<Pt> >> lines, or clear scrollback buffer if C<Pt = 0> (Compile frills).
2031 B<< C<Ps = 777> >> Call the perl extension with the given string, which should be of the form C<extension:parameters> (Compile perl).
781 2032
782=end table 2033=end table
783 2034
784=back 2035=back
785 2036
786X<menuBar> 2037=head1 BACKGROUND IMAGE
787 2038
788=head1 menuBar
789
790B<< The exact syntax used is I<almost> solidified. >>
791In the menus, B<DON'T> try to use menuBar commands that add or remove a
792menuBar.
793
794Note that in all of the commands, the B<< I</path/> >> I<cannot> be
795omitted: use B<./> to specify a menu relative to the current menu.
796
797=head2 Overview of menuBar operation
798
799For the menuBar XTerm escape sequence C<ESC ] 703 ; Pt ST>, the syntax
800of C<Pt> can be used for a variety of tasks:
801
802At the top level is the current menuBar which is a member of a circular
803linked-list of other such menuBars.
804
805The menuBar acts as a parent for the various drop-down menus, which in
806turn, may have labels, separator lines, menuItems and subMenus.
807
808The menuItems are the useful bits: you can use them to mimic keyboard
809input or even to send text or escape sequences back to rxvt.
810
811The menuBar syntax is intended to provide a simple yet robust method of
812constructing and manipulating menus and navigating through the
813menuBars.
814
815The first step is to use the tag B<< [menu:I<name>] >> which creates
816the menuBar called I<name> and allows access. You may now or menus,
817subMenus, and menuItems. Finally, use the tag B<[done]> to set the
818menuBar access as B<readonly> to prevent accidental corruption of the
819menus. To re-access the current menuBar for alterations, use the tag
820B<[menu]>, make the alterations and then use B<[done]>
821
822X<menuBarCommands>
823
824=head2 Commands
825
826=over 4
827
828=item B<< [menu:+I<name>] >>
829
830access the named menuBar for creation or alteration. If a new menuBar
831is created, it is called I<name> (max of 15 chars) and the current
832menuBar is pushed onto the stack
833
834=item B<[menu]>
835
836access the current menuBar for alteration
837
838=item B<< [title:+I<string>] >>
839
840set the current menuBar's title to I<string>, which may contain the
841following format specifiers:
842B<%%> : literal B<%> character
843B<%n> : rxvt name (as per the B<-name> command-line option)
844B<%v> : rxvt version
845
846=item B<[done]>
847
848set menuBar access as B<readonly>.
849End-of-file tag for B<< [read:+I<file>] >> operations.
850
851=item B<< [read:+I<file>] >>
852
853read menu commands directly from I<file> (extension ".menu" will be
854appended if required.) Start reading at a line with B<[menu]> or B<<
855[menu:+I<name> >> and continuing until B<[done]> is encountered.
856
857Blank and comment lines (starting with B<#>) are ignored. Actually,
858since any invalid menu commands are also ignored, almost anything could
859be construed as a comment line, but this may be tightened up in the
860future ... so don't count on it!.
861
862=item B<< [read:+I<file>;+I<name>] >>
863
864The same as B<< [read:+I<file>] >>, but start reading at a line with
865B<< [menu:+I<name>] >> and continuing until B<< [done:+I<name>] >> or
866B<[done]> is encountered.
867
868=item B<[dump]>
869
870dump all menuBars to the file B</tmp/rxvt-PID> in a format suitable for
871later rereading.
872
873=item B<[rm:name]>
874
875remove the named menuBar
876
877=item B<[rm] [rm:]>
878
879remove the current menuBar
880
881=item B<[rm*] [rm:*]>
882
883remove all menuBars
884
885=item B<[swap]>
886
887swap the top two menuBars
888
889=item B<[prev]>
890
891access the previous menuBar
892
893=item B<[next]>
894
895access the next menuBar
896
897=item B<[show]>
898
899Enable display of the menuBar
900
901=item B<[hide]>
902
903Disable display of the menuBar
904
905=item B<< [pixmap:+I<name>] >>
906
907=item B<< [pixmap:+I<name>;I<scaling>] >>
908
909(set the background pixmap globally
910
911B<< A Future implementation I<may> make this local to the menubar >>)
912
913=item B<< [:+I<command>:] >>
914
915ignore the menu readonly status and issue a I<command> to or a menu or
916menuitem or change the ; a useful shortcut for setting the quick arrows
917from a menuBar.
918
919=back
920
921X<menuBarAdd>
922
923=head2 Adding and accessing menus
924
925The following commands may also be B<+> prefixed.
926
927=over 4
928
929=item B</+>
930
931access menuBar top level
932
933=item B<./+>
934
935access current menu level
936
937=item B<../+>
938
939access parent menu (1 level up)
940
941=item B<../../>
942
943access parent menu (multiple levels up)
944
945=item B<< I</path/>menu >>
946
947add/access menu
948
949=item B<< I</path/>menu/* >>
950
951add/access menu and clear it if it exists
952
953=item B<< I</path/>{-} >>
954
955add separator
956
957=item B<< I</path/>{item} >>
958
959add B<item> as a label
960
961=item B<< I</path/>{item} action >>
962
963add/alter I<menuitem> with an associated I<action>
964
965=item B<< I</path/>{item}{right-text} >>
966
967add/alter I<menuitem> with B<right-text> as the right-justified text
968and as the associated I<action>
969
970=item B<< I</path/>{item}{rtext} action >>
971
972add/alter I<menuitem> with an associated I<action> and with B<rtext> as
973the right-justified text.
974
975=back
976
977=over 4
978
979=item Special characters in I<action> must be backslash-escaped:
980
981B<\a \b \E \e \n \r \t \octal>
982
983=item or in control-character notation:
984
985B<^@, ^A .. ^Z .. ^_, ^?>
986
987=back
988
989To send a string starting with a B<NUL> (B<^@>) character to the
990program, start I<action> with a pair of B<NUL> characters (B<^@^@>),
991the first of which will be stripped off and the balance directed to the
992program. Otherwise if I<action> begins with B<NUL> followed by
993non-+B<NUL> characters, the leading B<NUL> is stripped off and the
994balance is sent back to rxvt.
995
996As a convenience for the many Emacs-type editors, I<action> may start
997with B<M-> (eg, B<M-$> is equivalent to B<\E$>) and a B<CR> will be
998appended if missed from B<M-x> commands.
999
1000As a convenience for issuing XTerm B<ESC]> sequences from a menubar (or
1001quick arrow), a B<BEL> (B<^G>) will be appended if needed.
1002
1003=over 4
1004
1005=item For example,
1006
1007B<M-xapropos> is equivalent to B<\Exapropos\r>
1008
1009=item and
1010
1011B<\E]703;mona;100> is equivalent to B<\E]703;mona;100\a>
1012
1013=back
1014
1015The option B<< {I<right-rtext>} >> will be right-justified. In the
1016absence of a specified action, this text will be used as the I<action>
1017as well.
1018
1019=over 4
1020
1021=item For example,
1022
1023B</File/{Open}{^X^F}> is equivalent to B</File/{Open}{^X^F} ^X^F>
1024
1025=back
1026
1027The left label I<is> necessary, since it's used for matching, but
1028implicitly hiding the left label (by using same name for both left and
1029right labels), or explicitly hiding the left label (by preceeding it
1030with a dot), makes it possible to have right-justified text only.
1031
1032=over 4
1033
1034=item For example,
1035
1036B</File/{Open}{Open} Open-File-Action>
1037
1038=item or hiding it
1039
1040B</File/{.anylabel}{Open} Open-File-Action>
1041
1042=back
1043
1044X<menuBarRemove>
1045
1046=head2 Removing menus
1047
1048=over 4
1049
1050=item B<< -/*+ >>
1051
1052remove all menus from the menuBar, the same as B<[clear]>
1053
1054=item B<< -+I</path>menu+ >>
1055
1056remove menu
1057
1058=item B<< -+I</path>{item}+ >>
1059
1060remove item
1061
1062=item B<< -+I</path>{-} >>
1063
1064remove separator)
1065
1066=item B<-/path/menu/*>
1067
1068remove all items, separators and submenus from menu
1069
1070=back
1071
1072X<menuBarArrows>
1073
1074=head2 Quick Arrows
1075
1076The menus also provide a hook for I<quick arrows> to provide easier
1077user access. If nothing has been explicitly set, the default is to
1078emulate the curror keys. The syntax permits each arrow to be altered
1079individually or all four at once without re-entering their common
1080beginning/end text. For example, to explicitly associate cursor actions
1081with the arrows, any of the following forms could be used:
1082
1083=over 4
1084
1085=item B<< <r>+I<Right> >>
1086
1087=item B<< <l>+I<Left> >>
1088
1089=item B<< <u>+I<Up> >>
1090
1091=item B<< <d>+I<Down> >>
1092
1093Define actions for the respective arrow buttons
1094
1095=item B<< <b>+I<Begin> >>
1096
1097=item B<< <e>+I<End> >>
1098
1099Define common beginning/end parts for I<quick arrows> which used in
1100conjunction with the above <r> <l> <u> <d> constructs
1101
1102=back
1103
1104=over 4
1105
1106=item For example, define arrows individually,
1107
1108 <u>\E[A
1109
1110 <d>\E[B
1111
1112 <r>\E[C
1113
1114 <l>\E[D
1115
1116=item or all at once
1117
1118 <u>\E[AZ<><d>\E[BZ<><r>\E[CZ<><l>\E[D
1119
1120=item or more compactly (factoring out common parts)
1121
1122 <b>\E[<u>AZ<><d>BZ<><r>CZ<><l>D
1123
1124=back
1125
1126X<menuBarSummary>
1127
1128=head2 Command Summary
1129
1130A short summary of the most I<common> commands:
1131
1132=over 4
1133
1134=item [menu:name]
1135
1136use an existing named menuBar or start a new one
1137
1138=item [menu]
1139
1140use the current menuBar
1141
1142=item [title:string]
1143
1144set menuBar title
1145
1146=item [done]
1147
1148set menu access to readonly and, if reading from a file, signal EOF
1149
1150=item [done:name]
1151
1152if reading from a file using [read:file;name] signal EOF
1153
1154=item [rm:name]
1155
1156remove named menuBar(s)
1157
1158=item [rm] [rm:]
1159
1160remove current menuBar
1161
1162=item [rm*] [rm:*]
1163
1164remove all menuBar(s)
1165
1166=item [swap]
1167
1168swap top two menuBars
1169
1170=item [prev]
1171
1172access the previous menuBar
1173
1174=item [next]
1175
1176access the next menuBar
1177
1178=item [show]
1179
1180map menuBar
1181
1182=item [hide]
1183
1184unmap menuBar
1185
1186=item [pixmap;file]
1187
1188=item [pixmap;file;scaling]
1189
1190set a background pixmap
1191
1192=item [read:file]
1193
1194=item [read:file;name]
1195
1196read in a menu from a file
1197
1198=item [dump]
1199
1200dump out all menuBars to /tmp/rxvt-PID
1201
1202=item /
1203
1204access menuBar top level
1205
1206=item ./
1207
1208=item ../
1209
1210=item ../../
1211
1212access current or parent menu level
1213
1214=item /path/menu
1215
1216add/access menu
1217
1218=item /path/{-}
1219
1220add separator
1221
1222=item /path/{item}{rtext} action
1223
1224add/alter menu item
1225
1226=item -/*
1227
1228remove all menus from the menuBar
1229
1230=item -/path/menu
1231
1232remove menu items, separators and submenus from menu
1233
1234=item -/path/menu
1235
1236remove menu
1237
1238=item -/path/{item}
1239
1240remove item
1241
1242=item -/path/{-}
1243
1244remove separator
1245
1246=item <b>Begin<r>Right<l>Left<u>Up<d>Down<e>End
1247
1248menu quick arrows
1249
1250=back
1251X<XPM>
1252
1253=head1 XPM
1254
1255For the XPM XTerm escape sequence B<< C<ESC ] 20 ; Pt ST> >> then value 2039For the BACKGROUND IMAGE XTerm escape sequence B<< C<ESC ] 20 ; Pt ST> >> the value
1256of B<< C<Pt> >> can be the name of the background pixmap followed by a 2040of B<< C<Pt> >> can be the name of the background image file followed by a
1257sequence of scaling/positioning commands separated by semi-colons. The 2041sequence of scaling/positioning commands separated by semi-colons. The
1258scaling/positioning commands are as follows: 2042scaling/positioning commands are as follows:
1259 2043
1260=over 4 2044=over 4
1261 2045
… …
1299 2083
1300For example: 2084For example:
1301 2085
1302=over 4 2086=over 4
1303 2087
1304=item B<\E]20;funky\a> 2088=item B<\E]20;funky.jpg\a>
1305 2089
1306load B<funky.xpm> as a tiled image 2090load B<funky.jpg> as a tiled image
1307 2091
1308=item B<\E]20;mona;100\a> 2092=item B<\E]20;mona.jpg;100\a>
1309 2093
1310load B<mona.xpm> with a scaling of 100% 2094load B<mona.jpg> with a scaling of 100%
1311 2095
1312=item B<\E]20;;200;?\a> 2096=item B<\E]20;;200;?\a>
1313 2097
1314rescale the current pixmap to 200% and display the image geometry in 2098rescale the current pixmap to 200% and display the image geometry in
1315the title 2099the title
… …
1354=begin table 2138=begin table
1355 2139
1356 4 Shift 2140 4 Shift
1357 8 Meta 2141 8 Meta
1358 16 Control 2142 16 Control
1359 32 Double Click I<(Rxvt extension)> 2143 32 Double Click I<(rxvt extension)>
1360 2144
1361=end table 2145=end table
1362 2146
1363Col = B<< C<< <x> - SPACE >> >> 2147Col = B<< C<< <x> - SPACE >> >>
1364 2148
… …
1441=end table 2225=end table
1442 2226
1443=head1 CONFIGURE OPTIONS 2227=head1 CONFIGURE OPTIONS
1444 2228
1445General hint: if you get compile errors, then likely your configuration 2229General hint: if you get compile errors, then likely your configuration
1446hasn't been tested well. Either try with --enable-everything or use the 2230hasn't been tested well. Either try with C<--enable-everything> or use
1447./reconf script as a base for experiments. ./reconf is used by myself, 2231the default configuration (i.e. no C<--enable-xxx> or C<--disable-xxx>
1448so it should generally be a working config. Of course, you should always 2232switches). Of course, you should always report when a combination doesn't
1449report when a combination doesn't work, so it can be fixed. Marc Lehmann 2233work, so it can be fixed. Marc Lehmann <rxvt@schmorp.de>.
1450<rxvt@schmorp.de>. 2234
2235All
1451 2236
1452=over 4 2237=over 4
1453 2238
1454=item --enable-everything 2239=item --enable-everything
1455 2240
1456Add support for all non-multichoice options listed in "./configure 2241Add (or remove) support for all non-multichoice options listed in "./configure
1457--help". Note that unlike other enable options this is order dependant. 2242--help".
2243
1458You can specify this and then disable options which this enables by 2244You can specify this and then disable options you do not like by
1459I<following> this with the appropriate commands. 2245I<following> this with the appropriate C<--disable-...> arguments,
2246or you can start with a minimal configuration by specifying
2247C<--disable-everything> and than adding just the C<--enable-...> arguments
2248you want.
1460 2249
1461=item --enable-xft 2250=item --enable-xft (default: enabled)
1462 2251
1463Add support for Xft (anti-aliases, among others) fonts. Xft fonts are 2252Add support for Xft (anti-aliases, among others) fonts. Xft fonts are
1464slower and require lots of memory, but as long as you don't use them, you 2253slower and require lots of memory, but as long as you don't use them, you
1465don't pay for them. 2254don't pay for them.
1466 2255
1467=item --enable-font-styles 2256=item --enable-font-styles (default: on)
1468 2257
1469Add support for B<bold>, I<italic> and B<< I<bold italic> >> font 2258Add support for B<bold>, I<italic> and B<< I<bold italic> >> font
1470styles. The fonts can be set manually or automatically. 2259styles. The fonts can be set manually or automatically.
1471 2260
1472=item --with-codesets=NAME,... 2261=item --with-codesets=NAME,... (default: all)
1473 2262
1474Compile in support for additional codeset (encoding) groups (eu, vn are 2263Compile in support for additional codeset (encoding) groups (C<eu>, C<vn>
1475always compiled in, which includes most 8-bit character sets). These 2264are always compiled in, which includes most 8-bit character sets). These
1476codeset tables are currently only used for driving X11 core fonts, they 2265codeset tables are used for driving X11 core fonts, they are not required
1477are not required for Xft fonts. Compiling them in will make your binary 2266for Xft fonts, although having them compiled in lets rxvt-unicode choose
1478bigger (together about 700kB), but it doesn't increase memory usage unless 2267replacement fonts more intelligently. Compiling them in will make your
2268binary bigger (all of together cost about 700kB), but it doesn't increase
1479you use an X11 font requiring one of these encodings. 2269memory usage unless you use a font requiring one of these encodings.
1480 2270
1481=begin table 2271=begin table
1482 2272
1483 all all available codeset groups 2273 all all available codeset groups
1484 cn common chinese encodings 2274 zh common chinese encodings
1485 cn_ext rarely used but very big chinese encodigs 2275 zh_ext rarely used but very big chinese encodings
1486 jp common japanese encodings 2276 jp common japanese encodings
1487 jp_ext rarely used but big japanese encodings 2277 jp_ext rarely used but big japanese encodings
1488 kr korean encodings 2278 kr korean encodings
1489 2279
1490=end table 2280=end table
1491 2281
1492=item --enable-xim 2282=item --enable-xim (default: on)
1493 2283
1494Add support for XIM (X Input Method) protocol. This allows using 2284Add support for XIM (X Input Method) protocol. This allows using
1495alternative input methods (e.g. kinput2) and will also correctly 2285alternative input methods (e.g. kinput2) and will also correctly
1496set up the input for people using dead keys or compose keys. 2286set up the input for people using dead keys or compose keys.
1497 2287
1498=item --enable-unicode3 2288=item --enable-unicode3 (default: off)
2289
2290Recommended to stay off unless you really need non-BMP characters.
1499 2291
1500Enable direct support for displaying unicode codepoints above 2292Enable direct support for displaying unicode codepoints above
150165535 (the basic multilingual page). This increases storage 229365535 (the basic multilingual page). This increases storage
1502requirements per character from 2 to 4 bytes. X11 fonts do not yet 2294requirements per character from 2 to 4 bytes. X11 fonts do not yet
1503support these extra characters, but Xft does. 2295support these extra characters, but Xft does.
1504 2296
1505Please note that rxvt-unicode can store unicode code points >65535 2297Please note that rxvt-unicode can store unicode code points >65535
1506even without this flag, but the number of such characters is 2298even without this flag, but the number of such characters is
1507limited to a view thousand (shared with combining characters, 2299limited to a few thousand (shared with combining characters,
1508see next switch), and right now rxvt-unicode cannot display them 2300see next switch), and right now rxvt-unicode cannot display them
1509(input/output and cut&paste still work, though). 2301(input/output and cut&paste still work, though).
1510 2302
1511=item --enable-combining 2303=item --enable-combining (default: on)
1512 2304
1513Enable automatic composition of combining characters into 2305Enable automatic composition of combining characters into
1514composite characters. This is required for proper viewing of text 2306composite characters. This is required for proper viewing of text
1515where accents are encoded as seperate unicode characters. This is 2307where accents are encoded as seperate unicode characters. This is
1516done by using precomposited characters when available or creating 2308done by using precomposited characters when available or creating
1517new pseudo-characters when no precomposed form exists. 2309new pseudo-characters when no precomposed form exists.
1518 2310
1519Without --enable-unicode3, the number of additional precomposed 2311Without --enable-unicode3, the number of additional precomposed
1520characters is rather limited (2048, if this is full, rxvt will use the 2312characters is somewhat limited (the 6400 private use characters will be
1521private use area, extending the number of combinations to 8448). With 2313(ab-)used). With --enable-unicode3, no practical limit exists.
1522--enable-unicode3, no practical limit exists. This will also enable 2314
1523storage of characters >65535. 2315This option will also enable storage (but not display) of characters
2316beyond plane 0 (>65535) when --enable-unicode3 was not specified.
1524 2317
1525The combining table also contains entries for arabic presentation forms, 2318The combining table also contains entries for arabic presentation forms,
1526but these are not currently used. Bug me if you want these to be used. 2319but these are not currently used. Bug me if you want these to be used (and
2320tell me how these are to be used...).
1527 2321
1528=item --enable-fallback(=CLASS) 2322=item --enable-fallback(=CLASS) (default: Rxvt)
1529 2323
1530When reading resource settings, also read settings for class CLASS 2324When reading resource settings, also read settings for class CLASS. To
1531(default: Rxvt). To disable resource fallback use --disable-fallback. 2325disable resource fallback use --disable-fallback.
1532 2326
1533=item --with-res-name=NAME 2327=item --with-res-name=NAME (default: urxvt)
1534 2328
1535Use the given name (default: urxvt) as default application name when 2329Use the given name as default application name when
1536reading resources. Specify --with-res-name=rxvt to replace rxvt. 2330reading resources. Specify --with-res-name=rxvt to replace rxvt.
1537 2331
1538=item --with-res-class=CLASS 2332=item --with-res-class=CLASS (default: URxvt)
1539 2333
1540Use the given class (default: URxvt) as default application class 2334Use the given class as default application class
1541when reading resources. Specify --with-res-class=Rxvt to replace 2335when reading resources. Specify --with-res-class=Rxvt to replace
1542rxvt. 2336rxvt.
1543 2337
1544=item --enable-utmp 2338=item --enable-utmp (default: on)
1545 2339
1546Write user and tty to utmp file (used by programs like F<w>) at 2340Write user and tty to utmp file (used by programs like F<w>) at
1547start of rxvt execution and delete information when rxvt exits. 2341start of rxvt execution and delete information when rxvt exits.
1548 2342
1549=item --enable-wtmp 2343=item --enable-wtmp (default: on)
1550 2344
1551Write user and tty to wtmp file (used by programs like F<last>) at 2345Write user and tty to wtmp file (used by programs like F<last>) at
1552start of rxvt execution and write logout when rxvt exits. This 2346start of rxvt execution and write logout when rxvt exits. This
1553option requires --enable-utmp to also be specified. 2347option requires --enable-utmp to also be specified.
1554 2348
1555=item --enable-lastlog 2349=item --enable-lastlog (default: on)
1556 2350
1557Write user and tty to lastlog file (used by programs like 2351Write user and tty to lastlog file (used by programs like
1558F<lastlogin>) at start of rxvt execution. This option requires 2352F<lastlogin>) at start of rxvt execution. This option requires
1559--enable-utmp to also be specified. 2353--enable-utmp to also be specified.
1560 2354
1561=item --enable-xpm-background 2355=item --enable-afterimage (default: on)
1562 2356
1563Add support for XPM background pixmaps. 2357Add support for libAfterImage to be used for transparency and background
2358images. It adds support for many file formats including JPG, PNG,
2359SVG, TIFF, GIF, XPM, BMP, ICO, XCF, TGA and AfterStep image XML
2360(L<http://www.afterstep.org/visualdoc.php?show=asimagexml>).
1564 2361
2362This option also adds such eye candy as blending an image over the root
2363background, as well as dynamic scaling and bluring of background images.
2364
2365Note that with this option enabled, @@RXVT_NAME@@'s memory footprint might
2366increase by a few megabytes even if no extra features are used (mostly due
2367to third-party libraries used by libAI). Memory footprint may somewhat be
2368lowered if libAfterImage is configured without support for SVG.
2369
1565=item --enable-transparency 2370=item --enable-transparency (default: on)
1566 2371
1567Add support for inheriting parent backgrounds thus giving a fake 2372Add support for backgrounds, creating illusion of transparency in the term.
1568transparency to the term.
1569 2373
1570=item --enable-fading 2374=item --enable-fading (default: on)
1571 2375
1572Add support for fading the text when focus is lost. 2376Add support for fading the text when focus is lost.
1573 2377
1574=item --enable-tinting
1575
1576Add support for tinting of transparent backgrounds.
1577
1578=item --enable-menubar
1579
1580Add support for our menu bar system (this interacts badly with
1581dynamic locale switching currently).
1582
1583=item --enable-rxvt-scroll 2378=item --enable-rxvt-scroll (default: on)
1584 2379
1585Add support for the original rxvt scrollbar. 2380Add support for the original rxvt scrollbar.
1586 2381
1587=item --enable-next-scroll 2382=item --enable-next-scroll (default: on)
1588 2383
1589Add support for a NeXT-like scrollbar. 2384Add support for a NeXT-like scrollbar.
1590 2385
1591=item --enable-xterm-scroll 2386=item --enable-xterm-scroll (default: on)
1592 2387
1593Add support for an Xterm-like scrollbar. 2388Add support for an Xterm-like scrollbar.
1594 2389
1595=item --enable-plain-scroll 2390=item --enable-plain-scroll (default: on)
1596 2391
1597Add support for a very unobtrusive, plain-looking scrollbar that 2392Add support for a very unobtrusive, plain-looking scrollbar that
1598is the favourite of the rxvt-unicode author, having used it for 2393is the favourite of the rxvt-unicode author, having used it for
1599many years. 2394many years.
1600 2395
1601=item --enable-half-shadow
1602
1603Make shadows on the scrollbar only half the normal width & height.
1604only applicable to rxvt scrollbars.
1605
1606=item --enable-ttygid
1607
1608Change tty device setting to group "tty" - only use this if
1609your system uses this type of security.
1610
1611=item --disable-backspace-key 2396=item --disable-backspace-key
1612 2397
1613Disable any handling of the backspace key by us - let the X server 2398Removes any handling of the backspace key by us - let the X server do it.
2399
2400=item --disable-delete-key
2401
2402Removes any handling of the delete key by us - let the X server
1614do it. 2403do it.
1615 2404
1616=item --disable-delete-key
1617
1618Disable any handling of the delete key by us - let the X server
1619do it.
1620
1621=item --disable-resources 2405=item --disable-resources
1622 2406
1623Remove all resources checking. 2407Removes any support for resource checking.
1624
1625=item --enable-xgetdefault
1626
1627Make resources checking via XGetDefault() instead of our small
1628version which only checks ~/.Xdefaults, or if that doesn't exist
1629then ~/.Xresources.
1630
1631=item --enable-strings
1632
1633Add support for our possibly faster memset() function and other
1634various routines, overriding your system's versions which may
1635have been hand-crafted in assembly or may require extra libraries
1636to link in. (this breaks ANSI-C rules and has problems on many
1637GNU/Linux systems).
1638 2408
1639=item --disable-swapscreen 2409=item --disable-swapscreen
1640 2410
1641Remove support for swap screen. 2411Remove support for secondary/swap screen.
1642 2412
1643=item --enable-frills 2413=item --enable-frills (default: on)
1644 2414
1645Add support for many small features that are not essential but nice to 2415Add support for many small features that are not essential but nice to
1646have. Normally you want this, but for very small binaries you may want to 2416have. Normally you want this, but for very small binaries you may want to
1647disable this. 2417disable this.
1648 2418
2419A non-exhaustive list of features enabled by C<--enable-frills> (possibly
2420in combination with other switches) is:
2421
2422 MWM-hints
2423 EWMH-hints (pid, utf8 names) and protocols (ping)
2424 urgency hint
2425 seperate underline colour (-underlineColor)
2426 settable border widths and borderless switch (-w, -b, -bl)
2427 visual depth selection (-depth)
2428 settable extra linespacing /-lsp)
2429 iso-14755 5.1 (basic) support
2430 tripleclickwords (-tcw)
2431 settable insecure mode (-insecure)
2432 keysym remapping support
2433 cursor blinking and underline cursor (-cb, -uc)
2434 XEmbed support (-embed)
2435 user-pty (-pty-fd)
2436 hold on exit (-hold)
2437 compile in built-in block graphics
2438 skip builtin block graphics (-sbg)
2439 separate highlightcolor support (-hc)
2440
2441It also enables some non-essential features otherwise disabled, such as:
2442
2443 some round-trip time optimisations
2444 nearest color allocation on pseudocolor screens
2445 UTF8_STRING support for selection
2446 sgr modes 90..97 and 100..107
2447 backindex and forwardindex escape sequences
2448 view change/zero scrollback escape sequences
2449 locale switching escape sequence
2450 window op and some xterm/OSC escape sequences
2451 rectangular selections
2452 trailing space removal for selections
2453 verbose X error handling
2454
1649=item --enable-iso14755 2455=item --enable-iso14755 (default: on)
1650 2456
1651Enable extended ISO 14755 support (see @@RXVT_NAME@@(1), or 2457Enable extended ISO 14755 support (see @@RXVT_NAME@@(1), or
1652F<doc/rxvt.1.txt>). Basic support (section 5.1) is enabled by 2458F<doc/rxvt.1.txt>). Basic support (section 5.1) is enabled by
1653C<--enable-frills>, while support for 5.2, 5.3 and 5.4 is enabled with 2459C<--enable-frills>, while support for 5.2, 5.3 and 5.4 is enabled with
1654this switch. 2460this switch.
1655 2461
1656=item --enable-linespace
1657
1658Add support to provide user specified line spacing between text rows.
1659
1660=item --enable-keepscrolling 2462=item --enable-keepscrolling (default: on)
1661 2463
1662Add support for continual scrolling of the display when you hold 2464Add support for continual scrolling of the display when you hold
1663the mouse button down on a scrollbar arrow. 2465the mouse button down on a scrollbar arrow.
1664 2466
2467=item --enable-selectionscrolling (default: on)
2468
2469Add support for scrolling when the selection moves to the top or
2470bottom of the screen.
2471
1665=item --enable-mousewheel 2472=item --enable-mousewheel (default: on)
1666 2473
1667Add support for scrolling via mouse wheel or buttons 4 & 5. 2474Add support for scrolling via mouse wheel or buttons 4 & 5.
1668 2475
1669=item --enable-slipwheeling 2476=item --enable-slipwheeling (default: on)
1670 2477
1671Add support for continual scrolling (using the mouse wheel as an 2478Add support for continual scrolling (using the mouse wheel as an
1672accelerator) while the control key is held down. This option 2479accelerator) while the control key is held down. This option
1673requires --enable-mousewheel to also be specified. 2480requires --enable-mousewheel to also be specified.
1674 2481
1675=item --disable-new-selection
1676
1677Remove support for mouse selection style like that of xterm.
1678
1679=item --enable-dmalloc
1680
1681Use Gray Watson's malloc - which is good for debugging See
1682http://www.letters.com/dmalloc/ for details If you use either this or the
1683next option, you may need to edit src/Makefile after compiling to point
1684DINCLUDE and DLIB to the right places.
1685
1686You can only use either this option and the following (should
1687you use either) .
1688
1689=item --enable-dlmalloc
1690
1691Use Doug Lea's malloc - which is good for a production version
1692See L<http://g.oswego.edu/dl/html/malloc.html> for details.
1693
1694=item --enable-smart-resize 2482=item --enable-smart-resize (default: off)
1695 2483
1696Add smart growth/shrink behaviour when changing font size via from hot 2484Add smart growth/shrink behaviour when resizing.
1697keys. This should keep in a fixed position the rxvt corner which is 2485This should keep the window corner which is closest to a corner of
1698closest to a corner of the screen. 2486the screen in a fixed position.
1699 2487
1700=item --enable-cursor-blink 2488=item --enable-text-blink (default: on)
1701 2489
1702Add support for a blinking cursor. 2490Add support for blinking text.
1703 2491
1704=item --enable-pointer-blank 2492=item --enable-pointer-blank (default: on)
1705 2493
1706Add support to have the pointer disappear when typing or inactive. 2494Add support to have the pointer disappear when typing or inactive.
1707 2495
1708=item --with-name=NAME 2496=item --enable-perl (default: on)
1709 2497
2498Enable an embedded perl interpreter. See the B<@@RXVT_NAME@@perl(3)>
2499manpage (F<doc/rxvtperl.txt>) for more info on this feature, or the
2500files in F<src/perl-ext/> for the extensions that are installed by
2501default. The perl interpreter that is used can be specified via the
2502C<PERL> environment variable when running configure. Even when compiled
2503in, perl will I<not> be initialised when all extensions have been disabled
2504C<-pe "" --perl-ext-common "">, so it should be safe to enable from a
2505resource standpoint.
2506
2507=item --with-afterimage-config=DIR
2508
2509Look for the libAfterImage config script in DIR.
2510
2511=item --with-name=NAME (default: urxvt)
2512
1710Set the basename for the installed binaries (default: urxvt, resulting in 2513Set the basename for the installed binaries, resulting
1711urxvt, urxvtd etc.). Specify --with-name=rxvt to replace rxvt. 2514in C<urxvt>, C<urxvtd> etc.). Specify C<--with-name=rxvt> to replace with
2515C<rxvt>.
1712 2516
1713=item --with-term=NAME 2517=item --with-term=NAME (default: rxvt-unicode)
1714 2518
1715Change the environmental variable for the terminal to NAME (default 2519Change the environmental variable for the terminal to NAME.
1716"rxvt")
1717 2520
1718=item --with-terminfo=PATH 2521=item --with-terminfo=PATH
1719 2522
1720Change the environmental variable for the path to the terminfo tree to 2523Change the environmental variable for the path to the terminfo tree to
1721PATH. 2524PATH.
1722 2525
1723=item --with-x 2526=item --with-x
1724 2527
1725Use the X Window System (pretty much default, eh?). 2528Use the X Window System (pretty much default, eh?).
1726
1727=item --with-xpm-includes=DIR
1728
1729Look for the XPM includes in DIR.
1730
1731=item --with-xpm-library=DIR
1732
1733Look for the XPM library in DIR.
1734
1735=item --with-xpm
1736
1737Not needed - define via --enable-xpm-background.
1738 2529
1739=back 2530=back
1740 2531
1741=head1 AUTHORS 2532=head1 AUTHORS
1742 2533

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines