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.48 by root, Thu Feb 3 10:24:10 2005 UTC vs.
Revision 1.69 by root, Tue Oct 25 19:04:45 2005 UTC

14configurability. As a result, B<rxvt-unicode> uses much less swap space -- 14configurability. As a result, B<rxvt-unicode> uses much less swap space --
15a significant advantage on a machine serving many X sessions. 15a significant advantage on a machine serving many X sessions.
16 16
17=head1 FREQUENTLY ASKED QUESTIONS 17=head1 FREQUENTLY ASKED QUESTIONS
18 18
19See @@RXVT_NAME@@(7) (try C<man 7 @@RXVT_NAME@@>) for a list of frequently 19See @@RXVT_NAME@@(7) (try C<man 7 @@RXVT_NAME@@>) for a list of
20asked questions and answer to them and some common problems. 20frequently asked questions and answer to them and some common
21problems. That document is also accessible on the World-Wide-Web at
22L<http://cvs.schmorp.de/browse/*checkout*/rxvt-unicode/doc/rxvt.7.html>.
21 23
22=head1 RXVT-UNICODE VS. RXVT 24=head1 RXVT-UNICODE VS. RXVT
23 25
24Unlike the original rxvt, B<rxvt-unicode> stores all text in Unicode 26Unlike the original rxvt, B<rxvt-unicode> stores all text in Unicode
25internally. That means it can store and display most scripts in the 27internally. That means it can store and display most scripts in the
103 105
104=item B<-j>|B<+j> 106=item B<-j>|B<+j>
105 107
106Turn on/off jump scrolling; resource B<jumpScroll>. 108Turn on/off jump scrolling; resource B<jumpScroll>.
107 109
108=item B<-ip>|B<+ip> 110=item B<-ip>|B<+ip> | B<-tr>|B<+tr>
109 111
110Turn on/off inheriting parent window's pixmap. Alternative form is 112Turn on/off inheriting parent window's pixmap. Alternative form is
111B<-tr>; resource B<inheritPixmap>. 113B<-tr>; resource B<inheritPixmap>.
112 114
113=item B<-fade> I<number> 115=item B<-fade> I<number>
114 116
115Fade the text by the given percentage when focus is lost. resource B<fading>. 117Fade the text by the given percentage when focus is lost. Small values
118fade a little only, 100 completely replaces all colours by the fade
119colour; resource B<fading>.
120
121=item B<-fadecolor> I<colour>
122
123Fade to this colour when fading is used (see B<-fade>). The default colour
124is black. resource B<fadeColor>.
116 125
117=item B<-tint> I<colour> 126=item B<-tint> I<colour>
118 127
119Tint the transparent background pixmap with the given colour when 128Tint the transparent background pixmap with the given colour when
120transparency is enabled with B<-tr> or B<-ip>. See also the B<-sh> 129transparency is enabled with B<-tr> or B<-ip>. See also the B<-sh>
121option that can be used to brighten or darken the image in addition to 130option that can be used to brighten or darken the image in addition to
122tinting it. 131tinting it; resource I<tintColor>. Example:
132
133 @@RXVT_NAME@@ -tr -tint blue -sh 40
123 134
124=item B<-sh> 135=item B<-sh>
125 136
126I<number> Darken (0 .. 100) or lighten (-1 .. -100) the transparent 137I<number> Darken (0 .. 100) or lighten (-1 .. -100) the transparent
127background image in addition to tinting it (i.e. B<-tint> must be 138background image in addition to tinting it (i.e. B<-tint> must be
236 247
237Put scrollbar on right/left; resource B<scrollBar_right>. 248Put scrollbar on right/left; resource B<scrollBar_right>.
238 249
239=item B<-st>|B<+st> 250=item B<-st>|B<+st>
240 251
241Display normal (non XTerm/NeXT) scrollbar without/with a trough; 252Display rxvt (non XTerm/NeXT) scrollbar without/with a trough;
242resource B<scrollBar_floating>. 253resource B<scrollBar_floating>.
243 254
244=item B<-ptab>|B<+ptab> 255=item B<-ptab>|B<+ptab>
245 256
246If enabled (default), "Horizontal Tab" characters are being stored as 257If enabled (default), "Horizontal Tab" characters are being stored as
366=item B<-ssr>|B<+ssr> 377=item B<-ssr>|B<+ssr>
367 378
368Turn on/off secondary screen scroll (default enabled); resource 379Turn on/off secondary screen scroll (default enabled); resource
369B<secondaryScroll>. 380B<secondaryScroll>.
370 381
371=item B<-xrm> I<resourcestring> 382=item B<-keysym.>I<sym> I<string>
372 383
373No effect on rxvt-unicode. Simply passes through an argument to be made 384Remap a key symbol. See resource B<keysym>.
374available in the instance's argument list. Appears in I<WM_COMMAND> in 385
375some window managers. 386=item B<-embed> I<windowid>
387
388Tells @@RXVT_NAME@@ to embed it's windows into an already-existing window,
389which enables applications to easily embed a terminal.
390
391Right now, @@RXVT_NAME@@ will first unmap/map the specified window, so it
392shouldn't be a top-level window. @@RXVT_NAME@@ will also reconfigure it
393quite a bit, so don't expect it to keep some specific state. It's best to
394create an extra subwindow for @@RXVT_NAME@@ and leave it alone.
395
396The window will not be destroyed when @@RXVT_NAME@@ exits.
397
398It might be useful to know that @@RXVT_NAME@@ will not close file
399descriptors passed to it (except for stdin/out/err, of course), so you
400can use file descriptors to communicate with the programs within the
401terminal. This works regardless of wether the C<-embed> option was used or
402not.
403
404Here is a short Gtk2-perl snippet that illustrates how this option can be
405used (a longer example is in F<doc/embed>):
406
407 my $rxvt = new Gtk2::Socket;
408 $rxvt->signal_connect_after (realize => sub {
409 my $xid = $_[0]->window->get_xid;
410 system "@@RXVT_NAME@@ -embed $xid &";
411 });
412
413=item B<-pty-fd> I<fileno>
414
415Tells @@RXVT_NAME@@ NOT to execute any commands or create a new pty/tty
416pair but instead use the given filehandle as the tty master. This is
417useful if you want to drive @@RXVT_NAME@@ as a generic terminal emulator
418without having to run a program within it.
419
420If this switch is given, @@RXVT_NAME@@ will not create any utmp/wtmp
421entries and will not tinker with pty/tty permissions - you have to do that
422yourself if you want that.
423
424Here is a example in perl that illustrates how this option can be used (a
425longer example is in F<doc/pty-fd>):
426
427 use IO::Pty;
428 use Fcntl;
429
430 my $pty = new IO::Pty;
431 fcntl $pty, F_SETFD, 0; # clear close-on-exec
432 system "@@RXVT_NAME@@ -pty-fd " . (fileno $pty) . "&";
433 close $pty;
434
435 # now communicate with rxvt
436 my $slave = $pty->slave;
437 while (<$slave>) { print $slave "got <$_>\n" }
376 438
377=back 439=back
378 440
379=head1 RESOURCES (available also as long-options) 441=head1 RESOURCES (available also as long-options)
380 442
383 445
384There are two different methods that @@RXVT_NAME@@ can use to get the 446There are two different methods that @@RXVT_NAME@@ can use to get the
385Xresource data: using the X libraries (Xrm*-functions) or internal 447Xresource data: using the X libraries (Xrm*-functions) or internal
386Xresources reader (B<~/.Xdefaults>). For the first method (ie. 448Xresources reader (B<~/.Xdefaults>). For the first method (ie.
387B<@@RXVT_NAME@@ -h> lists B<XGetDefaults>), you can set and change the 449B<@@RXVT_NAME@@ -h> lists B<XGetDefaults>), you can set and change the
388resources using X11 tools like B<xset>. Many distribution do also load 450resources using X11 tools like B<xrdb>. Many distribution do also load
389settings from the B<~/.Xresources> file when X starts. 451settings from the B<~/.Xresources> file when X starts. @@RXVT_NAME@@
452will consult the following files/resources in order, with later settings
453overwriting earlier ones:
454
455 1. system-wide app-defaults file, either locale-dependent OR global
456 2. app-defaults file in $XAPPLRESDIR
457 3. RESOURCE_MANAGER property on root-window OR $HOME/.Xdefaults
458 4. SCREEN_RESOURCES for the current screen
459 5. $XENVIRONMENT file OR $HOME/.Xdefaults-<nodename>
390 460
391If compiled with internal Xresources support (i.e. B<@@RXVT_NAME@@ -h> 461If compiled with internal Xresources support (i.e. B<@@RXVT_NAME@@ -h>
392lists B<.Xdefaults>) then B<@@RXVT_NAME@@> accepts application defaults 462lists B<.Xdefaults>) then B<@@RXVT_NAME@@> accepts application defaults
393set in XAPPLOADDIR/URxvt (compile-time defined: usually 463set in XAPPLOADDIR/URxvt (compile-time defined: usually
394B</usr/lib/X11/app-defaults/URxvt>) and resources set in 464B</usr/lib/X11/app-defaults/URxvt>) and resources set in
487artificial transparency. B<False>: do not inherit the parent windows' 557artificial transparency. B<False>: do not inherit the parent windows'
488pixmap. 558pixmap.
489 559
490=item B<fading:> I<number> 560=item B<fading:> I<number>
491 561
492Fade the text by the given percentage when focus is lost. 562Fade the text by the given percentage when focus is lost; option B<-fade>.
563
564=item B<fadeColor:> I<colour>
565
566Fade to this colour, when fading is used (see B<fading:>). The default
567colour is black; option B<-fadecolor>.
493 568
494=item B<tintColor:> I<colour> 569=item B<tintColor:> I<colour>
495 570
496Tint the transparent background pixmap with the given colour. 571Tint the transparent background pixmap with the given colour; option
572B<-tint>.
497 573
498=item B<shading:> I<number> 574=item B<shading:> I<number>
499 575
500Darken (0 .. 100) or lighten (-1 .. -100) the transparent background 576Darken (0 .. 100) or lighten (-1 .. -100) the transparent background
501image in addition to tinting it. 577image in addition to tinting it.
505Use the specified colour for the scrollbar [default #B2B2B2]. 581Use the specified colour for the scrollbar [default #B2B2B2].
506 582
507=item B<troughColor:> I<colour> 583=item B<troughColor:> I<colour>
508 584
509Use the specified colour for the scrollbar's trough area [default 585Use the specified colour for the scrollbar's trough area [default
510#969696]. Only relevant for normal (non XTerm/NeXT) scrollbar. 586#969696]. Only relevant for rxvt (non XTerm/NeXT) scrollbar.
511 587
512=item B<borderColor:> I<colour> 588=item B<borderColor:> I<colour>
513 589
514The colour of the border around the text area and between the scrollbar 590The colour of the border around the text area and between the scrollbar
515and the text. 591and the text.
607xterm style selection. 683xterm style selection.
608 684
609=item B<scrollstyle:> I<mode> 685=item B<scrollstyle:> I<mode>
610 686
611Set scrollbar style to B<rxvt>, B<plain>, B<next> or B<xterm>. B<plain> is 687Set scrollbar style to B<rxvt>, B<plain>, B<next> or B<xterm>. B<plain> is
612the author's favourite.. 688the author's favourite.
613 689
614=item B<title:> I<string> 690=item B<title:> I<string>
615 691
616Set window title string, the default title is the command-line 692Set window title string, the default title is the command-line
617specified after the B<-e> option, if any, otherwise the application 693specified after the B<-e> option, if any, otherwise the application
649 725
650Specify a command pipe for vt100 printer [default I<lpr(1)>]. Use 726Specify a command pipe for vt100 printer [default I<lpr(1)>]. Use
651B<Print> to initiate a screen dump to the printer and B<Ctrl-Print> or 727B<Print> to initiate a screen dump to the printer and B<Ctrl-Print> or
652B<Shift-Print> to include the scrollback as well. 728B<Shift-Print> to include the scrollback as well.
653 729
730The string will be interpreted as if typed into the shell as-is.
731
732Example:
733
734 URxvt*print-pipe: cat > $(TMPDIR=$HOME mktemp urxvt.XXXXXX)
735
736This creates a new file in your home directory with the screen contents
737everytime you hit C<Print>.
738
654=item B<scrollBar:> I<boolean> 739=item B<scrollBar:> I<boolean>
655 740
656B<True>: enable the scrollbar [default]; option B<-sb>. B<False>: 741B<True>: enable the scrollbar [default]; option B<-sb>. B<False>:
657disable the scrollbar; option B<+sb>. 742disable the scrollbar; option B<+sb>.
658 743
678B<+si>. 763B<+si>.
679 764
680=item B<scrollWithBuffer:> I<boolean> 765=item B<scrollWithBuffer:> I<boolean>
681 766
682B<True>: scroll with scrollback buffer when tty receives new lines (and 767B<True>: scroll with scrollback buffer when tty receives new lines (and
683B<scrollTtyOutput> is False); option B<+sw>. B<False>: do not scroll 768B<scrollTtyOutput> is False); option B<-sw>. B<False>: do not scroll
684with scrollback buffer when tty recieves new lines; option B<-sw>. 769with scrollback buffer when tty recieves new lines; option B<+sw>.
685 770
686=item B<scrollTtyKeypress:> I<boolean> 771=item B<scrollTtyKeypress:> I<boolean>
687 772
688B<True>: scroll to bottom when a non-special key is pressed. Special keys 773B<True>: scroll to bottom when a non-special key is pressed. Special keys
689are those which are intercepted by rxvt-unicode for special handling and 774are those which are intercepted by rxvt-unicode for special handling and
754 839
755Mouse pointer background colour. 840Mouse pointer background colour.
756 841
757=item B<pointerBlankDelay:> I<number> 842=item B<pointerBlankDelay:> I<number>
758 843
759Specifies number of seconds before blanking the pointer [default 2]. 844Specifies number of seconds before blanking the pointer [default 2]. Use a
845large number (e.g. C<987654321>) to effectively disable the timeout.
760 846
761=item B<backspacekey:> I<string> 847=item B<backspacekey:> I<string>
762 848
763The string to send when the backspace key is pressed. If set to B<DEC> 849The string to send when the backspace key is pressed. If set to B<DEC>
764or unset it will send B<Delete> (code 127) or, if shifted, B<Backspace> 850or unset it will send B<Delete> (code 127) or, if shifted, B<Backspace>
896example the following means "change the current locale to C<zh_CN.GBK> 982example the following means "change the current locale to C<zh_CN.GBK>
897when Control-Meta-c is being pressed": 983when Control-Meta-c is being pressed":
898 984
899 URxvt.keysym.M-C-c: command:\033]701;zh_CN.GBK\007 985 URxvt.keysym.M-C-c: command:\033]701;zh_CN.GBK\007
900 986
987Due the the large number of modifier combinations, a defined key mapping
988will match if at I<at least> the specified identifiers are being set, and
989no other key mappings with those and more bits are being defined. That
990means that defining a key map for C<a> will automatically provide
991definitions for C<Meta-a>, C<Shift-a> and so on, unless some of those are defined
992mappings themselves.
993
994Unfortunately, this will override built-in key mappings. For example
995if you overwrite the C<Insert> key you will disable @@RXVT_NAME@@'s
996C<Shift-Insert> mapping. To re-enable that, you can poke "holes" into the
997user-defined keymap using the C<builtin:> replacement:
998
999 URxvt.keysym.Insert: <my insert key sequence>
1000 URxvt.keysym.S-Insert: builtin:
1001
1002The first line defines a mapping for C<Insert> and I<any> combination
1003of modifiers. The second line re-establishes the default mapping for
1004C<Shift-Insert>.
1005
901The following example will map Control-Meta-1 and Control-Meta-2 to 1006The 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 1007the fonts C<suxuseuro> and C<9x15bold>, so you can have some limited
903font-switching at runtime: 1008font-switching at runtime:
904 1009
905 URxvt.keysym.M-C-1: command:\033]50;suxuseuro\007 1010 URxvt.keysym.M-C-1: command:\033]50;suxuseuro\007
931the normal text selection/insertion, hold either the Shift or the Meta 1036the normal text selection/insertion, hold either the Shift or the Meta
932(Alt) key while performing the desired mouse action. 1037(Alt) key while performing the desired mouse action.
933 1038
934If mouse reporting mode is active, the normal scrollbar actions are 1039If mouse reporting mode is active, the normal scrollbar actions are
935disabled -- on the assumption that we are using a fullscreen 1040disabled -- on the assumption that we are using a fullscreen
936application. Instead, pressing Button1 and Button3 sends B<ESC[6~> 1041application. Instead, pressing Button1 and Button3 sends B<ESC [ 6 ~>
937(Next) and B<ESC[5~> (Prior), respectively. Similarly, clicking on the 1042(Next) and B<ESC [ 5 ~> (Prior), respectively. Similarly, clicking on the
938up and down arrows sends B<ESC[A> (Up) and B<ESC[B> (Down), 1043up and down arrows sends B<ESC [ A> (Up) and B<ESC [ B> (Down),
939respectively. 1044respectively.
940 1045
941=head1 TEXT SELECTION AND INSERTION 1046=head1 TEXT SELECTION AND INSERTION
942 1047
943The behaviour of text selection and insertion mechanism is similar to 1048The behaviour of text selection and insertion mechanism is similar to
1098 1203
1099=back 1204=back
1100 1205
1101=head1 ENVIRONMENT 1206=head1 ENVIRONMENT
1102 1207
1103B<@@RXVT_NAME@@> sets the environment variables B<TERM>, B<COLORTERM> 1208B<@@RXVT_NAME@@> sets and/or uses the following environment variables:
1104and B<COLORFGBG>. The environment variable B<WINDOWID> is set to the X 1209
1105window id number of the B<@@RXVT_NAME@@> window and it also uses and 1210=over 4
1106sets the environment variable B<DISPLAY> to specify which display 1211
1107terminal to use. B<@@RXVT_NAME@@> uses the environment variables 1212=item B<TERM>
1108B<RXVTPATH> and B<PATH> to find XPM files. 1213
1214Normally set to C<rxvt-unicode>, unless overwritten at configure time, via
1215resources or on the commandline.
1216
1217=item B<COLORTERM>
1218
1219Either C<rxvt>, C<rxvt-xpm>, depending on wether @@RXVT_NAME@@ was
1220compiled with XPM support, and optionally with the added extension
1221C<-mono> to indicate that rxvt-unicode runs on a monochrome screen.
1222
1223=item B<COLORFGBG>
1224
1225Set to a string of the form C<fg;bg> or C<fg;xpm;bg>, where C<fg> is
1226the colour code used as default foreground/text colour (or the string
1227C<default> to indicate that the default-colour escape sequence is to be
1228used), C<bg> is the colour code used as default background colour (or the
1229string C<default>), and C<xpm> is the string C<default> if @@RXVT_NAME@@
1230was compiled with XPM support. Libraries like C<ncurses> and C<slang> can
1231(and do) use this information to optimize screen output.
1232
1233=item B<WINDOWID>
1234
1235Set to the (decimal) X Window ID of the @@RXVT_NAME@@ window (the toplevel
1236window, which usually has subwindows for the scrollbar, the terminal
1237window and so on).
1238
1239=item B<TERMINFO>
1240
1241Set to the terminfo directory iff @@RXVT_NAME@@ was configured with
1242C<--with-terminfo=PATH>.
1243
1244=item B<DISPLAY>
1245
1246Used by @@RXVT_NAME@@ to connect to the display and set to the correct
1247display in it's child processes.
1248
1249=item B<SHELL>
1250
1251The shell to be used for command execution, defaults to C</bin/sh>.
1252
1253=item B<RXVTPATH>
1254
1255The path where @@RXVT_NAME@@ looks for support files such as menu and xpm
1256files.
1257
1258=item B<PATH>
1259
1260Used in the same way as C<RXVTPATH>.
1261
1262=item B<RXVT_SOCKET>
1263
1264The unix domain socket path used by @@RXVT_NAME@@c(1) and
1265@@RXVT_NAME@@d(1).
1266
1267Default F<<< $HOME/.rxvt-unicode-I<< <nodename >> >>>.
1268
1269=item B<HOME>
1270
1271Used to locate the default directory for the unix domain socket for
1272daemon communications and to locate various resource files (such as
1273C<.Xdefaults>)
1274
1275=item B<XAPPLRESDIR>
1276
1277Directory where various X resource files are being located.
1278
1279=item B<XENVIRONMENT>
1280
1281If set and accessible, gives the name of a X resource file to be loaded by
1282@@RXVT_NAME@@.
1283
1284=back
1109 1285
1110=head1 FILES 1286=head1 FILES
1111 1287
1112=over 4 1288=over 4
1113 1289
1117 1293
1118=back 1294=back
1119 1295
1120=head1 SEE ALSO 1296=head1 SEE ALSO
1121 1297
1122@@RXVT_NAME@@(7), xterm(1), sh(1), resize(1), X(1), pty(4), tty(4), utmp(5) 1298@@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)
1123 1299
1124=head1 BUGS 1300=head1 BUGS
1125 1301
1126Check the BUGS file for an up-to-date list. 1302Check the BUGS file for an up-to-date list.
1127 1303
1133 1309
1134=over 4 1310=over 4
1135 1311
1136=item Project Coordinator 1312=item Project Coordinator
1137 1313
1138@@RXVT_MAINT@@ L<@@RXVT_MAINTEMAIL@@> 1314Marc A. Lehmann L<< <rxvt-unicode@schmorp.de> >>
1139 1315
1140=item Web page maintainter 1316L<http://software.schmorp.de/#rxvt-unicode>
1141
1142@@RXVT_WEBMAINT@@ L<@@RXVT_WEBMAINTEMAIL@@>
1143
1144L<@@RXVT_WEBPAGE@@>
1145 1317
1146=back 1318=back
1147 1319
1148=head1 AUTHORS 1320=head1 AUTHORS
1149 1321
1174=item Geoff Wing L<< <gcw@pobox.com> >> 1346=item Geoff Wing L<< <gcw@pobox.com> >>
1175 1347
1176Rewrote screen display and text selection routines. Project Coordinator 1348Rewrote screen display and text selection routines. Project Coordinator
1177(changes.txt 2.4.6 - rxvt-unicode) 1349(changes.txt 2.4.6 - rxvt-unicode)
1178 1350
1179=item Marc Alexander Lehmann L<< <rxvt@schmorp.de> >> 1351=item Marc Alexander Lehmann L<< <rxvt-unicode@schmorp.de> >>
1180 1352
1181Forked rxvt-unicode, rewrote most of the display code and internal 1353Forked rxvt-unicode, rewrote most of the display code and internal
1182character handling to store text in unicode, improve xterm 1354character handling to store text in unicode, improve xterm
1183compatibility and apply numerous other bugfixes and extensions. 1355compatibility and apply numerous other bugfixes and extensions.
1184 1356

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines