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.225 by sf-exg, Wed Jun 5 07:58:17 2013 UTC vs.
Revision 1.243 by root, Sat May 30 21:02:05 2015 UTC

108of graphical corruption. This is harmless, but we can't do anything about 108of graphical corruption. This is harmless, but we can't do anything about
109this, so watch out] 109this, so watch out]
110 110
111=item B<-visual> I<visualID> 111=item B<-visual> I<visualID>
112 112
113Compile I<frills>: Use the given visual (see e.g. C<xdpyinfo> for possible 113Compile I<frills>: Use the given visual (see e.g. C<xdpyinfo> for
114visual ids). 114possible visual ids) instead of the default, and also allocate a private
115colormap. All visual types except for DirectColor are supported.
115 116
116=item B<-geometry> I<geom> 117=item B<-geometry> I<geom>
117 118
118Window geometry (B<-g> still respected); resource B<geometry>. 119Window geometry (B<-g> still respected); resource B<geometry>.
119 120
219 220
220=item B<-ls>|B<+ls> 221=item B<-ls>|B<+ls>
221 222
222Start as a login-shell/sub-shell; resource B<loginShell>. 223Start as a login-shell/sub-shell; resource B<loginShell>.
223 224
225=item B<-mc> I<milliseconds>
226
227Specify the maximum time between multi-click selections.
228
224=item B<-ut>|B<+ut> 229=item B<-ut>|B<+ut>
225 230
226Compile I<utmp>: Inhibit/enable writing a utmp entry; resource 231Compile I<utmp>: Inhibit/enable writing a utmp entry; resource
227B<utmpInhibit>. 232B<utmpInhibit>.
228 233
306 311
307=item B<-override-redirect> 312=item B<-override-redirect>
308 313
309Compile I<frills>: Sets override-redirect on the window; resource 314Compile I<frills>: Sets override-redirect on the window; resource
310B<override-redirect>. 315B<override-redirect>.
316
317=item B<-dockapp>
318
319Sets the initial state of the window to WithdrawnState, which makes
320window managers that support this extension treat it as a dockapp.
311 321
312=item B<-sbg> 322=item B<-sbg>
313 323
314Compile I<frills>: Disable the usage of the built-in block graphics/line 324Compile I<frills>: Disable the usage of the built-in block graphics/line
315drawing characters and just rely on what the specified fonts provide. Use 325drawing characters and just rely on what the specified fonts provide. Use
369 379
370=item B<-pt> I<style> 380=item B<-pt> I<style>
371 381
372Compile I<XIM>: input style for input method; B<OverTheSpot>, 382Compile I<XIM>: input style for input method; B<OverTheSpot>,
373B<OffTheSpot>, B<Root>; resource B<preeditType>. 383B<OffTheSpot>, B<Root>; resource B<preeditType>.
384
385If the perl extension C<xim-onthespot> is used (which is the default),
386then additionally the C<OnTheSpot> preedit type is available.
374 387
375=item B<-im> I<text> 388=item B<-im> I<text>
376 389
377Compile I<XIM>: input method name. resource B<inputMethod>. 390Compile I<XIM>: input method name. resource B<inputMethod>.
378 391
781 794
782B<True>: start as a login shell by prepending a `-' to B<argv[0]> of 795B<True>: start as a login shell by prepending a `-' to B<argv[0]> of
783the shell; option B<-ls>. B<False>: start as a normal sub-shell 796the shell; option B<-ls>. B<False>: start as a normal sub-shell
784[default]; option B<+ls>. 797[default]; option B<+ls>.
785 798
799=item B<multiClickTime:> I<number>
800
801Specify the maximum time in milliseconds between multi-click select
802events. The default is 500 milliseconds; option B<-mc>.
803
786=item B<utmpInhibit:> I<boolean> 804=item B<utmpInhibit:> I<boolean>
787 805
788B<True>: inhibit writing record into the system log file B<utmp>; 806B<True>: inhibit writing record into the system log file B<utmp>;
789option B<-ut>. B<False>: write record into the system log file B<utmp> 807option B<-ut>. B<False>: write record into the system log file B<utmp>
790[default]; option B<+ut>. 808[default]; option B<+ut>.
962 980
963B<< BACKSLASH `"'&()*,;<=>?@[]^{|} >> 981B<< BACKSLASH `"'&()*,;<=>?@[]^{|} >>
964 982
965=item B<preeditType:> I<style> 983=item B<preeditType:> I<style>
966 984
967B<OverTheSpot>, B<OffTheSpot>, B<Root>; option B<-pt>. 985B<OnTheSpot>, B<OverTheSpot>, B<OffTheSpot>, B<Root>; option B<-pt>.
968 986
969=item B<inputMethod:> I<name> 987=item B<inputMethod:> I<name>
970 988
971I<name> of inputMethod to use; option B<-im>. 989I<name> of inputMethod to use; option B<-im>.
972 990
1041Sets the working directory for the shell (or the command specified via 1059Sets the working directory for the shell (or the command specified via
1042B<-e>). The I<path> must be an absolute path and it must exist for 1060B<-e>). The I<path> must be an absolute path and it must exist for
1043@@RXVT_NAME@@ to start. If it isn't specified then the current working 1061@@RXVT_NAME@@ to start. If it isn't specified then the current working
1044directory will be used; option B<-cd>. 1062directory will be used; option B<-cd>.
1045 1063
1046=item B<keysym.>I<sym>: I<string> 1064=item B<keysym.>I<sym>: I<action>
1047 1065
1048Compile I<frills>: Associate I<string> with keysym I<sym>. The 1066Compile I<frills>: Associate I<action> with keysym I<sym>. The intervening
1049intervening resource name B<keysym.> cannot be omitted. 1067resource name B<keysym.> cannot be omitted.
1050 1068
1051The format of I<sym> is "I<(modifiers-)key>", where I<modifiers> can be 1069Using this resource, you can map key combinations such as
1052any combination of B<ISOLevel3>, B<AppKeypad>, B<Control>, B<NumLock>, 1070C<Ctrl-Shift-BackSpace> to various actions, such as outputting a different
1053B<Shift>, B<Meta>, B<Lock>, B<Mod1>, B<Mod2>, B<Mod3>, B<Mod4>, B<Mod5>, 1071string than would normally result from that combination, making the
1054and the abbreviated B<I>, B<K>, B<C>, B<N>, B<S>, B<M>, B<A>, B<L>, B<1>, 1072terminal scroll up or down the way you want it, or any other thing an
1055B<2>, B<3>, B<4>, B<5>. 1073extension might provide.
1074
1075The key combination that triggers the action, I<sym>, has the following format:
1076
1077 (modifiers-)key
1078
1079Where I<modifiers> can be any combination of B<ISOLevel3>, B<AppKeypad>,
1080B<Control>, B<NumLock>, B<Shift>, B<Meta>, B<Lock>, B<Mod1>, B<Mod2>,
1081B<Mod3>, B<Mod4>, B<Mod5>, and the abbreviated B<I>, B<K>, B<C>, B<N>,
1082B<S>, B<M>, B<A>, B<L>, B<1>, B<2>, B<3>, B<4>, B<5>.
1056 1083
1057The B<NumLock>, B<Meta> and B<ISOLevel3> modifiers are usually aliased to 1084The B<NumLock>, B<Meta> and B<ISOLevel3> modifiers are usually aliased to
1058whatever modifier the NumLock key, Meta/Alt keys or ISO Level3 Shift/AltGr 1085whatever modifier the NumLock key, Meta/Alt keys or ISO Level3 Shift/AltGr
1059keys are being mapped. B<AppKeypad> is a synthetic modifier mapped to the 1086keys are being mapped. B<AppKeypad> is a synthetic modifier mapped to the
1060current application keymap mode state. 1087current application keymap mode state.
1061 1088
1062The spellings of I<key> can be obtained by using B<xev>(1) command or 1089Due the the large number of modifier combinations, a key mapping will
1063searching keysym macros from B</usr/X11R6/include/X11/keysymdef.h> and 1090match if I<at least> the specified identifiers are being set, and no other
1091key mappings with those and more bits are being defined. That means that
1092defining a mapping for C<a> will automatically provide definitions for
1093C<Meta-a>, C<Shift-a> and so on, unless some of those are defined mappings
1094themselves. See the C<builtin:> action, below, for a way to work around
1095this when this is a problem.
1096
1097The spelling of I<key> depends on your implementation of X. An easy way to
1098find a key name is to use the B<xev>(1) command. You can find a list by
1099looking for the C<XK_> macros in the B<X11/keysymdef.h> include file (omit
1064omitting the prefix B<XK_>. Alternatively you can specify I<key> by its hex 1100the C<XK_> prefix). Alternatively you can specify I<key> by its hex keysym
1065keysym value (B<0x0000 - 0xFFFF>). Note that the lookup of I<sym>s is not 1101value (B<0x0000 - 0xFFFF>).
1066performed in an exact manner; however, the closest match is assured.
1067 1102
1068I<string> may contain escape values (C<\n>: newline, C<\000>: octal 1103As with any resource value, the I<action> string may contain backslash
1104escape sequences (C<\n>: newline, C<\\>: backslash, C<\000>: octal
1069number), see RESOURCES in C<man 7 X> for further details. 1105number), see RESOURCES in C<man 7 X> for further details.
1070 1106
1071You can define a range of keysyms in one shot by 1107An action starts with an action prefix that selects a certain type
1072loading the C<keysym-list> perl extension and providing a I<string> 1108of action, followed by a colon. An action string without colons is
1073with pattern B<list/PREFIX/MIDDLE/SUFFIX>, where the delimiter `/' 1109interpreted as a literal string to pass to the tty (as if it was
1110prefixed with C<string:>).
1111
1112The following action prefixes are known - extensions can provide
1113additional prefixes:
1114
1115=over 4
1116
1117=item string:STRING
1118
1119If the I<action> starts with C<string:> (or otherwise contains no colons),
1120then the remaining C<STRING> will be passed to the program running in the
1121terminal. For example, you could replace whatever Shift-Tab outputs by the
1122string C<echo rm -rf /> followed by a newline:
1123
1124 URxvt.keysym.Shift-Tab: string:echo rm -rf /\n
1125
1126This could in theory be used to completely redefine your keymap.
1127
1128In addition, for actions of this type, you can define a range of
1129keysyms in one shot by loading the C<keysym-list> perl extension and
1130providing an I<action> with pattern B<list/PREFIX/MIDDLE/SUFFIX>, where
1074should be a character not used by the strings. 1131the delimiter `/' should be a character not used by the strings.
1075 1132
1076Its usage can be demonstrated by an example: 1133Its usage can be demonstrated by an example:
1077 1134
1078 URxvt.keysym.M-C-0x61: list|\033<|abc|> 1135 URxvt.keysym.M-C-0x61: list|\033<|abc|>
1079 1136
1080The above line is equivalent to the following three lines: 1137The above line is equivalent to the following three lines:
1081 1138
1082 URxvt.keysym.Meta-Control-0x61: \033<a> 1139 URxvt.keysym.Meta-Control-0x61: string:\033<a>
1083 URxvt.keysym.Meta-Control-0x62: \033<b> 1140 URxvt.keysym.Meta-Control-0x62: string:\033<b>
1084 URxvt.keysym.Meta-Control-0x63: \033<c> 1141 URxvt.keysym.Meta-Control-0x63: string:\033<c>
1085 1142
1143=item command:STRING
1144
1086If I<string> takes the form of C<command:STRING>, the specified B<STRING> 1145If I<action> takes the form of C<command:STRING>, the specified B<STRING>
1087is interpreted and executed as @@RXVT_NAME@@'s control sequence. For 1146is interpreted and executed as @@RXVT_NAME@@'s control sequence (basically
1147the opposite of C<string:> - instead of sending it to the program running
1148in the terminal, it will be treated as if it were program output). This is
1149most useful to feed command sequences into @@RXVT_NAME@@.
1150
1088example the following means "change the current locale to C<zh_CN.GBK> 1151For example the following means "change the current locale to C<zh_CN.GBK>
1089when Control-Meta-c is being pressed": 1152when Control-Meta-c is being pressed":
1090 1153
1091 URxvt.keysym.M-C-c: command:\033]701;zh_CN.GBK\007 1154 URxvt.keysym.M-C-c: command:\033]701;zh_CN.GBK\007
1092 1155
1093If I<string> takes the form C<perl:STRING>, then the specified B<STRING> 1156The following example will map Control-Meta-1 and Control-Meta-2 to
1094is passed to the C<on_user_command> perl handler. See the @@RXVT_NAME@@perl(3) 1157the fonts C<suxuseuro> and C<9x15bold>, so you can have some limited
1095manpage. For example, the F<selection> extension (activated via 1158font-switching at runtime:
1096C<@@RXVT_NAME@@ -pe selection>) listens for C<selection:rot13> events:
1097 1159
1098 URxvt.keysym.M-C-c: perl:selection:rot13 1160 URxvt.keysym.M-C-1: command:\033]50;suxuseuro\007
1161 URxvt.keysym.M-C-2: command:\033]50;9x15bold\007
1099 1162
1100Due the the large number of modifier combinations, a defined key mapping 1163Other things are possible, e.g. resizing (see @@RXVT_NAME@@(7) for more
1101will match if I<at least> the specified identifiers are being set, and 1164info):
1102no other key mappings with those and more bits are being defined. That
1103means that defining a key map for C<a> will automatically provide
1104definitions for C<Meta-a>, C<Shift-a> and so on, unless some of those are defined
1105mappings themselves.
1106 1165
1107Unfortunately, this will override built-in key mappings. For example 1166 URxvt.keysym.M-C-3: command:\033[8;25;80t
1167 URxvt.keysym.M-C-4: command:\033[8;48;110t
1168
1169=item builtin:
1170
1171The builtin action is the action that @@RXVT_NAME@@ would execute if no
1172key binding existed for the key combination. The obvious use is to undo
1173the effect of existing bindings. The not so obvious use is to reinstate
1174bindings when another binding overrides too many modifiers.
1175
1108if you overwrite the C<Insert> key you will disable @@RXVT_NAME@@'s 1176For example if you overwrite the C<Insert> key you will disable
1109C<Shift-Insert> mapping. To re-enable that, you can poke "holes" into the 1177@@RXVT_NAME@@'s C<Shift-Insert> mapping. To re-enable that, you can poke
1110user-defined keymap using the C<builtin:> replacement: 1178"holes" into the user-defined keymap using the C<builtin:> replacement:
1111 1179
1112 URxvt.keysym.Insert: <my insert key sequence> 1180 URxvt.keysym.Insert: <my insert key sequence>
1113 URxvt.keysym.S-Insert: builtin: 1181 URxvt.keysym.S-Insert: builtin:
1114 1182
1115The first line defines a mapping for C<Insert> and I<any> combination 1183The first line defines a mapping for C<Insert> and I<any> combination
1116of modifiers. The second line re-establishes the default mapping for 1184of modifiers. The second line re-establishes the default mapping for
1117C<Shift-Insert>. 1185C<Shift-Insert>.
1118 1186
1119The following example will map Control-Meta-1 and Control-Meta-2 to 1187=item builtin-string:
1120the fonts C<suxuseuro> and C<9x15bold>, so you can have some limited
1121font-switching at runtime:
1122 1188
1123 URxvt.keysym.M-C-1: command:\033]50;suxuseuro\007 1189This action is mainly useful to restore string mappings for keys that
1124 URxvt.keysym.M-C-2: command:\033]50;9x15bold\007 1190have predefined actions in @@RXVT_NAME@@. The exact semantics are a bit
1191difficult to explain - basically, this action will send the string to the
1192application that would be sent if @@RXVT_NAME@@ wouldn't have a built-in
1193action for it.
1125 1194
1126Other things are possible, e.g. resizing (see @@RXVT_NAME@@(7) for more 1195An example might make it clearer: @@RXVT_NAME@@ normally pastes the
1127info): 1196selection when you press C<Shift-Insert>. With the following bindings, it
1197would instead emit the (undocumented, but what applications running in the
1198terminal might expect) sequence C<ESC [ 2 $> instead:
1128 1199
1129 URxvt.keysym.M-C-3: command:\033[8;25;80t 1200 URxvt.keysym.S-Insert: builtin-string:
1130 URxvt.keysym.M-C-4: command:\033[8;48;110t 1201 URxvt.keysym.C-S-Insert: builtin:
1202
1203The first line disables the paste functionality for that key
1204combination, and the second reinstates the default behaviour for
1205C<Control-Shift-Insert>, which would otherwise be overridden.
1206
1207Similarly, to let applications gain access to the C<C-M-c> (copy to
1208clipboard) and C<C-M-v> (paste clipboard) key combination, you can do
1209this:
1210
1211 URxvt.keysym.C-M-c: builtin-string:
1212 URxvt.keysym.C-M-v: builtin-string:
1213
1214=item EXTENSION:STRING
1215
1216An action of this form invokes the action B<STRING>, if any, provided
1217by the @@RXVT_NAME@@perl(3) extension B<EXTENSION>. The extension will
1218be loaded automatically if necessary.
1219
1220Not all extensions define actions, but popular extensions that do
1221include the I<selection> and I<matcher> extensions (documented in their
1222own manpages, @@RXVT_NAME@@-selection(1) and @@RXVT_NAME@@-matcher(1),
1223respectively).
1224
1225From the silly examples department, this will rot13-"encrypt"
1226@@RXVT_NAME@@'s selection when Alt-Control-c is pressed on typical PC
1227keyboards:
1228
1229 URxvt.keysym.M-C-c: selection:rot13
1230
1231=item perl:STRING *DEPRECATED*
1232
1233This is a deprecated way of invoking commands provided by perl
1234extensions. It is still supported, but should not be used anymore.
1235
1236=back
1131 1237
1132=item B<perl-ext-common>: I<string> 1238=item B<perl-ext-common>: I<string>
1133 1239
1134=item B<perl-ext>: I<string> 1240=item B<perl-ext>: I<string>
1135 1241
1137use in this terminal instance; option B<-pe>. 1243use in this terminal instance; option B<-pe>.
1138 1244
1139Extension names can be prefixed with a C<-> sign to prohibit using 1245Extension names can be prefixed with a C<-> sign to prohibit using
1140them. This can be useful to selectively disable some extensions loaded 1246them. This can be useful to selectively disable some extensions loaded
1141by default, or specified via the C<perl-ext-common> resource. For 1247by default, or specified via the C<perl-ext-common> resource. For
1142example, C<default,-selection> will use all the default extension except 1248example, C<default,-selection> will use all the default extensions except
1143C<selection>. 1249C<selection>.
1144 1250
1145Extension names can also be followed by an argument in angle brackets 1251The default set includes the C<selection>, C<option-popup>,
1146(e.g. C<< searchable-scrollback<M-s> >>, which binds the hotkey for 1252C<selection-popup>, C<readline> and C<searchable-scrollback>
1147searchable scrollback to Alt/Meta-s). Mentioning the same extension 1253extensions, and extensions which are mentioned in B<keysym> resources.
1148multiple times with different arguments will pass multiple arguments to 1254
1149the extension. 1255Any extension such that a corresponding resource is given on the
1256command line is automatically appended to B<perl-ext>.
1150 1257
1151Each extension is looked up in the library directories, loaded if 1258Each extension is looked up in the library directories, loaded if
1152necessary, and bound to the current terminal instance. 1259necessary, and bound to the current terminal instance. When the library
1260search path contains multiple extension files of the same name, then the
1261first one found will be used.
1153 1262
1154If both of these resources are the empty string, then the perl 1263If both of these resources are the empty string, then the perl interpreter
1155interpreter will not be initialized. The idea behind two options is that 1264will not be initialized. The rationale for having two options is that
1156B<perl-ext-common> will be used for extensions that should be available to 1265B<perl-ext-common> will be used for extensions that should be available to
1157all instances, while B<perl-ext> is used for specific instances. 1266all instances, while B<perl-ext> is used for specific instances.
1158 1267
1159=item B<perl-eval>: I<string> 1268=item B<perl-eval>: I<string>
1160 1269
1178=item B<< selection-autotransform.I<idx> >>: I<perl-transform> 1287=item B<< selection-autotransform.I<idx> >>: I<perl-transform>
1179 1288
1180Selection auto-transform patterns, see the @@RXVT_NAME@@perl(3) manpage 1289Selection auto-transform patterns, see the @@RXVT_NAME@@perl(3) manpage
1181for details. 1290for details.
1182 1291
1183=item B<searchable-scrollback:> I<keysym> 1292=item B<searchable-scrollback:> I<keysym> *DEPRECATED*
1184 1293
1185Sets the hotkey that starts the incremental scrollback buffer search 1294This resource is deprecated and will be removed. Use a B<keysym> resource
1186(default: C<M-s>). 1295instead, e.g.:
1296
1297 URxvt.keysym.M-s: searchable-scrollback:start
1187 1298
1188=item B<url-launcher>: I<string> 1299=item B<url-launcher>: I<string>
1189 1300
1190Specifies the program to be started with a URL argument. Used by the 1301Specifies the program to be started with a URL argument. Used by the
1191C<selection-popup> and C<matcher> perl extensions. 1302C<selection-popup> and C<matcher> perl extensions.
1375window causes the value of the PRIMARY selection (or CLIPBOARD with the 1486window causes the value of the PRIMARY selection (or CLIPBOARD with the
1376B<Meta> modifier) to be inserted as if it had been typed on the keyboard. 1487B<Meta> modifier) to be inserted as if it had been typed on the keyboard.
1377 1488
1378Pressing B<Shift-Insert> causes the value of the PRIMARY selection to be 1489Pressing B<Shift-Insert> causes the value of the PRIMARY selection to be
1379inserted too. 1490inserted too.
1491
1492rxvt-unicode also provides the bindings B<Ctrl-Meta-c> and
1493<Ctrl-Meta-v> to interact with the CLIPBOARD selection. The first
1494binding causes the value of the internal selection to be copied to the
1495CLIPBOARD selection, while the second binding causes the value of the
1496CLIPBOARD selection to be inserted.
1380 1497
1381=back 1498=back
1382 1499
1383=head1 CHANGING FONTS 1500=head1 CHANGING FONTS
1384 1501
1509The following text gives values for the standard 88 colour mode (and 1626The following text gives values for the standard 88 colour mode (and
1510values for the 256 colour mode in parentheses). 1627values for the 256 colour mode in parentheses).
1511 1628
1512The RGB cube uses indices 16..79 (16..231) using the following formulas: 1629The RGB cube uses indices 16..79 (16..231) using the following formulas:
1513 1630
1514 index_88 = (r * 4 + g) * 4 + b + 16 # r, g, b = 0..3 1631 index_88 = (r * 4 + g) * 4 + b + 16 # r, g, b = 0..3
1515 index_256 = (r * 16 + g) * 16 + b + 16 # r, g, b = 0..15 1632 index_256 = (r * 6 + g) * 6 + b + 16 # r, g, b = 0..5
1516 1633
1517The grayscale ramp uses indices 80..87 (232..239), from 10% to 90% in 10% 1634The grayscale ramp uses indices 80..87 (232..239), from 10% to 90% in 10%
1518steps (1/26 to 25/26 in 1/26 steps) - black and white are already part of 1635steps (1/26 to 25/26 in 1/26 steps) - black and white are already part of
1519the RGB cube. 1636the RGB cube.
1520 1637

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines