--- rxvt-unicode/src/perl/background	2012/06/20 18:18:14	1.65
+++ rxvt-unicode/src/perl/background	2012/07/02 01:32:26	1.69
@@ -75,8 +75,9 @@
       }
    }
 
-This expression is evaluated once per hour. It will set F<sunday.png> as
-background on Sundays, and F<weekday.png> on all other days.
+This inner expression is evaluated once per hour (and whenever the
+temrinal window is resized). It sets F<sunday.png> as background on
+Sundays, and F<weekday.png> on all other days.
 
 Fortunately, we expect that most expressions will be much simpler, with
 little Perl knowledge needed.
@@ -119,10 +120,10 @@
 
    scale 0.5, 2, load "$HOME/mypic.png"
 
-IF you try out these expressions, you might suffer from sluggishness,
-because each time the terminal is resized, it again loads the PNG image
-and scales it. Scaling is usually fast, but loading the image can be quite
-time consuming. This is where C<keep> comes in handy:
+IF you try out these expressions, you might suffer from some sluggishness,
+because each time the terminal is resized, it loads the PNG image agin
+and scales it. Scaling is usually fast (and unavoidable), but loading the
+image can be quite time consuming. This is where C<keep> comes in handy:
 
    scale 0.5, 2, keep { load "$HOME/mypic.png" }
 
@@ -174,7 +175,7 @@
 
 An expression can be "sensitive" to various external events, such as
 scaling or moving the window, root background changes and timers. Simply
-using an expression (such as C<scale> without parameters) that depend on
+using an expression (such as C<scale> without parameters) that depends on
 certain changing values (called "variables"), or using those variables
 directly, will make an expression sensitive to these events - for example,
 using C<scale> or C<TW> will make the expression sensitive to the terminal
@@ -185,7 +186,7 @@
 
 C<keep> is most useful for expensive operations, such as C<blur>:
 
-   rootalign once { blur 20, root }
+   rootalign keep { blur 20, root }
 
 This makes a blurred copy of the root background once, and on subsequent
 calls, just root-aligns it. Since C<blur> is usually quite slow and
@@ -278,15 +279,11 @@
 
 =cut
 
-   sub load_uc($) {
-      $self->new_img_from_file ($path)
-   }
-
    sub load($) {
       my ($path) = @_;
 
       $_IMG_CACHE{$path} || do {
-         my $img = load_uc $path;
+         my $img = $self->new_img_from_file ($path);
          Scalar::Util::weaken ($_IMG_CACHE{$path} = $img);
          $img
       }
@@ -847,41 +844,40 @@
 
 =over 4
 
-=item once { ... }
+=item keep { ... }
 
-This function takes a code block as argument, that is, one or more
+This operator takes a code block as argument, that is, one or more
 statements enclosed by braces.
 
-The trick is that this code block is only evaluated once - future calls
-will simply return the original image (yes, it should only be used with
-images).
-
-This can be extremely useful to avoid redoing the same slow operations
-again and again- for example, if your background expression takes the root
-background, blurs it and then root-aligns it it would have to blur the
-root background on every window move or resize.
+The trick is that this code block is only evaluated when the outcome
+changes - on other calls the C<keep> simply returns the image it computed
+previously (yes, it should only be used with images). Or in other words,
+C<keep> I<caches> the result of the code block so it doesn't need to be
+computed again.
+
+This can be extremely useful to avoid redoing slow operations - for
+example, if your background expression takes the root background, blurs it
+and then root-aligns it it would have to blur the root background on every
+window move or resize.
+
+Another example is C<load>, which can be quite slow.
 
 In fact, urxvt itself encloses the whole expression in some kind of
-C<once> block so it only is reevaluated as required.
+C<keep> block so it only is reevaluated as required.
 
-Putting the blur into a C<once> block will make sure the blur is only done
-once:
+Putting the blur into a C<keep> block will make sure the blur is only done
+once, while the C<rootalign> is still done each time the window moves.
 
-   rootlign once { blur 10, root }
+   rootlign keep { blur 10, root }
 
 This leaves the question of how to force reevaluation of the block,
 in case the root background changes: If expression inside the block
 is sensitive to some event (root background changes, window geometry
 changes), then it will be reevaluated automatically as needed.
 
-=item once_again
-
-Resets all C<once> block as if they had never been called, i.e. on the
-next call they will be reevaluated again.
-
 =cut
 
-   sub once(&) {
+   sub keep(&) {
       my $id = $_[0]+0;
 
       local $frame = $self->{frame_cache}{$id} ||= [$frame];
@@ -909,9 +905,9 @@
          : $frame->[FR_CACHE][0]
    }
 
-   sub once_again() {
-      delete $self->{frame_cache};
-   }
+#   sub keep_clear() {
+#      delete $self->{frame_cache};
+#   }
 
 =back