--- rxvt-unicode/src/urxvt.pm	2008/06/15 14:07:58	1.168
+++ rxvt-unicode/src/urxvt.pm	2009/05/30 08:47:07	1.174
@@ -110,7 +110,7 @@
 first argument.
 
 The following will add an entry C<myoption> that changes
-C<$self->{myoption}>:
+C<< $self->{myoption} >>:
 
    push @{ $self->{term}{option_popup_hook} }, sub {
       ("my option" => $myoption, sub { $self->{myoption} = $_[0] })
@@ -305,6 +305,12 @@
 If you want a quake-like animation, tell your window manager to do so
 (fvwm can do it).
 
+=item overlay-osc
+
+This extension implements some OSC commands to display timed popups on the
+screen - useful for status displays from within scripts. You have to read
+the sources for more info.
+
 =item block-graphics-to-ascii
 
 A not very useful example of filtering all text output to the terminal
@@ -369,6 +375,20 @@
 which works regardless of wether xrdb is used to parse the resource file
 or not.
 
+=item macosx-pastebin and macosx-pastebin-native
+
+These two modules implement an extended clipboard for Mac OS X. They are
+used like this:
+
+   URxvt.perl-ext-common: default,macosx-clipboard
+   URxvt.keysym.M-c: perl:macosx-clipboard:copy
+   URxvt.keysym.M-v: perl:macosx-clipboard:paste
+
+The difference between them is that the native variant requires a
+perl from apple's devkit or so, and C<maxosx-pastebin> requires the
+C<Mac::Pasteboard> module, works with other perls, has fewer bugs, is
+simpler etc. etc.
+
 =item example-refresh-hooks
 
 Displays a very simple digital clock in the upper right corner of the
@@ -543,29 +563,42 @@
 $nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
 number of lines that will be in the scrollback buffer.
 
-=item on_osc_seq $term, $op, $args
+=item on_osc_seq $term, $op, $args, $resp
 
 Called on every OSC sequence and can be used to suppress it or modify its
-behaviour.  The default should be to return an empty list. A true value
+behaviour. The default should be to return an empty list. A true value
 suppresses execution of the request completely. Make sure you don't get
-confused by recursive invocations when you output an osc sequence within
+confused by recursive invocations when you output an OSC sequence within
 this callback.
 
 C<on_osc_seq_perl> should be used for new behaviour.
 
-=item on_osc_seq_perl $term, $string
+=item on_osc_seq_perl $term, $args, $resp
 
 Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
 operating system command) is processed. Cursor position and other state
 information is up-to-date when this happens. For interoperability, the
-string should start with the extension name and a colon, to distinguish
-it from commands for other extensions, and this might be enforced in the
-future.
+string should start with the extension name (sans -osc) and a semicolon,
+to distinguish it from commands for other extensions, and this might be
+enforced in the future.
+
+For example, C<overlay-osc> uses this:
+
+   sub on_osc_seq_perl {
+      my ($self, $osc, $resp) = @_;
+
+      return unless $osc =~ s/^overlay;//;
+
+      ... process remaining $osc string
+   }
 
 Be careful not ever to trust (in a security sense) the data you receive,
 as its source can not easily be controlled (e-mail content, messages from
 other users on the same system etc.).
 
+For responses, C<$resp> contains the end-of-args separator used by the
+sender.
+
 =item on_add_lines $term, $string
 
 Called whenever text is about to be output, with the text as argument. You
@@ -595,8 +628,8 @@
 
 =item on_refresh_begin $term
 
-Called just before the screen gets redrawn. Can be used for overlay
-or similar effects by modify terminal contents in refresh_begin, and
+Called just before the screen gets redrawn. Can be used for overlay or
+similar effects by modifying the terminal contents in refresh_begin, and
 restoring them in refresh_end. The built-in overlay and selection display
 code is run after this hook, and takes precedence.
 
@@ -1282,7 +1315,7 @@
 sub resource($$;$) {
    my ($self, $name) = (shift, shift);
    unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
-   &urxvt::term::_resource
+   goto &urxvt::term::_resource
 }
 
 =item $value = $term->x_resource ($pattern)
@@ -1375,12 +1408,14 @@
 
 =over 4
 
-=item $overlay->set ($x, $y, $text, $rend)
+=item $overlay->set ($x, $y, $text[, $rend])
 
 Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts
 text in rxvt-unicode's special encoding and an array of rendition values
 at a specific position inside the overlay.
 
+If C<$rend> is missing, then the rendition will not be changed.
+
 =item $overlay->hide
 
 If visible, hide the overlay, but do not destroy it.