--- rxvt-unicode/src/perl/background	2012/07/14 08:42:54	1.74
+++ rxvt-unicode/src/perl/background	2013/01/19 10:04:34	1.82
@@ -6,7 +6,7 @@
 
 =head1 NAME
 
-   background - manage terminal background
+background - manage terminal background
 
 =head1 SYNOPSIS
 
@@ -14,6 +14,30 @@
          --background-border
          --background-interval seconds
 
+=head1 QUICK AND DIRTY CHEAT SHEET
+
+Just load a random jpeg image and tile the background with it without
+scaling or anything else:
+
+   load "/path/to/img.jpg"
+
+The same, but use mirroring/reflection instead of tiling:
+
+   mirror load "/path/to/img.jpg"
+
+Load an image and scale it to exactly fill the terminal window:
+
+   scale keep { load "/path/to/img.jpg" }
+
+Implement pseudo-transparency by using a suitably-aligned root pixmap
+as window background:
+
+   rootalign root
+
+Likewise, but keep a blurred copy:
+
+   rootalign keep { blur 10, root }
+
 =head1 DESCRIPTION
 
 This extension manages the terminal background by creating a picture that
@@ -400,6 +424,8 @@
       $base
    }
 
+=back
+
 =head2 TILING MODES
 
 The following operators modify the tiling mode of an image, that is, the
@@ -511,6 +537,8 @@
 
 =item TW
 
+=item TH
+
 Return the width (C<TW>) and height (C<TH>) of the terminal window (the
 terminal window is the full window by default, and the character area only
 when in border-respect mode).
@@ -587,7 +615,7 @@
 larger than the image, then the tiling mode defines how the extra pixels
 will be filled.
 
-If C<$x> an C<$y> are missing, then C<0> is assumed for both.
+If C<$x> and C<$y> are missing, then C<0> is assumed for both.
 
 If C<$width> and C<$height> are missing, then the window size will be
 assumed.
@@ -615,7 +643,7 @@
 Scales the image by the given factors in horizontal
 (C<$width>) and vertical (C<$height>) direction.
 
-If only one factor is give, it is used for both directions.
+If only one factor is given, it is used for both directions.
 
 If no factors are given, scales the image to the window size without
 keeping aspect.
@@ -750,7 +778,7 @@
 Rotates the image clockwise by C<$degrees> degrees, around the point at
 C<$center_x> and C<$center_y> (specified as factor of image width/height).
 
-Example: rotate the image by 90 degrees around it's center.
+Example: rotate the image by 90 degrees around its center.
 
    rotate 0.5, 0.5, 90, keep { load "$HOME/mybg.png" }
 
@@ -791,6 +819,16 @@
       $_[1]->tint ($_[0])
    }
 
+=item shade $factor, $img
+
+Shade the image by the given factor.
+
+=cut
+
+   sub shade($$) {
+      $_[1]->shade ($_[0])
+   }
+
 =item contrast $factor, $img
 
 =item contrast $r, $g, $b, $img
@@ -829,6 +867,8 @@
 Due to idiosyncrasies in the underlying XRender extension, biases less
 than zero can be I<very> slow.
 
+You can also try the experimental(!) C<muladd> operator.
+
 =cut
 
    sub contrast($$;$$;$) {
@@ -855,6 +895,26 @@
       $img
    }
 
+=item muladd $mul, $add, $img # EXPERIMENTAL
+
+First multiplies the pixels by C<$mul>, then adds C<$add>. This can be used
+to implement brightness and contrast at the same time, with a wider value
+range than contrast and brightness operators.
+
+Due to numerous bugs in XRender implementations, it can also introduce a
+number of visual artifacts.
+
+Example: increase contrast by a factor of C<$c> without changing image
+brightness too much.
+
+   muladd $c, (1 - $c) * 0.5, $img
+
+=cut
+
+   sub muladd($$$) {
+      $_[2]->muladd ($_[0], $_[1])
+   }
+
 =item blur $radius, $img
 
 =item blur $radius_horz, $radius_vert, $img