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

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines