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.107 by root, Sun Jan 29 20:51:27 2006 UTC vs.
Revision 1.120 by root, Sat Aug 12 01:37:11 2006 UTC

… …
28world. Being a terminal emulator, however, some things are very difficult, 28world. Being a terminal emulator, however, some things are very difficult,
29especially cursive scripts such as arabic, vertically written scripts 29especially cursive scripts such as arabic, vertically written scripts
30like mongolian or scripts requiring extremely complex combining rules, 30like mongolian or scripts requiring extremely complex combining rules,
31like tibetan or devenagari. Don't expect pretty output when using these 31like tibetan or devenagari. Don't expect pretty output when using these
32scripts. Most other scripts, latin, cyrillic, kanji, thai etc. should work 32scripts. Most other scripts, latin, cyrillic, kanji, thai etc. should work
33fine, though. A somewhat difficult case are left-to-right scripts, such 33fine, though. A somewhat difficult case are right-to-left scripts, such
34as hebrew: B<rxvt-unicode> adopts the view that bidirectional algorithms 34as hebrew: B<rxvt-unicode> adopts the view that bidirectional algorithms
35belong into the application, not the terminal emulator (too many things -- 35belong into the application, not the terminal emulator (too many things --
36such as cursor-movement while editing -- break otherwise), but that might 36such as cursor-movement while editing -- break otherwise), but that might
37change. 37change.
38 38
39If you are looking for a terminal that supports more exotic scripts, let 39If you are looking for a terminal that supports more exotic scripts, let
40me recommend C<mlterm>, which is a very userfriendly, lean and clean 40me recommend C<mlterm>, which is a very user friendly, lean and clean
41terminal emulator. In fact, the reason rxvt-unicode was born was solely 41terminal emulator. In fact, the reason rxvt-unicode was born was solely
42because the author couldn't get C<mlterm> to use one font for latin1 and 42because the author couldn't get C<mlterm> to use one font for latin1 and
43another for japanese. 43another for japanese.
44 44
45Therefore another design rationale was the use of multiple fonts to 45Therefore another design rationale was the use of multiple fonts to
46display characters: The idea of a single unicode font which many other 46display characters: The idea of a single unicode font which many other
47programs force onto it's users never made sense to me: You should be able 47programs force onto its users never made sense to me: You should be able
48to choose any font for any script freely. 48to choose any font for any script freely.
49 49
50Apart from that, rxvt-unicode is also much better internationalised than 50Apart from that, rxvt-unicode is also much better internationalised than
51it's predecessor, supports things such as XFT and ISO 14755 that are handy 51its predecessor, supports things such as XFT and ISO 14755 that are handy
52in i18n-environments, is faster, and has a lot less bugs than the original 52in i18n-environments, is faster, and has a lot bugs less than the original
53rxvt. This all in addition to dozens of other small improvements. 53rxvt. This all in addition to dozens of other small improvements.
54 54
55It is still faithfully following the original rxvt idea of being lean 55It is still faithfully following the original rxvt idea of being lean
56and nice on resources: for example, you can still configure rxvt-unicode 56and nice on resources: for example, you can still configure rxvt-unicode
57without most of it's features to get a lean binary. It also comes with 57without most of its features to get a lean binary. It also comes with
58a client/daemon pair that lets you open any number of terminal windows 58a client/daemon pair that lets you open any number of terminal windows
59from within a single process, which makes startup time very fast and 59from within a single process, which makes startup time very fast and
60drastically reduces memory usage. See @@RXVT_NAME@@d(1) (daemon) and 60drastically reduces memory usage. See @@RXVT_NAME@@d(1) (daemon) and
61@@RXVT_NAME@@c(1) (client). 61@@RXVT_NAME@@c(1) (client).
62 62
63It also makes technical information about escape sequences (which have 63It also makes technical information about escape sequences (which have
64been extended) easier accessible: see @@RXVT_NAME@@(7) for technical 64been extended) more accessible: see @@RXVT_NAME@@(7) for technical
65reference documentation (escape sequences etc.). 65reference documentation (escape sequences etc.).
66 66
67=head1 OPTIONS 67=head1 OPTIONS
68 68
69The B<@@RXVT_NAME@@> options (mostly a subset of I<xterm>'s) are listed 69The B<@@RXVT_NAME@@> options (mostly a subset of I<xterm>'s) are listed
… …
95respected). In the absence of this option, the display specified by the 95respected). In the absence of this option, the display specified by the
96B<DISPLAY> environment variable is used. 96B<DISPLAY> environment variable is used.
97 97
98=item B<-depth> I<bitdepth> 98=item B<-depth> I<bitdepth>
99 99
100Compile I<frills>: Attempt to find a visual with the given bit depth; 100Compile I<xft>: Attempt to find a visual with the given bit depth;
101resource B<depth>. 101resource B<depth>.
102 102
103=item B<-geometry> I<geom> 103=item B<-geometry> I<geom>
104 104
105Window geometry (B<-g> still respected); resource B<geometry>. 105Window geometry (B<-g> still respected); resource B<geometry>.
… …
114 114
115=item B<-ip>|B<+ip> | B<-tr>|B<+tr> 115=item B<-ip>|B<+ip> | B<-tr>|B<+tr>
116 116
117Turn on/off inheriting parent window's pixmap. Alternative form is 117Turn on/off inheriting parent window's pixmap. Alternative form is
118B<-tr>; resource B<inheritPixmap>. 118B<-tr>; resource B<inheritPixmap>.
119
120I<Please note that transparency of any kind if completely unsupported by
121the author. Don't bug him with installation questions! Read the FAQ (man 7
122@@RXVT_NAME@@)!>
119 123
120=item B<-fade> I<number> 124=item B<-fade> I<number>
121 125
122Fade the text by the given percentage when focus is lost. Small values 126Fade the text by the given percentage when focus is lost. Small values
123fade a little only, 100 completely replaces all colours by the fade 127fade a little only, 100 completely replaces all colours by the fade
124colour; resource B<fading>. 128colour; resource B<fading>.
125 129
126=item B<-fadecolor> I<colour> 130=item B<-fadecolor> I<colour>
127 131
128Fade to this colour when fading is used (see B<-fade>). The default colour 132Fade to this colour when fading is used (see B<-fade>). The default colour
129is black. resource B<fadeColor>. 133is opaque black. resource B<fadeColor>.
130 134
131=item B<-tint> I<colour> 135=item B<-tint> I<colour>
132 136
133Tint the transparent background pixmap with the given colour when 137Tint the transparent background pixmap with the given colour when
134transparency is enabled with B<-tr> or B<-ip>. This only works for 138transparency is enabled with B<-tr> or B<-ip>. This only works for
… …
182that are checked in order when trying to find glyphs for characters. The 186that are checked in order when trying to find glyphs for characters. The
183first font defines the cell size for characters; other fonts might be 187first font defines the cell size for characters; other fonts might be
184smaller, but not (in general) larger. A (hopefully) reasonable default 188smaller, but not (in general) larger. A (hopefully) reasonable default
185font list is always appended to it. See resource B<font> for more details. 189font list is always appended to it. See resource B<font> for more details.
186 190
187In short, to specify an X11 core font, just specify it's name or prefix it 191In short, to specify an X11 core font, just specify its name or prefix it
188with C<x:>. To specify an XFT-font, you need to prefix it with C<xft:>, 192with C<x:>. To specify an XFT-font, you need to prefix it with C<xft:>,
189e.g.: 193e.g.:
190 194
191 @@RXVT_NAME@@ -fn "xft:Bitstream Vera Sans Mono:pixelsize=15" 195 @@RXVT_NAME@@ -fn "xft:Bitstream Vera Sans Mono:pixelsize=15"
192 @@RXVT_NAME@@ -fn "9x15bold,xft:Bitstream Vera Sans Mono" 196 @@RXVT_NAME@@ -fn "9x15bold,xft:Bitstream Vera Sans Mono"
… …
420 424
421Remap a key symbol. See resource B<keysym>. 425Remap a key symbol. See resource B<keysym>.
422 426
423=item B<-embed> I<windowid> 427=item B<-embed> I<windowid>
424 428
425Tells @@RXVT_NAME@@ to embed it's windows into an already-existing window, 429Tells @@RXVT_NAME@@ to embed its windows into an already-existing window,
426which enables applications to easily embed a terminal. 430which enables applications to easily embed a terminal.
427 431
428Right now, @@RXVT_NAME@@ will first unmap/map the specified window, so it 432Right now, @@RXVT_NAME@@ will first unmap/map the specified window, so it
429shouldn't be a top-level window. @@RXVT_NAME@@ will also reconfigure it 433shouldn't be a top-level window. @@RXVT_NAME@@ will also reconfigure it
430quite a bit, so don't expect it to keep some specific state. It's best to 434quite a bit, so don't expect it to keep some specific state. It's best to
… …
433The window will not be destroyed when @@RXVT_NAME@@ exits. 437The window will not be destroyed when @@RXVT_NAME@@ exits.
434 438
435It might be useful to know that @@RXVT_NAME@@ will not close file 439It might be useful to know that @@RXVT_NAME@@ will not close file
436descriptors passed to it (except for stdin/out/err, of course), so you 440descriptors passed to it (except for stdin/out/err, of course), so you
437can use file descriptors to communicate with the programs within the 441can use file descriptors to communicate with the programs within the
438terminal. This works regardless of wether the C<-embed> option was used or 442terminal. This works regardless of whether the C<-embed> option was used or
439not. 443not.
440 444
441Here is a short Gtk2-perl snippet that illustrates how this option can be 445Here is a short Gtk2-perl snippet that illustrates how this option can be
442used (a longer example is in F<doc/embed>): 446used (a longer example is in F<doc/embed>):
443 447
… …
448 }); 452 });
449 453
450=item B<-pty-fd> I<file descriptor> 454=item B<-pty-fd> I<file descriptor>
451 455
452Tells @@RXVT_NAME@@ NOT to execute any commands or create a new pty/tty 456Tells @@RXVT_NAME@@ NOT to execute any commands or create a new pty/tty
453pair but instead use the given filehandle as the tty master. This is 457pair but instead use the given file descriptor as the tty master. This is
454useful if you want to drive @@RXVT_NAME@@ as a generic terminal emulator 458useful if you want to drive @@RXVT_NAME@@ as a generic terminal emulator
455without having to run a program within it. 459without having to run a program within it.
456 460
457If this switch is given, @@RXVT_NAME@@ will not create any utmp/wtmp 461If this switch is given, @@RXVT_NAME@@ will not create any utmp/wtmp
458entries and will not tinker with pty/tty permissions - you have to do that 462entries and will not tinker with pty/tty permissions - you have to do that
… …
512 516
513=over 4 517=over 4
514 518
515=item B<depth:> I<bitdepth> 519=item B<depth:> I<bitdepth>
516 520
517Compile I<frills>: Attempt to find a visual with the given bit depth; 521Compile I<xft>: Attempt to find a visual with the given bit depth;
518option B<-depth>. 522option B<-depth>.
519 523
520=item B<geometry:> I<geom> 524=item B<geometry:> I<geom>
521 525
522Create the window with the specified X window geometry [default 80x24]; 526Create the window with the specified X window geometry [default 80x24];
… …
596=item B<inheritPixmap:> I<boolean> 600=item B<inheritPixmap:> I<boolean>
597 601
598B<True>: make the background inherit the parent windows' pixmap, giving 602B<True>: make the background inherit the parent windows' pixmap, giving
599artificial transparency. B<False>: do not inherit the parent windows' 603artificial transparency. B<False>: do not inherit the parent windows'
600pixmap. 604pixmap.
605
606I<Please note that transparency of any kind if completely unsupported by
607the author. Don't bug him with installation questions!>
601 608
602=item B<fading:> I<number> 609=item B<fading:> I<number>
603 610
604Fade the text by the given percentage when focus is lost; option B<-fade>. 611Fade the text by the given percentage when focus is lost; option B<-fade>.
605 612
… …
712 719
713=item B<intensityStyles:> I<boolean> 720=item B<intensityStyles:> I<boolean>
714 721
715When font styles are not enabled, or this option is enabled (B<True>, 722When font styles are not enabled, or this option is enabled (B<True>,
716option B<-is>, the default), bold and italic font styles imply high 723option B<-is>, the default), bold and italic font styles imply high
717intensity foreground/backround colours. Disabling this option (B<False>, 724intensity foreground/background colours. Disabling this option (B<False>,
718option B<+is>) disables this behaviour, the high intensity colours are not 725option B<+is>) disables this behaviour, the high intensity colours are not
719reachable. 726reachable.
720 727
721=item B<selectstyle:> I<mode> 728=item B<selectstyle:> I<mode>
722 729
… …
774Example: 781Example:
775 782
776 URxvt.print-pipe: cat > $(TMPDIR=$HOME mktemp urxvt.XXXXXX) 783 URxvt.print-pipe: cat > $(TMPDIR=$HOME mktemp urxvt.XXXXXX)
777 784
778This creates a new file in your home directory with the screen contents 785This creates a new file in your home directory with the screen contents
779everytime you hit C<Print>. 786every time you hit C<Print>.
780 787
781=item B<scrollBar:> I<boolean> 788=item B<scrollBar:> I<boolean>
782 789
783B<True>: enable the scrollbar [default]; option B<-sb>. B<False>: 790B<True>: enable the scrollbar [default]; option B<-sb>. B<False>:
784disable the scrollbar; option B<+sb>. 791disable the scrollbar; option B<+sb>.
… …
806 813
807=item B<scrollWithBuffer:> I<boolean> 814=item B<scrollWithBuffer:> I<boolean>
808 815
809B<True>: scroll with scrollback buffer when tty receives new lines (and 816B<True>: scroll with scrollback buffer when tty receives new lines (and
810B<scrollTtyOutput> is False); option B<-sw>. B<False>: do not scroll 817B<scrollTtyOutput> is False); option B<-sw>. B<False>: do not scroll
811with scrollback buffer when tty recieves new lines; option B<+sw>. 818with scrollback buffer when tty receives new lines; option B<+sw>.
812 819
813=item B<scrollTtyKeypress:> I<boolean> 820=item B<scrollTtyKeypress:> I<boolean>
814 821
815B<True>: scroll to bottom when a non-special key is pressed. Special keys 822B<True>: scroll to bottom when a non-special key is pressed. Special keys
816are those which are intercepted by rxvt-unicode for special handling and 823are those which are intercepted by rxvt-unicode for special handling and
… …
1019 1026
1020I<string> may contain escape values (C<\a>: bell, C<\b>: backspace, 1027I<string> may contain escape values (C<\a>: bell, C<\b>: backspace,
1021C<\e>, C<\E>: escape, C<\n>: newline, C<\r>: carriage return, C<\t>: tab, 1028C<\e>, C<\E>: escape, C<\n>: newline, C<\r>: carriage return, C<\t>: tab,
1022C<\000>: octal number) or verbatim control characters (C<^?>: delete, 1029C<\000>: octal number) or verbatim control characters (C<^?>: delete,
1023C<^@>: null, C<^A> ...) and may be enclosed with double quotes so that it 1030C<^@>: null, C<^A> ...) and may be enclosed with double quotes so that it
1024can start or end with whitespace. 1031can start or end with whitespace. B<This feature is deprecated and will
1032be removed>.
1025 1033
1026Please note that you need to double the C<\> in resource files, as 1034Please note that you need to double the C<\> in resource files, as
1027Xlib itself does it's own de-escaping (you can use C<\033> instead of 1035Xlib itself does its own de-escaping (you can use C<\033> instead of
1028C<\e> (and so on), which will work with both Xt and @@RXVT_NAME@@'s own 1036C<\e> (and so on), which will work with both Xt and @@RXVT_NAME@@'s own
1029processing). 1037processing).
1030 1038
1031You can define a range of keysyms in one shot by providing a I<string> 1039You can define a range of keysyms in one shot by providing a I<string>
1032with pattern B<list/PREFIX/MIDDLE/SUFFIX>, where the delimeter `/' 1040with pattern B<list/PREFIX/MIDDLE/SUFFIX>, where the delimiter `/'
1033should be a character not used by the strings. 1041should be a character not used by the strings.
1034 1042
1035Its usage can be demonstrated by an example: 1043Its usage can be demonstrated by an example:
1036 1044
1037 URxvt.keysym.M-C-0x61: list|\033<M-C-|abc|> 1045 URxvt.keysym.M-C-0x61: list|\033<M-C-|abc|>
… …
1101example, C<default,-selection> will use all the default extension except 1109example, C<default,-selection> will use all the default extension except
1102C<selection>. 1110C<selection>.
1103 1111
1104Extension names can also be followed by an argument in angle brackets 1112Extension names can also be followed by an argument in angle brackets
1105(e.g. C<< searchable-scrollback<M-s> >>, which binds the hotkey for 1113(e.g. C<< searchable-scrollback<M-s> >>, which binds the hotkey for
1106searchable scorllback to Alt/Meta-s). Mentioning the same extension 1114searchable scrollback to Alt/Meta-s). Mentioning the same extension
1107multiple times with different arguments will pass multiple arguments to 1115multiple times with different arguments will pass multiple arguments to
1108the extension. 1116the extension.
1109 1117
1110Each extension is looked up in the library directories, loaded if 1118Each extension is looked up in the library directories, loaded if
1111necessary, and bound to the current terminal instance. 1119necessary, and bound to the current terminal instance.
… …
1267This mode lets you input characters representing the keycap symbols of 1275This mode lets you input characters representing the keycap symbols of
1268your keyboard, if representable in the current locale encoding. 1276your keyboard, if representable in the current locale encoding.
1269 1277
1270Start by pressing C<Control> and C<Shift> together, then releasing 1278Start by pressing C<Control> and C<Shift> together, then releasing
1271them. The next special key (cursor keys, home etc.) you enter will not 1279them. The next special key (cursor keys, home etc.) you enter will not
1272invoke it's usual function but instead will insert the corresponding 1280invoke its usual function but instead will insert the corresponding
1273keycap symbol. The symbol will only be entered when the key has been 1281keycap symbol. The symbol will only be entered when the key has been
1274released, otherwise pressing e.g. C<Shift> would enter the symbol for 1282released, otherwise pressing e.g. C<Shift> would enter the symbol for
1275C<ISO Level 2 Switch>, although your intention might have been to enter a 1283C<ISO Level 2 Switch>, although your intention might have been to enter a
1276reverse tab (Shift-Tab). 1284reverse tab (Shift-Tab).
1277 1285
… …
1340It is also possible to specify the colour values of B<foreground>, 1348It is also possible to specify the colour values of B<foreground>,
1341B<background>, B<cursorColor>, B<cursorColor2>, B<colorBD>, B<colorUL> as 1349B<background>, B<cursorColor>, B<cursorColor2>, B<colorBD>, B<colorUL> as
1342a number 0-15, as a convenient shorthand to reference the colour name of 1350a number 0-15, as a convenient shorthand to reference the colour name of
1343color0-color15. 1351color0-color15.
1344 1352
1345If Xft support has been compiled in and as long as Xft/Xrender don't get 1353In addition to the colours defined above, @@RXVT_NAME@@ offers an
1346their act together, rxvt-unicode will support C<#ARGB>, C<#AARRGGBB> 1354additional 72 colours. The first 64 of those (with indices 16 to 79)
1347and C<#AAAARRRRGGGGBBBB> colour specifications, in addition to the ones 1355consist of a 4*4*4 RGB colour cube (i.e. I<index = r * 16 + g * 4 + b +
1348provided by X, where the additional A component specifies alpha (opacity) 135616>), followed by 8 additional shades of gray (with indices 80 to 87).
1349values (0 is completely transparent and the maximum is opaque). You 1357
1350probably need to specify B<"-depth 32">, too, as X is far from just 1358Together, all those colours implement the 88 colour xterm colours. Only
1351supporting ARGB visuals out of the box. 1359the first 16 can be changed using resources currently, the rest can only
1360be changed via command sequences ("escape codes").
1352 1361
1353Note that B<-rv> (B<"reverseVideo: True">) simulates reverse video by 1362Note that B<-rv> (B<"reverseVideo: True">) simulates reverse video by
1354always swapping the foreground/background colours. This is in contrast to 1363always swapping the foreground/background colours. This is in contrast to
1355I<xterm>(1) where the colours are only swapped if they have not otherwise 1364I<xterm>(1) where the colours are only swapped if they have not otherwise
1356been specified. For example, 1365been specified. For example,
… …
1362would yield White on Black, while on I<xterm>(1) it would yield Black 1371would yield White on Black, while on I<xterm>(1) it would yield Black
1363on White. 1372on White.
1364 1373
1365=back 1374=back
1366 1375
1376=head2 ALPHA CHANNEL SUPPORT
1377
1378If Xft support has been compiled in and as long as Xft/Xrender/X don't get
1379their act together, rxvt-unicode will support C<rgba:rrrr/gggg/bbbb/aaaa>
1380(recommended, but B<MUST> have 4 digits/component) colour specifications,
1381in addition to the ones provided by X, where the additional A component
1382specifies opacity (alpha) values. The minimum value of C<0> is completely
1383transparent). You can also prefix any color with C<[a]>, where C<a> is on
1384to four hex digits specifiying the opacity value.
1385
1386You probably need to specify B<"-depth 32">, too, and have the luck that
1387your X-server uses ARGB pixel layout, as X is far from just supporting
1388ARGB visuals out of the box, and rxvt-unicode just fudges around.
1389
1390For example, the following selects an almost completely transparent red
1391background, and an almost opaque pink foreground:
1392
1393 @@RXVT_NAME@@ -depth 32 -bg rgba:0000/0000/0000/2222 -fg "[e]pink"
1394
1395I<Please note that transparency of any kind if completely unsupported by
1396the author. Don't bug him with installation questions!>
1397
1367=head1 ENVIRONMENT 1398=head1 ENVIRONMENT
1368 1399
1369B<@@RXVT_NAME@@> sets and/or uses the following environment variables: 1400B<@@RXVT_NAME@@> sets and/or uses the following environment variables:
1370 1401
1371=over 4 1402=over 4
1372 1403
1373=item B<TERM> 1404=item B<TERM>
1374 1405
1375Normally set to C<rxvt-unicode>, unless overwritten at configure time, via 1406Normally set to C<rxvt-unicode>, unless overwritten at configure time, via
1376resources or on the commandline. 1407resources or on the command line.
1377 1408
1378=item B<COLORTERM> 1409=item B<COLORTERM>
1379 1410
1380Either C<rxvt>, C<rxvt-xpm>, depending on wether @@RXVT_NAME@@ was 1411Either C<rxvt>, C<rxvt-xpm>, depending on whether @@RXVT_NAME@@ was
1381compiled with XPM support, and optionally with the added extension 1412compiled with XPM support, and optionally with the added extension
1382C<-mono> to indicate that rxvt-unicode runs on a monochrome screen. 1413C<-mono> to indicate that rxvt-unicode runs on a monochrome screen.
1383 1414
1384=item B<COLORFGBG> 1415=item B<COLORFGBG>
1385 1416
… …
1403C<--with-terminfo=PATH>. 1434C<--with-terminfo=PATH>.
1404 1435
1405=item B<DISPLAY> 1436=item B<DISPLAY>
1406 1437
1407Used by @@RXVT_NAME@@ to connect to the display and set to the correct 1438Used by @@RXVT_NAME@@ to connect to the display and set to the correct
1408display in it's child processes. 1439display in its child processes.
1409 1440
1410=item B<SHELL> 1441=item B<SHELL>
1411 1442
1412The shell to be used for command execution, defaults to C</bin/sh>. 1443The shell to be used for command execution, defaults to C</bin/sh>.
1413 1444
… …
1455 1486
1456=item Project Coordinator 1487=item Project Coordinator
1457 1488
1458Marc A. Lehmann L<< <rxvt-unicode@schmorp.de> >> 1489Marc A. Lehmann L<< <rxvt-unicode@schmorp.de> >>
1459 1490
1460L<http://software.schmorp.de/#rxvt-unicode> 1491L<http://software.schmorp.de/pkg/rxvt-unicode.html>
1461 1492
1462=back 1493=back
1463 1494
1464=head1 AUTHORS 1495=head1 AUTHORS
1465 1496

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines