[librsvg] rsvg_handle_set_size_callback(): Document example code for how to use Cairo directly

[Federico Mena Quintero <federico src gnome org>]

commit 876bdf55044a585192830891c0b8c67f2c08aa91
Author: Federico Mena Quintero <federico gnome org>
Date:   Mon Apr 4 14:40:23 2016 -0500

    rsvg_handle_set_size_callback(): Document example code for how to use Cairo directly
    
    ... instead of using this deprecated function.

 rsvg-base.c |   25 +++++++++++++++++++++++++
 rsvg.h      |    1 +
 2 files changed, 26 insertions(+), 0 deletions(-)
---
diff --git a/rsvg-base.c b/rsvg-base.c
index cfddf4e..3367b23 100644
--- a/rsvg-base.c
+++ b/rsvg-base.c
@@ -1670,6 +1670,31 @@ rsvg_handle_set_dpi_x_y (RsvgHandle * handle, double dpi_x, double dpi_y)
  * arguments are set to -1.
  *
  * Deprecated: Set up a cairo matrix and use rsvg_handle_render_cairo() instead.
+ * You can call rsvg_handle_get_dimensions() to figure out the size of your SVG,
+ * and then scale it to the desired size via Cairo.  For example, the following
+ * code renders an SVG at a specified size, scaled proportionally from whatever
+ * original size it may have had:
+ *
+ * |[<!-- language="C" -->
+ * void
+ * render_scaled_proportionally (RsvgHandle *handle, cairo_t cr, int width, int height)
+ * {
+ *     RsvgDimensionData dimensions;
+ *     double x_factor, y_factor;
+ *     double scale_factor;
+ * 
+ *     rsvg_handle_get_dimensions (handle, &dimensions);
+ * 
+ *     x_factor = (double) width / dimensions.width;
+ *     y_factor = (double) height / dimensions.height;
+ * 
+ *     scale_factor = MIN (x_factor, y_factor);
+ * 
+ *     cairo_scale (cr, scale_factor, scale_factor);
+ * 
+ *     rsvg_handle_render_cairo (handle, cr);
+ * }
+ * ]|
  **/
 void
 rsvg_handle_set_size_callback (RsvgHandle * handle,
diff --git a/rsvg.h b/rsvg.h
index b8a6f8c..25b775a 100644
--- a/rsvg.h
+++ b/rsvg.h
@@ -215,6 +215,7 @@ void rsvg_handle_free (RsvgHandle * handle);
  * Function to let a user of the library specify the SVG's dimensions
  *
  * Deprecated: Set up a cairo matrix and use rsvg_handle_render_cairo() instead.
+ * See the documentation for rsvg_handle_set_size_callback() for an example.
  */
 typedef /* RSVG_DEPRECATED */ void (*RsvgSizeFunc) (gint * width, gint * height, gpointer user_data);