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.228 by root, Sun Apr 27 19:43:46 2014 UTC vs.
Revision 1.250 by root, Sat Oct 10 20:06:45 2020 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>.
853are not passed onto the shell; option B<-sk>. B<False>: do not scroll to 871are not passed onto the shell; option B<-sk>. B<False>: do not scroll to
854bottom when a non-special key is pressed; option B<+sk>. 872bottom when a non-special key is pressed; option B<+sk>.
855 873
856=item B<saveLines:> I<number> 874=item B<saveLines:> I<number>
857 875
858Save I<number> lines in the scrollback buffer [default 64]. This 876Save I<number> lines in the scrollback buffer [default 1000]; option B<-sl>.
859resource is limited on most machines to 65535; option B<-sl>.
860 877
861=item B<internalBorder:> I<number> 878=item B<internalBorder:> I<number>
862 879
863Internal border of I<number> pixels. This resource is limited to 100; 880Internal border of I<number> pixels. This resource is limited to 100;
864option B<-b>. 881option B<-b>.
927 944
928=item B<pointerColor2:> I<colour> 945=item B<pointerColor2:> I<colour>
929 946
930Mouse pointer background colour. 947Mouse pointer background colour.
931 948
949=item B<pointerShape:> I<string>
950
951Compile I<frills>: Specifies the name of the mouse pointer shape
952[default B<xterm>]. See the macros in the B<X11/cursorfont.h> include
953file for possible values (omit the C<XC_> prefix).
954
932=item B<pointerBlankDelay:> I<number> 955=item B<pointerBlankDelay:> I<number>
933 956
934Specifies number of seconds before blanking the pointer [default 2]. Use a 957Specifies number of seconds before blanking the pointer [default 2]. Use a
935large number (e.g. C<987654321>) to effectively disable the timeout. 958large number (e.g. C<987654321>) to effectively disable the timeout.
936 959
962 985
963B<< BACKSLASH `"'&()*,;<=>?@[]^{|} >> 986B<< BACKSLASH `"'&()*,;<=>?@[]^{|} >>
964 987
965=item B<preeditType:> I<style> 988=item B<preeditType:> I<style>
966 989
967B<OverTheSpot>, B<OffTheSpot>, B<Root>; option B<-pt>. 990B<OnTheSpot>, B<OverTheSpot>, B<OffTheSpot>, B<Root>; option B<-pt>.
968 991
969=item B<inputMethod:> I<name> 992=item B<inputMethod:> I<name>
970 993
971I<name> of inputMethod to use; option B<-im>. 994I<name> of inputMethod to use; option B<-im>.
972 995
1055extension might provide. 1078extension might provide.
1056 1079
1057The key combination that triggers the action, I<sym>, has the following format: 1080The key combination that triggers the action, I<sym>, has the following format:
1058 1081
1059 (modifiers-)key 1082 (modifiers-)key
1060 1083
1061Where I<modifiers> can be any combination of B<ISOLevel3>, B<AppKeypad>, 1084Where I<modifiers> can be any combination of the following full or
1062B<Control>, B<NumLock>, B<Shift>, B<Meta>, B<Lock>, B<Mod1>, B<Mod2>, 1085abbreviated modifier names:
1063B<Mod3>, B<Mod4>, B<Mod5>, and the abbreviated B<I>, B<K>, B<C>, B<N>, 1086
1064B<S>, B<M>, B<A>, B<L>, B<1>, B<2>, B<3>, B<4>, B<5>. 1087=begin table
1088
1089 B<ISOLevel3> B<I>
1090 B<AppKeypad> B<K>
1091 B<Control> B<C>
1092 B<NumLock> B<N>
1093 B<Shift> B<S>
1094 B<Meta> B<M> I<or> B<A>
1095 B<Lock> B<L>
1096 B<Mod1> B<1>
1097 B<Mod2> B<2>
1098 B<Mod3> B<3>
1099 B<Mod4> B<4>
1100 B<Mod5> B<5>
1101
1102=end table
1065 1103
1066The B<NumLock>, B<Meta> and B<ISOLevel3> modifiers are usually aliased to 1104The B<NumLock>, B<Meta> and B<ISOLevel3> modifiers are usually aliased to
1067whatever modifier the NumLock key, Meta/Alt keys or ISO Level3 Shift/AltGr 1105whatever modifier the NumLock key, Meta/Alt keys or ISO Level3 Shift/AltGr
1068keys are being mapped. B<AppKeypad> is a synthetic modifier mapped to the 1106keys are being mapped. B<AppKeypad> is a synthetic modifier mapped to the
1069current application keymap mode state. 1107current application keymap mode state.
1085As with any resource value, the I<action> string may contain backslash 1123As with any resource value, the I<action> string may contain backslash
1086escape sequences (C<\n>: newline, C<\\>: backslash, C<\000>: octal 1124escape sequences (C<\n>: newline, C<\\>: backslash, C<\000>: octal
1087number), see RESOURCES in C<man 7 X> for further details. 1125number), see RESOURCES in C<man 7 X> for further details.
1088 1126
1089An action starts with an action prefix that selects a certain type 1127An action starts with an action prefix that selects a certain type
1090of action, followed by a colon. An action strings without colons is 1128of action, followed by a colon. An action string without colons is
1091interpreted as a literal string to pass to the tty (as if they were 1129interpreted as a literal string to pass to the tty (as if it was
1092prefixed with C<string:>). 1130prefixed with C<string:>).
1093 1131
1094The following action prefixes are known - extensions can provide 1132The following action prefixes are known - extensions can provide
1095additional prefixes: 1133additional prefixes:
1096 1134
1104string C<echo rm -rf /> followed by a newline: 1142string C<echo rm -rf /> followed by a newline:
1105 1143
1106 URxvt.keysym.Shift-Tab: string:echo rm -rf /\n 1144 URxvt.keysym.Shift-Tab: string:echo rm -rf /\n
1107 1145
1108This could in theory be used to completely redefine your keymap. 1146This could in theory be used to completely redefine your keymap.
1147
1148In addition, for actions of this type, you can define a range of
1149keysyms in one shot by loading the C<keysym-list> perl extension and
1150providing an I<action> with pattern B<list/PREFIX/MIDDLE/SUFFIX>, where
1151the delimiter `/' should be a character not used by the strings.
1152
1153Its usage can be demonstrated by an example:
1154
1155 URxvt.keysym.M-C-0x61: list|\033<|abc|>
1156
1157The above line is equivalent to the following three lines:
1158
1159 URxvt.keysym.Meta-Control-0x61: string:\033<a>
1160 URxvt.keysym.Meta-Control-0x62: string:\033<b>
1161 URxvt.keysym.Meta-Control-0x63: string:\033<c>
1109 1162
1110=item command:STRING 1163=item command:STRING
1111 1164
1112If I<action> takes the form of C<command:STRING>, the specified B<STRING> 1165If I<action> takes the form of C<command:STRING>, the specified B<STRING>
1113is interpreted and executed as @@RXVT_NAME@@'s control sequence (basically 1166is interpreted and executed as @@RXVT_NAME@@'s control sequence (basically
1149 1202
1150The first line defines a mapping for C<Insert> and I<any> combination 1203The first line defines a mapping for C<Insert> and I<any> combination
1151of modifiers. The second line re-establishes the default mapping for 1204of modifiers. The second line re-establishes the default mapping for
1152C<Shift-Insert>. 1205C<Shift-Insert>.
1153 1206
1207=item builtin-string:
1208
1209This action is mainly useful to restore string mappings for keys that
1210have predefined actions in @@RXVT_NAME@@. The exact semantics are a bit
1211difficult to explain - basically, this action will send the string to the
1212application that would be sent if @@RXVT_NAME@@ wouldn't have a built-in
1213action for it.
1214
1215An example might make it clearer: @@RXVT_NAME@@ normally pastes the
1216selection when you press C<Shift-Insert>. With the following bindings, it
1217would instead emit the (undocumented, but what applications running in the
1218terminal might expect) sequence C<ESC [ 2 $> instead:
1219
1220 URxvt.keysym.S-Insert: builtin-string:
1221 URxvt.keysym.C-S-Insert: builtin:
1222
1223The first line disables the paste functionality for that key
1224combination, and the second reinstates the default behaviour for
1225C<Control-Shift-Insert>, which would otherwise be overridden.
1226
1227Similarly, to let applications gain access to the C<C-M-c> (copy to
1228clipboard) and C<C-M-v> (paste clipboard) key combination, you can do
1229this:
1230
1231 URxvt.keysym.C-M-c: builtin-string:
1232 URxvt.keysym.C-M-v: builtin-string:
1233
1154=item EXTENSION:STRING 1234=item EXTENSION:STRING
1155 1235
1156An action of this form passes the B<STRING> to the @@RXVT_NAME@@perl(3) 1236An action of this form invokes the action B<STRING>, if any, provided
1157extension of the same name. The extension will be loaded automatically if 1237by the @@RXVT_NAME@@perl(3) extension B<EXTENSION>. The extension will
1158neccessary. 1238be loaded automatically if necessary.
1159 1239
1160Not all extensions define key actions, but popular extensions that do 1240Not all extensions define actions, but popular extensions that do
1161include the I<selection> and I<matcher> extensions (documented in their 1241include the I<selection> and I<matcher> extensions (documented in their
1162own manpages, @@RXVT_NAME@@-selection(1) and @@RXVT_NAME@@-matcher(1), 1242own manpages, @@RXVT_NAME@@-selection(1) and @@RXVT_NAME@@-matcher(1),
1163respectively). 1243respectively).
1164 1244
1165From the silly examples department, this will rot13-"encrypt" 1245From the silly examples department, this will rot13-"encrypt"
1166@@RXVT_NAME@@'s selection when Alt-Control-c is pressed on typical PC 1246@@RXVT_NAME@@'s selection when Alt-Control-c is pressed on typical PC
1167keyboards: 1247keyboards:
1168 1248
1169 URxvt.keysym.M-C-c: selection:rot13 1249 URxvt.keysym.M-C-c: selection:rot13
1170 1250
1171=item perl:STRING 1251=item perl:STRING *DEPRECATED*
1172 1252
1173This is a deprecated way of passing key mappings to perl extensions. It is 1253This is a deprecated way of invoking commands provided by perl
1174still supported, but should not be used anymore. 1254extensions. It is still supported, but should not be used anymore.
1175 1255
1176=back 1256=back
1177
1178In addition, you can define a range of keysyms in one shot by loading
1179the C<keysym-list> perl extension and providing a I<string> with pattern
1180B<list/PREFIX/MIDDLE/SUFFIX>, where the delimiter `/' should be a
1181character not used by the strings.
1182
1183Its usage can be demonstrated by an example:
1184
1185 URxvt.keysym.M-C-0x61: list|\033<|abc|>
1186
1187The above line is equivalent to the following three lines:
1188
1189 URxvt.keysym.Meta-Control-0x61: \033<a>
1190 URxvt.keysym.Meta-Control-0x62: \033<b>
1191 URxvt.keysym.Meta-Control-0x63: \033<c>
1192 1257
1193=item B<perl-ext-common>: I<string> 1258=item B<perl-ext-common>: I<string>
1194 1259
1195=item B<perl-ext>: I<string> 1260=item B<perl-ext>: I<string>
1196 1261
1198use in this terminal instance; option B<-pe>. 1263use in this terminal instance; option B<-pe>.
1199 1264
1200Extension names can be prefixed with a C<-> sign to prohibit using 1265Extension names can be prefixed with a C<-> sign to prohibit using
1201them. This can be useful to selectively disable some extensions loaded 1266them. This can be useful to selectively disable some extensions loaded
1202by default, or specified via the C<perl-ext-common> resource. For 1267by default, or specified via the C<perl-ext-common> resource. For
1203example, C<default,-selection> will use all the default extension except 1268example, C<default,-selection> will use all the default extensions except
1204C<selection>. 1269C<selection>.
1205 1270
1206Extension names can also be followed by an argument in angle brackets 1271The default set includes the C<selection>, C<option-popup>,
1207(e.g. C<< searchable-scrollback<M-s> >>, which binds the hotkey for 1272C<selection-popup>, C<readline> and C<searchable-scrollback>
1208searchable scrollback to Alt/Meta-s). Mentioning the same extension 1273extensions, and extensions which are mentioned in B<keysym> resources.
1209multiple times with different arguments will pass multiple arguments to 1274
1210the extension. 1275Any extension such that a corresponding resource is given on the
1276command line is automatically appended to B<perl-ext>.
1211 1277
1212Each extension is looked up in the library directories, loaded if 1278Each extension is looked up in the library directories, loaded if
1213necessary, and bound to the current terminal instance. 1279necessary, and bound to the current terminal instance. When the library
1280search path contains multiple extension files of the same name, then the
1281first one found will be used.
1214 1282
1215If both of these resources are the empty string, then the perl 1283If both of these resources are the empty string, then the perl interpreter
1216interpreter will not be initialized. The idea behind two options is that 1284will not be initialized. The rationale for having two options is that
1217B<perl-ext-common> will be used for extensions that should be available to 1285B<perl-ext-common> will be used for extensions that should be available to
1218all instances, while B<perl-ext> is used for specific instances. 1286all instances, while B<perl-ext> is used for specific instances.
1219 1287
1220=item B<perl-eval>: I<string> 1288=item B<perl-eval>: I<string>
1221 1289
1239=item B<< selection-autotransform.I<idx> >>: I<perl-transform> 1307=item B<< selection-autotransform.I<idx> >>: I<perl-transform>
1240 1308
1241Selection auto-transform patterns, see the @@RXVT_NAME@@perl(3) manpage 1309Selection auto-transform patterns, see the @@RXVT_NAME@@perl(3) manpage
1242for details. 1310for details.
1243 1311
1244=item B<searchable-scrollback:> I<keysym> 1312=item B<searchable-scrollback:> I<keysym> *DEPRECATED*
1245 1313
1246Sets the hotkey that starts the incremental scrollback buffer search 1314This resource is deprecated and will be removed. Use a B<keysym> resource
1247(default: C<M-s>). 1315instead, e.g.:
1316
1317 URxvt.keysym.M-s: searchable-scrollback:start
1248 1318
1249=item B<url-launcher>: I<string> 1319=item B<url-launcher>: I<string>
1250 1320
1251Specifies the program to be started with a URL argument. Used by the 1321Specifies the program to be started with a URL argument. Used by the
1252C<selection-popup> and C<matcher> perl extensions. 1322C<selection-popup> and C<matcher> perl extensions.
1265Turn on/off ISO 14755 (default enabled). 1335Turn on/off ISO 14755 (default enabled).
1266 1336
1267=item B<iso14755_52:> I<boolean> 1337=item B<iso14755_52:> I<boolean>
1268 1338
1269Turn on/off ISO 14755 5.2 mode (default enabled). 1339Turn on/off ISO 14755 5.2 mode (default enabled).
1270
1271=back
1272
1273=head1 BACKGROUND IMAGE OPTIONS AND RESOURCES
1274
1275=over 4
1276
1277=item B<-pixmap> I<file[;oplist]>
1278
1279=item B<backgroundPixmap:> I<file[;oplist]>
1280
1281Compile I<pixbuf>: Use the specified image file as the window's
1282background and also optionally specify a colon separated list of
1283operations to modify it. Note that you may need to quote the C<;>
1284character when using the command line option, as C<;> is usually a
1285metacharacter in shells. Supported operations are:
1286
1287=over 4
1288
1289=item B<WxH+X+Y>
1290
1291sets scale and position. B<"W" / "H"> specify the horizontal/vertical
1292scale (percent), and B<"X" / "Y"> locate the image centre (percent). A
1293scale of 0 disables scaling.
1294
1295=item B<op=tile>
1296
1297enables tiling
1298
1299=item B<op=keep-aspect>
1300
1301maintain the image aspect ratio when scaling
1302
1303=item B<op=root-align>
1304
1305use the position of the terminal window relative to the root window as
1306the image offset, simulating a root window background
1307
1308=back
1309
1310The default scale and position setting is C<100x100+50+50>.
1311Alternatively, a predefined set of templates can be used to achieve
1312the most common setups:
1313
1314=over 4
1315
1316=item B<style=tiled>
1317
1318the image is tiled with no scaling. Equivalent to 0x0+0+0:op=tile
1319
1320=item B<style=aspect-stretched>
1321
1322the image is scaled to fill the whole window maintaining the aspect
1323ratio and centered. Equivalent to 100x100+50+50:op=keep-aspect
1324
1325=item B<style=stretched>
1326
1327the image is scaled to fill the whole window. Equivalent to 100x100
1328
1329=item B<style=centered>
1330
1331the image is centered with no scaling. Equivalent to 0x0+50+50
1332
1333=item B<style=root-tiled>
1334
1335the image is tiled with no scaling and using 'root' positioning.
1336Equivalent to 0x0:op=tile:op=root-align
1337
1338=back
1339
1340If multiple templates are specified the last one wins. Note that a
1341template overrides all the scale, position and operations settings.
1342
1343If used in conjunction with pseudo-transparency, the specified pixmap
1344will be blended over the transparent background using alpha-blending.
1345
1346=item B<-tr>|B<+tr>
1347
1348=item B<transparent:> I<boolean>
1349
1350Turn on/off pseudo-transparency by using the root pixmap as background.
1351
1352B<-ip> (B<inheritPixmap>) is still accepted as an obsolete alias but
1353will be removed in future versions.
1354
1355=item B<-tint> I<colour>
1356
1357=item B<tintColor:> I<colour>
1358
1359Tint the transparent background with the given colour. Note that a
1360black tint yields a completely black image while a white tint yields
1361the image unchanged.
1362
1363=item B<-sh> I<number>
1364
1365=item B<shading:> I<number>
1366
1367Darken (0 .. 99) or lighten (101 .. 200) the transparent background.
1368A value of 100 means no shading.
1369
1370=item B<-blr> I<HxV>
1371
1372=item B<blurRadius:> I<HxV>
1373
1374Apply gaussian blur with the specified radius to the transparent
1375background. If a single number is specified, the vertical and
1376horizontal radii are considered to be the same. Setting one of the
1377radii to 1 and the other to a large number creates interesting effects
1378on some backgrounds. The maximum radius value is 128. An horizontal or
1379vertical radius of 0 disables blurring.
1380
1381=item B<path:> I<path>
1382
1383Specify the colon-delimited search path for finding background image files.
1384 1340
1385=back 1341=back
1386 1342
1387=head1 THE SCROLLBAR 1343=head1 THE SCROLLBAR
1388 1344
1540In addition to the default foreground and background colours, 1496In addition to the default foreground and background colours,
1541B<@@RXVT_NAME@@> can display up to 88/256 colours: 8 ANSI colours plus 1497B<@@RXVT_NAME@@> can display up to 88/256 colours: 8 ANSI colours plus
1542high-intensity (potentially bold/blink) versions of the same, and 72 (or 1498high-intensity (potentially bold/blink) versions of the same, and 72 (or
1543240 in 256 colour mode) colours arranged in an 4x4x4 (or 6x6x6) colour RGB 1499240 in 256 colour mode) colours arranged in an 4x4x4 (or 6x6x6) colour RGB
1544cube plus a 8 (24) colour greyscale ramp. 1500cube plus a 8 (24) colour greyscale ramp.
1501
1502B<@@RXVT_NAME@@> supports direct 24-bit fg/bg RGB colour escapes
1503C< ESC [ 38 ; 2 ; R ; G ; Bm > / C< ESC [ 48 ; 2; R ; G ; Bm >. However the
1504number of 24-bit colours that can be used is limited: an internal 7x7x5 (256
1505colour mode) or 6x6x4 (88 colour mode) colour cube is used to index into the
150624-bit colour space. When indexing collisions happen, the nearest old colour in
1507the cube will be adapted to the new 24-bit RGB colour. That means one cannot
1508use many similar 24-bit colours. It's typically not a problem in common
1509scenarios.
1545 1510
1546Here is a list of the ANSI colours with their names. 1511Here is a list of the ANSI colours with their names.
1547 1512
1548=begin table 1513=begin table
1549 1514

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines