--- rxvt-unicode/src/perl/readline	2011/11/20 11:09:22	1.11
+++ rxvt-unicode/src/perl/readline	2012/06/10 17:31:53	1.12
@@ -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;