[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.235 by mikachu, Tue Jul 29 13:50:05 2014 UTC

 =item B<-override-redirect>
 Compile I<frills>: Sets override-redirect on the window; resource
 B<override-redirect>.
+=item B<-dockapp>
+Sets the initial state of the window to WithdrawnState, which makes
+window managers that support this extension treat it as a dockapp.
 =item B<-sbg>
 Compile I<frills>: Disable the usage of the built-in block graphics/line
 drawing characters and just rely on what the specified fonts provide. Use
 this if you have a good font and want to use its block graphic glyphs;
 Sets the working directory for the shell (or the command specified via
 B<-e>). The I<path> must be an absolute path and it must exist for
 @@RXVT_NAME@@ to start. If it isn't specified then the current working
 directory will be used; option B<-cd>.
-=item B<keysym.>I<sym>: I<string>
+=item B<keysym.>I<sym>: I<action>
-Compile I<frills>: Associate I<string> with keysym I<sym>. The
+Compile I<frills>: Associate I<action> with keysym I<sym>. The intervening
-intervening resource name B<keysym.> cannot be omitted.
+resource name B<keysym.> cannot be omitted.
-The format of I<sym> is "I<(modifiers-)key>", where I<modifiers> can be
+Using this resource, you can map key combinations such as
-any combination of B<ISOLevel3>, B<AppKeypad>, B<Control>, B<NumLock>,
+C<Ctrl-Shift-BackSpace> to various actions, such as outputting a different
-B<Shift>, B<Meta>, B<Lock>, B<Mod1>, B<Mod2>, B<Mod3>, B<Mod4>, B<Mod5>,
+string than would normally result from that combination, making the
-and the abbreviated B<I>, B<K>, B<C>, B<N>, B<S>, B<M>, B<A>, B<L>, B<1>,
+terminal scroll up or down the way you want it, or any other thing an
-B<2>, B<3>, B<4>, B<5>.
+extension might provide.
+The key combination that triggers the action, I<sym>, has the following format:
+   (modifiers-)key
+Where I<modifiers> can be any combination of B<ISOLevel3>, B<AppKeypad>,
+B<Control>, B<NumLock>, B<Shift>, B<Meta>, B<Lock>, B<Mod1>, B<Mod2>,
+B<Mod3>, B<Mod4>, B<Mod5>, and the abbreviated B<I>, B<K>, B<C>, B<N>,
+B<S>, B<M>, B<A>, B<L>, B<1>, B<2>, B<3>, B<4>, B<5>.
 The B<NumLock>, B<Meta> and B<ISOLevel3> modifiers are usually aliased to
 whatever modifier the NumLock key, Meta/Alt keys or ISO Level3 Shift/AltGr
 keys are being mapped. B<AppKeypad> is a synthetic modifier mapped to the
 current application keymap mode state.
-The spellings of I<key> can be obtained by using B<xev>(1) command or
+Due the the large number of modifier combinations, a key mapping will
-searching keysym macros from B</usr/X11R6/include/X11/keysymdef.h> and
+match if I<at least> the specified identifiers are being set, and no other
+key mappings with those and more bits are being defined. That means that
+defining a mapping for C<a> will automatically provide definitions for
+C<Meta-a>, C<Shift-a> and so on, unless some of those are defined mappings
+themselves. See the C<builtin:> action, below, for a way to work around
+this when this is a problem.
+The spelling of I<key> depends on your implementation of X. An easy way to
+find a key name is to use the B<xev>(1) command. You can find a list by
+looking for the C<XK_> macros in the B<X11/keysymdef.h> include file (omit
-omitting the prefix B<XK_>. Alternatively you can specify I<key> by its hex
+the C<XK_> prefix). Alternatively you can specify I<key> by its hex keysym
-keysym value (B<0x0000 - 0xFFFF>). Note that the lookup of I<sym>s is not
+value (B<0x0000 - 0xFFFF>).
-performed in an exact manner; however, the closest match is assured.
-I<string> may contain escape values (C<\n>: newline, C<\000>: octal
+As with any resource value, the I<action> string may contain backslash
+escape sequences (C<\n>: newline, C<\\>: backslash, C<\000>: octal
 number), see RESOURCES in C<man 7 X> for further details.
-You can define a range of keysyms in one shot by
+An action starts with an action prefix that selects a certain type
-loading the C<keysym-list> perl extension and providing a I<string>
+of action, followed by a colon. An action string without colons is
-with pattern B<list/PREFIX/MIDDLE/SUFFIX>, where the delimiter `/'
+interpreted as a literal string to pass to the tty (as if it was
-should be a character not used by the strings.
+prefixed with C<string:>).
-Its usage can be demonstrated by an example:
+The following action prefixes are known - extensions can provide
+additional prefixes:
-  URxvt.keysym.M-C-0x61:    list|\033<|abc|>
+=over 4
-The above line is equivalent to the following three lines:
+=item string:STRING
-  URxvt.keysym.Meta-Control-0x61:    \033<a>
+If the I<action> starts with C<string:> (or otherwise contains no colons),
-  URxvt.keysym.Meta-Control-0x62:    \033<b>
+then the remaining C<STRING> will be passed to the program running in the
-  URxvt.keysym.Meta-Control-0x63:    \033<c>
+terminal. For example, you could replace whatever Shift-Tab outputs by the
+string C<echo rm -rf /> followed by a newline:
+   URxvt.keysym.Shift-Tab: string:echo rm -rf /\n
+This could in theory be used to completely redefine your keymap.
+=item command:STRING
-If I<string> takes the form of C<command:STRING>, the specified B<STRING>
+If I<action> takes the form of C<command:STRING>, the specified B<STRING>
-is interpreted and executed as @@RXVT_NAME@@'s control sequence. For
+is interpreted and executed as @@RXVT_NAME@@'s control sequence (basically
+the opposite of C<string:> - instead of sending it to the program running
+in the terminal, it will be treated as if it were program output). This is
+most useful to feed command sequences into @@RXVT_NAME@@.
-example the following means "change the current locale to C<zh_CN.GBK>
+For example the following means "change the current locale to C<zh_CN.GBK>
 when Control-Meta-c is being pressed":
   URxvt.keysym.M-C-c: command:\033]701;zh_CN.GBK\007
-If I<string> takes the form C<perl:STRING>, then the specified B<STRING>
+The following example will map Control-Meta-1 and Control-Meta-2 to
-is passed to the C<on_user_command> perl handler. See the @@RXVT_NAME@@perl(3)
+the fonts C<suxuseuro> and C<9x15bold>, so you can have some limited
-manpage. For example, the F<selection> extension (activated via
+font-switching at runtime:
-C<@@RXVT_NAME@@ -pe selection>) listens for C<selection:rot13> events:
-  URxvt.keysym.M-C-c: perl:selection:rot13
+  URxvt.keysym.M-C-1: command:\033]50;suxuseuro\007
+  URxvt.keysym.M-C-2: command:\033]50;9x15bold\007
-Due the the large number of modifier combinations, a defined key mapping
+Other things are possible, e.g. resizing (see @@RXVT_NAME@@(7) for more
-will match if I<at least> the specified identifiers are being set, and
+info):
-no other key mappings with those and more bits are being defined. That
-means that defining a key map for C<a> will automatically provide
-definitions for C<Meta-a>, C<Shift-a> and so on, unless some of those are defined
-mappings themselves.
-Unfortunately, this will override built-in key mappings. For example
+  URxvt.keysym.M-C-3: command:\033[8;25;80t
+  URxvt.keysym.M-C-4: command:\033[8;48;110t
+=item builtin:
+The builtin action is the action that @@RXVT_NAME@@ would execute if no
+key binding existed for the key combination. The obvious use is to undo
+the effect of existing bindings. The not so obvious use is to reinstate
+bindings when another binding overrides too many modifiers.
-if you overwrite the C<Insert> key you will disable @@RXVT_NAME@@'s
+For example if you overwrite the C<Insert> key you will disable
-C<Shift-Insert> mapping. To re-enable that, you can poke "holes" into the
+@@RXVT_NAME@@'s C<Shift-Insert> mapping. To re-enable that, you can poke
-user-defined keymap using the C<builtin:> replacement:
+"holes" into the user-defined keymap using the C<builtin:> replacement:
   URxvt.keysym.Insert: <my insert key sequence>
   URxvt.keysym.S-Insert: builtin:
 The first line defines a mapping for C<Insert> and I<any> combination
 of modifiers. The second line re-establishes the default mapping for
 C<Shift-Insert>.
-The following example will map Control-Meta-1 and Control-Meta-2 to
+=item builtin-string:
-the fonts C<suxuseuro> and C<9x15bold>, so you can have some limited
-font-switching at runtime:
-  URxvt.keysym.M-C-1: command:\033]50;suxuseuro\007
+This action is mainly useful to restore string mappings for keys that
-  URxvt.keysym.M-C-2: command:\033]50;9x15bold\007
+have predefined actions in @@RXVT_NAME@@. The exact semantics are a bit
+difficult to explain - basically, this action will send the string to the
+application that would be sent if @@RXVT_NAME@@ wouldn't have a built-in
+action for it.
-Other things are possible, e.g. resizing (see @@RXVT_NAME@@(7) for more
+An example might make it clearer: @@RXVT_NAME@@ normally pastes the
-info):
+selection when you press C<Shift-Insert>. With the following bindings, it
+would instead emit the (undocumented, but what applications running in the
+terminal might expect) sequence C<ESC [ 2 $> instead:
-  URxvt.keysym.M-C-3: command:\033[8;25;80t
+   URxvt.keysym.S-Insert: builtin-string:
-  URxvt.keysym.M-C-4: command:\033[8;48;110t
+   URxvt.keysym.C-S-Insert: builtin:
+The first line disables the paste functionality for that key
+combination, and the second reinstates the default behaviour for
+C<Control-Shift-Insert>, which would otherwise be overridden.
+Similarly, to let applications gain access to the C<C-M-c> (copy to
+clipboard) and C<C-M-v> (paste clipboard) key combination, you can do
+this:
+   URxvt.keysym.C-S-c: builtin-string:
+   URxvt.keysym.C-S-v: builtin-string:
+=item EXTENSION:STRING
+An action of this form passes the B<STRING> to the @@RXVT_NAME@@perl(3)
+extension of the same name. The extension will be loaded automatically if
+necessary.
+Not all extensions define key actions, but popular extensions that do
+include the I<selection> and I<matcher> extensions (documented in their
+own manpages, @@RXVT_NAME@@-selection(1) and @@RXVT_NAME@@-matcher(1),
+respectively).
+From the silly examples department, this will rot13-"encrypt"
+@@RXVT_NAME@@'s selection when Alt-Control-c is pressed on typical PC
+keyboards:
+  URxvt.keysym.M-C-c: selection:rot13
+=item perl:STRING *DEPRECATED*
+This is a deprecated way of passing key mappings to perl extensions. It is
+still supported, but should not be used anymore.
+=back
 =item B<perl-ext-common>: I<string>
 =item B<perl-ext>: I<string>
 use in this terminal instance; option B<-pe>.
 Extension names can be prefixed with a C<-> sign to prohibit using
 them. This can be useful to selectively disable some extensions loaded
 by default, or specified via the C<perl-ext-common> resource. For
-example, C<default,-selection> will use all the default extension except
+example, C<default,-selection> will use all the default extensions except
 C<selection>.
-Extension names can also be followed by an argument in angle brackets
+The default set includes the C<selection>, C<option-popup>,
-(e.g.  C<< searchable-scrollback<M-s> >>, which binds the hotkey for
+C<selection-popup> and C<readline> extensions, any extensions that define
-searchable scrollback to Alt/Meta-s). Mentioning the same extension
+keybindings via C<BINDING> meta comments, extensions loaded because
-multiple times with different arguments will pass multiple arguments to
+their resources/commandline switches were used, and extensions which are
-the extension.
+mentioned in B<keysym> resources.
 Each extension is looked up in the library directories, loaded if
-necessary, and bound to the current terminal instance.
+necessary, and bound to the current terminal instance. When the library
+search path contains multiple extension files of the same name, then the
+first one found will be used.
-If both of these resources are the empty string, then the perl
+If both of these resources are the empty string, then the perl interpreter
-interpreter will not be initialized. The idea behind two options is that
+will not be initialized. The rationale for having two options is that
 B<perl-ext-common> will be used for extensions that should be available to
 all instances, while B<perl-ext> is used for specific instances.
 =item B<perl-eval>: I<string>
 =item B<< selection-autotransform.I<idx> >>: I<perl-transform>
 Selection auto-transform patterns, see the @@RXVT_NAME@@perl(3) manpage
 for details.
-=item B<searchable-scrollback:> I<keysym>
+=item B<searchable-scrollback:> I<keysym> *DEPRECATED*
-Sets the hotkey that starts the incremental scrollback buffer search
+This resource is deprecated and will be removed. Use a B<keysym> resource
-(default: C<M-s>).
+instead, e.g.:
+   URxvt.keysym.M-s: searchable-scrollback:start
 =item B<url-launcher>: I<string>
 Specifies the program to be started with a URL argument. Used by the
 C<selection-popup> and C<matcher> perl extensions.
 window causes the value of the PRIMARY selection (or CLIPBOARD with the
 B<Meta> modifier) to be inserted as if it had been typed on the keyboard.
 Pressing B<Shift-Insert> causes the value of the PRIMARY selection to be
 inserted too.
+rxvt-unicode also provides the bindings B<Ctrl-Meta-c> and
+<Ctrl-Meta-v> to interact with the CLIPBOARD selection. The first
+binding causes the value of the internal selection to be copied to the
+CLIPBOARD selection, while the second binding causes the value of the
+CLIPBOARD selection to be inserted.
 =back
 =head1 CHANGING FONTS
 The following text gives values for the standard 88 colour mode (and
 values for the 256 colour mode in parentheses).
 The RGB cube uses indices 16..79 (16..231) using the following formulas:
-   index_88  = (r *  4 + g) *  4 + b + 16   # r, g, b = 0..3
+   index_88  = (r * 4 + g) * 4 + b + 16   # r, g, b = 0..3
-   index_256 = (r * 16 + g) * 16 + b + 16   # r, g, b = 0..15
+   index_256 = (r * 6 + g) * 6 + b + 16   # r, g, b = 0..5
 The grayscale ramp uses indices 80..87 (232..239), from 10% to 90% in 10%
 steps (1/26 to 25/26 in 1/26 steps) - black and white are already part of
 the RGB cube.

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.235 by mikachu, Tue Jul 29 13:50:05 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.235 by mikachu, Tue Jul 29 13:50:05 2014 UTC