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.1 by root, Thu Aug 12 20:42:12 2004 UTC vs.
Revision 1.113 by root, Thu Feb 2 18:04:45 2006 UTC

1=head1 Rxvt Technical Reference 1=head1 NAME
2 2
3Marc Lehmann <rxvt@schmorp.de>, converted to pod and reworked from the 3RXVT REFERENCE - FAQ, command sequences and other background information
4original Rxvt documentation by Geoff Wing <gcw@pobox.com>, who in turn used
5the XTerm documentation and other sources.
6 4
5=head1 SYNOPSIS
6
7 # set a new font set
8 printf '\33]50;%s\007' 9x15,xft:Kochi" Mincho"
9
10 # change the locale and tell rxvt-unicode about it
11 export LC_CTYPE=ja_JP.EUC-JP; printf "\33]701;$LC_CTYPE\007"
12
13 # set window title
14 printf '\33]2;%s\007' "new window title"
15
16=head1 DESCRIPTION
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://cvs.schmorp.de/browse/*checkout*/rxvt-unicode/doc/rxvt.7.html>.
23
24=head1 RXVT-UNICODE/URXVT FREQUENTLY ASKED QUESTIONS
25
26
27=head2 Meta, Features & Commandline Issues
28
29=head3 My question isn't answered here, can I ask a human?
30
31Before sending me mail, you could go to IRC: C<irc.freenode.net>,
32channel C<#rxvt-unicode> has some rxvt-unicode enthusiasts that might be
33interested in learning about new and exciting problems (but not FAQs :).
34
35=head3 Does it support tabs, can I have a tabbed rxvt-unicode?
36
37Beginning with version 7.3, there is a perl extension that implements a
38simple tabbed terminal. It is installed by default, so any of these should
39give you tabs:
40
41 @@URXVT_NAME@@ -pe tabbed
42
43 URxvt.perl-ext-common: default,tabbed
44
45It will also work fine with tabbing functionality of many window managers
46or similar tabbing programs, and its embedding-features allow it to be
47embedded into other programs, as witnessed by F<doc/rxvt-tabbed> or
48the upcoming C<Gtk2::URxvt> perl module, which features a tabbed urxvt
49(murxvt) terminal as an example embedding application.
50
51=head3 How do I know which rxvt-unicode version I'm using?
52
53The version number is displayed with the usage (-h). Also the escape
54sequence C<ESC [ 8 n> sets the window title to the version number. When
55using the @@URXVT_NAME@@c client, the version displayed is that of the
56daemon.
57
58=head3 Rxvt-unicode uses gobs of memory, how can I reduce that?
59
60Rxvt-unicode tries to obey the rule of not charging you for something you
61don't use. One thing you should try is to configure out all settings that
62you don't need, for example, Xft support is a resource hog by design,
63when used. Compiling it out ensures that no Xft font will be loaded
64accidentally when rxvt-unicode tries to find a font for your characters.
65
66Also, many people (me included) like large windows and even larger
67scrollback buffers: Without C<--enable-unicode3>, rxvt-unicode will use
686 bytes per screen cell. For a 160x?? window this amounts to almost a
69kilobyte per line. A scrollback buffer of 10000 lines will then (if full)
70use 10 Megabytes of memory. With C<--enable-unicode3> it gets worse, as
71rxvt-unicode then uses 8 bytes per screen cell.
72
73=head3 How can I start @@URXVT_NAME@@d in a race-free way?
74
75Try C<@@URXVT_NAME@@d -f -o>, which tells @@URXVT_NAME@@d to open the
76display, create the listening socket and then fork.
77
78=head3 How can I start @@URXVT_NAME@@d automatically when I run URXVT_NAME@@c?
79
80If you want to start @@URXVT_NAME@@d automatically whenever you run
81@@URXVT_NAME@@c and the daemon isn't running yet, use this script:
82
83 #!/bin/sh
84 @@URXVT_NAME@@c "$@"
85 if [ $? -eq 2 ]; then
86 @@URXVT_NAME@@d -q -o -f
87 @@URXVT_NAME@@c "$@"
88 fi
89
90This tries to create a new terminal, and if fails with exit status 2,
91meaning it couldn't connect to the daemon, it will start the daemon and
92re-run the command. Subsequent invocations of the script will re-use the
93existing daemon.
94
95=head3 How do I distinguish wether I'm running rxvt-unicode or a regular xterm? I need this to decide about setting colors etc.
96
97The original rxvt and rxvt-unicode always export the variable "COLORTERM",
98so you can check and see if that is set. Note that several programs, JED,
99slrn, Midnight Commander automatically check this variable to decide
100whether or not to use color.
101
102=head3 How do I set the correct, full IP address for the DISPLAY variable?
103
104If you've compiled rxvt-unicode with DISPLAY_IS_IP and have enabled
105insecure mode then it is possible to use the following shell script
106snippets to correctly set the display. If your version of rxvt-unicode
107wasn't also compiled with ESCZ_ANSWER (as assumed in these snippets) then
108the COLORTERM variable can be used to distinguish rxvt-unicode from a
109regular xterm.
110
111Courtesy of Chuck Blake <cblake@BBN.COM> with the following shell script
112snippets:
113
114 # Bourne/Korn/POSIX family of shells:
115 [ ${TERM:-foo} = foo ] && TERM=xterm # assume an xterm if we don't know
116 if [ ${TERM:-foo} = xterm ]; then
117 stty -icanon -echo min 0 time 15 # see if enhanced rxvt or not
118 echo -n '^[Z'
119 read term_id
120 stty icanon echo
121 if [ ""${term_id} = '^[[?1;2C' -a ${DISPLAY:-foo} = foo ]; then
122 echo -n '^[[7n' # query the rxvt we are in for the DISPLAY string
123 read DISPLAY # set it in our local shell
124 fi
125 fi
126
127=head3 How do I compile the manual pages on my own?
128
129You need to have a recent version of perl installed as F</usr/bin/perl>,
130one that comes with F<pod2man>, F<pod2text> and F<pod2html>. Then go to
131the doc subdirectory and enter C<make alldoc>.
132
133=head3 Isn't rxvt-unicode supposed to be small? Don't all those features bloat?
134
135I often get asked about this, and I think, no, they didn't cause extra
136bloat. If you compare a minimal rxvt and a minimal urxvt, you can see
137that the urxvt binary is larger (due to some encoding tables always being
138compiled in), but it actually uses less memory (RSS) after startup. Even
139with C<--disable-everything>, this comparison is a bit unfair, as many
140features unique to urxvt (locale, encoding conversion, iso14755 etc.) are
141already in use in this mode.
142
143 text data bss drs rss filename
144 98398 1664 24 15695 1824 rxvt --disable-everything
145 188985 9048 66616 18222 1788 urxvt --disable-everything
146
147When you C<--enable-everything> (which I<is> unfair, as this involves xft
148and full locale/XIM support which are quite bloaty inside libX11 and my
149libc), the two diverge, but not unreasnobaly so.
150
151 text data bss drs rss filename
152 163431 2152 24 20123 2060 rxvt --enable-everything
153 1035683 49680 66648 29096 3680 urxvt --enable-everything
154
155The very large size of the text section is explained by the east-asian
156encoding tables, which, if unused, take up disk space but nothing else
157and can be compiled out unless you rely on X11 core fonts that use those
158encodings. The BSS size comes from the 64k emergency buffer that my c++
159compiler allocates (but of course doesn't use unless you are out of
160memory). Also, using an xft font instead of a core font immediately adds a
161few megabytes of RSS. Xft indeed is responsible for a lot of RSS even when
162not used.
163
164Of course, due to every character using two or four bytes instead of one,
165a large scrollback buffer will ultimately make rxvt-unicode use more
166memory.
167
168Compared to e.g. Eterm (5112k), aterm (3132k) and xterm (4680k), this
169still fares rather well. And compared to some monsters like gnome-terminal
170(21152k + extra 4204k in separate processes) or konsole (22200k + extra
17143180k in daemons that stay around after exit, plus half a minute of
172startup time, including the hundreds of warnings it spits out), it fares
173extremely well *g*.
174
175=head3 Why C++, isn't that unportable/bloated/uncool?
176
177Is this a question? :) It comes up very often. The simple answer is: I had
178to write it, and C++ allowed me to write and maintain it in a fraction
179of the time and effort (which is a scarce resource for me). Put even
180shorter: It simply wouldn't exist without C++.
181
182My personal stance on this is that C++ is less portable than C, but in
183the case of rxvt-unicode this hardly matters, as its portability limits
184are defined by things like X11, pseudo terminals, locale support and unix
185domain sockets, which are all less portable than C++ itself.
186
187Regarding the bloat, see the above question: It's easy to write programs
188in C that use gobs of memory, an certainly possible to write programs in
189C++ that don't. C++ also often comes with large libraries, but this is
190not necessarily the case with GCC. Here is what rxvt links against on my
191system with a minimal config:
192
193 libX11.so.6 => /usr/X11R6/lib/libX11.so.6 (0x00002aaaaabc3000)
194 libc.so.6 => /lib/libc.so.6 (0x00002aaaaadde000)
195 libdl.so.2 => /lib/libdl.so.2 (0x00002aaaab01d000)
196 /lib64/ld-linux-x86-64.so.2 (0x00002aaaaaaab000)
197
198And here is rxvt-unicode:
199
200 libX11.so.6 => /usr/X11R6/lib/libX11.so.6 (0x00002aaaaabc3000)
201 libgcc_s.so.1 => /lib/libgcc_s.so.1 (0x00002aaaaada2000)
202 libc.so.6 => /lib/libc.so.6 (0x00002aaaaaeb0000)
203 libdl.so.2 => /lib/libdl.so.2 (0x00002aaaab0ee000)
204 /lib64/ld-linux-x86-64.so.2 (0x00002aaaaaaab000)
205
206No large bloated libraries (of course, none were linked in statically),
207except maybe libX11 :)
208
209
210=head2 Rendering, Font & Look and Feel Issues
211
212=head3 I can't get transparency working, what am I doing wrong?
213
214First of all, transparency isn't officially supported in rxvt-unicode, so
215you are mostly on your own. Do not bug the author about it (but you may
216bug everybody else). Also, if you can't get it working consider it a rite
217of passage: ... and you failed.
218
219Here are four ways to get transparency. B<Do> read the manpage and option
220descriptions for the programs mentioned and rxvt-unicode. Really, do it!
221
2221. Use inheritPixmap:
223
224 Esetroot wallpaper.jpg
225 @@URXVT_NAME@@ -ip -tint red -sh 40
226
227That works. If you think it doesn't, you lack transparency and tinting
228support, or you are unable to read.
229
2302. Use a simple pixmap and emulate pseudo-transparency. This enables you
231to use effects other than tinting and shading: Just shade/tint/whatever
232your picture with gimp or any other tool:
233
234 convert wallpaper.jpg -blur 20x20 -modulate 30 background.xpm
235 @@URXVT_NAME@@ -pixmap background.xpm -pe automove-background
236
237That works. If you think it doesn't, you lack XPM and Perl support, or you
238are unable to read.
239
2403. Use an ARGB visual:
241
242 @@URXVT_NAME@@ -depth 32 -fg grey90 -bg rgba:0000/0000/4444/cccc
243
244This requires XFT support, and the support of your X-server. If that
245doesn't work for you, blame Xorg and Keith Packard. ARGB visuals aren't
246there yet, no matter what they claim. Rxvt-Unicode contains the neccessary
247bugfixes and workarounds for Xft and Xlib to make it work, but that
248doesn't mean that your WM has the required kludges in place.
249
2504. Use xcompmgr and let it do the job:
251
252 xprop -frame -f _NET_WM_WINDOW_OPACITY 32c \
253 -set _NET_WM_WINDOW_OPACITY 0xc0000000
254
255Then click on a window you want to make transparent. Replace C<0xc0000000>
256by other values to change the degree of opacity. If it doesn't work and
257your server crashes, you got to keep the pieces.
258
259=head3 Why does rxvt-unicode sometimes leave pixel droppings?
260
261Most fonts were not designed for terminal use, which means that character
262size varies a lot. A font that is otherwise fine for terminal use might
263contain some characters that are simply too wide. Rxvt-unicode will avoid
264these characters. For characters that are just "a bit" too wide a special
265"careful" rendering mode is used that redraws adjacent characters.
266
267All of this requires that fonts do not lie about character sizes,
268however: Xft fonts often draw glyphs larger than their acclaimed bounding
269box, and rxvt-unicode has no way of detecting this (the correct way is to
270ask for the character bounding box, which unfortunately is wrong in these
271cases).
272
273It's not clear (to me at least), wether this is a bug in Xft, freetype,
274or the respective font. If you encounter this problem you might try using
275the C<-lsp> option to give the font more height. If that doesn't work, you
276might be forced to use a different font.
277
278All of this is not a problem when using X11 core fonts, as their bounding
279box data is correct.
280
281=head3 How can I keep rxvt-unicode from using reverse video so much?
282
283First of all, make sure you are running with the right terminal settings
284(C<TERM=rxvt-unicode>), which will get rid of most of these effects. Then
285make sure you have specified colours for italic and bold, as otherwise
286rxvt-unicode might use reverse video to simulate the effect:
287
288 URxvt.colorBD: white
289 URxvt.colorIT: green
290
291=head3 Some programs assume totally weird colours (red instead of blue), how can I fix that?
292
293For some unexplainable reason, some rare programs assume a very weird
294colour palette when confronted with a terminal with more than the standard
2958 colours (rxvt-unicode supports 88). The right fix is, of course, to fix
296these programs not to assume non-ISO colours without very good reasons.
297
298In the meantime, you can either edit your C<rxvt-unicode> terminfo
299definition to only claim 8 colour support or use C<TERM=rxvt>, which will
300fix colours but keep you from using other rxvt-unicode features.
301
302=head3 Can I switch the fonts at runtime?
303
304Yes, using an escape sequence. Try something like this, which has the same
305effect as using the C<-fn> switch, and takes effect immediately:
306
307 printf '\e]50;%s\007' "9x15bold,xft:Kochi Gothic"
308
309This is useful if you e.g. work primarily with japanese (and prefer a
310japanese font), but you have to switch to chinese temporarily, where
311japanese fonts would only be in your way.
312
313You can think of this as a kind of manual ISO-2022 switching.
314
315=head3 Why do italic characters look as if clipped?
316
317Many fonts have difficulties with italic characters and hinting. For
318example, the otherwise very nicely hinted font C<xft:Bitstream Vera Sans
319Mono> completely fails in it's italic face. A workaround might be to
320enable freetype autohinting, i.e. like this:
321
322 URxvt.italicFont: xft:Bitstream Vera Sans Mono:italic:autohint=true
323 URxvt.boldItalicFont: xft:Bitstream Vera Sans Mono:bold:italic:autohint=true
324
325=head3 Can I speed up Xft rendering somehow?
326
327Yes, the most obvious way to speed it up is to avoid Xft entirely, as
328it is simply slow. If you still want Xft fonts you might try to disable
329antialiasing (by appending C<:antialias=false>), which saves lots of
330memory and also speeds up rendering considerably.
331
332=head3 Rxvt-unicode doesn't seem to anti-alias its fonts, what is wrong?
333
334Rxvt-unicode will use whatever you specify as a font. If it needs to
335fall back to it's default font search list it will prefer X11 core
336fonts, because they are small and fast, and then use Xft fonts. It has
337antialiasing disabled for most of them, because the author thinks they
338look best that way.
339
340If you want antialiasing, you have to specify the fonts manually.
341
342=head3 What's with this bold/blink stuff?
343
344If no bold colour is set via C<colorBD:>, bold will invert text using the
345standard foreground colour.
346
347For the standard background colour, blinking will actually make the
348text blink when compiled with C<--enable-blinking>. with standard
349colours. Without C<--enable-blinking>, the blink attribute will be
350ignored.
351
352On ANSI colours, bold/blink attributes are used to set high-intensity
353foreground/background colors.
354
355color0-7 are the low-intensity colors.
356
357color8-15 are the corresponding high-intensity colors.
358
359=head3 I don't like the screen colors. How do I change them?
360
361You can change the screen colors at run-time using F<~/.Xdefaults>
362resources (or as long-options).
363
364Here are values that are supposed to resemble a VGA screen,
365including the murky brown that passes for low-intensity yellow:
366
367 URxvt.color0: #000000
368 URxvt.color1: #A80000
369 URxvt.color2: #00A800
370 URxvt.color3: #A8A800
371 URxvt.color4: #0000A8
372 URxvt.color5: #A800A8
373 URxvt.color6: #00A8A8
374 URxvt.color7: #A8A8A8
375
376 URxvt.color8: #000054
377 URxvt.color9: #FF0054
378 URxvt.color10: #00FF54
379 URxvt.color11: #FFFF54
380 URxvt.color12: #0000FF
381 URxvt.color13: #FF00FF
382 URxvt.color14: #00FFFF
383 URxvt.color15: #FFFFFF
384
385And here is a more complete set of non-standard colors.
386
387 URxvt.cursorColor: #dc74d1
388 URxvt.pointerColor: #dc74d1
389 URxvt.background: #0e0e0e
390 URxvt.foreground: #4ad5e1
391 URxvt.color0: #000000
392 URxvt.color8: #8b8f93
393 URxvt.color1: #dc74d1
394 URxvt.color9: #dc74d1
395 URxvt.color2: #0eb8c7
396 URxvt.color10: #0eb8c7
397 URxvt.color3: #dfe37e
398 URxvt.color11: #dfe37e
399 URxvt.color5: #9e88f0
400 URxvt.color13: #9e88f0
401 URxvt.color6: #73f7ff
402 URxvt.color14: #73f7ff
403 URxvt.color7: #e1dddd
404 URxvt.color15: #e1dddd
405
406They have been described (not by me) as "pretty girly".
407
408=head3 Why do some characters look so much different than others?
409
410See next entry.
411
412=head3 How does rxvt-unicode choose fonts?
413
414Most fonts do not contain the full range of Unicode, which is
415fine. Chances are that the font you (or the admin/package maintainer of
416your system/os) have specified does not cover all the characters you want
417to display.
418
419B<rxvt-unicode> makes a best-effort try at finding a replacement
420font. Often the result is fine, but sometimes the chosen font looks
421bad/ugly/wrong. Some fonts have totally strange characters that don't
422resemble the correct glyph at all, and rxvt-unicode lacks the artificial
423intelligence to detect that a specific glyph is wrong: it has to believe
424the font that the characters it claims to contain indeed look correct.
425
426In that case, select a font of your taste and add it to the font list,
427e.g.:
428
429 @@URXVT_NAME@@ -fn basefont,font2,font3...
430
431When rxvt-unicode sees a character, it will first look at the base
432font. If the base font does not contain the character, it will go to the
433next font, and so on. Specifying your own fonts will also speed up this
434search and use less resources within rxvt-unicode and the X-server.
435
436The only limitation is that none of the fonts may be larger than the base
437font, as the base font defines the terminal character cell size, which
438must be the same due to the way terminals work.
439
440=head3 Why do some chinese characters look so different than others?
441
442This is because there is a difference between script and language --
443rxvt-unicode does not know which language the text that is output is,
444as it only knows the unicode character codes. If rxvt-unicode first
445sees a japanese/chinese character, it might choose a japanese font for
446display. Subsequent japanese characters will use that font. Now, many
447chinese characters aren't represented in japanese fonts, so when the first
448non-japanese character comes up, rxvt-unicode will look for a chinese font
449-- unfortunately at this point, it will still use the japanese font for
450chinese characters that are also in the japanese font.
451
452The workaround is easy: just tag a chinese font at the end of your font
453list (see the previous question). The key is to view the font list as
454a preference list: If you expect more japanese, list a japanese font
455first. If you expect more chinese, put a chinese font first.
456
457In the future it might be possible to switch language preferences at
458runtime (the internal data structure has no problem with using different
459fonts for the same character at the same time, but no interface for this
460has been designed yet).
461
462Until then, you might get away with switching fonts at runtime (see L<Can
463I switch the fonts at runtime?> later in this document).
464
465=head2 Keyboard, Mouse & User Interaction
466
467=head3 The new selection selects pieces that are too big, how can I select single words?
468
469If you want to select e.g. alphanumeric words, you can use the following
470setting:
471
472 URxvt.selection.pattern-0: ([[:word:]]+)
473
474If you click more than twice, the selection will be extended
475more and more.
476
477To get a selection that is very similar to the old code, try this pattern:
478
479 URxvt.selection.pattern-0: ([^"&'()*,;<=>?@[\\\\]^`{|})]+)
480
481Please also note that the I<LeftClick Shift-LeftClik> combination also
482selects words like the old code.
483
484=head3 I don't like the new selection/popups/hotkeys/perl, how do I change/disable it?
485
486You can disable the perl extension completely by setting the
487B<perl-ext-common> resource to the empty string, which also keeps
488rxvt-unicode from initialising perl, saving memory.
489
490If you only want to disable specific features, you first have to
491identify which perl extension is responsible. For this, read the section
492B<PREPACKAGED EXTENSIONS> in the @@URXVT_NAME@@perl(3) manpage. For
493example, to disable the B<selection-popup> and B<option-popup>, specify
494this B<perl-ext-common> resource:
495
496 URxvt.perl-ext-common: default,-selection-popup,-option-popup
497
498This will keep the default extensions, but disable the two popup
499extensions. Some extensions can also be configured, for example,
500scrollback search mode is triggered by B<M-s>. You can move it to any
501other combination either by setting the B<searchable-scrollback> resource:
502
503 URxvt.searchable-scrollback: CM-s
504
505=head3 The cursor moves when selecting text in the current input line, how do I switch this off?
506
507See next entry.
508
509=head3 During rlogin/ssh/telnet/etc. sessions, clicking near the cursor outputs strange escape sequences, how do I fix this?
510
511These are caused by the C<readline> perl extension. Under normal
512circumstances, it will move your cursor around when you click into the
513line that contains it. It tries hard not to do this at the wrong moment,
514but when running a program that doesn't parse cursor movements or in some
515cases during rlogin sessions, it fails to detect this properly.
516
517You can permamently switch this feature off by disabling the C<readline>
518extension:
519
520 URxvt.perl-ext-common: default,-readline
521
522=head3 My numerical keypad acts weird and generates differing output?
523
524Some Debian GNUL/Linux users seem to have this problem, although no
525specific details were reported so far. It is possible that this is caused
526by the wrong C<TERM> setting, although the details of wether and how
527this can happen are unknown, as C<TERM=rxvt> should offer a compatible
528keymap. See the answer to the previous question, and please report if that
529helped.
530
531=head3 My Compose (Multi_key) key is no longer working.
532
533The most common causes for this are that either your locale is not set
534correctly, or you specified a B<preeditStyle> that is not supported by
535your input method. For example, if you specified B<OverTheSpot> and
536your input method (e.g. the default input method handling Compose keys)
537does not support this (for instance because it is not visual), then
538rxvt-unicode will continue without an input method.
539
540In this case either do not specify a B<preeditStyle> or specify more than
541one pre-edit style, such as B<OverTheSpot,Root,None>.
542
543=head3 I cannot type C<Ctrl-Shift-2> to get an ASCII NUL character due to ISO 14755
544
545Either try C<Ctrl-2> alone (it often is mapped to ASCII NUL even on
546international keyboards) or simply use ISO 14755 support to your
547advantage, typing <Ctrl-Shift-0> to get a ASCII NUL. This works for other
548codes, too, such as C<Ctrl-Shift-1-d> to type the default telnet escape
549character and so on.
550
551=head3 Mouse cut/paste suddenly no longer works.
552
553Make sure that mouse reporting is actually turned off since killing
554some editors prematurely may leave the mouse in mouse report mode. I've
555heard that tcsh may use mouse reporting unless it otherwise specified. A
556quick check is to see if cut/paste works when the Alt or Shift keys are
557depressed.
558
559=head3 What's with the strange Backspace/Delete key behaviour?
560
561Assuming that the physical Backspace key corresponds to the
562BackSpace keysym (not likely for Linux ... see the following
563question) there are two standard values that can be used for
564Backspace: C<^H> and C<^?>.
565
566Historically, either value is correct, but rxvt-unicode adopts the debian
567policy of using C<^?> when unsure, because it's the one only only correct
568choice :).
569
570Rxvt-unicode tries to inherit the current stty settings and uses the value
571of `erase' to guess the value for backspace. If rxvt-unicode wasn't
572started from a terminal (say, from a menu or by remote shell), then the
573system value of `erase', which corresponds to CERASE in <termios.h>, will
574be used (which may not be the same as your stty setting).
575
576For starting a new rxvt-unicode:
577
578 # use Backspace = ^H
579 $ stty erase ^H
580 $ @@URXVT_NAME@@
581
582 # use Backspace = ^?
583 $ stty erase ^?
584 $ @@URXVT_NAME@@
585
586Toggle with C<ESC [ 36 h> / C<ESC [ 36 l>.
587
588For an existing rxvt-unicode:
589
590 # use Backspace = ^H
591 $ stty erase ^H
592 $ echo -n "^[[36h"
593
594 # use Backspace = ^?
595 $ stty erase ^?
596 $ echo -n "^[[36l"
597
598This helps satisfy some of the Backspace discrepancies that occur, but
599if you use Backspace = C<^H>, make sure that the termcap/terminfo value
600properly reflects that.
601
602The Delete key is a another casualty of the ill-defined Backspace problem.
603To avoid confusion between the Backspace and Delete keys, the Delete
604key has been assigned an escape sequence to match the vt100 for Execute
605(C<ESC [ 3 ~>) and is in the supplied termcap/terminfo.
606
607Some other Backspace problems:
608
609some editors use termcap/terminfo,
610some editors (vim I'm told) expect Backspace = ^H,
611GNU Emacs (and Emacs-like editors) use ^H for help.
612
613Perhaps someday this will all be resolved in a consistent manner.
614
615=head3 I don't like the key-bindings. How do I change them?
616
617There are some compile-time selections available via configure. Unless
618you have run "configure" with the C<--disable-resources> option you can
619use the `keysym' resource to alter the keystrings associated with keysyms.
620
621Here's an example for a URxvt session started using C<@@URXVT_NAME@@ -name URxvt>
622
623 URxvt.keysym.Home: \033[1~
624 URxvt.keysym.End: \033[4~
625 URxvt.keysym.C-apostrophe: \033<C-'>
626 URxvt.keysym.C-slash: \033<C-/>
627 URxvt.keysym.C-semicolon: \033<C-;>
628 URxvt.keysym.C-grave: \033<C-`>
629 URxvt.keysym.C-comma: \033<C-,>
630 URxvt.keysym.C-period: \033<C-.>
631 URxvt.keysym.C-0x60: \033<C-`>
632 URxvt.keysym.C-Tab: \033<C-Tab>
633 URxvt.keysym.C-Return: \033<C-Return>
634 URxvt.keysym.S-Return: \033<S-Return>
635 URxvt.keysym.S-space: \033<S-Space>
636 URxvt.keysym.M-Up: \033<M-Up>
637 URxvt.keysym.M-Down: \033<M-Down>
638 URxvt.keysym.M-Left: \033<M-Left>
639 URxvt.keysym.M-Right: \033<M-Right>
640 URxvt.keysym.M-C-0: list \033<M-C- 0123456789 >
641 URxvt.keysym.M-C-a: list \033<M-C- abcdefghijklmnopqrstuvwxyz >
642 URxvt.keysym.F12: command:\033]701;zh_CN.GBK\007
643
644See some more examples in the documentation for the B<keysym> resource.
645
646=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
647
648 KP_Insert == Insert
649 F22 == Print
650 F27 == Home
651 F29 == Prior
652 F33 == End
653 F35 == Next
654
655Rather than have rxvt-unicode try to accommodate all the various possible
656keyboard mappings, it is better to use `xmodmap' to remap the keys as
657required for your particular machine.
658
659
660
661=head2 Terminal Configuration
662
663=head3 Why doesn't rxvt-unicode read my resources?
664
665Well, why, indeed? It does, in a way very similar to other X
666applications. Most importantly, this means that if you or your OS loads
667resources into the X display (the right way to do it), rxvt-unicode will
668ignore any resource files in your home directory. It will only read
669F<$HOME/.Xdefaults> when no resources are attached to the display.
670
671If you have or use an F<$HOME/.Xresources> file, chances are that
672resources are loaded into your X-server. In this case, you have to
673re-login after every change (or run F<xrdb -merge $HOME/.Xresources>).
674
675Also consider the form resources have to use:
676
677 URxvt.resource: value
678
679If you want to use another form (there are lots of different ways of
680specifying resources), make sure you understand wether and why it
681works. If unsure, use the form above.
682
683=head3 When I log-in to another system it tells me about missing terminfo data?
684
685The terminal description used by rxvt-unicode is not as widely available
686as that for xterm, or even rxvt (for which the same problem often arises).
687
688The correct solution for this problem is to install the terminfo, this can
689be done like this (with ncurses' infocmp):
690
691 REMOTE=remotesystem.domain
692 infocmp rxvt-unicode | ssh $REMOTE "cat >/tmp/ti && tic /tmp/ti"
693
694... or by installing rxvt-unicode normally on the remote system,
695
696If you cannot or do not want to do this, then you can simply set
697C<TERM=rxvt> or even C<TERM=xterm>, and live with the small number of
698problems arising, which includes wrong keymapping, less and different
699colours and some refresh errors in fullscreen applications. It's a nice
700quick-and-dirty workaround for rare cases, though.
701
702If you always want to do this (and are fine with the consequences) you
703can either recompile rxvt-unicode with the desired TERM value or use a
704resource to set it:
705
706 URxvt.termName: rxvt
707
708If you don't plan to use B<rxvt> (quite common...) you could also replace
709the rxvt terminfo file with the rxvt-unicode one and use C<TERM=rxvt>.
710
711=head3 C<tic> outputs some error when compiling the terminfo entry.
712
713Most likely it's the empty definition for C<enacs=>. Just replace it by
714C<enacs=\E[0@> and try again.
715
716=head3 C<bash>'s readline does not work correctly under @@URXVT_NAME@@.
717
718See next entry.
719
720=head3 I need a termcap file entry.
721
722One reason you might want this is that some distributions or operating
723systems still compile some programs using the long-obsoleted termcap
724library (Fedora Core's bash is one example) and rely on a termcap entry
725for C<rxvt-unicode>.
726
727You could use rxvt's termcap entry with resonable results in many cases.
728You can also create a termcap entry by using terminfo's infocmp program
729like this:
730
731 infocmp -C rxvt-unicode
732
733Or you could use this termcap entry, generated by the command above:
734
735 rxvt-unicode|rxvt-unicode terminal (X Window System):\
736 :am:bw:eo:km:mi:ms:xn:xo:\
737 :co#80:it#8:li#24:lm#0:\
738 :AL=\E[%dL:DC=\E[%dP:DL=\E[%dM:DO=\E[%dB:IC=\E[%d@:\
739 :K1=\EOw:K2=\EOu:K3=\EOy:K4=\EOq:K5=\EOs:LE=\E[%dD:\
740 :RI=\E[%dC:SF=\E[%dS:SR=\E[%dT:UP=\E[%dA:ae=\E(B:al=\E[L:\
741 :as=\E(0:bl=^G:cd=\E[J:ce=\E[K:cl=\E[H\E[2J:\
742 :cm=\E[%i%d;%dH:cr=^M:cs=\E[%i%d;%dr:ct=\E[3g:dc=\E[P:\
743 :dl=\E[M:do=^J:ec=\E[%dX:ei=\E[4l:ho=\E[H:\
744 :i1=\E[?47l\E=\E[?1l:ic=\E[@:im=\E[4h:\
745 :is=\E[r\E[m\E[2J\E[H\E[?7h\E[?1;3;4;6l\E[4l:\
746 :k1=\E[11~:k2=\E[12~:k3=\E[13~:k4=\E[14~:k5=\E[15~:\
747 :k6=\E[17~:k7=\E[18~:k8=\E[19~:k9=\E[20~:kD=\E[3~:\
748 :kI=\E[2~:kN=\E[6~:kP=\E[5~:kb=\177:kd=\EOB:ke=\E[?1l\E>:\
749 :kh=\E[7~:kl=\EOD:kr=\EOC:ks=\E[?1h\E=:ku=\EOA:le=^H:\
750 :mb=\E[5m:md=\E[1m:me=\E[m\017:mr=\E[7m:nd=\E[C:rc=\E8:\
751 :sc=\E7:se=\E[27m:sf=^J:so=\E[7m:sr=\EM:st=\EH:ta=^I:\
752 :te=\E[r\E[?1049l:ti=\E[?1049h:ue=\E[24m:up=\E[A:\
753 :us=\E[4m:vb=\E[?5h\E[?5l:ve=\E[?25h:vi=\E[?25l:\
754 :vs=\E[?25h:
755
756=head3 Why does C<ls> no longer have coloured output?
757
758The C<ls> in the GNU coreutils unfortunately doesn't use terminfo to
759decide wether a terminal has colour, but uses it's own configuration
760file. Needless to say, C<rxvt-unicode> is not in it's default file (among
761with most other terminals supporting colour). Either add:
762
763 TERM rxvt-unicode
764
765to C</etc/DIR_COLORS> or simply add:
766
767 alias ls='ls --color=auto'
768
769to your C<.profile> or C<.bashrc>.
770
771=head3 Why doesn't vim/emacs etc. use the 88 colour mode?
772
773See next entry.
774
775=head3 Why doesn't vim/emacs etc. make use of italic?
776
777See next entry.
778
779=head3 Why are the secondary screen-related options not working properly?
780
781Make sure you are using C<TERM=rxvt-unicode>. Some pre-packaged
782distributions (most notably Debian GNU/Linux) break rxvt-unicode
783by setting C<TERM> to C<rxvt>, which doesn't have these extra
784features. Unfortunately, some of these (most notably, again, Debian
785GNU/Linux) furthermore fail to even install the C<rxvt-unicode> terminfo
786file, so you will need to install it on your own (See the question B<When
787I log-in to another system it tells me about missing terminfo data?> on
788how to do this).
789
790
791=head2 Encoding / Locale / Input Method Issues
792
793=head3 Rxvt-unicode does not seem to understand the selected encoding?
794
795See next entry.
796
797=head3 Unicode does not seem to work?
798
799If you encounter strange problems like typing an accented character but
800getting two unrelated other characters or similar, or if program output is
801subtly garbled, then you should check your locale settings.
802
803Rxvt-unicode must be started with the same C<LC_CTYPE> setting as the
804programs. Often rxvt-unicode is started in the C<C> locale, while the
805login script running within the rxvt-unicode window changes the locale to
806something else, e.g. C<en_GB.UTF-8>. Needless to say, this is not going to work.
807
808The best thing is to fix your startup environment, as you will likely run
809into other problems. If nothing works you can try this in your .profile.
810
811 printf '\e]701;%s\007' "$LC_CTYPE"
812
813If this doesn't work, then maybe you use a C<LC_CTYPE> specification not
814supported on your systems. Some systems have a C<locale> command which
815displays this (also, C<perl -e0> can be used to check locale settings, as
816it will complain loudly if it cannot set the locale). If it displays something
817like:
818
819 locale: Cannot set LC_CTYPE to default locale: ...
820
821Then the locale you specified is not supported on your system.
822
823If nothing works and you are sure that everything is set correctly then
824you will need to remember a little known fact: Some programs just don't
825support locales :(
826
827=head3 How does rxvt-unicode determine the encoding to use?
828
829See next entry.
830
831=head3 Is there an option to switch encodings?
832
833Unlike some other terminals, rxvt-unicode has no encoding switch, and no
834specific "utf-8" mode, such as xterm. In fact, it doesn't even know about
835UTF-8 or any other encodings with respect to terminal I/O.
836
837The reasons is that there exists a perfectly fine mechanism for selecting
838the encoding, doing I/O and (most important) communicating this to all
839applications so everybody agrees on character properties such as width
840and code number. This mechanism is the I<locale>. Applications not using
841that info will have problems (for example, C<xterm> gets the width of
842characters wrong as it uses it's own, locale-independent table under all
843locales).
844
845Rxvt-unicode uses the C<LC_CTYPE> locale category to select encoding. All
846programs doing the same (that is, most) will automatically agree in the
847interpretation of characters.
848
849Unfortunately, there is no system-independent way to select locales, nor
850is there a standard on how locale specifiers will look like.
851
852On most systems, the content of the C<LC_CTYPE> environment variable
853contains an arbitrary string which corresponds to an already-installed
854locale. Common names for locales are C<en_US.UTF-8>, C<de_DE.ISO-8859-15>,
855C<ja_JP.EUC-JP>, i.e. C<language_country.encoding>, but other forms
856(i.e. C<de> or C<german>) are also common.
857
858Rxvt-unicode ignores all other locale categories, and except for
859the encoding, ignores country or language-specific settings,
860i.e. C<de_DE.UTF-8> and C<ja_JP.UTF-8> are the normally same to
861rxvt-unicode.
862
863If you want to use a specific encoding you have to make sure you start
864rxvt-unicode with the correct C<LC_CTYPE> category.
865
866=head3 Can I switch locales at runtime?
867
868Yes, using an escape sequence. Try something like this, which sets
869rxvt-unicode's idea of C<LC_CTYPE>.
870
871 printf '\e]701;%s\007' ja_JP.SJIS
872
873See also the previous answer.
874
875Sometimes this capability is rather handy when you want to work in
876one locale (e.g. C<de_DE.UTF-8>) but some programs don't support it
877(e.g. UTF-8). For example, I use this script to start C<xjdic>, which
878first switches to a locale supported by xjdic and back later:
879
880 printf '\e]701;%s\007' ja_JP.SJIS
881 xjdic -js
882 printf '\e]701;%s\007' de_DE.UTF-8
883
884You can also use xterm's C<luit> program, which usually works fine, except
885for some locales where character width differs between program- and
886rxvt-unicode-locales.
887
888=head3 I have problems getting my input method working.
889
890Try a search engine, as this is slightly different for every input method server.
891
892Here is a checklist:
893
894=over 4
895
896=item - Make sure your locale I<and> the imLocale are supported on your OS.
897
898Try C<locale -a> or check the documentation for your OS.
899
900=item - Make sure your locale or imLocale matches a locale supported by your XIM.
901
902For example, B<kinput2> does not support UTF-8 locales, you should use
903C<ja_JP.EUC-JP> or equivalent.
904
905=item - Make sure your XIM server is actually running.
906
907=item - Make sure the C<XMODIFIERS> environment variable is set correctly when I<starting> rxvt-unicode.
908
909When you want to use e.g. B<kinput2>, it must be set to
910C<@im=kinput2>. For B<scim>, use C<@im=SCIM>. Youc an see what input
911method servers are running with this command:
912
913 xprop -root XIM_SERVERS
914
915=item
916
917=back
918
919=head3 My input method wants <some encoding> but I want UTF-8, what can I do?
920
921You can specify separate locales for the input method and the rest of the
922terminal, using the resource C<imlocale>:
923
924 URxvt.imlocale: ja_JP.EUC-JP
925
926Now you can start your terminal with C<LC_CTYPE=ja_JP.UTF-8> and still
927use your input method. Please note, however, that, depending on your Xlib
928version, you may not be able to input characters outside C<EUC-JP> in a
929normal way then, as your input method limits you.
930
931=head3 Rxvt-unicode crashes when the X Input Method changes or exits.
932
933Unfortunately, this is unavoidable, as the XIM protocol is racy by
934design. Applications can avoid some crashes at the expense of memory
935leaks, and Input Methods can avoid some crashes by careful ordering at
936exit time. B<kinput2> (and derived input methods) generally succeeds,
937while B<SCIM> (or similar input methods) fails. In the end, however,
938crashes cannot be completely avoided even if both sides cooperate.
939
940So the only workaround is not to kill your Input Method Servers.
941
942
943=head2 Operating Systems / Package Maintaining
944
945=head3 I am using Debian GNU/Linux and have a problem...
946
947The Debian GNU/Linux package of rxvt-unicode in sarge contains large
948patches that considerably change the behaviour of rxvt-unicode (but
949unfortunately this notice has been removed). Before reporting a bug to
950the original rxvt-unicode author please download and install the genuine
951version (L<http://software.schmorp.de#rxvt-unicode>) and try to reproduce
952the problem. If you cannot, chances are that the problems are specific to
953Debian GNU/Linux, in which case it should be reported via the Debian Bug
954Tracking System (use C<reportbug> to report the bug).
955
956For other problems that also affect the Debian package, you can and
957probably should use the Debian BTS, too, because, after all, it's also a
958bug in the Debian version and it serves as a reminder for other users that
959might encounter the same issue.
960
961=head3 I am maintaining rxvt-unicode for distribution/OS XXX, any recommendation?
962
963You should build one binary with the default options. F<configure>
964now enables most useful options, and the trend goes to making them
965runtime-switchable, too, so there is usually no drawback to enbaling them,
966except higher disk and possibly memory usage. The perl interpreter should
967be enabled, as important functionality (menus, selection, likely more in
968the future) depends on it.
969
970You should not overwrite the C<perl-ext-common> snd C<perl-ext> resources
971system-wide (except maybe with C<defaults>). This will result in useful
972behaviour. If your distribution aims at low memory, add an empty
973C<perl-ext-common> resource to the app-defaults file. This will keep the
974perl interpreter disabled until the user enables it.
975
976If you can/want build more binaries, I recommend building a minimal
977one with C<--disable-everything> (very useful) and a maximal one with
978C<--enable-everything> (less useful, it will be very big due to a lot of
979encodings built-in that increase download times and are rarely used).
980
981=head3 I need to make it setuid/setgid to support utmp/ptys on my OS, is this safe?
982
983It should be, starting with release 7.1. You are encouraged to properly
984install urxvt with privileges necessary for your OS now.
985
986When rxvt-unicode detects that it runs setuid or setgid, it will fork
987into a helper process for privileged operations (pty handling on some
988systems, utmp/wtmp/lastlog handling on others) and drop privileges
989immediately. This is much safer than most other terminals that keep
990privileges while running (but is more relevant to urxvt, as it contains
991things as perl interpreters, which might be "helpful" to attackers).
992
993This forking is done as the very first within main(), which is very early
994and reduces possible bugs to initialisation code run before main(), or
995things like the dynamic loader of your system, which should result in very
996little risk.
997
998=head3 On Solaris 9, many line-drawing characters are too wide.
999
1000Seems to be a known bug, read
1001L<http://nixdoc.net/files/forum/about34198.html>. Some people use the
1002following ugly workaround to get non-double-wide-characters working:
1003
1004 #define wcwidth(x) wcwidth(x) > 1 ? 1 : wcwidth(x)
1005
1006=head3 I am on FreeBSD and rxvt-unicode does not seem to work at all.
1007
1008Rxvt-unicode requires the symbol C<__STDC_ISO_10646__> to be defined
1009in your compile environment, or an implementation that implements it,
1010wether it defines the symbol or not. C<__STDC_ISO_10646__> requires that
1011B<wchar_t> is represented as unicode.
1012
1013As you might have guessed, FreeBSD does neither define this symobl nor
1014does it support it. Instead, it uses it's own internal representation of
1015B<wchar_t>. This is, of course, completely fine with respect to standards.
1016
1017However, that means rxvt-unicode only works in C<POSIX>, C<ISO-8859-1> and
1018C<UTF-8> locales under FreeBSD (which all use Unicode as B<wchar_t>.
1019
1020C<__STDC_ISO_10646__> is the only sane way to support multi-language
1021apps in an OS, as using a locale-dependent (and non-standardized)
1022representation of B<wchar_t> makes it impossible to convert between
1023B<wchar_t> (as used by X11 and your applications) and any other encoding
1024without implementing OS-specific-wrappers for each and every locale. There
1025simply are no APIs to convert B<wchar_t> into anything except the current
1026locale encoding.
1027
1028Some applications (such as the formidable B<mlterm>) work around this
1029by carrying their own replacement functions for character set handling
1030with them, and either implementing OS-dependent hacks or doing multiple
1031conversions (which is slow and unreliable in case the OS implements
1032encodings slightly different than the terminal emulator).
1033
1034The rxvt-unicode author insists that the right way to fix this is in the
1035system libraries once and for all, instead of forcing every app to carry
1036complete replacements for them :)
1037
1038=head3 I use Solaris 9 and it doesn't compile/work/etc.
1039
1040Try the diff in F<doc/solaris9.patch> as a base. It fixes the worst
1041problems with C<wcwidth> and a compile problem.
1042
1043=head3 How can I use rxvt-unicode under cygwin?
1044
1045rxvt-unicode should compile and run out of the box on cygwin, using
1046the X11 libraries that come with cygwin. libW11 emulation is no
1047longer supported (and makes no sense, either, as it only supported a
1048single font). I recommend starting the X-server in C<-multiwindow> or
1049C<-rootless> mode instead, which will result in similar look&feel as the
1050old libW11 emulation.
1051
1052At the time of this writing, cygwin didn't seem to support any multi-byte
1053encodings (you might try C<LC_CTYPE=C-UTF-8>), so you are likely limited
1054to 8-bit encodings.
1055
1056=head1 RXVT-UNICODE TECHNICAL REFERENCE
1057
1058The rest of this document describes various technical aspects of
1059B<rxvt-unicode>. First the description of supported command sequences,
1060followed by pixmap support and last by a description of all features
1061selectable at C<configure> time.
1062
7=head1 Definitions 1063=head2 Definitions
8 1064
9=over 4 1065=over 4
10 1066
11=item B<< C<c> >> 1067=item B<< C<c> >>
12 1068
… …
30 1086
31A text parameter composed of printable characters. 1087A text parameter composed of printable characters.
32 1088
33=back 1089=back
34 1090
35=head1 Values 1091=head2 Values
36 1092
37=over 4 1093=over 4
38 1094
39=item B<< C<ENQ> >> 1095=item B<< C<ENQ> >>
40 1096
41Enquiry (Ctrl-E) = Send Device Attributes (DA) 1097Enquiry (Ctrl-E) = Send Device Attributes (DA)
42request attributes from terminal == 1098request attributes from terminal. See B<< C<ESC [ Ps c> >>.
43 1099
44=item B<< C<BEL> >> 1100=item B<< C<BEL> >>
45 1101
46Bell (Ctrl-G) 1102Bell (Ctrl-G)
47 1103
… …
83 1139
84Space Character 1140Space Character
85 1141
86=back 1142=back
87 1143
88=head1 Escape Sequences 1144=head2 Escape Sequences
89 1145
90=over 4 1146=over 4
91 1147
92=item B<< C<ESC # 8> >> 1148=item B<< C<ESC # 8> >>
93 1149
… …
139Single Shift Select of G3 Character Set (SS3): affects next character 1195Single Shift Select of G3 Character Set (SS3): affects next character
140only I<unimplemented> 1196only I<unimplemented>
141 1197
142=item B<< C<ESC Z> >> 1198=item B<< C<ESC Z> >>
143 1199
144Obsolete form of returns: B<< C<ESC[?1;2C> >> I<rxvt compile-time option> 1200Obsolete form of returns: B<< C<ESC [ ? 1 ; 2 C> >> I<rxvt-unicode compile-time option>
145 1201
146=item B<< C<ESC c> >> 1202=item B<< C<ESC c> >>
147 1203
148Full reset (RIS) 1204Full reset (RIS)
149 1205
… …
153 1209
154=item B<< C<ESC o> >> 1210=item B<< C<ESC o> >>
155 1211
156Invoke the G3 Character Set (LS3) 1212Invoke the G3 Character Set (LS3)
157 1213
158=item B<< C<ESC>(C<C> >> 1214=item B<< C<ESC ( C> >>
159 1215
160Designate G0 Character Set (ISO 2022), see below for values of C<C>. 1216Designate G0 Character Set (ISO 2022), see below for values of C<C>.
161 1217
162=item B<< C<ESC>)C<C> >> 1218=item B<< C<ESC ) C> >>
163 1219
164Designate G1 Character Set (ISO 2022), see below for values of C<C>. 1220Designate G1 Character Set (ISO 2022), see below for values of C<C>.
165 1221
166=item B<< C<ESC * C> >> 1222=item B<< C<ESC * C> >>
167 1223
… …
191 1247
192=back 1248=back
193 1249
194X<CSI> 1250X<CSI>
195 1251
196=head1 CSI (Code Sequence Introducer) Sequences 1252=head2 CSI (Command Sequence Introducer) Sequences
197 1253
198=over 4 1254=over 4
199 1255
200=item B<< C<ESC [ Ps @> >> 1256=item B<< C<ESC [ Ps @> >>
201 1257
… …
298 1354
299Move backward B<< C<Ps> >> [default: 1] tab stops 1355Move backward B<< C<Ps> >> [default: 1] tab stops
300 1356
301=item B<< C<ESC [ Ps '> >> 1357=item B<< C<ESC [ Ps '> >>
302 1358
303== 1359See B<< C<ESC [ Ps G> >>
304 1360
305=item B<< C<ESC [ Ps a> >> 1361=item B<< C<ESC [ Ps a> >>
306 1362
307==X<ESCOBPsc> 1363See B<< C<ESC [ Ps C> >>
308 1364
309=item B<< C<ESC [ Ps c> >> 1365=item B<< C<ESC [ Ps c> >>
310 1366
311Send Device Attributes (DA) 1367Send Device Attributes (DA)
312B<< C<Ps = 0> >> (or omitted): request attributes from terminal 1368B<< C<Ps = 0> >> (or omitted): request attributes from terminal
313returns: B<< C<ESC[?1;2c> >> (``I am a VT100 with Advanced Video 1369returns: B<< C<ESC [ ? 1 ; 2 c> >> (``I am a VT100 with Advanced Video
314Option'') 1370Option'')
315 1371
316=item B<< C<ESC [ Ps d> >> 1372=item B<< C<ESC [ Ps d> >>
317 1373
318Cursor to Line B<< C<Ps> >> (VPA) 1374Cursor to Line B<< C<Ps> >> (VPA)
319 1375
320=item B<< C<ESC [ Ps e> >> 1376=item B<< C<ESC [ Ps e> >>
321 1377
322== 1378See B<< C<ESC [ Ps A> >>
323 1379
324=item B<< C<ESC [ Ps;Ps f> >> 1380=item B<< C<ESC [ Ps;Ps f> >>
325 1381
326Horizontal and Vertical Position [row;column] (HVP) [default: 1;1] 1382Horizontal and Vertical Position [row;column] (HVP) [default: 1;1]
327 1383
… …
334 B<< C<Ps = 0> >> Clear Current Column (default) 1390 B<< C<Ps = 0> >> Clear Current Column (default)
335 B<< C<Ps = 3> >> Clear All (TBC) 1391 B<< C<Ps = 3> >> Clear All (TBC)
336 1392
337=end table 1393=end table
338 1394
1395=item B<< C<ESC [ Pm h> >>
1396
1397Set Mode (SM). See B<< C<ESC [ Pm l> >> sequence for description of C<Pm>.
1398
339=item B<< C<ESC [ Ps i> >> 1399=item B<< C<ESC [ Ps i> >>
340 1400
341Printing 1401Printing. See also the C<print-pipe> resource.
342 1402
343=begin table 1403=begin table
344 1404
1405 B<< C<Ps = 0> >> print screen (MC0)
345 B<< C<Ps = 4> >> disable transparent print mode (MC4) 1406 B<< C<Ps = 4> >> disable transparent print mode (MC4)
346 B<< C<Ps = 5> >> enable transparent print mode (MC5) I<unimplemented> 1407 B<< C<Ps = 5> >> enable transparent print mode (MC5)
347 1408
348=end table 1409=end table
349
350=item B<< C<ESC [ Pm h> >>
351
352Set Mode (SM). See next sequence for description of C<Pm>.
353 1410
354=item B<< C<ESC [ Pm l> >> 1411=item B<< C<ESC [ Pm l> >>
355 1412
356Reset Mode (RM) 1413Reset Mode (RM)
357 1414
… …
364 B<< C<h> >> Insert Mode (SMIR) 1421 B<< C<h> >> Insert Mode (SMIR)
365 B<< C<l> >> Replace Mode (RMIR) 1422 B<< C<l> >> Replace Mode (RMIR)
366 1423
367=end table 1424=end table
368 1425
369=item B<< C<Ps = 20> >> I<unimplemented> 1426=item B<< C<Ps = 20> >> (partially implemented)
370 1427
371=begin table 1428=begin table
372 1429
373 B<< C<h> >> Automatic Newline (LNM) 1430 B<< C<h> >> Automatic Newline (LNM)
374 B<< C<h> >> Normal Linefeed (LNM) 1431 B<< C<l> >> Normal Linefeed (LNM)
375 1432
376=end table 1433=end table
377 1434
378=back 1435=back
379 1436
… …
382Character Attributes (SGR) 1439Character Attributes (SGR)
383 1440
384=begin table 1441=begin table
385 1442
386 B<< C<Ps = 0> >> Normal (default) 1443 B<< C<Ps = 0> >> Normal (default)
387 B<< C<Ps = 1 / 22> >> On / Off Bold (bright fg) 1444 B<< C<Ps = 1 / 21> >> On / Off Bold (bright fg)
1445 B<< C<Ps = 3 / 23> >> On / Off Italic
388 B<< C<Ps = 4 / 24> >> On / Off Underline 1446 B<< C<Ps = 4 / 24> >> On / Off Underline
389 B<< C<Ps = 5 / 25> >> On / Off Blink (bright bg) 1447 B<< C<Ps = 5 / 25> >> On / Off Slow Blink (bright bg)
1448 B<< C<Ps = 6 / 26> >> On / Off Rapid Blink (bright bg)
390 B<< C<Ps = 7 / 27> >> On / Off Inverse 1449 B<< C<Ps = 7 / 27> >> On / Off Inverse
1450 B<< C<Ps = 8 / 27> >> On / Off Invisible (NYI)
391 B<< C<Ps = 30 / 40> >> fg/bg Black 1451 B<< C<Ps = 30 / 40> >> fg/bg Black
392 B<< C<Ps = 31 / 41> >> fg/bg Red 1452 B<< C<Ps = 31 / 41> >> fg/bg Red
393 B<< C<Ps = 32 / 42> >> fg/bg Green 1453 B<< C<Ps = 32 / 42> >> fg/bg Green
394 B<< C<Ps = 33 / 43> >> fg/bg Yellow 1454 B<< C<Ps = 33 / 43> >> fg/bg Yellow
395 B<< C<Ps = 34 / 44> >> fg/bg Blue 1455 B<< C<Ps = 34 / 44> >> fg/bg Blue
396 B<< C<Ps = 35 / 45> >> fg/bg Magenta 1456 B<< C<Ps = 35 / 45> >> fg/bg Magenta
397 B<< C<Ps = 36 / 46> >> fg/bg Cyan 1457 B<< C<Ps = 36 / 46> >> fg/bg Cyan
1458 B<< C<Ps = 38;5 / 48;5> >> set fg/bg to color #m (ISO 8613-6)
398 B<< C<Ps = 37 / 47> >> fg/bg White 1459 B<< C<Ps = 37 / 47> >> fg/bg White
399 B<< C<Ps = 39 / 49> >> fg/bg Default 1460 B<< C<Ps = 39 / 49> >> fg/bg Default
1461 B<< C<Ps = 90 / 100> >> fg/bg Bright Black
1462 B<< C<Ps = 91 / 101> >> fg/bg Bright Red
1463 B<< C<Ps = 92 / 102> >> fg/bg Bright Green
1464 B<< C<Ps = 93 / 103> >> fg/bg Bright Yellow
1465 B<< C<Ps = 94 / 104> >> fg/bg Bright Blue
1466 B<< C<Ps = 95 / 105> >> fg/bg Bright Magenta
1467 B<< C<Ps = 96 / 106> >> fg/bg Bright Cyan
1468 B<< C<Ps = 97 / 107> >> fg/bg Bright White
1469 B<< C<Ps = 99 / 109> >> fg/bg Bright Default
400 1470
401=end table 1471=end table
402 1472
403=item B<< C<ESC [ Ps n> >> 1473=item B<< C<ESC [ Ps n> >>
404 1474
… …
420 1490
421=item B<< C<ESC [ s> >> 1491=item B<< C<ESC [ s> >>
422 1492
423Save Cursor (SC) 1493Save Cursor (SC)
424 1494
1495=item B<< C<ESC [ Ps;Pt t> >>
1496
1497Window Operations
1498
1499=begin table
1500
1501 B<< C<Ps = 1> >> Deiconify (map) window
1502 B<< C<Ps = 2> >> Iconify window
1503 B<< C<Ps = 3> >> B<< C<ESC [ 3 ; X ; Y t> >> Move window to (X|Y)
1504 B<< C<Ps = 4> >> B<< C<ESC [ 4 ; H ; W t> >> Resize to WxH pixels
1505 B<< C<Ps = 5> >> Raise window
1506 B<< C<Ps = 6> >> Lower window
1507 B<< C<Ps = 7> >> Refresh screen once
1508 B<< C<Ps = 8> >> B<< C<ESC [ 8 ; R ; C t> >> Resize to R rows and C columns
1509 B<< C<Ps = 11> >> Report window state (responds with C<Ps = 1> or C<Ps = 2>)
1510 B<< C<Ps = 13> >> Report window position (responds with C<Ps = 3>)
1511 B<< C<Ps = 14> >> Report window pixel size (responds with C<Ps = 4>)
1512 B<< C<Ps = 18> >> Report window text size (responds with C<Ps = 7>)
1513 B<< C<Ps = 19> >> Currently the same as C<Ps = 18>, but responds with C<Ps = 9>
1514 B<< C<Ps = 20> >> Reports icon label (B<< C<ESC ] L NAME \234> >>)
1515 B<< C<Ps = 21> >> Reports window title (B<< C<ESC ] l NAME \234> >>)
1516 B<< C<Ps = 24..> >> Set window height to C<Ps> rows
1517
1518=end table
1519
1520=item B<< C<ESC [ u> >>
1521
1522Restore Cursor
1523
425=item B<< C<ESC [ Ps x> >> 1524=item B<< C<ESC [ Ps x> >>
426 1525
427Request Terminal Parameters (DECREQTPARM) 1526Request Terminal Parameters (DECREQTPARM)
428 1527
429=item B<< C<ESC [ u> >>
430
431Restore Cursor
432
433=back 1528=back
434 1529
435X<PrivateModes> 1530X<PrivateModes>
436 1531
437=head1 DEC Private Modes 1532=head2 DEC Private Modes
438 1533
439=over 4 1534=over 4
440 1535
441=item B<< C<ESC [ ? Pm h> >> 1536=item B<< C<ESC [ ? Pm h> >>
442 1537
… …
539 B<< C<h> >> Send Mouse X & Y on button press. 1634 B<< C<h> >> Send Mouse X & Y on button press.
540 B<< C<l> >> No mouse reporting. 1635 B<< C<l> >> No mouse reporting.
541 1636
542=end table 1637=end table
543 1638
544)X<Priv10>
545
546=item B<< C<Ps = 10> >> (B<rxvt>)
547
548=begin table
549
550 B<< C<h> >> visible
551 B<< C<l> >> invisible
552
553=end table
554
555=item B<< C<Ps = 25> >> 1639=item B<< C<Ps = 25> >>
556 1640
557=begin table 1641=begin table
558 1642
559 B<< C<h> >> Visible cursor {cnorm/cvvis} 1643 B<< C<h> >> Visible cursor {cnorm/cvvis}
… …
625 1709
626=item B<< C<Ps = 66> >> 1710=item B<< C<Ps = 66> >>
627 1711
628=begin table 1712=begin table
629 1713
630 B<< C<h> >> Application Keypad (DECPAM) == 1714 B<< C<h> >> Application Keypad (DECPAM) == C<ESC =>
631 B<< C<l> >> Normal Keypad (DECPNM) == 1715 B<< C<l> >> Normal Keypad (DECPNM) == C<< ESC > >>
632 1716
633=end table 1717=end table
634 1718
635=item B<< C<Ps = 67> >> 1719=item B<< C<Ps = 67> >>
636 1720
… …
657 B<< C<h> >> Use Hilite Mouse Tracking. 1741 B<< C<h> >> Use Hilite Mouse Tracking.
658 B<< C<l> >> No mouse reporting. 1742 B<< C<l> >> No mouse reporting.
659 1743
660=end table 1744=end table
661 1745
662=item B<< C<Ps = 1010> >> 1746=item B<< C<Ps = 1010> >> (B<rxvt>)
663 1747
664=begin table 1748=begin table
665 1749
666 B<< C<h> >> Don't scroll to bottom on TTY output 1750 B<< C<h> >> Don't scroll to bottom on TTY output
667 B<< C<l> >> Scroll to bottom on TTY output 1751 B<< C<l> >> Scroll to bottom on TTY output
668 1752
669=end table 1753=end table
670 1754
671=item B<< C<Ps = 1011> >> 1755=item B<< C<Ps = 1011> >> (B<rxvt>)
672 1756
673=begin table 1757=begin table
674 1758
675 B<< C<h> >> Scroll to bottom when a key is pressed 1759 B<< C<h> >> Scroll to bottom when a key is pressed
676 B<< C<l> >> Don't scroll to bottom when a key is pressed 1760 B<< C<l> >> Don't scroll to bottom when a key is pressed
677 1761
678=end table 1762=end table
679 1763
1764=item B<< C<Ps = 1021> >> (B<rxvt>)
1765
1766=begin table
1767
1768 B<< C<h> >> Bold/italic implies high intensity (see option B<-is>)
1769 B<< C<l> >> Font styles have no effect on intensity (Compile styles)
1770
1771=end table
1772
680=item B<< C<Ps = 1047> >> 1773=item B<< C<Ps = 1047> >>
681 1774
682=begin table 1775=begin table
683 1776
684 B<< C<h> >> Use Alternate Screen Buffer 1777 B<< C<h> >> Use Alternate Screen Buffer
… …
693 B<< C<h> >> Save cursor position 1786 B<< C<h> >> Save cursor position
694 B<< C<l> >> Restore cursor position 1787 B<< C<l> >> Restore cursor position
695 1788
696=end table 1789=end table
697 1790
1791=item B<< C<Ps = 1049> >>
1792
1793=begin table
1794
1795 B<< C<h> >> Use Alternate Screen Buffer - clear Alternate Screen Buffer if switching to it
1796 B<< C<l> >> Use Normal Screen Buffer
1797
1798=end table
1799
698=back 1800=back
699 1801
700=back 1802=back
701 1803
702X<XTerm> 1804X<XTerm>
703 1805
704=head1 XTerm Operating System Commands 1806=head2 XTerm Operating System Commands
705 1807
706=over 4 1808=over 4
707 1809
708=item B<< C<ESC ] Ps;Pt ST> >> 1810=item B<< C<ESC ] Ps;Pt ST> >>
709 1811
… …
721 B<< C<Ps = 10> >> Change colour of text foreground to B<< C<Pt> >> B<(NB: may change in future)> 1823 B<< C<Ps = 10> >> Change colour of text foreground to B<< C<Pt> >> B<(NB: may change in future)>
722 B<< C<Ps = 11> >> Change colour of text background to B<< C<Pt> >> B<(NB: may change in future)> 1824 B<< C<Ps = 11> >> Change colour of text background to B<< C<Pt> >> B<(NB: may change in future)>
723 B<< C<Ps = 12> >> Change colour of text cursor foreground to B<< C<Pt> >> 1825 B<< C<Ps = 12> >> Change colour of text cursor foreground to B<< C<Pt> >>
724 B<< C<Ps = 13> >> Change colour of mouse foreground to B<< C<Pt> >> 1826 B<< C<Ps = 13> >> Change colour of mouse foreground to B<< C<Pt> >>
725 B<< C<Ps = 17> >> Change colour of highlight characters to B<< C<Pt> >> 1827 B<< C<Ps = 17> >> Change colour of highlight characters to B<< C<Pt> >>
726 B<< C<Ps = 18> >> Change colour of bold characters to B<< C<Pt> >> 1828 B<< C<Ps = 18> >> Change colour of bold characters to B<< C<Pt> >> [deprecated, see 706]
727 B<< C<Ps = 19> >> Change colour of underlined characters to B<< C<Pt> >> 1829 B<< C<Ps = 19> >> Change colour of underlined characters to B<< C<Pt> >> [deprecated, see 707]
1830 B<< C<Ps = 20> >> Change background pixmap parameters (see section XPM) (Compile XPM).
728 B<< C<Ps = 20> >> Change default background to B<< C<Pt> >> 1831 B<< C<Ps = 39> >> Change default foreground colour to B<< C<Pt> >>.
729 B<< C<Ps = 39> >> Change default foreground colour to B<< C<Pt> >> I<rxvt compile-time option>
730 B<< C<Ps = 46> >> Change Log File to B<< C<Pt> >> I<unimplemented> 1832 B<< C<Ps = 46> >> Change Log File to B<< C<Pt> >> I<unimplemented>
731 B<< C<Ps = 49> >> Change default background colour to B<< C<Pt> >> I<rxvt compile-time option> 1833 B<< C<Ps = 49> >> Change default background colour to B<< C<Pt> >>.
732 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> >> 1834 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> >>
733 B<< C<Ps = 55> >> Log all scrollback buffer and all of screen to B<< C<Pt> >> 1835 B<< C<Ps = 55> >> Log all scrollback buffer and all of screen to B<< C<Pt> >>
734 B<< C<Ps = 701> >> Change current locale to B<< C<Pt> >>, or, if B<< C<Pt> >> is B<< C<?> >>, return the current locale (@@RXVTNAME@@ extension) 1836 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).
735 B<< C<Ps = 702> >> find font for character, used for debugging (@@RXVTNAME@@ extension) 1837 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>.
736 B<< C<Ps = 703> >> command B<< C<Pt> >> I<rxvt compile-time option> (@@RXVTNAME@@ extension) 1838 B<< C<Ps = 704> >> Change colour of italic characters to B<< C<Pt> >>
1839 B<< C<Ps = 705> >> Change background pixmap tint colour to B<< C<Pt> >> (Compile transparency).
1840 B<< C<Ps = 706> >> Change colour of bold characters to B<< C<Pt> >>
1841 B<< C<Ps = 707> >> Change colour of underlined characters to B<< C<Pt> >>
1842 B<< C<Ps = 710> >> Set normal fontset to B<< C<Pt> >>. Same as C<Ps = 50>.
1843 B<< C<Ps = 711> >> Set bold fontset to B<< C<Pt> >>. Similar to C<Ps = 50> (Compile styles).
1844 B<< C<Ps = 712> >> Set italic fontset to B<< C<Pt> >>. Similar to C<Ps = 50> (Compile styles).
1845 B<< C<Ps = 713> >> Set bold-italic fontset to B<< C<Pt> >>. Similar to C<Ps = 50> (Compile styles).
1846 B<< C<Ps = 720> >> Move viewing window up by B<< C<Pt> >> lines, or clear scrollback buffer if C<Pt = 0> (Compile frills).
1847 B<< C<Ps = 721> >> Move viewing window down by B<< C<Pt> >> lines, or clear scrollback buffer if C<Pt = 0> (Compile frills).
1848 B<< C<Ps = 777> >> Call the perl extension with the given string, which should be of the form C<extension:parameters> (Compile perl).
737 1849
738=end table 1850=end table
739 1851
740=back 1852=back
741
742X<menuBar>
743
744=head1 menuBar
745
746B<< The exact syntax used is I<almost> solidified. >>
747In the menus, B<DON'T> try to use menuBar commands that add or remove a
748menuBar.
749
750Note that in all of the commands, the B<< I</path/> >> I<cannot> be
751omitted: use B<./> to specify a menu relative to the current menu.
752
753=head2 Overview of menuBar operation
754
755For the menuBar XTerm escape sequence C<ESC ] 703 ; Pt ST>, the syntax
756of C<Pt> can be used for a variety of tasks:
757
758At the top level is the current menuBar which is a member of a circular
759linked-list of other such menuBars.
760
761The menuBar acts as a parent for the various drop-down menus, which in
762turn, may have labels, separator lines, menuItems and subMenus.
763
764The menuItems are the useful bits: you can use them to mimic keyboard
765input or even to send text or escape sequences back to rxvt.
766
767The menuBar syntax is intended to provide a simple yet robust method of
768constructing and manipulating menus and navigating through the
769menuBars.
770
771The first step is to use the tag B<< [menu:I<name>] >> which creates
772the menuBar called I<name> and allows access. You may now or menus,
773subMenus, and menuItems. Finally, use the tag B<[done]> to set the
774menuBar access as B<readonly> to prevent accidental corruption of the
775menus. To re-access the current menuBar for alterations, use the tag
776B<[menu]>, make the alterations and then use B<[done]>
777
778X<menuBarCommands>
779
780=head2 Commands
781
782=over 4
783
784=item B<< [menu:+I<name>] >>
785
786access the named menuBar for creation or alteration. If a new menuBar
787is created, it is called I<name> (max of 15 chars) and the current
788menuBar is pushed onto the stack
789
790=item B<[menu]>
791
792access the current menuBar for alteration
793
794=item B<< [title:+I<string>] >>
795
796set the current menuBar's title to I<string>, which may contain the
797following format specifiers:
798B<%%> : literal B<%> character
799B<%n> : rxvt name (as per the B<-name> command-line option)
800B<%v> : rxvt version
801
802=item B<[done]>
803
804set menuBar access as B<readonly>.
805End-of-file tag for B<< [read:+I<file>] >> operations.
806
807=item B<< [read:+I<file>] >>
808
809read menu commands directly from I<file> (extension ".menu" will be
810appended if required.) Start reading at a line with B<[menu]> or B<<
811[menu:+I<name> >> and continuing until B<[done]> is encountered.
812
813Blank and comment lines (starting with B<#>) are ignored. Actually,
814since any invalid menu commands are also ignored, almost anything could
815be construed as a comment line, but this may be tightened up in the
816future ... so don't count on it!.
817
818=item B<< [read:+I<file>;+I<name>] >>
819
820The same as B<< [read:+I<file>] >>, but start reading at a line with
821B<< [menu:+I<name>] >> and continuing until B<< [done:+I<name>] >> or
822B<[done]> is encountered.
823
824=item B<[dump]>
825
826dump all menuBars to the file B</tmp/rxvt-PID> in a format suitable for
827later rereading.
828
829=item B<[rm:name]>
830
831remove the named menuBar
832
833=item B<[rm] [rm:]>
834
835remove the current menuBar
836
837=item B<[rm*] [rm:*]>
838
839remove all menuBars
840
841=item B<[swap]>
842
843swap the top two menuBars
844
845=item B<[prev]>
846
847access the previous menuBar
848
849=item B<[next]>
850
851access the next menuBar
852
853=item B<[show]>
854
855Enable display of the menuBar
856
857=item B<[hide]>
858
859Disable display of the menuBar
860
861=item B<< [pixmap:+I<name>] >>
862
863=item B<< [pixmap:+I<name>;I<scaling>] >>
864
865(set the background pixmap globally
866
867B<< A Future implementation I<may> make this local to the menubar >>)
868
869=item B<< [:+I<command>:] >>
870
871ignore the menu readonly status and issue a I<command> to or a menu or
872menuitem or change the ; a useful shortcut for setting the quick arrows
873from a menuBar.
874
875=back
876
877X<menuBarAdd>
878
879=head2 Adding and accessing menus
880
881The following commands may also be B<+> prefixed.
882
883=over 4
884
885=item B</+>
886
887access menuBar top level
888
889=item B<./+>
890
891access current menu level
892
893=item B<../+>
894
895access parent menu (1 level up)
896
897=item B<../../>
898
899access parent menu (multiple levels up)
900
901=item B<< I</path/>menu >>
902
903add/access menu
904
905=item B<< I</path/>menu/* >>
906
907add/access menu and clear it if it exists
908
909=item B<< I</path/>{-} >>
910
911add separator
912
913=item B<< I</path/>{item} >>
914
915add B<item> as a label
916
917=item B<< I</path/>{item} action >>
918
919add/alter I<menuitem> with an associated I<action>
920
921=item B<< I</path/>{item}{right-text} >>
922
923add/alter I<menuitem> with B<right-text> as the right-justified text
924and as the associated I<action>
925
926=item B<< I</path/>{item}{rtext} action >>
927
928add/alter I<menuitem> with an associated I<action> and with B<rtext> as
929the right-justified text.
930
931=back
932
933=over 4
934
935=item Special characters in I<action> must be backslash-escaped:
936
937B<\a \b \E \e \n \r \t \octal>
938
939=item or in control-character notation:
940
941B<^@, ^A .. ^Z .. ^_, ^?>
942
943=back
944
945To send a string starting with a B<NUL> (B<^@>) character to the
946program, start I<action> with a pair of B<NUL> characters (B<^@^@>),
947the first of which will be stripped off and the balance directed to the
948program. Otherwise if I<action> begins with B<NUL> followed by
949non-+B<NUL> characters, the leading B<NUL> is stripped off and the
950balance is sent back to rxvt.
951
952As a convenience for the many Emacs-type editors, I<action> may start
953with B<M-> (eg, B<M-$> is equivalent to B<\E$>) and a B<CR> will be
954appended if missed from B<M-x> commands.
955
956As a convenience for issuing XTerm B<ESC]> sequences from a menubar (or
957quick arrow), a B<BEL> (B<^G>) will be appended if needed.
958
959=over 4
960
961=item For example,
962
963B<M-xapropos> is equivalent to B<\Exapropos\r>
964
965=item and
966
967B<\E]703;mona;100> is equivalent to B<\E]703;mona;100\a>
968
969=back
970
971The option B<< {I<right-rtext>} >> will be right-justified. In the
972absence of a specified action, this text will be used as the I<action>
973as well.
974
975=over 4
976
977=item For example,
978
979B</File/{Open}{^X^F}> is equivalent to B</File/{Open}{^X^F} ^X^F>
980
981=back
982
983The left label I<is> necessary, since it's used for matching, but
984implicitly hiding the left label (by using same name for both left and
985right labels), or explicitly hiding the left label (by preceeding it
986with a dot), makes it possible to have right-justified text only.
987
988=over 4
989
990=item For example,
991
992B</File/{Open}{Open} Open-File-Action>
993
994=item or hiding it
995
996B</File/{.anylabel}{Open} Open-File-Action>
997
998=back
999
1000X<menuBarRemove>
1001
1002=head2 Removing menus
1003
1004=over 4
1005
1006=item B<< -/*+ >>
1007
1008remove all menus from the menuBar, the same as B<[clear]>
1009
1010=item B<< -+I</path>menu+ >>
1011
1012remove menu
1013
1014=item B<< -+I</path>{item}+ >>
1015
1016remove item
1017
1018=item B<< -+I</path>{-} >>
1019
1020remove separator)
1021
1022=item B<-/path/menu/*>
1023
1024remove all items, separators and submenus from menu
1025
1026=back
1027
1028X<menuBarArrows>
1029
1030=head2 Quick Arrows
1031
1032The menus also provide a hook for I<quick arrows> to provide easier
1033user access. If nothing has been explicitly set, the default is to
1034emulate the curror keys. The syntax permits each arrow to be altered
1035individually or all four at once without re-entering their common
1036beginning/end text. For example, to explicitly associate cursor actions
1037with the arrows, any of the following forms could be used:
1038
1039=over 4
1040
1041=item B<< <r>+I<Right> >>
1042
1043=item B<< <l>+I<Left> >>
1044
1045=item B<< <u>+I<Up> >>
1046
1047=item B<< <d>+I<Down> >>
1048
1049Define actions for the respective arrow buttons
1050
1051=item B<< <b>+I<Begin> >>
1052
1053=item B<< <e>+I<End> >>
1054
1055Define common beginning/end parts for I<quick arrows> which used in
1056conjunction with the above <r> <l> <u> <d> constructs
1057
1058=back
1059
1060=over 4
1061
1062=item For example, define arrows individually,
1063
1064 <u>\E[A
1065
1066 <d>\E[B
1067
1068 <r>\E[C
1069
1070 <l>\E[D
1071
1072=item or all at once
1073
1074 <u>\E[AZ<><d>\E[BZ<><r>\E[CZ<><l>\E[D
1075
1076=item or more compactly (factoring out common parts)
1077
1078 <b>\E[<u>AZ<><d>BZ<><r>CZ<><l>D
1079
1080=back
1081
1082X<menuBarSummary>
1083
1084=head2 Command Summary
1085
1086A short summary of the most I<common> commands:
1087
1088=over 4
1089
1090=item [menu:name]
1091
1092use an existing named menuBar or start a new one
1093
1094=item [menu]
1095
1096use the current menuBar
1097
1098=item [title:string]
1099
1100set menuBar title
1101
1102=item [done]
1103
1104set menu access to readonly and, if reading from a file, signal EOF
1105
1106=item [done:name]
1107
1108if reading from a file using [read:file;name] signal EOF
1109
1110=item [rm:name]
1111
1112remove named menuBar(s)
1113
1114=item [rm] [rm:]
1115
1116remove current menuBar
1117
1118=item [rm*] [rm:*]
1119
1120remove all menuBar(s)
1121
1122=item [swap]
1123
1124swap top two menuBars
1125
1126=item [prev]
1127
1128access the previous menuBar
1129
1130=item [next]
1131
1132access the next menuBar
1133
1134=item [show]
1135
1136map menuBar
1137
1138=item [hide]
1139
1140unmap menuBar
1141
1142=item [pixmap;file]
1143
1144=item [pixmap;file;scaling]
1145
1146set a background pixmap
1147
1148=item [read:file]
1149
1150=item [read:file;name]
1151
1152read in a menu from a file
1153
1154=item [dump]
1155
1156dump out all menuBars to /tmp/rxvt-PID
1157
1158=item /
1159
1160access menuBar top level
1161
1162=item ./
1163
1164=item ../
1165
1166=item ../../
1167
1168access current or parent menu level
1169
1170=item /path/menu
1171
1172add/access menu
1173
1174=item /path/{-}
1175
1176add separator
1177
1178=item /path/{item}{rtext} action
1179
1180add/alter menu item
1181
1182=item -/*
1183
1184remove all menus from the menuBar
1185
1186=item -/path/menu
1187
1188remove menu items, separators and submenus from menu
1189
1190=item -/path/menu
1191
1192remove menu
1193
1194=item -/path/{item}
1195
1196remove item
1197
1198=item -/path/{-}
1199
1200remove separator
1201
1202=item <b>Begin<r>Right<l>Left<u>Up<d>Down<e>End
1203
1204menu quick arrows
1205
1206=back
1207X<XPM>
1208 1853
1209=head1 XPM 1854=head1 XPM
1210 1855
1211For the XPM XTerm escape sequence B<< C<ESC ] 20 ; Pt ST> >> then value 1856For the XPM XTerm escape sequence B<< C<ESC ] 20 ; Pt ST> >> then value
1212of B<< C<Pt> >> can be the name of the background pixmap followed by a 1857of B<< C<Pt> >> can be the name of the background pixmap followed by a
… …
1310=begin table 1955=begin table
1311 1956
1312 4 Shift 1957 4 Shift
1313 8 Meta 1958 8 Meta
1314 16 Control 1959 16 Control
1315 32 Double Click I<(Rxvt extension)> 1960 32 Double Click I<(rxvt extension)>
1316 1961
1317=end table 1962=end table
1318 1963
1319Col = B<< C<< <x> - SPACE >> >> 1964Col = B<< C<< <x> - SPACE >> >>
1320 1965
1321Row = B<< C<< <y> - SPACE >> >> 1966Row = B<< C<< <y> - SPACE >> >>
1322 1967
1323=back 1968=back
1324X<KeyCodes> 1969X<KeyCodes>
1325
1326=head1 ISO 14755 support
1327
1328Partial ISO 14755-support is implemented. that means that pressing
1329
1330section 5.1: Control and Shift together enters unicode input
1331mode. Entering hex digits composes a Unicode character, pressing space or
1332releasing the modifiers commits the keycode and every other key cancels
1333the current input character.
1334
1335section 5.2: Pressing and immediately releasing Control and Shift together
1336enters keycap entry mode for the next key: pressing a function key (tab,
1337return etc..) will enter the unicode character corresponding to the given
1338key.
1339 1970
1340=head1 Key Codes 1971=head1 Key Codes
1341 1972
1342Note: B<Shift> + B<F1>-B<F10> generates B<F11>-B<F20> 1973Note: B<Shift> + B<F1>-B<F10> generates B<F11>-B<F20>
1343 1974
… …
1408 XK_KP_8 8 ESC O x 2039 XK_KP_8 8 ESC O x
1409 XK_KP_9 9 ESC O y 2040 XK_KP_9 9 ESC O y
1410 2041
1411=end table 2042=end table
1412 2043
2044=head1 CONFIGURE OPTIONS
2045
2046General hint: if you get compile errors, then likely your configuration
2047hasn't been tested well. Either try with C<--enable-everything> or use
2048the F<./reconf> script as a base for experiments. F<./reconf> is used by
2049myself, so it should generally be a working config. Of course, you should
2050always report when a combination doesn't work, so it can be fixed. Marc
2051Lehmann <rxvt@schmorp.de>.
2052
2053All
2054
2055=over 4
2056
2057=item --enable-everything
2058
2059Add (or remove) support for all non-multichoice options listed in "./configure
2060--help".
2061
2062You can specify this and then disable options you do not like by
2063I<following> this with the appropriate C<--disable-...> arguments,
2064or you can start with a minimal configuration by specifying
2065C<--disable-everything> and than adding just the C<--enable-...> arguments
2066you want.
2067
2068=item --enable-xft (default: enabled)
2069
2070Add support for Xft (anti-aliases, among others) fonts. Xft fonts are
2071slower and require lots of memory, but as long as you don't use them, you
2072don't pay for them.
2073
2074=item --enable-font-styles (default: on)
2075
2076Add support for B<bold>, I<italic> and B<< I<bold italic> >> font
2077styles. The fonts can be set manually or automatically.
2078
2079=item --with-codesets=NAME,... (default: all)
2080
2081Compile in support for additional codeset (encoding) groups (C<eu>, C<vn>
2082are always compiled in, which includes most 8-bit character sets). These
2083codeset tables are used for driving X11 core fonts, they are not required
2084for Xft fonts, although having them compiled in lets rxvt-unicode choose
2085replacement fonts more intelligently. Compiling them in will make your
2086binary bigger (all of together cost about 700kB), but it doesn't increase
2087memory usage unless you use a font requiring one of these encodings.
2088
2089=begin table
2090
2091 all all available codeset groups
2092 zh common chinese encodings
2093 zh_ext rarely used but very big chinese encodigs
2094 jp common japanese encodings
2095 jp_ext rarely used but big japanese encodings
2096 kr korean encodings
2097
2098=end table
2099
2100=item --enable-xim (default: on)
2101
2102Add support for XIM (X Input Method) protocol. This allows using
2103alternative input methods (e.g. kinput2) and will also correctly
2104set up the input for people using dead keys or compose keys.
2105
2106=item --enable-unicode3 (default: off)
2107
2108Recommended to stay off unless you really need non-BMP characters.
2109
2110Enable direct support for displaying unicode codepoints above
211165535 (the basic multilingual page). This increases storage
2112requirements per character from 2 to 4 bytes. X11 fonts do not yet
2113support these extra characters, but Xft does.
2114
2115Please note that rxvt-unicode can store unicode code points >65535
2116even without this flag, but the number of such characters is
2117limited to a view thousand (shared with combining characters,
2118see next switch), and right now rxvt-unicode cannot display them
2119(input/output and cut&paste still work, though).
2120
2121=item --enable-combining (default: on)
2122
2123Enable automatic composition of combining characters into
2124composite characters. This is required for proper viewing of text
2125where accents are encoded as seperate unicode characters. This is
2126done by using precomposited characters when available or creating
2127new pseudo-characters when no precomposed form exists.
2128
2129Without --enable-unicode3, the number of additional precomposed
2130characters is somewhat limited (the 6400 private use characters will be
2131(ab-)used). With --enable-unicode3, no practical limit exists.
2132
2133This option will also enable storage (but not display) of characters
2134beyond plane 0 (>65535) when --enable-unicode3 was not specified.
2135
2136The combining table also contains entries for arabic presentation forms,
2137but these are not currently used. Bug me if you want these to be used (and
2138tell me how these are to be used...).
2139
2140=item --enable-fallback(=CLASS) (default: Rxvt)
2141
2142When reading resource settings, also read settings for class CLASS. To
2143disable resource fallback use --disable-fallback.
2144
2145=item --with-res-name=NAME (default: urxvt)
2146
2147Use the given name as default application name when
2148reading resources. Specify --with-res-name=rxvt to replace rxvt.
2149
2150=item --with-res-class=CLASS /default: URxvt)
2151
2152Use the given class as default application class
2153when reading resources. Specify --with-res-class=Rxvt to replace
2154rxvt.
2155
2156=item --enable-utmp (default: on)
2157
2158Write user and tty to utmp file (used by programs like F<w>) at
2159start of rxvt execution and delete information when rxvt exits.
2160
2161=item --enable-wtmp (default: on)
2162
2163Write user and tty to wtmp file (used by programs like F<last>) at
2164start of rxvt execution and write logout when rxvt exits. This
2165option requires --enable-utmp to also be specified.
2166
2167=item --enable-lastlog (default: on)
2168
2169Write user and tty to lastlog file (used by programs like
2170F<lastlogin>) at start of rxvt execution. This option requires
2171--enable-utmp to also be specified.
2172
2173=item --enable-xpm-background (default: on)
2174
2175Add support for XPM background pixmaps.
2176
2177=item --enable-transparency (default: on)
2178
2179Add support for inheriting parent backgrounds thus giving a fake
2180transparency to the term.
2181
2182=item --enable-fading (default: on)
2183
2184Add support for fading the text when focus is lost (requires C<--enable-transparency>).
2185
2186=item --enable-tinting (default: on)
2187
2188Add support for tinting of transparent backgrounds (requires C<--enable-transparency>).
2189
2190=item --enable-rxvt-scroll (default: on)
2191
2192Add support for the original rxvt scrollbar.
2193
2194=item --enable-next-scroll (default: on)
2195
2196Add support for a NeXT-like scrollbar.
2197
2198=item --enable-xterm-scroll (default: on)
2199
2200Add support for an Xterm-like scrollbar.
2201
2202=item --enable-plain-scroll (default: on)
2203
2204Add support for a very unobtrusive, plain-looking scrollbar that
2205is the favourite of the rxvt-unicode author, having used it for
2206many years.
2207
2208=item --enable-ttygid (default: off)
2209
2210Change tty device setting to group "tty" - only use this if
2211your system uses this type of security.
2212
2213=item --disable-backspace-key
2214
2215Removes any handling of the backspace key by us - let the X server do it.
2216
2217=item --disable-delete-key
2218
2219Removes any handling of the delete key by us - let the X server
2220do it.
2221
2222=item --disable-resources
2223
2224Removes any support for resource checking.
2225
2226=item --disable-swapscreen
2227
2228Remove support for secondary/swap screen.
2229
2230=item --enable-frills (default: on)
2231
2232Add support for many small features that are not essential but nice to
2233have. Normally you want this, but for very small binaries you may want to
2234disable this.
2235
2236A non-exhaustive list of features enabled by C<--enable-frills> (possibly
2237in combination with other switches) is:
2238
2239 MWM-hints
2240 EWMH-hints (pid, utf8 names) and protocols (ping)
2241 seperate underline colour (-underlineColor)
2242 settable border widths and borderless switch (-w, -b, -bl)
2243 visual depth selection (-depth)
2244 settable extra linespacing /-lsp)
2245 iso-14755-2 and -3, and visual feedback
2246 tripleclickwords (-tcw)
2247 settable insecure mode (-insecure)
2248 keysym remapping support
2249 cursor blinking and underline cursor (-cb, -uc)
2250 XEmbed support (-embed)
2251 user-pty (-pty-fd)
2252 hold on exit (-hold)
2253 skip builtin block graphics (-sbg)
2254
2255It also enabled some non-essential features otherwise disabled, such as:
2256
2257 some round-trip time optimisations
2258 nearest color allocation on pseudocolor screens
2259 UTF8_STRING supporr for selection
2260 sgr modes 90..97 and 100..107
2261 backindex and forwardindex escape sequences
2262 view change/zero scorllback esacpe sequences
2263 locale switching escape sequence
2264 window op and some xterm/OSC escape sequences
2265 rectangular selections
2266 trailing space removal for selections
2267 verbose X error handling
2268
2269=item --enable-iso14755 (default: on)
2270
2271Enable extended ISO 14755 support (see @@RXVT_NAME@@(1), or
2272F<doc/rxvt.1.txt>). Basic support (section 5.1) is enabled by
2273C<--enable-frills>, while support for 5.2, 5.3 and 5.4 is enabled with
2274this switch.
2275
2276=item --enable-keepscrolling (default: on)
2277
2278Add support for continual scrolling of the display when you hold
2279the mouse button down on a scrollbar arrow.
2280
2281=item --enable-mousewheel (default: on)
2282
2283Add support for scrolling via mouse wheel or buttons 4 & 5.
2284
2285=item --enable-slipwheeling (default: on)
2286
2287Add support for continual scrolling (using the mouse wheel as an
2288accelerator) while the control key is held down. This option
2289requires --enable-mousewheel to also be specified.
2290
2291=item --disable-new-selection
2292
2293Remove support for mouse selection style like that of xterm.
2294
2295=item --enable-dmalloc (default: off)
2296
2297Use Gray Watson's malloc - which is good for debugging See
2298L<http://www.letters.com/dmalloc/> for details If you use either this or the
2299next option, you may need to edit src/Makefile after compiling to point
2300DINCLUDE and DLIB to the right places.
2301
2302You can only use either this option and the following (should
2303you use either) .
2304
2305=item --enable-dlmalloc (default: off)
2306
2307Use Doug Lea's malloc - which is good for a production version
2308See L<http://g.oswego.edu/dl/html/malloc.html> for details.
2309
2310=item --enable-smart-resize (default: on)
2311
2312Add smart growth/shrink behaviour when changing font size via hot
2313keys. This should keep the window corner which is closest to a corner of
2314the screen in a fixed position.
2315
2316=item --enable-pointer-blank (default: on)
2317
2318Add support to have the pointer disappear when typing or inactive.
2319
2320=item --enable-perl (default: on)
2321
2322Enable an embedded perl interpreter. See the B<@@RXVT_NAME@@perl(3)>
2323manpage (F<doc/rxvtperl.txt>) for more info on this feature, or the files
2324in F<src/perl-ext/> for the extensions that are installed by default. The
2325perl interpreter that is used can be specified via the C<PERL> environment
2326variable when running configure.
2327
2328=item --with-name=NAME (default: urxvt)
2329
2330Set the basename for the installed binaries, resulting
2331in C<urxvt>, C<urxvtd> etc.). Specify C<--with-name=rxvt> to replace with
2332C<rxvt>.
2333
2334=item --with-term=NAME (default: rxvt-unicode)
2335
2336Change the environmental variable for the terminal to NAME.
2337
2338=item --with-terminfo=PATH
2339
2340Change the environmental variable for the path to the terminfo tree to
2341PATH.
2342
2343=item --with-x
2344
2345Use the X Window System (pretty much default, eh?).
2346
2347=item --with-xpm-includes=DIR
2348
2349Look for the XPM includes in DIR.
2350
2351=item --with-xpm-library=DIR
2352
2353Look for the XPM library in DIR.
2354
2355=item --with-xpm
2356
2357Not needed - define via --enable-xpm-background.
2358
2359=back
2360
2361=head1 AUTHORS
2362
2363Marc Lehmann <rxvt@schmorp.de> converted this document to pod and
2364reworked it from the original Rxvt documentation, which was done by Geoff
2365Wing <gcw@pobox.com>, who in turn used the XTerm documentation and other
2366sources.
2367

Diff Legend

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