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

Comparing rxvt-unicode/doc/rxvt.1.pod (file contents):
Revision 1.30 by root, Wed Sep 8 17:10:23 2004 UTC vs.
Revision 1.76 by root, Sat Dec 31 16:06:48 2005 UTC

14configurability. As a result, B<rxvt-unicode> uses much less swap space -- 14configurability. As a result, B<rxvt-unicode> uses much less swap space --
15a significant advantage on a machine serving many X sessions. 15a significant advantage on a machine serving many X sessions.
16 16
17=head1 FREQUENTLY ASKED QUESTIONS 17=head1 FREQUENTLY ASKED QUESTIONS
18 18
19See @@RXVT_NAME@@(7) (try C<man 7 @@RXVT_NAME@@>) for a list of frequently 19See @@RXVT_NAME@@(7) (try C<man 7 @@RXVT_NAME@@>) for a list of
20asked questions and answer to them and some common problems. 20frequently asked questions and answer to them and some common
21problems. That document is also accessible on the World-Wide-Web at
22L<http://cvs.schmorp.de/browse/*checkout*/rxvt-unicode/doc/rxvt.7.html>.
21 23
22=head1 RXVT-UNICODE VS. RXVT 24=head1 RXVT-UNICODE VS. RXVT
23 25
24Unlike the original rxvt, B<rxvt-unicode> stores all text in Unicode 26Unlike the original rxvt, B<rxvt-unicode> stores all text in Unicode
25internally. That means it can store and display most scripts in the 27internally. That means it can store and display most scripts in the
103 105
104=item B<-j>|B<+j> 106=item B<-j>|B<+j>
105 107
106Turn on/off jump scrolling; resource B<jumpScroll>. 108Turn on/off jump scrolling; resource B<jumpScroll>.
107 109
108=item B<-ip>|B<+ip> 110=item B<-ip>|B<+ip> | B<-tr>|B<+tr>
109 111
110Turn on/off inheriting parent window's pixmap. Alternative form is 112Turn on/off inheriting parent window's pixmap. Alternative form is
111B<-tr>; resource B<inheritPixmap>. 113B<-tr>; resource B<inheritPixmap>.
112 114
113=item B<-fade> I<number> 115=item B<-fade> I<number>
114 116
115Fade the text by the given percentage when focus is lost. 117Fade the text by the given percentage when focus is lost. Small values
118fade a little only, 100 completely replaces all colours by the fade
119colour; resource B<fading>.
120
121=item B<-fadecolor> I<colour>
122
123Fade to this colour when fading is used (see B<-fade>). The default colour
124is black. resource B<fadeColor>.
116 125
117=item B<-tint> I<colour> 126=item B<-tint> I<colour>
118 127
119Tint the transparent background pixmap with the given colour when 128Tint the transparent background pixmap with the given colour when
120transparency is enabled with B<-tr> or B<-ip>. See also the B<-sh> 129transparency is enabled with B<-tr> or B<-ip>. This only works for
121option that can be used to brighten or darken the image in addition to 130non-tiled backgrounds, currently. See also the B<-sh> option that can be
122tinting it. 131used to brighten or darken the image in addition to tinting it; resource
132I<tintColor>. Example:
133
134 @@RXVT_NAME@@ -tr -tint blue -sh 40
123 135
124=item B<-sh> 136=item B<-sh>
125 137
126I<number> Darken (0 .. 100) or lighten (-1 .. -100) the transparent 138I<number> Darken (0 .. 100) or lighten (-1 .. -100) the transparent
127background image in addition to tinting it (i.e. B<-tint> must be 139background image in addition to tinting it (i.e. B<-tint> must be
128specified, too). 140specified, too, e.g. C<-tint white>).
129 141
130=item B<-bg> I<colour> 142=item B<-bg> I<colour>
131 143
132Window background colour; resource B<background>. 144Window background colour; resource B<background>.
133 145
136Window foreground colour; resource B<foreground>. 148Window foreground colour; resource B<foreground>.
137 149
138=item B<-pixmap> I<file[;geom]> 150=item B<-pixmap> I<file[;geom]>
139 151
140Compile I<XPM>: Specify XPM file for the background and also optionally 152Compile I<XPM>: Specify XPM file for the background and also optionally
141specify its scaling with a geometry string. Note you may need to add 153specify its scaling with a geometry string. Note you may need to
142quotes to avoid special shell interpretation of the `;' in the 154add quotes to avoid special shell interpretation of the C<;> in the
143command-line; resource B<backgroundPixmap>. 155command-line; resource B<backgroundPixmap>.
144 156
145=item B<-cr> I<colour> 157=item B<-cr> I<colour>
146 158
147The cursor colour; resource B<cursorColor>. 159The cursor colour; resource B<cursorColor>.
162=item B<-fn> I<fontlist> 174=item B<-fn> I<fontlist>
163 175
164Select the fonts to be used. This is a comma separated list of font names 176Select the fonts to be used. This is a comma separated list of font names
165that are used in turn when trying to display Unicode characters. The 177that are used in turn when trying to display Unicode characters. The
166first font defines the cell size for characters; other fonts might be 178first font defines the cell size for characters; other fonts might be
167smaller, but not (in general) larger. A reasonable default font list is 179smaller, but not (in general) larger. A (hopefully) reasonable default
168always appended to it. See resource B<font> for details. 180font list is always appended to it. See resource B<font> for more details.
181
182In short, to specify an X11 core font, just specify it's name or prefix it
183with C<x:>. To specify an XFT-font, you need to prefix it with C<xft:>,
184e.g.:
185
186 @@RXVT_NAME@@ -fn "xft:Bitstream Vera Sans Mono:pixelsize=15"
187 @@RXVT_NAME@@ -fn "9x15bold,xft:Bitstream Vera Sans Mono"
169 188
170See also the question "How does rxvt-unicode choose fonts?" in the FAQ 189See also the question "How does rxvt-unicode choose fonts?" in the FAQ
171section of @@RXVT_NAME@@(7). 190section of @@RXVT_NAME@@(7).
172 191
173=item B<-fb> I<fontlist> 192=item B<-fb> I<fontlist>
182 201
183=item B<-fbi> I<fontlist> 202=item B<-fbi> I<fontlist>
184 203
185Compile font-styles: The bold italic font list to use when bold characters are to 204Compile font-styles: The bold italic font list to use when bold characters are to
186be printed. See resource B<boldItalicFont> for details. 205be printed. See resource B<boldItalicFont> for details.
206
207=item B<-is>|B<+is>
208
209Compile font-styles: Bold/Italic font styles imply high intensity
210foreground/background (default). See resource B<intensityStyles> for
211details.
187 212
188=item B<-name> I<name> 213=item B<-name> I<name>
189 214
190Specify the application name under which resources are to be obtained, 215Specify the application name under which resources are to be obtained,
191rather than the default executable file name. Name should not contain 216rather than the default executable file name. Name should not contain
229 254
230Put scrollbar on right/left; resource B<scrollBar_right>. 255Put scrollbar on right/left; resource B<scrollBar_right>.
231 256
232=item B<-st>|B<+st> 257=item B<-st>|B<+st>
233 258
234Display normal (non XTerm/NeXT) scrollbar without/with a trough; 259Display rxvt (non XTerm/NeXT) scrollbar without/with a trough;
235resource B<scrollBar_floating>. 260resource B<scrollBar_floating>.
261
262=item B<-ptab>|B<+ptab>
263
264If enabled (default), "Horizontal Tab" characters are being stored as
265actual wide characters in the screen buffer, which makes it possible to
266select and paste them. Since a horizontal tab is a cursor movement and
267not an actual glyph, this can sometimes be visually annoying as the cursor
268on a tab character is displayed as a wide cursor; resource B<pastableTabs>.
236 269
237=item B<-bc>|B<+bc> 270=item B<-bc>|B<+bc>
238 271
239Blink the cursor; resource B<cursorBlink>. 272Blink the cursor; resource B<cursorBlink>.
240 273
265if honoured by the WM, the rxvt-unicode window will not have window 298if honoured by the WM, the rxvt-unicode window will not have window
266decorations; resource B<borderLess>. 299decorations; resource B<borderLess>.
267 300
268=item B<-lsp> I<number> 301=item B<-lsp> I<number>
269 302
270Compile I<linespace>: Lines (pixel height) to insert between each row 303Compile I<frills>: Lines (pixel height) to insert between each row of
271of the display; resource B<linespace>. 304the display. Useful to work around font rendering problems; resource
305B<linespace>.
272 306
273=item B<-tn> I<termname> 307=item B<-tn> I<termname>
274 308
275This option specifies the name of the terminal type to be set in the 309This option specifies the name of the terminal type to be set in the
276B<TERM> environment variable. This terminal type must exist in the 310B<TERM> environment variable. This terminal type must exist in the
285given on the command line. If this option is used, it must be the last 319given on the command line. If this option is used, it must be the last
286on the command-line. If there is no B<-e> option then the default is to 320on the command-line. If there is no B<-e> option then the default is to
287run the program specified by the B<SHELL> environment variable or, 321run the program specified by the B<SHELL> environment variable or,
288failing that, I<sh(1)>. 322failing that, I<sh(1)>.
289 323
324Please note that you must specify a program with arguments. If you want to
325run shell commands, you have to specify the shell, like this:
326
327 @@RXVT_NAME@@ -e sh -c "shell commands"
328
290=item B<-title> I<text> 329=item B<-title> I<text>
291 330
292Window title (B<-T> still respected); the default title is the basename 331Window title (B<-T> still respected); the default title is the basename
293of the program specified after the B<-e> option, if any, otherwise the 332of the program specified after the B<-e> option, if any, otherwise the
294application name; resource B<title>. 333application name; resource B<title>.
312 351
313Compile I<XIM>: input method name. resource B<inputMethod>. 352Compile I<XIM>: input method name. resource B<inputMethod>.
314 353
315=item B<-imlocale> I<string> 354=item B<-imlocale> I<string>
316 355
317The locale to use for opening the IM. You can use an LC_CTYPE of e.g. 356The locale to use for opening the IM. You can use an C<LC_CTYPE> of e.g.
318de_DE.UTF-8 for normal text processing but ja_JP.EUC-JP for the input 357C<de_DE.UTF-8> for normal text processing but C<ja_JP.EUC-JP> for the
319extension to be able to input japanese characters while staying in 358input extension to be able to input japanese characters while staying in
320another locale. 359another locale. resource B<imLocale>.
360
361=item B<-imfont> I<fontset>
362
363Set the font set to use for the X Input Method, see resource B<imFont>
364for more info.
365
366=item B<-tcw>
367
368Change the meaning of triple-click selection with the left mouse
369button. Instead of selecting a full line it will extend the selection the
370end of the logical line only. resource B<tripleclickwords>.
321 371
322=item B<-insecure> 372=item B<-insecure>
323 373
324Enable "insecure" mode, which currently enables most of the escape 374Enable "insecure" mode, which currently enables most of the escape
325sequences that echo strings. See the resource B<insecure> for more 375sequences that echo strings. See the resource B<insecure> for more
339=item B<-ssr>|B<+ssr> 389=item B<-ssr>|B<+ssr>
340 390
341Turn on/off secondary screen scroll (default enabled); resource 391Turn on/off secondary screen scroll (default enabled); resource
342B<secondaryScroll>. 392B<secondaryScroll>.
343 393
344=item B<-xrm> I<resourcestring> 394=item B<-hold>|B<+hold>
345 395
346No effect on rxvt-unicode. Simply passes through an argument to be made 396Turn on/off hold window after exit support. If enabled, @@RXVT_NAME@@
347available in the instance's argument list. Appears in I<WM_COMMAND> in 397will not immediately destroy its window when the program executed within
348some window managers. 398it exits. Instead, it will wait till it is being killed or closed by the
399user; resource B<hold>.
400
401=item B<-keysym.>I<sym> I<string>
402
403Remap a key symbol. See resource B<keysym>.
404
405=item B<-embed> I<windowid>
406
407Tells @@RXVT_NAME@@ to embed it's windows into an already-existing window,
408which enables applications to easily embed a terminal.
409
410Right now, @@RXVT_NAME@@ will first unmap/map the specified window, so it
411shouldn't be a top-level window. @@RXVT_NAME@@ will also reconfigure it
412quite a bit, so don't expect it to keep some specific state. It's best to
413create an extra subwindow for @@RXVT_NAME@@ and leave it alone.
414
415The window will not be destroyed when @@RXVT_NAME@@ exits.
416
417It might be useful to know that @@RXVT_NAME@@ will not close file
418descriptors passed to it (except for stdin/out/err, of course), so you
419can use file descriptors to communicate with the programs within the
420terminal. This works regardless of wether the C<-embed> option was used or
421not.
422
423Here is a short Gtk2-perl snippet that illustrates how this option can be
424used (a longer example is in F<doc/embed>):
425
426 my $rxvt = new Gtk2::Socket;
427 $rxvt->signal_connect_after (realize => sub {
428 my $xid = $_[0]->window->get_xid;
429 system "@@RXVT_NAME@@ -embed $xid &";
430 });
431
432=item B<-pty-fd> I<fileno>
433
434Tells @@RXVT_NAME@@ NOT to execute any commands or create a new pty/tty
435pair but instead use the given filehandle as the tty master. This is
436useful if you want to drive @@RXVT_NAME@@ as a generic terminal emulator
437without having to run a program within it.
438
439If this switch is given, @@RXVT_NAME@@ will not create any utmp/wtmp
440entries and will not tinker with pty/tty permissions - you have to do that
441yourself if you want that.
442
443Here is a example in perl that illustrates how this option can be used (a
444longer example is in F<doc/pty-fd>):
445
446 use IO::Pty;
447 use Fcntl;
448
449 my $pty = new IO::Pty;
450 fcntl $pty, F_SETFD, 0; # clear close-on-exec
451 system "@@RXVT_NAME@@ -pty-fd " . (fileno $pty) . "&";
452 close $pty;
453
454 # now communicate with rxvt
455 my $slave = $pty->slave;
456 while (<$slave>) { print $slave "got <$_>\n" }
349 457
350=back 458=back
351 459
352=head1 RESOURCES (available also as long-options) 460=head1 RESOURCES (available also as long-options)
353 461
356 464
357There are two different methods that @@RXVT_NAME@@ can use to get the 465There are two different methods that @@RXVT_NAME@@ can use to get the
358Xresource data: using the X libraries (Xrm*-functions) or internal 466Xresource data: using the X libraries (Xrm*-functions) or internal
359Xresources reader (B<~/.Xdefaults>). For the first method (ie. 467Xresources reader (B<~/.Xdefaults>). For the first method (ie.
360B<@@RXVT_NAME@@ -h> lists B<XGetDefaults>), you can set and change the 468B<@@RXVT_NAME@@ -h> lists B<XGetDefaults>), you can set and change the
361resources using X11 tools like B<xset>. Many distribution do also load 469resources using X11 tools like B<xrdb>. Many distribution do also load
362settings from the B<~/.Xresources> file when X starts. 470settings from the B<~/.Xresources> file when X starts. @@RXVT_NAME@@
471will consult the following files/resources in order, with later settings
472overwriting earlier ones:
473
474 1. system-wide app-defaults file, either locale-dependent OR global
475 2. app-defaults file in $XAPPLRESDIR
476 3. RESOURCE_MANAGER property on root-window OR $HOME/.Xdefaults
477 4. SCREEN_RESOURCES for the current screen
478 5. $XENVIRONMENT file OR $HOME/.Xdefaults-<nodename>
363 479
364If compiled with internal Xresources support (i.e. B<@@RXVT_NAME@@ -h> 480If compiled with internal Xresources support (i.e. B<@@RXVT_NAME@@ -h>
365lists B<.Xdefaults>) then B<@@RXVT_NAME@@> accepts application defaults 481lists B<.Xdefaults>) then B<@@RXVT_NAME@@> accepts application defaults
366set in XAPPLOADDIR/URxvt (compile-time defined: usually 482set in XAPPLOADDIR/URxvt (compile-time defined: usually
367B</usr/lib/X11/app-defaults/URxvt>) and resources set in 483B</usr/lib/X11/app-defaults/URxvt>) and resources set in
412 528
413=item B<colorIT:> I<colour> 529=item B<colorIT:> I<colour>
414 530
415Use the specified colour to display bold or italic characters when the 531Use the specified colour to display bold or italic characters when the
416foreground colour is the default. If font styles are not available 532foreground colour is the default. If font styles are not available
417(Compile styles) and this option is unset, reverse video is used instead. 533(Compile I<styles>) and this option is unset, reverse video is used instead.
418 534
419=item B<colorUL:> I<colour> 535=item B<colorUL:> I<colour>
420 536
421Use the specified colour to display underlined characters when the 537Use the specified colour to display underlined characters when the
422foreground colour is the default. 538foreground colour is the default.
423 539
424=item B<colorRV:> I<colour> 540=item B<colorRV:> I<colour>
425 541
426Use the specified colour as the background for reverse video 542Use the specified colour as the background for reverse video
427characters. 543characters.
544
545=item B<underlineColor:> I<colour>
546
547If set, use the specified colour as the colour for the underline
548itself. If unset, use the foreground colour.
428 549
429=item B<cursorColor:> I<colour> 550=item B<cursorColor:> I<colour>
430 551
431Use the specified colour for the cursor. The default is to use the 552Use the specified colour for the cursor. The default is to use the
432foreground colour; option B<-cr>. 553foreground colour; option B<-cr>.
455artificial transparency. B<False>: do not inherit the parent windows' 576artificial transparency. B<False>: do not inherit the parent windows'
456pixmap. 577pixmap.
457 578
458=item B<fading:> I<number> 579=item B<fading:> I<number>
459 580
460Fade the text by the given percentage when focus is lost. 581Fade the text by the given percentage when focus is lost; option B<-fade>.
582
583=item B<fadeColor:> I<colour>
584
585Fade to this colour, when fading is used (see B<fading:>). The default
586colour is black; option B<-fadecolor>.
461 587
462=item B<tintColor:> I<colour> 588=item B<tintColor:> I<colour>
463 589
464Tint the transparent background pixmap with the given colour. 590Tint the transparent background pixmap with the given colour; option
591B<-tint>.
465 592
466=item B<shading:> I<number> 593=item B<shading:> I<number>
467 594
468Darken (0 .. 100) or lighten (-1 .. -100) the transparent background 595Darken (0 .. 100) or lighten (-1 .. -100) the transparent background
469image in addition to tinting it. 596image in addition to tinting it.
470 597
471=item B<fading:> I<number>
472
473Scale the tint colour by the given percentage.
474
475=item B<scrollColor:> I<colour> 598=item B<scrollColor:> I<colour>
476 599
477Use the specified colour for the scrollbar [default #B2B2B2]. 600Use the specified colour for the scrollbar [default #B2B2B2].
478 601
479=item B<troughColor:> I<colour> 602=item B<troughColor:> I<colour>
480 603
481Use the specified colour for the scrollbar's trough area [default 604Use the specified colour for the scrollbar's trough area [default
482#969696]. Only relevant for normal (non XTerm/NeXT) scrollbar. 605#969696]. Only relevant for rxvt (non XTerm/NeXT) scrollbar.
483 606
484=item B<borderColor:> I<colour> 607=item B<borderColor:> I<colour>
485 608
486The colour of the border around the text area and between the scrollbar 609The colour of the border around the text area and between the scrollbar
487and the text. 610and the text.
517The first font defines the cell size for characters; other fonts might 640The first font defines the cell size for characters; other fonts might
518be smaller, but not larger. A reasonable default font list is always 641be smaller, but not larger. A reasonable default font list is always
519appended to it. option B<-fn>. 642appended to it. option B<-fn>.
520 643
521Each font can either be a standard X11 core font (XLFD) name, with 644Each font can either be a standard X11 core font (XLFD) name, with
522optional prefix C<x:> or a Xft font (Compile xft), prefixed with C<xft:>. 645optional prefix C<x:> or a Xft font (Compile I<xft>), prefixed with C<xft:>.
523 646
524In addition, each font can be prefixed with additional hints and 647In addition, each font can be prefixed with additional hints and
525specifications enclosed in square brackets (C<[]>). The only available 648specifications enclosed in square brackets (C<[]>). The only available
526hint currently is C<codeset=codeset-name>, and this is only used for Xft 649hint currently is C<codeset=codeset-name>, and this is only used for Xft
527fonts. 650fonts.
537specifies five fonts to be used. The first one is C<9x15bold> (actually 660specifies five fonts to be used. The first one is C<9x15bold> (actually
538the iso8859-1 version of the second font), which is the base font (because 661the iso8859-1 version of the second font), which is the base font (because
539it is named first) and thus defines the character cell grid to be 9 pixels 662it is named first) and thus defines the character cell grid to be 9 pixels
540wide and 15 pixels high. 663wide and 15 pixels high.
541 664
542the second font is just used to add additional unicode characters not in 665The second font is just used to add additional unicode characters not in
543the base font, likewise the third, which is unfortunately non-bold, but 666the base font, likewise the third, which is unfortunately non-bold, but
544the bold version of the font does contain less characters, so this is a 667the bold version of the font does contain less characters, so this is a
545useful supplement. 668useful supplement.
546 669
547The third font is an Xft font with aliasing turned off, and the characters 670The third font is an Xft font with aliasing turned off, and the characters
570not possible, replacement fonts of the desired shape will be tried. 693not possible, replacement fonts of the desired shape will be tried.
571 694
572If set, but empty, then this specific style is disabled and the normal 695If set, but empty, then this specific style is disabled and the normal
573text font will being used for the given style. 696text font will being used for the given style.
574 697
698=item B<intensityStyles:> I<boolean>
699
700When font styles are not enabled, or this option is enabled (B<True>,
701option B<-is>, the default), bold and italic font styles imply high
702intensity foreground/backround colours. Disabling this option (B<False>,
703option B<+is>) disables this behaviour, the high intensity colours are not
704reachable.
705
575=item B<selectstyle:> I<mode> 706=item B<selectstyle:> I<mode>
576 707
577Set mouse selection style to B<old> which is 2.20, B<oldword> which is 708Set mouse selection style to B<old> which is 2.20, B<oldword> which is
578xterm style with 2.20 old word selection, or anything else which gives 709xterm style with 2.20 old word selection, or anything else which gives
579xterm style selection. 710xterm style selection.
580 711
581=item B<scrollstyle:> I<mode> 712=item B<scrollstyle:> I<mode>
582 713
583Set scrollbar style to B<rxvt>, B<plain>, B<next> or B<xterm>. B<plain> is 714Set scrollbar style to B<rxvt>, B<plain>, B<next> or B<xterm>. B<plain> is
584the author's favourite.. 715the author's favourite.
585 716
586=item B<title:> I<string> 717=item B<title:> I<string>
587 718
588Set window title string, the default title is the command-line 719Set window title string, the default title is the command-line
589specified after the B<-e> option, if any, otherwise the application 720specified after the B<-e> option, if any, otherwise the application
621 752
622Specify a command pipe for vt100 printer [default I<lpr(1)>]. Use 753Specify a command pipe for vt100 printer [default I<lpr(1)>]. Use
623B<Print> to initiate a screen dump to the printer and B<Ctrl-Print> or 754B<Print> to initiate a screen dump to the printer and B<Ctrl-Print> or
624B<Shift-Print> to include the scrollback as well. 755B<Shift-Print> to include the scrollback as well.
625 756
757The string will be interpreted as if typed into the shell as-is.
758
759Example:
760
761 URxvt*print-pipe: cat > $(TMPDIR=$HOME mktemp urxvt.XXXXXX)
762
763This creates a new file in your home directory with the screen contents
764everytime you hit C<Print>.
765
626=item B<scrollBar:> I<boolean> 766=item B<scrollBar:> I<boolean>
627 767
628B<True>: enable the scrollbar [default]; option B<-sb>. B<False>: 768B<True>: enable the scrollbar [default]; option B<-sb>. B<False>:
629disable the scrollbar; option B<+sb>. 769disable the scrollbar; option B<+sb>.
630 770
650B<+si>. 790B<+si>.
651 791
652=item B<scrollWithBuffer:> I<boolean> 792=item B<scrollWithBuffer:> I<boolean>
653 793
654B<True>: scroll with scrollback buffer when tty receives new lines (and 794B<True>: scroll with scrollback buffer when tty receives new lines (and
655B<scrollTtyOutput> is False); option B<+sw>. B<False>: do not scroll 795B<scrollTtyOutput> is False); option B<-sw>. B<False>: do not scroll
656with scrollback buffer when tty recieves new lines; option B<-sw>. 796with scrollback buffer when tty recieves new lines; option B<+sw>.
657 797
658=item B<scrollTtyKeypress:> I<boolean> 798=item B<scrollTtyKeypress:> I<boolean>
659 799
660B<True>: scroll to bottom when a non-special key is pressed. Special keys 800B<True>: scroll to bottom when a non-special key is pressed. Special keys
661are those which are intercepted by rxvt-unicode for special handling and 801are those which are intercepted by rxvt-unicode for special handling and
700=item B<mouseWheelScrollPage:> I<boolean> 840=item B<mouseWheelScrollPage:> I<boolean>
701 841
702B<True>: the mouse wheel scrolls a page full. B<False>: the mouse wheel 842B<True>: the mouse wheel scrolls a page full. B<False>: the mouse wheel
703scrolls five lines [default]. 843scrolls five lines [default].
704 844
845=item B<pastableTabs:> I<boolean>
846
847B<True>: store tabs as wide characters. B<False>: interpret tabs as cursor
848movement only; option C<-ptab>.
849
705=item B<cursorBlink:> I<boolean> 850=item B<cursorBlink:> I<boolean>
706 851
707B<True>: blink the cursor. B<False>: do not blink the cursor [default]; 852B<True>: blink the cursor. B<False>: do not blink the cursor [default];
708option B<-bc>. 853option B<-bc>.
709 854
721 866
722Mouse pointer background colour. 867Mouse pointer background colour.
723 868
724=item B<pointerBlankDelay:> I<number> 869=item B<pointerBlankDelay:> I<number>
725 870
726Specifies number of seconds before blanking the pointer [default 2]. 871Specifies number of seconds before blanking the pointer [default 2]. Use a
872large number (e.g. C<987654321>) to effectively disable the timeout.
727 873
728=item B<backspacekey:> I<string> 874=item B<backspacekey:> I<string>
729 875
730The string to send when the backspace key is pressed. If set to B<DEC> 876The string to send when the backspace key is pressed. If set to B<DEC>
731or unset it will send B<Delete> (code 127) or, if shifted, B<Backspace> 877or unset it will send B<Delete> (code 127) or, if shifted, B<Backspace>
753 899
754I<name> of inputMethod to use; option B<-im>. 900I<name> of inputMethod to use; option B<-im>.
755 901
756=item B<imLocale:> I<name> 902=item B<imLocale:> I<name>
757 903
758The locale to use for opening the IM. You can use an LC_CTYPE of e.g. 904The locale to use for opening the IM. You can use an C<LC_CTYPE> of e.g.
759de_DE.UTF-8 for normal text processing but ja_JP.EUC-JP for the input 905C<de_DE.UTF-8> for normal text processing but C<ja_JP.EUC-JP> for the
760extension to be able to input japanese characters while staying in 906input extension to be able to input japanese characters while staying in
761another locale. option B<-imlocale>. 907another locale. option B<-imlocale>.
908
909=item B<imFont:> I<fontset>
910
911Specify the font-set used for XIM styles C<OverTheSpot> or
912C<OffTheSpot>. It must be a standard X font set (XLFD patterns separated
913by commas), i.e. it's not in the same format as the other font lists used
914in @@RXVT_NAME@@. The default will be set-up to chose *any* suitable found
915found, preferably one or two pixels differing in size to the base font.
916option B<-imfont>.
917
918=item B<tripleclickwords:> I<boolean>
919
920Change the meaning of triple-click selection with the left mouse
921button. Instead of selecting a full line it will extend the selection to
922the end of the logical line only. option B<-tcw>.
762 923
763=item B<insecure:> I<boolean> 924=item B<insecure:> I<boolean>
764 925
765Enables "insecure" mode. Rxvt-unicode offers some escape sequences that 926Enables "insecure" mode. Rxvt-unicode offers some escape sequences that
766echo arbitrary strings like the icon name or the locale. This could be 927echo arbitrary strings like the icon name or the locale. This could be
767abused if somebody gets 8-bit-clean access to your display, whether 928abused if somebody gets 8-bit-clean access to your display, whether
768throuh a mail client displaying mail bodies unfiltered or though 929through a mail client displaying mail bodies unfiltered or through
769write(1). Therefore, these sequences are disabled by default. (Note 930write(1) or any other means. Therefore, these sequences are disabled by
770that other terminals, including xterm, have these sequences 931default. (Note that many other terminals, including xterm, have these
771enabled by default). You can enable them by setting this boolean 932sequences enabled by default, which doesn't make it safer, though).
772resource or specifying B<-insecure> as an option. At the moment, this 933
773enabled display-answer, locale, findfont, icon label and window title 934You can enable them by setting this boolean resource or specifying
774requests as well as dynamic menubar dispatch. 935B<-insecure> as an option. At the moment, this enables display-answer,
936locale, findfont, icon label and window title requests as well as dynamic
937menubar dispatch.
775 938
776=item B<modifier:> I<modifier> 939=item B<modifier:> I<modifier>
777 940
778Set the key to be interpreted as the Meta key to: B<alt>, B<meta>, 941Set the key to be interpreted as the Meta key to: B<alt>, B<meta>,
779B<hyper>, B<super>, B<mod1>, B<mod2>, B<mod3>, B<mod4>, B<mod5>; option 942B<hyper>, B<super>, B<mod1>, B<mod2>, B<mod3>, B<mod4>, B<mod5>; option
794Turn on/off secondary screen scroll (default enabled). If the this 957Turn on/off secondary screen scroll (default enabled). If the this
795option is enabled, scrolls on the secondary screen will change the 958option is enabled, scrolls on the secondary screen will change the
796scrollback buffer and switching to/from the secondary screen will 959scrollback buffer and switching to/from the secondary screen will
797instead scroll the screen up. 960instead scroll the screen up.
798 961
962=item B<hold>: I<bool>
963
964Turn on/off hold window after exit support. If enabled, @@RXVT_NAME@@
965will not immediately destroy its window when the program executed within
966it exits. Instead, it will wait till it is being killed or closed by the
967user.
968
799=item B<keysym.>I<sym>: I<string> 969=item B<keysym.>I<sym>: I<string>
800 970
801Associate I<string> with keysym I<sym> (B<0xFF00 - 0xFFFF>). It may 971Compile I<frills>: Associate I<string> with keysym I<sym>. The
802contain escape values (\a: bell, \b: backspace, \e, \E: escape, \n: 972intervening resource name B<keysym.> cannot be omitted.
803newline, \r: return, \t: 973
974The format of I<sym> is "I<(modifiers-)key>", where I<modifiers> can be
975any combination of B<ISOLevel3>, B<AppKeypad>, B<Control>, B<NumLock>,
976B<Shift>, B<Meta>, B<Lock>, B<Mod1>, B<Mod2>, B<Mod3>, B<Mod4>, B<Mod5>,
977and the abbreviated B<I>, B<K>, B<C>, B<N>, B<S>, B<M>, B<A>, B<L>, B<1>,
978B<2>, B<3>, B<4>, B<5>.
979
980The B<NumLock>, B<Meta> and B<ISOLevel3> modifiers are usually aliased to
981whatever modifier the NumLock key, Meta/Alt keys or ISO Level3 Shift/AltGr
982keys are being mapped. B<AppKeypad> is a synthetic modifier mapped to the
983current application keymap mode state.
984
985The spellings of I<key> can be obtained by using B<xev>(1) command or
986searching keysym macros from B</usr/X11R6/include/X11/keysymdef.h> and
987omitting the prefix B<XK_>. Alternatively you can specify I<key> by its hex
988keysym value (B<0x0000 - 0xFFFF>). Note that the lookup of I<sym>s is not
989performed in an exact manner; however, the closest match is assured.
990
991I<string> may contain escape values (C<\a>: bell, C<\b>: backspace,
992C<\e>, C<\E>: escape, C<\n>: newline, C<\r>: carriage return, C<\t>: tab,
804tab, \000: octal number) or control characters (^?: delete, ^@: null, 993C<\000>: octal number) or verbatim control characters (C<^?>: delete,
805^A ...) and may enclosed with double quotes so that it can start or end 994C<^@>: null, C<^A> ...) and may be enclosed with double quotes so that it
806with whitespace. The intervening resource name B<keysym.> cannot be 995can start or end with whitespace.
807omitted. This resource is only available when compiled with 996
808KEYSYM_RESOURCE. 997Please note that you need to double the C<\> when using
998C<--enable-xgetdefault>, as X itself does it's own de-escaping (you can
999use C<\033> instead of C<\e> (and so on), which will work with both Xt and
1000@@RXVT_NAME@@'s own processing).
1001
1002You can define a range of keysyms in one shot by providing a I<string>
1003with pattern B<list/PREFIX/MIDDLE/SUFFIX>, where the delimeter `/'
1004should be a character not used by the strings.
1005
1006Its usage can be demonstrated by an example:
1007
1008 URxvt.keysym.M-C-0x61: list|\033<M-C-|abc|>
1009
1010The above line is equivalent to the following three lines:
1011
1012 URxvt.keysym.Meta-Control-0x61: \033<M-C-a>
1013 URxvt.keysym.Meta-Control-0x62: \033<M-C-b>
1014 URxvt.keysym.Meta-Control-0x63: \033<M-C-c>
1015
1016If I<string> takes the form of C<command:STRING>, the specified B<STRING>
1017is interpreted and executed as @@RXVT_NAME@@'s control sequence. For
1018example the following means "change the current locale to C<zh_CN.GBK>
1019when Control-Meta-c is being pressed":
1020
1021 URxvt.keysym.M-C-c: command:\033]701;zh_CN.GBK\007
1022
1023Due the the large number of modifier combinations, a defined key mapping
1024will match if at I<at least> the specified identifiers are being set, and
1025no other key mappings with those and more bits are being defined. That
1026means that defining a key map for C<a> will automatically provide
1027definitions for C<Meta-a>, C<Shift-a> and so on, unless some of those are defined
1028mappings themselves.
1029
1030Unfortunately, this will override built-in key mappings. For example
1031if you overwrite the C<Insert> key you will disable @@RXVT_NAME@@'s
1032C<Shift-Insert> mapping. To re-enable that, you can poke "holes" into the
1033user-defined keymap using the C<builtin:> replacement:
1034
1035 URxvt.keysym.Insert: <my insert key sequence>
1036 URxvt.keysym.S-Insert: builtin:
1037
1038The first line defines a mapping for C<Insert> and I<any> combination
1039of modifiers. The second line re-establishes the default mapping for
1040C<Shift-Insert>.
1041
1042The following example will map Control-Meta-1 and Control-Meta-2 to
1043the fonts C<suxuseuro> and C<9x15bold>, so you can have some limited
1044font-switching at runtime:
1045
1046 URxvt.keysym.M-C-1: command:\033]50;suxuseuro\007
1047 URxvt.keysym.M-C-2: command:\033]50;9x15bold\007
1048
1049Other things are possible, e.g. resizing (see @@RXVT_NAME@@(7) for more
1050info):
1051
1052 URxvt.keysym.M-C-3: command:\033[8;25;80t
1053 URxvt.keysym.M-C-4: command:\033[8;48;110t
809 1054
810=back 1055=back
811 1056
812=head1 THE SCROLLBAR 1057=head1 THE SCROLLBAR
813 1058
827the normal text selection/insertion, hold either the Shift or the Meta 1072the normal text selection/insertion, hold either the Shift or the Meta
828(Alt) key while performing the desired mouse action. 1073(Alt) key while performing the desired mouse action.
829 1074
830If mouse reporting mode is active, the normal scrollbar actions are 1075If mouse reporting mode is active, the normal scrollbar actions are
831disabled -- on the assumption that we are using a fullscreen 1076disabled -- on the assumption that we are using a fullscreen
832application. Instead, pressing Button1 and Button3 sends B<ESC[6~> 1077application. Instead, pressing Button1 and Button3 sends B<ESC [ 6 ~>
833(Next) and B<ESC[5~> (Prior), respectively. Similarly, clicking on the 1078(Next) and B<ESC [ 5 ~> (Prior), respectively. Similarly, clicking on the
834up and down arrows sends B<ESC[A> (Up) and B<ESC[B> (Down), 1079up and down arrows sends B<ESC [ A> (Up) and B<ESC [ B> (Down),
835respectively. 1080respectively.
836 1081
837=head1 TEXT SELECTION AND INSERTION 1082=head1 TEXT SELECTION AND INSERTION
838 1083
839The behaviour of text selection and insertion mechanism is similar to 1084The behaviour of text selection and insertion mechanism is similar to
841 1086
842=over 4 1087=over 4
843 1088
844=item B<Selection>: 1089=item B<Selection>:
845 1090
846Left click at the beginning of the region, drag to the end of the 1091Left click at the beginning of the region, drag to the end of the region
847region and release; Right click to extend the marked region; Left 1092and release; Right click to extend the marked region; Left double-click
848double-click to select a word; Left triple-click to select the entire 1093to select a word; Left triple-click to select the entire logical line
849line. 1094(which can span multiple screen lines), unless modified by resource
1095B<tripleclickwords>.
850 1096
851Starting a selection while pressing the B<Meta> key (or B<Meta+Ctrl> keys) 1097Starting a selection while pressing the B<Meta> key (or B<Meta+Ctrl> keys)
852(Compile: frills) will create a rectangular selection instead of a normal 1098(Compile: I<frills>) will create a rectangular selection instead of a
853one. 1099normal one. In this mode, every selected row becomes its own line in the
1100selection, and trailing whitespace is visually underlined and removed from
1101the selection.
854 1102
855=item B<Insertion>: 1103=item B<Insertion>:
856 1104
857Pressing and releasing the Middle mouse button (or B<Shift-Insert>) in 1105Pressing and releasing the Middle mouse button (or B<Shift-Insert>) in
858an B<@@RXVT_NAME@@> window causes the current text selection to be 1106an B<@@RXVT_NAME@@> window causes the current text selection to be
866supported in rxvt-unicode. Bug me if you need this. 1114supported in rxvt-unicode. Bug me if you need this.
867 1115
868You can, however, switch fonts at runtime using escape sequences (and 1116You can, however, switch fonts at runtime using escape sequences (and
869therefore using the menubar), e.g.: 1117therefore using the menubar), e.g.:
870 1118
871 printf '\e]701;%s\007' "9x15bold,xft:Kochi Gothic" 1119 printf '\e]710;%s\007' "9x15bold,xft:Kochi Gothic"
872 1120
873rxvt-unicode will automatically re-apply these fonts to the output so far. 1121rxvt-unicode will automatically re-apply these fonts to the output so far.
874 1122
875=head1 ISO 14755 SUPPORT 1123=head1 ISO 14755 SUPPORT
876 1124
880C<--enable-frills>, the rest is available when rxvt-unicode was compiled 1128C<--enable-frills>, the rest is available when rxvt-unicode was compiled
881with C<--enable-iso14755>. 1129with C<--enable-iso14755>.
882 1130
883=over 4 1131=over 4
884 1132
885=item 5.1: Basic method 1133=item * 5.1: Basic method
886 1134
887This allows you to enter unicode characters using their hexcode. 1135This allows you to enter unicode characters using their hexcode.
888 1136
889Start by pressing and holding both C<Control> and C<Shift>, then enter 1137Start by pressing and holding both C<Control> and C<Shift>, then enter
890hex-digits (between one and six). Releasing C<Control> and C<Shift> will 1138hex-digits (between one and six). Releasing C<Control> and C<Shift> will
897address, which you cannot type. Fortunately, the card has the e-mail 1145address, which you cannot type. Fortunately, the card has the e-mail
898address printed as hexcodes, e.g. C<671d 65e5>. You can enter this easily 1146address printed as hexcodes, e.g. C<671d 65e5>. You can enter this easily
899by pressing C<Control> and C<Shift>, followed by C<6-7-1-D-SPACE-6-5-E-5>, 1147by pressing C<Control> and C<Shift>, followed by C<6-7-1-D-SPACE-6-5-E-5>,
900followed by releasing the modifier keys. 1148followed by releasing the modifier keys.
901 1149
902=item 5.2: Keyboard symbols entry method 1150=item * 5.2: Keyboard symbols entry method
903 1151
904This mode lets you input characters representing the keycap symbols of 1152This mode lets you input characters representing the keycap symbols of
905your keyboard, if representable in the current locale encoding. 1153your keyboard, if representable in the current locale encoding.
906 1154
907Start by pressing C<Control> and C<Shift> together, then releasing 1155Start by pressing C<Control> and C<Shift> together, then releasing
910keycap symbol. The symbol will only be entered when the key has been 1158keycap symbol. The symbol will only be entered when the key has been
911released, otherwise pressing e.g. C<Shift> would enter the symbol for 1159released, otherwise pressing e.g. C<Shift> would enter the symbol for
912C<ISO Level 2 Switch>, although your intention might have been to enter a 1160C<ISO Level 2 Switch>, although your intention might have been to enter a
913reverse tab (Shift-Tab). 1161reverse tab (Shift-Tab).
914 1162
915=item 5.3: Screen-selection entry method 1163=item * 5.3: Screen-selection entry method
916 1164
917While this is implemented already (it's basically the selection 1165While this is implemented already (it's basically the selection
918mechanism), it could be extended by displaying a unicode character map. 1166mechanism), it could be extended by displaying a unicode character map.
919 1167
920=item 5.4: Feedback method for identifying displayed characters for later input 1168=item * 5.4: Feedback method for identifying displayed characters for later input
921 1169
922This method lets you display the unicode character code associated with 1170This method lets you display the unicode character code associated with
923characters already displayed. 1171characters already displayed.
924 1172
925You enter this mode by holding down C<Control> and C<Shift> together, then 1173You enter this mode by holding down C<Control> and C<Shift> together, then
937With respect to conformance, rxvt-unicode is supposed to be compliant to 1185With respect to conformance, rxvt-unicode is supposed to be compliant to
938both scenario A and B of ISO 14755, including part 5.2. 1186both scenario A and B of ISO 14755, including part 5.2.
939 1187
940=head1 LOGIN STAMP 1188=head1 LOGIN STAMP
941 1189
942B<@@RXVT_NAME@@> tries to write an entry into the I<utmp>(5) file so 1190B<@@RXVT_NAME@@> tries to write an entry into the I<utmp>(5) file so that
943that it can be seen via the I<who(1)> command, and can accept messages. 1191it can be seen via the I<who(1)> command, and can accept messages. To
944To allow this feature, B<@@RXVT_NAME@@> must be installed setuid root on 1192allow this feature, B<@@RXVT_NAME@@> may need to be installed setuid root
945some systems. 1193on some systems or setgid to root or to some other group on others.
946 1194
947=head1 COLORS AND GRAPHICS 1195=head1 COLORS AND GRAPHICS
948 1196
949In addition to the default foreground and background colours, 1197In addition to the default foreground and background colours,
950B<@@RXVT_NAME@@> can display up to 16 colours (8 ANSI colours plus 1198B<@@RXVT_NAME@@> can display up to 16 colours (8 ANSI colours plus
993 1241
994=back 1242=back
995 1243
996=head1 ENVIRONMENT 1244=head1 ENVIRONMENT
997 1245
998B<@@RXVT_NAME@@> sets the environment variables B<TERM>, B<COLORTERM> 1246B<@@RXVT_NAME@@> sets and/or uses the following environment variables:
999and B<COLORFGBG>. The environment variable B<WINDOWID> is set to the X 1247
1000window id number of the B<@@RXVT_NAME@@> window and it also uses and 1248=over 4
1001sets the environment variable B<DISPLAY> to specify which display 1249
1002terminal to use. B<@@RXVT_NAME@@> uses the environment variables 1250=item B<TERM>
1003B<RXVTPATH> and B<PATH> to find XPM files. 1251
1252Normally set to C<rxvt-unicode>, unless overwritten at configure time, via
1253resources or on the commandline.
1254
1255=item B<COLORTERM>
1256
1257Either C<rxvt>, C<rxvt-xpm>, depending on wether @@RXVT_NAME@@ was
1258compiled with XPM support, and optionally with the added extension
1259C<-mono> to indicate that rxvt-unicode runs on a monochrome screen.
1260
1261=item B<COLORFGBG>
1262
1263Set to a string of the form C<fg;bg> or C<fg;xpm;bg>, where C<fg> is
1264the colour code used as default foreground/text colour (or the string
1265C<default> to indicate that the default-colour escape sequence is to be
1266used), C<bg> is the colour code used as default background colour (or the
1267string C<default>), and C<xpm> is the string C<default> if @@RXVT_NAME@@
1268was compiled with XPM support. Libraries like C<ncurses> and C<slang> can
1269(and do) use this information to optimize screen output.
1270
1271=item B<WINDOWID>
1272
1273Set to the (decimal) X Window ID of the @@RXVT_NAME@@ window (the toplevel
1274window, which usually has subwindows for the scrollbar, the terminal
1275window and so on).
1276
1277=item B<TERMINFO>
1278
1279Set to the terminfo directory iff @@RXVT_NAME@@ was configured with
1280C<--with-terminfo=PATH>.
1281
1282=item B<DISPLAY>
1283
1284Used by @@RXVT_NAME@@ to connect to the display and set to the correct
1285display in it's child processes.
1286
1287=item B<SHELL>
1288
1289The shell to be used for command execution, defaults to C</bin/sh>.
1290
1291=item B<RXVTPATH>
1292
1293The path where @@RXVT_NAME@@ looks for support files such as menu and xpm
1294files.
1295
1296=item B<PATH>
1297
1298Used in the same way as C<RXVTPATH>.
1299
1300=item B<RXVT_SOCKET>
1301
1302The unix domain socket path used by @@RXVT_NAME@@c(1) and
1303@@RXVT_NAME@@d(1).
1304
1305Default F<<< $HOME/.rxvt-unicode-I<< <nodename >> >>>.
1306
1307=item B<HOME>
1308
1309Used to locate the default directory for the unix domain socket for
1310daemon communications and to locate various resource files (such as
1311C<.Xdefaults>)
1312
1313=item B<XAPPLRESDIR>
1314
1315Directory where various X resource files are being located.
1316
1317=item B<XENVIRONMENT>
1318
1319If set and accessible, gives the name of a X resource file to be loaded by
1320@@RXVT_NAME@@.
1321
1322=back
1004 1323
1005=head1 FILES 1324=head1 FILES
1006 1325
1007=over 4 1326=over 4
1008 1327
1009=item B</etc/utmp>
1010
1011System file for login records.
1012
1013=item B</usr/lib/X11/rgb.txt> 1328=item B</usr/lib/X11/rgb.txt>
1014 1329
1015Color names. 1330Color names.
1016 1331
1017=back 1332=back
1018 1333
1019=head1 SEE ALSO 1334=head1 SEE ALSO
1020 1335
1021@@RXVT_NAME@@(7), xterm(1), sh(1), resize(1), X(1), pty(4), tty(4), utmp(5) 1336@@RXVT_NAME@@(7), @@RXVT_NAME@@c(1), @@RXVT_NAME@@d(1), xterm(1), sh(1), resize(1), X(1), pty(4), tty(4), utmp(5)
1022
1023=head1 BUGS
1024
1025Check the BUGS file for an up-to-date list.
1026
1027Cursor change support is not yet implemented.
1028
1029Click-and-drag doesn't work with X11 mouse report overriding.
1030 1337
1031=head1 CURRENT PROJECT COORDINATOR 1338=head1 CURRENT PROJECT COORDINATOR
1032 1339
1033=over 4 1340=over 4
1034 1341
1035=item Project Coordinator 1342=item Project Coordinator
1036 1343
1037@@RXVT_MAINT@@ L<@@RXVT_MAINTEMAIL@@> 1344Marc A. Lehmann L<< <rxvt-unicode@schmorp.de> >>
1038 1345
1039=item Web page maintainter 1346L<http://software.schmorp.de/#rxvt-unicode>
1040
1041@@RXVT_WEBMAINT@@ L<@@RXVT_WEBMAINTEMAIL@@>
1042
1043L<@@RXVT_WEBPAGE@@>
1044 1347
1045=back 1348=back
1046 1349
1047=head1 AUTHORS 1350=head1 AUTHORS
1048 1351
1073=item Geoff Wing L<< <gcw@pobox.com> >> 1376=item Geoff Wing L<< <gcw@pobox.com> >>
1074 1377
1075Rewrote screen display and text selection routines. Project Coordinator 1378Rewrote screen display and text selection routines. Project Coordinator
1076(changes.txt 2.4.6 - rxvt-unicode) 1379(changes.txt 2.4.6 - rxvt-unicode)
1077 1380
1078=item Marc Alexander Lehmann L<< <rxvt@schmorp.de> >> 1381=item Marc Alexander Lehmann L<< <rxvt-unicode@schmorp.de> >>
1079 1382
1080Forked rxvt-unicode, rewrote most of the display code and internal 1383Forked rxvt-unicode, rewrote most of the display code and internal
1081character handling to store text in unicode, improve xterm 1384character handling to store text in unicode, improve xterm
1082compatibility and apply numerous other bugfixes and extensions. 1385compatibility and apply numerous other bugfixes and extensions.
1083 1386

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines