--- rxvt-unicode/src/perl/selection-popup	2012/06/06 15:06:41	1.25
+++ rxvt-unicode/src/perl/selection-popup	2014/05/23 20:51:15	1.30
@@ -1,6 +1,38 @@
 #! perl
 
-#:META:X_RESOURCE:url-launcher:string:shell command to use
+#:META:RESOURCE:url-launcher:string:shell command to use
+
+=head1 NAME
+
+selection-popup (enabled by default)
+
+=head1 DESCRIPTION
+
+Binds a popup menu to Ctrl-Button3 that lets you paste the X
+selections and either modify or use the internal selection text in
+various ways (such as uri unescaping, perl evaluation, web-browser
+starting etc.), depending on content.
+
+Other extensions can extend this popup menu by pushing a code reference
+onto C<< @{ $term->{selection_popup_hook} } >>, which gets called whenever
+the popup is being displayed.
+
+Its sole argument is the popup menu, which can be modified. The selection
+is in C<$_>, which can be used to decide whether to add something or not.
+It should either return nothing or a string and a code reference. The
+string will be used as button text and the code reference will be called
+when the button gets activated and should transform C<$_>.
+
+The following will add an entry C<a to b> that transforms all C<a>s in
+the selection to C<b>s, but only if the selection currently contains any
+C<a>s:
+
+   push @{ $self->{term}{selection_popup_hook} }, sub {
+      /a/ ? ("a to b" => sub { s/a/b/g }
+          : ()
+   };
+
+=cut
 
 sub msg {
    my ($self, $msg) = @_;
@@ -30,7 +62,7 @@
       my $popup = $self->popup ($event)
          or return 1;
 
-      $popup->add_title ("Convert Selection");
+      $popup->add_title ("Selection");
 
       my $text = $self->selection;
 
@@ -59,6 +91,16 @@
 
       for ($text) {
          /\n/
+            and $add_button->("paste primary selection" => sub { $self->selection_request (urxvt::CurrentTime, 1) });
+
+         /./
+            and $add_button->("paste clipboard selection" => sub { $self->selection_request (urxvt::CurrentTime, 3) });
+
+         /./
+            and $add_button->("copy selection to clipboard" => sub { $self->selection ($self->selection, 1);
+								     $self->selection_grab (urxvt::CurrentTime, 1) });
+
+         /./
             and $add_button->("newlines to spaces" => sub { y/\n/ / });
 
          /./