ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/rxvt-unicode/doc/rxvt.1.pod
Revision: 1.98
Committed: Mon Jan 16 15:12:48 2006 UTC (18 years, 5 months ago) by root
Branch: MAIN
Changes since 1.97: +0 -9 lines
Log Message:
*** empty log message ***

File Contents

# User Rev Content
1 root 1.1 =head1 NAME
2    
3     rxvt-unicode (ouR XVT, unicode) - (a VT102 emulator for the X window system)
4    
5     =head1 SYNOPSIS
6    
7 root 1.2 B<@@RXVT_NAME@@> [options] [-e command [ args ]]
8 root 1.1
9     =head1 DESCRIPTION
10    
11 root 1.3 B<rxvt-unicode>, version B<@@RXVT_VERSION@@>, is a colour vt102 terminal
12 root 1.1 emulator intended as an I<xterm>(1) replacement for users who do not
13     require features such as Tektronix 4014 emulation and toolkit-style
14     configurability. As a result, B<rxvt-unicode> uses much less swap space --
15     a significant advantage on a machine serving many X sessions.
16    
17 root 1.30 =head1 FREQUENTLY ASKED QUESTIONS
18    
19 root 1.53 See @@RXVT_NAME@@(7) (try C<man 7 @@RXVT_NAME@@>) for a list of
20     frequently asked questions and answer to them and some common
21     problems. That document is also accessible on the World-Wide-Web at
22     L<http://cvs.schmorp.de/browse/*checkout*/rxvt-unicode/doc/rxvt.7.html>.
23 root 1.30
24 root 1.5 =head1 RXVT-UNICODE VS. RXVT
25    
26     Unlike the original rxvt, B<rxvt-unicode> stores all text in Unicode
27     internally. That means it can store and display most scripts in the
28     world. Being a terminal emulator, however, some things are very difficult,
29     especially cursive scripts such as arabic, vertically written scripts
30     like mongolian or scripts requiring extremely complex combining rules,
31     like tibetan or devenagari. Don't expect pretty output when using these
32     scripts. Most other scripts, latin, cyrillic, kanji, thai etc. should work
33     fine, though. A somewhat difficult case are left-to-right scripts, such
34     as hebrew: B<rxvt-unicode> adopts the view that bidirectional algorithms
35     belong into the application, not the terminal emulator (too many things --
36 root 1.30 such as cursor-movement while editing -- break otherwise), but that might
37 root 1.12 change.
38 root 1.5
39 root 1.12 If you are looking for a terminal that supports more exotic scripts, let
40     me recommend C<mlterm>, which is a very userfriendly, lean and clean
41     terminal emulator. In fact, the reason rxvt-unicode was born was solely
42     because the author couldn't get C<mlterm> to use one font for latin1 and
43     another for japanese.
44    
45     Therefore another design rationale was the use of multiple fonts to
46     display characters: The idea of a single unicode font which many other
47     programs force onto it's users never made sense to me: You should be able
48     to choose any font for any script freely.
49 root 1.5
50     Apart from that, rxvt-unicode is also much better internationalised than
51     it's predecessor, supports things such as XFT and ISO 14755 that are handy
52     in i18n-environments, is faster, and has a lot less bugs than the original
53     rxvt. This all in addition to dozens of other small improvements.
54    
55     It is still faithfully following the original rxvt idea of being lean
56     and nice on resources: for example, you can still configure rxvt-unicode
57     without most of it's features to get a lean binary. It also comes with
58     a client/daemon pair that lets you open any number of terminal windows
59     from within a single process, which makes startup time very fast and
60     drastically reduces memory usage. See @@RXVT_NAME@@d(1) (daemon) and
61     @@RXVT_NAME@@c(1) (client).
62    
63     It also makes technical information about escape sequences (which have
64     been extended) easier accessible: see @@RXVT_NAME@@(7) for technical
65 root 1.30 reference documentation (escape sequences etc.).
66 root 1.2
67 root 1.1 =head1 OPTIONS
68    
69 root 1.2 The B<@@RXVT_NAME@@> options (mostly a subset of I<xterm>'s) are listed
70 root 1.1 below. In keeping with the smaller-is-better philosophy, options may be
71     eliminated or default values chosen at compile-time, so options and
72     defaults listed may not accurately reflect the version installed on
73 root 1.3 your system. `@@RXVT_NAME@@ -h' gives a list of major compile-time options on
74 root 1.1 the I<Options> line. Option descriptions may be prefixed with which
75     compile option each is dependent upon. e.g. `Compile I<XIM>:' requires
76 root 1.3 I<XIM> on the I<Options> line. Note: `@@RXVT_NAME@@ -help' gives a list of all
77 root 1.1 command-line options compiled into your version.
78    
79 root 1.2 Note that B<@@RXVT_NAME@@> permits the resource name to be used as a
80 root 1.1 long-option (--/++ option) so the potential command-line options are
81 root 1.3 far greater than those listed. For example: `@@RXVT_NAME@@ --loginShell --color1
82 root 1.1 Orange'.
83    
84     The following options are available:
85    
86     =over 4
87    
88     =item B<-help>, B<--help>
89    
90     Print out a message describing available options.
91    
92     =item B<-display> I<displayname>
93    
94     Attempt to open a window on the named X display (B<-d> still
95     respected). In the absence of this option, the display specified by the
96     B<DISPLAY> environment variable is used.
97    
98     =item B<-geometry> I<geom>
99    
100     Window geometry (B<-g> still respected); resource B<geometry>.
101    
102     =item B<-rv>|B<+rv>
103    
104     Turn on/off simulated reverse video; resource B<reverseVideo>.
105    
106     =item B<-j>|B<+j>
107    
108     Turn on/off jump scrolling; resource B<jumpScroll>.
109    
110 root 1.69 =item B<-ip>|B<+ip> | B<-tr>|B<+tr>
111 root 1.1
112     Turn on/off inheriting parent window's pixmap. Alternative form is
113     B<-tr>; resource B<inheritPixmap>.
114    
115     =item B<-fade> I<number>
116    
117 root 1.68 Fade the text by the given percentage when focus is lost. Small values
118     fade a little only, 100 completely replaces all colours by the fade
119     colour; resource B<fading>.
120    
121     =item B<-fadecolor> I<colour>
122    
123     Fade to this colour when fading is used (see B<-fade>). The default colour
124     is black. resource B<fadeColor>.
125 root 1.1
126     =item B<-tint> I<colour>
127    
128     Tint the transparent background pixmap with the given colour when
129 root 1.70 transparency is enabled with B<-tr> or B<-ip>. This only works for
130     non-tiled backgrounds, currently. See also the B<-sh> option that can be
131     used to brighten or darken the image in addition to tinting it; resource
132     I<tintColor>. Example:
133 root 1.69
134     @@RXVT_NAME@@ -tr -tint blue -sh 40
135 root 1.1
136     =item B<-sh>
137    
138     I<number> Darken (0 .. 100) or lighten (-1 .. -100) the transparent
139     background image in addition to tinting it (i.e. B<-tint> must be
140 root 1.36 specified, too, e.g. C<-tint white>).
141 root 1.1
142     =item B<-bg> I<colour>
143    
144     Window background colour; resource B<background>.
145    
146     =item B<-fg> I<colour>
147    
148     Window foreground colour; resource B<foreground>.
149    
150     =item B<-pixmap> I<file[;geom]>
151    
152     Compile I<XPM>: Specify XPM file for the background and also optionally
153 root 1.43 specify its scaling with a geometry string. Note you may need to
154     add quotes to avoid special shell interpretation of the C<;> in the
155 root 1.1 command-line; resource B<backgroundPixmap>.
156    
157     =item B<-cr> I<colour>
158    
159     The cursor colour; resource B<cursorColor>.
160    
161     =item B<-pr> I<colour>
162    
163     The mouse pointer foreground colour; resource B<pointerColor>.
164    
165     =item B<-pr2> I<colour>
166    
167     The mouse pointer background colour; resource B<pointerColor2>.
168    
169     =item B<-bd> I<colour>
170    
171 root 1.22 The colour of the border around the text area and between the scrollbar and the text;
172 root 1.1 resource B<borderColor>.
173    
174 root 1.22 =item B<-fn> I<fontlist>
175 root 1.1
176 root 1.22 Select the fonts to be used. This is a comma separated list of font names
177 root 1.96 that are checked in order when trying to find glyphs for characters. The
178 root 1.22 first font defines the cell size for characters; other fonts might be
179 root 1.34 smaller, but not (in general) larger. A (hopefully) reasonable default
180     font list is always appended to it. See resource B<font> for more details.
181    
182     In short, to specify an X11 core font, just specify it's name or prefix it
183     with C<x:>. To specify an XFT-font, you need to prefix it with C<xft:>,
184     e.g.:
185    
186     @@RXVT_NAME@@ -fn "xft:Bitstream Vera Sans Mono:pixelsize=15"
187     @@RXVT_NAME@@ -fn "9x15bold,xft:Bitstream Vera Sans Mono"
188 root 1.1
189 root 1.5 See also the question "How does rxvt-unicode choose fonts?" in the FAQ
190 root 1.30 section of @@RXVT_NAME@@(7).
191 root 1.5
192 root 1.22 =item B<-fb> I<fontlist>
193    
194 root 1.85 Compile I<font-styles>: The bold font list to use when B<bold> characters
195     are to be printed. See resource B<boldFont> for details.
196 root 1.22
197     =item B<-fi> I<fontlist>
198    
199 root 1.85 Compile I<font-styles>: The italic font list to use when I<italic>
200     characters are to be printed. See resource B<italicFont> for details.
201 root 1.22
202     =item B<-fbi> I<fontlist>
203 root 1.1
204 root 1.85 Compile I<font-styles>: The bold italic font list to use when B<< I<bold
205 root 1.83 italic> >> characters are to be printed. See resource B<boldItalicFont>
206     for details.
207 root 1.1
208 root 1.76 =item B<-is>|B<+is>
209    
210 root 1.85 Compile I<font-styles>: Bold/Italic font styles imply high intensity
211 root 1.76 foreground/background (default). See resource B<intensityStyles> for
212     details.
213    
214 root 1.1 =item B<-name> I<name>
215    
216     Specify the application name under which resources are to be obtained,
217     rather than the default executable file name. Name should not contain
218     `.' or `*' characters. Also sets the icon and title name.
219    
220     =item B<-ls>|B<+ls>
221    
222     Start as a login-shell/sub-shell; resource B<loginShell>.
223    
224     =item B<-ut>|B<+ut>
225    
226     Compile I<utmp>: Inhibit/enable writing a utmp entry; resource
227     B<utmpInhibit>.
228    
229     =item B<-vb>|B<+vb>
230    
231     Turn on/off visual bell on receipt of a bell character; resource
232     B<visualBell>.
233    
234     =item B<-sb>|B<+sb>
235    
236     Turn on/off scrollbar; resource B<scrollBar>.
237    
238     =item B<-si>|B<+si>
239    
240     Turn on/off scroll-to-bottom on TTY output inhibit; resource
241     B<scrollTtyOutput> has opposite effect.
242    
243     =item B<-sk>|B<+sk>
244    
245     Turn on/off scroll-to-bottom on keypress; resource
246     B<scrollTtyKeypress>.
247    
248     =item B<-sw>|B<+sw>
249    
250     Turn on/off scrolling with the scrollback buffer as new lines appear.
251     This only takes effect if B<-si> is also given; resource
252     B<scrollWithBuffer>.
253    
254     =item B<-sr>|B<+sr>
255    
256     Put scrollbar on right/left; resource B<scrollBar_right>.
257    
258     =item B<-st>|B<+st>
259    
260 root 1.64 Display rxvt (non XTerm/NeXT) scrollbar without/with a trough;
261 root 1.1 resource B<scrollBar_floating>.
262    
263 root 1.34 =item B<-ptab>|B<+ptab>
264    
265     If enabled (default), "Horizontal Tab" characters are being stored as
266     actual wide characters in the screen buffer, which makes it possible to
267     select and paste them. Since a horizontal tab is a cursor movement and
268     not an actual glyph, this can sometimes be visually annoying as the cursor
269     on a tab character is displayed as a wide cursor; resource B<pastableTabs>.
270    
271 root 1.1 =item B<-bc>|B<+bc>
272    
273     Blink the cursor; resource B<cursorBlink>.
274    
275     =item B<-iconic>
276    
277     Start iconified, if the window manager supports that option.
278     Alternative form is B<-ic>.
279    
280     =item B<-sl> I<number>
281    
282     Save I<number> lines in the scrollback buffer. See resource entry for
283     limits; resource B<saveLines>.
284    
285     =item B<-b> I<number>
286    
287     Compile I<frills>: Internal border of I<number> pixels. See resource
288     entry for limits; resource B<internalBorder>.
289    
290     =item B<-w> I<number>
291    
292     Compile I<frills>: External border of I<number> pixels. Also, B<-bw>
293     and B<-borderwidth>. See resource entry for limits; resource
294     B<externalBorder>.
295    
296     =item B<-bl>
297    
298     Compile I<frills>: Set MWM hints to request a borderless window, i.e.
299 root 1.3 if honoured by the WM, the rxvt-unicode window will not have window
300 root 1.1 decorations; resource B<borderLess>.
301    
302 root 1.85 =item B<-sbg>
303    
304     Compile I<frills>: Disable the usage of the built-in block graphics/line
305     drawing characters and just rely on what the specified fonts provide. Use
306     this if you have a good font and want to use its block graphic glyphs;
307     resource B<skipBuiltinGlyphs>.
308    
309 root 1.1 =item B<-lsp> I<number>
310    
311 root 1.43 Compile I<frills>: Lines (pixel height) to insert between each row of
312     the display. Useful to work around font rendering problems; resource
313     B<linespace>.
314 root 1.1
315     =item B<-tn> I<termname>
316    
317     This option specifies the name of the terminal type to be set in the
318     B<TERM> environment variable. This terminal type must exist in the
319     I<termcap(5)> database and should have I<li#> and I<co#> entries;
320     resource B<termName>.
321    
322     =item B<-e> I<command [arguments]>
323    
324 root 1.2 Run the command with its command-line arguments in the B<@@RXVT_NAME@@>
325 root 1.1 window; also sets the window title and icon name to be the basename of
326     the program being executed if neither I<-title> (I<-T>) nor I<-n> are
327     given on the command line. If this option is used, it must be the last
328     on the command-line. If there is no B<-e> option then the default is to
329     run the program specified by the B<SHELL> environment variable or,
330     failing that, I<sh(1)>.
331    
332 root 1.74 Please note that you must specify a program with arguments. If you want to
333     run shell commands, you have to specify the shell, like this:
334    
335     @@RXVT_NAME@@ -e sh -c "shell commands"
336    
337 root 1.1 =item B<-title> I<text>
338    
339     Window title (B<-T> still respected); the default title is the basename
340     of the program specified after the B<-e> option, if any, otherwise the
341     application name; resource B<title>.
342    
343     =item B<-n> I<text>
344    
345     Icon name; the default name is the basename of the program specified
346     after the B<-e> option, if any, otherwise the application name;
347     resource B<iconName>.
348    
349     =item B<-C>
350    
351     Capture system console messages.
352    
353     =item B<-pt> I<style>
354    
355     Compile I<XIM>: input style for input method; B<OverTheSpot>,
356     B<OffTheSpot>, B<Root>; resource B<preeditType>.
357    
358     =item B<-im> I<text>
359    
360     Compile I<XIM>: input method name. resource B<inputMethod>.
361    
362     =item B<-imlocale> I<string>
363    
364 root 1.48 The locale to use for opening the IM. You can use an C<LC_CTYPE> of e.g.
365     C<de_DE.UTF-8> for normal text processing but C<ja_JP.EUC-JP> for the
366     input extension to be able to input japanese characters while staying in
367     another locale. resource B<imLocale>.
368    
369     =item B<-imfont> I<fontset>
370    
371     Set the font set to use for the X Input Method, see resource B<imFont>
372     for more info.
373    
374     =item B<-tcw>
375    
376     Change the meaning of triple-click selection with the left mouse
377     button. Instead of selecting a full line it will extend the selection the
378     end of the logical line only. resource B<tripleclickwords>.
379 root 1.1
380     =item B<-insecure>
381    
382     Enable "insecure" mode, which currently enables most of the escape
383     sequences that echo strings. See the resource B<insecure> for more
384     info.
385    
386     =item B<-mod> I<modifier>
387    
388     Override detection of Meta modifier with specified key: B<alt>,
389     B<meta>, B<hyper>, B<super>, B<mod1>, B<mod2>, B<mod3>, B<mod4>,
390     B<mod5>; resource I<modifier>.
391    
392     =item B<-ssc>|B<+ssc>
393    
394     Turn on/off secondary screen (default enabled); resource
395     B<secondaryScreen>.
396    
397     =item B<-ssr>|B<+ssr>
398    
399     Turn on/off secondary screen scroll (default enabled); resource
400     B<secondaryScroll>.
401    
402 root 1.74 =item B<-hold>|B<+hold>
403    
404     Turn on/off hold window after exit support. If enabled, @@RXVT_NAME@@
405     will not immediately destroy its window when the program executed within
406     it exits. Instead, it will wait till it is being killed or closed by the
407     user; resource B<hold>.
408    
409 root 1.59 =item B<-keysym.>I<sym> I<string>
410 root 1.53
411     Remap a key symbol. See resource B<keysym>.
412    
413 root 1.59 =item B<-embed> I<windowid>
414 root 1.1
415 root 1.56 Tells @@RXVT_NAME@@ to embed it's windows into an already-existing window,
416     which enables applications to easily embed a terminal.
417    
418     Right now, @@RXVT_NAME@@ will first unmap/map the specified window, so it
419     shouldn't be a top-level window. @@RXVT_NAME@@ will also reconfigure it
420     quite a bit, so don't expect it to keep some specific state. It's best to
421     create an extra subwindow for @@RXVT_NAME@@ and leave it alone.
422    
423 root 1.57 The window will not be destroyed when @@RXVT_NAME@@ exits.
424    
425 root 1.56 It might be useful to know that @@RXVT_NAME@@ will not close file
426     descriptors passed to it (except for stdin/out/err, of course), so you
427     can use file descriptors to communicate with the programs within the
428     terminal. This works regardless of wether the C<-embed> option was used or
429     not.
430 root 1.1
431 root 1.59 Here is a short Gtk2-perl snippet that illustrates how this option can be
432     used (a longer example is in F<doc/embed>):
433    
434 root 1.61 my $rxvt = new Gtk2::Socket;
435     $rxvt->signal_connect_after (realize => sub {
436     my $xid = $_[0]->window->get_xid;
437     system "@@RXVT_NAME@@ -embed $xid &";
438     });
439 root 1.59
440 root 1.86 =item B<-pty-fd> I<file descriptor>
441 root 1.59
442     Tells @@RXVT_NAME@@ NOT to execute any commands or create a new pty/tty
443     pair but instead use the given filehandle as the tty master. This is
444     useful if you want to drive @@RXVT_NAME@@ as a generic terminal emulator
445     without having to run a program within it.
446    
447     If this switch is given, @@RXVT_NAME@@ will not create any utmp/wtmp
448     entries and will not tinker with pty/tty permissions - you have to do that
449     yourself if you want that.
450    
451 root 1.86 As an extremely special case, specifying C<-1> will completely suppress
452     pty/tty operations.
453    
454 root 1.59 Here is a example in perl that illustrates how this option can be used (a
455     longer example is in F<doc/pty-fd>):
456    
457     use IO::Pty;
458     use Fcntl;
459    
460     my $pty = new IO::Pty;
461     fcntl $pty, F_SETFD, 0; # clear close-on-exec
462     system "@@RXVT_NAME@@ -pty-fd " . (fileno $pty) . "&";
463 root 1.60 close $pty;
464 root 1.59
465     # now communicate with rxvt
466     my $slave = $pty->slave;
467     while (<$slave>) { print $slave "got <$_>\n" }
468    
469 root 1.78 =item B<-pe> I<string>
470 root 1.77
471 root 1.88 Comma-separated list of perl extension scripts to use (or not to use) in
472     this terminal instance. See resource B<perl-ext> for details.
473 root 1.77
474 root 1.1 =back
475    
476     =head1 RESOURCES (available also as long-options)
477    
478 root 1.2 Note: `@@RXVT_NAME@@ --help' gives a list of all resources (long
479 root 1.1 options) compiled into your version.
480    
481 root 1.93 You can set and change the resources using X11 tools like B<xrdb>. Many
482     distribution do also load settings from the B<~/.Xresources> file when X
483     starts. @@RXVT_NAME@@ will consult the following files/resources in order,
484     with later settings overwriting earlier ones:
485 root 1.53
486     1. system-wide app-defaults file, either locale-dependent OR global
487     2. app-defaults file in $XAPPLRESDIR
488     3. RESOURCE_MANAGER property on root-window OR $HOME/.Xdefaults
489     4. SCREEN_RESOURCES for the current screen
490     5. $XENVIRONMENT file OR $HOME/.Xdefaults-<nodename>
491 root 1.1
492 root 1.93 Note that when reading X resources, B<@@RXVT_NAME@@> recognizes two class
493     names: B<Rxvt> and B<URxvt>. The class name B<Rxvt> allows resources
494     common to both B<@@RXVT_NAME@@> and the original I<rxvt> to be easily
495     configured, while the class name B<URxvt> allows resources unique to
496     B<@@RXVT_NAME@@>, to be shared between different B<@@RXVT_NAME@@>
497     configurations. If no resources are specified, suitable defaults will
498     be used. Command-line arguments can be used to override resource
499     settings. The following resources are supported (you might want to
500     check the @@RXVT_NAME@@perl(3) manpage for additional settings by perl
501     extensions not documented here):
502 root 1.1
503     =over 4
504    
505     =item B<geometry:> I<geom>
506    
507     Create the window with the specified X window geometry [default 80x24];
508     option B<-geometry>.
509    
510     =item B<background:> I<colour>
511    
512     Use the specified colour as the window's background colour [default
513     White]; option B<-bg>.
514    
515     =item B<foreground:> I<colour>
516    
517     Use the specified colour as the window's foreground colour [default
518     Black]; option B<-fg>.
519    
520     =item B<color>I<n>B<:> I<colour>
521    
522     Use the specified colour for the colour value I<n>, where 0-7
523     corresponds to low-intensity (normal) colours and 8-15 corresponds to
524     high-intensity (bold = bright foreground, blink = bright background)
525     colours. The canonical names are as follows: 0=black, 1=red, 2=green,
526     3=yellow, 4=blue, 5=magenta, 6=cyan, 7=white, but the actual colour
527     names used are listed in the B<COLORS AND GRAPHICS> section.
528    
529 root 1.22 Colours higher than 15 cannot be set using resources (yet), but can be
530     changed using an escape command (see @@RXVT_NAME@@(7)).
531    
532     Colours 16-79 form a standard 4x4x4 colour cube (the same as xterm with
533     88 colour support). Colours 80-87 are evenly spaces grey steps.
534    
535 root 1.1 =item B<colorBD:> I<colour>
536    
537 root 1.22 =item B<colorIT:> I<colour>
538    
539     Use the specified colour to display bold or italic characters when the
540     foreground colour is the default. If font styles are not available
541 root 1.43 (Compile I<styles>) and this option is unset, reverse video is used instead.
542 root 1.1
543     =item B<colorUL:> I<colour>
544    
545     Use the specified colour to display underlined characters when the
546     foreground colour is the default.
547    
548     =item B<colorRV:> I<colour>
549    
550     Use the specified colour as the background for reverse video
551     characters.
552    
553 root 1.35 =item B<underlineColor:> I<colour>
554    
555     If set, use the specified colour as the colour for the underline
556     itself. If unset, use the foreground colour.
557    
558 root 1.1 =item B<cursorColor:> I<colour>
559    
560     Use the specified colour for the cursor. The default is to use the
561     foreground colour; option B<-cr>.
562    
563     =item B<cursorColor2:> I<colour>
564    
565     Use the specified colour for the colour of the cursor text. For this to
566     take effect, B<cursorColor> must also be specified. The default is to
567     use the background colour.
568    
569     =item B<reverseVideo:> I<boolean>
570    
571     B<True>: simulate reverse video by foreground and background colours;
572     option B<-rv>. B<False>: regular screen colours [default]; option
573     B<+rv>. See note in B<COLORS AND GRAPHICS> section.
574    
575     =item B<jumpScroll:> I<boolean>
576    
577     B<True>: specify that jump scrolling should be used. When scrolling
578     quickly, fewer screen updates are performed [default]; option B<-j>.
579     B<False>: specify that smooth scrolling should be used; option B<+j>.
580    
581     =item B<inheritPixmap:> I<boolean>
582    
583     B<True>: make the background inherit the parent windows' pixmap, giving
584     artificial transparency. B<False>: do not inherit the parent windows'
585     pixmap.
586    
587     =item B<fading:> I<number>
588    
589 root 1.68 Fade the text by the given percentage when focus is lost; option B<-fade>.
590    
591     =item B<fadeColor:> I<colour>
592    
593     Fade to this colour, when fading is used (see B<fading:>). The default
594     colour is black; option B<-fadecolor>.
595 root 1.1
596     =item B<tintColor:> I<colour>
597    
598 root 1.68 Tint the transparent background pixmap with the given colour; option
599     B<-tint>.
600 root 1.1
601     =item B<shading:> I<number>
602    
603     Darken (0 .. 100) or lighten (-1 .. -100) the transparent background
604     image in addition to tinting it.
605    
606     =item B<scrollColor:> I<colour>
607    
608     Use the specified colour for the scrollbar [default #B2B2B2].
609    
610     =item B<troughColor:> I<colour>
611    
612     Use the specified colour for the scrollbar's trough area [default
613 root 1.64 #969696]. Only relevant for rxvt (non XTerm/NeXT) scrollbar.
614 root 1.1
615 root 1.22 =item B<borderColor:> I<colour>
616    
617     The colour of the border around the text area and between the scrollbar
618     and the text.
619    
620 root 1.1 =item B<backgroundPixmap:> I<file[;geom]>
621    
622     Use the specified XPM file (note the `.xpm' extension is optional) for
623     the background and also optionally specify its scaling with a geometry
624     string B<WxH+X+Y>, in which B<"W" / "H"> specify the
625     horizontal/vertical scale (percent) and B<"X" / "Y"> locate the image
626     centre (percent). A scale of 0 displays the image with tiling. A scale
627     of 1 displays the image without any scaling. A scale of 2 to 9
628     specifies an integer number of images in that direction. No image will
629     be magnified beyond 10 times its original size. The maximum permitted
630     scale is 1000. [default 0x0+50+50]
631    
632     =item B<path:> I<path>
633    
634 root 1.97 Specify the colon-delimited search path for finding XPM files.
635 root 1.1
636 root 1.22 =item B<font:> I<fontlist>
637 root 1.1
638 root 1.96 Select the fonts to be used. This is a comma separated list of font names
639     that are checked in order when trying to find glyphs for characters. The
640     first font defines the cell size for characters; other fonts might be
641     smaller, but not (in general) larger. A (hopefully) reasonable default
642     font list is always appended to it; option B<-fn>.
643 root 1.1
644 root 1.22 Each font can either be a standard X11 core font (XLFD) name, with
645 root 1.43 optional prefix C<x:> or a Xft font (Compile I<xft>), prefixed with C<xft:>.
646 root 1.22
647     In addition, each font can be prefixed with additional hints and
648     specifications enclosed in square brackets (C<[]>). The only available
649     hint currently is C<codeset=codeset-name>, and this is only used for Xft
650     fonts.
651    
652     For example, this font resource
653 root 1.1
654 root 1.97 URxvt.font: 9x15bold,\
655 root 1.22 -misc-fixed-bold-r-normal--15-140-75-75-c-90-iso10646-1,\
656     -misc-fixed-medium-r-normal--15-140-75-75-c-90-iso10646-1, \
657     [codeset=JISX0208]xft:Kochi Gothic:antialias=false, \
658     xft:Code2000:antialias=false
659    
660     specifies five fonts to be used. The first one is C<9x15bold> (actually
661     the iso8859-1 version of the second font), which is the base font (because
662     it is named first) and thus defines the character cell grid to be 9 pixels
663     wide and 15 pixels high.
664    
665 root 1.34 The second font is just used to add additional unicode characters not in
666 root 1.22 the base font, likewise the third, which is unfortunately non-bold, but
667     the bold version of the font does contain less characters, so this is a
668     useful supplement.
669    
670     The third font is an Xft font with aliasing turned off, and the characters
671     are limited to the B<JIS 0208> codeset (i.e. japanese kanji). The font
672     contains other characters, but we are not interested in them.
673    
674     The last font is a useful catch-all font that supplies most of the
675     remaining unicode characters.
676    
677     =item B<boldFont:> I<fontlist>
678    
679     =item B<italicFont:> I<fontlist>
680    
681     =item B<boldItalicFont:> I<fontlist>
682    
683     The font list to use for displaying B<bold>, I<italic> or B<< I<bold
684     italic> >> characters, respectively.
685    
686     If specified and non-empty, then the syntax is the same as for the
687     B<font>-resource, and the given font list will be used as is, which makes
688     it possible to substitute completely different font styles for bold and
689     italic.
690    
691     If unset (the default), a suitable font list will be synthesized by
692     "morphing" the normal text font list into the desired shape. If that is
693     not possible, replacement fonts of the desired shape will be tried.
694    
695     If set, but empty, then this specific style is disabled and the normal
696     text font will being used for the given style.
697 root 1.1
698 root 1.76 =item B<intensityStyles:> I<boolean>
699    
700     When font styles are not enabled, or this option is enabled (B<True>,
701     option B<-is>, the default), bold and italic font styles imply high
702     intensity foreground/backround colours. Disabling this option (B<False>,
703     option B<+is>) disables this behaviour, the high intensity colours are not
704     reachable.
705    
706 root 1.1 =item B<selectstyle:> I<mode>
707    
708     Set mouse selection style to B<old> which is 2.20, B<oldword> which is
709     xterm style with 2.20 old word selection, or anything else which gives
710     xterm style selection.
711    
712     =item B<scrollstyle:> I<mode>
713    
714 root 1.3 Set scrollbar style to B<rxvt>, B<plain>, B<next> or B<xterm>. B<plain> is
715 root 1.64 the author's favourite.
716 root 1.1
717     =item B<title:> I<string>
718    
719     Set window title string, the default title is the command-line
720     specified after the B<-e> option, if any, otherwise the application
721     name; option B<-title>.
722    
723     =item B<iconName:> I<string>
724    
725     Set the name used to label the window's icon or displayed in an icon
726     manager window, it also sets the window's title unless it is explicitly
727     set; option B<-n>.
728    
729     =item B<mapAlert:> I<boolean>
730    
731     B<True>: de-iconify (map) on receipt of a bell character. B<False>: no
732     de-iconify (map) on receipt of a bell character [default].
733    
734     =item B<visualBell:> I<boolean>
735    
736     B<True>: use visual bell on receipt of a bell character; option B<-vb>.
737     B<False>: no visual bell [default]; option B<+vb>.
738    
739     =item B<loginShell:> I<boolean>
740    
741     B<True>: start as a login shell by prepending a `-' to B<argv[0]> of
742     the shell; option B<-ls>. B<False>: start as a normal sub-shell
743     [default]; option B<+ls>.
744    
745     =item B<utmpInhibit:> I<boolean>
746    
747     B<True>: inhibit writing record into the system log file B<utmp>;
748     option B<-ut>. B<False>: write record into the system log file B<utmp>
749     [default]; option B<+ut>.
750    
751     =item B<print-pipe:> I<string>
752    
753     Specify a command pipe for vt100 printer [default I<lpr(1)>]. Use
754     B<Print> to initiate a screen dump to the printer and B<Ctrl-Print> or
755     B<Shift-Print> to include the scrollback as well.
756    
757 root 1.65 The string will be interpreted as if typed into the shell as-is.
758    
759 root 1.66 Example:
760    
761 root 1.97 URxvt.print-pipe: cat > $(TMPDIR=$HOME mktemp urxvt.XXXXXX)
762 root 1.66
763     This creates a new file in your home directory with the screen contents
764     everytime you hit C<Print>.
765    
766 root 1.1 =item B<scrollBar:> I<boolean>
767    
768     B<True>: enable the scrollbar [default]; option B<-sb>. B<False>:
769     disable the scrollbar; option B<+sb>.
770    
771     =item B<scrollBar_right:> I<boolean>
772    
773     B<True>: place the scrollbar on the right of the window; option B<-sr>.
774     B<False>: place the scrollbar on the left of the window; option B<+sr>.
775    
776     =item B<scrollBar_floating:> I<boolean>
777    
778     B<True>: display an rxvt scrollbar without a trough; option B<-st>.
779     B<False>: display an rxvt scrollbar with a trough; option B<+st>.
780    
781     =item B<scrollBar_align:> I<mode>
782    
783     Align the B<top>, B<bottom> or B<centre> [default] of the scrollbar
784     thumb with the pointer on middle button press/drag.
785    
786     =item B<scrollTtyOutput:> I<boolean>
787    
788 root 1.4 B<True>: scroll to bottom when tty receives output; option B<-si>.
789 root 1.1 B<False>: do not scroll to bottom when tty receives output; option
790 root 1.4 B<+si>.
791 root 1.1
792     =item B<scrollWithBuffer:> I<boolean>
793    
794 root 1.30 B<True>: scroll with scrollback buffer when tty receives new lines (and
795 root 1.58 B<scrollTtyOutput> is False); option B<-sw>. B<False>: do not scroll
796     with scrollback buffer when tty recieves new lines; option B<+sw>.
797 root 1.1
798     =item B<scrollTtyKeypress:> I<boolean>
799    
800 root 1.3 B<True>: scroll to bottom when a non-special key is pressed. Special keys
801     are those which are intercepted by rxvt-unicode for special handling and
802     are not passed onto the shell; option B<-sk>. B<False>: do not scroll to
803     bottom when a non-special key is pressed; option B<+sk>.
804 root 1.1
805     =item B<saveLines:> I<number>
806    
807     Save I<number> lines in the scrollback buffer [default 64]. This
808     resource is limited on most machines to 65535; option B<-sl>.
809    
810     =item B<internalBorder:> I<number>
811    
812     Internal border of I<number> pixels. This resource is limited to 100;
813     option B<-b>.
814    
815     =item B<externalBorder:> I<number>
816    
817     External border of I<number> pixels. This resource is limited to 100;
818     option B<-w>, B<-bw>, B<-borderwidth>.
819    
820     =item B<borderLess:> I<boolean>
821    
822     Set MWM hints to request a borderless window, i.e. if honoured by the
823 root 1.3 WM, the rxvt-unicode window will not have window decorations; option B<-bl>.
824 root 1.1
825 root 1.85 =item B<skipBuiltinGlyphs:> I<boolean>
826    
827     Compile I<frills>: Disable the usage of the built-in block graphics/line
828     drawing characters and just rely on what the specified fonts provide. Use
829     this if you have a good font and want to use its block graphic glyphs;
830     option B<-sbg>.
831    
832 root 1.1 =item B<termName:> I<termname>
833    
834     Specifies the terminal type name to be set in the B<TERM> environment
835     variable; option B<-tn>.
836    
837     =item B<linespace:> I<number>
838    
839     Specifies number of lines (pixel height) to insert between each row of
840     the display [default 0]; option B<-lsp>.
841    
842     =item B<meta8:> I<boolean>
843    
844     B<True>: handle Meta (Alt) + keypress to set the 8th bit. B<False>:
845     handle Meta (Alt) + keypress as an escape prefix [default].
846    
847     =item B<mouseWheelScrollPage:> I<boolean>
848    
849     B<True>: the mouse wheel scrolls a page full. B<False>: the mouse wheel
850     scrolls five lines [default].
851    
852 root 1.34 =item B<pastableTabs:> I<boolean>
853    
854     B<True>: store tabs as wide characters. B<False>: interpret tabs as cursor
855     movement only; option C<-ptab>.
856    
857 root 1.1 =item B<cursorBlink:> I<boolean>
858    
859     B<True>: blink the cursor. B<False>: do not blink the cursor [default];
860     option B<-bc>.
861    
862     =item B<pointerBlank:> I<boolean>
863    
864     B<True>: blank the pointer when a key is pressed or after a set number
865     of seconds of inactivity. B<False>: the pointer is always visible
866     [default].
867    
868     =item B<pointerColor:> I<colour>
869    
870     Mouse pointer foreground colour.
871    
872     =item B<pointerColor2:> I<colour>
873    
874     Mouse pointer background colour.
875    
876     =item B<pointerBlankDelay:> I<number>
877    
878 root 1.62 Specifies number of seconds before blanking the pointer [default 2]. Use a
879     large number (e.g. C<987654321>) to effectively disable the timeout.
880 root 1.1
881     =item B<backspacekey:> I<string>
882    
883     The string to send when the backspace key is pressed. If set to B<DEC>
884     or unset it will send B<Delete> (code 127) or, if shifted, B<Backspace>
885     (code 8) - which can be reversed with the appropriate DEC private mode
886     escape sequence.
887    
888     =item B<deletekey:> I<string>
889    
890     The string to send when the delete key (not the keypad delete key) is
891     pressed. If unset it will send the sequence traditionally associated
892     with the B<Execute> key.
893    
894     =item B<cutchars:> I<string>
895    
896     The characters used as delimiters for double-click word selection. The
897     built-in default:
898    
899     B<< BACKSLASH `"'&()*,;<=>?@[]{|} >>
900    
901     =item B<preeditType:> I<style>
902    
903     B<OverTheSpot>, B<OffTheSpot>, B<Root>; option B<-pt>.
904    
905     =item B<inputMethod:> I<name>
906    
907     I<name> of inputMethod to use; option B<-im>.
908    
909     =item B<imLocale:> I<name>
910    
911 root 1.48 The locale to use for opening the IM. You can use an C<LC_CTYPE> of e.g.
912     C<de_DE.UTF-8> for normal text processing but C<ja_JP.EUC-JP> for the
913     input extension to be able to input japanese characters while staying in
914 root 1.77 another locale; option B<-imlocale>.
915 root 1.1
916 root 1.48 =item B<imFont:> I<fontset>
917    
918     Specify the font-set used for XIM styles C<OverTheSpot> or
919     C<OffTheSpot>. It must be a standard X font set (XLFD patterns separated
920     by commas), i.e. it's not in the same format as the other font lists used
921     in @@RXVT_NAME@@. The default will be set-up to chose *any* suitable found
922     found, preferably one or two pixels differing in size to the base font.
923     option B<-imfont>.
924    
925     =item B<tripleclickwords:> I<boolean>
926    
927     Change the meaning of triple-click selection with the left mouse
928     button. Instead of selecting a full line it will extend the selection to
929 root 1.77 the end of the logical line only; option B<-tcw>.
930 root 1.48
931 root 1.22 =item B<insecure:> I<boolean>
932 root 1.1
933     Enables "insecure" mode. Rxvt-unicode offers some escape sequences that
934     echo arbitrary strings like the icon name or the locale. This could be
935 root 1.30 abused if somebody gets 8-bit-clean access to your display, whether
936 root 1.73 through a mail client displaying mail bodies unfiltered or through
937     write(1) or any other means. Therefore, these sequences are disabled by
938     default. (Note that many other terminals, including xterm, have these
939     sequences enabled by default, which doesn't make it safer, though).
940    
941     You can enable them by setting this boolean resource or specifying
942     B<-insecure> as an option. At the moment, this enables display-answer,
943 root 1.97 locale, findfont, icon label and window title requests.
944 root 1.1
945     =item B<modifier:> I<modifier>
946    
947     Set the key to be interpreted as the Meta key to: B<alt>, B<meta>,
948     B<hyper>, B<super>, B<mod1>, B<mod2>, B<mod3>, B<mod4>, B<mod5>; option
949     B<-mod>.
950    
951     =item B<answerbackString:> I<string>
952    
953 root 1.3 Specify the reply rxvt-unicode sends to the shell when an ENQ (control-E)
954 root 1.1 character is passed through. It may contain escape values as described
955     in the entry on B<keysym> following.
956    
957     =item B<secondaryScreen:> I<bool>
958    
959     Turn on/off secondary screen (default enabled).
960    
961     =item B<secondaryScroll:> I<bool>
962    
963     Turn on/off secondary screen scroll (default enabled). If the this
964     option is enabled, scrolls on the secondary screen will change the
965     scrollback buffer and switching to/from the secondary screen will
966     instead scroll the screen up.
967    
968 root 1.74 =item B<hold>: I<bool>
969    
970     Turn on/off hold window after exit support. If enabled, @@RXVT_NAME@@
971     will not immediately destroy its window when the program executed within
972     it exits. Instead, it will wait till it is being killed or closed by the
973     user.
974    
975 root 1.1 =item B<keysym.>I<sym>: I<string>
976    
977 root 1.43 Compile I<frills>: Associate I<string> with keysym I<sym>. The
978     intervening resource name B<keysym.> cannot be omitted.
979    
980     The format of I<sym> is "I<(modifiers-)key>", where I<modifiers> can be
981     any combination of B<ISOLevel3>, B<AppKeypad>, B<Control>, B<NumLock>,
982     B<Shift>, B<Meta>, B<Lock>, B<Mod1>, B<Mod2>, B<Mod3>, B<Mod4>, B<Mod5>,
983     and the abbreviated B<I>, B<K>, B<C>, B<N>, B<S>, B<M>, B<A>, B<L>, B<1>,
984     B<2>, B<3>, B<4>, B<5>.
985    
986     The B<NumLock>, B<Meta> and B<ISOLevel3> modifiers are usually aliased to
987     whatever modifier the NumLock key, Meta/Alt keys or ISO Level3 Shift/AltGr
988 root 1.48 keys are being mapped. B<AppKeypad> is a synthetic modifier mapped to the
989 root 1.43 current application keymap mode state.
990    
991     The spellings of I<key> can be obtained by using B<xev>(1) command or
992     searching keysym macros from B</usr/X11R6/include/X11/keysymdef.h> and
993     omitting the prefix B<XK_>. Alternatively you can specify I<key> by its hex
994     keysym value (B<0x0000 - 0xFFFF>). Note that the lookup of I<sym>s is not
995     performed in an exact manner; however, the closest match is assured.
996    
997     I<string> may contain escape values (C<\a>: bell, C<\b>: backspace,
998     C<\e>, C<\E>: escape, C<\n>: newline, C<\r>: carriage return, C<\t>: tab,
999     C<\000>: octal number) or verbatim control characters (C<^?>: delete,
1000     C<^@>: null, C<^A> ...) and may be enclosed with double quotes so that it
1001     can start or end with whitespace.
1002    
1003 root 1.93 Please note that you need to double the C<\> in resource files, as
1004     Xlib itself does it's own de-escaping (you can use C<\033> instead of
1005     C<\e> (and so on), which will work with both Xt and @@RXVT_NAME@@'s own
1006     processing).
1007 root 1.48
1008 root 1.43 You can define a range of keysyms in one shot by providing a I<string>
1009     with pattern B<list/PREFIX/MIDDLE/SUFFIX>, where the delimeter `/'
1010     should be a character not used by the strings.
1011    
1012     Its usage can be demonstrated by an example:
1013    
1014 root 1.48 URxvt.keysym.M-C-0x61: list|\033<M-C-|abc|>
1015 root 1.43
1016     The above line is equivalent to the following three lines:
1017    
1018 root 1.48 URxvt.keysym.Meta-Control-0x61: \033<M-C-a>
1019     URxvt.keysym.Meta-Control-0x62: \033<M-C-b>
1020     URxvt.keysym.Meta-Control-0x63: \033<M-C-c>
1021    
1022     If I<string> takes the form of C<command:STRING>, the specified B<STRING>
1023     is interpreted and executed as @@RXVT_NAME@@'s control sequence. For
1024     example the following means "change the current locale to C<zh_CN.GBK>
1025     when Control-Meta-c is being pressed":
1026    
1027     URxvt.keysym.M-C-c: command:\033]701;zh_CN.GBK\007
1028    
1029 root 1.80 If I<string> takes the form C<perl:STRING>, then the specified B<STRING>
1030 root 1.81 is passed to the C<on_keyboard_command> perl handler. See the @@RXVT_NAME@@perl(3)
1031 root 1.80 manpage. For example, the F<selection> extension (activated via
1032     C<@@RXVT_NAME@@ -pe selection>) listens for C<selection:rot13> events:
1033    
1034     URxvt.keysym.M-C-c: perl:selection:rot13
1035    
1036 root 1.63 Due the the large number of modifier combinations, a defined key mapping
1037     will match if at I<at least> the specified identifiers are being set, and
1038     no other key mappings with those and more bits are being defined. That
1039     means that defining a key map for C<a> will automatically provide
1040     definitions for C<Meta-a>, C<Shift-a> and so on, unless some of those are defined
1041     mappings themselves.
1042    
1043     Unfortunately, this will override built-in key mappings. For example
1044     if you overwrite the C<Insert> key you will disable @@RXVT_NAME@@'s
1045     C<Shift-Insert> mapping. To re-enable that, you can poke "holes" into the
1046     user-defined keymap using the C<builtin:> replacement:
1047    
1048     URxvt.keysym.Insert: <my insert key sequence>
1049     URxvt.keysym.S-Insert: builtin:
1050    
1051     The first line defines a mapping for C<Insert> and I<any> combination
1052     of modifiers. The second line re-establishes the default mapping for
1053     C<Shift-Insert>.
1054    
1055 root 1.48 The following example will map Control-Meta-1 and Control-Meta-2 to
1056     the fonts C<suxuseuro> and C<9x15bold>, so you can have some limited
1057     font-switching at runtime:
1058    
1059     URxvt.keysym.M-C-1: command:\033]50;suxuseuro\007
1060     URxvt.keysym.M-C-2: command:\033]50;9x15bold\007
1061    
1062     Other things are possible, e.g. resizing (see @@RXVT_NAME@@(7) for more
1063     info):
1064    
1065     URxvt.keysym.M-C-3: command:\033[8;25;80t
1066     URxvt.keysym.M-C-4: command:\033[8;48;110t
1067 root 1.1
1068 root 1.84 =item B<perl-ext-common>: I<string>
1069    
1070 root 1.78 =item B<perl-ext>: I<string>
1071 root 1.77
1072 root 1.88 Comma-separated list(s) of perl extension scripts (default: C<default>) to
1073     use in this terminal instance; option B<-pe>.
1074    
1075     Extension names can be prefixed with a C<-> sign to prohibit using
1076 root 1.91 them. This can be useful to selectively disable some extensions loaded
1077 root 1.88 by default, or specified via the C<perl-ext-common> resource. For
1078     example, C<default,-selection> will use all the default extension except
1079     C<selection>.
1080    
1081 root 1.91 Extension names can also be followed by an argument in angle brackets
1082     (e.g. C<< searchable-scrollback<M-s> >>, which binds the hotkey for
1083     searchable scorllback to Alt/Meta-s). Mentioning the same extension
1084     multiple times with different arguments will pass multiple arguments to
1085     the extension.
1086    
1087 root 1.88 Each extension is looked up in the library directories, loaded if
1088     necessary, and bound to the current terminal instance.
1089    
1090     If both of these resources are the empty string, then the perl
1091     interpreter will not be initialized. The idea behind two options is that
1092     B<perl-ext-common> will be used for extensions that should be available to
1093     all instances, while B<perl-ext> is used for specific instances.
1094 root 1.77
1095     =item B<perl-eval>: I<string>
1096    
1097 root 1.89 Perl code to be evaluated when all extensions have been registered. See
1098     the @@RXVT_NAME@@perl(3) manpage. Due to security reasons, this resource
1099     will be ignored when running setuid/setgid.
1100 root 1.77
1101     =item B<perl-lib>: I<path>
1102    
1103 root 1.78 Colon-separated list of additional directories that hold extension
1104     scripts. When looking for extensions specified by the C<perl> resource,
1105     @@RXVT_NAME@@ will first look in these directories and then in
1106 root 1.89 F<@@RXVT_LIBDIR@@/urxvt/perl/>. Due to security reasons, this resource
1107     will be ignored when running setuid/setgid.
1108 root 1.77
1109 root 1.81 See the @@RXVT_NAME@@perl(3) manpage.
1110 root 1.77
1111 root 1.95 =item B<< selection.pattern-I<idx> >>: I<perl-regex>
1112    
1113     Additional selection patterns, see the @@RXVT_NAME@@perl(3) manpage for
1114     details.
1115    
1116     =item B<< selection-autotransform.I<idx> >>: I<perl-transform>
1117    
1118     Selection auto-transform patterns, see the @@RXVT_NAME@@perl(3) manpage
1119     for details.
1120    
1121 root 1.94 =item B<searchable-scrollback:> I<keysym>
1122    
1123     Sets the hotkey that starts the incremental scrollback buffer search
1124     (default: C<M-s>).
1125    
1126 root 1.92 =item B<urlLauncher>: I<string>
1127    
1128     Specifies the program to be started with a URL argument. Used by the
1129     C<selection-popup> and C<mark-urls> perl extensions.
1130    
1131 root 1.90 =item B<transient-for>: I<windowid>
1132    
1133     Sets the WM_TRANSIENT_FOR property to the given window iw.
1134    
1135 root 1.1 =back
1136    
1137     =head1 THE SCROLLBAR
1138    
1139 root 1.2 Lines of text that scroll off the top of the B<@@RXVT_NAME@@> window
1140 root 1.1 (resource: B<saveLines>) and can be scrolled back using the scrollbar
1141 root 1.2 or by keystrokes. The normal B<@@RXVT_NAME@@> scrollbar has arrows and
1142 root 1.1 its behaviour is fairly intuitive. The B<xterm-scrollbar> is without
1143     arrows and its behaviour mimics that of I<xterm>
1144    
1145     Scroll down with B<Button1> (B<xterm-scrollbar>) or B<Shift-Next>.
1146     Scroll up with B<Button3> (B<xterm-scrollbar>) or B<Shift-Prior>.
1147     Continuous scroll with B<Button2>.
1148    
1149     =head1 MOUSE REPORTING
1150    
1151     To temporarily override mouse reporting, for either the scrollbar or
1152     the normal text selection/insertion, hold either the Shift or the Meta
1153     (Alt) key while performing the desired mouse action.
1154    
1155     If mouse reporting mode is active, the normal scrollbar actions are
1156     disabled -- on the assumption that we are using a fullscreen
1157 root 1.53 application. Instead, pressing Button1 and Button3 sends B<ESC [ 6 ~>
1158     (Next) and B<ESC [ 5 ~> (Prior), respectively. Similarly, clicking on the
1159     up and down arrows sends B<ESC [ A> (Up) and B<ESC [ B> (Down),
1160 root 1.1 respectively.
1161    
1162     =head1 TEXT SELECTION AND INSERTION
1163    
1164     The behaviour of text selection and insertion mechanism is similar to
1165     I<xterm>(1).
1166    
1167     =over 4
1168    
1169     =item B<Selection>:
1170    
1171 root 1.48 Left click at the beginning of the region, drag to the end of the region
1172     and release; Right click to extend the marked region; Left double-click
1173     to select a word; Left triple-click to select the entire logical line
1174     (which can span multiple screen lines), unless modified by resource
1175     B<tripleclickwords>.
1176 root 1.1
1177 root 1.30 Starting a selection while pressing the B<Meta> key (or B<Meta+Ctrl> keys)
1178 root 1.75 (Compile: I<frills>) will create a rectangular selection instead of a
1179     normal one. In this mode, every selected row becomes its own line in the
1180     selection, and trailing whitespace is visually underlined and removed from
1181     the selection.
1182 root 1.30
1183 root 1.1 =item B<Insertion>:
1184    
1185     Pressing and releasing the Middle mouse button (or B<Shift-Insert>) in
1186 root 1.2 an B<@@RXVT_NAME@@> window causes the current text selection to be
1187 root 1.1 inserted as if it had been typed on the keyboard.
1188    
1189     =back
1190    
1191     =head1 CHANGING FONTS
1192    
1193 root 1.12 Changing fonts (or font sizes, respectively) via the keypad is not yet
1194     supported in rxvt-unicode. Bug me if you need this.
1195    
1196 root 1.97 You can, however, switch fonts at runtime using escape sequences, e.g.:
1197 root 1.12
1198 root 1.72 printf '\e]710;%s\007' "9x15bold,xft:Kochi Gothic"
1199 root 1.12
1200 root 1.97 You can use keyboard shortcuts, too:
1201    
1202     URxvt.keysym.M-C-1: command:\033]710;suxuseuro\007\033]711;suxuseuro\007
1203     URxvt.keysym.M-C-2: command:\033]710;9x15bold\007\033]711;9x15bold\007
1204    
1205 root 1.12 rxvt-unicode will automatically re-apply these fonts to the output so far.
1206 root 1.1
1207 root 1.2 =head1 ISO 14755 SUPPORT
1208    
1209 root 1.12 ISO 14755 is a standard for entering and viewing unicode characters
1210     and character codes using the keyboard. It consists of 4 parts. The
1211     first part is available rxvt-unicode has been compiled with
1212     C<--enable-frills>, the rest is available when rxvt-unicode was compiled
1213     with C<--enable-iso14755>.
1214    
1215     =over 4
1216    
1217 root 1.48 =item * 5.1: Basic method
1218 root 1.12
1219     This allows you to enter unicode characters using their hexcode.
1220 root 1.2
1221 root 1.12 Start by pressing and holding both C<Control> and C<Shift>, then enter
1222     hex-digits (between one and six). Releasing C<Control> and C<Shift> will
1223     commit the character as if it were typed directly. While holding down
1224     C<Control> and C<Shift> you can also enter multiple characters by pressing
1225     C<Space>, which will commit the current character and lets you start a new
1226     one.
1227    
1228     As an example of use, imagine a business card with a japanese e-mail
1229     address, which you cannot type. Fortunately, the card has the e-mail
1230     address printed as hexcodes, e.g. C<671d 65e5>. You can enter this easily
1231     by pressing C<Control> and C<Shift>, followed by C<6-7-1-D-SPACE-6-5-E-5>,
1232     followed by releasing the modifier keys.
1233    
1234 root 1.48 =item * 5.2: Keyboard symbols entry method
1235 root 1.12
1236     This mode lets you input characters representing the keycap symbols of
1237     your keyboard, if representable in the current locale encoding.
1238    
1239     Start by pressing C<Control> and C<Shift> together, then releasing
1240     them. The next special key (cursor keys, home etc.) you enter will not
1241     invoke it's usual function but instead will insert the corresponding
1242     keycap symbol. The symbol will only be entered when the key has been
1243     released, otherwise pressing e.g. C<Shift> would enter the symbol for
1244 root 1.30 C<ISO Level 2 Switch>, although your intention might have been to enter a
1245 root 1.12 reverse tab (Shift-Tab).
1246    
1247 root 1.48 =item * 5.3: Screen-selection entry method
1248 root 1.12
1249     While this is implemented already (it's basically the selection
1250     mechanism), it could be extended by displaying a unicode character map.
1251    
1252 root 1.48 =item * 5.4: Feedback method for identifying displayed characters for later input
1253 root 1.12
1254     This method lets you display the unicode character code associated with
1255     characters already displayed.
1256    
1257     You enter this mode by holding down C<Control> and C<Shift> together, then
1258     pressing and holding the left mouse button and moving around. The unicode
1259     hex code(s) (it might be a combining character) of the character under the
1260     pointer is displayed until you release C<Control> and C<Shift>.
1261    
1262 root 1.22 In addition to the hex codes it will display the font used to draw this
1263     character - due to implementation reasons, characters combined with
1264     combining characters, line drawing characters and unknown characters will
1265     always be drawn using the built-in support font.
1266    
1267 root 1.12 =back
1268    
1269     With respect to conformance, rxvt-unicode is supposed to be compliant to
1270     both scenario A and B of ISO 14755, including part 5.2.
1271 root 1.2
1272 root 1.1 =head1 LOGIN STAMP
1273    
1274 root 1.48 B<@@RXVT_NAME@@> tries to write an entry into the I<utmp>(5) file so that
1275     it can be seen via the I<who(1)> command, and can accept messages. To
1276     allow this feature, B<@@RXVT_NAME@@> may need to be installed setuid root
1277     on some systems or setgid to root or to some other group on others.
1278 root 1.1
1279     =head1 COLORS AND GRAPHICS
1280    
1281     In addition to the default foreground and background colours,
1282 root 1.2 B<@@RXVT_NAME@@> can display up to 16 colours (8 ANSI colours plus
1283 root 1.1 high-intensity bold/blink versions of the same). Here is a list of the
1284     colours with their B<rgb.txt> names.
1285    
1286     =begin table
1287    
1288     B<color0> (black) = Black
1289     B<color1> (red) = Red3
1290     B<color2> (green) = Green3
1291     B<color3> (yellow) = Yellow3
1292     B<color4> (blue) = Blue3
1293     B<color5> (magenta) = Magenta3
1294     B<color6> (cyan) = Cyan3
1295     B<color7> (white) = AntiqueWhite
1296     B<color8> (bright black) = Grey25
1297     B<color9> (bright red) = Red
1298     B<color10> (bright green) = Green
1299     B<color11> (bright yellow) = Yellow
1300     B<color12> (bright blue) = Blue
1301     B<color13> (bright magenta) = Magenta
1302     B<color14> (bright cyan) = Cyan
1303     B<color15> (bright white) = White
1304     B<foreground> = Black
1305     B<background> = White
1306    
1307     =end table
1308    
1309     It is also possible to specify the colour values of B<foreground>,
1310     B<background>, B<cursorColor>, B<cursorColor2>, B<colorBD>, B<colorUL> as
1311     a number 0-15, as a convenient shorthand to reference the colour name of
1312     color0-color15.
1313    
1314     Note that B<-rv> (B<"reverseVideo: True">) simulates reverse video by
1315     always swapping the foreground/background colours. This is in contrast to
1316     I<xterm>(1) where the colours are only swapped if they have not otherwise
1317     been specified. For example,
1318    
1319     =over 4
1320    
1321 root 1.3 =item B<@@RXVT_NAME@@ -fg Black -bg White -rv>
1322 root 1.1
1323     would yield White on Black, while on I<xterm>(1) it would yield Black
1324     on White.
1325    
1326     =back
1327    
1328 root 1.5 =head1 ENVIRONMENT
1329    
1330 root 1.53 B<@@RXVT_NAME@@> sets and/or uses the following environment variables:
1331    
1332     =over 4
1333    
1334     =item B<TERM>
1335    
1336     Normally set to C<rxvt-unicode>, unless overwritten at configure time, via
1337     resources or on the commandline.
1338    
1339     =item B<COLORTERM>
1340    
1341     Either C<rxvt>, C<rxvt-xpm>, depending on wether @@RXVT_NAME@@ was
1342     compiled with XPM support, and optionally with the added extension
1343     C<-mono> to indicate that rxvt-unicode runs on a monochrome screen.
1344    
1345     =item B<COLORFGBG>
1346    
1347     Set to a string of the form C<fg;bg> or C<fg;xpm;bg>, where C<fg> is
1348     the colour code used as default foreground/text colour (or the string
1349     C<default> to indicate that the default-colour escape sequence is to be
1350     used), C<bg> is the colour code used as default background colour (or the
1351     string C<default>), and C<xpm> is the string C<default> if @@RXVT_NAME@@
1352 root 1.54 was compiled with XPM support. Libraries like C<ncurses> and C<slang> can
1353     (and do) use this information to optimize screen output.
1354 root 1.53
1355     =item B<WINDOWID>
1356    
1357     Set to the (decimal) X Window ID of the @@RXVT_NAME@@ window (the toplevel
1358     window, which usually has subwindows for the scrollbar, the terminal
1359     window and so on).
1360    
1361     =item B<TERMINFO>
1362    
1363     Set to the terminfo directory iff @@RXVT_NAME@@ was configured with
1364     C<--with-terminfo=PATH>.
1365    
1366     =item B<DISPLAY>
1367    
1368     Used by @@RXVT_NAME@@ to connect to the display and set to the correct
1369     display in it's child processes.
1370    
1371     =item B<SHELL>
1372    
1373     The shell to be used for command execution, defaults to C</bin/sh>.
1374    
1375     =item B<RXVT_SOCKET>
1376    
1377     The unix domain socket path used by @@RXVT_NAME@@c(1) and
1378     @@RXVT_NAME@@d(1).
1379    
1380 root 1.67 Default F<<< $HOME/.rxvt-unicode-I<< <nodename >> >>>.
1381 root 1.53
1382     =item B<HOME>
1383    
1384     Used to locate the default directory for the unix domain socket for
1385     daemon communications and to locate various resource files (such as
1386     C<.Xdefaults>)
1387    
1388     =item B<XAPPLRESDIR>
1389    
1390     Directory where various X resource files are being located.
1391    
1392     =item B<XENVIRONMENT>
1393    
1394     If set and accessible, gives the name of a X resource file to be loaded by
1395     @@RXVT_NAME@@.
1396    
1397     =back
1398 root 1.5
1399     =head1 FILES
1400    
1401     =over 4
1402    
1403     =item B</usr/lib/X11/rgb.txt>
1404    
1405     Color names.
1406 root 1.3
1407     =back
1408    
1409     =head1 SEE ALSO
1410 root 1.1
1411 root 1.67 @@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)
1412 root 1.1
1413     =head1 CURRENT PROJECT COORDINATOR
1414    
1415     =over 4
1416    
1417     =item Project Coordinator
1418    
1419 root 1.55 Marc A. Lehmann L<< <rxvt-unicode@schmorp.de> >>
1420 root 1.1
1421 root 1.55 L<http://software.schmorp.de/#rxvt-unicode>
1422 root 1.1
1423     =back
1424    
1425     =head1 AUTHORS
1426    
1427     =over 4
1428    
1429     =item John Bovey
1430    
1431     University of Kent, 1992, wrote the original Xvt.
1432    
1433     =item Rob Nation L<< <nation@rocket.sanders.lockheed.com> >>
1434    
1435     very heavily modified Xvt and came up with Rxvt
1436    
1437     =item Angelo Haritsis L<< <ah@doc.ic.ac.uk> >>
1438    
1439     wrote the Greek Keyboard Input (no longer in code)
1440    
1441     =item mj olesen L<< <olesen@me.QueensU.CA> >>
1442    
1443     Wrote the menu system.
1444    
1445     Project Coordinator (changes.txt 2.11 to 2.21)
1446    
1447     =item Oezguer Kesim L<< <kesim@math.fu-berlin.de> >>
1448    
1449     Project Coordinator (changes.txt 2.21a to 2.4.5)
1450    
1451     =item Geoff Wing L<< <gcw@pobox.com> >>
1452    
1453     Rewrote screen display and text selection routines. Project Coordinator
1454     (changes.txt 2.4.6 - rxvt-unicode)
1455    
1456 root 1.55 =item Marc Alexander Lehmann L<< <rxvt-unicode@schmorp.de> >>
1457 root 1.1
1458     Forked rxvt-unicode, rewrote most of the display code and internal
1459     character handling to store text in unicode, improve xterm
1460     compatibility and apply numerous other bugfixes and extensions.
1461    
1462     Project Coordinator (Changes 1.0 -)
1463    
1464     =back
1465