--- rxvt-unicode/src/urxvt.pm	2006/01/11 02:13:56	1.79
+++ rxvt-unicode/src/urxvt.pm	2006/01/12 05:37:34	1.87
@@ -42,9 +42,13 @@
 =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>.
+
+A double-click usually selects the word under the cursor, further clicks
+will enlarge the selection.
 
 It also offers the following bindable keyboard command:
 
@@ -72,13 +76,17 @@
 =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.
-
-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.
+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.
+
+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
 
@@ -87,8 +95,9 @@
 =item mark-urls
 
 Uses per-line display filtering (C<on_line_update>) to underline urls and
-make them clickable. When clicked, the program specified in the resource
-C<urlLauncher> (default C<x-www-browser>) will be started.
+make them clickable. When middle-clicked, the program specified in the
+resource C<urlLauncher> (default C<x-www-browser>) will be started with
+the URL as first argument.
 
 =item block-graphics-to-ascii
 
@@ -232,7 +241,9 @@
 Called whenever the user tries to extend the selection (e.g. with a double
 click) and is either supposed to return false (normal operation), or
 should extend the selection itelf and return true to suppress the built-in
-processing.
+processing. This can happen multiple times, as long as the callback
+returns true, it will be called on every further click by the user and is
+supposed to enlarge the selection more and more, if possible.
 
 See the F<selection> example extension.
 
@@ -498,6 +509,7 @@
       urxvt::warn ($msg);
    };
 
+   # %ENV is the original startup environment
    delete $ENV{IFS};
    delete $ENV{CDPATH};
    delete $ENV{BASH_ENV};
@@ -596,6 +608,9 @@
             warn $@;
          }
       }
+
+      verbose 11, "$HOOKNAME[$htype] returning <$retval>"
+         if $verbosity >= 11;
    }
 
    if ($htype == 1) { # DESTROY
@@ -616,6 +631,18 @@
    $retval
 }
 
+sub exec_async(@) {
+   my $pid = fork;
+
+   return
+      if !defined $pid or $pid;
+
+   %ENV = %{ $TERM->env };
+
+   exec @_;
+   _exit 255;
+}
+
 # urxvt::term::extension
 
 package urxvt::term::extension;
@@ -899,10 +926,18 @@
 Return the current values of the selection mark, begin or end positions,
 and optionally set them to new values.
 
+=item $term->selection_make ($eventtime[, $rectangular])
+
+Tries to make a selection as set by C<selection_beg> and
+C<selection_end>. If C<$rectangular> is true (default: false), a
+rectangular selection will be made. This is the prefered function to make
+a selection.
+
 =item $success = $term->selection_grab ($eventtime)
 
-Try to request the primary selection from the server (for example, as set
-by the next method).
+Try to request the primary selection text from the server (for example, as
+set by the next method). No visual feedback will be given. This function
+is mostly useful from within C<on_sel_grab> hooks.
 
 =item $oldtext = $term->selection ([$newtext])
 
@@ -1005,15 +1040,15 @@
 =item $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
 
 XORs the rendition values in the given span with the provided value
-(default: C<RS_RVid>). Useful in refresh hooks to provide effects similar
-to the selection.
+(default: C<RS_RVid>), which I<MUST NOT> contain font styles. Useful in
+refresh hooks to provide effects similar to the selection.
 
 =item $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[, $rstyle2]])
 
 Similar to C<scr_xor_span>, but xors a rectangle instead. Trailing
 whitespace will additionally be xored with the C<$rstyle2>, which defaults
 to C<RS_RVid | RS_Uline>, which removes reverse video again and underlines
-it instead.
+it instead. Both styles I<MUST NOT> contain font styles.
 
 =item $term->scr_bell
 
@@ -1207,7 +1242,8 @@
 =item $offset = $line->offset_of ($row, $col)
 
 Returns the character offset of the given row|col pair within the logical
-line.
+line. Works for rows outside the line, too, and returns corresponding
+offsets outside the string.
 
 =item ($row, $col) = $line->coord_of ($offset)
 
@@ -1572,7 +1608,9 @@
 
 =item >= 3 - script loading and management
 
-=item >=10 - all events received
+=item >=10 - all called hooks
+
+=item >=11 - hook reutrn values
 
 =back