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

Comparing rxvt-unicode/doc/rxvt.1.pod (file contents):
Revision 1.220 by root, Fri Sep 21 23:31:43 2012 UTC vs.
Revision 1.230 by sf-exg, Mon Apr 28 16:00:34 2014 UTC

 =item B<-ss>|B<+ss>
 Turn on/off skip scrolling (allow multiple screens per refresh); resource B<skipScroll>.
-=item B<-tr>|B<+tr>
-Turn on/off pseudo-transparency by using the root pixmap as background; resource B<transparent>.
-B<-ip> is still accepted as an obsolete alias but will be removed in
-future versions.
 =item B<-fade> I<number>
 Fade the text by the given percentage when focus is lost. Small values
 fade a little only, 100 completely replaces all colours by the fade
 colour; resource B<fading>.
 =item B<-fadecolor> I<colour>
 Fade to this colour when fading is used (see B<-fade>). The default colour
 is opaque black. resource B<fadeColor>.
-=item B<-tint> I<colour>
-Tint the transparent background with the given colour;
-resource I<tintColor>.
-=item B<-sh> I<number>
-Darken (0 .. 99) or lighten (101 .. 200) the transparent background.
-A value of 100 means no shading; resource I<shading>.
-=item B<-blr> I<HxV>
-Apply Gaussian Blur with the specified radii to the transparent
-background. If a single number is specified, the vertical and
-horizontal radii are considered to be the same. Setting one of the
-radii to 1 and the other to a large number creates interesting effects
-on some backgrounds. The maximum radius value is 128. An horizontal or
-vertical radius of 0 disables blurring;
-resource I<blurRadius>.
 =item B<-icon> I<file>
 Compile I<pixbuf>: Use the specified image as application icon. This
 is used by many window managers, taskbars and pagers to represent the
 application window; resource I<iconFile>.
 Window background colour; resource B<background>.
 =item B<-fg> I<colour>
 Window foreground colour; resource B<foreground>.
-=item B<-pixmap> I<file[;oplist]>
-Compile I<pixbuf>: Specify image file for the background and also
-optionally specify a list of operations to modify it. Note you may need to
-add quotes to avoid special shell interpretation of the C<;> in the
-command-line; for more details see resource B<backgroundPixmap>.
 =item B<-cr> I<colour>
 The cursor colour; resource B<cursorColor>.
 B<False>: specify that everything is to be displayed, even
 if the refresh is too fast for the human eye to read anything (or the
 monitor to display anything); option B<+ss>.
-=item B<transparent:> I<boolean>
-Turn on/off pseudo-transparency by using the root pixmap as background.
-B<inheritPixmap> is still accepted as an obsolete alias but will be removed in
-future versions.
 =item B<fading:> I<number>
 Fade the text by the given percentage when focus is lost; option B<-fade>.
 =item B<fadeColor:> I<colour>
 Fade to this colour, when fading is used (see B<fading:>). The default
 colour is black; option B<-fadecolor>.
-=item B<tintColor:> I<colour>
-Tint the transparent background with the given colour. If the RENDER
-extension is not available only black, red, green, yellow, blue,
-magenta, cyan and white tints can be performed server-side. Note that
-a black tint yields a completely black image while a white tint yields
-the image unchanged; option B<-tint>.
-=item B<shading:> I<number>
-Darken (0 .. 99) or lighten (101 .. 200) the transparent background.
-A value of 100 means no shading; option B<-sh>.
-=item B<blurRadius:> I<number>
-Apply gaussian blur with the specified radius to the transparent
-background; option B<-blr>.
 =item B<iconFile:> I<file>
 Set the application icon pixmap; option B<-icon>.
 =item B<scrollColor:> I<colour>
 =item B<borderColor:> I<colour>
 The colour of the border around the text area and between the scrollbar
 and the text.
-=item B<backgroundPixmap:> I<file[;oplist]>
-Use the specified image file for the background and also
-optionally specify a colon separated list of operations to modify it.
-Supported operations are:
-=over 4
-=item B<WxH+X+Y>
-sets scale and position. B<"W" / "H"> specify the horizontal/vertical
-scale (percent), and B<"X" / "Y"> locate the image centre (percent). A
-scale of 0 disables scaling.
-=item B<op=tile>
-enables tiling
-=item B<op=keep-aspect>
-maintain the image aspect ratio when scaling
-=item B<op=root-align>
-use the position of the terminal window relative to the root window as
-the image offset, simulating a root window background
-=back
-The default scale and position setting is C<100x100+50+50>.
-Alternatively, a predefined set of templates can be used to achieve
-the most common setups:
-=over 4
-=item B<style=tiled>
-the image is tiled with no scaling. Equivalent to 0x0+0+0:op=tile
-=item B<style=aspect-stretched>
-the image is scaled to fill the whole window maintaining the aspect
-ratio and centered. Equivalent to 100x100+50+50:op=keep-aspect
-=item B<style=stretched>
-the image is scaled to fill the whole window. Equivalent to 100x100
-=item B<style=centered>
-the image is centered with no scaling. Equivalent to 0x0+50+50
-=item B<style=root-tiled>
-the image is tiled with no scaling and using 'root' positioning.
-Equivalent to 0x0:op=tile:op=root-align
-=back
-If multiple templates are specified the last one wins. Note that a
-template overrides all the scale, position and operations settings.
-If used in conjunction with B<-tr> option, the specified pixmap will be
-blended over the transparent background using alpha-blending.
-=item B<path:> I<path>
-Specify the colon-delimited search path for finding background image files.
 =item B<font:> I<fontlist>
 Select the fonts to be used. This is a comma separated list of font names
 that are checked in order when trying to find glyphs for characters. The
 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.
+An action starts with an action prefix that selects a certain type
+of action, followed by a colon. An action strings without colons is
+interpreted as a literal string to pass to the tty (as if they were
+prefixed with C<string:>).
+The following action prefixes are known - extensions can provide
+additional prefixes:
+=over 4
+=item string:STRING
+If the I<action> starts with C<string:> (or otherwise contains no colons),
+then the remaining C<STRING> will be passed to the program running in the
+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<action> takes the form of C<command:STRING>, the specified B<STRING>
+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@@.
+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
+The following example will map Control-Meta-1 and Control-Meta-2 to
+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
+  URxvt.keysym.M-C-2: command:\033]50;9x15bold\007
+Other things are possible, e.g. resizing (see @@RXVT_NAME@@(7) for more
+info):
+  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.
+For example if you overwrite the C<Insert> key you will disable
+@@RXVT_NAME@@'s C<Shift-Insert> mapping. To re-enable that, you can poke
+"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>.
+=item builtin-string:
+This action is mainly useful to restore string mappings for keys that
+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.
+An example might make it clearer: @@RXVT_NAME@@ normally pastes the
+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.S-Insert: builtin-string:
+   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
+neccessary.
+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
+This is a deprecated way of passing key mappings to perl extensions. It is
+still supported, but should not be used anymore.
+=back
-You can define a range of keysyms in one shot by
+In addition, you can define a range of keysyms in one shot by loading
-loading the C<keysym-list> perl extension and providing a I<string>
+the C<keysym-list> perl extension and providing a I<string> with pattern
-with pattern B<list/PREFIX/MIDDLE/SUFFIX>, where the delimiter `/'
+B<list/PREFIX/MIDDLE/SUFFIX>, where the delimiter `/' should be a
-should be a character not used by the strings.
+character not used by the strings.
 Its usage can be demonstrated by an example:
   URxvt.keysym.M-C-0x61:    list|\033<|abc|>
 The above line is equivalent to the following three lines:
   URxvt.keysym.Meta-Control-0x61:    \033<a>
   URxvt.keysym.Meta-Control-0x62:    \033<b>
   URxvt.keysym.Meta-Control-0x63:    \033<c>
-If I<string> takes the form of C<command:STRING>, the specified B<STRING>
-is interpreted and executed as @@RXVT_NAME@@'s control sequence. 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>
-is passed to the C<on_user_command> perl handler. See the @@RXVT_NAME@@perl(3)
-manpage. For example, the F<selection> extension (activated via
-C<@@RXVT_NAME@@ -pe selection>) listens for C<selection:rot13> events:
-  URxvt.keysym.M-C-c: perl:selection:rot13
-Due the the large number of modifier combinations, a defined key mapping
-will 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 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
-if you overwrite the C<Insert> key you will disable @@RXVT_NAME@@'s
-C<Shift-Insert> mapping. To re-enable that, you can poke "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
-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
-  URxvt.keysym.M-C-2: command:\033]50;9x15bold\007
-Other things are possible, e.g. resizing (see @@RXVT_NAME@@(7) for more
-info):
-  URxvt.keysym.M-C-3: command:\033[8;25;80t
-  URxvt.keysym.M-C-4: command:\033[8;48;110t
 =item B<perl-ext-common>: I<string>
 =item B<perl-ext>: I<string>
 =item B<searchable-scrollback:> I<keysym>
 Sets the hotkey that starts the incremental scrollback buffer search
 (default: C<M-s>).
-=item B<urlLauncher>: I<string>
+=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.
 =item B<transient-for>: I<windowid>
 Turn on/off ISO 14755 (default enabled).
 =item B<iso14755_52:> I<boolean>
 Turn on/off ISO 14755 5.2 mode (default enabled).
+=back
+=head1 BACKGROUND IMAGE OPTIONS AND RESOURCES
+=over 4
+=item B<-pixmap> I<file[;oplist]>
+=item B<backgroundPixmap:> I<file[;oplist]>
+Compile I<pixbuf>: Use the specified image file as the window's
+background and also optionally specify a colon separated list of
+operations to modify it. Note that you may need to quote the C<;>
+character when using the command line option, as C<;> is usually a
+metacharacter in shells. Supported operations are:
+=over 4
+=item B<WxH+X+Y>
+sets scale and position. B<"W" / "H"> specify the horizontal/vertical
+scale (percent), and B<"X" / "Y"> locate the image centre (percent). A
+scale of 0 disables scaling.
+=item B<op=tile>
+enables tiling
+=item B<op=keep-aspect>
+maintain the image aspect ratio when scaling
+=item B<op=root-align>
+use the position of the terminal window relative to the root window as
+the image offset, simulating a root window background
+=back
+The default scale and position setting is C<100x100+50+50>.
+Alternatively, a predefined set of templates can be used to achieve
+the most common setups:
+=over 4
+=item B<style=tiled>
+the image is tiled with no scaling. Equivalent to 0x0+0+0:op=tile
+=item B<style=aspect-stretched>
+the image is scaled to fill the whole window maintaining the aspect
+ratio and centered. Equivalent to 100x100+50+50:op=keep-aspect
+=item B<style=stretched>
+the image is scaled to fill the whole window. Equivalent to 100x100
+=item B<style=centered>
+the image is centered with no scaling. Equivalent to 0x0+50+50
+=item B<style=root-tiled>
+the image is tiled with no scaling and using 'root' positioning.
+Equivalent to 0x0:op=tile:op=root-align
+=back
+If multiple templates are specified the last one wins. Note that a
+template overrides all the scale, position and operations settings.
+If used in conjunction with pseudo-transparency, the specified pixmap
+will be blended over the transparent background using alpha-blending.
+=item B<-tr>|B<+tr>
+=item B<transparent:> I<boolean>
+Turn on/off pseudo-transparency by using the root pixmap as background.
+B<-ip> (B<inheritPixmap>) is still accepted as an obsolete alias but
+will be removed in future versions.
+=item B<-tint> I<colour>
+=item B<tintColor:> I<colour>
+Tint the transparent background with the given colour. Note that a
+black tint yields a completely black image while a white tint yields
+the image unchanged.
+=item B<-sh> I<number>
+=item B<shading:> I<number>
+Darken (0 .. 99) or lighten (101 .. 200) the transparent background.
+A value of 100 means no shading.
+=item B<-blr> I<HxV>
+=item B<blurRadius:> I<HxV>
+Apply gaussian blur with the specified radius to the transparent
+background. If a single number is specified, the vertical and
+horizontal radii are considered to be the same. Setting one of the
+radii to 1 and the other to a large number creates interesting effects
+on some backgrounds. The maximum radius value is 128. An horizontal or
+vertical radius of 0 disables blurring.
+=item B<path:> I<path>
+Specify the colon-delimited search path for finding background image files.
 =back
 =head1 THE SCROLLBAR
 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.
 =over 4
 =item Project Coordinator
-Marc A. Lehmann L<< <rxvt-unicode@schmorp.de> >>
+Marc A. Lehmann <rxvt-unicode@schmorp.de>.
 L<http://software.schmorp.de/pkg/rxvt-unicode.html>
 =back
 =item John Bovey
 University of Kent, 1992, wrote the original Xvt.
-=item Rob Nation L<< <nation@rocket.sanders.lockheed.com> >>
+=item Rob Nation <nation@rocket.sanders.lockheed.com>
 very heavily modified Xvt and came up with Rxvt
-=item Angelo Haritsis L<< <ah@doc.ic.ac.uk> >>
+=item Angelo Haritsis <ah@doc.ic.ac.uk>
 wrote the Greek Keyboard Input (no longer in code)
-=item mj olesen L<< <olesen@me.QueensU.CA> >>
+=item mj olesen <olesen@me.QueensU.CA>
 Wrote the menu system.
 Project Coordinator (changes.txt 2.11 to 2.21)
-=item Oezguer Kesim L<< <kesim@math.fu-berlin.de> >>
+=item Oezguer Kesim <kesim@math.fu-berlin.de>
 Project Coordinator (changes.txt 2.21a to 2.4.5)
-=item Geoff Wing L<< <gcw@pobox.com> >>
+=item Geoff Wing <gcw@pobox.com>
 Rewrote screen display and text selection routines.
 Project Coordinator (changes.txt 2.4.6 - rxvt-unicode)
-=item Marc Alexander Lehmann L<< <rxvt-unicode@schmorp.de> >>
+=item Marc Alexander Lehmann <rxvt-unicode@schmorp.de>
 Forked rxvt-unicode, unicode support, rewrote almost all the code, perl
 extension, random hacks, numerous bugfixes and extensions.
 Project Coordinator (Changes 1.0 -)
-=item Emanuele Giaquinta L<< <e.giaquinta@glauco.it> >>
+=item Emanuele Giaquinta <emanuele.giaquinta@gmail.com>
 pty/utmp code rewrite, image code improvements, many random hacks and bugfixes.
 =back

Diff Legend

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

Comparing rxvt-unicode/doc/rxvt.1.pod (file contents): Revision 1.220 by root, Fri Sep 21 23:31:43 2012 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.220 by root, Fri Sep 21 23:31:43 2012 UTC vs.
Revision 1.230 by sf-exg, Mon Apr 28 16:00:34 2014 UTC