[librsvg] Document RsvgLength, RsvgUnit, rsvg_handle_get_intrinsic_dimensions()

[Federico Mena Quintero <federico src gnome org>]

commit 0174d64ec25dd5ae341a414d3f7a0e9ae6da201b
Author: Federico Mena Quintero <federico gnome org>
Date:   Wed Mar 27 18:30:24 2019 -0600

    Document RsvgLength, RsvgUnit, rsvg_handle_get_intrinsic_dimensions()

 doc/rsvg-sections.txt |  3 +++
 librsvg/rsvg-handle.c | 37 +++++++++++++++++++++++++++++++++++++
 librsvg/rsvg.h        | 51 +++++++++++++++++++++++++++++++++++++++++++--------
 3 files changed, 83 insertions(+), 8 deletions(-)
---
diff --git a/doc/rsvg-sections.txt b/doc/rsvg-sections.txt
index 36b0d0f1..53c7f304 100644
--- a/doc/rsvg-sections.txt
+++ b/doc/rsvg-sections.txt
@@ -7,6 +7,8 @@ rsvg_error_quark
 RsvgHandle
 RsvgHandleClass
 RsvgRectangle
+RsvgLength
+RsvgUnit
 RsvgDimensionData
 RsvgPositionData
 rsvg_cleanup
@@ -23,6 +25,7 @@ rsvg_handle_set_base_uri
 rsvg_handle_get_dimensions
 rsvg_handle_get_dimensions_sub
 rsvg_handle_get_position_sub
+rsvg_handle_get_intrinsic_dimensions
 rsvg_handle_get_geometry_for_element
 rsvg_handle_has_sub
 rsvg_handle_get_title
diff --git a/librsvg/rsvg-handle.c b/librsvg/rsvg-handle.c
index 371dc628..7469841c 100644
--- a/librsvg/rsvg-handle.c
+++ b/librsvg/rsvg-handle.c
@@ -1017,6 +1017,43 @@ rsvg_handle_set_size_callback (RsvgHandle *handle,
                                         user_data_destroy);
 }
 
+/**
+ * rsvg_handle_get_intrinsic_dimensions:
+ * @handle: An #RsvgHandle
+ * @out_has_width: (out)(optional) Will be set to #TRUE if the toplevel SVG has a <literal>width</literal> 
attribute
+ * @out_width: (out)(optional) Will be set to the value of the <literal>width</literal> attribute in the 
toplevel SVG
+ * @out_has_height: (out)(optional) Will be set to #TRUE if the toplevel SVG has a <literal>height</literal> 
attribute
+ * @out_height: (out)(optional) Will be set to the value of the <literal>height</literal> attribute in the 
toplevel SVG
+ * @out_has_viewbox: (out)(optional) Will be set to #TRUE if the toplevel SVG has a 
<literal>viewBox</literal> attribute
+ * @out_viewbox: (out)(optional) Will be set to the value of the <literal>viewBox</literal> attribute in the 
toplevel SVG
+ *
+ * Queries the <literal>width</literal>, <literal>height</literal>, and
+ * <literal>viewBox</literal> attributes in an SVG document.
+ *
+ * If you are calling this function to compute a scaling factor to render the SVG,
+ * consider simply using rsvg_handle_render_to_viewport() instead; it will do the
+ * scaling computations automatically.
+ *
+ * As an example, the following SVG element has a <literal>width</literal> of 100 pixels and a 
<literal>height</literal> of 400 pixels, but no <literal>viewBox</literal>:
+ *
+ * |[
+ * <svg xmlns="http://www.w3.org/2000/svg"; width="100" height="400">
+ * ]|
+ *
+ * Conversely, the following element has a <literal>viewBox</literal>, but no <literal>width</literal> or 
<literal>height</literal>:
+ *
+ * |[
+ * <svg xmlns="http://www.w3.org/2000/svg"; viewBox="0 0 100 400">
+ * ]|
+ *
+ * Note that the #RsvgLength return values have #RsvgUnits in them; you should
+ * not assume that they are always in pixels.  For example, the following SVG element
+ * will return a width value whose <literal>units</literal> field is RSVG_UNIT_MM.
+ *
+ * |[
+ * <svg xmlns="http://www.w3.org/2000/svg"; width="210mm" height="297mm">
+ * ]|
+ */
 void
 rsvg_handle_get_intrinsic_dimensions (RsvgHandle *handle,
                                       gboolean   *out_has_width,
diff --git a/librsvg/rsvg.h b/librsvg/rsvg.h
index 693d238d..63e31c8b 100644
--- a/librsvg/rsvg.h
+++ b/librsvg/rsvg.h
@@ -1,25 +1,25 @@
 /* -*- Mode: C; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
 /* vim: set sw=4 sts=4 expandtab: */
-/* 
+/*
    rsvg.h: SAX-based renderer for SVG files into a GdkPixbuf.
- 
+
    Copyright (C) 2000 Eazel, Inc.
-  
+
    This program is free software; you can redistribute it and/or
    modify it under the terms of the GNU Library General Public License as
    published by the Free Software Foundation; either version 2 of the
    License, or (at your option) any later version.
-  
+
    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Library General Public License for more details.
-  
+
    You should have received a copy of the GNU Library General Public
    License along with this program; if not, write to the
    Free Software Foundation, Inc., 59 Temple Place - Suite 330,
    Boston, MA 02111-1307, USA.
-  
+
    Author: Raph Levien <raph artofcode com>
 */
 
@@ -176,7 +176,7 @@ RsvgHandle  *rsvg_handle_new                (void);
 
 RSVG_DEPRECATED_FOR(rsvg_handle_read_stream_sync)
 gboolean     rsvg_handle_write         (RsvgHandle   *handle,
-                                         const guchar *buf, 
+                                         const guchar *buf,
                                          gsize         count,
                                          GError      **error);
 RSVG_DEPRECATED_FOR(rsvg_handle_read_stream_sync)
@@ -202,6 +202,22 @@ gboolean rsvg_handle_get_position_sub (RsvgHandle       *handle,
 
 gboolean rsvg_handle_has_sub (RsvgHandle *handle, const char *id);
 
+/**
+ * RsvgUnit:
+ * @RSVG_UNIT_PERCENT: percentage values; where <literal>1.0</literal> means 100%.
+ * @RSVG_UNIT_PX: pixels
+ * @RSVG_UNIT_EM: em, or the current font size
+ * @RSVG_UNIT_EX: x-height of the current font
+ * @RSVG_UNIT_IN: inches
+ * @RSVG_UNIT_CM: centimeters
+ * @RSVG_UNIT_MM: millimeters
+ * @RSVG_UNIT_PT: points, or 1/72 inch
+ * @RSVG_UNIT_PC: picas, or 1/6 inch (12 points)
+ *
+ * Units for the #RsvgLength struct.  These have the same meaning as <link
+ * href="https://www.w3.org/TR/CSS21/syndata.html#length-units";>CSS length
+ * units</link>.
+ */
 typedef enum {
     RSVG_UNIT_PERCENT,
     RSVG_UNIT_PX,
@@ -214,6 +230,25 @@ typedef enum {
     RSVG_UNIT_PC
 } RsvgUnit;
 
+/**
+ * RsvgLength:
+ * @length: numeric part of the length
+ * @unit: unit part of the length
+ *
+ * #RsvgLength values are used in rsvg_handle_get_intrinsic_dimensions(), for
+ * example, to return the CSS length values of the <literal>width</literal> and
+ * <literal>height</literal> attributes of an <literal>&lt;svg&gt;</literal>
+ * element.
+ *
+ * This is equivalent to <link
+ * href="https://www.w3.org/TR/CSS21/syndata.html#length-units";>CSS lengths</link>.
+ *
+ * It is up to the calling application to convert lengths in non-pixel units
+ * (i.e. those where the @unit field is not #RSVG_UNIT_PX) into something
+ * meaningful to the application.  For example, if your application knows the
+ * dots-per-inch (DPI) it is using, it can convert lengths with @unit in
+ * #RSVG_UNIT_IN or other physical units.
+ */
 typedef struct {
     double   length;
     RsvgUnit unit;
@@ -257,7 +292,7 @@ gboolean rsvg_handle_get_geometry_for_element (RsvgHandle     *handle,
  *  Cairo documentation</link> for details.
  *  Since: 2.40.3
  */
-typedef enum /*< flags >*/ 
+typedef enum /*< flags >*/
 {
     RSVG_HANDLE_FLAGS_NONE           = 0,
     RSVG_HANDLE_FLAG_UNLIMITED       = 1 << 0,