--- rxvt-unicode/src/urxvt.pm	2006/01/21 08:07:38	1.122
+++ rxvt-unicode/src/urxvt.pm	2006/01/25 15:11:31	1.129
@@ -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.
 
@@ -129,6 +136,31 @@
 additionally stores the first match in the current line into the primary
 selection.
 
+=item readline (enabled by default)
+
+A support package that tries to make editing with readline easier. At the
+moment, it reacts to clicking with the left mouse button by trying to
+move the text cursor to this position. It does so by generating as many
+cursor-left or cursor-right keypresses as required (the this only works
+for programs that correctly support wide characters).
+
+To avoid too many false positives, this is only done when:
+
+=over 4
+
+=item - the tty is in ICANON state.
+
+=item - the text cursor is visible.
+
+=item - the primary screen is currently being displayed.
+
+=item - the mouse is on the same (multi-row-) line as the text cursor.
+
+=back
+
+The normal selection mechanism isn't disabled, so quick successive clicks
+might interfere with selection creation in harmless ways.
+
 =item selection-autotransform
 
 This selection allows you to do automatic transforms on a selection
@@ -164,29 +196,6 @@
 every error message as a selection pattern, and the second line transforms
 the message into vi commands to load the file.
 
-=item readline
-
-A support package that tries to make editing with readline easier. At the
-moment, it reacts to clicking with the left mouse button by trying to
-move the text cursor to this position. It does so by generating as many
-cursor-left or cursor-right keypresses as required (the this only works
-for programs that correctly support wide characters).
-
-To avoid too many false positives, this is only done when:
-
-=over 4
-
-=item - the mouse is on the same (multi-row-) line as the text cursor.
-
-=item - the primary screen is currently being displayed.
-
-=item - the text cursor is visible.
-
-=back
-
-The normal selection mechanism isn't disabled, so quick successive clicks
-might interfere with selection creation in harmless ways.
-
 =item tabbed
 
 This transforms the terminal into a tabbar with additional terminals, that
@@ -205,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
@@ -223,11 +244,25 @@
 
 Displays a digital clock using the built-in overlay.
 
-=item example-refresh-hooks
+=item remote-selection
 
-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
 
@@ -258,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
@@ -363,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
 
@@ -563,7 +603,7 @@
 our $RESCLASS;
 our $RXVTNAME;
 
-our $NOCHAR = chr 0xfffe;
+our $NOCHAR = chr 0xffff;
 
 =head2 Variables in the C<urxvt> Package
 
@@ -720,6 +760,8 @@
    };
 }
 
+no warnings 'utf8';
+
 my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
 
 sub verbose {
@@ -745,7 +787,7 @@
          or die "$path: $!";
 
       my $source =
-         "package $pkg; use strict; use utf8;\n"
+         "package $pkg; use strict; use utf8; no warnings 'utf8';\n"
          . "#line 1 \"$path\"\n{\n"
          . (do { local $/; <$fh> })
          . "\n};\n1";
@@ -780,7 +822,7 @@
 
       for (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
          if ($_ eq "default") {
-            $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback);
+            $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback readline);
          } elsif (/^-(.*)$/) {
             delete $ext_arg{$1};
          } elsif (/^([^<]+)<(.*)>$/) {
@@ -1310,6 +1352,11 @@
 description of C<< urxvt::timer->events >>. Make sure to always restore
 the previous value.
 
+=item $fd = $term->pty_fd
+
+Returns the master file descriptor for the pty in use, or C<-1> if no pty
+is used.
+
 =item $windowid = $term->parent
 
 Return the window id of the toplevel window.
@@ -1418,8 +1465,8 @@
 to replace only parts of a line. The font index in the rendition will
 automatically be updated.
 
-C<$text> is in a special encoding: tabs and wide characters that use
-more than one cell when displayed are padded with C<$urxvt::NOCHAR>
+C<$text> is in a special encoding: tabs and wide characters that use more
+than one cell when displayed are padded with C<$urxvt::NOCHAR> (chr 65535)
 characters. Characters with combining characters and other characters that
 do not fit into the normal tetx encoding will be replaced with characters
 in the private use area.