--- rxvt-unicode/src/urxvt.pm	2014/10/10 14:38:02	1.241
+++ rxvt-unicode/src/urxvt.pm	2014/12/26 18:58:19	1.246
@@ -45,8 +45,15 @@
 
   URxvt.perl-ext-common: default,selection-autotransform
 
-Extensions that add command line parameters or resources on their own are
-loaded automatically when used.
+Extensions may add additional resources and C<actions>, i.e., methods
+which can be bound to a key and invoked by the user. An extension can
+define the resources it support and also default bindings for one or
+more actions it provides using so called META comments, described
+below. Similarly to builtin resources, extension resources can also be
+specified on the command line as long options (with C<.> replaced by
+C<->), in which case the corresponding extension is loaded
+automatically. For this to work the extension B<must> define META
+comments for its resources.
 
 =head1 API DOCUMENTATION
 
@@ -108,6 +115,29 @@
 Additional methods only supported for extension objects are described in
 the C<urxvt::extension> section below.
 
+=head2 META comments
+
+rxvt-unicode recognizes special comments in extensions that define
+different types of metadata:
+
+=over 4
+
+=item #:META:RESOURCE:name:type:desc
+
+The RESOURCE comment defines a resource used by the extension, where
+C<name> is the resource name, C<type> is the resource type, C<boolean>
+or C<string>, and C<desc> is the resource description.
+
+=item #:META:BINDING:sym:action
+
+The BINDING comment defines a default binding for an action provided
+by the extension, where C<sym> is the key combination that triggers
+the action, whose format is defined in the description of the
+B<keysym> resource in the urxvt(1) manpage, and C<action> is the name
+of the action method.
+
+=back
+
 =head2 Hooks
 
 The following subroutines can be declared in extension files, and will be
@@ -283,6 +313,14 @@
 
 Called just after the screen gets redrawn. See C<on_refresh_begin>.
 
+=item on_action $term, $string
+
+Called whenever an action is invoked for the corresponding extension
+(e.g. via a C<extension:string> builtin action bound to a key, see
+description of the B<keysym> resource in the urxvt(1) manpage). The
+event is simply the action string. Note that an action event is always
+associated to a single extension.
+
 =item on_user_command $term, $string *DEPRECATED*
 
 Called whenever a user-configured event is being activated (e.g. via
@@ -679,14 +717,14 @@
       }
 
       for (
-         grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2
+         (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2),
+         @{ delete $TERM->{perl_ext_3} }
       ) {
          if ($_ eq "default") {
 
             $ext_arg{$_} = []
                for
-                  qw(selection option-popup selection-popup readline),
-                  @{ delete $TERM->{perl_ext_3} },
+                  qw(selection option-popup selection-popup readline searchable-scrollback),
                   map $_->[0], values %{ $TERM->{meta}{binding} };
 
             for ($TERM->_keysym_resources) {
@@ -1275,15 +1313,15 @@
 same value as used by this instance of rxvt-unicode. Returns C<undef> if no
 resource with that pattern exists.
 
-Extensions that define extra resource or command line arguments also need
-to call this method to access their values.
+Extensions that define extra resources also need to call this method
+to access their values.
 
 If the method is called on an extension object (basically, from an
 extension), then the special prefix C<%.> will be replaced by the name of
 the extension and a dot, and the lone string C<%> will be replaced by the
 extension name itself. This makes it possible to code extensions so you
-can rename them and get a new set of commandline switches and resources
-without having to change the actual code.
+can rename them and get a new set of resources without having to change
+the actual code.
 
 This method should only be called during the C<on_start> hook, as there is
 only one resource database per display, and later invocations might return
@@ -1476,8 +1514,9 @@
 
 Write the given text string to the screen, as if output by the application
 running inside the terminal. It may not contain command sequences (escape
-codes), but is free to use line feeds, carriage returns and tabs. The
-string is a normal text string, not in locale-dependent encoding.
+codes - see C<cmd_parse> for that), but is free to use line feeds,
+carriage returns and tabs. The string is a normal text string, not in
+locale-dependent encoding.
 
 Normally its not a good idea to use this function, as programs might be
 confused by changes in cursor position or scrolling. Its useful inside a
@@ -1495,9 +1534,10 @@
 
 =item $term->tt_write ($octets)
 
-Write the octets given in C<$octets> to the tty (i.e. as program input). To
-pass characters instead of octets, you should convert your strings first
-to the locale-specific encoding using C<< $term->locale_encode >>.
+Write the octets given in C<$octets> to the tty (i.e. as user input
+to the program, see C<cmd_parse> for the opposite direction). To pass
+characters instead of octets, you should convert your strings first to the
+locale-specific encoding using C<< $term->locale_encode >>.
 
 =item $term->tt_write_user_input ($octets)