[librsvg] (#436): Explain reasons for deprecation of the width/height/em/ex properties in RsvgHandle

[Federico Mena Quintero <federico src gnome org>]

commit 3f164e3acea3fe22b4485a168c21dcaadce9c52c
Author: Federico Mena Quintero <federico gnome org>
Date:   Wed Jul 24 11:32:01 2019 -0500

    (#436): Explain reasons for deprecation of the width/height/em/ex properties in RsvgHandle
    
    Fixes https://gitlab.gnome.org/GNOME/librsvg/issues/436

 librsvg/rsvg-handle.c | 24 ++++++++++++++++++++----
 1 file changed, 20 insertions(+), 4 deletions(-)
---
diff --git a/librsvg/rsvg-handle.c b/librsvg/rsvg-handle.c
index db1032dc..36b789ea 100644
--- a/librsvg/rsvg-handle.c
+++ b/librsvg/rsvg-handle.c
@@ -240,7 +240,12 @@
  * Width, in pixels, of the rendered SVG after calling the size callback
  * as specified by rsvg_handle_set_size_callback().
  *
- * Deprecated: 2.46.  FIXME: point to deprecation documentation.
+ * Deprecated: 2.46.  For historical reasons, this property is of integer type,
+ * which cannot give the exact size of SVG images that are not pixel-aligned.
+ * Moreover, reading each of the size properties causes the size of the SVG to
+ * be recomputed, so reading both the <literal>width</literal> and
+ * <literal>height</literal> properties will cause two such computations.
+ * Please use rsvg_handle_get_intrinsic_dimensions() instead.
  */
 
 /**
@@ -249,7 +254,12 @@
  * Height, in pixels, of the rendered SVG after calling the size callback
  * as specified by rsvg_handle_set_size_callback().
  *
- * Deprecated: 2.46.  FIXME: point to deprecation documentation.
+ * Deprecated: 2.46.  For historical reasons, this property is of integer type,
+ * which cannot give the exact size of SVG images that are not pixel-aligned.
+ * Moreover, reading each of the size properties causes the size of the SVG to
+ * be recomputed, so reading both the <literal>width</literal> and
+ * <literal>height</literal> properties will cause two such computations.
+ * Please use rsvg_handle_get_intrinsic_dimensions() instead.
  */
 
 /**
@@ -258,7 +268,10 @@
  * Exact width, in pixels, of the rendered SVG before calling the size callback
  * as specified by rsvg_handle_set_size_callback().
  *
- * Deprecated: 2.46.  FIXME: point to deprecation documentation.
+ * Deprecated: 2.46.  Reading each of the size properties causes the size of the
+ * SVG to be recomputed, so reading both the <literal>em</literal> and
+ * <literal>ex</literal> properties will cause two such computations.  Please
+ * use rsvg_handle_get_intrinsic_dimensions() instead.
  */
 
 /**
@@ -267,7 +280,10 @@
  * Exact height, in pixels, of the rendered SVG before calling the size callback
  * as specified by rsvg_handle_set_size_callback().
  *
- * Deprecated: 2.46.  FIXME: point to deprecation documentation.
+ * Deprecated: 2.46.  Reading each of the size properties causes the size of the
+ * SVG to be recomputed, so reading both the <literal>em</literal> and
+ * <literal>ex</literal> properties will cause two such computations.  Please
+ * use rsvg_handle_get_intrinsic_dimensions() instead.
  */
 
 /**