--- rxvt-unicode/src/perl/selection-pastebin	2012/06/06 15:06:41	1.18
+++ rxvt-unicode/src/perl/selection-pastebin	2014/05/17 15:48:29	1.24
@@ -1,7 +1,47 @@
 #! perl
 
-#:META:X_RESOURCE:%.cmd:string:the command to run create a new pastebin
-#:META:X_RESOURCE:%.url:string:the url template for new pastebins
+#:META:RESOURCE:%.cmd:string:the command to run create a new pastebin
+#:META:RESOURCE:%.url:string:the url template for new pastebins
+
+=head1 NAME
+
+selection-pastebin - automatic pastebin upload
+
+=head1 DESCRIPTION
+
+This is a little rarely useful extension that uploads the selection as
+textfile to a remote site (or does other things). (The implementation is
+not currently secure for use in a multiuser environment as it writes to
+F</tmp> directly.).
+
+It listens to the C<selection-pastebin:remote-pastebin> keyboard command,
+i.e.
+
+   URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin
+
+Pressing this combination runs a command with C<%> replaced by the name of
+the textfile. This command can be set via a resource:
+
+   URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.
+
+And the default is likely not useful to anybody but the few people around
+here :)
+
+The name of the textfile is the hex encoded md5 sum of the selection, so
+the same content should lead to the same filename.
+
+After a successful upload the selection will be replaced by the text given
+in the C<selection-pastebin-url> resource (again, the % is the placeholder
+for the filename):
+
+   URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
+
+I<Note to xrdb users:> xrdb uses the C preprocessor, which might interpret
+the double C</> characters as comment start. Use C<\057\057> instead,
+which works regardless of whether xrdb is used to parse the resource file
+or not.
+
+=cut
 
 sub upload_paste {
    my ($self) = @_;
@@ -62,10 +102,10 @@
 sub on_start {
    my ($self) = @_;
 
-   $self->{pastebin_cmd} = $self->x_resource ("selection-pastebin.cmd")
+   $self->{pastebin_cmd} = $self->x_resource ("%.cmd")
                            || "rcp -p % ruth:/var/www/www.ta-sa.org/files/txt/";
 
-   $self->{pastebin_url} = $self->x_resource ("selection-pastebin.url")
+   $self->{pastebin_url} = $self->x_resource ("%.url")
                            || "http://www.ta-sa.org/files/txt/%";
 
    push @{ $self->{term}{selection_popup_hook} }, sub {
@@ -75,12 +115,11 @@
    ()
 }
 
-sub on_user_command {
-   my ($self, $cmd) = @_;
+sub on_action {
+   my ($self, $action) = @_;
 
-   if ($cmd eq "selection-pastebin:remote-pastebin") {
-      $self->upload_paste;
-   }
+   $action eq "remote-pastebin"
+      and $self->upload_paste;
 
    ()
 }