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.5 by root, Sat Aug 14 03:00:32 2004 UTC vs.
Revision 1.48 by root, Thu Feb 3 10:24:10 2005 UTC

11B<rxvt-unicode>, version B<@@RXVT_VERSION@@>, is a colour vt102 terminal 11B<rxvt-unicode>, version B<@@RXVT_VERSION@@>, is a colour vt102 terminal
12emulator intended as an I<xterm>(1) replacement for users who do not 12emulator intended as an I<xterm>(1) replacement for users who do not
13require features such as Tektronix 4014 emulation and toolkit-style 13require features such as Tektronix 4014 emulation and toolkit-style
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
17=head1 FREQUENTLY ASKED QUESTIONS
18
19See @@RXVT_NAME@@(7) (try C<man 7 @@RXVT_NAME@@>) for a list of frequently
20asked questions and answer to them and some common problems.
16 21
17=head1 RXVT-UNICODE VS. RXVT 22=head1 RXVT-UNICODE VS. RXVT
18 23
19Unlike the original rxvt, B<rxvt-unicode> stores all text in Unicode 24Unlike the original rxvt, B<rxvt-unicode> stores all text in Unicode
20internally. That means it can store and display most scripts in the 25internally. That means it can store and display most scripts in the
24like tibetan or devenagari. Don't expect pretty output when using these 29like tibetan or devenagari. Don't expect pretty output when using these
25scripts. Most other scripts, latin, cyrillic, kanji, thai etc. should work 30scripts. Most other scripts, latin, cyrillic, kanji, thai etc. should work
26fine, though. A somewhat difficult case are left-to-right scripts, such 31fine, though. A somewhat difficult case are left-to-right scripts, such
27as hebrew: B<rxvt-unicode> adopts the view that bidirectional algorithms 32as hebrew: B<rxvt-unicode> adopts the view that bidirectional algorithms
28belong into the application, not the terminal emulator (too many things -- 33belong into the application, not the terminal emulator (too many things --
29such as cursor-movement -- break othwerwise). 34such as cursor-movement while editing -- break otherwise), but that might
35change.
30 36
37If you are looking for a terminal that supports more exotic scripts, let
38me recommend C<mlterm>, which is a very userfriendly, lean and clean
39terminal emulator. In fact, the reason rxvt-unicode was born was solely
40because the author couldn't get C<mlterm> to use one font for latin1 and
41another for japanese.
42
31Another design rationale was the use of multiple fonts to display 43Therefore another design rationale was the use of multiple fonts to
32characters: The idea of a single unicode font which many other programs 44display characters: The idea of a single unicode font which many other
33force onto it's users never made sense to me: You should be able to choose 45programs force onto it's users never made sense to me: You should be able
34any font for any script. 46to choose any font for any script freely.
35 47
36Apart from that, rxvt-unicode is also much better internationalised than 48Apart from that, rxvt-unicode is also much better internationalised than
37it's predecessor, supports things such as XFT and ISO 14755 that are handy 49it's predecessor, supports things such as XFT and ISO 14755 that are handy
38in i18n-environments, is faster, and has a lot less bugs than the original 50in i18n-environments, is faster, and has a lot less bugs than the original
39rxvt. This all in addition to dozens of other small improvements. 51rxvt. This all in addition to dozens of other small improvements.
46drastically reduces memory usage. See @@RXVT_NAME@@d(1) (daemon) and 58drastically reduces memory usage. See @@RXVT_NAME@@d(1) (daemon) and
47@@RXVT_NAME@@c(1) (client). 59@@RXVT_NAME@@c(1) (client).
48 60
49It also makes technical information about escape sequences (which have 61It also makes technical information about escape sequences (which have
50been extended) easier accessible: see @@RXVT_NAME@@(7) for technical 62been extended) easier accessible: see @@RXVT_NAME@@(7) for technical
51reference documentation (escape sequences etc.) and the FAQ section at the 63reference documentation (escape sequences etc.).
52end of this document.
53 64
54=head1 OPTIONS 65=head1 OPTIONS
55 66
56The B<@@RXVT_NAME@@> options (mostly a subset of I<xterm>'s) are listed 67The B<@@RXVT_NAME@@> options (mostly a subset of I<xterm>'s) are listed
57below. In keeping with the smaller-is-better philosophy, options may be 68below. In keeping with the smaller-is-better philosophy, options may be
99Turn on/off inheriting parent window's pixmap. Alternative form is 110Turn on/off inheriting parent window's pixmap. Alternative form is
100B<-tr>; resource B<inheritPixmap>. 111B<-tr>; resource B<inheritPixmap>.
101 112
102=item B<-fade> I<number> 113=item B<-fade> I<number>
103 114
104Fade the text by the given percentage when focus is lost. 115Fade the text by the given percentage when focus is lost. resource B<fading>.
105 116
106=item B<-tint> I<colour> 117=item B<-tint> I<colour>
107 118
108Tint the transparent background pixmap with the given colour when 119Tint the transparent background pixmap with the given colour when
109transparency is enabled with B<-tr> or B<-ip>. See also the B<-sh> 120transparency is enabled with B<-tr> or B<-ip>. See also the B<-sh>
112 123
113=item B<-sh> 124=item B<-sh>
114 125
115I<number> Darken (0 .. 100) or lighten (-1 .. -100) the transparent 126I<number> Darken (0 .. 100) or lighten (-1 .. -100) the transparent
116background image in addition to tinting it (i.e. B<-tint> must be 127background image in addition to tinting it (i.e. B<-tint> must be
117specified, too). 128specified, too, e.g. C<-tint white>).
118 129
119=item B<-bg> I<colour> 130=item B<-bg> I<colour>
120 131
121Window background colour; resource B<background>. 132Window background colour; resource B<background>.
122 133
125Window foreground colour; resource B<foreground>. 136Window foreground colour; resource B<foreground>.
126 137
127=item B<-pixmap> I<file[;geom]> 138=item B<-pixmap> I<file[;geom]>
128 139
129Compile I<XPM>: Specify XPM file for the background and also optionally 140Compile I<XPM>: Specify XPM file for the background and also optionally
130specify its scaling with a geometry string. Note you may need to add 141specify its scaling with a geometry string. Note you may need to
131quotes to avoid special shell interpretation of the `;' in the 142add quotes to avoid special shell interpretation of the C<;> in the
132command-line; resource B<backgroundPixmap>. 143command-line; resource B<backgroundPixmap>.
133 144
134=item B<-cr> I<colour> 145=item B<-cr> I<colour>
135 146
136The cursor colour; resource B<cursorColor>. 147The cursor colour; resource B<cursorColor>.
143 154
144The mouse pointer background colour; resource B<pointerColor2>. 155The mouse pointer background colour; resource B<pointerColor2>.
145 156
146=item B<-bd> I<colour> 157=item B<-bd> I<colour>
147 158
148The colour of the border between the xterm scrollbar and the text; 159The colour of the border around the text area and between the scrollbar and the text;
149resource B<borderColor>. 160resource B<borderColor>.
150 161
151=item B<-fn> I<fontname> 162=item B<-fn> I<fontlist>
152 163
153Select the fonts to be used. This is a comma seperated list of font 164Select the fonts to be used. This is a comma separated list of font names
154names that are used in turn when trying to display Unicode characters. 165that are used in turn when trying to display Unicode characters. The
155The first font defines the cell size for characters; other fonts might 166first font defines the cell size for characters; other fonts might be
156be smaller, but not larger. A reasonable default font list is always 167smaller, but not (in general) larger. A (hopefully) reasonable default
157appended to it. resource B<font>. 168font list is always appended to it. See resource B<font> for more details.
169
170In short, to specify an X11 core font, just specify it's name or prefix it
171with C<x:>. To specify an XFT-font, you need to prefix it with C<xft:>,
172e.g.:
173
174 @@RXVT_NAME@@ -fn "xft:Bitstream Vera Sans Mono:pixelsize=15"
175 @@RXVT_NAME@@ -fn "9x15bold,xft:Bitstream Vera Sans Mono"
158 176
159See also the question "How does rxvt-unicode choose fonts?" in the FAQ 177See also the question "How does rxvt-unicode choose fonts?" in the FAQ
160section. 178section of @@RXVT_NAME@@(7).
161 179
162=item B<-rb>|B<+rb> 180=item B<-fb> I<fontlist>
163 181
164Enable "real bold" support. When this option is on, bold text will be 182Compile font-styles: The bold font list to use when bold characters are to
165displayed using the first available bold font in the font list. Bold 183be printed. See resource B<boldFont> for details.
166fonts should thus be specified in the font list after their 184
167corresponding regular fonts. If no bold font can be found, a regular 185=item B<-fi> I<fontlist>
168font will be used. resource B<realBold>. 186
187Compile font-styles: The italic font list to use when bold characters are to
188be printed. See resource B<italicFont> for details.
189
190=item B<-fbi> I<fontlist>
191
192Compile font-styles: The bold italic font list to use when bold characters are to
193be printed. See resource B<boldItalicFont> for details.
169 194
170=item B<-name> I<name> 195=item B<-name> I<name>
171 196
172Specify the application name under which resources are to be obtained, 197Specify the application name under which resources are to be obtained,
173rather than the default executable file name. Name should not contain 198rather than the default executable file name. Name should not contain
214=item B<-st>|B<+st> 239=item B<-st>|B<+st>
215 240
216Display normal (non XTerm/NeXT) scrollbar without/with a trough; 241Display normal (non XTerm/NeXT) scrollbar without/with a trough;
217resource B<scrollBar_floating>. 242resource B<scrollBar_floating>.
218 243
244=item B<-ptab>|B<+ptab>
245
246If enabled (default), "Horizontal Tab" characters are being stored as
247actual wide characters in the screen buffer, which makes it possible to
248select and paste them. Since a horizontal tab is a cursor movement and
249not an actual glyph, this can sometimes be visually annoying as the cursor
250on a tab character is displayed as a wide cursor; resource B<pastableTabs>.
251
219=item B<-bc>|B<+bc> 252=item B<-bc>|B<+bc>
220 253
221Blink the cursor; resource B<cursorBlink>. 254Blink the cursor; resource B<cursorBlink>.
222 255
223=item B<-iconic> 256=item B<-iconic>
247if honoured by the WM, the rxvt-unicode window will not have window 280if honoured by the WM, the rxvt-unicode window will not have window
248decorations; resource B<borderLess>. 281decorations; resource B<borderLess>.
249 282
250=item B<-lsp> I<number> 283=item B<-lsp> I<number>
251 284
252Compile I<linespace>: Lines (pixel height) to insert between each row 285Compile I<frills>: Lines (pixel height) to insert between each row of
253of the display; resource B<linespace>. 286the display. Useful to work around font rendering problems; resource
287B<linespace>.
254 288
255=item B<-tn> I<termname> 289=item B<-tn> I<termname>
256 290
257This option specifies the name of the terminal type to be set in the 291This option specifies the name of the terminal type to be set in the
258B<TERM> environment variable. This terminal type must exist in the 292B<TERM> environment variable. This terminal type must exist in the
294 328
295Compile I<XIM>: input method name. resource B<inputMethod>. 329Compile I<XIM>: input method name. resource B<inputMethod>.
296 330
297=item B<-imlocale> I<string> 331=item B<-imlocale> I<string>
298 332
299The locale to use for opening the IM. You can use an LC_CTYPE of e.g. 333The locale to use for opening the IM. You can use an C<LC_CTYPE> of e.g.
300de_DE.UTF-8 for normal text processing but ja_JP.EUC-JP for the input 334C<de_DE.UTF-8> for normal text processing but C<ja_JP.EUC-JP> for the
301extension to be able to input japanese characters while staying in 335input extension to be able to input japanese characters while staying in
302another locale. 336another locale. resource B<imLocale>.
337
338=item B<-imfont> I<fontset>
339
340Set the font set to use for the X Input Method, see resource B<imFont>
341for more info.
342
343=item B<-tcw>
344
345Change the meaning of triple-click selection with the left mouse
346button. Instead of selecting a full line it will extend the selection the
347end of the logical line only. resource B<tripleclickwords>.
303 348
304=item B<-insecure> 349=item B<-insecure>
305 350
306Enable "insecure" mode, which currently enables most of the escape 351Enable "insecure" mode, which currently enables most of the escape
307sequences that echo strings. See the resource B<insecure> for more 352sequences that echo strings. See the resource B<insecure> for more
382high-intensity (bold = bright foreground, blink = bright background) 427high-intensity (bold = bright foreground, blink = bright background)
383colours. The canonical names are as follows: 0=black, 1=red, 2=green, 428colours. The canonical names are as follows: 0=black, 1=red, 2=green,
3843=yellow, 4=blue, 5=magenta, 6=cyan, 7=white, but the actual colour 4293=yellow, 4=blue, 5=magenta, 6=cyan, 7=white, but the actual colour
385names used are listed in the B<COLORS AND GRAPHICS> section. 430names used are listed in the B<COLORS AND GRAPHICS> section.
386 431
432Colours higher than 15 cannot be set using resources (yet), but can be
433changed using an escape command (see @@RXVT_NAME@@(7)).
434
435Colours 16-79 form a standard 4x4x4 colour cube (the same as xterm with
43688 colour support). Colours 80-87 are evenly spaces grey steps.
437
387=item B<colorBD:> I<colour> 438=item B<colorBD:> I<colour>
388 439
440=item B<colorIT:> I<colour>
441
389Use the specified colour to display bold characters when the foreground 442Use the specified colour to display bold or italic characters when the
390colour is the default. This option will be ignored if B<realBold> is 443foreground colour is the default. If font styles are not available
391enabled. 444(Compile I<styles>) and this option is unset, reverse video is used instead.
392 445
393=item B<colorUL:> I<colour> 446=item B<colorUL:> I<colour>
394 447
395Use the specified colour to display underlined characters when the 448Use the specified colour to display underlined characters when the
396foreground colour is the default. 449foreground colour is the default.
397 450
398=item B<colorRV:> I<colour> 451=item B<colorRV:> I<colour>
399 452
400Use the specified colour as the background for reverse video 453Use the specified colour as the background for reverse video
401characters. 454characters.
455
456=item B<underlineColor:> I<colour>
457
458If set, use the specified colour as the colour for the underline
459itself. If unset, use the foreground colour.
402 460
403=item B<cursorColor:> I<colour> 461=item B<cursorColor:> I<colour>
404 462
405Use the specified colour for the cursor. The default is to use the 463Use the specified colour for the cursor. The default is to use the
406foreground colour; option B<-cr>. 464foreground colour; option B<-cr>.
440=item B<shading:> I<number> 498=item B<shading:> I<number>
441 499
442Darken (0 .. 100) or lighten (-1 .. -100) the transparent background 500Darken (0 .. 100) or lighten (-1 .. -100) the transparent background
443image in addition to tinting it. 501image in addition to tinting it.
444 502
445=item B<fading:> I<number>
446
447Scale the tint colour by the given percentage.
448
449=item B<scrollColor:> I<colour> 503=item B<scrollColor:> I<colour>
450 504
451Use the specified colour for the scrollbar [default #B2B2B2]. 505Use the specified colour for the scrollbar [default #B2B2B2].
452 506
453=item B<troughColor:> I<colour> 507=item B<troughColor:> I<colour>
454 508
455Use the specified colour for the scrollbar's trough area [default 509Use the specified colour for the scrollbar's trough area [default
456#969696]. Only relevant for normal (non XTerm/NeXT) scrollbar. 510#969696]. Only relevant for normal (non XTerm/NeXT) scrollbar.
511
512=item B<borderColor:> I<colour>
513
514The colour of the border around the text area and between the scrollbar
515and the text.
457 516
458=item B<backgroundPixmap:> I<file[;geom]> 517=item B<backgroundPixmap:> I<file[;geom]>
459 518
460Use the specified XPM file (note the `.xpm' extension is optional) for 519Use the specified XPM file (note the `.xpm' extension is optional) for
461the background and also optionally specify its scaling with a geometry 520the background and also optionally specify its scaling with a geometry
477 536
478Specify the colon-delimited search path for finding files (XPM and 537Specify the colon-delimited search path for finding files (XPM and
479menus), in addition to the paths specified by the B<RXVTPATH> and 538menus), in addition to the paths specified by the B<RXVTPATH> and
480B<PATH> environment variables. 539B<PATH> environment variables.
481 540
482=item B<font:> I<fontname> 541=item B<font:> I<fontlist>
483 542
484Select the fonts to be used. This is a comma seperated list of font 543Select the fonts to be used. This is a comma separated list of font
485names that are used in turn when trying to display Unicode characters. 544names that are used in turn when trying to display Unicode characters.
486The first font defines the cell size for characters; other fonts might 545The first font defines the cell size for characters; other fonts might
487be smaller, but not larger. A reasonable default font list is always 546be smaller, but not larger. A reasonable default font list is always
488appended to it. option B<-fn>. 547appended to it. option B<-fn>.
489 548
490=item B<realBold:> I<boolean> 549Each font can either be a standard X11 core font (XLFD) name, with
550optional prefix C<x:> or a Xft font (Compile I<xft>), prefixed with C<xft:>.
491 551
492B<True>: Enable "real bold" support. When this option is on, bold text 552In addition, each font can be prefixed with additional hints and
493will be displayed using the first available bold font in the font list. 553specifications enclosed in square brackets (C<[]>). The only available
494Bold fonts should thus be specified in the font list after their 554hint currently is C<codeset=codeset-name>, and this is only used for Xft
495corresponding regular fonts. If no bold font can be found, a regular 555fonts.
496font will be used. option B<-rb>. B<False>: Display bold text in a 556
497regular font, using the color specified with B<colorBD>; option B<+rb>. 557For example, this font resource
558
559 URxvt*font: 9x15bold,\
560 -misc-fixed-bold-r-normal--15-140-75-75-c-90-iso10646-1,\
561 -misc-fixed-medium-r-normal--15-140-75-75-c-90-iso10646-1, \
562 [codeset=JISX0208]xft:Kochi Gothic:antialias=false, \
563 xft:Code2000:antialias=false
564
565specifies five fonts to be used. The first one is C<9x15bold> (actually
566the iso8859-1 version of the second font), which is the base font (because
567it is named first) and thus defines the character cell grid to be 9 pixels
568wide and 15 pixels high.
569
570The second font is just used to add additional unicode characters not in
571the base font, likewise the third, which is unfortunately non-bold, but
572the bold version of the font does contain less characters, so this is a
573useful supplement.
574
575The third font is an Xft font with aliasing turned off, and the characters
576are limited to the B<JIS 0208> codeset (i.e. japanese kanji). The font
577contains other characters, but we are not interested in them.
578
579The last font is a useful catch-all font that supplies most of the
580remaining unicode characters.
581
582=item B<boldFont:> I<fontlist>
583
584=item B<italicFont:> I<fontlist>
585
586=item B<boldItalicFont:> I<fontlist>
587
588The font list to use for displaying B<bold>, I<italic> or B<< I<bold
589italic> >> characters, respectively.
590
591If specified and non-empty, then the syntax is the same as for the
592B<font>-resource, and the given font list will be used as is, which makes
593it possible to substitute completely different font styles for bold and
594italic.
595
596If unset (the default), a suitable font list will be synthesized by
597"morphing" the normal text font list into the desired shape. If that is
598not possible, replacement fonts of the desired shape will be tried.
599
600If set, but empty, then this specific style is disabled and the normal
601text font will being used for the given style.
498 602
499=item B<selectstyle:> I<mode> 603=item B<selectstyle:> I<mode>
500 604
501Set mouse selection style to B<old> which is 2.20, B<oldword> which is 605Set mouse selection style to B<old> which is 2.20, B<oldword> which is
502xterm style with 2.20 old word selection, or anything else which gives 606xterm style with 2.20 old word selection, or anything else which gives
573B<False>: do not scroll to bottom when tty receives output; option 677B<False>: do not scroll to bottom when tty receives output; option
574B<+si>. 678B<+si>.
575 679
576=item B<scrollWithBuffer:> I<boolean> 680=item B<scrollWithBuffer:> I<boolean>
577 681
578B<True>: scroll with scrollback buffer when tty recieves new lines (and 682B<True>: scroll with scrollback buffer when tty receives new lines (and
579B<scrollTtyOutput> is False); option B<+sw>. B<False>: do not scroll 683B<scrollTtyOutput> is False); option B<+sw>. B<False>: do not scroll
580with scrollback buffer when tty recieves new lines; option B<-sw>. 684with scrollback buffer when tty recieves new lines; option B<-sw>.
581 685
582=item B<scrollTtyKeypress:> I<boolean> 686=item B<scrollTtyKeypress:> I<boolean>
583 687
584B<True>: scroll to bottom when a non-special key is pressed. Special keys 688B<True>: scroll to bottom when a non-special key is pressed. Special keys
585are those which are intercepted by rxvt-unicode for special handling and 689are those which are intercepted by rxvt-unicode for special handling and
586are not passed onto the shell; option B<-sk>. B<False>: do not scroll to 690are not passed onto the shell; option B<-sk>. B<False>: do not scroll to
587bottom when a non-special key is pressed; option B<+sk>. 691bottom when a non-special key is pressed; option B<+sk>.
588 692
589=item B<smallfont_key:> I<keysym>
590
591If enabled, use B<@@HOTKEY@@->I<keysym> to toggle to a smaller font
592[default B<@@HOTKEY@@-@@SMALLFONT@@>]
593
594=item B<bigfont_key:> I<keysym>
595
596If enabled, use B<@@HOTKEY@@->I<keysym> to toggle to a bigger font
597[default B<@@HOTKEY@@-@@BIGFONT@@>]
598
599=item B<saveLines:> I<number> 693=item B<saveLines:> I<number>
600 694
601Save I<number> lines in the scrollback buffer [default 64]. This 695Save I<number> lines in the scrollback buffer [default 64]. This
602resource is limited on most machines to 65535; option B<-sl>. 696resource is limited on most machines to 65535; option B<-sl>.
603 697
633 727
634=item B<mouseWheelScrollPage:> I<boolean> 728=item B<mouseWheelScrollPage:> I<boolean>
635 729
636B<True>: the mouse wheel scrolls a page full. B<False>: the mouse wheel 730B<True>: the mouse wheel scrolls a page full. B<False>: the mouse wheel
637scrolls five lines [default]. 731scrolls five lines [default].
732
733=item B<pastableTabs:> I<boolean>
734
735B<True>: store tabs as wide characters. B<False>: interpret tabs as cursor
736movement only; option C<-ptab>.
638 737
639=item B<cursorBlink:> I<boolean> 738=item B<cursorBlink:> I<boolean>
640 739
641B<True>: blink the cursor. B<False>: do not blink the cursor [default]; 740B<True>: blink the cursor. B<False>: do not blink the cursor [default];
642option B<-bc>. 741option B<-bc>.
687 786
688I<name> of inputMethod to use; option B<-im>. 787I<name> of inputMethod to use; option B<-im>.
689 788
690=item B<imLocale:> I<name> 789=item B<imLocale:> I<name>
691 790
692The locale to use for opening the IM. You can use an LC_CTYPE of e.g. 791The locale to use for opening the IM. You can use an C<LC_CTYPE> of e.g.
693de_DE.UTF-8 for normal text processing but ja_JP.EUC-JP for the input 792C<de_DE.UTF-8> for normal text processing but C<ja_JP.EUC-JP> for the
694extension to be able to input japanese characters while staying in 793input extension to be able to input japanese characters while staying in
695another locale. option B<-imlocale>. 794another locale. option B<-imlocale>.
696 795
697=item B<insecure> 796=item B<imFont:> I<fontset>
797
798Specify the font-set used for XIM styles C<OverTheSpot> or
799C<OffTheSpot>. It must be a standard X font set (XLFD patterns separated
800by commas), i.e. it's not in the same format as the other font lists used
801in @@RXVT_NAME@@. The default will be set-up to chose *any* suitable found
802found, preferably one or two pixels differing in size to the base font.
803option B<-imfont>.
804
805=item B<tripleclickwords:> I<boolean>
806
807Change the meaning of triple-click selection with the left mouse
808button. Instead of selecting a full line it will extend the selection to
809the end of the logical line only. option B<-tcw>.
810
811=item B<insecure:> I<boolean>
698 812
699Enables "insecure" mode. Rxvt-unicode offers some escape sequences that 813Enables "insecure" mode. Rxvt-unicode offers some escape sequences that
700echo arbitrary strings like the icon name or the locale. This could be 814echo arbitrary strings like the icon name or the locale. This could be
701abused if somebody gets 8-bit-clean access to your display, wether 815abused if somebody gets 8-bit-clean access to your display, whether
702throuh a mail client displaying mail bodies unfiltered or though 816throuh a mail client displaying mail bodies unfiltered or though
703write(1). Therefore, these sequences are disabled by default. (Note 817write(1). Therefore, these sequences are disabled by default. (Note
704that other terminals, including xterm, have these sequences 818that other terminals, including xterm, have these sequences
705enabled by default). You can enable them by setting this boolean 819enabled by default). You can enable them by setting this boolean
706resource or specifying B<-insecure> as an option. At the moment, this 820resource or specifying B<-insecure> as an option. At the moment, this
730scrollback buffer and switching to/from the secondary screen will 844scrollback buffer and switching to/from the secondary screen will
731instead scroll the screen up. 845instead scroll the screen up.
732 846
733=item B<keysym.>I<sym>: I<string> 847=item B<keysym.>I<sym>: I<string>
734 848
735Associate I<string> with keysym I<sym> (B<0xFF00 - 0xFFFF>). It may 849Compile I<frills>: Associate I<string> with keysym I<sym>. The
736contain escape values (\a: bell, \b: backspace, \e, \E: escape, \n: 850intervening resource name B<keysym.> cannot be omitted.
737newline, \r: return, \t: 851
852The format of I<sym> is "I<(modifiers-)key>", where I<modifiers> can be
853any combination of B<ISOLevel3>, B<AppKeypad>, B<Control>, B<NumLock>,
854B<Shift>, B<Meta>, B<Lock>, B<Mod1>, B<Mod2>, B<Mod3>, B<Mod4>, B<Mod5>,
855and the abbreviated B<I>, B<K>, B<C>, B<N>, B<S>, B<M>, B<A>, B<L>, B<1>,
856B<2>, B<3>, B<4>, B<5>.
857
858The B<NumLock>, B<Meta> and B<ISOLevel3> modifiers are usually aliased to
859whatever modifier the NumLock key, Meta/Alt keys or ISO Level3 Shift/AltGr
860keys are being mapped. B<AppKeypad> is a synthetic modifier mapped to the
861current application keymap mode state.
862
863The spellings of I<key> can be obtained by using B<xev>(1) command or
864searching keysym macros from B</usr/X11R6/include/X11/keysymdef.h> and
865omitting the prefix B<XK_>. Alternatively you can specify I<key> by its hex
866keysym value (B<0x0000 - 0xFFFF>). Note that the lookup of I<sym>s is not
867performed in an exact manner; however, the closest match is assured.
868
869I<string> may contain escape values (C<\a>: bell, C<\b>: backspace,
870C<\e>, C<\E>: escape, C<\n>: newline, C<\r>: carriage return, C<\t>: tab,
738tab, \000: octal number) or control characters (^?: delete, ^@: null, 871C<\000>: octal number) or verbatim control characters (C<^?>: delete,
739^A ...) and may enclosed with double quotes so that it can start or end 872C<^@>: null, C<^A> ...) and may be enclosed with double quotes so that it
740with whitespace. The intervening resource name B<keysym.> cannot be 873can start or end with whitespace.
741omitted. This resource is only available when compiled with 874
742KEYSYM_RESOURCE. 875Please note that you need to double the C<\> when using
876C<--enable-xgetdefault>, as X itself does it's own de-escaping (you can
877use C<\033> instead of C<\e> (and so on), which will work with both Xt and
878@@RXVT_NAME@@'s own processing).
879
880You can define a range of keysyms in one shot by providing a I<string>
881with pattern B<list/PREFIX/MIDDLE/SUFFIX>, where the delimeter `/'
882should be a character not used by the strings.
883
884Its usage can be demonstrated by an example:
885
886 URxvt.keysym.M-C-0x61: list|\033<M-C-|abc|>
887
888The above line is equivalent to the following three lines:
889
890 URxvt.keysym.Meta-Control-0x61: \033<M-C-a>
891 URxvt.keysym.Meta-Control-0x62: \033<M-C-b>
892 URxvt.keysym.Meta-Control-0x63: \033<M-C-c>
893
894If I<string> takes the form of C<command:STRING>, the specified B<STRING>
895is interpreted and executed as @@RXVT_NAME@@'s control sequence. For
896example the following means "change the current locale to C<zh_CN.GBK>
897when Control-Meta-c is being pressed":
898
899 URxvt.keysym.M-C-c: command:\033]701;zh_CN.GBK\007
900
901The following example will map Control-Meta-1 and Control-Meta-2 to
902the fonts C<suxuseuro> and C<9x15bold>, so you can have some limited
903font-switching at runtime:
904
905 URxvt.keysym.M-C-1: command:\033]50;suxuseuro\007
906 URxvt.keysym.M-C-2: command:\033]50;9x15bold\007
907
908Other things are possible, e.g. resizing (see @@RXVT_NAME@@(7) for more
909info):
910
911 URxvt.keysym.M-C-3: command:\033[8;25;80t
912 URxvt.keysym.M-C-4: command:\033[8;48;110t
743 913
744=back 914=back
745 915
746=head1 THE SCROLLBAR 916=head1 THE SCROLLBAR
747 917
775 945
776=over 4 946=over 4
777 947
778=item B<Selection>: 948=item B<Selection>:
779 949
780Left click at the beginning of the region, drag to the end of the 950Left click at the beginning of the region, drag to the end of the region
781region and release; Right click to extend the marked region; Left 951and release; Right click to extend the marked region; Left double-click
782double-click to select a word; Left triple-click to select the entire 952to select a word; Left triple-click to select the entire logical line
783line. 953(which can span multiple screen lines), unless modified by resource
954B<tripleclickwords>.
955
956Starting a selection while pressing the B<Meta> key (or B<Meta+Ctrl> keys)
957(Compile: I<frills>) will create a rectangular selection instead of a normal
958one.
784 959
785=item B<Insertion>: 960=item B<Insertion>:
786 961
787Pressing and releasing the Middle mouse button (or B<Shift-Insert>) in 962Pressing and releasing the Middle mouse button (or B<Shift-Insert>) in
788an B<@@RXVT_NAME@@> window causes the current text selection to be 963an B<@@RXVT_NAME@@> window causes the current text selection to be
790 965
791=back 966=back
792 967
793=head1 CHANGING FONTS 968=head1 CHANGING FONTS
794 969
795You can change fonts on-the-fly, which is to say cycle through the 970Changing fonts (or font sizes, respectively) via the keypad is not yet
796default font and others of various sizes, by using B<Shift-KP_Add> and 971supported in rxvt-unicode. Bug me if you need this.
797B<Shift-KP_Subtract>. Or, alternatively (if enabled) with 972
798B<@@HOTKEY@@-@@BIGFONT@@> and B<@@HOTKEY@@-@@SMALLFONT@@>, where the 973You can, however, switch fonts at runtime using escape sequences (and
799actual key can be selected using resources 974therefore using the menubar), e.g.:
800B<smallfont_key>/B<bigfont_key>. 975
976 printf '\e]701;%s\007' "9x15bold,xft:Kochi Gothic"
977
978rxvt-unicode will automatically re-apply these fonts to the output so far.
801 979
802=head1 ISO 14755 SUPPORT 980=head1 ISO 14755 SUPPORT
803 981
804Partial ISO 14755-support is implemented. that means that pressing 982ISO 14755 is a standard for entering and viewing unicode characters
983and character codes using the keyboard. It consists of 4 parts. The
984first part is available rxvt-unicode has been compiled with
985C<--enable-frills>, the rest is available when rxvt-unicode was compiled
986with C<--enable-iso14755>.
805 987
806Section 5.1: Control and Shift together enters unicode input 988=over 4
807mode. Entering hex digits composes a Unicode character, pressing space or
808releasing the modifiers commits the keycode and every other key cancels
809the current input character.
810 989
811Section 5.2: Pressing and immediately releasing Control and Shift together 990=item * 5.1: Basic method
812enters keycap entry mode for the next key: pressing a function key (tab, 991
813return etc..) will enter the unicode character corresponding to the given 992This allows you to enter unicode characters using their hexcode.
814key. 993
994Start by pressing and holding both C<Control> and C<Shift>, then enter
995hex-digits (between one and six). Releasing C<Control> and C<Shift> will
996commit the character as if it were typed directly. While holding down
997C<Control> and C<Shift> you can also enter multiple characters by pressing
998C<Space>, which will commit the current character and lets you start a new
999one.
1000
1001As an example of use, imagine a business card with a japanese e-mail
1002address, which you cannot type. Fortunately, the card has the e-mail
1003address printed as hexcodes, e.g. C<671d 65e5>. You can enter this easily
1004by pressing C<Control> and C<Shift>, followed by C<6-7-1-D-SPACE-6-5-E-5>,
1005followed by releasing the modifier keys.
1006
1007=item * 5.2: Keyboard symbols entry method
1008
1009This mode lets you input characters representing the keycap symbols of
1010your keyboard, if representable in the current locale encoding.
1011
1012Start by pressing C<Control> and C<Shift> together, then releasing
1013them. The next special key (cursor keys, home etc.) you enter will not
1014invoke it's usual function but instead will insert the corresponding
1015keycap symbol. The symbol will only be entered when the key has been
1016released, otherwise pressing e.g. C<Shift> would enter the symbol for
1017C<ISO Level 2 Switch>, although your intention might have been to enter a
1018reverse tab (Shift-Tab).
1019
1020=item * 5.3: Screen-selection entry method
1021
1022While this is implemented already (it's basically the selection
1023mechanism), it could be extended by displaying a unicode character map.
1024
1025=item * 5.4: Feedback method for identifying displayed characters for later input
1026
1027This method lets you display the unicode character code associated with
1028characters already displayed.
1029
1030You enter this mode by holding down C<Control> and C<Shift> together, then
1031pressing and holding the left mouse button and moving around. The unicode
1032hex code(s) (it might be a combining character) of the character under the
1033pointer is displayed until you release C<Control> and C<Shift>.
1034
1035In addition to the hex codes it will display the font used to draw this
1036character - due to implementation reasons, characters combined with
1037combining characters, line drawing characters and unknown characters will
1038always be drawn using the built-in support font.
1039
1040=back
1041
1042With respect to conformance, rxvt-unicode is supposed to be compliant to
1043both scenario A and B of ISO 14755, including part 5.2.
815 1044
816=head1 LOGIN STAMP 1045=head1 LOGIN STAMP
817 1046
818B<@@RXVT_NAME@@> tries to write an entry into the I<utmp>(5) file so 1047B<@@RXVT_NAME@@> tries to write an entry into the I<utmp>(5) file so that
819that it can be seen via the I<who(1)> command, and can accept messages. 1048it can be seen via the I<who(1)> command, and can accept messages. To
820To allow this feature, B<@@RXVT_NAME@@> must be installed setuid root on 1049allow this feature, B<@@RXVT_NAME@@> may need to be installed setuid root
821some systems. 1050on some systems or setgid to root or to some other group on others.
822 1051
823=head1 COLORS AND GRAPHICS 1052=head1 COLORS AND GRAPHICS
824 1053
825In addition to the default foreground and background colours, 1054In addition to the default foreground and background colours,
826B<@@RXVT_NAME@@> can display up to 16 colours (8 ANSI colours plus 1055B<@@RXVT_NAME@@> can display up to 16 colours (8 ANSI colours plus
867would yield White on Black, while on I<xterm>(1) it would yield Black 1096would yield White on Black, while on I<xterm>(1) it would yield Black
868on White. 1097on White.
869 1098
870=back 1099=back
871 1100
872=head1 FREQUENTLY ASKED QUESTIONS (FAQ)
873
874=over 4
875
876=item How do I know which rxvt-unicode version I'm using?
877
878The version number is displayed with the usage (-h). For rxvt-unicode
879version 2.14 and later, the escape sequence C<ESC[8n> sets the window
880title to the version number.
881
882=item Why do the characters look ugly?
883
884=item How does rxvt-unicode choose fonts?
885
886Most fonts do not contain the full range of Unicode, which is
887fine. Chances are that the font you (or the admin/package maintainer of
888your system/os) have specified does not cover all the characters you want
889to display.
890
891B<rxvt-unicode> makes a best-effort try at finding a replacement
892font. Often the result is fine, but sometimes the chosen font looks
893bad. In that case, select a font of your taste and add it to the font
894list, e.g.:
895
896 @@RXVT_NAME@@ -fn basefont,font2,font3...
897
898When rxvt-unicode sees a character, it will first look at the base
899font. If the base font does not contain the character, it will go to the
900next font, and so on.
901
902The only limitation is that all the fonts must not be larger than the base
903font, as the base font defines the principial cell size, which must be the
904same due to the way terminals work.
905
906=item Why do some chinese characters look so different than others?
907
908This is because there is a difference between script and language --
909rxvt-unicode does not know which language the text that is output
910is, as it only knows the unicode character codes. If rxvt-unicode
911first sees a japanese character, it might choose a japanese font for
912it. Subseqzuent japanese characters will take that font. Now, many chinese
913characters aren't represented in japanese fonts, so when the first
914non-japanese character comes up, rxvt-unicode will look for a chinese font
915-- unfortunately at this point, it will still use the japanese font for
916japanese characters that are also chinese.
917
918The workaround is easy: just tag a chinese font at the end of your font
919list (see the previous question). The key is to view the font list as
920a preference list: If you expect more japanese, list a japanese font
921first. If you expect more chinese, put a chinese font first.
922
923In the future it might be possible to switch preferences at runtime (the
924internal data structure has no problem with using different fonts for
925the same character at the same time, but no interface for this has been
926designed yet).
927
928=item Mouse cut/paste suddenly no longer works.
929
930Make sure that mouse reporting is actually turned off since killing
931some editors prematurely may leave the mouse in mouse report mode. I've
932heard that tcsh may use mouse reporting unless it otherwise specified. A
933quick check is to see if cut/paste works when the Alt or Shift keys are
934depressed. See @@RXVT_NAME@@(7)
935
936=item What's with this bold/blink stuff?
937
938If no bold colour is set via C<colorBD:>, bold will invert text using the
939standard foreground colour.
940
941For the standard background colour, blinking will actually make the
942text blink when compiled with C<--enable-blinking>. with standard
943colours. Without C<--enable-blinking>, the blink attribute will be
944ignored.
945
946On ANSI colours, bold/blink attributes are used to set high-intensity
947foreground/background colors.
948
949color0-7 are the low-intensity colors.
950
951color8-15 are the corresponding high-intensity colors.
952
953=item I don't like the screen colors. How do I change them?
954
955You can change the screen colors at run-time using F<~/.Xdefaults>
956resources (or as long-options).
957
958Here are values that are supposed to resemble a VGA screen,
959including the murky brown that passes for low-intensity yellow:
960
961 Rxvt*color0: #000000
962 Rxvt*color1: #A80000
963 Rxvt*color2: #00A800
964 Rxvt*color3: #A8A800
965 Rxvt*color4: #0000A8
966 Rxvt*color5: #A800A8
967 Rxvt*color6: #00A8A8
968 Rxvt*color7: #A8A8A8
969
970 Rxvt*color8: #000054
971 Rxvt*color9: #FF0054
972 Rxvt*color10: #00FF54
973 Rxvt*color11: #FFFF54
974 Rxvt*color12: #0000FF
975 Rxvt*color13: #FF00FF
976 Rxvt*color14: #00FFFF
977 Rxvt*color15: #FFFFFF
978
979=item What's with the strange Backspace/Delete key behaviour?
980
981Assuming that the physical Backspace key corresponds to the
982BackSpace keysym (not likely for Linux ... see the following
983question) there are two standard values that can be used for
984Backspace: C<^H> and C<^?>.
985
986Historically, either value is correct, but rxvt-unicode adopts the debian
987policy of using C<^?> when unsure, because it's the one only only correct
988choice :).
989
990Rxvt-unicode tries to inherit the current stty settings and uses the value
991of `erase' to guess the value for backspace. If rxvt-unicode wasn't
992started from a terminal (say, from a menu or by remote shell), then the
993system value of `erase', which corresponds to CERASE in <termios.h>, will
994be used (which may not be the same as your stty setting).
995
996For starting a new rxvt-unicode:
997
998 # use Backspace = ^H
999 $ stty erase ^H
1000 $ @@RXVT_NAME@@
1001
1002 # use Backspace = ^?
1003 $ stty erase ^?
1004 $ @@RXVT_NAME@@
1005
1006Toggle with "ESC[36h" / "ESC[36l" as documented in @@RXVT_NAME@@(7).
1007
1008For an existing rxvt-unicode:
1009
1010 # use Backspace = ^H
1011 $ stty erase ^H
1012 $ echo -n "^[[36h"
1013
1014 # use Backspace = ^?
1015 $ stty erase ^?
1016 $ echo -n "^[[36l"
1017
1018This helps satisfy some of the Backspace discrepancies that occur, but
1019if you use Backspace = C<^H>, make sure that the termcap/terminfo value
1020properly reflects that.
1021
1022The Delete key is a another casualty of the ill-defined Backspace problem.
1023To avoid confusion between the Backspace and Delete keys, the Delete
1024key has been assigned an escape sequence to match the vt100 for Execute
1025(ESC[3~) and is in the supplied termcap/terminfo.
1026
1027Some other Backspace problems:
1028
1029some editors use termcap/terminfo,
1030some editors (vim I'm told) expect Backspace = ^H,
1031GNU Emacs (and Emacs-like editors) use ^H for help.
1032
1033Perhaps someday this will all be resolved in a consistent manner.
1034
1035=item I don't like the key-bindings. How do I change them?
1036
1037There are some compile-time selections available via configure. Unless
1038you have run "configure" with the C<--disable-resources> option you can
1039use the `keysym' resource to alter the keystrings associated with keysym
10400xFF00 - 0xFFFF (function, cursor keys, etc).
1041
1042Here's an example for a tn3270 session started using `@@RXVT_NAME@@ -name tn3270'
1043
1044 !# ----- special uses ------:
1045 ! tn3270 login, remap function and arrow keys.
1046 tn3270*font: *clean-bold-*-*--15-*
1047
1048 ! keysym - used by rxvt only
1049 ! Delete - ^D
1050 tn3270*keysym.0xFFFF: \004
1051
1052 ! Home - ^A
1053 tn3270*keysym.0xFF50: \001
1054 ! Left - ^B
1055 tn3270*keysym.0xFF51: \002
1056 ! Up - ^P
1057 tn3270*keysym.0xFF52: \020
1058 ! Right - ^F
1059 tn3270*keysym.0xFF53: \006
1060 ! Down - ^N
1061 tn3270*keysym.0xFF54: \016
1062 ! End - ^E
1063 tn3270*keysym.0xFF57: \005
1064
1065 ! F1 - F12
1066 tn3270*keysym.0xFFBE: \e1
1067 tn3270*keysym.0xFFBF: \e2
1068 tn3270*keysym.0xFFC0: \e3
1069 tn3270*keysym.0xFFC1: \e4
1070 tn3270*keysym.0xFFC2: \e5
1071 tn3270*keysym.0xFFC3: \e6
1072 tn3270*keysym.0xFFC4: \e7
1073 tn3270*keysym.0xFFC5: \e8
1074 tn3270*keysym.0xFFC6: \e9
1075 tn3270*keysym.0xFFC7: \e0
1076 tn3270*keysym.0xFFC8: \e-
1077 tn3270*keysym.0xFFC9: \e=
1078
1079 ! map Prior/Next to F7/F8
1080 tn3270*keysym.0xFF55: \e7
1081 tn3270*keysym.0xFF56: \e8
1082
1083=item I'm using keyboard model XXX that has extra Prior/Next/Insert keys.
1084How do I make use of them? For example, the Sun Keyboard type 4
1085has the following mappings that rxvt-unicode doesn't recognize.
1086
1087 KP_Insert == Insert
1088 F22 == Print
1089 F27 == Home
1090 F29 == Prior
1091 F33 == End
1092 F35 == Next
1093
1094Rather than have rxvt-unicode try to accomodate all the various possible keyboard
1095mappings, it is better to use `xmodmap' to remap the keys as required for
1096your particular machine.
1097
1098=item How do I distinguish if I'm running rxvt-unicode or a regular xterm?
1099I need this to decide about setting colors etc.
1100
1101rxvt and rxvt-unicode always export the variable "COLORTERM", so you can
1102check and see if that is set. Note that several programs, JED, slrn,
1103Midnight Commander automatically check this variable to decide whether or
1104not to use color.
1105
1106=item How do I set the correct, full IP address for the DISPLAY variable?
1107
1108If you've compiled rxvt-unicode with DISPLAY_IS_IP and ahve enabled
1109insecure mode then it is possible to use the following shell script
1110snippets to correctly set the display. If your version of rxvt-unicode
1111wasn't also compiled with ESCZ_ANSWER (as assumed in these snippets) then
1112the COLORTERM variable can be used to distinguish rxvt-unicode from a
1113regular xterm.
1114
1115Courtesy of Chuck Blake <cblake@BBN.COM> with the following shell script
1116snippets:
1117
1118 # Bourne/Korn/POSIX family of shells:
1119 [ ${TERM:-foo} = foo ] && TERM=xterm # assume an xterm if we don't know
1120 if [ ${TERM:-foo} = xterm ]; then
1121 stty -icanon -echo min 0 time 15 # see if enhanced rxvt or not
1122 echo -n '^[Z'
1123 read term_id
1124 stty icanon echo
1125 if [ ""${term_id} = '^[[?1;2C' -a ${DISPLAY:-foo} = foo ]; then
1126 echo -n '^[[7n' # query the rxvt we are in for the DISPLAY string
1127 read DISPLAY # set it in our local shell
1128 fi
1129 fi
1130
1131=item How do I compile the manual pages for myself?
1132
1133You need to have a recent version of perl installed as F</usr/bin/perl>,
1134one that comes with F<pod2man>, F<pod2text> and F<pod2html>. Then go to
1135the doc subdirectory and enter C<make alldoc>.
1136
1137=back
1138
1139=head1 ENVIRONMENT 1101=head1 ENVIRONMENT
1140 1102
1141B<@@RXVT_NAME@@> sets the environment variables B<TERM>, B<COLORTERM> 1103B<@@RXVT_NAME@@> sets the environment variables B<TERM>, B<COLORTERM>
1142and B<COLORFGBG>. The environment variable B<WINDOWID> is set to the X 1104and B<COLORFGBG>. The environment variable B<WINDOWID> is set to the X
1143window id number of the B<@@RXVT_NAME@@> window and it also uses and 1105window id number of the B<@@RXVT_NAME@@> window and it also uses and
1147 1109
1148=head1 FILES 1110=head1 FILES
1149 1111
1150=over 4 1112=over 4
1151 1113
1152=item B</etc/utmp>
1153
1154System file for login records.
1155
1156=item B</usr/lib/X11/rgb.txt> 1114=item B</usr/lib/X11/rgb.txt>
1157 1115
1158Color names. 1116Color names.
1159 1117
1160=back 1118=back
1175 1133
1176=over 4 1134=over 4
1177 1135
1178=item Project Coordinator 1136=item Project Coordinator
1179 1137
1180@@RXVTMAINT@@ L<@@RXVT_MAINTEMAIL@@> 1138@@RXVT_MAINT@@ L<@@RXVT_MAINTEMAIL@@>
1181 1139
1182=item Web page maintainter 1140=item Web page maintainter
1183 1141
1184@@RXVTWEBMAINT@@ L<@@RXVT_WEBMAINTEMAIL@@> 1142@@RXVT_WEBMAINT@@ L<@@RXVT_WEBMAINTEMAIL@@>
1185 1143
1186L<@@RXVT_WEBPAGE@@> 1144L<@@RXVT_WEBPAGE@@>
1187 1145
1188=back 1146=back
1189 1147

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines