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.43 by root, Sun Jan 16 19:22:16 2005 UTC vs.
Revision 1.56 by root, Mon Feb 14 18:47:54 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
328 330
329Compile I<XIM>: input method name. resource B<inputMethod>. 331Compile I<XIM>: input method name. resource B<inputMethod>.
330 332
331=item B<-imlocale> I<string> 333=item B<-imlocale> I<string>
332 334
333The locale to use for opening the IM. You can use an LC_CTYPE of e.g. 335The locale to use for opening the IM. You can use an C<LC_CTYPE> of e.g.
334de_DE.UTF-8 for normal text processing but ja_JP.EUC-JP for the input 336C<de_DE.UTF-8> for normal text processing but C<ja_JP.EUC-JP> for the
335extension to be able to input japanese characters while staying in 337input extension to be able to input japanese characters while staying in
336another locale. 338another locale. resource B<imLocale>.
339
340=item B<-imfont> I<fontset>
341
342Set the font set to use for the X Input Method, see resource B<imFont>
343for more info.
344
345=item B<-tcw>
346
347Change the meaning of triple-click selection with the left mouse
348button. Instead of selecting a full line it will extend the selection the
349end of the logical line only. resource B<tripleclickwords>.
337 350
338=item B<-insecure> 351=item B<-insecure>
339 352
340Enable "insecure" mode, which currently enables most of the escape 353Enable "insecure" mode, which currently enables most of the escape
341sequences that echo strings. See the resource B<insecure> for more 354sequences that echo strings. See the resource B<insecure> for more
355=item B<-ssr>|B<+ssr> 368=item B<-ssr>|B<+ssr>
356 369
357Turn on/off secondary screen scroll (default enabled); resource 370Turn on/off secondary screen scroll (default enabled); resource
358B<secondaryScroll>. 371B<secondaryScroll>.
359 372
360=item B<-xrm> I<resourcestring> 373=item B<-keysym.>I<sym>: I<string>
361 374
362No effect on rxvt-unicode. Simply passes through an argument to be made 375Remap a key symbol. See resource B<keysym>.
363available in the instance's argument list. Appears in I<WM_COMMAND> in 376
364some window managers. 377=item B<-embed>: I<windowid>
378
379Tells @@RXVT_NAME@@ to embed it's windows into an already-existing window,
380which enables applications to easily embed a terminal.
381
382Right now, @@RXVT_NAME@@ will first unmap/map the specified window, so it
383shouldn't be a top-level window. @@RXVT_NAME@@ will also reconfigure it
384quite a bit, so don't expect it to keep some specific state. It's best to
385create an extra subwindow for @@RXVT_NAME@@ and leave it alone.
386
387It might be useful to know that @@RXVT_NAME@@ will not close file
388descriptors passed to it (except for stdin/out/err, of course), so you
389can use file descriptors to communicate with the programs within the
390terminal. This works regardless of wether the C<-embed> option was used or
391not.
365 392
366=back 393=back
367 394
368=head1 RESOURCES (available also as long-options) 395=head1 RESOURCES (available also as long-options)
369 396
372 399
373There are two different methods that @@RXVT_NAME@@ can use to get the 400There are two different methods that @@RXVT_NAME@@ can use to get the
374Xresource data: using the X libraries (Xrm*-functions) or internal 401Xresource data: using the X libraries (Xrm*-functions) or internal
375Xresources reader (B<~/.Xdefaults>). For the first method (ie. 402Xresources reader (B<~/.Xdefaults>). For the first method (ie.
376B<@@RXVT_NAME@@ -h> lists B<XGetDefaults>), you can set and change the 403B<@@RXVT_NAME@@ -h> lists B<XGetDefaults>), you can set and change the
377resources using X11 tools like B<xset>. Many distribution do also load 404resources using X11 tools like B<xrdb>. Many distribution do also load
378settings from the B<~/.Xresources> file when X starts. 405settings from the B<~/.Xresources> file when X starts. @@RXVT_NAME@@
406will consult the following files/resources in order, with later settings
407overwriting earlier ones:
408
409 1. system-wide app-defaults file, either locale-dependent OR global
410 2. app-defaults file in $XAPPLRESDIR
411 3. RESOURCE_MANAGER property on root-window OR $HOME/.Xdefaults
412 4. SCREEN_RESOURCES for the current screen
413 5. $XENVIRONMENT file OR $HOME/.Xdefaults-<nodename>
379 414
380If compiled with internal Xresources support (i.e. B<@@RXVT_NAME@@ -h> 415If compiled with internal Xresources support (i.e. B<@@RXVT_NAME@@ -h>
381lists B<.Xdefaults>) then B<@@RXVT_NAME@@> accepts application defaults 416lists B<.Xdefaults>) then B<@@RXVT_NAME@@> accepts application defaults
382set in XAPPLOADDIR/URxvt (compile-time defined: usually 417set in XAPPLOADDIR/URxvt (compile-time defined: usually
383B</usr/lib/X11/app-defaults/URxvt>) and resources set in 418B</usr/lib/X11/app-defaults/URxvt>) and resources set in
775 810
776I<name> of inputMethod to use; option B<-im>. 811I<name> of inputMethod to use; option B<-im>.
777 812
778=item B<imLocale:> I<name> 813=item B<imLocale:> I<name>
779 814
780The locale to use for opening the IM. You can use an LC_CTYPE of e.g. 815The locale to use for opening the IM. You can use an C<LC_CTYPE> of e.g.
781de_DE.UTF-8 for normal text processing but ja_JP.EUC-JP for the input 816C<de_DE.UTF-8> for normal text processing but C<ja_JP.EUC-JP> for the
782extension to be able to input japanese characters while staying in 817input extension to be able to input japanese characters while staying in
783another locale. option B<-imlocale>. 818another locale. option B<-imlocale>.
819
820=item B<imFont:> I<fontset>
821
822Specify the font-set used for XIM styles C<OverTheSpot> or
823C<OffTheSpot>. It must be a standard X font set (XLFD patterns separated
824by commas), i.e. it's not in the same format as the other font lists used
825in @@RXVT_NAME@@. The default will be set-up to chose *any* suitable found
826found, preferably one or two pixels differing in size to the base font.
827option B<-imfont>.
828
829=item B<tripleclickwords:> I<boolean>
830
831Change the meaning of triple-click selection with the left mouse
832button. Instead of selecting a full line it will extend the selection to
833the end of the logical line only. option B<-tcw>.
784 834
785=item B<insecure:> I<boolean> 835=item B<insecure:> I<boolean>
786 836
787Enables "insecure" mode. Rxvt-unicode offers some escape sequences that 837Enables "insecure" mode. Rxvt-unicode offers some escape sequences that
788echo arbitrary strings like the icon name or the locale. This could be 838echo arbitrary strings like the icon name or the locale. This could be
829and the abbreviated B<I>, B<K>, B<C>, B<N>, B<S>, B<M>, B<A>, B<L>, B<1>, 879and the abbreviated B<I>, B<K>, B<C>, B<N>, B<S>, B<M>, B<A>, B<L>, B<1>,
830B<2>, B<3>, B<4>, B<5>. 880B<2>, B<3>, B<4>, B<5>.
831 881
832The B<NumLock>, B<Meta> and B<ISOLevel3> modifiers are usually aliased to 882The B<NumLock>, B<Meta> and B<ISOLevel3> modifiers are usually aliased to
833whatever modifier the NumLock key, Meta/Alt keys or ISO Level3 Shift/AltGr 883whatever modifier the NumLock key, Meta/Alt keys or ISO Level3 Shift/AltGr
834keys are being mapped. B<AppKeypad> is a artificial modifier mapped to the 884keys are being mapped. B<AppKeypad> is a synthetic modifier mapped to the
835current application keymap mode state. 885current application keymap mode state.
836 886
837The spellings of I<key> can be obtained by using B<xev>(1) command or 887The spellings of I<key> can be obtained by using B<xev>(1) command or
838searching keysym macros from B</usr/X11R6/include/X11/keysymdef.h> and 888searching keysym macros from B</usr/X11R6/include/X11/keysymdef.h> and
839omitting the prefix B<XK_>. Alternatively you can specify I<key> by its hex 889omitting the prefix B<XK_>. Alternatively you can specify I<key> by its hex
844C<\e>, C<\E>: escape, C<\n>: newline, C<\r>: carriage return, C<\t>: tab, 894C<\e>, C<\E>: escape, C<\n>: newline, C<\r>: carriage return, C<\t>: tab,
845C<\000>: octal number) or verbatim control characters (C<^?>: delete, 895C<\000>: octal number) or verbatim control characters (C<^?>: delete,
846C<^@>: null, C<^A> ...) and may be enclosed with double quotes so that it 896C<^@>: null, C<^A> ...) and may be enclosed with double quotes so that it
847can start or end with whitespace. 897can start or end with whitespace.
848 898
899Please note that you need to double the C<\> when using
900C<--enable-xgetdefault>, as X itself does it's own de-escaping (you can
901use C<\033> instead of C<\e> (and so on), which will work with both Xt and
902@@RXVT_NAME@@'s own processing).
903
849You can define a range of keysyms in one shot by providing a I<string> 904You can define a range of keysyms in one shot by providing a I<string>
850with pattern B<list/PREFIX/MIDDLE/SUFFIX>, where the delimeter `/' 905with pattern B<list/PREFIX/MIDDLE/SUFFIX>, where the delimeter `/'
851should be a character not used by the strings. 906should be a character not used by the strings.
852 907
853Its usage can be demonstrated by an example: 908Its usage can be demonstrated by an example:
854 909
855 URxvt.keysym.M-C-0x61: list|\e<M-C-|abc|> 910 URxvt.keysym.M-C-0x61: list|\033<M-C-|abc|>
856 911
857The above line is equivalent to the following three lines: 912The above line is equivalent to the following three lines:
858 913
859 URxvt.keysym.Meta-Control-0x61: \e<M-C-a> 914 URxvt.keysym.Meta-Control-0x61: \033<M-C-a>
860 URxvt.keysym.Meta-Control-0x62: \e<M-C-b> 915 URxvt.keysym.Meta-Control-0x62: \033<M-C-b>
861 URxvt.keysym.Meta-Control-0x63: \e<M-C-c> 916 URxvt.keysym.Meta-Control-0x63: \033<M-C-c>
862 917
863If I<string> takes the form of C<proto:STRING>, the specified B<STRING> is 918If I<string> takes the form of C<command:STRING>, the specified B<STRING>
864interpreted and executed as @@RXVT_NAME@@'s control sequence. For example, 919is interpreted and executed as @@RXVT_NAME@@'s control sequence. For
865C<proto:\033]701;zh_CN.GBK\007> means: change the current locale to 920example the following means "change the current locale to C<zh_CN.GBK>
866C<zh_CN.GBK>. 921when Control-Meta-c is being pressed":
922
923 URxvt.keysym.M-C-c: command:\033]701;zh_CN.GBK\007
924
925The following example will map Control-Meta-1 and Control-Meta-2 to
926the fonts C<suxuseuro> and C<9x15bold>, so you can have some limited
927font-switching at runtime:
928
929 URxvt.keysym.M-C-1: command:\033]50;suxuseuro\007
930 URxvt.keysym.M-C-2: command:\033]50;9x15bold\007
931
932Other things are possible, e.g. resizing (see @@RXVT_NAME@@(7) for more
933info):
934
935 URxvt.keysym.M-C-3: command:\033[8;25;80t
936 URxvt.keysym.M-C-4: command:\033[8;48;110t
867 937
868=back 938=back
869 939
870=head1 THE SCROLLBAR 940=head1 THE SCROLLBAR
871 941
885the normal text selection/insertion, hold either the Shift or the Meta 955the normal text selection/insertion, hold either the Shift or the Meta
886(Alt) key while performing the desired mouse action. 956(Alt) key while performing the desired mouse action.
887 957
888If mouse reporting mode is active, the normal scrollbar actions are 958If mouse reporting mode is active, the normal scrollbar actions are
889disabled -- on the assumption that we are using a fullscreen 959disabled -- on the assumption that we are using a fullscreen
890application. Instead, pressing Button1 and Button3 sends B<ESC[6~> 960application. Instead, pressing Button1 and Button3 sends B<ESC [ 6 ~>
891(Next) and B<ESC[5~> (Prior), respectively. Similarly, clicking on the 961(Next) and B<ESC [ 5 ~> (Prior), respectively. Similarly, clicking on the
892up and down arrows sends B<ESC[A> (Up) and B<ESC[B> (Down), 962up and down arrows sends B<ESC [ A> (Up) and B<ESC [ B> (Down),
893respectively. 963respectively.
894 964
895=head1 TEXT SELECTION AND INSERTION 965=head1 TEXT SELECTION AND INSERTION
896 966
897The behaviour of text selection and insertion mechanism is similar to 967The behaviour of text selection and insertion mechanism is similar to
899 969
900=over 4 970=over 4
901 971
902=item B<Selection>: 972=item B<Selection>:
903 973
904Left click at the beginning of the region, drag to the end of the 974Left click at the beginning of the region, drag to the end of the region
905region and release; Right click to extend the marked region; Left 975and release; Right click to extend the marked region; Left double-click
906double-click to select a word; Left triple-click to select the entire 976to select a word; Left triple-click to select the entire logical line
907line. 977(which can span multiple screen lines), unless modified by resource
978B<tripleclickwords>.
908 979
909Starting a selection while pressing the B<Meta> key (or B<Meta+Ctrl> keys) 980Starting a selection while pressing the B<Meta> key (or B<Meta+Ctrl> keys)
910(Compile: I<frills>) will create a rectangular selection instead of a normal 981(Compile: I<frills>) will create a rectangular selection instead of a normal
911one. 982one.
912 983
938C<--enable-frills>, the rest is available when rxvt-unicode was compiled 1009C<--enable-frills>, the rest is available when rxvt-unicode was compiled
939with C<--enable-iso14755>. 1010with C<--enable-iso14755>.
940 1011
941=over 4 1012=over 4
942 1013
943=item 5.1: Basic method 1014=item * 5.1: Basic method
944 1015
945This allows you to enter unicode characters using their hexcode. 1016This allows you to enter unicode characters using their hexcode.
946 1017
947Start by pressing and holding both C<Control> and C<Shift>, then enter 1018Start by pressing and holding both C<Control> and C<Shift>, then enter
948hex-digits (between one and six). Releasing C<Control> and C<Shift> will 1019hex-digits (between one and six). Releasing C<Control> and C<Shift> will
955address, which you cannot type. Fortunately, the card has the e-mail 1026address, which you cannot type. Fortunately, the card has the e-mail
956address printed as hexcodes, e.g. C<671d 65e5>. You can enter this easily 1027address printed as hexcodes, e.g. C<671d 65e5>. You can enter this easily
957by pressing C<Control> and C<Shift>, followed by C<6-7-1-D-SPACE-6-5-E-5>, 1028by pressing C<Control> and C<Shift>, followed by C<6-7-1-D-SPACE-6-5-E-5>,
958followed by releasing the modifier keys. 1029followed by releasing the modifier keys.
959 1030
960=item 5.2: Keyboard symbols entry method 1031=item * 5.2: Keyboard symbols entry method
961 1032
962This mode lets you input characters representing the keycap symbols of 1033This mode lets you input characters representing the keycap symbols of
963your keyboard, if representable in the current locale encoding. 1034your keyboard, if representable in the current locale encoding.
964 1035
965Start by pressing C<Control> and C<Shift> together, then releasing 1036Start by pressing C<Control> and C<Shift> together, then releasing
968keycap symbol. The symbol will only be entered when the key has been 1039keycap symbol. The symbol will only be entered when the key has been
969released, otherwise pressing e.g. C<Shift> would enter the symbol for 1040released, otherwise pressing e.g. C<Shift> would enter the symbol for
970C<ISO Level 2 Switch>, although your intention might have been to enter a 1041C<ISO Level 2 Switch>, although your intention might have been to enter a
971reverse tab (Shift-Tab). 1042reverse tab (Shift-Tab).
972 1043
973=item 5.3: Screen-selection entry method 1044=item * 5.3: Screen-selection entry method
974 1045
975While this is implemented already (it's basically the selection 1046While this is implemented already (it's basically the selection
976mechanism), it could be extended by displaying a unicode character map. 1047mechanism), it could be extended by displaying a unicode character map.
977 1048
978=item 5.4: Feedback method for identifying displayed characters for later input 1049=item * 5.4: Feedback method for identifying displayed characters for later input
979 1050
980This method lets you display the unicode character code associated with 1051This method lets you display the unicode character code associated with
981characters already displayed. 1052characters already displayed.
982 1053
983You enter this mode by holding down C<Control> and C<Shift> together, then 1054You enter this mode by holding down C<Control> and C<Shift> together, then
995With respect to conformance, rxvt-unicode is supposed to be compliant to 1066With respect to conformance, rxvt-unicode is supposed to be compliant to
996both scenario A and B of ISO 14755, including part 5.2. 1067both scenario A and B of ISO 14755, including part 5.2.
997 1068
998=head1 LOGIN STAMP 1069=head1 LOGIN STAMP
999 1070
1000B<@@RXVT_NAME@@> tries to write an entry into the I<utmp>(5) file so 1071B<@@RXVT_NAME@@> tries to write an entry into the I<utmp>(5) file so that
1001that it can be seen via the I<who(1)> command, and can accept messages. 1072it can be seen via the I<who(1)> command, and can accept messages. To
1002To allow this feature, B<@@RXVT_NAME@@> must be installed setuid root on 1073allow this feature, B<@@RXVT_NAME@@> may need to be installed setuid root
1003some systems. 1074on some systems or setgid to root or to some other group on others.
1004 1075
1005=head1 COLORS AND GRAPHICS 1076=head1 COLORS AND GRAPHICS
1006 1077
1007In addition to the default foreground and background colours, 1078In addition to the default foreground and background colours,
1008B<@@RXVT_NAME@@> can display up to 16 colours (8 ANSI colours plus 1079B<@@RXVT_NAME@@> can display up to 16 colours (8 ANSI colours plus
1051 1122
1052=back 1123=back
1053 1124
1054=head1 ENVIRONMENT 1125=head1 ENVIRONMENT
1055 1126
1056B<@@RXVT_NAME@@> sets the environment variables B<TERM>, B<COLORTERM> 1127B<@@RXVT_NAME@@> sets and/or uses the following environment variables:
1057and B<COLORFGBG>. The environment variable B<WINDOWID> is set to the X 1128
1058window id number of the B<@@RXVT_NAME@@> window and it also uses and 1129=over 4
1059sets the environment variable B<DISPLAY> to specify which display 1130
1060terminal to use. B<@@RXVT_NAME@@> uses the environment variables 1131=item B<TERM>
1061B<RXVTPATH> and B<PATH> to find XPM files. 1132
1133Normally set to C<rxvt-unicode>, unless overwritten at configure time, via
1134resources or on the commandline.
1135
1136=item B<COLORTERM>
1137
1138Either C<rxvt>, C<rxvt-xpm>, depending on wether @@RXVT_NAME@@ was
1139compiled with XPM support, and optionally with the added extension
1140C<-mono> to indicate that rxvt-unicode runs on a monochrome screen.
1141
1142=item B<COLORFGBG>
1143
1144Set to a string of the form C<fg;bg> or C<fg;xpm;bg>, where C<fg> is
1145the colour code used as default foreground/text colour (or the string
1146C<default> to indicate that the default-colour escape sequence is to be
1147used), C<bg> is the colour code used as default background colour (or the
1148string C<default>), and C<xpm> is the string C<default> if @@RXVT_NAME@@
1149was compiled with XPM support. Libraries like C<ncurses> and C<slang> can
1150(and do) use this information to optimize screen output.
1151
1152=item B<WINDOWID>
1153
1154Set to the (decimal) X Window ID of the @@RXVT_NAME@@ window (the toplevel
1155window, which usually has subwindows for the scrollbar, the terminal
1156window and so on).
1157
1158=item B<TERMINFO>
1159
1160Set to the terminfo directory iff @@RXVT_NAME@@ was configured with
1161C<--with-terminfo=PATH>.
1162
1163=item B<DISPLAY>
1164
1165Used by @@RXVT_NAME@@ to connect to the display and set to the correct
1166display in it's child processes.
1167
1168=item B<SHELL>
1169
1170The shell to be used for command execution, defaults to C</bin/sh>.
1171
1172=item B<RXVTPATH>
1173
1174The path where @@RXVT_NAME@@ looks for support files such as menu and xpm
1175files.
1176
1177=item B<PATH>
1178
1179Used in the same way as C<RXVTPATH>.
1180
1181=item B<RXVT_SOCKET>
1182
1183The unix domain socket path used by @@RXVT_NAME@@c(1) and
1184@@RXVT_NAME@@d(1).
1185
1186Default C<< $HOME/.rxvt-unicode-<nodename >>.
1187
1188=item B<HOME>
1189
1190Used to locate the default directory for the unix domain socket for
1191daemon communications and to locate various resource files (such as
1192C<.Xdefaults>)
1193
1194=item B<XAPPLRESDIR>
1195
1196Directory where various X resource files are being located.
1197
1198=item B<XENVIRONMENT>
1199
1200If set and accessible, gives the name of a X resource file to be loaded by
1201@@RXVT_NAME@@.
1202
1203=back
1062 1204
1063=head1 FILES 1205=head1 FILES
1064 1206
1065=over 4 1207=over 4
1066 1208
1067=item B</etc/utmp>
1068
1069System file for login records.
1070
1071=item B</usr/lib/X11/rgb.txt> 1209=item B</usr/lib/X11/rgb.txt>
1072 1210
1073Color names. 1211Color names.
1074 1212
1075=back 1213=back
1090 1228
1091=over 4 1229=over 4
1092 1230
1093=item Project Coordinator 1231=item Project Coordinator
1094 1232
1095@@RXVT_MAINT@@ L<@@RXVT_MAINTEMAIL@@> 1233Marc A. Lehmann L<< <rxvt-unicode@schmorp.de> >>
1096 1234
1097=item Web page maintainter 1235L<http://software.schmorp.de/#rxvt-unicode>
1098
1099@@RXVT_WEBMAINT@@ L<@@RXVT_WEBMAINTEMAIL@@>
1100
1101L<@@RXVT_WEBPAGE@@>
1102 1236
1103=back 1237=back
1104 1238
1105=head1 AUTHORS 1239=head1 AUTHORS
1106 1240
1131=item Geoff Wing L<< <gcw@pobox.com> >> 1265=item Geoff Wing L<< <gcw@pobox.com> >>
1132 1266
1133Rewrote screen display and text selection routines. Project Coordinator 1267Rewrote screen display and text selection routines. Project Coordinator
1134(changes.txt 2.4.6 - rxvt-unicode) 1268(changes.txt 2.4.6 - rxvt-unicode)
1135 1269
1136=item Marc Alexander Lehmann L<< <rxvt@schmorp.de> >> 1270=item Marc Alexander Lehmann L<< <rxvt-unicode@schmorp.de> >>
1137 1271
1138Forked rxvt-unicode, rewrote most of the display code and internal 1272Forked rxvt-unicode, rewrote most of the display code and internal
1139character handling to store text in unicode, improve xterm 1273character handling to store text in unicode, improve xterm
1140compatibility and apply numerous other bugfixes and extensions. 1274compatibility and apply numerous other bugfixes and extensions.
1141 1275

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines