--- rxvt-unicode/src/urxvt.pm	2006/01/02 20:35:39	1.8
+++ rxvt-unicode/src/urxvt.pm	2006/01/02 22:23:26	1.12
@@ -1,25 +1,27 @@
 =head1 NAME
 
-rxvtperl - rxvt-unicode's embedded perl interpreter
+@@RXVT_NAME@@perl - rxvt-unicode's embedded perl interpreter
 
 =head1 SYNOPSIS
 
-* Put your scripts into F<@@RXVT_LIBDIR@@/urxvt/perl-ext/>, they will be loaded automatically.
-
-* Scripts are evaluated in a 'use strict' and 'use utf8' environment, and
-thus must be encoded as UTF-8.
+   # create a file grab_test in $HOME:
 
    sub on_sel_grab {
       warn "you selected ", $_[0]->selection;
       ()
    }
 
-   1
+   # start a @@RXVT_NAME@@ using it:
+
+   @@RXVT_NAME@@ --perl-lib $HOME -pe grab_test
 
 =head1 DESCRIPTION
 
 Everytime a terminal object gets created, scripts specified via the
-C<perl> resource are associated with it.
+C<perl> resource are loaded and associated with it.
+
+Scripts are compiled in a 'use strict' and 'use utf8' environment, and
+thus must be encoded as UTF-8.
 
 Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where
 scripts will be shared (But not enabled) for all terminals.
@@ -124,6 +126,12 @@
 
 Called just after the screen gets redrawn. See C<on_refresh_begin>.
 
+=item on_keyboard_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>
+resource in the @@RXVT_NAME@@(1) manpage).
+
 =back
 
 =head2 Functions in the C<urxvt> Package
@@ -228,7 +236,7 @@
    my $htype = shift;
 
    if ($htype == 0) { # INIT
-      my @dirs = ((split /:/, $term->resource ("perl_lib")), $LIBDIR);
+      my @dirs = ((split /:/, $term->resource ("perl_lib")), "$LIBDIR/perl");
 
       for my $ext (split /:/, $term->resource ("perl_ext")) {
          my @files = grep -f $_, map "$_/$ext", @dirs;
@@ -384,8 +392,55 @@
 =item $term->tt_write ($octets)
 
 Write the octets given in C<$data> to the tty (i.e. as program input). To
-pass characters instead of octets, you should convetr you strings first to
-the locale-specific encoding using C<< $term->locale_encode >>.
+pass characters instead of octets, you should convert your strings first
+to the locale-specific encoding using C<< $term->locale_encode >>.
+
+=item $nsaved = $term->nsaved
+
+Returns the number of lines in the scrollback buffer.
+
+=item $view_start = $term->view_start ([$newvalue])
+
+Returns the negative row number of the topmost line. Minimum value is
+C<0>, which displays the normal terminal contents. Larger values scroll
+this many lines into the scrollback buffer.
+
+=item $text = $term->ROW_t ($row_number[, $new_text])
+
+Returns the text of the entire row with number C<$row_number>. Row C<0>
+is the topmost terminal line, row C<< $term->$ncol-1 >> is the bottommost
+terminal line. The scrollback buffer starts at line C<-1> and extends to
+line C<< -$term->nsaved >>.
+
+If C<$new_text> is specified, it will completely replace the current line.
+
+C<$text> is in a special encoding: tabs and wide characters that use more
+than one cell when displayed are padded with urxvt::NOCHAR characters
+(C<chr 65535>). 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.
+
+You have to obey this encoding when changing text. The advantage is
+that C<substr> and similar functions work on screen cells and not on
+characters.
+
+The methods C<< $term->special_encode >> and C<< $term->special_decode >>
+can be used to convert normal strings into this encoding and vice versa.
+
+=item $rend = $term->ROW_r ($row_number[, $new_rend])
+
+Like C<< $term->ROW_t >>
+
+=item $text = $term->special_encode $string
+
+Converts a perl string into the special encoding used by rxvt-unicode,
+where one character corresponds to one screen cell. See
+C<< $term->ROW_t >> for details.
+
+=item $string = $term->special_decode $text
+
+Converts rxvt-unicodes text reprsentation into a perl string. See
+C<< $term->ROW_t >> for details.
 
 =back