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.2 by root, Thu Aug 12 21:30:14 2004 UTC vs.
Revision 1.5 by root, Sat Aug 14 03:00:32 2004 UTC

6 6
7B<@@RXVT_NAME@@> [options] [-e command [ args ]] 7B<@@RXVT_NAME@@> [options] [-e command [ args ]]
8 8
9=head1 DESCRIPTION 9=head1 DESCRIPTION
10 10
11B<rxvt-unicode>, version B<@@RXVTVERSION@@>, is a colour vt102 terminal 11B<rxvt-unicode>, version B<@@RXVT_VERSION@@>, is a colour vt102 terminal
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
17See also @@RXVT_NAME@@(7) for technical reference documentation (escape 17=head1 RXVT-UNICODE VS. RXVT
18sequences etc.). 18
19Unlike the original rxvt, B<rxvt-unicode> stores all text in Unicode
20internally. That means it can store and display most scripts in the
21world. Being a terminal emulator, however, some things are very difficult,
22especially cursive scripts such as arabic, vertically written scripts
23like mongolian or scripts requiring extremely complex combining rules,
24like tibetan or devenagari. Don't expect pretty output when using these
25scripts. Most other scripts, latin, cyrillic, kanji, thai etc. should work
26fine, though. A somewhat difficult case are left-to-right scripts, such
27as hebrew: B<rxvt-unicode> adopts the view that bidirectional algorithms
28belong into the application, not the terminal emulator (too many things --
29such as cursor-movement -- break othwerwise).
30
31Another design rationale was the use of multiple fonts to display
32characters: The idea of a single unicode font which many other programs
33force onto it's users never made sense to me: You should be able to choose
34any font for any script.
35
36Apart from that, rxvt-unicode is also much better internationalised than
37it's predecessor, supports things such as XFT and ISO 14755 that are handy
38in i18n-environments, is faster, and has a lot less bugs than the original
39rxvt. This all in addition to dozens of other small improvements.
40
41It is still faithfully following the original rxvt idea of being lean
42and nice on resources: for example, you can still configure rxvt-unicode
43without most of it's features to get a lean binary. It also comes with
44a client/daemon pair that lets you open any number of terminal windows
45from within a single process, which makes startup time very fast and
46drastically reduces memory usage. See @@RXVT_NAME@@d(1) (daemon) and
47@@RXVT_NAME@@c(1) (client).
48
49It also makes technical information about escape sequences (which have
50been extended) easier accessible: see @@RXVT_NAME@@(7) for technical
51reference documentation (escape sequences etc.) and the FAQ section at the
52end of this document.
19 53
20=head1 OPTIONS 54=head1 OPTIONS
21 55
22The B<@@RXVT_NAME@@> options (mostly a subset of I<xterm>'s) are listed 56The B<@@RXVT_NAME@@> options (mostly a subset of I<xterm>'s) are listed
23below. In keeping with the smaller-is-better philosophy, options may be 57below. In keeping with the smaller-is-better philosophy, options may be
24eliminated or default values chosen at compile-time, so options and 58eliminated or default values chosen at compile-time, so options and
25defaults listed may not accurately reflect the version installed on 59defaults listed may not accurately reflect the version installed on
26your system. `rxvt -h' gives a list of major compile-time options on 60your system. `@@RXVT_NAME@@ -h' gives a list of major compile-time options on
27the I<Options> line. Option descriptions may be prefixed with which 61the I<Options> line. Option descriptions may be prefixed with which
28compile option each is dependent upon. e.g. `Compile I<XIM>:' requires 62compile option each is dependent upon. e.g. `Compile I<XIM>:' requires
29I<XIM> on the I<Options> line. Note: `rxvt -help' gives a list of all 63I<XIM> on the I<Options> line. Note: `@@RXVT_NAME@@ -help' gives a list of all
30command-line options compiled into your version. 64command-line options compiled into your version.
31 65
32Note that B<@@RXVT_NAME@@> permits the resource name to be used as a 66Note that B<@@RXVT_NAME@@> permits the resource name to be used as a
33long-option (--/++ option) so the potential command-line options are 67long-option (--/++ option) so the potential command-line options are
34far greater than those listed. For example: `rxvt --loginShell --color1 68far greater than those listed. For example: `@@RXVT_NAME@@ --loginShell --color1
35Orange'. 69Orange'.
36 70
37The following options are available: 71The following options are available:
38 72
39=over 4 73=over 4
120names that are used in turn when trying to display Unicode characters. 154names that are used in turn when trying to display Unicode characters.
121The first font defines the cell size for characters; other fonts might 155The first font defines the cell size for characters; other fonts might
122be smaller, but not larger. A reasonable default font list is always 156be smaller, but not larger. A reasonable default font list is always
123appended to it. resource B<font>. 157appended to it. resource B<font>.
124 158
159See also the question "How does rxvt-unicode choose fonts?" in the FAQ
160section.
161
125=item B<-rb>|B<+rb> 162=item B<-rb>|B<+rb>
126 163
127Enable "real bold" support. When this option is on, bold text will be 164Enable "real bold" support. When this option is on, bold text will be
128displayed using the first available bold font in the font list. Bold 165displayed using the first available bold font in the font list. Bold
129fonts should thus be specified in the font list after their 166fonts should thus be specified in the font list after their
205B<externalBorder>. 242B<externalBorder>.
206 243
207=item B<-bl> 244=item B<-bl>
208 245
209Compile I<frills>: Set MWM hints to request a borderless window, i.e. 246Compile I<frills>: Set MWM hints to request a borderless window, i.e.
210if honoured by the WM, the rxvt window will not have window 247if honoured by the WM, the rxvt-unicode window will not have window
211decorations; resource B<borderLess>. 248decorations; resource B<borderLess>.
212 249
213=item B<-lsp> I<number> 250=item B<-lsp> I<number>
214 251
215Compile I<linespace>: Lines (pixel height) to insert between each row 252Compile I<linespace>: Lines (pixel height) to insert between each row
286Turn on/off secondary screen scroll (default enabled); resource 323Turn on/off secondary screen scroll (default enabled); resource
287B<secondaryScroll>. 324B<secondaryScroll>.
288 325
289=item B<-xrm> I<resourcestring> 326=item B<-xrm> I<resourcestring>
290 327
291No effect on rxvt. Simply passes through an argument to be made 328No effect on rxvt-unicode. Simply passes through an argument to be made
292available in the instance's argument list. Appears in I<WM_COMMAND> in 329available in the instance's argument list. Appears in I<WM_COMMAND> in
293some window managers. 330some window managers.
294 331
295=back 332=back
296 333
465xterm style with 2.20 old word selection, or anything else which gives 502xterm style with 2.20 old word selection, or anything else which gives
466xterm style selection. 503xterm style selection.
467 504
468=item B<scrollstyle:> I<mode> 505=item B<scrollstyle:> I<mode>
469 506
470Set scrollbar style to B<@@RXVT_NAME@@>, B<rxvt>, B<plain>, B<next> or 507Set scrollbar style to B<rxvt>, B<plain>, B<next> or B<xterm>. B<plain> is
471B<xterm> 508the author's favourite..
472 509
473=item B<title:> I<string> 510=item B<title:> I<string>
474 511
475Set window title string, the default title is the command-line 512Set window title string, the default title is the command-line
476specified after the B<-e> option, if any, otherwise the application 513specified after the B<-e> option, if any, otherwise the application
530Align the B<top>, B<bottom> or B<centre> [default] of the scrollbar 567Align the B<top>, B<bottom> or B<centre> [default] of the scrollbar
531thumb with the pointer on middle button press/drag. 568thumb with the pointer on middle button press/drag.
532 569
533=item B<scrollTtyOutput:> I<boolean> 570=item B<scrollTtyOutput:> I<boolean>
534 571
535B<True>: scroll to bottom when tty receives output; option B<+si>. 572B<True>: scroll to bottom when tty receives output; option B<-si>.
536B<False>: do not scroll to bottom when tty receives output; option 573B<False>: do not scroll to bottom when tty receives output; option
537B<-si>. 574B<+si>.
538 575
539=item B<scrollWithBuffer:> I<boolean> 576=item B<scrollWithBuffer:> I<boolean>
540 577
541B<True>: scroll with scrollback buffer when tty recieves new lines (and 578B<True>: scroll with scrollback buffer when tty recieves new lines (and
542B<scrollTtyOutput> is False); option B<+sw>. B<False>: do not scroll 579B<scrollTtyOutput> is False); option B<+sw>. B<False>: do not scroll
543with scrollback buffer when tty recieves new lines; option B<-sw>. 580with scrollback buffer when tty recieves new lines; option B<-sw>.
544 581
545=item B<scrollTtyKeypress:> I<boolean> 582=item B<scrollTtyKeypress:> I<boolean>
546 583
547B<True>: scroll to bottom when a non-special key is pressed. Special 584B<True>: scroll to bottom when a non-special key is pressed. Special keys
548keys are those which are intercepted by rxvt for special handling and 585are those which are intercepted by rxvt-unicode for special handling and
549are not passed onto the shell; option B<-sk>. B<False>: do not scroll 586are not passed onto the shell; option B<-sk>. B<False>: do not scroll to
550to bottom when a non-special key is pressed; option B<+sk>. 587bottom when a non-special key is pressed; option B<+sk>.
551 588
552=item B<smallfont_key:> I<keysym> 589=item B<smallfont_key:> I<keysym>
553 590
554If enabled, use B<@@HOTKEY@@->I<keysym> to toggle to a smaller font 591If enabled, use B<@@HOTKEY@@->I<keysym> to toggle to a smaller font
555[default B<@@HOTKEY@@-@@SMALLFONT@@>] 592[default B<@@HOTKEY@@-@@SMALLFONT@@>]
575option B<-w>, B<-bw>, B<-borderwidth>. 612option B<-w>, B<-bw>, B<-borderwidth>.
576 613
577=item B<borderLess:> I<boolean> 614=item B<borderLess:> I<boolean>
578 615
579Set MWM hints to request a borderless window, i.e. if honoured by the 616Set MWM hints to request a borderless window, i.e. if honoured by the
580WM, the rxvt window will not have window decorations; option B<-bl>. 617WM, the rxvt-unicode window will not have window decorations; option B<-bl>.
581 618
582=item B<termName:> I<termname> 619=item B<termName:> I<termname>
583 620
584Specifies the terminal type name to be set in the B<TERM> environment 621Specifies the terminal type name to be set in the B<TERM> environment
585variable; option B<-tn>. 622variable; option B<-tn>.
676B<hyper>, B<super>, B<mod1>, B<mod2>, B<mod3>, B<mod4>, B<mod5>; option 713B<hyper>, B<super>, B<mod1>, B<mod2>, B<mod3>, B<mod4>, B<mod5>; option
677B<-mod>. 714B<-mod>.
678 715
679=item B<answerbackString:> I<string> 716=item B<answerbackString:> I<string>
680 717
681Specify the reply rxvt sends to the shell when an ENQ (control-E) 718Specify the reply rxvt-unicode sends to the shell when an ENQ (control-E)
682character is passed through. It may contain escape values as described 719character is passed through. It may contain escape values as described
683in the entry on B<keysym> following. 720in the entry on B<keysym> following.
684 721
685=item B<secondaryScreen:> I<bool> 722=item B<secondaryScreen:> I<bool>
686 723
823I<xterm>(1) where the colours are only swapped if they have not otherwise 860I<xterm>(1) where the colours are only swapped if they have not otherwise
824been specified. For example, 861been specified. For example,
825 862
826=over 4 863=over 4
827 864
828=item B<rxvt -fg Black -bg White -rv> 865=item B<@@RXVT_NAME@@ -fg Black -bg White -rv>
829 866
830would yield White on Black, while on I<xterm>(1) it would yield Black 867would yield White on Black, while on I<xterm>(1) it would yield Black
831on White. 868on White.
869
870=back
871
872=head1 FREQUENTLY ASKED QUESTIONS (FAQ)
873
874=over 4
875
876=item How do I know which rxvt-unicode version I'm using?
877
878The version number is displayed with the usage (-h). For rxvt-unicode
879version 2.14 and later, the escape sequence C<ESC[8n> sets the window
880title to the version number.
881
882=item Why do the characters look ugly?
883
884=item How does rxvt-unicode choose fonts?
885
886Most fonts do not contain the full range of Unicode, which is
887fine. Chances are that the font you (or the admin/package maintainer of
888your system/os) have specified does not cover all the characters you want
889to display.
890
891B<rxvt-unicode> makes a best-effort try at finding a replacement
892font. Often the result is fine, but sometimes the chosen font looks
893bad. In that case, select a font of your taste and add it to the font
894list, e.g.:
895
896 @@RXVT_NAME@@ -fn basefont,font2,font3...
897
898When rxvt-unicode sees a character, it will first look at the base
899font. If the base font does not contain the character, it will go to the
900next font, and so on.
901
902The only limitation is that all the fonts must not be larger than the base
903font, as the base font defines the principial cell size, which must be the
904same due to the way terminals work.
905
906=item Why do some chinese characters look so different than others?
907
908This is because there is a difference between script and language --
909rxvt-unicode does not know which language the text that is output
910is, as it only knows the unicode character codes. If rxvt-unicode
911first sees a japanese character, it might choose a japanese font for
912it. Subseqzuent japanese characters will take that font. Now, many chinese
913characters aren't represented in japanese fonts, so when the first
914non-japanese character comes up, rxvt-unicode will look for a chinese font
915-- unfortunately at this point, it will still use the japanese font for
916japanese characters that are also chinese.
917
918The workaround is easy: just tag a chinese font at the end of your font
919list (see the previous question). The key is to view the font list as
920a preference list: If you expect more japanese, list a japanese font
921first. If you expect more chinese, put a chinese font first.
922
923In the future it might be possible to switch preferences at runtime (the
924internal data structure has no problem with using different fonts for
925the same character at the same time, but no interface for this has been
926designed yet).
927
928=item Mouse cut/paste suddenly no longer works.
929
930Make sure that mouse reporting is actually turned off since killing
931some editors prematurely may leave the mouse in mouse report mode. I've
932heard that tcsh may use mouse reporting unless it otherwise specified. A
933quick check is to see if cut/paste works when the Alt or Shift keys are
934depressed. See @@RXVT_NAME@@(7)
935
936=item What's with this bold/blink stuff?
937
938If no bold colour is set via C<colorBD:>, bold will invert text using the
939standard foreground colour.
940
941For the standard background colour, blinking will actually make the
942text blink when compiled with C<--enable-blinking>. with standard
943colours. Without C<--enable-blinking>, the blink attribute will be
944ignored.
945
946On ANSI colours, bold/blink attributes are used to set high-intensity
947foreground/background colors.
948
949color0-7 are the low-intensity colors.
950
951color8-15 are the corresponding high-intensity colors.
952
953=item I don't like the screen colors. How do I change them?
954
955You can change the screen colors at run-time using F<~/.Xdefaults>
956resources (or as long-options).
957
958Here are values that are supposed to resemble a VGA screen,
959including the murky brown that passes for low-intensity yellow:
960
961 Rxvt*color0: #000000
962 Rxvt*color1: #A80000
963 Rxvt*color2: #00A800
964 Rxvt*color3: #A8A800
965 Rxvt*color4: #0000A8
966 Rxvt*color5: #A800A8
967 Rxvt*color6: #00A8A8
968 Rxvt*color7: #A8A8A8
969
970 Rxvt*color8: #000054
971 Rxvt*color9: #FF0054
972 Rxvt*color10: #00FF54
973 Rxvt*color11: #FFFF54
974 Rxvt*color12: #0000FF
975 Rxvt*color13: #FF00FF
976 Rxvt*color14: #00FFFF
977 Rxvt*color15: #FFFFFF
978
979=item What's with the strange Backspace/Delete key behaviour?
980
981Assuming that the physical Backspace key corresponds to the
982BackSpace keysym (not likely for Linux ... see the following
983question) there are two standard values that can be used for
984Backspace: C<^H> and C<^?>.
985
986Historically, either value is correct, but rxvt-unicode adopts the debian
987policy of using C<^?> when unsure, because it's the one only only correct
988choice :).
989
990Rxvt-unicode tries to inherit the current stty settings and uses the value
991of `erase' to guess the value for backspace. If rxvt-unicode wasn't
992started from a terminal (say, from a menu or by remote shell), then the
993system value of `erase', which corresponds to CERASE in <termios.h>, will
994be used (which may not be the same as your stty setting).
995
996For starting a new rxvt-unicode:
997
998 # use Backspace = ^H
999 $ stty erase ^H
1000 $ @@RXVT_NAME@@
1001
1002 # use Backspace = ^?
1003 $ stty erase ^?
1004 $ @@RXVT_NAME@@
1005
1006Toggle with "ESC[36h" / "ESC[36l" as documented in @@RXVT_NAME@@(7).
1007
1008For an existing rxvt-unicode:
1009
1010 # use Backspace = ^H
1011 $ stty erase ^H
1012 $ echo -n "^[[36h"
1013
1014 # use Backspace = ^?
1015 $ stty erase ^?
1016 $ echo -n "^[[36l"
1017
1018This helps satisfy some of the Backspace discrepancies that occur, but
1019if you use Backspace = C<^H>, make sure that the termcap/terminfo value
1020properly reflects that.
1021
1022The Delete key is a another casualty of the ill-defined Backspace problem.
1023To avoid confusion between the Backspace and Delete keys, the Delete
1024key has been assigned an escape sequence to match the vt100 for Execute
1025(ESC[3~) and is in the supplied termcap/terminfo.
1026
1027Some other Backspace problems:
1028
1029some editors use termcap/terminfo,
1030some editors (vim I'm told) expect Backspace = ^H,
1031GNU Emacs (and Emacs-like editors) use ^H for help.
1032
1033Perhaps someday this will all be resolved in a consistent manner.
1034
1035=item I don't like the key-bindings. How do I change them?
1036
1037There are some compile-time selections available via configure. Unless
1038you have run "configure" with the C<--disable-resources> option you can
1039use the `keysym' resource to alter the keystrings associated with keysym
10400xFF00 - 0xFFFF (function, cursor keys, etc).
1041
1042Here's an example for a tn3270 session started using `@@RXVT_NAME@@ -name tn3270'
1043
1044 !# ----- special uses ------:
1045 ! tn3270 login, remap function and arrow keys.
1046 tn3270*font: *clean-bold-*-*--15-*
1047
1048 ! keysym - used by rxvt only
1049 ! Delete - ^D
1050 tn3270*keysym.0xFFFF: \004
1051
1052 ! Home - ^A
1053 tn3270*keysym.0xFF50: \001
1054 ! Left - ^B
1055 tn3270*keysym.0xFF51: \002
1056 ! Up - ^P
1057 tn3270*keysym.0xFF52: \020
1058 ! Right - ^F
1059 tn3270*keysym.0xFF53: \006
1060 ! Down - ^N
1061 tn3270*keysym.0xFF54: \016
1062 ! End - ^E
1063 tn3270*keysym.0xFF57: \005
1064
1065 ! F1 - F12
1066 tn3270*keysym.0xFFBE: \e1
1067 tn3270*keysym.0xFFBF: \e2
1068 tn3270*keysym.0xFFC0: \e3
1069 tn3270*keysym.0xFFC1: \e4
1070 tn3270*keysym.0xFFC2: \e5
1071 tn3270*keysym.0xFFC3: \e6
1072 tn3270*keysym.0xFFC4: \e7
1073 tn3270*keysym.0xFFC5: \e8
1074 tn3270*keysym.0xFFC6: \e9
1075 tn3270*keysym.0xFFC7: \e0
1076 tn3270*keysym.0xFFC8: \e-
1077 tn3270*keysym.0xFFC9: \e=
1078
1079 ! map Prior/Next to F7/F8
1080 tn3270*keysym.0xFF55: \e7
1081 tn3270*keysym.0xFF56: \e8
1082
1083=item I'm using keyboard model XXX that has extra Prior/Next/Insert keys.
1084How do I make use of them? For example, the Sun Keyboard type 4
1085has the following mappings that rxvt-unicode doesn't recognize.
1086
1087 KP_Insert == Insert
1088 F22 == Print
1089 F27 == Home
1090 F29 == Prior
1091 F33 == End
1092 F35 == Next
1093
1094Rather than have rxvt-unicode try to accomodate all the various possible keyboard
1095mappings, it is better to use `xmodmap' to remap the keys as required for
1096your particular machine.
1097
1098=item How do I distinguish if I'm running rxvt-unicode or a regular xterm?
1099I need this to decide about setting colors etc.
1100
1101rxvt and rxvt-unicode always export the variable "COLORTERM", so you can
1102check and see if that is set. Note that several programs, JED, slrn,
1103Midnight Commander automatically check this variable to decide whether or
1104not to use color.
1105
1106=item How do I set the correct, full IP address for the DISPLAY variable?
1107
1108If you've compiled rxvt-unicode with DISPLAY_IS_IP and ahve enabled
1109insecure mode then it is possible to use the following shell script
1110snippets to correctly set the display. If your version of rxvt-unicode
1111wasn't also compiled with ESCZ_ANSWER (as assumed in these snippets) then
1112the COLORTERM variable can be used to distinguish rxvt-unicode from a
1113regular xterm.
1114
1115Courtesy of Chuck Blake <cblake@BBN.COM> with the following shell script
1116snippets:
1117
1118 # Bourne/Korn/POSIX family of shells:
1119 [ ${TERM:-foo} = foo ] && TERM=xterm # assume an xterm if we don't know
1120 if [ ${TERM:-foo} = xterm ]; then
1121 stty -icanon -echo min 0 time 15 # see if enhanced rxvt or not
1122 echo -n '^[Z'
1123 read term_id
1124 stty icanon echo
1125 if [ ""${term_id} = '^[[?1;2C' -a ${DISPLAY:-foo} = foo ]; then
1126 echo -n '^[[7n' # query the rxvt we are in for the DISPLAY string
1127 read DISPLAY # set it in our local shell
1128 fi
1129 fi
1130
1131=item How do I compile the manual pages for myself?
1132
1133You need to have a recent version of perl installed as F</usr/bin/perl>,
1134one that comes with F<pod2man>, F<pod2text> and F<pod2html>. Then go to
1135the doc subdirectory and enter C<make alldoc>.
832 1136
833=back 1137=back
834 1138
835=head1 ENVIRONMENT 1139=head1 ENVIRONMENT
836 1140
853 1157
854Color names. 1158Color names.
855 1159
856=back 1160=back
857 1161
858=head1 SEEALSO 1162=head1 SEE ALSO
859 1163
860I<xterm>(1), I<sh>(1), I<resize>(1), I<X>(1), I<pty>(4), I<tty>(4), I<utmp>(5) 1164@@RXVT_NAME@@(7), xterm(1), sh(1), resize(1), X(1), pty(4), tty(4), utmp(5)
861
862See rxvtRef.html rxvtRef.txt for detailed information on recognized escape sequences and menuBar syntax, etc.
863 1165
864=head1 BUGS 1166=head1 BUGS
865 1167
866Check the BUGS file for an up-to-date list. 1168Check the BUGS file for an up-to-date list.
867 1169

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines