--- rxvt-unicode/src/perl/readline	2006/02/20 20:46:54	1.9
+++ rxvt-unicode/src/perl/readline	2012/09/04 22:41:12	1.13
@@ -1,5 +1,36 @@
 #! perl
 
+=head1 NAME
+
+readline - improve readline editing (enabled by default)
+
+=head1 DESCRIPTION
+
+A support package that tries to make editing with readline easier. At
+the moment, it reacts to clicking shift-left mouse button by trying to
+move the text cursor to this position. It does so by generating as many
+cursor-left or cursor-right keypresses as required (this only works
+for programs that correctly support wide characters).
+
+To avoid too many false positives, this is only done when:
+
+=over 4
+
+=item - the tty is in ICANON state.
+
+=item - the text cursor is visible.
+
+=item - the primary screen is currently being displayed.
+
+=item - the mouse is on the same (multi-row-) line as the text cursor.
+
+=back
+
+The normal selection mechanism isn't disabled, so quick successive clicks
+might interfere with selection creation in harmless ways.
+
+=cut
+
 use POSIX ();
 
 my $termios = new POSIX::Termios;
@@ -24,7 +55,7 @@
 
    my $mask = $self->ModLevel3Mask | $self->ModMetaMask
             | urxvt::ShiftMask | urxvt::ControlMask;
-   
+
    ($event->{state} & $mask) == urxvt::ShiftMask
       or return;
 
@@ -39,24 +70,23 @@
    my $cur = $line->offset_of ($row, $col);
    my $ofs = $line->offset_of ($event->{row}, $event->{col});
 
-   if ($ofs >= 0 && $ofs < $line->l) {
-      my $diff = $ofs - $cur;
-      my $move;
-
-      if ($diff < 0) {
-         ($ofs, $cur) = ($cur, $ofs);
-         $move = "\x1b[D";
-      } else {
-         $move = "\x1b[C";
-      }
-
-      my $skipped = substr $line->t, $cur, $ofs - $cur;
-      $skipped =~ s/\x{ffff}//g;
+   $ofs >= 0 && $ofs < $line->l
+      or return;
 
-      $self->tt_write ($move x length $skipped);
+   my $diff = $ofs - $cur;
+   my $move;
 
-      return 1;
+   if ($diff < 0) {
+      ($ofs, $cur) = ($cur, $ofs);
+      $move = "\x1b[D";
+   } else {
+      $move = "\x1b[C";
    }
 
-   ()
+   my $skipped = substr $line->t, $cur, $ofs - $cur;
+   $skipped =~ s/\x{ffff}//g;
+
+   $self->tt_write ($move x length $skipped);
+
+   1
 }