If string takes the form perl:STRING, then the specified STRING +is passed to the on_keyboard_command perl handler. See the rxvtperl(3) +manpage. For example, the selection extension (activated via +rxvt -pe selection) listens for selection:rot13 events:

+  URxvt.keysym.M-C-c: perl:selection:rot13

Due the the large number of modifier combinations, a defined key mapping will match if at at least the specified identifiers are being set, and no other key mappings with those and more bits are being defined. That @@ -1437,7 +1447,7 @@ Perl code to be evaluated when all extensions have been registered. See the Colon-separated list of additional directories that hold extension scripts. When looking for extensions specified by the perl resource, rxvt will first look in these directories and then in -/opt/rxvt/lib/urxvt/perl-ext/. +/opt/rxvt/lib/urxvt/perl/.

See the rxvtperl(3) manpage.

--- a/doc/rxvt.1.man.in
+++ b/doc/rxvt.1.man.in
@@ -1043,6 +1043,15 @@ when Control-Meta-c is being pressed":
 \&  URxvt.keysym.M-C-c: command:\e033]701;zh_CN.GBK\e007
 .Ve
 .Sp
+If \fIstring\fR takes the form \f(CW\*(C`perl:STRING\*(C'\fR, then the specified \fB\s-1STRING\s0\fR
+is passed to the \f(CW\*(C`on_keyboard_command\*(C'\fR perl handler. See the @@RXVT_NAME@@\fIperl\fR\|(3)
+manpage. For example, the \fIselection\fR extension (activated via
+\&\f(CW\*(C`@@RXVT_NAME@@ \-pe selection\*(C'\fR) listens for \f(CW\*(C`selection:rot13\*(C'\fR events:
+.Sp
+.Vb 1
+\&  URxvt.keysym.M-C-c: perl:selection:rot13
+.Ve
+.Sp
 Due the the large number of modifier combinations, a defined key mapping
 will match if at \fIat least\fR the specified identifiers are being set, and
 no other key mappings with those and more bits are being defined. That
@@ -1088,15 +1097,15 @@ if necessary, and bound to the current terminal instance; option \fB\-pe\fR.
 .IP "\fBperl-eval\fR: \fIstring\fR" 4
 .IX Item "perl-eval: string"
 Perl code to be evaluated when all extensions have been registered. See the
-\&\fIrxvtperl\fR\|(3) manpage.
+@@RXVT_NAME@@\fIperl\fR\|(3) manpage.
 .IP "\fBperl-lib\fR: \fIpath\fR" 4
 .IX Item "perl-lib: path"
 Colon-separated list of additional directories that hold extension
 scripts. When looking for extensions specified by the \f(CW\*(C`perl\*(C'\fR resource,
 @@RXVT_NAME@@ will first look in these directories and then in
-\&\fI@@RXVT_LIBDIR@@/urxvt/perl\-ext/\fR.
+\&\fI@@RXVT_LIBDIR@@/urxvt/perl/\fR.
 .Sp
-See the \fIrxvtperl\fR\|(3) manpage.
+See the @@RXVT_NAME@@\fIperl\fR\|(3) manpage.
 .SH "THE SCROLLBAR"
 .IX Header "THE SCROLLBAR"
 Lines of text that scroll off the top of the \fB@@RXVT_NAME@@\fR window
diff --git a/doc/rxvt.1.pod b/doc/rxvt.1.pod

--- a/doc/rxvt.1.pod
+++ b/doc/rxvt.1.pod
@@ -1025,7 +1025,7 @@ when Control-Meta-c is being pressed":
   URxvt.keysym.M-C-c: command:\033]701;zh_CN.GBK\007

 If I takes the form C, then the specified B
-is passed to the C perl handler. See the rxvtperl(3)
+is passed to the C perl handler. See the @@RXVT_NAME@@perl(3)
 manpage. For example, the F extension (activated via
 C<@@RXVT_NAME@@ -pe selection>) listens for C events:

@@ -1072,7 +1072,7 @@ if necessary, and bound to the current terminal instance; option B<-pe>.
 =item B: I

 Perl code to be evaluated when all extensions have been registered. See the
-rxvtperl(3) manpage.
+@@RXVT_NAME@@perl(3) manpage.

 =item B: I

@@ -1081,7 +1081,7 @@ scripts. When looking for extensions specified by the C resource,
 @@RXVT_NAME@@ will first look in these directories and then in
 F<@@RXVT_LIBDIR@@/urxvt/perl/>.

-See the rxvtperl(3) manpage.
+See the @@RXVT_NAME@@perl(3) manpage.

 =back

diff --git a/doc/rxvt.1.txt b/doc/rxvt.1.txt

--- a/doc/rxvt.1.txt
+++ b/doc/rxvt.1.txt
@@ -887,6 +887,13 @@ RESOURCES (available also as long-options)

           URxvt.keysym.M-C-c: command:\033]701;zh_CN.GBK\007

+        If *string* takes the form "perl:STRING", then the specified STRING
+        is passed to the "on_keyboard_command" perl handler. See the
+        rxvtperl(3) manpage. For example, the selection extension (activated
+        via "rxvt -pe selection") listens for "selection:rot13" events:
+
+          URxvt.keysym.M-C-c: perl:selection:rot13
+
         Due the the large number of modifier combinations, a defined key
         mapping will match if at *at least* the specified identifiers are
         being set, and no other key mappings with those and more bits are
@@ -933,7 +940,7 @@ RESOURCES (available also as long-options)
         Colon-separated list of additional directories that hold extension
         scripts. When looking for extensions specified by the "perl"
         resource, rxvt will first look in these directories and then in
-        /opt/rxvt/lib/urxvt/perl-ext/.
+        /opt/rxvt/lib/urxvt/perl/.

         See the rxvtperl(3) manpage.

diff --git a/doc/rxvt.7.html b/doc/rxvt.7.html

--- a/doc/rxvt.7.html
+++ b/doc/rxvt.7.html
@@ -3019,9 +3019,9 @@ Add support to have the pointer disappear when typing or inactive.
 
--enable-perl (default: off)

 
 

-Enable an embedded perl interpreter. See the rxvtperl(3) manpage
-(doc/rxvtperl.txt) for more info on this feature, or the files in
-src/perl-ext/ for the extensions that are installed by default.
+Enable an embedded perl interpreter. See the rxvtperl(3)
+manpage (doc/rxvtperl.txt) for more info on this feature, or the files
+in src/perl-ext/ for the extensions that are installed by default.
 
 

 
--with-name=NAME (default: urxvt)

diff --git a/doc/rxvt.7.man.in b/doc/rxvt.7.man.in

--- a/doc/rxvt.7.man.in
+++ b/doc/rxvt.7.man.in
@@ -2537,9 +2537,9 @@ the screen in a fixed position.
 Add support to have the pointer disappear when typing or inactive.
 .IP "\-\-enable\-perl (default: off)" 4
 .IX Item "--enable-perl (default: off)"
-Enable an embedded perl interpreter. See the \fB\f(BIrxvtperl\fB\|(3)\fR manpage
-(\fIdoc/rxvtperl.txt\fR) for more info on this feature, or the files in
-\&\fIsrc/perl\-ext/\fR for the extensions that are installed by default.
+Enable an embedded perl interpreter. See the \fB@@RXVT_NAME@@\f(BIperl\fB\|(3)\fR
+manpage (\fIdoc/rxvtperl.txt\fR) for more info on this feature, or the files
+in \fIsrc/perl\-ext/\fR for the extensions that are installed by default.
 .IP "\-\-with\-name=NAME (default: urxvt)" 4
 .IX Item "--with-name=NAME (default: urxvt)"
 Set the basename for the installed binaries, resulting
diff --git a/doc/rxvt.7.pod b/doc/rxvt.7.pod

--- a/doc/rxvt.7.pod
+++ b/doc/rxvt.7.pod
@@ -2568,9 +2568,9 @@ Add support to have the pointer disappear when typing or inactive.

 =item --enable-perl (default: off)

-Enable an embedded perl interpreter. See the B manpage
-(F) for more info on this feature, or the files in
-F for the extensions that are installed by default.
+Enable an embedded perl interpreter. See the B<@@RXVT_NAME@@perl(3)>
+manpage (F) for more info on this feature, or the files
+in F for the extensions that are installed by default.

 =item --with-name=NAME (default: urxvt)

diff --git a/doc/rxvtperl.3.html b/doc/rxvtperl.3.html

--- a/doc/rxvtperl.3.html
+++ b/doc/rxvtperl.3.html
@@ -44,22 +44,25 @@
 

 

 
SYNOPSIS
-
* Put your scripts into /opt/rxvt/lib/urxvt/perl-ext/, they will be loaded automatically.
-
* Scripts are evaluated in a 'use strict' and 'use utf8' environment, and
-thus must be encoded as UTF-8.
+
+   # create a file grab_test in $HOME:
 
    sub on_sel_grab {
       warn "you selected ", $_[0]->selection;
       ()
    }
 
-   1
+   # start a rxvt using it:

+   rxvt --perl-lib $HOME -pe grab_test

DESCRIPTION

Everytime a terminal object gets created, scripts specified via the -perl resource are associated with it.

Scripts are compiled in a 'use strict' and 'use utf8' environment, and +thus must be encoded as UTF-8.

Each script will only ever be loaded once, even in rxvtd, where scripts will be shared (But not enabled) for all terminals.

@@ -184,6 +187,14 @@ code is run after this hook, and takes precedence.