diff --git a/docs/reference/gdk-pixbuf/tmpl/gnome-canvas-pixbuf.sgml b/docs/reference/gdk-pixbuf/tmpl/gnome-canvas-pixbuf.sgml
index f225a0c2cf..9d8eb9627f 100644
--- a/docs/reference/gdk-pixbuf/tmpl/gnome-canvas-pixbuf.sgml
+++ b/docs/reference/gdk-pixbuf/tmpl/gnome-canvas-pixbuf.sgml
@@ -8,7 +8,7 @@ Canvas item to display #GdkPixbuf images.
This canvas item displays #GdkPixbuf images. It handles full
affine transformations in both GDK and antialiased modes, and also
- supports W3C's SVG-like scaling and
translation semantics for absolute pixel values.
@@ -19,6 +19,123 @@ Canvas item to display #GdkPixbuf images.
functions for this.
+
+ Custom Scaling and Translation
+
+
+ In addition to the normal affine transformations supported by
+ canvas items, the #GnomeCanvasPixbuf item supports independent
+ object arguments for scaling and translation. This is useful
+ for explicitly setting a size to which the pixbuf's image will
+ be scaled, and for specifying translation offsets that take
+ place in the item's local coordinate system.
+
+
+
+ By default, the pixbuf canvas item will attain the size in units
+ of the #GdkPixbuf it contains. If a #GnomeCanvasPixbuf is
+ configured to use a #GdkPixbuf that has a size of 300 by 200
+ pixels, then the pixbuf item will automatically obtain a size of
+ 300 by 200 units in the item's local coordinate system. If the
+ item is transformed with a scaling transformation of (0.5, 2.0),
+ then the final image size will be of 150 by 400 pixels.
+
+
+
+ To set custom width and height values, you must set the width_set or height_set
+ arguments to %TRUE, and then set the width or height arguments to
+ the desired values. The former two arguments control whether
+ the latter two are used when computing the final image's size;
+ they are both %FALSE by default so that the pixbuf item will
+ attain a size in units equal to the size in pixels of the
+ #GdkPixbuf that the item contains.
+
+
+
+ The custom translation values are analogously controlled by the
+ x_set, y_set, x, and y arguments. The former
+ two control whether the custom translation offsets are used and
+ they are %FALSE by default, and the latter two control the
+ offsets themselves. If a custom translation offset is not used,
+ it is taken to be 0.0 by default. Otherwise, the logical
+ upper-left vertex of the image will be translated by the
+ specified distance, aligned with the item's local coordinate
+ system.
+
+
+
+
+ Absolute Pixel Scaling and Translation
+
+
+ The Scalable Vector
+ Graphics specification (SVG) of the World Wide Web Consortium also
+ allows images to be translated and scaled by absolute pixel
+ values that are independent of an item's normal affine
+ transformation.
+
+
+
+ Normally, the pixbuf item's translation and scaling arguments
+ are interpreted in units, so they will be modified by the item's
+ affine transformation. The width_pixels,
+ height_pixels,
+ x_pixels, and
+ y_pixels
+ object arguments can be used to modify this behavior. If one of
+ these arguments is %TRUE, then the corresponding scaling or
+ translation value will not be affected lengthwise by the pixbuf
+ item's affine transformation.
+
+
+
+ For example, consider a pixbuf item whose size is (300, 200).
+ If the item is modified with a scaling transformation of (0.5,
+ 2.0) but the width_pixels is
+ set to %TRUE, then the item will appear to be (300, 400) pixels
+ in size. This means that in this case the item's affine
+ transformation only applies to the height value, while the
+ width value is kept in absolute pixels.
+
+
+
+ Likewise, consider a pixbuf item whose (x, y) arguments are set to
+ (30, 40)
+
+ This of course assumes that the x_set and y_set arguments
+ are set to %TRUE for the translation offsets to take effect.
+
+ . If the item is then modified by the same scaling
+ transformation of (0.5, 2.0) but the y_pixels argument
+ is set to %TRUE, then the image's upper-left corner will appear
+ to be at position (15, 40). In this case, the affine
+ transformation is applied only to the x offset, while the y
+ offset is kept in absolute pixels.
+
+
+
+ In short, these arguments control whether a particular dimension
+ of a pixbuf item is scaled or not in the normal way by the
+ item's affine transformation.
+
+
+
#GnomeCanvas, #GdkPixbuf
@@ -124,9 +241,9 @@ Canvas item to display #GdkPixbuf images.
Indicates the horizontal translation offset of the pixbuf item's
image. This argument will only be used if the x_set argument is
- %TRUE. This ‘horizontal’ offset will actually be
- modified by the item's affine transformation.
+ linkend="GnomeCanvasPixbuf--x-set">x_set argument is %TRUE.
+ This offset may not actually appear horizontal, since it will be
+ affected by the item's affine transformation.
diff --git a/gdk-pixbuf/ChangeLog b/gdk-pixbuf/ChangeLog
index a5e02530bb..2246a765bd 100644
--- a/gdk-pixbuf/ChangeLog
+++ b/gdk-pixbuf/ChangeLog
@@ -1,3 +1,8 @@
+1999-11-07 Federico Mena Quintero
+
+ * doc/tmpl/gnome-canvas-pixbuf.sgml: Finished detailed explanation
+ of the width, height, x, and y setting and pixels arguments.
+
1999-11-05 Federico Mena Quintero
* doc/gdk-pixbuf-sections.txt: Removed gdk-pixbuf-io, since it is