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.144 by sasha, Thu Nov 15 18:40:10 2007 UTC vs.
Revision 1.159 by root, Wed Jan 23 14:34:00 2008 UTC

12emulator intended as an I<xterm>(1) replacement for users who do not 12emulator intended as an I<xterm>(1) replacement for users who do not
13require features such as Tektronix 4014 emulation and toolkit-style 13require features such as Tektronix 4014 emulation and toolkit-style
14configurability. As a result, B<rxvt-unicode> uses much less swap space -- 14configurability. As a result, B<rxvt-unicode> uses much less swap space --
15a significant advantage on a machine serving many X sessions. 15a significant advantage on a machine serving many X sessions.
16 16
17This document is also available on the World-Wide-Web at
18L<http://pod.tst.eu/http://cvs.schmorp.de/rxvt-unicode/doc/rxvt.1.pod>.
19
17=head1 FREQUENTLY ASKED QUESTIONS 20=head1 FREQUENTLY ASKED QUESTIONS
18 21
19See @@RXVT_NAME@@(7) (try C<man 7 @@RXVT_NAME@@>) for a list of 22See @@RXVT_NAME@@(7) (try C<man 7 @@RXVT_NAME@@>) for a list of
20frequently asked questions and answer to them and some common 23frequently asked questions and answer to them and some common
21problems. That document is also accessible on the World-Wide-Web at 24problems. That document is also accessible on the World-Wide-Web at
22L<http://cvs.schmorp.de/browse/rxvt-unicode/doc/rxvt.7.html>. 25L<http://pod.tst.eu/http://cvs.schmorp.de/rxvt-unicode/doc/rxvt.7.pod>.
23 26
24=head1 RXVT-UNICODE VS. RXVT 27=head1 RXVT-UNICODE VS. RXVT
25 28
26Unlike the original rxvt, B<rxvt-unicode> stores all text in Unicode 29Unlike the original rxvt, B<rxvt-unicode> stores all text in Unicode
27internally. That means it can store and display most scripts in the 30internally. That means it can store and display most scripts in the
30like mongolian or scripts requiring extremely complex combining rules, 33like mongolian or scripts requiring extremely complex combining rules,
31like tibetan or devanagari. Don't expect pretty output when using these 34like tibetan or devanagari. Don't expect pretty output when using these
32scripts. Most other scripts, latin, cyrillic, kanji, thai etc. should work 35scripts. Most other scripts, latin, cyrillic, kanji, thai etc. should work
33fine, though. A somewhat difficult case are right-to-left scripts, such 36fine, though. A somewhat difficult case are right-to-left scripts, such
34as hebrew: B<rxvt-unicode> adopts the view that bidirectional algorithms 37as hebrew: B<rxvt-unicode> adopts the view that bidirectional algorithms
35belong into the application, not the terminal emulator (too many things -- 38belong in the application, not the terminal emulator (too many things --
36such as cursor-movement while editing -- break otherwise), but that might 39such as cursor-movement while editing -- break otherwise), but that might
37change. 40change.
38 41
39If you are looking for a terminal that supports more exotic scripts, let 42If you are looking for a terminal that supports more exotic scripts, let
40me recommend C<mlterm>, which is a very user friendly, lean and clean 43me recommend C<mlterm>, which is a very user friendly, lean and clean
116 119
117Turn on/off skip scrolling (allow multiple screens per refresh); resource B<skipScroll>. 120Turn on/off skip scrolling (allow multiple screens per refresh); resource B<skipScroll>.
118 121
119=item B<-tr>|B<+tr> 122=item B<-tr>|B<+tr>
120 123
121Turn on/off illusion of a transparent window background. Obsolete form of it is 124Turn on/off illusion of a transparent window background; resource B<transparent>.
122B<-ip> and it should not be used anymore; resource B<transparent>.
123 125
124I<Please note that old resource name of B<inheritPixmap> is obsolete and should be 126B<-ip> is still accepted as an obsolete alias but will be removed in
125changed to B<transparent>. Backwards compatibility support for B<inheritPixmap> will 127future versions.
126be phased out in future versions of rxvt!>
127 128
128I<Please address all transparency related issues to Sasha Vasko at 129I<Please address all transparency related issues to Sasha Vasko at
129sasha@aftercode.net. Read the FAQ (man 7 @@RXVT_NAME@@)!> 130sasha@aftercode.net. Read the FAQ (man 7 @@RXVT_NAME@@)!>
130 131
131=item B<-fade> I<number> 132=item B<-fade> I<number>
244italic> >> characters are to be printed. See resource B<boldItalicFont> 245italic> >> characters are to be printed. See resource B<boldItalicFont>
245for details. 246for details.
246 247
247=item B<-is>|B<+is> 248=item B<-is>|B<+is>
248 249
249Compile I<font-styles>: Bold/Italic font styles imply high intensity 250Compile I<font-styles>: Bold/Blink font styles imply high intensity
250foreground/background (default). See resource B<intensityStyles> for 251foreground/background (default). See resource B<intensityStyles> for
251details. 252details.
252 253
253=item B<-name> I<name> 254=item B<-name> I<name>
254 255
272 273
273=item B<-sb>|B<+sb> 274=item B<-sb>|B<+sb>
274 275
275Turn on/off scrollbar; resource B<scrollBar>. 276Turn on/off scrollbar; resource B<scrollBar>.
276 277
278=item B<-sr>|B<+sr>
279
280Put scrollbar on right/left; resource B<scrollBar_right>.
281
282=item B<-st>|B<+st>
283
284Display rxvt (non XTerm/NeXT) scrollbar without/with a trough;
285resource B<scrollBar_floating>.
286
277=item B<-si>|B<+si> 287=item B<-si>|B<+si>
278 288
279Turn on/off scroll-to-bottom on TTY output inhibit; resource 289Turn on/off scroll-to-bottom on TTY output inhibit; resource
280B<scrollTtyOutput> has opposite effect. 290B<scrollTtyOutput> has opposite effect.
281 291
287=item B<-sw>|B<+sw> 297=item B<-sw>|B<+sw>
288 298
289Turn on/off scrolling with the scrollback buffer as new lines appear. 299Turn on/off scrolling with the scrollback buffer as new lines appear.
290This only takes effect if B<-si> is also given; resource 300This only takes effect if B<-si> is also given; resource
291B<scrollWithBuffer>. 301B<scrollWithBuffer>.
292
293=item B<-sr>|B<+sr>
294
295Put scrollbar on right/left; resource B<scrollBar_right>.
296
297=item B<-st>|B<+st>
298
299Display rxvt (non XTerm/NeXT) scrollbar without/with a trough;
300resource B<scrollBar_floating>.
301 302
302=item B<-ptab>|B<+ptab> 303=item B<-ptab>|B<+ptab>
303 304
304If enabled (default), "Horizontal Tab" characters are being stored as 305If enabled (default), "Horizontal Tab" characters are being stored as
305actual wide characters in the screen buffer, which makes it possible to 306actual wide characters in the screen buffer, which makes it possible to
417 418
418=item B<-tcw> 419=item B<-tcw>
419 420
420Change the meaning of triple-click selection with the left mouse 421Change the meaning of triple-click selection with the left mouse
421button. Only effective when the original (non-perl) selection code is 422button. Only effective when the original (non-perl) selection code is
422in-use. Instead of selecting a full line it will extend the selection the 423in-use. Instead of selecting a full line it will extend the selection to
423end of the logical line only. resource B<tripleclickwords>. 424the end of the logical line only. resource B<tripleclickwords>.
424 425
425=item B<-insecure> 426=item B<-insecure>
426 427
427Enable "insecure" mode, which currently enables most of the escape 428Enable "insecure" mode, which currently enables most of the escape
428sequences that echo strings. See the resource B<insecure> for more 429sequences that echo strings. See the resource B<insecure> for more
448 449
449Turn on/off hold window after exit support. If enabled, @@RXVT_NAME@@ 450Turn on/off hold window after exit support. If enabled, @@RXVT_NAME@@
450will not immediately destroy its window when the program executed within 451will not immediately destroy its window when the program executed within
451it exits. Instead, it will wait till it is being killed or closed by the 452it exits. Instead, it will wait till it is being killed or closed by the
452user; resource B<hold>. 453user; resource B<hold>.
454
455=item B<-xrm> I<string>
456
457Works like the X Toolkit option of the same name, by adding the I<string>
458as if it were specified in a resource file. Resource values specified this
459way take precedence over all other resource specifications.
460
461Note that you need to use the I<same> syntax as in the .Xdefaults file,
462e.g. C<*.background: black>. Also note that all @@RXVT_NAME@@-specific
463options can be specified as long-options on the commandline, so use
464of B<-xrm> is mostly limited to cases where you want to specify other
465resources (e.g. for input methods) or for compatibility with other
466programs.
453 467
454=item B<-keysym.>I<sym> I<string> 468=item B<-keysym.>I<sym> I<string>
455 469
456Remap a key symbol. See resource B<keysym>. 470Remap a key symbol. See resource B<keysym>.
457 471
492If this switch is given, @@RXVT_NAME@@ will not create any utmp/wtmp 506If this switch is given, @@RXVT_NAME@@ will not create any utmp/wtmp
493entries and will not tinker with pty/tty permissions - you have to do that 507entries and will not tinker with pty/tty permissions - you have to do that
494yourself if you want that. 508yourself if you want that.
495 509
496As an extremely special case, specifying C<-1> will completely suppress 510As an extremely special case, specifying C<-1> will completely suppress
497pty/tty operations. 511pty/tty operations, which is probably only useful in conjunction with some
512perl extension that manages the terminal.
498 513
499Here is a example in perl that illustrates how this option can be used (a 514Here is a example in perl that illustrates how this option can be used (a
500longer example is in F<doc/pty-fd>): 515longer example is in F<doc/pty-fd>):
501 516
502 use IO::Pty; 517 use IO::Pty;
516Comma-separated list of perl extension scripts to use (or not to use) in 531Comma-separated list of perl extension scripts to use (or not to use) in
517this terminal instance. See resource B<perl-ext> for details. 532this terminal instance. See resource B<perl-ext> for details.
518 533
519=back 534=back
520 535
521=head1 RESOURCES (available also as long-options) 536=head1 RESOURCES
522 537
523Note: `@@RXVT_NAME@@ --help' gives a list of all resources (long 538Note: `@@RXVT_NAME@@ --help' gives a list of all resources (long
524options) compiled into your version. 539options) compiled into your version. All resources are also available as
540long-options.
525 541
526You can set and change the resources using X11 tools like B<xrdb>. Many 542You can set and change the resources using X11 tools like B<xrdb>. Many
527distribution do also load settings from the B<~/.Xresources> file when X 543distribution do also load settings from the B<~/.Xresources> file when X
528starts. @@RXVT_NAME@@ will consult the following files/resources in order, 544starts. @@RXVT_NAME@@ will consult the following files/resources in order,
529with later settings overwriting earlier ones: 545with later settings overwriting earlier ones:
531 1. system-wide app-defaults file, either locale-dependent OR global 547 1. system-wide app-defaults file, either locale-dependent OR global
532 2. app-defaults file in $XAPPLRESDIR 548 2. app-defaults file in $XAPPLRESDIR
533 3. RESOURCE_MANAGER property on root-window OR $HOME/.Xdefaults 549 3. RESOURCE_MANAGER property on root-window OR $HOME/.Xdefaults
534 4. SCREEN_RESOURCES for the current screen 550 4. SCREEN_RESOURCES for the current screen
535 5. $XENVIRONMENT file OR $HOME/.Xdefaults-<nodename> 551 5. $XENVIRONMENT file OR $HOME/.Xdefaults-<nodename>
552 6. resources specified via -xrm on the commandline
536 553
537Note that when reading X resources, B<@@RXVT_NAME@@> recognizes two class 554Note that when reading X resources, B<@@RXVT_NAME@@> recognizes two class
538names: B<Rxvt> and B<URxvt>. The class name B<Rxvt> allows resources 555names: B<Rxvt> and B<URxvt>. The class name B<Rxvt> allows resources
539common to both B<@@RXVT_NAME@@> and the original I<rxvt> to be easily 556common to both B<@@RXVT_NAME@@> and the original I<rxvt> to be easily
540configured, while the class name B<URxvt> allows resources unique to 557configured, while the class name B<URxvt> allows resources unique to
642 659
643B<False>: specify that everything is to be displayed, even 660B<False>: specify that everything is to be displayed, even
644if the refresh is too fast for the human eye to read anything (or the 661if the refresh is too fast for the human eye to read anything (or the
645monitor to display anything); option B<+ss>. 662monitor to display anything); option B<+ss>.
646 663
647=item B<inheritPixmap:> I<boolean> 664=item B<transparent:> I<boolean>
648 665
649B<True>: make the background inherit the parent windows' pixmap, giving 666Turn on/off illusion of a transparent window background.
650artificial transparency. B<False>: do not inherit the parent windows'
651pixmap.
652 667
653I<Please note that transparency of any kind if completely unsupported by 668B<inheritPixmap> is still accepted as an obsolete alias but will be removed in
654the author. Don't bug him with installation questions!> 669future versions.
670
671I<Please address all transparency related issues to Sasha Vasko at
672sasha@aftercode.net. Read the FAQ (man 7 @@RXVT_NAME@@)!>
655 673
656=item B<fading:> I<number> 674=item B<fading:> I<number>
657 675
658Fade the text by the given percentage when focus is lost; option B<-fade>. 676Fade the text by the given percentage when focus is lost; option B<-fade>.
659 677
695The colour of the border around the text area and between the scrollbar 713The colour of the border around the text area and between the scrollbar
696and the text. 714and the text.
697 715
698=item B<backgroundPixmap:> I<file[;geom[:op1][:op2][...]]> 716=item B<backgroundPixmap:> I<file[;geom[:op1][:op2][...]]>
699 717
700Use the specified image file for the background and also optionally 718Use the specified image file for the background and also
701specify its scaling with a geometry string B<WxH+X+Y>, 719optionally specify its scaling with a geometry string B<WxH+X+Y>,
702in which B<"W" / "H"> specify the horizontal/vertical scale (percent), 720(default C<0x0+50+50>) in which B<"W" / "H"> specify the
703and B<"X" / "Y"> locate the image centre (percent). 721horizontal/vertical scale (percent), and B<"X" / "Y"> locate the image
704A scale of 0 displays the image with tiling. A scale of 1 displays the 722centre (percent). A scale of 0 displays the image with tiling. A scale
705image without any scaling. A scale of 2 to 9 specifies an integer 723of 1 displays the image without any scaling. A scale of 2 to 9 specifies
706number of images in that direction. No image will be magnified beyond 724an integer number of images in that direction. No image will be magnified
70710 times its original size. The maximum permitted scale is 1000. 725beyond 10 times its original size. The maximum permitted scale is 1000.
708Additional operations can be specified after colon B<:op1:op2...>. 726Additional operations can be specified after colon B<:op1:op2...>.
709Supported operations are: 727Supported operations are:
728
710 B<"tile"> - force background image to be tiled and not scaled. Equivalent to 0x0, 729 tile force background image to be tiled and not scaled. Equivalent to 0x0
711 B<"propscale"> - will scale image keeping proportions, 730 propscale will scale image keeping proportions
712 B<"auto"> - will scale image to match window size. Equivalent to 100x100; 731 auto will scale image to match window size. Equivalent to 100x100
713 B<"hscale"> - will scale image horizontally to the window size; 732 hscale will scale image horizontally to the window size
714 B<"vscale"> - will scale image vertically to the window size; 733 vscale will scale image vertically to the window size
715 B<"scale"> - will scale image to match window size; 734 scale will scale image to match window size
716 B<"root"> - will tile image as if it was a root window background, auto-adjusting 735 root will tile image as if it was a root window background, auto-adjusting
717 whenever terminal window moves. 736 whenever terminal window moves
718 737
719If used in conjunction with B<-tr> option - specified pixmap will be 738If used in conjunction with B<-tr> option, the specified pixmap will be
720blended over transparency image using either alpha-blending, or any 739blended over transparency image using either alpha-blending, or any
721other blending type, specified with B<-blt "type"> option. 740other blending type, specified with B<-blt "type"> option.
722[default 0x0+50+50]
723 741
724=item B<path:> I<path> 742=item B<path:> I<path>
725 743
726Specify the colon-delimited search path for finding background image files. 744Specify the colon-delimited search path for finding background image files.
727 745
788text font will being used for the given style. 806text font will being used for the given style.
789 807
790=item B<intensityStyles:> I<boolean> 808=item B<intensityStyles:> I<boolean>
791 809
792When font styles are not enabled, or this option is enabled (B<True>, 810When font styles are not enabled, or this option is enabled (B<True>,
793option B<-is>, the default), bold and italic font styles imply high 811option B<-is>, the default), bold/blink font styles imply high
794intensity foreground/background colours. Disabling this option (B<False>, 812intensity foreground/background colours. Disabling this option (B<False>,
795option B<+is>) disables this behaviour, the high intensity colours are not 813option B<+is>) disables this behaviour, the high intensity colours are not
796reachable. 814reachable.
797 815
798=item B<selectstyle:> I<mode>
799
800Set mouse selection style to B<old> which is 2.20, B<oldword> which
801is xterm style with 2.20 old word selection, or anything else which
802gives xterm style selection. Only effective when the original (non-perl)
803selection code is in use.
804
805=item B<scrollstyle:> I<mode>
806
807Set scrollbar style to B<rxvt>, B<plain>, B<next> or B<xterm>. B<plain> is
808the author's favourite.
809
810=item B<title:> I<string> 816=item B<title:> I<string>
811 817
812Set window title string, the default title is the command-line 818Set window title string, the default title is the command-line
813specified after the B<-e> option, if any, otherwise the application 819specified after the B<-e> option, if any, otherwise the application
814name; option B<-title>. 820name; option B<-title>.
858 864
859 URxvt.print-pipe: cat > $(TMPDIR=$HOME mktemp urxvt.XXXXXX) 865 URxvt.print-pipe: cat > $(TMPDIR=$HOME mktemp urxvt.XXXXXX)
860 866
861This creates a new file in your home directory with the screen contents 867This creates a new file in your home directory with the screen contents
862every time you hit C<Print>. 868every time you hit C<Print>.
869
870=item B<scrollstyle:> I<mode>
871
872Set scrollbar style to B<rxvt>, B<plain>, B<next> or B<xterm>. B<plain> is
873the author's favourite.
863 874
864=item B<scrollBar:> I<boolean> 875=item B<scrollBar:> I<boolean>
865 876
866B<True>: enable the scrollbar [default]; option B<-sb>. B<False>: 877B<True>: enable the scrollbar [default]; option B<-sb>. B<False>:
867disable the scrollbar; option B<+sb>. 878disable the scrollbar; option B<+sb>.
1000will be created). In this mode, characters outside ISO-8859-1 can be used. 1011will be created). In this mode, characters outside ISO-8859-1 can be used.
1001 1012
1002When the selection extension is not used, only ISO-8859-1 characters can 1013When the selection extension is not used, only ISO-8859-1 characters can
1003be used. If not specified, the built-in default is used: 1014be used. If not specified, the built-in default is used:
1004 1015
1005B<< BACKSLASH `"'&()*,;<=>?@[]{|} >> 1016B<< BACKSLASH `"'&()*,;<=>?@[]^{|} >>
1006 1017
1007=item B<preeditType:> I<style> 1018=item B<preeditType:> I<style>
1008 1019
1009B<OverTheSpot>, B<OffTheSpot>, B<Root>; option B<-pt>. 1020B<OverTheSpot>, B<OffTheSpot>, B<Root>; option B<-pt>.
1010 1021
1445=back 1456=back
1446 1457
1447=head2 ALPHA CHANNEL SUPPORT 1458=head2 ALPHA CHANNEL SUPPORT
1448 1459
1449If Xft support has been compiled in and as long as Xft/Xrender/X don't get 1460If Xft support has been compiled in and as long as Xft/Xrender/X don't get
1450their act together, rxvt-unicode will support C<rgba:rrrr/gggg/bbbb/aaaa> 1461their act together, rxvt-unicode will do it's own alpha channel management:
1451(recommended, but B<MUST> have 4 digits/component) colour specifications, 1462
1452in addition to the ones provided by X, where the additional A component 1463You can prefix any color with an opaquenes percentage enclosed in
1464brackets, i.e. C<[percent]>, where C<percent> is a decimal percentage
1465(0-100) that specifies the opacity of the color, where C<0> is completely
1466transparent and C<100> is completely opaque. For example, C<[50]red> is a
1467half-transparent red, while C<[95]#00ff00> is an almost opaque green. This
1468is the recommended format to specify transparency values, and works with
1469all ways to specify a colour.
1470
1471For complete control, rxvt-unicode also supports
1472C<rgba:rrrr/gggg/bbbb/aaaa> (exactly four hex digits/component) colour
1473specifications, where the additional C<aaaa> component specifies opacity
1453specifies opacity (alpha) values. The minimum value of C<0> is completely 1474(alpha) values. The minimum value of C<0000> is completely transparent,
1454transparent). You can also prefix any color with C<[percent]>, where 1475while C<ffff> is completely opaque). The two example colours from
1455C<percent> is a decimal percentage (0-100) that specifies the opacity of 1476earlier could also be specified as C<rgba:ff00/0000/0000/8000> and
1456the color, where C<0> is completely transparent and C<100> is completelxy 1477C<rgba:0000/ff00/0000/f332>.
1457opaque.
1458 1478
1459You probably need to specify B<"-depth 32">, too, and have the luck that 1479You probably need to specify B<"-depth 32">, too, to force a visual with
1460your X-server uses ARGB pixel layout, as X is far from just supporting 1480alpha channels, and have the luck that your X-server uses ARGB pixel
1461ARGB visuals out of the box, and rxvt-unicode just fudges around. 1481layout, as X is far from just supporting ARGB visuals out of the box, and
1482rxvt-unicode just fudges around.
1462 1483
1463For example, the following selects an almost completely transparent red 1484For example, the following selects an almost completely transparent black
1464background, and an almost opaque pink foreground: 1485background, and an almost opaque pink foreground:
1465 1486
1466 @@RXVT_NAME@@ -depth 32 -bg rgba:0000/0000/0000/aaaa -fg "[80]pink" 1487 @@RXVT_NAME@@ -depth 32 -bg rgba:0000/0000/0000/4444 -fg "[80]pink"
1467 1488
1468I<Please note that transparency of any kind if completely unsupported by 1489When not using a background image, then the interpretation of the
1469the author. Don't bug him with installation questions!> 1490alpha channel is up to your compositing manager (most interpret it as
1491transparency of course).
1492
1493When using a background pixmap or pseudo-transparency, then the background
1494colour will always behave as if it were completely transparent (so the
1495background image shows instead), regardless of how it was specified, while
1496other colours will either be transparent as specified (the background
1497image will show through) on servers supporting the RENDER extension, or
1498fully opaque on servers not supporting the RENDER EXTENSION.
1499
1500Please note that due to bugs in Xft, specifying alpha values might result
1501in garbage being displayed when the X-server does not support the RENDER
1502extension.
1470 1503
1471=head1 ENVIRONMENT 1504=head1 ENVIRONMENT
1472 1505
1473B<@@RXVT_NAME@@> sets and/or uses the following environment variables: 1506B<@@RXVT_NAME@@> sets and/or uses the following environment variables:
1474 1507

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines