[ViewVC] Diff of: cvs/rxvt-unicode/doc/rxvt.1.pod

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.230 by sf-exg, Mon Apr 28 16:00:34 2014 UTC

…		…
1041	Sets the working directory for the shell (or the command specified via	1041	Sets the working directory for the shell (or the command specified via
1042	B<-e>). The I<path> must be an absolute path and it must exist for	1042	B<-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
1044	directory will be used; option B<-cd>.	1044	directory 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
1048	Compile I<frills>: Associate I<string> with keysym I<sym>. The	1048	Compile I<frills>: Associate I<action> with keysym I<sym>. The intervening
1049	intervening resource name B<keysym.> cannot be omitted.	1049	resource name B<keysym.> cannot be omitted.
1050		1050
1051	The format of I<sym> is "I<(modifiers-)key>", where I<modifiers> can be	1051	Using this resource, you can map key combinations such as
1052	any combination of B<ISOLevel3>, B<AppKeypad>, B<Control>, B<NumLock>,	1052	C<Ctrl-Shift-BackSpace> to various actions, such as outputting a different
1053	B<Shift>, B<Meta>, B<Lock>, B<Mod1>, B<Mod2>, B<Mod3>, B<Mod4>, B<Mod5>,	1053	string than would normally result from that combination, making the
1054	and the abbreviated B<I>, B<K>, B<C>, B<N>, B<S>, B<M>, B<A>, B<L>, B<1>,	1054	terminal scroll up or down the way you want it, or any other thing an
1055	B<2>, B<3>, B<4>, B<5>.	1055	extension might provide.
		1056
		1057	The key combination that triggers the action, I<sym>, has the following format:
		1058
		1059	(modifiers-)key
		1060
		1061	Where I<modifiers> can be any combination of B<ISOLevel3>, B<AppKeypad>,
		1062	B<Control>, B<NumLock>, B<Shift>, B<Meta>, B<Lock>, B<Mod1>, B<Mod2>,
		1063	B<Mod3>, B<Mod4>, B<Mod5>, and the abbreviated B<I>, B<K>, B<C>, B<N>,
		1064	B<S>, B<M>, B<A>, B<L>, B<1>, B<2>, B<3>, B<4>, B<5>.
1056		1065
1057	The B<NumLock>, B<Meta> and B<ISOLevel3> modifiers are usually aliased to	1066	The B<NumLock>, B<Meta> and B<ISOLevel3> modifiers are usually aliased to
1058	whatever modifier the NumLock key, Meta/Alt keys or ISO Level3 Shift/AltGr	1067	whatever modifier the NumLock key, Meta/Alt keys or ISO Level3 Shift/AltGr
1059	keys are being mapped. B<AppKeypad> is a synthetic modifier mapped to the	1068	keys are being mapped. B<AppKeypad> is a synthetic modifier mapped to the
1060	current application keymap mode state.	1069	current application keymap mode state.
1061		1070
1062	The spellings of I<key> can be obtained by using B<xev>(1) command or	1071	Due the the large number of modifier combinations, a key mapping will
1063	searching keysym macros from B</usr/X11R6/include/X11/keysymdef.h> and	1072	match if I<at least> the specified identifiers are being set, and no other
		1073	key mappings with those and more bits are being defined. That means that
		1074	defining a mapping for C<a> will automatically provide definitions for
		1075	C<Meta-a>, C<Shift-a> and so on, unless some of those are defined mappings
		1076	themselves. See the C<builtin:> action, below, for a way to work around
		1077	this when this is a problem.
		1078
		1079	The spelling of I<key> depends on your implementation of X. An easy way to
		1080	find a key name is to use the B<xev>(1) command. You can find a list by
		1081	looking for the C<XK_> macros in the B<X11/keysymdef.h> include file (omit
1064	omitting the prefix B<XK_>. Alternatively you can specify I<key> by its hex	1082	the C<XK_> prefix). Alternatively you can specify I<key> by its hex keysym
1065	keysym value (B<0x0000 - 0xFFFF>). Note that the lookup of I<sym>s is not	1083	value (B<0x0000 - 0xFFFF>).
1066	performed in an exact manner; however, the closest match is assured.
1067		1084
1068	I<string> may contain escape values (C<\n>: newline, C<\000>: octal	1085	As with any resource value, the I<action> string may contain backslash
		1086	escape sequences (C<\n>: newline, C<\\>: backslash, C<\000>: octal
1069	number), see RESOURCES in C<man 7 X> for further details.	1087	number), see RESOURCES in C<man 7 X> for further details.
1070		1088
		1089	An action starts with an action prefix that selects a certain type
		1090	of action, followed by a colon. An action strings without colons is
		1091	interpreted as a literal string to pass to the tty (as if they were
		1092	prefixed with C<string:>).
		1093
		1094	The following action prefixes are known - extensions can provide
		1095	additional prefixes:
		1096
		1097	=over 4
		1098
		1099	=item string:STRING
		1100
		1101	If the I<action> starts with C<string:> (or otherwise contains no colons),
		1102	then the remaining C<STRING> will be passed to the program running in the
		1103	terminal. For example, you could replace whatever Shift-Tab outputs by the
		1104	string C<echo rm -rf /> followed by a newline:
		1105
		1106	URxvt.keysym.Shift-Tab: string:echo rm -rf /\n
		1107
		1108	This could in theory be used to completely redefine your keymap.
		1109
		1110	=item command:STRING
		1111
		1112	If I<action> takes the form of C<command:STRING>, the specified B<STRING>
		1113	is interpreted and executed as @@RXVT_NAME@@'s control sequence (basically
		1114	the opposite of C<string:> - instead of sending it to the program running
		1115	in the terminal, it will be treated as if it were program output). This is
		1116	most useful to feed command sequences into @@RXVT_NAME@@.
		1117
		1118	For example the following means "change the current locale to C<zh_CN.GBK>
		1119	when Control-Meta-c is being pressed":
		1120
		1121	URxvt.keysym.M-C-c: command:\033]701;zh_CN.GBK\007
		1122
		1123	The following example will map Control-Meta-1 and Control-Meta-2 to
		1124	the fonts C<suxuseuro> and C<9x15bold>, so you can have some limited
		1125	font-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
		1130	Other things are possible, e.g. resizing (see @@RXVT_NAME@@(7) for more
		1131	info):
		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
		1138	The builtin action is the action that @@RXVT_NAME@@ would execute if no
		1139	key binding existed for the key combination. The obvious use is to undo
		1140	the effect of existing bindings. The not so obvious use is to reinstate
		1141	bindings when another binding overrides too many modifiers.
		1142
		1143	For 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
		1150	The first line defines a mapping for C<Insert> and I<any> combination
		1151	of modifiers. The second line re-establishes the default mapping for
		1152	C<Shift-Insert>.
		1153
		1154	=item builtin-string:
		1155
		1156	This action is mainly useful to restore string mappings for keys that
		1157	have predefined actions in @@RXVT_NAME@@. The exact semantics are a bit
		1158	difficult to explain - basically, this action will send the string to the
		1159	application that would be sent if @@RXVT_NAME@@ wouldn't have a built-in
		1160	action for it.
		1161
		1162	An example might make it clearer: @@RXVT_NAME@@ normally pastes the
		1163	selection when you press C<Shift-Insert>. With the following bindings, it
		1164	would instead emit the (undocumented, but what applications running in the
		1165	terminal might expect) sequence C<ESC [ 2 $> instead:
		1166
		1167	URxvt.keysym.S-Insert: builtin-string:
		1168	URxvt.keysym.C-S-Insert: builtin:
		1169
		1170	The first line disables the paste functionality for that key
		1171	combination, and the second reinstates the default behaviour for
		1172	C<Control-Shift-Insert>, which would otherwise be overridden.
		1173
		1174	Similarly, to let applications gain access to the C<C-M-c> (copy to
		1175	clipboard) and C<C-M-v> (paste clipboard) key combination, you can do
		1176	this:
		1177
		1178	URxvt.keysym.C-S-c: builtin-string:
		1179	URxvt.keysym.C-S-v: builtin-string:
		1180
		1181	=item EXTENSION:STRING
		1182
		1183	An action of this form passes the B<STRING> to the @@RXVT_NAME@@perl(3)
		1184	extension of the same name. The extension will be loaded automatically if
		1185	neccessary.
		1186
		1187	Not all extensions define key actions, but popular extensions that do
		1188	include the I<selection> and I<matcher> extensions (documented in their
		1189	own manpages, @@RXVT_NAME@@-selection(1) and @@RXVT_NAME@@-matcher(1),
		1190	respectively).
		1191
		1192	From the silly examples department, this will rot13-"encrypt"
		1193	@@RXVT_NAME@@'s selection when Alt-Control-c is pressed on typical PC
		1194	keyboards:
		1195
		1196	URxvt.keysym.M-C-c: selection:rot13
		1197
		1198	=item perl:STRING
		1199
		1200	This is a deprecated way of passing key mappings to perl extensions. It is
		1201	still supported, but should not be used anymore.
		1202
		1203	=back
		1204
1071	You can define a range of keysyms in one shot by	1205	In addition, you can define a range of keysyms in one shot by loading
1072	loading the C<keysym-list> perl extension and providing a I<string>	1206	the C<keysym-list> perl extension and providing a I<string> with pattern
1073	with pattern B<list/PREFIX/MIDDLE/SUFFIX>, where the delimiter `/'	1207	B<list/PREFIX/MIDDLE/SUFFIX>, where the delimiter `/' should be a
1074	should be a character not used by the strings.	1208	character not used by the strings.
1075		1209
1076	Its usage can be demonstrated by an example:	1210	Its 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
1080	The above line is equivalent to the following three lines:	1214	The 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
1086	If I<string> takes the form of C<command:STRING>, the specified B<STRING>
1087	is interpreted and executed as @@RXVT_NAME@@'s control sequence. For
1088	example the following means "change the current locale to C<zh_CN.GBK>
1089	when Control-Meta-c is being pressed":
1090
1091	URxvt.keysym.M-C-c: command:\033]701;zh_CN.GBK\007
1092
1093	If I<string> takes the form C<perl:STRING>, then the specified B<STRING>
1094	is passed to the C<on_user_command> perl handler. See the @@RXVT_NAME@@perl(3)
1095	manpage. For example, the F<selection> extension (activated via
1096	C<@@RXVT_NAME@@ -pe selection>) listens for C<selection:rot13> events:
1097
1098	URxvt.keysym.M-C-c: perl:selection:rot13
1099
1100	Due the the large number of modifier combinations, a defined key mapping
1101	will match if I<at least> the specified identifiers are being set, and
1102	no other key mappings with those and more bits are being defined. That
1103	means that defining a key map for C<a> will automatically provide
1104	definitions for C<Meta-a>, C<Shift-a> and so on, unless some of those are defined
1105	mappings themselves.
1106
1107	Unfortunately, this will override built-in key mappings. For example
1108	if you overwrite the C<Insert> key you will disable @@RXVT_NAME@@'s
1109	C<Shift-Insert> mapping. To re-enable that, you can poke "holes" into the
1110	user-defined keymap using the C<builtin:> replacement:
1111
1112	URxvt.keysym.Insert: <my insert key sequence>
1113	URxvt.keysym.S-Insert: builtin:
1114
1115	The first line defines a mapping for C<Insert> and I<any> combination
1116	of modifiers. The second line re-establishes the default mapping for
1117	C<Shift-Insert>.
1118
1119	The following example will map Control-Meta-1 and Control-Meta-2 to
1120	the fonts C<suxuseuro> and C<9x15bold>, so you can have some limited
1121	font-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
1126	Other things are possible, e.g. resizing (see @@RXVT_NAME@@(7) for more
1127	info):
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
…		…
1375	window causes the value of the PRIMARY selection (or CLIPBOARD with the	1463	window causes the value of the PRIMARY selection (or CLIPBOARD with the
1376	B<Meta> modifier) to be inserted as if it had been typed on the keyboard.	1464	B<Meta> modifier) to be inserted as if it had been typed on the keyboard.
1377		1465
1378	Pressing B<Shift-Insert> causes the value of the PRIMARY selection to be	1466	Pressing B<Shift-Insert> causes the value of the PRIMARY selection to be
1379	inserted too.	1467	inserted too.
		1468
		1469	rxvt-unicode also provides the bindings B<Ctrl-Meta-c> and
		1470	<Ctrl-Meta-v> to interact with the CLIPBOARD selection. The first
		1471	binding causes the value of the internal selection to be copied to the
		1472	CLIPBOARD selection, while the second binding causes the value of the
		1473	CLIPBOARD selection to be inserted.
1380		1474
1381	=back	1475	=back
1382		1476
1383	=head1 CHANGING FONTS	1477	=head1 CHANGING FONTS
1384		1478
…		…
1509	The following text gives values for the standard 88 colour mode (and	1603	The following text gives values for the standard 88 colour mode (and
1510	values for the 256 colour mode in parentheses).	1604	values for the 256 colour mode in parentheses).
1511		1605
1512	The RGB cube uses indices 16..79 (16..231) using the following formulas:	1606	The 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
1517	The grayscale ramp uses indices 80..87 (232..239), from 10% to 90% in 10%	1611	The grayscale ramp uses indices 80..87 (232..239), from 10% to 90% in 10%
1518	steps (1/26 to 25/26 in 1/26 steps) - black and white are already part of	1612	steps (1/26 to 25/26 in 1/26 steps) - black and white are already part of
1519	the RGB cube.	1613	the RGB cube.
1520		1614

Diff Legend

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

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.230 by sf-exg, Mon Apr 28 16:00:34 2014 UTC

Diff Legend

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.230 by sf-exg, Mon Apr 28 16:00:34 2014 UTC