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.232 by root, Sun May 18 18:19:10 2014 UTC

… …
1041Sets the working directory for the shell (or the command specified via 1041Sets 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 1042B<-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 1043@@RXVT_NAME@@ to start. If it isn't specified then the current working
1044directory will be used; option B<-cd>. 1044directory will be used; option B<-cd>.
1045 1045
1046=item B<keysym.>I<sym>: I<string> 1046=item B<keysym.>I<sym>: I<action>
1047 1047
1048Compile I<frills>: Associate I<string> with keysym I<sym>. The 1048Compile I<frills>: Associate I<action> with keysym I<sym>. The intervening
1049intervening resource name B<keysym.> cannot be omitted. 1049resource name B<keysym.> cannot be omitted.
1050 1050
1051The format of I<sym> is "I<(modifiers-)key>", where I<modifiers> can be 1051Using this resource, you can map key combinations such as
1052any combination of B<ISOLevel3>, B<AppKeypad>, B<Control>, B<NumLock>, 1052C<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>, 1053string 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>, 1054terminal scroll up or down the way you want it, or any other thing an
1055B<2>, B<3>, B<4>, B<5>. 1055extension might provide.
1056
1057The key combination that triggers the action, I<sym>, has the following format:
1058
1059 (modifiers-)key
1060
1061Where I<modifiers> can be any combination of B<ISOLevel3>, B<AppKeypad>,
1062B<Control>, B<NumLock>, B<Shift>, B<Meta>, B<Lock>, B<Mod1>, B<Mod2>,
1063B<Mod3>, B<Mod4>, B<Mod5>, and the abbreviated B<I>, B<K>, B<C>, B<N>,
1064B<S>, B<M>, B<A>, B<L>, B<1>, B<2>, B<3>, B<4>, B<5>.
1056 1065
1057The B<NumLock>, B<Meta> and B<ISOLevel3> modifiers are usually aliased to 1066The 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 1067whatever 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 1068keys are being mapped. B<AppKeypad> is a synthetic modifier mapped to the
1060current application keymap mode state. 1069current application keymap mode state.
1061 1070
1062The spellings of I<key> can be obtained by using B<xev>(1) command or 1071Due the the large number of modifier combinations, a key mapping will
1063searching keysym macros from B</usr/X11R6/include/X11/keysymdef.h> and 1072match if I<at least> the specified identifiers are being set, and no other
1073key mappings with those and more bits are being defined. That means that
1074defining a mapping for C<a> will automatically provide definitions for
1075C<Meta-a>, C<Shift-a> and so on, unless some of those are defined mappings
1076themselves. See the C<builtin:> action, below, for a way to work around
1077this when this is a problem.
1078
1079The spelling of I<key> depends on your implementation of X. An easy way to
1080find a key name is to use the B<xev>(1) command. You can find a list by
1081looking 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 1082the 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 1083value (B<0x0000 - 0xFFFF>).
1066performed in an exact manner; however, the closest match is assured.
1067 1084
1068I<string> may contain escape values (C<\n>: newline, C<\000>: octal 1085As with any resource value, the I<action> string may contain backslash
1086escape sequences (C<\n>: newline, C<\\>: backslash, C<\000>: octal
1069number), see RESOURCES in C<man 7 X> for further details. 1087number), see RESOURCES in C<man 7 X> for further details.
1070 1088
1071You can define a range of keysyms in one shot by 1089An action starts with an action prefix that selects a certain type
1072loading the C<keysym-list> perl extension and providing a I<string> 1090of action, followed by a colon. An action strings without colons is
1073with pattern B<list/PREFIX/MIDDLE/SUFFIX>, where the delimiter `/' 1091interpreted as a literal string to pass to the tty (as if they were
1074should be a character not used by the strings. 1092prefixed with C<string:>).
1075 1093
1076Its usage can be demonstrated by an example: 1094The following action prefixes are known - extensions can provide
1095additional prefixes:
1077 1096
1078 URxvt.keysym.M-C-0x61: list|\033<|abc|> 1097=over 4
1079 1098
1080The above line is equivalent to the following three lines: 1099=item string:STRING
1081 1100
1082 URxvt.keysym.Meta-Control-0x61: \033<a> 1101If the I<action> starts with C<string:> (or otherwise contains no colons),
1083 URxvt.keysym.Meta-Control-0x62: \033<b> 1102then the remaining C<STRING> will be passed to the program running in the
1084 URxvt.keysym.Meta-Control-0x63: \033<c> 1103terminal. For example, you could replace whatever Shift-Tab outputs by the
1104string C<echo rm -rf /> followed by a newline:
1085 1105
1106 URxvt.keysym.Shift-Tab: string:echo rm -rf /\n
1107
1108This could in theory be used to completely redefine your keymap.
1109
1110=item command:STRING
1111
1086If I<string> takes the form of C<command:STRING>, the specified B<STRING> 1112If I<action> takes the form of C<command:STRING>, the specified B<STRING>
1087is interpreted and executed as @@RXVT_NAME@@'s control sequence. For 1113is interpreted and executed as @@RXVT_NAME@@'s control sequence (basically
1114the opposite of C<string:> - instead of sending it to the program running
1115in the terminal, it will be treated as if it were program output). This is
1116most useful to feed command sequences into @@RXVT_NAME@@.
1117
1088example the following means "change the current locale to C<zh_CN.GBK> 1118For example the following means "change the current locale to C<zh_CN.GBK>
1089when Control-Meta-c is being pressed": 1119when Control-Meta-c is being pressed":
1090 1120
1091 URxvt.keysym.M-C-c: command:\033]701;zh_CN.GBK\007 1121 URxvt.keysym.M-C-c: command:\033]701;zh_CN.GBK\007
1092 1122
1093If I<string> takes the form C<perl:STRING>, then the specified B<STRING> 1123The 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) 1124the fonts C<suxuseuro> and C<9x15bold>, so you can have some limited
1095manpage. For example, the F<selection> extension (activated via 1125font-switching at runtime:
1096C<@@RXVT_NAME@@ -pe selection>) listens for C<selection:rot13> events:
1097 1126
1098 URxvt.keysym.M-C-c: perl:selection:rot13 1127 URxvt.keysym.M-C-1: command:\033]50;suxuseuro\007
1128 URxvt.keysym.M-C-2: command:\033]50;9x15bold\007
1099 1129
1100Due the the large number of modifier combinations, a defined key mapping 1130Other 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 1131info):
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 1132
1107Unfortunately, this will override built-in key mappings. For example 1133 URxvt.keysym.M-C-3: command:\033[8;25;80t
1134 URxvt.keysym.M-C-4: command:\033[8;48;110t
1135
1136=item builtin:
1137
1138The builtin action is the action that @@RXVT_NAME@@ would execute if no
1139key binding existed for the key combination. The obvious use is to undo
1140the effect of existing bindings. The not so obvious use is to reinstate
1141bindings when another binding overrides too many modifiers.
1142
1108if you overwrite the C<Insert> key you will disable @@RXVT_NAME@@'s 1143For 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 1144@@RXVT_NAME@@'s C<Shift-Insert> mapping. To re-enable that, you can poke
1110user-defined keymap using the C<builtin:> replacement: 1145"holes" into the user-defined keymap using the C<builtin:> replacement:
1111 1146
1112 URxvt.keysym.Insert: <my insert key sequence> 1147 URxvt.keysym.Insert: <my insert key sequence>
1113 URxvt.keysym.S-Insert: builtin: 1148 URxvt.keysym.S-Insert: builtin:
1114 1149
1115The first line defines a mapping for C<Insert> and I<any> combination 1150The first line defines a mapping for C<Insert> and I<any> combination
1116of modifiers. The second line re-establishes the default mapping for 1151of modifiers. The second line re-establishes the default mapping for
1117C<Shift-Insert>. 1152C<Shift-Insert>.
1118 1153
1119The following example will map Control-Meta-1 and Control-Meta-2 to 1154=item builtin-string:
1120the fonts C<suxuseuro> and C<9x15bold>, so you can have some limited
1121font-switching at runtime:
1122 1155
1123 URxvt.keysym.M-C-1: command:\033]50;suxuseuro\007 1156This action is mainly useful to restore string mappings for keys that
1124 URxvt.keysym.M-C-2: command:\033]50;9x15bold\007 1157have predefined actions in @@RXVT_NAME@@. The exact semantics are a bit
1158difficult to explain - basically, this action will send the string to the
1159application that would be sent if @@RXVT_NAME@@ wouldn't have a built-in
1160action for it.
1125 1161
1126Other things are possible, e.g. resizing (see @@RXVT_NAME@@(7) for more 1162An example might make it clearer: @@RXVT_NAME@@ normally pastes the
1127info): 1163selection when you press C<Shift-Insert>. With the following bindings, it
1164would instead emit the (undocumented, but what applications running in the
1165terminal might expect) sequence C<ESC [ 2 $> instead:
1128 1166
1129 URxvt.keysym.M-C-3: command:\033[8;25;80t 1167 URxvt.keysym.S-Insert: builtin-string:
1130 URxvt.keysym.M-C-4: command:\033[8;48;110t 1168 URxvt.keysym.C-S-Insert: builtin:
1169
1170The first line disables the paste functionality for that key
1171combination, and the second reinstates the default behaviour for
1172C<Control-Shift-Insert>, which would otherwise be overridden.
1173
1174Similarly, to let applications gain access to the C<C-M-c> (copy to
1175clipboard) and C<C-M-v> (paste clipboard) key combination, you can do
1176this:
1177
1178 URxvt.keysym.C-S-c: builtin-string:
1179 URxvt.keysym.C-S-v: builtin-string:
1180
1181=item EXTENSION:STRING
1182
1183An action of this form passes the B<STRING> to the @@RXVT_NAME@@perl(3)
1184extension of the same name. The extension will be loaded automatically if
1185neccessary.
1186
1187Not all extensions define key actions, but popular extensions that do
1188include the I<selection> and I<matcher> extensions (documented in their
1189own manpages, @@RXVT_NAME@@-selection(1) and @@RXVT_NAME@@-matcher(1),
1190respectively).
1191
1192From the silly examples department, this will rot13-"encrypt"
1193@@RXVT_NAME@@'s selection when Alt-Control-c is pressed on typical PC
1194keyboards:
1195
1196 URxvt.keysym.M-C-c: selection:rot13
1197
1198=item perl:STRING *DEPRECATED*
1199
1200This is a deprecated way of passing key mappings to perl extensions. It is
1201still supported, but should not be used anymore.
1202
1203=back
1131 1204
1132=item B<perl-ext-common>: I<string> 1205=item B<perl-ext-common>: I<string>
1133 1206
1134=item B<perl-ext>: I<string> 1207=item B<perl-ext>: I<string>
1135 1208
… …
1137use in this terminal instance; option B<-pe>. 1210use in this terminal instance; option B<-pe>.
1138 1211
1139Extension names can be prefixed with a C<-> sign to prohibit using 1212Extension names can be prefixed with a C<-> sign to prohibit using
1140them. This can be useful to selectively disable some extensions loaded 1213them. This can be useful to selectively disable some extensions loaded
1141by default, or specified via the C<perl-ext-common> resource. For 1214by default, or specified via the C<perl-ext-common> resource. For
1142example, C<default,-selection> will use all the default extension except 1215example, C<default,-selection> will use all the default extensions except
1143C<selection>. 1216C<selection>.
1144 1217
1145Extension names can also be followed by an argument in angle brackets 1218The default set includes the C<selection>, C<option-popup>,
1146(e.g. C<< searchable-scrollback<M-s> >>, which binds the hotkey for 1219C<selection-popup> and C<readline> extensions, any extensions that define
1147searchable scrollback to Alt/Meta-s). Mentioning the same extension 1220keybindings via C<BINDING> meta comments, extensions loaded because
1148multiple times with different arguments will pass multiple arguments to 1221their resources/commandline switches were used, and extensions which are
1149the extension. 1222mentioned in B<keysym> resources.
1150 1223
1151Each extension is looked up in the library directories, loaded if 1224Each extension is looked up in the library directories, loaded if
1152necessary, and bound to the current terminal instance. 1225necessary, and bound to the current terminal instance. When the library
1226search path contains multiple extension files of the same name, then the
1227first one found will be used.
1153 1228
1154If both of these resources are the empty string, then the perl 1229If both of these resources are the empty string, then the perl interpreter
1155interpreter will not be initialized. The idea behind two options is that 1230will 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 1231B<perl-ext-common> will be used for extensions that should be available to
1157all instances, while B<perl-ext> is used for specific instances. 1232all instances, while B<perl-ext> is used for specific instances.
1158 1233
1159=item B<perl-eval>: I<string> 1234=item B<perl-eval>: I<string>
1160 1235
… …
1178=item B<< selection-autotransform.I<idx> >>: I<perl-transform> 1253=item B<< selection-autotransform.I<idx> >>: I<perl-transform>
1179 1254
1180Selection auto-transform patterns, see the @@RXVT_NAME@@perl(3) manpage 1255Selection auto-transform patterns, see the @@RXVT_NAME@@perl(3) manpage
1181for details. 1256for details.
1182 1257
1183=item B<searchable-scrollback:> I<keysym> 1258=item B<searchable-scrollback:> I<keysym> *DEPRECATED*
1184 1259
1185Sets the hotkey that starts the incremental scrollback buffer search 1260This resource is deprecated and will be removed. Use a B<keysym> resource
1186(default: C<M-s>). 1261instead, e.g.:
1262
1263 URxvt.keysym.M-s: searchable-scrollback:start
1187 1264
1188=item B<url-launcher>: I<string> 1265=item B<url-launcher>: I<string>
1189 1266
1190Specifies the program to be started with a URL argument. Used by the 1267Specifies the program to be started with a URL argument. Used by the
1191C<selection-popup> and C<matcher> perl extensions. 1268C<selection-popup> and C<matcher> perl extensions.
… …
1375window causes the value of the PRIMARY selection (or CLIPBOARD with the 1452window 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. 1453B<Meta> modifier) to be inserted as if it had been typed on the keyboard.
1377 1454
1378Pressing B<Shift-Insert> causes the value of the PRIMARY selection to be 1455Pressing B<Shift-Insert> causes the value of the PRIMARY selection to be
1379inserted too. 1456inserted too.
1457
1458rxvt-unicode also provides the bindings B<Ctrl-Meta-c> and
1459<Ctrl-Meta-v> to interact with the CLIPBOARD selection. The first
1460binding causes the value of the internal selection to be copied to the
1461CLIPBOARD selection, while the second binding causes the value of the
1462CLIPBOARD selection to be inserted.
1380 1463
1381=back 1464=back
1382 1465
1383=head1 CHANGING FONTS 1466=head1 CHANGING FONTS
1384 1467
… …
1509The following text gives values for the standard 88 colour mode (and 1592The following text gives values for the standard 88 colour mode (and
1510values for the 256 colour mode in parentheses). 1593values for the 256 colour mode in parentheses).
1511 1594
1512The RGB cube uses indices 16..79 (16..231) using the following formulas: 1595The RGB cube uses indices 16..79 (16..231) using the following formulas:
1513 1596
1514 index_88 = (r * 4 + g) * 4 + b + 16 # r, g, b = 0..3 1597 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 1598 index_256 = (r * 6 + g) * 6 + b + 16 # r, g, b = 0..5
1516 1599
1517The grayscale ramp uses indices 80..87 (232..239), from 10% to 90% in 10% 1600The 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 1601steps (1/26 to 25/26 in 1/26 steps) - black and white are already part of
1519the RGB cube. 1602the RGB cube.
1520 1603

Diff Legend

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