--- rxvt-unicode/src/urxvt.pm	2006/01/22 20:39:47	1.125
+++ rxvt-unicode/src/urxvt.pm	2006/01/29 20:51:28	1.131
@@ -69,6 +69,13 @@
 
    URxvt.selection.pattern-0: \\|([^|]+)\\|
 
+Another example: Programs I use often output "absolute path: " at the
+beginning of a line when they process multiple files. The following
+pattern matches the filename (note, there is a single space at the very
+end):
+
+   URxvt.selection.pattern-0: ^(/[^:]+):\ 
+
 You can look at the source of the selection extension to see more
 interesting uses, such as parsing a line from beginning to end.
 
@@ -207,6 +214,18 @@
 resource C<urlLauncher> (default C<x-www-browser>) will be started with
 the URL as first argument.
 
+=item xim-onthespot
+
+This (experimental) perl extension implements OnTheSpot editing. It does
+not work perfectly, and some input methods don't seem to work well with
+OnTheSpot editing in general, but it seems to work at leats for SCIM and
+kinput2.
+
+You enable it by specifying this extension and a preedit style of
+C<OnTheSpot>, i.e.:
+
+   @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot
+
 =item automove-background
 
 This is basically a one-line extension that dynamically changes the background pixmap offset
@@ -225,11 +244,25 @@
 
 Displays a digital clock using the built-in overlay.
 
-=item example-refresh-hooks
+=item remote-clipboard
 
-Displays a very simple digital clock in the upper right corner of the
-window. Illustrates overwriting the refresh callbacks to create your own
-overlays or changes.
+Somewhat of a misnomer, this extension adds two menu entries to the
+selection popup that allows one ti run external commands to store the
+selection somewhere and fetch it again.
+
+We use it to implement a "distributed selection mechanism", which just
+means that one command uploads the file to a remote server, and another
+reads it.
+
+The commands can be set using the C<URxvt.remote-selection.store> and
+C<URxvt.remote-selection.fetch> resources. The first should read the
+selection to store from STDIN (always in UTF-8), the second should provide
+the selection data on STDOUT (also in UTF-8).
+
+The defaults (which are likely useless to you) use rsh and cat:
+
+   URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
+   URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
 
 =item selection-pastebin
 
@@ -260,6 +293,12 @@
 
    URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
 
+=item example-refresh-hooks
+
+Displays a very simple digital clock in the upper right corner of the
+window. Illustrates overwriting the refresh callbacks to create your own
+overlays or changes.
+
 =back
 
 =head1 API DOCUMENTATION
@@ -365,9 +404,8 @@
 
 =item on_destroy $term
 
-Called whenever something tries to destroy terminal, before doing anything
-yet. If this hook returns true, then destruction is skipped, but this is
-rarely a good idea.
+Called whenever something tries to destroy terminal, when the terminal is
+still fully functional (not for long, though).
 
 =item on_reset $term
 
@@ -479,12 +517,15 @@
 
 Called just after the screen gets redrawn. See C<on_refresh_begin>.
 
-=item on_keyboard_command $term, $string
+=item on_user_command $term, $string
 
-Called whenever the user presses a key combination that has a
-C<perl:string> action bound to it (see description of the B<keysym>
+Called whenever the a user-configured event is being activated (e.g. via
+a C<perl:string> action bound to a key, see description of the B<keysym>
 resource in the @@RXVT_NAME@@(1) manpage).
 
+The event is simply the action string. This interface is assumed to change
+slightly in the future.
+
 =item on_x_event $term, $event
 
 Called on every X event received on the vt window (and possibly other
@@ -628,6 +669,13 @@
 
 Messages have a size limit of 1023 bytes currently.
 
+=item @terms = urxvt::termlist
+
+Returns all urxvt::term objects that exist in this process, regardless of
+wether they are started, being destroyed etc., so be careful. Only term
+objects that have perl extensions attached will be returned (because there
+is no urxvt::term objet associated with others).
+
 =item $time = urxvt::NOW
 
 Returns the "current time" (as per the event loop).
@@ -1017,14 +1065,18 @@
 Croaks (and probably outputs an error message) if the new instance
 couldn't be created.  Returns C<undef> if the new instance didn't
 initialise perl, and the terminal object otherwise. The C<init> and
-C<start> hooks will be called during this call.
+C<start> hooks will be called before this call returns, and are free to
+refer to global data (which is race free).
 
 =cut
 
 sub new {
    my ($class, $env, @args) = @_;
 
-   _new ([ map "$_=$env->{$_}", keys %$env ], @args);
+   $env  or Carp::croak "environment hash missing in call to urxvt::term->new";
+   @args or Carp::croak "name argument missing in call to urxvt::term->new";
+
+   _new ([ map "$_=$env->{$_}", keys %$env ], \@args);
 }
 
 =item $term->destroy
@@ -1588,9 +1640,12 @@
 Converts rxvt-unicodes text reprsentation into a perl string. See
 C<< $term->ROW_t >> for details.
 
-=item $success = $term->grab_button ($button, $modifiermask)
+=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
+
+=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
 
-Registers a synchronous button grab. See the XGrabButton manpage.
+Register/unregister a synchronous button grab. See the XGrabButton
+manpage.
 
 =item $success = $term->grab ($eventtime[, $sync])