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.223 by root, Thu May 30 18:49:16 2013 UTC vs.
Revision 1.230 by sf-exg, Mon Apr 28 16:00:34 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
1089An action starts with an action prefix that selects a certain type
1090of action, followed by a colon. An action strings without colons is
1091interpreted as a literal string to pass to the tty (as if they were
1092prefixed with C<string:>).
1093
1094The following action prefixes are known - extensions can provide
1095additional prefixes:
1096
1097=over 4
1098
1099=item string:STRING
1100
1101If the I<action> starts with C<string:> (or otherwise contains no colons),
1102then the remaining C<STRING> will be passed to the program running in the
1103terminal. For example, you could replace whatever Shift-Tab outputs by the
1104string C<echo rm -rf /> followed by a newline:
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
1112If I<action> takes the form of C<command:STRING>, the specified B<STRING>
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
1118For example the following means "change the current locale to C<zh_CN.GBK>
1119when Control-Meta-c is being pressed":
1120
1121 URxvt.keysym.M-C-c: command:\033]701;zh_CN.GBK\007
1122
1123The following example will map Control-Meta-1 and Control-Meta-2 to
1124the fonts C<suxuseuro> and C<9x15bold>, so you can have some limited
1125font-switching at runtime:
1126
1127 URxvt.keysym.M-C-1: command:\033]50;suxuseuro\007
1128 URxvt.keysym.M-C-2: command:\033]50;9x15bold\007
1129
1130Other things are possible, e.g. resizing (see @@RXVT_NAME@@(7) for more
1131info):
1132
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
1143For example if you overwrite the C<Insert> key you will disable
1144@@RXVT_NAME@@'s C<Shift-Insert> mapping. To re-enable that, you can poke
1145"holes" into the user-defined keymap using the C<builtin:> replacement:
1146
1147 URxvt.keysym.Insert: <my insert key sequence>
1148 URxvt.keysym.S-Insert: builtin:
1149
1150The first line defines a mapping for C<Insert> and I<any> combination
1151of modifiers. The second line re-establishes the default mapping for
1152C<Shift-Insert>.
1153
1154=item builtin-string:
1155
1156This action is mainly useful to restore string mappings for keys that
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.
1161
1162An example might make it clearer: @@RXVT_NAME@@ normally pastes the
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:
1166
1167 URxvt.keysym.S-Insert: builtin-string:
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
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
1204
1071You can define a range of keysyms in one shot by 1205In addition, you can define a range of keysyms in one shot by loading
1072loading the C<keysym-list> perl extension and providing a I<string> 1206the C<keysym-list> perl extension and providing a I<string> with pattern
1073with pattern B<list/PREFIX/MIDDLE/SUFFIX>, where the delimiter `/' 1207B<list/PREFIX/MIDDLE/SUFFIX>, where the delimiter `/' should be a
1074should be a character not used by the strings. 1208character not used by the strings.
1075 1209
1076Its usage can be demonstrated by an example: 1210Its usage can be demonstrated by an example:
1077 1211
1078 URxvt.keysym.M-C-0x61: list|\033<|abc|> 1212 URxvt.keysym.M-C-0x61: list|\033<|abc|>
1079 1213
1080The above line is equivalent to the following three lines: 1214The above line is equivalent to the following three lines:
1081 1215
1082 URxvt.keysym.Meta-Control-0x61: \033<a> 1216 URxvt.keysym.Meta-Control-0x61: \033<a>
1083 URxvt.keysym.Meta-Control-0x62: \033<b> 1217 URxvt.keysym.Meta-Control-0x62: \033<b>
1084 URxvt.keysym.Meta-Control-0x63: \033<c> 1218 URxvt.keysym.Meta-Control-0x63: \033<c>
1085
1086If I<string> takes the form of C<command:STRING>, the specified B<STRING>
1087is interpreted and executed as @@RXVT_NAME@@'s control sequence. For
1088example the following means "change the current locale to C<zh_CN.GBK>
1089when Control-Meta-c is being pressed":
1090
1091 URxvt.keysym.M-C-c: command:\033]701;zh_CN.GBK\007
1092
1093If I<string> takes the form C<perl:STRING>, then the specified B<STRING>
1094is passed to the C<on_user_command> perl handler. See the @@RXVT_NAME@@perl(3)
1095manpage. For example, the F<selection> extension (activated via
1096C<@@RXVT_NAME@@ -pe selection>) listens for C<selection:rot13> events:
1097
1098 URxvt.keysym.M-C-c: perl:selection:rot13
1099
1100Due the the large number of modifier combinations, a defined key mapping
1101will match if I<at least> the specified identifiers are being set, and
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
1107Unfortunately, this will override built-in key mappings. For example
1108if you overwrite the C<Insert> key you will disable @@RXVT_NAME@@'s
1109C<Shift-Insert> mapping. To re-enable that, you can poke "holes" into the
1110user-defined keymap using the C<builtin:> replacement:
1111
1112 URxvt.keysym.Insert: <my insert key sequence>
1113 URxvt.keysym.S-Insert: builtin:
1114
1115The first line defines a mapping for C<Insert> and I<any> combination
1116of modifiers. The second line re-establishes the default mapping for
1117C<Shift-Insert>.
1118
1119The following example will map Control-Meta-1 and Control-Meta-2 to
1120the fonts C<suxuseuro> and C<9x15bold>, so you can have some limited
1121font-switching at runtime:
1122
1123 URxvt.keysym.M-C-1: command:\033]50;suxuseuro\007
1124 URxvt.keysym.M-C-2: command:\033]50;9x15bold\007
1125
1126Other things are possible, e.g. resizing (see @@RXVT_NAME@@(7) for more
1127info):
1128
1129 URxvt.keysym.M-C-3: command:\033[8;25;80t
1130 URxvt.keysym.M-C-4: command:\033[8;48;110t
1131 1219
1132=item B<perl-ext-common>: I<string> 1220=item B<perl-ext-common>: I<string>
1133 1221
1134=item B<perl-ext>: I<string> 1222=item B<perl-ext>: I<string>
1135 1223
… …
1375window causes the value of the PRIMARY selection (or CLIPBOARD with the 1463window 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. 1464B<Meta> modifier) to be inserted as if it had been typed on the keyboard.
1377 1465
1378Pressing B<Shift-Insert> causes the value of the PRIMARY selection to be 1466Pressing B<Shift-Insert> causes the value of the PRIMARY selection to be
1379inserted too. 1467inserted too.
1468
1469rxvt-unicode also provides the bindings B<Ctrl-Meta-c> and
1470<Ctrl-Meta-v> to interact with the CLIPBOARD selection. The first
1471binding causes the value of the internal selection to be copied to the
1472CLIPBOARD selection, while the second binding causes the value of the
1473CLIPBOARD selection to be inserted.
1380 1474
1381=back 1475=back
1382 1476
1383=head1 CHANGING FONTS 1477=head1 CHANGING FONTS
1384 1478
… …
1509The following text gives values for the standard 88 colour mode (and 1603The following text gives values for the standard 88 colour mode (and
1510values for the 256 colour mode in parentheses). 1604values for the 256 colour mode in parentheses).
1511 1605
1512The RGB cube uses indices 16..79 (16..231) using the following formulas: 1606The RGB cube uses indices 16..79 (16..231) using the following formulas:
1513 1607
1514 index_88 = (r * 4 + g) * 4 + b + 16 # r, g, b = 0..3 1608 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 1609 index_256 = (r * 6 + g) * 6 + b + 16 # r, g, b = 0..5
1516 1610
1517The grayscale ramp uses indices 80..87 (232..239), from 10% to 90% in 10% 1611The 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 1612steps (1/26 to 25/26 in 1/26 steps) - black and white are already part of
1519the RGB cube. 1613the RGB cube.
1520 1614
… …
1683 1777
1684=over 4 1778=over 4
1685 1779
1686=item Project Coordinator 1780=item Project Coordinator
1687 1781
1688Marc A. Lehmann L<< <rxvt-unicode@schmorp.de> >> 1782Marc A. Lehmann <rxvt-unicode@schmorp.de>.
1689 1783
1690L<http://software.schmorp.de/pkg/rxvt-unicode.html> 1784L<http://software.schmorp.de/pkg/rxvt-unicode.html>
1691 1785
1692=back 1786=back
1693 1787
… …
1697 1791
1698=item John Bovey 1792=item John Bovey
1699 1793
1700University of Kent, 1992, wrote the original Xvt. 1794University of Kent, 1992, wrote the original Xvt.
1701 1795
1702=item Rob Nation L<< <nation@rocket.sanders.lockheed.com> >> 1796=item Rob Nation <nation@rocket.sanders.lockheed.com>
1703 1797
1704very heavily modified Xvt and came up with Rxvt 1798very heavily modified Xvt and came up with Rxvt
1705 1799
1706=item Angelo Haritsis L<< <ah@doc.ic.ac.uk> >> 1800=item Angelo Haritsis <ah@doc.ic.ac.uk>
1707 1801
1708wrote the Greek Keyboard Input (no longer in code) 1802wrote the Greek Keyboard Input (no longer in code)
1709 1803
1710=item mj olesen L<< <olesen@me.QueensU.CA> >> 1804=item mj olesen <olesen@me.QueensU.CA>
1711 1805
1712Wrote the menu system. 1806Wrote the menu system.
1713 1807
1714Project Coordinator (changes.txt 2.11 to 2.21) 1808Project Coordinator (changes.txt 2.11 to 2.21)
1715 1809
1716=item Oezguer Kesim L<< <kesim@math.fu-berlin.de> >> 1810=item Oezguer Kesim <kesim@math.fu-berlin.de>
1717 1811
1718Project Coordinator (changes.txt 2.21a to 2.4.5) 1812Project Coordinator (changes.txt 2.21a to 2.4.5)
1719 1813
1720=item Geoff Wing L<< <gcw@pobox.com> >> 1814=item Geoff Wing <gcw@pobox.com>
1721 1815
1722Rewrote screen display and text selection routines. 1816Rewrote screen display and text selection routines.
1723 1817
1724Project Coordinator (changes.txt 2.4.6 - rxvt-unicode) 1818Project Coordinator (changes.txt 2.4.6 - rxvt-unicode)
1725 1819
1726=item Marc Alexander Lehmann L<< <rxvt-unicode@schmorp.de> >> 1820=item Marc Alexander Lehmann <rxvt-unicode@schmorp.de>
1727 1821
1728Forked rxvt-unicode, unicode support, rewrote almost all the code, perl 1822Forked rxvt-unicode, unicode support, rewrote almost all the code, perl
1729extension, random hacks, numerous bugfixes and extensions. 1823extension, random hacks, numerous bugfixes and extensions.
1730 1824
1731Project Coordinator (Changes 1.0 -) 1825Project Coordinator (Changes 1.0 -)
1732 1826
1733=item Emanuele Giaquinta L<< <e.giaquinta@glauco.it> >> 1827=item Emanuele Giaquinta <emanuele.giaquinta@gmail.com>
1734 1828
1735pty/utmp code rewrite, image code improvements, many random hacks and bugfixes. 1829pty/utmp code rewrite, image code improvements, many random hacks and bugfixes.
1736 1830
1737=back 1831=back
1738 1832

Diff Legend

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