--- rxvt-unicode/src/urxvt.pm	2006/01/09 23:18:49	1.71
+++ rxvt-unicode/src/urxvt.pm	2006/01/10 19:46:28	1.76
@@ -28,9 +28,9 @@
 Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where
 scripts will be shared (but not enabled) for all terminals.
 
-=head2 Prepackaged Extensions
+=head1 PREPACKAGED EXTENSIONS
 
-This section describes the extensiosn delivered with this version. You can
+This section describes the extensions delivered with this release. You can
 find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>.
 
 You can activate them like this:
@@ -41,12 +41,12 @@
 
 =item selection (enabled by default)
 
-Intelligent selection. This extension tries to be more intelligent when
-the user extends selections (double-click). Right now, it tries to select
-urls and complete shell-quoted arguments, which is very convenient, too,
-if your F<ls> supports C<--quoting-style=shell>.
+(More) intelligent selection. This extension tries to be more intelligent
+when the user extends selections (double-click). Right now, it tries to
+select urls and complete shell-quoted arguments, which is very convenient,
+too, if your F<ls> supports C<--quoting-style=shell>.
 
-It also offers the following bindable event:
+It also offers the following bindable keyboard command:
 
 =over 4
 
@@ -66,15 +66,19 @@
 =item selection-popup (enabled by default)
 
 Binds a popup menu to Ctrl-Button3 that lets you convert the selection
-text into various other formats/action.
+text into various other formats/action (such as uri unescaping, perl
+evalution, web-browser starting etc.), depending on content.
 
-=item searchable-scrollback (enabled by default)
+=item searchable-scrollback<hotkey> (enabled by default)
 
-Adds regex search functionality to the scrollback buffer, triggered by a
-hotkey (default: C<M-s>). When in search mode, terminal input/output is
-suspended, C</> starts an incremental regex search, C<n> searches further,
-C<p> jumps to the previous match. C<enter> leaves search mode at the
-current position and C<escape> returns to the original position.
+Adds regex search functionality to the scrollback buffer, triggered
+by a hotkey (default: C<M-s>). When in search mode, normal terminal
+input/output is suspended.
+
+C</> starts an incremental regex search, C<n> searches further, C<p> or
+C<N> jump to the previous match, C<G> jumps to the bottom and clears the
+history, C<enter> leaves search mode at the current position and C<escape>
+returns to the original position.
 
 =item digital-clock
 
@@ -98,6 +102,8 @@
 
 =back
 
+=head1 API DOCUMENTATION
+
 =head2 General API Considerations
 
 All objects (such as terminals, time watchers etc.) are typical
@@ -265,6 +271,11 @@
 might be very slow, however, as your hook is called for B<all> text being
 output.
 
+=item on_tt_write $term, $octets
+
+Called whenever some data is written to the tty/pty and can be used to
+suppress or filter tty input.
+
 =item on_line_update $term, $row
 
 Called whenever a line was updated or changed. Can be used to filter
@@ -338,11 +349,26 @@
 
 =over 4
 
+=item $urxvt::LIBDIR
+
+The rxvt-unicode library directory, where, among other things, the perl
+modules and scripts are stored.
+
+=item $urxvt::RESCLASS, $urxvt::RESCLASS
+
+The resource class and name rxvt-unicode uses to look up X resources.
+
+=item $urxvt::RXVTNAME
+
+The basename of the installed binaries, usually C<urxvt>.
+
 =item $urxvt::TERM
 
 The current terminal. This variable stores the current C<urxvt::term>
 object, whenever a callback/hook is executing.
 
+=item
+
 =back
 
 =head2 Functions in the C<urxvt> Package
@@ -425,20 +451,20 @@
 
 Return the foreground/background colour index, respectively.
 
-=item $rend = urxvt::SET_FGCOLOR ($rend, $new_colour)
+=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
 
-=item $rend = urxvt::SET_BGCOLOR ($rend, $new_colour)
+=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
 
 Replace the foreground/background colour in the rendition mask with the
 specified one.
 
-=item $value = urxvt::GET_CUSTOM ($rend)
+=item $value = urxvt::GET_CUSTOM $rend
 
 Return the "custom" value: Every rendition has 5 bits for use by
 extensions. They can be set and changed as you like and are initially
 zero.
 
-=item $rend = urxvt::SET_CUSTOM ($rend, $new_value)
+=item $rend = urxvt::SET_CUSTOM $rend, $new_value
 
 Change the custom value.
 
@@ -459,7 +485,11 @@
 our @HOOKNAME;
 our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
 our %OPTION;
+
 our $LIBDIR;
+our $RESNAME;
+our $RESCLASS;
+our $RXVTNAME;
 
 BEGIN {
    urxvt->bootstrap;
@@ -665,9 +695,10 @@
 
 The sole purpose of this class is to deliver an interface to the
 C<AnyEvent> module - any module using it will work inside urxvt without
-further work. The only exception is that you cannot wait on condition
-variables, but non-blocking condvar use is ok. What this means is that you
-cannot use blocking APIs, but the non-blocking variant should work.
+further programming. The only exception is that you cannot wait on
+condition variables, but non-blocking condvar use is ok. What this means
+is that you cannot use blocking APIs, but the non-blocking variant should
+work.
 
 =cut
 
@@ -756,7 +787,9 @@
 
 =item $term->destroy
 
-Destroy the terminal object (close the window, free resources etc.).
+Destroy the terminal object (close the window, free resources
+etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event
+watchers (timers, io watchers) are still active.
 
 =item $isset = $term->option ($optval[, $set])
 
@@ -1280,6 +1313,28 @@
    push @{ $self->{item} }, $item;
 }
 
+=item $popup->add_title ($title)
+
+Adds a non-clickable title to the popup.
+
+=cut
+
+sub add_title {
+   my ($self, $title) = @_;
+
+   $self->add_item ({
+      rend => { normal => "\x1b[38;5;11;44m", hover => "\x1b[38;5;11;44m", active => "\x1b[38;5;11;44m" },
+      text => $title,
+      activate => sub { },
+   });
+}
+
+=item $popup->add_separator ([$sepchr])
+
+Creates a separator, optionally using the character given as C<$sepchr>.
+
+=cut
+
 sub add_separator {
    my ($self, $sep) = @_;
 
@@ -1293,15 +1348,12 @@
    });
 }
 
-sub add_title {
-   my ($self, $title) = @_;
+=item $popup->add_button ($text, $cb)
 
-   $self->add_item ({
-      rend => { normal => "\x1b[38;5;11;44m", hover => "\x1b[38;5;11;44m", active => "\x1b[38;5;11;44m" },
-      text => $title,
-      activate => sub { },
-   });
-}
+Adds a clickable button to the popup. C<$cb> is called whenever it is
+selected.
+
+=cut
 
 sub add_button {
    my ($self, $text, $cb) = @_;
@@ -1309,6 +1361,14 @@
    $self->add_item ({ type => "button", text => $text, activate => $cb});
 }
 
+=item $popup->add_toggle ($text, $cb, $initial_value)
+
+Adds a toggle/checkbox item to the popup. Teh callback gets called
+whenever it gets toggled, with a boolean indicating its value as its first
+argument.
+
+=cut
+
 sub add_toggle {
    my ($self, $text, $cb, $value) = @_;
 
@@ -1317,12 +1377,18 @@
       text => "  $text",
       value => $value,
       render => sub { ($_[0]{value} ? "* " : "  ") . $text },
-      activate => sub { $cb->($_[0]{value} = !$_[0]{value}); },
+      activate => sub { $cb->($_[1]{value} = !$_[1]{value}); },
    };
 
    $self->add_item ($item);
 }
 
+=item $popup->show
+
+Displays the popup (which is initially hidden).
+
+=cut
+
 sub show {
    my ($self) = @_;