--- rxvt-unicode/src/urxvt.pm	2006/01/12 05:22:47	1.86
+++ rxvt-unicode/src/urxvt.pm	2006/01/12 12:15:10	1.90
@@ -42,11 +42,33 @@
 =item selection (enabled by default)
 
 (More) intelligent selection. This extension tries to be more intelligent
-when the user extends selections (double-click). Right now, it tries to
-select urls and complete shell-quoted arguments, which is very convenient,
-too, if your F<ls> supports C<--quoting-style=shell>.
+when the user extends selections (double-click and further clicks). Right
+now, it tries to select words, urls and complete shell-quoted
+arguments, which is very convenient, too, if your F<ls> supports
+C<--quoting-style=shell>.
 
-It also offers the following bindable keyboard command:
+A double-click usually selects the word under the cursor, further clicks
+will enlarge the selection.
+
+The selection works by trying to match a number of regexes and displaying
+them in increasing order of length. You can add your own regexes by
+specifying resources of the form:
+
+   URxvt.selection.pattern-0: perl-regex
+   URxvt.selection.pattern-1: perl-regex
+   ...
+
+The index number (0, 1...) must not have any holes, and each regex must
+contain at least one pair of capturing parentheses, which will be used for
+the match. For example, the followign adds a regex that matches everything
+between two vertical bars:
+
+   URxvt.selection.pattern-0: \\|([^|]+)\\|
+
+You can look at the source of the selection extension to see more
+interesting uses, such as parsing a line from beginning to end.
+
+This extension also offers the following bindable keyboard command:
 
 =over 4
 
@@ -72,23 +94,49 @@
 =item searchable-scrollback<hotkey> (enabled by default)
 
 Adds regex search functionality to the scrollback buffer, triggered
-by a hotkey (default: C<M-s>). When in search mode, normal terminal
-input/output is suspended.
+by a hotkey (default: C<M-s>). While in search mode, normal terminal
+input/output is suspended and a regex is displayed at the bottom of the
+screen.
 
-C</> starts an incremental regex search, C<n> searches further, C<p> or
-C<N> jump to the previous match, C<G> jumps to the bottom and clears the
-history, C<enter> leaves search mode at the current position and C<escape>
-returns to the original position.
+Inputting characters appends them to the regex and continues incremental
+search. C<BackSpace> removes a character from the regex, C<Up> and C<Down>
+search upwards/downwards in the scrollback buffer, C<End> jumps to the
+bottom. C<Escape> leaves search mode and returns to the point where search
+was started, while C<Enter> or C<Return> stay at the current position and
+additionally stores the first match in the current line into the primary
+selection.
 
-=item digital-clock
+=item selection-autotransform
 
-Displays a digital clock using the built-in overlay.
+This selection allows you to do automatic transforms on a selection
+whenever a selection is made.
+
+It works by specifying perl snippets (most useful is a single C<s///>
+operator) that modify C<$_> as resources:
+
+   URxvt.selection-autotransform.0: transform
+   URxvt.selection-autotransform.1: transform
+   ...
+
+For example, the following will transform selections of the form
+C<filename:number>, often seen in compiler messages, into C<vi +$filename
+$word>:
+
+   URxvt.selection-autotransform.0: s/^(\\S+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
+
+And this example matches the same,but replaces it with vi-commands you can
+paste directly into your (vi :) editor:
+
+   URxvt.selection-autotransform.0: s/^(S+):(d+):?$/\\x1b:e \\Q$1\\E\\x0d:$2\\x0d/
+
+Of course, this can be modified to suit your needs and your editor :)
 
 =item mark-urls
 
 Uses per-line display filtering (C<on_line_update>) to underline urls and
 make them clickable. When middle-clicked, the program specified in the
-resource C<urlLauncher> (default C<x-www-browser>) will be started.
+resource C<urlLauncher> (default C<x-www-browser>) will be started with
+the URL as first argument.
 
 =item block-graphics-to-ascii
 
@@ -96,6 +144,10 @@
 by replacing all line-drawing characters (U+2500 .. U+259F) by a
 similar-looking ascii character.
 
+=item digital-clock
+
+Displays a digital clock using the built-in overlay.
+
 =item example-refresh-hooks
 
 Displays a very simple digital clock in the upper right corner of the